@foldkit/devtools-mcp 0.24.1-canary.2eb97fb142a1 → 0.24.1-canary.396b19976386

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,10 +36,10 @@ 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:
+Pass your `Message` Schema as `devTools.Message` when calling the Application Composition's owned `assembleApplication` method to let the agent dispatch Messages. The Runtime rejects a payload that does not match the Schema before it reaches update:
 
 ```typescript
-Runtime.makeApplication({
+ApplicationComposition.assembleApplication({
   devTools: {
     // Rest of your DevTools config
     Message,
@@ -61,16 +61,16 @@ Keep API keys, passwords, access and refresh tokens, authorization headers, sess
 
 ## Tools
 
-Each tool accepts an optional `runtime_id`. When omitted, the most recently connected Runtime is used.
+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. Agents call this first to discover which Runtime to target.                                                                                                                                                                                                                                                                                                                                                                                             |
+| `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 Submodel chain. Filter server-side with `changed_paths_match`, read the latest entries with `from_end`, and paginate forward with `since_index`.                                                                 |
+| `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.                                                                                                                                                                                                                                                   |
@@ -102,25 +102,27 @@ 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.
 
 ## 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`.
 
-| 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. |
+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.
 
-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.
+| 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. |
 
-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.
+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, 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
 

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. Pass the complete Message Codec to ApplicationComposition.assembleApplication (enables dispatch):');
     console.log('');
-    console.log('       devTools: { Message }');
+    console.log('       devTools: { Message: ApplicationComposition.Message }');
     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),
+        }));
+    }),
+});

package/dist/relayRegistry.d.ts

@@ -1,5 +1,15 @@
-import { Effect, FileSystem, Option, Path } from 'effect';
+import { Effect, FileSystem, HashSet, Path, Ref } from 'effect';
+import type { ChildProcessSpawner } from 'effect/process';
 import { RelayRecord } from 'foldkit/devtools-protocol';
+import { type RelayRegistryTrust } from './relayRegistryTrust.js';
 export type RelayRegistryServices = FileSystem.FileSystem | Path.Path;
-export declare const discoverRelay: (projectRoot: string) => Effect.Effect<Option.Option<RelayRecord>, never, RelayRegistryServices>;
+export type RelayRegistryReader = Readonly<{
+    trust: RelayRegistryTrust;
+    reportedRefusals: Ref.Ref<HashSet.HashSet<string>>;
+}>;
+type RootPathApi = Pick<Path.Path, 'isAbsolute' | 'relative' | 'sep'>;
+export declare const isWithinRoot: (root: string, candidate: string, pathApi: RootPathApi) => boolean;
+export declare const makeRelayRegistryReader: Effect.Effect<RelayRegistryReader>;
+export declare const discoverRelays: (projectRoot: string, registryReader: RelayRegistryReader) => Effect.Effect<ReadonlyArray<RelayRecord>, never, RelayRegistryServices | ChildProcessSpawner.ChildProcessSpawner>;
+export {};
 //# sourceMappingURL=relayRegistry.d.ts.map

package/dist/relayRegistry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"relayRegistry.d.ts","sourceRoot":"","sources":["../src/relayRegistry.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,MAAM,EACN,UAAU,EACV,MAAM,EAEN,IAAI,EAIL,MAAM,QAAQ,CAAA;AACf,OAAO,EAGL,WAAW,EACZ,MAAM,2BAA2B,CAAA;AAOlC,MAAM,MAAM,qBAAqB,GAAG,UAAU,CAAC,UAAU,GAAG,IAAI,CAAC,IAAI,CAAA;AA4FrE,eAAO,MAAM,aAAa,gBACX,MAAM,KAClB,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,EAAE,KAAK,EAAE,qBAAqB,CAoCrE,CAAA"}
+{"version":3,"file":"relayRegistry.d.ts","sourceRoot":"","sources":["../src/relayRegistry.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,MAAM,EACN,UAAU,EACV,OAAO,EAGP,IAAI,EACJ,GAAG,EAIJ,MAAM,QAAQ,CAAA;AACf,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAA;AACzD,OAAO,EAGL,WAAW,EACZ,MAAM,2BAA2B,CAAA;AAGlC,OAAO,EACL,KAAK,kBAAkB,EAExB,MAAM,yBAAyB,CAAA;AAMhC,MAAM,MAAM,qBAAqB,GAAG,UAAU,CAAC,UAAU,GAAG,IAAI,CAAC,IAAI,CAAA;AAErE,MAAM,MAAM,mBAAmB,GAAG,QAAQ,CAAC;IACzC,KAAK,EAAE,kBAAkB,CAAA;IACzB,gBAAgB,EAAE,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAA;CACnD,CAAC,CAAA;AAEF,KAAK,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,YAAY,GAAG,UAAU,GAAG,KAAK,CAAC,CAAA;AA8FrE,eAAO,MAAM,YAAY,SACjB,MAAM,aACD,MAAM,WACR,WAAW,KACnB,OASF,CAAA;AAED,eAAO,MAAM,uBAAuB,EAAE,MAAM,CAAC,MAAM,CAAC,mBAAmB,CASnE,CAAA;AAwEJ,eAAO,MAAM,cAAc,gBACZ,MAAM,kBACH,mBAAmB,KAClC,MAAM,CAAC,MAAM,CACd,aAAa,CAAC,WAAW,CAAC,EAC1B,KAAK,EACL,qBAAqB,GAAG,mBAAmB,CAAC,mBAAmB,CAqD7D,CAAA"}