@jbarket/loomai 0.5.0

package/dist/tools/update-identity.js

@@ -0,0 +1,194 @@
+/**
+ * Update Identity tool — section-level edits on self-model and preferences.
+ *
+ * Identity files are markdown with H2 sections. This tool can:
+ * - List sections in a file
+ * - Replace a section's content (between its H2 and the next H2 or EOF)
+ * - Append a new section at the end
+ *
+ * IDENTITY.md is immutable — only self-model.md and preferences.md are editable.
+ */
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { atomicWriteWithBackup } from '../path-safety.js';
+/** Files that can be edited via this tool. IDENTITY.md is explicitly excluded. */
+const EDITABLE_FILES = {
+    'self-model': 'self-model.md',
+    'preferences': 'preferences.md',
+};
+/**
+ * Parse a markdown file into H2 sections.
+ * Content before the first H2 is captured as a preamble (header: '').
+ *
+ * Fence-aware: a `## ` line inside a ``` or ~~~ code fence is body content,
+ * not a section boundary. Closing fences must use the same character and be
+ * at least as long as the opener (CommonMark-style).
+ */
+export function parseSections(text) {
+    const lines = text.split('\n');
+    const sections = [];
+    let currentHeader = '';
+    let currentLines = [];
+    let startLine = 0;
+    let fence = null; // opening fence marker while inside a fenced block
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const fenceMatch = line.match(/^\s{0,3}(`{3,}|~{3,})/);
+        if (fenceMatch) {
+            const marker = fenceMatch[1];
+            if (fence === null) {
+                fence = marker;
+            }
+            else if (marker[0] === fence[0] && marker.length >= fence.length) {
+                fence = null;
+            }
+            currentLines.push(line);
+            continue;
+        }
+        if (fence === null && line.startsWith('## ')) {
+            // Close previous section
+            sections.push({
+                header: currentHeader,
+                content: currentLines.join('\n').trim(),
+                startLine,
+                endLine: i - 1,
+            });
+            currentHeader = line.replace(/^## /, '').trim();
+            currentLines = [];
+            startLine = i;
+        }
+        else {
+            currentLines.push(line);
+        }
+    }
+    // Close final section
+    sections.push({
+        header: currentHeader,
+        content: currentLines.join('\n').trim(),
+        startLine,
+        endLine: lines.length - 1,
+    });
+    return sections;
+}
+/**
+ * Rebuild a markdown file from sections.
+ */
+export function rebuildMarkdown(sections) {
+    const parts = [];
+    for (const section of sections) {
+        if (section.header === '') {
+            // Preamble — just the content
+            if (section.content) {
+                parts.push(section.content);
+            }
+        }
+        else {
+            parts.push(`## ${section.header}\n${section.content}`);
+        }
+    }
+    return parts.join('\n\n') + '\n';
+}
+/**
+ * Replace a single section's body in place, leaving every other line of the
+ * file byte-identical. The header line itself is preserved as-is; only the
+ * lines between it and the next section (or EOF) are swapped for `content`,
+ * followed by one blank separator line when another section follows.
+ */
+function spliceSection(text, section, content) {
+    const lines = text.split('\n');
+    const before = lines.slice(0, section.startLine + 1); // includes the header line
+    const after = lines.slice(section.endLine + 1); // first line of the next section, if any
+    const body = content.replace(/\n+$/, '').split('\n');
+    const next = [...before, ...body];
+    if (after.length > 0) {
+        next.push(''); // blank line before the untouched next section
+    }
+    else if (text.endsWith('\n')) {
+        next.push(''); // preserve the file's trailing newline
+    }
+    return [...next, ...after].join('\n');
+}
+/**
+ * Append a new section at the end of the file, leaving existing content
+ * byte-identical apart from ensuring a trailing newline.
+ */
+function appendSection(text, header, content) {
+    const block = `## ${header}\n${content.replace(/\n+$/, '')}\n`;
+    if (text.trim() === '')
+        return block;
+    let base = text.endsWith('\n') ? text : text + '\n';
+    if (!base.endsWith('\n\n'))
+        base += '\n';
+    return base + block;
+}
+/**
+ * List sections in an identity file.
+ */
+export async function listSections(contextDir, file) {
+    const filename = EDITABLE_FILES[file];
+    if (!filename) {
+        return `Unknown file "${file}". Editable files: ${Object.keys(EDITABLE_FILES).join(', ')}`;
+    }
+    const filepath = join(contextDir, filename);
+    let text;
+    try {
+        text = await readFile(filepath, 'utf-8');
+    }
+    catch {
+        return `File not found: ${filename}. It will be created when you add a section.`;
+    }
+    const sections = parseSections(text);
+    const named = sections.filter(s => s.header !== '');
+    if (named.length === 0) {
+        return `${filename} has no H2 sections.`;
+    }
+    const list = named.map(s => `- **${s.header}** (${s.content.split('\n').length} lines)`).join('\n');
+    return `Sections in ${filename}:\n${list}`;
+}
+/**
+ * Update or append a section in an identity file.
+ */
+export async function updateIdentity(contextDir, input) {
+    const { file, section, content, mode = 'replace' } = input;
+    // Validate file
+    const filename = EDITABLE_FILES[file];
+    if (!filename) {
+        return `Unknown file "${file}". Editable files: ${Object.keys(EDITABLE_FILES).join(', ')}`;
+    }
+    // List mode — no section or content means "show me what's there"
+    if (!section && !content) {
+        return listSections(contextDir, file);
+    }
+    if (!section) {
+        return 'Section name is required when providing content.';
+    }
+    if (!content) {
+        return 'Content is required when specifying a section.';
+    }
+    const filepath = join(contextDir, filename);
+    let text;
+    try {
+        text = await readFile(filepath, 'utf-8');
+    }
+    catch {
+        // File doesn't exist — create it with the new section (atomic, no .bak)
+        const newContent = `## ${section}\n${content}\n`;
+        await atomicWriteWithBackup(filepath, newContent);
+        return `Created ${filename} with section "${section}".`;
+    }
+    const sections = parseSections(text);
+    const existing = sections.find(s => s.header.toLowerCase() === section.toLowerCase());
+    if (mode === 'append') {
+        if (existing) {
+            return `Section "${section}" already exists in ${filename}. Use mode "replace" to update it.`;
+        }
+        await atomicWriteWithBackup(filepath, appendSection(text, section, content));
+        return `Appended new section "${section}" to ${filename}.`;
+    }
+    // Replace mode
+    if (!existing) {
+        return `Section "${section}" not found in ${filename}. Available sections: ${sections.filter(s => s.header !== '').map(s => s.header).join(', ')}. Use mode "append" to add a new section.`;
+    }
+    await atomicWriteWithBackup(filepath, spliceSection(text, existing, content));
+    return `Updated section "${section}" in ${filename}.`;
+}

package/dist/tools/update.d.ts

@@ -0,0 +1,2 @@
+import type { UpdateInput } from '../backends/types.js';
+export declare function update(contextDir: string, input: UpdateInput): Promise<string>;

package/dist/tools/update.js

@@ -0,0 +1,16 @@
+/**
+ * Update tool — modifies an existing memory by reference or by category+title.
+ *
+ * Delegates to the configured memory backend. Supports full content
+ * replacement or metadata-only updates.
+ */
+import { createBackend } from '../backends/index.js';
+export async function update(contextDir, input) {
+    const backend = createBackend(contextDir);
+    const result = await backend.update(input);
+    if (!result.updated) {
+        const identifier = input.ref ?? `${input.category}/${input.title}`;
+        return `Memory not found: "${identifier}". Use recall to find the correct reference.`;
+    }
+    return `Memory updated: ${result.ref}`;
+}

package/dist/transport/guards.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Transport guards (c-loom-transport §boundary) — the security boundary as
+ * pure, testable behavior, independent of the HTTP wiring that calls them.
+ *
+ *   assertSafeBind   — refuse a public / 0.0.0.0 bind (bind-safety)
+ *   checkBearer      — refuse an unauthenticated call when a token is set (auth gate)
+ *   checkPayloadSize — refuse an oversized request before the handler runs
+ *
+ * The HTTP serve path applies these at startup (bind) and per request (auth,
+ * size); keeping them pure means the contract is verified without a live socket.
+ */
+export interface GuardResult {
+    ok: boolean;
+    error?: string;
+}
+/** Default request-body cap (1 MiB) — overridable via LOOM_HTTP_MAX_BYTES. */
+export declare const DEFAULT_MAX_BODY_BYTES = 1048576;
+/**
+ * A host is mesh-or-local-safe if it is loopback, an RFC1918 private address,
+ * the Tailscale CGNAT range (100.64.0.0/10), or an IPv6 ULA / link-local /
+ * loopback. Everything else — and explicitly the 0.0.0.0 / :: bind-all wildcard
+ * and any globally routable address — is refused.
+ */
+export declare function isSafeBindHost(hostRaw: string): boolean;
+/** Bind-safety: throws at startup if asked to listen on a public/wildcard host. */
+export declare function assertSafeBind(host: string): void;
+/**
+ * Auth gate: when a bearer token is configured, a call must present the matching
+ * token. When no token is configured, the call is allowed (the network boundary
+ * — loopback/mesh per bind-safety — is the access control). `presented` is the
+ * raw Authorization header value (e.g. "Bearer abc"); the scheme is tolerated.
+ */
+export declare function checkBearer(configured: string | undefined, presented: string | undefined): GuardResult;
+/** Oversized guard: refuse a body beyond the cap before the handler runs. */
+export declare function checkPayloadSize(bytes: number, cap?: number): GuardResult;

package/dist/transport/guards.js

@@ -0,0 +1,107 @@
+/**
+ * Transport guards (c-loom-transport §boundary) — the security boundary as
+ * pure, testable behavior, independent of the HTTP wiring that calls them.
+ *
+ *   assertSafeBind   — refuse a public / 0.0.0.0 bind (bind-safety)
+ *   checkBearer      — refuse an unauthenticated call when a token is set (auth gate)
+ *   checkPayloadSize — refuse an oversized request before the handler runs
+ *
+ * The HTTP serve path applies these at startup (bind) and per request (auth,
+ * size); keeping them pure means the contract is verified without a live socket.
+ */
+/** Default request-body cap (1 MiB) — overridable via LOOM_HTTP_MAX_BYTES. */
+export const DEFAULT_MAX_BODY_BYTES = 1_048_576;
+function v4Octets(host) {
+    const m = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(host);
+    if (!m)
+        return null;
+    const o = m.slice(1, 5).map((n) => Number(n));
+    if (o.some((n) => n > 255))
+        return null;
+    return o;
+}
+/**
+ * A host is mesh-or-local-safe if it is loopback, an RFC1918 private address,
+ * the Tailscale CGNAT range (100.64.0.0/10), or an IPv6 ULA / link-local /
+ * loopback. Everything else — and explicitly the 0.0.0.0 / :: bind-all wildcard
+ * and any globally routable address — is refused.
+ */
+export function isSafeBindHost(hostRaw) {
+    const host = hostRaw.trim().toLowerCase();
+    if (host === '' || host === '*')
+        return false;
+    // bind-all wildcards: the exact thing bind-safety exists to refuse
+    if (host === '0.0.0.0' || host === '::' || host === '[::]' || host === '0:0:0:0:0:0:0:0') {
+        return false;
+    }
+    // named loopback
+    if (host === 'localhost')
+        return true;
+    const v4 = v4Octets(host);
+    if (v4) {
+        const [a, b] = v4;
+        if (a === 127)
+            return true; // loopback 127.0.0.0/8
+        if (a === 10)
+            return true; // private 10.0.0.0/8
+        if (a === 192 && b === 168)
+            return true; // private 192.168.0.0/16
+        if (a === 172 && b >= 16 && b <= 31)
+            return true; // private 172.16.0.0/12
+        if (a === 100 && b >= 64 && b <= 127)
+            return true; // Tailscale CGNAT 100.64.0.0/10
+        if (a === 169 && b === 254)
+            return true; // link-local 169.254.0.0/16
+        return false; // any other v4 is treated as public
+    }
+    // IPv6 (possibly bracketed)
+    const v6 = host.replace(/^\[|\]$/g, '');
+    if (v6 === '::1')
+        return true; // loopback
+    if (v6.startsWith('fe80:') || v6.startsWith('fe80::'))
+        return true; // link-local
+    if (/^f[cd][0-9a-f]{0,2}:/.test(v6))
+        return true; // ULA fc00::/7
+    return false; // any other v6 (incl. global unicast) is public
+}
+/** Bind-safety: throws at startup if asked to listen on a public/wildcard host. */
+export function assertSafeBind(host) {
+    if (!isSafeBindHost(host)) {
+        throw new Error(`unsafe-bind: refusing to bind loom to "${host}" — only loopback or a mesh ` +
+            `(Tailscale/RFC1918) interface is allowed. Tailscale is the access control; ` +
+            `loom must never listen on a public or 0.0.0.0 interface.`);
+    }
+}
+/** Constant-time string compare (avoids leaking the token via timing). */
+function timingSafeEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++)
+        diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    return diff === 0;
+}
+/**
+ * Auth gate: when a bearer token is configured, a call must present the matching
+ * token. When no token is configured, the call is allowed (the network boundary
+ * — loopback/mesh per bind-safety — is the access control). `presented` is the
+ * raw Authorization header value (e.g. "Bearer abc"); the scheme is tolerated.
+ */
+export function checkBearer(configured, presented) {
+    if (!configured)
+        return { ok: true };
+    const token = (presented ?? '').replace(/^Bearer\s+/i, '').trim();
+    if (token === '')
+        return { ok: false, error: 'unauthorized: missing bearer token' };
+    if (!timingSafeEqual(token, configured)) {
+        return { ok: false, error: 'unauthorized: bearer token mismatch' };
+    }
+    return { ok: true };
+}
+/** Oversized guard: refuse a body beyond the cap before the handler runs. */
+export function checkPayloadSize(bytes, cap = DEFAULT_MAX_BODY_BYTES) {
+    if (bytes > cap) {
+        return { ok: false, error: `oversized: request body ${bytes} bytes exceeds cap ${cap}` };
+    }
+    return { ok: true };
+}

package/dist/transport/http-server.d.ts

@@ -0,0 +1,17 @@
+export interface HttpServeOptions {
+    contextDir: string;
+    host: string;
+    port: number;
+    /** When set, every request must present this bearer token. */
+    token?: string;
+    maxBytes?: number;
+    /** SSE keep-alive ping interval (ms). Default HEARTBEAT_MS; tests use a small value. */
+    heartbeatMs?: number;
+}
+export interface HttpServeHandle {
+    /** The actually-bound port (resolves a 0 request to the OS-assigned port). */
+    port: number;
+    host: string;
+    close(): Promise<void>;
+}
+export declare function startHttpServer(opts: HttpServeOptions): Promise<HttpServeHandle>;

package/dist/transport/http-server.js

@@ -0,0 +1,198 @@
+/**
+ * loom HTTP MCP transport (c-loom-transport) — the mesh-reachable surface.
+ *
+ * A thin node:http front for the StreamableHTTP MCP transport, applying loom's
+ * boundary guards: bind-safety at startup (assertSafeBind), a bearer auth gate
+ * and an oversized-payload guard per request. The MCP envelope/dispatch behavior
+ * itself is the SDK's McpServer — the same server factory that serves stdio, so
+ * results are transport-neutral by construction (ac-lt-envelope-ok parity).
+ *
+ * Session mode: each MCP session gets its own server+transport, keyed by the
+ * mcp-session-id header (the canonical persistent-daemon pattern, and what
+ * Claude Desktop uses). loom's durable state lives in the stores, not the
+ * session, so sessions are cheap routing handles over a shared contextDir.
+ * WHERE it binds on the mesh is deployment (the portable-MCP ADR); THAT it
+ * refuses an unsafe bind is this contract.
+ */
+import { randomUUID } from 'node:crypto';
+import { createServer } from 'node:http';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { isInitializeRequest, EmptyResultSchema } from '@modelcontextprotocol/sdk/types.js';
+import { createLoomServer } from '../server.js';
+import { assertSafeBind, checkBearer, checkPayloadSize, DEFAULT_MAX_BODY_BYTES, } from './guards.js';
+/**
+ * SSE keep-alive: the SDK opens the standalone GET stream but sends no
+ * heartbeat, so an idle stream gets reaped by proxies/NAT (Traefik's default
+ * idle is ~180s) and the session bricks. We drive a protocol-native `ping` to
+ * the client over the stream — it keeps the connection warm AND detects a dead
+ * client (after a few misses the session is closed, and the client re-inits via
+ * the 404 path). The interval stays well under typical idle windows.
+ */
+const HEARTBEAT_MS = 25_000;
+const HEARTBEAT_TIMEOUT_MS = 10_000;
+const HEARTBEAT_MISSES_BEFORE_CLOSE = 2;
+function sendError(res, status, message) {
+    // A typed error ENVELOPE, never a raw throw across the boundary.
+    if (res.headersSent)
+        return;
+    res.writeHead(status, { 'content-type': 'application/json' });
+    res.end(JSON.stringify({ error: message }));
+}
+const OVERSIZED = Symbol('oversized');
+function collectBody(req, cap) {
+    return new Promise((resolve, reject) => {
+        let size = 0;
+        const chunks = [];
+        req.on('data', (c) => {
+            size += c.length;
+            if (size > cap) {
+                resolve(OVERSIZED);
+                req.destroy();
+                return;
+            }
+            chunks.push(c);
+        });
+        req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+        req.on('error', reject);
+    });
+}
+export async function startHttpServer(opts) {
+    // Bind-safety (ac-lt-bind-safety): refuse an unsafe host BEFORE we open a socket.
+    assertSafeBind(opts.host);
+    const maxBytes = opts.maxBytes ?? DEFAULT_MAX_BODY_BYTES;
+    const heartbeatMs = opts.heartbeatMs ?? HEARTBEAT_MS;
+    // One transport (+ its connected server) per live MCP session.
+    const sessions = new Map();
+    async function openSession() {
+        const { server } = createLoomServer({ contextDir: opts.contextDir });
+        // Fires AFTER the initialize handshake completes — getClientVersion() is
+        // populated here (it is not yet at onsessioninitialized). Logging the peer
+        // makes the resolved harness observable and reveals an unmapped client's
+        // real clientInfo.name so the alias table can be extended.
+        server.server.oninitialized = () => {
+            const peer = server.server.getClientVersion();
+            process.stderr.write(`loom: peer connected client=${JSON.stringify(peer ?? null)}\n`);
+        };
+        const transport = new StreamableHTTPServerTransport({
+            sessionIdGenerator: () => randomUUID(),
+            enableJsonResponse: true,
+            onsessioninitialized: (sid) => {
+                sessions.set(sid, transport);
+            },
+        });
+        // SSE keep-alive: ping the client over the standalone stream. The first tick
+        // is one interval out, by when the client has opened the stream. A live
+        // client pongs (the SDK answers ping automatically); repeated misses mean a
+        // dead peer or a reaped stream → close the session so it can't zombie, and
+        // the client recovers via the 404 re-init path.
+        let misses = 0;
+        const heartbeat = setInterval(() => {
+            void server.server
+                .request({ method: 'ping' }, EmptyResultSchema, { timeout: HEARTBEAT_TIMEOUT_MS })
+                .then(() => {
+                misses = 0;
+            })
+                .catch(() => {
+                misses += 1;
+                if (misses >= HEARTBEAT_MISSES_BEFORE_CLOSE) {
+                    clearInterval(heartbeat);
+                    void transport.close().catch(() => undefined);
+                }
+            });
+        }, heartbeatMs);
+        // Don't let the heartbeat keep the event loop alive (clean process exit / test teardown).
+        if (typeof heartbeat.unref === 'function')
+            heartbeat.unref();
+        transport.onclose = () => {
+            clearInterval(heartbeat);
+            if (transport.sessionId)
+                sessions.delete(transport.sessionId);
+        };
+        await server.connect(transport);
+        return transport;
+    }
+    const http = createServer((req, res) => {
+        void (async () => {
+            // Auth gate (ac-lt-auth-gate): reject unauthenticated when a token is set.
+            const auth = checkBearer(opts.token, req.headers['authorization']);
+            if (!auth.ok)
+                return sendError(res, 401, auth.error);
+            // Oversized guard (ac-lt-oversized-guard): fast path on declared length.
+            const declared = Number(req.headers['content-length'] ?? 0);
+            if (Number.isFinite(declared) && declared > 0 && !checkPayloadSize(declared, maxBytes).ok) {
+                return sendError(res, 413, `oversized: declared ${declared} bytes exceeds cap ${maxBytes}`);
+            }
+            const sessionId = req.headers['mcp-session-id'];
+            // GET = the server->client SSE stream (server push: listChanged, progress,
+            // elicitation, ui:// updates). It attaches to an established session, so a
+            // GET routes to that session's transport. The stream is kept alive by the
+            // per-session heartbeat. A GET for a session we no longer hold is 404 (the
+            // client re-initializes); a GET with no session at all is 405.
+            if (req.method === 'GET' || req.method === 'DELETE') {
+                const existing = sessionId ? sessions.get(sessionId) : undefined;
+                if (existing) {
+                    return existing.handleRequest(req, res).catch((e) => sendError(res, 500, `internal: ${e.message}`));
+                }
+                if (sessionId) {
+                    res.writeHead(404, { 'content-type': 'application/json' });
+                    res.end(JSON.stringify({ error: 'session not found; reinitialize' }));
+                    return;
+                }
+                res.writeHead(405, { 'content-type': 'application/json', allow: 'POST' });
+                res.end(JSON.stringify({ error: 'method-not-allowed: open a session with an initialize POST first' }));
+                return;
+            }
+            if (req.method !== 'POST')
+                return sendError(res, 405, 'method-not-allowed');
+            // POST: read + cap the body, then route by session / initialize.
+            const body = await collectBody(req, maxBytes);
+            if (body === OVERSIZED)
+                return sendError(res, 413, `oversized: body exceeds cap ${maxBytes}`);
+            let parsed;
+            try {
+                parsed = body ? JSON.parse(body) : undefined;
+            }
+            catch (e) {
+                return sendError(res, 400, `bad-input: malformed JSON (${e.message})`);
+            }
+            let transport = sessionId ? sessions.get(sessionId) : undefined;
+            if (!transport) {
+                if (sessionId) {
+                    // A session id we don't have (expired / dropped). Per MCP spec, 404
+                    // tells the client to start over with a fresh initialize — so an idle
+                    // disconnect self-heals instead of bricking on a 400.
+                    res.writeHead(404, { 'content-type': 'application/json' });
+                    res.end(JSON.stringify({ error: 'session not found; reinitialize' }));
+                    return;
+                }
+                if (!isInitializeRequest(parsed)) {
+                    return sendError(res, 400, 'bad-input: no valid session; expected an initialize request');
+                }
+                transport = await openSession();
+            }
+            // Dispatch totality + typed envelopes (unknown tool / bad args -> JSON-RPC
+            // error) are the SDK server's job from here — never a raw throw out.
+            await transport.handleRequest(req, res, parsed);
+        })().catch((e) => sendError(res, 500, `internal: ${e.message}`));
+    });
+    await new Promise((resolve, reject) => {
+        http.once('error', reject);
+        http.listen(opts.port, opts.host, () => resolve());
+    });
+    const addr = http.address();
+    const port = typeof addr === 'object' && addr ? addr.port : opts.port;
+    return {
+        port,
+        host: opts.host,
+        async close() {
+            for (const t of sessions.values())
+                await t.close().catch(() => undefined);
+            sessions.clear();
+            await new Promise((resolve) => {
+                // Force-close lingering keep-alive/SSE sockets so close() can't hang.
+                http.closeAllConnections?.();
+                http.close(() => resolve());
+            });
+        },
+    };
+}

package/dist/transport/mcp-app-hello.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/** Register the env-gated MCP-App probes + the first real widget. Call only when probing. */
+export declare function registerHelloApp(server: McpServer, version: string, contextDir: string): void;

package/dist/transport/mcp-app-hello.js

@@ -0,0 +1,66 @@
+/**
+ * MCP-App render probes (env-gated: LOOM_MCP_APP_HELLO), built the RIGHT way on
+ * the official @modelcontextprotocol/ext-apps SDK:
+ *   - server side: registerAppResource / registerAppTool set the ui:// resource,
+ *     the text/html;profile=mcp-app mimeType, and BOTH _meta keys the host needs.
+ *   - widget side: the App class (bundled into dist/widgets/<name>.html by
+ *     scripts/build-widgets.mjs) does the full handshake, autoResize, etc.
+ *
+ * Two probes:
+ *   - loom_hello: a vanilla App-SDK "hello world" (renders + callServerTool).
+ *   - loom_display_modes: a Preact widget exercising inline/fullscreen/pip.
+ *
+ * Not specced, not in the permanent tool surface — throwaway validation + the
+ * reference for loom's real widgets.
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { registerAppResource, registerAppTool, RESOURCE_MIME_TYPE, } from '@modelcontextprotocol/ext-apps/server';
+import { resolveRepoRoot } from '../config.js';
+import { digestData } from '../backends/salience.js';
+import { listProposals } from '../backends/proposals.js';
+function registerApp(server, app) {
+    const html = readFileSync(join(resolveRepoRoot(), 'dist', 'widgets', app.htmlFile), 'utf-8');
+    registerAppResource(server, `${app.tool}-ui`, app.uri, { description: app.description }, async (uri) => ({
+        contents: [{ uri: uri.href, mimeType: RESOURCE_MIME_TYPE, text: html }],
+    }));
+    registerAppTool(server, app.tool, {
+        description: app.description,
+        inputSchema: {},
+        _meta: { ui: { resourceUri: app.uri, visibility: ['model', 'app'] } },
+    }, async () => ({
+        content: [{ type: 'text', text: `${app.tool} — see the rendered widget.` }],
+        structuredContent: app.structured(),
+    }));
+}
+/** Register the env-gated MCP-App probes + the first real widget. Call only when probing. */
+export function registerHelloApp(server, version, contextDir) {
+    registerApp(server, {
+        tool: 'loom_hello',
+        uri: 'ui://loom/hello',
+        htmlFile: 'hello.html',
+        description: 'MCP-App render probe — an interactive hello widget (vanilla + App SDK).',
+        structured: () => ({ message: 'loom MCP-App is live (ext-apps SDK)', version, at: new Date().toISOString() }),
+    });
+    registerApp(server, {
+        tool: 'loom_display_modes',
+        uri: 'ui://loom/display-modes',
+        htmlFile: 'display-modes.html',
+        description: 'MCP-App display-mode trial (Preact) — exercises inline / fullscreen / pip.',
+        structured: () => ({ message: 'pick a display mode in the widget', version }),
+    });
+    registerApp(server, {
+        tool: 'loom_top_of_mind',
+        uri: 'ui://loom/top-of-mind',
+        htmlFile: 'top-of-mind.html',
+        description: "Show what's top of mind — the salience-tiered memory digest as a widget. Inline = the hottest few; expand to fullscreen for the full Hot/Warm/Cool landscape.",
+        structured: () => digestData(contextDir) ?? { atoms: [], total: 0 },
+    });
+    registerApp(server, {
+        tool: 'loom_proposals',
+        uri: 'ui://loom/proposals',
+        htmlFile: 'proposals.html',
+        description: 'Review the capture-propose queue — pending memory drafts awaiting ratification. Ratify (commit to memory) or reject each. Inline = the count + newest; expand to review the full queue.',
+        structured: () => ({ proposals: listProposals(contextDir) }),
+    });
+}