chamba 0.7.0 → 0.8.0

package/templates/webterm/server.js

@@ -18,6 +18,7 @@ import { join, resolve, sep } from "node:path";
 import express from "express";
 import { WebSocketServer } from "ws";
 import { cleanLine, cleanSubmission, createPaneStore, isPageId } from "./artifacts.js";
+import { readColor, storeColor } from "./color.js";
 import {
     AGENT_ARGS,
     AGENT_STORES,
@@ -25,6 +26,7 @@ import {
     agentSpawnArgv,
     CHECK_INTERVAL_MS,
     CLIENT_PING_INTERVAL_MS,
+    COLOR_FILE,
     DEFAULT_AGENT,
     DIR_SCAN_DEPTH,
     DIR_SCAN_MAX,
@@ -46,9 +48,6 @@ import {
     MAX_PANE_BYTES,
     MAX_PANE_FILES,
     MAX_SESSIONS,
-    MAX_SPECS_BYTES,
-    MAX_SPECS_LINE_LENGTH,
-    MAX_SPECS_LINES_PER_SESSION,
     MAX_UPLOAD_BYTES,
     PANE_APPS_CLIENT_DIR,
     PANE_DIR,
@@ -58,11 +57,6 @@ import {
     PORT,
     RESUME_STAMP,
     resolveWorkspacePath,
-    SPECS_KEY,
-    SPECS_LINE_MIN_INTERVAL_MS,
-    SPECS_NEW_SESSION_DELAY_MS,
-    SPECS_RAW_TOKEN,
-    SPECS_ROOT,
     STATE_FILE,
     STATUS_SCAN_MS,
     STOP_ANNOUNCE_MS,
@@ -81,9 +75,9 @@ import { isSelfOrDescendant, processStart } from "./proc.js";
 import { resumeArgvFor } from "./resume.js";
 import { createRegistry, WORK_TICK_MS } from "./sessions.js";
 import { statusFor, writesSnapshots } from "./snapshot.js";
-import { CLIENT_PREFIX, createSpecsModule, mountSpecs, SPECS_AGENT_PATH, SPECS_KEYS_PATH, SPECS_PREFIX } from "./specs.js";
 import { documentPolicy, toolDocumentFor, withNonce } from "./tool-document.js";
-import { framedLine, reduceLine } from "./typed-line.js";
+import { CLIENT_PREFIX, commandFor, commandsOf, mountTool, TOOLS, toolPaths } from "./tools/index.js";
+import { commandLine, framedLine, reduceLine } from "./typed-line.js";
 
 // node-pty is a native CommonJS addon; load it through createRequire under ESM.
 const require = createRequire(import.meta.url);
@@ -173,6 +167,10 @@ function sessionAgent(raw) {
     return isKnownAgent(raw) ? raw : null;
 }
 
+// The accent colour this workspace is wearing, read once at start and moved by the "color" frame. "" means
+// nothing was picked, and the browser works one out from the published port.
+let chosenColor = readColor(COLOR_FILE);
+
 // The one-line file that names the default agent, for the `webterm` launcher to read back. Written when the
 // port is bound and again whenever the default moves, so a second `webterm <agent>` can say what is live.
 function publishAgent() {
@@ -361,7 +359,7 @@ app.use("/vendor/xterm-fit", express.static(join(import.meta.dirname, "node_modu
 // The pane's tool clients, built elsewhere and baked beside this directory. Open like the statics above, and
 // CORS-readable on top of it: a tool renders in a frame with an opaque origin, so it fetches its own module
 // scripts cross-origin and a browser will not run them without being told they may be read. Nothing here is
-// secret and nothing here drives anything - the data behind a tool is gated separately, in specs.js.
+// secret and nothing here drives anything - the data behind a tool is gated separately, in tools/mount.js.
 //
 // `frame-ancestors` is the one thing that is not open. A tool's document is only ever framed by this
 // interface, and framed by it inside a sandbox; a page somewhere else could otherwise frame the same document
@@ -500,6 +498,9 @@ function broadcastSessions() {
             agent: defaultAgent,
             agents: AGENTS,
             workspace: WORKSPACE,
+            // The accent colour, on the one frame that already reaches every window: a change has to travel
+            // to all of them either way, so this closes the door rather than adding a second one.
+            color: chosenColor,
             max: MAX_SESSIONS,
             defaultCwd: workspaceLabel(defaultCwd),
             list,
@@ -619,23 +620,33 @@ function sessionForPid(pid) {
     return null;
 }
 
-// --- The Specs tool ----------------------------------------------------------------------------------------------------------------------
+// --- The pane's tools --------------------------------------------------------------------------------------------------------------------
 //
-// The first of the pane's tools, mounted the way the pane store is: something built elsewhere is handed what
-// only this process can give it - where to look, and who to tell when the disk moves - and its answers are
-// registered behind gates it does not hold itself. It is not a process and not a port: a failure inside it is
-// one request answered with a status, and every terminal in this container carries on.
-
-const specs = mountSpecs({
-    module: createSpecsModule({ root: SPECS_ROOT, onChange: (change) => broadcastSpecs(change) }),
-    key: SPECS_KEY,
-    rawToken: SPECS_RAW_TOKEN,
-});
+// Each one is mounted the way the pane store is: something built elsewhere is handed what only this process
+// can give it - where to look, and who to tell when the disk moves - and its answers are registered behind
+// gates it does not hold itself. None of them is a process or a port: a failure inside one is one request
+// answered with a status, and every terminal in this container carries on.
+//
+// Nothing below names a tool. The list in `tools/index.js` is what is mounted, routed, broadcast and typed
+// from, so a third tool is a row there and a table beside it rather than an edit in this file.
+
+const mounted = new Map();
+for (const table of TOOLS) {
+    mounted.set(
+        table.id,
+        mountTool({
+            table,
+            module: table.create({ onChange: (change) => broadcastTool(table.id, change) }),
+            key: table.key,
+            rawToken: table.rawToken,
+        }),
+    );
+}
 
-// A spec directory moved. Every window hears it, not one: a spec belongs to the repository rather than to a
-// session, and two windows reading the same spec both need to know.
-function broadcastSpecs(change) {
-    for (const client of clients) send(client, { t: "specs", change });
+// A piece of work moved on disk. Every window hears it, not one: what a tool serves belongs to the repository
+// rather than to a session, and two windows reading the same spec or the same review both need to know.
+function broadcastTool(id, change) {
+    for (const client of clients) send(client, { t: id, change });
 }
 
 // --- The status strip --------------------------------------------------------------------------------------------------------------------
@@ -895,121 +906,130 @@ function nudge(session, title, path) {
     pasteToSession(session, `[web pane] Feedback submitted on "${quoted}" - read ${homeLabel(path)}`);
 }
 
-// --- Specs routes ------------------------------------------------------------------------------------------------------------------------
-
-/**
- * The scoped credentials, for the shell alone. It holds the master key already, so nothing new is exposed by
- * telling it these; what matters is where they go next - the shell posts the key into the tool's frame once,
- * and the frame presents it as a header. Behind the pane's gate, which is the master key in a header and
- * never in a URL, because a URL that carries it is a URL a document can read itself out of.
- */
-app.get(SPECS_KEYS_PATH, requirePaneKey, (_req, res) => {
-    res.json({ key: SPECS_KEY, raw: specs.rawBase });
-});
-
-/**
- * The `specs` helper's door: the agent's half of the coordination channel.
- *
- * The gate is the master key, which every helper route takes and which nothing outside the container has.
- * The session behind it is a claim rather than a second gate: the helper sends its own pid, this walks up
- * the process tree to see whether it lands in a session this server started, and any process in the
- * container could send another process's pid instead - the same rule `webpane` publishes under, and its
- * docstring says the same of itself. What that buys is a helper run outside a web session getting a clear
- * answer rather than a silent one, and it is not asked to buy more: the session is used for nothing else,
- * because a verb moves files in a spec directory, which belongs to the repository rather than to a terminal.
- */
-app.post(SPECS_AGENT_PATH, requirePaneKey, express.json({ limit: MAX_SPECS_BYTES }), (req, res) => {
-    const session = sessionForPid(Number(req.headers["x-specs-pid"]));
-    if (!session) {
-        res.status(409).json({ error: "not running inside a web session - there is no pane to tell" });
-        return;
-    }
-    const body = req.body && typeof req.body === "object" ? req.body : {};
-    const answer = specs.agent({ verb: body.verb, entry: body.spec, payload: body.payload });
-    res.status(answer.status).json(answer.body);
-});
-
-// The body of a Specs request, read only for a request the mount says may carry one. Reading it is itself
-// something a caller gets to make this process do - hold the bytes, decode them - so it sits behind the same
-// key as the route, rather than in front of it where every other body route in this file would not put it.
-const specsBody = express.text({ type: () => true, limit: MAX_SPECS_BYTES });
+// --- The tools' routes -------------------------------------------------------------------------------------------------------------------
+//
+// Three routes for each tool, registered from its own row: the credentials the shell hands into the frame,
+// the helper's door, and everything the tool itself answers. Every rule about who may ask is in the mount, so
+// what is here is one delegation per kind and no decision.
+
+for (const table of TOOLS) {
+    const tool = mounted.get(table.id);
+    const paths = toolPaths(table.id);
+
+    /**
+     * The scoped credentials, for the shell alone. It holds the master key already, so nothing new is exposed
+     * by telling it these; what matters is where they go next - the shell posts the key into the tool's frame
+     * once, and the frame presents it as a header. Behind the pane's gate, which is the master key in a header
+     * and never in a URL, because a URL that carries it is a URL a document can read itself out of.
+     */
+    app.get(paths.keys, requirePaneKey, (_req, res) => {
+        res.json({ key: table.key, raw: tool.rawBase });
+    });
 
-/**
- * Everything else the tool answers. One delegation and no decision: specs.js takes the request as plain data
- * and gives back the status, the headers and the body, and it never throws, so a Specs failure is a view that
- * says so rather than a process that went down.
- */
-app.all(
-    `${SPECS_PREFIX}/*`,
-    (req, res, next) => {
-        if (specs.takesBody(req.method, req.path, req.headers)) specsBody(req, res, next);
-        else next();
-    },
-    (req, res) => {
-        const answer = specs.handle({
-            method: req.method,
-            path: req.path,
-            query: req.query,
-            headers: req.headers,
-            body: req.body,
-        });
-        res.status(answer.status).set(answer.headers);
-        if (answer.body === null) {
-            res.end();
+    /**
+     * The tool helper's door: the agent's half of the coordination channel.
+     *
+     * The gate is the master key, which every helper route takes and which nothing outside the container has.
+     * The session behind it is a claim rather than a second gate: the helper sends its own pid, this walks up
+     * the process tree to see whether it lands in a session this server started, and any process in the
+     * container could send another process's pid instead - the same rule `webpane` publishes under, and its
+     * docstring says the same of itself. What that buys is a helper run outside a web session getting a clear
+     * answer rather than a silent one, and it is not asked to buy more: the session is used for nothing else,
+     * because a verb moves files in a directory of the repository rather than of a terminal.
+     */
+    app.post(paths.agent, requirePaneKey, express.json({ limit: table.limits.bytes }), async (req, res) => {
+        const session = sessionForPid(Number(req.headers[paths.pidHeader]));
+        if (!session) {
+            res.status(409).json({ error: "not running inside a web session - there is no pane to tell" });
             return;
         }
-        // A workspace file goes out as its own bytes, under the type the tool decided; the rest is JSON.
-        if (Buffer.isBuffer(answer.body)) res.send(answer.body);
-        else res.json(answer.body);
-    },
-);
+        const body = req.body && typeof req.body === "object" ? req.body : {};
+        const answer = await tool.agent({ verb: body.verb, entry: body.entry, payload: body.payload });
+        res.status(answer.status).json(answer.body);
+    });
+
+    // The body of a tool's request, read only for a request the mount says may carry one. Reading it is
+    // itself something a caller gets to make this process do - hold the bytes, decode them - so it sits
+    // behind the same key as the route, rather than in front of it where every other body route in this file
+    // would not put it.
+    const body = express.text({ type: () => true, limit: table.limits.bytes });
+
+    /**
+     * Everything else the tool answers. One delegation and no decision: the mount takes the request as plain
+     * data and answers with the status, the headers and the body, and it neither throws nor rejects, so a
+     * tool's failure is a view that says so rather than a process that went down. Awaited because a module
+     * may compute its answer - a review asks git for one - and the mount settles that before it answers.
+     */
+    app.all(
+        `${paths.prefix}/*`,
+        (req, res, next) => {
+            if (tool.takesBody(req.method, req.path, req.headers)) body(req, res, next);
+            else next();
+        },
+        async (req, res) => {
+            const answer = await tool.handle({
+                method: req.method,
+                path: req.path,
+                query: req.query,
+                headers: req.headers,
+                body: req.body,
+            });
+            res.status(answer.status).set(answer.headers);
+            if (answer.body === null) {
+                res.end();
+                return;
+            }
+            // A workspace file goes out as its own bytes, under the type the tool decided; the rest is JSON.
+            if (Buffer.isBuffer(answer.body)) res.send(answer.body);
+            else res.json(answer.body);
+        },
+    );
+}
 
-// --- The Specs delivery ------------------------------------------------------------------------------------------------------------------
+// --- The tools' deliveries ---------------------------------------------------------------------------------------------------------------
 //
-// Everything the pane sends the agent lands as a file plus one typed line. The file is written through the
-// data routes above, by the tool; this is the line. It rides the window's own socket, so the session it
-// reaches is the session that window is driving - the tool never names one, and there is no id on the frame
-// for it to name.
+// Everything a tool sends the agent lands as a file plus one typed line. The file is written through the data
+// routes above, by the tool; this is the line. It rides the window's own socket, so the session it reaches is
+// the session that window is driving - a tool never names one, and there is no id on the frame for it to
+// name.
 //
-// The words of the line are this server's. The event is a key into the table below, so a tool picks which of
-// a few sentences is typed and never what it says; the detail is the one part that came from somewhere else
-// and is reduced before it goes anywhere near a terminal; and the path has to be a file the tool itself
-// wrote, which the mount decides.
-
-// What a delivery may say it is. A key that is not here is not a delivery.
-const SPECS_EVENTS = {
-    annotations: "Annotations sent",
-    intake: "A new spec was filed",
-    answers: "A round of answers was submitted",
-    gate: "A gate was answered",
-    brief: "Pick up this spec",
-};
-
-// The gap and the total, per session, for as long as this container runs. Held here rather than in the
-// registry because they are about this one channel: a session that is closed and gone takes its count with
-// it, which is the same span the resume marker uses.
-const lastSpecsLine = new Map();
-const specsLineCount = new Map();
-
-/** Whether this session has had as much of this channel as it may have, and why. */
-function specsLimited(sid) {
+// The words of the line are this server's. The event is a key into the tool's own tables, so a tool picks
+// which of a few sentences - or which of its commands - is typed, and never what it says; the detail is the
+// one part that came from somewhere else and is reduced before it goes anywhere near a terminal; and the path
+// has to be a file the tool itself wrote, which the mount decides.
+//
+// What a tool may say is in its table: `events` for the sentences and `commands.js` for the commands. A
+// sentence carries information to an agent already inside the flow, and anything that starts a flow is a
+// command, so no framed sentence ever reaches an agent that is not allowed to act on it.
+
+// The gap and the total, per tool and per session, for as long as this container runs. Held here rather than
+// in the registry because they are about this one channel: a session that is closed and gone takes its count
+// with it, which is the same span the resume marker uses. Counted per tool, so one tool in a loop cannot
+// spend another's share of a session.
+const lastToolLine = new Map();
+const toolLineCount = new Map();
+
+/** Whether this session has had as much of one tool's channel as it may have, and why. */
+function toolLimited(table, sid) {
     const now = Date.now();
-    if (now - (lastSpecsLine.get(sid) ?? 0) < SPECS_LINE_MIN_INTERVAL_MS) {
+    const at = `${table.id}\n${sid}`;
+    if (now - (lastToolLine.get(at) ?? 0) < table.limits.interval) {
         return "that was just delivered - give it a moment";
     }
-    if ((specsLineCount.get(sid) ?? 0) >= MAX_SPECS_LINES_PER_SESSION) {
-        return `this session has had the ${MAX_SPECS_LINES_PER_SESSION} deliveries it may have`;
+    if ((toolLineCount.get(at) ?? 0) >= table.limits.perSession) {
+        return `this session has had the ${table.limits.perSession} deliveries it may have`;
     }
     return null;
 }
 
-function specsDelivered(sid) {
-    lastSpecsLine.set(sid, Date.now());
-    specsLineCount.set(sid, (specsLineCount.get(sid) ?? 0) + 1);
+function toolDelivered(table, sid) {
+    const at = `${table.id}\n${sid}`;
+    lastToolLine.set(at, Date.now());
+    toolLineCount.set(at, (toolLineCount.get(at) ?? 0) + 1);
 }
 
 /**
- * Type one Specs line into a session, or say why not.
+ * Type one line from one tool into a session, or say why not.
  *
  * The length is checked before the reduction, so an over-limit detail is refused with a reason rather than
  * cut into half a sentence - which is the one thing a silent trim would make unreadable.
@@ -1017,25 +1037,36 @@ function specsDelivered(sid) {
  * `after` is for a session this delivery has just started: the line waits for the agent to be there to read
  * it, and the delivery is answered now, because the session did start and the line will follow.
  */
-function typeSpecsLine(session, msg, after = 0) {
-    const event = SPECS_EVENTS[typeof msg.event === "string" ? msg.event : ""];
-    if (!event) return { ok: false, error: "that is not something the Specs tool delivers" };
+function typeToolLine(table, session, msg, after = 0) {
+    const tool = mounted.get(table.id);
+    const key = typeof msg.event === "string" ? msg.event : "";
+    // Read as the table's own entries and never as whatever an object inherits: the key came from the client,
+    // so a name like `constructor` would otherwise index a function and pass for a delivery.
+    const event = Object.hasOwn(table.events, key) ? table.events[key] : null;
+    const commanded = Object.hasOwn(commandsOf(table.id), key);
+    if (!event && !commanded) return { ok: false, error: `that is not something the ${table.label} tool delivers` };
+    // An agent with no spelling for this command gets no delivery. Both other ways out break the typed-line
+    // boundary: one agent's command word typed into another's session is a sentence that names a command, and
+    // a framed sentence may never start a flow.
+    const command = commanded ? commandFor(table.id, key, session.agent) : null;
+    if (commanded && !command) {
+        return { ok: false, error: `this button has no spelling for a ${session.agent} session` };
+    }
     const detail = typeof msg.detail === "string" ? msg.detail : "";
-    if (detail.length > MAX_SPECS_LINE_LENGTH) {
-        return { ok: false, error: `that message is longer than the ${MAX_SPECS_LINE_LENGTH} characters a delivery may carry` };
+    if (detail.length > table.limits.line) {
+        return { ok: false, error: `that message is longer than the ${table.limits.line} characters a delivery may carry` };
     }
-    const limited = specsLimited(session.id);
+    const limited = toolLimited(table, session.id);
     if (limited) return { ok: false, error: limited };
     // A path is optional - a briefing names no file - and one that is not a file this tool wrote is dropped
     // rather than refused: the line still reads, and it names nothing that is not there.
-    const absolute = msg.path ? specs.fileFor(msg.path) : null;
-    const line = framedLine({
-        tag: "specs",
-        event,
-        detail: reduceLine(detail, MAX_SPECS_LINE_LENGTH),
-        path: absolute === null ? "" : homeLabel(absolute),
-    });
-    specsDelivered(session.id);
+    const absolute = msg.path ? tool.fileFor(msg.path) : null;
+    const said = reduceLine(detail, table.limits.line, session.agent);
+    // A command names no file: it opens on the work itself, and the skill it starts reads what it needs.
+    const line = command
+        ? commandLine(command, said)
+        : framedLine({ tag: table.id, event, detail: said, path: absolute === null ? "" : homeLabel(absolute), agent: session.agent });
+    toolDelivered(table, session.id);
     if (after > 0) {
         // Only if that session is still there when the wait is over.
         setTimeout(() => {
@@ -1045,33 +1076,34 @@ function typeSpecsLine(session, msg, after = 0) {
     } else {
         pasteToSession(session, line);
     }
-    console.log(`[webterm] specs: delivered to session "${session.name || session.label}"`);
+    console.log(`[webterm] ${table.id}: delivered to session "${session.name || session.label}"`);
     return { ok: true };
 }
 
 /**
- * A delivery from the Specs tool, arriving over the shell's own socket.
+ * A delivery from a tool, arriving over the shell's own socket.
  *
  * With no session on this window there is nobody to tell, and the tool has already asked the user whether to
  * start one: `create` is that answer, and the briefing becomes the first line the new agent reads.
  */
-function deliverSpecs(ws, msg) {
+function deliverTool(table, ws, msg) {
+    const answered = `${table.id}:delivered`;
     const session = registry.sessionFor(ws);
     if (session) {
-        send(ws, { t: "specs:delivered", ...typeSpecsLine(session, msg) });
+        send(ws, { t: answered, ...typeToolLine(table, session, msg) });
         return;
     }
     if (msg.create !== true) {
-        send(ws, { t: "specs:delivered", ok: false, error: "no-session" });
+        send(ws, { t: answered, ok: false, error: "no-session" });
         return;
     }
     newSession(ws);
     const started = registry.sessionFor(ws);
     if (!started) {
-        send(ws, { t: "specs:delivered", ok: false, error: "a session could not be started" });
+        send(ws, { t: answered, ok: false, error: "a session could not be started" });
         return;
     }
-    send(ws, { t: "specs:delivered", ...typeSpecsLine(started, msg, SPECS_NEW_SESSION_DELAY_MS) });
+    send(ws, { t: answered, ...typeToolLine(table, started, msg, table.limits.newSession) });
 }
 
 // --- Resume, once per container start ----------------------------------------------------------------------------------------------------
@@ -1327,6 +1359,19 @@ function handleFrame(ws, msg) {
             if (attached) sendStatus(attached, { force: true });
             return;
         }
+        case "color": {
+            // The palette lives in the browser, so the id is opaque here and only its size and shape are
+            // checked. A refused frame writes nothing and broadcasts nothing, and the window that sent it is
+            // put right by the next sessions frame it receives.
+            const applied = storeColor(COLOR_FILE, msg.color);
+            if (applied === null) {
+                console.warn("[webterm] refused a colour id");
+                return;
+            }
+            chosenColor = applied;
+            broadcastSessions();
+            return;
+        }
         case "seen":
             // The user did something in this window - a click, a scroll, a key. It changes nothing about who
             // drives what, only whether the next ending of the session it is driving is worth a sound. Typing
@@ -1378,11 +1423,14 @@ function handleFrame(ws, msg) {
         case "paste":
             if (typeof msg.data === "string") paste(ws, msg.data);
             return;
-        case "specs:deliver":
-            // The pane's tool telling the agent something arrived. Like the pane's own frames, it reaches
-            // the session this window is driving, and the frame carries no id for it to reach another.
-            deliverSpecs(ws, msg);
+        case "tool:deliver": {
+            // A tool in the pane telling the agent something arrived. Like the pane's own frames, it reaches
+            // the session this window is driving, and the frame carries no id for it to reach another. The
+            // tool it came from is a name on the frame, and a name that is not a tool's is not a delivery.
+            const table = TOOLS.find((one) => one.id === msg.tool);
+            if (table) deliverTool(table, ws, msg);
             return;
+        }
         case "resize":
             resize(ws, msg.cols, msg.rows);
             return;

package/templates/webterm/tools/commands.js

@@ -0,0 +1,61 @@
+// =========================================================================================================================================
+// tools/commands.js - The commands a tool's button types, spelled for each agent.
+//
+// A button on a tab that starts a skill types the command the user would type, because a skill only the user may start may never
+// start from a framed sentence. Each agent spells that command its own way, so one row here is one event, and one cell is what that
+// event types into a session of that agent.
+//
+// The table is read from two sides. The web interface's server reads it to type the line, and chamba's host-side injector reads it
+// to write opencode's command files - the files that make opencode's spelling resolve at all. One table, so the word a button types
+// and the word the container answers to cannot come to differ.
+//
+// Nothing here imports anything. The injector runs on the host, where the interface's own config does not belong.
+// =========================================================================================================================================
+
+// claude resolves `/name` from a skill's own frontmatter. codex takes `$name`, with the argument on the same line. opencode
+// resolves `/name` from a command file, which is why the injector ships one per word below.
+//
+// One block per tool, and the event names are that tool's own: a delivery names its tool and its event, and the two together are
+// what picks a row.
+export const TOOL_COMMANDS = {
+    specs: {
+        brief: { claude: "/dx-spec", codex: "$dx-spec", opencode: "/dx-spec" },
+        execute: { claude: "/dx-spec-execute", codex: "$dx-spec-execute", opencode: "/dx-spec-execute" },
+    },
+    // One word for every act that starts the agent on a review - filing one, sending feedback, syncing, and asking it to carry on.
+    // The skill reads the review's state to know which of them it was woken for, so the line never says.
+    reviews: {
+        review: { claude: "/dx-review", codex: "$dx-review", opencode: "/dx-review" },
+    },
+};
+
+// The skill each command word starts. opencode's command file is a prompt rather than a skill, so it has to name the skill it
+// means, and this is where that name comes from.
+export const TOOL_COMMAND_SKILLS = {
+    specs: {
+        brief: "dx-spec",
+        execute: "dx-spec-execute",
+    },
+    reviews: {
+        review: "dx-review",
+    },
+};
+
+/** The rows one tool types from, or an empty table for a name that is not a tool. */
+export function commandsOf(tool) {
+    return Object.hasOwn(TOOL_COMMANDS, tool) ? TOOL_COMMANDS[tool] : {};
+}
+
+/** The skill one tool's word starts, or null. */
+export function commandSkill(tool, event) {
+    const rows = Object.hasOwn(TOOL_COMMAND_SKILLS, tool) ? TOOL_COMMAND_SKILLS[tool] : {};
+    return Object.hasOwn(rows, event) ? rows[event] : null;
+}
+
+/** The spelling for one tool's event in one agent's session, or null when that agent has none. */
+export function commandFor(tool, event, agent) {
+    const rows = commandsOf(tool);
+    if (!Object.hasOwn(rows, event)) return null;
+    const row = rows[event];
+    return Object.hasOwn(row, agent) ? row[agent] : null;
+}

package/templates/webterm/tools/index.js

@@ -0,0 +1,25 @@
+// =========================================================================================================================================
+// tools/index.js - The tools this pane hosts.
+//
+// One list, and everything about a tool is derived from its row: what is mounted, what is routed, what is broadcast, what a button
+// types and how much of the typing channel one session gets. server.js reads the list and never a tool's name, so a third tool is
+// a row here and a table beside it.
+//
+// The order is the order the tabs are drawn in, which is the pane's own list in `public/app/pane-shell.js`. The two lists are
+// checked against each other by the interface's tests rather than derived from one another, because the pane is drawn in the
+// browser and this file is read in the server.
+// =========================================================================================================================================
+
+import { REVIEWS_TABLE } from "./reviews.js";
+import { SPECS_TABLE } from "./specs.js";
+
+export const TOOLS = [SPECS_TABLE, REVIEWS_TABLE];
+
+/** The table of one tool, or undefined. Asked with `find`, so a name that is not a tool's is not one. */
+export function toolTable(id) {
+    return TOOLS.find((table) => table.id === id);
+}
+
+export { commandFor, commandSkill, commandsOf, TOOL_COMMAND_SKILLS, TOOL_COMMANDS } from "./commands.js";
+export { mountTool } from "./mount.js";
+export { CLIENT_PREFIX, toolPaths } from "./paths.js";