reasonix 0.3.0-alpha.3 → 0.3.0-alpha.6

package/dist/index.d.ts

@@ -527,6 +527,26 @@ declare class CacheFirstLoop {
     run(userInput: string, onEvent?: (ev: LoopEvent) => void): Promise<string>;
     private assistantMessage;
 }
+/**
+ * Truncate any tool-role message whose content exceeds the cap. User
+ * and assistant messages are left alone because (a) they're almost
+ * always small, (b) truncating user prompts would corrupt conversational
+ * intent in a way the user didn't author. Exported for tests.
+ */
+declare function healLoadedMessages(messages: ChatMessage[], maxChars: number): {
+    messages: ChatMessage[];
+    healedCount: number;
+    healedFrom: number;
+};
+/**
+ * Annotate the `DeepSeek 400: … maximum context length …` error the API
+ * returns when a session's history has grown past 131,072 tokens. The
+ * raw message is a JSON blob; we surface a short actionable hint on top
+ * so the user knows to `/forget` or `/clear` rather than parsing the
+ * JSON themselves. Other errors pass through unchanged — the loop's
+ * error channel already formats them well enough.
+ */
+declare function formatLoopError(err: Error): string;
 
 /**
  * Session persistence.
@@ -994,6 +1014,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.
  *
@@ -1014,7 +1089,26 @@ interface BridgeOptions {
     registry?: ToolRegistry;
     /** Auto-flatten deep schemas (Pillar 3). Defaults to the registry's own default (true). */
     autoFlatten?: boolean;
+    /**
+     * Per-tool-call result cap, in characters. If a tool returns more than
+     * this, the result is truncated and a `[…truncated N chars…]` marker is
+     * appended before the last KB so the model still sees a useful tail.
+     * Defaults to {@link DEFAULT_MAX_RESULT_CHARS}.
+     *
+     * Why this exists: DeepSeek V3's context is 131,072 tokens. A single
+     * `read_file` against a big source file can return >3 MB of text
+     * (~900k tokens) and permanently poison the session — every subsequent
+     * turn rebuilds the history and 400s. This cap is a floor. Users who
+     * legitimately want bigger payloads can raise it explicitly.
+     */
+    maxResultChars?: number;
 }
+/**
+ * 32,000 chars ≈ 8k English tokens, or ~16k CJK tokens. Small enough to
+ * fit comfortably in history even across 5–10 tool calls, large enough
+ * that most file reads and directory listings fit un-truncated.
+ */
+declare const DEFAULT_MAX_RESULT_CHARS = 32000;
 interface BridgeResult {
     registry: ToolRegistry;
     /** Names actually registered (may differ from MCP names when a prefix is applied). */
@@ -1033,6 +1127,10 @@ interface BridgeResult {
  * they fit Reasonix's existing tool-dispatch contract.
  */
 declare function bridgeMcpTools(client: McpClient, opts?: BridgeOptions): Promise<BridgeResult>;
+interface FlattenOptions {
+    /** Cap the flattened string at this many characters. Default: no cap. */
+    maxChars?: number;
+}
 /**
  * Turn an MCP CallToolResult into a string — the contract Reasonix's
  * ToolRegistry.dispatch returns. We:
@@ -1042,8 +1140,58 @@ declare function bridgeMcpTools(client: McpClient, opts?: BridgeOptions): Promis
  *     prompts later)
  *   - prefix error results with "ERROR: " so the calling model sees the
  *     failure clearly even through JSON mode
+ *   - optionally truncate to `maxChars` so a single oversized tool result
+ *     (e.g. a big `read_file`) can't poison the session by blowing past
+ *     the model's context window
+ */
+declare function flattenMcpResult(result: CallToolResult, opts?: FlattenOptions): string;
+/**
+ * Keep the head AND a short tail so the model sees both "what the tool
+ * started returning" and "how it ended". Head-only loses file endings
+ * (e.g. an error message appended at the bottom of a stack trace); the
+ * 1KB tail window covers that while costing almost nothing. Exported for
+ * tests and reuse by non-MCP tool adapters that want the same policy.
  */
-declare function flattenMcpResult(result: CallToolResult): string;
+declare function truncateForModel(s: string, maxChars: number): 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.
@@ -1055,10 +1203,36 @@ declare function flattenMcpResult(result: CallToolResult): string;
  * The library itself never touches the config file — it only reads
  * `DEEPSEEK_API_KEY` from the environment. The CLI is responsible for
  * pulling from the config file and exposing it via env var to the loop.
+ *
+ * Beyond the API key, the config also remembers the user's *defaults*
+ * from `reasonix setup`: preset, MCP servers, session. This is what
+ * makes `reasonix chat` with no flags "just work" after first-run.
  */
+/** One of the preset bundles (model + harvest + branch combo). */
+type PresetName = "fast" | "smart" | "max";
 interface ReasonixConfig {
     apiKey?: string;
     baseUrl?: string;
+    /**
+     * Default preset for `reasonix chat` / `reasonix run` when no flags override.
+     * Maps to model + harvest + branch combos (see presets.ts). Missing → "fast".
+     */
+    preset?: PresetName;
+    /**
+     * Default MCP server specs to bridge on every `reasonix chat`, in the
+     * same `"name=cmd args..."` format that `--mcp` takes. Stored as strings
+     * so `reasonix setup` stays symmetrical with the flag — one parser, one
+     * format in the config file, grep-friendly.
+     */
+    mcp?: string[];
+    /**
+     * Default session name (null/missing → "default", which is what the
+     * CLI has been doing anyway). `reasonix setup` lets users pick a name
+     * or opt into ephemeral.
+     */
+    session?: string | null;
+    /** Marks that `reasonix setup` has completed at least once. */
+    setupCompleted?: boolean;
 }
 declare function defaultConfigPath(): string;
 declare function readConfig(path?: string): ReasonixConfig;
@@ -1072,6 +1246,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.6";
 
-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, DEFAULT_MAX_RESULT_CHARS, DeepSeekClient, type DeepSeekClientOptions, type RenderOptions as DiffRenderOptions, type DiffReport, type DiffSide, type EventRole, type FlattenDecision, type FlattenOptions, 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, formatLoopError, harvest, healLoadedMessages, 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, truncateForModel, writeConfig, writeMeta, writeRecord };