functionalscript 0.46.1 → 0.47.0

package/fjs/protocol/mcp/module.f.d.mts

@@ -17,9 +17,9 @@
  * @import { Ts } from '../../types/rtti/ts/types.ts'
  * @import { Effect, Operation } from '../../effects/types.ts'
  * @import { Key, MemOp } from '../../effects/memory/types.ts'
- * @import { Response, Id, RpcError } from '../json_rpc/types.ts'
+ * @import { Response } from '../json_rpc/types.ts'
  * @import { Type } from '../../types/rtti/types.ts'
- * @import { Implementation, ServerCapabilities, InitializeResult, Tool, ToolsListParams, ToolsCallResult, McpHandlers, ToolEntry, McpSessionState, McpConfig } from './types.ts'
+ * @import { Implementation, ServerCapabilities, InitializeResult, Tool, ToolsListParams, ToolsCallResult, McpHandlers, ToolEntry, McpSessionState, McpConfig, ProtocolVersions } from './types.ts'
  */
 import type { Unknown } from '../../media/json/types.ts';
 import type { Ts } from '../../types/rtti/ts/types.ts';
@@ -29,123 +29,123 @@ import type { Response } from '../json_rpc/types.ts';
 import type { Type } from '../../types/rtti/types.ts';
 import type { ToolsCallResult, McpHandlers, ToolEntry, McpSessionState, McpConfig } from './types.ts';
 /** Name + version pair sent in `initialize` requests and responses. */
-export declare const implementation: {
+export declare const implementation: import("../../types/rtti/types.ts").Rest<{
     readonly name: import("../../types/rtti/types.ts")._Type0<"string">;
     readonly version: import("../../types/rtti/types.ts")._Type0<"string">;
-};
+}, import("../../types/rtti/types.ts").Unknown>;
 /** Server capabilities advertised in the `initialize` response. */
-export declare const serverCapabilities: {
-    readonly tools: import("../../types/rtti/types.ts").Or<readonly [{
+export declare const serverCapabilities: import("../../types/rtti/types.ts").Rest<{
+    readonly tools: import("../../types/rtti/types.ts").Or<readonly [import("../../types/rtti/types.ts").Rest<{
         readonly listChanged: import("../../types/rtti/types.ts").Or<readonly [import("../../types/rtti/types.ts")._Type0<"boolean">, undefined]>;
-    }, undefined]>;
-};
+    }, import("../../types/rtti/types.ts").Unknown>, undefined]>;
+}, import("../../types/rtti/types.ts").Unknown>;
 /** Params for the `initialize` request. */
-export declare const initializeParams: {
+export declare const initializeParams: import("../../types/rtti/types.ts").Rest<{
     readonly protocolVersion: import("../../types/rtti/types.ts")._Type0<"string">;
     readonly capabilities: () => readonly ['or', typeof import("../../media/json/rtti/module.f.mjs").primitive, typeof import("../../media/json/rtti/module.f.mjs").object, typeof import("../../media/json/rtti/module.f.mjs").array];
-    readonly clientInfo: {
+    readonly clientInfo: import("../../types/rtti/types.ts").Rest<{
         readonly name: import("../../types/rtti/types.ts")._Type0<"string">;
         readonly version: import("../../types/rtti/types.ts")._Type0<"string">;
-    };
-};
+    }, import("../../types/rtti/types.ts").Unknown>;
+}, import("../../types/rtti/types.ts").Unknown>;
 /** Result for the `initialize` request. */
-export declare const initializeResult: {
+export declare const initializeResult: import("../../types/rtti/types.ts").Rest<{
     readonly protocolVersion: import("../../types/rtti/types.ts")._Type0<"string">;
-    readonly capabilities: {
-        readonly tools: import("../../types/rtti/types.ts").Or<readonly [{
+    readonly capabilities: import("../../types/rtti/types.ts").Rest<{
+        readonly tools: import("../../types/rtti/types.ts").Or<readonly [import("../../types/rtti/types.ts").Rest<{
             readonly listChanged: import("../../types/rtti/types.ts").Or<readonly [import("../../types/rtti/types.ts")._Type0<"boolean">, undefined]>;
-        }, undefined]>;
-    };
-    readonly serverInfo: {
+        }, import("../../types/rtti/types.ts").Unknown>, undefined]>;
+    }, import("../../types/rtti/types.ts").Unknown>;
+    readonly serverInfo: import("../../types/rtti/types.ts").Rest<{
         readonly name: import("../../types/rtti/types.ts")._Type0<"string">;
         readonly version: import("../../types/rtti/types.ts")._Type0<"string">;
-    };
+    }, import("../../types/rtti/types.ts").Unknown>;
     readonly instructions: import("../../types/rtti/types.ts").Or<readonly [import("../../types/rtti/types.ts")._Type0<"string">, undefined]>;
-};
+}, import("../../types/rtti/types.ts").Unknown>;
 /** Plain-text content item returned by a tool call. */
-export declare const textContent: {
+export declare const textContent: import("../../types/rtti/types.ts").Rest<{
     readonly type: 'text';
     readonly text: import("../../types/rtti/types.ts")._Type0<"string">;
-};
+}, import("../../types/rtti/types.ts").Unknown>;
 /**
  * A binary resource carried inside an {@link embeddedResource}: a base64
  * `blob`, an addressing `uri`, and an optional `mimeType`. This is MCP's
  * `BlobResource` shape — the idiomatic way to return typed binary content so a
  * `mimeType` travels alongside the bytes and clients know how to route them.
  */
-export declare const blobResource: {
+export declare const blobResource: import("../../types/rtti/types.ts").Rest<{
     readonly uri: import("../../types/rtti/types.ts")._Type0<"string">;
     readonly mimeType: import("../../types/rtti/types.ts").Or<readonly [import("../../types/rtti/types.ts")._Type0<"string">, undefined]>;
     readonly blob: import("../../types/rtti/types.ts")._Type0<"string">;
-};
+}, import("../../types/rtti/types.ts").Unknown>;
 /** An `EmbeddedResource` content item wrapping a {@link blobResource}. */
-export declare const embeddedResource: {
+export declare const embeddedResource: import("../../types/rtti/types.ts").Rest<{
     readonly type: 'resource';
-    readonly resource: {
+    readonly resource: import("../../types/rtti/types.ts").Rest<{
         readonly uri: import("../../types/rtti/types.ts")._Type0<"string">;
         readonly mimeType: import("../../types/rtti/types.ts").Or<readonly [import("../../types/rtti/types.ts")._Type0<"string">, undefined]>;
         readonly blob: import("../../types/rtti/types.ts")._Type0<"string">;
-    };
-};
+    }, import("../../types/rtti/types.ts").Unknown>;
+}, import("../../types/rtti/types.ts").Unknown>;
 /**
  * A single item in a `tools/call` result's `content` array: either plain
  * {@link textContent} or an {@link embeddedResource} for typed binary. The
  * `image` and `audio` variants are not modelled yet.
  */
-export declare const contentItem: import("../../types/rtti/types.ts").Or<[{
+export declare const contentItem: import("../../types/rtti/types.ts").Or<readonly [import("../../types/rtti/types.ts").Rest<{
     readonly type: 'text';
     readonly text: import("../../types/rtti/types.ts")._Type0<"string">;
-}, {
+}, import("../../types/rtti/types.ts").Unknown>, import("../../types/rtti/types.ts").Rest<{
     readonly type: 'resource';
-    readonly resource: {
+    readonly resource: import("../../types/rtti/types.ts").Rest<{
         readonly uri: import("../../types/rtti/types.ts")._Type0<"string">;
         readonly mimeType: import("../../types/rtti/types.ts").Or<readonly [import("../../types/rtti/types.ts")._Type0<"string">, undefined]>;
         readonly blob: import("../../types/rtti/types.ts")._Type0<"string">;
-    };
-}]>;
+    }, import("../../types/rtti/types.ts").Unknown>;
+}, import("../../types/rtti/types.ts").Unknown>]>;
 /**
  * A tool descriptor returned by `tools/list`.
  * `inputSchema` is a JSON Schema object — use `toJsonSchema` to derive it from
  * an rtti schema.
  */
-export declare const tool: {
+export declare const tool: import("../../types/rtti/types.ts").Rest<{
     readonly name: import("../../types/rtti/types.ts")._Type0<"string">;
     readonly description: import("../../types/rtti/types.ts").Or<readonly [import("../../types/rtti/types.ts")._Type0<"string">, undefined]>;
     readonly inputSchema: () => readonly ['or', typeof import("../../media/json/rtti/module.f.mjs").primitive, typeof import("../../media/json/rtti/module.f.mjs").object, typeof import("../../media/json/rtti/module.f.mjs").array];
-};
+}, import("../../types/rtti/types.ts").Unknown>;
 /**
  * Params for the `tools/list` request. `cursor` is an opaque pagination token
  * from a previous `ToolsListResult.nextCursor`.
  */
-export declare const toolsListParams: {
+export declare const toolsListParams: import("../../types/rtti/types.ts").Rest<{
     readonly cursor: import("../../types/rtti/types.ts").Or<readonly [import("../../types/rtti/types.ts")._Type0<"string">, undefined]>;
-};
-export declare const toolsListResult: {
-    readonly tools: import("../../types/rtti/types.ts").Type1<"array", {
+}, import("../../types/rtti/types.ts").Unknown>;
+export declare const toolsListResult: import("../../types/rtti/types.ts").Rest<{
+    readonly tools: import("../../types/rtti/types.ts").Type1<"array", import("../../types/rtti/types.ts").Rest<{
         readonly name: import("../../types/rtti/types.ts")._Type0<"string">;
         readonly description: import("../../types/rtti/types.ts").Or<readonly [import("../../types/rtti/types.ts")._Type0<"string">, undefined]>;
         readonly inputSchema: () => readonly ['or', typeof import("../../media/json/rtti/module.f.mjs").primitive, typeof import("../../media/json/rtti/module.f.mjs").object, typeof import("../../media/json/rtti/module.f.mjs").array];
-    }>;
+    }, import("../../types/rtti/types.ts").Unknown>>;
     readonly nextCursor: import("../../types/rtti/types.ts").Or<readonly [import("../../types/rtti/types.ts")._Type0<"string">, undefined]>;
-};
-export declare const toolsCallParams: {
+}, import("../../types/rtti/types.ts").Unknown>;
+export declare const toolsCallParams: import("../../types/rtti/types.ts").Rest<{
     readonly name: import("../../types/rtti/types.ts")._Type0<"string">;
     readonly arguments: import("../../types/rtti/types.ts").Or<readonly [import("../../types/rtti/types.ts").Type1<"record", () => readonly ['or', typeof import("../../media/json/rtti/module.f.mjs").primitive, typeof import("../../media/json/rtti/module.f.mjs").object, typeof import("../../media/json/rtti/module.f.mjs").array]>, undefined]>;
-};
-export declare const toolsCallResult: {
-    readonly content: import("../../types/rtti/types.ts").Type1<"array", import("../../types/rtti/types.ts").Or<[{
+}, import("../../types/rtti/types.ts").Unknown>;
+export declare const toolsCallResult: import("../../types/rtti/types.ts").Rest<{
+    readonly content: import("../../types/rtti/types.ts").Type1<"array", import("../../types/rtti/types.ts").Or<readonly [import("../../types/rtti/types.ts").Rest<{
         readonly type: 'text';
         readonly text: import("../../types/rtti/types.ts")._Type0<"string">;
-    }, {
+    }, import("../../types/rtti/types.ts").Unknown>, import("../../types/rtti/types.ts").Rest<{
         readonly type: 'resource';
-        readonly resource: {
+        readonly resource: import("../../types/rtti/types.ts").Rest<{
             readonly uri: import("../../types/rtti/types.ts")._Type0<"string">;
             readonly mimeType: import("../../types/rtti/types.ts").Or<readonly [import("../../types/rtti/types.ts")._Type0<"string">, undefined]>;
             readonly blob: import("../../types/rtti/types.ts")._Type0<"string">;
-        };
-    }]>>;
+        }, import("../../types/rtti/types.ts").Unknown>;
+    }, import("../../types/rtti/types.ts").Unknown>]>>;
     readonly isError: import("../../types/rtti/types.ts").Or<readonly [import("../../types/rtti/types.ts")._Type0<"boolean">, undefined]>;
-};
+}, import("../../types/rtti/types.ts").Unknown>;
 /**
  * Creates a type-safe tool entry that binds an RTTI schema with a handler.
  *
@@ -153,7 +153,7 @@ export declare const toolsCallResult: {
  * arguments (typed as `Ts<T>`) to the handler. This eliminates manual validation
  * boilerplate and type assertions.
  *
- * @template {Type} T
+ * @template {Type} const T
  * @template {Operation} O
  * @param {string} name - The tool name (used in `tools/call` requests)
  * @param {string} description - Human-readable description for `tools/list`
@@ -161,7 +161,7 @@ export declare const toolsCallResult: {
  * @param {(args: Ts<T>) => Effect<O, ToolsCallResult, never>} handle - Handler receiving validated arguments of type `Ts<inputRtti>`
  * @returns {ToolEntry<O>} A `ToolEntry` ready to be added to a registry
  */
-export declare const toolEntry: <T extends Type, O extends Operation>(name: string, description: string, inputRtti: T, handle: (args: Ts<T>) => Effect<O, ToolsCallResult, never>) => ToolEntry<O>;
+export declare const toolEntry: <const T extends Type, O extends Operation>(name: string, description: string, inputRtti: T, handle: (args: Ts<T>) => Effect<O, ToolsCallResult, never>) => ToolEntry<O>;
 /**
  * Helper to create a successful single-text-block tool result.
  *
@@ -176,6 +176,36 @@ export declare const okResult: (text: string) => ToolsCallResult;
  * @returns {ToolsCallResult} A `ToolsCallResult` with `isError: true` and the text explanation
  */
 export declare const errorResult: (text: string) => ToolsCallResult;
+/**
+ * Answers a tool call with the outcome of one fallible operation: the `ok`
+ * value rendered by `text`, the failure rendered by `errorText` and tagged
+ * `isError`. It is the third member of the {@link okResult} / {@link errorResult}
+ * family — the one that picks between them — and it empties the error channel,
+ * because a tool-level failure is a result the client reads, never a transport
+ * error.
+ *
+ * Every tool whose body is a single `Evo`- or `Cas`-shaped call is that
+ * dispatch and nothing else, so each one is a single line:
+ *
+ * ```js
+ * ({ subject }) => toolResultStep(e.head(subject), lines, evoSummary)
+ * ```
+ *
+ * **Both renderers are required, and `errorText` is the load-bearing one** —
+ * for the reason `unwrapStep` gives for its own `summary`
+ * (`fjs/effects/module.f.mjs`): a renderer written for a particular error
+ * channel cannot accept a wider one, so a fallible call added upstream turns
+ * into a compile error at the tool that has to say what the new failure reads
+ * like, instead of silently reaching the client as whatever `String` made of
+ * it. `evoSummary` and `errorSummary` are the two in use today.
+ *
+ * @type {<O extends Operation, T, E>(
+ *     e: Effect<O, T, E>,
+ *     text: (value: T) => string,
+ *     errorText: (e: E) => string,
+ * ) => Effect<O, ToolsCallResult, never>}
+ */
+export declare const toolResultStep: <O extends Operation, T, E>(e: Effect<O, T, E>, text: (value: T) => string, errorText: (e: E) => string) => Effect<O, ToolsCallResult, never>;
 /**
  * Builds `McpHandlers` from a registry of tool entries.
  *
@@ -208,7 +238,12 @@ export declare const uninitializedState: McpSessionState;
  * - `ping` returns an empty success regardless of session state; non-object
  *   params → -32602.
  * - `initialize` is accepted only while uninitialized; a second call returns -32600.
- *   On success the state moves to `initializing`, not `initialized`.
+ *   On success the state moves to `initializing`, not `initialized`. The answered
+ *   `protocolVersion` is negotiated against `config.protocolVersions`: the client's
+ *   requested revision when the server supports it, the latest supported one
+ *   otherwise. A counter-proposal is a success frame like any other — the client,
+ *   not the server, decides whether the answer is usable — so the state moves the
+ *   same way in both cases.
  * - `notifications/initialized` (no `id`) transitions `initializing` → `initialized`;
  *   a malformed one (non-object params) is ignored and the session stays gated;
  *   other notifications are silently ignored in any state.
@@ -221,4 +256,4 @@ export declare const uninitializedState: McpSessionState;
  * @param {McpConfig} config
  * @returns {<O extends Operation>(handlers: McpHandlers<O>) => (stateKey: Key<McpSessionState>) => (value: Unknown) => Effect<MemOp | O, Response | null, never>}
  */
-export declare const mcpStep: ({ protocolVersion, capabilities, serverInfo, }: McpConfig) => <O extends Operation>(handlers: McpHandlers<O>) => (stateKey: Key<McpSessionState>) => (value: Unknown) => Effect<MemOp | O, Response | null, never>;
+export declare const mcpStep: ({ protocolVersions, capabilities, serverInfo, }: McpConfig) => <O extends Operation>(handlers: McpHandlers<O>) => (stateKey: Key<McpSessionState>) => (value: Unknown) => Effect<MemOp | O, Response | null, never>;

package/fjs/protocol/mcp/module.f.mjs

@@ -17,19 +17,19 @@
  * @import { Ts } from '../../types/rtti/ts/types.ts'
  * @import { Effect, Operation } from '../../effects/types.ts'
  * @import { Key, MemOp } from '../../effects/memory/types.ts'
- * @import { Response, Id, RpcError } from '../json_rpc/types.ts'
+ * @import { Response } from '../json_rpc/types.ts'
  * @import { Type } from '../../types/rtti/types.ts'
- * @import { Implementation, ServerCapabilities, InitializeResult, Tool, ToolsListParams, ToolsCallResult, McpHandlers, ToolEntry, McpSessionState, McpConfig } from './types.ts'
+ * @import { Implementation, ServerCapabilities, InitializeResult, Tool, ToolsListParams, ToolsCallResult, McpHandlers, ToolEntry, McpSessionState, McpConfig, ProtocolVersions } from './types.ts'
  */
 
-import { boolean, string, option, array, record, or } from '../../types/rtti/module.f.mjs'
+import { boolean, string, open, option, array, record, or } from '../../types/rtti/module.f.mjs'
 import { pureOk, resultMapStep, resultStep, step as ioStep } from '../../effects/module.f.mjs'
 import { ok } from '../../types/result/module.f.mjs'
 import { read, write } from '../../effects/memory/module.f.mjs'
 import {
     decodeRequest,
     rpcError, internalError, invalidRequest, invalidParams, methodNotFound,
-    jsonrpc,
+    errorResponseOf, successResponseOf,
 } from '../json_rpc/module.f.mjs'
 import { parse } from '../../types/rtti/parse/module.f.mjs'
 import { toJsonSchema } from '../../media/json/schema/module.f.mjs'
@@ -37,42 +37,48 @@ import { unknown } from '../../media/json/rtti/module.f.mjs'
 
 // ── Shared ─────────────────────────────────────────────────────────────────────
 
+// Every struct below says `open`, and that is the protocol's requirement
+// rather than a default: a bare struct is closed, and a peer implementing a
+// later revision of MCP sends members this one does not name — a schema that
+// rejected them would fail every such peer outright, where ignoring them is
+// what the specification asks for. Do not drop a wrapper.
+
 /** Name + version pair sent in `initialize` requests and responses. */
-export const implementation = /** @type {const} */ ({
+export const implementation = open(/** @type {const} */ ({
     name: string,
     version: string,
-})
+}))
 
 // ── Capabilities ───────────────────────────────────────────────────────────────
 
-const toolsCapability = /** @type {const} */ ({ listChanged: option(boolean) })
+const toolsCapability = open(/** @type {const} */ ({ listChanged: option(boolean) }))
 
 /** Server capabilities advertised in the `initialize` response. */
-export const serverCapabilities = /** @type {const} */ ({
+export const serverCapabilities = open(/** @type {const} */ ({
     tools: option(toolsCapability),
-})
+}))
 
 // ── Lifecycle ──────────────────────────────────────────────────────────────────
 
 /** Params for the `initialize` request. */
-export const initializeParams = /** @type {const} */ ({
+export const initializeParams = open(/** @type {const} */ ({
     protocolVersion: string,
     capabilities: unknown,
     clientInfo: implementation,
-})
+}))
 
 /** Result for the `initialize` request. */
-export const initializeResult = /** @type {const} */ ({
+export const initializeResult = open(/** @type {const} */ ({
     protocolVersion: string,
     capabilities: serverCapabilities,
     serverInfo: implementation,
     instructions: option(string),
-})
+}))
 
 // ── Content ────────────────────────────────────────────────────────────────────
 
 /** Plain-text content item returned by a tool call. */
-export const textContent = /** @type {const} */ ({ type: 'text', text: string })
+export const textContent = open(/** @type {const} */ ({ type: 'text', text: string }))
 
 /**
  * A binary resource carried inside an {@link embeddedResource}: a base64
@@ -80,17 +86,17 @@ export const textContent = /** @type {const} */ ({ type: 'text', text: string })
  * `BlobResource` shape — the idiomatic way to return typed binary content so a
  * `mimeType` travels alongside the bytes and clients know how to route them.
  */
-export const blobResource = /** @type {const} */ ({
+export const blobResource = open(/** @type {const} */ ({
     uri: string,
     mimeType: option(string),
     blob: string,
-})
+}))
 
 /** An `EmbeddedResource` content item wrapping a {@link blobResource}. */
-export const embeddedResource = /** @type {const} */ ({
+export const embeddedResource = open(/** @type {const} */ ({
     type: 'resource',
     resource: blobResource,
-})
+}))
 
 /**
  * A single item in a `tools/call` result's `content` array: either plain
@@ -106,34 +112,34 @@ export const contentItem = or(textContent, embeddedResource)
  * `inputSchema` is a JSON Schema object — use `toJsonSchema` to derive it from
  * an rtti schema.
  */
-export const tool = /** @type {const} */ ({
+export const tool = open(/** @type {const} */ ({
     name: string,
     description: option(string),
     inputSchema: unknown,
-})
+}))
 
 /**
  * Params for the `tools/list` request. `cursor` is an opaque pagination token
  * from a previous `ToolsListResult.nextCursor`.
  */
-export const toolsListParams = /** @type {const} */ ({
+export const toolsListParams = open(/** @type {const} */ ({
     cursor: option(string),
-})
+}))
 
-export const toolsListResult = /** @type {const} */ ({
+export const toolsListResult = open(/** @type {const} */ ({
     tools: array(tool),
     nextCursor: option(string),
-})
+}))
 
-export const toolsCallParams = /** @type {const} */ ({
+export const toolsCallParams = open(/** @type {const} */ ({
     name: string,
     arguments: option(record(unknown)),
-})
+}))
 
-export const toolsCallResult = /** @type {const} */ ({
+export const toolsCallResult = open(/** @type {const} */ ({
     content: array(contentItem),
     isError: option(boolean),
-})
+}))
 
 // ── Dispatch ───────────────────────────────────────────────────────────────────
 
@@ -144,7 +150,7 @@ export const toolsCallResult = /** @type {const} */ ({
  * arguments (typed as `Ts<T>`) to the handler. This eliminates manual validation
  * boilerplate and type assertions.
  *
- * @template {Type} T
+ * @template {Type} const T
  * @template {Operation} O
  * @param {string} name - The tool name (used in `tools/call` requests)
  * @param {string} description - Human-readable description for `tools/list`
@@ -183,6 +189,41 @@ export const okResult = text =>
 export const errorResult = text =>
     ({ ...okResult(text), isError: true })
 
+/**
+ * Answers a tool call with the outcome of one fallible operation: the `ok`
+ * value rendered by `text`, the failure rendered by `errorText` and tagged
+ * `isError`. It is the third member of the {@link okResult} / {@link errorResult}
+ * family — the one that picks between them — and it empties the error channel,
+ * because a tool-level failure is a result the client reads, never a transport
+ * error.
+ *
+ * Every tool whose body is a single `Evo`- or `Cas`-shaped call is that
+ * dispatch and nothing else, so each one is a single line:
+ *
+ * ```js
+ * ({ subject }) => toolResultStep(e.head(subject), lines, evoSummary)
+ * ```
+ *
+ * **Both renderers are required, and `errorText` is the load-bearing one** —
+ * for the reason `unwrapStep` gives for its own `summary`
+ * (`fjs/effects/module.f.mjs`): a renderer written for a particular error
+ * channel cannot accept a wider one, so a fallible call added upstream turns
+ * into a compile error at the tool that has to say what the new failure reads
+ * like, instead of silently reaching the client as whatever `String` made of
+ * it. `evoSummary` and `errorSummary` are the two in use today.
+ *
+ * @type {<O extends Operation, T, E>(
+ *     e: Effect<O, T, E>,
+ *     text: (value: T) => string,
+ *     errorText: (e: E) => string,
+ * ) => Effect<O, ToolsCallResult, never>}
+ */
+export const toolResultStep = (e, text, errorText) => resultMapStep(
+    e,
+    ([tag, value]) => ok(tag === 'error'
+        ? errorResult(errorText(value))
+        : okResult(text(value))))
+
 /**
  * Builds `McpHandlers` from a registry of tool entries.
  *
@@ -215,12 +256,6 @@ export const fromRegistry = registry => ({
 
 // ── Lifecycle / capability state machine ───────────────────────────────────────
 
-/** @type {(id: Id) => (error: RpcError) => Response} */
-const _errResponse = id => error => ({ jsonrpc, error, id })
-
-/** @type {(id: Id) => (result: Unknown) => Response} */
-const _okResponse = id => result => ({ jsonrpc, result, id })
-
 /** MCP error -32002: the client called a method before `initialize`. */
 export const notInitialized = rpcError(-32002)('Server not initialized')
 
@@ -232,6 +267,20 @@ const _noParams = option(record(unknown))
 /** @type {McpSessionState} */
 export const uninitializedState = ['uninitialized']
 
+/**
+ * Version negotiation: the revision to answer an `initialize` with. The
+ * requested one when this server speaks it, the latest one it does speak
+ * otherwise — a counter-proposal, not an error, because the
+ * [lifecycle spec](https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle#version-negotiation)
+ * leaves the decision to the client (`SHOULD disconnect`). `supported` is
+ * non-empty by type, so there is always something to propose.
+ * @type {(supported: ProtocolVersions, requested: string) => string}
+ */
+const _negotiateVersion = (supported, requested) => {
+    const [latest] = supported
+    return supported.includes(requested) ? requested : latest
+}
+
 /**
  * State-machine step for an MCP session using memory effects.
  *
@@ -242,7 +291,12 @@ export const uninitializedState = ['uninitialized']
  * - `ping` returns an empty success regardless of session state; non-object
  *   params → -32602.
  * - `initialize` is accepted only while uninitialized; a second call returns -32600.
- *   On success the state moves to `initializing`, not `initialized`.
+ *   On success the state moves to `initializing`, not `initialized`. The answered
+ *   `protocolVersion` is negotiated against `config.protocolVersions`: the client's
+ *   requested revision when the server supports it, the latest supported one
+ *   otherwise. A counter-proposal is a success frame like any other — the client,
+ *   not the server, decides whether the answer is usable — so the state moves the
+ *   same way in both cases.
  * - `notifications/initialized` (no `id`) transitions `initializing` → `initialized`;
  *   a malformed one (non-object params) is ignored and the session stays gated;
  *   other notifications are silently ignored in any state.
@@ -256,7 +310,7 @@ export const uninitializedState = ['uninitialized']
  * @returns {<O extends Operation>(handlers: McpHandlers<O>) => (stateKey: Key<McpSessionState>) => (value: Unknown) => Effect<MemOp | O, Response | null, never>}
  */
 export const mcpStep = ({
-        protocolVersion,
+        protocolVersions,
         capabilities,
         serverInfo,
     }) =>
@@ -265,7 +319,7 @@ export const mcpStep = ({
     value => {
         const [t, message] = decodeRequest(value)
         if (t === 'error') {
-            return pureOk(_errResponse(null)(invalidRequest))
+            return pureOk(errorResponseOf(null)(invalidRequest))
         }
         const { id, method, params } = message
 
@@ -302,8 +356,8 @@ export const mcpStep = ({
         if (method === 'ping') {
             const [pt] = parse(_noParams)(params)
             return pt === 'error'
-                ? pureOk(_errResponse(id)(invalidParams))
-                : pureOk(_okResponse(id)({}))
+                ? pureOk(errorResponseOf(id)(invalidParams))
+                : pureOk(successResponseOf(id)({}))
         }
 
         // `initialize` transitions uninitialized → initializing; reject if already done.
@@ -311,17 +365,17 @@ export const mcpStep = ({
             return resultStep(
                 read(stateKey),
                 r => {
-                    if (r[0] === 'error') { return pureOk(_errResponse(id)(internalError)) }
+                    if (r[0] === 'error') { return pureOk(errorResponseOf(id)(internalError)) }
                     if (r[1][0] !== 'uninitialized') {
-                        return pureOk(_errResponse(id)(invalidRequest))
+                        return pureOk(errorResponseOf(id)(invalidRequest))
                     }
-                    const [pr] = parse(initializeParams)(params)
+                    const [pr, pv] = parse(initializeParams)(params)
                     if (pr === 'error') {
-                        return pureOk(_errResponse(id)(invalidParams))
+                        return pureOk(errorResponseOf(id)(invalidParams))
                     }
                     /** @type {InitializeResult} */
                     const result = {
-                        protocolVersion,
+                        protocolVersion: _negotiateVersion(protocolVersions, pv.protocolVersion),
                         capabilities,
                         serverInfo,
                     }
@@ -333,8 +387,8 @@ export const mcpStep = ({
                     return resultStep(
                         write(stateKey, ['initializing']),
                         w => pureOk(w[0] === 'error'
-                            ? _errResponse(id)(internalError)
-                            : _okResponse(id)(result)),
+                            ? errorResponseOf(id)(internalError)
+                            : successResponseOf(id)(result)),
                     )
                 },
             )
@@ -347,39 +401,39 @@ export const mcpStep = ({
         return resultStep(
             read(stateKey),
             r => {
-                if (r[0] === 'error') { return pureOk(_errResponse(id)(internalError)) }
+                if (r[0] === 'error') { return pureOk(errorResponseOf(id)(internalError)) }
                 if (r[1][0] !== 'initialized') {
-                    return pureOk(_errResponse(id)(notInitialized))
+                    return pureOk(errorResponseOf(id)(notInitialized))
                 }
 
                 if (method === 'tools/list') {
                     if (capabilities.tools === undefined) {
-                        return pureOk(_errResponse(id)(methodNotFound))
+                        return pureOk(errorResponseOf(id)(methodNotFound))
                     }
                     // `params` may be absent — `tools/list` without a cursor.
                     const [t, pr] = parse(toolsListParams)(params === undefined ? {} : params)
                     return t === 'error'
-                        ? pureOk(_errResponse(id)(invalidParams))
+                        ? pureOk(errorResponseOf(id)(invalidParams))
                         : ioStep(
                             handlers.toolsList(pr),
-                            r => pureOk(_okResponse(id)(r)),
+                            r => pureOk(successResponseOf(id)(r)),
                         )
                 }
 
                 if (method === 'tools/call') {
                     if (capabilities.tools === undefined) {
-                        return pureOk(_errResponse(id)(methodNotFound))
+                        return pureOk(errorResponseOf(id)(methodNotFound))
                     }
                     const [t, pr] = parse(toolsCallParams)(params)
                     return t === 'error'
-                        ? pureOk(_errResponse(id)(invalidParams))
+                        ? pureOk(errorResponseOf(id)(invalidParams))
                         : ioStep(
                             handlers.toolsCall(pr),
-                            r => pureOk(_okResponse(id)(r)),
+                            r => pureOk(successResponseOf(id)(r)),
                         )
                 }
 
-                return pureOk(_errResponse(id)(methodNotFound))
+                return pureOk(errorResponseOf(id)(methodNotFound))
             },
         )
     }