nexus-ai-pro 2.0.0 → 2.2.0

package/dist-cjs/graph/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.START = exports.Send = exports.END = exports.Command = exports.interruptKey = exports.GraphValidationError = exports.GraphThreadNotFoundError = exports.GraphStepLimitError = exports.GraphNotInterruptedError = exports.GraphNodeTimeoutError = exports.GraphNodeError = exports.GraphInterrupt = exports.GraphError = exports.OperationStoreCheckpointer = exports.MemoryGraphCheckpointer = exports.reducerChannel = exports.mergeObject = exports.lastValue = exports.counter = exports.appendSet = exports.appendList = exports.toCheckpoint = exports.migrateCheckpoint = exports.createGraph = exports.StateGraph = exports.CompiledGraph = void 0;
+exports.START = exports.Send = exports.END = exports.Command = exports.GraphStreamOverflowError = exports.GraphEventStream = exports.RunControl = exports.interruptKey = exports.GraphValidationError = exports.GraphThreadNotFoundError = exports.GraphStepLimitError = exports.GraphNotInterruptedError = exports.GraphNodeTimeoutError = exports.GraphNodeError = exports.GraphInterrupt = exports.GraphError = exports.GraphDrainedError = exports.OperationStoreCheckpointer = exports.MemoryGraphCheckpointer = exports.reducerChannel = exports.mergeObject = exports.lastValue = exports.counter = exports.appendSet = exports.appendList = exports.toCheckpoint = exports.migrateCheckpoint = exports.createGraph = exports.StateGraph = exports.CompiledGraph = void 0;
 var graph_js_1 = require("./graph.js");
 Object.defineProperty(exports, "CompiledGraph", { enumerable: true, get: function () { return graph_js_1.CompiledGraph; } });
 Object.defineProperty(exports, "StateGraph", { enumerable: true, get: function () { return graph_js_1.StateGraph; } });
@@ -19,6 +19,7 @@ var checkpointer_js_1 = require("./checkpointer.js");
 Object.defineProperty(exports, "MemoryGraphCheckpointer", { enumerable: true, get: function () { return checkpointer_js_1.MemoryGraphCheckpointer; } });
 Object.defineProperty(exports, "OperationStoreCheckpointer", { enumerable: true, get: function () { return checkpointer_js_1.OperationStoreCheckpointer; } });
 var errors_js_1 = require("./errors.js");
+Object.defineProperty(exports, "GraphDrainedError", { enumerable: true, get: function () { return errors_js_1.GraphDrainedError; } });
 Object.defineProperty(exports, "GraphError", { enumerable: true, get: function () { return errors_js_1.GraphError; } });
 Object.defineProperty(exports, "GraphInterrupt", { enumerable: true, get: function () { return errors_js_1.GraphInterrupt; } });
 Object.defineProperty(exports, "GraphNodeError", { enumerable: true, get: function () { return errors_js_1.GraphNodeError; } });
@@ -28,6 +29,11 @@ Object.defineProperty(exports, "GraphStepLimitError", { enumerable: true, get: f
 Object.defineProperty(exports, "GraphThreadNotFoundError", { enumerable: true, get: function () { return errors_js_1.GraphThreadNotFoundError; } });
 Object.defineProperty(exports, "GraphValidationError", { enumerable: true, get: function () { return errors_js_1.GraphValidationError; } });
 Object.defineProperty(exports, "interruptKey", { enumerable: true, get: function () { return errors_js_1.interruptKey; } });
+var run_control_js_1 = require("./run-control.js");
+Object.defineProperty(exports, "RunControl", { enumerable: true, get: function () { return run_control_js_1.RunControl; } });
+var event_stream_js_1 = require("./event-stream.js");
+Object.defineProperty(exports, "GraphEventStream", { enumerable: true, get: function () { return event_stream_js_1.GraphEventStream; } });
+Object.defineProperty(exports, "GraphStreamOverflowError", { enumerable: true, get: function () { return event_stream_js_1.GraphStreamOverflowError; } });
 var graph_js_2 = require("../types/graph.js");
 Object.defineProperty(exports, "Command", { enumerable: true, get: function () { return graph_js_2.Command; } });
 Object.defineProperty(exports, "END", { enumerable: true, get: function () { return graph_js_2.END; } });

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

@@ -0,0 +1,57 @@
+import type { GraphDescription } from '../types/graph.js';
+/** How much a lint finding matters: `error` fails `nexus graph lint`, the others only report. */
+export type GraphLintSeverity = 'error' | 'warning' | 'info';
+/** The rules `lintGraph()` checks. */
+export type GraphLintCode = 'UNBOUNDED_CYCLE' | 'RETRY_WITHOUT_IDEMPOTENCY' | 'RETRY_WITHOUT_TIMEOUT' | 'DEFERRED_DURABILITY_WITH_SIDE_EFFECTS' | 'MEMORY_CHECKPOINTER' | 'NO_CHECKPOINTER' | 'UNBOUNDED_CONCURRENCY' | 'DYNAMIC_ROUTE';
+/** One design problem `lintGraph()` found. */
+export interface GraphLintFinding {
+    /** Which rule found it. */
+    code: GraphLintCode;
+    /** How much it matters. */
+    severity: GraphLintSeverity;
+    /** The node it is about, as a path through subgraphs such as `review/approve`. Absent for the graph itself. */
+    node?: string;
+    /** What is wrong. */
+    message: string;
+    /** What to do about it. */
+    fix: string;
+}
+/** Options for `lintGraph()`. */
+export interface GraphLintOptions {
+    /**
+     * The graph runs where a restart, a second replica, or a hand-off is normal: under the agent
+     * server, a job queue, or more than one process. An in-process checkpointer is then an error, not
+     * a note.
+     */
+    deployed?: boolean;
+    /** Rules to skip, by code. */
+    ignore?: GraphLintCode[];
+}
+/**
+ * Finds designs that work in a demo and fail in production, by reading a compiled graph's shape.
+ *
+ * It needs no run and calls no node: it reads `describe()`, so it also works on a description saved
+ * as JSON. The checks:
+ *
+ * | Code | Severity | Finds |
+ * | --- | --- | --- |
+ * | `UNBOUNDED_CYCLE` | error | A cycle of static edges, which only the step limit can stop |
+ * | `RETRY_WITHOUT_IDEMPOTENCY` | warning | A retried node not declared `idempotent`, whose side effects can repeat |
+ * | `RETRY_WITHOUT_TIMEOUT` | warning | A retried node with no timeout, whose hung attempt is never retried |
+ * | `DEFERRED_DURABILITY_WITH_SIDE_EFFECTS` | warning | `async` or `exit` durability with nodes not declared `idempotent` |
+ * | `MEMORY_CHECKPOINTER` | warning, or error when `deployed` | The in-process default, which a restart loses |
+ * | `NO_CHECKPOINTER` | info | No checkpoints, so no interrupt, resume, or recovery |
+ * | `UNBOUNDED_CONCURRENCY` | warning | A fan-out with no limit on tasks at once |
+ * | `DYNAMIC_ROUTE` | info | A router with no mapping or `ends`, so routes cannot be checked |
+ *
+ * @example
+ * ```ts
+ * import { lintGraph } from 'nexus-ai-pro/graph/lint';
+ *
+ * const findings = lintGraph(graph, { deployed: true });
+ * for (const finding of findings) console.log(finding.severity, finding.code, finding.message);
+ * ```
+ */
+export declare function lintGraph(graph: {
+    describe(): GraphDescription;
+} | GraphDescription, options?: GraphLintOptions): GraphLintFinding[];

package/dist-cjs/graph/lint.js

@@ -0,0 +1,144 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.lintGraph = lintGraph;
+function lintGraph(graph, options = {}) {
+    const description = 'describe' in graph && typeof graph.describe === 'function' ? graph.describe() : graph;
+    const findings = [];
+    lintDescription(description, '', options, findings, true);
+    const ignored = new Set(options.ignore ?? []);
+    return findings.filter((finding) => !ignored.has(finding.code));
+}
+function lintDescription(description, prefix, options, findings, top) {
+    const at = (node) => `${prefix}${node}`;
+    for (const cycle of staticCycles(description)) {
+        findings.push({
+            code: 'UNBOUNDED_CYCLE',
+            severity: 'error',
+            node: at(cycle[0]),
+            message: `${cycle.map((node) => `"${at(node)}"`).join(' → ')} loop through static edges only, so the run can only stop at the step limit.`,
+            fix: 'Route out of the loop with a conditional edge, a Command with declared ends, or an edge to END.',
+        });
+    }
+    const sideEffecting = [];
+    for (const node of description.nodes) {
+        if (!node.idempotent)
+            sideEffecting.push(node.id);
+        if (node.retry && !node.idempotent) {
+            findings.push({
+                code: 'RETRY_WITHOUT_IDEMPOTENCY',
+                severity: 'warning',
+                node: at(node.id),
+                message: `"${at(node.id)}" is retried up to ${node.maxAttempts ?? 'several'} times but is not declared idempotent, so a side effect can happen more than once.`,
+                fix: 'Give its side effects an idempotency key and declare `idempotent: true`, or stop retrying it.',
+            });
+        }
+        const timed = node.timeoutMs !== undefined || node.timeout?.runMs !== undefined || node.timeout?.idleMs !== undefined;
+        if (node.retry && !timed) {
+            findings.push({
+                code: 'RETRY_WITHOUT_TIMEOUT',
+                severity: 'warning',
+                node: at(node.id),
+                message: `"${at(node.id)}" is retried but has no timeout, so an attempt that hangs is never retried.`,
+                fix: 'Set `timeout: { runMs }`, or `idleMs` with `context.heartbeat()` for long work.',
+            });
+        }
+        if (node.subgraph)
+            lintDescription(node.subgraph, `${at(node.id)}/`, options, findings, false);
+    }
+    if (!top)
+        return;
+    if ((description.durability === 'async' || description.durability === 'exit') && sideEffecting.length > 0) {
+        findings.push({
+            code: 'DEFERRED_DURABILITY_WITH_SIDE_EFFECTS',
+            severity: 'warning',
+            message: `Durability is "${description.durability}", so a crash can repeat supersteps, and ${sideEffecting.map((node) => `"${node}"`).join(', ')} ${sideEffecting.length === 1 ? 'is' : 'are'} not declared idempotent.`,
+            fix: 'Use `sync` durability for graphs with side effects, or make those nodes idempotent and declare it.',
+        });
+    }
+    if (description.checkpointer === 'memory') {
+        findings.push({
+            code: 'MEMORY_CHECKPOINTER',
+            severity: options.deployed ? 'error' : 'warning',
+            message: 'Checkpoints go to the in-process default, so a restart loses every thread, and another process cannot resume one.',
+            fix: 'Pass a persistent checkpointer, such as an OperationStoreCheckpointer over Postgres, SQLite, or Redis.',
+        });
+    }
+    if (description.checkpointer === 'none') {
+        findings.push({
+            code: 'NO_CHECKPOINTER',
+            severity: 'info',
+            message: 'The graph writes no checkpoints, so it cannot interrupt, resume, drain, or recover after a crash.',
+            fix: 'Pass a checkpointer if any of those is needed.',
+        });
+    }
+    if (description.maxConcurrency !== undefined && !Number.isFinite(description.maxConcurrency)) {
+        findings.push({
+            code: 'UNBOUNDED_CONCURRENCY',
+            severity: 'warning',
+            message: 'Tasks in a superstep run with no limit, so a large Send fan-out starts all of them at once.',
+            fix: 'Set `maxConcurrency` to what the services behind the nodes can take.',
+        });
+    }
+    for (const node of description.dynamic) {
+        findings.push({
+            code: 'DYNAMIC_ROUTE',
+            severity: 'info',
+            node: at(node),
+            message: `The router after "${at(node)}" has no mapping and the node declares no ends, so its routes cannot be checked or drawn.`,
+            fix: "Give the conditional edge a mapping, or declare the node's `ends`.",
+        });
+    }
+}
+function staticCycles(description) {
+    const deciding = new Set(description.dynamic);
+    for (const node of description.nodes)
+        if (node.ends?.length)
+            deciding.add(node.id);
+    for (const edge of description.edges)
+        if (edge.conditional)
+            deciding.add(edge.from);
+    const next = new Map();
+    for (const edge of description.edges) {
+        if (edge.conditional || deciding.has(edge.from))
+            continue;
+        next.set(edge.from, [...(next.get(edge.from) ?? []), edge.to]);
+    }
+    const cycles = [];
+    const index = new Map();
+    const low = new Map();
+    const stack = [];
+    const onStack = new Set();
+    let counter = 0;
+    const visit = (node) => {
+        index.set(node, counter);
+        low.set(node, counter);
+        counter += 1;
+        stack.push(node);
+        onStack.add(node);
+        for (const to of next.get(node) ?? []) {
+            if (!index.has(to)) {
+                visit(to);
+                low.set(node, Math.min(low.get(node), low.get(to)));
+            }
+            else if (onStack.has(to)) {
+                low.set(node, Math.min(low.get(node), index.get(to)));
+            }
+        }
+        if (low.get(node) !== index.get(node))
+            return;
+        const component = [];
+        let member;
+        do {
+            member = stack.pop();
+            onStack.delete(member);
+            component.push(member);
+        } while (member !== node);
+        const selfLoop = component.length === 1 && (next.get(node) ?? []).includes(node);
+        if (component.length > 1 || selfLoop)
+            cycles.push(component.reverse());
+    };
+    for (const node of description.nodes)
+        if (!index.has(node.id))
+            visit(node.id);
+    return cycles;
+}

package/dist-cjs/graph/run-control.d.ts

@@ -0,0 +1,28 @@
+import type { RunControlLike } from '../types/graph.js';
+/**
+ * Stops graph runs cleanly: each finishes its current superstep, writes its checkpoint, and ends with
+ * `GraphDrainedError`, so another worker can `continue()` it.
+ *
+ * An abort signal stops a run in the middle of a superstep, cancelling the nodes in flight. A drain
+ * waits for them, which is what a rolling deploy, a spot eviction, or a scale-down wants: nothing
+ * half done, nothing lost. One control can drain any number of runs at once.
+ *
+ * @example
+ * ```ts
+ * const control = new RunControl();
+ * process.on('SIGTERM', () => control.drain('sigterm'));
+ * await graph.invoke(input, { threadId, control });
+ * ```
+ */
+export declare class RunControl implements RunControlLike {
+    private requested;
+    private readonly listeners;
+    /** True once `drain()` was called. */
+    get draining(): boolean;
+    /** Why the drain was requested. */
+    get reason(): string | undefined;
+    /** Asks every run using this control to stop after its current superstep. A second call is ignored. */
+    drain(reason?: string): void;
+    /** Calls `listener` when a drain is requested. Returns a function that removes it. */
+    onDrain(listener: (reason?: string) => void): () => void;
+}

package/dist-cjs/graph/run-control.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RunControl = void 0;
+class RunControl {
+    requested;
+    listeners = new Set();
+    get draining() {
+        return this.requested !== undefined;
+    }
+    get reason() {
+        return this.requested?.reason;
+    }
+    drain(reason) {
+        if (this.requested)
+            return;
+        this.requested = { reason };
+        for (const listener of this.listeners) {
+            try {
+                listener(reason);
+            }
+            catch {
+            }
+        }
+    }
+    onDrain(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+}
+exports.RunControl = RunControl;

package/dist-cjs/images/evals.js

@@ -38,6 +38,7 @@ exports.perceptualSimilarity = perceptualSimilarity;
 exports.textAccuracy = textAccuracy;
 exports.stats = stats;
 const node_crypto_1 = require("node:crypto");
+const signals_js_1 = require("../utils/signals.js");
 const errors_js_1 = require("./errors.js");
 class MemoryReviewQueue {
     items = [];
@@ -72,7 +73,8 @@ class MediaEvalRunner {
         const runsOf = new Map(examples.map((example, index) => [example.id, runCounts[index]]));
         const outcomes = new Map();
         const stop = new AbortController();
-        const signal = runOptions.signal ? AbortSignal.any([stop.signal, runOptions.signal]) : stop.signal;
+        const linked = (0, signals_js_1.linkSignals)([stop.signal, runOptions.signal]);
+        const signal = linked.signal;
         const { evaluate } = await Promise.resolve().then(() => __importStar(require('../evaluate/run.js')));
         const experiment = await evaluate(async (evalCase, { example, run }) => {
             try {
@@ -97,7 +99,7 @@ class MediaEvalRunner {
             signal,
             ...(runOptions.store ? { store: runOptions.store } : {}),
             ...(runOptions.metadata ? { metadata: runOptions.metadata } : {}),
-        });
+        }).finally(linked.dispose);
         const caseReports = [];
         const allScores = {};
         const safety = { truePositives: 0, falsePositives: 0, trueNegatives: 0, falseNegatives: 0 };

package/dist-cjs/operations/adapters.d.ts

@@ -3,7 +3,8 @@ import type { OperationDispatcher, OperationRecord, OperationStore, OperationSto
  * The Redis commands the operation store needs.
  *
  * Structural rather than tied to one client, so `ioredis`, `node-redis`, or a cluster proxy all
- * satisfy it without this package depending on any of them.
+ * satisfy it without this package depending on any of them. The sorted-set commands are needed only
+ * with `index: true`; `ioredis` has them all.
  */
 export interface RedisOperationLikeClient {
     /** Reads a hash field. */
@@ -16,6 +17,14 @@ export interface RedisOperationLikeClient {
     hvals(key: string): Promise<string[]> | string[];
     /** Optional CAS primitive. When absent the store falls back to a read-compare-write. */
     eval?(script: string, numKeys: number, ...args: string[]): Promise<unknown> | unknown;
+    /** Reads several hash fields in one round trip. Used by the index when present. */
+    hmget?(key: string, ...fields: string[]): Promise<Array<string | null>> | Array<string | null>;
+    /** Adds a sorted-set member. Needed with `index: true`. */
+    zadd?(key: string, score: number, member: string): Promise<unknown> | unknown;
+    /** Removes a sorted-set member. Needed with `index: true`. */
+    zrem?(key: string, member: string): Promise<unknown> | unknown;
+    /** Members by score, as `ZRANGEBYSCORE key min max LIMIT offset count`. Needed with `index: true`. */
+    zrangebyscore?(key: string, min: number | string, max: number | string, limit: 'LIMIT', offset: number, count: number): Promise<string[]> | string[];
 }
 /** Options for the Redis operation store. */
 export interface RedisOperationStoreOptions {
@@ -23,6 +32,19 @@ export interface RedisOperationStoreOptions {
     prefix?: string;
     /** Disables the Lua compare-and-set even when the client exposes `eval`. */
     useEval?: boolean;
+    /**
+     * Keeps queued work in a sorted set by age, and leased work in one by lease expiry, so
+     * `listQueued()` and `claimExpired()` read the oldest few records instead of every one: a claim
+     * costs the same with 100,000 operations queued as with 1,000. The records stay the source of
+     * truth; an index entry only says where to look, and one that no longer matches its record is
+     * skipped and removed.
+     *
+     * Off by default, because a 2.1 worker writes records without index entries. Turn it on once every
+     * worker sharing the prefix runs 2.2, then call `reindex()` once to index what is already there.
+     * Needs `zadd`, `zrem`, and `zrangebyscore`; with `eval`, a record and its index entries change in
+     * one step.
+     */
+    index?: boolean;
 }
 /**
  * Redis-backed operation storage, so a submitted operation survives a restart.
@@ -36,8 +58,13 @@ export declare class RedisOperationStore<TResult = unknown> implements Operation
     private readonly client;
     private readonly prefix;
     private readonly useEval;
+    private readonly indexed;
     constructor(client: RedisOperationLikeClient, options?: RedisOperationStoreOptions);
-    /** Stores a new record and indexes its idempotency key. Refuses records carrying raw bytes. */
+    /**
+     * Stores a new record and indexes its idempotency key. Throws `OperationDuplicateError` when another
+     * record holds the key, checked in the same Lua call as the write when the client has `eval`.
+     * Refuses records carrying raw bytes.
+     */
     create(record: OperationRecord<TResult>): Promise<void>;
     /** Reads a record. */
     read(id: string): Promise<OperationRecord<TResult> | undefined>;
@@ -50,19 +77,40 @@ export declare class RedisOperationStore<TResult = unknown> implements Operation
     delete(id: string): Promise<boolean>;
     /**
      * Records whose lease has expired, or running records without one, up to `limit`, for another
-     * worker to take over.
+     * worker to take over. With the index, reads only records whose lease has lapsed.
      */
     claimExpired(now: string, limit: number): Promise<Array<OperationRecord<TResult>>>;
     /** Finds the record that claimed an idempotency key. */
     findByIdempotencyKey(key: string): Promise<OperationRecord<TResult> | undefined>;
     /** Every record. */
     list(): Promise<Array<OperationRecord<TResult>>>;
-    /** Queued records no worker holds, oldest first. Reads every record, as `list()` does. */
+    /**
+     * Queued records no worker holds, oldest first. With the index, reads them oldest first from the
+     * sorted set and stops at `limit`; without it, reads every record, as `list()` does.
+     */
     listQueued(limit: number, filter?: OperationStoreFilter): Promise<Array<OperationRecord<TResult>>>;
     /** Counts unfinished records by status. Reads every record, as `list()` does. */
     stats(now: string, filter?: OperationStoreFilter): Promise<OperationStoreStats>;
+    /**
+     * Indexes every record already stored, for turning `index` on over existing data. Safe to run
+     * while workers are busy, and to run again: it only adds entries, then removes those that no
+     * longer match their record, checking each record as it does. Resolves to how many records it read.
+     */
+    reindex(): Promise<number>;
+    /**
+     * Reads one index in score order up to `max`, a page at a time, keeping records that pass `keep`
+     * until `limit`. Entries whose record is gone or no longer `belongs` are removed afterwards.
+     */
+    private scanIndex;
+    private readMany;
+    /** Removes index entries that no longer describe their record. Only with `eval`, where the check is atomic. */
+    private prune;
+    /** Writes a record's index entries without `eval`, after the record itself. */
+    private place;
     private recordsKey;
     private idempotencyKey;
+    private queuedKey;
+    private leasesKey;
 }
 /** The part of a BullMQ `Queue` the dispatcher needs. */
 export interface BullMQLikeOperationQueue {