nexus-ai-pro 2.0.0 → 2.2.0

package/dist-cjs/graph/errors.d.ts

@@ -98,7 +98,8 @@ export declare class GraphNotInterruptedError extends GraphError {
     status: string);
 }
 /**
- * Raised when a node outlives its `timeoutMs`.
+ * Raised when a node outlives its run limit, or goes longer than its idle limit without showing
+ * progress.
  *
  * 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.
@@ -106,13 +107,38 @@ export declare class GraphNotInterruptedError extends GraphError {
 export declare class GraphNodeTimeoutError extends GraphError {
     /** The node. */
     readonly node: string;
-    /** The timeout it exceeded, in milliseconds. */
+    /** The limit it exceeded, in milliseconds. */
     readonly timeoutMs: number;
+    /** `run` for the whole-attempt limit, `idle` for the limit between signs of progress. */
+    readonly kind: 'run' | 'idle';
     constructor(
     /** The node. */
     node: string, 
-    /** The timeout it exceeded, in milliseconds. */
-    timeoutMs: number);
+    /** The limit it exceeded, in milliseconds. */
+    timeoutMs: number, 
+    /** `run` for the whole-attempt limit, `idle` for the limit between signs of progress. */
+    kind?: 'run' | 'idle');
+}
+/**
+ * Raised when a run stops because its `RunControl` was drained.
+ *
+ * Not a failure: the superstep in flight finished and its checkpoint was written, so the thread is
+ * intact. Call `continue(threadId)` to resume it, on this worker or another.
+ */
+export declare class GraphDrainedError extends GraphError {
+    /** The thread to continue. */
+    readonly threadId: string;
+    /** Supersteps completed before the drain. */
+    readonly step: number;
+    /** Why the drain was requested. */
+    readonly reason?: string | undefined;
+    constructor(
+    /** The thread to continue. */
+    threadId: string, 
+    /** Supersteps completed before the drain. */
+    step: number, 
+    /** Why the drain was requested. */
+    reason?: string | undefined);
 }
 /**
  * Stable key for one interrupt, so a replayed node picks up the answer it was given.

package/dist-cjs/graph/errors.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GraphNodeTimeoutError = exports.GraphNotInterruptedError = exports.GraphThreadNotFoundError = exports.GraphNodeError = exports.GraphStepLimitError = exports.GraphInterrupt = exports.GraphValidationError = exports.GraphError = void 0;
+exports.GraphDrainedError = exports.GraphNodeTimeoutError = exports.GraphNotInterruptedError = exports.GraphThreadNotFoundError = exports.GraphNodeError = exports.GraphStepLimitError = exports.GraphInterrupt = exports.GraphValidationError = exports.GraphError = void 0;
 exports.interruptKey = interruptKey;
 class GraphError extends Error {
     code;
@@ -82,14 +82,31 @@ exports.GraphNotInterruptedError = GraphNotInterruptedError;
 class GraphNodeTimeoutError extends GraphError {
     node;
     timeoutMs;
-    constructor(node, timeoutMs) {
-        super(`Graph node "${node}" exceeded its ${timeoutMs}ms timeout`, 'GRAPH_NODE_TIMEOUT');
+    kind;
+    constructor(node, timeoutMs, kind = 'run') {
+        super(kind === 'idle'
+            ? `Graph node "${node}" showed no progress for ${timeoutMs}ms, its idle timeout`
+            : `Graph node "${node}" exceeded its ${timeoutMs}ms timeout`, 'GRAPH_NODE_TIMEOUT');
         this.node = node;
         this.timeoutMs = timeoutMs;
+        this.kind = kind;
         this.name = 'GraphNodeTimeoutError';
     }
 }
 exports.GraphNodeTimeoutError = GraphNodeTimeoutError;
+class GraphDrainedError extends GraphError {
+    threadId;
+    step;
+    reason;
+    constructor(threadId, step, reason) {
+        super(`Graph run on thread "${threadId}" drained after step ${step}${reason ? ` (${reason})` : ''}; continue() resumes it`, 'GRAPH_DRAINED');
+        this.threadId = threadId;
+        this.step = step;
+        this.reason = reason;
+        this.name = 'GraphDrainedError';
+    }
+}
+exports.GraphDrainedError = GraphDrainedError;
 function interruptKey(pending) {
     return `${pending.taskId ?? pending.node}:${pending.step}:${pending.index}`;
 }

package/dist-cjs/graph/event-stream.d.ts

@@ -0,0 +1,75 @@
+import type { ChannelSchema, GraphEvent, GraphResult, GraphStepEvent, GraphStreamEvent, GraphStreamOverflow, GraphStreamProjection, GraphStreamStats } from '../types/graph.js';
+import { GraphError } from './errors.js';
+/** Raised by an event stream whose reader fell behind with `overflow: 'error'`. The run is stopped. */
+export declare class GraphStreamOverflowError extends GraphError {
+    /** The buffer that filled. */
+    readonly maxBuffered: number;
+    constructor(
+    /** The buffer that filled. */
+    maxBuffered: number);
+}
+/** What starts the run behind a stream: given the event listener and a signal, the step events. */
+export type GraphRunStarter<S extends ChannelSchema> = (onEvent: (event: GraphEvent) => void, signal: AbortSignal) => AsyncIterable<GraphStepEvent<S>>;
+interface StreamSettings {
+    include: GraphStreamProjection[];
+    subgraphs: boolean;
+    maxBuffered: number;
+    overflow: GraphStreamOverflow;
+}
+/**
+ * A graph run as one stream of typed events, with each projection readable on its own.
+ *
+ * Iterate the stream for every included event, or take `messages()`, `tools()`, `values()`, or
+ * `updates()` for one kind. Every reader gets its own bounded buffer. The run starts when the first
+ * reader asks for an event, so create every reader before reading any. It stops when every reader
+ * has stopped.
+ */
+export declare class GraphEventStream<S extends ChannelSchema, O extends keyof S = keyof S> implements AsyncIterable<GraphStreamEvent<S>> {
+    private readonly start;
+    private readonly toResult;
+    private readonly settings;
+    private readonly readers;
+    private readonly controller;
+    private started;
+    private readonly stats;
+    private resolveResult;
+    private rejectResult;
+    /** Resolves with the run's result once it ends, or rejects with its error. */
+    readonly result: Promise<GraphResult<S, O>>;
+    constructor(start: GraphRunStarter<S>, toResult: (last: GraphStepEvent<S> | undefined) => GraphResult<S, O>, settings: StreamSettings);
+    /** Every included event. */
+    [Symbol.asyncIterator](): AsyncIterator<GraphStreamEvent<S>>;
+    /** Model output, as nodes stream it. */
+    messages(): AsyncIterable<Extract<GraphStreamEvent<S>, {
+        type: 'messages';
+    }>>;
+    /** Tool calls: each starting, progressing, and returning or failing. */
+    tools(): AsyncIterable<Extract<GraphStreamEvent<S>, {
+        type: 'tools';
+    }>>;
+    /** The state after each superstep. */
+    values(): AsyncIterable<Extract<GraphStreamEvent<S>, {
+        type: 'values';
+    }>>;
+    /** Each task's write. */
+    updates(): AsyncIterable<Extract<GraphStreamEvent<S>, {
+        type: 'updates';
+    }>>;
+    /** How the stream kept up with its slowest reader so far. */
+    streamStats(): GraphStreamStats;
+    /** A reader for one projection, registered now so it sees the run from its first event. */
+    private only;
+    private reader;
+    private begin;
+    private publish;
+    private fail;
+    private pump;
+}
+/** Builds a stream's settings from its options. */
+export declare function streamSettings(options: {
+    include?: GraphStreamProjection[];
+    subgraphs?: boolean;
+    maxBuffered?: number;
+    overflow?: GraphStreamOverflow;
+}): StreamSettings;
+export {};

package/dist-cjs/graph/event-stream.js

@@ -0,0 +1,295 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GraphEventStream = exports.GraphStreamOverflowError = void 0;
+exports.streamSettings = streamSettings;
+const errors_js_1 = require("./errors.js");
+const DEFAULT_INCLUDE = ['values', 'updates', 'messages', 'tools', 'custom'];
+const DEFAULT_MAX_BUFFERED = 1_000;
+class GraphStreamOverflowError extends errors_js_1.GraphError {
+    maxBuffered;
+    constructor(maxBuffered) {
+        super(`A graph event reader fell more than ${maxBuffered} events behind`, 'GRAPH_STREAM_OVERFLOW');
+        this.maxBuffered = maxBuffered;
+        this.name = 'GraphStreamOverflowError';
+    }
+}
+exports.GraphStreamOverflowError = GraphStreamOverflowError;
+class Reader {
+    accepts;
+    settings;
+    stats;
+    onOverflow;
+    queue = [];
+    waiting;
+    failure;
+    drained = [];
+    ended = false;
+    error;
+    closed = false;
+    constructor(accepts, settings, stats, onOverflow) {
+        this.accepts = accepts;
+        this.settings = settings;
+        this.stats = stats;
+        this.onOverflow = onOverflow;
+    }
+    push(event) {
+        if (this.closed || !this.accepts(event))
+            return;
+        if (this.waiting) {
+            const resolve = this.waiting;
+            this.waiting = undefined;
+            this.failure = undefined;
+            resolve({ value: event, done: false });
+            return;
+        }
+        if (this.queue.length >= this.settings.maxBuffered && !this.makeRoom(event))
+            return;
+        this.queue.push(event);
+        this.stats.peak = Math.max(this.stats.peak, this.queue.length);
+    }
+    makeRoom(event) {
+        switch (this.settings.overflow) {
+            case 'drop-newest':
+                this.stats.dropped += 1;
+                return false;
+            case 'drop-oldest':
+                this.queue.shift();
+                this.stats.dropped += 1;
+                return true;
+            case 'error':
+                this.onOverflow(new GraphStreamOverflowError(this.settings.maxBuffered));
+                return false;
+            default: {
+                if (this.coalesce(event)) {
+                    this.stats.coalesced += 1;
+                    return false;
+                }
+                this.queue.shift();
+                this.stats.dropped += 1;
+                return true;
+            }
+        }
+    }
+    coalesce(event) {
+        for (let index = this.queue.length - 1; index >= 0; index -= 1) {
+            const queued = this.queue[index];
+            if (event.type === 'messages' && queued.type === 'messages') {
+                const sameMessage = queued.taskId === event.taskId &&
+                    (queued.chunk.kind ?? 'text') === (event.chunk.kind ?? 'text') &&
+                    queued.chunk.messageId === event.chunk.messageId &&
+                    queued.namespace.join('/') === event.namespace.join('/');
+                if (!sameMessage)
+                    continue;
+                this.queue[index] = {
+                    ...queued,
+                    chunk: { ...queued.chunk, content: queued.chunk.content + event.chunk.content },
+                };
+                return true;
+            }
+            if (event.type === 'values' &&
+                queued.type === 'values' &&
+                queued.namespace.join('/') === event.namespace.join('/')) {
+                this.queue[index] = event;
+                return true;
+            }
+        }
+        return false;
+    }
+    whenDrained() {
+        if (this.closed || this.queue.length <= this.settings.maxBuffered / 2)
+            return Promise.resolve();
+        return new Promise((resolve) => this.drained.push(resolve));
+    }
+    next() {
+        const event = this.queue.shift();
+        if (this.queue.length <= this.settings.maxBuffered / 2)
+            this.releaseWaiters();
+        if (event)
+            return Promise.resolve({ value: event, done: false });
+        if (this.error !== undefined)
+            return Promise.reject(this.error);
+        if (this.ended || this.closed)
+            return Promise.resolve({ value: undefined, done: true });
+        return new Promise((resolve, reject) => {
+            this.waiting = resolve;
+            this.failure = reject;
+        });
+    }
+    end(error) {
+        this.ended = true;
+        if (error !== undefined)
+            this.error = error;
+        this.releaseWaiters();
+        if (!this.waiting)
+            return;
+        const resolve = this.waiting;
+        const reject = this.failure;
+        this.waiting = undefined;
+        this.failure = undefined;
+        if (error !== undefined)
+            reject?.(error);
+        else
+            resolve({ value: undefined, done: true });
+    }
+    close() {
+        this.closed = true;
+        this.queue.length = 0;
+        this.end();
+    }
+    releaseWaiters() {
+        const waiters = this.drained;
+        this.drained = [];
+        for (const resolve of waiters)
+            resolve();
+    }
+}
+class GraphEventStream {
+    start;
+    toResult;
+    settings;
+    readers = [];
+    controller = new AbortController();
+    started = false;
+    stats = { peak: 0, coalesced: 0, dropped: 0 };
+    resolveResult;
+    rejectResult;
+    result;
+    constructor(start, toResult, settings) {
+        this.start = start;
+        this.toResult = toResult;
+        this.settings = settings;
+        this.result = new Promise((resolve, reject) => {
+            this.resolveResult = resolve;
+            this.rejectResult = reject;
+        });
+        this.result.catch(() => undefined);
+    }
+    [Symbol.asyncIterator]() {
+        return this.reader(() => true);
+    }
+    messages() {
+        return this.only('messages');
+    }
+    tools() {
+        return this.only('tools');
+    }
+    values() {
+        return this.only('values');
+    }
+    updates() {
+        return this.only('updates');
+    }
+    streamStats() {
+        return { ...this.stats };
+    }
+    only(type) {
+        const iterator = this.reader((event) => event.type === type);
+        return { [Symbol.asyncIterator]: () => iterator };
+    }
+    reader(accepts) {
+        const reader = new Reader(accepts, this.settings, this.stats, (error) => this.fail(error));
+        if (this.started)
+            reader.end();
+        else
+            this.readers.push(reader);
+        return {
+            next: () => {
+                this.begin();
+                return reader.next();
+            },
+            return: async () => {
+                reader.close();
+                if (this.readers.every((item) => item.closed))
+                    this.controller.abort(new Error('Every reader stopped'));
+                return { value: undefined, done: true };
+            },
+        };
+    }
+    begin() {
+        if (this.started)
+            return;
+        this.started = true;
+        void this.pump();
+    }
+    publish(event) {
+        if (event.namespace.length > 0 && !this.settings.subgraphs)
+            return;
+        const projection = event.type;
+        if (!this.settings.include.includes(projection))
+            return;
+        for (const reader of this.readers)
+            reader.push(event);
+    }
+    fail(error) {
+        if (this.controller.signal.aborted)
+            return;
+        this.controller.abort(error);
+        for (const reader of this.readers)
+            reader.end(error);
+        this.rejectResult(error);
+    }
+    async pump() {
+        let last;
+        try {
+            for await (const step of this.start((event) => {
+                for (const item of fromGraphEvent(event))
+                    this.publish(item);
+            }, this.controller.signal)) {
+                last = step;
+                this.publish({ type: 'values', step: step.step, status: step.status, state: step.state, namespace: [] });
+                await Promise.all(this.readers.map((reader) => reader.whenDrained()));
+            }
+            for (const reader of this.readers)
+                reader.end();
+            this.resolveResult(this.toResult(last));
+        }
+        catch (error) {
+            const reason = this.controller.signal.reason;
+            this.fail(reason instanceof GraphStreamOverflowError ? reason : error);
+        }
+    }
+}
+exports.GraphEventStream = GraphEventStream;
+function streamSettings(options) {
+    return {
+        include: options.include ?? DEFAULT_INCLUDE,
+        subgraphs: options.subgraphs ?? false,
+        maxBuffered: Math.max(2, options.maxBuffered ?? DEFAULT_MAX_BUFFERED),
+        overflow: options.overflow ?? 'coalesce',
+    };
+}
+function fromGraphEvent(event) {
+    const namespace = event.namespace ?? [];
+    switch (event.type) {
+        case 'message':
+            return [
+                { type: 'messages', step: event.step, node: event.node, taskId: event.taskId, chunk: event.chunk, namespace },
+            ];
+        case 'tool':
+            return [{ type: 'tools', step: event.step, node: event.node, taskId: event.taskId, tool: event.tool, namespace }];
+        case 'custom':
+            return [
+                { type: 'custom', step: event.step, node: event.node, taskId: event.taskId, data: event.data, namespace },
+            ];
+        case 'checkpoint':
+            return [{ type: 'checkpoints', step: event.step, status: event.status, next: event.next, namespace }];
+        case 'task_end':
+            return [
+                { type: 'tasks', event, namespace },
+                ...(event.update === undefined
+                    ? []
+                    : [
+                        {
+                            type: 'updates',
+                            step: event.step,
+                            node: event.node,
+                            taskId: event.taskId,
+                            update: event.update,
+                            namespace,
+                        },
+                    ]),
+            ];
+        default:
+            return [{ type: 'tasks', event, namespace }];
+    }
+}

package/dist-cjs/graph/functional.d.ts

@@ -1,14 +1,18 @@
 import type { OperationLifecycleLike } from '../types/lifecycle.js';
 import { GraphError } from './errors.js';
-import type { GraphCheckpoint, GraphCheckpointer, GraphDescription, GraphEvent, GraphStatus, InterruptRequest, PendingInterrupt, RetryPolicy } from '../types/graph.js';
+import type { GraphCheckpoint, GraphCheckpointer, GraphDescription, GraphEvent, GraphStatus, InterruptRequest, PendingInterrupt, RetryPolicy, RunControlLike } 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. */
+    /**
+     * Each completed step's result, keyed by step name — `name#2` for the second call with a name. A
+     * step whose `onError` supplied its result after its retries ran out also records `recovered`.
+     */
     steps: Record<string, {
         value?: unknown;
+        recovered?: StepRecovery;
     }>;
     /** The workflow's return value, once it has completed. */
     output?: O;
@@ -23,21 +27,68 @@ export interface StepContext {
     readonly attempt: number;
     /** Aborted when the run is cancelled or the step exceeds its timeout. */
     readonly signal: AbortSignal;
+    /**
+     * Shows the step is still making progress, which refreshes its idle timeout. For long work that
+     * sends nothing else, such as a large upload or a slow tool call.
+     */
+    heartbeat(): void;
+}
+/** Limits on one attempt of a step: its whole run, and the time it may go without progress. */
+export interface StepTimeout {
+    /** Fails the attempt when it runs longer than this, in milliseconds. */
+    runMs?: number;
+    /**
+     * Fails the attempt when this long passes without `context.heartbeat()`, in milliseconds, which
+     * tells a hung step from a slow one that is working.
+     */
+    idleMs?: number;
+}
+/** What a step's `onError` receives once its retries have run out. */
+export interface StepFailure {
+    /** The step's name. */
+    name: string;
+    /** The key its result is recorded under. */
+    key: string;
+    /** Attempts made. */
+    attempts: number;
+    /** The last attempt's error. */
+    error: unknown;
+}
+/** How a step's result was recovered, as recorded in the workflow state. */
+export interface StepRecovery {
+    /** The error that exhausted the step's retries. */
+    error: {
+        name: string;
+        message: string;
+    };
+    /** Attempts made before `onError` decided. */
+    attempts: number;
 }
 /** How one step runs. */
-export interface StepOptions {
+export interface StepOptions<T = unknown> {
     /** 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;
+    /** Run and idle limits on each attempt. `runMs` is `timeoutMs` by another name; `timeoutMs` wins when both are set. */
+    timeout?: StepTimeout;
+    /**
+     * Decides what happens once the step's retries run out. What it returns becomes the step's
+     * result, recorded with `recovered`, so a resumed run does not run the step again — a refund after
+     * a charge that kept failing, say. Throwing fails the step with that error. A cancelled run, a
+     * question, or a drain is never passed to it.
+     */
+    onError?: (failure: StepFailure) => T | Promise<T>;
 }
 /** What a workflow function receives besides its input. */
 export interface WorkflowContext {
     /** The thread this run belongs to. */
     readonly threadId: string;
+    /** The tenant the run is for, when it has one. */
+    readonly tenantId?: string;
     /** Aborted when the run is cancelled. */
     readonly signal: AbortSignal;
-    /** Long-term memory, when the workflow was created with a store. */
+    /** Long-term memory, when the workflow was created with a store. In a tenant's run, the tenant's view of it. */
     readonly store?: Store;
     /**
      * Runs a piece of work once per thread and records its result.
@@ -46,7 +97,7 @@ export interface WorkflowContext {
      * 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>;
+    step<T>(name: string, run: (context: StepContext) => Promise<T> | T, options?: StepOptions<T>): Promise<T>;
     /**
      * Suspends the workflow until a person answers.
      *
@@ -73,6 +124,11 @@ export interface WorkflowOptions {
     store?: Store;
     /** Default retry policy for every step. A step's own policy wins. Defaults to one attempt. */
     retry?: RetryPolicy;
+    /**
+     * Defaults for every step: its retries, its run and idle timeouts, and its `onError`. A step's own
+     * options win, field by field.
+     */
+    stepDefaults?: Pick<StepOptions, 'retry' | 'timeout' | 'onError'>;
     /** Steps that may run at once, for a workflow that starts many with `Promise.all`. Defaults to 16. */
     maxConcurrency?: number;
     /**
@@ -93,6 +149,19 @@ export interface WorkflowRunOptions {
     metadata?: Record<string, unknown>;
     /** Receives each step starting, retrying, and finishing, each checkpoint, and custom events. */
     onEvent?: (event: GraphEvent) => void;
+    /**
+     * Lets the caller stop the run between steps: pass a `RunControl` and call `drain()`. Steps in
+     * flight finish and are recorded, no new step starts, and the run ends with `GraphDrainedError`;
+     * `continue()` carries it on, on this worker or another. The agent server drains a workflow it
+     * serves this way.
+     */
+    control?: RunControlLike;
+    /**
+     * The tenant the run is for. Recorded on every checkpoint as `metadata.tenantId`, read as
+     * `context.tenantId`, and scoping `context.store`; another tenant's thread is not found. A run
+     * without one carries on the thread's.
+     */
+    tenantId?: string;
 }
 /** One event of a streamed workflow run. */
 export type WorkflowEvent<O = unknown> = {
@@ -152,17 +221,21 @@ export interface WorkflowResult<O = unknown> {
     /** Every pending question. */
     interrupts?: PendingInterrupt[];
 }
-/** Raised when a step outlives its `timeoutMs`. */
+/** Raised when a step outlives its run timeout, or goes longer than its idle timeout without progress. */
 export declare class WorkflowStepTimeoutError extends GraphError {
     /** The step. */
     readonly stepName: string;
     /** The limit it exceeded, in milliseconds. */
     readonly timeoutMs: number;
+    /** Which limit: `run` for the whole attempt, `idle` for the time without progress. */
+    readonly kind: 'run' | 'idle';
     constructor(
     /** The step. */
     stepName: string, 
     /** The limit it exceeded, in milliseconds. */
-    timeoutMs: number);
+    timeoutMs: number, 
+    /** Which limit: `run` for the whole attempt, `idle` for the time without progress. */
+    kind?: 'run' | 'idle');
 }
 /**
  * A durable workflow: a function whose steps are checkpointed, so it survives interrupts, restarts,