nexus-ai-pro 1.10.0 → 1.11.0

package/API_STABILITY.md

@@ -106,7 +106,7 @@ exactly-once provider execution. Those capabilities will use additive adapters a
 `MemoryAssetStore` is likewise process-local and does not promise cross-process durability or shared
 tenant state.
 
-### Image portability (Unreleased)
+### Image portability (1.10.0)
 
 The following are public under the same 1.x rules. None is exported from the root or from
 `nexus-ai-pro/images`:
@@ -278,10 +278,10 @@ and threading the schema through it would force an annotation on every construct
 The graph casts at that boundary and hands typed state back through `state()` and `history()`.
 
 `compile()` without a checkpointer uses an in-process `MemoryGraphCheckpointer` capped at 1,000
-threads (Unreleased; earlier releases created none). `checkpointer: false` disables checkpointing. A
+threads (since 1.10.0; earlier releases created none). `checkpointer: false` disables checkpointing. A
 run started without a `threadId` reports its generated id on the result.
 
-Also Unreleased:
+Also since 1.10.0:
 
 - A paused or failed superstep records its already finished nodes in the optional `completed` field.
   Those nodes are not run again, and their edges still count when the step completes.
@@ -290,10 +290,28 @@ Also Unreleased:
 - A subgraph interrupt surfaces as an interrupt of the parent node.
 - `onProgress` receives `context.report()` calls.
 
-Scheduling within a superstep is not a guarantee. Nodes in a fan-out currently run in edge order and
-sequentially; running them concurrently is a valid future change, so a node must not depend on
-observing another node's write within the same superstep — that is what channels are for. The default
-`maxSteps` may change; pass it explicitly when a run depends on the bound.
+Scheduling within a superstep is not a guarantee, and 1.11.0 makes use of that: tasks in a
+superstep now run concurrently, bounded by `maxConcurrency` (default 16, settable per compile and per
+run; `1` is strictly sequential). A node still must not depend on observing another node's write
+within the same superstep — that is what channels are for. What is guaranteed is that writes are
+reduced in task order rather than completion order, so a replay of the same decisions produces the
+same state. The default `maxSteps` and `maxConcurrency` may change; pass them explicitly when a run
+depends on the bound.
+
+Also since 1.11.0, all additive:
+
+- `Send` creates one task per value, with the task's input on `context.input`. Task ids are derived
+  from the step and the order produced, and appear in the checkpoint's optional `tasks` field, which
+  is written only when it says more than `next` does.
+- `NodeOptions` on `addNode` carries `retry`, `timeoutMs`, and `ends`; `compile({ retry })` sets the
+  default policy. Retrying is off unless asked for. A timeout raises `GraphNodeTimeoutError`.
+- `onNodeError` chooses `fail-fast` (default) or `settle` for the siblings of a failed task.
+- A paused checkpoint and result carry `interrupts`, every question the step asked;
+  `interrupt` remains the first of them. `resumeInterrupts()` and `resumeInterruptsWith()` answer any
+  subset by interrupt id. Interrupt ids are keyed by task, so ids written by earlier releases for
+  ordinary nodes still resolve.
+- `context.taskId` and `context.attempt` are new. Step events carry `tasks` and `attempts` when there
+  is something to report.
 
 ## Deprecation process
 

package/CHANGELOG.md

@@ -4,6 +4,55 @@ Notable changes to this project are recorded here. The format follows [Keep a Ch
 
 ## [Unreleased]
 
+## [1.11.0] - 2026-09-18
+
+Parallel graphs. A fan-out that looks parallel now runs in parallel, a graph can fan out over data it
+discovers at run time, and a node can retry or time out on its own.
+
+### Added
+
+- **Concurrent supersteps.** Every task in a superstep starts together: four branches of 300 ms
+  finish in about 310 ms, where they used to take 1,253 ms. `npm run bench:graph` measures it and
+  fails if the gain disappears.
+  - `maxConcurrency` bounds how many run at once. It defaults to 16, is settable per compile and per
+    run, and `1` restores strictly sequential execution.
+  - Writes are reduced in task order, never completion order, so timing cannot change the state a
+    replay produces.
+  - A superstep with a single task skips the scheduler, so a linear graph pays nothing for this.
+- **`Send`, for fan-out over run-time data.** A router can return `new Send(node, input)` values,
+  creating one task per value, each reading its own `context.input`. Fifty-seven URLs become
+  fifty-seven tasks of one node in one superstep.
+  - Each copy is checkpointed separately, so a resume re-runs only the copies that did not finish.
+  - Task ids come from the step and the order produced, so a replay rebuilds the same tasks.
+  - `addNode(name, fn, { ends })` declares `Send` targets, keeping reachability checks exact.
+- **Per-node retries and timeouts.** `addNode(name, fn, { retry, timeoutMs })`, with
+  `compile({ retry })` as the default for every node.
+  - Retrying is off unless asked for, because only the application knows whether a node is
+    idempotent. Interrupts, aborts, and validation errors are never retried.
+  - `context.attempt` tells a node which try it is on, and step events report the attempts a task
+    needed.
+  - A timeout aborts the node's signal and fails that attempt with `GraphNodeTimeoutError`, even if
+    the node ignores its signal.
+- **`onNodeError`.** When a task fails, its siblings are aborted (`fail-fast`, the default) or left to
+  finish (`settle`). Either way, what they already wrote is kept.
+- **Several questions at once.** Parallel tasks can each interrupt. Paused checkpoints and results
+  carry `interrupts`, and `resumeInterrupts()` answers any subset by id. A single question still works
+  exactly as before through `resume()`.
+- **Install weight is now measured honestly.** The size table only ever counted this package's own
+  files, so a small entry point could quietly force a large dependency on the consumer.
+  - `npm run size:check` follows bare imports too, and the README table gains a column for what each
+    entry point makes you install. Most entry points force nothing: `/graph`, `/operations`,
+    `/batch`, `/embeddings`, and every image subpath import no third-party package at all. The root
+    import, `/core`, `/config`, and `/security` pull in 3.4 to 4.7 MB, because JSON-schema and Zod
+    validation live there.
+  - The clean-install test now measures and bounds the whole production install: 10.0 MB of
+    `node_modules`, of which 3.0 MB is this package.
+
+### Fixed
+
+- **A retry no longer lets the process exit while it waits.** The backoff timer was unref'd, so a run
+  waiting to retry could be abandoned by an otherwise idle process.
+
 ## [1.10.0] - 2026-09-16
 
 Image portability. Three image backends now sit behind one contract: OpenAI, Google Imagen, and a
@@ -565,7 +614,8 @@ shared policy vocabulary is in place for a future release that revisits this.
 - URL fetching rejects unsafe private-network targets and limits response reads.
 - CLI and audit findings no longer disclose detected secret values.
 
-[Unreleased]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.10.0...HEAD
+[Unreleased]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.11.0...HEAD
+[1.11.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.10.0...v1.11.0
 [1.10.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.9.0...v1.10.0
 [1.9.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.8.0...v1.9.0
 [1.8.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.7.0...v1.8.0

package/README.md

@@ -452,6 +452,58 @@ whether that means overwrite, append, or sum. Assignment would silently drop one
 **Cycles are first-class**, so `maxSteps` is what stands between a mistaken router and an infinite
 loop. Exceeding it names the nodes still pending rather than hanging.
 
+**Branches run in parallel.** Every task in a superstep starts together, so four branches of three
+seconds each finish in about three seconds rather than twelve:
+
+```ts
+.addConditionalEdges('plan', () => ['research-a', 'research-b', 'research-c', 'research-d'])
+```
+
+`maxConcurrency` caps how many run at once — 16 by default, settable per compile and per run, and
+`1` restores strictly sequential execution. Whatever the timing, writes are reduced in task order, so
+a replay produces the same state. A superstep with one task skips the scheduler entirely.
+
+**Fan out over data decided at run time.** Edges can only name nodes that already exist. `Send`
+creates one task per value instead, each reading its own `context.input`:
+
+```ts
+import { Send } from 'nexus-ai-pro/graph';
+
+.addNode('research', async (ctx) => ({ findings: [await fetch(ctx.input as string)] }), { ends: [END] })
+.addConditionalEdges('plan', (state) => state.urls.map((url) => new Send('research', url)))
+```
+
+Fifty-seven URLs become fifty-seven tasks of one node in a single superstep, bounded by
+`maxConcurrency` and checkpointed individually, so a resume re-runs only the copies that did not
+finish. Declaring `ends` keeps compile-time reachability checks exact.
+
+**Retries and timeouts per node.** A node that calls a flaky service can retry on its own, without
+wrapping every node body in the same try/catch:
+
+```ts
+.addNode('fetch', fetchNode, {
+  retry: { maxAttempts: 3, initialIntervalMs: 500, backoffFactor: 2, jitter: true },
+  timeoutMs: 10_000,
+})
+```
+
+Retrying defaults to off, because only you know whether a node is idempotent; `compile({ retry })`
+sets a default for every node. Interrupts, aborts, and validation errors are never retried.
+`context.attempt` tells a node which try it is on, and a timeout aborts the node's signal and fails
+that attempt. When one task fails, its siblings are aborted by default; `onNodeError: 'settle'` lets
+them finish first, and either way what they already wrote is kept.
+
+**Several questions at once.** Parallel tasks can each interrupt. The paused result carries every
+pending question, and they can be answered together or a few at a time:
+
+```ts
+const run = await graph.invoke(input, { threadId });
+await graph.resumeInterruptsWith(threadId, {
+  [run.interrupts[0].id]: true,
+  [run.interrupts[1].id]: 'use the second draft',
+});
+```
+
 **Human in the loop.** A node calls `interrupt()`; the graph checkpoints and stops:
 
 ```ts
@@ -481,7 +533,8 @@ await graph.history(threadId);      // newest first
 graph.resumeFrom(threadId, 3);      // rewind and run forward
 ```
 
-**Durable by construction.** The default checkpointer is in-process. Point it at the operation store
+**Durable by construction.** The default checkpointer is in-process, holding up to 1,000 threads;
+pass `checkpointer: false` to turn checkpointing off. Point it at the operation store
 that already backs durable operations and a thread survives a restart — a different worker resumes
 what another suspended:
 
@@ -1750,85 +1803,93 @@ Importing one piece loads one piece. The figures below are the transitive import
 point, generated from the build by `npm run size:check`, which fails CI when an entry point grows
 past its budget — so the numbers stay true rather than aspirational.
 
+The last column is the part a file-size table usually hides: what an entry point forces you to
+install. Most of them force nothing at all — `/graph`, `/operations`, `/images/*`, `/batch`,
+`/embeddings` and the rest import no third-party package. The root import, `/core`, `/config`, and
+`/security` do, because JSON-schema and Zod validation live there. A production install of this
+package is about 10 MB of `node_modules`, of which 3 MB is this package; the clean-install test holds
+that total to a ceiling too. `@types/node` accounts for a further 2.4 MB at install time but is types
+only, so it never appears in an import graph.
+
 <!-- size-table:start -->
-| Import | Size | Share of root |
-| --- | --- | --- |
-| `nexus-ai-pro` | 612 KB | 100% |
-| `nexus-ai-pro/config` | 468 KB | 76% |
-| `nexus-ai-pro/core` | 462 KB | 75% |
-| `nexus-ai-pro/realtime` | 157 KB | 26% |
-| `nexus-ai-pro/batch` | 118 KB | 19% |
-| `nexus-ai-pro/realtime/session` | 94 KB | 15% |
-| `nexus-ai-pro/embeddings` | 91 KB | 15% |
-| `nexus-ai-pro/providers/groq` | 79 KB | 13% |
-| `nexus-ai-pro/providers/mistral` | 79 KB | 13% |
-| `nexus-ai-pro/providers/azure-openai` | 78 KB | 13% |
-| `nexus-ai-pro/providers/openrouter` | 78 KB | 13% |
-| `nexus-ai-pro/providers/deepseek` | 77 KB | 13% |
-| `nexus-ai-pro/providers/llamacpp` | 77 KB | 13% |
-| `nexus-ai-pro/providers/lmstudio` | 77 KB | 13% |
-| `nexus-ai-pro/providers/openai` | 77 KB | 13% |
-| `nexus-ai-pro/providers/anthropic` | 70 KB | 11% |
-| `nexus-ai-pro/providers/google` | 66 KB | 11% |
-| `nexus-ai-pro/images` | 65 KB | 11% |
-| `nexus-ai-pro/providers/ollama` | 58 KB | 9% |
-| `nexus-ai-pro/batch/openai` | 52 KB | 8% |
-| `nexus-ai-pro/batch/anthropic` | 52 KB | 8% |
-| `nexus-ai-pro/operations` | 49 KB | 8% |
-| `nexus-ai-pro/batch/mock` | 47 KB | 8% |
-| `nexus-ai-pro/providers/cohere` | 46 KB | 8% |
-| `nexus-ai-pro/realtime/openai-webrtc` | 46 KB | 8% |
-| `nexus-ai-pro/security` | 40 KB | 7% |
-| `nexus-ai-pro/models` | 35 KB | 6% |
-| `nexus-ai-pro/graph` | 33 KB | 5% |
-| `nexus-ai-pro/images/inputs` | 31 KB | 5% |
-| `nexus-ai-pro/realtime/openai-websocket` | 29 KB | 5% |
-| `nexus-ai-pro/evals` | 23 KB | 4% |
-| `nexus-ai-pro/images/transform` | 22 KB | 4% |
-| `nexus-ai-pro/images/stores` | 22 KB | 4% |
-| `nexus-ai-pro/telephony/twilio` | 21 KB | 3% |
-| `nexus-ai-pro/telephony` | 20 KB | 3% |
-| `nexus-ai-pro/images/openai` | 19 KB | 3% |
-| `nexus-ai-pro/realtime/mock` | 19 KB | 3% |
-| `nexus-ai-pro/voice` | 18 KB | 3% |
-| `nexus-ai-pro/images/comfyui` | 17 KB | 3% |
-| `nexus-ai-pro/embeddings/adapters` | 17 KB | 3% |
-| `nexus-ai-pro/realtime/conversation` | 16 KB | 3% |
-| `nexus-ai-pro/images/google` | 15 KB | 2% |
-| `nexus-ai-pro/images/evals` | 15 KB | 2% |
-| `nexus-ai-pro/images/assets` | 14 KB | 2% |
-| `nexus-ai-pro/context` | 13 KB | 2% |
-| `nexus-ai-pro/operations/adapters` | 13 KB | 2% |
-| `nexus-ai-pro/realtime/tools` | 13 KB | 2% |
-| `nexus-ai-pro/workflows` | 13 KB | 2% |
-| `nexus-ai-pro/images/mock` | 12 KB | 2% |
-| `nexus-ai-pro/optimizer` | 11 KB | 2% |
-| `nexus-ai-pro/voice/session` | 11 KB | 2% |
-| `nexus-ai-pro/providers` | 10 KB | 2% |
-| `nexus-ai-pro/providers/base` | 10 KB | 2% |
-| `nexus-ai-pro/embeddings/models` | 10 KB | 2% |
-| `nexus-ai-pro/voice/openai` | 9 KB | 1% |
-| `nexus-ai-pro/images/moderation` | 9 KB | 1% |
-| `nexus-ai-pro/ops/circuit-breaker` | 8 KB | 1% |
-| `nexus-ai-pro/realtime/openai-server` | 8 KB | 1% |
-| `nexus-ai-pro/capabilities` | 8 KB | 1% |
-| `nexus-ai-pro/telephony/realtime-bridge` | 7 KB | 1% |
-| `nexus-ai-pro/providers/errors` | 5 KB | 0.8% |
-| `nexus-ai-pro/embeddings/mock` | 5 KB | 0.8% |
-| `nexus-ai-pro/cache/semantic-cache` | 5 KB | 0.8% |
-| `nexus-ai-pro/evals/judge` | 5 KB | 0.8% |
-| `nexus-ai-pro/operations/webhooks` | 4 KB | 0.7% |
-| `nexus-ai-pro/ops/rate-limit-adapters` | 3 KB | 0.5% |
-| `nexus-ai-pro/cache/memory-cache` | 3 KB | 0.5% |
-| `nexus-ai-pro/cache` | 2 KB | 0.3% |
-| `nexus-ai-pro/cache/adapters` | 2 KB | 0.3% |
-| `nexus-ai-pro/rag` | 2 KB | 0.3% |
-| `nexus-ai-pro/jobs` | 2 KB | 0.3% |
-| `nexus-ai-pro/jobs/durable-adapters` | 2 KB | 0.3% |
-| `nexus-ai-pro/jobs/queue` | 2 KB | 0.3% |
-| `nexus-ai-pro/streaming` | 1 KB | 0.2% |
-| `nexus-ai-pro/providers/type-guards` | 1 KB | 0.2% |
-| `nexus-ai-pro/jobs/batch` | 1 KB | 0.2% |
+| Import | Size | Share of root | Third-party install |
+| --- | --- | --- | --- |
+| `nexus-ai-pro` | 612 KB | 100% | +4.7 MB |
+| `nexus-ai-pro/config` | 468 KB | 76% | +4.7 MB |
+| `nexus-ai-pro/core` | 462 KB | 75% | +4.7 MB |
+| `nexus-ai-pro/realtime` | 157 KB | 26% | none |
+| `nexus-ai-pro/batch` | 118 KB | 19% | none |
+| `nexus-ai-pro/realtime/session` | 94 KB | 15% | none |
+| `nexus-ai-pro/embeddings` | 91 KB | 15% | none |
+| `nexus-ai-pro/providers/groq` | 79 KB | 13% | none |
+| `nexus-ai-pro/providers/mistral` | 79 KB | 13% | none |
+| `nexus-ai-pro/providers/azure-openai` | 78 KB | 13% | none |
+| `nexus-ai-pro/providers/openrouter` | 78 KB | 13% | none |
+| `nexus-ai-pro/providers/deepseek` | 77 KB | 13% | none |
+| `nexus-ai-pro/providers/llamacpp` | 77 KB | 13% | none |
+| `nexus-ai-pro/providers/lmstudio` | 77 KB | 13% | none |
+| `nexus-ai-pro/providers/openai` | 77 KB | 13% | none |
+| `nexus-ai-pro/providers/anthropic` | 70 KB | 11% | none |
+| `nexus-ai-pro/providers/google` | 66 KB | 11% | none |
+| `nexus-ai-pro/images` | 65 KB | 11% | none |
+| `nexus-ai-pro/providers/ollama` | 58 KB | 9% | none |
+| `nexus-ai-pro/batch/openai` | 52 KB | 8% | none |
+| `nexus-ai-pro/batch/anthropic` | 52 KB | 8% | none |
+| `nexus-ai-pro/operations` | 49 KB | 8% | none |
+| `nexus-ai-pro/batch/mock` | 47 KB | 8% | none |
+| `nexus-ai-pro/providers/cohere` | 46 KB | 8% | none |
+| `nexus-ai-pro/graph` | 46 KB | 8% | none |
+| `nexus-ai-pro/realtime/openai-webrtc` | 46 KB | 8% | none |
+| `nexus-ai-pro/security` | 40 KB | 7% | +3.4 MB |
+| `nexus-ai-pro/models` | 35 KB | 6% | none |
+| `nexus-ai-pro/images/inputs` | 31 KB | 5% | none |
+| `nexus-ai-pro/realtime/openai-websocket` | 29 KB | 5% | none |
+| `nexus-ai-pro/evals` | 23 KB | 4% | none |
+| `nexus-ai-pro/images/transform` | 22 KB | 4% | none |
+| `nexus-ai-pro/images/stores` | 22 KB | 4% | none |
+| `nexus-ai-pro/telephony/twilio` | 21 KB | 3% | none |
+| `nexus-ai-pro/telephony` | 20 KB | 3% | none |
+| `nexus-ai-pro/images/openai` | 19 KB | 3% | none |
+| `nexus-ai-pro/realtime/mock` | 19 KB | 3% | none |
+| `nexus-ai-pro/voice` | 18 KB | 3% | none |
+| `nexus-ai-pro/images/comfyui` | 17 KB | 3% | none |
+| `nexus-ai-pro/embeddings/adapters` | 17 KB | 3% | none |
+| `nexus-ai-pro/realtime/conversation` | 16 KB | 3% | none |
+| `nexus-ai-pro/images/google` | 15 KB | 2% | none |
+| `nexus-ai-pro/images/evals` | 15 KB | 2% | none |
+| `nexus-ai-pro/images/assets` | 14 KB | 2% | none |
+| `nexus-ai-pro/context` | 13 KB | 2% | none |
+| `nexus-ai-pro/operations/adapters` | 13 KB | 2% | none |
+| `nexus-ai-pro/realtime/tools` | 13 KB | 2% | none |
+| `nexus-ai-pro/workflows` | 13 KB | 2% | none |
+| `nexus-ai-pro/images/mock` | 12 KB | 2% | none |
+| `nexus-ai-pro/optimizer` | 11 KB | 2% | none |
+| `nexus-ai-pro/voice/session` | 11 KB | 2% | none |
+| `nexus-ai-pro/providers` | 10 KB | 2% | none |
+| `nexus-ai-pro/providers/base` | 10 KB | 2% | none |
+| `nexus-ai-pro/embeddings/models` | 10 KB | 2% | none |
+| `nexus-ai-pro/voice/openai` | 9 KB | 1% | none |
+| `nexus-ai-pro/images/moderation` | 9 KB | 1% | none |
+| `nexus-ai-pro/ops/circuit-breaker` | 8 KB | 1% | none |
+| `nexus-ai-pro/realtime/openai-server` | 8 KB | 1% | none |
+| `nexus-ai-pro/capabilities` | 8 KB | 1% | none |
+| `nexus-ai-pro/telephony/realtime-bridge` | 7 KB | 1% | none |
+| `nexus-ai-pro/providers/errors` | 5 KB | 0.8% | none |
+| `nexus-ai-pro/embeddings/mock` | 5 KB | 0.8% | none |
+| `nexus-ai-pro/cache/semantic-cache` | 5 KB | 0.8% | none |
+| `nexus-ai-pro/evals/judge` | 5 KB | 0.8% | none |
+| `nexus-ai-pro/operations/webhooks` | 4 KB | 0.7% | none |
+| `nexus-ai-pro/ops/rate-limit-adapters` | 3 KB | 0.5% | none |
+| `nexus-ai-pro/cache/memory-cache` | 3 KB | 0.5% | none |
+| `nexus-ai-pro/cache` | 2 KB | 0.3% | none |
+| `nexus-ai-pro/cache/adapters` | 2 KB | 0.3% | none |
+| `nexus-ai-pro/rag` | 2 KB | 0.3% | none |
+| `nexus-ai-pro/jobs` | 2 KB | 0.3% | none |
+| `nexus-ai-pro/jobs/durable-adapters` | 2 KB | 0.3% | none |
+| `nexus-ai-pro/jobs/queue` | 2 KB | 0.3% | none |
+| `nexus-ai-pro/streaming` | 1 KB | 0.2% | none |
+| `nexus-ai-pro/providers/type-guards` | 1 KB | 0.2% | none |
+| `nexus-ai-pro/jobs/batch` | 1 KB | 0.2% | none |
 <!-- size-table:end -->
 
 A capability that only works by importing the whole runtime is treated as a design problem, not an

package/dist/graph/errors.d.ts

@@ -19,7 +19,11 @@ export declare class GraphInterrupt extends GraphError {
     readonly node: string;
     readonly step: number;
     readonly index: number;
-    constructor(request: InterruptRequest, node: string, step: number, index: number);
+    /** Task that asked. Equal to `node` unless the task came from a `Send`. */
+    readonly taskId: string;
+    constructor(request: InterruptRequest, node: string, step: number, index: number, 
+    /** Task that asked. Equal to `node` unless the task came from a `Send`. */
+    taskId?: string);
 }
 /**
  * Raised when a run exceeds its superstep budget.
@@ -46,5 +50,24 @@ export declare class GraphNotInterruptedError extends GraphError {
     readonly status: string;
     constructor(threadId: string, status: string);
 }
-/** Stable key for one interrupt, so a replayed node picks up the answer it was given. */
-export declare function interruptKey(pending: Pick<PendingInterrupt, 'node' | 'step' | 'index'>): string;
+/**
+ * Raised when a node outlives its `timeoutMs`.
+ *
+ * Separate from an ordinary failure because it is usually worth retrying, and because the node's
+ * signal was aborted underneath it rather than the node choosing to stop.
+ */
+export declare class GraphNodeTimeoutError extends GraphError {
+    readonly node: string;
+    readonly timeoutMs: number;
+    constructor(node: string, timeoutMs: number);
+}
+/**
+ * Stable key for one interrupt, so a replayed node picks up the answer it was given.
+ *
+ * Keyed by task rather than node, so several `Send` tasks of one node each keep their own answer.
+ * For a node reached through an ordinary edge the task id is the node name, so keys written by
+ * earlier releases still resolve.
+ */
+export declare function interruptKey(pending: Pick<PendingInterrupt, 'node' | 'step' | 'index'> & {
+    taskId?: string;
+}): string;

package/dist/graph/errors.js

@@ -26,12 +26,16 @@ export class GraphInterrupt extends GraphError {
     node;
     step;
     index;
-    constructor(request, node, step, index) {
+    taskId;
+    constructor(request, node, step, index, 
+    /** Task that asked. Equal to `node` unless the task came from a `Send`. */
+    taskId = node) {
         super(`Graph interrupted at "${node}": ${request.reason}`, 'GRAPH_INTERRUPT');
         this.request = request;
         this.node = node;
         this.step = step;
         this.index = index;
+        this.taskId = taskId;
         this.name = 'GraphInterrupt';
     }
 }
@@ -79,7 +83,29 @@ export class GraphNotInterruptedError extends GraphError {
         this.name = 'GraphNotInterruptedError';
     }
 }
-/** Stable key for one interrupt, so a replayed node picks up the answer it was given. */
+/**
+ * Raised when a node outlives its `timeoutMs`.
+ *
+ * Separate from an ordinary failure because it is usually worth retrying, and because the node's
+ * signal was aborted underneath it rather than the node choosing to stop.
+ */
+export class GraphNodeTimeoutError extends GraphError {
+    node;
+    timeoutMs;
+    constructor(node, timeoutMs) {
+        super(`Graph node "${node}" exceeded its ${timeoutMs}ms timeout`, 'GRAPH_NODE_TIMEOUT');
+        this.node = node;
+        this.timeoutMs = timeoutMs;
+        this.name = 'GraphNodeTimeoutError';
+    }
+}
+/**
+ * Stable key for one interrupt, so a replayed node picks up the answer it was given.
+ *
+ * Keyed by task rather than node, so several `Send` tasks of one node each keep their own answer.
+ * For a node reached through an ordinary edge the task id is the node name, so keys written by
+ * earlier releases still resolve.
+ */
 export function interruptKey(pending) {
-    return `${pending.node}:${pending.step}:${pending.index}`;
+    return `${pending.taskId ?? pending.node}:${pending.step}:${pending.index}`;
 }

package/dist/graph/graph.d.ts

@@ -1,4 +1,8 @@
-import type { ChannelSchema, CompileOptions, EdgeRouter, GraphCheckpoint, GraphProgress, GraphResult, GraphRunOptions, GraphStatus, GraphStepEvent, NodeFn, StateUpdate } from '../types/graph.js';
+import type { ChannelSchema, CompileOptions, EdgeRouter, GraphCheckpoint, GraphProgress, GraphResult, GraphRunOptions, GraphStatus, GraphStepEvent, NodeFn, NodeOptions, StateUpdate } from '../types/graph.js';
+interface GraphNodeDefinition<S extends ChannelSchema> {
+    fn: NodeFn<S>;
+    options: NodeOptions;
+}
 interface Edge<S extends ChannelSchema> {
     from: string;
     to?: string;
@@ -18,7 +22,7 @@ export declare class StateGraph<S extends ChannelSchema> {
     private readonly nodes;
     private readonly edges;
     constructor(channels: S);
-    addNode(name: string, fn: NodeFn<S>): this;
+    addNode(name: string, fn: NodeFn<S>, options?: NodeOptions): this;
     addEdge(from: string, to: string): this;
     /**
      * Routes on state after `from` runs.
@@ -40,7 +44,7 @@ export declare class CompiledGraph<S extends ChannelSchema> {
     private readonly options;
     private readonly now;
     private readonly store;
-    constructor(channels: S, nodes: Map<string, NodeFn<S>>, edges: Array<Edge<S>>, options: CompileOptions);
+    constructor(channels: S, nodes: Map<string, GraphNodeDefinition<S>>, edges: Array<Edge<S>>, options: CompileOptions);
     /** Runs to completion, to an interrupt, or to the step limit. */
     invoke(input?: StateUpdate<S>, runOptions?: GraphRunOptions): Promise<GraphResult<S>>;
     /** Yields one event per superstep, so a caller can render progress as it happens. */
@@ -55,6 +59,15 @@ export declare class CompiledGraph<S extends ChannelSchema> {
     resume(threadId: string, value: unknown, runOptions?: GraphRunOptions): AsyncIterable<GraphStepEvent<S>>;
     /** Like `resume`, but returns the final result rather than the stream. */
     resumeWith(threadId: string, value: unknown, runOptions?: GraphRunOptions): Promise<GraphResult<S>>;
+    /**
+     * Answers several of a paused step's questions at once, keyed by interrupt id.
+     *
+     * Parallel tasks can each ask something, so one answer is not always enough. Questions left
+     * unanswered are asked again when the step runs.
+     */
+    resumeInterrupts(threadId: string, answers: Record<string, unknown>, runOptions?: GraphRunOptions): AsyncIterable<GraphStepEvent<S>>;
+    /** Like `resumeInterrupts`, but returns the final result rather than the stream. */
+    resumeInterruptsWith(threadId: string, answers: Record<string, unknown>, runOptions?: GraphRunOptions): Promise<GraphResult<S>>;
     /** Continues a thread that stopped for any other reason, such as the step limit. */
     continue(threadId: string, runOptions?: GraphRunOptions): AsyncIterable<GraphStepEvent<S>>;
     /**
@@ -79,10 +92,13 @@ export declare class CompiledGraph<S extends ChannelSchema> {
      */
     asNode<P extends ChannelSchema>(): NodeFn<P>;
     private run;
+    /** Runs one task to a verdict, applying its retry policy and timeout. */
+    private runTask;
     private runNode;
     /** Combines this superstep's writes into state through each channel's reducer. */
     private reduce;
-    private nextNodes;
+    /** Follows every edge out of the nodes that ran, producing the next step's tasks. */
+    private nextTasks;
     private entryNodes;
     private seedState;
     private requireCheckpoint;