@jbarket/loomai 0.9.2 → 0.10.0

package/CHANGELOG.md

@@ -12,6 +12,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.10.0] - 2026-10-24
+
+### Security
+
+- **`harness_init` could write any file the daemon's user can.** Its
+  `target` was a free path and the harness name could carry newlines, so any
+  MCP caller could append to another agent's `IDENTITY.md` or plant a command
+  in a shell rc file. Over HTTP the target is now refused: it names a file on
+  the server, never the caller's. Locally it must be a harness instruction
+  file (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, …), judged at its real path.
+  Names refuse control characters, and managed-block writes use a random,
+  exclusive temp file. Found by the security review of the household work.
+
+### Added
+
+- **The household, phase 1: one loom, several agents**
+  (docs/specs/household.md).
+  - `$LOOM_HOME/household.json` lists the agents and the default, and
+    `tokens.json` holds every token by sha256 with a label and a role.
+  - **Roles:** `agent:<name>` is MCP and `/cli` as that agent's stack only.
+    `owner` gets the default agent, another at `/agents/<name>/`, and the
+    page. `peer:<name>` gets knowledge tools only.
+  - **On every request** the daemon resolves the role and builds the
+    session's server over that agent's context dir. A session stays pinned
+    to the role and agent it opened with, and a revoke takes effect on the
+    next request.
+  - **New commands:** `loom household init|add|show` and
+    `loom token create|list|revoke`.
+  - **Nothing changes for one agent:** a plain context dir is a household of
+    one and behaves exactly as before.
+
 ## [0.9.2] - 2026-10-24
 
 ### Fixed
@@ -666,7 +697,8 @@ Initial public release.
   stack and all added external-service dependencies or operational
   overhead.
 
-[Unreleased]: https://github.com/sleepunit-agents/loom/compare/v0.9.2...HEAD
+[Unreleased]: https://github.com/sleepunit-agents/loom/compare/v0.10.0...HEAD
+[0.10.0]: https://github.com/sleepunit-agents/loom/compare/v0.9.2...v0.10.0
 [0.9.2]: https://github.com/sleepunit-agents/loom/compare/v0.9.1...v0.9.2
 [0.9.1]: https://github.com/sleepunit-agents/loom/compare/v0.9.0...v0.9.1
 [0.9.0]: https://github.com/sleepunit-agents/loom/compare/v0.8.0...v0.9.0

package/README.md

@@ -648,6 +648,34 @@ loom tasks ready       # → loom-tasks ready
 The rules, the dispatch details and how pieces compose:
 [`docs/extensions.md`](docs/extensions.md).
 
+### The household — several agents on one loom
+
+One loom can serve several agents, with a shared commons
+([`docs/specs/household.md`](docs/specs/household.md)). A household is a
+directory (`$LOOM_HOME`, default `~/.config/loom`) with a `household.json`,
+a `tokens.json`, and one context dir per agent under `agents/`. A plain
+context dir with no household around it is a household of one and works
+exactly as before.
+
+```bash
+loom household init art             # ~/.config/loom/art → agents/art (a symlink stays)
+loom household add mark             # an agent whose dir already exists under agents/
+loom token create --agent art --label "Art · house on wunder"   # printed once
+loom token create --owner --label "Jonathan · page"
+loom token list
+loom token revoke "Art · house on wunder"
+```
+
+Every token has a role. **`agent:<name>`** is MCP and `/cli` as that agent:
+its own stack only. **`owner`** gets the default agent, or another at
+`/agents/<name>/` on the daemon, and the page. **`peer:<name>`** gets
+knowledge tools only. The daemon resolves the role on every request; no tool
+takes an agent argument, so a body can only be the agent its token names.
+`LOOM_BEARER_TOKEN`, when set, is an owner token too. A daemon whose context
+dir is `<home>/agents/<name>` next to a `household.json` serves the whole
+household. A process with `LOOM_HOME` set and no context dir uses
+`LOOM_AGENT`, or the household's default.
+
 ### Harness manifests and self-describe
 
 A **harness** is the MCP-capable runtime the agent runs in (Claude Code,

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,139 @@
+/**
+ * `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, createToken, householdHome, HouseholdError, initHousehold, loadHousehold, loadTokens, parseRole, revokeToken, } from '../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/
+
+$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') });
+            io.stdout(`Household at ${h.home}: ${agent} moved to agents/${agent}; ${h.home}/${agent} is now a symlink to it.\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.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 { contextFromHome } 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();
 }
 /**

package/dist/household.d.ts

@@ -0,0 +1,101 @@
+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;