@posthog/agent 2.3.386 → 2.3.387

package/dist/types.d.ts

@@ -1,3 +1,5 @@
+import { HandoffLocalGitState as HandoffLocalGitState$1, GitHandoffCheckpoint } from '@posthog/git/handoff';
+
 /**
  * Stored custom notification following ACP extensibility model.
  * Custom notifications use underscore-prefixed methods (e.g., `_posthog/phase_start`).
@@ -146,5 +148,20 @@ interface TreeSnapshot {
 interface TreeSnapshotEvent extends TreeSnapshot {
     device?: DeviceInfo;
 }
+type HandoffLocalGitState = HandoffLocalGitState$1;
+interface GitCheckpoint extends GitHandoffCheckpoint {
+    artifactPath?: string;
+    indexArtifactPath?: string;
+}
+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.
+ */
+declare const AGENT_TYPES_MODULE = true;
 
-export type { AgentConfig, AgentMode, ArtifactType, DeviceInfo, FileChange, FileStatus, LogLevel, OnLogCallback, OtelTransportConfig, PostHogAPIConfig, ProcessSpawnedCallback, StoredEntry, StoredNotification, Task, TaskExecutionOptions, TaskRun, TaskRunArtifact, TaskRunEnvironment, TaskRunStatus, TreeSnapshot, TreeSnapshotEvent };
+export { AGENT_TYPES_MODULE, type AgentConfig, type AgentMode, type ArtifactType, type DeviceInfo, type FileChange, type FileStatus, type GitCheckpoint, type GitCheckpointEvent, type HandoffLocalGitState, type LogLevel, type OnLogCallback, type OtelTransportConfig, type PostHogAPIConfig, type ProcessSpawnedCallback, type StoredEntry, type StoredNotification, type Task, type TaskExecutionOptions, type TaskRun, type TaskRunArtifact, type TaskRunEnvironment, type TaskRunStatus, type TreeSnapshot, type TreeSnapshotEvent };

package/dist/types.js

@@ -1 +1,6 @@
+// src/types.ts
+var AGENT_TYPES_MODULE = true;
+export {
+  AGENT_TYPES_MODULE
+};
 //# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}
+{"version":3,"sources":["../src/types.ts"],"sourcesContent":["import type {\n  GitHandoffCheckpoint,\n  HandoffLocalGitState as GitHandoffLocalGitState,\n} from \"@posthog/git/handoff\";\n\n/**\n * Stored custom notification following ACP extensibility model.\n * Custom notifications use underscore-prefixed methods (e.g., `_posthog/phase_start`).\n * See: https://agentclientprotocol.com/docs/extensibility\n */\nexport interface StoredNotification {\n  type: \"notification\";\n  /** When this notification was stored */\n  timestamp: string;\n  /** JSON-RPC 2.0 notification (no id field = notification, not request) */\n  notification: {\n    jsonrpc: \"2.0\";\n    method: string;\n    params?: Record<string, unknown>;\n  };\n}\n\n/**\n * Type alias for stored log entries.\n */\nexport type StoredEntry = StoredNotification;\n\n// PostHog Task model (matches PostHog Code's OpenAPI schema)\nexport interface Task {\n  id: string;\n  task_number?: number;\n  slug?: string;\n  title: string;\n  description: string;\n  origin_product:\n    | \"error_tracking\"\n    | \"eval_clusters\"\n    | \"user_created\"\n    | \"support_queue\"\n    | \"session_summaries\";\n  github_integration?: number | null;\n  repository: string; // Format: \"organization/repository\" (e.g., \"posthog/posthog-js\")\n  json_schema?: Record<string, unknown> | null; // JSON schema for task output validation\n  created_at: string;\n  updated_at: string;\n  created_by?: {\n    id: number;\n    uuid: string;\n    distinct_id: string;\n    first_name: string;\n    email: string;\n  };\n  latest_run?: TaskRun;\n}\n\n// Log entry structure for TaskRun.log\n\nexport type ArtifactType =\n  | \"plan\"\n  | \"context\"\n  | \"reference\"\n  | \"output\"\n  | \"artifact\"\n  | \"tree_snapshot\"\n  | \"user_attachment\";\n\nexport interface TaskRunArtifact {\n  id?: string;\n  name: string;\n  type: ArtifactType;\n  source?: string;\n  size?: number;\n  content_type?: string;\n  storage_path?: string;\n  uploaded_at?: string;\n}\n\nexport type TaskRunStatus =\n  | \"not_started\"\n  | \"queued\"\n  | \"in_progress\"\n  | \"completed\"\n  | \"failed\"\n  | \"cancelled\";\n\nexport type TaskRunEnvironment = \"local\" | \"cloud\";\n\n// TaskRun model - represents individual execution runs of tasks\nexport interface TaskRun {\n  id: string;\n  task: string; // Task ID\n  team: number;\n  branch: string | null;\n  stage: string | null; // Current stage (e.g., 'research', 'plan', 'build')\n  environment: TaskRunEnvironment;\n  status: TaskRunStatus;\n  log_url: string;\n  error_message: string | null;\n  output: Record<string, unknown> | null; // Structured output (PR URL, commit SHA, etc.)\n  state: Record<string, unknown>; // Intermediate run state (defaults to {}, never null)\n  artifacts?: TaskRunArtifact[];\n  created_at: string;\n  updated_at: string;\n  completed_at: string | null;\n}\n\nexport interface ProcessSpawnedCallback {\n  onProcessSpawned?: (info: {\n    pid: number;\n    command: string;\n    sessionId?: string;\n  }) => void;\n  onProcessExited?: (pid: number) => void;\n  onMcpServersReady?: (serverNames: string[]) => void;\n}\n\nexport interface TaskExecutionOptions {\n  repositoryPath?: string;\n  adapter?: \"claude\" | \"codex\";\n  model?: string;\n  gatewayUrl?: string;\n  codexBinaryPath?: string;\n  instructions?: string;\n  processCallbacks?: ProcessSpawnedCallback;\n  /** Callback invoked when the agent calls the create_output tool for structured output */\n  onStructuredOutput?: (output: Record<string, unknown>) => Promise<void>;\n}\n\nexport type LogLevel = \"debug\" | \"info\" | \"warn\" | \"error\";\n\nexport type OnLogCallback = (\n  level: LogLevel,\n  scope: string,\n  message: string,\n  data?: unknown,\n) => void;\n\nexport interface PostHogAPIConfig {\n  apiUrl: string;\n  getApiKey: () => string | Promise<string>;\n  refreshApiKey?: () => string | Promise<string>;\n  projectId: number;\n  userAgent?: string;\n}\n\nexport interface OtelTransportConfig {\n  /** PostHog ingest host, e.g., \"https://us.i.posthog.com\" */\n  host: string;\n  /** Project API key */\n  apiKey: string;\n  /** Override the logs endpoint path (default: /i/v1/logs) */\n  logsPath?: string;\n}\n\nexport interface AgentConfig {\n  posthog?: PostHogAPIConfig;\n  /** OTEL transport config for shipping logs to PostHog Logs */\n  otelTransport?: OtelTransportConfig;\n  /** Skip session log persistence (e.g. for preview sessions with no real task) */\n  skipLogPersistence?: boolean;\n  /** Local cache path for instant log loading (e.g., ~/.posthog-code) */\n  localCachePath?: string;\n  /**\n   * Annotate files the agent reads with PostHog enrichment (event volume,\n   * flag rollout/staleness, experiment links). Defaults to enabled when\n   * `posthog` config is present; set `{ enabled: false }` to opt out.\n   */\n  enricher?: { enabled?: boolean };\n  debug?: boolean;\n  onLog?: OnLogCallback;\n}\n\n// Device info for tracking where work happens\nexport interface DeviceInfo {\n  type: \"local\" | \"cloud\";\n  name?: string;\n}\n\n// Agent execution mode - for tracking interactive vs background runs, when backgrounded an agent will continue working without asking questions\nexport type AgentMode = \"interactive\" | \"background\";\n\n// Git file status codes\nexport type FileStatus = \"A\" | \"M\" | \"D\";\n\nexport interface FileChange {\n  path: string;\n  status: FileStatus;\n}\n\n// Tree snapshot - what TreeTracker captures\nexport interface TreeSnapshot {\n  treeHash: string;\n  baseCommit: string | null;\n  archiveUrl?: string;\n  changes: FileChange[];\n  timestamp: string;\n  interrupted?: boolean;\n}\n\n// Tree snapshot event - includes device info when sent as notification\nexport interface TreeSnapshotEvent extends TreeSnapshot {\n  device?: DeviceInfo;\n}\n\nexport type HandoffLocalGitState = GitHandoffLocalGitState;\n\nexport interface GitCheckpoint extends GitHandoffCheckpoint {\n  artifactPath?: string;\n  indexArtifactPath?: string;\n}\n\nexport interface GitCheckpointEvent extends GitCheckpoint {\n  device?: DeviceInfo;\n}\n\n/**\n * Keeps the emitted `@posthog/agent/types` entrypoint as a runtime ESM module.\n *\n * `export {}` is stripped by tsup in this package, which leaves `dist/types.js`\n * empty and breaks downstream type resolution for the exported subpath.\n */\nexport const AGENT_TYPES_MODULE = true;\n"],"mappings":";AA6NO,IAAM,qBAAqB;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@posthog/agent",
-  "version": "2.3.386",
+  "version": "2.3.387",
   "repository": "https://github.com/PostHog/code",
   "description": "TypeScript agent framework wrapping Claude Agent SDK with Git-based task execution for PostHog",
   "exports": {
@@ -60,6 +60,10 @@
       "types": "./dist/resume.d.ts",
       "import": "./dist/resume.js"
     },
+    "./handoff-checkpoint": {
+      "types": "./dist/handoff-checkpoint.d.ts",
+      "import": "./dist/handoff-checkpoint.js"
+    },
     "./tree-tracker": {
       "types": "./dist/tree-tracker.d.ts",
       "import": "./dist/tree-tracker.js"
@@ -67,6 +71,10 @@
     "./server": {
       "types": "./dist/server/agent-server.d.ts",
       "import": "./dist/server/agent-server.js"
+    },
+    "./server/schemas": {
+      "types": "./dist/server/schemas.d.ts",
+      "import": "./dist/server/schemas.js"
     }
   },
   "bin": {

package/src/acp-extensions.ts

@@ -37,6 +37,9 @@ export const POSTHOG_NOTIFICATIONS = {
   /** 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) */
   MODE_CHANGE: "_posthog/mode_change",
 

package/src/handoff-checkpoint.test.ts

@@ -0,0 +1,183 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { HandoffCheckpointTracker } from "./handoff-checkpoint";
+import {
+  cloneTestRepo,
+  createTestRepo,
+  type TestRepo,
+} from "./sagas/test-fixtures";
+import type { HandoffLocalGitState } from "./types";
+
+interface BundleStore {
+  artifacts: Record<string, string>;
+  storagePath: string;
+  manifest: Array<{ storage_path: string }>;
+}
+
+interface HandoffRepos {
+  cloudRepo: TestRepo;
+  localRepo: TestRepo;
+  branch: string;
+  localGitState: HandoffLocalGitState;
+}
+
+const WORKTREE_FILES = ["tracked.txt", "unstaged.txt", "untracked.txt"];
+
+function createMockApi(store: BundleStore) {
+  return {
+    uploadTaskArtifacts: async (
+      _taskId: string,
+      _runId: string,
+      artifacts: Array<{
+        name: string;
+        content: string;
+      }>,
+    ) => {
+      const uploaded = artifacts.map((artifact, index) => {
+        const storagePath = `${store.storagePath}-${store.manifest.length + index}-${artifact.name}`;
+        store.artifacts[storagePath] = artifact.content;
+        return { storage_path: storagePath };
+      });
+      for (const entry of uploaded) {
+        store.manifest.push(entry);
+      }
+      return store.manifest;
+    },
+    downloadArtifact: async (
+      _taskId: string,
+      _runId: string,
+      artifactPath: string,
+    ) => {
+      const contentBase64 = store.artifacts[artifactPath];
+      if (!contentBase64) return null;
+      const buffer = Buffer.from(contentBase64, "utf-8");
+      return buffer.buffer.slice(
+        buffer.byteOffset,
+        buffer.byteOffset + buffer.byteLength,
+      );
+    },
+  };
+}
+
+function createBundleStore(): BundleStore {
+  return {
+    storagePath: "gs://bucket/handoff",
+    artifacts: {},
+    manifest: [
+      {
+        storage_path: "gs://bucket/handoff-0-existing-tree_snapshot.tar.gz",
+      },
+    ],
+  };
+}
+
+function createTracker(
+  repositoryPath: string,
+  apiClient: ReturnType<typeof createMockApi>,
+) {
+  return new HandoffCheckpointTracker({
+    repositoryPath,
+    taskId: "task-1",
+    runId: "run-1",
+    apiClient: apiClient as never,
+  });
+}
+
+async function seedCloudRepo(repo: TestRepo): Promise<void> {
+  await repo.writeFile("tracked.txt", "base\n");
+  await repo.writeFile("unstaged.txt", "base unstaged\n");
+  await repo.git(["add", "tracked.txt", "unstaged.txt"]);
+  await repo.git(["commit", "-m", "Add tracked files"]);
+}
+
+async function prepareHandoffRepos(
+  cleanups: Array<() => Promise<void>>,
+): Promise<HandoffRepos> {
+  const cloudRepo = await createTestRepo("handoff-cloud");
+  cleanups.push(cloudRepo.cleanup);
+  await seedCloudRepo(cloudRepo);
+
+  const localRepo = await cloneTestRepo(cloudRepo.path, "handoff-local");
+  cleanups.push(localRepo.cleanup);
+
+  const branch = await cloudRepo.git(["rev-parse", "--abbrev-ref", "HEAD"]);
+  const localHead = await localRepo.git(["rev-parse", "HEAD"]);
+  const upstreamHead = await localRepo.git(["rev-parse", `origin/${branch}`]);
+
+  return {
+    cloudRepo,
+    localRepo,
+    branch,
+    localGitState: {
+      head: localHead,
+      branch,
+      upstreamHead,
+      upstreamRemote: "origin",
+      upstreamMergeRef: `refs/heads/${branch}`,
+    },
+  };
+}
+
+async function makeCloudChanges(repo: TestRepo): Promise<void> {
+  await repo.writeFile("committed.txt", "cloud commit\n");
+  await repo.git(["add", "committed.txt"]);
+  await repo.git(["commit", "-m", "Cloud commit"]);
+
+  await repo.writeFile("tracked.txt", "staged change\n");
+  await repo.git(["add", "tracked.txt"]);
+  await repo.writeFile("unstaged.txt", "unstaged change\n");
+  await repo.writeFile("untracked.txt", "untracked\n");
+}
+
+async function mirrorRestoredWorktree(
+  cloudRepo: TestRepo,
+  localRepo: TestRepo,
+): Promise<void> {
+  for (const file of WORKTREE_FILES) {
+    await localRepo.writeFile(file, await cloudRepo.readFile(file));
+  }
+}
+
+describe("HandoffCheckpointTracker", () => {
+  const cleanups: Array<() => Promise<void>> = [];
+
+  afterEach(async () => {
+    await Promise.all(cleanups.splice(0).map((cleanup) => cleanup()));
+  });
+
+  it("restores head commit and index state for handoff replay", async () => {
+    const { cloudRepo, localRepo, branch, localGitState } =
+      await prepareHandoffRepos(cleanups);
+    await makeCloudChanges(cloudRepo);
+
+    const store = createBundleStore();
+    const apiClient = createMockApi(store);
+    const captureTracker = createTracker(cloudRepo.path, apiClient);
+
+    const checkpoint = await captureTracker.captureForHandoff(localGitState);
+
+    expect(checkpoint).not.toBeNull();
+    if (!checkpoint) return;
+    expect(Object.keys(store.artifacts).length).toBeGreaterThan(0);
+
+    const applyTracker = createTracker(localRepo.path, apiClient);
+    await applyTracker.applyFromHandoff(checkpoint);
+
+    // The handoff service restores files separately via tree_snapshot.
+    // Mirror that here so the restored git index can be validated.
+    await mirrorRestoredWorktree(cloudRepo, localRepo);
+
+    expect(await localRepo.git(["rev-parse", "HEAD"])).toBe(checkpoint.head);
+    expect(await localRepo.git(["rev-parse", "--abbrev-ref", "HEAD"])).toBe(
+      branch,
+    );
+    expect(await localRepo.readFile("committed.txt")).toBe("cloud commit\n");
+    expect(await localRepo.readFile("tracked.txt")).toBe("staged change\n");
+    expect(await localRepo.readFile("unstaged.txt")).toBe("unstaged change\n");
+    expect(await localRepo.readFile("untracked.txt")).toBe("untracked\n");
+
+    const status = await localRepo.git(["status", "--porcelain"]);
+    expect(status).toContain("M  tracked.txt");
+    expect(status).toContain(" M unstaged.txt");
+    expect(status).toContain("?? untracked.txt");
+  });
+});

package/src/handoff-checkpoint.ts

@@ -0,0 +1,361 @@
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import {
+  type GitHandoffBranchDivergence,
+  type GitHandoffCheckpoint,
+  GitHandoffTracker,
+} from "@posthog/git/handoff";
+import type { PostHogAPIClient } from "./posthog-api";
+import type { GitCheckpoint, HandoffLocalGitState } from "./types";
+import { Logger } from "./utils/logger";
+
+export interface HandoffCheckpointTrackerConfig {
+  repositoryPath: string;
+  taskId: string;
+  runId: string;
+  apiClient?: PostHogAPIClient;
+  logger?: Logger;
+}
+
+type ArtifactTransfer<T extends object = {}> = T & {
+  rawBytes: number;
+  wireBytes: number;
+};
+
+type UploadedArtifact = ArtifactTransfer<{ storagePath?: string }>;
+type DownloadedArtifact = ArtifactTransfer<{ filePath: string }>;
+
+type ArtifactKey = "pack" | "index";
+type ArtifactSlotMap<T extends object> = Partial<
+  Record<ArtifactKey, ArtifactTransfer<T>>
+>;
+
+interface UploadArtifactSpec {
+  key: ArtifactKey;
+  filePath?: string;
+  name: string;
+  contentType: string;
+}
+
+interface DownloadArtifactSpec {
+  key: ArtifactKey;
+  storagePath?: string;
+  filePath: string;
+  label: string;
+}
+
+type Uploads = ArtifactSlotMap<{ storagePath?: string }>;
+type Downloads = ArtifactSlotMap<{ filePath: string }>;
+
+export class HandoffCheckpointTracker {
+  private repositoryPath: string;
+  private taskId: string;
+  private runId: string;
+  private apiClient?: PostHogAPIClient;
+  private logger: Logger;
+
+  constructor(config: HandoffCheckpointTrackerConfig) {
+    this.repositoryPath = config.repositoryPath;
+    this.taskId = config.taskId;
+    this.runId = config.runId;
+    this.apiClient = config.apiClient;
+    this.logger =
+      config.logger ||
+      new Logger({ debug: false, prefix: "[HandoffCheckpointTracker]" });
+  }
+
+  async captureForHandoff(
+    localGitState?: HandoffLocalGitState,
+  ): Promise<GitCheckpoint | null> {
+    if (!this.apiClient) {
+      throw new Error(
+        "Cannot capture handoff checkpoint: API client not configured",
+      );
+    }
+
+    const gitTracker = this.createGitTracker();
+    const capture = await gitTracker.captureForHandoff(localGitState);
+
+    try {
+      const uploads = await this.uploadArtifacts([
+        {
+          key: "pack",
+          filePath: capture.headPack?.path,
+          name: `handoff/${capture.checkpoint.checkpointId}.pack`,
+          contentType: "application/x-git-packed-objects",
+        },
+        {
+          key: "index",
+          filePath: capture.indexFile.path,
+          name: `handoff/${capture.checkpoint.checkpointId}.index`,
+          contentType: "application/octet-stream",
+        },
+      ]);
+
+      this.logCaptureMetrics(capture.checkpoint, uploads);
+
+      return {
+        ...capture.checkpoint,
+        artifactPath: uploads.pack?.storagePath,
+        indexArtifactPath: uploads.index?.storagePath,
+      };
+    } finally {
+      await this.removeIfPresent(capture.headPack?.path);
+      await this.removeIfPresent(capture.indexFile.path);
+    }
+  }
+
+  async applyFromHandoff(
+    checkpoint: GitCheckpoint,
+    options?: {
+      localGitState?: HandoffLocalGitState;
+      onDivergedBranch?: (
+        divergence: GitHandoffBranchDivergence,
+      ) => Promise<boolean>;
+    },
+  ): Promise<void> {
+    if (!this.apiClient) {
+      throw new Error(
+        "Cannot apply handoff checkpoint: API client not configured",
+      );
+    }
+
+    const gitTracker = this.createGitTracker();
+    const tmpDir = join(this.repositoryPath, ".posthog", "tmp");
+    await mkdir(tmpDir, { recursive: true });
+
+    const packPath = join(tmpDir, `${checkpoint.checkpointId}.pack`);
+    const indexPath = join(tmpDir, `${checkpoint.checkpointId}.index`);
+
+    try {
+      const downloads = await this.downloadArtifacts([
+        {
+          key: "pack",
+          storagePath: checkpoint.artifactPath,
+          filePath: packPath,
+          label: "handoff pack",
+        },
+        {
+          key: "index",
+          storagePath: checkpoint.indexArtifactPath,
+          filePath: indexPath,
+          label: "handoff index",
+        },
+      ]);
+
+      const applyResult = await gitTracker.applyFromHandoff({
+        checkpoint: this.toGitCheckpoint(checkpoint),
+        headPackPath: downloads.pack?.filePath,
+        indexPath: downloads.index?.filePath,
+        localGitState: options?.localGitState,
+        onDivergedBranch: options?.onDivergedBranch,
+      });
+
+      this.logApplyMetrics(checkpoint, downloads, applyResult.totalBytes);
+    } finally {
+      await this.removeIfPresent(packPath);
+      await this.removeIfPresent(indexPath);
+    }
+  }
+
+  private toGitCheckpoint(checkpoint: GitCheckpoint): GitHandoffCheckpoint {
+    return {
+      checkpointId: checkpoint.checkpointId,
+      commit: checkpoint.commit,
+      checkpointRef: checkpoint.checkpointRef,
+      headRef: checkpoint.headRef,
+      head: checkpoint.head,
+      branch: checkpoint.branch,
+      indexTree: checkpoint.indexTree,
+      worktreeTree: checkpoint.worktreeTree,
+      timestamp: checkpoint.timestamp,
+      upstreamRemote: checkpoint.upstreamRemote ?? null,
+      upstreamMergeRef: checkpoint.upstreamMergeRef ?? null,
+      remoteUrl: checkpoint.remoteUrl ?? null,
+    };
+  }
+
+  private async uploadArtifactFile(
+    filePath: string,
+    name: string,
+    contentType: string,
+  ): Promise<UploadedArtifact> {
+    if (!this.apiClient) {
+      return { rawBytes: 0, wireBytes: 0 };
+    }
+
+    const content = await readFile(filePath);
+    const base64Content = content.toString("base64");
+    const artifacts = await this.apiClient.uploadTaskArtifacts(
+      this.taskId,
+      this.runId,
+      [
+        {
+          name,
+          type: "artifact",
+          content: base64Content,
+          content_type: contentType,
+        },
+      ],
+    );
+
+    return {
+      storagePath: artifacts.at(-1)?.storage_path,
+      rawBytes: content.byteLength,
+      wireBytes: Buffer.byteLength(base64Content, "utf-8"),
+    };
+  }
+
+  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;
+      }),
+    );
+
+    return Object.fromEntries(uploads) as Uploads;
+  }
+
+  private async downloadArtifactToFile(
+    artifactPath: string,
+    filePath: string,
+    label: string,
+  ): Promise<DownloadedArtifact> {
+    if (!this.apiClient) {
+      throw new Error(`Cannot download ${label}: API client not configured`);
+    }
+
+    const arrayBuffer = await this.apiClient.downloadArtifact(
+      this.taskId,
+      this.runId,
+      artifactPath,
+    );
+    if (!arrayBuffer) {
+      throw new Error(`Failed to download ${label}`);
+    }
+
+    const base64Content = Buffer.from(arrayBuffer).toString("utf-8");
+    const binaryContent = Buffer.from(base64Content, "base64");
+    await writeFile(filePath, binaryContent);
+    return {
+      filePath,
+      rawBytes: binaryContent.byteLength,
+      wireBytes: arrayBuffer.byteLength,
+    };
+  }
+
+  private async downloadArtifacts(
+    specs: DownloadArtifactSpec[],
+  ): Promise<Downloads> {
+    const downloads = await Promise.all(
+      specs.map(async (spec) => {
+        if (!spec.storagePath) {
+          return [spec.key, undefined] as const;
+        }
+        return [
+          spec.key,
+          await this.downloadArtifactToFile(
+            spec.storagePath,
+            spec.filePath,
+            spec.label,
+          ),
+        ] as const;
+      }),
+    );
+
+    return Object.fromEntries(downloads) as Downloads;
+  }
+
+  private createGitTracker(): GitHandoffTracker {
+    return new GitHandoffTracker({
+      repositoryPath: this.repositoryPath,
+      logger: this.logger,
+    });
+  }
+
+  private logCaptureMetrics(
+    checkpoint: GitHandoffCheckpoint,
+    uploads: Uploads,
+  ): void {
+    this.logger.info("Captured handoff checkpoint", {
+      checkpointId: checkpoint.checkpointId,
+      branch: checkpoint.branch,
+      head: checkpoint.head,
+      artifactPath: uploads.pack?.storagePath,
+      indexArtifactPath: uploads.index?.storagePath,
+      ...this.buildMetricPayload(uploads),
+    });
+  }
+
+  private logApplyMetrics(
+    checkpoint: GitCheckpoint,
+    downloads: Downloads,
+    totalBytes: number,
+  ): void {
+    this.logger.info("Applied handoff checkpoint", {
+      checkpointId: checkpoint.checkpointId,
+      commit: checkpoint.commit,
+      branch: checkpoint.branch,
+      head: checkpoint.head,
+      packBytes: downloads.pack?.rawBytes ?? 0,
+      packWireBytes: downloads.pack?.wireBytes ?? 0,
+      indexBytes: downloads.index?.rawBytes ?? 0,
+      indexWireBytes: downloads.index?.wireBytes ?? 0,
+      totalBytes,
+      totalWireBytes: this.sumWireBytes(downloads.pack, downloads.index),
+    });
+  }
+
+  private buildMetricPayload(metrics: ArtifactSlotMap<object>): {
+    packBytes: number;
+    packWireBytes: number;
+    indexBytes: number;
+    indexWireBytes: number;
+    totalBytes: number;
+    totalWireBytes: number;
+  } {
+    return {
+      packBytes: metrics.pack?.rawBytes ?? 0,
+      packWireBytes: metrics.pack?.wireBytes ?? 0,
+      indexBytes: metrics.index?.rawBytes ?? 0,
+      indexWireBytes: metrics.index?.wireBytes ?? 0,
+      totalBytes: this.sumRawBytes(metrics.pack, metrics.index),
+      totalWireBytes: this.sumWireBytes(metrics.pack, metrics.index),
+    };
+  }
+
+  private sumRawBytes(
+    ...artifacts: Array<{ rawBytes: number } | undefined>
+  ): number {
+    return artifacts.reduce(
+      (total, artifact) => total + (artifact?.rawBytes ?? 0),
+      0,
+    );
+  }
+
+  private sumWireBytes(
+    ...artifacts: Array<{ wireBytes: number } | undefined>
+  ): number {
+    return artifacts.reduce(
+      (total, artifact) => total + (artifact?.wireBytes ?? 0),
+      0,
+    );
+  }
+
+  private async removeIfPresent(filePath: string | undefined): Promise<void> {
+    if (!filePath) {
+      return;
+    }
+    await rm(filePath, { force: true }).catch(() => {});
+  }
+}

package/src/posthog-api.test.ts

@@ -77,4 +77,33 @@ describe("PostHogAPIClient", () => {
       }),
     );
   });
+
+  it("returns only the artifacts created by the current upload request", async () => {
+    const client = new PostHogAPIClient({
+      apiUrl: "https://app.posthog.com",
+      getApiKey: vi.fn().mockResolvedValue("token"),
+      projectId: 1,
+    });
+
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      json: vi.fn().mockResolvedValue({
+        artifacts: [
+          { storage_path: "gs://bucket/existing.tar.gz", name: "existing" },
+          { storage_path: "gs://bucket/new-1.pack", name: "new-1" },
+          { storage_path: "gs://bucket/new-2.index", name: "new-2" },
+        ],
+      }),
+    });
+
+    const artifacts = await client.uploadTaskArtifacts("task-1", "run-1", [
+      { name: "new-1", type: "artifact", content: "AAA" },
+      { name: "new-2", type: "artifact", content: "BBB" },
+    ]);
+
+    expect(artifacts).toEqual([
+      { storage_path: "gs://bucket/new-1.pack", name: "new-1" },
+      { storage_path: "gs://bucket/new-2.index", name: "new-2" },
+    ]);
+  });
 });

package/src/posthog-api.ts

@@ -230,7 +230,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);
   }
 
   /**