@chalky/chalky 0.0.0-stage → 0.1.3

package/app/extensions/swarm/index.ts

@@ -0,0 +1,304 @@
+// Peer-to-peer swarm (port of the Python swarm plugin, on pi's pieces): 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
+//     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;
+//     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).
+// 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 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"));
+
+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");
+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");
+
+function header(item: Item, to?: string) {
+  let h = `[${item.kind} from ${item.sender} · ${new Date(item.ts).toTimeString().slice(0, 8)}]`;
+  if (item.kind === "question") h += " (they are waiting for your answer)";
+  if (item.kind === "reply" && to) h += ` (your final answer goes to ${to})`;
+  return h;
+}
+
+function changed(name?: string, doing?: string) {
+  if (name && doing !== undefined) S.doing[name] = [doing, Date.now() / 1000];
+  host.broadcast("status", { agents: status() });
+}
+
+// png paths -> pi's image content (a file gone since is left out)
+const pictures = (paths: string[] = []) => paths.filter((p) => fs.existsSync(p))
+  .map((p) => ({ type: "image" as const, data: fs.readFileSync(p).toString("base64"), mimeType: "image/png" }));
+
+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));
+  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 {
+    inbox(to).push(item);
+    if (!S.running.has(to)) void work(to);
+  }
+  changed();
+  return item;
+}
+
+// One item -> one turn -> one answer, in order, while the inbox has items
+async function work(name: string) {
+  S.running.add(name);
+  changed(name, "thinking");
+  try {
+    while (inbox(name).length) {
+      const item = inbox(name).shift()!;
+      const to = target(item.chain);
+      S.chain[name] = item.chain;
+      const answer = await host.prompt(name, `${header(item, to)}\n${item.text}`, to, pictures(item.images));
+      delete S.chain[name];
+      if (item.waiter) item.waiter.resolve(answer);  // a question: the asker is waiting
+      else if (to !== "user" && to !== name && answer.trim()) put(to, "reply", name, answer, item.chain.slice(1));
+    }
+  } finally {
+    S.running.delete(name);
+    changed(name, "idle");
+  }
+}
+
+function status() {
+  const out: Record<string, any> = {};
+  for (const a of host.agents.values()) {
+    const [doing, since] = S.doing[a.name] ?? ["idle", Date.now() / 1000];
+    const waiting = [...(S.waiting[a.name] ?? [])].sort();
+    const busy = S.running.has(a.name);
+    out[a.name] = { role: a.role, app: a.app ?? null, state: waiting.length ? `waiting on ${waiting.join(", ")}` : busy ? "working" : "idle",
+                    doing: busy ? doing : "", since, queued: inbox(a.name).length };
+  }
+  return out;
+}
+
+const owed = (name: string) => { const c = S.chain[name]; return c?.[0] && isAgent(c[0]) ? c[0] : null; };
+
+function waitsOn(a: string, b: string) {  // is agent a waiting on agent b, directly or through others?
+  const seen = new Set<string>(), todo = [a];
+  while (todo.length)
+    for (const x of S.waiting[todo.pop()!] ?? []) {
+      if (x === b) return true;
+      if (!seen.has(x)) { seen.add(x); todo.push(x); }
+    }
+  return false;
+}
+
+function ask(asker: string, to: string, text: string, signal?: AbortSignal) {
+  (S.waiting[asker] ??= new Set()).add(to);
+  changed();
+  return new Promise<string>((resolve) => {
+    const done = (answer: string) => {
+      clearTimeout(timer);
+      S.waiting[asker]?.delete(to);
+      changed();
+      resolve(answer);
+    };
+    const item = put(to, "question", asker, text, [asker, ...(S.chain[asker] ?? [])], { resolve: done });
+    const timer = setTimeout(() => {
+      item.waiter = null;  // the answer will come as a reply instead
+      done(`error: no answer from ${to} within ${ASK_TIMEOUT} s. It is still working on it; its answer will come to you `
+        + "as a reply. Continue with something else.");
+    }, ASK_TIMEOUT * 1000);
+    signal?.addEventListener("abort", () => { item.waiter = null; done("error: stopped"); });
+  });
+}
+
+const api = {
+  status,
+  // From the user or the harness (the page's chat, apps, ui 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[]) {
+    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);
+  },
+  // 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]); },
+  // Take back an item that is still waiting in an inbox: true if it was there (its agent never saw it)
+  withdraw(item: Item) {
+    for (const items of Object.values(S.inbox) as Item[][]) {
+      const i = items.indexOf(item);
+      if (i >= 0) { items.splice(i, 1); changed(); return true; }
+    }
+    return false;
+  },
+  // Drop all queued items and stop every running turn; agents stay, idle
+  async stop() {
+    for (const name of Object.keys(S.inbox))
+      for (const item of S.inbox[name].splice(0)) item.waiter?.resolve(`error: ${name} was stopped before replying`);
+    await Promise.all([...host.agents.keys()].map((n: string) => host.abort(n)));
+    for (const k of Object.keys(S.waiting)) delete S.waiting[k];
+    changed();
+    host.broadcast("stopped", { agent: "all" });
+  },
+  // Empty these agents' memories (roles kept): a new pi session each. An error string, or null when done.
+  async reset(names: string[]) {
+    const busy = names.filter((n) => S.running.has(n) || S.waiting[n]?.size || inbox(n).length);
+    if (busy.length) return `error: ${busy.join(", ")} still working or with messages waiting. Reset when they are idle.`;
+    for (const n of names) { const a = host.agents.get(n); await host.createAgent(n, a.role, a.app, true); }
+    return null;
+  },
+};
+host.api.swarm = 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());
+  });
+  pi.on("turn_start", () => changed(me(), "thinking"));
+
+  const checkTo = (agent: string, to: string) => {
+    if (!isAgent(to)) return `error: no agent '${to}'. Agents: ${[...host.agents.keys()].join(", ")}`;
+    if (to === agent) return "error: that is you";
+    if (S.sent >= MAX_MESSAGES) return `error: message budget (${MAX_MESSAGES} asks/tells per user message) used up. Finish with what you have.`;
+    return null;
+  };
+
+  pi.registerTool({
+    name: "spawn_agent", label: "Spawn agent",
+    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 "
+        + "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).`);
+      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);
+      changed(name, "idle");
+      return result(`created agent '${name}'` + (a.app ? `, part of app '${a.app}'` : "") + ". It is idle until someone messages it.");
+    },
+  });
+
+  pi.registerTool({
+    name: "reset_agent", label: "Reset agent",
+    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()) }),
+    async execute(_id, a) {
+      const names = [...host.agents.values()].filter((x: any) => x.name === a.name || (a.app && x.app === a.app)).map((x: any) => x.name);
+      if (!names.length) return result(a.name ? `error: no agent '${a.name}'` : `error: no agents in app '${a.app}'`);
+      if (names.includes(me())) return result("error: you can't reset yourself");
+      const error = await api.reset(names);
+      return result(error ?? `reset ${names.join(", ")}: each starts its next turn with an empty memory and the same role.`);
+    },
+  });
+
+  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.",
+    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 (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.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.`);
+      }
+      put(a.to, "note", 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.",
+    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.`);
+      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.",
+    parameters: Type.Object({}),
+    async execute() {
+      const now = Date.now() / 1000;
+      return result(Object.entries(status()).map(([n, s]: any) => `${n} (${s.role}): ${s.state}`
+        + (s.doing ? `, doing: ${s.doing} for ${Math.round(now - s.since)} s` : "")
+        + (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/ui/README.md

@@ -0,0 +1,69 @@
+# Showing UI to the user (the ui extension)
+Show forms, tables, dashboards or games as UI surfaces: cards in the page's main space, described as JSON.
+Prefer a surface over editing the page ({code}/extensions/page/page.html). Aim for one screen; make it scroll only if the user asks.
+A surface shows only what you build, with no frame: when asked for a thing (a smiley, a chart), show just
+that thing. Add a background, border or Card only if the thing itself needs one. An app's page should keep
+a transparent background, so it sits on the workspace.
+Name what you build (a clear surface id, ids or data-name on elements): the user points at things by name.
+Compose from existing components; write a new component only if none fits.
+Before building or restyling what the user sees, load the ui-design skill (how it should look and read).
+- ui_catalog: lists the components and their props. Read it first.
+- ui_render(surface, components, data): draw or replace a surface. components is a flat list; each has
+  "id", "component" (a catalog name), its props, and "children": [ids] or "child": id. One has id "root".
+  A prop can be {"path": "/x"} to bind it to this surface's data (inputs write to it), or
+  {"ref": "other-surface", "path": "/x"} to read another surface's data live (no copy: it follows changes).
+  Errors come back to you; fix and retry.
+- about="...": one or two sentences on what the surface is for and why it is built this way. The user reads
+  it on the surface's back side; you read it in {code}/ui/surfaces.json. Keep it true when you change things.
+- options=[{"label", "components", "data"}, ...] instead of components: when you are not sure what the user
+  meant, offer 2-3 versions; they flip through them and keep one.
+- Pinned surfaces (the user held their label): your ui_render, ui_update and ui_delete on them fail. Don't
+  work around it: make a new surface (made_from=[the pinned one]) or ask the user.
+- Surfaces stack in the main space and are as wide as their content. place={"x", "y", "width"?, "height"?}
+  (px from the main space's top-left) pins one at a spot instead: use it when the user points at a spot
+  ("here") or draws an area (then fill that area: its x, y, width and height).
+- Everything you show is draggable by default: the user moves a surface by its label (shown on hover), and
+  it stays where they put it (ui_render without place keeps it there; where things are now: the "place" of
+  each surface in {code}/ui/surfaces.json). Pass draggable=false only when the
+  user wants something fixed. In an app you build, make separate pieces draggable too, unless told otherwise.
+- Everything you show is resizable by default too: the user drags its bottom-right corner (shown on hover),
+  and the surface's root component fills the new size. So build things that fill their space (sizes in %,
+  flex, or scaled to their box, e.g. an SVG with a viewBox), not fixed px. Pass resizable=false only when the
+  user wants a fixed size.
+- ui_update(surface, path, value): change data only (fast; components keep their state). ui_delete(surface).
+- Data (what users typed, rows, scores) is kept in {data}/ui-data.json (not versioned); the rest of each
+  surface in {code}/ui/surfaces.json. The user can undo any change (theirs or yours), so don't keep backups.
+- When the user clicks a Button you get "[ui action] <name> ..." with the surface's data.
+- Voice input (dictation, meeting notes): import /ui/voice.js in the app (read its header), never the
+  browser's speech API or a provider directly: it uses the sandbox's speech-to-text API, or the browser's.
+- A new component: {code}/extensions/ui/components/<Name>.js. Start with a comment line "// Name: what it does" (more
+  comment lines if needed), then its about block, then
+  `export default class extends HTMLElement { update(props, ui) {...} }`.
+  The about block of a component (strict JSON after `export const about = `):
+    "version": 1             the shape of its props; raise it when they change, and export
+                             upgrade(props, fromVersion) -> props, so surfaces saved earlier still draw
+    "props": {"name": {"type": "text" | "number" | "boolean" | "choice" | "list" | "rows" | "object" | "action",
+                       "options": [...] (for choice), "default": ..., "doc": "what it is"}}
+    "children": "none" | "one" | "many"
+    "levers": ["Shown as {variant}."]   the back side: plain sentences; each {prop} becomes a control the user
+                             can change there (choice and boolean cycle, text and number are typed)
+    "accepts": "rows with a number column"   optional: what it can take when something is dropped on it
+    "example": {...props}    one sample, for the catalog and for checks
+  When you change a component's props in a way old surfaces would break on, raise "version" and export
+  upgrade(props, fromVersion) returning props in the new shape.
+  update() runs on every change, on the same element: keep internal state there (e.g. a game loop).
+  ui.children: child elements, placed with ui.mount(container); ui.set(prop, value) writes a bound prop;
+  ui.action(name, context) sends an action to you. Make it general so it can be reused. New components work
+  immediately; edited components and App files show when your turn ends (the page refreshes itself). Big multi-file apps: {code}/ui/apps/<name>/, shown with App.
+  Pointing inside a canvas: give the element (or an App page's window) a partAt(x, y) function returning
+  {"name", ...} for what is at that spot, so the user can point at parts (an enemy, a cell).
+- Agents inside what you build (a simulation's members, a debate, characters): load the agent-apps
+  skill first. They are real agents that belong to the app, not workers helping you build it.
+- Libraries: components import them by name (import { marked } from "marked"), as mapped in the import map
+  at the top of {code}/extensions/page/page.html; installed ones are in {code}/extensions/ui/package.json. To add
+  one, download its ES-module build into {code}/extensions/ui/node_modules/<pkg>/ and add a line to the import map.
+- Component pitfalls (you can't see the browser, so avoid them up front):
+  keep your own state in one object, this.state = {...}: fields like this.dir, this.title, this.hidden,
+  this.id, this.style, this.lang are built-in HTMLElement properties and silently break;
+  set a canvas's width/height BEFORE drawing (resizing clears it); don't create things twice in update();
+  remove document-level listeners/timers when the element is no longer connected.

package/app/extensions/ui/agents.js

@@ -0,0 +1,45 @@
+// Bridge from an app ({code}/ui/apps/<name>/, shown by the App component) to the agents. An app imports it:
+//   import agents from "/ui/agents.js";
+//   agents.send(to, text)         a message to an agent, from "app"; its answer comes as a "message" event
+//                                 (role "assistant", no tool_calls). Each one is a model call: limited per minute.
+//   agents.action(name, context)  an action for the agent that owns this app's surface, like a Button
+//   agents.on(type, fn)           events as the page gets them, past ones first (replayed on connect), then live:
+//                                 "message" {agent, role, content, tool_calls, ts}: every message of every agent,
+//                                 incl. its ask_agent / tell calls (who talks to whom); "status" {agents}: who is busy
+//   agents.list()                 {name: {role, app, state, doing, queued}}, from the latest "status" event
+//   agents.reset()                empty the memories of this app's agents (spawned with app=<this surface>),
+//                                 roles kept: a fresh round. Refused (an "error" event) while one is busy.
+//   agents.load()                 this app's saved data ({} at first), from the appdata plugin (on the server)
+//   agents.save(data)             replace it; every page and app frame then gets "app_data" {app, data}, so
+//                                 the same app in other surfaces updates (check ev.app === agents.app)
+//   agents.app                    this app's name: its folder in {code}/ui/apps
+// It opens its own WebSocket to /ws, the page's protocol (the page extension).
+const ws = new WebSocket((location.protocol === "https:" ? "wss://" : "ws://") + location.host + "/ws");
+const open = new Promise((resolve) => ws.addEventListener("open", resolve));
+const listeners = {};
+let status = {};
+
+ws.onmessage = (e) => {
+  const ev = JSON.parse(e.data);
+  if (ev.type === "status") status = ev.agents;
+  for (const fn of listeners[ev.type] || []) fn(ev);
+};
+
+// In the versions plugin's screenshot (/?shot) the app is only looked at: send nothing, no model calls.
+const shot = new URLSearchParams(window.top.location.search).has("shot");
+const post = async (obj) => { if (shot) return; await open; ws.send(JSON.stringify(obj)); };
+const app = location.pathname.split("/")[3];  // /ui/apps/<name>/...
+const store = `/ui-api/app-data/${app}`;
+// the surface this app is shown in (the App component's frame sits inside it on the page)
+const surface = () => window.frameElement?.closest("[data-surface]")?.dataset.surface;
+
+export default {
+  send: (to, text) => post({ type: "app_message", to, text }),
+  action: (name, context = {}) => post({ type: "ui_action", surface: surface(), component: "app", name, context }),
+  on: (type, fn) => (listeners[type] ??= []).push(fn),
+  list: () => status,
+  reset: () => post({ type: "app_reset", surface: surface() }),
+  app,
+  load: async () => (await fetch(store, { cache: "no-store" })).json(),
+  save: async (data) => { if (!shot) await fetch(store, { method: "PUT", body: JSON.stringify(data) }); },
+};