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.

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

Readmodel-registry.ts

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.

Readmodels.json

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.

Readmodel-registry.ts

ReadCHANGELOG.md

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:

ReadREADME.md50 lines

EditedREADME.md

Now update the changelog:

EditedCHANGELOG.md

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

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

Readmodel-registry.ts60 lines

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"

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