@verax-ai/body 0.1.1 → 0.1.3

package/dist/downstream.js

@@ -0,0 +1,274 @@
+import { Readable } from "node:stream";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { getDefaultEnvironment, StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+const PREFIX_RE = /^[A-Za-z][A-Za-z0-9_-]{0,31}$/;
+const CHILD_TOOL_RE = /^[A-Za-z][A-Za-z0-9._-]{0,63}$/;
+/** Prefixed name a caller may put on extraTools: `prefix.childName`. */
+const EXTRA_NAME_RE = /^[A-Za-z][A-Za-z0-9_-]{0,31}\.[A-Za-z][A-Za-z0-9._-]{0,63}$/;
+export class DownstreamCallError extends Error {
+    prefix;
+    tool;
+    constructor(prefix, tool, cause) {
+        const detail = cause instanceof Error ? cause.message : "call-failed";
+        super(`downstream-call-failed:${prefix}.${tool}:${detail}`);
+        this.name = "DownstreamCallError";
+        this.prefix = prefix;
+        this.tool = tool;
+        if (cause !== undefined)
+            this.cause = cause;
+    }
+}
+export function prefixedName(prefix, childName) {
+    return `${prefix}.${childName}`;
+}
+export function extraToolNameOk(name) {
+    return EXTRA_NAME_RE.test(name);
+}
+export function parseDownstreamJson(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error("downstream-json-invalid");
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error("downstream-json-not-object");
+    }
+    const rec = parsed;
+    if (typeof rec.prefix !== "string" || !PREFIX_RE.test(rec.prefix)) {
+        throw new Error("downstream-prefix-invalid");
+    }
+    const cmdVar = rec.command !== undefined;
+    const urlVar = rec.url !== undefined;
+    if (cmdVar && urlVar)
+        throw new Error("downstream-transport-ambiguous");
+    if (!cmdVar && !urlVar)
+        throw new Error("downstream-transport-missing");
+    const spec = { prefix: rec.prefix };
+    if (cmdVar) {
+        if (typeof rec.command !== "string" || rec.command.trim() === "") {
+            throw new Error("downstream-command-invalid");
+        }
+        spec.command = rec.command;
+    }
+    else {
+        if (typeof rec.url !== "string" || rec.url.trim() === "") {
+            throw new Error("downstream-url-invalid");
+        }
+        let parsed;
+        try {
+            parsed = new URL(rec.url);
+        }
+        catch {
+            throw new Error("downstream-url-invalid");
+        }
+        // Only the two schemes the SDK transport speaks. A `file:` or `ftp:` URL
+        // would be read as a fetch target by something later, so it is refused here.
+        if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+            throw new Error("downstream-url-invalid");
+        }
+        spec.url = rec.url;
+        if (rec.headers !== undefined) {
+            if (rec.headers === null || typeof rec.headers !== "object" || Array.isArray(rec.headers)) {
+                throw new Error("downstream-headers-invalid");
+            }
+            const headers = {};
+            for (const [k, v] of Object.entries(rec.headers)) {
+                if (typeof v !== "string")
+                    throw new Error("downstream-headers-invalid");
+                headers[k] = v;
+            }
+            spec.headers = headers;
+        }
+    }
+    if (rec.args !== undefined) {
+        if (!Array.isArray(rec.args) || rec.args.some((a) => typeof a !== "string")) {
+            throw new Error("downstream-args-invalid");
+        }
+        spec.args = rec.args;
+    }
+    if (rec.cwd !== undefined) {
+        if (typeof rec.cwd !== "string" || rec.cwd === "") {
+            throw new Error("downstream-cwd-invalid");
+        }
+        spec.cwd = rec.cwd;
+    }
+    if (rec.env !== undefined) {
+        if (rec.env === null || typeof rec.env !== "object" || Array.isArray(rec.env)) {
+            throw new Error("downstream-env-invalid");
+        }
+        const env = {};
+        for (const [k, v] of Object.entries(rec.env)) {
+            if (typeof v !== "string")
+                throw new Error("downstream-env-invalid");
+            env[k] = v;
+        }
+        spec.env = env;
+    }
+    if (rec.timeoutMs !== undefined) {
+        if (typeof rec.timeoutMs !== "number" || !Number.isInteger(rec.timeoutMs) || rec.timeoutMs <= 0) {
+            throw new Error("downstream-timeout-invalid");
+        }
+        spec.timeoutMs = rec.timeoutMs;
+    }
+    return spec;
+}
+/**
+ * The `VERAX_DOWNSTREAM` document: one child, or an array of them. An empty
+ * array is a document that attaches nothing, which is not the same as no
+ * document at all — the operator wrote it, so it is honoured.
+ */
+export function parseDownstreamDocument(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error("downstream-json-invalid");
+    }
+    const items = Array.isArray(parsed) ? parsed : [parsed];
+    const specs = [];
+    const prefixes = new Set();
+    for (const item of items) {
+        const spec = parseDownstreamJson(JSON.stringify(item));
+        if (prefixes.has(spec.prefix)) {
+            throw new Error(`downstream-prefix-duplicate:${spec.prefix}`);
+        }
+        prefixes.add(spec.prefix);
+        specs.push(spec);
+    }
+    return specs;
+}
+// The SDK result is a union (current shape with an index signature, or the
+// legacy { toolResult } shape), so it is narrowed here rather than trusted.
+function asTextResult(raw) {
+    const rec = raw !== null && typeof raw === "object" ? raw : {};
+    const content = [];
+    const items = Array.isArray(rec.content) ? rec.content : [];
+    for (const item of items) {
+        if (item !== null &&
+            typeof item === "object" &&
+            item.type === "text" &&
+            typeof item.text === "string") {
+            content.push({ type: "text", text: item.text });
+            continue;
+        }
+        content.push({ type: "text", text: JSON.stringify(item) });
+    }
+    return {
+        content: content.length > 0 ? content : [{ type: "text", text: "" }],
+        isError: rec.isError === true,
+    };
+}
+async function shut(client, transport) {
+    await client.close().catch(() => undefined);
+    await transport.close().catch(() => undefined);
+}
+/** Spawns the child. Its stderr is drained so a chatty child cannot block it. */
+function stdioTransport(spec) {
+    if (spec.command === undefined || spec.command.trim() === "") {
+        throw new Error("downstream-command-invalid");
+    }
+    // Safe inherit + operator overlay. Not process.env: that would copy
+    // VERAX_* tokens the body already holds.
+    const env = { ...getDefaultEnvironment(), ...(spec.env ?? {}) };
+    const transport = new StdioClientTransport({
+        command: spec.command,
+        args: spec.args,
+        cwd: spec.cwd,
+        env,
+        stderr: "pipe",
+    });
+    // The SDK types the pipe as Stream; only a Readable can be drained.
+    const stderr = transport.stderr;
+    if (stderr instanceof Readable)
+        stderr.resume();
+    return transport;
+}
+/**
+ * Talks to a server already running. The headers are the operator's, from the
+ * document — the body's own bearer is never forwarded, for the same
+ * confused-deputy reason the stdio child does not inherit `VERAX_*`.
+ */
+function httpTransport(spec) {
+    if (spec.url === undefined)
+        throw new Error("downstream-url-invalid");
+    return new StreamableHTTPClientTransport(new URL(spec.url), {
+        ...(spec.headers ? { requestInit: { headers: spec.headers } } : {}),
+    });
+}
+export async function openDownstream(spec) {
+    if (!PREFIX_RE.test(spec.prefix)) {
+        throw new Error("downstream-prefix-invalid");
+    }
+    if (spec.command !== undefined && spec.url !== undefined) {
+        throw new Error("downstream-transport-ambiguous");
+    }
+    if (spec.command === undefined && spec.url === undefined) {
+        throw new Error("downstream-transport-missing");
+    }
+    const timeoutMs = spec.timeoutMs ?? 10_000;
+    const transport = spec.url !== undefined ? httpTransport(spec) : stdioTransport(spec);
+    const client = new Client({ name: "verax-downstream", version: "0.0.0" });
+    let listed;
+    try {
+        await client.connect(transport);
+        listed = await client.listTools();
+    }
+    catch (err) {
+        await shut(client, transport);
+        throw err;
+    }
+    const tools = [];
+    const seen = new Set();
+    for (const tool of listed.tools) {
+        if (!CHILD_TOOL_RE.test(tool.name)) {
+            await shut(client, transport);
+            throw new Error(`downstream-child-name-invalid:${tool.name}`);
+        }
+        const name = prefixedName(spec.prefix, tool.name);
+        if (seen.has(name)) {
+            await shut(client, transport);
+            throw new Error(`downstream-name-collision:${name}`);
+        }
+        seen.add(name);
+        const childName = tool.name;
+        tools.push({
+            name,
+            ...(typeof tool.description === "string" ? { description: tool.description } : {}),
+            ...(tool.inputSchema !== undefined ? { inputSchema: tool.inputSchema } : {}),
+            fn: async (call) => {
+                let raw;
+                try {
+                    // Mutation check: stub this call and the allow test expecting
+                    // "pong":true from the child goes red.
+                    raw = await client.callTool({ name: childName, arguments: call.arguments }, undefined, { timeout: timeoutMs });
+                }
+                catch (err) {
+                    throw new DownstreamCallError(spec.prefix, childName, err);
+                }
+                const result = asTextResult(raw);
+                if (result.isError) {
+                    throw new DownstreamCallError(spec.prefix, childName, textOf(result) || "isError");
+                }
+                return result;
+            },
+        });
+    }
+    let closed = false;
+    return {
+        prefix: spec.prefix,
+        tools,
+        async close() {
+            if (closed)
+                return;
+            closed = true;
+            await shut(client, transport);
+        },
+    };
+}
+function textOf(result) {
+    return result.content.map((c) => c.text).join("");
+}

package/dist/inputs-read.d.ts

@@ -1,3 +1,10 @@
+/**
+ * The inputs documents behind these decisions, keyed by ref, each checked
+ * against the hash its decision recorded. inputs.jsonl is written in the
+ * same order as decisions.jsonl, so the rows for a window of decisions sit
+ * near its end: the file is read from there, and the read stops once every
+ * ref has been seen. The newest row for a ref is the one that counts.
+ */
 export declare function matchingInputs(stateDir: string, decisions: {
     claims: {
         ref: string | null;

package/dist/inputs-read.js

@@ -1,57 +1,64 @@
 import { createHash } from "node:crypto";
 import { readFile } from "node:fs/promises";
-import { join } from "node:path";
 import { canonical } from "@cedulon/core";
+import { listPieceFiles, readLedgerTail } from "@verax-ai/proxy";
 function sha256Canonical(value) {
     return createHash("sha256").update(canonical(value), "utf8").digest("hex");
 }
+/**
+ * The inputs documents behind these decisions, keyed by ref, each checked
+ * against the hash its decision recorded. inputs.jsonl is written in the
+ * same order as decisions.jsonl, so the rows for a window of decisions sit
+ * near its end: the file is read from there, and the read stops once every
+ * ref has been seen. The newest row for a ref is the one that counts.
+ */
 export async function matchingInputs(stateDir, decisions) {
-    let text;
-    try {
-        text = await readFile(join(stateDir, "inputs.jsonl"), "utf8");
-    }
-    catch (err) {
-        if (err.code === "ENOENT")
-            return {};
-        throw err;
-    }
-    const byRef = new Map();
-    for (const line of text.split("\n")) {
-        if (line === "")
-            continue;
-        const row = JSON.parse(line);
-        if (typeof row.ref === "string")
-            byRef.set(row.ref, row.inputs);
+    const wanted = new Map();
+    for (const d of decisions) {
+        if (d.claims.ref && typeof d.claims.inputsHash === "string")
+            wanted.set(d.claims.ref, d.claims.inputsHash);
     }
     const out = {};
-    for (const d of decisions) {
-        const ref = d.claims.ref;
-        if (!ref || typeof d.claims.inputsHash !== "string")
-            continue;
-        const doc = byRef.get(ref);
-        if (doc !== undefined && sha256Canonical(doc) === d.claims.inputsHash) {
-            out[ref] = doc;
-        }
+    if (wanted.size === 0)
+        return out;
+    const seen = new Set();
+    const pieces = [...listPieceFiles(stateDir)].reverse();
+    for (const piece of pieces) {
+        if (seen.size === wanted.size)
+            break;
+        await readLedgerTail(piece.inputs, (row) => {
+            if (typeof row.ref !== "string" || seen.has(row.ref))
+                return "skip";
+            const hash = wanted.get(row.ref);
+            if (hash === undefined)
+                return "skip";
+            seen.add(row.ref);
+            if (sha256Canonical(row.inputs) === hash)
+                out[row.ref] = row.inputs;
+            return seen.size === wanted.size ? "stop" : "skip";
+        });
     }
     return out;
 }
 export async function inputsPrincipal(stateDir, ref) {
-    let text;
-    try {
-        text = await readFile(join(stateDir, "inputs.jsonl"), "utf8");
-    }
-    catch (err) {
-        if (err.code === "ENOENT")
-            return null;
-        throw err;
-    }
     let found = null;
-    for (const line of text.split("\n")) {
-        if (line === "")
-            continue;
-        const row = JSON.parse(line);
-        if (row.ref === ref)
-            found = row.inputs?.principal ?? null;
+    for (const piece of listPieceFiles(stateDir)) {
+        let text;
+        try {
+            text = await readFile(piece.inputs, "utf8");
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                continue;
+            throw err;
+        }
+        for (const line of text.split("\n")) {
+            if (line === "")
+                continue;
+            const row = JSON.parse(line);
+            if (row.ref === ref)
+                found = row.inputs?.principal ?? null;
+        }
     }
     if (!found || typeof found.brain !== "string")
         return null;

package/dist/no-bypass-scan.js

@@ -26,6 +26,9 @@ const CREATE_REQUIRE = /\bcreateRequire\b/;
 const CONCAT_TOOLS = /["']\.\/to["']\s*\+\s*["']ols/;
 const CHILD = /\bchild_process\b/;
 const WORKER = /\bworker_threads\b/;
+// The SDK stdio client transport spawns a process without naming
+// child_process in this tree. Only src/downstream.ts may use it.
+const SDK_STDIO = /client\/stdio\.js|\bStdioClientTransport\b/;
 function lineAt(text, index) {
     return text.slice(0, index).split(/\n/).length;
 }
@@ -51,6 +54,8 @@ export function scanNoBypass(base = pkgRoot, extra = []) {
         const wiring = rel === "src/wiring.ts";
         // Desktop supervises issuer/body/panel. It is not a tool-call path.
         const desktop = rel === "src/desktop.ts";
+        // The downstream spike attaches one stdio MCP server. Not a tool-call path.
+        const downstream = rel === "src/downstream.ts";
         const originalLines = text.split(/\r?\n/);
         for (const match of text.matchAll(DYNAMIC_IMPORT)) {
             const index = match.index ?? 0;
@@ -89,6 +94,8 @@ export function scanNoBypass(base = pkgRoot, extra = []) {
                 push("child_process");
             if (WORKER.test(line))
                 push("worker_threads");
+            if (SDK_STDIO.test(line) && !downstream)
+                push("sdk-stdio-spawn");
         }
     }
     return hits;

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 };