@zanii/blackbox 0.0.0-stage → 0.2.0

package/dist/analysis/memory.js

@@ -0,0 +1,33 @@
+// The Memory X-ray (spec/agents.md §2). Mirrors analysis/memory.py.
+/** spec/agents.md §2, over parsed events (sdk.event bodies attached). */
+export function memoryXrayOf(events, revokedElsewhere = []) {
+    const revoked = new Set(revokedElsewhere);
+    const stale = [];
+    let writes = 0;
+    let reads = 0;
+    for (const e of events) {
+        if (e.kind !== "sdk.event")
+            continue;
+        const d = e.data ?? {};
+        if (e.meta.type === "memory.write")
+            writes++;
+        else if (e.meta.type === "memory.revoke" && typeof d.memory_id === "string")
+            revoked.add(d.memory_id);
+        else if (e.meta.type === "memory.read") {
+            reads++;
+            for (const id of Array.isArray(d.memory_ids) ? d.memory_ids : [])
+                if (typeof id === "string" && revoked.has(id))
+                    stale.push({ seq: e.seq, memory_id: id });
+        }
+    }
+    return { writes, reads, revoked: [...revoked].sort(), stale_reads: stale };
+}
+/** The findings part (this record's own revocations only). */
+export function memoryFindings(events) {
+    return memoryXrayOf(events).stale_reads.map((r) => ({
+        code: "REVOKED_MEMORY_READ",
+        source: "memory",
+        severity: "warning",
+        ref: { seq: r.seq, memory_id: r.memory_id },
+    }));
+}

package/dist/analysis/waste.d.ts

@@ -0,0 +1,29 @@
+import { type LoadedPrices } from "../cost/index.ts";
+import { type Bodies } from "../reconcile/record.ts";
+export type WasteReason = "repeat" | "failed" | "outcome";
+export type Outcome = "success" | "failure" | "abandoned";
+export interface WasteReport {
+    v: 1;
+    outcome: Outcome | null;
+    total_micro_usd: number;
+    wasted_micro_usd: number;
+    wasted_aed_fils: number;
+    by_reason: Record<WasteReason, number>;
+    calls: Array<{
+        seq: number;
+        reason: WasteReason;
+        micro_usd: number;
+    }>;
+}
+export declare const OUTCOMES: readonly Outcome[];
+export declare function waste(lines: readonly string[], bodies: Bodies, prices: LoadedPrices): WasteReport;
+export interface OutcomeRollup {
+    sessions: number;
+    outcomes: Record<Outcome | "unlabelled", number>;
+    total_micro_usd: number;
+    wasted_micro_usd: number;
+    /** All the labelled sessions' cost over their successes (J5); null with no success. */
+    cost_per_success_micro_usd: number | null;
+}
+/** Rolls session waste reports up (spec/cost.md §5). Integer micro-USD, rounded half up. */
+export declare function rollup(reports: readonly WasteReport[]): OutcomeRollup;

package/dist/analysis/waste.js

@@ -0,0 +1,79 @@
+// The waste ledger (spec/cost.md §5): which paid model calls were wasted, and why.
+// Mirrors analysis/waste.py.
+import { sessionCost, toAedFils } from "../cost/index.js";
+import { callsOf } from "../reconcile/record.js";
+import { toolCallsOf } from "./detectors.js";
+export const OUTCOMES = ["success", "failure", "abandoned"];
+export function waste(lines, bodies, prices) {
+    const cost = sessionCost(lines, prices);
+    const status = new Map();
+    let outcome = null;
+    for (const line of lines) {
+        const e = JSON.parse(line);
+        if (e.kind === "llm.response" && typeof e.meta.status === "number")
+            status.set(e.seq, e.meta.status);
+        else if (e.kind === "llm.incomplete")
+            status.set(e.seq, "incomplete");
+        else if (e.kind === "outcome" && OUTCOMES.includes(e.meta.outcome))
+            outcome = e.meta.outcome; // the last one wins
+    }
+    // A response whose tool calls all repeat an identical earlier call (same tool + fingerprint).
+    const seen = new Set();
+    const byResponse = new Map();
+    for (const t of toolCallsOf(callsOf(lines, bodies))) {
+        const key = `${t.tool}\n${t.fp}`;
+        byResponse.set(t.seq, [...(byResponse.get(t.seq) ?? []), seen.has(key)]);
+        seen.add(key);
+    }
+    const by_reason = { repeat: 0, failed: 0, outcome: 0 };
+    const calls = [];
+    for (const c of cost.calls) {
+        if (!c.micro_usd)
+            continue;
+        const s = status.get(c.seq);
+        const repeats = byResponse.get(c.seq);
+        const reason = s === "incomplete" || (typeof s === "number" && s >= 400)
+            ? "failed"
+            : repeats?.every(Boolean)
+                ? "repeat"
+                : outcome === "failure" || outcome === "abandoned"
+                    ? "outcome"
+                    : null;
+        if (!reason)
+            continue;
+        by_reason[reason] += c.micro_usd;
+        calls.push({ seq: c.seq, reason, micro_usd: c.micro_usd });
+    }
+    const wasted = by_reason.repeat + by_reason.failed + by_reason.outcome;
+    return {
+        v: 1,
+        outcome,
+        total_micro_usd: cost.total_micro_usd,
+        wasted_micro_usd: wasted,
+        wasted_aed_fils: toAedFils(wasted),
+        by_reason,
+        calls,
+    };
+}
+/** Rolls session waste reports up (spec/cost.md §5). Integer micro-USD, rounded half up. */
+export function rollup(reports) {
+    const outcomes = { success: 0, failure: 0, abandoned: 0, unlabelled: 0 };
+    let total = 0;
+    let wasted = 0;
+    let labelledCost = 0;
+    for (const r of reports) {
+        outcomes[r.outcome ?? "unlabelled"]++;
+        total += r.total_micro_usd;
+        wasted += r.wasted_micro_usd;
+        if (r.outcome)
+            labelledCost += r.total_micro_usd;
+    }
+    const n = outcomes.success;
+    return {
+        sessions: reports.length,
+        outcomes,
+        total_micro_usd: total,
+        wasted_micro_usd: wasted,
+        cost_per_success_micro_usd: n ? Math.floor((labelledCost + Math.floor(n / 2)) / n) : null,
+    };
+}

package/dist/approvals/index.d.ts

@@ -0,0 +1,11 @@
+export interface ApprovalFinding {
+    code: "APPROVAL_REJECTED" | "APPROVAL_TIMEOUT";
+    source: "approval";
+    severity: "advisory" | "warning";
+    ref: {
+        seq: number;
+        approval_id: string;
+    };
+}
+/** spec/approvals.md §3: a refused action (advisory), and one nobody confirmed in time (warning). */
+export declare function approvalFindings(lines: readonly string[]): ApprovalFinding[];

package/dist/approvals/index.js

@@ -0,0 +1,27 @@
+// The two-person rule (spec/approvals.md): what the approval decisions say. Pure; mirrors
+// sdks/python/src/zanii_blackbox/approvals.py; pinned by spec/vectors/approvals.json.
+/** spec/approvals.md §3: a refused action (advisory), and one nobody confirmed in time (warning). */
+export function approvalFindings(lines) {
+    const out = [];
+    for (const line of lines) {
+        const e = JSON.parse(line);
+        if (e.kind !== "control" || e.meta.action !== "approval")
+            continue;
+        const id = typeof e.meta.approval_id === "string" ? e.meta.approval_id : "";
+        if (e.meta.decision === "reject")
+            out.push({
+                code: "APPROVAL_REJECTED",
+                source: "approval",
+                severity: "advisory",
+                ref: { seq: e.seq, approval_id: id },
+            });
+        else if (e.meta.decision === "timeout")
+            out.push({
+                code: "APPROVAL_TIMEOUT",
+                source: "approval",
+                severity: "warning",
+                ref: { seq: e.seq, approval_id: id },
+            });
+    }
+    return out;
+}

package/dist/approvals/warnings.d.ts

@@ -0,0 +1,2 @@
+/** What might mislead a person about this text; empty when nothing does. */
+export declare function textWarnings(text: string): string[];

package/dist/approvals/warnings.js

@@ -0,0 +1,28 @@
+// Warnings for approval screens (spec/approvals.md §6, idea S5): text a person is asked to
+// approve that may not say what it looks like it says. Mirrors approvals/warnings.py.
+const BIDI = /[\u202A-\u202E\u2066-\u2069]/u;
+const ZERO_WIDTH = /[\u200B-\u200D\u2060\uFEFF]/u;
+const URL_RE = /\bhttps?:\/\/([^\s/?#]+)/giu;
+/** What might mislead a person about this text; empty when nothing does. */
+export function textWarnings(text) {
+    const out = [];
+    if (BIDI.test(text))
+        out.push("bidi_control");
+    if (ZERO_WIDTH.test(text))
+        out.push("zero_width");
+    // A word that mixes Latin with Cyrillic or Greek letters: a look-alike (раypal).
+    for (const word of text.split(/[^\p{L}]+/u))
+        if (/\p{Script=Latin}/u.test(word) && /[\p{Script=Cyrillic}\p{Script=Greek}]/u.test(word)) {
+            out.push("mixed_script");
+            break;
+        }
+    const hosts = [...text.matchAll(URL_RE)].map((m) => (m[1] ?? "").toLowerCase());
+    if (hosts.some((h) => h.includes("@")))
+        out.push("url_userinfo");
+    const bare = hosts.map((h) => h.slice(h.lastIndexOf("@") + 1).replace(/:\d+$/, ""));
+    if (bare.some((h) => h.split(".").some((label) => label.startsWith("xn--"))))
+        out.push("url_punycode");
+    if (bare.some((h) => /^\d{1,3}(\.\d{1,3}){3}$/.test(h) || h.startsWith("[")))
+        out.push("url_ip");
+    return out;
+}

package/dist/attest/index.d.ts

@@ -0,0 +1,17 @@
+/** A plain command's argv, or null (spec/attestation.md §1). */
+export declare function parseCommand(text: string): string[] | null;
+export declare function isReadOnly(argv: readonly string[]): boolean;
+/** `\r\n` → `\n`; trailing spaces, tabs and line breaks removed (spec/attestation.md §2). */
+export declare const normalise: (s: string) => string;
+export interface Attestation {
+    command: string[];
+    claimed_sha256: string;
+    observed_sha256: string | null;
+    match: boolean;
+    exit_code: number | null;
+    /** The exit code the tool result reported, when it did (L7.3.6): then it must match too. */
+    claimed_exit_code?: number;
+    error?: string;
+}
+/** Re-runs a read-only argv and compares (call isReadOnly first; this refuses anything else). */
+export declare function attest(argv: readonly string[], claimed: string, cwd?: string, claimedExit?: number): Attestation;

package/dist/attest/index.js

@@ -0,0 +1,106 @@
+// Tool-output attestation (spec/attestation.md): re-run a read-only command, no shell, and compare
+// hashes with the output the model was given. Mirrors sdks/python/src/zanii_blackbox/attest.py.
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+const SPECIAL = /[|&;<>()$`\\"'*?[\]{}~!#\n\r]/;
+/** A plain command's argv, or null (spec/attestation.md §1). */
+export function parseCommand(text) {
+    if (text.length === 0 || text.length > 1000 || SPECIAL.test(text))
+        return null;
+    const argv = text.split(/[ \t]+/).filter((a) => a.length > 0);
+    return argv.length ? argv : null;
+}
+const ANY_ARGS = new Set([
+    "cat",
+    "head",
+    "tail",
+    "wc",
+    "ls",
+    "pwd",
+    "grep",
+    "rg",
+    "stat",
+    "du",
+    "file",
+    "sha256sum",
+    "md5sum",
+]);
+const GIT = new Set([
+    "status",
+    "log",
+    "diff",
+    "show",
+    "rev-parse",
+    "ls-files",
+    "blame",
+    "branch",
+    "remote",
+    "describe",
+    "cat-file",
+]);
+const LISTING = /^(-v|--list|-a|-r)/;
+const programOf = (a) => (a.split(/[\\/]/).pop() ?? a).toLowerCase().replace(/\.exe$/, "");
+export function isReadOnly(argv) {
+    const [first, ...args] = argv;
+    if (first === undefined)
+        return false;
+    const program = programOf(first);
+    const git = program === "git";
+    if (!ANY_ARGS.has(program) && !git)
+        return false;
+    if (args.some((a) => a.startsWith("--output") ||
+        a.startsWith("--exec") ||
+        a.startsWith("--ext-diff") ||
+        (git && a.startsWith("-o"))))
+        return false;
+    if (!git)
+        return true;
+    const [sub, ...rest] = args;
+    if (sub === undefined || !GIT.has(sub))
+        return false;
+    if (sub === "branch" || sub === "remote")
+        return rest.every((a) => LISTING.test(a));
+    return true;
+}
+/** `\r\n` → `\n`; trailing spaces, tabs and line breaks removed (spec/attestation.md §2). */
+export const normalise = (s) => s.replace(/\r\n/g, "\n").replace(/[ \t\n\r\f\v]+$/, "");
+const sha = (s) => `sha256:${createHash("sha256").update(normalise(s), "utf8").digest("hex")}`;
+/** Re-runs a read-only argv and compares (call isReadOnly first; this refuses anything else). */
+export function attest(argv, claimed, cwd, claimedExit) {
+    const base = {
+        command: [...argv],
+        claimed_sha256: sha(claimed),
+        ...(claimedExit === undefined ? {} : { claimed_exit_code: claimedExit }),
+    };
+    if (!isReadOnly(argv))
+        return {
+            ...base,
+            observed_sha256: null,
+            match: false,
+            exit_code: null,
+            error: "not read-only",
+        };
+    const r = spawnSync(argv[0], argv.slice(1), {
+        cwd,
+        shell: false,
+        timeout: 10_000,
+        maxBuffer: 10 * 1024 * 1024,
+        encoding: "utf8",
+        windowsHide: true,
+    });
+    if (r.error || r.status === null)
+        return {
+            ...base,
+            observed_sha256: null,
+            match: false,
+            exit_code: null,
+            error: r.error ? r.error.message : "killed",
+        };
+    const observed = sha(r.stdout);
+    return {
+        ...base,
+        observed_sha256: observed,
+        match: observed === base.claimed_sha256 && (claimedExit === undefined || claimedExit === r.status),
+        exit_code: r.status,
+    };
+}

package/dist/authority/index.d.ts

@@ -0,0 +1,24 @@
+export type Mode = "agent" | "supervised" | "human";
+export interface Span {
+    mode: Mode;
+    from_seq: number;
+    /** The seq before the next change; null for the span still in force. */
+    to_seq: number | null;
+    by: string;
+    reason: string | null;
+}
+export interface AuthorityFinding {
+    code: "AUTOMATION_SURPRISE";
+    source: "authority";
+    severity: "warning";
+    ref: {
+        seq: number;
+        authority_seq: number;
+    };
+}
+/** spec/authority.md §3: who was flying, span by span, oldest first. */
+export declare function authorityTimeline(lines: readonly string[]): Span[];
+/** The span that covers `seq`, or null before the session opened. */
+export declare function authorityAt(lines: readonly string[], seq: number): Span | null;
+/** spec/authority.md §4: the agent acted in a `human` span before it knew the mode had changed. */
+export declare function automationSurprise(lines: readonly string[]): AuthorityFinding[];

package/dist/authority/index.js

@@ -0,0 +1,77 @@
+// Who had the controls (spec/authority.md): the authority timeline, and automation surprise.
+// Pure; mirrors sdks/python/src/zanii_blackbox/authority.py; pinned by spec/vectors/authority.json.
+const MODES = new Set(["agent", "supervised", "human"]);
+const ADMIN_BLOCKS = new Set(["EMERGENCY", "TAKEOVER"]);
+/** The mode an event sets, or null for one that doesn't change who is flying (spec §2). */
+function change(e) {
+    const m = e.meta;
+    if (e.kind === "session.open") {
+        const mode = typeof m.authority === "string" && MODES.has(m.authority) ? m.authority : "agent";
+        return { mode: mode, by: "open", reason: null };
+    }
+    if (e.kind !== "control")
+        return null;
+    if (m.action === "block") {
+        const code = String(m.code);
+        return { mode: "human", by: ADMIN_BLOCKS.has(code) ? "admin" : "gateway", reason: code };
+    }
+    if (m.action === "resume")
+        return { mode: "agent", by: typeof m.by === "string" ? m.by : "admin", reason: "resume" };
+    if (m.action === "authority" && typeof m.to === "string" && MODES.has(m.to))
+        return {
+            mode: m.to,
+            by: typeof m.by === "string" ? m.by : "admin",
+            reason: typeof m.reason === "string" ? m.reason : null,
+        };
+    return null;
+}
+/** spec/authority.md §3: who was flying, span by span, oldest first. */
+export function authorityTimeline(lines) {
+    const spans = [];
+    for (const line of lines) {
+        const e = JSON.parse(line);
+        const c = change(e);
+        const current = spans.at(-1);
+        if (!c || current?.mode === c.mode)
+            continue;
+        if (current)
+            current.to_seq = e.seq - 1;
+        spans.push({ mode: c.mode, from_seq: e.seq, to_seq: null, by: c.by, reason: c.reason });
+    }
+    return spans;
+}
+/** The span that covers `seq`, or null before the session opened. */
+export function authorityAt(lines, seq) {
+    for (const s of authorityTimeline(lines))
+        if (seq >= s.from_seq && (s.to_seq === null || seq <= s.to_seq))
+            return s;
+    return null;
+}
+/** spec/authority.md §4: the agent acted in a `human` span before it knew the mode had changed. */
+export function automationSurprise(lines) {
+    const events = lines.map((l) => JSON.parse(l));
+    const out = [];
+    for (const span of authorityTimeline(lines)) {
+        if (span.mode !== "human")
+            continue;
+        for (const e of events) {
+            if (e.seq <= span.from_seq || (span.to_seq !== null && e.seq > span.to_seq))
+                continue;
+            if (e.kind === "control" && e.meta.action === "ack")
+                break; // it knew
+            const acted = (e.kind === "control" && e.meta.action === "refused") ||
+                (e.kind === "sdk.event" && e.meta.type === "tool.call") ||
+                e.kind === "tool.call";
+            if (acted) {
+                out.push({
+                    code: "AUTOMATION_SURPRISE",
+                    source: "authority",
+                    severity: "warning",
+                    ref: { seq: e.seq, authority_seq: span.from_seq },
+                });
+                break;
+            }
+        }
+    }
+    return out;
+}

package/dist/billing/index.d.ts

@@ -0,0 +1,99 @@
+export interface Plan {
+    name: string;
+    monthly_fils: number;
+    /** Event metering: both or neither. */
+    included_events?: number;
+    per_1000_events_fils?: number;
+    /** Session metering (spec/billing.md §1): both or neither. */
+    included_sessions?: number;
+    per_session_fils?: number;
+}
+export interface InvoiceLine {
+    description: string;
+    quantity: number;
+    unit_fils: number;
+    amount_fils: number;
+}
+export interface Invoice {
+    lines: InvoiceLine[];
+    subtotal_fils: number;
+    vat_percent: number;
+    vat_fils: number;
+    total_fils: number;
+}
+export declare function invoice(plan: Plan, usage: {
+    events: number;
+    sessions?: number;
+}, vatPercent?: number): Invoice;
+export interface Plans {
+    version: string;
+    plans: Record<string, Plan>;
+}
+/** Parses a plans file (spec/billing.md §1); throws on anything that isn't integer fils. */
+export declare function loadPlans(bytes: Uint8Array): Plans;
+export interface TaxInvoiceInput {
+    number: string;
+    issued_at: string;
+    month: string;
+    supplier: {
+        name: string;
+        address: string;
+        trn: string;
+    };
+    customer: {
+        legal_name: string;
+        address: string;
+        trn?: string | null;
+    };
+    plan_id: string;
+    plans_version: string;
+    plan: Plan;
+    usage: {
+        events: number;
+        sessions: number;
+    };
+    vat_percent?: number;
+}
+/** spec/billing.md §5: the tax invoice document. */
+export declare function taxInvoice(input: TaxInvoiceInput): {
+    lines: InvoiceLine[];
+    subtotal_fils: number;
+    vat_percent: number;
+    vat_fils: number;
+    total_fils: number;
+    v: 1;
+    title: "Tax Invoice";
+    number: string;
+    issued_at: string;
+    period: {
+        from: string;
+        to: string;
+    };
+    date_of_supply: string;
+    supplier: {
+        name: string;
+        address: string;
+        trn: string;
+    };
+    customer: {
+        legal_name: string;
+        address: string;
+        trn: string | null;
+    };
+    currency: "AED";
+    plan: {
+        id: string;
+        name: string;
+        version: string;
+    };
+    usage: {
+        events: number;
+        sessions: number;
+    };
+    total_aed: string;
+};
+export type TaxInvoice = ReturnType<typeof taxInvoice>;
+/** spec/billing.md §5: the printable copy. */
+export declare function renderTaxInvoice(d: TaxInvoice): 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;