@frebreco/canvas 0.3.0-next.1 → 0.3.0-next.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frebreco/canvas",
-  "version": "0.3.0-next.1",
+  "version": "0.3.0-next.2",
   "description": "A multiplayer canvas for coding agents that run on your machine.",
   "license": "MIT",
   "type": "module",

package/src/server/board-mcp.ts

@@ -12,12 +12,18 @@
  * paths are checked against the shared set here first (ADR 0002), so the
  * agent hears why a file can't be shown. It listens on loopback only: agents
  * run on this machine.
+ *
+ * Scratch files (ADR 0005) never reach the browser as content: a call's
+ * `content` becomes a file in `.canvas/scratch/` here, and the call goes on
+ * with its path. Reading and writing them needs no board, so those tools are
+ * answered here.
  */
 
 import { randomBytes } from "node:crypto";
 import type { McpServer } from "@agentclientprotocol/sdk";
 import { BOARD_SERVER_NAME, BOARD_TOOLS, boardInstructions } from "../shared/board-tools";
 import type { FileContent } from "../shared/protocol";
+import type { Scratch } from "./scratch";
 
 export interface BoardCall {
   readonly callId: string;
@@ -29,6 +35,7 @@ export interface BoardCall {
 export interface BoardMcpOptions {
   /** A file as the shared set lets it out. */
   readonly read: (path: string) => FileContent;
+  readonly scratch: Pick<Scratch, "create" | "write" | "read" | "list" | "remove">;
   /** Send a call to the host's browser; false if none is connected. */
   readonly relay: (call: BoardCall) => boolean;
   readonly timeoutMs?: number;
@@ -151,22 +158,84 @@ export class BoardMcp {
   private async call(
     sessionId: string,
     tool: string,
-    args: Record<string, unknown>,
+    input: Record<string, unknown>,
   ): Promise<ToolResult> {
     if (!BOARD_TOOLS.some((t) => t.name === tool)) return failed(`no tool ${tool}`);
-    let note = "";
-    if (typeof args.path === "string" && args.path.trim()) {
-      const path = args.path.trim().replace(/^(\.\/)+/, "");
-      const file = this.options.read(path);
-      if (file.kind === "denied") return failed(file.reason);
-      if (file.kind === "missing")
-        note = `\n(${path} doesn't exist yet; the frame shows it as soon as it is written.)`;
-      if (file.kind === "text" && typeof args.start_line === "number") {
-        const lines = file.text.split("\n").length - (file.text.endsWith("\n") ? 1 : 0);
-        if (args.start_line > lines) return failed(`${path} has ${lines} lines`);
+    const args = { ...input };
+    const notes: string[] = [];
+    // Content becomes a scratch file; the board only ever sees its path.
+    const created: string[] = [];
+    const undo = () => created.forEach((path) => this.options.scratch.remove(path));
+    try {
+      switch (tool) {
+        case "read_board_file":
+          return done(this.readScratch(args.path));
+        case "write_board_file":
+          return done(this.writeScratch(args));
       }
+      if (args.content !== undefined) {
+        if (args.path !== undefined) throw new Error("give either path or content, not both");
+        args.path = this.createScratch(args.name, args.content, created, notes);
+        delete args.content;
+        delete args.name;
+      } else this.checkPath(args, notes);
+      if (Array.isArray(args.files))
+        args.files = args.files.map((value: unknown) => {
+          if (typeof value !== "object" || value === null)
+            throw new Error("each entry of files is an object with a display path");
+          const entry = { ...(value as Record<string, unknown>) };
+          if (entry.content !== undefined) {
+            if (entry.path !== undefined)
+              throw new Error("give a list entry either path or content, not both");
+            // No name: one from the display path's last segment, e.g. "1 Overview.md" → 1-Overview.md.
+            const name =
+              entry.name ??
+              (String(entry.display ?? "")
+                .split("/")
+                .at(-1)!
+                .replace(/[^\w.-]+/g, "-")
+                .replace(/^[^\w]+/, "") ||
+                "file");
+            entry.path = this.createScratch(name, entry.content, created, notes);
+            delete entry.content;
+            delete entry.name;
+          } else this.checkPath(entry, notes);
+          return entry;
+        });
+    } catch (error) {
+      undo();
+      return failed((error as Error).message);
+    }
+    if (tool === "view_board") {
+      const scratch = this.options.scratch.list();
+      notes.push(
+        scratch.length ? `Scratch files: ${scratch.join(", ")}.` : "No scratch files yet.",
+      );
+    }
+
+    const answer = await this.relay(sessionId, tool, args);
+    if (answer.isError) {
+      undo();
+      return answer;
+    }
+    return notes.length ? done([answer.content[0]!.text, ...notes].join("\n")) : answer;
+  }
+
+  /** A named file must be in the shared set (or a scratch file), and have the lines asked for. */
+  private checkPath(args: Record<string, unknown>, notes: string[]) {
+    if (typeof args.path !== "string" || !args.path.trim()) return;
+    const path = args.path.trim().replace(/^(\.\/)+/, "");
+    const file = this.options.read(path);
+    if (file.kind === "denied") throw new Error(file.reason);
+    if (file.kind === "missing")
+      notes.push(`(${path} doesn't exist yet; the frame shows it as soon as it is written.)`);
+    if (file.kind === "text" && typeof args.start_line === "number") {
+      const lines = file.text.split("\n").length - (file.text.endsWith("\n") ? 1 : 0);
+      if (args.start_line > lines) throw new Error(`${path} has ${lines} lines`);
     }
+  }
 
+  private relay(sessionId: string, tool: string, args: Record<string, unknown>) {
     const callId = crypto.randomUUID();
     const result = new Promise<ToolResult>((resolve) => {
       const timer = setTimeout(
@@ -182,8 +251,41 @@ export class BoardMcp {
         "the board isn't open right now: it lives in the host's browser, which is not connected",
       );
     }
-    const answer = await result;
-    return note && !answer.isError ? done(answer.content[0]!.text + note) : answer;
+    return result;
+  }
+
+  /** A new scratch file for `content`; its path. Says so in `notes`. */
+  private createScratch(name: unknown, content: unknown, created: string[], notes: string[]) {
+    if (typeof content !== "string") throw new Error("content must be text");
+    if (typeof name !== "string" || !name.trim())
+      throw new Error("content needs a name for its scratch file, e.g. overview.md");
+    const path = this.options.scratch.create(name.trim(), content);
+    created.push(path);
+    const taken = !path.endsWith(`/${name.trim()}`);
+    notes.push(`Wrote scratch file ${path}${taken ? ` (${name.trim()} was taken)` : ""}.`);
+    return path;
+  }
+
+  private readScratch(path: unknown): string {
+    if (typeof path !== "string") throw new Error("path must be a canvas:scratch/… path");
+    const file = this.options.scratch.read(path.trim());
+    if (file.kind === "text") return file.text;
+    if (file.kind === "denied") throw new Error(file.reason);
+    if (file.kind === "missing")
+      throw new Error(`${path} doesn't exist; view_board lists the scratch files`);
+    throw new Error(`${path} can't be read`);
+  }
+
+  private writeScratch(args: Record<string, unknown>): string {
+    if (typeof args.path === "string" && args.path.trim()) {
+      if (args.name !== undefined) throw new Error("give either path (overwrite) or name (create)");
+      if (typeof args.content !== "string") throw new Error("content must be text");
+      this.options.scratch.write(args.path.trim(), args.content);
+      return `Wrote ${args.path.trim()}; frames showing it update.`;
+    }
+    const notes: string[] = [];
+    this.createScratch(args.name, args.content, [], notes);
+    return notes[0]!;
   }
 }
 

package/src/server/files.ts

@@ -8,11 +8,15 @@
  * One recursive watcher covers the working dir: editors and agents often
  * replace files rather than write them in place, and a frame may wait for a
  * file (or its directory) that does not exist yet.
+ *
+ * Scratch files (`canvas:scratch/…`, ADR 0005) are read and listed alongside;
+ * the watcher skips `.canvas/`, so `Scratch` reports its writes itself.
  */
 
 import { readFileSync, statSync, watch, type FSWatcher } from "node:fs";
 import { sep } from "node:path";
 import type { FileContent } from "../shared/protocol";
+import { isScratchPath, Scratch } from "./scratch";
 import { SharedSet } from "./shared-set";
 
 export const MAX_FILE_BYTES = 1024 * 1024;
@@ -35,11 +39,13 @@ export class Files {
     dir: string,
     private readonly onFile: (path: string, file: FileContent) => void,
     private readonly onTree: (paths: ReadonlyArray<string>) => void,
+    private readonly scratch: Scratch = new Scratch(dir),
   ) {
     this.shared = new SharedSet(dir);
   }
 
   read(path: string): FileContent {
+    if (isScratchPath(path)) return this.scratch.read(path);
     let absolute: string;
     try {
       absolute = this.shared.resolve(path);
@@ -83,6 +89,12 @@ export class Files {
     this.ensureWatcher();
   }
 
+  /** A scratch file was written: re-send it, and the tree if it is new. */
+  scratchChanged(path: string): void {
+    if (this.subscribers.has(path)) this.send(path);
+    if (this.treeWatched) this.sendTree();
+  }
+
   stop(): void {
     this.watcher?.close();
     if (this.timer) clearTimeout(this.timer);
@@ -97,7 +109,7 @@ export class Files {
   }
 
   private sendTree() {
-    const paths = this.shared.list();
+    const paths = [...this.shared.list(), ...this.scratch.list()];
     const key = paths.join("\0");
     if (key === this.lastTree) return;
     this.lastTree = key;

package/src/server/scratch.ts

@@ -0,0 +1,115 @@
+/**
+ * Scratch files (ADR 0005): content an agent writes for the board only —
+ * a write-up, an HTML visualisation — kept in `<dir>/.canvas/scratch/`, out
+ * of the project. Board paths name them `canvas:scratch/<name>`; they are
+ * read like the shared set's files and mirrored the same way.
+ *
+ * Only agents write them, through their board tools: nothing a browser
+ * sends reaches `create` or `write`. One flat namespace; a name is never
+ * taken twice, so creating one never overwrites another agent's file.
+ */
+
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import { SCRATCH_PREFIX } from "../shared/board-tools";
+import type { FileContent } from "../shared/protocol";
+
+export const MAX_SCRATCH_BYTES = 1024 * 1024;
+
+export const isScratchPath = (path: string) => path.startsWith(SCRATCH_PREFIX);
+
+/** A name as agents may give it: one plain segment, e.g. `auth-overview.md`. */
+const NAME = /^[\w][\w.-]*$/;
+
+export class Scratch {
+  private readonly dir: string;
+
+  constructor(
+    root: string,
+    /** A scratch file was written: `canvas:scratch/<name>`. */
+    private readonly onChange: (path: string) => void = () => {},
+  ) {
+    this.dir = join(root, ".canvas", "scratch");
+  }
+
+  /** A new file, under `name` or, if that is taken, `name-2`, `name-3`…; its path. */
+  create(name: string, text: string): string {
+    checkName(name);
+    checkSize(text);
+    const dot = name.lastIndexOf(".");
+    const [stem, ext] = dot > 0 ? [name.slice(0, dot), name.slice(dot)] : [name, ""];
+    let free = name;
+    for (let n = 2; existsSync(join(this.dir, free)); n++) free = `${stem}-${n}${ext}`;
+    mkdirSync(this.dir, { recursive: true });
+    writeFileSync(join(this.dir, free), text);
+    const path = SCRATCH_PREFIX + free;
+    this.onChange(path);
+    return path;
+  }
+
+  /** Overwrite an existing scratch file. */
+  write(path: string, text: string): void {
+    const name = this.name(path);
+    if (!existsSync(join(this.dir, name)))
+      throw new Error(`${path} doesn't exist; give a name to create it`);
+    checkSize(text);
+    writeFileSync(join(this.dir, name), text);
+    this.onChange(path);
+  }
+
+  /** Undo a `create` whose board call failed. */
+  remove(path: string): void {
+    rmSync(join(this.dir, this.name(path)), { force: true });
+    this.onChange(path);
+  }
+
+  read(path: string): FileContent {
+    let name: string;
+    try {
+      name = this.name(path);
+    } catch (error) {
+      return { kind: "denied", reason: (error as Error).message };
+    }
+    const file = join(this.dir, name);
+    const stat = statSync(file, { throwIfNoEntry: false });
+    if (!stat?.isFile()) return { kind: "missing" };
+    if (stat.size > MAX_SCRATCH_BYTES) return { kind: "too-large", size: stat.size };
+    return { kind: "text", text: readFileSync(file, "utf8") };
+  }
+
+  /** Every scratch file's path, sorted. */
+  list(): string[] {
+    if (!existsSync(this.dir)) return [];
+    return readdirSync(this.dir, { withFileTypes: true })
+      .filter((entry) => entry.isFile() && NAME.test(entry.name))
+      .map((entry) => SCRATCH_PREFIX + entry.name)
+      .sort();
+  }
+
+  private name(path: string): string {
+    if (!isScratchPath(path)) throw new Error(`not a scratch file: ${path}`);
+    const name = path.slice(SCRATCH_PREFIX.length);
+    checkName(name);
+    return name;
+  }
+}
+
+function checkName(name: string) {
+  if (!NAME.test(name) || name.length > 120)
+    throw new Error(
+      `scratch file names are one plain segment of letters, digits, '.', '_' and '-' (got ${JSON.stringify(name)})`,
+    );
+}
+
+function checkSize(text: string) {
+  if (Buffer.byteLength(text) > MAX_SCRATCH_BYTES)
+    throw new Error("scratch files are at most 1 MiB");
+}

package/src/server/server.ts

@@ -11,6 +11,7 @@ import type { ClientToServer, ServerToClient } from "../shared/protocol";
 import { AgentManager, detectAgents } from "./agents";
 import { BoardMcp } from "./board-mcp";
 import { Files } from "./files";
+import { Scratch } from "./scratch";
 import { Store } from "./store";
 import { Terminals } from "./terminals";
 
@@ -31,15 +32,19 @@ export async function serve(options: ServeOptions) {
     for (const ws of clients) ws.send(text);
   };
 
+  // Scratch files are written by agents' board tools; `files` mirrors them.
+  const scratch = new Scratch(options.dir, (path) => files.scratchChanged(path));
   const files = new Files(
     options.dir,
     (path, file) => broadcast({ t: "file", path, file }),
     (paths) => broadcast({ t: "tree", paths }),
+    scratch,
   );
   process.on("exit", () => files.stop());
   // Board tools: an agent's call goes to one host browser (the board is there).
   const boardMcp = new BoardMcp({
     read: (path) => files.read(path),
+    scratch,
     relay: (call) => {
       const [ws] = clients;
       if (!ws) return false;

package/src/shared/board-tools.ts

@@ -14,6 +14,8 @@ export const BOARD_TOOL_NAMES = [
   "open_frame",
   "update_frame",
   "close_frame",
+  "read_board_file",
+  "write_board_file",
 ] as const;
 export type BoardToolName = (typeof BOARD_TOOL_NAMES)[number];
 
@@ -39,7 +41,25 @@ interface FileTarget {
   readonly end_line?: number;
 }
 
-export interface OpenFrameArgs extends Placement, FileTarget {
+/** A new scratch file to show (ADR 0005); `canvas serve` turns it into a `path`. */
+interface ScratchContent {
+  readonly name?: string;
+  readonly content?: string;
+}
+
+/** One entry of a file frame's list (ADR 0005): a file at a display path. */
+export interface FileListEntry extends ScratchContent {
+  readonly display: string;
+  readonly path?: string;
+  readonly start_line?: number;
+  readonly end_line?: number;
+}
+
+interface FileList {
+  readonly files?: ReadonlyArray<FileListEntry>;
+}
+
+export interface OpenFrameArgs extends Placement, FileTarget, ScratchContent, FileList {
   readonly type: FrameKind;
   readonly title?: string;
   readonly url?: string;
@@ -47,7 +67,7 @@ export interface OpenFrameArgs extends Placement, FileTarget {
   readonly draft?: string;
 }
 
-export interface UpdateFrameArgs extends Placement, FileTarget {
+export interface UpdateFrameArgs extends Placement, FileTarget, ScratchContent, FileList {
   readonly frame: string;
   readonly title?: string;
   readonly url?: string;
@@ -58,6 +78,17 @@ export interface CloseFrameArgs {
   readonly frame: string;
 }
 
+export interface ReadBoardFileArgs {
+  readonly path: string;
+}
+
+export interface WriteBoardFileArgs extends ScratchContent {
+  readonly path?: string;
+}
+
+/** Where scratch files live, as board paths name them. */
+export const SCRATCH_PREFIX = "canvas:scratch/";
+
 const placement = {
   next_to: {
     type: "string",
@@ -74,12 +105,60 @@ const placement = {
 const fileTarget = {
   path: {
     type: "string",
-    description: "File path relative to the project root, e.g. src/auth/session.ts.",
+    description:
+      "File path relative to the project root, e.g. src/auth/session.ts, or a scratch file: " +
+      "canvas:scratch/<name>.",
   },
   start_line: { type: "integer", minimum: 1, description: "First line to show and highlight." },
   end_line: { type: "integer", minimum: 1, description: "Last highlighted line (inclusive)." },
 };
 
+const scratchContent = {
+  content: {
+    type: "string",
+    description:
+      "Instead of path: the text of a new scratch file to show — content for this board only, " +
+      "like a write-up or an HTML visualisation. canvas keeps it outside the project.",
+  },
+  name: {
+    type: "string",
+    description:
+      "With content: the scratch file's name, e.g. auth-overview.md; its extension decides how " +
+      "it shows. A taken name gets a suffix; the result says which path you got.",
+  },
+};
+
+const fileList = {
+  files: {
+    type: "array",
+    description:
+      "file: a list of files for the frame's tree, for people to click through at their pace — " +
+      "e.g. the files of one feature, with a write-up first. Each entry is a project file or a " +
+      "scratch file at a display path you choose: make folders, rename, order it (a folder sorts " +
+      "where its first entry is; no folders for a flat list). The frame shows path, else the " +
+      "first entry. update_frame replaces the list; [] removes it.",
+    items: {
+      type: "object",
+      properties: {
+        display: {
+          type: "string",
+          description:
+            'Where it shows in the tree, e.g. "1 Overview.md" or "Auth/session.ts". Unique.',
+        },
+        path: { type: "string", description: "A project file or canvas:scratch/<name>." },
+        ...scratchContent,
+        start_line: {
+          type: "integer",
+          minimum: 1,
+          description: "Lines to open it at, shown as a badge.",
+        },
+        end_line: { type: "integer", minimum: 1 },
+      },
+      required: ["display"],
+    },
+  },
+};
+
 export const BOARD_TOOLS: ReadonlyArray<{
   readonly name: BoardToolName;
   readonly description: string;
@@ -105,7 +184,9 @@ export const BOARD_TOOLS: ReadonlyArray<{
     name: "open_frame",
     description:
       "Open a new frame on the board, in your own cluster unless placed next to another frame. " +
-      "file: a project file (read-only, live), optionally at a line range which gets highlighted. " +
+      "file: a project file (read-only, live), optionally at a line range which gets highlighted, " +
+      "or a scratch file: content you pass, kept by canvas outside the project. A file frame can " +
+      "also carry a list of files (files): one frame to click through, instead of many. " +
       "browser: a URL, loaded by each viewer's own browser. terminal: an idle shell people can " +
       "type into. agent: another agent session; `draft` pre-fills its prompt, a person sends it.",
     inputSchema: {
@@ -113,6 +194,8 @@ export const BOARD_TOOLS: ReadonlyArray<{
       properties: {
         type: { type: "string", enum: ["file", "browser", "terminal", "agent"] },
         ...fileTarget,
+        ...scratchContent,
+        ...fileList,
         url: { type: "string", description: "browser: an http(s) URL." },
         agent: { type: "string", description: "agent: which agent runs it (see view_board)." },
         draft: { type: "string", description: "agent: a prompt draft for people to send." },
@@ -125,7 +208,8 @@ export const BOARD_TOOLS: ReadonlyArray<{
   {
     name: "update_frame",
     description:
-      "Change a frame: point a file frame at another file or line range, switch a markdown " +
+      "Change a frame: point a file frame at another file, line range or new scratch file " +
+      "(content), give it a list of files or replace it (files), switch a markdown " +
       "or HTML file between preview and source, change a browser frame's URL, rename a frame, or move " +
       "it next to another frame.",
     inputSchema: {
@@ -133,6 +217,8 @@ export const BOARD_TOOLS: ReadonlyArray<{
       properties: {
         frame: { type: "string", description: "Id of the frame to change." },
         ...fileTarget,
+        ...scratchContent,
+        ...fileList,
         view: { type: "string", enum: ["preview", "source"] },
         url: { type: "string" },
         title: { type: "string" },
@@ -151,6 +237,33 @@ export const BOARD_TOOLS: ReadonlyArray<{
       required: ["frame"],
     },
   },
+  {
+    name: "read_board_file",
+    description:
+      "Read a scratch file (canvas:scratch/<name>), e.g. one another agent wrote. view_board " +
+      "lists them.",
+    inputSchema: {
+      type: "object",
+      properties: { path: { type: "string", description: "canvas:scratch/<name>" } },
+      required: ["path"],
+    },
+  },
+  {
+    name: "write_board_file",
+    description:
+      "Write a scratch file without opening a frame. With name: a new one. With path: overwrite " +
+      "an existing one (any agent's); every frame showing it updates. Show a new one with " +
+      "open_frame (path).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "canvas:scratch/<name> to overwrite." },
+        name: scratchContent.name,
+        content: { type: "string", description: "The file's full text." },
+      },
+      required: ["content"],
+    },
+  },
 ];
 
 /** The agent's standing context, sent as MCP server instructions. */
@@ -159,7 +272,7 @@ export function boardInstructions(frameId: string): string {
 
 Frames that sit close together form a cluster: people keep related work together that way, and your own cluster is your workspace. Within a cluster frames sit in rows; frames in a row share a height.
 
-The ${BOARD_SERVER_NAME} tools let you see and change the board: ${BOARD_TOOL_NAMES.join(", ")}. Use them when showing something on the board helps the people you work with — e.g. asked to show the files relevant to a topic, open them as file frames at the relevant lines instead of pasting code. Don't use them when a plain answer is enough.
+The ${BOARD_SERVER_NAME} tools let you see and change the board: ${BOARD_TOOL_NAMES.join(", ")}. Use them when showing something on the board helps the people you work with — e.g. asked to show the files relevant to a topic, show them on the board (one file, or a list of them) at the relevant lines instead of pasting code. Don't use them when a plain answer is enough.
 
 - Look first (view_board). Reuse or retarget a frame (update_frame) rather than open a duplicate.
 - New frames go into your cluster by default; that is almost always right. Keep it to a handful per request.
@@ -168,5 +281,8 @@ The ${BOARD_SERVER_NAME} tools let you see and change the board: ${BOARD_TOOL_NA
 - A terminal frame is an idle shell for people; you cannot type into it. Run commands with your own tools.
 - An agent frame starts another agent. You can leave a draft prompt in it; only a person can send it.
 - A browser frame loads its URL in each viewer's own browser, so localhost means their machine, not this one: only the host sees a localhost URL, guests get a notice.
-- To show a page you wrote to everyone, open the HTML file as a file frame: it renders, scripts included, but relative links and assets (CSS, images, other scripts) don't load, so inline them.`;
+- Scratch files hold what exists only to be shown on this board: a write-up, a diagram, an HTML visualisation. Pass the text as \`content\` (with a \`name\`) to open_frame or update_frame, or use write_board_file; canvas keeps them outside the project, as canvas:scratch/<name>. Don't write such files into the project for the board. Anything else — a temp file for your own work, a script, test data — goes wherever it would without canvas.
+- Any agent may read (read_board_file) and overwrite (write_board_file) any scratch file; view_board lists them.
+- To show several files for one topic, prefer one file frame with a list (files) over a frame per file: people click through it at their own pace. You decide the tree: display paths, folders, order, line ranges. A write-up (a scratch file) at the top and a visualisation at the bottom fit in the same list.
+- Markdown and HTML files render. HTML runs its scripts, but relative links and assets (CSS, images, other scripts) don't load, so inline them.`;
 }