@posthog/agent 2.3.233 → 2.3.259

package/dist/types.d.ts

@@ -84,6 +84,8 @@ interface TaskExecutionOptions {
     codexBinaryPath?: string;
     instructions?: string;
     processCallbacks?: ProcessSpawnedCallback;
+    /** Callback invoked when the agent calls the create_output tool for structured output */
+    onStructuredOutput?: (output: Record<string, unknown>) => Promise<void>;
 }
 type LogLevel = "debug" | "info" | "warn" | "error";
 type OnLogCallback = (level: LogLevel, scope: string, message: string, data?: unknown) => void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@posthog/agent",
-  "version": "2.3.233",
+  "version": "2.3.259",
   "repository": "https://github.com/PostHog/code",
   "description": "TypeScript agent framework wrapping Claude Agent SDK with Git-based task execution for PostHog",
   "exports": {
@@ -87,6 +87,7 @@
   },
   "dependencies": {
     "@agentclientprotocol/sdk": "0.16.1",
+    "ajv": "^8.17.1",
     "@anthropic-ai/claude-agent-sdk": "0.2.76",
     "@anthropic-ai/sdk": "^0.78.0",
     "@hono/node-server": "^1.19.9",

package/src/adapters/acp-connection.ts

@@ -24,6 +24,8 @@ export type AcpConnectionConfig = {
   processCallbacks?: ProcessSpawnedCallback;
   codexOptions?: CodexProcessOptions;
   allowedModelIds?: Set<string>;
+  /** Callback invoked when the agent calls the create_output tool for structured output */
+  onStructuredOutput?: (output: Record<string, unknown>) => Promise<void>;
 };
 
 export type AcpConnection = {
@@ -97,7 +99,10 @@ function createClaudeConnection(config: AcpConnectionConfig): AcpConnection {
 
   let agent: ClaudeAcpAgent | null = null;
   const agentConnection = new AgentSideConnection((client) => {
-    agent = new ClaudeAcpAgent(client, config.processCallbacks);
+    agent = new ClaudeAcpAgent(client, {
+      ...config.processCallbacks,
+      onStructuredOutput: config.onStructuredOutput,
+    });
     logger.info(`Created ${agent.adapterName} agent`);
     return agent;
   }, agentStream);

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

@@ -109,6 +109,7 @@ export interface ClaudeAcpAgentOptions {
   onProcessSpawned?: (info: ProcessSpawnedInfo) => void;
   onProcessExited?: (pid: number) => void;
   onMcpServersReady?: (serverNames: string[]) => void;
+  onStructuredOutput?: (output: Record<string, unknown>) => Promise<void>;
 }
 
 export class ClaudeAcpAgent extends BaseAcpAgent {
@@ -483,6 +484,17 @@ export class ClaudeAcpAgent extends BaseAcpAgent {
             const result = handleResultMessage(message);
             if (result.error) throw result.error;
 
+            // Deliver structured output from SDK's native outputFormat
+            if (
+              message.subtype === "success" &&
+              message.structured_output != null &&
+              this.options?.onStructuredOutput
+            ) {
+              await this.options.onStructuredOutput(
+                message.structured_output as Record<string, unknown>,
+              );
+            }
+
             // For local-only commands, forward the result text to the client
             if (
               isLocalOnlyCommand &&
@@ -825,6 +837,12 @@ export class ClaudeAcpAgent extends BaseAcpAgent {
       : {};
     const systemPrompt = buildSystemPrompt(meta?.systemPrompt);
 
+    // Configure structured output via SDK's native outputFormat
+    const outputFormat =
+      meta?.jsonSchema && this.options?.onStructuredOutput
+        ? { type: "json_schema" as const, schema: meta.jsonSchema }
+        : undefined;
+
     this.logger.info(isResume ? "Resuming session" : "Creating new session", {
       sessionId,
       taskId,
@@ -854,6 +872,7 @@ export class ClaudeAcpAgent extends BaseAcpAgent {
         ...(meta?.additionalRoots ?? []),
       ],
       disableBuiltInTools: meta?.disableBuiltInTools,
+      outputFormat,
       settingsManager,
       onModeChange: this.createOnModeChange(),
       onProcessSpawned: this.options?.onProcessSpawned,

package/src/adapters/claude/session/jsonl-hydration.ts

@@ -496,7 +496,7 @@ export async function hydrateSessionJsonl(params: {
   permissionMode?: string;
   posthogAPI: PostHogAPIClient;
   log: HydrationLog;
-}): Promise<void> {
+}): Promise<boolean> {
   const { posthogAPI, log } = params;
 
   try {
@@ -506,7 +506,7 @@ export async function hydrateSessionJsonl(params: {
       log.info("Local JSONL exists, skipping S3 hydration", {
         sessionId: params.sessionId,
       });
-      return;
+      return true;
     } catch {
       // File doesn't exist, proceed with hydration
     }
@@ -514,13 +514,13 @@ export async function hydrateSessionJsonl(params: {
     const taskRun = await posthogAPI.getTaskRun(params.taskId, params.runId);
     if (!taskRun.log_url) {
       log.info("No log URL, skipping JSONL hydration");
-      return;
+      return false;
     }
 
     const entries = await posthogAPI.fetchTaskRunLogs(taskRun);
     if (entries.length === 0) {
       log.info("No S3 log entries, skipping JSONL hydration");
-      return;
+      return false;
     }
 
     const entryCounts: Record<string, number> = {};
@@ -545,7 +545,7 @@ export async function hydrateSessionJsonl(params: {
     const allTurns = rebuildConversation(entries);
     if (allTurns.length === 0) {
       log.info("No conversation in S3 logs, skipping JSONL hydration");
-      return;
+      return false;
     }
 
     const maxTokens = supports1MContext(params.model ?? "")
@@ -577,10 +577,12 @@ export async function hydrateSessionJsonl(params: {
       turns: conversation.length,
       lines: jsonlLines.length,
     });
+    return true;
   } catch (err) {
     log.warn("Failed to hydrate session JSONL, continuing", {
       sessionId: params.sessionId,
       error: err instanceof Error ? err.message : String(err),
     });
+    return false;
   }
 }

package/src/adapters/claude/session/options.ts

@@ -6,6 +6,7 @@ import type {
   CanUseTool,
   McpServerConfig,
   Options,
+  OutputFormat,
   SpawnedProcess,
   SpawnOptions,
 } from "@anthropic-ai/claude-agent-sdk";
@@ -42,6 +43,7 @@ export interface BuildOptionsParams {
   forkSession?: boolean;
   additionalDirectories?: string[];
   disableBuiltInTools?: boolean;
+  outputFormat?: OutputFormat;
   settingsManager: SettingsManager;
   onModeChange?: OnModeChange;
   onProcessSpawned?: (info: ProcessSpawnedInfo) => void;
@@ -268,6 +270,7 @@ export function buildSessionOptions(params: BuildOptionsParams): Options {
       params.settingsManager,
       params.logger,
     ),
+    outputFormat: params.outputFormat,
     abortController: getAbortController(
       params.userProvidedOptions?.abortController,
     ),

package/src/adapters/claude/types.ts

@@ -110,6 +110,7 @@ export type NewSessionMeta = {
   allowedDomains?: string[];
   /** Model ID to use for this session (e.g. "claude-sonnet-4-6") */
   model?: string;
+  jsonSchema?: Record<string, unknown> | null;
   claudeCode?: {
     options?: Options;
   };

package/src/agent.ts

@@ -122,6 +122,7 @@ export class Agent {
       deviceType: "local",
       logger: this.logger,
       processCallbacks: options.processCallbacks,
+      onStructuredOutput: options.onStructuredOutput,
       allowedModelIds,
       codexOptions:
         options.adapter === "codex" && gatewayConfig

package/src/posthog-api.ts

@@ -158,6 +158,20 @@ export class PostHogAPIClient {
     );
   }
 
+  async setTaskRunOutput(
+    taskId: string,
+    runId: string,
+    output: Record<string, unknown>,
+  ): Promise<TaskRun> {
+    return this.apiRequest(
+      `/api/projects/${this.getTeamId()}/tasks/${taskId}/runs/${runId}/set_output/`,
+      {
+        method: "PATCH",
+        body: JSON.stringify(output),
+      },
+    );
+  }
+
   async appendTaskRunLog(
     taskId: string,
     runId: string,

package/src/server/agent-server.ts

@@ -665,6 +665,15 @@ export class AgentServer {
       taskId: payload.task_id,
       deviceType: deviceInfo.type,
       logWriter,
+      onStructuredOutput: async (output) => {
+        await this.posthogAPI.setTaskRunOutput(
+          payload.task_id,
+          payload.run_id,
+          {
+            output,
+          },
+        );
+      },
     });
 
     // Tap both streams to broadcast all ACP messages via SSE (mimics local transport)
@@ -700,18 +709,25 @@ export class AgentServer {
       clientCapabilities: {},
     });
 
-    let preTaskRun: TaskRun | null = null;
-    try {
-      preTaskRun = await this.posthogAPI.getTaskRun(
-        payload.task_id,
-        payload.run_id,
-      );
-    } catch {
-      this.logger.warn("Failed to fetch task run for session context", {
-        taskId: payload.task_id,
-        runId: payload.run_id,
-      });
-    }
+    const [preTaskRun, preTask] = await Promise.all([
+      this.posthogAPI
+        .getTaskRun(payload.task_id, payload.run_id)
+        .catch((err) => {
+          this.logger.warn("Failed to fetch task run for session context", {
+            taskId: payload.task_id,
+            runId: payload.run_id,
+            error: err,
+          });
+          return null;
+        }),
+      this.posthogAPI.getTask(payload.task_id).catch((err) => {
+        this.logger.warn("Failed to fetch task for session context", {
+          taskId: payload.task_id,
+          error: err,
+        });
+        return null;
+      }),
+    ]);
 
     const prUrl =
       typeof (preTaskRun?.state as Record<string, unknown>)
@@ -732,6 +748,7 @@ export class AgentServer {
         taskRunId: payload.run_id,
         systemPrompt: this.buildSessionSystemPrompt(prUrl),
         allowedDomains: this.config.allowedDomains,
+        jsonSchema: preTask?.json_schema ?? null,
         ...(this.config.claudeCode?.plugins?.length && {
           claudeCode: {
             options: {

package/src/types.ts

@@ -114,6 +114,8 @@ export interface TaskExecutionOptions {
   codexBinaryPath?: string;
   instructions?: string;
   processCallbacks?: ProcessSpawnedCallback;
+  /** Callback invoked when the agent calls the create_output tool for structured output */
+  onStructuredOutput?: (output: Record<string, unknown>) => Promise<void>;
 }
 
 export type LogLevel = "debug" | "info" | "warn" | "error";