@zanii/blackbox 0.9.0 → 0.11.0

package/README.md

@@ -83,6 +83,19 @@ verifyAnswerCredential(credential, lines, bodies, packs); // { ok, problems }: t
 
 The same checks run offline as pure functions: `toolHallucinations`, `groundingFindings`, `factsIn`, `loadReferencePacks`, `answerRisk`, `detectorAccuracy`.
 
+## New in 0.11.0
+
+- Facts against the record compare currencies and units: `AED 500` in a tool result no longer grounds `USD 500` in the answer, nor `500 g` grounds `500 mg` (`currencyCodes`, `unitOf`). Dates written with an English or Arabic month (`3 March 2026`, `3 مارس 2026`) are facts too.
+- `blackbox policy-hook`: a Claude Code / Codex PreToolUse hook that asks the gateway's policy before a local tool runs, and fails closed.
+- Works with gateway v0.13 (`POST /v1/sessions/:id/policy-check`).
+
+## New in 0.10.0
+
+- `setTenantPolicy` / `tenantPolicy` / `removeTenantPolicy`: a tenant's own rules, hot on the gateway. `setProviderKey` / `providerKeys` / `removeProviderKey`: a tenant's own model keys, sealed. `cancelRun(sessionId, runId)`: stop one run (calls carrying `x-blackbox-run`).
+- `loadPolicy` refuses an `args_match` that JavaScript and Python would read differently (`portableRegexError`).
+- `blackbox sessions --outcome success|failure|abandoned`.
+- Works with gateway v0.12: alert routing to PagerDuty, Teams, Alertmanager and Slack; the key passphrase from Vault or AWS KMS.
+
 ## New in 0.9.0
 
 - `client(...).createKey(tenantId, {scope: "approve", expires_in_days})`: a key that only decides approvals (and labels findings), and keys that expire.

package/dist/analysis/grounding.d.ts

@@ -10,7 +10,14 @@ export interface Fact {
     at: number;
     end: number;
     currency?: string;
+    /** Quantities: the canonical unit (spec/findings.md §9). */
+    unit?: string;
 }
+/** spec/findings.md §9: the ISO codes a written currency may be (a symbol or a word names a
+ * family: "$" is any dollar). */
+export declare function currencyCodes(written: string): string[];
+/** spec/findings.md §9: a written unit's canonical unit. */
+export declare const unitOf: (written: string) => string;
 /** The facts an answer states: money, percentages, quantities, ISO dates, then identifiers (as H1's). */
 export declare function factsIn(text: string): Fact[];
 /** What the agent was given, to check facts against: the record lines it came from (§11 points at
@@ -30,7 +37,9 @@ export declare class Evidence {
     /**
      * The seqs of the lines that hold a fact, or null. Money, percentages and quantities: the same
      * number, the same in minor units, a percentage as a fraction, or (money) the sum of two of the
-     * evidence's numbers. Dates and identifiers: the normalised text.
+     * evidence's numbers. A number the evidence writes only with another currency or unit doesn't
+     * hold it (AED 500 isn't USD 500; 500 g isn't 500 mg); one it writes bare does. Dates and
+     * identifiers: the normalised text (a date in words as its ISO form).
      */
     support(f: Fact): number[] | null;
     private pairSums;

package/dist/analysis/grounding.js

@@ -19,9 +19,291 @@ const MONEY = new RegExp(`(?<![A-Za-z])(${CURRENCY})\\s?(${AMOUNT})(?![0-9])|(?<
 const PERCENT = new RegExp(`(?<![0-9.,])(${AMOUNT})\\s?(?:%|٪|percent|per cent|بالمائة|في المائة)`, "gi");
 // any measured quantity: a dose, a weight, a distance, a duration ("within 14 days")
 const UNIT = "mg/dL|mmol/L|mcg|µg|mg|kg|g|mL|ml|L|km|cm|mm|m|mi|ft|lbs|lb|oz|°C|°F|kWh|MWh|kW|MW|IU|hours|hour|hrs|hr|h|minutes|minute|mins|min|seconds|second|secs|days|day|weeks|week|months|month|years|year|units|unit|items|pieces|tablets|doses|ملغ|مجم|غرام|كغ|كيلوغرام|مل|لتر|كم|متر|ساعة|ساعات|دقيقة|دقائق|يوم|أيام|أسبوع|أسابيع|شهر|أشهر|سنة|سنوات|وحدة|حبة|جرعة";
-const QUANTITY = new RegExp(`(?<![0-9.,])(${AMOUNT})\\s?(?:${UNIT})(?![A-Za-z\u0600-\u06FF])`, "g");
+const QUANTITY = new RegExp(`(?<![0-9.,])(${AMOUNT})\\s?(${UNIT})(?![A-Za-z\u0600-\u06FF])`, "g");
 const ISO_DATE = /(?<![0-9])[0-9]{4}-[0-9]{2}-[0-9]{2}(?![0-9])/g;
 const NUMBER = new RegExp(`(?<![0-9.,])(?:${AMOUNT})(?![0-9])`, "g");
+// spec/grounding-tables.json, inline (both SDKs carry the same tables)
+const FAMILIES = {
+    $: [
+        "USD",
+        "CAD",
+        "AUD",
+        "NZD",
+        "SGD",
+        "HKD",
+        "TWD",
+        "JMD",
+        "BSD",
+        "BBD",
+        "BZD",
+        "BMD",
+        "BND",
+        "FJD",
+        "GYD",
+        "KYD",
+        "LRD",
+        "NAD",
+        "SBD",
+        "SRD",
+        "TTD",
+        "XCD",
+    ],
+    dollar: [
+        "USD",
+        "CAD",
+        "AUD",
+        "NZD",
+        "SGD",
+        "HKD",
+        "TWD",
+        "JMD",
+        "BSD",
+        "BBD",
+        "BZD",
+        "BMD",
+        "BND",
+        "FJD",
+        "GYD",
+        "KYD",
+        "LRD",
+        "NAD",
+        "SBD",
+        "SRD",
+        "TTD",
+        "XCD",
+    ],
+    دولار: [
+        "USD",
+        "CAD",
+        "AUD",
+        "NZD",
+        "SGD",
+        "HKD",
+        "TWD",
+        "JMD",
+        "BSD",
+        "BBD",
+        "BZD",
+        "BMD",
+        "BND",
+        "FJD",
+        "GYD",
+        "KYD",
+        "LRD",
+        "NAD",
+        "SBD",
+        "SRD",
+        "TTD",
+        "XCD",
+    ],
+    "€": ["EUR"],
+    euro: ["EUR"],
+    يورو: ["EUR"],
+    "£": ["GBP", "EGP", "LBP", "SYP", "SDG", "SSP", "GIP", "FKP", "SHP"],
+    pound: ["GBP", "EGP", "LBP", "SYP", "SDG", "SSP", "GIP", "FKP", "SHP"],
+    جنيه: ["GBP", "EGP", "LBP", "SYP", "SDG", "SSP", "GIP", "FKP", "SHP"],
+    "¥": ["JPY", "CNY"],
+    yen: ["JPY"],
+    yuan: ["CNY"],
+    "₹": ["INR"],
+    rupee: ["INR", "PKR", "LKR", "NPR", "MUR", "SCR"],
+    "₩": ["KRW"],
+    "₽": ["RUB"],
+    "₺": ["TRY"],
+    lira: ["TRY", "LBP", "SYP"],
+    "₪": ["ILS"],
+    "฿": ["THB"],
+    "₫": ["VND"],
+    "₦": ["NGN"],
+    naira: ["NGN"],
+    "₱": ["PHP"],
+    dirham: ["AED", "MAD"],
+    dh: ["AED", "MAD"],
+    dhs: ["AED", "MAD"],
+    "د.إ": ["AED"],
+    درهم: ["AED", "MAD"],
+    دراهم: ["AED", "MAD"],
+    riyal: ["SAR", "QAR", "OMR", "YER", "IRR"],
+    rial: ["SAR", "QAR", "OMR", "YER", "IRR"],
+    ريال: ["SAR", "QAR", "OMR", "YER", "IRR"],
+    dinar: ["KWD", "BHD", "JOD", "IQD", "LYD", "TND", "DZD", "RSD", "MKD"],
+    دينار: ["KWD", "BHD", "JOD", "IQD", "LYD", "TND", "DZD", "RSD", "MKD"],
+    franc: ["CHF", "XAF", "XOF", "XPF", "CDF", "BIF", "DJF", "GNF", "KMF", "RWF"],
+    peso: ["MXN", "ARS", "CLP", "COP", "CUP", "DOP", "PHP", "UYU"],
+    ringgit: ["MYR"],
+    rand: ["ZAR"],
+    shilling: ["KES", "UGX", "TZS", "SOS"],
+    taka: ["BDT"],
+};
+const UNITS = {
+    "mg/dl": "mg/dL",
+    "mmol/l": "mmol/L",
+    mcg: "mcg",
+    µg: "mcg",
+    mg: "mg",
+    ملغ: "mg",
+    مجم: "mg",
+    g: "g",
+    غرام: "g",
+    kg: "kg",
+    كغ: "kg",
+    كيلوغرام: "kg",
+    ml: "ml",
+    مل: "ml",
+    l: "l",
+    لتر: "l",
+    km: "km",
+    كم: "km",
+    cm: "cm",
+    mm: "mm",
+    m: "m",
+    متر: "m",
+    mi: "mi",
+    ft: "ft",
+    lb: "lb",
+    lbs: "lb",
+    oz: "oz",
+    "°c": "°C",
+    "°f": "°F",
+    kwh: "kWh",
+    mwh: "MWh",
+    kw: "kW",
+    mw: "MW",
+    iu: "IU",
+    hours: "hour",
+    hour: "hour",
+    hrs: "hour",
+    hr: "hour",
+    h: "hour",
+    ساعة: "hour",
+    ساعات: "hour",
+    minutes: "minute",
+    minute: "minute",
+    mins: "minute",
+    min: "minute",
+    دقيقة: "minute",
+    دقائق: "minute",
+    seconds: "second",
+    second: "second",
+    secs: "second",
+    days: "day",
+    day: "day",
+    يوم: "day",
+    أيام: "day",
+    weeks: "week",
+    week: "week",
+    أسبوع: "week",
+    أسابيع: "week",
+    months: "month",
+    month: "month",
+    شهر: "month",
+    أشهر: "month",
+    years: "year",
+    year: "year",
+    سنة: "year",
+    سنوات: "year",
+    units: "unit",
+    unit: "unit",
+    وحدة: "unit",
+    items: "item",
+    pieces: "piece",
+    tablets: "tablet",
+    حبة: "tablet",
+    doses: "dose",
+    جرعة: "dose",
+};
+const MONTHS = {
+    january: 1,
+    february: 2,
+    march: 3,
+    april: 4,
+    may: 5,
+    june: 6,
+    july: 7,
+    august: 8,
+    september: 9,
+    october: 10,
+    november: 11,
+    december: 12,
+    jan: 1,
+    feb: 2,
+    mar: 3,
+    apr: 4,
+    jun: 6,
+    jul: 7,
+    aug: 8,
+    sept: 9,
+    sep: 9,
+    oct: 10,
+    nov: 11,
+    dec: 12,
+    يناير: 1,
+    فبراير: 2,
+    مارس: 3,
+    أبريل: 4,
+    إبريل: 4,
+    ابريل: 4,
+    مايو: 5,
+    يونيو: 6,
+    يوليو: 7,
+    أغسطس: 8,
+    اغسطس: 8,
+    سبتمبر: 9,
+    أكتوبر: 10,
+    اكتوبر: 10,
+    نوفمبر: 11,
+    ديسمبر: 12,
+    "كانون الثاني": 1,
+    شباط: 2,
+    آذار: 3,
+    نيسان: 4,
+    أيار: 5,
+    حزيران: 6,
+    تموز: 7,
+    آب: 8,
+    أيلول: 9,
+    "تشرين الأول": 10,
+    "تشرين الثاني": 11,
+    "كانون الأول": 12,
+};
+/** spec/findings.md §9: the ISO codes a written currency may be (a symbol or a word names a
+ * family: "$" is any dollar). */
+export function currencyCodes(written) {
+    if (/^[A-Z]{3}$/.test(written))
+        return [written];
+    const w = written.toLowerCase();
+    return FAMILIES[w] ?? FAMILIES[w.replace(/s$/, "")] ?? [written];
+}
+/** spec/findings.md §9: a written unit's canonical unit. */
+export const unitOf = (written) => UNITS[written.toLowerCase()] ?? written;
+const MONTH = Object.keys(MONTHS)
+    .sort((a, b) => b.length - a.length)
+    .join("|");
+const DATE_DMY = new RegExp(`(?<![0-9])([0-9]{1,2})(?:st|nd|rd|th)?\\s+(${MONTH})\\.?,?\\s+([0-9]{4})(?![0-9])`, "gi");
+const DATE_MDY = new RegExp(`(?<![A-Za-z])(${MONTH})\\.?\\s+([0-9]{1,2})(?:st|nd|rd|th)?,?\\s+([0-9]{4})(?![0-9])`, "gi");
+/** Dates written in words (English or Arabic months), as ISO dates with their spans. */
+function wordDates(s) {
+    const out = [];
+    const add = (d, m, y, at, end) => {
+        const month = MONTHS[m.toLowerCase()];
+        const day = Number(d);
+        const date = new Date(Date.UTC(Number(y), (month ?? 0) - 1, day));
+        if (!month || date.getUTCDate() !== day || date.getUTCMonth() !== month - 1)
+            return;
+        if (out.some((o) => at < o.end && end > o.at))
+            return;
+        out.push({ iso: `${y}-${String(month).padStart(2, "0")}-${d.padStart(2, "0")}`, at, end });
+    };
+    for (const m of s.matchAll(DATE_DMY)) {
+        const at = m.index ?? 0;
+        add(m[1], m[2], m[3], at, at + m[0].length);
+    }
+    for (const m of s.matchAll(DATE_MDY)) {
+        const at = m.index ?? 0;
+        add(m[2], m[1], m[3], at, at + m[0].length);
+    }
+    return out.sort((a, b) => a.at - b.at);
+}
 /** A canonical decimal as an integer of millionths, exactly (sums without floats). */
 function micros(c) {
     const [w = "0", f = ""] = c.split(".");
@@ -58,12 +340,20 @@ export function factsIn(text) {
     }
     for (const m of s.matchAll(QUANTITY)) {
         const at = m.index ?? 0;
-        add({ kind: "quantity", value: canonicalNumber(m[1]), at, end: at + m[0].length });
+        add({
+            kind: "quantity",
+            value: canonicalNumber(m[1]),
+            at,
+            end: at + m[0].length,
+            unit: unitOf(m[2]),
+        });
     }
     for (const m of s.matchAll(ISO_DATE)) {
         const at = m.index ?? 0;
         add({ kind: "date", value: normaliseValue(m[0]), at, end: at + m[0].length });
     }
+    for (const d of wordDates(s))
+        add({ kind: "date", value: normaliseValue(d.iso), at: d.at, end: d.end });
     for (const x of identifierSpans(s, taken))
         out.push({ kind: x.kind, value: x.value, at: x.at, end: x.end });
     return out.sort((a, b) => a.at - b.at);
@@ -80,10 +370,32 @@ export class Evidence {
         this.raw = raw;
         this.pieces = (pieces ?? [{ seq: -1, text: raw }]).map((p) => {
             const s = westernText(p.text);
+            const tags = new Map();
+            let blank = s;
+            const tag = (value, t, at, end) => {
+                const set = tags.get(value) ?? new Set();
+                for (const x of t)
+                    set.add(x);
+                tags.set(value, set);
+                blank = blank.slice(0, at) + " ".repeat(end - at) + blank.slice(end);
+            };
+            for (const m of s.matchAll(MONEY)) {
+                const at = m.index ?? 0;
+                const codes = currencyCodes((m[1] ?? m[4])).map((c) => `cur:${c}`);
+                tag(canonicalNumber((m[2] ?? m[3])), codes, at, at + m[0].length);
+            }
+            for (const m of s.matchAll(QUANTITY)) {
+                const at = m.index ?? 0;
+                tag(canonicalNumber(m[1]), [`unit:${unitOf(m[2])}`], at, at + m[0].length);
+            }
+            const numbersIn = (t) => new Set([...t.matchAll(NUMBER)].map((m) => canonicalNumber(m[0])));
             return {
                 seq: p.seq,
-                text: normaliseValue(s),
-                numbers: new Set([...s.matchAll(NUMBER)].map((m) => canonicalNumber(m[0]))),
+                // dates in words count as their ISO form too
+                text: normaliseValue([s, ...wordDates(s).map((d) => d.iso)].join(" ")),
+                numbers: numbersIn(s),
+                bare: numbersIn(blank),
+                tags,
             };
         });
         this.numbers = new Set(this.pieces.flatMap((p) => [...p.numbers]));
@@ -95,7 +407,9 @@ export class Evidence {
     /**
      * The seqs of the lines that hold a fact, or null. Money, percentages and quantities: the same
      * number, the same in minor units, a percentage as a fraction, or (money) the sum of two of the
-     * evidence's numbers. Dates and identifiers: the normalised text.
+     * evidence's numbers. A number the evidence writes only with another currency or unit doesn't
+     * hold it (AED 500 isn't USD 500; 500 g isn't 500 mg); one it writes bare does. Dates and
+     * identifiers: the normalised text (a date in words as its ISO form).
      */
     support(f) {
         if (f.kind === "money" || f.kind === "percent" || f.kind === "quantity") {
@@ -104,7 +418,14 @@ export class Evidence {
                 shift(f.value, 2),
                 ...(f.kind === "percent" ? [shift(f.value, -2)] : []),
             ];
-            const hit = this.pieces.find((p) => wanted.some((w) => p.numbers.has(w)));
+            const mine = f.kind === "money" && f.currency
+                ? currencyCodes(f.currency).map((c) => `cur:${c}`)
+                : f.kind === "quantity" && f.unit
+                    ? [`unit:${f.unit}`]
+                    : null;
+            const fits = (p, w) => p.numbers.has(w) &&
+                (mine === null || p.bare.has(w) || mine.some((t) => p.tags.get(w)?.has(t) === true));
+            const hit = this.pieces.find((p) => wanted.some((w) => fits(p, w)));
             if (hit)
                 return [hit.seq];
             return f.kind === "money" ? (this.pairSums().get(f.value) ?? null) : null;

package/dist/cli.js

@@ -15,7 +15,7 @@ const USAGE = `usage (spec/cli.md):
   blackbox verify <bundle.json> [--proofs] [--bodies <dir>]
   blackbox export <session_id> --out <bundle.json> [--bodies <dir>]
   blackbox export-all --from <date> --to <date> --out <file.ndjson>
-  blackbox sessions [--limit N] [--label L] [--open | --closed] [--before <session_id>] [--from <date>] [--to <date>] [--json]
+  blackbox sessions [--limit N] [--label L] [--open | --closed] [--outcome success|failure|abandoned] [--before <session_id>] [--from <date>] [--to <date>] [--json]
   blackbox sessions <session_id> [--json]
   blackbox summary <session_id>
   blackbox incident <session_id> [--lang en|ar]
@@ -52,7 +52,8 @@ const USAGE = `usage (spec/cli.md):
   blackbox reconcile --harness claude-code|codex --bundle <bundle.json> --bodies <dir> [--agent-session <id>]... [--require-receipts] <path>
   blackbox reconcile-system --connector <connector.json> --log <export.csv|jsonl> [--pack <pack.json>] <session_id>
   blackbox workspace-receipt   (a Claude Code PreToolUse / PostToolUse hook; reads the hook JSON on stdin)
-  blackbox attest   (a Claude Code PostToolUse hook: spec/attestation.md §4)`;
+  blackbox attest   (a Claude Code PostToolUse hook: spec/attestation.md §4)
+  blackbox policy-hook   (a Claude Code / Codex PreToolUse hook: asks the gateway's policy; fails closed)`;
 async function main(argv) {
     const [command, ...rest] = argv;
     if (command === "mcp")
@@ -67,6 +68,8 @@ async function main(argv) {
         return receiptCommand();
     if (command === "attest")
         return attestCommand();
+    if (command === "policy-hook")
+        return policyHookCommand();
     if (command === "verify")
         return verifyCommand(rest);
     if (command === "export")
@@ -215,6 +218,69 @@ async function attestCommand() {
     }
     return 0;
 }
+/** spec/policy.md §2a: a PreToolUse hook. Deny: exit 2, the reason on stderr (the agent sees it).
+ * Ask: Claude Code's `permissionDecision: "ask"` on stdout. Allow: exit 0, nothing printed. Any
+ * failure denies, unless BLACKBOX_HOOK_FAIL_OPEN=1. */
+async function policyHookCommand() {
+    const refuse = (why) => {
+        if (process.env.BLACKBOX_HOOK_FAIL_OPEN === "1") {
+            process.stderr.write(`blackbox policy-hook: ${why}; allowed (BLACKBOX_HOOK_FAIL_OPEN=1)\n`);
+            return 0;
+        }
+        process.stderr.write(`blackbox policy-hook: ${why}; refused (fails closed)\n`);
+        return 2;
+    };
+    const url = process.env.BLACKBOX_URL;
+    const token = process.env.BLACKBOX_TOKEN;
+    const sessionId = process.env.BLACKBOX_SESSION_ID;
+    if (!url || !token || !sessionId)
+        return refuse("BLACKBOX_URL, BLACKBOX_TOKEN and BLACKBOX_SESSION_ID are needed");
+    let hook;
+    try {
+        const parts = [];
+        for await (const chunk of process.stdin)
+            parts.push(chunk);
+        hook = JSON.parse(Buffer.concat(parts).toString("utf8"));
+    }
+    catch {
+        return refuse("the hook input is not JSON");
+    }
+    if (typeof hook.tool_name !== "string")
+        return refuse("the hook input has no tool_name");
+    let answer;
+    try {
+        const res = await fetch(new URL(`/v1/sessions/${encodeURIComponent(sessionId)}/policy-check`, url), {
+            method: "POST",
+            headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+            body: JSON.stringify({ tool: hook.tool_name, args: hook.tool_input ?? {} }),
+            signal: AbortSignal.timeout(5_000),
+        });
+        if (!res.ok)
+            return refuse(`the gateway answered HTTP ${res.status}`);
+        answer = (await res.json());
+    }
+    catch (error) {
+        return refuse(`the gateway couldn't be asked (${error instanceof Error ? error.message : error})`);
+    }
+    const why = `${typeof answer.reason === "string" ? answer.reason : "the policy says so"} (rule ${String(answer.rule)})`;
+    if (answer.decision === "deny") {
+        process.stderr.write(`Blackbox policy refused ${hook.tool_name}: ${why}\n`);
+        return 2;
+    }
+    if (answer.decision === "ask") {
+        process.stdout.write(`${JSON.stringify({
+            hookSpecificOutput: {
+                hookEventName: "PreToolUse",
+                permissionDecision: "ask",
+                permissionDecisionReason: `Blackbox policy: ${why}`,
+            },
+        })}\n`);
+        return 0;
+    }
+    if (answer.decision === "allow")
+        return 0;
+    return refuse("the gateway's answer has no decision");
+}
 async function receiptCommand() {
     const url = process.env.BLACKBOX_URL;
     const token = process.env.BLACKBOX_TOKEN;
@@ -388,6 +454,8 @@ async function sessionsCommand(rest) {
         q.set("from", f.from);
     if (f.to !== undefined)
         q.set("to", f.to);
+    if (f.outcome !== undefined)
+        q.set("outcome", f.outcome);
     if (f.open === "1")
         q.set("status", "open");
     if (f.closed === "1")

package/dist/client/index.d.ts

@@ -102,6 +102,10 @@ export declare function client(options: ClientOptions): {
     emergency: (id: string, o?: {
         note?: string;
     }) => Promise<Json>;
+    /** Refuses the session's later calls that name this run (x-blackbox-run), spec/control.md §3a. */
+    cancelRun: (id: string, runId: string, o?: {
+        note?: string;
+    }) => Promise<Json>;
     /** Hands the controls over (spec/authority.md): `human` takes over; `agent`/`supervised` hand back. */
     authority: (id: string, to: "human" | "agent" | "supervised", o?: {
         reason?: string;
@@ -143,5 +147,13 @@ export declare function client(options: ClientOptions): {
         expires_in_days?: number;
     }) => Promise<Json>;
     revokeKey: (tenantId: string, keyId: string) => Promise<Json>;
+    /** Operator only: a tenant's own rules (spec/policy.md §7a). */
+    tenantPolicy: (tenantId: string) => Promise<Json>;
+    setTenantPolicy: (tenantId: string, rules: object[]) => Promise<Json>;
+    removeTenantPolicy: (tenantId: string) => Promise<Json>;
+    /** Operator only: a tenant's own provider keys, sealed, never shown (spec/tenancy.md §5a). */
+    providerKeys: (tenantId: string) => Promise<Json>;
+    setProviderKey: (tenantId: string, provider: string, apiKey: string) => Promise<Json>;
+    removeProviderKey: (tenantId: string, provider: string) => Promise<Json>;
 };
 export type Client = ReturnType<typeof client>;

package/dist/client/index.js

@@ -187,6 +187,8 @@ export function client(options) {
         pause: (id, o = {}) => json("POST", ses(id, "pause"), compact(o)),
         /** The emergency stop (squawk 7700, spec/control.md). */
         emergency: (id, o = {}) => json("POST", ses(id, "emergency"), compact(o)),
+        /** Refuses the session's later calls that name this run (x-blackbox-run), spec/control.md §3a. */
+        cancelRun: (id, runId, o = {}) => json("POST", ses(id, `runs/${encodeURIComponent(runId)}/cancel`), compact(o), true),
         /** Hands the controls over (spec/authority.md): `human` takes over; `agent`/`supervised` hand back. */
         authority: (id, to, o = {}) => json("POST", ses(id, "authority"), compact({ to, ...o })),
         /** The pending approvals (spec/approvals.md). */
@@ -205,6 +207,14 @@ export function client(options) {
         updateTenant: (tenantId, o) => json("PATCH", `/v1/tenants/${encodeURIComponent(tenantId)}`, compact(o)),
         createKey: (tenantId, o = {}) => json("POST", `/v1/tenants/${encodeURIComponent(tenantId)}/keys`, compact(o)),
         revokeKey: (tenantId, keyId) => json("POST", `/v1/tenants/${encodeURIComponent(tenantId)}/keys/${encodeURIComponent(keyId)}/revoke`, {}, true),
+        /** Operator only: a tenant's own rules (spec/policy.md §7a). */
+        tenantPolicy: (tenantId) => json("GET", `/v1/tenants/${encodeURIComponent(tenantId)}/policy`),
+        setTenantPolicy: (tenantId, rules) => json("PUT", `/v1/tenants/${encodeURIComponent(tenantId)}/policy`, { policy: { rules } }, true),
+        removeTenantPolicy: (tenantId) => json("DELETE", `/v1/tenants/${encodeURIComponent(tenantId)}/policy`, undefined, true),
+        /** Operator only: a tenant's own provider keys, sealed, never shown (spec/tenancy.md §5a). */
+        providerKeys: (tenantId) => json("GET", `/v1/tenants/${encodeURIComponent(tenantId)}/providers`),
+        setProviderKey: (tenantId, provider, apiKey) => json("PUT", `/v1/tenants/${encodeURIComponent(tenantId)}/providers/${encodeURIComponent(provider)}`, { api_key: apiKey }, true),
+        removeProviderKey: (tenantId, provider) => json("DELETE", `/v1/tenants/${encodeURIComponent(tenantId)}/providers/${encodeURIComponent(provider)}`, undefined, true),
     };
     return api;
 }

package/dist/policy/index.d.ts

@@ -59,6 +59,9 @@ interface Compiled {
     args: RegExp | null;
 }
 /** Parses a policy file; throws on anything invalid (the server refuses to start). */
+/** spec/policy.md §1 (L6.5.4): null when `args_match` uses only syntax JavaScript and Python
+ * share, else what doesn't (vectors: spec/vectors/policy-regex.json). */
+export declare function portableRegexError(p: string): string | null;
 export declare function loadPolicy(bytes: Uint8Array): Policy;
 export declare function compilePolicy(policy: Policy): Compiled[];
 /** spec/api.md: the session's environment, from its `session.open` (the first line). */

package/dist/policy/index.js

@@ -58,6 +58,52 @@ const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 /** A tool pattern: `*` is any run of characters, the rest is literal, anchored at both ends. */
 const glob = (pattern) => new RegExp(`^${pattern.split("*").map(escapeRe).join(".*")}$`);
 /** Parses a policy file; throws on anything invalid (the server refuses to start). */
+/** spec/policy.md §1 (L6.5.4): null when `args_match` uses only syntax JavaScript and Python
+ * share, else what doesn't (vectors: spec/vectors/policy-regex.json). */
+export function portableRegexError(p) {
+    const hex = (s) => /^[0-9A-Fa-f]+$/.test(s);
+    let inClass = false;
+    for (let i = 0; i < p.length; i++) {
+        const c = p[i];
+        if (c === "\\") {
+            const n = p[i + 1];
+            if (n === undefined)
+                return "a trailing \\";
+            if (n === "x" && !(p.length >= i + 4 && hex(p.slice(i + 2, i + 4))))
+                return "\\x needs 2 hex digits";
+            if (n === "u" && !(p.length >= i + 6 && hex(p.slice(i + 2, i + 6))))
+                return "\\u needs 4 hex digits";
+            if (/[A-Za-z]/.test(n) && !"dDwWsSbBnrtfvxu".includes(n))
+                return `\\${n}`;
+            i++;
+            continue;
+        }
+        if (inClass) {
+            if (c === "]")
+                inClass = false;
+            else if (c === "[" && p[i + 1] === ":")
+                return "[:";
+            continue;
+        }
+        if (c === "[") {
+            if (p[i + 1] === ":")
+                return "[:";
+            const first = p[i + 1] === "^" ? i + 2 : i + 1;
+            if (p[first] === "]")
+                return "an empty class";
+            inClass = true;
+            i = first - 1;
+            continue;
+        }
+        if (c === "(" && p[i + 1] === "?" && !":=!".includes(p[i + 2] ?? ""))
+            return "(? other than (?: (?= (?!";
+        if ("*+?}".includes(c) && p[i + 1] === "+" && !(c === "?" && "*+?}".includes(p[i - 1] ?? "")))
+            return "a possessive quantifier";
+        if (c === "{" && p[i + 1] === ",")
+            return "{,";
+    }
+    return null;
+}
 export function loadPolicy(bytes) {
     const doc = JSON.parse(new TextDecoder().decode(bytes));
     if (doc.version !== 1 || !Array.isArray(doc.rules))
@@ -77,6 +123,9 @@ export function loadPolicy(bytes) {
         if (r.args_match !== undefined) {
             if (typeof r.args_match !== "string" || r.args_match.length > 200)
                 throw new Error(`policy ${r.id}: args_match must be a regular expression of ≤ 200 characters`);
+            const unportable = portableRegexError(r.args_match);
+            if (unportable)
+                throw new Error(`policy ${r.id}: args_match uses syntax JavaScript and Python don't share (${unportable})`);
             new RegExp(r.args_match); // throws on bad syntax
         }
         if (r.audit !== undefined && typeof r.audit !== "boolean")

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.9.0";
+export declare const VERSION = "0.11.0";

package/dist/version.js

@@ -1,2 +1,2 @@
 // The SDK version, on its own so the CLI can print it without loading the whole SDK.
-export const VERSION = "0.9.0";
+export const VERSION = "0.11.0";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zanii/blackbox",
   "license": "Apache-2.0",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "The flight recorder for AI agents: sessions, a zero-loss spool, framework hooks, approvals, and offline verification of the gateway's hash-chained record.",
   "keywords": [
     "ai-agents",