nexus-ai-pro 1.7.0 → 1.8.0

package/API_STABILITY.md

@@ -225,6 +225,28 @@ guarantee about how the registry is maintained, not a runtime surface: the resol
 `KNOWN_MODELS`, and a test asserts the two match. Switching the resolver over is a later change, so
 that introducing generation cannot alter pricing behavior in the same release.
 
+## Graph API stage
+
+`createGraph`, `StateGraph`, `CompiledGraph`, the channel constructors, both checkpointers, the error
+classes, and the `nexus-ai-pro/graph` subpath are public and follow the 1.x rules, as are the
+normalized checkpoint, result, and step-event shapes.
+
+Four behaviors are guaranteed. A superstep is atomic with respect to checkpointing: state is reduced
+and written before the next set of nodes is computed. A node that finished is never re-run by a
+resume, so a completed branch's side effect happens once. `interrupt()` returns the supplied value on
+replay rather than throwing again, keyed by node, step, and position, so a node may ask more than one
+question. And `GraphCheckpoint` stays JSON-serializable, because a checkpoint that cannot be written
+to Redis is not a checkpoint.
+
+`GraphCheckpointer` is deliberately not generic over the channel schema: it persists opaque state,
+and threading the schema through it would force an annotation on every construction for no benefit.
+The graph casts at that boundary and hands typed state back through `state()` and `history()`.
+
+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.
+
 ## Deprecation process
 
 Deprecated APIs are marked with `@deprecated` in declarations and described in the changelog. Removals

package/CHANGELOG.md

@@ -4,6 +4,39 @@ Notable changes to this project are recorded here. The format follows [Keep a Ch
 
 ## [Unreleased]
 
+## [Unreleased]
+
+## [1.8.0] - 2026-09-14
+
+Graphs. Nodes, edges, cycles, fan-out and subgraphs over typed state, with every superstep
+checkpointed so a run is resumable, inspectable and interruptible by construction rather than
+after opting in. This closes the five capability rows where LangGraph led, on a subpath that
+costs 5% of the root import.
+
+### Added
+
+- **Typed state graphs.** `nexus-ai-pro/graph` adds nodes, edges, conditional edges, cycles, fan-out,
+  and subgraphs over typed state channels, closing the five capability rows where LangGraph led:
+  explicit nodes and edges, persistent graph state, checkpoint and resume, human-in-the-loop
+  interrupts, and complex branching.
+- **Durable by construction.** Every superstep is checkpointed, so a run is resumable without opting
+  into a checkpointer first. `MemoryGraphCheckpointer` covers a single process;
+  `OperationStoreCheckpointer` persists through the `OperationStore` that already backs durable
+  operations, which makes a Redis-backed thread a one-line change and lets a different worker resume
+  what another suspended. The store is imported as a type only, so the graph subpath stays small.
+- **Human in the loop.** A node calls `context.interrupt()`; the graph checkpoints and reports
+  `awaiting_input`, and `resume()` supplies the value. On replay the same call returns that value
+  instead of throwing, keyed by node, step, and position, so one node can ask several questions
+  across several resumes. A sibling branch that already completed is not re-run.
+- **Channels with reducers** — `lastValue`, `appendList`, `appendSet`, `mergeObject`, `counter`, and
+  `reducerChannel` — so two branches writing the same slot in one superstep combine rather than
+  clobber.
+- **Time travel.** `state()`, `history()`, and `resumeFrom(step)` read and rewind a thread.
+- **Compile-time validation.** An edge to an unknown node, a node nothing routes to, a duplicate node
+  name, and a reserved name are all refused at `compile()` rather than at run time.
+- New subpath `nexus-ai-pro/graph`. It is deliberately absent from the root import, so a user who
+  does not build graphs pays nothing for it.
+
 ## [1.7.0] - 2026-09-08
 
 Batch economics, distributed limits, and durable assets: the rest of the theme *work that
@@ -397,7 +430,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.7.0...HEAD
+[Unreleased]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.8.0...HEAD
+[1.8.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.7.0...v1.8.0
 [1.7.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.6.0...v1.7.0
 [1.6.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.5.0...v1.6.0
 [1.5.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.4.0...v1.5.0

package/README.md

@@ -85,6 +85,7 @@ You can still pass a plain `NexusAIConfig` to `new NexusAI(...)` when you want f
 - add tools, agents, RAG context, evals, batch jobs, and queues
 - embed text through the same routing, caching, batching, budget, retry, and metrics as a completion
 - run long operations that survive a restart, with leases, retries, dead-lettering, and signed webhooks
+- build stateful graphs with cycles, fan-out, subgraphs, human approval, and resumable checkpoints
 - trip routing away from a failing provider, and share one rate-limit budget across workers
 - reach the providers' half-price asynchronous batch tier behind one operation handle
 - persist generated media to disk or S3 with tenant isolation, retention, and checksums
@@ -421,6 +422,90 @@ const response = await ai.completeVerified(
 );
 ```
 
+## Graphs
+
+A graph is nodes, edges, and typed state. Cycles, fan-out, subgraphs, and human approval are
+supported shapes rather than workarounds, and every run is checkpointed, so it is resumable by
+construction rather than after configuring a checkpointer.
+
+```ts
+import { createGraph, appendList, counter, END, MemoryGraphCheckpointer } from 'nexus-ai-pro/graph';
+
+const graph = createGraph({
+  channels: { messages: appendList<string>(), turns: counter() },
+})
+  .addNode('research', async (ctx) => ({ messages: [await search(ctx.state.messages)], turns: 1 }))
+  .addNode('answer', async (ctx) => ({ messages: [await ai.complete(...).then((r) => r.content)] }))
+  .setEntry('research')
+  .addConditionalEdges('research', (state) => (state.turns >= 3 ? 'answer' : 'research'))
+  .addEdge('answer', END)
+  .compile({ checkpointer: new MemoryGraphCheckpointer() });
+
+const result = await graph.invoke({ messages: ['who won?'] }, { threadId: 'q-42' });
+```
+
+**Channels, not assignment.** Each state slot declares how writes combine — `lastValue`,
+`appendList`, `appendSet`, `mergeObject`, `counter`, or your own `reducerChannel`. That is what makes
+fan-out safe: two branches running in the same superstep can both write, and the channel decides
+whether that means overwrite, append, or sum. Assignment would silently drop one branch's work.
+
+**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.
+
+**Human in the loop.** A node calls `interrupt()`; the graph checkpoints and stops:
+
+```ts
+.addNode('approve', (ctx) => ({
+  approved: ctx.interrupt<boolean>({ reason: 'Publish this draft?', payload: { chars: 1200 } }),
+}))
+```
+
+```ts
+const run = await graph.invoke(input, { threadId });
+if (run.status === 'awaiting_input') {
+  // Hours later, in another process:
+  await graph.resumeWith(threadId, true);
+}
+```
+
+The interrupted node runs again from the top and `interrupt()` returns the supplied value instead of
+throwing, so the node body reads as straight-line code either way. Keep the work before an interrupt
+cheap, because it happens twice. A sibling branch that already finished is **not** re-run — its
+writes were checkpointed before the graph suspended.
+
+**Time travel and inspection.** Every superstep is a checkpoint:
+
+```ts
+await graph.state(threadId);        // latest checkpoint
+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
+that already backs durable operations and a thread survives a restart — a different worker resumes
+what another suspended:
+
+```ts
+import { OperationStoreCheckpointer } from 'nexus-ai-pro/graph';
+import { RedisOperationStore } from 'nexus-ai-pro/operations/adapters';
+
+const checkpointer = new OperationStoreCheckpointer(new RedisOperationStore(redis));
+```
+
+Writes are compare-and-set on the record's sequence, so two workers advancing the same thread cannot
+both win.
+
+**Subgraphs.** A compiled graph is a node:
+
+```ts
+parent.addNode('research', researchGraph.asNode());
+```
+
+Channels shared by name are passed in and merged back; anything the parent does not declare stays
+private to the subgraph.
+
+The graph is not in the root import. It costs nothing to a user who does not build graphs.
+
 ## Provider Batch Tiers
 
 Both OpenAI and Anthropic sell an asynchronous tier at roughly half price, in exchange for a
@@ -428,6 +513,7 @@ completion window measured in hours. Local `runBatch()` concurrency cannot reach
 different API. `BatchManager` puts both behind one operation handle.
 
 ```ts
+import { createGraph } from 'nexus-ai-pro/graph';
 import { BatchManager } from 'nexus-ai-pro/batch';
 import { OpenAIBatchProvider } from 'nexus-ai-pro/batch/openai';
 

package/dist/graph/channels.d.ts

@@ -0,0 +1,19 @@
+import type { Channel } from '../types/graph.js';
+/**
+ * The last write wins.
+ *
+ * The right default for a scalar a node computes fresh each time. Under fan-out the winner is
+ * whichever branch reduced last, so prefer an accumulating channel when several branches write the
+ * same slot and the outcome matters.
+ */
+export declare function lastValue<T>(initial?: T): Channel<T>;
+/** Concatenates every write, which is what a message history or an event log wants. */
+export declare function appendList<T>(): Channel<T[]>;
+/** Shallow-merges object writes, so two branches can each contribute their own keys. */
+export declare function mergeObject<T extends Record<string, unknown>>(): Channel<T>;
+/** Sums numeric writes, for a counter several branches increment. */
+export declare function counter(initial?: number): Channel<number>;
+/** Keeps distinct values in first-seen order. */
+export declare function appendSet<T>(): Channel<T[]>;
+/** Builds a channel from a plain reducer, for a rule none of the built-ins covers. */
+export declare function reducerChannel<T>(reduce: (current: T | undefined, update: T) => T, initial?: () => T): Channel<T>;

package/dist/graph/channels.js

@@ -0,0 +1,55 @@
+/**
+ * The last write wins.
+ *
+ * The right default for a scalar a node computes fresh each time. Under fan-out the winner is
+ * whichever branch reduced last, so prefer an accumulating channel when several branches write the
+ * same slot and the outcome matters.
+ */
+export function lastValue(initial) {
+    return {
+        reduce: (_current, update) => update,
+        ...(initial === undefined ? {} : { initial: () => initial }),
+    };
+}
+/** Concatenates every write, which is what a message history or an event log wants. */
+export function appendList() {
+    return {
+        reduce: (current, update) => [...(current ?? []), ...update],
+        initial: () => [],
+    };
+}
+/** Shallow-merges object writes, so two branches can each contribute their own keys. */
+export function mergeObject() {
+    return {
+        reduce: (current, update) => ({ ...(current ?? {}), ...update }),
+        initial: () => ({}),
+    };
+}
+/** Sums numeric writes, for a counter several branches increment. */
+export function counter(initial = 0) {
+    return {
+        reduce: (current, update) => (current ?? initial) + update,
+        initial: () => initial,
+    };
+}
+/** Keeps distinct values in first-seen order. */
+export function appendSet() {
+    return {
+        reduce: (current, update) => {
+            const seen = new Set(current ?? []);
+            const merged = [...(current ?? [])];
+            for (const value of update) {
+                if (!seen.has(value)) {
+                    seen.add(value);
+                    merged.push(value);
+                }
+            }
+            return merged;
+        },
+        initial: () => [],
+    };
+}
+/** Builds a channel from a plain reducer, for a rule none of the built-ins covers. */
+export function reducerChannel(reduce, initial) {
+    return { reduce, ...(initial ? { initial } : {}) };
+}

package/dist/graph/checkpointer.d.ts

@@ -0,0 +1,62 @@
+import type { GraphCheckpoint, GraphCheckpointer } from '../types/graph.js';
+import type { OperationRecord, OperationStore } from '../types/operations.js';
+export interface MemoryGraphCheckpointerOptions {
+    /** Checkpoints kept per thread, newest first. Defaults to 50. */
+    maxPerThread?: number;
+}
+/**
+ * In-process checkpoint history.
+ *
+ * The default, and enough for a single process that wants interrupts, resume, and time travel
+ * without a store. It does not survive a restart; `OperationStoreCheckpointer` does.
+ */
+export declare class MemoryGraphCheckpointer implements GraphCheckpointer {
+    private readonly threads;
+    private readonly maxPerThread;
+    constructor(options?: MemoryGraphCheckpointerOptions);
+    put(checkpoint: GraphCheckpoint): void;
+    get(threadId: string, step?: number): GraphCheckpoint | undefined;
+    history(threadId: string, limit?: number): GraphCheckpoint[];
+    delete(threadId: string): void;
+    /** Thread ids this checkpointer knows about. */
+    threadIds(): string[];
+}
+export interface OperationStoreCheckpointerOptions {
+    /** Checkpoints kept per thread. Defaults to 50. */
+    maxPerThread?: number;
+}
+/**
+ * Persists checkpoints through the `OperationStore` that already backs durable operations.
+ *
+ * This is what makes a graph durable without the graph module depending on the operations runtime:
+ * the store is imported as a type only, so `nexus-ai-pro/graph` stays small, and handing it a
+ * `RedisOperationStore` is all it takes to make a thread survive a restart.
+ *
+ * Each checkpoint is one record at `<threadId>#<step>`, with a head record at `<threadId>` naming
+ * the latest step. Two records per superstep, in exchange for time travel and a resume point that
+ * another process can read.
+ */
+export declare class OperationStoreCheckpointer implements GraphCheckpointer {
+    private readonly store;
+    private readonly maxPerThread;
+    constructor(store: OperationStore<GraphCheckpoint | ThreadHead>, options?: OperationStoreCheckpointerOptions);
+    put(checkpoint: GraphCheckpoint): Promise<void>;
+    get(threadId: string, step?: number): Promise<GraphCheckpoint | undefined>;
+    history(threadId: string, limit?: number): Promise<GraphCheckpoint[]>;
+    delete(threadId: string): Promise<void>;
+    private readHead;
+    /**
+     * Writes one record, creating it when absent and otherwise updating in place.
+     *
+     * `update` is a compare-and-set on the record's sequence, so two workers advancing the same
+     * thread cannot both win; the loser simply re-reads on its next step.
+     */
+    private write;
+}
+interface ThreadHead {
+    kind: 'graph-thread';
+    latest: number;
+    steps: number[];
+}
+/** Re-exported for the adapter's signature, so a caller need not import the operations types. */
+export type { OperationRecord, OperationStore };

package/dist/graph/checkpointer.js

@@ -0,0 +1,136 @@
+/**
+ * In-process checkpoint history.
+ *
+ * The default, and enough for a single process that wants interrupts, resume, and time travel
+ * without a store. It does not survive a restart; `OperationStoreCheckpointer` does.
+ */
+export class MemoryGraphCheckpointer {
+    threads = new Map();
+    maxPerThread;
+    constructor(options = {}) {
+        this.maxPerThread = options.maxPerThread ?? 50;
+    }
+    put(checkpoint) {
+        const list = this.threads.get(checkpoint.threadId) ?? [];
+        // A resumed run can rewrite a step it already wrote, so replace rather than append blindly.
+        const existing = list.findIndex((item) => item.step === checkpoint.step);
+        if (existing >= 0)
+            list.splice(existing, 1);
+        list.push(clone(checkpoint));
+        list.sort((a, b) => a.step - b.step);
+        while (list.length > this.maxPerThread)
+            list.shift();
+        this.threads.set(checkpoint.threadId, list);
+    }
+    get(threadId, step) {
+        const list = this.threads.get(threadId);
+        if (!list?.length)
+            return undefined;
+        const found = step === undefined ? list[list.length - 1] : list.find((item) => item.step === step);
+        return found ? clone(found) : undefined;
+    }
+    history(threadId, limit = 20) {
+        const list = this.threads.get(threadId) ?? [];
+        return [...list].reverse().slice(0, limit).map(clone);
+    }
+    delete(threadId) {
+        this.threads.delete(threadId);
+    }
+    /** Thread ids this checkpointer knows about. */
+    threadIds() {
+        return [...this.threads.keys()];
+    }
+}
+/**
+ * Persists checkpoints through the `OperationStore` that already backs durable operations.
+ *
+ * This is what makes a graph durable without the graph module depending on the operations runtime:
+ * the store is imported as a type only, so `nexus-ai-pro/graph` stays small, and handing it a
+ * `RedisOperationStore` is all it takes to make a thread survive a restart.
+ *
+ * Each checkpoint is one record at `<threadId>#<step>`, with a head record at `<threadId>` naming
+ * the latest step. Two records per superstep, in exchange for time travel and a resume point that
+ * another process can read.
+ */
+export class OperationStoreCheckpointer {
+    store;
+    maxPerThread;
+    constructor(store, options = {}) {
+        this.store = store;
+        this.maxPerThread = options.maxPerThread ?? 50;
+    }
+    async put(checkpoint) {
+        await this.write(stepId(checkpoint.threadId, checkpoint.step), checkpoint);
+        const head = await this.readHead(checkpoint.threadId);
+        const steps = [...new Set([...(head?.steps ?? []), checkpoint.step])].sort((a, b) => a - b);
+        while (steps.length > this.maxPerThread) {
+            const dropped = steps.shift();
+            await this.store.delete?.(stepId(checkpoint.threadId, dropped));
+        }
+        await this.write(checkpoint.threadId, { kind: 'graph-thread', latest: checkpoint.step, steps });
+    }
+    async get(threadId, step) {
+        const target = step ?? (await this.readHead(threadId))?.latest;
+        if (target === undefined)
+            return undefined;
+        const record = await this.store.read(stepId(threadId, target));
+        return record?.result && !isHead(record.result) ? record.result : undefined;
+    }
+    async history(threadId, limit = 20) {
+        const head = await this.readHead(threadId);
+        if (!head)
+            return [];
+        const wanted = [...head.steps].reverse().slice(0, limit);
+        const found = [];
+        for (const step of wanted) {
+            const checkpoint = await this.get(threadId, step);
+            if (checkpoint)
+                found.push(checkpoint);
+        }
+        return found;
+    }
+    async delete(threadId) {
+        const head = await this.readHead(threadId);
+        for (const step of head?.steps ?? [])
+            await this.store.delete?.(stepId(threadId, step));
+        await this.store.delete?.(threadId);
+    }
+    async readHead(threadId) {
+        const record = await this.store.read(threadId);
+        return record?.result && isHead(record.result) ? record.result : undefined;
+    }
+    /**
+     * Writes one record, creating it when absent and otherwise updating in place.
+     *
+     * `update` is a compare-and-set on the record's sequence, so two workers advancing the same
+     * thread cannot both win; the loser simply re-reads on its next step.
+     */
+    async write(id, value) {
+        const existing = await this.store.read(id);
+        const now = new Date().toISOString();
+        if (!existing) {
+            await this.store.create({
+                id,
+                status: 'succeeded',
+                attempt: 1,
+                maxAttempts: 1,
+                sequence: 0,
+                createdAt: now,
+                updatedAt: now,
+                kind: 'graph.checkpoint',
+                result: value,
+            });
+            return;
+        }
+        await this.store.update({ ...existing, result: value, sequence: existing.sequence + 1, updatedAt: now }, existing.sequence);
+    }
+}
+function isHead(value) {
+    return typeof value === 'object' && value !== null && value.kind === 'graph-thread';
+}
+function stepId(threadId, step) {
+    return `${threadId}#${step}`;
+}
+function clone(value) {
+    return structuredClone(value);
+}

package/dist/graph/errors.d.ts

@@ -0,0 +1,50 @@
+import type { InterruptRequest, PendingInterrupt } from '../types/graph.js';
+export declare class GraphError extends Error {
+    readonly code: string;
+    readonly cause?: unknown | undefined;
+    constructor(message: string, code: string, cause?: unknown | undefined);
+}
+export declare class GraphValidationError extends GraphError {
+    constructor(message: string, cause?: unknown);
+}
+/**
+ * Thrown by `context.interrupt()` to suspend the graph.
+ *
+ * Control flow, not a failure: the runtime catches it, checkpoints, and reports `awaiting_input`.
+ * It escapes to the caller only when a node interrupts on a graph compiled without a checkpointer,
+ * where there would be nothing to resume from.
+ */
+export declare class GraphInterrupt extends GraphError {
+    readonly request: InterruptRequest;
+    readonly node: string;
+    readonly step: number;
+    readonly index: number;
+    constructor(request: InterruptRequest, node: string, step: number, index: number);
+}
+/**
+ * Raised when a run exceeds its superstep budget.
+ *
+ * Cycles are a supported shape, so this is the only thing standing between a mistaken router and an
+ * infinite loop. The message names what was still pending.
+ */
+export declare class GraphStepLimitError extends GraphError {
+    readonly maxSteps: number;
+    readonly pending: readonly string[];
+    constructor(maxSteps: number, pending: readonly string[]);
+}
+export declare class GraphNodeError extends GraphError {
+    readonly node: string;
+    readonly step: number;
+    constructor(node: string, step: number, cause: unknown);
+}
+export declare class GraphThreadNotFoundError extends GraphError {
+    readonly threadId: string;
+    constructor(threadId: string);
+}
+export declare class GraphNotInterruptedError extends GraphError {
+    readonly threadId: string;
+    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;

package/dist/graph/errors.js

@@ -0,0 +1,85 @@
+export class GraphError extends Error {
+    code;
+    cause;
+    constructor(message, code, cause) {
+        super(message);
+        this.code = code;
+        this.cause = cause;
+        this.name = 'GraphError';
+    }
+}
+export class GraphValidationError extends GraphError {
+    constructor(message, cause) {
+        super(message, 'GRAPH_VALIDATION_ERROR', cause);
+        this.name = 'GraphValidationError';
+    }
+}
+/**
+ * Thrown by `context.interrupt()` to suspend the graph.
+ *
+ * Control flow, not a failure: the runtime catches it, checkpoints, and reports `awaiting_input`.
+ * It escapes to the caller only when a node interrupts on a graph compiled without a checkpointer,
+ * where there would be nothing to resume from.
+ */
+export class GraphInterrupt extends GraphError {
+    request;
+    node;
+    step;
+    index;
+    constructor(request, node, step, index) {
+        super(`Graph interrupted at "${node}": ${request.reason}`, 'GRAPH_INTERRUPT');
+        this.request = request;
+        this.node = node;
+        this.step = step;
+        this.index = index;
+        this.name = 'GraphInterrupt';
+    }
+}
+/**
+ * Raised when a run exceeds its superstep budget.
+ *
+ * Cycles are a supported shape, so this is the only thing standing between a mistaken router and an
+ * infinite loop. The message names what was still pending.
+ */
+export class GraphStepLimitError extends GraphError {
+    maxSteps;
+    pending;
+    constructor(maxSteps, pending) {
+        super(`Graph exceeded ${maxSteps} supersteps without reaching END. Pending: ${pending.join(', ') || 'none'}. Raise maxSteps, or check that a conditional edge eventually routes to END.`, 'GRAPH_STEP_LIMIT');
+        this.maxSteps = maxSteps;
+        this.pending = pending;
+        this.name = 'GraphStepLimitError';
+    }
+}
+export class GraphNodeError extends GraphError {
+    node;
+    step;
+    constructor(node, step, cause) {
+        super(`Graph node "${node}" failed at step ${step}: ${cause instanceof Error ? cause.message : String(cause)}`, 'GRAPH_NODE_ERROR', cause);
+        this.node = node;
+        this.step = step;
+        this.name = 'GraphNodeError';
+    }
+}
+export class GraphThreadNotFoundError extends GraphError {
+    threadId;
+    constructor(threadId) {
+        super(`No checkpoint for thread "${threadId}". A thread is resumable only when the graph was compiled with a checkpointer and run with an explicit threadId.`, 'GRAPH_THREAD_NOT_FOUND');
+        this.threadId = threadId;
+        this.name = 'GraphThreadNotFoundError';
+    }
+}
+export class GraphNotInterruptedError extends GraphError {
+    threadId;
+    status;
+    constructor(threadId, status) {
+        super(`Thread "${threadId}" is ${status}, not awaiting input, so there is nothing to resume with`, 'GRAPH_NOT_INTERRUPTED');
+        this.threadId = threadId;
+        this.status = status;
+        this.name = 'GraphNotInterruptedError';
+    }
+}
+/** Stable key for one interrupt, so a replayed node picks up the answer it was given. */
+export function interruptKey(pending) {
+    return `${pending.node}:${pending.step}:${pending.index}`;
+}