@chalky/chalky 0.0.0-stage → 0.1.4

package/app/extensions/ui/index.ts

@@ -0,0 +1,291 @@
+// UI surfaces from the page's components (port of the Python ui plugin; browser.js, the page side, is its ui.js).
+// Tools ui_catalog, ui_render, ui_update, ui_delete; guide.md, a short prompt section (README.md, copied from ui.py: the whole of it).
+// The surfaces are shared by every agent: one Surfaces 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
+// surface, who did it and the words for it ("you moved s1"; none: part of a bigger change). restore() puts back a
+// saved state (not a change: no watchers). Watchers (Python: the "ui_changed" event), registered from session_start:
+//   host.api.ui.watch(name, fn(surface, by, what))   name: the extension's, so its reload replaces its own
+// (ui_history: a step per change with words; frames: a frame is done when its surface appears).
+//   app/ui/surfaces.json  design (everything but data)      state/ui-data.json  data (what users typed)
+// In this folder: components/*.js (the catalog), agents.js and voice.js (what apps import), package.json and
+// node_modules/ (browser libraries components import), skills/ (ui-design, ui-check, agent-apps: given to pi).
+//   GET /ui/apps/<name>/...  an app (app/ui/apps: what the agents built)
+//   GET /ui/components/..., /ui/agents.js, /ui/voice.js  from this folder; /ui/node_modules/{marked,dompurify}/...  the host's
+//   GET /ui-api/catalog (name -> mtime), /ui-api/about (name -> about block), /ui-api/surfaces
+// App messages and app_reset: swarm/.
+import fs from "node:fs";
+import path from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+const host = (globalThis as any).chalky;
+const DESIGN = path.join(host.app, "ui/surfaces.json");
+const APPS = path.join(host.app, "ui/apps");
+const COMPONENTS = path.join(import.meta.dirname, "components");
+const SERVED = ["components/", "agents.js", "voice.js"];  // what /ui/ serves from this folder
+const LIBS = ["marked/", "dompurify/"];  // the page's browser libraries, from the host's node_modules (its package.json)
+const DATA = path.join(host.state, "ui-data.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 propsOf = (c: any) => Object.fromEntries(Object.entries(c).filter(([k]) => !["id", "component", "children", "child"].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, (sid: string, by?: string, what?: string) => void> = host.shared.get("ui-watchers") ?? new Map();
+host.shared.set("ui-watchers", watchers);
+host.api.ui = { watch: (name: string, fn: (sid: string, by?: string, what?: string) => void) => watchers.set(name, fn) };
+
+class Surfaces {
+  surfaces: Record<string, any> = read(DESIGN, {});
+  constructor() {
+    const data = read(DATA, {});
+    for (const [sid, r] of Object.entries(this.surfaces)) r.data = data[sid] ?? {};
+  }
+  save() {
+    fs.writeFileSync(DESIGN, JSON.stringify(Object.fromEntries(Object.entries(this.surfaces)
+      .map(([sid, r]) => [sid, { ...r, data: undefined }])), null, 1));
+    fs.writeFileSync(DATA, JSON.stringify(Object.fromEntries(Object.entries(this.surfaces).map(([sid, r]) => [sid, r.data ?? {}]))));
+  }
+  get(sid: string) { return clone(this.surfaces[sid]); }
+  snapshot() { return clone(this.surfaces); }
+  // 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(sid: string, record: any, by?: string, what?: string) {
+    if (record === null) delete this.surfaces[sid];
+    else this.surfaces[sid] = record;
+    this.save();
+    host.broadcast("ui", record === null ? { op: "delete", surface: sid } : { op: "render", surface: sid, ...record });
+    for (const [name, fn] of watchers) {
+      try { fn(sid, by, what); }
+      catch (e) { host.broadcast("error", { agent: "server", text: `ui watcher ${name}: ${e}` }); }  // one broken watcher doesn't stop the rest
+    }
+  }
+  load() {  // read the files again (after a rollback of the code changed surfaces.json); true if the surfaces changed
+    const before = JSON.stringify(this.surfaces), design = read(DESIGN, {}), data = read(DATA, {});
+    for (const [sid, r] of Object.entries(design) as any) r.data = data[sid] ?? {};
+    this.surfaces = design;
+    host.broadcast("ui", { op: "reset", surfaces: this.surfaces });
+    return JSON.stringify(this.surfaces) !== before;
+  }
+  restore(surfaces: Record<string, any>) {  // a whole saved state (undo, redo, rewind): not a change of its own
+    this.surfaces = clone(surfaces);
+    this.save();
+    host.broadcast("ui", { op: "reset", surfaces: this.surfaces });
+  }
+  locked(sid: string) {
+    return this.surfaces[sid]?.pinned ? `error: surface '${sid}' is pinned by the user, so agents can't change or delete it. `
+      + `Make a new surface instead (made_from=['${sid}'] keeps the link), or ask the user to unpin it.` : null;
+  }
+  copyIntoUsers(sid: string) {  // before sid goes: surfaces reading from it get its current values
+    const users = Object.keys(this.surfaces).filter((o) => o !== sid && this.surfaces[o].components
+      .some((c: any) => Object.values(propsOf(c)).some((v: any) => isRef(v) && v.ref === sid)));
+    for (const o of users) {
+      const r = this.get(o);
+      for (const c of r.components)
+        for (const [k, v] of Object.entries(propsOf(c)) as any)
+          if (isRef(v) && v.ref === sid) c[k] = clone(getPath(this.surfaces[sid].data, v.path));
+      this.change(o, r);
+    }
+    return users;
+  }
+}
+
+if (!host.shared.has("ui")) host.shared.set("ui", new Surfaces());
+const ui: Surfaces = host.shared.get("ui");
+
+function problems(components: any[], madeFrom: string[] = []) {
+  const catalog = readCatalog(), ids = new Set(components.map((c) => c.id));
+  const errors = ids.has("root") ? [] : ['one component must have "id": "root"'];
+  for (const c of components) {
+    if (!(c.component in catalog)) { errors.push(`${c.id}: unknown component '${c.component}' (have: ${Object.keys(catalog).join(", ")})`); continue; }
+    for (const child of [...(c.children ?? []), ...(c.child ? [c.child] : [])])
+      if (!ids.has(child)) errors.push(`${c.id}: child '${child}' is not defined`);
+    const known = catalog[c.component].about?.props;
+    for (const [k, v] of Object.entries(propsOf(c)) as any) {
+      if (known && !(k in known)) errors.push(`${c.id}: ${c.component} has no prop '${k}' (props: ${Object.keys(known).join(", ") || "none"})`);
+      if (isRef(v) && !(v.ref in ui.surfaces)) errors.push(`${c.id}.${k}: refers to surface '${v.ref}', which does not exist`);
+    }
+  }
+  return [...errors, ...madeFrom.filter((m) => !(m in ui.surfaces)).map((m) => `made_from: no surface '${m}'`)];
+}
+
+// The components (components/*.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(COMPONENTS).filter((f) => f.endsWith(".js")).sort()) {
+    const text = fs.readFileSync(path.join(COMPONENTS, 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(COMPONENTS, f)).mtimeMs / 1000), about, problem };
+  }
+  return out;
+}
+
+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) {
+  const guide = fs.readFileSync(path.join(import.meta.dirname, "guide.md"), "utf8")  // short; README.md: the whole of it, read when it says
+    .replace("README.md", path.join(import.meta.dirname, "README.md"));
+  pi.on("before_agent_start", (event) => { event.systemPromptOptions.sections.ui = guide; });
+  pi.on("resources_discover", () => ({ skillPaths: [path.join(import.meta.dirname, "skills")] }));
+  // a removed board (boards/) takes its surfaces with it: one step in the history (undo brings them back)
+  pi.on("session_start", () => host.api.boards?.onRemove("ui", (n: number) => {
+    const sids = Object.keys(ui.surfaces).filter((sid) => (ui.surfaces[sid].board ?? 1) === n);
+    const gone = sids.map((sid) => ({ owner: ui.surfaces[sid].owner, what: `surface ${sid}` }));
+    sids.forEach((sid, i) => {
+      ui.copyIntoUsers(sid);  // surfaces elsewhere reading from it keep its values
+      ui.change(sid, null, "user", i === sids.length - 1 ? `you removed board ${n} (${sids.join(", ")})` : undefined);
+    });
+    return gone;
+  }));
+
+  pi.registerTool({
+    name: "ui_catalog", label: "UI catalog", description: "List the UI components you can use in surfaces, 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(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: "ui_render", label: "UI render", description: "Draw or replace a UI surface (a card in the main space) from catalog components.",
+    parameters: Type.Object({
+      surface: Type.String(),
+      components: Type.Optional(Type.Array(Type.Record(Type.String(), Type.Any()))),
+      data: Type.Optional(Type.Record(Type.String(), Type.Any())),
+      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 components: [{"label", "components", "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 surface is, else the board the user is on' })),
+    }),
+    async execute(_id, a) {
+      const agent = pi.getSessionName() ?? "agent";
+      const locked = ui.locked(a.surface);
+      if (locked) return result(locked);
+      if (!a.components && !a.options) return result("error: give components, or options (a list of alternatives)");
+      const options = (a.options ?? []).map((o: any, i: number) => ({ label: o.label ?? `option ${i + 1}`, components: o.components ?? [], data: o.data ?? {} }));
+      for (const o of options.length ? options : [{ label: "", components: a.components! }]) {
+        const errors = problems(o.components, a.made_from);
+        if (errors.length) return result("error: " + (o.label ? `${o.label}: ` : "") + errors.join("; "));
+      }
+      const old = ui.surfaces[a.surface] ?? {}, catalog = readCatalog(), boards = host.api.boards;
+      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 first = options[0] ?? { components: a.components, data: a.data ?? {} };
+      const record: any = { owner: agent, components: first.components, data: first.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 : [first]).flatMap((o: any) => o.components)
+          .map((c: any) => [c.component, catalog[c.component].about?.version ?? 1])) };
+      for (const [k, v] of [["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 (boards/): 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();
+      ui.change(a.surface, record, agent, `${agent} drew ${a.surface}` + (options.length ? ` (${options.length} options)` : ""));
+      const where = boards ? `on board ${record.board}${a.board === "new" ? " (a new board)" : ""}` : "on screen";
+      return result(options.length ? `surface '${a.surface}' shows ${options.length} options ${where}; the user flips through them and keeps one`
+        : `surface '${a.surface}' is ${where}`);
+    },
+  });
+
+  pi.registerTool({
+    name: "ui_update", label: "UI update", description: "Change one value in a surface's data (e.g. a score or a list).",
+    parameters: Type.Object({ surface: Type.String(), path: Type.String({ description: "e.g. /score" }), value: Type.Any() }),
+    async execute(_id, a) {
+      if (!(a.surface in ui.surfaces)) return result(`error: no surface '${a.surface}'. Surfaces: ${Object.keys(ui.surfaces).join(", ")}`);
+      const locked = ui.locked(a.surface);
+      if (locked) return result(locked);
+      const r = ui.get(a.surface);
+      setPath(r.data, a.path, a.value);
+      const agent = pi.getSessionName() ?? "agent";
+      ui.change(a.surface, r, agent, `${agent} changed ${a.path} in ${a.surface}`);
+      return result("updated");
+    },
+  });
+
+  pi.registerTool({
+    name: "ui_delete", label: "UI delete", description: "Remove a UI surface.",
+    parameters: Type.Object({ surface: Type.String() }),
+    async execute(_id, a) {
+      const locked = ui.locked(a.surface);
+      if (locked) return result(locked);
+      const users = ui.copyIntoUsers(a.surface), agent = pi.getSessionName() ?? "agent";
+      ui.change(a.surface, null, agent, `${agent} deleted ${a.surface}` + (users.length ? ` (${users.join(", ")} got a copy)` : ""));
+      return result("deleted" + (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)
+  host.routes.set("/ui-api/catalog", (_req: any, res: any) => res.writeHead(200, { "content-type": "application/json" })
+    .end(JSON.stringify(Object.fromEntries(Object.entries(readCatalog()).map(([n, m]: any) => [n, m.mtime])))));
+  host.routes.set("/ui-api/about", (_req: any, res: any) => res.writeHead(200, { "content-type": "application/json" })
+    .end(JSON.stringify(Object.fromEntries(Object.entries(readCatalog()).filter(([, m]: any) => m.about).map(([n, m]: any) => [n, m.about])))));
+  host.routes.set("/ui/", (req: any, res: any) => {
+    let url = "";
+    try { url = path.posix.normalize(decodeURIComponent(new URL(req.url, "http://x").pathname)); } catch {}  // bad %-escape: 404
+    if (!url.startsWith("/ui/")) return res.writeHead(404).end();  // also a ".." out of /ui/
+    const p = url.slice("/ui/".length);
+    if (p.startsWith("apps/")) return host.file(res, path.join(APPS, p.slice("apps/".length)));
+    const lib = p.slice("node_modules/".length);
+    if (p.startsWith("node_modules/")) return LIBS.some((l) => lib.startsWith(l)) ? host.file(res, path.join(host.modules, lib)) : res.writeHead(404).end();
+    if (!SERVED.some((s) => p === s || (s.endsWith("/") && p.startsWith(s)))) return res.writeHead(404).end();
+    host.file(res, path.join(import.meta.dirname, p));
+  });
+  host.routes.set("/ui-api/surfaces", (_req: any, res: any) => res.writeHead(200, { "content-type": "application/json" }).end(JSON.stringify(ui.surfaces)));
+  host.pageHandlers.set("ui", (msg: any) => {
+    const { type, surface: sid } = msg;
+    const r = typeof sid === "string" ? ui.get(sid) : undefined;
+    if (!r) return;
+    if (type === "ui_close") {
+      const users = ui.copyIntoUsers(sid);
+      ui.change(sid, null, "user", `you closed ${sid}` + (users.length ? ` (${users.join(", ")} got a copy)` : ""));
+    }
+    else if (type === "ui_move") {
+      if (r.pinned) return host.broadcast("ui", { op: "render", surface: sid, ...r });
+      r.place = msg.place; ui.change(sid, r, "user", `you moved ${sid}`);
+    } else if (type === "ui_board" && host.api.boards?.has(msg.board)) {  // dropped on another board's thumbnail
+      if (r.pinned) return host.broadcast("ui", { op: "render", surface: sid, ...r });
+      r.board = msg.board; r.place = msg.place ?? null; ui.change(sid, r, "user", `you moved ${sid} to board ${msg.board}`);
+    } else if (type === "ui_set") { setPath(r.data, msg.path ?? "/", msg.value); ui.change(sid, r, "user", `you changed ${msg.path} in ${sid}`); }
+    else if (type === "ui_prop") {
+      for (const c of r.components) if (c.id === msg.component && !["id", "component", "children", "child"].includes(msg.prop)) c[msg.prop] = msg.value;
+      ui.change(sid, r, "user", `you set ${msg.prop} of ${msg.component} in ${sid}`);
+    } else if (type === "ui_pin") { r.pinned = !!msg.pinned; ui.change(sid, r, "user", `you ${r.pinned ? "pinned" : "unpinned"} ${sid}`); }
+    else if (type === "ui_keep" && r.options) {
+      const o = r.options[Number(msg.index ?? 0)];
+      delete r.options;
+      if (o) { r.components = o.components; r.data = o.data; ui.change(sid, r, "user", `you kept ${o.label} of ${sid}`); }
+    } else if (type === "ui_action") {
+      r.data = msg.data ?? r.data;
+      ui.change(sid, r, "user", `you used ${msg.name} in ${sid}`);
+      host.send("user", r.owner, `[ui action] ${msg.name} on surface '${sid}' (component ${msg.component})\n`
+        + `context: ${JSON.stringify(msg.context ?? {})}\ndata: ${JSON.stringify(r.data)}`);
+    }
+  });
+}

package/app/extensions/ui/skills/agent-apps/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: agent-apps
+description: Build an app whose members are real AI agents (a simulated board meeting, a debate, a negotiation, a panel of experts, game characters), run and shown by the app itself, in turns or all at once. Use when the user wants agents inside what you build, as opposed to agents helping you build it.
+---
+# Apps with real agents inside
+
+## Two kinds of agents: keep them apart
+|                   | Worker agents                   | App agents                                   |
+|-------------------|---------------------------------|----------------------------------------------|
+| What for          | help you build or fix the app   | are part of the app (a board member, a debater) |
+| Spawn             | `spawn_agent(role)`             | `spawn_agent(role, name, app="<surface>")`    |
+| Who talks to them | you (`tell`, `ask_agent`)       | the app, through `/ui/agents.js`             |
+| Messages panel    | shown                           | hidden: the app shows their talk             |
+| When they run     | while you build                 | each time the user runs the app              |
+
+Don't mix them: an app agent never edits code, and a worker never plays a character. The `app` label
+is what keeps app agents out of the user's messages panel and lets the app reset them.
+
+## Why the app runs the activity, not you
+Your context is large (system prompt plus everything you did while building): each of your model calls
+costs all of it, often 50k tokens or more. If you relay a meeting yourself (ask the chair who's next, ask
+that member, `ui_update` the transcript), every line spoken costs two or three of your calls. The app
+can talk to its agents directly, and their contexts are small. So you build, fix, and answer the user;
+at run time you make no calls at all.
+
+## Steps
+1. **Plan the members**: a short name each (it is the agent's name, seen in every event), and a role with
+   stance and personality. End each role with: "You are a character in <app>. Answer in plain text,
+   briefly, starting with [to: <name>] or [to: all]. Don't use tools." App agents have the same tools
+   you have; this keeps them in character, fast, and gives the app a "to" to draw.
+2. **Build the UI as an App**: `ui/apps/<name>/index.html` in your code folder (the one your prompt names, with
+   `extensions/` in it), and its scripts, shown with
+   `ui_render("<surface>", [{"id": "root", "component": "App", "src": "<name>/index.html"}])`.
+   An App can import `/ui/agents.js`; the bridge finds the app's surface from the frame it runs in.
+3. **Spawn the members once**, while building: `spawn_agent(role, name=..., app="<surface>")`, the same
+   string as the surface id. In the app, check `agents.list()`: if a member is missing, show that
+   instead of failing.
+4. **Wire the app with `/ui/agents.js`** (read its header):
+   - `send(to, text)`: ask a member. Its answer arrives as a `"message"` event: `agent` is that member,
+     `role` is `"assistant"`, and there are no `tool_calls` (its final answer).
+   - `on("message", fn)`: draw each answer as it arrives (speaker, the `[to: …]` target, the text).
+   - `reset()`: a fresh round, members' memories empty and roles kept. Call it before each run if the
+     user wants rounds to start fresh.
+   - `action(name, context)`: only for what needs you, e.g. "add a member" (you spawn it).
+5. **Run the activity in the app's own JavaScript**, the way the user asked:
+   - In turns: one member at a time; the next speaker comes from a rule or from a chair member (ask
+     it to answer "NEXT: <name>").
+   - All at once: send to several members together; answers come back in any order, so draw each one
+     as it arrives.
+   Members only know what you send them: include the transcript so far (or its last lines) each time.
+6. **Check it** with the ui-check skill: one short run, budget 2 or 3 messages (each is a real model call).
+
+## The ask helper (copy into the app)
+```js
+import agents from "/ui/agents.js";
+const waiting = {};  // member -> resolve() for its next final answer
+agents.on("message", (ev) => {
+  if (ev.role === "assistant" && !ev.tool_calls?.length && waiting[ev.agent]) {
+    waiting[ev.agent](ev.content);
+    delete waiting[ev.agent];
+  }
+});
+function ask(name, text) {  // send, then wait for that member's answer
+  const answer = new Promise((resolve) => (waiting[name] = resolve));
+  agents.send(name, text);
+  return answer;
+}
+// in turns:      const said = await ask(next, `${scenario}\nSo far:\n${lines.join("\n")}\nYour turn.`);
+// all at once:   const said = await Promise.all(names.map((n) => ask(n, prompt)));
+```
+Only start asking after the user presses Start: on load, past events are replayed first, and an
+answer from an earlier run must not resolve a new question.
+
+## Record and replay
+- Keep the run in the app: `[{ts, from, to, text}]` from the events. Replay draws them in `ts` order
+  with play, pause and a scrubber.
+- After a reload, past events replay: rebuild earlier runs from them (only your members' messages).
+  A member's `"system"` message means a fresh memory, i.e. a new round began.
+- Don't keep the transcript in the surface's data with `ui_update`: that is you relaying again.
+
+## Limits
+- App messages: at most 30 a minute (each is a model call); more are dropped with an `"error"` event.
+  Show the run's message budget in the UI and stop when it is spent.
+- At most 8 agents in all, you and any workers included.
+- An agent takes one turn at a time: sending to a busy member queues the message.
+
+## Pitfalls
+- Disable Start while a run is going: a double click starts two runs.
+- An answer without a `[to: …]` tag: treat it as to all.
+- If the app shows nothing, the panel won't help (app agents are hidden there): check the app with
+  ui-check, e.g. `eval:` the length of its transcript, and look for `"error"` events.

package/app/extensions/ui/skills/ui-check/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: ui-check
+description: Check a web UI in a real headless browser - JavaScript errors, failed requests, clipped or overflowing elements, how it looks, and whether clicks and keys work. Use after changing any UI (the page, UI components or surfaces, an app you built) and before calling UI work done.
+---
+# Checking a UI in a headless browser
+
+Reading the code back doesn't show what the user sees: the page is built when its scripts run, and
+layout only exists once the browser has computed it. So check UI work by running it.
+
+## 1. Run the check
+From this skill's folder (paths here are relative to it):
+```
+node scripts/check.mjs URL [STEPS ...] [--size 1280x800] [--shot /tmp/ui.png] [--full]
+```
+- URL: the user's page is `{page}/`. An app you built is served by it too
+  (`{page}/ui/apps/<name>/index.html`); any other file: `file:///<full path>`.
+- Steps run in order after the page loads (it gets 1.5 s first):
+  `wait:500`, `click:#pause`, `drag:#card=200,0`, `altdrag:#top=-150,0` (Alt held), `hold:.label=800` (press and hold),
+  `dblclick:.label`, `type:#message=hello`, `key:Enter`, `eval:document.querySelectorAll('.agent').length`,
+  `shot:/tmp/after.png`, `dialog:accept` (`node scripts/check.mjs --help` lists them).
+- confirm()/alert()/prompt() dialogs are answered for you and reported (`dialog confirm "Stop agent3?" -> dismissed`).
+  Default is dismiss (Cancel). Put `dialog:accept` (or `dialog:accept=TEXT` for a prompt) before the click
+  whose dialog you want to accept.
+- It prints errors (uncaught exceptions, console errors, failed requests), layout problems (an element
+  cut off by a box that hides overflow, an element sticking out of the window, cut-off text, sideways
+  scrolling), each step's result, and the screenshot path. Exit code 1 means a step failed or there were
+  errors. Layout problems don't change the exit code: judge each one (a decoration meant to bleed off the edge
+  is fine; a cut-off button isn't).
+
+Example: did the map fit, and does pause work?
+```
+node scripts/check.mjs {page}/ \
+  "eval:getComputedStyle(document.querySelector('#map')).height" click:#pause \
+  "eval:document.querySelector('#pause').textContent" --shot /tmp/ui.png
+```
+
+## The browser
+The check needs a headless browser. It uses $CHROME if set, else one downloaded before, else an installed
+Chrome, Chromium or Edge. If none is there it stops (exit code 2) and prints a download command with pinned
+versions: run exactly that command once (about 270 MB on disk; later runs reuse it), then run the check again. Only
+download when the check says none was found. If the download fails (no network, no space), tell the user what
+the error said; don't try other browsers or versions.
+
+## 2. Read the report, fix, run again
+- Fix every error and layout problem, or say in your evidence why one is fine.
+- Check at the size users have (1280x800) and a narrow one (`--size 390x844`) if the layout should adapt.
+- `eval:` is how you check state precisely: counts, text, sizes, a value your code exposes.
+
+## 3. Look at it
+The layout check sees elements, not pixels: a sprite drawn on a canvas, colours, contrast, overlapping
+drawings, whether it looks right at all - those need eyes. Take a screenshot (`--shot`) and look at it
+with `read(path)`, then check what you were looking for ("are all five agent sprites fully inside the map?
+is any text unreadable?"). Look after a real change, not after every run: each image stays in your
+conversation and adds to every later call.
+
+## Careful: the page is live
+`{page}/` is the real page connected to the real agents. A click or a typed message
+there really happens: sending a message wakes an agent, Stop stops everyone, rollback changes
+code. Click only what you mean to test, prefer pause/resume over stop, and test destructive controls
+on a copy (a replay, or your own test page), not on the live system. Dialogs are dismissed unless
+you say `dialog:accept`, so a "Stop agent3?" confirm only acts when you mean it to.
+
+## Good evidence for "done"
+The command you ran, its counts ("0 errors, 0 layout problems at 1280x800 and 390x844"), what the
+eval steps returned, and what you saw in the screenshot.
+
+## Pitfalls
+- `type:` splits at the first `=`: use a selector without one (`ui-textfield input`, not `[data-surface=x] input`).
+- `querySelector` doesn't reach inside a shadow root; use `eval:` with `el.shadowRoot.querySelector(...)`.
+- Content that arrives over the WebSocket may need `wait:1000` before you check it.
+- Chrome starts fresh for each run (no cookies, no storage); each run takes a few seconds.