reasonix 0.4.5 → 0.4.9

package/dist/index.d.ts

@@ -405,11 +405,22 @@ declare class SessionStats {
     summary(): SessionSummary;
 }
 
+/**
+ * Per-call context a tool `fn` can optionally consume. Today the only
+ * field is `signal`, plumbed through so long-running tools (MCP calls,
+ * HTTP requests) can abort when the user presses Esc. Omitted fields
+ * stay optional — tools written against the pre-0.4.9 signature keep
+ * working; they just ignore cancellation, which is fine for fast
+ * local work where "await finishes" happens before the next tick anyway.
+ */
+interface ToolCallContext {
+    signal?: AbortSignal;
+}
 interface ToolDefinition<A = any, R = any> {
     name: string;
     description?: string;
     parameters?: JSONSchema;
-    fn: (args: A) => R | Promise<R>;
+    fn: (args: A, ctx?: ToolCallContext) => R | Promise<R>;
 }
 interface ToolRegistryOptions {
     /**
@@ -430,7 +441,9 @@ declare class ToolRegistry {
     /** True if a registered tool's schema was flattened for the model. */
     wasFlattened(name: string): boolean;
     specs(): ToolSpec[];
-    dispatch(name: string, argumentsRaw: string | Record<string, unknown>): Promise<string>;
+    dispatch(name: string, argumentsRaw: string | Record<string, unknown>, opts?: {
+        signal?: AbortSignal;
+    }): Promise<string>;
 }
 
 type EventRole = "assistant_delta" | "assistant_final"
@@ -547,11 +560,13 @@ declare class CacheFirstLoop {
     private _turn;
     private _streamPreference;
     /**
-     * Set by {@link abort} to short-circuit the tool-call loop after the
-     * current iteration. Reset at the start of each `step()` so an Esc
-     * during one turn doesn't poison the next.
+     * AbortController per active turn. Threaded through the DeepSeek
+     * HTTP calls AND every tool dispatch so Esc actually cancels the
+     * in-flight network/subprocess work — not "we'll get to it after
+     * the current call finishes." Re-created at the start of each
+     * `step()` (the prior turn's signal has already fired).
      */
-    private _aborted;
+    private _turnAbort;
     constructor(opts: CacheFirstLoopOptions);
     /**
      * Shrink the log by re-truncating oversized tool results to a tighter
@@ -578,11 +593,12 @@ declare class CacheFirstLoop {
     configure(opts: ReconfigurableOptions): void;
     private buildMessages;
     /**
-     * Signal the currently-running {@link step} that the user wants to
-     * stop exploring. Takes effect at the next iteration boundary — if a
-     * tool call is mid-flight it will be allowed to finish, then the
-     * loop diverts to the forced-summary path so the user gets an
-     * answer instead of a cliff. Called by the TUI on Esc.
+     * Signal the currently-running {@link step} to stop **now**. Cancels
+     * the in-flight network request (DeepSeek HTTP/SSE) AND any tool call
+     * currently dispatching (MCP `notifications/cancelled` + promise
+     * reject). The loop itself also sees `signal.aborted` at each
+     * iteration boundary and exits quickly instead of looping again.
+     * Called by the TUI on Esc.
      */
     abort(): void;
     /**
@@ -634,6 +650,50 @@ declare function healLoadedMessages(messages: ChatMessage[], maxChars: number):
  */
 declare function formatLoopError(err: Error): string;
 
+/**
+ * Built-in filesystem tools for `reasonix code`.
+ *
+ * Why native instead of the official `@modelcontextprotocol/server-filesystem`:
+ *   - No subprocess overhead — every call is 50-200 ms cheaper.
+ *   - Schema shapes tuned for R1: `edit_file` takes a single
+ *     SEARCH/REPLACE string instead of `string="false"`-encoded
+ *     JSON arrays, which was the biggest single source of DSML
+ *     hallucinations in 0.4.x.
+ *   - Sandbox enforcement lives here so Reasonix can reason about
+ *     it (tests cover path-traversal, symlink-escape, and the
+ *     cwd-outside-root case) rather than trusting an external server.
+ *   - No `npx install` / network dependency in `reasonix code`.
+ *
+ * Tool names + argument shapes intentionally mirror the official
+ * filesystem server so R1's muscle memory carries over. The only
+ * intentional divergence is `edit_file`, noted above.
+ */
+
+interface FilesystemToolsOptions {
+    /** Absolute directory the tools may read/write. Paths outside this are refused. */
+    rootDir: string;
+    /**
+     * When `false`, register only read-side tools (read_file, list_directory,
+     * search_files, get_file_info, directory_tree). Useful for read-only
+     * workflows where the model should never mutate the tree. Default: true.
+     */
+    allowWriting?: boolean;
+    /**
+     * Cap for a single file read, in bytes. Prevents a stray `read_file`
+     * on a multi-GB blob from OOM'ing Node. 2 MB is enough for any realistic
+     * source file (the biggest single-file TypeScript project checked in to
+     * GitHub is ~500 KB); pass higher when working with data files.
+     */
+    maxReadBytes?: number;
+    /**
+     * Cap for total bytes returned from search_files / directory_tree /
+     * grep, so the model can't accidentally pull down the whole tree as
+     * one giant string. 256 KB by default.
+     */
+    maxListBytes?: number;
+}
+declare function registerFilesystemTools(registry: ToolRegistry, opts: FilesystemToolsOptions): ToolRegistry;
+
 /**
  * Session persistence.
  *
@@ -974,6 +1034,26 @@ interface ListToolsResult {
     tools: McpTool[];
     nextCursor?: string;
 }
+/**
+ * Server → client notification emitted during a long-running request
+ * that the client subscribed to via `_meta.progressToken`. `progress`
+ * and `total` are typically matched units (files scanned, bytes
+ * processed, etc.); `total` may be missing when the server can't
+ * estimate the upper bound up front.
+ */
+interface ProgressNotificationParams {
+    progressToken: string | number;
+    progress: number;
+    total?: number;
+    message?: string;
+}
+/** Values a `ProgressHandler` receives — `progressToken` is already matched away. */
+interface McpProgressInfo {
+    progress: number;
+    total?: number;
+    message?: string;
+}
+type McpProgressHandler = (info: McpProgressInfo) => void;
 interface McpContentBlockText {
     type: "text";
     text: string;
@@ -1152,9 +1232,20 @@ declare class McpClient {
     private readerStarted;
     private initialized;
     private _serverCapabilities;
+    private _serverInfo;
+    private _protocolVersion;
+    private _instructions;
+    private readonly progressHandlers;
+    private nextProgressToken;
     constructor(opts: McpClientOptions);
     /** Server's advertised capabilities, available after initialize(). */
     get serverCapabilities(): InitializeResult["capabilities"];
+    /** Server's self-reported name + version, available after initialize(). */
+    get serverInfo(): InitializeResult["serverInfo"];
+    /** Protocol version the server agreed to during the handshake. */
+    get protocolVersion(): string;
+    /** Optional free-form instructions the server provides at handshake. */
+    get serverInstructions(): string | undefined;
     /**
      * Complete the initialize → initialized handshake. Must be called
      * before any other method (otherwise compliant servers reject).
@@ -1162,8 +1253,26 @@ declare class McpClient {
     initialize(): Promise<InitializeResult>;
     /** List tools the server exposes. */
     listTools(): Promise<ListToolsResult>;
-    /** Invoke a tool by name. Returns the raw MCP result (caller unwraps content). */
-    callTool(name: string, args?: Record<string, unknown>): Promise<CallToolResult>;
+    /**
+     * Invoke a tool by name. When `onProgress` is supplied, attaches a
+     * fresh progress token so the server can send incremental updates
+     * via `notifications/progress`; they're routed to the callback until
+     * the final response arrives (or the request times out, in which
+     * case the handler is simply dropped — no extra notification).
+     *
+     * When `signal` is supplied, aborting it:
+     *   1) fires `notifications/cancelled` to the server (MCP 2024-11-05
+     *      way of saying "forget this request, I no longer care"), and
+     *   2) rejects the pending promise immediately with an AbortError,
+     *      so the caller doesn't have to wait for the subprocess to
+     *      finish its in-flight file write or network request.
+     * The server MAY still emit a late response; we drop it in dispatch
+     * since the request id is gone from `pending`.
+     */
+    callTool(name: string, args?: Record<string, unknown>, opts?: {
+        onProgress?: McpProgressHandler;
+        signal?: AbortSignal;
+    }): Promise<CallToolResult>;
     /**
      * List resources the server exposes. Supports a pagination cursor;
      * callers interested in the full set should loop on `nextCursor`.
@@ -1279,6 +1388,19 @@ interface BridgeOptions {
      * legitimately want bigger payloads can raise it explicitly.
      */
     maxResultChars?: number;
+    /**
+     * Callback fired for every `notifications/progress` frame the server
+     * emits during any bridged tool call. Includes the registered
+     * (prefix-applied) tool name so a multi-server UI can attribute
+     * progress correctly. Absent → no `_meta.progressToken` is sent and
+     * the server won't emit progress for these calls.
+     */
+    onProgress?: (info: {
+        toolName: string;
+        progress: number;
+        total?: number;
+        message?: string;
+    }) => void;
 }
 /**
  * 32,000 chars ≈ 8k English tokens, or ~16k CJK tokens. Small enough to
@@ -1370,6 +1492,44 @@ interface SseMcpSpec {
 type McpSpec = StdioMcpSpec | SseMcpSpec;
 declare function parseMcpSpec(input: string): McpSpec;
 
+/**
+ * Gather a full inspection report from an initialized MCP client:
+ * server info, capabilities, tools, resources, prompts. Methods the
+ * server doesn't support come back as `{ supported: false }` instead
+ * of throwing, so a CLI or UI can render a consistent "what this
+ * server exposes" summary even against minimal implementations.
+ *
+ * Pure with respect to I/O beyond the passed-in client — the CLI
+ * layer owns argument parsing, connection setup, and printing.
+ */
+
+interface InspectionReport {
+    protocolVersion: string;
+    serverInfo: {
+        name: string;
+        version: string;
+    };
+    capabilities: Record<string, unknown>;
+    instructions?: string;
+    tools: SectionResult<McpTool>;
+    resources: SectionResult<McpResource>;
+    prompts: SectionResult<McpPrompt>;
+}
+type SectionResult<T> = {
+    supported: true;
+    items: T[];
+} | {
+    supported: false;
+    reason: string;
+};
+/**
+ * Run an inspection against a **already-initialized** client. Caller
+ * is responsible for `initialize()` before this and `close()` after.
+ * We keep this pure so unit tests can feed in a FakeMcpTransport and
+ * verify the aggregate shape without spinning up a real process.
+ */
+declare function inspectMcpServer(client: McpClient): Promise<InspectionReport>;
+
 /**
  * Aider-style SEARCH/REPLACE edit blocks.
  *
@@ -1532,4 +1692,4 @@ declare function redactKey(key: string): string;
 
 declare const VERSION = "0.4.3";
 
-export { AppendOnlyLog, type ApplyResult, type ApplyStatus, type BranchOptions, type BranchProgress, type BranchResult, type BranchSample, type BranchSelector, type BranchSummary, type BridgeOptions, type BridgeResult, CODE_SYSTEM_PROMPT, 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 EditBlock, type EditSnapshot, type EventRole, type FlattenDecision, type FlattenOptions, type GetPromptResult, type HarvestOptions, ImmutablePrefix, type ImmutablePrefixOptions, type InitializeResult, type JSONSchema, type JsonRpcMessage, type JsonRpcRequest, type JsonRpcResponse, type ListPromptsResult, type ListResourcesResult, type ListToolsResult, type LoopEvent, MCP_PROTOCOL_VERSION, McpClient, type McpClientOptions, type McpContentBlock, type McpPrompt, type McpPromptArgument, type McpPromptMessage, type McpPromptResourceBlock, type McpResource, type McpResourceContents, type McpResourceContentsBlob, type McpResourceContentsText, type McpSpec, type McpTool, type McpToolSchema, type McpTransport, type ReadResourceResult, 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, applyEditBlock, applyEditBlocks, bridgeMcpTools, claudeEquivalentCost, codeSystemPrompt, computeReplayStats, costUsd, defaultConfigPath, defaultSelector, deleteSession, diffTranscripts, emptyPlanState, fetchWithRetry, flattenMcpResult, flattenSchema, formatLoopError, harvest, healLoadedMessages, isJsonRpcError, isPlanStateEmpty, isPlausibleKey, listSessions, loadApiKey, loadDotenv, loadSessionMessages, nestArguments, openTranscriptFile, parseEditBlocks, parseMcpSpec, parseTranscript, readConfig, readTranscript, recordFromLoopEvent, redactKey, renderMarkdown as renderDiffMarkdown, renderSummaryTable as renderDiffSummary, repairTruncatedJson, replayFromFile, restoreSnapshots, runBranches, sanitizeName as sanitizeSessionName, saveApiKey, scavengeToolCalls, sessionPath, sessionsDir, similarity, snapshotBeforeEdits, stripHallucinatedToolMarkup, truncateForModel, writeConfig, writeMeta, writeRecord };
+export { AppendOnlyLog, type ApplyResult, type ApplyStatus, type BranchOptions, type BranchProgress, type BranchResult, type BranchSample, type BranchSelector, type BranchSummary, type BridgeOptions, type BridgeResult, CODE_SYSTEM_PROMPT, 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 EditBlock, type EditSnapshot, type EventRole, type FilesystemToolsOptions, type FlattenDecision, type FlattenOptions, type GetPromptResult, type HarvestOptions, ImmutablePrefix, type ImmutablePrefixOptions, type InitializeResult, type InspectionReport, type JSONSchema, type JsonRpcMessage, type JsonRpcRequest, type JsonRpcResponse, type ListPromptsResult, type ListResourcesResult, type ListToolsResult, type LoopEvent, MCP_PROTOCOL_VERSION, McpClient, type McpClientOptions, type McpContentBlock, type McpProgressHandler, type McpProgressInfo, type McpPrompt, type McpPromptArgument, type McpPromptMessage, type McpPromptResourceBlock, type McpResource, type McpResourceContents, type McpResourceContentsBlob, type McpResourceContentsText, type McpSpec, type McpTool, type McpToolSchema, type McpTransport, type ProgressNotificationParams, type ReadResourceResult, type ReadTranscriptResult, type ReasonixConfig, type ReconfigurableOptions, type RepairReport, type ReplayStats, type RetryInfo, type RetryOptions, type Role, type ScavengeOptions, type ScavengeResult, type SectionResult, type SessionInfo, SessionStats, type SessionSummary, type SseMcpSpec, SseTransport, type SseTransportOptions, type StdioMcpSpec, StdioTransport, type StdioTransportOptions, StormBreaker, type StreamChunk, type ToolCall, type ToolCallContext, 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, applyEditBlock, applyEditBlocks, bridgeMcpTools, claudeEquivalentCost, codeSystemPrompt, computeReplayStats, costUsd, defaultConfigPath, defaultSelector, deleteSession, diffTranscripts, emptyPlanState, fetchWithRetry, flattenMcpResult, flattenSchema, formatLoopError, harvest, healLoadedMessages, inspectMcpServer, isJsonRpcError, isPlanStateEmpty, isPlausibleKey, listSessions, loadApiKey, loadDotenv, loadSessionMessages, nestArguments, openTranscriptFile, parseEditBlocks, parseMcpSpec, parseTranscript, readConfig, readTranscript, recordFromLoopEvent, redactKey, registerFilesystemTools, renderMarkdown as renderDiffMarkdown, renderSummaryTable as renderDiffSummary, repairTruncatedJson, replayFromFile, restoreSnapshots, runBranches, sanitizeName as sanitizeSessionName, saveApiKey, scavengeToolCalls, sessionPath, sessionsDir, similarity, snapshotBeforeEdits, stripHallucinatedToolMarkup, truncateForModel, writeConfig, writeMeta, writeRecord };