@posthog/agent 2.3.520 → 2.3.526

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);

package/src/handoff-checkpoint.ts

@@ -300,7 +300,7 @@ export class HandoffCheckpointTracker {
     checkpoint: GitHandoffCheckpoint,
     uploads: Uploads,
   ): void {
-    this.logger.info("Captured handoff checkpoint", {
+    this.logger.debug("Captured handoff checkpoint", {
       branch: checkpoint.branch,
       head: checkpoint.head?.slice(0, 7),
       totalBytes: this.sumRawBytes(uploads.pack, uploads.index),
@@ -312,7 +312,7 @@ export class HandoffCheckpointTracker {
     _downloads: Downloads,
     totalBytes: number,
   ): void {
-    this.logger.info("Applied handoff checkpoint", {
+    this.logger.debug("Applied handoff checkpoint", {
       branch: checkpoint.branch,
       head: checkpoint.head?.slice(0, 7),
       totalBytes,

package/src/server/agent-server.ts

@@ -588,7 +588,7 @@ export class AgentServer {
     switch (method) {
       case POSTHOG_NOTIFICATIONS.USER_MESSAGE:
       case "user_message": {
-        this.logger.info("Received user_message command", {
+        this.logger.debug("Received user_message command", {
           hasContent:
             typeof params.content === "string"
               ? params.content.trim().length > 0
@@ -608,7 +608,7 @@ export class AgentServer {
         if (prompt.length === 0) {
           throw new Error("User message cannot be empty");
         }
-        this.logger.info("Built user_message prompt", {
+        this.logger.debug("Built user_message prompt", {
           blockTypes: prompt.map((block) => block.type),
         });
         const promptPreview = promptBlocksToText(prompt);
@@ -718,7 +718,7 @@ export class AgentServer {
           ? params.mcpServers
           : [];
 
-        this.logger.info("Refresh session requested", {
+        this.logger.debug("Refresh session requested", {
           serverCount: mcpServers.length,
         });
 
@@ -1191,7 +1191,7 @@ export class AgentServer {
             this.resumeState.latestGitCheckpoint,
           );
           checkpointApplied = true;
-          this.logger.info("Git checkpoint applied", {
+          this.logger.debug("Git checkpoint applied", {
             branch: this.resumeState.latestGitCheckpoint.branch,
             head: this.resumeState.latestGitCheckpoint.head,
             packBytes: metrics.packBytes,
@@ -1314,7 +1314,7 @@ export class AgentServer {
       taskId: taskRun.task,
       runId: taskRun.id,
     });
-    this.logger.info("Built pending user prompt", {
+    this.logger.debug("Built pending user prompt", {
       hasMessage: typeof message === "string" && message.trim().length > 0,
       requestedArtifactCount: artifactIds.length,
       blockTypes: prompt.map((block) => block.type),