nexus-ai-pro 2.19.0 → 2.21.0

package/API_STABILITY.md

@@ -41,6 +41,84 @@ 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.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.
+
+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.
@@ -655,7 +733,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,145 @@ Notable changes to this project are recorded here. The format follows [Keep a Ch
 
 ## [Unreleased]
 
+## [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
+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
@@ -3222,7 +3361,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.19.0...HEAD
+[Unreleased]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.21.0...HEAD
+[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
 [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

package/README.md

@@ -335,15 +335,19 @@ Shipped so far:
 - 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.
+  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;
+- 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.
 
 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.20 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.
-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.22, 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/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;

package/dist/adapter-kit/record.js

@@ -161,7 +161,7 @@ export function compatibilityPage(records, options = {}) {
             record,
             status,
             cells: [
-                record.adapter.repository
+                record.adapter.repository && /^https?:\/\//i.test(record.adapter.repository)
                     ? { text: record.adapter.name, href: record.adapter.repository }
                     : { text: record.adapter.name },
                 { text: record.adapter.kind },
@@ -187,7 +187,8 @@ export function compatibilityPage(records, options = {}) {
         const cell = (item) => item.href ? `<a href="${escapeHtml(item.href)}">${escapeHtml(item.text)}</a>` : escapeHtml(item.text);
         return [
             '<!doctype html>',
-            `<html lang="en"><head><meta charset="utf-8"><title>${escapeHtml(title)}</title></head><body>`,
+            `<html lang="en"><head><meta charset="utf-8"><title>${escapeHtml(title)}</title>`,
+            `<style>${STATE_STYLE}</style></head><body>`,
             `<h1>${escapeHtml(title)}</h1>`,
             ...(options.intro ? [`<p>${escapeHtml(options.intro)}</p>`] : []),
             `<p>States are judged against nexus-ai-pro ${escapeHtml(nexusVersion)}.</p>`,
@@ -207,9 +208,11 @@ export function compatibilityPage(records, options = {}) {
             '',
         ].join('\n');
     }
+    const literal = (text) => oneLine(text).replace(/[|[\]*_`\\]/g, (char) => `\\${char}`);
     const cell = (item) => {
-        const text = item.text.replace(/\|/g, '\\|');
-        return item.href ? `[${text}](${item.href.replace(/\|/g, '%7C')})` : text;
+        const text = literal(item.text);
+        const href = item.href?.replace(/[|\s()]/g, (char) => `%${char.charCodeAt(0).toString(16).toUpperCase().padStart(2, '0')}`);
+        return href ? `[${text}](${href})` : text;
     };
     return [
         `# ${title}`,
@@ -221,7 +224,10 @@ export function compatibilityPage(records, options = {}) {
         `| ${headers.map(() => '---').join(' | ')} |`,
         ...rows.map((row) => `| ${row.cells.map(cell).join(' | ')} |`),
         ...(notes.length > 0
-            ? ['', ...notes.map((row) => `- **${row.record.adapter.name}**: ${row.status.reasons.join('; ')}`)]
+            ? [
+                '',
+                ...notes.map((row) => `- **${literal(row.record.adapter.name)}**: ${row.status.reasons.map(literal).join('; ')}`),
+            ]
             : []),
         '',
     ].join('\n');
@@ -240,6 +246,15 @@ function runtimeName() {
 function isRecord(value) {
     return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
+const STATE_STYLE = [
+    'tr[data-state="passing"] td{color:#1a7f37}',
+    'tr[data-state="failing"] td{color:#cf222e;font-weight:600}',
+    'tr[data-state="incompatible"] td{color:#9a6700}',
+    'tr[data-state="stale"] td{color:#57606a}',
+].join('');
+function oneLine(text) {
+    return text.replace(/\s+/g, ' ').trim();
+}
 function escapeHtml(text) {
     return text.replace(/[&<>"']/g, (char) => `&#${char.charCodeAt(0)};`);
 }

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