@jbarket/loomai 0.8.0 → 0.9.0

package/dist/ui/vocab.d.ts

@@ -0,0 +1,175 @@
+/**
+ * The page vocabulary (docs/extensions.md, "The page").
+ *
+ * loom's page is built from these shapes, both loom's own pages and the
+ * installed pieces'. A piece answers `ui --json` (a manifest), `ui page --json`
+ * (a page) and `ui act --json` (an action's result) 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';
+/** Where a link goes: a page of the same source, one of loom's (`loom:` prefix), or outside. */
+export interface Target {
+    page?: string;
+    href?: string;
+}
+export type Cell = string | {
+    text: string;
+    page?: string;
+};
+export interface Field {
+    name: string;
+    label: string;
+    kind: 'text' | 'textarea' | 'choice' | 'secret';
+    hint?: string;
+    value?: string;
+    required?: boolean;
+    options?: Array<{
+        value: string;
+        label: string;
+        detail?: string;
+    }>;
+}
+export type Block = {
+    type: 'stats';
+    items: Array<{
+        label: string;
+        value: string;
+        detail?: string;
+        tone?: Tone;
+        page?: string;
+    }>;
+} | {
+    type: 'list';
+    items: Array<{
+        text: string;
+        meta?: string;
+        badge?: string;
+        tone?: Tone;
+    } & Target>;
+} | {
+    type: 'table';
+    columns: string[];
+    rows: Cell[][];
+} | {
+    type: 'kv';
+    items: Array<{
+        label: string;
+        value: string;
+        page?: string;
+    }>;
+} | {
+    type: 'text';
+    text: string;
+    tone?: Tone;
+} | {
+    type: 'callout';
+    text: string;
+    title?: string;
+    tone?: Tone;
+} | ({
+    type: 'link';
+    text: string;
+} & Target) | {
+    type: 'filters';
+    param: string;
+    options: Array<{
+        value: string;
+        label: string;
+    }>;
+} | {
+    type: 'details';
+    summary: string;
+    meta?: string;
+    blocks: Block[];
+} | {
+    type: 'form';
+    action: string;
+    submit: string;
+    fields: Field[];
+    title?: string;
+    note?: string;
+    hidden?: Record<string, string>;
+} | {
+    type: 'buttons';
+    items: Array<{
+        action: string;
+        label: string;
+        tone?: 'primary' | 'danger';
+        fields?: Record<string, string>;
+    }>;
+};
+export interface Section {
+    id: string;
+    title?: string;
+    side?: boolean;
+    tone?: Tone;
+    blocks: Block[];
+}
+export interface Page {
+    title: string;
+    intro?: string;
+    sections: Section[];
+}
+export interface Tile {
+    label: string;
+    value: string;
+    detail?: string;
+    tone?: Tone;
+    page?: string;
+}
+export interface Ask {
+    text: string;
+    meta?: string;
+    page?: string;
+    label?: string;
+}
+export interface Manifest {
+    tab?: {
+        label: string;
+    };
+    tile?: Tile;
+    asks: Ask[];
+    /** A first-version answer: these sections become the piece's page. */
+    legacy?: Section[];
+}
+export interface ActResult {
+    ok: boolean;
+    message: string;
+    page?: string;
+}
+export declare const LIMITS: {
+    readonly sections: 10;
+    readonly blocks: 20;
+    readonly items: 200;
+    readonly columns: 12;
+    readonly string: 2000;
+    readonly asks: 10;
+    readonly fields: 30;
+    readonly hidden: 20;
+    readonly options: 50;
+    readonly query: 10;
+    readonly queryValue: 200;
+    readonly path: 200;
+};
+export declare const ID: RegExp;
+export declare const QUERY_KEY: RegExp;
+/** A page path: `""` (the main page) or lowercase segments, never `..`, never absolute. */
+export declare function validPath(p: string): boolean;
+/**
+ * A page link: `[loom:]<path>[?<query>]`. Split into the source (loom's own or
+ * this piece's), the path and the query, or null when it isn't valid.
+ */
+export declare function splitPage(s: string): {
+    core: boolean;
+    path: string;
+    query: Record<string, string>;
+} | null;
+/** Validate a piece's `ui --json` answer (v2, or a first-version `{sections}`). */
+export declare function parseManifest(value: unknown): Manifest | string;
+/** Validate a piece's `ui page --json` answer. */
+export declare function parsePage(value: unknown): Page | string;
+/** Validate a piece's `ui act --json` answer. */
+export declare function parseActResult(value: unknown): ActResult | string;

package/dist/ui/vocab.js

@@ -0,0 +1,360 @@
+/**
+ * The page vocabulary (docs/extensions.md, "The page").
+ *
+ * loom's page is built from these shapes, both loom's own pages and the
+ * installed pieces'. A piece answers `ui --json` (a manifest), `ui page --json`
+ * (a page) and `ui act --json` (an action's result) 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,
+    asks: 10,
+    fields: 30,
+    hidden: 20,
+    options: 50,
+    query: 10,
+    queryValue: 200,
+    path: 200,
+};
+const TONES = new Set(['ok', 'warn', 'bad', 'muted']);
+export const ID = /^[a-z][a-z0-9-]{0,39}$/;
+const NAME = /^[a-z][a-z0-9_-]{0,39}$/;
+export const QUERY_KEY = /^[a-z][a-z0-9_-]{0,31}$/;
+const PATH_CHARS = /^[a-z0-9._~/-]*$/;
+class Invalid extends Error {
+}
+/** loom's own pages a link may name with `loom:`. */
+const CORE_PAGES = /^(|mind|people|people\/[a-z0-9][a-z0-9-]*|memory\/.+)$/;
+/** A page path: `""` (the main page) or lowercase segments, never `..`, never absolute. */
+export function validPath(p) {
+    if (p.length > LIMITS.path || !PATH_CHARS.test(p))
+        return false;
+    if (p === '')
+        return true;
+    if (p.startsWith('/') || p.endsWith('/'))
+        return false;
+    return p.split('/').every((seg) => seg !== '' && seg !== '.' && seg !== '..');
+}
+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 || v === null ? undefined : str(v, what);
+}
+function bool(v) {
+    return v === undefined ? undefined : v === true;
+}
+function tone(v) {
+    if (v === undefined || v === null)
+        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 name(v, what) {
+    const s = str(v, what);
+    if (!NAME.test(s))
+        throw new Invalid(`${what} ${JSON.stringify(s)} must be lowercase letters, digits, _ and -`);
+    return s;
+}
+/**
+ * A page link: `[loom:]<path>[?<query>]`. Split into the source (loom's own or
+ * this piece's), the path and the query, or null when it isn't valid.
+ */
+export function splitPage(s) {
+    const core = s.startsWith('loom:');
+    const rest = core ? s.slice(5) : s;
+    const q = rest.indexOf('?');
+    const path = q === -1 ? rest : rest.slice(0, q);
+    if (!validPath(path))
+        return null;
+    // Into loom, only loom's own pages: not another piece's, and not login,
+    // logout, actions or the JSON endpoints.
+    if (core && !CORE_PAGES.test(path))
+        return null;
+    const query = {};
+    if (q !== -1) {
+        const params = new URLSearchParams(rest.slice(q + 1));
+        let n = 0;
+        for (const [k, v] of params) {
+            if (!QUERY_KEY.test(k) || v.length > LIMITS.queryValue || ++n > LIMITS.query)
+                return null;
+            query[k] = v;
+        }
+    }
+    return { core, path, query };
+}
+/** A link to a page: this source's path, or `loom:<path>` for one of loom's own, either with an optional query. */
+function page(v, what) {
+    if (v === undefined || v === null)
+        return undefined;
+    const s = str(v, what);
+    if (!splitPage(s))
+        throw new Invalid(`${what} ${JSON.stringify(s)} is not a valid page link`);
+    return s;
+}
+/** Only http(s): no javascript:, data:, or relative tricks. */
+function href(v, what) {
+    if (v === undefined || v === null)
+        return undefined;
+    const s = str(v, what);
+    let url;
+    try {
+        url = new URL(s);
+    }
+    catch {
+        throw new Invalid(`${what} must be an absolute URL`);
+    }
+    if (url.protocol !== 'http:' && url.protocol !== 'https:')
+        throw new Invalid(`${what} must be http(s)`);
+    return url.href;
+}
+function target(o, what) {
+    const p = page(o.page, `${what}.page`);
+    const h = href(o.href, `${what}.href`);
+    if (p !== undefined && h !== undefined)
+        throw new Invalid(`${what} has both page and href`);
+    return { ...(p !== undefined ? { page: p } : {}), ...(h !== undefined ? { href: h } : {}) };
+}
+function strMap(v, what, max) {
+    if (v === undefined || v === null)
+        return undefined;
+    const o = obj(v, what);
+    const keys = Object.keys(o);
+    if (keys.length > max)
+        throw new Invalid(`${what} has more than ${max} entries`);
+    const out = {};
+    for (const k of keys)
+        out[name(k, `${what} key`)] = str(o[k], `${what}.${k}`);
+    return out;
+}
+function field(v) {
+    const o = obj(v, 'field');
+    const kind = o.kind;
+    if (kind !== 'text' && kind !== 'textarea' && kind !== 'choice' && kind !== 'secret') {
+        throw new Invalid('field.kind must be text, textarea, choice or secret');
+    }
+    const f = { name: name(o.name, 'field.name'), label: str(o.label, 'field.label'), kind };
+    const hint = optStr(o.hint, 'field.hint');
+    if (hint !== undefined)
+        f.hint = hint;
+    // A secret field never carries a value: the page must not be able to show one.
+    if (kind !== 'secret') {
+        const value = optStr(o.value, 'field.value');
+        if (value !== undefined)
+            f.value = value;
+    }
+    if (bool(o.required))
+        f.required = true;
+    if (kind === 'choice') {
+        f.options = arr(o.options, 'field.options', LIMITS.options).map((x) => {
+            const opt = obj(x, 'option');
+            return { value: str(opt.value, 'option.value'), label: str(opt.label, 'option.label'), detail: optStr(opt.detail, 'option.detail') };
+        });
+    }
+    return f;
+}
+function block(v, depth = 0) {
+    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'),
+                        detail: optStr(o.detail, 'stat.detail'), tone: tone(o.tone), page: page(o.page, 'stat.page'),
+                    };
+                }),
+            };
+        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'), badge: optStr(o.badge, 'list.badge'),
+                        tone: tone(o.tone), ...target(o, 'list item'),
+                    };
+                }),
+            };
+        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) => arr(r, 'table row', columns.length).map((c) => {
+                if (typeof c === 'string' || typeof c === 'number')
+                    return str(c, 'table cell');
+                const o = obj(c, 'table cell');
+                const p = page(o.page, 'table cell.page');
+                return p !== undefined ? { text: str(o.text, 'table cell.text'), page: p } : str(o.text, 'table cell.text');
+            }));
+            return { type: 'table', columns, rows };
+        }
+        case 'kv':
+            return {
+                type: 'kv',
+                items: arr(b.items, 'kv.items', LIMITS.items).map((i) => {
+                    const o = obj(i, 'kv item');
+                    return { label: str(o.label, 'kv.label'), value: str(o.value, 'kv.value'), page: page(o.page, 'kv.page') };
+                }),
+            };
+        case 'text':
+            return { type: 'text', text: str(b.text, 'text'), tone: tone(b.tone) };
+        case 'callout':
+            return { type: 'callout', text: str(b.text, 'callout.text'), title: optStr(b.title, 'callout.title'), tone: tone(b.tone) };
+        case 'link': {
+            const t = target(b, 'link');
+            if (t.page === undefined && t.href === undefined)
+                throw new Invalid('link needs page or href');
+            return { type: 'link', text: str(b.text, 'link.text'), ...t };
+        }
+        case 'filters': {
+            const param = str(b.param, 'filters.param');
+            if (!QUERY_KEY.test(param))
+                throw new Invalid('filters.param must be a query key');
+            return {
+                type: 'filters',
+                param,
+                options: arr(b.options, 'filters.options', LIMITS.options).map((x) => {
+                    const o = obj(x, 'filter option');
+                    const value = str(o.value, 'filter.value');
+                    if (value.length > LIMITS.queryValue)
+                        throw new Invalid('filter.value is too long');
+                    return { value, label: str(o.label, 'filter.label') };
+                }),
+            };
+        }
+        case 'details':
+            if (depth > 0)
+                throw new Invalid('details can\'t contain details');
+            return {
+                type: 'details',
+                summary: str(b.summary, 'details.summary'),
+                meta: optStr(b.meta, 'details.meta'),
+                blocks: arr(b.blocks, 'details.blocks', LIMITS.blocks).map((x) => block(x, depth + 1)),
+            };
+        case 'form':
+            return {
+                type: 'form',
+                action: name(b.action, 'form.action'),
+                submit: str(b.submit, 'form.submit'),
+                fields: arr(b.fields, 'form.fields', LIMITS.fields).map(field),
+                title: optStr(b.title, 'form.title'),
+                note: optStr(b.note, 'form.note'),
+                hidden: strMap(b.hidden, 'form.hidden', LIMITS.hidden),
+            };
+        case 'buttons':
+            return {
+                type: 'buttons',
+                items: arr(b.items, 'buttons.items', LIMITS.fields).map((x) => {
+                    const o = obj(x, 'button');
+                    const t = o.tone;
+                    if (t !== undefined && t !== 'primary' && t !== 'danger')
+                        throw new Invalid('button.tone must be primary or danger');
+                    return {
+                        action: name(o.action, 'button.action'),
+                        label: str(o.label, 'button.label'),
+                        tone: t,
+                        fields: strMap(o.fields, 'button.fields', LIMITS.hidden),
+                    };
+                }),
+            };
+        default:
+            throw new Invalid(`unknown block type ${JSON.stringify(b.type)}`);
+    }
+}
+function section(v) {
+    const o = obj(v, '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: optStr(o.title, 'section.title'),
+        side: bool(o.side),
+        tone: tone(o.tone),
+        blocks: arr(o.blocks, 'section.blocks', LIMITS.blocks).map((x) => block(x)),
+    };
+}
+function sections(v) {
+    return arr(v, 'sections', LIMITS.sections).map(section);
+}
+function attempt(f) {
+    try {
+        return f();
+    }
+    catch (err) {
+        if (err instanceof Invalid)
+            return err.message;
+        throw err;
+    }
+}
+/** Validate a piece's `ui --json` answer (v2, or a first-version `{sections}`). */
+export function parseManifest(value) {
+    return attempt(() => {
+        const top = obj(value, 'answer');
+        if (top.v === undefined && top.sections !== undefined) {
+            return { asks: [], legacy: sections(top.sections) };
+        }
+        if (top.v !== 2)
+            throw new Invalid('v must be 2');
+        const m = { asks: [] };
+        if (top.tab !== undefined)
+            m.tab = { label: str(obj(top.tab, 'tab').label, 'tab.label') };
+        if (top.tile !== undefined) {
+            const t = obj(top.tile, 'tile');
+            m.tile = {
+                label: str(t.label, 'tile.label'), value: str(t.value, 'tile.value'),
+                detail: optStr(t.detail, 'tile.detail'), tone: tone(t.tone), page: page(t.page, 'tile.page'),
+            };
+        }
+        if (top.asks !== undefined) {
+            m.asks = arr(top.asks, 'asks', LIMITS.asks).map((x) => {
+                const a = obj(x, 'ask');
+                return { text: str(a.text, 'ask.text'), meta: optStr(a.meta, 'ask.meta'), page: page(a.page, 'ask.page'), label: optStr(a.label, 'ask.label') };
+            });
+        }
+        return m;
+    });
+}
+/** Validate a piece's `ui page --json` answer. */
+export function parsePage(value) {
+    return attempt(() => {
+        const top = obj(value, 'page');
+        return { title: str(top.title, 'title'), intro: optStr(top.intro, 'intro'), sections: sections(top.sections) };
+    });
+}
+/** Validate a piece's `ui act --json` answer. */
+export function parseActResult(value) {
+    return attempt(() => {
+        const top = obj(value, 'result');
+        if (typeof top.ok !== 'boolean')
+            throw new Invalid('ok must be true or false');
+        return { ok: top.ok, message: str(top.message, 'message'), page: page(top.page, 'page') };
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jbarket/loomai",
-  "version": "0.8.0",
+  "version": "0.9.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",

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

@@ -1,20 +0,0 @@
-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

@@ -1,112 +0,0 @@
-/**
- * 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),
-    };
-}