@verax-ai/body 0.1.0 → 0.1.2

package/dist/server.d.ts

@@ -1,5 +1,188 @@
 import { type Server } from "node:http";
 import type { BodyConfig } from "./config.ts";
 import { TOOL_NAMES } from "./wiring.ts";
+export declare const TOOL_META: ({
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        additionalProperties: boolean;
+        properties: {
+            id: {
+                type: string;
+                description: string;
+            };
+            body?: undefined;
+            source?: undefined;
+            validFromMs?: undefined;
+            validUntilMs?: undefined;
+            ref?: undefined;
+            to?: undefined;
+            text?: undefined;
+            _ref?: undefined;
+            amountMinor?: undefined;
+            currency?: undefined;
+            payee?: undefined;
+            reference?: undefined;
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        additionalProperties: boolean;
+        properties: {
+            id: {
+                type: string;
+                description: string;
+            };
+            body: {
+                description: string;
+            };
+            source: {
+                type: string;
+                description: string;
+            };
+            validFromMs: {
+                type: string;
+                description: string;
+            };
+            validUntilMs: {
+                type: string;
+                description: string;
+            };
+            ref?: undefined;
+            to?: undefined;
+            text?: undefined;
+            _ref?: undefined;
+            amountMinor?: undefined;
+            currency?: undefined;
+            payee?: undefined;
+            reference?: undefined;
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        additionalProperties: boolean;
+        properties: {
+            ref: {
+                type: string;
+                description: string;
+            };
+            id?: undefined;
+            body?: undefined;
+            source?: undefined;
+            validFromMs?: undefined;
+            validUntilMs?: undefined;
+            to?: undefined;
+            text?: undefined;
+            _ref?: undefined;
+            amountMinor?: undefined;
+            currency?: undefined;
+            payee?: undefined;
+            reference?: undefined;
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        additionalProperties: boolean;
+        properties: {
+            id?: undefined;
+            body?: undefined;
+            source?: undefined;
+            validFromMs?: undefined;
+            validUntilMs?: undefined;
+            ref?: undefined;
+            to?: undefined;
+            text?: undefined;
+            _ref?: undefined;
+            amountMinor?: undefined;
+            currency?: undefined;
+            payee?: undefined;
+            reference?: undefined;
+        };
+        required?: undefined;
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        additionalProperties: boolean;
+        properties: {
+            to: {
+                type: string;
+                description: string;
+            };
+            text: {
+                type: string;
+                description: string;
+            };
+            _ref: {
+                type: string;
+                description: string;
+            };
+            id?: undefined;
+            body?: undefined;
+            source?: undefined;
+            validFromMs?: undefined;
+            validUntilMs?: undefined;
+            ref?: undefined;
+            amountMinor?: undefined;
+            currency?: undefined;
+            payee?: undefined;
+            reference?: undefined;
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        additionalProperties: boolean;
+        properties: {
+            amountMinor: {
+                type: string;
+                description: string;
+            };
+            currency: {
+                type: string;
+                description: string;
+            };
+            payee: {
+                type: string;
+                description: string;
+            };
+            reference: {
+                type: string;
+                description: string;
+            };
+            _ref: {
+                type: string;
+                description: string;
+            };
+            id?: undefined;
+            body?: undefined;
+            source?: undefined;
+            validFromMs?: undefined;
+            validUntilMs?: undefined;
+            ref?: undefined;
+            to?: undefined;
+            text?: undefined;
+        };
+        required: string[];
+    };
+})[];
 export declare function listen(config: BodyConfig): Promise<Server>;
 export { TOOL_NAMES };

package/dist/server.js

@@ -3,7 +3,7 @@ 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 +11,101 @@ 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 = [
+// 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 +114,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"];
@@ -209,14 +291,26 @@ 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),
@@ -244,7 +338,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 +398,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 +407,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 +416,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 +452,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 +501,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;
                     }

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;