reasonix 0.3.0-alpha.2 → 0.3.0-alpha.4

package/README.md

@@ -100,12 +100,13 @@ the same Cache-First benefits. Two live runs, two data points:
 |---|---:|---:|---:|---:|---:|
 | bundled demo (`add` / `echo` / `get_time`) | 2 | 1 | **96.6%** (turn 2) | $0.000254 | −94.0% |
 | official `@modelcontextprotocol/server-filesystem` | 5 | 4 | **96.7%** overall | $0.001235 | −97.0% |
+| **both concurrently** (`demo_add` + `fs_write_file`) | 5 | 4 | **81.1%** | $0.001852 | −95.9% |
 
-The second run is the interesting one — it's through an *external*,
-production MCP server (no code we control). Five turns including
-`list_directory`, a permission-denied recovery via
-`list_allowed_directories`, a successful retry, and `read_text_file`.
-Byte-stable prefix held across every turn; cache hit stayed at 96.7%.
+The third row is the ecosystem proof: two MCP servers running as
+separate subprocesses, tools from both exercised in one conversation
+(compute `17+25` with the demo server, write the result to a real file
+via the filesystem server). **One single prefix hash across all 5
+turns** — byte-stability survives concurrent MCP subprocesses.
 
 **Reproduce without an API key** (replay the committed transcripts):
 
@@ -117,9 +118,24 @@ npx reasonix replay benchmarks/tau-bench/transcripts/mcp-filesystem.jsonl
 **Reproduce with your own key** (live, ~$0.002):
 
 ```bash
-reasonix chat --mcp "node --import tsx examples/mcp-server-demo.ts"
-# or against the real filesystem server:
-reasonix chat --mcp "npx -y @modelcontextprotocol/server-filesystem /path/to/safe/dir"
+# Don't know what MCP servers exist? Start here:
+reasonix mcp list
+# Prints a curated catalog (filesystem, fetch, github, sqlite, …) with
+# ready-to-paste --mcp commands.
+
+# One server:
+reasonix chat --mcp "filesystem=npx -y @modelcontextprotocol/server-filesystem /tmp/safe"
+
+# Multiple servers at once — each gets its own namespace prefix:
+reasonix chat \
+  --mcp "fs=npx -y @modelcontextprotocol/server-filesystem /tmp/safe" \
+  --mcp "mem=npx -y @modelcontextprotocol/server-memory"
+# Tools land in a shared registry as fs_read_file, mem_set, etc.
+
+# Remote / hosted MCP server — pass an http(s) URL instead of a command.
+# Reasonix opens an SSE stream and POSTs JSON-RPC to the endpoint the
+# server advertises (MCP 2024-11-05 HTTP+SSE transport).
+reasonix chat --mcp "kb=https://mcp.example.com/sse"
 ```
 
 [mcp]: ./benchmarks/tau-bench/transcripts/mcp-demo.add.jsonl

package/dist/cli/index.js

@@ -2103,6 +2103,145 @@ function quoteArg(s, windows) {
   return `"${s.replace(/"/g, '""')}"`;
 }
 
+// src/mcp/sse.ts
+import { createParser as createParser2 } from "eventsource-parser";
+var SseTransport = class {
+  url;
+  headers;
+  queue = [];
+  waiters = [];
+  controller = new AbortController();
+  closed = false;
+  postUrl = null;
+  endpointReady;
+  resolveEndpoint;
+  rejectEndpoint;
+  constructor(opts) {
+    this.url = opts.url;
+    this.headers = opts.headers ?? {};
+    this.endpointReady = new Promise((resolve2, reject) => {
+      this.resolveEndpoint = resolve2;
+      this.rejectEndpoint = reject;
+    });
+    this.endpointReady.catch(() => void 0);
+    void this.runStream();
+  }
+  async send(message) {
+    if (this.closed) throw new Error("MCP SSE transport is closed");
+    const postUrl = await this.endpointReady;
+    const res = await fetch(postUrl, {
+      method: "POST",
+      headers: { "content-type": "application/json", ...this.headers },
+      body: JSON.stringify(message),
+      signal: this.controller.signal
+    });
+    await res.arrayBuffer().catch(() => void 0);
+    if (!res.ok) {
+      throw new Error(`MCP SSE POST ${postUrl} failed: ${res.status} ${res.statusText}`);
+    }
+  }
+  async *messages() {
+    while (true) {
+      if (this.queue.length > 0) {
+        yield this.queue.shift();
+        continue;
+      }
+      if (this.closed) return;
+      const next = await new Promise((resolve2) => {
+        this.waiters.push(resolve2);
+      });
+      if (next === null) return;
+      yield next;
+    }
+  }
+  async close() {
+    if (this.closed) return;
+    this.closed = true;
+    while (this.waiters.length > 0) this.waiters.shift()(null);
+    this.rejectEndpoint(new Error("MCP SSE transport closed before endpoint was ready"));
+    try {
+      this.controller.abort();
+    } catch {
+    }
+  }
+  // ---------- internals ----------
+  async runStream() {
+    let res;
+    try {
+      res = await fetch(this.url, {
+        method: "GET",
+        headers: { accept: "text/event-stream", ...this.headers },
+        signal: this.controller.signal
+      });
+    } catch (err) {
+      this.failHandshake(`SSE connect to ${this.url} failed: ${err.message}`);
+      return;
+    }
+    if (!res.ok || !res.body) {
+      await res.body?.cancel().catch(() => void 0);
+      this.failHandshake(`SSE handshake ${this.url} \u2192 ${res.status} ${res.statusText}`);
+      return;
+    }
+    const parser = createParser2({
+      onEvent: (ev) => this.handleEvent(ev.event ?? "message", ev.data)
+    });
+    const decoder = new TextDecoder();
+    try {
+      for await (const chunk of res.body) {
+        parser.feed(decoder.decode(chunk, { stream: true }));
+      }
+    } catch (err) {
+      if (!this.closed) {
+        this.pushError(`SSE stream error: ${err.message}`);
+      }
+    } finally {
+      this.markClosed();
+    }
+  }
+  handleEvent(type, data) {
+    if (type === "endpoint") {
+      if (this.postUrl) return;
+      try {
+        this.postUrl = new URL(data, this.url).toString();
+        this.resolveEndpoint(this.postUrl);
+      } catch (err) {
+        this.failHandshake(`SSE endpoint event had bad URL "${data}": ${err.message}`);
+      }
+      return;
+    }
+    if (type === "message") {
+      try {
+        const parsed = JSON.parse(data);
+        this.pushMessage(parsed);
+      } catch {
+      }
+      return;
+    }
+  }
+  failHandshake(reason) {
+    this.rejectEndpoint(new Error(reason));
+    this.pushError(reason);
+    this.markClosed();
+  }
+  pushMessage(msg) {
+    const waiter = this.waiters.shift();
+    if (waiter) waiter(msg);
+    else this.queue.push(msg);
+  }
+  pushError(message) {
+    this.pushMessage({
+      jsonrpc: "2.0",
+      id: null,
+      error: { code: -32e3, message }
+    });
+  }
+  markClosed() {
+    if (this.closed) return;
+    this.closed = true;
+    while (this.waiters.length > 0) this.waiters.shift()(null);
+  }
+};
+
 // src/mcp/registry.ts
 async function bridgeMcpTools(client, opts = {}) {
   const registry = opts.registry ?? new ToolRegistry({ autoFlatten: opts.autoFlatten });
@@ -2142,56 +2281,6 @@ function blockToString(block) {
   return `[unknown block: ${JSON.stringify(block)}]`;
 }
 
-// src/config.ts
-import { chmodSync as chmodSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync4, writeFileSync } from "fs";
-import { homedir as homedir2 } from "os";
-import { dirname as dirname2, join as join2 } from "path";
-function defaultConfigPath() {
-  return join2(homedir2(), ".reasonix", "config.json");
-}
-function readConfig(path = defaultConfigPath()) {
-  try {
-    const raw = readFileSync4(path, "utf8");
-    const parsed = JSON.parse(raw);
-    if (parsed && typeof parsed === "object") return parsed;
-  } catch {
-  }
-  return {};
-}
-function writeConfig(cfg, path = defaultConfigPath()) {
-  mkdirSync2(dirname2(path), { recursive: true });
-  writeFileSync(path, JSON.stringify(cfg, null, 2), "utf8");
-  try {
-    chmodSync2(path, 384);
-  } catch {
-  }
-}
-function loadApiKey(path = defaultConfigPath()) {
-  if (process.env.DEEPSEEK_API_KEY) return process.env.DEEPSEEK_API_KEY;
-  return readConfig(path).apiKey;
-}
-function saveApiKey(key, path = defaultConfigPath()) {
-  const cfg = readConfig(path);
-  cfg.apiKey = key.trim();
-  writeConfig(cfg, path);
-}
-function isPlausibleKey(key) {
-  const trimmed = key.trim();
-  return /^sk-[A-Za-z0-9_-]{16,}$/.test(trimmed);
-}
-function redactKey(key) {
-  if (!key) return "";
-  if (key.length <= 12) return "****";
-  return `${key.slice(0, 6)}\u2026${key.slice(-4)}`;
-}
-
-// src/index.ts
-var VERSION = "0.3.0-alpha.2";
-
-// src/cli/commands/chat.tsx
-import { render } from "ink";
-import React8, { useState as useState4 } from "react";
-
 // src/mcp/shell-split.ts
 function shellSplit(input) {
   const tokens = [];
@@ -2221,11 +2310,6 @@ function shellSplit(input) {
       i++;
       continue;
     }
-    if (ch === "\\" && i + 1 < s.length) {
-      cur += s[i + 1];
-      i += 2;
-      continue;
-    }
     if (ch === " " || ch === "	") {
       if (cur.length > 0) {
         tokens.push(cur);
@@ -2246,6 +2330,81 @@ function shellSplit(input) {
   return tokens;
 }
 
+// src/mcp/spec.ts
+var NAME_PREFIX = /^([a-zA-Z_][a-zA-Z0-9_]*)=(.*)$/;
+var HTTP_URL = /^https?:\/\//i;
+function parseMcpSpec(input) {
+  const trimmed = input.trim();
+  if (!trimmed) {
+    throw new Error("empty MCP spec");
+  }
+  const nameMatch = NAME_PREFIX.exec(trimmed);
+  const name = nameMatch ? nameMatch[1] : null;
+  const body = (nameMatch ? nameMatch[2] : trimmed).trim();
+  if (!body) {
+    throw new Error(`MCP spec has name but no command: ${input}`);
+  }
+  if (HTTP_URL.test(body)) {
+    return { transport: "sse", name, url: body };
+  }
+  const argv = shellSplit(body);
+  if (argv.length === 0) {
+    throw new Error(`MCP spec has name but no command: ${input}`);
+  }
+  const [command, ...args] = argv;
+  return { transport: "stdio", name, command, args };
+}
+
+// src/config.ts
+import { chmodSync as chmodSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync4, writeFileSync } from "fs";
+import { homedir as homedir2 } from "os";
+import { dirname as dirname2, join as join2 } from "path";
+function defaultConfigPath() {
+  return join2(homedir2(), ".reasonix", "config.json");
+}
+function readConfig(path = defaultConfigPath()) {
+  try {
+    const raw = readFileSync4(path, "utf8");
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === "object") return parsed;
+  } catch {
+  }
+  return {};
+}
+function writeConfig(cfg, path = defaultConfigPath()) {
+  mkdirSync2(dirname2(path), { recursive: true });
+  writeFileSync(path, JSON.stringify(cfg, null, 2), "utf8");
+  try {
+    chmodSync2(path, 384);
+  } catch {
+  }
+}
+function loadApiKey(path = defaultConfigPath()) {
+  if (process.env.DEEPSEEK_API_KEY) return process.env.DEEPSEEK_API_KEY;
+  return readConfig(path).apiKey;
+}
+function saveApiKey(key, path = defaultConfigPath()) {
+  const cfg = readConfig(path);
+  cfg.apiKey = key.trim();
+  writeConfig(cfg, path);
+}
+function isPlausibleKey(key) {
+  const trimmed = key.trim();
+  return /^sk-[A-Za-z0-9_-]{16,}$/.test(trimmed);
+}
+function redactKey(key) {
+  if (!key) return "";
+  if (key.length <= 12) return "****";
+  return `${key.slice(0, 6)}\u2026${key.slice(-4)}`;
+}
+
+// src/index.ts
+var VERSION = "0.3.0-alpha.4";
+
+// src/cli/commands/chat.tsx
+import { render } from "ink";
+import React8, { useState as useState4 } from "react";
+
 // src/cli/ui/App.tsx
 import { Box as Box6, Static, Text as Text6, useApp } from "ink";
 import React6, { useCallback, useEffect as useEffect2, useMemo, useRef, useState as useState2 } from "react";
@@ -2994,34 +3153,32 @@ function Root({ initialKey, tools, ...appProps }) {
 async function chatCommand(opts) {
   loadDotenv();
   const initialKey = loadApiKey();
-  let mcp;
+  const mcpSpecs = opts.mcp ?? [];
+  const clients = [];
   let tools;
-  if (opts.mcp) {
-    const argv = shellSplit(opts.mcp);
-    if (argv.length === 0) {
-      process.stderr.write("error: --mcp requires a command\n");
-      process.exit(2);
-    }
-    const [command, ...args] = argv;
-    if (!command) {
-      process.stderr.write("error: --mcp command is empty\n");
-      process.exit(2);
-    }
-    const transport = new StdioTransport({ command, args });
-    mcp = new McpClient({ transport });
-    try {
-      await mcp.initialize();
-      const bridge = await bridgeMcpTools(mcp, { namePrefix: opts.mcpPrefix });
-      tools = bridge.registry;
-      process.stderr.write(
-        `\u25B8 MCP: ${bridge.registeredNames.length} tool(s) from ${argv.join(" ")}
+  if (mcpSpecs.length > 0) {
+    tools = new ToolRegistry();
+    for (const raw of mcpSpecs) {
+      try {
+        const spec = parseMcpSpec(raw);
+        const prefix = spec.name ? `${spec.name}_` : mcpSpecs.length === 1 && opts.mcpPrefix ? opts.mcpPrefix : "";
+        const transport = spec.transport === "sse" ? new SseTransport({ url: spec.url }) : new StdioTransport({ command: spec.command, args: spec.args });
+        const mcp2 = new McpClient({ transport });
+        await mcp2.initialize();
+        const bridge = await bridgeMcpTools(mcp2, { registry: tools, namePrefix: prefix });
+        const label = spec.name ?? "anon";
+        const source = spec.transport === "sse" ? spec.url : `${spec.command} ${spec.args.join(" ")}`;
+        process.stderr.write(
+          `\u25B8 MCP[${label}]: ${bridge.registeredNames.length} tool(s) from ${source}
 `
-      );
-    } catch (err) {
-      process.stderr.write(`MCP setup failed: ${err.message}
+        );
+        clients.push(mcp2);
+      } catch (err) {
+        process.stderr.write(`MCP setup failed for "${raw}": ${err.message}
 `);
-      await mcp.close();
-      process.exit(1);
+        for (const c of clients) await c.close();
+        process.exit(1);
+      }
     }
   }
   const { waitUntilExit } = render(/* @__PURE__ */ React8.createElement(Root, { initialKey, tools, ...opts }), {
@@ -3030,7 +3187,7 @@ async function chatCommand(opts) {
   try {
     await waitUntilExit();
   } finally {
-    await mcp?.close();
+    for (const c of clients) await c.close();
   }
 }
 
@@ -3196,6 +3353,82 @@ markdown report written to ${opts.mdPath}`);
   console.log(renderSummaryTable(report));
 }
 
+// src/mcp/catalog.ts
+var MCP_CATALOG = [
+  {
+    name: "filesystem",
+    summary: "read/write/search files inside a sandboxed directory",
+    package: "@modelcontextprotocol/server-filesystem",
+    userArgs: "<dir>",
+    note: "the directory is a hard sandbox \u2014 the server refuses access outside it"
+  },
+  {
+    name: "fetch",
+    summary: "fetch URLs (markdown-friendly extraction, not a full browser)",
+    package: "@modelcontextprotocol/server-fetch"
+  },
+  {
+    name: "memory",
+    summary: "persistent key-value memory across sessions",
+    package: "@modelcontextprotocol/server-memory"
+  },
+  {
+    name: "github",
+    summary: "read issues, PRs, code search (needs GITHUB_PERSONAL_ACCESS_TOKEN)",
+    package: "@modelcontextprotocol/server-github",
+    note: "set GITHUB_PERSONAL_ACCESS_TOKEN in your env before spawning"
+  },
+  {
+    name: "sqlite",
+    summary: "read/write a sqlite database file",
+    package: "@modelcontextprotocol/server-sqlite",
+    userArgs: "<db.sqlite>"
+  },
+  {
+    name: "puppeteer",
+    summary: "browser automation \u2014 take screenshots, click, type",
+    package: "@modelcontextprotocol/server-puppeteer",
+    note: "downloads Chromium on first run (~200 MB)"
+  },
+  {
+    name: "everything",
+    summary: "official test server \u2014 exercises every MCP feature",
+    package: "@modelcontextprotocol/server-everything",
+    note: "useful for debugging your Reasonix setup"
+  }
+];
+function mcpCommandFor(entry) {
+  const pkg = entry.package;
+  const tail = entry.userArgs ? ` ${entry.userArgs}` : "";
+  return `--mcp "${entry.name}=npx -y ${pkg}${tail}"`;
+}
+
+// src/cli/commands/mcp.ts
+function mcpListCommand(opts) {
+  if (opts.json) {
+    console.log(JSON.stringify(MCP_CATALOG, null, 2));
+    return;
+  }
+  console.log("Popular MCP servers you can bridge into Reasonix:");
+  console.log("");
+  for (const entry of MCP_CATALOG) {
+    console.log(`  ${pad(entry.name, 12)} ${entry.summary}`);
+    console.log(`               ${mcpCommandFor(entry)}`);
+    if (entry.note) console.log(`               \xB7 ${entry.note}`);
+    console.log("");
+  }
+  console.log("Usage:  reasonix chat <one-of-the---mcp-lines-above>");
+  console.log(
+    "Docs:   https://github.com/modelcontextprotocol/servers  \u2014  Anthropic's official server repo"
+  );
+  console.log(
+    "        https://mcp.so                                   \u2014  community-maintained catalog"
+  );
+}
+function pad(s, width) {
+  return s.length >= width ? s : s + " ".repeat(width - s.length);
+}
+
 // src/cli/commands/replay.ts
 import { render as render3 } from "ink";
 import React13 from "react";
@@ -3386,29 +3619,31 @@ async function runCommand(opts) {
   loadDotenv();
   const apiKey = await ensureApiKey();
   process.env.DEEPSEEK_API_KEY = apiKey;
-  let mcp;
+  const mcpSpecs = opts.mcp ?? [];
+  const clients = [];
   let tools;
-  if (opts.mcp) {
-    const argv = shellSplit(opts.mcp);
-    const [command, ...args] = argv;
-    if (!command) {
-      process.stderr.write("error: --mcp command is empty\n");
-      process.exit(2);
-    }
-    mcp = new McpClient({ transport: new StdioTransport({ command, args }) });
-    try {
-      await mcp.initialize();
-      const bridge = await bridgeMcpTools(mcp, { namePrefix: opts.mcpPrefix });
-      tools = bridge.registry;
-      process.stderr.write(
-        `\u25B8 MCP: ${bridge.registeredNames.length} tool(s) from ${argv.join(" ")}
+  if (mcpSpecs.length > 0) {
+    tools = new ToolRegistry();
+    for (const raw of mcpSpecs) {
+      try {
+        const spec = parseMcpSpec(raw);
+        const prefix2 = spec.name ? `${spec.name}_` : mcpSpecs.length === 1 && opts.mcpPrefix ? opts.mcpPrefix : "";
+        const transport = spec.transport === "sse" ? new SseTransport({ url: spec.url }) : new StdioTransport({ command: spec.command, args: spec.args });
+        const mcp2 = new McpClient({ transport });
+        await mcp2.initialize();
+        const bridge = await bridgeMcpTools(mcp2, { registry: tools, namePrefix: prefix2 });
+        const source = spec.transport === "sse" ? spec.url : `${spec.command} ${spec.args.join(" ")}`;
+        process.stderr.write(
+          `\u25B8 MCP[${spec.name ?? "anon"}]: ${bridge.registeredNames.length} tool(s) from ${source}
 `
-      );
-    } catch (err) {
-      process.stderr.write(`MCP setup failed: ${err.message}
+        );
+        clients.push(mcp2);
+      } catch (err) {
+        process.stderr.write(`MCP setup failed for "${raw}": ${err.message}
 `);
-      await mcp.close();
-      process.exit(1);
+        for (const c of clients) await c.close();
+        process.exit(1);
+      }
     }
   }
   const client = new DeepSeekClient();
@@ -3470,7 +3705,7 @@ transcript: ${opts.transcript}
     process.stdout.write(`  \u2192 npx reasonix replay ${opts.transcript}
 `);
   }
-  await mcp?.close();
+  for (const c of clients) await c.close();
 }
 
 // src/cli/commands/sessions.ts
@@ -3595,9 +3830,14 @@ program.command("chat").description("Interactive Ink TUI with live cache/cost pa
   "--session <name>",
   "Use a named session (default: 'default'). Resume the same session next time."
 ).option("--no-session", "Disable session persistence for this run (ephemeral chat)").option(
-  "--mcp <command>",
-  'Spawn an MCP server and bridge its tools. Shell-quoted: --mcp "npx -y @scope/server-x /path"'
-).option("--mcp-prefix <str>", "Prefix prepended to every MCP tool name (avoid collisions)").action(async (opts) => {
+  "--mcp <spec>",
+  'MCP server spec; repeatable. Forms: "name=cmd args..." (namespaced, tools get `name_` prefix) or "cmd args..." (anonymous). Example: --mcp "fs=npx -y @scope/fs /tmp" --mcp "gh=npx -y @scope/gh"',
+  (value, previous = []) => [...previous, value],
+  []
+).option(
+  "--mcp-prefix <str>",
+  "Global prefix applied to every MCP tool (only honored when no per-spec name is set; avoids collisions with a single anonymous server)"
+).action(async (opts) => {
   let session;
   if (opts.session === false) {
     session = void 0;
@@ -3625,9 +3865,14 @@ program.command("run <task>").description("Run a single task non-interactively,
   "Self-consistency: run N parallel samples per turn and pick the most confident",
   (v) => Number.parseInt(v, 10)
 ).option("--transcript <path>", "Write a JSONL transcript to this path for replay/diff").option(
-  "--mcp <command>",
-  'Spawn an MCP server and bridge its tools. Shell-quoted: --mcp "npx -y @scope/server-x /path"'
-).option("--mcp-prefix <str>", "Prefix prepended to every MCP tool name (avoid collisions)").action(async (task, opts) => {
+  "--mcp <spec>",
+  'MCP server spec; repeatable. "name=cmd args..." or "cmd args...".',
+  (value, previous = []) => [...previous, value],
+  []
+).option(
+  "--mcp-prefix <str>",
+  "Global prefix (only honored when no per-spec name is set; for a single anonymous server)"
+).action(async (task, opts) => {
   await runCommand({
     task,
     model: opts.model,
@@ -3668,6 +3913,10 @@ program.command("diff <a> <b>").description(
     tui: !!opts.tui
   });
 });
+var mcp = program.command("mcp").description("Model Context Protocol helpers \u2014 discover servers, test your setup.");
+mcp.command("list").description("Show a curated catalog of popular MCP servers with ready-to-use --mcp commands.").option("--json", "Emit the catalog as JSON instead of the human-readable table").action((opts) => {
+  mcpListCommand({ json: !!opts.json });
+});
 program.command("version").description("Print Reasonix version.").action(versionCommand);
 program.parseAsync(process.argv).catch((err) => {
   console.error(err);