Skip to content

Local-first 🧠 memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.

TypeScript
20.1 KB
Raw Blame
/**
 * Newline-delimited JSON stdio loop for the MCP server.
 *
 * Mirrors `serve_stdio` from the legacy Python implementation. The server
 * only writes JSON-RPC frames to stdout; logs go to stderr.
 *
 * ## Shutdown
 *
 * The loop had no shutdown path at all: a SIGTERM took the default
 * disposition and killed the process wherever it happened to be, which
 * for a `tools/call` is mid-dispatch with no frame written. It now shares
 * the HTTP transport's register (`./drain.ts`): a drain stops the loop at
 * a request boundary and waits for every request it has accepted - under
 * the bounded parallel reads that can be several at once, and including a
 * write still parked behind them - and only then closes the reader.
 * Nothing here handles a signal - that
 * belongs to the CLI, which owns the process (`src/cli/mcp-drain.ts`).
 */

import { createInterface } from "node:readline";
import type { Readable, Writable } from "node:stream";

import { MCPServer, type MCPServerOptions, type MCPServerRuntimeOptions } from "./server.ts";
import { errorResponse, internalErrorResponse, type JsonRpcResponse } from "./server.ts";
import { INVALID_REQUEST, PARSE_ERROR, type JsonRpcNotification } from "./protocol.ts";
import { RequestDrain, resolveDrainDeadlineMs, type DrainOutcome } from "./drain.ts";
import { ORIGIN_CHANNEL, setOriginChannel } from "../core/origin-channel.ts";
import { TRANSPORT_REACH, type TransportReach } from "../core/graph/transport-reach.ts";

/**
 * What a stdio connection establishes about its caller.
 *
 * `local`, and the reason is the process tree rather than the protocol:
 * this transport is spoken over the stdin and stdout of a process the
 * caller started, so the caller already holds whatever filesystem access
 * that process runs with. It does NOT prove operator intent - a remote
 * host can spawn a stdio subprocess - and the alternative, minting
 * `remote` here, would take an operator's own reserved pages away from
 * their own editor and their own CLI. The limit is stated rather than
 * papered over; see `src/core/graph/transport-reach.ts`.
 */
export const STDIO_TRANSPORT_REACH: TransportReach = TRANSPORT_REACH.local;

/**
 * Any frame this transport writes: a response to a request, or a
 * notification the server sent on its own initiative (today, progress).
 */
type OutboundFrame = JsonRpcResponse | JsonRpcNotification;

/**
 * The shutdown handle for a running stdio loop.
 *
 * The same two members the HTTP handle exposes, so `src/cli/mcp-drain.ts`
 * wires one signal handler for both transports rather than one each. It
 * is handed to {@link ServeStdioOptions.onStart} rather than returned,
 * because this loop does not return until it is over.
 */
export interface StdioTransportHandle {
  readonly drain: RequestDrain;
  /** The reach this transport minted for every request it will carry. */
  readonly reach: TransportReach;
  /** Stop reading new lines, await the in-flight request, end the loop. */
  close(): Promise<DrainOutcome>;
}

export interface ServeStdioOptions {
  readonly stdin?: Readable;
  readonly stdout?: Writable;
  readonly stderr?: Writable;
  /** Defaults to `O2B_MCP_DRAIN_MS`, and to ten seconds without it. */
  readonly drainDeadlineMs?: number;
  /** Called once the loop is live, with the handle that shuts it down. */
  readonly onStart?: (handle: StdioTransportHandle) => void;
  /**
   * Dispatch against this server instead of the one the loop builds.
   *
   * The loop still claims the origin channel, reads the stream and
   * writes every frame; a caller passing a server owns everything else
   * about it - its `sendNotification` wiring and its reach (tests, which
   * need handlers they can hold and release). Production callers leave
   * this unset: the built server is how the transport facts get set
   * after the caller's options, and no production caller can supply a
   * server that carries them.
   */
  readonly server?: MCPServer;
}

/**
 * How many read-classified requests the production loop keeps in flight
 * at once.
 *
 * A constant, not a knob: the number exists to bound this process's
 * concurrent SQLite read connections and its share of the event loop
 * under one slow read, and four answers that for every host this
 * transport runs on. The loop backpressures at the cap - it does not
 * read another line until a slot frees - so the bound holds by
 * construction, not by cooperation. Writes never consume a slot: they
 * run alone behind the write gate below.
 */
export const STDIO_READ_CONCURRENCY = 4;

/**
 * The in-loop write gate: a FIFO async mutex every write-classified
 * dispatch passes through.
 *
 * Dispatch-only by design rule: the gate lives HERE, in the transport
 * loop, never inside a core handler - `brain_write_batch` composes write
 * kernels, so a lower-level lock would self-block the one caller that
 * most needs writes to work. One write runs at a time (FIFO, in arrival
 * order), and - because the same loop is the only reader - the loop does
 * not read another line until the write it dispatched has settled, so no
 * read starts beside a running write either; the gate's dispatch body
 * additionally waits for the reads already in flight to settle first.
 * Cross-request frame order is thereby surrendered in one direction
 * only: reads may complete and be written out of arrival order, which is
 * JSON-RPC-legal, while every write keeps its arrival order and runs
 * exclusively. Clients correlate out-of-order responses by id and
 * interleaved progress by progress token.
 */
class WriteGate {
  #tail: Promise<void> = Promise.resolve();

  run(body: () => Promise<void>): Promise<void> {
    const run = this.#tail.then(body);
    this.#tail = run.then(
      () => undefined,
      () => undefined,
    );
    return run;
  }
}

/**
 * Stream-based stdio loop. Resolves to 0 on normal EOF.
 *
 * The implementation reads line-by-line and dispatches each line as a
 * JSON-RPC request. Invalid JSON yields a `-32700` parse-error response;
 * batch requests (an array at the top level) yield a `-32600` invalid-request
 * response, matching the 2025-06-18 spec which removed batch support.
 *
 * Reads (everything `MCPServer.classifiesWrite` declines) are dispatched
 * without being awaited, up to {@link STDIO_READ_CONCURRENCY} in flight;
 * the loop backpressures on a free slot before reading further lines.
 * Writes run one at a time through {@link WriteGate}. Every response is
 * written inside its own drain window: a read is tracked from its
 * dispatch, a write from its ACCEPTANCE - before it parks behind the
 * gate - so a drain that starts while the write is parked waits for it,
 * and no request is marked finished before its answer frame is queued.
 */
export async function serveStdio(
  ctx: MCPServerOptions,
  ioOpts: ServeStdioOptions = {},
  runtimeOpts: MCPServerRuntimeOptions = {},
): Promise<number> {
  // This process serves MCP tool calls, so it claims the `mcp-tool`
  // origin channel for every record written under it (Unit C). Claimed at
  // the TRANSPORT and not in the `MCPServer` constructor: `o2b tool-call`
  // and the MCP probe build a server to invoke a handler from a shell, and
  // stamping those `mcp-tool` would name a transport that carried nothing.
  // Redundant when `o2b mcp` started us - it claimed the same value - and
  // load-bearing when a host embeds this transport directly.
  setOriginChannel(ORIGIN_CHANNEL.mcpTool);
  const stdin = ioOpts.stdin ?? process.stdin;
  const stdout = ioOpts.stdout ?? process.stdout;
  // This transport owns a duplex stream, so it CAN write a frame nobody
  // asked for - which is what lets a `tools/call` carrying a progress
  // token be answered with live notifications instead of a refusal. Set
  // after the caller's options so a transport fact cannot be overridden
  // by a runtime option. The test-supplyable `ioOpts.server` bypasses
  // this constructor on purpose; see its docblock.
  const server =
    ioOpts.server ??
    new MCPServer(ctx, {
      ...runtimeOpts,
      sendNotification: (notification) => writeFrame(stdout, notification),
      // A transport fact, so it is set after the caller's options for the
      // same reason `sendNotification` is: a runtime option must not be
      // able to claim a reach this transport did not establish.
      reach: STDIO_TRANSPORT_REACH,
    });
  const rl = createInterface({ input: stdin, crlfDelay: Infinity });

  const drain = new RequestDrain();
  const deadlineMs = ioOpts.drainDeadlineMs ?? resolveDrainDeadlineMs(process.env);
  ioOpts.onStart?.({
    drain,
    reach: STDIO_TRANSPORT_REACH,
    close: async () => {
      // The wait comes first and the reader is closed after it: closing
      // the interface while a `tools/call` is still running would end the
      // loop before its response frame was written, which is the stdio
      // shape of the truncated HTTP response this unit removes. The
      // register holds every dispatched request - parallel reads included
      // - so this wait covers the whole in-flight set.
      const outcome = await drain.drain(deadlineMs);
      rl.close();
      return outcome;
    },
  });

  // One dispatch, read or write alike: the response write stays INSIDE
  // the tracked window, so a request is never marked finished before its
  // frame is queued (the drain could otherwise end the loop between the
  // dispatch and the answer). The window's `finish` is handed in rather
  // than opened here because the two paths open it at different moments:
  // a read at its dispatch, a WRITE at its acceptance - before it parks
  // behind the gate - so a drain that starts while the write is parked
  // already sees it (see dispatchWrite).
  const dispatch = async (request: Record<string, unknown>, finish: () => void): Promise<void> => {
    try {
      const response = await server.handleRequest(request);
      if (response !== null) writeFrame(stdout, response);
    } catch (exc) {
      // A dispatch failure still answers its id. An unanswered request is
      // worse than a failed one - the caller waits for a correlation that
      // never arrives - so the catch frames the error here rather than
      // letting the rejection escape into the bookkeeping below. The
      // dispatcher's own INTERNAL_ERROR builder, the same framing the
      // HTTP catch-all uses: the prose goes through the redactor for this
      // transport's reach, and the code comes from the classifier. A
      // NOTIFICATION has no id to answer, so it gets no frame: the
      // dispatcher itself returns null for a failed notification rather
      // than an `id: null` error, and this catch-all mirrors that instead
      // of writing a response to a frame that was never a request.
      if ("id" in request) {
        writeFrame(stdout, internalErrorResponse(request["id"], exc, server.vault, server.reach));
      }
    } finally {
      finish();
    }
  };

  // The read path. `readsInFlight` is the slot count; the loop is the
  // only reader, so the single-waiter `slotFreed` release is enough.
  const readPromises = new Set<Promise<void>>();
  let readsInFlight = 0;
  let slotFreed: (() => void) | null = null;
  const dispatchRead = (request: Record<string, unknown>): void => {
    // Swallowed ONCE, here, and every hook below derived from the
    // swallow. Deriving the bookkeeping from the RAW promise - a bare
    // `void run.finally(...)` beside a swallowed `run` - creates a SECOND
    // promise that rejects when `run` does, and voiding it leaves an
    // unhandled rejection the runtime kills the process for, while the
    // request it belongs to never sees an error frame. The set holds the
    // settled twin, so every `Promise.all` over it (the write gate's
    // wait, this loop's exit barrier) stays rejection-free by
    // construction.
    const run = dispatch(request, drain.begin(requestLabel(request))).then(
      () => undefined,
      () => undefined,
    );
    readPromises.add(run);
    readsInFlight++;
    void run.finally(() => {
      readsInFlight--;
      readPromises.delete(run);
      slotFreed?.();
      slotFreed = null;
    });
  };

  // The write path. The loop awaits each write, so one write is in
  // flight at a time and no further line is read until it settles; the
  // gate is the FIFO order, and its body first waits out the reads that
  // were already running when the write arrived.
  const writeGate = new WriteGate();
  const writePromises = new Set<Promise<void>>();
  const dispatchWrite = (request: Record<string, unknown>): Promise<void> => {
    // The drain window opens at ACCEPTANCE, not when the write finally
    // dispatches. A write that arrives while reads are in flight parks in
    // the gate body below until they settle, and a write left unregistered
    // through that park was invisible to a drain: a SIGTERM in the window
    // watched the reads empty the register, resolved `drained`, and the
    // CLI exited - leaving the write to run afterward, its mutation landed
    // with no response ever delivered. Begun here, the write holds the
    // drain open from the moment the loop accepted it and is named in a
    // deadline report that beats it; `finish` is idempotent, and the
    // window closes when the response frame is written, inside `dispatch`.
    const finish = drain.begin(requestLabel(request));
    // Swallowed once, for the same reason the read path swallows: the
    // gate body can only settle cleanly when every promise it waits on
    // does, and the loop awaits this twin - a rejection here would fall
    // out of the `for await` and kill the loop a framed error already
    // answered for.
    const run = writeGate
      .run(async () => {
        while (readPromises.size > 0) {
          await Promise.all(readPromises);
        }
        await dispatch(request, finish);
      })
      .then(
        () => undefined,
        () => undefined,
      );
    writePromises.add(run);
    void run.finally(() => {
      writePromises.delete(run);
    });
    return run;
  };

  // EOF, a drain break and `rl.close()` all leave this loop only after
  // every dispatched request has settled: the exit hooks that run after
  // `serveStdio` returns (the search store WAL checkpoint, the
  // sync-lockfile unlink) must never run under floating handlers.
  try {
    readLoop: for await (const rawLine of rl) {
      // Stopped accepting. A line that arrives after a drain has started
      // is left unread rather than answered with an error frame: the
      // client is being disconnected either way, and a half-served
      // shutdown that replies to some requests and not others is harder
      // to reason about than one that stops cleanly at a request
      // boundary.
      if (drain.draining) break;
      const line = rawLine.trim();
      if (!line) continue;
      let request: unknown;
      try {
        request = JSON.parse(line);
      } catch (exc) {
        writeFrame(
          stdout,
          errorResponse(null, PARSE_ERROR, `invalid JSON: ${(exc as Error).message}`),
        );
        continue;
      }
      if (Array.isArray(request)) {
        writeFrame(
          stdout,
          errorResponse(
            null,
            INVALID_REQUEST,
            "batch requests are not supported by the 2025-06-18 spec",
          ),
        );
        continue;
      }
      if (typeof request !== "object" || request === null) {
        writeFrame(stdout, errorResponse(null, INVALID_REQUEST, "request must be an object"));
        continue;
      }
      const record = request as Record<string, unknown>;
      if (server.classifiesWrite(record)) {
        // oxlint-disable-next-line no-await-in-loop -- the await IS the write gate: no new line is read while a write runs
        await dispatchWrite(record);
      } else {
        while (readsInFlight >= STDIO_READ_CONCURRENCY) {
          // oxlint-disable-next-line no-await-in-loop -- backpressure: hold at the cap before reading further lines
          await new Promise<void>((resolve) => {
            slotFreed = resolve;
          });
          // The park sits between the drain-break check above and the
          // dispatch below, so the boundary is re-checked once it is
          // over: this line was read BEFORE the drain began, but it was
          // held behind a full cap, and dispatching it after the drain
          // resolved would serve it outside the drain's wait - past
          // `rl.close()`, where the client may have stopped reading. So
          // it is left unread, under the same rule the check at the top
          // of the loop states: a line that arrives after a drain has
          // started is not answered.
          if (drain.draining) break readLoop;
        }
        dispatchRead(record);
      }
    }
  } finally {
    await Promise.all([...readPromises, ...writePromises]);
  }
  return 0;
}

/** How one in-flight stdio request is named in a drain report. */
function requestLabel(request: Record<string, unknown>): string {
  const method = typeof request["method"] === "string" ? request["method"] : "(no method)";
  const id = request["id"];
  return id === undefined ? method : `${method} (id ${JSON.stringify(id)})`;
}

/**
 * One frame as the single line this protocol delimits by.
 *
 * Shared by both loops below so a notification and a response are framed
 * by identical code: the format is the contract, and two copies of it
 * could drift apart the moment one of them gained a case.
 */
function frameLine(frame: OutboundFrame): string {
  const line = JSON.stringify(frame);
  return line.includes("\n") ? line.replace(/\n/g, " ") : line;
}

/**
 * Write one frame in ONE `write` call, terminator included.
 *
 * That single call is what keeps a progress notification from landing
 * inside a response: `Writable.write` appends the whole string to the
 * stream's queue atomically, so no other frame can be spliced between a
 * frame's body and its newline.
 */
function writeFrame(out: Writable, frame: OutboundFrame): void {
  out.write(frameLine(frame) + "\n");
}

/**
 * Synchronous-style serveStdio fallback for embedded test harnesses that pass
 * an in-memory string buffer instead of a real stream. Tests use this to
 * bypass the readline async iteration.
 *
 * Returns newline-joined output (one JSON-RPC frame per line, trailing newline).
 *
 * It carries notifications on the same terms as the real loop, and
 * frames them through the same {@link frameLine}: a harness that dropped
 * the unsolicited frames would report the progress feature as absent
 * wherever it is used, which is the failure mode this release is about.
 */
export async function serveStdioFromString(
  ctx: MCPServerOptions,
  input: string,
  opts: MCPServerRuntimeOptions = {},
): Promise<string> {
  const out: string[] = [];
  const server = new MCPServer(ctx, {
    ...opts,
    sendNotification: (notification) => out.push(frameLine(notification)),
    reach: STDIO_TRANSPORT_REACH,
  });
  for (const rawLine of input.split("\n")) {
    const line = rawLine.trim();
    if (!line) continue;
    let request: unknown;
    try {
      request = JSON.parse(line);
    } catch (exc) {
      out.push(
        frameLine(errorResponse(null, PARSE_ERROR, `invalid JSON: ${(exc as Error).message}`)),
      );
      continue;
    }
    if (Array.isArray(request)) {
      out.push(
        frameLine(
          errorResponse(
            null,
            INVALID_REQUEST,
            "batch requests are not supported by the 2025-06-18 spec",
          ),
        ),
      );
      continue;
    }
    if (typeof request !== "object" || request === null) {
      out.push(frameLine(errorResponse(null, INVALID_REQUEST, "request must be an object")));
      continue;
    }
    // Sequential on purpose, and not because the transport serializes -
    // the production loop does not. This harness collects its frames
    // positionally: a test that writes "initialize, then tools/call"
    // reads the answers back by index, and running the calls in parallel
    // would shuffle collected frames whose whole meaning is their
    // position. Concurrency semantics belong to {@link serveStdio} and
    // its suite; this loop stays the deterministic harness.
    // oxlint-disable-next-line no-await-in-loop
    const response = await server.handleRequest(request as Record<string, unknown>);
    if (response !== null) out.push(frameLine(response));
  }
  return out.join("\n") + (out.length > 0 ? "\n" : "");
}