@jbarket/loomai 0.11.0 → 0.13.0

package/dist/cli/bundle.js

@@ -0,0 +1,107 @@
+/**
+ * `loom export` and `loom restore` (src/bundle.ts; docs/specs/household.md,
+ * "Export and restore"). Local only: neither is a remote verb.
+ */
+import { householdHome } from '../household.js';
+import { BundleError, drillBundle, exportBundle, restoreBundle, sizeOf } from '../bundle.js';
+import { extractGlobalFlags, resolveEnv } from './args.js';
+const EXPORT_USAGE = `Usage: loom export --to <file> --recipient <age1…> [--recipient …]
+
+Write the whole household to one file, encrypted to the owner's key (an age
+public key, or an ssh public key). Inside: the household's files, the commons,
+every agent's directory, and each installed piece's own part, which the piece
+encrypts itself (loom-<piece> bundle export). A plain context dir exports as a
+household of one.
+`;
+const RESTORE_USAGE = `Usage: loom restore <file> --identity <key file> [--to <dir>]
+       loom restore <file> --identity <key file> --drill
+
+Lay a bundle down in an empty LOOM_HOME (--to, else $LOOM_HOME, else
+~/.config/loom), then hand each installed piece its part (loom-<piece> bundle import).
+A piece that isn't installed keeps its part in pieces-pending/.
+
+--drill restores into a throwaway directory instead and compares it with the
+live household (agents, identities, memories, every card, knowledge, tokens),
+then removes it. Nothing live is touched.
+
+A restore trusts what's in the bundle: age encrypts but doesn't prove who made
+the file, so only restore bundles you made.
+`;
+function flags(args, name) {
+    const out = [];
+    for (let i = 0; i < args.length; i++)
+        if (args[i] === name && args[i + 1])
+            out.push(args[++i]);
+    return out;
+}
+export async function runExport(rawArgv, io) {
+    const { flags: global, rest: argv } = extractGlobalFlags(rawArgv);
+    if (argv.includes('--help') || argv.includes('-h')) {
+        io.stdout(EXPORT_USAGE);
+        return 0;
+    }
+    const to = flags(argv, '--to')[0];
+    const recipients = flags(argv, '--recipient');
+    if (!to || recipients.length === 0) {
+        io.stderr(EXPORT_USAGE);
+        return 2;
+    }
+    const { contextDir } = resolveEnv(global, io.env);
+    try {
+        const m = await exportBundle({ contextDir, to, recipients, env: io.env });
+        const left = m.pieces.filter((p) => !p.included);
+        io.stdout(`Bundle written: ${to} (${(sizeOf(to) / 1048576).toFixed(1)} MB), agents ${m.household.agents.join(', ')}.\n`);
+        for (const p of m.pieces.filter((x) => x.included))
+            io.stdout(`  piece ${p.name}: included (${p.bytes} bytes, encrypted by the piece)\n`);
+        for (const p of left)
+            io.stdout(`  piece ${p.name}: not included (${p.reason})\n`);
+        return 0;
+    }
+    catch (err) {
+        if (err instanceof BundleError) {
+            io.stderr(`${err.message}\n`);
+            return 1;
+        }
+        throw err;
+    }
+}
+export async function runRestore(rawArgv, io) {
+    const { flags: global, rest: argv } = extractGlobalFlags(rawArgv);
+    if (argv.includes('--help') || argv.includes('-h')) {
+        io.stdout(RESTORE_USAGE);
+        return 0;
+    }
+    const file = argv.find((a, i) => !a.startsWith('--') && (i === 0 || !argv[i - 1].startsWith('--')));
+    const identity = flags(argv, '--identity')[0];
+    if (!file || !identity) {
+        io.stderr(RESTORE_USAGE);
+        return 2;
+    }
+    try {
+        if (argv.includes('--drill')) {
+            const { contextDir } = resolveEnv(global, io.env);
+            const r = await drillBundle({ file, identity, contextDir, env: io.env });
+            if (r.ok) {
+                io.stdout(`Drill passed: the bundle from ${r.manifest.created} restores to a household that matches the live one.\n`);
+                return 0;
+            }
+            io.stdout(`Drill found ${r.differences.length} difference${r.differences.length === 1 ? '' : 's'} (the live household may simply have moved on since ${r.manifest.created}):\n`);
+            for (const d of r.differences)
+                io.stdout(`  ${d.what}: live ${JSON.stringify(d.live)}, restored ${JSON.stringify(d.restored)}\n`);
+            return 1;
+        }
+        const home = flags(argv, '--to')[0] ?? householdHome(io.env);
+        const r = await restoreBundle({ file, identity, home, env: io.env });
+        io.stdout(`Restored the household (${r.manifest.household.agents.join(', ')}, bundle from ${r.manifest.created}) to ${r.home}.\n`);
+        for (const p of r.pieces)
+            io.stdout(`  piece ${p.name}: ${p.restored ? 'restored' : `not restored (${p.reason})`}\n`);
+        return 0;
+    }
+    catch (err) {
+        if (err instanceof BundleError) {
+            io.stderr(`${err.message}\n`);
+            return 1;
+        }
+        throw err;
+    }
+}

package/dist/cli/index.js

@@ -34,6 +34,8 @@ Commands:
   pieces            List installed pieces (loom-<name> on PATH)
   household         The household: agents and the default (docs/specs/household.md)
   token             Mint, list and revoke the household's tokens
+  export            Write the whole household to one encrypted bundle
+  restore           Lay a bundle down in an empty LOOM_HOME, or --drill it
 
 Pieces: \`loom <name> ...\` runs an installed extension, loom-<name> on PATH
 (e.g. loom tasks list). Core commands always win. See docs/extensions.md.
@@ -208,6 +210,14 @@ async function dispatch(sub, rest, io) {
             const { runToken } = await import('./household.js');
             return runToken(rest, io);
         }
+        case 'export': {
+            const { runExport } = await import('./bundle.js');
+            return runExport(rest, io);
+        }
+        case 'restore': {
+            const { runRestore } = await import('./bundle.js');
+            return runRestore(rest, io);
+        }
         default:
             io.stderr(`Subcommand not implemented yet: ${sub}\n`);
             return 2;

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', 'pieces', 'household', 'token'];
+export declare const SUBCOMMANDS: readonly ['wake', 'recall', 'remember', 'forget', 'update', 'memory', 'knowledge', 'person', 'update-identity', 'bootstrap', 'serve', 'inject', 'harness', 'install', 'doctor', 'migrate', 'pieces', 'household', 'token', 'export', 'restore'];
 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', 'pieces', 'household', 'token',
+    'install', 'doctor', 'migrate', 'pieces', 'household', 'token', 'export', 'restore',
 ];

package/dist/household.d.ts

@@ -60,10 +60,12 @@ export declare function revokeToken(h: Household, label: string, now?: Date): To
  * time, and records when a token was last used, at most once a minute.
  */
 export declare class TokenResolver {
-    private readonly h;
     private cache;
     private lastTouch;
-    constructor(h: Household);
+    private readonly get;
+    /** A household, or a function returning the current one (re-read as household.json changes). */
+    constructor(h: Household | (() => Household));
+    private get h();
     private current;
     /**
      * The role for a presented token, or null. Revoked tokens and roles naming a
@@ -115,3 +117,9 @@ export declare function commonsProblem(h: Household): string | null;
  * stopped.
  */
 export declare function moveKnowledgeToCommons(h: Household, agent: string): string | null;
+/**
+ * The household at `home`, re-read whenever household.json changes, so an
+ * agent added while a daemon runs is served without a restart. Keeps the
+ * last good copy if the file is briefly unreadable mid-write.
+ */
+export declare function liveHousehold(initial: Household): () => Household;

package/dist/household.js

@@ -254,12 +254,14 @@ export function revokeToken(h, label, now = new Date()) {
  * time, and records when a token was last used, at most once a minute.
  */
 export class TokenResolver {
-    h;
     cache = null;
     lastTouch = new Map();
+    get;
+    /** A household, or a function returning the current one (re-read as household.json changes). */
     constructor(h) {
-        this.h = h;
+        this.get = typeof h === 'function' ? h : () => h;
     }
+    get h() { return this.get(); }
     current() {
         const path = join(this.h.home, TOKENS_FILE);
         let key;
@@ -457,3 +459,27 @@ export function moveKnowledgeToCommons(h, agent) {
         return to;
     });
 }
+/**
+ * The household at `home`, re-read whenever household.json changes, so an
+ * agent added while a daemon runs is served without a restart. Keeps the
+ * last good copy if the file is briefly unreadable mid-write.
+ */
+export function liveHousehold(initial) {
+    let current = initial;
+    let key = '';
+    return () => {
+        try {
+            const st = statSync(join(initial.home, HOUSEHOLD_FILE));
+            const k = `${st.ino}:${st.size}:${st.mtimeMs}`;
+            if (k !== key) {
+                const next = loadHousehold(initial.home);
+                if (next) {
+                    current = next;
+                    key = k;
+                }
+            }
+        }
+        catch { /* keep the last good one */ }
+        return current;
+    };
+}

package/dist/transport/http-server.js

@@ -42,7 +42,7 @@ import { handleCliBody } from './cli-endpoint.js';
 import { handleUi, isUiRequest, legacyUiAuth } from '../ui/handler.js';
 import { createKnowledgeOnlyServer } from './knowledge-server.js';
 import { hasUnsplitPeople } from '../backends/people-household.js';
-import { agentDir, assertRealAgentDir, commonsProblem, roleString, TokenResolver } from '../household.js';
+import { agentDir, assertRealAgentDir, commonsProblem, liveHousehold, roleString, TokenResolver } from '../household.js';
 import { createHash, timingSafeEqual as cryptoTimingSafeEqual } from 'node:crypto';
 import { assertSafeBind, checkBearer, checkBearerMulti, checkPayloadSize, DEFAULT_MAX_BODY_BYTES, } from './guards.js';
 /**
@@ -152,7 +152,9 @@ export async function startHttpServer(opts) {
             }
         }
     }
-    const resolver = household ? new TokenResolver(household) : undefined;
+    // Read fresh on each use: an agent added from the page is served at once.
+    const live = household ? liveHousehold(household) : undefined;
+    const resolver = live ? new TokenResolver(live) : undefined;
     const ownerDigest = opts.token ? createHash('sha256').update(opts.token).digest() : undefined;
     /** Resolve a household caller: 401 (no/unknown token), 403 (not allowed there) or 404 (no such agent). */
     function callerFor(header, target) {
@@ -175,7 +177,7 @@ export async function startHttpServer(opts) {
         }
         if (!role)
             return { status: 401, error: 'unauthorized: bearer token not recognized' };
-        const h = household;
+        const h = live();
         if (role.kind === 'peer') {
             if (target)
                 return { status: 403, error: 'forbidden: a peer token reaches the commons only' };
@@ -317,6 +319,7 @@ export async function startHttpServer(opts) {
                     contextDir: opts.contextDir,
                     auth: uiAuth,
                     env: process.env,
+                    household: live,
                 });
             }
             // Household: `/agents/<name>/…` names the agent (the owner's way to

package/dist/ui/core.d.ts

@@ -9,6 +9,8 @@ export interface CoreOptions {
 }
 /** "Sat Oct 24, 12:09 pm" */
 export declare function when(iso: string | null, tz: string): string;
+/** "today 12:09 pm", "yesterday", "Oct 19" */
+export declare function ago(iso: string | null, tz: string, nowMs: number): string;
 export interface Home {
     tile: Tile;
     page: Page;

package/dist/ui/core.js

@@ -59,7 +59,7 @@ export function when(iso, tz) {
     return `${p.weekday} ${p.date}, ${p.time}`;
 }
 /** "today 12:09 pm", "yesterday", "Oct 19" */
-function ago(iso, tz, nowMs) {
+export function ago(iso, tz, nowMs) {
     if (!iso || Number.isNaN(Date.parse(iso)))
         return 'never';
     const p = parts(iso, tz);

package/dist/ui/handler.d.ts

@@ -1,10 +1,16 @@
 import type { IncomingMessage, ServerResponse } from 'node:http';
+import { type Household } from '../household.js';
 export interface UiOptions {
     contextDir: string;
     /** Who may log in to the page. */
     auth: UiAuth;
     /** Env for piece discovery and piece processes (PATH decides which pieces exist). */
     env: NodeJS.ProcessEnv;
+    /**
+     * The household, read fresh (an agent added from the page shows up on the
+     * next request). Absent for a plain context dir: the single-agent page.
+     */
+    household?: () => Household;
 }
 /** Whether a request is for the page (see the header for how `/` is shared with MCP). */
 export declare function isUiRequest(req: IncomingMessage, pathname: string): boolean;

package/dist/ui/handler.js

@@ -34,8 +34,10 @@
  */
 import { createHash, createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
 import { agentName, coreAct, corePage, homePage, uiTimeZone } from './core.js';
+import { agentSetup, householdAct, householdHome, householdPeople, householdPerson, knowledgeEntry, knowledgePage, newAgentPage } from './household-pages.js';
+import { agentDir } from '../household.js';
 import { pieceAct, pieceManifests, piecePage } from './pieces.js';
-import { CORE, pieceSource, renderHome, renderLogin, renderPage } from './render.js';
+import { agentSource, CORE, pageHref, pieceSource, renderHome, renderLogin, renderPage } from './render.js';
 import { ID, LIMITS, QUERY_KEY, splitPage, validPath } from './vocab.js';
 const COOKIE = 'loom_ui';
 const LOGIN_MAX_BYTES = 4096;
@@ -54,7 +56,7 @@ const SECURITY_HEADERS = {
     'referrer-policy': 'same-origin',
     'cache-control': 'no-store',
 };
-const PAGE_ROOTS = ['/login', '/logout', '/pieces.json', '/mind', '/people', '/memory', '/p', '/act'];
+const PAGE_ROOTS = ['/login', '/logout', '/pieces.json', '/mind', '/people', '/memory', '/p', '/act', '/knowledge', '/a', '/new-agent'];
 /** Whether a request is for the page (see the header for how `/` is shared with MCP). */
 export function isUiRequest(req, pathname) {
     if (pathname === '/ui' || pathname.startsWith('/ui/'))
@@ -241,6 +243,23 @@ function chrome(opts, pieces, skipped, current, csrf, flash) {
     const tabs = pieces.filter(hasPages)
         .map((p) => ({ label: p.manifest.tab?.label ?? p.piece, href: `/p/${p.piece}`, current: current === `p/${p.piece}`, piece: true }))
         .sort((a, b) => a.label.localeCompare(b.label));
+    const h = opts.household?.();
+    if (h) {
+        return {
+            agent: h.owner ? `${h.owner}'s household` : 'household',
+            nav: [
+                { label: 'Home', href: '/', current: current === '', piece: false },
+                { label: 'Knowledge', href: '/knowledge', current: current === 'knowledge', piece: false },
+                { label: 'People', href: '/people', current: current === 'people', piece: false },
+                ...h.agents.map((a) => ({ label: agentName(agentDir(h, a)), href: `/a/${a}`, current: current === `a/${a}`, piece: true })),
+                ...tabs,
+            ],
+            clock: clock(),
+            csrf,
+            flash,
+            skipped,
+        };
+    }
     return {
         agent: agentName(opts.contextDir),
         nav: [
@@ -257,12 +276,8 @@ function chrome(opts, pieces, skipped, current, csrf, flash) {
 }
 /** Where to land after an action: the page the piece names, or back where the form was. */
 function landing(source, result, back) {
-    const s = (result.page !== undefined ? splitPage(result.page) : null) ?? splitPage(back);
-    const core = s?.core || source.id === 'loom';
-    const path = s?.path ?? '';
-    const q = s ? new URLSearchParams(s.query).toString() : '';
-    const base = core ? `/${path}` : `/p/${source.id}${path ? `/${path}` : ''}`;
-    return q ? `${base}?${q}` : base;
+    const link = result.page !== undefined && splitPage(result.page) ? result.page : splitPage(back) ? back : '';
+    return pageHref(link, source);
 }
 function withFlash(to, id) {
     return `${to}${to.includes('?') ? '&' : '?'}_flash=${id}`;
@@ -334,12 +349,16 @@ export async function handleUi(req, res, pathname, opts) {
         return send(res, 401, 'text/plain', 'unauthorized');
     }
     const url = new URL(req.url ?? pathname, 'http://loom.invalid');
-    if (pathname.startsWith('/act/')) {
+    const hh = opts.household?.();
+    const agentAct = hh ? /^\/a\/([a-z][a-z0-9-]{0,39})\/act\/loom$/.exec(pathname) : null;
+    if (pathname.startsWith('/act/') || agentAct) {
         if (req.method !== 'POST')
             return send(res, 405, 'text/plain', 'method not allowed');
         if (!sameOrigin(req))
             return send(res, 403, 'text/plain', 'forbidden: cross-site request');
-        const sourceId = pathname.slice('/act/'.length);
+        if (agentAct && !hh.agents.includes(agentAct[1]))
+            return send(res, 404, 'text/plain', 'not found');
+        const sourceId = agentAct ? 'loom' : pathname.slice('/act/'.length);
         if (sourceId !== 'loom' && !ID.test(sourceId))
             return send(res, 404, 'text/plain', 'not found');
         const form = await readForm(req, ACT_MAX_BYTES);
@@ -368,7 +387,17 @@ export async function handleUi(req, res, pathname, opts) {
             return send(res, 400, 'text/plain', 'too many fields');
         let source;
         let result;
-        if (sourceId === 'loom') {
+        if (agentAct) {
+            // One agent's own actions (archive, ratify, reject), on its stack.
+            source = agentSource(agentAct[1]);
+            result = await coreAct(agentDir(hh, agentAct[1]), action, fields);
+        }
+        else if (sourceId === 'loom' && hh) {
+            // The household's: tokens and agents.
+            source = CORE;
+            result = await householdAct(hh, action, fields);
+        }
+        else if (sourceId === 'loom') {
             source = CORE;
             result = await coreAct(opts.contextDir, action, fields);
         }
@@ -403,6 +432,61 @@ export async function handleUi(req, res, pathname, opts) {
     const { pieces, skipped } = await pieceManifests(opts.env);
     const skippedNames = skipped.map((s) => s.piece);
     const html = (body, status = 200) => send(res, status, 'text/html; charset=utf-8', body);
+    if (hh) {
+        const ctxOf = (path, source = CORE) => ({ source, path, query, csrf });
+        const send200 = (page, current, ctx) => html(renderPage(page, ctx, chrome(opts, pieces, skippedNames, current, csrf, flash)), page.title === 'Not found' && page.sections.length === 0 ? 404 : 200);
+        if (pathname === '/') {
+            const home = householdHome(hh);
+            const tiles = [
+                ...home.tiles.map((t) => ({ ...t, source: CORE })),
+                ...pieces.filter((p) => p.manifest.tile).map((p) => ({ ...p.manifest.tile, source: pieceSource(p.piece) })),
+            ];
+            const asks = pieces.flatMap((p) => p.manifest.asks.map((a) => ({ ...a, source: pieceSource(p.piece) })));
+            return html(renderHome(home.page, ctxOf(''), chrome(opts, pieces, skippedNames, '', csrf, flash), tiles, asks));
+        }
+        if (pathname === '/knowledge')
+            return send200(knowledgePage(hh, query), 'knowledge', ctxOf('knowledge'));
+        if (pathname.startsWith('/knowledge/')) {
+            const slug = decode(pathname.slice('/knowledge/'.length));
+            return send200(slug && validPath(slug) ? knowledgeEntry(hh, slug) : notFound, 'knowledge', ctxOf('knowledge'));
+        }
+        if (pathname === '/people')
+            return send200(householdPeople(hh), 'people', ctxOf('people'));
+        if (pathname.startsWith('/people/')) {
+            const slug = decode(pathname.slice('/people/'.length));
+            return send200(slug && /^[a-z0-9][a-z0-9-]*$/.test(slug) ? householdPerson(hh, slug) : notFound, 'people', ctxOf(`people/${slug}`));
+        }
+        if (pathname === '/new-agent')
+            return send200(newAgentPage(), '', ctxOf('new-agent'));
+        const a = /^\/a\/([a-z][a-z0-9-]{0,39})(?:\/(.*))?$/.exec(pathname);
+        if (a) {
+            const agent = a[1];
+            if (!hh.agents.includes(agent))
+                return send200(notFound, '', ctxOf(''));
+            const rest = decode(a[2] ?? '') ?? '\0';
+            const dir = agentDir(hh, agent);
+            const src = agentSource(agent);
+            if (rest === '') {
+                const home = homePage(dir, query);
+                home.page.sections.unshift({ id: 'agent-nav', side: true, blocks: [{ type: 'list', items: [
+                                { text: 'Mind', meta: 'what it wakes up holding, and why', page: 'mind' },
+                                { text: 'People', meta: 'as it sees them', page: 'people' },
+                                { text: 'Setup', meta: 'identity, tokens, health', page: `loom:a/${agent}/setup` },
+                            ] }] });
+                const tiles = [{ ...home.tile, source: src }];
+                return html(renderHome(home.page, ctxOf('', src), chrome(opts, pieces, skippedNames, `a/${agent}`, csrf, flash), tiles, []));
+            }
+            if (rest === 'setup')
+                return send200(agentSetup(hh, agent), `a/${agent}`, ctxOf(`a/${agent}/setup`, CORE));
+            const page = validPath(rest) ? corePage(dir, rest, query) : null;
+            return send200(page ?? notFound, `a/${agent}`, ctxOf(validPath(rest) ? rest : '', src));
+        }
+        // loom's own single-agent addresses land on the default agent's view.
+        if (pathname === '/mind' || pathname.startsWith('/memory/')) {
+            res.writeHead(302, { location: `/a/${hh.default}${pathname}${url.search}`, ...SECURITY_HEADERS });
+            return void res.end();
+        }
+    }
     if (pathname === '/') {
         const home = homePage(opts.contextDir, query);
         const tiles = [

package/dist/ui/household-pages.d.ts

@@ -0,0 +1,15 @@
+import { type Household } from '../household.js';
+import { type CoreOptions } from './core.js';
+import { type ActResult, type Page, type Tile } from './vocab.js';
+export declare function householdHome(h: Household, opts?: CoreOptions): {
+    tiles: Tile[];
+    page: Page;
+};
+export declare function knowledgePage(h: Household, query: Record<string, string>, opts?: CoreOptions): Page;
+export declare function knowledgeEntry(h: Household, slug: string, opts?: CoreOptions): Page;
+export declare function householdPeople(h: Household): Page;
+export declare function householdPerson(h: Household, slug: string, opts?: CoreOptions): Page;
+export declare function agentSetup(h: Household, agent: string, opts?: CoreOptions): Page;
+export declare function newAgentPage(): Page;
+/** The owner's household actions: tokens and agents. */
+export declare function householdAct(h: Household, action: string, fields: Record<string, string>): Promise<ActResult>;