feat(canvas): create-if-missing checkout, authoring contract, discovery + allowlist

adboio · adboio · commit 061c5de7d1b3 · 2026-07-20T15:55:56.000-04:00
Build on the canvas_checkout/canvas_publish tools so canvas work is reachable
and correct from any task, not just the channel generate bar:

- canvas_checkout takes an optional id (edit) OR a name (create-if-missing), so
  the agent starts a canvas in one call instead of chaining desktop-fs create.
- checkout returns the freeform authoring contract (from @posthog/shared), so an
  agent editing a canvas from a normal task authors valid source.
- a channelMode-gated "## Canvases" block in the base system prompt names the
  tools + the create-&gt;checkout-&gt;publish sequence (fixes ToolSearch flakiness).
- add a declarative autoApprove flag to local tools; canvas_checkout (read-only)
  and speak are auto-approved, canvas_publish (write) still prompts.
- createDesktopCanvas API helper + allowlist regression test.

Generated-By: PostHog Code
Task-Id: 2ed89933-091b-446c-af91-5cc72d939b3b
diff --git a/packages/agent/src/adapters/claude/permissions/permission-handlers.ts b/packages/agent/src/adapters/claude/permissions/permission-handlers.ts
@@ -9,8 +9,7 @@ import type {
 } from "@anthropic-ai/claude-agent-sdk";
 import { text } from "../../../utils/acp-content";
 import type { Logger } from "../../../utils/logger";
-import { qualifiedLocalToolName } from "../../local-tools";
-import { SPEAK_TOOL_NAME } from "../../local-tools/tools/speak";
+import { AUTO_APPROVED_LOCAL_TOOL_IDS } from "../../local-tools";
 import { toolInfoFromToolUse } from "../conversion/tool-use-to-acp";
 import {
   getMcpToolApprovalState,
@@ -40,8 +39,6 @@ import {
   isPostHogExecTool,
 } from "./posthog-exec-gate";
 
-const SPEAK_TOOL_ID = qualifiedLocalToolName(SPEAK_TOOL_NAME);
-
 export type ToolPermissionResult =
   | {
       behavior: "allow";
@@ -761,10 +758,10 @@ export async function canUseTool(
       return { behavior: "deny", message, interrupt: false };
     }
 
-    // Narration is a fire-and-forget no-op on the agent side; a permission
-    // prompt for it interrupts the user to approve a line they may never hear.
-    // An explicit do_not_use block above still wins.
-    if (toolName === SPEAK_TOOL_ID) {
+    // Auto-approve tools flagged `autoApprove` — read-only or fire-and-forget
+    // (canvas checkout, speak narration) where a permission prompt is pure
+    // friction. An explicit do_not_use block above still wins.
+    if (AUTO_APPROVED_LOCAL_TOOL_IDS.has(toolName)) {
       return {
         behavior: "allow",
         updatedInput: toolInput as Record<string, unknown>,
diff --git a/packages/agent/src/adapters/local-tools/index.ts b/packages/agent/src/adapters/local-tools/index.ts
@@ -1,4 +1,9 @@
-import type { LocalTool, LocalToolCtx, LocalToolGateMeta } from "./registry";
+import {
+  type LocalTool,
+  type LocalToolCtx,
+  type LocalToolGateMeta,
+  qualifiedLocalToolName,
+} from "./registry";
 import { canvasCheckoutTool, canvasPublishTool } from "./tools/canvas";
 import { cloneRepoTool } from "./tools/clone-repo";
 import { listReposTool } from "./tools/list-repos";
@@ -28,6 +33,17 @@ export const LOCAL_TOOLS: LocalTool[] = [
   canvasPublishTool,
 ];
 
+/**
+ * Qualified ids of local tools flagged `autoApprove` — the Claude permission
+ * handler allows these without a prompt. Codex does not prompt for MCP tool
+ * calls, so it does not consult this.
+ */
+export const AUTO_APPROVED_LOCAL_TOOL_IDS: ReadonlySet<string> = new Set(
+  LOCAL_TOOLS.filter((t) => t.autoApprove).map((t) =>
+    qualifiedLocalToolName(t.name),
+  ),
+);
+
 /** Tools whose gate passes for the given context — the set to actually expose. */
 export function enabledLocalTools(
   ctx: LocalToolCtx,
diff --git a/packages/agent/src/adapters/local-tools/registry.ts b/packages/agent/src/adapters/local-tools/registry.ts
@@ -53,6 +53,13 @@ export interface LocalToolDef<S extends z.ZodRawShape> {
    * by default in the Claude adapter (ENABLE_TOOL_SEARCH). Ignored by Codex.
    */
   alwaysLoad?: boolean;
+  /**
+   * Auto-approve this tool's calls without a permission prompt — for read-only
+   * or fire-and-forget tools where prompting is pure friction (an explicit
+   * do_not_use block still wins). Honored by the Claude permission handler;
+   * Codex does not prompt for MCP tool calls, so it is a no-op there.
+   */
+  autoApprove?: boolean;
   isEnabled(ctx: LocalToolCtx, meta: LocalToolGateMeta | undefined): boolean;
   handler(
     ctx: LocalToolCtx,
@@ -66,6 +73,8 @@ export interface LocalTool {
   description: string;
   schema: z.ZodRawShape;
   alwaysLoad?: boolean;
+  /** See {@link LocalToolDef.autoApprove}. */
+  autoApprove?: boolean;
   isEnabled(ctx: LocalToolCtx, meta: LocalToolGateMeta | undefined): boolean;
   handler(
     ctx: LocalToolCtx,
diff --git a/packages/agent/src/adapters/local-tools/tools/canvas.test.ts b/packages/agent/src/adapters/local-tools/tools/canvas.test.ts
@@ -1,4 +1,5 @@
 import { describe, expect, it } from "vitest";
+import { AUTO_APPROVED_LOCAL_TOOL_IDS } from "../index";
 import { canvasScratchDir, canvasScratchFile } from "./canvas";
 
 // Version composition and the stale-base rejection live server-side in the
@@ -12,3 +13,18 @@ describe("canvas scratch paths", () => {
     );
   });
 });
+
+describe("canvas tool permissions", () => {
+  it("auto-approves canvas_checkout (read-only) but not canvas_publish (write)", () => {
+    expect(
+      AUTO_APPROVED_LOCAL_TOOL_IDS.has(
+        "mcp__posthog-code-tools__canvas_checkout",
+      ),
+    ).toBe(true);
+    expect(
+      AUTO_APPROVED_LOCAL_TOOL_IDS.has(
+        "mcp__posthog-code-tools__canvas_publish",
+      ),
+    ).toBe(false);
+  });
+});
diff --git a/packages/agent/src/adapters/local-tools/tools/canvas.ts b/packages/agent/src/adapters/local-tools/tools/canvas.ts
@@ -1,5 +1,7 @@
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import * as path from "node:path";
+import { freeformSystemPromptFor } from "@posthog/shared/canvas-freeform-prompt";
+import { FREEFORM_STARTER_CODE } from "@posthog/shared/canvas-freeform-starter";
 import { z } from "zod";
 import {
   DesktopCanvasVersionConflictError,
@@ -48,6 +50,7 @@ function baseVersionMarkerFile(canvasId: string): string {
 interface CanvasMeta {
   code?: string;
   currentVersionId?: string;
+  templateId?: string;
   [key: string]: unknown;
 }
 
@@ -92,6 +95,43 @@ async function fetchCanvasEntry(canvasId: string): Promise<CanvasFsEntry> {
   return entry;
 }
 
+// Create-if-missing for `canvas_checkout`: an agent working from a normal task
+// (not the channel generate bar) can start a canvas in one call instead of
+// chaining the raw desktop-fs create tool first.
+async function createCanvasEntry(
+  name: string | undefined,
+  parentPath: string | undefined,
+): Promise<CanvasFsEntry> {
+  if (!name?.trim()) {
+    throw new Error(
+      "pass `id` to edit an existing canvas, or `name` to create a new one.",
+    );
+  }
+  const client = createClient();
+  if (!client) {
+    throw new Error("No PostHog credentials available in this session.");
+  }
+  return client.createDesktopCanvas<CanvasFsEntry>({
+    name: name.trim(),
+    parentPath,
+  });
+}
+
+// The freeform authoring rules (allowed imports, the `ph` data shim, style
+// rules) the channel generate bar injects up front. Returned on checkout so an
+// agent editing a canvas from any task authors valid source; an empty canvas
+// also gets the known-good starter scaffold to build on.
+function authoringContract(
+  templateId: string | undefined,
+  isEmpty: boolean,
+): string {
+  const contract = freeformSystemPromptFor(templateId);
+  const starter = isEmpty
+    ? `\n\nStarter scaffold — write this working baseline to the scratch file first, then build by editing it:\n\n\`\`\`tsx\n${FREEFORM_STARTER_CODE}\n\`\`\``
+    : "";
+  return `Authoring contract for this canvas (imports, the \`ph\` data shim, and style rules):\n\n${contract}${starter}`;
+}
+
 function readMarker(canvasId: string): BaseVersionMarker | undefined {
   try {
     return JSON.parse(
@@ -119,32 +159,56 @@ const CONFLICT_MESSAGE = (canvasId: string) =>
 export const canvasCheckoutTool = defineLocalTool({
   name: "canvas_checkout",
   description:
-    "Check out a PostHog canvas (a freeform React desktop-fs dashboard) for editing: fetches the live " +
-    "source, writes it to a local scratch file, and records the version your edits are based on. " +
-    "Returns the file path. Edit that file with your normal file-editing tools, then call " +
-    "canvas_publish to save. Always start canvas work with this tool.",
+    "Check out a PostHog canvas (a freeform React desktop-fs dashboard) for editing. Pass `id` to edit " +
+    "an existing canvas, or omit `id` and pass `name` to create a fresh one. Fetches (or creates) the " +
+    "canvas, writes its source to a local scratch file, records the base version for the publish-time " +
+    "concurrency guard, and returns the scratch path plus the authoring contract to follow. Edit that " +
+    "file with your normal file-editing tools, then call canvas_publish. Always start canvas work with " +
+    "this tool.",
   schema: {
-    id: z.string().describe("The canvas (desktop-fs dashboard row) id."),
+    id: z
+      .string()
+      .optional()
+      .describe(
+        "Existing canvas (desktop-fs dashboard row) id to edit. Omit to create a new canvas via `name`.",
+      ),
+    name: z
+      .string()
+      .optional()
+      .describe(
+        "Name for a NEW canvas when `id` is omitted — creates it, then checks it out.",
+      ),
+    parentPath: z
+      .string()
+      .optional()
+      .describe(
+        "Optional desktop-fs folder path to create the new canvas under (e.g. a channel folder). Defaults to the top level.",
+      ),
   },
   alwaysLoad: true,
+  autoApprove: true,
   isEnabled: () => resolveSandboxPosthogApi() !== undefined,
   handler: async (_ctx, args): Promise<LocalToolResult> => {
     try {
-      const entry = await fetchCanvasEntry(args.id);
-      const file = canvasScratchFile(args.id);
+      const entry = args.id
+        ? await fetchCanvasEntry(args.id)
+        : await createCanvasEntry(args.name, args.parentPath);
+      const canvasId = entry.id;
+      const file = canvasScratchFile(canvasId);
       const code = entry.meta?.code ?? "";
-      mkdirSync(canvasScratchDir(args.id), { recursive: true });
+      mkdirSync(canvasScratchDir(canvasId), { recursive: true });
       writeFileSync(file, code);
-      writeMarker(args.id, {
+      writeMarker(canvasId, {
         versionId: entry.meta?.currentVersionId,
         fetchedAt: Date.now(),
       });
       const lines = code ? code.split("\n").length : 0;
-      const text = code
-        ? `Checked out canvas "${entry.path}" to ${file} (${lines} lines, base version ${
+      const header = code
+        ? `Checked out canvas "${entry.path}" (id ${canvasId}) to ${file} (${lines} lines, base version ${
             entry.meta?.currentVersionId ?? "none"
-          }).\nApply your changes by editing that file, then call canvas_publish with id "${args.id}".`
-        : `Canvas "${entry.path}" is empty. Author the complete single-file React app at ${file}, then call canvas_publish with id "${args.id}".`;
+          }). Edit that file, then call canvas_publish with id "${canvasId}".`
+        : `Canvas "${entry.path}" (id ${canvasId}) is empty — author the complete single-file React app at ${file}, then call canvas_publish with id "${canvasId}".`;
+      const text = `${header}\n\n${authoringContract(entry.meta?.templateId, !code)}`;
       return { content: [{ type: "text", text }] };
     } catch (err) {
       return errorResult(
diff --git a/packages/agent/src/adapters/local-tools/tools/speak.ts b/packages/agent/src/adapters/local-tools/tools/speak.ts
@@ -59,6 +59,7 @@ export const speakTool = defineLocalTool({
   description: SPEAK_TOOL_DESCRIPTION,
   schema: speakSchema,
   alwaysLoad: true,
+  autoApprove: true,
   isEnabled: (_ctx, meta) => meta?.spokenNarration === true,
   handler: async (): Promise<LocalToolResult> => {
     return { content: [{ type: "text", text: "ok" }] };
diff --git a/packages/agent/src/posthog-api.ts b/packages/agent/src/posthog-api.ts
@@ -364,6 +364,31 @@ export class PostHogAPIClient {
     return response.json() as Promise<T>;
   }
 
+  /**
+   * Create a new freeform canvas ("dashboard" row) on the desktop surface and
+   * return the created entry (with its id). `parentPath` nests it under a
+   * folder (e.g. a channel); omit it for a top-level canvas.
+   */
+  async createDesktopCanvas<T>(input: {
+    name: string;
+    parentPath?: string;
+  }): Promise<T> {
+    const teamId = this.getTeamId();
+    const parent = input.parentPath?.replace(/\/+$/, "");
+    const path = parent ? `${parent}/${input.name}` : input.name;
+    const response = await this.performRequestWithRetry(
+      `/api/projects/${teamId}/desktop_file_system/`,
+      {
+        method: "POST",
+        body: JSON.stringify({ path, type: "dashboard", meta: {} }),
+      },
+    );
+    if (!response.ok) {
+      throw new Error(`Failed to create canvas (${response.status})`);
+    }
+    return response.json() as Promise<T>;
+  }
+
   /**
    * Publish a freeform canvas's source via the desktop-fs canvas action. The
    * server owns version composition (appends the full-file snapshot, moves
diff --git a/packages/core/src/canvas/freeformSchemas.ts b/packages/core/src/canvas/freeformSchemas.ts
@@ -4,7 +4,8 @@ import { z } from "zod";
 // generation path can resolve the right system prompt.
 
 // A single point in a freeform canvas's edit history. Every agent turn appends
-// one full-file snapshot (Q7: full-file rewrite); the user can revert to any of
+// one full-file snapshot (the agent edits a local scratch copy incrementally,
+// then publishes the finished file wholesale); the user can revert to any of
 // them and the `currentVersionId` pointer is what publishes. We keep whole-file
 // snapshots rather than diffs because canvases are small and a snapshot can
 // never fail to reconstruct.
diff --git a/packages/ui/src/features/canvas/AGENTS.md b/packages/ui/src/features/canvas/AGENTS.md
@@ -80,11 +80,13 @@ The root `AGENTS.md` architecture rules still apply.
   version composition server-side and accepts an optional
   `expected_current_version_id`: a publish based on a stale version (a
   concurrent edit or undo) is rejected 409 inside the row lock instead of
-  clobbering the newer head. The **agent publish path uses that guard**:
-  generation works the source as a local scratch file via the
-  `canvas_checkout` / `canvas_publish` local tools (`@posthog/agent`,
-  `adapters/local-tools/tools/canvas.ts`) — checkout records the fetched
-  `currentVersionId`, publish passes it as the expected version (backends
+  clobbering the newer head. The **agent edit path uses that guard**: the agent
+  works the source as a local scratch file via the `canvas_checkout` /
+  `canvas_publish` local tools (`@posthog/agent`,
+  `adapters/local-tools/tools/canvas.ts`) — `canvas_checkout` fetches an
+  existing canvas (or creates one from a `name`), writes the scratch file,
+  records the fetched `currentVersionId`, and returns the authoring contract;
+  `canvas_publish` passes that version as the expected version (backends
   predating the field ignore it and publish unguarded). **User-side saves**
   (`saveFreeform`) are still last-write-wins; adopt the same guard if
   multi-client editing becomes real.
diff --git a/packages/workspace-server/src/services/agent/agent.ts b/packages/workspace-server/src/services/agent/agent.ts
@@ -673,6 +673,14 @@ If a repository IS genuinely required, attach one in this priority order:
 1. **Reuse a folder the user already has locally.** ${localFolders.length ? "Pick the one that best matches the request and the channel CONTEXT.md, then `cd` into its absolute path and do all git and file work there. It is already on disk — do NOT clone it again." : "If the user names a folder or path, `cd` into that absolute path and work there."}
 2. **If you can't confidently pick one** (none clearly match, or it's ambiguous), use the AskUserQuestion tool to ask the user which local folder to use, or for the path where the folder lives on this machine. Do not guess.
 3. **Only as a last resort** — when the user has no local copy, or explicitly wants a fresh checkout — clone from remote. Call \`list_repos\` to see what's available (prefer repos named in CONTEXT.md), then **confirm with the user via AskUserQuestion before cloning**, and use \`clone_repo\` (pass \`owner/repo\`); it clones into a subdirectory of your working directory and returns the path to \`cd\` into.${localFoldersBlock}`;
+
+      prompt += `
+
+## Canvases
+A canvas is an agent-authored single-file React app that lives in PostHog (a desktop-fs "dashboard" row), not a file on disk. Build and edit canvases only through the \`canvas_checkout\` / \`canvas_publish\` tools (posthog-code-tools) — never publish canvas source through the raw PostHog MCP:
+- Edit an existing canvas: \`canvas_checkout\` with its id, edit the scratch file it writes, then \`canvas_publish\`.
+- Create a new canvas: \`canvas_checkout\` with a \`name\` (omit the id), author the scratch file, then \`canvas_publish\`.
+\`canvas_checkout\` returns the authoring contract (allowed imports, the \`ph\` data shim, style rules) — follow it. Editing through these tools is what applies the scratch-file workflow and the publish-time concurrency guard.`;
     }
 
     if (customInstructions) {
