nexus-ai-pro 2.0.0 → 2.2.0

package/dist-cjs/cli/db.js

@@ -1,31 +1,211 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.runDbCommand = runDbCommand;
 const index_js_1 = require("../postgres/index.js");
 const args_js_1 = require("./args.js");
-const ADAPTERS = [
-    'operations',
-    'store',
-    'traces',
-    'evaluation',
-    'circuits',
-    'prompts',
-    'vectors',
-];
-async function runDbCommand(subcommand, { flags }) {
-    if (subcommand !== 'sql')
-        throw new args_js_1.CliUsageError(`Unknown db command "${subcommand ?? ''}". Use sql.`);
-    const adapters = (0, args_js_1.listFlag)(flags, 'adapters');
-    const unknown = adapters?.filter((adapter) => !ADAPTERS.includes(adapter));
-    if (unknown?.length) {
-        throw new args_js_1.CliUsageError(`Unknown adapter ${unknown.join(', ')}. Choose from ${ADAPTERS.join(', ')}.`);
-    }
+const SQLITE_ADAPTERS = ['operations', 'store', 'vectors'];
+async function runDbCommand(subcommand, args) {
+    if (subcommand === 'sql')
+        return printSql(args);
+    if (subcommand === 'status' || subcommand === 'migrate')
+        return withDatabase(subcommand, args);
+    throw new args_js_1.CliUsageError(`Unknown db command "${subcommand ?? ''}". Use sql, status, or migrate.`);
+}
+function printSql({ flags }) {
+    const adapters = postgresAdapters(flags);
     const vectorDimensions = (0, args_js_1.numberFlag)(flags, 'vector-dimensions');
-    if (adapters?.includes('vectors') && vectorDimensions === undefined) {
-        throw new args_js_1.CliUsageError('The vectors adapter needs --vector-dimensions.');
-    }
     process.stdout.write((0, index_js_1.postgresMigration)({
         ...(adapters ? { adapters } : {}),
         ...(vectorDimensions === undefined ? {} : { vectorDimensions }),
+        ...((0, args_js_1.flagBool)(flags, 'record') ? { record: true } : {}),
     }));
 }
+function postgresAdapters(flags) {
+    const adapters = (0, args_js_1.listFlag)(flags, 'adapters');
+    const unknown = adapters?.filter((adapter) => !index_js_1.POSTGRES_ADAPTERS.includes(adapter));
+    if (unknown?.length) {
+        throw new args_js_1.CliUsageError(`Unknown adapter ${unknown.join(', ')}. Choose from ${index_js_1.POSTGRES_ADAPTERS.join(', ')}.`);
+    }
+    if (adapters?.includes('vectors') && (0, args_js_1.numberFlag)(flags, 'vector-dimensions') === undefined) {
+        throw new args_js_1.CliUsageError('The vectors adapter needs --vector-dimensions.');
+    }
+    return adapters;
+}
+async function withDatabase(command, { flags }) {
+    const location = (0, args_js_1.stringFlag)(flags, 'client');
+    if (!location)
+        throw new args_js_1.CliUsageError(`nexus db ${command} needs --client <db.mjs>, a module exporting \`client\`.`);
+    const database = await openDatabase(location, (0, args_js_1.stringFlag)(flags, 'dialect'));
+    try {
+        const migrations = database.migrations ?? (await bundledMigrations(database.dialect, flags));
+        const table = (0, args_js_1.stringFlag)(flags, 'table');
+        if (command === 'status') {
+            const status = await statusOf(database, migrations, table);
+            if ((0, args_js_1.flagBool)(flags, 'json'))
+                (0, args_js_1.writeJson)(status);
+            else
+                printStatus(status);
+            if ((0, args_js_1.flagBool)(flags, 'check') && !status.current)
+                process.exitCode = 1;
+            return;
+        }
+        const result = await migrate(database, migrations, { dryRun: (0, args_js_1.flagBool)(flags, 'dry-run'), table });
+        if ((0, args_js_1.flagBool)(flags, 'json'))
+            (0, args_js_1.writeJson)(result);
+        else
+            printResult(result);
+    }
+    finally {
+        await database.close?.();
+    }
+}
+async function openDatabase(location, dialectFlag) {
+    const loaded = await (0, args_js_1.loadModule)(location);
+    const client = loaded.client ?? loaded.default;
+    if (!client || typeof client !== 'object') {
+        throw new args_js_1.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 args_js_1.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 = (0, args_js_1.numberFlag)(flags, 'vector-dimensions');
+        return (0, index_js_1.postgresMigrations)({
+            ...(adapters ? { adapters } : {}),
+            ...(vectorDimensions === undefined ? {} : { vectorDimensions }),
+        });
+    }
+    const adapters = (0, args_js_1.listFlag)(flags, 'adapters');
+    const unknown = adapters?.filter((adapter) => !SQLITE_ADAPTERS.includes(adapter));
+    if (unknown?.length) {
+        throw new args_js_1.CliUsageError(`Unknown SQLite adapter ${unknown.join(', ')}. Choose from ${SQLITE_ADAPTERS.join(', ')}.`);
+    }
+    const { sqliteMigrations } = await Promise.resolve().then(() => __importStar(require('../sqlite/index.js')));
+    return sqliteMigrations(adapters ? { adapters } : {});
+}
+async function statusOf(database, migrations, table) {
+    const options = table ? { table } : {};
+    if (database.dialect === 'postgres') {
+        const { postgresMigrationStatus } = await Promise.resolve().then(() => __importStar(require('../postgres/migrations.js')));
+        return postgresMigrationStatus(database.client, migrations, options);
+    }
+    const { sqliteMigrationStatus } = await Promise.resolve().then(() => __importStar(require('../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 Promise.resolve().then(() => __importStar(require('../postgres/migrations.js')));
+        return applyPostgresMigrations(database.client, migrations, {
+            ...common,
+            ...(database.transaction ? { transaction: database.transaction } : {}),
+        });
+    }
+    const { applySqliteMigrations } = await Promise.resolve().then(() => __importStar(require('../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;
+    }
+    (0, args_js_1.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-cjs/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-cjs/cli/doctor.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runDoctorCommand = runDoctorCommand;
+const index_js_1 = require("../doctor/index.js");
+const args_js_1 = require("./args.js");
+const LABELS = { ok: 'ok  ', warn: 'warn', fail: 'FAIL', skip: 'skip' };
+async function runDoctorCommand({ flags }) {
+    const location = (0, args_js_1.stringFlag)(flags, 'module');
+    const loaded = location ? await (0, args_js_1.loadModule)(location) : {};
+    const options = {};
+    const source = (0, args_js_1.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 ((0, args_js_1.isRecord)(loaded.deployment))
+        options.deployment = loaded.deployment;
+    const replicas = (0, args_js_1.numberFlag)(flags, 'replicas');
+    if (replicas !== undefined)
+        options.deployment = { ...options.deployment, replicas };
+    const maxQueueAgeMs = (0, args_js_1.numberFlag)(flags, 'max-queue-age-ms');
+    if (maxQueueAgeMs !== undefined)
+        options.maxQueueAgeMs = maxQueueAgeMs;
+    let report;
+    try {
+        report = await (0, index_js_1.diagnose)(options);
+    }
+    finally {
+        if (typeof loaded.close === 'function')
+            await loaded.close();
+    }
+    if ((0, args_js_1.flagBool)(flags, 'json'))
+        (0, args_js_1.writeJson)(report);
+    else
+        print(report);
+    if (!report.ok || ((0, args_js_1.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-cjs/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-cjs/cli/graph.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runGraphCommand = runGraphCommand;
+const lint_js_1 = require("../graph/lint.js");
+const args_js_1 = require("./args.js");
+async function runGraphCommand(subcommand, args) {
+    if (subcommand !== 'lint') {
+        throw new args_js_1.CliUsageError(`Unknown graph command "${subcommand ?? ''}". Use lint.`);
+    }
+    const [target] = args.positionals;
+    if (!target)
+        throw new args_js_1.CliUsageError('nexus graph lint needs a module: nexus graph lint ./graph.mjs[#exportName].');
+    const [file, exportName] = target.split('#');
+    const loaded = await (0, args_js_1.loadModule)(file);
+    const graph = (exportName ? loaded[exportName] : (loaded.graph ?? loaded.default ?? loaded));
+    if (!isLintable(graph)) {
+        throw new args_js_1.CliUsageError(`${target} must export a compiled graph, or a graph description, ${exportName ? `as "${exportName}"` : 'as `graph` or its default'}.`);
+    }
+    const findings = (0, lint_js_1.lintGraph)(graph, {
+        deployed: (0, args_js_1.flagBool)(args.flags, 'deployed'),
+        ignore: (0, args_js_1.listFlag)(args.flags, 'ignore'),
+    });
+    const failing = findings.filter((finding) => finding.severity === 'error' || ((0, args_js_1.flagBool)(args.flags, 'strict') && finding.severity === 'warning'));
+    if ((0, args_js_1.flagBool)(args.flags, 'json')) {
+        (0, args_js_1.writeJson)({ findings, failed: failing.length > 0 });
+    }
+    else if (findings.length === 0) {
+        console.log('No findings.');
+    }
+    else {
+        (0, args_js_1.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 (!(0, args_js_1.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-cjs/core/lifecycle.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.OperationLifecycle = exports.BudgetExceededError = exports.OperationDeniedError = exports.LIFECYCLE_STAGES = void 0;
 const rate_limiter_js_1 = require("../ops/rate-limiter.js");
 const ids_js_1 = require("../utils/ids.js");
+const signals_js_1 = require("../utils/signals.js");
 exports.LIFECYCLE_STAGES = [
     'validate',
     'authorize',
@@ -48,14 +49,15 @@ 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);
@@ -110,6 +112,7 @@ 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);
@@ -141,13 +144,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;
@@ -217,14 +222,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 (0, signals_js_1.linkSignals)([signal, AbortSignal.timeout(timeoutMs)]);
 }
 function outcomeOf(error, signal) {
     if (error instanceof OperationDeniedError ||

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

package/dist-cjs/core/nexus.js

@@ -190,13 +190,26 @@ class NexusAI {
             }
             await this.applyBudgets(context, ticket);
             const responseFormat = context.request.responseFormat || this.config.responseFormat;
-            const cacheKey = this.isCacheEnabled() ? (0, memory_cache_js_1.createCacheKey)({ request: context.request, responseFormat }) : undefined;
-            if (cacheKey) {
-                const cached = await this.pipeline.trace(context, 'cacheLookup', () => this.getCachedResponse(cacheKey, context.request));
+            const cachePlan = this.isCacheEnabled() ? this.cachePlan(context.request, responseFormat) : undefined;
+            let cacheOutcome;
+            if (cachePlan && !cachePlan.read) {
+                cacheOutcome = {
+                    outcome: 'bypass',
+                    reason: context.request.responseCache === 'refresh'
+                        ? 'the request asked for a fresh answer'
+                        : 'the request skipped the cache',
+                    ...(cachePlan.namespace ? { namespace: cachePlan.namespace } : {}),
+                };
+            }
+            if (cachePlan?.read) {
+                const plan = cachePlan;
+                const lookup = await this.pipeline.trace(context, 'cacheLookup', () => this.getCachedResponse(plan, context.request));
+                cacheOutcome = lookup.outcome;
+                const cached = lookup.response;
                 if (cached) {
                     let cachedResponse = this.attachTrace({
                         ...cached,
-                        meta: { ...cached.meta, requestId: ticket.descriptor.requestId, cacheHit: true },
+                        meta: { ...cached.meta, requestId: ticket.descriptor.requestId, cacheHit: true, cache: lookup.outcome },
                     }, this.pipeline.finish(context));
                     if (this.isSecurityEnabled()) {
                         const outputResult = this.security.protectOutput(cachedResponse);
@@ -258,12 +271,24 @@ class NexusAI {
                 });
                 context.response = formattedResponse;
             }
-            if (cacheKey) {
+            if (cachePlan?.write) {
                 const responseToCache = context.response;
                 if (!responseToCache) {
                     throw new Error('Cannot cache an empty response.');
                 }
-                await this.pipeline.trace(context, 'cacheWrite', () => this.setCachedResponse(cacheKey, context.request, responseToCache));
+                const plan = cachePlan;
+                try {
+                    await this.pipeline.trace(context, 'cacheWrite', () => this.setCachedResponse(plan, context.request, responseToCache));
+                }
+                catch (error) {
+                    cacheOutcome = {
+                        ...(cacheOutcome ?? { outcome: 'miss', reason: 'no entry for this request' }),
+                        writeError: error instanceof Error ? error.message : String(error),
+                    };
+                }
+            }
+            if (cacheOutcome && context.response) {
+                context.response = { ...context.response, meta: { ...context.response.meta, cache: cacheOutcome } };
             }
             context = await this.pipeline.runHook('beforeReturn', context);
             let responseToReturn = context.response;
@@ -583,9 +608,11 @@ class NexusAI {
     getProviderHealth() {
         return this.health.snapshot();
     }
-    async checkProviders() {
+    async checkProviders(options = {}) {
         const results = [];
         for (const [providerName, provider] of this.providers) {
+            if (options.staleOnly && !this.health.isUnknown(providerName))
+                continue;
             const started = Date.now();
             try {
                 const ok = await provider.healthCheck();
@@ -828,35 +855,86 @@ class NexusAI {
         });
         return this.semanticCacheLoading;
     }
-    async getCachedResponse(cacheKey, request) {
-        if (!this.config.cache?.enabled)
-            return undefined;
-        if (this.usesSemanticCache()) {
-            const semantic = await (await this.loadSemanticCache()).get(request);
-            if (semantic)
-                return semantic;
+    cachePlan(request, responseFormat) {
+        const configured = this.config.cache?.namespace;
+        const chosen = typeof configured === 'function' ? configured(request) : configured;
+        const namespace = chosen ? namespaceKey({ ...chosen, tenant: chosen.tenant ?? request.tenantId }) : undefined;
+        const base = (0, memory_cache_js_1.createCacheKey)({ request: { ...request, responseCache: undefined }, responseFormat });
+        return {
+            key: namespace ? `${namespace}\u0000${base}` : base,
+            ...(namespace ? { namespace } : {}),
+            scope: namespace ?? namespaceKey({ tenant: request.tenantId }),
+            read: request.responseCache === undefined,
+            write: request.responseCache !== 'bypass',
+        };
+    }
+    async getCachedResponse(plan, request) {
+        const namespace = plan.namespace ? { namespace: plan.namespace } : {};
+        const cache = this.config.cache ?? {};
+        let layer = this.usesSemanticCache() ? 'semantic' : 'exact';
+        try {
+            if (this.usesSemanticCache()) {
+                const semantic = await (await this.loadSemanticCache()).get(request, plan.scope);
+                if (semantic) {
+                    return {
+                        response: semantic,
+                        outcome: { outcome: 'hit', layer: 'semantic', reason: 'a similar request was answered', ...namespace },
+                    };
+                }
+                if (cache.strategy === 'semantic') {
+                    return {
+                        outcome: {
+                            outcome: 'miss',
+                            layer: 'semantic',
+                            reason: 'no similar request above the threshold',
+                            ...namespace,
+                        },
+                    };
+                }
+            }
+            layer = 'exact';
+            if (cache.adapter) {
+                const value = (await cache.adapter.get(plan.key));
+                return value
+                    ? { response: value, outcome: { outcome: 'hit', layer, reason: 'this request was answered', ...namespace } }
+                    : { outcome: { outcome: 'miss', layer, reason: 'no entry for this request', ...namespace } };
+            }
+            const { value, stale } = this.cache.lookup(plan.key);
+            if (value) {
+                return {
+                    response: value,
+                    outcome: { outcome: 'hit', layer, reason: 'this request was answered', ...namespace },
+                };
+            }
+            return stale
+                ? { outcome: { outcome: 'stale', layer, reason: 'the entry for this request had expired', ...namespace } }
+                : { outcome: { outcome: 'miss', layer, reason: 'no entry for this request', ...namespace } };
         }
-        if (this.config.cache.strategy === 'semantic')
-            return undefined;
-        if (this.config.cache.adapter) {
-            return (await this.config.cache.adapter.get(cacheKey));
+        catch (error) {
+            return {
+                outcome: {
+                    outcome: 'error',
+                    layer,
+                    reason: error instanceof Error ? error.message : String(error),
+                    ...namespace,
+                },
+            };
         }
-        return this.cache.get(cacheKey);
     }
-    async setCachedResponse(cacheKey, request, response) {
+    async setCachedResponse(plan, request, response) {
         if (!this.config.cache?.enabled)
             return;
         const ttl = this.config.cache.ttlSeconds || 300;
         if (this.usesSemanticCache()) {
-            await (await this.loadSemanticCache()).set(cacheKey, request, response);
+            await (await this.loadSemanticCache()).set(plan.key, request, response, plan.scope);
         }
         if (this.config.cache.strategy === 'semantic')
             return;
         if (this.config.cache.adapter) {
-            await this.config.cache.adapter.set(cacheKey, response, ttl);
+            await this.config.cache.adapter.set(plan.key, response, ttl);
             return;
         }
-        this.cache.set(cacheKey, response, ttl);
+        this.cache.set(plan.key, response, ttl);
     }
     estimateRequestCost(request) {
         return (0, cost_js_1.estimateCost)({
@@ -891,3 +969,8 @@ function streamStopped() {
     error.name = 'AbortError';
     return error;
 }
+function namespaceKey(namespace) {
+    return [namespace.tenant, namespace.environment, namespace.modelRevision, namespace.contextVersion]
+        .map((part) => encodeURIComponent(part ?? ''))
+        .join('/');
+}