reasonix 0.4.6 → 0.4.12

package/dist/index.d.ts

@@ -120,6 +120,23 @@ interface StreamChunk {
     finishReason?: string;
     raw: any;
 }
+/**
+ * Response shape for DeepSeek's `/user/balance` endpoint. One entry
+ * per currency the account is funded in (typically CNY, sometimes
+ * USD). `total_balance` is the spendable figure; `granted_balance`
+ * counts promotional credits that expire, `topped_up_balance` is
+ * what the user paid for and keeps.
+ */
+interface BalanceInfo {
+    currency: string;
+    total_balance: string;
+    granted_balance?: string;
+    topped_up_balance?: string;
+}
+interface UserBalance {
+    is_available: boolean;
+    balance_infos: BalanceInfo[];
+}
 interface DeepSeekClientOptions {
     apiKey?: string;
     baseUrl?: string;
@@ -136,6 +153,15 @@ declare class DeepSeekClient {
     private readonly _fetch;
     constructor(opts?: DeepSeekClientOptions);
     private buildPayload;
+    /**
+     * Fetch the current DeepSeek account balance. Separate endpoint
+     * from chat completions, no billing impact. Returns null on any
+     * network/auth failure so callers can gate the balance display
+     * without a hard error — the rest of the session works regardless.
+     */
+    getBalance(opts?: {
+        signal?: AbortSignal;
+    }): Promise<UserBalance | null>;
     chat(opts: ChatRequestOptions): Promise<ChatResponse>;
     stream(opts: ChatRequestOptions): AsyncGenerator<StreamChunk>;
 }
@@ -172,7 +198,7 @@ interface HarvestOptions {
 }
 declare function emptyPlanState(): TypedPlanState;
 declare function isPlanStateEmpty(s: TypedPlanState | null | undefined): boolean;
-declare function harvest(reasoningContent: string | null | undefined, client?: DeepSeekClient, options?: HarvestOptions): Promise<TypedPlanState>;
+declare function harvest(reasoningContent: string | null | undefined, client?: DeepSeekClient, options?: HarvestOptions, signal?: AbortSignal): Promise<TypedPlanState>;
 
 /**
  * Self-consistency branching.
@@ -373,6 +399,10 @@ declare class ToolCallRepair {
 }
 
 declare function costUsd(model: string, usage: Usage): number;
+/** Input-side cost only (prompt, cache hit + miss). Used for the panel breakdown. */
+declare function inputCostUsd(model: string, usage: Usage): number;
+/** Output-side cost only (completion tokens). Used for the panel breakdown. */
+declare function outputCostUsd(model: string, usage: Usage): number;
 declare function claudeEquivalentCost(usage: Usage): number;
 interface TurnStats {
     turn: number;
@@ -384,7 +414,17 @@ interface TurnStats {
 interface SessionSummary {
     turns: number;
     totalCostUsd: number;
+    /**
+     * Input-side (prompt) cost aggregated across the session. Split
+     * from totalCostUsd so the panel can render "cost $X (in $Y · out
+     * $Z)" — users asked for visibility into where the spend lands.
+     */
+    totalInputCostUsd: number;
+    /** Output-side (completion) cost aggregated across the session. */
+    totalOutputCostUsd: number;
+    /** @deprecated Claude reference; kept for benchmarks + replay compat, no longer surfaced in the TUI. */
     claudeEquivalentUsd: number;
+    /** @deprecated. Same as claudeEquivalentUsd — synthetic ratio, not a real measurement. */
     savingsVsClaudePct: number;
     cacheHitRatio: number;
     /**
@@ -401,15 +441,28 @@ declare class SessionStats {
     get totalCost(): number;
     get totalClaudeEquivalent(): number;
     get savingsVsClaude(): number;
+    get totalInputCost(): number;
+    get totalOutputCost(): number;
     get aggregateCacheHitRatio(): number;
     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 +483,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"
@@ -441,7 +496,16 @@ type EventRole = "assistant_delta" | "assistant_final"
  * takes more than a few hundred ms (a big `filesystem_edit_file`
  * is a typical trigger).
  */
- | "tool_start" | "tool" | "done" | "error" | "warning" | "branch_start" | "branch_progress" | "branch_done";
+ | "tool_start" | "tool" | "done" | "error" | "warning"
+/**
+ * Transient "what's happening right now" indicator. Emitted during
+ * silent phases — between a tool result and the next iteration's
+ * first streaming byte, and right before harvest — so the TUI can
+ * show a spinner with explanatory text instead of looking frozen.
+ * The UI clears it on the next primary event (assistant_delta,
+ * tool_start, tool, assistant_final, error).
+ */
+ | "status" | "branch_start" | "branch_progress" | "branch_done";
 interface BranchSummary {
     budget: number;
     chosenIndex: number;
@@ -547,11 +611,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
@@ -569,6 +635,20 @@ declare class CacheFirstLoop {
         charsSaved: number;
     };
     private appendAndPersist;
+    /**
+     * Start a fresh conversation WITHOUT exiting. Drops every message
+     * in the in-memory log AND rewrites the session file to empty so
+     * a resume won't re-hydrate the old turns. Unlike `/forget`, which
+     * deletes the session entirely, this keeps the session name and
+     * config intact — it's the "new chat" button.
+     *
+     * The immutable prefix (system prompt + tool specs) is preserved
+     * — that's the cache-first invariant, not part of the conversation.
+     * Returns the number of messages dropped so the UI can show it.
+     */
+    clearLog(): {
+        dropped: number;
+    };
     /**
      * Reconfigure model/harvest/branch/stream mid-session. The loop's log,
      * scratch, and stats are preserved — only the per-turn behavior changes.
@@ -578,11 +658,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;
     /**
@@ -613,12 +694,6 @@ declare class CacheFirstLoop {
  * Exported so tests can exercise it against concrete R1 outputs.
  */
 declare function stripHallucinatedToolMarkup(s: string): string;
-/**
- * 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;
@@ -634,6 +709,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 +1093,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;
@@ -1155,6 +1294,8 @@ declare class McpClient {
     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"];
@@ -1171,8 +1312,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`.
@@ -1288,6 +1447,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
@@ -1579,4 +1751,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 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 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 SectionResult, 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, inspectMcpServer, 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, inputCostUsd, inspectMcpServer, isJsonRpcError, isPlanStateEmpty, isPlausibleKey, listSessions, loadApiKey, loadDotenv, loadSessionMessages, nestArguments, openTranscriptFile, outputCostUsd, 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 };