dyadic 1.3.1 → 1.7.0

package/dist/blackbox.js

@@ -0,0 +1,852 @@
+// Dyadic Agent Black Box for TypeScript and JavaScript: record your agent's runs, check evidence bundles offline.
+//
+//   const recorder = new BlackBoxRecorder(client);            // a Dyadic client whose key may send Black Box telemetry
+//   await recorder.run({ title: "Book a room", agent: "planner" }, async (run) => {
+//     run.declare({ allowedTools: ["book_room"], allowedHosts: ["rooms.example.com"] });
+//     await run.modelCall("gpt-4.1", { input: messages }, async (call) => {
+//       const reply = await llm(messages);
+//       call.responded({ usage: { input_tokens: 812, output_tokens: 40 }, toolCalls: [{ id: "call_1", name: "book_room" }] });
+//       return reply;
+//     });
+//     await run.toolCall("book_room", { args: { room: "Orion" }, effect: true, hosts: ["rooms.example.com"], callId: "call_1" },
+//       async (tool) => tool.result(await bookRoom("Orion")));
+//     run.verified("booking", "confirmation ORN-1042 read back from the booking API");
+//   });
+//
+// Recording never blocks: events queue (bounded; telemetry is dropped first, every drop leaves a gap in this process's
+// own sequence numbers and a note) and are sent in batches with an Idempotency-Key. Spans nest explicitly: a span's
+// own methods (span.toolCall, span.agent, ...) make its children. Content (inputs, outputs, tool arguments and results)
+// is sent only with { captureContent: true }, after `redact` (secrets by default). Everything is recorded as *reported*
+// by your application. The same canonical JSON (RFC 8785), hashes and Ed25519 checks as the service and the Python SDK,
+// tested against sdk/contracts/blackbox.
+export const BUNDLE_FORMAT = "dyadic.blackbox.bundle/1";
+const GENESIS_PREFIX = "dyadic.blackbox.genesis/1:";
+const COMMIT_PREFIX = "dyadic.blackbox.commit/1\u0000";
+const TELEMETRY = new Set(["note", "span.started", "span.ended", "stream.summary", "retry"]);
+export const LIMITATIONS = [
+    "A hash chain shows recorded events were not altered, removed or reordered afterwards; it cannot show that activity the recorder never observed did not happen.",
+    "Events with basis 'reported' are what a producer outside the platform said happened; the platform did not see them.",
+    "A signature shows the holder of the signing key issued the checkpoint. Anyone holding the key (or a compromised signing service) could sign a different history; compare key ids with keys published independently.",
+    "Events after the last checkpoint are chained but not signed.",
+    "Timestamps come from the clock named in each event; clocks can be wrong or skewed.",
+    "Analysis in the bundle (graph, findings) is not covered by any signature and is interpretation, not evidence.",
+];
+// -- canonical JSON, hashes, trace context ------------------------------------------------------------
+/** RFC 8785 canonical JSON: sorted keys (UTF-16 code units), no whitespace, ECMAScript numbers and string escapes. */
+export function canonical(value) {
+    if (value === null || typeof value === "boolean" || typeof value === "string")
+        return JSON.stringify(value);
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            throw new TypeError("NaN and infinity have no JSON form");
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(",")}]`;
+    if (typeof value === "object") {
+        const record = value;
+        return `{${Object.keys(record).filter((k) => record[k] !== undefined).sort().map((k) => `${JSON.stringify(k)}:${canonical(record[k])}`).join(",")}}`;
+    }
+    throw new TypeError(`${typeof value} is not JSON`);
+}
+async function subtle() {
+    const web = globalThis.crypto;
+    if (web?.subtle)
+        return web.subtle;
+    const name = "node:crypto"; // Node 18 keeps WebCrypto here; never reached where globalThis.crypto exists
+    const node = await import(name);
+    return node.webcrypto.subtle;
+}
+const encoder = new TextEncoder();
+const hex = (bytes) => Array.from(new Uint8Array(bytes), (b) => b.toString(16).padStart(2, "0")).join("");
+export async function sha256Hex(data) {
+    return hex(await (await subtle()).digest("SHA-256", typeof data === "string" ? encoder.encode(data) : data));
+}
+export const genesis = (runId) => sha256Hex(GENESIS_PREFIX + runId);
+function fromBase64(text) {
+    const binary = atob(text);
+    return Uint8Array.from(binary, (c) => c.charCodeAt(0));
+}
+/** Base64 that isn't is a failed check, never an exception: bundles are hostile input. */
+function maybeBase64(text) {
+    try {
+        return typeof text === "string" ? fromBase64(text) : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function commitment(salt, value) {
+    const head = encoder.encode(COMMIT_PREFIX);
+    const body = encoder.encode(canonical(value));
+    const all = new Uint8Array(head.length + salt.length + body.length);
+    all.set(head, 0);
+    all.set(salt, head.length);
+    all.set(body, head.length + salt.length);
+    return sha256Hex(all);
+}
+export async function ed25519Verify(publicKey, message, signature) {
+    try {
+        const s = await subtle();
+        const key = await s.importKey("raw", publicKey, { name: "Ed25519" }, false, ["verify"]);
+        return await s.verify({ name: "Ed25519" }, key, signature, message);
+    }
+    catch {
+        return false;
+    }
+}
+// Ids need to be unique, not secret: WebCrypto where the runtime has it globally (Node 19+, browsers, Deno, Bun),
+// else Math.random (Node 18 keeps WebCrypto only in node:crypto, which can't be loaded synchronously).
+function fill(out) {
+    const web = globalThis.crypto;
+    if (web?.getRandomValues)
+        web.getRandomValues(out);
+    else
+        for (let i = 0; i < out.length; i++)
+            out[i] = Math.floor(Math.random() * 256);
+    return out;
+}
+function randomHex(bytes) {
+    const value = hex(fill(new Uint8Array(bytes)));
+    return /^0+$/.test(value) ? randomHex(bytes) : value;
+}
+export const newTraceId = () => randomHex(16);
+export const newSpanId = () => randomHex(8);
+const uuid = () => {
+    const b = fill(new Uint8Array(16));
+    b[6] = (b[6] & 0x0f) | 0x40;
+    b[8] = (b[8] & 0x3f) | 0x80;
+    const h = hex(b);
+    return `${h.slice(0, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}-${h.slice(16, 20)}-${h.slice(20)}`;
+};
+/** { traceId, spanId, sampled } from a W3C traceparent header (lowercase hex only), or null. */
+export function parseTraceparent(header) {
+    const match = /^([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/.exec((header ?? "").trim());
+    if (!match || match[1] === "ff" || /^0+$/.test(match[2]) || /^0+$/.test(match[3]))
+        return null;
+    return { traceId: match[2], spanId: match[3], sampled: (parseInt(match[4], 16) & 1) === 1 };
+}
+export const formatTraceparent = (traceId, spanId, sampled = true) => `00-${traceId}-${spanId}-${sampled ? "01" : "00"}`;
+// -- redaction --------------------------------------------------------------------------------------------
+const SECRET_PATTERNS = [
+    ["private_key", /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g],
+    ["jwt", /\beyJ[A-Za-z0-9_-]{8,}\.eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/g],
+    ["dyadic", /\bdy[ar][-_][A-Za-z0-9_-]{16,}/g],
+    ["provider", /\bsk-(?:ant-|or-v1-|proj-)?[A-Za-z0-9_-]{16,}/g],
+    ["github", /\b(?:gh[pousr]_[A-Za-z0-9]{30,}|github_pat_[A-Za-z0-9_]{40,})/g],
+    ["aws", /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/g],
+    ["bearer", /\b(?:[Bb]earer|[Bb]asic)\s+[A-Za-z0-9._~+/=-]{16,}/g],
+];
+const SECRET_FIELDS = new Set(["password", "passwd", "secret", "clientsecret", "token", "accesstoken", "refreshtoken", "apikey", "xapikey",
+    "authorization", "cookie", "setcookie", "privatekey", "sessionid", "credentials"]);
+/** Credentials replaced with [REDACTED:<kind>] before anything leaves the process (the service redacts again, and more). */
+export function redactSecrets(value, depth = 0) {
+    if (depth > 32)
+        return "[nested too deeply]";
+    if (typeof value === "string")
+        return SECRET_PATTERNS.reduce((text, [kind, pattern]) => text.replace(pattern, `[REDACTED:${kind}]`), value);
+    if (Array.isArray(value))
+        return value.map((v) => redactSecrets(v, depth + 1));
+    if (value && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, SECRET_FIELDS.has(k.toLowerCase().replace(/[^a-z0-9]/g, "")) && v !== null && v !== "" ? "[REDACTED:field]" : redactSecrets(v, depth + 1)]));
+    }
+    return value;
+}
+function canonicalText(text) {
+    if (typeof text !== "string")
+        return null;
+    try {
+        const value = JSON.parse(text);
+        return canonical(value) === text ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The same checks as the service's and the Python SDK's verifier. `trustedKeys` maps key ids to base64 public keys. */
+export async function verifyBundle(bundle, trustedKeys) {
+    const checks = [], errors = [], warnings = [];
+    const check = (name, ok, detail = "") => { checks.push({ name, ok, detail }); if (!ok)
+        errors.push(detail ? `${name}: ${detail}` : name); return ok; };
+    const report = (total, sealed) => ({ ok: errors.length === 0, events: total, signed_through: sealed,
+        trusted_keys: Boolean(trustedKeys), checks, errors, warnings, limitations: LIMITATIONS });
+    if (!bundle || bundle.format !== BUNDLE_FORMAT) {
+        check("format", false, `not a ${BUNDLE_FORMAT} bundle`);
+        return report(0, 0);
+    }
+    const runId = String(bundle.run?.id ?? ""), tenant = String(bundle.run?.tenant_ref ?? "");
+    const events = [...(bundle.events ?? [])].sort((a, b) => Number(a.seq) - Number(b.seq));
+    let previous = await genesis(runId), expected = 1, broken = 0;
+    const envelopes = [];
+    for (const item of events) {
+        const seq = Number(item.seq);
+        if (seq !== expected) {
+            check(`event ${expected}`, false, `missing: the chain jumps from ${expected - 1} to ${seq}`);
+            broken++;
+            expected = seq;
+        }
+        const envelope = canonicalText(item.canonical);
+        if (envelope === null) {
+            check(`event ${seq}`, false, "not canonical JSON");
+            broken++;
+            previous = String(item.hash ?? "");
+            expected = seq + 1;
+            continue;
+        }
+        const digest = await sha256Hex(item.canonical);
+        const problems = [];
+        if (digest !== item.hash)
+            problems.push("its hash doesn't match its text (changed after it was recorded)");
+        if (envelope.seq !== seq)
+            problems.push("its text names another position");
+        if (envelope.run !== runId || envelope.tenant !== tenant)
+            problems.push("its text names another run or tenant");
+        if (envelope.prev !== previous)
+            problems.push("it doesn't follow the event before it (an event was removed, added or reordered)");
+        if (problems.length) {
+            check(`event ${seq}`, false, problems.join("; "));
+            broken++;
+        }
+        envelopes.push(envelope);
+        previous = digest;
+        expected = seq + 1;
+    }
+    if (!broken)
+        check("chain", true, `${envelopes.length} events, unbroken from the genesis value`);
+    const bundled = {};
+    for (const key of bundle.keys ?? [])
+        if (key?.key_id && key?.public_key)
+            bundled[key.key_id] = key.public_key;
+    const keys = trustedKeys ?? bundled;
+    if (!trustedKeys)
+        warnings.push("No keys were given: the bundle's own keys were used, which shows only that it is consistent with itself. Compare its key ids with the keys the platform publishes.");
+    const hashes = new Map(events.map((e) => [Number(e.seq), e.hash]));
+    let sealed = 0;
+    for (const cp of bundle.checkpoints ?? []) {
+        const label = `checkpoint ${cp.tenant_seq ?? "?"}`;
+        const payload = canonicalText(cp.payload);
+        if (payload === null) {
+            check(label, false, "not canonical JSON");
+            continue;
+        }
+        const publicKey = keys[cp.key_id];
+        if (!publicKey) {
+            check(label, false, `signed with key '${cp.key_id}', which isn't among the keys given`);
+            continue;
+        }
+        const signature = maybeBase64(cp.signature), key = maybeBase64(publicKey);
+        if (!signature || !key) {
+            check(label, false, "the signature or key isn't base64");
+            continue;
+        }
+        if (!(await ed25519Verify(key, encoder.encode(cp.payload), signature))) {
+            check(label, false, "the signature doesn't verify");
+            continue;
+        }
+        if (cp.hash && (await sha256Hex(cp.payload)) !== cp.hash) {
+            check(label, false, "its hash doesn't match its payload");
+            continue;
+        }
+        if (payload.kind === "run" || payload.kind === "erasure") {
+            if (payload.run !== runId) {
+                check(label, false, "it is about another run");
+                continue;
+            }
+            if (hashes.get(Number(payload.seq)) !== payload.head) {
+                check(label, false, `it signed a different event ${payload.seq} than the bundle holds`);
+                continue;
+            }
+            sealed = Math.max(sealed, Number(payload.seq));
+        }
+        check(label, true, `${payload.kind} checkpoint signed by ${cp.key_id}, covering events 1..${payload.seq}`);
+    }
+    const chain = [...(bundle.tenant_chain ?? [])].sort((a, b) => Number(a.tenant_seq) - Number(b.tenant_seq));
+    let prior = null, chainOk = chain.length > 0;
+    for (const entry of chain) {
+        const payload = canonicalText(entry.payload);
+        const publicKey = keys[entry.key_id];
+        const signature = maybeBase64(entry.signature), key = maybeBase64(publicKey);
+        if (payload === null || !signature || !key || !(await ed25519Verify(key, encoder.encode(entry.payload), signature))) {
+            check("tenant chain", false, `checkpoint ${entry.tenant_seq} isn't canonical or signed by a given key`);
+            chainOk = false;
+            break;
+        }
+        if (prior && (Number(payload.tenant_seq) !== prior.seq + 1 || payload.prev !== prior.hash)) {
+            check("tenant chain", false, `the account's checkpoint log breaks before ${payload.tenant_seq}`);
+            chainOk = false;
+            break;
+        }
+        prior = { seq: Number(payload.tenant_seq), hash: await sha256Hex(entry.payload) };
+    }
+    if (chainOk)
+        check("tenant chain", true, `${chain.length} of the account's checkpoints link without a gap`);
+    const commits = new Map();
+    for (const envelope of envelopes)
+        for (const ref of envelope.content ?? [])
+            if (ref?.ref)
+                commits.set(ref.ref, ref.commit);
+    let bad = 0;
+    for (const item of bundle.content ?? []) {
+        if (!commits.has(item.ref)) {
+            check(`content ${item.ref}`, false, "no event refers to it");
+            bad++;
+            continue;
+        }
+        const salt = maybeBase64(item.salt);
+        if (!salt || (await commitment(salt, item.value)) !== commits.get(item.ref)) {
+            check(`content ${item.ref}`, false, "doesn't match the commitment its event recorded");
+            bad++;
+        }
+    }
+    if ((bundle.content ?? []).length && !bad)
+        check("content", true, `${bundle.content.length} pieces match their commitments`);
+    await verifyAnchors((bundle.anchors ?? []).filter((a) => a && typeof a === "object"), chain, bundle.checkpoints ?? [], tenant, check, warnings);
+    if (events.length && sealed < events.length)
+        warnings.push(`Events ${sealed + 1}..${events.length} are after the last valid checkpoint: chained, not signed.`);
+    if (!checks.some((c) => c.name.startsWith("checkpoint") && c.ok))
+        warnings.push("No valid checkpoint: nothing in the bundle is signed.");
+    return report(events.length, sealed);
+}
+// -- anchors: RFC 3161 timestamps over a Merkle root of checkpoint heads ------------------------------------
+const OID_SIGNED_DATA = "1.2.840.113549.1.7.2";
+const OID_TST_INFO = "1.2.840.113549.1.9.16.1.4";
+const HASH_OIDS = { "1.3.14.3.2.26": "sha1", "2.16.840.1.101.3.4.2.4": "sha224", "2.16.840.1.101.3.4.2.1": "sha256",
+    "2.16.840.1.101.3.4.2.2": "sha384", "2.16.840.1.101.3.4.2.3": "sha512" };
+const MAX_TOKEN = 256 * 1024;
+function readTlv(data, pos = 0) {
+    if (pos + 2 > data.length)
+        throw new Error("truncated");
+    const tag = data[pos];
+    if ((tag & 0x1f) === 0x1f)
+        throw new Error("high tag numbers are not used here");
+    let length = data[pos + 1], at = pos + 2;
+    if (length === 0x80)
+        throw new Error("indefinite lengths are not DER");
+    if (length & 0x80) {
+        const count = length & 0x7f;
+        if (count > 4 || at + count > data.length)
+            throw new Error("bad length");
+        length = 0;
+        for (let i = 0; i < count; i++)
+            length = length * 256 + data[at + i];
+        at += count;
+    }
+    if (at + length > data.length)
+        throw new Error("a length runs past the end");
+    return { tag, value: data.subarray(at, at + length), end: at + length };
+}
+function derChildren(value) {
+    const out = [];
+    for (let pos = 0; pos < value.length;) {
+        const item = readTlv(value, pos);
+        out.push(item);
+        pos = item.end;
+    }
+    return out;
+}
+function derOne(data) {
+    const item = readTlv(data);
+    if (item.end !== data.length)
+        throw new Error("trailing bytes");
+    return item;
+}
+function derExpect(item, tag, what) {
+    if (!item)
+        throw new Error(`${what}: missing`);
+    if (item.tag !== tag)
+        throw new Error(`${what}: expected tag 0x${tag.toString(16).padStart(2, "0")}, found 0x${item.tag.toString(16).padStart(2, "0")}`);
+    return item;
+}
+function derOid(item) {
+    const value = derExpect(item, 0x06, "OBJECT IDENTIFIER").value;
+    const arcs = [];
+    let current = 0;
+    for (const byte of value) {
+        current = current * 128 + (byte & 0x7f);
+        if (!(byte & 0x80)) {
+            arcs.push(current);
+            current = 0;
+        }
+    }
+    if (!arcs.length)
+        throw new Error("an empty OBJECT IDENTIFIER");
+    const first = arcs[0] < 40 ? [0, arcs[0]] : arcs[0] < 80 ? [1, arcs[0] - 40] : [2, arcs[0] - 80];
+    return [...first, ...arcs.slice(1)].join(".");
+}
+/** What an RFC 3161 TimeStampToken says it stamps (its TSTInfo's messageImprint) and when (genTime). Unchecked: the
+ * authority's CMS signature over it is not verified here. */
+export function readTimestampToken(token) {
+    if (token.length > MAX_TOKEN)
+        throw new Error("the token is too large");
+    const info = derChildren(derExpect(derOne(token), 0x30, "ContentInfo").value);
+    if (info.length !== 2 || derOid(info[0]) !== OID_SIGNED_DATA || info[1].tag !== 0xa0)
+        throw new Error("not a CMS SignedData");
+    const fields = derChildren(derExpect(derOne(info[1].value), 0x30, "SignedData").value);
+    if (fields.length < 4)
+        throw new Error("short SignedData");
+    const encap = derChildren(derExpect(fields[2], 0x30, "EncapsulatedContentInfo").value);
+    if (derOid(encap[0]) !== OID_TST_INFO)
+        throw new Error("the signed content is not a TSTInfo");
+    if (encap.length < 2 || encap[1].tag !== 0xa0)
+        throw new Error("the token carries no TSTInfo");
+    const econtent = derExpect(derOne(encap[1].value), 0x04, "eContent").value;
+    const tst = derChildren(derExpect(derOne(econtent), 0x30, "TSTInfo").value);
+    if (tst.length < 5)
+        throw new Error("short TSTInfo");
+    const imprint = derChildren(derExpect(tst[2], 0x30, "MessageImprint").value);
+    const algorithm = derOid(derChildren(derExpect(imprint[0], 0x30, "AlgorithmIdentifier").value)[0]);
+    const digest = hex(derExpect(imprint[1], 0x04, "hashedMessage").value);
+    const time = new TextDecoder().decode(derExpect(tst[4], 0x18, "genTime").value);
+    const match = /^(\d{4})(\d{2})(\d{2})(\d{2})(\d{2})(\d{2})(\.\d{1,9})?Z$/.exec(time);
+    if (!match)
+        throw new Error("bad time");
+    return { hashAlg: HASH_OIDS[algorithm] ?? algorithm, digest,
+        genTime: `${match[1]}-${match[2]}-${match[3]}T${match[4]}:${match[5]}:${match[6]}${match[7] ?? ""}Z` };
+}
+function fromHex(text) {
+    if (typeof text !== "string" || !/^(?:[0-9a-fA-F]{2})*$/.test(text))
+        throw new Error("not hex");
+    return Uint8Array.from(text.match(/../g) ?? [], (pair) => parseInt(pair, 16));
+}
+async function sha256Bytes(...parts) {
+    const all = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+    let at = 0;
+    for (const part of parts) {
+        all.set(part, at);
+        at += part.length;
+    }
+    return new Uint8Array(await (await subtle()).digest("SHA-256", all));
+}
+/** A head's leaf in an anchoring batch (RFC 6962 hashing): sha256(0x00 || canonical({v, tenant, tenant_seq, head})). */
+export const anchorLeaf = (tenant, tenantSeq, head) => sha256Bytes(new Uint8Array([0]), encoder.encode(canonical({ v: 1, tenant, tenant_seq: tenantSeq, head })));
+/** The root a leaf and its proof lead to: each step's sibling on its side, nodes sha256(0x01 || left || right). */
+export async function foldProof(leaf, proof) {
+    let value = leaf;
+    for (const step of proof) {
+        if (!step || typeof step !== "object")
+            throw new Error("a proof step isn't an object");
+        const sibling = fromHex(step.hash);
+        value = step.side === "left" ? await sha256Bytes(new Uint8Array([1]), sibling, value) : await sha256Bytes(new Uint8Array([1]), value, sibling);
+    }
+    return value;
+}
+/** The anchor checks of the service's verifier, except the authority's signature on its token (which needs CMS, X.509
+ * and RSA or ECDSA work this verifier doesn't do): reported as unchecked, never as verified. */
+async function verifyAnchors(anchors, chain, checkpoints, tenant, check, warnings) {
+    if (!anchors.length)
+        return;
+    const logged = new Map();
+    for (const entry of chain)
+        if (typeof entry?.payload === "string")
+            logged.set(Number(entry.tenant_seq ?? 0), await sha256Hex(entry.payload));
+    const sealedAt = Math.max(0, ...checkpoints.filter((c) => c && typeof c === "object").map((c) => Number(c.tenant_seq ?? 0) || 0));
+    for (const anchor of anchors) {
+        const name = `anchor at checkpoint ${anchor.tenant_seq}`;
+        let seq, top, token;
+        try {
+            seq = Number(anchor.tenant_seq);
+            if (!Number.isInteger(seq))
+                throw new Error("tenant_seq");
+            const head = String(anchor.head);
+            top = fromHex(String(anchor.root));
+            if (String(anchor.tenant) !== tenant) {
+                check(name, false, "it is for another account");
+                continue;
+            }
+            if (logged.get(seq) !== head) {
+                check(name, false, "the checkpoint it names isn't in the bundle's checkpoint log");
+                continue;
+            }
+            if (seq < sealedAt) {
+                check(name, false, "it comes before the run's last checkpoint, so it doesn't cover it");
+                continue;
+            }
+            if (!Array.isArray(anchor.proof ?? []))
+                throw new Error("proof");
+            if (hex(await foldProof(await anchorLeaf(tenant, seq, head), anchor.proof ?? [])) !== hex(top)) {
+                check(name, false, "its Merkle proof doesn't lead to the anchored root");
+                continue;
+            }
+            token = maybeBase64(anchor.token);
+            if (!token)
+                throw new Error("token");
+        }
+        catch (error) {
+            check(name, false, `unreadable (${error.message})`);
+            continue;
+        }
+        let stamped;
+        try {
+            stamped = readTimestampToken(token);
+        }
+        catch (error) {
+            check(name, false, `the time-stamping authority's token: not a usable timestamp token: ${error.message}`);
+            continue;
+        }
+        if (!Object.values(HASH_OIDS).includes(stamped.hashAlg)) {
+            check(name, false, `the time-stamping authority's token: unknown imprint hash ${stamped.hashAlg}`);
+            continue;
+        }
+        if (stamped.digest !== hex(top)) {
+            check(name, false, "the time-stamping authority's token: the token stamps a different digest");
+            continue;
+        }
+        check(name, true, `the checkpoint log through ${seq} is under the anchored root, which the token (${anchor.tsa ?? "an authority"}) stamps at `
+            + `${stamped.genTime}; the token's signature was not checked by this verifier`);
+        warnings.push(`${name}: the time-stamping authority's signature on its token was not checked (this verifier reads the token but `
+            + "does no CMS signature or certificate checks), so the time rests on the token's contents alone; check it with the Python SDK's "
+            + "verify_bundle or the bundle's verify.py.");
+    }
+}
+// -- webhooks (Standard Webhooks) ---------------------------------------------------------------------------
+/** The message isn't one the sink signed, or its timestamp is too far from now. */
+export class WebhookVerificationError extends Error {
+    constructor(message) { super(message); this.name = "WebhookVerificationError"; }
+}
+function headerValue(headers, name) {
+    const pick = (value) => (Array.isArray(value) ? String(value[0] ?? "") : value === undefined || value === null ? "" : String(value));
+    const getter = headers.get;
+    if (typeof getter === "function") {
+        const found = getter.call(headers, name);
+        if (found !== undefined && found !== null)
+            return pick(found);
+    }
+    const entries = typeof headers[Symbol.iterator] === "function"
+        ? headers : Object.entries(headers ?? {});
+    for (const [key, value] of entries)
+        if (String(key).toLowerCase() === name)
+            return pick(value);
+    return "";
+}
+function webhookKey(secret) {
+    const text = secret.trim().replace(/^whsec_/, "");
+    if (!text || text.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(text))
+        throw new WebhookVerificationError("The secret isn't a whsec_ secret (base64 after the prefix).");
+    return fromBase64(text);
+}
+const toBytes = (body) => typeof body === "string" ? encoder.encode(body) : body instanceof Uint8Array ? body : new Uint8Array(body);
+function toBase64(bytes) {
+    let binary = "";
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary);
+}
+/** The webhook-signature value the service sends for `body` (to test your own receiver). */
+export async function signWebhook(secret, messageId, timestamp, body) {
+    const s = await subtle();
+    const key = await s.importKey("raw", webhookKey(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+    const head = encoder.encode(`${messageId}.${Math.trunc(timestamp)}.`), raw = toBytes(body);
+    const message = new Uint8Array(head.length + raw.length);
+    message.set(head, 0);
+    message.set(raw, head.length);
+    return `v1,${toBase64(new Uint8Array(await s.sign("HMAC", key, message)))}`;
+}
+function sameText(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++)
+        diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    return diff === 0;
+}
+/** A Black Box webhook, parsed, once its signature matches and its timestamp is within `tolerance` seconds (300) of now
+ * (`now`, in Unix seconds, for tests); otherwise WebhookVerificationError says why. Pass the body exactly as it arrived (the
+ * raw text or bytes, before any JSON parsing) and the request's headers (a Headers object, Node's req.headers, or a plain
+ * object: case doesn't matter). Several space-separated signatures (a secret being rotated) are fine. WebCrypto: Node 18+,
+ * browsers, Deno, Bun, workers. */
+export async function verifyWebhook(body, headers, secret, options = {}) {
+    const id = headerValue(headers, "webhook-id").trim(), stamp = headerValue(headers, "webhook-timestamp").trim();
+    const signatures = headerValue(headers, "webhook-signature").trim();
+    if (!id || !stamp || !signatures)
+        throw new WebhookVerificationError("The webhook-id, webhook-timestamp and webhook-signature headers are required.");
+    if (!/^\d+$/.test(stamp))
+        throw new WebhookVerificationError("webhook-timestamp isn't a Unix time in seconds.");
+    const tolerance = options.tolerance ?? 300, now = options.now ?? Date.now() / 1000;
+    if (Math.abs(now - Number(stamp)) > tolerance) {
+        throw new WebhookVerificationError(`The message's timestamp is more than ${tolerance} seconds from now (a replay, or a wrong clock).`);
+    }
+    const expected = (await signWebhook(secret, id, Number(stamp), body)).slice(3);
+    const matched = signatures.split(/\s+/).filter((part) => part.startsWith("v1,")).map((part) => sameText(part.slice(3), expected));
+    if (!matched.includes(true))
+        throw new WebhookVerificationError("No signature matches: the body was changed, or it was signed with another secret.");
+    try {
+        return JSON.parse(new TextDecoder().decode(toBytes(body)));
+    }
+    catch {
+        throw new WebhookVerificationError("The signature matches but the body isn't JSON.");
+    }
+}
+const now = () => new Date().toISOString().replace(/\.(\d{3})Z$/, ".$1000Z");
+const clean = (attrs = {}) => JSON.parse(JSON.stringify(Object.fromEntries(Object.entries(attrs).filter(([, v]) => v !== undefined && v !== null))));
+export class BlackBoxRecorder {
+    constructor(client, options = {}) {
+        this.stats = { queued: 0, sent: 0, dropped: 0, failedBatches: 0 };
+        this.queue = [];
+        this.dropped = new Map();
+        this.timer = null;
+        this.sending = Promise.resolve();
+        const send = options.send ?? (client ? (batch, key) => client.blackbox.send(batch, { idempotencyKey: key }) : null);
+        if (!send)
+            throw new Error("BlackBoxRecorder needs a Dyadic client or options.send");
+        this.send = send;
+        this.options = { environment: options.environment ?? "production", captureContent: options.captureContent ?? false,
+            redact: options.redact === undefined ? redactSecrets : options.redact, batchSize: options.batchSize ?? 200,
+            flushIntervalMs: options.flushIntervalMs ?? 1000, maxQueue: Math.max(10, options.maxQueue ?? 10000), maxRetries: options.maxRetries ?? 5,
+            onError: options.onError };
+    }
+    /** Start a run; with `body`, run it and end it (failed if it throws). */
+    start(params) {
+        return new BlackBoxRun(this, params).start();
+    }
+    async run(params, body) {
+        const run = this.start(params);
+        try {
+            const value = await body(run);
+            run.end("completed");
+            return value;
+        }
+        catch (error) {
+            run.end("failed", { error });
+            throw error;
+        }
+    }
+    /** @internal */
+    enqueue(run, event) {
+        if (this.queue.length >= this.options.maxQueue) {
+            let index = this.queue.findIndex(([, e]) => TELEMETRY.has(e.type));
+            if (index < 0)
+                index = 0;
+            const [droppedRun] = this.queue.splice(index, 1)[0];
+            this.dropped.set(droppedRun.id, [droppedRun, (this.dropped.get(droppedRun.id)?.[1] ?? 0) + 1]);
+            this.stats.dropped++;
+        }
+        this.queue.push([run, event]);
+        this.stats.queued++;
+        if (this.queue.length >= this.options.batchSize)
+            void this.flush();
+        else if (!this.timer) {
+            this.timer = setTimeout(() => { this.timer = null; void this.flush(); }, this.options.flushIntervalMs);
+            this.timer?.unref?.();
+        }
+    }
+    /** Send everything queued; resolves when it has been sent (or given up on). */
+    flush() {
+        this.sending = this.sending.then(() => this.drain());
+        return this.sending;
+    }
+    async drain() {
+        while (this.queue.length || this.dropped.size) {
+            const items = this.queue.splice(0, this.options.batchSize);
+            const groups = new Map();
+            for (const [run, event] of items) {
+                if (!groups.has(run.id))
+                    groups.set(run.id, [run, []]);
+                groups.get(run.id)[1].push(event);
+            }
+            for (const [id, [run, count]] of this.dropped) {
+                if (!groups.has(id))
+                    groups.set(id, [run, []]);
+                groups.get(id)[1].push(run.noteEvent(`this process dropped ${count} events (its recorder's queue was full)`, { sdk_dropped: count }));
+            }
+            this.dropped.clear();
+            for (const [run, events] of groups.values())
+                await this.deliver(run, events);
+        }
+    }
+    async deliver(run, events) {
+        const batch = { run: run.descriptor(), events, sent_at: now() };
+        const key = (await sha256Hex(`${run.id}:${events[0].id}:${events[events.length - 1].id}:${events.length}`)).slice(0, 40);
+        for (let attempt = 0;; attempt++) {
+            try {
+                await this.send(batch, key);
+                this.stats.sent += events.length;
+                return;
+            }
+            catch (error) {
+                const status = Number(error.status);
+                if ((status >= 400 && status < 500 && status !== 429) || attempt >= this.options.maxRetries) {
+                    this.stats.failedBatches++;
+                    this.stats.dropped += events.length;
+                    this.options.onError?.(error, batch);
+                    return;
+                }
+                await new Promise((resolve) => { const t = setTimeout(resolve, Math.min(30000, 500 * 2 ** attempt)); t?.unref?.(); });
+            }
+        }
+    }
+}
+const KINDS = {
+    run: ["run.started", "run.completed", "run.failed"], span: ["span.started", "span.ended", "span.ended"],
+    model: ["model.requested", "model.responded", "model.failed"], tool: ["tool.requested", "tool.completed", "tool.failed"],
+    agent: ["agent.invoked", "agent.completed", "agent.failed"],
+};
+/** A timed piece of a run. Its methods make its children. */
+export class BlackBoxSpan {
+    constructor(run, kind, name, parentId, agent, attrs = {}, content, spanId) {
+        this.run = run;
+        this.kind = kind;
+        this.name = name;
+        this.parentId = parentId;
+        this.agent = agent;
+        this.attrs = attrs;
+        this.content = content;
+        this.ended = false;
+        this.startedAt = Date.now();
+        this.spanId = spanId ?? newSpanId();
+    }
+    /** @internal */
+    begin() { this.run.emit(KINDS[this.kind][0], this, { name: this.name, attrs: this.attrs, content: this.content }); return this; }
+    finish(type, status, attrs = {}, content) {
+        if (this.ended)
+            return;
+        this.ended = true;
+        this.run.emit(type, this, { status, name: this.name, attrs: { duration_ms: Date.now() - this.startedAt, ...attrs }, content });
+    }
+    end(attrs = {}) { this.finish(KINDS[this.kind][1], "ok", attrs); }
+    fail(error, attrs = {}) {
+        this.finish(KINDS[this.kind][2], "error", { error_type: error instanceof Error ? error.name : String(error ?? "error").slice(0, 120), ...attrs });
+    }
+    traceparent() { return formatTraceparent(this.run.traceId, this.spanId); }
+    async around(child, body) {
+        child.begin();
+        if (!body)
+            return undefined;
+        try {
+            const value = await body(child);
+            if (!child.ended)
+                child.end();
+            return value;
+        }
+        catch (error) {
+            child.fail(error);
+            throw error;
+        }
+    }
+    modelCall(model, options = {}, body) {
+        const { input, ...attrs } = options;
+        return this.around(new ModelCallSpan(this.run, "model", model, this.spanId, this.agent, { model, ...attrs }, input === undefined ? undefined : { "model.input": input }), body);
+    }
+    toolCall(name, options = {}, body) {
+        const { args, kind = "function", effect = false, hosts, callId, risk, ...attrs } = options;
+        const egress = ["external_api", "mcp", "browser", "communication"].includes(kind) ? "data" : undefined;
+        return this.around(new ToolCallSpan(this.run, "tool", name, this.spanId, this.agent, { kind, effect, hosts: hosts ? [...new Set(hosts)].sort() : undefined,
+            call_id: callId, risk, egress, arg_keys: args && typeof args === "object" && !Array.isArray(args) ? Object.keys(args).sort() : undefined, ...attrs }, args === undefined ? undefined : { "tool.args": args }), body);
+    }
+    agentSpan(agentId, options = {}, body) {
+        const { name, task, ...attrs } = options;
+        return this.around(new BlackBoxSpan(this.run, "agent", agentId, this.spanId, agentId, { agent: agentId, agent_name: name ?? agentId, ...attrs }, task === undefined ? undefined : { "agent.task": task }), body);
+    }
+    span(name, attrs = {}, body) {
+        return this.around(new BlackBoxSpan(this.run, "span", name, this.spanId, this.agent, attrs), body);
+    }
+    /** A decision your own policy made (allow, deny, require_approval). */
+    policy(decision, rule, options = {}) {
+        this.run.emit("policy.decision", this, { status: ["allow", "deny", "require_approval"].includes(decision) ? decision : "", name: options.tool ?? "",
+            attrs: { decision, rule, tool: options.tool, reason: options.reason, policy: options.policy, policy_version: options.version, subject: options.tool ? "tool" : undefined } });
+    }
+    note(text, attrs = {}) { this.run.emit("note", this, { attrs: { text, ...attrs } }); }
+}
+export class ModelCallSpan extends BlackBoxSpan {
+    /** What the model returned. Never pass hidden reasoning: it is not recorded. */
+    responded(options = {}) {
+        const usage = options.usage ?? {};
+        this.finish("model.responded", "ok", { input_tokens: usage.input_tokens ?? usage.prompt_tokens, output_tokens: usage.output_tokens ?? usage.completion_tokens,
+            cost_usd: usage.cost_usd, response_model: options.responseModel, response_id: options.responseId, finish_reason: options.finishReason,
+            tool_calls: options.toolCalls?.map((c) => ({ id: c.id, name: c.name })) }, options.output === undefined ? undefined : { "model.output": options.output });
+    }
+}
+export class ToolCallSpan extends BlackBoxSpan {
+    executing() { this.run.emit("tool.executing", this, { name: this.name, attrs: { write_ahead: true } }); }
+    /** It worked, as the tool reports: a claim, until `run.verified` records evidence. */
+    result(value, attrs = {}) {
+        this.finish("tool.completed", "ok", { ok: true, ...attrs }, value === undefined ? undefined : { "tool.result": value });
+    }
+    blocked(rule, reason = "", decision = "deny") {
+        this.policy(decision, rule, { tool: this.name, reason });
+        this.finish("tool.blocked", decision === "deny" ? "blocked" : "pending", { rule, decision });
+    }
+}
+export class BlackBoxRun extends BlackBoxSpan {
+    constructor(recorder, params) {
+        const parsed = parseTraceparent(params.traceparent);
+        const traceId = parsed?.traceId ?? newTraceId();
+        super(null, "run", params.agent ?? "run", parsed?.spanId ?? "", params.agent ?? "");
+        this.recorder = recorder;
+        this.seq = 0;
+        this.run = this;
+        this.id = params.runId ?? uuid();
+        this.traceId = traceId;
+        this.title = params.title ?? "";
+        this.agentName = params.agentName ?? params.agent ?? "";
+        this.parentHeader = parsed ? params.traceparent.trim() : null;
+        this.remoteParent = parsed?.spanId ?? "";
+    }
+    descriptor() {
+        return { id: this.id, trace_id: this.traceId, agent: { id: this.agent, name: this.agentName }, title: this.title,
+            environment: this.recorder.options.environment, root_span_id: this.spanId, ...(this.parentHeader ? { parent: this.parentHeader } : {}) };
+    }
+    /** @internal */
+    event(type, span, fields = {}) {
+        const event = { id: uuid().replace(/-/g, ""), type, status: fields.status ?? "", name: (fields.name ?? "").slice(0, 200), time: now(),
+            seq: ++this.seq, span_id: span.spanId, parent_span_id: span === this ? this.remoteParent : span.parentId, agent: span.agent || this.agent,
+            attrs: clean(fields.attrs) };
+        const options = this.recorder.options;
+        if (fields.content && options.captureContent) {
+            const kept = clean(fields.content);
+            if (Object.keys(kept).length)
+                event.content = (options.redact ? options.redact(kept) : kept);
+        }
+        return event;
+    }
+    /** @internal */
+    emit(type, span, fields = {}) { this.recorder.enqueue(this, this.event(type, span, fields)); }
+    /** @internal */
+    noteEvent(text, attrs) { return this.event("note", this, { attrs: { text, ...attrs } }); }
+    start() { this.emit("run.started", this, { name: this.agent, attrs: { title: this.title, sdk: "dyadic-js" } }); return this; }
+    end(status = "completed", options = {}) {
+        if (typeof status !== "string")
+            return this.end("completed");
+        if (this.ended)
+            return;
+        this.ended = true;
+        const type = { completed: "run.completed", failed: "run.failed", cancelled: "run.cancelled", requires_action: "run.requires_action" }[status];
+        const attrs = {};
+        if (options.error !== undefined)
+            attrs.error_type = options.error instanceof Error ? options.error.name : String(options.error).slice(0, 120);
+        this.emit(type, this, { status: { completed: "ok", failed: "error", cancelled: "cancelled", requires_action: "pending" }[status], attrs });
+    }
+    /** The task and its boundaries: the Black Box flags tools, hosts or steps beyond them. */
+    declare(options = {}) {
+        const { prompt, allowedTools, allowedHosts, maxSteps, ...attrs } = options;
+        this.emit("task.declared", this, { attrs: { allowed_tools: allowedTools ? [...new Set(allowedTools)].sort() : undefined,
+                allowed_hosts: allowedHosts ? [...new Set(allowedHosts)].sort() : undefined, max_steps: maxSteps, prompt_chars: prompt?.length, ...attrs },
+            content: prompt === undefined ? undefined : { "task.prompt": prompt } });
+    }
+    approval(tool, decision, options = {}) {
+        this.emit("approval.decided", this, { status: decision, name: tool, attrs: { tool, decision, approval_id: options.approvalId, decided_by: options.by } });
+    }
+    /** You checked an effect independently (read back what was written): evidence, not a claim. */
+    verified(kind, evidence, attrs = {}) {
+        this.emit("outcome.verified", this, { status: "ok", attrs: { kind, evidence, ...attrs } });
+    }
+    unverified(kind, reason) { this.emit("outcome.unverified", this, { status: "error", attrs: { kind, reason } }); }
+}
+/** Every tool an MCP client calls, recorded on `span`: the official TypeScript SDK's Client (callTool({ name, arguments })), or anything shaped like it. */
+export function instrumentMcpClient(client, span, options = {}) {
+    const original = client.callTool.bind(client);
+    if (client.callTool._dyadicBlackBox)
+        return client;
+    const readOnly = new Set(options.readOnly ?? []);
+    const wrapped = async (params, ...rest) => span.toolCall(params.name, { args: params.arguments, kind: "mcp", effect: !readOnly.has(params.name), hosts: options.host ? [options.host] : undefined,
+        mcp_server: options.server, mcp_tool: params.name }, async (tool) => {
+        const result = await original(params, ...rest);
+        if (result?.isError)
+            tool.fail("mcp_tool_error", { detail: "the server returned isError" });
+        else
+            tool.result(result?.structuredContent ?? result?.content);
+        return result;
+    });
+    wrapped._dyadicBlackBox = true;
+    client.callTool = wrapped;
+    return client;
+}