nexus-ai-pro 2.16.0 → 2.17.0

package/API_STABILITY.md

@@ -41,6 +41,28 @@ 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.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,58 @@ Notable changes to this project are recorded here. The format follows [Keep a Ch
 
 ## [Unreleased]
 
+## [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 +3103,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.16.0...HEAD
+[Unreleased]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.17.0...HEAD
+[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,15 @@ 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.
 
 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.18 records events and links on spans, as OpenTelemetry has them, and reads the length of
+compressed audio and video, so an evaluation holds a clip to its duration. 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/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 {
@@ -109,9 +152,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;
@@ -168,3 +209,21 @@ 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;
+}
+/**
+ * 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.
+ */
+export declare function createSseTransport(options: SseClientOptions): McpTransport;

package/dist/mcp/client.js

@@ -1,4 +1,11 @@
 import { isNotification, isRequest, isResponse, LineDecoder, MCP_PROTOCOL_VERSION, McpError, } from './protocol.js';
+export function mcpToolCapabilities(tool, server) {
+    const hints = tool.annotations;
+    if (!hints || typeof hints !== 'object')
+        return undefined;
+    const effect = hints.readOnlyHint === true ? 'mcp.read' : hints.destructiveHint === false ? 'mcp.write' : 'mcp.destructive';
+    return [`${effect}:${server}/${tool.name}`, ...(hints.openWorldHint === false ? [] : ['network'])];
+}
 export class McpClient {
     transport;
     options;
@@ -79,22 +86,34 @@ export class McpClient {
     }
     async toNexusTools(options = {}) {
         const tools = await this.listTools();
-        return tools.map((descriptor) => ({
-            name: options.prefix ? `${options.prefix}_${descriptor.name}` : descriptor.name,
-            description: descriptor.description ?? `MCP tool ${descriptor.name}`,
-            parameters: descriptor.inputSchema ?? { type: 'object', properties: {} },
-            execute: async (args, context) => {
-                const progress = context?.progress;
-                const result = await this.callTool(descriptor.name, args, progress ? { progress } : {});
-                const text = result.content
-                    .map((part) => part.text ?? (part.type === 'text' ? '' : JSON.stringify(part)))
-                    .filter(Boolean)
-                    .join('\n');
-                if (result.isError)
-                    throw new McpError(text || `MCP tool ${descriptor.name} failed`);
-                return text;
-            },
-        }));
+        const server = options.server ?? options.prefix ?? this.serverInfo.name ?? 'mcp';
+        const declared = (descriptor) => {
+            const { capabilities } = options;
+            if (!capabilities)
+                return undefined;
+            const list = capabilities === true ? mcpToolCapabilities(descriptor, server) : capabilities(descriptor);
+            return list === undefined ? undefined : [...list];
+        };
+        return tools.map((descriptor) => {
+            const capabilities = declared(descriptor);
+            return {
+                name: options.prefix ? `${options.prefix}_${descriptor.name}` : descriptor.name,
+                description: descriptor.description ?? `MCP tool ${descriptor.name}`,
+                parameters: descriptor.inputSchema ?? { type: 'object', properties: {} },
+                ...(capabilities ? { capabilities } : {}),
+                execute: async (args, context) => {
+                    const progress = context?.progress;
+                    const result = await this.callTool(descriptor.name, args, progress ? { progress } : {});
+                    const text = result.content
+                        .map((part) => part.text ?? (part.type === 'text' ? '' : JSON.stringify(part)))
+                        .filter(Boolean)
+                        .join('\n');
+                    if (result.isError)
+                        throw new McpError(text || `MCP tool ${descriptor.name} failed`);
+                    return text;
+                },
+            };
+        });
     }
     async close() {
         this.failAll(new McpError('The MCP client was closed'));
@@ -297,6 +316,125 @@ export function createHttpTransport(options) {
         },
     };
 }
+export function createSseTransport(options) {
+    const fetchImplementation = options.fetch ?? globalThis.fetch;
+    let onMessage = () => undefined;
+    const onClose = [];
+    let endpoint;
+    let opening;
+    let closed = false;
+    const stream = new AbortController();
+    const ended = () => {
+        if (closed)
+            return;
+        closed = true;
+        for (const handler of onClose)
+            handler();
+    };
+    const open = async () => {
+        const response = await fetchImplementation(options.url, {
+            headers: { accept: 'text/event-stream', ...options.headers },
+            signal: stream.signal,
+        });
+        if (!response.ok || !response.body)
+            throw new McpError(`MCP SSE transport failed with ${response.status}`);
+        const reader = response.body.getReader();
+        await new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                reject(new McpError(`The MCP server named no endpoint within ${options.timeoutMs ?? 10_000}ms`));
+                stream.abort();
+            }, options.timeoutMs ?? 10_000);
+            const event = (name, data) => {
+                if (name === 'endpoint') {
+                    if (endpoint)
+                        return;
+                    const target = new URL(data.trim(), options.url);
+                    if (target.origin !== new URL(options.url).origin) {
+                        clearTimeout(timer);
+                        reject(new McpError(`The MCP server named an endpoint on another origin, ${target.origin}`));
+                        stream.abort();
+                        return;
+                    }
+                    endpoint = target.href;
+                    clearTimeout(timer);
+                    resolve();
+                }
+                else if (name === 'message') {
+                    try {
+                        onMessage(JSON.parse(data));
+                    }
+                    catch {
+                    }
+                }
+            };
+            void readEvents(reader, event).then(() => {
+                clearTimeout(timer);
+                reject(new McpError('The MCP event stream ended'));
+                ended();
+            }, (error) => {
+                clearTimeout(timer);
+                reject(error instanceof McpError ? error : new McpError(`The MCP event stream failed: ${String(error)}`));
+                ended();
+            });
+        });
+    };
+    const started = () => {
+        opening ??= open();
+        return opening;
+    };
+    return {
+        start: started,
+        async send(message) {
+            await started();
+            if (closed || !endpoint)
+                throw new McpError('The MCP event stream is closed');
+            const response = await fetchImplementation(endpoint, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json', ...options.headers },
+                body: JSON.stringify(message),
+            });
+            await response.body?.cancel().catch(() => undefined);
+            if (!response.ok)
+                throw new McpError(`MCP SSE transport failed with ${response.status}`);
+        },
+        onMessage(handler) {
+            onMessage = handler;
+        },
+        onClose(handler) {
+            onClose.push(handler);
+        },
+        close() {
+            stream.abort();
+            ended();
+        },
+    };
+}
+async function readEvents(reader, event) {
+    const decoder = new TextDecoder();
+    let buffer = '';
+    while (true) {
+        const { value, done } = await reader.read();
+        if (done)
+            return;
+        buffer += decoder.decode(value, { stream: true }).replace(/\r\n?/g, '\n');
+        let boundary = buffer.indexOf('\n\n');
+        while (boundary !== -1) {
+            const frame = buffer.slice(0, boundary);
+            buffer = buffer.slice(boundary + 2);
+            let name = 'message';
+            const data = [];
+            for (const line of frame.split('\n')) {
+                if (line.startsWith('event:'))
+                    name = line.slice(6).trim();
+                else if (line.startsWith('data:'))
+                    data.push(line.slice(5).replace(/^ /, ''));
+            }
+            if (data.length)
+                event(name, data.join('\n'));
+            boundary = buffer.indexOf('\n\n');
+        }
+    }
+}
 function sseData(body) {
     return body
         .split('\n')

package/dist/mcp/index.d.ts

@@ -1,3 +1,3 @@
-export { createHttpTransport, createStdioTransport, type HttpClientOptions, McpClient, type McpClientOptions, type McpContent, type McpResourceDescriptor, type McpToolDescriptor, type McpToolResult, type StdioClientOptions, } from './client.js';
+export { createHttpTransport, createSseTransport, createStdioTransport, type HttpClientOptions, McpClient, type McpClientOptions, type McpContent, type McpResourceDescriptor, type McpToolAnnotations, type McpToolDescriptor, type McpToolResult, type McpToolsOptions, mcpToolCapabilities, type SseClientOptions, type StdioClientOptions, } from './client.js';
 export { JSON_RPC_ERRORS, type JsonRpcMessage, type JsonRpcNotification, type JsonRpcRequest, type JsonRpcResponse, LineDecoder, MCP_PROTOCOL_VERSION, McpError, type McpTransport, } from './protocol.js';
-export { createStdioServerTransport, McpServer, type McpServerOptions } from './server.js';
+export { createStdioServerTransport, McpServer, type McpServerOptions, mcpToolAnnotations } from './server.js';

package/dist/mcp/index.js

@@ -1,3 +1,3 @@
-export { createHttpTransport, createStdioTransport, McpClient, } from './client.js';
+export { createHttpTransport, createSseTransport, createStdioTransport, McpClient, mcpToolCapabilities, } from './client.js';
 export { JSON_RPC_ERRORS, LineDecoder, MCP_PROTOCOL_VERSION, McpError, } from './protocol.js';
-export { createStdioServerTransport, McpServer } from './server.js';
+export { createStdioServerTransport, McpServer, mcpToolAnnotations } from './server.js';

package/dist/mcp/server.d.ts

@@ -1,4 +1,5 @@
 import type { ToolDefinition } from '../types/messages.js';
+import type { McpToolAnnotations } from './client.js';
 import { type JsonRpcMessage, type McpTransport } from './protocol.js';
 /** Options for an MCP server. */
 export interface McpServerOptions {
@@ -17,6 +18,17 @@ export interface McpServerOptions {
         read(): Promise<unknown> | unknown;
     }>;
 }
+/**
+ * The annotations a tool is served with, from the capabilities it declares, read so a client is never
+ * told less than the tool may do:
+ * - read-only only when every capability reads, `filesystem:read` or `mcp.read`, or there are none;
+ * - not destructive only when everything else it does is `mcp.write`;
+ * - closed to the world only when every capability is the filesystem's or an MCP tool's effect.
+ *
+ * A tool whose capabilities depend on its arguments, or that declares none, is served without
+ * annotations, which a client reads as the specification's defaults: it may do anything.
+ */
+export declare function mcpToolAnnotations(tool: Pick<ToolDefinition, 'capabilities'>): McpToolAnnotations | undefined;
 /**
  * Exposes tools over MCP, so other assistants can call them.
  *

package/dist/mcp/server.js

@@ -1,4 +1,19 @@
+import { parseCapability } from '../agent/capabilities.js';
 import { isNotification, isRequest, JSON_RPC_ERRORS, LineDecoder, MCP_PROTOCOL_VERSION, McpError, textContent, } from './protocol.js';
+const CLOSED = new Set(['filesystem', 'mcp.read', 'mcp.write', 'mcp.destructive']);
+export function mcpToolAnnotations(tool) {
+    const declared = tool.capabilities;
+    if (!declared || typeof declared === 'function')
+        return undefined;
+    const parsed = declared.map((capability) => parseCapability(capability));
+    const reads = (item) => (item.kind === 'filesystem' && item.access === 'read') || item.kind === 'mcp.read';
+    const readOnly = parsed.every(reads);
+    return {
+        readOnlyHint: readOnly,
+        ...(readOnly ? {} : { destructiveHint: !parsed.every((item) => reads(item) || item.kind === 'mcp.write') }),
+        openWorldHint: !parsed.every((item) => CLOSED.has(item.kind)),
+    };
+}
 export class McpServer {
     options;
     tools = new Map();
@@ -57,11 +72,15 @@ export class McpServer {
                 return {};
             case 'tools/list':
                 return {
-                    tools: [...this.tools.values()].map((item) => ({
-                        name: item.name,
-                        description: item.description,
-                        inputSchema: item.parameters ?? { type: 'object', properties: {} },
-                    })),
+                    tools: [...this.tools.values()].map((item) => {
+                        const annotations = mcpToolAnnotations(item);
+                        return {
+                            name: item.name,
+                            description: item.description,
+                            inputSchema: item.parameters ?? { type: 'object', properties: {} },
+                            ...(annotations ? { annotations } : {}),
+                        };
+                    }),
                 };
             case 'tools/call': {
                 const name = String(params.name ?? '');

package/dist/protocols/acp-editor.d.ts

@@ -10,9 +10,11 @@
  *
  * A tool is offered only when the editor said it can do that thing, in `initialize`. Each declares
  * what it touches, as `filesystem:read:<path>`, `filesystem:write:<path>`, or `shell:<command>`, so a
- * permission policy decides it like any other tool, and an approval asks the person in the editor.
+ * permission policy decides it like any other tool, and an approval asks the person in the editor. An
+ * MCP server's tools, over stdio, HTTP, or SSE, declare what their server says they do.
  */
 import type { ToolSourceContext } from '../agent/create-agent.js';
+import { type McpToolDescriptor } from '../mcp/client.js';
 import type { ToolDefinition } from '../types/messages.js';
 import type { AcpEditorBridge } from './acp.js';
 /** Options for `acpEditor()`. */
@@ -25,8 +27,15 @@ export interface AcpEditorOptions {
     mcp?: boolean;
     /** How long a request to an MCP server may take, in milliseconds. Defaults to 30 seconds. */
     mcpTimeoutMs?: number;
-    /** Replaces `fetch` for MCP servers reached over HTTP: a proxy, or a test. */
+    /** Replaces `fetch` for MCP servers reached over HTTP or SSE: a proxy, or a test. */
     mcpFetch?: typeof globalThis.fetch;
+    /**
+     * What an MCP server's tools declare they do, for a permission policy. `true`, the default, reads
+     * it from the server's annotations, with `mcpToolCapabilities()`: `mcp.read`, `mcp.write`, or
+     * `mcp.destructive` under the server's name, and `network` for a tool that reaches beyond it. A
+     * function decides per tool, and `false` declares nothing, as before 2.17.
+     */
+    mcpToolCapabilities?: boolean | ((tool: McpToolDescriptor, server: string) => readonly string[] | undefined);
     /** The most terminal output a command returns, in bytes. Defaults to 64 KB. */
     maxOutputBytes?: number;
     /** Receives an MCP server that failed to start, whose tools are then not offered. */
@@ -34,6 +43,11 @@ export interface AcpEditorOptions {
 }
 /** The editor, as tools for an agent. */
 export interface AcpEditor extends AcpEditorBridge {
+    /** The MCP transports it connects, which the agent tells the editor in `initialize`. */
+    readonly mcpCapabilities: {
+        http: boolean;
+        sse: boolean;
+    };
     /** The tools of one session, for `CreateAgentOptions.toolSource`: the session is the run's thread. */
     toolSource(context: ToolSourceContext): Promise<ToolDefinition[]>;
     /** Closes every MCP server it connected. */

package/dist/protocols/acp-editor.js

@@ -1,4 +1,4 @@
-import { createHttpTransport, createStdioTransport, McpClient } from '../mcp/client.js';
+import { createHttpTransport, createSseTransport, createStdioTransport, McpClient, } from '../mcp/client.js';
 export function acpEditor(options = {}) {
     let connection;
     const servers = new Map();
@@ -9,9 +9,18 @@ export function acpEditor(options = {}) {
             connected = (async () => {
                 const clients = [];
                 const tools = [];
+                const declare = options.mcpToolCapabilities ?? true;
                 for (const offered of session.mcpServers) {
                     const name = String(offered.name ?? 'mcp');
+                    const prefix = name.replace(/[^A-Za-z0-9_-]/g, '_');
                     try {
+                        const remote = offered.url
+                            ? {
+                                url: offered.url,
+                                headers: Object.fromEntries((offered.headers ?? []).map((item) => [item.name, item.value])),
+                                ...(options.mcpFetch ? { fetch: options.mcpFetch } : {}),
+                            }
+                            : undefined;
                         const transport = offered.command
                             ? createStdioTransport({
                                 command: offered.command,
@@ -19,18 +28,20 @@ export function acpEditor(options = {}) {
                                 env: Object.fromEntries((offered.env ?? []).map((item) => [item.name, item.value])),
                                 ...(session.cwd ? { cwd: session.cwd } : {}),
                             })
-                            : offered.url && (offered.type === 'http' || offered.type === undefined)
-                                ? createHttpTransport({
-                                    url: offered.url,
-                                    headers: Object.fromEntries((offered.headers ?? []).map((item) => [item.name, item.value])),
-                                    ...(options.mcpFetch ? { fetch: options.mcpFetch } : {}),
-                                })
-                                : undefined;
+                            : remote && offered.type === 'sse'
+                                ? createSseTransport({ ...remote, timeoutMs: options.mcpTimeoutMs ?? 30_000 })
+                                : remote && (offered.type === 'http' || offered.type === undefined)
+                                    ? createHttpTransport(remote)
+                                    : undefined;
                         if (!transport)
                             throw new Error(`MCP server "${name}" uses a transport this agent does not speak`);
                         const client = new McpClient(transport, { timeoutMs: options.mcpTimeoutMs ?? 30_000 });
-                        tools.push(...(await client.toNexusTools({ prefix: name.replace(/[^A-Za-z0-9_-]/g, '_') })));
                         clients.push(client);
+                        tools.push(...(await client.toNexusTools({
+                            prefix,
+                            server: prefix,
+                            capabilities: typeof declare === 'function' ? (tool) => declare(tool, prefix) : declare,
+                        })));
                     }
                     catch (error) {
                         options.onError?.(error, name);
@@ -130,6 +141,7 @@ export function acpEditor(options = {}) {
         return list;
     };
     return {
+        mcpCapabilities: { http: options.mcp !== false, sse: options.mcp !== false },
         attach(next) {
             connection = next;
         },

package/dist/protocols/acp.d.ts

@@ -104,6 +104,14 @@ export interface AcpConnection {
 }
 /** Something that uses the editor's connection, such as `acpEditor()`. `serveAcp()` attaches it when it starts. */
 export interface AcpEditorBridge {
+    /**
+     * The MCP transports it connects beyond stdio, which the agent tells the editor in `initialize` so
+     * the editor offers servers over them too.
+     */
+    readonly mcpCapabilities?: {
+        http?: boolean;
+        sse?: boolean;
+    };
     /** Receives the connection to the editor. */
     attach(connection: AcpConnection): void;
     /** Called when the editor closes its end, or the server is closed: the place to stop what it started. */

package/dist/protocols/acp.js

@@ -249,6 +249,7 @@ export function serveAcp(graph, streams, options = {}) {
                     agentCapabilities: {
                         loadSession: true,
                         promptCapabilities: { image: true, audio: true, embeddedContext: true },
+                        ...(options.editor?.mcpCapabilities ? { mcpCapabilities: options.editor.mcpCapabilities } : {}),
                     },
                     authMethods: [],
                     ...(options.agentInfo ? { agentInfo: options.agentInfo } : {}),

package/dist/version.d.ts

@@ -2,4 +2,4 @@
  * This package's version, recorded where provenance matters, such as on every experiment. A test
  * keeps it equal to `package.json`.
  */
-export declare const NEXUS_VERSION = "2.16.0";
+export declare const NEXUS_VERSION = "2.17.0";

package/dist/version.js

@@ -1 +1 @@
-export const NEXUS_VERSION = '2.16.0';
+export const NEXUS_VERSION = '2.17.0';