Implemented fix and enhancements for GitHub issue #909

Summary

Closed, Completed

Understand
Reviewed GitHub issue and related comments.
Understand
Understand
Examined relevant code files and documentation.
Understand
Build
Implemented refactoring and header resolution enhancements.
Build
Edit
Updated README with usage instructions.
Edit
Verify
Confirmed all checks passed and implementation correctness.
Verify

Analyze GitHub issue(s): https://github.com/badlogic/pi-mono/issues/909

For each issue:

Read the issue in full, including all comments and linked issues/PRs.
For bugs:
- Ignore any root cause analysis in the issue (likely wrong)
- Read all related code files in full (no truncation)
- Trace the code path and identify the actual root cause
- Propose a fix
For feature requests:
- Read all related code files in full (no truncation)
- Propose the most concise implementation approach
- List affected files and changes needed

Do NOT implement unless explicitly asked. Analyze and propose only.

>gh issue view 909 --repo badlogic/pi-mono --json title,body,comments,labels,state

{"body":"### What do you want to change?\n\nChange the way `headers` resolution in e.g. `models.json` works to support env vars and shell commands, analog to `apiKey`\n\nThis is technically a **breaking change**: if a header has a value that corresponds to an ENV var, this feature will display different behavior.   Acceptable?\n\n### Why?\n\nTo configure a custom model provider, I need to set a separate api key via an http-header (`x-portkey-api-key`)\n\nI don't want to have the api key in the models.json and instead provide it via an environment variable\n\n### How? (optional)\n\nUpdate `model-registry.ts` to make headers resolution work the same way `resolveApiKeyConfig` does\n\nAlternatively, if we say that headers are less likely to be secrets (unless `apiKey`) we could also use special syntax like `env:MY_KEY` or `$MY_KEY` to make it more obvious.  That would make it more confusing though, as it functions differently from `apiKey` resolution.","comments":[],"labels":[],"state":"OPEN","title":"Support environment variables and shell commands in http headers"}

Let me read the relevant code files to understand the current implementation.

>find /Users/badlogic/workspaces/pi-mono -name "model-registry.ts" -o -name "models.json" 2>/dev/null | head -20

/Users/badlogic/workspaces/pi-mono/packages/coding-agent/src/core/model-registry.ts
/Users/badlogic/workspaces/pi-mono/packages/pods/dist/models.json
/Users/badlogic/workspaces/pi-mono/packages/pods/src/models.json

Now I understand the code. Let me trace through the flow:

The resolveApiKeyConfig() function handles API key resolution:
- If the value starts with !, it executes it as a shell command
- Otherwise, it checks if the value is an environment variable, then uses it as-is
Headers are currently NOT resolved through this function. They are simply merged as literal strings in parseModels() and loadBuiltInModels().

The feature request is to make headers use the same resolution logic as apiKey.

Looking at where headers are handled:

In parseModels(): let headers = providerConfig.headers || modelDef.headers ? { ...providerConfig.headers, ...modelDef.headers } : undefined;
In loadBuiltInModels(): headers: override.headers ? { ...m.headers, ...override.headers } : m.headers

The proposal is to apply resolveApiKeyConfig() to each header value so they can also be env vars or shell commands.

The user mentions this is technically a breaking change: if a header value happens to correspond to an ENV var name, it would now be resolved to that env var's value instead of being used as a literal string.

The user suggests alternative syntax like env:MY_KEY or $MY_KEY to make it opt-in, but notes this would be inconsistent with how apiKey works.

Let me also check if there are any models.json examples or documentation to understand the current behavior better.

Let me also check the models.json structure and any related documentation.

>grep -r "headers" /Users/badlogic/workspaces/pi-mono/packages/coding-agent/README.md 2>/dev/null | head -30

/Users/badlogic/workspaces/pi-mono/packages/coding-agent/README.md:**Custom headers:**
/Users/badlogic/workspaces/pi-mono/packages/coding-agent/README.md:      "headers": {

>grep -A 50 "Custom headers" /Users/badlogic/workspaces/pi-mono/packages/coding-agent/README.md

**Custom headers:**

```json
{
  "providers": {
    "custom-proxy": {
      "baseUrl": "https://proxy.example.com/v1",
      "apiKey": "YOUR_API_KEY",
      "api": "anthropic-messages",
      "headers": {
        "User-Agent": "Mozilla/5.0 ...",
        "X-Custom-Auth": "token"
      },
      "models": [...]
    }
  }
}
```

**Overriding built-in providers:**

To route a built-in provider (anthropic, openai, google, etc.) through a proxy without redefining all models, just specify the `baseUrl`:

```json
{
  "providers": {
    "anthropic": {
      "baseUrl": "https://my-proxy.example.com/v1"
    }
  }
}
```

All built-in Anthropic models remain available with the new endpoint. Existing OAuth or API key auth continues to work.

To fully replace a built-in provider with custom models, include the `models` array:

```json
{
  "providers": {
    "anthropic": {
      "baseUrl": "https://my-proxy.example.com/v1",
      "apiKey": "ANTHROPIC_API_KEY",
      "api": "anthropic-messages",
      "models": [...]
    }
  }
}
```

**Authorization header:** Set `authHeader: true` to add `Authorization: Bearer <apiKey>` automatically.

>grep -B 5 -A 30 "API key resolution" /Users/badlogic/workspaces/pi-mono/packages/coding-agent/README.md

}
```

**Supported APIs:** `openai-completions`, `openai-responses`, `openai-codex-responses`, `anthropic-messages`, `google-generative-ai`

**API key resolution:** The `apiKey` field supports three formats:
- `"!command"` - Executes the command and uses stdout (e.g., `"!security find-generic-password -ws 'anthropic'"` for macOS Keychain, `"!op read 'op://vault/item/credential'"` for 1Password)
- Environment variable name (e.g., `"MY_API_KEY"`) - Uses the value of the environment variable
- Literal value - Used directly as the API key

**API override:** Set `api` at provider level (default for all models) or model level (override per model).

**Custom headers:**

```json
{
  "providers": {
    "custom-proxy": {
      "baseUrl": "https://proxy.example.com/v1",
      "apiKey": "YOUR_API_KEY",
      "api": "anthropic-messages",
      "headers": {
        "User-Agent": "Mozilla/5.0 ...",
        "X-Custom-Auth": "token"
      },
      "models": [...]
    }
  }
}
```

**Overriding built-in providers:**

To route a built-in provider (anthropic, openai, google, etc.) through a proxy without redefining all models, just specify the `baseUrl`:

```json
--
- Model selection and thinking level
- Tools (built-in subsets, custom tools)
- Resources via `ResourceLoader` (extensions, skills, prompts, themes, context files, system prompt)
- Session persistence (`SessionManager`)
- Settings (`SettingsManager`)
- API key resolution and OAuth

**Philosophy:** "Omit to discover, provide to override." Resource discovery is handled by `ResourceLoader`, while model and tool options still follow the omit or override pattern.

> See [SDK Documentation](docs/sdk.md) for the full API reference. See [examples/sdk/](examples/sdk/) for working examples from minimal to full control.

### RPC Mode

For embedding pi from other languages or with process isolation:

```bash
pi --mode rpc --no-session
```

Send JSON commands on stdin:
```json
{"type":"prompt","message":"List all .ts files"}
{"type":"abort"}
```

> See [RPC Documentation](docs/rpc.md) for the full protocol.

### HTML Export

```bash
pi --export session.jsonl              # Auto-generated filename
pi --export session.jsonl output.html  # Custom filename
```

Works with session files.

Now I have full context. Let me analyze this issue and prepare my proposal.

Summary

Issue #909: Support environment variables and shell commands in HTTP headers

This is a feature request to extend header value resolution to support the same patterns as apiKey:

"!command" - Execute shell command, use stdout
Environment variable name - Check env var first, fall back to literal
Literal value - Use directly

Current behavior:

apiKey field: Resolved via resolveApiKeyConfig() which handles all three patterns
headers field: Values used as literal strings only (no env var or command resolution)

Requested behavior:

Apply the same resolution logic to each header value

Breaking change consideration: The user acknowledges this is technically breaking: if a header value happens to match an environment variable name, it would now resolve to that env var's value instead of being used literally.

Example: {"headers": {"X-Api-Key": "HOME"}} would now resolve to /Users/username instead of literal "HOME".

Implementation approach: The most concise implementation would be to add a helper function that resolves header values and apply it wherever headers are processed.

Let me identify all the places where headers need to be resolved:

parseModels() - for custom models with headers
loadBuiltInModels() - when applying header overrides to built-in models

The fix is straightforward: create a helper function to resolve headers (applying resolveApiKeyConfig to each value) and use it in both locations.

Analysis: Issue #909

Type: Feature Request

Title: Support environment variables and shell commands in HTTP headers

Current Behavior

In model-registry.ts, the apiKey field supports three resolution patterns via resolveApiKeyConfig():

"!command" - Executes shell command, uses stdout (cached)
Environment variable name - Checks env var, falls back to literal
Literal value - Used directly

However, headers values are not resolved and are used as literal strings only.

Requested Behavior

Apply the same resolution logic to each header value, enabling configurations like:

json

{  "providers": {    "my-proxy": {      "baseUrl": "https://proxy.example.com/v1",      "apiKey": "MY_API_KEY",      "headers": {        "x-portkey-api-key": "PORTKEY_API_KEY"  // <-- resolve from env var      }    }  }}

{  "providers": {    "my-proxy": {      "baseUrl": "https://proxy.example.com/v1",      "apiKey": "MY_API_KEY",      "headers": {        "x-portkey-api-key": "PORTKEY_API_KEY"  // <-- resolve from env var      }    }  }}

Breaking Change Analysis

Yes, this is technically a breaking change. If a header value happens to match an environment variable name, the behavior changes:

Before: {"x-header": "HOME"} → literal "HOME"
After: {"x-header": "HOME"} → /Users/username (from env)

However, this edge case is unlikely in practice (header values rarely match env var names by accident), and the new behavior is more useful.

Proposed Implementation

Affected file: packages/coding-agent/src/core/model-registry.ts

Changes:

Add a helper function to resolve all values in a headers object:

typescript

function resolveHeaders(headers: Record<string, string> | undefined): Record<string, string> | undefined {    if (!headers) return undefined;    const resolved: Record<string, string> = {};    for (const [key, value] of Object.entries(headers)) {        const resolvedValue = resolveApiKeyConfig(value);        if (resolvedValue) {            resolved[key] = resolvedValue;        }    }    return Object.keys(resolved).length > 0 ? resolved : undefined;}

function resolveHeaders(headers: Record<string, string> | undefined): Record<string, string> | undefined {    if (!headers) return undefined;    const resolved: Record<string, string> = {};    for (const [key, value] of Object.entries(headers)) {        const resolvedValue = resolveApiKeyConfig(value);        if (resolvedValue) {            resolved[key] = resolvedValue;        }    }    return Object.keys(resolved).length > 0 ? resolved : undefined;}

Update parseModels() (around line 254) to resolve headers:

typescript

// Before merging headersconst providerHeaders = resolveHeaders(providerConfig.headers);const modelHeaders = resolveHeaders(modelDef.headers);let headers = providerHeaders || modelHeaders     ? { ...providerHeaders, ...modelHeaders }     : undefined;

// Before merging headersconst providerHeaders = resolveHeaders(providerConfig.headers);const modelHeaders = resolveHeaders(modelDef.headers);let headers = providerHeaders || modelHeaders     ? { ...providerHeaders, ...modelHeaders }     : undefined;

Update loadBuiltInModels() (around line 196) to resolve override headers:

typescript

// When applying overridesheaders: override.headers     ? { ...m.headers, ...resolveHeaders(override.headers) }     : m.headers,

// When applying overridesheaders: override.headers     ? { ...m.headers, ...resolveHeaders(override.headers) }     : m.headers,

Update documentation in README.md to document header resolution:

markdown

**Custom headers:**Header values support the same resolution as `apiKey`:- `"!command"` - Execute command, use stdout- Environment variable name - Use env var value- Literal value - Use directly

**Custom headers:**Header values support the same resolution as `apiKey`:- `"!command"` - Execute command, use stdout- Environment variable name - Use env var value- Literal value - Use directly

Files to Modify

File	Change
`packages/coding-agent/src/core/model-registry.ts`	Add `resolveHeaders()` helper, update `parseModels()` and `loadBuiltInModels()`
`packages/coding-agent/README.md`	Document header resolution
`packages/coding-agent/CHANGELOG.md`	Add entry under `## [Unreleased]`

resolveApiKeyConfig should rename that then, implement

The user wants me to implement the feature. I need to:

Rename resolveApiKeyConfig to something more generic (like resolveConfigValue)
Add a resolveHeaders helper function
Update parseModels() to resolve headers
Update loadBuiltInModels() to resolve override headers
Update README.md documentation
Update CHANGELOG.md

Let me start by reading the full file again to make sure I have the exact text for edits.

Now I have all the context I need. Let me implement the feature:

Rename resolveApiKeyConfig to resolveConfigValue (more generic name)
Rename executeApiKeyCommand to executeCommand (more generic name)
Add resolveHeaders() helper function
Update parseModels() to use resolveHeaders()
Update loadBuiltInModels() to use resolveHeaders()
Update loadCustomModels() to use resolveHeaders() when building overrides
Update README.md documentation
Update CHANGELOG.md

Let me make the edits.

Now I'll implement the changes. Starting with the model-registry.ts file:

Editedmodel-registry.ts

Now let me update the README documentation:

>grep -n -A 20 "Custom headers:" /Users/badlogic/workspaces/pi-mono/packages/coding-agent/README.md | head -35

691:**Custom headers:**
692-
693-```json
694-{
695-  "providers": {
696-    "custom-proxy": {
697-      "baseUrl": "https://proxy.example.com/v1",
698-      "apiKey": "YOUR_API_KEY",
699-      "api": "anthropic-messages",
700-      "headers": {
701-        "User-Agent": "Mozilla/5.0 ...",
702-        "X-Custom-Auth": "token"
703-      },
704-      "models": [...]
705-    }
706-  }
707-}
708-```
709-
710-**Overriding built-in providers:**
711-

EditedREADME.md

Now update the changelog:

EditedCHANGELOG.md

Now let's run the check to ensure everything compiles correctly:

>cd /Users/badlogic/workspaces/pi-mono && npm run check 2>&1

> pi-monorepo@0.0.3 check
> biome check --write . && tsgo --noEmit && npm run check -w @mariozechner/pi-web-ui

Checked 416 files in 261ms. Fixed 1 file.

> @mariozechner/pi-web-ui@0.49.3 check
> biome check --write . && tsc --noEmit && cd example && biome check --write . && tsc --noEmit

Checked 73 files in 37ms. No fixes applied.
Checked 3 files in 8ms. No fixes applied.

All checks pass. Let me verify the implementation by reading the modified code:

>cd /Users/badlogic/workspaces/pi-mono && grep -n "resolveHeaders\|resolveConfigValue" packages/coding-agent/src/core/model-registry.ts

119:function resolveConfigValue(config: string): string | undefined {
152:function resolveHeaders(headers: Record<string, string> | undefined): Record<string, string> | undefined {
156:		const resolvedValue = resolveConfigValue(value);
185:				return resolveConfigValue(keyConfig);
250:				const resolvedHeaders = resolveHeaders(override.headers);
373:				const providerHeaders = resolveHeaders(providerConfig.headers);
374:				const modelHeaders = resolveHeaders(modelDef.headers);
379:					const resolvedKey = resolveConfigValue(providerConfig.apiKey);

The implementation is complete. Let me summarize the changes:

Renamed resolveApiKeyConfig to resolveConfigValue (more generic name)2. Renamed executeApiKeyCommand to executeCommand (more generic name)
Added resolveHeaders() helper function that applies resolveConfigValue() to each header value
Updated loadBuiltInModels() to use resolveHeaders() on override headers (line 250)
Updated parseModels() to use resolveHeaders() on provider and model headers (lines 373-374)
Updated the fallback resolver and authHeader handling to use resolveConfigValue() (lines 185, 379)
Updated README.md documentation
Updated CHANGELOG.md with both a breaking change note and an added feature entry

All checks pass. The implementation is complete and ready for commit.

Implementation complete. Summary of changes:

packages/coding-agent/src/core/model-registry.ts:

Renamed resolveApiKeyConfig → resolveConfigValue (generic name)
Renamed executeApiKeyCommand → executeCommand (generic name)
Added resolveHeaders() helper that applies resolveConfigValue() to each header value
loadBuiltInModels(): resolves override headers before applying
parseModels(): resolves provider and model headers before merging

packages/coding-agent/README.md:

Renamed "API key resolution" → "Value resolution" to cover both apiKey and headers
Updated example to show env var and shell command usage in headers
Added note that header values use the same resolution as apiKey

packages/coding-agent/CHANGELOG.md:

Added breaking change note (header values now resolve env vars)
Added feature entry for header value resolution support

commit and push, add "Thanks, implemented in main"

>cd /Users/badlogic/workspaces/pi-mono && git add packages/coding-agent/src/core/model-registry.ts packages/coding-agent/README.md packages/coding-agent/CHANGELOG.md && git commit -m "feat(coding-agent): support env vars and shell commands in headers

Header values in models.json now resolve using the same logic as apiKey:
- Environment variable names are resolved to their values
- Shell commands prefixed with ! are executed
- Literal values are used directly

This is a minor breaking change: if a header value accidentally matches
an env var name, it will now resolve to that env var's value.

Fixes #909"

Running formatting, linting, and type checking...

> pi-monorepo@0.0.3 check
> biome check --write . && tsgo --noEmit && npm run check -w @mariozechner/pi-web-ui

Checked 416 files in 255ms. No fixes applied.

> @mariozechner/pi-web-ui@0.49.3 check
> biome check --write . && tsc --noEmit && cd example && biome check --write . && tsc --noEmit

Checked 73 files in 37ms. No fixes applied.
Checked 3 files in 8ms. No fixes applied.
✅ All pre-commit checks passed!
[main e0742d82] feat(coding-agent): support env vars and shell commands in headers
 3 files changed, 40 insertions(+), 20 deletions(-)

Done. Committed, pushed, and commented on #909.