nexus-ai-pro 2.1.0 → 2.3.0

package/API_STABILITY.md

@@ -41,6 +41,83 @@ 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.3 stage (2.3.0)
+
+Everything 2.3 adds is stable from the start and additive: no default changes meaning.
+
+- `ToolDefinition.capabilities` and the capability grammar; `permissionPolicy()`, `PermissionPolicy`,
+  `PermissionRules`, `PermissionRequest`, `PermissionVerdict`, `PermissionDecision`,
+  `PermissionPolicyLike`, `parseCapability()`, `capabilitiesOf()`, `isSensitiveCapability()`, and
+  `normalizePath()` (`nexus-ai-pro/agent/permissions`); `CreateAgentOptions.permissions`;
+- the sandbox contract: `Sandbox`, its option, result, and isolation types, `sandboxTools()`,
+  `runSandboxConformance()` and its report types, `SandboxPathError` (`nexus-ai-pro/agent/sandbox`).
+  `processSandbox()` is a development reference and may change; conformance checks may be added;
+- `NodeOptions.effects` and `interrupts`, `CompileOptions.tools`, `GraphToolDescription`, and the lint
+  codes `SENSITIVE_TOOL_WITHOUT_APPROVAL`, `UNDECLARED_TOOL_CAPABILITIES`, and
+  `SIDE_EFFECT_BEFORE_INTERRUPT`;
+- `nexus-ai-pro/agent/middleware` and every middleware and option type on it;
+  `AgentMiddleware.wrapModelCall`, `AgentMiddlewareContext`, `AgentModelCallContext`, the third
+  argument of `wrapToolCall`, `next(call)`, and `AgentStopReason` `'stopped'`. The PII patterns
+  may be tightened in a minor release to cut false positives, and new `PiiKind` members may be
+  added;
+- `nexus-ai-pro/server/auth`: `jwtAuth()`, `apiKeyAuth()`, `trustedProxyAuth()`, `anyAuth()`,
+  `createJwtVerifier()`, `hashApiKey()`, `JwtError` and its codes, and every option type. New
+  `JwtAlgorithm` and `JwtErrorCode` members may be added;
+- `Principal.roles`, `method`, and `claims`; `GraphRunOptions.principal`, `NodeContext.principal`,
+  `WorkflowRunOptions.principal`, and `WorkflowContext.principal`; `ToolContext` and the second
+  argument of `ToolDefinition.execute`; `AgentMiddlewareContext.principal` and
+  `PermissionRequest.principal`. A checkpoint's `metadata.userId` is recorded when a run has a
+  principal with a subject;
+- `SparseRetriever`; `PostgresKeywordIndex` and `keywordIndexMigrations()`
+  (`nexus-ai-pro/postgres/fulltext`); `ElasticsearchKeywordIndex` and `ElasticsearchError`
+  (`nexus-ai-pro/rag/elasticsearch`); and every reranker and option type on
+  `nexus-ai-pro/rag/rerankers`. The default endpoints of hosted rerankers follow their providers'
+  current API versions;
+- `nexus-ai-pro/rag/pipeline`: `createIngestionPipeline()`, `ingestionExecutor()`, and their types.
+  The manifest's layout under `['nexus', 'ingestion', <name>]` is stable: a later release reads a
+  manifest an earlier one wrote;
+- `nexus-ai-pro/deep-agent`: `createDeepAgent()`, `DeepAgentOptions`, `DeepSubagent`, and
+  `DeepSkill`, and the names and arguments of the tools it gives the model (`write_todos`,
+  `delegate`, `load_skill`, `edit_file`). The wording of its system prompt may change in any release.
+
+## 2.2 stage (2.2.0)
+
+Everything 2.2 adds is stable from the start and additive: no default changes meaning.
+
+- versioned migrations: `SchemaMigration`, `AppliedMigration`, `MigrationStatus`, `MigrationResult`,
+  `SchemaMigrationError`, `migrationChecksum()`, `applyPostgresMigrations()`,
+  `postgresMigrationStatus()`, `postgresMigrations()`, `PostgresMigrateOptions`, every adapter's
+  `…Migrations()`, and the SQLite twins (`nexus-ai-pro/postgres`, `nexus-ai-pro/postgres/migrations`,
+  `nexus-ai-pro/sqlite`, `nexus-ai-pro/sqlite/migrations`). A migration, once released, never
+  changes; later releases add versions. `migrate()` now resolves to a `MigrationResult` instead of
+  nothing;
+- `nexus db status` and `nexus db migrate`, and `nexus db sql --record`;
+- `RedisOperationStoreOptions.index` and `reindex()`;
+- `CircuitBreakerConfig.shareObservations`, `CircuitStateStore.observe()`, `CircuitObservation`,
+  `CircuitWindow`, and `CircuitSnapshot.shared`;
+- `PostgresRollupStore` (`nexus-ai-pro/postgres/rollups`);
+- the tenant model (`nexus-ai-pro/tenancy`): every `tenant…()` view, `tenantScope()`,
+  `TenantAssetStore`, `TenantStores`, `assertTenantId()`, `TenantIdError`, and `TENANT_NAMESPACE`.
+  The prefix a view stores names under (`tenant/<id>/`) is part of the contract and does not change
+  within 2.x; `GraphRunOptions.tenantId`, `NodeContext.tenantId`, the `tenantId` options of `state()`,
+  `history()`, `fork()`, and `updateState()`, `OperationRecord.tenantId`,
+  `OperationSubmitOptions.tenantId`, `OperationStoreFilter.tenantId`, `RateLimitedRequest.tenantId`,
+  and `rateLimit.key: 'tenantId'`;
+- `CacheConfig.namespace`, `CacheNamespace`, `CacheOutcome` and `ResponseMeta.cache`,
+  `CompletionRequest.responseCache`, `MemoryCache.lookup()`, and the `scope` of `SemanticCache`'s
+  `get()` and `set()`;
+- `diagnose()` and its types (`nexus-ai-pro/doctor`), and `nexus doctor`. Checks may be added in a
+  minor release; a check's id and what makes it fail do not change within 2.x;
+- workflow steps' `timeout`, `onError`, `StepTimeout`, `StepFailure`, `StepRecovery`,
+  `StepContext.heartbeat()`, `WorkflowOptions.stepDefaults`, `WorkflowRunOptions.control` and
+  `tenantId`, `WorkflowContext.tenantId`, and `WorkflowStepTimeoutError.kind`;
+- `RunHandOffError`, `AssistantRunContext.saveProgress()` and `progress`.
+
+Three races are closed rather than added: a busy thread is claimed atomically, and the in-memory and
+Redis operation stores refuse a second record under a held idempotency key, as the SQL stores
+already did. The semantic cache no longer matches across tenants, and a failing response cache no
+longer fails a request.
+
 ## 2.1 stage (2.1.0)
 
 Everything 2.1 adds is stable from the start and additive: no default changes meaning.

package/CHANGELOG.md

@@ -4,6 +4,289 @@ Notable changes to this project are recorded here. The format follows [Keep a Ch
 
 ## [Unreleased]
 
+## [2.3.0] - 2026-10-06
+
+Agents that act safely, on production retrieval.
+
+### Added
+
+- **Capabilities and permission policies.** A tool declares what each call does —
+  `filesystem:write:<path>`, `network:<host>`, `shell:<command>`, `code`, or an effect of the
+  application's own — as a list or a function of its arguments. `permissionPolicy()`, on the new
+  `nexus-ai-pro/agent/permissions`, grants filesystem globs, network hosts, and shell command
+  prefixes, and decides each call: allow, deny, or ask. Paths are normalized before any grant sees
+  them, and a command that chains, pipes, or substitutes is never granted by a prefix.
+  `createAgent({ permissions })` enforces it before a tool runs: a denied call never runs, an `ask`
+  interrupts as `interruptOn` does, and arguments an approver edits are decided again.
+- **A sandbox contract**, on the new `nexus-ai-pro/agent/sandbox`: the `Sandbox` interface a
+  container, VM, or hosted interpreter fills; `sandboxTools()`, whose calls declare exactly the
+  command or path they use; `runSandboxConformance()`, which proves any sandbox against the
+  contract; and `processSandbox()`, a reference for development that is never a security boundary
+  and says so.
+- **The linter reads capabilities.** `SENSITIVE_TOOL_WITHOUT_APPROVAL` reports a tool that writes, runs
+  commands or code, or reaches the network with neither approval nor a policy;
+  `UNDECLARED_TOOL_CAPABILITIES` a tool whose effects cannot be judged; and
+  `SIDE_EFFECT_BEFORE_INTERRUPT` a node that declares `effects` and `interrupts`. An agent's graph
+  describes its tools for it.
+- **A middleware catalog**, on the new `nexus-ai-pro/agent/middleware`, each a separate import:
+  `modelRetry()`, `modelFallback()` (to another model or another client), `dynamicModel()`,
+  `toolRetry()` (which by default repeats only a call that cannot have changed anything),
+  `toolSelector()` (by rule, embedding similarity, or both), `contextEditor()` (clears old tool
+  results in batches, so a prompt cache keeps working), `piiMiddleware()` (validated card numbers
+  and IBANs; redact, mask, hash, or block), `humanApproval()` (per call, in band or out of band),
+  `modelCallLimit()` (per run and per thread, the thread count shared through the store), and
+  `filesystemContext()` (instruction files in, large results out to a file). The three existing
+  middleware are there too.
+- **A wider middleware seam.** `wrapModelCall` wraps the model call itself, and may call `next()`
+  again to retry or fall back. Every hook receives an `AgentMiddlewareContext`: the state, the
+  store, the thread and tenant, the run's signal, and `interrupt()`. `context.stop()` ends a run
+  with an answer and the new `stopReason: 'stopped'`. A `wrapToolCall` can pass `next()` changed
+  arguments, which the permission policy decides again.
+- **Server authentication**, on the new `nexus-ai-pro/server/auth`. It is built on Web Crypto, with no
+  dependency:
+  - `jwtAuth()` takes an identity provider's key set (cached, and refetched when a token names a new
+    key), a public key, or a shared secret, and checks issuer, audience, expiry, and age. It refuses
+    `alg: none` and key confusion, and requires an audience with a key set.
+  - `apiKeyAuth()` compares keys by their SHA-256 hash, from `hashApiKey()`.
+  - `trustedProxyAuth()` refuses to exist without proof that the proxy sent the request.
+  - `anyAuth()` combines hooks.
+  - `createJwtVerifier()` verifies tokens outside the server.
+- **One Principal, everywhere a run goes.** It gains `roles`, `method`, and `claims`.
+  - Graph and workflow runs take a `principal`, which nodes read as `context.principal`. Its tenant
+    becomes the run's, and its subject is recorded on every checkpoint and in the run's trace.
+  - `graphAssistant()` passes the authenticated caller on.
+  - Tools receive a `ToolContext` as the second argument of `execute`: the principal, the thread
+    and tenant, the run's signal, and the tenant's store.
+  - Middleware and permission policies see the principal too.
+- **Sparse retrieval as a contract.** A `SparseRetriever` is keyword search that takes writes, so it
+  fuses with vector search and stays in step with a vector store. `KeywordIndex` is one. Two more
+  ship:
+  - `PostgresKeywordIndex` (`nexus-ai-pro/postgres/fulltext`) uses Postgres full-text search, with a
+    GIN index and ranking in the database. With `shared`, it searches a pgvector table through a
+    generated column, so hybrid search keeps one copy of the data.
+  - `ElasticsearchKeywordIndex` (`nexus-ai-pro/rag/elasticsearch`) works with Elasticsearch or
+    OpenSearch over the REST API, with no client library.
+- **Rerankers**, on the new `nexus-ai-pro/rag/rerankers`, with no SDK:
+  - `cohereReranker()`, `voyageReranker()`, and `jinaReranker()` for hosted APIs;
+  - `teiReranker()` for a self-hosted cross-encoder;
+  - `httpReranker()` for any other API;
+  - `crossEncoderReranker()` for a model run in process.
+- **Durable ingestion**, on the new `nexus-ai-pro/rag/pipeline`. `createIngestionPipeline()` keeps a
+  manifest in any `Store`: each document's content version, its chunking, the embedding model, and
+  each chunk's version. A run:
+  - embeds only new and changed chunks; chunks are named by their text, so one that only moved keeps
+    its embedding;
+  - deletes the chunks and documents that are gone;
+  - keeps keyword indexes in step;
+  - writes to the stores before the manifest.
+
+  `ingestionExecutor()` runs it as a durable operation, and a retry starts at the document the
+  failed attempt stopped on.
+- **A deep-agent preset**, on the new `nexus-ai-pro/deep-agent`. `createDeepAgent()` is
+  `createAgent()` composed with:
+  - a plan, kept in the transcript;
+  - a sandboxed workspace, with `edit_file` for precise changes and commands granted by name;
+  - helpers behind one `delegate` tool, which never get a tool that needs approval;
+  - skills loaded on demand;
+  - instruction files and context offloading;
+  - context editing, optional tool selection, and a default permission policy.
+
+  It returns the same compiled graph as any agent; it is not a new engine.
+- `processSandbox()` loads Node's modules when first used, so `nexus-ai-pro/agent/sandbox`, and a
+  deep agent over a container sandbox, import on any runtime.
+
+### Fixed
+
+- `MemoryStore` swept every item for expiry on every write, so writing n items took time
+  proportional to n². It now sweeps only once an item has a time to live, and at most once a second.
+  Expired items were already hidden from reads.
+
+- `limitToolCalls()` counted calls in memory shared by every run of an agent, so one thread's calls
+  used up another's limit, and the count never reset. It now counts per run from the transcript.
+- A subgraph run through `asNode()` now runs for its parent's tenant, so its store is the tenant's
+  view, as the parent's is.
+- `sandboxTools()` file tools accept a path that names the mount, such as `/workspace/notes.txt`,
+  as well as one relative to it, and say in their descriptions which to use.
+
+### Proof
+
+- In a real agent tool loop, a write outside the workspace and a request to an unlisted host are
+  refused before their tools run, and a granted command that needs approval waits for a person.
+- The process sandbox passes the conformance suite, and a sandbox that leaks the host's environment
+  and writes outside its root fails exactly those two checks.
+- An agent over 150 tools completes 40 tasks, a third of them needing two tools, with
+  `toolSelector()` at equal quality: every task succeeds either way. Input tokens per task fall from
+  about 64,000 to about 5,200, and latency by about 70%: the model's time computed from
+  each request's size, plus the agent's own measured time. Two experiments, reported by
+  `compareExperiments()`, show it.
+- Each middleware is proved in a real agent loop. For example:
+  - a charge that timed out is never retried;
+  - an approver who raises a refund past what the policy allows has the edit refused;
+  - two agents sharing a store share one thread budget;
+  - a 45,000-character tool result reaches the transcript as a preview and a file.
+- A JWT from a test identity provider is verified against its key set and reaches an agent's tool
+  call as a `Principal` with its subject, tenant, roles, and scopes.
+  - The tool's writes land in that tenant's view of the store.
+  - The checkpoint records who ran the step.
+  - Another tenant's token gets 404 for the thread.
+  - Expired, wrong-audience, wrong-issuer, unsigned, and forged tokens are refused.
+  - The provider rotates its key with one refetch.
+- On the stored support dataset, on real Postgres with full-text search and pgvector, hybrid retrieval
+  beats vector-only: recall@5 0.71 → 0.97 and mean reciprocal rank 0.51 → 0.71, both with a 95%
+  interval above zero. A hosted reranker and a local cross-encoder, compared in the same experiment,
+  each lift mean reciprocal rank to 0.97. One contract test runs against all four keyword indexes.
+- An ingestion of 100,000 documents dies halfway inside a durable operation. Its retry starts at the
+  document the first attempt stopped on, and embeds no chunk that had finished. A second run after
+  ten documents are edited embeds exactly ten chunks and deletes their old versions.
+- A deep agent completes a multi-step task on a fixture repository inside the reference sandbox. It
+  plans, runs the failing test, reads and edits the bug, verifies the fix, has a helper review it,
+  loads a skill, and records the change; the test then passes outside the agent. Along the way, a
+  30,000-character log is offloaded to a file. The default policy refuses an unlisted command, a
+  chained command, a write outside the workspace, and an ungranted tool.
+
+## [2.2.0] - 2026-10-05
+
+Production scale and safe upgrades. Every database schema is versioned, so an upgrade applies only
+what changed, and a worker of the previous release keeps running beside the new one. A claim costs
+the same however long the queue is, routing costs the same however many models are configured, a
+circuit breaker counts every worker's failures, and work that several replicas race for is taken by
+exactly one. One tenant model reaches every store, and a deployment can check itself. Nothing
+changes until it is opted into, except races and leaks that are now closed.
+
+### Added
+
+- **Versioned migrations.** Every Postgres and SQLite adapter's schema is a list of numbered
+  `SchemaMigration`s, recorded in `nexus_schema_migrations` with a checksum. `migrate()` applies what
+  is pending, under a lock that holds through a connection pool, and refuses a migration whose
+  statements changed after it ran (`SchemaMigrationError`). Version 1 is the schema 2.0 created, so an
+  existing database is recognized as it is. `applyPostgresMigrations()`, `postgresMigrationStatus()`,
+  `postgresMigrations()`, and their SQLite twins work on any list, from `nexus-ai-pro/postgres`,
+  `nexus-ai-pro/sqlite`, and the new `nexus-ai-pro/postgres/migrations` and
+  `nexus-ai-pro/sqlite/migrations`. `PostgresMigrateOptions.transaction` runs each migration in one
+  transaction on one connection, and `postgresMigration({ record: true })` records what the script
+  creates.
+- **`nexus db status` and `nexus db migrate`**, through a module that exports your own client:
+  applied, pending, changed, and newer migrations, `--check` for a deploy step, and `--dry-run`.
+- **Indexed dispatch.** Version 2 of the Postgres and SQLite operation schemas indexes queued work by
+  age, so a claim reads the oldest few rows instead of sorting the queue, and version 3 by tenant.
+  `RedisOperationStore` takes `index: true`: queued work in a sorted set by age and leased work in one
+  by lease expiry, kept in the same Lua call as the record, with `reindex()` to index what is already
+  stored. A claim reads the same handful of records with 100,000 operations queued as with 1,000.
+- **A circuit breaker that counts across workers.** `shareObservations: true` adds each worker's
+  calls to a rolling window in the shared store, so nine failures over three workers count as nine
+  and the circuit opens on all of them. Checks stay synchronous; a worker learns the shared count on
+  its next sync. `CircuitStateStore.observe()` is implemented by the memory, Redis, and Postgres
+  stores, and `CircuitSnapshot.shared` reports the window.
+- **`PostgresRollupStore`**, on the new `nexus-ai-pro/postgres/rollups`: hourly rollups beside the
+  traces, summed in one statement so two workers adding to one hour both count.
+- **A routing index.** The auto-router plans once per configuration — candidates, allow and deny
+  lists, capability requirements as bitmasks, and strategy scores — and a request pays only for open
+  circuits and health. Over 1,000 models a warm route takes about 15 µs at p50 and 23 µs at p99.
+- **One tenant model**, on the new `nexus-ai-pro/tenancy`: a tenant's view of every store —
+  `tenantStore()`, `tenantTraceStore()`, `tenantOperationStore()`, `tenantPromptStore()` (and with it
+  the context hub), `tenantDatasetStore()`, `tenantExperimentStore()`, `tenantVectorStore()`,
+  `tenantCache()`, `tenantAssetStore()`, `tenantRollupStore()` — each implementing the store's own
+  contract over any backend, and `tenantScope()` for all of them at once. Graph runs take a
+  `tenantId`: recorded on every checkpoint, read as `context.tenantId`, scoping `context.store`, and
+  refusing another tenant's resume, continue, fork, or edit. `graphAssistant()` passes the
+  principal's tenant. Operations carry `tenantId`, and `OperationStoreFilter.tenantId` narrows queue
+  reads. Model calls are traced with their `tenantId`, so rollups count model spend per tenant, and
+  `rateLimit.key: 'tenantId'` gives each tenant its own share of a client's rate limit.
+- **Cache namespaces and outcomes.** `cache.namespace` keeps responses apart by tenant, environment,
+  model revision, and context version. Every response reports `meta.cache` — `hit`, `miss`, `stale`,
+  `bypass`, or `error`, with its layer and reason — and the request's trace records it.
+  `CompletionRequest.responseCache` skips the cache (`bypass`) or refreshes it (`refresh`).
+- **`nexus doctor`**, and `diagnose()` on the new `nexus-ai-pro/doctor`: the Node.js version,
+  optional packages, provider credentials (by name only), database connectivity and pending or
+  changed migrations, Redis, lapsed leases and a stalled queue, the registry's age, stale provider
+  health, and process-local stores behind several replicas. It exits 1 on a failure, or with
+  `--strict` on a warning.
+- **Runtime budgets.** `npm run bench:runtime`, part of the release gate, times fourteen paths — graph
+  creation, a 1,000-node compile, `Send`, checkpoints, routing at three registry sizes, a
+  20-middleware agent, traces, the event stream, server event fan-out, claims, and cache lookups —
+  as ratios to a calibration loop, so a budget holds across machines, and checks that 100,000
+  checkpoints and 10,000 runs leave the heap where it was.
+- **Workflow steps have what graph nodes have.** `timeout: { runMs, idleMs }` with
+  `context.heartbeat()`, an `onError` that decides once retries run out — recorded as `recovered`,
+  so a resume repeats neither the step nor its recovery — `stepDefaults`, a `control` that drains
+  between steps and ends in `GraphDrainedError`, and `tenantId`. A workflow the agent server serves
+  is handed off on a drain like a graph.
+- **A function assistant hands its run off on a drain**: it checks `context.control?.draining`,
+  saves how far it got with `context.saveProgress()`, and throws `RunHandOffError`; the next worker
+  reads `context.progress` and carries on.
+
+### Changed
+
+- `migrate()` on every Postgres and SQLite adapter resolves to a `MigrationResult` instead of
+  nothing, records what it applied, and loads the migration runner only when called.
+- `nexus db sql` and `postgresMigration()` include the rollups table and the new indexes by
+  default; every statement stays idempotent.
+- The root import grew by 11 KB, to 336 KB, with the routing plan, cache outcomes, and linked
+  signals; `nexus-ai-pro/graph` by 5 KB, to 78 KB, with tenant runs; and
+  `nexus-ai-pro/graph/functional` by 6 KB, to 32 KB, with step timeouts, recovery, drain, and
+  tenants.
+
+### Fixed
+
+- **Two replicas could both start a run on one busy thread.** The busy check read and wrote
+  separately. A thread is now claimed through the operation store under a unique key with
+  compare-and-set, so exactly one run proceeds and the rest meet the busy policy. An `enqueue` start
+  still busy when `queueTimeoutMs` runs out is refused instead of running beside the other.
+- **Two submissions under one idempotency key could both run** on the in-memory and Redis operation
+  stores, which overwrote the key's owner. Both now refuse a second record under a key another record
+  holds, as Postgres and SQLite do, and Redis checks and writes in one Lua call.
+- A circuit breaker's calls recorded before its shared-state module finished loading were not
+  shared.
+- **Security: the semantic response cache answered one tenant with another's response** when their
+  questions were alike, because it compared every entry regardless of tenant. A semantic match is
+  now kept to the request's tenant and cache namespace.
+- A response cache that threw failed the request, and one that failed to store an answer failed it
+  after the provider had answered. Both are now reported in `meta.cache`, and the request goes on.
+- The auto-router rebuilt the model registry for every candidate on every request: over 1,000 models
+  a request took most of a second.
+- **Memory grew with every run that shared a signal.** `AbortSignal.any()`, which composed each task
+  attempt's signal, keeps a reference per call for as long as any source lives in Node 22, so a
+  server's or a worker's long-lived signal held about 5 KB per graph run, and every client operation
+  with a deadline held one too. Signals are now linked and released when their work ends; 10,000
+  runs leave the heap within 0.3 MB of where it started, down from 52 MB.
+
+### Proof
+
+- A database created by the published 2.0.0 package upgrades with 2.2's migrations, on Postgres and
+  SQLite, and a published 2.1.0 worker and a 2.2 worker drain one queue together, nothing run twice.
+- Ten workers race one thread, one idempotency key, one queue, one tenant's slots and budget, and one
+  circuit, on every shared store, and every invariant holds.
+- A Redis claim reads the same number of records at 1,000 and 100,000 queued; Postgres and SQLite
+  plan a claim through the age index with no sort.
+- The Redis stores' Lua runs for real in the tests, in a Lua VM over an in-memory Redis.
+- The routing index decides exactly as the published 2.1.0 router on 300 random configurations, and
+  a warm route over 1,000 models stays under 100 µs at p50 and 1 ms at p99.
+- A tenant-isolation suite runs against every storage adapter — memory, Redis, Postgres, SQLite, and
+  files — and fails on any cross-tenant get, list, search, delete, fork, resume, trace query, vector
+  search, or cache hit.
+- `nexus doctor` reports each misconfiguration a fixture deployment is seeded with — an old Node.js,
+  no credentials, an old registry, pending migrations, an unreachable Redis, a lapsed lease and a
+  stalled queue, stale health, and memory stores behind three replicas — and passes it once fixed.
+- A workflow and a function assistant are each drained on one worker and finished on the next, with
+  every step and every item run exactly once.
+
+### Not in this release, and why
+
+- **The migration lock is a row with a lease, not a session advisory lock.** A session lock does not
+  hold through a connection pool or a serverless driver, where each statement may reach another
+  connection; a lease row does, everywhere. Without a `transaction` function, statements run one at a
+  time, which is safe because every bundled statement is idempotent.
+- **The Redis dispatch index is opt-in**, since a 2.1 worker writes records without index entries;
+  `stats()` on Redis still reads every record.
+- **Consecutive failures across workers are counted as failures since any worker's last success.**
+  Calls are reported in batches, so two workers' failures and successes in the same second may be
+  ordered differently than they happened.
+- **Tenant views scope by prefix and stamp, not by a column**, so they work over every backend
+  unchanged; data written before a view was used is not the tenant's until it is copied under its
+  prefix.
+- **Runtime budgets compare ratios to a calibration loop**, which catches a cliff, not a 10% drift;
+  the tolerance is three times the recorded ratio.
+
 ## [2.1.0] - 2026-10-04
 
 Fault-tolerant graphs and crash-safe observability. A graph now chooses when its checkpoints are
@@ -1494,7 +1777,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/v2.1.0...HEAD
+[Unreleased]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.3.0...HEAD
+[2.3.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.2.0...v2.3.0
+[2.2.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.1.0...v2.2.0
 [2.1.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.0.0...v2.1.0
 [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

package/README.md

@@ -8,12 +8,12 @@ team can share.
 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 73 KB, and installs nothing but this package.
+loads 80 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)
+- 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
@@ -132,7 +132,8 @@ from the doc comments. The guides live in the repository, so these links go to G
 | [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 |
-| [Agents and tools](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/agents.md) | Graph-based agents with approvals and middleware, and the simple tool loop |
+| [Agents and tools](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/agents.md) | Graph-based agents with approvals, capabilities and permission policies, a sandbox contract, the middleware catalog, and the simple tool loop |
+| [The deep-agent preset](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/deep-agents.md) | Long, multi-step agents: a plan, a sandboxed workspace, helpers, skills, and a context that stays small |
 | [Long-term memory](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/memory.md) | Namespaced memory with semantic search, in memory or Redis |
 | [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 |
@@ -158,6 +159,7 @@ from the doc comments. The guides live in the repository, so these links go to G
 | [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 |
+| [Tenancy](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/tenancy.md) | One tenant model: a tenant's view of every store, tenant graph runs, and the isolation suite |
 | [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 |
@@ -200,7 +202,8 @@ npm run check:release
 
 `check` runs formatting and lint gates, source/test/example type checks, the build, unit and mock
 conformance tests, coverage thresholds, package import checks, and an external type-consumer test.
-`check:release` additionally verifies the dry-run tarball and a clean packed-package install.
+`check:release` additionally holds the scheduling and runtime budgets — speed against a calibration
+loop, and memory by retention — and verifies the dry-run tarball and a clean packed-package install.
 
 `npm run docs:check` fails when any public export, or any public member of an exported class,
 interface, or enum, has no doc comment, and `npm run docs:guides` fails when a guide does not name
@@ -216,8 +219,8 @@ npm run test:vectors:live
 
 ## Roadmap
 
-See [ROADMAP.md](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/ROADMAP.md) for what has
-shipped and what is planned. It is a design proposal, not a compatibility promise; the guarantees
+See [ROADMAP.md](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/ROADMAP.md) for what is
+planned, and [CHANGELOG.md](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/CHANGELOG.md) for what has shipped. It is a design proposal, not a compatibility promise; the guarantees
 live in [API_STABILITY.md](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/API_STABILITY.md).
 
 Shipped so far:
@@ -246,12 +249,19 @@ Shipped so far:
   every provider;
 - 2.1 fault tolerance and crash-safe observability: checkpoints written on your terms, recovery after
   retries, idle timeouts and a clean drain, traces that survive a crash and reach any OpenTelemetry
-  backend, one event stream, and dashboard rollups.
+  backend, one event stream, and dashboard rollups;
+- 2.2 production scale and safe upgrades: versioned database migrations, queue claims and routing
+  that cost the same at any size, a circuit breaker that counts across workers, one tenant model
+  across every store, and `nexus doctor` to check a deployment before it serves traffic;
+- 2.3 agents that act safely, on production retrieval: capabilities and permission policies, a
+  sandbox contract, a middleware catalog, server authentication with one principal on every run,
+  keyword search in Postgres and Elasticsearch with rerankers, durable ingestion, and a deep-agent
+  preset.
 
 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, 2.2 removes the scaling cliffs the guides document: versioned database migrations, indexed
-queue dispatch, a circuit breaker that counts across workers, a routing index, and one tenant model. The [roadmap](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/ROADMAP.md) lists the
+Next, 2.4 takes the experimental surfaces out of experimental with evidence, adds an adapter kit, and
+speaks the agent protocols beyond MCP from a portable kernel. The [roadmap](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/ROADMAP.md) lists the
 releases after it.
 
 ## Before Production

package/dist/agent/capabilities.d.ts

@@ -0,0 +1,39 @@
+import type { ToolDefinition } from '../types/messages.js';
+/**
+ * Capabilities: what a tool does to the world, written as strings a policy can decide on.
+ *
+ * | Capability | Means |
+ * | --- | --- |
+ * | `filesystem:read`, `filesystem:read:<path>` | Reads files, or one path |
+ * | `filesystem:write`, `filesystem:write:<path>` | Writes, creates, or deletes files |
+ * | `network`, `network:<host or URL>` | Opens a network connection, to a host when given |
+ * | `shell`, `shell:<command line>` | Runs a shell command |
+ * | `code` | Runs code it was given, as an interpreter does |
+ * | `<name>`, `<name>:<detail>` | Anything the application names, such as `payments:refund` |
+ *
+ * A tool that declares `capabilities: []` does nothing to the world; one that declares none at all
+ * is undeclared, and a policy decides on it as such.
+ */
+/** One capability, split into its parts. */
+export interface ParsedCapability {
+    /** `filesystem`, `network`, `shell`, `code`, or the application's own name. */
+    kind: string;
+    /** `read` or `write`, for the filesystem. */
+    access?: 'read' | 'write';
+    /** The path, host, command, or detail, when the capability names one. */
+    target?: string;
+}
+/** Splits a capability string into its kind, access, and target. */
+export declare function parseCapability(capability: string): ParsedCapability;
+/**
+ * The capabilities one call of a tool declares: its static list, or what its function computes from
+ * the call's arguments. `undefined` means undeclared — no list, or a function that threw — which is
+ * not the same as `[]`, a tool that declares it does nothing to the world.
+ */
+export declare function capabilitiesOf(tool: Pick<ToolDefinition, 'capabilities'> | undefined, args: Record<string, unknown>): string[] | undefined;
+/**
+ * Whether a capability is sensitive: anything but reading files. A pure tool declares
+ * `capabilities: []`; whatever it does declare, a write, a command, code, the network, or an
+ * effect of the application's own such as `payments`, changes the world or leaves the process.
+ */
+export declare function isSensitiveCapability(capability: string): boolean;

package/dist/agent/capabilities.js

@@ -0,0 +1,36 @@
+export function parseCapability(capability) {
+    const text = capability.trim();
+    const colon = text.indexOf(':');
+    const kind = (colon < 0 ? text : text.slice(0, colon)).toLowerCase();
+    const rest = colon < 0 ? undefined : text.slice(colon + 1);
+    if (kind === 'filesystem') {
+        if (!rest)
+            return { kind };
+        const [access, ...path] = rest.split(':');
+        const parsed = { kind };
+        if (access === 'read' || access === 'write')
+            parsed.access = access;
+        const target = parsed.access ? path.join(':') : rest;
+        if (target)
+            parsed.target = target;
+        return parsed;
+    }
+    return rest === undefined || rest === '' ? { kind } : { kind, target: rest };
+}
+export function capabilitiesOf(tool, args) {
+    const declared = tool?.capabilities;
+    if (!declared)
+        return undefined;
+    if (typeof declared !== 'function')
+        return [...declared];
+    try {
+        return [...declared(args)];
+    }
+    catch {
+        return undefined;
+    }
+}
+export function isSensitiveCapability(capability) {
+    const parsed = parseCapability(capability);
+    return !(parsed.kind === 'filesystem' && parsed.access === 'read');
+}