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

package/CHANGELOG.md

@@ -3,6 +3,249 @@
 All notable changes to `darwin-langgraph` are documented here.
 The project adheres to [Semantic Versioning](https://semver.org/).
 
+## [0.4.0-alpha.1] — 2026-05-29
+
+V0.4 is an additive release that closes the V0.3 R2 deferrals and lands
+nine new surfaces driven by a research sweep across LangGraph 1.3, the
+OpenTelemetry GenAI Semantic Conventions registry, and the LangGraph
+TypeScript Production Guide. **Zero breaking changes** — every existing
+V0.3 consumer keeps working unchanged.
+
+### Added — nine new surfaces
+
+- **`DarwinCallbackHandler.onToolEvent`** — new option that fires for
+  every LangGraph tool-chain start / end / error inside a tracked node.
+  Emits a `DarwinToolEvent` (`phase: "start" | "end" | "error"`) with
+  `toolName`, `runId`, `parentRunId`, plus `input` / `output` / `error`
+  depending on phase. Use it to emit per-tool OTEL spans, drive progress
+  UIs, or wire abort-on-tool-failure logic. The handler now also caches
+  tool names internally so end / error events get the same name the
+  start event reported, even when the LangChain tool-end signature does
+  not carry the name (LangChain 0.3 quirk).
+- **`DarwinCallbackHandler` `maxTrajectoryBytes`** — soft cap (default
+  `262_144` = 256 KiB) on the serialised trajectory size emitted via
+  `onTrajectory`. Oversized trajectories are replaced with a
+  structurally-compatible BUT minimal stub (counts + `capturedAt` +
+  `tokenUsage` preserved, `toolCalls` / `errors` replaced with empty
+  arrays). The event payload gains a new `trajectoryTruncated: true`
+  field so consumers can branch. Circular-reference trajectories are
+  caught defensively and treated as oversized. `tokenUsage` is shallow-
+  copied and `bigint` token counters are coerced to `number` so
+  downstream `JSON.stringify` never trips.
+- **`MAX_KNOWN_TRACE_VERSION` + forward-compat `isExecutionTrace`** —
+  the handler now accepts `version >= 1` and warns once per process when
+  a higher-than-known version is observed. The accumulator reducer,
+  `withDarwinEvolution`, and `toOtelAttributes` all share the same
+  widening so a future `darwin-agents` schema bump does not silently
+  drop trajectories anywhere on the pipeline.
+- **`toOtelAttributes` LangGraph + OTel cross-cutting attributes** —
+  four new options. `langGraphNode` and `langGraphStep` emit
+  `gen_ai.langgraph.node` / `gen_ai.langgraph.step` per the Coralogix /
+  Last9 / Honeycomb LangGraph instrumentation convention. `userId` emits
+  BOTH the OTel-spec-canonical `enduser.id` (cross-cutting) AND the
+  historical alias `gen_ai.request.user` so dashboards on either
+  convention keep working. `conversationId` emits the spec-correct
+  `gen_ai.conversation.id` (typically the LangGraph `thread_id`).
+  `requestId` emits `gen_ai.request.id`.
+- **`createDarwinNode.onAttempt`** — config-aware passthrough that
+  fires before `runAgent` with the runtime info LangGraph surfaces.
+  Reads `nodeAttempt` from `config.runtime.executionInfo` (per
+  LangGraph PR #7363, surfacing `1` on first execution and incrementing
+  per retry under an `addNode(name, fn, { retryPolicy })` policy),
+  `nodeFirstAttemptTime` from the same source (per PR #7363 for
+  retry-latency computation), `langGraphStep` from
+  `config.metadata.langgraph_step` (the canonical LangGraph 1.3 source —
+  NOT `executionInfo`), and `threadId` from `config.configurable.thread_id`.
+  Pairs naturally with LangGraph's native `retryPolicy` without adding
+  a competing retry layer.
+- **`darwinAccumulatingAnnotation`** + **`darwinTrajectoryAccumulatorReducer`**
+  + **`getDarwinAccumulatingChannelSpec`** — variant of `darwinAnnotation`
+  that replaces the singleton `darwinTrajectory: ExecutionTrace | undefined`
+  channel with an accumulating `darwinTrajectories: ExecutionTrace[]`
+  channel. Use it when you orchestrate multiple Darwin nodes in a graph
+  (fan-out, sequential pipeline, supervisor) and want every trajectory
+  preserved in state without declaring a per-node trace channel by
+  hand. The reducer accepts a single `ExecutionTrace` (matching the
+  bare `createDarwinNode` contract) or `ExecutionTrace[]` (batch
+  append) and drops non-`version >= 1` shapes defensively. The
+  annotation throws when the optional `extra` argument tries to redefine
+  one of the Darwin-managed channels (`task`, `output`,
+  `darwinTrajectories`) — a previously silent contract footgun.
+- **`createTokenBudgetCallbacks(opts)`** + **`TokenBudgetCallbackHandler`**
+  + **`DarwinTokenBudgetExceededError`** — production-pattern from the
+  LangGraph TypeScript Production Guide. Enforces a per-invocation
+  token budget across all LLM calls inside the graph. Extracts tokens
+  from `output.llmOutput.tokenUsage.totalTokens` (LangChain canonical
+  for ChatOpenAI / ChatAnthropic) and falls back to summing per-message
+  `generations[][].message.usage_metadata` (Anthropic native + others).
+  Throws the typed `DarwinTokenBudgetExceededError` on breach so
+  callers can `instanceof`-check without parsing message text.
+  `awaitHandlers = true` so LangChain awaits the handler and the
+  synchronous throw reliably reaches the `graph.invoke` caller.
+  Constructor validates the budget is a finite positive integer
+  (NaN / Infinity / 0 / negative / non-integer all throw eagerly).
+- **`toW3CTraceContext(event, opts?)`** — pure mapper from
+  `DarwinTrajectoryEvent` to a [W3C Trace Context](https://www.w3.org/TR/trace-context/)
+  `traceparent` header value (`00-<32hex>-<16hex>-(00|01)`). When the
+  event has no `parentRunId`, the spanId is taken from the SECOND 16
+  hex of the runId so it is never a prefix of the traceId — several
+  OTEL backends (Datadog APM, Honeycomb classic) reject or misroute
+  spans whose ids look like self-parents. When the event has a valid
+  `parentRunId`, the traceId is taken from the parent and the spanId
+  from the first 16 hex of the runId. Returns `undefined` for malformed
+  / non-UUID runIds and for the all-zero strings the W3C spec forbids.
+- **Example 04 — OTEL + W3C + token budget**
+  (`examples/04-otel-and-budget.ts`). End-to-end wiring of every new
+  V0.4 surface against a console-only span emitter so the example
+  runs without external services; swap in a real OTLP exporter or
+  Langfuse SDK at the marked line.
+
+### Added — error class
+
+- **`DarwinTokenBudgetExceededError`** — thrown by
+  `TokenBudgetCallbackHandler` on breach AND eagerly on construction
+  when the configured budget is invalid. Exposes `budget`, `totalTokens`,
+  and `providerHint` (`modelName` / `model_name` extracted from the
+  LLMResult when present) so callers can branch on cost / provider.
+
+### Changed
+
+- **`DarwinTrajectoryEvent` extended** with optional `trajectoryTruncated`
+  field — set to `true` when `DarwinCallbackHandler.maxTrajectoryBytes`
+  replaces the trajectory with a stub. Omitted (not `false`) when the
+  trajectory passed through unchanged.
+- **`InFlightRun` shape** in `DarwinCallbackHandler` — internal change,
+  the `runIdToName` map now stores `{ nodeName, parentRunId, pendingTools,
+  finalized }`. The two new fields drive the R1 P1-4 fix that keeps
+  chain entries alive past `handleChainEnd` until pending tool events
+  have surfaced so `onToolEvent` callbacks for late-completing tools
+  are no longer silently dropped.
+- **VERSION constant bumped** to `0.4.0-alpha.1` in both `package.json`
+  and `src/index.ts` (verified by `prepublishOnly` script).
+
+### Fixed (R1 + R2 code-review-loop pre-publish)
+
+A three-agent R1 review (Critic + Analyst + Research) followed by an
+R2 critic verification + R3 grep self-check surfaced and closed ten
+issues before publish:
+
+- **P0-1 — W3C trace context self-parent collision.** Top-level
+  invokes derived BOTH `traceId` and `spanId` from the first 16 chars
+  of the same UUID, producing `traceparent` headers where the spanId
+  was a prefix of the traceId. Several OTEL backends reject those as
+  self-parents. Fix: when no `parentRunId`, `spanId = runHex.slice(16, 32)`.
+- **P0-2 — Forward-compat version drift.** The accumulator reducer
+  strict-equality-checked `version === 1` while `isExecutionTrace`
+  accepted `version >= 1`. The same widening was also missed in
+  `toOtelAttributes` and the legacy `withDarwinEvolution` wrapper.
+  All four sites now share the same `version >= 1 && Number.isFinite`
+  gate so a v=2 trajectory flows through every code path consistently.
+- **P1-1 — Tool name lost between start and end.** `handleToolEnd`
+  tried to read `output.name`, which is absent for the common
+  `ToolNode` case (output is a plain string). Fix: cache the name
+  from `handleToolStart` keyed by tool runId; consume it in
+  `handleToolEnd` / `handleToolError`. Falls back to `output.name`
+  when the start was missed.
+- **P1-2 — `buildTruncatedTrace` aliased original `tokenUsage`.**
+  The stub kept a reference to the original (potentially `bigint`-
+  carrying) `tokenUsage` object, breaking downstream `JSON.stringify`.
+  Fix: shallow copy via `Object.fromEntries(Object.entries(...))` and
+  coerce `bigint` values to `number`.
+- **P1-4 — Pending tool events vs `handleChainEnd` race.** Chains
+  with long-running tools sometimes saw `handleChainEnd` synchronously
+  delete the `runIdToName` entry before the matching
+  `handleToolEnd` / `handleToolError` arrived. Fix: reference-count
+  pending tools per chain (`InFlightRun.pendingTools`). `handleChainEnd`
+  marks the entry `finalized` instead of deleting it; the last tool
+  callback drains a deferred trajectory dispatch and cleans up.
+- **Research-1 — `gen_ai.request.user` is not OTel-canonical.** The
+  GenAI semconv registry defines `gen_ai.conversation.id` and the
+  cross-cutting `enduser.id` for user / session identity, not
+  `gen_ai.request.user`. Fix: emit both the canonical `enduser.id`
+  AND the historical alias `gen_ai.request.user` (older Coralogix /
+  Last9 dashboards key off the alias). New `conversationId` option
+  emits the spec-correct `gen_ai.conversation.id`.
+- **Research-2 — `langGraphStep` source path corrected.** LangGraph
+  1.3 surfaces the step counter in `config.metadata.langgraph_step`,
+  not `executionInfo.langGraphStep`. Fix: `createDarwinNode` reads
+  from the correct path and additionally surfaces
+  `nodeFirstAttemptTime` from `executionInfo` (per LangGraph PR
+  #7363) for retry-latency math.
+- **P2-2 — `darwinAccumulatingAnnotation` reserved-key silent
+  overwrite.** Passing `extra = { darwinTrajectories: customAnnotation }`
+  silently replaced the accumulator channel with no warning. Fix:
+  throws on any `extra` key that conflicts with `task` / `output` /
+  `darwinTrajectories`.
+- **P2-3 — `TokenBudgetCallbackHandler.awaitHandlers = false`.**
+  With `awaitHandlers = false` LangChain may not await the handler;
+  the synchronous throw inside `handleLLMEnd` could surface as an
+  unhandled rejection rather than aborting the graph. Fix:
+  `awaitHandlers = true` (the throw IS the abort signal).
+- **R2 MUST-FIX — `toOtelAttributes` strict version guard.** The R1
+  P0-2 widening was applied to the accumulator reducer and the
+  callback-handler `isExecutionTrace` but missed in `toOtelAttributes`
+  (which still threw `TypeError` on v=2 trajectories). The R2 critic
+  caught it; the same forward-compat guard now lives in all four
+  trajectory consumers.
+
+### Test coverage
+
+- **241/241 vitest tests green** (was 132 in V0.3, **+109 V0.4 tests**
+  across `tests/token-budget.test.ts`, `tests/to-w3c-trace-context.test.ts`,
+  `tests/darwin-accumulating-annotation.test.ts`, `tests/v04-features.test.ts`,
+  `tests/r1-v04-fixes.test.ts`).
+- New regression-test file `tests/r1-v04-fixes.test.ts` (28 tests across
+  10 R1+R2 fix groups) pins each fix so a future patch cannot regress
+  the corrected behaviour silently.
+- `tsc --strict --noEmit` clean (src + examples).
+- `npm run build` clean — all V0.4 surface additions ship in `dist/`.
+
+### V0.5 backlog (deferred from R1 + R2)
+
+- **Per-tool size cap** alongside `maxTrajectoryBytes` (instead of the
+  per-trajectory level — surgical truncation of one fat tool result
+  rather than the whole agent).
+- **`gen_ai.provider.name` + `gen_ai.request.model` + `gen_ai.response.model`
+  + `gen_ai.response.finish_reasons`** — spec-required OTel GenAI
+  attributes V0.4 does not yet emit.
+- **`gen_ai.workflow.*` parallel emission** — Traceloop RFC #3460
+  proposes `gen_ai.workflow.current_node` as the canonical successor
+  to `gen_ai.langgraph.node`. Emit both during the transition.
+- **`gen_ai.usage.reasoning.output_tokens`** for Claude extended
+  thinking / Opus 4.x reasoning models.
+- **`gen_ai.usage.cache_*` rollup into the token-budget total** with
+  an `countCacheTokens?: boolean` flag — Anthropic prompt caching can
+  shift 90% of effective tokens into the cache bucket.
+- **Bedrock LLMResult shape** in `extractTokenDelta` (third branch
+  alongside ChatOpenAI canonical + per-message `usage_metadata`).
+- **`getMessagesAccumulatingChannelSpec`** + companion
+  `darwinMessagesAccumulatingAnnotation` for graphs mixing
+  `createReactAgent` with multi-Darwin fan-out.
+- **Explicit `@langchain/core` peer dep declaration** in `package.json`
+  (currently implicit via `@langchain/langgraph` peer dep).
+- **`MAX_KNOWN_TRACE_VERSION` migration to `darwin-agents`** — let the
+  upstream library own the constant so the adapter dependency drift
+  becomes a peer-dep semver failure rather than a runtime warn.
+- **`tools/list` notification handler** in `streamEvents` v3 — separate
+  V0.5 surface that fires on tool-list changes without polling.
+- **`tool_result` content-block streaming events** when LangGraph 1.4
+  surfaces them through the callback contract.
+
+### Migration from V0.3
+
+None required. V0.4 is additive. Existing consumers can adopt the new
+surfaces incrementally:
+
+- Adopt `DarwinCallbackHandler.onToolEvent` to emit per-tool spans.
+- Wrap `graph.invoke` with `createTokenBudgetCallbacks(...)` to enforce
+  a cost ceiling.
+- Pass `event` through `toW3CTraceContext(event)` and attach the
+  `traceparent` header to outgoing HTTP calls for cross-process span
+  correlation.
+- Swap `darwinAnnotation()` for `darwinAccumulatingAnnotation()` when
+  you orchestrate more than one Darwin node and want every trajectory
+  preserved.
+
 ## [0.3.0-alpha.1] — 2026-05-25
 
 V0.3 closes the three deferred items from V0.2's R2 review (parent-run

package/README.md

@@ -72,7 +72,24 @@ console.log(result.output);
 console.log("trajectory:", result.darwinTrajectory);
 ```
 
-## Three surfaces
+## Surfaces (V0.4 — 11 total)
+
+V0.4 adds six new surfaces on top of the V0.3 baseline. Every addition
+is additive — existing V0.3 code keeps working. The full list:
+
+| # | Name | When to use |
+|---|---|---|
+| 1 | `createDarwinNode(agent, opts?)` | Wrap one Darwin agent as a `StateGraph` node. |
+| 2 | `darwinAnnotation(extra?)` | Annotation with `task` + `output` + singleton `darwinTrajectory` channel. |
+| 3 | `withDarwinEvolution(graph, opts)` *(deprecated since V0.2)* | Legacy monkey-patch wrapper — migrate to `DarwinCallbackHandler`. |
+| 4 | `DarwinCallbackHandler` *(V0.2)* | LangChain-native callback handler with `onTrajectory` + V0.4 `onToolEvent` + V0.4 `maxTrajectoryBytes`. |
+| 5 | `toOtelAttributes(trajectory, opts?)` *(V0.2)* | Map an `ExecutionTrace` to OpenTelemetry GenAI Semantic Conventions attributes. V0.4 adds `langGraphNode` / `langGraphStep` / `userId` / `conversationId` / `requestId`. |
+| 6 | `darwinMessagesAnnotation(extra?)` *(V0.2)* | Annotation with a `messages` channel for `createReactAgent` interop. |
+| 7 | `darwinAccumulatingAnnotation(extra?)` *(V0.4)* | Annotation with an accumulating `darwinTrajectories: ExecutionTrace[]` channel — every node write appends instead of overwriting. |
+| 8 | `createTokenBudgetCallbacks(opts)` *(V0.4)* | Production guard — throws `DarwinTokenBudgetExceededError` when a per-invocation token budget is breached. |
+| 9 | `toW3CTraceContext(event, opts?)` *(V0.4)* | Pure mapper to a W3C `traceparent` header value for cross-process span correlation. |
+| 10 | `MAX_KNOWN_TRACE_VERSION` *(V0.4 const)* | Highest `ExecutionTrace.version` this adapter natively understands; `isExecutionTrace` warns once on higher versions but emits them anyway. |
+| 11 | Error classes | `DarwinNodeError` + `DarwinEvolutionHookError` + V0.4 `DarwinTokenBudgetExceededError`. |
 
 ### 1. `createDarwinNode(agent, opts?)`
 

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

@@ -77,6 +77,43 @@ export interface DarwinRunOptionsPassthrough {
     timeout?: number;
     autonomous?: boolean;
 }
+/**
+ * V0.4 (S1235) — runtime info surfaced from the LangGraph `RunnableConfig`
+ * for the `onAttempt` callback. Lets consumers branch on retries (e.g.
+ * fall back to a cheaper model after the first attempt fails — the
+ * canonical LangGraph retryPolicy pattern from
+ * langchain.com/oss/javascript/langgraph/use-graph-api#access-execution-info-inside-a-node).
+ *
+ * `nodeAttempt` is `1` for the first execution; if a retry policy is
+ * attached via `addNode("name", fn, { retryPolicy })` and the node
+ * throws, LangGraph re-fires with `nodeAttempt = 2`, etc.
+ *
+ * NEW V0.4 (S1235).
+ */
+export interface DarwinNodeAttemptInfo {
+    /** Current attempt number (1-indexed, increments per retry). */
+    nodeAttempt: number;
+    /**
+     * LangGraph step counter for this node execution within the graph
+     * run. Read from `config.metadata.langgraph_step` (the canonical
+     * 1.3.x source) — R1 Research Finding 2 (S1235) corrected the
+     * source: it is metadata, NOT `executionInfo`.
+     */
+    langGraphStep?: number;
+    /**
+     * V0.4 (R1 Research Finding 2, S1235) — first-attempt timestamp as
+     * ISO 8601 string when LangGraph surfaces it. Useful to compute
+     * retry-attempt latency in fallback paths. Read from
+     * `config.runtime.executionInfo.nodeFirstAttemptTime` per
+     * LangGraph PR #7363 — value may be `null` on Platform-managed
+     * graphs (PR #7406 workaround).
+     */
+    nodeFirstAttemptTime?: string;
+    /** LangGraph thread id (from `config.configurable.thread_id`). */
+    threadId?: string;
+    /** Raw runtime info object — passed through for power-users. */
+    raw: Record<string, unknown> | undefined;
+}
 /**
  * Options accepted by {@link createDarwinNode}.
  *
@@ -115,6 +152,24 @@ export interface CreateDarwinNodeOptions {
      * break the LangGraph node.
      */
     onResult?: (result: RunResult) => void | Promise<void>;
+    /**
+     * V0.4 — Fired before `runAgent` with the runtime info LangGraph
+     * surfaces via `config.runtime.executionInfo`. Use this to:
+     *   - Log retry behaviour (`nodeAttempt > 1` means LangGraph's
+     *     retryPolicy decided to retry).
+     *   - Switch to a cheaper / faster fallback model on retries
+     *     (mutate `runOptions` via closure capture).
+     *   - Forward step / thread context to upstream tracing systems.
+     *
+     * Pairs naturally with LangGraph's `addNode(name, fn, { retryPolicy })`
+     * — the adapter does NOT add its own retry layer (would conflict).
+     *
+     * **Errors are swallowed** with a one-shot warn per node, same contract
+     * as `onResult`.
+     *
+     * NEW V0.4 (S1235).
+     */
+    onAttempt?: (info: DarwinNodeAttemptInfo) => void | Promise<void>;
 }
 /**
  * Type alias for the function returned by {@link createDarwinNode}.

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

@@ -1 +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"}
+{"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;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,qBAAqB;IACpC,gEAAgE;IAChE,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;;;OAOG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,kEAAkE;IAClE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gEAAgE;IAChE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;CAC1C;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;IACvD;;;;;;;;;;;;;;;;OAgBG;IACH,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,qBAAqB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnE;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,CAqJd"}

package/dist/create-darwin-node.js

@@ -68,11 +68,13 @@ export function createDarwinNode(agent, opts = {}) {
     const captureTrace = opts.captureTrace !== false;
     const agentName = agent.name;
     const onResult = opts.onResult;
+    const onAttempt = opts.onAttempt;
     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) {
+    let onAttemptWarned = false;
+    return async function darwinNode(state, config) {
         if (state === null || typeof state !== "object") {
             throw new DarwinNodeError(`createDarwinNode(${agentName}): state must be an object, got ${typeof state}.`, agentName);
         }
@@ -81,6 +83,59 @@ export function createDarwinNode(agent, opts = {}) {
             throw new DarwinNodeError(`createDarwinNode(${agentName}): state["${taskKey}"] must be a non-empty string, ` +
                 `got ${rawTask === undefined ? "undefined" : typeof rawTask}.`, agentName);
         }
+        // V0.4 (S1235): surface LangGraph runtime info to the optional
+        // onAttempt callback. The shape of `config.runtime.executionInfo` is
+        // defined in @langchain/langgraph 1.3+ via PR #7363 (2026-03-31).
+        //
+        // R1 Research Finding 2 fix (S1235): `langGraphStep` does NOT live
+        // on `executionInfo` — it is in `config.metadata.langgraph_step`.
+        // `executionInfo` carries `nodeAttempt` and `nodeFirstAttemptTime`
+        // among other identifiers. We read both defensively so older
+        // LangGraph versions don't crash this node.
+        if (onAttempt && config && typeof config === "object") {
+            const c = config;
+            const runtime = c.runtime;
+            const executionInfo = runtime?.executionInfo;
+            const metadata = c.metadata;
+            const configurable = c.configurable;
+            const nodeAttempt = typeof executionInfo?.nodeAttempt === "number" &&
+                Number.isFinite(executionInfo.nodeAttempt) &&
+                executionInfo.nodeAttempt >= 1
+                ? executionInfo.nodeAttempt
+                : 1;
+            // R1 Research Finding 2: langgraph_step lives in metadata.
+            const rawStep = metadata?.["langgraph_step"];
+            const langGraphStep = typeof rawStep === "number" && Number.isFinite(rawStep)
+                ? rawStep
+                : undefined;
+            // R1 Research Finding 2: nodeFirstAttemptTime from executionInfo.
+            const rawFirstAttempt = executionInfo?.nodeFirstAttemptTime;
+            const nodeFirstAttemptTime = typeof rawFirstAttempt === "string" && rawFirstAttempt.length > 0
+                ? rawFirstAttempt
+                : undefined;
+            const threadId = typeof configurable?.thread_id === "string"
+                ? configurable.thread_id
+                : undefined;
+            try {
+                await onAttempt({
+                    nodeAttempt,
+                    ...(langGraphStep !== undefined ? { langGraphStep } : {}),
+                    ...(nodeFirstAttemptTime !== undefined
+                        ? { nodeFirstAttemptTime }
+                        : {}),
+                    ...(threadId !== undefined ? { threadId } : {}),
+                    raw: runtime,
+                });
+            }
+            catch (err) {
+                if (!onAttemptWarned) {
+                    onAttemptWarned = true;
+                    console.warn(`[darwin-langgraph] onAttempt callback for "${agentName}" threw — ` +
+                        `swallowed. Subsequent throws will be silent. Original error: ` +
+                        `${err?.message ?? String(err)}`);
+                }
+            }
+        }
         let result;
         try {
             result = await runAgent(agent, rawTask, runOptions);

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

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

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

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

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

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