frontmcp 1.2.1 → 1.4.0

package/src/commands/dev/bridge/state-machine.js

@@ -0,0 +1,245 @@
+"use strict";
+/**
+ * Bridge state machine (issue #399).
+ *
+ *   Idle → Booting → Ready ⇄ Reloading
+ *                           ↓ deadline
+ *                        Degraded
+ *
+ * Owns the request buffer that absorbs inbound JSON-RPC frames while the
+ * upstream child is mid-restart. When buffered requests exceed the
+ * configured cap (default 8), the FSM synthesises an immediate
+ * `dev_buffer_full` response so clients never silently lose frames.
+ *
+ * The FSM is transport-agnostic — `child-supervisor` and `upstream-client`
+ * call into it; this module never touches sockets, child processes, or
+ * file descriptors.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createBridgeStateMachine = createBridgeStateMachine;
+const errors_1 = require("./errors");
+function createBridgeStateMachine(options) {
+    const { log, bufferSize, reloadDeadlineMs, respond, forward } = options;
+    let state = 'Idle';
+    const buffer = [];
+    const inflight = new Map();
+    let reloadTimer;
+    // Monotonic token bumped every time the FSM leaves Ready. The async
+    // drain loop started in onChildReady() captures the token at start
+    // and bails out as soon as it changes — without this guard a watcher
+    // event mid-drain would let buffered frames forward into the old
+    // child (now being killed), producing stranded inflight entries and
+    // potentially duplicate responses.
+    let readyGen = 0;
+    function transition(next, info) {
+        if (state === next)
+            return;
+        log.info('state-transition', { from: state, to: next, ...info });
+        state = next;
+    }
+    function clearReloadTimer() {
+        if (reloadTimer) {
+            clearTimeout(reloadTimer);
+            reloadTimer = undefined;
+        }
+    }
+    async function flushBufferAsResponses(code, reason, data) {
+        while (buffer.length > 0) {
+            const f = buffer.shift();
+            if (!f)
+                break;
+            const id = f.id ?? null;
+            // Notifications (no id) can't get a response — drop with a log line.
+            if (id === null) {
+                log.warn('drop-notification', { method: f.method, reason });
+                continue;
+            }
+            await respond((0, errors_1.makeDevError)(id, code, { reason, ...data }));
+        }
+    }
+    async function failInflightAsResponses(reason, data) {
+        for (const [id, req] of inflight) {
+            const idVal = typeof id === 'number' ? id : id;
+            await respond((0, errors_1.makeDevError)(idVal, errors_1.DEV_SERVER_UNREACHABLE, { reason, ...data, method: req.frame.method }));
+        }
+        inflight.clear();
+    }
+    return {
+        get state() {
+            return state;
+        },
+        bufferDepth: () => buffer.length,
+        onBootStart() {
+            transition('Booting');
+        },
+        onChildReady() {
+            clearReloadTimer();
+            transition('Ready', { bufferDepth: buffer.length });
+            // Drain buffered requests in FIFO; preserve order on the wire.
+            const drain = [...buffer];
+            buffer.length = 0;
+            const drainGen = readyGen;
+            void (async () => {
+                for (const f of drain) {
+                    // Bail out if the FSM left Ready (watcher event, child exit,
+                    // or stop()) — otherwise this drain would forward into a
+                    // child that's already being killed and duplicate responses
+                    // already sent by `failInflightAsResponses`.
+                    if (readyGen !== drainGen)
+                        return;
+                    const requestId = typeof f.id === 'string' || typeof f.id === 'number' ? f.id : null;
+                    // Re-mark as inflight when forwarding; relayUpstream will clear it.
+                    if (requestId !== null) {
+                        inflight.set(requestId, { frame: f, forwardedAt: Date.now() });
+                    }
+                    try {
+                        await forward(f);
+                    }
+                    catch (err) {
+                        log.error('forward-failed', { error: err.message });
+                        // Mirror the live-enqueue failure path: a request that never
+                        // reached the child must still resolve on the wire, otherwise
+                        // the MCP client sits on `Calling…` forever. Notifications
+                        // (`requestId === null`) have no caller waiting on a response.
+                        // Only respond if we still own this generation — otherwise
+                        // failInflightAsResponses() already sent the error.
+                        if (requestId !== null && readyGen === drainGen) {
+                            inflight.delete(requestId);
+                            await respond((0, errors_1.makeDevError)(requestId, errors_1.DEV_SERVER_UNREACHABLE, { reason: 'forward_failed' }));
+                        }
+                    }
+                }
+            })();
+        },
+        onChildExit(reason) {
+            log.warn('child-exit', { reason, state });
+            if (state === 'Stopping')
+                return; // expected
+            // Treat as a reload trigger if we were Ready; otherwise stay where we are.
+            if (state === 'Ready' || state === 'Booting') {
+                // Invalidate any in-progress drain that captured the prior readyGen.
+                readyGen++;
+                transition('Reloading', { trigger: 'child-exit', reason });
+                // Inflight requests will never get a real response — synthesise one.
+                void failInflightAsResponses('child_exit', { reason });
+                scheduleReloadDeadline();
+            }
+            else if (state === 'Reloading') {
+                // Two exits in a row — keep waiting for boot
+            }
+        },
+        onWatcherEvent(trigger) {
+            if (state === 'Stopping' || state === 'Degraded')
+                return;
+            log.reloadEvent('start', { trigger });
+            // Invalidate any in-progress drain so it stops forwarding into
+            // the child that's about to be killed.
+            readyGen++;
+            transition('Reloading', { trigger });
+            // Inflight requests will likely be killed when supervisor kills the
+            // child. Respond now so the client spinner clears immediately.
+            void failInflightAsResponses('reload', { trigger });
+            scheduleReloadDeadline();
+        },
+        onReloadDeadline() {
+            log.error('reload-deadline-elapsed', { bufferDepth: buffer.length });
+            transition('Degraded', { reason: 'reload_deadline' });
+            // Deadline path → DEV_RELOAD_DEADLINE (not DEV_SERVER_UNREACHABLE).
+            // The two map to distinct public error codes so clients can
+            // distinguish "watcher reload took too long" from "child crashed".
+            void flushBufferAsResponses(errors_1.DEV_RELOAD_DEADLINE, 'deadline', { deadlineMs: reloadDeadlineMs });
+        },
+        async enqueue(frame) {
+            const isRequest = frame.id !== undefined && frame.id !== null;
+            if (state === 'Ready') {
+                if (isRequest) {
+                    inflight.set(frame.id, { frame, forwardedAt: Date.now() });
+                }
+                try {
+                    await forward(frame);
+                }
+                catch (err) {
+                    log.error('forward-failed', { error: err.message });
+                    if (isRequest) {
+                        inflight.delete(frame.id);
+                        await respond((0, errors_1.makeDevError)(frame.id ?? null, errors_1.DEV_SERVER_UNREACHABLE, { reason: 'forward_failed' }));
+                    }
+                }
+                return;
+            }
+            if (state === 'Degraded' || state === 'Stopping') {
+                // Both states are terminal for new traffic — Degraded is post-
+                // deadline (user code is broken), Stopping means SIGINT/SIGTERM
+                // already fired. Buffering here is wrong because nothing will
+                // drain it. Reject so the client spinner clears immediately.
+                if (isRequest) {
+                    await respond((0, errors_1.makeDevError)(frame.id ?? null, errors_1.DEV_SERVER_UNREACHABLE, {
+                        reason: state === 'Stopping' ? 'stopping' : 'degraded',
+                    }));
+                }
+                else {
+                    log.warn('drop-notification', {
+                        method: frame.method,
+                        reason: state === 'Stopping' ? 'stopping' : 'degraded',
+                    });
+                }
+                return;
+            }
+            // Idle / Booting / Reloading → buffer (will drain on onChildReady)
+            if (buffer.length >= bufferSize) {
+                if (isRequest) {
+                    await respond((0, errors_1.makeDevError)(frame.id ?? null, errors_1.DEV_BUFFER_FULL, { capacity: bufferSize }));
+                }
+                else {
+                    log.warn('drop-notification', { method: frame.method, reason: 'buffer_full' });
+                }
+                return;
+            }
+            buffer.push(frame);
+        },
+        async relayUpstream(frame) {
+            // Clear inflight if this is a response to a known id
+            if (frame.id !== undefined && frame.id !== null && (frame.result !== undefined || frame.error !== undefined)) {
+                inflight.delete(frame.id);
+            }
+            await respond(frame);
+        },
+        async stop() {
+            // Invalidate any in-progress drain — same reason as the watcher /
+            // child-exit paths: avoid forwarding into a child we're tearing
+            // down.
+            readyGen++;
+            transition('Stopping');
+            clearReloadTimer();
+            // Inflight + buffered: respond once so the client's pending RPCs don't
+            // dangle past the bridge exit.
+            await failInflightAsResponses('stopping');
+            await flushBufferAsResponses(errors_1.DEV_SERVER_UNREACHABLE, 'stopping');
+        },
+    };
+    function scheduleReloadDeadline() {
+        clearReloadTimer();
+        reloadTimer = setTimeout(() => {
+            if (state === 'Reloading' || state === 'Booting') {
+                // Mark deadline reached — supervisor stays alive, watcher retries.
+                log.error('reload-deadline-fired');
+                transition('Degraded', { reason: 'reload_deadline' });
+                // Drain buffer with deadline-shaped error.
+                void (async () => {
+                    while (buffer.length > 0) {
+                        const f = buffer.shift();
+                        if (!f)
+                            break;
+                        const id = f.id ?? null;
+                        if (id === null) {
+                            log.warn('drop-notification', { method: f.method, reason: 'deadline' });
+                            continue;
+                        }
+                        await respond((0, errors_1.makeDevError)(id, errors_1.DEV_RELOAD_DEADLINE, { deadlineMs: reloadDeadlineMs }));
+                    }
+                })();
+            }
+        }, reloadDeadlineMs).unref();
+    }
+}
+//# sourceMappingURL=state-machine.js.map

package/src/commands/dev/bridge/state-machine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-machine.js","sourceRoot":"","sources":["../../../../../src/commands/dev/bridge/state-machine.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Bridge state machine (issue #399).\n *\n *   Idle → Booting → Ready ⇄ Reloading\n *                           ↓ deadline\n *                        Degraded\n *\n * Owns the request buffer that absorbs inbound JSON-RPC frames while the\n * upstream child is mid-restart. When buffered requests exceed the\n * configured cap (default 8), the FSM synthesises an immediate\n * `dev_buffer_full` response so clients never silently lose frames.\n *\n * The FSM is transport-agnostic — `child-supervisor` and `upstream-client`\n * call into it; this module never touches sockets, child processes, or\n * file descriptors.\n */\n\nimport { DEV_BUFFER_FULL, DEV_RELOAD_DEADLINE, DEV_SERVER_UNREACHABLE, makeDevError } from './errors';\nimport type { BridgeLogger } from './log';\nimport type { JsonRpcFrame } from './stdio-framer';\n\nexport type BridgeState = 'Idle' | 'Booting' | 'Ready' | 'Reloading' | 'Degraded' | 'Stopping';\n\nexport interface InflightRequest {\n  /** Original frame (kept for replay if the child dies before responding). */\n  frame: JsonRpcFrame;\n  /** Wall-clock when the bridge forwarded the frame to upstream. */\n  forwardedAt: number;\n}\n\nexport interface BridgeStateMachineOptions {\n  log: BridgeLogger;\n  bufferSize: number;\n  reloadDeadlineMs: number;\n  /** Send a JSON-RPC frame back to the client (stdio out). */\n  respond(frame: JsonRpcFrame): void | Promise<void>;\n  /** Forward a request frame to the upstream child. Implemented by the supervisor. */\n  forward(frame: JsonRpcFrame): void | Promise<void>;\n}\n\nexport interface BridgeStateMachine {\n  readonly state: BridgeState;\n  /** Bridge has begun launching the child — buffer inbound frames. */\n  onBootStart(): void;\n  /** Child reports ready — drain the buffer through `forward`. */\n  onChildReady(): void;\n  /** Child exited unexpectedly. If we were Ready, transition to Reloading. */\n  onChildExit(reason: string): void;\n  /** Watcher fired. Buffer inbound, start reload timer. */\n  onWatcherEvent(trigger: string): void;\n  /** Reload deadline elapsed without a ready signal. */\n  onReloadDeadline(): void;\n  /** Inbound JSON-RPC frame from stdin. Routes to `forward` or buffers. */\n  enqueue(frame: JsonRpcFrame): Promise<void>;\n  /** Outbound JSON-RPC frame from upstream — relay to client. */\n  relayUpstream(frame: JsonRpcFrame): Promise<void>;\n  /** SIGTERM/SIGINT — flush buffer with `dev_server_unreachable` and stop. */\n  stop(): Promise<void>;\n  /** Number of frames currently buffered (testing hook). */\n  bufferDepth(): number;\n}\n\nexport function createBridgeStateMachine(options: BridgeStateMachineOptions): BridgeStateMachine {\n  const { log, bufferSize, reloadDeadlineMs, respond, forward } = options;\n  let state: BridgeState = 'Idle';\n  const buffer: JsonRpcFrame[] = [];\n  const inflight = new Map<string | number, InflightRequest>();\n  let reloadTimer: NodeJS.Timeout | undefined;\n  // Monotonic token bumped every time the FSM leaves Ready. The async\n  // drain loop started in onChildReady() captures the token at start\n  // and bails out as soon as it changes — without this guard a watcher\n  // event mid-drain would let buffered frames forward into the old\n  // child (now being killed), producing stranded inflight entries and\n  // potentially duplicate responses.\n  let readyGen = 0;\n\n  function transition(next: BridgeState, info?: Record<string, unknown>): void {\n    if (state === next) return;\n    log.info('state-transition', { from: state, to: next, ...info });\n    state = next;\n  }\n\n  function clearReloadTimer(): void {\n    if (reloadTimer) {\n      clearTimeout(reloadTimer);\n      reloadTimer = undefined;\n    }\n  }\n\n  async function flushBufferAsResponses(code: number, reason: string, data?: Record<string, unknown>): Promise<void> {\n    while (buffer.length > 0) {\n      const f = buffer.shift();\n      if (!f) break;\n      const id = f.id ?? null;\n      // Notifications (no id) can't get a response — drop with a log line.\n      if (id === null) {\n        log.warn('drop-notification', { method: f.method, reason });\n        continue;\n      }\n      await respond(makeDevError(id, code, { reason, ...data }));\n    }\n  }\n\n  async function failInflightAsResponses(reason: string, data?: Record<string, unknown>): Promise<void> {\n    for (const [id, req] of inflight) {\n      const idVal = typeof id === 'number' ? id : (id as string);\n      await respond(makeDevError(idVal, DEV_SERVER_UNREACHABLE, { reason, ...data, method: req.frame.method }));\n    }\n    inflight.clear();\n  }\n\n  return {\n    get state() {\n      return state;\n    },\n    bufferDepth: () => buffer.length,\n\n    onBootStart() {\n      transition('Booting');\n    },\n\n    onChildReady() {\n      clearReloadTimer();\n      transition('Ready', { bufferDepth: buffer.length });\n      // Drain buffered requests in FIFO; preserve order on the wire.\n      const drain = [...buffer];\n      buffer.length = 0;\n      const drainGen = readyGen;\n      void (async () => {\n        for (const f of drain) {\n          // Bail out if the FSM left Ready (watcher event, child exit,\n          // or stop()) — otherwise this drain would forward into a\n          // child that's already being killed and duplicate responses\n          // already sent by `failInflightAsResponses`.\n          if (readyGen !== drainGen) return;\n          const requestId = typeof f.id === 'string' || typeof f.id === 'number' ? f.id : null;\n          // Re-mark as inflight when forwarding; relayUpstream will clear it.\n          if (requestId !== null) {\n            inflight.set(requestId, { frame: f, forwardedAt: Date.now() });\n          }\n          try {\n            await forward(f);\n          } catch (err) {\n            log.error('forward-failed', { error: (err as Error).message });\n            // Mirror the live-enqueue failure path: a request that never\n            // reached the child must still resolve on the wire, otherwise\n            // the MCP client sits on `Calling…` forever. Notifications\n            // (`requestId === null`) have no caller waiting on a response.\n            // Only respond if we still own this generation — otherwise\n            // failInflightAsResponses() already sent the error.\n            if (requestId !== null && readyGen === drainGen) {\n              inflight.delete(requestId);\n              await respond(makeDevError(requestId, DEV_SERVER_UNREACHABLE, { reason: 'forward_failed' }));\n            }\n          }\n        }\n      })();\n    },\n\n    onChildExit(reason) {\n      log.warn('child-exit', { reason, state });\n      if (state === 'Stopping') return; // expected\n      // Treat as a reload trigger if we were Ready; otherwise stay where we are.\n      if (state === 'Ready' || state === 'Booting') {\n        // Invalidate any in-progress drain that captured the prior readyGen.\n        readyGen++;\n        transition('Reloading', { trigger: 'child-exit', reason });\n        // Inflight requests will never get a real response — synthesise one.\n        void failInflightAsResponses('child_exit', { reason });\n        scheduleReloadDeadline();\n      } else if (state === 'Reloading') {\n        // Two exits in a row — keep waiting for boot\n      }\n    },\n\n    onWatcherEvent(trigger) {\n      if (state === 'Stopping' || state === 'Degraded') return;\n      log.reloadEvent('start', { trigger });\n      // Invalidate any in-progress drain so it stops forwarding into\n      // the child that's about to be killed.\n      readyGen++;\n      transition('Reloading', { trigger });\n      // Inflight requests will likely be killed when supervisor kills the\n      // child. Respond now so the client spinner clears immediately.\n      void failInflightAsResponses('reload', { trigger });\n      scheduleReloadDeadline();\n    },\n\n    onReloadDeadline() {\n      log.error('reload-deadline-elapsed', { bufferDepth: buffer.length });\n      transition('Degraded', { reason: 'reload_deadline' });\n      // Deadline path → DEV_RELOAD_DEADLINE (not DEV_SERVER_UNREACHABLE).\n      // The two map to distinct public error codes so clients can\n      // distinguish \"watcher reload took too long\" from \"child crashed\".\n      void flushBufferAsResponses(DEV_RELOAD_DEADLINE, 'deadline', { deadlineMs: reloadDeadlineMs });\n    },\n\n    async enqueue(frame: JsonRpcFrame) {\n      const isRequest = frame.id !== undefined && frame.id !== null;\n\n      if (state === 'Ready') {\n        if (isRequest) {\n          inflight.set(frame.id as string | number, { frame, forwardedAt: Date.now() });\n        }\n        try {\n          await forward(frame);\n        } catch (err) {\n          log.error('forward-failed', { error: (err as Error).message });\n          if (isRequest) {\n            inflight.delete(frame.id as string | number);\n            await respond(makeDevError(frame.id ?? null, DEV_SERVER_UNREACHABLE, { reason: 'forward_failed' }));\n          }\n        }\n        return;\n      }\n\n      if (state === 'Degraded' || state === 'Stopping') {\n        // Both states are terminal for new traffic — Degraded is post-\n        // deadline (user code is broken), Stopping means SIGINT/SIGTERM\n        // already fired. Buffering here is wrong because nothing will\n        // drain it. Reject so the client spinner clears immediately.\n        if (isRequest) {\n          await respond(\n            makeDevError(frame.id ?? null, DEV_SERVER_UNREACHABLE, {\n              reason: state === 'Stopping' ? 'stopping' : 'degraded',\n            }),\n          );\n        } else {\n          log.warn('drop-notification', {\n            method: frame.method,\n            reason: state === 'Stopping' ? 'stopping' : 'degraded',\n          });\n        }\n        return;\n      }\n\n      // Idle / Booting / Reloading → buffer (will drain on onChildReady)\n      if (buffer.length >= bufferSize) {\n        if (isRequest) {\n          await respond(makeDevError(frame.id ?? null, DEV_BUFFER_FULL, { capacity: bufferSize }));\n        } else {\n          log.warn('drop-notification', { method: frame.method, reason: 'buffer_full' });\n        }\n        return;\n      }\n      buffer.push(frame);\n    },\n\n    async relayUpstream(frame: JsonRpcFrame) {\n      // Clear inflight if this is a response to a known id\n      if (frame.id !== undefined && frame.id !== null && (frame.result !== undefined || frame.error !== undefined)) {\n        inflight.delete(frame.id);\n      }\n      await respond(frame);\n    },\n\n    async stop() {\n      // Invalidate any in-progress drain — same reason as the watcher /\n      // child-exit paths: avoid forwarding into a child we're tearing\n      // down.\n      readyGen++;\n      transition('Stopping');\n      clearReloadTimer();\n      // Inflight + buffered: respond once so the client's pending RPCs don't\n      // dangle past the bridge exit.\n      await failInflightAsResponses('stopping');\n      await flushBufferAsResponses(DEV_SERVER_UNREACHABLE, 'stopping');\n    },\n  };\n\n  function scheduleReloadDeadline(): void {\n    clearReloadTimer();\n    reloadTimer = setTimeout(() => {\n      if (state === 'Reloading' || state === 'Booting') {\n        // Mark deadline reached — supervisor stays alive, watcher retries.\n        log.error('reload-deadline-fired');\n        transition('Degraded', { reason: 'reload_deadline' });\n        // Drain buffer with deadline-shaped error.\n        void (async () => {\n          while (buffer.length > 0) {\n            const f = buffer.shift();\n            if (!f) break;\n            const id = f.id ?? null;\n            if (id === null) {\n              log.warn('drop-notification', { method: f.method, reason: 'deadline' });\n              continue;\n            }\n            await respond(makeDevError(id, DEV_RELOAD_DEADLINE, { deadlineMs: reloadDeadlineMs }));\n          }\n        })();\n      }\n    }, reloadDeadlineMs).unref();\n  }\n}\n"]}

package/src/commands/dev/bridge/stdio-framer.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 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`.
+ */
+import type { Readable, Writable } from 'node:stream';
+import type { BridgeLogger } from './log';
+export interface JsonRpcFrame {
+    jsonrpc: '2.0';
+    id?: string | number | null;
+    method?: string;
+    params?: unknown;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+}
+export interface StdioFramerOptions {
+    input: Readable;
+    output: Writable;
+    log: BridgeLogger;
+    onFrame: (frame: JsonRpcFrame) => void | Promise<void>;
+}
+export interface StdioFramer {
+    start(): void;
+    /** Write a single frame as a newline-terminated JSON line. Resolves on `'drain'` when backpressure kicks in. */
+    write(frame: JsonRpcFrame): Promise<void>;
+    stop(): void;
+}
+/**
+ * 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.
+ */
+export declare function createStdioFramer(options: StdioFramerOptions): StdioFramer;

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;