@symbols-cli/cli 0.0.1

package/dist/mcp/scopes.js

@@ -0,0 +1,215 @@
+// Copyright (c) 2025 Symbols LLC. All rights reserved.
+//
+// This source code is proprietary and confidential. Unauthorized copying,
+// distribution, modification, or use of this file, via any medium, is strictly prohibited.
+// The read surface the Symbols MCP server may reach, and the matcher that
+// enforces it before anything goes on the wire.
+//
+// ─────────────────────────────────────────────────────────────────────────────
+// ⚠ THE INCIDENT THIS FILE EXISTS TO PREVENT
+// ─────────────────────────────────────────────────────────────────────────────
+// The Python MCP server (`docker/odin-runtime/symbols-mcp/__main__.py`) kept a
+// hand-maintained `SCOPED_PATHS`. On 2026-07-22 the Rust scope list was narrowed
+// and this list was not, so for THREE WEEKS half the advertised tools returned
+// 403/404 — which, from the agent's side, is indistinguishable from "the Symbols
+// tools are not connected". Nobody noticed, because nothing compared the two.
+//
+// So the list below is NOT hand-written. Everything between the GENERATED
+// markers is emitted by:
+//
+//     python3 scripts/check_mcp_scopes.py --write
+//
+// from `apps/server/kernel/shell_token.rs` — specifically the GET half of
+// `SHELL_TOKEN_SCOPES` ∪ `CLI_EXTRA_SCOPES`, which is exactly the read surface
+// `cli_scope_allows` permits a CLI token. The same script, run without `--write`,
+// FAILS when the two disagree in either direction, and it is publish-blocking.
+//
+// Deriving rather than curating is the point. Any hand-picked subset — however
+// sensible — re-opens the drift class, because a subset has no mechanical
+// definition and therefore no mechanical check.
+//
+// ⚠ `nest("/api", …)` strips the prefix server-side, so every template here
+// carries `/api/...`. A template written without it authorises nothing and 403s
+// silently while both lists still look self-consistent.
+/* eslint-disable */
+// ─── GENERATED: SCOPED_PATHS (do not edit by hand) ───────────────────────────
+/**
+ * Every route template a CLI token may GET.
+ *
+ * Derived: `{ t | (GET, t) ∈ SHELL_TOKEN_SCOPES ∪ CLI_EXTRA_SCOPES }`.
+ */
+export const SCOPED_PATHS = [
+    "/api/quote/{symbol}",
+    "/api/quotes",
+    "/api/chart/pricing-data",
+    "/api/chart/sparklines",
+    "/api/options/chart-pricing",
+    "/api/levels/{ticker}",
+    "/api/scan/catalog",
+    "/api/scan/presets",
+    "/api/scan/sectors",
+    "/api/research/papers/search",
+    "/api/research/papers/tags",
+    "/api/research/papers/graph",
+    "/api/research/papers/topic-graph",
+    "/api/research/papers/stats",
+    "/api/research/papers/{resource_id}",
+    "/api/flow/alerts",
+    "/api/flow/analysts",
+    "/api/flow/congress",
+    "/api/flow/darkpool",
+    "/api/flow/economic-calendar",
+    "/api/flow/fda-calendar",
+    "/api/flow/gex",
+    "/api/flow/gex-aggregate",
+    "/api/flow/gex-expiry",
+    "/api/flow/headlines",
+    "/api/flow/insider",
+    "/api/flow/market-tide",
+    "/api/flow/max-pain",
+    "/api/flow/oi-change",
+    "/api/flow/options-volume",
+    "/api/flow/sector-etfs",
+    "/api/flow/spot-exposures",
+    "/api/flow/vol-realized",
+    "/api/flow/vol-stats",
+    "/api/flow/vol-term",
+    "/api/company/profile/{symbol}",
+    "/api/earnings/{symbol}",
+    "/api/earnings/{symbol}/uw",
+    "/api/ratios/{symbol}",
+    "/api/financial-statements/{symbol}",
+    "/api/regimes",
+    "/api/regimes/stats",
+    "/api/regimes/by-symbol/{symbol}",
+    "/api/regimes/{regime_id}",
+    "/api/regimes/{regime_id}/with-stats",
+    "/api/regimes/{regime_id}/health",
+    "/api/regime-trades",
+    "/api/regime-trades/{trade_id}",
+    "/api/regime-trades/regime/{regime_id}",
+    "/api/regime-trades/regime/{regime_id}/open",
+    "/api/regime-trades/regime/{regime_id}/stats",
+    "/api/regime-executions/{execution_id}",
+    "/api/regime-executions/{execution_id}/with-trades",
+    "/api/regime-executions/regime/{regime_id}",
+    "/api/regime-executions/regime/{regime_id}/latest",
+    "/api/regime-executions/regime/{regime_id}/running",
+    "/api/regime-executions/regime/{regime_id}/stats",
+    "/api/feeds/status",
+    "/api/data-pipeline/tickers",
+    "/api/odin-code/brokerage/snapshot",
+    "/api/odin-code/brokerage/history",
+    "/api/notebooks/{notebook_id}/files",
+    "/api/notebooks/{notebook_id}/files/tree",
+    "/api/notebooks/{notebook_id}/files/bulk-content",
+    "/api/notebooks/{notebook_id}/files/combined",
+    "/api/notebooks/{notebook_id}/files/download",
+    "/api/notebooks/{notebook_id}/files/artifacts",
+    "/api/notebooks/files/{file_id}",
+    "/api/notebooks",
+    "/api/notebooks/search",
+    "/api/cli/arm/status",
+    "/api/cli/projects",
+    "/api/cli/bundle/manifest",
+    "/api/cli/bundle.tgz",
+    "/api/auth/cli/session",
+];
+// ─── END GENERATED: SCOPED_PATHS ─────────────────────────────────────────────
+// ─── GENERATED: WRITE_PATHS (do not edit by hand) ────────────────────────────
+/**
+ * Paths reached with the SHORT-LIVED write credential (POST/DELETE).
+ *
+ * ⚠ **EMPTY IN v1, DELIBERATELY.** `place_order`, `cancel_order`,
+ * `deploy_regime` and `backtest_regime` are NOT ported — settled in P0 so this
+ * phase would know whether it was porting 12, 14 or 16 tools. They ship in
+ * **P5**, together with the armed window (`symbols arm`) that is the only thing
+ * making an autonomous order credential on a laptop defensible.
+ *
+ * The list, the checker's write arm, and the disjointness assertion all stay
+ * live rather than being deleted, so P5 fills a seam that is already verified
+ * instead of re-deriving one. See `mcp/tools.ts` — `P5_SEAM`.
+ */
+export const WRITE_PATHS = [];
+// ─── END GENERATED: WRITE_PATHS ──────────────────────────────────────────────
+/* eslint-enable */
+/**
+ * Split `"GET /api/quote/{symbol}"` into its method and template.
+ *
+ * Every tool declares its route in this one wire form, so a tool's declared
+ * surface and the string the checker reads are the same characters.
+ */
+export function splitRoute(route) {
+    const i = route.indexOf(" ");
+    if (i <= 0)
+        throw new Error(`malformed route '${route}' — expected "METHOD /api/..."`);
+    return { method: route.slice(0, i), template: route.slice(i + 1) };
+}
+/**
+ * Does a CONCRETE path match one of the `SCOPED_PATHS` templates?
+ *
+ * Segment-wise: `{anything}` matches exactly one non-empty segment. Mirrors the
+ * server's own `template_matches` closely enough for a pre-flight check — the
+ * server remains the authority; this turns a would-be silent 403 into an
+ * actionable error before the wire.
+ *
+ * ⚠ Stricter than the Python original in one place, on purpose: `.` and `..` are
+ * refused as path segments. `{symbol}` happily matched `..` there, so
+ * `/api/quote/..` passed the allow-list and then normalised to `/api/` at the
+ * fetch layer — a tool argument that walked out of its own route. Nothing was
+ * exploitable behind it, but "the allow-list said yes to a traversal" is not a
+ * property worth carrying forward.
+ */
+export function templateOk(path) {
+    if (path.includes("?") || path.includes("#"))
+        return false;
+    if (!path.startsWith("/api/"))
+        return false;
+    const parts = path.split("/");
+    // parts[0] is "" from the leading slash; every later segment must be a real,
+    // non-relative name.
+    for (const seg of parts.slice(1)) {
+        if (seg === "" || seg === "." || seg === "..")
+            return false;
+    }
+    return SCOPED_PATHS.some((tmpl) => {
+        const t = tmpl.split("/");
+        if (t.length !== parts.length)
+            return false;
+        return t.every((seg, i) => {
+            const part = parts[i];
+            if (seg.startsWith("{") && seg.endsWith("}"))
+                return part !== "";
+            return seg === part;
+        });
+    });
+}
+/** The `/api/<family>` prefixes, for an actionable refusal message. */
+export function allowedFamilies() {
+    return [...new Set(SCOPED_PATHS.map((t) => t.split("/").slice(0, 3).join("/")))].sort();
+}
+/**
+ * Substitute path parameters into a route template.
+ *
+ * ⚠ This is the ONLY place a request path is built, and that is the design.
+ * Each tool declares a template that the checker reads and that this function
+ * fills — so a tool's declared route and the bytes on the wire cannot diverge.
+ * The Python original had a template list on one side and hand-written f-strings
+ * on the other, and needed an AST pass to keep them honest.
+ *
+ * Values are percent-encoded. The Python version interpolated `args['symbol']`
+ * raw, so a `/` in a tool argument added path segments.
+ */
+export function buildPath(template, params = {}) {
+    const out = template.replace(/\{([^}]+)\}/g, (_m, name) => {
+        const v = params[name];
+        if (v === undefined || v === "") {
+            throw new Error(`route '${template}' needs a value for '{${name}}'`);
+        }
+        return encodeURIComponent(v);
+    });
+    if (out.includes("{") || out.includes("}")) {
+        throw new Error(`route '${template}' still has unfilled parameters after substitution`);
+    }
+    return out;
+}

package/dist/mcp/server.js

@@ -0,0 +1,366 @@
+// Copyright (c) 2025 Symbols LLC. All rights reserved.
+//
+// This source code is proprietary and confidential. Unauthorized copying,
+// distribution, modification, or use of this file, via any medium, is strictly prohibited.
+// `symbols mcp` — the stdio MCP server.
+//
+// Port of `docker/odin-runtime/symbols-mcp/__main__.py`. The tool surface lives
+// in `tools.ts`; the allow-list in `scopes.ts`; this file is the transport, the
+// registration, and the checks that make a failure LOUD.
+//
+// ─────────────────────────────────────────────────────────────────────────────
+// ⚠ THE FAILURE MODE THIS FILE IS BUILT AROUND
+// ─────────────────────────────────────────────────────────────────────────────
+// The Python server died AT IMPORT when the image moved to `mcp` 2.0, which had
+// dropped the 1.x decorators:
+//
+//     AttributeError: 'Server' object has no attribute 'list_tools'
+//
+// The process never served a byte. `claude mcp list` said "Failed to connect",
+// and to the agent that is indistinguishable from "this user has no Symbols
+// access" — so it simply stopped using the tools and nobody filed a bug.
+//
+// A tool server that starts and registers NOTHING is worse than one that
+// crashes, because a crash is visible. Three guards, in order:
+//
+//   1. `loadSdk()` — dynamic import inside a try, so an SDK that cannot load, or
+//      that no longer exports what we call, produces a named diagnostic instead
+//      of an unhandled rejection.
+//   2. `assertSurface()` — every SDK symbol we use is checked for existence and
+//      callability BEFORE any of it is used. This is the check that would have
+//      caught the 1.x -> 2.x break at the door.
+//   3. `EXPECTED_TOOL_COUNT` — the tool list is asserted non-empty, unique, and
+//      exactly the expected size before the transport is connected. Adding a
+//      tool means bumping a number; that is deliberate.
+//
+// The in-process round trip (a real MCP client over `InMemoryTransport` calling
+// `tools/list` and `tools/call`) lives in `apps/cli/test/mcp-server.test.mjs`,
+// where it can afford to be exhaustive.
+//
+// ⚠ STDOUT IS THE PROTOCOL. Not a single byte of logging may go there — a stray
+// `console.log` corrupts the JSON-RPC stream and looks like a client bug. Every
+// diagnostic in this file writes to stderr.
+import { EXPECTED_TOOL_COUNT, TOOLS, assertDerivedTablesAreSound, callTool, } from "./tools.js";
+import { CLI_VERSION } from "../util/version.js";
+import { enterProtocolMode, eprint } from "../util/log.js";
+const SERVER_NAME = "symbols";
+/** Diagnostics go to stderr, always. See the stdout warning above. */
+function warn(line) {
+    eprint(`symbols-mcp: ${line}\n`);
+}
+export class McpStartupError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "McpStartupError";
+    }
+}
+/**
+ * Import the MCP SDK, converting any failure into a named, actionable error.
+ *
+ * A top-level static import cannot be caught, so a broken or missing SDK would
+ * kill the process with a module-resolution stack — technically visible, but not
+ * to whoever has to work out why their tools disappeared.
+ */
+export async function loadSdk() {
+    try {
+        const [server, stdio, types] = await Promise.all([
+            import("@modelcontextprotocol/sdk/server/index.js"),
+            import("@modelcontextprotocol/sdk/server/stdio.js"),
+            import("@modelcontextprotocol/sdk/types.js"),
+        ]);
+        return {
+            Server: server.Server,
+            StdioServerTransport: stdio.StdioServerTransport,
+            ListToolsRequestSchema: types.ListToolsRequestSchema,
+            CallToolRequestSchema: types.CallToolRequestSchema,
+        };
+    }
+    catch (err) {
+        throw new McpStartupError(`could not load @modelcontextprotocol/sdk (${err instanceof Error ? err.message : String(err)}). ` +
+            `Reinstall the CLI: npm i -g @symbols-cli/cli`);
+    }
+}
+/**
+ * Assert the SDK still exports what this file calls.
+ *
+ * This is the guard for the exact 1.x -> 2.x class of break: the package loads,
+ * the constructor exists, and one method we depend on has quietly gone. Checking
+ * before use turns that into a startup refusal naming the missing symbol.
+ */
+export function assertSurface(sdk) {
+    const missing = [];
+    if (typeof sdk.Server !== "function")
+        missing.push("Server (constructor)");
+    if (typeof sdk.StdioServerTransport !== "function")
+        missing.push("StdioServerTransport (constructor)");
+    if (typeof sdk.Server?.prototype?.setRequestHandler !== "function") {
+        missing.push("Server.prototype.setRequestHandler");
+    }
+    if (typeof sdk.Server?.prototype?.connect !== "function") {
+        missing.push("Server.prototype.connect");
+    }
+    for (const [name, schema] of [
+        ["ListToolsRequestSchema", sdk.ListToolsRequestSchema],
+        ["CallToolRequestSchema", sdk.CallToolRequestSchema],
+    ]) {
+        if (!schema || typeof schema !== "object")
+            missing.push(name);
+    }
+    if (missing.length > 0) {
+        throw new McpStartupError(`the installed @modelcontextprotocol/sdk does not export: ${missing.join(", ")}. ` +
+            `This is the failure that silently removed every Symbols tool once before — ` +
+            `refusing to start rather than serving an empty tool list.`);
+    }
+}
+/** The `tools/list` payload, built once and asserted before anything connects. */
+export function listToolsPayload(specs = TOOLS) {
+    return specs.map((t) => ({
+        name: t.name,
+        description: t.description,
+        inputSchema: t.inputSchema,
+    }));
+}
+/**
+ * Refuse to serve a tool list that is empty, duplicated, or the wrong size.
+ *
+ * The size check is the one that matters: it makes "registered nothing" a
+ * startup failure with a message, instead of a healthy-looking server with no
+ * capabilities.
+ */
+export function assertRegistration(tools) {
+    if (tools.length === 0) {
+        throw new McpStartupError("the tool table is EMPTY. Refusing to start — a connected server with no " +
+            "tools is indistinguishable from a healthy one, and that is how the " +
+            "Symbols tools vanished for three weeks.");
+    }
+    if (tools.length !== EXPECTED_TOOL_COUNT) {
+        throw new McpStartupError(`expected ${EXPECTED_TOOL_COUNT} tools, built ${tools.length}. ` +
+            `If a tool was added or removed on purpose, update EXPECTED_TOOL_COUNT ` +
+            `in mcp/tools.ts in the same change.`);
+    }
+    const names = new Set();
+    for (const t of tools) {
+        if (!t.name)
+            throw new McpStartupError("a tool has an empty name");
+        if (names.has(t.name))
+            throw new McpStartupError(`duplicate tool name '${t.name}'`);
+        names.add(t.name);
+        if (!t.description)
+            throw new McpStartupError(`tool '${t.name}' has no description`);
+        if (!t.inputSchema)
+            throw new McpStartupError(`tool '${t.name}' has no inputSchema`);
+    }
+}
+/**
+ * Build a fully-registered server WITHOUT connecting it.
+ *
+ * Split from `serve()` so the test can drive the very same object over an
+ * in-memory transport — the round trip then proves the real registration path,
+ * not a parallel one written for the test.
+ */
+export async function buildServer(sdk) {
+    const resolved = sdk ?? (await loadSdk());
+    assertSurface(resolved);
+    assertDerivedTablesAreSound();
+    const tools = listToolsPayload();
+    assertRegistration(tools);
+    const server = new resolved.Server({ name: SERVER_NAME, version: CLI_VERSION }, { capabilities: { tools: {} } });
+    server.setRequestHandler(resolved.ListToolsRequestSchema, async () => ({ tools }));
+    server.setRequestHandler(resolved.CallToolRequestSchema, async (req) => {
+        const name = req.params.name;
+        const args = (req.params.arguments ?? {});
+        // `callTool` is written to answer rather than throw; this catch is the belt
+        // for anything genuinely unexpected. A tool that raises out of the handler
+        // reads to the agent as a broken connection, not a failed call.
+        let result;
+        try {
+            result = await callTool(name, args);
+        }
+        catch (err) {
+            warn(`tool ${name} raised: ${err instanceof Error ? err.message : String(err)}`);
+            result = { error: err instanceof Error ? err.message : String(err) };
+        }
+        // The Python server rendered every result as indented JSON text, and the
+        // agent's prompts are tuned to that shape. `default=str` there tolerated
+        // non-serialisable values; the JS equivalent is a replacer, because a throw
+        // from JSON.stringify would take the whole call down.
+        return { content: [{ type: "text", text: await capResult(renderResult(result)) }] };
+    });
+    return { server, tools };
+}
+/**
+ * The largest tool result that may go straight into the agent's context.
+ *
+ * Matches `sync/api.ts`'s `MAX_FILE_BYTES`, deliberately: that is already the
+ * size this system considers "a whole file", so it is a defensible line rather
+ * than an invented one.
+ */
+export const MAX_RESULT_BYTES = 1_000_000;
+/** How much of an oversized result the agent still sees inline. */
+const HEAD_BYTES = 8_000;
+/**
+ * Bound what a tool call can put into the agent's context.
+ *
+ * ⚠ NOTHING BOUNDED THIS. `MAX_FILE_BYTES` caps what SYNC pushes, but a tool
+ * result had no cap at all, and `api_get` is an explicit escape hatch. One wide
+ * call was buffered whole here, passed whole to the agent, and written whole to
+ * the transcript — degrading every later turn in that session PERMANENTLY,
+ * because context does not shrink.
+ *
+ * The shape is borrowed from Claude Code, measured on this machine: its
+ * transcript for this very session is 83 MB across 20,723 records and still
+ * appends instantly, because the big payloads live in a sibling `tool-results/`
+ * directory rather than in the hot file. Same idea here — spill the payload,
+ * keep a bounded head in context, and hand back a path.
+ *
+ * ⚠ THE TRUNCATION IS ANNOUNCED, ALWAYS. A silent truncation is worse than a
+ * slow response: the agent then reasons about a prefix believing it has the
+ * whole thing, and produces confidently wrong work. Saying so costs one line.
+ */
+export async function capResult(text) {
+    const bytes = Buffer.byteLength(text, "utf8");
+    if (bytes <= MAX_RESULT_BYTES)
+        return text;
+    const head = Buffer.from(text, "utf8").subarray(0, HEAD_BYTES).toString("utf8");
+    let where = "(could not be written to disk)";
+    try {
+        const { promises: fs } = await import("node:fs");
+        const { join } = await import("node:path");
+        const { randomUUID } = await import("node:crypto");
+        const { symbolsHome } = await import("../util/platform.js");
+        const dir = join(symbolsHome(), "tool-results");
+        await fs.mkdir(dir, { recursive: true });
+        const file = join(dir, `${randomUUID()}.json`);
+        await fs.writeFile(file, text, { mode: 0o600 });
+        where = file;
+    }
+    catch {
+        // A spill failure must not fail the tool call. A truncated-but-announced
+        // result is still useful; losing the call outright is not.
+    }
+    return (`⚠ TRUNCATED — this result was ${bytes} bytes, over the ${MAX_RESULT_BYTES}-byte limit.\n` +
+        `The full payload was written to:\n  ${where}\n\n` +
+        `Read it with a file tool, or narrow the request (a date range, fewer symbols,\n` +
+        `a specific field) so the answer fits. What follows is the first ${HEAD_BYTES}\n` +
+        `bytes ONLY — do not treat it as the complete result.\n\n` +
+        head);
+}
+/**
+ * JSON, indented, and never able to throw.
+ *
+ * ⚠ A7 — THE CYCLE/BIGINT REPLACER WAS DEAD CODE WITH A COST. Nothing reachable
+ * here can contain either: every value is `JSON.parse(text)` from the API or a
+ * plain `{error}` literal built in `tools.ts`. Neither can produce a cycle or a
+ * BigInt, so the `WeakSet` walked every node of every result for nothing.
+ *
+ * Measured on a legal maximum-size `get_bars` (50 000 bars, 6 022 347 bytes):
+ * with the replacer 43.6 ms, without it 14.4 ms. That ~29 ms is synchronous and
+ * buffered, so it stalled every CONCURRENT tool call in the process too.
+ *
+ * `indent: 2` STAYS. It is documented as deliberate — the agent's prompts are
+ * tuned to that shape — so dropping it would be a prompt-behaviour change
+ * wearing a performance costume. The `try/catch` stays for the same reason it
+ * always did: a throw must degrade to an error object, not kill the server.
+ */
+export function renderResult(value) {
+    try {
+        // The fast path, taken for every real result.
+        return JSON.stringify(value, null, 2) ?? "null";
+    }
+    catch {
+        // ⚠ NOT REACHED BY ANYTHING TODAY — and kept anyway, because "unreachable"
+        // is an argument about callers, and callers change. A test pins this shape,
+        // which is how the first version of this optimisation was caught silently
+        // downgrading a cycle to an error object.
+        //
+        // Paying the WeakSet only here means the happy path is 14.4 ms on a 6 MB
+        // result instead of 43.6 ms, and the graceful degradation is unchanged.
+        const seen = new WeakSet();
+        try {
+            return (JSON.stringify(value, (_k, v) => {
+                if (typeof v === "bigint")
+                    return v.toString();
+                if (typeof v === "object" && v !== null) {
+                    if (seen.has(v))
+                        return "[circular]";
+                    seen.add(v);
+                }
+                return v;
+            }, 2) ?? "null");
+        }
+        catch (err) {
+            return JSON.stringify({ error: `unserialisable result: ${String(err)}` });
+        }
+    }
+}
+/**
+ * Hold the TCP+TLS connection open between tool calls. **MCP ONLY.**
+ *
+ * Node's global `fetch` uses undici with no dispatcher configured, so every
+ * tool call pays a fresh TCP handshake plus a TLS handshake. Measured against
+ * prod on a 253 ms link that is ~475-510 ms of the round trip — but state it as
+ * **~2 x RTT**, not a flat number: for a user near nyc1 at 15 ms it is ~30 ms.
+ *
+ * ⚠ DELIBERATELY NOT GLOBAL. For a one-shot command this buys nothing (the
+ * process makes one request and exits) and only delays exit. It is installed
+ * here, in the long-lived server, and nowhere else.
+ *
+ * ⚠ NO HEARTBEAT. A keep-alive PING timer was proposed and is refused: it would
+ * be a permanent outbound request from every user's laptop, for the life of the
+ * session, aimed at one droplet that already runs a 60/min per-IP limiter.
+ * `keepAliveTimeout` is set BELOW the measured 65 s server cliff instead, so a
+ * socket is retired by us rather than found dead by a request.
+ *
+ * ⚠ CONNECTION COUNT IS SIZED AGAINST A1. `setGlobalDispatcher` is
+ * process-global and the agent can call `api_get` freely; too small a pool lets
+ * a flood of tool calls block the credential rotation into the "another
+ * `symbols` process is refreshing" refusal. 8 leaves headroom beside the
+ * single-flight mint.
+ */
+async function installKeepAlive() {
+    try {
+        const undici = (await import("undici"));
+        const agent = new undici.Agent({
+            keepAliveTimeout: 50_000, // under the measured 65 s cliff
+            keepAliveMaxTimeout: 50_000,
+            connections: 8,
+        });
+        undici.setGlobalDispatcher(agent);
+        // ⚠ ASSERT IT TOOK EFFECT. The injection rides
+        // `Symbol.for('undici.globalDispatcher.N')` — an undocumented, VERSION-TAGGED
+        // contract that has already been bumped once. If Node's bundled copy moves
+        // to a tag this undici does not write, `setGlobalDispatcher` becomes a
+        // silent no-op: nothing throws, nothing logs, and the latency quietly
+        // returns. A warning is the difference between a regression and a mystery.
+        const installed = undici.getGlobalDispatcher?.();
+        if (installed !== agent) {
+            warn("keep-alive dispatcher did NOT take effect — every tool call will pay a " +
+                "fresh TCP+TLS handshake. This usually means Node's bundled undici and " +
+                "the installed one disagree on the global-dispatcher symbol version.");
+        }
+    }
+    catch (err) {
+        // Never fatal. A slower server beats a server that will not start.
+        warn(`could not install the keep-alive dispatcher: ${err.message}`);
+    }
+}
+/** Start the stdio server. Resolves when the transport closes. */
+export async function serve() {
+    // ⚠ CLAIM STDOUT BEFORE ANYTHING CAN WRITE TO IT. From here on `print()`
+    // redirects to stderr, so a diagnostic added to any helper this process
+    // reaches becomes a misplaced log line instead of a corrupted JSON-RPC
+    // stream. The warning at the top of this file states the rule; this enforces
+    // it for code that never read the warning.
+    enterProtocolMode();
+    await installKeepAlive();
+    const sdk = await loadSdk();
+    const { server, tools } = await buildServer(sdk);
+    const transport = new sdk.StdioServerTransport();
+    await server.connect(transport);
+    warn(`serving ${tools.length} tools over stdio (cli ${CLI_VERSION})`);
+    await new Promise((resolve) => {
+        transport.onclose = () => resolve();
+        process.on("SIGINT", () => resolve());
+        process.on("SIGTERM", () => resolve());
+    });
+}