@zanii/blackbox 0.0.0-stage → 0.2.0

package/dist/hooks/langchain-agent.d.ts

@@ -0,0 +1,69 @@
+import { type CompiledPolicy } from "../policy/index.ts";
+import { type EventSink } from "./shared.ts";
+/** A BlackboxSession, or anything with the same methods. */
+export interface AgentSink extends EventSink {
+    state?(): Promise<{
+        control?: {
+            state?: string;
+        };
+    } | null>;
+    requestApproval?(tool: string, options?: {
+        args?: Record<string, unknown>;
+        reason?: string;
+    }): Promise<"approved" | "rejected" | "timeout" | "error">;
+}
+type ToolCall = {
+    name: string;
+    args?: Record<string, unknown>;
+    id?: string;
+};
+/** Thrown by `beforeAgent` when the gateway has stopped this session (spec/control.md). */
+export declare class BlackboxStoppedError extends Error {
+    constructor(state: string);
+}
+export declare function blackboxAgentMiddleware(session: AgentSink, options?: {
+    /** A tool policy checked before each tool call (spec/policy.md): deny refuses it,
+     * require_approval asks a second person through `requestApproval`. */
+    policy?: CompiledPolicy;
+    /** Before the run, stop if the gateway has blocked or paused the session (default true). */
+    checkBlock?: boolean;
+    /** Files with a machine-managed block (idea S5): file tools may not change it. */
+    protect?: readonly string[];
+}): {
+    [x: symbol]: true;
+    name: string;
+    beforeAgent(): Promise<undefined>;
+    wrapModelCall<Q extends {
+        messages?: readonly unknown[];
+        model?: unknown;
+    }, R>(request: Q, handler: (r: Q) => R | Promise<R>): Promise<R>;
+    wrapToolCall<Q extends {
+        toolCall: ToolCall;
+    }, R>(request: Q, handler: (r: Q) => R | Promise<R>): Promise<R>;
+    afterAgent(): undefined;
+};
+/** LangChain's human-in-the-loop request (humanInTheLoopMiddleware's interrupt value). */
+export interface HitlRequest {
+    actionRequests: Array<{
+        name: string;
+        args?: Record<string, unknown>;
+        description?: string;
+    }>;
+    reviewConfigs?: Array<{
+        actionName: string;
+        allowedDecisions: string[];
+    }>;
+}
+/** Idea I2: answers a LangChain HITL interrupt with Blackbox approvals, one per action, so a
+ * second person decides through Blackbox and the agent resumes with
+ * `new Command({ resume: await blackboxHitl(session, interrupt.value) })`. An edit can't be
+ * made here: anything but an approval is a reject, with the reason as its message. */
+export declare function blackboxHitl(session: AgentSink, request: HitlRequest): Promise<{
+    decisions: Array<{
+        type: "approve";
+    } | {
+        type: "reject";
+        message: string;
+    }>;
+}>;
+export {};

package/dist/hooks/langchain-agent.js

@@ -0,0 +1,163 @@
+// LangChain.js `createAgent` middleware (spec/sdk.md §5.2, idea I1). Mirrors hooks/langchain_agent.py.
+//
+//   const agent = createAgent({ model, tools, middleware: [blackboxAgentMiddleware(session, { policy })] });
+//
+// Put it first in the list, so it's the outermost: it sees every model and tool call, and its
+// gate is the last word before a tool runs. A plain object with LangChain's brand, so the SDK
+// needs no LangChain dependency (ToolMessage is loaded only when a call is refused).
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { decide } from "../policy/index.js";
+import { stableEventId } from "../session/index.js";
+import { protectedEdit } from "./protect.js";
+import { llmIds, neverThrow, providerOf } from "./shared.js";
+/** Thrown by `beforeAgent` when the gateway has stopped this session (spec/control.md). */
+export class BlackboxStoppedError extends Error {
+    constructor(state) {
+        super(`blackbox: the session is ${state}; resume it before the agent runs again`);
+        this.name = "BlackboxStoppedError";
+    }
+}
+/** The refusal for a file tool call that would change a protected file's managed block. */
+function protectedRefusal(protect, call) {
+    const args = call.args ?? {};
+    const target = typeof args.file_path === "string"
+        ? args.file_path
+        : typeof args.path === "string"
+            ? args.path
+            : undefined;
+    if (!protect?.length || target === undefined)
+        return null;
+    if (!protect.some((p) => resolve(p) === resolve(target)))
+        return null;
+    let current = null;
+    try {
+        current = readFileSync(target, "utf8");
+    }
+    catch { } // it doesn't exist (yet)
+    return protectedEdit(current, call.name, args);
+}
+/** LangGraph's control signals (interrupt(), Command) pass through untouched and aren't failures. */
+const isControl = (e) => ["GraphInterrupt", "NodeInterrupt", "ParentCommand"].includes(e?.name ?? "");
+export function blackboxAgentMiddleware(session, options = {}) {
+    /** With the tool call's id, a stable event id (idea R6), so a re-sent event counts once. */
+    const emit = (type, name, data, key) => neverThrow(() => session.event(type, name, data, key ? { eventId: stableEventId("lc-agent", type, key) } : {}));
+    const refusal = async (call, text) => {
+        const { ToolMessage } = await import("@langchain/core/messages");
+        return new ToolMessage({
+            content: `blackbox: ${text}`,
+            tool_call_id: call.id ?? "",
+            name: call.name,
+            status: "error",
+        });
+    };
+    return {
+        [Symbol.for("AgentMiddleware")]: true,
+        name: "blackbox",
+        async beforeAgent() {
+            emit("step", "agent.start", {});
+            if (options.checkBlock === false || !session.state)
+                return undefined;
+            const state = (await session.state())?.control?.state;
+            if (state === "blocked" || state === "paused")
+                throw new BlackboxStoppedError(state);
+            return undefined;
+        },
+        async wrapModelCall(request, handler) {
+            const m = request.model;
+            const model = m?.model ?? m?.modelName;
+            emit("llm.start", undefined, {
+                messages: request.messages?.length ?? 0,
+                ...(typeof model === "string" ? { params: { model } } : {}),
+            });
+            try {
+                const out = await handler(request);
+                neverThrow(() => {
+                    const m = out;
+                    const meta = m?.response_metadata ?? {};
+                    const id = typeof meta.id === "string" ? meta.id : typeof m?.id === "string" ? m.id : undefined;
+                    const ids = llmIds(id && !/^(lc_)?run-/.test(id) ? id : undefined, typeof meta.request_id === "string" ? meta.request_id : undefined, typeof meta.model_name === "string" ? meta.model_name : undefined);
+                    if (Object.keys(ids).length)
+                        emit("llm.call", providerOf(id), ids);
+                });
+                return out;
+            }
+            catch (error) {
+                if (!isControl(error))
+                    emit("llm.error", undefined, {
+                        error: String(error?.message ?? error).slice(0, 500),
+                    });
+                throw error;
+            }
+        },
+        async wrapToolCall(request, handler) {
+            const call = request.toolCall;
+            // The tool call's id is the run id the detectors pair a call and its result by.
+            const key = call.id;
+            emit("tool.call", call.name, { args: call.args ?? {}, ...(key ? { run_id: key } : {}) }, key);
+            const guarded = protectedRefusal(options.protect, call);
+            if (guarded) {
+                emit("tool.result", call.name, { ok: false, ...(key ? { run_id: key } : {}), error: "protected region" }, key);
+                return (await refusal(call, guarded.replace(/^blackbox: /, "")));
+            }
+            const d = options.policy ? decide(options.policy, [call.name], call.args ?? {}) : null;
+            if (d?.action === "deny") {
+                emit("tool.result", call.name, { ok: false, ...(key ? { run_id: key } : {}), error: `denied by ${d.rule}` }, key);
+                return (await refusal(call, `denied by policy ${d.rule}${d.reason ? `: ${d.reason}` : ""}`));
+            }
+            if (d?.action === "require_approval") {
+                const answer = session.requestApproval
+                    ? await session.requestApproval(call.name, {
+                        args: call.args ?? {},
+                        reason: `policy ${d.rule}`,
+                    })
+                    : "error";
+                if (answer !== "approved") {
+                    emit("tool.result", call.name, { ok: false, ...(key ? { run_id: key } : {}), error: `approval ${answer}` }, key);
+                    return (await refusal(call, `a second person's approval is needed (${answer})`));
+                }
+            }
+            try {
+                const out = await handler(request);
+                const status = out?.status;
+                emit("tool.result", call.name, { ok: status !== "error", ...(key ? { run_id: key } : {}) }, key);
+                return out;
+            }
+            catch (error) {
+                if (isControl(error)) {
+                    emit("interrupt", call.name, { ...(key ? { run_id: key } : {}) }, key);
+                }
+                else
+                    emit("tool.result", call.name, {
+                        ok: false,
+                        ...(key ? { run_id: key } : {}),
+                        error: String(error?.message ?? error).slice(0, 500),
+                    }, key);
+                throw error; // control signals included: LangGraph needs them
+            }
+        },
+        afterAgent() {
+            emit("step", "agent.end", {});
+            return undefined;
+        },
+    };
+}
+/** Idea I2: answers a LangChain HITL interrupt with Blackbox approvals, one per action, so a
+ * second person decides through Blackbox and the agent resumes with
+ * `new Command({ resume: await blackboxHitl(session, interrupt.value) })`. An edit can't be
+ * made here: anything but an approval is a reject, with the reason as its message. */
+export async function blackboxHitl(session, request) {
+    const decisions = [];
+    for (const a of request.actionRequests) {
+        const answer = session.requestApproval
+            ? await session.requestApproval(a.name, {
+                args: a.args ?? {},
+                ...(a.description ? { reason: a.description } : {}),
+            })
+            : "error";
+        decisions.push(answer === "approved"
+            ? { type: "approve" }
+            : { type: "reject", message: `blackbox: not approved (${answer})` });
+    }
+    return { decisions };
+}

package/dist/hooks/langchain.d.ts

@@ -0,0 +1,41 @@
+import { type EventSink } from "./shared.ts";
+type Meta = Record<string, unknown> | undefined;
+export interface BlackboxCallbacks {
+    name: string;
+    /** N4 (idea R11): LangChain.js waits for each handler, so the log keeps up with the run. */
+    awaitHandlers: boolean;
+    /** LangGraph.js's GraphCallbackHandler brand. */
+    readonly [brand: symbol]: unknown;
+    handleChatModelStart(llm: unknown, messages: readonly (readonly unknown[])[], runId: string, parentRunId?: string, extraParams?: Record<string, unknown>): void;
+    handleLLMStart(llm: unknown, prompts: readonly string[], runId: string, parentRunId?: string, extraParams?: Record<string, unknown>): void;
+    handleLLMError(error: unknown, runId: string): void;
+    handleRetrieverEnd(documents: readonly unknown[], runId: string): void;
+    handleCustomEvent(eventName: string, data: unknown, runId: string): void;
+    /** N5 (idea R3): LangGraph.js's own lifecycle callbacks (it calls them for handlers with its brand). */
+    handleInterrupt(event: GraphEvent): void;
+    handleResume(event: GraphEvent): void;
+    handleChainStart(chain: unknown, inputs: unknown, runId: string, parentRunId?: string, tags?: string[], metadata?: Meta, runType?: string, runName?: string): void;
+    handleToolStart(tool: unknown, input: string, runId: string, parentRunId?: string, tags?: string[], metadata?: Meta, runName?: string, toolCallId?: string, toolInputs?: unknown): void;
+    handleChainEnd(outputs: unknown, runId: string): void;
+    handleChainError(error: unknown, runId: string): void;
+    handleToolEnd(output: unknown, runId: string): void;
+    handleToolError(error: unknown, runId: string): void;
+    handleLLMEnd(output: {
+        generations?: readonly (readonly object[])[];
+        llmOutput?: Record<string, unknown>;
+    }, runId: string, parentRunId?: string, tags?: string[], extraParams?: Record<string, unknown>): void;
+}
+/** LangGraph.js's GraphInterruptEvent / GraphResumeEvent. */
+type GraphEvent = {
+    runId?: string;
+    status?: string;
+    checkpointId?: string;
+    checkpointNs?: readonly string[];
+    interrupts?: ReadonlyArray<{
+        id?: string;
+    }>;
+};
+export declare function blackboxCallbacks(session: EventSink): BlackboxCallbacks;
+/** Audit S6: the Python SDK's name, so docs and examples can be written once. Called, not `new`ed. */
+export declare const BlackboxCallbackHandler: typeof blackboxCallbacks;
+export {};

package/dist/hooks/langchain.js

@@ -0,0 +1,216 @@
+// LangChain.js / LangGraph.js callback handler (spec/sdk.md §5). Mirrors hooks/langchain.py.
+//
+//   await graph.invoke(input, { callbacks: [blackboxCallbacks(session)], configurable: { thread_id } })
+//
+// A plain handler object: LangChain.js accepts any object with the handle* methods, so the SDK
+// needs no LangChain dependency.
+import { stableEventId } from "../session/index.js";
+import { llmIds, neverThrow, providerOf } from "./shared.js";
+/** A stable id per callback (N4, idea R6): a re-sent callback is recorded as a duplicate. The
+ * extra argument is ignored by sinks that don't take it. */
+const emit = (sink, type, name, data, key) => sink.event(type, name, data, { eventId: stableEventId("langchain", type, key) });
+const PARAMS = ["model", "model_name", "temperature", "max_tokens", "top_p", "stop", "seed"];
+/** N4 (idea R11): usage_metadata, flattened: tokens only, with cache and reasoning detail. */
+function usageOf(u) {
+    const out = {};
+    for (const k of ["input_tokens", "output_tokens", "total_tokens"])
+        if (Number.isSafeInteger(u?.[k]))
+            out[k] = u?.[k];
+    for (const group of ["input_token_details", "output_token_details"])
+        for (const [k, v] of Object.entries(u?.[group] ?? {}))
+            if (Number.isSafeInteger(v))
+                out[`${group.split("_")[0]}_${k}`] = v;
+    return out;
+}
+export function blackboxCallbacks(session) {
+    const parents = new Map();
+    const threads = new Map(); // a graph run's thread_id, for its interrupts
+    const lifecycle = (type, e) => {
+        const ns = [...(e.checkpointNs ?? [])].map(String);
+        const last = ns.at(-1) ?? "";
+        const node = last.includes(":") ? last.slice(0, last.lastIndexOf(":")) : undefined;
+        session.event(type, node?.slice(0, 256), {
+            source: "langgraph",
+            checkpoint_id: String(e.checkpointId ?? ""),
+            checkpoint_ns: ns.join("|"),
+            status: String(e.status ?? ""),
+            ...(e.runId ? { run_id: e.runId } : {}),
+            ...(e.runId && threads.has(e.runId) ? { thread_id: threads.get(e.runId) } : {}),
+            ...(node ? { node, task_id: last.slice(last.lastIndexOf(":") + 1) } : {}),
+            ...(type === "interrupt"
+                ? { interrupt_ids: (e.interrupts ?? []).flatMap((i) => (i?.id ? [String(i.id)] : [])) }
+                : {}),
+        });
+    };
+    const tools = new Map();
+    const nodes = new Map();
+    const track = (runId, parentRunId) => {
+        parents.set(runId, parentRunId);
+        let root = runId;
+        const seen = new Set();
+        for (let p = parents.get(root); p && !seen.has(root); p = parents.get(root)) {
+            seen.add(root);
+            root = p;
+        }
+        return root;
+    };
+    const graph = (metadata) => {
+        const m = metadata ?? {};
+        return {
+            ...(typeof m.langgraph_node === "string" ? { node: m.langgraph_node } : {}),
+            ...(typeof m.langgraph_step === "number" ? { langgraph_step: m.langgraph_step } : {}),
+            ...(m.thread_id !== undefined && m.thread_id !== null
+                ? { thread_id: String(m.thread_id) }
+                : {}),
+            // LangGraph's deterministic task id is the suffix after the last ":" of langgraph_checkpoint_ns.
+            ...(typeof m.langgraph_checkpoint_ns === "string" && m.langgraph_checkpoint_ns.includes(":")
+                ? {
+                    checkpoint_ns: m.langgraph_checkpoint_ns,
+                    task_id: m.langgraph_checkpoint_ns.slice(m.langgraph_checkpoint_ns.lastIndexOf(":") + 1),
+                }
+                : {}),
+        };
+    };
+    const nameOf = (serialized, runName) => {
+        const s = serialized;
+        const fromId = Array.isArray(s?.id) ? s?.id.at(-1) : undefined;
+        return String(runName ?? s?.name ?? fromId ?? "run").slice(0, 256);
+    };
+    const llmStart = (runId, parentRunId, count, extra) => {
+        const root = track(runId, parentRunId);
+        const raw = extra?.invocation_params ?? {};
+        const params = Object.fromEntries(PARAMS.filter((k) => ["string", "number"].includes(typeof raw[k]) || Array.isArray(raw[k])).map((k) => [k, raw[k]]));
+        emit(session, "llm.start", undefined, { run_id: runId, root_run_id: root, messages: count, params }, runId);
+    };
+    return {
+        name: "blackbox",
+        awaitHandlers: true,
+        [Symbol.for("langgraph.graph_callback_handler")]: true,
+        handleInterrupt(event) {
+            neverThrow(() => lifecycle("interrupt", event));
+        },
+        handleResume(event) {
+            neverThrow(() => lifecycle("resume", event));
+        },
+        handleChatModelStart(_llm, messages, runId, parentRunId, extraParams) {
+            neverThrow(() => llmStart(runId, parentRunId, messages.reduce((n, m) => n + m.length, 0), extraParams));
+        },
+        handleLLMStart(_llm, prompts, runId, parentRunId, extraParams) {
+            neverThrow(() => llmStart(runId, parentRunId, prompts.length, extraParams));
+        },
+        handleLLMError(error, runId) {
+            neverThrow(() => {
+                const text = error instanceof Error ? error.message : String(error);
+                const type = error instanceof Error ? error.name : typeof error;
+                emit(session, "llm.error", undefined, { run_id: runId, error: text.slice(0, 500), type }, runId);
+            });
+        },
+        handleRetrieverEnd(documents, runId) {
+            neverThrow(() => {
+                const sources = documents
+                    .slice(0, 20)
+                    .map((d) => {
+                    const doc = d;
+                    return doc.metadata?.source ?? doc.id;
+                })
+                    .filter((s) => s !== undefined && s !== null)
+                    .map((s) => String(s).slice(0, 256));
+                emit(session, "retrieval", undefined, { run_id: runId, documents: documents.length, sources }, runId);
+            });
+        },
+        handleCustomEvent(eventName, data, runId) {
+            neverThrow(() => session.event("custom", String(eventName).slice(0, 256), {
+                run_id: runId,
+                ...(typeof data === "object" && data !== null && !Array.isArray(data) ? { data } : {}),
+            }));
+        },
+        handleChainStart(chain, _inputs, runId, parentRunId, _tags, metadata, _runType, runName) {
+            neverThrow(() => {
+                const root = track(runId, parentRunId);
+                const g = graph(metadata);
+                const name = nameOf(chain, runName);
+                if (g.node && name === g.node)
+                    nodes.set(runId, g);
+                if (!parentRunId && g.thread_id)
+                    threads.set(runId, g.thread_id);
+                // A LangGraph node's own run, or a top-level run; not every inner runnable.
+                if (!parentRunId || (g.node && name === g.node))
+                    emit(session, "step", name, { run_id: runId, root_run_id: root, ...g }, runId);
+            });
+        },
+        handleToolStart(tool, input, runId, parentRunId, _tags, metadata, runName, _toolCallId, toolInputs) {
+            neverThrow(() => {
+                const root = track(runId, parentRunId);
+                const name = nameOf(tool, runName);
+                tools.set(runId, name);
+                let args = toolInputs ?? input;
+                if (toolInputs === undefined && typeof input === "string") {
+                    try {
+                        args = JSON.parse(input);
+                    }
+                    catch { }
+                }
+                emit(session, "tool.call", name, { args, run_id: runId, root_run_id: root, ...graph(metadata) }, runId);
+            });
+        },
+        handleChainEnd(_outputs, runId) {
+            nodes.delete(runId);
+        },
+        handleChainError(error, runId) {
+            neverThrow(() => {
+                const g = nodes.get(runId);
+                nodes.delete(runId);
+                // interrupt() stops a node with GraphInterrupt; resuming re-runs the node from the top.
+                const kind = error?.name;
+                if (g && (kind === "GraphInterrupt" || kind === "NodeInterrupt"))
+                    session.event("interrupt", String(g.node).slice(0, 256), { run_id: runId, ...g });
+            });
+        },
+        handleToolEnd(_output, runId) {
+            neverThrow(() => {
+                emit(session, "tool.result", tools.get(runId) ?? "tool", { ok: true, run_id: runId }, runId);
+                tools.delete(runId);
+            });
+        },
+        handleToolError(error, runId) {
+            neverThrow(() => {
+                const text = error instanceof Error ? error.message : String(error);
+                emit(session, "tool.result", tools.get(runId) ?? "tool", { ok: false, run_id: runId, error: text.slice(0, 500) }, runId);
+                tools.delete(runId);
+            });
+        },
+        handleLLMEnd(output, runId, _parentRunId, _tags, extraParams) {
+            neverThrow(() => {
+                if (extraParams?.cached === true)
+                    return; // a LangChain cache hit: no provider call to witness
+                let id;
+                let model;
+                let requestId;
+                let usage = {};
+                for (const generations of output.generations ?? [])
+                    for (const g of generations) {
+                        if (Object.keys(usage).length === 0)
+                            usage = usageOf(g.message?.usage_metadata);
+                        const meta = g.message?.response_metadata ?? {};
+                        // response_metadata.id, else the message's own id (Chat Completions, Anthropic
+                        // streaming); LangChain's placeholders ("run-…", "lc_run-…") aren't provider ids.
+                        const own = [g.message?.id, g.message?.additional_kwargs?.id].find((v) => typeof v === "string" && !/^(lc_)?run-/.test(v));
+                        id ??= typeof meta.id === "string" ? meta.id : own;
+                        model ??=
+                            typeof meta.model_name === "string"
+                                ? meta.model_name
+                                : typeof meta.model === "string"
+                                    ? meta.model
+                                    : undefined;
+                        requestId ??= typeof meta.request_id === "string" ? meta.request_id : undefined;
+                    }
+                id ??= typeof output.llmOutput?.id === "string" ? output.llmOutput.id : undefined;
+                const ids = llmIds(id, requestId, model);
+                if (Object.keys(ids).length > 0)
+                    emit(session, "llm.call", providerOf(id), { ...ids, ...(Object.keys(usage).length ? { usage } : {}) }, runId);
+            });
+        },
+    };
+}
+/** Audit S6: the Python SDK's name, so docs and examples can be written once. Called, not `new`ed. */
+export const BlackboxCallbackHandler = blackboxCallbacks;

package/dist/hooks/langgraph-checkpoint.d.ts

@@ -0,0 +1,12 @@
+import { type EventSink } from "./shared.ts";
+type Config = {
+    configurable?: Record<string, unknown>;
+};
+interface Saver {
+    put(config: Config, checkpoint: {
+        id?: unknown;
+    }, metadata: unknown, versions: unknown): Promise<unknown>;
+    putWrites(config: Config, writes: ReadonlyArray<readonly [string, unknown]>, taskId: string): Promise<void>;
+}
+export declare function blackboxCheckpointer<T extends Saver>(inner: T, session: EventSink): T;
+export {};

package/dist/hooks/langgraph-checkpoint.js

@@ -0,0 +1,73 @@
+// A LangGraph.js checkpointer that records what it saves (spec/sdk.md §5.3, ideas R1, R2).
+// Mirrors hooks/langgraph_checkpoint.py.
+//
+//   const app = graph.compile({ checkpointer: blackboxCheckpointer(new MemorySaver(), session) });
+//
+// Every `put` is a `checkpoint.put` event and every `putWrites` a `checkpoint.writes` event: ids,
+// the step, the source and channel names, never the values. The wrapper is the inner saver with
+// two methods replaced (its prototype is the inner one, so `instanceof BaseCheckpointSaver` still
+// holds): the SDK needs no LangGraph dependency.
+import { stableEventId } from "../session/index.js";
+import { neverThrow } from "./shared.js";
+export function blackboxCheckpointer(inner, session) {
+    const emit = (type, name, data, key) => neverThrow(() => session.event(type, name, data, {
+        eventId: stableEventId("checkpoint", type, ...key),
+    }));
+    const where = (config) => {
+        const c = config?.configurable ?? {};
+        return Object.fromEntries(["thread_id", "checkpoint_ns", "checkpoint_id"]
+            .filter((k) => c[k] !== undefined && c[k] !== null)
+            .map((k) => [k, String(c[k])]));
+    };
+    // Every method runs on the inner saver itself, so its own state stays its own.
+    const wrapped = Object.create(inner);
+    let p = inner;
+    while (p && p !== Object.prototype) {
+        for (const name of Object.getOwnPropertyNames(p)) {
+            const v = inner[name];
+            if (name !== "constructor" &&
+                typeof v === "function" &&
+                !(name in wrapped && Object.hasOwn(wrapped, name)))
+                Object.defineProperty(wrapped, name, {
+                    value: v.bind(inner),
+                    writable: true,
+                    configurable: true,
+                });
+        }
+        p = Object.getPrototypeOf(p);
+    }
+    wrapped.put = async (config, checkpoint, metadata, versions) => {
+        const out = await inner.put(config, checkpoint, metadata, versions);
+        const w = where(config);
+        const m = (metadata ?? {});
+        const data = {
+            thread_id: w.thread_id ?? "",
+            checkpoint_ns: w.checkpoint_ns ?? "",
+            checkpoint_id: String(checkpoint?.id ?? ""),
+            ...(w.checkpoint_id ? { parent_checkpoint_id: w.checkpoint_id } : {}),
+            ...(Number.isSafeInteger(m.step) ? { step: m.step } : {}),
+            ...(m.source ? { source: String(m.source) } : {}),
+            channels: Object.keys(versions ?? {}).sort(),
+        };
+        emit("checkpoint.put", data.source, data, [
+            data.thread_id,
+            data.checkpoint_ns,
+            data.checkpoint_id,
+        ]);
+        return out;
+    };
+    wrapped.putWrites = async (config, writes, taskId) => {
+        await inner.putWrites(config, writes, taskId);
+        const w = where(config);
+        const channels = writes.map(([c]) => String(c));
+        emit("checkpoint.writes", undefined, {
+            ...w,
+            task_id: taskId,
+            channels,
+            error: channels.includes("__error__"),
+            interrupt: channels.includes("__interrupt__"),
+            resume: channels.includes("__resume__"),
+        }, [w.thread_id ?? "", w.checkpoint_id ?? "", taskId, ...channels]);
+    };
+    return wrapped;
+}

package/dist/hooks/memory.d.ts

@@ -0,0 +1,17 @@
+export interface MemorySink {
+    memoryWrite(memoryId: string, summary?: string): void;
+    memoryRead(memoryIds: string[], query?: string): void;
+    memoryRevoke(memoryId: string, reason?: string): void;
+}
+export interface MemoryMethod {
+    /** The store's method name. */
+    method: string;
+    /** The memory ids a call touched, from its result and arguments. */
+    ids?: (result: unknown, args: unknown[]) => string[];
+}
+export interface TrackMemoryOptions {
+    write?: MemoryMethod;
+    read?: MemoryMethod;
+    revoke?: MemoryMethod;
+}
+export declare function trackMemory<T extends object>(store: T, sink: MemorySink, options?: TrackMemoryOptions): T;

package/dist/hooks/memory.js

@@ -0,0 +1,64 @@
+// Audit S10: a memory store, wrapped so its writes, reads and deletes are recorded for the Memory
+// X-ray (spec/agents.md §1) without wiring memoryWrite / memoryRead / memoryRevoke by hand.
+// Duck-typed; the defaults fit mem0-shaped stores (add / search / delete, `{results: [{id, memory}]}`).
+// Mirrors sdks/python/src/zanii_blackbox/hooks/memory.py.
+//
+//   const memory = trackMemory(new Memory(), session);
+//   await memory.add(messages, { userId });   // → memory.write, one per memory id
+import { neverThrow } from "./shared.js";
+/** Items with an `id`: an array, `{results: [...]}`, or one item. */
+function itemsOf(result) {
+    if (Array.isArray(result))
+        return result;
+    const r = result;
+    if (r && Array.isArray(r.results))
+        return r.results;
+    if (r && typeof r === "object" && typeof r.id === "string")
+        return [r];
+    return [];
+}
+const idsOf = (result) => itemsOf(result)
+    .map((i) => i.id)
+    .filter((id) => typeof id === "string");
+const DEFAULTS = {
+    write: { method: "add", ids: idsOf },
+    read: { method: "search", ids: idsOf },
+    // delete(memoryId): the id is the argument
+    revoke: { method: "delete", ids: (_r, args) => (typeof args[0] === "string" ? [args[0]] : []) },
+};
+export function trackMemory(store, sink, options = {}) {
+    const kinds = {
+        write: { ...DEFAULTS.write, ...options.write },
+        read: { ...DEFAULTS.read, ...options.read },
+        revoke: { ...DEFAULTS.revoke, ...options.revoke },
+    };
+    const record = (kind, result, args) => neverThrow(() => {
+        const ids = (kinds[kind].ids ?? idsOf)(result, args);
+        if (kind === "read") {
+            sink.memoryRead(ids, typeof args[0] === "string" ? args[0] : undefined);
+            return;
+        }
+        const summaries = new Map(itemsOf(result).map((i) => [i.id, typeof i.memory === "string" ? i.memory : undefined]));
+        for (const id of ids)
+            if (kind === "write")
+                sink.memoryWrite(id, summaries.get(id)?.slice(0, 200));
+            else
+                sink.memoryRevoke(id);
+    });
+    return new Proxy(store, {
+        get(obj, prop, receiver) {
+            const value = Reflect.get(obj, prop, receiver);
+            const kind = Object.keys(kinds).find((k) => kinds[k].method === prop);
+            if (!kind || typeof value !== "function")
+                return value;
+            return (...args) => {
+                const result = value.apply(obj, args);
+                if (typeof result?.then === "function")
+                    result.then((r) => record(kind, r, args), () => { });
+                else
+                    record(kind, result, args);
+                return result;
+            };
+        },
+    });
+}

package/dist/hooks/openai-agents.d.ts

@@ -0,0 +1,6 @@
+import { type EventSink } from "./shared.ts";
+interface HookEmitter {
+    on(event: any, listener: any): unknown;
+}
+export declare function attachBlackbox(runner: HookEmitter, session: EventSink): void;
+export {};