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

package/CHANGELOG.md

@@ -3,6 +3,212 @@
 All notable changes to `darwin-langgraph` are documented here.
 The project adheres to [Semantic Versioning](https://semver.org/).
 
+## [0.3.0-alpha.1] — 2026-05-25
+
+V0.3 closes the three deferred items from V0.2's R2 review (parent-run
+propagation, double-wrap detection, hung-invoke guard) and lifts the
+repository to the StudioMeyer open-source-standard documentation layout
+(CONTRIBUTING, CODE_OF_CONDUCT, SECURITY, ECOSYSTEM, issue + PR
+templates, GitHub Actions CI matrix on Node 20 + 22).
+
+### Added — three new behaviours + one new option
+
+- **`DarwinTrajectoryEvent.runId` + `.parentRunId`** — propagated by
+  `DarwinCallbackHandler` from the LangChain callback contract. Lets
+  downstream consumers (OTEL exporters, Langfuse, LangSmith, custom
+  span-tree loggers) rebuild the chain hierarchy from the event payload
+  alone without a separate runId-tracking side-channel. `runId` is
+  always present on V0.2+ handler events; `parentRunId` is present
+  only when the chain has a parent (omitted for top-level invokes).
+- **`withDarwinEvolution` double-wrap warning** — a `Symbol.for(...)`
+  sentinel is stamped on each wrapped graph. A second wrap of the same
+  graph instance now emits a one-shot `console.warn` flagging the
+  duplicate-hook footgun. The wrap still succeeds (some users legitimately
+  layer multiple `nodeMap` slices), but the silent-double-fire case
+  is now visible in logs.
+- **`DarwinCallbackHandler` hung-invoke guard** — new option
+  `maxInFlightRuns?: number` on `DarwinCallbackHandlerOptions`. Caps the
+  internal `runId → InFlightRun` map. When the cap is exceeded the
+  oldest entry is evicted (LRU via Map insertion order) and a
+  one-shot warning fires. Defaults to 1024 — small enough to surface
+  real leaks within minutes, large enough for typical fan-out. Set to
+  `Infinity` to opt out.
+
+### Changed
+
+- **`DarwinCallbackHandlerOptions` type exported** alongside
+  `DarwinCallbackHandler`. Was internal in V0.2; now a public type so
+  consumers can build wrapper handlers without re-declaring the shape.
+- **`InFlightRun` shape** — internal change in `DarwinCallbackHandler`:
+  the `runIdToName` map now stores `{ nodeName, parentRunId }` rather
+  than just the name string, to carry parentRunId through to
+  `handleChainEnd`. Non-breaking — only the internal field type changed.
+- **VERSION constant bumped** to `0.3.0-alpha.1` in both `package.json`
+  and `src/index.ts` (verified by `prepublishOnly` script).
+
+### Added — open-source documentation standard
+
+The repo now matches the
+[`temporal-memory-workflows`](https://github.com/studiomeyer-io/temporal-memory-workflows)
+OS-standard layout. New top-level files:
+
+- **`CONTRIBUTING.md`** — folder layout, code-review expectations, PR
+  format, Conventional Commits convention, deprecation contract on
+  `withDarwinEvolution`, adapter-vs-upstream-bugs separation.
+- **`CODE_OF_CONDUCT.md`** — adapted from Contributor Covenant 2.1.
+- **`SECURITY.md`** — disclosure policy, supported versions
+  (`0.3.x` + `0.2.x` security-only), supply-chain stance (no
+  postinstall scripts), defense-in-depth layer breakdown.
+- **`ECOSYSTEM.md`** — where the adapter sits in the StudioMeyer
+  toolkit, pairing notes with `darwin-agents` /
+  `@langchain/langgraph` / `temporal-memory-workflows`, when-to-use-what
+  decision table, sibling-repo links.
+- **`.github/ISSUE_TEMPLATE/{bug_report,feature_request,config}.yml`**
+  — surface-aware bug template, problem-first feature template, contact
+  links routing to upstream where appropriate.
+- **`.github/PULL_REQUEST_TEMPLATE.md`** — surface checklist,
+  zero-hard-dep check, deprecation-contract check, R1/R2 code-review
+  trail field for maintainers.
+- **`.github/workflows/ci.yml`** — Node 20 + 22 matrix, runs
+  `npm ci` → `verify-version-sync` → `typecheck` → `examples:check` →
+  `test` → `build` on every push to `main` and every PR.
+
+### Test coverage
+
+- **132/132 vitest tests green** (was 116 in V0.2, **+16 V0.3 tests**).
+- New test file: `tests/v03-features.test.ts` (16 tests across 4 groups:
+  parent-run propagation, double-wrap warning, hung-invoke timeout
+  guard, `vi.resetModules()` pattern for module-level flag tests).
+- tsc strict + examples typecheck + version-sync + build all clean.
+- No regressions: all V0.1 + V0.2 surface tests + R1 + R2 fixes still
+  green.
+
+### Migration notes
+
+- **From V0.2.x → V0.3.x:** No code changes required. The
+  `runId`/`parentRunId` fields on `DarwinTrajectoryEvent` are optional
+  additions; existing callbacks ignore them. The double-wrap warning
+  only fires if you actually double-wrap (most users do not). The
+  default `maxInFlightRuns: 1024` cap is invisible in normal use.
+- **From V0.1.x → V0.3.x:** Still recommended to migrate from
+  `withDarwinEvolution` to `DarwinCallbackHandler` — see V0.2
+  migration notes in this changelog.
+
+### V0.4 Roadmap (deferred)
+
+- **`reflectionRunPrompt` override on `darwin-agents` (paper-fidelity).**
+  The GEPA paper uses a stronger reflection LM than the task LM. Currently
+  the adapter inherits `darwin-agents@0.5.0-alpha.2`'s single-`runPrompt`
+  implementation. Defer to a paired bump.
+- **OTEL exporter binding helper** — turn the pure `toOtelAttributes`
+  mapping into a one-liner that registers a span per trajectory with
+  a configured tracer.
+- **Langfuse handler subclass** — `DarwinLangfuseHandler` that extends
+  `DarwinCallbackHandler` and emits Langfuse traces directly.
+- **LangSmith trace correlation** — propagate `runId`/`parentRunId`
+  into a LangSmith-compatible attribute set.
+
+## [0.2.0-alpha.1] — 2026-05-25
+
+### Added — three new surfaces (V0.1 roadmap → LIVE)
+
+- **Surface 4: `DarwinCallbackHandler`** — LangChain-native replacement
+  for `withDarwinEvolution`. Subclass of `BaseCallbackHandler` from
+  `@langchain/core/callbacks/base`. Pass via
+  `graph.invoke(input, { callbacks: [new DarwinCallbackHandler({ nodeMap,
+  onTrajectory }) ] })`. No monkey-patching of `invoke` / `stream`,
+  no `Set<symbol>` race-fix needed, no `streamMode` warn — works
+  identically across `invoke`, `stream` (any `streamMode`), and
+  `streamEvents`. Uses `metadata.langgraph_node` as the primary
+  node-name source (live-verified against `@langchain/langgraph@1.3.x`)
+  with the `runName` parameter as fallback for non-LangGraph chains.
+- **Surface 5: `toOtelAttributes(trajectory, opts?)` +
+  `toolCallToOtelAttributes(call, opts?)`** — pure mappers from Darwin's
+  `ExecutionTrace` to flat `Record<string, string|number|boolean>` keyed
+  by [OpenTelemetry GenAI Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/).
+  Spec-compliant cache attribute names
+  (`gen_ai.usage.cache_read.input_tokens` /
+  `gen_ai.usage.cache_creation.input_tokens`). MCP tools correctly map
+  to `gen_ai.tool.type = "extension"` (server-side, calls external APIs)
+  vs `"function"` for builtins. Sensitive `arguments` / `result` fields
+  are opt-in per OTEL spec. NaN/Infinity values dropped from output
+  (OTEL exporter compliance).
+- **Surface 6: `darwinMessagesAnnotation(extra?)`** — variant of
+  `darwinAnnotation` that also includes LangGraph's canonical `messages`
+  channel (`messagesStateReducer`). Use it when your graph mixes Darwin
+  agents with `createReactAgent` / `MessagesAnnotation`-based prebuilt
+  agents. Power-user escape hatch `getMessagesChannelSpec()` exposed
+  for manual `Annotation.Root` composition.
+
+### Changed
+
+- **`withDarwinEvolution` is `@deprecated` since v0.2.0** — JSDoc tag
+  plus a one-shot `console.warn` on first call (process-level, never
+  spam). Will be **removed in v1.0.0**. Migration is two lines (see
+  README "Migration from v0.1.x to v0.2.x").
+- **VERSION constant bumped** to `0.2.0-alpha.1` in both `package.json`
+  and `src/index.ts` (verified by `prepublishOnly` script).
+
+### Fixed (R1 + R2 V0.2 code-review findings, all in-place pre-publish)
+
+The 3-Agent code-review loop ran twice on V0.2. R1 surfaced 10 findings,
+R2 caught 1 HIGH that R1 missed. All addressed before this release.
+
+**R1 — 6 MUST-FIX (S1185):**
+
+1. **CRITICAL (Critic 1):** `firedRuns: Set<string>` in
+   `DarwinCallbackHandler` was an unbounded memory leak for long-lived
+   handlers (e.g. server singletons). Removed — `runIdToName.delete` is
+   the sole dedup and LangGraph guarantees one `handleChainEnd` per
+   `runId`.
+2. **HIGH (Critic 2):** `isExecutionTrace` only checked `version === 1`
+   — a malformed trajectory could pass and crash downstream
+   `toOtelAttributes(trajectory.toolCalls.length)`. Guard now also
+   requires `Array.isArray(toolCalls)` + `Array.isArray(errors)`.
+   `toOtelAttributes` got defensive fallbacks too.
+3. **HIGH (Critic 3 + 7):** `typeof === "number"` passed `NaN` and
+   `Infinity` through to OTEL exporters (silent span drop). All numeric
+   attributes (token usage, durationMs, turn, textBlockCount, turnCount,
+   mcpInvocations) now use `Number.isFinite`.
+4. **HIGH (Research 1):** OTEL spec uses
+   `gen_ai.usage.cache_read.input_tokens` /
+   `cache_creation.input_tokens` per the official attribute registry,
+   not the short `cache_*_tokens` form we initially emitted. Fixed
+   pre-release (zero-cost rename in alpha).
+5. **HIGH (Research 3):** MCP tools execute server-side and call
+   external APIs — `gen_ai.tool.type` must be `"extension"`, not
+   `"function"`. Adapter now routes on the existing `is_mcp` heuristic.
+6. **MED (Critic 5):** `swallow(err)` used `if (warned || !err)` which
+   silently dropped falsy throws (`throw null` etc). Fixed in
+   `DarwinCallbackHandler.swallow`.
+
+**R2 — 1 HIGH (caught what R1 missed, S1185):**
+
+7. **HIGH (R2 Critic R2-1):** R1's fix #6 was applied to
+   `DarwinCallbackHandler.swallow` but NOT to the parallel `swallow`
+   inside `withDarwinEvolution`. Both now consistent.
+
+### Known limitations carried to V0.3
+
+- **`withDarwinEvolution` module-level deprecation flag** is not reset
+  across tests in the same process (R2 Critic R2-2). Acceptable for
+  one-shot warn semantics; testing the contract requires
+  `vi.resetModules()`.
+- **Double-wrapping `withDarwinEvolution` on the same graph instance**
+  is unsupported and produces no clear error (R2 Critic R2-3). Use
+  `DarwinCallbackHandler` instead — composable by default.
+- **Parent-run propagation** on `DarwinTrajectoryEvent` not exposed
+  yet (R1 Research 5). Planned for V0.3 — needs use-case validation.
+
+### Test coverage
+
+- **116/116 vitest tests green** (was 63 in V0.1).
+- New test files: `tests/darwin-callback-handler.test.ts` (14),
+  `tests/to-otel-attributes.test.ts` (18),
+  `tests/darwin-messages-annotation.test.ts` (7),
+  `tests/r2-v02-fixes.test.ts` (10 R1+R2 regression).
+- tsc strict + examples typecheck + version-sync + build all clean.
+
 ## [0.1.0-alpha.1] — 2026-05-24
 
 ### Added
@@ -37,9 +243,12 @@ controls the installed versions and the adapter never pins them.
 
 - 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`.
+  `ExecutionTrace` capture). Because `0.1.0-alpha.1` is the very
+  first publish of this package, npm assigns BOTH `alpha` and
+  `latest` to it (npm rule: `latest` always exists), so
+  `npm install darwin-langgraph` resolves to the alpha version
+  until `0.1.0` final ships. Prefer the explicit
+  `npm install darwin-langgraph@alpha` form for clarity.
 - 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.

package/README.md

@@ -202,26 +202,147 @@ The [`examples/`](./examples/) directory ships three runnable scripts:
 
 | `darwin-langgraph` | `darwin-agents` | `@langchain/langgraph` | Status |
 |---|---|---|---|
-| `0.1.0-alpha.x` | `^0.5.0-alpha.1` | `^1.3.0` | alpha (this release) |
+| `0.3.0-alpha.x` | `^0.5.0-alpha.1` | `^1.3.0` | alpha (this release) |
+| `0.2.0-alpha.x` | `^0.5.0-alpha.1` | `^1.3.0` | superseded |
+| `0.1.0-alpha.x` | `^0.5.0-alpha.1` | `^1.3.0` | superseded |
 
 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)
+## V0.3 — observability + safety (LIVE this release)
 
-- **`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.
+V0.3 closes the three deferred items from V0.2's R2 review. Backwards
+compatible — no consumer code changes required.
+
+### Parent-run propagation on `DarwinTrajectoryEvent`
+
+`DarwinCallbackHandler` now populates two new fields on every emitted
+event:
+
+- **`runId: string`** — the LangChain runId of the node-chain that
+  produced the trajectory. Stable identifier suitable for correlation
+  with OTEL spans, Langfuse traces, LangSmith runs.
+- **`parentRunId?: string`** — the runId of the chain that invoked
+  this node-chain. Omitted for top-level invokes. Use it to build the
+  full span hierarchy in OTEL exporters.
+
+```ts
+const handler = new DarwinCallbackHandler({
+  nodeMap: { research: "researcher" },
+  onTrajectory: (event) => {
+    const attrs = toOtelAttributes(event.trajectory);
+    const span = tracer.startSpan(event.nodeName, {
+      attributes: { ...attrs, "darwin.run.id": event.runId },
+    });
+    // event.parentRunId can be used as the parent context for span linking
+    span.end();
+  },
+});
+```
+
+`withDarwinEvolution` legacy events do NOT carry the runId fields (no
+runId exists in the monkey-patch path). Migrate to
+`DarwinCallbackHandler` if you need them.
+
+### Double-wrap warning on `withDarwinEvolution`
+
+A `Symbol.for("darwin-langgraph.evolution.wrapped")` sentinel is now
+stamped on each wrapped graph. A second `withDarwinEvolution(graph, …)`
+call on the same graph instance emits a one-shot `console.warn`:
+
+```
+[darwin-langgraph] withDarwinEvolution(): graph appears to be wrapped twice
+  — both hooks will fire per run, producing duplicate trajectories.
+```
+
+Some users legitimately layer multiple `nodeMap` slices on one graph,
+so the wrap still succeeds — but the silent-double-fire footgun is now
+visible in logs. To layer cleanly, prefer multiple
+`DarwinCallbackHandler` instances via `callbacks: [h1, h2]`.
+
+### Hung-invoke guard on `DarwinCallbackHandler`
+
+New option `maxInFlightRuns?: number` on
+`DarwinCallbackHandlerOptions`. Caps the internal `runId → InFlightRun`
+map at the configured size. When the cap is exceeded, the oldest
+entry is evicted (Map insertion order) and a one-shot warning fires.
+Defaults to **1024** — large enough for typical fan-out, small enough
+to surface a real leak within minutes of an incident.
+
+```ts
+const handler = new DarwinCallbackHandler({
+  nodeMap: { research: "researcher" },
+  onTrajectory: (event) => { /* ... */ },
+  maxInFlightRuns: 500,  // tighter for memory-constrained workers
+});
+```
+
+Set `maxInFlightRuns: Infinity` to opt out (discouraged in production).
+
+This defends against the failure mode where `handleChainEnd` /
+`handleChainError` never fires (LangGraph internal bug, OS-level kill
+of the worker mid-invoke, parent invoke aborted mid-flight). Without
+the cap, the map grows without bound and leaks memory in long-running
+processes (server singletons, schedulers, Temporal Workers).
+
+### V0.2 — new surfaces (still LIVE)
+
+V0.2 ships the three items from the V0.1 V0.2-roadmap, plus runtime
+deprecation warnings on the legacy wrapper:
+
+- **`DarwinCallbackHandler`** — LangChain-native replacement for
+  `withDarwinEvolution`. Pass it via `graph.invoke(input, { callbacks:
+  [new DarwinCallbackHandler({ nodeMap, onTrajectory }) ] })`. No more
+  monkey-patching `invoke`/`stream`, no more `Set<symbol>` race-fix,
+  no more `streamMode` gymnastics. Works identically with `invoke`,
+  `stream` (any `streamMode`), and `streamEvents` because LangChain's
+  callback mechanism fires regardless of how the consumer iterates.
+- **`toOtelAttributes(trajectory, opts?)` + `toolCallToOtelAttributes(call, opts?)`** —
+  pure mappers from Darwin's `ExecutionTrace` to flat
+  `Record<string, string|number|boolean>` keyed by
+  [OpenTelemetry GenAI Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/)
+  (`gen_ai.operation.name`, `gen_ai.usage.input_tokens`, etc.) plus
+  Darwin-namespaced custom attrs. Drop straight into Langfuse,
+  Braintrust, Honeycomb, Datadog. Sensitive `arguments` / `result`
+  fields are opt-in per OTEL spec.
+- **`darwinMessagesAnnotation(extra?)`** — variant of `darwinAnnotation`
+  that also includes LangGraph's canonical `messages` channel
+  (`messagesStateReducer`). Use it when your graph mixes Darwin agents
+  with `createReactAgent` / `MessagesAnnotation`-based prebuilt agents.
+- **Runtime deprecation warning on `withDarwinEvolution`** — fires once
+  per process on first call. The function still works identically for
+  back-compat; it will be removed in v1.0. Migrate to
+  `DarwinCallbackHandler`.
+
+## Migration from v0.1.x to v0.2.x
+
+Two lines:
+
+```diff
+- import { withDarwinEvolution } from "darwin-langgraph";
++ import { DarwinCallbackHandler } from "darwin-langgraph";
+- const graph = withDarwinEvolution(compiledGraph, { nodeMap, onTrajectory });
+- const result = await graph.invoke(input);
++ const handler = new DarwinCallbackHandler({ nodeMap, onTrajectory });
++ const result = await compiledGraph.invoke(input, { callbacks: [handler] });
+```
+
+`DarwinEvolutionOptions`, `DarwinNodeMapEntry`, and the
+`DarwinTrajectoryEvent` shape passed to `onTrajectory` are 100% identical
+between both APIs — no other code changes required.
+
+## Migration from v0.2.x to v0.3.x
+
+**No code changes required.** V0.3 is purely additive:
+
+- `event.runId` and `event.parentRunId` are new optional fields — existing
+  callbacks that don't read them keep working untouched.
+- The double-wrap warning only fires if you actually double-wrap (most
+  users do not).
+- The default `maxInFlightRuns: 1024` is invisible in normal use. Override
+  only if you have memory pressure or want to opt out via `Infinity`.
 
 The adapter releases follow `darwin-agents` major bumps. When
 `@langchain/langgraph` 2.x lands, the adapter ships a new major within
@@ -267,9 +388,20 @@ delete process.env.ANTHROPIC_API_KEY; // enforce Max-Plan subscription
 ## 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`.
+`darwin-agents@0.5.0-alpha.1`. Because `0.1.0-alpha.1` is the FIRST
+publish, npm assigns BOTH `alpha` and `latest` to it (npm rule: a
+package must always have a `latest` tag) — so `npm install
+darwin-langgraph` and `npm install darwin-langgraph@alpha` resolve to
+the same version right now. Once `0.1.0` final ships, `latest` will
+point to the stable release and `alpha` will continue to track
+pre-releases.
+
+For maximum clarity in alpha-stage projects, prefer the explicit
+opt-in form:
+
+```bash
+npm install darwin-langgraph@alpha @langchain/langgraph darwin-agents@alpha
+```
 
 ## License
 

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

@@ -0,0 +1,134 @@
+/**
+ * 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 type { ChainValues } from "@langchain/core/utils/types";
+import type { DarwinEvolutionOptions } from "./with-darwin-evolution.js";
+/**
+ * V0.3 — extra options on top of `DarwinEvolutionOptions`. Pass to
+ * `new DarwinCallbackHandler({ ...opts, maxInFlightRuns })`.
+ *
+ * NEW V0.3 (S1187).
+ */
+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;
+}
+/**
+ * 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 declare class DarwinCallbackHandler extends BaseCallbackHandler {
+    readonly name = "DarwinCallbackHandler";
+    readonly awaitHandlers = false;
+    private readonly resolved;
+    private readonly 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).
+     */
+    private readonly runIdToName;
+    private readonly maxInFlightRuns;
+    private warned;
+    private evictionWarned;
+    constructor(opts: DarwinCallbackHandlerOptions);
+    /**
+     * 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: 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.
+     *
+     * `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: ChainValues, runId: string, _parentRunId?: string, _tags?: string[], _kwargs?: {
+        inputs?: ChainValues;
+    }): void;
+    /**
+     * 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: Error, runId: string, _parentRunId?: string): void;
+    private swallow;
+    /**
+     * Helper for tests + debug introspection — returns how many in-flight
+     * chain runs we are currently tracking. Should be 0 between
+     * top-level invocations.
+     */
+    getInFlightCount(): number;
+}
+//# sourceMappingURL=darwin-callback-handler.d.ts.map

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

@@ -0,0 +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;AAEpC;;;;;GAKG;AACH,MAAM,WAAW,4BAA6B,SAAQ,sBAAsB;IAC1E;;;;;;;;;;;;OAYG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAoED;;;;;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;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAuC;IACnE,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,cAAc,CAAS;gBAEnB,IAAI,EAAE,4BAA4B;IAsB9C;;;;;;;;;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,WAAW,CAAC,EAAE,MAAM,EACpB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,IAAI;IAkDP;;;;;;;;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;IAwCP;;;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"}