nexus-ai-pro 2.20.2 → 2.22.0

package/API_STABILITY.md

@@ -67,6 +67,99 @@ graduation:
 | Upgrade | A migration test from the previous minor |
 | Soak | A long-running test with flat memory and no leaked handles |
 
+## 2.22 stage (2.22.0)
+
+Everything 2.22 adds is stable from the start and additive, unless this section says otherwise.
+
+New and stable: `StreamChunk.logprobs`; in `nexus-ai-pro/protocols/a2a`, `signA2aCard()`,
+`verifyA2aCard()`, `canonicalA2aCard()`, `A2aCardSignatureError`, `A2aCardSigner`, `A2aCardKeyResolver`,
+`A2aSignatureAlgorithm`, `A2aJsonWebKey`, `A2aCryptoKey`, `A2aServerOptions.sign`, and
+`A2aClientOptions.verifyCard`, which `A2aGrpcClientOptions` takes too; in `nexus-ai-pro/mcp`,
+`mcpHttpHandler()`, `McpHttpOptions`, `McpHttpHandler`, `samplingFrom()`, `McpSamplingOptions`,
+`McpSamplingClient`, `McpServerPrompt`, `McpPromptArgument`, `McpPromptMessage`, `McpServerResource`,
+the server's `registerPrompt()`, `registerResource()`, `resourceUpdated()`, `createMessage()`,
+`elicit()`, `listRoots()`, and `onRootsChanged()`, the client's `sampling`, `elicitation`, and `roots`
+options, `onPromptsChanged()`, `onResourcesChanged()`, `onResourceUpdated()`, `subscribeResource()`,
+`unsubscribeResource()`, and `rootsChanged()`, `HttpClientOptions.listen`, the protocol types
+`McpSamplingRequest`, `McpSamplingResult`, `McpSamplingMessage`, `McpSamplingContent`,
+`McpModelPreferences`, `McpElicitationRequest`, `McpElicitationResult`, `McpRoot`, and
+`McpCallerRequests`, and `ToolContext.mcp`; in `nexus-ai-pro/agent/openapi`, `swaggerToOpenApi()`,
+`bundleOpenApiDocument()`, `OpenApiBundleOptions`, `OpenApiCredential`, `OpenApiWebhook`,
+`OpenApiToolsOptions.credentials`, `OpenApiOperation.security`, `OpenApiTools.webhooks`, and
+`loadOpenApiTools()`'s `references`, `maxDocuments`, and `maxBytes`; in `nexus-ai-pro/server/auth`,
+`createJwtSigner()`, `JwtSigner`, `JwtSignerOptions`, `JwtSignOptions`, `generateJwtKey()`,
+`jwksHandler()`, `createApiKeyStore()`, `ApiKeyStore`, `ApiKeyStoreOptions`, `ApiKeyRecord`,
+`IssuedApiKey`, `ApiKeyIssueOptions`, `createSessions()`, `Sessions`, `SessionOptions`,
+`SessionCookieOptions`, `SessionRecord`, and `StartedSession`, and the principal method `session`; in
+`nexus-ai-pro/rag/pinecone`, `PineconeVectorStore.create()`, `ensurePineconeIndex()`,
+`PineconeIndexOptions`, `PineconeIndex`, and `PineconeCreateOptions`, experimental with the store;
+`TypeSafeDecisionProviderOptions.pictures`; and in `nexus-ai-pro/embeddings`, `EmbeddingVideoPart`, the
+modality `video`, `EmbeddingMeta.unpricedMedia`, and `EmbeddingModelCapabilities`'
+`costPerAudioSecond`, `costPerVideoFrame`, `videoFrames`, `maxAudioSeconds`, and `maxVideoSeconds`; in
+the loaders, `FileInput`'s stream form, `CsvRowParser`, `JsonLoaderOptions.recordsAt`,
+`WebLoaderOptions.render` and `renderBelow`, `browserRenderer()`, `WebPageRenderer`, `WebPageToRender`,
+`RenderingBrowser`, and `BrowserRendererOptions`; in the realtime family, `ImageItem`, the `message.image`
+event, and `RealtimeConversationOptions.recordImages`; in telephony, `TelephonyGatherResult`,
+`EndGatherRequest`, `parseGatherResult()` and `endGather()` on the manager and the providers, and
+`TelnyxTelephonyProviderConfig.transcriptionEngine`; in the studio, `StudioOptions.tenantSources`,
+`StudioUser.tenant`, `StudioAuditEntry.tenant`, `StudioComment.tenant`, `StudioAuditQuery`,
+`HeaderAuthOptions.tenant`, `BearerAuthOptions.tenant`, `StudioSignIn`, and `StudioOptions.signIn`.
+Experimental: in the studio, `oidcSignIn()`, `OidcSignInOptions`, `SIGN_IN_COOKIE`, and the
+`/auth/` routes, until a sign-in against a live provider is recorded; `nexus-ai-pro/voice/google`,
+`GoogleVoiceProvider` and `GoogleVoiceProviderConfig`, until a live run is recorded.
+The state store keys and sessions are kept in, under `nexus/server`, is read by every later 2.x.
+
+Changed on purpose: an answer the output guard changes or blocks keeps no `logprobs`, streamed or
+not; a typed decision of a model that reports the chosen token alone is sampled; an Ollama stream
+honours `stop`. An MCP server declares prompts and resource subscriptions at `initialize` whatever it
+was given, and serves every transport connected to it rather than the last; a tool it runs gets a
+`signal` and `mcp` in its context. The HTTP client transport returns from `send()` before a streamed
+answer ends, sends `mcp-protocol-version`, and sends a `DELETE` when closed with a session. OpenAPI
+tools are made of operations with any request body, where those with a body other than JSON or a form
+were skipped, and of Swagger 2.0 documents, which were refused; `loadOpenApiTools()` reads no more of
+a document than `maxBytes`. With `credentials` given, an operation whose security cannot be met fails
+before it is sent.
+
+A TypeSafe AI request with pictures is multipart unless `pictures: 'base64'`, and its size is counted
+in bytes. gemini-embedding-2's audio and video are priced, where they cost nothing before, and audio
+past 180 seconds or video past 120 is refused before the call. A Google embedding batch over 20 MB is
+sent as a file, where it was refused. Gemini Live acts on `updateSession()`, which it ignored. A
+realtime record holds the images sent, as `image` items, which a consumer that switches on every item
+type meets for the first time. A Telnyx gather for speech transcribes the caller, where it was
+refused.
+
+Deprecated: `OpenApiTools.skipped`, always empty, is removed in 3.0.
+
+## 2.21 stage (2.21.0)
+
+Everything 2.21 adds is stable from the start and additive, unless this section says otherwise.
+
+New and stable, in `nexus-ai-pro/decisions`: `BoxQuestion`, `BoxAnswer`, `DecisionBox`, `boxOverlap()`,
+`statePictures()`, `readPicture()`, `DecisionPicture`, `ReadDecisionPicture`, the question type `box`
+and its `DecisionDistribution`, `DecisionProviderCapabilities.images`, `answeredRight()`'s box and
+`overlap`, `DecisionEvaluatorOptions.where` and `overlap`, `DecisionConformanceOptions.picture`,
+`DecisionConformanceReport.skipped`, and `CompletionDecisionsOptions.images`; in
+`nexus-ai-pro/decisions/typesafe`, `TypeSafeDecisionProviderOptions.media`; in `nexus-ai-pro/adapter-kit`,
+`gatherRecords()`, `GatherRecordsOptions`, `GatherReport`, `GatheredSource`, `GatherOutcome`,
+`RecordSource`, and `ADAPTER_KEYWORD`; the command `nexus adapters gather`; a package's
+`nexus.compatibility` field, the URL of its record; in `nexus-ai-pro/config`, `useDefaults()`,
+`nexusDefaults()`, `NexusDefaults`, `DEFAULT_CHANGES`, and `DefaultChange`, and the `NEXUS_DEFAULTS`
+variable; `DoctorOptions.upgrade` and `nexus doctor --upgrade`; and `TraceStore.durable`. The
+preview turns on exactly what 3.0 will; should 3.0 change its defaults again before it ships, the
+preview follows, and `DEFAULT_CHANGES` says so. A box from TypeSafe AI rests
+on what it marks as experimental, its pictures and boxes, whose request format may change between its
+releases.
+
+Changed on purpose: TypeSafe AI's 400 and 413 are `DECISION_INVALID`, not `DECISION_FAILED`; neither
+was retried before or is now. A provider of your own that reads pictures declares `images: true`;
+without it, a decision about a picture is not sent to it. A union over `DecisionQuestionType` or
+`DecisionAnswer` that handled three kinds now meets a fourth, `box`. `compatibilityPage()` writes a
+repository that is not an `http` or `https` address as text, not a link, and escapes a record's
+Markdown. A doctor report has one more check, `upgrade`, skipped unless asked for. With `tenants`, an
+A2A handler answers `/{tenant}/.well-known/agent-card.json` with that tenant's card, where it answered
+the card itself; without `tenants`, nothing changes. A model on OpenAI's Responses API is sent
+`include` and `top_logprobs` when a request asks for log probabilities, which it was not before.
+
 ## 2.20 stage (2.20.0)
 
 Everything 2.20 adds is stable from the start and additive, unless this section says otherwise.

package/CHANGELOG.md

@@ -4,6 +4,211 @@ Notable changes to this project are recorded here. The format follows [Keep a Ch
 
 ## [Unreleased]
 
+## [2.22.0] - 2026-10-29
+
+MCP over streamable HTTP both ways, OpenAPI tools that send each operation's credentials, tokens, keys,
+and sessions the server issues, and a studio that signs people in and serves many tenants; with signed
+A2A cards, embeddings of video, loaders that stream, Gemini's voice, and the kernel in Firefox and
+WebKit.
+
+### Added
+
+- **Log probabilities from a stream.** Each `text` chunk's `StreamChunk.logprobs` holds its tokens'
+  log probabilities, from OpenAI's Chat Completions and Responses API, Gemini, Ollama, and Cohere, so
+  the chunks' together are what `complete()` reports.
+- Cohere reports log probabilities, `complete()` and streamed: a piece of text at a time, each piece's
+  the sum of its tokens', with no alternatives.
+- **MCP both ways.** A server offers prompts (`McpServerPrompt`, `registerPrompt()`), resources a client
+  subscribes to (`resourceUpdated()`), and tells every client each list's changes; a tool it runs may ask
+  the client that called it for a completion from its model, an answer from its person, or its roots,
+  through `context.mcp`, and is stopped when the client cancels it. A client answers a server's
+  `sampling`, `elicitation`, and `roots` with handlers of its own, `samplingFrom()` answering with
+  the application's own model, and hears each list change and each resource it subscribed to.
+- **MCP over streamable HTTP, both ways.** `mcpHttpHandler()` serves an `McpServer` as a Web handler:
+  a session per client, a stream of events per request carrying the server's progress and questions
+  before its answer, a `GET` stream for what it sends of its own accord, `DELETE` to end a session, and
+  a request from another origin refused. The client's HTTP transport reads a stream as it comes, so a
+  question in the middle of a call arrives in time, listens on a `GET` stream with `listen`, sends the
+  protocol version, and ends its session on `close()`. The nightly interoperability run drives the
+  server with `@modelcontextprotocol/sdk`'s own client: its tools, a completion asked mid-call, its
+  progress, a prompt, and a subscribed resource's change.
+- **Signed A2A cards.** `signA2aCard()` and `verifyA2aCard()`, with `canonicalA2aCard()`, sign and check
+  a card as protocol 1.0 does, a flattened JWS over its canonical form, which is the A2A project's SDK's
+  form: a card either signs, the other verifies. A handler's `sign` signs every card it serves, each
+  tenant's and the extended card included, and a client's `verifyCard` makes no call until a signature
+  on the card holds. ES256, ES384, ES512, RS256, RS384, RS512, PS256, PS384, PS512, and Ed25519, by the
+  Web Crypto API alone. The nightly interoperability run checks both directions against `@a2a-js/sdk`.
+- **OpenAPI credentials.** Tools read from an OpenAPI document send the credentials each operation's
+  security asks for, from `credentials` given by scheme name, or chosen per call: an API key in a
+  header, query parameter, or cookie; HTTP Basic, bearer, or another HTTP scheme; and an OAuth 2.0 or
+  OpenID Connect token, held, or fetched by the client-credentials flow for the operation's scopes and
+  kept until a minute before it expires. An operation whose alternatives none can be met fails before
+  anything is sent, naming them. Each `OpenApiOperation` carries its `security`.
+- **Swagger 2.0, and references to other documents.** A Swagger 2.0 document is read as the OpenAPI 3.0
+  one it describes, which `swaggerToOpenApi()` returns. `bundleOpenApiDocument()` reads in the other
+  documents a document's references name, on its own origin by default, or as `references` allows,
+  within `maxDocuments` and `maxBytes`; `loadOpenApiTools()` does so itself.
+- OpenAPI tools send a multipart form, its file fields given as base64, a text or XML body, and a body
+  of bytes, such as an image, so every operation becomes a tool. `webhooks` lists what the API sends
+  the application, its webhooks and its operations' callbacks, each with its JSON body's schema.
+- **Tokens, keys, and sessions the server issues.** `createJwtSigner()` issues tokens with a secret, a
+  PEM or JWK private key, or a Web Crypto key pair, and `issue()` writes a principal under the claim
+  names `jwtAuth()` reads back; `generateJwtKey()` makes a key, and `jwksHandler()` publishes the
+  public halves, for a rotation that refuses no live token. `createApiKeyStore()` issues, rotates with
+  a grace period, and revokes API keys, kept as hashes in the server's state store with when each was
+  last used. `createSessions()` signs browsers in after a sign-in of the application's own: an
+  `HttpOnly`, `Secure`, `SameSite=Lax` cookie of a random secret whose hash alone is kept, an idle
+  and a total lifetime, sign-out here or everywhere, and a request from another site's page refused.
+- **A Pinecone store makes its own index.** `PineconeVectorStore.create()` creates a serverless index
+  with the cosine metric and the store's width, or uses one of that name that fits, waits until it is
+  ready, and returns a store over its host; `ensurePineconeIndex()` does the first part alone.
+- TypeSafe AI is sent a decision's pictures as parts of a multipart request, as bytes, so three
+  pictures of 10 MiB fit in the 32 MiB a request holds; `TypeSafeDecisionProviderOptions.pictures`
+  set to `base64` sends them within the JSON, as before.
+- **Embeddings of video, and audio and video priced by length.** An `EmbeddingVideoPart` holds a video
+  by its bytes, base64, or a URL, such as a Files API URI, and gemini-embedding-2 embeds it. Audio is
+  priced by the second and video by the frame the model takes, one a second and at most 32 on
+  gemini-embedding-2, at $0.00016 a second and $0.00079 a frame, each length read from the media's own
+  headers; a budget counts them before the call. Media longer than a model's `maxAudioSeconds` or
+  `maxVideoSeconds` is refused before it is sent, and media whose length cannot be read is counted in
+  `unpricedMedia`. A registry data file sets these prices and limits too, each checked when it loads.
+- A Google embedding batch over 20 MB, up to 2 GB, is uploaded as a JSONL file through the Files API, and
+  its results are read from the file the batch writes, matched to their inputs by key.
+- **CSV and JSON stream through.** `loadCsv()` and `loadJson()` read a file as it arrives and yield each
+  row or record as soon as it is read: a path in chunks, or a `FileInput` that is now also a stream,
+  such as a response's body. `CsvRowParser` parses CSV a piece at a time, and `recordsAt` names the
+  array of records inside a JSON document, such as `data.items`, read item by item. A file larger than
+  memory goes to the store a batch at a time.
+- **Pages built by script.** `loadWebPages()` takes a `render` of the application's own for a page
+  whose text a script builds, and `browserRenderer()` makes one from a Playwright or Puppeteer browser,
+  with no browser a dependency of the package.
+- **Gemini voice.** `GoogleVoiceProvider`, on `nexus-ai-pro/voice/google`, speaks in Gemini's voices, as
+  WAV or raw PCM, whichever its model answers with, directed by a system instruction that is never
+  spoken; and transcribes with a text model that hears the audio, inline or by a Files API URI, guided
+  by its language and the names it may hold. Experimental until a live run is recorded.
+- **Gemini Live changes its setup mid-call.** `updateSession()` on Gemini Live sets the session up again
+  between turns, on a new socket resumed from the latest handle: instructions, voice, language,
+  modalities, tools, turn detection, the model, and Gemini's own setup fields. What is sent meanwhile
+  waits, and the conversation carries on.
+- **Images in the realtime record.** An image sent in a realtime conversation is kept as an `ImageItem`,
+  with its digest and, unless `recordImages` is `digest`, the image, and a resumed session gives it
+  back to the model. Video frames are not kept.
+- **Telnyx gathers speech.** A gather that listens for speech on Telnyx transcribes the caller's side of
+  the call, with its prompts spoken and keys still taken, until `endGather()`. `parseGatherResult()`
+  reads what a gather collected on either provider, Twilio's `SpeechResult` and `Digits` or Telnyx's
+  `call.transcription` and `call.gather.ended`, as one `TelephonyGatherResult`.
+- **The studio signs people in, and serves many tenants.** `oidcSignIn()` signs people in with any
+  OpenID Connect provider, with no proxy in front: the code flow with PKCE, a state, and a nonce, the ID
+  token verified against the provider's keys, and a signed session cookie that replicas share, with
+  sign-out at the provider too. A person's `tenant`, from a claim, a header, or the users file, picks
+  the sources they read, from `tenantSources`; they see their tenant's comments and audit entries
+  alone, and their page token is bound to it.
+- **The kernel in Firefox and WebKit.** The portable kernel's own tests, the file Node.js, Deno, Bun,
+  and the edge runtime run, now run in a browser page too, in headless Chromium on every build and in
+  Firefox and WebKit, Safari's engine, in CI, with a graph, an agent with a streaming tool, and AG-UI.
+- **Cohere's Embed 5.** `embed-v5.0-pro` and `embed-v5.0-fast` are in the registry, with their
+  sizes from 256 to 2,048, 128,000 tokens, and images. Cohere publishes no per-token price for them,
+  so they are registered without one.
+
+### Changed
+
+- A TypeSafe AI request with pictures is multipart by default, and its 32 MiB is counted in bytes, not
+  characters, so a state of text outside ASCII is refused before it is sent rather than by the API.
+- `loadCsv()` and `loadJson()` yield their first document before the rest of the file is read; a JSON
+  file whose array of records is cut short is refused as such, after the records before the cut.
+- An OpenAPI operation with a multipart or other non-JSON body becomes a tool, where it was skipped; a
+  Swagger 2.0 document is read, where it was refused; and `loadOpenApiTools()` refuses a document over
+  `maxBytes`, 5 MB by default, reading no further.
+
+### Deprecated
+
+- `OpenApiTools.skipped`, always empty now that every operation becomes a tool. It is removed in 3.0.
+
+### Fixed
+
+- **An answer the output guard redacts keeps no log probabilities.** They name the tokens the model
+  wrote, so a redacted address or connection string was still spelled out in `response.logprobs`; now
+  they are dropped wherever the guard changes or blocks the text, streamed or not.
+- The Google embedding batch adapter reads inline results under the name Google's API reference gives
+  them, `inlinedResponses`, as well as its clients' name.
+- A typed decision asked of a model that reports only the chosen token's log probability, with no
+  alternatives, is sampled, where it was read as certain.
+- An Ollama stream stops at the request's `stop` sequences, as a call does.
+
+## [2.21.0] - 2026-10-26
+
+Typed decisions about pictures, compatibility records gathered from community adapters' own CI, and
+3.0's defaults behind one switch today; with log probabilities from OpenAI's Responses API, and a card
+of its own for each tenant of an A2A agent.
+
+### Added
+
+- **Decisions about pictures.** A decision's state may hold pictures, as image parts or image assets
+  anywhere in it, and a question names each by its path in backticks, such as `photo` or
+  `frames[2].frame`. Every question type may ask about one, and a new `box` question, `BoxQuestion`,
+  asks where something is: its `BoxAnswer` is a `DecisionBox` of four edges, each a fraction of the
+  picture's height or width, with a confidence. `boxOverlap()` measures how far two boxes overlap,
+  `answeredRight()` counts a box right at half or more, `calibrate()` chooses a box's threshold as any
+  answer's, and `decisionEvaluator()` scores a box against `where` the thing is. `statePictures()`
+  lists a state's pictures and `readPicture()` reads one with the media family's readers.
+- TypeSafe AI's Jev is sent a state's pictures as the API's assets, each under a new reference, with
+  the `TypeSafe-Danger-Zone-Images` header that pictures and boxes require, and answers boxes on Jev 1.14
+  and later. A picture it would refuse, outside PNG or JPEG, animated, over 16 MiB, or outside 280 to
+  1,568 pixels a side, or a request over 32 MiB, is refused first, naming the picture's path.
+  `TypeSafeDecisionProviderOptions.media` reads pictures held by file, URL, or stored asset.
+- `completionDecisions()` shows a vision model the pictures a state holds, each labelled by its path,
+  and reads a box as the median of several samples, its confidence how far they agree; `images: false`
+  marks a text-only model.
+- `DecisionProviderCapabilities.images`: a provider that does not read pictures is refused a decision
+  about one, and passed over as a fallback. The mock reads pictures and answers boxes.
+- `DecisionConformanceOptions.picture` runs the conformance checks of pictures and boxes, and
+  `DecisionConformanceReport.skipped` lists the checks that could not run, rather than passing them.
+- **Compatibility records from community CI.** An adapter's own CI publishes its sealed record at the
+  URL its package names as `nexus.compatibility`, beside the keyword `nexus-ai-pro-adapter`.
+  `nexus adapters gather`, and `gatherRecords()` in `nexus-ai-pro/adapter-kit`, find those packages on
+  npm, fetch each record, and keep only those whose digest matches and that name their own package,
+  from HTTPS; a source that is down keeps its last record, and a package that no longer names one
+  leaves the page. Nothing an adapter publishes is run. A daily `Community compatibility` workflow
+  writes the page, with the adapters this repository ships, to the `compatibility` branch, where a
+  record that says its adapter fails turns it red. `compatibility/sources.json` lists adapters not
+  on npm.
+
+- **A preview of 3.0's defaults.** `useDefaults('3.0')`, from `nexus-ai-pro/config`, or
+  `NEXUS_DEFAULTS=3.0`, turns on the three settings 2.x keeps opt-in, as 3.0 will: incremental tracing on
+  a durable trace store, the Redis operation store's dispatch index where the client can keep it, and
+  `hash-v2` for a deployment first recorded. An option set explicitly wins, and without the switch
+  nothing changes. `DEFAULT_CHANGES` lists each, with what to do first; `nexusDefaults()` says which
+  defaults are in effect; and `nexus doctor --upgrade 3.0`, `DoctorOptions.upgrade`, says what 3.0
+  would change for a deployment. `TraceStore.durable` marks a store whose runs live only in the
+  process, as `MemoryTraceStore`'s.
+
+- OpenAI's models on the Responses API, such as `gpt-5.5-pro`, report token log probabilities when a
+  request asks for them, as its chat models do: the request includes `message.output_text.logprobs`
+  with up to 20 alternatives a token, and each text part's are read back. A typed decision asked of
+  one is read from them in one call, rather than sampled; a model that refuses them is still sampled.
+
+- With `tenants`, an A2A handler serves each tenant a card of its own at
+  `/{tenant}/.well-known/agent-card.json`, every interface naming the tenant, so a client that reads it,
+  such as the A2A project's reference client, calls as that tenant over each binding. The nightly
+  interoperability run drives a tenant through `@a2a-js/sdk` over JSON-RPC, HTTP+JSON, and gRPC, and
+  checks that a tenant it may not act for, and a call naming none, are refused.
+
+### Fixed
+
+- The compatibility page writes a record as text: an adapter links to its repository only at an
+  `http` or `https` address, so a record naming `javascript:` makes no link on the HTML page; a
+  record's line breaks, pipes, brackets, and stars no longer break or add to the Markdown; and the
+  HTML page colours each row by its state.
+
+### Changed
+
+- TypeSafe AI's 400 and 413 refuse a decision as `DECISION_INVALID`, as a 422 does, rather than
+  failing it as `DECISION_FAILED`: the request, such as a picture, is what was refused. Neither is
+  retried.
+- A decision's trace and cache key hold a digest of each picture in its place, never its bytes, and the
+  budget holds a picture at 1,600 tokens rather than reading its base64 as text.
+- A doctor report has one more check, `upgrade`, skipped unless `upgrade` asks about a release.
+
 ## [2.20.2] - 2026-10-24
 
 The first published release of 2.20. The package is 2.20.0's: the publishes of 2.20.0 and 2.20.1
@@ -3287,7 +3492,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.20.2...HEAD
+[Unreleased]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.22.0...HEAD
+[2.22.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.21.0...v2.22.0
+[2.21.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.20.2...v2.21.0
 [2.20.2]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.20.1...v2.20.2
 [2.20.1]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.20.0...v2.20.1
 [2.20.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.19.0...v2.20.0

package/README.md

@@ -338,15 +338,20 @@ Shipped so far:
   a person when it is not;
 - 2.20 tools read from a service's own OpenAPI document, which an agent calls or an emulator plays,
   an emulator that holds what a whole evaluation did so examples that build on each other are
-  evaluated with nothing sent, and one A2A handler serving many tenants, each seeing only its own.
+  evaluated with nothing sent, and one A2A handler serving many tenants, each seeing only its own;
+- 2.21 typed decisions about pictures, a yes or no, a choice, a score, or a box around something in
+  one, from TypeSafe AI's Jev or any vision model; community adapters' compatibility records gathered
+  from their own CI, a failing one turning red; and 3.0's defaults behind one switch today;
+- 2.22 MCP over streamable HTTP both ways, with prompts, resources, and a server's questions back to
+  the client; OpenAPI tools that send each operation's credentials; tokens, API keys, and sessions the
+  server issues; and a studio that signs people in with your identity provider and serves many
+  tenants, each seeing only its own.
 
 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.21 asks typed decisions about pictures, and gathers community adapters' compatibility
-records from their own CI.
-Pinecone, images, the Gemini
-embedding batch tier, media understanding, video, Gemini Live, SIP, and both phone providers
-graduate once the live workflow passes against each. The
+Next, in 2.23, Pinecone, images, the Gemini embedding batch tier, media understanding, video, typed
+decisions, Gemini Live, SIP, and both phone providers graduate once the live workflow passes against
+each. The
 [roadmap](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/ROADMAP.md) lists what comes after, in the order
 applications ask for it.
 

package/SECURITY.md

@@ -281,9 +281,23 @@ Findings, each fixed in 2.5 with a test in `studio/test/security.test.ts`:
 - **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.
 
+Signing in and tenants, reviewed for 2.22, with tests in `studio/test/signin.test.ts` and
+`studio/test/tenants.test.ts`:
+- The provider's configuration must name the issuer the studio was given. An ID token must verify
+  against the provider's keys, name that issuer and the studio's client as its audience, and carry
+  the sign-in's nonce; a token for several clients must name the studio as `azp`.
+- The state, nonce, and PKCE verifier travel in a cookie signed for that purpose alone, for ten
+  minutes, so a callback from another browser, a late one, or a changed one is refused, and a sign-in
+  cookie is never taken as a session.
+- The page to come back to is always a path on the studio, never another site.
+- A tenant's people read only what `tenantSources` gives for their tenant. The studio itself keeps
+  comments and audit entries to their tenant, whatever the store does, and binds the page token to it.
+  `headerAuth()` with a tenant header refuses a request that lacks it.
+
 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.
+- Someone without a tenant reads the studio's own sources, the operators' view.
+- A session is a signed cookie, so one person's cannot be ended before it expires; rotating the
+  sign-in secret signs everyone out. Signing out is a plain link, which another site can follow.
 - 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.

package/dist/adapter-kit/gather.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Compatibility records gathered from where adapters' own CI publishes them: packages found on npm by
+ * a keyword, each naming its record's URL in its `package.json`, and sources listed by hand. Each
+ * record is read as `nexus adapters verify` sealed it, and must name the package that points to it.
+ * Nothing an adapter publishes is run: a gathered record is listed as its CI recorded it.
+ */
+import { type CompatibilityRecord } from './record.js';
+/** The npm keyword an adapter package carries to be found: `nexus-ai-pro-adapter`. */
+export declare const ADAPTER_KEYWORD = "nexus-ai-pro-adapter";
+/** Where one adapter's CI publishes its record. */
+export interface RecordSource {
+    /** The adapter's package name, which its record must name. */
+    package: string;
+    /** The record's URL: HTTPS, or HTTP to this machine. */
+    url: string;
+}
+/** Options for `gatherRecords()`. */
+export interface GatherRecordsOptions {
+    /**
+     * The keyword adapter packages are found by on npm, each naming its record's URL as
+     * `nexus.compatibility` in its `package.json`. Defaults to `ADAPTER_KEYWORD`; `false` finds none.
+     */
+    keyword?: string | false;
+    /** Sources listed by hand, beside those found; a listed package's URL is used over its own. */
+    sources?: readonly RecordSource[];
+    /** The npm registry. Defaults to `https://registry.npmjs.org`. */
+    registry?: string;
+    /**
+     * The records gathered last time: a package whose record cannot be read now, because its source is
+     * down or what it serves is refused, keeps its last one, and says why.
+     */
+    previous?: readonly CompatibilityRecord[];
+    /** The most bytes a record may have. Defaults to 1 MiB. */
+    maxBytes?: number;
+    /** How long each request may take, in milliseconds. Defaults to 15 seconds. */
+    timeoutMs?: number;
+    /** The most packages found by keyword. Defaults to 1,000. */
+    maxPackages?: number;
+    /** Replaces the global `fetch`. */
+    fetch?: typeof fetch;
+}
+/**
+ * What became of one package's record: `gathered` now; `kept` from last time, as now it could not be;
+ * `refused` or `unreachable` with nothing to keep; or `undeclared`, a package that names no record.
+ */
+export type GatherOutcome = 'gathered' | 'kept' | 'refused' | 'unreachable' | 'undeclared';
+/** One package's source, and what became of its record. */
+export interface GatheredSource {
+    /** The package's name. */
+    package: string;
+    /** Where its record is published, when it says. */
+    url?: string;
+    /** What became of it. */
+    outcome: GatherOutcome;
+    /** Why, for every outcome but `gathered`. */
+    detail?: string;
+    /** The record listed for it: gathered now, or kept. */
+    record?: CompatibilityRecord;
+}
+/** What `gatherRecords()` found. */
+export interface GatherReport {
+    /** Every record to list, gathered now or kept, by package name. */
+    records: CompatibilityRecord[];
+    /** Every package, by name, and what became of its record. */
+    sources: GatheredSource[];
+}
+/**
+ * Gathers the compatibility records adapters' own CI publishes: finds adapter packages on npm by
+ * `keyword`, reads where each publishes its record, and fetches each, with `sources` listed by hand.
+ * A record is gathered only when it reads as sealed, with a digest that matches it, and names the
+ * package that points to it; a package whose record cannot be read now keeps its `previous` one.
+ * Throws when npm cannot be searched, rather than reporting every adapter gone.
+ */
+export declare function gatherRecords(options?: GatherRecordsOptions): Promise<GatherReport>;
+/** The name of a package from how a record names it, such as `@acme/nexus-milvus` from `@acme/nexus-milvus@0.3.0`. */
+export declare function packageName(specifier: string): string;

package/dist/adapter-kit/gather.js

@@ -0,0 +1,147 @@
+import { readCompatibilityRecord } from './record.js';
+export const ADAPTER_KEYWORD = 'nexus-ai-pro-adapter';
+export async function gatherRecords(options = {}) {
+    const request = options.fetch ?? fetch;
+    const registry = (options.registry ?? 'https://registry.npmjs.org').replace(/\/+$/, '');
+    const timeoutMs = options.timeoutMs ?? 15_000;
+    const maxBytes = options.maxBytes ?? 1024 * 1024;
+    const get = (url) => request(url, { signal: AbortSignal.timeout(timeoutMs), redirect: 'follow' });
+    const found = new Map();
+    const keyword = options.keyword === undefined ? ADAPTER_KEYWORD : options.keyword;
+    if (keyword) {
+        for (const name of await search(get, registry, keyword, options.maxPackages ?? 1_000))
+            found.set(name, undefined);
+    }
+    for (const source of options.sources ?? [])
+        found.set(source.package, source.url);
+    const previous = new Map();
+    for (const record of options.previous ?? []) {
+        const name = record.adapter.package ? packageName(record.adapter.package) : undefined;
+        if (name)
+            previous.set(name, record);
+    }
+    const sources = [];
+    for (const name of [...found.keys()].sort()) {
+        const listed = found.get(name);
+        const result = await gatherOne(name, listed, { get, registry, maxBytes });
+        const last = previous.get(name);
+        if ((result.outcome === 'refused' || result.outcome === 'unreachable') && last) {
+            sources.push({ ...result, outcome: 'kept', record: last, detail: `${result.outcome}: ${result.detail}` });
+        }
+        else
+            sources.push(result);
+    }
+    return {
+        records: sources.flatMap((source) => (source.record ? [source.record] : [])),
+        sources,
+    };
+}
+export function packageName(specifier) {
+    const at = specifier.lastIndexOf('@');
+    return at > 0 ? specifier.slice(0, at) : specifier;
+}
+async function search(get, registry, keyword, limit) {
+    const names = [];
+    for (let from = 0; names.length < limit;) {
+        const url = `${registry}/-/v1/search?text=keywords:${encodeURIComponent(keyword)}&size=250&from=${from}`;
+        let page;
+        try {
+            const response = await get(url);
+            if (!response.ok)
+                throw new Error(`it answered ${response.status}`);
+            page = (await response.json());
+        }
+        catch (error) {
+            throw new Error(`npm could not be searched for "${keyword}": ${message(error)}`);
+        }
+        const objects = page.objects ?? [];
+        for (const item of objects)
+            if (typeof item.package?.name === 'string')
+                names.push(item.package.name);
+        from += objects.length;
+        if (objects.length === 0 || from >= (page.total ?? 0))
+            break;
+    }
+    return [...new Set(names)].slice(0, limit);
+}
+async function gatherOne(name, listed, context) {
+    let url = listed;
+    if (url === undefined) {
+        try {
+            const response = await context.get(`${context.registry}/${name.replace('/', '%2f')}/latest`);
+            if (!response.ok)
+                return { package: name, outcome: 'unreachable', detail: `npm answered ${response.status}` };
+            const manifest = (await response.json());
+            const declared = manifest.nexus?.compatibility;
+            if (typeof declared !== 'string' || !declared.trim()) {
+                return { package: name, outcome: 'undeclared', detail: 'its package.json names no nexus.compatibility record' };
+            }
+            url = declared.trim();
+        }
+        catch (error) {
+            return { package: name, outcome: 'unreachable', detail: `npm could not be read: ${message(error)}` };
+        }
+    }
+    if (!allowed(url))
+        return { package: name, url, outcome: 'refused', detail: `${url} is not HTTPS` };
+    let text;
+    try {
+        const response = await context.get(url);
+        if (response.url && !allowed(response.url)) {
+            return {
+                package: name,
+                url,
+                outcome: 'refused',
+                detail: `${url} redirects to ${response.url}, which is not HTTPS`,
+            };
+        }
+        if (!response.ok)
+            return { package: name, url, outcome: 'unreachable', detail: `${url} answered ${response.status}` };
+        const declared = Number(response.headers.get('content-length') ?? 0);
+        if (declared > context.maxBytes)
+            return tooLarge(name, url, declared, context.maxBytes);
+        text = await response.text();
+    }
+    catch (error) {
+        return { package: name, url, outcome: 'unreachable', detail: `${url} could not be read: ${message(error)}` };
+    }
+    const size = new TextEncoder().encode(text).length;
+    if (size > context.maxBytes)
+        return tooLarge(name, url, size, context.maxBytes);
+    let record;
+    try {
+        record = readCompatibilityRecord(text);
+    }
+    catch (error) {
+        return { package: name, url, outcome: 'refused', detail: message(error) };
+    }
+    const named = record.adapter.package;
+    if (!named)
+        return { package: name, url, outcome: 'refused', detail: 'the record names no package' };
+    if (packageName(named) !== name) {
+        return { package: name, url, outcome: 'refused', detail: `the record names ${named}, not ${name}` };
+    }
+    return { package: name, url, outcome: 'gathered', record };
+}
+function allowed(url) {
+    try {
+        const parsed = new URL(url);
+        if (parsed.protocol === 'https:')
+            return true;
+        return parsed.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(parsed.hostname);
+    }
+    catch {
+        return false;
+    }
+}
+function tooLarge(name, url, size, limit) {
+    return {
+        package: name,
+        url,
+        outcome: 'refused',
+        detail: `the record is ${size} bytes, over the ${limit}-byte limit`,
+    };
+}
+function message(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/adapter-kit/index.d.ts

@@ -20,6 +20,7 @@ import { type AdapterErrorClass } from './errors.js';
 import { type CompatibilityRecord, type CompatibilityRecordOptions } from './record.js';
 export { ADAPTER_CONTRACTS, ADAPTER_FIXTURE_PASSAGES, type AdapterCheck, type AdapterContract, type AdapterContractVersion, type RetrieverCapabilities, type RetrieverContractOptions, runRetrieverContract, runStoreContract, runVectorStoreContract, type StoreCapabilities, type VectorStoreCapabilities, type VectorStoreContractOptions, } from './contracts.js';
 export { AdapterError, type AdapterErrorClass, type AdapterErrorCode, classifyAdapterError } from './errors.js';
+export { ADAPTER_KEYWORD, type GatheredSource, type GatherOutcome, type GatherRecordsOptions, type GatherReport, gatherRecords, type RecordSource, } from './gather.js';
 export { type CheckChange, COMPATIBILITY_RECORD_FORMAT, type CompatibilityComparison, type CompatibilityPageOptions, type CompatibilityRecord, type CompatibilityRecordAdapter, CompatibilityRecordError, type CompatibilityRecordOptions, type CompatibilityState, type CompatibilityStatus, compareRecords, compatibilityPage, compatibilityRecord, readCompatibilityRecord, recordDigest, recordStatus, } from './record.js';
 export { parseVersion, satisfiesRange } from './semver.js';
 /** The kinds of adapter the kit builds. */

package/dist/adapter-kit/index.js

@@ -7,6 +7,7 @@ import { compatibilityRecord } from './record.js';
 import { satisfiesRange } from './semver.js';
 export { ADAPTER_CONTRACTS, ADAPTER_FIXTURE_PASSAGES, runRetrieverContract, runStoreContract, runVectorStoreContract, } from './contracts.js';
 export { AdapterError, classifyAdapterError } from './errors.js';
+export { ADAPTER_KEYWORD, gatherRecords, } from './gather.js';
 export { COMPATIBILITY_RECORD_FORMAT, CompatibilityRecordError, compareRecords, compatibilityPage, compatibilityRecord, readCompatibilityRecord, recordDigest, recordStatus, } from './record.js';
 export { parseVersion, satisfiesRange } from './semver.js';
 const OPERATIONS = {

package/dist/adapter-kit/record.d.ts

@@ -145,6 +145,8 @@ export interface CompatibilityPageOptions {
 /**
  * One page listing every record: each adapter, its kind and version, the release and contract it was
  * verified against, its state there, its checks, and its p95 per operation, by kind and name. The
- * same records make the same page, so it can be checked for drift.
+ * same records make the same page, so it can be checked for drift. A record is written as text, never
+ * as markup: an adapter links to its repository only at an `http` or `https` address, and the HTML
+ * page colours each row by its state, a failing one red.
  */
 export declare function compatibilityPage(records: readonly CompatibilityRecord[], options?: CompatibilityPageOptions): string;