codecaine-cli 0.0.0-stage → 0.1.2

package/dist/resources/bb-plugin/src/server.ts

@@ -0,0 +1,1084 @@
+/**
+ * bb-plugin-canvas-editor — the canvas editor's layer tools, inside bb.
+ *
+ * WHY a plugin at all: bb has no user-configurable MCP servers, so there is no
+ * per-run `--mcp-config` to hand a coding agent. `bb.agents.registerTool` is the
+ * sanctioned way to put tools in front of whichever provider CLI the user has
+ * authenticated, and a plugin is the only thing allowed to call it.
+ *
+ * WHY the HTTP hop: this file is loaded inside the *bb server process*. That
+ * process has no handle on the editor's renderer, where the document actually
+ * lives — so every execute() posts to the loopback endpoint the editor opened
+ * for us (`electron/bb/tool-server.ts`), which fans the call out to whichever
+ * open project answers for that workspace:
+ *
+ *   provider ─► bb ─► execute() ─POST /tool─► editor main
+ *                                              └─► renderer relay ─► canvas API
+ *
+ * The editor hands us that endpoint's URL and bearer token by calling our own
+ * `POST /config` route once per session. Nothing is persisted: the token is
+ * per-session, and a bb server that outlives the editor must fail loudly rather
+ * than keep a stale secret around.
+ *
+ * Typed against `@get-bb/plugin-sdk` (verified against bb-app 0.42.1). The
+ * import is types-only and erased before bb loads this file, so the package
+ * does not have to be installed for the plugin to run — which is the point:
+ * this directory is registered with bb by path and has no node_modules of its
+ * own.
+ */
+
+import { mkdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { BbPluginApi, PluginAgentToolResult } from "@get-bb/plugin-sdk";
+import { frameOfLiveId, layerSnapshot, SNAPSHOT_MAX_LAYERS } from "./snapshot.js";
+import { CANVAS_TOOLS, FRAMES_TOOLS, SCREENSHOT_TOOL } from "./tools.js";
+
+/** Where the editor's tool server lives, as handed over by POST /config. */
+interface CallbackTarget {
+  /** Base URL with no trailing slash, e.g. "http://127.0.0.1:51234". */
+  url: string;
+  token: string;
+}
+
+/**
+ * Screenshots are spilled to the OS temp dir rather than into an app-owned
+ * folder: the editor has no directory it prunes on launch (unlike ui-editor's
+ * voice temp), and inventing one would mean inventing its retention policy too.
+ * The OS already sweeps this one.
+ */
+const SHOT_DIR = join(tmpdir(), "canvas-agent-shots");
+
+/**
+ * A tool call answered by the wrong document is worse than one that fails: the
+ * model silently edits somebody else's design. A thread's workspace path is
+ * learned from `bb.agents.configure` — the per-call tool context carries
+ * threadId and projectId but no path — so that callback doubles as the place
+ * the mapping is recorded. It runs when a turn starts, so after a restart the
+ * project's folder, as the editor's pushes name it, stands in (`pathByProject`).
+ */
+const MAX_TRACKED_THREADS = 512;
+
+/** Waits between attempts at the editor after a refused connection — about
+ *  four seconds in all, long enough for an editor that is restarting its
+ *  endpoint to push the new one, short enough not to stall a turn. */
+const EDITOR_RETRY_DELAYS_MS = [250, 750, 1500, 2000];
+/** How long a call waits for an editor to push its address when there is none
+ *  yet, and how often it looks. */
+const CALLBACK_WAIT_MS = 4_000;
+const CALLBACK_POLL_MS = 200;
+
+/** Sleep, or resolve false at once if the turn is cancelled. */
+function pause(ms: number, signal?: AbortSignal): Promise<boolean> {
+  if (signal?.aborted) return Promise.resolve(false);
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve(true);
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      resolve(false);
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+/**
+ * Standing instructions, per bb project — the editor's "system prompt".
+ *
+ * Per project rather than one global string because the editor keeps them in
+ * the project's own settings, so two projects open against one bb server must
+ * not overwrite each other's. Bounded for the same reason as the thread map: a
+ * long-lived server sees unboundedly many projects.
+ */
+const MAX_TRACKED_PROJECTS = 256;
+
+/**
+ * How much of the two per-turn contributions can be sent.
+ *
+ * bb truncates a plugin's contributed instructions past 4096 characters, and a
+ * prompt that silently loses its last paragraph is worse than one that was
+ * never that long. The project's own instructions are kept whole and the
+ * selection block is what gives way — it is regenerable, since the assistant
+ * can call `getSelection` for the same answer.
+ */
+const MAX_INSTRUCTIONS = 4096;
+/** Layers named in the per-turn selection block before it summarises. */
+const MAX_SELECTION_LAYERS = 12;
+
+/** The per-turn line about the board's selection. Names for a person reading
+ *  the transcript, ids for the model to call `getLayer` and `updateLayer`
+ *  with. */
+/**
+ * Where an element inside a running project actually is.
+ *
+ * A layer of the design is a node id and that is the whole answer. An element
+ * of somebody's running application is not: its id is a handle this session
+ * issued, meaningless in a codebase, and the editor's tools can only write a
+ * stylesheet held *over* the page — which the next build throws away. So this
+ * carries the other vocabulary, and says what to do with it.
+ */
+interface LiveElement {
+  address?: unknown;
+  selector?: unknown;
+  path?: unknown;
+  tag?: unknown;
+  component?: unknown;
+  band?: unknown;
+  maxWidth?: unknown;
+  state?: unknown;
+}
+
+function liveLine(layer: { name?: unknown; live?: LiveElement }): string | null {
+  const live = layer.live;
+  if (!live || typeof live.selector !== "string") return null;
+  const named =
+    (typeof layer.name === "string" && layer.name) ||
+    (typeof live.component === "string" && live.component) ||
+    (typeof live.tag === "string" && live.tag) ||
+    "an element";
+  let line =
+    `${named} — inside the page running at ${typeof live.address === "string" ? live.address : "the project"}, ` +
+    `found by the CSS selector \`${live.selector}\``;
+  if (typeof live.path === "string") line += ` (path: ${live.path})`;
+  if (typeof live.component === "string") line += `, rendered by the React component \`${live.component}\``;
+  if (typeof live.band === "string" && typeof live.maxWidth === "number") {
+    line += `, being designed at ${live.band} — @media (max-width: ${live.maxWidth}px) and narrower`;
+  }
+  if (typeof live.state === "string" && live.state) {
+    line += `, in its \`:${live.state}\` state`;
+  }
+  return line + ".";
+}
+
+/** What every live element in a selection has in common, said once. */
+const LIVE_RULE =
+  "Those are elements of a running application, not layers of this design. The layer tools reach them, and what they write is a stylesheet the editor holds OVER the page: it looks right and it is discarded the moment the page is rebuilt from its source. A change the person means to keep is a change to the code — find the element by its selector and edit whatever renders it. Use the layer tools there only to look, or to show them what a change would look like before you write it. Check it in light and dark mode.";
+
+/** LIVE_RULE in the room the default instructions leave — about 800
+ *  characters, which one live element's line plus the full rule overran. */
+const LIVE_RULE_SHORT =
+  "Those are elements of a running app: a layer-tool edit to them is discarded when the page rebuilds, so a lasting change goes in its source, checked in light and dark. Layers of this design are edited with the layer tools.";
+
+/**
+ * The selection cut to `room` characters, keeping what matters most.
+ *
+ * Over bb's cap the whole block used to be dropped, and with the default
+ * instructions any selection holding a live element was over it — so the
+ * one turn that most needed the live rule never got it. Shorter rule first,
+ * then no per-element lines, then the head alone.
+ */
+export function fitSelection(selection: string, room: number): string | null {
+  if (selection.length <= room) return selection;
+  const short = selection.replace(LIVE_RULE, LIVE_RULE_SHORT);
+  if (short.length <= room) return short;
+  const head = selection.split("\n")[0] ?? "";
+  const headAndRule = selection.includes(LIVE_RULE) ? `${head}\n\n${LIVE_RULE_SHORT}` : head;
+  if (headAndRule.length <= room) return headAndRule;
+  return head.length <= room ? head : null;
+}
+
+function selectionBlock(layers: readonly unknown[]): string {
+  const live: string[] = [];
+  const named = layers
+    .slice(0, MAX_SELECTION_LAYERS)
+    .map((entry) => {
+      const layer = (entry ?? {}) as {
+        id?: unknown;
+        name?: unknown;
+        type?: unknown;
+        live?: LiveElement;
+      };
+      const id = typeof layer.id === "string" ? layer.id : "?";
+      const name =
+        (typeof layer.name === "string" && layer.name) ||
+        (typeof layer.type === "string" && layer.type) ||
+        "layer";
+      const line = liveLine(layer);
+      if (line) live.push(line);
+      return `${name} (${id})`;
+    })
+    .join(", ");
+  const rest = layers.length - MAX_SELECTION_LAYERS;
+  const tail = rest > 0 ? `, and ${rest} more — call getSelection for all of them` : "";
+  const head =
+    `The person currently has ${layers.length} layer${layers.length === 1 ? "" : "s"} selected on the board: ` +
+    `${named}${tail}. When they say "this", "these" or "the selection", that is what they mean. ` +
+    `The selection changes as they work — call getSelection if you need it again later in the conversation.`;
+  if (live.length === 0) return head;
+  return [head, "", ...live.map((line) => `- ${line}`), "", LIVE_RULE].join("\n");
+}
+
+/**
+ * How to reach this design — the plugin's own word on it, not the project's.
+ *
+ * Returned from `configure`, which bb pushes into the thread's instructions as
+ * a section of its own. Deliberately NOT part of the project's editable system
+ * prompt: that budget belongs to the person, this is the plugin saying what its
+ * tools are, and the two must not compete for the same 4096 characters.
+ *
+ * It exists because of what a coding agent does when it has a machine's whole
+ * tool surface in front of it. Somebody asked "rewrite the text in this frame"
+ * and watched the assistant reach for `mcp__pencil__get_app_state` — another
+ * design application's MCP server, which cannot see this board — and then
+ * explain the failure with it, inventing a connection that had to be restarted.
+ *
+ * **The prefix is the trap, and it cuts both ways.** For an ACP provider bb
+ * hands a plugin's tools over as a session MCP server of its own, named
+ * `bb-bridge` (`ACP_BRIDGE_MCP_SERVER_NAME`, @get-bb/plugin-sdk) — so these
+ * tools arrive as `mcp__bb-bridge__listLayers` and the like. A rule saying
+ * "never call an mcp__ tool" therefore tells the model to refuse the very tools
+ * this plugin exists to give it. What separates ours from somebody else's is
+ * the *name*, never the prefix.
+ */
+export const CANVAS_TOOL_GUIDE = [
+  "THE DESIGN ON THE BOARD IS REACHED THROUGH THESE TOOLS, BY THESE NAMES:",
+  CANVAS_TOOLS.map((tool) => tool.name).join(", ") + ".",
+  "Your provider may show them prefixed — `mcp__bb-bridge__listLayers` — as bb hands them " +
+    "over as a session MCP server named `bb-bridge`. Prefixed or not, they are the editor's own, " +
+    "already connected: there is nothing to start, connect, configure or open first.",
+  "It is the NAME that makes a tool this design's, never the prefix. A tool not listed above " +
+    "does not touch this design, however it sounds. " +
+    "Never use one for work on this board, or to explain a failure on it.",
+  "THE BOARD SHOWS WHAT YOU ARE DOING. Every write you make already puts a band of colour round " +
+    "the layer for a few seconds. holdLayer is the longer claim: it keeps a layer for a " +
+    "whole job, says what you are doing to it, and refuses the person's edits meanwhile. Take one " +
+    "before your first change when you are REWRITING it — redesigning, restyling, replacing its " +
+    "insides — so nobody edits under a half-applied change. Reading takes nothing; " +
+    "nor do variants BESIDE one, which are new layers.",
+  "Release before your turn ends even " +
+    "when you are giving up, a tool failed, or you are handing the question back — say so. " +
+    "askAboutLayer keeps the hold and puts your question on the board; holdLayer picks " +
+    "it back up. The person can take a layer back with the button beside its name, and a hold whose " +
+    "assistant goes quiet frees itself; getLayer reports the run on a layer, and an edit to one no longer held still lands.",
+  "If a tool reports it cannot reach the editor, the tool has already retried: report its " +
+    "message as it stands — do not assume more than it says — and stop. If the tools are missing from this session altogether, say " +
+    "THAT, plainly, first. In neither case substitute another " +
+    "application's tools or edit the design's files: the editor overwrites them.",
+  "WRITE ORDINARY WEB MARKUP. replaceLayer and insertHtml take any HTML — sections, tables, " +
+    "svg, canvas, forms with real inputs. Lay it out with flexbox and grid, which the inspector " +
+    "edits; absolute positioning only on the outermost element the board places. Linked stylesheets are ignored. " +
+    "Behaviour goes on a layer in a webpage (updateLayer's `script`, or script tags in markup) " +
+    "and runs in Interact and Preview with `element` as that layer, never on the canvas.",
+  "TO SEE AN EFFECT WORK: setPageView (in-view, motion playing), then observePage to read it or " +
+    "canvasPointer to use it with a real mouse. Restructure as a drag would with moveLayer, " +
+    "groupLayers and duplicateLayers.",
+  "A LIVE PROJECT ON THIS MACHINE (localhost, LAN): a change asked for there is done only once " +
+    "SAVED in its source — a layer-tool edit is discarded at the next rebuild. Write it as the " +
+    "project's own code: the component or stylesheet that renders it, its Tailwind classes and " +
+    "theme variables, no inline styles or hard-coded colours. Then check LIGHT AND DARK MODE: " +
+    "every colour from a token with a value for each (listVariables; a new one gets both), and " +
+    "look at the page in each (setPageView theme light, then dark, then system) before saying done. A page " +
+    "served from the web has no source here: say so.",
+  "COPYING BETWEEN LIVE PROJECTS: a copy is the original, never a redesign. Read it in its " +
+    "source project first; keep its markup, words, data and look. Each colour, size, radius, " +
+    "shadow and font becomes var(--name) holding that same value: the target's own " +
+    "(listVariables) only if equal, else a new one (setVariable).",
+  "Start by looking: getSelection is what the person is pointing at when they say \"this\"; " +
+    "listLayers gives bearings; listVariables gives the design " +
+    "system behind it — change a shared colour there, not on every layer.",
+].join("\n\n");
+
+function toolResult(text: string, isError = false): PluginAgentToolResult {
+  return { content: [{ type: "text", text }], isError };
+}
+
+/** Only ever point the plugin at the local machine. The /config route is
+ *  `auth: "local"` already, but this endpoint receives a bearer token and would
+ *  otherwise be a one-request exfiltration relay for anything that reached the
+ *  route by some other path. */
+function isLoopbackUrl(raw: string): boolean {
+  let parsed: URL;
+  try {
+    parsed = new URL(raw);
+  } catch {
+    return false;
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return false;
+  const host = parsed.hostname.replace(/^\[|\]$/g, "");
+  return host === "127.0.0.1" || host === "localhost" || host === "::1";
+}
+
+export default function plugin(bb: BbPluginApi) {
+  let callback: CallbackTarget | null = null;
+
+  /**
+   * Take the editor's callback from any push that carries one.
+   *
+   * Every route below accepts `{url, token}`, not just /config, and that is the
+   * whole repair strategy for this plugin's one real failure: everything it
+   * knows lives in memory, and bb restarts a plugin host whenever it reloads,
+   * updates or re-installs. Before this, a restart left the tools registered
+   * and permanently unreachable — the agent would be told the editor was not
+   * connected, and (having a shell) would go and edit the design's files
+   * instead. Now the next selection change or settings save puts it back.
+   */
+  function adoptCallback(record: { url?: unknown; token?: unknown }): boolean {
+    const url =
+      typeof record.url === "string" ? record.url.trim().replace(/\/+$/, "") : "";
+    const token = typeof record.token === "string" ? record.token : "";
+    if (!url || !token || !isLoopbackUrl(url)) return false;
+    if (callback?.url !== url || callback.token !== token) {
+      bb.log.info(`canvas layer tools connected to the editor at ${url}`);
+    }
+    callback = { url, token };
+    return true;
+  }
+  /** threadId → the environment path bb is running that thread in. */
+  const workspaceByThread = new Map<string, string>();
+  /**
+   * bb projectId → the folder the editor has that project open from, as the
+   * editor itself says on every push.
+   *
+   * The fallback for `workspaceByThread`, which only `configure()` fills — and
+   * that runs when a turn starts, so a plugin host bb restarted mid-turn came
+   * back with it empty and every call after carried no path. A push is what
+   * repairs a restarted plugin (see /state), so it brings this back too. Only
+   * a fallback: a thread in a worktree runs somewhere else, and says so.
+   */
+  const pathByProject = new Map<string, string>();
+  /** bb projectId → what the editor wants the assistant told first. */
+  const instructionsByProject = new Map<string, string>();
+  /** bb projectId → what is selected on that project's board right now. */
+  const selectionByProject = new Map<string, string>();
+  let shotSeq = 0;
+
+  /**
+   * Keep one project's entry, evicting the oldest once the server has seen
+   * more projects than it will hold.
+   *
+   * An empty value deletes rather than keeps the last one: somebody who
+   * cleared the instructions box wants the assistant told nothing, and
+   * somebody who deselected is pointing at nothing — in both cases the stale
+   * answer is worse than no answer.
+   */
+  function remember(
+    map: Map<string, string>,
+    projectId: string,
+    value: string,
+  ): void {
+    if (!value) {
+      map.delete(projectId);
+      return;
+    }
+    if (map.size >= MAX_TRACKED_PROJECTS && !map.has(projectId)) {
+      const oldest = map.keys().next();
+      if (!oldest.done) map.delete(oldest.value);
+    }
+    map.set(projectId, value);
+  }
+
+  /** Record the folder a push names for its project. Never cleared by a push
+   *  that leaves it out: most of them are about something else. */
+  function adoptPath(projectId: string, record: { path?: unknown }): void {
+    const path = typeof record.path === "string" ? record.path.trim() : "";
+    if (projectId && path) remember(pathByProject, projectId, path);
+  }
+
+  /**
+   * POST /api/v1/plugins/canvas-editor/http/config  { url, token }
+   *
+   * "local" auth checks Origin/Host against bb's own app origins and, for a
+   * mutation, requires a JSON content-type. A Node `fetch` sends no Origin
+   * header at all, so the editor's call passes; the content-type requirement is
+   * what stops a browser from forging this one.
+   */
+  bb.http.route(
+    "POST",
+    "/config",
+    async (context) => {
+      let body: unknown;
+      try {
+        body = await context.req.json();
+      } catch {
+        body = null;
+      }
+      const record = (body ?? {}) as { url?: unknown; token?: unknown };
+      const url =
+        typeof record.url === "string"
+          ? record.url.trim().replace(/\/+$/, "")
+          : "";
+      const token = typeof record.token === "string" ? record.token : "";
+      if (!url || !token) {
+        return context.json(
+          { ok: false, error: "body must be { url, token }" },
+          400,
+        );
+      }
+      if (!isLoopbackUrl(url)) {
+        return context.json(
+          { ok: false, error: `url must be a loopback address, got "${url}"` },
+          400,
+        );
+      }
+      adoptCallback({ url, token });
+      return context.json({
+        ok: true,
+        tools: CANVAS_TOOLS.map((tool) => tool.name),
+      });
+    },
+    { auth: "local" },
+  );
+
+  /**
+   * POST /api/v1/plugins/canvas-editor/http/instructions  { projectId, instructions, path? }
+   *
+   * The editor's standing instructions for one project, pushed when the panel
+   * opens and again whenever somebody edits them in Project settings. Kept
+   * here rather than in bb's own per-thread instructions because they belong to
+   * the editor's project file, travel with it, and must apply to a conversation
+   * the user has not started yet.
+   */
+  bb.http.route(
+    "POST",
+    "/instructions",
+    async (context) => {
+      let body: unknown;
+      try {
+        body = await context.req.json();
+      } catch {
+        body = null;
+      }
+      const record = (body ?? {}) as {
+        projectId?: unknown;
+        instructions?: unknown;
+        path?: unknown;
+        url?: unknown;
+        token?: unknown;
+      };
+      adoptCallback(record);
+      const projectId =
+        typeof record.projectId === "string" ? record.projectId.trim() : "";
+      if (!projectId) {
+        return context.json(
+          { ok: false, error: "body must be { projectId, instructions }" },
+          400,
+        );
+      }
+      adoptPath(projectId, record);
+      const instructions =
+        typeof record.instructions === "string" ? record.instructions.trim() : "";
+      remember(instructionsByProject, projectId, instructions);
+      if (!instructions) return context.json({ ok: true, cleared: true });
+      bb.log.info(`canvas instructions set for project ${projectId}`);
+      return context.json({ ok: true, length: instructions.length });
+    },
+    { auth: "local" },
+  );
+
+  /**
+   * POST /api/v1/plugins/canvas-editor/http/selection  { projectId, layers, path? }
+   *
+   * What the person is pointing at, pushed by the editor whenever the board's
+   * selection changes. It becomes part of the next turn's instructions, which
+   * is what makes "make this bigger" a sentence the assistant can act on
+   * without anybody typing an id.
+   *
+   * Pushed rather than pulled because `contributeInstructions` has to answer
+   * synchronously, on the thread-start path — there is no room there to ask the
+   * editor and wait.
+   */
+  bb.http.route(
+    "POST",
+    "/selection",
+    async (context) => {
+      let body: unknown;
+      try {
+        body = await context.req.json();
+      } catch {
+        body = null;
+      }
+      const record = (body ?? {}) as {
+        projectId?: unknown;
+        layers?: unknown;
+        path?: unknown;
+        url?: unknown;
+        token?: unknown;
+      };
+      // A selection changes often, which is what makes it the best repair
+      // signal this plugin has: it is the push most likely to arrive first
+      // after bb restarted the plugin host.
+      adoptCallback(record);
+      const projectId =
+        typeof record.projectId === "string" ? record.projectId.trim() : "";
+      if (!projectId) {
+        return context.json(
+          { ok: false, error: "body must be { projectId, layers }" },
+          400,
+        );
+      }
+      adoptPath(projectId, record);
+      const layers = Array.isArray(record.layers) ? record.layers : [];
+      remember(
+        selectionByProject,
+        projectId,
+        layers.length === 0 ? "" : selectionBlock(layers),
+      );
+      return context.json({ ok: true, count: layers.length });
+    },
+    { auth: "local" },
+  );
+
+  /**
+   * POST /api/v1/plugins/canvas-editor/http/state
+   *   { url?, token?, projectId?, instructions?, layers?, path? }
+   *
+   * Say what this plugin is holding — and take everything the caller knows on
+   * the way in.
+   *
+   * The reporting half is what lets the panel say "not connected to the board"
+   * instead of leaving somebody to find that out from a tool call that failed
+   * mid-conversation. The *writing* half is the fix for the failure that
+   * reporting alone only made visible: everything here lives in memory, bb
+   * restarts a plugin host whenever it reloads or updates one, and the pushes
+   * that fill these maps happen on *change* — a settings save, a new
+   * selection. So a restart left a project with no instructions and no
+   * selection until somebody happened to change one, and "make this bigger"
+   * quietly meant nothing in between.
+   *
+   * The editor therefore sends its whole picture with every check, and this
+   * route applies it. Only keys that are actually present are applied, so a
+   * bare `{}` — the diagnostic anybody would reach for — still just reports.
+   */
+  bb.http.route(
+    "POST",
+    "/state",
+    async (context) => {
+      let body: unknown;
+      try {
+        body = await context.req.json();
+      } catch {
+        body = null;
+      }
+      const record = (body ?? {}) as {
+        projectId?: unknown;
+        instructions?: unknown;
+        layers?: unknown;
+        path?: unknown;
+        url?: unknown;
+        token?: unknown;
+      };
+      adoptCallback(record);
+      const projectId =
+        typeof record.projectId === "string" ? record.projectId.trim() : "";
+      if (projectId) {
+        adoptPath(projectId, record);
+        if (typeof record.instructions === "string") {
+          remember(instructionsByProject, projectId, record.instructions.trim());
+        }
+        if (Array.isArray(record.layers)) {
+          remember(
+            selectionByProject,
+            projectId,
+            record.layers.length === 0 ? "" : selectionBlock(record.layers),
+          );
+        }
+      }
+      return context.json({
+        ok: true,
+        connected: callback !== null,
+        projects: [...new Set([
+          ...instructionsByProject.keys(),
+          ...selectionByProject.keys(),
+        ])].map((id) => ({
+          projectId: id,
+          instructions: (instructionsByProject.get(id) ?? "").length,
+          selection: (selectionByProject.get(id) ?? "").length,
+        })),
+      });
+    },
+    { auth: "local" },
+  );
+
+  /** Resolve once the editor has pushed an address, or with null after
+   *  CALLBACK_WAIT_MS or an abort. Polled: the address is a plain variable
+   *  several routes write, and a call in this gap is rare. */
+  async function waitForCallback(
+    signal?: AbortSignal,
+  ): Promise<CallbackTarget | null> {
+    const until = Date.now() + CALLBACK_WAIT_MS;
+    while (callback === null && Date.now() < until) {
+      if (!(await pause(CALLBACK_POLL_MS, signal))) return null;
+    }
+    return callback;
+  }
+
+  /** One tool call, round-tripped through the editor. Transport faults come
+   *  back as `{ error }` so the model sees a recoverable tool failure rather
+   *  than a crashed turn. */
+  async function callEditor(
+    tool: string,
+    params: unknown,
+    ctx: { threadId?: string | null; projectId?: string | null; signal?: AbortSignal },
+  ): Promise<{ result?: unknown; error?: string }> {
+    // A project just created or opened pushes its address a beat after bb
+    // starts the thread, and an editor that restarted its endpoint pushes a
+    // new one; a call landing in that gap used to fail on the first try and
+    // the model told the person to reopen a window that was open. So a
+    // missing address is waited for briefly, and a refused connection is
+    // retried against whatever address is current by then.
+    let response: Response | null = null;
+    let lastError: unknown = null;
+    for (let attempt = 0; attempt < EDITOR_RETRY_DELAYS_MS.length + 1; attempt++) {
+      if (attempt > 0) {
+        if (!(await pause(EDITOR_RETRY_DELAYS_MS[attempt - 1], ctx.signal))) break;
+      }
+      const target = callback ?? (await waitForCallback(ctx.signal));
+      if (target === null) break;
+      try {
+        response = await fetch(`${target.url}/tool`, {
+          method: "POST",
+          headers: {
+            "content-type": "application/json",
+            authorization: `Bearer ${target.token}`,
+          },
+          body: JSON.stringify({
+            tool,
+            params:
+              params && typeof params === "object" && !Array.isArray(params)
+                ? params
+                : {},
+            // Routes the call to the project that owns this thread's workspace;
+            // with an empty string the editor can only guess (see relay.ts).
+            cwd:
+              (ctx.threadId ? workspaceByThread.get(ctx.threadId) : undefined) ??
+              (ctx.projectId ? pathByProject.get(ctx.projectId) : undefined) ??
+              "",
+          }),
+          ...(ctx.signal ? { signal: ctx.signal } : {}),
+        });
+      } catch (error) {
+        lastError = error;
+        if (ctx.signal?.aborted) break;
+        continue;
+      }
+      // A stale token while a newer address has already arrived is the
+      // editor having restarted under this call: try the new one.
+      if (response.status === 401 && callback !== null && callback !== target) {
+        response = null;
+        continue;
+      }
+      if (response.status === 401 && callback === target) callback = null;
+      break;
+    }
+    if (response === null && lastError === null) {
+      return {
+        error:
+          "The canvas editor is not reachable: the window holding this design is " +
+          "not open — the project was closed, or the app restarted. Tell the " +
+          "person that, and stop. If it IS open, clicking into this chat hands " +
+          "the address back, so sending the message again is all it takes (the " +
+          "Agent panel also shows a banner with Reconnect). Do not guess at " +
+          "another cause and do not try another application's tools: this is not " +
+          "MCP, there is nothing to restart, and a new thread changes nothing. Do " +
+          "NOT edit the design's files instead — the editor holds the document in " +
+          "memory and overwrites them, so that work would be discarded.",
+      };
+    }
+    if (response === null) {
+      // Every retry failed. The editor moved or went away: its endpoint is
+      // per session, and a bb server outlives editors. Drop the address
+      // rather than keep failing against it — that is what makes the panel's
+      // own indicator say "can't reach this board", and the next push from a
+      // live editor puts a working one back.
+      callback = null;
+      return {
+        error:
+          `could not reach the canvas editor (${lastError instanceof Error ? lastError.message : String(lastError)}). ` +
+          "The usual cause is the editor window for this design being closed. " +
+          "Report that message as it stands rather than guessing, and ask the " +
+          "person to send the message again — clicking into this chat, or the " +
+          "Reconnect button on the Agent panel's banner, puts the address back. " +
+          "Do not reach for another application's tools, and do NOT edit the " +
+          "design's files instead: anything written there is discarded.",
+      };
+    }
+    if (response.status === 401) {
+      // The editor restarted and minted a fresh token and no new address came
+      // while retrying; ours was dropped above, so the next call reports "not
+      // connected" instead of retrying a dead secret.
+      return {
+        error:
+          "the canvas editor rejected this connection (stale token) — the editor " +
+          "restarted since this plugin was configured. Ask the person to send the " +
+          "message again, or to press Reconnect on the Agent panel's banner. Do " +
+          "not guess at another cause, and do not edit the design's files instead.",
+      };
+    }
+    let payload: unknown;
+    try {
+      payload = await response.json();
+    } catch {
+      return {
+        error: `the canvas editor returned a non-JSON response (HTTP ${response.status})`,
+      };
+    }
+    const record = (payload ?? {}) as { result?: unknown; error?: unknown };
+    if (typeof record.error === "string") return { error: record.error };
+    if (!response.ok) {
+      return { error: `the canvas editor returned HTTP ${response.status}` };
+    }
+    return { result: record.result };
+  }
+
+  /**
+   * Spill the PNG bytes to disk and report the path.
+   *
+   * bb's provider bridge decodes a tool response by keeping only text parts and
+   * dropping everything else, which is the shared path for claude-code and every
+   * ACP bridge — an inline image reaches the model on one provider alone. So the
+   * path is the contract and the image part is a bonus for that provider.
+   */
+  function saveShot(base64: string, label: string): string | null {
+    const safe = label.replace(/[^a-zA-Z0-9_-]/g, "").slice(0, 32) || "shot";
+    const file = join(SHOT_DIR, `canvas-${safe}-${Date.now()}-${++shotSeq}.png`);
+    try {
+      mkdirSync(SHOT_DIR, { recursive: true });
+      writeFileSync(file, Buffer.from(base64, "base64"));
+      return file;
+    } catch {
+      return null;
+    }
+  }
+
+  function spillScreenshot(
+    result: unknown,
+    threadId: string,
+  ): PluginAgentToolResult {
+    const record = (result ?? {}) as {
+      png?: unknown;
+      width?: unknown;
+      height?: unknown;
+    };
+    if (typeof record.png !== "string" || record.png.length === 0) {
+      return toolResult(JSON.stringify(result));
+    }
+    const safeThread =
+      threadId.replace(/[^a-zA-Z0-9_-]/g, "").slice(0, 32) || "thread";
+    const file = join(
+      SHOT_DIR,
+      `canvas-${safeThread}-${Date.now()}-${++shotSeq}.png`,
+    );
+    try {
+      mkdirSync(SHOT_DIR, { recursive: true });
+      writeFileSync(file, Buffer.from(record.png, "base64"));
+    } catch (error) {
+      return toolResult(
+        `the screenshot was taken but could not be saved: ${error instanceof Error ? error.message : String(error)}`,
+        true,
+      );
+    }
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            path: file,
+            width: record.width,
+            height: record.height,
+          }),
+        },
+        { type: "image", data: record.png, mimeType: "image/png" },
+      ],
+      isError: false,
+    };
+  }
+
+  /**
+   * The same spill, for a result that carries several pictures.
+   *
+   * A frame that only exists as base64 in a tool result is a frame the model
+   * never sees — bb keeps text parts and drops the rest before most providers
+   * are handed the result, which is the whole reason `spillScreenshot` exists.
+   * A dozen of them is a dozen files and one JSON list of paths; the image
+   * parts ride along for the one provider that keeps them.
+   *
+   * Two things it is careful about that the screenshot's version does not have
+   * to be:
+   *
+   *  - **The rest of the result survives.** An observed scene is its tracks
+   *    and its animations, with the frames alongside; returning only the paths
+   *    would throw the answer away and keep the illustrations.
+   *  - **Either encoding.** Video frames come as JPEG because a dozen
+   *    photographic stills as PNG is tens of megabytes; an element rebuilt
+   *    from markup comes as PNG because it is flat colour and type.
+   *
+   * Anything with no frames in it is passed through unchanged, so a refusal or
+   * an empty answer reads as itself rather than as a failed save.
+   */
+  function spillFrames(
+    result: unknown,
+    threadId: string,
+  ): PluginAgentToolResult {
+    const record = (result ?? {}) as { frames?: unknown };
+    if (!Array.isArray(record.frames) || record.frames.length === 0) {
+      return toolResult(JSON.stringify(result));
+    }
+    const safeThread =
+      threadId.replace(/[^a-zA-Z0-9_-]/g, "").slice(0, 32) || "thread";
+    const written: Array<Record<string, unknown>> = [];
+    const images: Array<{ type: "image"; data: string; mimeType: string }> = [];
+    try {
+      mkdirSync(SHOT_DIR, { recursive: true });
+      for (const entry of record.frames) {
+        const { jpeg, png, ...rest } = (entry ?? {}) as Record<string, unknown>;
+        const bytes = typeof jpeg === "string" ? jpeg : typeof png === "string" ? png : "";
+        if (!bytes) continue;
+        const jpg = typeof jpeg === "string";
+        const file = join(
+          SHOT_DIR,
+          `canvas-${safeThread}-${Date.now()}-${++shotSeq}.${jpg ? "jpg" : "png"}`,
+        );
+        writeFileSync(file, Buffer.from(bytes, "base64"));
+        // Everything the tool said about this frame, with the bytes swapped
+        // for the path — so a still keeps its step and its label, and a video
+        // frame keeps the time the decoder actually landed on.
+        written.push({ path: file, ...rest });
+        images.push({
+          type: "image",
+          data: bytes,
+          mimeType: jpg ? "image/jpeg" : "image/png",
+        });
+      }
+    } catch (error) {
+      return toolResult(
+        `the frames were taken but could not be saved: ${error instanceof Error ? error.message : String(error)}`,
+        true,
+      );
+    }
+    if (written.length === 0) return toolResult(JSON.stringify(result));
+    return {
+      content: [
+        { type: "text", text: JSON.stringify({ ...record, frames: written }) },
+        ...images,
+      ],
+      isError: false,
+    };
+  }
+
+  for (const definition of CANVAS_TOOLS) {
+    bb.agents.registerTool({
+      name: definition.name,
+      description: definition.description,
+      // Raw JSON schema rather than zod: the renderer validates every target
+      // and patch it is handed anyway, and a zod round-trip would rewrite the
+      // schema the parity test pins. Params therefore arrive unvalidated.
+      parameters: definition.inputSchema as Record<string, unknown>,
+      async execute(params, ctx) {
+        const outcome = await callEditor(definition.name, params, ctx);
+        if (typeof outcome.error === "string") {
+          return toolResult(outcome.error, true);
+        }
+        if (definition.name === SCREENSHOT_TOOL) {
+          return spillScreenshot(outcome.result, ctx.threadId);
+        }
+        if (FRAMES_TOOLS.includes(definition.name)) {
+          return spillFrames(outcome.result, ctx.threadId);
+        }
+        return toolResult(JSON.stringify(outcome.result));
+      },
+    });
+  }
+
+  /**
+   * Mentioning a layer in the composer.
+   *
+   * bb's own `@` menu lists files, folders and sections — the things a coding
+   * agent works on. What somebody using a design editor wants to point at is a
+   * *layer*, and the whole reason this plugin exists is that the layer is
+   * reachable. So the same menu gets the board: type `@` (or `#`) and the rows
+   * are the layers of the open design, with "the current selection" first.
+   *
+   * The context a picked row resolves to is agent-visible and user-hidden, so
+   * a mention costs the person nothing in their own message and still tells the
+   * model exactly which id to call `getLayer` and `updateLayer` with. That is
+   * the difference between "make this bigger" working and not.
+   *
+   * `search` is time-boxed by bb (2s) and failure-isolated: if the editor is
+   * not answering, the menu simply has no layer rows. `resolve` throwing would
+   * block the send, so it degrades to a line of text saying the layer could not
+   * be read rather than to an exception.
+   */
+  const SELECTION_ITEM = "selection";
+
+  /** The snapshot a mention carries (`layerSnapshot`), gathered at send time.
+   *  Every read is best effort: a picture or markup that cannot be had leaves a
+   *  shorter snapshot, never a mention that blocks the send. */
+  async function mentionSnapshot(id: string): Promise<string> {
+    const read = await callEditor("getLayer", { target: { id } }, {});
+    if (typeof read.error === "string") return `The layer "${id}" could not be read: ${read.error}`;
+    const layer = (read.result ?? {}) as Record<string, unknown>;
+
+    // An element of a running page is named by its page too: the element's own
+    // handle dies with the session, the page's address and node do not.
+    const frameId = frameOfLiveId(id);
+    let page: { id: string; address: string } | null = null;
+    if (frameId) {
+      const frame = await callEditor("getLayer", { target: { id: frameId } }, {});
+      const src = ((frame.result ?? {}) as { props?: { src?: unknown } }).props?.src;
+      if (typeof src === "string" && src) page = { id: frameId, address: src };
+    }
+
+    const [exported, shot] = await Promise.all([
+      callEditor("exportHtml", { target: { id } }, {}),
+      callEditor("canvasScreenshot", { target: { id }, width: 480 }, {}),
+    ]);
+    const html = ((exported.result ?? {}) as { html?: unknown }).html;
+    const png = ((shot.result ?? {}) as { png?: unknown }).png;
+    return layerSnapshot({
+      layer,
+      html: typeof html === "string" ? html : null,
+      page,
+      shot: typeof png === "string" && png ? saveShot(png, "mention") : null,
+    });
+  }
+
+  // Guarded because it is the one registration this plugin can live without:
+  // a bb whose `ui` surface predates mention providers would otherwise throw
+  // here and take the tools down with it, which is a much worse trade than a
+  // menu that lists files but no layers.
+  try {
+    bb.ui.registerMentionProvider({
+      id: "layers",
+      label: "Canvas layers",
+      // `@` is where people already look; `#` is for anybody who wants the
+      // board without wading past the file list.
+      triggers: ["@", "#"],
+      async search(context) {
+        const query = context.query.trim();
+        const rows: Array<{ id: string; title: string; subtitle?: string }> = [];
+
+        // The selection first, and only when there is one: a row that says
+        // "0 selected" wastes the only line most menus show.
+        const selection = await callEditor("getSelection", {}, {
+          threadId: context.threadId,
+        });
+        const selected = (selection.result ?? {}) as { count?: number };
+        if (typeof selected.count === "number" && selected.count > 0) {
+          if (!query || "selection".startsWith(query.toLowerCase())) {
+            rows.push({
+              id: SELECTION_ITEM,
+              title: `Current selection (${selected.count} layer${selected.count === 1 ? "" : "s"})`,
+              subtitle: "What is picked on the board right now",
+            });
+          }
+        }
+
+        const listed = await callEditor(
+          "listLayers",
+          query ? { search: query, limit: 8 } : { limit: 8 },
+          { threadId: context.threadId },
+        );
+        const layers = ((listed.result ?? {}) as { layers?: unknown }).layers;
+        if (Array.isArray(layers)) {
+          for (const entry of layers) {
+            const layer = (entry ?? {}) as {
+              id?: unknown;
+              name?: unknown;
+              type?: unknown;
+              text?: unknown;
+            };
+            if (typeof layer.id !== "string") continue;
+            const name =
+              typeof layer.name === "string" && layer.name
+                ? layer.name
+                : typeof layer.type === "string"
+                  ? layer.type
+                  : layer.id;
+            const subtitle = [layer.type, layer.text]
+              .filter((part): part is string => typeof part === "string" && part.length > 0)
+              .join(" · ");
+            rows.push({
+              id: `layer:${layer.id}`,
+              title: name,
+              ...(subtitle ? { subtitle } : {}),
+            });
+          }
+        }
+        return rows;
+      },
+      async resolve(itemId) {
+        if (itemId === SELECTION_ITEM) {
+          const outcome = await callEditor("getSelection", {}, {});
+          if (typeof outcome.error === "string") {
+            return { context: `The canvas selection could not be read: ${outcome.error}` };
+          }
+          const layers = ((outcome.result ?? {}) as { layers?: unknown }).layers;
+          const ids = Array.isArray(layers)
+            ? layers
+                .map((entry) => (entry as { id?: unknown } | null)?.id)
+                .filter((id): id is string => typeof id === "string")
+            : [];
+          const shots = await Promise.all(
+            ids.slice(0, SNAPSHOT_MAX_LAYERS).map((id) => mentionSnapshot(id)),
+          );
+          const rest = ids.length - shots.length;
+          return {
+            context:
+              "The layers selected on the board right now (address them by id with getLayer/updateLayer):\n" +
+              shots.join("\n\n") +
+              (rest > 0 ? `\n\n…and ${rest} more — call getSelection for them.` : ""),
+          };
+        }
+        const id = itemId.startsWith("layer:") ? itemId.slice("layer:".length) : itemId;
+        return {
+          context:
+            "A layer of the open design (address it by id with getLayer/updateLayer):\n" +
+            (await mentionSnapshot(id)),
+        };
+      },
+    });
+  } catch (error) {
+    bb.log.info(
+      `canvas layer mentions unavailable on this bb: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+
+  // Registering a configure() provider means bb stops auto-selecting all of our
+  // tools, so this has to return the full set. We pay that cost to learn
+  // `environment.path`, which is not available anywhere in the per-call context.
+  bb.agents.configure((context) => {
+    if (context.environment.path) {
+      // Insertion-ordered eviction: a long-lived bb server sees unboundedly
+      // many threads, and a stale entry only ever costs a mis-routed call.
+      if (
+        workspaceByThread.size >= MAX_TRACKED_THREADS &&
+        !workspaceByThread.has(context.thread.id)
+      ) {
+        const oldest = workspaceByThread.keys().next();
+        if (!oldest.done) workspaceByThread.delete(oldest.value);
+      }
+      workspaceByThread.set(context.thread.id, context.environment.path);
+    }
+    return {
+      tools: CANVAS_TOOLS.map((tool) => tool.name),
+      skills: [],
+      instructions: CANVAS_TOOL_GUIDE,
+    };
+  });
+
+  // What the assistant is told before the conversation starts. bb resolves this
+  // when a thread starts and when a turn is submitted, so an edit in Project
+  // settings reaches the next turn without reloading anything.
+  bb.agents.contributeInstructions((context) => {
+    const standing = instructionsByProject.get(context.projectId) ?? "";
+    const selection = selectionByProject.get(context.projectId) ?? "";
+    if (!standing) return selection || null;
+    if (!selection) return standing;
+    // Over bb's cap the project's own instructions are kept whole and the
+    // selection gives way, because the assistant can ask for it
+    // (getSelection) and cannot ask for the half of a prompt that went
+    // missing — but it gives way a piece at a time, see `fitSelection`.
+    const fitted = fitSelection(selection, MAX_INSTRUCTIONS - standing.length - 2);
+    return fitted ? `${standing}\n\n${fitted}` : standing.slice(0, MAX_INSTRUCTIONS);
+  });
+
+  bb.onDispose(() => {
+    callback = null;
+    workspaceByThread.clear();
+    pathByProject.clear();
+    instructionsByProject.clear();
+    selectionByProject.clear();
+  });
+}