@frebreco/canvas 0.3.0-next.8 → 0.3.0-next.9

package/package.json

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

package/src/server/board-mcp.ts

@@ -13,6 +13,10 @@
  * agent hears why a file can't be shown. It listens on loopback only: agents
  * run on this machine.
  *
+ * An agent's comment (ADR 0006) gets the text of its lines here, from the
+ * shared set: the browser keeps it to find the lines again as the file
+ * changes.
+ *
  * 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
@@ -22,6 +26,7 @@
 import { randomBytes } from "node:crypto";
 import type { McpServer } from "@agentclientprotocol/sdk";
 import { BOARD_SERVER_NAME, BOARD_TOOLS, boardInstructions } from "../shared/board-tools";
+import { linesOf, quoteOf } from "../shared/comments";
 import type { FileContent } from "../shared/protocol";
 import type { Scratch } from "./scratch";
 import type { Skill } from "./skills";
@@ -182,6 +187,7 @@ export class BoardMcp {
         delete args.content;
         delete args.name;
       } else this.checkPath(args, notes);
+      if (tool === "add_comment") this.quote(args);
       if (Array.isArray(args.files))
         args.files = args.files.map((value: unknown) => {
           if (typeof value !== "object" || value === null)
@@ -238,6 +244,26 @@ export class BoardMcp {
     }
   }
 
+  /** An agent's comment carries the text of its lines. */
+  private quote(args: Record<string, unknown>) {
+    if (typeof args.path !== "string" || !args.path.trim())
+      throw new Error("a comment needs the path of the file it is on");
+    const path = args.path.trim().replace(/^(\.\/)+/, "");
+    const file = this.options.read(path);
+    if (file.kind !== "text")
+      throw new Error(
+        `${path} can't be commented on: ${file.kind === "denied" ? file.reason : file.kind}`,
+      );
+    const start = Math.floor(Number(args.start_line));
+    const end = args.end_line === undefined ? start : Math.floor(Number(args.end_line));
+    const quote = quoteOf(file.text, start, end);
+    if (quote === null)
+      throw new Error(
+        `lines ${start}-${end} aren't in ${path}: it has ${linesOf(file.text).length} lines`,
+      );
+    Object.assign(args, { path, start_line: start, end_line: end, quote });
+  }
+
   private relay(sessionId: string, tool: string, args: Record<string, unknown>) {
     const callId = crypto.randomUUID();
     const result = new Promise<ToolResult>((resolve) => {

package/src/shared/board-tools.ts

@@ -11,11 +11,15 @@
 
 export const BOARD_TOOL_NAMES = [
   "view_board",
+  "view_frame",
   "open_frame",
   "update_frame",
   "close_frame",
   "read_board_file",
   "write_board_file",
+  "add_comment",
+  "edit_comment",
+  "delete_comment",
 ] as const;
 export type BoardToolName = (typeof BOARD_TOOL_NAMES)[number];
 
@@ -72,6 +76,33 @@ export interface UpdateFrameArgs extends Placement, FileTarget, ScratchContent,
   readonly title?: string;
   readonly url?: string;
   readonly view?: "preview" | "source";
+  /** A comment's id: show its file at its lines. */
+  readonly comment?: string;
+}
+
+export interface ViewFrameArgs {
+  readonly frame: string;
+}
+
+export interface AddCommentArgs {
+  readonly frame: string;
+  readonly path: string;
+  readonly start_line: number;
+  readonly end_line?: number;
+  readonly body: string;
+  /** The lines' text, which `canvas serve` adds (ADR 0006). */
+  readonly quote?: string;
+}
+
+export interface EditCommentArgs {
+  readonly frame: string;
+  readonly comment: string;
+  readonly body: string;
+}
+
+export interface DeleteCommentArgs {
+  readonly frame: string;
+  readonly comment: string;
 }
 
 export interface CloseFrameArgs {
@@ -180,6 +211,18 @@ export const BOARD_TOOLS: ReadonlyArray<{
       },
     },
   },
+  {
+    name: "view_frame",
+    description:
+      "Look at one frame in full. For a file frame: what it shows, its list of files, and its " +
+      "comments — people's and agents' notes on lines of its files, with ids, authors and lines. " +
+      "view_board says which frames have comments.",
+    inputSchema: {
+      type: "object",
+      properties: { frame: { type: "string", description: "Id of the frame." } },
+      required: ["frame"],
+    },
+  },
   {
     name: "open_frame",
     description:
@@ -220,6 +263,10 @@ export const BOARD_TOOLS: ReadonlyArray<{
         ...scratchContent,
         ...fileList,
         view: { type: "string", enum: ["preview", "source"] },
+        comment: {
+          type: "string",
+          description: "file: a comment's id (view_frame) — show its file at its lines.",
+        },
         url: { type: "string" },
         title: { type: "string" },
         ...placement,
@@ -264,6 +311,51 @@ export const BOARD_TOOLS: ReadonlyArray<{
       required: ["content"],
     },
   },
+  {
+    name: "add_comment",
+    description:
+      "Comment on lines of a file, in a file frame: it shows below the lines for everyone, " +
+      "whatever file the frame shows. Markdown. The frame keeps it; people read it there.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        frame: { type: "string", description: "Id of the file frame." },
+        path: {
+          type: "string",
+          description: "The file, relative to the project root, or canvas:scratch/<name>.",
+        },
+        start_line: { type: "integer", minimum: 1 },
+        end_line: { type: "integer", minimum: 1, description: "Default: start_line." },
+        body: { type: "string", description: "The comment, markdown." },
+      },
+      required: ["frame", "path", "start_line", "body"],
+    },
+  },
+  {
+    name: "edit_comment",
+    description: "Rewrite a comment's text. Only agents' comments: people's are theirs.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        frame: { type: "string", description: "Id of the file frame." },
+        comment: { type: "string", description: "The comment's id (view_frame)." },
+        body: { type: "string", description: "The new text, markdown." },
+      },
+      required: ["frame", "comment", "body"],
+    },
+  },
+  {
+    name: "delete_comment",
+    description: "Remove a comment. Only agents' comments: people's are theirs.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        frame: { type: "string", description: "Id of the file frame." },
+        comment: { type: "string", description: "The comment's id (view_frame)." },
+      },
+      required: ["frame", "comment"],
+    },
+  },
 ];
 
 /** The agent's standing context, sent as MCP server instructions. */
@@ -287,6 +379,7 @@ The ${BOARD_SERVER_NAME} tools let you see and change the board: ${BOARD_TOOL_NA
 - 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.
+- People (and agents) comment on lines of files in a file frame. view_board says which frames have comments; view_frame lists them, with ids. You aren't told when someone comments: look when asked to, e.g. to address feedback. add_comment leaves one of yours; edit_comment and delete_comment change agents' comments, never people's. update_frame with a comment's id shows its file at its lines. A comment is "outdated" when its lines changed since; it shows what they were.
 - Markdown and HTML files render. HTML runs its scripts, but relative links and assets (CSS, images, other scripts) don't load, so inline them.${skillsSection(skills)}`;
 }
 

package/src/shared/comments.ts

@@ -0,0 +1,48 @@
+/**
+ * Comments on the lines of a file (ADR 0006). A comment keeps the lines it
+ * was written on as text, its quote: files change under it — agents edit them
+ * live — and the quote is how it finds its lines again, or knows it can't.
+ * Pure, so `canvas serve` (which quotes agents' comments) and the browser
+ * agree on what a line is.
+ */
+
+/** A file's lines as the frames number them: a final newline ends the last line. */
+export function linesOf(text: string): string[] {
+  const lines = text.split("\n");
+  if (lines.length > 1 && lines.at(-1) === "") lines.pop();
+  return lines;
+}
+
+/** Lines `start`–`end` (1-based, inclusive) of `text`; null if the file hasn't got them. */
+export function quoteOf(text: string, start: number, end: number): string | null {
+  const lines = linesOf(text);
+  if (start < 1 || end < start || end > lines.length) return null;
+  return lines.slice(start - 1, end).join("\n");
+}
+
+/**
+ * Where a quote is now: its old place if the lines there still read the same,
+ * else the nearest place they do. null if they're gone — the comment is
+ * outdated. A quote of blank lines only stays where it was: blank lines are
+ * everywhere, finding "them" elsewhere would be a guess.
+ */
+export function relocate(
+  text: string,
+  quote: string,
+  start: number,
+): { start: number; end: number } | null {
+  const lines = linesOf(text);
+  const wanted = quote.split("\n");
+  const at = (s: number) => wanted.every((line, i) => lines[s - 1 + i] === line);
+  const found = (s: number) => ({ start: s, end: s + wanted.length - 1 });
+  const last = lines.length - wanted.length + 1;
+  if (start >= 1 && start <= last && at(start)) return found(start);
+  if (!quote.trim()) return null;
+  for (let distance = 1; distance < Math.max(start, last); distance++) {
+    if (start - distance >= 1 && start - distance <= last && at(start - distance))
+      return found(start - distance);
+    if (start + distance >= 1 && start + distance <= last && at(start + distance))
+      return found(start + distance);
+  }
+  return null;
+}