nexus-ai-pro 2.4.0 → 2.6.0

package/API_STABILITY.md

@@ -41,6 +41,127 @@ 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.6 stage (2.6.0)
+
+Everything 2.6 adds is stable from the start and additive.
+
+New and stable:
+- `ToolDefinition.stream`, `ToolContext.progress`, and `ToolBody`; `tool()` with `stream`. The
+  AG-UI event name `tool_progress`, and the `progress` and `callId` fields of a tool run's metadata;
+- `McpClient.callTool()`'s `progress` option, and `notifications/progress` from `McpServer`;
+- `AgUiOptions.stateDeltas`, `messagesSnapshot`, and `frontendTools`, and `AgUiPatchOperation`;
+- `CreateAgentOptions.toolSource` and `ToolSourceContext`; `ClientToolDefinition`, the `clientTools`
+  channel, and the `AgentStopReason` member `client_tools`;
+- the `step` member of `GraphEvent`;
+- on `nexus-ai-pro/protocols/a2a`: `A2aTaskStore`, `A2aTaskRecord`, `A2aTaskQuery`,
+  `MemoryA2aTaskStore`, `storeA2aTasks()`; `A2aServerOptions.store`, `pushNotifications`,
+  `extendedCard`, `pollMs`, and `onError`; `A2aPushOptions` and `A2aPushNotificationConfig`; the
+  methods `ListTasks`, `SubscribeToTask`, the four push notification config methods, and
+  `GetExtendedAgentCard`; the client's new methods, `A2aListTasksOptions`, and `A2aTaskPage`; and
+  the error codes `pushNotificationNotSupported` and `extendedCardNotConfigured`.
+
+- on `nexus-ai-pro/protocols/acp`: `AcpSessionStore`, `AcpSessionRecord`, `MemoryAcpSessionStore`,
+  `storeAcpSessions()`, `AcpOptions.sessions` and `editor`, `AcpEditorBridge`, `AcpConnection`,
+  `AcpClientCapabilities`, `session/load`, image and audio blocks, and the fourth argument of
+  `AcpOptions.input`;
+- `nexus-ai-pro/protocols/acp/editor`: `acpEditor()`, `AcpEditor`, `AcpEditorOptions`, and the tool
+  names `editor_read_file`, `editor_write_file`, and `editor_run_command`.
+
+An AG-UI run reports a node's tasks running side by side as one step, and finishes every step it
+started before `RUN_FINISHED` or `RUN_ERROR`. A2A `ListTasks` refuses a status that is not a task
+state, and reads `TASK_STATE_UNSPECIFIED` and `UNRECOGNIZED` as no filter.
+
+A streamed A2A task now reports its move to `TASK_STATE_WORKING` as a status update, before its
+other events.
+
+`GraphEvent` and `AgentStopReason` gain members, as the compatibility rules allow in a minor
+release. Code that switches over either exhaustively should handle the new ones.
+
+## 2.5 stage (2.5.0)
+
+Everything 2.5 adds is stable from the start and additive.
+
+New and stable:
+- `putIfVersion()`, optional on `Store` and `ServerStateStore`, and its implementations;
+  `Deployments.atomicChanges`; `ScalingSnapshot.atomicChanges`;
+- `nexus-ai-pro/postgres/tenancy`: `PostgresTenantUsage`, `PostgresTenantUsageOptions`,
+  `tenantUsageMigration()`, and `tenantUsageMigrations()`; the `tenancy` member of
+  `PostgresAdapter`;
+- `OperationStoreFilter.kinds`, `OperationStoreStats.queuedByKind`, `RevisionRequest.queued`,
+  `RevisionChoice.local`, `ScalingSnapshot.queuedByRevision`, and the
+  `nexus_server_runs_queued_by_revision` metric.
+
+- signing on `nexus-ai-pro/context-hub`: `ContextHubOptions.signer`, `keyring`, and `requireSignature`;
+  `ContextHub.verify()` and `ContextVerification`; `ContextBundle.signatures`; `ContextSignatureError`;
+  `generateContextKey()`, `ed25519Signer()`, `ed25519Keyring()`, `contextDigest()`, and the signing
+  types. The signed digest's format is `nexus-context-signature`, format version 1, and a later release
+  verifies it;
+- `metadata.context` on a traced model call;
+- on `nexus-ai-pro/server/deployments`, experimental with the rest of it: `BucketStrategy`,
+  `DeploymentRecord.bucketStrategy`, `RevisionedAssistantOptions.bucketStrategy`, the `bucketing`
+  change and `Deployments.bucketing()`, the strategy argument of `bucket()`; `recordRun()`,
+  `rollups()`, `flushRollups()`, `stats({ deployment })`, `DeploymentRollup`, `RevisionRollup`, and
+  `DeploymentsOptions.rollupMs`; `CanaryGuardOptions.from`. `ServerDeployments` gains an optional
+  `recordRun()`, and `RunManagerOptions.deployments`. The positions `fnv1a-v1` and `hash-v2` give a key
+  never change;
+- the doctor's `settings` check; `RedisOperationStore.indexed`; `Tracer.store` and
+  `Tracer.incremental`;
+- `nexus-ai-pro/evaluate/threads`, experimental: `simulatedUser()`, `scriptedUser()`,
+  `conversationTarget()`, `graphThreadAgent()`, `formatThread()`, `goalReached()`,
+  `goalCompletion()`, `turnCount()`, `turnScores()`, and their types. The score keys `goal_reached`,
+  `goal_completion`, `turns`, and `turn_score` are stable once the entry point graduates.
+
+The studio now refuses, as the compatibility rules allow for security: a change whose body is not
+`application/json`, with `415`; a body that is not a JSON object, with `400`; a body past
+`maxBodyBytes`, with `413`; and a list `limit`, `hours`, or `days` past its ceiling, with `400`. With
+accounts, only a bearer `Authorization` header stands in for the page token. The agent server refuses
+an assistant or revision named after a built-in property, such as `constructor`. Also stable from
+2.5: `StudioOptions.maxBodyBytes`, `Studio.routes` and `StudioRoute`, and
+`MemoryStudioJournalOptions.maxComments`.
+
+### Graduation
+
+Two more surfaces leave experimental status in 2.5, by the same checklist as in 2.4. Every test named
+here runs in CI.
+
+**Deployments** (`nexus-ai-pro/server/deployments`):
+
+| Requirement | Evidence |
+| --- | --- |
+| Conformance | Atomic changes on the memory server store and the memory, Redis, Postgres, and SQLite stores: `tests/atomic-deployments.test.ts`; routing, canaries, and guards: `tests/deployments.test.ts`, `tests/fair-canaries.test.ts`; revision pools: `tests/revision-pools.test.ts` |
+| Crash recovery | A change is one compare-and-set write, so a crash leaves the old record or the new one; a drained replica hands its runs to another: `tests/deployments.test.ts`. A replica that dies loses at most its last `rollupMs` of counts, which the guide states |
+| Concurrency | Ten replicas making mixed changes at once land in one linear history on every store: `tests/atomic-deployments.test.ts` |
+| Load | `deployments.route-canary` and `deployments.bucket` in `surface-budget.json` |
+| Tenant isolation | n/a: a deployment is an assistant's configuration, not a tenant's data. The runs it routes are operations, which are isolated: `tests/tenant-isolation.test.ts` |
+| Security | [Review](./SECURITY.md#deployments): four findings fixed, two documented limitations |
+| Upgrade | A 2.3 replica's deployment routes the same here, and every thread keeps its bucket: `tests/upgrade-previous-minor.test.ts` |
+| Soak | 50,000 route, admit, and release cycles, 500 replica lifecycles, and 20,000 runs counted and judged from rollups, with no timer left running |
+
+**The studio and its accounts** (`nexus-ai-pro-studio`):
+
+| Requirement | Evidence |
+| --- | --- |
+| Conformance | Every view over its sources, with and without accounts: `studio/test/studio.test.ts`, `studio/test/team.test.ts`, `studio/test/deployments.test.ts` |
+| Crash recovery | n/a: the studio keeps no state but its journal, which appends one line per entry and skips a line a crash cut short: `studio/test/security.test.ts` |
+| Concurrency | n/a: every change goes through its source's own API, where races are settled: prompt and bundle labels by compare-and-set, deployments by `putIfVersion()` |
+| Load | 500 signed-in reads within a budget relative to the machine: `studio/test/security.test.ts` |
+| Tenant isolation | A studio over `tenantScope()` views lists one tenant's runs, and another tenant's trace is not found: `studio/test/security.test.ts` |
+| Security | [Review](./SECURITY.md#the-studio-and-its-accounts): ten findings, all fixed; every route fuzzed by every role and with hostile input: `studio/test/security.test.ts` |
+| Upgrade | The journal reads what 2.4 wrote, and accounts and configuration load unchanged: `studio/test/security.test.ts`, `studio/test/team.test.ts` |
+| Soak | 2,000 sign-in, read, and change cycles with flat memory, and 200 servers started and closed with no handle left open: `studio/test/security.test.ts` |
+
+**Still experimental**, each with what remains:
+- **Images.** Recorded live conformance must pass on all three backends. The scheduled live workflow
+  records it wherever a backend's credential is set, and none has run with all three yet.
+- **The Qdrant, Redis, Pinecone, Weaviate, and Chroma vector stores.** The contract must pass against
+  the real servers. The scheduled live workflow runs it against each one, Pinecone when its secret is
+  set, and its evidence is published when it has passed against all five.
+
+A queued run's kind now names its revision, as `assistant:<id>@<revision>`. Code that reads the
+server's runs by the `assistant:` prefix, as the server itself does, is unaffected.
+
+A state store without `putIfVersion()` keeps its earlier behavior.
+
 ## 2.4 stage (2.4.0)
 
 Everything 2.4 adds is stable from the start and additive. These security fixes tighten behavior,

package/CHANGELOG.md

@@ -4,6 +4,251 @@ Notable changes to this project are recorded here. The format follows [Keep a Ch
 
 ## [Unreleased]
 
+## [2.6.0] - 2026-10-11
+
+Protocols complete, and progress on every stream.
+
+### Added
+
+- **Tool progress, end to end.**
+  - A `ToolDefinition` can have `stream`: an async generator that yields progress and returns the
+    result. `tool()` takes one instead of `execute`, and gives it an `execute` that runs the stream,
+    so it works wherever a tool is executed. `ToolExecutor` runs a stream itself.
+  - `ToolContext.progress` reports progress from any tool. An agent sets it, and turns each report
+    into a `progress` tool event while the tool runs.
+  - Progress reaches the event stream and the server's run events; AG-UI, as a `CUSTOM`
+    `tool_progress` event; A2A, as a working status update with the progress as data; ACP, as an
+    update of the tool call in progress; traces, in the tool run's `metadata.progress`; and the
+    studio's run view.
+  - MCP: `McpServer` runs `stream` tools and sends `notifications/progress` for a call that names a
+    `progressToken`. `McpClient.callTool()` takes a `progress` listener, and the tools from
+    `toNexusTools()` pass a remote tool's progress to the agent.
+
+- **AG-UI, complete**, each part opt-in on `AgUiOptions`:
+  - `stateDeltas` reports state as it changes: a `STATE_SNAPSHOT` after the first step, then a
+    `STATE_DELTA` with an RFC 6902 JSON Patch after every step that changed it, appending to arrays
+    item by item. `AgUiPatchOperation` is its type.
+  - `messagesSnapshot` sends the whole transcript as `MESSAGES_SNAPSHOT` before the run finishes.
+  - `frontendTools` offers the tools the frontend sends to the model. The frontend runs a call to one,
+    and the next run's messages carry its result.
+- **Tools the client runs.** An agent's input may carry `clientTools`, each a `ClientToolDefinition`.
+  The model is offered them; a call to one ends the turn with the new `stopReason: 'client_tools'`
+  once the agent's own calls of that step have run, and the client's result continues it. A client
+  tool never replaces a tool of the agent's own.
+- **Tools that depend on the run.** `CreateAgentOptions.toolSource` supplies tools per run, from a
+  `ToolSourceContext`, offered and run like `tools`, under the same permission policy.
+- **A2A, durable and complete.**
+  - Tasks and conversations live in an `A2aTaskStore`: `MemoryA2aTaskStore` by default, or
+    `storeA2aTasks()` over any long-term `Store`, so a task paused for an answer survives a restart
+    and another replica finishes it.
+  - `ListTasks` by context and state, a page at a time; `SubscribeToTask` on any replica; and a
+    cancel that stands against the replica running the task.
+  - Push notifications, with `pushNotifications`: each state change POSTed to a task's webhook,
+    with the caller's token and signed as the server's operation webhooks are. A webhook must be
+    `https` and not a private address, unless `allowPrivateNetworks` is set.
+  - `GetExtendedAgentCard`, with `extendedCard`, for authenticated callers.
+  - The client gains `extendedCard()`, `listTasks()`, `subscribe()`, `setPushNotification()`,
+    `listPushNotifications()`, `deletePushNotification()`, and `push` and `returnImmediately` when
+    sending.
+- **ACP, durable and complete.**
+  - Sessions live in an `AcpSessionStore`: `MemoryAcpSessionStore` by default, or
+    `storeAcpSessions()` over any long-term `Store`. The agent offers `session/load`, replays the
+    conversation, and asks again a question it was waiting on.
+  - A prompt can carry images and audio, which reach the model as content parts.
+  - `acpEditor()`, on the new `nexus-ai-pro/protocols/acp/editor`, gives an agent the editor's files,
+    terminal, and MCP servers, as tools from its `toolSource`, each declaring what it touches.
+    `serveAcp()` takes it as `editor`, and detaches it when the editor closes its end.
+- **Interoperability, proven.**
+  - A browser in CI: `npm run test:browser` serves the build to headless Chromium, which imports
+    every kernel entry point and runs a graph, an agent, and AG-UI. It runs in `npm test`.
+  - The previous minor on the other side of the wire: a 2.5 client against a 2.6 server, and the
+    other way round, on the server's HTTP API and A2A, and one harness across both releases for
+    AG-UI and ACP.
+  - A nightly `Interoperability` workflow drives each protocol with its reference client:
+    `@ag-ui/client`, `@a2a-js/sdk`, and `@agentclientprotocol/sdk`.
+- **A `step` graph event.** `GraphRunOptions.onEvent` receives `step` after each superstep, with the
+  state after it.
+
+### Fixed
+
+- AG-UI: a run that paused inside a node left that node's step open, so a strict client refused its
+  `RUN_FINISHED`; and a node's tasks running side by side each started the same step. A node's tasks
+  are now one step, and every step still open is finished before the run finishes or fails. Found by
+  the reference client.
+- A2A: `ListTasks` without a status filter, as the reference SDK sends it (`UNRECOGNIZED`), matched
+  no task. An unset filter now filters nothing, and an unknown state is refused as invalid.
+- MCP: the stdio transport's `close()` killed the server without waiting for it, so what the process
+  held, such as its working directory, could outlive the close. It now waits up to two seconds for
+  the process to exit.
+
+### Proof
+
+- Headless Chromium imports every kernel entry point and runs a graph, an agent with a streaming
+  tool, and AG-UI. A 2.5 client and a 2.6 server pass the protocol suites in both directions, and the
+  reference clients of AG-UI, A2A, and ACP each drive this release's servers through a whole run.
+- An ACP session paused on a question survives the agent's restart, on memory and SQLite; the
+  editor reopens it, sees the conversation replayed, and answers. An image and audio reach the model.
+  Through the bridge, an agent reads, writes (after the person allows it), and runs the tests in the
+  editor, and searches docs through an MCP server the editor offered, started as a real process.
+- An A2A task paused for an approval survives a restart and is finished by another replica, sending
+  its email once, on the memory, SQLite, Postgres, and Redis stores. A running task is followed where
+  it runs and from another replica; a cancel on one replica stands against the other. Every state
+  change reaches the webhook, signed and with the caller's token, and nine webhook URLs that point
+  into the agent's own network or are not https are refused.
+- An AG-UI client applying a run's snapshot and its deltas rebuilds the final state exactly, with
+  each new message one `add`. A frontend tool is offered to the model beside the agent's own; the
+  agent runs its own call, waits without calling the model again, and continues from the page's
+  result in the next run. A page cannot shadow the agent's tool, and without the options the events
+  are what they were.
+- A tool that will not go on until a reader has seen its first report finishes on every stream: the
+  event stream, the server's events, AG-UI, A2A, ACP, and MCP. Its reports arrive in order, after the
+  call and before the result, and its traced run keeps them.
+
+## [2.5.0] - 2026-10-09
+
+Graduation finished, and conversations evaluated.
+
+### Added
+
+- **Deployment changes that are atomic across replicas.**
+  - The long-term `Store` contract and the server's `ServerStateStore` gain an optional
+    `putIfVersion()`. It writes a record only when the stored one's `version` is still the version
+    the change was decided on, in one atomic step. The memory, Postgres, and SQLite stores, the server's
+    memory store, and the Redis store (when its client has `eval`) have it, and `fromStore()` passes
+    it on.
+  - A deployment change uses it. A replica that loses the race decides again on the winner's record,
+    so two changes made at once both land, in order. A change made on an `expectedVersion` is
+    refused with `DEPLOYMENT_CONFLICT` instead. Two replicas starting at once seed one record.
+  - `Deployments.atomicChanges` and `/scaling`'s `atomicChanges` say whether the state store
+    offers this.
+- **Tenant usage in Postgres**, on the new `nexus-ai-pro/postgres/tenancy`: `PostgresTenantUsage`, so
+  every replica enforces one tenant limit without Redis. The `tenancy` adapter joins
+  `postgresMigrations()` and `nexus db migrate`.
+- **Revision worker pools.** A worker image carries some revisions of an assistant, and claims only
+  the runs routed to them, so a new revision ships in a new image beside the old one.
+  - A queued run's kind names its revision, as `assistant:<id>@<revision>`, and a worker claims with
+    the kinds of the revisions it registered.
+  - A run that will wait in the queue is routed over the revisions any fresh worker reports
+    (`RevisionRequest.queued`), so the API replicas send traffic to a revision only a new image
+    carries. `RevisionChoice.local` says whether the answering replica has it.
+  - `/scaling` reports `queuedByRevision`, and `/metrics` `nexus_server_runs_queued_by_revision`, so an
+    autoscaler starts the pool a waiting revision needs.
+  - `OperationStoreFilter.kinds` filters by exact kinds on every operation store, and
+    `OperationStoreStats.queuedByKind` counts queued records per kind. `claimQueued()` checks each
+    candidate against the filter itself, for a store that ignores one.
+- **Signed context bundles.**
+  - A hub with a `signer` signs every new version with Ed25519, through Web Crypto, so on any
+    runtime. The signature covers the bundle's content and its pinned prompts' content, under the
+    full SHA-256 that `contextDigest()` computes, not the 12-digit version.
+  - A hub with a `keyring` checks signatures with `verify()`. With `requireSignature`, it refuses a
+    bundle without a trusted signature, with a `ContextSignatureError`, on `import()` and whenever
+    `resolve()` or `renderPrompt()` serves one.
+  - An import keeps the signatures that claim its content, and adds the importing hub's. That is how
+    keys rotate.
+  - `generateContextKey()`, `ed25519Signer()`, and `ed25519Keyring()` make and load keys, as JSON Web
+    Keys or Web Crypto keys.
+- **Canaries that stay fair.**
+  - A deployment records a `bucketStrategy`. `hash-v2` mixes the thread id's hash with
+    MurmurHash3's finalizer, so sequential ids such as `user-1` to `user-500` split as evenly as random
+    ones. `fnv1a-v1` stays the default, and every deployment recorded before keeps it, so no thread
+    moves through an upgrade. `Deployments.assistant()` takes `bucketStrategy`; `bucketing()` and a
+    `bucketing` change switch a recorded deployment. `bucket()` takes the strategy.
+  - Every replica counts the runs it finishes, per revision, in a rollup under the deployment version
+    they were routed with: counts, latency in buckets 5% apart, and cost. `stats()` with `deployment`
+    and `rollups()` sum them in one read, and `GET /deployments/:assistant` reports them.
+  - `watchCanaries({ from: 'rollups' })` judges a canary on every run since the split last changed,
+    instead of the latest 2,000 run records.
+- **A doctor that knows the opt-in settings.** `nexus doctor` and `diagnose()` warn, in a new
+  `settings` check, when a `RedisOperationStore` runs without `index: true`, and when a `Tracer`
+  writes to a persistent store without `incremental`. Each warning names the setting that fixes it.
+  Both stay opt-in through 2.x. `RedisOperationStore.indexed`, `Tracer.store`, and
+  `Tracer.incremental` report the settings.
+- **Graduation.** Deployments and the studio leave experimental status, each with its checklist and
+  evidence in `API_STABILITY.md` and a threat review in `SECURITY.md`.
+- **The studio's routes, listed.** `Studio.routes` gives every route's method, path, role, and audit
+  action. `StudioOptions.maxBodyBytes` bounds a request body, and
+  `MemoryStudioJournalOptions.maxComments` bounds the comments kept in memory.
+- **Whole conversations, evaluated** (`nexus-ai-pro/evaluate/threads`).
+  - `simulatedUser()` plays a user with a goal and a persona, driven by a model, and says when the goal
+    was met or when it gives up. `scriptedUser()` follows a script, for deterministic tests.
+  - `conversationTarget()` is an `evaluate()` target that holds a conversation per example and returns
+    the `Thread`: every turn, how long each answer took, the messages the agent added, and how it
+    ended. `graphThreadAgent()` drives an agent from `createAgent()`, which keeps its own tool calls
+    from turn to turn.
+  - Thread evaluators: `goalReached()`, `goalCompletion()` with a judge, `turnCount()`, and
+    `turnScores()`, which scores every turn with an evaluator of single answers and names the turn
+    where the conversation went wrong.
+- **Context on every trace.** A traced model call records `metadata.context` beside
+  `metadata.prompt`, so a trace query or an insight narrows by bundle version.
+
+### Security
+
+- **The studio**, from its threat review:
+  - A request body is refused with `413` past `maxBodyBytes`, 1 MiB by default, as it arrives and
+    before anyone is signed in. Before, a body was read whole into memory first.
+  - With accounts, only a bearer `Authorization` header stands in for the page token. Before, any
+    `Authorization` header did, and a browser adds Basic credentials to another site's request by
+    itself, so a sign-in proxy that uses Basic authentication let another site make changes.
+  - A change's body must be `application/json` (`415` otherwise) and a JSON object (`400`
+    otherwise).
+  - A change refused for want of the page token is recorded in the audit log.
+  - Graphs and review queues are looked up among the application's own entries, so a name such as
+    `constructor` no longer reaches the prototype.
+  - Malformed percent-encoding in a path is a `400`, not a server error.
+  - `limit`, `hours`, and `days` have ceilings: 1,000 items, 10,000 audit entries, 90 days of
+    issues, and 366 days of costs.
+  - The memory journal keeps at most 10,000 comments.
+  - The server no longer sends an internal error's message, and logs it instead.
+  - Only `http` and `https` pull-request links are rendered.
+- **The agent server** refuses an assistant or revision named after a built-in property, such as
+  `constructor`, with `400`. Before, such a run was accepted and failed when it ran.
+
+### Fixed
+
+- A worker that lacked the revision a run was routed to ran the assistant's live revision instead,
+  and the run still recorded the revision it was routed to. A worker now claims only runs of revisions
+  it carries.
+
+### Proof
+
+- The studio's threat review is a test: every route is called by every role and refuses the roles
+  below its own, recording each refusal; over 2,000 requests with hostile paths, queries, and bodies
+  all answer below `500`, and no prototype is polluted. 2,000 sign-in, read, and change cycles leave
+  the heap flat, and 200 servers start and close with no handle left open.
+- The doctor's seeded deployment warns about a Redis operation store without its index and a tracer
+  writing to a persistent store at the end of each trace, and the same deployment with both settings
+  turned on passes.
+- Ten replicas make mixed changes to one deployment at once (canaries, splits, promotions,
+  rollbacks, and a bucketing change), held until all ten arrive, on the memory server store and the
+  memory, Redis, Postgres, and SQLite stores. Every change lands, each with a version of its own, and
+  the history is one linear sequence.
+- Over 48 sets of 500 sequential thread ids, `hash-v2` places a canary's share within 2.3 standard
+  deviations of its weight, as random placement does; `fnv1a-v1` strays by up to 9.9. Over 10,000
+  sequential ids, `hash-v2` is within half a point at every weight.
+- A canary that fails 0.8% of the time against 0.5% is held by a guard over the latest 2,000 run
+  records, and rolled back by a guard over rollups, which counts all 100,000 runs from three replicas
+  in one read.
+- A simulated user holds 50 conversations with each of two versions of a support agent built with
+  `createAgent()`. The thread evaluators score every conversation, and `compareExperiments()` finds
+  the second version better on goals met, the judge's verdict, turns taken, and per-turn scores, with
+  no regression; the reverse comparison regresses. A conversation that failed names the turn where it
+  went wrong.
+- A signed bundle imports into a hub that requires signatures. It is refused there when it is unsigned,
+  or edited after export even with its version recomputed. One edited where it is stored is refused
+  when it is served. A re-import through a hub with a new key keeps both signatures, so the bundle
+  stays trusted once the old key is retired. Every traced model call rendered from it names its
+  context and prompt versions.
+- Two worker images drain one queue, one carrying v1 and the other v1 and v2, with an API replica
+  that carries only v1. Under a 50% canary, every run executes on the revision it was routed to, and
+  only the image with v2 runs v2. A run for a pool scaled to zero waits, is counted per revision on
+  `/scaling` and `/metrics`, and runs when that pool returns.
+- Two replicas changing one deployment in the same instant both land, on the memory, Redis,
+  Postgres, and SQLite stores. The race test holds both writers until both arrive, and the same race
+  on a store without `putIfVersion()` loses a change. Of two changes made on one expected version,
+  exactly one is refused.
+- Ten workers spending one tenant budget lose nothing, and never over-grant a slot, on Postgres as
+  on memory and Redis.
+
 ## [2.4.0] - 2026-10-08
 
 Graduation and interoperability.
@@ -1959,7 +2204,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.4.0...HEAD
+[Unreleased]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.6.0...HEAD
+[2.6.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.5.0...v2.6.0
+[2.5.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.4.0...v2.5.0
 [2.4.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.3.0...v2.4.0
 [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

package/README.md

@@ -266,12 +266,23 @@ Shipped so far:
 - 2.4 graduation and interoperability: SQLite, loaders, retrievers, the MCP registry, the context
   hub, insights, and tenant limits out of experimental with published evidence; canaries judged with
   confidence and on quality; an adapter kit; AG-UI, A2A, and ACP; and a portable kernel, with the
-  client, providers, graphs, and agents running on Deno, Bun, edge runtimes, and browsers.
+  client, providers, graphs, and agents running on Deno, Bun, edge runtimes, and browsers;
+- 2.5 graduation finished, and conversations evaluated: deployments that change atomically across
+  replicas, revision worker pools, fair canaries judged on every run, and the studio out of
+  experimental after a threat review; Postgres tenant usage; signed context named on every trace;
+  simulated users and thread evaluators; and a doctor that knows the opt-in settings;
+- 2.6 protocols complete, and progress on every stream: a tool's progress reaching the event stream,
+  the protocols, traces, and the studio; AG-UI state deltas and frontend tools; A2A tasks and ACP
+  sessions that survive a restart, with push notifications, `session/load`, and the editor's files,
+  terminal, and MCP servers; and every protocol proven in a browser, against the previous release,
+  and against its reference client.
 
 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.
-What comes next is on the [roadmap](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/ROADMAP.md):
-the gaps 2.4 left open, and the work applications ask for after them.
+Next, 2.7 lets agents do more: provider tool search, an interpreter contract, workspace search,
+helpers that run beside the agent, and a container sandbox. Evaluation grows its own datasets and
+runs on workers, within a budget. The [roadmap](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/ROADMAP.md) lists the
+releases after it.
 
 ## Before Production
 

package/SECURITY.md

@@ -52,7 +52,7 @@ what it could do with that input. Each review is published here with its finding
 before the surface graduates. A finding is closed in one of two ways: by a fix with a test that
 names the attack, or by a documented limitation that the surface's guide states.
 
-These reviews were done for 2.4.
+These reviews were done for 2.4, and for 2.5 where a review says so.
 
 ### SQLite adapters
 
@@ -168,7 +168,18 @@ server trusts by itself.
 
 Findings: none.
 
-### Deployments (reviewed; still experimental)
+### Deployments
+
+Reviewed for 2.4, and again for 2.5, when it graduated.
+
+Trust boundary: a deployment is changed by an admin, a canary guard, or the studio's admins; a run
+names its assistant, and optionally a revision, in a request from any caller with the write scope.
+Replicas, guards, and the studio share the server's state store, which they trust.
+- Every change is decided on the version it read and written by compare-and-set, on every included
+  state store, so a stale change never overwrites a newer one.
+- A guard acts on the version it judged, so guards on every replica never undo each other.
+- A replica writes rollups only to its own record. Counts are as trustworthy as the state store, as
+  run records already are.
 
 Findings:
 - **Fixed in 2.4: one caller's ratings could decide a canary.** A canary was judged on feedback
@@ -177,10 +188,68 @@ Findings:
   key, as the mean of its ratings.
 - **Fixed in 2.4: two changes at once on one replica could lose one**, such as a guard's rollback
   and an operator's promotion. Changes to one deployment now apply in order.
-- **Open: two replicas changing one deployment in the same instant can lose one change.** The
-  server's state store has no atomic compare-and-set. Until it does, deployments stay experimental.
-  The guide says to make changes from one place, or to pass `expectedVersion` and retry a conflict.
-- **Documented limitation: `bucket()` spreads sequential ids unevenly.** Ids that differ only in their
-  last characters spread unevenly over a few hundred threads. Random ids, which the server gives by
-  default, spread evenly. The function's output is part of the stability promise, so it is not
-  changed in 2.x.
+- **Fixed in 2.5: two replicas changing one deployment in the same instant could lose one change.**
+  The state store gained `putIfVersion()`, and a replica that loses the race decides again on the
+  winner's record. Proof: ten replicas held until all arrive make mixed changes on every store, and
+  every change lands in one linear history.
+- **Fixed in 2.5: a name from a request could reach an object's prototype.** A run for the assistant
+  `constructor`, or naming the revision `constructor`, was accepted and failed when it ran. Only an
+  application's own assistants and revisions are looked up now, and both are refused with `400`.
+- **Documented limitation: `fnv1a-v1` spreads sequential ids unevenly.** It stays the default, since
+  its positions are part of the stability promise. `hash-v2` spreads them evenly, opt-in per
+  deployment.
+- **Documented limitation: a replica that dies loses the runs it counted in its last `rollupMs`.**
+  Rollups are statistics; the run records stay whole.
+
+### The studio and its accounts
+
+Reviewed for 2.5, when it graduated.
+
+Trust boundary: anyone who can reach the port, before signing in; a signed-in person, limited by
+their role; a page on another site acting through a signed-in person's browser; and the data the
+studio shows, which traces, models, and people wrote.
+- The `Host` header must be a loopback name or one in `allowedHosts`, which closes DNS rebinding.
+- Tokens are compared in constant time. A token in the URL is moved into an HTTP-only, `SameSite=Strict`
+  cookie, `Secure` over HTTPS, and taken out of the address bar. `headerAuth()` trusts identity
+  headers only with the proxy's secret or from its addresses.
+- Every change needs a page token in a header, an HMAC of the user and their role under the server's
+  secret, which another site can neither read nor send. Every refusal is audited.
+- Every response carries a content security policy without inline script, `nosniff`, `no-store`,
+  and no referrer. The page inserts every value as text.
+
+Findings, each fixed in 2.5 with a test in `studio/test/security.test.ts`:
+- **A request body was read whole before anyone signed in.** Anyone who could reach the port could
+  fill the server's memory. A body past `maxBodyBytes`, 1 MiB by default, is now refused with `413`
+  as it arrives.
+- **Behind a sign-in proxy that uses Basic authentication, another site could make a change.** Any
+  `Authorization` header counted as proof that a script, not a browser, sent the change. But a
+  browser attaches Basic credentials to another site's request by itself. Only a bearer token counts
+  now, and a change's body must be `application/json`, which a form on another site cannot send.
+- **A change refused for want of the page token was not audited.** It is now, under the person whose
+  browser sent it, so a forged change leaves a trace.
+- **A name from the URL could reach an object's prototype.** A graph or review queue named
+  `constructor` failed with a server error. Only an application's own entries are looked up.
+- **A body that was not a JSON object reached handlers that read its fields.** `null`, an array, or a
+  number failed with a server error. Such a body is now refused with `400`.
+- **A path with malformed percent-encoding failed with a server error.** It is now a `400`.
+- **A viewer could ask a store for everything it holds.** `limit`, `hours`, and `days` had no
+  ceiling. A list now returns at most 1,000 items, the audit log 10,000 entries, the issues view 90
+  days, and the costs view 366 days; past that, the request is refused with `400`.
+- **The memory journal kept every comment.** It now keeps the latest 10,000, as it keeps audit entries.
+- **The server answered an internal error with its message.** That reply could reach anyone who can
+  reach the port. It now says only that the request failed, and logs the error on the server.
+- **A proposal's pull-request link was rendered as stored.** The content security policy already
+  blocked a `javascript:` address. Only `http` and `https` links are rendered now.
+
+Documented limitations, which the studio guide states:
+- The studio has no tenants of its own. Every account sees every source the studio is given, so a
+  tenant's people get a studio over that tenant's `tenantScope()` views.
+- A page token stays valid while the secret, the user, and their role do. Rotate `secret` to revoke
+  every page at once.
+- Someone without a session who opens another person's personal link is signed in as that person.
+  The page shows who is signed in.
+- `FileStudioJournal` reads its whole file for each listing, so rotate a long-lived one.
+- The playground spends model budget, which is why it needs the editor role.
+
+The fuzzing behind these: every route called by every role, and over 2,000 requests with hostile
+paths, queries, and bodies. Each must answer below `500`, and no prototype may be polluted.

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

@@ -163,12 +163,44 @@ export interface CreateAgentOptions {
      * event once the model returns. Middleware sees the assembled response either way.
      */
     streamTokens?: boolean;
+    /**
+     * Tools that depend on the run, added to `tools` on every model call and run like them: an editor's
+     * file system for one session, or the MCP servers one user connected. A tool in `tools` wins over a
+     * source's tool of the same name.
+     */
+    toolSource?: (context: ToolSourceContext) => ToolDefinition[] | Promise<ToolDefinition[]>;
+}
+/** What a tool source is told about the run it supplies tools for. */
+export interface ToolSourceContext {
+    /** The run's thread. */
+    threadId: string;
+    /** The tenant the run is for. */
+    tenantId?: string;
+    /** Who the run is for. */
+    principal?: Readonly<Principal>;
+    /** Aborted when the run is cancelled. */
+    signal: AbortSignal;
+}
+/**
+ * A tool the client runs, such as one an AG-UI frontend offers: a name, a description, and a schema,
+ * with no implementation on the agent's side. Given in the input as `clientTools`, it is offered to
+ * the model like any tool. When the model calls one, the agent ends its turn with `stopReason:
+ * 'client_tools'`, and the client sends the result back in the next run's messages.
+ */
+export interface ClientToolDefinition {
+    /** The name the model calls it by. */
+    name: string;
+    /** What it does, written for the model. */
+    description: string;
+    /** JSON Schema for the arguments. */
+    parameters: Record<string, unknown>;
 }
 declare const agentChannels: () => {
     messages: import("../types/graph.js").Channel<Message[]>;
     iterations: import("../types/graph.js").Channel<number>;
     answer: import("../types/graph.js").Channel<string>;
     stopReason: import("../types/graph.js").Channel<AgentStopReason | undefined>;
+    clientTools: import("../types/graph.js").Channel<ClientToolDefinition[] | undefined>;
 };
 /** The agent's state channels, as a graph schema. */
 export type AgentChannels = ReturnType<typeof agentChannels>;
@@ -182,12 +214,15 @@ export type AgentState = {
     answer: string;
     /** Why the agent stopped. */
     stopReason?: AgentStopReason;
+    /** Tools the client runs, given in the input; see `ClientToolDefinition`. */
+    clientTools?: ClientToolDefinition[];
 };
 /**
  * `completed` when the model answered, `max_iterations` when it ran out of model calls, `stopped`
- * when a middleware ended the run through `context.stop()`.
+ * when a middleware ended the run through `context.stop()`, and `client_tools` when the model called
+ * a tool the client runs, which waits for the client's result.
  */
-export type AgentStopReason = 'completed' | 'max_iterations' | 'stopped';
+export type AgentStopReason = 'completed' | 'max_iterations' | 'stopped' | 'client_tools';
 /** An agent: a compiled graph over the agent's channels. */
 export type AgentGraph = CompiledGraph<AgentChannels>;
 /** Wraps a question into the state an agent starts from. */