frontmcp 1.2.0 → 1.3.0

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../src/commands/dev/bridge/index.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Dev stdio bridge entry point (issue #399).\n *\n * Wires the framer (stdio in/out), state machine (buffer + reload FSM),\n * watcher (file-change source), child supervisor (user-code lifecycle),\n * and upstream client (forwarding to the child) into a single\n * long-lived process.\n *\n * Lifetime:\n *\n *   1. Parse options, resolve entry + log file path.\n *   2. Pin a stable session id (uuid) so the same id survives child\n *      restarts.\n *   3. Construct logger; open log file.\n *   4. Construct state machine + framer + watcher + supervisor +\n *      upstream client (transport per `--serve`).\n *   5. Spawn the first child, wait for ready, transition state to Ready.\n *   6. Forward frames in both directions; watcher events trigger\n *      controlled restart.\n *   7. SIGINT/SIGTERM → flush buffer with `dev_server_unreachable`,\n *      tear down child + watcher, exit cleanly.\n */\n\nimport type { ChildProcess } from 'node:child_process';\nimport * as path from 'node:path';\n\nimport { randomUUID } from '@frontmcp/utils';\n\nimport type { ParsedArgs } from '../../../core/args';\nimport { resolveEntry } from '../../../shared/fs';\nimport { createChildSupervisor, type ChildSupervisor, type SupervisorMode } from './child-supervisor';\nimport { createBridgeLogger, type BridgeLogger } from './log';\nimport { createBridgeStateMachine, type BridgeStateMachine } from './state-machine';\nimport { createStdioFramer, type JsonRpcFrame, type StdioFramer } from './stdio-framer';\nimport { createHttpUpstream, createPipeUpstream, type UpstreamClient } from './upstream-client';\nimport { createDevWatcher } from './watcher';\n\ninterface RuntimeBridgeOptions {\n  entry: string;\n  mode: SupervisorMode;\n  port: number;\n  bufferSize: number;\n  reloadDeadlineMs: number;\n  logFile: string;\n}\n\nconst DEFAULT_PORT = 3000;\nconst DEFAULT_LOG_FILE = path.join('.frontmcp', 'dev.log');\n\nfunction normalizeOptions(opts: ParsedArgs, entry: string): RuntimeBridgeOptions {\n  const mode: SupervisorMode = opts.serve ? 'pipe' : 'http';\n  const port = typeof opts.port === 'number' ? opts.port : DEFAULT_PORT;\n  const bufferSize = typeof opts.bufferSize === 'number' && opts.bufferSize > 0 ? opts.bufferSize : 8;\n  const reloadDeadlineMs =\n    typeof opts.reloadDeadlineMs === 'number' && opts.reloadDeadlineMs > 0 ? opts.reloadDeadlineMs : 30_000;\n  const logFile = typeof opts.logFile === 'string' && opts.logFile.length > 0 ? opts.logFile : DEFAULT_LOG_FILE;\n  return { entry, mode, port, bufferSize, reloadDeadlineMs, logFile };\n}\n\nexport async function runDevBridge(opts: ParsedArgs): Promise<void> {\n  const cwd = process.cwd();\n  const entry = await resolveEntry(cwd, opts.entry);\n  const runtime = normalizeOptions(opts, entry);\n\n  const log = await createBridgeLogger({ filePath: runtime.logFile });\n  log.info('bridge-start', {\n    entry: runtime.entry,\n    mode: runtime.mode,\n    port: runtime.port,\n    bufferSize: runtime.bufferSize,\n    reloadDeadlineMs: runtime.reloadDeadlineMs,\n  });\n\n  // Pinned session id — child reads from FRONTMCP_DEV_FORCE_SESSION_ID so\n  // session continuity works across restarts (memory or Redis store both OK).\n  const sessionId = randomUUID();\n\n  // Only `upstream` is reassigned during runtime (on every child restart).\n  // The rest are constructed exactly once below and referenced through\n  // closures that fire after all bindings exist.\n  let upstream: UpstreamClient | undefined;\n\n  function buildUpstreamForChild(child: ChildProcess): UpstreamClient {\n    if (runtime.mode === 'http') {\n      return createHttpUpstream({\n        url: `http://127.0.0.1:${runtime.port}/`,\n        log,\n        sessionId,\n        onFrame: (frame: JsonRpcFrame) => fsm.relayUpstream(frame),\n      });\n    }\n    return createPipeUpstream({\n      child,\n      log,\n      sessionId,\n      onFrame: (frame: JsonRpcFrame) => fsm.relayUpstream(frame),\n    });\n  }\n\n  // ─── construct framer + FSM. Closures bind to each other by reference,\n  // so referencing `fsm`/`framer` inside a callback executed at runtime\n  // is safe even though `framer` is declared first textually. ───\n  const framer = createStdioFramer({\n    input: process.stdin,\n    output: process.stdout,\n    log,\n    onFrame: (frame) => fsm.enqueue(frame),\n  });\n\n  const fsm = createBridgeStateMachine({\n    log,\n    bufferSize: runtime.bufferSize,\n    reloadDeadlineMs: runtime.reloadDeadlineMs,\n    respond: (frame) => framer.write(frame),\n    forward: async (frame) => {\n      if (!upstream) {\n        log.warn('forward-without-upstream', { method: frame.method });\n        return;\n      }\n      await upstream.send(frame);\n    },\n  });\n\n  framer.start();\n\n  // ─── supervisor → boots first child, then attaches upstream ───\n  const supervisor = createChildSupervisor({\n    mode: runtime.mode,\n    entry: runtime.entry,\n    log,\n    sessionId,\n    port: runtime.mode === 'http' ? runtime.port : undefined,\n    onReady: async (child) => {\n      // Close any previous upstream (reload path). A rejection here MUST\n      // NOT block re-binding — the child is up and ready, and leaving the\n      // bridge without an upstream would strand every subsequent RPC.\n      try {\n        await upstream?.close();\n      } catch (err) {\n        log.error('upstream-stop-error', {\n          error: err instanceof Error ? err.message : String(err),\n        });\n      }\n      upstream = buildUpstreamForChild(child);\n      fsm.onChildReady();\n    },\n    onExit: (reason) => {\n      // Don't drop the close() promise — an in-flight HTTP request or SSE\n      // body read can reject (e.g. AbortError when we abort it ourselves),\n      // and an unhandled rejection here would crash the bridge on the\n      // next tick. Hand the rejection to the logger; the child is dead\n      // either way so we always proceed to onChildExit.\n      const closingUpstream = upstream;\n      upstream = undefined;\n      void closingUpstream?.close().catch((err: unknown) => {\n        log.error('upstream-stop-error', {\n          error: err instanceof Error ? err.message : String(err),\n        });\n      });\n      fsm.onChildExit(reason);\n    },\n  });\n\n  fsm.onBootStart();\n\n  try {\n    await supervisor.start();\n  } catch (err) {\n    log.error('initial-boot-failed', { error: (err as Error).message });\n    fsm.onReloadDeadline();\n    // Stay running so the watcher can retry once the user fixes the source.\n  }\n\n  // ─── watcher → restart on file change ───\n  // Watch the project root (cwd), not just the entry's directory: shared\n  // helpers, `frontmcp.config.ts`, and `tsconfig.json` all live above\n  // `src/main.ts` and must trigger a reload too. The recursive watcher\n  // already debounces and filters via `shouldIgnore` so the wider scope\n  // doesn't generate spurious reloads.\n  const watcher = createDevWatcher({\n    rootDir: cwd,\n    log,\n    onChange: (trigger) => {\n      fsm.onWatcherEvent(trigger);\n      void (async () => {\n        // Defensive — `supervisor` is captured in this closure after the\n        // initial assignment above, but a runtime check keeps the\n        // non-null assertion off the call site.\n        if (!supervisor) {\n          log.error('restart-failed', { error: 'supervisor not initialised', trigger });\n          return;\n        }\n        try {\n          await supervisor.restart();\n        } catch (err) {\n          log.error('restart-failed', { error: (err as Error).message });\n        }\n      })();\n    },\n  });\n  watcher.start();\n\n  // ─── teardown wiring ───\n  let stopping = false;\n  async function shutdown(signal: NodeJS.Signals): Promise<void> {\n    if (stopping) return;\n    stopping = true;\n    log.info('bridge-stop', { signal });\n    try {\n      await fsm.stop();\n    } catch (err) {\n      log.error('fsm-stop-error', { error: (err as Error).message });\n    }\n    try {\n      watcher.stop();\n    } catch (err) {\n      log.error('watcher-stop-error', { error: (err as Error).message });\n    }\n    try {\n      await upstream?.close();\n    } catch (err) {\n      log.error('upstream-stop-error', { error: (err as Error).message });\n    }\n    try {\n      await supervisor.stop();\n    } catch (err) {\n      log.error('supervisor-stop-error', { error: (err as Error).message });\n    }\n    framer.stop();\n    await log.close();\n    process.exit(0);\n  }\n\n  process.once('SIGINT', () => void shutdown('SIGINT'));\n  process.once('SIGTERM', () => void shutdown('SIGTERM'));\n\n  // Bridge runs until SIGINT/SIGTERM — keep the event loop alive via the\n  // open stdin + watcher.\n}\n\nexport { type BridgeLogger, type BridgeStateMachine, type ChildSupervisor, type StdioFramer, type UpstreamClient };\n"]}

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

@@ -0,0 +1,29 @@
+/**
+ * File logger for the dev bridge (issue #399).
+ *
+ * The bridge owns `process.stdout` for JSON-RPC frames — every log line
+ * MUST go to a file (or stderr as fallback) so a single `console.log`
+ * never corrupts the wire. Append-only, line-buffered, no rotation in v1
+ * (operators can layer `logrotate`).
+ */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+export interface BridgeLogger {
+    readonly path: string | undefined;
+    debug(message: string, data?: Record<string, unknown>): void;
+    info(message: string, data?: Record<string, unknown>): void;
+    warn(message: string, data?: Record<string, unknown>): void;
+    error(message: string, data?: Record<string, unknown>): void;
+    reloadEvent(kind: string, data?: Record<string, unknown>): void;
+    close(): Promise<void>;
+}
+interface CreateLoggerOptions {
+    filePath?: string;
+    /** When true, write the line to stderr as well — useful when --color is set. */
+    alsoStderr?: boolean;
+}
+/**
+ * Create the file logger. When `filePath` is undefined or opening the file
+ * fails, falls back to stderr (stdout is reserved for JSON-RPC frames).
+ */
+export declare function createBridgeLogger(options?: CreateLoggerOptions): Promise<BridgeLogger>;
+export {};

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

@@ -0,0 +1,82 @@
+"use strict";
+/**
+ * File logger for the dev bridge (issue #399).
+ *
+ * The bridge owns `process.stdout` for JSON-RPC frames — every log line
+ * MUST go to a file (or stderr as fallback) so a single `console.log`
+ * never corrupts the wire. Append-only, line-buffered, no rotation in v1
+ * (operators can layer `logrotate`).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createBridgeLogger = createBridgeLogger;
+const tslib_1 = require("tslib");
+const fs = tslib_1.__importStar(require("node:fs"));
+const utils_1 = require("@frontmcp/utils");
+function formatLine(level, message, data) {
+    const ts = new Date().toISOString();
+    const payload = data && Object.keys(data).length > 0 ? ` ${JSON.stringify(data)}` : '';
+    return `${ts} bridge ${level} ${message}${payload}\n`;
+}
+/**
+ * Create the file logger. When `filePath` is undefined or opening the file
+ * fails, falls back to stderr (stdout is reserved for JSON-RPC frames).
+ */
+async function createBridgeLogger(options = {}) {
+    const filePath = options.filePath;
+    let stream;
+    let resolvedPath;
+    if (filePath) {
+        try {
+            const absolutePath = (0, utils_1.pathResolve)(filePath);
+            const dir = (0, utils_1.dirname)(absolutePath);
+            await (0, utils_1.ensureDir)(dir);
+            stream = fs.createWriteStream(filePath, { flags: 'a' });
+            // Async write failures (disk full, FD revoked) surface here, not
+            // from the synchronous `stream.write(...)` call. Without this
+            // handler Node turns the event into an unhandled 'error' that
+            // crashes the bridge. Drop the stream and fall back to stderr
+            // for the remainder of the session.
+            stream.on('error', (err) => {
+                process.stderr.write(formatLine('error', 'logger-stream-error', { error: err.message }));
+                stream = undefined;
+                resolvedPath = undefined;
+            });
+            resolvedPath = absolutePath;
+        }
+        catch {
+            // Stream creation failed (read-only FS, permission denied, …).
+            // Fall back to stderr-only logging; stdout stays clean.
+            stream = undefined;
+            resolvedPath = undefined;
+        }
+    }
+    function write(level, message, data) {
+        const line = formatLine(level, message, data);
+        if (stream) {
+            try {
+                stream.write(line);
+            }
+            catch {
+                // Best-effort: a write failure mid-session falls back to stderr.
+                process.stderr.write(line);
+            }
+        }
+        if (!stream || options.alsoStderr) {
+            process.stderr.write(line);
+        }
+    }
+    return {
+        path: resolvedPath,
+        debug: (msg, data) => write('debug', msg, data),
+        info: (msg, data) => write('info', msg, data),
+        warn: (msg, data) => write('warn', msg, data),
+        error: (msg, data) => write('error', msg, data),
+        reloadEvent: (kind, data) => write('info', `reload-${kind}`, data),
+        close: () => new Promise((resolve) => {
+            if (!stream)
+                return resolve();
+            stream.end(() => resolve());
+        }),
+    };
+}
+//# sourceMappingURL=log.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"log.js","sourceRoot":"","sources":["../../../../../src/commands/dev/bridge/log.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;AAkCH,gDA0DC;;AA1FD,oDAA8B;AAE9B,2CAAkE;AAoBlE,SAAS,UAAU,CAAC,KAAe,EAAE,OAAe,EAAE,IAA8B;IAClF,MAAM,EAAE,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACpC,MAAM,OAAO,GAAG,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IACvF,OAAO,GAAG,EAAE,WAAW,KAAK,IAAI,OAAO,GAAG,OAAO,IAAI,CAAC;AACxD,CAAC;AAED;;;GAGG;AACI,KAAK,UAAU,kBAAkB,CAAC,UAA+B,EAAE;IACxE,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;IAClC,IAAI,MAAkC,CAAC;IACvC,IAAI,YAAgC,CAAC;IAErC,IAAI,QAAQ,EAAE,CAAC;QACb,IAAI,CAAC;YACH,MAAM,YAAY,GAAG,IAAA,mBAAW,EAAC,QAAQ,CAAC,CAAC;YAC3C,MAAM,GAAG,GAAG,IAAA,eAAO,EAAC,YAAY,CAAC,CAAC;YAClC,MAAM,IAAA,iBAAS,EAAC,GAAG,CAAC,CAAC;YACrB,MAAM,GAAG,EAAE,CAAC,iBAAiB,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC;YACxD,iEAAiE;YACjE,8DAA8D;YAC9D,8DAA8D;YAC9D,8DAA8D;YAC9D,oCAAoC;YACpC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE;gBACzB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,OAAO,EAAE,qBAAqB,EAAE,EAAE,KAAK,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;gBACzF,MAAM,GAAG,SAAS,CAAC;gBACnB,YAAY,GAAG,SAAS,CAAC;YAC3B,CAAC,CAAC,CAAC;YACH,YAAY,GAAG,YAAY,CAAC;QAC9B,CAAC;QAAC,MAAM,CAAC;YACP,+DAA+D;YAC/D,wDAAwD;YACxD,MAAM,GAAG,SAAS,CAAC;YACnB,YAAY,GAAG,SAAS,CAAC;QAC3B,CAAC;IACH,CAAC;IAED,SAAS,KAAK,CAAC,KAAe,EAAE,OAAe,EAAE,IAA8B;QAC7E,MAAM,IAAI,GAAG,UAAU,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;QAC9C,IAAI,MAAM,EAAE,CAAC;YACX,IAAI,CAAC;gBACH,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YACrB,CAAC;YAAC,MAAM,CAAC;gBACP,iEAAiE;gBACjE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YAC7B,CAAC;QACH,CAAC;QACD,IAAI,CAAC,MAAM,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;YAClC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC7B,CAAC;IACH,CAAC;IAED,OAAO;QACL,IAAI,EAAE,YAAY;QAClB,KAAK,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,EAAE,GAAG,EAAE,IAAI,CAAC;QAC/C,IAAI,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,EAAE,GAAG,EAAE,IAAI,CAAC;QAC7C,IAAI,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,EAAE,GAAG,EAAE,IAAI,CAAC;QAC7C,KAAK,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,EAAE,GAAG,EAAE,IAAI,CAAC;QAC/C,WAAW,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,EAAE,UAAU,IAAI,EAAE,EAAE,IAAI,CAAC;QAClE,KAAK,EAAE,GAAG,EAAE,CACV,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;YAC5B,IAAI,CAAC,MAAM;gBAAE,OAAO,OAAO,EAAE,CAAC;YAC9B,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC;QAC9B,CAAC,CAAC;KACL,CAAC;AACJ,CAAC","sourcesContent":["/**\n * File logger for the dev bridge (issue #399).\n *\n * The bridge owns `process.stdout` for JSON-RPC frames — every log line\n * MUST go to a file (or stderr as fallback) so a single `console.log`\n * never corrupts the wire. Append-only, line-buffered, no rotation in v1\n * (operators can layer `logrotate`).\n */\n\nimport * as fs from 'node:fs';\n\nimport { dirname, ensureDir, pathResolve } from '@frontmcp/utils';\n\nexport type LogLevel = 'debug' | 'info' | 'warn' | 'error';\n\nexport interface BridgeLogger {\n  readonly path: string | undefined;\n  debug(message: string, data?: Record<string, unknown>): void;\n  info(message: string, data?: Record<string, unknown>): void;\n  warn(message: string, data?: Record<string, unknown>): void;\n  error(message: string, data?: Record<string, unknown>): void;\n  reloadEvent(kind: string, data?: Record<string, unknown>): void;\n  close(): Promise<void>;\n}\n\ninterface CreateLoggerOptions {\n  filePath?: string;\n  /** When true, write the line to stderr as well — useful when --color is set. */\n  alsoStderr?: boolean;\n}\n\nfunction formatLine(level: LogLevel, message: string, data?: Record<string, unknown>): string {\n  const ts = new Date().toISOString();\n  const payload = data && Object.keys(data).length > 0 ? ` ${JSON.stringify(data)}` : '';\n  return `${ts} bridge ${level} ${message}${payload}\\n`;\n}\n\n/**\n * Create the file logger. When `filePath` is undefined or opening the file\n * fails, falls back to stderr (stdout is reserved for JSON-RPC frames).\n */\nexport async function createBridgeLogger(options: CreateLoggerOptions = {}): Promise<BridgeLogger> {\n  const filePath = options.filePath;\n  let stream: fs.WriteStream | undefined;\n  let resolvedPath: string | undefined;\n\n  if (filePath) {\n    try {\n      const absolutePath = pathResolve(filePath);\n      const dir = dirname(absolutePath);\n      await ensureDir(dir);\n      stream = fs.createWriteStream(filePath, { flags: 'a' });\n      // Async write failures (disk full, FD revoked) surface here, not\n      // from the synchronous `stream.write(...)` call. Without this\n      // handler Node turns the event into an unhandled 'error' that\n      // crashes the bridge. Drop the stream and fall back to stderr\n      // for the remainder of the session.\n      stream.on('error', (err) => {\n        process.stderr.write(formatLine('error', 'logger-stream-error', { error: err.message }));\n        stream = undefined;\n        resolvedPath = undefined;\n      });\n      resolvedPath = absolutePath;\n    } catch {\n      // Stream creation failed (read-only FS, permission denied, …).\n      // Fall back to stderr-only logging; stdout stays clean.\n      stream = undefined;\n      resolvedPath = undefined;\n    }\n  }\n\n  function write(level: LogLevel, message: string, data?: Record<string, unknown>): void {\n    const line = formatLine(level, message, data);\n    if (stream) {\n      try {\n        stream.write(line);\n      } catch {\n        // Best-effort: a write failure mid-session falls back to stderr.\n        process.stderr.write(line);\n      }\n    }\n    if (!stream || options.alsoStderr) {\n      process.stderr.write(line);\n    }\n  }\n\n  return {\n    path: resolvedPath,\n    debug: (msg, data) => write('debug', msg, data),\n    info: (msg, data) => write('info', msg, data),\n    warn: (msg, data) => write('warn', msg, data),\n    error: (msg, data) => write('error', msg, data),\n    reloadEvent: (kind, data) => write('info', `reload-${kind}`, data),\n    close: () =>\n      new Promise<void>((resolve) => {\n        if (!stream) return resolve();\n        stream.end(() => resolve());\n      }),\n  };\n}\n"]}

package/src/commands/dev/bridge/state-machine.d.ts

@@ -0,0 +1,56 @@
+/**
+ * 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.
+ */
+import type { BridgeLogger } from './log';
+import type { JsonRpcFrame } from './stdio-framer';
+export type BridgeState = 'Idle' | 'Booting' | 'Ready' | 'Reloading' | 'Degraded' | 'Stopping';
+export interface InflightRequest {
+    /** Original frame (kept for replay if the child dies before responding). */
+    frame: JsonRpcFrame;
+    /** Wall-clock when the bridge forwarded the frame to upstream. */
+    forwardedAt: number;
+}
+export interface BridgeStateMachineOptions {
+    log: BridgeLogger;
+    bufferSize: number;
+    reloadDeadlineMs: number;
+    /** Send a JSON-RPC frame back to the client (stdio out). */
+    respond(frame: JsonRpcFrame): void | Promise<void>;
+    /** Forward a request frame to the upstream child. Implemented by the supervisor. */
+    forward(frame: JsonRpcFrame): void | Promise<void>;
+}
+export interface BridgeStateMachine {
+    readonly state: BridgeState;
+    /** Bridge has begun launching the child — buffer inbound frames. */
+    onBootStart(): void;
+    /** Child reports ready — drain the buffer through `forward`. */
+    onChildReady(): void;
+    /** Child exited unexpectedly. If we were Ready, transition to Reloading. */
+    onChildExit(reason: string): void;
+    /** Watcher fired. Buffer inbound, start reload timer. */
+    onWatcherEvent(trigger: string): void;
+    /** Reload deadline elapsed without a ready signal. */
+    onReloadDeadline(): void;
+    /** Inbound JSON-RPC frame from stdin. Routes to `forward` or buffers. */
+    enqueue(frame: JsonRpcFrame): Promise<void>;
+    /** Outbound JSON-RPC frame from upstream — relay to client. */
+    relayUpstream(frame: JsonRpcFrame): Promise<void>;
+    /** SIGTERM/SIGINT — flush buffer with `dev_server_unreachable` and stop. */
+    stop(): Promise<void>;
+    /** Number of frames currently buffered (testing hook). */
+    bufferDepth(): number;
+}
+export declare function createBridgeStateMachine(options: BridgeStateMachineOptions): BridgeStateMachine;

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;