reasonix 0.4.14 → 0.4.16

package/dist/index.d.ts

@@ -762,6 +762,184 @@ interface FilesystemToolsOptions {
 }
 declare function registerFilesystemTools(registry: ToolRegistry, opts: FilesystemToolsOptions): ToolRegistry;
 
+/**
+ * Native shell tool — lets the model run commands inside the sandbox
+ * root so it can actually verify its own work (run tests, check git
+ * status, inspect a lockfile, etc.). Without this the coding-mode
+ * loop is "write code, hope it works, ask the user to run it" —
+ * defeats the purpose.
+ *
+ * Safety model:
+ *   - Commands run with `cwd` pinned to the registered root. No
+ *     path traversal via the command itself is enforced (users can
+ *     `cat ../outside.txt`); the trust boundary is the directory
+ *     you opened Reasonix from.
+ *   - Commands are matched against a read-only / testing allowlist.
+ *     Allowlisted commands execute immediately and return stdout +
+ *     stderr merged. Everything else throws with a clear message —
+ *     the UI translates that into an `/apply`-style confirm gate so
+ *     the user sees the exact command before it runs.
+ *   - Default timeout: 60s. Output cap: matches tool-result budget.
+ *   - Every command that DOES run is spawned with `shell: false` and
+ *     a tokenized argv — no string-to-shell interpolation, so the
+ *     model can't accidentally construct a chained `rm` via quoting.
+ *
+ * This is intentionally narrower than what Claude Code / Aider ship:
+ * we gate more commands behind confirmation by default. Users who
+ * trust the model can widen the allowlist by instantiating their
+ * own tool registry.
+ */
+
+interface ShellToolsOptions {
+    /** Directory to run commands in. Must be an absolute path. */
+    rootDir: string;
+    /** Seconds before an individual command is killed. Default: 60. */
+    timeoutSec?: number;
+    /**
+     * Per-command stdout+stderr cap in characters. Default: 32_000 to
+     * match the tool-result budget.
+     */
+    maxOutputChars?: number;
+    /**
+     * Extra command-name prefixes the user explicitly trusts. Added on
+     * top of the built-in allowlist. Examples: `["my-ci-script", "lint"]`.
+     */
+    extraAllowed?: string[];
+    /**
+     * When true, skip the allowlist entirely and auto-run every command.
+     * Off by default — this is an escape hatch for non-interactive use
+     * (CI, benchmarks) where a human can't be in the loop to confirm.
+     */
+    allowAll?: boolean;
+}
+/**
+ * Tokenize a shell-ish command string into argv. Handles single/double
+ * quoting; rejects unclosed quotes. Does NOT expand env vars, globs,
+ * backticks, or `$(…)` — the goal is to prevent the model from
+ * accidentally (or not) sneaking arbitrary shells past the allowlist
+ * via concatenation. Exported for testing.
+ */
+declare function tokenizeCommand(cmd: string): string[];
+/**
+ * Return true when `cmd` matches an allowlisted prefix. Exported for
+ * testing. Match is on the space-normalized leading tokens so
+ * `git   status  -s ` and `git status` both match `git status`.
+ */
+declare function isAllowed(cmd: string, extra?: readonly string[]): boolean;
+interface RunCommandResult {
+    exitCode: number | null;
+    /** Combined stdout+stderr, truncated to `maxOutputChars` with a marker. */
+    output: string;
+    /** True when the process was killed for exceeding `timeoutSec`. */
+    timedOut: boolean;
+}
+declare function runCommand(cmd: string, opts: {
+    cwd: string;
+    timeoutSec?: number;
+    maxOutputChars?: number;
+    signal?: AbortSignal;
+}): Promise<RunCommandResult>;
+/** Error thrown by `run_command` when the command isn't allowlisted. */
+declare class NeedsConfirmationError extends Error {
+    readonly command: string;
+    constructor(command: string);
+}
+declare function registerShellTools(registry: ToolRegistry, opts: ShellToolsOptions): ToolRegistry;
+declare function formatCommandResult(cmd: string, r: RunCommandResult): string;
+
+/**
+ * Built-in web search + fetch tools.
+ *
+ *   - `web_search(query, topK?)` — Mojeek's public search page. No API
+ *     key, no signup. We originally shipped this backed by DuckDuckGo's
+ *     HTML endpoint, but DDG started serving anti-bot interstitials
+ *     (HTTP 202 with a challenge page) for every unauthenticated POST.
+ *     Mojeek runs its own independent index, is bot-friendly, and
+ *     returns parseable HTML.
+ *   - `web_fetch(url)` — HTTP GET + naïve HTML-to-text extraction.
+ *
+ * Both are registered by default on `reasonix chat` / `reasonix code`;
+ * set `search: false` in config (or `REASONIX_SEARCH=off`) to turn
+ * them off. The model decides when to call them based on the query —
+ * no slash command required.
+ */
+
+interface SearchResult {
+    title: string;
+    url: string;
+    snippet: string;
+}
+interface PageContent {
+    url: string;
+    title?: string;
+    text: string;
+    /** True when the extracted text was clipped to fit the cap. */
+    truncated: boolean;
+}
+interface WebFetchOptions {
+    /** Max bytes of extracted text. Defaults to 32_000 to match tool-result cap. */
+    maxChars?: number;
+    /** Timeout in ms. Defaults to 15_000. */
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}
+interface WebSearchOptions {
+    topK?: number;
+    signal?: AbortSignal;
+}
+/**
+ * Search the public web via Mojeek. Returns up to `topK` ranked
+ * results with title, url, snippet.
+ *
+ * Mojeek is an independent index (not a Google/Bing front-end) which
+ * means coverage on niche or very recent topics can be thinner, but
+ * it's reliable from scripts and doesn't gate on cookies or sessions.
+ * If the response has 0 results we distinguish "truly empty" from
+ * "layout changed or blocked" so the caller isn't left guessing.
+ */
+declare function webSearch(query: string, opts?: WebSearchOptions): Promise<SearchResult[]>;
+/**
+ * Extract results from a Mojeek search page.
+ *
+ * Mojeek's stable shape (as of April 2026):
+ *   <a … class="ob" href="URL"> … breadcrumb … </a>
+ *   <h2><a class="title" href="URL">Title</a></h2>
+ *   <p class="s">snippet text …</p>
+ *
+ * We do two tolerant passes — title anchors, then snippet paragraphs —
+ * and pair them positionally. Attribute order inside a tag varies
+ * between versions, so each pass captures the whole element and we
+ * re-extract href / inner text with a second regex. Exported for
+ * unit testing against a fixture.
+ */
+declare function parseMojeekResults(html: string): SearchResult[];
+/**
+ * Download a URL, strip HTML down to readable text, return it. Times
+ * out at 15s, caps extracted text at 32k chars to fit the tool-result
+ * budget.
+ */
+declare function webFetch(url: string, opts?: WebFetchOptions): Promise<PageContent>;
+/**
+ * Strip HTML to readable text. Removes scripts/styles/nav/footer/aside
+ * blocks first, then tags, then collapses whitespace. Not a Readability
+ * clone — purpose-built to keep the extracted text small enough for the
+ * tool-result budget while preserving paragraph breaks.
+ */
+declare function htmlToText(html: string): string;
+interface WebToolsOptions {
+    /** Default top-K for `web_search` when the model doesn't specify. */
+    defaultTopK?: number;
+    /** Byte cap for `web_fetch` extracted text. */
+    maxFetchChars?: number;
+}
+/**
+ * Register `web_search` + `web_fetch` on a ToolRegistry. The model
+ * invokes them automatically when a question needs current info —
+ * no slash command from the user is required.
+ */
+declare function registerWebTools(registry: ToolRegistry, opts?: WebToolsOptions): ToolRegistry;
+declare function formatSearchResults(query: string, results: SearchResult[]): string;
+
 /**
  * Session persistence.
  *
@@ -1745,6 +1923,23 @@ interface ReasonixConfig {
     session?: string | null;
     /** Marks that `reasonix setup` has completed at least once. */
     setupCompleted?: boolean;
+    /**
+     * Whether `web_search` + `web_fetch` tools are registered. Default:
+     * enabled (no key required — backed by DuckDuckGo's public HTML
+     * endpoint). Set to `false` to keep the session offline.
+     */
+    search?: boolean;
+    /**
+     * Per-project state keyed by absolute directory path. Written by the
+     * "always allow" choice on a shell confirmation prompt; merged into
+     * `registerShellTools({ extraAllowed })` when `reasonix code` runs
+     * against that directory again.
+     */
+    projects?: {
+        [absoluteRootDir: string]: {
+            shellAllowed?: string[];
+        };
+    };
 }
 declare function defaultConfigPath(): string;
 declare function readConfig(path?: string): ReasonixConfig;
@@ -1758,6 +1953,6 @@ declare function redactKey(key: string): string;
 
 /** Reasonix — DeepSeek-native agent framework. Library entry point. */
 
-declare const VERSION = "0.4.14";
+declare const VERSION = "0.4.16";
 
-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 };
+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, NeedsConfirmationError, type PageContent, type ProgressNotificationParams, type ReadResourceResult, type ReadTranscriptResult, type ReasonixConfig, type ReconfigurableOptions, type RepairReport, type ReplayStats, type RetryInfo, type RetryOptions, type Role, type RunCommandResult, type ScavengeOptions, type ScavengeResult, type SearchResult, type SectionResult, type SessionInfo, SessionStats, type SessionSummary, type ShellToolsOptions, 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, type WebFetchOptions, type WebSearchOptions, type WebToolsOptions, aggregateBranchUsage, analyzeSchema, appendSessionMessage, applyEditBlock, applyEditBlocks, bridgeMcpTools, claudeEquivalentCost, codeSystemPrompt, computeReplayStats, costUsd, defaultConfigPath, defaultSelector, deleteSession, diffTranscripts, emptyPlanState, fetchWithRetry, flattenMcpResult, flattenSchema, formatCommandResult, formatLoopError, formatSearchResults, harvest, healLoadedMessages, htmlToText, inputCostUsd, inspectMcpServer, isAllowed, isJsonRpcError, isPlanStateEmpty, isPlausibleKey, listSessions, loadApiKey, loadDotenv, loadSessionMessages, nestArguments, openTranscriptFile, outputCostUsd, parseEditBlocks, parseMcpSpec, parseMojeekResults, parseTranscript, readConfig, readTranscript, recordFromLoopEvent, redactKey, registerFilesystemTools, registerShellTools, registerWebTools, renderMarkdown as renderDiffMarkdown, renderSummaryTable as renderDiffSummary, repairTruncatedJson, replayFromFile, restoreSnapshots, runBranches, runCommand, sanitizeName as sanitizeSessionName, saveApiKey, scavengeToolCalls, sessionPath, sessionsDir, similarity, snapshotBeforeEdits, stripHallucinatedToolMarkup, tokenizeCommand, truncateForModel, webFetch, webSearch, writeConfig, writeMeta, writeRecord };