nexus-ai-pro 2.20.2 → 2.22.0

package/dist/cli/adapters.d.ts

@@ -1,10 +1,11 @@
 import { type ParsedArgs } from './args.js';
 /**
- * `nexus adapters verify <module>[#export]`, `nexus adapters page <records...>`, and
- * `nexus adapters recheck <records...>`.
+ * `nexus adapters verify <module>[#export]`, `nexus adapters page <records...>`,
+ * `nexus adapters recheck <records...>`, and `nexus adapters gather --out <dir>`.
  *
  * `verify` runs an adapter's contract suite and benchmark from its own repository and writes its
  * compatibility record; `page` lists records on one page; `recheck` verifies each listed adapter again
- * against the installed release and fails when one that passed no longer does.
+ * against the installed release and fails when one that passed no longer does; `gather` fetches the
+ * records adapters' own CI publishes, checked and never run, into a directory a page lists.
  */
 export declare function runAdaptersCommand(subcommand: string | undefined, args: ParsedArgs): Promise<void>;

package/dist/cli/adapters.js

@@ -1,8 +1,9 @@
 import { existsSync } from 'node:fs';
-import { mkdir, readdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { mkdir, readdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
 import { createRequire } from 'node:module';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
+import { ADAPTER_KEYWORD, gatherRecords } from '../adapter-kit/gather.js';
 import { compareRecords, compatibilityPage, readCompatibilityRecord, recordStatus, } from '../adapter-kit/record.js';
 import { CliUsageError, flagBool, isRecord, printTable, stringFlag, writeJson } from './args.js';
 export async function runAdaptersCommand(subcommand, args) {
@@ -12,7 +13,75 @@ export async function runAdaptersCommand(subcommand, args) {
         return page(args);
     if (subcommand === 'recheck')
         return recheck(args);
-    throw new CliUsageError(`Unknown adapters command "${subcommand ?? ''}". Use verify, page, or recheck.`);
+    if (subcommand === 'gather')
+        return gather(args);
+    throw new CliUsageError(`Unknown adapters command "${subcommand ?? ''}". Use verify, page, recheck, or gather.`);
+}
+async function gather(args) {
+    const out = stringFlag(args.flags, 'out');
+    if (!out)
+        throw new CliUsageError('nexus adapters gather needs --out <dir>: where the gathered records are kept.');
+    const sourcesFile = stringFlag(args.flags, 'sources');
+    const sources = sourcesFile ? sourcesFrom(await readFile(sourcesFile, 'utf8'), sourcesFile) : [];
+    const previous = [];
+    for (const name of existsSync(out) ? (await readdir(out)).sort() : []) {
+        if (!name.endsWith('.json'))
+            continue;
+        try {
+            previous.push({ file: name, record: readCompatibilityRecord(await readFile(path.join(out, name), 'utf8')) });
+        }
+        catch {
+        }
+    }
+    const registry = stringFlag(args.flags, 'registry');
+    const report = await gatherRecords({
+        keyword: args.flags.keyword === false ? false : (stringFlag(args.flags, 'keyword') ?? ADAPTER_KEYWORD),
+        sources,
+        previous: previous.map((entry) => entry.record),
+        ...(registry ? { registry } : {}),
+    });
+    await mkdir(out, { recursive: true });
+    const written = new Set();
+    for (const source of report.sources) {
+        if (!source.record)
+            continue;
+        const file = `${slug(source.package)}.json`;
+        written.add(file);
+        await writeFile(path.join(out, file), `${JSON.stringify(source.record, null, 2)}
+`);
+    }
+    for (const { file } of previous)
+        if (!written.has(file))
+            await rm(path.join(out, file));
+    if (flagBool(args.flags, 'json')) {
+        writeJson(report);
+        return;
+    }
+    printTable(report.sources.map((source) => ({
+        package: source.package,
+        outcome: source.outcome,
+        state: source.record ? recordStatus(source.record).state : '',
+        detail: source.detail ?? '',
+    })), ['package', 'outcome', 'state', 'detail']);
+    console.log('');
+    console.log(`${report.records.length} records listed in ${out}, of ${report.sources.length} packages.`);
+}
+function sourcesFrom(text, file) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (error) {
+        throw new CliUsageError(`${file} is not JSON: ${error.message}`);
+    }
+    if (!Array.isArray(parsed))
+        throw new CliUsageError(`${file} must list sources: [{ "package": ..., "url": ... }]`);
+    return parsed.map((item, index) => {
+        if (!isRecord(item) || typeof item.package !== 'string' || typeof item.url !== 'string') {
+            throw new CliUsageError(`${file}, source ${index + 1}: each source names its "package" and its record's "url"`);
+        }
+        return { package: item.package, url: item.url };
+    });
 }
 async function verify(args) {
     const [target] = args.positionals;

package/dist/cli/doctor.js

@@ -28,6 +28,9 @@ export async function runDoctorCommand({ flags }) {
     const maxQueueAgeMs = numberFlag(flags, 'max-queue-age-ms');
     if (maxQueueAgeMs !== undefined)
         options.maxQueueAgeMs = maxQueueAgeMs;
+    const upgrade = stringFlag(flags, 'upgrade');
+    if (upgrade !== undefined)
+        options.upgrade = upgrade;
     let report;
     try {
         report = await diagnose(options);

package/dist/cli.js

@@ -437,7 +437,7 @@ Usage:
   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 doctor [--module doctor.mjs] [--replicas n] [--max-queue-age-ms n] [--upgrade 3.0] [--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]
@@ -446,6 +446,7 @@ Usage:
   nexus adapters verify <module>[#export] [--out record.json] [--package name@version] [--repository url] [--verify spec] [--json]
   nexus adapters page <records|dir...> [--out page.md] [--html] [--title t] [--intro text] [--expect page.md] [--check] [--strict]
   nexus adapters recheck <records|dir...> [--out dir] [--update] [--json]
+  nexus adapters gather --out <dir> [--keyword nexus-ai-pro-adapter | --no-keyword] [--sources sources.json] [--registry url] [--json]
   nexus policy check <policy.json> [--base <policy.json>|git:<ref>] [--accept path,path] [--json]
   nexus optimize [request.json|prompt.txt] [--model gpt-5-mini] [--max-input-tokens 4000] [--densify] [--json]
 
@@ -461,6 +462,7 @@ Database modules for "db status" and "db migrate" export { client }, and optiona
 "graph lint" reads a compiled graph's shape and exits 1 on an error finding, or on a warning with --strict.
 "adapters verify" exits 1 when the adapter does not pass; its module exports { adapter, config, options, record, close }.
 "adapters recheck" verifies each listed adapter again and exits 1 when one that passed no longer does; "adapters page --check" exits 1 on a failing or incompatible record, --strict on a stale one too.
+"adapters gather" fetches the records adapters' own CI publishes, found on npm by keyword or listed in --sources, keeps only those sealed and naming their package, and never runs them.
 "policy check" exits 1 when the policy is not valid, or, against --base, when a change that widens what a tenant may reach is not acknowledged.`);
 }
 main().catch((error) => {

package/dist/core/config-builder.d.ts

@@ -95,3 +95,4 @@ export declare function createNexusConfig(seed?: Partial<NexusAIConfig>): NexusC
  * Identity helper for users who prefer object literals but want type inference and validation in editors.
  */
 export declare function defineNexusConfig(config: NexusAIConfig): NexusAIConfig;
+export { DEFAULT_CHANGES, type DefaultChange, type NexusDefaults, nexusDefaults, useDefaults } from './defaults.js';

package/dist/core/config-builder.js

@@ -148,3 +148,4 @@ export function createNexusConfig(seed = {}) {
 export function defineNexusConfig(config) {
     return config;
 }
+export { DEFAULT_CHANGES, nexusDefaults, useDefaults } from './defaults.js';

package/dist/core/defaults.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Which release's defaults apply where an option is left out: 2.x's, or a preview of 3.0's. 3.0 turns on
+ * three settings that 2.x keeps opt-in, because turning them on changes what an upgrade does; the
+ * preview turns on all three at once, so an application can run as 3.0 will before it upgrades. An
+ * option set explicitly always wins, under either.
+ */
+/** A release whose defaults apply: `2.x`, the default, or `3.0`, a preview of the next major release's. */
+export type NexusDefaults = '2.x' | '3.0';
+/** One default that 3.0 changes: what it is, what 2.x does, what 3.0 does, and what to do first. */
+export interface DefaultChange {
+    /** The setting, as its option is named. */
+    setting: string;
+    /** Where it is set. */
+    module: string;
+    /** What 2.x does when the option is left out. */
+    today: string;
+    /** What 3.0, and the preview, does when it is left out. */
+    next: string;
+    /** What to do before turning it on, if anything. */
+    before: string;
+}
+/** The defaults 3.0 changes, each turned on by the preview. */
+export declare const DEFAULT_CHANGES: readonly DefaultChange[];
+/**
+ * Chooses which release's defaults apply to everything created after it: `3.0` previews the next
+ * major release's, `2.x` returns to today's. Call it before creating a tracer, an operation store, or
+ * a deployment: each reads the defaults when it is created. Overrides `NEXUS_DEFAULTS`.
+ */
+export declare function useDefaults(release: NexusDefaults): void;
+/**
+ * The defaults in effect: as `useDefaults()` chose, else the `NEXUS_DEFAULTS` environment variable,
+ * `2.x` or `3.0`, else `2.x`. Throws for any other value of the variable, rather than ignore a typo.
+ */
+export declare function nexusDefaults(): NexusDefaults;

package/dist/core/defaults.js

@@ -0,0 +1,39 @@
+export const DEFAULT_CHANGES = [
+    {
+        setting: 'Tracer incremental',
+        module: 'nexus-ai-pro/tracing',
+        today: 'false: a trace is written when its root run finishes',
+        next: 'true on a durable trace store: each run is written as it starts and again as it ends, so a run in a process that dies is not lost',
+        before: 'Nothing; close what a process that died left open with closeAbandonedRuns().',
+    },
+    {
+        setting: 'RedisOperationStore index',
+        module: 'nexus-ai-pro/operations',
+        today: 'false: finding queued work reads every record',
+        next: 'true where the client has zadd, zrem, and zrangebyscore: queued and leased work is kept in sorted sets',
+        before: 'Run 2.2 or later on every worker sharing the prefix, and call reindex() once.',
+    },
+    {
+        setting: 'Deployments bucketStrategy',
+        module: 'nexus-ai-pro/server',
+        today: 'fnv1a-v1 for a deployment first recorded',
+        next: 'hash-v2 for a deployment first recorded, which spreads sequential thread ids evenly; a recorded deployment keeps its own',
+        before: 'Nothing; a deployment already recorded keeps the strategy it records, and bucketing() changes one.',
+    },
+];
+let chosen;
+export function useDefaults(release) {
+    chosen = checked(release, 'useDefaults()');
+}
+export function nexusDefaults() {
+    if (chosen)
+        return chosen;
+    const variable = globalThis.process?.env
+        ?.NEXUS_DEFAULTS;
+    return variable === undefined || variable === '' ? '2.x' : checked(variable, 'NEXUS_DEFAULTS');
+}
+function checked(release, where) {
+    if (release === '2.x' || release === '3.0')
+        return release;
+    throw new Error(`${where} takes 2.x or 3.0, not ${JSON.stringify(release)}`);
+}

package/dist/core/secure-stream.js

@@ -50,6 +50,7 @@ export function protectStreamOutput(stream, security, requestSignal) {
             const protectedOutput = security.protectOutput(toPseudoResponse(bufferedText, bufferedToolCalls, sourceMeta));
             security.assertOutputSafe(protectedOutput);
             const safeText = protectedOutput.value.content;
+            const textChanged = safeText !== bufferedText;
             const safeToolCalls = protectedOutput.value.toolCalls || [];
             const applied = protectedOutput.value.meta.guardrailsApplied;
             const textIndexes = chunks
@@ -69,9 +70,11 @@ export function protectStreamOutput(stream, security, requestSignal) {
                     safeOffset += length;
                     if (!content)
                         continue;
+                    const { logprobs, ...text } = chunk;
                     yield {
-                        ...chunk,
+                        ...text,
                         content,
+                        ...(logprobs && !textChanged ? { logprobs } : {}),
                         meta: withGuardrails(chunk.meta, applied),
                     };
                     continue;

package/dist/decisions/completion.d.ts

@@ -1,8 +1,3 @@
-/**
- * Decisions from any completion model: each question asked on its own, answered with a one-token code,
- * and its probabilities read from the code token's log probabilities, or counted over samples where
- * the model reports none.
- */
 import type { CompletionRequest } from '../types/messages.js';
 import type { NexusResponse } from '../types/response.js';
 import { type DecisionProvider } from './core.js';
@@ -25,8 +20,14 @@ export interface CompletionDecisionsOptions {
      * a model that reports none or refuses to, which it then asks by sampling from the start.
      */
     method?: CompletionDecisionMethod;
-    /** Calls per question, when sampling. Defaults to 8. */
+    /** Calls per question, when sampling, and per box. Defaults to 8. */
     samples?: number;
+    /**
+     * Whether the model reads pictures, so a decision about the pictures a state holds, or a box, may
+     * be asked of it. Defaults to `true`; set `false` for a text-only model, which such a decision then
+     * passes over to a fallback.
+     */
+    images?: boolean;
     /** The temperature samples are drawn at. Defaults to 1. */
     temperature?: number;
     /** Questions asked at once. Defaults to 8. */
@@ -41,7 +42,9 @@ export interface CompletionDecisionsOptions {
  * Its probabilities are read from the log probabilities of that token's alternatives where the model
  * reports them, the way TypeSafe AI's Jev reads its own; elsewhere the question is asked `samples`
  * times, and each answer counted. Sampled probabilities come in steps of one sample, and cost as many
- * calls.
+ * calls. The pictures a state holds are shown to the model after the state, each labelled by its
+ * path; a box is asked `samples` times, and is the median of each edge, its confidence how far the
+ * samples overlap it.
  */
 export declare function completionDecisions(client: DecisionCompletionClient, options: CompletionDecisionsOptions): DecisionProvider & {
     readonly sampledModels: ReadonlySet<string>;

package/dist/decisions/completion.js

@@ -1,14 +1,17 @@
-import { DecisionError, } from './core.js';
+import { boxOverlap, DecisionError, } from './core.js';
+import { replacePictures, statePictures } from './pictures.js';
 const LOGPROB_OPTIONS = 20;
 export function completionDecisions(client, options) {
     const method = options.method ?? 'auto';
+    const images = options.images !== false;
     const sampled = new Set();
     const info = {
         name: options.name ?? options.model,
         capabilities: {
-            types: ['yes-no', 'choice', 'score'],
+            types: images ? ['yes-no', 'choice', 'score', 'box'] : ['yes-no', 'choice', 'score'],
             maxOptions: 255,
             maxLevels: 10,
+            images,
             defaultModel: options.model,
         },
         chargedByItsCalls: true,
@@ -21,7 +24,9 @@ export function completionDecisions(client, options) {
             messages: [
                 {
                     role: 'system',
-                    content: 'You answer one question about a state with exactly one of the codes given, and nothing else.',
+                    content: question.type === 'box'
+                        ? 'You answer where something is in a picture with exactly four numbers, and nothing else.'
+                        : 'You answer one question about a state with exactly one of the codes given, and nothing else.',
                 },
                 { role: 'user', content: prompt },
             ],
@@ -29,6 +34,8 @@ export function completionDecisions(client, options) {
             ...(context.tenantId !== undefined ? { tenantId: context.tenantId } : {}),
             ...extra,
         });
+        if (question.type === 'box')
+            return askBox(request, model, usage);
         const readable = codes.length <= LOGPROB_OPTIONS && codes.every((code) => code.length === 1);
         if (method !== 'sampling' && readable && !sampled.has(model)) {
             let response;
@@ -64,6 +71,28 @@ export function completionDecisions(client, options) {
         }
         return distributionOf(question, codes, weights);
     };
+    const askBox = async (request, model, usage) => {
+        if (method === 'logprobs') {
+            throw new DecisionError('A box is read from several samples of the answer, not from log probabilities', 'DECISION_UNSUPPORTED');
+        }
+        const count = Math.max(1, Math.floor(options.samples ?? 8));
+        const readings = await Promise.all(Array.from({ length: count }, () => client.complete(request({ temperature: options.temperature ?? 1, maxTokens: 32 })).then((response) => {
+            usage.add(response);
+            return boxIn(response.content);
+        })));
+        const boxes = readings.filter((box) => box !== undefined);
+        if (boxes.length === 0) {
+            throw new DecisionError(`"${model}" answered none of ${count} samples with a box`, 'DECISION_FAILED');
+        }
+        const box = {
+            top: median(boxes.map((item) => item.top)),
+            bottom: median(boxes.map((item) => item.bottom)),
+            left: median(boxes.map((item) => item.left)),
+            right: median(boxes.map((item) => item.right)),
+        };
+        const agreement = boxes.reduce((sum, item) => sum + boxOverlap(item, box), 0) / count;
+        return { type: 'box', box, confidence: agreement };
+    };
     return {
         info,
         sampledModels: sampled,
@@ -112,6 +141,8 @@ class Totals {
     }
 }
 function codesOf(question) {
+    if (question.type === 'box')
+        return [];
     if (question.type === 'yes-no')
         return ['Y', 'N'];
     if (question.type === 'score')
@@ -121,10 +152,37 @@ function codesOf(question) {
         : question.options.map((_, index) => String(index + 1));
 }
 function promptOf(state, question, codes, instructions) {
-    const text = typeof state === 'string' ? state : JSON.stringify(state, null, 2);
-    const lines = [`State:\n${text}`, ''];
+    const pictures = typeof state === 'string' ? [] : statePictures(state);
+    const shown = pictures.length ? replacePictures(state, (picture) => `[picture \`${picture.path}\`]`) : state;
+    const text = typeof shown === 'string' ? shown : JSON.stringify(shown, null, 2);
+    const asked = questionLines(question, codes, instructions).join('\n');
+    if (pictures.length === 0)
+        return `State:\n${text}\n\n${asked}`;
+    return [
+        { type: 'text', text: `State:\n${text}\n\nThe pictures it holds, by path:` },
+        ...pictures.flatMap((picture) => [
+            { type: 'text', text: `\`${picture.path}\`:` },
+            imagePart(picture.part),
+        ]),
+        { type: 'text', text: asked },
+    ];
+}
+function imagePart(part) {
+    if (part.type === 'image')
+        return part;
+    if (part.type === 'asset')
+        return { type: 'image', source: { asset: part.asset } };
+    return part;
+}
+function questionLines(question, codes, instructions) {
+    const lines = [];
     if (instructions)
         lines.push(instructions, '');
+    if (question.type === 'box') {
+        lines.push(`Find: ${question.question}`);
+        lines.push('', "Answer with four numbers from 0 to 1, separated by spaces: the top, bottom, left, and right edges of a box around it, each a fraction of the picture's height or width from its top-left corner.");
+        return lines;
+    }
     if (question.type === 'yes-no') {
         lines.push(`Question: ${question.question ?? 'Is the statement true of the state?'}`);
         lines.push(`Y: yes${question.criteria?.yes ? `, ${question.criteria.yes}` : ''}`);
@@ -143,16 +201,30 @@ function promptOf(state, question, codes, instructions) {
         });
     }
     lines.push('', `Answer with one code: ${codes.join(', ')}.`);
-    return lines.join('\n');
+    return lines;
+}
+function boxIn(content) {
+    const numbers = (content.match(/-?\d*\.?\d+/g) ?? []).slice(0, 4).map(Number);
+    if (numbers.length < 4 || numbers.some((value) => !(value >= 0 && value <= 1)))
+        return undefined;
+    const [top, bottom, left, right] = numbers;
+    return top <= bottom && left <= right ? { top, bottom, left, right } : undefined;
+}
+function median(values) {
+    const sorted = [...values].sort((a, b) => a - b);
+    const middle = Math.floor(sorted.length / 2);
+    return sorted.length % 2
+        ? sorted[middle]
+        : (sorted[middle - 1] + sorted[middle]) / 2;
 }
 function codeOf(token) {
     return token.replace(/^[\s"'`*(]+|[\s"'`*).:,]+$/g, '').toUpperCase();
 }
 function weightsFrom(logprobs, codes) {
     const first = logprobs?.find((item) => item.token.trim() !== '');
-    if (!first)
+    if (!first?.top?.length)
         return undefined;
-    const candidates = first.top?.length ? first.top : [{ token: first.token, logprob: first.logprob }];
+    const candidates = first.top;
     const weights = codes.map(() => 0);
     let found = false;
     for (const candidate of candidates) {
@@ -184,6 +256,8 @@ function distributionOf(question, codes, weights) {
         return { type: 'yes-no', yes: share(0) };
     if (question.type === 'score')
         return { type: 'score', probabilities: codes.map((_, index) => share(index)) };
+    if (question.type === 'box')
+        throw new DecisionError('A box has no codes to weigh', 'DECISION_INVALID');
     return {
         type: 'choice',
         probabilities: Object.fromEntries(question.options.map((option, index) => [option.name, share(index)])),