nexus-ai-pro 1.11.0 → 1.12.0

package/API_STABILITY.md

@@ -313,6 +313,21 @@ Also since 1.11.0, all additive:
 - `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
 
 Deprecated APIs are marked with `@deprecated` in declarations and described in the changelog. Removals

package/CHANGELOG.md

@@ -4,6 +4,45 @@ 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
@@ -614,7 +653,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.11.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

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
@@ -533,6 +537,98 @@ await graph.history(threadId);      // newest first
 graph.resumeFrom(threadId, 3);      // rewind and run forward
 ```
 
+**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
@@ -1832,13 +1928,13 @@ only, so it never appears in an import graph.
 | `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/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 |
@@ -1874,6 +1970,7 @@ only, so it never appears in an import graph.
 | `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 |

package/dist/graph/graph.d.ts

@@ -1,4 +1,4 @@
-import type { ChannelSchema, CompileOptions, EdgeRouter, GraphCheckpoint, GraphProgress, GraphResult, GraphRunOptions, GraphStatus, GraphStepEvent, NodeFn, NodeOptions, StateUpdate } from '../types/graph.js';
+import type { ChannelSchema, CompileOptions, EdgeRouter, GraphCheckpoint, GraphDescription, GraphProgress, GraphResult, GraphRunOptions, GraphStatus, GraphStepEvent, NodeFn, NodeOptions, StateUpdate } from '../types/graph.js';
 interface GraphNodeDefinition<S extends ChannelSchema> {
     fn: NodeFn<S>;
     options: NodeOptions;
@@ -91,6 +91,36 @@ export declare class CompiledGraph<S extends ChannelSchema> {
      * passes the answer into the subgraph, which continues where it stopped rather than starting over.
      */
     asNode<P extends ChannelSchema>(): NodeFn<P>;
+    /**
+     * The graph's shape as plain data: nodes, edges, and which routes are chosen at run time.
+     *
+     * What `nexus-ai-pro/graph/visualize` draws, and what a UI or a test can inspect without running
+     * anything. Subgraphs added through `asNode()` are described inside the node that runs them.
+     */
+    describe(): GraphDescription;
+    /**
+     * Edits a thread's state.
+     *
+     * Without `asNode`, the update is merged into the latest checkpoint in place, through the channel
+     * reducers, and the run continues exactly where it was — including a thread paused for input.
+     * With `asNode`, the update is applied as if that node had just produced it: a new checkpoint is
+     * written and the next step follows that node's edges. That is how an operator corrects a wrong
+     * intermediate result and lets the rest of the graph run on the fix.
+     */
+    updateState(threadId: string, update: StateUpdate<S>, options?: {
+        asNode?: string;
+    }): Promise<GraphCheckpoint<S>>;
+    /**
+     * Copies a thread's history up to `step` into a new thread, and returns the new thread's id.
+     *
+     * Rewinding with `resumeFrom()` replaces the original timeline. A fork keeps it: both threads stay
+     * readable and runnable, so two answers to the same question can be compared side by side. Every
+     * copied checkpoint records `metadata.forkedFrom`.
+     */
+    fork(threadId: string, options?: {
+        step?: number;
+        threadId?: string;
+    }): Promise<string>;
     private run;
     /** Runs one task to a verdict, applying its retry policy and timeout. */
     private runTask;