@chalky/chalky 0.1.4 → 0.1.6

package/agent/extensions/card/index.ts

@@ -0,0 +1,370 @@
+// Cards: what the agents show the user, each one thing on a board in the page's main space (browser.js draws them).
+// A card shows blocks (a JSON list of pieces from blocks/*.js: Text, Button, Table...) or an app (a page of its own in
+// built/apps/<name>/, in a frame; the app extension serves its data and its bridge to the agents).
+// Tools card_blocks, card_show, card_update, card_remove. card_show of an app opens the page in the browser-check
+// skill's headless browser and says what it found: errors, and whether the app fits its card. The cards are shared by every agent: one Cards object on
+// the host, made by whichever agent loads first.
+// One door: every change goes through change(): it saves, tells every open page, and calls every watcher with the
+// card, who did it ("user" or the agent) and the words for it, without who ("moved s1"; none: part of a bigger
+// change). restore() puts back a saved state (not a change: no watchers). Watchers, registered from session_start:
+//   host.api.card.watch(name, fn(card, by, what))   name: the extension's, so its reload replaces its own
+// (history: a step per change with words; frame: a frame is done when its card appears; version: a version's label).
+//   built/card.json  each card but its data (versioned)      data/card.json  each card's data (what users typed)
+// A card: {owner, blocks | app, data, place, board, about, pinned, options, made_from, instruction, draggable,
+//   resizable, height (an app's, when nothing else sizes it), kinds (each block's about.version, for upgrades)}.
+//   app: the page's path in built/, e.g. "apps/habit/index.html" (card_show takes the full path).
+//   GET /card/all           every card                   GET /card/about   block name -> its about block
+//   GET /card/blocks        block name -> mtime          GET /card/blocks/<Name>.js, /card/node_modules/{marked,dompurify}/...
+//   GET /card/lib/...       libraries the agents added for blocks (lib/ here: ES-module builds)
+//   page messages           card_set, card_prop, card_move, card_board, card_pin, card_keep, card_close, card_action
+//   page event "card"       {op: "render", card, ...record} | {op: "delete", card} | {op: "reset", cards}
+import fs from "node:fs";
+import path from "node:path";
+import { execFile } from "node:child_process";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+const host = (globalThis as any).chalky;
+const DESIGN = path.join(host.built, "card.json");
+const DATA = path.join(host.data, "card.json");
+const BLOCKS = path.join(import.meta.dirname, "blocks");
+const LIB = path.join(import.meta.dirname, "lib");
+const LIBS = ["marked/", "dompurify/"];  // the browser libraries blocks import, from the host's node_modules (its package.json)
+const read = (p: string, d: any) => (fs.existsSync(p) ? JSON.parse(fs.readFileSync(p, "utf8")) : d);
+const clone = (v: any) => structuredClone(v);
+const isRef = (v: any) => v && typeof v === "object" && !Array.isArray(v) && Object.keys(v).sort().join() === "path,ref";
+const STRUCTURE = ["id", "block", "children", "child"];  // what makes the tree: changed only by card_show
+const propsOf = (b: any) => Object.fromEntries(Object.entries(b).filter(([k]) => ![...STRUCTURE, "when"].includes(k)));
+
+function getPath(data: any, p: string) {
+  for (const k of p.split("/").filter(Boolean)) data = data?.[Array.isArray(data) ? Number(k) : k];
+  return data;
+}
+function setPath(data: any, p: string, value: any) {
+  const keys = p.split("/").filter(Boolean);
+  for (const k of keys.slice(0, -1)) data = data[k] ??= {};
+  data[keys.at(-1)!] = value;
+}
+
+// On the host, so they outlive this file's reloads; one per watching extension
+const watchers: Map<string, (id: string, by?: string, what?: string) => void> = host.shared.get("card-watchers") ?? new Map();
+host.shared.set("card-watchers", watchers);
+host.api.card = { watch: (name: string, fn: (id: string, by?: string, what?: string) => void) => watchers.set(name, fn) };
+
+class Cards {
+  cards: Record<string, any> = read(DESIGN, {});
+  constructor() {
+    const data = read(DATA, {});
+    for (const [id, r] of Object.entries(this.cards)) r.data = data[id] ?? {};
+  }
+  save() {
+    fs.writeFileSync(DESIGN, JSON.stringify(Object.fromEntries(Object.entries(this.cards)
+      .map(([id, r]) => [id, { ...r, data: undefined }])), null, 1));
+    fs.writeFileSync(DATA, JSON.stringify(Object.fromEntries(Object.entries(this.cards).map(([id, r]) => [id, r.data ?? {}]))));
+  }
+  get(id: string) { return clone(this.cards[id]); }
+  snapshot() { return clone(this.cards); }
+  // record null: delete. by: "user" or an agent; what: the history's words for it (none: part of a bigger change,
+  // so no step of its own; the last change makes one)
+  change(id: string, record: any, by?: string, what?: string) {
+    if (record === null) delete this.cards[id];
+    else this.cards[id] = record;
+    this.save();
+    host.broadcast("card", record === null ? { op: "delete", card: id } : { op: "render", card: id, ...record });
+    for (const [name, fn] of watchers) {
+      try { fn(id, by, what); }
+      catch (e) { host.broadcast("error", { agent: "server", text: `card watcher ${name}: ${e}` }); }  // one broken watcher doesn't stop the rest
+    }
+  }
+  load() {  // read the files again (after a rollback changed built/card.json); true if the cards changed
+    const before = JSON.stringify(this.cards), design = read(DESIGN, {}), data = read(DATA, {});
+    for (const [id, r] of Object.entries(design) as any) r.data = data[id] ?? {};
+    this.cards = design;
+    host.broadcast("card", { op: "reset", cards: this.cards });
+    return JSON.stringify(this.cards) !== before;
+  }
+  restore(cards: Record<string, any>) {  // a whole saved state (undo, redo, rewind): not a change of its own
+    this.cards = clone(cards);
+    this.save();
+    host.broadcast("card", { op: "reset", cards: this.cards });
+  }
+  locked(id: string) {
+    return this.cards[id]?.pinned ? `error: card '${id}' is pinned by the user, so agents can't change or remove it. `
+      + `Make a new card instead (made_from=['${id}'] keeps the link), or ask the user to unpin it.` : null;
+  }
+  copyIntoUsers(id: string) {  // before id goes: cards reading from it get its current values
+    const users = Object.keys(this.cards).filter((o) => o !== id && (this.cards[o].blocks ?? [])
+      .some((b: any) => Object.values(propsOf(b)).some((v: any) => isRef(v) && v.ref === id)));
+    for (const o of users) {
+      const r = this.get(o);
+      for (const b of r.blocks)
+        for (const [k, v] of Object.entries(propsOf(b)) as any)
+          if (isRef(v) && v.ref === id) b[k] = clone(getPath(this.cards[id].data, v.path));
+      this.change(o, r);
+    }
+    return users;
+  }
+}
+
+if (!host.shared.has("card")) host.shared.set("card", new Cards());
+const cards: Cards = host.shared.get("card");
+
+function problems(blocks: any[], madeFrom: string[] = []) {
+  const catalog = readCatalog(), ids = new Set(blocks.map((b) => b.id));
+  const errors = ids.has("root") ? [] : ['one block must have "id": "root"'];
+  for (const b of blocks) {
+    if (!(b.block in catalog)) { errors.push(`${b.id}: unknown block '${b.block}' (have: ${Object.keys(catalog).join(", ")})`); continue; }
+    for (const child of [...(b.children ?? []), ...(b.child ? [b.child] : [])])
+      if (!ids.has(child)) errors.push(`${b.id}: child '${child}' is not defined`);
+    if (b.when && !(typeof b.when === "object" && typeof b.when.path === "string" && "is" in b.when))
+      errors.push(`${b.id}: when must be {"path": "/x", "is": value}`);
+    const known = catalog[b.block].about?.props;
+    for (const [k, v] of Object.entries(propsOf(b)) as any) {
+      if (known && !(k in known)) errors.push(`${b.id}: ${b.block} has no prop '${k}' (props: ${Object.keys(known).join(", ") || "none"})`);
+      if (isRef(v) && !(v.ref in cards.cards)) errors.push(`${b.id}.${k}: refers to card '${v.ref}', which does not exist`);
+    }
+  }
+  const byId = new Map(blocks.map((b) => [b.id, b])), drawn = new Set<string>();
+  const walk = (id: string) => {  // what is drawn: root and what it contains, down
+    if (drawn.has(id) || !byId.has(id)) return;
+    drawn.add(id);
+    const b = byId.get(id);
+    for (const c of [...(b.children ?? []), ...(b.child ? [b.child] : [])]) walk(c);
+  };
+  walk("root");
+  const orphans = ids.has("root") ? [...ids].filter((id) => !drawn.has(id)) : [];
+  if (orphans.length) errors.push(`${orphans.join(", ")}: not inside root (no block lists ${orphans.length > 1 ? "them" : "it"} in children or child), so never drawn`);
+  return [...errors, ...madeFrom.filter((m) => !(m in cards.cards)).map((m) => `made_from: no card '${m}'`)];
+}
+
+// An app's page, given as its name ("habit": apps/habit/index.html), its path in built/ or its full path: its path in
+// built/, or an error that says where it should be
+function appPath(given: string): { app?: string; error?: string } {
+  const apps = path.join(host.built, "apps");
+  const full = !given.includes("/") ? path.join(apps, given, "index.html")
+    : path.isAbsolute(given) ? given : path.join(host.built, given.replace(/^\/?(built\/)?/, ""));
+  const p = path.resolve(full);
+  if (!p.startsWith(apps + path.sep)) return { error: `an app's page is a file in ${apps}/<name>/ (e.g. ${apps}/habit/index.html); ${full} is not` };
+  if (!fs.existsSync(p) || !fs.statSync(p).isFile()) return { error: `no file ${p}: write the app's page there first` };
+  return { app: path.relative(host.built, p).split(path.sep).join("/") };
+}
+
+// The blocks (blocks/*.js): {name: {doc, mtime, about, problem}}; doc = the comment lines at the top
+function readCatalog() {
+  const out: Record<string, any> = {};
+  for (const f of fs.readdirSync(BLOCKS).filter((f) => f.endsWith(".js")).sort()) {
+    const text = fs.readFileSync(path.join(BLOCKS, f), "utf8");
+    const doc: string[] = [];
+    for (const line of text.split("\n")) {
+      if (!line.startsWith("//")) break;
+      doc.push(line.slice(2).trim());
+    }
+    let about = null, problem = null;
+    const i = text.indexOf("export const about = ");
+    if (i >= 0) {
+      try { about = JSON.parse(text.slice(i + 21, text.indexOf("};", i) + 1)); }
+      catch (e) { problem = `its about block is not valid JSON (${e})`; }
+    }
+    out[f.slice(0, -3)] = { doc: doc.join("\n"), mtime: Math.floor(fs.statSync(path.join(BLOCKS, f)).mtimeMs / 1000), about, problem };
+  }
+  return out;
+}
+
+// An app card as the user sees it: the page opened in the headless browser of the browser-check skill, its errors and
+// whether the app fits its card. A few seconds; what it can't do (no browser yet) it says, and the card stays.
+function checkOnBoard(id: string): Promise<string> {
+  const script = path.join(host.agent, "skills/browser-check/scripts/check.mjs");
+  const measure = `eval:(()=>{const f=document.querySelector('[data-card="${id}"] iframe'); if(!f) return 'none';
+    const d=f.contentDocument; return f.clientHeight+' '+d.documentElement.scrollHeight+' '+f.clientWidth+' '+d.documentElement.scrollWidth})()`;
+  return new Promise((resolve) => execFile(process.execPath, [script, `http://127.0.0.1:${host.port}/`, "wait:2500", measure],
+    { timeout: 45000 }, (err, stdout) => {
+      const errors = /errors \((\d+)\):\n?([\s\S]*?)\n?layout problems/.exec(stdout ?? "");
+      const m = /-> "(\d+) (\d+) (\d+) (\d+)"/.exec(stdout ?? "");
+      if (!errors) return resolve(`not checked (${String(err?.message ?? stdout).split("\n")[0].slice(0, 200)})`);
+      const said = Number(errors[1]) ? `${errors[1]} error(s): ${errors[2].trim().slice(0, 600)}` : "no errors";
+      const fit = !m ? "not on the board the user is on, so not measured"
+        : Number(m[2]) > Number(m[1]) + 2 ? `its content is ${m[2]}px tall in a ${m[1]}px card, so it scrolls inside: make it fit (or pass height=${Number(m[2]) + 8})`
+        : Number(m[4]) > Number(m[3]) + 2 ? `its content is ${m[4]}px wide in a ${m[3]}px card: make it fit` : "it fits its card";
+      resolve(`checked on the board: ${said}; ${fit}`);
+    }));
+}
+
+const result = (text: string) => ({ content: [{ type: "text" as const, text }], details: undefined });
+const Place = Type.Optional(Type.Object({ x: Type.Number(), y: Type.Number(), width: Type.Optional(Type.Number()), height: Type.Optional(Type.Number()) },
+  { description: "pin it at a spot (px from the main space's top-left); leave out to stack it" }));
+
+export default function (pi: ExtensionAPI) {
+  // a removed board (board/) takes its cards with it: one step in the history (undo brings them back)
+  pi.on("session_start", () => host.api.board?.onRemove("card", (n: number) => {
+    const ids = Object.keys(cards.cards).filter((id) => (cards.cards[id].board ?? 1) === n);
+    const gone = ids.map((id) => ({ owner: cards.cards[id].owner, what: `card ${id}` }));
+    ids.forEach((id, i) => {
+      cards.copyIntoUsers(id);  // cards elsewhere reading from it keep its values
+      cards.change(id, null, "user", i === ids.length - 1 ? `removed board ${n} (${ids.join(", ")})` : undefined);
+    });
+    return gone;
+  }));
+
+  pi.registerTool({
+    name: "card_blocks", label: "Card blocks", exposure: "deferred", description: "List the blocks you can build a card from, with their props.",
+    parameters: Type.Object({}),
+    async execute() {
+      const catalog = readCatalog();
+      const broken = Object.entries(catalog).filter(([, m]: any) => m.problem).map(([n, m]: any) => `${n}: ${m.problem}`);
+      return result(`Before your first blocks card or a new block, read ${path.join(import.meta.dirname, "README.md")} (bindings, `
+        + `when, tabs, refs, options, new blocks).\n\n` + Object.values(catalog).map((m: any) => m.doc + (m.about ? `\nabout: ${JSON.stringify(m.about)}` : "")).join("\n\n")
+        + (broken.length ? `\n\nProblems:\n${broken.join("\n")}` : ""));
+    },
+  });
+
+  pi.registerTool({
+    name: "card_show", label: "Card show", description: "Show a card on a board, or replace one: built from blocks, or an app "
+      + "(a page you wrote in the apps folder of what you built).",
+    parameters: Type.Object({
+      card: Type.String({ description: "its id: a clear name (the user points at things by name)" }),
+      blocks: Type.Optional(Type.Array(Type.Record(Type.String(), Type.Any()), { description: 'e.g. [{"id": "root", "block": "Text", "text": "hi"}]' })),
+      app: Type.Optional(Type.String({ description: "instead of blocks: the app's name (its page is <built>/apps/<name>/index.html)" })),
+      height: Type.Optional(Type.Number({ description: "an app's height in px when nothing else sizes it (default 400)" })),
+      data: Type.Optional(Type.Record(Type.String(), Type.Any(), { description: "the blocks' data; leave out to keep the card's data" })),
+      place: Place,
+      draggable: Type.Optional(Type.Boolean()), resizable: Type.Optional(Type.Boolean()),
+      about: Type.Optional(Type.String({ description: "what it is for and why it is built this way (its back side)" })),
+      options: Type.Optional(Type.Array(Type.Record(Type.String(), Type.Any()), { description: 'alternatives instead of blocks or app: [{"label", "blocks" or "app", "data"}]' })),
+      made_from: Type.Optional(Type.Array(Type.String())), instruction: Type.Optional(Type.String()),
+      board: Type.Optional(Type.Union([Type.Number(), Type.Literal("new")], { description:
+        'a board number, or "new" for a new board; leave out: where the card is, else the board the user is on' })),
+    }),
+    async execute(_id, a) {
+      const agent = pi.getSessionName() ?? "agent";
+      const locked = cards.locked(a.card);
+      if (locked) return result(locked);
+      if ([a.blocks, a.app, a.options].filter((v) => v !== undefined).length !== 1) return result("error: give one of blocks, app or options");
+      const old = cards.cards[a.card] ?? {}, catalog = readCatalog(), boards = host.api.board;
+      // the content: {blocks, data} or {app}, checked; each option is one too
+      const content = (o: any, label = "") => {
+        if (o.app !== undefined) {
+          const { app, error } = appPath(o.app);
+          return error ? { error: (label && `${label}: `) + error } : { app };
+        }
+        const errors = problems(o.blocks ?? [], a.made_from);
+        return errors.length ? { error: (label && `${label}: `) + errors.join("; ") } : { blocks: o.blocks ?? [] };
+      };
+      const options = [];
+      for (const [i, o] of (a.options ?? []).entries()) {
+        const label = o.label ?? `option ${i + 1}`, c: any = content(o, label);
+        if (c.error) return result("error: " + c.error);
+        options.push({ label, ...c, data: o.data ?? {} });
+      }
+      const main: any = options[0] ?? content(a);
+      if (main.error) return result("error: " + main.error);
+      if (typeof a.board === "number" && boards && !boards.has(a.board))
+        return result(`error: no board ${a.board}. Boards: ${boards.list().join(", ")} (or board "new")`);
+      const record: any = { owner: agent, ...(main.app ? { app: main.app } : { blocks: main.blocks }),
+        data: options.length ? main.data : a.data ?? old.data ?? {}, place: a.place ?? old.place ?? null,
+        draggable: a.draggable ?? true, resizable: a.resizable ?? true, about: a.about ?? old.about ?? "",
+        kinds: Object.fromEntries((options.length ? options : [main]).flatMap((o: any) => o.blocks ?? [])
+          .map((b: any) => [b.block, catalog[b.block].about?.version ?? 1])) };
+      for (const [k, v] of [["height", main.app ? a.height ?? old.height : undefined], ["made_from", a.made_from ?? old.made_from],
+                            ["instruction", a.instruction ?? old.instruction], ["options", options.length ? options : null]] as const) if (v) record[k] = v;
+      // its board (board/): the one asked for, a new one, where it already is, or the one the user is on
+      if (boards) record.board = a.board === "new" ? boards.add() : a.board ?? old.board ?? boards.current();
+      cards.change(a.card, record, agent, `showed ${a.card}` + (options.length ? ` (${options.length} options)` : ""));
+      const where = boards ? `on board ${record.board}${a.board === "new" ? " (a new board)" : ""}` : "on screen";
+      if (options.length) return result(`card '${a.card}' shows ${options.length} options ${where}; the user flips through them and keeps one`);
+      if (!main.app) return result(`card '${a.card}' is ${where}`);
+      return result(`card '${a.card}' is ${where}, showing ${host.built}/${main.app} (at http://127.0.0.1:${host.port}/built/${main.app}); `
+        + await checkOnBoard(a.card) + ". Errors and fit are all this checked: now use it as the user would (load the "
+        + "test-your-app skill) before you tell the user what it does.");
+    },
+  });
+
+  pi.registerTool({
+    name: "card_update", label: "Card update", description: "Change one value in a card's data (e.g. a score or a list), "
+      + "or with block, one prop of that block (e.g. a label): the rest of the card stays as it is.",
+    parameters: Type.Object({ card: Type.String(),
+      path: Type.String({ description: "a data path, e.g. /score; with block: the prop, e.g. text" }), value: Type.Any(),
+      block: Type.Optional(Type.String({ description: "a block's id: change its prop instead of data" })) }),
+    async execute(_id, a) {
+      if (!(a.card in cards.cards)) return result(`error: no card '${a.card}'. Cards: ${Object.keys(cards.cards).join(", ")}`);
+      const locked = cards.locked(a.card);
+      if (locked) return result(locked);
+      const r = cards.get(a.card), agent = pi.getSessionName() ?? "agent";
+      if (a.block !== undefined) {  // as the page's card_prop: the structure only via card_show
+        const b = (r.blocks ?? []).find((b: any) => b.id === a.block);
+        if (!b) return result(`error: no block '${a.block}' in ${a.card}. Blocks: ${(r.blocks ?? []).map((b: any) => b.id).join(", ") || "none (an app)"}`);
+        if (STRUCTURE.includes(a.path)) return result(`error: '${a.path}' changes the structure: use card_show`);
+        b[a.path] = a.value;
+        const errors = problems(r.blocks, r.made_from);
+        if (errors.length) return result("error: " + errors.join("; "));
+        cards.change(a.card, r, agent, `set ${a.path} of ${a.block} in ${a.card}`);
+        return result("updated");
+      }
+      setPath(r.data, a.path, a.value);
+      cards.change(a.card, r, agent, `changed ${a.path} in ${a.card}`);
+      return result("updated");
+    },
+  });
+
+  pi.registerTool({
+    name: "card_remove", label: "Card remove", description: "Take a card off its board.",
+    parameters: Type.Object({ card: Type.String() }),
+    async execute(_id, a) {
+      if (!(a.card in cards.cards)) return result(`error: no card '${a.card}'. Cards: ${Object.keys(cards.cards).join(", ")}`);
+      const locked = cards.locked(a.card);
+      if (locked) return result(locked);
+      const users = cards.copyIntoUsers(a.card), agent = pi.getSessionName() ?? "agent";
+      cards.change(a.card, null, agent, `removed ${a.card}` + (users.length ? ` (${users.join(", ")} got a copy)` : ""));
+      return result("removed" + (users.length ? `; ${users.join(", ")} read from it, so they got a copy of its data` : ""));
+    },
+  });
+
+  // The page side: registered once for all agents (keyed by name, so each agent's load replaces the last one)
+  const json = (res: any, v: unknown) => res.writeHead(200, { "content-type": "application/json" }).end(JSON.stringify(v));
+  host.routes.set("/card/all", (_req: any, res: any) => json(res, cards.cards));
+  host.routes.set("/card/blocks", (_req: any, res: any) => json(res, Object.fromEntries(Object.entries(readCatalog()).map(([n, m]: any) => [n, m.mtime]))));
+  host.routes.set("/card/about", (_req: any, res: any) =>
+    json(res, Object.fromEntries(Object.entries(readCatalog()).filter(([, m]: any) => m.about).map(([n, m]: any) => [n, m.about]))));
+  host.routes.set("/card/", (req: any, res: any) => {  // the blocks' code and the libraries they import
+    let url = "";
+    try { url = path.posix.normalize(decodeURIComponent(new URL(req.url, "http://x").pathname)); } catch {}  // bad %-escape: 404
+    if (url.startsWith("/card/blocks/") && url.endsWith(".js")) return host.file(res, path.join(BLOCKS, url.slice("/card/blocks/".length)));
+    if (url.startsWith("/card/lib/")) return host.file(res, path.join(LIB, url.slice("/card/lib/".length)));
+    const lib = url.slice("/card/node_modules/".length);
+    if (url.startsWith("/card/node_modules/") && LIBS.some((l) => lib.startsWith(l))) return host.file(res, path.join(host.modules, lib));
+    res.writeHead(404).end();  // also a ".." out of /card/
+  });
+  host.pageHandlers.set("card", (msg: any) => {
+    const { type, card: id } = msg;
+    const r = typeof id === "string" ? cards.get(id) : undefined;
+    if (!r || !type?.startsWith("card_")) return;
+    if (type === "card_close") {
+      const users = cards.copyIntoUsers(id);
+      cards.change(id, null, "user", `closed ${id}` + (users.length ? ` (${users.join(", ")} got a copy)` : ""));
+    }
+    else if (type === "card_move") {
+      if (r.pinned) return host.broadcast("card", { op: "render", card: id, ...r });
+      r.place = msg.place; cards.change(id, r, "user", `moved ${id}`);
+    } else if (type === "card_board" && host.api.board?.has(msg.board)) {  // dropped on another board's thumbnail
+      if (r.pinned) return host.broadcast("card", { op: "render", card: id, ...r });
+      r.board = msg.board; r.place = msg.place ?? null; cards.change(id, r, "user", `moved ${id} to board ${msg.board}`);
+    } else if (type === "card_set") { setPath(r.data, msg.path ?? "/", msg.value); cards.change(id, r, "user", `changed ${msg.path} in ${id}`); }
+    else if (type === "card_prop") {
+      for (const b of r.blocks ?? []) if (b.id === msg.block && !STRUCTURE.includes(msg.prop)) b[msg.prop] = msg.value;
+      cards.change(id, r, "user", `set ${msg.prop} of ${msg.block} in ${id}`);
+    } else if (type === "card_pin") { r.pinned = !!msg.pinned; cards.change(id, r, "user", `${r.pinned ? "pinned" : "unpinned"} ${id}`); }
+    else if (type === "card_keep" && r.options) {
+      const o = r.options[Number(msg.index ?? 0)];
+      delete r.options;
+      if (o) {
+        delete r.blocks; delete r.app;
+        Object.assign(r, o.app ? { app: o.app } : { blocks: o.blocks }, { data: o.data });
+        cards.change(id, r, "user", `kept ${o.label} of ${id}`);
+      }
+    } else if (type === "card_action") {
+      r.data = msg.data ?? r.data;
+      cards.change(id, r, "user", `used ${msg.name} in ${id}`);
+      host.send("user", r.owner, `[card action] ${msg.name} on card '${id}' (${msg.block === "app" ? "its app" : `block ${msg.block}`})\n`
+        + `context: ${JSON.stringify(msg.context ?? {})}\ndata: ${JSON.stringify(r.data)}`);
+    }
+  });
+}

package/{app/extensions/commands → agent/extensions/command}/browser.js

@@ -1,9 +1,9 @@
-// Browser half of the commands extension: the agents' pi commands (GET /commands) join the "/" list in the chat
+// The page side of the command extension: the agents' pi commands (GET /command) join the "/" list in the chat
 // input. One runs on the agent picked in "to" (agent1 if none), with the words after it.
 export default function (page) {
   const target = () => document.getElementById("to")?.value || "main";
-  page.on("commands", (ev) => page.note(`${ev.agent}: ${ev.text}`));
-  fetch("/commands").then((r) => r.ok ? r.json() : []).then((list) => {
+  page.on("command", (ev) => page.note(`${ev.agent}: ${ev.text}`));
+  fetch("/command").then((r) => r.ok ? r.json() : []).then((list) => {
     for (const c of list) page.command(c.name, (rest) => {
       const agent = target() === "main" ? "agent1" : target();
       page.note(`/${c.name} → ${agent}`);

package/agent/extensions/command/guide.md

@@ -0,0 +1,2 @@
+# Commands
+The user's "/" commands for an agent (e.g. /compact) are pi commands in {agent}/extensions/command/index.ts.

package/{app/extensions/commands → agent/extensions/command}/index.ts

@@ -1,10 +1,10 @@
-// Agent commands: pi's built-in "/" commands live in its terminal UI only, so an SDK session doesn't have them. Each
+// Commands: pi's built-in "/" commands live in its terminal UI only, so an SDK session doesn't have them. Each
 // one here is a pi command (pi.registerCommand) that calls what the built-in calls (pi's docs/extensions.md).
 // The page lists every pi command an agent has and sends one to the agent picked in "to" (pi runs it at once, even
 // mid-run: session.prompt checks for commands first).
-//   GET /commands                             -> [{name, description}] (agent1's, from app/extensions)
+//   GET /command                              -> [{name, description}] (agent1's, from agent/extensions)
 //   page message  command {agent, text: "/name args"}
-//   page event    commands {agent, text}        -> a plain note (e.g. /compact with nothing new)
+//   page event    command  {agent, text}        -> a plain note (e.g. /compact with nothing new)
 import fs from "node:fs";
 import path from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
@@ -12,12 +12,10 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 const host = (globalThis as any).chalky;
 
 export default function (pi: ExtensionAPI) {
-  const guide = fs.readFileSync(path.join(import.meta.dirname, "guide.md"), "utf8");
-  pi.on("before_agent_start", (event) => { event.systemPromptOptions.sections.commands = guide; });
 
   // pi's /compact: summarize the conversation now (the page shows "history compacted" when it's done). Whatever its
   // size: keepRecentTokens is 0 for this one (in memory, not saved), so all but the newest message is summarized;
-  // the automatic compaction keeps app/settings.json's.
+  // the automatic compaction keeps agent/settings.json's.
   pi.registerCommand("compact", {
     description: "Summarize the agent's conversation now (words after it: what the summary should focus on)",
     handler: async (args, ctx) => {
@@ -25,7 +23,7 @@ export default function (pi: ExtensionAPI) {
       // nothing said since the last compaction (its note is the newest entry): skip, it would only re-summarize the summary
       const last = ctx.sessionManager.getLeafEntry();
       if (last?.type === "compaction" || (last?.type === "custom_message" && last.customType === "compacted"))
-        return host.broadcast("commands", { agent, text: "nothing new since the last compaction" });
+        return host.broadcast("command", { agent, text: "nothing new since the last compaction" });
       const settings = host.agents.get(agent).session.settingsManager;
       const keep = settings.getSettings().compaction?.keepRecentTokens;
       settings.applyOverrides({ compaction: { keepRecentTokens: 0 } });
@@ -47,11 +45,11 @@ export default function (pi: ExtensionAPI) {
       if (level && !session.getAvailableThinkingLevels().includes(level))
         return host.broadcast("error", { agent, text: `thinking: "${level}" isn't one of ${levels}` });
       if (level) pi.setThinkingLevel(level);
-      host.broadcast("commands", { agent, text: `thinking ${pi.getThinkingLevel()}${level ? "" : ` (${levels})`}` });
+      host.broadcast("command", { agent, text: `thinking ${pi.getThinkingLevel()}${level ? "" : ` (${levels})`}` });
     },
   });
 
-  // pi's /new: an empty conversation for this agent (the swarm's reset: a new session file, role and thinking kept;
+  // pi's /new: an empty conversation for this agent (the team's reset: a new session file, role and thinking kept;
   // the old file stays). After this command returns: the reset replaces the session that is running it.
   pi.registerCommand("new", {
     description: "Start a new, empty conversation for the agent (its role stays; the old one is kept on disk)",
@@ -59,10 +57,10 @@ export default function (pi: ExtensionAPI) {
       const agent = pi.getSessionName()!;
       const thinking = pi.getThinkingLevel();
       setTimeout(async () => {
-        const error = await host.api.swarm.reset([agent]);
+        const error = await host.api.team.reset([agent]);
         if (error) return host.broadcast("error", { agent, text: `new: ${error}` });
         host.agents.get(agent).session.setThinkingLevel(thinking);
-        host.broadcast("commands", { agent, text: "new conversation" });
+        host.broadcast("command", { agent, text: "new conversation" });
       });
     },
   });
@@ -71,21 +69,21 @@ export default function (pi: ExtensionAPI) {
   // happened and where the full conversation still is (pi only appends to the session file; nothing is deleted)
   pi.on("session_compact", (event, ctx) => {
     const time = new Date().toTimeString().slice(0, 8);
-    pi.sendMessage({ customType: "compacted", display: false, content: `[note from system · ${time}]\nYour ` +
+    pi.sendMessage({ customType: "compacted", display: false, content: `[fyi from system · ${time}]\nYour ` +
       `conversation was just compacted (${event.reason}): what came before is the summary above. The full ` +
       `conversation is still in ${ctx.sessionManager.getSessionFile()} when the summary isn't enough. Its lines are ` +
       `long JSON entries, so print only around a match: grep -oE '.{0,300}words.{0,300}' <file>` });
   });
 
-  host.routes.set("/commands", (_req: any, res: any) => {
-    // only ours (app/extensions): pi's built-in extensions' commands are terminal screens (e.g. its MCP's /mcp)
+  host.routes.set("/command", (_req: any, res: any) => {
+    // only ours (agent/extensions): pi's built-in extensions' commands are terminal screens (e.g. its MCP's /mcp)
     const runner = host.agents.get("agent1")?.session.extensionRunner;
-    const list = (runner?.getRegisteredCommands() ?? []).filter((c: any) => c.sourceInfo?.path?.startsWith(host.app))
+    const list = (runner?.getRegisteredCommands() ?? []).filter((c: any) => c.sourceInfo?.path?.startsWith(host.agent))
       .map((c: any) => ({ name: c.invocationName, description: c.description ?? "" }));
     res.writeHead(200, { "content-type": "application/json" }).end(JSON.stringify(list));
   });
 
-  host.pageHandlers.set("commands", async (msg: any) => {
+  host.pageHandlers.set("command", async (msg: any) => {
     if (msg.type !== "command") return;
     const name = host.agents.has(msg.agent) ? msg.agent : "agent1";
     // a running turn is stopped first, on purpose (compact would abort it anyway; this way it isn't shown as an error)

package/agent/extensions/doodle/README.md

@@ -0,0 +1,57 @@
+# Doodles (the doodle extension)
+The page is a shared board. The user draws on it (lines, arrows, circles, words in handwriting), clicks through it
+while drawing, then sends it all with a few words; you answer on the same board with your own pen, in your colour.
+
+## What you get: "[doodles on the page] <their words>"
+- group: the id of this batch (g3). Their marks stay on the page after they send; your marks in reply join the group.
+- marks still on the page: one line per mark (m7, m8, ...) with what the page can tell from the geometry alone:
+  "closed loop around "12.50" (card shop)", "line under "Total"", "open line from "Milk" to "Bread"", "handwriting
+  "why?" beside "Total"", with its box in main-space px. It names what is near; the picture shows what they meant.
+- other groups still on the page: earlier batches, answered or dimmed (older), that nobody has cleared yet.
+- the steps, in order: a picture of the screen as they saw it, with their drawing on it (cropped to the drawing; the
+  pictures are attached to the message, in step order), which part of the page it shows (main-space px), the words
+  they wrote on it (exactly), then what they clicked to get to the next step.
+
+Read it as a story: step 1 is how it is and what they marked; their clicks lead to step 2; and so on. A step with
+nothing drawn after clicks is how the screen looked after them: often the point ("after Save, this should show the date").
+Look at every picture closely: the drawing is the message. A line from A to B links them ("this goes there", "this
+feeds that"); a circle or a box points at the thing to change; a cross removes; handwriting says what.
+- To place something where they drew (on empty space): the picture's area maps to the page, so a mark's spot in the
+  picture is a spot on the page; card_show(..., place=<that box>).
+- If the drawing could mean two quite different things, don't change anything: mark the options and ask which.
+
+## Your pen: doodle_mark(gesture, on, to?, words?, group?)
+You name the thing; the page draws it by hand in your colour, and keeps it on that thing if the card moves.
+- gesture: ring (circle it: look here, a problem, an option), underline, strike (through it: this is wrong), tick (✓
+  beside it: yes, this one), cross (✕ over it: only for "remove this"; a crossed-out row reads as delete), arrow
+  (from on to to), none (only words).
+- on / to: {card, block, element, text, mark, note}, as few as name it exactly. text is the exact words shown on the
+  page (the mark goes on just those characters), element a CSS selector or an element's id or data-name (also inside
+  an app's frame), mark one of the marks (theirs or yours: m7). Example: {"card": "shop", "text": "12.50"}.
+- The page's own controls can be marked too, by name: {element: "pen"} (the marker), "text", "eraser", "show-marks"
+  (the eye), "note" (the note pencil), "frames", "files", "dictate" (the mic), "tools" (the whole palette, top centre),
+  "rail" (left edge), "messages", "versions", "message-line" (bottom), "boards" (the shelf above it), "new-board". Such
+  marks stay fixed to the window. Good for a tour: ring "pen" with "draw here".
+- at: {x, y, width, height} in window px, as screen_see's picture shows it: a last resort for something with no name
+  (empty space, a spot in a picture). Look first (screen_see), then mark.
+- words: at most 40 characters, handwritten beside it. Longer things go in a note (note_add).
+- group: the group you are answering; left out, the group of the message you are answering. With none (a plain
+  message, a review you were asked for), your marks start a group of your own.
+The tool checks the thing on the open page and says if it can't find it: then name it as it is on the page.
+
+When to use it: to show (ring the cell that is wrong), to point (an arrow from the input to the total), to confirm
+(tick the one you changed), to ask which one (ring two options, words "this one or this?"). A mark is a pointer, not an
+essay: one mark per thing, a few words. Explanations, questions with context, anything they may answer: a note.
+
+## Groups and clearing
+Each send with marks is a group: their marks, then yours. Nothing clears by itself. The user taps a group's ✓ to clear
+it; you call doodle_clear(group) when a group is done. Two cases:
+- They asked for a change ("remove this", "make it green") and you made it: clear the group in that same turn. The
+  change is the answer, and their marks now point at something that has changed or gone. Don't add a tick to confirm.
+- Your answer is on the board (you marked options, pointed something out, asked, left a note): leave the group, or
+  your marks vanish before they are seen. Clear it in a later turn, once they have moved on or said it's fine.
+Don't clear a group whose question is still open. Earlier groups still on the page (listed with each message) that
+are done: clear them too. When you marked several things (a review) and deal with one of them, take just that mark
+away: doodle_clear(mark="m7") (your own marks only; that one goes for good), and leave the rest up. Cleared marks go
+for everyone; the user can bring them back from the chat log (you get an fyi when they clear or bring one back).
+When the user sends something new, answered groups dim: still there, but older.