@posthog/agent 2.3.398 → 2.3.403

package/README.md

@@ -59,7 +59,7 @@ The same ACP agent runs in both contexts. The difference is how it's connected:
 
 **Local (PostHog Code desktop):** The agent runs in-process. PostHog Code calls `createAcpConnection()` directly — no HTTP server, no JWT. The bidirectional ACP streams connect client ↔ agent within the same process.
 
-**TreeTracker** handles the bridge between these contexts: it captures the git working tree as snapshots (tree hash + file archive) so work can be transferred between cloud and local. This enables the "hand off" flow — start locally, continue in cloud, or vice versa. Tree snapshots use the Saga pattern (`src/sagas/`) for atomic operations with automatic rollback on failure.
+**HandoffCheckpointTracker** handles the bridge between these contexts: it captures git checkpoint state plus the object pack/index needed to restore the worktree across cloud and local. This enables the "hand off" flow — start locally, continue in cloud, or vice versa.
 
 ### Permission modes
 
@@ -108,7 +108,7 @@ start()
        ├─ Creates synthetic JwtPayload from CLI config
        ├─ configureEnvironment() — sets ANTHROPIC_BASE_URL, OPENAI_BASE_URL, etc.
        │    pointing at the PostHog LLM gateway
-       ├─ Creates TreeTracker, SessionLogWriter, PostHogAPIClient
+       ├─ Creates HandoffCheckpointTracker, SessionLogWriter, PostHogAPIClient
        ├─ createAcpConnection() — sets up ACP streams with log tapping
        │
        ├─ Wraps client streams with a SECOND tap layer (NdJsonTap)
@@ -144,9 +144,9 @@ When `POST /command` receives a `user_message`, it doesn't handle it directly
 
 The `AgentServer` provides a `requestPermission` callback to the `ClientSideConnection` that always selects the "allow" option. In background mode this is necessary (no human to ask). In interactive mode it currently does the same, with a TODO for future per-tool approval via SSE round-trips.
 
-### Tree state capture
+### Checkpoint capture
 
-After every `Write` or `Edit` tool call, the server captures a git tree snapshot via `TreeTracker` and broadcasts it as a `_posthog/tree_snapshot` SSE event. A final snapshot is captured during session cleanup. This is how the client knows what files changed and can restore state for cloud↔local handoff.
+After file-mutating tool calls, the server captures a git checkpoint via `HandoffCheckpointTracker` and broadcasts it as a `_posthog/git_checkpoint` SSE event. A final checkpoint is captured during session cleanup. This is how the client restores repo state for cloud↔local handoff.
 
 ### CLI
 
@@ -200,7 +200,7 @@ For Codex adapters, `agent.run()` also fetches available models from the PostHog
 
 ## Log pipeline and session resume
 
-Logs serve two purposes: real-time observability and session resume. Every ACP message that flows through the tapped streams is persisted, creating a complete record of the conversation — user messages, agent responses, tool calls, tool results, tree snapshots, and metadata events. This record is the single source of truth for resuming a session from any point.
+Logs serve two purposes: real-time observability and session resume. Every ACP message that flows through the tapped streams is persisted, creating a complete record of the conversation — user messages, agent responses, tool calls, tool results, git checkpoints, and metadata events. This record is the single source of truth for resuming a session from any point.
 
 ### Writing logs
 
@@ -218,10 +218,9 @@ When a session needs to continue (e.g. cloud↔local handoff, or recovering from
 ```text
 1. fetch_task_run   → GET /api/.../runs/{runId}/ to find the log_url
 2. fetch_logs       → Download all StoredNotification entries
-3. find_snapshot    → Scan backwards for latest _posthog/tree_snapshot
-4. apply_snapshot   → Download archive from snapshot URL, restore working tree
-5. rebuild_conversation → Walk log entries to reconstruct conversation turns
-6. find_device      → Scan backwards for last device info (local vs cloud)
+3. find_git_checkpoint → Scan backwards for latest _posthog/git_checkpoint
+4. rebuild_conversation → Walk log entries to reconstruct conversation turns
+5. find_device      → Scan backwards for last device info (local vs cloud)
 ```
 
 The conversation rebuild (`rebuildConversation`) walks the log entries and reassembles turns from ACP `session/update` notifications:
@@ -231,9 +230,7 @@ The conversation rebuild (`rebuildConversation`) walks the log entries and reass
 - `tool_call` / `tool_call_update` → track tool calls with their inputs
 - `tool_result` → match results back to tool calls by `toolCallId`
 
-The result is a `ResumeState` containing the conversation history as `ConversationTurn[]`, the latest tree snapshot, and metadata. This feeds into the ACP `session/load` or `_posthog/session/resume` methods on the Claude adapter, which initializes a new Claude SDK query with the rebuilt context.
-
-Snapshot application can fail without aborting the resume — if the archive URL is missing or the download fails, the saga logs a warning and continues with just the conversation history. The `snapshotApplied` flag in the result tells the caller whether files were actually restored.
+The result is a `ResumeState` containing the conversation history as `ConversationTurn[]`, the latest git checkpoint, and metadata. This feeds into the ACP `session/load` or `_posthog/session/resume` methods on the Claude adapter, which initializes a new Claude SDK query with the rebuilt context.
 
 ## ACP extensions
 
@@ -250,7 +247,7 @@ ACP defines standard methods like `session/prompt`, `session/update`, and `sessi
 **State synchronization** — events that keep the client's view of the agent's state in sync. These are essential for the cloud↔local handoff flow and for the client to render accurate UI.
 
 - `_posthog/branch_created` — `{ branch }` — agent created a git branch (client can update branch display)
-- `_posthog/tree_snapshot` — `{ treeHash, baseCommit, changes, ... }` — git working tree captured as a snapshot. Contains the tree hash, base commit, file change list, and optionally an archive URL. This is the key event for session resume — the resume saga scans backwards for the latest snapshot to restore files
+- `_posthog/git_checkpoint` — `{ checkpointId, checkpointRef, branch, head, indexTree, worktreeTree, ... }` — git checkpoint captured for resume and handoff. This is the key event for session resume — the resume saga scans backwards for the latest checkpoint to restore files
 - `_posthog/mode_change` — `{ mode, previous_mode }` — permission mode changed (client updates mode selector)
 - `_posthog/compact_boundary` — `{ sessionId, timestamp }` — marks where context compaction occurred, so the client knows the conversation was summarized at this point
 - `_posthog/task_notification` — `{ sessionId, type, message?, data? }` — generic extensible notification for adapter-specific events
@@ -260,7 +257,7 @@ ACP defines standard methods like `session/prompt`, `session/update`, and `sessi
 - `_posthog/user_message` — `{ content }` — user typed a message (translated to `session/prompt`)
 - `_posthog/cancel` — cancel the current operation (translated to `session/cancel`)
 - `_posthog/close` — close the session and clean up
-- `_posthog/session/resume` — `{ sessionId, fromSnapshot? }` — request to resume a previous session (triggers the resume flow on the Claude adapter)
+- `_posthog/session/resume` — `{ sessionId }` — request to resume a previous session (triggers the resume flow on the Claude adapter)
 
 **Debug** — operational visibility without polluting the ACP conversation.
 

package/dist/agent.js

@@ -4030,7 +4030,7 @@ import { v7 as uuidv7 } from "uuid";
 // package.json
 var package_default = {
   name: "@posthog/agent",
-  version: "2.3.398",
+  version: "2.3.403",
   repository: "https://github.com/PostHog/code",
   description: "TypeScript agent framework wrapping Claude Agent SDK with Git-based task execution for PostHog",
   exports: {
@@ -4098,10 +4098,6 @@ var package_default = {
       types: "./dist/handoff-checkpoint.d.ts",
       import: "./dist/handoff-checkpoint.js"
     },
-    "./tree-tracker": {
-      types: "./dist/tree-tracker.d.ts",
-      import: "./dist/tree-tracker.js"
-    },
     "./server": {
       types: "./dist/server/agent-server.d.ts",
       import: "./dist/server/agent-server.js"
@@ -4197,8 +4193,6 @@ var POSTHOG_NOTIFICATIONS = {
   CONSOLE: "_posthog/console",
   /** Maps taskRunId to agent's sessionId and adapter type (for resumption) */
   SDK_SESSION: "_posthog/sdk_session",
-  /** Tree state snapshot captured (git tree hash + file archive) */
-  TREE_SNAPSHOT: "_posthog/tree_snapshot",
   /** Git checkpoint captured for handoff */
   GIT_CHECKPOINT: "_posthog/git_checkpoint",
   /** Agent mode changed (interactive/background) */