@kodax-ai/kodax 0.7.40 → 0.7.42

package/README.md

@@ -1,36 +1,133 @@
-# KodaX
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="assets/logo-dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset="assets/logo-light.svg">
+    <img src="assets/logo-light.svg" alt="KodaX" width="640">
+  </picture>
+</p>
+
+<p align="center">
+  <b>Open-source AI coding agent on every LLM you can reach.</b><br>
+  Anthropic · OpenAI · DeepSeek · Kimi · Zhipu · MiniMax · MiMo · Ark · Qwen · Gemini · Codex.<br>
+  REPL · CLI · library · Node-free single binary.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@kodax-ai/kodax"><img alt="npm version" src="https://img.shields.io/npm/v/@kodax-ai/kodax?style=flat-square&color=cb3837"></a>
+  <a href="LICENSE"><img alt="license" src="https://img.shields.io/badge/license-Apache--2.0-blue?style=flat-square"></a>
+  <a href="https://github.com/icetomoyo/KodaX/stargazers"><img alt="GitHub stars" src="https://img.shields.io/github/stars/icetomoyo/KodaX?style=flat-square&logo=github&color=f1c40f"></a>
+  <a href="https://github.com/icetomoyo/KodaX/actions"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/icetomoyo/KodaX/release.yml?style=flat-square&label=release"></a>
+  <img alt="providers" src="https://img.shields.io/badge/LLMs-13_native_+_OpenAI%2FAnthropic--compat-2ecc71?style=flat-square">
+</p>
+
+<p align="center">
+  <a href="#install-in-30-seconds">Install</a> ·
+  <a href="#four-ways-to-use-kodax">Usage</a> ·
+  <a href="#sdk-usage">SDK</a> ·
+  <a href="CHANGELOG.md">Changelog</a> ·
+  <a href="docs/FEATURE_LIST.md">Roadmap</a> ·
+  <a href="https://github.com/icetomoyo/KodaX/discussions">Discussions</a> ·
+  <a href="README_CN.md">中文 README</a>
+</p>
+
+<p align="center">
+  <img src="kodax.gif" alt="KodaX in action" width="880">
+</p>
 
-Extreme Lightweight Coding Agent - TypeScript Implementation
+---
 
-## Overview
+## Install in 30 seconds
 
-KodaX is a **modular, lightweight AI coding agent** built with TypeScript. It supports **12 LLM providers**, works as both a CLI tool and a library, ships an optional **Node-free standalone binary**, and includes a Scout-first adaptive multi-agent workflow for long-running coding tasks.
+```bash
+npm i -g @kodax-ai/kodax
 
-**Core Philosophy**: Transparent, Flexible, Minimalist
+# Pick any one you have an API key for:
+export ZHIPU_API_KEY=...        # or ANTHROPIC_API_KEY / OPENAI_API_KEY / KIMI_API_KEY /
+                                # MINIMAX_API_KEY / MIMO_API_KEY / ARK_API_KEY / QWEN_API_KEY /
+                                # DEEPSEEK_API_KEY / GEMINI_API_KEY
 
-**Why KodaX?**
+kodax
+```
 
-| Question | KodaX answer |
-|---------|--------------|
-| Why not only use Claude Code? | KodaX is easier to inspect, modify, self-host, and switch across providers. |
-| Why not only use an SDK? | KodaX already gives you a CLI, sessions, tools, permissions, and skills out of the box. |
-| Why use it as a codebase? | The architecture is small enough to understand and customize without wading through thousands of files. |
-| Why use it in production tools? | The packages are separated cleanly, so you can reuse only the layer you need. |
+That's it. You're in the REPL — ask anything in natural language.
 
-**KodaX vs hosted coding assistants**
+> **No-Node target machines:** download a Bun-compiled single binary for Windows / macOS / Linux × x64 + arm64 from the [GitHub Releases](https://github.com/icetomoyo/KodaX/releases) page. See [docs/release.md](docs/release.md) for the build pipeline.
 
-| Feature | KodaX | Typical hosted coding assistant |
-|---------|-------|----------------------------------|
-| **Architecture** | Modular (5 packages), library-friendly | Usually product-first, less reusable as code |
-| **Provider choice** | 12 providers (incl. Anthropic, OpenAI, DeepSeek, Kimi, Qwen, Zhipu, MiniMax, MiMo, Gemini CLI, Codex CLI) + custom OpenAI/Anthropic-compatible providers | Often optimized for one provider |
-| **Customization** | Edit prompts, tools, skills, session flow directly | Limited extension surface |
-| **Codebase clarity** | Small TypeScript monorepo | Often much larger and harder to trace |
-| **Distribution** | npm install / global link / **standalone binary** (Bun --compile, no Node required on target) | Closed-source installer or web app |
-| **Learning value** | Good for understanding agent internals | More black-box |
+---
+
+## Four ways to use KodaX
 
-## Quick Start
+| Form | Command / Import | When to use it |
+|---|---|---|
+| **REPL** | `kodax` | Interactive multi-turn coding session with streaming UI, permissions, slash commands |
+| **CLI** | `kodax -p "your task"` | One-shot scripted task, CI runs, batch processing |
+| **Library** | `import { runKodaX } from '@kodax-ai/kodax'` | Embed in your own tool / agent / web service |
+| **Single binary** | `./kodax` | Distribute to machines that don't have Node installed |
 
-### 1. Install and build the CLI
+---
+
+## Why KodaX
+
+<table>
+  <tr>
+    <td width="33%" align="center" valign="top">
+      <h3>🇨🇳 6 China-native LLMs</h3>
+      <sub>Zhipu · Kimi · MiniMax · MiMo · Ark · Qwen</sub>
+      <br><br>
+      First-class adapters with cross-provider <a href="benchmark/EVAL_GUIDELINES.md">prompt-eval calibration</a> on a canonical 5-alias panel — not OpenAI-compat shims.
+    </td>
+    <td width="33%" align="center" valign="top">
+      <h3>📦 Single-file binary</h3>
+      <sub>Bun --compile · Win / macOS / Linux · x64 + arm64</sub>
+      <br><br>
+      No Node required on the target machine. Drop one file, run anywhere — restricted envs, CI runners, air-gapped boxes.
+    </td>
+    <td width="33%" align="center" valign="top">
+      <h3>🌳 Branchable session lineage</h3>
+      <sub>Fork · rewind · parallel edit</sub>
+      <br><br>
+      Conversation history is a DAG, not a list. Powers the upcoming <b>KodaX Space</b> desktop app.
+    </td>
+  </tr>
+  <tr>
+    <td align="center" valign="top">
+      <h3>🤖 Multi-agent by default</h3>
+      <sub>V2 Worker + Evaluator + async children</sub>
+      <br><br>
+      <code>dispatch_child_task</code>, <code>send_message</code>, <code>task_stop</code>, multi-instance auto-coordination with content-hash safety net.
+    </td>
+    <td align="center" valign="top">
+      <h3>🧩 Skills + self-construction</h3>
+      <sub>Markdown skills, NL triggers</sub>
+      <br><br>
+      5-stage self-modification staircase (scaffold → validate → stage → test → activate) gated by an 8-invariant admission contract.
+    </td>
+    <td align="center" valign="top">
+      <h3>🛠 30+ built-in tools</h3>
+      <sub>File · shell · search · MCP · ACP</sub>
+      <br><br>
+      Repo intelligence, semantic search, git worktree, web fetch — all addressable through one clean tool surface.
+    </td>
+  </tr>
+</table>
+
+## How KodaX compares
+
+| Feature | **KodaX** | Claude Code | Aider | Codex CLI | Cursor | Cline |
+|---|---|---|---|---|---|---|
+| Open source | ✅ Apache&nbsp;2.0 | ❌ Source-available | ✅ Apache&nbsp;2.0 | ✅ Apache&nbsp;2.0 | ❌ Proprietary | ✅ Apache&nbsp;2.0 |
+| Node-free single binary | ✅ Bun | ❌ Node | ❌ Python | ✅ Rust | ❌ Electron | ❌ Extension |
+| Native China providers<br><sub>(Zhipu · Kimi · MiniMax · MiMo · Ark · Qwen)</sub> | ✅ 6 native | ❌ | ⚠ via LiteLLM | ❌ OpenAI-first | ❌ no provider menu | ⚠ Kimi / Qwen / DeepSeek |
+| Branchable session lineage | ✅ fork & rewind | ⚠ routines / sessions | ❌ | ❌ | ❌ | ⚠ checkpoints |
+| Multi-agent + MCP + 30+ tools | ✅ all three | ✅ all three | ⚠ tools, no MCP | ✅ all three | ⚠ Composer + MCP | ✅ all three |
+
+<sub>Data verified May 2026 against public docs ([Claude Code](https://github.com/anthropics/claude-code) · [Aider](https://aider.chat/docs/llms.html) · [Codex CLI](https://github.com/openai/codex) · [Cursor](https://cursor.com) · [Cline](https://github.com/cline/cline)). ⚠ = partial / requires extra setup / not first-class. Corrections welcome via PR.</sub>
+
+## Detailed Setup
+
+> The `npm i -g @kodax-ai/kodax` one-liner above is the fastest path. This section is for building from source, configuring custom providers, or using KodaX as a library.
+
+### 1. Build the CLI from source
 
 ```bash
 git clone https://github.com/icetomoyo/KodaX.git
@@ -156,220 +253,18 @@ const result = await runKodaX(
 );
 ```
 
-## Core Workflows
-
-- **CLI coding assistant**: run one-off tasks or stay in a session for multi-step work.
-- **Skills-driven workflows**: trigger built-in or custom skills from natural language.
-- **Project Mode / harness engineering**: bootstrap a long-running project, keep project truth on disk, and execute through verifier-gated `/project` flows.
-- **Embeddable library**: reuse the provider layer, session layer, or full coding agent in your own app.
-
-## Repo Intelligence Premium
-
-KodaX now supports a split repo-intelligence architecture:
-
-- **Public OSS baseline** lives in the public `KodaX` repo and keeps `CLI`, `REPL`, `ACP`, library imports, and repo-aware tools working even when no premium component is installed.
-- **Premium intelligence** lives in the sibling private repo `KodaX-private` and runs through the local `repointel` daemon / CLI frontdoor.
-- **KodaX native mode** is the flagship experience. It can prefetch repo intelligence before routing and prompt building, while other hosts such as Codex / Claude Code / OpenCode use the same premium tool through thin skills.
-
-### Runtime modes
+## Repo Intelligence (optional premium engine)
 
-KodaX supports these repo-intelligence modes:
+KodaX ships with built-in OSS repo intelligence (`repo_overview`, `module_context`, `symbol_context`, `process_context`, `impact_estimate`, …) that helps the coding agent understand large codebases without ad-hoc grep/glob exploration.
 
-- `off`: strict benchmark baseline. Disable the repo-intelligence working plane entirely while keeping `/repointel` control commands available.
-- `oss`: use only the public OSS baseline.
-- `premium-shared`: use the premium engine, but without the native KodaX auto lane. This is useful for comparing KodaX against other hosts.
-- `premium-native`: use the premium engine through the KodaX native bridge. This is the best local experience.
-- `auto`: user-facing convenience mode. KodaX resolves it to `premium-native` when the premium daemon is reachable, otherwise it falls back to `oss`.
-
-### Quick usage
-
-Run KodaX with explicit repo-intelligence mode flags:
+An optional **premium engine** (`repointel` local daemon, distributed via the sibling `KodaX-private` repo) adds proactive context injection, deeper module capsules, and a native auto-lane integration. KodaX automatically falls back to OSS when premium is unavailable.
 
 ```bash
-# OSS baseline only
-kodax --repo-intelligence oss
-
-# Premium native mode with trace output
+# Pick a runtime mode (off | oss | premium-shared | premium-native | auto)
 kodax --repo-intelligence premium-native --repo-intelligence-trace
-
-# Compare against the shared premium path
-kodax --repo-intelligence premium-shared --repo-intelligence-trace
-```
-
-You can also set the same behavior through config or environment variables:
-
-```powershell
-$env:KODAX_REPO_INTELLIGENCE_MODE = "premium-native"
-$env:KODAX_REPO_INTELLIGENCE_TRACE = "1"
-$env:KODAX_REPOINTEL_BIN = "C:\Tools\repointel\repointel.exe"
-```
-
-Official `KodaX-private` releases should now publish only the native `repointel` package. The older offline bundle remains useful for internal/manual validation, but it should not be the normal end-user release artifact.
-
-### REPL mode
-
-It is not CLI-only. REPL mode supports the same repo-intelligence runtime modes.
-
-The most direct premium-native REPL flow is:
-
-```powershell
-Set-Location <path-to-your-KodaX-clone>
-kodax --repo-intelligence premium-native --repo-intelligence-trace
-```
-
-If you save the premium settings in `~/.kodax/config.json`, plain REPL startup is enough:
-
-```powershell
-kodax
-```
-
-Inside REPL, repo intelligence is still consumed automatically by the normal KodaX flow, and there are also lightweight status/control commands:
-
-- `/status`: shows a compact repo-intelligence summary together with the normal session status output.
-- `/repointel` or `/repointel status`: shows the current repo-intelligence state in more detail.
-- `/repointel mode premium-native|premium-shared|oss|off|auto`: switches the current mode and writes it back to user config.
-- `/repointel trace on|off|toggle`: turns repo-intelligence trace output on or off.
-- `/repointel warm`: tries to warm or start the local premium service. If it cannot be started, KodaX reports the failure clearly and continues with the normal fallback path.
-
-The most important fields to watch are:
-
-- `mode`: the resolved runtime mode, such as `oss`, `premium-shared`, or `premium-native`
-- `engine`: the actual engine in use, `oss` or `premium`
-- `bridge`: `none`, `shared`, or `native`
-- `status`: typically `ok`, `limited`, or `unavailable`
-
-The practical difference between the two premium modes is:
-
-- `premium-native`: the flagship KodaX path. KodaX can prefetch and inject repo intelligence earlier in its native runtime flow.
-- `premium-shared`: still uses premium, but intentionally avoids the KodaX-native auto lane so you can compare against the shared multi-host path.
-- `oss`: keep the public baseline repo tools and OSS intelligence only.
-- `off`: strict disable for repo-intelligence working tools and auto injection. `/repointel` remains available as the control plane.
-
-### User-level config
-
-Repo-intelligence premium settings are supported in the user config file `~/.kodax/config.json`.
-
-Supported fields:
-
-- `repoIntelligenceMode`
-- `repointelEndpoint`
-- `repointelBin`
-- `repoIntelligenceTrace`
-
-Recommended end-user example when `repointel` is installed but not on `PATH`:
-
-```json
-{
-  "provider": "zhipu-coding",
-  "reasoningMode": "auto",
-  "repoIntelligenceMode": "premium-native",
-  "repointelBin": "C:\\Tools\\repointel\\repointel.exe",
-  "repoIntelligenceTrace": false
-}
-```
-
-For normal user installs, the preferred setup is to install the premium tool so the `repointel` command is already on `PATH`, in which case this is usually enough:
-
-```json
-{
-  "repoIntelligenceMode": "premium-native"
-}
 ```
 
-If `repointel` is not on `PATH`, `repointelBin` can point to the installed native executable, for example:
-
-```json
-{
-  "repoIntelligenceMode": "premium-native",
-  "repointelBin": "C:\\Tools\\repointel\\repointel.exe"
-}
-```
-
-For author same-parent local development, it is still valid to point `repointelBin` at the sibling private source build:
-
-```json
-{
-  "repoIntelligenceMode": "premium-native",
-  "repointelEndpoint": "http://127.0.0.1:47891",
-  "repointelBin": "C:\\path\\to\\KodaX-private\\packages\\repointel-cli\\dist\\index.js",
-  "repoIntelligenceTrace": true
-}
-```
-
-`repointelEndpoint` is optional in normal installs. It only tells KodaX which local premium daemon address to use, and the default `http://127.0.0.1:47891` is usually enough unless you deliberately run a non-default endpoint.
-
-For same-parent author local development, `repointelBin` can still point to the sibling private build output.
-
-These config values are loaded by both CLI mode and REPL mode, and they are bridged into the runtime environment automatically.
-
-### Config template
-
-The repo now includes a user-facing config template:
-
-- `config.example.jsonc`
-
-Copy it to `~/.kodax/config.json`, then adjust provider and repo-intelligence settings as needed.
-
-### Local same-parent development
-
-The intended phase-1 development layout is to clone both repos under the same parent directory, for example:
-
-- Public repo: `<parent>/KodaX`
-- Private repo: `<parent>/KodaX-private`
-
-Typical local workflow:
-
-```powershell
-# 1. Build the public repo
-Set-Location <parent>\KodaX
-npm install
-npm run build
-
-# 2. Build the private premium repo
-Set-Location <parent>\KodaX-private
-npm install
-npm run build
-
-# 3. Warm or start the premium daemon
-node .\packages\repointel-cli\dist\index.js warm "{}"
-
-# 4. Run KodaX in premium-native mode
-Set-Location <parent>\KodaX
-npm run dev -- --repo-intelligence premium-native --repo-intelligence-trace
-```
-
-### How KodaX behaves after the split
-
-- If premium is unavailable, KodaX automatically falls back to the OSS baseline. Startup, imports, and public tools keep working.
-- If premium is available, `premium-native` uses the daemon client directly and injects repo intelligence earlier than shared-host integrations.
-- Trace-enabled runs can be used to compare `off`, `oss`, `premium-shared`, and `premium-native` on the same task, including mode, engine, bridge, daemon latency, cache hits, and capsule token estimates.
-
-### External hosts
-
-Codex, Claude Code, and OpenCode are intentionally thinner in phase 1:
-
-- they install the shared Repointel skill
-- they call the same local premium tool
-- they do **not** ship a separate OSS fallback engine
-
-Install the shared thin skill from the public repo:
-
-```powershell
-# Cross-platform primary entrypoint
-node .\clients\repointel\scripts\install.mjs --host codex
-node .\clients\repointel\scripts\install.mjs --host claude --workspace-root C:\path\to\workspace
-node .\clients\repointel\scripts\install.mjs --host opencode --workspace-root C:\path\to\workspace
-```
-
-Useful helper scripts:
-
-- `clients/repointel/scripts/demo.mjs`: run a local premium demo flow against a temporary endpoint.
-- `clients/repointel/scripts/doctor.mjs`: inspect local premium setup, bridge status, daemon reachability, and host skill installation.
-- `clients/repointel/scripts/install.mjs`: install the shared thin skill into Codex / Claude / OpenCode host paths.
-
-The installable shared skill itself lives at:
-
-- `clients/repointel/SKILL.md`
+Setup, runtime modes, REPL controls, config schema, and external-host integrations: see [docs/REPOINTEL.md](docs/REPOINTEL.md).
 
 ## Architecture
 
@@ -711,7 +606,7 @@ KodaX recognizes a number of environment variables for tuning runtime behavior.
 
 #### `KODAX_MAX_OUTPUT_TOKENS`
 
-Overrides the per-turn `max_tokens` value sent to **every** provider (Anthropic, OpenAI, Zhipu, Kimi, MiniMax, Qwen, DeepSeek, MiMo, Gemini, Codex, …). Set to a positive integer; unset or non-numeric values are ignored. This is an **explicit user intent**: when set, it wins over the provider's model descriptor cap, over the provider config default, and over the global `KODAX_MAX_TOKENS` fallback. The runtime's automatic safety caps (e.g. the v0.7.28 P2b RST-prone write-turn cap that limits write/edit turns to 8K tokens on Zhipu/Kimi/MiniMax) are **bypassed** when this variable is set, so the user override is also a way to opt out of those caps.
+Overrides the per-turn `max_tokens` value sent to **every** provider (Anthropic, OpenAI, Zhipu, Kimi, MiniMax, Qwen, DeepSeek, MiMo, Gemini, Codex, …). Set to a positive integer; unset or non-numeric values are ignored. This is an **explicit user intent**: when set, it wins over the provider's model descriptor cap, over the provider config default, and over the global `KODAX_MAX_TOKENS` fallback. RST defense is handled at the provider config layer (`streamMaxDurationMs` watchdog + non-streaming fallback in `packages/llm/src/providers/registry.ts`), so this variable is purely an output-budget knob.
 
 ```bash
 # Allow up to 48K output tokens per turn (use a higher cap when generating long files)
@@ -730,7 +625,9 @@ Precedence used by every provider's `getEffectiveMaxOutputTokens()` (see `packag
 4. Provider config default
 5. Global `KODAX_MAX_TOKENS` fallback
 
-Related variables: `KODAX_MAX_TOKENS` (global fallback when no provider/model cap applies), `KODAX_RST_PRONE_PROVIDERS` and `KODAX_WRITE_TURN_MAX_TOKENS` (v0.7.28 P2b write-turn safety cap configuration), `KODAX_ESCALATED_MAX_OUTPUT_TOKENS` (escalation budget used by the agent loop when a turn returns `stop_reason: max_tokens`).
+Related variables: `KODAX_MAX_TOKENS` (global fallback when no provider/model cap applies), `KODAX_ESCALATED_MAX_OUTPUT_TOKENS` (escalation budget used by the agent loop when a turn returns `stop_reason: max_tokens`).
+
+> **Retired in v0.7.42**: `KODAX_RST_PRONE_PROVIDERS` and `KODAX_WRITE_TURN_MAX_TOKENS` (the v0.7.28 P2b write-turn cap mechanism) are no longer recognized. The 2026-04 bench measured RST as time-based (zhipu-coding 308s server kill window), not payload-size-based, so the cap was retired in favor of the per-provider `streamMaxDurationMs` watchdog + non-streaming fallback chain (configured in `registry.ts`). Existing env exports become silent no-ops; remove them from shell profiles when convenient.
 
 ## Advanced Library Usage