feat(agent): structured output for codex adapter via stdio MCP (#1885)

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: ryans-posthog

packages/agent/package.json

@@ -117,7 +117,6 @@
   },
   "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",
@@ -131,6 +130,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",

packages/agent/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);

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

@@ -53,14 +53,24 @@ 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", () => {
   beforeEach(() => {
     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.