nexus-ai-pro 2.3.0 → 2.5.0

package/CHANGELOG.md

@@ -4,6 +4,333 @@ Notable changes to this project are recorded here. The format follows [Keep a Ch
 
 ## [Unreleased]
 
+## [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.
+
+### Added
+
+- **Canaries judged with confidence, and on quality.**
+  - `watchCanaries({ confidence })` judges each metric the way an evaluation comparison judges a
+    score: a seeded bootstrap interval that must not reach zero, and a minimum effect —
+    `minErrorRateIncrease`, the latency and cost margins, and `minFeedbackDrop`. A real regression
+    rolls back; noise and a trivially small change do not. `compareRuns()` takes the same options,
+    and each `Regression` carries its `interval`.
+  - `Deployments.evaluate()` scores an assistant's finished runs with evaluators from
+    `nexus-ai-pro/evaluate`, and records the scores as run feedback. A canary that answers worse is
+    then rolled back like one that fails more. Sampling is stable by run id, and a run is scored
+    once per source.
+  - Runs carry `feedback`. `POST /runs/:id/feedback` and `RunManager.addFeedback()` record a
+    person's rating as well.
+- **An adapter kit**, on the new `nexus-ai-pro/adapter-kit`, for building adapters outside this
+  repository:
+  - `defineProviderAdapter()`, `defineEmbeddingsAdapter()`, `defineVectorStoreAdapter()`,
+    `defineRetrieverAdapter()`, and `defineStoreAdapter()`. Each takes a capability declaration
+    and the range of releases the adapter supports, read as npm reads ranges.
+  - Every instance normalizes its failures into an `AdapterError` with a code and `retryable`, and
+    reports each call to an `onCall` telemetry hook.
+  - `verify()` runs the adapter's contract suite, skipping only what it declares it cannot do, with
+    a benchmark held to the p95 budgets it declares.
+  - The vector-store, retriever, and store contracts ship as `runVectorStoreContract()`,
+    `runRetrieverContract()`, and `runStoreContract()`, with no test framework needed.
+- **Agent protocols**, each on its own entry point and with no dependency:
+  - `nexus-ai-pro/protocols/ag-ui`: `agUiHandler()` serves a graph to any AG-UI frontend as
+    Server-Sent Events: each step, text as it streams, tool calls with their results, and the final
+    state. A run that needs approval finishes with an interrupt, and a resume entry on the same
+    thread continues it. `agUiEvents()` yields the same events for any other transport.
+  - `nexus-ai-pro/protocols/a2a`: `a2aHandler()` serves a graph as an A2A 1.0 agent: its card,
+    `SendMessage`, `SendStreamingMessage`, `GetTask`, and `CancelTask`. A context is a
+    conversation, and a task that needs approval asks for input and continues when a message answers
+    it. `a2aClient()` calls any A2A agent, and `a2aTool()` makes one a tool that declares the
+    host it reaches, so a permission policy decides it.
+  - `nexus-ai-pro/protocols/acp`: `serveAcp()` puts a graph in a code editor over the Agent
+    Client Protocol. The editor sees streamed text and thought, each tool call with its kind, file,
+    and diff, and the plan from `write_todos`. It asks the person to approve calls, and keeps an
+    always-allow or always-reject choice for the session.
+- **A portable kernel**, on the new `nexus-ai-pro/runtime`: messages, responses, the provider and
+  tool contracts, streaming, and capabilities, in one small import that reaches nothing Node-only.
+  `runtimeInfo()` names the runtime the code is on.
+- **The client, the provider adapters, graphs, agents, and the agent protocols run on Deno, Bun,
+  edge runtimes, and browsers.**
+  - Ids come from Web Crypto.
+  - SHA-256 for node-cache keys and dataset versions is computed in plain JavaScript where the
+    runtime has no synchronous native digest. The digests are identical, so existing cache keys
+    still match.
+  - Base64 and UTF-8 byte counts no longer need `Buffer`.
+  - 125 of 157 entry points now run anywhere. The new runtimes guide lists the rest, each with
+    exactly what it needs.
+- The OpenAI, Anthropic, Google, and Cohere providers take a `fetch` option: a platform's bound
+  fetch, a proxy, or a test stub.
+- **Measured graduation.** These surfaces leave experimental status, each with evidence for every
+  requirement of the graduation checklist, published in `API_STABILITY.md`:
+  - the SQLite adapters;
+  - the Postgres and SQLite vector stores;
+  - the loaders and the retrievers;
+  - the MCP registry;
+  - the context hub and insights;
+  - tenant limits and the server's worker queue.
+
+  Deployments, images, the Qdrant, Redis, Pinecone, Weaviate, and Chroma vector stores, and the
+  studio stay experimental, each with the requirement that remains named.
+- `inheritEnv` on a local MCP server, in `StdioClientOptions` and in the registry's server
+  configuration: which of this process's environment variables the server inherits.
+- Load and soak budgets for every graduated surface, held in CI by `npm run bench:surfaces`. A soak
+  fails on heap growth, on a handle left open, or on a timer never cleared, unref'd ones included.
+- The scheduled live workflow records image conformance on every backend with a credential, and
+  runs the vector store contract against real Qdrant, Chroma, Weaviate, and Redis servers.
+
+### Security
+
+Testing the security code to depth found these gaps, and each is closed:
+
+- **The upload scanner trusted the caller.**
+  - A declared `sizeBytes` could carry a larger file past `maxBytes`; the larger of the declared and
+    actual sizes is now checked.
+  - `run.exe.`, `run.exe ` (Windows drops the trailing dot or space), and a name with a control
+    character such as `run.exe\0.txt` passed the extension block; names are now read as the file
+    system reads them, and a control character is itself a critical finding.
+  - Content given as bytes, which is how upload middleware delivers it, was never scanned; textual
+    bytes are now decoded and scanned.
+  - A file with no MIME type passed an allowlist; an allowlist now fails closed. Types are compared
+    without parameters, so `text/plain; charset=utf-8` is `text/plain`.
+- **File ingestion read what it never scanned.** Text an extractor returns from a PDF or an image is
+  now scanned like a text file. A text file given as bytes is ingested rather than skipped.
+- **The input guard put secrets in its findings.** A finding now carries a short preview, such as
+  `ghp_… (40 characters)`, never the secret. The SSRF check also catches `[::1]`, all of
+  `127.0.0.0/8`, and the Google and Alibaba metadata hosts.
+- **Prompt hardening could be escaped.** User text holding the delimiter closed the block early; each
+  occurrence inside the text is now broken apart. The text parts of multi-part messages are wrapped
+  too.
+- **The injection detectors read text as typed, not as the model reads it.** Both now fold
+  full-width letters and drop zero-width characters first, so `ＩＧＮＯＲＥ previous instructions` and
+  `ig​nore previous instructions` are found. `neutralize()` leaves clean text exactly as it was.
+- **The PII detector and the output guard took any long number for a card or a phone.** A
+  millisecond timestamp or an order id was masked, and in the output guard a card's last digits
+  could survive because the phone pattern claimed the rest first. Card numbers must now pass Luhn,
+  and phone numbers need 10 to 15 digits with a separator or a leading `+`. Cards are claimed before
+  phones, and a span one kind has claimed is not reported again as another.
+- **Retrieved context reads as data.** `withRagContext()` now tells the model that the context is
+  data, not instructions.
+
+The graduation reviews, published in `SECURITY.md`, found these, and each is closed:
+
+- **The Git loader followed symbolic links.** A repository with a tracked link to a file of the host,
+  such as `~/.ssh/id_rsa`, had that file loaded into a knowledge base. A link is now never followed,
+  nor a path that leaves the checkout.
+- **A gzipped sitemap could be a decompression bomb.** Inflation now stops at 50 MB, the sitemap
+  protocol's maximum, and the loader reports the sitemap.
+- **A local MCP server inherited this process's whole environment**, every API key and database URL
+  included. It now starts with its `env` and only what a process needs to run: the path, the home
+  and temporary directories, the locale, the Windows system variables, proxies, and certificates.
+  Name what else a server needs in `env`, or set `inheritEnv`.
+- **One caller's ratings could decide a canary.** Feedback was counted per rating, so a hundred low
+  ratings of one run met the minimum sample alone, and could roll back a canary or keep a bad one
+  alive. Each run now counts once per feedback key, as the mean of its ratings.
+- **The file prompt store could lose a label move.** Its compare-and-set was a read and then a write,
+  so two moves at once in one process could both succeed, the later erasing the earlier. Label
+  writes to one file are now serialized across the process.
+- **Two changes at once to one deployment, on one replica, could lose one**, such as a guard's
+  rollback and an operator's promotion. They now apply in order. Changes from two replicas in the
+  same instant still can, which keeps deployments experimental.
+
+### Fixed
+
+- The agent server's guide called the server experimental, though it has been stable since 2.0.
+- Bundling the client for an edge runtime failed: it reached the file-based evaluation cache, which
+  loads `node:fs`. `FileEvaluationCache` now lives in a module of its own, still exported from
+  `nexus-ai-pro/evaluate`.
+- `extractCitations()` and `validateCitations()` read a Markdown link `[text](url)` as a citation,
+  and `[doc-1, doc-2]` as one id; links are ignored and lists are split.
+- The semantic injection classifier embeds a request in one call instead of one per message, and
+  `detectSync()` honours `enabled: false` as `detect()` did.
+
+### Proof
+
+- Grounding and verification, file ingestion, the upload scanner, the PII detector, and both
+  injection detectors are tested to the package's own coverage:
+  - grounding, the PII detector, prompt hardening, and the upload scanner at 100% of lines;
+  - file ingestion, which no test loaded before, at 97%.
+- Each security fix above is a test that names the attack it stops or the false positive it rules
+  out.
+- A canary seeded with a quality regression is rolled back. The proof runs on a real server: 300
+  runs, online evaluation recording the scores, and the guard reading them. A canary whose quality
+  differs only within the noise keeps its share. A difference that 20,000 runs make significant, but
+  that is under the minimum effect, is not a regression either.
+- A community-style adapter, built only from the kit, passes its contract suite. It is a vector store
+  in plain JavaScript inside the clean-install test's consumer project, importing nothing but
+  `nexus-ai-pro/adapter-kit` from the installed tarball. A deliberately broken store fails exactly the
+  checks it breaks.
+- A Nexus agent and a remote agent complete tasks over A2A in both directions:
+  - A client that writes raw JSON-RPC, as the specification describes it, drives the served agent
+    through a conversation, an approval, streaming, cancellation, and each error code.
+  - The client and tool complete tasks against a stub agent written from the specification alone.
+  - One Nexus agent calls another through the tool.
+- A frontend renders a run through AG-UI with a plain `fetch` and Server-Sent Events parser, and
+  no Nexus client code, approval and resume included.
+- An editor's end of an ACP connection approves an edit, and sees the plan, the diff, and the
+  answer.
+- The kernel's tests pass on Node.js, Deno, Bun, and Vercel's edge runtime, and CI runs all four.
+  The tests are written against web-standard APIs only, with no test framework and nothing of Node's,
+  and they cover a provider over `fetch`, the client, a cached graph, an agent, and A2A and AG-UI.
+  A check walks every entry point's imports, static and dynamic. It fails the build when the client,
+  the kernel, a provider adapter, graphs, agents, or a protocol reaches anything Node-only.
+- Every graduated surface passes its contract on every backend it supports. For the context hub,
+  that is memory, files, Redis, and Postgres, with two hubs racing for one label and never both
+  winning. For the retrievers, it is a vector retriever over memory, SQLite, and pgvector, besides
+  the keyword and hybrid retrievers.
+- What the published 2.3.0 package wrote, this release reads, and what it derived, this release
+  derives the same: a SQLite file shared by a 2.3 and a 2.4 worker, a pgvector table, loader ids,
+  retriever rankings, MCP configurations, context bundle versions and exports, insight proposals
+  and error signatures, and canary routing, thread by thread.
+- Each security fix has a test that names the attack, and fails on the code before it. The Git test
+  runs on Linux, where links are tracked as links, and the race test holds both writers until both
+  arrive, so it does not depend on timing.
+
 ## [2.3.0] - 2026-10-06
 
 Agents that act safely, on production retrieval.
@@ -1777,7 +2104,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.3.0...HEAD
+[Unreleased]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.5.0...HEAD
+[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
 [2.1.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.0.0...v2.1.0

package/README.md

@@ -8,7 +8,10 @@ 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 80 KB, and installs nothing but this package.
+loads 81 KB, and installs nothing but this package.
+The client, the provider adapters, graphs, agents, and the agent protocols run on Node.js, Deno,
+Bun, edge runtimes, and browsers; [the runtimes guide](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/runtimes.md)
+lists the entry points that need Node.js, and why.
 
 - NPM: https://www.npmjs.com/package/nexus-ai-pro
 - GitHub: https://github.com/mkhitar-abrahamyan/nexus-ai
@@ -136,6 +139,7 @@ from the doc comments. The guides live in the repository, so these links go to G
 | [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 |
+| [Agent protocols](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/protocols.md) | Serving an agent to user interfaces over AG-UI, to other agents over A2A, and to code editors over ACP, and calling remote agents as tools |
 | [Traces](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/tracing.md) | Run trees, queries, feedback, comparison, and alerts |
 | [Evaluation](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/evaluation.md) | Datasets, evaluators, experiments, comparisons with a verdict, review queues, LLM judges |
 | [Context hub](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/context-hub.md) | Prompts, instructions, tools, and skills versioned together, promoted through gates, and moved between projects |
@@ -156,6 +160,7 @@ from the doc comments. The guides live in the repository, so these links go to G
 | [Realtime voice](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/realtime.md) | Browser and server realtime sessions with barge-in, tools, and exports |
 | [Telephony](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/telephony.md) | Calls, webhooks, phone numbers, and phone agents on realtime sessions |
 | [Testing](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/testing.md) | Recording and replaying provider traffic, and conformance suites |
+| [Adapter kit](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/adapter-kit.md) | Building a provider, store, or retriever outside this repository, and verifying it against the same contracts |
 | [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 |
@@ -163,6 +168,7 @@ from the doc comments. The guides live in the repository, so these links go to G
 | [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 |
+| [Runtimes](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/runtimes.md) | The portable kernel, and running the client, providers, graphs, and agents on Deno, Bun, edge runtimes, and browsers |
 
 ## Examples
 
@@ -256,12 +262,20 @@ Shipped so far:
 - 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.
+  preset;
+- 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;
+- 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.
 
 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.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
+Next, 2.6 completes the agent protocols: tool progress on every stream, AG-UI deltas and frontend
+tools, A2A tasks and ACP sessions that survive a restart, and a browser in CI. The [roadmap](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/ROADMAP.md) lists the
 releases after it.
 
 ## Before Production

package/SECURITY.md

@@ -44,3 +44,212 @@ Nexus guardrails reduce common AI application risks, but they are not a complete
 - Browser WebRTC still requires a backend security boundary. A direct media path reduces latency; it
   does not remove the need for server-owned credentials, session policy, tool authorization, abuse
   monitoring, and provider-side safety controls.
+
+## Threat reviews
+
+Every surface that leaves experimental status is reviewed for how untrusted input reaches it and
+what it could do with that input. Each review is published here with its findings, which are closed
+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, and for 2.5 where a review says so.
+
+### SQLite adapters
+
+Trust boundary: an application's data, an operation's payload, and metadata filters that may come
+from a request.
+- Table names are checked against a strict pattern and quoted. Every value, including each metadata
+  filter key and its JSON path, is a bound parameter, so a filter cannot change a statement.
+- A migration records its checksum, and a changed migration is refused rather than reapplied.
+- Every change to an operation is one `UPDATE … WHERE sequence = expected`, so two workers sharing
+  a file never both claim it. The ten-worker race tests run on SQLite.
+- Tenant data is scoped by key prefix, and the isolation suite runs on every SQLite store.
+
+Findings: none.
+
+### The Postgres and SQLite vector stores
+
+Trust boundary: metadata filters, which applications often build from a request.
+- The pgvector store sends a filter as one bound `jsonb` containment parameter, and quotes its table
+  and index names.
+- The SQLite store binds each key's JSON path and value, and matches a value's JSON type as well as
+  its value, so `"1"` never matches `1`.
+
+Findings: none.
+
+### Loaders
+
+Trust boundary: everything a loader reads is untrusted. A repository, a website, a sitemap, or an
+uploaded file may be written by an attacker who wants it in a knowledge base, or who wants the
+loader to read something else.
+- Web pages and sitemaps go through the SSRF-safe fetch. Private, loopback, and cloud-metadata
+  addresses are refused, every redirect is checked again, and bodies are capped.
+- The Git loader runs `git` without a shell. It disables the `ext::` transport, puts `--` before
+  the repository, and refuses a repository that starts with `-`.
+- `loadDirectory()` does not follow symbolic links.
+
+Findings, both fixed in 2.4:
+- **The Git loader followed symbolic links.** A tracked link such as `notes.md` pointing to
+  `~/.ssh/id_rsa` was read and ingested, so a knowledge base could quote a file of the host. A
+  link is now never followed, nor a path that resolves outside the checkout. Proof: a repository
+  holding a tracked link to a file outside it loads without that file, cloned and in place. On
+  Linux, the test fails on the earlier loader.
+- **A gzipped sitemap could be a decompression bomb.** A few megabytes of gzip inflated without a
+  limit. Inflation now stops at 50 MB, the sitemap protocol's own maximum. Proof: 60 MB of gzip
+  that inflates past it is refused.
+
+### Retrievers
+
+Trust boundary: queries come from users, and documents may hold text written to steer a model.
+- Tokenizing is one linear regular expression, with no backtracking on hostile input.
+- Filters compare values; they never become code or a query language.
+- A model reranker or query-variant generator reads documents and queries as data in its prompt. Its
+  output is parsed as JSON and used only to order or widen a search, never to call a tool.
+
+Findings: none.
+
+### MCP registry
+
+Trust boundary: the configuration file is trusted, since it names programs to run. What a server
+says about itself is not: its tool names, its descriptions, and its results.
+- A server's tools are prefixed with its name by default, so one server cannot shadow another's
+  tool.
+- Allow and deny lists limit what agents see, and deny wins.
+- A tool from a server declares no capabilities. A permission policy denies such a tool unless its
+  `undeclared` rule says otherwise, and `humanApproval()` asks about it by default.
+- `${NAME}` placeholders keep credentials out of the file. A missing variable is named in the error,
+  never its value.
+
+Finding, fixed in 2.4: **a local server inherited this process's whole environment.** Any
+`npx`-started server, which is usually third-party code, saw every API key and database URL the
+application held. A server now starts with `env` and only what a process needs to run: the path,
+the home and temporary directories, the locale, proxies, and certificates. The new `inheritEnv`
+option widens this by name, or entirely. Proof: a real child process started by the transport sees
+the variables it was given, and not a secret set in the parent.
+
+### Context hub
+
+Trust boundary: an imported bundle may come from another team or another organization. Who may
+commit and promote is the application's access control, which the studio's roles enforce.
+- An import recomputes each bundle's and each prompt's content version, and refuses one whose content
+  changed after export.
+- A bundle names tools, but `bindTools()` binds only implementations the application supplies, so
+  a bundle cannot add code.
+- Promotion runs the label's gates, an experiment over the exact version among them.
+- Labels move by compare-and-set, so a promotion decided on a stale version is refused.
+
+Finding, fixed in 2.4: **the file store's compare-and-set could lose a move.** Two label moves at
+once in one process could both pass the check, and the later write erased the earlier one. Label
+writes to one file are now serialized across the process. Proof: two hubs whose writes are held
+until both arrive race for one label on every backend, and on the file store the earlier code
+loses a move every time. Several processes promoting the same label at once still need the Redis or
+Postgres store, as the prompts guide says.
+
+### Insights
+
+Trust boundary: runs and their errors carry user data, and a model proposes fixes.
+- An error signature replaces numbers, quoted values, URLs, ids, and long hexadecimal strings, so a
+  cluster's summary does not carry a customer's data.
+- A model's proposed fix is parsed as data, evaluated on a dataset, and never applied without a
+  person. A promotion still runs the label's gates.
+- A proposal id is checked against a strict pattern before it becomes a file name.
+
+Findings: none.
+
+### Tenant limits and the worker queue
+
+Trust boundary: a tenant is whoever the application's `authenticate()` says, never a header the
+server trusts by itself.
+- Concurrency, rate, and budget limits are kept in a shared store, so several replicas enforce one
+  limit. Admission and release are tested by ten racing workers.
+- A run is released exactly once, however it ends.
+- The queue claims an operation under a lease in one atomic step on every store. A lost lease
+  cancels the run's signal, and a crash at any durable boundary resumes to the same state.
+
+Findings: none.
+
+### 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
+  entries, not on runs. A hundred low ratings of one run met the minimum sample alone, and could
+  roll back a canary for everyone, or keep a bad one alive. Each run now counts once per feedback
+  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.
+- **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.