@chalky/chalky 0.1.3 → 0.1.5

package/{app/extensions/swarm → agent/extensions/team}/index.ts

@@ -1,46 +1,42 @@
-// Peer-to-peer swarm (port of the Python swarm plugin, on pi's pieces): no manager; anyone (the user or an agent)
+// The team: peer-to-peer agents, no manager; anyone (the user or an agent)
 // can talk to any agent. Every agent is its own pi session (host.createAgent). A message starts a turn, and the
 // turn's final answer goes back to whoever is owed it. Nothing is said "to no one".
 //   - Kinds of item:  message  from the user or the harness; the answer is shown in the chat
-//                     question ask_agent: the asker waits; the answer is its tool result
-//                     note     tell: the sender goes on; the answer comes back to it as a reply
-//                     reply    the answer to a note (or to a question that timed out)
-//                     fyi      a tell to the agent you owe your answer to: an update, not a request (no answer back)
-//   - Each item has a chain: who gets the answer, nearest first. A note from agent1 (working for the user) has
+//                     question team_ask: the asker waits; the answer is its tool result
+//                     request  team_tell: the sender goes on; the answer comes back to it as a reply
+//                     reply    the answer to a request (or to a question that timed out)
+//                     fyi      a team_tell to the agent you owe your answer to: an update, not a request (no answer back)
+//   - Each item has a chain: who gets the answer, nearest first. A request from agent1 (working for the user) has
 //     chain [agent1, user]; agent2's answer goes to agent1 as a reply with chain [user], and agent1's answer to that
 //     reply goes to the user. So replies never bounce back and forth.
-//   - Notes, replies and fyis for an agent in the middle of a turn: pi's steer() (it sees them between its tool calls;
+//   - Requests, replies and fyis for an agent in the middle of a turn: pi's steer() (it sees them between its tool calls;
 //     no turn of their own). An fyi for an idle agent: pi's sendCustomMessage() (filed; the model sees it next turn).
 //     Messages and questions wait in the inbox for a turn of their own, one at a time.
-//   - Limits: asks + tells per user message, agents, inbox size, notes per minute, identical notes dropped, ask
-//     timeout. Asking an agent that is waiting on you is refused (use tell).
-// Shared state is plain data on the host (host.shared "swarm"); the code that acts on it is this file's newest load
-// (host.api.swarm), so an edited swarm/index.ts takes effect after a reload. Agents: host.agents (role, app, session).
+//   - Limits: asks + tells per user message, agents, inbox size, requests per minute, identical requests dropped, ask
+//     timeout. Asking an agent that is waiting on you is refused (use team_tell).
+// Shared state is plain data on the host (host.shared "team"); the code that acts on it is this file's newest load
+// (host.api.team), so an edited team/index.ts takes effect after a reload. Agents: host.agents (role, app, session).
 // Pictures with a message (doodle's steps): send(..., images) takes png paths; they go to pi with the text (prompt
 // or steer), read when the agent gets the message.
-// Not ported: the tasks plugin's "blocked" state.
 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 MAX_MESSAGES = Number(process.env.SWARM_MAX_MESSAGES || 50);  // ask_agent + tell calls per user message
-const MAX_AGENTS = Number(process.env.SWARM_MAX_AGENTS || 8);
-const ASK_TIMEOUT = Number(process.env.SWARM_ASK_TIMEOUT || 600);   // seconds; then the answer comes as a reply
+const MAX_MESSAGES = Number(process.env.TEAM_MAX_MESSAGES || 50);  // team_ask + team_tell calls per user message
+const MAX_AGENTS = Number(process.env.TEAM_MAX_AGENTS || 8);
+const ASK_TIMEOUT = Number(process.env.TEAM_ASK_TIMEOUT || 600);   // seconds; then the answer comes as a reply
 const INBOX_CAP = 50;          // items waiting for one agent
-const NOTES_PER_MINUTE = 20;   // per sender
-const APP_MESSAGES_PER_MINUTE = 30;  // from apps (the page) to agents
-const TEAM = fs.readFileSync(path.join(import.meta.dirname, "guide.md"), "utf8")  // short; README.md: the whole of it
-  .replace("README.md", path.join(import.meta.dirname, "README.md"));
+const REQUESTS_PER_MINUTE = 20;   // per sender
 
 type Waiter = { resolve: (answer: string) => void } | null;
 type Item = { kind: string; sender: string; text: string; chain: string[]; ts: number; waiter: Waiter; images?: string[] };
 
-if (!host.shared.has("swarm"))
-  host.shared.set("swarm", { inbox: {}, running: new Set(), chain: {}, waiting: {}, doing: {}, sent: 0, recent: {},
-                             lastNote: {}, appSent: [] });
-const S = host.shared.get("swarm");
+if (!host.shared.has("team"))
+  host.shared.set("team", { inbox: {}, running: new Set(), chain: {}, waiting: {}, doing: {}, sent: 0, recent: {},
+                             lastRequest: {} });
+const S = host.shared.get("team");
 const inbox = (name: string): Item[] => (S.inbox[name] ??= []);
 const isAgent = (name: string) => host.agents.has(name);
 const target = (chain: string[]) => (chain[0] && isAgent(chain[0]) ? chain[0] : "user");
@@ -64,7 +60,7 @@ const pictures = (paths: string[] = []) => paths.filter((p) => fs.existsSync(p))
 function put(to: string, kind: string, sender: string, text: string, chain: string[], waiter: Waiter = null, images?: string[]) {
   const item: Item = { kind, sender, text, chain, ts: Date.now(), waiter, images };
   const session = host.agents.get(to).session;
-  if (["note", "reply", "fyi"].includes(kind) && session.isStreaming) void session.steer(`${header(item)}\n${text}`, pictures(images));
+  if (["request", "reply", "fyi"].includes(kind) && session.isStreaming) void session.steer(`${header(item)}\n${text}`, pictures(images));
   else if (kind === "fyi")  // its turn ended before it was handed over: file it, don't start a turn
     void session.sendCustomMessage({ customType: "inbox", content: `${header(item)}\n${text}`, display: true });
   else {
@@ -141,11 +137,11 @@ function ask(asker: string, to: string, text: string, signal?: AbortSignal) {
 
 const api = {
   status,
-  // From the user or the harness (the page's chat, apps, ui actions). The answer is shown in the chat.
+  // From the user or the harness (the page's chat, apps, card actions). The answer is shown in the chat.
   // Returns the item (for withdraw). images: png paths sent with it.
-  send(sender: string, to: string, text: string, note = false, images?: string[]) {
+  send(sender: string, to: string, text: string, request = false, images?: string[]) {
     if (sender === "user") S.sent = 0;  // a new user message gives the team a fresh budget
-    return put(to, note ? "note" : "message", sender, text, [sender], null, images);
+    return put(to, request ? "request" : "message", sender, text, [sender], null, images);
   },
   // An update for an agent that doesn't start a turn (filed if idle, between its tool calls if busy)
   fyi(sender: string, to: string, text: string) { return put(to, "fyi", sender, text, [sender]); },
@@ -174,21 +170,16 @@ const api = {
     return null;
   },
 };
-host.api.swarm = api;
+host.api.team = api;
 
 const result = (text: string) => ({ content: [{ type: "text" as const, text }], details: undefined });
 
 export default function (pi: ExtensionAPI) {
   const me = () => pi.getSessionName()!;
-  pi.on("before_agent_start", (event) => {
-    const a = host.agents.get(me());
-    if (a) event.systemPromptOptions.sections.team = TEAM.replace("{name}", me()).replace("{role}", a.role)
-      .replace("{max_agents}", String(MAX_AGENTS));
-  });
   // What each agent is doing right now, for status
   pi.on("tool_execution_start", (ev) => {
     const args = ev.args ?? {};
-    changed(me(), `${ev.toolName} ${String(args.command ?? args.to ?? args.surface ?? args.path ?? "").slice(0, 60)}`.trim());
+    changed(me(), `${ev.toolName} ${String(args.command ?? args.to ?? args.card ?? args.path ?? "").slice(0, 60)}`.trim());
   });
   pi.on("turn_start", () => changed(me(), "thinking"));
 
@@ -200,18 +191,18 @@ export default function (pi: ExtensionAPI) {
   };
 
   pi.registerTool({
-    name: "spawn_agent", label: "Spawn agent",
+    name: "team_spawn", label: "Team spawn",
     description: "Create a new peer agent with a role. It starts idle. Agents are numbered in creation order (agent1, agent2, ...); "
       + "the result tells you the new name.",
     parameters: Type.Object({
       role: Type.String(),
       name: Type.Optional(Type.String({ description: "Only if the user asked for a specific name. Otherwise leave out." })),
-      app: Type.Optional(Type.String({ description: "The surface of the app this agent is part of (a simulation's member, a "
+      app: Type.Optional(Type.String({ description: "The card of the app this agent is part of (a simulation's member, a "
         + "character). Leave out for agents that work with you." })),
     }),
     async execute(_id, a) {
       if (a.name && (isAgent(a.name) || a.name === "user")) return result(`error: name '${a.name}' is taken`);
-      if (host.agents.size >= MAX_AGENTS) return result(`error: the team is full (${MAX_AGENTS} agents). Give work to an existing agent (list_agents).`);
+      if (host.agents.size >= MAX_AGENTS) return result(`error: the team is full (${MAX_AGENTS} agents). Give work to an existing agent (team_list).`);
       let name = a.name, n = host.agents.size + 1;
       while (!name || isAgent(name)) name = `agent${n++}`;  // next free number
       await host.createAgent(name, a.role, a.app);
@@ -221,7 +212,7 @@ export default function (pi: ExtensionAPI) {
   });
 
   pi.registerTool({
-    name: "reset_agent", label: "Reset agent",
+    name: "team_reset", label: "Team reset", exposure: "deferred",
     description: "Empty an agent's memory, keeping its role (for a new round that starts fresh). Give a name, or app to reset "
       + "all agents of that app. Only when they are idle.",
     parameters: Type.Object({ name: Type.Optional(Type.String()), app: Type.Optional(Type.String()) }),
@@ -235,48 +226,48 @@ export default function (pi: ExtensionAPI) {
   });
 
   pi.registerTool({
-    name: "tell", label: "Tell",
-    description: "Send a note to another agent and keep working (don't wait). Its answer comes back to you later as a reply.",
+    name: "team_tell", label: "Team tell",
+    description: "Send a request to another agent and keep working (don't wait). Its answer comes back to you later as a reply.",
     parameters: Type.Object({ to: Type.String(), text: Type.String() }),
     async execute(_id, a) {
       const agent = me(), now = Date.now();
       const error = checkTo(agent, a.to);
       if (error) return result(error);
       const recent = (S.recent[agent] ?? []).filter((t: number) => now - t < 60000);
-      if (S.lastNote[`${agent}>${a.to}`] === a.text) return result(`error: dropped, same as your last note to ${a.to}. It already has it.`);
-      if (recent.length >= NOTES_PER_MINUTE) return result(`error: slow down: at most ${NOTES_PER_MINUTE} notes a minute. Wait for replies instead.`);
+      if (S.lastRequest[`${agent}>${a.to}`] === a.text) return result(`error: dropped, same as your last request to ${a.to}. It already has it.`);
+      if (recent.length >= REQUESTS_PER_MINUTE) return result(`error: slow down: at most ${REQUESTS_PER_MINUTE} requests a minute. Wait for replies instead.`);
       if (inbox(a.to).length >= INBOX_CAP) return result(`error: ${a.to}'s inbox is full (${INBOX_CAP}). Wait for it to catch up.`);
       S.recent[agent] = [...recent, now];
-      S.lastNote[`${agent}>${a.to}`] = a.text;
+      S.lastRequest[`${agent}>${a.to}`] = a.text;
       S.sent++;
       if (owed(agent) === a.to) {  // it's owed your final answer anyway: an update, no answer back
         put(a.to, "fyi", agent, a.text, []);
         return result(`sent as information only: ${a.to} gets your final answer anyway, so don't repeat this there. `
-          + `It won't answer this; if you need an answer from ${a.to}, use ask_agent.`);
+          + `It won't answer this; if you need an answer from ${a.to}, use team_ask.`);
       }
-      put(a.to, "note", agent, a.text, [agent, ...(S.chain[agent] ?? [])]);
+      put(a.to, "request", agent, a.text, [agent, ...(S.chain[agent] ?? [])]);
       return result(`sent. ${a.to} is ${status()[a.to].state}; its answer will come to you as a reply. `
         + "If all you have left is waiting, end your turn: the reply wakes you.");
     },
   });
 
   pi.registerTool({
-    name: "ask_agent", label: "Ask agent",
-    description: "Ask another agent and wait for its answer (the result). For quick questions; use tell for longer work. "
-      + "Several ask_agent calls in one step run in parallel.",
+    name: "team_ask", label: "Team ask",
+    description: "Ask another agent and wait for its answer (the result). For quick questions; use team_tell for longer work. "
+      + "Several team_ask calls in one step run in parallel.",
     parameters: Type.Object({ to: Type.String(), text: Type.String() }),
     async execute(_id, a, signal) {
       const agent = me();
       const error = checkTo(agent, a.to);
       if (error) return result(error);
-      if (waitsOn(a.to, agent)) return result(`error: '${a.to}' is waiting on you, so it can't answer now. Use tell, or answer from what you know.`);
+      if (waitsOn(a.to, agent)) return result(`error: '${a.to}' is waiting on you, so it can't answer now. Use team_tell, or answer from what you know.`);
       S.sent++;
       return result(await ask(agent, a.to, a.text, signal));
     },
   });
 
   pi.registerTool({
-    name: "list_agents", label: "List agents", description: "List all agents: role, and what each is doing right now.",
+    name: "team_list", label: "Team list", description: "List all agents: role, and what each is doing right now.",
     parameters: Type.Object({}),
     async execute() {
       const now = Date.now() / 1000;
@@ -285,20 +276,4 @@ export default function (pi: ExtensionAPI) {
         + (s.queued ? `, ${s.queued} waiting in its inbox` : "")).join("\n"));
     },
   });
-
-  // From apps on the page (/ui/agents.js): a message to an app agent, or a fresh round for an app's agents
-  host.pageHandlers.set("swarm", async (msg: any) => {
-    if (msg.type === "app_reset") {
-      const names = [...host.agents.values()].filter((x: any) => x.app === msg.surface).map((x: any) => x.name);
-      const error = await api.reset(names);
-      if (error) host.broadcast("error", { agent: "app", text: `reset of ${msg.surface}: ${error}` });
-    } else if (msg.type === "app_message") {
-      const now = Date.now();
-      S.appSent = S.appSent.filter((t: number) => now - t < 60000);
-      if (!isAgent(msg.to)) host.broadcast("error", { agent: "app", text: `app message to unknown agent '${msg.to}'` });
-      else if (S.appSent.length >= APP_MESSAGES_PER_MINUTE)
-        host.broadcast("error", { agent: "app", text: `app message to ${msg.to} dropped: more than ${APP_MESSAGES_PER_MINUTE} a minute` });
-      else { S.appSent.push(now); api.send("app", msg.to, msg.text ?? ""); }
-    }
-  });
 }

package/{app/extensions/versions → agent/extensions/version}/browser.js

@@ -1,25 +1,25 @@
 // Pictures for the Versions panel, taken by the open page itself (no headless browser): after a new version (the
 // "version" event), and when the page opens and the current version has none yet. It draws the main space (#top)
 // with dom-to-image-more, then each same-site app frame's own page pasted in place (the library leaves frames
-// blank), crops to the surfaces plus a margin, and uploads it: PUT /versions/<sha>/shot (the first page wins).
+// blank), crops to the cards plus a margin, and uploads it: PUT /version/<sha>/shot (the first page wins).
 // Can't be drawn: video, and pictures or frames from other sites (those parts stay blank).
 const MARGIN = 32;
 let lib;
 const library = () => lib ??= new Promise((ok, no) => {  // loaded once, on the first picture
-  const s = Object.assign(document.createElement("script"), { src: "/versions/dom-to-image-more.js", onload: () => ok(window.domtoimage), onerror: no });
+  const s = Object.assign(document.createElement("script"), { src: "/version/dom-to-image-more.js", onload: () => ok(window.domtoimage), onerror: no });
   document.head.append(s);
 });
 const image = (src) => new Promise((ok, no) => Object.assign(new Image(), { onload() { ok(this); }, onerror: no, src }));
 
-async function picture() {  // a PNG blob of the surfaces, or null if there are none
-  const top = document.getElementById("top"), surfaces = [...top.querySelectorAll("[data-surface]")];
-  if (!surfaces.length) return null;
+async function picture() {  // a PNG blob of the cards, or null if there are none
+  const top = document.getElementById("top"), cards = [...top.querySelectorAll("[data-card]")];
+  if (!cards.length) return null;
   const domtoimage = await library(), at = top.getBoundingClientRect();
   const box = (el) => { const r = el.getBoundingClientRect(); return { x: r.left - at.left + top.scrollLeft, y: r.top - at.top + top.scrollTop, w: r.width, h: r.height }; };
-  const all = surfaces.map(box);
+  const all = cards.map(box);
   const x0 = Math.max(0, Math.min(...all.map((b) => b.x)) - MARGIN), y0 = Math.max(0, Math.min(...all.map((b) => b.y)) - MARGIN);
   const x1 = Math.max(...all.map((b) => b.x + b.w)) + MARGIN, y1 = Math.max(...all.map((b) => b.y + b.h)) + MARGIN;
-  const width = Math.ceil(x1), height = Math.ceil(y1);  // the whole main space up to the last surface; cropped below
+  const width = Math.ceil(x1), height = Math.ceil(y1);  // the whole main space up to the last card; cropped below
   const bgcolor = getComputedStyle(document.body).backgroundColor;
   const page = await image(await domtoimage.toPng(top, { width, height, bgcolor,
     style: { position: "static", inset: "auto", overflow: "visible", width: `${width}px`, height: `${height}px` } }));
@@ -44,7 +44,7 @@ let busy = Promise.resolve();
 function shoot(sha) {  // one picture at a time
   busy = busy.then(async () => {
     const png = await picture();
-    if (png) await fetch(`/versions/${sha}/shot`, { method: "PUT", body: png });
+    if (png) await fetch(`/version/${sha}/shot`, { method: "PUT", body: png });
   }).catch((e) => console.warn("versions: no picture", e));
 }
 
@@ -52,7 +52,7 @@ export default async function (page) {
   if (new URLSearchParams(location.search).has("shot")) return;  // the old headless view
   page.on("version", (ev) => setTimeout(() => shoot(ev.sha), 2000));  // after the page has redrawn what changed
   try {  // the current version has no picture yet (made while no page was open): take it now
-    const current = (await (await fetch("/versions")).json()).find((v) => v.current);
-    if (current && !current.shot) setTimeout(() => shoot(current.short), 3000);  // once the surfaces are drawn
+    const current = (await (await fetch("/version")).json()).find((v) => v.current);
+    if (current && !current.shot) setTimeout(() => shoot(current.short), 3000);  // once the cards are drawn
   } catch {}
 }

package/{app/extensions/versions → agent/extensions/version}/index.ts

@@ -1,67 +1,51 @@
-// Version history of the agents' own code, app/ (port of the Python versions plugin; the page's Versions panel is
-// unchanged). The history is a git repo kept OUTSIDE app/, in state/versions.git (the idea of pi-workspace-history):
-// app/ has no .git, so an agent's own git commands can't rewrite it. Its first commit is app/ as it was the first
-// time, tagged "original". Git through isomorphic-git (pure JS; no git program needed), one operation at a time.
-//   - When an agent's turn is over (pi's agent_settled) and app/ changed: commit, author = that agent, message =
+// Version history of agent/ and built/ together: what the agents are and what they made, so one rollback puts both
+// back. The repo and the rule for what it keeps (not logins, endpoints or installed packages) are the host's
+// (host.history, server.ts: /recover uses them too); this extension commits, lists and rolls back, one operation at
+// a time. Its first commit is both folders as they were the first time, tagged "original".
+//   - When an agent's turn is over (pi's agent_settled) and either folder changed: commit, author = that agent, message =
 //     its reload reason, else what it was asked (Python: what it first said, often just "done"), else what it said.
 //     Event "version" to the pages ({agent, sha, message, files, restart: false}: they refresh what changed).
 //   - Pictures for the panel: taken by the open page itself (browser.js here, with dom-to-image-more; no
 //     headless browser), after each new version and, when a page opens, for the current version if it has none.
-//     In state/shots/<sha>.png. A version made while no page was open and changed again before one opened: none.
-//   - GET  /versions                 commits, newest first ({sha, short, author, date, message, current, shot})
-//     GET  /versions/<sha>/shot      that commit's picture (404 if none; HEAD too)
-//     PUT  /versions/<sha>/shot      the page's picture (PNG, at most 10 MB; {saved: false} if it has one: the first page wins)
-//     POST /versions/<sha>/rollback  that commit's files as a NEW commit (history is never rewritten, so a rollback
+//     In data/version/shots/<sha>.png. A version made while no page was open and changed again before one opened: none.
+//   - GET  /version                  commits, newest first ({sha, short, author, date, message, current, shot})
+//     GET  /version/<sha>/shot      that commit's picture (404 if none; HEAD too)
+//     PUT  /version/<sha>/shot      the page's picture (PNG, at most 10 MB; {saved: false} if it has one: the first page wins)
+//     POST /version/<sha>/rollback  that commit's files as a NEW commit (history is never rewritten, so a rollback
 //                                    can be rolled back). The Python agent restarted its process; here: stop every
 //                                    agent, put the files back, reload every agent's extensions (pi's reload), read
-//                                    the surfaces again, and tell each agent (an fyi: no turn).
-//   - Not ported: pip freeze (Python's library list per version).
-// Ignored (info/exclude in the history repo): pi's auth.json, models-store.json and mcp-auth.json (logins), node_modules/.
-// Guard: app/ is the agents' code. If a commit includes other files, its agent is told to move them to the
-// workspace: a rollback would undo them.
+//                                    the cards again, and tell each agent (an fyi: no turn).
+// Guard: agent/ is the agents themselves. If a commit adds other files there, its agent is told where they belong
+// (built/ for what it makes for the user, workspace/ for project work).
 import fs from "node:fs";
 import path from "node:path";
 import git from "isomorphic-git";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
 const host = (globalThis as any).chalky;
-const GIT_DIR = path.join(host.state, "versions.git");
-const SHOTS = path.join(host.state, "shots");
+const { repo, kept, stage } = host.history;
+const SHOTS = path.join(host.data, "version", "shots");
 const MAX_SHOT = 10 * 1024 * 1024;
-const CODE = ["extensions/", "skills/", "ui/", "SYSTEM.md", "mcp.json"];
-const IGNORE = ["auth.json", "models-store.json", "mcp-auth.json", "node_modules/"];
-const repo = { fs, dir: host.app, gitdir: GIT_DIR };
 const who = (name: string) => ({ name, email: `${name}@chalky` });
 
-const shared = host.shared.get("versions") ?? { queue: Promise.resolve(), turnFrom: {} as Record<string, number> };
-host.shared.set("versions", shared);
+const shared = host.shared.get("version") ?? { queue: Promise.resolve(), turnFrom: {} as Record<string, number> };
+host.shared.set("version", shared);
 function queued<T>(fn: () => Promise<T>): Promise<T> {  // history operations one at a time (agents can finish together)
   const run = shared.queue.then(fn);
   shared.queue = run.catch(() => {});
   return run;
 }
 
-async function stage() {  // git add -A: every change in app/ into the index; the changed paths
-  const changed = [];
-  for (const [filepath, head, workdir, index] of await git.statusMatrix(repo)) {
-    if (head === 1 && workdir === 1 && index === 1) continue;  // unchanged
-    // new files: statusMatrix (1.44.2) checks ignores without our gitdir, so it misses info/exclude; isIgnored doesn't
-    if (head === 0 && index === 0 && await git.isIgnored({ ...repo, filepath })) continue;
-    if (workdir === 0) { if (index !== 0) await git.remove({ ...repo, filepath }); }
-    else await git.add({ ...repo, filepath });
-    changed.push(filepath);
-  }
-  return changed;
-}
 
-if (!fs.existsSync(GIT_DIR) && !shared.creating) shared.creating = queued(async () => {  // the first time (once, though every agent loads this): the history starts with app/ as it is
+// The first time (once per start, though every agent loads this): the history starts with both folders as they are.
+// "No commit yet", not "no repo yet": a start stopped between init and the first commit leaves a repo without HEAD.
+if (!shared.creating) shared.creating = queued(async () => {
+  try { await git.resolveRef({ ...repo, ref: "HEAD" }); return; } catch {}
   await git.init({ ...repo, defaultBranch: "main" });
-  fs.writeFileSync(path.join(GIT_DIR, "info/exclude"), IGNORE.join("\n") + "\n");
   await stage();
   await git.commit({ ...repo, message: "original", author: who("chalky") });
   await git.tag({ ...repo, ref: "original" });
 });
-else if (fs.existsSync(GIT_DIR)) fs.writeFileSync(path.join(GIT_DIR, "info/exclude"), IGNORE.join("\n") + "\n");  // a history from before an IGNORE change
 
 const head = async () => { await shared.queue; return git.resolveRef({ ...repo, ref: "HEAD" }); };  // after queued work (e.g. the first commit)
 
@@ -92,16 +76,16 @@ export default function (pi: ExtensionAPI) {
     }
     return queued(async () => {
       const changed = await commit(agent, message.slice(0, 100) || `changes by ${agent}`);
-      // files outside the code folders that are there now (a deleted one is the agent moving it: no new warning)
-      const stray = changed.filter((p) => !CODE.some((c) => p.startsWith(c)) && fs.existsSync(path.join(host.app, p)));
+      // files in agent/ that aren't part of an agent, there now (a deleted one is the agent moving it: no new warning)
+      const stray = changed.filter((p) => p.startsWith("agent/") && !host.isAgentPart(p.slice("agent/".length)) && fs.existsSync(path.join(host.home, p)));
       if (stray.length && host.agents.has(agent))
-        host.api.swarm?.send("system", agent, `Your last turn changed files in ${host.app} that aren't your code: ${stray.slice(0, 5).join(", ")}. `
-          + `${host.app} is your own code (extensions, skills, ui, SYSTEM.md, mcp.json): it is versioned, and a rollback would undo these files. `
-          + `Move project work to ${host.work} and use it from there.`, true);
+        host.api.team?.send("system", agent, `Your last turn added files to ${host.agent} that aren't part of you: ${stray.slice(0, 5).join(", ")}. `
+          + `${host.agent} is you (extensions, skills, SYSTEM.md, mcp.json, settings.json). Move what you make for the user to `
+          + `${host.built}, and project work to ${host.workspace}.`, true);
     });
   });
 
-  host.routes.set("/versions", async (_req: any, res: any) => {
+  host.routes.set("/version", async (_req: any, res: any) => {
     const now = await head();  // waits for queued work, so the log is complete
     const out = (await git.log(repo)).map(({ oid, commit: c }) => ({ sha: oid, short: oid.slice(0, 7), author: c.author.name,
       date: new Date(c.author.timestamp * 1000).toISOString(), message: c.message.split("\n")[0], current: oid === now,
@@ -109,7 +93,7 @@ export default function (pi: ExtensionAPI) {
     res.writeHead(200, { "content-type": "application/json" }).end(JSON.stringify(out));
   });
 
-  host.routes.set("/versions/", async (req: any, res: any) => {  // /versions/<sha>/shot, /versions/<sha>/rollback
+  host.routes.set("/version/", async (req: any, res: any) => {  // /version/<sha>/shot, /version/<sha>/rollback
     const [, , given, what] = new URL(req.url, "http://x").pathname.split("/");
     if (!/^[0-9a-f]{7,40}$/.test(given ?? "")) return res.writeHead(400).end();
     let sha: string;
@@ -138,31 +122,32 @@ export default function (pi: ExtensionAPI) {
     }
     if (what !== "rollback" || req.method !== "POST") return res.writeHead(404).end();
     const subject = `${sha.slice(0, 7)} ${(await git.readCommit({ ...repo, oid: sha })).commit.message.split("\n")[0]}`;
-    await host.api.swarm?.stop();
+    await host.api.team?.stop();
     const files = await queued(async () => {
       await commit("user", "uncommitted changes before rollback");  // nothing is ever lost
-      // that commit's files into app/ and the index, removing files it doesn't have; the branch stays where it is
-      await git.checkout({ ...repo, ref: sha, noUpdateHead: true, force: true });
-      const files = (await git.statusMatrix(repo)).filter(([, h, w, i]) => !(h === 1 && w === 1 && i === 1)).map(([f]) => f);
+      // that commit's agent/ and built/ into the folders and the index, removing files it doesn't have; the branch
+      // stays where it is. What the history doesn't keep (logins, endpoints) isn't touched.
+      await git.checkout({ ...repo, ref: sha, noUpdateHead: true, force: true, filepaths: kept.filepaths });
+      const files = await stage();
       // git keeps files, not folders: a folder whose files the rollback removed stays, empty (an extension folder
       // without index.ts would show in the map). Remove those, up to the first one that isn't empty.
-      for (const f of files) for (let d = path.dirname(f); d !== "."; d = path.dirname(d)) {
-        try { fs.rmdirSync(path.join(host.app, d)); } catch { break; }
+      for (const f of files) for (let d = path.dirname(f); !["agent", "built", "."].includes(d); d = path.dirname(d)) {
+        try { fs.rmdirSync(path.join(host.home, d)); } catch { break; }
       }
       await git.commit({ ...repo, message: `rollback to ${subject}`, author: who("user") });
       return files;
     });
     for (const name of host.agents.keys()) await host.reloadAgent(name);
-    if (files.includes("ui/surfaces.json")) { host.shared.get("ui")?.load(); host.api.uiHistory?.add("user", `rolled the code back to ${subject}`); }
+    if (files.includes("built/card.json")) { host.shared.get("card")?.load(); host.api.history?.add("user", `rolled back to ${subject}`); }
     for (const name of host.agents.keys())
-      host.api.swarm?.fyi("system", name, `The user rolled ${host.app} back to version ${subject}. Later changes are undone `
-        + `(still in the history: GET http://127.0.0.1:${host.port}/versions). Check before relying on them.`);
+      host.api.team?.fyi("system", name, `The user rolled ${host.agent} and ${host.built} back to version ${subject}. Later changes are undone `
+        + `(still in the history: GET http://127.0.0.1:${host.port}/version). Check before relying on them.`);
     const now = await head();
     host.broadcast("version", { agent: "user", sha: now.slice(0, 7), message: `rollback to ${subject}`, files, restart: false });
     res.writeHead(200, { "content-type": "application/json" }).end(JSON.stringify({ ok: true }));
   });
 
-  host.routes.set("/versions/dom-to-image-more.js", (_req: any, res: any) =>
+  host.routes.set("/version/dom-to-image-more.js", (_req: any, res: any) =>
     res.writeHead(200, { "content-type": "text/javascript" })
       .end(fs.readFileSync(path.join(host.modules, "dom-to-image-more/dist/dom-to-image-more.min.js"))));
 }

package/{app → agent}/extensions/viewer/README.md

@@ -1,12 +1,12 @@
 # Previews of the user's files (the viewer extension)
-The user can open any file in {work}/drops/ in a preview window (a click on its name in the file
-panel). A note pointed at that window has a part like {"viewing": "{work}/drops/q3.xlsx", "sheet":
+The user can open any file in {workspace}/drops/ in a preview window (a click on its name in the file
+panel). A note pointed at that window has a part like {"viewing": "{workspace}/drops/q3.xlsx", "sheet":
 "Costs", "cell": "B4"} (or "slide", "paragraph", "line"): the note is about that file and that spot, not
 about the page (ignore the note's source file then).
 - If the user drew around something there, the part says exactly what: {"sheet", "range": "B2:D5", "values"},
   {"paragraphs": [{"paragraph", "text"}]}, {"lines": [{"slide", "line", "text"}]} or {"slides": [...]},
   {"lines": "12-18", "text"}, or for an image {"region": {"x", "y", "width", "height"}} in the image's own
   pixels. On a pdf it is {"image": <png>}: a picture of the circled area as the user saw it; look at it with
-  read (read_document gives the pdf's text, to find the same words there).
-- read_document(path): a document's content as text (docx, pptx, xlsx, xls, csv, pdf, doc, txt), to see
+  read (viewer_read gives the pdf's text, to find the same words there).
+- viewer_read(path) (load it with tool_search): a document's content as text (docx, pptx, xlsx, xls, csv, pdf, doc, txt), to see
   what the user sees. For pictures use read.

package/{app → agent}/extensions/viewer/browser.js

@@ -1,10 +1,10 @@
-// Browser half of the viewer plugin: a preview window per file, opened by the files plugin's "file-open" DOM
+// The page side of the viewer extension: a preview window per file, opened by the file extension's "file-open" DOM
 // event {file: {name, path, size}} (a click on a row of the file panel, or files dropped on the page).
 // A window starts attached to its row: left of the panel, at the row's height, a notch pointing at it, the row
 // lit. Only one window is attached at a time (opening another file replaces it); dragging its label (shown
-// on hover, like a surface's: name, ✕) or resizing it from the corner detaches it, and then it stays where
+// on hover, like a card's: name, ✕) or resizing it from the corner detaches it, and then it stays where
 // it was put. ✕ closes it. Windows live only in this page (not saved, not seen by the agent).
-// Pointing at a window with the pen: point.js asks its partAt(x, y), which answers which file and where:
+// Pointing at a window with the pen: note/browser.js asks its partAt(x, y), which answers which file and where:
 // {viewing, sheet, cell} | {viewing, slide} | {viewing, paragraph} | {viewing, line} | {viewing}.
 // Drawing around something: partIn(points) answers what is inside the drawn shape (a thing whose middle is
 // inside it; if none, the thing under the drawing's middle), with its content, at most MAX_PICK characters:
@@ -83,19 +83,19 @@ export default async function (page) {
   const layer = el("div", { class: "viewers" });
   document.body.append(layer);
 
-  const rowOf = (path) => document.querySelector(`#side .files-row[data-path="${CSS.escape(path)}"]`);
+  const rowOf = (path) => document.querySelector(`#side .file-row[data-path="${CSS.escape(path)}"]`);
 
   function place(w) {  // attached: left of the panel, at the row's height (the folder button if the panel is closed)
     if (!w.attached) return;
     const row = rowOf(w.file.path);
     const visible = row && row.offsetParent;
-    const anchor = visible ? row : document.querySelector("#side .files-toggle");
+    const anchor = visible ? row : document.querySelector("#side .file-toggle");
     if (!anchor) return;
     const a = anchor.getBoundingClientRect(), panel = (visible ? row.parentElement : anchor).getBoundingClientRect();
     const h = w.box.offsetHeight, y = Math.max(72, Math.min(a.top - 14, innerHeight - h - 16));  // 72: below the palette
     Object.assign(w.box.style, { right: `${innerWidth - panel.left + 14}px`, left: "", top: `${y}px` });
     w.box.style.setProperty("--notch", `${Math.max(10, Math.min(a.top + a.height / 2 - y - 6, h - 22))}px`);
-    for (const r of document.querySelectorAll("#side .files-row.viewing")) r.classList.remove("viewing");
+    for (const r of document.querySelectorAll("#side .file-row.viewing")) r.classList.remove("viewing");
     if (visible) row.classList.add("viewing");
   }
   const placeAll = () => Object.values(windows).forEach(place);
@@ -103,7 +103,7 @@ export default async function (page) {
   document.addEventListener("scroll", placeAll, true);  // the panel's list scrolls
   const side = document.getElementById("side");
   if (side) new MutationObserver(() => {  // the list redrawn or the panel opened or closed
-    for (const w of Object.values(windows)) if (!rowOf(w.file.path) && w.attached && side.querySelector(".files-row")) close(w);  // file gone
+    for (const w of Object.values(windows)) if (!rowOf(w.file.path) && w.attached) close(w);  // file gone (deleted too)
     placeAll();
   }).observe(side, { childList: true, subtree: true, attributes: true, attributeFilter: ["data-open", "hidden"] });
 
@@ -148,7 +148,7 @@ export default async function (page) {
       left: `${Math.max(0, Math.min(r.left + dx, innerWidth - 60))}px`, top: `${Math.max(24, Math.min(r.top + dy, innerHeight - 40))}px` }));
     corner.onpointerdown = (e) => dragging(w, e, (r, dx, dy) => Object.assign(box.style, {
       width: `${Math.max(240, r.width + dx)}px`, height: `${Math.max(160, r.height + dy)}px` }));
-    box.partAt = (x, y) => {  // for point.js: which file, and where in it
+    box.partAt = (x, y) => {  // for note/browser.js: which file, and where in it
       const r = box.getBoundingClientRect();
       const hit = document.elementsFromPoint(r.left + x, r.top + y).find((e) => box.contains(e));
       const spot = hit?.closest("[data-part]");

package/agent/extensions/viewer/guide.md

@@ -0,0 +1,3 @@
+# Previews of the user's files
+A note whose part has "viewing": <a file> is about that spot in that file, not the page: read README.md before you
+handle one.