spatialagents 0.1.0__py3-none-any.whl

spatialagents/chat/static/chat.js

@@ -0,0 +1,933 @@
+/**
+ * chat.js -- the shared AI chat page (spatialagents.chat), lifted from
+ * Plexora's chat panel (client/src/js/views/chatPanel.js) as a full page.
+ *
+ * It speaks the `ChatApi` wire (spatialagents/chat/http.py):
+ *
+ *   - POST <base>/conversations starts one; a refusal carrying a `license`
+ *     block goes to the host's licence hook instead of a line;
+ *   - POST <base>/conversations/<id>/messages sends the person's turn;
+ *   - GET  <base>/conversations/<id>/events streams events (server-sent
+ *     events, resuming after the last id on a reconnect), and falls back to a
+ *     held poll (?after=&wait=20) when the stream errors -- a proxy that
+ *     buffers it, say;
+ *   - POST .../control (Stop), .../approve (Approve / Deny), .../undo (Undo,
+ *     when the host offers it);
+ *   - and, when the host runs plans, <base>/plans and <base>/plans/<id>/...:
+ *     compose a plan for a goal, answer its decisions, confirm and run it,
+ *     summarise it.
+ *
+ * The five hooks a host sets (window.SPATIALAGENTS_CHAT, or the page's
+ * settings block, or the script tag's data- attributes):
+ *
+ *   base              where the API is mounted ("api", "ai/v1")
+ *   title             the page's title, or a function returning a conversation title
+ *   onLicenseRefused  called with the `license` block of a 403 (default: a line saying so)
+ *   undo              whether to offer Undo on a reversible write
+ *   globalName        the window property this registers as ("SpatialAgentsChat")
+ *
+ * What the person sees: their words with thumbnails of what they attached;
+ * the answer as it streams, then rendered as Markdown -- headings, lists,
+ * tables, code, emphasis, links to http(s) only -- built with
+ * createElement/textContent, so nothing a model or a tool says is ever parsed
+ * as markup; one chip per tool call (cached, declined, error, Undo) with the
+ * figures a tool returned shown inline; approval cards; sub-agents' lines; a
+ * pause for credit; the credit meter. The plan panel shows a plan's steps
+ * (function, rationale badged by who wrote it, status), its claim ceiling,
+ * unit of replication and n per arm, its decisions as cards the person
+ * answers, the actions open now, and the report.
+ *
+ * Classic script, no build step.
+ */
+(function () {
+    "use strict";
+
+    const POLL_WAIT_S = 20;
+    const MAX_IMAGES = 4;
+    const INPUT_MAX_PX = 200;
+    const STICK_PX = 48;
+    const AUTHORS = { agent: "model", model: "model", template: "template", user: "you", rule: "rule" };
+    const KNOWN = ["disclosure", "user_message", "turn_started", "text_delta", "text", "tool_call", "tool_result",
+                   "approval_requested", "approval_decided", "usage", "done", "error", "paused", "stopped",
+                   "compacted", "agent_started", "agent_finished", "control", "undone", "turn_finished", "idle"];
+    const PLAN_EVENTS = ["composed", "problems", "decision_needed", "answered", "phase", "step", "run_finished",
+                         "report", "usage", "paused", "failed", "stopped", "stop_requested", "error"];
+
+    // -- settings -----------------------------------------------------------------------
+
+    function settings() {
+        let fromPage = {};
+        try {
+            const block = document.getElementById("spatialagents-settings");
+            if (block) fromPage = JSON.parse(block.textContent || "{}") || {};
+        } catch (_) { fromPage = {}; }
+        const tag = document.currentScript || document.querySelector("script[data-global]");
+        const fromTag = tag ? { globalName: tag.dataset.global, base: tag.dataset.base } : {};
+        const fromHost = (typeof window.SPATIALAGENTS_CHAT === "object" && window.SPATIALAGENTS_CHAT) || {};
+        const out = { base: "api", title: "AI assistant", assistant: "the assistant", undo: false, plans: false,
+                      globalName: "SpatialAgentsChat", dataset: "", storage: "spatialagents.chat",
+                      mount: "spatialagents-chat", onLicenseRefused: null };
+        for (const source of [fromPage, fromTag, fromHost]) {
+            for (const key of Object.keys(source)) {
+                if (source[key] !== undefined && source[key] !== null && source[key] !== "") out[key] = source[key];
+            }
+        }
+        out.base = String(out.base).replace(/^\/+|\/+$/g, "");
+        return out;
+    }
+
+    const config = settings();
+
+    const state = {
+        root: null, log: null, input: null, send: null, stop: null, meter: null, thumbs: null, planBox: null,
+        conversation: null, cursor: 0, source: null, polling: false, streamingNode: null, attached: [],
+        busy: false, credits: 0, echoes: 0, approvals: {},
+        plan: null, planCursor: 0, planSource: null, planPolling: false, planStatus: null, report: null,
+    };
+
+    function url(path) {
+        return (config.base ? config.base + "/" : "") + path;
+    }
+
+    // -- the DOM, safely ------------------------------------------------------------------
+
+    function el(tag, className, text) {
+        const node = document.createElement(tag);
+        if (className) node.className = className;
+        if (text !== undefined && text !== null) node.textContent = String(text);
+        return node;
+    }
+
+    function button(label, className, onClick) {
+        const node = el("button", className, label);
+        node.type = "button";
+        node.addEventListener("click", onClick);
+        return node;
+    }
+
+    async function post(path, body) {
+        try {
+            const response = await fetch(url(path), {
+                method: "POST", headers: { "Content-Type": "application/json" }, credentials: "same-origin",
+                body: JSON.stringify(body || {}),
+            });
+            let payload = {};
+            try { payload = await response.json(); } catch (_) { payload = {}; }
+            return { status: response.status, body: payload };
+        } catch (error) {
+            return { status: 0, body: { ok: false, error: { message: "The page could not reach the server." } } };
+        }
+    }
+
+    async function get(path) {
+        try {
+            const response = await fetch(url(path), { credentials: "same-origin" });
+            let payload = {};
+            try { payload = await response.json(); } catch (_) { payload = {}; }
+            return { status: response.status, body: payload };
+        } catch (_) {
+            return { status: 0, body: { ok: false } };
+        }
+    }
+
+    function errorText(body, fallback) {
+        const error = body && body.error;
+        if (error && typeof error === "object") return error.message || error.code || fallback;
+        return error || fallback;
+    }
+
+    // -- Markdown, as DOM ---------------------------------------------------------------------
+
+    const INLINE = /(`[^`]+`)|(\*\*[^*]+\*\*)|(__[^_]+__)|(\*[^*\s][^*]*\*)|(_[^_\s][^_]*_)|(\[[^\]]+\]\([^)\s]+\))/;
+
+    /** `text` with `code`, **bold**, *italic* and [links](https://...) as nodes. */
+    function inline(parent, text) {
+        let rest = String(text || "");
+        while (rest) {
+            const found = INLINE.exec(rest);
+            if (!found) {
+                parent.appendChild(document.createTextNode(rest));
+                break;
+            }
+            if (found.index) parent.appendChild(document.createTextNode(rest.slice(0, found.index)));
+            const token = found[0];
+            if (found[1]) {
+                parent.appendChild(el("code", "", token.slice(1, -1)));
+            } else if (found[2] || found[3]) {
+                inline(parent.appendChild(el("strong")), token.slice(2, -2));
+            } else if (found[4] || found[5]) {
+                inline(parent.appendChild(el("em")), token.slice(1, -1));
+            } else {
+                const label = token.slice(1, token.indexOf("]("));
+                const href = token.slice(token.indexOf("](") + 2, -1);
+                if (/^https?:\/\//i.test(href)) {
+                    const link = el("a", "", label);
+                    link.href = href;
+                    link.target = "_blank";
+                    link.rel = "noopener noreferrer";
+                    parent.appendChild(link);
+                } else {
+                    parent.appendChild(document.createTextNode(label));
+                }
+            }
+            rest = rest.slice(found.index + token.length);
+        }
+        return parent;
+    }
+
+    function cells(row) {
+        return row.trim().replace(/^\|/, "").replace(/\|$/, "").split("|").map((cell) => cell.trim());
+    }
+
+    /** Markdown into `parent`: headings, lists, tables, fenced code, quotes, paragraphs. */
+    function markdown(parent, text) {
+        parent.textContent = "";
+        const lines = String(text || "").replace(/\r\n?/g, "\n").split("\n");
+        let i = 0;
+        while (i < lines.length) {
+            const line = lines[i];
+            if (/^\s*```/.test(line)) {
+                const body = [];
+                i += 1;
+                while (i < lines.length && !/^\s*```/.test(lines[i])) body.push(lines[i++]);
+                i += 1;
+                parent.appendChild(el("pre", "sa-code")).appendChild(el("code", "", body.join("\n")));
+                continue;
+            }
+            const heading = /^(#{1,6})\s+(.*)$/.exec(line);
+            if (heading) {
+                const level = Math.min(6, heading[1].length + 2);
+                inline(parent.appendChild(el("h" + level, "sa-md-h")), heading[2]);
+                i += 1;
+                continue;
+            }
+            if (/^\s*\|.*\|\s*$/.test(line) && i + 1 < lines.length && /^\s*\|?\s*:?-{2,}/.test(lines[i + 1])) {
+                const table = parent.appendChild(el("table", "sa-md-table"));
+                const head = table.appendChild(el("thead")).appendChild(el("tr"));
+                for (const cell of cells(line)) inline(head.appendChild(el("th")), cell);
+                const body = table.appendChild(el("tbody"));
+                i += 2;
+                while (i < lines.length && /^\s*\|.*\|\s*$/.test(lines[i])) {
+                    const row = body.appendChild(el("tr"));
+                    for (const cell of cells(lines[i])) inline(row.appendChild(el("td")), cell);
+                    i += 1;
+                }
+                continue;
+            }
+            const bullet = /^\s*([-*+]|\d+[.)])\s+(.*)$/.exec(line);
+            if (bullet) {
+                const ordered = /\d/.test(bullet[1]);
+                const list = parent.appendChild(el(ordered ? "ol" : "ul", "sa-md-list"));
+                while (i < lines.length) {
+                    const item = /^\s*([-*+]|\d+[.)])\s+(.*)$/.exec(lines[i]);
+                    if (!item || /\d/.test(item[1]) !== ordered) break;
+                    inline(list.appendChild(el("li")), item[2]);
+                    i += 1;
+                }
+                continue;
+            }
+            if (/^\s*>/.test(line)) {
+                const quote = [];
+                while (i < lines.length && /^\s*>/.test(lines[i])) quote.push(lines[i++].replace(/^\s*>\s?/, ""));
+                inline(parent.appendChild(el("blockquote", "sa-md-quote")), quote.join(" "));
+                continue;
+            }
+            if (!line.trim()) {
+                i += 1;
+                continue;
+            }
+            const paragraph = [];
+            while (i < lines.length && lines[i].trim() && !/^(#{1,6}\s|\s*```|\s*[-*+]\s|\s*\d+[.)]\s|\s*>|\s*\|)/
+                .test(lines[i])) {
+                paragraph.push(lines[i++].trim());
+            }
+            if (!paragraph.length) paragraph.push(lines[i++].trim());
+            inline(parent.appendChild(el("p", "sa-md-p")), paragraph.join(" "));
+        }
+        return parent;
+    }
+
+    // -- the transcript ---------------------------------------------------------------------
+
+    function scroll(force) {
+        const log = state.log;
+        if (!log) return;
+        const away = (log.scrollHeight || 0) - (log.scrollTop || 0) - (log.clientHeight || 0);
+        if (force || away < STICK_PX) log.scrollTop = log.scrollHeight;
+    }
+
+    function line(className, text) {
+        const node = el("div", "sa-line " + className, text);
+        state.log.appendChild(node);
+        scroll();
+        return node;
+    }
+
+    function figure(parent, image, caption) {
+        const box = parent.appendChild(el("figure", "sa-figure"));
+        const img = box.appendChild(el("img", "sa-figure-img"));
+        img.src = "data:image/" + (image.format || "png") + ";base64," + image.data;
+        img.alt = caption || "a figure a tool returned";
+        if (caption) box.appendChild(el("figcaption", "", caption));
+        return box;
+    }
+
+    function credits(micro) {
+        return (Number(micro || 0) / 10000).toFixed(1);
+    }
+
+    function setBusy(busy) {
+        state.busy = busy;
+        if (state.send) state.send.disabled = busy;
+        if (state.stop) state.stop.hidden = !busy;
+        if (state.root) state.root.classList.toggle("is-busy", busy);
+    }
+
+    function grow() {
+        const input = state.input;
+        input.style.height = "auto";
+        input.style.height = Math.min(input.scrollHeight || 0, INPUT_MAX_PX) + "px";
+    }
+
+    function mount() {
+        if (state.root) return;
+        const host = document.getElementById(config.mount) || document.body;
+        const root = el("div", "sa-chat");
+        const header = root.appendChild(el("header", "sa-header"));
+        header.appendChild(el("h1", "sa-title", typeof config.title === "string" ? config.title : "AI assistant"));
+        state.meter = header.appendChild(el("span", "sa-meter", "0.0 credits"));
+        state.meter.title = "AI credits this page has used";
+
+        const body = root.appendChild(el("div", "sa-body"));
+        const chat = body.appendChild(el("section", "sa-conversation"));
+        chat.setAttribute("aria-label", "Conversation");
+        state.log = chat.appendChild(el("div", "sa-log"));
+        state.log.setAttribute("role", "log");
+        state.log.setAttribute("aria-live", "polite");
+
+        const dock = chat.appendChild(el("div", "sa-dock"));
+        state.thumbs = dock.appendChild(el("div", "sa-thumbs"));
+        const form = dock.appendChild(el("div", "sa-form"));
+        const picker = el("input", "sa-file");
+        picker.type = "file";
+        picker.accept = "image/png,image/jpeg,image/webp";
+        picker.multiple = true;
+        picker.hidden = true;
+        picker.addEventListener("change", () => attach(picker.files || []));
+        form.appendChild(button("Attach", "sa-attach", () => picker.click()));
+        state.input = form.appendChild(el("textarea", "sa-input"));
+        state.input.rows = 1;
+        state.input.placeholder = "Ask " + config.assistant + "...";
+        state.input.setAttribute("aria-label", "Message");
+        state.input.addEventListener("input", grow);
+        state.input.addEventListener("keydown", (event) => {
+            if (event.key === "Enter" && !event.shiftKey) {
+                event.preventDefault();
+                submit();
+            }
+        });
+        state.input.addEventListener("paste", (event) => {
+            const items = (event.clipboardData && event.clipboardData.files) || [];
+            if (items.length) attach(items);
+        });
+        state.stop = form.appendChild(button("Stop", "sa-stop", () => control("stop")));
+        state.stop.hidden = true;
+        state.send = form.appendChild(button("Send", "sa-send", () => submit()));
+        form.appendChild(picker);
+
+        if (config.plans) {
+            state.planBox = body.appendChild(el("aside", "sa-plan"));
+            state.planBox.setAttribute("aria-label", "Plan");
+        }
+        host.appendChild(root);
+        state.root = root;
+        if (config.plans) drawPlan();
+    }
+
+    // -- the conversation -----------------------------------------------------------------------
+
+    function storage(key, value) {
+        try {
+            if (!window.sessionStorage) return null;
+            if (value === undefined) return window.sessionStorage.getItem(config.storage + "." + key);
+            if (value === null) window.sessionStorage.removeItem(config.storage + "." + key);
+            else window.sessionStorage.setItem(config.storage + "." + key, value);
+        } catch (_) { /* private window: nothing survives a reload */ }
+        return null;
+    }
+
+    function titleOf() {
+        if (typeof config.title === "function") return String(config.title() || "");
+        return String(config.title || "");
+    }
+
+    function licenseRefused(license) {
+        if (typeof config.onLicenseRefused === "function") return config.onLicenseRefused(license);
+        line("sa-error", (license && license.message) || "This needs a licence that includes AI.");
+        return null;
+    }
+
+    async function open() {
+        mount();
+        if (state.conversation) return true;
+        const saved = storage("conversation");
+        if (saved) {
+            const answer = await get(`conversations/${encodeURIComponent(saved)}`);
+            if (answer.status === 200 && answer.body.ok) {
+                state.conversation = saved;
+                state.cursor = 0;
+                listen();
+                return true;
+            }
+            storage("conversation", null);
+        }
+        const answer = await post("conversations", { title: titleOf(), viewer: false });
+        if (answer.status === 403 && answer.body.license) {
+            licenseRefused(answer.body.license);
+            return false;
+        }
+        if (!answer.body.ok) {
+            line("sa-error", errorText(answer.body, "The assistant is not available."));
+            return false;
+        }
+        state.conversation = answer.body.conversation_id;
+        storage("conversation", state.conversation);
+        state.cursor = 0;
+        listen();
+        return true;
+    }
+
+    function attach(files) {
+        for (const file of Array.from(files)) {
+            if (state.attached.length >= MAX_IMAGES || !/^image\//.test(file.type || "")) continue;
+            const reader = new FileReader();
+            reader.onload = () => {
+                state.attached.push({ data: String(reader.result), format: (file.type.split("/")[1] || "png") });
+                drawThumbs();
+            };
+            reader.readAsDataURL(file);
+        }
+    }
+
+    function drawThumbs() {
+        state.thumbs.textContent = "";
+        state.attached.forEach((image, index) => {
+            const img = el("img", "sa-thumb");
+            img.src = image.data;
+            img.alt = "attached image " + (index + 1);
+            img.title = "Click to remove";
+            img.addEventListener("click", () => {
+                state.attached.splice(index, 1);
+                drawThumbs();
+            });
+            state.thumbs.appendChild(img);
+        });
+    }
+
+    async function submit() {
+        if (state.busy) return;
+        if (!state.conversation && !(await open())) return;
+        const text = (state.input.value || "").trim();
+        const images = state.attached.slice();
+        if (!text && !images.length) return;
+        state.input.value = "";
+        grow();
+        state.attached = [];
+        drawThumbs();
+        state.echoes += 1;
+        const mine = line("sa-user", text);
+        for (const image of images) {
+            const img = el("img", "sa-thumb");
+            img.src = image.data;
+            img.alt = "your image";
+            mine.appendChild(img);
+        }
+        scroll(true);
+        setBusy(true);
+        const answer = await post(`conversations/${state.conversation}/messages`, { text, images });
+        if (!answer.body.ok) {
+            state.echoes = Math.max(0, state.echoes - 1);
+            setBusy(false);
+            line("sa-error", errorText(answer.body, "The message was not sent."));
+        }
+    }
+
+    function control(action) {
+        if (!state.conversation) return Promise.resolve();
+        return post(`conversations/${state.conversation}/control`, { action });
+    }
+
+    // -- events, streamed or polled ----------------------------------------------------------------
+
+    /** Stream `path`'s events into `deliver`; fall back to a held poll. */
+    function subscribe(path, names, cursorOf, deliver, onFallback) {
+        if (typeof EventSource === "function") {
+            const source = new EventSource(url(`${path}?after=${cursorOf()}`));
+            const receive = (message) => {
+                let event;
+                try { event = JSON.parse(message.data); } catch (_) { return; }
+                deliver(event);
+            };
+            source.onmessage = receive;
+            for (const name of names) source.addEventListener(name, receive);
+            source.onerror = () => {
+                source.close();
+                onFallback();
+            };
+            return source;
+        }
+        onFallback();
+        return null;
+    }
+
+    async function pollLoop(path, active, cursorOf, deliver) {
+        while (active()) {
+            const answer = await get(`${path}?after=${cursorOf()}&wait=${POLL_WAIT_S}`);
+            for (const event of (answer.body && answer.body.events) || []) deliver(event);
+            if (answer.status !== 200) await new Promise((resolve) => setTimeout(resolve, 2000));
+        }
+    }
+
+    function listen() {
+        const path = `conversations/${state.conversation}/events`;
+        state.source = subscribe(path, KNOWN, () => state.cursor, handle, () => {
+            state.source = null;
+            if (state.polling) return;
+            state.polling = true;
+            pollLoop(path, () => state.polling && state.conversation, () => state.cursor, handle);
+        });
+    }
+
+    function handle(event) {
+        if (!event || typeof event.seq !== "number" || event.seq <= state.cursor) return;
+        state.cursor = event.seq;
+        const sub = event.agent ? "[" + event.agent + "] " : "";
+        switch (event.event) {
+        case "user_message":
+            if (state.echoes > 0) {
+                state.echoes -= 1;
+            } else {
+                const mine = line("sa-user", event.text || "");
+                if (event.images) mine.appendChild(el("div", "sa-note",
+                    event.images + (event.images === 1 ? " image" : " images")));
+            }
+            break;
+        case "approval_decided":
+            decided(event);
+            break;
+        case "turn_started":
+            setBusy(true);
+            break;
+        case "text_delta":
+            if (event.agent) break;
+            if (!state.streamingNode) state.streamingNode = line("sa-assistant", "");
+            state.streamingNode.textContent += event.text;
+            scroll();
+            break;
+        case "text":
+            if (event.agent) {
+                line("sa-sub", sub + event.text);
+            } else {
+                const node = state.streamingNode || line("sa-assistant", "");
+                markdown(node, event.text);
+                state.streamingNode = null;
+                scroll();
+            }
+            break;
+        case "tool_result":
+            toolChip(event, sub);
+            break;
+        case "approval_requested":
+            approvalCard(event, sub);
+            break;
+        case "usage":
+            if (typeof event.total_charged_micro === "number") meter(event.total_charged_micro, "chat");
+            break;
+        case "paused":
+            line("sa-notice", sub + "Paused: " + (event.message || event.reason) +
+                 (event.resume ? " (" + event.resume + ")" : ""));
+            break;
+        case "error":
+            line("sa-error", sub + (event.message || event.code));
+            break;
+        case "stopped":
+            line("sa-notice", "Stopped.");
+            break;
+        case "agent_started":
+            line("sa-sub", sub + "started: " + (event.brief || event.role || ""));
+            break;
+        case "agent_finished":
+            line("sa-sub", sub + (event.state === "done" ? "done: " : event.state + ": ") + (event.summary || ""));
+            break;
+        case "undone":
+            line("sa-notice", "Undone: " + event.operation_id);
+            break;
+        case "turn_finished":
+            state.streamingNode = null;
+            setBusy(false);
+            break;
+        default:
+            break;
+        }
+    }
+
+    const spent = { chat: 0, plan: 0 };
+
+    function meter(micro, which) {
+        spent[which] = micro;
+        state.meter.textContent = credits(spent.chat + spent.plan) + " credits";
+    }
+
+    function toolChip(event, sub) {
+        const chip = el("div", "sa-tool" + (event.ok ? "" : " is-error"));
+        const head = chip.appendChild(el("div", "sa-tool-head"));
+        head.appendChild(el("span", "sa-tool-name", sub + event.tool));
+        const status = event.ok ? (event.source === "cache" ? "ok, cached" : "ok") :
+            (event.source === "declined" ? "declined" : "error");
+        head.appendChild(el("span", "sa-tool-status", status));
+        if (event.summary && !event.ok) chip.title = event.summary;
+        if (config.undo && event.undo && event.operation_id) {
+            const undo = button("Undo", "sa-undo", async () => {
+                undo.disabled = true;
+                const answer = await post(`conversations/${state.conversation}/undo`,
+                                          { operation_id: event.operation_id });
+                undo.textContent = answer.body.ok ? "Undone" : "Undo failed";
+            });
+            undo.title = "Undo " + event.operation_id;
+            head.appendChild(undo);
+        }
+        for (const image of event.images || []) figure(chip, image, event.tool);
+        state.log.appendChild(chip);
+        scroll();
+    }
+
+    function approvalCard(event, sub) {
+        const card = el("div", "sa-approval");
+        const what = event.permission === "destructive" ? "cannot be undone" : "writes into your source file";
+        card.appendChild(el("div", "sa-approval-title", sub + event.tool + " " + what));
+        if (event.purpose) card.appendChild(el("div", "sa-approval-purpose", event.purpose));
+        card.appendChild(el("pre", "sa-code", JSON.stringify(event.arguments || {}, null, 1)));
+        const row = card.appendChild(el("div", "sa-actions"));
+        const decide = (decision) => async () => {
+            approve.disabled = true;
+            deny.disabled = true;
+            const answer = await post(`conversations/${state.conversation}/approve`,
+                                      { approval_id: event.approval_id, decision });
+            row.textContent = answer.body.ok ? (decision === "approve" ? "Approved" : "Declined") :
+                errorText(answer.body, "Not recorded");
+        };
+        const approve = row.appendChild(button("Approve", "sa-primary", decide("approve")));
+        const deny = row.appendChild(button("Deny", "sa-secondary", decide("deny")));
+        state.approvals[event.approval_id] = { row, approve, deny };
+        state.log.appendChild(card);
+        scroll();
+    }
+
+    function decided(event) {
+        const card = state.approvals[event.approval_id];
+        if (!card) return;
+        card.approve.disabled = true;
+        card.deny.disabled = true;
+        const words = { approved: "Approved", denied: "Declined", stopped: "Stopped", expired: "Expired" };
+        card.row.textContent = words[event.status] || String(event.status || "Decided");
+    }
+
+    // -- plans --------------------------------------------------------------------------------------
+
+    const ACTIONS = { confirm: "Confirm and run", continue: "Continue", summarise: "Summarise",
+                      retry: "Try again", compose: "Start over" };
+    const PHASE_WORDS = { composing: "Composing a plan", awaiting_decision: "Waiting for you",
+                          validated: "Ready to run", running: "Running", finished: "Finished",
+                          summarising: "Writing the report", reported: "Reported", nothing: "Nothing to run",
+                          failed: "Could not continue", stopped: "Stopped" };
+
+    async function startPlan(goal, dataset) {
+        const answer = await post("plans", { goal, dataset });
+        if (answer.status === 403 && answer.body.license) return licenseRefused(answer.body.license);
+        if (!answer.body.ok) {
+            line("sa-error", errorText(answer.body, "The plan could not be started."));
+            return null;
+        }
+        followPlan(answer.body.run_id);
+        return answer.body.run_id;
+    }
+
+    function followPlan(runId) {
+        if (state.planSource) state.planSource.close();
+        state.plan = runId;
+        state.planCursor = 0;
+        state.planPolling = false;
+        state.report = null;
+        storage("plan", runId);
+        const path = `plans/${runId}/events`;
+        state.planSource = subscribe(path, PLAN_EVENTS, () => state.planCursor, planEvent, () => {
+            state.planSource = null;
+            if (state.planPolling) return;
+            state.planPolling = true;
+            pollLoop(path, () => state.planPolling && state.plan === runId, () => state.planCursor, planEvent);
+        });
+        refreshPlan();
+    }
+
+    let refreshing = null;
+
+    async function refreshPlan() {
+        if (!state.plan) return;
+        if (refreshing) return refreshing;
+        refreshing = (async () => {
+            const answer = await get(`plans/${state.plan}`);
+            if (answer.status === 200 && answer.body.ok) {
+                state.planStatus = answer.body;
+                if (typeof answer.body.charged_micro === "number") meter(answer.body.charged_micro, "plan");
+                drawPlan();
+            }
+            refreshing = null;
+        })();
+        return refreshing;
+    }
+
+    function planEvent(event) {
+        if (!event || typeof event.seq !== "number" || event.seq <= state.planCursor) return;
+        state.planCursor = event.seq;
+        if (event.event === "report") state.report = event.markdown || "";
+        if (event.event === "usage" && typeof event.total_charged_micro === "number") {
+            meter(event.total_charged_micro, "plan");
+            return;
+        }
+        if (event.event === "error") line("sa-error", "Plan: " + (event.message || event.code));
+        refreshPlan();
+    }
+
+    async function planAction(action) {
+        const answer = await post(`plans/${state.plan}/${action}`, {});
+        if (!answer.body.ok) line("sa-error", errorText(answer.body, "That did not work."));
+        refreshPlan();
+    }
+
+    async function answerDecision(decision, value, row) {
+        const answer = await post(`plans/${state.plan}/answer`, { decision_id: decision.id, answer: value });
+        if (!answer.body.ok) {
+            if (row) row.appendChild(el("div", "sa-error", errorText(answer.body, "That answer was not taken.")));
+            return;
+        }
+        state.planStatus = answer.body;
+        drawPlan();
+    }
+
+    function drawPlan() {
+        const box = state.planBox;
+        if (!box) return;
+        box.textContent = "";
+        box.appendChild(el("h2", "sa-plan-title", "Plan"));
+        const status = state.planStatus;
+        if (!state.plan || !status) {
+            box.appendChild(planForm());
+            return;
+        }
+        const head = box.appendChild(el("div", "sa-plan-head"));
+        head.appendChild(el("div", "sa-plan-goal", status.goal || ""));
+        head.appendChild(el("span", "sa-phase sa-phase-" + status.phase, PHASE_WORDS[status.phase] || status.phase));
+        if (status.summary) box.appendChild(el("p", "sa-plan-summary", status.summary));
+        if (status.paused) {
+            box.appendChild(el("div", "sa-notice", "Paused: " + (status.paused.message || status.paused.code)));
+        }
+        if (status.reason) box.appendChild(el("div", "sa-error", status.reason));
+        const plan = status.plan;
+        if (plan) {
+            const facts = box.appendChild(el("dl", "sa-facts"));
+            const fact = (label, value) => {
+                if (value === null || value === undefined || value === "") return;
+                facts.appendChild(el("dt", "", label));
+                facts.appendChild(el("dd", "", typeof value === "object" ? perArm(value) : String(value)));
+            };
+            fact("Claim ceiling", plan.claim_ceiling);
+            fact("Unit of replication", plan.unit_of_replication);
+            fact("n per arm", plan.n_per_arm);
+            fact("Version", plan.version);
+            const steps = box.appendChild(el("ol", "sa-steps"));
+            for (const step of plan.steps || []) steps.appendChild(stepItem(step));
+            for (const decision of plan.decisions || []) {
+                if (decision.state === "open") box.appendChild(decisionCard(decision));
+            }
+        }
+        const actions = box.appendChild(el("div", "sa-actions"));
+        for (const action of status.actions || []) {
+            if (action === "answer") continue;
+            if (action === "compose") {
+                actions.appendChild(button(ACTIONS.compose, "sa-secondary", () => {
+                    state.plan = null;
+                    state.planStatus = null;
+                    storage("plan", null);
+                    drawPlan();
+                }));
+                continue;
+            }
+            actions.appendChild(button(ACTIONS[action] || action, action === "confirm" ? "sa-primary" : "sa-secondary",
+                                       () => planAction(action)));
+        }
+        if (status.phase === "running") actions.appendChild(button("Stop after this step", "sa-secondary",
+                                                                   () => planAction("stop")));
+        if (state.report !== null && state.report !== undefined) {
+            const report = box.appendChild(el("section", "sa-report"));
+            report.appendChild(el("h3", "", "Report"));
+            markdown(report.appendChild(el("div", "sa-report-body")), state.report);
+            if (status.report && status.report.path) report.appendChild(el("div", "sa-note", status.report.path));
+        }
+        if (typeof status.charged_micro === "number") {
+            box.appendChild(el("div", "sa-note", credits(status.charged_micro) + " credits for this plan"));
+        }
+    }
+
+    function perArm(value) {
+        return Object.keys(value).map((key) => key + ": " + value[key]).join(", ");
+    }
+
+    function planForm() {
+        const form = el("div", "sa-plan-form");
+        const goal = form.appendChild(el("textarea", "sa-input"));
+        goal.rows = 3;
+        goal.placeholder = "What do you want to learn?";
+        goal.setAttribute("aria-label", "Goal");
+        const dataset = form.appendChild(el("input", "sa-text"));
+        dataset.placeholder = "Dataset";
+        dataset.value = config.dataset || "";
+        dataset.setAttribute("aria-label", "Dataset");
+        form.appendChild(button("Make a plan", "sa-primary", () => {
+            const text = (goal.value || "").trim();
+            if (text) startPlan(text, (dataset.value || "").trim());
+        }));
+        return form;
+    }
+
+    function stepItem(step) {
+        const item = el("li", "sa-step sa-step-" + (step.status || "pending"));
+        const head = item.appendChild(el("div", "sa-step-head"));
+        head.appendChild(el("code", "sa-step-function", step.function));
+        head.appendChild(el("span", "sa-step-status", step.status || "pending"));
+        if (step.rationale) {
+            const why = item.appendChild(el("div", "sa-step-why"));
+            const by = AUTHORS[step.rationale_by] || step.rationale_by;
+            if (by) why.appendChild(el("span", "sa-badge sa-badge-" + by, by));
+            why.appendChild(document.createTextNode(" " + step.rationale));
+        }
+        if (step.claim) item.appendChild(el("div", "sa-note", "supports: " + step.claim));
+        if (step.error) item.appendChild(el("div", "sa-error", (step.error && step.error.message) || String(step.error)));
+        return item;
+    }
+
+    // -- decision cards ------------------------------------------------------------------------------
+
+    function decisionCard(decision) {
+        const card = el("div", "sa-decision sa-decision-" + decision.kind);
+        card.appendChild(el("div", "sa-decision-question", decision.question || decision.id));
+        if (decision.why) card.appendChild(el("div", "sa-decision-why", decision.why));
+        if (decision.consequence) card.appendChild(el("div", "sa-note", decision.consequence));
+        if ((decision.evidence || []).length) {
+            const list = card.appendChild(el("ul", "sa-evidence"));
+            for (const item of decision.evidence) list.appendChild(el("li", "", evidence(item)));
+        }
+        const row = card.appendChild(el("div", "sa-decision-answer"));
+        const options = (decision.options || []).filter((option) => option && option.id !== undefined);
+        if (decision.kind === "build_workflow") {
+            rowsEditor(decision, row);
+        } else if (decision.kind === "provide_file" || (decision.kind === "free_text" && !options.length)) {
+            const input = row.appendChild(el(decision.kind === "free_text" ? "textarea" : "input", "sa-text"));
+            input.placeholder = decision.kind === "provide_file" ? "A file path" : "Your answer";
+            if (decision.default) input.value = String(decision.default);
+            row.appendChild(button("Answer", "sa-primary", () => {
+                const value = (input.value || "").trim();
+                if (value) answerDecision(decision, value, row);
+            }));
+        } else {
+            for (const option of options) {
+                const choice = row.appendChild(button(option.label || String(option.id),
+                                                      option.recommended ? "sa-primary" : "sa-secondary",
+                                                      () => answerDecision(decision, option.id, row)));
+                if (option.consequence) choice.title = option.consequence;
+                if (option.recommended) choice.appendChild(el("span", "sa-badge", "recommended"));
+            }
+            if (decision.kind === "free_text" || decision.kind === "choose_option") freeText(decision, row, options);
+        }
+        return card;
+    }
+
+    function evidence(item) {
+        if (item === null || typeof item !== "object") return String(item);
+        return Object.keys(item).map((key) => key + ": " + (typeof item[key] === "object" ?
+            JSON.stringify(item[key]) : item[key])).join("; ");
+    }
+
+    /** In words, matched to an option by one small model call, which the person then confirms. */
+    function freeText(decision, row, options) {
+        if (!options.length) return;
+        const wrap = row.appendChild(el("div", "sa-free"));
+        const input = wrap.appendChild(el("input", "sa-text"));
+        input.placeholder = "Or say it in your words";
+        const result = el("div", "sa-note");
+        wrap.appendChild(button("Match", "sa-secondary", async () => {
+            const text = (input.value || "").trim();
+            if (!text) return;
+            const answer = await post(`plans/${state.plan}/resolve`, { decision_id: decision.id, text });
+            result.textContent = "";
+            if (!answer.body.ok || !answer.body.option) {
+                result.textContent = (answer.body && answer.body.why) || "That matched none of the options.";
+                return;
+            }
+            const option = options.find((item) => String(item.id) === String(answer.body.option));
+            result.appendChild(document.createTextNode("Did you mean “" +
+                ((option && option.label) || answer.body.option) + "”? "));
+            result.appendChild(button("Yes", "sa-primary", () => answerDecision(decision, answer.body.option, row)));
+        }));
+        wrap.appendChild(result);
+    }
+
+    /** A phenotype workflow, row by row: parent, population, markers. */
+    function rowsEditor(decision, row) {
+        const table = row.appendChild(el("table", "sa-md-table sa-rows"));
+        const head = table.appendChild(el("thead")).appendChild(el("tr"));
+        for (const name of ["Parent", "Population", "Markers (comma separated)", ""]) head.appendChild(el("th", "", name));
+        const body = table.appendChild(el("tbody"));
+        const addRow = (values) => {
+            const tr = body.appendChild(el("tr"));
+            for (const key of ["parent", "population", "markers"]) {
+                const input = tr.appendChild(el("td")).appendChild(el("input", "sa-text"));
+                input.dataset.key = key;
+                const value = values && values[key];
+                input.value = Array.isArray(value) ? value.join(", ") : (value || "");
+            }
+            tr.appendChild(el("td")).appendChild(button("Remove", "sa-secondary", () => tr.remove()));
+        };
+        for (const values of Array.isArray(decision.default) ? decision.default : [{}]) addRow(values);
+        const actions = row.appendChild(el("div", "sa-actions"));
+        actions.appendChild(button("Add a row", "sa-secondary", () => addRow({})));
+        actions.appendChild(button("Use these rows", "sa-primary", () => {
+            const rows = [];
+            for (const tr of Array.from(body.querySelectorAll("tr"))) {
+                const values = {};
+                for (const input of Array.from(tr.querySelectorAll("input"))) values[input.dataset.key] = input.value.trim();
+                if (!values.population) continue;
+                rows.push({ parent: values.parent || null, population: values.population,
+                            markers: (values.markers || "").split(",").map((m) => m.trim()).filter(Boolean) });
+            }
+            if (rows.length) answerDecision(decision, rows, row);
+        }));
+    }
+
+    // -- start ----------------------------------------------------------------------------------------
+
+    function boot() {
+        mount();
+        open();
+        if (config.plans) {
+            const saved = storage("plan");
+            if (saved) followPlan(saved);
+        }
+    }
+
+    const api = { open, handle, planEvent, startPlan, followPlan, markdown, mount, config, _state: state };
+    window[config.globalName || "SpatialAgentsChat"] = api;
+    if (config.autostart !== false) {
+        if (document.readyState === "loading") document.addEventListener("DOMContentLoaded", boot);
+        else boot();
+    }
+})();