@kodax-ai/kodax 0.7.63 → 0.7.67

package/README.md

@@ -296,6 +296,76 @@ const result = await runKodaX(
 > surface (`startKodaX` + `RunningSession`), MCP popout manager API (`McpManager`),
 > Skill `` !`cmd` `` host hook, and per-app data dir namespacing (`getAppDataDir`).
 
+## Runtime SDK and daemon
+
+SDK hosts can use `@kodax-ai/kodax/runtime` in three forms: inline embedded for
+lowest latency, Worker-hosted embedded for private state plus hard V8 disposal,
+or a local daemon shared by REPL, Space, IDE adapters, and custom SDK clients.
+All three expose the same `KodaXRuntime` services.
+
+```ts
+import { createKodaXRuntime } from '@kodax-ai/kodax/runtime';
+
+const isolated = await createKodaXRuntime({
+  mode: 'embedded',
+  isolation: 'worker',
+  requirements: { hardDispose: true },
+});
+```
+
+Inline is private and lowest-overhead; Worker is private and hard-disposable;
+daemon is process-isolated and shared. `runtime.close()` closes private
+inline/Worker ownership, but only detaches one daemon client. Contradictory
+isolation options fail instead of silently selecting a weaker mode. Worker
+isolation is a V8 fault boundary, not a security sandbox.
+
+Because a daemon is intentionally persistent, tests that auto-start one must
+also run `kodax daemon stop --home <dir> --profile <name>` (or send authenticated
+`runtime.shutdown`) before deleting their temporary home. A remaining Node
+process is not safe to kill by name alone; verify its command line and owner.
+
+```bash
+kodax daemon start
+kodax daemon stop --profile default
+kodax --runtime-mode daemon
+kodax -p "Review this repository" --runtime-mode daemon
+```
+
+All CLI task forms now use the same Runtime path: interactive REPL, positional
+prompts, slash-command prompts, and `kodax -p`. Select the persistent default in
+`~/.kodax/config.json`:
+
+```json
+{
+  "runtimeMode": "daemon"
+}
+```
+
+Resolution order is explicit CLI/SDK option > environment variable >
+`config.json` > built-in default (`embedded`). `KODAX_RUNTIME_MODE=daemon` is a
+temporary environment override. The same rule applies to other paired settings,
+for example `provider` ↔ `KODAX_PROVIDER` and `effort` ↔ `KODAX_EFFORT`.
+JSON names stay camelCase while environment names use `KODAX_UPPER_SNAKE_CASE`.
+
+By default, daemon state, config, and runtime session storage are scoped under
+the OS user home directory, so `kodax --runtime-mode daemon` and SDK clients
+using `createKodaXRuntime({ mode: 'daemon' })` converge on the same local daemon
+profile. The high-level `createKodaXRuntime({ mode: 'daemon' })` API starts or
+reuses that daemon unless you pass an explicit endpoint/transport or
+`autoStartDaemon: false`. Pass `--home <dir>` or `homeDir` only when you
+intentionally want an isolated daemon namespace for tests, CI, or project-local
+experiments.
+
+One daemon owns many sessions. Different sessions may run concurrently; starts
+within the same session are queued so that only one run is active for that
+session. Multiple `kodax` processes can attach to the same daemon and open or
+observe different sessions.
+
+For the full host-integration contract, including inline/Worker/daemon selection,
+multi-client permission handling, config/catalog/MCP admin APIs, artifacts,
+context diagnostics, and daemon protocol schemas, see
+[docs/SDK_EMBEDDER_GUIDE.md §17](docs/SDK_EMBEDDER_GUIDE.md#17-runtime-sdk-worker-isolation-and-local-daemon-feature_253-feature_257).
+
 ## Repo Intelligence
 
 KodaX ships with built-in repo intelligence (`repo_overview`, `module_context`, `symbol_context`, `process_context`, `impact_estimate`, and related tools) that helps the coding agent understand large codebases without ad-hoc grep/glob exploration.
@@ -309,7 +379,7 @@ kodax --repo-intelligence full --repo-intelligence-trace
 
 ## Architecture
 
-KodaX uses a **monorepo architecture** with npm workspaces. Source layout currently has 4 workspace packages; published as a single bundled npm package `@kodax-ai/kodax` with 8 SDK subpath exports (`/agent`, `/llm`, `/coding`, `/media`, `/repl`, `/skills`, `/mcp`, `/session`; ADR-024 + ADR-032 + ADR-038, with ADR-036 consolidation):
+KodaX uses a **monorepo architecture** with npm workspaces. Source layout currently has 4 workspace packages; published as a single bundled npm package `@kodax-ai/kodax` with 9 SDK subpath exports (`/agent`, `/llm`, `/coding`, `/media`, `/repl`, `/skills`, `/mcp`, `/session`, `/runtime`; ADR-024 + ADR-032 + ADR-038, with ADR-036 consolidation):
 
 ```
 KodaX/
@@ -335,7 +405,7 @@ KodaX/
 │
 ├── 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,media,repl,skills,mcp,session}
+│   └── sdk-*.ts             # SDK subpath re-exports → @kodax-ai/kodax/{agent,llm,coding,media,repl,skills,mcp,session,runtime}
 │
 └── package.json             # Root workspace config; release.mjs rewrites name + injects subpath exports
 ```
@@ -384,19 +454,21 @@ Source-side workspace package names (`@kodax-ai/*`). npm consumers install the s
 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 8 SDK subpaths (what SDK consumers `import` from). The subpaths are split into two roles:
+- **npm-published**: a single bundled package `@kodax-ai/kodax` with 9 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** (`/media`, `/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 | 15-alias 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/llm`    | `@kodax-ai/kodax/llm`     | Full package | 15-alias LLM abstraction (108 exports) | Standalone LLM clients |
+| `packages/agent`  | `@kodax-ai/kodax/agent`   | Full package | Runner / fan-out / external-agent plane / session-lineage / capabilities / tracing (331 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 + 50+ 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` / `loadFullTranscript` / `appendClientNotice` / `forkSession` / `compactSession` / `watchSessions` / ... | IDE plugins and desktop hosts reading session history |
+| `packages/agent`  | `@kodax-ai/kodax/mcp`     | **Narrow subset** | MCP only — `McpCapabilityProvider` / `createMcpTransport` / `searchMcpCatalog` / ... (23 exports) | MCP server hosts |
+| `packages/agent`  | `@kodax-ai/kodax/media`   | **Narrow subset** | Structured image/file/video input-artifact helpers (22 exports) | Desktop hosts and multimodal clients |
+| `packages/coding` | `@kodax-ai/kodax/coding`  | Full package | Coding agent + 50+ tools + repo-intelligence (505 exports) | Build a Claude Code-shape product |
+| `packages/repl`   | `@kodax-ai/kodax/repl`    | Full package | Ink TUI + permission modes + commands (217 exports) | Terminal-UI consumers |
+| `packages/repl`   | `@kodax-ai/kodax/session` | **Narrow subset** | Session management only — `listSessions` / `loadFullTranscript` / `appendClientNotice` / `forkSession` / `compactSession` / `watchSessions` / ... (17 exports) | IDE plugins and desktop hosts reading session history |
+| `src`             | `@kodax-ai/kodax/runtime` | Host API | Embedded/Worker/daemon runtime facade, sessions/runs/events/permissions/catalog/MCP/artifacts/diagnostics/external agents, daemon protocol schema (10 exports) | SDK hosts, Space/IDE clients, daemon clients |
 
 **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.
 
@@ -414,6 +486,12 @@ KodaX has two layers that consumers should understand separately:
 
 **Tool-Output Compression + Workflow Quality Preflight (FEATURE_251 + FEATURE_252, v0.7.61)**: KodaX's own `bash` tool now compresses noisy command output **inside the tool**, so a big `git diff`, test run, package install, or `docker build` no longer spends thousands of context tokens — command-aware filters (git/test/lint/JSON + a declarative package/docker/infra long-tail) summarize the stdout/stderr body while the `Command:`/`Exit:` header stays verbatim and every lossy summary keeps a raw-recovery path; isolated measurements show ~66–99% body-token reduction. Alongside it, inline `run_workflow` gains a deterministic pre-start quality lint that hard-fails weak-model authoring contract bugs (unawaited workflow-command used as a boolean, top-level access of `result.structured` fields, literal agent fanout above manifest/host caps) before a run starts. Both are deterministic (no prompt change). See [docs/features/v0.7.61.md](docs/features/v0.7.61.md) and [docs/ADR.md ADR-050](docs/ADR.md).
 
+**External Agent SDK Plane (FEATURE_258, v0.7.67)**: `/agent` exports the protocol-neutral executor, registration, policy, credential-broker, artifact-policy, catalog, and durable task contracts. `/runtime` exposes the installed plane through `admin.agentRegistrations`, `agents`, and `agentTasks`, with the same DTO service methods over embedded and daemon clients. Executor factories are host functions: install them in an inline owner or while creating a new in-process daemon owner; they cannot be injected through an existing daemon connection or across a Runtime Worker boundary. Plane shutdown is terminal: pending waits and all later service calls reject. Restricted Workflow scripts preserve validated `phase` and external `target` routing. See the [complete owner/consumer recipes and safety contract](docs/SDK_EMBEDDER_GUIDE.md#18-external-agent-executor-plane-feature_258-v0767).
+
+**Cost-Disciplined Workflow SDK (FEATURE_259, v0.7.67)**: SDK callers configure run-scoped `modelTiers` and `workflow.maxConcurrency`, while workflow authors express semantic `fast` / `balanced` / `deep` intent. Terminal workflow events expose resolved tier/source/fallback/usage/duration facts, and each durable `run.json` contains an `efficiencyReport` with token coverage, role/tier starts, packet-read topology, review waves, and quality-gate outcomes. See the [routing and telemetry contract](docs/SDK_EMBEDDER_GUIDE.md#20-cost-disciplined-workflow-routing-and-telemetry-feature_259-v0767).
+
+**Paged Session Listing (FEATURE_261, v0.7.67)**: both `/session` `listSessions()` and `runtime.sessions.list()` accept an exact `surface` filter and opaque continuation `cursor`; each returned summary carries the cursor for the next page. Filtering happens before the page limit, so a host does not need to over-fetch mixed surfaces. See the [pagination recipes](docs/SDK_EMBEDDER_GUIDE.md#19-session-surface-filtering-and-cursor-pagination-feature_261-v0767).
+
 ---
 
 ## Features
@@ -478,8 +556,12 @@ Output lives under `dist/binary/<target>/`:
 
 ```
 dist/binary/linux-x64/
-├── kodax              # ~60 MB Bun-compiled executable
-└── builtin/           # Sidecar built-in skills
+├── kodax                          # ~60 MB Bun-compiled executable
+├── builtin/                       # Sidecar built-in skills
+├── provider-capabilities.json
+├── semantic-worker.js             # Repo-intelligence Worker
+├── runtime-worker.js              # SDK Runtime Worker
+└── constructed-handler-worker.js  # Constructed-tool Worker
 ```
 
 Smoke-test: `dist/binary/<host>/kodax --version`.
@@ -519,13 +601,20 @@ For smaller surface and tree-shake-friendly imports, the SDK is also exposed via
 import { Runner } from '@kodax-ai/kodax/agent';                // agent runtime
 import { getProvider } from '@kodax-ai/kodax/llm';              // LLM abstraction (15 aliases)
 import { runKodaX } from '@kodax-ai/kodax/coding';              // coding tools + prompts
+import { createImageArtifactFromPath } from '@kodax-ai/kodax/media'; // input artifacts
 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)
 import { listSessions } from '@kodax-ai/kodax/session';         // session history helpers
+import { createKodaXRuntime } from '@kodax-ai/kodax/runtime';   // embedded/daemon runtime API
 ```
 
-All 9 SDK entries (root + 8 subpaths) share internal code via ESM chunk splitting — importing from `/agent` does not pull in `/repl`'s Ink + React surface.
+All 10 SDK entries (root + 9 subpaths) share internal code via ESM chunk splitting — importing from `/agent` does not pull in `/repl`'s Ink + React surface.
+
+For the complete host-facing contract — including embedded/Worker/daemon ownership,
+external-agent registration and task control, session cursor pagination, workflow
+model-tier routing, and efficiency telemetry — see the
+[SDK Embedder Integration Guide](docs/SDK_EMBEDDER_GUIDE.md).
 
 > **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.
 
@@ -583,10 +672,21 @@ kodax --session my-project "Summarize it"
 kodax --session my-project "How should I fix the first issue?"
 
 # Session management
-kodax --session list
-kodax --session resume "continue"
+kodax -r                    # Search, page, and select a non-empty session
+kodax -r <session-id>       # Resume a known session directly
+kodax -r "Review runtime"   # Resume a unique exact title; duplicates open the picker
+kodax --session list        # List up to 50 non-empty sessions
+kodax --session cleanup-acp # Preview strictly matched empty ACP-test pollution
 ```
 
+Bare `-r` opens an interactive picker with incremental search, arrow/PageUp/PageDown
+navigation, Tab completion, full selected-session ID display, and Enter-to-resume.
+An explicit value checks the complete session ID first, then an exact
+case-insensitive title; duplicate titles open a narrowed picker instead of
+silently choosing one. Cleanup is preview-only unless
+`--apply-session-cleanup` is also provided; matching sessions are archived rather
+than permanently deleted.
+
 ### Session Patterns
 
 ```bash
@@ -621,7 +721,7 @@ kodax                    Start the interactive REPL
 -h, --help [topic]   Show help or topic help
 -p, --print <text>   Run a single task and exit
 -c, --continue       Continue the most recent conversation in this directory
--r, --resume [id]    Resume a session by ID, or the latest session
+-r, --resume [value] Resume by ID/exact title, or open the searchable picker
 -m, --provider       Provider to use
 --model <name>       Override the model
 --reasoning <mode>   off | auto | quick | balanced | deep
@@ -812,7 +912,7 @@ await runKodaX({
 
 ## SDK Usage
 
-KodaX ships as a single npm package `@kodax-ai/kodax` with 8 SDK subpath exports (ADR-024 v0.7.39 + ADR-032 v0.7.42 + ADR-038 v0.7.49 + v0.7.56 `/media`). Each subpath is tree-shake-friendly so consumers pull only what they need:
+KodaX ships as a single npm package `@kodax-ai/kodax` with 9 SDK subpath exports (ADR-024 v0.7.39 + ADR-032 v0.7.42 + ADR-038 v0.7.49 + v0.7.56 `/media` + v0.7.64 `/runtime`). Each subpath is tree-shake-friendly so consumers pull only what they need:
 
 ```bash
 npm install @kodax-ai/kodax
@@ -828,6 +928,7 @@ import { runInkInteractiveMode } from '@kodax-ai/kodax/repl';     // Ink TUI ent
 import { SkillRegistry } from '@kodax-ai/kodax/skills';           // zero-dep skill loader
 import { createMcpManager } from '@kodax-ai/kodax/mcp';           // MCP popout manager (v0.7.42)
 import { listSessions } from '@kodax-ai/kodax/session';           // session history helpers
+import { createKodaXRuntime } from '@kodax-ai/kodax/runtime';     // embedded/daemon runtime API
 ```
 
 > 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).
@@ -976,6 +1077,7 @@ await runInkInteractiveMode({ provider: 'zhipu-coding', effort: 'auto' });
 | 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 |
+| Runtime host / daemon client | `@kodax-ai/kodax/runtime` | Sessions, runs, events, permissions, catalog, MCP, artifacts, diagnostics |
 
 ---
 

package/README_CN.md

@@ -213,9 +213,12 @@ import { SkillRegistry } from '@kodax-ai/kodax/skills';         // 零依赖 ski
 import { loadConfig } from '@kodax-ai/kodax/repl';              // REPL 配置 / session 工具
 import { createMcpManager } from '@kodax-ai/kodax/mcp';         // MCP popout manager（v0.7.42 起）
 import { listSessions } from '@kodax-ai/kodax/session';         // session 历史工具
+import { createKodaXRuntime } from '@kodax-ai/kodax/runtime';   // embedded/Worker/daemon 宿主 API
 ```
 
-9 个 SDK 入口（root + 8 subpath）通过 ESM 共享 chunk 复用底层代码 —— 只 import `/agent` 不会把 `/repl` 的 Ink + React 一起拉进来。
+10 个 SDK 入口（root + 9 subpath）通过 ESM 共享 chunk 复用底层代码 —— 只 import `/agent` 不会把 `/repl` 的 Ink + React 一起拉进来。
+
+完整的宿主集成契约——包括 embedded/Worker/daemon 所有权、外部 Agent 注册与任务控制、session cursor 分页、workflow 模型分层和效率遥测——见 [SDK Embedder Integration Guide](docs/SDK_EMBEDDER_GUIDE.md)。
 
 > **SDK 是 ESM-only**。在 CommonJS 上下文（Electron main 进程、传统 Webpack CJS bundle、`require()` 调用方）必须用 `await import('@kodax-ai/kodax/...')` 代替 `require()`。详见 [docs/SDK_EMBEDDER_GUIDE.md §5](docs/SDK_EMBEDDER_GUIDE.md#5-consuming-from-a-commonjs-context-electron-main-cjs-bundles)，含 Electron main 完整 recipe + 为什么大多数 subpath 物理上无法做 dual ESM/CJS bundle。
 
@@ -344,7 +347,57 @@ registerCustomProviders([
 await runKodaX({ provider: 'my-openai-compatible' }, '解释这个仓库');
 ```
 
-### 6. 打包成单文件二进制（无需 Node）
+### 6. Runtime 与本机 daemon
+
+交互 REPL、位置参数、slash-command 生成的任务和 `kodax -p` 现在都走统一的
+`KodaXRuntime` 入口。默认使用最低延迟的进程内 `embedded`；单一 SDK 宿主需要
+独立 V8 与硬销毁时，可选择 Worker-hosted embedded；需要后台持续运行、断线后
+查询或多个本机客户端共享时，可切到 `daemon`：
+
+```ts
+import { createKodaXRuntime } from '@kodax-ai/kodax/runtime';
+
+const isolated = await createKodaXRuntime({
+  mode: 'embedded',
+  isolation: 'worker',
+  requirements: { hardDispose: true },
+});
+```
+
+inline 形态由调用方私有且开销最低；Worker 形态仍然私有，但可硬销毁；
+daemon 形态使用独立进程并允许多个客户端共享。`runtime.close()` 会关闭
+私有 inline/Worker Runtime，但对 daemon 只断开当前客户端。矛盾的隔离参数
+会直接报错，不会静默降级。Worker 是 V8 故障隔离边界，不是安全沙箱。
+
+daemon 按设计会持续驻留。测试若自动启动 daemon，删除临时 home 前还必须执行
+`kodax daemon stop --home <目录> --profile <名称>`（或发送已认证的
+`runtime.shutdown`）。不要按进程名批量结束 Node；应先核验命令行和父进程归属。
+
+```bash
+kodax daemon start
+kodax daemon stop --profile default
+kodax --runtime-mode daemon
+kodax -p "检查这个仓库" --runtime-mode daemon
+```
+
+持久设置写入 `~/.kodax/config.json`：
+
+```json
+{
+  "runtimeMode": "daemon"
+}
+```
+
+统一优先级是：显式 CLI/SDK 参数 > 环境变量 > `config.json` > 内置默认值。
+`KODAX_RUNTIME_MODE=daemon` 适合临时覆盖。其他成对配置也遵循相同规则，例如
+`provider` ↔ `KODAX_PROVIDER`、`effort` ↔ `KODAX_EFFORT`。JSON 保持 camelCase，
+环境变量保持 `KODAX_UPPER_SNAKE_CASE`，两者按语义一一对应。
+
+一个 daemon 可以承载多个 session。不同 session 可以并发运行；同一个 session
+内部仍保持一次只运行一个任务，后续任务按队列执行。多个 `kodax` 进程可以连接
+同一个 daemon，并分别打开或观察不同 session。
+
+### 7. 打包成单文件二进制（无需 Node）
 
 KodaX 可以用 `bun --compile` 打包成单可执行文件 + 一个 `builtin/` sidecar 目录，目标机器**不需要安装 Node.js 或任何运行时**。
 
@@ -365,8 +418,12 @@ node scripts/build-binary.mjs --target=linux-arm64   # 指定平台
 
 ```
 dist/binary/linux-x64/
-├── kodax              # ~60 MB Bun 编译的二进制
-└── builtin/           # 内置 skills sidecar
+├── kodax                          # ~60 MB Bun 编译的二进制
+├── builtin/                       # 内置 skills sidecar
+├── provider-capabilities.json
+├── semantic-worker.js             # Repo intelligence Worker
+├── runtime-worker.js              # SDK Runtime Worker
+└── constructed-handler-worker.js  # Constructed tool Worker
 ```
 
 冒烟验证：`dist/binary/<host>/kodax --version`。
@@ -494,13 +551,15 @@ KodaX 有两层结构，SDK 用户需要分开理解：
 
 | 源码包 | npm subpath | 类型 | 内容 | 典型消费者 |
 |---|---|---|---|---|
-| `packages/llm`    | `@kodax-ai/kodax/llm`     | 完整包 | 15-alias LLM 抽象 (77 exports) | 独立 LLM 客户端 |
-| `packages/agent`  | `@kodax-ai/kodax/agent`   | 完整包 | Runner / fan-out / session-lineage / capabilities / tracing (202 exports) | 自定义 agent 框架 |
+| `packages/llm`    | `@kodax-ai/kodax/llm`     | 完整包 | 15-alias LLM 抽象 (108 exports) | 独立 LLM 客户端 |
+| `packages/agent`  | `@kodax-ai/kodax/agent`   | 完整包 | Runner / fan-out / 外部 Agent plane / session-lineage / capabilities / tracing (331 exports) | 自定义 agent 框架 |
 | `packages/agent`  | `@kodax-ai/kodax/skills`  | **窄子集** | 仅 Skills 系统 —— `SkillRegistry` / `loadFullSkill` / `expandSkillForLLM` 等 (26 exports = v0.7.43 之前 `@kodax-ai/skills` 完整 API) | Skill 加载器、IDE 插件 |
-| `packages/agent`  | `@kodax-ai/kodax/mcp`     | **窄子集** | 仅 MCP —— `McpCapabilityProvider` / `createMcpTransport` / `searchMcpCatalog` 等 (11 exports = v0.7.43 之前 `@kodax-ai/mcp` 完整 API) | MCP server 宿主 |
-| `packages/coding` | `@kodax-ai/kodax/coding`  | 完整包 | Coding agent + 50+ 工具 + repo-intelligence (342 exports) | 构建 Claude Code 形态产品 |
-| `packages/repl`   | `@kodax-ai/kodax/repl`    | 完整包 | Ink TUI + 权限模式 + 命令系统 (193 exports) | 终端 UI 消费者 |
-| `packages/repl`   | `@kodax-ai/kodax/session` | **窄子集** | 仅会话管理 —— `listSessions` / `loadFullTranscript` / `appendClientNotice` / `forkSession` / `compactSession` / `watchSessions` 等 | 读取 session 历史的 IDE 插件和桌面宿主 |
+| `packages/agent`  | `@kodax-ai/kodax/mcp`     | **窄子集** | 仅 MCP —— `McpCapabilityProvider` / `createMcpTransport` / `searchMcpCatalog` 等 (23 exports) | MCP server 宿主 |
+| `packages/agent`  | `@kodax-ai/kodax/media`   | **窄子集** | 结构化图片/文件/视频输入 artifact helpers (22 exports) | 桌面宿主、多模态客户端 |
+| `packages/coding` | `@kodax-ai/kodax/coding`  | 完整包 | Coding agent + 50+ 工具 + repo-intelligence (505 exports) | 构建 Claude Code 形态产品 |
+| `packages/repl`   | `@kodax-ai/kodax/repl`    | 完整包 | Ink TUI + 权限模式 + 命令系统 (217 exports) | 终端 UI 消费者 |
+| `packages/repl`   | `@kodax-ai/kodax/session` | **窄子集** | 仅会话管理 —— `listSessions` / `loadFullTranscript` / `appendClientNotice` / `forkSession` / `compactSession` / `watchSessions` 等 (17 exports) | 读取 session 历史的 IDE 插件和桌面宿主 |
+| `src`             | `@kodax-ai/kodax/runtime` | 宿主 API | Embedded/Worker/daemon facade，含 sessions/runs/events/permissions/catalog/MCP/artifacts/diagnostics/外部 Agent 和 daemon schema (10 exports) | SDK 宿主、Space/IDE、daemon client |
 
 **经验法则**：需要 Runner / Agent / fan-out 时从 `/agent` 引入；只需要 skills 或 mcp API 时从 `/skills` 或 `/mcp` 引入，bundle 更小。窄子集是完整包的真子集 —— **不会**有额外符号。
 
@@ -508,6 +567,12 @@ KodaX 有两层结构，SDK 用户需要分开理解：
 
 **宿主读持久化历史（FEATURE_230 + FEATURE_234，v0.7.51；v0.7.63 hardening）**：面向「宿主读持久化状态」的 additive 闭环。**持久化工具记录回放**——resume 的会话现在会回放助手用过的工具卡片，而不是退化成纯文本。`messages` / `lineage` 仍是 canonical；`SessionData.uiHistory` 成为有界、脱敏、仅 terminal 状态的回放缓存。SDK transcript 契约明确化：`loadSession()` = 活动 model context，`loadFullTranscript()` = 带结构化条目的追加序 host scrollback（`message` / `compaction` / `branch_summary` / `rewind_marker` / `client_notice` / `task_result`）并带 clone provenance（`logicalId` / `sourceEntryId`），`uiHistory` = 可选回放缓存，工具卡片始终可从 canonical messages 重建。宿主可用 `appendClientNotice()` 持久化本地 slash 输出且不进入模型上下文；workflow/child 完成结果通过结构化 `taskResults[]` 暴露，不再要求解析 `<task-completed>` 文本。`rewind_marker` 只用于 host scrollback 审计，不进入 model-context messages。**Workflow run 宿主归属**——`WorkflowProcessTrackerOptions` / `WorkflowProcessSnapshot` 新增 host-owned 不透明 `hostMetadata?: Record<string, string>`，SDK 存储、持久化进 `run.json`、回读回显（含进程重启后）但不解释其含义，让宿主零侧表把 run 归回发起它的 session/surface。未 stamp 的旧 run 诚实回显 `hostMetadata === undefined`。详见 [docs/features/v0.7.51.md](docs/features/v0.7.51.md)。
 
+**会话恢复与 ACP 污染修复（FEATURE_261，v0.7.67）**：直接运行 `kodax -r` 会进入可搜索、上下选择、Tab 补全和翻页的交互式会话选择器，并显示当前选中项的完整 session ID；`kodax -r <值>` 优先按完整 ID 恢复，ID 不存在时再按忽略大小写的完整标题匹配。标题唯一则直接恢复，同名标题则进入只包含候选项的选择器，绝不静默选第一条。`listSessions()` / Runtime / daemon 会话列表新增 `surface` 精确过滤和不透明 `cursor` 分页。ACP session 改为收到首个有效 prompt 后才持久化，ACP 测试强制使用临时 runtime home，避免测试记录写入真实 `~/.kodax/sessions`。`kodax -s cleanup-acp` 只预览严格匹配的空 ACP 污染记录；仅显式追加 `--apply-session-cleanup` 时才归档，不做永久删除。
+
+**外部 Agent SDK plane（FEATURE_258，v0.7.67）**：`/agent` 导出协议中立的 executor、registration、policy、credential broker、artifact policy、catalog 和 durable task 契约；`/runtime` 通过 `admin.agentRegistrations`、`agents`、`agentTasks` 向 embedded 与 daemon client 提供同一组 DTO API。Executor factory 是宿主函数，只能装入 inline owner，或在创建新的 in-process daemon owner 时装入；不能通过既有 daemon 连接或 Runtime Worker 边界注入。Plane 关闭后是终态：未完成的 wait 和后续所有服务调用都会拒绝；受限 Workflow 脚本会完整校验并传递 `phase` 与外部 `target`。完整所有权、注册、preflight、启动/等待/继续/取消/对账和安全边界见 [SDK Embedder Guide §18](docs/SDK_EMBEDDER_GUIDE.md#18-external-agent-executor-plane-feature_258-v0767)。
+
+**成本受控 Workflow SDK（FEATURE_259，v0.7.67）**：SDK 调用方用 run-scoped `modelTiers` 与 `workflow.maxConcurrency` 配置路由和并发，workflow 作者只表达 `fast` / `balanced` / `deep` 语义意图。terminal workflow event 回显 tier/source/fallback/usage/duration，持久化 `run.json.efficiencyReport` 给出 token coverage、role/tier 启动数、packet-read 拓扑、review wave 和 quality gate 结果。完整配置与遥测读取方式见 [SDK Embedder Guide §20](docs/SDK_EMBEDDER_GUIDE.md#20-cost-disciplined-workflow-routing-and-telemetry-feature_259-v0767)。
+
 **Inline workflow authoring（FEATURE_246，v0.7.58）**：AMA/AMAW 下 Worker 现在可通过 model-callable 的 `run_workflow` 工具在会话内直接编写并运行工作流——先用自己的工具 scout 代码库，再把具体发现烤进每个 child prompt，然后走**不变的** sandbox + 静态校验 + postcondition 验证流水线。它取代 context-blind 的 `sideQuery` generator 成为主交互路径（generator 仅作为显式 `/workflow create` 命令与无 investigating Worker 的 non-interactive/CI 主机的 fallback 保留）；新增结构化 child 输出（`outputSchema`）、无 barrier 的 `wf.pipeline` 分阶段原语、同会话 resume（`resumeFromRunId`）、嵌套 `wf.workflow(...)`，`/workflow create` 重定向到 Worker 的 scout-then-author；`run_workflow` 为 async / idle-yield，不阻塞当前轮。中立的 run-lifecycle manager（`createWorkflowRunManager`）已移入 `@kodax-ai/kodax/agent` 供非 coding SDK 宿主使用。详见 [docs/features/v0.7.58.md](docs/features/v0.7.58.md) 与 [docs/ADR.md](docs/ADR.md) ADR-044/046/047/048/049。
 
 **工作流激活分层（FEATURE_248 + FEATURE_249，v0.7.59）**：三种 agent 模式现在有一致的工作流姿态。**AMAW** 携带 mode-level 的 `ORCHESTRATION DEFAULT` 常驻指令（对齐参考实现的 "ultracode" 姿态）：实质性工作——多文件调查、设计决策、任何做错代价高的任务——默认编排多个交叉验证的 agent，并有 PLAN-TIME COMMITMENT 流程修正把 orchestrate-vs-solo 决策前置到第 0 轮。**AMA** 同样 host `run_workflow` 工具但没有常驻指令——当你用自然语言请求编排时才激活，绝不因复杂度独自触发。**SA** 保持单独作业。该指令通过 `amawOrchestrationAvailable` 关闭泄漏，因此 AMA 与 SA 的 prompt 保持逐字节一致。详见 [docs/features/v0.7.59.md](docs/features/v0.7.59.md)。
@@ -531,9 +596,9 @@ KodaX/                       # 4 workspace packages(FEATURE_194 v0.7.43)
 │   └── repl/                # @kodax-ai/repl —— Ink TUI
 ├── src/
 │   ├── kodax_cli.ts         # CLI 主入口（bin: `kodax`）
-│   └── sdk-*.ts             # SDK subpath 入口 → @kodax-ai/kodax/{agent,llm,coding,media,repl,skills,mcp,session}
+│   └── sdk-*.ts             # SDK subpath 入口 → @kodax-ai/kodax/{agent,llm,coding,media,repl,skills,mcp,session,runtime}
 ├── scripts/
-│   ├── build-bundle.mjs     # esbuild 单 bundle 多 entry 打包（CLI + root + 8 SDK subpath + chunks）
+│   ├── build-bundle.mjs     # esbuild 单 bundle 多 entry 打包（CLI + root + 9 SDK subpath + chunks）
 │   ├── build-binary.mjs     # Bun --compile 单文件二进制打包
 │   └── release.mjs          # ADR-024 release-time pkg name/exports 注入
 └── .github/workflows/
@@ -627,6 +692,7 @@ KodaX 现在会把 Repo Intelligence 的本地缓存分成内置引擎 profile
 ## 文档
 
 - [README.md](README.md) - 英文版 README
+- [docs/SDK_EMBEDDER_GUIDE.md](docs/SDK_EMBEDDER_GUIDE.md) - SDK 宿主集成与 v0.7.67 公共 API 契约
 - [docs/release.md](docs/release.md) - 单文件二进制构建与发布流程
 - [docs/PRD.md](docs/PRD.md) - 产品需求
 - [docs/ADR.md](docs/ADR.md) - 架构决策

package/dist/chunks/{agent-SL444XLN.js → agent-E4V5SLX6.js}

@@ -1,2 +1,2 @@
 // @kodax-ai/kodax — bundled distribution. See docs/ADR.md ADR-022 + ADR-024.
-import{I as c,J as d,K as e,L as f,Z as g,_ as h,ja as i,ra as j}from"./chunk-LGR7ACBQ.js";import"./chunk-D6QVXQNI.js";import"./chunk-UA744TZM.js";import"./chunk-RR7W7UF6.js";import"./chunk-S4GVQO3W.js";import{ob as a,pb as b}from"./chunk-UGTK2JIJ.js";import"./chunk-ZL5CEANW.js";import"./chunk-V4WSBIXB.js";export{d as bucketProviderPayloadSize,g as buildAutoRepoIntelligenceContext,e as checkPromiseSignal,b as cleanupIncompleteToolCalls,h as describeTransientProviderRetry,f as emitResilienceDebug,c as estimateProviderPayloadBytes,j as runKodaX,i as saveSessionSnapshot,a as validateAndFixToolHistory};
+import{I as c,J as d,K as e,L as f,Z as g,_ as h,ra as i,za as j}from"./chunk-RS2GAABJ.js";import"./chunk-D6QVXQNI.js";import"./chunk-YRBNXFHY.js";import"./chunk-YH5BTUQO.js";import"./chunk-O7N22GJ3.js";import{rb as a,sb as b}from"./chunk-NVDK375I.js";import"./chunk-PZTG2C33.js";import"./chunk-ONUPGMER.js";export{d as bucketProviderPayloadSize,g as buildAutoRepoIntelligenceContext,e as checkPromiseSignal,b as cleanupIncompleteToolCalls,h as describeTransientProviderRetry,f as emitResilienceDebug,c as estimateProviderPayloadBytes,j as runKodaX,i as saveSessionSnapshot,a as validateAndFixToolHistory};

package/dist/chunks/argument-completer-N6RT5KYT.js

@@ -0,0 +1,2 @@
+// @kodax-ai/kodax — bundled distribution. See docs/ADR.md ADR-022 + ADR-024.
+import{Ba as a,Ca as b}from"./chunk-EN3O2C43.js";import"./chunk-AKMXJSGM.js";import"./chunk-CW32NQFO.js";import"./chunk-WCSSXBHR.js";import"./chunk-DEICMTHO.js";import"./chunk-KBBGDRER.js";import"./chunk-RS2GAABJ.js";import"./chunk-D6QVXQNI.js";import"./chunk-YRBNXFHY.js";import"./chunk-YH5BTUQO.js";import"./chunk-O7N22GJ3.js";import"./chunk-NVDK375I.js";import"./chunk-PZTG2C33.js";import"./chunk-ONUPGMER.js";export{a as ArgumentCompleter,b as createArgumentCompleter};

package/dist/chunks/{chunk-ARUWXX25.js → chunk-35P7QL2Q.js}

@@ -1,2 +1,2 @@
 // @kodax-ai/kodax — bundled distribution. See docs/ADR.md ADR-022 + ADR-024.
-import{a as o}from"./chunk-V4WSBIXB.js";var t=o(()=>{},"noop"),c={initialize:t,connectToDevTools:t};var e=class{static{o(this,"WebSocketStub")}},l=e;export{l as a,c as b};
+import{a as o}from"./chunk-ONUPGMER.js";var t=o(()=>{},"noop"),c={initialize:t,connectToDevTools:t};var e=class{static{o(this,"WebSocketStub")}},l=e;export{l as a,c as b};

package/dist/chunks/chunk-AKMXJSGM.js

@@ -0,0 +1,56 @@
+// @kodax-ai/kodax — bundled distribution. See docs/ADR.md ADR-022 + ADR-024.
+import{w as q,y as J}from"./chunk-RS2GAABJ.js";import{C as k,D as X,E as R,Ja as B,Na as z,ja as F,ka as j,la as G,ma as U,n as K,na as V,oa as A,va as $,wa as E,z as x,za as I}from"./chunk-O7N22GJ3.js";import{Ea as H,ya as W}from"./chunk-NVDK375I.js";import{a as o}from"./chunk-ONUPGMER.js";import c from"fs";import f from"path";import{exec as ce,spawnSync as le}from"child_process";import{promisify as ue}from"util";import{fileURLToPath as fe}from"url";var L="en";function ae(){return(process.env.LC_ALL||process.env.LC_MESSAGES||process.env.LANG||"").toLowerCase().startsWith("zh")?"zh":"en"}o(ae,"detectSystemLocale");function Q(e){if(!e||e==="auto"){L=ae();return}L=e.toLowerCase().replace(/[-_].*/,"")==="zh"?"zh":"en"}o(Q,"setLocale");var Y={en:{"dialog.confirm":"[Confirm]","dialog.select":"[Select]","dialog.input":"[Input]","confirm.instruction.basic":"Press (y) yes, (n) no","confirm.instruction.always":"Press (y) yes, (a) always yes for this tool, (n) no","confirm.instruction.protected":"Press (y) to confirm, (n) to cancel (protected path)","confirm.result.approved":"Approved","confirm.result.approved_always":"Approved (always)","confirm.result.denied":"Denied","tool.bash.title":"Execute bash command?","tool.shell.title":"Execute shell command?","tool.write.title":"Write to file?","tool.edit.title":"Edit file?","tool.generic.title":"Execute {tool}?","field.reason":"Reason","field.intent":"Intent","field.target":"Target","field.scope":"Scope","field.risk":"Risk","field.summary":"Summary","intent.read":"Read project files","intent.delete":"Delete files","intent.deps":"Modify dependencies or environment","intent.modify":"Modify files","intent.execute":"Execute command","intent.write_file":"Write file","intent.edit_file":"Edit file","intent.use_tool":"Use {tool}","risk.destructive":"Destructive change","risk.deps":"May change dependencies or local tools","risk.modify":"May modify files","risk.unknown":"Command effects depend on its arguments","risk.network":"May access network","scope.outside":"Outside project","scope.protected":"Protected path","waiting.confirm":"Waiting: approval required","waiting.select":"Waiting: choose an option","waiting.input":"Waiting: answer the prompt","placeholder.confirm":"Respond to the approval prompt above...","placeholder.select":"Choose an option above...","placeholder.input":"Answer the prompt above...","placeholder.busy":"Agent is busy...","placeholder.queue":"Queue a follow-up for the next round...","placeholder.idle":"Type a message...","select.choice":"Choice:","select.type_number":"(type a number)","select.more":"{count} more choices...","select.more_above":"\u2191 {count} more above","select.more_below":"\u2193 {count} more below","select.confirm_hint":"Press Enter to confirm, Esc to cancel","select.navigate_hint":"Use \u2191\u2193 to navigate, Enter to confirm, Esc to cancel","select.multiselect_hint":"Use \u2191\u2193 to navigate, Space to toggle, Enter to confirm, Esc to cancel","select.multiselect_empty":"Select at least one option with Space before confirming.","select.multiselect_min":"Select at least {min} option(s) with Space before confirming.","select.multiselect_max":"Select at most {max} option(s) with Space before confirming.","select.back_prev":"\u2190 Back to previous question","input.default":"Default:","input.value":"Value:","input.type_response":"(type your response)","managed.completed":"Task completed","managed.completed.blocked":"Task blocked","managed.completed.continuation":"Task needs continuation",cancelled:"[Cancelled] Operation cancelled by user"},zh:{"dialog.confirm":"[\u786E\u8BA4]","dialog.select":"[\u9009\u62E9]","dialog.input":"[\u8F93\u5165]","confirm.instruction.basic":"\u6309 (y) \u786E\u8BA4, (n) \u62D2\u7EDD","confirm.instruction.always":"\u6309 (y) \u786E\u8BA4, (a) \u59CB\u7EC8\u5141\u8BB8\u6B64\u5DE5\u5177, (n) \u62D2\u7EDD","confirm.instruction.protected":"\u6309 (y) \u786E\u8BA4, (n) \u53D6\u6D88 (\u53D7\u4FDD\u62A4\u8DEF\u5F84)","confirm.result.approved":"\u5DF2\u6279\u51C6","confirm.result.approved_always":"\u5DF2\u6279\u51C6 (\u59CB\u7EC8\u5141\u8BB8)","confirm.result.denied":"\u5DF2\u62D2\u7EDD","tool.bash.title":"\u6267\u884C bash \u547D\u4EE4\uFF1F","tool.shell.title":"\u6267\u884C shell \u547D\u4EE4\uFF1F","tool.write.title":"\u5199\u5165\u6587\u4EF6\uFF1F","tool.edit.title":"\u7F16\u8F91\u6587\u4EF6\uFF1F","tool.generic.title":"\u6267\u884C {tool}\uFF1F","field.reason":"\u539F\u56E0","field.intent":"\u610F\u56FE","field.target":"\u76EE\u6807","field.scope":"\u8303\u56F4","field.risk":"\u98CE\u9669","field.summary":"\u6458\u8981","intent.read":"\u8BFB\u53D6\u9879\u76EE\u6587\u4EF6","intent.delete":"\u5220\u9664\u6587\u4EF6","intent.deps":"\u4FEE\u6539\u4F9D\u8D56\u6216\u73AF\u5883","intent.modify":"\u4FEE\u6539\u6587\u4EF6","intent.execute":"\u6267\u884C\u547D\u4EE4","intent.write_file":"\u5199\u5165\u6587\u4EF6","intent.edit_file":"\u7F16\u8F91\u6587\u4EF6","intent.use_tool":"\u4F7F\u7528 {tool}","risk.destructive":"\u7834\u574F\u6027\u53D8\u66F4","risk.deps":"\u53EF\u80FD\u4FEE\u6539\u4F9D\u8D56\u6216\u672C\u5730\u5DE5\u5177","risk.modify":"\u53EF\u80FD\u4FEE\u6539\u6587\u4EF6","risk.unknown":"\u547D\u4EE4\u6548\u679C\u53D6\u51B3\u4E8E\u53C2\u6570","risk.network":"\u53EF\u80FD\u8BBF\u95EE\u7F51\u7EDC","scope.outside":"\u9879\u76EE\u5916\u90E8","scope.protected":"\u53D7\u4FDD\u62A4\u8DEF\u5F84","waiting.confirm":"\u7B49\u5F85\u4E2D\uFF1A\u9700\u8981\u5BA1\u6279","waiting.select":"\u7B49\u5F85\u4E2D\uFF1A\u8BF7\u9009\u62E9","waiting.input":"\u7B49\u5F85\u4E2D\uFF1A\u8BF7\u56DE\u7B54","placeholder.confirm":"\u8BF7\u56DE\u5E94\u4E0A\u65B9\u7684\u5BA1\u6279\u63D0\u793A...","placeholder.select":"\u8BF7\u5728\u4E0A\u65B9\u9009\u62E9\u4E00\u4E2A\u9009\u9879...","placeholder.input":"\u8BF7\u56DE\u7B54\u4E0A\u65B9\u7684\u63D0\u793A...","placeholder.busy":"\u667A\u80FD\u4F53\u6B63\u5728\u5DE5\u4F5C\u4E2D...","placeholder.queue":"\u6392\u961F\u7B49\u5F85\u4E0B\u4E00\u8F6E\u8DDF\u8FDB...","placeholder.idle":"\u8F93\u5165\u6D88\u606F...","select.choice":"\u9009\u9879\uFF1A","select.type_number":"(\u8F93\u5165\u7F16\u53F7)","select.more":"\u8FD8\u6709 {count} \u4E2A\u9009\u9879...","select.more_above":"\u2191 \u4E0A\u65B9\u8FD8\u6709 {count} \u4E2A","select.more_below":"\u2193 \u4E0B\u65B9\u8FD8\u6709 {count} \u4E2A","select.confirm_hint":"\u6309 Enter \u786E\u8BA4\uFF0CEsc \u53D6\u6D88","select.navigate_hint":"\u4F7F\u7528 \u2191\u2193 \u5BFC\u822A\uFF0CEnter \u786E\u8BA4\uFF0CEsc \u53D6\u6D88","select.multiselect_hint":"\u4F7F\u7528 \u2191\u2193 \u5BFC\u822A\uFF0C\u7A7A\u683C \u5207\u6362\u9009\u4E2D\uFF0CEnter \u786E\u8BA4\uFF0CEsc \u53D6\u6D88","select.multiselect_empty":"\u8BF7\u5148\u4F7F\u7528\u7A7A\u683C\u9009\u62E9\u81F3\u5C11\u4E00\u4E2A\u9009\u9879\u3002","select.multiselect_min":"\u8BF7\u5148\u4F7F\u7528\u7A7A\u683C\u81F3\u5C11\u9009\u62E9 {min} \u4E2A\u9009\u9879\u3002","select.multiselect_max":"\u6700\u591A\u53EA\u80FD\u9009\u62E9 {max} \u4E2A\u9009\u9879\u3002","select.back_prev":"\u2190 \u8FD4\u56DE\u4E0A\u4E00\u9898","input.default":"\u9ED8\u8BA4\u503C\uFF1A","input.value":"\u503C\uFF1A","input.type_response":"(\u8F93\u5165\u4F60\u7684\u56DE\u7B54)","managed.completed":"\u4EFB\u52A1\u5B8C\u6210","managed.completed.blocked":"\u4EFB\u52A1\u53D7\u963B","managed.completed.continuation":"\u4EFB\u52A1\u9700\u8981\u7EE7\u7EED",cancelled:"[\u5DF2\u53D6\u6D88] \u64CD\u4F5C\u5DF2\u88AB\u7528\u6237\u53D6\u6D88"}};function Ne(e,t){let r=Y[L][e]??Y.en[e]??e;if(t)for(let[i,s]of Object.entries(t))r=r.replace(`{${i}}`,String(s));return r}o(Ne,"t");var de=ue(ce),S=W(),He=f.join(S,"sessions"),d=f.join(S,"config.json"),qe=60,p=null,D=!1,pe="dumb";function me(e){let t=f.basename(e).toLowerCase(),n="__KODAX_SHELL_ENV_START__",r=`printf '%s\\0' '${n}'; env -0`;return t==="fish"?{args:["-i","-c",r],sentinel:n}:{args:t==="bash"||t==="zsh"?["-ic",r]:["-lc",r],sentinel:n}}o(me,"buildShellEnvCommand");function ge(e,t){let n=`${t}\0`,r=e.lastIndexOf(n);if(r===-1)return{};let i=e.slice(r+n.length),s={};for(let a of i.split("\0")){if(!a)continue;let u=a.indexOf("=");u<=0||(s[a.slice(0,u)]=a.slice(u+1))}return s}o(ge,"parseNullDelimitedShellEnv");function ve(e={}){let t=e.env??process.env;if((e.platform??process.platform)==="win32"||t.KODAX_DISABLE_SHELL_ENV_HYDRATION==="1")return!1;let r=e.shell??t.SHELL;if(!r||!f.isAbsolute(r))return!1;let{args:i,sentinel:s}=me(r),a=e.run??le,u={...t,TERM:pe},l=a(r,i,{encoding:"utf8",env:u,maxBuffer:1024*1024,timeout:5e3,windowsHide:!0,detached:!0,stdio:["ignore","pipe","pipe"]});if(l.status!==0||!l.stdout)return!1;let re=typeof l.stdout=="string"?l.stdout:l.stdout.toString("utf8"),ie=ge(re,s),N=!1;for(let[C,se]of Object.entries(ie))C!=="TERM"&&t[C]===void 0&&(t[C]=se,N=!0);return N}o(ve,"hydrateProcessEnvFromShell");function he(){if(!D){D=!0;try{ve()}catch{}}}o(he,"ensureShellEnvironmentHydrated");function Je(){D=!1}o(Je,"resetShellEnvironmentHydrationForTesting");function ye(e){$(e.customProviders??[])}o(ye,"registerConfiguredCustomProviders");function te(e){if(!Array.isArray(e))return;let t=e.filter(n=>typeof n=="string").map(n=>n.trim()).filter(n=>n.length>0);return t.length>0?t:[]}o(te,"normalizeConfiguredExtensions");function Ee(e){if(e.permissionMode!=="default")return e;let t={...e,permissionMode:"accept-edits"};try{c.mkdirSync(f.dirname(d),{recursive:!0}),c.writeFileSync(d,JSON.stringify(t,null,2))}catch{}return t}o(Ee,"migrateLegacyPermissionModeInConfig");function Pe(e){if(e.permissionMode!=="auto-in-project")return e;try{let t=c.readFileSync(d,"utf-8"),n=t.replace(/("permissionMode"\s*:\s*)"auto-in-project"/,'$1"auto"');n!==t&&c.writeFileSync(d,n)}catch{}return{...e,permissionMode:"auto"}}o(Pe,"migrateAutoInProjectAliasInConfig");function be(){if(p)return p;let e="0.7.67";if(e)return p=e,p;let t=f.join(f.dirname(fe(import.meta.url)),"../../package.json");if(c.existsSync(t))try{return p=JSON.parse(c.readFileSync(t,"utf-8")).version??"0.0.0",p??"0.0.0"}catch{}return p="0.0.0",p}o(be,"getVersion");var Ye=be();function _e(e){return j(e)}o(_e,"getProviderModel");function T(e,t){let n=new Set(e.map(i=>i.toLowerCase())),r=[...e];for(let i of t)n.has(i.toLowerCase())||r.push(i);return r}o(T,"mergeModels");function Se(e,t){t||(t=w().providerModels);let n=t?.[e];if(n&&n.length>0){try{let r=A(e);if(r.length>0)return T(n,r)}catch{}try{let r=E(e);if(r)return T(n,r.getAvailableModels())}catch{}return n}try{let r=A(e);if(r.length>0)return r}catch{}try{let r=E(e);if(r)return r.getAvailableModels()}catch{}return[]}o(Se,"getProviderAvailableModels");function Oe(e,t){let n=G(e,t);if(n!=="unknown")return n;try{let r=E(e);if(r)return r.getReasoningCapability(t)}catch{}return"unknown"}o(Oe,"getProviderReasoningCapability");function we(e){let t=U(e);if(t)return t;try{return I().find(r=>r.name===e)?.capabilityProfile??null}catch{return null}}o(we,"getProviderCapabilityProfile");function ne(e,t){let n=we(e),r=Oe(e,t);if(n)return{capabilityProfile:n,reasoningCapability:r};try{let i=B(e);return{capabilityProfile:i.getCapabilityProfile(),reasoningCapability:i.getReasoningCapability(t)}}catch{return null}}o(ne,"getProviderCapabilityMetadata");function Qe(e,t){let n=ne(e,t);return n?q({providerName:e,model:t,capabilityProfile:n.capabilityProfile,reasoningCapability:n.reasoningCapability==="unknown"?void 0:n.reasoningCapability}):null}o(Qe,"getProviderCapabilitySnapshot");function Ce(e,t,n,r){let i=ne(e,t);return i?J({providerName:e,model:t,capabilityProfile:i.capabilityProfile,reasoningCapability:i.reasoningCapability==="unknown"?void 0:i.reasoningCapability,reasoningMode:n,hints:r}):null}o(Ce,"getProviderPolicyDecision");function Ze(e){let t=e.transport==="cli-bridge"?"CLI bridge":"Native API",n=e.conversationSemantics==="last-user-message"?"forwards only the latest user message":"preserves full conversation history",r=e.mcpSupport==="native"?"MCP available":"MCP unavailable";return`${t}; ${n}; ${r}`}o(Ze,"describeProviderCapabilitySummary");function et(e){switch(e){case"native-budget":return"B";case"native-effort":return"E";case"native-toggle":return"T";case"native-adaptive":return"A";default:return"-"}}o(et,"formatReasoningCapabilityShort");function y(e){if(e)return e==="none"?"off":e}o(y,"formatReasoningEffortForDisplay");function _(e,t){let n=y(t);n&&!e.includes(n)&&e.push(n)}o(_,"pushUniqueEffortDisplay");function tt(e,t){let n=["auto"],i=O(e,t)?.supportedEfforts?.filter(s=>s.isUserVisible!==!1);if(!i||i.length===0){for(let s of["off","low","medium","high"])_(n,s);return n}for(let s of i)_(n,s.value);return n}o(tt,"getProviderReasoningEffortOptions");function nt(e,t){let n=O(e,t),r=new Set(n?.disabledEfforts??[]),i=n?.supportedEfforts?.filter(l=>l.isUserVisible!==!1),s=[],a=n?.supportsDisabledThinking===!0;if(!i||i.length===0){for(let l of["low","medium","high"])_(s,l);a=!0}else for(let l of i){if(l.value==="none"){a=!0;continue}if(r.has(l.value)){a=!0;continue}_(s,l.value)}let u=[];return a&&u.push("off"),u.push(...s),u.push("auto"),u}o(nt,"getProviderReasoningEffortCycle");function xe(e,t){if(t===!1)return"off";switch(e){case"off":return"off";case"quick":return"low";case"balanced":return"medium";case"deep":return"high";default:return"auto"}}o(xe,"legacyReasoningModeToEffortDisplay");function O(e,t){let n=t??_e(e);if(!n)return;let r=z(e,n)?.reasoningProfile;if(r)return K(r,H(e,n))}o(O,"resolveReasoningProfileForDisplay");function ot(e){let t=y(e.effort)??xe(e.reasoningMode,e.thinking),n=O(e.provider,e.model);if(!n)return t;try{let r=X({capability:n,explicitEffort:e.effortOverride?e.effort:void 0,sessionEffort:e.effortOverride?void 0:e.effort,legacyReasoningMode:e.reasoningMode,thinking:e.thinking}),i=y(r.configuredEffort)??t,a=r.configuredEffort!==void 0&&n.disabledEfforts?.includes(r.configuredEffort)===!0?"off":y(r.effectiveEffort);return a&&a!==i?`${i}->${a}`:i}catch{if(e.effort)try{let r=R({currentEffort:e.effort,capability:n}),i=y(e.effort)??t,s=y(r.effectiveEffort);return s&&s!==i?`${i}->${s}`:i}catch{return t}return t}}o(ot,"formatReasoningEffortStatusLabel");function rt(e){let t=De(e);if(!t)return{preserved:!0};let n=O(e.provider,e.model);if(!n)return{configuredEffort:t,runtimeEffort:t,preserved:!0};let r=R({currentEffort:t,capability:n});return{configuredEffort:t,runtimeEffort:r.effectiveEffort,preserved:r.preserved,diagnostic:r.diagnostic}}o(rt,"resolveProviderReasoningRuntimeEffort");function ke(e){switch(e){case"native-budget":return"budget";case"native-effort":return"effort";case"native-toggle":return"toggle";case"native-adaptive":return"adaptive";default:return"none"}}o(ke,"describeReasoningCapabilityControl");function it(e,t){if(e==="off")return"Reasoning disabled";switch(t){case"native-budget":return"Uses native thinking budget control";case"native-effort":return"Uses native reasoning effort control";case"native-toggle":return"Uses provider-native thinking toggle only";case"native-adaptive":return"Model adaptively decides thinking depth (Opus 4.7+)";case"none":return"Runs without native reasoning parameters";case"prompt-only":return"Uses prompt overlays only; no native reasoning parameter";default:return"Runs without native reasoning parameters"}}o(it,"describeReasoningExecution");function st(e){let t=[];e||(e=w().providerModels);for(let n of V())t.push({name:n.name,model:n.model,models:Se(n.name,e),configured:n.capabilityProfile.transport==="cli-bridge"?!0:n.configured,reasoningCapability:n.reasoningCapability,capabilityProfile:n.capabilityProfile});try{let n=I().map(r=>({...r,models:(()=>{let i=e?.[r.name];return i&&i.length>0?T(i,r.models):r.models})()}));t.push(...n)}catch{}return t}o(st,"getProviderList");function at(e){if(F(e))return!0;try{return E(e)?.isConfigured()??!1}catch{return!1}}o(at,"isProviderConfigured");function w(){try{if(c.existsSync(d)){let e=JSON.parse(c.readFileSync(d,"utf-8")),t=e.reasoningCeiling??e.reasoningMode;return Pe(Ee({...e,reasoningMode:t,extensions:te(e.extensions)}))}}catch{}return{}}o(w,"loadConfig");var M=f.join(S,"config.example.jsonc"),Re=`// KodaX example configuration \u2014 copy what you need into config.json (in this same
+// folder). config.json must be STRICT JSON: no comments, no trailing commas. Most
+// settings also have a semantic KODAX_* env counterpart that overrides the file.
+// Priority: explicit option > environment > config.json > default. Delete anything
+// you don't use; everything here is optional.
+{
+  // Default provider + model. Override live with /provider and /model.
+  // "provider": "deepseek",
+  // "model": "deepseek-v4",
+
+  // Task runtime: "embedded" (default) or shared local "daemon".
+  // "runtimeMode": "embedded",
+
+  // Reasoning effort for normal turns: off | auto | low | medium | high | xhigh | max.
+  // "effort": "high",
+
+  // Permission mode: "accept-edits" | "plan" | "auto".
+  // "permissionMode": "accept-edits",
+
+  // Custom providers \u2014 point KodaX at an OpenAI/Anthropic-compatible endpoint.
+  // "customProviders": [
+  //   {
+  //     "name": "my-relay",              // unique; do NOT reuse a built-in provider name
+  //     "protocol": "openai",            // "openai" or "anthropic" = the wire format the endpoint speaks
+  //     "baseUrl": "https://api.example.com/v1",
+  //     "apiKeyEnv": "MY_RELAY_API_KEY", // env var that holds the key (never put the key here)
+  //     "model": "deepseek/deepseek-v4",
+  //     "models": ["deepseek/deepseek-v4"],
+  //
+  //     // --- Thinking / reasoning (optional) ---
+  //     // For most NON-Claude models this single line is all you need:
+  //     "supportsThinking": true
+  //     //   openai-compat  : KodaX sends no thinking toggle and just shows whatever
+  //     //                    reasoning the model emits (deepseek/qwen/etc. via relays).
+  //     //   anthropic-compat: KodaX sends thinking:{type:"enabled"} \u2014 what the Anthropic
+  //     //                    endpoints of zhipu / kimi / minimax / deepseek expect.
+  //     //
+  //     // openai-compat MULTI-TURN: some models (notably DeepSeek V4) reject later turns
+  //     // whose history drops the previous reasoning_content. If thinking shows on turn 1
+  //     // but turn 2 errors, also set: "replayReasoningContent": true
+  //     //
+  //     // To expose a TUNABLE effort level, use "reasoning" instead. Include "off" to
+  //     // allow disabling thinking:
+  //     // "reasoning": { "efforts": ["off", "low", "high"], "default": "high" }
+  //     //
+  //     // Pointing anthropic-compat at REAL Claude (4.6+)? Claude needs ADAPTIVE
+  //     // thinking, not the enable toggle \u2014 set instead:
+  //     // "reasoningCapability": "native-adaptive"
+  //   }
+  // ],
+
+  // MCP servers (stdio or remote). See the /mcp command and manual topic "mcp".
+  // "mcpServers": {}
+}
+`;function ct(){try{return c.existsSync(d)||c.existsSync(M)?void 0:(c.mkdirSync(S,{recursive:!0}),c.writeFileSync(M,Re,"utf-8"),M)}catch{return}}o(ct,"ensureExampleConfigFile");var b=new Map;function Ae(e,t){let n=process.env[e],r=b.get(e),i=r!==void 0&&n===r;if(n!==void 0&&!i){b.delete(e);return}if(t===void 0){i&&delete process.env[e],b.delete(e);return}process.env[e]=t,b.set(e,t)}o(Ae,"projectConfigEnvironment");var oe=[{configPath:"streamIdleTimeoutMs",env:"KODAX_STREAM_IDLE_TIMEOUT_MS",value:o(e=>v(e.streamIdleTimeoutMs),"value")},{configPath:"repoIntelligenceMode",env:"KODAX_REPO_INTELLIGENCE",value:o(e=>e.repoIntelligenceMode,"value")},{configPath:"repoIntelligenceTrace",env:"KODAX_REPO_INTELLIGENCE_TRACE",value:o(e=>h(e.repoIntelligenceTrace),"value")},{configPath:"verifierLog",env:"KODAX_VERIFIER_LOG",value:o(e=>h(e.verifierLog),"value")},{configPath:"stallLog",env:"KODAX_STALL_LOG",value:o(e=>h(e.stallLog),"value")},{configPath:"fallbackProviders",env:"KODAX_FALLBACK_PROVIDERS",value:o(e=>Le(e.fallbackProviders),"value")},{configPath:"fastProvider",env:"KODAX_FAST_PROVIDER",value:o(e=>m(e.fastProvider),"value")},{configPath:"fastModel",env:"KODAX_FAST_MODEL",value:o(e=>m(e.fastModel),"value")},{configPath:"deepProvider",env:"KODAX_DEEP_PROVIDER",value:o(e=>m(e.deepProvider),"value")},{configPath:"deepModel",env:"KODAX_DEEP_MODEL",value:o(e=>m(e.deepModel),"value")},{configPath:"provider",env:"KODAX_PROVIDER",value:o(e=>m(e.provider),"value")},{configPath:"effort",env:"KODAX_EFFORT",value:o(e=>m(e.effort),"value")},{configPath:"runtimeMode",env:"KODAX_RUNTIME_MODE",value:o(e=>e.runtimeMode,"value")},{configPath:"sessionRetentionDays",env:"KODAX_SESSION_RETENTION_DAYS",value:o(e=>v(e.sessionRetentionDays),"value")},{configPath:"maxOutputTokens",env:"KODAX_MAX_OUTPUT_TOKENS",value:o(e=>v(e.maxOutputTokens),"value")},{configPath:"disablePromptCache",env:"KODAX_DISABLE_PROMPT_CACHE",value:o(e=>h(e.disablePromptCache),"value")},{configPath:"lsp",env:"KODAX_LSP",value:o(e=>h(e.lsp),"value")},{configPath:"lspAutoDownload",env:"KODAX_LSP_DOWNLOAD",value:o(e=>h(e.lspAutoDownload),"value")},{configPath:"acpLogLevel",env:"KODAX_ACP_LOG",value:o(e=>m(e.acpLogLevel),"value")},{configPath:"repoIntelligence.toolWaitMs",env:"KODAX_REPO_INTELLIGENCE_TOOL_WAIT_MS",value:o(e=>v(e.repoIntelligence?.toolWaitMs),"value")},{configPath:"repoIntelligence.workerTimeoutMs",env:"KODAX_REPO_INTELLIGENCE_WORKER_TIMEOUT_MS",value:o(e=>v(e.repoIntelligence?.workerTimeoutMs),"value")},{configPath:"repoIntelligence.workerOldSpaceMb",env:"KODAX_REPO_INTELLIGENCE_WORKER_OLD_SPACE_MB",value:o(e=>v(e.repoIntelligence?.workerOldSpaceMb),"value")},{configPath:"repoIntelligence.storageDir",env:"KODAX_REPO_INTELLIGENCE_STORAGE_DIR",value:o(e=>m(e.repoIntelligence?.storageDir),"value")},{configPath:"workflow.maxConcurrency",env:"KODAX_WORKFLOW_MAX_CONCURRENCY",value:o(e=>v(e.workflow?.maxConcurrency),"value")}];function Ie(e){for(let t of oe)Ae(t.env,t.value(e))}o(Ie,"applyConfigSurfaceBridges");function m(e){return e?.trim()||void 0}o(m,"normalizedConfigString");function v(e){return typeof e=="number"&&Number.isFinite(e)?String(e):void 0}o(v,"configNumberString");function h(e){return e===void 0?void 0:e?"1":"0"}o(h,"configBooleanString");function Le(e){return e?.filter(t=>t.trim().length>0).join(",")}o(Le,"configStringList");var lt=[...oe.map(({configPath:e,env:t})=>({configPath:e,env:t}))];function Me(e){Ie(e)}o(Me,"applyConfigEnvironment");function ut(){he();let e=w();return Me(e),ye(e),Q(e.locale),e}o(ut,"prepareRuntimeConfig");function ft(e){let n={...w(),...e},r=te(n.extensions);r!==void 0&&(n.extensions=r);for(let i of Object.keys(e))e[i]===void 0&&delete n[i];c.mkdirSync(f.dirname(d),{recursive:!0}),c.writeFileSync(d,JSON.stringify(n,null,2))}o(ft,"saveConfig");function dt(e,t,n){return e.effort!==void 0||k(n).kind==="value"||t.effort!==void 0}o(dt,"resolveInitialEffortOverride");function g(e){return e?.trim()?e:void 0}o(g,"nonEmptySelection");function pt(e){return g(e.explicitProvider)??g(e.environmentProvider)??g(e.configuredProvider)??e.defaultProvider}o(pt,"resolveRuntimeProviderSelection");function mt(e){let t=g(e.explicitModel);if(t)return t;let n=g(e.configuredModel);if(!n)return;let r=g(e.explicitProvider)??g(e.environmentProvider);return r?g(e.configuredProvider)===r?n:void 0:n}o(mt,"resolveRuntimeModelSelection");function gt(e){if(e.explicitEffort!==void 0)return x(e.explicitEffort);let t=k(e.environmentEffort);return t.kind==="value"?t.value:e.configuredEffort===void 0?void 0:x(e.configuredEffort)}o(gt,"resolveRuntimeEffortSelection");function De(e){return e.permissionMode==="plan"&&e.effortOverride!==!0&&e.planModeEffort!==void 0?e.planModeEffort:e.effort}o(De,"resolvePermissionModeEffort");async function vt(e){try{let{stdout:t}=await de("git rev-parse --show-toplevel",{cwd:e});return t.trim()}catch{return null}}o(vt,"getGitRoot");function Te(e){switch(e){case"builtin":return"Built-in";case"runtime":return"Runtime extension";case"custom":return"Custom config";default:return"Unknown"}}o(Te,"formatProviderSourceKind");function ht(e){let t=e.transport==="cli-bridge"?"CLI bridge":"Native API",n=e.conversationSemantics==="last-user-message"?"latest-user-message only":"full conversation history";return[`Source: ${Te(e.sourceKind)}`,`Transport: ${t}`,`Conversation semantics: ${n}`,`Context fidelity: ${e.contextFidelity}`,`Tool calling: ${e.toolCallingFidelity}`,`Session behavior: ${e.sessionSupport}`,`Long-running support: ${e.longRunningSupport}`,`Evidence-heavy flows: ${e.evidenceSupport}`,`Multimodal support: ${e.multimodalSupport}`,`MCP support: ${e.mcpSupport}`,`Reasoning control: ${ke(e.reasoningCapability)}`]}o(ht,"formatProviderCapabilityDetailLines");function yt(e,t,n){return[{label:"General coding",hints:{}},{label:"Evidence-heavy review",hints:{evidenceHeavy:!0}},{label:"Long-running task",hints:{longRunning:!0}}].map(i=>({label:i.label,decision:Ce(e,t,n,i.hints)})).filter(i=>i.decision!==null)}o(yt,"getProviderCommonPolicyScenarios");var Z=.5,ee=0,P={locked:!1,queue:[]};async function Et(e){for(;P.locked;)await new Promise(t=>P.queue.push(t));P.locked=!0;try{let t=(Date.now()-ee)/1e3;t<Z&&await new Promise(r=>setTimeout(r,(Z-t)*1e3));let n=await e();return ee=Date.now(),n}finally{P.locked=!1;let t=P.queue.shift();t&&t()}}o(Et,"rateLimitedCall");export{Ne as a,S as b,He as c,d,qe as e,ve as f,Je as g,ye as h,be as i,Ye as j,_e as k,Se as l,Oe as m,we as n,Qe as o,Ce as p,Ze as q,et as r,y as s,tt as t,nt as u,ot as v,rt as w,ke as x,it as y,st as z,at as A,w as B,M as C,ct as D,lt as E,Me as F,ut as G,ft as H,dt as I,pt as J,mt as K,gt as L,De as M,vt as N,Te as O,ht as P,yt as Q,Et as R};

package/dist/chunks/{chunk-L3MF5V64.js → chunk-CW32NQFO.js}

@@ -1,2 +1,2 @@
 // @kodax-ai/kodax — bundled distribution. See docs/ADR.md ADR-022 + ADR-024.
-import{wa as e}from"./chunk-UGTK2JIJ.js";import{a as n}from"./chunk-V4WSBIXB.js";import{readFile as i}from"fs/promises";var c={enabled:!0,triggerPercent:75};async function g(o){let t=e("config.json");try{let r=await a(t);if(r?.compaction)return{...c,...r.compaction}}catch{}return c}n(g,"loadCompactionConfig");async function a(o){try{let t=await i(o,"utf-8");return JSON.parse(t)}catch{return null}}n(a,"readConfigFile");export{g as a};
+import{za as e}from"./chunk-NVDK375I.js";import{a as n}from"./chunk-ONUPGMER.js";import{readFile as i}from"fs/promises";var c={enabled:!0,triggerPercent:75};async function g(o){let t=e("config.json");try{let r=await a(t);if(r?.compaction)return{...c,...r.compaction}}catch{}return c}n(g,"loadCompactionConfig");async function a(o){try{let t=await i(o,"utf-8");return JSON.parse(t)}catch{return null}}n(a,"readConfigFile");export{g as a};