reasonix 0.3.0-alpha.3 → 0.3.0-alpha.4

package/dist/index.d.ts

@@ -994,6 +994,61 @@ declare class McpClient {
     private dispatch;
 }
 
+/**
+ * HTTP+SSE transport for MCP (spec version 2024-11-05).
+ *
+ * Wire shape:
+ *   1. Client opens GET to the SSE URL with `Accept: text/event-stream`.
+ *   2. Server's first SSE event is `event: endpoint`, `data: <url>` — the
+ *      URL (relative or absolute) the client must POST JSON-RPC requests
+ *      to. All subsequent server → client messages arrive as `event: message`
+ *      SSE frames carrying a JSON-RPC response or server-initiated frame.
+ *   3. Client POSTs each outgoing JSON-RPC frame to the endpoint URL.
+ *      The POST response body is ignored — replies land on the SSE stream.
+ *
+ * This transport exists so Reasonix can talk to hosted/remote MCP servers
+ * (e.g. a company's internal knowledge server fronted by auth). Stdio
+ * covers local subprocesses; SSE covers everything else.
+ *
+ * Note: the newer "Streamable HTTP" transport (2025 spec) folds the POST
+ * and SSE streams onto a single endpoint. We stay on 2024-11-05 here —
+ * that's what `MCP_PROTOCOL_VERSION` advertises in the initialize handshake
+ * and what currently-published servers implement.
+ */
+
+interface SseTransportOptions {
+    /** SSE endpoint URL, e.g. `https://mcp.example.com/sse`. */
+    url: string;
+    /** Extra headers sent on both the SSE GET and the JSON-RPC POSTs (e.g. `Authorization`). */
+    headers?: Record<string, string>;
+}
+/**
+ * Open an SSE stream to `url`, parse incoming events into JsonRpcMessages,
+ * POST outgoing frames to the endpoint URL the server advertises.
+ */
+declare class SseTransport implements McpTransport {
+    private readonly url;
+    private readonly headers;
+    private readonly queue;
+    private readonly waiters;
+    private readonly controller;
+    private closed;
+    private postUrl;
+    private readonly endpointReady;
+    private resolveEndpoint;
+    private rejectEndpoint;
+    constructor(opts: SseTransportOptions);
+    send(message: JsonRpcMessage): Promise<void>;
+    messages(): AsyncIterableIterator<JsonRpcMessage>;
+    close(): Promise<void>;
+    private runStream;
+    private handleEvent;
+    private failHandshake;
+    private pushMessage;
+    private pushError;
+    private markClosed;
+}
+
 /**
  * Bridge: register an MCP server's tools into a Reasonix ToolRegistry.
  *
@@ -1045,6 +1100,45 @@ declare function bridgeMcpTools(client: McpClient, opts?: BridgeOptions): Promis
  */
 declare function flattenMcpResult(result: CallToolResult): string;
 
+/**
+ * Parse the `--mcp` CLI argument into a transport-tagged spec.
+ *
+ * Accepted forms:
+ *   "name=command args..."      → stdio, namespaced (tools prefixed with `name_`)
+ *   "command args..."           → stdio, anonymous
+ *   "name=https://host/sse"     → SSE, namespaced
+ *   "https://host/sse"          → SSE, anonymous
+ *   ("http://" is also honored — useful for local dev servers.)
+ *
+ * The identifier regex before `=` is deliberately narrow
+ * (`[a-zA-Z_][a-zA-Z0-9_]*`) so Windows drive letters ("C:\\...") and
+ * other strings containing `=` or `:` don't accidentally trigger the
+ * namespace branch. If a user ever wants their command to literally start
+ * with `foo=...` as a bare command, they can wrap it in quotes inside the
+ * shell command string.
+ *
+ * Transport is selected solely by whether the body begins with `http://`
+ * or `https://`. Anything else is stdio — including ws:// (unsupported)
+ * which will surface later as a spawn error, keeping the rule local.
+ */
+interface StdioMcpSpec {
+    transport: "stdio";
+    /** Namespace prefix applied to each registered tool, or null if anonymous. */
+    name: string | null;
+    /** Argv[0]. */
+    command: string;
+    /** Remaining argv. */
+    args: string[];
+}
+interface SseMcpSpec {
+    transport: "sse";
+    name: string | null;
+    /** Fully qualified SSE endpoint URL. */
+    url: string;
+}
+type McpSpec = StdioMcpSpec | SseMcpSpec;
+declare function parseMcpSpec(input: string): McpSpec;
+
 /**
  * User-level config storage for the Reasonix CLI.
  *
@@ -1072,6 +1166,6 @@ declare function redactKey(key: string): string;
 
 /** Reasonix — DeepSeek-native agent framework. Library entry point. */
 
-declare const VERSION = "0.3.0-alpha.3";
+declare const VERSION = "0.3.0-alpha.4";
 
-export { AppendOnlyLog, type BranchOptions, type BranchProgress, type BranchResult, type BranchSample, type BranchSelector, type BranchSummary, type BridgeOptions, type BridgeResult, CacheFirstLoop, type CacheFirstLoopOptions, type CallToolResult, type ChatMessage, type ChatResponse, DeepSeekClient, type DeepSeekClientOptions, type RenderOptions as DiffRenderOptions, type DiffReport, type DiffSide, type EventRole, type FlattenDecision, type HarvestOptions, ImmutablePrefix, type ImmutablePrefixOptions, type InitializeResult, type JSONSchema, type JsonRpcMessage, type JsonRpcRequest, type JsonRpcResponse, type ListToolsResult, type LoopEvent, MCP_PROTOCOL_VERSION, McpClient, type McpClientOptions, type McpContentBlock, type McpTool, type McpToolSchema, type McpTransport, type ReadTranscriptResult, type ReasonixConfig, type ReconfigurableOptions, type RepairReport, type ReplayStats, type RetryInfo, type RetryOptions, type Role, type ScavengeOptions, type ScavengeResult, type SessionInfo, SessionStats, type SessionSummary, StdioTransport, type StdioTransportOptions, StormBreaker, type StreamChunk, type ToolCall, ToolCallRepair, type ToolCallRepairOptions, type ToolDefinition, type ToolFunctionSpec, ToolRegistry, type ToolSpec, type TranscriptMeta, type TranscriptRecord, type TruncationRepairResult, type TurnPair, type TurnStats, type TypedPlanState, Usage, VERSION, VolatileScratch, aggregateBranchUsage, analyzeSchema, appendSessionMessage, bridgeMcpTools, claudeEquivalentCost, computeReplayStats, costUsd, defaultConfigPath, defaultSelector, deleteSession, diffTranscripts, emptyPlanState, fetchWithRetry, flattenMcpResult, flattenSchema, harvest, isJsonRpcError, isPlanStateEmpty, isPlausibleKey, listSessions, loadApiKey, loadDotenv, loadSessionMessages, nestArguments, openTranscriptFile, parseTranscript, readConfig, readTranscript, recordFromLoopEvent, redactKey, renderMarkdown as renderDiffMarkdown, renderSummaryTable as renderDiffSummary, repairTruncatedJson, replayFromFile, runBranches, sanitizeName as sanitizeSessionName, saveApiKey, scavengeToolCalls, sessionPath, sessionsDir, similarity, writeConfig, writeMeta, writeRecord };
+export { AppendOnlyLog, type BranchOptions, type BranchProgress, type BranchResult, type BranchSample, type BranchSelector, type BranchSummary, type BridgeOptions, type BridgeResult, CacheFirstLoop, type CacheFirstLoopOptions, type CallToolResult, type ChatMessage, type ChatResponse, DeepSeekClient, type DeepSeekClientOptions, type RenderOptions as DiffRenderOptions, type DiffReport, type DiffSide, type EventRole, type FlattenDecision, type HarvestOptions, ImmutablePrefix, type ImmutablePrefixOptions, type InitializeResult, type JSONSchema, type JsonRpcMessage, type JsonRpcRequest, type JsonRpcResponse, type ListToolsResult, type LoopEvent, MCP_PROTOCOL_VERSION, McpClient, type McpClientOptions, type McpContentBlock, type McpSpec, type McpTool, type McpToolSchema, type McpTransport, type ReadTranscriptResult, type ReasonixConfig, type ReconfigurableOptions, type RepairReport, type ReplayStats, type RetryInfo, type RetryOptions, type Role, type ScavengeOptions, type ScavengeResult, type SessionInfo, SessionStats, type SessionSummary, type SseMcpSpec, SseTransport, type SseTransportOptions, type StdioMcpSpec, StdioTransport, type StdioTransportOptions, StormBreaker, type StreamChunk, type ToolCall, ToolCallRepair, type ToolCallRepairOptions, type ToolDefinition, type ToolFunctionSpec, ToolRegistry, type ToolSpec, type TranscriptMeta, type TranscriptRecord, type TruncationRepairResult, type TurnPair, type TurnStats, type TypedPlanState, Usage, VERSION, VolatileScratch, aggregateBranchUsage, analyzeSchema, appendSessionMessage, bridgeMcpTools, claudeEquivalentCost, computeReplayStats, costUsd, defaultConfigPath, defaultSelector, deleteSession, diffTranscripts, emptyPlanState, fetchWithRetry, flattenMcpResult, flattenSchema, harvest, isJsonRpcError, isPlanStateEmpty, isPlausibleKey, listSessions, loadApiKey, loadDotenv, loadSessionMessages, nestArguments, openTranscriptFile, parseMcpSpec, parseTranscript, readConfig, readTranscript, recordFromLoopEvent, redactKey, renderMarkdown as renderDiffMarkdown, renderSummaryTable as renderDiffSummary, repairTruncatedJson, replayFromFile, runBranches, sanitizeName as sanitizeSessionName, saveApiKey, scavengeToolCalls, sessionPath, sessionsDir, similarity, writeConfig, writeMeta, writeRecord };

package/dist/index.js

@@ -2067,6 +2067,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 });
@@ -2106,6 +2245,80 @@ function blockToString(block) {
   return `[unknown block: ${JSON.stringify(block)}]`;
 }
 
+// src/mcp/shell-split.ts
+function shellSplit(input) {
+  const tokens = [];
+  let cur = "";
+  let quote = null;
+  let i = 0;
+  const s = input;
+  while (i < s.length) {
+    const ch = s[i];
+    if (quote) {
+      if (ch === quote) {
+        quote = null;
+        i++;
+        continue;
+      }
+      if (ch === "\\" && quote === '"' && i + 1 < s.length) {
+        cur += s[i + 1];
+        i += 2;
+        continue;
+      }
+      cur += ch;
+      i++;
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      quote = ch;
+      i++;
+      continue;
+    }
+    if (ch === " " || ch === "	") {
+      if (cur.length > 0) {
+        tokens.push(cur);
+        cur = "";
+      }
+      i++;
+      continue;
+    }
+    cur += ch;
+    i++;
+  }
+  if (quote) {
+    throw new Error(
+      `shellSplit: unterminated ${quote === '"' ? "double" : "single"} quote in input`
+    );
+  }
+  if (cur.length > 0) tokens.push(cur);
+  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";
@@ -2150,7 +2363,7 @@ function redactKey(key) {
 }
 
 // src/index.ts
-var VERSION = "0.3.0-alpha.3";
+var VERSION = "0.3.0-alpha.4";
 export {
   AppendOnlyLog,
   CacheFirstLoop,
@@ -2159,6 +2372,7 @@ export {
   MCP_PROTOCOL_VERSION,
   McpClient,
   SessionStats,
+  SseTransport,
   StdioTransport,
   StormBreaker,
   ToolCallRepair,
@@ -2191,6 +2405,7 @@ export {
   loadSessionMessages,
   nestArguments,
   openTranscriptFile,
+  parseMcpSpec,
   parseTranscript,
   readConfig,
   readTranscript,