nexus-ai-pro 2.15.1 → 2.17.0

package/API_STABILITY.md

@@ -41,6 +41,43 @@ 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.
+
+New and stable:
+- `nexus-ai-pro/protocols/a2a/grpc`: `a2aGrpcService()`, `a2aGrpcClient()`, `A2aGrpcService`,
+  `A2aGrpcServiceOptions`, `A2aGrpcClient`, and `A2aGrpcClientOptions`;
+- in `nexus-ai-pro/protocols/a2a`: the HTTP+JSON routes, `A2aServerOptions.bindings` and
+  `interfaces`, `A2aHandler.call()`, `card`, and `authenticate()`, `A2aBinding`, `A2aCallContext`,
+  `A2aCallOutcome`, `A2aErrorStatus`, `a2aErrorStatus()`, `a2aErrorCode()`,
+  `A2aClientOptions.binding`, `A2aPushOptions.text`, and `A2aPushNotificationConfig.authentication`.
+
+The routes, the gRPC service, and their errors follow A2A 1.0's bindings: a change the specification
+makes in a later version comes with that version, behind `A2A_PROTOCOL_VERSION`.
+
 ## 2.15 stage (2.15.0)
 
 Everything 2.15 adds is stable from the start and additive, unless this section says otherwise.

package/CHANGELOG.md

@@ -4,6 +4,88 @@ 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.
+
+### Added
+
+- **A2A over HTTP+JSON and gRPC.** `a2aHandler()` serves the protocol's HTTP+JSON binding beside
+  JSON-RPC, at routes under the card's URL, its errors AIP-193's JSON with A2A's `ErrorInfo` reason.
+  `a2aGrpcService()`, on the new `nexus-ai-pro/protocols/a2a/grpc`, serves the gRPC binding,
+  `lf.a2a.v1.A2AService`, over `node:http2` with no dependency. The card names each binding served
+  (`bindings`, `interfaces`). All three run through `A2aHandler.call()` over one task store, so a
+  caller on any binding continues, reads, cancels, or follows a task another started, and reads the
+  same history.
+- **Clients on every binding.** `a2aClient({ binding: 'HTTP+JSON' })` calls the HTTP+JSON binding, and
+  `a2aGrpcClient()` the gRPC one, with every method `a2aClient()` has. An error on any binding raises
+  an `A2aError` with A2A's code; `a2aErrorStatus()` and `a2aErrorCode()` map a code to its HTTP
+  status, gRPC status, and reason, and back.
+- **A webhook told the answer as it is written.** `pushNotifications.text` pushes each piece of
+  streamed text to a task's webhooks, the same pieces a stream sends, before the state that follows
+  them; `text: { everyMs }` gathers the pieces into fewer deliveries. A push config's
+  `authentication` is sent as each delivery's `Authorization` header.
+- Push configs take protocol 1.0's flat shape on every binding, and JSON-RPC answers both it and the
+  drafts' nested one; `ListTaskPushNotificationConfigs` is answered under its 1.0 name too.
+
+### Changed
+
+- The nightly interoperability check drives `@a2a-js/sdk` over each of the three bindings, and a
+  task across them. It drives `@agentclientprotocol/sdk` 2.0, which dropped
+  `ClientSideConnection`, through its new connection API, and 1.x as before.
+
 ## [2.15.1] - 2026-10-19
 
 A test that could fail by chance, made exact. The package is unchanged from 2.15.0.
@@ -3021,7 +3103,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.15.1...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
 [2.14.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.13.0...v2.14.0

package/README.md

@@ -321,12 +321,18 @@ Shipped so far:
 - 2.15 a compatibility record for community adapters: `nexus adapters verify` seals the contract an
   adapter passed, against which release, with its benchmark; `nexus adapters recheck` turns a listed
   adapter red before a release that would break it; and one
-  [page](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/COMPATIBILITY.md) lists them.
+  [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;
+- 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.16 serves A2A over its HTTP+JSON and gRPC bindings beside JSON-RPC, one task store behind
-all three, and lets a push webhook receive each piece of streamed text. 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/a2a-grpc.d.ts

@@ -0,0 +1,63 @@
+/**
+ * A2A's gRPC binding: the service `lf.a2a.v1.A2AService` of protocol 1.0, served over the same
+ * `a2aHandler()` as its JSON-RPC and HTTP+JSON bindings, and so over the same tasks, and a client that
+ * calls an agent over it. Over HTTP/2 from `node:http2`, with no dependency.
+ *
+ * ```ts
+ * const handler = a2aHandler(agent, { card, interfaces: [{ url: 'agents.example.com:50051', protocolBinding: 'GRPC' }] });
+ * const grpc = a2aGrpcService(handler);
+ * await grpc.listen(50051);
+ * ```
+ */
+import { type Http2Server, type IncomingHttpHeaders, type ServerHttp2Stream } from 'node:http2';
+import { type A2aClient, type A2aClientOptions, type A2aHandler } from './a2a.js';
+/** Options for `a2aGrpcService()`. */
+export interface A2aGrpcServiceOptions {
+    /** Largest request message taken, in bytes. Defaults to 4 MiB, gRPC's own default. */
+    maxMessageBytes?: number;
+}
+/** The gRPC binding of one A2A handler. */
+export interface A2aGrpcService {
+    /**
+     * Answers one HTTP/2 stream: give it each stream of a server of your own, such as one over TLS,
+     * as `server.on('stream', service.handle)`.
+     */
+    handle(stream: ServerHttp2Stream, headers: IncomingHttpHeaders): void;
+    /**
+     * Starts a server over plain HTTP/2 on `port`, 0 for any, on `host`: for a server behind a proxy
+     * that ends TLS, and for tests. Resolves with the address to list on the card, `host:port`. Its
+     * `close()` stops taking calls, tells each connected client to go, and resolves once the calls in
+     * flight finish.
+     */
+    listen(port?: number, host?: string): Promise<{
+        url: string;
+        port: number;
+        server: Http2Server;
+        close(): Promise<void>;
+    }>;
+}
+/**
+ * The gRPC binding over an `a2aHandler()`: each method of `lf.a2a.v1.A2AService`, its message read as
+ * the JSON the handler takes and its answer written back, a stream as a server-streaming call, and an
+ * error as a gRPC status with A2A's `ErrorInfo` in `grpc-status-details-bin`. The caller is read by the
+ * handler's own `principal`, from a `Request` with the call's metadata as its headers.
+ */
+export declare function a2aGrpcService(handler: A2aHandler, options?: A2aGrpcServiceOptions): A2aGrpcService;
+/** Options for `a2aGrpcClient()`. */
+export interface A2aGrpcClientOptions extends Omit<A2aClientOptions, 'binding' | 'url'> {
+    /** Where the agent's gRPC service is: `host:port`, as its card lists it, or an `http://` or `https://` URL. */
+    url: string;
+    /** Where its card is, for `card()`. Without it, `card()` reads the extended card. */
+    cardUrl?: string;
+}
+/** A client for an A2A agent over gRPC, with `close()` for its connection. */
+export interface A2aGrpcClient extends A2aClient {
+    /** Closes the HTTP/2 connection. */
+    close(): Promise<void>;
+}
+/**
+ * A client for one A2A agent over its gRPC binding: the same methods as `a2aClient()`, each a call of
+ * `lf.a2a.v1.A2AService` over one HTTP/2 connection, a gRPC error raised as an `A2aError` with the
+ * protocol's code. Plain HTTP/2 for `host:port` and `http://`; TLS for `https://`.
+ */
+export declare function a2aGrpcClient(options: A2aGrpcClientOptions): A2aGrpcClient;