@verax-ai/body 0.1.1 → 0.1.2

package/dist/agents.d.ts

@@ -0,0 +1,33 @@
+import { type FileLedger } from "@verax-ai/proxy";
+export type AgentRow = {
+    brain: string;
+    decisions: number;
+    allowed: number;
+    denied: number;
+    deferred: number;
+    /** Approvals waiting on an operator now, whatever the window. */
+    pending: number;
+    /** The newest decision in the window, or null when there was none. */
+    lastMs: number | null;
+    /** What the roster declares; null for an agent the roster does not name. */
+    roster: {
+        state: string;
+        label: string;
+        group: string | null;
+    } | null;
+};
+export type AgentsAnswer = {
+    fromMs: number;
+    toMs: number;
+    /** Pending first, then the most recently active; ties by name. */
+    agents: AgentRow[];
+    /** Decisions in the window whose inputs document was not found or did not match its hash. */
+    unattributed: number;
+};
+export declare function agentsWindow(opts: {
+    ledger: FileLedger;
+    stateDir: string;
+    inventoryFile: string | null | undefined;
+    fromMs: number;
+    toMs: number;
+}): Promise<AgentsAnswer>;

package/dist/agents.js

@@ -0,0 +1,59 @@
+// One row per agent for the panel's status tab: what each did in a window
+// of the ledger, what is waiting on an operator for it, when it last acted,
+// and what the roster says about it. A company runs hundreds of agents; the
+// operator reads this list, not the records. The window is read from the
+// end of the ledger, so the answer costs the window and not the ledger.
+import { parseInventory } from "@verax-ai/inventory";
+import { loadApprovalsFromDir } from "@verax-ai/proxy";
+import { matchingInputs } from "./inputs-read.js";
+import { readInventoryFile } from "./inventory-file.js";
+export async function agentsWindow(opts) {
+    const { rows } = await opts.ledger.decisionsWindow(opts.fromMs, opts.toMs);
+    const inputs = (await matchingInputs(opts.stateDir, rows));
+    const byBrain = new Map();
+    const rowFor = (brain) => {
+        let row = byBrain.get(brain);
+        if (!row) {
+            row = { brain, decisions: 0, allowed: 0, denied: 0, deferred: 0, pending: 0, lastMs: null, roster: null };
+            byBrain.set(brain, row);
+        }
+        return row;
+    };
+    let unattributed = 0;
+    for (const d of rows) {
+        const ref = d.claims.ref;
+        const brain = typeof ref === "string" ? inputs[ref]?.principal?.brain : undefined;
+        if (typeof brain !== "string" || brain === "") {
+            unattributed += 1;
+            continue;
+        }
+        const row = rowFor(brain);
+        row.decisions += 1;
+        if (d.claims.decision === "allow")
+            row.allowed += 1;
+        else if (d.claims.decision === "deny")
+            row.denied += 1;
+        else if (d.claims.decision === "defer")
+            row.deferred += 1;
+        if (row.lastMs === null || d.claims.timestampMs > row.lastMs)
+            row.lastMs = d.claims.timestampMs;
+    }
+    for (const approval of loadApprovalsFromDir(opts.stateDir)) {
+        if (approval.status === "pending")
+            rowFor(approval.brain).pending += 1;
+    }
+    const door = readInventoryFile(opts.inventoryFile);
+    const parsed = door.inventory == null ? null : parseInventory(door.inventory);
+    if (parsed && parsed.ok) {
+        const groups = new Map(parsed.value.groups.map((g) => [g.id, g.label]));
+        for (const agent of parsed.value.agents) {
+            rowFor(agent.id).roster = {
+                state: agent.state,
+                label: agent.label,
+                group: agent.groupId === null ? null : (groups.get(agent.groupId) ?? agent.groupId),
+            };
+        }
+    }
+    const agents = [...byBrain.values()].sort((a, b) => b.pending - a.pending || (b.lastMs ?? -1) - (a.lastMs ?? -1) || a.brain.localeCompare(b.brain));
+    return { fromMs: opts.fromMs, toMs: opts.toMs, agents, unattributed };
+}

package/dist/approve-cli.js

@@ -1,6 +1,28 @@
+import { existsSync, readFileSync } from "node:fs";
 import { userInfo } from "node:os";
-import { approvePending, approvalsLogFor, enqueueApprovalCommand, FileLedger, loadApprovalsFromDir } from "@verax-ai/proxy";
+import { join } from "node:path";
+import { approvePending, approvalsLogFor, createApprovalBudgetGuard, enqueueApprovalCommand, FileLedger, loadApprovalsFromDir, loadPolicy, } from "@verax-ai/proxy";
 import { loadOrCreateSigners } from "./keys.js";
+function policyForApprove(stateDir, policyHash) {
+    const fromEnv = process.env.VERAX_POLICY_FILE?.trim();
+    if (fromEnv) {
+        try {
+            return loadPolicy(readFileSync(fromEnv, "utf8"));
+        }
+        catch {
+            // Fall through to the snapshot the body wrote for this hash.
+        }
+    }
+    const snap = join(stateDir, "policies", `${policyHash}.json`);
+    if (!existsSync(snap))
+        return null;
+    try {
+        return loadPolicy(JSON.parse(readFileSync(snap, "utf8")));
+    }
+    catch {
+        return null;
+    }
+}
 function operatorName() {
     try {
         const name = userInfo().username;
@@ -65,6 +87,7 @@ export async function runApprove(argv, writeErr = (s) => process.stderr.write(s)
             writeErr("approve-unknown-ref\n");
             return 78;
         }
+        const policy = policyForApprove(stateDir, defer.claims.policyHash);
         const result = await approvePending({
             ledger,
             recordSigner: signers.recordSigner,
@@ -75,6 +98,9 @@ export async function runApprove(argv, writeErr = (s) => process.stderr.write(s)
             via: "cli",
             policyHash: defer.claims.policyHash,
             approvals,
+            ...(policy
+                ? { budgetGuard: createApprovalBudgetGuard({ policy, approvals, now: () => Date.now() }) }
+                : {}),
         });
         if (!result.ok) {
             writeErr(`approve-${result.reason}\n`);

package/dist/cli.js

@@ -23,7 +23,7 @@ Usage: verax <command> [options]
   witness <stateDir>   run the witness alongside a body
   halt <stateDir>      stop the body from allowing anything further
   unlock [--force] <stateDir>   clear a stale ledger lock
-  desktop <args>       open the local panel
+  desktop <args>       open the local panel, joining the body that holds the ledger if one is up
 
   --help, -h           print this
   --version, -v        print the version

package/dist/desktop.d.ts

@@ -17,6 +17,29 @@ export declare function parseDesktopArgs(argv: string[]): DesktopOpts | {
     error: string;
 };
 export declare function portOpen(port: number, host?: string): Promise<boolean>;
+/** GET /healthz on the loopback port; true only for a 200. */
+export declare function healthzUp(port: number): Promise<boolean>;
+export type DesktopMode = {
+    mode: "spawn";
+} | {
+    mode: "attach";
+    pid: number;
+} | {
+    error: "desktop-body-locked";
+    pid: number;
+};
+/**
+ * One ledger, one body. The desktop used to build its own issuer and body on
+ * every open, which on a machine whose body starts at logon put the window on
+ * a second, empty ledger: the panel looked broken while the real decisions sat
+ * in the directory the lock names. So the lock is read first. Held by a live
+ * process that answers /healthz where this run was told to look, the panel
+ * joins that body. Held by a live process that does not answer there, the
+ * desktop stops: someone owns the ledger and is not where we were pointed, and
+ * a second body would be refused by the lock anyway. A dead or unreadable lock
+ * is the body's own to clear (`verax unlock`); the desktop builds as before.
+ */
+export declare function desktopMode(stateDir: string, bodyPort: number, probe?: (port: number) => Promise<boolean>): Promise<DesktopMode>;
 export declare function killTree(pid: number | undefined): void;
 /** The panel's redirect is its own origin, so the issuer has to be told which port
  *  this run put it on: the allow-list default only holds 5173 and 4173. */

package/dist/desktop.js

@@ -1,8 +1,10 @@
 import { spawn, spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { get } from "node:http";
 import { createConnection } from "node:net";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { pidAlive, readLockFile } from "./unlock.js";
 const here = dirname(fileURLToPath(import.meta.url));
 const repoRoot = join(here, "..", "..", "..");
 /** Newest modification time under a file or directory, ignoring build output. */
@@ -110,6 +112,42 @@ async function waitPort(port, ms) {
     }
     return false;
 }
+/** GET /healthz on the loopback port; true only for a 200. */
+export function healthzUp(port) {
+    return new Promise((resolve) => {
+        const req = get({ host: "127.0.0.1", port, path: "/healthz", timeout: 3_000 }, (res) => {
+            res.resume();
+            resolve(res.statusCode === 200);
+        });
+        req.once("timeout", () => {
+            req.destroy();
+            resolve(false);
+        });
+        req.once("error", () => resolve(false));
+    });
+}
+/**
+ * One ledger, one body. The desktop used to build its own issuer and body on
+ * every open, which on a machine whose body starts at logon put the window on
+ * a second, empty ledger: the panel looked broken while the real decisions sat
+ * in the directory the lock names. So the lock is read first. Held by a live
+ * process that answers /healthz where this run was told to look, the panel
+ * joins that body. Held by a live process that does not answer there, the
+ * desktop stops: someone owns the ledger and is not where we were pointed, and
+ * a second body would be refused by the lock anyway. A dead or unreadable lock
+ * is the body's own to clear (`verax unlock`); the desktop builds as before.
+ */
+export async function desktopMode(stateDir, bodyPort, probe = healthzUp) {
+    const lockPath = join(stateDir, "ledger.lock");
+    if (!existsSync(lockPath))
+        return { mode: "spawn" };
+    const lock = readLockFile(lockPath);
+    if (!lock || !pidAlive(lock.pid))
+        return { mode: "spawn" };
+    if (await probe(bodyPort))
+        return { mode: "attach", pid: lock.pid };
+    return { error: "desktop-body-locked", pid: lock.pid };
+}
 export function killTree(pid) {
     if (pid == null)
         return;
@@ -206,36 +244,48 @@ export async function runDesktop(opts, writeErr = (s) => process.stderr.write(s)
             killTree(c.pid);
     };
     try {
-        const issuer = spawnLogged(process.execPath, ["--experimental-strip-types", issuerScript, "--out", tokenPath], issuerEnv(cleanEnv(), opts, audience, issuerUrl), repoRoot);
-        kids.push(issuer);
-        collectOutput(issuer, log);
-        if (!(await waitPort(opts.issuerPort, 15_000))) {
-            writeErr("desktop-issuer-timeout\n");
-            stopAll();
-            return 1;
-        }
-        const token = readFileSync(tokenPath, "utf8").trim();
-        if (token === "") {
-            writeErr("desktop-token-missing\n");
-            stopAll();
+        const decided = await desktopMode(opts.stateDir, opts.bodyPort);
+        if ("error" in decided) {
+            writeErr(`${decided.error}:${decided.pid}\n`);
             return 1;
         }
-        const body = spawnLogged(process.execPath, ["--experimental-strip-types", mainTs], {
-            ...cleanEnv(),
-            VERAX_STATE_DIR: opts.stateDir,
-            VERAX_ISSUER: issuerUrl,
-            VERAX_JWKS_URL: `${issuerUrl}/.well-known/jwks.json`,
-            VERAX_AUDIENCE: audience,
-            VERAX_BIND: `127.0.0.1:${opts.bodyPort}`,
-            VERAX_POLICY_FILE: policy,
-            ...(opts.inventoryFile ? { VERAX_INVENTORY_FILE: opts.inventoryFile } : {}),
-        }, repoRoot);
-        kids.push(body);
-        collectOutput(body, log);
-        if (!(await waitPort(opts.bodyPort, 15_000))) {
-            writeErr("desktop-body-timeout\n");
-            stopAll();
-            return 1;
+        // Joining a running body: its issuer is whatever the body's resource
+        // metadata names, and its token is not ours to read. The panel's own
+        // origin has to be on that issuer's allow-list (VERAX_DEV_REDIRECT_URIS on
+        // the running issuer), which this run cannot set after the fact.
+        let token = null;
+        if (decided.mode === "spawn") {
+            const issuer = spawnLogged(process.execPath, ["--experimental-strip-types", issuerScript, "--out", tokenPath], issuerEnv(cleanEnv(), opts, audience, issuerUrl), repoRoot);
+            kids.push(issuer);
+            collectOutput(issuer, log);
+            if (!(await waitPort(opts.issuerPort, 15_000))) {
+                writeErr("desktop-issuer-timeout\n");
+                stopAll();
+                return 1;
+            }
+            token = readFileSync(tokenPath, "utf8").trim();
+            if (token === "") {
+                writeErr("desktop-token-missing\n");
+                stopAll();
+                return 1;
+            }
+            const body = spawnLogged(process.execPath, ["--experimental-strip-types", mainTs], {
+                ...cleanEnv(),
+                VERAX_STATE_DIR: opts.stateDir,
+                VERAX_ISSUER: issuerUrl,
+                VERAX_JWKS_URL: `${issuerUrl}/.well-known/jwks.json`,
+                VERAX_AUDIENCE: audience,
+                VERAX_BIND: `127.0.0.1:${opts.bodyPort}`,
+                VERAX_POLICY_FILE: policy,
+                ...(opts.inventoryFile ? { VERAX_INVENTORY_FILE: opts.inventoryFile } : {}),
+            }, repoRoot);
+            kids.push(body);
+            collectOutput(body, log);
+            if (!(await waitPort(opts.bodyPort, 15_000))) {
+                writeErr("desktop-body-timeout\n");
+                stopAll();
+                return 1;
+            }
         }
         const panelSources = [
             join(panelDir, "src"),
@@ -290,12 +340,14 @@ export async function runDesktop(opts, writeErr = (s) => process.stderr.write(s)
         const browser = spawnLogged(browserBin, browserArgv, cleanEnv(), repoRoot, false);
         kids.push(browser);
         collectOutput(browser, log);
-        if (log.text.includes(token)) {
+        if (token !== null && log.text.includes(token)) {
             writeErr("desktop-token-leaked\n");
             stopAll();
             return 1;
         }
-        process.stdout.write(`desktop-ready issuer=${opts.issuerPort} body=${opts.bodyPort} panel=${opts.panelPort}\n`);
+        process.stdout.write(decided.mode === "attach"
+            ? `desktop-ready body=${opts.bodyPort} panel=${opts.panelPort} attached=1 pid=${decided.pid}\n`
+            : `desktop-ready issuer=${opts.issuerPort} body=${opts.bodyPort} panel=${opts.panelPort}\n`);
         const onSignal = () => {
             stopAll();
             process.exit(1);

package/dist/doctor.js

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
+import { indexCoverage, listPieceFiles } from "@verax-ai/proxy";
 import { loadConfig, isLoopbackHost } from "./config.js";
 import { pidAlive, readLockFile } from "./unlock.js";
 const SECRET_RE = /sk-|-----BEGIN|Bearer |eyJ[A-Za-z0-9_-]{10,}\./;
@@ -263,7 +264,51 @@ function heartbeatMaxMs(env) {
 }
 function evidenceChecks(stateDir, env) {
     const checks = [];
-    const src = countJsonl(join(stateDir, "decisions.jsonl"));
+    let pieces;
+    try {
+        pieces = listPieceFiles(stateDir);
+    }
+    catch (err) {
+        checks.push({ id: "ledger-manifest", level: "fail", detail: err.message });
+        return checks;
+    }
+    const srcLines = pieces.reduce((s, p) => s + countJsonl(p.decisions).lines, 0);
+    const decisionN = pieces.reduce((s, p) => s + (p.closed ? p.n : countJsonl(p.decisions).lines), 0);
+    if (decisionN > 0) {
+        const known = new Set(pieces.map((p) => p.id));
+        const cov = indexCoverage(stateDir);
+        if (cov === null) {
+            checks.push({
+                id: "ledger-index",
+                level: "fail",
+                detail: `index names 0 of ${decisionN} decisions; the next open rebuilds it, a running body misses the rest until then`,
+            });
+        }
+        else {
+            const ghost = [...cov.pieces].find((id) => !known.has(id));
+            if (ghost !== undefined) {
+                checks.push({
+                    id: "ledger-index",
+                    level: "fail",
+                    detail: `index names piece ${ghost} that the manifest does not`,
+                });
+            }
+            else if (cov.refs === decisionN) {
+                checks.push({
+                    id: "ledger-index",
+                    level: "ok",
+                    detail: `index names ${decisionN} of ${decisionN} decisions`,
+                });
+            }
+            else {
+                checks.push({
+                    id: "ledger-index",
+                    level: "fail",
+                    detail: `index names ${cov.refs} of ${decisionN} decisions; the next open rebuilds it, a running body misses the rest until then`,
+                });
+            }
+        }
+    }
     const hbPath = join(stateDir, "heartbeat.json");
     let hb = null;
     if (existsSync(hbPath)) {
@@ -274,7 +319,7 @@ function evidenceChecks(stateDir, env) {
             hb = null;
         }
     }
-    if (src.lines > 0 || hb) {
+    if (srcLines > 0 || hb) {
         if (!hb || typeof hb.atMs !== "number") {
             checks.push({
                 id: "heartbeat",
@@ -297,46 +342,58 @@ function evidenceChecks(stateDir, env) {
             });
         }
     }
-    // Both halves of the evidence are mirrored, so both are compared: an effects
-    // copy that quietly drops rows is the same silence as a missing decision copy.
-    const srcEffects = countJsonl(join(stateDir, "effects.jsonl"));
-    const copy = countJsonl(join(stateDir, "evidence-copy", "decisions.jsonl"));
-    const copyEffects = countJsonl(join(stateDir, "evidence-copy", "effects.jsonl"));
-    const anything = src.lines > 0 ||
-        srcEffects.lines > 0 ||
-        copy.lines > 0 ||
-        copyEffects.lines > 0 ||
-        copy.corrupt ||
-        copyEffects.corrupt;
-    if (anything) {
+    // Each piece is mirrored on its own, so a short copy on one piece is a fail
+    // even when another piece's copy still matches.
+    let anything = false;
+    let fail = null;
+    let decisionLines = 0;
+    let effectLines = 0;
+    for (const piece of pieces) {
+        const src = countJsonl(piece.decisions);
+        const srcEffects = countJsonl(piece.effects);
+        const copy = countJsonl(piece.copyDecisions);
+        const copyEffects = countJsonl(piece.copyEffects);
+        decisionLines += src.lines;
+        effectLines += srcEffects.lines;
+        const pieceAnything = src.lines > 0 ||
+            srcEffects.lines > 0 ||
+            copy.lines > 0 ||
+            copyEffects.lines > 0 ||
+            copy.corrupt ||
+            copyEffects.corrupt;
+        if (!pieceAnything)
+            continue;
+        anything = true;
+        if (fail)
+            continue;
         if (copy.corrupt || copyEffects.corrupt) {
-            checks.push({
+            fail = {
                 id: "evidence-copy",
                 level: "fail",
-                detail: `evidence-copy/${copy.corrupt ? "decisions" : "effects"}.jsonl is corrupt`,
-            });
+                detail: `evidence-copy piece ${piece.id} ${copy.corrupt ? "decisions" : "effects"}.jsonl is corrupt`,
+            };
         }
         else if (copy.lines < src.lines) {
-            checks.push({
+            fail = {
                 id: "evidence-copy",
                 level: "fail",
-                detail: `evidence copy is stale: ${copy.lines} lines behind source ${src.lines}`,
-            });
+                detail: `evidence copy is stale on piece ${piece.id}: ${copy.lines} lines behind source ${src.lines}`,
+            };
         }
         else if (copyEffects.lines < srcEffects.lines) {
-            checks.push({
+            fail = {
                 id: "evidence-copy",
                 level: "fail",
-                detail: `evidence copy is stale on effects: ${copyEffects.lines} effect line(s) behind source ${srcEffects.lines}`,
-            });
-        }
-        else {
-            checks.push({
-                id: "evidence-copy",
-                level: "ok",
-                detail: `evidence copy has ${copy.lines} decision line(s) and ${copyEffects.lines} effect line(s)`,
-            });
+                detail: `evidence copy is stale on piece ${piece.id} effects: ${copyEffects.lines} effect line(s) behind source ${srcEffects.lines}`,
+            };
         }
     }
+    if (anything) {
+        checks.push(fail ?? {
+            id: "evidence-copy",
+            level: "ok",
+            detail: `evidence copy has ${decisionLines} decision line(s) and ${effectLines} effect line(s)`,
+        });
+    }
     return checks;
 }

package/dist/downstream.d.ts

@@ -0,0 +1,28 @@
+import type { Principal, ToolCall, ToolResult } from "@verax-ai/proxy";
+export type DownstreamToolFn = (call: ToolCall, principal: Principal, ref?: string) => Promise<ToolResult>;
+export type DownstreamSpec = {
+    prefix: string;
+    command: string;
+    args?: string[];
+    cwd?: string;
+    env?: Record<string, string>;
+    timeoutMs?: number;
+};
+export type DownstreamTool = {
+    name: string;
+    fn: DownstreamToolFn;
+};
+export type DownstreamSession = {
+    prefix: string;
+    tools: readonly DownstreamTool[];
+    close(): Promise<void>;
+};
+export declare class DownstreamCallError extends Error {
+    readonly prefix: string;
+    readonly tool: string;
+    constructor(prefix: string, tool: string, cause?: unknown);
+}
+export declare function prefixedName(prefix: string, childName: string): string;
+export declare function extraToolNameOk(name: string): boolean;
+export declare function parseDownstreamJson(raw: string): DownstreamSpec;
+export declare function openDownstream(spec: DownstreamSpec): Promise<DownstreamSession>;