feat(canvas): edit canvases as scratch files via canvas_checkout/publish

Canvas generation previously required the agent to regenerate and emit the
entire React source every turn. Add a canvas_checkout / canvas_publish local
tool pair (available to both the Claude and Codex adapters) that moves the
file I/O tool-side: checkout writes the live source to a scratch path and
records the base version, the agent applies targeted edits with its native
file tools, and publish reads the file from disk and appends a version —
refusing when the canvas moved past the checkout base (concurrent edit or
undo) instead of clobbering it.

The generation prompt now routes through checkout → edit → publish and no
longer embeds the current source. Storage stays wholesale full-file
snapshots; a server-side base_version check on the desktop-fs PATCH remains
a follow-up.

Generated-By: PostHog Code
Task-Id: 2b3d176e-3023-41d2-92e8-81eda7c12a8c

Author: adboio

packages/agent/src/adapters/local-tools/index.ts

@@ -1,4 +1,5 @@
 import type { LocalTool, LocalToolCtx, LocalToolGateMeta } from "./registry";
+import { canvasCheckoutTool, canvasPublishTool } from "./tools/canvas";
 import { cloneRepoTool } from "./tools/clone-repo";
 import { listReposTool } from "./tools/list-repos";
 import { signedCommitTool } from "./tools/signed-commit";
@@ -23,6 +24,8 @@ export const LOCAL_TOOLS: LocalTool[] = [
   listReposTool,
   cloneRepoTool,
   speakTool,
+  canvasCheckoutTool,
+  canvasPublishTool,
 ];
 
 /** Tools whose gate passes for the given context — the set to actually expose. */

packages/agent/src/adapters/local-tools/tools/canvas.test.ts

@@ -0,0 +1,132 @@
+import { describe, expect, it } from "vitest";
+import {
+  canvasScratchDir,
+  canvasScratchFile,
+  composePublishedMeta,
+} from "./canvas";
+
+describe("canvas scratch paths", () => {
+  it("keys the scratch dir and file by canvas id, outside any workspace", () => {
+    expect(canvasScratchDir("dash-1")).toBe("/tmp/posthog-canvas/dash-1");
+    expect(canvasScratchFile("dash-1")).toBe(
+      "/tmp/posthog-canvas/dash-1/canvas.tsx",
+    );
+  });
+});
+
+describe("composePublishedMeta", () => {
+  const v1 = { id: "v1", code: "one", createdAt: 1 };
+  const v2 = { id: "v2", code: "two", createdAt: 2 };
+  const v3 = { id: "v3", code: "three", createdAt: 3 };
+
+  it("appends a new head version when the base matches", () => {
+    const result = composePublishedMeta({
+      freshMeta: { code: "two", versions: [v1, v2], currentVersionId: "v2" },
+      baseVersionId: "v2",
+      code: "edited",
+      prompt: "tweak the chart",
+      now: 10,
+    });
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.meta.code).toBe("edited");
+    expect(result.meta.currentVersionId).toBe(result.versionId);
+    expect(result.meta.versions).toHaveLength(3);
+    expect(result.meta.versions?.at(-1)).toMatchObject({
+      code: "edited",
+      prompt: "tweak the chart",
+      createdAt: 10,
+    });
+    expect(result.meta.updatedAt).toBe(10);
+  });
+
+  it("preserves unrelated meta keys", () => {
+    const result = composePublishedMeta({
+      freshMeta: {
+        code: "one",
+        versions: [v1],
+        currentVersionId: "v1",
+        templateId: "freeform",
+        pinnedAt: 123,
+      },
+      baseVersionId: "v1",
+      code: "edited",
+      now: 10,
+    });
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.meta.templateId).toBe("freeform");
+    expect(result.meta.pinnedAt).toBe(123);
+  });
+
+  it("rejects when the canvas moved past the base (concurrent edit)", () => {
+    const result = composePublishedMeta({
+      freshMeta: {
+        code: "three",
+        versions: [v1, v2, v3],
+        currentVersionId: "v3",
+      },
+      baseVersionId: "v2",
+      code: "edited",
+      now: 10,
+    });
+    expect(result.ok).toBe(false);
+  });
+
+  it("rejects a based publish onto a canvas with no versions", () => {
+    const result = composePublishedMeta({
+      freshMeta: {},
+      baseVersionId: "v1",
+      code: "edited",
+      now: 10,
+    });
+    expect(result.ok).toBe(false);
+  });
+
+  it("truncates the redo tail when publishing from an undone version", () => {
+    // The user undid to v1 (pointer mid-history), then the agent edited from
+    // that checkout: the redo tail (v2, v3) is discarded — the same
+    // linear-discard the client's undo/redo uses.
+    const result = composePublishedMeta({
+      freshMeta: {
+        code: "one",
+        versions: [v1, v2, v3],
+        currentVersionId: "v1",
+      },
+      baseVersionId: "v1",
+      code: "edited",
+      now: 10,
+    });
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.meta.versions?.map((v) => v.id)).toEqual([
+      "v1",
+      result.versionId,
+    ]);
+  });
+
+  it("seeds an empty canvas as the first version (no base)", () => {
+    const result = composePublishedMeta({
+      freshMeta: { templateId: "freeform" },
+      baseVersionId: undefined,
+      code: "first build",
+      now: 10,
+    });
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.meta.versions).toHaveLength(1);
+    expect(result.meta.currentVersionId).toBe(result.versionId);
+    expect(result.meta.code).toBe("first build");
+  });
+
+  it("rejects an un-based publish onto a canvas that gained versions", () => {
+    // Checked out empty, but a concurrent first build published meanwhile.
+    const result = composePublishedMeta({
+      freshMeta: { code: "one", versions: [v1], currentVersionId: "v1" },
+      baseVersionId: undefined,
+      code: "edited",
+      now: 10,
+    });
+    expect(result.ok).toBe(false);
+  });
+});