frontmcp 1.2.1 → 1.3.0

package/src/commands/dev/bridge/stdio-framer.js

@@ -0,0 +1,128 @@
+"use strict";
+/**
+ * Newline-delimited JSON-RPC framer for the dev bridge (issue #399).
+ *
+ * Reads `process.stdin` and yields complete JSON-RPC frames. Writes
+ * complete frames to `process.stdout` (atomic per `\n` boundary). Parser
+ * state is preserved across chunks so frames split arbitrarily on the
+ * wire still parse.
+ *
+ * MCP stdio framing per spec is newline-delimited JSON (`\n`-terminated
+ * UTF-8). We do NOT implement LSP-style `Content-Length` framing — it's
+ * not in the MCP spec and adding it would silently shadow real JSON
+ * bodies that happen to start with `C`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createStdioFramer = createStdioFramer;
+const errors_1 = require("./errors");
+/**
+ * Build a newline-delimited JSON framer bound to the supplied streams.
+ *
+ * Parse errors (malformed JSON between newlines) emit a `-32700` Parse
+ * error response back on the output stream and continue — a malformed
+ * frame must not kill the bridge.
+ */
+function createStdioFramer(options) {
+    const { input, output, log, onFrame } = options;
+    let buffer = '';
+    // True while `output.write` is signalling backpressure. Read by `onData`
+    // to pause the inbound stream so we don't keep buffering frames when the
+    // outbound side can't keep up.
+    let paused = false;
+    let drainResolvers = [];
+    function flushBuffer() {
+        let nl;
+        while ((nl = buffer.indexOf('\n')) >= 0) {
+            const raw = buffer.slice(0, nl).replace(/\r$/, '');
+            buffer = buffer.slice(nl + 1);
+            if (raw.length === 0)
+                continue;
+            let parsed;
+            try {
+                parsed = JSON.parse(raw);
+            }
+            catch (err) {
+                log.warn('parse-error', { raw: raw.slice(0, 200), error: err.message });
+                // `makeDevError` returns a strict JSON-RPC error shape that
+                // structurally satisfies `JsonRpcFrame`; the dev bridge owns both
+                // sides of this constructor, so write() trusts the payload.
+                void write((0, errors_1.makeDevError)(null, -32700, { reason: 'parse_error' }));
+                continue;
+            }
+            if (!parsed || typeof parsed !== 'object') {
+                // Per JSON-RPC 2.0, every frame must be an object. A bare `42` or
+                // `"string"` line is just as invalid as garbage JSON — emit the
+                // same -32700 envelope so the client doesn't get inconsistent
+                // behaviour depending on whether the parser stage or the shape
+                // check rejected the input.
+                log.warn('parse-error', { raw: raw.slice(0, 200), reason: 'not_object' });
+                void write((0, errors_1.makeDevError)(null, -32700, { reason: 'not_object' }));
+                continue;
+            }
+            // Don't drop the onFrame promise. `onFrame` is user-supplied (the
+            // state machine in the production wiring) and can reject — if we
+            // void the rejection, Node bubbles it as an unhandledRejection and
+            // crashes the bridge. Funnel it through the logger instead.
+            void Promise.resolve(onFrame(parsed)).catch((err) => {
+                log.error('on-frame-error', {
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            });
+        }
+    }
+    function onData(chunk) {
+        buffer += typeof chunk === 'string' ? chunk : chunk.toString('utf-8');
+        flushBuffer();
+    }
+    function write(frame) {
+        return new Promise((resolve) => {
+            const line = JSON.stringify(frame) + '\n';
+            const ok = output.write(line);
+            if (ok)
+                return resolve();
+            // Backpressure: pause inbound parsing AND the input stream so we
+            // stop accumulating frames in `buffer` until drain. `input.pause()`
+            // is a no-op on streams that don't support flow-mode pausing.
+            if (!paused) {
+                paused = true;
+                input.pause?.();
+            }
+            drainResolvers.push(resolve);
+        });
+    }
+    function onDrain() {
+        if (paused) {
+            paused = false;
+            input.resume?.();
+        }
+        const resolvers = drainResolvers;
+        drainResolvers = [];
+        for (const r of resolvers)
+            r();
+    }
+    return {
+        start: () => {
+            input.setEncoding?.('utf-8');
+            input.on('data', onData);
+            output.on('drain', onDrain);
+        },
+        write,
+        stop: () => {
+            input.off('data', onData);
+            output.off('drain', onDrain);
+            // Settle any queued write() promises so callers blocked on
+            // backpressure don't hang past shutdown. Resume the input stream
+            // symmetrically (we may have paused it on backpressure) so the
+            // caller doesn't inherit a paused stdin.
+            if (paused) {
+                paused = false;
+                input.resume?.();
+            }
+            const resolvers = drainResolvers;
+            drainResolvers = [];
+            for (const r of resolvers)
+                r();
+        },
+    };
+}
+//# sourceMappingURL=stdio-framer.js.map

package/src/commands/dev/bridge/stdio-framer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdio-framer.js","sourceRoot":"","sources":["../../../../../src/commands/dev/bridge/stdio-framer.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Newline-delimited JSON-RPC framer for the dev bridge (issue #399).\n *\n * Reads `process.stdin` and yields complete JSON-RPC frames. Writes\n * complete frames to `process.stdout` (atomic per `\\n` boundary). Parser\n * state is preserved across chunks so frames split arbitrarily on the\n * wire still parse.\n *\n * MCP stdio framing per spec is newline-delimited JSON (`\\n`-terminated\n * UTF-8). We do NOT implement LSP-style `Content-Length` framing — it's\n * not in the MCP spec and adding it would silently shadow real JSON\n * bodies that happen to start with `C`.\n */\n\nimport type { Readable, Writable } from 'node:stream';\n\nimport { makeDevError } from './errors';\nimport type { BridgeLogger } from './log';\n\nexport interface JsonRpcFrame {\n  jsonrpc: '2.0';\n  id?: string | number | null;\n  method?: string;\n  params?: unknown;\n  result?: unknown;\n  error?: { code: number; message: string; data?: unknown };\n}\n\nexport interface StdioFramerOptions {\n  input: Readable;\n  output: Writable;\n  log: BridgeLogger;\n  onFrame: (frame: JsonRpcFrame) => void | Promise<void>;\n}\n\nexport interface StdioFramer {\n  start(): void;\n  /** Write a single frame as a newline-terminated JSON line. Resolves on `'drain'` when backpressure kicks in. */\n  write(frame: JsonRpcFrame): Promise<void>;\n  stop(): void;\n}\n\n/**\n * Build a newline-delimited JSON framer bound to the supplied streams.\n *\n * Parse errors (malformed JSON between newlines) emit a `-32700` Parse\n * error response back on the output stream and continue — a malformed\n * frame must not kill the bridge.\n */\nexport function createStdioFramer(options: StdioFramerOptions): StdioFramer {\n  const { input, output, log, onFrame } = options;\n  let buffer = '';\n  // True while `output.write` is signalling backpressure. Read by `onData`\n  // to pause the inbound stream so we don't keep buffering frames when the\n  // outbound side can't keep up.\n  let paused = false;\n  let drainResolvers: Array<() => void> = [];\n\n  function flushBuffer(): void {\n    let nl: number;\n    while ((nl = buffer.indexOf('\\n')) >= 0) {\n      const raw = buffer.slice(0, nl).replace(/\\r$/, '');\n      buffer = buffer.slice(nl + 1);\n      if (raw.length === 0) continue;\n      let parsed: unknown;\n      try {\n        parsed = JSON.parse(raw);\n      } catch (err) {\n        log.warn('parse-error', { raw: raw.slice(0, 200), error: (err as Error).message });\n        // `makeDevError` returns a strict JSON-RPC error shape that\n        // structurally satisfies `JsonRpcFrame`; the dev bridge owns both\n        // sides of this constructor, so write() trusts the payload.\n        void write(makeDevError(null, -32700, { reason: 'parse_error' }));\n        continue;\n      }\n      if (!parsed || typeof parsed !== 'object') {\n        // Per JSON-RPC 2.0, every frame must be an object. A bare `42` or\n        // `\"string\"` line is just as invalid as garbage JSON — emit the\n        // same -32700 envelope so the client doesn't get inconsistent\n        // behaviour depending on whether the parser stage or the shape\n        // check rejected the input.\n        log.warn('parse-error', { raw: raw.slice(0, 200), reason: 'not_object' });\n        void write(makeDevError(null, -32700, { reason: 'not_object' }));\n        continue;\n      }\n      // Don't drop the onFrame promise. `onFrame` is user-supplied (the\n      // state machine in the production wiring) and can reject — if we\n      // void the rejection, Node bubbles it as an unhandledRejection and\n      // crashes the bridge. Funnel it through the logger instead.\n      void Promise.resolve(onFrame(parsed as JsonRpcFrame)).catch((err: unknown) => {\n        log.error('on-frame-error', {\n          error: err instanceof Error ? err.message : String(err),\n        });\n      });\n    }\n  }\n\n  function onData(chunk: Buffer | string): void {\n    buffer += typeof chunk === 'string' ? chunk : chunk.toString('utf-8');\n    flushBuffer();\n  }\n\n  function write(frame: JsonRpcFrame): Promise<void> {\n    return new Promise<void>((resolve) => {\n      const line = JSON.stringify(frame) + '\\n';\n      const ok = output.write(line);\n      if (ok) return resolve();\n      // Backpressure: pause inbound parsing AND the input stream so we\n      // stop accumulating frames in `buffer` until drain. `input.pause()`\n      // is a no-op on streams that don't support flow-mode pausing.\n      if (!paused) {\n        paused = true;\n        input.pause?.();\n      }\n      drainResolvers.push(resolve);\n    });\n  }\n\n  function onDrain(): void {\n    if (paused) {\n      paused = false;\n      input.resume?.();\n    }\n    const resolvers = drainResolvers;\n    drainResolvers = [];\n    for (const r of resolvers) r();\n  }\n\n  return {\n    start: () => {\n      input.setEncoding?.('utf-8');\n      input.on('data', onData);\n      output.on('drain', onDrain);\n    },\n    write,\n    stop: () => {\n      input.off('data', onData);\n      output.off('drain', onDrain);\n      // Settle any queued write() promises so callers blocked on\n      // backpressure don't hang past shutdown. Resume the input stream\n      // symmetrically (we may have paused it on backpressure) so the\n      // caller doesn't inherit a paused stdin.\n      if (paused) {\n        paused = false;\n        input.resume?.();\n      }\n      const resolvers = drainResolvers;\n      drainResolvers = [];\n      for (const r of resolvers) r();\n    },\n  };\n}\n"]}

package/src/commands/dev/bridge/upstream-client.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Upstream MCP client for the dev bridge (issue #399).
+ *
+ * Two transport variants:
+ *
+ *   - **HTTP mode**: speaks streamable-HTTP JSON-RPC to the child's HTTP
+ *     listener at `http://127.0.0.1:<port>/`. Carries the bridge-pinned
+ *     `mcp-session-id` header on every request so session continuity
+ *     survives reload.
+ *
+ *   - **Pipe mode (--serve)**: writes/reads newline-delimited JSON-RPC
+ *     frames on a pair of FDs paired with the child via `child_process`
+ *     IPC. The child opens these FDs because `FRONTMCP_DEV_STDIO_FD` is
+ *     set; the bridge writes requests, reads responses, no HTTP layer.
+ */
+import type { ChildProcess } from 'node:child_process';
+import type { BridgeLogger } from './log';
+import type { JsonRpcFrame } from './stdio-framer';
+export interface UpstreamClient {
+    send(frame: JsonRpcFrame): Promise<void>;
+    /** Stop background tasks (SSE listener, pipe parser). */
+    close(): Promise<void>;
+}
+export interface UpstreamClientOptions {
+    log: BridgeLogger;
+    /** Called for every frame the upstream child sends back. */
+    onFrame: (frame: JsonRpcFrame) => void | Promise<void>;
+    /** Session id pinned by the bridge for HTTP mode. */
+    sessionId?: string;
+}
+export interface HttpUpstreamOptions extends UpstreamClientOptions {
+    /** Loopback URL of the user-code HTTP server. */
+    url: string;
+}
+export declare function createHttpUpstream(options: HttpUpstreamOptions): UpstreamClient;
+export interface PipeUpstreamOptions extends UpstreamClientOptions {
+    /** The forked child; we write to / read from the IPC pipe (FD 3). */
+    child: ChildProcess;
+}
+/**
+ * Pipe mode: the child speaks JSON-RPC on FD 3 (set via
+ * `FRONTMCP_DEV_STDIO_FD=3`). We use Node's IPC channel for the same wire
+ * — `child.send(...)` forwards a structured message and `child.on('message', …)`
+ * yields whatever the child writes back.
+ *
+ * (Node's IPC wraps JSON over a pipe internally; the framing is consistent
+ * with what `runStdio` would write if it were pointed at FD 3.)
+ */
+export declare function createPipeUpstream(options: PipeUpstreamOptions): UpstreamClient;

package/src/commands/dev/bridge/upstream-client.js

@@ -0,0 +1,159 @@
+"use strict";
+/**
+ * Upstream MCP client for the dev bridge (issue #399).
+ *
+ * Two transport variants:
+ *
+ *   - **HTTP mode**: speaks streamable-HTTP JSON-RPC to the child's HTTP
+ *     listener at `http://127.0.0.1:<port>/`. Carries the bridge-pinned
+ *     `mcp-session-id` header on every request so session continuity
+ *     survives reload.
+ *
+ *   - **Pipe mode (--serve)**: writes/reads newline-delimited JSON-RPC
+ *     frames on a pair of FDs paired with the child via `child_process`
+ *     IPC. The child opens these FDs because `FRONTMCP_DEV_STDIO_FD` is
+ *     set; the bridge writes requests, reads responses, no HTTP layer.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createHttpUpstream = createHttpUpstream;
+exports.createPipeUpstream = createPipeUpstream;
+function createHttpUpstream(options) {
+    const { log, url, onFrame, sessionId } = options;
+    // Track every in-flight request — `close()` must abort all of them,
+    // not just whichever happened to be assigned last. A shared scalar
+    // would let concurrent sends clobber each other's controller.
+    const abortControllers = new Set();
+    async function send(frame) {
+        const abortController = new AbortController();
+        abortControllers.add(abortController);
+        const signal = abortController.signal;
+        try {
+            const headers = {
+                'content-type': 'application/json',
+                accept: 'application/json, text/event-stream',
+            };
+            if (sessionId)
+                headers['mcp-session-id'] = sessionId;
+            const res = await fetch(url, {
+                method: 'POST',
+                headers,
+                body: JSON.stringify(frame),
+                signal,
+            });
+            if (!res.ok) {
+                // Reject so the FSM can clear inflight bookkeeping and synthesise
+                // a JSON-RPC error response back to the client. Silently swallowing
+                // a non-OK status here leaves callers hanging.
+                log.warn('http-upstream-non-ok', { status: res.status, method: frame.method });
+                throw new Error(`upstream returned ${res.status} for ${frame.method ?? 'request'}`);
+            }
+            const contentType = res.headers.get('content-type') ?? '';
+            if (contentType.includes('text/event-stream')) {
+                // SSE: parse `data: <json>` lines until the stream ends, forward each.
+                const reader = res.body?.getReader();
+                if (!reader)
+                    return;
+                const decoder = new TextDecoder();
+                let buffer = '';
+                while (true) {
+                    const { done, value } = await reader.read();
+                    if (done)
+                        break;
+                    buffer += decoder.decode(value, { stream: true });
+                    let nl;
+                    while ((nl = buffer.indexOf('\n')) >= 0) {
+                        const line = buffer.slice(0, nl).trim();
+                        buffer = buffer.slice(nl + 1);
+                        if (!line.startsWith('data:'))
+                            continue;
+                        const json = line.slice(5).trim();
+                        if (!json)
+                            continue;
+                        try {
+                            const parsed = JSON.parse(json);
+                            await onFrame(parsed);
+                        }
+                        catch (err) {
+                            log.warn('sse-parse-error', { error: err.message, raw: json.slice(0, 200) });
+                        }
+                    }
+                }
+            }
+            else {
+                // Single JSON response.
+                const body = (await res.json());
+                await onFrame(body);
+            }
+        }
+        catch (err) {
+            // AbortError surfaces when close() interrupts an in-flight request
+            // during reload; that's expected, so log it at info-not-error. We
+            // still rethrow so the FSM can clear inflight bookkeeping and
+            // synthesise an error response on its end.
+            if (err.name === 'AbortError') {
+                log.info('http-upstream-aborted', { method: frame.method });
+            }
+            else {
+                log.error('http-upstream-error', { error: err.message, method: frame.method });
+            }
+            throw err;
+        }
+        finally {
+            abortControllers.delete(abortController);
+        }
+    }
+    return {
+        send,
+        close: async () => {
+            for (const ac of abortControllers)
+                ac.abort();
+            abortControllers.clear();
+        },
+    };
+}
+/**
+ * Pipe mode: the child speaks JSON-RPC on FD 3 (set via
+ * `FRONTMCP_DEV_STDIO_FD=3`). We use Node's IPC channel for the same wire
+ * — `child.send(...)` forwards a structured message and `child.on('message', …)`
+ * yields whatever the child writes back.
+ *
+ * (Node's IPC wraps JSON over a pipe internally; the framing is consistent
+ * with what `runStdio` would write if it were pointed at FD 3.)
+ */
+function createPipeUpstream(options) {
+    const { log, child, onFrame } = options;
+    function handleMessage(msg) {
+        if (!msg || typeof msg !== 'object') {
+            log.warn('pipe-upstream-non-object', { type: typeof msg });
+            return;
+        }
+        void onFrame(msg);
+    }
+    child.on('message', handleMessage);
+    async function send(frame) {
+        if (!child.connected) {
+            log.warn('pipe-upstream-disconnected', { method: frame.method });
+            throw new Error(`pipe upstream disconnected for ${frame.method ?? 'request'}`);
+        }
+        await new Promise((resolve, reject) => {
+            child.send(frame, (err) => {
+                if (err)
+                    reject(err);
+                else
+                    resolve();
+            });
+        }).catch((err) => {
+            // Reject so the FSM can produce a JSON-RPC error response back to
+            // the client rather than leaving the request stuck inflight.
+            log.warn('pipe-upstream-send-error', { error: err.message, method: frame.method });
+            throw err;
+        });
+    }
+    return {
+        send,
+        close: async () => {
+            child.off('message', handleMessage);
+        },
+    };
+}
+//# sourceMappingURL=upstream-client.js.map

package/src/commands/dev/bridge/upstream-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"upstream-client.js","sourceRoot":"","sources":["../../../../../src/commands/dev/bridge/upstream-client.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Upstream MCP client for the dev bridge (issue #399).\n *\n * Two transport variants:\n *\n *   - **HTTP mode**: speaks streamable-HTTP JSON-RPC to the child's HTTP\n *     listener at `http://127.0.0.1:<port>/`. Carries the bridge-pinned\n *     `mcp-session-id` header on every request so session continuity\n *     survives reload.\n *\n *   - **Pipe mode (--serve)**: writes/reads newline-delimited JSON-RPC\n *     frames on a pair of FDs paired with the child via `child_process`\n *     IPC. The child opens these FDs because `FRONTMCP_DEV_STDIO_FD` is\n *     set; the bridge writes requests, reads responses, no HTTP layer.\n */\n\nimport type { ChildProcess } from 'node:child_process';\n\nimport type { BridgeLogger } from './log';\nimport type { JsonRpcFrame } from './stdio-framer';\n\nexport interface UpstreamClient {\n  send(frame: JsonRpcFrame): Promise<void>;\n  /** Stop background tasks (SSE listener, pipe parser). */\n  close(): Promise<void>;\n}\n\nexport interface UpstreamClientOptions {\n  log: BridgeLogger;\n  /** Called for every frame the upstream child sends back. */\n  onFrame: (frame: JsonRpcFrame) => void | Promise<void>;\n  /** Session id pinned by the bridge for HTTP mode. */\n  sessionId?: string;\n}\n\n// ─── HTTP mode ──────────────────────────────────────────────────────────\n\nexport interface HttpUpstreamOptions extends UpstreamClientOptions {\n  /** Loopback URL of the user-code HTTP server. */\n  url: string;\n}\n\nexport function createHttpUpstream(options: HttpUpstreamOptions): UpstreamClient {\n  const { log, url, onFrame, sessionId } = options;\n  // Track every in-flight request — `close()` must abort all of them,\n  // not just whichever happened to be assigned last. A shared scalar\n  // would let concurrent sends clobber each other's controller.\n  const abortControllers = new Set<AbortController>();\n\n  async function send(frame: JsonRpcFrame): Promise<void> {\n    const abortController = new AbortController();\n    abortControllers.add(abortController);\n    const signal = abortController.signal;\n    try {\n      const headers: Record<string, string> = {\n        'content-type': 'application/json',\n        accept: 'application/json, text/event-stream',\n      };\n      if (sessionId) headers['mcp-session-id'] = sessionId;\n\n      const res = await fetch(url, {\n        method: 'POST',\n        headers,\n        body: JSON.stringify(frame),\n        signal,\n      });\n\n      if (!res.ok) {\n        // Reject so the FSM can clear inflight bookkeeping and synthesise\n        // a JSON-RPC error response back to the client. Silently swallowing\n        // a non-OK status here leaves callers hanging.\n        log.warn('http-upstream-non-ok', { status: res.status, method: frame.method });\n        throw new Error(`upstream returned ${res.status} for ${frame.method ?? 'request'}`);\n      }\n\n      const contentType = res.headers.get('content-type') ?? '';\n      if (contentType.includes('text/event-stream')) {\n        // SSE: parse `data: <json>` lines until the stream ends, forward each.\n        const reader = res.body?.getReader();\n        if (!reader) return;\n        const decoder = new TextDecoder();\n        let buffer = '';\n        while (true) {\n          const { done, value } = await reader.read();\n          if (done) break;\n          buffer += decoder.decode(value, { stream: true });\n          let nl: number;\n          while ((nl = buffer.indexOf('\\n')) >= 0) {\n            const line = buffer.slice(0, nl).trim();\n            buffer = buffer.slice(nl + 1);\n            if (!line.startsWith('data:')) continue;\n            const json = line.slice(5).trim();\n            if (!json) continue;\n            try {\n              const parsed = JSON.parse(json) as JsonRpcFrame;\n              await onFrame(parsed);\n            } catch (err) {\n              log.warn('sse-parse-error', { error: (err as Error).message, raw: json.slice(0, 200) });\n            }\n          }\n        }\n      } else {\n        // Single JSON response.\n        const body = (await res.json()) as JsonRpcFrame;\n        await onFrame(body);\n      }\n    } catch (err) {\n      // AbortError surfaces when close() interrupts an in-flight request\n      // during reload; that's expected, so log it at info-not-error. We\n      // still rethrow so the FSM can clear inflight bookkeeping and\n      // synthesise an error response on its end.\n      if ((err as { name?: string }).name === 'AbortError') {\n        log.info('http-upstream-aborted', { method: frame.method });\n      } else {\n        log.error('http-upstream-error', { error: (err as Error).message, method: frame.method });\n      }\n      throw err;\n    } finally {\n      abortControllers.delete(abortController);\n    }\n  }\n\n  return {\n    send,\n    close: async () => {\n      for (const ac of abortControllers) ac.abort();\n      abortControllers.clear();\n    },\n  };\n}\n\n// ─── Pipe mode (--serve) ────────────────────────────────────────────────\n\nexport interface PipeUpstreamOptions extends UpstreamClientOptions {\n  /** The forked child; we write to / read from the IPC pipe (FD 3). */\n  child: ChildProcess;\n}\n\n/**\n * Pipe mode: the child speaks JSON-RPC on FD 3 (set via\n * `FRONTMCP_DEV_STDIO_FD=3`). We use Node's IPC channel for the same wire\n * — `child.send(...)` forwards a structured message and `child.on('message', …)`\n * yields whatever the child writes back.\n *\n * (Node's IPC wraps JSON over a pipe internally; the framing is consistent\n * with what `runStdio` would write if it were pointed at FD 3.)\n */\nexport function createPipeUpstream(options: PipeUpstreamOptions): UpstreamClient {\n  const { log, child, onFrame } = options;\n\n  function handleMessage(msg: unknown): void {\n    if (!msg || typeof msg !== 'object') {\n      log.warn('pipe-upstream-non-object', { type: typeof msg });\n      return;\n    }\n    void onFrame(msg as JsonRpcFrame);\n  }\n\n  child.on('message', handleMessage);\n\n  async function send(frame: JsonRpcFrame): Promise<void> {\n    if (!child.connected) {\n      log.warn('pipe-upstream-disconnected', { method: frame.method });\n      throw new Error(`pipe upstream disconnected for ${frame.method ?? 'request'}`);\n    }\n    await new Promise<void>((resolve, reject) => {\n      child.send(frame, (err) => {\n        if (err) reject(err);\n        else resolve();\n      });\n    }).catch((err: Error) => {\n      // Reject so the FSM can produce a JSON-RPC error response back to\n      // the client rather than leaving the request stuck inflight.\n      log.warn('pipe-upstream-send-error', { error: err.message, method: frame.method });\n      throw err;\n    });\n  }\n\n  return {\n    send,\n    close: async () => {\n      child.off('message', handleMessage);\n    },\n  };\n}\n"]}

package/src/commands/dev/bridge/watcher.d.ts

@@ -0,0 +1,30 @@
+/**
+ * File watcher for the dev bridge (issue #399).
+ *
+ * In bridge mode, `tsx` is used as a loader (no `--watch`) — the bridge
+ * owns the watcher so it can emit a `reload-start` signal to the state
+ * machine. Today's `tsx --watch` owns the watcher internally, which is
+ * why it can't coordinate with anyone else.
+ *
+ * Uses `fs.watch` (Node built-in, no dep) with a 150ms debounce. The
+ * default ignore list filters `node_modules`, `.git`, `dist`, and the
+ * non-TS extensions that don't trigger source-of-truth reloads.
+ */
+import type { BridgeLogger } from './log';
+export interface DevWatcherOptions {
+    /** Directory to watch (typically the entry's parent). */
+    rootDir: string;
+    /** Debounce window in ms — multiple events within this window collapse. */
+    debounceMs?: number;
+    /** Glob fragments to skip. Default: node_modules, .git, dist, .frontmcp. */
+    ignore?: string[];
+    /** Extensions that trigger reload. Default: .ts, .tsx, .js, .mjs, .cjs. */
+    triggerExtensions?: string[];
+    log: BridgeLogger;
+    onChange: (relativePath: string) => void;
+}
+export interface DevWatcher {
+    start(): void;
+    stop(): void;
+}
+export declare function createDevWatcher(options: DevWatcherOptions): DevWatcher;

package/src/commands/dev/bridge/watcher.js

@@ -0,0 +1,87 @@
+"use strict";
+/**
+ * File watcher for the dev bridge (issue #399).
+ *
+ * In bridge mode, `tsx` is used as a loader (no `--watch`) — the bridge
+ * owns the watcher so it can emit a `reload-start` signal to the state
+ * machine. Today's `tsx --watch` owns the watcher internally, which is
+ * why it can't coordinate with anyone else.
+ *
+ * Uses `fs.watch` (Node built-in, no dep) with a 150ms debounce. The
+ * default ignore list filters `node_modules`, `.git`, `dist`, and the
+ * non-TS extensions that don't trigger source-of-truth reloads.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDevWatcher = createDevWatcher;
+const tslib_1 = require("tslib");
+const fs = tslib_1.__importStar(require("node:fs"));
+const path = tslib_1.__importStar(require("node:path"));
+const DEFAULT_IGNORE = ['node_modules', '.git', 'dist', '.frontmcp'];
+const DEFAULT_EXTS = ['.ts', '.tsx', '.js', '.mjs', '.cjs'];
+function createDevWatcher(options) {
+    const debounce = options.debounceMs ?? 150;
+    const ignore = options.ignore ?? DEFAULT_IGNORE;
+    const exts = options.triggerExtensions ?? DEFAULT_EXTS;
+    const log = options.log;
+    let timer;
+    let lastTrigger;
+    let watcher;
+    function shouldIgnore(rel) {
+        if (ignore.some((seg) => rel.split(path.sep).includes(seg)))
+            return true;
+        const ext = path.extname(rel);
+        return ext.length > 0 && !exts.includes(ext);
+    }
+    function fire(rel) {
+        lastTrigger = rel;
+        if (timer)
+            clearTimeout(timer);
+        timer = setTimeout(() => {
+            timer = undefined;
+            const triggerLabel = lastTrigger ?? '(unknown)';
+            log.reloadEvent('watcher', { trigger: triggerLabel });
+            options.onChange(triggerLabel);
+        }, debounce);
+    }
+    return {
+        start() {
+            try {
+                watcher = fs.watch(options.rootDir, { recursive: true }, (_event, filename) => {
+                    if (!filename)
+                        return;
+                    // Node's `fs.watch` types `filename` as `string | null` here
+                    // (no `encoding: 'buffer'` option set), so a `typeof filename ===
+                    // 'string'` narrow leaves the else-branch as `never` and trips
+                    // TS2339. `String(filename)` is defensive for any future widening
+                    // (e.g., a `Buffer` arriving via a polyfill) without confusing
+                    // the type checker.
+                    const rel = String(filename);
+                    if (shouldIgnore(rel))
+                        return;
+                    fire(rel);
+                });
+                watcher.on('error', (err) => {
+                    log.warn('watcher-error', { error: err.message });
+                });
+                log.info('watcher-started', { rootDir: options.rootDir, debounceMs: debounce });
+            }
+            catch (err) {
+                log.error('watcher-start-failed', { error: err.message });
+            }
+        },
+        stop() {
+            if (timer) {
+                clearTimeout(timer);
+                timer = undefined;
+            }
+            try {
+                watcher?.close();
+            }
+            catch {
+                // ignore
+            }
+            log.info('watcher-stopped');
+        },
+    };
+}
+//# sourceMappingURL=watcher.js.map

package/src/commands/dev/bridge/watcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"watcher.js","sourceRoot":"","sources":["../../../../../src/commands/dev/bridge/watcher.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * File watcher for the dev bridge (issue #399).\n *\n * In bridge mode, `tsx` is used as a loader (no `--watch`) — the bridge\n * owns the watcher so it can emit a `reload-start` signal to the state\n * machine. Today's `tsx --watch` owns the watcher internally, which is\n * why it can't coordinate with anyone else.\n *\n * Uses `fs.watch` (Node built-in, no dep) with a 150ms debounce. The\n * default ignore list filters `node_modules`, `.git`, `dist`, and the\n * non-TS extensions that don't trigger source-of-truth reloads.\n */\n\nimport * as fs from 'node:fs';\nimport * as path from 'node:path';\n\nimport type { BridgeLogger } from './log';\n\nexport interface DevWatcherOptions {\n  /** Directory to watch (typically the entry's parent). */\n  rootDir: string;\n  /** Debounce window in ms — multiple events within this window collapse. */\n  debounceMs?: number;\n  /** Glob fragments to skip. Default: node_modules, .git, dist, .frontmcp. */\n  ignore?: string[];\n  /** Extensions that trigger reload. Default: .ts, .tsx, .js, .mjs, .cjs. */\n  triggerExtensions?: string[];\n  log: BridgeLogger;\n  onChange: (relativePath: string) => void;\n}\n\nexport interface DevWatcher {\n  start(): void;\n  stop(): void;\n}\n\nconst DEFAULT_IGNORE = ['node_modules', '.git', 'dist', '.frontmcp'];\nconst DEFAULT_EXTS = ['.ts', '.tsx', '.js', '.mjs', '.cjs'];\n\nexport function createDevWatcher(options: DevWatcherOptions): DevWatcher {\n  const debounce = options.debounceMs ?? 150;\n  const ignore = options.ignore ?? DEFAULT_IGNORE;\n  const exts = options.triggerExtensions ?? DEFAULT_EXTS;\n  const log = options.log;\n  let timer: NodeJS.Timeout | undefined;\n  let lastTrigger: string | undefined;\n  let watcher: fs.FSWatcher | undefined;\n\n  function shouldIgnore(rel: string): boolean {\n    if (ignore.some((seg) => rel.split(path.sep).includes(seg))) return true;\n    const ext = path.extname(rel);\n    return ext.length > 0 && !exts.includes(ext);\n  }\n\n  function fire(rel: string): void {\n    lastTrigger = rel;\n    if (timer) clearTimeout(timer);\n    timer = setTimeout(() => {\n      timer = undefined;\n      const triggerLabel = lastTrigger ?? '(unknown)';\n      log.reloadEvent('watcher', { trigger: triggerLabel });\n      options.onChange(triggerLabel);\n    }, debounce);\n  }\n\n  return {\n    start() {\n      try {\n        watcher = fs.watch(options.rootDir, { recursive: true }, (_event, filename) => {\n          if (!filename) return;\n          // Node's `fs.watch` types `filename` as `string | null` here\n          // (no `encoding: 'buffer'` option set), so a `typeof filename ===\n          // 'string'` narrow leaves the else-branch as `never` and trips\n          // TS2339. `String(filename)` is defensive for any future widening\n          // (e.g., a `Buffer` arriving via a polyfill) without confusing\n          // the type checker.\n          const rel = String(filename);\n          if (shouldIgnore(rel)) return;\n          fire(rel);\n        });\n        watcher.on('error', (err) => {\n          log.warn('watcher-error', { error: err.message });\n        });\n        log.info('watcher-started', { rootDir: options.rootDir, debounceMs: debounce });\n      } catch (err) {\n        log.error('watcher-start-failed', { error: (err as Error).message });\n      }\n    },\n    stop() {\n      if (timer) {\n        clearTimeout(timer);\n        timer = undefined;\n      }\n      try {\n        watcher?.close();\n      } catch {\n        // ignore\n      }\n      log.info('watcher-stopped');\n    },\n  };\n}\n"]}

package/src/commands/dev/dev.d.ts

@@ -1,2 +1,19 @@
-import { ParsedArgs } from '../../core/args';
+import { type ParsedArgs } from '../../core/args';
+/**
+ * Resolve the port the dev child should bind to and report any conflict
+ * clearly. Returns the chosen port — or never returns and exits the process
+ * with a clear error when the port is busy and `--auto-port` was not set.
+ *
+ * Issue #398: previously the child crashed with a raw `EADDRINUSE` stack
+ * trace; this helper turns that into a one-line message with a suggested
+ * remediation and (optionally) the owning process.
+ */
+export declare function resolveDevPort(opts: {
+    port?: number;
+    autoPort?: boolean;
+    showConflict?: boolean;
+    envPort?: string | undefined;
+    exit?: (code: number) => never;
+    log?: (msg: string) => void;
+}): Promise<number>;
 export declare function runDev(opts: ParsedArgs): Promise<void>;