@posthog/agent 2.3.385 → 2.3.387

package/src/resume.ts

@@ -16,14 +16,20 @@
  */
 
 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;
+  latestGitCheckpoint: GitCheckpointEvent | null;
   /** Whether the tree snapshot was successfully applied (files restored) */
   snapshotApplied: boolean;
   interrupted: boolean;
@@ -95,6 +101,7 @@ export async function resumeFromLog(
   return {
     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,
@@ -113,3 +120,53 @@ export function conversationToPromptHistory(
     content: turn.content,
   }));
 }
+
+const RESUME_HISTORY_TOKEN_BUDGET = 50_000;
+const TOOL_RESULT_MAX_CHARS = 2000;
+
+export function formatConversationForResume(
+  conversation: ConversationTurn[],
+): string {
+  const selected = selectRecentTurns(conversation, RESUME_HISTORY_TOKEN_BUDGET);
+  const parts: string[] = [];
+
+  if (selected.length < conversation.length) {
+    parts.push(
+      `*(${conversation.length - selected.length} earlier turns omitted)*`,
+    );
+  }
+
+  for (const turn of selected) {
+    const role = turn.role === "user" ? "User" : "Assistant";
+
+    const textParts = turn.content
+      .filter((block) => block.type === "text")
+      .map((block) => (block as { type: "text"; text: string }).text);
+
+    if (textParts.length > 0) {
+      parts.push(`**${role}**: ${textParts.join("\n")}`);
+    }
+
+    if (turn.toolCalls?.length) {
+      const toolSummary = turn.toolCalls
+        .map((tc) => {
+          let resultStr = "";
+          if (tc.result !== undefined) {
+            const raw =
+              typeof tc.result === "string"
+                ? tc.result
+                : JSON.stringify(tc.result);
+            resultStr =
+              raw.length > TOOL_RESULT_MAX_CHARS
+                ? ` → ${raw.substring(0, TOOL_RESULT_MAX_CHARS)}...(truncated)`
+                : ` → ${raw}`;
+          }
+          return `  - ${tc.toolName}${resultStr}`;
+        })
+        .join("\n");
+      parts.push(`**${role} (tools)**:\n${toolSummary}`);
+    }
+  }
+
+  return parts.join("\n\n");
+}

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.ts

@@ -5,6 +5,7 @@ import type { PostHogAPIClient } from "../posthog-api";
 import { TreeTracker } from "../tree-tracker";
 import type {
   DeviceInfo,
+  GitCheckpointEvent,
   StoredNotification,
   TreeSnapshotEvent,
 } from "../types";
@@ -34,6 +35,7 @@ export interface ResumeInput {
 export interface ResumeOutput {
   conversation: ConversationTurn[];
   latestSnapshot: TreeSnapshotEvent | null;
+  latestGitCheckpoint: GitCheckpointEvent | null;
   snapshotApplied: boolean;
   interrupted: boolean;
   lastDevice?: DeviceInfo;
@@ -75,6 +77,11 @@ 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;
@@ -158,6 +165,7 @@ export class ResumeSaga extends Saga<ResumeInput, ResumeOutput> {
     return {
       conversation,
       latestSnapshot,
+      latestGitCheckpoint,
       snapshotApplied,
       interrupted: latestSnapshot?.interrupted ?? false,
       lastDevice,
@@ -169,6 +177,7 @@ export class ResumeSaga extends Saga<ResumeInput, ResumeOutput> {
     return {
       conversation: [],
       latestSnapshot: null,
+      latestGitCheckpoint: null,
       snapshotApplied: false,
       interrupted: false,
       logEntryCount: 0,
@@ -197,6 +206,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(),

package/src/server/agent-server.ts

@@ -25,12 +25,12 @@ import {
   type AgentErrorClassification,
   classifyAgentError,
 } from "../adapters/claude/conversion/sdk-to-acp";
-import { selectRecentTurns } from "../adapters/claude/session/jsonl-hydration";
 import type { PermissionMode } from "../execution-mode";
 import { DEFAULT_CODEX_MODEL } from "../gateway-models";
+import { HandoffCheckpointTracker } from "../handoff-checkpoint";
 import { PostHogAPIClient } from "../posthog-api";
 import {
-  type ConversationTurn,
+  formatConversationForResume,
   type ResumeState,
   resumeFromLog,
 } from "../resume";
@@ -39,6 +39,8 @@ import { TreeTracker } from "../tree-tracker";
 import type {
   AgentMode,
   DeviceInfo,
+  GitCheckpointEvent,
+  HandoffLocalGitState,
   LogLevel,
   TaskRun,
   TaskRunArtifact,
@@ -53,7 +55,11 @@ import {
   promptBlocksToText,
 } from "./cloud-prompt";
 import { type JwtPayload, JwtValidationError, validateJwt } from "./jwt";
-import { jsonRpcRequestSchema, validateCommandParams } from "./schemas";
+import {
+  handoffLocalGitStateSchema,
+  jsonRpcRequestSchema,
+  validateCommandParams,
+} from "./schemas";
 import type { AgentServerConfig } from "./types";
 
 const agentErrorClassificationSchema = z.enum([
@@ -186,6 +192,7 @@ interface ActiveSession {
   permissionMode: PermissionMode;
   /** Whether a desktop client has ever connected via SSE during this session */
   hasDesktopConnected: boolean;
+  pendingHandoffGitState?: HandoffLocalGitState;
 }
 
 function getTaskRunStateString(
@@ -662,6 +669,10 @@ export class AgentServer {
       case POSTHOG_NOTIFICATIONS.CLOSE:
       case "close": {
         this.logger.debug("Close requested");
+        const localGitState = this.extractHandoffLocalGitState(params);
+        if (localGitState && this.session) {
+          this.session.pendingHandoffGitState = localGitState;
+        }
         await this.cleanupSession();
         return { closed: true };
       }
@@ -959,6 +970,7 @@ export class AgentServer {
       logWriter,
       permissionMode: initialPermissionMode,
       hasDesktopConnected: sseController !== null,
+      pendingHandoffGitState: undefined,
     };
 
     this.logger = new Logger({
@@ -1147,7 +1159,7 @@ export class AgentServer {
     if (!this.session || !this.resumeState) return;
 
     try {
-      const conversationSummary = this.formatConversationForResume(
+      const conversationSummary = formatConversationForResume(
         this.resumeState.conversation,
       );
 
@@ -1229,59 +1241,6 @@ export class AgentServer {
     }
   }
 
-  private static RESUME_HISTORY_TOKEN_BUDGET = 50_000;
-  private static TOOL_RESULT_MAX_CHARS = 2000;
-
-  private formatConversationForResume(
-    conversation: ConversationTurn[],
-  ): string {
-    const selected = selectRecentTurns(
-      conversation,
-      AgentServer.RESUME_HISTORY_TOKEN_BUDGET,
-    );
-    const parts: string[] = [];
-
-    if (selected.length < conversation.length) {
-      parts.push(
-        `*(${conversation.length - selected.length} earlier turns omitted)*`,
-      );
-    }
-
-    for (const turn of selected) {
-      const role = turn.role === "user" ? "User" : "Assistant";
-
-      const textParts = turn.content
-        .filter((block) => block.type === "text")
-        .map((block) => (block as { type: "text"; text: string }).text);
-
-      if (textParts.length > 0) {
-        parts.push(`**${role}**: ${textParts.join("\n")}`);
-      }
-
-      if (turn.toolCalls?.length) {
-        const toolSummary = turn.toolCalls
-          .map((tc) => {
-            let resultStr = "";
-            if (tc.result !== undefined) {
-              const raw =
-                typeof tc.result === "string"
-                  ? tc.result
-                  : JSON.stringify(tc.result);
-              resultStr =
-                raw.length > AgentServer.TOOL_RESULT_MAX_CHARS
-                  ? ` → ${raw.substring(0, AgentServer.TOOL_RESULT_MAX_CHARS)}...(truncated)`
-                  : ` → ${raw}`;
-            }
-            return `  - ${tc.toolName}${resultStr}`;
-          })
-          .join("\n");
-        parts.push(`**${role} (tools)**:\n${toolSummary}`);
-      }
-    }
-
-    return parts.join("\n\n");
-  }
-
   private getInitialPromptOverride(taskRun: TaskRun): string | null {
     const state = taskRun.state as Record<string, unknown> | undefined;
     const override = state?.initial_prompt_override;
@@ -2158,6 +2117,12 @@ ${attributionInstructions}
 
     this.logger.debug("Cleaning up session");
 
+    try {
+      await this.captureHandoffCheckpoint();
+    } catch (error) {
+      this.logger.error("Failed to capture handoff checkpoint", error);
+    }
+
     try {
       await this.captureTreeState();
     } catch (error) {
@@ -2234,6 +2199,60 @@ ${attributionInstructions}
     }
   }
 
+  private async captureHandoffCheckpoint(): Promise<void> {
+    if (!this.session?.treeTracker || !this.session.pendingHandoffGitState) {
+      return;
+    }
+    if (!this.posthogAPI) {
+      this.logger.warn(
+        "Skipping handoff checkpoint capture: PostHog API client is not configured",
+      );
+      return;
+    }
+
+    const tracker = new HandoffCheckpointTracker({
+      repositoryPath: this.config.repositoryPath ?? "/tmp/workspace",
+      taskId: this.session.payload.task_id,
+      runId: this.session.payload.run_id,
+      apiClient: this.posthogAPI,
+      logger: this.logger.child("HandoffCheckpoint"),
+    });
+
+    const checkpoint = await tracker.captureForHandoff(
+      this.session.pendingHandoffGitState,
+    );
+    if (!checkpoint) return;
+
+    const checkpointWithDevice: GitCheckpointEvent = {
+      ...checkpoint,
+      device: this.session.deviceInfo,
+    };
+
+    const notification = {
+      jsonrpc: "2.0" as const,
+      method: POSTHOG_NOTIFICATIONS.GIT_CHECKPOINT,
+      params: checkpointWithDevice,
+    };
+
+    this.broadcastEvent({
+      type: "notification",
+      timestamp: new Date().toISOString(),
+      notification,
+    });
+
+    this.session.logWriter.appendRawLine(
+      this.session.payload.run_id,
+      JSON.stringify(notification),
+    );
+  }
+
+  private extractHandoffLocalGitState(
+    params: Record<string, unknown>,
+  ): HandoffLocalGitState | null {
+    const result = handoffLocalGitStateSchema.safeParse(params.localGitState);
+    return result.success ? result.data : null;
+  }
+
   private broadcastTurnComplete(stopReason: string): void {
     if (!this.session) return;
     this.broadcastEvent({

package/src/server/schemas.ts

@@ -5,6 +5,19 @@ const httpHeaderSchema = z.object({
   value: z.string(),
 });
 
+const nullishString = z
+  .string()
+  .nullish()
+  .transform((value) => value ?? null);
+
+export const handoffLocalGitStateSchema = z.object({
+  head: nullishString,
+  branch: nullishString,
+  upstreamHead: nullishString,
+  upstreamRemote: nullishString,
+  upstreamMergeRef: nullishString,
+});
+
 const remoteMcpServerSchema = z.object({
   type: z.enum(["http", "sse"]),
   name: z.string().min(1, "MCP server name is required"),
@@ -83,13 +96,19 @@ export const refreshSessionParamsSchema = z.object({
   mcpServers: mcpServersSchema,
 });
 
+export const closeParamsSchema = z
+  .object({
+    localGitState: handoffLocalGitStateSchema.optional(),
+  })
+  .optional();
+
 export const commandParamsSchemas = {
   user_message: userMessageParamsSchema,
   "posthog/user_message": userMessageParamsSchema,
   cancel: z.object({}).optional(),
   "posthog/cancel": z.object({}).optional(),
-  close: z.object({}).optional(),
-  "posthog/close": z.object({}).optional(),
+  close: closeParamsSchema,
+  "posthog/close": closeParamsSchema,
   permission_response: permissionResponseParamsSchema,
   "posthog/permission_response": permissionResponseParamsSchema,
   set_config_option: setConfigOptionParamsSchema,

package/src/types.ts

@@ -1,3 +1,8 @@
+import type {
+  GitHandoffCheckpoint,
+  HandoffLocalGitState as GitHandoffLocalGitState,
+} from "@posthog/git/handoff";
+
 /**
  * Stored custom notification following ACP extensibility model.
  * Custom notifications use underscore-prefixed methods (e.g., `_posthog/phase_start`).
@@ -196,3 +201,22 @@ export interface TreeSnapshot {
 export interface TreeSnapshotEvent extends TreeSnapshot {
   device?: DeviceInfo;
 }
+
+export type HandoffLocalGitState = GitHandoffLocalGitState;
+
+export interface GitCheckpoint extends GitHandoffCheckpoint {
+  artifactPath?: string;
+  indexArtifactPath?: string;
+}
+
+export interface GitCheckpointEvent extends GitCheckpoint {
+  device?: DeviceInfo;
+}
+
+/**
+ * Keeps the emitted `@posthog/agent/types` entrypoint as a runtime ESM module.
+ *
+ * `export {}` is stripped by tsup in this package, which leaves `dist/types.js`
+ * empty and breaks downstream type resolution for the exported subpath.
+ */
+export const AGENT_TYPES_MODULE = true;