reasonix 0.3.1 → 0.4.1

package/README.md

@@ -6,20 +6,25 @@
 [![downloads](https://img.shields.io/npm/dm/reasonix.svg)](https://www.npmjs.com/package/reasonix)
 [![node](https://img.shields.io/node/v/reasonix.svg)](./package.json)
 
-**The DeepSeek-native agent framework.** TypeScript. Ink TUI. No LangChain.
-
-Reasonix is not another generic agent wrapper. Every abstraction is justified
-by a DeepSeek-specific property — dirt-cheap tokens, R1 reasoning traces,
-automatic prefix caching, JSON mode. Generic frameworks treat DeepSeek as
-"OpenAI with a different base URL" and leave these advantages on the table.
-Reasonix leans into them.
+**A DeepSeek-native AI coding assistant in your terminal.** Ink TUI. MCP
+first-class. No LangChain.
 
 ```bash
-npx reasonix chat          # first run prompts for your DeepSeek key
-                           # inside the TUI, type /help for everything else
+npx reasonix
 ```
 
-No flag soup. All feature toggles live behind slash commands in the TUI.
+One command. First run walks you through a 30-second wizard (API key →
+preset → pick MCP servers from a checklist); every run after that drops
+straight into chat with your tools wired up. Inside the chat, type `/help`.
+
+Why bother with yet another agent framework? Because every abstraction
+here earns its weight against a DeepSeek-specific property — dirt-cheap
+tokens, R1 reasoning traces, automatic prefix caching, JSON mode.
+Generic wrappers treat DeepSeek as "OpenAI with a different base URL"
+and leave these advantages on the table. Reasonix leans into them:
+on the same τ-bench-lite workload,
+[**94.4% cache hit, ~40% cheaper tokens, 100% pass rate**](#validated-numbers)
+vs. a cache-hostile baseline.
 
 ---
 
@@ -27,12 +32,15 @@ No flag soup. All feature toggles live behind slash commands in the TUI.
 
 | Feature | How it works | Opt in |
 |---|---|---|
+| **Setup wizard** | First run of `npx reasonix`: pick preset, multi-select MCP servers from a curated catalog, saved to config so the next run just launches chat | always on (first run) |
+| **MCP (stdio + SSE)** | Multi-server bridge — every MCP tool inherits Cache-First + repair + context-safety automatically. `reasonix mcp list` shows the catalog | always on |
 | **Cache-First Loop** | Immutable prefix + append-only log = prefix byte-stable across turns → DeepSeek's automatic prefix cache hits at 70–95% | always on |
-| **R1 Thought Harvesting** | Parses `reasoning_content` into typed `{ subgoals, hypotheses, uncertainties, rejectedPaths }` via a cheap V3 call | `--harvest` |
-| **Self-Consistency Branching** | Runs N parallel samples at spread temperatures; picks the one with the fewest flagged uncertainties | `--branch <N>` |
+| **Context safety net** | Tool results capped at 32k chars · oversized sessions auto-heal on load · `/compact` to shrink further · ctx gauge in the status bar · Esc to abort exploration and get a forced summary | always on |
+| **R1 Thought Harvesting** | Parses `reasoning_content` into typed `{ subgoals, hypotheses, uncertainties, rejectedPaths }` via a cheap V3 call | `/preset smart` |
+| **Self-Consistency Branching** | Runs N parallel samples at spread temperatures; picks the one with the fewest flagged uncertainties | `/preset max` / `/branch N` |
 | **Tool-Call Repair** | Auto-flattens deep/wide schemas, scavenges tool calls leaked into `<think>`, repairs truncated JSON, breaks call-storms | always on |
 | **Retry layer** | Exponential backoff + jitter on 408/429/500/502/503/504 and network errors. 4xx auth errors don't retry | always on |
-| **Ink TUI** | Live cache-hit / cost panel. Streams R1 thinking to a compact preview. Renders Markdown (bold / lists / code / stripped LaTeX) | always on |
+| **Ink TUI** | Live cache-hit / cost / context panel. Streams R1 thinking to a compact preview. Renders Markdown (bold / lists / code / stripped LaTeX) | always on |
 
 ---
 
@@ -91,10 +99,12 @@ with your own API key: `npx tsx benchmarks/tau-bench/runner.ts --repeats 3`.
 
 [r]: ./benchmarks/tau-bench/report.md
 
-### Extends to MCP (v0.3-alpha)
+### MCP — works out of the box
 
 Any [MCP](https://spec.modelcontextprotocol.io/) server's tools inherit
-the same Cache-First benefits. Two live runs, two data points:
+Cache-First + repair + context-safety automatically. The wizard (`npx
+reasonix`) lets you multi-select from a curated catalog — no flags, no
+JSON-by-hand. Three live reference runs:
 
 | server | turns | tool calls | cache hit | cost | vs Claude |
 |---|---:|---:|---:|---:|---:|
@@ -103,40 +113,21 @@ the same Cache-First benefits. Two live runs, two data points:
 | **both concurrently** (`demo_add` + `fs_write_file`) | 5 | 4 | **81.1%** | $0.001852 | −95.9% |
 
 The third row is the ecosystem proof: two MCP servers running as
-separate subprocesses, tools from both exercised in one conversation
-(compute `17+25` with the demo server, write the result to a real file
-via the filesystem server). **One single prefix hash across all 5
-turns** — byte-stability survives concurrent MCP subprocesses.
+separate subprocesses, tools from both exercised in one conversation.
+**One single prefix hash across all 5 turns** — byte-stability survives
+concurrent MCP subprocesses.
 
-**Reproduce without an API key** (replay the committed transcripts):
+Reproduce without an API key (replay the committed transcripts):
 
 ```bash
 npx reasonix replay benchmarks/tau-bench/transcripts/mcp-demo.add.jsonl
 npx reasonix replay benchmarks/tau-bench/transcripts/mcp-filesystem.jsonl
 ```
 
-**Reproduce with your own key** (live, ~$0.002):
-
-```bash
-# Don't know what MCP servers exist? Start here:
-reasonix mcp list
-# Prints a curated catalog (filesystem, fetch, github, sqlite, …) with
-# ready-to-paste --mcp commands.
-
-# One server:
-reasonix chat --mcp "filesystem=npx -y @modelcontextprotocol/server-filesystem /tmp/safe"
-
-# Multiple servers at once — each gets its own namespace prefix:
-reasonix chat \
-  --mcp "fs=npx -y @modelcontextprotocol/server-filesystem /tmp/safe" \
-  --mcp "mem=npx -y @modelcontextprotocol/server-memory"
-# Tools land in a shared registry as fs_read_file, mem_set, etc.
-
-# Remote / hosted MCP server — pass an http(s) URL instead of a command.
-# Reasonix opens an SSE stream and POSTs JSON-RPC to the endpoint the
-# server advertises (MCP 2024-11-05 HTTP+SSE transport).
-reasonix chat --mcp "kb=https://mcp.example.com/sse"
-```
+Supported transports: **stdio** (local `npx` or binary) and **HTTP+SSE**
+(remote / hosted servers, MCP 2024-11-05 spec). Pass an `http(s)://`
+URL to `--mcp` and Reasonix opens the SSE stream and POSTs JSON-RPC
+to the endpoint the server advertises.
 
 [mcp]: ./benchmarks/tau-bench/transcripts/mcp-demo.add.jsonl
 
@@ -144,55 +135,98 @@ reasonix chat --mcp "kb=https://mcp.example.com/sse"
 
 ## Usage
 
-### CLI
+### One command
 
 ```bash
-npx reasonix chat                # auto-saves to session 'default'; resumes next time
-npx reasonix chat --session work # use a different named session
-npx reasonix chat --no-session   # ephemeral — nothing persisted
-npx reasonix run "ask anything"  # one-shot, streams to stdout
-npx reasonix stats session.jsonl # quick summary of a transcript
-npx reasonix replay chat.jsonl   # pretty-print a transcript + rebuild cost/cache offline
-npx reasonix diff a.jsonl b.jsonl --md diff.md   # compare two transcripts: cache/cost delta + first divergence
+npx reasonix
 ```
 
-Sessions live as JSONL under `~/.reasonix/sessions/<name>.jsonl` — every
-turn's message log is appended atomically, so killing the CLI never loses
-context. Inside the TUI: `/sessions` to list, `/forget` to delete the
-current one.
+First run: a wizard asks for your API key, lets you pick a preset
+(fast / smart / max), then offers a multi-select checklist of MCP
+servers — filesystem, memory, github, puppeteer, everything. Everything
+is saved to `~/.reasonix/config.json`. Subsequent runs drop straight
+into chat.
 
-### Inside the chat — slash commands
+### Inside the chat
 
-A command strip runs under the input box so you don't have to memorize
-anything. Type `/help` for the full list. The biggest shortcut:
+A status bar at the top shows cache hit %, cost, Claude-equivalent, and
+the **context gauge** (`ctx 42k/131k (32%)` — yellow at 50%, red + a
+`/compact` nudge at 80%). A command strip under the input lists the
+slash commands:
 
 ```
-/preset fast     deepseek-chat, no harvest, no branch        (default)
-/preset smart    reasoner + harvest                           (~10x cost)
-/preset max      reasoner + harvest + branch 3                (~30x cost, slowest)
+/help                   full list + hints
+/preset <fast|smart|max> one-tap bundles (model + harvest + branch)
+/mcp                    list attached MCP servers and tools
+/compact [cap]          shrink oversized tool results in history
+/sessions · /forget     list / delete saved sessions
+/setup                  reconfigure (exits and tells you to run `reasonix setup`)
+/clear · /exit
 ```
 
-One-tap switch between fast daily driver, careful thinker, and max-quality
-self-consistency. Individual knobs are available too:
+**Esc while thinking** — abort the current exploration and force the
+model to summarize what it already found. No more "model ran 24 tool
+calls and gave up" — you get an answer every time.
+
+Sessions live as JSONL under `~/.reasonix/sessions/<name>.jsonl` —
+every message appended atomically, so killing the CLI never loses
+context. Oversized tool results auto-heal on load, so poisoning a
+session with one giant `read_file` doesn't brick your history.
+
+### Code mode — `npx reasonix code`
+
+A thin opinionated layer on top of chat: filesystem MCP bridged at
+`cwd`, coding system prompt, reasoner preset, per-directory session.
+The model proposes edits as **SEARCH/REPLACE blocks**:
 
 ```
-/status          show current model / harvest / branch / stream
-/model <id>      deepseek-chat or deepseek-reasoner
-/harvest [on|off] Pillar 2 — parse R1 reasoning into typed plan state
-/branch <N|off>  run N parallel samples per turn, pick most confident
-/clear           clear displayed history (log is kept)
-/exit            quit
+src/foo.ts
+<<<<<<< SEARCH
+const x = 1;
+=======
+const x = 2;
+>>>>>>> REPLACE
 ```
 
-The top panel shows active flags live: `· harvest · branch3` appear next to
-the model once enabled.
+Reasonix parses them out of each turn, applies them to disk, reports
+`✓ applied src/foo.ts` in the TUI. SEARCH must match byte-for-byte;
+we never fuzzy-match (silent wrong edits are worse than loud
+rejections). Run `git diff` to review, `git checkout .` to undo.
 
-### Flags (for automation / CI)
+```bash
+cd my-project
+npx reasonix code           # default: cwd, reasoner, per-dir session
+npx reasonix code src/      # scope the filesystem sandbox tighter
+npx reasonix code --no-session   # ephemeral
+```
+
+First-run sandbox: because code mode uses the filesystem MCP from
+`@modelcontextprotocol/server-filesystem`, the model can only read
+and write inside the directory you pointed at. It literally can't
+touch files above that root.
+
+### Advanced — CLI subcommands and flags
 
-The same knobs are also available as CLI flags if you're scripting:
+```bash
+npx reasonix setup                       # reconfigure any time
+npx reasonix chat --session work         # a different named session
+npx reasonix chat --no-session           # ephemeral — nothing persisted
+npx reasonix run "ask anything"          # one-shot, streams to stdout
+npx reasonix stats session.jsonl         # summarize a transcript
+npx reasonix replay chat.jsonl           # scrub a transcript + rebuild cost/cache
+npx reasonix diff a.jsonl b.jsonl --md   # compare two transcripts
+npx reasonix mcp list                    # curated MCP server catalog
+```
+
+Power users can still bypass config and drive Reasonix with flags:
 
 ```bash
-npx reasonix chat -m deepseek-reasoner --harvest --branch 3 --transcript session.jsonl
+npx reasonix chat \
+  --preset max \
+  --mcp "filesystem=npx -y @modelcontextprotocol/server-filesystem /tmp/safe" \
+  --mcp "kb=https://mcp.example.com/sse" \
+  --transcript session.jsonl \
+  --no-config   # ignore ~/.reasonix/config.json (for CI / reproducing issues)
 ```
 
 ### Library
@@ -238,16 +272,19 @@ console.log(loop.stats.summary());
 
 ### Configuration
 
-On first run the CLI prompts for your DeepSeek API key and saves it to
-`~/.reasonix/config.json`. Alternatives:
+The wizard handles everything on first run. If you'd rather use env vars
+(CI, shared boxes, etc.):
 
 ```bash
-export DEEPSEEK_API_KEY=sk-...        # env var (wins over config file)
+export DEEPSEEK_API_KEY=sk-...        # wins over ~/.reasonix/config.json
 export DEEPSEEK_BASE_URL=https://...  # optional alternate endpoint
 ```
 
 Get a key (free credit on signup): <https://platform.deepseek.com/api_keys>
 
+Re-run `npx reasonix setup` any time to add/remove MCP servers or switch
+preset — your existing selections are pre-checked.
+
 ---
 
 ## Non-goals
@@ -269,7 +306,7 @@ cd reasonix
 npm install
 npm run dev chat        # run CLI from source via tsx
 npm run build           # tsup to dist/
-npm test                # vitest (89 tests)
+npm test                # vitest (279 tests)
 npm run lint            # biome
 npm run typecheck       # tsc --noEmit
 ```

package/dist/cli/chunk-2P2MZLCE.js

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+
+// src/code/prompt.ts
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+var CODE_SYSTEM_PROMPT = `You are Reasonix Code, a coding assistant. You have filesystem tools (read_file, write_file, list_directory, search_files, etc.) rooted at the user's working directory.
+
+# When to edit vs. when to explore
+
+Only propose edits when the user explicitly asks you to change, fix, add, remove, refactor, or write something. Do NOT propose edits when the user asks you to:
+- analyze, read, explore, describe, or summarize a project
+- explain how something works
+- answer a question about the code
+
+In those cases, use tools to gather what you need, then reply in prose. No SEARCH/REPLACE blocks, no file changes. If you're unsure what the user wants, ask.
+
+When you do propose edits, the user will review them and decide whether to \`/apply\` or \`/discard\`. Don't assume they'll accept \u2014 write as if each edit will be audited, because it will.
+
+# Editing files
+
+When you've been asked to change a file, output one or more SEARCH/REPLACE blocks in this exact format:
+
+path/to/file.ext
+<<<<<<< SEARCH
+exact existing lines from the file, including whitespace
+=======
+the new lines
+>>>>>>> REPLACE
+
+Rules:
+- Always read_file first so your SEARCH matches byte-for-byte. If it doesn't match, the edit is rejected and you'll have to retry with the exact current content.
+- One edit per block. Multiple blocks in one response are fine.
+- To create a new file, leave SEARCH empty:
+    path/to/new.ts
+    <<<<<<< SEARCH
+    =======
+    (whole file content here)
+    >>>>>>> REPLACE
+- Do NOT use write_file to change existing files \u2014 the user reviews your edits as SEARCH/REPLACE. write_file is only for files you explicitly want to overwrite wholesale (rare).
+- Paths are relative to the working directory. Don't use absolute paths.
+
+# Exploration
+
+- Avoid listing or reading inside these common dependency / build directories unless the user explicitly asks about them: node_modules, dist, build, out, .next, .nuxt, .svelte-kit, .git, .venv, venv, __pycache__, target, coverage, .turbo, .cache. They're expensive and usually irrelevant.
+- Prefer search_files / grep over list_directory when you know roughly what you're looking for \u2014 it saves context and avoids enumerating huge trees.
+
+# Style
+
+- Show edits; don't narrate them in prose. "Here's the fix:" is enough.
+- One short paragraph explaining *why*, then the blocks.
+- If you need to explore first (list / grep / read), do it with tool calls before writing any prose \u2014 silence while exploring is fine.
+`;
+function codeSystemPrompt(rootDir) {
+  const gitignorePath = join(rootDir, ".gitignore");
+  if (!existsSync(gitignorePath)) return CODE_SYSTEM_PROMPT;
+  let content;
+  try {
+    content = readFileSync(gitignorePath, "utf8");
+  } catch {
+    return CODE_SYSTEM_PROMPT;
+  }
+  const MAX = 2e3;
+  const truncated = content.length > MAX ? `${content.slice(0, MAX)}
+\u2026 (truncated ${content.length - MAX} chars)` : content;
+  return `${CODE_SYSTEM_PROMPT}
+
+# Project .gitignore
+
+The user's repo ships this .gitignore \u2014 treat every pattern as "don't traverse or edit inside these paths unless explicitly asked":
+
+\`\`\`
+${truncated}
+\`\`\`
+`;
+}
+
+export {
+  CODE_SYSTEM_PROMPT,
+  codeSystemPrompt
+};
+//# sourceMappingURL=chunk-2P2MZLCE.js.map

package/dist/cli/chunk-2P2MZLCE.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/code/prompt.ts"],"sourcesContent":["/**\n * System prompt used by `reasonix code`. Teaches the model:\n *\n *   1. It has a filesystem MCP bridge rooted at the user's CWD.\n *   2. To modify files it emits SEARCH/REPLACE blocks (not\n *      `write_file` — that would whole-file rewrite and kill diff\n *      reviewability).\n *   3. Read first, edit second — SEARCH must match byte-for-byte.\n *   4. Be concise. The user can read a diff faster than prose.\n *\n * Kept short on purpose. Long system prompts eat context budget that\n * the Cache-First Loop is trying to conserve. The SEARCH/REPLACE spec\n * is the one unavoidable bloat; we trim everything else.\n */\n\nimport { existsSync, readFileSync } from \"node:fs\";\nimport { join } from \"node:path\";\n\nexport const CODE_SYSTEM_PROMPT = `You are Reasonix Code, a coding assistant. You have filesystem tools (read_file, write_file, list_directory, search_files, etc.) rooted at the user's working directory.\n\n# When to edit vs. when to explore\n\nOnly propose edits when the user explicitly asks you to change, fix, add, remove, refactor, or write something. Do NOT propose edits when the user asks you to:\n- analyze, read, explore, describe, or summarize a project\n- explain how something works\n- answer a question about the code\n\nIn those cases, use tools to gather what you need, then reply in prose. No SEARCH/REPLACE blocks, no file changes. If you're unsure what the user wants, ask.\n\nWhen you do propose edits, the user will review them and decide whether to \\`/apply\\` or \\`/discard\\`. Don't assume they'll accept — write as if each edit will be audited, because it will.\n\n# Editing files\n\nWhen you've been asked to change a file, output one or more SEARCH/REPLACE blocks in this exact format:\n\npath/to/file.ext\n<<<<<<< SEARCH\nexact existing lines from the file, including whitespace\n=======\nthe new lines\n>>>>>>> REPLACE\n\nRules:\n- Always read_file first so your SEARCH matches byte-for-byte. If it doesn't match, the edit is rejected and you'll have to retry with the exact current content.\n- One edit per block. Multiple blocks in one response are fine.\n- To create a new file, leave SEARCH empty:\n    path/to/new.ts\n    <<<<<<< SEARCH\n    =======\n    (whole file content here)\n    >>>>>>> REPLACE\n- Do NOT use write_file to change existing files — the user reviews your edits as SEARCH/REPLACE. write_file is only for files you explicitly want to overwrite wholesale (rare).\n- Paths are relative to the working directory. Don't use absolute paths.\n\n# Exploration\n\n- Avoid listing or reading inside these common dependency / build directories unless the user explicitly asks about them: node_modules, dist, build, out, .next, .nuxt, .svelte-kit, .git, .venv, venv, __pycache__, target, coverage, .turbo, .cache. They're expensive and usually irrelevant.\n- Prefer search_files / grep over list_directory when you know roughly what you're looking for — it saves context and avoids enumerating huge trees.\n\n# Style\n\n- Show edits; don't narrate them in prose. \"Here's the fix:\" is enough.\n- One short paragraph explaining *why*, then the blocks.\n- If you need to explore first (list / grep / read), do it with tool calls before writing any prose — silence while exploring is fine.\n`;\n\n/**\n * Inject the project's `.gitignore` content into the system prompt as a\n * \"respect this on top of the built-in denylist\" hint. We don't parse\n * the file — we hand it to the model as-is. Truncate long ones so we\n * don't eat context budget on huge generated ignore lists.\n *\n * Missing or unreadable .gitignore → returns the base prompt unchanged.\n */\nexport function codeSystemPrompt(rootDir: string): string {\n  const gitignorePath = join(rootDir, \".gitignore\");\n  if (!existsSync(gitignorePath)) return CODE_SYSTEM_PROMPT;\n  let content: string;\n  try {\n    content = readFileSync(gitignorePath, \"utf8\");\n  } catch {\n    return CODE_SYSTEM_PROMPT;\n  }\n  const MAX = 2000;\n  const truncated =\n    content.length > MAX\n      ? `${content.slice(0, MAX)}\\n… (truncated ${content.length - MAX} chars)`\n      : content;\n  return `${CODE_SYSTEM_PROMPT}\n\n# Project .gitignore\n\nThe user's repo ships this .gitignore — treat every pattern as \"don't traverse or edit inside these paths unless explicitly asked\":\n\n\\`\\`\\`\n${truncated}\n\\`\\`\\`\n`;\n}\n"],"mappings":";;;AAeA,SAAS,YAAY,oBAAoB;AACzC,SAAS,YAAY;AAEd,IAAM,qBAAqB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAwD3B,SAAS,iBAAiB,SAAyB;AACxD,QAAM,gBAAgB,KAAK,SAAS,YAAY;AAChD,MAAI,CAAC,WAAW,aAAa,EAAG,QAAO;AACvC,MAAI;AACJ,MAAI;AACF,cAAU,aAAa,eAAe,MAAM;AAAA,EAC9C,QAAQ;AACN,WAAO;AAAA,EACT;AACA,QAAM,MAAM;AACZ,QAAM,YACJ,QAAQ,SAAS,MACb,GAAG,QAAQ,MAAM,GAAG,GAAG,CAAC;AAAA,oBAAkB,QAAQ,SAAS,GAAG,YAC9D;AACN,SAAO,GAAG,kBAAkB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAO5B,SAAS;AAAA;AAAA;AAGX;","names":[]}