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

package/CHANGELOG.md

@@ -3,6 +3,354 @@
 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
+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)

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?)`
 
@@ -202,7 +219,8 @@ The [`examples/`](./examples/) directory ships three runnable scripts:
 
 | `darwin-langgraph` | `darwin-agents` | `@langchain/langgraph` | Status |
 |---|---|---|---|
-| `0.2.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
@@ -210,7 +228,83 @@ 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`.
 
-## V0.2 — new surfaces (LIVE this release)
+## V0.3 — observability + safety (LIVE this release)
+
+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:
@@ -256,6 +350,17 @@ Two lines:
 `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
 the same minor of the underlying Darwin release.

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":"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;AA8J9C;;;;;;;;;;;;;;;;;;;;;;;;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,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;IACjC,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,IAAI,EAAE,CAAC;IAEzC,oEAAoE;IACpE,+DAA+D;IAC/D,IAAI,cAAc,GAAG,KAAK,CAAC;IAC3B,IAAI,eAAe,GAAG,KAAK,CAAC;IAE5B,OAAO,KAAK,UAAU,UAAU,CAAC,KAAK,EAAE,MAAM;QAC5C,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,+DAA+D;QAC/D,qEAAqE;QACrE,kEAAkE;QAClE,EAAE;QACF,mEAAmE;QACnE,kEAAkE;QAClE,mEAAmE;QACnE,6DAA6D;QAC7D,4CAA4C;QAC5C,IAAI,SAAS,IAAI,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;YACtD,MAAM,CAAC,GAAG,MAAiC,CAAC;YAC5C,MAAM,OAAO,GAAG,CAAC,CAAC,OAA8C,CAAC;YACjE,MAAM,aAAa,GAAG,OAAO,EAAE,aAKlB,CAAC;YACd,MAAM,QAAQ,GAAG,CAAC,CAAC,QAA+C,CAAC;YACnE,MAAM,YAAY,GAAG,CAAC,CAAC,YAEV,CAAC;YACd,MAAM,WAAW,GACf,OAAO,aAAa,EAAE,WAAW,KAAK,QAAQ;gBAC9C,MAAM,CAAC,QAAQ,CAAC,aAAa,CAAC,WAAW,CAAC;gBAC1C,aAAa,CAAC,WAAW,IAAI,CAAC;gBAC5B,CAAC,CAAC,aAAa,CAAC,WAAW;gBAC3B,CAAC,CAAC,CAAC,CAAC;YACR,2DAA2D;YAC3D,MAAM,OAAO,GAAG,QAAQ,EAAE,CAAC,gBAAgB,CAAC,CAAC;YAC7C,MAAM,aAAa,GACjB,OAAO,OAAO,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC;gBACrD,CAAC,CAAC,OAAO;gBACT,CAAC,CAAC,SAAS,CAAC;YAChB,kEAAkE;YAClE,MAAM,eAAe,GAAG,aAAa,EAAE,oBAAoB,CAAC;YAC5D,MAAM,oBAAoB,GACxB,OAAO,eAAe,KAAK,QAAQ,IAAI,eAAe,CAAC,MAAM,GAAG,CAAC;gBAC/D,CAAC,CAAC,eAAe;gBACjB,CAAC,CAAC,SAAS,CAAC;YAChB,MAAM,QAAQ,GACZ,OAAO,YAAY,EAAE,SAAS,KAAK,QAAQ;gBACzC,CAAC,CAAC,YAAY,CAAC,SAAS;gBACxB,CAAC,CAAC,SAAS,CAAC;YAChB,IAAI,CAAC;gBACH,MAAM,SAAS,CAAC;oBACd,WAAW;oBACX,GAAG,CAAC,aAAa,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;oBACzD,GAAG,CAAC,oBAAoB,KAAK,SAAS;wBACpC,CAAC,CAAC,EAAE,oBAAoB,EAAE;wBAC1B,CAAC,CAAC,EAAE,CAAC;oBACP,GAAG,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;oBAC/C,GAAG,EAAE,OAAO;iBACb,CAAC,CAAC;YACL,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,CAAC,eAAe,EAAE,CAAC;oBACrB,eAAe,GAAG,IAAI,CAAC;oBACvB,OAAO,CAAC,IAAI,CACV,8CAA8C,SAAS,YAAY;wBACjE,+DAA+D;wBAC/D,GAAI,GAAa,EAAE,OAAO,IAAI,MAAM,CAAC,GAAG,CAAC,EAAE,CAC9C,CAAC;gBACJ,CAAC;YACH,CAAC;QACH,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"}