@foldkit/devtools-mcp 0.1.2 → 0.3.0

package/README.md

@@ -4,8 +4,11 @@ A Model Context Protocol server that exposes a running [Foldkit](https://foldkit
 
 With it attached, agents can:
 
-- Read the current Model
-- List and inspect the Message history
+- Read the current Model, or any historical Model by history index
+- Narrow reads with dot-string paths and summarized payloads to fit token budgets
+- List and inspect the Message history, with diffs and submodel chains
+- Read the recorded init Model and init Command names
+- Inspect runtime state: current index, retained history bounds, pause status
 - Replay to any past state and resume
 - Dispatch Messages into the runtime, decoded against your `Message` Schema
 
@@ -55,7 +58,7 @@ Runtime.makeProgram({
 })
 ```
 
-Restart your dev server, then restart your AI agent. The MCP server will appear with the eight `foldkit_*` tools attached.
+Restart your dev server, then restart your AI agent. The MCP server will appear with the `foldkit_*` tools attached.
 
 The browser bridge runs inside your app, so the MCP server only sees a runtime while the app is open in a browser tab. Close the tab and the runtime disappears from `foldkit_list_runtimes`.
 
@@ -63,16 +66,26 @@ The browser bridge runs inside your app, so the MCP server only sees a runtime w
 
 Each tool accepts an optional `runtime_id`. When omitted, the most recently connected runtime is used.
 
-| Tool                         | Description                                                                                                                                                                 |
-| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `foldkit_list_runtimes`      | Returns metadata for every connected browser tab. Agents call this first to discover which runtime to target.                                                               |
-| `foldkit_get_model`          | Snapshots the current Model.                                                                                                                                                |
-| `foldkit_list_messages`      | Lists recent Message history entries with pagination. Each entry carries the Message body, command names triggered, timestamp, and a path-level diff.                       |
-| `foldkit_get_message`        | Reads one entry at a given index, including the Model before and after the Message was applied.                                                                             |
-| `foldkit_list_keyframes`     | Returns the indices Foldkit can replay back to. Index `-1` is the initial Model.                                                                                            |
-| `foldkit_replay_to_keyframe` | Time-travels the runtime to a previous state. The runtime is paused at that snapshot until `foldkit_resume` is called.                                                      |
-| `foldkit_resume`             | Resumes normal execution after a replay.                                                                                                                                    |
-| `foldkit_dispatch_message`   | Enqueues a Message into the runtime as if your application produced it. The runtime decodes the payload against your Schema and returns a clean error if it does not match. |
+| Tool                         | Description                                                                                                                                                                                                                                             |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `foldkit_list_runtimes`      | Returns metadata for every connected browser tab. Agents call this first to discover which runtime to target.                                                                                                                                           |
+| `foldkit_get_model`          | Snapshots the current Model. Accepts an optional `path` to narrow to a subtree and `expand` to control summarization.                                                                                                                                   |
+| `foldkit_get_model_at`       | Snapshots a historical Model after a given history entry. Pass `index: N - 1` to read the Model just before message `N`. Same `path`/`expand` semantics as `foldkit_get_model`. For the initial Model (and init Command names), use `foldkit_get_init`. |
+| `foldkit_get_init`           | Reads the recorded initial Model and the names of Commands returned from the application's `init` function. Equivalent to selecting the synthetic "init" row in the DevTools panel.                                                                     |
+| `foldkit_get_runtime_state`  | Snapshots the runtime's DevTools state: history bounds, current paused/live status, and whether init is recorded. Useful for understanding what `foldkit_list_messages` and `foldkit_get_message` will see and detecting whether the runtime is paused. |
+| `foldkit_list_messages`      | Lists recent Message history entries with pagination. Each entry carries the Message body, Command names triggered, timestamp, an `isModelChanged` flag, the diff path lists (`changedPaths` / `affectedPaths`), and any extracted Submodel chain.      |
+| `foldkit_get_message`        | Reads one entry at a given index. The response carries the SerializedEntry only; to inspect the Model around the entry, call `foldkit_get_model_at` with `index - 1` (before) and `index` (after). Use `foldkit_get_init` for the synthetic init entry. |
+| `foldkit_list_keyframes`     | Returns the indices Foldkit can replay back to. Index `-1` is the initial Model.                                                                                                                                                                        |
+| `foldkit_replay_to_keyframe` | Time-travels the runtime to a previous state. The runtime is paused at that snapshot until `foldkit_resume` is called.                                                                                                                                  |
+| `foldkit_resume`             | Resumes normal execution after a replay.                                                                                                                                                                                                                |
+| `foldkit_dispatch_message`   | Enqueues a Message into the runtime as if your application produced it. The runtime decodes the payload against your Schema and returns a clean error if it does not match.                                                                             |
+
+### Reading the Model efficiently
+
+`foldkit_get_model` and `foldkit_get_model_at` are designed for AI agents reading state into a token-bounded context. Two parameters control the payload size:
+
+- **`path`** is a dot-string anchored at `root` that narrows the response to a subtree. The alphabet matches the `changedPaths` array on each `SerializedEntry`, so a path observed in `foldkit_list_messages` can be passed straight back. Examples: `'root'` (the whole Model), `'root.route'`, `'root.session.user'`, `'root.cards.0'`. When the path doesn't resolve, the response is an error listing the keys available at the deepest segment that did resolve, so the agent can refine in one follow-up call.
+- **`expand`** controls summarization. By default (`false`), large arrays collapse to `{ _summary: 'array', length, sample: [head, last] }`, deeply nested records collapse to `{ _summary: 'record', keys }`, and long strings collapse to `{ _summary: 'string', length, head }`. Tagged-union variants (`{ _tag, ... }`) keep their tag and recursively summarize children. With `expand: true`, the literal value at the path is returned with no summarization. Pair a narrow `path` with `expand: true` to read a specific subtree at full fidelity without paying for the rest of the Model.
 
 ## Architecture
 

package/dist/server.js

@@ -2,7 +2,7 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
-import { Effect, HashMap, Option, Runtime } from 'effect';
+import { Console, Effect, HashMap, Option } from 'effect';
 import { runInit } from './install.js';
 import { buildTools } from './tools.js';
 import { connectWebSocketClient } from './webSocketClient.js';
@@ -14,7 +14,7 @@ const main = Effect.gen(function* () {
     const wsClient = yield* connectWebSocketClient(`ws://${host}:${port}`);
     const tools = buildTools(wsClient);
     const toolsByName = HashMap.fromIterable(tools.map(tool => [tool.name, tool]));
-    const runtime = yield* Effect.runtime();
+    const runtime = yield* Effect.context();
     const server = new Server({ name: '@foldkit/devtools-mcp', version: '0.1.0' }, { capabilities: { tools: {} } });
     server.setRequestHandler(ListToolsRequestSchema, () => Promise.resolve({
         tools: tools.map(({ name, description, inputSchema }) => ({
@@ -33,21 +33,34 @@ const main = Effect.gen(function* () {
             ],
             isError: true,
         }),
-        onSome: tool => Runtime.runPromise(runtime)(tool.handle(request.params.arguments ?? {})),
+        onSome: tool => Effect.runPromiseWith(runtime)(tool.handle(request.params.arguments ?? {})),
     }));
     const transport = new StdioServerTransport();
     yield* Effect.tryPromise({
         try: () => server.connect(transport),
         catch: error => error,
     });
-    yield* Effect.sync(() => console.error('[foldkit-devtools-mcp] MCP server ready on stdio'));
+    yield* Console.error('[foldkit-devtools-mcp] MCP server ready on stdio');
+    // NOTE: blocks until stdin closes (parent MCP host exited). Without this,
+    // the forked WebSocket connection-loop fiber keeps the Effect runtime alive
+    // forever. The subprocess outlives its parent and accumulates as a zombie
+    // across host restarts.
+    yield* Effect.callback(resume => {
+        const onClose = () => resume(Effect.void);
+        process.stdin.on('end', onClose);
+        process.stdin.on('close', onClose);
+        return Effect.sync(() => {
+            process.stdin.off('end', onClose);
+            process.stdin.off('close', onClose);
+        });
+    });
 });
 const subcommand = process.argv[2];
 if (subcommand === 'init') {
     runInit();
 }
 else {
-    Effect.runPromise(main).catch(error => {
+    Effect.runPromise(main).then(() => process.exit(0), error => {
         console.error('[foldkit-devtools-mcp] fatal error', error);
         process.exit(1);
     });

package/dist/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAS,MAAM,EAA0C,MAAM,QAAQ,CAAA;AAc9E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAyF3D,KAAK,UAAU,GAAG,QAAQ,CAAC;IACzB,OAAO,EAAE,aAAa,CAAC,QAAQ,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,CAAA;IAChE,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB,CAAC,CAAA;AAEF,8HAA8H;AAC9H,MAAM,MAAM,cAAc,GAAG,QAAQ,CAAC;IACpC,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,WAAW,EAAE,MAAM,CAAA;IACnB,MAAM,EAAE,CAAC,QAAQ,EAAE,OAAO,KAAK,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,CAAA;CACzD,CAAC,CAAA;AA4GF;;;;GAIG;AACH,eAAO,MAAM,UAAU,GACrB,UAAU,eAAe,KACxB,aAAa,CAAC,cAAc,CA0F9B,CAAA"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAS,MAAM,EAA8B,MAAM,QAAQ,CAAA;AAiBlE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAuH3D,KAAK,UAAU,GAAG,QAAQ,CAAC;IACzB,OAAO,EAAE,aAAa,CAAC,QAAQ,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,CAAA;IAChE,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB,CAAC,CAAA;AAEF,8HAA8H;AAC9H,MAAM,MAAM,cAAc,GAAG,QAAQ,CAAC;IACpC,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,WAAW,EAAE,MAAM,CAAA;IACnB,MAAM,EAAE,CAAC,QAAQ,EAAE,OAAO,KAAK,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,CAAA;CACzD,CAAC,CAAA;AA0GF;;;;GAIG;AACH,eAAO,MAAM,UAAU,GACrB,UAAU,eAAe,KACxB,aAAa,CAAC,cAAc,CAqI9B,CAAA"}

package/dist/tools.js

@@ -1,22 +1,39 @@
-import { Array, Effect, JSONSchema, Match, Option, Schema as S } from 'effect';
-import { RequestDispatchMessage, RequestGetMessage, RequestGetModel, RequestListKeyframes, RequestListMessages, RequestListRuntimes, RequestReplayToKeyframe, RequestResume, } from 'foldkit/devtools-protocol';
+import { Array, Effect, Match, Option, Schema as S } from 'effect';
+import { RequestDispatchMessage, RequestGetInit, RequestGetMessage, RequestGetModel, RequestGetModelAt, RequestGetRuntimeState, RequestListKeyframes, RequestListMessages, RequestListRuntimes, RequestReplayToKeyframe, RequestResume, } from 'foldkit/devtools-protocol';
 const RUNTIME_ID_DESCRIPTION = 'Optional connection id of a specific Foldkit runtime. Defaults to the most recently connected runtime.';
 const DEFAULT_LIST_MESSAGES_LIMIT = 50;
-const RuntimeIdField = S.optional(S.String.annotations({ description: RUNTIME_ID_DESCRIPTION }));
-const ListLimit = S.Number.pipe(S.int(), S.between(1, 500), S.annotations({
+const RuntimeIdField = S.optional(S.String.annotate({ description: RUNTIME_ID_DESCRIPTION }));
+const ListLimit = S.Int.check(S.isBetween({ minimum: 1, maximum: 500 })).annotate({
     description: `Maximum number of entries to return. Defaults to ${DEFAULT_LIST_MESSAGES_LIMIT}; max 500.`,
-}));
-const SinceIndex = S.Number.pipe(S.int(), S.annotations({
+});
+const SinceIndex = S.Int.annotate({
     description: 'Absolute history index to start from. Use the maybeNextIndex returned by a prior call to paginate.',
-}));
-const MessageIndex = S.Number.pipe(S.int(), S.annotations({
+});
+const MessageIndex = S.Int.annotate({
     description: 'Absolute history index of the entry to read.',
-}));
-const KeyframeIndex = S.Number.pipe(S.int(), S.annotations({
+});
+const KeyframeIndex = S.Int.annotate({
     description: 'Index to replay to. Use -1 to jump to the initial Model (before any messages). Use a non-negative index to jump to the Model state right after that history index. Call foldkit_list_keyframes for the canonical replay points.',
+});
+const ModelIndex = S.Int.annotate({
+    description: 'Absolute history index. Returns the Model state right after the entry at this index was applied. To inspect the Model immediately before message N, pass index N - 1. For the initial Model, use foldkit_get_init.',
+});
+const PathField = S.optional(S.String.annotate({
+    description: "Dot-string path into the Model anchored at 'root'. Examples: 'root', 'root.route', 'root.session.user', 'root.cards.0'. Matches the alphabet used by SerializedEntry.changedPaths so paths copied from one tool's output can be passed straight into the next. Defaults to 'root' (the whole Model).",
+}));
+const ExpandField = S.optional(S.Boolean.annotate({
+    description: "When false (the default), large arrays/records/strings collapse to '_summary' placeholders to keep payloads small. Set true to receive the literal value at the path. Pair with `path` to drill in: a narrow path with `expand: true` is the cheapest way to read a specific subtree at full fidelity.",
 }));
 const GetModelInput = S.Struct({
     runtime_id: RuntimeIdField,
+    path: PathField,
+    expand: ExpandField,
+});
+const GetModelAtInput = S.Struct({
+    runtime_id: RuntimeIdField,
+    index: ModelIndex,
+    path: PathField,
+    expand: ExpandField,
 });
 const ListMessagesInput = S.Struct({
     runtime_id: RuntimeIdField,
@@ -37,17 +54,26 @@ const ReplayToKeyframeInput = S.Struct({
 const ResumeInput = S.Struct({
     runtime_id: RuntimeIdField,
 });
+const GetInitInput = S.Struct({
+    runtime_id: RuntimeIdField,
+});
+const GetRuntimeStateInput = S.Struct({
+    runtime_id: RuntimeIdField,
+});
 const DispatchMessageInput = S.Struct({
     runtime_id: RuntimeIdField,
-    message: S.Unknown.annotations({
+    message: S.Unknown.annotate({
         description: "A Foldkit Message object to dispatch into the runtime. Must match the runtime's Message Schema — read the application's source to see the exact shape. At minimum it has a `_tag` field naming the variant. The runtime decodes the payload and returns a clean error if it doesn't match.",
     }),
 });
 /**
- * JSON Schema for tools that take no input. Inlined as a literal because
- * `JSONSchema.make(S.Struct({}))` produces a shape MCP's AJV validator
- * rejects (no top-level `type: "object"` for an empty struct).
+ * Extract the inner JSON Schema from Effect's `JsonSchema.Document` wrapper.
+ * MCP's tool registry validates `inputSchema.type === "object"` at the top
+ * level; the Document wrapper (`{ dialect, schema, definitions }`) hides
+ * `type` one level deeper, so registration silently fails. Unwrapping fixes
+ * tool surfacing in Claude Code, Cursor, and any other MCP host.
  */
+const toInputSchema = (codec) => S.toJsonSchemaDocument(codec).schema;
 const NO_INPUT_SCHEMA = {
     type: 'object',
     properties: {},
@@ -64,7 +90,7 @@ const formatError = (reason) => ({
  * Decode a tool's raw input against its Effect Schema. Failure surfaces as an
  * `Error` for the outer handler's `catchAll` to convert into a `ToolResult`.
  */
-const decodeInput = (schema, rawInput) => S.decodeUnknown(schema)(rawInput).pipe(Effect.mapError(error => new Error(`Invalid input: ${error.message}`)));
+const decodeInput = (schema, rawInput) => S.decodeUnknownEffect(schema)(rawInput).pipe(Effect.mapError(error => new Error(`Invalid input: ${error.message}`)));
 /**
  * Resolve a runtime id, defaulting to the most recently connected runtime when
  * the caller did not specify one. Failures (no runtimes connected, relay
@@ -89,7 +115,7 @@ const callRuntimeRequest = (wsClient, explicitRuntimeId, buildRequest) => Effect
     const runtimeId = yield* resolveRuntimeId(wsClient, explicitRuntimeId);
     const response = yield* wsClient.sendRequest(buildRequest(), Option.some(runtimeId));
     return responseToToolResult(response);
-}).pipe(Effect.catchAll(error => Effect.succeed(formatError(error.message))));
+}).pipe(Effect.catch(error => Effect.succeed(formatError(error.message))));
 /**
  * Build a tool handler that decodes its input, resolves the target runtime,
  * issues a typed `Request`, and formats the response. Used for every tool
@@ -98,7 +124,7 @@ const callRuntimeRequest = (wsClient, explicitRuntimeId, buildRequest) => Effect
 const runRuntimeTool = (inputSchema, buildRequest, wsClient) => (rawInput) => Effect.gen(function* () {
     const input = yield* decodeInput(inputSchema, rawInput);
     return yield* callRuntimeRequest(wsClient, input.runtime_id, () => buildRequest(input));
-}).pipe(Effect.catchAll(error => Effect.succeed(formatError(error.message))));
+}).pipe(Effect.catch(error => Effect.succeed(formatError(error.message))));
 /**
  * Build the read-only Foldkit DevTools tool definitions. Each tool decodes its
  * input via Effect Schema, dispatches a typed `Request` through the WebSocket
@@ -107,47 +133,72 @@ const runRuntimeTool = (inputSchema, buildRequest, wsClient) => (rawInput) => Ef
 export const buildTools = (wsClient) => [
     {
         name: 'foldkit_get_model',
-        description: 'Snapshot the current Model from a connected Foldkit runtime.',
-        inputSchema: JSONSchema.make(GetModelInput),
-        handle: runRuntimeTool(GetModelInput, () => RequestGetModel(), wsClient),
+        description: "Snapshot the current Model from a connected Foldkit runtime. By default the response is summarized (large arrays/records/strings collapse to `_summary` placeholders) to keep payloads small for AI agents. Pass `path` (e.g. 'root.session.user') to narrow to a subtree, and `expand: true` to receive the literal value at that path. Returns `{ value, atPath, summarized }`.",
+        inputSchema: toInputSchema(GetModelInput),
+        handle: runRuntimeTool(GetModelInput, ({ path, expand }) => RequestGetModel({
+            maybePath: Option.fromNullishOr(path),
+            expand: expand ?? false,
+        }), wsClient),
+    },
+    {
+        name: 'foldkit_get_model_at',
+        description: "Snapshot a historical Model after a given history entry was applied. Pass `index: N - 1` to read the Model just before message N. Same `path`/`expand` semantics as foldkit_get_model. For the initial Model (and the names of Commands returned from the application's `init`), use foldkit_get_init.",
+        inputSchema: toInputSchema(GetModelAtInput),
+        handle: runRuntimeTool(GetModelAtInput, ({ index, path, expand }) => RequestGetModelAt({
+            index,
+            maybePath: Option.fromNullishOr(path),
+            expand: expand ?? false,
+        }), wsClient),
     },
     {
         name: 'foldkit_list_messages',
         description: 'List recent Message history entries from a Foldkit runtime, with optional pagination via since_index.',
-        inputSchema: JSONSchema.make(ListMessagesInput),
+        inputSchema: toInputSchema(ListMessagesInput),
         handle: runRuntimeTool(ListMessagesInput, ({ limit, since_index }) => RequestListMessages({
             limit: limit ?? DEFAULT_LIST_MESSAGES_LIMIT,
-            maybeSinceIndex: Option.fromNullable(since_index),
+            maybeSinceIndex: Option.fromNullishOr(since_index),
         }), wsClient),
     },
     {
         name: 'foldkit_get_message',
-        description: 'Read a single Message history entry by absolute index, including before/after Model snapshots.',
-        inputSchema: JSONSchema.make(GetMessageInput),
+        description: 'Read a single Message history entry by absolute index. The response carries the SerializedEntry (tag, message body, commandNames, timestamp, `isModelChanged`, `changedPaths` for leaf-level mutations, `affectedPaths` adding their ancestor paths). For Submodel-routed entries (tag matches `Got*Message`), the entry also carries `submodelPath` listing wrapper tags from outer to inner and `maybeLeafTag` naming the innermost child Message. Model snapshots are not included; call foldkit_get_model_at with `index - 1` (before) and `index` (after) to inspect Model state around the entry.',
+        inputSchema: toInputSchema(GetMessageInput),
         handle: runRuntimeTool(GetMessageInput, ({ index }) => RequestGetMessage({ index }), wsClient),
     },
+    {
+        name: 'foldkit_get_init',
+        description: "Read the runtime's initial Model and the names of Commands returned from the application's `init` function. The init entry is the synthetic row at index -1 in the DevTools panel; this tool exposes the same data without time-travelling the runtime. `maybeModel` is `None` until the runtime has finished its first render and recorded init, then stays `Some` for the rest of the runtime's life.",
+        inputSchema: toInputSchema(GetInitInput),
+        handle: runRuntimeTool(GetInitInput, () => RequestGetInit(), wsClient),
+    },
+    {
+        name: 'foldkit_get_runtime_state',
+        description: "Snapshot the runtime's DevTools state: history bounds, current paused/live status, and whether init is recorded. Returns `currentIndex` (the absolute index of the most recent Message, or -1 when none), `startIndex` (the earliest absolute index still retained in the rolling buffer), `totalEntries` (count of retained entries), `isPaused`, `maybePausedAtIndex` (`Some(index)` when paused, `None` otherwise), and `hasInitModel`. Use it to reason about what `foldkit_list_messages` and `foldkit_get_message` will see, and to detect whether the runtime is currently paused at a replayed snapshot.",
+        inputSchema: toInputSchema(GetRuntimeStateInput),
+        handle: runRuntimeTool(GetRuntimeStateInput, () => RequestGetRuntimeState(), wsClient),
+    },
     {
         name: 'foldkit_list_keyframes',
         description: 'List the available keyframes (replayable Model snapshots) from a Foldkit runtime.',
-        inputSchema: JSONSchema.make(ListKeyframesInput),
+        inputSchema: toInputSchema(ListKeyframesInput),
         handle: runRuntimeTool(ListKeyframesInput, () => RequestListKeyframes(), wsClient),
     },
     {
         name: 'foldkit_replay_to_keyframe',
         description: 'Time-travel a Foldkit runtime back to a previous Model snapshot. Pass `keyframe_index: -1` for the initial Model, or a non-negative index for the state right after that history entry. The runtime is paused at the snapshot until foldkit_resume is called.',
-        inputSchema: JSONSchema.make(ReplayToKeyframeInput),
+        inputSchema: toInputSchema(ReplayToKeyframeInput),
         handle: runRuntimeTool(ReplayToKeyframeInput, ({ keyframe_index }) => RequestReplayToKeyframe({ keyframeIndex: keyframe_index }), wsClient),
     },
     {
         name: 'foldkit_resume',
         description: 'Resume normal execution of a Foldkit runtime that was paused by foldkit_replay_to_keyframe.',
-        inputSchema: JSONSchema.make(ResumeInput),
+        inputSchema: toInputSchema(ResumeInput),
         handle: runRuntimeTool(ResumeInput, () => RequestResume(), wsClient),
     },
     {
         name: 'foldkit_dispatch_message',
         description: "Dispatch a Message into a Foldkit runtime's message queue, as if the application itself produced it. Requires the runtime to have configured DevToolsConfig.Message; without it, dispatch is rejected. Read the application's Message Schema source to construct a valid Message object. The runtime decodes the payload and returns a clean error if it doesn't match.",
-        inputSchema: JSONSchema.make(DispatchMessageInput),
+        inputSchema: toInputSchema(DispatchMessageInput),
         handle: runRuntimeTool(DispatchMessageInput, ({ message }) => RequestDispatchMessage({ message }), wsClient),
     },
     {
@@ -157,6 +208,6 @@ export const buildTools = (wsClient) => [
         handle: () => Effect.gen(function* () {
             const response = yield* wsClient.sendRequest(RequestListRuntimes(), Option.none());
             return responseToToolResult(response);
-        }).pipe(Effect.catchAll(error => Effect.succeed(formatError(error.message)))),
+        }).pipe(Effect.catch(error => Effect.succeed(formatError(error.message)))),
     },
 ];

package/dist/webSocketClient.d.ts

@@ -1,28 +1,36 @@
 import { type Cause, Effect, Option } from 'effect';
 import { type Request, type Response } from 'foldkit/devtools-protocol';
 /**
- * A connected WebSocket client to the Foldkit Vite plugin's DevTools relay.
+ * A WebSocket client to the Foldkit Vite plugin's DevTools relay.
  *
  * Sends typed `Request`s and resolves with the matching `Response`. The
  * `sendRequest` Effect fails with `TimeoutException` when no response arrives
- * within the request timeout window, or with `Error` when the socket is not
- * open or the send throws. Either way, no pending entry leaks.
+ * within the request timeout window, or with `Error` when no relay is
+ * connected or the send throws. Either way, no pending entry leaks.
  *
- * The client transparently reconnects with exponential backoff when the
- * underlying socket closes (e.g. when the user restarts the Vite dev server).
- * Pending response correlators live in a client-owned Ref, not on the socket,
- * so they survive reconnects: in-flight requests time out and future requests
- * succeed once the new socket is open.
+ * The client manages its own connection lifecycle in a background fiber:
+ * the initial connect is retried with exponential backoff, and any later
+ * disconnect (e.g. when the user restarts the Vite dev server) reconnects
+ * via the same loop. The MCP server can stay live across dev-server
+ * restarts and even when no dev server has started yet — `sendRequest`
+ * returns a clear "not connected" error in that window, and tools should
+ * surface it to the agent so the user can start a dev server and retry.
+ *
+ * Pending response correlators live in a client-owned Ref, not on the
+ * socket, so they survive reconnects: in-flight requests time out and
+ * future requests succeed once the new socket is open.
  */
 export type WebSocketClient = Readonly<{
-    sendRequest: (request: typeof Request.Type, maybeRuntimeId: Option.Option<string>) => Effect.Effect<typeof Response.Type, Cause.TimeoutException | Error>;
+    sendRequest: (request: typeof Request.Type, maybeRuntimeId: Option.Option<string>) => Effect.Effect<typeof Response.Type, Cause.TimeoutError | Error>;
     close: Effect.Effect<void>;
 }>;
 /**
- * Open a WebSocket connection to the Foldkit Vite plugin's DevTools relay.
- * The Effect succeeds once the initial connection is open and ready for
- * traffic. It fails with the underlying `Error` if the *first* connection
- * cannot be opened. Subsequent disconnects reconnect transparently.
+ * Construct a WebSocket client that maintains its connection to the Foldkit
+ * Vite plugin's DevTools relay in the background. The Effect succeeds
+ * immediately with a client whose connection state evolves over time. The
+ * initial connect is retried with exponential backoff; later disconnects
+ * reconnect via the same loop. `sendRequest` fails with a clear "not
+ * connected" error while no relay is reachable.
  */
-export declare const connectWebSocketClient: (url: string) => Effect.Effect<WebSocketClient, Error>;
+export declare const connectWebSocketClient: (url: string) => Effect.Effect<WebSocketClient>;
 //# sourceMappingURL=webSocketClient.d.ts.map

package/dist/webSocketClient.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"webSocketClient.d.ts","sourceRoot":"","sources":["../src/webSocketClient.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,KAAK,EAGV,MAAM,EAIN,MAAM,EAMP,MAAM,QAAQ,CAAA;AACf,OAAO,EACL,KAAK,OAAO,EAEZ,KAAK,QAAQ,EAEd,MAAM,2BAA2B,CAAA;AAYlC;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,eAAe,GAAG,QAAQ,CAAC;IACrC,WAAW,EAAE,CACX,OAAO,EAAE,OAAO,OAAO,CAAC,IAAI,EAC5B,cAAc,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,KAClC,MAAM,CAAC,MAAM,CAAC,OAAO,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC,gBAAgB,GAAG,KAAK,CAAC,CAAA;IACxE,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;CAC3B,CAAC,CAAA;AAwDF;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,GACjC,KAAK,MAAM,KACV,MAAM,CAAC,MAAM,CAAC,eAAe,EAAE,KAAK,CAuHnC,CAAA"}
+{"version":3,"file":"webSocketClient.d.ts","sourceRoot":"","sources":["../src/webSocketClient.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,KAAK,EAIV,MAAM,EAIN,MAAM,EAKP,MAAM,QAAQ,CAAA;AACf,OAAO,EACL,KAAK,OAAO,EAEZ,KAAK,QAAQ,EAEd,MAAM,2BAA2B,CAAA;AAgBlC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,eAAe,GAAG,QAAQ,CAAC;IACrC,WAAW,EAAE,CACX,OAAO,EAAE,OAAO,OAAO,CAAC,IAAI,EAC5B,cAAc,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,KAClC,MAAM,CAAC,MAAM,CAAC,OAAO,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC,YAAY,GAAG,KAAK,CAAC,CAAA;IACpE,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;CAC3B,CAAC,CAAA;AAqDF;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,GACjC,KAAK,MAAM,KACV,MAAM,CAAC,MAAM,CAAC,eAAe,CAuH5B,CAAA"}

package/dist/webSocketClient.js

@@ -1,15 +1,13 @@
-import { Deferred, Duration, Effect, Either, Fiber, HashMap, Option, Ref, Runtime, Schema as S, Schedule, pipe, } from 'effect';
-import { ResponseFrame, } from 'foldkit/devtools-protocol';
+import { Console, Deferred, Duration, Effect, Exit, Fiber, HashMap, Option, Ref, Schema as S, Schedule, pipe, } from 'effect';
+import { RequestFrame, ResponseFrame, } from 'foldkit/devtools-protocol';
 import { WebSocket } from 'ws';
 const REQUEST_TIMEOUT = Duration.seconds(10);
 const INITIAL_RECONNECT_DELAY = Duration.millis(500);
 const MAX_RECONNECT_DELAY = Duration.seconds(30);
+const encodeRequestFrameToJson = S.encodeUnknownSync(S.fromJsonString(RequestFrame));
 const generateRequestId = () => `req-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
-/** Exponential backoff capped at MAX_RECONNECT_DELAY, retried indefinitely. */
-const reconnectSchedule = Schedule.exponential(INITIAL_RECONNECT_DELAY).pipe(Schedule.modifyDelay(delay => Duration.lessThanOrEqualTo(delay, MAX_RECONNECT_DELAY)
-    ? delay
-    : MAX_RECONNECT_DELAY));
-const attemptOpen = (url) => Effect.async(resume => {
+const reconnectSchedule = Schedule.exponential(INITIAL_RECONNECT_DELAY).pipe(Schedule.modifyDelay((_output, delay) => Effect.succeed(Duration.min(delay, MAX_RECONNECT_DELAY))));
+const attemptOpen = (url) => Effect.callback(resume => {
     const socket = new WebSocket(url);
     let settled = false;
     socket.once('open', () => {
@@ -31,7 +29,7 @@ const attemptOpen = (url) => Effect.async(resume => {
         }
     });
 });
-const waitForClose = (socket) => Effect.async(resume => {
+const waitForClose = (socket) => Effect.callback(resume => {
     const isAlreadyClosing = socket.readyState === WebSocket.CLOSED ||
         socket.readyState === WebSocket.CLOSING;
     if (isAlreadyClosing) {
@@ -49,58 +47,60 @@ const waitForClose = (socket) => Effect.async(resume => {
     }
 });
 /**
- * Open a WebSocket connection to the Foldkit Vite plugin's DevTools relay.
- * The Effect succeeds once the initial connection is open and ready for
- * traffic. It fails with the underlying `Error` if the *first* connection
- * cannot be opened. Subsequent disconnects reconnect transparently.
+ * Construct a WebSocket client that maintains its connection to the Foldkit
+ * Vite plugin's DevTools relay in the background. The Effect succeeds
+ * immediately with a client whose connection state evolves over time. The
+ * initial connect is retried with exponential backoff; later disconnects
+ * reconnect via the same loop. `sendRequest` fails with a clear "not
+ * connected" error while no relay is reachable.
  */
 export const connectWebSocketClient = (url) => Effect.gen(function* () {
-    const initialSocket = yield* attemptOpen(url);
-    yield* Effect.sync(() => console.error(`[foldkit-devtools-mcp] connected to ${url}`));
     const pendingResponsesRef = yield* Ref.make(HashMap.empty());
-    const currentSocketRef = yield* Ref.make(initialSocket);
+    const currentSocketRef = yield* Ref.make(Option.none());
     const isManuallyClosedRef = yield* Ref.make(false);
-    const runtime = yield* Effect.runtime();
+    const capturedContext = yield* Effect.context();
     const attachMessageHandler = (socket) => {
         socket.on('message', raw => {
-            Runtime.runFork(runtime)(handleIncomingMessage(raw, pendingResponsesRef));
+            Effect.runForkWith(capturedContext)(handleIncomingMessage(raw, pendingResponsesRef));
         });
         socket.on('error', error => {
             console.error(`[foldkit-devtools-mcp] socket error: ${error.message}`);
         });
     };
-    attachMessageHandler(initialSocket);
-    const reconnectLoop = Effect.gen(function* () {
-        const socket = yield* Ref.get(currentSocketRef);
+    const openWithBackoff = pipe(attemptOpen(url), Effect.tapError(error => Console.error(`[foldkit-devtools-mcp] connect attempt failed: ${error.message}`)), Effect.retry(reconnectSchedule), Effect.orDie);
+    const maintainConnection = Effect.gen(function* () {
+        const socket = yield* openWithBackoff;
+        yield* Console.error(`[foldkit-devtools-mcp] connected to ${url}`);
+        attachMessageHandler(socket);
+        yield* Ref.set(currentSocketRef, Option.some(socket));
         yield* waitForClose(socket);
         const isManual = yield* Ref.get(isManuallyClosedRef);
         if (isManual) {
             return;
         }
-        yield* Effect.sync(() => console.error('[foldkit-devtools-mcp] connection lost, reconnecting with backoff'));
-        const newSocket = yield* pipe(attemptOpen(url), Effect.tapError(error => Effect.sync(() => console.error(`[foldkit-devtools-mcp] reconnect attempt failed: ${error.message}`))), Effect.retry(reconnectSchedule), Effect.orDie);
-        yield* Effect.sync(() => console.error(`[foldkit-devtools-mcp] reconnected to ${url}`));
-        attachMessageHandler(newSocket);
-        yield* Ref.set(currentSocketRef, newSocket);
-        yield* reconnectLoop;
+        yield* Ref.set(currentSocketRef, Option.none());
+        yield* Console.error('[foldkit-devtools-mcp] connection lost, reconnecting');
+        yield* maintainConnection;
     });
-    const reconnectFiber = yield* Effect.forkDaemon(reconnectLoop);
+    const connectionFiber = yield* Effect.forkDetach(maintainConnection);
     const sendRequest = (request, maybeRuntimeId) => Effect.gen(function* () {
+        const maybeSocket = yield* Ref.get(currentSocketRef);
+        const socket = yield* Option.match(maybeSocket, {
+            onNone: () => Effect.fail(new Error('Not connected to a Foldkit dev server. Start your Foldkit Vite dev server and retry the tool call.')),
+            onSome: candidate => candidate.readyState === WebSocket.OPEN
+                ? Effect.succeed(candidate)
+                : Effect.fail(new Error('Foldkit dev server connection is reconnecting. Retry the tool call in a moment.')),
+        });
         const id = generateRequestId();
         const deferred = yield* Deferred.make();
         yield* Ref.update(pendingResponsesRef, HashMap.set(id, deferred));
-        const socket = yield* Ref.get(currentSocketRef);
-        if (socket.readyState !== WebSocket.OPEN) {
-            yield* Ref.update(pendingResponsesRef, HashMap.remove(id));
-            return yield* Effect.fail(new Error('Socket not open. The dev server may have just restarted; the MCP client is reconnecting. Retry the tool call in a moment.'));
-        }
         const frame = {
             id,
             maybeConnectionId: maybeRuntimeId,
             request,
         };
         yield* Effect.try({
-            try: () => socket.send(JSON.stringify(frame)),
+            try: () => socket.send(encodeRequestFrameToJson(frame)),
             catch: error => error instanceof Error
                 ? error
                 : new Error(`Failed to send request: ${String(error)}`),
@@ -109,17 +109,20 @@ export const connectWebSocketClient = (url) => Effect.gen(function* () {
     });
     const close = Effect.gen(function* () {
         yield* Ref.set(isManuallyClosedRef, true);
-        const socket = yield* Ref.get(currentSocketRef);
-        yield* Effect.sync(() => socket.close());
-        yield* Fiber.interrupt(reconnectFiber);
+        const maybeSocket = yield* Ref.get(currentSocketRef);
+        yield* Option.match(maybeSocket, {
+            onNone: () => Effect.void,
+            onSome: socket => Effect.sync(() => socket.close()),
+        });
+        yield* Fiber.interrupt(connectionFiber);
     });
     return { sendRequest, close };
 });
 const handleIncomingMessage = (raw, pendingResponsesRef) => {
-    const decoded = S.decodeUnknownEither(S.parseJson(ResponseFrame))(raw.toString());
-    return Either.match(decoded, {
-        onLeft: error => Effect.sync(() => console.error('[foldkit-devtools-mcp] failed to decode frame', error)),
-        onRight: responseFrame => Effect.gen(function* () {
+    const decoded = S.decodeUnknownExit(S.fromJsonString(ResponseFrame))(raw.toString());
+    return Exit.match(decoded, {
+        onFailure: error => Effect.sync(() => console.error('[foldkit-devtools-mcp] failed to decode frame', error)),
+        onSuccess: responseFrame => Effect.gen(function* () {
             const map = yield* Ref.get(pendingResponsesRef);
             const maybeDeferred = HashMap.get(map, responseFrame.id);
             yield* Option.match(maybeDeferred, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foldkit/devtools-mcp",
-  "version": "0.1.2",
+  "version": "0.3.0",
   "description": "MCP server exposing Foldkit DevTools to AI agents (Claude Code, Cursor, etc.)",
   "type": "module",
   "main": "./dist/server.js",
@@ -16,7 +16,7 @@
     }
   },
   "peerDependencies": {
-    "effect": "^3.18.2",
+    "effect": "4.0.0-beta.59",
     "foldkit": "^0"
   },
   "dependencies": {
@@ -26,10 +26,10 @@
   "devDependencies": {
     "@types/node": "^22.0.0",
     "@types/ws": "^8.5.13",
-    "effect": "^3.19.19",
+    "effect": "4.0.0-beta.59",
     "rimraf": "^6.0.0",
     "typescript": "^6.0.2",
-    "foldkit": "0.77.0"
+    "foldkit": "0.82.0"
   },
   "files": [
     "dist"