nexus-ai-pro 1.23.0 → 1.25.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,35 @@ 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.
 
+## 2.0 preparation stage (1.25.0)
+
+The last 1.x minor deprecates what 2.0 removes. Deprecated APIs keep working, unchanged, for the rest
+of the 1.x line.
+
+- The 2.0 root import keeps the core client, its config builders, the types of its configuration,
+  requests, and responses, and the errors it throws. Every other root export is deprecated in favour of
+  the subpath that already provides it, under the same name or, where noted, another.
+- Every deprecated option warns once per process through Node's `DeprecationWarning` channel, so
+  `--throw-deprecation` finds them in a test run. Deprecated exports and fields are marked in the type
+  declarations, where editors show them.
+- `nexus migrate` and its map follow the root's deprecations; both are generated from the export map,
+  so they cannot disagree.
+- A 1.x checkpoint stays readable throughout 2.x, by both checkpointers and by `migrateCheckpoint()`.
+
+## 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

package/CHANGELOG.md

@@ -4,6 +4,109 @@ Notable changes to this project are recorded here. The format follows [Keep a Ch
 
 ## [Unreleased]
 
+## [1.25.0] - 2026-10-01
+
+The bridge to 2.0. Everything 2.0 removes is deprecated now, every capability has a subpath of its
+own, and the tools to migrate ship with it, so a codebase can move while it is still on 1.x.
+
+### Added
+
+- **A subpath for every capability.** What could only be imported from the root has an entry point
+  of its own, each with no third-party dependency: `nexus-ai-pro/grounding` (grounded prompts,
+  verification, self-consistency, knowledge graphs), `/connectors` (web tools), `/ops` (metrics,
+  health, audit, OpenTelemetry export, rate limiting), `/pipeline`, `/router`, `/testing`
+  (conformance suites), `/next` (the route handler), `/rag/files` (scanned file ingestion), and
+  `/optimizer/cost` (cost estimates and budgets). Grounding alone is 15 KB, where it used to mean the
+  584 KB root and its validators. `hardenPrompt()` joins `/security`, `Tokenizer` joins `/optimizer`, the
+  registry's data joins `/models`, and the capability types join `/capabilities`.
+- **`nexus migrate`**, a codemod that moves imports to the subpaths the 2.0 root keeps them on. It
+  rewrites `import`, `import type`, `export … from`, and destructured `require()` in TypeScript,
+  JavaScript, and Markdown code blocks, keeps local names when a name moved under another, and lists
+  what it cannot rewrite safely. `--check` fails a CI job while anything is left.
+- **`MIGRATING.md`**, shipped in the package: every change 2.0 makes, with before-and-after code.
+- **Modalities with a direction**: `inputModalities` and `outputModalities` on a model's capabilities,
+  `modalitiesOf()` on `nexus-ai-pro/models` to read either shape, and both as routing requirements.
+- **The 2.0 checkpoint schema, readable now**: `migrateCheckpoint()` and `GraphCheckpointV2` on
+  `nexus-ai-pro/graph`.
+
+### Deprecated
+
+- 499 exports of the root import, each in favour of the subpath that already provides it. 2.0 keeps
+  only the core client, its config builders, its types, and the errors it throws on the root. Editors
+  strike a deprecated import through and name the subpath; `nexus migrate` moves them.
+- `ModelCapabilities.modalities` and `routing.requiredCapabilities.modalities`, for the directional
+  fields. The routing requirement warns once per process.
+- `GraphCheckpoint.interrupt`, for `interrupts`.
+
+### Changed
+
+- The guides' examples import from subpaths, as 2.0 requires.
+
+### Fixed
+
+- The agents guide pointed at `nexus-ai-pro/connectors`, which did not exist. It does now.
+- `tenantLimits({ now })` drives the default usage and rate stores too. They kept the system clock, so
+  a budget judged on a replaced clock reset when the real day ended.
+
+## [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
@@ -1152,7 +1255,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.23.0...HEAD
+[Unreleased]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.25.0...HEAD
+[1.25.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.24.0...v1.25.0
+[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

package/MIGRATING.md

@@ -0,0 +1,169 @@
+# Migrating to 2.0
+
+2.0.0 removes what the 1.x line deprecated. Everything you need to get ready ships in 1.25, so you can
+migrate while you are still on 1.x. Nothing below breaks before 2.0.
+
+Start with the codemod. It rewrites what it can safely, and lists the rest:
+
+```bash
+npx nexus migrate src           # reports what would change
+npx nexus migrate src --write   # rewrites the files
+npx nexus migrate src --check   # exits 1 while anything is left, for CI
+```
+
+Then run your tests with `node --throw-deprecation`. Every deprecated option warns once per process,
+so a clean run means nothing you call is going away.
+
+| Change | The codemod | By hand |
+| --- | --- | --- |
+| [The root import keeps only the core](#the-root-import-keeps-only-the-core) | Rewrites the imports | Namespace and dynamic imports of the root |
+| [`estimatedCost` is removed](#a-responses-estimatedcost-is-removed) | Lists each read | Read `cost.amount` |
+| [`ImageManagerConfig` is removed](#imagemanagerconfig-is-removed) | Renames it | — |
+| [Options that were never read are removed](#options-that-were-never-read-are-removed) | — | Delete them; each warns today |
+| [Modalities say which way they flow](#modalities-say-which-way-they-flow) | — | Set the two new fields |
+| [Checkpoints gain ids and lose `interrupt`](#checkpoints-gain-ids-and-lose-interrupt) | — | Read `interrupts` |
+| [Validators and Node types become optional](#validators-and-node-types-become-optional) | — | Install what you use |
+| [Planned, not yet final](#planned-not-yet-final) | — | Nothing yet |
+
+## The root import keeps only the core
+
+In 2.0, `nexus-ai-pro` exports the core client and nothing else. That is:
+
+- `NexusAI`, `createNexus`, and the config builders;
+- `tool()`, the streaming helpers, and the usage and pricing helpers for custom providers;
+- the types of the client's configuration, requests, and responses;
+- the errors the client throws: `NexusProviderError`, `NexusSecurityError`, `NexusRateLimitError`,
+  `NexusCapabilityError`, `TokenBudgetError`, `CostBudgetError`, and `ResponseFormatError`.
+
+Every other export is on its own subpath already. In 1.25 each one is deprecated on the root, and your
+editor strikes it through with the subpath to use.
+
+```ts
+// Before
+import { NexusAI, MemoryVectorStore, withRagContext, OperationRunner } from 'nexus-ai-pro';
+
+// After
+import { NexusAI } from 'nexus-ai-pro';
+import { OperationRunner } from 'nexus-ai-pro/operations';
+import { withRagContext } from 'nexus-ai-pro/grounding';
+import { MemoryVectorStore } from 'nexus-ai-pro/rag';
+```
+
+The codemod does this for `import`, `import type`, `export … from`, and destructured `require()`. A
+name that moved under another name keeps its local name through an alias:
+
+```ts
+// Before
+import type { AgentModelClient } from 'nexus-ai-pro';
+// After
+import type { AgentLoopModelClient as AgentModelClient } from 'nexus-ai-pro/agent';
+```
+
+It cannot split a namespace import (`import * as nexus from 'nexus-ai-pro'`) or a dynamic `import()`,
+so it lists them. Import each name you use from its subpath instead. Every subpath and what it costs to
+install is in the [packaging guide](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/packaging.md).
+
+The smaller root is the point: an application that uses one family no longer loads the client, its
+validators, or the model registry.
+
+## A response's `estimatedCost` is removed
+
+The formatted string on a response's metadata goes. Read the numeric cost and format it yourself:
+
+```ts
+// Before
+console.log(response.meta.estimatedCost); // '$0.0012'
+
+// After
+const cost = response.meta.cost;
+if (cost) console.log(new Intl.NumberFormat('en-US', { style: 'currency', currency: cost.currency }).format(cost.amount));
+```
+
+A plan's `estimatedCost`, from `ai.plan()`, is an object and stays.
+
+## `ImageManagerConfig` is removed
+
+It was an alias of `ImageConfig`. The codemod renames the import and keeps your local name.
+
+## Options that were never read are removed
+
+These were accepted and ignored. Each one already warns once per process when it is set.
+
+| Option | Deprecated in |
+| --- | --- |
+| `GoogleProviderConfig.projectId` | 1.16.0 |
+| `OllamaProviderConfig.timeout` | 1.16.0 |
+| `MetricsConfig.prometheus` | 1.16.0 |
+| `DensificationConfig.preserveMarkdown` | 1.16.0 |
+| `HealthConfig.latencyHalfLife` | 1.16.0 |
+| `InjectionDetectionConfig.sensitivity` | 1.19.0 |
+| `ToolPolicyConfig.requiresApproval` | 1.19.0 |
+
+Delete them. Nothing changes, because nothing read them.
+
+## Modalities say which way they flow
+
+A model's `modalities` list mixed inputs and outputs: `vision` meant an image in, and `image` meant an
+image out. 2.0 replaces it with `inputModalities` and `outputModalities`, which 1.25 already reads.
+
+```ts
+// A model you define, before
+models: { registry: { 'my-model': { modalities: ['text', 'vision'], /* … */ } } }
+
+// After: keep modalities until 2.0, and add the two new fields
+models: {
+  registry: {
+    'my-model': { modalities: ['text', 'vision'], inputModalities: ['text', 'image'], outputModalities: ['text'], /* … */ },
+  },
+}
+```
+
+Read either shape through `modalitiesOf()` from `nexus-ai-pro/models`. In routing requirements, replace
+`modalities` with `inputModalities` or `outputModalities`; the old field warns once.
+
+## Checkpoints gain ids and lose `interrupt`
+
+The 2.0 checkpoint schema gives every checkpoint an id and its pending tasks, and keeps questions only
+in `interrupts`. Both checkpointers keep reading 1.x checkpoints throughout 2.x, so stored threads
+resume.
+
+```ts
+// Before
+const question = checkpoint.interrupt;
+
+// After
+const [question] = checkpoint.interrupts ?? [];
+```
+
+To write code against the 2.0 shape today, read checkpoints through `migrateCheckpoint()` from
+`nexus-ai-pro/graph`, which returns it from either schema.
+
+## Validators and Node types become optional
+
+`zod`, `ajv`, and `ajv-formats` become optional peer dependencies, and so does `@types/node`. The target is
+that a graph-only application installs at most 3.5 MB, instead of about 10 MB today.
+
+If you validate with schemas, or compile TypeScript against Node's types, add what you use:
+
+```bash
+npm install zod ajv ajv-formats
+npm install --save-dev @types/node
+```
+
+The 2.0 release notes list exactly which calls need each one.
+
+## Planned, not yet final
+
+These are designed during the 2.0 cycle. This guide gains their before-and-after code when they land.
+
+- **One lifecycle for every operation.** Completions, streams, embeddings, voice, images, jobs, graphs,
+  and agents share authorization, budgets, hooks, audit, metrics, and tracing. Custom providers receive
+  a `ProviderCallContext` with the abort signal, deadline, request id, trace context, and idempotency key.
+- **Typed pipeline contexts.** `PipelineContext` becomes generic over its request and response, and
+  `PipelineStepName` lists only the built-in steps.
+- **Mixed outputs.** A tool result can carry asset references instead of base64 JSON.
+
+## Runtime
+
+2.0 runs on Node 22 and newer. If it ships after Node 22's end of life in April 2027, the floor moves to
+Node 24.

package/README.md

@@ -99,6 +99,8 @@ You can still pass a plain `NexusAIConfig` to `new NexusAI(...)` when you want f
   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
@@ -139,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 |
@@ -219,9 +222,15 @@ Shipped so far:
   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.
-
-Next: self-managed deployment at scale, before 2.0.0 consolidates. The image family leaves experimental once recorded live
+  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;
+- the bridge to 2.0: every capability on a subpath of its own, everything 2.0 removes deprecated, and
+  a codemod that moves your imports.
+
+Next: 2.0.0 consolidates. It slims the root import to the core client; `npx nexus migrate src --write`
+moves your imports today, and [MIGRATING.md](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/MIGRATING.md)
+covers the rest. The image family leaves experimental once recorded live
 conformance passes on all three backends.
 
 ## Before Production

package/dist/capabilities/negotiate.d.ts

@@ -45,3 +45,4 @@ export interface NegotiateOptions {
  * declaration means the registry does not know, not that the provider refuses.
  */
 export declare function negotiateCompletionRequest(request: CompletionRequest, capabilities: ModelCapabilities | undefined, options?: NegotiateOptions): NegotiationResult<CompletionRequest>;
+export type { CapabilityConfig, CapabilityPolicy, CapabilityWarning, CapabilityWarningAction, } from '../types/capabilities.js';

package/dist/cli/args.js

@@ -3,6 +3,7 @@ import { pathToFileURL } from 'node:url';
 export const BOOLEAN_FLAGS = new Set([
     'all',
     'allow-dataset-mismatch',
+    'check',
     'densify',
     'fail',
     'fail-on-regression',
@@ -10,6 +11,7 @@ export const BOOLEAN_FLAGS = new Set([
     'json',
     'print',
     'reveal-values',
+    'write',
 ]);
 export function parseArgs(args) {
     const positionals = [];

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/migrate.d.ts

@@ -0,0 +1,52 @@
+import { type ParsedArgs } from './args.js';
+/** One thing `migrateSource()` changed, or found and left for a person. */
+export interface MigrationNote {
+    /** The line, starting at 1. */
+    line: number;
+    /** What was done, or what to do. */
+    message: string;
+}
+/** What `migrateSource()` produced for one file's text. */
+export interface MigrationOutcome {
+    /** The text after migration; the input itself when nothing changed. */
+    text: string;
+    /** Imports rewritten and names renamed. */
+    changes: MigrationNote[];
+    /** What it found and could not rewrite safely, for a person to finish. */
+    notes: MigrationNote[];
+}
+/**
+ * Migrates one file's text to the 2.0 imports: names the root import drops are imported from their
+ * subpaths, names that moved under another name keep their local name through an alias, and deprecated
+ * aliases are replaced. What cannot be rewritten safely — a namespace import of the root, a dynamic
+ * import, a read of `estimatedCost` — is reported instead of guessed at.
+ *
+ * Markdown is migrated inside its TypeScript and JavaScript code blocks only. Running it twice changes
+ * nothing the second time.
+ */
+export declare function migrateSource(text: string, options?: {
+    file?: string;
+}): MigrationOutcome;
+/** Options for `migrateFiles()`. */
+export interface MigrateFilesOptions {
+    /** Writes the migrated files. Without it, nothing is written and the result says what would change. */
+    write?: boolean;
+}
+/** What `migrateFiles()` did with one file. */
+export interface FileMigration extends Omit<MigrationOutcome, 'text'> {
+    /** The file, as given or found. */
+    file: string;
+    /** Whether its text changed. */
+    changed: boolean;
+}
+/**
+ * Migrates every source and Markdown file under the given paths, skipping `node_modules`, build
+ * output, and version control. Files are written only with `write`.
+ */
+export declare function migrateFiles(paths: readonly string[], options?: MigrateFilesOptions): Promise<FileMigration[]>;
+/**
+ * `nexus migrate [paths…] [--write] [--check] [--json]` moves imports of the root to the subpaths the
+ * 2.0 root import keeps them on. Without `--write` it only reports; `--check` exits 1 when a file still
+ * needs migrating, for a CI job that keeps a codebase ready.
+ */
+export declare function runMigrateCommand({ positionals, flags }: ParsedArgs): Promise<void>;