@verax-ai/body 0.1.1 → 0.1.3

package/dist/server.js

@@ -1,9 +1,10 @@
 import { AsyncLocalStorage } from "node:async_hooks";
+import { readFileSync } from "node:fs";
 import { createServer } from "node:http";
 import { Server as McpServer } from "@modelcontextprotocol/sdk/server/index.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
-import { approvalsLogFor, approvePending, explain, LedgerDenyUnrecorded, loadApprovalsFromDir, } from "@verax-ai/proxy";
+import { approvalsLogFor, approvePending, createApprovalBudgetGuard, explain, LedgerDenyUnrecorded, loadApprovalsFromDir, } from "@verax-ai/proxy";
 import { createVerifier, readBearer, resourceMetadataUrl, wwwAuthenticate } from "./auth.js";
 import { bumpMetric, bumpUnauthenticated } from "./metrics.js";
 import { isRevokedJti } from "./revoke.js";
@@ -11,48 +12,102 @@ import { loadOrCreateSigners } from "./keys.js";
 import { matchingInputs } from "./inputs-read.js";
 import { readPolicySnapshots } from "./policy-store.js";
 import { readHeartbeat, readWitnessPulse } from "./health-extras.js";
+import { agentsWindow } from "./agents.js";
 import { inventoryHealth, readInventoryFile } from "./inventory-file.js";
 import { createBodyServices, TOOL_NAMES } from "./wiring.js";
-const TOOL_META = [
+import { openDownstream, parseDownstreamDocument, } from "./downstream.js";
+// What a brain reads before it calls. Each description says what the tool is
+// for, what it does and does not do, what the gate may answer, and what comes
+// back; each parameter says its format and its bounds. The answers named here
+// are the proxy's: `denied:<reason>:<ref>`, `deferred:approval-required:<ref>`
+// and `allowed:<ref>` (packages/proxy/src/proxy.ts).
+const ID_FORMAT = "1 to 128 characters of letters, digits, '.', '_' or '-', starting with a letter or digit; case-sensitive.";
+const REF_FORMAT = "1 to 64 characters of letters, digits, '.', '_' or '-', starting with a letter or digit.";
+const REF_PARAM = {
+    type: "string",
+    description: "Optional reference you choose for this call, " +
+        REF_FORMAT +
+        " Resend the same call with the same _ref after an operator approved it to receive allowed:<ref>; " +
+        "a _ref reused for a different call is refused with denied:ref-reuse.",
+};
+export const TOOL_META = [
     {
         name: "memory.get",
-        description: "Read a memory item. Stale items return { stale: true } without the body.",
+        description: "Reads one memory item this tenant stored earlier with memory.put, by its id. " +
+            "Use it to recall a fact, a setting or a note before acting on it; nothing is written. " +
+            "Like every call it passes the policy gate and leaves a signed decision record; an id that belongs to another tenant is answered with a signed deny. " +
+            "Returns the stored item as JSON: {id, body, source, validFromMs, validUntilMs, versionHash}. " +
+            "Outside the validity window the body is withheld: {stale: true, id, validUntilMs} after it, {notYetValid: true, id, validFromMs} before it. " +
+            'An unknown id answers {error: "not-found", id}.',
         inputSchema: {
             type: "object",
             additionalProperties: false,
-            properties: { id: { type: "string" } },
+            properties: {
+                id: { type: "string", description: "The id given to memory.put: " + ID_FORMAT },
+            },
             required: ["id"],
         },
     },
     {
         name: "memory.put",
-        description: "Write a memory item. source and validUntilMs are required.",
+        description: "Writes one memory item for this tenant, or replaces the item with the same id, in the body's state directory on this machine. " +
+            "Use it to keep a fact for a later memory.get together with where it came from and how long it holds, so a stale fact is not served later. " +
+            "The call passes the policy gate and is recorded; the record carries the item's versionHash, a SHA-256 over id, body and validity window. " +
+            "Returns {ok: true, id, versionHash}. " +
+            'A missing source answers {error: "source-required"}, a missing validUntilMs {error: "validUntilMs-required"}, a malformed id {error: "id-invalid"}.',
         inputSchema: {
             type: "object",
             additionalProperties: false,
             properties: {
-                id: { type: "string" },
-                body: {},
-                source: { type: "object" },
-                validFromMs: { type: "number" },
-                validUntilMs: { type: "number" },
+                id: {
+                    type: "string",
+                    description: "Identifier to store under and read back with memory.get: " +
+                        ID_FORMAT +
+                        " An existing item with this id is replaced.",
+                },
+                body: {
+                    description: "The value to keep, as any JSON: object, array, string, number or boolean. Stored as given and returned as given by memory.get.",
+                },
+                source: {
+                    type: "object",
+                    description: 'Where the value came from, as a JSON object of your choosing, for example {"kind": "document", "ref": "invoice-2026-09.pdf"}. Required; stored with the item so a later reader can weigh it.',
+                },
+                validFromMs: {
+                    type: "number",
+                    description: "Optional. Unix time in milliseconds from which the item may be served; before it memory.get answers notYetValid. Omit to serve it at once.",
+                },
+                validUntilMs: {
+                    type: "number",
+                    description: "Required. Unix time in milliseconds after which memory.get answers stale and withholds the body. Pick the moment the fact should no longer be trusted.",
+                },
             },
             required: ["id", "body", "source", "validUntilMs"],
         },
     },
     {
         name: "audit.explain",
-        description: "Explain a decision ref against the ledger.",
+        description: "Reads one decision back from the signed ledger by its ref and explains it. " +
+            "Use it to check what the body decided about an earlier call and whether the recorded effect matched, before repeating a call or reporting on it; read-only, and the lookup itself is recorded too. " +
+            "Returns JSON with record (the signed decision's claims: tool, verdict, policy hash, timestamps), effect (the reconciled effect row), finding (match, mismatch or missing), witnessClass, guarantee, warnings, trustRoot (which key verified the signatures), and for a held call pair with its defer and resolution records. " +
+            "A ref that does not exist, or belongs to another tenant, is answered with the same signed deny, so neither case reveals the other.",
         inputSchema: {
             type: "object",
             additionalProperties: false,
-            properties: { ref: { type: "string" } },
+            properties: {
+                ref: {
+                    type: "string",
+                    description: "The decision reference: the ref returned by an earlier call, also the tail of a denied:… or deferred:… answer; " +
+                        REF_FORMAT,
+                },
+            },
             required: ["ref"],
         },
     },
     {
         name: "message.read",
-        description: "Read the local inbox fixture as JSON.",
+        description: "Reads this tenant's inbox, the messages placed for it in the body's state directory on this machine, and returns them as a JSON array in arrival order, oldest first. " +
+            "Use it to see what has arrived before deciding what to answer. " +
+            "Takes no arguments; read-only; the call is recorded like every other. An empty or absent inbox answers [].",
         inputSchema: {
             type: "object",
             additionalProperties: false,
@@ -61,34 +116,63 @@ const TOOL_META = [
     },
     {
         name: "message.send",
-        description: "Queue a message on the local outbox. Does not open a network.",
+        description: "Queues one message in this tenant's outbox on this machine for the delivery step the operator runs; this call opens no network connection and nothing leaves the body from it. " +
+            "Use it to hand off a message, not to deliver one. " +
+            "Like every call it passes the policy gate and leaves a signed decision record. " +
+            "The gate reads the host after the last '@' in to and allows it only when it is on the policy's egress allow-list; otherwise the call is refused with denied:egress-blocked, or denied:egress-host-missing when no host can be read. " +
+            "A policy rule in approve mode holds the call for an operator instead and answers deferred:approval-required:<ref>. " +
+            "Returns {queued: true, ref}, where ref is the decision reference for audit.explain.",
         inputSchema: {
             type: "object",
             additionalProperties: false,
             properties: {
-                to: { type: "string" },
-                text: { type: "string" },
+                to: {
+                    type: "string",
+                    description: "Recipient address with a host after the last '@', for example ops@example.com. The host, lower-cased, is matched against the policy's egress list.",
+                },
+                text: { type: "string", description: "The message body as plain text. Stored as given in the outbox row." },
+                _ref: REF_PARAM,
             },
             required: ["to", "text"],
         },
     },
     {
         name: "spend",
-        description: "Authorizes a payment; does not move money.",
+        description: "Asks the body to authorize a payment and records the decision; the body never moves money, so authorized: true is a signed permission for a later payment step, not a transfer. " +
+            "Use it before any payment so that amount, currency, payee and reference are checked against the policy: the one currency the policy names, a cap per call, a payee list and a daily limit. " +
+            "A call outside those bounds is refused with a signed deny naming the bound: denied:spend-cap, denied:spend-payee, denied:spend-currency or denied:spend-daily. " +
+            "A call within them is held for an operator on this machine and answers deferred:approval-required:<ref>; once that ref is approved (verax approve, or the panel), resending the same call with the same _ref answers allowed:<ref>, and the authorization is recorded as {authorized: true, ref, amountMinor, currency, payee, reference}. " +
+            "Without a spend rule in the policy every call answers denied:spend-not-wired.",
         inputSchema: {
             type: "object",
             additionalProperties: false,
             properties: {
-                amountMinor: { type: "integer" },
-                currency: { type: "string" },
-                payee: { type: "string" },
-                reference: { type: "string" },
+                amountMinor: {
+                    type: "integer",
+                    description: "Amount in the currency's minor unit as a positive integer: cents, kuruş or pence, so 1250 means 12.50. Compared against the policy's cap per call and daily limit.",
+                },
+                currency: {
+                    type: "string",
+                    description: "ISO 4217 code in upper case, for example USD, EUR or TRY. Must equal the currency the policy's spend rule names.",
+                },
+                payee: {
+                    type: "string",
+                    description: "Who is to be paid, spelled exactly as the policy's payee list spells it (a merchant or account name). A payee off the list is refused.",
+                },
+                reference: {
+                    type: "string",
+                    description: "Your own reference for this payment, such as an invoice or order id. Recorded with the authorization and used by verax reconcile to match the card statement.",
+                },
+                _ref: REF_PARAM,
             },
             required: ["amountMinor", "currency", "payee", "reference"],
         },
     },
 ];
 const MAX_BODY_BYTES = 1024 * 1024;
+// Unbounded GET /api/ledger stringified ~690 MB at 200k rows and threw Invalid string length (HTTP 500).
+const DEFAULT_LEDGER_LIMIT = 1000;
+const MAX_LEDGER_LIMIT = 5000;
 const responseSlot = new AsyncLocalStorage();
 function contentLengthOverLimit(req) {
     const raw = req.headers["content-length"];
@@ -139,17 +223,94 @@ function send(res, status, body, headers) {
     });
     res.end(text);
 }
+/**
+ * Republishes a child's own `tools/list` entry under its prefixed name. The
+ * description is the child's; the sentence added here says what changes by
+ * going through the body, because the answers a caller gets back
+ * (`denied:…`, `deferred:…`) are the gate's, not the child's.
+ */
+function downstreamMeta(tool) {
+    const own = typeof tool.description === "string" && tool.description !== "" ? `${tool.description} ` : "";
+    return {
+        name: tool.name,
+        description: own +
+            "Forwarded by this body to the downstream server that published it: the call passes the same policy gate " +
+            "and leaves the same signed decision under this name, so it may be answered with denied:<reason>:<ref> or " +
+            "deferred:approval-required:<ref> before the downstream server ever sees it.",
+        inputSchema: tool.inputSchema ?? { type: "object" },
+    };
+}
+async function closeAll(sessions) {
+    for (const session of sessions) {
+        await session.close().catch(() => undefined);
+    }
+}
+/**
+ * What an operator may see about the attached children: the prefix they call
+ * by, how the body reaches them, and the names it will accept.
+ *
+ * Deliberately not the address. A child's URL can carry its token in the path
+ * — the live Conarium's does — and a command line names a path on this host.
+ * Neither is needed to answer "what is standing behind this gate", so neither
+ * is published. The `tests/downstream-visible` guard asserts their absence.
+ */
+function downstreamPublic(sessions, specs) {
+    return sessions.map((session) => {
+        const spec = specs.find((s) => s.prefix === session.prefix);
+        return {
+            prefix: session.prefix,
+            transport: spec?.url !== undefined ? "http" : "stdio",
+            tools: session.tools.map((t) => t.name),
+        };
+    });
+}
+/**
+ * Opens every child the document names. One child that refuses to attach
+ * closes the ones already open and throws: a half-attached body would serve a
+ * tool list its operator never wrote.
+ */
+async function attachDownstream(file) {
+    if (file === null || file.trim() === "")
+        return { sessions: [], specs: [] };
+    const specs = parseDownstreamDocument(readFileSync(file, "utf8"));
+    const sessions = [];
+    for (const spec of specs) {
+        try {
+            sessions.push(await openDownstream(spec));
+        }
+        catch (err) {
+            await closeAll(sessions);
+            const detail = err instanceof Error ? err.message : "attach-failed";
+            throw new Error(`downstream-attach-failed:${spec.prefix}:${detail}`);
+        }
+    }
+    return { sessions, specs };
+}
 export async function listen(config) {
     const signers = loadOrCreateSigners(config.stateDir);
-    const services = createBodyServices({
-        stateDir: config.stateDir,
-        policyFile: config.policyFile,
-        recordSigner: signers.recordSigner,
-        effectSigner: signers.effectSigner,
-    });
+    // The children are attached before the door opens. A named document the body
+    // cannot honour stops the start: a body that serves six tools while its
+    // operator wrote seven is answering for a gate it does not have.
+    const { sessions, specs: downstreamSpecs } = await attachDownstream(config.downstreamFile ?? null);
+    const extraTools = sessions.flatMap((session) => session.tools);
+    let services;
+    try {
+        services = createBodyServices({
+            stateDir: config.stateDir,
+            policyFile: config.policyFile,
+            recordSigner: signers.recordSigner,
+            effectSigner: signers.effectSigner,
+            ...(extraTools.length > 0 ? { extraTools } : {}),
+        });
+    }
+    catch (err) {
+        await closeAll(sessions);
+        throw err;
+    }
+    const toolMeta = [...TOOL_META, ...extraTools.map(downstreamMeta)];
     const verify = createVerifier(config.jwksUrl, config.issuer, config.audience);
     const attachHandlers = (mcp) => {
-        mcp.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOL_META }));
+        mcp.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: toolMeta }));
         mcp.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
             const auth = extra?.authInfo;
             const scopes = new Set(auth?.scopes ?? []);
@@ -209,18 +370,33 @@ export async function listen(config) {
                     send(res, 200, { ok: true });
                     return;
                 }
-                const decisions = await services.ledger.decisions();
-                const effects = await services.ledger.effects();
-                const last = decisions[decisions.length - 1];
+                // The ledger counts its own lines as it writes them; asking it is free.
+                // Reading both files back to count them was one second per call on a
+                // 100k-decision ledger, five times a minute for as long as a panel was open.
+                // When the active piece cannot be read back, the fallback below counts
+                // the merged files; it cannot tell which rows sit in the active piece,
+                // so the piece fields stay out of that degraded answer.
+                let counted = services.ledger.counts();
+                if (!counted) {
+                    const decisions = await services.ledger.decisions();
+                    const effects = await services.ledger.effects();
+                    const last = decisions[decisions.length - 1];
+                    counted = {
+                        decisions: decisions.length,
+                        effects: effects.length,
+                        lastDecisionMs: last ? last.claims.timestampMs : null,
+                    };
+                }
                 send(res, 200, {
                     ok: true,
-                    decisions: decisions.length,
-                    effects: effects.length,
-                    lastDecisionMs: last ? last.claims.timestampMs : null,
+                    ...counted,
                     lock: services.ledger.lockStatus(),
                     heartbeat: readHeartbeat(config.stateDir),
                     witness: readWitnessPulse(config.stateDir),
                     inventory: inventoryHealth(readInventoryFile(config.inventoryFile)),
+                    // Always an array, empty when nothing is attached: a missing field
+                    // would read as "this body is too old to tell you".
+                    downstream: downstreamPublic(sessions, downstreamSpecs),
                 });
                 return;
             }
@@ -244,7 +420,8 @@ export async function listen(config) {
             const apiInventory = url.pathname === "/api/inventory";
             const contest = req.method === "POST" && url.pathname.startsWith("/api/contest/");
             const apiApprove = req.method === "POST" && url.pathname === "/api/approve";
-            if (url.pathname !== "/mcp" && !apiLedger && !apiInventory && !contest && !apiApprove) {
+            const apiAgents = req.method === "GET" && url.pathname === "/api/agents";
+            if (url.pathname !== "/mcp" && !apiLedger && !apiInventory && !contest && !apiApprove && !apiAgents) {
                 send(res, 404, { error: "not-found" });
                 return;
             }
@@ -303,9 +480,8 @@ export async function listen(config) {
                         send(res, 409, { error: "stale", requestHash: waiting.requestHash });
                         return;
                     }
-                    const decisions = await services.ledger.decisions();
-                    const defer = decisions.find((d) => d.claims.ref === ref && d.claims.decision === "defer");
-                    if (!defer) {
+                    const defer = services.ledger.lookupByRef(ref);
+                    if (!defer || defer.decision !== "defer") {
                         send(res, 404, { error: "unknown-ref" });
                         return;
                     }
@@ -313,6 +489,7 @@ export async function listen(config) {
                     // which says nothing about the person holding the phone; the session's
                     // own subject does.
                     const approver = verified.principal.brain;
+                    const approvals = approvalsLogFor(services.ledger);
                     const outcome = await approvePending({
                         ledger: services.ledger,
                         recordSigner: loadOrCreateSigners(config.stateDir).recordSigner,
@@ -321,18 +498,26 @@ export async function listen(config) {
                         ref,
                         approverId: approver,
                         via: "http",
-                        policyHash: defer.claims.policyHash,
-                        approvals: approvalsLogFor(services.ledger),
+                        policyHash: defer.policyHash,
+                        approvals,
+                        budgetGuard: createApprovalBudgetGuard({
+                            policy: services.policy,
+                            approvals,
+                            now: () => Date.now(),
+                        }),
                     });
                     if (!outcome.ok) {
                         const code = outcome.reason === "unknown-ref" || outcome.reason === "snapshot-missing" ? 404 : 409;
-                        send(res, code, { error: outcome.reason });
+                        send(res, code, {
+                            error: outcome.reason,
+                            ...(outcome.allowRef ? { allowRef: outcome.allowRef } : {}),
+                        });
                         return;
                     }
                     send(res, 200, { allowRef: outcome.allowRef, approver });
                     return;
                 }
-                if (apiLedger || apiInventory || contest) {
+                if (apiLedger || apiInventory || contest || apiAgents) {
                     // The audit doors hand out the whole ledger: every tenant's decisions, the
                     // inputs documents that name their principals, and the approval snapshots
                     // that carry spend arguments. `verax:read` is a brain scope, so it cannot be
@@ -349,11 +534,47 @@ export async function listen(config) {
                         send(res, 200, readInventoryFile(config.inventoryFile));
                         return;
                     }
+                    if (apiAgents) {
+                        // The last day unless the caller names a window; the roster's
+                        // agents are on the list whether or not they acted in it.
+                        const now = Date.now();
+                        const fromRaw = url.searchParams.get("from");
+                        const toRaw = url.searchParams.get("to");
+                        const from = fromRaw === null ? now - 86_400_000 : Number(fromRaw);
+                        const to = toRaw === null ? now : Number(toRaw);
+                        if (!Number.isFinite(from) || !Number.isFinite(to)) {
+                            send(res, 400, { error: "bad-window" });
+                            return;
+                        }
+                        send(res, 200, await agentsWindow({
+                            ledger: services.ledger,
+                            stateDir: config.stateDir,
+                            inventoryFile: config.inventoryFile,
+                            fromMs: from,
+                            toMs: to,
+                        }));
+                        return;
+                    }
                     if (apiLedger) {
                         const from = Number(url.searchParams.get("from") ?? "0");
                         const to = Number(url.searchParams.get("to") ?? String(Number.MAX_SAFE_INTEGER));
-                        const decisions = (await services.ledger.decisions()).filter((d) => d.claims.timestampMs >= from && d.claims.timestampMs < to);
-                        const effects = (await services.ledger.effects()).filter((e) => e.row.timestampMs >= from && e.row.timestampMs < to);
+                        const limitRaw = url.searchParams.get("limit");
+                        const parsedLimit = limitRaw === null ? undefined : Number(limitRaw);
+                        if (!Number.isFinite(from) ||
+                            !Number.isFinite(to) ||
+                            (parsedLimit !== undefined && (!Number.isFinite(parsedLimit) || parsedLimit < 0))) {
+                            send(res, 400, { error: "bad-window" });
+                            return;
+                        }
+                        const limit = parsedLimit === undefined ? DEFAULT_LEDGER_LIMIT : Math.min(MAX_LEDGER_LIMIT, Math.floor(parsedLimit));
+                        // The window is read from the end of the files, so a day costs a
+                        // day whatever the ledger's age. With a limit, the newest rows of
+                        // the window come back and `more` says the rest is there to ask for.
+                        const { rows: decisions, more, piecesTouched } = await services.ledger.decisionsWindow(from, to, limit);
+                        // Effects belong to the decisions returned. When the limit cut the
+                        // window, the oldest decision returned is where their window starts.
+                        const effectsFrom = more && decisions.length > 0 ? decisions[0].claims.timestampMs : from;
+                        const effects = await services.ledger.effectsWindow(effectsFrom, to);
                         const hashes = [...new Set(decisions.map((d) => d.claims.policyHash))];
                         send(res, 200, {
                             decisions,
@@ -362,6 +583,9 @@ export async function listen(config) {
                             policies: readPolicySnapshots(config.stateDir, hashes),
                             inputs: await matchingInputs(config.stateDir, decisions),
                             approvals: loadApprovalsFromDir(config.stateDir),
+                            more,
+                            piecesTouched,
+                            limit,
                         });
                         return;
                     }
@@ -478,6 +702,7 @@ export async function listen(config) {
     });
     server.on("close", () => {
         services.ledger.close();
+        void closeAll(sessions);
     });
     return server;
 }

package/dist/tools/memory.d.ts

@@ -1,6 +1,8 @@
 import { type Principal, type ToolCall, type ToolResult } from "@verax-ai/proxy";
 /** True when `id` exists under a different tenant. Does not read legacy `memory/`. */
 export declare function memoryBelongsToOtherTenant(stateDir: string, id: string, selfKey: string): boolean;
+/** True when this tenant already has `id` under its own memory path. */
+export declare function memoryExistsForTenant(stateDir: string, id: string, principal: Principal): boolean;
 export declare function readMemoryMeta(stateDir: string, id: string, principal?: Principal): Promise<{
     versionHash: string;
     validFromMs: number;

package/dist/tools/memory.js

@@ -51,6 +51,13 @@ export function memoryBelongsToOtherTenant(stateDir, id, selfKey) {
     }
     return false;
 }
+/** True when this tenant already has `id` under its own memory path. */
+export function memoryExistsForTenant(stateDir, id, principal) {
+    const path = resolveMemoryPath(stateDir, id, principal);
+    if (path === null)
+        return false;
+    return existsSync(path);
+}
 export async function readMemoryMeta(stateDir, id, principal) {
     if (!principal)
         return null;

package/dist/wiring.d.ts

@@ -1,9 +1,14 @@
-import { createProxy, FileLedger, type EffectSigner, type ExplainOpts, type Principal, type RecordSigner, type ToolCall, type ToolResult } from "@verax-ai/proxy";
+import { createProxy, FileLedger, type EffectSigner, type ExplainOpts, type Policy, type Principal, type RecordSigner, type ToolCall, type ToolResult } from "@verax-ai/proxy";
 export type ToolFn = (call: ToolCall, principal: Principal, ref?: string) => Promise<ToolResult>;
 export declare const TOOL_NAMES: readonly ["memory.get", "memory.put", "audit.explain", "message.read", "message.send", "spend"];
+export type ExtraTool = {
+    name: string;
+    fn: ToolFn;
+};
 export type BodyServices = {
     proxy: ReturnType<typeof createProxy>;
     ledger: FileLedger;
+    policy: Policy;
     policyHash: string;
     policyDocument: unknown;
     listTools: () => readonly string[];
@@ -11,7 +16,9 @@ export type BodyServices = {
 };
 /**
  * Tool functions live in a Map that is not exported. The only way to
- * reach them at runtime is `proxy.call` -> `inner`.
+ * reach them at runtime is `proxy.call` -> `inner`. Extra tools (a
+ * downstream prefix) enter that Map at construction; they still pass
+ * the gate.
  */
 export declare function createBodyServices(opts: {
     stateDir: string;
@@ -20,4 +27,5 @@ export declare function createBodyServices(opts: {
     effectSigner: EffectSigner;
     now?: () => number;
     nonce?: () => string;
+    extraTools?: readonly ExtraTool[];
 }): BodyServices;

package/dist/wiring.js

@@ -2,11 +2,11 @@ import { createProxy, FileLedger, loadPolicy, tenantKey, } from "@verax-ai/proxy
 import { readFileSync } from "node:fs";
 import { persistPolicySnapshot } from "./policy-store.js";
 import { inputsPrincipal } from "./inputs-read.js";
-import { memoryBelongsToOtherTenant, memoryGet, memoryPut, readMemoryMeta } from "./tools/memory.js";
+import { memoryBelongsToOtherTenant, memoryExistsForTenant, memoryGet, memoryPut, readMemoryMeta, } from "./tools/memory.js";
 import { auditExplain } from "./tools/audit.js";
 import { messageRead, messageSend } from "./tools/message.js";
 import { spendAuthorize } from "./tools/spend.js";
-import { requestWitnessSign } from "./witness.js";
+import { requestWitnessCheckpoint, requestWitnessSign } from "./witness.js";
 export const TOOL_NAMES = [
     "memory.get",
     "memory.put",
@@ -17,11 +17,32 @@ export const TOOL_NAMES = [
 ];
 /**
  * Tool functions live in a Map that is not exported. The only way to
- * reach them at runtime is `proxy.call` -> `inner`.
+ * reach them at runtime is `proxy.call` -> `inner`. Extra tools (a
+ * downstream prefix) enter that Map at construction; they still pass
+ * the gate.
  */
 export function createBodyServices(opts) {
+    const extraNames = [];
+    const reserved = new Set(TOOL_NAMES);
+    for (const tool of opts.extraTools ?? []) {
+        if (reserved.has(tool.name) || extraNames.includes(tool.name)) {
+            throw new Error(`downstream-name-collision:${tool.name}`);
+        }
+        // Same shape as extraToolNameOk in downstream.ts (prefix.childName).
+        if (!/^[A-Za-z][A-Za-z0-9_-]{0,31}\.[A-Za-z][A-Za-z0-9._-]{0,63}$/.test(tool.name)) {
+            throw new Error(`downstream-name-invalid:${tool.name}`);
+        }
+        extraNames.push(tool.name);
+    }
     const ledger = new FileLedger(opts.stateDir);
     ledger.remoteWitness = (row, resultHash) => requestWitnessSign(opts.stateDir, row, resultHash);
+    ledger.onPieceClose = async (window) => {
+        await requestWitnessCheckpoint(opts.stateDir, {
+            epoch: 0,
+            startMs: window.startMs,
+            endMs: window.endMs,
+        });
+    };
     const policyText = readFileSync(opts.policyFile, "utf8");
     const policyDocument = JSON.parse(policyText);
     const policy = loadPolicy(policyText);
@@ -49,6 +70,9 @@ export function createBodyServices(opts) {
     registry.set("message.read", (call, principal) => messageRead(call, opts.stateDir, principal));
     registry.set("message.send", (call, principal, ref) => messageSend(call, opts.stateDir, ref ?? "", principal));
     registry.set("spend", (call, _principal, ref) => spendAuthorize(call, ref ?? ""));
+    for (const tool of opts.extraTools ?? []) {
+        registry.set(tool.name, tool.fn);
+    }
     const inner = async (call, principal, ref) => {
         const fn = registry.get(call.name);
         if (!fn) {
@@ -73,6 +97,8 @@ export function createBodyServices(opts) {
                 const id = call.arguments.id;
                 if (typeof id !== "string")
                     return false;
+                if (memoryExistsForTenant(opts.stateDir, id, principal))
+                    return false;
                 return memoryBelongsToOtherTenant(opts.stateDir, id, tenantKey(principal));
             }
             if (call.name === "audit.explain") {
@@ -93,9 +119,10 @@ export function createBodyServices(opts) {
     return {
         proxy,
         ledger,
+        policy,
         policyHash: policy.hash,
         policyDocument,
-        listTools: () => TOOL_NAMES,
+        listTools: () => (extraNames.length === 0 ? TOOL_NAMES : [...TOOL_NAMES, ...extraNames]),
         explainOpts,
     };
 }

package/dist/witness.js

@@ -5,7 +5,7 @@ import { join } from "node:path";
 import { writeFileAtomic } from "./atomic-write.js";
 import { buildCheckpointClaims, checkpointHash, signCheckpoint, totalsFromDecisionRecords, } from "@cedulon/checkpoint";
 import { decisionRecordHash } from "@cedulon/core";
-import { checkpointsPath, signEffectAttestation } from "@verax-ai/proxy";
+import { checkpointsPath, listPieceFiles, signEffectAttestation } from "@verax-ai/proxy";
 import { pidAlive } from "./unlock.js";
 const WITNESS_CLASS = "same-org";
 function listenPath(stateDir) {
@@ -104,21 +104,23 @@ function send(res, status, body) {
     res.end(text);
 }
 function loadDecisions(stateDir) {
-    try {
-        const text = readFileSync(join(stateDir, "decisions.jsonl"), "utf8");
-        const out = [];
-        for (const line of text.split("\n")) {
-            if (line === "")
+    const out = [];
+    for (const piece of listPieceFiles(stateDir)) {
+        try {
+            const text = readFileSync(piece.decisions, "utf8");
+            for (const line of text.split("\n")) {
+                if (line === "")
+                    continue;
+                out.push(JSON.parse(line));
+            }
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
                 continue;
-            out.push(JSON.parse(line));
+            throw err;
         }
-        return out;
-    }
-    catch (err) {
-        if (err.code === "ENOENT")
-            return [];
-        throw err;
     }
+    return out;
 }
 function lastCheckpointHash(stateDir) {
     try {