@zanii/blackbox 0.0.0-stage → 0.1.0

package/dist/hooks/claude-agent-sdk.d.ts

@@ -0,0 +1,14 @@
+import { type EventSink } from "./shared.ts";
+type Callback = (input: unknown, toolUseId: string | undefined, options: unknown) => Promise<object>;
+export interface BlackboxAgentHooks {
+    /** Pass as `options.hooks`. */
+    hooks: Record<"PreToolUse" | "PostToolUse" | "PostToolUseFailure", Array<{
+        hooks: Callback[];
+    }>>;
+    /** Call with every message `query()` yields; reports each model call's id once. */
+    observe(message: unknown): void;
+}
+export declare function blackboxAgentHooks(session: EventSink): BlackboxAgentHooks;
+/** Audit S6: the Python SDK's name, so docs and examples can be written once. Called, not `new`ed. */
+export declare const BlackboxAgentHooks: typeof blackboxAgentHooks;
+export {};

package/dist/hooks/claude-agent-sdk.js

@@ -0,0 +1,70 @@
+// Claude Agent SDK hooks (spec/sdk.md §5). Mirrors hooks/claude_agent_sdk.py.
+//
+//   const bbx = blackboxAgentHooks(session);
+//   for await (const message of query({ prompt, options: { hooks: bbx.hooks, env } })) {
+//     bbx.observe(message);
+//     …
+//   }
+//
+// Tool calls come from the SDK's PreToolUse / PostToolUse / PostToolUseFailure hooks; model calls
+// from the assistant messages `query()` yields (the Agent SDK has no model-call hook). Structural
+// types only, so the Agent SDK stays an optional dependency.
+import { neverThrow } from "./shared.js";
+const MAX_ERROR = 500;
+export function blackboxAgentHooks(session) {
+    const seen = new Set();
+    const hook = (fn) => async (input) => {
+        neverThrow(() => fn((input ?? {})));
+        return {}; // no decision: the hook only records
+    };
+    const common = (i) => ({
+        ...(i.tool_use_id ? { tool_use_id: i.tool_use_id } : {}),
+        ...(i.agent_id ? { agent_id: i.agent_id } : {}),
+    });
+    const name = (i) => String(i.tool_name ?? "tool").slice(0, 256);
+    return {
+        hooks: {
+            PreToolUse: [
+                {
+                    hooks: [
+                        hook((i) => session.event("tool.call", name(i), {
+                            ...common(i),
+                            ...(i.tool_input === undefined ? {} : { args: i.tool_input }),
+                        })),
+                    ],
+                },
+            ],
+            PostToolUse: [
+                { hooks: [hook((i) => session.event("tool.result", name(i), { ok: true, ...common(i) }))] },
+            ],
+            PostToolUseFailure: [
+                {
+                    hooks: [
+                        hook((i) => session.event("tool.result", name(i), {
+                            ok: false,
+                            ...common(i),
+                            error: String(i.error ?? "").slice(0, MAX_ERROR),
+                        })),
+                    ],
+                },
+            ],
+        },
+        observe(message) {
+            neverThrow(() => {
+                const m = message;
+                const id = m?.type === "assistant" ? m.message?.id : undefined;
+                // One API response can arrive as several assistant messages (one per content block).
+                if (typeof id !== "string" || seen.has(id))
+                    return;
+                seen.add(id);
+                session.event("llm.call", "anthropic", {
+                    provider: "anthropic",
+                    message_id: id,
+                    ...(typeof m.message?.model === "string" ? { model: m.message.model } : {}),
+                });
+            });
+        },
+    };
+}
+/** Audit S6: the Python SDK's name, so docs and examples can be written once. Called, not `new`ed. */
+export const BlackboxAgentHooks = blackboxAgentHooks;

package/dist/hooks/index.d.ts

@@ -0,0 +1,7 @@
+export { blackboxMiddleware } from "./ai-sdk.ts";
+export { BlackboxAgentHooks, blackboxAgentHooks } from "./claude-agent-sdk.ts";
+export { BlackboxCallbackHandler, type BlackboxCallbacks, blackboxCallbacks } from "./langchain.ts";
+export { type MemorySink, type TrackMemoryOptions, trackMemory } from "./memory.ts";
+export { attachBlackbox } from "./openai-agents.ts";
+export { llmIdsOf, wrapAnthropic, wrapBedrock, wrapGemini, wrapOpenAI } from "./providers.ts";
+export { type EventSink, llmIds } from "./shared.ts";

package/dist/hooks/index.js

@@ -0,0 +1,10 @@
+// Framework hooks (spec/sdk.md §5): framework callbacks → SDK session events. Agent-asserted structure
+// only; every callback is wrapped so a hook can never break the framework. Mirrors
+// sdks/python/src/zanii_blackbox/hooks/.
+export { blackboxMiddleware } from "./ai-sdk.js";
+export { BlackboxAgentHooks, blackboxAgentHooks } from "./claude-agent-sdk.js";
+export { BlackboxCallbackHandler, blackboxCallbacks } from "./langchain.js";
+export { trackMemory } from "./memory.js";
+export { attachBlackbox } from "./openai-agents.js";
+export { llmIdsOf, wrapAnthropic, wrapBedrock, wrapGemini, wrapOpenAI } from "./providers.js";
+export { llmIds } from "./shared.js";

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 {};