darwin-langgraph 0.1.0-alpha.1

package/dist/create-darwin-node.js

@@ -0,0 +1,121 @@
+/**
+ * Surface 1 — `createDarwinNode(agent, opts?)`.
+ *
+ * Wraps a Darwin `AgentDefinition` as a LangGraph node action. The
+ * returned function:
+ *   1. Reads the task from `state[opts.taskKey ?? "task"]`.
+ *   2. Invokes `runAgent(agent, task, { memory })` from `darwin-agents`.
+ *   3. Writes the agent output to `state[opts.outputKey ?? "output"]`.
+ *   4. Optionally writes the captured `ExecutionTrace` to
+ *      `state[opts.trajectoryKey ?? "darwinTrajectory"]` so downstream
+ *      nodes (or the evolution hook) can read it.
+ *
+ * Design notes (S1185):
+ *   - **Non-generic return type.** The adapter returns `(state, config?) =>
+ *     Promise<Record<string, unknown>>`. LangGraph accepts any function
+ *     with the shape `(state, config?) => Partial<State>` as a NodeAction;
+ *     leaving the return type generic-free keeps the public API trivial
+ *     to consume from JS and TS alike. Strong typing is recovered via
+ *     `darwinAnnotation()` on the StateGraph side.
+ *   - **`runAgent` errors are wrapped** in `DarwinNodeError` so consumers
+ *     can `instanceof`-check adapter failures vs upstream failures.
+ *   - **`opts.onResult` is fire-and-forget swallowed.** A user callback
+ *     must NEVER break the graph; we await it, but suppress any throw
+ *     and surface it via `console.warn` once per Node. Mirrors the
+ *     `darwinPostRun` no-throw guarantee from `agents/lib/darwin-hook.ts`.
+ *   - **No `ANTHROPIC_API_KEY` manipulation.** `runAgent` makes its own
+ *     subprocess/provider decisions; consumers running on Claude Max
+ *     subscriptions must `delete process.env.ANTHROPIC_API_KEY` in
+ *     their own bootstrap (documented in README).
+ */
+import { isGraphInterrupt } from "@langchain/langgraph";
+import { runAgent } from "darwin-agents";
+import { DarwinNodeError } from "./errors.js";
+/**
+ * Build a LangGraph node from a Darwin agent.
+ *
+ * @example
+ * ```ts
+ * import { StateGraph } from "@langchain/langgraph";
+ * import { createDarwinNode, darwinAnnotation } from "darwin-langgraph";
+ * import { defineAgent } from "darwin-agents";
+ *
+ * const researcher = defineAgent({
+ *   name: "researcher",
+ *   role: "Topic Researcher",
+ *   description: "Researches a topic and returns 5 bullet points.",
+ *   systemPrompt: "Return exactly 5 bullets.",
+ * });
+ *
+ * const graph = new StateGraph(darwinAnnotation())
+ *   .addNode("research", createDarwinNode(researcher))
+ *   .addEdge("__start__", "research")
+ *   .compile();
+ *
+ * const result = await graph.invoke({ task: "What is GEPA?" });
+ * console.log(result.output);
+ * ```
+ */
+export function createDarwinNode(agent, opts = {}) {
+    if (!agent || typeof agent !== "object" || typeof agent.name !== "string") {
+        throw new DarwinNodeError("createDarwinNode: agent must be an AgentDefinition with a `name` field.", typeof agent === "object" && agent !== null && "name" in agent
+            ? String(agent.name ?? "<unknown>")
+            : "<unknown>");
+    }
+    const taskKey = opts.taskKey ?? "task";
+    const outputKey = opts.outputKey ?? "output";
+    const trajectoryKey = opts.trajectoryKey ?? "darwinTrajectory";
+    const captureTrace = opts.captureTrace !== false;
+    const agentName = agent.name;
+    const onResult = opts.onResult;
+    const runOptions = opts.runOptions ?? {};
+    // Track whether we already warned about a swallowed callback so the
+    // log stays at most one line per node, not one per invocation.
+    let onResultWarned = false;
+    return async function darwinNode(state) {
+        if (state === null || typeof state !== "object") {
+            throw new DarwinNodeError(`createDarwinNode(${agentName}): state must be an object, got ${typeof state}.`, agentName);
+        }
+        const rawTask = state[taskKey];
+        if (typeof rawTask !== "string" || rawTask.length === 0) {
+            throw new DarwinNodeError(`createDarwinNode(${agentName}): state["${taskKey}"] must be a non-empty string, ` +
+                `got ${rawTask === undefined ? "undefined" : typeof rawTask}.`, agentName);
+        }
+        let result;
+        try {
+            result = await runAgent(agent, rawTask, runOptions);
+        }
+        catch (err) {
+            // R1 Research Finding 5: LangGraph `interrupt()` surfaces as a
+            // `GraphInterrupt` thrown from inside the node call stack. The
+            // adapter MUST re-throw it untouched so LangGraph's HITL
+            // persistence + resume protocol works. Only non-interrupt errors
+            // get wrapped in `DarwinNodeError`.
+            if (isGraphInterrupt(err)) {
+                throw err;
+            }
+            throw new DarwinNodeError(`createDarwinNode(${agentName}): runAgent failed: ${err?.message ?? String(err)}`, agentName, { cause: err });
+        }
+        if (onResult) {
+            try {
+                await onResult(result);
+            }
+            catch (err) {
+                if (!onResultWarned) {
+                    onResultWarned = true;
+                    console.warn(`[darwin-langgraph] onResult callback for "${agentName}" threw — swallowed. ` +
+                        `Subsequent throws will be silent. Original error: ` +
+                        `${err?.message ?? String(err)}`);
+                }
+            }
+        }
+        const update = {
+            [outputKey]: result.output,
+        };
+        if (captureTrace && result.experiment?.trajectory) {
+            update[trajectoryKey] = result.experiment.trajectory;
+        }
+        return update;
+    };
+}
+//# sourceMappingURL=create-darwin-node.js.map

package/dist/create-darwin-node.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-darwin-node.js","sourceRoot":"","sources":["../src/create-darwin-node.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAOzC,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAsG9C;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,gBAAgB,CAC9B,KAAsB,EACtB,OAAgC,EAAE;IAElC,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC1E,MAAM,IAAI,eAAe,CACvB,yEAAyE,EACzE,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,MAAM,IAAI,KAAK;YAC5D,CAAC,CAAC,MAAM,CAAE,KAA4B,CAAC,IAAI,IAAI,WAAW,CAAC;YAC3D,CAAC,CAAC,WAAW,CAChB,CAAC;IACJ,CAAC;IAED,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,MAAM,CAAC;IACvC,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,QAAQ,CAAC;IAC7C,MAAM,aAAa,GAAG,IAAI,CAAC,aAAa,IAAI,kBAAkB,CAAC;IAC/D,MAAM,YAAY,GAAG,IAAI,CAAC,YAAY,KAAK,KAAK,CAAC;IACjD,MAAM,SAAS,GAAG,KAAK,CAAC,IAAI,CAAC;IAC7B,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;IAC/B,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,IAAI,EAAE,CAAC;IAEzC,oEAAoE;IACpE,+DAA+D;IAC/D,IAAI,cAAc,GAAG,KAAK,CAAC;IAE3B,OAAO,KAAK,UAAU,UAAU,CAAC,KAAK;QACpC,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAChD,MAAM,IAAI,eAAe,CACvB,oBAAoB,SAAS,mCAAmC,OAAO,KAAK,GAAG,EAC/E,SAAS,CACV,CAAC;QACJ,CAAC;QAED,MAAM,OAAO,GAAI,KAAiC,CAAC,OAAO,CAAC,CAAC;QAC5D,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACxD,MAAM,IAAI,eAAe,CACvB,oBAAoB,SAAS,aAAa,OAAO,iCAAiC;gBAChF,OAAO,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,OAAO,OAAO,GAAG,EAChE,SAAS,CACV,CAAC;QACJ,CAAC;QAED,IAAI,MAAiB,CAAC;QACtB,IAAI,CAAC;YACH,MAAM,GAAG,MAAM,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC;QACtD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,+DAA+D;YAC/D,+DAA+D;YAC/D,yDAAyD;YACzD,iEAAiE;YACjE,oCAAoC;YACpC,IAAI,gBAAgB,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC1B,MAAM,GAAG,CAAC;YACZ,CAAC;YACD,MAAM,IAAI,eAAe,CACvB,oBAAoB,SAAS,uBAAwB,GAAa,EAAE,OAAO,IAAI,MAAM,CAAC,GAAG,CAAC,EAAE,EAC5F,SAAS,EACT,EAAE,KAAK,EAAE,GAAG,EAAE,CACf,CAAC;QACJ,CAAC;QAED,IAAI,QAAQ,EAAE,CAAC;YACb,IAAI,CAAC;gBACH,MAAM,QAAQ,CAAC,MAAM,CAAC,CAAC;YACzB,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,CAAC,cAAc,EAAE,CAAC;oBACpB,cAAc,GAAG,IAAI,CAAC;oBACtB,OAAO,CAAC,IAAI,CACV,6CAA6C,SAAS,uBAAuB;wBAC3E,oDAAoD;wBACpD,GAAI,GAAa,EAAE,OAAO,IAAI,MAAM,CAAC,GAAG,CAAC,EAAE,CAC9C,CAAC;gBACJ,CAAC;YACH,CAAC;QACH,CAAC;QAED,MAAM,MAAM,GAA4B;YACtC,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM;SAC3B,CAAC;QACF,IAAI,YAAY,IAAI,MAAM,CAAC,UAAU,EAAE,UAAU,EAAE,CAAC;YAClD,MAAM,CAAC,aAAa,CAAC,GAAG,MAAM,CAAC,UAAU,CAAC,UAAU,CAAC;QACvD,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC,CAAC;AACJ,CAAC"}

package/dist/darwin-annotation.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Surface 2 — `darwinAnnotation(extra?)`.
+ *
+ * Returns a LangGraph `Annotation.Root({ ... })` pre-populated with three
+ * Darwin-aware channels:
+ *   - `task` (string, last-write-wins): the task fed to the Darwin agent.
+ *   - `output` (string, last-write-wins): the agent's final text output.
+ *   - `darwinTrajectory` (ExecutionTrace | undefined, last-write-wins):
+ *     the captured execution trace, available downstream nodes or to
+ *     the post-run evolution hook.
+ *
+ * Composable: pass any extra channels via the `extra` argument and they
+ * merge into the same `Annotation.Root` spread.
+ *
+ * @example
+ * ```ts
+ * import { darwinAnnotation } from "darwin-langgraph";
+ * import { Annotation, StateGraph } from "@langchain/langgraph";
+ *
+ * const State = darwinAnnotation({
+ *   reviewNotes: Annotation<string[]>({
+ *     reducer: (a, b) => a.concat(b),
+ *     default: () => [],
+ *   }),
+ * });
+ *
+ * const graph = new StateGraph(State)
+ *   .addNode("research", createDarwinNode(researcher))
+ *   .addNode("review", createDarwinNode(reviewer))
+ *   .compile();
+ * ```
+ *
+ * Design note: the channels use default last-write-wins reducers. If you
+ * want trajectory-accumulation (e.g. one entry per node), define your own
+ * channel via `extra` (e.g. `trajectories: Annotation<ExecutionTrace[]>(...)`)
+ * and skip `captureTrace` on every `createDarwinNode` call except the one
+ * you want to overwrite the singleton.
+ */
+import type { ExecutionTrace } from "darwin-agents";
+/**
+ * Pure last-write-wins reducer for trajectory. Exported for testability
+ * and so consumers can wrap it (e.g. cap at last-N).
+ */
+export declare function lastWriteWinsTrajectoryReducer(_prev: ExecutionTrace | undefined, next: ExecutionTrace | undefined): ExecutionTrace | undefined;
+/**
+ * Spec object used inside `Annotation.Root({ ... })`. Exported so power
+ * users can spread it manually into their own `Annotation.Root` call when
+ * the generic helper doesn't fit their setup (e.g. when they need a
+ * differently named `task` or `output` channel and don't want the
+ * defaults).
+ *
+ * Returned as a fresh object on every call so consumers can mutate it
+ * without affecting other graphs in the same process — the underlying
+ * `Annotation<T>` references are reused, which is what LangGraph expects.
+ *
+ * Return type is intentionally inferred. The internal `LastValue<T>` vs
+ * `BaseChannel<...>` mismatch between `Annotation<T>()` (zero-arg, plain
+ * last-write) and `Annotation<T>({reducer,default})` (full BaseChannel)
+ * is opaque to `Annotation.Root` (it accepts the union via `SDZod`).
+ * Hand-typing the return triggers TS2741 — inference works correctly.
+ */
+export declare function getDarwinChannelSpec(): {
+    task: import("@langchain/langgraph").LastValue<string>;
+    output: import("@langchain/langgraph").LastValue<string>;
+    darwinTrajectory: import("@langchain/langgraph").BaseChannel<ExecutionTrace | undefined, ExecutionTrace | import("@langchain/langgraph").OverwriteValue<ExecutionTrace | undefined> | undefined, unknown>;
+};
+/**
+ * Build an `Annotation.Root` schema with Darwin's three default channels
+ * plus any extra channels supplied by the caller.
+ *
+ * The return type is intentionally inferred from
+ * `Annotation.Root({...})` so `typeof darwinAnnotation().State` works
+ * exactly like a hand-rolled `Annotation.Root`.
+ */
+export declare function darwinAnnotation<Extra extends Record<string, any> = {}>(extra?: Extra): import("@langchain/langgraph").AnnotationRoot<{
+    task: import("@langchain/langgraph").LastValue<string>;
+    output: import("@langchain/langgraph").LastValue<string>;
+    darwinTrajectory: import("@langchain/langgraph").BaseChannel<ExecutionTrace | undefined, ExecutionTrace | import("@langchain/langgraph").OverwriteValue<ExecutionTrace | undefined> | undefined, unknown>;
+} & Extra>;
+//# sourceMappingURL=darwin-annotation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"darwin-annotation.d.ts","sourceRoot":"","sources":["../src/darwin-annotation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEpD;;;GAGG;AACH,wBAAgB,8BAA8B,CAC5C,KAAK,EAAE,cAAc,GAAG,SAAS,EACjC,IAAI,EAAE,cAAc,GAAG,SAAS,GAC/B,cAAc,GAAG,SAAS,CAE5B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,oBAAoB;;;;EASnC;AAED;;;;;;;GAOG;AAKH,wBAAgB,gBAAgB,CAAC,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,EAAE,EACrE,KAAK,CAAC,EAAE,KAAK;;;;WAMd"}

package/dist/darwin-annotation.js

@@ -0,0 +1,92 @@
+/**
+ * Surface 2 — `darwinAnnotation(extra?)`.
+ *
+ * Returns a LangGraph `Annotation.Root({ ... })` pre-populated with three
+ * Darwin-aware channels:
+ *   - `task` (string, last-write-wins): the task fed to the Darwin agent.
+ *   - `output` (string, last-write-wins): the agent's final text output.
+ *   - `darwinTrajectory` (ExecutionTrace | undefined, last-write-wins):
+ *     the captured execution trace, available downstream nodes or to
+ *     the post-run evolution hook.
+ *
+ * Composable: pass any extra channels via the `extra` argument and they
+ * merge into the same `Annotation.Root` spread.
+ *
+ * @example
+ * ```ts
+ * import { darwinAnnotation } from "darwin-langgraph";
+ * import { Annotation, StateGraph } from "@langchain/langgraph";
+ *
+ * const State = darwinAnnotation({
+ *   reviewNotes: Annotation<string[]>({
+ *     reducer: (a, b) => a.concat(b),
+ *     default: () => [],
+ *   }),
+ * });
+ *
+ * const graph = new StateGraph(State)
+ *   .addNode("research", createDarwinNode(researcher))
+ *   .addNode("review", createDarwinNode(reviewer))
+ *   .compile();
+ * ```
+ *
+ * Design note: the channels use default last-write-wins reducers. If you
+ * want trajectory-accumulation (e.g. one entry per node), define your own
+ * channel via `extra` (e.g. `trajectories: Annotation<ExecutionTrace[]>(...)`)
+ * and skip `captureTrace` on every `createDarwinNode` call except the one
+ * you want to overwrite the singleton.
+ */
+import { Annotation } from "@langchain/langgraph";
+/**
+ * Pure last-write-wins reducer for trajectory. Exported for testability
+ * and so consumers can wrap it (e.g. cap at last-N).
+ */
+export function lastWriteWinsTrajectoryReducer(_prev, next) {
+    return next;
+}
+/**
+ * Spec object used inside `Annotation.Root({ ... })`. Exported so power
+ * users can spread it manually into their own `Annotation.Root` call when
+ * the generic helper doesn't fit their setup (e.g. when they need a
+ * differently named `task` or `output` channel and don't want the
+ * defaults).
+ *
+ * Returned as a fresh object on every call so consumers can mutate it
+ * without affecting other graphs in the same process — the underlying
+ * `Annotation<T>` references are reused, which is what LangGraph expects.
+ *
+ * Return type is intentionally inferred. The internal `LastValue<T>` vs
+ * `BaseChannel<...>` mismatch between `Annotation<T>()` (zero-arg, plain
+ * last-write) and `Annotation<T>({reducer,default})` (full BaseChannel)
+ * is opaque to `Annotation.Root` (it accepts the union via `SDZod`).
+ * Hand-typing the return triggers TS2741 — inference works correctly.
+ */
+export function getDarwinChannelSpec() {
+    return {
+        task: Annotation(),
+        output: Annotation(),
+        darwinTrajectory: Annotation({
+            reducer: lastWriteWinsTrajectoryReducer,
+            default: () => undefined,
+        }),
+    };
+}
+/**
+ * Build an `Annotation.Root` schema with Darwin's three default channels
+ * plus any extra channels supplied by the caller.
+ *
+ * The return type is intentionally inferred from
+ * `Annotation.Root({...})` so `typeof darwinAnnotation().State` works
+ * exactly like a hand-rolled `Annotation.Root`.
+ */
+// Wide return type because `Annotation.Root` returns a complex inferred
+// generic that depends on the precise channel spec. Consumers extract
+// `typeof X.State` so the concrete shape is recovered at the use site.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function darwinAnnotation(extra) {
+    return Annotation.Root({
+        ...getDarwinChannelSpec(),
+        ...(extra ?? {}),
+    });
+}
+//# sourceMappingURL=darwin-annotation.js.map

package/dist/darwin-annotation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"darwin-annotation.js","sourceRoot":"","sources":["../src/darwin-annotation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAGlD;;;GAGG;AACH,MAAM,UAAU,8BAA8B,CAC5C,KAAiC,EACjC,IAAgC;IAEhC,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,oBAAoB;IAClC,OAAO;QACL,IAAI,EAAE,UAAU,EAAU;QAC1B,MAAM,EAAE,UAAU,EAAU;QAC5B,gBAAgB,EAAE,UAAU,CAA6B;YACvD,OAAO,EAAE,8BAA8B;YACvC,OAAO,EAAE,GAAG,EAAE,CAAC,SAAS;SACzB,CAAC;KACH,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,wEAAwE;AACxE,sEAAsE;AACtE,uEAAuE;AACvE,8DAA8D;AAC9D,MAAM,UAAU,gBAAgB,CAC9B,KAAa;IAEb,OAAO,UAAU,CAAC,IAAI,CAAC;QACrB,GAAG,oBAAoB,EAAE;QACzB,GAAG,CAAC,KAAK,IAAK,EAAY,CAAC;KAC5B,CAAC,CAAC;AACL,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Adapter-specific error classes. Both subclass `Error` so consumers can
+ * use `err instanceof DarwinNodeError` to distinguish adapter failures
+ * from upstream `darwin-agents` or `@langchain/langgraph` errors.
+ *
+ * Pattern mirrors `mcp-armor` and `darwin-agents@0.4.9` McpBridge*Error
+ * (see `nex_decide 34a506ba` for the upstream pattern).
+ */
+export declare class DarwinNodeError extends Error {
+    readonly agentName: string;
+    readonly name = "DarwinNodeError";
+    constructor(message: string, agentName: string, options?: {
+        cause?: unknown;
+    });
+}
+export declare class DarwinEvolutionHookError extends Error {
+    readonly name = "DarwinEvolutionHookError";
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,qBAAa,eAAgB,SAAQ,KAAK;aAKtB,SAAS,EAAE,MAAM;IAJnC,SAAyB,IAAI,qBAAqB;gBAGhD,OAAO,EAAE,MAAM,EACC,SAAS,EAAE,MAAM,EACjC,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAIhC;AAED,qBAAa,wBAAyB,SAAQ,KAAK;IACjD,SAAyB,IAAI,8BAA8B;gBAE/C,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAG3D"}

package/dist/errors.js

@@ -0,0 +1,23 @@
+/**
+ * Adapter-specific error classes. Both subclass `Error` so consumers can
+ * use `err instanceof DarwinNodeError` to distinguish adapter failures
+ * from upstream `darwin-agents` or `@langchain/langgraph` errors.
+ *
+ * Pattern mirrors `mcp-armor` and `darwin-agents@0.4.9` McpBridge*Error
+ * (see `nex_decide 34a506ba` for the upstream pattern).
+ */
+export class DarwinNodeError extends Error {
+    agentName;
+    name = "DarwinNodeError";
+    constructor(message, agentName, options) {
+        super(message, options);
+        this.agentName = agentName;
+    }
+}
+export class DarwinEvolutionHookError extends Error {
+    name = "DarwinEvolutionHookError";
+    constructor(message, options) {
+        super(message, options);
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,OAAO,eAAgB,SAAQ,KAAK;IAKtB;IAJO,IAAI,GAAG,iBAAiB,CAAC;IAElD,YACE,OAAe,EACC,SAAiB,EACjC,OAA6B;QAE7B,KAAK,CAAC,OAAO,EAAE,OAAuB,CAAC,CAAC;QAHxB,cAAS,GAAT,SAAS,CAAQ;IAInC,CAAC;CACF;AAED,MAAM,OAAO,wBAAyB,SAAQ,KAAK;IACxB,IAAI,GAAG,0BAA0B,CAAC;IAE3D,YAAY,OAAe,EAAE,OAA6B;QACxD,KAAK,CAAC,OAAO,EAAE,OAAuB,CAAC,CAAC;IAC1C,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,47 @@
+/**
+ * darwin-langgraph — LangGraph.js adapter for darwin-agents.
+ *
+ * Public entry. Three surfaces + types + errors.
+ *
+ * @example
+ * ```ts
+ * import { StateGraph } from "@langchain/langgraph";
+ * import { defineAgent } from "darwin-agents";
+ * import {
+ *   createDarwinNode,
+ *   darwinAnnotation,
+ *   withDarwinEvolution,
+ * } from "darwin-langgraph";
+ *
+ * const researcher = defineAgent({
+ *   name: "researcher",
+ *   role: "Topic Researcher",
+ *   description: "Five bullets on a topic.",
+ *   systemPrompt: "Return exactly 5 bullet points.",
+ * });
+ *
+ * const graph = withDarwinEvolution(
+ *   new StateGraph(darwinAnnotation())
+ *     .addNode("research", createDarwinNode(researcher))
+ *     .addEdge("__start__", "research")
+ *     .compile(),
+ *   {
+ *     nodeMap: { research: "researcher" },
+ *     onTrajectory: (event) => {
+ *       console.log(`${event.nodeName} (${event.agentName}) trajectory:`, event.trajectory);
+ *     },
+ *   },
+ * );
+ *
+ * const result = await graph.invoke({ task: "What is GEPA?" });
+ * console.log(result.output);
+ * ```
+ */
+export { createDarwinNode, type CreateDarwinNodeOptions, type DarwinNodeFn, } 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 { 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";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +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"}

package/dist/index.js

@@ -0,0 +1,46 @@
+/**
+ * darwin-langgraph — LangGraph.js adapter for darwin-agents.
+ *
+ * Public entry. Three surfaces + types + errors.
+ *
+ * @example
+ * ```ts
+ * import { StateGraph } from "@langchain/langgraph";
+ * import { defineAgent } from "darwin-agents";
+ * import {
+ *   createDarwinNode,
+ *   darwinAnnotation,
+ *   withDarwinEvolution,
+ * } from "darwin-langgraph";
+ *
+ * const researcher = defineAgent({
+ *   name: "researcher",
+ *   role: "Topic Researcher",
+ *   description: "Five bullets on a topic.",
+ *   systemPrompt: "Return exactly 5 bullet points.",
+ * });
+ *
+ * const graph = withDarwinEvolution(
+ *   new StateGraph(darwinAnnotation())
+ *     .addNode("research", createDarwinNode(researcher))
+ *     .addEdge("__start__", "research")
+ *     .compile(),
+ *   {
+ *     nodeMap: { research: "researcher" },
+ *     onTrajectory: (event) => {
+ *       console.log(`${event.nodeName} (${event.agentName}) trajectory:`, event.trajectory);
+ *     },
+ *   },
+ * );
+ *
+ * const result = await graph.invoke({ task: "What is GEPA?" });
+ * console.log(result.output);
+ * ```
+ */
+export { createDarwinNode, } from "./create-darwin-node.js";
+export { darwinAnnotation, getDarwinChannelSpec, lastWriteWinsTrajectoryReducer, } from "./darwin-annotation.js";
+export { withDarwinEvolution, } from "./with-darwin-evolution.js";
+export { DarwinNodeError, DarwinEvolutionHookError } from "./errors.js";
+/** Adapter version — sync with `package.json` on every release. */
+export const VERSION = "0.1.0-alpha.1";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +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"}

package/dist/types.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Re-exports the darwin-agents types that consumers of darwin-langgraph
+ * need most often, so a typical project can import everything from one
+ * place:
+ *
+ * ```ts
+ * import {
+ *   createDarwinNode,
+ *   darwinAnnotation,
+ *   withDarwinEvolution,
+ *   type AgentDefinition,
+ *   type ExecutionTrace,
+ * } from "darwin-langgraph";
+ * ```
+ *
+ * Re-export only — no runtime code. Keeps the bundle tiny and avoids
+ * accidental dual-import of darwin-agents.
+ */
+export type { AgentDefinition, DarwinExperiment, ExecutionTrace, MemoryProvider, RunResult, TraceToolCall, TraceTokenUsage, TraceTurnError, } from "darwin-agents";
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,YAAY,EACV,eAAe,EACf,gBAAgB,EAChB,cAAc,EACd,cAAc,EACd,SAAS,EACT,aAAa,EACb,eAAe,EACf,cAAc,GACf,MAAM,eAAe,CAAC"}

package/dist/types.js

@@ -0,0 +1,20 @@
+/**
+ * Re-exports the darwin-agents types that consumers of darwin-langgraph
+ * need most often, so a typical project can import everything from one
+ * place:
+ *
+ * ```ts
+ * import {
+ *   createDarwinNode,
+ *   darwinAnnotation,
+ *   withDarwinEvolution,
+ *   type AgentDefinition,
+ *   type ExecutionTrace,
+ * } from "darwin-langgraph";
+ * ```
+ *
+ * Re-export only — no runtime code. Keeps the bundle tiny and avoids
+ * accidental dual-import of darwin-agents.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG"}

package/dist/with-darwin-evolution.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Surface 3 — `withDarwinEvolution(graph, opts)`.
+ *
+ * Wraps a compiled `StateGraph` with a fire-and-forget post-run hook
+ * that mirrors Darwin's closed-loop evolution pattern (see
+ * `agents/lib/darwin-hook.ts` for the in-tree Nex implementation):
+ *
+ *   1. After `graph.invoke(...)` resolves, we extract trajectories from
+ *      the final state and dispatch them to `opts.onTrajectory` per
+ *      mapped node.
+ *   2. The same applies to `graph.stream(...)` — we wrap the async
+ *      iterator and replay the final-state chunk to the hook once the
+ *      consumer finishes iterating.
+ *
+ * Design notes (S1185):
+ *   - **Never throws inside the hook.** Caller logic that fails inside
+ *     `onTrajectory` is logged once per process and otherwise swallowed.
+ *     The graph result the consumer sees is identical with or without
+ *     the wrap.
+ *   - **No mutation of `graph` if it doesn't expose `invoke`/`stream`
+ *     as own properties.** We bind via `Object.defineProperty` and fall
+ *     back to a no-op wrap if the graph is frozen. This means future
+ *     LangGraph internals that move `invoke` to a hidden prototype slot
+ *     won't crash — at worst, the hook silently never fires (the test
+ *     suite catches that case).
+ *   - **`nodeMap` shape:** either `string` (treated as
+ *     `{ agentName: string, trajectoryKey: defaultKey }`) or an object
+ *     with explicit `trajectoryKey`. Supports both ergonomic one-liner
+ *     and per-node trajectory routing in the same graph.
+ */
+import type { ExecutionTrace } from "darwin-agents";
+/** Map entry — either a bare agent name or an explicit `{agent, key}` tuple. */
+export type DarwinNodeMapEntry = string | {
+    agentName: string;
+    trajectoryKey: string;
+};
+/** Argument passed to {@link DarwinEvolutionOptions.onTrajectory}. */
+export interface DarwinTrajectoryEvent {
+    /** Name of the StateGraph node that produced the trajectory. */
+    nodeName: string;
+    /** Darwin agent name (from the `nodeMap` mapping). */
+    agentName: string;
+    /** The captured execution trace. */
+    trajectory: ExecutionTrace;
+    /**
+     * Snapshot of the final graph state. The TOP-LEVEL object is frozen
+     * (shallow), but NESTED objects (incl. the trajectory itself) are NOT
+     * deep-frozen for performance — treat them as logically immutable by
+     * convention. Mutating nested values leaks back into the live graph
+     * state and corrupts subsequent runs (R1 Critic Finding 4, S1185).
+     */
+    finalState: Readonly<Record<string, unknown>>;
+}
+/** Options for {@link withDarwinEvolution}. */
+export interface DarwinEvolutionOptions {
+    /**
+     * Maps StateGraph node names to either a bare Darwin agent name
+     * (uses `darwinTrajectory` as the state key) or an object specifying
+     * a custom `trajectoryKey` for that node.
+     *
+     * Example:
+     * ```ts
+     * nodeMap: {
+     *   research: "researcher",
+     *   review: { agentName: "critic", trajectoryKey: "criticTrajectory" },
+     * }
+     * ```
+     */
+    nodeMap: Record<string, DarwinNodeMapEntry>;
+    /**
+     * Called once per mapped node whose trajectory was found in the final
+     * state. Errors are swallowed — never breaks the graph result.
+     */
+    onTrajectory?: (event: DarwinTrajectoryEvent) => void | Promise<void>;
+    /** Default trajectory key when `nodeMap` entry is a bare string. Default: `"darwinTrajectory"`. */
+    defaultTrajectoryKey?: string;
+}
+/** Minimal interface the adapter needs — covers `CompiledStateGraph`. */
+interface InvokableGraph {
+    invoke(input: unknown, config?: unknown): Promise<unknown>;
+    stream(input: unknown, config?: unknown): Promise<AsyncIterable<unknown>>;
+}
+/**
+ * Wraps a compiled LangGraph so the supplied `onTrajectory` callback
+ * fires for each node listed in `nodeMap` after every `invoke` / `stream`
+ * run. Returns the same graph instance for chaining.
+ *
+ * @throws {DarwinEvolutionHookError} when `nodeMap` is empty or missing.
+ */
+export declare function withDarwinEvolution<G extends InvokableGraph>(graph: G, opts: DarwinEvolutionOptions): G;
+export {};
+//# sourceMappingURL=with-darwin-evolution.d.ts.map

package/dist/with-darwin-evolution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"with-darwin-evolution.d.ts","sourceRoot":"","sources":["../src/with-darwin-evolution.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAIpD,gFAAgF;AAChF,MAAM,MAAM,kBAAkB,GAC1B,MAAM,GACN;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjD,sEAAsE;AACtE,MAAM,WAAW,qBAAqB;IACpC,gEAAgE;IAChE,QAAQ,EAAE,MAAM,CAAC;IACjB,sDAAsD;IACtD,SAAS,EAAE,MAAM,CAAC;IAClB,oCAAoC;IACpC,UAAU,EAAE,cAAc,CAAC;IAC3B;;;;;;OAMG;IACH,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAC/C;AAED,+CAA+C;AAC/C,MAAM,WAAW,sBAAsB;IACrC;;;;;;;;;;;;OAYG;IACH,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;IAC5C;;;OAGG;IACH,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,qBAAqB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtE,mGAAmG;IACnG,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,yEAAyE;AACzE,UAAU,cAAc;IACtB,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC3D,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC;CAC3E;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,cAAc,EAC1D,KAAK,EAAE,CAAC,EACR,IAAI,EAAE,sBAAsB,GAC3B,CAAC,CA+OH"}