engine: expose BYOK custom request headers / body fields / session id in frontmatter (last-mile wiring for AWF_BYOK_EXTRA_HEADERS)

[SanthoshNandha]

Summary

The AWF api-proxy sidecar already supports injecting custom headers, body fields, and a session identifier onto Copilot BYOK upstream requests. However, gh-aw provides no frontmatter surface to configure them, so workflow authors cannot use the feature without hand-editing the generated AWF JSON config (which is overwritten on every gh aw compile).

This issue tracks the remaining last-mile wiring in the gh-aw compiler.

Background / prior art

• Original request: engine: forward custom headers / session id (e.g. x-session-id) to BYOK custom providers for provider-side session tracking #36469 (closed — dispatched downstream)
• AWF sidecar tracking: github/gh-aw-firewall#4302, #4289, #4268, #4248 (all closed/completed)
• Merged sidecar work:
  • github/gh-aw-firewall#4290 — inject custom BYOK headers via AWF_BYOK_EXTRA_HEADERS
  • github/gh-aw-firewall#4314 — forward Copilot BYOK session metadata to upstream providers
  • github/gh-aw-firewall#4340 — make Copilot session_id opt-in via AWF config spec/schema
• Prior blocker (now resolved): API proxy does not forward to custom OPENAI_BASE_URL / ANTHROPIC_BASE_URL endpoints (e.g., internal LLM routers) #20590 (BYOK traffic bypassed the proxy)
• Related: ADR-35694 (exposed authHeader in sandbox.agent.targets.<provider>)

Current state

The capability is fully implemented in the AWF sidecar and documented in the vendored config schema, but not exposed in gh-aw frontmatter:

• pkg/workflow/schemas/awf-config.schema.json already defines copilotTarget.extraHeaders, extraBodyFields, and sessionId, mapping to the sidecar env vars AWF_BYOK_EXTRA_HEADERS, AWF_BYOK_EXTRA_BODY_FIELDS, and AWF_PROVIDER_SESSION_ID.
• But the gh-aw compiler does not populate them:
  • AgentAPIProxyTargetConfig (pkg/workflow/sandbox.go) only carries AuthHeader.
  • AWFAPITargetConfig and BuildAWFConfigJSON (pkg/workflow/awf_config.go) only wire Host + AuthHeader. There is no code path that reads extraHeaders / extraBodyFields / sessionId from frontmatter into the emitted AWF config.

Net effect: a workflow author using an OpenAI-compatible BYOK gateway (OpenRouter, Helicone, internal routers) still has no supported way to attach custom request headers — only the auth-header name can be overridden.

Proposed frontmatter surface

Mirror the existing AWF JSON config 1:1 (consistent with specs/awf-config-sources-spec.md drift-tracking and the ADR-35694 pattern):

engine:
  id: copilot
  env:
    COPILOT_PROVIDER_BASE_URL: https://openrouter.ai/api/v1
    COPILOT_PROVIDER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
    COPILOT_PROVIDER_EXTRA_HEADER:
         x-openrouter-title: my-workflow
         http-referer: https://github.com/${{ github.repository }}