nexus-ai-pro 2.16.0 → 2.18.0

package/API_STABILITY.md

@@ -41,6 +41,63 @@ 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.
 
+## 2.18 stage (2.18.0)
+
+Everything 2.18 adds is stable from the start and additive, unless this section says otherwise.
+
+New and stable:
+- in `nexus-ai-pro/tracing`: `RunEvent`, `RunLink`, `RunAttributeValue`, `RunEventInput`, `RunLinkInput`,
+  `Run.events`, `droppedEvents`, and `links`, `Tracer.event()`, `RunHandle.event()` and `link()`,
+  `StartRunOptions.links`, `FinishRunOptions.events` and `links`, `TracerOptions.maxEventsPerRun`, and
+  the event names `retry`, `failover`, `progress`, `guardrail`, `cache`, and `capability_warning`;
+- in `nexus-ai-pro/tracing/otlp`: `OtlpSpanEvent`, `OtlpSpanLink`, and `OtlpSpan.events`,
+  `droppedEventsCount`, and `links`;
+- in the root: `ResponseAttempt` and `ResponseMeta.failedAttempts`;
+- in `nexus-ai-pro/evaluate/media`: `readMediaDuration()` and `MediaDuration`;
+- in `nexus-ai-pro/video`, experimental with the family: `VideoModelCapabilities.maxInputVideoSeconds`;
+- in `nexus-ai-pro/server/regions`: `RegionalGatewayOptions.lists`, `RegionListGap`, and a merged
+  list's `regions`, `incomplete`, and `nextCursor`;
+- in `nexus-ai-pro/server`: `ListPage`, `RunManager.listThreads()` and `listRuns()`, and the lists'
+  `cursor` and `nextCursor`;
+- in `nexus-ai-pro/mcp`: `McpClientOptions.reconnect`, `McpClient.onToolsChanged()`, and
+  `SseClientOptions.reopen`;
+- in `nexus-ai-pro/video`, experimental with the family: `VideoGenerateRequest.referenceVideos` and
+  `VideoProviderRequest.referenceVideos`, the `reference-videos` input kind,
+  `VideoModelCapabilities.maxReferenceVideos` and `referenceVideoSeconds`, and
+  `VideoConformanceOptions.referenceVideo`;
+- in `nexus-ai-pro/video/google`, experimental with the family:
+  `GoogleVideoProviderConfig.interactionsBaseUrl`, and Gemini Omni Flash on Vertex AI.
+
+Changed on purpose:
+- a list through the regional gateway is merged from every region the tenant may reach;
+  `lists: 'home'` keeps the earlier answer;
+- an agent server's lists are ordered by last write, then id, and a `limit` that is not a whole
+  number above 0 is refused;
+- `McpServer` says `tools.listChanged`, and `register()` sends the notification;
+- `VideoInputKind` widens with `reference-videos`.
+
+## 2.17 stage (2.17.0)
+
+Everything 2.17 adds is stable from the start and additive, unless this section says otherwise.
+
+New and stable:
+- in `nexus-ai-pro/mcp`: `createSseTransport()`, `SseClientOptions`, `mcpToolCapabilities()`,
+  `mcpToolAnnotations()`, `McpToolAnnotations`, `McpToolsOptions`, and `McpToolDescriptor.annotations`;
+  the capability kinds `mcp.read`, `mcp.write`, and `mcp.destructive`;
+- in `nexus-ai-pro/protocols/acp/editor`: `AcpEditorOptions.mcpToolCapabilities` and
+  `AcpEditor.mcpCapabilities`; in `nexus-ai-pro/protocols/acp`: `AcpEditorBridge.mcpCapabilities`;
+- in `nexus-ai-pro/video`, experimental with the family: `VideoSource`, `VideoGenerateRequest.video`,
+  `VideoProviderRequest.video`, the `VideoInputKind` values `extend` and `edit`,
+  `VideoModelCapabilities.extendDurations`, `requires`, and `continuesJobs`,
+  `VideoProviderCapabilities.inputVideoMimeTypes`, and `VideoConformanceOptions.video`; Gemini Omni
+  Flash in `nexus-ai-pro/video/google`, and video to video in `nexus-ai-pro/video/runway`.
+
+Changed on purpose: `acpEditor()` reads MCP tool annotations by default. A policy that allowed the
+editor's MCP tools as undeclared (`undeclared: 'allow'`) now decides annotated tools by their
+capabilities; `mcpToolCapabilities: false` keeps the earlier decisions. `GoogleVideoProvider`'s
+default models follow Google's shutdown of the Veo 3.1 previews: Gemini Omni Flash on the Gemini API,
+and the generally available Veo 3.1 models on Vertex AI.
+
 ## 2.16 stage (2.16.0)
 
 Everything 2.16 adds is stable from the start and additive, unless this section says otherwise.

package/CHANGELOG.md

@@ -4,6 +4,134 @@ Notable changes to this project are recorded here. The format follows [Keep a Ch
 
 ## [Unreleased]
 
+## [2.18.0] - 2026-10-22
+
+Span events and links, media that knows its length, a tenant's threads and runs listed and paged
+across all of its regions, MCP servers that reconnect and change their tools mid-session, and videos
+made after reference videos.
+
+### Added
+
+- **Span events and links.** A run records what happened inside it as `RunEvent` values, each at its
+  time, and the runs it came from beside its parent as `RunLink` values. `Tracer.event()` records on
+  the run in scope, `RunHandle.event()` and `link()` on one run; `StartRunOptions.links` take a link
+  or a W3C `traceparent`, and `FinishRunOptions` take the `events` and `links` a run learns as it
+  ends. `maxEventsPerRun` (128) keeps a run's events bounded, counting the rest as `droppedEvents`.
+  Both reach OTLP as span events and links, in JSON, in protobuf, and over gRPC. The studio shows them
+  on a run, each link opening the run it names, and `#/traces/<trace>/<run>` opens one run of a trace.
+- **Events where they happen.** A graph's retry is a `retry` event of its task's run, a tool's
+  progress a `progress` event of the tool's, and a task after a step of several, such as a fan-out's
+  join, links to each of them. A model run has the attempts that failed before its answer, as `retry`
+  and `failover` at the times they failed, and its guardrails, cache answer, and capability warnings.
+- **Failed attempts on the response.** `ResponseMeta.failedAttempts` lists each `ResponseAttempt` that
+  failed before the answer: its provider, model, error, category, and time; a stream's last chunk
+  carries them too.
+- **Media that knows its length.** `readMediaDuration()`, on `nexus-ai-pro/evaluate/media`, reads the
+  length of WAV, MP4 and MOV (fragmented MP4 included), WebM and Matroska, MP3, Ogg Vorbis and Opus,
+  and FLAC from their own headers, with no dependency. `mediaChecks()` holds audio and video to a
+  `durationMs` range with it, and a video model's `maxInputVideoSeconds` refuses a longer video before
+  it is sent: 10 seconds on Gemini Omni Flash, 30 on Veo.
+- **Lists across regions.** The regional gateway answers `GET /threads` and `GET /runs` from every
+  region the tenant may reach, merged newest first and cut to the limit, naming the regions that
+  answered and, as `RegionListGap` values under `incomplete`, those that were down or failed. A
+  refusal every region gives is the answer. `lists: 'home'` keeps the home region's list alone.
+- **Lists that page.** An agent server's `GET /threads`, `GET /runs`, and `GET /threads/:id/runs`
+  take a `cursor` and answer with a `nextCursor` while more follow; `RunManager.listThreads()` and
+  `listRuns()` return a `ListPage`. A cursor names a place in the order every region lists by, so the
+  regional gateway pages a merged list with it too, each record once, in order, however the records
+  fall between regions. A region that does not page by it contributes only what comes after it.
+- **MCP that reconnects.** With `McpClientOptions.reconnect`, a client whose connection closed opens
+  it again at the next request and greets the server again: an SSE stream that ended, with
+  `SseClientOptions.reopen`, or a stdio server that exited, started again. A stream that cannot open,
+  or names no endpoint in time, is let go at once, so the next request tries again.
+- **Tools that change.** `McpClient.onToolsChanged()` hears a server's
+  `notifications/tools/list_changed`. `McpServer.register()` sends one to a connected client, and the
+  server says it will. The editor bridge reconnects an editor's SSE servers within a session and lists
+  a server's tools again before the turn after it says they changed, keeping the last list when that
+  fails.
+- **Reference videos.** `VideoGenerateRequest.referenceVideos` gives a model videos to take after.
+  Models declare `reference-videos` among their inputs, with `maxReferenceVideos` and
+  `referenceVideoSeconds`, each and together, read from a video's headers before it is sent. Gemini
+  Omni Flash takes three of three seconds each, as does Runway's `gemini_omni_flash_1.1`; Runway's
+  Seedance 2 models, `hailuo3`, and `wan3` take 15 seconds together, beside reference images. The
+  conformance suite checks them with `referenceVideo`.
+- **Gemini Omni Flash on Vertex AI.** `GoogleVideoProvider` serves `gemini-omni-1.1-flash-preview` on
+  Vertex AI's Interactions API, at the global location for the project its `baseUrl` names, or at
+  `interactionsBaseUrl`.
+
+### Changed
+
+- A list of threads or runs through the regional gateway comes from every region the tenant may
+  reach, not its home region alone; `RegionalGatewayOptions.lists: 'home'` keeps the 2.17 answer.
+- An agent server lists threads and runs by when each was last written, then by id, the order its
+  cursor pages by. A `limit` that is not a whole number above 0 is refused with a 400.
+- `McpServer` says its tools change, as `tools.listChanged`, and `register()` tells a connected
+  client.
+- `VideoInputKind` has `reference-videos`; a `switch` over it that names every kind needs the new one.
+- Tested on Node.js 26 as well as 22 and 24: CI runs the release gate on each, on the newest patch of
+  its line, so a Node.js security release, such as 2026-10-21's, is what the package is tested and
+  published on the day it ships.
+
+### Fixed
+
+- A tenant's threads and runs on a server several tenants share: a list read the newest records of
+  every tenant and then kept the tenant's, so another tenant's newer ones could crowd its page out,
+  down to an empty one. A list now reads until the tenant's page is full.
+- The studio showed a run's metadata, its feedback, and a tool's progress as
+  `[object HTMLHeadingElement]` rather than their content.
+
+## [2.17.0] - 2026-10-21
+
+The editor's MCP servers over every transport, decided by what their servers say they do; and video
+extended or edited on every provider, with Gemini Omni Flash on Google's Interactions API.
+
+### Added
+
+- **Video extended or edited.** A `VideoGenerateRequest` takes a `video`, a `VideoSource`: `extend`
+  continues it, and `edit` changes it as the prompt says. The video is an input (bytes, a URL, or a
+  stored asset), or `from` a finished job of the same provider, which continues from what it holds
+  with nothing uploaded. Models declare `extend` and `edit` among their `inputs`, with
+  `extendDurations`, `continuesJobs`, and `requires`, and providers their `inputVideoMimeTypes`;
+  anything a model cannot do is refused before it is sent, and the input travels with a durable
+  generation. The conformance suite checks extending and editing, and continuing a job.
+- **Gemini Omni Flash on the Interactions API.** `GoogleVideoProvider` serves `gemini-omni-1.1-flash`
+  as a background interaction: 3 to 10 seconds at 360p to 4k, from a prompt, a first frame, or
+  reference images, extending and editing videos, continuing its own interactions by id, cancelled and
+  deleted with them. It is priced at its 720p token rate.
+- **Veo extends on Vertex AI.** Veo 3.1 extends a video in Cloud Storage by seven seconds, or a job of
+  its own when `storageUri` keeps its videos there, and makes up to four videos a request.
+- **Runway's video to video.** `gemini_omni_flash_1.1` extends and edits, `gemini_omni_flash` edits,
+  and `aleph2`, now among the models, only edits, from a video by URL, inline up to 5 MB, or a task's
+  own video.
+
+- **MCP over SSE.** `createSseTransport()`, on `nexus-ai-pro/mcp`, speaks to a server over HTTP with
+  Server-Sent Events, MCP's transport before streamable HTTP: one `GET` on the event stream, a `POST`
+  per message to the endpoint the stream names, kept to the stream's origin. An ACP agent connects the
+  SSE servers an editor offers, beside stdio and HTTP.
+- **MCP tools that declare what they do.** `toNexusTools({ capabilities: true })` gives each tool the
+  capabilities its server's annotations describe, from `mcpToolCapabilities()`: `mcp.read`,
+  `mcp.write`, or `mcp.destructive` under the server's name, and `network` for one that reaches
+  beyond it, with the specification's defaults for a hint left out. A permission policy then decides a
+  server's tools as it decides the agent's own: `{ custom: { 'mcp.read': 'allow' } }` runs a lookup
+  and refuses a delete, with no rule naming either. A function decides per tool instead.
+- **The package's MCP server says what its tools do.** `McpServer` lists each tool with the
+  annotations its capabilities give it, from `mcpToolAnnotations()`, never claiming less than the
+  tool may do.
+
+### Changed
+
+- **Google's video defaults follow its shutdown of the Veo 3.1 previews on 2026-10-22.** On the Gemini
+  API, `GoogleVideoProvider` serves Gemini Omni Flash by default; on Vertex AI, the generally
+  available `veo-3.1-generate-001` and `veo-3.1-fast-generate-001`, and `veo-3.1-lite-generate-001`.
+  Name the preview models in `models` to keep them until Google stops serving them.
+- `acpEditor()` reads its MCP servers' annotations by default (`mcpToolCapabilities`), so an
+  annotated tool is decided by its capabilities rather than as undeclared; `mcpToolCapabilities: false`
+  keeps the 2.16 behaviour. A tool its server says nothing about is undeclared, as before.
+- The ACP agent tells the editor, in `initialize`, that it connects MCP servers over HTTP and SSE, so
+  an editor that follows the protocol offers them; before, it offered only stdio servers.
+- The nightly interoperability check offers the ACP agent MCP servers built with
+  `@modelcontextprotocol/sdk` over stdio, HTTP, and SSE.
+
 ## [2.16.0] - 2026-10-20
 
 A2A on all three of its bindings over one set of tasks, and webhooks told the answer as it is written.
@@ -3051,7 +3179,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.16.0...HEAD
+[Unreleased]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.18.0...HEAD
+[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
 [2.15.1]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.15.0...v2.15.1
 [2.15.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.14.0...v2.15.0

package/README.md

@@ -324,13 +324,19 @@ Shipped so far:
   [page](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/COMPATIBILITY.md) lists them;
 - 2.16 A2A over every binding: one agent served over JSON-RPC, HTTP+JSON, and gRPC from one task
   store, so a caller on any binding continues a task another started, and webhooks told the answer
-  as it is written.
+  as it is written;
+- 2.17 the editor's MCP servers over every transport, and video you can extend or edit: an ACP agent
+  connects stdio, HTTP, and SSE servers and decides each tool by what its server says it does, and a
+  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.
 
 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.17 connects the MCP servers an editor gives an ACP agent over SSE as well as stdio and HTTP,
-and reads what their tools declare they do, so a permission policy covers them without a rule for
-each. Pinecone, images, the Gemini
+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.
+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
 [roadmap](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/ROADMAP.md) lists what comes after, in the order

package/dist/agent/capabilities.d.ts

@@ -9,6 +9,9 @@ import type { ToolDefinition } from '../types/messages.js';
  * | `network`, `network:<host or URL>` | Opens a network connection, to a host when given |
  * | `shell`, `shell:<command line>` | Runs a shell command |
  * | `code` | Runs code it was given, as an interpreter does |
+ * | `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 |
  * | `<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/evaluate/media.d.ts

@@ -5,6 +5,7 @@
  */
 import { type JudgeClient } from '../evals/judge.js';
 import type { EvaluationContext, Evaluator, MediaPart } from '../types/evaluate.js';
+export { type MediaDuration, readMediaDuration } from '../utils/media-duration.js';
 /** What kind of medium something is. */
 export type MediaSubjectKind = 'image' | 'audio' | 'video' | 'document' | 'other';
 /** A medium read for judging: what it is, and as much of it as could be read. */
@@ -27,7 +28,10 @@ export interface ResolvedMedia {
     width?: number;
     /** Height in pixels. */
     height?: number;
-    /** Duration in milliseconds, read from a WAV header. */
+    /**
+     * Duration in milliseconds, read from the file's own headers: WAV, MP4 and MOV, WebM and Matroska,
+     * MP3, Ogg (Vorbis and Opus), and FLAC.
+     */
     durationMs?: number;
     /** Why its bytes could not be read, when they could not. */
     unreadable?: string;
@@ -93,7 +97,7 @@ export interface MediaCheckOptions extends MediaResolveOptions, MediaSelection {
         ratio: number;
         tolerance?: number;
     };
-    /** The duration in milliseconds allowed, for audio whose header says it. */
+    /** The duration in milliseconds allowed, for audio or video whose headers say it. */
     durationMs?: MediaRange;
     /** A medium whose measurement could not be read passes or fails that check. Defaults to `fail`. */
     unknown?: 'pass' | 'fail';

package/dist/evaluate/media.js

@@ -4,6 +4,8 @@ import { decodeBase64, encodeBase64 } from '../utils/base64.js';
 import { sha256Hex } from '../utils/sha256.js';
 import { withProvenance } from './provenance.js';
 import { asMediaPart, mediaParts } from './trace.js';
+import { readMediaDuration } from '../utils/media-duration.js';
+export { readMediaDuration } from '../utils/media-duration.js';
 export function mediaOf(context, from = 'output') {
     const traced = (direction) => (context.trace?.media ?? []).filter((item) => item.direction === direction).map((item) => item.part);
     const output = () => {
@@ -65,11 +67,11 @@ export async function resolveMedia(part, options = {}) {
             resolved.kind = 'document';
         }
         else {
-            const wav = wavDuration(bytes);
-            if (wav !== undefined) {
-                resolved.mimeType = 'audio/wav';
-                resolved.kind = 'audio';
-                resolved.durationMs = wav;
+            const read = readMediaDuration(bytes);
+            if (read) {
+                resolved.mimeType = read.mimeType;
+                resolved.kind = read.kind;
+                resolved.durationMs = read.durationMs;
             }
         }
     }
@@ -410,22 +412,6 @@ function mimeMatches(pattern, mimeType) {
         return mimeType.startsWith(pattern.slice(0, -1));
     return pattern === mimeType;
 }
-function wavDuration(bytes) {
-    if (!startsWith(bytes, 'RIFF') || ascii(bytes, 8, 4) !== 'WAVE')
-        return undefined;
-    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
-    let byteRate;
-    for (let at = 12; at + 8 <= bytes.length;) {
-        const id = ascii(bytes, at, 4);
-        const size = view.getUint32(at + 4, true);
-        if (id === 'fmt ' && at + 16 <= bytes.length)
-            byteRate = view.getUint32(at + 16, true);
-        if (id === 'data')
-            return byteRate ? Math.round((size / byteRate) * 1000) : undefined;
-        at += 8 + size + (size % 2);
-    }
-    return undefined;
-}
 function startsWith(bytes, text) {
     return ascii(bytes, 0, text.length) === text;
 }

package/dist/index.d.ts

@@ -20,7 +20,7 @@ export { tool, toolOutput } from './agent/tool.js';
 export type { CacheHint, CompletionRequest, Message, MessageRole, ContentPart, PromptCacheConfig, ReasoningConfig, TextContent, ImageContent, AudioContent, BinaryBuffer, VideoContent, AssetContent, ToolChoice, ToolDefinition, ToolCallResult, ToolOutput, } from './types/messages.js';
 export type { CapabilityConfig, CapabilityPolicy, CapabilityWarning, CapabilityWarningAction, } from './types/capabilities.js';
 export type { CostEstimate, NexusPlan, } from './types/planning.js';
-export type { NexusResponse, NexusStream, ResponseCost, ResponseMeta, StreamChunk, TokenUsage, ToolCall, } from './types/response.js';
+export type { NexusResponse, NexusStream, ResponseAttempt, ResponseCost, ResponseMeta, StreamChunk, TokenUsage, ToolCall, } from './types/response.js';
 export type { NexusAIConfig, ProvidersConfig, OpenAIProviderConfig, AnthropicProviderConfig, GoogleProviderConfig, OllamaProviderConfig, GroqProviderConfig, MistralProviderConfig, CohereProviderConfig, CustomProviderConfig, DeepSeekProviderConfig, AzureOpenAIProviderConfig, LMStudioProviderConfig, LlamaCppProviderConfig, RoutingConfig, RoutingRule, RoutingStrategy, FallbackConfig, ResponseFormatConfig, RetryConfig, CostBudgetConfig, AuditLogConfig, AuditLogEvent, LoggerConfig, LogEvent, LogLevel, RateLimitConfig, } from './types/config.js';
 export type { ContextSummaryConfig, ContextSummaryInput, ContextSummaryMode, ContextSummarizer, ContextWindowConfig, ContextWindowResult, ContextWindowStrategy, ContextWindowUsage, } from './types/context-window.js';
 export type { AliasMetadata, AliasStage, CacheTtl, InputModality, ModelCapabilities, ModelEndpoint, ModelStatus, OutputModality, PromptCachingCapability, ProviderCapabilities, ReasoningEffort, RoutingModelPreference, } from './types/providers.js';

package/dist/mcp/client.d.ts

@@ -1,5 +1,21 @@
 import type { ToolDefinition } from '../types/messages.js';
 import { type McpTransport } from './protocol.js';
+/**
+ * What a server says a tool does, as MCP's tool annotations: hints, which a client trusts only as far
+ * as it trusts the server. A hint left out takes the specification's default.
+ */
+export interface McpToolAnnotations {
+    /** A name for people. */
+    title?: string;
+    /** It changes nothing. Defaults to false. */
+    readOnlyHint?: boolean;
+    /** When it changes things, it may destroy or overwrite them, not only add. Defaults to true. */
+    destructiveHint?: boolean;
+    /** Calling it again with the same arguments changes nothing more. Defaults to false. */
+    idempotentHint?: boolean;
+    /** It reaches things beyond the server, such as the web. Defaults to true. */
+    openWorldHint?: boolean;
+}
 /** A tool an MCP server offers. */
 export interface McpToolDescriptor {
     /** The tool's name. */
@@ -8,6 +24,33 @@ export interface McpToolDescriptor {
     description?: string;
     /** JSON Schema for the arguments. */
     inputSchema?: Record<string, unknown>;
+    /** What the server says the tool does. */
+    annotations?: McpToolAnnotations;
+}
+/**
+ * The capabilities an MCP tool declares, from what its server says of it in its annotations, so a
+ * permission policy decides it as it decides any tool:
+ * - `mcp.read:<server>/<tool>` for a tool that only reads;
+ * - `mcp.write:<server>/<tool>` for one that changes things but destroys nothing;
+ * - `mcp.destructive:<server>/<tool>` for one that may destroy or overwrite;
+ * - and `network`, beside it, for one that reaches beyond its server.
+ *
+ * A hint left out takes the specification's default: not read-only, destructive, and open. A tool
+ * with no annotations at all declares nothing, `undefined`, so a policy decides it as undeclared.
+ */
+export declare function mcpToolCapabilities(tool: McpToolDescriptor, server: string): string[] | undefined;
+/** Options for `McpClient.toNexusTools()`. */
+export interface McpToolsOptions {
+    /** Put before each tool's name with an underscore, so two servers' `search` tools differ. */
+    prefix?: string;
+    /**
+     * The capabilities each tool declares: `true` reads them from the server's annotations, with
+     * `mcpToolCapabilities()`, under the server's name (the prefix, or the name the server gives); a
+     * function decides them per tool. Without it, a tool declares none, as before 2.17.
+     */
+    capabilities?: boolean | ((tool: McpToolDescriptor) => readonly string[] | undefined);
+    /** The server's name in each capability, when `capabilities` is `true`. Defaults to the prefix. */
+    server?: string;
 }
 /** A resource an MCP server offers. */
 export interface McpResourceDescriptor {
@@ -48,6 +91,14 @@ export interface McpClientOptions {
     };
     /** How long a request waits before failing. Defaults to 30 seconds. */
     timeoutMs?: number;
+    /**
+     * When the transport closes, as an SSE stream that ends or a server process that exits does, the
+     * next request opens it again and repeats the handshake, since the server's session went with it.
+     * Requests in flight still fail, and a client closed with `close()` stays closed. Needs a transport
+     * that can open again: `createStdioTransport` starts a new process, `createSseTransport` with
+     * `reopen` a new stream.
+     */
+    reconnect?: boolean;
 }
 /**
  * Talks to an MCP server.
@@ -66,7 +117,15 @@ export declare class McpClient {
     private initialized;
     private connecting;
     private serverInfo;
+    /** Who hears that the server's tools changed. */
+    private readonly toolsChanged;
+    private stopped;
     constructor(transport: McpTransport, options?: McpClientOptions);
+    /**
+     * Hears each `notifications/tools/list_changed` the server sends: its tools are no longer what
+     * `listTools()` returned. Returns a function that stops hearing.
+     */
+    onToolsChanged(handler: () => void): () => void;
     /**
      * Performs the handshake and returns the server's name and version. Called automatically by the
      * first request that needs it; requests made together share one handshake.
@@ -109,9 +168,7 @@ export declare class McpClient {
      * Names are prefixed when asked, because two servers can both offer `search` and a model has to be
      * able to tell them apart.
      */
-    toNexusTools(options?: {
-        prefix?: string;
-    }): Promise<ToolDefinition[]>;
+    toNexusTools(options?: McpToolsOptions): Promise<ToolDefinition[]>;
     /** Closes the connection and rejects every request still waiting. */
     close(): Promise<void>;
     private request;
@@ -149,7 +206,8 @@ export declare function serverEnvironment(source: Record<string, string | undefi
  * Runs an MCP server as a child process and speaks to it over its stdin and stdout.
  *
  * The transport most MCP servers ship with. `node:child_process` is imported lazily, so a browser
- * or edge build that only uses the HTTP transport never reaches for it.
+ * or edge build that only uses the HTTP transport never reaches for it. When the process exits, the
+ * transport closes; started again, it runs a new one.
  */
 export declare function createStdioTransport(options: StdioClientOptions): McpTransport;
 /** Connects to a remote MCP server over HTTP. */
@@ -168,3 +226,27 @@ export interface HttpClientOptions {
  * calling a tool needs.
  */
 export declare function createHttpTransport(options: HttpClientOptions): McpTransport;
+/** Connects to a remote MCP server over HTTP with Server-Sent Events, the transport before streamable HTTP. */
+export interface SseClientOptions {
+    /** The server's event stream: a `GET` here opens it, and the server names where to post messages. */
+    url: string;
+    /** Headers sent with the stream's request and with every message, such as authorization. */
+    headers?: Record<string, string>;
+    /** Replaces the global `fetch`. */
+    fetch?: typeof globalThis.fetch;
+    /** How long to wait for the server to name where messages go, in milliseconds. Defaults to 10 seconds. */
+    timeoutMs?: number;
+    /**
+     * Opens a new stream when the next message is sent after the stream ended, rather than staying
+     * closed. The server starts a new session on it, so an `McpClient` with `reconnect` greets it again.
+     */
+    reopen?: boolean;
+}
+/**
+ * Speaks to an MCP server over HTTP with Server-Sent Events, as MCP's 2024-11-05 transport: one
+ * long `GET` the server answers on, and a `POST` per message to the endpoint the stream names
+ * first. The endpoint must be on the stream's own origin, so a server cannot send the messages, and
+ * their headers, anywhere else. When the stream ends, the transport closes; with `reopen`, the next
+ * message opens a new one.
+ */
+export declare function createSseTransport(options: SseClientOptions): McpTransport;