@jbarket/loomai 0.13.1 → 0.14.0

package/CHANGELOG.md

@@ -12,6 +12,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.14.0] - 2026-10-25
+
+### Added
+
+- **The piece API** (docs/extensions.md, "The API"). In a household,
+  `POST /api/<piece>/<path>` runs `loom-<piece> api --json` with
+  `{caller, path, body}` and passes the piece's `{status, body}` back. It's for
+  callers that aren't a browser: a box calling home to the runtime piece, a
+  body asking for a house. POST, JSON and no Origin, like `/cli`. It has its
+  own pool (four running, eight waiting, then 503), so a flood can't starve
+  the page.
+- **Piece credentials:** a token role `piece:<piece>/<subject>`
+  (`loom token create --piece box/thor`). It reaches only its own piece's
+  API, as its subject: no MCP, no `/cli`, no page, no other piece.
+
+### Security
+
+- The household daemon's caller resolution now handles every role kind by
+  name, and refuses anything that isn't one of them. Before this, a role
+  kind it didn't know would have been served as the owner.
+
 ## [0.13.1] - 2026-10-24
 
 ### Changed
@@ -779,7 +800,8 @@ Initial public release.
   stack and all added external-service dependencies or operational
   overhead.
 
-[Unreleased]: https://github.com/sleepunit-agents/loom/compare/v0.13.1...HEAD
+[Unreleased]: https://github.com/sleepunit-agents/loom/compare/v0.14.0...HEAD
+[0.14.0]: https://github.com/sleepunit-agents/loom/compare/v0.13.1...v0.14.0
 [0.13.1]: https://github.com/sleepunit-agents/loom/compare/v0.13.0...v0.13.1
 [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

package/dist/cli/household.js

@@ -21,13 +21,14 @@ $LOOM_HOME defaults to ~/.config/loom.
 `;
 const TOKEN_USAGE = `Usage: loom token <command>
 
-  create (--agent <name> | --owner | --peer <name>) --label <text>
+  create (--agent <name> | --owner | --peer <name> | --piece <piece>/<subject>) --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.
+the page; peer:<name> reaches commons knowledge only; piece:<piece>/<subject> is
+a piece's own credential (e.g. a box's), reaching only POST /api/<piece>/.
 `;
 function flag(args, name) {
     const i = args.indexOf(name);
@@ -107,7 +108,7 @@ export async function runToken(argv, 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 picked = [flag(rest, '--agent') && `agent:${flag(rest, '--agent')}`, rest.includes('--owner') && 'owner', flag(rest, '--peer') && `peer:${flag(rest, '--peer')}`, flag(rest, '--piece') && `piece:${flag(rest, '--piece')}`].filter(Boolean);
             const role = picked.length === 1 ? parseRole(picked[0]) : null;
             if (!label || !role) {
                 io.stderr(TOKEN_USAGE);

package/dist/household.d.ts

@@ -15,10 +15,19 @@ export type Role = {
 } | {
     kind: 'peer';
     name: string;
+}
+/**
+ * A piece's credential (docs/extensions.md, "The API"): reaches only
+ * POST /api/<piece>/…, as `subject`. No MCP, no /cli, no page, no store.
+ */
+ | {
+    kind: 'piece';
+    piece: string;
+    subject: string;
 };
 export interface TokenRecord {
     label: string;
-    /** `agent:<name>`, `owner` or `peer:<name>`. */
+    /** `agent:<name>`, `owner`, `peer:<name>` or `piece:<piece>/<subject>`. */
     role: string;
     /** sha256 of the token, hex. The token itself is never stored. */
     sha256: string;

package/dist/household.js

@@ -86,13 +86,21 @@ export function householdOf(contextDir) {
 export function parseRole(s) {
     if (s === 'owner')
         return { kind: 'owner' };
+    const p = /^piece:([a-z][a-z0-9-]{0,39})\/([a-z0-9][a-z0-9._-]{0,63})$/.exec(s);
+    if (p)
+        return p[1] === 'loom' ? null : { kind: 'piece', piece: p[1], subject: p[2] };
     const m = /^(agent|peer):([a-z][a-z0-9-]{0,39})$/.exec(s);
     if (!m)
         return null;
     return m[1] === 'agent' ? { kind: 'agent', agent: m[2] } : { kind: 'peer', name: m[2] };
 }
 export function roleString(r) {
-    return r.kind === 'owner' ? 'owner' : r.kind === 'agent' ? `agent:${r.agent}` : `peer:${r.name}`;
+    switch (r.kind) {
+        case 'owner': return 'owner';
+        case 'agent': return `agent:${r.agent}`;
+        case 'peer': return `peer:${r.name}`;
+        case 'piece': return `piece:${r.piece}/${r.subject}`;
+    }
 }
 const sha = (s) => createHash('sha256').update(s).digest('hex');
 function writePrivate(path, body) {

package/dist/transport/http-server.js

@@ -40,6 +40,8 @@ import { createLoomServer } from '../server.js';
 import { createBackend } from '../backends/index.js';
 import { handleCliBody } from './cli-endpoint.js';
 import { handleUi, isUiRequest, legacyUiAuth } from '../ui/handler.js';
+import { pieceApi } from '../ui/pieces.js';
+import { findPiece } from '../cli/pieces.js';
 import { createKnowledgeOnlyServer } from './knowledge-server.js';
 import { hasUnsplitPeople } from '../backends/people-household.js';
 import { agentDir, assertRealAgentDir, commonsProblem, liveHousehold, roleString, TokenResolver } from '../household.js';
@@ -156,8 +158,8 @@ export async function startHttpServer(opts) {
     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) {
+    /** The role a presented bearer has: 401 (none/unknown) or 503 (tokens.json unreadable). */
+    function roleFor(header) {
         const presented = (header ?? '').replace(/^Bearer\s+/i, '').trim();
         if (!presented)
             return { status: 401, error: 'unauthorized: missing bearer token' };
@@ -177,6 +179,16 @@ export async function startHttpServer(opts) {
         }
         if (!role)
             return { status: 401, error: 'unauthorized: bearer token not recognized' };
+        return role;
+    }
+    /** Resolve a household caller: 401 (no/unknown token), 403 (not allowed there) or 404 (no such agent). */
+    function callerFor(header, target) {
+        const role = roleFor(header);
+        if ('status' in role)
+            return role;
+        // Every kind is handled by name: an unlisted one must never fall through to the owner's branch.
+        if (role.kind === 'piece')
+            return { status: 403, error: `forbidden: a piece credential reaches only /api/${role.piece}/` };
         const h = live();
         if (role.kind === 'peer') {
             if (target)
@@ -188,6 +200,8 @@ export async function startHttpServer(opts) {
                 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}` };
         }
+        if (role.kind !== 'owner')
+            return { status: 403, error: 'forbidden' };
         const agent = target ?? h.default;
         if (!h.agents.includes(agent))
             return { status: 404, error: `not-found: no agent named ${agent}` };
@@ -306,6 +320,66 @@ export async function startHttpServer(opts) {
         await server.connect(transport);
         return transport;
     }
+    /**
+     * POST /api/<piece>/<path>. Like /cli: JSON only, no Origin (a browser
+     * always sends one, and this route grants no CORS), within the body cap.
+     * An owner or agent token calls as itself; a piece credential only its own
+     * piece, as its subject; a peer never.
+     */
+    async function handlePieceApi(req, res, piece, subpath) {
+        if (req.method !== 'POST')
+            return sendError(res, 405, `method-not-allowed: POST /api/${piece}/`);
+        const role = roleFor(req.headers['authorization']);
+        if ('status' in role)
+            return sendError(res, role.status, role.error);
+        let caller;
+        switch (role.kind) {
+            case 'owner':
+                caller = { kind: 'owner' };
+                break;
+            case 'agent':
+                caller = { kind: 'agent', agent: role.agent };
+                break;
+            case 'piece':
+                if (role.piece !== piece)
+                    return sendError(res, 403, `forbidden: this credential is ${role.piece}'s`);
+                caller = { kind: 'piece', subject: role.subject };
+                break;
+            case 'peer': return sendError(res, 403, 'forbidden: a peer token reaches the commons only');
+        }
+        if (req.headers['origin'] !== undefined)
+            return sendError(res, 403, 'forbidden: /api refuses browser requests');
+        if (!/^application\/json\b/i.test(req.headers['content-type'] ?? '')) {
+            return sendError(res, 415, 'unsupported-media-type: POST /api takes application/json');
+        }
+        const declared = Number(req.headers['content-length'] ?? 0);
+        if (Number.isFinite(declared) && declared > 0 && !checkPayloadSize(declared, maxBytes).ok) {
+            return sendError(res, 413, `oversized: declared ${declared} bytes exceeds cap ${maxBytes}`);
+        }
+        const raw = await collectBody(req, maxBytes);
+        if (raw === OVERSIZED)
+            return sendError(res, 413, `oversized: body exceeds cap ${maxBytes}`);
+        let body;
+        try {
+            body = raw === '' ? {} : JSON.parse(raw);
+        }
+        catch (e) {
+            return sendError(res, 400, `bad-input: malformed JSON (${e.message})`);
+        }
+        // "loom" is core's own name; a piece can't take it.
+        const path = piece === 'loom' ? null : findPiece(piece, process.env);
+        if (!path)
+            return sendError(res, 404, `not-found: no piece named ${piece}`);
+        // A caller that hangs up while queued gives its place back.
+        const gone = new AbortController();
+        res.on('close', () => { if (!res.writableEnded)
+            gone.abort(); });
+        const out = await pieceApi(path, { caller, path: subpath, body }, process.env, gone.signal);
+        if (gone.signal.aborted)
+            return;
+        res.writeHead(out.status, { 'content-type': 'application/json', 'cache-control': 'no-store' });
+        res.end(JSON.stringify(out.body));
+    }
     const http = createServer((req, res) => {
         void (async () => {
             // loom's web page (src/ui), at the root. Its own auth (a session from
@@ -322,6 +396,15 @@ export async function startHttpServer(opts) {
                     household: live,
                 });
             }
+            // POST /api/<piece>/…: a piece's API (docs/extensions.md, "The API"),
+            // for callers that aren't a browser: a box calling home, a body asking
+            // for a house. Household only, bearer only, JSON only.
+            if (household && (fullPath === '/api' || fullPath.startsWith('/api/'))) {
+                const api = /^\/api\/([a-z][a-z0-9-]{0,39})((?:\/[A-Za-z0-9._~-]+)*)\/?$/.exec(fullPath);
+                if (!api || api[2].split('/').some((s) => s === '.' || s === '..'))
+                    return sendError(res, 404, 'not-found: /api/<piece>/<path>');
+                return handlePieceApi(req, res, api[1], api[2].replace(/^\//, ''));
+            }
             // 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;

package/dist/ui/pieces.d.ts

@@ -22,6 +22,9 @@ export declare function pieceEnv(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
  * when a piece actually runs.
  */
 export declare const MAX_RUNNING = 6;
+/** /api: at most four at once, eight more waiting. */
+export declare const MAX_API_RUNNING = 4;
+export declare const MAX_API_WAITING = 8;
 /** Every installed piece's manifest, plus the ones that had nothing to show and why. */
 export declare function pieceManifests(env: NodeJS.ProcessEnv, nowMs?: number): Promise<{
     pieces: PieceInfo[];
@@ -35,3 +38,29 @@ export declare function pieceAct(info: PieceInfo, request: {
     path: string;
     fields: Record<string, string>;
 }, env: NodeJS.ProcessEnv): Promise<ActResult>;
+/** A piece's API answer is its own JSON; these bound how long one call may take. */
+export declare const API_TIMEOUT_MS = 15000;
+/** Who is calling a piece's API, as core resolved the bearer. */
+export type ApiCaller = {
+    kind: 'owner';
+} | {
+    kind: 'agent';
+    agent: string;
+} | {
+    kind: 'piece';
+    subject: string;
+};
+/**
+ * Call a piece's API (docs/extensions.md, "The API"): `loom-<piece> api --json`
+ * with {caller, path, body} on stdin. The piece answers {status?, body}; a
+ * status outside 200-499, or anything that isn't that shape, is the piece's
+ * failure, which the caller sees as a 502.
+ */
+export declare function pieceApi(path: string, request: {
+    caller: ApiCaller;
+    path: string;
+    body: unknown;
+}, env: NodeJS.ProcessEnv, gone?: AbortSignal): Promise<{
+    status: number;
+    body: unknown;
+}>;

package/dist/ui/pieces.js

@@ -56,22 +56,56 @@ function killGroup(pid) {
  * when a piece actually runs.
  */
 export const MAX_RUNNING = 6;
-let running = 0;
-const waiting = [];
-async function slot(f) {
-    if (running >= MAX_RUNNING)
-        await new Promise((r) => waiting.push(r));
-    running++;
-    try {
-        return await f();
+/**
+ * A pool of piece processes. The page's and the API's are separate, so callers
+ * of /api (a box, which may be compromised) can never starve the owner's page.
+ * The API's queue is bounded too: past it, a call is refused, not parked.
+ */
+class Pool {
+    max;
+    maxWaiting;
+    running = 0;
+    waiting = [];
+    constructor(max, maxWaiting = Infinity) {
+        this.max = max;
+        this.maxWaiting = maxWaiting;
     }
-    finally {
-        running--;
-        waiting.shift()?.();
+    /** null when the queue is full, or when `gone` fired before a slot came up. */
+    async run(f, gone) {
+        if (this.running >= this.max) {
+            if (this.waiting.length >= this.maxWaiting)
+                return null;
+            const got = await new Promise((resolve) => {
+                const go = () => { gone?.removeEventListener('abort', drop); resolve(true); };
+                const drop = () => { const i = this.waiting.indexOf(go); if (i >= 0)
+                    this.waiting.splice(i, 1); resolve(false); };
+                this.waiting.push(go);
+                gone?.addEventListener('abort', drop, { once: true });
+            });
+            if (!got)
+                return null;
+        }
+        if (gone?.aborted) {
+            this.waiting.shift()?.();
+            return null;
+        }
+        this.running++;
+        try {
+            return await f();
+        }
+        finally {
+            this.running--;
+            this.waiting.shift()?.();
+        }
     }
 }
-function ask(path, args, env, opts = {}) {
-    return slot(() => run(path, args, env, opts));
+const pagePool = new Pool(MAX_RUNNING);
+/** /api: at most four at once, eight more waiting. */
+export const MAX_API_RUNNING = 4;
+export const MAX_API_WAITING = 8;
+const apiPool = new Pool(MAX_API_RUNNING, MAX_API_WAITING);
+async function ask(path, args, env, opts = {}) {
+    return (await pagePool.run(() => run(path, args, env, opts)));
 }
 function run(path, args, env, opts) {
     return new Promise((resolve) => {
@@ -189,3 +223,27 @@ export async function pieceAct(info, request, env) {
     const result = parsed === undefined ? 'not JSON' : parseActResult(parsed);
     return typeof result === 'string' ? { ok: false, message: `${info.piece} sent an answer loom couldn't read (${result}).` } : result;
 }
+/** A piece's API answer is its own JSON; these bound how long one call may take. */
+export const API_TIMEOUT_MS = 15_000;
+/**
+ * Call a piece's API (docs/extensions.md, "The API"): `loom-<piece> api --json`
+ * with {caller, path, body} on stdin. The piece answers {status?, body}; a
+ * status outside 200-499, or anything that isn't that shape, is the piece's
+ * failure, which the caller sees as a 502.
+ */
+export async function pieceApi(path, request, env, gone) {
+    const r = await apiPool.run(() => run(path, ['api', '--json'], env, { stdin: JSON.stringify(request), timeoutMs: API_TIMEOUT_MS }), gone);
+    if (r === null)
+        return { status: 503, body: { error: 'busy: too many piece API calls at once; try again shortly' } };
+    if (!r.ok)
+        return { status: 502, body: { error: `the piece didn't answer (${r.reason})` } };
+    const parsed = json(r.stdout);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed) || !('body' in parsed)) {
+        return { status: 502, body: { error: 'the piece answered with something other than {status?, body}' } };
+    }
+    const status = parsed.status === undefined ? 200 : parsed.status;
+    if (typeof status !== 'number' || !Number.isInteger(status) || status < 200 || status > 499) {
+        return { status: 502, body: { error: 'the piece answered with a status outside 200-499' } };
+    }
+    return { status, body: parsed.body };
+}

package/package.json

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