@posthog/agent 2.1.17 → 2.1.29

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@posthog/agent",
-  "version": "2.1.17",
+  "version": "2.1.29",
   "repository": "https://github.com/PostHog/twig",
   "description": "TypeScript agent framework wrapping Claude Agent SDK with Git-based task execution for PostHog",
   "exports": {
@@ -76,16 +76,16 @@
     "@twig/git": "1.0.0"
   },
   "dependencies": {
+    "@agentclientprotocol/sdk": "^0.14.0",
+    "@anthropic-ai/claude-agent-sdk": "0.2.42",
+    "@anthropic-ai/sdk": "^0.71.0",
+    "@hono/node-server": "^1.19.9",
+    "@modelcontextprotocol/sdk": "^1.25.3",
     "@opentelemetry/api-logs": "^0.208.0",
     "@opentelemetry/exporter-logs-otlp-http": "^0.208.0",
     "@opentelemetry/resources": "^2.0.0",
     "@opentelemetry/sdk-logs": "^0.208.0",
     "@opentelemetry/semantic-conventions": "^1.28.0",
-    "@agentclientprotocol/sdk": "^0.14.0",
-    "@anthropic-ai/claude-agent-sdk": "0.2.12",
-    "@anthropic-ai/sdk": "^0.71.0",
-    "@hono/node-server": "^1.19.9",
-    "@modelcontextprotocol/sdk": "^1.25.3",
     "@types/jsonwebtoken": "^9.0.10",
     "commander": "^14.0.2",
     "diff": "^8.0.2",

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

@@ -137,7 +137,7 @@ export class ClaudeAcpAgent extends BaseAcpAgent {
     this.checkAuthStatus();
 
     const meta = params._meta as NewSessionMeta | undefined;
-    const internalSessionId = uuidv7();
+    const sessionId = uuidv7();
     const permissionMode: TwigExecutionMode =
       meta?.permissionMode &&
       TWIG_EXECUTION_MODES.includes(meta.permissionMode as TwigExecutionMode)
@@ -151,11 +151,13 @@ export class ClaudeAcpAgent extends BaseAcpAgent {
       cwd: params.cwd,
       mcpServers,
       permissionMode,
-      canUseTool: this.createCanUseTool(internalSessionId),
+      canUseTool: this.createCanUseTool(sessionId),
       logger: this.logger,
       systemPrompt: buildSystemPrompt(meta?.systemPrompt),
       userProvidedOptions: meta?.claudeCode?.options,
-      onModeChange: this.createOnModeChange(internalSessionId),
+      sessionId,
+      isResume: false,
+      onModeChange: this.createOnModeChange(sessionId),
       onProcessSpawned: this.processCallbacks?.onProcessSpawned,
       onProcessExited: this.processCallbacks?.onProcessExited,
     });
@@ -164,7 +166,7 @@ export class ClaudeAcpAgent extends BaseAcpAgent {
     const q = query({ prompt: input, options });
 
     const session = this.createSession(
-      internalSessionId,
+      sessionId,
       q,
       input,
       permissionMode,
@@ -172,21 +174,27 @@ export class ClaudeAcpAgent extends BaseAcpAgent {
       options.abortController as AbortController,
     );
     session.taskRunId = meta?.taskRunId;
-    this.registerPersistence(
-      internalSessionId,
-      meta as Record<string, unknown>,
-    );
+    this.registerPersistence(sessionId, meta as Record<string, unknown>);
+
+    if (meta?.taskRunId) {
+      await this.client.extNotification("_posthog/sdk_session", {
+        taskRunId: meta.taskRunId,
+        sessionId,
+        adapter: "claude",
+      });
+    }
+
     const modelOptions = await this.getModelConfigOptions();
     session.modelId = modelOptions.currentModelId;
     await this.trySetModel(q, modelOptions.currentModelId);
 
     this.sendAvailableCommandsUpdate(
-      internalSessionId,
+      sessionId,
       await getAvailableSlashCommands(q),
     );
 
     return {
-      sessionId: internalSessionId,
+      sessionId,
       configOptions: await this.buildConfigOptions(modelOptions),
     };
   }
@@ -198,12 +206,15 @@ export class ClaudeAcpAgent extends BaseAcpAgent {
   async resumeSession(
     params: LoadSessionRequest,
   ): Promise<LoadSessionResponse> {
-    const { sessionId: internalSessionId } = params;
-    if (this.sessionId === internalSessionId) {
+    const meta = params._meta as NewSessionMeta | undefined;
+    const sessionId = meta?.sessionId;
+    if (!sessionId) {
+      throw new Error("Cannot resume session without sessionId");
+    }
+    if (this.sessionId === sessionId) {
       return {};
     }
 
-    const meta = params._meta as NewSessionMeta | undefined;
     const mcpServers = parseMcpServers(params);
     await fetchMcpToolMetadata(mcpServers, this.logger);
 
@@ -214,27 +225,21 @@ export class ClaudeAcpAgent extends BaseAcpAgent {
         : "default";
 
     const { query: q, session } = await this.initializeQuery({
-      internalSessionId,
       cwd: params.cwd,
       permissionMode,
       mcpServers,
       systemPrompt: buildSystemPrompt(meta?.systemPrompt),
       userProvidedOptions: meta?.claudeCode?.options,
-      sessionId: meta?.sessionId,
+      sessionId,
+      isResume: true,
       additionalDirectories: meta?.claudeCode?.options?.additionalDirectories,
     });
 
     session.taskRunId = meta?.taskRunId;
-    if (meta?.sessionId) {
-      session.sessionId = meta.sessionId;
-    }
 
-    this.registerPersistence(
-      internalSessionId,
-      meta as Record<string, unknown>,
-    );
+    this.registerPersistence(sessionId, meta as Record<string, unknown>);
     this.sendAvailableCommandsUpdate(
-      internalSessionId,
+      sessionId,
       await getAvailableSlashCommands(q),
     );
 
@@ -322,13 +327,13 @@ export class ClaudeAcpAgent extends BaseAcpAgent {
   }
 
   private async initializeQuery(config: {
-    internalSessionId: string;
     cwd: string;
     permissionMode: TwigExecutionMode;
     mcpServers: ReturnType<typeof parseMcpServers>;
     userProvidedOptions?: Options;
     systemPrompt?: Options["systemPrompt"];
-    sessionId?: string;
+    sessionId: string;
+    isResume: boolean;
     additionalDirectories?: string[];
   }): Promise<{
     query: Query;
@@ -341,13 +346,14 @@ export class ClaudeAcpAgent extends BaseAcpAgent {
       cwd: config.cwd,
       mcpServers: config.mcpServers,
       permissionMode: config.permissionMode,
-      canUseTool: this.createCanUseTool(config.internalSessionId),
+      canUseTool: this.createCanUseTool(config.sessionId),
       logger: this.logger,
       systemPrompt: config.systemPrompt,
       userProvidedOptions: config.userProvidedOptions,
       sessionId: config.sessionId,
+      isResume: config.isResume,
       additionalDirectories: config.additionalDirectories,
-      onModeChange: this.createOnModeChange(config.internalSessionId),
+      onModeChange: this.createOnModeChange(config.sessionId),
       onProcessSpawned: this.processCallbacks?.onProcessSpawned,
       onProcessExited: this.processCallbacks?.onProcessExited,
     });
@@ -356,7 +362,7 @@ export class ClaudeAcpAgent extends BaseAcpAgent {
     const abortController = options.abortController as AbortController;
 
     const session = this.createSession(
-      config.internalSessionId,
+      config.sessionId,
       q,
       input,
       config.permissionMode,
@@ -596,6 +602,7 @@ export class ClaudeAcpAgent extends BaseAcpAgent {
 
       case "tool_progress":
       case "auth_status":
+      case "tool_use_summary":
         return null;
 
       default:

package/src/adapters/claude/conversion/sdk-to-acp.ts

@@ -328,20 +328,10 @@ export async function handleSystemMessage(
   message: any,
   context: MessageHandlerContext,
 ): Promise<void> {
-  const { session, sessionId, client, logger } = context;
+  const { sessionId, client, logger } = context;
 
   switch (message.subtype) {
     case "init":
-      if (message.session_id && session && !session.sessionId) {
-        session.sessionId = message.session_id;
-        if (session.taskRunId) {
-          await client.extNotification("_posthog/sdk_session", {
-            taskRunId: session.taskRunId,
-            sessionId: message.session_id,
-            adapter: "claude",
-          });
-        }
-      }
       break;
     case "compact_boundary":
       await client.extNotification("_posthog/compact_boundary", {

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

@@ -27,7 +27,8 @@ export interface BuildOptionsParams {
   logger: Logger;
   systemPrompt?: Options["systemPrompt"];
   userProvidedOptions?: Options;
-  sessionId?: string;
+  sessionId: string;
+  isResume: boolean;
   additionalDirectories?: string[];
   onModeChange?: OnModeChange;
   onProcessSpawned?: (info: ProcessSpawnedInfo) => void;
@@ -213,7 +214,7 @@ export function buildSessionOptions(params: BuildOptionsParams): Options {
     ),
     ...(params.onProcessSpawned && {
       spawnClaudeCodeProcess: buildSpawnWrapper(
-        params.sessionId ?? "unknown",
+        params.sessionId,
         params.onProcessSpawned,
         params.onProcessExited,
       ),
@@ -224,8 +225,11 @@ export function buildSessionOptions(params: BuildOptionsParams): Options {
     options.pathToClaudeCodeExecutable = process.env.CLAUDE_CODE_EXECUTABLE;
   }
 
-  if (params.sessionId) {
+  if (params.isResume) {
     options.resume = params.sessionId;
+    options.forkSession = false;
+  } else {
+    options.sessionId = params.sessionId;
   }
 
   if (params.additionalDirectories) {

package/src/adapters/claude/types.ts

@@ -29,7 +29,6 @@ export type Session = BaseSession & {
   modelId?: string;
   cwd: string;
   taskRunId?: string;
-  sessionId?: string;
   lastPlanFilePath?: string;
   lastPlanContent?: string;
 };

package/src/server/agent-server.ts

@@ -578,6 +578,8 @@ export class AgentServer {
       // Only auto-complete for background mode
       const mode = this.getEffectiveMode(payload);
       if (mode === "background") {
+        // Flush all pending session logs before signaling completion,
+        await this.session.logWriter.flushAll();
         await this.signalTaskComplete(payload, result.stopReason);
       } else {
         this.logger.info("Interactive mode - staying open for conversation");
@@ -587,6 +589,9 @@ export class AgentServer {
       // Signal failure for background mode
       const mode = this.getEffectiveMode(payload);
       if (mode === "background") {
+        if (this.session) {
+          await this.session.logWriter.flushAll();
+        }
         await this.signalTaskComplete(payload, "error");
       }
     }
@@ -602,7 +607,10 @@ After completing the requested changes:
 3. Push the branch to origin
 4. Create a pull request using \`gh pr create\` with a descriptive title and body
 
-Important: Always create the PR. Do not ask for confirmation.
+Important:
+- Always create the PR. Do not ask for confirmation.
+- Do NOT add "Co-Authored-By" trailers to commit messages.
+- Do NOT add "Generated with [Claude Code]" or similar attribution lines to PR descriptions.
 `;
   }
 
@@ -610,6 +618,18 @@ Important: Always create the PR. Do not ask for confirmation.
     payload: JwtPayload,
     stopReason: string,
   ): Promise<void> {
+    if (this.session?.payload.run_id === payload.run_id) {
+      try {
+        await this.session.logWriter.flush(payload.run_id);
+      } catch (error) {
+        this.logger.warn("Failed to flush session logs before completion", {
+          taskId: payload.task_id,
+          runId: payload.run_id,
+          error,
+        });
+      }
+    }
+
     const status =
       stopReason === "cancelled"
         ? "cancelled"

package/src/session-log-writer.test.ts

@@ -61,6 +61,47 @@ describe("SessionLogWriter", () => {
       await logWriter.flush(sessionId);
       expect(mockAppendLog).not.toHaveBeenCalled();
     });
+
+    it("re-queues entries when persistence fails and retries", async () => {
+      const sessionId = "s1";
+      logWriter.register(sessionId, { taskId: "t1", runId: sessionId });
+
+      mockAppendLog
+        .mockRejectedValueOnce(new Error("network error"))
+        .mockResolvedValueOnce(undefined);
+
+      logWriter.appendRawLine(sessionId, JSON.stringify({ method: "test" }));
+
+      await logWriter.flush(sessionId);
+      await logWriter.flush(sessionId);
+
+      expect(mockAppendLog).toHaveBeenCalledTimes(2);
+      const retriedEntries: StoredNotification[] =
+        mockAppendLog.mock.calls[1][2];
+      expect(retriedEntries).toHaveLength(1);
+      expect(retriedEntries[0].notification.method).toBe("test");
+    });
+
+    it("drops entries after max retries", async () => {
+      const sessionId = "s1";
+      logWriter.register(sessionId, { taskId: "t1", runId: sessionId });
+
+      mockAppendLog.mockRejectedValue(new Error("persistent failure"));
+
+      logWriter.appendRawLine(sessionId, JSON.stringify({ method: "test" }));
+
+      // Flush 10 times (MAX_FLUSH_RETRIES) — entries should be dropped on the 10th
+      for (let i = 0; i < 10; i++) {
+        await logWriter.flush(sessionId);
+      }
+
+      expect(mockAppendLog).toHaveBeenCalledTimes(10);
+
+      // After max retries the entries are dropped, so an 11th flush has nothing
+      mockAppendLog.mockClear();
+      await logWriter.flush(sessionId);
+      expect(mockAppendLog).not.toHaveBeenCalled();
+    });
   });
 
   describe("agent_message_chunk coalescing", () => {

package/src/session-log-writer.ts

@@ -21,10 +21,18 @@ interface SessionState {
 }
 
 export class SessionLogWriter {
+  private static readonly FLUSH_DEBOUNCE_MS = 500;
+  private static readonly FLUSH_MAX_INTERVAL_MS = 5000;
+  private static readonly MAX_FLUSH_RETRIES = 10;
+  private static readonly MAX_RETRY_DELAY_MS = 30_000;
+
   private posthogAPI?: PostHogAPIClient;
   private pendingEntries: Map<string, StoredNotification[]> = new Map();
   private flushTimeouts: Map<string, NodeJS.Timeout> = new Map();
+  private lastFlushAttemptTime: Map<string, number> = new Map();
+  private retryCounts: Map<string, number> = new Map();
   private sessions: Map<string, SessionState> = new Map();
+  private messageCounts: Map<string, number> = new Map();
   private logger: Logger;
 
   constructor(options: SessionLogWriterOptions = {}) {
@@ -35,8 +43,19 @@ export class SessionLogWriter {
   }
 
   async flushAll(): Promise<void> {
+    const sessionIds = [...this.sessions.keys()];
+    const pendingCounts = sessionIds.map((id) => ({
+      id,
+      pending: this.pendingEntries.get(id)?.length ?? 0,
+      messages: this.messageCounts.get(id) ?? 0,
+    }));
+    this.logger.info("flushAll called", {
+      sessions: sessionIds.length,
+      pending: pendingCounts,
+    });
+
     const flushPromises: Promise<void>[] = [];
-    for (const sessionId of this.sessions.keys()) {
+    for (const sessionId of sessionIds) {
       flushPromises.push(this.flush(sessionId));
     }
     await Promise.all(flushPromises);
@@ -47,7 +66,12 @@ export class SessionLogWriter {
       return;
     }
 
+    this.logger.info("Session registered", {
+      sessionId,
+      taskId: context.taskId,
+    });
     this.sessions.set(sessionId, { context });
+    this.lastFlushAttemptTime.set(sessionId, Date.now());
   }
 
   isRegistered(sessionId: string): boolean {
@@ -57,9 +81,18 @@ export class SessionLogWriter {
   appendRawLine(sessionId: string, line: string): void {
     const session = this.sessions.get(sessionId);
     if (!session) {
+      this.logger.warn("appendRawLine called for unregistered session", {
+        sessionId,
+      });
       return;
     }
 
+    const count = (this.messageCounts.get(sessionId) ?? 0) + 1;
+    this.messageCounts.set(sessionId, count);
+    if (count % 10 === 1) {
+      this.logger.info("Messages received", { count, sessionId });
+    }
+
     try {
       const message = JSON.parse(line);
       const timestamp = new Date().toISOString();
@@ -103,13 +136,23 @@ export class SessionLogWriter {
 
   async flush(sessionId: string): Promise<void> {
     const session = this.sessions.get(sessionId);
-    if (!session) return;
+    if (!session) {
+      this.logger.warn("flush: no session found", { sessionId });
+      return;
+    }
 
     // Emit any buffered chunks before flushing
     this.emitCoalescedMessage(sessionId, session);
 
     const pending = this.pendingEntries.get(sessionId);
-    if (!this.posthogAPI || !pending?.length) return;
+    if (!this.posthogAPI || !pending?.length) {
+      this.logger.info("flush: nothing to persist", {
+        sessionId,
+        hasPosthogAPI: !!this.posthogAPI,
+        pendingCount: pending?.length ?? 0,
+      });
+      return;
+    }
 
     this.pendingEntries.delete(sessionId);
     const timeout = this.flushTimeouts.get(sessionId);
@@ -118,14 +161,38 @@ export class SessionLogWriter {
       this.flushTimeouts.delete(sessionId);
     }
 
+    this.lastFlushAttemptTime.set(sessionId, Date.now());
+
     try {
       await this.posthogAPI.appendTaskRunLog(
         session.context.taskId,
         session.context.runId,
         pending,
       );
+      this.retryCounts.set(sessionId, 0);
+      this.logger.info("Flushed session logs", {
+        sessionId,
+        entryCount: pending.length,
+      });
     } catch (error) {
-      this.logger.error("Failed to persist session logs:", error);
+      const retryCount = (this.retryCounts.get(sessionId) ?? 0) + 1;
+      this.retryCounts.set(sessionId, retryCount);
+
+      if (retryCount >= SessionLogWriter.MAX_FLUSH_RETRIES) {
+        this.logger.error(
+          `Dropping ${pending.length} session log entries after ${retryCount} failed flush attempts`,
+          { sessionId, error },
+        );
+        this.retryCounts.set(sessionId, 0);
+      } else {
+        this.logger.error(
+          `Failed to persist session logs (attempt ${retryCount}/${SessionLogWriter.MAX_FLUSH_RETRIES}):`,
+          error,
+        );
+        const currentPending = this.pendingEntries.get(sessionId) ?? [];
+        this.pendingEntries.set(sessionId, [...pending, ...currentPending]);
+        this.scheduleFlush(sessionId);
+      }
     }
   }
 
@@ -180,7 +247,26 @@ export class SessionLogWriter {
   private scheduleFlush(sessionId: string): void {
     const existing = this.flushTimeouts.get(sessionId);
     if (existing) clearTimeout(existing);
-    const timeout = setTimeout(() => this.flush(sessionId), 500);
+
+    const retryCount = this.retryCounts.get(sessionId) ?? 0;
+    const lastAttempt = this.lastFlushAttemptTime.get(sessionId) ?? 0;
+    const elapsed = Date.now() - lastAttempt;
+
+    let delay: number;
+    if (retryCount > 0) {
+      // Exponential backoff on retries: FLUSH_DEBOUNCE_MS * 2^retryCount, capped
+      delay = Math.min(
+        SessionLogWriter.FLUSH_DEBOUNCE_MS * 2 ** retryCount,
+        SessionLogWriter.MAX_RETRY_DELAY_MS,
+      );
+    } else if (elapsed >= SessionLogWriter.FLUSH_MAX_INTERVAL_MS) {
+      // If we've been accumulating for longer than the max interval, flush immediately
+      delay = 0;
+    } else {
+      delay = SessionLogWriter.FLUSH_DEBOUNCE_MS;
+    }
+
+    const timeout = setTimeout(() => this.flush(sessionId), delay);
     this.flushTimeouts.set(sessionId, timeout);
   }
 }

package/src/test/mocks/claude-sdk.ts

@@ -95,6 +95,11 @@ export function createMockQuery(
       .fn()
       .mockResolvedValue({ added: [], removed: [], errors: {} }),
     streamInput: vi.fn().mockResolvedValue(undefined),
+    close: vi.fn(),
+    initializationResult: vi.fn().mockResolvedValue({}),
+    reconnectMcpServer: vi.fn().mockResolvedValue(undefined),
+    toggleMcpServer: vi.fn().mockResolvedValue(undefined),
+    stopTask: vi.fn().mockResolvedValue(undefined),
     [Symbol.asyncDispose]: vi.fn().mockResolvedValue(undefined),
     _abortController: abortController,
     _mockHelpers: {
@@ -158,6 +163,7 @@ export function createSuccessResult(
     is_error: false,
     num_turns: 1,
     result: "Done",
+    stop_reason: null,
     total_cost_usd: 0.01,
     usage: {
       input_tokens: 100,
@@ -190,6 +196,7 @@ export function createErrorResult(
     duration_ms: 100,
     duration_api_ms: 50,
     num_turns: 1,
+    stop_reason: null,
     total_cost_usd: 0.01,
     usage: {
       input_tokens: 100,