fix(agent): forward posthog property headers on the codex gateway path (#3297)

Author: joshsny

packages/agent/src/adapters/acp-connection.ts

@@ -225,6 +225,7 @@ function createCodexConnection(config: AcpConnectionConfig): AcpConnection {
         apiKey: codexOptions.apiKey,
         codexHome: codexOptions.codexHome,
         developerInstructions: codexOptions.developerInstructions,
+        httpHeaders: codexOptions.httpHeaders,
         configOverrides: codexOptions.configOverrides,
       },
       model: codexOptions.model,

packages/agent/src/adapters/claude/session/options.ts

@@ -50,6 +50,13 @@ export type GatewayEnv = {
   openaiApiKey: string;
   /** Task-specific custom headers forwarded to the gateway (e.g. task_id, run_id). */
   anthropicCustomHeaders?: string;
+  /**
+   * Same task-metadata attribution headers as {@link anthropicCustomHeaders},
+   * in record form for the codex/OpenAI path (which sets provider
+   * `http_headers` rather than `ANTHROPIC_CUSTOM_HEADERS`). Includes `team_id`,
+   * which the Claude path instead appends in {@link buildEnvironment}.
+   */
+  openaiCustomHeaders?: Record<string, string>;
   /** PostHog project ID for per-team attribution headers. */
   posthogProjectId?: string;
 };

packages/agent/src/adapters/codex-app-server/spawn.test.ts

@@ -39,6 +39,43 @@ describe("buildAppServerArgs", () => {
     );
   });
 
+  it("forwards http headers as a quoted TOML inline table on the posthog provider", () => {
+    const args = buildAppServerArgs({
+      binaryPath: "/bundle/codex",
+      apiBaseUrl: "https://gateway.example/v1",
+      httpHeaders: {
+        "x-posthog-property-ai_stage": "research",
+        "x-posthog-property-team_id": "42",
+      },
+    });
+
+    expect(args).toContain(
+      'model_providers.posthog.http_headers={ "x-posthog-property-ai_stage" = "research", "x-posthog-property-team_id" = "42" }',
+    );
+  });
+
+  it("omits http_headers when none are provided or the provider is unset", () => {
+    const withoutHeaders = buildAppServerArgs({
+      binaryPath: "/bundle/codex",
+      apiBaseUrl: "https://gateway.example/v1",
+    });
+    const withoutProvider = buildAppServerArgs({
+      binaryPath: "/bundle/codex",
+      httpHeaders: { "x-posthog-property-ai_stage": "research" },
+    });
+
+    expect(
+      withoutHeaders.some((arg) =>
+        arg.startsWith("model_providers.posthog.http_headers="),
+      ),
+    ).toBe(false);
+    expect(
+      withoutProvider.some((arg) =>
+        arg.startsWith("model_providers.posthog.http_headers="),
+      ),
+    ).toBe(false);
+  });
+
   it.each([
     ["darwin", 'sandbox_mode="workspace-write"'],
     ["linux", 'sandbox_mode="danger-full-access"'],

packages/agent/src/adapters/codex-app-server/spawn.ts

@@ -17,6 +17,13 @@ export interface CodexOptions {
   apiKey?: string;
   model?: string;
   reasoningEffort?: string;
+  /**
+   * Static HTTP headers forwarded on every request to the PostHog gateway
+   * (the codex equivalent of Claude's `ANTHROPIC_CUSTOM_HEADERS`). Carries the
+   * `x-posthog-property-*` attribution headers the gateway lifts onto the
+   * `$ai_generation` event (team_id, ai_stage, task metadata).
+   */
+  httpHeaders?: Record<string, string>;
   /** Guidance appended on top of Codex's base prompt via `developer_instructions`. */
   developerInstructions?: string;
   /**
@@ -50,6 +57,12 @@ export interface CodexAppServerProcessOptions {
   codexHome?: string;
   /** Guidance appended to Codex's base prompt via `developer_instructions`. */
   developerInstructions?: string;
+  /**
+   * Static HTTP headers forwarded on every request to the PostHog gateway, set
+   * as `model_providers.posthog.http_headers`. Codex equivalent of Claude's
+   * `ANTHROPIC_CUSTOM_HEADERS` (see {@link CodexOptions.httpHeaders}).
+   */
+  httpHeaders?: Record<string, string>;
   /** Extra codex `-c key=value` config overrides (e.g. auto_compact_token_limit). */
   configOverrides?: Record<string, string | number>;
   logger?: Logger;
@@ -63,6 +76,19 @@ export interface CodexAppServerProcess {
   kill: () => void;
 }
 
+/** Serialize a string map as a TOML basic string (escapes `\` and `"`). */
+function tomlBasicString(value: string): string {
+  return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+
+/** Render a `Record<string, string>` as a TOML inline table. */
+function tomlInlineTable(entries: Record<string, string>): string {
+  const pairs = Object.entries(entries).map(
+    ([key, value]) => `${tomlBasicString(key)} = ${tomlBasicString(value)}`,
+  );
+  return `{ ${pairs.join(", ")} }`;
+}
+
 export function buildAppServerArgs(
   options: CodexAppServerProcessOptions,
 ): string[] {
@@ -116,6 +142,17 @@ export function buildAppServerArgs(
       "-c",
       `model_providers.posthog.env_key="POSTHOG_GATEWAY_API_KEY"`,
     );
+
+    // Attribution + task-metadata headers the gateway lifts onto the captured
+    // $ai_generation event. Passed as a single TOML inline table so hyphenated
+    // header names (`x-posthog-property-*`) stay quoted rather than becoming
+    // bare-key segments of a dotted `-c` path.
+    if (options.httpHeaders && Object.keys(options.httpHeaders).length > 0) {
+      args.push(
+        "-c",
+        `model_providers.posthog.http_headers=${tomlInlineTable(options.httpHeaders)}`,
+      );
+    }
   }
 
   // developer_instructions are set per-thread in thread/start (with the host's

packages/agent/src/server/agent-server.configure-environment.test.ts

@@ -161,6 +161,35 @@ describe("AgentServer.configureEnvironment", () => {
     },
   );
 
+  // The codex/OpenAI path sets provider http_headers rather than
+  // ANTHROPIC_CUSTOM_HEADERS, so the same task metadata must be exposed as a
+  // record — including team_id, which the Claude path adds separately in
+  // buildEnvironment.
+  it("forwards task metadata (plus team_id) as openaiCustomHeaders", () => {
+    const env = buildServer("background").configureEnvironment({
+      isInternal: true,
+      originProduct: "signal_report",
+      signalReportId: "report-123",
+      aiStage: "research",
+      taskId: "task-abc",
+      taskRunId: "run-xyz",
+      taskUserId: 42,
+      taskTitle: "Fix the bug",
+    });
+
+    expect(env.openaiCustomHeaders).toEqual({
+      "x-posthog-property-task_origin_product": "signal_report",
+      "x-posthog-property-task_internal": "true",
+      "x-posthog-property-signal_report_id": "report-123",
+      "x-posthog-property-ai_stage": "research",
+      "x-posthog-property-task_id": "task-abc",
+      "x-posthog-property-task_run_id": "run-xyz",
+      "x-posthog-property-task_user_id": "42",
+      "x-posthog-property-task_title": "Fix the bug",
+      "x-posthog-property-team_id": "1",
+    });
+  });
+
   it("forwards task metadata as anthropicCustomHeaders", () => {
     const env = buildServer("background").configureEnvironment({
       isInternal: true,

packages/agent/src/server/agent-server.ts

@@ -74,6 +74,7 @@ import type {
 import { resourceLink } from "../utils/acp-content";
 import { AsyncMutex } from "../utils/async-mutex";
 import {
+  buildGatewayPropertyHeaderRecord,
   buildGatewayPropertyHeaders,
   resolveGatewayProduct,
   resolveLlmGatewayUrl,
@@ -1254,6 +1255,7 @@ export class AgentServer {
               model: this.config.model ?? DEFAULT_CODEX_MODEL,
               reasoningEffort: this.config.reasoningEffort,
               developerInstructions: codexInstructions,
+              httpHeaders: gatewayEnv.openaiCustomHeaders,
             }
           : undefined,
       onStructuredOutput: async (output) => {
@@ -3060,12 +3062,11 @@ ${signedCommitInstructions}${prLinkInstructions}${shellEfficiencyInstructions}
       ? gatewayUrl
       : `${gatewayUrl}/v1`;
     // Forward task metadata as `x-posthog-property-*` headers so the gateway
-    // lifts them onto the $ai_generation event. Routes through the Anthropic
-    // SDK's ANTHROPIC_CUSTOM_HEADERS env var; the OpenAI/codex path has no
-    // equivalent today. (The `team_id` attribution header is added downstream
-    // in the Claude session builder from POSTHOG_PROJECT_ID — see
-    // adapters/claude/session/options.ts.)
-    const customHeaders = buildGatewayPropertyHeaders({
+    // lifts them onto the $ai_generation event. The Claude path routes these
+    // through the Anthropic SDK's ANTHROPIC_CUSTOM_HEADERS env var; the codex
+    // path sets them as `model_providers.posthog.http_headers` instead, so we
+    // also expose the record form below.
+    const gatewayProperties = {
       task_origin_product: originProduct,
       task_internal: isInternal,
       signal_report_id: signalReportId,
@@ -3074,6 +3075,14 @@ ${signedCommitInstructions}${prLinkInstructions}${shellEfficiencyInstructions}
       task_run_id: taskRunId,
       task_user_id: taskUserId,
       task_title: taskTitle,
+    };
+    const customHeaders = buildGatewayPropertyHeaders(gatewayProperties);
+    // The Claude path appends `team_id` in buildEnvironment from
+    // POSTHOG_PROJECT_ID; the codex path has no such hook, so fold it into the
+    // record here to keep team attribution working for both adapters.
+    const openaiCustomHeaders = buildGatewayPropertyHeaderRecord({
+      ...gatewayProperties,
+      team_id: projectId,
     });
 
     // Server-level constants that don't vary per task — safe to keep in
@@ -3096,6 +3105,7 @@ ${signedCommitInstructions}${prLinkInstructions}${shellEfficiencyInstructions}
       openaiBaseUrl,
       openaiApiKey: apiKey,
       anthropicCustomHeaders: customHeaders,
+      openaiCustomHeaders,
       posthogProjectId: String(projectId),
     };
   }

packages/agent/src/utils/gateway.ts

@@ -31,7 +31,10 @@ export function resolveGatewayProduct({
   return "posthog_code";
 }
 
-export { buildPosthogPropertyHeaderLines as buildGatewayPropertyHeaders } from "@posthog/shared/posthog-property-headers";
+export {
+  buildPosthogPropertyHeaderLines as buildGatewayPropertyHeaders,
+  buildPosthogPropertyHeaderRecord as buildGatewayPropertyHeaderRecord,
+} from "@posthog/shared/posthog-property-headers";
 
 function getGatewayBaseUrl(posthogHost: string): string {
   const url = new URL(posthogHost);