darwin-langgraph 0.2.0-alpha.1 → 0.4.0-alpha.1

package/dist/darwin-accumulating-annotation.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Surface 9 (V0.4) — `darwinAccumulatingAnnotation(extra?)`.
+ *
+ * Variant of {@link darwinAnnotation} that REPLACES the singleton
+ * `darwinTrajectory: ExecutionTrace | undefined` channel with an
+ * accumulating `darwinTrajectories: ExecutionTrace[]` channel — every
+ * node write appends, the channel never overwrites.
+ *
+ * Use this when you orchestrate multiple Darwin nodes in a single graph
+ * (fan-out, sequential pipeline, supervisor pattern) and want ALL
+ * trajectories preserved in graph state for end-of-run analysis without
+ * having to declare a separate `*Trace` channel per node manually.
+ *
+ * The matching `trajectoryKey` you pass to each `createDarwinNode(...)`
+ * call is `"darwinTrajectories"`. The reducer accepts EITHER a single
+ * `ExecutionTrace` (matching the bare {@link createDarwinNode} contract)
+ * OR an `ExecutionTrace[]` (lets advanced users batch-append from a
+ * worker). Both paths flatten into the same accumulator array.
+ *
+ * @example
+ * ```ts
+ * import {
+ *   createDarwinNode,
+ *   darwinAccumulatingAnnotation,
+ * } from "darwin-langgraph";
+ * import { StateGraph } from "@langchain/langgraph";
+ *
+ * const State = darwinAccumulatingAnnotation();
+ *
+ * const graph = new StateGraph(State)
+ *   .addNode("research", createDarwinNode(researcher, {
+ *     trajectoryKey: "darwinTrajectories",
+ *   }))
+ *   .addNode("critique", createDarwinNode(critic, {
+ *     trajectoryKey: "darwinTrajectories",
+ *     taskKey: "output",
+ *   }))
+ *   .addEdge("__start__", "research")
+ *   .addEdge("research", "critique")
+ *   .compile();
+ *
+ * const result = await graph.invoke({ task: "What is GEPA?" });
+ * console.log(`captured ${result.darwinTrajectories.length} trajectories`);
+ * // → captured 2 trajectories
+ * ```
+ *
+ * NEW V0.4 (S1235).
+ */
+import type { ExecutionTrace } from "darwin-agents";
+/**
+ * Tolerant accumulator reducer — accepts either a single
+ * `ExecutionTrace` (the shape `createDarwinNode` actually emits) or an
+ * `ExecutionTrace[]` (lets advanced users batch-append from a worker
+ * graph). Both paths flatten into the previous array.
+ *
+ * Pure, exported for testability and so advanced users can hand-roll
+ * their own `Annotation.Root` with the same semantics.
+ */
+export declare function darwinTrajectoryAccumulatorReducer(prev: ExecutionTrace[] | undefined, next: ExecutionTrace | ExecutionTrace[] | undefined): ExecutionTrace[];
+/**
+ * Channel spec for the accumulating trajectory variant — re-exported for
+ * power-users who want to spread it into their own `Annotation.Root`
+ * call manually. Mirrors the {@link getDarwinChannelSpec} pattern.
+ *
+ * NEW V0.4 (S1235).
+ */
+export declare function getDarwinAccumulatingChannelSpec(): {
+    task: import("@langchain/langgraph").LastValue<string>;
+    output: import("@langchain/langgraph").LastValue<string>;
+    darwinTrajectories: import("@langchain/langgraph").BaseChannel<ExecutionTrace[], ExecutionTrace[] | import("@langchain/langgraph").OverwriteValue<ExecutionTrace[]>, unknown>;
+};
+/**
+ * Build an `Annotation.Root` with `task` + `output` + accumulating
+ * `darwinTrajectories: ExecutionTrace[]` plus any extra channels.
+ */
+export declare function darwinAccumulatingAnnotation<Extra extends Record<string, any> = {}>(extra?: Extra): import("@langchain/langgraph").AnnotationRoot<{
+    task: import("@langchain/langgraph").LastValue<string>;
+    output: import("@langchain/langgraph").LastValue<string>;
+    darwinTrajectories: import("@langchain/langgraph").BaseChannel<ExecutionTrace[], ExecutionTrace[] | import("@langchain/langgraph").OverwriteValue<ExecutionTrace[]>, unknown>;
+} & Extra>;
+//# sourceMappingURL=darwin-accumulating-annotation.d.ts.map

package/dist/darwin-accumulating-annotation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"darwin-accumulating-annotation.d.ts","sourceRoot":"","sources":["../src/darwin-accumulating-annotation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAIpD;;;;;;;;GAQG;AACH,wBAAgB,kCAAkC,CAChD,IAAI,EAAE,cAAc,EAAE,GAAG,SAAS,EAClC,IAAI,EAAE,cAAc,GAAG,cAAc,EAAE,GAAG,SAAS,GAClD,cAAc,EAAE,CAoBlB;AAeD;;;;;;GAMG;AACH,wBAAgB,gCAAgC;;;;EAe/C;AAED;;;GAGG;AAEH,wBAAgB,4BAA4B,CAAC,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,EAAE,EACjF,KAAK,CAAC,EAAE,KAAK;;;;WAsBd"}

package/dist/darwin-accumulating-annotation.js

@@ -0,0 +1,144 @@
+/**
+ * Surface 9 (V0.4) — `darwinAccumulatingAnnotation(extra?)`.
+ *
+ * Variant of {@link darwinAnnotation} that REPLACES the singleton
+ * `darwinTrajectory: ExecutionTrace | undefined` channel with an
+ * accumulating `darwinTrajectories: ExecutionTrace[]` channel — every
+ * node write appends, the channel never overwrites.
+ *
+ * Use this when you orchestrate multiple Darwin nodes in a single graph
+ * (fan-out, sequential pipeline, supervisor pattern) and want ALL
+ * trajectories preserved in graph state for end-of-run analysis without
+ * having to declare a separate `*Trace` channel per node manually.
+ *
+ * The matching `trajectoryKey` you pass to each `createDarwinNode(...)`
+ * call is `"darwinTrajectories"`. The reducer accepts EITHER a single
+ * `ExecutionTrace` (matching the bare {@link createDarwinNode} contract)
+ * OR an `ExecutionTrace[]` (lets advanced users batch-append from a
+ * worker). Both paths flatten into the same accumulator array.
+ *
+ * @example
+ * ```ts
+ * import {
+ *   createDarwinNode,
+ *   darwinAccumulatingAnnotation,
+ * } from "darwin-langgraph";
+ * import { StateGraph } from "@langchain/langgraph";
+ *
+ * const State = darwinAccumulatingAnnotation();
+ *
+ * const graph = new StateGraph(State)
+ *   .addNode("research", createDarwinNode(researcher, {
+ *     trajectoryKey: "darwinTrajectories",
+ *   }))
+ *   .addNode("critique", createDarwinNode(critic, {
+ *     trajectoryKey: "darwinTrajectories",
+ *     taskKey: "output",
+ *   }))
+ *   .addEdge("__start__", "research")
+ *   .addEdge("research", "critique")
+ *   .compile();
+ *
+ * const result = await graph.invoke({ task: "What is GEPA?" });
+ * console.log(`captured ${result.darwinTrajectories.length} trajectories`);
+ * // → captured 2 trajectories
+ * ```
+ *
+ * NEW V0.4 (S1235).
+ */
+import { Annotation } from "@langchain/langgraph";
+import { getDarwinChannelSpec } from "./darwin-annotation.js";
+/**
+ * Tolerant accumulator reducer — accepts either a single
+ * `ExecutionTrace` (the shape `createDarwinNode` actually emits) or an
+ * `ExecutionTrace[]` (lets advanced users batch-append from a worker
+ * graph). Both paths flatten into the previous array.
+ *
+ * Pure, exported for testability and so advanced users can hand-roll
+ * their own `Annotation.Root` with the same semantics.
+ */
+export function darwinTrajectoryAccumulatorReducer(prev, next) {
+    const base = prev ?? [];
+    if (next === undefined || next === null)
+        return base;
+    // R1 P0-2 fix (S1235): forward-compat — match `isExecutionTrace` and
+    // accept `version >= 1` rather than strict `=== 1`. The mismatch let
+    // v=2 trajectories through the DarwinCallbackHandler.onTrajectory
+    // hook but silently dropped them on the accumulator side.
+    const isTrace = (t) => {
+        if (!t || typeof t !== "object")
+            return false;
+        const v = t.version;
+        return typeof v === "number" && Number.isFinite(v) && v >= 1;
+    };
+    if (Array.isArray(next)) {
+        const valid = next.filter(isTrace);
+        if (valid.length === 0)
+            return base;
+        return [...base, ...valid];
+    }
+    if (!isTrace(next))
+        return base;
+    return [...base, next];
+}
+/**
+ * Reserved channel keys the accumulating annotation owns. Used by
+ * {@link darwinAccumulatingAnnotation} to fail loud when an `extra`
+ * spread would silently overwrite a Darwin-managed channel.
+ *
+ * NEW V0.4 (R1 P2-2 fix, S1235).
+ */
+const DARWIN_ACCUMULATING_RESERVED_KEYS = new Set([
+    "task",
+    "output",
+    "darwinTrajectories",
+]);
+/**
+ * Channel spec for the accumulating trajectory variant — re-exported for
+ * power-users who want to spread it into their own `Annotation.Root`
+ * call manually. Mirrors the {@link getDarwinChannelSpec} pattern.
+ *
+ * NEW V0.4 (S1235).
+ */
+export function getDarwinAccumulatingChannelSpec() {
+    // Take task + output from the base spec but DROP the singleton
+    // darwinTrajectory channel — callers using this annotation want the
+    // accumulator under the plural key.
+    const base = getDarwinChannelSpec();
+    // Surgical: pluck task + output, drop darwinTrajectory.
+    const { task, output } = base;
+    return {
+        task,
+        output,
+        darwinTrajectories: Annotation({
+            reducer: darwinTrajectoryAccumulatorReducer,
+            default: () => [],
+        }),
+    };
+}
+/**
+ * Build an `Annotation.Root` with `task` + `output` + accumulating
+ * `darwinTrajectories: ExecutionTrace[]` plus any extra channels.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function darwinAccumulatingAnnotation(extra) {
+    // R1 P2-2 fix (S1235): fail loud if `extra` would silently overwrite
+    // a Darwin-managed channel. Before this guard a caller passing
+    // `extra = { darwinTrajectories: customAnnotation }` silently replaced
+    // the accumulator and broke the contract advertised by the function
+    // name without a single warning.
+    if (extra) {
+        for (const key of Object.keys(extra)) {
+            if (DARWIN_ACCUMULATING_RESERVED_KEYS.has(key)) {
+                throw new Error(`darwinAccumulatingAnnotation: "extra" cannot redefine the ` +
+                    `Darwin-managed channel "${key}". Reserved keys: ` +
+                    `${[...DARWIN_ACCUMULATING_RESERVED_KEYS].join(", ")}.`);
+            }
+        }
+    }
+    return Annotation.Root({
+        ...getDarwinAccumulatingChannelSpec(),
+        ...(extra ?? {}),
+    });
+}
+//# sourceMappingURL=darwin-accumulating-annotation.js.map

package/dist/darwin-accumulating-annotation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"darwin-accumulating-annotation.js","sourceRoot":"","sources":["../src/darwin-accumulating-annotation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAGlD,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAE9D;;;;;;;;GAQG;AACH,MAAM,UAAU,kCAAkC,CAChD,IAAkC,EAClC,IAAmD;IAEnD,MAAM,IAAI,GAAG,IAAI,IAAI,EAAE,CAAC;IACxB,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACrD,qEAAqE;IACrE,qEAAqE;IACrE,kEAAkE;IAClE,0DAA0D;IAC1D,MAAM,OAAO,GAAG,CAAC,CAAU,EAAuB,EAAE;QAClD,IAAI,CAAC,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ;YAAE,OAAO,KAAK,CAAC;QAC9C,MAAM,CAAC,GAAI,CAA2B,CAAC,OAAO,CAAC;QAC/C,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC/D,CAAC,CAAC;IAEF,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QACxB,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QACnC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QACpC,OAAO,CAAC,GAAG,IAAI,EAAE,GAAG,KAAK,CAAC,CAAC;IAC7B,CAAC;IACD,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAChC,OAAO,CAAC,GAAG,IAAI,EAAE,IAAI,CAAC,CAAC;AACzB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,iCAAiC,GAAG,IAAI,GAAG,CAAC;IAChD,MAAM;IACN,QAAQ;IACR,oBAAoB;CACrB,CAAC,CAAC;AAEH;;;;;;GAMG;AACH,MAAM,UAAU,gCAAgC;IAC9C,+DAA+D;IAC/D,oEAAoE;IACpE,oCAAoC;IACpC,MAAM,IAAI,GAAG,oBAAoB,EAAE,CAAC;IACpC,wDAAwD;IACxD,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IAC9B,OAAO;QACL,IAAI;QACJ,MAAM;QACN,kBAAkB,EAAE,UAAU,CAAmB;YAC/C,OAAO,EAAE,kCAAkC;YAC3C,OAAO,EAAE,GAAG,EAAE,CAAC,EAAE;SAClB,CAAC;KACH,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,8DAA8D;AAC9D,MAAM,UAAU,4BAA4B,CAC1C,KAAa;IAEb,qEAAqE;IACrE,+DAA+D;IAC/D,uEAAuE;IACvE,oEAAoE;IACpE,iCAAiC;IACjC,IAAI,KAAK,EAAE,CAAC;QACV,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YACrC,IAAI,iCAAiC,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC/C,MAAM,IAAI,KAAK,CACb,4DAA4D;oBAC1D,2BAA2B,GAAG,oBAAoB;oBAClD,GAAG,CAAC,GAAG,iCAAiC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAC1D,CAAC;YACJ,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,UAAU,CAAC,IAAI,CAAC;QACrB,GAAG,gCAAgC,EAAE;QACrC,GAAG,CAAC,KAAK,IAAK,EAAY,CAAC;KAC5B,CAAC,CAAC;AACL,CAAC"}

package/dist/darwin-callback-handler.d.ts

@@ -52,6 +52,102 @@
 import { BaseCallbackHandler } from "@langchain/core/callbacks/base";
 import type { ChainValues } from "@langchain/core/utils/types";
 import type { DarwinEvolutionOptions } from "./with-darwin-evolution.js";
+/**
+ * Highest `ExecutionTrace.version` this handler natively understands.
+ * The forward-compat guard in {@link isExecutionTrace} warns once for
+ * higher versions but still emits them (structural shape covers the
+ * required fields) so a Darwin upgrade ahead of the adapter doesn't
+ * silently drop trajectories.
+ *
+ * NEW V0.4 (S1235).
+ */
+export declare const MAX_KNOWN_TRACE_VERSION = 1;
+/**
+ * Surface 8 (V0.4) — `DarwinToolEvent`.
+ *
+ * Emitted by {@link DarwinCallbackHandler.onToolEvent} whenever LangGraph
+ * surfaces a tool-chain start, end, or error inside a tracked node-chain.
+ * Lets consumers correlate per-tool spans with the parent agent trajectory
+ * BEFORE the chain completes — useful for live OTEL span emission,
+ * progress UIs, and abort-on-tool-failure logic.
+ *
+ * Phase semantics:
+ *   - `"start"` — populated `input`, no `output`/`error`. Fired from
+ *     `handleToolStart`.
+ *   - `"end"` — populated `output`, no `error`. Fired from `handleToolEnd`.
+ *   - `"error"` — populated `error`, no `output`. Fired from `handleToolError`.
+ *
+ * NEW V0.4 (S1235).
+ */
+export interface DarwinToolEvent {
+    /** Node name the tool ran under (resolved from `runIdToName` via the
+     * tool-chain's parentRunId — the chain runId from `handleChainStart`). */
+    nodeName: string;
+    /** Darwin agent name (from `nodeMap`). */
+    agentName: string;
+    /** Tool name LangChain passed in `handleToolStart` (often the function name). */
+    toolName: string;
+    /** Phase of the tool-chain event. */
+    phase: "start" | "end" | "error";
+    /** LangChain runId of this tool-chain (NOT the parent chain). */
+    runId: string;
+    /** LangChain parentRunId — chain runId of the node the tool ran under. */
+    parentRunId: string;
+    /** Raw input arg passed to `handleToolStart`. Only present on phase=start. */
+    input?: string;
+    /** Raw output from `handleToolEnd`. Only present on phase=end. */
+    output?: unknown;
+    /** Error from `handleToolError`. Only present on phase=error. */
+    error?: Error;
+}
+/**
+ * V0.3 — extra options on top of `DarwinEvolutionOptions`. Pass to
+ * `new DarwinCallbackHandler({ ...opts, maxInFlightRuns })`.
+ *
+ * NEW V0.3 (S1187), extended V0.4 (S1235).
+ */
+export interface DarwinCallbackHandlerOptions extends DarwinEvolutionOptions {
+    /**
+     * Maximum number of in-flight `runId → nodeName` mappings the handler
+     * holds at once. If `handleChainEnd` / `handleChainError` never fires
+     * (LangGraph internal bug, OS-level kill of the worker mid-invoke,
+     * etc.) the map would otherwise grow without bound and leak memory.
+     *
+     * When the limit is exceeded, the OLDEST entry is evicted and a
+     * one-shot warning is logged. Default: 1024 (enough for typical
+     * fan-out patterns with safety margin, small enough to surface real
+     * leaks within minutes of an incident).
+     *
+     * Set to `Infinity` to opt out — discouraged in production.
+     */
+    maxInFlightRuns?: number;
+    /**
+     * V0.4 — soft cap on the serialised trajectory size before it is
+     * surfaced through `onTrajectory`. When a trajectory's `JSON.stringify`
+     * length exceeds `maxTrajectoryBytes`, the handler emits a one-shot
+     * warning and replaces the `trajectory` field on the event with a
+     * structurally-compatible BUT minimal stub (same `version`, empty
+     * `toolCalls` and `errors`, original counts and capturedAt preserved).
+     * Downstream consumers can detect the swap by inspecting
+     * `event.trajectoryTruncated === true`.
+     *
+     * Default: `262_144` (256 KiB). Set to `Infinity` to opt out.
+     *
+     * NEW V0.4 (S1235).
+     */
+    maxTrajectoryBytes?: number;
+    /**
+     * V0.4 — Fired for every tool-chain start / end / error observed inside
+     * a tracked node-chain. Use this to emit per-tool OTEL spans, drive a
+     * progress UI, or abort downstream work on a tool failure.
+     *
+     * Errors thrown inside `onToolEvent` are swallowed with a single warn
+     * per handler instance — never breaks the graph.
+     *
+     * NEW V0.4 (S1235).
+     */
+    onToolEvent?: (event: DarwinToolEvent) => void | Promise<void>;
+}
 /**
  * LangChain `BaseCallbackHandler` that listens for LangGraph node-chain
  * events and dispatches Darwin trajectory hooks. Pass it via the
@@ -63,9 +159,49 @@ export declare class DarwinCallbackHandler extends BaseCallbackHandler {
     readonly awaitHandlers = false;
     private readonly resolved;
     private readonly onTrajectory;
+    private readonly onToolEvent;
+    /**
+     * runId → in-flight run state. Map preserves insertion order so the
+     * oldest entry is always at `.keys().next().value` for LRU eviction
+     * when the cap is exceeded (V0.3 hung-invoke guard).
+     */
     private readonly runIdToName;
+    /**
+     * V0.4 (R1 P1-1 fix, S1235) — `toolRunId → toolName` cache populated
+     * from `handleToolStart` and consumed by `handleToolEnd` /
+     * `handleToolError`. LangChain v0.3 `handleToolEnd` does NOT reliably
+     * carry the tool name in its signature (the slot was repurposed
+     * across releases); reading `output.name` only works for some shapes
+     * and yields "<anonymous-tool>" for the common ToolNode case.
+     */
+    private readonly toolRunIdToName;
+    /**
+     * V0.4 (R1 P1-1 fix, S1235) — pending callbacks keyed by parent chain
+     * runId so we can also restore the chain's tool name at end-time even
+     * after the `toolRunIdToName` entry is cleaned up.
+     */
+    private readonly maxInFlightRuns;
+    /** V0.4 — byte cap before trajectory replacement. */
+    private readonly maxTrajectoryBytes;
+    /**
+     * V0.4 (R1 P1-1 fix) — also cap the tool-name cache. Default matches
+     * `maxInFlightRuns` since tool runs are children of chain runs.
+     */
+    private readonly maxInFlightToolRuns;
+    /**
+     * Pending trajectory dispatches keyed by chain runId. When a chain
+     * ends with tools still in flight we hold the dispatch closure here
+     * and fire it from the LAST `handleToolEnd` / `handleToolError`.
+     *
+     * V0.4 (R1 P1-4 fix, S1235).
+     */
+    private readonly pendingTrajectoryDispatch;
     private warned;
-    constructor(opts: DarwinEvolutionOptions);
+    private evictionWarned;
+    private toolWarned;
+    /** V0.4 — once-per-handler warn for trajectory size cap. */
+    private trajectoryTruncatedWarned;
+    constructor(opts: DarwinCallbackHandlerOptions);
     /**
      * Capture the run-id → node-name mapping.
      *
@@ -76,7 +212,7 @@ export declare class DarwinCallbackHandler extends BaseCallbackHandler {
      * `BaseCallbackHandler` d.ts is undefined for LangGraph chains at
      * runtime — we keep it as a fallback for non-LangGraph chains.
      */
-    handleChainStart(_chain: unknown, _inputs: ChainValues, runId: string, _runType?: string, _tags?: string[], metadata?: Record<string, unknown>, runName?: string, _parentRunId?: string, _extra?: Record<string, unknown>): void;
+    handleChainStart(_chain: unknown, _inputs: ChainValues, runId: string, _runType?: string, _tags?: string[], metadata?: Record<string, unknown>, runName?: string, parentRunId?: string, _extra?: Record<string, unknown>): void;
     /**
      * When a node-chain finishes, look up its name, locate the matching
      * trajectory in `outputs`, and dispatch onTrajectory.
@@ -94,7 +230,30 @@ export declare class DarwinCallbackHandler extends BaseCallbackHandler {
      * the hook on error — the trajectory is by definition incomplete.
      */
     handleChainError(_err: Error, runId: string, _parentRunId?: string): void;
+    /**
+     * V0.4 (S1235) — tool-chain start event. LangGraph fires `handleToolStart`
+     * for every tool-invocation a node performs (whether via `ToolNode`,
+     * `createReactAgent`, or a custom tool-call dispatcher). We use the
+     * `parentRunId` slot to associate the tool with the tracking node and
+     * emit a `DarwinToolEvent` so consumers can build per-tool OTEL spans
+     * or progress UIs.
+     *
+     * If `parentRunId` is missing OR the parent is not a tracked node, the
+     * tool event is silently dropped — the handler never surfaces unmapped
+     * activity (consistent with the chain-side `resolved.has(nodeName)` gate).
+     */
+    handleToolStart(_tool: unknown, input: string, runId: string, parentRunId?: string, _tags?: string[], _metadata?: Record<string, unknown>, _runType?: string, name?: string): void;
+    /**
+     * V0.4 (S1235) — tool-chain end event.
+     */
+    handleToolEnd(output: unknown, runId: string, parentRunId?: string): void;
+    /**
+     * V0.4 (S1235) — tool-chain error event.
+     */
+    handleToolError(err: Error, runId: string, parentRunId?: string): void;
+    private dispatchToolEvent;
     private swallow;
+    private swallowTool;
     /**
      * Helper for tests + debug introspection — returns how many in-flight
      * chain runs we are currently tracking. Should be 0 between

package/dist/darwin-callback-handler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"darwin-callback-handler.d.ts","sourceRoot":"","sources":["../src/darwin-callback-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAC;AACrE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAI/D,OAAO,KAAK,EACV,sBAAsB,EAGvB,MAAM,4BAA4B,CAAC;AAqDpC;;;;;GAKG;AACH,qBAAa,qBAAsB,SAAQ,mBAAmB;IAC5D,SAAyB,IAAI,2BAA2B;IACxD,SAAyB,aAAa,SAAS;IAE/C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAoC;IAC7D,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAyC;IACtE,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAkC;IAC9D,OAAO,CAAC,MAAM,CAAS;gBAEX,IAAI,EAAE,sBAAsB;IAYxC;;;;;;;;;OASG;IACM,gBAAgB,CACvB,MAAM,EAAE,OAAO,EACf,OAAO,EAAE,WAAW,EACpB,KAAK,EAAE,MAAM,EACb,QAAQ,CAAC,EAAE,MAAM,EACjB,KAAK,CAAC,EAAE,MAAM,EAAE,EAChB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClC,OAAO,CAAC,EAAE,MAAM,EAChB,YAAY,CAAC,EAAE,MAAM,EACrB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,IAAI;IAoBP;;;;;;;;OAQG;IACM,cAAc,CACrB,OAAO,EAAE,WAAW,EACpB,KAAK,EAAE,MAAM,EACb,YAAY,CAAC,EAAE,MAAM,EACrB,KAAK,CAAC,EAAE,MAAM,EAAE,EAChB,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GACjC,IAAI;IAmCP;;;OAGG;IACM,gBAAgB,CACvB,IAAI,EAAE,KAAK,EACX,KAAK,EAAE,MAAM,EACb,YAAY,CAAC,EAAE,MAAM,GACpB,IAAI;IAIP,OAAO,CAAC,OAAO;IAaf;;;;OAIG;IACI,gBAAgB,IAAI,MAAM;CAGlC"}
+{"version":3,"file":"darwin-callback-handler.d.ts","sourceRoot":"","sources":["../src/darwin-callback-handler.ts"],"names":[],"mappings":"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"}