@sabaiway/agent-workflow-kit 6.0.0 → 7.0.0

package/tools/mcp-server.mjs

@@ -0,0 +1,314 @@
+#!/usr/bin/env node
+// mcp-server.mjs — the kit's stdio MCP server: the two promptless readers as TYPED tools.
+//
+// WHY THIS EXISTS. Every lane an agent used for a path question or a literal search ended in a STRING
+// handed to a shell, and a string always admits a pipe, a redirect, a quote, an `||`. Here the same two
+// readers (path-inventory.mjs, repo-search.mjs) are reached through named JSON fields: validated against
+// a CLOSED schema, turned into an in-process argv LIST, handed to each reader's exported `main(argv,
+// {cwd})`. No shell, no subprocess, no string — a decoration has no slot; `>`, a backtick, `$(` are bytes.
+// Root = `--root` > env CLAUDE_PROJECT_DIR (Claude Code sets it for a stdio server) > cwd; containment
+// stays the readers' own real-path rule. A client's child, outside any Bash sandbox, read-only,
+// root-contained. Dependency-free, Node >= 22, no side effects on import.
+
+import { readFileSync, realpathSync, statSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { PassThrough } from 'node:stream';
+import { isDirectRun } from './direct-run.mjs';
+import { JSONRPC_ERRORS, createDispatcher, rpcError, serveStdio } from './mcp-stdio.mjs';
+import {
+  main as inventoryMain,
+  HARD_MAX_CONTENT_BYTES,
+  HARD_MAX_ENTRIES,
+  HARD_MAX_TOTAL_BYTES as INVENTORY_HARD_MAX_TOTAL_BYTES,
+  HARD_MAX_TOTAL_ENTRIES,
+} from './path-inventory.mjs';
+import {
+  main as searchMain,
+  HARD_MAX_TARGETS,
+  HARD_MAX_RESULTS,
+  HARD_MAX_FILE_BYTES,
+  HARD_MAX_TOTAL_BYTES as SEARCH_HARD_MAX_TOTAL_BYTES,
+} from './repo-search.mjs';
+
+export const SERVER_NAME = 'agent-workflow';
+const EXIT_OK = 0;
+const EXIT_FAILED = 1;
+const EXIT_USAGE = 2;
+const ROOT_ENV = 'CLAUDE_PROJECT_DIR';
+const READ_ONLY = Object.freeze({ readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false });
+const INSTRUCTIONS =
+  'Read-only tools over the project root. Prefer them to a shell for a path question (exists / type / size / lines / listing / a small file) and for a literal search: a pattern or path is a JSON field, never a command string.';
+
+const pathList = (description) => ({
+  type: 'array',
+  items: { type: 'string', minLength: 1 },
+  minItems: 1,
+  maxItems: HARD_MAX_TARGETS,
+  description,
+});
+const count = (maximum, description) => ({ type: 'integer', minimum: 0, maximum, description });
+
+// The public definitions — exactly what tools/list returns. The schema a client sees is the schema
+// validateArgs enforces: one object, no second copy to drift.
+export const TOOLS = Object.freeze([
+  Object.freeze({
+    name: 'path_inventory',
+    title: 'Path inventory',
+    description:
+      'Facts about named paths inside the project root, in ONE call: exists, type, bytes, line count (wc -l compatible), a directory listing (one level), and with contents=true the text of a small file. A missing path is a RESULT (absent), never an error. Symlinks are reported by type and never followed; binaries are never decoded.',
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['paths'],
+      properties: {
+        paths: pathList('Project-relative paths, any number; a trailing "/" asserts a directory.'),
+        contents: { type: 'boolean', description: 'Also return the text of each regular text file.' },
+        maxContentBytes: count(HARD_MAX_CONTENT_BYTES, 'Per-file ceiling for the line count and contents.'),
+        maxEntries: count(HARD_MAX_ENTRIES, 'Per-directory listing ceiling.'),
+        maxTotalBytes: count(INVENTORY_HARD_MAX_TOTAL_BYTES, 'Whole-call byte ceiling.'),
+        maxTotalEntries: count(HARD_MAX_TOTAL_ENTRIES, 'Whole-call listed-entries ceiling.'),
+      },
+    },
+    annotations: READ_ONLY,
+  }),
+  Object.freeze({
+    name: 'repo_search',
+    title: 'Repository search (literal)',
+    description:
+      'LITERAL search (no regex) for a pattern across the project root or the named paths: every hit as file:line with a bounded snippet. The pattern is a plain JSON string, so shell-significant bytes need no quoting. A fired bound is reported as INCOMPLETE with its name, never as an empty result.',
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['pattern'],
+      properties: {
+        pattern: { type: 'string', minLength: 1, description: 'The literal bytes to find; multiline allowed.' },
+        paths: pathList('Project-relative search targets (default: the whole root).'),
+        max: count(HARD_MAX_RESULTS, 'Result ceiling.'),
+        maxBytes: count(HARD_MAX_FILE_BYTES, 'Per-file byte ceiling.'),
+        maxTotalBytes: count(SEARCH_HARD_MAX_TOTAL_BYTES, 'Whole-call byte ceiling.'),
+      },
+    },
+    annotations: READ_ONLY,
+  }),
+]);
+
+const numericFlags = (value, pairs) => pairs.flatMap(([key, flag]) => (value[key] === undefined ? [] : [flag, String(value[key])]));
+const pathFlags = (paths = []) => paths.flatMap((p) => ['--path', p]);
+
+// Field → argv, deterministic and ONE flag per field. Kept beside the public definitions by NAME.
+const RUNTIME = Object.freeze({
+  path_inventory: Object.freeze({
+    main: inventoryMain,
+    argv: (v) => [
+      ...pathFlags(v.paths),
+      ...(v.contents === true ? ['--contents'] : []),
+      ...numericFlags(v, [['maxContentBytes', '--max-content-bytes'], ['maxEntries', '--max-entries'], ['maxTotalBytes', '--max-total-bytes'], ['maxTotalEntries', '--max-total-entries']]),
+    ],
+  }),
+  repo_search: Object.freeze({
+    main: searchMain,
+    argv: (v) => ['--pattern', v.pattern, ...pathFlags(v.paths), ...numericFlags(v, [['max', '--max'], ['maxBytes', '--max-bytes'], ['maxTotalBytes', '--max-total-bytes']])],
+  }),
+});
+
+const toolByName = (name) => TOOLS.find((t) => t.name === name);
+const isPlainObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+
+// A walker over the schema subset the two tools use — the public schema IS the validator's input. A
+// schema type outside that subset is a fault, never a silent pass; exported so that arm has a test.
+export const checkAgainst = (schema, value, at) => {
+  if (schema.type === 'object') {
+    if (!isPlainObject(value)) return `${at} must be an object`;
+    for (const key of Object.keys(value)) if (!Object.hasOwn(schema.properties, key)) return `${at}: unknown key "${key}"`;
+    for (const key of schema.required ?? []) if (!Object.hasOwn(value, key)) return `${at}: "${key}" is required`;
+    for (const [key, sub] of Object.entries(schema.properties)) {
+      if (!Object.hasOwn(value, key)) continue;
+      const fault = checkAgainst(sub, value[key], `${at}.${key}`);
+      if (fault !== null) return fault;
+    }
+    return null;
+  }
+  if (schema.type === 'string') {
+    if (typeof value !== 'string') return `${at} must be a string`;
+    if (schema.minLength !== undefined && value.length < schema.minLength) return `${at} must not be empty`;
+    // A lone surrogate becomes U+FFFD on the way to the filesystem, so the reader could answer about
+    // a DIFFERENT, existing path — the substitution class the readers refuse; refused here, before argv.
+    if (!value.isWellFormed()) return `${at} must be well-formed Unicode (no lone surrogate)`;
+    return null;
+  }
+  if (schema.type === 'boolean') return typeof value === 'boolean' ? null : `${at} must be a boolean`;
+  if (schema.type === 'integer') {
+    if (!Number.isInteger(value)) return `${at} must be an integer`;
+    if (schema.minimum !== undefined && value < schema.minimum) return `${at} must be >= ${schema.minimum}`;
+    if (schema.maximum !== undefined && value > schema.maximum) return `${at} must be <= ${schema.maximum}`;
+    return null;
+  }
+  if (schema.type === 'array') {
+    if (!Array.isArray(value)) return `${at} must be an array`;
+    if (schema.minItems !== undefined && value.length < schema.minItems) return `${at} must not be empty`;
+    if (schema.maxItems !== undefined && value.length > schema.maxItems) return `${at} holds more than ${schema.maxItems} item(s)`;
+    for (const [i, item] of value.entries()) {
+      const fault = checkAgainst(schema.items, item, `${at}[${i}]`);
+      if (fault !== null) return fault;
+    }
+    return null;
+  }
+  return `${at}: unsupported schema type ${schema.type}`;
+};
+
+export const validateArgs = (name, args) => {
+  const tool = toolByName(name);
+  if (tool === undefined) return { ok: false, message: `Unknown tool: ${name}` };
+  const fault = checkAgainst(tool.inputSchema, args, 'arguments');
+  return fault === null ? { ok: true, value: args } : { ok: false, message: fault };
+};
+
+export const toolArgv = (name, args) => {
+  if (!Object.hasOwn(RUNTIME, name)) throw rpcError(JSONRPC_ERRORS.INVALID_PARAMS, `Unknown tool: ${name}`);
+  return RUNTIME[name].argv(args);
+};
+
+// Reader outcome → tool result. 0 and 3 (INCOMPLETE, the reader names the bound in its own stdout)
+// are answers; 1 (I/O or containment refusal) and 2 (usage) are errors carrying the reader's stderr.
+export const toToolResult = (r) => {
+  const isError = !(r.code === 0 || r.code === 3);
+  const text = isError ? (r.stderr || r.stdout) : r.stdout;
+  return { content: [{ type: 'text', text }], isError };
+};
+
+export const callTool = (name, args, root) => {
+  if (!Object.hasOwn(RUNTIME, name)) throw rpcError(JSONRPC_ERRORS.INVALID_PARAMS, `Unknown tool: ${name}`);
+  const verdict = validateArgs(name, args);
+  if (!verdict.ok) throw rpcError(JSONRPC_ERRORS.INVALID_PARAMS, `${name}: ${verdict.message}`);
+  return toToolResult(RUNTIME[name].main(toolArgv(name, verdict.value), { cwd: root }));
+};
+
+const usage = (message) => Object.assign(new Error(message), { exitCode: EXIT_USAGE });
+
+export const parseArgv = (argv) => {
+  const opts = { root: null, selfCheck: false, help: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--help' || arg === '-h') opts.help = true;
+    else if (arg === '--self-check') opts.selfCheck = true;
+    else if (arg === '--root') {
+      i += 1;
+      // An EMPTY value is refused: `'' ?? env` keeps the empty string, and resolve(cwd, '') is the cwd —
+      // a silent override of a correct CLAUDE_PROJECT_DIR by whatever directory the client started in.
+      if (argv[i] === undefined || argv[i] === '') throw usage('--root requires a non-empty value');
+      opts.root = argv[i];
+    } else throw usage(`unknown argument: ${arg} (see --help)`);
+  }
+  return opts;
+};
+
+export const resolveRoot = ({ argv = [], env = {}, cwd }) => {
+  const opts = parseArgv(argv);
+  const fromEnv = typeof env[ROOT_ENV] === 'string' && env[ROOT_ENV] !== '' ? env[ROOT_ENV] : null;
+  // The same rule as a tool argument: a lone surrogate would reach the filesystem as U+FFFD and pick
+  // a DIFFERENT existing directory as the root. EVERY string resolve() will see is checked — the flag,
+  // the env value and the cwd a relative candidate resolves against — not only the one selected.
+  for (const [source, value] of [['--root', opts.root], [ROOT_ENV, fromEnv], ['cwd', cwd]]) {
+    if (value === null) continue;
+    if (typeof value !== 'string' || !value.isWellFormed()) throw usage(`${source} must be a well-formed Unicode string (no lone surrogate)`);
+  }
+  const candidate = opts.root ?? fromEnv ?? cwd;
+  let real;
+  try {
+    real = realpathSync(resolve(cwd, candidate));
+  } catch (err) {
+    throw usage(`root does not exist: ${candidate} (${err?.code ?? err?.message ?? err})`);
+  }
+  if (!statSync(real).isDirectory()) throw usage(`root is not a directory: ${candidate}`);
+  return real;
+};
+
+// The kit's package version, informational: an unreadable or versionless package.json degrades to 0.0.0.
+export const readServerVersion = (readFile = readFileSync) => {
+  try {
+    return JSON.parse(readFile(new URL('../package.json', import.meta.url), 'utf8')).version ?? '0.0.0';
+  } catch {
+    return '0.0.0';
+  }
+};
+
+export const createServer = ({ root }) =>
+  createDispatcher({
+    serverInfo: { name: SERVER_NAME, version: readServerVersion() },
+    capabilities: { tools: {} },
+    instructions: INSTRUCTIONS,
+    handlers: {
+      'tools/list': () => ({ tools: TOOLS }),
+      'tools/call': (params) => {
+        if (typeof params.name !== 'string') throw rpcError(JSONRPC_ERRORS.INVALID_PARAMS, 'tools/call: "name" must be a string');
+        return callTool(params.name, params.arguments ?? {}, root);
+      },
+    },
+  });
+
+// In-process round trip through the SAME transport and dispatcher a client drives: the installed bytes
+// load, the handshake answers, both tools answer a call rooted here. No process is spawned.
+export const selfCheck = async ({ root }) => {
+  const input = new PassThrough();
+  const lines = [];
+  const done = serveStdio({ input, output: { write: (t) => lines.push(t) }, dispatcher: createServer({ root }) });
+  const requests = [
+    { jsonrpc: '2.0', id: 1, method: 'initialize', params: { protocolVersion: '2025-06-18', capabilities: {}, clientInfo: { name: 'self-check', version: '0' } } },
+    { jsonrpc: '2.0', method: 'notifications/initialized' },
+    { jsonrpc: '2.0', id: 2, method: 'tools/list' },
+    { jsonrpc: '2.0', id: 3, method: 'tools/call', params: { name: 'path_inventory', arguments: { paths: ['.'] } } },
+    { jsonrpc: '2.0', id: 4, method: 'tools/call', params: { name: 'repo_search', arguments: { pattern: '2>/dev/null', paths: ['.'], max: 1 } } },
+  ];
+  input.end(requests.map((r) => `${JSON.stringify(r)}\n`).join(''));
+  await done;
+  const answers = lines.map((l) => JSON.parse(l));
+  const byId = (id) => answers.find((a) => a.id === id);
+  const checks = [
+    ['initialize answered', byId(1)?.result?.protocolVersion !== undefined],
+    ['tools/list names both tools', JSON.stringify(byId(2)?.result?.tools?.map((t) => t.name)) === JSON.stringify(TOOLS.map((t) => t.name))],
+    ['path_inventory answers', byId(3)?.result?.isError === false],
+    ['repo_search answers a shell-significant pattern', byId(4)?.result?.isError === false],
+  ];
+  const ok = checks.every(([, passed]) => passed);
+  const report = [...checks.map(([label, passed]) => `  ${passed ? 'ok ' : 'FAIL'} ${label}`), `self-check: ${ok ? 'OK' : 'FAILED'} (root ${root})`];
+  return { ok, report };
+};
+
+const HELP = `mcp-server — the kit's stdio MCP server (server name "${SERVER_NAME}").
+
+Tools: ${TOOLS.map((t) => t.name).join(', ')} — the kit's read-only path inventory and literal search,
+reached through typed JSON fields instead of a shell string.
+Usage:
+  node mcp-server.mjs [--root <dir>]      serve JSON-RPC over stdin/stdout until stdin closes
+  node mcp-server.mjs --self-check        in-process handshake + one call per tool, exit 0 on success
+Root = --root > env ${ROOT_ENV} > cwd; every path is contained to it on the REAL path.
+Exit codes: 0 served / self-check passed · 1 self-check failed · 2 usage.`;
+
+export const main = async (argv, deps = {}) => {
+  const out = deps.stdout ?? process.stdout;
+  const err = deps.stderr ?? process.stderr;
+  try {
+    const opts = parseArgv(argv);
+    if (opts.help) {
+      out.write(`${HELP}\n`);
+      return EXIT_OK;
+    }
+    const root = resolveRoot({ argv, env: deps.env ?? process.env, cwd: deps.cwd ?? process.cwd() });
+    if (opts.selfCheck) {
+      const result = await selfCheck({ root });
+      out.write(`${result.report.join('\n')}\n`);
+      return result.ok ? EXIT_OK : EXIT_FAILED;
+    }
+    await serveStdio({ input: deps.stdin ?? process.stdin, output: out, dispatcher: createServer({ root }) });
+    return EXIT_OK;
+  } catch (e) {
+    err.write(`mcp-server: ${e?.message ?? e}\n`);
+    return e?.exitCode ?? EXIT_FAILED;
+  }
+};
+
+if (isDirectRun(import.meta.url)) {
+  main(process.argv.slice(2)).then((code) => {
+    process.exitCode = code;
+  });
+}

package/tools/mcp-stdio.mjs

@@ -0,0 +1,229 @@
+// mcp-stdio.mjs — JSON-RPC 2.0 line framing for the kit's stdio MCP server (the transport half).
+//
+// The MCP stdio transport is newline-delimited JSON-RPC over stdin/stdout: one message per line, no
+// embedded newline, UTF-8, nothing on stdout that is not a message. This module owns exactly that and
+// nothing about tools: a bounded line reader, the request/notification/response classification, the
+// lifecycle gate (initialize first, ping any time) and a dispatcher that turns a parsed message into
+// ONE response object or null. Streams are INJECTED so the whole contract is testable without a process.
+//
+// Bounds, stated: a line longer than `maxLineBytes` is answered with -32600 (id null) and the transport
+// then CLOSES — a null-id error cannot be correlated with the request that caused it, so a client would
+// otherwise wait on it forever, while a server that exits is one it can restart. (The line reader itself
+// can resync at the next newline; the transport chooses not to continue.) Bytes are buffered and decoded
+// only per complete line, so a UTF-8 code point split across two chunks is never replaced. Dependency-
+// free, Node >= 22, no side effects on import; no CLI of its own (mcp-server.mjs is the entry point).
+
+export const PROTOCOL_VERSION = '2025-06-18';
+// Newest first. A requested version in this set is echoed; anything else is answered with the newest,
+// as the lifecycle spec prescribes (the client then decides whether to continue).
+export const SUPPORTED_PROTOCOL_VERSIONS = Object.freeze(['2025-06-18', '2025-03-26', '2024-11-05']);
+export const MAX_LINE_BYTES = 4 * 1024 * 1024;
+export const JSONRPC_ERRORS = Object.freeze({
+  PARSE_ERROR: -32700,
+  INVALID_REQUEST: -32600,
+  METHOD_NOT_FOUND: -32601,
+  INVALID_PARAMS: -32602,
+  INTERNAL_ERROR: -32603,
+});
+
+const JSONRPC_VERSION = '2.0';
+const NEWLINE = 0x0a;
+const CARRIAGE_RETURN = 0x0d;
+const METHOD_INITIALIZE = 'initialize';
+const METHOD_PING = 'ping';
+const PRE_INITIALIZE_METHODS = Object.freeze([METHOD_INITIALIZE, METHOD_PING]);
+
+export const rpcError = (code, message) => Object.assign(new Error(message), { rpcCode: code });
+
+const isPlainObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+// MCP's RequestId is a string or an integer, never null; and a numeric id must survive parse →
+// serialize unchanged, or the answer no longer correlates with the request: only a safe integer does
+// (1.5, 1e400 and friends are refused as invalid requests). The server's OWN null id on an error
+// for an unparseable line is a different thing: a response, not a request.
+const isValidId = (id) => typeof id === 'string' || Number.isSafeInteger(id);
+// A client RESPONSE carries an id and exactly one of result / error; it is the one shape the server
+// never answers. Anything else without a method is an invalid request, answered — never swallowed.
+const isClientResponse = (message) =>
+  'id' in message && (Object.hasOwn(message, 'result') !== Object.hasOwn(message, 'error'));
+
+export const negotiateProtocolVersion = (requested) =>
+  SUPPORTED_PROTOCOL_VERSIONS.includes(requested) ? requested : PROTOCOL_VERSION;
+
+export const isNotification = (message) => typeof message.method === 'string' && !('id' in message);
+
+// One line → { message } or { error: { code, message } } (the error is answered with id null).
+export const parseLine = (line) => {
+  let parsed;
+  try {
+    parsed = JSON.parse(line);
+  } catch {
+    return { error: { code: JSONRPC_ERRORS.PARSE_ERROR, message: 'Parse error' } };
+  }
+  if (!isPlainObject(parsed) || parsed.jsonrpc !== JSONRPC_VERSION) {
+    return { error: { code: JSONRPC_ERRORS.INVALID_REQUEST, message: 'Invalid Request: not a JSON-RPC 2.0 object' } };
+  }
+  if ('id' in parsed && !isValidId(parsed.id)) {
+    return { error: { code: JSONRPC_ERRORS.INVALID_REQUEST, message: 'Invalid Request: id must be a string or an integer' } };
+  }
+  if ('method' in parsed && typeof parsed.method !== 'string') {
+    return { error: { code: JSONRPC_ERRORS.INVALID_REQUEST, message: 'Invalid Request: method must be a string' } };
+  }
+  return { message: parsed };
+};
+
+const errorResponse = (id, code, message) => ({ jsonrpc: JSONRPC_VERSION, id, error: { code, message } });
+const resultResponse = (id, result) => ({ jsonrpc: JSONRPC_VERSION, id, result });
+
+// A lossy decode would replace an invalid byte with U+FFFD and the request could then name a DIFFERENT,
+// existing path — the substitution class both readers refuse; a line that is not UTF-8 is a parse error.
+const strictUtf8 = new TextDecoder('utf-8', { fatal: true });
+
+// Bytes in, complete lines out. The pending buffer is capped: past `maxLineBytes` without a newline the
+// reader drops bytes until the next newline, reporting the overflow ONCE, then frames normally again.
+export const createLineReader = ({ maxLineBytes = MAX_LINE_BYTES, onLine, onOverflow, onInvalidUtf8 = () => {} }) => {
+  let pending = [];
+  let pendingBytes = 0;
+  let discarding = false;
+
+  const emit = () => {
+    const buf = Buffer.concat(pending, pendingBytes);
+    pending = [];
+    pendingBytes = 0;
+    const end = buf.length > 0 && buf[buf.length - 1] === CARRIAGE_RETURN ? buf.length - 1 : buf.length;
+    let text;
+    try {
+      text = strictUtf8.decode(buf.subarray(0, end));
+    } catch {
+      onInvalidUtf8();
+      return;
+    }
+    onLine(text);
+  };
+
+  const feed = (chunk) => {
+    let from = 0;
+    for (;;) {
+      const at = chunk.indexOf(NEWLINE, from);
+      const piece = chunk.subarray(from, at === -1 ? chunk.length : at);
+      if (discarding) {
+        if (at === -1) return;
+        discarding = false;
+      } else if (pendingBytes + piece.length > maxLineBytes) {
+        pending = [];
+        pendingBytes = 0;
+        onOverflow();
+        if (at === -1) {
+          discarding = true;
+          return;
+        }
+      } else {
+        if (piece.length > 0) {
+          pending.push(piece);
+          pendingBytes += piece.length;
+        }
+        if (at === -1) return;
+        emit();
+      }
+      from = at + 1;
+      if (from >= chunk.length) return;
+    }
+  };
+
+  // A final line without a trailing newline is still a message; a discarded tail is not.
+  const end = () => {
+    if (!discarding && pendingBytes > 0) emit();
+  };
+
+  return { feed, end };
+};
+
+// handlers: { [method]: (params) => result } for everything beyond initialize/ping. A handler may throw
+// rpcError(code, message) for a typed error; any other throw is an internal error WITH its message.
+export const createDispatcher = ({ handlers = {}, serverInfo, capabilities = { tools: {} }, instructions }) => {
+  let initialized = false;
+
+  const handle = (message) => {
+    if (typeof message.method !== 'string') {
+      if (isClientResponse(message)) return null; // a response to something — never answered
+      return errorResponse(message.id ?? null, JSONRPC_ERRORS.INVALID_REQUEST, 'Invalid Request: neither a request, a notification nor a response');
+    }
+    if (isNotification(message)) return null; // initialized, cancelled, anything: silence
+    const { id, method } = message;
+    if ('params' in message && message.params !== undefined && !isPlainObject(message.params)) {
+      return errorResponse(id, JSONRPC_ERRORS.INVALID_PARAMS, `Invalid params: "${method}" params must be an object`);
+    }
+    if (!initialized && !PRE_INITIALIZE_METHODS.includes(method)) {
+      return errorResponse(id, JSONRPC_ERRORS.INVALID_REQUEST, `Invalid Request: "${method}" before initialize`);
+    }
+    if (method === METHOD_PING) return resultResponse(id, {});
+    if (method === METHOD_INITIALIZE) {
+      // The three required fields are checked BEFORE the state flips: a malformed initialize leaves the
+      // server un-initialized and is answered as invalid params, never served as a handshake.
+      const params = isPlainObject(message.params) ? message.params : null;
+      const client = params !== null && isPlainObject(params.clientInfo) ? params.clientInfo : null;
+      if (params === null || typeof params.protocolVersion !== 'string' || !isPlainObject(params.capabilities) || client === null || typeof client.name !== 'string' || typeof client.version !== 'string') {
+        return errorResponse(id, JSONRPC_ERRORS.INVALID_PARAMS, 'initialize: protocolVersion (string), capabilities (object) and clientInfo { name, version } (strings) are required');
+      }
+      initialized = true;
+      const result = { protocolVersion: negotiateProtocolVersion(params.protocolVersion), capabilities, serverInfo };
+      if (typeof instructions === 'string') result.instructions = instructions;
+      return resultResponse(id, result);
+    }
+    const handler = Object.hasOwn(handlers, method) ? handlers[method] : undefined;
+    if (typeof handler !== 'function') return errorResponse(id, JSONRPC_ERRORS.METHOD_NOT_FOUND, `Method not found: ${method}`);
+    try {
+      return resultResponse(id, handler(isPlainObject(message.params) ? message.params : {}));
+    } catch (err) {
+      if (typeof err?.rpcCode === 'number') return errorResponse(id, err.rpcCode, err.message);
+      return errorResponse(id, JSONRPC_ERRORS.INTERNAL_ERROR, `Internal error: ${err?.message ?? err}`);
+    }
+  };
+
+  return { handle };
+};
+
+// Serve until the input ends. `input` is an async iterable of Buffers (process.stdin, a PassThrough),
+// `output` anything with write(string) — and, when it also has once(), its backpressure is honoured:
+// a write that returns false stops the flush until 'drain', so a run of large answers never piles up
+// unbounded in process memory. Every write is exactly one JSON document plus "\n" — JSON.stringify
+// escapes every newline inside strings, so no message ever embeds one.
+export const serveStdio = async ({ input, output, dispatcher, maxLineBytes = MAX_LINE_BYTES }) => {
+  // The reader only QUEUES framed lines (bounded by the chunk size); each line is dispatched and its
+  // answer written one at a time, with the drain wait BETWEEN lines — so a chunk holding many compact
+  // requests never has all their answers computed and held in memory at once.
+  const pending = [];
+  const reader = createLineReader({
+    maxLineBytes,
+    onOverflow: () => pending.push({ overflow: true }),
+    onInvalidUtf8: () => pending.push({ invalidUtf8: true }),
+    onLine: (line) => pending.push({ line }),
+  });
+  const answerFor = (entry) => {
+    if (entry.overflow) return errorResponse(null, JSONRPC_ERRORS.INVALID_REQUEST, `Invalid Request: line exceeds ${maxLineBytes} byte(s) — the transport is closing; restart the server`);
+    if (entry.invalidUtf8) return errorResponse(null, JSONRPC_ERRORS.PARSE_ERROR, 'Parse error: the line is not valid UTF-8');
+    if (entry.line.trim() === '') return null;
+    const parsed = parseLine(entry.line);
+    if (parsed.error) return errorResponse(null, parsed.error.code, parsed.error.message);
+    return dispatcher.handle(parsed.message);
+  };
+  // Returns true once the transport must close: a null-id overflow error cannot be correlated, so
+  // nothing after it is served — not even the rest of the same chunk.
+  const drainPending = async () => {
+    while (pending.length > 0) {
+      const entry = pending.shift();
+      const response = answerFor(entry);
+      if (response !== null) {
+        const accepted = output.write(`${JSON.stringify(response)}\n`);
+        if (accepted === false && typeof output.once === 'function') await new Promise((resolve) => output.once('drain', resolve));
+      }
+      if (entry.overflow) return true;
+    }
+    return false;
+  };
+  for await (const chunk of input) {
+    reader.feed(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    if (await drainPending()) return;
+  }
+  reader.end();
+  await drainPending();
+};