nexus-ai-pro 2.0.0 → 2.2.0

package/dist/utils/schema-migrations.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Versioned schema migrations, shared by the Postgres and SQLite adapters.
+ *
+ * Each adapter's tables form a component, such as `operations:nexus_operations`, with numbered
+ * migrations. The database records which ran, with a checksum of their statements, so an upgrade
+ * applies only what is new and an edited migration is refused instead of silently ignored.
+ */
+/** One numbered schema change to one adapter's tables. */
+export interface SchemaMigration {
+    /**
+     * The tables it belongs to, such as `operations:nexus_operations`. Versions count per component,
+     * so two operation stores on two tables migrate independently.
+     */
+    component: string;
+    /** Its number, from 1, in the order it applies. */
+    version: number;
+    /** What it does, in a few words. */
+    name: string;
+    /**
+     * Its statements, in order. Every bundled statement is idempotent (`IF NOT EXISTS`), so a migration
+     * interrupted between statements on a database without transactional DDL runs again safely.
+     */
+    statements: readonly string[];
+}
+/** A migration the database has recorded as applied. */
+export interface AppliedMigration {
+    /** Its component. */
+    component: string;
+    /** Its version. */
+    version: number;
+    /** Its name when it ran. */
+    name: string;
+    /** The checksum of its statements when it ran. */
+    checksum: string;
+    /** ISO-8601 time it was applied. */
+    appliedAt: string;
+}
+/** Where a database stands against the migrations this code knows. */
+export interface MigrationStatus {
+    /** Recorded migrations, oldest first. */
+    applied: AppliedMigration[];
+    /** Known migrations not yet applied, in the order `migrate()` would apply them. */
+    pending: SchemaMigration[];
+    /**
+     * Applied migrations whose statements have changed since: an edited migration, or adapter options,
+     * such as a vector width, that differ from those it ran with. `migrate()` refuses to run while any
+     * remain.
+     */
+    changed: Array<{
+        migration: SchemaMigration;
+        applied: AppliedMigration;
+    }>;
+    /**
+     * Recorded migrations this code does not know, written by a newer release. Expected while a rollout
+     * runs two versions side by side, since every migration only adds.
+     */
+    unknown: AppliedMigration[];
+    /** True when nothing is pending or changed. */
+    current: boolean;
+}
+/** What one `migrate()` call did, or with `dryRun`, would do. */
+export interface MigrationResult {
+    /** Migrations applied, or with `dryRun`, pending. */
+    applied: SchemaMigration[];
+    /** The statements run, or with `dryRun`, that would run, in order. */
+    statements: string[];
+    /** Whether nothing was written. */
+    dryRun: boolean;
+}
+/** Raised when migrations cannot run safely: a changed migration, a bad list, or a lock held too long. */
+export declare class SchemaMigrationError extends Error {
+    /** A stable code: `MIGRATION_CHANGED`, `MIGRATION_INVALID`, or `MIGRATION_LOCKED`. */
+    readonly code: 'MIGRATION_CHANGED' | 'MIGRATION_INVALID' | 'MIGRATION_LOCKED';
+    constructor(code: SchemaMigrationError['code'], message: string);
+}
+/** The default table that records applied migrations. */
+export declare const MIGRATIONS_TABLE = "nexus_schema_migrations";
+/**
+ * A checksum of a migration's statements: cyrb53, a fast 53-bit hash, as 14 hex digits.
+ *
+ * It detects a migration edited after it ran; it is not a security boundary, so it needs no crypto
+ * module and runs anywhere a driver does. Line endings are normalized, so a checkout on Windows
+ * computes the same value as one on Linux.
+ */
+export declare function migrationChecksum(migration: Pick<SchemaMigration, 'statements'>): string;
+/** @internal Refuses a list with a gap, a duplicate, or an empty migration, before anything runs. */
+export declare function validateMigrations(migrations: readonly SchemaMigration[]): void;
+/** @internal Compares known migrations with recorded ones. */
+export declare function planMigrations(known: readonly SchemaMigration[], applied: readonly AppliedMigration[]): MigrationStatus;
+/** @internal Refuses to migrate while an applied migration has changed. */
+export declare function assertUnchanged(status: MigrationStatus): void;
+/** @internal A SQL string literal. Values here are component names and checksums, never user input. */
+export declare function sqlLiteral(value: string): string;
+/** @internal */
+export declare function label(migration: Pick<SchemaMigration, 'component' | 'version' | 'name'>): string;
+/** @internal Waits, for lock polling. */
+export declare function delay(ms: number): Promise<void>;

package/dist/utils/schema-migrations.js

@@ -0,0 +1,91 @@
+export class SchemaMigrationError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'SchemaMigrationError';
+        this.code = code;
+    }
+}
+export const MIGRATIONS_TABLE = 'nexus_schema_migrations';
+export function migrationChecksum(migration) {
+    const text = migration.statements.map((statement) => statement.replace(/\r\n/g, '\n').trim()).join('\n;\n');
+    let h1 = 0xdeadbeef;
+    let h2 = 0x41c6ce57;
+    for (let index = 0; index < text.length; index += 1) {
+        const code = text.charCodeAt(index);
+        h1 = Math.imul(h1 ^ code, 2654435761);
+        h2 = Math.imul(h2 ^ code, 1597334677);
+    }
+    h1 = Math.imul(h1 ^ (h1 >>> 16), 2246822507) ^ Math.imul(h2 ^ (h2 >>> 13), 3266489909);
+    h2 = Math.imul(h2 ^ (h2 >>> 16), 2246822507) ^ Math.imul(h1 ^ (h1 >>> 13), 3266489909);
+    return (4294967296 * (2097151 & h2) + (h1 >>> 0)).toString(16).padStart(14, '0');
+}
+export function validateMigrations(migrations) {
+    const versions = new Map();
+    for (const migration of migrations) {
+        if (!migration.component)
+            throw new SchemaMigrationError('MIGRATION_INVALID', 'A migration has no component');
+        if (!Number.isInteger(migration.version) || migration.version < 1) {
+            throw new SchemaMigrationError('MIGRATION_INVALID', `${migration.component} has version ${migration.version}; versions are integers from 1`);
+        }
+        if (migration.statements.length === 0) {
+            throw new SchemaMigrationError('MIGRATION_INVALID', `${label(migration)} has no statements`);
+        }
+        const list = versions.get(migration.component) ?? [];
+        if (list.includes(migration.version)) {
+            throw new SchemaMigrationError('MIGRATION_INVALID', `${label(migration)} is listed twice`);
+        }
+        list.push(migration.version);
+        versions.set(migration.component, list);
+    }
+    for (const [component, list] of versions) {
+        const sorted = [...list].sort((a, b) => a - b);
+        sorted.forEach((version, index) => {
+            if (version !== index + 1) {
+                throw new SchemaMigrationError('MIGRATION_INVALID', `${component} skips version ${index + 1}`);
+            }
+        });
+    }
+}
+export function planMigrations(known, applied) {
+    validateMigrations(known);
+    const recorded = new Map(applied.map((row) => [`${row.component}@${row.version}`, row]));
+    const knownKeys = new Set(known.map((migration) => `${migration.component}@${migration.version}`));
+    const pending = [];
+    const changed = [];
+    for (const migration of known) {
+        const row = recorded.get(`${migration.component}@${migration.version}`);
+        if (!row)
+            pending.push(migration);
+        else if (row.checksum !== migrationChecksum(migration))
+            changed.push({ migration, applied: row });
+    }
+    const order = new Map();
+    for (const migration of known)
+        if (!order.has(migration.component))
+            order.set(migration.component, order.size);
+    pending.sort((a, b) => order.get(a.component) - order.get(b.component) || a.version - b.version);
+    const sortedApplied = [...applied].sort((a, b) => a.appliedAt.localeCompare(b.appliedAt) || a.component.localeCompare(b.component) || a.version - b.version);
+    return {
+        applied: sortedApplied,
+        pending,
+        changed,
+        unknown: sortedApplied.filter((row) => !knownKeys.has(`${row.component}@${row.version}`)),
+        current: pending.length === 0 && changed.length === 0,
+    };
+}
+export function assertUnchanged(status) {
+    if (status.changed.length === 0)
+        return;
+    const names = status.changed.map(({ migration }) => label(migration)).join(', ');
+    throw new SchemaMigrationError('MIGRATION_CHANGED', `${names} changed after it was applied. A migration is never edited once it runs; add a new one, or check the adapter options (a table or vector width) match those it ran with.`);
+}
+export function sqlLiteral(value) {
+    return `'${value.replace(/'/g, "''")}'`;
+}
+export function label(migration) {
+    return `${migration.component} v${migration.version} (${migration.name})`;
+}
+export function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/utils/signals.d.ts

@@ -0,0 +1,17 @@
+/**
+ * A signal that aborts when any of its sources does, and can be let go of.
+ *
+ * `AbortSignal.any()` cannot be undone: in Node 22 a source signal keeps a reference for every signal
+ * ever composed from it, about half a kilobyte each, for as long as the source lives. A graph composes
+ * one per task attempt from the run's signal, so a long-lived signal shared by many runs — a server's,
+ * a worker's — grew without bound. A linked signal listens to its sources directly and `dispose()`
+ * removes the listeners, so a finished attempt keeps nothing.
+ */
+export interface LinkedSignal {
+    /** Aborts, with that source's reason, when any source aborts. */
+    readonly signal: AbortSignal;
+    /** Stops listening to the sources. Safe to call more than once. */
+    dispose(): void;
+}
+/** Links the given signals; missing ones are ignored, and one signal is returned as it is. */
+export declare function linkSignals(sources: ReadonlyArray<AbortSignal | undefined>): LinkedSignal;

package/dist/utils/signals.js

@@ -0,0 +1,26 @@
+const NOTHING_TO_DISPOSE = () => undefined;
+export function linkSignals(sources) {
+    const present = sources.filter((source) => source !== undefined);
+    if (present.length === 1)
+        return { signal: present[0], dispose: NOTHING_TO_DISPOSE };
+    const controller = new AbortController();
+    const aborted = present.find((source) => source.aborted);
+    if (aborted) {
+        controller.abort(aborted.reason);
+        return { signal: controller.signal, dispose: NOTHING_TO_DISPOSE };
+    }
+    const listeners = [];
+    const dispose = () => {
+        for (const [source, listener] of listeners.splice(0))
+            source.removeEventListener('abort', listener);
+    };
+    for (const source of present) {
+        const listener = () => {
+            controller.abort(source.reason);
+            dispose();
+        };
+        source.addEventListener('abort', listener, { once: true });
+        listeners.push([source, listener]);
+    }
+    return { signal: controller.signal, dispose };
+}

package/dist/utils/tenant.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The tenant id rule every scope shares. An id is letters, digits, `_`, and `-`, so it can never hold
+ * the `/` a scoped name or key is built with: no tenant's prefix is a prefix of another's.
+ */
+/** Refused when a tenant id is empty, too long, or holds a character a scoped key could be split on. */
+export declare class TenantIdError extends RangeError {
+    /** Always `TENANT_ID_INVALID`. */
+    readonly code = "TENANT_ID_INVALID";
+    constructor(tenantId: unknown);
+}
+/** Returns a tenant id unchanged, or throws `TenantIdError` when it is not one. */
+export declare function assertTenantId(tenantId: string): string;
+/** @internal The prefix a tenant's names and keys carry in a shared store. */
+export declare function tenantPrefix(tenantId: string): string;

package/dist/utils/tenant.js

@@ -0,0 +1,16 @@
+export class TenantIdError extends RangeError {
+    code = 'TENANT_ID_INVALID';
+    constructor(tenantId) {
+        super(`"${String(tenantId)}" is not a valid tenant id: use 1 to 128 letters, digits, underscores, and hyphens`);
+        this.name = 'TenantIdError';
+    }
+}
+const TENANT_ID = /^[A-Za-z0-9_-]{1,128}$/;
+export function assertTenantId(tenantId) {
+    if (typeof tenantId !== 'string' || !TENANT_ID.test(tenantId))
+        throw new TenantIdError(tenantId);
+    return tenantId;
+}
+export function tenantPrefix(tenantId) {
+    return `tenant/${assertTenantId(tenantId)}/`;
+}

package/dist/version.d.ts

@@ -0,0 +1,5 @@
+/**
+ * This package's version, recorded where provenance matters, such as on every experiment. A test
+ * keeps it equal to `package.json`.
+ */
+export declare const NEXUS_VERSION = "2.2.0";

package/dist/version.js

@@ -0,0 +1 @@
+export const NEXUS_VERSION = '2.2.0';

package/dist-cjs/agent/create-agent.d.ts

@@ -2,7 +2,7 @@ import type { OperationLifecycleLike } from '../types/lifecycle.js';
 import { type CompiledGraph } from '../graph/graph.js';
 import type { GraphCheckpointer, NodeContext } from '../types/graph.js';
 import type { CompletionRequest, Message, ToolDefinition } from '../types/messages.js';
-import type { NexusResponse } from '../types/response.js';
+import type { NexusResponse, StreamChunk } from '../types/response.js';
 import type { Store } from '../types/store.js';
 /**
  * An agent as a graph.
@@ -17,6 +17,8 @@ import type { Store } from '../types/store.js';
 export interface AgentModelClient {
     /** Runs one completion. */
     complete(request: CompletionRequest): Promise<NexusResponse>;
+    /** Streams one completion. Used when the agent is created with `streamTokens`. */
+    stream?(request: CompletionRequest): AsyncIterable<StreamChunk>;
 }
 /** A tool call the agent is about to make. */
 export interface AgentToolCall {
@@ -108,6 +110,12 @@ export interface CreateAgentOptions {
      * `ai.lifecycle`. Its model calls are operations of their own.
      */
     lifecycle?: OperationLifecycleLike;
+    /**
+     * Streams the model's output token by token onto the run's `messages` events, through the client's
+     * `stream()`. Without it, or with a client that cannot stream, each answer arrives as one message
+     * event once the model returns. Middleware sees the assembled response either way.
+     */
+    streamTokens?: boolean;
 }
 declare const agentChannels: () => {
     messages: import("../types/graph.js").Channel<Message[]>;

package/dist-cjs/agent/create-agent.js

@@ -42,7 +42,12 @@ function createAgent(options) {
         for (const item of middleware) {
             request = (await item.beforeModel?.({ request, state, store: options.store })) ?? request;
         }
-        let response = await options.client.complete(request);
+        let response = options.streamTokens && options.client.stream
+            ? await streamed(options.client.stream(request), (chunk) => context.message(chunk))
+            : await options.client.complete(request);
+        if (!(options.streamTokens && options.client.stream) && response.content) {
+            context.message({ content: response.content });
+        }
         for (const item of middleware) {
             response = (await item.afterModel?.({ response, state, store: options.store })) ?? response;
         }
@@ -93,9 +98,13 @@ function createAgent(options) {
                 args = verdict.args;
         }
         const run = async () => executor.execute(description.name, args);
+        context.tool({ phase: 'start', id: call.id, name: description.name, args });
         const result = await middleware.reduceRight((next, item) => item.wrapToolCall
             ? () => Promise.resolve(item.wrapToolCall?.({ ...description, args }, next))
             : next, run)();
+        context.tool(result.ok
+            ? { phase: 'result', id: call.id, name: description.name, result: result.result }
+            : { phase: 'error', id: call.id, name: description.name, error: result.error ?? 'The tool failed' });
         return { messages: [toolMessage(call, result)] };
     }, { ends: ['model'] })
         .setEntry('model')
@@ -161,3 +170,33 @@ function parseArguments(raw) {
         return { ok: false, error: `Tool arguments are not valid JSON (${reason}); the tool was not run` };
     }
 }
+async function streamed(chunks, onChunk) {
+    let content = '';
+    const toolCalls = [];
+    let meta = {};
+    for await (const chunk of chunks) {
+        if (chunk.type === 'text' && chunk.content) {
+            content += chunk.content;
+            onChunk({ kind: 'text', content: chunk.content });
+        }
+        else if (chunk.type === 'reasoning' && chunk.content) {
+            onChunk({ kind: 'reasoning', content: chunk.content });
+        }
+        else if (chunk.type === 'tool_call' && chunk.toolCall) {
+            toolCalls.push(chunk.toolCall);
+        }
+        else if (chunk.type === 'done') {
+            meta = chunk.meta ?? meta;
+        }
+        else if (chunk.type === 'error') {
+            throw new Error(chunk.error ?? 'The model stream failed');
+        }
+    }
+    return {
+        content,
+        role: 'assistant',
+        ...(toolCalls.length ? { toolCalls } : {}),
+        finishReason: toolCalls.length ? 'tool_calls' : 'stop',
+        meta: meta,
+    };
+}

package/dist-cjs/cache/memory-cache.d.ts

@@ -15,6 +15,14 @@ export declare class MemoryCache<T> {
     constructor(maxEntries?: number);
     /** Returns a value, or `undefined` for a miss or an expired entry. A hit counts as recent use. */
     get(key: string): T | undefined;
+    /**
+     * Like `get()`, also saying whether an entry was there but had expired, which a caller can report
+     * as stale rather than missing. The expired entry is removed either way.
+     */
+    lookup(key: string): {
+        value?: T;
+        stale: boolean;
+    };
     /** Stores a value. Defaults to 5 minutes. */
     set(key: string, value: T, ttlSeconds?: number): void;
     /** Removes every entry. */

package/dist-cjs/cache/memory-cache.js

@@ -20,6 +20,15 @@ class MemoryCache {
         this.entries.set(key, entry);
         return entry.value;
     }
+    lookup(key) {
+        const entry = this.entries.get(key);
+        if (entry && entry.expiresAt < Date.now()) {
+            this.entries.delete(key);
+            return { stale: true };
+        }
+        const value = this.get(key);
+        return value === undefined ? { stale: false } : { value, stale: false };
+    }
     set(key, value, ttlSeconds = 300) {
         if (this.entries.size >= this.maxEntries) {
             const oldest = this.entries.keys().next().value;

package/dist-cjs/cache/semantic-cache.d.ts

@@ -25,10 +25,13 @@ export declare class SemanticCache {
     constructor(options?: SemanticCacheOptions);
     /**
      * The cached response for the most similar earlier request above the threshold, or `undefined`.
+     * Only entries stored under the same `scope` are compared: the client passes the request's tenant
+     * and cache namespace, so one tenant is never answered from another's entry however alike the
+     * questions are.
      */
-    get(request: CompletionRequest): Promise<NexusResponse | undefined>;
-    /** Caches a response under its request's embedding. */
-    set(key: string, request: CompletionRequest, response: NexusResponse): Promise<void>;
+    get(request: CompletionRequest, scope?: string): Promise<NexusResponse | undefined>;
+    /** Caches a response under its request's embedding, in a `scope` lookups must match. */
+    set(key: string, request: CompletionRequest, response: NexusResponse, scope?: string): Promise<void>;
     /** Removes every entry. */
     clear(): void;
 }

package/dist-cjs/cache/semantic-cache.js

@@ -10,7 +10,7 @@ class SemanticCache {
         this.options = options;
         this.embed = options.embed || retrieval_js_1.createHashEmbeddings;
     }
-    async get(request) {
+    async get(request, scope = '') {
         if (!this.options.enabled)
             return undefined;
         const text = requestToSearchText(request);
@@ -20,6 +20,8 @@ class SemanticCache {
         let best;
         this.entries = this.entries.filter((entry) => entry.expiresAt > now);
         for (const entry of this.entries) {
+            if (entry.scope !== scope)
+                continue;
             const score = (0, retrieval_js_1.cosineSimilarity)(embedding, entry.embedding);
             if (score >= threshold && (!best || score > best.score)) {
                 best = { entry, score };
@@ -40,7 +42,7 @@ class SemanticCache {
             },
         };
     }
-    async set(key, request, response) {
+    async set(key, request, response, scope = '') {
         if (!this.options.enabled)
             return;
         const text = requestToSearchText(request);
@@ -50,6 +52,7 @@ class SemanticCache {
             this.entries.shift();
         this.entries.push({
             key,
+            scope,
             text,
             embedding,
             response,

package/dist-cjs/cli/args.js

@@ -53,12 +53,15 @@ exports.BOOLEAN_FLAGS = new Set([
     'allow-dataset-mismatch',
     'check',
     'densify',
+    'dry-run',
     'fail',
     'fail-on-regression',
     'help',
     'json',
     'print',
+    'record',
     'reveal-values',
+    'strict',
     'write',
 ]);
 function parseArgs(args) {

package/dist-cjs/cli/db.d.ts

@@ -1,8 +1,20 @@
 import { type ParsedArgs } from './args.js';
 /**
- * `nexus db sql` prints the Postgres schema for the chosen adapters.
+ * `nexus db sql | status | migrate`.
  *
- * Printed rather than applied, so the CLI needs no database driver and the schema goes through
- * whatever review and migration tooling the application already has: `nexus db sql | psql "$URL"`.
+ * `sql` prints the Postgres schema, so the CLI needs no driver and the schema can go through the
+ * application's own review and tooling: `nexus db sql | psql "$URL"`. `status` and `migrate` reach
+ * the database through a module the application writes, which exports its own client:
+ *
+ * ```js
+ * // db.mjs
+ * import pg from 'pg';
+ * export const client = new pg.Pool({ connectionString: process.env.DATABASE_URL });
+ * export const close = () => client.end();
+ * ```
+ *
+ * The module may also export `dialect` (`postgres` or `sqlite`), a `transaction` function (see
+ * `PostgresMigrateOptions`), and `migrations`, a list replacing the bundled ones, for stores on
+ * custom tables.
  */
-export declare function runDbCommand(subcommand: string | undefined, { flags }: ParsedArgs): Promise<void>;
+export declare function runDbCommand(subcommand: string | undefined, args: ParsedArgs): Promise<void>;