@zanii/blackbox 0.10.0 → 0.12.0

package/README.md

@@ -83,6 +83,16 @@ 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.12.0
+
+- Tax credit notes: `taxCreditNote` / `renderTaxCreditNote`, the document and printable copy behind gateway v0.14's `POST /v1/invoices/:number/credit-notes`.
+
+## 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`).

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/billing/index.d.ts

@@ -95,5 +95,51 @@ export declare function taxInvoice(input: TaxInvoiceInput): {
 export type TaxInvoice = ReturnType<typeof taxInvoice>;
 /** spec/billing.md §5: the printable copy. */
 export declare function renderTaxInvoice(d: TaxInvoice): string;
+export interface TaxCreditNoteInput {
+    number: string;
+    issued_at: string;
+    /** The invoice it corrects, as issued. */
+    invoice: TaxInvoice;
+    reason: string;
+    /** What this note credits, before VAT. */
+    subtotal_fils: number;
+    /** What earlier notes on the invoice credited already. */
+    credited?: {
+        subtotal_fils: number;
+        vat_fils: number;
+    };
+}
+/** spec/billing.md §5a: a tax credit note. The note that credits what's left of the invoice takes
+ * the rest of its VAT exactly, so the notes never credit more VAT than was invoiced. */
+export declare function taxCreditNote(input: TaxCreditNoteInput): {
+    v: 1;
+    title: "Tax Credit Note";
+    number: string;
+    issued_at: string;
+    invoice: {
+        number: string;
+        issued_at: string;
+    };
+    reason: string;
+    supplier: {
+        name: string;
+        address: string;
+        trn: string;
+    };
+    customer: {
+        legal_name: string;
+        address: string;
+        trn: string | null;
+    };
+    currency: "AED";
+    subtotal_fils: number;
+    vat_percent: number;
+    vat_fils: number;
+    total_fils: number;
+    total_aed: string;
+};
+export type TaxCreditNote = ReturnType<typeof taxCreditNote>;
+/** spec/billing.md §5a: the printable copy. */
+export declare function renderTaxCreditNote(d: TaxCreditNote): string;
 /** spec/billing.md §6: a `Stripe-Signature` header checked against the raw body. */
 export declare function stripeSignatureOk(header: string, rawBody: Uint8Array, secret: string, nowSeconds: number, toleranceSeconds?: number): boolean;

package/dist/billing/index.js

@@ -151,6 +151,64 @@ export function renderTaxInvoice(d) {
     ];
     return out.join("\n");
 }
+/** spec/billing.md §5a: a tax credit note. The note that credits what's left of the invoice takes
+ * the rest of its VAT exactly, so the notes never credit more VAT than was invoiced. */
+export function taxCreditNote(input) {
+    const inv = input.invoice;
+    const before = input.credited ?? { subtotal_fils: 0, vat_fils: 0 };
+    const last = input.subtotal_fils === inv.subtotal_fils - before.subtotal_fils;
+    const vat = last
+        ? inv.vat_fils - before.vat_fils
+        : Math.floor((input.subtotal_fils * inv.vat_percent + 50) / 100);
+    return {
+        v: 1,
+        title: "Tax Credit Note",
+        number: input.number,
+        issued_at: input.issued_at,
+        invoice: { number: inv.number, issued_at: inv.issued_at },
+        reason: input.reason,
+        supplier: inv.supplier,
+        customer: inv.customer,
+        currency: "AED",
+        subtotal_fils: input.subtotal_fils,
+        vat_percent: inv.vat_percent,
+        vat_fils: vat,
+        total_fils: input.subtotal_fils + vat,
+        total_aed: formatAed(input.subtotal_fils + vat),
+    };
+}
+/** spec/billing.md §5a: the printable copy. */
+export function renderTaxCreditNote(d) {
+    return [
+        "# Tax Credit Note",
+        "",
+        "| Field | Value |",
+        "|---|---|",
+        `| Credit note number | ${cell(d.number)} |`,
+        `| Date of issue | ${d.issued_at} |`,
+        `| Corrects invoice | ${cell(d.invoice.number)} of ${d.invoice.issued_at} |`,
+        `| Reason | ${cell(oneLine(d.reason))} |`,
+        "",
+        "## Supplier",
+        "",
+        `${oneLine(d.supplier.name)}  `,
+        `${oneLine(d.supplier.address)}  `,
+        `TRN: ${d.supplier.trn}`,
+        "",
+        "## Customer",
+        "",
+        `${oneLine(d.customer.legal_name)}  `,
+        `${oneLine(d.customer.address)}  `,
+        `TRN: ${d.customer.trn ?? "not registered"}`,
+        "",
+        "| Credited | AED |",
+        "|---|---:|",
+        `| Subtotal | ${aed(d.subtotal_fils)} |`,
+        `| VAT ${d.vat_percent}% | ${aed(d.vat_fils)} |`,
+        `| **Total credited** | **${aed(d.total_fils)}** |`,
+        "",
+    ].join("\n");
+}
 // ---------------------------------------------------------------- Stripe webhook signature (§6)
 /** spec/billing.md §6: a `Stripe-Signature` header checked against the raw body. */
 export function stripeSignatureOk(header, rawBody, secret, nowSeconds, toleranceSeconds = 300) {

package/dist/cli.js

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

package/dist/index.d.ts

@@ -11,7 +11,7 @@ export { archiveParquet } from "./archive/parquet.ts";
 export { type Attestation, attest, isReadOnly, normalise, parseCommand } from "./attest/index.ts";
 export { type AuthorityFinding, authorityAt, authorityTimeline, automationSurprise, type Mode as AuthorityMode, type Span as AuthoritySpan, } from "./authority/index.ts";
 export { badgeSvg, RECORD_STATES, type RecordState, recordBadge, recordState, } from "./badge/index.ts";
-export { type Invoice, type InvoiceLine, invoice, loadPlans, type Plan, type Plans, renderTaxInvoice, stripeSignatureOk, type TaxInvoice, type TaxInvoiceInput, taxInvoice, } from "./billing/index.ts";
+export { type Invoice, type InvoiceLine, invoice, loadPlans, type Plan, type Plans, renderTaxCreditNote, renderTaxInvoice, stripeSignatureOk, type TaxCreditNote, type TaxCreditNoteInput, type TaxInvoice, type TaxInvoiceInput, taxCreditNote, taxInvoice, } from "./billing/index.ts";
 export { type AgentIdentity, checkAgent, sessionBom } from "./bom/index.ts";
 export { BlackboxApiError, type Client, type ClientOptions, client, type SessionQuery, } from "./client/index.ts";
 export { ART12_MIN_RETENTION_DAYS, type Art12Check, type Art12Report, art12Check, } from "./compliance/art12.ts";

package/dist/index.js

@@ -13,7 +13,7 @@ export { archiveParquet } from "./archive/parquet.js";
 export { attest, isReadOnly, normalise, parseCommand } from "./attest/index.js";
 export { authorityAt, authorityTimeline, automationSurprise, } from "./authority/index.js";
 export { badgeSvg, RECORD_STATES, recordBadge, recordState, } from "./badge/index.js";
-export { invoice, loadPlans, renderTaxInvoice, stripeSignatureOk, taxInvoice, } from "./billing/index.js";
+export { invoice, loadPlans, renderTaxCreditNote, renderTaxInvoice, stripeSignatureOk, taxCreditNote, taxInvoice, } from "./billing/index.js";
 export { checkAgent, sessionBom } from "./bom/index.js";
 export { BlackboxApiError, client, } from "./client/index.js";
 export { ART12_MIN_RETENTION_DAYS, art12Check, } from "./compliance/art12.js";

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.10.0";
+export declare const VERSION = "0.12.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.10.0";
+export const VERSION = "0.12.0";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zanii/blackbox",
   "license": "Apache-2.0",
-  "version": "0.10.0",
+  "version": "0.12.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",