functionalscript 0.43.0 → 0.44.0

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

@@ -1,89 +0,0 @@
-/**
- * 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 { number, string, or, option } from '../../types/rtti/module.f.js';
-import { validate } from '../../types/rtti/validate/module.f.js';
-import { unknown } from '../../media/json/module.f.js';
-export const jsonrpc = '2.0';
-/** Request/response identifier: a string, a number, or `null`. */
-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 = {
-    jsonrpc,
-    method: string,
-    params: option(unknown),
-    id: option(id),
-};
-/** The JSON-RPC error object. */
-export const error = {
-    code: number,
-    message: string,
-    data: option(unknown),
-};
-export const successResponse = { jsonrpc, result: unknown, id };
-export const errorResponse = { jsonrpc, error, 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`). */
-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');
-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
- */
-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;
-    }
-    const handler = handlers[method];
-    if (handler === undefined) {
-        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.js

@@ -1,68 +0,0 @@
-import { assert, assertEq } from '../../asserts/module.f.js';
-import { ok, error } from '../../types/result/module.f.js';
-import { validate } from '../../types/rtti/validate/module.f.js';
-import { error as errorSchema, decodeRequest, dispatch, rpcError, parseError, invalidRequest, methodNotFound, invalidParams, internalError, } from './module.f.js';
-const isOk = (r) => r[0] === 'ok';
-const handlers = {
-    ping: () => ok('pong'),
-    echo: params => ok(params ?? null),
-    boom: () => error(invalidParams),
-};
-const d = dispatch(handlers);
-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);
-        },
-        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/mcp/module.f.d.ts

@@ -1,239 +0,0 @@
-import { unknown, type Unknown } from '../../media/json/module.f.ts';
-import type { Ts } from '../../types/rtti/ts/module.f.ts';
-import { type Operation, type Effect } from '../../effects/module.f.ts';
-import { type Key, type MemOp } from '../../effects/memory/module.f.ts';
-import { type Response } from '../json_rpc/module.f.ts';
-import type { Type } from '../../types/rtti/module.f.ts';
-/** Name + version pair sent in `initialize` requests and responses. */
-export declare const implementation: {
-    readonly name: import("../../types/rtti/module.f.ts").String;
-    readonly version: import("../../types/rtti/module.f.ts").String;
-};
-export type Implementation = Ts<typeof implementation>;
-/** Server capabilities advertised in the `initialize` response. */
-export declare const serverCapabilities: {
-    readonly tools: import("../../types/rtti/module.f.ts").Or<readonly [{
-        readonly listChanged: import("../../types/rtti/module.f.ts").Or<readonly [import("../../types/rtti/module.f.ts").Boolean, undefined]>;
-    }, undefined]>;
-};
-export type ServerCapabilities = Ts<typeof serverCapabilities>;
-/** Params for the `initialize` request. */
-export declare const initializeParams: {
-    readonly protocolVersion: import("../../types/rtti/module.f.ts").String;
-    readonly capabilities: typeof unknown;
-    readonly clientInfo: {
-        readonly name: import("../../types/rtti/module.f.ts").String;
-        readonly version: import("../../types/rtti/module.f.ts").String;
-    };
-};
-export type InitializeParams = Ts<typeof initializeParams>;
-/** Result for the `initialize` request. */
-export declare const initializeResult: {
-    readonly protocolVersion: import("../../types/rtti/module.f.ts").String;
-    readonly capabilities: {
-        readonly tools: import("../../types/rtti/module.f.ts").Or<readonly [{
-            readonly listChanged: import("../../types/rtti/module.f.ts").Or<readonly [import("../../types/rtti/module.f.ts").Boolean, undefined]>;
-        }, undefined]>;
-    };
-    readonly serverInfo: {
-        readonly name: import("../../types/rtti/module.f.ts").String;
-        readonly version: import("../../types/rtti/module.f.ts").String;
-    };
-    readonly instructions: import("../../types/rtti/module.f.ts").Or<readonly [import("../../types/rtti/module.f.ts").String, undefined]>;
-};
-export type InitializeResult = Ts<typeof initializeResult>;
-/** Plain-text content item returned by a tool call. */
-export declare const textContent: {
-    readonly type: 'text';
-    readonly text: import("../../types/rtti/module.f.ts").String;
-};
-export type TextContent = Ts<typeof textContent>;
-/**
- * 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/module.f.ts").String;
-    readonly mimeType: import("../../types/rtti/module.f.ts").Or<readonly [import("../../types/rtti/module.f.ts").String, undefined]>;
-    readonly blob: import("../../types/rtti/module.f.ts").String;
-};
-export type BlobResource = Ts<typeof blobResource>;
-/** An `EmbeddedResource` content item wrapping a {@link blobResource}. */
-export declare const embeddedResource: {
-    readonly type: 'resource';
-    readonly resource: {
-        readonly uri: import("../../types/rtti/module.f.ts").String;
-        readonly mimeType: import("../../types/rtti/module.f.ts").Or<readonly [import("../../types/rtti/module.f.ts").String, undefined]>;
-        readonly blob: import("../../types/rtti/module.f.ts").String;
-    };
-};
-export type EmbeddedResource = Ts<typeof embeddedResource>;
-/**
- * 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/module.f.ts").Or<[{
-    readonly type: 'text';
-    readonly text: import("../../types/rtti/module.f.ts").String;
-}, {
-    readonly type: 'resource';
-    readonly resource: {
-        readonly uri: import("../../types/rtti/module.f.ts").String;
-        readonly mimeType: import("../../types/rtti/module.f.ts").Or<readonly [import("../../types/rtti/module.f.ts").String, undefined]>;
-        readonly blob: import("../../types/rtti/module.f.ts").String;
-    };
-}]>;
-export type ContentItem = Ts<typeof contentItem>;
-/**
- * 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/module.f.ts").String;
-    readonly description: import("../../types/rtti/module.f.ts").Or<readonly [import("../../types/rtti/module.f.ts").String, undefined]>;
-    readonly inputSchema: typeof unknown;
-};
-export type Tool = Ts<typeof tool>;
-/**
- * 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/module.f.ts").Or<readonly [import("../../types/rtti/module.f.ts").String, undefined]>;
-};
-export type ToolsListParams = Ts<typeof toolsListParams>;
-export declare const toolsListResult: {
-    readonly tools: import("../../types/rtti/module.f.ts").Type1<"array", {
-        readonly name: import("../../types/rtti/module.f.ts").String;
-        readonly description: import("../../types/rtti/module.f.ts").Or<readonly [import("../../types/rtti/module.f.ts").String, undefined]>;
-        readonly inputSchema: typeof unknown;
-    }>;
-    readonly nextCursor: import("../../types/rtti/module.f.ts").Or<readonly [import("../../types/rtti/module.f.ts").String, undefined]>;
-};
-export type ToolsListResult = Ts<typeof toolsListResult>;
-export declare const toolsCallParams: {
-    readonly name: import("../../types/rtti/module.f.ts").String;
-    readonly arguments: import("../../types/rtti/module.f.ts").Or<readonly [import("../../types/rtti/module.f.ts").Type1<"record", typeof unknown>, undefined]>;
-};
-export type ToolsCallParams = Ts<typeof toolsCallParams>;
-export declare const toolsCallResult: {
-    readonly content: import("../../types/rtti/module.f.ts").Type1<"array", import("../../types/rtti/module.f.ts").Or<[{
-        readonly type: 'text';
-        readonly text: import("../../types/rtti/module.f.ts").String;
-    }, {
-        readonly type: 'resource';
-        readonly resource: {
-            readonly uri: import("../../types/rtti/module.f.ts").String;
-            readonly mimeType: import("../../types/rtti/module.f.ts").Or<readonly [import("../../types/rtti/module.f.ts").String, undefined]>;
-            readonly blob: import("../../types/rtti/module.f.ts").String;
-        };
-    }]>>;
-    readonly isError: import("../../types/rtti/module.f.ts").Or<readonly [import("../../types/rtti/module.f.ts").Boolean, undefined]>;
-};
-export type ToolsCallResult = Ts<typeof toolsCallResult>;
-/** Per-method handlers for a hello-world MCP tool server. */
-export type McpHandlers<O extends Operation> = {
-    readonly toolsList: (params: ToolsListParams) => Effect<O, ToolsListResult>;
-    readonly toolsCall: (params: ToolsCallParams) => Effect<O, ToolsCallResult>;
-};
-/**
- * A single declarative tool entry combining metadata, input schema, and type-safe handler.
- *
- * The handler receives pre-validated arguments of type `Ts<inputRtti>`, eliminating the need
- * for manual validation or type casting. All validation is encapsulated in the entry.
- */
-export type ToolEntry<O extends Operation> = {
-    readonly name: string;
-    readonly description: string;
-    readonly inputRtti: Type;
-    readonly handle: (args: Unknown) => Effect<O, ToolsCallResult>;
-};
-/**
- * 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.
- *
- * @param name - The tool name (used in `tools/call` requests)
- * @param description - Human-readable description for `tools/list`
- * @param inputRtti - Runtime type info for input validation
- * @param handle - Handler receiving validated arguments of type `Ts<inputRtti>`
- * @returns 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 text - The text to return to the client
- * @returns 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 text - The error message to return to the client
- * @returns 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.
- *
- * @param registry - Array of tool entries
- * @returns Complete `McpHandlers` ready for use with `mcpStep`
- */
-export declare const fromRegistry: <O extends Operation>(registry: readonly ToolEntry<O>[]) => McpHandlers<O>;
-/** Top-level handler: maps a raw JSON value to a JSON-RPC response (or `null` for notifications). */
-export type Handle<O extends Operation> = (value: Unknown) => Effect<O, Response | null>;
-/** MCP error -32002: the client called a method before `initialize`. */
-export declare const notInitialized: import("../../types/rtti/ts/module.f.ts").StructTs<{
-    readonly code: import("../../types/rtti/module.f.ts").Number;
-    readonly message: import("../../types/rtti/module.f.ts").String;
-    readonly data: import("../../types/rtti/module.f.ts").Or<readonly [typeof unknown, undefined]>;
-}>;
-/** State carried before the peer sends `initialize`. */
-export type Uninitialized = readonly ['uninitialized'];
-/** State after `initialize` response was sent but before `notifications/initialized` arrives. */
-export type Initializing = readonly ['initializing'];
-/** State carried after a successful `initialize` exchange. */
-export type InitializedState = true;
-/** The three phases of an MCP session. */
-export type McpSessionState = Uninitialized | Initializing | readonly ['initialized', InitializedState];
-/** Initial session state — always start here. */
-export declare const uninitializedState: McpSessionState;
-/** Static configuration supplied by the server implementer. */
-export type McpConfig = {
-    readonly serverInfo: Implementation;
-    readonly capabilities: ServerCapabilities;
-    readonly protocolVersion: string;
-};
-/**
- * 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.
- */
-export declare const mcpStep: ({ protocolVersion, capabilities, serverInfo, }: McpConfig) => <O extends Operation>(handlers: McpHandlers<O>) => (stateKey: Key<McpSessionState>) => (value: Unknown) => Effect<MemOp | O, Response | null>;

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

@@ -1,272 +0,0 @@
-/**
- * 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.ts`.
- *
- * @module
- */
-import { boolean, string, option, array, record, or } from '../../types/rtti/module.f.js';
-import { unknown } from '../../media/json/module.f.js';
-import { pure, step } from '../../effects/module.f.js';
-import { read, write } from '../../effects/memory/module.f.js';
-import { decodeRequest, rpcError, invalidRequest, invalidParams, methodNotFound, jsonrpc, } from '../json_rpc/module.f.js';
-import { validate } from '../../types/rtti/validate/module.f.js';
-import { toJsonSchema } from '../../media/json/schema/module.f.js';
-// ── Shared ─────────────────────────────────────────────────────────────────────
-/** Name + version pair sent in `initialize` requests and responses. */
-export const implementation = {
-    name: string,
-    version: string,
-};
-// ── Capabilities ───────────────────────────────────────────────────────────────
-const toolsCapability = { listChanged: option(boolean) };
-/** Server capabilities advertised in the `initialize` response. */
-export const serverCapabilities = {
-    tools: option(toolsCapability),
-};
-// ── Lifecycle ──────────────────────────────────────────────────────────────────
-/** Params for the `initialize` request. */
-export const initializeParams = {
-    protocolVersion: string,
-    capabilities: unknown,
-    clientInfo: implementation,
-};
-/** Result for the `initialize` request. */
-export const initializeResult = {
-    protocolVersion: string,
-    capabilities: serverCapabilities,
-    serverInfo: implementation,
-    instructions: option(string),
-};
-// ── Content ────────────────────────────────────────────────────────────────────
-/** Plain-text content item returned by a tool call. */
-export const textContent = { type: 'text', text: 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 const blobResource = {
-    uri: string,
-    mimeType: option(string),
-    blob: string,
-};
-/** An `EmbeddedResource` content item wrapping a {@link blobResource}. */
-export const embeddedResource = {
-    type: 'resource',
-    resource: blobResource,
-};
-/**
- * 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 const contentItem = or(textContent, embeddedResource);
-// ── Tools ──────────────────────────────────────────────────────────────────────
-/**
- * A tool descriptor returned by `tools/list`.
- * `inputSchema` is a JSON Schema object — use `toJsonSchema` to derive it from
- * an rtti schema.
- */
-export const tool = {
-    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 = {
-    cursor: option(string),
-};
-export const toolsListResult = {
-    tools: array(tool),
-    nextCursor: option(string),
-};
-export const toolsCallParams = {
-    name: string,
-    arguments: option(record(unknown)),
-};
-export const toolsCallResult = {
-    content: array(contentItem),
-    isError: option(boolean),
-};
-/**
- * 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.
- *
- * @param name - The tool name (used in `tools/call` requests)
- * @param description - Human-readable description for `tools/list`
- * @param inputRtti - Runtime type info for input validation
- * @param handle - Handler receiving validated arguments of type `Ts<inputRtti>`
- * @returns A `ToolEntry` ready to be added to a registry
- */
-export const toolEntry = (name, description, inputRtti, handle) => ({
-    name,
-    description,
-    inputRtti,
-    handle: (a) => {
-        const [t, r] = validate(inputRtti)(a);
-        return t === 'error'
-            ? pure(errorResult(`invalid arguments: ${r.message}`))
-            : handle(r);
-    }
-});
-/**
- * Helper to create a successful single-text-block tool result.
- *
- * @param text - The text to return to the client
- * @returns A `ToolsCallResult` with the text content
- */
-export const okResult = (text) => ({ content: [{ type: 'text', text }] });
-/**
- * Helper to create a tool-level error result with plain text explanation.
- *
- * @param text - The error message to return to the client
- * @returns A `ToolsCallResult` with `isError: true` and the text explanation
- */
-export const errorResult = (text) => ({ ...okResult(text), isError: true });
-/**
- * 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.
- *
- * @param registry - Array of tool entries
- * @returns Complete `McpHandlers` ready for use with `mcpStep`
- */
-export const fromRegistry = (registry) => ({
-    toolsList: () => {
-        const tools = registry.map(entry => ({
-            name: entry.name,
-            description: entry.description,
-            inputSchema: toJsonSchema(entry.inputRtti),
-        }));
-        return pure({ tools });
-    },
-    toolsCall: ({ name, arguments: args }) => {
-        const entry = registry.find(e => e.name === name);
-        return entry === undefined
-            ? pure(errorResult(`unknown tool: ${name}`))
-            : entry.handle(args === undefined ? {} : args);
-    },
-});
-// ── Lifecycle / capability state machine ───────────────────────────────────────
-const _errResponse = (id) => (error) => ({ jsonrpc, error, id });
-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');
-// Params for methods that take no arguments (`ping`, `notifications/initialized`):
-// absent, or an object (which may carry `_meta`).
-const _noParams = option(record(unknown));
-/** Initial session state — always start here. */
-export const uninitializedState = ['uninitialized'];
-/**
- * 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.
- */
-export const mcpStep = ({ protocolVersion, capabilities, serverInfo, }) => (handlers) => (stateKey) => (value) => {
-    const [t, message] = decodeRequest(value);
-    if (t === 'error') {
-        return pure(_errResponse(null)(invalidRequest));
-    }
-    const { id, method, params } = message;
-    // Notifications (no `id`) never receive a response.
-    // `notifications/initialized` transitions the session from initializing → initialized.
-    if (id === undefined) {
-        if (method === 'notifications/initialized') {
-            const [pt] = validate(_noParams)(params);
-            if (pt === 'error') {
-                // Malformed handshake — ignore it; the session stays gated.
-                return pure(null);
-            }
-            return step(read(stateKey), ([t]) => t === 'initializing'
-                ? step(write(stateKey, ['initialized', true]), () => pure(null))
-                : pure(null));
-        }
-        return pure(null);
-    }
-    // `ping` is always valid regardless of session state, but its params
-    // (if present) must be an object.
-    if (method === 'ping') {
-        const [pt] = validate(_noParams)(params);
-        return pt === 'error'
-            ? pure(_errResponse(id)(invalidParams))
-            : pure(_okResponse(id)({}));
-    }
-    // `initialize` transitions uninitialized → initializing; reject if already done.
-    if (method === 'initialize') {
-        return step(read(stateKey), ([t]) => {
-            if (t !== 'uninitialized') {
-                return pure(_errResponse(id)(invalidRequest));
-            }
-            const [pr] = validate(initializeParams)(params);
-            if (pr === 'error') {
-                return pure(_errResponse(id)(invalidParams));
-            }
-            const result = {
-                protocolVersion,
-                capabilities,
-                serverInfo,
-            };
-            return step(write(stateKey, ['initializing']), () => pure(_okResponse(id)(result)));
-        });
-    }
-    // All other methods require fully initialized state — read it first.
-    return step(read(stateKey), ([t]) => {
-        if (t !== 'initialized') {
-            return pure(_errResponse(id)(notInitialized));
-        }
-        if (method === 'tools/list') {
-            if (capabilities.tools === undefined) {
-                return pure(_errResponse(id)(methodNotFound));
-            }
-            // `params` may be absent — `tools/list` without a cursor.
-            const [t, pr] = validate(toolsListParams)(params === undefined ? {} : params);
-            return t === 'error'
-                ? pure(_errResponse(id)(invalidParams))
-                : step(handlers.toolsList(pr), r => pure(_okResponse(id)(r)));
-        }
-        if (method === 'tools/call') {
-            if (capabilities.tools === undefined) {
-                return pure(_errResponse(id)(methodNotFound));
-            }
-            const [t, pr] = validate(toolsCallParams)(params);
-            return t === 'error'
-                ? pure(_errResponse(id)(invalidParams))
-                : step(handlers.toolsCall(pr), r => pure(_okResponse(id)(r)));
-        }
-        return pure(_errResponse(id)(methodNotFound));
-    });
-};