nexus-ai-pro 2.21.0 → 2.22.0

package/API_STABILITY.md

@@ -67,6 +67,69 @@ 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.

package/CHANGELOG.md

@@ -4,6 +4,137 @@ 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
@@ -3361,7 +3492,8 @@ 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.21.0...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

package/README.md

@@ -341,11 +341,15 @@ Shipped so far:
   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.
+  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, in 2.22, Pinecone, images, the Gemini embedding batch tier, media understanding, video, typed
+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

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/agent/openapi.d.ts

@@ -44,6 +44,38 @@ export interface OpenApiOperation {
     tags: string[];
     /** What it does to the service, read from its method: `read` for GET, HEAD, OPTIONS, and TRACE, `destructive` for DELETE, and `write` for the rest. */
     access: 'read' | 'write' | 'destructive';
+    /**
+     * The security it asks for, as the document writes it: alternatives, any one of which will do, each
+     * the schemes it needs at once with their scopes. Empty when it asks for none.
+     */
+    security: Array<Record<string, string[]>>;
+}
+/**
+ * A credential for one of the API's security schemes: the API key, bearer token, or access token as
+ * text or `{ token }`; `{ username, password }` for HTTP basic; or `{ clientId, clientSecret }` for an
+ * OAuth 2.0 client-credentials flow, whose token is fetched and kept until it expires.
+ */
+export type OpenApiCredential = string | {
+    token: string;
+} | {
+    username: string;
+    password: string;
+} | {
+    clientId: string;
+    clientSecret: string;
+};
+/** A request or callback the API sends to the application, which no tool calls: its name and the body it carries. */
+export interface OpenApiWebhook {
+    /** The webhook's name, or the operation and callback it belongs to. */
+    name: string;
+    /** `webhook` for one of the document's webhooks, `callback` for an operation's callback. */
+    source: 'webhook' | 'callback';
+    /** The HTTP method it arrives with, in capitals. */
+    method: string;
+    /** For a callback, the expression that names where it is sent, such as `{$request.body#/callbackUrl}`. */
+    expression?: string;
+    /** The JSON Schema of the body it carries, when it carries JSON. */
+    body?: Record<string, unknown>;
 }
 /** What a tool's headers are chosen from: the operation, and the call's context. */
 export interface OpenApiHeadersRequest {
@@ -79,6 +111,15 @@ export interface OpenApiToolsOptions {
     maxResponseBytes?: number;
     /** Replaces the global `fetch`. */
     fetch?: typeof globalThis.fetch;
+    /**
+     * Credentials for the API's own security schemes, by the name the document gives each, or a
+     * function choosing one per call, such as by its tenant. Each call sends those its operation asks
+     * for: the first of its alternatives every scheme of which has a credential, as an API key in its
+     * header, query, or cookie, HTTP basic or bearer, or an OAuth 2.0 or OpenID Connect token. With
+     * credentials given, a call whose operation asks for schemes none of which has one fails before it
+     * is sent. They win over `headers`.
+     */
+    credentials?: Readonly<Record<string, OpenApiCredential | ((request: OpenApiHeadersRequest) => OpenApiCredential | Promise<OpenApiCredential>)>>;
 }
 /** An API's operations as tools, with what each returns. */
 export interface OpenApiTools {
@@ -92,19 +133,26 @@ export interface OpenApiTools {
     operations: OpenApiOperation[];
     /** The JSON Schema of what each tool returns, by name: its first success response's. Pass it to `emulatedTools()` as `results`. */
     results: Record<string, Record<string, unknown>>;
-    /** Operations that could not become tools, and why: a request body of a type the tools do not send. */
+    /**
+     * Operations that could not become tools, and why.
+     *
+     * @deprecated Every operation becomes a tool since 2.22, its body sent whatever its type, so this is
+     * always empty. It is removed in 3.0.
+     */
     skipped: Array<{
         method: string;
         path: string;
         reason: string;
     }>;
+    /** What the API sends the application, which no tool calls: its webhooks and its operations' callbacks. */
+    webhooks: OpenApiWebhook[];
 }
 /** Why an API could not be read into tools, or a call to it failed. */
 export declare class OpenApiError extends Error {
     /**
      * `OPENAPI_INVALID` for a malformed document or call, `OPENAPI_UNSUPPORTED` for one these tools
-     * cannot read, such as Swagger 2.0 or a reference outside the document, and `OPENAPI_REQUEST`
-     * for a call the API refused or did not answer.
+     * cannot read, such as Swagger 1.2 or a reference outside the document not bundled first, and
+     * `OPENAPI_REQUEST` for a call the API refused or did not answer.
      */
     readonly code: 'OPENAPI_INVALID' | 'OPENAPI_UNSUPPORTED' | 'OPENAPI_REQUEST';
     /** The HTTP status the API answered with, when it did. */
@@ -112,8 +160,8 @@ export declare class OpenApiError extends Error {
     constructor(message: string, 
     /**
      * `OPENAPI_INVALID` for a malformed document or call, `OPENAPI_UNSUPPORTED` for one these tools
-     * cannot read, such as Swagger 2.0 or a reference outside the document, and `OPENAPI_REQUEST`
-     * for a call the API refused or did not answer.
+     * cannot read, such as Swagger 1.2 or a reference outside the document not bundled first, and
+     * `OPENAPI_REQUEST` for a call the API refused or did not answer.
      */
     code: 'OPENAPI_INVALID' | 'OPENAPI_UNSUPPORTED' | 'OPENAPI_REQUEST', 
     /** The HTTP status the API answered with, when it did. */
@@ -124,7 +172,10 @@ export declare class OpenApiError extends Error {
  * method and path; described by its summary; its path, query, and header parameters, and the fields
  * of a JSON body, as the tool's parameters. Each declares `api.read`, `api.write`, or
  * `api.destructive` with the API's name and its own, as its method says, and `network` for the
- * API's host when it runs. References within the document are followed; one outside it is refused.
+ * API's host when it runs. References within the document are followed; one outside it is refused
+ * here, and followed by `loadOpenApiTools()` or `bundleOpenApiDocument()`. A Swagger 2.0 document is
+ * read as the OpenAPI 3 document it describes. Each call sends the credentials its operation's
+ * security asks for, from `credentials`.
  *
  * ```ts
  * const shop = openApiTools(JSON.parse(await readFile('shop.openapi.json', 'utf8')), {
@@ -135,5 +186,40 @@ export declare class OpenApiError extends Error {
  * ```
  */
 export declare function openApiTools(document: OpenApiDocument | string, options?: OpenApiToolsOptions): OpenApiTools;
-/** Fetches an OpenAPI document, as JSON, and reads it into tools, resolving its servers against where it came from. */
-export declare function loadOpenApiTools(url: string, options?: OpenApiToolsOptions): Promise<OpenApiTools>;
+/**
+ * Fetches an OpenAPI document, as JSON, and reads it into tools, resolving its servers against where
+ * it came from, and following its references to other documents on the same origin, or as
+ * `references` allows.
+ */
+export declare function loadOpenApiTools(url: string, options?: OpenApiToolsOptions & Pick<OpenApiBundleOptions, 'references' | 'maxDocuments' | 'maxBytes'>): Promise<OpenApiTools>;
+/**
+ * A Swagger 2.0 document as the OpenAPI 3.0 document it describes: its host, base path, and schemes
+ * as a server; its definitions, parameters, responses, and security definitions as components; a
+ * body parameter, and form data, as a request body of what it consumes; and each response's schema as
+ * content of what it produces. Every reference is moved with what it names.
+ */
+export declare function swaggerToOpenApi(swagger: Record<string, unknown>): OpenApiDocument;
+/** Options for `bundleOpenApiDocument()`. */
+export interface OpenApiBundleOptions {
+    /** Where the document came from: references outside it are read relative to it. */
+    documentUrl: string;
+    /**
+     * Which documents a reference may name: `same-origin`, the default, only those on the document's
+     * own origin; `any`, any HTTP or HTTPS URL; or a function deciding each. A document never makes the
+     * tools fetch where it was not allowed to.
+     */
+    references?: 'same-origin' | 'any' | ((url: string) => boolean);
+    /** The most documents read, the first included. Defaults to 50. */
+    maxDocuments?: number;
+    /** The largest document read, the first included, in bytes. Defaults to 5 MB. */
+    maxBytes?: number;
+    /** Replaces the global `fetch`. */
+    fetch?: typeof globalThis.fetch;
+}
+/**
+ * The document with every reference outside it read in its place: each other document fetched, as
+ * JSON, relative to the one that names it, its own references followed the same way, and a reference
+ * back to one still being read left as a description. `loadOpenApiTools()` does this before reading the
+ * document into tools.
+ */
+export declare function bundleOpenApiDocument(document: OpenApiDocument, options: OpenApiBundleOptions): Promise<OpenApiDocument>;