@posthog/agent 2.3.520 → 2.3.524

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@posthog/agent",
-  "version": "2.3.520",
+  "version": "2.3.524",
   "repository": "https://github.com/PostHog/code",
   "description": "TypeScript agent framework wrapping Claude Agent SDK with Git-based task execution for PostHog",
   "exports": {
@@ -103,12 +103,11 @@
     "typescript": "^5.5.0",
     "vitest": "^2.1.8",
     "@posthog/git": "1.0.0",
-    "@posthog/enricher": "1.0.0",
-    "@posthog/shared": "1.0.0"
+    "@posthog/shared": "1.0.0",
+    "@posthog/enricher": "1.0.0"
   },
   "dependencies": {
     "@agentclientprotocol/sdk": "0.19.0",
-    "ajv": "^8.17.1",
     "@anthropic-ai/claude-agent-sdk": "0.2.112",
     "@anthropic-ai/sdk": "0.89.0",
     "@hono/node-server": "^1.19.9",
@@ -122,6 +121,7 @@
     "hono": "^4.11.7",
     "jsonwebtoken": "^9.0.2",
     "minimatch": "^10.0.3",
+    "@modelcontextprotocol/sdk": "1.29.0",
     "tar": "^7.5.0",
     "uuid": "13.0.0",
     "yoga-wasm-web": "^0.3.3",

package/src/adapters/acp-connection.ts

@@ -205,6 +205,7 @@ function createCodexConnection(config: AcpConnectionConfig): AcpConnection {
       codexProcessOptions: config.codexOptions ?? {},
       processCallbacks: config.processCallbacks,
       posthogApiConfig: resolveEnricherApiConfig(config),
+      onStructuredOutput: config.onStructuredOutput,
     });
     return agent;
   }, agentStream);

package/src/adapters/codex/codex-agent.test.ts

@@ -53,6 +53,11 @@ vi.mock("./settings", () => ({
   })),
 }));
 
+vi.mock("node:fs", async (importActual) => {
+  const actual = await importActual<typeof import("node:fs")>();
+  return { ...actual, existsSync: vi.fn(actual.existsSync) };
+});
+
 import { CodexAcpAgent } from "./codex-agent";
 
 describe("CodexAcpAgent", () => {
@@ -60,7 +65,12 @@ describe("CodexAcpAgent", () => {
     vi.clearAllMocks();
   });
 
-  function createAgent(overrides: Partial<AgentSideConnection> = {}): {
+  function createAgent(
+    overrides: Partial<AgentSideConnection> = {},
+    agentOptions?: {
+      onStructuredOutput?: (output: Record<string, unknown>) => Promise<void>;
+    },
+  ): {
     agent: CodexAcpAgent;
     client: AgentSideConnection & {
       extNotification: ReturnType<typeof vi.fn>;
@@ -80,6 +90,7 @@ describe("CodexAcpAgent", () => {
       codexProcessOptions: {
         cwd: process.cwd(),
       },
+      onStructuredOutput: agentOptions?.onStructuredOutput,
     });
     return { agent, client };
   }
@@ -295,6 +306,128 @@ describe("CodexAcpAgent", () => {
     ).resolves.toEqual({ stopReason: "end_turn" });
   });
 
+  describe("structured output injection", () => {
+    const schema = {
+      type: "object",
+      properties: { answer: { type: "string" } },
+      required: ["answer"],
+    } as const;
+
+    beforeEach(async () => {
+      // The resolver checks existsSync to find the compiled MCP script.
+      // In unit tests the dist asset isn't on the walk-up path, so we
+      // make the first candidate succeed. Nothing in this test actually
+      // spawns the script — the agent only forwards the path to codex-acp.
+      const fs = await import("node:fs");
+      vi.mocked(fs.existsSync).mockReturnValue(true);
+    });
+
+    it("injects the create_output MCP server and system-prompt note when jsonSchema and callback are present", async () => {
+      const { agent } = createAgent({}, { onStructuredOutput: vi.fn() });
+      mockCodexConnection.newSession.mockResolvedValue({
+        sessionId: "session-1",
+        modes: { currentModeId: "auto", availableModes: [] },
+        configOptions: [],
+      } satisfies Partial<NewSessionResponse>);
+
+      await agent.newSession({
+        cwd: process.cwd(),
+        mcpServers: [{ name: "existing", command: "echo", args: [], env: [] }],
+        _meta: { jsonSchema: schema, systemPrompt: "be terse." },
+      } as never);
+
+      const forwarded = mockCodexConnection.newSession.mock.calls[0][0] as {
+        mcpServers: Array<{ name: string; command: string; env: unknown }>;
+        _meta: { systemPrompt: string };
+      };
+
+      // Existing MCP server is preserved; ours is appended.
+      expect(forwarded.mcpServers).toHaveLength(2);
+      expect(forwarded.mcpServers[0].name).toBe("existing");
+      expect(forwarded.mcpServers[1].name).toBe("posthog_output");
+      expect(forwarded.mcpServers[1].command).toBe(process.execPath);
+
+      // The schema is forwarded base64-encoded so codex-acp doesn't have
+      // to escape it through a shell.
+      const envEntry = (
+        forwarded.mcpServers[1].env as Array<{ name: string; value: string }>
+      ).find((e) => e.name === "POSTHOG_OUTPUT_SCHEMA");
+      expect(envEntry).toBeDefined();
+      const decoded = JSON.parse(
+        Buffer.from(envEntry?.value ?? "", "base64").toString("utf-8"),
+      );
+      expect(decoded).toEqual(schema);
+
+      // Existing systemPrompt is preserved with the structured-output
+      // instruction appended (not overwritten).
+      expect(forwarded._meta.systemPrompt.startsWith("be terse.")).toBe(true);
+      expect(forwarded._meta.systemPrompt).toContain("create_output");
+    });
+
+    it("is a no-op when jsonSchema is absent", async () => {
+      const { agent } = createAgent({}, { onStructuredOutput: vi.fn() });
+      mockCodexConnection.newSession.mockResolvedValue({
+        sessionId: "session-1",
+        modes: { currentModeId: "auto", availableModes: [] },
+        configOptions: [],
+      } satisfies Partial<NewSessionResponse>);
+
+      await agent.newSession({
+        cwd: process.cwd(),
+        mcpServers: [],
+      } as never);
+
+      const forwarded = mockCodexConnection.newSession.mock.calls[0][0] as {
+        mcpServers: unknown[];
+        _meta?: { systemPrompt?: string };
+      };
+      expect(forwarded.mcpServers).toEqual([]);
+      expect(forwarded._meta?.systemPrompt).toBeUndefined();
+    });
+
+    it("is a no-op when onStructuredOutput callback is not wired", async () => {
+      const { agent } = createAgent();
+      mockCodexConnection.newSession.mockResolvedValue({
+        sessionId: "session-1",
+        modes: { currentModeId: "auto", availableModes: [] },
+        configOptions: [],
+      } satisfies Partial<NewSessionResponse>);
+
+      await agent.newSession({
+        cwd: process.cwd(),
+        mcpServers: [],
+        _meta: { jsonSchema: schema },
+      } as never);
+
+      const forwarded = mockCodexConnection.newSession.mock.calls[0][0] as {
+        mcpServers: unknown[];
+      };
+      expect(forwarded.mcpServers).toEqual([]);
+    });
+
+    it("also injects on loadSession", async () => {
+      const { agent } = createAgent({}, { onStructuredOutput: vi.fn() });
+      mockCodexConnection.loadSession.mockResolvedValue({
+        modes: { currentModeId: "auto", availableModes: [] },
+        configOptions: [],
+      } satisfies Partial<LoadSessionResponse>);
+
+      await agent.loadSession({
+        sessionId: "session-1",
+        cwd: process.cwd(),
+        mcpServers: [],
+        _meta: { jsonSchema: schema },
+      } as never);
+
+      const forwarded = mockCodexConnection.loadSession.mock.calls[0][0] as {
+        mcpServers: Array<{ name: string }>;
+      };
+      expect(forwarded.mcpServers.map((s) => s.name)).toContain(
+        "posthog_output",
+      );
+    });
+  });
+
   it("broadcasts user prompt as user_message_chunk before delegating to codex-acp", async () => {
     const { agent, client } = createAgent();
     // Seed an active session so prompt() has the state it expects.

package/src/adapters/codex/codex-agent.ts

@@ -9,6 +9,8 @@
  * - System prompt injection
  */
 
+import { existsSync } from "node:fs";
+import { resolve as resolvePath } from "node:path";
 import {
   type AgentSideConnection,
   type AuthenticateRequest,
@@ -22,6 +24,7 @@ import {
   type LoadSessionRequest,
   type LoadSessionResponse,
   type McpServer,
+  type McpServerStdio,
   type NewSessionRequest,
   type NewSessionResponse,
   ndJsonStream,
@@ -72,6 +75,15 @@ import {
   type CodexProcessOptions,
   spawnCodexProcess,
 } from "./spawn";
+import {
+  STRUCTURED_OUTPUT_MCP_NAME,
+  STRUCTURED_OUTPUT_TOOL_NAME,
+} from "./structured-output-constants";
+
+export {
+  STRUCTURED_OUTPUT_MCP_NAME,
+  STRUCTURED_OUTPUT_TOOL_NAME,
+} from "./structured-output-constants";
 
 interface NewSessionMeta {
   taskRunId?: string;
@@ -86,12 +98,14 @@ interface NewSessionMeta {
   additionalRoots?: string[];
   disableBuiltInTools?: boolean;
   allowedDomains?: string[];
+  jsonSchema?: Record<string, unknown> | null;
 }
 
 export interface CodexAcpAgentOptions {
   codexProcessOptions: CodexProcessOptions;
   processCallbacks?: ProcessSpawnedCallback;
   posthogApiConfig?: PostHogAPIConfig;
+  onStructuredOutput?: (output: Record<string, unknown>) => Promise<void>;
 }
 
 type CodexSession = BaseSession & {
@@ -153,6 +167,46 @@ function getCurrentPermissionMode(
   return toCodexPermissionMode(fallbackMode);
 }
 
+const STRUCTURED_OUTPUT_INSTRUCTIONS = `\n\nWhen you have completed the task, call the \`${STRUCTURED_OUTPUT_TOOL_NAME}\` tool with the final structured result. The tool's input schema matches the required output format for this task. Do not describe the result in a plain message — submitting it via the tool is required for the task to be considered complete.`;
+
+/**
+ * Builds the stdio MCP server config that exposes the `create_output` tool.
+ * The child process validates tool input against the JSON schema with AJV.
+ * We pass the schema as a base64-encoded env var to avoid shell escaping.
+ *
+ * Path resolves relative to the compiled adapter location. When bundled into
+ * different entry points (dist/agent.js, dist/server/bin.cjs, dist/server/
+ * harness/bin.js, etc), `import.meta.dirname` sits at different depths. Walk
+ * up until we find the script so each bundle locates the shared dist asset.
+ */
+function resolveStructuredOutputMcpScript(): string {
+  const rel = "adapters/codex/structured-output-mcp-server.js";
+  let dir = import.meta.dirname ?? __dirname;
+  for (let i = 0; i < 5; i++) {
+    const candidate = resolvePath(dir, rel);
+    if (existsSync(candidate)) return candidate;
+    dir = resolvePath(dir, "..");
+  }
+  throw new Error(
+    `Could not locate ${rel} relative to ${import.meta.dirname ?? __dirname}.`,
+  );
+}
+
+function buildStructuredOutputMcpServer(
+  jsonSchema: Record<string, unknown>,
+): McpServerStdio {
+  const scriptPath = resolveStructuredOutputMcpScript();
+  const schemaBase64 = Buffer.from(JSON.stringify(jsonSchema)).toString(
+    "base64",
+  );
+  return {
+    name: STRUCTURED_OUTPUT_MCP_NAME,
+    command: process.execPath,
+    args: [scriptPath],
+    env: [{ name: "POSTHOG_OUTPUT_SCHEMA", value: schemaBase64 }],
+  };
+}
+
 export class CodexAcpAgent extends BaseAcpAgent {
   readonly adapterName = "codex";
   declare session: CodexSession;
@@ -172,6 +226,9 @@ export class CodexAcpAgent extends BaseAcpAgent {
   private promptMutex: Promise<unknown> = Promise.resolve();
   private readonly codexProcessOptions: CodexProcessOptions;
   private readonly processCallbacks?: ProcessSpawnedCallback;
+  private readonly onStructuredOutput?: (
+    output: Record<string, unknown>,
+  ) => Promise<void>;
   // Snapshot of the initialize() request so refreshSession can replay the
   // same handshake against a respawned codex-acp subprocess.
   private lastInitRequest?: InitializeRequest;
@@ -188,6 +245,7 @@ export class CodexAcpAgent extends BaseAcpAgent {
 
     this.codexProcessOptions = options.codexProcessOptions;
     this.processCallbacks = options.processCallbacks;
+    this.onStructuredOutput = options.onStructuredOutput;
 
     // Spawn the codex-acp subprocess
     this.codexProcess = spawnCodexProcess({
@@ -222,6 +280,7 @@ export class CodexAcpAgent extends BaseAcpAgent {
       (_agent) =>
         createCodexClient(this.client, this.logger, this.sessionState, {
           enrichmentDeps: this.enrichment?.deps,
+          onStructuredOutput: this.onStructuredOutput,
         }),
       codexStream,
     );
@@ -265,7 +324,8 @@ export class CodexAcpAgent extends BaseAcpAgent {
     const meta = params._meta as NewSessionMeta | undefined;
     const requestedPermissionMode = toCodexPermissionMode(meta?.permissionMode);
 
-    const response = await this.codexConnection.newSession(params);
+    const injectedParams = this.applyStructuredOutput(params, meta);
+    const response = await this.codexConnection.newSession(injectedParams);
     response.configOptions = normalizeCodexConfigOptions(
       response.configOptions,
     );
@@ -305,11 +365,12 @@ export class CodexAcpAgent extends BaseAcpAgent {
   }
 
   async loadSession(params: LoadSessionRequest): Promise<LoadSessionResponse> {
-    const response = await this.codexConnection.loadSession(params);
+    const meta = params._meta as NewSessionMeta | undefined;
+    const injectedParams = this.applyStructuredOutput(params, meta);
+    const response = await this.codexConnection.loadSession(injectedParams);
     response.configOptions = normalizeCodexConfigOptions(
       response.configOptions,
     );
-    const meta = params._meta as NewSessionMeta | undefined;
     const currentPermissionMode = getCurrentPermissionMode(
       response.modes?.currentModeId,
       meta?.permissionMode,
@@ -342,17 +403,22 @@ export class CodexAcpAgent extends BaseAcpAgent {
   async unstable_resumeSession(
     params: ResumeSessionRequest,
   ): Promise<ResumeSessionResponse> {
+    const meta = params._meta as NewSessionMeta | undefined;
+    const injectedParams = this.applyStructuredOutput(
+      {
+        sessionId: params.sessionId,
+        cwd: params.cwd,
+        mcpServers: params.mcpServers ?? [],
+        _meta: params._meta,
+      },
+      meta,
+    );
+
     // codex-acp doesn't support resume natively, use loadSession instead
-    const loadResponse = await this.codexConnection.loadSession({
-      sessionId: params.sessionId,
-      cwd: params.cwd,
-      mcpServers: params.mcpServers ?? [],
-    });
+    const loadResponse = await this.codexConnection.loadSession(injectedParams);
     loadResponse.configOptions = normalizeCodexConfigOptions(
       loadResponse.configOptions,
     );
-
-    const meta = params._meta as NewSessionMeta | undefined;
     const currentPermissionMode = getCurrentPermissionMode(
       loadResponse.modes?.currentModeId,
       meta?.permissionMode,
@@ -384,17 +450,22 @@ export class CodexAcpAgent extends BaseAcpAgent {
   async unstable_forkSession(
     params: ForkSessionRequest,
   ): Promise<ForkSessionResponse> {
+    const meta = params._meta as NewSessionMeta | undefined;
+    const injectedParams = this.applyStructuredOutput(
+      {
+        cwd: params.cwd,
+        mcpServers: params.mcpServers ?? [],
+        _meta: params._meta,
+      },
+      meta,
+    );
+
     // Create a new session via codex-acp (fork isn't natively supported)
-    const newResponse = await this.codexConnection.newSession({
-      cwd: params.cwd,
-      mcpServers: params.mcpServers ?? [],
-      _meta: params._meta,
-    });
+    const newResponse = await this.codexConnection.newSession(injectedParams);
     newResponse.configOptions = normalizeCodexConfigOptions(
       newResponse.configOptions,
     );
 
-    const meta = params._meta as NewSessionMeta | undefined;
     const requestedPermissionMode = toCodexPermissionMode(meta?.permissionMode);
     this.sessionState = createSessionState(newResponse.sessionId, params.cwd, {
       taskRunId: meta?.taskRunId,
@@ -414,6 +485,38 @@ export class CodexAcpAgent extends BaseAcpAgent {
     return newResponse;
   }
 
+  /**
+   * When the caller wires up `onStructuredOutput` and provides a JSON schema
+   * via `_meta.jsonSchema`, inject the stdio MCP server that exposes
+   * `create_output` and append instructions telling the model to use it.
+   *
+   * Codex has no native equivalent of Claude's `outputFormat`, so we lean on
+   * MCP tool-calling to get validated structured output back.
+   */
+  private applyStructuredOutput<
+    T extends { mcpServers?: McpServer[]; _meta?: unknown },
+  >(request: T, meta: NewSessionMeta | undefined): T {
+    if (!meta?.jsonSchema || !this.onStructuredOutput) {
+      return request;
+    }
+
+    const mcpServer = buildStructuredOutputMcpServer(meta.jsonSchema);
+    const existingMeta = (request._meta ?? {}) as Record<string, unknown>;
+    const existingSystemPrompt =
+      typeof existingMeta.systemPrompt === "string"
+        ? existingMeta.systemPrompt
+        : "";
+
+    return {
+      ...request,
+      mcpServers: [...(request.mcpServers ?? []), mcpServer],
+      _meta: {
+        ...existingMeta,
+        systemPrompt: existingSystemPrompt + STRUCTURED_OUTPUT_INSTRUCTIONS,
+      },
+    };
+  }
+
   private async applyInitialPermissionMode(
     sessionId: string,
     permissionMode?: string,
@@ -630,7 +733,9 @@ export class CodexAcpAgent extends BaseAcpAgent {
     const newAbortController = new AbortController();
     const newConnection = new ClientSideConnection(
       (_agent) =>
-        createCodexClient(this.client, this.logger, this.sessionState),
+        createCodexClient(this.client, this.logger, this.sessionState, {
+          onStructuredOutput: this.onStructuredOutput,
+        }),
       codexStream,
     );
 

package/src/adapters/codex/codex-client.test.ts

@@ -2,6 +2,7 @@ import type {
   AgentSideConnection,
   ReadTextFileRequest,
   ReadTextFileResponse,
+  SessionNotification,
 } from "@agentclientprotocol/sdk";
 import { describe, expect, test, vi } from "vitest";
 import type { FileEnrichmentDeps } from "../../enrichment/file-enricher";
@@ -110,3 +111,180 @@ describe("createCodexClient readTextFile", () => {
     expect(upstream.readTextFile).toHaveBeenCalledWith(params);
   });
 });
+
+describe("createCodexClient onStructuredOutput", () => {
+  const logger = new Logger({ debug: false, prefix: "[test]" });
+  const sessionState = createSessionState("sess", "/tmp");
+
+  function makeUpstream(): AgentSideConnection {
+    return {
+      sessionUpdate: vi.fn(async () => {}),
+      requestPermission: vi.fn(),
+      readTextFile: vi.fn(),
+      writeTextFile: vi.fn(),
+      createTerminal: vi.fn(),
+      terminalOutput: vi.fn(),
+      releaseTerminal: vi.fn(),
+      waitForTerminalExit: vi.fn(),
+      killTerminal: vi.fn(),
+      extMethod: vi.fn(),
+      extNotification: vi.fn(),
+    } as unknown as AgentSideConnection;
+  }
+
+  function notification(update: Record<string, unknown>): SessionNotification {
+    return {
+      sessionId: "sess",
+      update,
+    } as unknown as SessionNotification;
+  }
+
+  test("fires once when create_output completes after rawInput arrived", async () => {
+    const onStructuredOutput = vi.fn(async () => {});
+    const upstream = makeUpstream();
+    const client = createCodexClient(upstream, logger, sessionState, {
+      onStructuredOutput,
+    });
+
+    await client.sessionUpdate?.(
+      notification({
+        sessionUpdate: "tool_call",
+        toolCallId: "tc-1",
+        title: "create_output",
+        status: "in_progress",
+        rawInput: { result: "ok", count: 5 },
+      }),
+    );
+    expect(onStructuredOutput).not.toHaveBeenCalled();
+
+    await client.sessionUpdate?.(
+      notification({
+        sessionUpdate: "tool_call_update",
+        toolCallId: "tc-1",
+        title: "create_output",
+        status: "completed",
+      }),
+    );
+
+    expect(onStructuredOutput).toHaveBeenCalledTimes(1);
+    expect(onStructuredOutput).toHaveBeenCalledWith({ result: "ok", count: 5 });
+  });
+
+  test("matches mcp__-prefixed tool titles", async () => {
+    const onStructuredOutput = vi.fn(async () => {});
+    const upstream = makeUpstream();
+    const client = createCodexClient(upstream, logger, sessionState, {
+      onStructuredOutput,
+    });
+
+    await client.sessionUpdate?.(
+      notification({
+        sessionUpdate: "tool_call",
+        toolCallId: "tc-1",
+        title: "mcp__posthog_output__create_output",
+        status: "completed",
+        rawInput: { ok: true },
+      }),
+    );
+
+    expect(onStructuredOutput).toHaveBeenCalledWith({ ok: true });
+  });
+
+  test("ignores tool calls that aren't create_output", async () => {
+    const onStructuredOutput = vi.fn(async () => {});
+    const upstream = makeUpstream();
+    const client = createCodexClient(upstream, logger, sessionState, {
+      onStructuredOutput,
+    });
+
+    await client.sessionUpdate?.(
+      notification({
+        sessionUpdate: "tool_call",
+        toolCallId: "tc-1",
+        title: "Read",
+        status: "completed",
+        rawInput: { path: "/tmp/x" },
+      }),
+    );
+
+    expect(onStructuredOutput).not.toHaveBeenCalled();
+  });
+
+  test("does not fire when rawInput never arrived", async () => {
+    const onStructuredOutput = vi.fn(async () => {});
+    const upstream = makeUpstream();
+    const client = createCodexClient(upstream, logger, sessionState, {
+      onStructuredOutput,
+    });
+
+    await client.sessionUpdate?.(
+      notification({
+        sessionUpdate: "tool_call",
+        toolCallId: "tc-1",
+        title: "create_output",
+        status: "completed",
+      }),
+    );
+
+    expect(onStructuredOutput).not.toHaveBeenCalled();
+  });
+
+  test("does not fire twice if completed is re-emitted for the same tool call", async () => {
+    const onStructuredOutput = vi.fn(async () => {});
+    const upstream = makeUpstream();
+    const client = createCodexClient(upstream, logger, sessionState, {
+      onStructuredOutput,
+    });
+
+    const completed = notification({
+      sessionUpdate: "tool_call",
+      toolCallId: "tc-1",
+      title: "create_output",
+      status: "completed",
+      rawInput: { final: 1 },
+    });
+
+    await client.sessionUpdate?.(completed);
+    await client.sessionUpdate?.(completed);
+
+    expect(onStructuredOutput).toHaveBeenCalledTimes(1);
+  });
+
+  test("forwards the notification upstream regardless of structured-output handling", async () => {
+    const onStructuredOutput = vi.fn(async () => {});
+    const upstream = makeUpstream();
+    const client = createCodexClient(upstream, logger, sessionState, {
+      onStructuredOutput,
+    });
+
+    const note = notification({
+      sessionUpdate: "tool_call",
+      toolCallId: "tc-1",
+      title: "create_output",
+      status: "completed",
+      rawInput: { final: 1 },
+    });
+    await client.sessionUpdate?.(note);
+
+    expect(upstream.sessionUpdate).toHaveBeenCalledWith(note);
+  });
+
+  test("does nothing when the callback is not wired", async () => {
+    const upstream = makeUpstream();
+    const client = createCodexClient(upstream, logger, sessionState);
+
+    // No onStructuredOutput configured — must not throw and must still
+    // forward upstream.
+    await client.sessionUpdate?.(
+      notification({
+        sessionUpdate: "tool_call",
+        toolCallId: "tc-1",
+        title: "create_output",
+        status: "completed",
+        rawInput: { x: 1 },
+      }),
+    );
+
+    expect(upstream.sessionUpdate).toHaveBeenCalledTimes(1);
+  });
+});