@chalky/chalky 0.1.4 → 0.1.6

package/app/extensions/ui/components/Button.js

@@ -1,28 +0,0 @@
-// Button: a button that sends an action to the agent when clicked.
-export const about = {
-  "version": 1,
-  "props": {
-    "label": {"type": "text", "default": "OK"},
-    "action": {"type": "action", "default": "click", "doc": "the action name you will receive"},
-    "context": {"type": "object", "doc": "sent with the action; values may be {\"path\": ...}"},
-    "variant": {"type": "choice", "options": ["primary", "secondary"], "default": "primary"}
-  },
-  "children": "none",
-  "levers": ["Says {label}.", "Looks {variant}."],
-  "example": {"label": "Send order", "action": "send", "variant": "primary"}
-};
-export default class extends HTMLElement {
-  update(props, ui) {
-    if (!this.button) {
-      this.button = document.createElement("button");
-      this.button.onclick = () => this.ui.action(this.props.action || "click", this.props.context || {});
-      this.append(this.button);
-    }
-    this.props = props;
-    this.ui = ui;
-    this.button.textContent = props.label || "OK";
-    this.button.style.cssText = "border-radius:980px;padding:7px 16px;font-weight:500;" + (props.variant === "secondary"
-      ? "background:var(--glass-strong);color:var(--accent);border:1px solid var(--line)"
-      : "background:var(--accent);color:#fff;border:0");
-  }
-}

package/app/extensions/ui/components/Markdown.js

@@ -1,37 +0,0 @@
-// Markdown: formatted text from a markdown string (headings, lists, tables, code, links, quotes).
-// HTML in the text is sanitised; links open in a new tab. The chat draws message bodies with it too.
-export const about = {
-  "version": 1,
-  "props": {
-    "text": {"type": "text", "doc": "markdown"}
-  },
-  "children": "none",
-  "levers": [],
-  "example": {"text": "**Lunch** closes *Friday 11:00*"}
-};
-import { marked } from "marked";      // bare names: resolved by the import map in chat_ui.html
-import DOMPurify from "dompurify";
-
-const CSS = `
-ui-markdown { display: block; white-space: normal; }
-ui-markdown p, ui-markdown ul, ui-markdown ol, ui-markdown pre, ui-markdown table, ui-markdown blockquote { margin: 6px 0; }
-ui-markdown ul, ui-markdown ol { padding-left: 22px; }
-ui-markdown h1, ui-markdown h2, ui-markdown h3, ui-markdown h4 { font-size: 1.05em; margin: 8px 0 4px; }
-ui-markdown code { font: 12.5px monospace; background: rgba(0, 0, 0, .06); padding: 1px 4px; border-radius: 3px; }
-ui-markdown pre { background: var(--hover); padding: 8px; border-radius: 4px; overflow-x: auto; }
-ui-markdown pre code { background: none; padding: 0; }
-ui-markdown table { border-collapse: collapse; }
-ui-markdown th, ui-markdown td { border: 1px solid var(--line); padding: 3px 8px; }
-ui-markdown blockquote { border-left: 3px solid var(--line); padding-left: 8px; color: var(--soft); }`;
-
-export default class extends HTMLElement {
-  update({ text = "" }) {
-    if (!document.getElementById("ui-markdown-css")) {
-      document.head.insertAdjacentHTML("beforeend", `<style id="ui-markdown-css">${CSS}</style>`);
-    }
-    if (this.state?.text === text) return;  // unchanged: keep the DOM (and any selection)
-    this.state = { text };
-    this.innerHTML = DOMPurify.sanitize(marked.parse(text, { gfm: true, breaks: true }));
-    for (const a of this.querySelectorAll("a")) { a.target = "_blank"; a.rel = "noopener"; }
-  }
-}

package/app/extensions/ui/guide.md

@@ -1,7 +0,0 @@
-# Showing UI to the user
-Show what you build as UI surfaces: cards in the page's main space, described as JSON (ui_catalog, ui_render,
-ui_update, ui_delete), rather than by editing the page. Load the ui-design skill before building or restyling.
-- Name what you build (surface ids, element ids): the user points at things by name.
-- The user moves and resizes surfaces: build things that fill their box (%, flex, a viewBox), not fixed px.
-- A surface the user pinned: don't work around it (make a new one, made_from=[it], or ask).
-Before your first ui_render in a conversation, and before writing a component or an App, read README.md.

package/app/extensions/ui/index.ts

@@ -1,291 +0,0 @@
-// 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/versions/index.ts

@@ -1,168 +0,0 @@
-// 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 =
-//     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
-//                                    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.
-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 MAX_SHOT = 10 * 1024 * 1024;
-const CODE = ["extensions/", "skills/", "ui/", "SYSTEM.md", "mcp.json", "settings.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);
-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
-  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)
-
-async function commit(author: string, message: string) {  // the changed files, or [] if nothing changed
-  const changed = await stage();
-  if (!changed.length) return [];
-  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, files: changed, restart: false });  // pages take its picture
-  return changed;
-}
-
-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) {
-  pi.on("agent_start", (_e, ctx) => { shared.turnFrom[pi.getSessionName()!] = ctx.sessionManager.getEntries().length; });
-  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}`);
-    let message = "";
-    for (const text of [reason ?? "", ...turn.filter((m: any) => m.role === "user").map(textOf), ...turn.filter((m: any) => m.role === "assistant").map(textOf)]) {
-      const line = text.split("\n").map((l: string) => l.trim()).find((l: string) => l && !/^\[\w+ (from|to) /.test(l));
-      if (line) { message = line; break; }
-    }
-    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)));
-      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, settings.json): it is versioned, and a rollback would undo these files. `
-          + `Move project work to ${host.work} and use it from there.`, true);
-    });
-  });
-
-  host.routes.set("/versions", 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,
-      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("/versions/", async (req: any, res: any) => {  // /versions/<sha>/shot, /versions/<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.swarm?.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);
-      // 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; }
-      }
-      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}`); }
-    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.`);
-    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) =>
-    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/extensions/viewer/guide.md

@@ -1,5 +0,0 @@
-# Previews of the user's files
-The user can open a file from their panel in a preview and point at a spot in it: the note's part has
-"viewing": <the file>. Such a note is about that file and that spot, not about the page.
-read_document(path) gives a document's text (docx, pptx, xlsx, pdf, ...). Before you handle a note on a
-preview, read README.md.

package/app/mcp.json

@@ -1,3 +0,0 @@
-{
-  "mcpServers": {}
-}

package/app/settings.json

@@ -1,3 +0,0 @@
-{
-  "compaction": { "keepRecentTokens": 20000 }
-}

package/app/skills/plugin-map/SKILL.md

@@ -1,49 +0,0 @@
----
-name: plugin-map
-description: Find your way around your own code (the pi extensions in your code folder, the page among them) without reading whole files. Use before changing yourself, or before planning work for others that will.
----
-# Getting a map of your own code
-
-Your code folder is the one your prompt names (it holds `extensions/`). Every feature is one extension, and every
-extension is one folder, `extensions/<name>/`, holding all of that feature:
-
-| File          | What it is                                                         |
-|---------------|--------------------------------------------------------------------|
-| `index.ts`    | the extension itself (pi loads it); starts with a header comment    |
-| `guide.md`    | its short prompt section (the part you are reading in your own prompt) |
-| `README.md`   | the whole of what the guide says, read when the guide says          |
-| `browser.js`  | its part of the page (the page extension loads every one it finds)  |
-| `skills/`     | skills only this feature needs (its index.ts gives them to pi)      |
-
-An extension can have other files too (`ui/` has its components, `page/` has `page.html`). The headers are the
-documentation, kept with the code, so read them before the code itself.
-
-## 1. The map: one line per extension
-From your code folder:
-```
-for d in extensions/*/; do printf '%-24s %s\n' "$d" "$(grep -m1 '^//' "$d/index.ts" | sed 's|^// \?||' | cut -c1-140)"; done
-```
-Also there:
-- `extensions/page/`: the page itself (`page.html`), its list of browser parts, and what serves them.
-- `extensions/ui/components/*.js`: UI components, each starting with a comment line on what it is, then its
-  `about` block (props, levers, example; `head -20 <file>`).
-- `skills/<name>/SKILL.md`: skills about you as a whole (this one); a feature's own skills are in its folder.
-- `ui/`: what you built, not code: `surfaces.json` (the surfaces' design) and `apps/<name>/`.
-- The host, `server.ts` one folder up: sessions, the web server, `globalThis.chalky`. Read its header; don't edit it.
-
-## 2. The headers of the extensions involved
-```
-awk '/^import /{exit} 1' extensions/swarm/index.ts     # everything above the imports
-```
-Read only the headers of the extensions your work touches. All of them at once is over 13,000 characters.
-
-## 3. Then only the code you will change
-Use `grep -n` to find the function, then `sed -n 'START,ENDp'` for that part. A whole file can be long
-(swarm's index.ts is over 16,000 characters). If you are planning work for other agents, the headers are usually
-enough: let each agent read the code it owns.
-
-## Keep the headers true
-When you change what an extension provides (a tool, a route, a page message, an event, a host service), update
-its header in the same change. Other agents, and you after a reload, rely on it. A new extension is a new folder
-with an `index.ts` whose header starts with a one-line summary: that line is its entry in the map. After editing,
-call the reload tool.