@orkestrel/mcp 0.0.30 → 0.0.31

package/dist/src/core/index.d.cts

@@ -2,6 +2,7 @@ import type { EmitterErrorHandler } from '@orkestrel/emitter';
 import type { EmitterHooks } from '@orkestrel/emitter';
 import type { EmitterInterface } from '@orkestrel/emitter';
 import type { JSONValue } from '@orkestrel/contract';
+import type { ToolAnnotations } from '@orkestrel/tool';
 import type { ToolCall } from '@orkestrel/tool';
 import type { ToolInterface } from '@orkestrel/tool';
 import type { ToolManagerInterface } from '@orkestrel/tool';
@@ -177,10 +178,11 @@ export declare function buildCancelledNotification(id: JSONRPCId, reason?: strin
  * @remarks
  * `capabilities.resources` and `capabilities.prompts` appear only for servers with their
  * respective managers and derive notification flags from the configured subscription filter.
- * `capabilities.completions` is independent and appears only with a completion provider.
- * `capabilities.extensions` appears only for a server that configured the extension it
- * would name. An advertisement is a promise a client is entitled to act on, so a server
- * with no `task` policy omits the member entirely rather than advertising an empty
+ * `tools.listChanged` is always advertised because the server produces the family from its
+ * own registry. `capabilities.completions` is independent and appears only with a completion
+ * provider. `capabilities.extensions` appears only for a server that configured the
+ * extension it would name. An advertisement is a promise a client is entitled to act on, so
+ * a server with no `task` policy omits the member entirely rather than advertising an empty
  * record — and its discovery answer stays byte-for-byte what it was before the extension
  * existed.
  *
@@ -405,11 +407,10 @@ export declare function buildSubscriptionResult(id: JSONRPCId, identity: MCPIden
  * Builds the canonical Tool call for one validated MCP `tools/call` request.
  *
  * @param request - The original MCP request
- * @param caller - Optional consumer-asserted caller context
  * @param args - Optional once-validated modern arguments; omission retains legacy normalization
  * @returns The canonical call, or `undefined` when the name is invalid
  */
-export declare function buildToolCall(request: JSONRPCRequest, caller?: unknown, args?: Readonly<Record<string, unknown>>): ToolCall | undefined;
+export declare function buildToolCall(request: JSONRPCRequest, args?: Readonly<Record<string, unknown>>): ToolCall | undefined;
 
 /**
  * Maps a {@link ToolManagerInterface}'s definitions to MCP `tools/list` descriptors
@@ -417,7 +418,8 @@ export declare function buildToolCall(request: JSONRPCRequest, caller?: unknown,
  *
  * @remarks
  * Each {@link import('@orkestrel/tool').ToolDefinition} carries through its
- * `name` and (when present) `description`; its open JSON-Schema `parameters`
+ * `name`, optional `title` and `description`, and mapped annotation hints;
+ * its open JSON-Schema `parameters`
  * becomes `inputSchema`, defaulting to an empty object schema (`{ type: 'object' }`)
  * when a tool declares none (MCP requires an `inputSchema`).
  *
@@ -1488,6 +1490,20 @@ export declare function isMCPCompletionReference(value: unknown): value is MCPCo
  */
 export declare function isMCPCompletionResult(value: unknown): value is MCPCompletionResult;
 
+/**
+ * Checks whether a subscription filter leaves the built-in tools family to the server.
+ *
+ * @param value - The unknown value to inspect
+ * @returns True if the filter is valid and does not claim tools changes; false otherwise
+ *
+ * @example
+ * ```ts
+ * isMCPConsumerFilter({ promptsListChanged: true }) // true
+ * isMCPConsumerFilter({ toolsListChanged: true }) // false
+ * ```
+ */
+export declare function isMCPConsumerFilter(value: unknown): value is MCPConsumerFilter;
+
 /**
  * Determines whether a value is one exact dated-schema MCP tool content block.
  *
@@ -2151,6 +2167,24 @@ export declare function isMCPTaskStatus(value: unknown): value is MCPTaskStatus;
  */
 export declare function isMCPTextResource(value: unknown): value is MCPTextResource;
 
+/**
+ * Checks whether a value carries valid consumed MCP 2026-07-28 tool annotation hints.
+ *
+ * @remarks
+ * Validates only `readOnlyHint` and `destructiveHint`; other wire fields are not consumed, so
+ * the open `objectOf` combinator carries them through unread. Every declared member is
+ * optional, a hostile read answers `false` rather than throwing, and an array is refused.
+ *
+ * @param value - The unknown wire annotations
+ * @returns True if consumed annotation fields are optional booleans; false otherwise
+ *
+ * @example
+ * ```ts
+ * isMCPToolAnnotations({ readOnlyHint: false }) // true
+ * ```
+ */
+export declare function isMCPToolAnnotations(value: unknown): value is MCPToolAnnotations;
+
 /**
  * Determines whether a value is a supported {@link MCPVersion}.
  *
@@ -2628,6 +2662,19 @@ export declare interface MCPAnnotations {
     readonly lastModified?: string;
 }
 
+/**
+ * Projects MCP wire hints onto domain tool annotations without inventing defaults.
+ *
+ * @param annotations - The validated MCP wire annotations
+ * @returns The mapped annotations; unmapped wire hints are omitted
+ *
+ * @example
+ * ```ts
+ * mcpAnnotationsToTool({ readOnlyHint: false, destructiveHint: true }) // { pure: false, consequential: true }
+ * ```
+ */
+export declare function mcpAnnotationsToTool(annotations: MCPToolAnnotations): ToolAnnotations;
+
 /** Represents a base64-encoded audio MCP content block. */
 export declare interface MCPAudioContent {
     readonly type: 'audio';
@@ -2986,9 +3033,11 @@ export declare interface MCPClientInterface {
      *
      * @remarks
      * Runs `tools/list` and maps each descriptor: `name` (narrowed to a string),
-     * `description`, and `inputSchema` → `parameters` (the inverse of the server's
-     * `parameters` → `inputSchema` rename). Add the returned tools to an agent's
-     * {@link ToolManagerInterface} to give it the remote tools.
+     * `title`, `description`, `inputSchema` → `parameters`, and the mapped annotation hints.
+     * The wrapped handler forwards its context signal into {@link call}. The result is a
+     * snapshot; fetch it again to refresh an agent's {@link ToolManagerInterface}.
+     * A summary authored on the remote tool replaces its advertised description, so the
+     * separate summary and full description cannot be recovered from this wire view.
      *
      * @returns The remote tools as local {@link ToolInterface}s, in server order
      */
@@ -3140,6 +3189,12 @@ export declare interface MCPCompletionResult {
     readonly _meta?: MCPResultMetaObject;
 }
 
+/** Declares the consumer-produced notification families, excluding registry-owned tools changes. */
+export declare interface MCPConsumerFilter extends MCPSubscriptionFilter {
+    /** Leaves tools changes to the server's registry. */
+    readonly toolsListChanged?: false;
+}
+
 /** Represents one exact dated-schema tool content block. */
 export declare type MCPContent = MCPTextContent | MCPImageContent | MCPAudioContent | MCPResourceLink | MCPEmbeddedResource;
 
@@ -3357,9 +3412,12 @@ export declare type MCPEra = 'modern' | 'legacy';
  * optional structured context.
  *
  * @remarks
- * {@link MCPClient} throws this error for a remote JSON-RPC `error` response and for a
- * locally detected protocol incompatibility. Local lifecycle and transport conditions such
- * as disconnects and request timeouts remain plain `Error`s. For a remote response, `context`
+ * {@link MCPClient} throws this error for a remote JSON-RPC `error` response, for a locally
+ * detected protocol incompatibility, and for a session-bound request refused because the
+ * client holds no connection — that one carries `-32600`, so a caller separates "reconnect"
+ * from "retry" without reading a message. Local lifecycle and transport conditions that
+ * settle a request already in flight, such as a disconnect and a request timeout, remain
+ * plain `Error`s. For a remote response, `context`
  * carries the optional `error.data` unchanged and is `undefined` when the peer omitted it.
  * This includes the modern reserved paths: `-32020` carries no context, `-32021` may carry
  * `requiredCapabilities`, and `-32022` carries the peer's `supported` revisions and
@@ -3389,12 +3447,19 @@ export declare class MCPError extends Error {
     constructor(message: string, code: number, context?: unknown);
 }
 
-/** Represents the explicit, host-neutral context for one modern tool execution. */
+/**
+ * Represents the explicit, host-neutral context for one modern tool execution.
+ *
+ * @remarks
+ * The default execution path forwards the request signal and caller to the tool manager.
+ * A delegating execution handler forwards `signal` and `caller` itself.
+ */
 export declare interface MCPExecutionContext {
     readonly request: JSONRPCRequest;
     readonly call: ToolCall;
     readonly tools: ToolManagerInterface;
     readonly signal: AbortSignal;
+    readonly caller?: unknown;
     readonly progress?: MCPProgressInterface;
 }
 
@@ -4840,12 +4905,10 @@ export declare interface MCPServerOptions {
      * Holds the optional explicit execution policy above the canonical live tool registry.
      *
      * @remarks
-     * This is also the only way a tool observes cancellation. The default path calls
-     * {@link ToolManagerInterface.execute}, whose signature takes a call and nothing else, so
-     * there is no seam to hand a signal through — a server with no `execution` runs its tool to
-     * completion even after the request that asked for it has ended, and abandons the result.
-     * An {@link MCPExecutionHandler} receives `signal` on its {@link MCPExecutionContext} and
-     * can stop the work itself.
+     * The default path forwards the request signal and optional caller through
+     * {@link ToolManagerInterface.execute}. An {@link MCPExecutionHandler} receives them on
+     * its {@link MCPExecutionContext}; a delegating handler forwards `signal` and `caller`
+     * to the manager itself. Tool handlers observe the signal to stop their work.
      *
      * A handler returning a complete {@link MCPCallResult} is taken at its word: the server
      * bounds it and re-proves its shape, then sends what the handler composed. Nothing stamps
@@ -4865,7 +4928,13 @@ export declare interface MCPServerOptions {
      * consumer-supplied.
      */
     readonly input?: MCPInputOptions;
-    /** Holds the optional event-driven producer for the modern `subscriptions/listen` method. */
+    /**
+     * Holds the optional consumer producer for modern subscriptions. The server supplies the
+     * tools family from its registry independently. The producer advances on stream demand;
+     * a failure terminates the stream after its queued notifications. Registry changes
+     * coalesce while a tools notification remains unread. A consumer filter claiming
+     * `toolsListChanged: true` throws `MCPError` with `JSONRPC_INVALID_PARAMS` at construction.
+     */
     readonly subscription?: MCPSubscriptionOptions;
     /**
      * Holds the optional Tasks extension; the durable store and the deferral decision are
@@ -5097,7 +5166,7 @@ export declare interface MCPStreamControllerInterface extends MCPStream {
 }
 
 /**
- * Names the notification families a client may opt in to on a `subscriptions/listen` stream.
+ * Names the notification families a client may opt in to on a `subscriptions/listen` stream, including built-in registry changes.
  *
  * @remarks
  * Every key here is a wire spelling, carried verbatim from the dated schema's
@@ -5108,7 +5177,7 @@ export declare interface MCPStreamControllerInterface extends MCPStream {
  * and takes the `MCP` prefix; the keys are the protocol's and do not change.
  */
 export declare interface MCPSubscriptionFilter {
-    /** Receives `notifications/tools/list_changed` when the server produces it. */
+    /** Receives built-in `notifications/tools/list_changed` from registry add, remove, and clear events. */
     readonly toolsListChanged?: boolean;
     /** Receives `notifications/prompts/list_changed` when the server produces it. */
     readonly promptsListChanged?: boolean;
@@ -5141,9 +5210,13 @@ export declare interface MCPSubscriptionFilter {
  * Produces notifications for one honoured `subscriptions/listen` filter.
  *
  * @remarks
- * The producer parks on its own event source while idle and ends its iterable to close the
- * subscription gracefully. `options.signal` is the per-request cancellation signal; a
- * producer that needs cancellation observes it directly rather than polling.
+ * The producer parks on its own event source while idle. Ending its iterable closes the
+ * subscription gracefully when the honoured filter omits the built-in tools family. A
+ * subscription honouring that family stays open until failure or signal abort.
+ * `options.signal` is the per-request cancellation signal; a producer that needs
+ * cancellation observes it directly rather than polling. The server releases the source's
+ * iterator with that signal's reason, so a `ReadableStream`-backed producer sees its pending
+ * writes reject with the reason the request was aborted with.
  *
  * @param notifications - The requested filter intersected with the server's supported filter
  * @param options - The resolved per-request method options
@@ -5153,9 +5226,19 @@ export declare type MCPSubscriptionHandler = (notifications: MCPSubscriptionFilt
 
 /** Configures the server's built-in `subscriptions/listen` method. */
 export declare interface MCPSubscriptionOptions {
-    /** Holds the notification filter this server can actually honour. */
-    readonly notifications: MCPSubscriptionFilter;
-    /** Opens the producer for one honoured filter. */
+    /**
+     * Holds the consumer's supported filter. A malformed filter, and one claiming
+     * `toolsListChanged: true`, are both invalid.
+     */
+    readonly notifications: MCPConsumerFilter;
+    /**
+     * Opens the consumer producer beside the server's built-in tools producer.
+     *
+     * @remarks
+     * The producer advances on the stream's demand. A failure terminates the stream after
+     * the notifications it already produced. Registry changes coalesce while a tools
+     * notification remains unread.
+     */
     readonly producer: MCPSubscriptionHandler;
 }
 
@@ -5456,7 +5539,7 @@ export declare type MCPTaskDetailResult = MCPTaskDetail & {
  *
  * The returned string is the stable operation key the manager deduplicates on: the same
  * logical call must produce the same key, and two different calls must not. Mint it from
- * the caller and the canonical call — never from `call.id`, which is the client's own
+ * `options.caller` and the canonical call — never from `call.id`, which is the client's own
  * JSON-RPC request id: a retry of one logical call changes it, so dedup never fires, and
  * two principals whose clients both started counting at 1 collide on it.
  *
@@ -5845,8 +5928,22 @@ export declare interface MCPTextStreamControllerInterface extends MCPTextStream
 }
 
 /**
- * Represents one entry of the MCP `tools/list` result — a tool's `name`, optional
- * `description`, and its JSON-Schema `inputSchema`.
+ * Describes tool hints using the MCP 2026-07-28 specification's wire field names.
+ *
+ * @remarks
+ * These hints describe behavior; they do not authorize execution. The domain projection
+ * carries `pure` as `readOnlyHint` and `consequential` as `destructiveHint`.
+ */
+export declare interface MCPToolAnnotations {
+    readonly title?: string;
+    readonly readOnlyHint?: boolean;
+    readonly destructiveHint?: boolean;
+    readonly idempotentHint?: boolean;
+    readonly openWorldHint?: boolean;
+}
+
+/**
+ * Represents one entry of the MCP `tools/list` result with its display metadata and JSON-Schema input.
  *
  * @remarks
  * The wire renaming of a `ToolDefinition`: `name` / `description` carry through,
@@ -5855,8 +5952,10 @@ export declare interface MCPTextStreamControllerInterface extends MCPTextStream
  */
 export declare interface MCPToolDescriptor {
     readonly name: string;
+    readonly title?: string;
     readonly description?: string;
     readonly inputSchema: Readonly<Record<string, unknown>>;
+    readonly annotations?: MCPToolAnnotations;
 }
 
 /** Represents one tool's outcome returned to the model, carried in a sampling completion. */
@@ -6303,4 +6402,17 @@ export declare function supportsFormElicitation(value: unknown): boolean;
  */
 export declare function supportsTask(value: unknown): boolean;
 
+/**
+ * Projects domain tool annotations onto MCP wire hints without inventing defaults.
+ *
+ * @param annotations - The authored domain annotations
+ * @returns The mapped hints; `untrusted` has no MCP counterpart
+ *
+ * @example
+ * ```ts
+ * toolAnnotationsToMCP({ pure: true, consequential: false }) // { readOnlyHint: true, destructiveHint: false }
+ * ```
+ */
+export declare function toolAnnotationsToMCP(annotations: ToolAnnotations): MCPToolAnnotations;
+
 export { }

package/dist/src/core/index.d.ts

@@ -2,6 +2,7 @@ import type { EmitterErrorHandler } from '@orkestrel/emitter';
 import type { EmitterHooks } from '@orkestrel/emitter';
 import type { EmitterInterface } from '@orkestrel/emitter';
 import type { JSONValue } from '@orkestrel/contract';
+import type { ToolAnnotations } from '@orkestrel/tool';
 import type { ToolCall } from '@orkestrel/tool';
 import type { ToolInterface } from '@orkestrel/tool';
 import type { ToolManagerInterface } from '@orkestrel/tool';
@@ -177,10 +178,11 @@ export declare function buildCancelledNotification(id: JSONRPCId, reason?: strin
  * @remarks
  * `capabilities.resources` and `capabilities.prompts` appear only for servers with their
  * respective managers and derive notification flags from the configured subscription filter.
- * `capabilities.completions` is independent and appears only with a completion provider.
- * `capabilities.extensions` appears only for a server that configured the extension it
- * would name. An advertisement is a promise a client is entitled to act on, so a server
- * with no `task` policy omits the member entirely rather than advertising an empty
+ * `tools.listChanged` is always advertised because the server produces the family from its
+ * own registry. `capabilities.completions` is independent and appears only with a completion
+ * provider. `capabilities.extensions` appears only for a server that configured the
+ * extension it would name. An advertisement is a promise a client is entitled to act on, so
+ * a server with no `task` policy omits the member entirely rather than advertising an empty
  * record — and its discovery answer stays byte-for-byte what it was before the extension
  * existed.
  *
@@ -405,11 +407,10 @@ export declare function buildSubscriptionResult(id: JSONRPCId, identity: MCPIden
  * Builds the canonical Tool call for one validated MCP `tools/call` request.
  *
  * @param request - The original MCP request
- * @param caller - Optional consumer-asserted caller context
  * @param args - Optional once-validated modern arguments; omission retains legacy normalization
  * @returns The canonical call, or `undefined` when the name is invalid
  */
-export declare function buildToolCall(request: JSONRPCRequest, caller?: unknown, args?: Readonly<Record<string, unknown>>): ToolCall | undefined;
+export declare function buildToolCall(request: JSONRPCRequest, args?: Readonly<Record<string, unknown>>): ToolCall | undefined;
 
 /**
  * Maps a {@link ToolManagerInterface}'s definitions to MCP `tools/list` descriptors
@@ -417,7 +418,8 @@ export declare function buildToolCall(request: JSONRPCRequest, caller?: unknown,
  *
  * @remarks
  * Each {@link import('@orkestrel/tool').ToolDefinition} carries through its
- * `name` and (when present) `description`; its open JSON-Schema `parameters`
+ * `name`, optional `title` and `description`, and mapped annotation hints;
+ * its open JSON-Schema `parameters`
  * becomes `inputSchema`, defaulting to an empty object schema (`{ type: 'object' }`)
  * when a tool declares none (MCP requires an `inputSchema`).
  *
@@ -1488,6 +1490,20 @@ export declare function isMCPCompletionReference(value: unknown): value is MCPCo
  */
 export declare function isMCPCompletionResult(value: unknown): value is MCPCompletionResult;
 
+/**
+ * Checks whether a subscription filter leaves the built-in tools family to the server.
+ *
+ * @param value - The unknown value to inspect
+ * @returns True if the filter is valid and does not claim tools changes; false otherwise
+ *
+ * @example
+ * ```ts
+ * isMCPConsumerFilter({ promptsListChanged: true }) // true
+ * isMCPConsumerFilter({ toolsListChanged: true }) // false
+ * ```
+ */
+export declare function isMCPConsumerFilter(value: unknown): value is MCPConsumerFilter;
+
 /**
  * Determines whether a value is one exact dated-schema MCP tool content block.
  *
@@ -2151,6 +2167,24 @@ export declare function isMCPTaskStatus(value: unknown): value is MCPTaskStatus;
  */
 export declare function isMCPTextResource(value: unknown): value is MCPTextResource;
 
+/**
+ * Checks whether a value carries valid consumed MCP 2026-07-28 tool annotation hints.
+ *
+ * @remarks
+ * Validates only `readOnlyHint` and `destructiveHint`; other wire fields are not consumed, so
+ * the open `objectOf` combinator carries them through unread. Every declared member is
+ * optional, a hostile read answers `false` rather than throwing, and an array is refused.
+ *
+ * @param value - The unknown wire annotations
+ * @returns True if consumed annotation fields are optional booleans; false otherwise
+ *
+ * @example
+ * ```ts
+ * isMCPToolAnnotations({ readOnlyHint: false }) // true
+ * ```
+ */
+export declare function isMCPToolAnnotations(value: unknown): value is MCPToolAnnotations;
+
 /**
  * Determines whether a value is a supported {@link MCPVersion}.
  *
@@ -2628,6 +2662,19 @@ export declare interface MCPAnnotations {
     readonly lastModified?: string;
 }
 
+/**
+ * Projects MCP wire hints onto domain tool annotations without inventing defaults.
+ *
+ * @param annotations - The validated MCP wire annotations
+ * @returns The mapped annotations; unmapped wire hints are omitted
+ *
+ * @example
+ * ```ts
+ * mcpAnnotationsToTool({ readOnlyHint: false, destructiveHint: true }) // { pure: false, consequential: true }
+ * ```
+ */
+export declare function mcpAnnotationsToTool(annotations: MCPToolAnnotations): ToolAnnotations;
+
 /** Represents a base64-encoded audio MCP content block. */
 export declare interface MCPAudioContent {
     readonly type: 'audio';
@@ -2986,9 +3033,11 @@ export declare interface MCPClientInterface {
      *
      * @remarks
      * Runs `tools/list` and maps each descriptor: `name` (narrowed to a string),
-     * `description`, and `inputSchema` → `parameters` (the inverse of the server's
-     * `parameters` → `inputSchema` rename). Add the returned tools to an agent's
-     * {@link ToolManagerInterface} to give it the remote tools.
+     * `title`, `description`, `inputSchema` → `parameters`, and the mapped annotation hints.
+     * The wrapped handler forwards its context signal into {@link call}. The result is a
+     * snapshot; fetch it again to refresh an agent's {@link ToolManagerInterface}.
+     * A summary authored on the remote tool replaces its advertised description, so the
+     * separate summary and full description cannot be recovered from this wire view.
      *
      * @returns The remote tools as local {@link ToolInterface}s, in server order
      */
@@ -3140,6 +3189,12 @@ export declare interface MCPCompletionResult {
     readonly _meta?: MCPResultMetaObject;
 }
 
+/** Declares the consumer-produced notification families, excluding registry-owned tools changes. */
+export declare interface MCPConsumerFilter extends MCPSubscriptionFilter {
+    /** Leaves tools changes to the server's registry. */
+    readonly toolsListChanged?: false;
+}
+
 /** Represents one exact dated-schema tool content block. */
 export declare type MCPContent = MCPTextContent | MCPImageContent | MCPAudioContent | MCPResourceLink | MCPEmbeddedResource;
 
@@ -3357,9 +3412,12 @@ export declare type MCPEra = 'modern' | 'legacy';
  * optional structured context.
  *
  * @remarks
- * {@link MCPClient} throws this error for a remote JSON-RPC `error` response and for a
- * locally detected protocol incompatibility. Local lifecycle and transport conditions such
- * as disconnects and request timeouts remain plain `Error`s. For a remote response, `context`
+ * {@link MCPClient} throws this error for a remote JSON-RPC `error` response, for a locally
+ * detected protocol incompatibility, and for a session-bound request refused because the
+ * client holds no connection — that one carries `-32600`, so a caller separates "reconnect"
+ * from "retry" without reading a message. Local lifecycle and transport conditions that
+ * settle a request already in flight, such as a disconnect and a request timeout, remain
+ * plain `Error`s. For a remote response, `context`
  * carries the optional `error.data` unchanged and is `undefined` when the peer omitted it.
  * This includes the modern reserved paths: `-32020` carries no context, `-32021` may carry
  * `requiredCapabilities`, and `-32022` carries the peer's `supported` revisions and
@@ -3389,12 +3447,19 @@ export declare class MCPError extends Error {
     constructor(message: string, code: number, context?: unknown);
 }
 
-/** Represents the explicit, host-neutral context for one modern tool execution. */
+/**
+ * Represents the explicit, host-neutral context for one modern tool execution.
+ *
+ * @remarks
+ * The default execution path forwards the request signal and caller to the tool manager.
+ * A delegating execution handler forwards `signal` and `caller` itself.
+ */
 export declare interface MCPExecutionContext {
     readonly request: JSONRPCRequest;
     readonly call: ToolCall;
     readonly tools: ToolManagerInterface;
     readonly signal: AbortSignal;
+    readonly caller?: unknown;
     readonly progress?: MCPProgressInterface;
 }
 
@@ -4840,12 +4905,10 @@ export declare interface MCPServerOptions {
      * Holds the optional explicit execution policy above the canonical live tool registry.
      *
      * @remarks
-     * This is also the only way a tool observes cancellation. The default path calls
-     * {@link ToolManagerInterface.execute}, whose signature takes a call and nothing else, so
-     * there is no seam to hand a signal through — a server with no `execution` runs its tool to
-     * completion even after the request that asked for it has ended, and abandons the result.
-     * An {@link MCPExecutionHandler} receives `signal` on its {@link MCPExecutionContext} and
-     * can stop the work itself.
+     * The default path forwards the request signal and optional caller through
+     * {@link ToolManagerInterface.execute}. An {@link MCPExecutionHandler} receives them on
+     * its {@link MCPExecutionContext}; a delegating handler forwards `signal` and `caller`
+     * to the manager itself. Tool handlers observe the signal to stop their work.
      *
      * A handler returning a complete {@link MCPCallResult} is taken at its word: the server
      * bounds it and re-proves its shape, then sends what the handler composed. Nothing stamps
@@ -4865,7 +4928,13 @@ export declare interface MCPServerOptions {
      * consumer-supplied.
      */
     readonly input?: MCPInputOptions;
-    /** Holds the optional event-driven producer for the modern `subscriptions/listen` method. */
+    /**
+     * Holds the optional consumer producer for modern subscriptions. The server supplies the
+     * tools family from its registry independently. The producer advances on stream demand;
+     * a failure terminates the stream after its queued notifications. Registry changes
+     * coalesce while a tools notification remains unread. A consumer filter claiming
+     * `toolsListChanged: true` throws `MCPError` with `JSONRPC_INVALID_PARAMS` at construction.
+     */
     readonly subscription?: MCPSubscriptionOptions;
     /**
      * Holds the optional Tasks extension; the durable store and the deferral decision are
@@ -5097,7 +5166,7 @@ export declare interface MCPStreamControllerInterface extends MCPStream {
 }
 
 /**
- * Names the notification families a client may opt in to on a `subscriptions/listen` stream.
+ * Names the notification families a client may opt in to on a `subscriptions/listen` stream, including built-in registry changes.
  *
  * @remarks
  * Every key here is a wire spelling, carried verbatim from the dated schema's
@@ -5108,7 +5177,7 @@ export declare interface MCPStreamControllerInterface extends MCPStream {
  * and takes the `MCP` prefix; the keys are the protocol's and do not change.
  */
 export declare interface MCPSubscriptionFilter {
-    /** Receives `notifications/tools/list_changed` when the server produces it. */
+    /** Receives built-in `notifications/tools/list_changed` from registry add, remove, and clear events. */
     readonly toolsListChanged?: boolean;
     /** Receives `notifications/prompts/list_changed` when the server produces it. */
     readonly promptsListChanged?: boolean;
@@ -5141,9 +5210,13 @@ export declare interface MCPSubscriptionFilter {
  * Produces notifications for one honoured `subscriptions/listen` filter.
  *
  * @remarks
- * The producer parks on its own event source while idle and ends its iterable to close the
- * subscription gracefully. `options.signal` is the per-request cancellation signal; a
- * producer that needs cancellation observes it directly rather than polling.
+ * The producer parks on its own event source while idle. Ending its iterable closes the
+ * subscription gracefully when the honoured filter omits the built-in tools family. A
+ * subscription honouring that family stays open until failure or signal abort.
+ * `options.signal` is the per-request cancellation signal; a producer that needs
+ * cancellation observes it directly rather than polling. The server releases the source's
+ * iterator with that signal's reason, so a `ReadableStream`-backed producer sees its pending
+ * writes reject with the reason the request was aborted with.
  *
  * @param notifications - The requested filter intersected with the server's supported filter
  * @param options - The resolved per-request method options
@@ -5153,9 +5226,19 @@ export declare type MCPSubscriptionHandler = (notifications: MCPSubscriptionFilt
 
 /** Configures the server's built-in `subscriptions/listen` method. */
 export declare interface MCPSubscriptionOptions {
-    /** Holds the notification filter this server can actually honour. */
-    readonly notifications: MCPSubscriptionFilter;
-    /** Opens the producer for one honoured filter. */
+    /**
+     * Holds the consumer's supported filter. A malformed filter, and one claiming
+     * `toolsListChanged: true`, are both invalid.
+     */
+    readonly notifications: MCPConsumerFilter;
+    /**
+     * Opens the consumer producer beside the server's built-in tools producer.
+     *
+     * @remarks
+     * The producer advances on the stream's demand. A failure terminates the stream after
+     * the notifications it already produced. Registry changes coalesce while a tools
+     * notification remains unread.
+     */
     readonly producer: MCPSubscriptionHandler;
 }
 
@@ -5456,7 +5539,7 @@ export declare type MCPTaskDetailResult = MCPTaskDetail & {
  *
  * The returned string is the stable operation key the manager deduplicates on: the same
  * logical call must produce the same key, and two different calls must not. Mint it from
- * the caller and the canonical call — never from `call.id`, which is the client's own
+ * `options.caller` and the canonical call — never from `call.id`, which is the client's own
  * JSON-RPC request id: a retry of one logical call changes it, so dedup never fires, and
  * two principals whose clients both started counting at 1 collide on it.
  *
@@ -5845,8 +5928,22 @@ export declare interface MCPTextStreamControllerInterface extends MCPTextStream
 }
 
 /**
- * Represents one entry of the MCP `tools/list` result — a tool's `name`, optional
- * `description`, and its JSON-Schema `inputSchema`.
+ * Describes tool hints using the MCP 2026-07-28 specification's wire field names.
+ *
+ * @remarks
+ * These hints describe behavior; they do not authorize execution. The domain projection
+ * carries `pure` as `readOnlyHint` and `consequential` as `destructiveHint`.
+ */
+export declare interface MCPToolAnnotations {
+    readonly title?: string;
+    readonly readOnlyHint?: boolean;
+    readonly destructiveHint?: boolean;
+    readonly idempotentHint?: boolean;
+    readonly openWorldHint?: boolean;
+}
+
+/**
+ * Represents one entry of the MCP `tools/list` result with its display metadata and JSON-Schema input.
  *
  * @remarks
  * The wire renaming of a `ToolDefinition`: `name` / `description` carry through,
@@ -5855,8 +5952,10 @@ export declare interface MCPTextStreamControllerInterface extends MCPTextStream
  */
 export declare interface MCPToolDescriptor {
     readonly name: string;
+    readonly title?: string;
     readonly description?: string;
     readonly inputSchema: Readonly<Record<string, unknown>>;
+    readonly annotations?: MCPToolAnnotations;
 }
 
 /** Represents one tool's outcome returned to the model, carried in a sampling completion. */
@@ -6303,4 +6402,17 @@ export declare function supportsFormElicitation(value: unknown): boolean;
  */
 export declare function supportsTask(value: unknown): boolean;
 
+/**
+ * Projects domain tool annotations onto MCP wire hints without inventing defaults.
+ *
+ * @param annotations - The authored domain annotations
+ * @returns The mapped hints; `untrusted` has no MCP counterpart
+ *
+ * @example
+ * ```ts
+ * toolAnnotationsToMCP({ pure: true, consequential: false }) // { readOnlyHint: true, destructiveHint: false }
+ * ```
+ */
+export declare function toolAnnotationsToMCP(annotations: ToolAnnotations): MCPToolAnnotations;
+
 export { }