nexus-ai-pro 1.10.0 → 1.12.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,43 @@ 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.
+
+Also since 1.12.0, all additive:
+
+- `Command` (with `Command.PARENT`) may be returned from a node; `NodeResult` names what a node may
+  return. `goto` routes are added to the node's outgoing edges, and a paused checkpoint records them in
+  the optional `gotos` field.
+- `interruptBefore` and `interruptAfter` on compile and run options; a paused checkpoint and result
+  carry `breakpoint`, and step events may have type `breakpoint`.
+- `NodeOptions.defer`, `GraphRunOptions.onEvent` with the `GraphEvent` union, and `context.emit()`.
+  New `GraphEvent` variants may be added in a minor release.
+- `updateState()`, `fork()`, and `describe()` on a compiled graph, and the `nexus-ai-pro/graph/visualize`
+  subpath. The exact Mermaid text `toMermaid()` produces is not a guarantee — diagram layout may
+  improve in a minor release — but `GraphDescription` is a normalized shape.
+- A subgraph node's thread id is `<parent thread>:<task id>`, which equals the previous
+  `<parent thread>:<node>` for any node not reached through `Send`.
 
 ## Deprecation process
 

package/CHANGELOG.md

@@ -4,6 +4,94 @@ Notable changes to this project are recorded here. The format follows [Keep a Ch
 
 ## [Unreleased]
 
+## [1.12.0] - 2026-09-20
+
+Graph control and introspection. A node can route itself, a run can pause at breakpoints and be
+edited or forked, every task and custom event can be watched as it happens, and a graph can draw
+itself.
+
+### Added
+
+- **`Command`.** A node returns `new Command({ update, goto })` to write state and choose its
+  successors in one step, instead of splitting the decision into a separate router. `goto` takes node
+  names or `Send`s. A route chosen by a task that finished before its step paused is kept on the
+  checkpoint, so it is still followed when the step resumes.
+- **`Command.PARENT`.** A node inside a subgraph hands control back to the graph that contains it. The
+  subgraph's own writes and the update it addressed to the parent are reduced separately, in order,
+  so neither overwrites the other.
+- **Breakpoints.** `interruptBefore` and `interruptAfter`, per compile or per run, pause a run at
+  chosen nodes with status `interrupted` and a `breakpoint` describing where. `continue()` carries on,
+  and does not pause again at the breakpoint it resumes from.
+- **Deferred nodes.** `addNode(name, fn, { defer: true })` holds a node until every other pending task
+  has finished, so an aggregator after branches of different lengths runs once.
+- **`updateState()`.** Merges a correction into a thread's latest checkpoint in place, keeping any
+  pending question; with `asNode`, applies it as that node's output and continues along its edges.
+- **`fork()`.** Copies a thread's history up to a step into a new thread, leaving the original
+  untouched and runnable, and records `metadata.forkedFrom`.
+- **`onEvent` and `context.emit()`.** A run can observe each task starting, retrying, and finishing
+  with its update, every checkpoint written, and custom events a node emits, such as model tokens. A
+  listener that throws never fails the run.
+- **`describe()` and `nexus-ai-pro/graph/visualize`.** `describe()` returns a graph's nodes, edges, and
+  run-time routes as plain JSON, including subgraphs. `toMermaid()` draws it, with optional
+  highlighting of where a thread is; `toGraphJSON()` returns the data. The visualizer imports no
+  runtime code.
+
+### Fixed
+
+- **Parallel copies of a subgraph node no longer share a thread.** `asNode()` keyed the subgraph's
+  thread by node name, so two `Send` copies of one subgraph node in the same step wrote to the same
+  thread. It is now keyed by task; a plain node's task id is its name, so existing threads are
+  unaffected.
+
+## [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 +653,9 @@ 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.12.0...HEAD
+[1.12.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.11.0...v1.12.0
+[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

@@ -1,8 +1,12 @@
 # nexus-ai-pro
 
-The Universal AI Pipeline for Node.js: one typed API for routing, guardrails, caching, context-window management, tools, RAG, evals, jobs, and provider failover.
+The typed AI framework for TypeScript. One API for provider routing and failover, agent graphs that
+run branches in parallel and survive a restart, durable background operations, guardrails, cost
+control, images, voice, and evals.
 
-Use the whole pipeline for production AI features, or turn pieces off when you only need a thin provider wrapper.
+Import the whole runtime, or one piece: every capability has its own entry point with a size budget
+CI enforces, and the table below publishes what each one costs. A graph-only application loads 60 KB
+and installs no third-party package at all.
 
 - NPM: https://www.npmjs.com/package/nexus-ai-pro
 - GitHub: https://github.com/mkhitar-abrahamyan/nexus-ai
@@ -452,6 +456,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 +537,100 @@ 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
+**Route from inside a node.** When a node already knows where to go — an agent that just picked a
+tool, a triage step that classified a ticket — return a `Command` instead of splitting the decision
+into a separate router:
+
+```ts
+import { Command } from 'nexus-ai-pro/graph';
+
+.addNode('triage', (ctx) =>
+  new Command({ update: { label: classify(ctx.state) }, goto: isUrgent(ctx.state) ? 'page-oncall' : 'queue' }),
+  { ends: ['page-oncall', 'queue'] },
+)
+```
+
+`goto` takes node names or `Send`s, and `ends` keeps compile-time checks and diagrams exact. A node
+inside a subgraph can return `new Command({ graph: Command.PARENT, goto: 'human' })` to hand control
+back to the graph that contains it — how a nested agent escalates.
+
+**Aggregate after branches of different lengths.** `{ defer: true }` holds a node until every other
+pending task has finished, so an aggregator after a two-step branch and a one-step branch runs once,
+after both, rather than once per arrival.
+
+**Pause for inspection.** Breakpoints stop a run before or after chosen nodes, checkpointed, without
+changing the nodes themselves:
+
+```ts
+const graph = builder.compile({ interruptBefore: ['publish'] });
+const paused = await graph.invoke(input, { threadId });   // status: 'interrupted', breakpoint: { when: 'before', ... }
+await graph.updateState(threadId, { draft: fixedDraft }); // correct something first, if needed
+for await (const _ of graph.continue(threadId)) {}         // then carry on
+```
+
+Set them per compile or per run; a run's list replaces the compiled one.
+
+**Edit state, or fork a thread.** `updateState(threadId, update)` merges a correction into the latest
+checkpoint through the channel reducers, leaving any pending question in place.
+`updateState(threadId, update, { asNode: 'research' })` applies it as if that node had produced it,
+so the next step follows that node's edges. `fork(threadId, { step })` copies the history up to a step
+into a new thread and leaves the original untouched, so two answers to the same question can be run
+side by side.
+
+**Watch it run.** `onEvent` receives every task starting, retrying, and finishing with its update,
+every checkpoint written, and whatever a node passes to `context.emit()` — model tokens as they
+stream, a status line, an intermediate result:
+
+```ts
+.addNode('write', async (ctx) => {
+  for await (const token of streamAnswer(ctx.state)) ctx.emit({ token });
+  return { answer };
+})
+
+await graph.invoke(input, {
+  onEvent: (event) => event.type === 'custom' && process.stdout.write((event.data as { token: string }).token),
+});
+```
+
+A listener that throws never fails the run it is watching.
+
+**See the shape.** `graph.describe()` returns nodes, edges, and which routes are decided at run
+time, as plain JSON. `toMermaid()` from `nexus-ai-pro/graph/visualize` draws it — solid arrows are
+always taken, dotted ones are chosen at run time, and subgraphs are drawn inside the node that runs
+them:
+
+```ts
+import { toMermaid } from 'nexus-ai-pro/graph/visualize';
+
+console.log(toMermaid(graph, { highlight: checkpoint.next }));
+```
+
+This diagram is that function's actual output for a research-and-review graph:
+
+```mermaid
+flowchart TD
+  __start__([start])
+  __end__([end])
+  n_plan["plan"]
+  n_research["research<br/><small>retries</small>"]
+  n_summarize["summarize<br/><small>deferred</small>"]
+  n_review["review"]
+  n_publish["publish"]
+  __start__ --> n_plan
+  n_summarize --> n_review
+  n_publish --> __end__
+  n_plan -.-> n_research
+  n_research -.-> n_summarize
+  n_review -.-> n_publish
+  n_review -.-> n_plan
+```
+
+The visualizer is its own subpath and imports no runtime code, so drawing a graph costs nothing to an
+application that only runs one. No image renderer is bundled; any Mermaid renderer turns the output
+into PNG or SVG.
+
+**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 +1899,94 @@ 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/graph` | 60 KB | 10% | 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/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/graph/visualize` | 6 KB | 1.0% | 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}`;
 }