@chalky/chalky 0.1.4 → 0.1.6

package/{app/extensions/swarm → agent/extensions/team}/README.md

@@ -1,4 +1,4 @@
-# Your team (the swarm extension)
+# Your team (the team extension)
 Your name and role are in your team section.
 You work with other AI agents as peers; there is no manager.
 
@@ -6,30 +6,30 @@ You work with other AI agents as peers; there is no manager.
 - What you receive starts with a header: "[<kind> from <name> · <time>]". <name> is "user" (the human),
   another agent, or a harness part ("system"). Kinds:
   message (from the user or the harness), question (the sender is waiting for your answer),
-  note (the sender went on working), reply (the answer to a note you sent),
+  request (the sender went on working), reply (the answer to a request you sent),
   fyi (an update from an agent working for you; its final answer still comes).
-- Your final answer in a turn is delivered for you: to the sender of a message, question or note; after a
+- Your final answer in a turn is delivered for you: to the sender of a message, question or request; after a
   reply, to whoever you were working for (the header says where). Say it once, there; don't repeat it.
-- tell(to, text): send a note and keep working. If the agent is busy it sees the note between its tool
+- team_tell(to, text): send a request and keep working. If the agent is busy it sees the request between its tool
   calls; if idle it starts on it. Its answer comes back to you later as a reply.
-  Notes that arrive while you work show up between your tool calls: if one needs an answer other than
-  your final one, answer it with tell.
-  A tell to the agent you are working for is information only (it gets your final answer anyway and won't
-  reply to the tell). To ask it something, use ask_agent.
-- Waiting: when all that is left is waiting for others, end your turn. Replies and notes wake
+  Requests that arrive while you work show up between your tool calls: if one needs an answer other than
+  your final one, answer it with team_tell.
+  A team_tell to the agent you are working for is information only (it gets your final answer anyway and won't
+  reply to it). To ask it something, use team_ask.
+- Waiting: when all that is left is waiting for others, end your turn. Replies and requests wake
   you. Never sleep or poll (no sleep loops, no repeated status checks).
-- Don't use tell to deliver your result: your final answer already gets there. Don't send thanks or
+- Don't use team_tell to deliver your result: your final answer already gets there. Don't send thanks or
   acknowledgements.
-- ask_agent(to, text): ask and wait for the answer (it comes back as the result). Use it for quick
-  questions you can't continue without; use tell for work that takes a while. Several ask_agent calls
-  in one step run in parallel. You can't ask an agent that is waiting on you (tell it instead).
-- list_agents shows the team and what each agent is doing right now (idle, working on what, waiting on
+- team_ask(to, text): ask and wait for the answer (it comes back as the result). Use it for quick
+  questions you can't continue without; use team_tell for work that takes a while. Several team_ask calls
+  in one step run in parallel. You can't ask an agent that is waiting on you (team_tell it instead).
+- team_list shows the team and what each agent is doing right now (idle, working on what, waiting on
   whom). Check it instead of asking agents for status.
-- spawn_agent adds a member (numbered agent1, agent2, ... in creation order; spawn_agent says when the team is full).
+- team_spawn adds a member (numbered agent1, agent2, ... in creation order; it says when the team is full).
   An agent that is part of something you build (a simulation's member, a character) is an app agent,
-  not a worker: load the agent-apps skill. spawn_agent(..., app=<its surface>) keeps its talk out of the
+  not a worker: load the app-agents skill. team_spawn(..., app=<its card>) keeps its talk out of the
   user's messages panel (the app shows it).
-  reset_agent(name, or app=<surface> for all of an app's agents) empties their memory, keeping their
+  team_reset(name, or app=<card> for all of an app's agents; load it with tool_search) empties their memory, keeping their
   roles: for a new round that should start fresh.
 
 # Working as a team
@@ -42,6 +42,6 @@ You work with other AI agents as peers; there is no manager.
 - Found a defect in someone else's work? Tell its owner what is wrong and how you found it; don't fix it
   in their files yourself.
 - When others' code will import yours, create the file (a stub) first so imports work while you build.
-- Before saying something is missing or not done, check again (files, list_agents): it may have changed.
+- Before saying something is missing or not done, check again (files, team_list): it may have changed.
 - Say so before installing anything or making a decision that affects others.
-- Other agents may change the same files (in {code} too). Check list_agents and coordinate with tell.
+- Other agents may change the same files (in {agent} too). Check team_list and coordinate with team_tell.

package/{app/extensions/swarm → agent/extensions/team}/guide.md

@@ -1,11 +1,11 @@
 # Your team
 Your name: {name}. Your role: {role}. You work with other AI agents as peers; there is no manager.
 - What you receive starts with "[<kind> from <name> · <time>]": a message (from the user or the harness), a
-  question (the sender waits for your answer), a note (the sender went on working), a reply (the answer to
-  your note) or an fyi (an update, no answer needed). Your final answer is delivered for you, to whoever the
+  question (the sender waits for your answer), a request (the sender went on working), a reply (the answer to
+  your request) or an fyi (an update, no answer needed). Your final answer is delivered for you, to whoever the
   header says: say it once, there.
-- tell(to, text) sends a note and you keep working; its answer comes back as a reply. ask_agent(to, text) asks
-  and waits. list_agents shows who is doing what now. spawn_agent adds a member (at most {max_agents}).
+- team_tell(to, text) sends a request and you keep working; its answer comes back as a reply. team_ask(to, text)
+  asks and waits. team_list shows who is doing what now. team_spawn adds a member (it says when the team is full).
 - When all that is left is waiting, end your turn: replies wake you. Never sleep or poll.
 - Done means checked: run or test it, and say what you ran and what it showed.
 - Simple work: do it yourself. Before you spawn, split or hand out work, or take work from another agent, read README.md.

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,26 @@
 // 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).
+// Also: when Chalky was updated at this start (GET /version/update), a notice says what changed or why it couldn't.
 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,15 +45,23 @@ 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));
 }
 
 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
+  fetch("/version/update").then((r) => r.json()).then((u) => {
+    if (!u) return;
+    const kept = u.conflicts?.length;
+    page.notice(u.error ? [`Chalky couldn't update to ${u.release}, so it runs as before. ${u.error}`]
+      : [`Updated to ${u.release}: ${u.files} file${u.files === 1 ? "" : "s"} changed.`
+        + (kept ? ` ${kept} kept your change; agent1 is merging the update into ${kept === 1 ? "it" : "them"}.` : "")
+        + " To undo it, go back a version in Versions."]);
+  }).catch(() => {});
   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/agent/extensions/version/index.ts

@@ -0,0 +1,205 @@
+// 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" (in an installed home,
+// server.ts makes the first one: "Started with Chalky <version>"; it also merges each new release, as a version).
+//   - When an agent's turn is over (pi's agent_settled) and either folder changed: commit, author = that agent. The
+//     message's first line (the label) says what changed, made here from facts, not from what was said: the card
+//     extension's words for the agent's card changes ("showed trip"), then the other changed things named from
+//     their paths (NAMES: "new app planner", "changed extension card"), at most 3, then its reload reason, if any.
+//     The second line: the first line of what it was asked (detail, not shown in the list).
+//     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 data/version/shots/<sha>.png. A version made while no page was open and changed again before one opened: none.
+//   - GET  /version                  the user's versions, newest first ({sha, short, author, date, message, current, shot}):
+//                                    host.history.versions(), so not the releases an update merged in
+//     GET  /version/update          this start's update of Chalky (server.ts's host.update), to the first page that
+//                                    asks (browser.js: a notice); later: null. {release, files, conflicts} or {release, error}
+//     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 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 { repo, stage, restore, versions } = host.history;
+const SHOTS = path.join(host.data, "version", "shots");
+const MAX_SHOT = 10 * 1024 * 1024;
+const who = (name: string) => ({ name, email: `${name}@chalky` });
+
+const shared = host.shared.get("version") ?? { queue: Promise.resolve(), turnFrom: {} as Record<string, number>, cards: {} as Record<string, string[]> };
+shared.cards ??= {};  // (shared state made by an older copy of this file, before a reload)
+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;
+}
+
+
+// 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" });
+  await stage();
+  await git.commit({ ...repo, message: "original", author: who("chalky") });
+  await git.tag({ ...repo, ref: "original" });
+});
+
+const head = async () => { await shared.queue; return git.resolveRef({ ...repo, ref: "HEAD" }); };  // after queued work (e.g. the first commit)
+
+async function commit(author: string, words: string | ((changed: string[]) => Promise<string>)) {  // the changed files, or [] if nothing changed
+  const changed = await stage();
+  if (!changed.length) return [];
+  const message = typeof words === "string" ? words : await words(changed);
+  let sha: string;
+  try { sha = await git.commit({ ...repo, message, author: who(author), disallowEmpty: true }); }
+  catch (e: any) { if (e.code === "EmptyCommitError") return []; throw e; }  // nothing really changed
+  host.broadcast("version", { agent: author, sha: sha.slice(0, 7), message: message.split("\n")[0], files: changed, restart: false });  // pages take its picture
+  return changed;
+}
+
+// A version's label: what changed, in words. The things a path is part of (anything else: the path itself):
+const NAMES: [RegExp, string][] = [
+  [/^agent\/extensions\/([^/]+)\//, "extension $1"],
+  [/^agent\/skills\/([^/]+)\//, "skill $1"],
+  [/^agent\/SYSTEM\.md$/, "instructions"],
+  [/^agent\/settings\.json$/, "settings"],
+  [/^built\/apps\/([^/]+)\//, "app $1"],
+  [/^built\/card\.json$/, "cards"],  // left out when the card extension's words say what changed
+  [/^built\/board\.json$/, "boards"],
+  [/^built\//, ""],                  // another file: its path in built/
+];
+function nameOf(p: string) {  // "agent/extensions/card/browser.js" -> "extension card"; "built/notes/a.txt" -> "notes/a.txt"
+  for (const [re, name] of NAMES) {
+    const m = p.match(re);
+    if (m) return name ? m[0].replace(re, name) : p.slice(m[0].length);
+  }
+  return p;
+}
+function describe(files: { path: string, how: "new" | "changed" | "removed" }[], cards: string[], reason?: string) {
+  const hows = new Map<string, Set<string>>();  // thing -> how its files changed
+  for (const f of files) { const t = nameOf(f.path); if (t !== "cards" || !cards.length) hows.set(t, (hows.get(t) ?? new Set()).add(f.how)); }
+  const parts = [...new Set(cards), ...[...hows].map(([t, h]) => `${h.size === 1 ? [...h][0] : "changed"} ${t}`)];
+  const label = parts.length > 3 ? `${parts.slice(0, 3).join("; ")} and ${parts.length - 3} more` : parts.join("; ");
+  return reason ? `${label}: ${reason.split("\n")[0]}` : label;
+}
+
+const textOf = (m: any) => typeof m.content === "string" ? m.content
+  : (m.content ?? []).filter((c: any) => c.type === "text").map((c: any) => c.text).join("\n");
+
+export default function (pi: ExtensionAPI) {
+  // the card extension's words for each card change, kept per agent while its turn runs (the user's: not an agent's)
+  pi.on("session_start", () => host.api.card?.watch("version", (_id: string, by?: string, what?: string) => {
+    if (what && by) shared.cards[by]?.push(what);
+  }));
+  pi.on("agent_start", (_e, ctx) => {
+    const agent = pi.getSessionName()!;
+    shared.turnFrom[agent] = ctx.sessionManager.getEntries().length;
+    shared.cards[agent] = [];
+  });
+  pi.on("agent_settled", (_e, ctx) => {
+    const agent = pi.getSessionName()!;
+    const turn = ctx.sessionManager.getEntries().slice(shared.turnFrom[agent] ?? 0).filter((e: any) => e.type === "message").map((e: any) => e.message);
+    const reason = host.shared.get(`reload-reason ${agent}`);
+    host.shared.delete(`reload-reason ${agent}`);
+    const cards = shared.cards[agent] ?? [];
+    delete shared.cards[agent];
+    const asked = turn.filter((m: any) => m.role === "user").map(textOf)
+      .flatMap((t: string) => t.split("\n").map((l) => l.trim())).find((l: string) => l && !/^\[\w+ (from|to) /.test(l)) ?? "";
+    return queued(async () => {
+      const changed = await commit(agent, async (files) => {
+        const before = new Set(await git.listFiles({ ...repo, ref: "HEAD" }));
+        const label = describe(files.map((p) => ({ path: p, how: !fs.existsSync(path.join(host.home, p)) ? "removed" : before.has(p) ? "changed" : "new" })), cards, reason);
+        return [label || `changes by ${agent}`, asked.slice(0, 200)].filter(Boolean).join("\n\n");
+      });
+      // 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.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("/version/update", (_req: any, res: any) => {
+    const u = host.update && !host.update.told ? host.update : null;
+    if (u) u.told = true;
+    res.writeHead(200, { "content-type": "application/json" }).end(JSON.stringify(u));
+  });
+  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 versions()).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,
+      shot: fs.existsSync(path.join(SHOTS, `${oid}.png`)) }));  // the page takes the current one's picture if it has none
+    res.writeHead(200, { "content-type": "application/json" }).end(JSON.stringify(out));
+  });
+
+  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;
+    try { sha = await git.expandOid({ ...repo, oid: given }); } catch { return res.writeHead(404).end(); }
+    const shot = path.join(SHOTS, `${sha}.png`);
+    if (what === "shot" && (req.method === "GET" || req.method === "HEAD")) {
+      if (!fs.existsSync(shot)) return res.writeHead(404).end();
+      if (req.method === "HEAD") return res.writeHead(200, { "content-type": "image/png" }).end();
+      return fs.createReadStream(shot).pipe(res.writeHead(200, { "content-type": "image/png" }));
+    }
+    if (what === "shot" && req.method === "PUT") {  // a page's picture of this version
+      if (fs.existsSync(shot))  // another page was first: not an error (a 409 would be logged by the browser)
+        return res.writeHead(200, { "content-type": "application/json" }).end(JSON.stringify({ saved: false }));
+      const chunks: Buffer[] = [];
+      let size = 0;
+      req.on("data", (c: Buffer) => { size += c.length; if (size <= MAX_SHOT) chunks.push(c); });
+      req.on("end", () => {
+        const png = Buffer.concat(chunks);
+        if (size > MAX_SHOT || !png.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]))) return res.writeHead(400).end();
+        fs.mkdirSync(SHOTS, { recursive: true });
+        fs.writeFileSync(shot + ".tmp", png);
+        fs.renameSync(shot + ".tmp", shot);
+        res.writeHead(200, { "content-type": "application/json" }).end(JSON.stringify({ saved: true }));
+      });
+      return;
+    }
+    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.team?.stop();
+    let files: string[];
+    try { files = await queued(async () => {
+      await commit("user", "uncommitted changes before rollback");  // nothing is ever lost
+      await restore(sha);  // that commit's agent/ and built/ (server.ts)
+      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); !["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;
+    }); } catch (e: any) {  // an answer, not a request left hanging
+      return res.writeHead(500, { "content-type": "application/json" }).end(JSON.stringify({ error: String(e?.message ?? e) }));
+    }
+    for (const name of host.agents.keys()) await host.reloadAgent(name);
+    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.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("/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.