functionalscript 0.43.1 → 0.45.0

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

@@ -0,0 +1,115 @@
+/**
+ * JSON-RPC 2.0 envelopes and a pure dispatcher.
+ *
+ * The envelopes are rtti schemas, so one declaration yields both a runtime
+ * decoder (`validate(request)`) and the static type (`Ts<typeof request>`) — no
+ * drift between them. The dispatcher is pure: it maps an already-parsed request
+ * value to a response value (or `null` for a notification) and performs no I/O.
+ *
+ * Out of scope here (follow-ups): transports — stdio / HTTP framing — over
+ * `fjs/effects/node`, and concrete method sets such as MCP (i665-mcp), which layer
+ * on top of `dispatch`.
+ *
+ * https://www.jsonrpc.org/specification
+ *
+ * @module
+ *
+ * @import { Unknown } from '../../media/json/types.ts'
+ * @import { Id, RpcError, Handlers, Response } from './types.ts'
+ */
+
+import { at } from '../../types/object/module.f.mjs'
+import { number, string, or, option } from '../../types/rtti/module.f.mjs'
+import { validate } from '../../types/rtti/validate/module.f.mjs'
+import { unknown } from '../../media/json/rtti/module.f.mjs'
+
+export const jsonrpc = /** @type {const} */ ('2.0')
+
+/** Request/response identifier: a string, a number, or `null`. */
+export const _id = or(string, number, null)
+
+/**
+ * A request or notification envelope. `id` present → request (a response is
+ * expected); `id` absent → notification (no response). `params` is optional.
+ *
+ * https://www.jsonrpc.org/specification#request_object
+ */
+export const request = /** @type {const} */ ({
+    jsonrpc,
+    method: string,
+    params: option(unknown),
+    id: option(_id),
+})
+
+/** The JSON-RPC error object. */
+export const error = /** @type {const} */ ({
+    code: number,
+    message: string,
+    data: option(unknown),
+})
+
+export const successResponse = /** @type {const} */ ({ jsonrpc, result: unknown, id: _id })
+export const errorResponse = /** @type {const} */ ({ jsonrpc, error, id: _id })
+
+/**
+ * A response envelope: either a success (`result`) or an error (`error`).
+ * Derived from the rtti schema via `Ts<>` — the same declaration is the
+ * runtime decoder and the static type, with no drift. rtti structs are open
+ * (extra keys allowed), so "result XOR error" is not enforced at runtime; in
+ * practice the dispatcher only ever constructs one or the other.
+ *
+ * https://www.jsonrpc.org/specification#response_object
+ */
+export const response = or(successResponse, errorResponse)
+
+/** Decodes an untrusted value as a JSON-RPC request / notification. */
+export const decodeRequest = validate(request)
+
+/**
+ * Builds an `RpcError` with the given `code` and `message` (no `data`).
+ * @type {(code: number) => (message: string) => RpcError}
+ */
+export const rpcError = code => message => ({ code, message })
+
+// The standard JSON-RPC 2.0 errors.
+export const parseError = rpcError(-32700)('Parse error')
+export const invalidRequest = rpcError(-32600)('Invalid Request')
+export const methodNotFound = rpcError(-32601)('Method not found')
+export const invalidParams = rpcError(-32602)('Invalid params')
+export const internalError = rpcError(-32603)('Internal error')
+
+/** @type {(id: Id) => (error: RpcError) => Response} */
+const errorResponseOf = id => error => ({ jsonrpc, error, id })
+
+/**
+ * Dispatches an already-parsed JSON-RPC value against `handlers`.
+ *
+ * - invalid envelope → `Invalid Request` (`-32600`) with `id: null`
+ * - notification (no `id`) → `null` (never a response)
+ * - unknown method → `Method not found` (`-32601`)
+ * - otherwise the handler's `ok` / `error` result becomes a success / error response
+ *
+ * @param {Handlers} handlers
+ * @returns {(value: Unknown) => Response | null}
+ */
+export const dispatch = handlers => value => {
+    const [t, message] = decodeRequest(value)
+    if (t === 'error') {
+        return errorResponseOf(null)(invalidRequest)
+    }
+    const { id, method, params } = message
+    if (id === undefined) {
+        return null
+    }
+    // `at`, not `handlers[method]`: `method` is untrusted wire data, and a
+    // bracket lookup on a plain object resolves inherited `Object.prototype`
+    // names (`constructor`, `toString`, …) to callables.
+    const handler = at(method)(handlers)
+    if (handler === null) {
+        return errorResponseOf(id)(methodNotFound)
+    }
+    const [t2, result] = handler(params)
+    return t2 === 'ok'
+        ? { jsonrpc, result, id }
+        : errorResponseOf(id)(result)
+}

package/fjs/protocol/json_rpc/proof.f.d.mts

@@ -0,0 +1,41 @@
+/**
+ * @import { Handlers } from './types.ts'
+ */
+export declare const proof: {
+    schema: {
+        request: {
+            full: () => void;
+            notification: () => void;
+            nullId: () => void;
+            stringId: () => void;
+            badVersion: () => void;
+            missingMethod: () => void;
+            badId: () => void;
+            notObject: () => void;
+        };
+        error: {
+            ok: () => void;
+            withData: () => void;
+            missingMessage: () => void;
+        };
+    };
+    errors: {
+        factory: () => void;
+        parseError: () => void;
+        invalidRequest: () => void;
+        methodNotFound: () => void;
+        invalidParams: () => void;
+        internalError: () => void;
+    };
+    dispatch: {
+        success: () => void;
+        paramsPassed: () => void;
+        handlerError: () => void;
+        methodNotFound: () => void;
+        inheritedToString: () => void;
+        inheritedConstructor: () => void;
+        ownPrototypeName: () => void;
+        invalidRequest: () => void;
+        notification: () => void;
+    };
+};

package/fjs/protocol/json_rpc/proof.f.mjs

@@ -0,0 +1,105 @@
+/**
+ * @import { Handlers } from './types.ts'
+ */
+
+import { assert, assertEq } from '../../asserts/module.f.mjs'
+import { ok, error } from '../../types/result/module.f.mjs'
+import { validate } from '../../types/rtti/validate/module.f.mjs'
+import {
+    error as errorSchema,
+    decodeRequest,
+    dispatch,
+    rpcError,
+    parseError,
+    invalidRequest,
+    methodNotFound,
+    invalidParams,
+    internalError,
+} from './module.f.mjs'
+
+/** @type {(r: readonly [string, unknown]) => boolean} */
+const isOk = r => r[0] === 'ok'
+
+/** @type {Handlers} */
+const handlers = {
+    ping: () => ok('pong'),
+    echo: params => ok(params ?? null),
+    boom: () => error(invalidParams),
+}
+const d = dispatch(handlers)
+
+/** A handler table that does own the `Object.prototype` name `toString`. */
+const dOwnPrototypeName = dispatch({ toString: () => ok('own') })
+
+export const proof = {
+    schema: {
+        request: {
+            full: () => assert(isOk(decodeRequest({ jsonrpc: '2.0', method: 'm', params: [1], id: 1 }))),
+            notification: () => assert(isOk(decodeRequest({ jsonrpc: '2.0', method: 'm' }))),
+            nullId: () => assert(isOk(decodeRequest({ jsonrpc: '2.0', method: 'm', id: null }))),
+            stringId: () => assert(isOk(decodeRequest({ jsonrpc: '2.0', method: 'm', id: 'abc' }))),
+            badVersion: () => assert(!isOk(decodeRequest({ jsonrpc: '1.0', method: 'm', id: 1 }))),
+            missingMethod: () => assert(!isOk(decodeRequest({ jsonrpc: '2.0', id: 1 }))),
+            badId: () => assert(!isOk(decodeRequest({ jsonrpc: '2.0', method: 'm', id: true }))),
+            notObject: () => assert(!isOk(decodeRequest(42))),
+        },
+        error: {
+            ok: () => assert(isOk(validate(errorSchema)({ code: -1, message: 'x' }))),
+            withData: () => assert(isOk(validate(errorSchema)({ code: -1, message: 'x', data: [1, 2] }))),
+            missingMessage: () => assert(!isOk(validate(errorSchema)({ code: -1 }))),
+        },
+    },
+    errors: {
+        factory: () => {
+            const e = rpcError(-7)('boom')
+            assertEq(e.code, -7)
+            assertEq(e.message, 'boom')
+        },
+        parseError: () => { assertEq(parseError.code, -32700); assertEq(parseError.message, 'Parse error') },
+        invalidRequest: () => { assertEq(invalidRequest.code, -32600); assertEq(invalidRequest.message, 'Invalid Request') },
+        methodNotFound: () => { assertEq(methodNotFound.code, -32601); assertEq(methodNotFound.message, 'Method not found') },
+        invalidParams: () => { assertEq(invalidParams.code, -32602); assertEq(invalidParams.message, 'Invalid params') },
+        internalError: () => { assertEq(internalError.code, -32603); assertEq(internalError.message, 'Internal error') },
+    },
+    dispatch: {
+        success: () => {
+            const r = d({ jsonrpc: '2.0', method: 'ping', id: 1 })
+            assert(r !== null && 'result' in r && r.result === 'pong' && r.id === 1)
+        },
+        paramsPassed: () => {
+            const r = d({ jsonrpc: '2.0', method: 'echo', params: 'hi', id: 2 })
+            assert(r !== null && 'result' in r && r.result === 'hi')
+        },
+        handlerError: () => {
+            const r = d({ jsonrpc: '2.0', method: 'boom', id: 3 })
+            assert(r !== null && 'error' in r && r.error.code === -32602 && r.id === 3)
+        },
+        methodNotFound: () => {
+            const r = d({ jsonrpc: '2.0', method: 'nope', id: 4 })
+            assert(r !== null && 'error' in r && r.error.code === -32601)
+        },
+        // `method` is untrusted wire data: an inherited `Object.prototype`
+        // name must not resolve to a callable.
+        inheritedToString: () => {
+            const r = d({ jsonrpc: '2.0', method: 'toString', id: 4 })
+            assert(r !== null && 'error' in r && r.error.code === -32601)
+        },
+        inheritedConstructor: () => {
+            const r = d({ jsonrpc: '2.0', method: 'constructor', id: 4 })
+            assert(r !== null && 'error' in r && r.error.code === -32601)
+        },
+        // ... while an *own* property of that name is an ordinary method.
+        ownPrototypeName: () => {
+            const r = dOwnPrototypeName({ jsonrpc: '2.0', method: 'toString', id: 4 })
+            assert(r !== null && 'result' in r && r.result === 'own')
+        },
+        invalidRequest: () => {
+            const r = d({ jsonrpc: '1.0', method: 'ping', id: 5 })
+            assert(r !== null && 'error' in r && r.error.code === -32600 && r.id === null)
+        },
+        notification: () => {
+            const r = d({ jsonrpc: '2.0', method: 'ping' })
+            assertEq(r, null)
+        },
+    },
+}

package/fjs/protocol/json_rpc/types.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Type-level API for `fjs/protocol/json_rpc/module.f.mjs`: `Id`, `Request`,
+ * `RpcError`, and `Response`, derived from the module's own rtti schemas,
+ * plus the `Handler` / `Handlers` shapes a dispatcher is built from.
+ *
+ * @module
+ */
+import type { Unknown } from '../../media/json/types.ts';
+import type { Result } from '../../types/result/types.ts';
+import type { _id, request, error as errorSchema, response } from './module.f.mjs';
+import type { Ts } from '../../types/rtti/ts/types.ts';
+export type Id = Ts<typeof _id>;
+export type Request = Ts<typeof request>;
+export type RpcError = Ts<typeof errorSchema>;
+/**
+ * A response envelope: either a success (`result`) or an error (`error`).
+ * Derived from the rtti schema via `Ts<>` — the same declaration is the
+ * runtime decoder and the static type, with no drift. rtti structs are open
+ * (extra keys allowed), so "result XOR error" is not enforced at runtime; in
+ * practice the dispatcher only ever constructs one or the other.
+ *
+ * https://www.jsonrpc.org/specification#response_object
+ */
+export type Response = Ts<typeof response>;
+/** A method implementation: maps `params` to a result or an `RpcError`. */
+export type Handler = (params: Unknown | undefined) => Result<Unknown, RpcError>;
+/** A `method` name → `Handler` map. */
+export type Handlers = {
+    readonly [method: string]: Handler;
+};

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

@@ -0,0 +1,227 @@
+/**
+ * MCP (Model Context Protocol) message schemas — minimal subset for a
+ * hello-world tool server.
+ *
+ * Covers the three exchanges a minimal server must handle:
+ * - `initialize` / `notifications/initialized` lifecycle
+ * - `tools/list` — advertise available tools
+ * - `tools/call` — invoke a tool and return text content
+ *
+ * Each schema is both a runtime decoder (`validate(schema)`) and a static
+ * TypeScript type (`Ts<typeof schema>`). Transport framing (stdio) and the
+ * JSON-RPC dispatcher are in `fjs/protocol/json_rpc/module.f.mjs`.
+ *
+ * @module
+ *
+ * @import { Unknown } from '../../media/json/types.ts'
+ * @import { Ts } from '../../types/rtti/ts/types.ts'
+ * @import { Operation, Effect } from '../../effects/types.ts'
+ * @import { Key, MemOp } from '../../effects/memory/types.ts'
+ * @import { Response, Id, RpcError } from '../json_rpc/types.ts'
+ * @import { Type } from '../../types/rtti/types.ts'
+ * @import {
+ *   Implementation, ServerCapabilities, InitializeResult, Tool,
+ *   ToolsListParams, ToolsCallResult, McpHandlers, ToolEntry,
+ *   InitializedState, McpSessionState, McpConfig,
+ * } from './types.ts'
+ */
+import type { Unknown } from '../../media/json/types.ts';
+import type { Ts } from '../../types/rtti/ts/types.ts';
+import type { Operation, Effect } from '../../effects/types.ts';
+import type { Key, MemOp } from '../../effects/memory/types.ts';
+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: {
+    readonly name: import("../../types/rtti/types.ts")._Type0<"string">;
+    readonly version: import("../../types/rtti/types.ts")._Type0<"string">;
+};
+/** Server capabilities advertised in the `initialize` response. */
+export declare const serverCapabilities: {
+    readonly tools: import("../../types/rtti/types.ts").Or<readonly [{
+        readonly listChanged: import("../../types/rtti/types.ts").Or<readonly [import("../../types/rtti/types.ts")._Type0<"boolean">, undefined]>;
+    }, undefined]>;
+};
+/** Params for the `initialize` request. */
+export declare const initializeParams: {
+    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 name: import("../../types/rtti/types.ts")._Type0<"string">;
+        readonly version: import("../../types/rtti/types.ts")._Type0<"string">;
+    };
+};
+/** Result for the `initialize` request. */
+export declare const initializeResult: {
+    readonly protocolVersion: import("../../types/rtti/types.ts")._Type0<"string">;
+    readonly capabilities: {
+        readonly tools: import("../../types/rtti/types.ts").Or<readonly [{
+            readonly listChanged: import("../../types/rtti/types.ts").Or<readonly [import("../../types/rtti/types.ts")._Type0<"boolean">, undefined]>;
+        }, undefined]>;
+    };
+    readonly serverInfo: {
+        readonly name: import("../../types/rtti/types.ts")._Type0<"string">;
+        readonly version: import("../../types/rtti/types.ts")._Type0<"string">;
+    };
+    readonly instructions: import("../../types/rtti/types.ts").Or<readonly [import("../../types/rtti/types.ts")._Type0<"string">, undefined]>;
+};
+/** Plain-text content item returned by a tool call. */
+export declare const textContent: {
+    readonly type: 'text';
+    readonly text: import("../../types/rtti/types.ts")._Type0<"string">;
+};
+/**
+ * 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: {
+    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">;
+};
+/** An `EmbeddedResource` content item wrapping a {@link blobResource}. */
+export declare const embeddedResource: {
+    readonly type: 'resource';
+    readonly resource: {
+        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">;
+    };
+};
+/**
+ * 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<[{
+    readonly type: 'text';
+    readonly text: import("../../types/rtti/types.ts")._Type0<"string">;
+}, {
+    readonly type: 'resource';
+    readonly resource: {
+        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">;
+    };
+}]>;
+/**
+ * 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: {
+    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];
+};
+/**
+ * Params for the `tools/list` request. `cursor` is an opaque pagination token
+ * from a previous `ToolsListResult.nextCursor`.
+ */
+export declare const toolsListParams: {
+    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", {
+        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];
+    }>;
+    readonly nextCursor: import("../../types/rtti/types.ts").Or<readonly [import("../../types/rtti/types.ts")._Type0<"string">, undefined]>;
+};
+export declare const toolsCallParams: {
+    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<[{
+        readonly type: 'text';
+        readonly text: import("../../types/rtti/types.ts")._Type0<"string">;
+    }, {
+        readonly type: 'resource';
+        readonly resource: {
+            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">;
+        };
+    }]>>;
+    readonly isError: import("../../types/rtti/types.ts").Or<readonly [import("../../types/rtti/types.ts")._Type0<"boolean">, undefined]>;
+};
+/**
+ * Creates a type-safe tool entry that binds an RTTI schema with a handler.
+ *
+ * The builder validates arguments at runtime using the RTTI and passes pre-validated
+ * arguments (typed as `Ts<T>`) to the handler. This eliminates manual validation
+ * boilerplate and type assertions.
+ *
+ * @template {Type} T
+ * @template {Operation} O
+ * @param {string} name - The tool name (used in `tools/call` requests)
+ * @param {string} description - Human-readable description for `tools/list`
+ * @param {T} inputRtti - Runtime type info for input validation
+ * @param {(args: Ts<T>) => Effect<O, ToolsCallResult>} 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>) => ToolEntry<O>;
+/**
+ * Helper to create a successful single-text-block tool result.
+ *
+ * @param {string} text - The text to return to the client
+ * @returns {ToolsCallResult} A `ToolsCallResult` with the text content
+ */
+export declare const okResult: (text: string) => ToolsCallResult;
+/**
+ * Helper to create a tool-level error result with plain text explanation.
+ *
+ * @param {string} text - The error message to return to the client
+ * @returns {ToolsCallResult} A `ToolsCallResult` with `isError: true` and the text explanation
+ */
+export declare const errorResult: (text: string) => ToolsCallResult;
+/**
+ * Builds `McpHandlers` from a registry of tool entries.
+ *
+ * This factory generates `toolsList` and `toolsCall` handlers that work with a
+ * declarative registry, eliminating boilerplate. The `toolsList` handler converts
+ * entries into MCP `Tool` descriptors, and `toolsCall` dispatches by name and
+ * delegates to the appropriate handler.
+ *
+ * @template {Operation} O
+ * @param {readonly ToolEntry<O>[]} registry - Array of tool entries
+ * @returns {McpHandlers<O>} Complete `McpHandlers` ready for use with `mcpStep`
+ */
+export declare const fromRegistry: <O extends Operation>(registry: readonly ToolEntry<O>[]) => McpHandlers<O>;
+/** MCP error -32002: the client called a method before `initialize`. */
+export declare const notInitialized: import("../../types/rtti/ts/types.ts").StructTs<{
+    readonly code: import("../../types/rtti/types.ts")._Type0<"number">;
+    readonly message: import("../../types/rtti/types.ts")._Type0<"string">;
+    readonly data: import("../../types/rtti/types.ts").Or<readonly [() => 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]>;
+}>;
+/** Initial session state — always start here. */
+export declare const uninitializedState: McpSessionState;
+/**
+ * State-machine step for an MCP session using memory effects.
+ *
+ * Given configuration, handlers, and a memory key holding the session state,
+ * returns a function `(value) => Effect<MemOp | O, Response | null>`.
+ *
+ * Rules:
+ * - `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`.
+ * - `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.
+ * - Any other method before `notifications/initialized` → error -32002 (not initialized).
+ * - Methods gated by a capability (e.g. `tools/list`) → -32601 when the capability
+ *   is absent.
+ * - `tools/list` params (an optional pagination `cursor`) are validated and passed
+ *   to the handler; invalid params → -32602.
+ *
+ * @param {McpConfig} config
+ * @returns {<O extends Operation>(handlers: McpHandlers<O>) => (stateKey: Key<McpSessionState>) => (value: Unknown) => Effect<MemOp | O, Response | null>}
+ */
+export declare const mcpStep: ({ protocolVersion, capabilities, serverInfo, }: McpConfig) => <O extends Operation>(handlers: McpHandlers<O>) => (stateKey: Key<McpSessionState>) => (value: Unknown) => Effect<MemOp | O, Response | null>;