nexus-ai-pro 1.24.0 → 2.0.0

package/API_STABILITY.md

@@ -1,12 +1,13 @@
 # API Stability Policy
 
-This policy describes compatibility guarantees for `nexus-ai-pro`. The 1.x compatibility guarantees
-apply beginning with version 1.0.0.
+This policy describes compatibility guarantees for `nexus-ai-pro`. The 2.x guarantees apply beginning
+with version 2.0.0, as the 1.x guarantees applied from 1.0.0. The sections for the 1.x stages below
+still describe each surface; where they say "the 1.x rules", read the rules of the current major line.
 
 ## Release stages
 
-The package follows semantic versioning. Within the 1.x line, incompatible changes to stable public
-APIs require a major release. Minor releases may add backward-compatible features, and patch releases
+The package follows semantic versioning. Within a major line, incompatible changes to stable public
+APIs require the next major release. Minor releases may add backward-compatible features, and patch releases
 are intended to remain backward compatible.
 
 The following surfaces are public and covered by this policy:
@@ -40,6 +41,45 @@ Both are covered by this policy:
 Deep imports into `dist`, `dist-cjs`, or `src` are not supported. Import only from `nexus-ai-pro` or
 one of its explicit subpaths.
 
+## 2.0 stage (2.0.0)
+
+2.0 removes what 1.x deprecated and promotes the surfaces that have settled.
+
+**Promoted to stable.** These follow the 2.x rules without an experimental label:
+
+- graphs, with their advanced APIs: `Send`, `Command`, breakpoints, `updateState()`, `fork()`, node
+  caching, and functional workflows (`nexus-ai-pro/graph`, `/graph/functional`, `/graph/visualize`);
+- the store (`nexus-ai-pro/store`, `/store/redis`), agents (`nexus-ai-pro/agent`), and tracing
+  (`nexus-ai-pro/tracing`);
+- evaluation (`nexus-ai-pro/evaluate`) and prompts (`nexus-ai-pro/prompts` and `/postgres/prompts`);
+- the agent server (`nexus-ai-pro/server`): its routes, `RunRecord`, `ThreadRecord`, `RunEvent`, and
+  recovery.
+
+**New in 2.0, and stable from the start:**
+
+- the operation lifecycle: the stage order, `LifecycleConfig`, `LifecycleHooks`, the
+  `OperationDescriptor`, `OperationOutcome`, and `OperationTicket` shapes, the `BudgetLedger`
+  contract, and `ProviderCallContext`. New families and stages may be added in a minor release;
+  existing ones keep their names;
+- mixed content: `AssetContent`, `ToolOutput`, and `response.assets`;
+- checkpoint schema version 2. Both checkpointers read version 1 throughout 2.x.
+
+**Still experimental in production readiness**, each following the 2.x rules all the same:
+
+- images, until recorded live conformance passes on all three backends;
+- the studio package;
+- deployments, tenant limits, and the server's worker queue (1.24);
+- the context hub, insights, and the studio's accounts (1.23);
+- the loaders, the vector stores added in 1.20 and 1.22, the retrievers, and the MCP registry;
+- the SQLite adapters (1.21).
+
+**Root import.** The root exports the core client, its config builders, its types, the errors it
+throws, the lifecycle, and `tool()` and `toolOutput()`. Adding anything else to the root waits for a
+major release, and a check in CI fails when the root grows.
+
+**Dependencies.** The package has no required dependency. `zod`, `ajv`, `ajv-formats`, and
+`@types/node` are optional peers; making any of them required again would need a major release.
+
 ## Capability negotiation stage
 
 `negotiateCompletionRequest()`, `NexusCapabilityError`, `CapabilityPolicy`, `CapabilityWarning`, and
@@ -457,6 +497,21 @@ 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

package/CHANGELOG.md

@@ -4,6 +4,168 @@ Notable changes to this project are recorded here. The format follows [Keep a Ch
 
 ## [Unreleased]
 
+## [2.0.0] - 2026-10-02
+
+Consolidation. One lifecycle runs every call of every family, the root import holds the core client
+and nothing else, and the package installs with no required dependency. Everything removed here was
+deprecated in 1.x; [MIGRATING.md](./MIGRATING.md) covers each change with before-and-after code, and
+`nexus migrate` rewrites the imports.
+
+### Breaking
+
+- **The root import keeps only the core**: the client, its config builders, its types, the errors it
+  throws, the lifecycle, and the tool helpers. The 498 other names it re-exported are on their
+  subpaths; `nexus migrate` moves 1.x imports there. Importing the root costs 323 KB, down from 572 KB.
+- **`zod`, `ajv`, `ajv-formats`, and `@types/node` are optional peer dependencies.** A zod shape is
+  checked through its own `safeParse`; a JSON Schema response format loads ajv on its first check, and
+  says what to install when it is missing. A production install is 5.3 MB, the package alone, down
+  from 12.3 MB.
+- **A response's `estimatedCost` string is removed**, for the numeric `cost`. A plan's
+  `estimatedCost` object stays.
+- **Modalities say which way they flow.** `ModelCapabilities.inputModalities` and `outputModalities`
+  are required on every entry, bundled or registered; `modalities`, the `Modality` type, and the
+  `modalities` routing requirement are removed.
+- **Checkpoint schema version 2.** A checkpoint has its `version`, an `id`, its `tasks` always, and its
+  questions only in `interrupts`; `interrupt` is gone. Both checkpointers read version 1 for the whole
+  2.x line, so threads 1.x left waiting resume. A checkpointer's `get()` and `history()` return a
+  `StoredGraphCheckpoint` of either version.
+- **Options that were never read are removed**: `GoogleProviderConfig.projectId`,
+  `OllamaProviderConfig.timeout`, `MetricsConfig.prometheus`, `DensificationConfig.preserveMarkdown`,
+  `HealthConfig.latencyHalfLife`, `InjectionDetectionConfig.sensitivity`, and
+  `ToolPolicyConfig.requiresApproval`.
+- **`ImageManagerConfig` is removed**, for `ImageConfig`.
+- **`PipelineStepName` is a closed list.** A custom step is recorded as `customStep`, with its own name
+  in `PipelineTraceStep.custom`. The `auditLog` step is replaced by the lifecycle's `audit`.
+- **`ai.stream()` opens on its first read**, so authorization, rate-limit, guardrail, and budget errors
+  come out of the loop rather than from the call.
+- **What the lifecycle records changed**: metrics carry `family` and `operation` for every family, the
+  image family is labelled `image`, audit events carry `family` and `operation` and add an `error`
+  event, and `response.meta.requestId` is the operation's id.
+- **The model registry is current as of 2026-10-02.** Models their providers shut down are removed:
+  Claude 3.x and 4.0 to 4.1, `gpt-4.5-preview`, `o1-mini`, `gpt-5-codex`, Gemini 1.5 and 2.0 and the
+  shut-down 3.x previews, Groq Compound, Llama 4 Scout, and Qwen3 32B, Mistral's 2024 models, Devstral,
+  and Magistral, and DeepSeek's `deepseek-chat`, `deepseek-reasoner`, V3, and R1. Four names no
+  provider served are gone too: `claude-sonnet-5-0`, `claude-haiku-5-0`, `claude-fable-5-0`, and
+  `gemini-3.5-pro`. Cohere's `command-r` and `command-r-plus` are filed under their dated names, and
+  `mistral-medium-3-5` under `mistral-medium-2604`. Every intent alias points at a current model.
+
+### Added
+
+- **One lifecycle for every operation.** Completions, streams, embeddings, voice, telephony, images,
+  realtime sessions, graphs, agents, queued jobs, and provider batches pass through the same stages:
+  validate, authorize, input policy, resolve assets, route, reserve budget, execute, output policy,
+  persist, reconcile cost, and audit. `lifecycle` on the client configures what they share: an
+  `authorize` callback that can refuse any call, a `budget` every family draws on, and `hooks` that see
+  each call start and finish, cache hits included. `ai.lifecycle` makes graphs, agents, workflows,
+  realtime sessions, job queues, and batches operations of the client too.
+- **A shared spend budget**: `budgetLedger()` on the new `nexus-ai-pro/lifecycle` holds each call's
+  estimate before it runs and charges what it cost after, per tenant and per period, so concurrent calls
+  cannot overshoot together. It keeps totals in memory or in any tenant usage store, Redis included.
+- **`ProviderCallContext`**, handed to every provider call of every family: the request id, the abort
+  signal, the deadline, trace headers, and the idempotency key. The OpenAI and Anthropic adapters send
+  the key and the headers on. Requests take `requestId`, `tenantId`, and `idempotencyKey`.
+- **Mixed text-and-asset content.** `toolOutput()` lets a tool return text, images, and asset
+  references, sent as the tool message itself instead of base64 JSON. An `asset` content part names an
+  asset by reference, an image part can carry an asset, and a model that produces images returns them
+  on `response.assets`.
+- **Typed pipelines**: `PipelineContext` and the runner are generic over the request and response, with
+  `PipelineShapes` for another family's types.
+- **New models**: OpenAI GPT-6 Astra, GPT-6.1 Sol, GPT-6 Sol, GPT-6 Luna, GPT-5 Pro, o3-pro, and
+  GPT-5.3 Codex; Claude Fable 5.1, Opus 5.5, Sonnet 5.5, Fable 5, Opus 5, Sonnet 5, and Sonnet 4.5;
+  Gemini 3.8, 3.7, and 3.6 Flash, 3.5 Flash-Lite, 3.1 Flash-Lite, 3 Pro Image, and 3.1 Flash Image;
+  Groq's Qwen3.8 27B and MiniMax M2.7; Mistral Medium 3.5 and Ministral 3 14B, 8B, and 3B; DeepSeek
+  Flash and V4 Pro; and Cohere Command A Plus, North Mini Code, North Small Translate, and three Tiny
+  Aya models.
+- `ModelCapabilities.sampling`, false for a model that accepts only its default temperature and top-p.
+  Negotiation drops a non-default value for it.
+- `nexus migrate` lists each model name the 2.0 registry dropped, with what to use instead.
+- Anthropic responses report thinking tokens in `usage.reasoningTokens`.
+- **`llms.txt` and `llms-full.txt`** for AI assistants and coding agents: an index of every guide with
+  the facts an assistant needs to recommend the package correctly, and the guides in one file.
+  `llms.txt` ships in the package. Both are generated from the README and the guides, and CI fails
+  when they fall behind.
+- `toCheckpoint()` and `CheckpointDraft` for building a version 2 checkpoint by hand.
+- A `cache_hits` metric, and `routingDecision.provider` and `.model` on a response.
+
+### Changed
+
+- Provider adapters, and the agent, verification, evaluation, workflow, semantic-cache, image, and
+  embedding engines, load on first use, so importing the client never loads them.
+- A context-window summary is an operation of its own, authorized, budgeted, and audited.
+- `getCall()`, `listPhoneNumbers()`, and `updatePhoneNumber()` run through the lifecycle, so they are
+  rate-limited and audited like `createCall()`.
+- `nexus migrate` lists the options and model entries 2.0 removed, and keeps a single moved name on
+  one line.
+- **Prices and limits follow the providers.** GPT-5.6, GPT-5.2 Pro, Mistral Large 3, and Mistral
+  Small 4 cost less. Gemini 3.5 Flash costs $1.50 and $9 per million tokens, not $0.10 and $0.40.
+  Claude Opus 4.5 has a 200K context and 64K output, not 1M and 128K, and Codestral a 128K context.
+  Models with an announced shutdown are `deprecated`, with the date and the replacement in their
+  notes, and an alias that resolves to one is deprecated too.
+- `toolChoice: false` now means a call cannot be forced: negotiation drops `required` or a named tool
+  and lets `auto` and `none` through.
+
+### Fixed
+
+- **Claude 4.6 onward get adaptive thinking.** The Anthropic adapter sent every model a thinking
+  budget, which Claude rejects after 4.6, so a request with `reasoning` failed on current models. It
+  now sends adaptive thinking and `output_config.effort` from 4.6 on, and turns thinking off the way
+  each model allows. It drops sampling values that Claude 4.7 and later reject, and leaves room for
+  thinking when no output limit is set.
+- **Tool calls reach providers whole.** The OpenAI chat and Responses, Anthropic, and Google adapters
+  dropped a conversation's tool calls and the ids that link results to them, so a real tool loop could
+  fail on its second turn. Each now sends both the way its API expects, images in results included.
+- **Responses are priced on the model they were routed to.** A provider that echoed a dated snapshot
+  name priced the call at nothing; Groq, Mistral, and Cohere models filed under a prefix did too.
+- `resolveModel('google/gemini-2.5-flash')` found no capabilities for a provider-prefixed name. It now
+  finds the entry filed without the prefix, when that entry belongs to the same provider.
+- Streams honour the circuit breaker, the cost budget, audit, and metrics, as completions always did.
+- A cache hit is audited and counted.
+- The upload scanner's types no longer need Node's: `content` takes text or any `Uint8Array`.
+
+## [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:
@@ -1211,7 +1373,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.24.0...HEAD
+[Unreleased]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.0.0...HEAD
+[2.0.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.25.0...v2.0.0
+[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

package/MIGRATING.md

@@ -0,0 +1,303 @@
+# Migrating to 2.0
+
+2.0.0 removes what the 1.x line deprecated, and runs every call of every family through one
+lifecycle. Most applications change only their imports, and a codemod does that.
+
+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
+```
+
+Run it while you are still on 1.25, where every name it moves already works on its subpath. Then
+upgrade, and work through the table.
+
+| 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 |
+| [Validators and Node types are optional](#validators-and-node-types-are-optional) | — | Install what you use |
+| [`estimatedCost` is removed](#a-responses-estimatedcost-is-removed) | Lists each read | Read `cost.amount` |
+| [Modalities say which way they flow](#modalities-say-which-way-they-flow) | Lists entries that name `vision` or `pdf` | Write the two fields |
+| [Checkpoints are version 2](#checkpoints-are-version-2) | — | Read `interrupts`; build checkpoints with `toCheckpoint()` |
+| [Options that were never read are removed](#options-that-were-never-read-are-removed) | Lists each one | Delete them |
+| [`ImageManagerConfig` is removed](#imagemanagerconfig-is-removed) | Renames it | — |
+| [Pipeline step names are a closed list](#pipeline-step-names-are-a-closed-list) | — | Read a custom step's name from `custom` |
+| [Streams open on their first read](#streams-open-on-their-first-read) | — | Catch errors around the loop |
+| [Every call runs through the lifecycle](#every-call-runs-through-the-lifecycle) | — | Check dashboards, audit sinks, and rate limits |
+| [Responses are priced on the routed model](#responses-are-priced-on-the-routed-model) | — | Expect costs that were 0 to be priced |
+| [The model registry is current](#the-model-registry-is-current) | Lists each dropped model name, with its replacement | Choose the replacement; check what your aliases resolve to |
+| [Claude 4.6 onward think adaptively](#claude-46-onward-think-adaptively) | — | Nothing |
+| [Tool calls reach providers whole](#tool-calls-reach-providers-whole) | — | Nothing |
+
+## The root import keeps only the core
+
+In 2.0, `nexus-ai-pro` exports the core client and nothing else:
+
+- `NexusAI`, `createNexus`, and the config builders;
+- `tool()`, `toolOutput()`, the streaming helpers, and the usage and pricing helpers;
+- the lifecycle: `OperationLifecycle`, its errors, and its types;
+- 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.
+
+```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,
+is in the [packaging guide](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/packaging.md).
+
+The root import now costs about 323 KB, down from 572 KB.
+
+## Validators and Node types are optional
+
+`zod`, `ajv`, `ajv-formats`, and `@types/node` are optional peer dependencies. A production install
+is the package alone, about 5.3 MB instead of 12.3 MB.
+
+| You | Install |
+| --- | --- |
+| Compile TypeScript for Node | `npm install --save-dev @types/node` |
+| Write schemas with zod | Nothing more: the package uses the zod your schema came from |
+| Check output against a JSON Schema object | `npm install ajv ajv-formats` |
+
+A JSON Schema response format without ajv fails with a `ResponseFormatError` that says what to
+install. A zod shape is checked through each field's own `safeParse`.
+
+The request check in the guardrails, `SchemaValidator`, no longer uses zod. It reports the same
+fields by the same paths; the wording of its findings changed.
+
+## A response's `estimatedCost` is removed
+
+The formatted string on a response's metadata is gone. 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. A custom provider that set the
+string should drop it; `buildMeta()` fills `usage` and `cost`.
+
+## 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 removes it, and the `Modality` type with it. Every entry declares `inputModalities` and
+`outputModalities`, and both are required.
+
+```ts
+// Before
+models: { registry: { 'my-model': { modalities: ['text', 'vision'], /* … */ } } }
+
+// After
+models: { registry: { 'my-model': { inputModalities: ['text', 'image'], outputModalities: ['text'], /* … */ } } }
+```
+
+| 1.x value | 2.0 |
+| --- | --- |
+| `text` | `text` in both lists |
+| `vision` | `image` in `inputModalities` |
+| `image` | `image` in `outputModalities` |
+| `audio`, `video`, `pdf` | the same name in `inputModalities` |
+
+In routing requirements, replace `modalities` with `inputModalities` or `outputModalities`.
+`modalitiesOf()` still reads both lists, and now requires both.
+
+## Checkpoints are version 2
+
+A checkpoint 2.x writes has a `version` of 2, an `id`, its `tasks` always spelled out, and every
+pending question in `interrupts`. The single `interrupt` field is gone.
+
+```ts
+// Before
+const question = checkpoint.interrupt;
+
+// After
+const [question] = checkpoint.interrupts;
+```
+
+Threads stored by 1.x keep working. Both bundled checkpointers read version 1 for the whole 2.x line,
+so a thread left waiting resumes after the upgrade.
+
+| You | What to do |
+| --- | --- |
+| Read checkpoints through a graph | Nothing: `state()` and `history()` return version 2 |
+| Wrote your own `GraphCheckpointer` | Its `get()` and `history()` may return either version, typed `StoredGraphCheckpoint`; the graph reads both |
+| Read a store directly | Pass what you read to `migrateCheckpoint()` |
+| Build a checkpoint by hand | Use `toCheckpoint()`, which fills in the version, id, tasks, and questions |
+| Named `GraphCheckpointV2` | It still compiles; it is now another name for `GraphCheckpoint` |
+
+## Options that were never read are removed
+
+These were accepted and ignored, and warned once per process since they were deprecated. The codemod
+lists each one it finds.
+
+| 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. Approval before a tool runs is
+`interruptOn` on `createAgent()`.
+
+## `ImageManagerConfig` is removed
+
+It was another name for `ImageConfig`. The codemod renames the import and keeps your local name.
+
+## Pipeline step names are a closed list
+
+`PipelineStepName` lists the built-in stages only, so a `switch` over it can be exhaustive. A step you
+add with `use()` is recorded as `customStep`, with its own name in `custom`.
+
+```ts
+// Before
+const mine = response.meta.pipeline?.steps.find((step) => step.name === 'enrich');
+
+// After
+const mine = response.meta.pipeline?.steps.find((step) => step.custom === 'enrich');
+```
+
+The trace's `auditLog` step is gone: auditing is the lifecycle's `audit` stage. `authorize` and
+`audit` appear when a lifecycle has work to do, and `reconcileCost` appears on every response.
+Metrics for a custom step keep its own name as their `step` label.
+
+`PipelineContext`, `PipelineMiddleware`, `PipelineStep`, `PipelineHooksConfig`, `PipelineConfig`, and
+`PipelineRunner` are generic over the request and the response. Both default to a completion's, so
+existing code compiles unchanged.
+
+## Streams open on their first read
+
+`ai.stream()` returns at once. Authorization, the rate limit, guardrails, routing, and the budget run
+when the stream is first read, so their errors come out of the loop:
+
+```ts
+// Before: a blocked request threw here
+const stream = ai.stream(request);
+
+// After: it throws from the loop
+try {
+  for await (const chunk of ai.stream(request)) render(chunk);
+} catch (error) {
+  // NexusSecurityError, NexusRateLimitError, OperationDeniedError, BudgetExceededError, …
+}
+```
+
+Streams now get what completions always had. They are audited and counted, the cost budget and the
+circuit breaker apply, and the `done` chunk carries the request id and a cost priced on the routed
+model.
+
+## Every call runs through the lifecycle
+
+Completions, streams, embeddings, voice, telephony, images, realtime sessions, graphs, agents, jobs,
+and batches share one [lifecycle](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/lifecycle.md).
+Nothing has to change in your code, but what the lifecycle records looks different:
+
+| What | 1.x | 2.0 |
+| --- | --- | --- |
+| Metric labels | `model`, or `provider` and `model`, per family | `family`, `operation`, `provider`, and `model` for every family |
+| The image family's label | `family=images` | `family=image` |
+| Audit event family | in `metadata.family` | `family` and `operation` on the event |
+| A call that fails after it starts | No event after `request` | An `error` event |
+| A blocked request | `blocked`, with `metadata.findings` | `blocked`, with `metadata.error` and `metadata.findings` |
+| `response.meta.requestId` | An id the adapter made up | The operation's id, the same on its audit events |
+| A cache hit | Not audited or counted | Audited, counted, and seen by `onFinish` |
+| A context-window summary | An unrecorded model call | Its own `summarize` operation |
+| `getCall()`, `listPhoneNumbers()`, `updatePhoneNumber()` | Called directly | Rate-limited and audited like `createCall()` |
+
+So check three things:
+
+- dashboards and alerts that match an exact label set;
+- audit sinks that read `metadata.family`, or that expect no event after a failed `request`;
+- rate limits, which now also count streams and the telephony reads above.
+
+To use the lifecycle, set `lifecycle` on the client: an `authorize` callback, a shared `budget`, and
+`hooks`. Pass `ai.lifecycle` to graphs, agents, workflows, realtime sessions, queues, and batches to
+make their runs operations of the client too.
+
+## Responses are priced on the routed model
+
+The client now prices each response on the model the request was routed to, as the registry names
+it. Providers often answer with a dated snapshot name the registry does not file. In 1.x, pricing on
+that echo cost the call nothing, so OpenAI responses could show a cost of 0, and so could Groq, Mistral,
+DeepSeek, and Cohere models filed under a prefix. Expect those costs to be priced in 2.0, and budgets
+to count them. A charge the provider reports, with `basis: 'reported'`, is kept as it is.
+
+## The model registry is current
+
+The bundled registry was checked against each provider's documentation on 2026-10-02.
+
+- **Shut-down models are gone.** So are four names 1.x invented that no provider served:
+  `claude-sonnet-5-0`, `claude-haiku-5-0`, `claude-fable-5-0`, and `gemini-3.5-pro`. The codemod lists
+  each one it finds, with what to use instead.
+- **Models with an announced shutdown stay,** marked `deprecated`. Their notes give the date and the
+  replacement, and an alias that resolves to one is deprecated too.
+- **Intent aliases point at current models.** For example, `anthropic/best` is `claude-fable-5-1`,
+  `openai/fast` is `gpt-6-luna`, and `deepseek/best` is `deepseek/deepseek-v4-pro`. Pin the resolved
+  model when a run must be reproducible.
+- **Prices moved both ways.** GPT-5.6 and Mistral Large 3 cost less. Gemini 3.5 Flash costs more than
+  1.x said, and the Gemini 3.6 to 3.8 Flash prices double on 2027-01-01.
+
+`describeModel()` shows what a name resolves to and when its entry was verified.
+
+## Claude 4.6 onward think adaptively
+
+From the 4.6 generation on, Claude takes adaptive thinking and an effort level, not a thinking budget.
+After 4.6 a budget is rejected, so 1.x requests with `reasoning` failed on those models. 2.0 sends what
+each model accepts, and the [core guide](docs/core.md#reasoning) has the details. Nothing changes in
+your code. From 4.7 on, Claude also rejects a non-default `temperature` or `topP`, so the client
+drops one and records a capability warning.
+
+## Tool calls reach providers whole
+
+In 1.x the OpenAI, Anthropic, and Google adapters dropped a conversation's tool calls and the ids that
+link results to them. A real tool loop could fail on its second turn. 2.0 sends both the way each API
+expects. Nothing changes in your code.
+
+Two things are new beside it. A tool can return `toolOutput()`, whose text, images, and asset
+references go back as the tool message itself. And a model that produces images returns them on
+`response.assets`.
+
+## For provider authors
+
+The provider contracts only grew:
+
+- `BaseProvider.complete()` and `stream()` take a second, optional `ProviderCallContext`;
+- voice and telephony provider methods take it too;
+- `ImageProviderCallContext`, `EmbeddingProviderCallContext`, and `BatchProviderCallContext` extend it;
+- `FamilyTelemetry.run()` hands its function the context, and takes an optional settle function.
+
+A provider written for 1.x compiles unchanged.
+
+## Runtime
+
+2.0 runs on Node 22 and newer.

package/README.md

@@ -5,14 +5,16 @@ workflows that run branches in parallel and survive a restart, retrieval over an
 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
-and installs no third-party package at all.
+Import only what you use. The root import is the client and nothing else, and every other capability
+has its own entry point with a size budget CI enforces; [the packaging guide](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/packaging.md)
+publishes what each one costs. The package has no required dependencies: a graph-only application
+loads 51 KB, and installs nothing but this package.
 
 - NPM: https://www.npmjs.com/package/nexus-ai-pro
 - GitHub: https://github.com/mkhitar-abrahamyan/nexus-ai
 - Contributing, testing, and release procedure: [CONTRIBUTING.md](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/CONTRIBUTING.md)
 - Delivered work and what is planned next: [ROADMAP.md](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/ROADMAP.md)
+- For AI assistants: [llms.txt](https://raw.githubusercontent.com/mkhitar-abrahamyan/nexus-ai/main/llms.txt) indexes every guide, and [llms-full.txt](https://raw.githubusercontent.com/mkhitar-abrahamyan/nexus-ai/main/llms-full.txt) holds them all in one file
 
 ## Install
 
@@ -32,6 +34,14 @@ Install only the provider SDKs your app uses. The OpenAI SDK also powers OpenAI-
 npm install openai @anthropic-ai/sdk ollama
 ```
 
+Everything else is optional too. Add what your code needs:
+
+| Package | When |
+| --- | --- |
+| `@types/node` | A TypeScript project on Node. The client, graphs, and the lifecycle compile without it. |
+| `zod` | You write schemas with zod. The package uses the zod your schema came from. |
+| `ajv`, `ajv-formats` | A response format checks output against a JSON Schema object. |
+
 The Google Gemini provider uses Node.js `fetch`, so it does not need an extra SDK.
 Realtime transports use injected or platform WebRTC, WebSocket, and `fetch` interfaces and do not
 require the OpenAI SDK.
@@ -105,6 +115,9 @@ You can still pass a plain `NexusAIConfig` to `new NexusAI(...)` when you want f
 - 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
 - build persistent realtime voice agents with interruption, live tools, and normalized conversation state
+- authorize, budget, audit, and observe every call of every family in one place, with hooks that see
+  each one finish
+- pass images a tool made back to the model by reference, never as base64 text
 - keep TypeScript types around every request and response
 
 ## Guides
@@ -115,6 +128,7 @@ from the doc comments. The guides live in the repository, so these links go to G
 | Guide | Covers |
 | --- | --- |
 | [The client](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/core.md) | Requests, context windows, token optimization, cost checks, reasoning, prompt caching, streaming |
+| [The lifecycle](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/lifecycle.md) | Authorization, a shared budget, hooks, audit, and metrics for every call of every family |
 | [Providers and routing](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/providers.md) | The twelve completion providers, routing and failover, the model registry |
 | [Guardrails](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/security.md) | Injection, PII, secrets, schema validation, output redaction |
 | [Graphs](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/graphs.md) | Parallel branches, interrupts, checkpoints, time travel, subgraphs, caching, diagrams |
@@ -224,10 +238,17 @@ Shipped so far:
 - 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.
+  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;
+- 2.0 consolidation: one lifecycle for every call of every family, a shared spend budget, a root
+  import that holds only the client, no required dependencies, and a model registry checked against
+  every provider.
+
+Upgrading from 1.x: `npx nexus migrate src --write` moves your imports, and
+[MIGRATING.md](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/MIGRATING.md) covers the rest.
+Next, the image family leaves experimental once recorded live conformance passes on all three
+backends.
 
 ## Before Production
 

package/dist/agent/create-agent.d.ts

@@ -1,3 +1,4 @@
+import type { OperationLifecycleLike } from '../types/lifecycle.js';
 import { type CompiledGraph } from '../graph/graph.js';
 import type { GraphCheckpointer, NodeContext } from '../types/graph.js';
 import type { CompletionRequest, Message, ToolDefinition } from '../types/messages.js';
@@ -102,6 +103,11 @@ export interface CreateAgentOptions {
     responseFormat?: CompletionRequest['responseFormat'];
     /** Application data sent with every model request. */
     metadata?: Record<string, unknown>;
+    /**
+     * Runs every invocation as one operation of a client's lifecycle, labelled `agent`: pass
+     * `ai.lifecycle`. Its model calls are operations of their own.
+     */
+    lifecycle?: OperationLifecycleLike;
 }
 declare const agentChannels: () => {
     messages: import("../types/graph.js").Channel<Message[]>;