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

package/CHANGELOG.md

@@ -8,6 +8,106 @@ All notable changes to this project will be documented in this file.
 
 ---
 
+## [0.7.97-alpha.4] - 2026-10-12
+
+Fourth alpha of the v0.7.97 line: FEATURE_301 adds the independent
+`@kodax-ai/artifacts` package — PPTX authoring, bounded editing, and
+current-file visual evidence through LibreOffice/PDF rendering — with an
+optional managed KodaX adapter, and retires the out-of-band Sidecar
+Verifier in favor of evidence-based in-run result review with the
+`visual-review` builtin skill. Every v0.7.96 stable and
+v0.7.97-alpha.1/alpha.2/alpha.3 contract is retained. npm publication
+remains a manual maintainer action.
+
+### Added
+
+- `@kodax-ai/artifacts`: independent optional package for PPTX authoring,
+  bounded editing, and current-file visual evidence; its optional KodaX
+  bridge uses managed permissions, sandbox, and cancellation (FEATURE_301).
+- Managed PPT review loop: native Office and autonomous non-Office PPT
+  validation with rendered-page evidence and bounded edit cycles.
+- `visual-review` builtin skill covering static images/charts, paginated
+  documents/slides/sheets, interactive web/app/terminal/canvas/3D surfaces,
+  and temporal video/animation results; missing capabilities and unchecked
+  scope are reported honestly as unverified.
+
+### Changed
+
+- Main-agent result verification replaces the Sidecar Verifier (ADR
+  2026-10-11): the main agent verifies each requested requirement with
+  actual tool and rendered evidence before delivery, and an ordinary
+  read-only child reviewer may contribute findings within the same Run.
+  Retired: verifier execution, config, live callbacks, the synthetic
+  revision producer, `/verifier-log`, and `KODAX_VERIFIER_*` diagnostics;
+  persisted verifier history readers remain. Stall sidecar, Auto
+  permission reviewer, Bash/sandbox policy, Actor waits, and Stop hooks
+  are unchanged.
+- Bundled skill discovery resolves the packaged `builtin` layout, and
+  provider capability profiles carry the capability snapshot into managed
+  task admission; the release audit now walks the runtime tarball
+  (`audit-runtime-tarball.mjs`).
+- Unified client startup progress: `connectKodaXClient` /
+  `ensureKodaXClient` accept an `onStartupProgress` observer over the
+  pure-data `ClientStartupProgress` contract (checking / starting /
+  upgrading / connecting / ready, with waiting reasons
+  `connected_clients`, `host_starting`, `host_stopping`). Observation is
+  local, never awaited, and observer failures never change the startup
+  result; the CLI drives its loading animation from the same notifications
+  and stays responsive, and the REPL gains an optional `onBeforeRender` to
+  clear the loading display before restoring prompts.
+
+---
+
+## [0.7.97-alpha.3] - 2026-10-10
+
+Third alpha of the v0.7.97 line: trusted Main can now bound Product
+Workflows. `authorizeExecution` may return a `workflowHostPolicy`
+(`maxAgents`, `tokenBudget`) without registering credential or hostTools
+leases; the Host capability moves to `productExecutionAuthorization:2`.
+Ceilings bind to Product Runs including their Workflow children, Workflow
+spawn slots are reserved across concurrent admissions, and output usage is
+published only when every executed round reported it. Every v0.7.96
+stable and v0.7.97-alpha.1/alpha.2 contract is retained. npm publication
+remains a manual maintainer action.
+
+### Added
+
+- Trusted-Main Workflow ceilings: `workflowHostPolicy` (`maxAgents`,
+  `tokenBudget`) on `RuntimeExecutionAuthorization`, accepted policy-only
+  on `/client` inputs, queued consumes, and Skill/command/review derived
+  Runs; rejected on independent Actor admissions; Host capability
+  `productExecutionAuthorization:2`.
+- Workflow `maxAgents` race safety: spawn slots are reserved synchronously
+  across pending backend admissions, so concurrent requests cannot exceed
+  the lifetime cap.
+- Workflow output usage: finalized managed results carry aggregate
+  input/output usage; `outputTokens` is published only when every executed
+  round (including verification repair) reported its output usage.
+
+### Changed
+
+- Product Runs capture the Host `workflow.maxConcurrency` at start and use
+  the Host-owned workflow-runs directory; the client adapter strips forged
+  `workflowHostPolicy` fields from Product payloads.
+
+### Fixed
+
+- Terminal Memory review drains no longer reclaim an unavailable preferred
+  job as backlog and steal startup recovery from the next Run (Issue 362).
+- Clipboard helper input-pipe failures now enter the existing native/tmux/OSC
+  52 fallback instead of crashing mouse copy-on-select (Issue 363).
+- MCP stdio sends observe asynchronous write failures and report them through
+  the awaited send and transport diagnostics; required initialization
+  notifications cannot turn a failed connection into ready (Issue 364).
+- Workflow child budgets retain all reported Provider fallback attempts and
+  requests before a thrown attempt, including truncated continuations. Local
+  accounting reuses normalized request facts, preserves Host observers, and
+  keeps conservative totals when component usage is incomplete (Issue 365).
+- The Host interrupt-fence and statistics fixtures wait for actual Provider entry, observe
+  early Run termination, and retain a bounded cleanup window (Issue 366).
+
+---
+
 ## [0.7.97-alpha.2] - 2026-10-10
 
 Second alpha of the v0.7.97 line: completes the FEATURE_298 product seams

package/README.md

@@ -111,7 +111,7 @@ does not break ordinary permission handling.
   <tr>
     <td align="center" valign="top">
       <h3>🤖 Multi-agent by default</h3>
-      <sub>V2 Worker single-loop + Sidecar Verifier + async children</sub>
+      <sub>V2 Worker single-loop + evidence-based result review + async children</sub>
       <br><br>
       <code>spawn_agent</code>, <code>send_message</code>, <code>followup_task</code>, <code>interrupt_agent</code>, multi-instance auto-coordination with content-hash safety net.
     </td>
@@ -346,7 +346,6 @@ receive `prompt_cache_key`. The default is `false` because some strict
 compatible gateways reject unknown request fields. Do not enable it solely
 because an endpoint claims protocol compatibility.
 
-Sidecar verifier judge calls use provider-level forced tool choice when supported. If a compatible endpoint rejects the `tool_choice` parameter, KodaX retries that verifier request once without forced tool choice and still fails open rather than blocking the main Worker.
 
 #### Opting a custom provider into image / vision input (FEATURE_134 v0.7.40)
 
@@ -448,6 +447,11 @@ connector does not provide browser HTTP/WebSocket transport. The retained
 Worker-hosted embedded Runtime is removed. The following structured-failure
 reference is scoped to that low-level API, not fields promised by Product Client.
 
+Both product entries accept optional `onStartupProgress` with the shared
+`ClientStartupProgress` type. Launcher `ready` means the Client is usable;
+Session loading and UI rendering have separate boundaries. See the
+[startup progress example](public_docs/sdk/embedder-guide.md#show-local-startup-progress).
+
 ### Structured Runtime failures
 
 Since v0.7.96, when Runtime has a structured failure fact, failed/cancelled runs
@@ -769,6 +773,34 @@ 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.4 release:** Adds the independent `@kodax-ai/artifacts`
+package — PPTX authoring, bounded editing, and current-file visual
+evidence through LibreOffice/PDF rendering — with an optional managed
+KodaX adapter (FEATURE_301), and retires the out-of-band Sidecar
+Verifier: the main agent now verifies requested requirements with actual
+tool and rendered evidence before delivery, guided by the `visual-review`
+builtin skill across static, paginated, interactive, and temporal
+surfaces, with read-only child reviewers inside the same Run and
+unverified scope reported honestly. Client and CLI startup share one
+`onStartupProgress` contract, keeping the CLI responsive while the Host
+starts, upgrades, or waits. See
+[docs/SPACE_SDK_SEAMS.md](docs/SPACE_SDK_SEAMS.md) and the
+[v0.7.97-alpha.4 release notes](docs/release.md#v0797-alpha4-release-preparation).
+Every v0.7.96 stable and v0.7.97-alpha.1/alpha.2/alpha.3 contract is
+retained.
+
+**v0.7.97-alpha.3 release:** Lets trusted Main bound Product Workflows.
+`authorizeExecution` may return a `workflowHostPolicy` (`maxAgents`,
+`tokenBudget`) without registering credential or hostTools leases, and the
+Host capability moves to `productExecutionAuthorization:2`. Policy-only
+authorizations bind to `/client` inputs, queued consumes, and
+Skill/command/review derived Runs, never to independent Actor admissions;
+Workflow spawn slots are reserved across concurrent admissions, and output
+usage publishes only when every executed round reported it. See
+[docs/SPACE_SDK_SEAMS.md](docs/SPACE_SDK_SEAMS.md) and the
+[v0.7.97-alpha.3 release notes](docs/release.md#v0797-alpha3-release-preparation).
+Every v0.7.96 stable and v0.7.97-alpha.1/alpha.2 contract is retained.
+
 **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
@@ -1326,11 +1358,12 @@ kodax --repo-intelligence full --repo-intelligence-trace
 
 ## Architecture
 
-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 uses a **monorepo architecture** with npm workspaces. Four core packages ship in `@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). The independent optional `@kodax-ai/artifacts` package provides PPTX authoring, bounded editing and current-file visual evidence without adding renderers to the core bundle. Its optional KodaX bridge uses managed permissions, sandbox and cancellation. [Setup and checks](docs/test-guides/FEATURE_301_v0.7.97_TEST_GUIDE.md).
 
 ```
 KodaX/
-├── packages/                # 4 workspace packages (FEATURE_194 v0.7.43)
+├── packages/                # 4 core packages + optional artifacts
+│   ├── artifacts/           # Independent Artifact SDK + optional managed KodaX adapter
 │   ├── llm/                 # @kodax-ai/llm - LLM abstraction (16 built-in provider aliases)
 │   │   └── providers/       # Anthropic, OpenAI, DeepSeek, Kimi, MiMo, MiniMax, Zhipu, Ark, …
 │   │
@@ -1571,7 +1604,7 @@ per-command `denyRead`, which the Windows `WRITE_RESTRICTED` backend rejects as
 - **Modular Architecture** - Use as CLI, as a library, or as a Node-free single binary
 - **16 Built-in Provider Aliases** - Anthropic, OpenAI, DeepSeek, Kimi, Kimi Code, Qwen, Qwen Token Plan, Zhipu, Zhipu Coding, Zai Coding, MiniMax Coding, MiMo Coding, MiMo, Ark Coding, Gemini CLI, Codex CLI - plus user-defined OpenAI/Anthropic-compatible providers
 - **Dynamic Workflows + SDK Process Surface** - Generate/reuse capability-routed workflows, observe live progress through `WorkflowProcessSnapshot`, and control workflow lifecycle from SDK hosts without parsing REPL output
-- **V2 Worker single-loop + Sidecar Verifier (default)** - Single-agent main loop with an out-of-band Sidecar Verifier as Stop-hook (claudecode-shape; FEATURE_184 v0.7.42, ADR-030). Verifier returns accept/revise/blocked verdict on Worker text-only termination. The pre-v0.7.43 V1 chain is retired, `emit_handoff` is deleted, accept-verdict UI silently passes through, and content-aware gating skips trivial-chat sidecar calls. Adaptive child steering uses the canonical Actor collaboration tools with idle-yield waiting; specialist routing uses `spawn_agent(agent_id=...)`.
+- **V2 Worker single-loop + result review (default)** — The main agent verifies actual results and may use ordinary read-only child Actors for independent review.
 - **Reasoning Effort** - Effort-first control (`off/auto/low/medium/high` plus model-supported extras) across providers
 - **Streaming Output** - Real-time response display
 - **Session Management** - JSONL format with branchable session lineage tree
@@ -1918,24 +1951,9 @@ Related variables: `KODAX_MAX_TOKENS` (global fallback when no provider/model ca
 
 > **Retired in v0.7.42**: `KODAX_RST_PRONE_PROVIDERS` and `KODAX_WRITE_TURN_MAX_TOKENS` (the v0.7.28 P2b write-turn cap mechanism) are no longer recognized. The 2026-04 bench measured RST as time-based (zhipu-coding 308s server kill window), not payload-size-based, so the cap was retired in favor of the per-provider `streamMaxDurationMs` watchdog + non-streaming fallback chain (configured in `registry.ts`). Existing env exports become silent no-ops; remove them from shell profiles when convenient.
 
-#### Sidecar verifier diagnostics
-
-Use these when diagnosing Worker text-only completion stalls or custom provider verifier behavior:
-
-```bash
-export KODAX_VERIFIER_LOG=1
-export KODAX_VERIFIER_PROVIDER=anthropic
-export KODAX_VERIFIER_MODEL=claude-haiku-4-5-20251001
-```
-
-- `KODAX_VERIFIER_LOG=1` shows verifier gate/elapsed/trace information and is equivalent to `"verifierLog": true` in `~/.kodax/config.json`.
-- `KODAX_VERIFIER_PROVIDER` + `KODAX_VERIFIER_MODEL` route the verifier to a separate provider/model instead of inheriting the main Worker model. Set both together.
-- `KODAX_VERIFIER_ALWAYS=1` forces the verifier to fire on every text-only completion for debugging/regression sweeps.
+#### Result verification
 
-SDK/headless hosts can observe actionable Sidecar Verifier messages via
-`KodaXEvents.onSidecarMessage`; JSONL output emits the same payload as
-`sidecar.message`. Only `revise` and `blocked` verdicts are surfaced; `accept`
-stays silent.
+The main agent verifies each requested requirement with actual tool and rendered evidence before delivery. The built-in `visual-review` skill covers static images/charts, paginated documents/slides/sheets, interactive web/app/terminal/canvas/3D surfaces, and temporal video/animation results. Missing capabilities and unchecked scope are reported as unverified. An ordinary read-only child reviewer may contribute findings within the same Run; the main agent owns repairs and the final answer.
 
 ## Advanced Library Usage
 
@@ -1952,7 +1970,6 @@ const events: KodaXEvents = {
   onTextDelta: (text) => process.stdout.write(text),
   onThinkingDelta: (text) => console.log(`Thinking delta: ${text.length} chars`),
   onToolResult: (result) => console.log(`Tool ${result.name}: ${result.content.slice(0, 100)}`),
-  onSidecarMessage: (event) => console.log(`[sidecar:${event.verdict}] ${event.content}`),
   onComplete: () => console.log('\nDone!'),
   onError: (e) => console.error(e.message),
 };
@@ -2029,8 +2046,9 @@ await runKodaX({
 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.
+and [SDK migration guide](docs/SDK_MIGRATION.md). This documentation was checked
+against package version `0.7.97-alpha.4`; npm publication is separate from
+the current development-tree contract.
 
 ```bash
 npm install @kodax-ai/kodax
@@ -2144,7 +2162,7 @@ cannot elevate a `disable-model-invocation` Skill.
 
 ### `@kodax-ai/kodax/coding` — Coding Agent
 
-Complete coding agent: 50+ tools (`read`/`write`/`edit`/`bash`/`grep`/`glob` plus `spawn_agent`/`send_message`/`followup_task`/`wait_agent`/`interrupt_agent`/`list_agents`/`agent_output`) + Worker role prompt + Sidecar Verifier (out-of-band Stop-hook) + agent loop + auto-continue + session management.
+Complete coding agent: 50+ tools (`read`/`write`/`edit`/`bash`/`grep`/`glob` plus `spawn_agent`/`send_message`/`followup_task`/`wait_agent`/`interrupt_agent`/`list_agents`/`agent_output`) + Worker role prompt + evidence-based result review (out-of-band Stop-hook) + agent loop + auto-continue + session management.
 
 ```typescript
 import { runKodaX, KodaXClient, KODAX_TOOLS } from '@kodax-ai/kodax/coding';
@@ -2166,7 +2184,7 @@ await client.send('Create a new file');
 await client.send('Add a function to it'); // Has context from previous message
 ```
 
-**Key Features**: 50+ built-in tools (see [Tools](#tools)) · V2 Worker single-loop + Sidecar Verifier (FEATURE_184 v0.7.42 / V1 chain fully retired by FEATURE_193 v0.7.43) · Runtime-owned Actor collaboration and safe-boundary steering (FEATURE_270, v0.7.72) · idle-yield waiting · specialist routing via `spawn_agent(agent_id=...)` · auto-continue · session lineage.
+**Key Features**: 50+ built-in tools (see [Tools](#tools)) · V2 Worker single-loop + evidence-based result review (FEATURE_184 v0.7.42 / V1 chain fully retired by FEATURE_193 v0.7.43) · Runtime-owned Actor collaboration and safe-boundary steering (FEATURE_270, v0.7.72) · idle-yield waiting · specialist routing via `spawn_agent(agent_id=...)` · auto-continue · session lineage.
 
 ### `@kodax-ai/kodax/repl` — Interactive Terminal UI
 
@@ -2322,7 +2340,6 @@ KodaX ships 50+ built-in tools, grouped below. They are registered as a single f
 | `ask_user_question` | Single/multi-select or free-text prompt back to the user |
 | `exit_plan_mode` | Present a finalized plan only when the active REPL/host supplied an approval callback |
 | `run_workflow` | Author and run a deterministic Workflow protocol in AMA only when Workflow intent is explicit; complexity alone never activates it. Child Agents share the Actor control plane. Async / idle-yield. (FEATURE_246; FEATURE_270 v0.7.72) |
-| `emit_managed_protocol` | Internal managed-task protocol side-channel for role payloads (verdict). V2 Worker single-loop + Sidecar Verifier is the default since v0.7.42 (FEATURE_184); V1 chain retired in v0.7.43 (FEATURE_193). |
 
 ---
 

package/README_CN.md

@@ -98,6 +98,8 @@ try {
 
 `connectKodaXClient` 只连接已有兼容 Host；`ensureKodaXClient` 通过统一启动器启动或正常更新空闲 Host。Node 连接器不提供浏览器 HTTP/WebSocket transport。
 
+两个产品入口均支持可选 `onStartupProgress` 和共享 `ClientStartupProgress` 类型。启动 `ready` 表示 Client 接口可用；Session 加载与 UI 渲染仍有独立完成边界。详见[启动进度示例](public_docs/sdk/embedder-guide.md#show-local-startup-progress)。
+
 底层 `/runtime` 仍支持显式 inline embedded 与 daemon，供受信任宿主处理凭据桥、Host Tools、启动和诊断；Worker-hosted embedded、通用 operation receipt/journal 已移除。不能在产品连接失败时退回私有 Runtime。下方结构化 Runtime 错误说明仅属于底层接口，不能假定 Product Client 暴露相同字段。
 
 ### 结构化且凭据安全的 Runtime 错误
@@ -301,6 +303,27 @@ SDK 系统代码契约更新，但没有放宽 shell/sandbox 的 fail-closed 边
 `handleRuntimePermissionRequest()` 管理 SDK 权限 UI，并在 prepared Session 尾部遇到
 `data_changed` 时通过权威 delta 合并恢复；后台持久化失败会显示为诊断，不再静默丢失。
 
+**v0.7.97-alpha.4 发布**：新增独立的 `@kodax-ai/artifacts` 包——PPTX 创作、
+有界编辑与当前文件视觉证据（LibreOffice/PDF 渲染），并带可选的受管 KodaX
+适配器（FEATURE_301）；同时退役旁路 Sidecar Verifier：主 Agent 在交付前用
+真实工具与渲染证据核验每条需求，由内置 `visual-review` 技能覆盖静态、分页、
+交互与时间性表面，允许只读子评审者在同一 Run 内参与，未核验范围如实报告。
+客户端与 CLI 启动共享同一 `onStartupProgress` 契约，在 Host 启动、升级或
+等待期间保持 CLI 可响应。
+详见 [docs/SPACE_SDK_SEAMS.md](docs/SPACE_SDK_SEAMS.md) 与
+[v0.7.97-alpha.4 发布清单](docs/release.md#v0797-alpha4-release-preparation)。
+所有 v0.7.96 稳定与 v0.7.97-alpha.1/alpha.2/alpha.3 契约全部保留。
+
+**v0.7.97-alpha.3 发布**：让可信 Main 为产品 Workflow 设定上限。
+`authorizeExecution` 可以只返回 `workflowHostPolicy`（`maxAgents`、
+`tokenBudget`），无需注册 credential 或 hostTools lease；宿主能力升级为
+`productExecutionAuthorization:2`。仅策略的授权绑定 `/client` 输入、排队
+消费与 Skill/command/review 派生 Run，从不绑定独立 Actor 准入；Workflow
+spawn 名额在并发准入间同步预留，输出用量只在每个执行轮都上报时才发布。
+详见 [docs/SPACE_SDK_SEAMS.md](docs/SPACE_SDK_SEAMS.md) 与
+[v0.7.97-alpha.3 发布清单](docs/release.md#v0797-alpha3-release-preparation)。
+所有 v0.7.96 稳定与 v0.7.97-alpha.1/alpha.2 契约全部保留。
+
 **v0.7.97-alpha.2 发布**：补齐 FEATURE_298 面向嵌入方（Space）的产品接缝——
 在可信壳内运行客户端所需的最后一块。`connectKodaXClient`/`ensureKodaXClient`
 接受仅在可信 Main 进程执行的 `authorizeExecution` 回调，注册 scoped credential
@@ -734,7 +757,7 @@ Reviewer 首次 90 秒，只有 timeout/provider/无效输出会再试一次 180
   <tr>
     <td align="center" valign="top">
       <h3>🤖 默认多 agent</h3>
-      <sub>V2 Worker 单循环 + Sidecar Verifier + 异步子 agent</sub>
+      <sub>V2 Worker 单循环 + 实际结果评审 + 异步子 agent</sub>
       <br><br>
       <code>spawn_agent</code>、<code>send_message</code>、<code>followup_task</code>、<code>interrupt_agent</code>，多实例自动协调（content-hash safety net）。
     </td>
@@ -1022,21 +1045,7 @@ key 写入 `metadata.user_id`，OpenAI-compatible 请求写入 `prompt_cache_key
 默认值为 `false`，因为部分严格兼容网关会拒绝未知请求字段；不要只因端点宣称协议
 兼容就开启。
 
-Sidecar verifier 的结构化裁决请求会优先使用 provider 级 `tool_choice` 强制工具调用；如果某个兼容端点明确拒绝 `tool_choice` 参数，KodaX 会对该 verifier 请求自动重试一次“不强制但仍带 tools”的兼容模式，并保持 fail-open，不会阻塞主 Worker。
-
-调试 Worker 结束后的 verifier 行为时可设置：
-
-```bash
-export KODAX_VERIFIER_LOG=1
-export KODAX_VERIFIER_PROVIDER=anthropic
-export KODAX_VERIFIER_MODEL=claude-haiku-4-5-20251001
-```
-
-`KODAX_VERIFIER_LOG=1` 等价于在 `~/.kodax/config.json` 写 `"verifierLog": true`，会显示 verifier gate、elapsedMs 和 trace；`KODAX_VERIFIER_PROVIDER` / `KODAX_VERIFIER_MODEL` 需要成对设置，用独立模型执行 verifier；`KODAX_VERIFIER_ALWAYS=1` 仅建议调试和回归测试时使用。
-
-SDK / headless 宿主可以通过 `KodaXEvents.onSidecarMessage` 观察 Sidecar
-Verifier 的 `revise` / `blocked` 可执行消息；JSONL 输出使用同形
-`sidecar.message` 事件。`accept` 仍保持静默。
+结果由主 Agent 按需求逐项验证。内置 `visual-review` 技能覆盖图像/图表、文档/幻灯片/表格、Web/应用/终端/Canvas/3D、视频/动画，检查真实渲染证据；缺少能力或未覆盖部分明确标为未验证。必要时使用当前 Run 内普通只读子 Agent 做独立评审，主 Agent 负责修复和最终交付。
 
 #### 给自定义 provider 开图片 / vision 输入（FEATURE_134 v0.7.40）
 
@@ -1217,7 +1226,6 @@ KodaX 有 50+ 个内置工具，按类别分组如下（实际暴露给 LLM 是
 | `agent_output` | 读取有权限的 Actor/Turn 有界持久输出。 |
 | `ask_user_question` | 向用户发起单选 / 多选 / 自由文本提问 |
 | `exit_plan_mode` | 仅在当前 REPL/宿主提供审批回调时提交最终方案 |
-| `emit_managed_protocol` | managed-task 协议侧信道（verdict role payload）。v0.7.42 FEATURE_184 起默认走 V2 Worker 单循环 + Sidecar Verifier；v0.7.43 FEATURE_193 退役 V1 chain。 |
 
 ## Repo Intelligence（内置 full/light 引擎）
 
@@ -1232,7 +1240,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` 发布 + 13 个 SDK subpath exports（`/agent`、`/llm`、`/coding`、`/media`、`/repl`、`/skills`、`/mcp`、`/session`、`/client`、`/runtime`、`/sandbox`、`/a2a`、`/experimental-memory`；ADR-024 + ADR-032 + ADR-038）。核心包：
+KodaX 是基于 npm workspaces 的 TypeScript monorepo，**4 个核心 workspace 包与独立可选 Artifact SDK**（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 包 | 作用 | 主要依赖 |
 |----|------|---------|
@@ -1247,7 +1255,7 @@ KodaX 是基于 npm workspaces 的 TypeScript monorepo，**源码层 4 个 works
 
 KodaX 有两层结构，SDK 用户需要分开理解：
 
-- **源码层**：上面 4 个 workspace 包（开发者读代码时看到的物理结构）。
+- **源码层**：4 个核心 workspace 包，另有独立可选 `@kodax-ai/artifacts`：PPTX 创作、限定编辑、当前文件渲染及四类视觉证据契约。它不增加核心 bundle 的渲染依赖；KodaX 桥接沿用受管权限、沙箱和取消。[启用与验证](docs/test-guides/FEATURE_301_v0.7.97_TEST_GUIDE.md)。
 - **当前源码打包导出**（不表示已发布到 npm）：单个 bundled 包 `@kodax-ai/kodax`，对外暴露 13 个 SDK subpath（SDK 消费者 `import` 时看到的接口）。subpath 分两种角色：
   - **完整包 subpath**（`/agent`、`/llm`、`/coding`、`/repl`）—— 每个 1:1 对应一个源码包，暴露完整公开 API。
   - **集成与窄子集 subpath**（`/media`、`/skills`、`/mcp`、`/session`、`/client`、`/runtime`、`/sandbox`、`/a2a`、`/experimental-memory`）—— 聚焦能力或宿主集成边界；`/experimental-memory` 明确为 opt-in 不稳定接口。

package/config-templates/config.example.jsonc

@@ -82,7 +82,6 @@
 
   // Runtime/provider diagnostics and timeouts.
   // "streamIdleTimeoutMs": 120000,
-  // "verifierLog": false,
   // "stallLog": false,
 
   // Ordered provider fallback for child tasks and optional model tiers used by

package/dist/builtin/visual-review/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: visual-review
+description: Verify visible results when creating, changing or reviewing images, diagrams, charts, documents, spreadsheets, websites, application or terminal interfaces, canvas/3D scenes, videos or animations. Use actual rendered evidence and relevant states; source inspection alone does not establish visual correctness. Not needed for work without a visual acceptance requirement.
+user-invocable: true
+argument-hint: "[artifact, surface, or requested visual result]"
+compatibility: Uses the current session's image input and available rendering, capture or frame extraction tools. Missing capabilities are reported explicitly.
+---
+
+# Visual review
+
+Use the same workflow for creation, modification, and review. The user's
+requirements determine the scope, not the file extension or change size.
+Respect review-only requests: report findings without modifying the subject.
+
+## Obtain evidence
+
+Identify the current result and the visual requirements to check. Discover
+available session tools and relevant format skills before choosing a renderer
+or capture method. Use the existing permission, sandbox, working-directory,
+tool and provider boundaries. Do not enable broader access, install software,
+or call an external model just to make a check appear successful.
+
+- **Static** images, icons, posters, diagrams, maps, plots and charts: inspect
+  the actual final image. Render SVG or drawing code to pixels; use a full
+  view and detailed crops when necessary. Include the intended background for
+  transparent assets. Compare reference images when fidelity was requested.
+- **Paginated** documents, slides, PDFs, reports and spreadsheets: render the
+  actual deliverable. Track page/slide/sheet/range, font and page size. Inspect
+  pagination, overflow, clipping, legibility and consistency. A PDF text
+  extraction or Office file listing does not replace rendered page evidence.
+- **Interactive** web, desktop, mobile, terminal, canvas and 3D surfaces:
+  capture the actual running result at the relevant viewport, terminal size,
+  state or camera. Perform requested interactions and inspect the resulting
+  states; use DOM, accessibility tree, terminal state or event evidence with
+  screenshots. Include relevant loading/error states and responsive sizes.
+  A static picture does not prove interaction or invisible 3D geometry.
+- **Temporal** video, GIF, animation, transitions and changing visualizations:
+  decode or capture the final output with timestamps/frame numbers. Inspect
+  the required start/end states, motion, transitions and captions, using
+  consecutive frames where continuity matters. A GIF read may expose only its
+  first frame. A thumbnail or sparse sampling does not prove the whole clip.
+
+Use the available image-reading tool to deliver actual image content to the
+model. A saved screenshot path, UI preview, successful render exit code or
+tool-call receipt does not mean the model received or inspected the image.
+If image input, rendering or capture is unavailable, identify the affected
+requirement as **unverified** and state the reason. Continue other useful work.
+
+## Check and repair
+
+Check against the brief: missing or wrong content, illegible text, unintended
+cropping/distortion, overlaps, overflow, poor contrast and requested visual
+fidelity. Cite a concrete page, region, state, camera or timestamp with each
+finding. Do not invent pixels, constraints or aesthetic preferences.
+
+Visual evidence supplements content and behavior checks. Verify chart source
+values and spreadsheet calculations separately; use functional checks for
+backend behavior and audio/timing checks for sound or synchronization.
+
+Self-review in single-agent mode. When an independent view is useful and
+collaboration is available, the main agent captures evidence and spawns an
+ordinary read-only child within the current task. Give it the brief, current
+artifact identity, evidence references and exact scope, with fresh history.
+It reports findings and gaps; the main agent owns repairs and final delivery.
+Do not create independent background work or repeat the same full review.
+
+After a repair, obtain new evidence for the affected scope. Associate findings
+with the artifact version and capture settings actually inspected; an old
+screenshot cannot certify a changed result. Use existing task/actor results
+and artifact metadata, not a separate verification database or completion API.
+
+## Report honestly
+
+Record the checked requirements, current artifact/version, evidence references,
+pages/regions/states/viewports/cameras/time ranges inspected, concrete findings
+and unverified scope. Distinguish **passed**, **issues** and **unverified** for
+each requirement. State sampling limits. Missing evidence never means passed.
+Respect current cancellation and budgets; do not restart an interrupted action
+or repeatedly spawn reviewers without new evidence. Final delivery follows
+the required checks and repairs; lifecycle completion is not a quality verdict.

package/dist/chunks/agent-QPYNXWUF.js

@@ -0,0 +1,2 @@
+// @kodax-ai/kodax — bundled distribution. See docs/ADR.md ADR-022 + ADR-024.
+import{Aa as e,Ba as f,Ra as g,Ta as h,mb as i,nb as j,wb as k,za as d}from"./chunk-NGFXDSP2.js";import{a as c}from"./chunk-ULYEFYIV.js";import"./chunk-V26LAWJY.js";import"./chunk-7VOTRMUH.js";import"./chunk-62IOXGHA.js";import"./chunk-6ERRCDWZ.js";import"./chunk-3XIY3OYT.js";import{Rb as a,Sb as b}from"./chunk-62V3CQH4.js";import"./chunk-YVBBU6K5.js";import"./chunk-2AM3FRQ7.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};

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

@@ -0,0 +1,2 @@
+// @kodax-ai/kodax — bundled distribution. See docs/ADR.md ADR-022 + ADR-024.
+import{$a as a,ab as b}from"./chunk-D2WGP3VS.js";import"./chunk-ZQYWDI4O.js";import"./chunk-JRHESXS5.js";import"./chunk-2E3TJ7KO.js";import"./chunk-4VCYZ2PV.js";import"./chunk-NGFXDSP2.js";import"./chunk-ULYEFYIV.js";import"./chunk-4BYTAJU4.js";import"./chunk-V26LAWJY.js";import"./chunk-4HSDJRRJ.js";import"./chunk-7VOTRMUH.js";import"./chunk-62IOXGHA.js";import"./chunk-6ERRCDWZ.js";import"./chunk-3XIY3OYT.js";import"./chunk-62V3CQH4.js";import"./chunk-YVBBU6K5.js";import"./chunk-2AM3FRQ7.js";import"./chunk-ONUPGMER.js";export{a as ArgumentCompleter,b as createArgumentCompleter};