@posthog/agent 2.3.519 → 2.3.524

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

@@ -36,12 +36,45 @@ import {
 import type { PermissionMode } from "../../execution-mode";
 import type { Logger } from "../../utils/logger";
 import type { CodexSessionState } from "./session-state";
+import {
+  STRUCTURED_OUTPUT_MCP_NAME,
+  STRUCTURED_OUTPUT_TOOL_NAME,
+} from "./structured-output-constants";
 
 export interface CodexClientCallbacks {
   /** Called when a usage_update session notification is received */
   onUsageUpdate?: (update: Record<string, unknown>) => void;
   /** When set, Read responses are annotated with PostHog enrichment before reaching codex-acp. */
   enrichmentDeps?: FileEnrichmentDeps;
+  /**
+   * Called once per session when the agent completes the injected
+   * `create_output` MCP tool. Matches the Claude adapter's structured
+   * output delivery.
+   */
+  onStructuredOutput?: (output: Record<string, unknown>) => Promise<void>;
+}
+
+/**
+ * Tool calls for our injected MCP server surface in ACP `tool_call` /
+ * `tool_call_update` notifications. The `title` from codex-acp can be
+ * either the bare tool name or prefixed (`mcp__<server>__<tool>`); match
+ * both forms but require the server name on prefixed titles so an unrelated
+ * user tool happening to contain `create_output` doesn't trigger us.
+ */
+function isStructuredOutputToolCall(title: string | undefined | null): boolean {
+  if (!title) return false;
+  if (title === STRUCTURED_OUTPUT_TOOL_NAME) return true;
+  return (
+    title.includes(STRUCTURED_OUTPUT_MCP_NAME) &&
+    title.includes(STRUCTURED_OUTPUT_TOOL_NAME)
+  );
+}
+
+function toRecord(value: unknown): Record<string, unknown> | null {
+  if (value && typeof value === "object" && !Array.isArray(value)) {
+    return value as Record<string, unknown>;
+  }
+  return null;
 }
 
 const AUTO_APPROVED_KINDS: Record<PermissionMode, Set<ToolKind>> = {
@@ -96,6 +129,14 @@ export function createCodexClient(
   callbacks?: CodexClientCallbacks,
 ): Client {
   const terminalHandles = new Map<string, TerminalHandle>();
+  // Track rawInput across tool_call → tool_call_update → completed so we can
+  // fire onStructuredOutput exactly once per tool call id. Entries stay in
+  // the map after firing with `fired: true` so a re-emitted completion
+  // (if codex-acp ever resends one) is a no-op.
+  const structuredOutputState = new Map<
+    string,
+    { rawInput?: Record<string, unknown>; fired: boolean }
+  >();
 
   return {
     async requestPermission(
@@ -125,6 +166,33 @@ export function createCodexClient(
 
     async sessionUpdate(params: SessionNotification): Promise<void> {
       const update = params.update as Record<string, unknown> | undefined;
+
+      if (
+        callbacks?.onStructuredOutput &&
+        (update?.sessionUpdate === "tool_call" ||
+          update?.sessionUpdate === "tool_call_update")
+      ) {
+        const toolCallId = update.toolCallId as string | undefined;
+        const title = update.title as string | undefined;
+        if (toolCallId && isStructuredOutputToolCall(title)) {
+          const entry = structuredOutputState.get(toolCallId) ?? {
+            fired: false,
+          };
+          const rawInput = toRecord(update.rawInput);
+          if (rawInput) entry.rawInput = rawInput;
+          structuredOutputState.set(toolCallId, entry);
+
+          if (update.status === "completed" && !entry.fired && entry.rawInput) {
+            entry.fired = true;
+            try {
+              await callbacks.onStructuredOutput(entry.rawInput);
+            } catch (err) {
+              logger.warn("onStructuredOutput callback threw", { error: err });
+            }
+          }
+        }
+      }
+
       if (update?.sessionUpdate === "usage_update") {
         const used = update.used as number | undefined;
         const size = update.size as number | undefined;

package/src/adapters/codex/structured-output-constants.ts

@@ -0,0 +1,9 @@
+/**
+ * Shared identifiers for the injected structured-output MCP server.
+ * Imported by codex-agent.ts (server config), codex-client.ts (tool-call
+ * matching), and structured-output-mcp-server.ts (tool registration) so the
+ * three stay in sync.
+ */
+
+export const STRUCTURED_OUTPUT_MCP_NAME = "posthog_output";
+export const STRUCTURED_OUTPUT_TOOL_NAME = "create_output";

package/src/adapters/codex/structured-output-mcp-server.ts

@@ -0,0 +1,72 @@
+/**
+ * Standalone stdio MCP server for structured output in the Codex adapter.
+ *
+ * Spawned by codex-acp as an MCP server process. Reads the JSON schema
+ * from the POSTHOG_OUTPUT_SCHEMA env var (base64-encoded) and registers
+ * a tool whose Zod shape McpServer.tool() validates on each call.
+ *
+ * Usage:
+ *   POSTHOG_OUTPUT_SCHEMA=<base64> node structured-output-mcp-server.js
+ */
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import {
+  STRUCTURED_OUTPUT_MCP_NAME,
+  STRUCTURED_OUTPUT_TOOL_NAME,
+} from "./structured-output-constants";
+
+function die(message: string): never {
+  process.stderr.write(`[structured-output-mcp-server] ${message}\n`);
+  process.exit(1);
+}
+
+const schemaEnv = process.env.POSTHOG_OUTPUT_SCHEMA;
+if (!schemaEnv) {
+  die("POSTHOG_OUTPUT_SCHEMA env var is required");
+}
+
+let jsonSchema: Record<string, unknown>;
+try {
+  jsonSchema = JSON.parse(Buffer.from(schemaEnv, "base64").toString("utf-8"));
+} catch (err) {
+  die(`Failed to parse POSTHOG_OUTPUT_SCHEMA as base64-encoded JSON: ${err}`);
+}
+
+const zodType = z.fromJSONSchema(jsonSchema);
+if (!(zodType instanceof z.ZodObject)) {
+  die(
+    `POSTHOG_OUTPUT_SCHEMA must describe a JSON object schema (got ${zodType.constructor.name})`,
+  );
+}
+// McpServer.tool() expects a mutable ZodRawShape
+const zodShape = { ...zodType.shape } as z.ZodRawShape;
+
+const server = new McpServer({
+  name: STRUCTURED_OUTPUT_MCP_NAME,
+  version: "1.0.0",
+});
+
+server.tool(
+  STRUCTURED_OUTPUT_TOOL_NAME,
+  "Submit the structured output for this task. Call this tool with the required fields to deliver your final result.",
+  zodShape,
+  async () => {
+    // McpServer.tool() validates `args` against `zodShape` before invoking
+    // this handler, so reaching this point means the input is valid. The
+    // parent process captures the validated output by intercepting the
+    // tool call in the ACP stream.
+    return {
+      content: [
+        {
+          type: "text" as const,
+          text: "Output submitted successfully.",
+        },
+      ],
+    };
+  },
+);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);