@jbarket/loomai 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -12,6 +12,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.13.0] - 2026-10-24
+
+### Added
+
+- **The household page** (docs/specs/household.md, phase 4). In a
+  household, the page is the owner's view of all of it:
+  - **Home:** every agent (what it's doing, from its tape), the tape across
+    all of them, and the commons.
+  - **Knowledge:** the commons' pages, by domain.
+  - **People:** the directory, with every agent's relationship to each
+    person, and who changed the shared entry.
+  - **`/a/<agent>`:** that agent's view, plus **Setup**: its identity
+    (read-only), its tokens (make one, shown once; revoke) and health.
+  - **Add an agent:** creates its stack and its first token.
+
+  A daemon now re-reads household.json as it changes, so a new agent is
+  served at once. The old single-agent addresses (`/mind`, `/memory/…`)
+  land on the default agent's view. A plain context dir keeps the
+  single-agent page.
+
 ## [0.12.0] - 2026-10-24
 
 ### Added
@@ -751,7 +771,8 @@ Initial public release.
   stack and all added external-service dependencies or operational
   overhead.
 
-[Unreleased]: https://github.com/sleepunit-agents/loom/compare/v0.12.0...HEAD
+[Unreleased]: https://github.com/sleepunit-agents/loom/compare/v0.13.0...HEAD
+[0.13.0]: https://github.com/sleepunit-agents/loom/compare/v0.12.0...v0.13.0
 [0.12.0]: https://github.com/sleepunit-agents/loom/compare/v0.11.0...v0.12.0
 [0.11.0]: https://github.com/sleepunit-agents/loom/compare/v0.10.0...v0.11.0
 [0.10.0]: https://github.com/sleepunit-agents/loom/compare/v0.9.2...v0.10.0

package/README.md

@@ -402,6 +402,19 @@ replace, never read back), the chat bridges. Nothing to configure: install a
 piece and it shows up, uninstall it and it's gone. loom never names a piece
 ([`docs/extensions.md`](docs/extensions.md), "The page").
 
+**In a household** ([`docs/specs/household.md`](docs/specs/household.md))
+the page is the owner's view of all of it:
+- **Home** shows every agent (what it's doing, from its tape), the tape
+  across all of them, and the commons at a glance.
+- **Knowledge** is the commons' pages.
+- **People** is the directory, and each person's page shows every agent's
+  relationship with them.
+- **`/a/<agent>`** is one agent's own view (its tape, Mind and people) plus
+  **Setup**: its identity (read-only), its tokens (make one, shown once;
+  revoke), and health.
+- **Add an agent** creates its stack and hands over its first token. It's
+  served at once, without a restart.
+
 **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

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>;

package/dist/ui/household-pages.js

@@ -0,0 +1,438 @@
+/**
+ * The owner's view of a household (docs/specs/household.md, "The page").
+ *
+ *   /                      Home: every agent, what each is doing, the tape
+ *                          across all of them, the commons at a glance
+ *   /knowledge[/<slug>]    the commons' knowledge
+ *   /people[/<slug>]       the directory, each person with every agent's relationship
+ *   /a/<agent>/…           one agent's view (its tape, Mind, its people), plus Setup
+ *   /new-agent             add an agent
+ *
+ * Only the owner sees these (the page is owner-only), which is why a person's
+ * page here may show every agent's relationship: an agent's own tools never
+ * can.
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import BetterSqlite3 from 'better-sqlite3';
+import { addAgent, AGENT_NAME, agentDir, commonsKnowledgePath, createToken, HouseholdError, loadTokens, parseRole, revokeToken, } from '../household.js';
+import { commonsPeoplePath } from '../backends/people-household.js';
+import { fieldState, PeopleStore } from '../backends/people.js';
+import { resolveSqliteDbPath } from '../config.js';
+import { bootstrap } from '../tools/bootstrap.js';
+import { ago, agentName, uiTimeZone, when } from './core.js';
+import { tapeRows } from './data.js';
+import { validPath } from './vocab.js';
+const HOME_TAPE = 30;
+function agentLink(agent, path = '') {
+    return `loom:a/${agent}${path ? `/${path}` : ''}`;
+}
+function count(path, sql, ...args) {
+    if (!existsSync(path))
+        return 0;
+    const db = new BetterSqlite3(path, { readonly: true, fileMustExist: true });
+    try {
+        return db.prepare(sql).get(...args).n;
+    }
+    catch {
+        return 0;
+    }
+    finally {
+        db.close();
+    }
+}
+function value(v) {
+    return Array.isArray(v) ? v.join(', ') : String(v);
+}
+// ─── Home ────────────────────────────────────────────────────────────────────
+export function householdHome(h, opts = {}) {
+    const tz = opts.timeZone ?? uiTimeZone();
+    const nowMs = opts.nowMs ?? Date.now();
+    const agents = h.agents.map((a) => {
+        const dir = agentDir(h, a);
+        const tape = tapeRows(dir, 24, nowMs);
+        return {
+            agent: a,
+            name: agentName(dir),
+            tape,
+            memories: count(resolveSqliteDbPath(dir), "SELECT COUNT(*) AS n FROM memories WHERE archived = 0 AND category != 'episode'"),
+        };
+    });
+    const tape = agents
+        .flatMap((x) => x.tape.map((e) => ({ ...e, agent: x.agent, name: x.name })))
+        .sort((a, b) => (a.created < b.created ? 1 : -1));
+    const pages = count(commonsKnowledgePath(h), "SELECT COUNT(*) AS n FROM pages WHERE status = 'active'");
+    const people = count(commonsPeoplePath(h), 'SELECT COUNT(*) AS n FROM people WHERE archived_at IS NULL');
+    const sections = [
+        {
+            id: 'agents',
+            title: 'Agents',
+            blocks: [
+                {
+                    type: 'list',
+                    items: agents.map((x) => {
+                        const last = x.tape[0];
+                        return {
+                            text: x.name,
+                            meta: last ? `${ago(last.created, tz, nowMs)} · ${last.where} · ${last.title}` : 'quiet for a day',
+                            badge: `${x.tape.length} today`,
+                            page: agentLink(x.agent),
+                        };
+                    }),
+                },
+                { type: 'link', text: 'Add an agent', page: 'loom:new-agent' },
+            ],
+        },
+        {
+            id: 'tape',
+            title: 'What\'s happening, everywhere',
+            blocks: tape.length
+                ? [{
+                        type: 'list',
+                        items: tape.slice(0, HOME_TAPE).map((e) => ({
+                            text: e.title,
+                            meta: `${e.name} · ${ago(e.created, tz, nowMs)} · ${e.where}`,
+                            page: validPath(`a/${e.agent}/memory/${e.ref}`) ? agentLink(e.agent, `memory/${e.ref}`) : undefined,
+                        })),
+                    },
+                    ...(tape.length > HOME_TAPE ? [{ type: 'text', text: `and ${tape.length - HOME_TAPE} more today; each agent's page has its whole tape`, tone: 'muted' }] : [])]
+                : [{ type: 'text', text: 'Nothing in the last day.', tone: 'muted' }],
+        },
+        {
+            id: 'commons',
+            title: 'The commons',
+            side: true,
+            blocks: [
+                { type: 'stats', items: [
+                        { label: 'knowledge pages', value: pages.toLocaleString('en-US'), page: 'loom:knowledge' },
+                        { label: 'people', value: String(people), page: 'loom:people' },
+                    ] },
+                { type: 'text', text: 'Shared by every agent: facts about the world, and who people are and where to reach them.', tone: 'muted' },
+            ],
+        },
+    ];
+    return {
+        tiles: [
+            { label: 'Agents', value: String(h.agents.length), detail: agents.map((x) => x.name).join(', '), page: '' },
+            { label: 'Commons', value: `${pages.toLocaleString('en-US')} pages`, detail: `${people} people`, page: 'knowledge' },
+        ],
+        page: { title: 'Home', sections },
+    };
+}
+export function knowledgePage(h, query, opts = {}) {
+    const tz = opts.timeZone ?? uiTimeZone();
+    const nowMs = opts.nowMs ?? Date.now();
+    const path = commonsKnowledgePath(h);
+    if (!existsSync(path))
+        return { title: 'Knowledge', intro: 'The commons has no knowledge yet.', sections: [] };
+    const db = new BetterSqlite3(path, { readonly: true, fileMustExist: true });
+    try {
+        const domains = db.prepare("SELECT substr(domain, 1, instr(domain || '/', '/') - 1) AS top, COUNT(*) AS n FROM pages WHERE status = 'active' GROUP BY top ORDER BY n DESC LIMIT 12").all();
+        const pick = domains.some((d) => d.top === query.domain) ? query.domain : '';
+        const rows = db.prepare(`SELECT slug, title, domain, updated, sourcing FROM pages WHERE status = 'active' ${pick ? "AND (domain = ? OR domain LIKE ? || '/%')" : ''} ORDER BY updated DESC LIMIT 60`).all(...(pick ? [pick, pick] : []));
+        const total = count(path, "SELECT COUNT(*) AS n FROM pages WHERE status = 'active'");
+        return {
+            title: 'Knowledge',
+            intro: 'Facts about the world, shared by every agent in the household. Newest first.',
+            sections: [
+                { id: 'filter', blocks: [
+                        { type: 'filters', param: 'domain', options: [{ value: '', label: 'Everything' }, ...domains.map((d) => ({ value: d.top, label: `${d.top} (${d.n})` }))] },
+                        { type: 'text', text: `${total.toLocaleString('en-US')} pages${pick ? `, ${rows.length} shown in ${pick}` : ''}`, tone: 'muted' },
+                    ] },
+                { id: 'pages', blocks: [{
+                            type: 'list',
+                            items: rows.map((r) => ({
+                                text: r.title,
+                                meta: `${r.domain} · ${ago(r.updated, tz, nowMs)}${r.sourcing ? ` · ${r.sourcing}` : ''}`,
+                                page: validPath(`knowledge/${r.slug}`) ? `loom:knowledge/${r.slug}` : undefined,
+                            })),
+                        }] },
+            ],
+        };
+    }
+    finally {
+        db.close();
+    }
+}
+export function knowledgeEntry(h, slug, opts = {}) {
+    const tz = opts.timeZone ?? uiTimeZone();
+    const path = commonsKnowledgePath(h);
+    if (!existsSync(path))
+        return { title: 'Not found', sections: [] };
+    const db = new BetterSqlite3(path, { readonly: true, fileMustExist: true });
+    try {
+        const r = db.prepare("SELECT slug, title, domain, body, updated, sourcing, created_by, author, verified_at FROM pages WHERE slug = ? AND status = 'active'").get(slug);
+        if (!r)
+            return { title: 'Not found', sections: [] };
+        const cites = (() => {
+            try {
+                return db.prepare('SELECT claim, source_kind, source_locator FROM citations c JOIN pages p ON p.id = c.page_id WHERE p.slug = ? LIMIT 40').all(slug);
+            }
+            catch {
+                return [];
+            }
+        })();
+        const body = r.body ?? '';
+        const chunks = body.match(/[\s\S]{1,1900}/g) ?? [''];
+        return {
+            title: r.title,
+            sections: [
+                { id: 'body', blocks: chunks.slice(0, 18).map((c) => ({ type: 'text', text: c })) },
+                ...(cites.length ? [{ id: 'citations', title: 'Sources', blocks: [{ type: 'list', items: cites.map((c) => ({ text: c.claim, meta: `${c.source_kind}${c.source_locator ? ` · ${c.source_locator}` : ''}`, ...(c.source_locator && /^https?:\/\//.test(c.source_locator) ? { href: c.source_locator } : {}) })) }] }] : []),
+                { id: 'record', side: true, blocks: [{ type: 'kv', items: [
+                                { label: 'domain', value: r.domain },
+                                { label: 'sourcing', value: r.sourcing ?? 'unknown' },
+                                { label: 'updated', value: when(r.updated, tz) },
+                                { label: 'verified', value: when(r.verified_at ?? null, tz) },
+                                { label: 'written by', value: r.created_by ?? r.author ?? 'unknown' },
+                                { label: 'slug', value: r.slug },
+                            ] }] },
+            ],
+        };
+    }
+    finally {
+        db.close();
+    }
+}
+// ─── People ──────────────────────────────────────────────────────────────────
+function directory(h) {
+    const path = commonsPeoplePath(h);
+    return existsSync(path) ? new PeopleStore({ dbPath: path, readonly: true }) : null;
+}
+/** Each agent's relationship with a person, for the owner's view. */
+function relationships(h, slug) {
+    return h.agents.flatMap((a) => {
+        const path = resolveSqliteDbPath(agentDir(h, a));
+        if (!existsSync(path))
+            return [];
+        const st = new PeopleStore({ dbPath: path, readonly: true });
+        try {
+            const row = st.getRow(slug);
+            return row ? [{ agent: a, name: agentName(agentDir(h, a)), row, memories: st.memoriesSince(slug, row.synthesized_at) }] : [];
+        }
+        catch {
+            return [];
+        }
+        finally {
+            st.close();
+        }
+    });
+}
+export function householdPeople(h) {
+    const dir = directory(h);
+    if (!dir)
+        return { title: 'People', intro: 'Nobody in the directory yet.', sections: [] };
+    try {
+        const list = dir.list();
+        return {
+            title: 'People',
+            intro: 'One entry per person, shared by every agent: who they are and where to reach them. Each agent keeps its own relationship with them.',
+            sections: [{ id: 'everyone', blocks: [{
+                            type: 'list',
+                            items: list.map((p) => {
+                                const rel = relationships(h, p.slug).map((r) => r.name);
+                                const flag = [p.stale ? `${p.stale} stale` : '', p.unverified ? `${p.unverified} unverified` : ''].filter(Boolean).join(' · ');
+                                return {
+                                    text: p.name,
+                                    meta: rel.length ? `known to ${rel.join(', ')}` : 'no agent has a relationship yet',
+                                    badge: flag || undefined,
+                                    tone: flag ? 'warn' : undefined,
+                                    page: validPath(`people/${p.slug}`) ? `loom:people/${p.slug}` : undefined,
+                                };
+                            }),
+                        }] }],
+        };
+    }
+    finally {
+        dir.close();
+    }
+}
+export function householdPerson(h, slug, opts = {}) {
+    const tz = opts.timeZone ?? uiTimeZone();
+    const nowMs = opts.nowMs ?? Date.now();
+    const dir = directory(h);
+    if (!dir)
+        return { title: 'Not found', sections: [] };
+    try {
+        const d = dir.getRow(slug);
+        if (!d)
+            return { title: 'Not found', sections: [] };
+        const where = Object.entries(d.card.where ?? {}).sort(([a], [b]) => a.localeCompare(b));
+        const facts = Object.entries(d.card.how ?? {});
+        const history = dir.history(slug).slice(0, 12);
+        const sections = [];
+        if (where.length) {
+            sections.push({ id: 'where', title: 'Where to reach them', blocks: [{
+                        type: 'table', columns: ['where', 'value', 'from', 'checked'],
+                        rows: where.map(([k, env]) => {
+                            const s = fieldState(env, nowMs);
+                            return [k, value(env.value), env.source ?? '', s.kind === 'ok' ? `ok, ${ago(env.verified_at ?? null, tz, nowMs)}` : s.kind === 'stale' ? `stale ${s.days}d` : 'unverified'];
+                        }),
+                    }] });
+        }
+        for (const r of relationships(h, slug)) {
+            const how = Object.entries(r.row.card.how ?? {});
+            const blocks = [];
+            if (r.row.card.summary)
+                blocks.push({ type: 'text', text: r.row.card.summary });
+            if (how.length)
+                blocks.push({ type: 'kv', items: how.map(([k, v]) => ({ label: k, value: value(v) })) });
+            if (r.row.card.may?.length)
+                blocks.push({ type: 'list', items: r.row.card.may.map((m) => ({ text: m.text, meta: `said by ${m.source}` })) });
+            blocks.push({ type: 'text', text: `${r.memories} memor${r.memories === 1 ? 'y' : 'ies'} newer than this view · updated ${ago(r.row.updated, tz, nowMs)}`, tone: r.memories ? 'warn' : 'muted' });
+            if (!r.row.card.summary && !how.length && !r.row.card.may?.length)
+                blocks.unshift({ type: 'text', text: 'Knows of them; nothing more yet.', tone: 'muted' });
+            blocks.push({ type: 'link', text: `${r.name}'s view`, page: agentLink(r.agent, `people/${slug}`) });
+            sections.push({ id: `rel-${r.agent}`, title: `${r.name}`, blocks });
+        }
+        if (facts.length)
+            sections.push({ id: 'facts', title: 'Facts', side: true, blocks: [{ type: 'kv', items: facts.map(([k, v]) => ({ label: k, value: value(v) })) }] });
+        if (history.length) {
+            sections.push({ id: 'changes', title: 'Changes to the shared entry', side: true, blocks: [{
+                        type: 'list', items: history.map((r) => ({ text: `${r.actor ?? 'someone'} ${r.op === 'write' ? 'changed it' : r.op}`, meta: ago(r.replaced_at, tz, nowMs) })),
+                    }] });
+        }
+        return { title: d.card.name, intro: 'The shared entry, then how each agent sees them.', sections };
+    }
+    finally {
+        dir.close();
+    }
+}
+// ─── An agent's Setup ────────────────────────────────────────────────────────
+/**
+ * The creed, folded by its own headings: one fold per `#`/`##` section,
+ * each split at paragraph breaks to fit a block, never mid-word.
+ */
+function identitySections(md) {
+    if (!md.trim())
+        return [{ type: 'text', text: '(no IDENTITY.md)', tone: 'muted' }];
+    const sections = [];
+    for (const line of md.split('\n')) {
+        const m = /^#{1,2}\s+(.+)$/.exec(line);
+        if (m || sections.length === 0)
+            sections.push({ title: m ? m[1].trim() : 'Identity', body: '' });
+        if (!m)
+            sections[sections.length - 1].body += `${line}\n`;
+    }
+    return sections.filter((x) => x.body.trim()).slice(0, 16).map((x) => {
+        const chunks = [];
+        let cur = '';
+        for (const para of x.body.trim().split(/\n\s*\n/)) {
+            if (cur && cur.length + para.length + 2 > 1900) {
+                chunks.push(cur);
+                cur = '';
+            }
+            cur = cur ? `${cur}\n\n${para}` : para.slice(0, 1900);
+        }
+        if (cur)
+            chunks.push(cur);
+        return { type: 'details', summary: x.title.slice(0, 200), blocks: chunks.slice(0, 19).map((c) => ({ type: 'text', text: c })) };
+    });
+}
+export function agentSetup(h, agent, opts = {}) {
+    const tz = opts.timeZone ?? uiTimeZone();
+    const dir = agentDir(h, agent);
+    let identity = '';
+    try {
+        identity = readFileSync(join(dir, 'IDENTITY.md'), 'utf-8');
+    }
+    catch { /* none */ }
+    const harnesses = (() => { try {
+        return readdirSync(join(dir, 'harnesses')).filter((f) => f.endsWith('.md')).map((f) => f.slice(0, -3));
+    }
+    catch {
+        return [];
+    } })();
+    const tokens = loadTokens(h.home).filter((t) => t.role === `agent:${agent}` || (agent === h.default && t.role === 'owner'));
+    const dbSize = (() => { try {
+        return statSync(resolveSqliteDbPath(dir)).size;
+    }
+    catch {
+        return 0;
+    } })();
+    const memories = count(resolveSqliteDbPath(dir), "SELECT COUNT(*) AS n FROM memories WHERE archived = 0 AND category != 'episode'");
+    return {
+        title: `${agentName(dir)} · Setup`,
+        sections: [
+            { id: 'identity', title: 'Identity', blocks: [
+                    { type: 'text', text: 'Read-only here: an agent\'s creed is changed by the agent (update_identity) or by hand, never from a web page.', tone: 'muted' },
+                    ...identitySections(identity),
+                ] },
+            { id: 'tokens', title: 'Tokens', blocks: [
+                    tokens.length
+                        ? { type: 'details', summary: `${tokens.filter((t) => !t.revoked).length} live, ${tokens.filter((t) => t.revoked).length} revoked`, blocks: tokens.map((t) => (t.revoked
+                                ? { type: 'text', text: `${t.label} (${t.role}) · revoked ${when(t.revoked, tz)}`, tone: 'muted' }
+                                : { type: 'callout', title: `${t.label} · ${t.role}`, text: `created ${when(t.created, tz)} · ${t.last_used ? `last used ${when(t.last_used, tz)}` : 'never used'}` })) }
+                        : { type: 'text', text: 'No tokens yet.', tone: 'muted' },
+                    ...tokens.filter((t) => !t.revoked).map((t) => ({ type: 'buttons', items: [{ action: 'revoke-token', label: `Revoke "${t.label}"`, tone: 'danger', fields: { label: t.label } }] })),
+                    { type: 'form', action: 'create-token', title: 'New token', submit: 'Create token', hidden: { agent },
+                        note: 'Shown once, on the next page. Give it to the harness or house that will be this agent; loom keeps only its fingerprint.',
+                        fields: [{ name: 'label', label: 'Label', kind: 'text', hint: 'Where it goes, e.g. "Art · laptop".', required: true }] },
+                ] },
+            { id: 'health', side: true, title: 'Health', blocks: [{ type: 'kv', items: [
+                            { label: 'memories', value: memories.toLocaleString('en-US') },
+                            { label: 'memory store', value: `${(dbSize / 1048576).toFixed(1)} MB` },
+                            { label: 'harnesses', value: harnesses.join(', ') || 'none' },
+                            { label: 'directory', value: `agents/${agent}` },
+                            { label: 'default agent', value: agent === h.default ? 'yes' : 'no' },
+                        ] }] },
+        ],
+    };
+}
+// ─── Adding an agent ─────────────────────────────────────────────────────────
+export function newAgentPage() {
+    return {
+        title: 'Add an agent',
+        intro: 'A new stack in this household: its own identity, memory and relationships, sharing the commons. You get its first token on the next page.',
+        sections: [{ id: 'form', blocks: [{
+                        type: 'form', action: 'add-agent', submit: 'Create the agent',
+                        fields: [
+                            { name: 'agent', label: 'Short name', kind: 'text', hint: 'Lowercase letters, digits and dashes, e.g. "mark". It names the directory and the token role.', required: true },
+                            { name: 'name', label: 'Name', kind: 'text', hint: 'What it\'s called, e.g. "Visual Mark".', required: true },
+                            { name: 'purpose', label: 'What it\'s for', kind: 'textarea', required: true },
+                            { name: 'voice', label: 'How it talks', kind: 'textarea', hint: 'A line or two. It can change this itself later.', required: true },
+                        ],
+                    }] }],
+    };
+}
+/** The owner's household actions: tokens and agents. */
+export async function householdAct(h, action, fields) {
+    try {
+        if (action === 'create-token') {
+            const agent = fields.agent ?? '';
+            const role = agent === '' ? null : parseRole(`agent:${agent}`);
+            if (!role)
+                return { ok: false, message: 'Name an agent for the token.' };
+            const { token } = createToken(h, { role, label: fields.label ?? '' });
+            return { ok: true, message: `Token for ${agent}, shown this once: ${token}`, page: `loom:a/${agent}/setup` };
+        }
+        if (action === 'revoke-token') {
+            const t = revokeToken(h, fields.label ?? '');
+            const agent = t.role.startsWith('agent:') ? t.role.slice('agent:'.length) : h.default;
+            return { ok: true, message: `Revoked "${t.label}". It stops working on its next request.`, page: `loom:a/${agent}/setup` };
+        }
+        if (action === 'add-agent') {
+            const agent = (fields.agent ?? '').trim();
+            if (!AGENT_NAME.test(agent))
+                return { ok: false, message: 'The short name must be lowercase letters, digits and dashes, starting with a letter.' };
+            if (h.agents.includes(agent))
+                return { ok: false, message: `${agent} is already in the household.` };
+            if (!fields.name?.trim() || !fields.purpose?.trim() || !fields.voice?.trim())
+                return { ok: false, message: 'A name, what it\'s for, and how it talks are all needed.' };
+            const dir = agentDir(h, agent);
+            if (existsSync(dir))
+                return { ok: false, message: `agents/${agent} already exists on disk; add it with loom household add.` };
+            mkdirSync(dir, { recursive: true, mode: 0o700 });
+            await bootstrap(dir, { name: fields.name.trim(), purpose: fields.purpose.trim(), voice: fields.voice.trim(), user: h.owner });
+            const next = addAgent(h, agent);
+            const { token } = createToken(next, { role: { kind: 'agent', agent }, label: `${fields.name.trim()} · first token` });
+            return { ok: true, message: `${fields.name.trim()} is in the household. Its first token, shown this once: ${token}`, page: `loom:a/${agent}/setup` };
+        }
+        return { ok: false, message: `loom has no action "${action}".` };
+    }
+    catch (err) {
+        if (err instanceof HouseholdError)
+            return { ok: false, message: err.message };
+        return { ok: false, message: err.message };
+    }
+}

package/dist/ui/render.d.ts

@@ -6,13 +6,20 @@
  */
 import type { Ask, Page, Tile } from './vocab.js';
 export declare function esc(s: string): string;
-/** Whose page this is: loom's own (`loom`) or a piece's. */
+/**
+ * Whose page this is: loom's own (`loom`) or a piece's. `base` is where its
+ * page links resolve; `act` is where its forms post (one agent's view in a
+ * household posts to that agent).
+ */
 export interface Source {
     id: string;
     base: string;
+    act?: string;
 }
 export declare const CORE: Source;
 export declare const pieceSource: (piece: string) => Source;
+/** One agent's view in a household. */
+export declare const agentSource: (agent: string) => Source;
 export interface RenderContext {
     source: Source;
     /** This page's path within its source, and its query, for filters and for returning after an action. */

package/dist/ui/render.js

@@ -9,6 +9,8 @@ export function esc(s) {
 }
 export const CORE = { id: 'loom', base: '/' };
 export const pieceSource = (piece) => ({ id: piece, base: `/p/${piece}/` });
+/** One agent's view in a household. */
+export const agentSource = (agent) => ({ id: 'loom', base: `/a/${agent}/`, act: `/a/${agent}/act/loom` });
 function qs(query) {
     const p = new URLSearchParams();
     for (const [k, v] of Object.entries(query))
@@ -40,7 +42,7 @@ function hiddenInputs(fields) {
 }
 function actionForm(ctx, action, inner, cls) {
     const back = ctx.path + qs(ctx.query);
-    return `<form class="${cls}" method="post" action="/act/${esc(ctx.source.id)}">${hiddenInputs({ _csrf: ctx.csrf, _action: action, _path: back })}${inner}</form>`;
+    return `<form class="${cls}" method="post" action="${esc(ctx.source.act ?? `/act/${ctx.source.id}`)}">${hiddenInputs({ _csrf: ctx.csrf, _action: action, _path: back })}${inner}</form>`;
 }
 let fieldSeq = 0;
 function renderField(f) {

package/dist/ui/vocab.js

@@ -31,7 +31,7 @@ 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\/.+)$/;
+const CORE_PAGES = /^(|mind|people|people\/[a-z0-9][a-z0-9-]*|memory\/.+|knowledge|knowledge\/.+|new-agent|a\/[a-z][a-z0-9-]{0,39}(|\/mind|\/setup|\/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))

package/package.json

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