@kodax-ai/kodax 0.7.96 → 0.7.97-alpha.2

package/CHANGELOG.md

@@ -8,6 +8,92 @@ All notable changes to this project will be documented in this file.
 
 ---
 
+## [0.7.97-alpha.2] - 2026-10-10
+
+Second alpha of the v0.7.97 line: completes the FEATURE_298 product seams
+embedders need to run the client inside a trusted shell (Space). Execution
+authorization moves to the trusted Main process, every provider wire request
+carries its attribution, and full exits become verifiable. Every
+v0.7.96 stable and v0.7.97-alpha.1 contract is retained. npm publication
+remains a manual maintainer action.
+
+### Added
+
+- Trusted Main execution authorization: `connectKodaXClient` /
+  `ensureKodaXClient` accept an `authorizeExecution(request, services)`
+  callback that runs only in the trusted Main process (Host capability
+  `productExecutionAuthorization:1`; older Hosts reject it instead of
+  silently dropping bindings). It registers scoped credential and hostTools
+  leases and attaches non-secret bindings per operation kind — input,
+  command, review, agents_lean, tool, workflow, agent_spawn, agent_followup,
+  and manual compaction. Queued consumes bind at consumption time, steers
+  keep the target Run's authorization, redirects carry their own, and
+  different authorizations never merge or widen.
+- Provider request attribution: every provider wire request carries its
+  execution identity and route so hosts and embedders can observe which
+  authorization issued it.
+- Client lifecycle and exit: `lifecycle.requestExit` settles client work and
+  records durable exit receipts that `readKodaXClientExits` verifies after
+  reconnect; full exits no longer rely on disconnect side effects.
+- Host surfaces for embedders: an execution facts store and per-session
+  statistics exposed through the daemon, and a bundled product-exit smoke
+  joined the release gates.
+
+---
+
+## [0.7.97-alpha.1] - 2026-10-08
+
+First alpha of the v0.7.97 line: FEATURE_298's unified product Host and
+client contract. The interactive product pins to the independent Host, one
+shared session contract carries data, control, and information semantics to
+every consumer, and execution funnels through one prepared action. Every
+v0.7.96 stable contract is retained. npm publication remains a manual
+maintainer action.
+
+### Added
+
+- Shared product session contract and SDK entry: `KodaXProductClient`
+  through `/client` exposes sessions, goals, notices, paged history reads,
+  and Host-estimated token accounting to product consumers (T01, T09, T32).
+- The interactive REPL pins to the independent Host: session-command
+  mutations, `/compact`, `/goal`, full-text queue retention with atomic
+  pull-back, prompt input artifacts, and canonical session writes route
+  through the Host plane (T27, T34).
+- Host-owned planes replace client-side reimplementations: queued inputs
+  with batching and withdrawal (T06), steer/redirect/explicit-stop delivery
+  with required target runs (T07), one permission authority (T14), skills
+  preparation expanded at consumption (T37), declarative workflow start and
+  control operations (T22), memory management (T36), per-session MCP
+  persistence with typed catalogs (T12), A2A serving from bootstrap listen
+  config (T21), agent registry and Actor collaboration (T30), invocations
+  preparation over RPC for all interactive faces (T37), session derivation
+  by fork or deterministic recovery seed (T10), lineage selection/labels/
+  rewind (T11), and conservative legacy-run reads with event repair (T33).
+
+### Fixed
+
+- Preserve canonical history and ordinary browsing: complete canonical items
+  restore before identity assignment, reverse wheel input routes from frozen
+  windows, browse waiting is bounded and cancellable, partial pages keep the
+  final answer after older tools, and quoted managed protocol markers no
+  longer truncate ordinary assistant answers (Issues 344-349).
+- Host command failures stay visible with their feedback, late observation
+  cleanup keeps its diagnostics, and Host message counts drive `/new`.
+- Frontmatter hooks execute on Linux: the default hook contract no longer
+  pairs the bash contract with `/bin/sh`, which is dash on Debian/Ubuntu and
+  rejected every hook at shell environment resolution (Issue 354).
+- Crash recovery proceeds after a `SIGKILL`ed daemon on Linux: a zombie pid
+  waiting for its parent to reap it is no longer classified as a live
+  competing owner (Issue 355).
+- Release validation hardened the interactive fixtures (CI static-output
+  detection, learning-review request classification), raised the
+  machine-relative long-line layout budget on CI evidence (Issues 356-358;
+  358 remains open for profiling), and aligned the release binary provider
+  smoke with Host-owned execution by seeding every provider's key env per
+  probe.
+
+---
+
 ## [0.7.96] - 2026-10-01
 
 Stable release of the v0.7.96 line, finalizing the fourteen release

package/README.md

@@ -424,21 +424,30 @@ const result = await runKodaX(
 
 ## 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.
+For shared Sessions, use `KodaXProductClient` from `@kodax-ai/kodax/client`.
+The Host owns execution, settings and persistence; the UI submits inputs,
+answers Host interactions and replaces its display from `sessions.observe`.
+See the [Client contract](docs/CLIENT_CONTRACT.md), [SDK migration guide](docs/SDK_MIGRATION.md),
+and [integration example](public_docs/sdk/embedder-guide.md#product-client-integration).
 
 ```ts
-import { createKodaXRuntime } from '@kodax-ai/kodax/runtime';
-
-const isolated = await createKodaXRuntime({
-  mode: 'embedded',
-  isolation: 'worker',
-  requirements: { hardDispose: true },
-});
+import { ensureKodaXClient } from '@kodax-ai/kodax/client';
+
+const client = await ensureKodaXClient();
+try {
+  const sessions = await client.sessions.list();
+  process.stdout.write(`Sessions: ${sessions.length}\n`);
+} finally {
+  await client.disconnect(); // Shared Host and Runs remain alive.
+}
 ```
 
+`connectKodaXClient` attaches without starting or replacing a Host. The Node
+connector does not provide browser HTTP/WebSocket transport. The retained
+`/runtime` inline/daemon APIs are for explicit low-level Host integration;
+Worker-hosted embedded Runtime is removed. The following structured-failure
+reference is scoped to that low-level API, not fields promised by Product Client.
+
 ### Structured Runtime failures
 
 Since v0.7.96, when Runtime has a structured failure fact, failed/cancelled runs
@@ -470,47 +479,21 @@ collections, URLs, full local paths, stacks, or raw `Error` objects into
 See [Structured Runtime failures](public_docs/sdk/embedder-guide.md#structured-credential-safe-runtime-failures)
 for the field contract, taxonomy, migration guidance, and security boundary.
 
-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.
+The product CLI uses the shared Host; `--runtime-mode`, `KODAX_RUNTIME_MODE`
+and the `runtimeMode` config key are removed. Explicit low-level inline
+embedding retains private ownership, while daemon clients detach independently.
+Worker-hosted embedded Runtime is no longer an option.
 
 ```bash
 kodax daemon start
+kodax -p "Review this repository"
 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 use the exact
-resolved `KODAX_HOME` (normally `<OS user home>/.kodax`), so CLI and SDK clients
-converge on the same local daemon even when `KODAX_HOME` is an arbitrary custom
-directory. The high-level `createKodaXRuntime({ mode: 'daemon' })` API starts or
-reuses that daemon unless you pass an explicit endpoint/transport or
-`autoStartDaemon: false`. An explicit `--home <dir>` or `homeDir` selects the
-isolated `<dir>/.kodax` namespace for tests, CI, or project-local experiments.
+Tests that start an isolated Host must close that exact Host after its work has
+settled, before removing its temporary home. Never stop arbitrary Node processes.
+With no explicit home, CLI and SDK use the resolved `KODAX_HOME`; explicit
+`homeDir` / `--home` selects a base directory containing `.kodax`.
 
 **v0.7.71 packaged Electron patch:** packaged/asar Electron hosts can use daemon
 auto-start without relaunching the GUI. `ELECTRON_RUN_AS_NODE` is limited to a
@@ -616,7 +599,7 @@ FEATURE_280 was explicitly rescheduled to v0.7.81 (then to v0.7.86 on
 Issue 256 was explicitly rescheduled to v0.7.84 and is likewise not represented
 as shipped by this release.
 
-**v0.7.80 hardening release:** The CLI honors `worker.configuredA2A` in
+**v0.7.80 hardening release:** The CLI honored `worker.configuredA2A` in
 `~/.kodax/config.json`: the embedded Runtime becomes Worker-hosted and loads
 the configured A2A plane inside the Worker owner, so configured outbound
 Agents appear as `external:<name>` in `list_dispatchable_agents` and can be
@@ -786,6 +769,30 @@ provider's model, REPL `/compact` clears the UI only after a durable save, and
 successful reports carry bounded `summaryRequests` plus `commitMs` per
 physical summary call.
 
+**v0.7.97-alpha.2 release:** Completes the FEATURE_298 product seams
+embedders need to run the client inside a trusted shell (Space).
+`connectKodaXClient`/`ensureKodaXClient` accept a trusted
+`authorizeExecution` callback that registers scoped credential and hostTools
+leases and attaches non-secret bindings per operation kind (queued consumes
+bind at consumption, steers keep the target Run's authorization, redirects
+carry their own); every provider wire request carries its execution
+attribution; `lifecycle.requestExit` settles client work and records
+durable exit receipts that `readKodaXClientExits` verifies; and the Host
+exposes execution facts and per-session statistics. See
+[docs/SPACE_SDK_SEAMS.md](docs/SPACE_SDK_SEAMS.md). Every v0.7.96 stable
+and v0.7.97-alpha.1 contract is retained.
+
+**v0.7.97-alpha.1 release:** First alpha of the v0.7.97 line — FEATURE_298's
+unified product Host and client contract. The interactive REPL pins to the
+independent Host; the shared product session contract (`KodaXProductClient`
+through `/client`) carries sessions, goals, notices, paged history, queued
+inputs with batching and withdrawal, and the steer/redirect/stop delivery
+distinction; one permission authority, skills, workflows, memory, per-session
+MCP persistence, and A2A serving become Host-owned; sessions derive by fork
+or deterministic recovery seed; and runtime read/write gaps close (Issues
+344-349). Every v0.7.96 stable contract is retained; cross-platform manual
+acceptance remains open.
+
 **v0.7.96 stable release:** The stable release of the v0.7.96 line,
 finalizing the fourteen release candidates: trusted text transactions and
 platform shell containment across Windows, Linux, and macOS; Windows daemon
@@ -1285,10 +1292,10 @@ effective draft after streaming and reconnect while raw journals retain the
 complete audit trail. They must not replay provider recovery checkpoints or
 deduplicate text heuristically.
 
-For the full host-integration contract, including inline/Worker/daemon selection,
+For the full host-integration contract, including Product Client and explicit inline/daemon ownership,
 multi-client permission handling, config/catalog/MCP admin APIs, artifacts,
 context diagnostics, and daemon protocol schemas, see
-[public_docs/sdk/embedder-guide.md §17](public_docs/sdk/embedder-guide.md#17-runtime-sdk-worker-isolation-and-local-daemon-feature_253-feature_257).
+[public_docs/sdk/embedder-guide.md §17](public_docs/sdk/embedder-guide.md#17-runtime-sdk-and-local-daemon-feature_253-feature_257).
 
 The Space/IDE shared-daemon contract is documented in
 [SDK Embedder Guide section 23](public_docs/sdk/embedder-guide.md#23-shared-coder-daemon-for-space-and-ide-hosts-feature_269-v0769).
@@ -1319,7 +1326,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 12 SDK subpath exports (`/agent`, `/llm`, `/coding`, `/media`, `/repl`, `/skills`, `/mcp`, `/session`, `/runtime`, `/sandbox`, `/a2a`, `/experimental-memory`; 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; the current source packages them as a single bundled npm package `@kodax-ai/kodax` with 13 SDK subpath exports (`/agent`, `/llm`, `/coding`, `/media`, `/repl`, `/skills`, `/mcp`, `/session`, `/client`, `/runtime`, `/sandbox`, `/a2a`, `/experimental-memory`; ADR-024 + ADR-032 + ADR-038, with ADR-036 consolidation):
 
 ```
 KodaX/
@@ -1394,9 +1401,9 @@ 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 12 SDK subpaths (what SDK consumers `import` from). The subpaths are split into two roles:
+- **Current packaged exports** (not a claim of npm availability): a single bundled package `@kodax-ai/kodax` with 13 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.
-  - **Integration and narrow subpaths** (`/media`, `/skills`, `/mcp`, `/session`, `/runtime`, `/sandbox`, `/a2a`, `/experimental-memory`) — focused host surfaces. `/a2a` composes the neutral F258 plane with the Runtime facade; it does not add A2A wire types to `/agent`.
+  - **Integration and narrow subpaths** (`/media`, `/skills`, `/mcp`, `/session`, `/client`, `/runtime`, `/sandbox`, `/a2a`, `/experimental-memory`) — focused host surfaces. `/a2a` composes the neutral F258 plane with the Runtime facade; it does not add A2A wire types to `/agent`.
 
 | Source package | npm subpath | Type | What you get | Example consumer |
 |---|---|---|---|---|
@@ -1409,7 +1416,8 @@ KodaX has two layers that consumers should understand separately:
 | `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 |
+| `src`             | `@kodax-ai/kodax/client` | Product API | Shared Host connection and `KodaXProductClient` contract | TUI, desktop/IDE and automation applications |
+| `src`             | `@kodax-ai/kodax/runtime` | Host API | Explicit inline/daemon runtime facade, sessions/runs/events/permissions/catalog/MCP/artifacts/diagnostics/external agents, daemon protocol schema (10 exports) | Trusted Host integration |
 | `src`             | `@kodax-ai/kodax/sandbox` | Host API | Explicit ASRT capability/doctor/setup and host-owned contained command execution; unavailability never means silent ordinary execution | SDK hosts that need standalone process containment |
 | `src`             | `@kodax-ai/kodax/a2a` | Integration edge | A2A 1.0 Agent Card discovery, JSON-RPC/SSE F258 executor, safe fetch policy, and authenticated Runtime-backed Agent server | Agent orchestrators and KodaX hosts |
 
@@ -1532,10 +1540,11 @@ later re-enable. Private-address access and non-loopback plaintext HTTP are
 independent, persisted, default-deny permissions (`--allow-private` and
 `--allow-insecure-http`); exact loopback HTTP remains available without either.
 OAuth token endpoints retain their stricter HTTPS-or-exact-loopback rule.
-Worker-hosted SDK Runtimes can load this same configured plane inside the Worker
-owner with `worker: { configuredA2A: true }`. The CLI honors the same opt-in
-from `~/.kodax/config.json` (`"worker": { "configuredA2A": true }`) by creating
-a Worker-hosted embedded Runtime that loads the configured A2A plane. `a2a serve` loads
+SDK hosts load this same configured plane by wiring
+`createConfiguredA2ARuntimeIntegration({ configHome })` and passing its
+`runtimeOptions` as `externalAgents` — the CLI does this for its embedded
+sessions and the daemon Host it launches, and the `worker.configuredA2A` opt-in
+was removed with the Worker facade in v0.7.97. `a2a serve` loads
 its configured MCP/Extension capability surface before listening and pins that
 execution authority; it hot-reloads publication, authentication, and limits.
 
@@ -1623,7 +1632,6 @@ dist/binary/linux-x64/
 ├── 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
 ```
 
@@ -1635,6 +1643,10 @@ See [docs/release.md](docs/release.md) for full details on build flags, archive
 
 ### As Library
 
+For shared-Session applications, use the [Product Client integration](public_docs/sdk/embedder-guide.md#product-client-integration)
+and [migration guide](docs/SDK_MIGRATION.md). The example below is independent
+in-process coding library usage; it is not the product UI contract.
+
 ```bash
 npm install @kodax-ai/kodax
 ```
@@ -1662,6 +1674,7 @@ For smaller surface and tree-shake-friendly imports, the SDK is also exposed via
 
 ```typescript
 import { Runner } from '@kodax-ai/kodax/agent';                // agent runtime
+import { ensureKodaXClient } from '@kodax-ai/kodax/client';     // shared product Client
 import { getProvider } from '@kodax-ai/kodax/llm';              // LLM abstraction (16 aliases)
 import { runKodaX } from '@kodax-ai/kodax/coding';              // coding tools + prompts
 import { createImageArtifactFromPath } from '@kodax-ai/kodax/media'; // input artifacts
@@ -1675,9 +1688,9 @@ import { createKodaXA2AServer } from '@kodax-ai/kodax/a2a';    // A2A 1.0 client
 import { createMemoryAgent } from '@kodax-ai/kodax/experimental-memory'; // opt-in memory SDK
 ```
 
-All 13 SDK entries (root + 12 subpaths) share internal code via ESM chunk splitting — importing from `/agent` does not pull in `/repl`'s Ink + React surface.
+All 14 SDK entries (root + 13 subpaths, including `/client`) 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,
+For the product contract and separate low-level inline/daemon ownership,
 external-agent registration and task control, session cursor pagination, workflow
 model-tier routing, and efficiency telemetry — see the
 [SDK Embedder Integration Guide](public_docs/sdk/embedder-guide.md).
@@ -1926,6 +1939,10 @@ stays silent.
 
 ## Advanced Library Usage
 
+These examples describe independent coding-library ownership. Shared product
+clients use `/client`; see the [migration guide](docs/SDK_MIGRATION.md) before
+adapting these callbacks or storage examples into a UI.
+
 #### Simple Mode (runKodaX)
 
 ```typescript
@@ -2009,7 +2026,11 @@ await runKodaX({
 
 ## SDK Usage
 
-KodaX ships as a single npm package `@kodax-ai/kodax` with 12 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` + v0.7.68 `/experimental-memory` + v0.7.69 `/a2a` + v0.7.78 `/sandbox`). Each subpath is tree-shake-friendly so consumers pull only what they need:
+This development tree exposes 13 SDK subpaths plus the root. Shared product
+applications use `@kodax-ai/kodax/client`; independent libraries and trusted Host
+APIs remain available through the other subpaths. See the [Client contract](docs/CLIENT_CONTRACT.md)
+and [SDK migration guide](docs/SDK_MIGRATION.md). The package version is still
+`0.7.96-rc.11`; npm publication is separate from the `v0.7.97` design target.
 
 ```bash
 npm install @kodax-ai/kodax
@@ -2017,6 +2038,7 @@ npm install @kodax-ai/kodax
 
 ```typescript
 import { runKodaX } from '@kodax-ai/kodax';                       // root: CLI helpers + runKodaX
+import { ensureKodaXClient, connectKodaXClient } from '@kodax-ai/kodax/client'; // shared product contract
 import { Runner, runFanOut } from '@kodax-ai/kodax/agent';        // generic Agent framework
 import { getProvider } from '@kodax-ai/kodax/llm';                // 16-alias LLM abstraction
 import { KODAX_TOOLS } from '@kodax-ai/kodax/coding';             // tools + prompts + agent loop
@@ -2186,7 +2208,8 @@ 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 |
+| Shared Session application | `@kodax-ai/kodax/client` | Unified product intent, observation, interactions and history |
+| Trusted Runtime host | `@kodax-ai/kodax/runtime` | Explicit embedding, credentials/Host Tools and diagnostics |
 | Experimental governed memory | `@kodax-ai/kodax/experimental-memory` | Governed `MemoryAgent` list/remember/forget and scoped `MemorySession` recall/outcome contracts |
 
 ---

package/README_CN.md

@@ -82,18 +82,23 @@ macOS/Linux 会报告 Seatbelt/bubblewrap 所需依赖。拒绝 UAC 或缺少依
 
 ## Runtime SDK 与共享 daemon
 
-`@kodax-ai/kodax/runtime` 支持 inline、Worker 和本机共享 daemon。FEATURE_269
-让 CLI、Space、IDE 与其他本地 SDK 客户端可以原子加入同一个 Coder
-session/run，共享 transcript、Todo、tool、AskUser、permission、队列与唯一终态。
-daemon mutation 使用持久 operation identity 和 revision CAS；崩溃后不会盲目重放
-可能已有副作用的 provider、run 或 Host Tool 调用。
-
-Space 的 provider credential 仍由 OS keychain 持有，只通过 run/provider-scoped
-broker 使用；Space Artifact/Office/Control 只通过显式绑定到该 run 的 Host Tool
-lease 暴露。CLI run 不会因为 Space 后来加入而继承这些能力。Partner 继续使用独立
-data/session root 下的 inline Runtime，不参与 Coder owner fence。capability 缺失时必须
-fail closed，不能静默退回 inline Coder。完整接入说明见
-[SDK Embedder Guide §23](public_docs/sdk/embedder-guide.md#23-shared-coder-daemon-for-space-and-ide-hosts-feature_269-v0769)。
+产品接入统一使用 `@kodax-ai/kodax/client` 的 `KodaXProductClient`。Host 负责执行、设置和存储，TUI、SDK 应用及其他 UI 提交意图并观察同一事实。详见[迁移指南](docs/SDK_MIGRATION.md)、[Client 契约](docs/CLIENT_CONTRACT.md)和[接入示例](public_docs/sdk/embedder-guide.md#product-client-integration)。
+
+```ts
+import { ensureKodaXClient } from '@kodax-ai/kodax/client';
+
+const client = await ensureKodaXClient();
+try {
+  const sessions = await client.sessions.list();
+  process.stdout.write(`Sessions: ${sessions.length}\n`);
+} finally {
+  await client.disconnect(); // 只断开当前连接，共享 Host 和 Run 继续存在。
+}
+```
+
+`connectKodaXClient` 只连接已有兼容 Host；`ensureKodaXClient` 通过统一启动器启动或正常更新空闲 Host。Node 连接器不提供浏览器 HTTP/WebSocket transport。
+
+底层 `/runtime` 仍支持显式 inline embedded 与 daemon，供受信任宿主处理凭据桥、Host Tools、启动和诊断；Worker-hosted embedded、通用 operation receipt/journal 已移除。不能在产品连接失败时退回私有 Runtime。下方结构化 Runtime 错误说明仅属于底层接口，不能假定 Product Client 暴露相同字段。
 
 ### 结构化且凭据安全的 Runtime 错误
 
@@ -296,6 +301,25 @@ SDK 系统代码契约更新，但没有放宽 shell/sandbox 的 fail-closed 边
 `handleRuntimePermissionRequest()` 管理 SDK 权限 UI，并在 prepared Session 尾部遇到
 `data_changed` 时通过权威 delta 合并恢复；后台持久化失败会显示为诊断，不再静默丢失。
 
+**v0.7.97-alpha.2 发布**：补齐 FEATURE_298 面向嵌入方（Space）的产品接缝——
+在可信壳内运行客户端所需的最后一块。`connectKodaXClient`/`ensureKodaXClient`
+接受仅在可信 Main 进程执行的 `authorizeExecution` 回调，注册 scoped credential
+与 hostTools lease，并按操作种类附加非秘密绑定（排队消费在消费时绑定、steer
+保留目标 Run 的授权、redirect 携带自身授权）；每条 Provider wire request 携带
+其执行归因；`lifecycle.requestExit` 结清客户端工作并记录持久退出回执，由
+`readKodaXClientExits` 在重连后核验；宿主暴露 execution facts 与按会话统计。
+详见 [docs/SPACE_SDK_SEAMS.md](docs/SPACE_SDK_SEAMS.md) 与
+[v0.7.97-alpha.2 发布清单](docs/release.md#v0797-alpha2-release-preparation)。
+所有 v0.7.96 稳定与 v0.7.97-alpha.1 契约全部保留。
+
+**v0.7.97-alpha.1 发布**：v0.7.97 线首个 alpha——FEATURE_298 统一产品宿主
+与客户端契约。交互式 REPL 绑定独立宿主；共享产品会话契约
+（`KodaXProductClient`，经 `/client`）承载会话、目标、通知、分页历史、
+带批量与撤回的排队输入，以及 steer/redirect/stop 投递区分；唯一权限权威、
+技能、工作流、内存、按会话 MCP 持久化与 A2A 服务收归宿主；会话按 fork 或
+确定性恢复种子派生；运行时读写缺口闭合（Issues 344-349）。所有 v0.7.96
+稳定契约全部保留；跨平台人工验收保持开放。
+
 **v0.7.96 正式版发布**：v0.7.96 线的正式版本，定格十四个发布候选的全部
 成果：跨 Windows/Linux/macOS 的受信文本事务与平台 Shell 隔离；Windows
 daemon 生命周期仲裁与不阻塞的不确定 Shell 清理；按回合匹配的中断 Run 跨
@@ -478,7 +502,7 @@ native 文本权威改在摘要固定的 `manylinux_2_28` 构建器中编译，
 scope 在 SDK、Agent 摘要、CLI 与 Runtime Worker 请求间共享，保留结构化的 Child Agent Provider
 失败信息，精确遵循 run-scoped 凭据校验，并为严格 vLLM 网关省略空 `tools` 数组（Issues 329-332）。
 npm 发布仍由
-维护者手动执行。详见 [v0.7.96 正式版发布清单](docs/release.md#v0796-release-preparation)。
+维护者手动执行。详见 [v0.7.97-alpha.1 发布清单](docs/release.md#v0797-alpha1-release-preparation)。
 
 **v0.7.96-alpha.3 发布**：Provider 凭据成为惰性、受限、可撤销的能力（ADR-068）。v2
 credential broker 将 Provider 密钥保留在 OS keychain，按每次 wire call、为单一封闭
@@ -876,6 +900,8 @@ kodax "Review this repository and summarize the architecture"
 
 ### 4. 作为库使用
 
+共享 Session 的 TUI、桌面/IDE 和自动化应用应使用 `@kodax-ai/kodax/client`，见[迁移指南](docs/SDK_MIGRATION.md)和[完整 Client 契约](docs/CLIENT_CONTRACT.md)。以下 `runKodaX` 示例属于独立 coding 库，不是产品客户端入口。
+
 ```bash
 npm install @kodax-ai/kodax
 ```
@@ -905,15 +931,15 @@ 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
+import { createKodaXRuntime } from '@kodax-ai/kodax/runtime';   // inline/daemon 宿主 API
 import { runKodaXSandboxed } from '@kodax-ai/kodax/sandbox';    // 独立 ASRT 受控执行
 import { createKodaXA2AServer } from '@kodax-ai/kodax/a2a';    // A2A 1.0 双向接入
 import { createMemoryAgent } from '@kodax-ai/kodax/experimental-memory'; // opt-in 实验性记忆 SDK
 ```
 
-13 个 SDK 入口（root + 12 subpath）通过 ESM 共享 chunk 复用底层代码 —— 只 import `/agent` 不会把 `/repl` 的 Ink + React 一起拉进来。
+14 个 SDK 入口（root + 13 subpath，包含产品 `/client`）通过 ESM 共享 chunk 复用底层代码 —— 只 import `/agent` 不会把 `/repl` 的 Ink + React 一起拉进来。
 
-完整的宿主集成契约——包括 embedded/Worker/daemon 所有权、外部 Agent 注册与任务控制、session cursor 分页、workflow 模型分层和效率遥测——见 [SDK Embedder Integration Guide](public_docs/sdk/embedder-guide.md)。
+完整的宿主集成契约——包括 inline/daemon 所有权、外部 Agent 注册与任务控制、session cursor 分页、workflow 模型分层和效率遥测——见 [SDK Embedder Integration Guide](public_docs/sdk/embedder-guide.md)。
 
 > **SDK 是 ESM-only**。在 CommonJS 上下文（Electron main 进程、传统 Webpack CJS bundle、`require()` 调用方）必须用 `await import('@kodax-ai/kodax/...')` 代替 `require()`。详见 [public_docs/sdk/embedder-guide.md §5](public_docs/sdk/embedder-guide.md#5-consuming-from-a-commonjs-context-electron-main-cjs-bundles)，含 Electron main 完整 recipe + 为什么大多数 subpath 物理上无法做 dual ESM/CJS bundle。
 
@@ -1056,55 +1082,19 @@ registerCustomProviders([
 await runKodaX({ provider: 'my-openai-compatible' }, '解释这个仓库');
 ```
 
-### 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 故障隔离边界，不是安全沙箱。
+### 6. 统一 Client 与本机 Host
 
-daemon 按设计会持续驻留。测试若自动启动 daemon，删除临时 home 前还必须执行
-`kodax daemon stop --home <目录> --profile <名称>`（或发送已认证的
-`runtime.shutdown`）。不要按进程名批量结束 Node；应先核验命令行和父进程归属。
+当前产品入口采用共享 daemon Host，TUI 和 SDK 产品客户端都通过统一契约提交输入、读取状态、回答交互。`--runtime-mode`、`KODAX_RUNTIME_MODE` 和 config 的 `runtimeMode` 已从产品面移除。
 
 ```bash
 kodax daemon start
+kodax -p "检查这个仓库"
 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 的交付由 Host 串行协调。`after_turn` 可在当前 Run 的安全点交付，不必等整个长任务结束。客户端关闭观察或断开连接不会停止 Run。停止任务使用 `runs.stop` 或 `sessions.cancel`；关闭空闲 Host 才使用 `host.shutdown`/daemon stop。
 
-一个 daemon 可以承载多个 session。不同 session 可以并发运行；同一个 session
-内部仍保持一次只运行一个任务，后续任务按队列执行。多个 `kodax` 进程可以连接
-同一个 daemon，并分别打开或观察不同 session。
+显式独立库嵌入仍可使用 `/runtime` 的 `createKodaXRuntime({mode:'embedded'})`，其 owner 和退出责任属于调用者。这不是 CLI 的可选运行模式，也不是产品客户端的连接失败回退。当前包版本与发布状态见[SDK 迁移指南](docs/SDK_MIGRATION.md)。
 
 ### 7. 打包成单文件二进制（无需 Node）
 
@@ -1131,7 +1121,6 @@ dist/binary/linux-x64/
 ├── 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
 ```
 
@@ -1243,7 +1232,7 @@ kodax --repo-intelligence full --repo-intelligence-trace
 
 ## 仓库结构
 
-KodaX 是基于 npm workspaces 的 TypeScript monorepo，**源码层 4 个 workspace 包**（FEATURE_194 v0.7.43 包合并 — 9 → 4，ADR-036），npm 上以单 bundle 包 `@kodax-ai/kodax` 发布 + 12 个 SDK subpath exports（`/agent`、`/llm`、`/coding`、`/media`、`/repl`、`/skills`、`/mcp`、`/session`、`/runtime`、`/sandbox`、`/a2a`、`/experimental-memory`；ADR-024 + ADR-032 + ADR-038）。核心包：
+KodaX 是基于 npm workspaces 的 TypeScript monorepo，**源码层 4 个 workspace 包**（FEATURE_194 v0.7.43 包合并 — 9 → 4，ADR-036），npm 上以单 bundle 包 `@kodax-ai/kodax` 发布 + 13 个 SDK subpath exports（`/agent`、`/llm`、`/coding`、`/media`、`/repl`、`/skills`、`/mcp`、`/session`、`/client`、`/runtime`、`/sandbox`、`/a2a`、`/experimental-memory`；ADR-024 + ADR-032 + ADR-038）。核心包：
 
 | Workspace 包 | 作用 | 主要依赖 |
 |----|------|---------|
@@ -1259,9 +1248,9 @@ KodaX 是基于 npm workspaces 的 TypeScript monorepo，**源码层 4 个 works
 KodaX 有两层结构，SDK 用户需要分开理解：
 
 - **源码层**：上面 4 个 workspace 包（开发者读代码时看到的物理结构）。
-- **npm 发布层**：单个 bundled 包 `@kodax-ai/kodax`，对外暴露 12 个 SDK subpath（SDK 消费者 `import` 时看到的接口）。subpath 分两种角色：
+- **当前源码打包导出**（不表示已发布到 npm）：单个 bundled 包 `@kodax-ai/kodax`，对外暴露 13 个 SDK subpath（SDK 消费者 `import` 时看到的接口）。subpath 分两种角色：
   - **完整包 subpath**（`/agent`、`/llm`、`/coding`、`/repl`）—— 每个 1:1 对应一个源码包，暴露完整公开 API。
-  - **集成与窄子集 subpath**（`/media`、`/skills`、`/mcp`、`/session`、`/runtime`、`/sandbox`、`/a2a`、`/experimental-memory`）—— 聚焦能力或宿主集成边界；`/experimental-memory` 明确为 opt-in 不稳定接口。
+  - **集成与窄子集 subpath**（`/media`、`/skills`、`/mcp`、`/session`、`/client`、`/runtime`、`/sandbox`、`/a2a`、`/experimental-memory`）—— 聚焦能力或宿主集成边界；`/experimental-memory` 明确为 opt-in 不稳定接口。
 
 | 源码包 | npm subpath | 类型 | 内容 | 典型消费者 |
 |---|---|---|---|---|
@@ -1274,7 +1263,8 @@ KodaX 有两层结构，SDK 用户需要分开理解：
 | `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 |
+| `src`             | `@kodax-ai/kodax/client` | 产品 API | 共享 Host 连接与 `KodaXProductClient` 统一契约 | TUI、桌面/IDE 和自动化应用 |
+| `src`             | `@kodax-ai/kodax/runtime` | 宿主 API | Explicit inline/daemon facade，含 sessions/runs/events/permissions/catalog/MCP/artifacts/diagnostics/外部 Agent 和 daemon schema (10 exports) | 受信任宿主集成 |
 | `src`             | `@kodax-ai/kodax/sandbox` | 宿主 API | 显式 ASRT capability/doctor/setup 与宿主自有受控命令执行；不可用时绝不静默普通执行 | 需要独立进程 containment 的 SDK 宿主 |
 | `src`             | `@kodax-ai/kodax/a2a` | 集成边界 | A2A 1.0 Agent Card 发现、JSON-RPC/SSE F258 executor、安全 fetch 与鉴权 Runtime Agent server | Agent 编排器和 KodaX 宿主 |
 
@@ -1369,10 +1359,10 @@ MCP、A2A、Extension 分别使用 `~/.kodax/integrations/` 下的一个用户
 停用条目可随时重新启用。私网地址访问与非 loopback 明文 HTTP 是两项独立、
 持久化且默认拒绝的权限（`--allow-private` 与 `--allow-insecure-http`）；精确
 loopback HTTP 无需这两项授权。OAuth token endpoint 仍保持更严格的
-HTTPS 或精确 loopback 规则。Worker-hosted SDK Runtime 可通过
-`worker: { configuredA2A: true }` 让 Worker owner 装载同一配置执行平面。
-CLI 同样支持在 `~/.kodax/config.json` 中配置 `"worker": { "configuredA2A": true }`，
-将嵌入式运行时改为 Worker 托管并装载配置的 A2A 执行平面。
+HTTPS 或精确 loopback 规则。SDK 宿主通过 `createConfiguredA2ARuntimeIntegration({ configHome })` 装载同一
+配置执行平面，并把其 `runtimeOptions` 作为 `externalAgents` 传入——CLI 为其嵌入式
+会话和它启动的 daemon Host 完成同样的接线；`worker.configuredA2A` 选项已随
+Worker facade 在 v0.7.97 移除。
 `a2a serve` 会在监听前装载已配置的 MCP/Extension 能力并固定执行权威，同时热加载
 公开信息、鉴权和限额。Agent、Skill、Extension 工具权威、工作区、tool policy
 或任务存储变更必须显式重启服务。
@@ -1430,7 +1420,7 @@ KodaX/                       # 4 workspace packages(FEATURE_194 v0.7.43)
 │   ├── kodax_cli.ts         # CLI 主入口（bin: `kodax`）
 │   └── sdk-*.ts             # SDK subpath 入口 → @kodax-ai/kodax/{agent,llm,coding,media,repl,skills,mcp,session,runtime,sandbox,a2a,experimental-memory}
 ├── scripts/
-│   ├── build-bundle.mjs     # esbuild 单 bundle 多 entry 打包（CLI + root + 12 SDK subpath + chunks）
+│   ├── build-bundle.mjs     # esbuild 单 bundle 多 entry 打包（CLI + root + 13 SDK subpath + chunks）
 │   ├── build-binary.mjs     # Bun --compile 单文件二进制打包
 │   └── release.mjs          # 发布 CI 构建的通用 tarball；本地 --pack-only 保持 private:true
 └── .github/workflows/

package/config-templates/config.example.jsonc

@@ -13,20 +13,6 @@
   //   "deepseek": ["deepseek-flash", "deepseek-v4-pro"]
   // },
 
-  // Interactive Runtime hosting: "embedded" (this process) or "daemon".
-  // "runtimeMode": "embedded",
-
-  // Worker-hosted embedded Runtime options. `configuredA2A` lets a
-  // Worker-hosted embedded Runtime load and reconcile
-  // ~/.kodax/integrations/a2a.json inside the Worker owner, so configured
-  // outbound A2A Agents appear as `external:<name>` and can be dispatched
-  // with spawn_agent. Default inline (non-Worker) CLI sessions already load
-  // the configured A2A plane automatically; this key switches the embedded
-  // session to a Worker-hosted Runtime and loads the plane in that mode.
-  // "worker": {
-  //   "configuredA2A": true
-  // },
-
   // Native model reasoning. `effort` is the preferred explicit depth;
   // `reasoningCeiling` is the session ceiling. `reasoningMode` and `thinking`
   // remain accepted for backward compatibility.

package/dist/chunks/{agent-7N427EVB.js → agent-J7SHFM5N.js}

@@ -1,2 +1,2 @@
 // @kodax-ai/kodax — bundled distribution. See docs/ADR.md ADR-022 + ADR-024.
-import{Fb as k,Va as g,Xa as h,a as c,qa as d,ra as e,sa as f,wb as i,xb as j}from"./chunk-7O2AIFNE.js";import"./chunk-EM4XJBTK.js";import"./chunk-66XN5AFU.js";import"./chunk-C7U542KM.js";import"./chunk-NI7PBPUR.js";import{Rb as a,Sb as b}from"./chunk-WV3DJVW4.js";import"./chunk-DSXUXUZG.js";import"./chunk-HZYRLIOC.js";import"./chunk-ONUPGMER.js";export{e as bucketProviderPayloadSize,g as buildAutoRepoIntelligenceContext,f as checkPromiseSignal,b as cleanupIncompleteToolCalls,h as describeTransientProviderRetry,c as emitResilienceDebug,d as estimateProviderPayloadBytes,k as runKodaX,j as saveRequiredSessionSnapshot,i as saveSessionSnapshot,a as validateAndFixToolHistory};
+import{Ib as k,Xa as g,Za as h,a as c,sa as d,ta as e,ua as f,yb as i,zb as j}from"./chunk-K3DQGSQU.js";import"./chunk-ZZQ4GDVU.js";import"./chunk-4VJMQDTH.js";import"./chunk-F7DHZH6T.js";import"./chunk-5DSUVP46.js";import{Rb as a,Sb as b}from"./chunk-VDGPJQL7.js";import"./chunk-ZPPAT25E.js";import"./chunk-7V2QBZ73.js";import"./chunk-ONUPGMER.js";export{e as bucketProviderPayloadSize,g as buildAutoRepoIntelligenceContext,f as checkPromiseSignal,b as cleanupIncompleteToolCalls,h as describeTransientProviderRetry,c as emitResilienceDebug,d as estimateProviderPayloadBytes,k as runKodaX,j as saveRequiredSessionSnapshot,i as saveSessionSnapshot,a as validateAndFixToolHistory};