@posthog/agent 2.3.386 → 2.3.388

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,
@@ -230,7 +238,11 @@ export class PostHogAPIClient {
       },
     );
 
-    return response.artifacts ?? [];
+    const manifest = response.artifacts ?? [];
+
+    // The backend returns the full run artifact manifest after each upload.
+    // Callers want the artifacts corresponding to this upload request only.
+    return manifest.slice(-artifacts.length);
   }
 
   /**

package/src/resume.ts

@@ -19,14 +19,17 @@ import type { ContentBlock } from "@agentclientprotocol/sdk";
 import { selectRecentTurns } from "./adapters/claude/session/jsonl-hydration";
 import type { PostHogAPIClient } from "./posthog-api";
 import { ResumeSaga } from "./sagas/resume-saga";
-import type { DeviceInfo, TreeSnapshotEvent } from "./types";
+import type {
+  DeviceInfo,
+  GitCheckpointEvent,
+  TreeSnapshotEvent,
+} from "./types";
 import { Logger } from "./utils/logger";
 
 export interface ResumeState {
   conversation: ConversationTurn[];
   latestSnapshot: TreeSnapshotEvent | null;
-  /** Whether the tree snapshot was successfully applied (files restored) */
-  snapshotApplied: boolean;
+  latestGitCheckpoint: GitCheckpointEvent | null;
   interrupted: boolean;
   lastDevice?: DeviceInfo;
   logEntryCount: number;
@@ -56,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,
@@ -96,7 +95,7 @@ export async function resumeFromLog(
   return {
     conversation: result.data.conversation as ConversationTurn[],
     latestSnapshot: result.data.latestSnapshot,
-    snapshotApplied: result.data.snapshotApplied,
+    latestGitCheckpoint: result.data.latestGitCheckpoint,
     interrupted: result.data.interrupted,
     lastDevice: result.data.lastDevice,
     logEntryCount: result.data.logEntryCount,
@@ -118,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/apply-snapshot-saga.ts

@@ -59,6 +59,13 @@ export class ApplySnapshotSaga extends Saga<
         const base64Content = Buffer.from(arrayBuffer).toString("utf-8");
         const binaryContent = Buffer.from(base64Content, "base64");
         await writeFile(archivePath, binaryContent);
+        this.log.info("Tree archive downloaded", {
+          treeHash: snapshot.treeHash,
+          snapshotBytes: binaryContent.byteLength,
+          snapshotWireBytes: arrayBuffer.byteLength,
+          totalBytes: binaryContent.byteLength,
+          totalWireBytes: arrayBuffer.byteLength,
+        });
       },
       rollback: async () => {
         if (this.archivePath) {

package/src/sagas/capture-tree-saga.ts

@@ -113,6 +113,8 @@ export class CaptureTreeSaga extends Saga<CaptureTreeInput, CaptureTreeOutput> {
       execute: async () => {
         const archiveContent = await readFile(archivePath);
         const base64Content = archiveContent.toString("base64");
+        const snapshotBytes = archiveContent.byteLength;
+        const snapshotWireBytes = Buffer.byteLength(base64Content, "utf-8");
 
         const artifacts = await apiClient.uploadTaskArtifacts(taskId, runId, [
           {
@@ -123,12 +125,17 @@ export class CaptureTreeSaga extends Saga<CaptureTreeInput, CaptureTreeOutput> {
           },
         ]);
 
-        if (artifacts.length > 0 && artifacts[0].storage_path) {
+        const uploadedArtifact = artifacts[0];
+        if (uploadedArtifact?.storage_path) {
           this.log.info("Tree archive uploaded", {
-            storagePath: artifacts[0].storage_path,
+            storagePath: uploadedArtifact.storage_path,
             treeHash,
+            snapshotBytes,
+            snapshotWireBytes,
+            totalBytes: snapshotBytes,
+            totalWireBytes: snapshotWireBytes,
           });
-          return artifacts[0].storage_path;
+          return uploadedArtifact.storage_path;
         }
 
         return undefined;

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,13 +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";
@@ -34,7 +34,7 @@ export interface ResumeInput {
 export interface ResumeOutput {
   conversation: ConversationTurn[];
   latestSnapshot: TreeSnapshotEvent | null;
-  snapshotApplied: boolean;
+  latestGitCheckpoint: GitCheckpointEvent | null;
   interrupted: boolean;
   lastDevice?: DeviceInfo;
   logEntryCount: number;
@@ -44,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", () =>
@@ -75,70 +73,27 @@ export class ResumeSaga extends Saga<ResumeInput, ResumeOutput> {
       Promise.resolve(this.findLatestTreeSnapshot(entries)),
     );
 
+    const latestGitCheckpoint = await this.readOnlyStep(
+      "find_git_checkpoint",
+      () => Promise.resolve(this.findLatestGitCheckpoint(entries)),
+    );
+
     // 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)),
     );
@@ -151,14 +106,14 @@ 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,
     });
 
     return {
       conversation,
       latestSnapshot,
-      snapshotApplied,
+      latestGitCheckpoint,
       interrupted: latestSnapshot?.interrupted ?? false,
       lastDevice,
       logEntryCount: entries.length,
@@ -169,7 +124,7 @@ export class ResumeSaga extends Saga<ResumeInput, ResumeOutput> {
     return {
       conversation: [],
       latestSnapshot: null,
-      snapshotApplied: false,
+      latestGitCheckpoint: null,
       interrupted: false,
       logEntryCount: 0,
     };
@@ -197,6 +152,29 @@ export class ResumeSaga extends Saga<ResumeInput, ResumeOutput> {
     return null;
   }
 
+  private findLatestGitCheckpoint(
+    entries: StoredNotification[],
+  ): GitCheckpointEvent | null {
+    const sdkPrefixedMethod = `_${POSTHOG_NOTIFICATIONS.GIT_CHECKPOINT}`;
+
+    for (let i = entries.length - 1; i >= 0; i--) {
+      const entry = entries[i];
+      const method = entry.notification?.method;
+      if (
+        method === sdkPrefixedMethod ||
+        method === POSTHOG_NOTIFICATIONS.GIT_CHECKPOINT
+      ) {
+        const params = entry.notification?.params as
+          | GitCheckpointEvent
+          | undefined;
+        if (params?.checkpointId && params?.checkpointRef) {
+          return params;
+        }
+      }
+    }
+    return null;
+  }
+
   private findLastDeviceInfo(
     entries: StoredNotification[],
   ): DeviceInfo | undefined {

package/src/sagas/test-fixtures.ts

@@ -67,6 +67,52 @@ export async function createTestRepo(prefix = "test-repo"): Promise<TestRepo> {
   };
 }
 
+export async function cloneTestRepo(
+  sourcePath: string,
+  prefix = "test-repo-clone",
+): Promise<TestRepo> {
+  const clonePath = join(
+    tmpdir(),
+    `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+  );
+  await execFileAsync("git", ["clone", sourcePath, clonePath]);
+  await execFileAsync("git", ["config", "user.email", "test@test.com"], {
+    cwd: clonePath,
+  });
+  await execFileAsync("git", ["config", "user.name", "Test"], {
+    cwd: clonePath,
+  });
+  await execFileAsync("git", ["config", "commit.gpgsign", "false"], {
+    cwd: clonePath,
+  });
+
+  const git = async (args: string[]): Promise<string> => {
+    const { stdout } = await execFileAsync("git", args, { cwd: clonePath });
+    return stdout.trim();
+  };
+
+  return {
+    path: clonePath,
+    cleanup: () => rm(clonePath, { recursive: true, force: true }),
+    git,
+    writeFile: async (relativePath: string, content: string) => {
+      const fullPath = join(clonePath, relativePath);
+      const dir = join(fullPath, "..");
+      await mkdir(dir, { recursive: true });
+      await writeFile(fullPath, content);
+    },
+    readFile: async (relativePath: string) => {
+      return readFile(join(clonePath, relativePath), "utf-8");
+    },
+    deleteFile: async (relativePath: string) => {
+      await rm(join(clonePath, relativePath), { force: true });
+    },
+    exists: (relativePath: string) => {
+      return existsSync(join(clonePath, relativePath));
+    },
+  };
+}
+
 export function createMockLogger(): SagaLogger {
   return {
     info: vi.fn(),