nexus-ai-pro 2.0.0 → 2.2.0

package/dist/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>;

package/dist/cli/db.js

@@ -1,28 +1,175 @@
-import { postgresMigration } from '../postgres/index.js';
-import { CliUsageError, listFlag, numberFlag } from './args.js';
-const ADAPTERS = [
-    'operations',
-    'store',
-    'traces',
-    'evaluation',
-    'circuits',
-    'prompts',
-    'vectors',
-];
-export async function runDbCommand(subcommand, { flags }) {
-    if (subcommand !== 'sql')
-        throw new CliUsageError(`Unknown db command "${subcommand ?? ''}". Use sql.`);
-    const adapters = listFlag(flags, 'adapters');
-    const unknown = adapters?.filter((adapter) => !ADAPTERS.includes(adapter));
-    if (unknown?.length) {
-        throw new CliUsageError(`Unknown adapter ${unknown.join(', ')}. Choose from ${ADAPTERS.join(', ')}.`);
-    }
+import { POSTGRES_ADAPTERS, postgresMigration, postgresMigrations } from '../postgres/index.js';
+import { CliUsageError, flagBool, listFlag, loadModule, numberFlag, printTable, stringFlag, writeJson, } from './args.js';
+const SQLITE_ADAPTERS = ['operations', 'store', 'vectors'];
+export async function runDbCommand(subcommand, args) {
+    if (subcommand === 'sql')
+        return printSql(args);
+    if (subcommand === 'status' || subcommand === 'migrate')
+        return withDatabase(subcommand, args);
+    throw new CliUsageError(`Unknown db command "${subcommand ?? ''}". Use sql, status, or migrate.`);
+}
+function printSql({ flags }) {
+    const adapters = postgresAdapters(flags);
     const vectorDimensions = numberFlag(flags, 'vector-dimensions');
-    if (adapters?.includes('vectors') && vectorDimensions === undefined) {
-        throw new CliUsageError('The vectors adapter needs --vector-dimensions.');
-    }
     process.stdout.write(postgresMigration({
         ...(adapters ? { adapters } : {}),
         ...(vectorDimensions === undefined ? {} : { vectorDimensions }),
+        ...(flagBool(flags, 'record') ? { record: true } : {}),
     }));
 }
+function postgresAdapters(flags) {
+    const adapters = listFlag(flags, 'adapters');
+    const unknown = adapters?.filter((adapter) => !POSTGRES_ADAPTERS.includes(adapter));
+    if (unknown?.length) {
+        throw new CliUsageError(`Unknown adapter ${unknown.join(', ')}. Choose from ${POSTGRES_ADAPTERS.join(', ')}.`);
+    }
+    if (adapters?.includes('vectors') && numberFlag(flags, 'vector-dimensions') === undefined) {
+        throw new CliUsageError('The vectors adapter needs --vector-dimensions.');
+    }
+    return adapters;
+}
+async function withDatabase(command, { flags }) {
+    const location = stringFlag(flags, 'client');
+    if (!location)
+        throw new CliUsageError(`nexus db ${command} needs --client <db.mjs>, a module exporting \`client\`.`);
+    const database = await openDatabase(location, stringFlag(flags, 'dialect'));
+    try {
+        const migrations = database.migrations ?? (await bundledMigrations(database.dialect, flags));
+        const table = stringFlag(flags, 'table');
+        if (command === 'status') {
+            const status = await statusOf(database, migrations, table);
+            if (flagBool(flags, 'json'))
+                writeJson(status);
+            else
+                printStatus(status);
+            if (flagBool(flags, 'check') && !status.current)
+                process.exitCode = 1;
+            return;
+        }
+        const result = await migrate(database, migrations, { dryRun: flagBool(flags, 'dry-run'), table });
+        if (flagBool(flags, 'json'))
+            writeJson(result);
+        else
+            printResult(result);
+    }
+    finally {
+        await database.close?.();
+    }
+}
+async function openDatabase(location, dialectFlag) {
+    const loaded = await loadModule(location);
+    const client = loaded.client ?? loaded.default;
+    if (!client || typeof client !== 'object') {
+        throw new CliUsageError(`${location} must export a database client as \`client\`.`);
+    }
+    const candidate = client;
+    const dialect = (dialectFlag ?? loaded.dialect);
+    const detected = dialect ??
+        (typeof candidate.query === 'function'
+            ? 'postgres'
+            : typeof candidate.prepare === 'function' || typeof candidate.exec === 'function'
+                ? 'sqlite'
+                : undefined);
+    if (detected !== 'postgres' && detected !== 'sqlite') {
+        throw new CliUsageError(`${location} exports a client this CLI cannot recognize. Export \`dialect\` as "postgres" or "sqlite".`);
+    }
+    return {
+        dialect: detected,
+        client,
+        ...(typeof loaded.transaction === 'function'
+            ? { transaction: loaded.transaction }
+            : {}),
+        ...(Array.isArray(loaded.migrations) ? { migrations: loaded.migrations } : {}),
+        ...(typeof loaded.close === 'function' ? { close: loaded.close } : {}),
+    };
+}
+async function bundledMigrations(dialect, flags) {
+    if (dialect === 'postgres') {
+        const adapters = postgresAdapters(flags);
+        const vectorDimensions = numberFlag(flags, 'vector-dimensions');
+        return postgresMigrations({
+            ...(adapters ? { adapters } : {}),
+            ...(vectorDimensions === undefined ? {} : { vectorDimensions }),
+        });
+    }
+    const adapters = listFlag(flags, 'adapters');
+    const unknown = adapters?.filter((adapter) => !SQLITE_ADAPTERS.includes(adapter));
+    if (unknown?.length) {
+        throw new CliUsageError(`Unknown SQLite adapter ${unknown.join(', ')}. Choose from ${SQLITE_ADAPTERS.join(', ')}.`);
+    }
+    const { sqliteMigrations } = await import('../sqlite/index.js');
+    return sqliteMigrations(adapters ? { adapters } : {});
+}
+async function statusOf(database, migrations, table) {
+    const options = table ? { table } : {};
+    if (database.dialect === 'postgres') {
+        const { postgresMigrationStatus } = await import('../postgres/migrations.js');
+        return postgresMigrationStatus(database.client, migrations, options);
+    }
+    const { sqliteMigrationStatus } = await import('../sqlite/migrations.js');
+    return sqliteMigrationStatus(database.client, migrations, options);
+}
+async function migrate(database, migrations, options) {
+    const common = { dryRun: options.dryRun, ...(options.table ? { table: options.table } : {}) };
+    if (database.dialect === 'postgres') {
+        const { applyPostgresMigrations } = await import('../postgres/migrations.js');
+        return applyPostgresMigrations(database.client, migrations, {
+            ...common,
+            ...(database.transaction ? { transaction: database.transaction } : {}),
+        });
+    }
+    const { applySqliteMigrations } = await import('../sqlite/migrations.js');
+    return applySqliteMigrations(database.client, migrations, common);
+}
+function printStatus(status) {
+    const changed = new Set(status.changed.map(({ migration }) => `${migration.component}@${migration.version}`));
+    const rows = [
+        ...status.applied
+            .filter((row) => !status.unknown.includes(row))
+            .map((row) => {
+            const key = `${row.component}@${row.version}`;
+            return {
+                component: row.component,
+                version: String(row.version),
+                name: row.name,
+                state: changed.has(key) ? 'changed' : 'applied',
+                applied: row.appliedAt,
+            };
+        }),
+        ...status.unknown.map((row) => ({
+            component: row.component,
+            version: String(row.version),
+            name: row.name,
+            state: 'newer release',
+            applied: row.appliedAt,
+        })),
+        ...status.pending.map((migration) => ({
+            component: migration.component,
+            version: String(migration.version),
+            name: migration.name,
+            state: 'pending',
+            applied: '',
+        })),
+    ];
+    if (rows.length === 0) {
+        console.log('No migrations known or recorded.');
+        return;
+    }
+    printTable(rows, ['component', 'version', 'name', 'state', 'applied']);
+    console.log(status.current
+        ? '\nUp to date.'
+        : `\n${status.pending.length} pending${status.changed.length ? `, ${status.changed.length} changed after they ran` : ''}. Run: nexus db migrate`);
+}
+function printResult(result) {
+    if (result.applied.length === 0) {
+        console.log('Nothing to apply: the database is up to date.');
+        return;
+    }
+    const verb = result.dryRun ? 'Would apply' : 'Applied';
+    for (const migration of result.applied)
+        console.log(`${verb} ${migration.component} v${migration.version}: ${migration.name}`);
+    if (result.dryRun) {
+        console.log('\n-- The statements, in order:\n');
+        console.log(`${result.statements.join(';\n\n')};`);
+    }
+}

package/dist/cli/doctor.d.ts

@@ -0,0 +1,17 @@
+import { type ParsedArgs } from './args.js';
+/**
+ * `nexus doctor` checks a deployment and exits 1 when a check fails, or with `--strict` when one
+ * warns. Without `--module` it checks what it can see from the shell: Node.js, packages, credentials,
+ * and the model registry. A module reaches the rest, exporting any of:
+ *
+ * ```js
+ * // doctor.mjs
+ * export const database = { client: pool };       // or `client` alone, as for nexus db
+ * export const redis = new Redis(process.env.REDIS_URL);
+ * export const operations = new PostgresOperationStore(pool);
+ * export const ai = client;
+ * export const deployment = { replicas: 3, stores: { checkpointer, state, tenantUsage } };
+ * export const close = async () => { await pool.end(); redis.disconnect(); };
+ * ```
+ */
+export declare function runDoctorCommand({ flags }: ParsedArgs): Promise<void>;

package/dist/cli/doctor.js

@@ -0,0 +1,53 @@
+import { diagnose } from '../doctor/index.js';
+import { flagBool, isRecord, loadModule, numberFlag, stringFlag, writeJson } from './args.js';
+const LABELS = { ok: 'ok  ', warn: 'warn', fail: 'FAIL', skip: 'skip' };
+export async function runDoctorCommand({ flags }) {
+    const location = stringFlag(flags, 'module');
+    const loaded = location ? await loadModule(location) : {};
+    const options = {};
+    const source = isRecord(loaded.database) ? loaded.database : loaded.client ? loaded : undefined;
+    if (source?.client) {
+        options.database = {
+            client: source.client,
+            ...(source.dialect === 'postgres' || source.dialect === 'sqlite' ? { dialect: source.dialect } : {}),
+            ...(Array.isArray(source.migrations) ? { migrations: source.migrations } : {}),
+            ...(typeof source.table === 'string' ? { table: source.table } : {}),
+        };
+    }
+    if (loaded.redis)
+        options.redis = loaded.redis;
+    if (loaded.operations)
+        options.operations = loaded.operations;
+    if (loaded.ai)
+        options.ai = loaded.ai;
+    if (isRecord(loaded.deployment))
+        options.deployment = loaded.deployment;
+    const replicas = numberFlag(flags, 'replicas');
+    if (replicas !== undefined)
+        options.deployment = { ...options.deployment, replicas };
+    const maxQueueAgeMs = numberFlag(flags, 'max-queue-age-ms');
+    if (maxQueueAgeMs !== undefined)
+        options.maxQueueAgeMs = maxQueueAgeMs;
+    let report;
+    try {
+        report = await diagnose(options);
+    }
+    finally {
+        if (typeof loaded.close === 'function')
+            await loaded.close();
+    }
+    if (flagBool(flags, 'json'))
+        writeJson(report);
+    else
+        print(report);
+    if (!report.ok || (flagBool(flags, 'strict') && report.warnings > 0))
+        process.exitCode = 1;
+}
+function print(report) {
+    for (const check of report.checks) {
+        console.log(`${LABELS[check.status]}  ${check.title}: ${check.detail}`);
+        if (check.hint && (check.status === 'fail' || check.status === 'warn'))
+            console.log(`      ${check.hint}`);
+    }
+    console.log(`\n${report.failures} failed, ${report.warnings} warned, ${report.checks.length - report.failures - report.warnings} passed or skipped.`);
+}

package/dist/cli/graph.d.ts

@@ -0,0 +1,9 @@
+import { type ParsedArgs } from './args.js';
+/**
+ * `nexus graph lint <module>[#export]`.
+ *
+ * The module exports a compiled graph, or a description of one as `describe()` returns it, as the
+ * named export, as `graph`, or as its default. Exits 1 when a finding is an error, or with `--strict`
+ * when any finding is a warning too.
+ */
+export declare function runGraphCommand(subcommand: string | undefined, args: ParsedArgs): Promise<void>;

package/dist/cli/graph.js

@@ -0,0 +1,47 @@
+import { lintGraph } from '../graph/lint.js';
+import { CliUsageError, flagBool, isRecord, listFlag, loadModule, printTable, writeJson, } from './args.js';
+export async function runGraphCommand(subcommand, args) {
+    if (subcommand !== 'lint') {
+        throw new CliUsageError(`Unknown graph command "${subcommand ?? ''}". Use lint.`);
+    }
+    const [target] = args.positionals;
+    if (!target)
+        throw new CliUsageError('nexus graph lint needs a module: nexus graph lint ./graph.mjs[#exportName].');
+    const [file, exportName] = target.split('#');
+    const loaded = await loadModule(file);
+    const graph = (exportName ? loaded[exportName] : (loaded.graph ?? loaded.default ?? loaded));
+    if (!isLintable(graph)) {
+        throw new CliUsageError(`${target} must export a compiled graph, or a graph description, ${exportName ? `as "${exportName}"` : 'as `graph` or its default'}.`);
+    }
+    const findings = lintGraph(graph, {
+        deployed: flagBool(args.flags, 'deployed'),
+        ignore: listFlag(args.flags, 'ignore'),
+    });
+    const failing = findings.filter((finding) => finding.severity === 'error' || (flagBool(args.flags, 'strict') && finding.severity === 'warning'));
+    if (flagBool(args.flags, 'json')) {
+        writeJson({ findings, failed: failing.length > 0 });
+    }
+    else if (findings.length === 0) {
+        console.log('No findings.');
+    }
+    else {
+        printTable(findings.map((finding) => ({
+            severity: finding.severity,
+            code: finding.code,
+            node: finding.node ?? '',
+            message: finding.message,
+        })), ['severity', 'code', 'node', 'message']);
+        console.log('');
+        for (const finding of findings)
+            console.log(`${finding.code}: ${finding.fix}`);
+    }
+    if (failing.length > 0)
+        process.exitCode = 1;
+}
+function isLintable(value) {
+    if (!isRecord(value))
+        return false;
+    if (typeof value.describe === 'function')
+        return true;
+    return Array.isArray(value.nodes) && Array.isArray(value.edges) && Array.isArray(value.dynamic);
+}

package/dist/cli.js

@@ -43,6 +43,11 @@ async function main() {
             await runTracesCommand(subcommand, { positionals: args, flags: parsed.flags });
             return;
         }
+        case 'doctor': {
+            const { runDoctorCommand } = await import('./cli/doctor.js');
+            await runDoctorCommand({ positionals: parsed.positionals.slice(1), flags: parsed.flags });
+            return;
+        }
         case 'db': {
             const [subcommand, ...args] = parsed.positionals;
             const { runDbCommand } = await import('./cli/db.js');
@@ -54,6 +59,12 @@ async function main() {
             await runMigrateCommand(parsed);
             return;
         }
+        case 'graph': {
+            const [subcommand, ...args] = parsed.positionals;
+            const { runGraphCommand } = await import('./cli/graph.js');
+            await runGraphCommand(subcommand, { positionals: args, flags: parsed.flags });
+            return;
+        }
         case 'deploy': {
             const [subcommand, ...args] = parsed.positionals;
             const { runDeployCommand } = await import('./cli/deploy.js');
@@ -400,8 +411,12 @@ Usage:
                     [--min-cost n] [--feedback-key k] [--limit 20] [--offset n] [--json]
   nexus traces show <traceId> --store <runs.jsonl|store.mjs> [--json]
   nexus traces export --store <runs.jsonl|store.mjs> [--out runs.jsonl] [same filters as list]
-  nexus db sql [--adapters operations,store,traces,evaluation,circuits,prompts] [--vector-dimensions 1536]
+  nexus db sql [--adapters operations,store,traces,evaluation,circuits,prompts,rollups] [--vector-dimensions 1536] [--record]
+  nexus db status --client <db.mjs> [--adapters ...] [--dialect postgres|sqlite] [--table t] [--check] [--json]
+  nexus db migrate --client <db.mjs> [--dry-run] [--adapters ...] [--dialect postgres|sqlite] [--table t] [--json]
   nexus migrate [paths...] [--write] [--check] [--json]
+  nexus doctor [--module doctor.mjs] [--replicas n] [--max-queue-age-ms n] [--strict] [--json]
+  nexus graph lint <module>[#export] [--deployed] [--strict] [--ignore CODE,CODE] [--json]
   nexus deploy status [assistant] --url <server> [--token t] [--json]
   nexus deploy canary <assistant> <revision> <percent> --url <server> [--reason r] [--version n]
   nexus deploy promote <assistant> <revision> --url <server> [--reason r] [--version n]
@@ -412,8 +427,12 @@ Eval files can export { cases, client } or { cases, config }. JSON cases may use
 Evaluation modules for "eval run" export { target, dataset, evaluators, summary?, options? }.
 "eval gate" exits 1 when a metric got worse beyond noise, a new failure appeared, or the datasets differ.
 Trace store modules export any TraceStore as { store }, such as a PostgresTraceStore over the application's own pool.
+Database modules for "db status" and "db migrate" export { client }, and optionally { dialect, transaction, migrations, close }.
+"db status --check" exits 1 while a migration is pending or changed.
+"doctor" exits 1 when a check fails, or with --strict when one warns. Its module exports any of { database, client, redis, operations, ai, deployment, close }.
 "deploy" reads NEXUS_SERVER_URL and NEXUS_SERVER_TOKEN when --url and --token are not given.
-"migrate" moves 1.x root imports to their 2.0 subpaths and reports removed options; --check exits 1 while any remain.`);
+"migrate" moves 1.x root imports to their 2.0 subpaths and reports removed options; --check exits 1 while any remain.
+"graph lint" reads a compiled graph's shape and exits 1 on an error finding, or on a warning with --strict.`);
 }
 main().catch((error) => {
     const message = error instanceof Error ? error.message : String(error);

package/dist/core/lifecycle.js

@@ -1,5 +1,6 @@
 import { NexusRateLimitError } from '../ops/rate-limiter.js';
 import { generateRequestId } from '../utils/ids.js';
+import { linkSignals } from '../utils/signals.js';
 export const LIFECYCLE_STAGES = [
     'validate',
     'authorize',
@@ -43,14 +44,15 @@ export class OperationLifecycle {
         const startedAt = Date.now();
         const timeoutMs = options.timeoutMs ?? this.runtime.timeoutMs;
         const deadline = timeoutMs !== undefined && Number.isFinite(timeoutMs) && timeoutMs > 0 ? startedAt + timeoutMs : undefined;
+        const call = callSignal(options.signal, deadline === undefined ? undefined : deadline - startedAt);
         const context = {
             requestId: descriptor.requestId,
-            signal: callSignal(options.signal, deadline === undefined ? undefined : deadline - startedAt),
+            signal: call.signal,
             ...(deadline !== undefined ? { deadline } : {}),
             ...(options.traceContext ? { traceContext: options.traceContext } : {}),
             ...(options.idempotencyKey ? { idempotencyKey: options.idempotencyKey } : {}),
         };
-        const ticket = new Ticket(this.runtime, descriptor, context, startedAt);
+        const ticket = new Ticket(this.runtime, descriptor, context, startedAt, call.dispose);
         try {
             await this.runtime.metrics?.recordRequest(labelsOf(descriptor));
             await this.checkRateLimit(descriptor);
@@ -105,6 +107,7 @@ export class OperationLifecycle {
         const bucket = {
             model: descriptor.model ?? `${descriptor.family}:${descriptor.operation}`,
             userId: descriptor.userId,
+            tenantId: descriptor.tenantId,
         };
         if (rateLimit.store)
             await rateLimiter.checkAsync(bucket, rateLimit);
@@ -135,13 +138,15 @@ class Ticket {
     descriptor;
     context;
     startedAt;
+    release;
     reservation;
     finished = false;
-    constructor(runtime, descriptor, context, startedAt) {
+    constructor(runtime, descriptor, context, startedAt, release = () => undefined) {
         this.runtime = runtime;
         this.descriptor = descriptor;
         this.context = context;
         this.startedAt = startedAt;
+        this.release = release;
     }
     async reserve(estimate) {
         const budget = this.runtime.config?.budget;
@@ -211,14 +216,14 @@ class Ticket {
         });
     }
     async finish(outcome) {
+        this.release();
         await runHook(() => this.runtime.config?.hooks?.onFinish?.(this.descriptor, outcome));
     }
 }
 function callSignal(signal, timeoutMs) {
     if (timeoutMs === undefined)
-        return signal ?? new AbortController().signal;
-    const timeout = AbortSignal.timeout(timeoutMs);
-    return signal ? AbortSignal.any([signal, timeout]) : timeout;
+        return { signal: signal ?? new AbortController().signal, dispose: () => undefined };
+    return linkSignals([signal, AbortSignal.timeout(timeoutMs)]);
 }
 function outcomeOf(error, signal) {
     if (error instanceof OperationDeniedError ||

package/dist/core/nexus.d.ts

@@ -248,9 +248,13 @@ export declare class NexusAI {
     /** Health of every provider seen so far, when health tracking is on. */
     getProviderHealth(): import("../ops/health.js").ProviderHealthSnapshot[];
     /**
-     * Calls each provider's health check and records the result.
+     * Calls each provider's health check and records the result. With `staleOnly`, only the providers
+     * whose health is `unknown` are checked: never called, or not since `health.observationTtlMs`. Run
+     * it on a schedule to keep an idle provider's health current.
      */
-    checkProviders(): Promise<Array<{
+    checkProviders(options?: {
+        staleOnly?: boolean;
+    }): Promise<Array<{
         providerName: string;
         ok: boolean;
         error?: string;
@@ -314,6 +318,12 @@ export declare class NexusAI {
     private attachTrace;
     private usesSemanticCache;
     private loadSemanticCache;
+    /**
+     * Where a request's cached response lives: its key, its namespace, and the scope a semantic match
+     * must share, which is always at least the request's tenant.
+     */
+    private cachePlan;
+    /** Looks a request up in the cache. A cache that fails is reported as an `error` outcome and treated as a miss. */
     private getCachedResponse;
     private setCachedResponse;
     private estimateRequestCost;