@jbarket/loomai 0.9.2 → 0.11.0

package/dist/backends/people.js

@@ -313,7 +313,7 @@ function canonical(v) {
     return JSON.stringify(v);
 }
 // ─── Store ───────────────────────────────────────────────────────────────────
-const PEOPLE_MIGRATION = 'people_cards';
+const PEOPLE_MIGRATIONS = ['people_cards', 'person_revisions_actor'];
 function hasTable(db, table) {
     return db.prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?").get(table) !== undefined;
 }
@@ -339,19 +339,23 @@ function parseRow(raw) {
 export class PeopleStore {
     db;
     now;
+    actor;
     /** False on a read-only store whose tables do not exist yet. */
     migrated;
     constructor(config) {
         this.now = config.now ?? Date.now;
+        this.actor = config.actor ?? null;
         this.db = new BetterSqlite3(config.dbPath, config.readonly ? { readonly: true } : {});
         this.db.pragma(`busy_timeout = ${config.busyTimeoutMs ?? 5000}`);
         if (!config.readonly) {
             this.db.pragma('journal_mode = WAL');
             // Only this feature's migration: the people tables do not depend on the
             // memories schema, and a raw store must not half-run the others.
-            const m = MIGRATIONS.find((x) => x.id === PEOPLE_MIGRATION);
-            if (m.pending(this.db))
-                m.run(this.db);
+            for (const id of PEOPLE_MIGRATIONS) {
+                const m = MIGRATIONS.find((x) => x.id === id);
+                if (m.pending(this.db))
+                    m.run(this.db);
+            }
         }
         this.migrated = hasTable(this.db, 'people') && hasTable(this.db, 'person_revisions');
     }
@@ -368,8 +372,8 @@ export class PeopleStore {
         const snap = { ...prev, card: JSON.parse(prev.card_json) };
         delete snap.card_json;
         const id = Number(this.db
-            .prepare('INSERT INTO person_revisions (slug, snapshot_json, op, replaced_at) VALUES (?, ?, ?, ?)')
-            .run(prev.slug, JSON.stringify(snap), op, at).lastInsertRowid);
+            .prepare('INSERT INTO person_revisions (slug, snapshot_json, op, replaced_at, actor) VALUES (?, ?, ?, ?, ?)')
+            .run(prev.slug, JSON.stringify(snap), op, at, this.actor).lastInsertRowid);
         this.db
             .prepare(`DELETE FROM person_revisions WHERE slug = ? AND id NOT IN
            (SELECT id FROM person_revisions WHERE slug = ? ORDER BY id DESC LIMIT ?)`)
@@ -681,10 +685,41 @@ export class PeopleStore {
             fail(`slug: ${slugErr}`);
         if (!this.migrated)
             return [];
+        const hasActor = this.db.pragma('table_info(person_revisions)').some((c) => c.name === 'actor');
         return this.db
-            .prepare('SELECT id, op, replaced_at FROM person_revisions WHERE slug = ? ORDER BY id DESC')
+            .prepare(`SELECT id, op, replaced_at${hasActor ? ', actor' : ''} FROM person_revisions WHERE slug = ? ORDER BY id DESC`)
             .all(slug);
     }
+    /**
+     * Put a card in place as is, keeping the row's timestamps and archive state
+     * (a migration, not an edit). Recorded as a 'split' revision when a row is
+     * replaced.
+     */
+    replaceCard(slug, card, keep) {
+        validateCard(card, null);
+        this.mutate(() => {
+            const existing = this.readRow(slug);
+            if (existing)
+                this.snapshot(existing, 'split', this.nowIso());
+            this.store({ slug, name: card.name, card_json: JSON.stringify(card), ...keep });
+        });
+    }
+    /** The raw stored rows (timestamps and archive state included), for a migration. */
+    rows() {
+        if (!this.migrated)
+            return [];
+        return this.db.prepare('SELECT slug, name, card_json, archived_at, archived_by, archive_reason, updated, synthesized_at FROM people ORDER BY slug').all()
+            .map((r) => ({ slug: r.slug, card: JSON.parse(r.card_json), updated: r.updated, synthesized_at: r.synthesized_at, archived_at: r.archived_at, archived_by: r.archived_by, archive_reason: r.archive_reason }));
+    }
+    /** This database's `user` memories about a person, newer than `since` (all of them when null). */
+    memoriesSince(slug, since) {
+        if (!hasTable(this.db, 'memories'))
+            return 0;
+        const nowIso = new Date(this.now()).toISOString();
+        return this.db.prepare(`SELECT COUNT(*) AS n FROM memories
+       WHERE category = 'user' AND archived = 0 AND json_extract(metadata, '$.person') = ?
+         AND (expires_at IS NULL OR expires_at > ?) AND (? IS NULL OR created > ?)`).get(slug, nowIso, since, since).n;
+    }
     /** A revision's snapshot (the whole previous row), for tests and inspection. */
     revisionSnapshot(id) {
         const rev = this.db.prepare('SELECT snapshot_json FROM person_revisions WHERE id = ?').get(id);

package/dist/cli/args.js

@@ -5,9 +5,11 @@
  */
 import { resolve } from 'node:path';
 import { resolveDefaultContextPath } from '../config.js';
+import { contextFromHome } from '../household.js';
 export function resolveEnv(flags, processEnv) {
     const contextDir = flags.contextDir ??
         processEnv.LOOM_CONTEXT_DIR ??
+        contextFromHome(processEnv) ??
         resolveDefaultContextPath(processEnv.HOME);
     return {
         contextDir: resolve(contextDir),

package/dist/cli/household.d.ts

@@ -0,0 +1,3 @@
+import type { IOStreams } from './io.js';
+export declare function runHousehold(argv: string[], io: IOStreams): Promise<number>;
+export declare function runToken(argv: string[], io: IOStreams): Promise<number>;

package/dist/cli/household.js

@@ -0,0 +1,159 @@
+/**
+ * `loom household` and `loom token` (docs/specs/household.md). Local only:
+ * neither is a remote verb, so they never run through /cli. They read and
+ * write $LOOM_HOME (default ~/.config/loom) directly.
+ */
+import { addAgent, agentDir, moveKnowledgeToCommons, createToken, householdHome, HouseholdError, initHousehold, loadHousehold, loadTokens, parseRole, revokeToken, } from '../household.js';
+import { splitPeopleIntoCommons } from '../backends/people-household.js';
+const HOUSEHOLD_USAGE = `Usage: loom household <command>
+
+  show                     The household at $LOOM_HOME: agents, the default, the owner
+  init <agent> [--owner <name>]
+                           Make $LOOM_HOME/<agent> (a context dir) the first agent of a new
+                           household: it moves to agents/<agent>, and a symlink stays behind
+  add <agent>              Add an agent whose directory already exists under agents/
+  commons                  Move the default agent's knowledge.db to commons/knowledge.db and
+                           split every agent's person cards (handles and facts to the commons
+                           directory, the rest stays as its relationships). Once, with
+                           every loom daemon on this household stopped
+
+$LOOM_HOME defaults to ~/.config/loom.
+`;
+const TOKEN_USAGE = `Usage: loom token <command>
+
+  create (--agent <name> | --owner | --peer <name>) --label <text>
+                           Mint a token. It's printed once; only its sha256 is kept
+  list                     Every token: label, role, created, last used, revoked
+  revoke <label>           Revoke the live token with that label (takes effect on the next request)
+
+Roles: agent:<name> is MCP and the CLI as that agent; owner sees everything and
+the page; peer:<name> reaches commons knowledge only.
+`;
+function flag(args, name) {
+    const i = args.indexOf(name);
+    return i === -1 ? undefined : args[i + 1];
+}
+function need(io) {
+    const home = householdHome(io.env);
+    const h = loadHousehold(home);
+    if (!h)
+        io.stderr(`No household at ${home} (no household.json). Make one with: loom household init <agent>\n`);
+    return h;
+}
+export async function runHousehold(argv, io) {
+    const [sub, ...rest] = argv;
+    try {
+        if (sub === 'show') {
+            const h = need(io);
+            if (!h)
+                return 1;
+            io.stdout(`home     ${h.home}\nagents   ${h.agents.join(', ')}\ndefault  ${h.default}\n${h.owner ? `owner    ${h.owner}\n` : ''}`);
+            return 0;
+        }
+        if (sub === 'init') {
+            const agent = rest[0];
+            if (!agent || agent.startsWith('-')) {
+                io.stderr(HOUSEHOLD_USAGE);
+                return 2;
+            }
+            const h = initHousehold(householdHome(io.env), agent, { owner: flag(rest, '--owner') });
+            const cards = splitPeopleIntoCommons(h, agent, agentDir(h, agent));
+            io.stdout(`Household at ${h.home}: ${agent} moved to agents/${agent}; ${h.home}/${agent} is now a symlink to it. ${cards} person card${cards === 1 ? '' : 's'} split into the commons directory.\n`);
+            return 0;
+        }
+        if (sub === 'commons') {
+            const h = need(io);
+            if (!h)
+                return 1;
+            const moved = moveKnowledgeToCommons(h, h.default);
+            io.stdout(moved ? `Knowledge moved to ${moved}; every agent shares it now.\n` : `agents/${h.default} has no knowledge.db to move.\n`);
+            // Every agent's cards, so the daemon's "haven't been split" refusal can
+            // always be cleared here.
+            for (const a of h.agents) {
+                const cards = splitPeopleIntoCommons(h, a, agentDir(h, a));
+                io.stdout(`${a}: ${cards} person card${cards === 1 ? '' : 's'} split (handles and facts in the commons directory, the rest as ${a}'s relationships).\n`);
+            }
+            return 0;
+        }
+        if (sub === 'add') {
+            const h = need(io);
+            if (!h)
+                return 1;
+            const agent = rest[0];
+            if (!agent) {
+                io.stderr(HOUSEHOLD_USAGE);
+                return 2;
+            }
+            const next = addAgent(h, agent);
+            io.stdout(`Agents: ${next.agents.join(', ')}\n`);
+            return 0;
+        }
+        io.stderr(HOUSEHOLD_USAGE);
+        return sub === undefined || sub === '--help' || sub === '-h' ? 0 : 2;
+    }
+    catch (err) {
+        if (err instanceof HouseholdError) {
+            io.stderr(`${err.message}\n`);
+            return 1;
+        }
+        throw err;
+    }
+}
+export async function runToken(argv, io) {
+    const [sub, ...rest] = argv;
+    try {
+        if (sub === 'create') {
+            const h = need(io);
+            if (!h)
+                return 1;
+            const label = flag(rest, '--label');
+            const picked = [flag(rest, '--agent') && `agent:${flag(rest, '--agent')}`, rest.includes('--owner') && 'owner', flag(rest, '--peer') && `peer:${flag(rest, '--peer')}`].filter(Boolean);
+            const role = picked.length === 1 ? parseRole(picked[0]) : null;
+            if (!label || !role) {
+                io.stderr(TOKEN_USAGE);
+                return 2;
+            }
+            const { token, record } = createToken(h, { role, label });
+            // The token goes to stdout alone, so it can be piped straight into a file.
+            io.stderr(`Created ${record.role} token "${record.label}". It won't be shown again.\n`);
+            io.stdout(`${token}\n`);
+            return 0;
+        }
+        if (sub === 'list') {
+            const h = need(io);
+            if (!h)
+                return 1;
+            const tokens = loadTokens(h.home);
+            if (!tokens.length) {
+                io.stdout('No tokens yet.\n');
+                return 0;
+            }
+            for (const t of tokens) {
+                io.stdout(`${t.revoked ? 'revoked' : 'live   '}  ${t.role.padEnd(16)}  ${t.label}  (created ${t.created.slice(0, 10)}${t.last_used ? `, last used ${t.last_used.slice(0, 16).replace('T', ' ')}` : ', never used'}${t.revoked ? `, revoked ${t.revoked.slice(0, 10)}` : ''})\n`);
+            }
+            return 0;
+        }
+        if (sub === 'revoke') {
+            const h = need(io);
+            if (!h)
+                return 1;
+            const label = rest.join(' ').trim();
+            if (!label) {
+                io.stderr(TOKEN_USAGE);
+                return 2;
+            }
+            const t = revokeToken(h, label);
+            io.stdout(`Revoked ${t.role} token "${t.label}".\n`);
+            return 0;
+        }
+        io.stderr(TOKEN_USAGE);
+        return sub === undefined || sub === '--help' || sub === '-h' ? 0 : 2;
+    }
+    catch (err) {
+        if (err instanceof HouseholdError) {
+            io.stderr(`${err.message}\n`);
+            return 1;
+        }
+        throw err;
+    }
+}

package/dist/cli/index.js

@@ -32,6 +32,8 @@ Commands:
   doctor            Probe the loom environment (read-only)
   migrate           Apply pending schema migrations to memories.db
   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
 
 Pieces: \`loom <name> ...\` runs an installed extension, loom-<name> on PATH
 (e.g. loom tasks list). Core commands always win. See docs/extensions.md.
@@ -198,6 +200,14 @@ async function dispatch(sub, rest, io) {
             const { runPiecesCommand } = await import('./pieces.js');
             return runPiecesCommand(rest, io);
         }
+        case 'household': {
+            const { runHousehold } = await import('./household.js');
+            return runHousehold(rest, io);
+        }
+        case 'token': {
+            const { runToken } = await import('./household.js');
+            return runToken(rest, io);
+        }
         default:
             io.stderr(`Subcommand not implemented yet: ${sub}\n`);
             return 2;

package/dist/cli/serve.js

@@ -17,6 +17,7 @@ import { parseArgs } from 'node:util';
 import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
 import { createLoomServer } from '../server.js';
 import { createKnowledgeOnlyServer } from '../transport/knowledge-server.js';
+import { householdOf } from '../household.js';
 import { startHttpServer } from '../transport/http-server.js';
 import { resolveContextDir } from '../config.js';
 const USAGE = `Usage: loom serve [options]
@@ -140,9 +141,15 @@ export async function run(argv, io) {
         const host = values.host ?? process.env.LOOM_HTTP_HOST ?? '127.0.0.1';
         const port = Number(values.port ?? process.env.LOOM_HTTP_PORT ?? 8787);
         const token = process.env.LOOM_BEARER_TOKEN || undefined;
-        const handle = await startHttpServer({ contextDir, host, port, token, gapsDir });
+        // A context dir at <home>/agents/<name> next to a household.json serves
+        // the whole household (docs/specs/household.md); anything else is a
+        // household of one, exactly as before.
+        const found = householdOf(contextDir);
+        const handle = await startHttpServer({ contextDir, host, port, token, gapsDir, household: found?.household });
         io.stderr(`loom: HTTP MCP daemon on http://${handle.host}:${handle.port} ` +
-            `(${token ? 'bearer-gated' : 'open — network is the boundary'})\n`);
+            (found
+                ? `(household of ${found.household.agents.join(', ')}; tokens in ${found.household.home}/tokens.json)\n`
+                : `(${token ? 'bearer-gated' : 'open — network is the boundary'})\n`));
         // Hold open until the process is signalled.
         await new Promise(() => { });
         return 0;

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'];
+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 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',
+    'install', 'doctor', 'migrate', 'pieces', 'household', 'token',
 ];

package/dist/config.d.ts

@@ -24,6 +24,11 @@ export declare function assertContextBootable(contextDir: string, defaultPath?:
  */
 export declare function resolveRepoRoot(): string;
 export declare function resolveSqliteDbPath(contextDir: string): string;
+/**
+ * Knowledge is facts about the world. In a household it's the commons, shared
+ * by every agent (docs/specs/household.md); otherwise it lives in the
+ * agent's own context dir, as it always has.
+ */
 export declare function resolveKnowledgeDbPath(contextDir: string): string;
 /**
  * Resolve the acting identity's name for actor attribution (knowledge

package/dist/config.js

@@ -18,6 +18,7 @@ import { resolve, dirname, basename } from 'node:path';
 import { homedir } from 'node:os';
 import { fileURLToPath } from 'node:url';
 import { existsSync, readFileSync, writeFileSync, statSync, realpathSync } from 'node:fs';
+import { commonsKnowledgePath, contextFromHome, householdOf } from './household.js';
 /**
  * The single canonical helper for the default context path. Every call
  * site that needs `~/.config/loom/default` must go through this —
@@ -34,6 +35,10 @@ export function resolveContextDir() {
     if (argIdx !== -1 && process.argv[argIdx + 1]) {
         return resolve(process.argv[argIdx + 1]);
     }
+    // LOOM_HOME with a household.json: the agent LOOM_AGENT names, or its default.
+    const fromHome = contextFromHome();
+    if (fromHome)
+        return fromHome;
     return resolveDefaultContextPath();
 }
 /**
@@ -67,8 +72,18 @@ export function resolveRepoRoot() {
 export function resolveSqliteDbPath(contextDir) {
     return process.env.LOOM_SQLITE_DB_PATH ?? resolve(contextDir, 'memories.db');
 }
+/**
+ * Knowledge is facts about the world. In a household it's the commons, shared
+ * by every agent (docs/specs/household.md); otherwise it lives in the
+ * agent's own context dir, as it always has.
+ */
 export function resolveKnowledgeDbPath(contextDir) {
-    return process.env.LOOM_KNOWLEDGE_DB_PATH ?? resolve(contextDir, 'knowledge.db');
+    if (process.env.LOOM_KNOWLEDGE_DB_PATH)
+        return process.env.LOOM_KNOWLEDGE_DB_PATH;
+    const hh = householdOf(contextDir);
+    if (hh)
+        return commonsKnowledgePath(hh.household);
+    return resolve(contextDir, 'knowledge.db');
 }
 /**
  * Resolve the acting identity's name for actor attribution (knowledge

package/dist/household.d.ts

@@ -0,0 +1,117 @@
+export declare const AGENT_NAME: RegExp;
+export interface Household {
+    /** $LOOM_HOME: where household.json lives. */
+    home: string;
+    agents: string[];
+    /** The agent the owner's token acts as when it names none. */
+    default: string;
+    owner?: string;
+}
+export type Role = {
+    kind: 'agent';
+    agent: string;
+} | {
+    kind: 'owner';
+} | {
+    kind: 'peer';
+    name: string;
+};
+export interface TokenRecord {
+    label: string;
+    /** `agent:<name>`, `owner` or `peer:<name>`. */
+    role: string;
+    /** sha256 of the token, hex. The token itself is never stored. */
+    sha256: string;
+    created: string;
+    last_used?: string;
+    revoked?: string;
+}
+export declare class HouseholdError extends Error {
+}
+/** $LOOM_HOME, else ~/.config/loom. */
+export declare function householdHome(env?: NodeJS.ProcessEnv): string;
+export declare function agentDir(h: Household, agent: string): string;
+/** The household at `home`, or null when there's none. Throws on a malformed file. */
+export declare function loadHousehold(home: string): Household | null;
+/**
+ * The household a context dir belongs to: one whose `agents/<name>` is this
+ * dir (after resolving symlinks, so an old `~/.config/loom/art` link still
+ * finds it). Null for a plain context dir.
+ */
+export declare function householdOf(contextDir: string): {
+    household: Household;
+    agent: string;
+} | null;
+export declare function parseRole(s: string): Role | null;
+export declare function roleString(r: Role): string;
+export declare function loadTokens(home: string): TokenRecord[];
+/** Mint a token. Returns it once; only its sha256 is kept. */
+export declare function createToken(h: Household, input: {
+    role: Role;
+    label: string;
+}, now?: Date): {
+    token: string;
+    record: TokenRecord;
+};
+export declare function revokeToken(h: Household, label: string, now?: Date): TokenRecord;
+/**
+ * Resolves presented tokens to roles. Reads tokens.json when it changes (so
+ * a revoke takes effect on the next request), compares digests in constant
+ * 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 current;
+    /**
+     * The role for a presented token, or null. Revoked tokens and roles naming a
+     * missing agent resolve to null. Throws HouseholdError when tokens.json is
+     * unreadable or untrusted: the caller fails closed.
+     */
+    resolve(presented: string): Role | null;
+    /** Whether a live owner token has this sha256 (the page's sessions check this, so revoking ends them). */
+    ownerDigestLive(digestHex: string): boolean;
+    private touch;
+}
+/**
+ * Turn a plain context dir into the first agent of a new household: move
+ * `<home>/<name>` to `<home>/agents/<name>`, leave a symlink at the old path
+ * so anything that still names it keeps working, and write household.json.
+ */
+export declare function initHousehold(home: string, agent: string, opts?: {
+    owner?: string;
+}): Household;
+/**
+ * An agent's directory must be a real directory, not a symlink: `agents/mark
+ * -> art` would make two agents share one stack.
+ */
+export declare function assertRealAgentDir(h: Household, agent: string): void;
+/** Add an agent to a household (its directory must already exist under agents/). */
+export declare function addAgent(h: Household, agent: string): Household;
+/**
+ * The context dir a household names when nothing else does: with LOOM_HOME
+ * set and a household.json there, `agents/<LOOM_AGENT or the default>`.
+ * Undefined otherwise. Only an explicit LOOM_HOME is consulted here, so a
+ * stray household.json never changes where an unconfigured process looks.
+ * (A daemon is different: one whose context dir already is
+ * `<home>/agents/<name>` serves that household; see householdOf.)
+ */
+export declare function contextFromHome(env?: NodeJS.ProcessEnv): string | undefined;
+export declare function commonsDir(h: Household): string;
+/** The household's shared knowledge store. */
+export declare function commonsKnowledgePath(h: Household): string;
+/**
+ * Why this household can't serve yet, or null. An agent's own knowledge.db
+ * beside the commons would quietly fork the knowledge base, so both "only the
+ * agent's" (not moved yet) and "both" (needs a merge) are refusals.
+ */
+export declare function commonsProblem(h: Household): string | null;
+/**
+ * Move one agent's knowledge.db to the commons: checkpoint its WAL into the
+ * main file, then rename it (and any sidecars). Refuses when the commons
+ * already has a knowledge store. Run with every daemon on this household
+ * stopped.
+ */
+export declare function moveKnowledgeToCommons(h: Household, agent: string): string | null;