darwin-langgraph 0.1.0-alpha.1 → 0.3.0-alpha.1

package/dist/darwin-callback-handler.js

@@ -0,0 +1,261 @@
+/**
+ * Surface 4 (V0.2) — `DarwinCallbackHandler`.
+ *
+ * Drop-in replacement for {@link withDarwinEvolution} that uses
+ * LangChain's canonical `BaseCallbackHandler` mechanism instead of
+ * monkey-patching `graph.invoke` / `graph.stream`. The same trajectory
+ * hook fires, the same `nodeMap` routing applies, but the integration
+ * is now LangGraph-native — no method overwrites, no concurrent-invoke
+ * Set<symbol> dance, no streamMode gymnastics.
+ *
+ * Usage:
+ * ```ts
+ * import { DarwinCallbackHandler } from "darwin-langgraph";
+ *
+ * const handler = new DarwinCallbackHandler({
+ *   nodeMap: { research: "researcher" },
+ *   onTrajectory: (event) => {
+ *     console.log(event.nodeName, event.trajectory.toolCalls.length);
+ *   },
+ * });
+ *
+ * const result = await graph.invoke(
+ *   { task: "What is GEPA?" },
+ *   { callbacks: [handler] },
+ * );
+ * ```
+ *
+ * Design notes (S1185 V0.2):
+ *   - **runId → runName mapping.** LangChain invokes `handleChainStart`
+ *     with the `runName` arg (the node name in LangGraph's case) and
+ *     a unique `runId`. We cache that mapping. On `handleChainEnd` we
+ *     look up the name, find the matching `nodeMap` entry, and dispatch
+ *     `onTrajectory`.
+ *   - **Fire-and-forget.** Like the v0.1 monkey-patch wrapper, hook
+ *     errors are swallowed with one warn-once per handler instance.
+ *   - **No mutation of LangGraph internals.** This handler never touches
+ *     `graph.invoke` or `graph.stream` — registering it via the standard
+ *     `{ callbacks: [...] }` option is the only side effect, which is
+ *     LangChain's documented integration point (matches Langfuse,
+ *     Braintrust, LangSmith handler patterns).
+ *   - **Stream-mode-agnostic.** Works identically with `invoke`,
+ *     `stream` (any streamMode), and `streamEvents` because the chain
+ *     callbacks fire regardless of how the consumer iterates.
+ *   - **Concurrent runs work natively.** LangChain's runId is unique
+ *     per call — no shared-counter race condition is possible.
+ *   - **Backwards compat.** `withDarwinEvolution` from v0.1 still works
+ *     (marked `@deprecated`) and produces the same `DarwinTrajectoryEvent`
+ *     payload shape. Migration is one line: replace
+ *     `withDarwinEvolution(graph, opts)` with
+ *     `graph.invoke(input, { callbacks: [new DarwinCallbackHandler(opts)] })`.
+ */
+import { BaseCallbackHandler } from "@langchain/core/callbacks/base";
+import { DarwinEvolutionHookError } from "./errors.js";
+/** Default cap. Aligned with reasonable LangGraph fan-out (~1k nodes / minute). */
+const DEFAULT_MAX_IN_FLIGHT_RUNS = 1024;
+function isExecutionTrace(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const v = value;
+    // R1 V0.2 Critic Finding 2 (S1185): require shape-tightness, not just
+    // version. Downstream consumers (e.g. toOtelAttributes) read
+    // `toolCalls.length` directly — a malformed trace with missing arrays
+    // would crash there. Guard explicitly.
+    return (v.version === 1 &&
+        Array.isArray(v.toolCalls) &&
+        Array.isArray(v.errors));
+}
+function normaliseNodeMap(nodeMap, defaultKey) {
+    const resolved = new Map();
+    for (const [nodeName, entry] of Object.entries(nodeMap)) {
+        if (typeof entry === "string") {
+            resolved.set(nodeName, { agentName: entry, trajectoryKey: defaultKey });
+        }
+        else if (entry !== null &&
+            typeof entry === "object" &&
+            typeof entry.agentName === "string" &&
+            typeof entry.trajectoryKey === "string") {
+            resolved.set(nodeName, {
+                agentName: entry.agentName,
+                trajectoryKey: entry.trajectoryKey,
+            });
+        }
+        else {
+            throw new DarwinEvolutionHookError(`DarwinCallbackHandler: nodeMap entry for "${nodeName}" must be a string or ` +
+                `{ agentName, trajectoryKey }, got ${typeof entry}.`);
+        }
+    }
+    return resolved;
+}
+/**
+ * LangChain `BaseCallbackHandler` that listens for LangGraph node-chain
+ * events and dispatches Darwin trajectory hooks. Pass it via the
+ * standard `{ callbacks: [...] }` option to any `invoke`/`stream`/`streamEvents`
+ * call on a compiled `StateGraph`.
+ */
+export class DarwinCallbackHandler extends BaseCallbackHandler {
+    name = "DarwinCallbackHandler";
+    awaitHandlers = false;
+    resolved;
+    onTrajectory;
+    /**
+     * 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).
+     */
+    runIdToName = new Map();
+    maxInFlightRuns;
+    warned = false;
+    evictionWarned = false;
+    constructor(opts) {
+        super();
+        if (!opts || !opts.nodeMap || Object.keys(opts.nodeMap).length === 0) {
+            throw new DarwinEvolutionHookError("DarwinCallbackHandler: opts.nodeMap is required and must contain at least one entry.");
+        }
+        const defaultKey = opts.defaultTrajectoryKey ?? "darwinTrajectory";
+        this.resolved = normaliseNodeMap(opts.nodeMap, defaultKey);
+        this.onTrajectory = opts.onTrajectory;
+        // V0.3 (S1187): hung-invoke guard. NaN / negative / non-number falls
+        // back to default. Infinity disables the cap (opt-out).
+        const raw = opts.maxInFlightRuns;
+        if (raw === Infinity) {
+            this.maxInFlightRuns = Infinity;
+        }
+        else if (typeof raw === "number" && Number.isFinite(raw) && raw > 0) {
+            this.maxInFlightRuns = Math.floor(raw);
+        }
+        else {
+            this.maxInFlightRuns = DEFAULT_MAX_IN_FLIGHT_RUNS;
+        }
+    }
+    /**
+     * Capture the run-id → node-name mapping.
+     *
+     * Implementation note (S1185 V0.2 — live-debug against @langchain/langgraph@1.3.x):
+     * `metadata.langgraph_node` is the stable, reliable source for the
+     * StateGraph node name. LangGraph populates it on every node-chain
+     * invocation. The `runName` parameter slot in `@langchain/core`'s
+     * `BaseCallbackHandler` d.ts is undefined for LangGraph chains at
+     * runtime — we keep it as a fallback for non-LangGraph chains.
+     */
+    handleChainStart(_chain, _inputs, runId, _runType, _tags, metadata, runName, parentRunId, _extra) {
+        // Primary source: metadata.langgraph_node (set by LangGraph internals).
+        let nodeName;
+        if (metadata && typeof metadata === "object") {
+            const m = metadata;
+            if (typeof m["langgraph_node"] === "string") {
+                nodeName = m["langgraph_node"];
+            }
+        }
+        // Fallback: runName parameter (for non-LangGraph integrations).
+        if (!nodeName && typeof runName === "string" && runName.length > 0) {
+            nodeName = runName;
+        }
+        if (!nodeName)
+            return;
+        // Only track names that map to a known node. Reduces memory and
+        // makes lookup in handleChainEnd a simple `.has()` check.
+        if (!this.resolved.has(nodeName))
+            return;
+        // V0.3 (S1187): hung-invoke guard. If we are about to exceed the cap
+        // AND the runId is genuinely new (not a re-fire), evict the oldest
+        // entry. Map iteration order is insertion order — the first key is
+        // the oldest. Warn once per handler instance so a real leak shows up
+        // in logs without spamming.
+        if (this.maxInFlightRuns !== Infinity &&
+            !this.runIdToName.has(runId) &&
+            this.runIdToName.size >= this.maxInFlightRuns) {
+            const oldest = this.runIdToName.keys().next().value;
+            if (oldest !== undefined) {
+                this.runIdToName.delete(oldest);
+            }
+            if (!this.evictionWarned) {
+                this.evictionWarned = true;
+                console.warn(`[darwin-langgraph] DarwinCallbackHandler: in-flight runs exceeded ` +
+                    `${this.maxInFlightRuns} — evicting oldest entry. This usually ` +
+                    `means handleChainEnd / handleChainError did not fire for some ` +
+                    `runs (worker crash, parent invoke aborted mid-flight, or ` +
+                    `LangGraph internal bug). Subsequent evictions are silent.`);
+            }
+        }
+        this.runIdToName.set(runId, {
+            nodeName,
+            parentRunId: typeof parentRunId === "string" ? parentRunId : undefined,
+        });
+    }
+    /**
+     * When a node-chain finishes, look up its name, locate the matching
+     * trajectory in `outputs`, and dispatch onTrajectory.
+     *
+     * `outputs` carries the state update the node returned — which may be
+     * a partial state (just the new keys). When the node was wrapped via
+     * {@link createDarwinNode}, the trajectoryKey lives directly on that
+     * partial state under its configured name.
+     */
+    handleChainEnd(outputs, runId, _parentRunId, _tags, _kwargs) {
+        const inFlight = this.runIdToName.get(runId);
+        if (!inFlight)
+            return;
+        // One-shot cleanup of the mapping so completed runs don't leak.
+        // R1 V0.2 Critic Finding 1 (S1185): the `runIdToName.delete` here
+        // is the ONLY dedup we need — LangGraph guarantees `handleChainEnd`
+        // fires exactly once per `runId`, and after deletion any second
+        // call returns early at `if (!inFlight)`. The pre-V0.2 `firedRuns`
+        // Set was redundant AND leaked unbounded — removed.
+        this.runIdToName.delete(runId);
+        if (!this.onTrajectory)
+            return;
+        const entry = this.resolved.get(inFlight.nodeName);
+        if (!entry)
+            return;
+        if (outputs === null || typeof outputs !== "object")
+            return;
+        const trajectory = outputs[entry.trajectoryKey];
+        if (!isExecutionTrace(trajectory))
+            return;
+        const frozen = Object.freeze({ ...outputs });
+        // V0.3 (S1187): propagate runId + parentRunId so OTEL exporters,
+        // Langfuse, LangSmith, etc. can rebuild the span hierarchy from the
+        // event payload alone (no separate runId-tracking side-channel).
+        const event = {
+            nodeName: inFlight.nodeName,
+            agentName: entry.agentName,
+            trajectory,
+            finalState: frozen,
+            runId,
+            ...(inFlight.parentRunId !== undefined ? { parentRunId: inFlight.parentRunId } : {}),
+        };
+        // Fire-and-forget. The handler base class supports async returns
+        // but we don't want to block the chain end on slow user callbacks.
+        void Promise.resolve()
+            .then(() => this.onTrajectory(event))
+            .catch((err) => this.swallow(err));
+    }
+    /**
+     * Forget the in-flight runId when a chain errors out. We don't fire
+     * the hook on error — the trajectory is by definition incomplete.
+     */
+    handleChainError(_err, runId, _parentRunId) {
+        this.runIdToName.delete(runId);
+    }
+    swallow(err) {
+        // R1 V0.2 Critic Finding 5 (S1185): do NOT short-circuit on falsy
+        // `err` — `throw 0` / `throw ""` / `throw null` from user callbacks
+        // should still surface in logs (silent-failure is worse than noisy).
+        if (this.warned)
+            return;
+        this.warned = true;
+        console.warn(`[darwin-langgraph] DarwinCallbackHandler.onTrajectory threw — swallowed. ` +
+            `Subsequent throws will be silent. Original error: ` +
+            `${err instanceof Error ? err.message : String(err)}`);
+    }
+    /**
+     * Helper for tests + debug introspection — returns how many in-flight
+     * chain runs we are currently tracking. Should be 0 between
+     * top-level invocations.
+     */
+    getInFlightCount() {
+        return this.runIdToName.size;
+    }
+}
+//# sourceMappingURL=darwin-callback-handler.js.map

package/dist/darwin-callback-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"darwin-callback-handler.js","sourceRoot":"","sources":["../src/darwin-callback-handler.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,70 @@
+/**
+ * Surface 6 (V0.2) — `darwinMessagesAnnotation(extra?)`.
+ *
+ * Variant of {@link darwinAnnotation} that also includes LangGraph's
+ * canonical `messages` channel (using `messagesStateReducer` from
+ * `@langchain/langgraph`). Use this when your graph mixes Darwin agents
+ * with `createReactAgent` / `MessagesAnnotation`-based prebuilt agents
+ * — they all read and write the same `messages` channel without
+ * channel-name conflicts.
+ *
+ * Layered channels:
+ *   - `task` (string, last-write-wins) — Darwin agent task input
+ *   - `output` (string, last-write-wins) — Darwin agent text output
+ *   - `darwinTrajectory` (ExecutionTrace | undefined) — captured trace
+ *   - `messages` (BaseMessage[], `messagesStateReducer`) — chat history
+ *
+ * Composable: any `extra` channels merge in.
+ *
+ * @example
+ * ```ts
+ * import { darwinMessagesAnnotation, createDarwinNode } from "darwin-langgraph";
+ * import { StateGraph } from "@langchain/langgraph";
+ * import { createReactAgent } from "@langchain/langgraph/prebuilt";
+ * import { ChatAnthropic } from "@langchain/anthropic";
+ *
+ * const State = darwinMessagesAnnotation();
+ *
+ * const planner = createReactAgent({
+ *   llm: new ChatAnthropic({ model: "claude-haiku-4-5" }),
+ *   tools: [],
+ * });
+ *
+ * const graph = new StateGraph(State)
+ *   .addNode("plan", planner)                        // writes to messages
+ *   .addNode("execute", createDarwinNode(myAgent))   // writes to output
+ *   .addEdge("__start__", "plan")
+ *   .addEdge("plan", "execute")
+ *   .compile();
+ * ```
+ *
+ * Design notes:
+ *   - **Same inference quirk as `darwinAnnotation`.** Return type is
+ *     inferred from `Annotation.Root`; the internal `LastValue` vs
+ *     `BaseChannel` union is opaque to it. Hand-typing triggers TS2741.
+ *   - **`messages` default is `[]`** — graphs that don't seed messages
+ *     in `invoke({ task: "..." })` still work.
+ */
+import type { BaseMessage } from "@langchain/core/messages";
+/**
+ * Spec for the `messages` channel — re-exported for power-users who want
+ * to spread it into their own `Annotation.Root` call manually.
+ *
+ * Return type inferred (same `LastValue<T>` vs `BaseChannel<T>` quirk
+ * documented on `getDarwinChannelSpec` — hand-typing triggers TS2741).
+ */
+export declare function getMessagesChannelSpec(): {
+    messages: import("@langchain/langgraph").BaseChannel<BaseMessage<import("@langchain/core/messages").MessageStructure<import("@langchain/core/messages").MessageToolSet>, import("@langchain/core/messages").MessageType>[], BaseMessage<import("@langchain/core/messages").MessageStructure<import("@langchain/core/messages").MessageToolSet>, import("@langchain/core/messages").MessageType>[] | import("@langchain/langgraph").OverwriteValue<BaseMessage<import("@langchain/core/messages").MessageStructure<import("@langchain/core/messages").MessageToolSet>, import("@langchain/core/messages").MessageType>[]>, unknown>;
+};
+/**
+ * Build an `Annotation.Root` with the three Darwin channels PLUS the
+ * canonical `messages` channel for interop with `createReactAgent` /
+ * `MessagesAnnotation`-based prebuilt agents.
+ */
+export declare function darwinMessagesAnnotation<Extra extends Record<string, any> = {}>(extra?: Extra): import("@langchain/langgraph").AnnotationRoot<{
+    messages: import("@langchain/langgraph").BaseChannel<BaseMessage<import("@langchain/core/messages").MessageStructure<import("@langchain/core/messages").MessageToolSet>, import("@langchain/core/messages").MessageType>[], BaseMessage<import("@langchain/core/messages").MessageStructure<import("@langchain/core/messages").MessageToolSet>, import("@langchain/core/messages").MessageType>[] | import("@langchain/langgraph").OverwriteValue<BaseMessage<import("@langchain/core/messages").MessageStructure<import("@langchain/core/messages").MessageToolSet>, import("@langchain/core/messages").MessageType>[]>, unknown>;
+    task: import("@langchain/langgraph").LastValue<string>;
+    output: import("@langchain/langgraph").LastValue<string>;
+    darwinTrajectory: import("@langchain/langgraph").BaseChannel<import("darwin-agents").ExecutionTrace | undefined, import("darwin-agents").ExecutionTrace | import("@langchain/langgraph").OverwriteValue<import("darwin-agents").ExecutionTrace | undefined> | undefined, unknown>;
+} & Extra>;
+//# sourceMappingURL=darwin-messages-annotation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"darwin-messages-annotation.d.ts","sourceRoot":"","sources":["../src/darwin-messages-annotation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAMH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAI5D;;;;;;GAMG;AACH,wBAAgB,sBAAsB;;EAOrC;AAED;;;;GAIG;AAEH,wBAAgB,wBAAwB,CAAC,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,EAAE,EAC7E,KAAK,CAAC,EAAE,KAAK;;;;;WAOd"}

package/dist/darwin-messages-annotation.js

@@ -0,0 +1,78 @@
+/**
+ * Surface 6 (V0.2) — `darwinMessagesAnnotation(extra?)`.
+ *
+ * Variant of {@link darwinAnnotation} that also includes LangGraph's
+ * canonical `messages` channel (using `messagesStateReducer` from
+ * `@langchain/langgraph`). Use this when your graph mixes Darwin agents
+ * with `createReactAgent` / `MessagesAnnotation`-based prebuilt agents
+ * — they all read and write the same `messages` channel without
+ * channel-name conflicts.
+ *
+ * Layered channels:
+ *   - `task` (string, last-write-wins) — Darwin agent task input
+ *   - `output` (string, last-write-wins) — Darwin agent text output
+ *   - `darwinTrajectory` (ExecutionTrace | undefined) — captured trace
+ *   - `messages` (BaseMessage[], `messagesStateReducer`) — chat history
+ *
+ * Composable: any `extra` channels merge in.
+ *
+ * @example
+ * ```ts
+ * import { darwinMessagesAnnotation, createDarwinNode } from "darwin-langgraph";
+ * import { StateGraph } from "@langchain/langgraph";
+ * import { createReactAgent } from "@langchain/langgraph/prebuilt";
+ * import { ChatAnthropic } from "@langchain/anthropic";
+ *
+ * const State = darwinMessagesAnnotation();
+ *
+ * const planner = createReactAgent({
+ *   llm: new ChatAnthropic({ model: "claude-haiku-4-5" }),
+ *   tools: [],
+ * });
+ *
+ * const graph = new StateGraph(State)
+ *   .addNode("plan", planner)                        // writes to messages
+ *   .addNode("execute", createDarwinNode(myAgent))   // writes to output
+ *   .addEdge("__start__", "plan")
+ *   .addEdge("plan", "execute")
+ *   .compile();
+ * ```
+ *
+ * Design notes:
+ *   - **Same inference quirk as `darwinAnnotation`.** Return type is
+ *     inferred from `Annotation.Root`; the internal `LastValue` vs
+ *     `BaseChannel` union is opaque to it. Hand-typing triggers TS2741.
+ *   - **`messages` default is `[]`** — graphs that don't seed messages
+ *     in `invoke({ task: "..." })` still work.
+ */
+import { Annotation, messagesStateReducer, } from "@langchain/langgraph";
+import { getDarwinChannelSpec } from "./darwin-annotation.js";
+/**
+ * Spec for the `messages` channel — re-exported for power-users who want
+ * to spread it into their own `Annotation.Root` call manually.
+ *
+ * Return type inferred (same `LastValue<T>` vs `BaseChannel<T>` quirk
+ * documented on `getDarwinChannelSpec` — hand-typing triggers TS2741).
+ */
+export function getMessagesChannelSpec() {
+    return {
+        messages: Annotation({
+            reducer: messagesStateReducer,
+            default: () => [],
+        }),
+    };
+}
+/**
+ * Build an `Annotation.Root` with the three Darwin channels PLUS the
+ * canonical `messages` channel for interop with `createReactAgent` /
+ * `MessagesAnnotation`-based prebuilt agents.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function darwinMessagesAnnotation(extra) {
+    return Annotation.Root({
+        ...getDarwinChannelSpec(),
+        ...getMessagesChannelSpec(),
+        ...(extra ?? {}),
+    });
+}
+//# sourceMappingURL=darwin-messages-annotation.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"darwin-messages-annotation.js","sourceRoot":"","sources":["../src/darwin-messages-annotation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAEH,OAAO,EACL,UAAU,EACV,oBAAoB,GACrB,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAE9D;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB;IACpC,OAAO;QACL,QAAQ,EAAE,UAAU,CAAgB;YAClC,OAAO,EAAE,oBAAoB;YAC7B,OAAO,EAAE,GAAG,EAAE,CAAC,EAAE;SAClB,CAAC;KACH,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,8DAA8D;AAC9D,MAAM,UAAU,wBAAwB,CACtC,KAAa;IAEb,OAAO,UAAU,CAAC,IAAI,CAAC;QACrB,GAAG,oBAAoB,EAAE;QACzB,GAAG,sBAAsB,EAAE;QAC3B,GAAG,CAAC,KAAK,IAAK,EAAY,CAAC;KAC5B,CAAC,CAAC;AACL,CAAC"}

package/dist/index.d.ts

@@ -37,11 +37,14 @@
  * console.log(result.output);
  * ```
  */
-export { createDarwinNode, type CreateDarwinNodeOptions, type DarwinNodeFn, } from "./create-darwin-node.js";
+export { createDarwinNode, type CreateDarwinNodeOptions, type DarwinNodeFn, type DarwinRunOptionsPassthrough, } from "./create-darwin-node.js";
 export { darwinAnnotation, getDarwinChannelSpec, lastWriteWinsTrajectoryReducer, } from "./darwin-annotation.js";
 export { withDarwinEvolution, type DarwinEvolutionOptions, type DarwinNodeMapEntry, type DarwinTrajectoryEvent, } from "./with-darwin-evolution.js";
+export { DarwinCallbackHandler, type DarwinCallbackHandlerOptions, } from "./darwin-callback-handler.js";
+export { toOtelAttributes, toolCallToOtelAttributes, type OtelAttributes, type ToOtelAttributesOptions, type ToolCallOtelOptions, } from "./to-otel-attributes.js";
+export { darwinMessagesAnnotation, getMessagesChannelSpec, } from "./darwin-messages-annotation.js";
 export { DarwinNodeError, DarwinEvolutionHookError } from "./errors.js";
 export type { AgentDefinition, DarwinExperiment, ExecutionTrace, MemoryProvider, RunResult, TraceToolCall, TraceTokenUsage, TraceTurnError, } from "./types.js";
 /** Adapter version — sync with `package.json` on every release. */
-export declare const VERSION = "0.1.0-alpha.1";
+export declare const VERSION = "0.3.0-alpha.1";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,OAAO,EACL,gBAAgB,EAChB,KAAK,uBAAuB,EAC5B,KAAK,YAAY,GAClB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,8BAA8B,GAC/B,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EACL,mBAAmB,EACnB,KAAK,sBAAsB,EAC3B,KAAK,kBAAkB,EACvB,KAAK,qBAAqB,GAC3B,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EAAE,eAAe,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAExE,YAAY,EACV,eAAe,EACf,gBAAgB,EAChB,cAAc,EACd,cAAc,EACd,SAAS,EACT,aAAa,EACb,eAAe,EACf,cAAc,GACf,MAAM,YAAY,CAAC;AAEpB,mEAAmE;AACnE,eAAO,MAAM,OAAO,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,OAAO,EACL,gBAAgB,EAChB,KAAK,uBAAuB,EAC5B,KAAK,YAAY,EACjB,KAAK,2BAA2B,GACjC,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,8BAA8B,GAC/B,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EACL,mBAAmB,EACnB,KAAK,sBAAsB,EAC3B,KAAK,kBAAkB,EACvB,KAAK,qBAAqB,GAC3B,MAAM,4BAA4B,CAAC;AAGpC,OAAO,EACL,qBAAqB,EACrB,KAAK,4BAA4B,GAClC,MAAM,8BAA8B,CAAC;AAGtC,OAAO,EACL,gBAAgB,EAChB,wBAAwB,EACxB,KAAK,cAAc,EACnB,KAAK,uBAAuB,EAC5B,KAAK,mBAAmB,GACzB,MAAM,yBAAyB,CAAC;AAGjC,OAAO,EACL,wBAAwB,EACxB,sBAAsB,GACvB,MAAM,iCAAiC,CAAC;AAEzC,OAAO,EAAE,eAAe,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAExE,YAAY,EACV,eAAe,EACf,gBAAgB,EAChB,cAAc,EACd,cAAc,EACd,SAAS,EACT,aAAa,EACb,eAAe,EACf,cAAc,GACf,MAAM,YAAY,CAAC;AAEpB,mEAAmE;AACnE,eAAO,MAAM,OAAO,kBAAkB,CAAC"}

package/dist/index.js

@@ -40,7 +40,13 @@
 export { createDarwinNode, } from "./create-darwin-node.js";
 export { darwinAnnotation, getDarwinChannelSpec, lastWriteWinsTrajectoryReducer, } from "./darwin-annotation.js";
 export { withDarwinEvolution, } from "./with-darwin-evolution.js";
+// V0.2 — LangChain-native callback handler (preferred over `withDarwinEvolution`)
+export { DarwinCallbackHandler, } from "./darwin-callback-handler.js";
+// V0.2 — OTEL GenAI Semantic Conventions mapping
+export { toOtelAttributes, toolCallToOtelAttributes, } from "./to-otel-attributes.js";
+// V0.2 — MessagesAnnotation interop for graphs mixing createReactAgent + createDarwinNode
+export { darwinMessagesAnnotation, getMessagesChannelSpec, } from "./darwin-messages-annotation.js";
 export { DarwinNodeError, DarwinEvolutionHookError } from "./errors.js";
 /** Adapter version — sync with `package.json` on every release. */
-export const VERSION = "0.1.0-alpha.1";
+export const VERSION = "0.3.0-alpha.1";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,OAAO,EACL,gBAAgB,GAGjB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,8BAA8B,GAC/B,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EACL,mBAAmB,GAIpB,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EAAE,eAAe,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAaxE,mEAAmE;AACnE,MAAM,CAAC,MAAM,OAAO,GAAG,eAAe,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,OAAO,EACL,gBAAgB,GAIjB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,8BAA8B,GAC/B,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EACL,mBAAmB,GAIpB,MAAM,4BAA4B,CAAC;AAEpC,kFAAkF;AAClF,OAAO,EACL,qBAAqB,GAEtB,MAAM,8BAA8B,CAAC;AAEtC,iDAAiD;AACjD,OAAO,EACL,gBAAgB,EAChB,wBAAwB,GAIzB,MAAM,yBAAyB,CAAC;AAEjC,0FAA0F;AAC1F,OAAO,EACL,wBAAwB,EACxB,sBAAsB,GACvB,MAAM,iCAAiC,CAAC;AAEzC,OAAO,EAAE,eAAe,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAaxE,mEAAmE;AACnE,MAAM,CAAC,MAAM,OAAO,GAAG,eAAe,CAAC"}

package/dist/to-otel-attributes.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Surface 5 (V0.2) — `toOtelAttributes(trajectory, opts?)`.
+ *
+ * Pure mapper from Darwin's `ExecutionTrace` to a flat
+ * `Record<string, string | number | boolean>` keyed by
+ * [OpenTelemetry GenAI Semantic Conventions](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/gen-ai/gen-ai-spans.md)
+ * attribute names — so any OTEL-compatible exporter (Langfuse,
+ * Braintrust, Honeycomb, Datadog, New Relic, Grafana) picks up the
+ * trace data without further mapping.
+ *
+ * Coverage:
+ *   - `gen_ai.operation.name` = `"invoke_agent"` (constant per OTEL
+ *     GenAI spec for agent-level operations).
+ *   - `gen_ai.agent.name` = `opts.agentName` (callers passes the
+ *     agent's logical name).
+ *   - `gen_ai.agent.id` = `opts.agentId` (optional UUID/run id).
+ *   - `gen_ai.usage.input_tokens` / `output_tokens` / `cache_read_tokens` /
+ *     `cache_creation_tokens` — only emitted when the upstream
+ *     trajectory captured token usage (i.e. provider reported it).
+ *   - `darwin.trajectory.tool_calls.count` (custom, non-OTEL — namespaced
+ *     under `darwin.*` to avoid colliding with future OTEL fields).
+ *   - `darwin.trajectory.text_blocks` / `turns` / `mcp_invocations` /
+ *     `errors.count` — same custom namespace.
+ *   - `darwin.trajectory.captured_at` — ISO string for traceability.
+ *
+ * Per OTEL GenAI spec we DO NOT emit `gen_ai.tool.call.arguments` /
+ * `gen_ai.tool.call.result` here — those are span-level attributes
+ * meant to be attached to per-tool-call spans, not the aggregate
+ * trajectory. Callers who need them should iterate `trajectory.toolCalls`
+ * and emit one child span per call.
+ *
+ * Design notes:
+ *   - **Sparse output.** Undefined fields stay out of the result rather
+ *     than appearing as `null` — keeps OTEL exporters from over-counting
+ *     missing-data buckets.
+ *   - **No allocation on hot path.** The function builds a single
+ *     object literal incrementally; no Map / Set / array intermediates.
+ *   - **Pure.** No side effects, no I/O, no Date.now() — fully
+ *     testable with deterministic inputs.
+ */
+import type { ExecutionTrace } from "darwin-agents";
+/** Options accepted by {@link toOtelAttributes}. */
+export interface ToOtelAttributesOptions {
+    /** Logical agent name. Maps to `gen_ai.agent.name`. */
+    agentName?: string;
+    /** Optional agent id (e.g. uuid or experiment id). Maps to `gen_ai.agent.id`. */
+    agentId?: string;
+    /**
+     * Custom namespace for Darwin-specific attributes that have no OTEL
+     * equivalent. Default: `"darwin"` → emits `darwin.trajectory.*`.
+     * Override for organisation-wide naming conventions (e.g. `"company.darwin"`).
+     */
+    customNamespace?: string;
+}
+/** Flat attribute bag matching OTEL's primitive-only attribute types. */
+export type OtelAttributes = Record<string, string | number | boolean>;
+/**
+ * Build the OTEL attribute bag for an `ExecutionTrace`.
+ *
+ * @example
+ * ```ts
+ * import { toOtelAttributes } from "darwin-langgraph";
+ *
+ * const attrs = toOtelAttributes(event.trajectory, {
+ *   agentName: event.agentName,
+ *   agentId: someExperimentId,
+ * });
+ * // attrs = {
+ * //   "gen_ai.operation.name": "invoke_agent",
+ * //   "gen_ai.agent.name": "researcher",
+ * //   "gen_ai.agent.id": "exp-2026-05-25-001",
+ * //   "gen_ai.usage.input_tokens": 1200,
+ * //   "gen_ai.usage.output_tokens": 340,
+ * //   "darwin.trajectory.tool_calls.count": 3,
+ * //   "darwin.trajectory.text_blocks": 2,
+ * //   "darwin.trajectory.turns": 4,
+ * //   "darwin.trajectory.mcp_invocations": 2,
+ * //   "darwin.trajectory.errors.count": 0,
+ * //   "darwin.trajectory.captured_at": "2026-05-25T08:00:00.000Z",
+ * // }
+ *
+ * // OTEL exporter usage (any tracer):
+ * span.setAttributes(attrs);
+ * ```
+ */
+export declare function toOtelAttributes(trajectory: ExecutionTrace, opts?: ToOtelAttributesOptions): OtelAttributes;
+/**
+ * Build per-tool-call OTEL attributes for each entry in
+ * `trajectory.toolCalls`. Use this to emit one child span per tool call
+ * under the parent agent span.
+ *
+ * Coverage:
+ *   - `gen_ai.operation.name` = `"execute_tool"` (OTEL spec).
+ *   - `gen_ai.tool.name` (OTEL spec).
+ *   - `gen_ai.tool.call.id` (OTEL spec).
+ *   - `gen_ai.tool.type` = `"function"` (default for MCP + builtins).
+ *   - `darwin.tool.outcome` = `"success" | "error"` (custom).
+ *   - `darwin.tool.duration_ms` (custom).
+ *   - `darwin.tool.turn` (custom).
+ *   - `darwin.tool.is_mcp` (boolean, custom).
+ *   - `gen_ai.tool.call.arguments` (JSON-stringified) — opt-in via
+ *     `opts.includeArguments`. Per OTEL spec this is OPT-IN because args
+ *     can contain sensitive data.
+ *   - `gen_ai.tool.call.result` — opt-in via `opts.includeResults` for
+ *     the same reason.
+ *   - `error.type` = `trajectory.toolCalls[i].errorClass` (when outcome=error).
+ */
+export interface ToolCallOtelOptions {
+    customNamespace?: string;
+    /** Emit `gen_ai.tool.call.arguments` (OPT-IN, may contain PII). */
+    includeArguments?: boolean;
+    /** Emit `gen_ai.tool.call.result` (OPT-IN, may contain PII). */
+    includeResults?: boolean;
+}
+export declare function toolCallToOtelAttributes(call: ExecutionTrace["toolCalls"][number], opts?: ToolCallOtelOptions): OtelAttributes;
+//# sourceMappingURL=to-otel-attributes.d.ts.map

package/dist/to-otel-attributes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"to-otel-attributes.d.ts","sourceRoot":"","sources":["../src/to-otel-attributes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEpD,oDAAoD;AACpD,MAAM,WAAW,uBAAuB;IACtC,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iFAAiF;IACjF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,yEAAyE;AACzE,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;AAEvE;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,cAAc,EAC1B,IAAI,GAAE,uBAA4B,GACjC,cAAc,CAmEhB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,mBAAmB;IAClC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,mEAAmE;IACnE,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,gEAAgE;IAChE,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,cAAc,CAAC,WAAW,CAAC,CAAC,MAAM,CAAC,EACzC,IAAI,GAAE,mBAAwB,GAC7B,cAAc,CAoDhB"}