@jbarket/loomai 0.6.0 → 0.8.0

package/CHANGELOG.md

@@ -12,6 +12,39 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.8.0] - 2026-10-24
+
+### Added
+
+- **loom's page: `/ui` on the HTTP daemon.** A read-only web page with loom's
+  own sections: top of mind, the last 24h of episodes, proposals waiting, and
+  people. It also gets a group for each installed piece that answers
+  `loom-<piece> ui --json` in a small section vocabulary (stats, list, table,
+  text, link). Pieces send data, never markup: everything is escaped, the page
+  has no script, and a CSP forbids script and framing. Invalid answers are
+  dropped whole, and a slow or missing piece is left out.
+  - **Login:** the bearer token, once. The page requires `LOOM_BEARER_TOKEN` (no
+    token gives 403, like `/cli`). The cookie is keyed per daemon process, isn't
+    the token, and lasts 30 days or until a restart. Pieces never see loom's
+    tokens; on a timeout their whole process group is killed; concurrent loads
+    share one run per piece.
+  - **`/ui/sections.json`:** the same data, for scripts.
+  - **Scope:** full scope only.
+
+## [0.7.0] - 2026-10-24
+
+### Added
+
+- **Pieces: `loom <piece>` dispatches to `loom-<piece>` on PATH, and `loom
+  pieces` lists them.** loom's command namespace now reaches separate,
+  swappable extensions (tasks, secrets, a wake clock, …) the way `git` reaches
+  `git-<cmd>`. loom never links them, and they never write loom's stores. Core
+  commands always win, piece names are validated before PATH is searched,
+  loom's env passes through unchanged, and the piece's exit code comes back.
+  The tiers, the rules (alone, composes without requiring, a contract per
+  role, no secrets in argv) and how pieces meet through named seams are in
+  `docs/extensions.md`.
+
 ## [0.6.0] - 2026-10-24
 
 ### Added
@@ -574,7 +607,9 @@ Initial public release.
   stack and all added external-service dependencies or operational
   overhead.
 
-[Unreleased]: https://github.com/sleepunit-agents/loom/compare/v0.6.0...HEAD
+[Unreleased]: https://github.com/sleepunit-agents/loom/compare/v0.8.0...HEAD
+[0.8.0]: https://github.com/sleepunit-agents/loom/compare/v0.7.0...v0.8.0
+[0.7.0]: https://github.com/sleepunit-agents/loom/compare/v0.6.0...v0.7.0
 [0.6.0]: https://github.com/sleepunit-agents/loom/compare/v0.5.0...v0.6.0
 [0.5.0]: https://github.com/sleepunit-agents/loom/compare/v0.4.1...v0.5.0
 [0.4.1]: https://github.com/sleepunit-agents/loom/compare/v0.3.1...v0.4.1

package/README.md

@@ -383,6 +383,26 @@ header, or a body that isn't `application/json`). The knowledge-only daemon
 has no `/cli`. Every other command (`doctor`, `inject`, `serve`, …) stays
 local, and `--url` on one of them is an error.
 
+### loom's page — `/ui`
+
+The full-scope daemon serves a read-only web page at `/ui`. It shows top of
+mind, the last 24h of episodes from every body, proposals waiting for
+ratification, and person cards with their freshness. Below that, it shows a
+group for each installed **piece** that answers `ui --json`: a chat bridge's
+live conversations, the task queue, and so on. Nothing to configure: install
+a piece and it shows up ([`docs/extensions.md`](docs/extensions.md), "UI
+sections").
+
+**The page needs `LOOM_BEARER_TOKEN`.** A daemon with no token serves none
+(403), the same rule as `/cli`, because any site that DNS-rebinds a name to
+the loopback address could read an open page. Log in once with the token. The
+browser keeps a cookie under a key the daemon made at start: it's not the
+token, it can't be replayed against `/mcp` or `/cli`, and it can't be used to
+guess the token. It lasts 30 days, or until the daemon restarts. Scripts can
+send the bearer header to `/ui/sections.json` for the same data. The page has
+no script and is served under a CSP that forbids script and framing. Pieces
+never receive loom's bearer tokens.
+
 ### Behind a reverse proxy
 
 Terminate TLS at a reverse proxy in front of the daemon and point the
@@ -593,6 +613,24 @@ loom migrate --dry-run   # check without applying
 loom migrate --json      # machine-readable output
 ```
 
+### Pieces — `loom tasks`, `loom secrets`, … as separate programs
+
+loom stays identity and memory. Everything else an agent leans on (tasks,
+secrets, a wake clock, an approval page) is a **piece**: its own program,
+reached through loom's command namespace the way `git` reaches `git-<cmd>`.
+`loom tasks list` runs the first `loom-tasks` on `PATH` with `list`, and
+passes back its exit code. Core commands can't be shadowed. Pieces never
+write loom's stores, work alone, and compose when others are installed. Each
+piece role has a contract, so an implementation can be swapped for another.
+
+```bash
+loom pieces            # what's installed (name → path)
+loom tasks ready       # → loom-tasks ready
+```
+
+The rules, the dispatch details and how pieces compose:
+[`docs/extensions.md`](docs/extensions.md).
+
 ### Harness manifests and self-describe
 
 A **harness** is the MCP-capable runtime the agent runs in (Claude Code,

package/dist/cli/index.js

@@ -9,6 +9,7 @@ import { realStreams } from './io.js';
 import { SUBCOMMANDS } from './subcommands.js';
 import { extractGlobalFlags, firstNonGlobalIndex } from './args.js';
 import { REMOTE_VERBS, runRemote } from './remote.js';
+import { findPiece, isPieceName, runPiece } from './pieces.js';
 const TOP_HELP = `Usage: loom <command> [options]
 
 Commands:
@@ -30,6 +31,10 @@ Commands:
   install           Write loom-setup skill into a harness's skills dir
   doctor            Probe the loom environment (read-only)
   migrate           Apply pending schema migrations to memories.db
+  pieces            List installed pieces (loom-<name> on PATH)
+
+Pieces: \`loom <name> ...\` runs an installed extension, loom-<name> on PATH
+(e.g. loom tasks list). Core commands always win. See docs/extensions.md.
 
 Global flags:
   --context-dir <path>   Agent context dir (default: $LOOM_CONTEXT_DIR or ~/.config/loom/default)
@@ -50,6 +55,19 @@ async function readVersion() {
     return pkg.version;
 }
 export async function runCli(argv, io = realStreams()) {
+    // A piece (docs/extensions.md): not a core command, and loom-<name> is on PATH.
+    const pieceIdx = firstNonGlobalIndex(argv);
+    const pieceName = argv[pieceIdx];
+    if (isPieceName(pieceName)) {
+        const path = findPiece(pieceName, io.env);
+        if (path) {
+            if (pieceIdx > 0) {
+                io.stderr(`loom: global flags (${argv.slice(0, pieceIdx).join(' ')}) don't apply to pieces; put the piece's own flags after its name.\n`);
+                return 2;
+            }
+            return runPiece(path, argv.slice(pieceIdx + 1), io);
+        }
+    }
     const resolved = await resolveSubcommand(argv, io);
     if (typeof resolved === 'number')
         return resolved;
@@ -101,6 +119,8 @@ async function resolveSubcommand(argv, io) {
     }
     if (!SUBCOMMANDS.includes(first)) {
         io.stderr(`Unknown subcommand: ${first}\n`);
+        if (isPieceName(first))
+            io.stderr(`(no piece installed either: nothing named loom-${first} on PATH; \`loom pieces\` lists what is)\n`);
         io.stderr(TOP_HELP);
         return 2;
     }
@@ -174,6 +194,10 @@ async function dispatch(sub, rest, io) {
             const { run } = await import('./migrate.js');
             return run(rest, io);
         }
+        case 'pieces': {
+            const { runPiecesCommand } = await import('./pieces.js');
+            return runPiecesCommand(rest, io);
+        }
         default:
             io.stderr(`Subcommand not implemented yet: ${sub}\n`);
             return 2;

package/dist/cli/pieces.d.ts

@@ -0,0 +1,24 @@
+import type { IOStreams } from './io.js';
+/** A piece name: lowercase, starts with a letter, no dots or slashes. */
+export declare const PIECE_NAME: RegExp;
+/** Whether `name` could be a piece (valid name, not a core subcommand). */
+export declare function isPieceName(name: string | undefined): name is string;
+/** The executable that answers `loom <name>`: the first `loom-<name>` on PATH. */
+export declare function findPiece(name: string, env: NodeJS.ProcessEnv): string | undefined;
+export interface InstalledPiece {
+    name: string;
+    path: string;
+}
+/** Every installed piece, first on PATH wins (the one `loom <name>` would run). */
+export declare function listPieces(env: NodeJS.ProcessEnv): InstalledPiece[];
+/**
+ * Run a piece with `args`, passing loom's env through unchanged. With the
+ * process's own streams the piece inherits the terminal (so it can prompt,
+ * e.g. for a secret's value); with captured streams (tests) its output is
+ * forwarded. Exit code: the piece's own, 128+signal if it was killed, 127 if
+ * it couldn't start.
+ */
+export declare function runPiece(path: string, args: string[], io: IOStreams): Promise<number>;
+/** `loom pieces`: list what's installed. */
+export declare function runPiecesCommand(argv: string[], io: IOStreams): number;
+export declare const PIECES_USAGE = "Usage: loom pieces [--json]\n\nList the installed pieces: every executable named loom-<name> on PATH, which\nanswers `loom <name> ...`. The first one on PATH wins; core commands can't be\nshadowed. See docs/extensions.md.\n";

package/dist/cli/pieces.js

@@ -0,0 +1,139 @@
+/**
+ * Pieces — `loom <piece> ...` runs the installed extension `loom-<piece>`
+ * (docs/extensions.md, t-1466).
+ *
+ * Git-style dispatch: an executable named `loom-tasks` on PATH answers
+ * `loom tasks list`. loom doesn't know what a piece does and never links its
+ * code: the piece is its own program, reached as its own process, so it can't
+ * reach into loom's stores and can be swapped for anything else that installs
+ * the same name and honors that piece's contract.
+ *
+ * Core subcommands always win (a `loom-recall` on PATH is never consulted),
+ * and a name must match PIECE_NAME before PATH is searched at all.
+ */
+import { accessSync, constants, readdirSync, statSync } from 'node:fs';
+import { delimiter, join } from 'node:path';
+import { spawn } from 'node:child_process';
+import { constants as osConstants } from 'node:os';
+import { SUBCOMMANDS } from './subcommands.js';
+/** A piece name: lowercase, starts with a letter, no dots or slashes. */
+export const PIECE_NAME = /^[a-z][a-z0-9-]{0,39}$/;
+const PREFIX = 'loom-';
+const CORE = new Set(SUBCOMMANDS);
+function isExecutableFile(path) {
+    try {
+        if (!statSync(path).isFile())
+            return false;
+        accessSync(path, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function pathDirs(env) {
+    return (env.PATH ?? '').split(delimiter).filter(Boolean);
+}
+/** Whether `name` could be a piece (valid name, not a core subcommand). */
+export function isPieceName(name) {
+    return name !== undefined && PIECE_NAME.test(name) && !CORE.has(name);
+}
+/** The executable that answers `loom <name>`: the first `loom-<name>` on PATH. */
+export function findPiece(name, env) {
+    if (!isPieceName(name))
+        return undefined;
+    for (const dir of pathDirs(env)) {
+        const candidate = join(dir, PREFIX + name);
+        if (isExecutableFile(candidate))
+            return candidate;
+    }
+    return undefined;
+}
+/** Every installed piece, first on PATH wins (the one `loom <name>` would run). */
+export function listPieces(env) {
+    const seen = new Map();
+    for (const dir of pathDirs(env)) {
+        let entries;
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries.sort()) {
+            if (!entry.startsWith(PREFIX))
+                continue;
+            const name = entry.slice(PREFIX.length);
+            if (seen.has(name) || !isPieceName(name))
+                continue;
+            const path = join(dir, entry);
+            if (isExecutableFile(path))
+                seen.set(name, path);
+        }
+    }
+    return [...seen].map(([name, path]) => ({ name, path })).sort((a, b) => a.name.localeCompare(b.name));
+}
+/**
+ * Run a piece with `args`, passing loom's env through unchanged. With the
+ * process's own streams the piece inherits the terminal (so it can prompt,
+ * e.g. for a secret's value); with captured streams (tests) its output is
+ * forwarded. Exit code: the piece's own, 128+signal if it was killed, 127 if
+ * it couldn't start.
+ */
+export async function runPiece(path, args, io) {
+    const inherit = io.stdin === process.stdin;
+    const child = spawn(path, args, {
+        env: io.env,
+        stdio: inherit ? 'inherit' : ['pipe', 'pipe', 'pipe'],
+    });
+    if (!inherit) {
+        child.stdout?.on('data', (d) => io.stdout(d.toString()));
+        child.stderr?.on('data', (d) => io.stderr(d.toString()));
+        if (child.stdin) {
+            if (io.stdinIsTTY)
+                child.stdin.end();
+            else
+                io.stdin.pipe(child.stdin);
+        }
+    }
+    return new Promise((resolve) => {
+        child.on('error', (err) => {
+            io.stderr(`loom: couldn't run ${path}: ${err.message}\n`);
+            resolve(127);
+        });
+        child.on('close', (code, signal) => {
+            if (signal)
+                resolve(128 + (osConstants.signals[signal] ?? 0));
+            else
+                resolve(code ?? 1);
+        });
+    });
+}
+/** `loom pieces`: list what's installed. */
+export function runPiecesCommand(argv, io) {
+    const json = argv.includes('--json');
+    const rest = argv.filter((a) => a !== '--json');
+    if (rest.includes('--help') || rest.includes('-h')) {
+        io.stdout(PIECES_USAGE);
+        return 0;
+    }
+    if (rest.length) {
+        io.stderr(`loom pieces takes no arguments.\n${PIECES_USAGE}`);
+        return 2;
+    }
+    const pieces = listPieces(io.env);
+    if (json) {
+        io.stdout(JSON.stringify(pieces, null, 2) + '\n');
+        return 0;
+    }
+    io.stdout(pieces.length === 0
+        ? 'no pieces installed (a piece is an executable named loom-<name> on PATH)\n'
+        : pieces.map((p) => `${p.name}\t${p.path}`).join('\n') + '\n');
+    return 0;
+}
+export const PIECES_USAGE = `Usage: loom pieces [--json]
+
+List the installed pieces: every executable named loom-<name> on PATH, which
+answers \`loom <name> ...\`. The first one on PATH wins; core commands can't be
+shadowed. See docs/extensions.md.
+`;

package/dist/cli/subcommands.d.ts

@@ -3,5 +3,5 @@
  * (src/cli/index.ts) and the CLI-vs-MCP routing gate (src/index.ts) so
  * the set never drifts between entry points.
  */
-export declare const SUBCOMMANDS: readonly ['wake', 'recall', 'remember', 'forget', 'update', 'memory', 'knowledge', 'person', 'update-identity', 'bootstrap', 'serve', 'inject', 'harness', 'install', 'doctor', 'migrate'];
+export declare const SUBCOMMANDS: readonly ['wake', 'recall', 'remember', 'forget', 'update', 'memory', 'knowledge', 'person', 'update-identity', 'bootstrap', 'serve', 'inject', 'harness', 'install', 'doctor', 'migrate', 'pieces'];
 export type Subcommand = typeof SUBCOMMANDS[number];

package/dist/cli/subcommands.js

@@ -7,5 +7,5 @@ export const SUBCOMMANDS = [
     'wake', 'recall', 'remember', 'forget', 'update',
     'memory', 'knowledge', 'person', 'update-identity', 'bootstrap', 'serve',
     'inject', 'harness',
-    'install', 'doctor', 'migrate',
+    'install', 'doctor', 'migrate', 'pieces',
 ];

package/dist/index.js

@@ -27,6 +27,7 @@ import { createLoomServer } from './server.js';
 import { resolveContextDir } from './config.js';
 import { SUBCOMMANDS } from './cli/subcommands.js';
 import { firstNonGlobalIndex } from './cli/args.js';
+import { findPiece } from './cli/pieces.js';
 const CLI_KEYWORDS = new Set(SUBCOMMANDS);
 function isCliInvocation(argv) {
     const args = argv.slice(2);
@@ -37,7 +38,11 @@ function isCliInvocation(argv) {
         return true;
     if (first === '--version' || first === '-V')
         return true;
-    return CLI_KEYWORDS.has(first);
+    if (CLI_KEYWORDS.has(first))
+        return true;
+    // An installed piece (loom-<first> on PATH) is a CLI call too. Anything else
+    // still falls through to the stdio server, exactly as before.
+    return findPiece(first, process.env) !== undefined;
 }
 export { isCliInvocation };
 async function main() {

package/dist/transport/http-server.js

@@ -32,6 +32,7 @@ import { EmptyResultSchema } from '@modelcontextprotocol/core';
 import { createLoomServer } from '../server.js';
 import { createBackend } from '../backends/index.js';
 import { handleCliBody } from './cli-endpoint.js';
+import { handleUi, isUiPath } from '../ui/handler.js';
 import { assertSafeBind, checkBearer, checkBearerMulti, checkPayloadSize, DEFAULT_MAX_BODY_BYTES, } from './guards.js';
 /**
  * SSE keep-alive: the SDK opens the standalone GET stream but sends no
@@ -196,6 +197,19 @@ export async function startHttpServer(opts) {
     }
     const http = createServer((req, res) => {
         void (async () => {
+            // /ui: loom's web page (src/ui). Its own auth (a cookie from the bearer,
+            // or the bearer header), so it comes before the bearer gate. Full scope
+            // only: a scoped server has no memory to show.
+            const uiPath = new URL(req.url ?? '/', 'http://localhost').pathname;
+            if (isUiPath(uiPath)) {
+                if (opts.createServer)
+                    return sendError(res, 404, 'not-found: this server has no UI');
+                return handleUi(req, res, uiPath, {
+                    contextDir: opts.contextDir,
+                    secrets: opts.token ? [opts.token] : Object.values(opts.tokens ?? {}),
+                    env: process.env,
+                });
+            }
             // Auth gate (ac-lt-auth-gate): reject unauthenticated when a token (or
             // token map) is configured. Multi-token mode additionally resolves
             // WHICH identity made this call — the bearer itself is the identity

package/dist/ui/core.d.ts

@@ -0,0 +1,9 @@
+import type { Section } from './sections.js';
+/** loom's zone (LOOM_TIMEZONE, then TZ), and one that Intl accepts: a bad value never breaks the page. */
+export declare function uiTimeZone(): string;
+/** The agent's name: IDENTITY.md's first heading, else the context dir's name. */
+export declare function agentName(contextDir: string): string;
+export declare function coreSections(contextDir: string, opts?: {
+    timeZone?: string;
+    nowMs?: number;
+}): Section[];

package/dist/ui/core.js

@@ -0,0 +1,140 @@
+/**
+ * loom's own sections for the UI: what only loom knows. Read-only views over
+ * the stores (top of mind, the episode tape, pending proposals, people),
+ * assembled from the same functions the identity payload and the MCP-App
+ * widgets use. Nothing here writes.
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { digestData } from '../backends/salience.js';
+import { episodeRows, tapeClock } from '../backends/episodes.js';
+import { listProposals } from '../backends/proposals.js';
+import { listPeople } from '../tools/person.js';
+const TOP_OF_MIND = 12;
+const TAPE_HOURS = 24;
+const TAPE_SHOWN = 20;
+function whereOf(metadata, project) {
+    try {
+        const meta = JSON.parse(metadata || '{}');
+        if (typeof meta.where === 'string' && meta.where.trim())
+            return meta.where.trim();
+    }
+    catch { /* fall through */ }
+    return project?.trim() || '?';
+}
+/** loom's zone (LOOM_TIMEZONE, then TZ), and one that Intl accepts: a bad value never breaks the page. */
+export function uiTimeZone() {
+    for (const z of [process.env.LOOM_TIMEZONE, process.env.TZ, 'America/Chicago']) {
+        if (!z)
+            continue;
+        try {
+            new Intl.DateTimeFormat('en-US', { timeZone: z });
+            return z;
+        }
+        catch { /* next */ }
+    }
+    return 'UTC';
+}
+function tierTone(tier) {
+    return tier === 'cold' ? 'muted' : undefined;
+}
+/** The agent's name: IDENTITY.md's first heading, else the context dir's name. */
+export function agentName(contextDir) {
+    try {
+        const line = readFileSync(join(contextDir, 'IDENTITY.md'), 'utf-8').split('\n').find((l) => /^#\s+\S/.test(l));
+        if (line)
+            return line.replace(/^#\s+/, '').trim();
+    }
+    catch { /* no identity file */ }
+    return contextDir.split('/').filter(Boolean).pop() ?? 'loom';
+}
+export function coreSections(contextDir, opts = {}) {
+    const timeZone = opts.timeZone ?? uiTimeZone();
+    const digest = digestData(contextDir, TOP_OF_MIND);
+    const episodes = episodeRows(contextDir, { hours: TAPE_HOURS, nowMs: opts.nowMs });
+    const pending = listProposals(contextDir).filter((p) => p.status === 'pending');
+    const people = listPeople(contextDir);
+    const sections = [
+        {
+            id: 'overview',
+            title: 'Overview',
+            blocks: [{
+                    type: 'stats',
+                    items: [
+                        { label: 'memories', value: String(digest?.total ?? 0) },
+                        { label: `episodes, last ${TAPE_HOURS}h`, value: String(episodes.length) },
+                        { label: 'proposals pending', value: String(pending.length), tone: pending.length ? 'warn' : undefined },
+                        { label: 'people', value: String(people.length) },
+                    ],
+                }],
+        },
+        {
+            id: 'tape',
+            title: `Last ${TAPE_HOURS}h`,
+            blocks: episodes.length
+                ? [
+                    {
+                        type: 'list',
+                        items: [...episodes].reverse().slice(0, TAPE_SHOWN).map((e) => ({
+                            text: e.title,
+                            meta: `${tapeClock(e.created, timeZone)} · ${whereOf(e.metadata, e.project)}`,
+                        })),
+                    },
+                    ...(episodes.length > TAPE_SHOWN
+                        ? [{ type: 'text', text: `and ${episodes.length - TAPE_SHOWN} earlier` }]
+                        : []),
+                ]
+                : [{ type: 'text', text: 'No episodes in the last day.' }],
+        },
+        {
+            id: 'top-of-mind',
+            title: 'Top of mind',
+            blocks: digest && digest.atoms.length
+                ? [{
+                        type: 'list',
+                        items: digest.atoms.map((a) => ({ text: a.title, meta: `${a.category} · ${a.tier}`, tone: tierTone(a.tier) })),
+                    }]
+                : [{ type: 'text', text: 'Nothing hot yet.' }],
+        },
+    ];
+    if (pending.length) {
+        sections.push({
+            id: 'proposals',
+            title: 'Proposals waiting',
+            blocks: [{
+                    type: 'list',
+                    items: pending.map((p) => ({
+                        text: p.title ?? '(untitled)',
+                        meta: `#${p.id} · ${p.category ?? '?'}${p.source ? ` · ${p.source}` : ''}`,
+                        tone: 'warn',
+                    })),
+                }],
+        });
+    }
+    if (people.length) {
+        // Only the cards that need a look: stale or unverified fields, or memories
+        // written since the summary was last synthesized.
+        const attention = people.filter((p) => p.stale || p.unverified || p.memories_since_synthesis);
+        sections.push({
+            id: 'people',
+            title: 'People',
+            blocks: [
+                {
+                    type: 'stats',
+                    items: [
+                        { label: 'cards', value: String(people.length) },
+                        { label: 'need a look', value: String(attention.length), tone: attention.length ? 'warn' : 'ok' },
+                    ],
+                },
+                attention.length
+                    ? {
+                        type: 'table',
+                        columns: ['name', 'stale', 'unverified', 'new memories'],
+                        rows: attention.map((p) => [p.name, String(p.stale), String(p.unverified), String(p.memories_since_synthesis)]),
+                    }
+                    : { type: 'text', text: 'Every card is fresh.' },
+            ],
+        });
+    }
+    return sections;
+}

package/dist/ui/handler.d.ts

@@ -0,0 +1,11 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+export interface UiOptions {
+    contextDir: string;
+    /** Configured bearer secrets (the single token, or the token map's values). Empty = open. */
+    secrets: string[];
+    /** Env for piece discovery and piece processes (PATH decides which pieces exist). */
+    env: NodeJS.ProcessEnv;
+}
+export declare function isUiPath(pathname: string): boolean;
+/** Handle a /ui request. The caller has already matched isUiPath. */
+export declare function handleUi(req: IncomingMessage, res: ServerResponse, pathname: string, opts: UiOptions): Promise<void>;

package/dist/ui/handler.js

@@ -0,0 +1,159 @@
+/**
+ * loom's web UI on the HTTP daemon (full scope only): GET /ui, the page;
+ * GET /ui/sections.json, the same sections as data; /ui/login and /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. The cookie is `<issued-at>.<mac>`, a MAC under
+ * a key this process made at start, over the issued-at time and a digest of
+ * the token. 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 offline. It lasts 30 days,
+ * or until the daemon restarts (log in again). Scripts can send the bearer
+ * header instead. The page is read-only, has no script, and is served under a
+ * CSP that forbids script and framing.
+ */
+import { createHash, createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+import { checkBearer } from '../transport/guards.js';
+import { agentName, coreSections, uiTimeZone } from './core.js';
+import { pieceSections } from './piece-sections.js';
+import { renderLogin, renderPage } from './render.js';
+const COOKIE = 'loom_ui';
+const LOGIN_MAX_BYTES = 4096;
+const COOKIE_MAX_AGE_S = 30 * 24 * 3600;
+/** 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();
+function mac(issuedAt, secret) {
+    return createHmac('sha256', COOKIE_KEY).update(`loom-ui-v2|${issuedAt}|`).update(digest(secret)).digest('hex');
+}
+function cookieValue(secret, issuedAt = Math.floor(Date.now() / 1000)) {
+    return `${issuedAt}.${mac(issuedAt, secret)}`;
+}
+/** 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 validCookie(value, secrets, nowS = Math.floor(Date.now() / 1000)) {
+    const m = /^(\d{1,12})\.([0-9a-f]{64})$/.exec(value);
+    if (!m)
+        return false;
+    const issuedAt = Number(m[1]);
+    if (issuedAt > nowS + 60 || nowS - issuedAt > COOKIE_MAX_AGE_S)
+        return false;
+    return secrets.some((s) => safeEq(m[2], mac(issuedAt, s)));
+}
+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 authorized(req, opts) {
+    if (opts.secrets.length === 0)
+        return false;
+    const c = readCookie(req, COOKIE);
+    if (c && validCookie(c, opts.secrets))
+        return true;
+    const header = req.headers['authorization'];
+    return header !== undefined && opts.secrets.some((s) => checkBearer(s, header).ok);
+}
+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) {
+    return new Promise((resolve) => {
+        let body = '';
+        let done = false;
+        const finish = (v) => { if (!done) {
+            done = true;
+            resolve(v);
+        } };
+        req.on('data', (d) => {
+            if (done)
+                return;
+            body += d.toString('utf-8');
+            if (body.length > LOGIN_MAX_BYTES) {
+                finish(null);
+                req.destroy();
+            }
+        });
+        req.on('end', () => finish(new URLSearchParams(body)));
+        req.on('error', () => finish(null));
+        req.on('close', () => finish(null));
+    });
+}
+async function sections(opts) {
+    const core = coreSections(opts.contextDir);
+    const { contributed, skipped } = await pieceSections(opts.env);
+    return { core, pieces: contributed, skipped };
+}
+/** 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');
+        const form = await readForm(req);
+        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}=${cookieValue(match)}; Path=/ui; HttpOnly; SameSite=Strict; Max-Age=${COOKIE_MAX_AGE_S}${secure ? '; Secure' : ''}`,
+        });
+    }
+    if (pathname === '/ui/logout') {
+        if (req.method !== 'POST')
+            return send(res, 405, 'text/plain', 'method not allowed');
+        return redirect(res, '/ui/login', { 'set-cookie': `${COOKIE}=; Path=/ui; HttpOnly; SameSite=Strict; Max-Age=0` });
+    }
+    const agent = agentName(opts.contextDir);
+    if (req.method !== 'GET')
+        return send(res, 405, 'text/plain', 'method not allowed');
+    if (pathname === '/ui/sections.json') {
+        if (!authorized(req, opts))
+            return send(res, 401, 'application/json', JSON.stringify({ error: 'unauthorized' }));
+        const s = await sections(opts);
+        return send(res, 200, 'application/json', JSON.stringify({ agent, ...s }));
+    }
+    if (pathname === '/ui' || pathname === '/ui/') {
+        if (!authorized(req, opts))
+            return redirect(res, '/ui/login');
+        const s = await sections(opts);
+        return send(res, 200, 'text/html; charset=utf-8', renderPage({
+            agent,
+            core: s.core,
+            pieces: s.pieces,
+            skipped: s.skipped,
+            generatedAt: new Date().toLocaleTimeString('en-US', { timeZone: uiTimeZone(), hour: '2-digit', minute: '2-digit' }),
+        }));
+    }
+    return send(res, 404, 'text/plain', 'not found');
+}

package/dist/ui/piece-sections.d.ts

@@ -0,0 +1,20 @@
+import { type Section } from './sections.js';
+export declare const PIECE_TIMEOUT_MS = 3000;
+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 PieceSections {
+    piece: string;
+    sections: Section[];
+}
+/** 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(): void;
+export declare function pieceEnv(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+export declare function pieceSections(env: NodeJS.ProcessEnv, nowMs?: number): Promise<{
+    contributed: PieceSections[];
+    skipped: PieceSkip[];
+}>;

package/dist/ui/piece-sections.js

@@ -0,0 +1,112 @@
+/**
+ * Sections from installed pieces: each `loom-<piece>` on PATH is asked
+ * `ui --json`. A piece that answers with valid sections shows up on loom's
+ * page with no configuration; one that doesn't (no `ui` verb, a timeout, bad
+ * JSON) simply isn't there. Composes without requiring (docs/extensions.md).
+ *
+ * Bounded on every axis: one run per piece per cache window however many
+ * pages load at once (the in-flight promise is what's cached), 3s and 512KB
+ * per answer, and on a timeout the piece's whole process group is killed, not
+ * just its first process. A piece gets the daemon's env minus loom's own
+ * bearer tokens.
+ */
+import { spawn } from 'node:child_process';
+import { listPieces } from '../cli/pieces.js';
+import { parseSections } from './sections.js';
+export const PIECE_TIMEOUT_MS = 3_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() { cache.clear(); }
+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 */ }
+}
+function ask(path, env) {
+    return new Promise((resolve) => {
+        // Its own process group, so a timeout takes the piece's children with it.
+        const child = spawn(path, ['ui', '--json'], { env: pieceEnv(env), stdio: ['ignore', '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();
+            resolve(r);
+        };
+        const timer = setTimeout(() => { killGroup(child.pid); finish({ ok: false, reason: 'timed out' }); }, 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 }));
+        // 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);
+        });
+    });
+}
+async function run(name, path, env) {
+    const r = await ask(path, env);
+    if (!r.ok)
+        return { piece: name, reason: r.reason };
+    let parsed;
+    try {
+        parsed = JSON.parse(r.stdout);
+    }
+    catch {
+        return { piece: name, reason: 'invalid: not JSON' };
+    }
+    const sections = parseSections(parsed);
+    return typeof sections === 'string' ? { piece: name, reason: `invalid: ${sections}` } : { piece: name, sections };
+}
+function sectionsFor(name, 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 = run(name, path, env);
+    cache.set(path, { at: nowMs, result });
+    return result;
+}
+export async function pieceSections(env, nowMs = Date.now()) {
+    // "loom" is the core group's name on the page; a piece can't take it.
+    const pieces = listPieces(env).filter((p) => p.name !== 'loom');
+    const results = await Promise.all(pieces.map((p) => sectionsFor(p.name, p.path, env, nowMs)));
+    return {
+        contributed: results.filter((r) => 'sections' in r && r.sections.length > 0),
+        skipped: results.filter((r) => 'reason' in r),
+    };
+}

package/dist/ui/render.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Server-side HTML for loom's page. Every string that reaches the page goes
+ * through esc(): pieces send data in the section vocabulary, never markup.
+ * No client script; the page refreshes itself.
+ */
+import type { Section } from './sections.js';
+import type { PieceSections, PieceSkip } from './piece-sections.js';
+export declare function esc(s: string): string;
+export declare function renderPage(opts: {
+    agent: string;
+    core: Section[];
+    pieces: PieceSections[];
+    skipped: PieceSkip[];
+    generatedAt: string;
+}): string;
+export declare function renderLogin(error?: string): string;

package/dist/ui/render.js

@@ -0,0 +1,70 @@
+export function esc(s) {
+    return s
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}
+const toneClass = (t) => (t ? ` tone-${t}` : '');
+function renderBlock(b) {
+    switch (b.type) {
+        case 'stats':
+            return `<dl class="stats">${b.items
+                .map((i) => `<div class="stat${toneClass(i.tone)}"><dt>${esc(i.label)}</dt><dd>${esc(i.value)}</dd></div>`)
+                .join('')}</dl>`;
+        case 'list':
+            return `<ul class="list">${b.items
+                .map((i) => `<li class="${toneClass(i.tone).trim()}"><span class="text">${esc(i.text)}</span>${i.meta ? `<span class="meta">${esc(i.meta)}</span>` : ''}</li>`)
+                .join('')}</ul>`;
+        case 'table':
+            return `<div class="table-wrap"><table><thead><tr>${b.columns.map((c) => `<th>${esc(c)}</th>`).join('')}</tr></thead><tbody>${b.rows
+                .map((r) => `<tr>${r.map((c) => `<td>${esc(c)}</td>`).join('')}</tr>`)
+                .join('')}</tbody></table></div>`;
+        case 'text':
+            return `<p class="text-block">${esc(b.text)}</p>`;
+        case 'link':
+            return `<p><a href="${esc(b.href)}" rel="noopener noreferrer">${esc(b.text)}</a></p>`;
+    }
+}
+// Ids are namespaced (g- groups, s-<source>--<id> sections) so no piece's
+// anchors can land on another's or on loom's.
+function renderSection(s, source) {
+    return `<section class="card" id="s-${esc(source)}--${esc(s.id)}"><h2>${esc(s.title)}</h2>${s.blocks.map(renderBlock).join('')}</section>`;
+}
+const STYLE = `
+:root{--bg:#f7f7f5;--card:#fff;--fg:#1d1d1b;--muted:#6b6b66;--line:#e4e4df;--accent:#3b5bdb;--ok:#2b8a3e;--warn:#b26a00;--bad:#c92a2a;color-scheme:light}
+@media (prefers-color-scheme:dark){:root:not([data-theme="light"]){--bg:#141413;--card:#1e1e1c;--fg:#ececea;--muted:#9a9a94;--line:#2e2e2b;--accent:#8ca2ff;--ok:#69db7c;--warn:#ffc078;--bad:#ff8787;color-scheme:dark}}
+*{box-sizing:border-box}body{margin:0;background:var(--bg);color:var(--fg);font:15px/1.45 system-ui,-apple-system,"Segoe UI",sans-serif}
+header{padding:14px 16px 0;max-width:1100px;margin:0 auto}header h1{margin:0;font-size:18px;font-weight:600}header .sub{color:var(--muted);font-size:13px}
+nav{display:flex;gap:4px;overflow-x:auto;padding:10px 16px;max-width:1100px;margin:0 auto;border-bottom:1px solid var(--line)}
+nav a{color:var(--muted);text-decoration:none;padding:6px 10px;border-radius:8px;white-space:nowrap;font-size:14px}nav a:hover{background:var(--card);color:var(--fg)}
+main{max-width:1100px;margin:0 auto;padding:16px}.group{margin-bottom:24px}.group>h2.source{font-size:13px;text-transform:uppercase;letter-spacing:.06em;color:var(--muted);margin:0 0 8px}
+.grid{display:grid;gap:12px;align-items:start;grid-template-columns:repeat(auto-fill,minmax(min(100%,340px),1fr))}
+.card{background:var(--card);border:1px solid var(--line);border-radius:12px;padding:14px;min-width:0}.card h2{margin:0 0 10px;font-size:15px}
+.stats{display:flex;flex-wrap:wrap;gap:16px;margin:0}.stat dt{color:var(--muted);font-size:12px}.stat dd{margin:0;font-size:22px;font-weight:600;font-variant-numeric:tabular-nums}
+.list{list-style:none;margin:0;padding:0}.list li{padding:6px 0;border-top:1px solid var(--line);display:flex;flex-direction:column;gap:2px}.list li:first-child{border-top:0}
+.list .meta{color:var(--muted);font-size:12px}.text-block{margin:0;color:var(--muted)}
+.table-wrap{overflow-x:auto}table{border-collapse:collapse;width:100%;font-size:13px}th,td{text-align:left;padding:5px 6px;border-top:1px solid var(--line)}th{color:var(--muted);font-weight:500;border-top:0}
+.tone-ok dd,.tone-ok .text{color:var(--ok)}.tone-warn dd,.tone-warn .text{color:var(--warn)}.tone-bad dd,.tone-bad .text{color:var(--bad)}.tone-muted dd,.tone-muted .text{color:var(--muted)}
+a{color:var(--accent)}footer{max-width:1100px;margin:0 auto;padding:0 16px 24px;color:var(--muted);font-size:12px}
+form.login{max-width:360px;margin:48px auto;padding:16px}form.login input{width:100%;padding:10px;border:1px solid var(--line);border-radius:8px;background:var(--card);color:var(--fg);font:inherit}
+form.inline{display:inline}form.inline button{background:none;border:0;padding:0;color:var(--accent);font:inherit;cursor:pointer;text-decoration:underline}
+form.login button{margin-top:10px;padding:9px 14px;border:0;border-radius:8px;background:var(--accent);color:#fff;font:inherit}.err{color:var(--bad)}
+`;
+function shell(title, body, refresh) {
+    return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">${refresh ? '<meta http-equiv="refresh" content="30">' : ''}<title>${esc(title)}</title><style>${STYLE}</style></head><body>${body}</body></html>`;
+}
+export function renderPage(opts) {
+    const groups = [{ source: 'loom', sections: opts.core }, ...opts.pieces.map((p) => ({ source: p.piece, sections: p.sections }))];
+    const nav = groups.map((g) => `<a href="#g-${esc(g.source)}">${esc(g.source)}</a>`).join('');
+    const main = groups
+        .map((g) => `<div class="group" id="g-${esc(g.source)}"><h2 class="source">${esc(g.source)}</h2><div class="grid">${g.sections.map((s) => renderSection(s, g.source)).join('')}</div></div>`)
+        .join('');
+    const quiet = opts.skipped.length ? ` · pieces with no page: ${opts.skipped.map((s) => esc(s.piece)).join(', ')}` : '';
+    return shell(`${opts.agent} · loom`, `<header><h1>${esc(opts.agent)}</h1><div class="sub">loom</div></header><nav>${nav}</nav><main>${main}</main>` +
+        `<footer>Updated ${esc(opts.generatedAt)} · refreshes every 30s${quiet} · <form class="inline" method="post" action="/ui/logout"><button type="submit">log out</button></form></footer>`, true);
+}
+export function renderLogin(error) {
+    return shell('loom', `<form class="login" method="post" action="/ui/login"><h1>loom</h1><p class="sub">Paste the bearer token once. This browser keeps a cookie (until the daemon restarts, or 30 days).</p>${error ? `<p class="err">${esc(error)}</p>` : ''}<input type="password" name="token" autocomplete="current-password" autofocus aria-label="token"><button type="submit">Open</button></form>`, false);
+}

package/dist/ui/sections.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The UI section vocabulary (docs/extensions.md, "UI sections").
+ *
+ * loom's page is built from sections, both its own and the installed pieces'.
+ * A piece contributes by answering `loom-<piece> ui --json` with
+ * `{ "sections": [...] }` in this vocabulary. Pieces send data, never markup:
+ * loom renders every block itself and escapes every string, so a piece can't
+ * put HTML or script on loom's page. Anything that doesn't validate is dropped
+ * whole (a piece that sends garbage just isn't shown), never half-rendered.
+ */
+export type Tone = 'ok' | 'warn' | 'bad' | 'muted';
+export type Block = {
+    type: 'stats';
+    items: Array<{
+        label: string;
+        value: string;
+        tone?: Tone;
+    }>;
+} | {
+    type: 'list';
+    items: Array<{
+        text: string;
+        meta?: string;
+        tone?: Tone;
+    }>;
+} | {
+    type: 'table';
+    columns: string[];
+    rows: string[][];
+} | {
+    type: 'text';
+    text: string;
+} | {
+    type: 'link';
+    text: string;
+    href: string;
+};
+export interface Section {
+    id: string;
+    title: string;
+    blocks: Block[];
+}
+export declare const LIMITS: {
+    readonly sections: 10;
+    readonly blocks: 20;
+    readonly items: 200;
+    readonly columns: 12;
+    readonly string: 2000;
+};
+/** Validate a piece's `ui --json` answer. Returns the sections, or why it was refused. */
+export declare function parseSections(value: unknown): Section[] | string;

package/dist/ui/sections.js

@@ -0,0 +1,121 @@
+/**
+ * The UI section vocabulary (docs/extensions.md, "UI sections").
+ *
+ * loom's page is built from sections, both its own and the installed pieces'.
+ * A piece contributes by answering `loom-<piece> ui --json` with
+ * `{ "sections": [...] }` in this vocabulary. Pieces send data, never markup:
+ * loom renders every block itself and escapes every string, so a piece can't
+ * put HTML or script on loom's page. Anything that doesn't validate is dropped
+ * whole (a piece that sends garbage just isn't shown), never half-rendered.
+ */
+export const LIMITS = {
+    sections: 10,
+    blocks: 20,
+    items: 200,
+    columns: 12,
+    string: 2000,
+};
+const TONES = new Set(['ok', 'warn', 'bad', 'muted']);
+const ID = /^[a-z][a-z0-9-]{0,39}$/;
+class Invalid extends Error {
+}
+function str(v, what) {
+    if (typeof v === 'number' && Number.isFinite(v))
+        return String(v);
+    if (typeof v !== 'string')
+        throw new Invalid(`${what} must be a string`);
+    if (v.length > LIMITS.string)
+        throw new Invalid(`${what} is longer than ${LIMITS.string}`);
+    return v;
+}
+function optStr(v, what) {
+    return v === undefined ? undefined : str(v, what);
+}
+function tone(v) {
+    if (v === undefined)
+        return undefined;
+    if (typeof v !== 'string' || !TONES.has(v))
+        throw new Invalid(`tone must be one of ${[...TONES].join(', ')}`);
+    return v;
+}
+function arr(v, what, max) {
+    if (!Array.isArray(v))
+        throw new Invalid(`${what} must be an array`);
+    if (v.length > max)
+        throw new Invalid(`${what} has more than ${max} entries`);
+    return v;
+}
+function obj(v, what) {
+    if (typeof v !== 'object' || v === null || Array.isArray(v))
+        throw new Invalid(`${what} must be an object`);
+    return v;
+}
+function block(v) {
+    const b = obj(v, 'block');
+    switch (b.type) {
+        case 'stats':
+            return {
+                type: 'stats',
+                items: arr(b.items, 'stats.items', LIMITS.items).map((i) => {
+                    const o = obj(i, 'stat');
+                    return { label: str(o.label, 'stat.label'), value: str(o.value, 'stat.value'), tone: tone(o.tone) };
+                }),
+            };
+        case 'list':
+            return {
+                type: 'list',
+                items: arr(b.items, 'list.items', LIMITS.items).map((i) => {
+                    const o = obj(i, 'list item');
+                    return { text: str(o.text, 'list.text'), meta: optStr(o.meta, 'list.meta'), tone: tone(o.tone) };
+                }),
+            };
+        case 'table': {
+            const columns = arr(b.columns, 'table.columns', LIMITS.columns).map((c) => str(c, 'table column'));
+            const rows = arr(b.rows, 'table.rows', LIMITS.items).map((r) => {
+                const row = arr(r, 'table row', columns.length).map((c) => str(c, 'table cell'));
+                return row;
+            });
+            return { type: 'table', columns, rows };
+        }
+        case 'text':
+            return { type: 'text', text: str(b.text, 'text') };
+        case 'link': {
+            const href = str(b.href, 'link.href');
+            // Only http(s): no javascript:, data:, or relative tricks.
+            let url;
+            try {
+                url = new URL(href);
+            }
+            catch {
+                throw new Invalid('link.href must be an absolute URL');
+            }
+            if (url.protocol !== 'http:' && url.protocol !== 'https:')
+                throw new Invalid('link.href must be http(s)');
+            return { type: 'link', text: str(b.text, 'link.text'), href: url.href };
+        }
+        default:
+            throw new Invalid(`unknown block type ${JSON.stringify(b.type)}`);
+    }
+}
+/** Validate a piece's `ui --json` answer. Returns the sections, or why it was refused. */
+export function parseSections(value) {
+    try {
+        const top = obj(value, 'answer');
+        return arr(top.sections, 'sections', LIMITS.sections).map((s) => {
+            const o = obj(s, 'section');
+            const id = str(o.id, 'section.id');
+            if (!ID.test(id))
+                throw new Invalid(`section.id ${JSON.stringify(id)} must be lowercase letters, digits and dashes`);
+            return {
+                id,
+                title: str(o.title, 'section.title'),
+                blocks: arr(o.blocks, 'section.blocks', LIMITS.blocks).map(block),
+            };
+        });
+    }
+    catch (err) {
+        if (err instanceof Invalid)
+            return err.message;
+        throw err;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jbarket/loomai",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "MCP server for persistent AI agent identity and memory. Single-file sqlite-vec + local ONNX embeddings; zero external services.",
   "type": "module",
   "main": "dist/index.js",