@kodax-ai/kodax 0.7.63 → 0.7.66

package/README.md

@@ -296,6 +296,70 @@ 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.
+
+```bash
+kodax daemon start
+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 +373,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 +399,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,7 +448,7 @@ 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.
 
@@ -397,6 +461,7 @@ KodaX has two layers that consumers should understand separately:
 | `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 |
+| `src`             | `@kodax-ai/kodax/runtime` | Host API | Embedded/daemon runtime facade, sessions/runs/events/permissions/catalog/MCP/artifacts/diagnostics, daemon protocol schema | 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.
 
@@ -478,8 +543,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`.
@@ -523,9 +592,10 @@ import { SkillRegistry } from '@kodax-ai/kodax/skills';         // zero-dep skil
 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.
 
 > **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.
 
@@ -812,7 +882,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 +898,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 +1047,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

@@ -344,7 +344,52 @@ 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 故障隔离边界，不是安全沙箱。
+
+```bash
+kodax daemon start
+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 +410,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`。

package/dist/chunks/{agent-SL444XLN.js → agent-KER4WDNO.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-MHRN2LQV.js";import"./chunk-D6QVXQNI.js";import"./chunk-YRBNXFHY.js";import"./chunk-3HKBBY74.js";import"./chunk-O7N22GJ3.js";import{rb as a,sb as b}from"./chunk-TLJGOKBT.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-HK3MHA3K.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-VS4CDDEF.js";import"./chunk-QJVZZSEO.js";import"./chunk-WMIZCY2J.js";import"./chunk-QAQ2HNXD.js";import"./chunk-ALS32RNZ.js";import"./chunk-NBQW7PNZ.js";import"./chunk-MHRN2LQV.js";import"./chunk-D6QVXQNI.js";import"./chunk-YRBNXFHY.js";import"./chunk-3HKBBY74.js";import"./chunk-O7N22GJ3.js";import"./chunk-TLJGOKBT.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};