@zanii/blackbox 0.0.0-stage → 0.2.0

package/dist/weather/index.js

@@ -0,0 +1,45 @@
+// Weather (spec/weather.md): how each provider and model is doing, from the gateway's own calls.
+// Pure; mirrors sdks/python/src/zanii_blackbox/weather.py; pinned by spec/vectors/weather.json.
+const MIN5 = 5 * 60_000;
+const MIN15 = 15 * 60_000;
+function windowOf(samples) {
+    const calls = samples.length;
+    const errors = samples.filter((s) => !s.ok).length;
+    const ms = samples.map((s) => s.ms).sort((a, b) => a - b);
+    return {
+        calls,
+        errors,
+        error_ppm: calls ? Math.floor((errors * 1_000_000) / calls) : 0,
+        // nearest rank, in integers: ceil(0.95 × calls) without floating-point drift
+        p95_ms: calls ? ms[Math.floor((95 * calls + 99) / 100) - 1] : 0,
+    };
+}
+/** spec/weather.md §2. */
+export function weather(samples, nowMs, { slowMs = 30_000 } = {}) {
+    const groups = new Map();
+    for (const s of samples) {
+        if (nowMs - s.at_ms > MIN15 || s.at_ms > nowMs)
+            continue;
+        const key = JSON.stringify([s.provider, s.model]);
+        const list = groups.get(key);
+        if (list)
+            list.push(s);
+        else
+            groups.set(key, [s]);
+    }
+    const out = [];
+    for (const [key, list] of groups) {
+        const [provider, model] = JSON.parse(key);
+        const last5 = windowOf(list.filter((s) => nowMs - s.at_ms <= MIN5));
+        const status = last5.calls < 3
+            ? "clear"
+            : last5.error_ppm >= 500_000
+                ? "down"
+                : last5.error_ppm >= 100_000 || last5.p95_ms >= slowMs
+                    ? "degraded"
+                    : "clear";
+        out.push({ provider, model, last_5m: last5, last_15m: windowOf(list), status });
+    }
+    const cmp = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+    return out.sort((a, b) => cmp(a.provider, b.provider) || cmp(a.model ?? "", b.model ?? ""));
+}

package/dist/workspace-receipt/index.d.ts

@@ -0,0 +1,15 @@
+export type Tree = {
+    tree: string;
+} | {
+    reason: "not_a_git_repo" | "git_unavailable" | "git_failed";
+};
+/**
+ * The workspace's content as one git tree hash: tracked and untracked files (minus .gitignore'd
+ * ones), built in a temporary index so the user's staging area is never touched.
+ * ponytail: `git add -A` hashes every changed file, so a huge dirty tree costs seconds per tool call.
+ */
+export declare function workspaceTree(cwd: string): Tree;
+/** The hook's JSON input (from Claude Code on stdin) → the receipt posted to the gateway. */
+export declare function receiptFor(hook: Record<string, unknown>, tree: Tree): Record<string, unknown> | null;
+/** Posts one receipt. Resolves with null on 204, else the reason; never rejects. */
+export declare function postReceipt(gatewayUrl: string, token: string, receipt: Record<string, unknown>): Promise<string | null>;

package/dist/workspace-receipt/index.js

@@ -0,0 +1,121 @@
+// Workspace receipts (T1.3, spec/reconcile.md §7): a Claude Code PreToolUse / PostToolUse hook that
+// records the git tree hash of the workspace before and after every tool call.
+// Mirrors sdks/python/src/zanii_blackbox/workspace_receipt.py.
+import { spawnSync } from "node:child_process";
+import { copyFileSync, existsSync, mkdirSync, mkdtempSync, rmSync } from "node:fs";
+import { request as httpRequest } from "node:http";
+import { request as httpsRequest } from "node:https";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+const GIT_TIMEOUT_MS = 10_000;
+const HTTP_TIMEOUT_MS = 5_000;
+/**
+ * The workspace's content as one git tree hash: tracked and untracked files (minus .gitignore'd
+ * ones), built in a temporary index so the user's staging area is never touched.
+ * ponytail: `git add -A` hashes every changed file, so a huge dirty tree costs seconds per tool call.
+ */
+export function workspaceTree(cwd) {
+    const git = (args, env = process.env) => spawnSync("git", args, {
+        cwd,
+        env,
+        encoding: "utf8",
+        timeout: GIT_TIMEOUT_MS,
+        windowsHide: true,
+    });
+    const top = git(["rev-parse", "--show-toplevel", "--absolute-git-dir", "--git-path", "objects"]);
+    if (top.error)
+        return { reason: "git_unavailable" };
+    if (top.status !== 0)
+        return { reason: "not_a_git_repo" };
+    const [toplevel, gitDir, objects] = top.stdout.trim().split(/\r?\n/);
+    if (!toplevel || !gitDir || !objects)
+        return { reason: "git_failed" };
+    const scratch = mkdtempSync(join(tmpdir(), "bbx-receipt-"));
+    try {
+        const index = join(scratch, "index");
+        // Starting from the real index lets git skip files it already hashed.
+        if (existsSync(join(gitDir, "index")))
+            copyFileSync(join(gitDir, "index"), index);
+        // New blobs go to a scratch object store (the repository's is an alternate, so what's already
+        // there is found), and vanish with it: the receipt leaves no loose objects behind (L2.1.3).
+        const store = join(scratch, "objects");
+        mkdirSync(store);
+        const env = {
+            ...process.env,
+            GIT_INDEX_FILE: index,
+            GIT_OBJECT_DIRECTORY: store,
+            GIT_ALTERNATE_OBJECT_DIRECTORIES: resolve(cwd, objects),
+        };
+        const add = spawnSync("git", ["add", "-A", "--", "."], {
+            cwd: toplevel,
+            env,
+            encoding: "utf8",
+            timeout: GIT_TIMEOUT_MS,
+            windowsHide: true,
+        });
+        if (add.status !== 0)
+            return { reason: "git_failed" };
+        const tree = spawnSync("git", ["write-tree"], {
+            cwd: toplevel,
+            env,
+            encoding: "utf8",
+            timeout: GIT_TIMEOUT_MS,
+            windowsHide: true,
+        });
+        const hash = tree.stdout.trim();
+        return tree.status === 0 && /^([0-9a-f]{40}|[0-9a-f]{64})$/.test(hash)
+            ? { tree: hash }
+            : { reason: "git_failed" };
+    }
+    finally {
+        rmSync(scratch, { recursive: true, force: true });
+    }
+}
+/** The hook's JSON input (from Claude Code on stdin) → the receipt posted to the gateway. */
+export function receiptFor(hook, tree) {
+    const phase = hook.hook_event_name === "PreToolUse"
+        ? "pre"
+        : hook.hook_event_name === "PostToolUse"
+            ? "post"
+            : null;
+    if (!phase || typeof hook.tool_use_id !== "string" || hook.tool_use_id === "")
+        return null;
+    return {
+        phase,
+        tool_use_id: hook.tool_use_id,
+        ...(typeof hook.tool_name === "string" ? { tool: hook.tool_name.slice(0, 256) } : {}),
+        ...(typeof hook.session_id === "string"
+            ? { agent_session: hook.session_id.slice(0, 256) }
+            : {}),
+        ...("tree" in tree ? { tree: tree.tree } : { tree: null, reason: tree.reason }),
+    };
+}
+/** Posts one receipt. Resolves with null on 204, else the reason; never rejects. */
+export function postReceipt(gatewayUrl, token, receipt) {
+    return new Promise((resolve) => {
+        let url;
+        try {
+            url = new URL(`${gatewayUrl.replace(/\/$/, "")}/v1/workspace-receipts`);
+        }
+        catch {
+            return resolve("BLACKBOX_URL is not a URL");
+        }
+        const body = JSON.stringify(receipt);
+        const req = (url.protocol === "https:" ? httpsRequest : httpRequest)(url, {
+            method: "POST",
+            timeout: HTTP_TIMEOUT_MS,
+            headers: {
+                authorization: `Bearer ${token}`,
+                "content-type": "application/json",
+                "content-length": Buffer.byteLength(body),
+            },
+        });
+        req.on("response", (res) => {
+            res.resume();
+            resolve(res.statusCode === 204 ? null : `the gateway answered ${res.statusCode}`);
+        });
+        req.on("timeout", () => req.destroy(new Error("timed out")));
+        req.on("error", (error) => resolve(`the gateway could not be reached (${error.message})`));
+        req.end(body);
+    });
+}

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "@zanii/blackbox",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "license": "Apache-2.0",
+  "version": "0.2.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",
+    "observability",
+    "audit",
+    "flight-recorder",
+    "llm",
+    "mcp",
+    "langgraph",
+    "openai-agents",
+    "claude",
+    "tamper-evident",
+    "compliance"
+  ],
+  "homepage": "https://zanii.agency",
+  "bugs": {
+    "email": "info@zanii.agency"
+  },
+  "author": "Zanii <info@zanii.agency>",
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "blackbox": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@zanii/core": "^0.5.1",
+    "@zanii/sdk": "^0.5.1"
+  },
+  "devDependencies": {
+    "@anthropic-ai/claude-agent-sdk": "0.3.283",
+    "@langchain/core": "1.2.13",
+    "@langchain/langgraph": "1.4.18",
+    "@openai/agents": "0.18.0",
+    "langchain": "1.5.14",
+    "zod": "^4.6.5"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p .",
+    "test": "node --test --test-timeout=30000 \"src/**/*.test.ts\""
+  }
 }