@posthog/agent 2.3.386 → 2.3.388

package/src/server/agent-server.ts

@@ -27,6 +27,7 @@ import {
 } from "../adapters/claude/conversion/sdk-to-acp";
 import type { PermissionMode } from "../execution-mode";
 import { DEFAULT_CODEX_MODEL } from "../gateway-models";
+import { HandoffCheckpointTracker } from "../handoff-checkpoint";
 import { PostHogAPIClient } from "../posthog-api";
 import {
   formatConversationForResume,
@@ -38,6 +39,8 @@ import { TreeTracker } from "../tree-tracker";
 import type {
   AgentMode,
   DeviceInfo,
+  GitCheckpointEvent,
+  HandoffLocalGitState,
   LogLevel,
   TaskRun,
   TaskRunArtifact,
@@ -52,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([
@@ -185,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(
@@ -470,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> {
@@ -661,6 +653,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 };
       }
@@ -958,6 +954,7 @@ export class AgentServer {
       logWriter,
       permissionMode: initialPermissionMode,
       hasDesktopConnected: sseController !== null,
+      pendingHandoffGitState: undefined,
     };
 
     this.logger = new Logger({
@@ -1044,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,
+        );
       }
     }
 
@@ -1150,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.`;
 
@@ -1193,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
@@ -1421,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;
@@ -2104,6 +2167,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) {
@@ -2180,6 +2249,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;