darwin-langgraph 0.1.0-alpha.1

package/CHANGELOG.md

@@ -0,0 +1,119 @@
+# Changelog
+
+All notable changes to `darwin-langgraph` are documented here.
+The project adheres to [Semantic Versioning](https://semver.org/).
+
+## [0.1.0-alpha.1] — 2026-05-24
+
+### Added
+
+- **Surface 1: `createDarwinNode(agent, opts?)`** — wraps a Darwin
+  `AgentDefinition` as a LangGraph `NodeAction`. Reads the task from state,
+  runs the agent via `darwin-agents.runAgent()`, writes `output` and (opt-in)
+  the captured `ExecutionTrace` back to state.
+- **Surface 2: `darwinAnnotation(extra?)`** — `Annotation.Root` helper with
+  three pre-defined channels (`task`, `output`, `darwinTrajectory`).
+  Composable via `extra` for user channels.
+- **Surface 3: `withDarwinEvolution(graph, opts)`** — wraps a compiled
+  `StateGraph`'s `invoke` / `stream` methods with a fire-and-forget post-run
+  hook that forwards each node's trajectory to a user-supplied callback,
+  enabling Darwin's closed-loop A/B evolution without changing graph code.
+- **Custom errors:** `DarwinNodeError`, `DarwinEvolutionHookError` — subclass
+  `Error` for `instanceof` checks.
+- **Types:** Re-export of `AgentDefinition`, `ExecutionTrace`, `RunResult`,
+  `MemoryProvider`, `TraceToolCall`, `TraceTokenUsage`, `TraceTurnError`
+  from `darwin-agents` for ergonomic single-import.
+
+### Compatibility
+
+| `darwin-langgraph` | `darwin-agents` | `@langchain/langgraph` |
+|---|---|---|
+| `0.1.0-alpha.x` | `^0.5.0-alpha.1` | `^1.3.0` |
+
+Both upstream packages are declared as **peer-dependencies** — the consumer
+controls the installed versions and the adapter never pins them.
+
+### Notes
+
+- Released under the `alpha` npm dist-tag in parallel with
+  `darwin-agents@0.5.0-alpha.1` (the first release that ships
+  `ExecutionTrace` capture). Default `npm install darwin-langgraph`
+  refuses to resolve until `0.1.0` final ships — explicit opt-in via
+  `npm install darwin-langgraph@alpha`.
+- The adapter never touches `ANTHROPIC_API_KEY`. If you run Darwin on a
+  Claude Max subscription via the Claude Code CLI, set `delete
+  process.env.ANTHROPIC_API_KEY` in your own bootstrap.
+- **Peer-dep semver caveat:** `darwin-agents: "^0.5.0-alpha.1"` follows
+  npm's prerelease semver rules — `0.5.0-alpha.N` and `0.5.0` final
+  satisfy it, but `0.5.1-alpha.0` does NOT. A patch release of this
+  adapter will be required when `darwin-agents` bumps past `0.5.x`.
+
+### R1 + R2 Code-Review Loop Pre-Publish
+
+The 3-Agent code-review loop (Critic + Analyst + Research, in parallel)
+ran twice before this release. R1 surfaced 8 findings, all fixed
+in-place. R2 surfaced 1 HIGH must-fix + 4 LOW deferrals, the must-fix
+landed in this release. The 9 R1 + 4 R2 regression tests live in
+[`tests/r1-fixes.test.ts`](./tests/r1-fixes.test.ts).
+
+**R2 MUST-FIX (S1185):**
+
+- **HIGH (R2 Research 1):** the R1 hand-rolled `isGraphInterrupt`
+  duck-type missed `NodeInterrupt` (a `GraphInterrupt` subclass that
+  is the ACTUAL error thrown by `interrupt()` inside a node) AND broke
+  under bundler minification when `keep_classnames` was off. Fix:
+  import `isGraphInterrupt` directly from `@langchain/langgraph`'s
+  main entry (a stable public export that uses LangGraph's internal
+  `unminifiable_name` static-getter pattern). 12 LOC of hand-rolled
+  helper deleted, 1 line of named import added. Tests now use real
+  `GraphInterrupt` + `NodeInterrupt` instances.
+- **LOW (R2 Critic 3):** added a comment block in `wrappedStream`
+  explaining the `activeInvokeMarkers.size > 0` ordering invariant
+  so future maintainers don't misread the race-free pattern.
+- **LOW (R2 Analyst):** fixed stale README design-note line that still
+  said "counter" instead of "`Set<symbol>`".
+
+**R1-Fixes (8 findings):**
+
+1. **CRITICAL (Critic 1):** `withDarwinEvolution` shared-counter race —
+   replaced `let invokesInFlight = 0` with `Set<symbol>` so concurrent
+   `Promise.all([graph.invoke, graph.invoke])` calls fire `onTrajectory`
+   exactly once each instead of double-firing. Regression test in
+   `tests/r1-fixes.test.ts`.
+2. **HIGH (Critic 2):** `stream({ streamMode: "updates" })` silently
+   skipped hook — adapter now `console.warn`s once when streamMode is
+   not `"values"`, surfacing the contract gap to users.
+3. **HIGH (Research 5):** `runAgent`-throws of `GraphInterrupt`
+   (LangGraph HITL signal) were getting wrapped in `DarwinNodeError`,
+   breaking the resume protocol. `createDarwinNode` now duck-types the
+   `name` / `constructor.name` field and re-throws untouched.
+4. **MEDIUM (Critic 4):** `Object.freeze({...stateObj})` is shallow.
+   JSDoc on `DarwinTrajectoryEvent.finalState` now says so explicitly
+   and points to "treat nested values as immutable by convention."
+5. **MEDIUM (Critic 6):** Added explicit test for
+   `result.experiment.trajectory === null` (not just `undefined`).
+6. **MEDIUM (Critic 7):** Added `verify:version-sync` script that the
+   `prepublishOnly` step runs — refuses to publish when `package.json`
+   and `src/index.ts` `VERSION` constant drift.
+7. **MEDIUM (Critic 8, Analyst 4):** Example 02 + 03 now warn about
+   `taskKey` shadowing and `MemorySaver` being dev-only.
+8. **LOW (Research 6):** `peerDependenciesMeta` stanza added
+   (both peers marked `optional: false` explicitly).
+
+### V0.2 Roadmap (deferred from R1 review)
+
+- **`DarwinCallbackHandler` migration** (Research 2): drop the
+  `invoke`/`stream` monkey-patch in `withDarwinEvolution` in favour of
+  LangChain's `BaseCallbackHandler` registered via `graph.invoke(input,
+  { callbacks: [...] })`. Outlives any LangGraph-internal API shuffle.
+- **`toOtelAttributes(trajectory)` helper** (Research 3): map Darwin's
+  `ExecutionTrace` to OpenTelemetry GenAI Semantic Conventions
+  (`gen_ai.usage.input_tokens`, `gen_ai.agent.name`, etc.) so Langfuse /
+  Braintrust / Datadog integrate out-of-the-box.
+- **`darwinMessagesAnnotation()`** (Research 7): variant that merges
+  Darwin's three channels with LangGraph's `MessagesAnnotation.spec` so
+  mixing `createReactAgent` and `createDarwinNode` in one graph works
+  without channel-name conflicts.
+- **`onResult` vs `onTrajectory` README paragraph** (Analyst 2):
+  explicit "when to pick which" guidance. Currently covered in JSDoc
+  only.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 StudioMeyer (Matthias Meyer)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,276 @@
+# darwin-langgraph
+
+> **LangGraph.js adapter for [`darwin-agents`](https://www.npmjs.com/package/darwin-agents).**
+> Wrap self-evolving Darwin agents as `StateGraph` nodes — with zero hard deps.
+
+[![npm version](https://img.shields.io/npm/v/darwin-langgraph/alpha.svg)](https://www.npmjs.com/package/darwin-langgraph)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+
+`darwin-langgraph` is a thin, peer-dependency-only bridge between two
+independent libraries:
+
+- **[`darwin-agents`](https://www.npmjs.com/package/darwin-agents)** — Darwin
+  is an agent framework where prompts evolve themselves via A/B testing,
+  multi-model critics, safety gates, and (since `v0.5.0-alpha.1`) full
+  execution-trace capture for GEPA-style reflective optimizers.
+- **[`@langchain/langgraph`](https://www.npmjs.com/package/@langchain/langgraph)** —
+  LangGraph is the state-graph orchestration runtime used by Uber,
+  LinkedIn, Klarna, Replit, and others to build multi-step, multi-agent
+  workflows with durable execution and human-in-the-loop.
+
+If you use **only Darwin**, you install nothing extra — Darwin itself has
+zero LangChain dependency. If you use **only LangGraph**, the same.
+If you want to combine the two — let LangGraph orchestrate, let Darwin
+evolve — install this adapter.
+
+## Install
+
+```bash
+npm install darwin-langgraph@alpha @langchain/langgraph darwin-agents@alpha
+```
+
+Both `@langchain/langgraph` and `darwin-agents` are declared as
+**peer-dependencies** — you control the installed versions, the adapter
+never pins them.
+
+## Quick start
+
+```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} ran in ${event.trajectory.turnCount} turns ` +
+          `with ${event.trajectory.toolCalls.length} tool calls.`,
+      );
+    },
+  },
+);
+
+const result = await graph.invoke({ task: "What is GEPA?" });
+console.log(result.output);
+console.log("trajectory:", result.darwinTrajectory);
+```
+
+## Three surfaces
+
+### 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. Calls `runAgent(agent, task, opts.runOptions)` from `darwin-agents`.
+3. Writes the agent's output to `state[opts.outputKey ?? "output"]`.
+4. Optionally writes the captured `ExecutionTrace` to
+   `state[opts.trajectoryKey ?? "darwinTrajectory"]`.
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `taskKey` | `string` | `"task"` | State property to read the task from. |
+| `outputKey` | `string` | `"output"` | State property the output is written to. |
+| `trajectoryKey` | `string` | `"darwinTrajectory"` | State property the trace is written to. |
+| `runOptions` | object | `{}` | Passthrough for `model`, `maxTurns`, `timeout`, `cwd`, `autonomous`, `config`. |
+| `captureTrace` | `boolean` | `true` | Set `false` to skip trajectory propagation. |
+| `onResult` | function | — | Fire-and-forget side-effect after each run. Errors are swallowed. |
+
+### 2. `darwinAnnotation(extra?)`
+
+Returns an `Annotation.Root` with three pre-defined channels
+(`task` / `output` / `darwinTrajectory`) plus any extra channels you pass
+in. Composable:
+
+```ts
+const State = darwinAnnotation({
+  reviewNotes: Annotation<string[]>({
+    reducer: (a, b) => a.concat(b),
+    default: () => [],
+  }),
+});
+```
+
+Power-users can spread `getDarwinChannelSpec()` directly into their own
+`Annotation.Root({...})` when the helper doesn't fit.
+
+### 3. `withDarwinEvolution(graph, opts)`
+
+Wraps a compiled `StateGraph` with a post-run hook that fires `onTrajectory`
+for each node listed in `nodeMap` after every `invoke` / `stream` run.
+Errors inside the hook are swallowed — the graph result is always
+returned unchanged.
+
+```ts
+withDarwinEvolution(graph, {
+  nodeMap: {
+    research: "researcher",
+    critique: { agentName: "critic", trajectoryKey: "critiqueTrace" },
+  },
+  onTrajectory: (event) => {
+    // event.nodeName, event.agentName, event.trajectory, event.finalState
+  },
+});
+```
+
+### Custom errors
+
+```ts
+import { DarwinNodeError, DarwinEvolutionHookError } from "darwin-langgraph";
+
+try { await graph.invoke({ task: "..." }); }
+catch (err) {
+  if (err instanceof DarwinNodeError) {
+    console.error(`Node "${err.agentName}" failed:`, err.cause);
+  }
+}
+```
+
+> **GraphInterrupt is re-thrown un-wrapped.** When a downstream node
+> calls LangGraph's `interrupt()` for human-in-the-loop, the resulting
+> `GraphInterrupt` is surfaced through `createDarwinNode` un-touched so
+> the resume protocol (`Command({ resume: ... })`) works. Only non-HITL
+> errors get wrapped in `DarwinNodeError`.
+
+### `onResult` vs `onTrajectory` — when to pick which
+
+Both hooks fire after a Darwin agent finishes, but at different layers:
+
+- **`onResult`** (per-node, on `createDarwinNode`) receives the **full
+  raw `RunResult`** — including `experiment`, `evolution`, `reportPath`,
+  and the raw output. Use it for **per-agent side-effects** that don't
+  care about graph structure (e.g. writing to a database, logging the
+  full result).
+- **`onTrajectory`** (graph-wide, on `withDarwinEvolution`) receives a
+  **normalised `DarwinTrajectoryEvent`** with `nodeName`, `agentName`,
+  trajectory, and a frozen final-state snapshot. Use it for
+  **cross-node observability** that needs to know which LangGraph node
+  produced which trace (cost tracking, A/B telemetry, evolution loops).
+
+If you only need per-agent side-effects, use `onResult`. If you need
+node-aware telemetry, use `onTrajectory`. They are **not redundant** —
+combining both is fine, just be aware they fire at slightly different
+points (node-completion vs graph-completion).
+
+### `streamMode` and the trajectory hook
+
+`withDarwinEvolution` wraps both `invoke()` and `stream()`. The hook
+reliably fires when:
+
+- You call `graph.invoke({...})` — always works. Internally
+  `streamMode: "values"`.
+- You call `graph.stream({...})` or `graph.stream({...}, { streamMode:
+  "values" })` — works.
+- You include `"values"` in a multi-mode array
+  (`streamMode: ["values", "updates"]`) — works.
+
+It does **not** fire on `streamMode: "updates"` / `"messages"` /
+`"debug"` (without `"values"`) — the last chunk in those modes is a
+node-update dict, not the final state, so the trajectory key lookup
+silently misses. The adapter logs a `console.warn` (once per process)
+the first time it detects a non-`values` stream so you don't silently
+lose telemetry. V0.2 will migrate to the LangChain `CallbackHandler`
+mechanism which fires regardless of stream mode.
+
+## Examples
+
+The [`examples/`](./examples/) directory ships three runnable scripts:
+
+- [`01-basic-node.ts`](./examples/01-basic-node.ts) — single Darwin node in a 1-edge graph.
+- [`02-multi-agent-research.ts`](./examples/02-multi-agent-research.ts) — researcher → critic → writer pipeline with per-node trajectories.
+- [`03-hitl-with-darwin.ts`](./examples/03-hitl-with-darwin.ts) — LangGraph `interrupt()` before a Darwin agent runs, with `Command({ resume: ... })` to continue.
+
+## Compatibility matrix
+
+| `darwin-langgraph` | `darwin-agents` | `@langchain/langgraph` | Status |
+|---|---|---|---|
+| `0.1.0-alpha.x` | `^0.5.0-alpha.1` | `^1.3.0` | alpha (this release) |
+
+The peer-dep range `darwin-agents: "^0.5.0-alpha.1"` follows npm's
+prerelease semver rules — `0.5.0-alpha.N` and `0.5.0` final satisfy it,
+but `0.5.1-alpha.0` does NOT. A patch release of this adapter will be
+required when `darwin-agents` bumps past `0.5.x`.
+
+## Known limitations (will be addressed in v0.2)
+
+- **`withDarwinEvolution` monkey-patches `invoke`/`stream`** — V0.2
+  will migrate to a `DarwinCallbackHandler` you pass via
+  `graph.invoke(input, { callbacks: [...] })`, which is the canonical
+  LangChain pattern (matches Langfuse, Braintrust, LangSmith handlers).
+- **No `gen_ai.*` OTEL attribute helper** — V0.2 will ship
+  `toOtelAttributes(trajectory)` so traces forward to Langfuse /
+  Braintrust / Datadog with OpenTelemetry GenAI Semantic Conventions.
+- **No bundled `messages` channel** — V0.2 will add
+  `darwinMessagesAnnotation()` for graphs that mix `createReactAgent`
+  with `createDarwinNode`. Until then, you can pass
+  `darwinAnnotation({ ...MessagesAnnotation.spec })` manually.
+
+The adapter releases follow `darwin-agents` major bumps. When
+`@langchain/langgraph` 2.x lands, the adapter ships a new major within
+the same minor of the underlying Darwin release.
+
+## Subscription / API key handling
+
+The adapter NEVER touches `ANTHROPIC_API_KEY`. If you run Darwin on a
+Claude Max subscription via the Claude Code CLI, your bootstrap must
+`delete process.env.ANTHROPIC_API_KEY` BEFORE invoking the graph —
+otherwise Darwin's `ClaudeCliProvider` will hit the metered API and you
+pay per request instead of the flat subscription.
+
+```ts
+// bootstrap.ts
+import "dotenv/config";
+delete process.env.ANTHROPIC_API_KEY; // enforce Max-Plan subscription
+```
+
+## Design notes
+
+- **Zero runtime deps.** Both `darwin-agents` and `@langchain/langgraph`
+  are peer-dependencies. The adapter itself is a couple of hundred lines
+  of TypeScript that re-exports a handful of types.
+- **`invoke()` calls `stream()` internally.** LangGraph v1.x implements
+  `invoke` on top of `stream`. The adapter tracks in-flight invokes
+  with a per-call `Symbol` marker stored in a `Set` so the trajectory
+  hook fires exactly once per logical run, even under concurrent
+  `Promise.all([graph.invoke(...), graph.invoke(...)])`.
+- **`GraphInterrupt` re-throw.** The adapter imports `isGraphInterrupt`
+  directly from `@langchain/langgraph` so LangGraph's HITL exceptions
+  (both `GraphInterrupt` and `NodeInterrupt`) propagate untouched —
+  `Command({ resume })` works as expected.
+- **Hook errors never propagate.** Both `opts.onResult` (on
+  `createDarwinNode`) and `opts.onTrajectory` (on `withDarwinEvolution`)
+  use a fire-and-forget pattern with one-shot `console.warn` for the
+  first swallowed throw per process.
+- **No memory provider construction.** Memory backends (Postgres,
+  SQLite) are resolved by `darwin-agents` itself — set
+  `DARWIN_POSTGRES_URL` / `DARWIN_SQLITE_PATH` env vars or pass
+  `runOptions.config.dataDir`.
+
+## Versioning
+
+Released under the `alpha` npm dist-tag in parallel with
+`darwin-agents@0.5.0-alpha.1`. Default `npm install darwin-langgraph`
+will NOT resolve until `0.1.0` final ships. Explicit opt-in via
+`npm install darwin-langgraph@alpha`.
+
+## License
+
+MIT © 2026 StudioMeyer

package/dist/create-darwin-node.d.ts

@@ -0,0 +1,151 @@
+/**
+ * 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 type { AgentDefinition, DarwinConfig, RunResult } from "darwin-agents";
+/**
+ * LangGraph HITL detector (R1 Research Finding 5, refined by R2 Research
+ * Finding 1, S1185).
+ *
+ * When `interrupt()` is called inside a downstream node during a
+ * `runAgent` run, LangGraph throws a typed error to surface the HITL
+ * pause. The adapter MUST re-throw that error untouched — wrapping it
+ * in `DarwinNodeError` would swallow the interrupt and break the
+ * `Command({ resume })` protocol.
+ *
+ * Initially (R1) we hand-rolled a `name === "GraphInterrupt"` duck-type.
+ * R2 surfaced two issues with that approach:
+ *   1. Production minifiers (esbuild/Terser/SWC) rewrite class.name
+ *      and constructor.name unless `keep_classnames` is set — breaking
+ *      the constructor-name fallback for bundled consumers.
+ *   2. The real-world case throws `NodeInterrupt` (a `GraphInterrupt`
+ *      subclass), NOT raw `GraphInterrupt`. The hand-rolled string
+ *      check missed it.
+ *
+ * Fix: import `isGraphInterrupt` from `@langchain/langgraph`'s main
+ * entry — it is a stable PUBLIC export and uses LangGraph's internal
+ * `unminifiable_name` static-getter pattern that survives minification
+ * AND covers both `GraphInterrupt` and `NodeInterrupt`. The previous
+ * concern about "internal-ish module paths" was wrong — it lives in the
+ * top-level barrel.
+ */
+/**
+ * Mirror of `darwin-agents` `RunOptions` — narrower because the adapter
+ * sets `taskType` and `promptVersion` implicitly. Exposed as `runOptions`
+ * on {@link CreateDarwinNodeOptions} so consumers can forward
+ * `model` / `maxTurns` / `timeout` / `autonomous` flags to `runAgent`
+ * without re-importing `darwin-agents`.
+ *
+ * If the upstream `RunOptions` shape changes in a future `darwin-agents`
+ * release, the build will break here on purpose — peer-dep semver
+ * guarantees additive-only changes inside the alpha range, but real
+ * drift happens (see `nex_learn fcfc928f`).
+ */
+export interface DarwinRunOptionsPassthrough {
+    model?: string;
+    maxTurns?: number;
+    taskType?: string;
+    config?: DarwinConfig;
+    promptVersion?: string;
+    cwd?: string;
+    timeout?: number;
+    autonomous?: boolean;
+}
+/**
+ * Options accepted by {@link createDarwinNode}.
+ *
+ * All keys are optional. Defaults match the channel names returned by
+ * {@link darwinAnnotation} so the most common case (`createDarwinNode(myAgent)`
+ * inside `darwinAnnotation()`) needs zero configuration.
+ */
+export interface CreateDarwinNodeOptions {
+    /** State property to read the task from. Default: `"task"`. */
+    taskKey?: string;
+    /** State property to write the agent output to. Default: `"output"`. */
+    outputKey?: string;
+    /** State property to write the captured trajectory to. Default: `"darwinTrajectory"`. */
+    trajectoryKey?: string;
+    /**
+     * Passthrough options forwarded to `darwin-agents.runAgent()`. Use this
+     * to override `model`, `maxTurns`, `timeout`, `cwd`, `autonomous`, or to
+     * provide a custom `DarwinConfig` (data dir, MCP servers, etc.).
+     *
+     * Memory resolution lives inside `darwin-agents` itself — set
+     * `DARWIN_POSTGRES_URL` / `DARWIN_SQLITE_PATH` env vars or pass a
+     * `config.dataDir` here. The adapter never instantiates a memory
+     * provider on its own.
+     */
+    runOptions?: DarwinRunOptionsPassthrough;
+    /**
+     * Persist the captured `ExecutionTrace` in graph state. Default `true`.
+     * Set `false` to skip trajectory propagation when memory pressure is a
+     * concern (long-running streams) or when the consumer reads
+     * trajectories from Darwin's own memory backend.
+     */
+    captureTrace?: boolean;
+    /**
+     * Fire-and-forget side-effect after every successful run. Receives the
+     * full `RunResult`. **Errors are swallowed** — never let a callback
+     * break the LangGraph node.
+     */
+    onResult?: (result: RunResult) => void | Promise<void>;
+}
+/**
+ * Type alias for the function returned by {@link createDarwinNode}.
+ * Matches the loose `NodeAction` contract from `@langchain/langgraph`:
+ * `(state, config?) => Promise<Partial<State>>`.
+ */
+export type DarwinNodeFn = (state: Record<string, unknown>, config?: unknown) => Promise<Record<string, unknown>>;
+/**
+ * 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 declare function createDarwinNode(agent: AgentDefinition, opts?: CreateDarwinNodeOptions): DarwinNodeFn;
+//# sourceMappingURL=create-darwin-node.d.ts.map

package/dist/create-darwin-node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-darwin-node.d.ts","sourceRoot":"","sources":["../src/create-darwin-node.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAIH,OAAO,KAAK,EACV,eAAe,EACf,YAAY,EACZ,SAAS,EACV,MAAM,eAAe,CAAC;AAIvB;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,2BAA2B;IAC1C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,uBAAuB;IACtC,+DAA+D;IAC/D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yFAAyF;IACzF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;;;;;OASG;IACH,UAAU,CAAC,EAAE,2BAA2B,CAAC;IACzC;;;;;OAKG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,SAAS,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACxD;AAED;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,CACzB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,MAAM,CAAC,EAAE,OAAO,KACb,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAEtC;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,eAAe,EACtB,IAAI,GAAE,uBAA4B,GACjC,YAAY,CAiFd"}