nexus-ai-pro 2.18.0 → 2.20.2

package/API_STABILITY.md

@@ -41,6 +41,69 @@ Both are covered by this policy:
 Deep imports into `dist`, `dist-cjs`, or `src` are not supported. Import only from `nexus-ai-pro` or
 one of its explicit subpaths.
 
+## How an item graduates
+
+A new surface starts this way:
+
+1. Provider-neutral types and a deterministic mock land first.
+2. One real adapter proves the contract; conformance fixtures cover it.
+3. A second adapter on a different wire protocol proves portability.
+4. Packed-package, clean-install, and consumer type-resolution tests pass on every supported Node
+   line.
+5. Evaluation appropriate to the modality covers the supported capability matrix.
+
+It leaves experimental status here only when every item below has evidence, published with the
+graduation:
+
+| Requirement | Evidence |
+| --- | --- |
+| API stability | Covered by the 2.x compatibility rules, with no planned breaking change |
+| Conformance | Passes its contract suite on every supported backend |
+| Crash recovery | Crash-injection tests at each durable boundary, where it has one |
+| Concurrency | Race tests with several processes on the same records |
+| Load | A published benchmark with a budget in CI |
+| Tenant isolation | The isolation suite, where it stores tenant data |
+| Security | A written threat review, with its findings closed |
+| Upgrade | A migration test from the previous minor |
+| Soak | A long-running test with flat memory and no leaked handles |
+
+## 2.20 stage (2.20.0)
+
+Everything 2.20 adds is stable from the start and additive, unless this section says otherwise.
+
+New and stable:
+- `nexus-ai-pro/agent/openapi`: `openApiTools()`, `loadOpenApiTools()`, `OpenApiError`,
+  `OpenApiDocument`, `OpenApiOperation`, `OpenApiTools`, `OpenApiToolsOptions`, and
+  `OpenApiHeadersRequest`;
+- the capabilities `api.read`, `api.write`, and `api.destructive`;
+- in `nexus-ai-pro/evaluate/emulate`: `EmulatedWorld`, `EmulatedWorldCall`, `EmulatedWorldSnapshot`,
+  `EmulatedToolsOptions.world` and `reads`, and `emulationKey()`'s `world`. A key without a world is
+  the key of every earlier release;
+- in `nexus-ai-pro/protocols/a2a`: `A2aServerOptions.tenants`, `A2aTenancyOptions`,
+  `A2aClientOptions.tenant`, `A2aTaskRecord.tenant`, `A2aTaskQuery.tenant`, `A2A_ERRORS.permissionDenied`,
+  the card's `securitySchemes`, `securityRequirements`, and `signatures`, `A2aSkill.securityRequirements`,
+  `A2aSecurityScheme`, `A2aOAuthFlows`, `A2aSecurityRequirement`, and `A2aCardSignature`.
+
+Changed on purpose: the gRPC binding writes and reads a card's security schemes, requirements, and
+signatures, which it read past; without `tenants`, a request's tenant is still not read. A custom
+`A2aTaskStore` serving several tenants should honour `A2aTaskQuery.tenant`, for full pages; the handler
+filters by tenant either way.
+
+## 2.19 stage (2.19.0)
+
+Everything 2.19 adds is stable from the start and additive, unless this section says otherwise.
+
+New and stable:
+- in the root: `CompletionRequest.logprobs`, `NexusResponse.logprobs`, `TokenLogprob`, and
+  `ModelCapabilities.logprobs`;
+- in `nexus-ai-pro/workflows`: `ClassifyRouteOptions.decisions`.
+
+New and experimental, until the live workflow passes against TypeSafe AI's Jev and a model that
+reports log probabilities: the typed decisions family, `nexus-ai-pro/decisions`,
+`nexus-ai-pro/decisions/typesafe`, and `nexus-ai-pro/decisions/mock`.
+
+Changed on purpose: `OperationFamily` and `RunKind` widen with `decision`.
+
 ## 2.18 stage (2.18.0)
 
 Everything 2.18 adds is stable from the start and additive, unless this section says otherwise.
@@ -640,7 +703,7 @@ These security fixes tighten more behavior, each closing a finding of a graduati
 ### Graduation
 
 A surface left experimental status in 2.4 only when every requirement in
-[How an item graduates](./ROADMAP.md#how-an-item-graduates) had evidence. That evidence is below.
+[How an item graduates](#how-an-item-graduates) had evidence. That evidence is below.
 "n/a" names a requirement that does not apply, and says why. Every test named here runs in CI.
 Load and soak budgets are checked by `npm run bench:surfaces` and `npm run bench:runtime`, which are
 part of `check:release`. Upgrade tests run against the published 2.3.0 package, installed as a

package/CHANGELOG.md

@@ -4,6 +4,114 @@ Notable changes to this project are recorded here. The format follows [Keep a Ch
 
 ## [Unreleased]
 
+## [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
+stopped at a studio test that failed by chance, so neither reached npm.
+
+### Fixed
+
+- The studio's load budget is judged by the fastest of five passes, after three warm-up passes
+  rather than one. The median of five failed the 2.20.1 publish at 3.61 calibration loops: its first
+  three passes took 91 to 102 ms and its last two 37 and 48 ms. A busy runner only ever adds time,
+  while a real slowdown slows every pass, so a request made 0.1 ms slower still fails it, at 4.3 loops.
+
+## [2.20.1] - 2026-10-24 (not published)
+
+The package is 2.20.0's. Its publish stopped at the same studio test, measured another way.
+
+### Fixed
+
+- The studio's load budget is measured as the median of five passes, as the surface budgets are,
+  rather than one: a single slow pass on a busy runner failed the 2.20.0 publish at 2.56 calibration
+  loops against a budget of 2.55, where the test measures 0.77. A real slowdown still fails it.
+
+## [2.20.0] - 2026-10-24 (not published)
+
+Tools read from a service's OpenAPI document, an emulator that remembers the evaluation, and one A2A
+handler serving many tenants.
+
+### Added
+
+- **Tools from an OpenAPI document.** `openApiTools()` and `loadOpenApiTools()`, on
+  `nexus-ai-pro/agent/openapi`, read an OpenAPI 3.0 or 3.1 document into one tool per operation: its
+  name, description, and parameters the API's, its body's fields flattened, references followed, and
+  each declaring `api.read`, `api.write`, or `api.destructive` as its method says, with `network` for
+  the API's host. Given where the API lives, each tool calls it, the path encoded, the application's
+  headers sent, no redirect followed, and an answer read only up to a limit; a refusal is an
+  `OpenApiError` in the API's own words. `results` holds the schema of what each returns.
+- **An emulator that remembers the evaluation.** An `EmulatedWorld`, given to `emulatedTools()` as
+  `world`, holds the scenario and every call across the runs of an evaluation, so a change one example
+  makes is there for the next; the emulator is told every change. `snapshot()` writes it as JSON,
+  `fork()` and `new EmulatedWorld(snapshot)` start runs from it, and the key of each answer kept carries
+  the world's `digest()`, so a recorded evaluation replays only after the same changes. `reads` names
+  tools that change nothing, beside those whose capabilities only read.
+- **Capabilities for an API's operations:** `api.read:<api>/<operation>`, `api.write`, and
+  `api.destructive`, decided by a permission policy as MCP's are.
+- **A2A for several tenants.** `a2aHandler({ tenants })` routes each request by the `tenant` it names,
+  in its params, its path (`/{tenant}/message:send`), or its gRPC message. Each tenant's tasks and
+  conversations are its own, its runs carry the tenant on their principal, and a caller that may not
+  act for the tenant it names is refused with `A2A_ERRORS.permissionDenied`, HTTP 403 and
+  `PERMISSION_DENIED` over gRPC. `A2aTenancyOptions` sets who may, and whether a tenant is required.
+  Task stores keep and list by tenant. A client names its interface's tenant, or its `tenant` option,
+  on every request, as protocol 1.0 requires.
+- **A card's security.** `securitySchemes` (`A2aSecurityScheme`, with `A2aOAuthFlows`),
+  `securityRequirements` (`A2aSecurityRequirement`, on the card and on a skill), and `signatures`
+  (`A2aCardSignature`) are part of the card, and the gRPC binding writes and reads them, which it read
+  past before.
+
+### Fixed
+
+- The prompt densifier joined a code block's fences to the text around them, so a block it meant to
+  keep stopped being one; it shortened phrases inside other words, turning "in order today" into
+  "today"; and it lowercased a phrase that began a sentence.
+- A test of a call that never answers, and the unit, coverage, and studio runs, no longer let a hung
+  test hold the release gate: every synchronous child the tests start has a timeout, and a test that
+  runs past five minutes fails.
+
+## [2.19.0] - 2026-10-24
+
+Typed decisions: a yes or no, a choice, or a score, answered with probabilities and a confidence read
+from them, from TypeSafe AI's Jev or from any model, acted on when sure and sent to a person when not.
+
+### Added
+
+- **Typed decisions.** `nexus-ai-pro/decisions` asks a `DecisionRequest`'s questions of one state: a
+  `YesNoQuestion`, a `ChoiceQuestion` of up to 255 options, or a `ScoreQuestion` of up to ten levels,
+  each answered in isolation with its probabilities and a confidence read the same way from any
+  provider. Answers are typed by their questions, so a choice's answer names only its options.
+  `DecisionManager` refuses a malformed question before it is sent, fails over, caches, traces each
+  decision as a run of kind `decision`, and runs it as an operation of the client, family
+  `decision`, budgeted at its model's price and on the tenant's key.
+- **TypeSafe AI's Jev.** `TypeSafeDecisionProvider`, on `nexus-ai-pro/decisions/typesafe`, speaks the
+  System One API: every question of a decision in one call, its refusals naming the field at fault,
+  priced at $42 per billion input tokens with output free.
+- **Decisions from any model.** `completionDecisions()` asks a completion model each question for a
+  one-token code, and reads its probabilities from that token's log probabilities where the provider
+  reports them, or counts them over samples where it does not, or refuses to.
+- **Gates and calibration.** `gate()` acts, sends to a person, or abstains by confidence; `calibrate()`
+  measures how answers' probabilities track how often they are right, and chooses the threshold that
+  holds a target accuracy on the application's own labelled answers.
+- **Decisions where the package decides.** `decisionRoute()` for a graph's branch, `decisionPermissions()`
+  for an agent's tool calls, `decisionGuard()` and `decisionModel()` as agent middleware,
+  `decisionEvaluator()` and `reviewUnsure()` for evaluation, and `classifyRoute()`'s `decisions`:
+  an uncertain answer goes to a person.
+- **Log probabilities.** `CompletionRequest.logprobs` asks for each answer token's log probability and
+  its alternatives, on `NexusResponse.logprobs` as `TokenLogprob` values, from OpenAI's Chat
+  Completions, the OpenAI-compatible adapters that report them, Gemini, and Ollama;
+  `ModelCapabilities.logprobs` declares a model that cannot.
+- `MockDecisionProvider`, on `nexus-ai-pro/decisions/mock`, and `runDecisionConformance()`.
+
+### Changed
+
+- `OperationFamily` and `RunKind` have `decision`; a `switch` over either that names every one needs
+  the new one.
+
+### Fixed
+
+- A test that waits forever fails at five minutes, and every child process the tests start
+  synchronously has a timeout of its own: the 2.18.0 publish's first attempt waited two hours on one.
+
 ## [2.18.0] - 2026-10-22
 
 Span events and links, media that knows its length, a tenant's threads and runs listed and paged
@@ -3179,7 +3287,11 @@ 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.18.0...HEAD
+[Unreleased]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.20.2...HEAD
+[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
+[2.19.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.18.0...v2.19.0
 [2.18.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.17.0...v2.18.0
 [2.17.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.16.0...v2.17.0
 [2.16.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.15.1...v2.16.0

package/README.md

@@ -156,6 +156,7 @@ from the doc comments. The guides live in the repository, so these links go to G
 | [Retrieval](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/retrieval.md) | Hybrid search, reranking, MMR, parent documents, and Redis, Pinecone, Weaviate, and Chroma stores |
 | [Embeddings and retrieval](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/embeddings.md) | Embeddings as a routed operation family, and RAG helpers |
 | [Media understanding](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/media.md) | Reading documents and images page by page, describing images, and answering questions about them, through any vision model or OCR |
+| [Typed decisions](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/decisions.md) | A yes or no, a choice, or a score, answered with probabilities and a calibrated confidence, from TypeSafe AI's Jev or any model, so a graph, an approval, or a guardrail acts when it is sure and asks a person when not |
 | [Video generation](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/video.md) | Videos from a prompt or a first frame, on Google Veo and Runway, as durable jobs streamed into an asset store and priced per second |
 | [Images (experimental)](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/images.md) | Generation and masked edits over three backends, input safety, moderation, asset stores |
 | [Voice](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/voice.md) | Transcription, speech, voice turns, and voice sessions |
@@ -330,12 +331,19 @@ Shipped so far:
   video is extended from its own job or edited on Gemini Omni Flash, Veo, and Runway;
 - 2.18 span events and links, as OpenTelemetry has them, media that knows its length from its own
   headers, a tenant's threads and runs listed and paged across all of its regions, MCP servers that
-  reconnect and change their tools within a session, and videos made after reference videos.
+  reconnect and change their tools within a session, and videos made after reference videos;
+- 2.19 typed decisions: a yes or no, a choice, or a score, answered with probabilities and a
+  confidence, from TypeSafe AI's Jev or from any model's log probabilities, gated by thresholds a
+  calibration chooses, so a graph's branch, an approval, or a guardrail acts when it is sure and asks
+  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.
 
 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.19 reads a service's own API description into emulated tools, and lets an emulator hold
-what a whole evaluation did, so examples that build on each other are evaluated with nothing sent.
+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

package/dist/agent/capabilities.d.ts

@@ -12,6 +12,9 @@ import type { ToolDefinition } from '../types/messages.js';
  * | `mcp.read:<server>/<tool>` | An MCP tool its server says only reads |
  * | `mcp.write:<server>/<tool>` | An MCP tool its server says changes things but destroys nothing |
  * | `mcp.destructive:<server>/<tool>` | An MCP tool its server says may destroy or overwrite |
+ * | `api.read:<api>/<operation>` | An operation of an OpenAPI document whose method only reads |
+ * | `api.write:<api>/<operation>` | One whose method changes things |
+ * | `api.destructive:<api>/<operation>` | One whose method deletes |
  * | `<name>`, `<name>:<detail>` | Anything the application names, such as `payments:refund` |
  *
  * A tool that declares `capabilities: []` does nothing to the world; one that declares none at all

package/dist/agent/openapi.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Tools read from a service's own API description, an OpenAPI document: one tool per operation, its
+ * name, description, and parameters the service's, the capabilities it declares read from its method,
+ * and what it returns kept as a schema. Given where the API lives, each tool calls it; without, the
+ * tools describe the API and run nowhere, as `emulatedTools()` wants them.
+ */
+import type { ToolContext, ToolDefinition } from '../types/messages.js';
+/** An OpenAPI 3 document, as parsed JSON. Only what tools are read from is typed. */
+export interface OpenApiDocument {
+    /** The OpenAPI version, `3.0.x` or `3.1.x`. */
+    openapi: string;
+    /** The API's title and version. */
+    info?: {
+        title?: string;
+        version?: string;
+        description?: string;
+    };
+    /** Where the API is served. */
+    servers?: Array<{
+        url: string;
+        variables?: Record<string, {
+            default: string;
+        }>;
+    }>;
+    /** Its operations, by path and method. */
+    paths?: Record<string, Record<string, unknown>>;
+    /** Schemas, parameters, request bodies, and responses its operations refer to. */
+    components?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+/** One operation of the API, as a tool reads it. */
+export interface OpenApiOperation {
+    /** The tool's name: the operation's id, or its method and path. */
+    name: string;
+    /** The HTTP method, in capitals. */
+    method: string;
+    /** The path, with its `{parameters}`. */
+    path: string;
+    /** The operation's id, when it has one. */
+    operationId?: string;
+    /** Its summary, when it has one. */
+    summary?: string;
+    /** Its tags. */
+    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';
+}
+/** What a tool's headers are chosen from: the operation, and the call's context. */
+export interface OpenApiHeadersRequest {
+    /** The operation being called. */
+    operation: OpenApiOperation;
+    /** The call's context: its tenant, principal, and thread. */
+    context?: ToolContext;
+}
+/** Options for `openApiTools()`. */
+export interface OpenApiToolsOptions {
+    /** The API's name, in each tool's capabilities. Defaults to its title, as a slug, or `api`. */
+    name?: string;
+    /**
+     * Where the API lives, its path prefix included, such as `https://shop.example.com/api`. Defaults
+     * to the document's first server, resolved against `documentUrl` when relative. Without one, the
+     * tools describe the API and run nowhere.
+     */
+    baseUrl?: string;
+    /** Where the document came from, to resolve a relative server URL against. */
+    documentUrl?: string;
+    /**
+     * Headers every call sends, such as authorization, or a function choosing them per operation and
+     * call, such as by its tenant. They win over a header parameter the model sets.
+     */
+    headers?: Readonly<Record<string, string>> | ((request: OpenApiHeadersRequest) => Record<string, string> | Promise<Record<string, string>>);
+    /** Which operations become tools. Defaults to every one. */
+    include?: (operation: OpenApiOperation) => boolean;
+    /** Put before every tool's name, with an underscore, so two APIs' operations stay apart. */
+    prefix?: string;
+    /** How long a call may take, in milliseconds. Defaults to 30 seconds. */
+    timeoutMs?: number;
+    /** The largest answer a call reads, in bytes; a larger one fails the call. Defaults to 1 MB. */
+    maxResponseBytes?: number;
+    /** Replaces the global `fetch`. */
+    fetch?: typeof globalThis.fetch;
+}
+/** An API's operations as tools, with what each returns. */
+export interface OpenApiTools {
+    /** The API's name, as its tools' capabilities carry it. */
+    name: string;
+    /** Where the tools send their calls, when they run. */
+    baseUrl?: string;
+    /** One tool per operation. */
+    tools: ToolDefinition[];
+    /** The operations, in the tools' order. */
+    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. */
+    skipped: Array<{
+        method: string;
+        path: string;
+        reason: string;
+    }>;
+}
+/** 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.
+     */
+    readonly code: 'OPENAPI_INVALID' | 'OPENAPI_UNSUPPORTED' | 'OPENAPI_REQUEST';
+    /** The HTTP status the API answered with, when it did. */
+    readonly status?: number | undefined;
+    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.
+     */
+    code: 'OPENAPI_INVALID' | 'OPENAPI_UNSUPPORTED' | 'OPENAPI_REQUEST', 
+    /** The HTTP status the API answered with, when it did. */
+    status?: number | undefined);
+}
+/**
+ * Reads an OpenAPI 3 document into tools, one per operation: named by its `operationId`, or its
+ * 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.
+ *
+ * ```ts
+ * const shop = openApiTools(JSON.parse(await readFile('shop.openapi.json', 'utf8')), {
+ *   baseUrl: 'https://shop.example.com/api',
+ *   headers: { authorization: `Bearer ${process.env.SHOP_TOKEN}` },
+ * });
+ * const agent = createAgent({ client: ai, tools: shop.tools });
+ * ```
+ */
+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>;