@kodax-ai/kodax 0.7.41 → 0.7.43

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.
+
+> **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.
+
+---
 
-**KodaX vs hosted coding assistants**
+## Four ways to use KodaX
 
-| 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 |
+| 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 |
 
-## Quick Start
+---
 
-### 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 single-loop + Sidecar Verifier + 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,251 +253,53 @@ 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
-
-KodaX supports these repo-intelligence modes:
+> **Embedding KodaX inside another app?** (KodaX Space, IDE extensions, custom CLIs)
+> See [docs/SDK_EMBEDDER_GUIDE.md](docs/SDK_EMBEDDER_GUIDE.md) for the runtime-mutation
+> surface (`startKodaX` + `RunningSession`), MCP popout manager API (`McpManager`),
+> Skill `` !`cmd` `` host hook, and per-app data dir namespacing (`getAppDataDir`).
 
-- `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`.
+## Repo Intelligence (optional premium engine)
 
-### Quick usage
+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.
 
-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
 
-KodaX uses a **monorepo architecture** with npm workspaces. Source layout has 9 workspace packages; published as a single bundled npm package `@kodax-ai/kodax` with 5 SDK subpath exports (ADR-022 + ADR-024, v0.7.39):
+KodaX uses a **monorepo architecture** with npm workspaces. Source layout has 9 workspace packages; published as a single bundled npm package `@kodax-ai/kodax` with 6 SDK subpath exports (`/agent`, `/llm`, `/coding`, `/repl`, `/skills`, `/mcp`; ADR-022 + ADR-024 v0.7.39 + ADR-032 v0.7.42 added `/mcp`):
 
 ```
 KodaX/
-├── packages/
-│   ├── ai/                  # @kodax-ai/llm - LLM abstraction (12 providers)
+├── packages/                # 4 workspace packages (FEATURE_194 v0.7.43)
+│   ├── llm/                 # @kodax-ai/llm - LLM abstraction (12 providers)
 │   │   └── providers/       # Anthropic, OpenAI, DeepSeek, Kimi, MiMo, MiniMax, Zhipu, Ark, …
 │   │
 │   ├── agent/               # @kodax-ai/agent - Generic Agent framework
-│   │   └── orchestration/   # Runner, runFanOut, runWithIdleYield, ChildTaskRegistry
-│   │
-│   ├── skills/              # @kodax-ai/skills - Skills standard implementation
-│   │   └── builtin/         # Built-in skills (code-review, tdd, git-workflow)
+│   │   ├── orchestration/   # Runner, runFanOut, runWithIdleYield, ChildTaskRegistry
+│   │   ├── session-lineage/ # branchable session tree (inline v0.7.43)
+│   │   ├── capabilities/
+│   │   │   ├── mcp/         # MCP integration (inline v0.7.43)
+│   │   │   └── skills/      # Skills standard implementation + builtin (inline v0.7.43)
+│   │   └── tracing/         # tracing / observability (inline v0.7.43)
 │   │
 │   ├── coding/              # @kodax-ai/coding - Coding Agent (tools + prompts)
-│   │   └── tools/           # 30+ tools: read, write, edit, bash, glob, grep, undo,
-│   │                        #   dispatch_child_task, send_message, task_stop,
-│   │                        #   ask_user_question, repo-intelligence, …
+│   │   ├── tools/           # 30+ tools: read, write, edit, bash, glob, grep, undo,
+│   │   │                    #   dispatch_child_task, send_message, task_stop,
+│   │   │                    #   ask_user_question, repo-intelligence, …
+│   │   └── repo-intelligence/ # incl. protocol.ts (inline v0.7.43)
 │   │
-│   ├── repl/                # @kodax-ai/repl - Interactive terminal UI (Ink TUI)
-│   ├── mcp/                 # @kodax-ai/mcp - MCP integration
-│   ├── repointel-protocol/  # @kodax-ai/repointel-protocol - repo-intel protocol
-│   ├── session-lineage/     # @kodax-ai/session-lineage - branchable session tree
-│   └── tracing/             # @kodax-ai/tracing - tracing / observability
+│   └── repl/                # @kodax-ai/repl - Interactive terminal UI (Ink TUI)
 │
-├── src/                     # CLI entry + 5 SDK subpath entries (sdk-{agent,llm,coding,repl,skills}.ts)
+├── src/                     # CLI entry + SDK subpath entries
 │   ├── kodax_cli.ts         # Main CLI entry point (bin: `kodax`)
-│   └── sdk-*.ts             # SDK subpath re-exports → @kodax-ai/kodax/{agent,llm,coding,repl,skills}
+│   └── sdk-*.ts             # SDK subpath re-exports → @kodax-ai/kodax/{agent,llm,coding,repl}
 │
 └── package.json             # Root workspace config; release.mjs rewrites name + injects subpath exports
 ```
@@ -421,37 +320,57 @@ KodaX/
        │  UI Layer    │              │ Tools+Prompts  │
        └──────┬───────┘              └──────┬─────────┘
               │                             │
-              │              ┌──────────────┼──────────────┐
-              │              │              │              │
-              ▼              ▼              ▼              ▼
-       ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌─────────────┐
-       │@kodax-ai/    │ │@kodax-ai/    │ │@kodax-ai/llm │ │  External   │
-       │skills        │ │agent         │ │LLM Abstract  │ │   SDKs      │
-       │(zero deps)   │ │Runner +      │ │(12 providers)│ │             │
-       │              │ │fan-out +     │ │              │ │             │
-       │              │ │idle-yield    │ │              │ │             │
-       └──────────────┘ └──────────────┘ └──────────────┘ └─────────────┘
+              │              ┌──────────────┴──────────────┐
+              │              │                             │
+              ▼              ▼                             ▼
+       ┌──────────────┐ ┌──────────────────────────┐ ┌──────────────┐
+       │@kodax-ai/    │ │@kodax-ai/agent           │ │@kodax-ai/llm │
+       │coding (via   │ │Runner + fan-out +        │ │LLM Abstract  │
+       │above)        │ │idle-yield + session-     │ │(12 providers)│
+       │              │ │lineage + skills + mcp +  │ │              │
+       │              │ │tracing (FEATURE_194)     │ │              │
+       └──────────────┘ └──────────────────────────┘ └──────────────┘
 ```
 
 ### Package Overview
 
-Source-side workspace package names (`@kodax-ai/*`). npm consumers install the single bundled `@kodax-ai/kodax` package and import from SDK subpaths — see [SDK Usage](#sdk-usage) below.
+Source-side workspace package names (`@kodax-ai/*`). npm consumers install the single bundled `@kodax-ai/kodax` package and import from SDK subpaths — see [Source-side vs npm-published surface](#source-side-vs-npm-published-surface) and [SDK Usage](#sdk-usage) below.
 
 | Workspace package | Purpose | Key Dependencies |
 |---------|---------|------------------|
 | `@kodax-ai/llm` | LLM abstraction (12 providers + custom registration) | @anthropic-ai/sdk, openai |
-| `@kodax-ai/agent` | Generic Agent framework — Runner, fan-out, idle-yield, session, tokenization (ADR-021 standalone-consumable) | @kodax-ai/llm, js-tiktoken |
-| `@kodax-ai/skills` | Skills standard implementation | Zero external deps |
-| `@kodax-ai/coding` | Coding Agent — 30+ tools (incl. `dispatch_child_task` / `send_message` / `task_stop`) + role prompts + auto-continue | @kodax-ai/llm, @kodax-ai/agent, @kodax-ai/skills |
+| `@kodax-ai/agent` | Generic Agent framework — Runner, fan-out, idle-yield, session-lineage, capabilities (mcp + skills), tracing (ADR-036 v0.7.43 consolidation; subpaths: `/session-lineage`, `/capabilities/mcp`, `/capabilities/skills`, `/tracing`) | @kodax-ai/llm, js-tiktoken, fflate, yaml |
+| `@kodax-ai/coding` | Coding Agent — 30+ tools (incl. `dispatch_child_task` / `send_message` / `task_stop`) + role prompts + auto-continue + repo-intelligence protocol | @kodax-ai/llm, @kodax-ai/agent |
 | `@kodax-ai/repl` | Complete interactive terminal UI (Ink/React, permission modes, commands, streaming) | @kodax-ai/coding, ink, react |
 
+### Source-side vs npm-published surface
+
+KodaX has two layers that consumers should understand separately:
+
+- **Source-side**: 4 workspace packages above (what developers see when reading the repo).
+- **npm-published**: a single bundled package `@kodax-ai/kodax` with 7 SDK subpaths (what SDK consumers `import` from). The subpaths are split into two roles:
+  - **Full-package subpaths** (`/agent`, `/llm`, `/coding`, `/repl`) — each one maps 1:1 to a source workspace and exposes its complete public API.
+  - **Narrow-subset subpaths** (`/skills`, `/mcp`, `/session`) — each one exposes only a focused capability slice carved out of `/agent` or `/repl`. This lets consumers who only need (say) the Skills system import a much smaller surface without pulling in the full agent framework.
+
+| Source package | npm subpath | Type | What you get | Example consumer |
+|---|---|---|---|---|
+| `packages/llm`    | `@kodax-ai/kodax/llm`     | Full package | 12-provider LLM abstraction (77 exports) | Standalone LLM clients |
+| `packages/agent`  | `@kodax-ai/kodax/agent`   | Full package | Runner / fan-out / session-lineage / capabilities / tracing (202 exports) | Custom agent frameworks |
+| `packages/agent`  | `@kodax-ai/kodax/skills`  | **Narrow subset** | Skills system only — `SkillRegistry` / `loadFullSkill` / `expandSkillForLLM` / ... (26 exports = pre-v0.7.43 `@kodax-ai/skills` complete API) | Skill loaders, IDE plugins |
+| `packages/agent`  | `@kodax-ai/kodax/mcp`     | **Narrow subset** | MCP only — `McpCapabilityProvider` / `createMcpTransport` / `searchMcpCatalog` / ... (11 exports = pre-v0.7.43 `@kodax-ai/mcp` complete API) | MCP server hosts |
+| `packages/coding` | `@kodax-ai/kodax/coding`  | Full package | Coding agent + 30+ tools + repo-intelligence (342 exports) | Build a Claude Code-shape product |
+| `packages/repl`   | `@kodax-ai/kodax/repl`    | Full package | Ink TUI + permission modes + commands (193 exports) | Terminal-UI consumers |
+| `packages/repl`   | `@kodax-ai/kodax/session` | **Narrow subset** | Session management only — `listSessions` / `forkSession` / `watchSessions` / ... (9 exports) | IDE plugins reading session history |
+
+**Rule of thumb**: if you need Runner / Agent / fan-out, import from `/agent`. If you only need skills or mcp APIs, import from `/skills` or `/mcp` to get a smaller bundle. The narrow subsets are subsets of the full packages — they do **not** expose extra symbols.
+
 ---
 
 ## Features
 
 - **Modular Architecture** - Use as CLI, as a library, or as a Node-free single binary
 - **12 LLM Providers** - Anthropic, OpenAI, DeepSeek, Kimi, Kimi Code, Qwen, Zhipu, Zhipu Coding, MiniMax Coding, MiMo Coding (Xiaomi Token Plan), Gemini CLI, Codex CLI — plus user-defined OpenAI/Anthropic-compatible providers
-- **Worker + Evaluator AMA (V2, default)** - Adaptive multi-agent with H0/H1/H2 harness levels. Worker single-loop replaces the V1 Scout/Planner/Generator chain (FEATURE_114, v0.7.36); structural Evaluator gate preserved. Async child steering via `dispatch_child_task` + `send_message` + `task_stop` with idle-yield wait (FEATURE_120 / FEATURE_155, v0.7.39).
+- **V2 Worker single-loop + Sidecar Verifier (default)** - Single-agent main loop with an out-of-band Sidecar Verifier as Stop-hook (claudecode-shape; FEATURE_184 v0.7.42, ADR-030). Verifier returns accept/revise/blocked verdict on Worker text-only termination. V1 Scout/Planner/Generator/Evaluator chain fully retired (FEATURE_193 v0.7.43); `emit_handoff` tool deleted (FEATURE_190 v0.7.43); accept-verdict UI silently passes through (FEATURE_195 v0.7.43); content-aware fire gate skips trivial-chat sidecar calls (FEATURE_196 v0.7.43). Async child steering via `dispatch_child_task` + `send_message` + `task_stop` with idle-yield wait (FEATURE_120 / FEATURE_155, v0.7.39); specialist routing via `subagent_type` (FEATURE_191 v0.7.43).
 - **Reasoning Modes** - Unified `off/auto/quick/balanced/deep` interface across providers
 - **Streaming Output** - Real-time response display
 - **Session Management** - JSONL format with branchable session lineage tree
@@ -546,14 +465,17 @@ console.log(result.lastText);
 For smaller surface and tree-shake-friendly imports, the SDK is also exposed via subpath exports — pick only the package(s) you need:
 
 ```typescript
-import { Runner } from '@kodax-ai/kodax/agent';       // agent runtime
-import { createProvider } from '@kodax-ai/kodax/llm'; // LLM abstraction (12 providers)
-import { runKodaX } from '@kodax-ai/kodax/coding';    // coding tools + prompts
-import { SkillRegistry } from '@kodax-ai/kodax/skills'; // zero-dep skill loader
-import { loadConfig } from '@kodax-ai/kodax/repl';    // REPL config / session helpers
+import { Runner } from '@kodax-ai/kodax/agent';                // agent runtime
+import { createProvider } from '@kodax-ai/kodax/llm';           // LLM abstraction (12 providers)
+import { runKodaX } from '@kodax-ai/kodax/coding';              // coding tools + prompts
+import { SkillRegistry } from '@kodax-ai/kodax/skills';         // zero-dep skill loader
+import { loadConfig } from '@kodax-ai/kodax/repl';              // REPL config / session helpers
+import { createMcpManager } from '@kodax-ai/kodax/mcp';         // MCP popout manager (v0.7.42)
 ```
 
-All 6 entries (root + 5 subpaths) share internal code via ESM chunk splitting — importing from `/agent` does not pull in `/repl`'s Ink + React surface.
+All 7 entries (root + 6 subpaths) share internal code via ESM chunk splitting — importing from `/agent` does not pull in `/repl`'s Ink + React surface.
+
+> **ESM-only.** The SDK is published as ES Modules. In a CommonJS context (Electron main process, legacy Webpack CJS bundles, `require()`-based code) you must use `await import(...)` instead of `require()`. See [docs/SDK_EMBEDDER_GUIDE.md §5](docs/SDK_EMBEDDER_GUIDE.md#5-consuming-from-a-commonjs-context-electron-main-cjs-bundles) for the canonical recipe + the technical reason most subpaths cannot ship a dual ESM/CJS build.
 
 For CLI users, provider defaults live in `~/.kodax/config.json`. For library users, API keys are still read from environment variables; if you need custom base URLs or provider aliases, use `registerCustomProviders()` as shown above.
 
@@ -711,7 +633,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 +652,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
 
@@ -816,21 +740,24 @@ await runKodaX({
 
 ## SDK Usage
 
-KodaX ships as a single npm package `@kodax-ai/kodax` with 5 SDK subpath exports (ADR-024, v0.7.39). Each subpath is tree-shake-friendly so consumers pull only what they need:
+KodaX ships as a single npm package `@kodax-ai/kodax` with 6 SDK subpath exports (ADR-024 v0.7.39 + ADR-032 v0.7.42 added `/mcp`). Each subpath is tree-shake-friendly so consumers pull only what they need:
 
 ```bash
 npm install @kodax-ai/kodax
 ```
 
 ```typescript
-import { runKodaX } from '@kodax-ai/kodax';                  // root: CLI helpers + runKodaX
-import { Runner, runFanOut } from '@kodax-ai/kodax/agent';   // generic Agent framework
-import { getProvider } from '@kodax-ai/kodax/llm';           // 12-provider LLM abstraction
-import { KODAX_TOOLS } from '@kodax-ai/kodax/coding';        // tools + prompts + agent loop
-import { InkREPL } from '@kodax-ai/kodax/repl';              // Ink TUI components
-import { SkillRegistry } from '@kodax-ai/kodax/skills';      // zero-dep skill loader
+import { runKodaX } from '@kodax-ai/kodax';                       // root: CLI helpers + runKodaX
+import { Runner, runFanOut } from '@kodax-ai/kodax/agent';        // generic Agent framework
+import { getProvider } from '@kodax-ai/kodax/llm';                // 12-provider LLM abstraction
+import { KODAX_TOOLS } from '@kodax-ai/kodax/coding';             // tools + prompts + agent loop
+import { InkREPL } from '@kodax-ai/kodax/repl';                   // Ink TUI components
+import { SkillRegistry } from '@kodax-ai/kodax/skills';           // zero-dep skill loader
+import { createMcpManager } from '@kodax-ai/kodax/mcp';           // MCP popout manager (v0.7.42)
 ```
 
+> The SDK is **ESM-only**. CommonJS consumers (Electron main / Webpack CJS / `require()` callers) must use `await import('@kodax-ai/kodax/...')` — see [docs/SDK_EMBEDDER_GUIDE.md §5](docs/SDK_EMBEDDER_GUIDE.md#5-consuming-from-a-commonjs-context-electron-main-cjs-bundles).
+
 ### `@kodax-ai/kodax/llm` — LLM Abstraction
 
 12 built-in providers (Anthropic, OpenAI, DeepSeek, Kimi, Kimi-Code, Qwen, Zhipu, Zhipu-Coding, MiniMax-Coding, MiMo-Coding, Ark-Coding, Gemini-CLI, Codex-CLI) + custom provider registration.
@@ -911,7 +838,7 @@ const result = await executeSkill({
 
 ### `@kodax-ai/kodax/coding` — Coding Agent
 
-Complete coding agent: 30+ tools (`read`/`write`/`edit`/`bash`/`grep`/`glob`/`dispatch_child_task`/`send_message`/`task_stop`/...) + role prompts (Worker / Evaluator) + agent loop + auto-continue + session management.
+Complete coding agent: 30+ tools (`read`/`write`/`edit`/`bash`/`grep`/`glob`/`dispatch_child_task`/`send_message`/`task_stop`/...) + Worker role prompt + Sidecar Verifier (out-of-band Stop-hook) + agent loop + auto-continue + session management.
 
 ```typescript
 import { runKodaX, KodaXClient, KODAX_TOOLS } from '@kodax-ai/kodax/coding';
@@ -933,7 +860,7 @@ await client.send('Create a new file');
 await client.send('Add a function to it'); // Has context from previous message
 ```
 
-**Key Features**: 30+ built-in tools (see [Tools](#tools)) · Worker+Evaluator V2 chain (FEATURE_114, v0.7.36 default) · async child steering via `send_message` / `task_stop` (FEATURE_120, v0.7.39) · idle-yield wait mechanic (FEATURE_155, v0.7.38) · auto-continue · session lineage.
+**Key Features**: 30+ built-in tools (see [Tools](#tools)) · V2 Worker single-loop + Sidecar Verifier (FEATURE_184 v0.7.42 / V1 chain fully retired by FEATURE_193 v0.7.43) · async child steering via `send_message` / `task_stop` (FEATURE_120, v0.7.39) · idle-yield wait mechanic (FEATURE_155, v0.7.38) · specialist routing via `subagent_type` (FEATURE_191, v0.7.43) · auto-continue · session lineage.
 
 ### `@kodax-ai/kodax/repl` — Interactive Terminal UI
 
@@ -957,11 +884,13 @@ import { InkREPL } from '@kodax-ai/kodax/repl';
 ```
 @kodax-ai/llm    (zero business-logic deps)
     ↓
-@kodax-ai/agent  (depends @kodax-ai/llm; ADR-021 standalone-consumable)
+@kodax-ai/agent  (depends @kodax-ai/llm; ADR-021 standalone-consumable;
+                  inlines session-lineage + capabilities/{mcp,skills} +
+                  tracing per ADR-036 v0.7.43)
+    ↓
+@kodax-ai/coding (depends llm + agent; inlines repo-intelligence/protocol per ADR-036)
     ↓
-@kodax-ai/skills (zero external deps)  →  @kodax-ai/coding  (depends llm + agent + skills)
-                                                    ↓
-                                              @kodax-ai/repl (depends coding + ink + react)
+@kodax-ai/repl   (depends coding + ink + react)
 ```
 
 **Subpath Recommendations**:
@@ -969,8 +898,7 @@ import { InkREPL } from '@kodax-ai/kodax/repl';
 | Use Case | Subpath | Why |
 |----------|---------|-----|
 | Only need LLM abstraction | `@kodax-ai/kodax/llm` | Minimal deps; 12 providers |
-| Building custom agent | `@kodax-ai/kodax/agent` | Runner + fan-out + idle-yield + sessions |
-| Using skills system | `@kodax-ai/kodax/skills` | Zero deps, pure skills |
+| Building custom agent | `@kodax-ai/kodax/agent` | Runner + fan-out + idle-yield + session-lineage + capabilities |
 | Coding tasks | `@kodax-ai/kodax/coding` | Complete coding agent + tools |
 | Terminal app | `@kodax-ai/kodax/repl` | Full interactive experience |
 
@@ -1013,7 +941,7 @@ kodax --session list
 # Parallel tool execution
 kodax --parallel "Read package.json and tsconfig.json"
 
-# Adaptive multi-agent (AMA) mode — Scout-first fan-out for multi-file work
+# Adaptive multi-agent (AMA) mode — V2 Worker single-loop with `dispatch_child_task` fan-out
 kodax --agent-mode ama "Analyze code structure, check test coverage, find bugs"
 ```
 
@@ -1076,7 +1004,7 @@ KodaX ships 30+ built-in tools, grouped below. They are registered as a single f
 | `task_stop` | Request graceful exit of a specific child. Current tool finishes atomically, then the child sees a `<coordinator-stop-request>` and emits a final summary. Coordinator-only. (FEATURE_120, v0.7.39) |
 | `ask_user_question` | Single/multi-select or free-text prompt back to the user |
 | `exit_plan_mode` | Present a finalized plan for approval (REPL only) |
-| `emit_managed_protocol` | Internal managed-task protocol side-channel for role payloads (handoff / verdict). V2 chain (Worker→Evaluator) is the default since v0.7.36 (FEATURE_114). |
+| `emit_managed_protocol` | Internal managed-task protocol side-channel for role payloads (verdict). V2 Worker single-loop + Sidecar Verifier is the default since v0.7.42 (FEATURE_184); V1 chain retired in v0.7.43 (FEATURE_193). |
 
 ---