nexus-ai-pro 1.20.0 → 1.21.0

package/API_STABILITY.md

@@ -439,8 +439,9 @@ from the root.
   that reconnects with an id never receives it again.
 - The server is not a security boundary on its own: authentication, authorization beyond tenancy and
   scopes, and rate limiting are the application's, through the hooks.
-- Recovery re-runs a whole run rather than the step it died on, so an assistant with side effects
-  should be idempotent or be left at a single attempt.
+- Recovery repeats the step a run died in for graphs and workflows served by `graphAssistant()`, and
+  the whole run for any other assistant, so the repeated part should be idempotent or the run left at a
+  single attempt.
 
 ## Studio stage (1.19.0)
 
@@ -455,6 +456,18 @@ with nexus-ai-pro and declares the core versions it works with as a peer depende
 - The access rules are a guarantee: loopback binding by default, a token on every request, the token
   in a header for every change, and loopback hosts only unless others are allowed.
 
+## Durable execution stage (1.21.0)
+
+Functional workflows (`nexus-ai-pro/graph/functional`) and the SQLite adapters (`nexus-ai-pro/sqlite`)
+are experimental in production readiness. Their contracts follow the 1.x rules.
+
+- A workflow checkpoint is a graph checkpoint whose state holds the input, the recorded step results
+  keyed by step name and call order, and the output. That layout is stable across 1.x, so a thread
+  started by one release resumes on the next.
+- The SQLite table layouts may gain columns in a minor release; `migrate()` adds what is missing.
+- `ServerAssistant.recover()` and `AssistantRunContext.attempt` are optional additions: an assistant
+  without `recover()` behaves as before.
+
 ## Retrieval stores stage (1.20.0)
 
 `PostgresVectorStore` (`nexus-ai-pro/postgres/vectors`) and `QdrantVectorStore` (`nexus-ai-pro/rag/qdrant`)

package/CHANGELOG.md

@@ -4,6 +4,48 @@ Notable changes to this project are recorded here. The format follows [Keep a Ch
 
 ## [Unreleased]
 
+## [1.21.0] - 2026-09-29
+
+Durable execution everywhere. Durability no longer requires drawing a graph, and a crash costs a
+step rather than a run.
+
+### Added
+
+- **Functional workflows**, experimental, on `nexus-ai-pro/graph/functional`. `workflow()` makes an
+  ordinary async function durable: each `step()` records its result, so a workflow that is resumed,
+  continued, or recovered on another worker returns finished steps from its checkpoint and carries on
+  from the first that did not finish. Steps run in parallel through `Promise.all`, bounded by
+  `maxConcurrency`, with per-step retries and timeouts; `interrupt()` pauses for a person exactly as in
+  a graph node; and the checkpoints are ordinary graph checkpoints, so every checkpointer stores
+  them, `traceGraph()` records them, and `graphAssistant()` serves a workflow on the agent server.
+- **Step-level recovery in the agent server.** A run recovered after its worker died continues from
+  the last checkpoint that run wrote — for graphs and workflows served by `graphAssistant()` — so
+  only the step in flight runs again. `AssistantRunContext.attempt` reports the attempt, and the new
+  optional `ServerAssistant.recover()` hook is how an assistant continues.
+- **SQLite persistence** on `nexus-ai-pro/sqlite`: `SqliteOperationStore` for durable operations and,
+  through `OperationStoreCheckpointer`, graph and workflow checkpoints; and `SqliteStore` for
+  long-term memory. Both take the database you open — `node:sqlite` and `better-sqlite3` directly,
+  libSQL through `fromLibsql()` — so no driver is a dependency, and both pass the same contract tests as
+  the memory, Redis, and Postgres stores.
+- **Diagrams as images.** `toSvg()` on `nexus-ai-pro/graph/visualize` draws a graph as a standalone,
+  escaped SVG document with no dependency. `layoutGraph()`, the layered layout underneath, moved from
+  the studio into the core visualizer, so both draw the same diagram.
+
+### Changed
+
+- The server reads a streamed event's `output` before its `state` when it records a run's output, so a
+  workflow's return value is the run's output.
+- `nexus-ai-pro-studio` requires nexus-ai-pro 1.21 or newer, and re-exports `layoutGraph()` from the
+  core visualizer.
+
+### Fixed
+
+- `guardrailPolicy()`, `GUARDRAIL_POLICIES`, `calibrateSemanticInjectionClassifier()`, and
+  `SEMANTIC_INJECTION_CALIBRATION_SET` are exported from `nexus-ai-pro/security`, and the four domain
+  workflows such as `supportTriageWorkflow()` from `nexus-ai-pro/workflows`, as their guides already
+  showed. They were reachable only from the package root. A new docs check fails when a guide's
+  example imports a name from an entry point that does not export it.
+
 ## [1.20.0] - 2026-09-28
 
 Retrieval that scales past one process. Deprecated options now say so at run time, and every guide
@@ -1043,7 +1085,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.20.0...HEAD
+[Unreleased]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.21.0...HEAD
+[1.21.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.20.0...v1.21.0
 [1.20.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.19.0...v1.20.0
 [1.19.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.18.0...v1.19.0
 [1.18.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.17.0...v1.18.0

package/README.md

@@ -114,6 +114,7 @@ from the doc comments. The guides live in the repository, so these links go to G
 | [Evaluation](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/evaluation.md) | Datasets, evaluators, experiments, comparisons with a verdict, review queues, LLM judges |
 | [Prompts](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/prompts.md) | Typed templates, content versions, gated promotion, rollback, A/B splits, serving through outages |
 | [Postgres](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/postgres.md) | One adapter family for operations, memory, traces, evaluation, circuits, and prompts |
+| [SQLite](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/sqlite.md) | Durable operations, checkpoints, and memory on one machine, over any SQLite driver |
 | [Durable operations and jobs](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/operations.md) | Operations that survive a restart, webhooks, and in-process job helpers |
 | [Resilience and observability](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/resilience.md) | Circuit breaking, distributed rate limits, metrics, logs, and audit |
 | [Batch tiers](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/batch.md) | The providers' discounted batch APIs, resumable from any process |

package/dist/graph/functional.d.ts

@@ -0,0 +1,217 @@
+import { GraphError } from './errors.js';
+import type { GraphCheckpoint, GraphCheckpointer, GraphDescription, GraphEvent, GraphStatus, InterruptRequest, PendingInterrupt, RetryPolicy } from '../types/graph.js';
+import type { Store } from '../types/store.js';
+/** What a workflow checkpoint holds: the input, every completed step's result, and the output. */
+export interface WorkflowState<I = unknown, O = unknown> {
+    /** The input the workflow was started with. */
+    input: I;
+    /** Each completed step's result, keyed by step name — `name#2` for the second call with a name. */
+    steps: Record<string, {
+        value?: unknown;
+    }>;
+    /** The workflow's return value, once it has completed. */
+    output?: O;
+}
+/** What a step's function receives. */
+export interface StepContext {
+    /** The step's name. */
+    readonly name: string;
+    /** The key its result is recorded under: the name, or `name#n` for a repeated name. */
+    readonly key: string;
+    /** Attempt number, starting at 1. Above 1 only under a retry policy. */
+    readonly attempt: number;
+    /** Aborted when the run is cancelled or the step exceeds its timeout. */
+    readonly signal: AbortSignal;
+}
+/** How one step runs. */
+export interface StepOptions {
+    /** Retries a failing attempt, overriding the workflow's default policy. */
+    retry?: RetryPolicy;
+    /** Aborts the step's signal and fails the attempt when it runs longer than this, in milliseconds. */
+    timeoutMs?: number;
+}
+/** What a workflow function receives besides its input. */
+export interface WorkflowContext {
+    /** The thread this run belongs to. */
+    readonly threadId: string;
+    /** Aborted when the run is cancelled. */
+    readonly signal: AbortSignal;
+    /** Long-term memory, when the workflow was created with a store. */
+    readonly store?: Store;
+    /**
+     * Runs a piece of work once per thread and records its result.
+     *
+     * When the workflow runs again, a step that already finished returns its recorded result without
+     * running. Name steps so the same call has the same name every time; a name used more than once
+     * is numbered in call order. The result must survive JSON serialization.
+     */
+    step<T>(name: string, run: (context: StepContext) => Promise<T> | T, options?: StepOptions): Promise<T>;
+    /**
+     * Suspends the workflow until a person answers.
+     *
+     * The first time, the run stops with status `awaiting_input` and this question pending. After
+     * `resume()` supplies a value, the workflow runs again from the top — completed steps return their
+     * recorded results — and this call returns the value instead of stopping.
+     */
+    interrupt<T = unknown>(request: InterruptRequest): T;
+    /** Sends anything to the run's `onEvent` listener as a `custom` event. Nothing is recorded. */
+    emit(data: unknown): void;
+}
+/** A workflow function: its input and context in, its output out. */
+export type WorkflowFn<I, O> = (input: I, context: WorkflowContext) => Promise<O> | O;
+/** Options for `workflow()`. */
+export interface WorkflowOptions {
+    /** Names the workflow in checkpoints, events, and diagrams. Defaults to `workflow`. */
+    name?: string;
+    /**
+     * Where checkpoints go. Defaults to an in-process `MemoryGraphCheckpointer`; pass a persistent one
+     * to survive restarts, or `false` to record nothing, which also disables interrupts and resume.
+     */
+    checkpointer?: GraphCheckpointer | false;
+    /** Long-term memory handed to the function as `context.store`. */
+    store?: Store;
+    /** Default retry policy for every step. A step's own policy wins. Defaults to one attempt. */
+    retry?: RetryPolicy;
+    /** Steps that may run at once, for a workflow that starts many with `Promise.all`. Defaults to 16. */
+    maxConcurrency?: number;
+    /** Replaces the system clock, for tests. */
+    now?: () => Date;
+}
+/** Options for one run of a workflow. */
+export interface WorkflowRunOptions {
+    /** Identifies the run. Reusing one continues that thread. Defaults to a generated id. */
+    threadId?: string;
+    /** Stops the run. Steps in flight see the signal. */
+    signal?: AbortSignal;
+    /** Application data recorded on every checkpoint of the run. */
+    metadata?: Record<string, unknown>;
+    /** Receives each step starting, retrying, and finishing, each checkpoint, and custom events. */
+    onEvent?: (event: GraphEvent) => void;
+}
+/** One event of a streamed workflow run. */
+export type WorkflowEvent<O = unknown> = {
+    /** A step finished, or returned its recorded result. */
+    type: 'step';
+    /** Checkpoints written so far in the thread. */
+    step: number;
+    /** The step's name. */
+    name: string;
+    /** The key its result is recorded under. */
+    key: string;
+    /** True when the result came from a checkpoint and the step did not run. */
+    cached: boolean;
+    /** The workflow state after the step. */
+    state: WorkflowState<unknown, O>;
+    /** Always `running`. */
+    status: 'running';
+} | {
+    /** The workflow returned. */
+    type: 'done';
+    /** Checkpoints written in the thread. */
+    step: number;
+    /** The final state. */
+    state: WorkflowState<unknown, O>;
+    /** Always `completed`. */
+    status: 'completed';
+    /** What the workflow returned. */
+    output: O;
+} | {
+    /** The workflow is waiting for a person, or was stopped by its signal. */
+    type: 'interrupt';
+    /** Checkpoints written in the thread. */
+    step: number;
+    /** The state when it stopped. */
+    state: WorkflowState<unknown, O>;
+    /** `awaiting_input` for a question, `interrupted` for a cancelled run. */
+    status: 'awaiting_input' | 'interrupted';
+    /** The first pending question. */
+    interrupt?: PendingInterrupt;
+    /** Every pending question. */
+    interrupts?: PendingInterrupt[];
+};
+/** The outcome of a workflow run. */
+export interface WorkflowResult<O = unknown> {
+    /** The thread the run belongs to. */
+    threadId: string;
+    /** `completed`, `awaiting_input`, or `interrupted`. A failed run throws instead. */
+    status: GraphStatus;
+    /** What the workflow returned, when it completed. */
+    output?: O;
+    /** The workflow state: input, step results, and output. */
+    state: WorkflowState<unknown, O>;
+    /** Steps whose results are recorded. */
+    steps: number;
+    /** The first pending question, when it is waiting. */
+    interrupt?: PendingInterrupt;
+    /** Every pending question. */
+    interrupts?: PendingInterrupt[];
+}
+/** Raised when a step outlives its `timeoutMs`. */
+export declare class WorkflowStepTimeoutError extends GraphError {
+    /** The step. */
+    readonly stepName: string;
+    /** The limit it exceeded, in milliseconds. */
+    readonly timeoutMs: number;
+    constructor(
+    /** The step. */
+    stepName: string, 
+    /** The limit it exceeded, in milliseconds. */
+    timeoutMs: number);
+}
+/**
+ * A durable workflow: a function whose steps are checkpointed, so it survives interrupts, restarts,
+ * and a move to another worker. Create one with `workflow()`.
+ */
+export declare class Workflow<I = unknown, O = unknown> {
+    private readonly fn;
+    private readonly options;
+    /** The workflow's name. */
+    readonly name: string;
+    private readonly defaultCheckpointer;
+    private readonly now;
+    constructor(fn: WorkflowFn<I, O>, options?: WorkflowOptions);
+    /** Runs to the end, or to the first question, and returns the result. */
+    invoke(input: I, runOptions?: WorkflowRunOptions): Promise<WorkflowResult<O>>;
+    /** Runs, yielding an event as each step finishes. */
+    stream(input: I, runOptions?: WorkflowRunOptions): AsyncIterable<WorkflowEvent<O>>;
+    /** Answers the first pending question and runs on. */
+    resume(threadId: string, value: unknown, runOptions?: WorkflowRunOptions): AsyncIterable<WorkflowEvent<O>>;
+    /** Answers the first pending question, runs on, and returns the result. */
+    resumeWith(threadId: string, value: unknown, runOptions?: WorkflowRunOptions): Promise<WorkflowResult<O>>;
+    /** Answers pending questions by id and runs on. */
+    resumeInterrupts(threadId: string, answers: Record<string, unknown>, runOptions?: WorkflowRunOptions): AsyncIterable<WorkflowEvent<O>>;
+    /**
+     * Runs a thread on from its latest checkpoint: after a crash, a failure, or a cancelled run.
+     * Completed steps return their recorded results, so only unfinished work runs again.
+     */
+    continue(threadId: string, runOptions?: WorkflowRunOptions): AsyncIterable<WorkflowEvent<O>>;
+    /** The latest checkpoint, or the one at `step`. */
+    state(threadId: string, step?: number): Promise<GraphCheckpoint | undefined>;
+    /** Every checkpoint of a thread, newest first. */
+    history(threadId: string, limit?: number): Promise<GraphCheckpoint[]>;
+    /** The workflow as a one-node graph, so diagrams and the studio can show it. */
+    describe(): GraphDescription;
+    private checkpointer;
+    private latest;
+    private fresh;
+    private waiting;
+    private answered;
+    private collect;
+    /** Runs the function against a starting checkpoint, streaming events through a queue. */
+    private execute;
+    private run;
+    private runStep;
+}
+/**
+ * Creates a durable workflow from a function.
+ *
+ * ```ts
+ * const refund = workflow(async (input: { orderId: string }, { step, interrupt }) => {
+ *   const order = await step('load', () => orders.get(input.orderId));
+ *   if (!interrupt<boolean>({ reason: `Refund ${order.total}?` })) return { refunded: false };
+ *   await step('refund', () => payments.refund(order.id));
+ *   return { refunded: true };
+ * }, { checkpointer });
+ * ```
+ */
+export declare function workflow<I, O>(fn: WorkflowFn<I, O>, options?: WorkflowOptions): Workflow<I, O>;