@chalky/chalky 0.0.0-stage → 0.1.3

package/app/extensions/ui_history/index.ts

@@ -0,0 +1,109 @@
+// Every state of the UI surfaces, kept: undo, redo and rewind for the user (port of the Python ui_history plugin; the
+// browser half, browser.js, is its ui_history.js). After each change (ui.ts's change() with words for it, from the user or
+// an agent) it saves a step: a full copy of all surfaces, design and data. Steps form a tree: each has a parent, so
+// undoing and then doing something new starts a branch and loses nothing; redo follows the newest branch.
+//   Page messages:  ui_undo, ui_redo, ui_goto {step}
+//   Server -> page: {"type": "ui_history", "event": "moved", "at", "what"}  after undo/redo/goto
+//                   {"type": "ui_history", "event": "branched", "tip"}       a change made after undoing
+//   GET /ui-api/history: {"at", "line": [{"n", "ts", "by", "what"}]}, the current line (root to newest tip)
+// Kept in state/ui-history.jsonl (one step per line), for HISTORY_KEEP_DAYS (default 7). Older steps are dropped at
+// start and every PRUNE_EVERY steps; the current step is always kept.
+// Undo puts back the surfaces only: code (components, apps) has its own history (the versions extension).
+// pi has no undo for this: /tree and /fork rewind one agent's conversation, not the shared page.
+// It watches the ui extension's changes (host.api.ui.watch); others reach it as host.api.uiHistory. Not pi.events:
+// each agent has its own bus, and a reload keeps the old listeners on it, so every change would be recorded again.
+import fs from "node:fs";
+import path from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+const host = (globalThis as any).chalky;
+const FILE = path.join(host.state, "ui-history.jsonl");
+const KEEP_DAYS = Number(process.env.HISTORY_KEEP_DAYS ?? 7);
+const PRUNE_EVERY = 200;
+
+// JSON with every object's keys in order: the same content compares the same (a record loaded from the files has
+// "data" last, one just drawn has it in the middle)
+const sorted = (v: any) => JSON.stringify(v, (_k, x) => x && typeof x === "object" && !Array.isArray(x) ? Object.fromEntries(Object.entries(x).sort()) : x);
+
+type Step = { n: number, parent: number | null, ts: number, by: string, what: string, surfaces: Record<string, any> };
+
+class History {
+  steps = new Map<number, Step>();
+  at: number | null = null;  // the step the surfaces are at now
+  constructor(public ui: any) {
+    if (fs.existsSync(FILE))
+      for (const line of fs.readFileSync(FILE, "utf8").split("\n").filter(Boolean)) {
+        const entry = JSON.parse(line);
+        if ("at" in entry) this.at = entry.at;  // a marker line: where undo/redo left us
+        else { this.steps.set(entry.n, entry); this.at = entry.n; }  // a new step is where we are (the Python version
+      }                                                                // missed this: after a goto, a restart went back there)
+    if (this.at === null || !this.steps.has(this.at)) this.at = this.steps.size ? Math.max(...this.steps.keys()) : null;
+    this.prune();
+    if (this.at === null || sorted(this.steps.get(this.at)!.surfaces) !== sorted(ui.surfaces))
+      this.add("start", "the surfaces as loaded");  // first start, or the files changed while we were away
+  }
+  write(entry: object) { fs.appendFileSync(FILE, JSON.stringify(entry) + "\n"); }
+  add(by: string, what: string) {  // a new step after the current one; tells the pages if it left a branch behind
+    const left = this.children(this.at).length ? this.tip(this.at!) : null;
+    const n = this.steps.size ? Math.max(...this.steps.keys()) + 1 : 0;
+    const step = { n, parent: this.at, ts: Date.now() / 1000, by, what, surfaces: this.ui.snapshot() };
+    this.steps.set(n, step);
+    this.at = n;
+    this.write(step);
+    if (n % PRUNE_EVERY === 0) this.prune();
+    if (left !== null) host.broadcast("ui_history", { event: "branched", tip: left });
+  }
+  children(n: number | null) { return [...this.steps.values()].filter((s) => s.parent === n).map((s) => s.n).sort((a, b) => a - b); }
+  tip(n: number) {  // follow the newest child down to the end of the line
+    for (let kids = this.children(n); kids.length; kids = this.children(n)) n = kids.at(-1)!;
+    return n;
+  }
+  line() {  // the steps from the oldest kept one to the tip of the current branch
+    const back = [];
+    for (let n = this.at; n !== null && this.steps.has(n); n = this.steps.get(n)!.parent) back.push(n);
+    const ahead = [];
+    for (let n = this.at, kids = this.children(n); kids.length; kids = this.children(n)) { n = kids.at(-1)!; ahead.push(n); }
+    return [...back.reverse(), ...ahead];
+  }
+  goto(n: number) {
+    if (!this.steps.has(n) || n === this.at) return;
+    this.at = n;
+    this.write({ at: n });
+    this.ui.restore(this.steps.get(n)!.surfaces);
+    host.broadcast("ui_history", { event: "moved", at: n, what: this.steps.get(n)!.what });
+  }
+  prune() {  // drop steps older than KEEP_DAYS (never the current one), then rewrite the file
+    const cutoff = Date.now() / 1000 - KEEP_DAYS * 86400;
+    for (const [n, s] of this.steps) if (s.ts < cutoff && n !== this.at) this.steps.delete(n);
+    for (const s of this.steps.values()) if (s.parent !== null && !this.steps.has(s.parent)) s.parent = null;
+    const lines = [...this.steps.values()].sort((a, b) => a.n - b.n).map((s) => JSON.stringify(s));
+    if (this.at !== null) lines.push(JSON.stringify({ at: this.at }));
+    fs.writeFileSync(FILE + ".tmp", lines.map((l) => l + "\n").join(""));
+    fs.renameSync(FILE + ".tmp", FILE);
+  }
+}
+
+export default function (pi: ExtensionAPI) {
+  // made once all of an agent's extensions are loaded (pi loads them in folder order, not by name, so ui and its
+  // surfaces may come after this file); the first agent's session_start makes it, at startup, before any change
+  pi.on("session_start", () => {
+    if (!host.shared.has("ui-history")) host.shared.set("ui-history", new History(host.shared.get("ui")));
+    host.api.uiHistory = host.shared.get("ui-history");
+    host.api.ui?.watch("ui_history", (_sid: string, by?: string, what?: string) => { if (what) host.api.uiHistory.add(by, what); });
+  });
+  const shared = (): History | undefined => host.shared.get("ui-history");
+
+  host.pageHandlers.set("ui_history", (msg: any) => {
+    const history = shared();
+    if (!history) return;
+    const now = history.at === null ? undefined : history.steps.get(history.at);
+    if (msg.type === "ui_undo" && now && now.parent !== null) history.goto(now.parent);
+    else if (msg.type === "ui_redo") { const kids = history.children(history.at); if (kids.length) history.goto(kids.at(-1)!); }
+    else if (msg.type === "ui_goto") history.goto(msg.step);
+  });
+  host.routes.set("/ui-api/history", (_req: any, res: any) => {
+    const history = shared();
+    res.writeHead(200, { "content-type": "application/json" }).end(JSON.stringify({ at: history?.at ?? null,
+      line: (history?.line() ?? []).map((n) => { const { surfaces, parent, ...s } = history!.steps.get(n)!; return s; }) }));
+  });
+}

package/app/extensions/versions/browser.js

@@ -0,0 +1,58 @@
+// 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).
+// 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 });
+  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;
+  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 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 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` } }));
+  const canvas = Object.assign(document.createElement("canvas"), { width: Math.ceil(x1 - x0), height: Math.ceil(y1 - y0) });
+  const g = canvas.getContext("2d");
+  g.drawImage(page, -x0, -y0);
+  for (const frame of top.querySelectorAll("iframe")) {  // apps: their own pages, drawn and pasted where they are
+    let doc;
+    try { doc = frame.contentDocument; } catch { continue; }  // another site's frame: stays blank
+    if (!doc?.documentElement) continue;
+    const b = box(frame);
+    if (!b.w || !b.h) continue;
+    try {
+      const app = await image(await domtoimage.toPng(doc.documentElement, { width: b.w, height: b.h, bgcolor: "#fff" }));
+      g.drawImage(app, b.x - x0, b.y - y0, b.w, b.h);
+    } catch {}  // this app can't be drawn: the rest of the picture still is
+  }
+  return new Promise((ok) => canvas.toBlob(ok, "image/png"));
+}
+
+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 });
+  }).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
+  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
+  } catch {}
+}

package/app/extensions/versions/index.ts

@@ -0,0 +1,168 @@
+// 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"];
+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): 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/README.md

@@ -0,0 +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":
+"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
+  what the user sees. For pictures use read.