@jbarket/loomai 0.9.2 → 0.11.0

package/dist/tools/person.js

@@ -9,7 +9,9 @@
  * loom tool. The CLI (`loom person`) calls the read functions here too.
  */
 import { resolveIdentityName } from '../config.js';
-import { openPeopleStore, personSlugError, PersonCardError, UnreadableCardError, } from '../backends/people.js';
+import { householdOf } from '../household.js';
+import { openHouseholdPeople } from '../backends/people-household.js';
+import { openPeopleStore, PeopleStore, personSlugError, PersonCardError, UnreadableCardError, } from '../backends/people.js';
 const json = (v) => JSON.stringify(v, null, 2);
 /** Slugs validate before anything else, store or no store (criterion 11). */
 function assertSlug(slug) {
@@ -22,9 +24,20 @@ function errorText(e) {
         return `Error: ${e.message}`;
     return `Error: ${e.message ?? String(e)}`;
 }
+/**
+ * The people a context dir sees. In a household: the commons directory plus
+ * this agent's relationships (backends/people-household.ts). Otherwise the
+ * one store in the agent's memories.db, as before.
+ */
+function openPeople(contextDir, opts = {}) {
+    const hh = householdOf(contextDir);
+    if (hh)
+        return openHouseholdPeople(hh.household, hh.agent, contextDir, opts);
+    return openPeopleStore(contextDir, opts);
+}
 function withWritable(contextDir, fn) {
     try {
-        const store = openPeopleStore(contextDir);
+        const store = openPeople(contextDir);
         try {
             return json(fn(store));
         }
@@ -50,12 +63,12 @@ export async function personRestore(contextDir, input) {
     return withWritable(contextDir, (s) => s.restore(input));
 }
 export async function personRevisionRestore(contextDir, input) {
-    return withWritable(contextDir, (s) => s.revisionRestore(input));
+    return withWritable(contextDir, (s) => (s instanceof PeopleStore ? s.revisionRestore({ slug: input.slug, revision_id: input.revision_id }) : s.revisionRestore(input)));
 }
 /** The `person` read. Throws on an invalid slug or an unreadable row; the MCP wrapper turns that into text. */
 export function readPerson(contextDir, slug, includeArchived = false) {
     assertSlug(slug);
-    const store = openPeopleStore(contextDir, { readonly: true });
+    const store = openPeople(contextDir, { readonly: true });
     if (!store)
         return { found: false };
     try {
@@ -66,7 +79,7 @@ export function readPerson(contextDir, slug, includeArchived = false) {
     }
 }
 export function listPeople(contextDir, includeArchived = false) {
-    const store = openPeopleStore(contextDir, { readonly: true });
+    const store = openPeople(contextDir, { readonly: true });
     if (!store)
         return [];
     try {
@@ -95,7 +108,7 @@ export async function personList(contextDir, input) {
 export async function personHistory(contextDir, input) {
     try {
         assertSlug(input.slug);
-        const store = openPeopleStore(contextDir, { readonly: true });
+        const store = openPeople(contextDir, { readonly: true });
         if (!store)
             return json([]);
         try {

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

@@ -1,4 +1,5 @@
 import type { McpServer } from '@modelcontextprotocol/server';
+import { type Household } from '../household.js';
 export interface HttpServeOptions {
     contextDir: string;
     host: string;
@@ -34,6 +35,12 @@ export interface HttpServeOptions {
     }) => {
         server: McpServer;
     };
+    /**
+     * Household mode: tokens resolve to roles from household.home/tokens.json
+     * (plus `token`, if set, as an owner token). Mutually exclusive with
+     * `tokens` and `createServer`; `contextDir` should be the default agent's.
+     */
+    household?: Household;
 }
 export interface HttpServeHandle {
     /** The actually-bound port (resolves a 0 request to the OS-assigned port). */

package/dist/transport/http-server.js

@@ -23,6 +23,13 @@
  *     bound to the session at open time (a later request on the same
  *     session presenting a DIFFERENT identity's token is refused, not
  *     silently re-attributed).
+ *   - `household` (docs/specs/household.md) — one daemon for many agents.
+ *     Each token in $LOOM_HOME/tokens.json has a role: `agent:<name>` gets a
+ *     full server over that agent's context dir; `owner` gets the default
+ *     agent's (or another's under `/agents/<name>/…`) and the page; `peer`
+ *     gets the knowledge-only server. LOOM_BEARER_TOKEN, when set, is an
+ *     owner token too. The role is resolved on every request and a session
+ *     is pinned to the role and agent it opened with.
  */
 import { randomUUID } from 'node:crypto';
 import { createServer } from 'node:http';
@@ -32,7 +39,11 @@ import { EmptyResultSchema } from '@modelcontextprotocol/core';
 import { createLoomServer } from '../server.js';
 import { createBackend } from '../backends/index.js';
 import { handleCliBody } from './cli-endpoint.js';
-import { handleUi, isUiRequest } from '../ui/handler.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 { createHash, timingSafeEqual as cryptoTimingSafeEqual } from 'node:crypto';
 import { assertSafeBind, checkBearer, checkBearerMulti, checkPayloadSize, DEFAULT_MAX_BODY_BYTES, } from './guards.js';
 /**
  * SSE keep-alive: the SDK opens the standalone GET stream but sends no
@@ -119,6 +130,67 @@ export async function startHttpServer(opts) {
     if (opts.token && opts.tokens) {
         throw new Error('startHttpServer: pass either token or tokens, not both');
     }
+    if (opts.household && (opts.tokens || opts.createServer)) {
+        throw new Error('startHttpServer: household mode resolves roles itself; pass neither tokens nor createServer');
+    }
+    const household = opts.household;
+    if (household) {
+        // Each of these points every agent at one store or one name, which would
+        // quietly merge the household. Refuse rather than serve it that way.
+        for (const v of ['LOOM_SQLITE_DB_PATH', 'LOOM_KNOWLEDGE_DB_PATH', 'LOOM_IDENTITY']) {
+            if (process.env[v])
+                throw new Error(`startHttpServer: ${v} is set; a household gives each agent its own store and name, so unset it`);
+        }
+        for (const a of household.agents)
+            assertRealAgentDir(household, a);
+        const problem = commonsProblem(household);
+        if (problem)
+            throw new Error(`startHttpServer: ${problem}`);
+        for (const a of household.agents) {
+            if (hasUnsplitPeople(agentDir(household, a))) {
+                throw new Error(`startHttpServer: agents/${a}'s person cards haven't been split into the commons; with every loom daemon stopped, run: loom household commons`);
+            }
+        }
+    }
+    const resolver = household ? new TokenResolver(household) : 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) {
+        const presented = (header ?? '').replace(/^Bearer\s+/i, '').trim();
+        if (!presented)
+            return { status: 401, error: 'unauthorized: missing bearer token' };
+        // The env owner token first: a broken tokens.json must not lock it out.
+        let role = null;
+        if (ownerDigest && cryptoTimingSafeEqual(createHash('sha256').update(presented).digest(), ownerDigest))
+            role = { kind: 'owner' };
+        if (!role) {
+            try {
+                role = resolver.resolve(presented);
+            }
+            catch (err) {
+                // Fail closed, and keep the details (paths) out of the response.
+                process.stderr.write(`loom: household tokens unreadable: ${err.message}\n`);
+                return { status: 503, error: 'unavailable: the household token file is unreadable; see the daemon log' };
+            }
+        }
+        if (!role)
+            return { status: 401, error: 'unauthorized: bearer token not recognized' };
+        const h = household;
+        if (role.kind === 'peer') {
+            if (target)
+                return { status: 403, error: 'forbidden: a peer token reaches the commons only' };
+            return { role, agent: h.default, contextDir: agentDir(h, h.default), key: `${roleString(role)}>${h.default}` };
+        }
+        if (role.kind === 'agent') {
+            if (target && target !== role.agent)
+                return { status: 403, error: `forbidden: this token is ${role.agent}'s` };
+            return { role, agent: role.agent, contextDir: agentDir(h, role.agent), key: `${roleString(role)}>${role.agent}` };
+        }
+        const agent = target ?? h.default;
+        if (!h.agents.includes(agent))
+            return { status: 404, error: `not-found: no agent named ${agent}` };
+        return { role, agent, contextDir: agentDir(h, agent), key: `owner>${agent}` };
+    }
     // A scoped server factory (e.g. the knowledge-only service) always needs
     // to know WHO is calling for attribution — refuse to boot it open or on a
     // single shared secret with no identity behind it.
@@ -140,15 +212,52 @@ export async function startHttpServer(opts) {
     // a session three hops later. Scoped to the default server only — a scoped
     // createServer (e.g. the knowledge-only service) never touches this
     // backend, so forcing it there would just pay for an unused embedder load.
-    if (!opts.createServer)
+    if (household)
+        for (const a of household.agents)
+            createBackend(agentDir(household, a));
+    else if (!opts.createServer)
         createBackend(opts.contextDir);
-    const makeServer = opts.createServer ?? ((ctx) => createLoomServer(ctx));
+    // The page is the owner's: in a household, only owner tokens log in to it.
+    const uiAuth = household
+        ? {
+            enabled: true,
+            check: (t) => {
+                const d = createHash('sha256').update(t).digest();
+                if (ownerDigest && cryptoTimingSafeEqual(d, ownerDigest))
+                    return d;
+                try {
+                    return resolver.resolve(t)?.kind === 'owner' ? d : null;
+                }
+                catch {
+                    return null;
+                }
+            },
+            live: (d) => {
+                if (ownerDigest !== undefined && cryptoTimingSafeEqual(d, ownerDigest))
+                    return true;
+                try {
+                    return resolver.ownerDigestLive(d.toString('hex'));
+                }
+                catch {
+                    return false;
+                }
+            },
+        }
+        : legacyUiAuth(opts.token ? [opts.token] : Object.values(opts.tokens ?? {}));
+    const makeServer = opts.createServer ?? ((ctx) => createLoomServer({ ...ctx, remote: true }));
+    const serverFor = (c, identity) => {
+        if (!c)
+            return makeServer({ contextDir: opts.contextDir, gapsDir: opts.gapsDir, identity });
+        if (c.role.kind === 'peer')
+            return createKnowledgeOnlyServer({ contextDir: c.contextDir, gapsDir: opts.gapsDir, identity: c.role.name });
+        return createLoomServer({ contextDir: c.contextDir, gapsDir: opts.gapsDir, remote: true });
+    };
     // One transport (+ its connected server) per live MCP session, plus the
     // identity it was opened for — a multi-token session is pinned to that
     // identity for its lifetime (see the mismatch check in the request handler).
     const sessions = new Map();
-    async function openSession(identity) {
-        const { server } = makeServer({ contextDir: opts.contextDir, gapsDir: opts.gapsDir, identity });
+    async function openSession(identity, caller) {
+        const { server } = serverFor(caller, identity);
         // 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
@@ -200,26 +309,53 @@ export async function startHttpServer(opts) {
             // loom's web page (src/ui), at the root. Its own auth (a session from
             // the bearer, or the bearer header), so it comes before the bearer gate.
             // Full scope only: a scoped server has no memory to show.
-            const uiPath = new URL(req.url ?? '/', 'http://localhost').pathname;
-            if (isUiRequest(req, uiPath)) {
+            const fullPath = new URL(req.url ?? '/', 'http://localhost').pathname;
+            if (isUiRequest(req, fullPath)) {
                 if (opts.createServer)
                     return sendError(res, 404, 'not-found: this server has no UI');
-                return handleUi(req, res, uiPath, {
+                return handleUi(req, res, fullPath, {
                     contextDir: opts.contextDir,
-                    secrets: opts.token ? [opts.token] : Object.values(opts.tokens ?? {}),
+                    auth: uiAuth,
                     env: process.env,
                 });
             }
+            // Household: `/agents/<name>/…` names the agent (the owner's way to
+            // reach a non-default one; an agent's own token may use its own name).
+            const scoped = household ? /^\/agents\/([a-z][a-z0-9-]{0,39})(\/.*)?$/.exec(fullPath) : null;
+            // A path under /agents/ that doesn't name an agent cleanly is a mistake,
+            // not a request for the default agent.
+            if (household && !scoped && (fullPath === '/agents' || fullPath.startsWith('/agents/'))) {
+                return sendError(res, 404, 'not-found: /agents/<name>/ takes a lowercase agent name');
+            }
+            const target = scoped?.[1];
+            const path = scoped ? (scoped[2] ?? '/') : fullPath;
+            // In a household the only routes past the page are MCP and /cli: any
+            // other path (/AGENTS/mark/mcp, /x/agents/mark/mcp) is a 404, not the
+            // default agent.
+            if (household && path !== '/' && path !== '/mcp' && path !== '/cli') {
+                return sendError(res, 404, 'not-found: in a household, use /, /mcp or /cli, optionally under /agents/<name>/');
+            }
             // Auth gate (ac-lt-auth-gate): reject unauthenticated when a token (or
             // token map) is configured. Multi-token mode additionally resolves
             // WHICH identity made this call — the bearer itself is the identity
             // claim (t-677); there is no separate login step.
-            const auth = opts.tokens
-                ? checkBearerMulti(opts.tokens, req.headers['authorization'])
-                : checkBearer(opts.token, req.headers['authorization']);
-            if (!auth.ok)
-                return sendError(res, 401, auth.error);
-            const identity = auth.identity ?? 'art';
+            let caller;
+            let identity;
+            if (household) {
+                const c = callerFor(req.headers['authorization'], target);
+                if ('status' in c)
+                    return sendError(res, c.status, c.error);
+                caller = c;
+                identity = c.key;
+            }
+            else {
+                const auth = opts.tokens
+                    ? checkBearerMulti(opts.tokens, req.headers['authorization'])
+                    : checkBearer(opts.token, req.headers['authorization']);
+                if (!auth.ok)
+                    return sendError(res, 401, auth.error);
+                identity = auth.identity ?? 'art';
+            }
             // 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) {
@@ -228,15 +364,15 @@ export async function startHttpServer(opts) {
             // POST /cli: the CLI's remote mode (cli-endpoint.ts). Same gate and cap
             // as /mcp above. Full server only: a scoped server (knowledge-only)
             // can't offer the memory verbs, so it has no /cli at all.
-            if (new URL(req.url ?? '/', 'http://localhost').pathname === '/cli') {
-                if (opts.createServer)
+            if (path === '/cli') {
+                if (opts.createServer || caller?.role.kind === 'peer')
                     return sendError(res, 404, 'not-found: this server has no CLI endpoint');
                 // Unlike /mcp (initialize handshake + mcp-session-id header), a bare
                 // POST could be a browser's "simple" cross-site request. So /cli needs
                 // a configured token, a JSON content type (forces a CORS preflight,
                 // which this server never grants), and no Origin header at all: the
                 // CLI never sends one, and a browser always does.
-                if (!opts.token && !opts.tokens)
+                if (!opts.token && !opts.tokens && !household)
                     return sendError(res, 403, 'forbidden: /cli requires LOOM_BEARER_TOKEN');
                 if (req.headers['origin'] !== undefined)
                     return sendError(res, 403, 'forbidden: /cli refuses browser requests');
@@ -255,7 +391,7 @@ export async function startHttpServer(opts) {
                 catch (e) {
                     return sendError(res, 400, `bad-input: malformed JSON (${e.message})`);
                 }
-                const outcome = await handleCliBody(opts.contextDir, parsed);
+                const outcome = await handleCliBody(caller?.contextDir ?? opts.contextDir, parsed);
                 if (!outcome.ok)
                     return sendError(res, 400, outcome.error);
                 res.writeHead(200, { 'content-type': 'application/json' });
@@ -319,7 +455,7 @@ export async function startHttpServer(opts) {
                 if (!isInitializeRequest(parsed)) {
                     return sendError(res, 400, 'bad-input: no valid session; expected an initialize request');
                 }
-                transport = await openSession(identity);
+                transport = await openSession(identity, caller);
             }
             // Dispatch totality + typed envelopes (unknown tool / bad args -> JSON-RPC
             // error) are the SDK server's job from here — never a raw throw out.

package/dist/ui/handler.d.ts

@@ -1,12 +1,25 @@
 import type { IncomingMessage, ServerResponse } from 'node:http';
 export interface UiOptions {
     contextDir: string;
-    /** Configured bearer secrets (the single token, or the token map's values). Empty = open. */
-    secrets: string[];
+    /** Who may log in to the page. */
+    auth: UiAuth;
     /** Env for piece discovery and piece processes (PATH decides which pieces exist). */
     env: NodeJS.ProcessEnv;
 }
 /** 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;
+/**
+ * Who may log in. `check` answers a presented token with its digest when the
+ * token may use the page, `live` says whether a digest still may (so revoking
+ * or rotating the token ends its sessions). `enabled` false means no token is
+ * configured, and the page refuses to serve.
+ */
+export interface UiAuth {
+    enabled: boolean;
+    check(token: string): Buffer | null;
+    live(digest: Buffer): boolean;
+}
+/** A fixed list of tokens (a single bearer, or a token map's values). */
+export declare function legacyUiAuth(secrets: string[]): UiAuth;
 /** Handle a request for the page. The caller has already matched isUiRequest. */
 export declare function handleUi(req: IncomingMessage, res: ServerResponse, pathname: string, opts: UiOptions): Promise<void>;

package/dist/ui/handler.js

@@ -33,7 +33,6 @@
  * message is kept in memory under a random id for a minute.
  */
 import { createHash, createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
-import { checkBearer } from '../transport/guards.js';
 import { agentName, coreAct, corePage, homePage, uiTimeZone } from './core.js';
 import { pieceAct, pieceManifests, piecePage } from './pieces.js';
 import { CORE, pieceSource, renderHome, renderLogin, renderPage } from './render.js';
@@ -72,9 +71,21 @@ export function isUiRequest(req, pathname) {
 const digest = (s) => createHash('sha256').update(s).digest();
 const sessions = new Map();
 const MAX_SESSIONS = 50;
-function newSession(secret) {
+/** A fixed list of tokens (a single bearer, or a token map's values). */
+export function legacyUiAuth(secrets) {
+    const digests = secrets.map((t) => digest(t));
+    return {
+        enabled: secrets.length > 0,
+        check: (t) => {
+            const d = digest(t);
+            return digests.some((x) => timingSafeEqual(x, d)) ? d : null;
+        },
+        live: (d) => digests.some((x) => timingSafeEqual(x, d)),
+    };
+}
+function newSession(tokenDigest) {
     const id = randomBytes(32).toString('hex');
-    sessions.set(id, { issuedAt: Math.floor(Date.now() / 1000), secret: digest(secret) });
+    sessions.set(id, { issuedAt: Math.floor(Date.now() / 1000), secret: tokenDigest });
     // Oldest first in a Map: drop the oldest past the cap.
     while (sessions.size > MAX_SESSIONS)
         sessions.delete(sessions.keys().next().value);
@@ -88,7 +99,7 @@ function csrfFor(id) {
 function safeEq(a, b) {
     return timingSafeEqual(digest(a), digest(b));
 }
-function validSession(id, secrets, nowS = Math.floor(Date.now() / 1000)) {
+function validSession(id, auth, nowS = Math.floor(Date.now() / 1000)) {
     if (!/^[0-9a-f]{64}$/.test(id))
         return false;
     const s = sessions.get(id);
@@ -99,7 +110,7 @@ function validSession(id, secrets, nowS = Math.floor(Date.now() / 1000)) {
         return false;
     }
     // A session dies with its token: rotate the token and old sessions stop.
-    return secrets.some((t) => timingSafeEqual(digest(t), s.secret));
+    return auth.live(s.secret);
 }
 function readCookie(req, name) {
     for (const part of (req.headers.cookie ?? '').split(';')) {
@@ -110,13 +121,14 @@ function readCookie(req, name) {
     return undefined;
 }
 function whoIs(req, opts) {
-    if (opts.secrets.length === 0)
+    if (!opts.auth.enabled)
         return null;
     const c = readCookie(req, COOKIE);
-    if (c && validSession(c, opts.secrets))
+    if (c && validSession(c, opts.auth))
         return { kind: 'session', cookie: c };
     const header = req.headers['authorization'];
-    if (header !== undefined && opts.secrets.some((s) => checkBearer(s, header).ok))
+    const presented = header?.replace(/^Bearer\s+/i, '').trim();
+    if (presented && opts.auth.check(presented))
         return { kind: 'bearer' };
     return null;
 }
@@ -269,7 +281,7 @@ function decode(s) {
 export async function handleUi(req, res, pathname, opts) {
     // No token, no page: an open /ui would be readable by any site that
     // DNS-rebinds a name to the loopback address (the same rule as /cli).
-    if (opts.secrets.length === 0) {
+    if (!opts.auth.enabled) {
         return send(res, 403, 'text/plain', 'forbidden: loom\'s page requires LOOM_BEARER_TOKEN');
     }
     // The page used to live under /ui. Old links and bookmarks land on the same page.
@@ -294,7 +306,7 @@ export async function handleUi(req, res, pathname, opts) {
         if (!form)
             return send(res, 413, 'text/plain', 'too large');
         const token = form.get('token')?.trim() ?? '';
-        const match = opts.secrets.find((s) => safeEq(token, s));
+        const match = token ? opts.auth.check(token) : null;
         if (!match)
             return send(res, 401, 'text/html; charset=utf-8', renderLogin('That token didn’t match.'));
         return redirect(res, '/', {

package/package.json

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