@jbarket/loomai 0.7.0 → 0.9.0

package/dist/ui/handler.js

@@ -0,0 +1,399 @@
+/**
+ * loom's web UI on the HTTP daemon (full scope only).
+ *
+ *   GET  /ui                       Home: the tape, tiles, "Your call"
+ *   GET  /ui/mind, /ui/people[/<slug>], /ui/memory/<ref>   loom's own pages
+ *   GET  /ui/p/<piece>[/<path>]    a piece's page
+ *   GET  /ui/pieces.json           the installed pieces' manifests, for scripts
+ *   POST /ui/act/<source>          an action (source = loom or a piece)
+ *   GET/POST /ui/login, POST /ui/logout
+ *
+ * Auth follows the daemon's bearer token, and the UI needs one: a daemon with
+ * no token serves no /ui (like /cli), because an open page would be readable
+ * by any site that DNS-rebinds a name to the loopback address. A browser logs
+ * in once by pasting the token and gets a session: a random id held in this
+ * process's memory. It isn't the token and isn't derivable from it, so it
+ * can't be replayed as a bearer or used to guess the token. It lasts 30 days,
+ * until logout (which revokes it), until the token changes, or until the
+ * daemon restarts. Scripts can send the bearer header instead.
+ *
+ * A GET from another site or another port is served only as a top-level
+ * navigation, never to an <img> or a fetch (fetch metadata).
+ *
+ * Every POST from a browser carries an anti-forgery token derived from its
+ * cookie, and a cross-site POST is refused outright (Sec-Fetch-Site / Origin),
+ * on top of the SameSite=Strict cookie. The page runs no script and is served
+ * under a CSP that forbids script and framing. Action fields go to the piece
+ * on stdin and are never logged, stored, or put in a URL; the one-time result
+ * message is kept in memory under a random id for a minute.
+ */
+import { createHash, createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+import { checkBearer } from '../transport/guards.js';
+import { agentName, coreAct, corePage, homePage, uiTimeZone } from './core.js';
+import { pieceAct, pieceManifests, piecePage } from './pieces.js';
+import { CORE, pieceSource, renderHome, renderLogin, renderPage } from './render.js';
+import { ID, LIMITS, QUERY_KEY, splitPage, validPath } from './vocab.js';
+const COOKIE = 'loom_ui';
+const LOGIN_MAX_BYTES = 4096;
+const ACT_MAX_BYTES = 64 * 1024;
+const COOKIE_MAX_AGE_S = 30 * 24 * 3600;
+const FLASH_TTL_MS = 60_000;
+const FLASH_MAX = 200;
+/** This process's cookie key. Never written anywhere: a restart means logging in again. */
+const COOKIE_KEY = randomBytes(32);
+const SECURITY_HEADERS = {
+    'content-security-policy': "default-src 'none'; style-src 'unsafe-inline'; form-action 'self'; frame-ancestors 'none'; base-uri 'none'",
+    'x-content-type-options': 'nosniff',
+    'referrer-policy': 'no-referrer',
+    'cache-control': 'no-store',
+};
+export function isUiPath(pathname) {
+    return pathname === '/ui' || pathname.startsWith('/ui/');
+}
+const digest = (s) => createHash('sha256').update(s).digest();
+const sessions = new Map();
+const MAX_SESSIONS = 50;
+function newSession(secret) {
+    const id = randomBytes(32).toString('hex');
+    sessions.set(id, { issuedAt: Math.floor(Date.now() / 1000), secret: digest(secret) });
+    // Oldest first in a Map: drop the oldest past the cap.
+    while (sessions.size > MAX_SESSIONS)
+        sessions.delete(sessions.keys().next().value);
+    return id;
+}
+/** The anti-forgery token for a session: bound to its id, useless without it. */
+function csrfFor(id) {
+    return createHmac('sha256', COOKIE_KEY).update(`loom-ui-csrf|${id}`).digest('hex');
+}
+/** Equal-length digests, so neither the content nor the length of a guess leaks. */
+function safeEq(a, b) {
+    return timingSafeEqual(digest(a), digest(b));
+}
+function validSession(id, secrets, nowS = Math.floor(Date.now() / 1000)) {
+    if (!/^[0-9a-f]{64}$/.test(id))
+        return false;
+    const s = sessions.get(id);
+    if (!s)
+        return false;
+    if (nowS - s.issuedAt > COOKIE_MAX_AGE_S) {
+        sessions.delete(id);
+        return false;
+    }
+    // A session dies with its token: rotate the token and old sessions stop.
+    return secrets.some((t) => timingSafeEqual(digest(t), s.secret));
+}
+function readCookie(req, name) {
+    for (const part of (req.headers.cookie ?? '').split(';')) {
+        const [k, ...v] = part.trim().split('=');
+        if (k === name)
+            return v.join('=');
+    }
+    return undefined;
+}
+function whoIs(req, opts) {
+    if (opts.secrets.length === 0)
+        return null;
+    const c = readCookie(req, COOKIE);
+    if (c && validSession(c, opts.secrets))
+        return { kind: 'session', cookie: c };
+    const header = req.headers['authorization'];
+    if (header !== undefined && opts.secrets.some((s) => checkBearer(s, header).ok))
+        return { kind: 'bearer' };
+    return null;
+}
+/**
+ * A GET from somewhere else is fine as a top-level navigation (a link in a
+ * chat) and refused otherwise: an <img> or fetch from another site, or from
+ * another port on this host (same-site, so the cookie rides along), must not
+ * make loom run a piece.
+ */
+function allowedGet(req) {
+    const site = req.headers['sec-fetch-site'];
+    if (site === undefined || site === 'same-origin' || site === 'none')
+        return true;
+    return req.headers['sec-fetch-mode'] === 'navigate' && req.headers['sec-fetch-dest'] === 'document';
+}
+/**
+ * A browser POST must come from loom's own page. Sec-Fetch-Site is set by
+ * every current browser and can't be forged by a page; Origin, when sent,
+ * must name this host. Either one saying "elsewhere" is a refusal.
+ */
+function sameOrigin(req) {
+    const site = req.headers['sec-fetch-site'];
+    if (site !== undefined && site !== 'same-origin' && site !== 'none')
+        return false;
+    const origin = req.headers.origin;
+    if (origin !== undefined) {
+        if (origin === 'null')
+            return false;
+        try {
+            if (new URL(origin).host !== req.headers.host)
+                return false;
+        }
+        catch {
+            return false;
+        }
+    }
+    return true;
+}
+function send(res, status, type, body, extra = {}) {
+    res.writeHead(status, { 'content-type': type, ...SECURITY_HEADERS, ...extra });
+    res.end(body);
+}
+function redirect(res, to, extra = {}) {
+    res.writeHead(303, { location: to, ...SECURITY_HEADERS, ...extra });
+    res.end();
+}
+function readForm(req, max) {
+    return new Promise((resolve) => {
+        const chunks = [];
+        let bytes = 0;
+        let done = false;
+        const finish = (v) => { if (!done) {
+            done = true;
+            resolve(v);
+        } };
+        req.on('data', (d) => {
+            if (done)
+                return;
+            bytes += d.length;
+            if (bytes > max) {
+                finish(null);
+                req.destroy();
+                return;
+            }
+            chunks.push(d);
+        });
+        req.on('end', () => finish(new URLSearchParams(Buffer.concat(chunks).toString('utf-8'))));
+        req.on('error', () => finish(null));
+        req.on('close', () => finish(null));
+    });
+}
+/** The page's own query: valid keys only, loom's `_` keys and oversize values dropped. */
+function pageQuery(url) {
+    const q = Object.create(null);
+    let n = 0;
+    for (const [k, v] of url.searchParams) {
+        if (!QUERY_KEY.test(k) || v.length > LIMITS.queryValue || Object.hasOwn(q, k))
+            continue;
+        if (++n > LIMITS.query)
+            break;
+        q[k] = v;
+    }
+    return q;
+}
+const flashes = new Map();
+function putFlash(flash) {
+    const now = Date.now();
+    for (const [k, v] of flashes)
+        if (now - v.at > FLASH_TTL_MS || flashes.size > FLASH_MAX)
+            flashes.delete(k);
+    const id = randomBytes(12).toString('hex');
+    flashes.set(id, { at: now, flash });
+    return id;
+}
+function takeFlash(id) {
+    if (!id)
+        return undefined;
+    const f = flashes.get(id);
+    flashes.delete(id);
+    return f && Date.now() - f.at <= FLASH_TTL_MS ? f.flash : undefined;
+}
+// ─── Assembling a page ───────────────────────────────────────────────────────
+function clock() {
+    return new Intl.DateTimeFormat('en-US', { timeZone: uiTimeZone(), weekday: 'short', hour: 'numeric', minute: '2-digit', timeZoneName: 'short' }).format(new Date());
+}
+function hasPages(p) {
+    return Boolean(p.manifest.tab || p.manifest.legacy?.length);
+}
+function chrome(opts, pieces, skipped, current, csrf, flash) {
+    const tabs = pieces.filter(hasPages)
+        .map((p) => ({ label: p.manifest.tab?.label ?? p.piece, href: `/ui/p/${p.piece}`, current: current === `p/${p.piece}`, piece: true }))
+        .sort((a, b) => a.label.localeCompare(b.label));
+    return {
+        agent: agentName(opts.contextDir),
+        nav: [
+            { label: 'Home', href: '/ui', current: current === '', piece: false },
+            { label: 'Mind', href: '/ui/mind', current: current === 'mind', piece: false },
+            { label: 'People', href: '/ui/people', current: current === 'people', piece: false },
+            ...tabs,
+        ],
+        clock: clock(),
+        csrf,
+        flash,
+        skipped,
+    };
+}
+/** Where to land after an action: the page the piece names, or back where the form was. */
+function landing(source, result, back) {
+    const s = (result.page !== undefined ? splitPage(result.page) : null) ?? splitPage(back);
+    const core = s?.core || source.id === 'loom';
+    const path = s?.path ?? '';
+    const q = s ? new URLSearchParams(s.query).toString() : '';
+    const base = core ? `/ui${path ? `/${path}` : ''}` : `/ui/p/${source.id}${path ? `/${path}` : ''}`;
+    return q ? `${base}?${q}` : base;
+}
+function withFlash(to, id) {
+    return `${to}${to.includes('?') ? '&' : '?'}_flash=${id}`;
+}
+const notFound = { title: 'Not found', sections: [] };
+/** decodeURIComponent, or null for a malformed escape (a 404, never a 500). */
+function decode(s) {
+    try {
+        return decodeURIComponent(s);
+    }
+    catch {
+        return null;
+    }
+}
+/** Handle a /ui request. The caller has already matched isUiPath. */
+export async function handleUi(req, res, pathname, opts) {
+    // No token, no page: an open /ui would be readable by any site that
+    // DNS-rebinds a name to the loopback address (the same rule as /cli).
+    if (opts.secrets.length === 0) {
+        return send(res, 403, 'text/plain', 'forbidden: loom\'s page requires LOOM_BEARER_TOKEN');
+    }
+    const secure = req.headers['x-forwarded-proto'] === 'https';
+    if (pathname === '/ui/login') {
+        // Unauthenticated: the login page names no agent.
+        if (req.method === 'GET')
+            return send(res, 200, 'text/html; charset=utf-8', renderLogin());
+        if (req.method !== 'POST')
+            return send(res, 405, 'text/plain', 'method not allowed');
+        if (!sameOrigin(req))
+            return send(res, 403, 'text/plain', 'forbidden: cross-site request');
+        const form = await readForm(req, LOGIN_MAX_BYTES);
+        if (!form)
+            return send(res, 413, 'text/plain', 'too large');
+        const token = form.get('token')?.trim() ?? '';
+        const match = opts.secrets.find((s) => safeEq(token, s));
+        if (!match)
+            return send(res, 401, 'text/html; charset=utf-8', renderLogin('That token didn’t match.'));
+        return redirect(res, '/ui', {
+            'set-cookie': `${COOKIE}=${newSession(match)}; Path=/ui; HttpOnly; SameSite=Strict; Max-Age=${COOKIE_MAX_AGE_S}${secure ? '; Secure' : ''}`,
+        });
+    }
+    const who = whoIs(req, opts);
+    const csrf = who?.kind === 'session' ? csrfFor(who.cookie) : '';
+    if (pathname === '/ui/logout') {
+        if (req.method !== 'POST')
+            return send(res, 405, 'text/plain', 'method not allowed');
+        if (!sameOrigin(req))
+            return send(res, 403, 'text/plain', 'forbidden: cross-site request');
+        // Revoke it server-side, so a copy of the cookie stops working too.
+        const c = readCookie(req, COOKIE);
+        if (c)
+            sessions.delete(c);
+        return redirect(res, '/ui/login', { 'set-cookie': `${COOKIE}=; Path=/ui; HttpOnly; SameSite=Strict; Max-Age=0` });
+    }
+    if (!who) {
+        if (pathname.endsWith('.json'))
+            return send(res, 401, 'application/json', JSON.stringify({ error: 'unauthorized' }));
+        if (req.method === 'GET')
+            return redirect(res, '/ui/login');
+        return send(res, 401, 'text/plain', 'unauthorized');
+    }
+    const url = new URL(req.url ?? pathname, 'http://loom.invalid');
+    if (pathname.startsWith('/ui/act/')) {
+        if (req.method !== 'POST')
+            return send(res, 405, 'text/plain', 'method not allowed');
+        if (!sameOrigin(req))
+            return send(res, 403, 'text/plain', 'forbidden: cross-site request');
+        const sourceId = pathname.slice('/ui/act/'.length);
+        if (sourceId !== 'loom' && !ID.test(sourceId))
+            return send(res, 404, 'text/plain', 'not found');
+        const form = await readForm(req, ACT_MAX_BYTES);
+        if (!form)
+            return send(res, 413, 'text/plain', 'too large');
+        // A browser session must prove the form came from loom's page. A bearer
+        // script has no ambient credential a forger could ride, so it needs none.
+        if (who.kind === 'session' && !safeEq(form.get('_csrf') ?? '', csrf)) {
+            return send(res, 403, 'text/plain', 'forbidden: this form is stale or not from loom\'s page; reload and try again');
+        }
+        const action = form.get('_action') ?? '';
+        const back = form.get('_path') ?? '';
+        if (!/^[a-z][a-z0-9_-]{0,39}$/.test(action))
+            return send(res, 400, 'text/plain', 'bad action');
+        const backLink = splitPage(back) ? back : '';
+        // A form has up to LIMITS.fields fields plus LIMITS.hidden hidden values.
+        // More than that is refused whole, never cut short: a truncated form
+        // could drop the very field (a secret) the piece needs.
+        const fields = Object.create(null);
+        for (const [k, v] of form) {
+            if (k.startsWith('_') || !/^[a-z][a-z0-9_-]{0,39}$/.test(k) || Object.hasOwn(fields, k))
+                continue;
+            fields[k] = v;
+        }
+        if (Object.keys(fields).length > LIMITS.fields + LIMITS.hidden)
+            return send(res, 400, 'text/plain', 'too many fields');
+        let source;
+        let result;
+        if (sourceId === 'loom') {
+            source = CORE;
+            result = await coreAct(opts.contextDir, action, fields);
+        }
+        else {
+            const { pieces } = await pieceManifests(opts.env);
+            const info = pieces.find((p) => p.piece === sourceId);
+            if (!info)
+                return send(res, 404, 'text/plain', 'not found');
+            source = pieceSource(info.piece);
+            const path = splitPage(backLink)?.path ?? '';
+            result = await pieceAct(info, { action, path, fields }, opts.env);
+        }
+        const to = landing(source, result, backLink);
+        // A piece's message is labeled with the piece, so it can't pass as loom's.
+        const from = source.id === 'loom' ? undefined : source.id;
+        return redirect(res, withFlash(to, putFlash({ ok: result.ok, message: result.message, from })));
+    }
+    if (req.method !== 'GET')
+        return send(res, 405, 'text/plain', 'method not allowed');
+    if (!allowedGet(req))
+        return send(res, 403, 'text/plain', 'forbidden: loom\'s page can only be opened, not embedded or fetched from another site');
+    if (pathname === '/ui/pieces.json') {
+        const m = await pieceManifests(opts.env);
+        return send(res, 200, 'application/json', JSON.stringify({
+            agent: agentName(opts.contextDir),
+            pieces: m.pieces.map((p) => ({ piece: p.piece, manifest: p.manifest })),
+            skipped: m.skipped,
+        }));
+    }
+    const query = pageQuery(url);
+    const flash = takeFlash(url.searchParams.get('_flash'));
+    const { pieces, skipped } = await pieceManifests(opts.env);
+    const skippedNames = skipped.map((s) => s.piece);
+    const html = (body, status = 200) => send(res, status, 'text/html; charset=utf-8', body);
+    if (pathname === '/ui' || pathname === '/ui/') {
+        const home = homePage(opts.contextDir, query);
+        const tiles = [
+            { ...home.tile, source: CORE },
+            ...pieces.filter((p) => p.manifest.tile).map((p) => ({ ...p.manifest.tile, source: pieceSource(p.piece) })),
+        ];
+        const asks = pieces.flatMap((p) => p.manifest.asks.map((a) => ({ ...a, source: pieceSource(p.piece) })));
+        return html(renderHome(home.page, { source: CORE, path: '', query, csrf }, chrome(opts, pieces, skippedNames, '', csrf, flash), tiles, asks));
+    }
+    if (pathname.startsWith('/ui/p/')) {
+        const rest = pathname.slice('/ui/p/'.length);
+        const slash = rest.indexOf('/');
+        const piece = slash === -1 ? rest : rest.slice(0, slash);
+        const path = slash === -1 ? '' : decode(rest.slice(slash + 1));
+        const info = pieces.find((p) => p.piece === piece && hasPages(p));
+        const ch = chrome(opts, pieces, skippedNames, `p/${piece}`, csrf, flash);
+        if (!info || path === null || !validPath(path))
+            return html(renderPage(notFound, { source: pieceSource(piece), path: '', query: {}, csrf }, ch), 404);
+        const page = await piecePage(info, path, query, opts.env);
+        const ctx = { source: pieceSource(piece), path, query, csrf };
+        if (typeof page === 'string') {
+            return html(renderPage({ title: info.manifest.tab?.label ?? piece, sections: [{ id: 'error', blocks: [{ type: 'callout', tone: 'bad', text: `${piece} couldn't show this page (${page}).` }] }] }, ctx, ch), 502);
+        }
+        return html(renderPage(page, ctx, ch), page.title === 'Not found' && page.sections.length === 0 ? 404 : 200);
+    }
+    const path = decode(pathname.slice('/ui/'.length)) ?? '\0';
+    const top = path.split('/')[0];
+    const ch = chrome(opts, pieces, skippedNames, top, csrf, flash);
+    const page = validPath(path) ? corePage(opts.contextDir, path, query) : null;
+    const ctx = { source: CORE, path: validPath(path) ? path : '', query, csrf };
+    if (!page)
+        return html(renderPage(notFound, ctx, ch), 404);
+    return html(renderPage(page, ctx, ch), page.title === 'Not found' && page.sections.length === 0 ? 404 : 200);
+}

package/dist/ui/pieces.d.ts

@@ -0,0 +1,37 @@
+import { type ActResult, type Manifest, type Page } from './vocab.js';
+export declare const PIECE_TIMEOUT_MS = 3000;
+export declare const ACT_TIMEOUT_MS = 15000;
+export declare const PIECE_MAX_BYTES: number;
+/** Longer than the page's 30s refresh, so an open tab doesn't re-run every piece each time. */
+export declare const CACHE_MS = 45000;
+export interface PieceInfo {
+    piece: string;
+    path: string;
+    manifest: Manifest;
+}
+/** Why a piece contributed nothing, for the page footer (never shown as an error). */
+export interface PieceSkip {
+    piece: string;
+    reason: string;
+}
+export declare function clearPieceCache(path?: string): void;
+export declare function pieceEnv(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+/**
+ * At most this many piece processes at once, across every page load: a burst
+ * of requests queues instead of forking a process each. The time limit starts
+ * when a piece actually runs.
+ */
+export declare const MAX_RUNNING = 6;
+/** Every installed piece's manifest, plus the ones that had nothing to show and why. */
+export declare function pieceManifests(env: NodeJS.ProcessEnv, nowMs?: number): Promise<{
+    pieces: PieceInfo[];
+    skipped: PieceSkip[];
+}>;
+/** One page from a piece, or why it couldn't be had. */
+export declare function piecePage(info: PieceInfo, path: string, query: Record<string, string>, env: NodeJS.ProcessEnv): Promise<Page | string>;
+/** Run an action on a piece. Field values go on stdin only. */
+export declare function pieceAct(info: PieceInfo, request: {
+    action: string;
+    path: string;
+    fields: Record<string, string>;
+}, env: NodeJS.ProcessEnv): Promise<ActResult>;

package/dist/ui/pieces.js

@@ -0,0 +1,191 @@
+/**
+ * Talking to installed pieces for the page: each `loom-<piece>` on PATH is
+ * asked `ui --json` for its manifest, `ui page --json` for a page and
+ * `ui act --json` to run an action (docs/extensions.md, "The page"). A piece
+ * that answers shows up with no configuration; one that doesn't (no `ui`
+ * verb, a timeout, bad JSON) simply isn't there. Composes without requiring.
+ *
+ * Bounded on every axis: one manifest run per piece per cache window however
+ * many pages load at once (the in-flight promise is what's cached), a time
+ * limit and 512KB per answer, and on a timeout the piece's whole process group
+ * is killed (after every run, not just a timeout), and at most MAX_RUNNING
+ * pieces run at once. Requests travel on stdin, never argv, so an action's
+ * field values (a secret typed into a form) stay out of `ps`.
+ *
+ * A piece is trusted code running as the same user as the daemon. It gets the
+ * daemon's env minus loom's own bearer tokens, but that's hygiene, not a
+ * boundary: a same-user process can read the daemon's environment from /proc.
+ * Install only pieces you'd trust with the daemon itself.
+ */
+import { spawn } from 'node:child_process';
+import { listPieces } from '../cli/pieces.js';
+import { parseActResult, parseManifest, parsePage } from './vocab.js';
+export const PIECE_TIMEOUT_MS = 3_000;
+export const ACT_TIMEOUT_MS = 15_000;
+export const PIECE_MAX_BYTES = 512 * 1024;
+/** Longer than the page's 30s refresh, so an open tab doesn't re-run every piece each time. */
+export const CACHE_MS = 45_000;
+/** After the piece exits, how long to wait for its stdout to close (a background helper may hold it). */
+const DRAIN_MS = 200;
+/** Env loom never hands to a piece. */
+const WITHHELD = ['LOOM_BEARER_TOKEN', 'LOOM_KNOWLEDGE_BEARER_TOKENS'];
+const cache = new Map();
+export function clearPieceCache(path) {
+    if (path === undefined)
+        cache.clear();
+    else
+        cache.delete(path);
+}
+export function pieceEnv(env) {
+    const out = { ...env };
+    for (const k of WITHHELD)
+        delete out[k];
+    return out;
+}
+function killGroup(pid) {
+    if (pid === undefined)
+        return;
+    try {
+        process.kill(-pid, 'SIGKILL');
+    }
+    catch { /* already gone */ }
+}
+/**
+ * At most this many piece processes at once, across every page load: a burst
+ * of requests queues instead of forking a process each. The time limit starts
+ * when a piece actually runs.
+ */
+export const MAX_RUNNING = 6;
+let running = 0;
+const waiting = [];
+async function slot(f) {
+    if (running >= MAX_RUNNING)
+        await new Promise((r) => waiting.push(r));
+    running++;
+    try {
+        return await f();
+    }
+    finally {
+        running--;
+        waiting.shift()?.();
+    }
+}
+function ask(path, args, env, opts = {}) {
+    return slot(() => run(path, args, env, opts));
+}
+function run(path, args, env, opts) {
+    return new Promise((resolve) => {
+        // Its own process group, so a timeout takes the piece's children with it.
+        const child = spawn(path, args, {
+            env: pieceEnv(env),
+            stdio: [opts.stdin === undefined ? 'ignore' : 'pipe', 'pipe', 'ignore'],
+            detached: true,
+        });
+        let out = '';
+        let bytes = 0;
+        let settled = false;
+        let drain;
+        const finish = (r) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (drain)
+                clearTimeout(drain);
+            child.stdout?.destroy();
+            // Every time, not only on a timeout: whatever the piece left running in
+            // its group goes with it. (A piece that calls setsid on purpose escapes.)
+            killGroup(child.pid);
+            resolve(r);
+        };
+        const timer = setTimeout(() => { killGroup(child.pid); finish({ ok: false, reason: 'timed out' }); }, opts.timeoutMs ?? PIECE_TIMEOUT_MS);
+        child.stdout?.on('data', (d) => {
+            bytes += d.length;
+            if (bytes > PIECE_MAX_BYTES) {
+                killGroup(child.pid);
+                finish({ ok: false, reason: 'answer too large' });
+                return;
+            }
+            out += d.toString('utf-8');
+        });
+        child.on('error', (e) => finish({ ok: false, reason: e.message }));
+        if (opts.stdin !== undefined && child.stdin) {
+            child.stdin.on('error', () => { });
+            child.stdin.end(opts.stdin);
+        }
+        // Resolve on the piece's own exit (plus a short drain), not on 'close':
+        // 'close' waits for every holder of the pipe, and a helper the piece left
+        // running would hold it open past the timeout.
+        child.on('exit', (code) => {
+            const done = () => finish(code === 0 ? { ok: true, stdout: out } : { ok: false, reason: 'no ui' });
+            if (child.stdout?.readableEnded)
+                return done();
+            child.stdout?.once('end', done);
+            drain = setTimeout(done, DRAIN_MS);
+        });
+    });
+}
+function json(stdout) {
+    try {
+        return JSON.parse(stdout);
+    }
+    catch {
+        return undefined;
+    }
+}
+async function fetchManifest(piece, path, env) {
+    const r = await ask(path, ['ui', '--json'], env);
+    if (!r.ok)
+        return { piece, reason: r.reason };
+    const parsed = json(r.stdout);
+    if (parsed === undefined)
+        return { piece, reason: 'invalid: not JSON' };
+    const m = parseManifest(parsed);
+    return typeof m === 'string' ? { piece, reason: `invalid: ${m}` } : { piece, path, manifest: m };
+}
+function manifestFor(piece, path, env, nowMs) {
+    const hit = cache.get(path);
+    if (hit && nowMs - hit.at < CACHE_MS)
+        return hit.result;
+    // Cache the promise itself: concurrent page loads share one run.
+    const result = fetchManifest(piece, path, env);
+    cache.set(path, { at: nowMs, result });
+    return result;
+}
+/** Every installed piece's manifest, plus the ones that had nothing to show and why. */
+export async function pieceManifests(env, nowMs = Date.now()) {
+    // "loom" is loom's own name on the page; a piece can't take it.
+    const installed = listPieces(env).filter((p) => p.name !== 'loom');
+    const results = await Promise.all(installed.map((p) => manifestFor(p.name, p.path, env, nowMs)));
+    const pieces = results.filter((r) => 'manifest' in r);
+    const empty = pieces.filter((p) => !p.manifest.tab && !p.manifest.tile && !p.manifest.asks.length && !p.manifest.legacy?.length);
+    return {
+        pieces: pieces.filter((p) => !empty.includes(p)),
+        skipped: [...results.filter((r) => 'reason' in r), ...empty.map((p) => ({ piece: p.piece, reason: 'nothing to show' }))],
+    };
+}
+/** One page from a piece, or why it couldn't be had. */
+export async function piecePage(info, path, query, env) {
+    // A first-version piece has one page: its sections.
+    if (info.manifest.legacy) {
+        return path === '' ? { title: info.piece, sections: info.manifest.legacy } : { title: 'Not found', sections: [] };
+    }
+    const r = await ask(info.path, ['ui', 'page', '--json'], env, { stdin: JSON.stringify({ path, query }) });
+    if (!r.ok)
+        return r.reason;
+    const parsed = json(r.stdout);
+    if (parsed === undefined)
+        return 'not JSON';
+    return parsePage(parsed);
+}
+/** Run an action on a piece. Field values go on stdin only. */
+export async function pieceAct(info, request, env) {
+    const r = await ask(info.path, ['ui', 'act', '--json'], env, { stdin: JSON.stringify(request), timeoutMs: ACT_TIMEOUT_MS });
+    // Whatever happened, the piece's state may have changed.
+    clearPieceCache(info.path);
+    if (!r.ok)
+        return { ok: false, message: `${info.piece} didn't answer (${r.reason}).` };
+    const parsed = json(r.stdout);
+    const result = parsed === undefined ? 'not JSON' : parseActResult(parsed);
+    return typeof result === 'string' ? { ok: false, message: `${info.piece} sent an answer loom couldn't read (${result}).` } : result;
+}

package/dist/ui/render.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Server-side HTML for loom's page. Every string that reaches the page goes
+ * through esc(): pieces send data in the page vocabulary, never markup. No
+ * client script anywhere; folding is <details>, filters are links, and every
+ * action is a plain form post carrying the anti-forgery token.
+ */
+import type { Ask, Page, Tile } from './vocab.js';
+export declare function esc(s: string): string;
+/** Whose page this is: loom's own (`loom`) or a piece's. */
+export interface Source {
+    id: string;
+    base: string;
+}
+export declare const CORE: Source;
+export declare const pieceSource: (piece: string) => Source;
+export interface RenderContext {
+    source: Source;
+    /** This page's path within its source, and its query, for filters and for returning after an action. */
+    path: string;
+    query: Record<string, string>;
+    csrf: string;
+}
+/** Where a page link goes. Pieces' links stay inside their own base unless they say `loom:`. */
+export declare function pageHref(link: string, source: Source): string;
+export interface Chrome {
+    agent: string;
+    nav: Array<{
+        label: string;
+        href: string;
+        current: boolean;
+        piece: boolean;
+    }>;
+    clock: string;
+    csrf: string;
+    /** The one-time result of an action; `from` names the piece that sent it. */
+    flash?: {
+        ok: boolean;
+        message: string;
+        from?: string;
+    };
+    skipped: string[];
+}
+/** One page, loom's or a piece's. */
+export declare function renderPage(page: Page, ctx: RenderContext, chrome: Chrome): string;
+export interface HomeTile extends Tile {
+    source: Source;
+}
+export interface HomeAsk extends Ask {
+    source: Source;
+}
+/** Home: tiles across the top, the tape as the page, "Your call" leading the side column. */
+export declare function renderHome(page: Page, ctx: RenderContext, chrome: Chrome, tiles: HomeTile[], asks: HomeAsk[]): string;
+export declare function renderLogin(error?: string): string;