functionalscript 0.39.0 → 0.41.0

package/fjs/mcp/module.f.js

@@ -1,272 +1,69 @@
 /**
- * MCP (Model Context Protocol) message schemas — minimal subset for a
- * hello-world tool server.
+ * The FJS MCP server: the composition root the `fjs mcp` / `m` CLI command
+ * runs. Session configuration (`McpConfig`), the top-level entry point
+ * (`casMcpServer`, wiring `mcpStep` + `stdioTransport` from
+ * `fjs/protocol/mcp/`), and the composed tool registry — nothing CAS- or
+ * Evo-specific lives here, it only knows about tool *registries*, not what is
+ * in them, so a future non-CAS tool set can land as a new sibling of
+ * `fjs/mcp/cas/` and `fjs/mcp/evo/` without touching either of them.
  *
- * 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
+ * ## Tools
  *
- * 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/media/json/rpc/module.f.ts`.
+ * | Tool           | args                                          | action           | result                              |
+ * |----------------|------------------------------------------------|------------------|--------------------------------------|
+ * | `cas_add`      | `{ content, type? }`                          | `c.write(...)`   | hash (cBase32)                      |
+ * | `cas_get`      | `{ hash, content?: boolean }`                 | `c.read(key)`    | JSON `{length,mimeType,type[,uri][,text\|blob]}` |
+ * | `cas_list`     | `{}`                                          | `c.list()`       | hashes, one per line                |
+ * | `evo_list`     | `{ archived? }`                               | `e.list(...)`    | subjects, as a JSON array of strings |
+ * | `evo_head`     | `{ subject }`                                 | `e.head(...)`    | head hashes, one per line           |
+ * | `evo_revision` | `{ hash }`                                    | `e.revision(...)`| the revision, as JSON               |
+ * | `evo_add`      | `{ parents, snapshot?, subject?, archived? }` | `e.add(...)`     | hash (cBase32)                      |
+ *
+ * `cas_add`/`cas_get`/`cas_list` are `fjs/mcp/cas` — see that module for tool
+ * documentation (input encoding, output shape, error convention). `evo_*` is
+ * `fjs/mcp/evo`. Both tool sets run in one process, sharing one `~/.cas/`
+ * store and one in-memory Evo cache scanned once at startup (`initEvo`).
  *
  * @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 '../media/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 ──────────────────────────────────────────────────────────────────────
+import { step } from '../effects/module.f.js';
+import { create } from '../effects/memory/module.f.js';
+import {} from '../effects/node/module.f.js';
+import { stdioTransport } from '../protocol/mcp/stdio/module.f.js';
+import { mcpStep, uninitializedState, fromRegistry, } from '../protocol/mcp/module.f.js';
+import { fileCas } from '../cas/module.f.js';
+import { initEvo, evo } from '../cas/evo/module.f.js';
+import { sha256 } from '../crypto/sha2/module.f.js';
+import { casToolRegistry } from './cas/module.f.js';
+import { evoToolRegistry } from './evo/module.f.js';
+// ── Handlers ────────────────────────────────────────────────────────────────────
 /**
- * A tool descriptor returned by `tools/list`.
- * `inputSchema` is a JSON Schema object — use `toJsonSchema` to derive it from
- * an rtti schema.
+ * MCP handlers for `FileCas` (`fjs/mcp/cas`) plus the Evo API (`fjs/mcp/evo`)
+ * layered on it, bound to `home` and an already-built Evo cache slot (see
+ * `initEvo`).
  */
-export const tool = {
-    name: string,
-    description: option(string),
-    inputSchema: unknown,
-};
+export const casMcpHandlers = (home) => (cacheKey) => fromRegistry([...casToolRegistry(home)(cacheKey), ...evoToolRegistry(evo(fileCas(sha256)(home))(cacheKey))]);
+// ── Session configuration ───────────────────────────────────────────────────────
 /**
- * Params for the `tools/list` request. `cursor` is an opaque pagination token
- * from a previous `ToolsListResult.nextCursor`.
+ * Static MCP configuration for the CAS server: advertises the `tools`
+ * capability, identifies the server, and pins the protocol version.
  */
-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),
+export const casConfig = {
+    serverInfo: { name: 'functionalscript-cas', version: '0.30.0' },
+    capabilities: { tools: {} },
+    protocolVersion: '2024-11-05',
 };
+// ── Server ──────────────────────────────────────────────────────────────────────
 /**
- * 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.
+ * Runs the combined CAS + Evo MCP server over stdio: scans `~/.cas/` once to
+ * build the Evo subject/head cache (`initEvo`), allocates the session-state
+ * slot, builds the `mcpStep` for the merged tool registry, and drives the
+ * read → parse → dispatch → write loop until stdin EOF.
  */
-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));
-    });
+export const casMcpServer = (home) => step(initEvo(fileCas(sha256)(home)), cacheKey => step(create(uninitializedState), sessionKey => stdioTransport(mcpStep(casConfig)(casMcpHandlers(home)(cacheKey))(sessionKey))));
+// ── Tests ────────────────────────────────────────────────────────────────────
+export const proof = {
+    // casMcpServer is never called in integration tests because it drives a
+    // real stdio server; call it here to cover its Effect-building body.
+    casMcpServer: () => { casMcpServer('/'); },
 };

package/fjs/mcp/proof.f.d.ts

@@ -1,34 +1,45 @@
 export declare const proof: {
-    lifecycle: {
-        initialStateIsUninitialized: () => void;
-        initializeTransitionsToInitializing: () => void;
-        initializedNotificationTransitionsToInitialized: () => void;
-        initializeReturnsResult: () => void;
-        initializeWithBadParamsReturnsInvalidParams: () => void;
-        notificationBeforeInitReturnNull: () => void;
-        unknownNotificationReturnNull: () => void;
-        doubleInitializeReturnsInvalidRequest: () => void;
-        pingBeforeInitSucceeds: () => void;
-        pingDuringInitializingSucceeds: () => void;
-        pingAfterInitSucceeds: () => void;
-        pingWithObjectParamsSucceeds: () => void;
-        pingInvalidParamsReturnsInvalidParams: () => void;
-        initializedNotificationObjectParamsTransitions: () => void;
-        initializedNotificationBadParamsIgnored: () => void;
-        methodBeforeInitReturnsNotInitialized: () => void;
-        methodDuringInitializingReturnsNotInitialized: () => void;
-        invalidEnvelopeReturnsInvalidRequest: () => void;
-    };
-    tools: {
-        toolsListSucceeds: () => void;
-        toolsListPassesCursorToHandler: () => void;
-        toolsListInvalidCursorReturnsInvalidParams: () => void;
-        toolsCallSucceeds: () => void;
-        toolsCallBadParamsReturnsInvalidParams: () => void;
-        toolsCallAbsentArgumentsSucceeds: () => void;
-        toolsCallNullArgumentsReturnsInvalidParams: () => void;
-        toolsListWithoutCapabilityReturnsMethodNotFound: () => void;
-        toolsCallWithoutCapabilityReturnsMethodNotFound: () => void;
-        unknownMethodReturnsMethodNotFound: () => void;
-    };
+    getMetaLargeMultiChunkBlobNoError: () => void;
+    getMetaLargeMultiChunkUtf8Symbols: () => void;
+    getMetaLargeMultiChunkTextThenBinary: () => void;
+    getContentLargeBlobTooLargeError: () => void;
+    getContentMissingHashIsError: () => void;
+    getContentBase64InflationOverflowWritesInternalError: () => void;
+    getContentBase64NearBoundarySucceeds: () => void;
+    getContentDoubleEscapedOverflowWritesInternalError: () => void;
+    toolsListAdvertisesSevenTools: () => void;
+    evoAddListHeadRoundTripsThroughCasServer: () => void;
+    evoAddDomainErrorIsErrorThroughCasServer: () => void;
+    casAddSyncsEvoCacheForRevisionContent: () => void;
+    addReturnsHash: () => void;
+    textAddGetMetaRoundTrips: () => void;
+    textAddGetContentRoundTrips: () => void;
+    binaryAddGetMetaRoundTrips: () => void;
+    binaryAddGetContentRoundTrips: () => void;
+    addGetRoundTrips: () => void;
+    getUntypedReturnsText: () => void;
+    getTypedReturnsBinaryJson: () => void;
+    getMetaRecognizesRevisionDialect: () => void;
+    getContentRecognizesRevisionDialect: () => void;
+    listEnumeratesStoredHashes: () => void;
+    addInvalidContentIsError: () => void;
+    addBadLengthContentIsError: () => void;
+    addBase64OverLimitIsError: () => void;
+    addTextOverLimitIsError: () => void;
+    addTextAtLimitSucceeds: () => void;
+    addBase64AtLimitSucceeds: () => void;
+    getUnterminatedHashIsError: () => void;
+    addMissingContentIsError: () => void;
+    getMissingHashArgumentIsError: () => void;
+    getInvalidHashIsError: () => void;
+    getMissingHashIsError: () => void;
+    unknownToolIsError: () => void;
+    toolErrorIsNotJsonRpcError: () => void;
+    getMetaReturnsLengthAndMimeType: () => void;
+    getMetaBinaryBlob: () => void;
+    getMetaOctetStreamForUnknownBinary: () => void;
+    getMetaOctetStreamForNulBlob: () => void;
+    getMetaMissingHashIsError: () => void;
+    getMetaInvalidHashIsError: () => void;
+    getOctetStreamWithContentIncludesBase64: () => void;
 };