fix: forward client x-initiator header to GitHub Copilot upstream

[cedrugs]

• feat: add optional clientHeaders field to ExecuteInput type
• feat: thread clientRawRequest.headers through all executor.execute() callsites in chatCore
• fix: GithubExecutor reads client x-initiator and forwards "agent" or "user" to Copilot
• chore: clean up _clientHeaders in finally block to prevent cross-request leakage

Summary

• OmniRoute currently hardcodes X-Initiator: "user" on every request to GitHub Copilot. This causes all tool-call continuation turns to be billed as premium requests, when GitHub Copilot's billing treats x-initiator: "agent" turns as free.
• This PR threads the client's original request headers through the executor pipeline and forwards the x-initiator value ("agent" or "user") to Copilot upstream, falling back to "user" when absent.
• For an agentic coding session triggering 10 tool calls on Claude Opus (3x multiplier), this reduces premium request consumption from ~30 per user message to ~3.

Related Issues

• Related to Reduce Premium Copilot requests BerriAI/litellm#12859 (Reduce Premium Copilot requests BerriAI/litellm#12859) - Same issue reported for litellm's Copilot proxy
• Related to fix: Copilot Premium Requests anomalyco/opencode#595 (fix: Copilot Premium Requests anomalyco/opencode#595) - OpenCode's native fix (merged Jul 2025) that this PR mirrors for OmniRoute
• Related to Reduce Premium Requests with Copilot Adapter olimorris/codecompanion.nvim#1738 (Reduce Premium Requests with Copilot Adapter olimorris/codecompanion.nvim#1738) - codecompanion.nvim's equivalent fix (merged Jun 2025)

Validation

• npm run lint
• npm run test:unit
• npm run test:coverage
• Coverage is still >= 60% for statements, lines, functions, and branches
• SonarQube PR analysis is green or any remaining issues are explicitly documented below

Tests Added Or Updated

• No new test files added. The change is a header-forwarding fix in the existing GithubExecutor pipeline. The existing 2719 unit tests all pass and cover the executor and chatCore paths exercised by this change.

Coverage Notes

• This PR changes open-sse/executors/base.ts, open-sse/executors/github.ts, and open-sse/handlers/chatCore.ts.
• github.ts changes are covered by existing GitHub executor unit tests (buildHeaders, execute flow, streaming transform). The _clientHeaders stash/cleanup pattern follows the same try/finally structure already tested in retry and fallback paths.
• chatCore.ts changes are additive (passing one extra field to executor.execute()), covered by existing chat handler integration tests.
• base.ts adds an optional field to a type — no runtime change, no coverage impact.
• No coverage regression expected.

Reviewer Notes

• Whitelist approach: Only "agent" and "user" are forwarded — any other value from the client is silently replaced with "user". This prevents clients from injecting unexpected initiator values.
• Stash pattern: _clientHeaders is set at the top of execute() and cleared in a finally block to prevent cross-request header leakage in case of errors or retries.
• No new dependencies added.
• Backward compatible: When clients don't send x-initiator (e.g., non-Copilot-aware clients), behaviour is identical to before — "user" is sent.
• Manual validation: Tested with OpenCode + OmniRoute against GitHub Copilot. Tool-call turns sent with x-initiator: "agent" are confirmed free in the Copilot usage dashboard.

[gemini-code-assist]

Code Review

This pull request implements the forwarding of the x-initiator header to GitHub Copilot to distinguish between user and agent-initiated requests, which helps in optimizing billing. The feedback identifies a critical concurrency issue where storing headers in a class property of a singleton executor leads to race conditions; it is recommended to pass these headers through the credentials object instead. Additionally, the reviewer noted that client headers should be converted from a Headers instance to a plain object to ensure consistent property access and avoid lookup failures.

[gemini-code-assist]

The use of a private class property _clientHeaders to stash request-specific data is not concurrency-safe because GithubExecutor is a singleton (instantiated once in executors/index.ts). Multiple concurrent requests will overwrite this value, leading to race conditions where one request's headers are used for another's buildHeaders call. Instead of stashing, consider threading the headers through the credentials.providerSpecificData object which is passed to buildHeaders.

[gemini-code-assist]

Refactor execute to avoid the race condition by passing clientHeaders through the credentials object. This removes the need for the class property and the try/finally block, making the implementation thread-safe.

    const result = await super.execute({
      ...input,
      credentials: {
        ...input.credentials,
        providerSpecificData: {
          ...(input.credentials.providerSpecificData || {}),
          _clientHeaders: input.clientHeaders,
        },
      },
    });
    if (!result || !result.response) return result;

    if (!input.stream) {
      // wreq-js clone/text semantics consume the original response body. Materialize
      // non-streaming responses immediately so downstream code always sees a native
      // fetch Response with a readable body.
      const status = result.response.status;
      const statusText = result.response.statusText;
      const headers = new Headers(result.response.headers);
      const payload = await result.response.text();
      result.response = new Response(payload, { status, statusText, headers });
      return result;
    }

    if (!result.response.body) return result;

    const isStreaming = input.stream === true;
    const contentType = (result.response.headers.get("content-type") || "").toLowerCase();
    if (isStreaming && result.response.ok && contentType.includes("text/event-stream")) {
      // Preserve the original response body for downstream error handling.
      const sourceResponse = result.response.clone();
      if (!sourceResponse.body) return result;

      const decoder = new TextDecoder();
      const transformStream = new TransformStream({
        transform(chunk, controller) {
          const text = decoder.decode(chunk, { stream: true });
          if (text.includes("data: [DONE]")) {
            return;
          }
          controller.enqueue(chunk);
        },
      });

      const newResponse = new Response(sourceResponse.body.pipeThrough(transformStream), {
        status: sourceResponse.status,
        statusText: sourceResponse.statusText,
        headers: new Headers(sourceResponse.headers),
      });
      result.response = newResponse;
    }

    return result;

[gemini-code-assist]

Update buildHeaders to read the client headers from the credentials object to ensure concurrency safety.

Suggested change

	const ch = this._clientHeaders;
	const clientInitiator = ch?.["x-initiator"] || ch?.["X-Initiator"];
	const initiator =
	clientInitiator === "agent" || clientInitiator === "user" ? clientInitiator : "user";
	const ch = (credentials.providerSpecificData as any)?._clientHeaders;
	const clientInitiator = ch?.["x-initiator"] || ch?.["X-Initiator"];
	const initiator =
	clientInitiator === "agent" || clientInitiator === "user" ? clientInitiator : "user";

[gemini-code-assist]

clientRawRequest.headers is often a Headers instance (Web API). Passing it directly to clientHeaders (typed as Record<string, string>) will cause property access like ch['x-initiator'] to fail in executors. It should be converted to a plain object. Using Object.fromEntries(headers.entries()) also has the benefit of lowercasing all keys, which simplifies lookup logic in the executors.

Suggested change

	clientHeaders: clientRawRequest?.headers ?? null,
	clientHeaders: clientRawRequest?.headers ? (typeof (clientRawRequest.headers as any).get === 'function' ? Object.fromEntries((clientRawRequest.headers as any).entries()) : clientRawRequest.headers) : null,

[diegosouzapw]

Thanks @cedrugs for this great contribution! 🎉 The fix has been integrated into the release/v3.6.6 branch and will be part of the next release. We appreciate your effort!