@posthog/agent 2.3.387 → 2.3.388

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@posthog/agent",
-  "version": "2.3.387",
+  "version": "2.3.388",
   "repository": "https://github.com/PostHog/code",
   "description": "TypeScript agent framework wrapping Claude Agent SDK with Git-based task execution for PostHog",
   "exports": {
@@ -102,8 +102,8 @@
     "tsx": "^4.20.6",
     "typescript": "^5.5.0",
     "vitest": "^2.1.8",
-    "@posthog/shared": "1.0.0",
     "@posthog/git": "1.0.0",
+    "@posthog/shared": "1.0.0",
     "@posthog/enricher": "1.0.0"
   },
   "dependencies": {

package/src/handoff-checkpoint.ts

@@ -113,7 +113,7 @@ export class HandoffCheckpointTracker {
         divergence: GitHandoffBranchDivergence,
       ) => Promise<boolean>;
     },
-  ): Promise<void> {
+  ): Promise<{ packBytes: number; indexBytes: number; totalBytes: number }> {
     if (!this.apiClient) {
       throw new Error(
         "Cannot apply handoff checkpoint: API client not configured",
@@ -152,6 +152,12 @@ export class HandoffCheckpointTracker {
       });
 
       this.logApplyMetrics(checkpoint, downloads, applyResult.totalBytes);
+
+      return {
+        packBytes: downloads.pack?.rawBytes ?? 0,
+        indexBytes: downloads.index?.rawBytes ?? 0,
+        totalBytes: applyResult.totalBytes,
+      };
     } finally {
       await this.removeIfPresent(packPath);
       await this.removeIfPresent(indexPath);
@@ -207,23 +213,24 @@ export class HandoffCheckpointTracker {
   }
 
   private async uploadArtifacts(specs: UploadArtifactSpec[]): Promise<Uploads> {
-    const uploads = await Promise.all(
-      specs.map(async (spec) => {
-        if (!spec.filePath) {
-          return [spec.key, undefined] as const;
-        }
-        return [
-          spec.key,
-          await this.uploadArtifactFile(
-            spec.filePath,
-            spec.name,
-            spec.contentType,
-          ),
-        ] as const;
-      }),
-    );
+    const results: Array<readonly [ArtifactKey, UploadedArtifact | undefined]> =
+      [];
+    for (const spec of specs) {
+      if (!spec.filePath) {
+        results.push([spec.key, undefined] as const);
+        continue;
+      }
+      results.push([
+        spec.key,
+        await this.uploadArtifactFile(
+          spec.filePath,
+          spec.name,
+          spec.contentType,
+        ),
+      ] as const);
+    }
 
-    return Object.fromEntries(uploads) as Uploads;
+    return Object.fromEntries(results) as Uploads;
   }
 
   private async downloadArtifactToFile(
@@ -241,9 +248,8 @@ export class HandoffCheckpointTracker {
       artifactPath,
     );
     if (!arrayBuffer) {
-      throw new Error(`Failed to download ${label}`);
+      throw new Error(`Failed to download ${label} from ${artifactPath}`);
     }
-
     const base64Content = Buffer.from(arrayBuffer).toString("utf-8");
     const binaryContent = Buffer.from(base64Content, "base64");
     await writeFile(filePath, binaryContent);

package/src/posthog-api.ts

@@ -153,6 +153,14 @@ export class PostHogAPIClient {
     );
   }
 
+  async resumeRunInCloud(taskId: string, runId: string): Promise<TaskRun> {
+    const teamId = this.getTeamId();
+    return this.apiRequest<TaskRun>(
+      `/api/projects/${teamId}/tasks/${taskId}/runs/${runId}/resume_in_cloud/`,
+      { method: "POST" },
+    );
+  }
+
   async updateTaskRun(
     taskId: string,
     runId: string,

package/src/resume.ts

@@ -30,8 +30,6 @@ export interface ResumeState {
   conversation: ConversationTurn[];
   latestSnapshot: TreeSnapshotEvent | null;
   latestGitCheckpoint: GitCheckpointEvent | null;
-  /** Whether the tree snapshot was successfully applied (files restored) */
-  snapshotApplied: boolean;
   interrupted: boolean;
   lastDevice?: DeviceInfo;
   logEntryCount: number;
@@ -61,11 +59,7 @@ export interface ResumeConfig {
 /**
  * Resume a task from its persisted log.
  * Returns the rebuilt state for the agent to continue from.
- *
- * Uses Saga pattern internally for atomic operations.
- * Note: snapshotApplied field indicates if files were actually restored -
- * even if latestSnapshot is non-null, files may not have been restored if
- * the snapshot had no archive URL or download/extraction failed.
+ * Snapshot and checkpoint application happens in the agent server after SSE connects.
  */
 export async function resumeFromLog(
   config: ResumeConfig,
@@ -102,7 +96,6 @@ export async function resumeFromLog(
     conversation: result.data.conversation as ConversationTurn[],
     latestSnapshot: result.data.latestSnapshot,
     latestGitCheckpoint: result.data.latestGitCheckpoint,
-    snapshotApplied: result.data.snapshotApplied,
     interrupted: result.data.interrupted,
     lastDevice: result.data.lastDevice,
     logEntryCount: result.data.logEntryCount,
@@ -124,15 +117,31 @@ export function conversationToPromptHistory(
 const RESUME_HISTORY_TOKEN_BUDGET = 50_000;
 const TOOL_RESULT_MAX_CHARS = 2000;
 
+const RESUME_CONTEXT_MARKERS = [
+  "You are resuming a previous conversation",
+  "Here is the conversation history from the",
+  "Continue from where you left off",
+];
+
+function isResumeContextTurn(turn: ConversationTurn): boolean {
+  if (turn.role !== "user") return false;
+  const text = turn.content
+    .filter((b) => b.type === "text")
+    .map((b) => (b as { type: "text"; text: string }).text)
+    .join("");
+  return RESUME_CONTEXT_MARKERS.some((marker) => text.includes(marker));
+}
+
 export function formatConversationForResume(
   conversation: ConversationTurn[],
 ): string {
-  const selected = selectRecentTurns(conversation, RESUME_HISTORY_TOKEN_BUDGET);
+  const filtered = conversation.filter((turn) => !isResumeContextTurn(turn));
+  const selected = selectRecentTurns(filtered, RESUME_HISTORY_TOKEN_BUDGET);
   const parts: string[] = [];
 
-  if (selected.length < conversation.length) {
+  if (selected.length < filtered.length) {
     parts.push(
-      `*(${conversation.length - selected.length} earlier turns omitted)*`,
+      `*(${filtered.length - selected.length} earlier turns omitted)*`,
     );
   }
 

package/src/sagas/resume-saga.test.ts

@@ -6,7 +6,6 @@ import { ResumeSaga } from "./resume-saga";
 import {
   createAgentChunk,
   createAgentMessage,
-  createArchiveBuffer,
   createMockApiClient,
   createMockLogger,
   createNotification,
@@ -52,7 +51,6 @@ describe("ResumeSaga", () => {
       if (result.success) {
         expect(result.data.conversation).toHaveLength(0);
         expect(result.data.latestSnapshot).toBeNull();
-        expect(result.data.snapshotApplied).toBe(false);
         expect(result.data.logEntryCount).toBe(0);
       }
     });
@@ -468,14 +466,10 @@ describe("ResumeSaga", () => {
     });
   });
 
-  describe("snapshot application", () => {
-    it("applies snapshot when archive URL present", async () => {
+  describe("snapshot metadata", () => {
+    it("returns latest snapshot metadata when archive URL present", async () => {
       const baseCommit = await repo.git(["rev-parse", "HEAD"]);
 
-      const archive = await createArchiveBuffer([
-        { path: "restored.ts", content: "restored content" },
-      ]);
-
       (mockApiClient.getTaskRun as ReturnType<typeof vi.fn>).mockResolvedValue(
         createTaskRun(),
       );
@@ -490,9 +484,6 @@ describe("ResumeSaga", () => {
           timestamp: new Date().toISOString(),
         }),
       ]);
-      (
-        mockApiClient.downloadArtifact as ReturnType<typeof vi.fn>
-      ).mockResolvedValue(archive);
 
       const saga = new ResumeSaga(mockLogger);
       const result = await saga.run({
@@ -505,13 +496,13 @@ describe("ResumeSaga", () => {
       expect(result.success).toBe(true);
       if (!result.success) return;
 
-      expect(result.data.snapshotApplied).toBe(true);
-
-      const content = await repo.readFile("restored.ts");
-      expect(content).toBe("restored content");
+      expect(result.data.latestSnapshot?.treeHash).toBe("hash-1");
+      expect(result.data.latestSnapshot?.archiveUrl).toBe(
+        "gs://bucket/hash-1.tar.gz",
+      );
     });
 
-    it("continues without snapshot when no archive URL", async () => {
+    it("returns snapshot metadata even when no archive URL", async () => {
       (mockApiClient.getTaskRun as ReturnType<typeof vi.fn>).mockResolvedValue(
         createTaskRun(),
       );
@@ -533,40 +524,9 @@ describe("ResumeSaga", () => {
       expect(result.success).toBe(true);
       if (!result.success) return;
 
-      expect(result.data.snapshotApplied).toBe(false);
       expect(result.data.latestSnapshot).not.toBeNull();
       expect(result.data.conversation).toHaveLength(1);
     });
-
-    it("continues without snapshot when apply fails", async () => {
-      (mockApiClient.getTaskRun as ReturnType<typeof vi.fn>).mockResolvedValue(
-        createTaskRun(),
-      );
-      (
-        mockApiClient.fetchTaskRunLogs as ReturnType<typeof vi.fn>
-      ).mockResolvedValue([
-        createTreeSnapshotNotification("hash-1", "gs://bucket/hash-1.tar.gz"),
-        createUserMessage("hello"),
-      ]);
-      (
-        mockApiClient.downloadArtifact as ReturnType<typeof vi.fn>
-      ).mockRejectedValue(new Error("Download failed"));
-
-      const saga = new ResumeSaga(mockLogger);
-      const result = await saga.run({
-        taskId: "task-1",
-        runId: "run-1",
-        repositoryPath: repo.path,
-        apiClient: mockApiClient,
-      });
-
-      expect(result.success).toBe(true);
-      if (!result.success) return;
-
-      expect(result.data.snapshotApplied).toBe(false);
-      expect(result.data.conversation).toHaveLength(1);
-      expect(mockLogger.warn).toHaveBeenCalled();
-    });
   });
 
   describe("device info", () => {

package/src/sagas/resume-saga.ts

@@ -2,14 +2,13 @@ import type { ContentBlock } from "@agentclientprotocol/sdk";
 import { Saga } from "@posthog/shared";
 import { isNotification, POSTHOG_NOTIFICATIONS } from "../acp-extensions";
 import type { PostHogAPIClient } from "../posthog-api";
-import { TreeTracker } from "../tree-tracker";
 import type {
   DeviceInfo,
   GitCheckpointEvent,
   StoredNotification,
   TreeSnapshotEvent,
 } from "../types";
-import { Logger } from "../utils/logger";
+import type { Logger } from "../utils/logger";
 
 export interface ConversationTurn {
   role: "user" | "assistant";
@@ -36,7 +35,6 @@ export interface ResumeOutput {
   conversation: ConversationTurn[];
   latestSnapshot: TreeSnapshotEvent | null;
   latestGitCheckpoint: GitCheckpointEvent | null;
-  snapshotApplied: boolean;
   interrupted: boolean;
   lastDevice?: DeviceInfo;
   logEntryCount: number;
@@ -46,9 +44,7 @@ export class ResumeSaga extends Saga<ResumeInput, ResumeOutput> {
   readonly sagaName = "ResumeSaga";
 
   protected async execute(input: ResumeInput): Promise<ResumeOutput> {
-    const { taskId, runId, repositoryPath, apiClient } = input;
-    const logger =
-      input.logger || new Logger({ debug: false, prefix: "[Resume]" });
+    const { taskId, runId, apiClient } = input;
 
     // Step 1: Fetch task run (read-only)
     const taskRun = await this.readOnlyStep("fetch_task_run", () =>
@@ -83,69 +79,21 @@ export class ResumeSaga extends Saga<ResumeInput, ResumeOutput> {
     );
 
     // Step 4: Apply snapshot if present (wrapped in step for consistent logging)
-    // Note: We use a try/catch inside the step because snapshot failure should NOT fail the saga
-    let snapshotApplied = false;
-    if (latestSnapshot?.archiveUrl && repositoryPath) {
+    if (latestSnapshot) {
       this.log.info("Found tree snapshot", {
         treeHash: latestSnapshot.treeHash,
-        hasArchiveUrl: true,
+        hasArchiveUrl: !!latestSnapshot.archiveUrl,
         changes: latestSnapshot.changes?.length ?? 0,
-        interrupted: latestSnapshot.interrupted,
       });
+    }
 
-      await this.step({
-        name: "apply_snapshot",
-        execute: async () => {
-          const treeTracker = new TreeTracker({
-            repositoryPath,
-            taskId,
-            runId,
-            apiClient,
-            logger: logger.child("TreeTracker"),
-          });
-
-          try {
-            await treeTracker.applyTreeSnapshot(latestSnapshot);
-            treeTracker.setLastTreeHash(latestSnapshot.treeHash);
-            snapshotApplied = true;
-            this.log.info("Tree snapshot applied successfully", {
-              treeHash: latestSnapshot.treeHash,
-            });
-          } catch (error) {
-            // Log but don't fail - continue with conversation rebuild
-            // ApplySnapshotSaga handles its own rollback internally
-            this.log.warn(
-              "Failed to apply tree snapshot, continuing without it",
-              {
-                error: error instanceof Error ? error.message : String(error),
-                treeHash: latestSnapshot.treeHash,
-              },
-            );
-          }
-        },
-        rollback: async () => {
-          // Inner ApplySnapshotSaga handles its own rollback
-        },
+    if (latestGitCheckpoint) {
+      this.log.info("Found git checkpoint", {
+        checkpointId: latestGitCheckpoint.checkpointId,
+        branch: latestGitCheckpoint.branch,
       });
-    } else if (latestSnapshot?.archiveUrl && !repositoryPath) {
-      this.log.warn(
-        "Snapshot found but no repositoryPath configured - files cannot be restored",
-        {
-          treeHash: latestSnapshot.treeHash,
-          changes: latestSnapshot.changes?.length ?? 0,
-        },
-      );
-    } else if (latestSnapshot) {
-      this.log.warn(
-        "Snapshot found but has no archive URL - files cannot be restored",
-        {
-          treeHash: latestSnapshot.treeHash,
-          changes: latestSnapshot.changes?.length ?? 0,
-        },
-      );
     }
 
-    // Step 5: Rebuild conversation (read-only, pure computation)
     const conversation = await this.readOnlyStep("rebuild_conversation", () =>
       Promise.resolve(this.rebuildConversation(entries)),
     );
@@ -158,7 +106,7 @@ export class ResumeSaga extends Saga<ResumeInput, ResumeOutput> {
     this.log.info("Resume state rebuilt", {
       turns: conversation.length,
       hasSnapshot: !!latestSnapshot,
-      snapshotApplied,
+      hasGitCheckpoint: !!latestGitCheckpoint,
       interrupted: latestSnapshot?.interrupted ?? false,
     });
 
@@ -166,7 +114,6 @@ export class ResumeSaga extends Saga<ResumeInput, ResumeOutput> {
       conversation,
       latestSnapshot,
       latestGitCheckpoint,
-      snapshotApplied,
       interrupted: latestSnapshot?.interrupted ?? false,
       lastDevice,
       logEntryCount: entries.length,
@@ -178,7 +125,6 @@ export class ResumeSaga extends Saga<ResumeInput, ResumeOutput> {
       conversation: [],
       latestSnapshot: null,
       latestGitCheckpoint: null,
-      snapshotApplied: false,
       interrupted: false,
       logEntryCount: 0,
     };

package/src/server/agent-server.ts

@@ -478,50 +478,34 @@ export class AgentServer {
     await this.autoInitializeSession();
   }
 
-  private async autoInitializeSession(): Promise<void> {
-    const { taskId, runId, mode, projectId } = this.config;
-
-    this.logger.debug("Auto-initializing session", { taskId, runId, mode });
-
-    // Check if this is a resume from a previous run
-    const resumeRunId = process.env.POSTHOG_RESUME_RUN_ID;
-    if (resumeRunId) {
-      this.logger.debug("Resuming from previous run", {
-        resumeRunId,
-        currentRunId: runId,
+  private async loadResumeState(
+    taskId: string,
+    resumeRunId: string,
+    currentRunId: string,
+  ): Promise<void> {
+    this.logger.debug("Loading resume state", { resumeRunId, currentRunId });
+    try {
+      this.resumeState = await resumeFromLog({
+        taskId,
+        runId: resumeRunId,
+        repositoryPath: this.config.repositoryPath,
+        apiClient: this.posthogAPI,
+        logger: new Logger({ debug: true, prefix: "[Resume]" }),
       });
-      try {
-        this.resumeState = await resumeFromLog({
-          taskId,
-          runId: resumeRunId,
-          repositoryPath: this.config.repositoryPath,
-          apiClient: this.posthogAPI,
-          logger: new Logger({ debug: true, prefix: "[Resume]" }),
-        });
-        this.logger.debug("Resume state loaded", {
-          conversationTurns: this.resumeState.conversation.length,
-          snapshotApplied: this.resumeState.snapshotApplied,
-          logEntries: this.resumeState.logEntryCount,
-        });
-      } catch (error) {
-        this.logger.debug("Failed to load resume state, starting fresh", {
-          error,
-        });
-        this.resumeState = null;
-      }
+      this.logger.debug("Resume state loaded", {
+        conversationTurns: this.resumeState.conversation.length,
+        hasSnapshot: !!this.resumeState.latestSnapshot,
+        hasGitCheckpoint: !!this.resumeState.latestGitCheckpoint,
+        gitCheckpointBranch:
+          this.resumeState.latestGitCheckpoint?.branch ?? null,
+        logEntries: this.resumeState.logEntryCount,
+      });
+    } catch (error) {
+      this.logger.debug("Failed to load resume state, starting fresh", {
+        error,
+      });
+      this.resumeState = null;
     }
-
-    // Create a synthetic payload from config (no JWT needed for auto-init)
-    const payload: JwtPayload = {
-      task_id: taskId,
-      run_id: runId,
-      team_id: projectId,
-      user_id: 0, // System-initiated
-      distinct_id: "agent-server",
-      mode,
-    };
-
-    await this.initializeSession(payload, null);
   }
 
   async stop(): Promise<void> {
@@ -1057,33 +1041,14 @@ export class AgentServer {
       }
     }
 
-    // Check for resume if not already loaded from env var in autoInitializeSession
     if (!this.resumeState) {
       const resumeRunId = this.getResumeRunId(taskRun);
       if (resumeRunId) {
-        this.logger.debug("Resuming from previous run (via TaskRun state)", {
+        await this.loadResumeState(
+          payload.task_id,
           resumeRunId,
-          currentRunId: payload.run_id,
-        });
-        try {
-          this.resumeState = await resumeFromLog({
-            taskId: payload.task_id,
-            runId: resumeRunId,
-            repositoryPath: this.config.repositoryPath,
-            apiClient: this.posthogAPI,
-            logger: new Logger({ debug: true, prefix: "[Resume]" }),
-          });
-          this.logger.debug("Resume state loaded (via TaskRun state)", {
-            conversationTurns: this.resumeState.conversation.length,
-            snapshotApplied: this.resumeState.snapshotApplied,
-            logEntries: this.resumeState.logEntryCount,
-          });
-        } catch (error) {
-          this.logger.debug("Failed to load resume state, starting fresh", {
-            error,
-          });
-          this.resumeState = null;
-        }
+          payload.run_id,
+        );
       }
     }
 
@@ -1163,11 +1128,70 @@ export class AgentServer {
         this.resumeState.conversation,
       );
 
-      // Read the pending user prompt from TaskRun state (set by the workflow
-      // when the user sends a follow-up message that triggers a resume).
+      let snapshotApplied = false;
+      if (
+        this.resumeState.latestSnapshot?.archiveUrl &&
+        this.config.repositoryPath &&
+        this.posthogAPI
+      ) {
+        try {
+          const treeTracker = new TreeTracker({
+            repositoryPath: this.config.repositoryPath,
+            taskId: payload.task_id,
+            runId: payload.run_id,
+            apiClient: this.posthogAPI,
+            logger: this.logger.child("TreeTracker"),
+          });
+          await treeTracker.applyTreeSnapshot(this.resumeState.latestSnapshot);
+          treeTracker.setLastTreeHash(this.resumeState.latestSnapshot.treeHash);
+          snapshotApplied = true;
+          this.logger.info("Tree snapshot applied", {
+            treeHash: this.resumeState.latestSnapshot.treeHash,
+            changes: this.resumeState.latestSnapshot.changes?.length ?? 0,
+            hasArchiveUrl: !!this.resumeState.latestSnapshot.archiveUrl,
+          });
+        } catch (error) {
+          this.logger.warn("Failed to apply tree snapshot", {
+            error: error instanceof Error ? error.message : String(error),
+            treeHash: this.resumeState.latestSnapshot.treeHash,
+          });
+        }
+      }
+
+      if (
+        this.resumeState.latestGitCheckpoint &&
+        this.config.repositoryPath &&
+        this.posthogAPI
+      ) {
+        try {
+          const checkpointTracker = new HandoffCheckpointTracker({
+            repositoryPath: this.config.repositoryPath,
+            taskId: payload.task_id,
+            runId: payload.run_id,
+            apiClient: this.posthogAPI,
+            logger: this.logger.child("HandoffCheckpoint"),
+          });
+          const metrics = await checkpointTracker.applyFromHandoff(
+            this.resumeState.latestGitCheckpoint,
+          );
+          this.logger.info("Git checkpoint applied", {
+            branch: this.resumeState.latestGitCheckpoint.branch,
+            head: this.resumeState.latestGitCheckpoint.head,
+            packBytes: metrics.packBytes,
+            indexBytes: metrics.indexBytes,
+            totalBytes: metrics.totalBytes,
+          });
+        } catch (error) {
+          this.logger.warn("Failed to apply git checkpoint", {
+            error: error instanceof Error ? error.message : String(error),
+            branch: this.resumeState.latestGitCheckpoint.branch,
+          });
+        }
+      }
+
       const pendingUserPrompt = await this.getPendingUserPrompt(taskRun);
 
-      const sandboxContext = this.resumeState.snapshotApplied
+      const sandboxContext = snapshotApplied
         ? `The workspace environment (all files, packages, and code changes) has been fully restored from where you left off.`
         : `The workspace files from the previous session were not restored (the file snapshot may have expired), so you are starting with a fresh environment. Your conversation history is fully preserved below.`;
 
@@ -1206,7 +1230,10 @@ export class AgentServer {
         conversationTurns: this.resumeState.conversation.length,
         promptLength: promptBlocksToText(resumePromptBlocks).length,
         hasPendingUserMessage: !!pendingUserPrompt?.length,
-        snapshotApplied: this.resumeState.snapshotApplied,
+        snapshotApplied,
+        hasGitCheckpoint: !!this.resumeState.latestGitCheckpoint,
+        gitCheckpointBranch:
+          this.resumeState.latestGitCheckpoint?.branch ?? null,
       });
 
       // Clear resume state so it's not reused
@@ -1434,6 +1461,29 @@ export class AgentServer {
     return normalizedName.length > 0 ? normalizedName : "attachment";
   }
 
+  private async autoInitializeSession(): Promise<void> {
+    const { taskId, runId, mode, projectId } = this.config;
+
+    this.logger.debug("Auto-initializing session", { taskId, runId, mode });
+
+    const resumeRunId = process.env.POSTHOG_RESUME_RUN_ID;
+    if (resumeRunId) {
+      await this.loadResumeState(taskId, resumeRunId, runId);
+    }
+
+    // Create a synthetic payload from config (no JWT needed for auto-init)
+    const payload: JwtPayload = {
+      task_id: taskId,
+      run_id: runId,
+      team_id: projectId,
+      user_id: 0, // System-initiated
+      distinct_id: "agent-server",
+      mode,
+    };
+
+    await this.initializeSession(payload, null);
+  }
+
   private getResumeRunId(taskRun: TaskRun | null): string | null {
     // Env var takes precedence (set by backend infra)
     const envRunId = process.env.POSTHOG_RESUME_RUN_ID;