nexus-ai-pro 1.22.0 → 1.24.0

package/API_STABILITY.md

@@ -437,8 +437,9 @@ from the root.
   `ThreadRecord`, and `RunEvent` follow the 1.x rules. A minor release may add routes and fields.
 - Event ids are per run and strictly increasing, which is what `Last-Event-ID` depends on. A client
   that reconnects with an id never receives it again.
-- The server is not a security boundary on its own: authentication, authorization beyond tenancy and
-  scopes, and rate limiting are the application's, through the hooks.
+- The server is not a security boundary on its own: authentication, and authorization beyond tenancy
+  and scopes, are the application's, through the hooks. Per-tenant limits are opt-in, through
+  `tenants`.
 - Recovery repeats the step a run died in for graphs and workflows served by `graphAssistant()`, and
   the whole run for any other assistant, so the repeated part should be idempotent or the run left at a
   single attempt.
@@ -456,6 +457,32 @@ with nexus-ai-pro and declares the core versions it works with as a peer depende
 - The access rules are a guarantee: loopback binding by default, a token on every request, the token
   in a header for every change, and loopback hosts only unless others are allowed.
 
+## Deployment stage (1.24.0)
+
+Deployments (`nexus-ai-pro/server/deployments`), tenant limits (`nexus-ai-pro/server/tenancy`), and the
+server's worker queue are experimental in production readiness. Their contracts follow the 1.x rules.
+
+- `bucket()` is stable across 1.x, so a thread keeps its place in a traffic split through an upgrade.
+- The stored `DeploymentRecord` and `ReplicaReport` shapes may gain fields but not lose them, so
+  replicas on different minor releases share one store.
+- The metric names on `/metrics` and the fields of `/scaling` follow the 1.x rules; a minor release may
+  add metrics and fields. Autoscaler configurations that read them keep working.
+- `drain()` hands off only runs it could not finish; a hand-off never counts against the retry budget.
+- The files under `deploy/` are templates in the repository, not part of the package, and may change in
+  any release.
+
+## Team platform stage (1.23.0)
+
+The context hub (`nexus-ai-pro/context-hub`), insights (`nexus-ai-pro/insights`), and the studio's
+accounts are experimental in production readiness. Their contracts follow the 1.x rules.
+
+- A bundle's content version covers its name, description, prompts, instructions, tools, skills, and
+  config, and is stable across 1.x, so the same content is the same version in every release.
+- The export format is `nexus-context-bundle`, format version 1; a later release reads it.
+- A cached evaluation output is keyed by the fingerprint, the example's id and inputs, and the
+  repetition. The key's derivation is stable across 1.x, so a cache survives an upgrade.
+- The studio's roles keep their order and meaning; new actions are assigned to an existing role.
+
 ## Retrieval breadth stage (1.22.0)
 
 The loaders (`nexus-ai-pro/loaders/*`), the Redis, Pinecone, Weaviate, Chroma, and SQLite vector

package/CHANGELOG.md

@@ -4,6 +4,99 @@ Notable changes to this project are recorded here. The format follows [Keep a Ch
 
 ## [Unreleased]
 
+## [1.24.0] - 2026-09-30
+
+Deployment at scale, self-managed. Running assistants as a service without a hosted platform:
+revisions and canaries, a worker pool that scales on its queue, and limits per tenant.
+
+### Added
+
+- **Revisions and canaries** on `nexus-ai-pro/server/deployments`. `Deployments.assistant()` serves
+  several revisions of an assistant from one image; the traffic split is recorded in the server's
+  state store and changed with `canary()`, `split()`, `promote()`, and `rollback()`, each kept in a
+  history with who and why, and guarded by an expected version. New threads and stateless runs are
+  split by a stable hash, a thread keeps its revision while that revision takes traffic, and every
+  run records its revision, share, reason, and the deployment version.
+- **A canary guard**: `watchCanaries()` compares each canary with the live revision over the same
+  window, rolls it back when its error rate, latency, or cost regressed, and moves one that holds up
+  through its `steps` to promotion. A latency rise must be at least `minLatencyChangeMs`, 50 ms by
+  default, so noise on fast runs never rolls a canary back. `compareRuns()` on `nexus-ai-pro/insights`
+  is the comparison, lifted out of `detectRegressions()`.
+- **A worker queue** in the agent server: with `queue`, a replica runs at most `concurrency` runs and
+  leaves the rest queued for the next free worker; `claim: false` makes an API replica. Replicas take
+  over lapsed runs every `recoverEveryMs`. `drain()` answers `/health` with `503`, stops claiming, and
+  hands runs still going after its timeout to another worker without using a retry.
+- **Scaling signals**: `GET /scaling` as JSON and `GET /metrics` in Prometheus text — queued and running
+  runs across the deployment, their load, the oldest wait, lapsed leases, each replica's capacity, and
+  run counts and latency per revision. `metrics: { public: true }` serves them to in-cluster scrapers.
+- **Kubernetes and Helm**: `deploy/app` is one image run as an API, a worker, or both, configured from
+  the environment; `deploy/kubernetes` has the manifests with a KEDA `ScaledObject` and an HPA
+  alternative; `deploy/helm/agent-server` is the chart. The clean-install test runs the template against
+  the packed package.
+- **Tenant limits** on `nexus-ai-pro/server/tenancy`: `tenantLimits()` holds each tenant to its active
+  runs, its runs per window, and its spending per period, answered with `429` and `Retry-After`.
+  `MemoryTenantUsage`, and `RedisTenantUsage` with atomic scripts so replicas share one set of limits.
+  Assistants record spending with `context.recordCost()`; `GET /usage` reports it.
+- **Replica health**: with `deployments`, each replica heartbeats its runs, capacity, drain state, and
+  revisions, readable from `GET /replicas`.
+- **A deployments view** in the studio: traffic splits and history, each revision's runs, error rate,
+  and latency since the last change, replicas, the queue, and tenant usage, with canary, promote, and
+  rollback for admins.
+- **`nexus deploy`**: `status`, `canary`, `promote`, and `rollback` against a running server, for the
+  pipeline that rolls out an image.
+- Operation queues: `OperationRunner.enqueue()`, `claimQueued()`, and `release()`; `listQueued()` and
+  `stats()` on every operation store, and `operationStats()`.
+- Run records gain `revision`, `startedAt`, `finishedAt`, `durationMs`, `cost`, `worker`, and `attempt`.
+
+### Changed
+
+- `GET /health` is answered without authentication, so a load balancer's or Kubernetes' probe reaches
+  it.
+- A worker never takes over an operation whose lease another worker still holds.
+- `RedisStoreLikeClient` declares `set()` with its expiry and `del()` with one key, the shapes an
+  `ioredis` client satisfies as it is.
+- The last nine guides are rewritten for readability.
+- `nexus-ai-pro-studio` requires nexus-ai-pro 1.24 or newer.
+
+### Fixed
+
+- The deployment templates run. The Dockerfile started a file the build never produced, and the
+  example server ignored `REDIS_URL`, so its replicas shared nothing.
+
+## [1.23.0] - 2026-09-30
+
+The team engineering platform. The studio becomes something a team shares, and it starts finding
+problems on its own.
+
+### Added
+
+- **A shared studio.** Accounts through an authenticator — personal links, identity headers from a
+  signing-in proxy, or bearer tokens verified by your function, such as OIDC — with four roles
+  (viewer, reviewer, editor, admin), an audit log of every change and every refused attempt, comments
+  on runs, review items, proposals, threads, and bundles, per-person page tokens for changes, and
+  `Secure` cookies behind HTTPS. Local, token-only use stays the default. The CLI gains `--users` and
+  `--journal`, and a config module may export `options`.
+- **The context hub** on `nexus-ai-pro/context-hub`: prompts, instructions, tool sets, skills, and
+  settings versioned together as bundles, committed by content, labelled, promoted through evaluation
+  gates, diffed, rolled back, and exported with their prompts to move between projects. Bundles live in
+  any prompt store. The studio shows them.
+- **Insights** on `nexus-ai-pro/insights`: failing and slow runs clustered by error, trajectory, or
+  meaning; regressions between two time windows; and, opt-in, a proposed fix — a candidate prompt or
+  bundle version — evaluated against the dataset before it waits in the studio's inbox for a person
+  to promote, with an optional pull request through an injected client.
+- **Evaluation caching**: `evaluate()` reuses a target's outputs when the example and the target's
+  fingerprint are unchanged, so a comparison re-runs only what changed; evaluators always run again.
+  `MemoryEvaluationCache`, `FileEvaluationCache`, and `fingerprintOf()` on `nexus-ai-pro/evaluate`;
+  `evaluatePrompt()` fingerprints the prompt version itself.
+
+### Changed
+
+- The guides are rewritten for readability: each says what its feature is for before its options,
+  options and fields are in tables, and long sentences are split. Every export is still explained.
+- `nexus-ai-pro-studio` requires nexus-ai-pro 1.23 or newer.
+- The studio's development type paths map each entry point to the file it publishes, so studio tests
+  exercise what the package ships.
+
 ## [1.22.0] - 2026-09-29
 
 Retrieval and integration breadth. Getting documents in, finding the right ones, and reaching the
@@ -1118,7 +1211,9 @@ shared policy vocabulary is in place for a future release that revisits this.
 - URL fetching rejects unsafe private-network targets and limits response reads.
 - CLI and audit findings no longer disclose detected secret values.
 
-[Unreleased]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.22.0...HEAD
+[Unreleased]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.24.0...HEAD
+[1.24.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.23.0...v1.24.0
+[1.23.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.22.0...v1.23.0
 [1.22.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.21.0...v1.22.0
 [1.21.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.20.0...v1.21.0
 [1.20.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.19.0...v1.20.0

package/README.md

@@ -1,8 +1,9 @@
 # nexus-ai-pro
 
-The typed AI framework for TypeScript. One API for provider routing and failover, agent graphs that
-run branches in parallel and survive a restart, durable background operations, guardrails, cost
-control, images, voice, and evals.
+The typed AI framework for TypeScript. One API for provider routing and failover, agent graphs and
+workflows that run branches in parallel and survive a restart, retrieval over any vector store, MCP,
+durable background operations, guardrails, cost control, images, voice, and evals — with a studio a
+team can share.
 
 Import the whole runtime, or one piece: every capability has its own entry point with a size budget
 CI enforces, and [the packaging guide](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/packaging.md) publishes what each one costs. A graph-only application loads 49 KB
@@ -90,6 +91,16 @@ You can still pass a plain `NexusAIConfig` to `new NexusAI(...)` when you want f
 - embed text through the same routing, caching, batching, budget, retry, and metrics as a completion
 - run long operations that survive a restart, with leases, retries, dead-lettering, and signed webhooks
 - build stateful graphs with cycles, fan-out, subgraphs, human approval, and resumable checkpoints
+- make ordinary async functions durable step by step, and recover a crashed run at the step it died on
+- load files, web pages, sitemaps, and Git repositories into retrieval, over memory, Postgres, SQLite,
+  Redis, Qdrant, Pinecone, Weaviate, or Chroma
+- retrieve with hybrid keyword and vector search, reranking, and diversity, and measure it with evals
+- reach tools from many MCP servers under one configuration, with allowlists and credentials from the
+  environment
+- version prompts, instructions, tools, and skills together, and promote them through evaluation gates
+- find failing and slow runs, detect regressions, and review evaluated fix proposals in a shared studio
+- serve assistants as revisions, with canaries that roll back on a regression, workers that scale on
+  the queue under Kubernetes, and per-tenant quotas, rate limits, and budgets
 - trip routing away from a failing provider, and share one rate-limit budget across workers
 - reach the providers' half-price asynchronous batch tier behind one operation handle
 - persist generated media to disk or S3 with tenant isolation, retention, and checksums
@@ -112,6 +123,8 @@ from the doc comments. The guides live in the repository, so these links go to G
 | [MCP](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/mcp.md) | Borrowing tools from MCP servers, a registry of many, and serving your own |
 | [Traces](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/tracing.md) | Run trees, queries, feedback, comparison, and alerts |
 | [Evaluation](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/evaluation.md) | Datasets, evaluators, experiments, comparisons with a verdict, review queues, LLM judges |
+| [Context hub](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/context-hub.md) | Prompts, instructions, tools, and skills versioned together, promoted through gates, and moved between projects |
+| [Insights](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/insights.md) | Failing and slow runs clustered, regressions between time windows, and evaluated fix proposals |
 | [Prompts](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/prompts.md) | Typed templates, content versions, gated promotion, rollback, A/B splits, serving through outages |
 | [Postgres](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/postgres.md) | One adapter family for operations, memory, traces, evaluation, circuits, and prompts |
 | [SQLite](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/sqlite.md) | Durable operations, checkpoints, and memory on one machine, over any SQLite driver |
@@ -128,8 +141,9 @@ from the doc comments. The guides live in the repository, so these links go to G
 | [Realtime voice](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/realtime.md) | Browser and server realtime sessions with barge-in, tools, and exports |
 | [Telephony](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/telephony.md) | Calls, webhooks, phone numbers, and phone agents on realtime sessions |
 | [Testing](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/testing.md) | Recording and replaying provider traffic, and conformance suites |
-| [Studio](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/studio.md) | A local UI for traces, threads, approvals, experiments, prompts, costs, and health, as a separate package |
-| [Agent server](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/server.md) | Self-hosted HTTP server for assistants: threads, durable runs, resumable streams, cron |
+| [Studio](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/studio.md) | A shared UI for traces, threads, approvals, experiments, prompts, deployments, costs, and health, as a separate package |
+| [Agent server](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/server.md) | Self-hosted HTTP server for assistants: threads, durable runs, resumable streams, cron, a worker queue, and metrics |
+| [Deployments](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/deployments.md) | Revisions and canaries with automatic rollback, autoscaling on Kubernetes and Helm, and per-tenant limits |
 | [Workflows](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/workflows.md) | Ready-made chains and domain workflows |
 | [Command line](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/cli.md) | The `nexus` command |
 | [Packaging and install weight](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/packaging.md) | Every entry point and what it costs |
@@ -179,10 +193,11 @@ interface, or enum, has no doc comment, and `npm run docs:guides` fails when a g
 every export of the entry points it covers, or its generated reference is stale. Both hold at 100%;
 `--list` names what is missing, and `npm run docs:update` regenerates the references.
 
-Real provider conformance is opt-in:
+Real provider conformance, and the vector store contract against real servers, are opt-in:
 
 ```bash
 npm run test:conformance:real
+npm run test:vectors:live
 ```
 
 ## Roadmap
@@ -201,11 +216,18 @@ Shipped so far:
 - record and replay of provider traffic;
 - prompt versioning: typed templates, content versions, gated promotion, and serving through outages;
 - a self-hosted agent server, and a local studio as a separate package;
-- per-entry-point size budgets.
-
-Next: durable functional workflows and step-level recovery, then retrieval and integration breadth,
-a shared team studio, and self-managed deployment at scale, before 2.0.0 consolidates. The image
-family leaves experimental once recorded live conformance passes on all three backends.
+- per-entry-point size budgets;
+- vector stores behind one contract, and deprecation warnings at run time;
+- durable functional workflows, step-level recovery in the server, SQLite persistence, and diagrams
+  as images;
+- document loaders, five more vector stores, hybrid retrieval with reranking, and an MCP registry;
+- a shared studio with accounts, roles, an audit log, and comments; a context hub; insights with
+  evaluated fix proposals; and evaluation caching;
+- self-managed deployment at scale: revisions and canaries with automatic rollback, a worker queue
+  that autoscales on Kubernetes, and per-tenant limits.
+
+Next: 2.0.0 consolidates. The image family leaves experimental once recorded live
+conformance passes on all three backends.
 
 ## Before Production
 

package/dist/cli/deploy.d.ts

@@ -0,0 +1,15 @@
+import { type ParsedArgs } from './args.js';
+/**
+ * `nexus deploy` reads and changes an agent server's deployments over HTTP, for a pipeline that rolls
+ * out a new image and then moves traffic onto it:
+ *
+ *   nexus deploy status [assistant]
+ *   nexus deploy canary <assistant> <revision> <percent>
+ *   nexus deploy promote <assistant> <revision>
+ *   nexus deploy rollback <assistant> [--to <revision>]
+ *
+ * `--url` (or `NEXUS_SERVER_URL`) names the server, and `--token` (or `NEXUS_SERVER_TOKEN`) is sent
+ * as a bearer token. Changes take `--reason`, recorded in the deployment's history, and `--version`,
+ * which refuses the change if someone else moved the deployment first.
+ */
+export declare function runDeployCommand(subcommand: string | undefined, { positionals, flags }: ParsedArgs): Promise<void>;

package/dist/cli/deploy.js

@@ -0,0 +1,116 @@
+import { CliUsageError, numberFlag, printTable, stringFlag, writeJson } from './args.js';
+export async function runDeployCommand(subcommand, { positionals, flags }) {
+    const server = serverOf(flags);
+    const reason = stringFlag(flags, 'reason');
+    const expectedVersion = numberFlag(flags, 'version');
+    const change = async (assistant, body) => {
+        if (!assistant)
+            throw new CliUsageError(`nexus deploy ${subcommand} needs an assistant.`);
+        const deployment = await server.request('POST', `/deployments/${encodeURIComponent(assistant)}`, {
+            ...body,
+            ...(reason ? { reason } : {}),
+            ...(expectedVersion === undefined ? {} : { expectedVersion }),
+        });
+        if (flags.json === true)
+            writeJson(deployment);
+        else
+            console.log(`${assistant}: version ${deployment.version}, live ${deployment.live}, ${splitText(deployment.traffic)}`);
+    };
+    switch (subcommand) {
+        case 'status': {
+            const [assistant] = positionals;
+            if (assistant) {
+                const deployment = await server.request('GET', `/deployments/${encodeURIComponent(assistant)}`);
+                if (flags.json === true)
+                    return writeJson(deployment);
+                console.log(`${deployment.assistant}: version ${deployment.version}, live ${deployment.live}`);
+                console.log(`split: ${splitText(deployment.traffic)}`);
+                if (deployment.stats?.length) {
+                    console.log('');
+                    printTable(deployment.stats.map((item) => ({
+                        revision: item.revision || '(none)',
+                        runs: String(item.runs),
+                        failed: String(item.failed),
+                        'error rate': `${(item.errorRate * 100).toFixed(1)}%`,
+                        p95: item.p95Ms === undefined ? '' : `${Math.round(item.p95Ms)}ms`,
+                    })), ['revision', 'runs', 'failed', 'error rate', 'p95']);
+                }
+                if (deployment.history.length) {
+                    console.log('');
+                    printTable(deployment.history.slice(0, 10).map((entry) => ({
+                        version: String(entry.version),
+                        at: entry.at,
+                        action: entry.action,
+                        split: splitText(entry.traffic),
+                        by: entry.by ?? '',
+                        reason: entry.reason ?? '',
+                    })), ['version', 'at', 'action', 'split', 'by', 'reason']);
+                }
+                return;
+            }
+            const { deployments } = await server.request('GET', '/deployments');
+            if (flags.json === true)
+                return writeJson(deployments);
+            printTable(deployments.map((deployment) => ({
+                assistant: deployment.assistant,
+                live: deployment.live,
+                split: splitText(deployment.traffic),
+                version: String(deployment.version),
+                updated: deployment.version ? deployment.updatedAt : 'never',
+            })), ['assistant', 'live', 'split', 'version', 'updated']);
+            return;
+        }
+        case 'canary': {
+            const [assistant, revision, percent] = positionals;
+            const share = Number(percent);
+            if (!revision || !Number.isFinite(share) || share < 0 || share > 100) {
+                throw new CliUsageError('Usage: nexus deploy canary <assistant> <revision> <percent from 0 to 100>');
+            }
+            return change(assistant, { action: 'canary', revision, weight: share / 100 });
+        }
+        case 'promote': {
+            const [assistant, revision] = positionals;
+            if (!revision)
+                throw new CliUsageError('Usage: nexus deploy promote <assistant> <revision>');
+            return change(assistant, { action: 'promote', revision });
+        }
+        case 'rollback': {
+            const [assistant] = positionals;
+            const to = stringFlag(flags, 'to');
+            return change(assistant, { action: 'rollback', ...(to ? { to } : {}) });
+        }
+        default:
+            throw new CliUsageError(`Unknown deploy command "${subcommand ?? ''}". Use status, canary, promote, or rollback.`);
+    }
+}
+function serverOf(flags) {
+    const url = stringFlag(flags, 'url') ?? process.env.NEXUS_SERVER_URL;
+    if (!url)
+        throw new CliUsageError('nexus deploy needs the server: pass --url or set NEXUS_SERVER_URL.');
+    const token = stringFlag(flags, 'token') ?? process.env.NEXUS_SERVER_TOKEN;
+    const base = url.replace(/\/+$/, '');
+    return {
+        async request(method, route, body) {
+            const response = await fetch(`${base}${route}`, {
+                method,
+                headers: {
+                    ...(token ? { authorization: `Bearer ${token}` } : {}),
+                    ...(body === undefined ? {} : { 'content-type': 'application/json' }),
+                },
+                ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+            });
+            const text = await response.text();
+            const parsed = text ? JSON.parse(text) : {};
+            if (!response.ok) {
+                const error = parsed.error;
+                throw new Error(`${response.status} ${error?.code ?? response.statusText}: ${error?.message ?? text}`);
+            }
+            return parsed;
+        },
+    };
+}
+function splitText(traffic) {
+    return Object.entries(traffic)
+        .map(([revision, weight]) => `${revision} ${Math.round(weight * 1000) / 10}%`)
+        .join(', ');
+}

package/dist/cli.js

@@ -49,6 +49,12 @@ async function main() {
             await runDbCommand(subcommand, { positionals: args, flags: parsed.flags });
             return;
         }
+        case 'deploy': {
+            const [subcommand, ...args] = parsed.positionals;
+            const { runDeployCommand } = await import('./cli/deploy.js');
+            await runDeployCommand(subcommand, { positionals: args, flags: parsed.flags });
+            return;
+        }
         case 'optimize':
             await runOptimize(parsed);
             return;
@@ -390,12 +396,17 @@ Usage:
   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 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]
+  nexus deploy rollback <assistant> [--to revision] --url <server> [--reason r] [--version n]
   nexus optimize [request.json|prompt.txt] [--model gpt-5-mini] [--max-input-tokens 4000] [--densify] [--json]
 
 Eval files can export { cases, client } or { cases, config }. JSON cases may use "expected", "contains", and "match": "includes" | "exact" | "regex".
 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.`);
+Trace store modules export any TraceStore as { store }, such as a PostgresTraceStore over the application's own pool.
+"deploy" reads NEXUS_SERVER_URL and NEXUS_SERVER_TOKEN when --url and --token are not given.`);
 }
 main().catch((error) => {
     const message = error instanceof Error ? error.message : String(error);

package/dist/context-hub/diff.d.ts

@@ -0,0 +1,32 @@
+import { type PromptLineChange } from '../prompts/diff.js';
+import type { ContextBundle } from './hub.js';
+/** One entry that differs between two bundle versions. */
+export interface ContextChange {
+    /** The part of the bundle. */
+    section: 'description' | 'prompts' | 'instructions' | 'tools' | 'skills' | 'config';
+    /** The entry within it: a prompt role, an instruction or skill name, a tool name, or a config key. */
+    key: string;
+    /** Whether the entry was added, removed, or changed. */
+    change: 'added' | 'removed' | 'changed';
+    /** Line by line, for text: an instruction, a skill's instructions, or the description. */
+    lines?: PromptLineChange[];
+    /** The entry before, for anything that is not text. */
+    before?: unknown;
+    /** The entry after, for anything that is not text. */
+    after?: unknown;
+}
+/** What changed between two versions of a bundle. */
+export interface ContextDiff {
+    /** The bundle. */
+    name: string;
+    /** The earlier version. */
+    from: string;
+    /** The later version. */
+    to: string;
+    /** Every entry that differs, section by section. */
+    changes: ContextChange[];
+}
+/** Compares two versions of a bundle, entry by entry, with line diffs for text. */
+export declare function diffContexts(from: ContextBundle, to: ContextBundle): ContextDiff;
+/** A diff as text, one line per change and `+`/`-` lines for text, for a terminal or a pull request. */
+export declare function formatContextDiff(diff: ContextDiff): string;

package/dist/context-hub/diff.js

@@ -0,0 +1,64 @@
+import { diffLines } from '../prompts/diff.js';
+import { canonicalJson } from '../prompts/version.js';
+export function diffContexts(from, to) {
+    const changes = [];
+    if ((from.description ?? '') !== (to.description ?? '')) {
+        changes.push({
+            section: 'description',
+            key: 'description',
+            change: from.description === undefined ? 'added' : to.description === undefined ? 'removed' : 'changed',
+            lines: diffLines(from.description ?? '', to.description ?? ''),
+        });
+    }
+    compare(changes, 'prompts', from.prompts, to.prompts);
+    compare(changes, 'instructions', from.instructions, to.instructions, (value) => value);
+    compare(changes, 'tools', Object.fromEntries((from.tools ?? []).map((tool) => [tool.name, tool])), Object.fromEntries((to.tools ?? []).map((tool) => [tool.name, tool])));
+    compare(changes, 'skills', from.skills, to.skills, (value) => {
+        const skill = value;
+        return `${skill.description}\n\n${skill.instructions}${Object.entries(skill.resources ?? {})
+            .map(([name, text]) => `\n\n[${name}]\n${text}`)
+            .join('')}`;
+    });
+    compare(changes, 'config', from.config, to.config);
+    return { name: to.name, from: from.version, to: to.version, changes };
+}
+export function formatContextDiff(diff) {
+    const lines = [`${diff.name}: ${diff.from} -> ${diff.to}`];
+    if (diff.changes.length === 0)
+        lines.push('  no changes');
+    for (const change of diff.changes) {
+        lines.push(`  ${change.change} ${change.section}.${change.key}`);
+        for (const line of change.lines ?? []) {
+            if (line.op !== '=')
+                lines.push(`    ${line.op} ${line.text}`);
+        }
+        if (!change.lines && change.change === 'changed') {
+            lines.push(`    - ${canonicalJson(change.before)}`, `    + ${canonicalJson(change.after)}`);
+        }
+    }
+    return lines.join('\n');
+}
+function compare(changes, section, before, after, asText) {
+    const keys = [...new Set([...Object.keys(before ?? {}), ...Object.keys(after ?? {})])].sort();
+    for (const key of keys) {
+        const was = before?.[key];
+        const is = after?.[key];
+        if (was !== undefined && is !== undefined && canonicalJson(was) === canonicalJson(is))
+            continue;
+        const change = was === undefined ? 'added' : is === undefined ? 'removed' : 'changed';
+        changes.push(asText
+            ? {
+                section,
+                key,
+                change,
+                lines: diffLines(was === undefined ? '' : asText(was), is === undefined ? '' : asText(is)),
+            }
+            : {
+                section,
+                key,
+                change,
+                ...(was === undefined ? {} : { before: was }),
+                ...(is === undefined ? {} : { after: is }),
+            });
+    }
+}