@foldkit/devtools-mcp 0.24.1-canary.11a69068d31a → 0.24.1-canary.1fbeaffe6563

package/README.md

@@ -6,7 +6,7 @@ With it attached, agents can:
 
 - 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 Command and Mount lifecycle, diffs, and Submodel chains
+- List and inspect the Message history, with Command and Mount lifecycle, diffs, and Block chains
 - Query history server-side: filter entries by changed Model paths, count Messages by tag, tail the latest entries, and diff the Models at two indices
 - Read the recorded init Model, the Commands returned from `init`, and the Mounts that fired during the first render
 - Inspect Runtime state: current index, retained history bounds, pause status
@@ -36,17 +36,21 @@ pnpm add -D @foldkit/devtools-mcp
 yarn add -D @foldkit/devtools-mcp
 ```
 
-Pass your `Message` Schema to `Runtime.makeApplication` to let the agent dispatch Messages. The Runtime rejects a payload that does not match the Schema before it reaches update:
+Set `devTools.dispatch` to `true` when calling `Program.make` to let the agent discover and dispatch Messages. Foldkit derives the dispatch Schema from the completed root Block, including generated envelopes for registered child Blocks. The Runtime rejects a payload that does not match that Schema before it reaches update:
 
 ```typescript
-Runtime.makeApplication({
+Program.make({
+  block: ApplicationBlock,
+  container,
   devTools: {
     // Rest of your DevTools config
-    Message,
+    dispatch: true,
   },
 })
 ```
 
+If the completed Message Codec needs Services for decoding, `dispatch: true` adds them to the Program's requirements. Supply any remaining decoding Services through `program.provide(...)`; the dispatch opt-in does not provide them.
+
 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`.
@@ -57,29 +61,29 @@ Treat this server as privileged access to the running application. A connected a
 
 Keep API keys, passwords, access and refresh tokens, authorization headers, session material, and private personal data out of those values. Long-lived secrets belong behind a server boundary, including in local demos. If the browser must temporarily carry a sensitive value, use Effect `Redacted` with a `Schema.Redacted` field configured with `disallowJsonEncode: true`. `Redacted` protects normal string, JSON, and inspection output; it does not encrypt the value or hide a browser-side credential from the person running the browser.
 
-`excludeFromHistory` is for noisy Messages, not sensitive ones. The resulting Model remains inspectable. Omitting `DevToolsConfig.Message` disables dispatch only; read and replay tools remain available. Set `devToolsMcpPort: false` in the Foldkit Vite plugin options to keep the in-browser DevTools without starting the MCP relay, or set `devTools: false` in the application config to disable recording and the browser bridge too.
+`excludeFromHistory` is for noisy Messages, not sensitive ones. The resulting Model remains inspectable. External dispatch is disabled by default; read and replay tools remain available. Set `devToolsMcpPort: false` in the Foldkit Vite plugin options to keep the in-browser DevTools without starting the MCP relay, or set `devTools: false` in the application config to disable recording and the browser bridge too.
 
 ## Tools
 
-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. 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`. Indices outside the readable range (older entries are evicted past the rolling buffer) are rejected with the valid bounds. For the initial Model (and the init Commands and Mounts), use `foldkit_get_init`.                                                                                                              |
-| `foldkit_get_init`              | Reads the recorded initial Model, the Commands returned from the application's `init` function, and the Mounts that fired during the first render. Each Command and Mount carries its declared args. 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 Message history entries. Each entry carries the Message body, Commands triggered (with args), Mounts that started or ended during the resulting render (with args), timestamp, an `isModelChanged` flag, the diff path lists (`changedPaths` / `affectedPaths`), and any extracted Submodel chain. Filter server-side with `changed_paths_match`, read the latest entries with `from_end`, and paginate forward with `since_index`.                                                                 |
-| `foldkit_count_messages_by_tag` | Counts retained history entries by Message tag, without payloads, sorted by count descending. A cheap reconnaissance call before paging through history: it surfaces the high-frequency Messages worth filtering out, and with `changed_paths_match` it answers which Message tags touch a Model subtree.                                                                                                                                                                                                 |
-| `foldkit_diff_models`           | Diffs the Models at two history indices server-side, returning path-level changes `{ path, before, after }` with summarized values. Each side is `{ _tag: 'Present', value }`, or `{ _tag: 'Absent' }` when the path does not exist on that side. Pass `changed_paths_match` to narrow the diff to a subtree.                                                                                                                                                                                             |
-| `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_get_message_schema`    | Describes the Runtime's Message Schema so agents can construct valid Messages without reading the application source. With no arguments, returns a small variant index (top-level tag names plus payload fields). With `variant_tag` set to a dot-separated path of variant tags (e.g. `"GotChildMessage.Opened"`), narrows the JSON Schema along the chain and collapses deeper unions to summary placeholders. Returns `maybeResult: None` when the Runtime hasn't configured `DevToolsConfig.Message`. |
-| `foldkit_dispatch_message`      | Dispatches 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.                                                                                                                                                                                                                                                                                                                             |
-| `foldkit_dispatch_messages`     | Dispatches an ordered batch of 1 to 100 Messages in one call, first to last. The Runtime validates every payload before dispatching any of them, so one invalid entry rejects the whole batch with its zero-based position and nothing is dispatched. The response reports the predicted history index for each Message.                                                                                                                                                                                  |
+Every tool except `foldkit_list_runtimes` accepts an optional `runtime_id`. Without one, the tool uses the most recently connected Runtime of the most recently started dev server.
+
+| Tool                            | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `foldkit_list_runtimes`         | Returns metadata for every connected browser tab. Each tab carries the `projectRoot` of the dev server it belongs to, unless `FOLDKIT_DEVTOOLS_MCP_PORT` or `FOLDKIT_DEVTOOLS_MCP_HOST` is set. 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`. Indices outside the readable range (older entries are evicted past the rolling buffer) are rejected with the valid bounds. For the initial Model (and the init Commands and Mounts), use `foldkit_get_init`.                                                                                        |
+| `foldkit_get_init`              | Reads the recorded initial Model, the Commands returned from the application's `init` function, and the Mounts that fired during the first render. Each Command and Mount carries its declared args. 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 Message history entries. Each entry carries the Message body, Commands triggered (with args), Mounts that started or ended during the resulting render (with args), timestamp, an `isModelChanged` flag, the diff path lists (`changedPaths` / `affectedPaths`), and any extracted Block chain. Filter server-side with `changed_paths_match`, read the latest entries with `from_end`, and paginate forward with `since_index`.                                              |
+| `foldkit_count_messages_by_tag` | Counts retained history entries by Message tag, without payloads, sorted by count descending. A cheap reconnaissance call before paging through history: it surfaces the high-frequency Messages worth filtering out, and with `changed_paths_match` it answers which Message tags touch a Model subtree.                                                                                                                                                                           |
+| `foldkit_diff_models`           | Diffs the Models at two history indices server-side, returning path-level changes `{ path, before, after }` with summarized values. Each side is `{ _tag: 'Present', value }`, or `{ _tag: 'Absent' }` when the path does not exist on that side. Pass `changed_paths_match` to narrow the diff to a subtree.                                                                                                                                                                       |
+| `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_get_message_schema`    | Describes the Runtime's Message Schema so agents can construct valid Messages without reading the application source. With no arguments, returns a small variant index (top-level tag names plus payload fields). With `variant_tag` set to a dot-separated path of variant tags (e.g. `"GotChildMessage.Opened"`), narrows the JSON Schema along the chain and collapses deeper unions to summary placeholders. Returns `maybeResult: None` when external dispatch is not enabled. |
+| `foldkit_dispatch_message`      | Dispatches 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.                                                                                                                                                                                                                                                                                                       |
+| `foldkit_dispatch_messages`     | Dispatches an ordered batch of 1 to 100 Messages in one call, first to last. The Runtime validates every payload before dispatching any of them, so one invalid entry rejects the whole batch with its zero-based position and nothing is dispatched. The response reports the predicted history index for each Message.                                                                                                                                                            |
 
 ### Reading the Model efficiently
 
@@ -102,30 +106,34 @@ High-frequency flows (drag-paint, scroll, keystroke) can fill the history buffer
 Three components cooperate:
 
 - **Browser bridge** (in `foldkit`): runs alongside DevTools, subscribes to the DevTools store, and exchanges typed frames over Vite's HMR WebSocket.
-- **Vite plugin relay** (in `@foldkit/vite-plugin`): serves a WebSocket endpoint on the dev server, publishes its address for discovery, and forwards traffic between browsers and MCP clients.
+- **Vite plugin relay** (in `@foldkit/vite-plugin`): gives each dev server its own loopback listener by default, publishes its address, and forwards traffic between browsers and MCP clients.
 - **MCP server** (this package): runs as a Node child process under your AI agent, connects to the plugin's relay over WebSocket, and exposes the typed tools over MCP's stdio transport.
 
 Multiple browser tabs can be connected at once and each is addressable by its connection id. Tabs that close (gracefully or not) are pruned from the live Runtime list automatically.
 
+The bridge derives JSON Schema for its transport boundary. A Message payload must have a supported JSON representation to be dispatched from MCP. Browser-memory values such as `File` cannot be constructed through this connection.
+
 ## Configuration
 
-The MCP server looks for a running dev server in its project directory. If several relays match, it uses the most recently started one. It discovers the relay again when the dev server restarts.
+An agent started at a workspace root can inspect every Foldkit app running under it. If no dev server runs under the agent's project root, the MCP server finds the nearest root that encloses it. This also lets an agent started in `src/` or through a symlink find the app. `foldkit_list_runtimes` lists the Runtimes from every matching dev server and includes each server's `projectRoot`.
+
+The MCP server connects when a tool is called. It checks the registry on every call, so the next call can reach a dev server that started or restarted after the agent.
 
-| Environment variable               | What it changes                                                                                                                                                             |
-| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `FOLDKIT_PROJECT_ROOT`             | Project to search. Defaults to the working directory. A relay for that directory or one inside it can match.                                                                |
-| `FOLDKIT_DEVTOOLS_MCP_PORT`        | Skips discovery and connects to this port. Set it to the `devToolsMcpPort` in your Vite config. Without this setting, the server tries `9988` if discovery finds nothing.   |
-| `FOLDKIT_DEVTOOLS_MCP_HOST`        | Overrides the hostname of a discovered relay or configured port.                                                                                                            |
-| `FOLDKIT_DEVTOOLS_RELAY_DIRECTORY` | Registry location. Defaults to a directory under `XDG_RUNTIME_DIR` when set, or under the OS temporary directory. Set it in both processes if they use different sandboxes. |
+| Environment variable               | What it changes                                                                                                                                                                                                                                                                            |
+| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `FOLDKIT_PROJECT_ROOT`             | Project to search. Defaults to the working directory.                                                                                                                                                                                                                                      |
+| `FOLDKIT_DEVTOOLS_MCP_PORT`        | Skips discovery and connects to this port. Set it to the `devToolsMcpPort` in your Vite config. When discovery finds no relay, set this variable to use a fixed port.                                                                                                                      |
+| `FOLDKIT_DEVTOOLS_MCP_HOST`        | Skips discovery and connects to this host, on `FOLDKIT_DEVTOOLS_MCP_PORT` or `9988`. Set it when a `devToolsMcpPort` relay runs on another host.                                                                                                                                           |
+| `FOLDKIT_DEVTOOLS_RELAY_DIRECTORY` | Registry location. Defaults to a directory under `XDG_RUNTIME_DIR` when set, `~/.cache` on macOS and Linux, or the user temporary directory on Windows. Set it in both processes if they use different sandboxes. On Windows, it must be a direct child of the user's temporary directory. |
 
-A relay discovered through the registry requires the token in its published address. The plugin will not publish that token into a directory owned by another user or readable by other users. This token keeps unapproved clients from connecting; it does not hide runtime data from the agent that was given the MCP server. A configured `devToolsMcpPort` opens a separate socket on every interface without a token. Do not use a fixed port on a shared or untrusted network.
+An automatically discovered relay's registry record contains a random token. The MCP client uses it to sign a connection challenge and checks the relay's response before sending tool requests. The plugin refuses to publish the record if another user can read or replace the registry directory. The MCP server applies the same check before reading it. Both reject symlinks and junctions; on macOS they also check directory ACLs. Clients without access to the registry cannot connect, but the agent using this MCP server can inspect the Runtime data.
 
-On Windows, directory ownership cannot be verified, so automatic discovery is unavailable. Use `devToolsMcpPort` in the Vite config and set `FOLDKIT_DEVTOOLS_MCP_PORT` to the same port.
+On Windows, both processes use PowerShell to check the directory's owner, access list, ancestors, and reparse points. The registry must be a private direct child of the user's temporary directory. If the check cannot run or refuses the directory, configure `devToolsMcpPort` in Vite and set `FOLDKIT_DEVTOOLS_MCP_PORT` to the same port. A fixed port listens on every interface without a token. Do not use it on a shared or untrusted network.
 
 ## Notes
 
 - The MCP bridge shares its lifecycle with Foldkit DevTools. If you set `devTools: false` in your program config, the bridge does not start and the Runtime is invisible to MCP. The default enables the bridge in dev.
-- Without `Message` in your `DevToolsConfig`, dispatch is rejected. The other (read-only) tools still work.
+- External dispatch and Message Schema discovery require `devTools: { dispatch: true }`. The other tools still work with the default configuration.
 - The relay only runs at dev time. Production builds never include the relay or the bridge, regardless of any `show` setting.
 
 ## Documentation

package/dist/install.js

@@ -36,9 +36,9 @@ const printNextSteps = (alreadyRegistered) => {
     console.log('');
     console.log('Next steps:');
     console.log('');
-    console.log('  1. Pass your Message Schema to Runtime.makeApplication (enables dispatch):');
+    console.log('  1. Enable Message dispatch in Program.make or Program.makeElement:');
     console.log('');
-    console.log('       devTools: { Message }');
+    console.log('       devTools: { dispatch: true }');
     console.log('');
     console.log('  2. Start your dev server, then restart your AI agent (Claude Code, Cursor, etc.).');
     console.log('');

package/dist/relayClient.d.ts

@@ -0,0 +1,37 @@
+import { type Cause, Effect, Option } from 'effect';
+import { Request, type Response, type RuntimeInfo } from 'foldkit/devtools-protocol';
+import type { RelayTarget } from './relayLocation.js';
+export type ListedRuntime = Readonly<{
+    runtime: typeof RuntimeInfo.Type;
+    maybeProjectRoot: Option.Option<string>;
+}>;
+/**
+ * Connects MCP tool calls to the DevTools relays for a project.
+ *
+ * Each call checks the registry, connects to matching relays, and lists their
+ * Runtimes before routing a request. It closes connections to relays that are
+ * no longer published. Concurrent calls share one registry lookup. A dev server
+ * started or restarted after the previous call is reached on the next one.
+ *
+ * `listRuntimes` returns Runtimes from every connected relay, oldest dev server
+ * first. `sendRequest` uses the newest relay that lists the requested Runtime.
+ * Without an id, it uses the most recently connected Runtime of the most
+ * recently started dev server. An id that no relay lists returns an error
+ * without waiting for the request timeout.
+ *
+ * Cancelling one call leaves shared discovery available to other calls. `close`
+ * interrupts discovery, closes the relay connections, and fails pending
+ * requests.
+ */
+export type RelayClient = Readonly<{
+    listRuntimes: Effect.Effect<ReadonlyArray<ListedRuntime>, Error>;
+    sendRequest: (request: typeof Request.Type, maybeRuntimeId: Option.Option<string>) => Effect.Effect<typeof Response.Type, Cause.TimeoutError | Error>;
+    close: Effect.Effect<void>;
+}>;
+/**
+ * Returns an error message for display. Effect's `TimeoutError` has no
+ * `message`, so its string form is used instead.
+ */
+export declare const errorReason: (error: Error) => string;
+export declare const makeRelayClient: <Services>(resolveTargets: Effect.Effect<ReadonlyArray<RelayTarget>, never, Services>) => Effect.Effect<RelayClient, never, Services>;
+//# sourceMappingURL=relayClient.d.ts.map

package/dist/relayClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relayClient.d.ts","sourceRoot":"","sources":["../src/relayClient.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,KAAK,EAKV,MAAM,EAKN,MAAM,EASP,MAAM,QAAQ,CAAA;AACf,OAAO,EACL,OAAO,EAEP,KAAK,QAAQ,EAEb,KAAK,WAAW,EACjB,MAAM,2BAA2B,CAAA;AAIlC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAqDrD,MAAM,MAAM,aAAa,GAAG,QAAQ,CAAC;IACnC,OAAO,EAAE,OAAO,WAAW,CAAC,IAAI,CAAA;IAChC,gBAAgB,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;CACxC,CAAC,CAAA;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,WAAW,GAAG,QAAQ,CAAC;IACjC,YAAY,EAAE,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,aAAa,CAAC,EAAE,KAAK,CAAC,CAAA;IAChE,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;AAiBF;;;GAGG;AACH,eAAO,MAAM,WAAW,UAAW,KAAK,KAAG,MACe,CAAA;AA4H1D,eAAO,MAAM,eAAe,GAAI,QAAQ,kBACtB,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,WAAW,CAAC,EAAE,KAAK,EAAE,QAAQ,CAAC,KACzE,MAAM,CAAC,MAAM,CAAC,WAAW,EAAE,KAAK,EAAE,QAAQ,CAkTzC,CAAA"}

package/dist/relayClient.js

@@ -0,0 +1,276 @@
+import { Array, Console, Data, Deferred, Duration, Effect, Exit, HashMap, HashSet, Match, Option, Predicate, Ref, Result, Schema, Scope, Semaphore, String, pipe, } from 'effect';
+import { Request, RequestFrame, ResponseFrame, } from 'foldkit/devtools-protocol';
+import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+import { WebSocket } from 'ws';
+const REQUEST_TIMEOUT = Duration.seconds(10);
+const CONNECT_TIMEOUT = Duration.seconds(2);
+const LIST_RUNTIMES_TIMEOUT = Duration.seconds(2);
+const NOT_CONNECTED_REASON = 'Not connected to a Foldkit dev server. Start your Foldkit Vite dev server and retry the tool call.';
+const NO_RUNTIMES_REASON = 'No connected Foldkit runtimes. Open a Foldkit dev page and try again.';
+const INVALID_ADDRESS_REASON = 'the relay address is not a valid URL';
+const UNVERIFIED_RELAY_REASON = 'the relay could not prove its identity';
+const CLOSED_REASON = 'The Foldkit relay client is closed.';
+const RELAY_TOKEN_PARAMETER = 'token';
+const RELAY_CHALLENGE_HEADER = 'X-Foldkit-Relay-Challenge';
+const RELAY_CLIENT_PROOF_HEADER = 'X-Foldkit-Relay-Client-Proof';
+const RELAY_SERVER_PROOF_HEADER = 'x-foldkit-relay-server-proof';
+const RELAY_TOKEN_PATTERN = /^[0-9a-f]{64}$/;
+const RELAY_PROOF_PATTERN = /^[0-9a-f]{64}$/;
+const RELAY_CHALLENGE_BYTES = 32;
+const encodeRequestFrameToJson = Schema.encodeUnknownSync(Schema.fromJsonString(RequestFrame));
+const RefreshTurn = Data.taggedEnum();
+const generateRequestId = () => `req-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+const parseUrl = Option.liftThrowable((url) => new URL(url));
+const relayUrlForLog = (url) => Option.match(parseUrl(url), {
+    onNone: () => Array.headNonEmpty(String.split(url, '?')),
+    onSome: parsed => {
+        parsed.search = '';
+        return parsed.toString();
+    },
+});
+/**
+ * Returns an error message for display. Effect's `TimeoutError` has no
+ * `message`, so its string form is used instead.
+ */
+export const errorReason = (error) => error.message ? error.message : globalThis.String(error);
+const toError = (description) => (cause) => cause instanceof Error
+    ? cause
+    : new Error(`${description}: ${globalThis.String(cause)}`);
+const computeRelayProof = (token, role, challenge) => createHmac('sha256', token).update(`${role}:${challenge}`).digest('hex');
+const attemptOpen = (url) => Effect.suspend(() => Option.match(parseUrl(url), {
+    onNone: () => Effect.fail(new Error(INVALID_ADDRESS_REASON)),
+    onSome: parsedUrl => {
+        const maybeToken = Option.fromNullishOr(parsedUrl.searchParams.get(RELAY_TOKEN_PARAMETER));
+        if (Option.isSome(maybeToken) &&
+            !RELAY_TOKEN_PATTERN.test(maybeToken.value)) {
+            return Effect.fail(new Error(INVALID_ADDRESS_REASON));
+        }
+        const maybeChallenge = Option.map(maybeToken, () => randomBytes(RELAY_CHALLENGE_BYTES).toString('hex'));
+        parsedUrl.searchParams.delete(RELAY_TOKEN_PARAMETER);
+        return Effect.callback(resume => {
+            const constructed = Result.try({
+                try: () => Option.match(Option.all([maybeToken, maybeChallenge]), {
+                    onNone: () => new WebSocket(parsedUrl),
+                    onSome: ([token, challenge]) => new WebSocket(parsedUrl, {
+                        headers: {
+                            [RELAY_CHALLENGE_HEADER]: challenge,
+                            [RELAY_CLIENT_PROOF_HEADER]: computeRelayProof(token, 'client', challenge),
+                        },
+                    }),
+                }),
+                catch: toError('Failed to open a connection'),
+            });
+            if (Result.isFailure(constructed)) {
+                resume(Effect.fail(constructed.failure));
+                return;
+            }
+            const socket = constructed.success;
+            let isSettled = false;
+            let isVerified = Option.isNone(maybeToken);
+            socket.once('upgrade', response => {
+                if (Option.isNone(maybeToken) || Option.isNone(maybeChallenge)) {
+                    return;
+                }
+                const presented = response.headers[RELAY_SERVER_PROOF_HEADER];
+                const expected = Buffer.from(computeRelayProof(maybeToken.value, 'server', maybeChallenge.value), 'hex');
+                const isValidProof = Predicate.isString(presented) &&
+                    RELAY_PROOF_PATTERN.test(presented) &&
+                    timingSafeEqual(expected, Buffer.from(presented, 'hex'));
+                if (isValidProof) {
+                    isVerified = true;
+                }
+                else {
+                    isSettled = true;
+                    socket.terminate();
+                    resume(Effect.fail(new Error(UNVERIFIED_RELAY_REASON)));
+                }
+            });
+            socket.once('open', () => {
+                if (!isVerified) {
+                    isSettled = true;
+                    socket.terminate();
+                    resume(Effect.fail(new Error(UNVERIFIED_RELAY_REASON)));
+                    return;
+                }
+                isSettled = true;
+                resume(Effect.succeed(socket));
+            });
+            socket.on('error', error => {
+                if (!isSettled) {
+                    isSettled = true;
+                    resume(Effect.fail(error));
+                }
+            });
+            return Effect.sync(() => {
+                isSettled = true;
+                socket.terminate();
+            });
+        });
+    },
+}));
+const isOpen = ({ socket }) => socket.readyState === WebSocket.OPEN;
+export const makeRelayClient = (resolveTargets) => Effect.gen(function* () {
+    const pendingResponsesRef = yield* Ref.make(HashMap.empty());
+    const socketsRef = yield* Ref.make(HashMap.empty());
+    const refreshLock = yield* Semaphore.make(1);
+    const pendingRefreshRef = yield* Ref.make(Option.none());
+    const refreshScope = yield* Scope.make();
+    const closed = yield* Deferred.make();
+    const context = yield* Effect.context();
+    const attachHandlers = (socket) => {
+        socket.on('message', raw => {
+            Effect.runForkWith(context)(handleIncomingMessage(raw, pendingResponsesRef));
+        });
+        socket.on('error', error => {
+            console.error(`[foldkit-devtools-mcp] socket error: ${error.message}`);
+        });
+    };
+    const openTarget = (target) => Effect.uninterruptibleMask(restore => restore(attemptOpen(target.url).pipe(Effect.timeoutOrElse({
+        duration: CONNECT_TIMEOUT,
+        orElse: () => Effect.fail(new Error(`no connection within ${Duration.format(CONNECT_TIMEOUT)}`)),
+    }))).pipe(Effect.flatMap(socket => Effect.gen(function* () {
+        attachHandlers(socket);
+        yield* Ref.update(socketsRef, HashMap.set(target.key, { socket, target }));
+        yield* Console.error(`[foldkit-devtools-mcp] connected to ${relayUrlForLog(target.url)}`);
+    })))).pipe(Effect.catch(error => Console.error(`[foldkit-devtools-mcp] connect attempt to ${relayUrlForLog(target.url)} failed: ${errorReason(error)}`)));
+    const reconcile = Effect.gen(function* () {
+        if (yield* Deferred.isDone(closed)) {
+            return [];
+        }
+        const targets = yield* Effect.provideContext(resolveTargets, context);
+        const targetKeys = HashSet.fromIterable(Array.map(targets, ({ key }) => key));
+        const sockets = yield* Ref.get(socketsRef);
+        const isKept = (relaySocket, key) => HashSet.has(targetKeys, key) && isOpen(relaySocket);
+        const keptSockets = HashMap.filter(sockets, isKept);
+        const droppedSockets = HashMap.filter(sockets, (relaySocket, key) => !isKept(relaySocket, key));
+        yield* Effect.sync(() => {
+            for (const { socket } of HashMap.values(droppedSockets)) {
+                socket.terminate();
+            }
+        });
+        yield* Ref.set(socketsRef, keptSockets);
+        const missingTargets = Array.filter(targets, ({ key }) => !HashMap.has(keptSockets, key));
+        yield* Effect.forEach(missingTargets, openTarget, {
+            concurrency: 'unbounded',
+            discard: true,
+        });
+        const nextSockets = yield* Ref.get(socketsRef);
+        return pipe(targets, Array.reverse, Array.map(({ key }) => HashMap.get(nextSockets, key)), Array.getSomes);
+    });
+    const takeRefreshTurn = (ownRefresh) => Ref.modify(pendingRefreshRef, (maybePendingRefresh) => Option.match(maybePendingRefresh, {
+        onNone: () => [
+            RefreshTurn.Leader({ refresh: ownRefresh }),
+            Option.some(ownRefresh),
+        ],
+        onSome: refresh => [
+            RefreshTurn.Follower({ refresh }),
+            maybePendingRefresh,
+        ],
+    }));
+    const leadRefresh = (refresh) => Deferred.into(refreshLock.withPermits(1)(Effect.gen(function* () {
+        yield* Ref.set(pendingRefreshRef, Option.none());
+        return yield* reconcile;
+    })), refresh).pipe(Effect.asVoid);
+    const refreshRelays = Effect.uninterruptibleMask(restore => Effect.gen(function* () {
+        if (yield* Deferred.isDone(closed)) {
+            return [];
+        }
+        const ownRefresh = yield* Deferred.make();
+        const turn = yield* takeRefreshTurn(ownRefresh);
+        yield* Match.value(turn).pipe(Match.withReturnType(), Match.tagsExhaustive({
+            Leader: ({ refresh }) => Effect.forkIn(leadRefresh(refresh), refreshScope, {
+                startImmediately: true,
+            }).pipe(Effect.asVoid),
+            Follower: () => Effect.void,
+        }));
+        return yield* restore(Deferred.await(turn.refresh));
+    }));
+    const exchange = (socket, request, maybeConnectionId, timeout) => Effect.acquireUseRelease(Effect.gen(function* () {
+        if (yield* Deferred.isDone(closed)) {
+            return yield* Effect.fail(new Error(CLOSED_REASON));
+        }
+        const id = generateRequestId();
+        const deferred = yield* Deferred.make();
+        yield* Ref.update(pendingResponsesRef, HashMap.set(id, deferred));
+        return { id, deferred };
+    }), ({ id, deferred }) => {
+        const frame = {
+            id,
+            maybeConnectionId,
+            request,
+        };
+        return Effect.try({
+            try: () => socket.send(encodeRequestFrameToJson(frame)),
+            catch: toError('Failed to send request'),
+        }).pipe(Effect.andThen(Effect.raceFirst(Deferred.await(deferred).pipe(Effect.timeout(timeout)), Deferred.await(closed).pipe(Effect.andThen(Effect.fail(new Error(CLOSED_REASON)))))));
+    }, ({ id }) => Ref.update(pendingResponsesRef, HashMap.remove(id)));
+    const listRelayRuntimes = ({ socket, target, }) => exchange(socket, Request.RequestListRuntimes(), Option.none(), LIST_RUNTIMES_TIMEOUT).pipe(Effect.flatMap(response => Match.value(response).pipe(Match.withReturnType(), Match.tag('ResponseRuntimes', ({ runtimes }) => Effect.succeed(runtimes)), Match.tag('ResponseError', ({ reason }) => Effect.fail(new Error(reason))), Match.orElse(({ _tag }) => Effect.fail(new Error(`the relay answered ${_tag}`))))), Effect.catch(error => Console.error(`[foldkit-devtools-mcp] listing runtimes at ${relayUrlForLog(target.url)} failed: ${errorReason(error)}`).pipe(Effect.as([]))));
+    const listRelays = Effect.gen(function* () {
+        const relaySockets = yield* refreshRelays;
+        if (Array.isReadonlyArrayEmpty(relaySockets)) {
+            return yield* Effect.fail(new Error(NOT_CONNECTED_REASON));
+        }
+        return yield* Effect.forEach(relaySockets, relaySocket => Effect.map(listRelayRuntimes(relaySocket), runtimes => ({
+            relaySocket,
+            runtimes,
+        })), { concurrency: 'unbounded' });
+    });
+    const listRuntimes = Effect.map(listRelays, listings => Array.flatMap(listings, ({ relaySocket, runtimes }) => Array.map(runtimes, runtime => ({
+        runtime,
+        maybeProjectRoot: relaySocket.target.maybeProjectRoot,
+    }))));
+    const sendRequest = (request, maybeRuntimeId) => Effect.gen(function* () {
+        const listings = yield* listRelays;
+        const route = yield* routeFromListings(listings, maybeRuntimeId);
+        return yield* exchange(route.socket, request, Option.some(route.connectionId), REQUEST_TIMEOUT);
+    });
+    const close = Effect.uninterruptible(Effect.gen(function* () {
+        yield* Deferred.succeed(closed, undefined);
+        yield* Scope.close(refreshScope, Exit.void);
+        yield* refreshLock.withPermits(1)(Effect.gen(function* () {
+            const sockets = yield* Ref.getAndSet(socketsRef, HashMap.empty());
+            yield* Effect.sync(() => {
+                for (const { socket } of HashMap.values(sockets)) {
+                    socket.terminate();
+                }
+            });
+        }));
+    }));
+    const client = { listRuntimes, sendRequest, close };
+    return client;
+});
+const routeToRuntime = (listings, runtimeId) => Option.match(Array.findLast(listings, ({ runtimes }) => Array.some(runtimes, ({ connectionId }) => connectionId === runtimeId)), {
+    onNone: () => Effect.fail(new Error(`No connected Foldkit Runtime has the id ${runtimeId}. Call foldkit_list_runtimes for the current ids.`)),
+    onSome: ({ relaySocket }) => Effect.succeed({
+        socket: relaySocket.socket,
+        connectionId: runtimeId,
+    }),
+});
+const routeToDefaultRuntime = (listings) => Option.match(pipe(listings, Array.flatMap(({ relaySocket, runtimes }) => Array.map(runtimes, ({ connectionId }) => ({
+    socket: relaySocket.socket,
+    connectionId,
+}))), Array.last), {
+    onNone: () => Effect.fail(new Error(NO_RUNTIMES_REASON)),
+    onSome: Effect.succeed,
+});
+const routeFromListings = (listings, maybeRuntimeId) => Option.match(maybeRuntimeId, {
+    onNone: () => routeToDefaultRuntime(listings),
+    onSome: runtimeId => routeToRuntime(listings, runtimeId),
+});
+const handleIncomingMessage = (raw, pendingResponsesRef) => {
+    const decoded = Schema.decodeExit(Schema.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, {
+                onNone: () => Effect.void,
+                onSome: deferred => Effect.gen(function* () {
+                    yield* Ref.update(pendingResponsesRef, HashMap.remove(responseFrame.id));
+                    yield* Deferred.succeed(deferred, responseFrame.response);
+                }),
+            });
+        }),
+    });
+};

package/dist/relayLocation.d.ts

@@ -1,9 +1,17 @@
 import { Effect, Option } from 'effect';
+import type { ChildProcessSpawner } from 'effect/process';
+import { type RelayRegistryReader, type RelayRegistryServices } from './relayRegistry.js';
 export type Settings = Readonly<{
     maybeConfiguredPort: Option.Option<string>;
     maybeConfiguredHost: Option.Option<string>;
     projectRoot: string;
 }>;
+export type RelayTarget = Readonly<{
+    key: string;
+    url: string;
+    maybeProjectRoot: Option.Option<string>;
+}>;
 export declare const loadSettings: Effect.Effect<Settings>;
-export declare const resolveRelayUrl: (settings: Settings) => Effect.Effect<string, never, never> | Effect.Effect<string, never, import("./relayRegistry.js").RelayRegistryServices>;
+export declare const configuredRelayUrl: (settings: Settings) => Option.Option<string>;
+export declare const resolveRelayTargets: (settings: Settings, registryReader: RelayRegistryReader) => Effect.Effect<ReadonlyArray<RelayTarget>, never, RelayRegistryServices | ChildProcessSpawner.ChildProcessSpawner>;
 //# sourceMappingURL=relayLocation.d.ts.map

package/dist/relayLocation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"relayLocation.d.ts","sourceRoot":"","sources":["../src/relayLocation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAU,MAAM,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAO/C,MAAM,MAAM,QAAQ,GAAG,QAAQ,CAAC;IAC9B,mBAAmB,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;IAC1C,mBAAmB,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;IAC1C,WAAW,EAAE,MAAM,CAAA;CACpB,CAAC,CAAA;AAEF,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,MAAM,CAAC,QAAQ,CAe5B,CAAA;AAkBrB,eAAO,MAAM,eAAe,aAAc,QAAQ,2HAmBjD,CAAA"}
+{"version":3,"file":"relayLocation.d.ts","sourceRoot":"","sources":["../src/relayLocation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,MAAM,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AACtD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAA;AAGzD,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,EAE3B,MAAM,oBAAoB,CAAA;AAS3B,MAAM,MAAM,QAAQ,GAAG,QAAQ,CAAC;IAC9B,mBAAmB,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;IAC1C,mBAAmB,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;IAC1C,WAAW,EAAE,MAAM,CAAA;CACpB,CAAC,CAAA;AAEF,MAAM,MAAM,WAAW,GAAG,QAAQ,CAAC;IACjC,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;IACX,gBAAgB,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;CACxC,CAAC,CAAA;AAEF,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,MAAM,CAAC,QAAQ,CAe5B,CAAA;AAmDrB,eAAO,MAAM,kBAAkB,aACnB,QAAQ,KACjB,MAAM,CAAC,MAAM,CAAC,MAAM,CAiBtB,CAAA;AAED,eAAO,MAAM,mBAAmB,aACpB,QAAQ,kBACF,mBAAmB,KAClC,MAAM,CAAC,MAAM,CACd,aAAa,CAAC,WAAW,CAAC,EAC1B,KAAK,EACL,qBAAqB,GAAG,mBAAmB,CAAC,mBAAmB,CAmB7D,CAAA"}

package/dist/relayLocation.js

@@ -1,7 +1,12 @@
-import { Config, Effect, Option } from 'effect';
-import { discoverRelay } from './relayRegistry.js';
+import { Array, Config, Effect, Option } from 'effect';
+import { isIPv6 } from 'node:net';
+import { discoverRelays, } from './relayRegistry.js';
 const LEGACY_DEFAULT_PORT = 9988;
 const DEFAULT_HOST = 'localhost';
+const AUTOMATIC_RELAY_HOST = '127.0.0.1';
+const AUTOMATIC_RELAY_PATH = '/__foldkit/devtools-mcp';
+const RELAY_TOKEN_PARAMETER = 'token';
+const RELAY_TOKEN_PATTERN = /^[0-9a-f]{64}$/;
 export const loadSettings = Effect.gen(function* () {
     const maybeConfiguredPort = yield* Config.option(Config.String('FOLDKIT_DEVTOOLS_MCP_PORT'));
     const maybeConfiguredHost = yield* Config.option(Config.String('FOLDKIT_DEVTOOLS_MCP_HOST'));
@@ -12,22 +17,55 @@ export const loadSettings = Effect.gen(function* () {
         projectRoot: Option.getOrElse(maybeProjectRoot, () => process.cwd()),
     };
 }).pipe(Effect.orDie);
-const relayUrl = (host, port) => `ws://${host}:${port}`;
-const withConfiguredHost = (maybeConfiguredHost, url) => Option.match(maybeConfiguredHost, {
-    onNone: () => url,
-    onSome: host => {
-        const parsed = new URL(url);
-        parsed.hostname = host;
-        return parsed.toString();
-    },
+const urlHost = (host) => (isIPv6(host) ? `[${host}]` : host);
+const relayUrl = (host, port) => `ws://${urlHost(host)}:${port}`;
+const fixedTarget = (url) => ({
+    key: url,
+    url,
+    maybeProjectRoot: Option.none(),
 });
-export const resolveRelayUrl = (settings) => {
-    const configuredHost = Option.getOrElse(settings.maybeConfiguredHost, () => DEFAULT_HOST);
-    return Option.match(settings.maybeConfiguredPort, {
-        onSome: port => Effect.succeed(relayUrl(configuredHost, port)),
-        onNone: () => discoverRelay(settings.projectRoot).pipe(Effect.map(maybeRecord => Option.match(maybeRecord, {
-            onSome: record => withConfiguredHost(settings.maybeConfiguredHost, record.url),
-            onNone: () => relayUrl(configuredHost, LEGACY_DEFAULT_PORT),
-        }))),
-    });
+const parseUrl = Option.liftThrowable((url) => new URL(url));
+const hasValidPort = (url) => {
+    const port = globalThis.Number(url.port);
+    return (url.port !== '' &&
+        globalThis.Number.isInteger(port) &&
+        port > 0 &&
+        port <= 65_535);
 };
+const isPublishedRelayUrl = (value) => Option.exists(parseUrl(value), url => {
+    if (url.protocol !== 'ws:' ||
+        url.username !== '' ||
+        url.password !== '' ||
+        url.hash !== '' ||
+        !hasValidPort(url)) {
+        return false;
+    }
+    const parameters = Array.fromIterable(url.searchParams);
+    return (url.hostname === AUTOMATIC_RELAY_HOST &&
+        url.pathname === AUTOMATIC_RELAY_PATH &&
+        Array.length(parameters) === 1 &&
+        Option.exists(Array.head(parameters), ([name, token]) => name === RELAY_TOKEN_PARAMETER && RELAY_TOKEN_PATTERN.test(token)));
+});
+export const configuredRelayUrl = (settings) => {
+    const { maybeConfiguredHost, maybeConfiguredPort } = settings;
+    if (Option.isSome(maybeConfiguredHost) ||
+        Option.isSome(maybeConfiguredPort)) {
+        const host = Option.getOrElse(maybeConfiguredHost, () => DEFAULT_HOST);
+        const port = Option.getOrElse(maybeConfiguredPort, () => LEGACY_DEFAULT_PORT);
+        return Option.some(relayUrl(host, port));
+    }
+    else {
+        return Option.none();
+    }
+};
+export const resolveRelayTargets = (settings, registryReader) => Option.match(configuredRelayUrl(settings), {
+    onSome: url => Effect.succeed([fixedTarget(url)]),
+    onNone: () => Effect.map(discoverRelays(settings.projectRoot, registryReader), records => {
+        const trustedRecords = Array.filter(records, record => isPublishedRelayUrl(record.url));
+        return Array.map(trustedRecords, (record) => ({
+            key: record.id,
+            url: record.url,
+            maybeProjectRoot: Option.some(record.root),
+        }));
+    }),
+});