@kodax-ai/kodax 0.7.77 → 0.7.78

package/README_CN.md

@@ -41,18 +41,25 @@
 ```bash
 npm i -g @kodax-ai/kodax
 
-# 选一个你有 API key 的 provider
-export ZHIPU_API_KEY=...        # 或 KIMI_API_KEY / MINIMAX_API_KEY / MIMO_API_KEY /
-                                # ARK_API_KEY / DEEPSEEK_API_KEY / ANTHROPIC_API_KEY /
-                                # OPENAI_API_KEY / QWEN_API_KEY / QWEN_TOKEN_API_KEY / GEMINI_API_KEY
+# 选一个你有 API key 的 provider（`kodax setup --help` 会列出全部）
+export ZHIPU_API_KEY=...        # ANTHROPIC_API_KEY / OPENAI_API_KEY / DEEPSEEK_API_KEY /
+                                # KIMI_API_KEY / KIMI_CODE_API_KEY / QWEN_API_KEY /
+                                # QWEN_TOKEN_API_KEY / ZHIPU_CODING_API_KEY /
+                                # ZAI_CODING_API_KEY / MINIMAX_CODING_API_KEY /
+                                # MIMO_API_KEY / MIMO_CODING_API_KEY / ARK_CODING_API_KEY
 
 kodax
 ```
 
-就这样。进 REPL，自然语言提问。如果新机器既没有选择 provider，也没有任何
-受支持的 API Key 环境变量，直接运行 `kodax` 会先打开只配置元数据的向导；它不会
-要求输入或保存 Key。选择 provider/model 后，按提示设置对应环境变量、重启终端，
-再运行 `kodax`。需要主动重新配置时可运行 `kodax setup`。
+就这样。进 REPL，自然语言提问。新机器只要还没有选择 provider，交互式运行
+`kodax` 就会先进入 setup，即使已经存在受支持的 API Key 环境变量。setup 会检查
+core、MCP、Extensions、A2A 的活跃配置和注释模板，不覆盖已有文件，也不会要求输入
+或保存 Key。选择 provider/model 后，按提示设置对应环境变量、重启终端，再运行
+`kodax`。使用 `kodax setup --custom` 配置自定义 provider；使用
+`kodax setup --help` 或 REPL `/setup --help` 查看完整路径、环境变量、命令和快捷键。
+交互式 setup 还会检查一次可选 ASRT sandbox：Windows 可能弹出一次 UAC；
+macOS/Linux 会报告 Seatbelt/bubblewrap 所需依赖。拒绝 UAC 或缺少依赖不会破坏普通
+权限管理，日常启动也不会反复提醒。
 
 > **不装 Node 的目标机器**：从 [GitHub Releases](https://github.com/icetomoyo/KodaX/releases) 拿 Bun 编译的单文件二进制（Win / macOS / Linux × x64 + arm64）。详见 [docs/release.md](docs/release.md)。
 
@@ -107,7 +114,7 @@ daemon Runtime 边界保留结构化 blocked 原因。
 可选模型，同时保留 `kimi-for-coding-highspeed` 与 1M `k3` tier。K3 支持
 `low` / `high` / `max` 思考强度，默认 `high`；256K 路由支持图片但不支持视频输入。
 
-**v0.7.77 发布就绪候选版**：AMA 现在通过现有 Actor 控制面按需组合六种具名问题解决
+**v0.7.77 正式版**：AMA 现在通过现有 Actor 控制面按需组合六种具名问题解决
 模式，不引入固定拓扑或隐藏 Workflow。可选策略元数据会形成有界、仅记录事实的
 `PatternTrace`，现有 Sidecar 仍是唯一的终态答案质量裁决者。治理式记忆可在工具
 失败、验证失败或已提交 compact 之后稀疏触发，在下一次 Action-LLM 请求前注入最多
@@ -120,7 +127,60 @@ daemon Runtime 边界保留结构化 blocked 原因。
 为 `recommend-ship`，随后形成发布确定性契约的联合 `SHIP` 决策。语义记忆选择仍为
 实验性、宿主显式启用能力；本版本不宣称任务质量、token 或延迟改善。
 
-同一候选版还增加了由宿主显式配置的 Shell Execution Contract。Runtime Session
+**v0.7.78 证据门禁学习、首次配置与权限/沙盒正式版**：后台学习遵循
+Memory-first；只有重复且独立验证的证据，或带已验证终态证据的显式
+preserve-as-Skill 请求，才能把低风险声明式 Skill 放入不可变、项目级的有界
+canary。自动项目信任需要完成三次精确 revision 使用并取得独立验证成功；每个
+revision 都可在 `/learn` 中查看、禁用、回滚、信任或拒绝。受保护/正式 Skill、
+全局提升和 Extension 编写仍必须由用户显式决定。
+
+### 将 learned Skill 提升到用户正式目录
+
+自动 canary 激活和用户目录提升不是一回事：
+
+- 独立验证成功会把项目 Learned Area 中的 `testing` 变为
+  `active_learned`；
+- `/learn promote` 是一次显式所有权转移：它把精确 fingerprint 对应、且已审查的
+  `ready` 或 `active_learned` revision 复制到用户正式 Skill 目录，并把生命周期
+  改为 `promoted_user`。
+
+先检查具体 revision，再按名称、slug 或精确 capability ID 提升：
+
+```text
+/learn show normalize-release-notes
+/learn promote normalize-release-notes --scope user
+```
+
+`--scope user` 是目前唯一支持的 scope，也可以省略。错误 scope、未知或重复
+option，以及多余参数都会失败且不改变目录。目标位置是所配置 KodaX home 下的
+`skills/<slug>/SKILL.md`，通常为
+`~/.kodax/skills/<slug>/SKILL.md`；不同内容的同名正式 Skill 永远不会被覆盖。
+
+专属帮助入口为 `/learn promote --help`、`/learn help promote` 和
+`/help learn promote`。在 Ink Learning Center 中可执行 `/learn`，选择一个
+`active_learned` Skill，再选择 **Promote to user catalog**。
+
+首次 setup 会创建并校验 core/MCP/Extensions/A2A 分离配置及带注释模板，不覆盖
+现有配置，也不收集密钥。Auto[LLM] 在 classifier 延迟之前放行可精确建模的普通
+读取及 workspace/temp 变更；classifier 基础设施失败只重试一次，随后按
+Accept-edits 边界降级，绝不切换到 rules。ASRT 是可选执行期 containment，不是
+权限裁决者；`/sandbox` 是显式诊断入口，SDK 宿主也可独立使用 `/sandbox`
+subpath，且不可用时不会静默改为非隔离执行。KodaX 自身的 workspace containment
+会拒绝读取常见的用户主目录凭据路径及完整的已解析 agent home，同时不把普通外部
+读取收窄成 allowlist。详见
+[v0.7.78 设计](docs/features/v0.7.78.md)、
+[发布检查清单](docs/release.md#v0778-release-verification)与
+[SDK 指南第 29–30 节](docs/SDK_EMBEDDER_GUIDE.md#29-evidence-gated-background-skill-learning-feature_263-v0778)。
+
+本次发布收口同时保证相邻表面不扭曲意图：Edit/Plan 可加载静态 Skill 指令，但不
+预授权其后续副作用；动态 Skill 命令必须由宿主显式控制 executor；根 AMA 使用受
+治理的 `memory_intent` 生命周期（包括在后续取消前已捕获的显式意图）；Workflow
+Actor wait 只有在 workflow 显式设置
+deadline 时才超时；embedded、Worker 与 daemon 的 Runtime Auto v4 均声明
+`fallbackPersistsEngine:false`。Actor owner 还会验证 Runtime identity，而不是只看
+PID，因此 PID 复用不会卡住已崩溃 owner。恢复 Session 选择器也改为显示宿主本地时区。
+
+v0.7.77 还增加了由宿主显式配置的 Shell Execution Contract。Runtime Session
 设置或单次 Run 可以选择 `pwsh`、Windows PowerShell、`cmd`、`bash`、`zsh`
 或 Git Bash 的绝对路径；KodaX 会在实际项目 cwd 中解析 shell 环境，再通过同一
 解释器执行命令。环境缓存按 contract 与 cwd 隔离，使用有界 TTL，也可由宿主显式
@@ -149,10 +209,11 @@ CLI 也会在配置的 deadline 被终止。详见
 
 **v0.7.72–v0.7.73 Runtime 权限契约：**Auto Mode 的权限决策由 Runtime Session 持有，
 不再由 UI hook 抢先决定。Runtime 会跨 turn 复用 LLM/rules guardrail，先分类、
-仅在 `escalate` 时创建共享 permission 请求，并把自动降级到 rules 的结果持久化到
-session。Session 也可设置 classifier model 和有界 timeout；`auto` 默认使用 LLM
-分类，没有有效 classifier model 时会在调用 provider 或创建审批前返回可恢复配置错误，
-绝不静默退回 rules。Runtime 权限请求可给出由 Runtime 生成的精确作用域建议：一次允许、
+仅在 `escalate` 时创建共享 permission 请求，并持久化显式选择的 engine。
+Session 也可设置 classifier model 和有界 timeout；`auto` 默认使用 LLM
+分类，没有有效 classifier model 时会在调用 provider 或创建审批前返回可恢复配置错误，
+绝不静默退回 rules。v0.7.78 中 classifier 失败会重试一次，再按 Accept-edits
+安全边界降级，绝不把 engine 改为 rules。Runtime 权限请求可给出由 Runtime 生成的精确作用域建议：一次允许、
 本 Session 允许，或（仅安全场景）持久允许；客户端只能回传不透明 suggestion id，不能从
 预览内容自行扩大范围。持久授权由 daemon 持有并通过 revision 管理。没有宿主审批回调时，
 不会向模型暴露 `exit_plan_mode`。完整 SDK 接入见
@@ -161,8 +222,9 @@ session。Session 也可设置 classifier model 和有界 timeout；`auto` 默
 **v0.7.74 Auto 切换可靠性：**默认用 `Shift+Tab` 在 `Plan -> Edits -> Auto`
 之间循环，`Shift+Enter` 仍用于换行。进入 Auto 时状态栏会立即显示已解析的
 `Auto[LLM]` 或 `Auto[RULES]`，同一 Session 的 Runtime 设置按键入顺序串行提交，
-快速循环不会让较早的异步结果覆盖最后一次选择。`Auto[RULES]` 可能是自动降级或
-手动选择后的合法粘性状态；使用 `/auto-engine llm` 可显式恢复 LLM 分类。
+快速循环不会让较早的异步结果覆盖最后一次选择。`Auto[RULES]` 是手动选择后的
+合法粘性状态；从 v0.7.78 起它只由显式/持久化选择产生。使用
+`/auto-engine llm` 可显式选择 LLM 分类。
 
 ## 为什么用 KodaX
 
@@ -245,22 +307,61 @@ kodax
 
 可以先运行不会收集 Key 的交互配置：
 
-```bash
-kodax setup
-```
-
-命令会保存 provider/model，告诉你准确的环境变量名，然后退出以便重启终端。
-也可以直接设置 API Key：
+```bash
+kodax setup
+
+# 交互配置自定义 OpenAI/Anthropic-compatible provider
+kodax setup --custom
+
+# 只显示完整指导，不修改文件
+kodax setup --help
+```
+
+setup 会检查以下活跃文件以及对应的 `*.example.jsonc` 注释模板：
+
+- `~/.kodax/config.json` 与 `~/.kodax/config.example.jsonc`
+- `~/.kodax/integrations/mcp.json`
+- `~/.kodax/integrations/extensions.json`
+- `~/.kodax/integrations/a2a.json`
+
+活跃 `config.json` 仍是严格 JSON；`config.example.jsonc` 第一行指向全部分离配置，
+并注释说明所有受支持的 core 配置项。setup 不覆盖已有文件；创建空的权威分离配置
+前会先保全可读取的旧 `config.json#mcpServers` / `config.json#extensions`。命令会
+先验证已有活动配置；发现无效文件时会报告并停止，不创建或覆盖任何配置。随后才会
+保存 provider/model，告诉你准确的环境变量名，然后退出以便重启终端。也可以直接设置 API Key：
 
 ```bash
 # macOS / Linux
 export ZHIPU_API_KEY=your_api_key
 
 # PowerShell
-$env:ZHIPU_API_KEY="your_api_key"
-```
-
-Qwen Token Plan 需要选择 `qwen-token-plan` 并使用单独的凭据；`QWEN_API_KEY`
+$env:ZHIPU_API_KEY="your_api_key"
+```
+
+### 2.1 激活可选 sandbox
+
+`kodax setup` 与首次安装 setup 会检查 sandbox。也可以显式检查或激活：
+
+```bash
+kodax sandbox doctor
+kodax sandbox setup
+```
+
+- Windows 使用受限 sandbox 账户和网络策略。普通 Terminal 即可，按提示同意一次
+  UAC；不必先以管理员身份启动 Terminal。
+- macOS 使用 Seatbelt/`sandbox-exec`，需要 ripgrep：
+  `brew install ripgrep`。
+- Linux 使用 bubblewrap，需要 `bubblewrap`、`socat` 和 `ripgrep`，请根据发行版用
+  `apt`、`dnf` 或 `pacman` 安装。
+
+KodaX 不会自动运行 `sudo` 或系统包管理器。sandbox 未激活时，确定性安全操作与
+Auto[LLM] 的权限体验保持一致，只缺少 OS 级 containment；普通运行不会反复打扰。
+在 REPL 中，`/sandbox` 会刷新 ready 状态与诊断，但不会激活 backend 或请求提权。
+逐命令 sandbox 路由属于内部机制，不显示在普通命令历史中。SDK 嵌入方还可通过
+`@kodax-ai/kodax/sandbox` 在 Auto[LLM] 之外独立使用该能力，
+见 [SDK sandbox 指南](docs/SDK_EMBEDDER_GUIDE.md#30-standalone-sandbox-sdk-v0778)。
+
+Qwen Token Plan 需要选择 `qwen-token-plan` 并使用单独的凭据；`QWEN_API_KEY`
 不能用于该路由：
 
 ```bash
@@ -325,13 +426,14 @@ import { createImageArtifactFromPath } from '@kodax-ai/kodax/media'; // 输入 a
 import { SkillRegistry } from '@kodax-ai/kodax/skills';         // 零依赖 skill loader
 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 { createKodaXA2AServer } from '@kodax-ai/kodax/a2a';    // A2A 1.0 双向接入
-import { createMemoryAgent } from '@kodax-ai/kodax/experimental-memory'; // opt-in 实验性记忆 SDK
-```
-
-12 个 SDK 入口（root + 11 subpath）通过 ESM 共享 chunk 复用底层代码 —— 只 import `/agent` 不会把 `/repl` 的 Ink + React 一起拉进来。
+import { listSessions } from '@kodax-ai/kodax/session';         // session 历史工具
+import { createKodaXRuntime } from '@kodax-ai/kodax/runtime';   // embedded/Worker/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 一起拉进来。
 
 完整的宿主集成契约——包括 embedded/Worker/daemon 所有权、外部 Agent 注册与任务控制、session cursor 分页、workflow 模型分层和效率遥测——见 [SDK Embedder Integration Guide](docs/SDK_EMBEDDER_GUIDE.md)。
 
@@ -571,8 +673,8 @@ dist/binary/linux-x64/
 | mimo-coding | `MIMO_CODING_API_KEY` | Native | mimo-v2.5-pro（小米 MiMo Token Plan，Anthropic 协议） |
 | ark-coding | `ARK_CODING_API_KEY` | Native | glm-5.2（火山方舟 Coding Plan — GLM-5.2（别名 `glm-latest`） · Kimi K2.7 Code / K2.6 · MiniMax M3 / M2.7 · DeepSeek V4 Pro / V4 Flash · Doubao Seed 2.0 Code / Pro / Lite · Doubao Seed Code） |
 | deepseek | `DEEPSEEK_API_KEY` | Native | deepseek-v4-flash（可 `/model` 切换 `deepseek-v4-pro`） |
-| gemini-cli | `GEMINI_API_KEY` | Prompt-only / CLI bridge | （通过 gemini CLI） |
-| codex-cli | `OPENAI_API_KEY` | Prompt-only / CLI bridge | （通过 codex CLI） |
+| gemini-cli | 由 Provider CLI 完成认证（无 KodaX API-key 环境变量） | Prompt-only / CLI bridge | （通过 gemini CLI） |
+| codex-cli | 由 Provider CLI 完成认证（无 KodaX API-key 环境变量） | Prompt-only / CLI bridge | （通过 codex CLI） |
 
 > 不在表里的端点：用上面"自定义 Provider"那一节加进来即可。
 
@@ -655,7 +757,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` 发布 + 11 个 SDK subpath exports（`/agent`、`/llm`、`/coding`、`/media`、`/repl`、`/skills`、`/mcp`、`/session`、`/runtime`、`/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` 发布 + 12 个 SDK subpath exports（`/agent`、`/llm`、`/coding`、`/media`、`/repl`、`/skills`、`/mcp`、`/session`、`/runtime`、`/sandbox`、`/a2a`、`/experimental-memory`；ADR-024 + ADR-032 + ADR-038）。核心包：
 
 | Workspace 包 | 作用 | 主要依赖 |
 |----|------|---------|
@@ -664,20 +766,20 @@ KodaX 是基于 npm workspaces 的 TypeScript monorepo，**源码层 4 个 works
 | `@kodax-ai/coding` | Coding Agent:50+ 工具（含 canonical Actor 协作工具）、role prompts、agent loop、auto-continue + repo-intelligence protocol(v0.7.43 inline) | `@kodax-ai/llm`, `@kodax-ai/agent` |
 | `@kodax-ai/repl` | 完整交互式终端 UI（Ink / React、权限模式、命令系统、流式渲染） | `@kodax-ai/coding`, `ink`, `react` |
 
-根目录 `src/kodax_cli.ts` 是 CLI 入口；`src/sdk-{agent,llm,coding,media,repl,skills,mcp,session,runtime,a2a,experimental-memory}.ts` 是 SDK subpath 入口；构建产物在 `dist/`，单文件二进制在 `dist/binary/<target>/`。
+根目录 `src/kodax_cli.ts` 是 CLI 入口；`src/sdk-{agent,llm,coding,media,repl,skills,mcp,session,runtime,sandbox,a2a,experimental-memory}.ts` 是 SDK subpath 入口；构建产物在 `dist/`，单文件二进制在 `dist/binary/<target>/`。
 
 ### 源码层 vs npm 发布层
 
 KodaX 有两层结构，SDK 用户需要分开理解：
 
 - **源码层**：上面 4 个 workspace 包（开发者读代码时看到的物理结构）。
-- **npm 发布层**：单个 bundled 包 `@kodax-ai/kodax`，对外暴露 11 个 SDK subpath（SDK 消费者 `import` 时看到的接口）。subpath 分两种角色：
+- **npm 发布层**：单个 bundled 包 `@kodax-ai/kodax`，对外暴露 12 个 SDK subpath（SDK 消费者 `import` 时看到的接口）。subpath 分两种角色：
   - **完整包 subpath**（`/agent`、`/llm`、`/coding`、`/repl`）—— 每个 1:1 对应一个源码包，暴露完整公开 API。
-  - **窄子集 subpath**（`/media`、`/skills`、`/mcp`、`/session`、`/experimental-memory`）—— 从 `/agent` 或 `/repl` 切出聚焦能力；`/experimental-memory` 明确为 opt-in 不稳定接口。
+  - **集成与窄子集 subpath**（`/media`、`/skills`、`/mcp`、`/session`、`/runtime`、`/sandbox`、`/a2a`、`/experimental-memory`）—— 聚焦能力或宿主集成边界；`/experimental-memory` 明确为 opt-in 不稳定接口。
 
 | 源码包 | npm subpath | 类型 | 内容 | 典型消费者 |
 |---|---|---|---|---|
-| `packages/llm`    | `@kodax-ai/kodax/llm`     | 完整包 | 15-alias LLM 抽象 (108 exports) | 独立 LLM 客户端 |
+| `packages/llm`    | `@kodax-ai/kodax/llm`     | 完整包 | 16-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` 等 (23 exports) | MCP server 宿主 |
@@ -685,9 +787,10 @@ KodaX 有两层结构，SDK 用户需要分开理解：
 | `packages/agent`  | `@kodax-ai/kodax/experimental-memory` | **实验性子集** | F228-backed `MemoryAgent` / `MemorySession` scope、recall、query、observation、outcome 契约 | 显式评估 FEATURE_260 的 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/a2a` | 集成边界 | A2A 1.0 Agent Card 发现、JSON-RPC/SSE F258 executor、安全 fetch 与鉴权 Runtime Agent server | Agent 编排器和 KodaX 宿主 |
+| `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/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 宿主 |
 
 **经验法则**：需要 Runner / Agent / fan-out 时从 `/agent` 引入；只需要 skills 或 mcp API 时从 `/skills` 或 `/mcp` 引入，bundle 更小。窄子集是完整包的真子集 —— **不会**有额外符号。
 
@@ -705,7 +808,7 @@ runtime、消息、UI 历史、lineage、artifact、extension 状态、标题、
 
 **实验性 Memory Agent SDK（FEATURE_260，v0.7.68）**：`/experimental-memory` 暴露基于既有 F228 治理平面的薄 `MemoryAgent` 与 scoped `MemorySession`。被动 recall 零等待，`query()` 只读且由主 Action LLM 主动选择；持久化仍必须经过 proposal/preview/fingerprint/apply。召回内容保持低权限，安全与 scope 边界仍由确定性代码门禁承担。直接 session 示例与宿主边界见 [SDK Embedder Guide §21](docs/SDK_EMBEDDER_GUIDE.md#21-experimental-governed-memory--experimental-memory-feature_260-v0768)。
 
-**双向 A2A 1.0（FEATURE_267，v0.7.69）**：`/a2a` 可发现 allowlist 内的 Agent Card，并通过既有 F258 plane 安装 JSON-RPC/SSE executor。配置中的出站 Agent 还会作为 `external:<name>` 自动注册到 embedded CLI 与用户 daemon Runtime，因此主 Agent 无需宿主代码即可编排。一个 `a2a.json` 可保存多个出站注册，但最多只有一个入站 server；入站可发布 Runtime 默认 Agent，或发布一个经过验证的 `~/.kodax/agents/*.md` Agent。内置 listener 仅允许 loopback；公网部署必须由宿主用 TLS、鉴权和授权包住 `handle()`。不宣称支持 A2A 0.3、gRPC、HTTP+JSON、push notification，也不会自动把本地 Agent 暴露到网络。详见 [SDK Embedder Guide §22](docs/SDK_EMBEDDER_GUIDE.md#22-bidirectional-a2a-10--a2a-feature_267-v0769)。
+**双向 A2A 1.0（FEATURE_267，v0.7.69）**：`/a2a` 可发现 allowlist 内的 Agent Card，并通过既有 F258 plane 安装 JSON-RPC/SSE executor。配置中的出站 Agent 还会作为 `external:<name>` 自动注册到 embedded CLI 与用户 daemon Runtime，因此主 Agent 无需宿主代码即可编排。一个 `a2a.json` 可保存多个出站注册，但最多只有一个入站 server；入站可发布 Runtime 默认 Agent，或发布一个经过验证的 `~/.kodax/agents/*.md` Agent。内置 listener 仅允许 loopback，且不会返回 Fetch 兼容客户端禁止的端口；公网部署必须由宿主用 TLS、鉴权和授权包住 `handle()`。不宣称支持 A2A 0.3、gRPC、HTTP+JSON、push notification，也不会自动把本地 Agent 暴露到网络。详见 [SDK Embedder Guide §22](docs/SDK_EMBEDDER_GUIDE.md#22-bidirectional-a2a-10--a2a-feature_267-v0769)。
 
 **A2A 互操作与认证加固**：发现得到的 interface 必须与受信 Agent Card 同源，且只有
 完整满足 Card/Skill 的一个 security requirement 时才会携带凭据。无代码 client
@@ -755,8 +858,9 @@ kodax a2a expose                 # 或：kodax a2a expose document-agent
 kodax a2a serve                  # 仅监听 http://127.0.0.1:8765
 ```
 
-MCP、A2A、Extension 分别使用 `~/.kodax/integrations/` 下的一个用户级文件。
-可以通过 `kodax config template <mcp|a2a|extensions>` 查看模板，通过
+MCP、A2A、Extension 分别使用 `~/.kodax/integrations/` 下的一个用户级文件。
+可以通过 `kodax config paths` 查看全部活跃/模板路径，通过
+`kodax config template <core|mcp|a2a|extensions>` 查看模板，通过
 `kodax integrations migrate --apply` 迁移旧配置，并用 `kodax mcp`、
 `kodax a2a`、`kodax extensions` 管理。迁移只导入旧
 `config.json#mcpServers` 与 `config.json#extensions`；A2A 没有旧来源，且不会
@@ -824,11 +928,11 @@ 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,runtime,a2a,experimental-memory}
+│   └── 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 + 11 SDK subpath + chunks）
+│   ├── build-bundle.mjs     # esbuild 单 bundle 多 entry 打包（CLI + root + 12 SDK subpath + chunks）
 │   ├── build-binary.mjs     # Bun --compile 单文件二进制打包
-│   └── release.mjs          # ADR-024 release-time pkg name/exports 注入
+│   └── release.mjs          # 构建/审计后仅临时切换 private 以 pack/publish
 └── .github/workflows/
     └── release.yml          # 推 v* tag 自动发布 GitHub Release
 ```

package/config-templates/config.example.jsonc

@@ -1,33 +1,115 @@
-// KodaX core configuration template.
-// Copy only the fields you need to ~/.kodax/config.json (strict JSON).
-// MCP, A2A, and Extensions live in ~/.kodax/integrations/*.json; use
-// `kodax integrations migrate --dry-run` for legacy declarations.
-{
-  // "provider": "deepseek",
-  // "model": "deepseek-v4",
-  // "runtimeMode": "embedded",
-  // "effort": "high",
-  // "agentMode": "ama",
-  // "permissionMode": "accept-edits",
-  // "locale": "zh",
-  // "customProviders": [
-  //   {
-  //     "name": "my-relay",
+// Split configs: ~/.kodax/integrations/mcp.json, extensions.json, and a2a.json.
+// KodaX core configuration template.
+// Copy only the fields you need to ~/.kodax/config.json (strict JSON).
+// MCP, A2A, and Extensions live in ~/.kodax/integrations/*.json; use
+// `kodax integrations migrate` to preview legacy declarations.
+{
+  // Active provider alias and optional model override. Run `kodax setup` or
+  // `/model` instead of editing these manually when possible.
+  // "provider": "deepseek",
+  // "model": "deepseek-v4-flash",
+  // Add or reorder model ids shown by `/model` for a provider.
+  // "providerModels": {
+  //   "deepseek": ["deepseek-v4-flash", "deepseek-v4-pro"]
+  // },
+
+  // Interactive Runtime hosting: "embedded" (this process) or "daemon".
+  // "runtimeMode": "embedded",
+
+  // Native model reasoning. `effort` is the preferred explicit depth;
+  // `reasoningCeiling` is the session ceiling. `reasoningMode` and `thinking`
+  // remain accepted for backward compatibility.
+  // "effort": "high",
+  // "planModeEffort": "high",
+  // "reasoningCeiling": "auto",
+  // "reasoningMode": "auto",
+  // "thinking": true,
+
+  // Agent harness: "ama" enables adaptive multi-agent use; "sa" forces one
+  // agent. Permission mode is "plan", "accept-edits", or classifier-backed
+  // "auto".
+  // "agentMode": "ama",
+  // "permissionMode": "accept-edits",
+  // User-level Bash allow patterns. Project additions belong in
+  // <project>/.kodax/config.local.json. Broad Bash(*) is rejected.
+  // "alwaysAllowTools": ["Bash(npm test)", "Bash(git status:*)"],
+  // "autoMode": {
+  //   "engine": "llm",
+  //   "classifierModel": "provider:model",
+  //   "timeoutMs": 20000,
+  //   "speculativeWindowMs": 500
+  // },
+
+  // UI/manual locale.
+  // "locale": "zh",
+
+  // Custom providers store public connection metadata only. Put the actual
+  // credential in the named environment variable, never in this file. Use
+  // `kodax setup --custom` for the guided writer.
+  // "customProviders": [
+  //   {
+  //     "name": "my-relay",
   //     "protocol": "openai",
-  //     "baseUrl": "https://api.example.com/v1",
-  //     "apiKeyEnv": "MY_RELAY_API_KEY",
-  //     "model": "provider/model",
-  //     "reasoning": { "efforts": ["off", "low", "high"], "default": "high" }
-  //   }
-  // ],
-  // "repoIntelligenceMode": "auto",
-  // Automatic large compaction is always enabled. Percentage defaults to 75
-  // and is clamped to 15..90. A missing/zero absolute threshold is inactive;
-  // otherwise the smaller percentage, absolute, and physical limit wins.
-  // "compaction": {
-  //   "triggerPercent": 75,
-  //   "triggerTokens": 0
-  // },
-  // "sessionRetentionDays": 0,
-  // "workflow": { "maxConcurrency": 8 }
-}
+  //     "baseUrl": "https://api.example.com/v1",
+  //     "apiKeyEnv": "MY_RELAY_API_KEY",
+  //     "model": "provider/model",
+  //     "models": ["provider/model", "provider/fast-model"],
+  //     "reasoning": { "efforts": ["off", "low", "high"], "default": "high" },
+  //     "userAgentMode": "compat",
+  //     "contextWindow": 128000,
+  //     "maxOutputTokens": 8192,
+  //     "thinkingBudgetCap": 32000,
+  //     "promptCacheAffinity": false,
+  //     "replayReasoningContent": false,
+  //     "strictThinkingSignature": false,
+  //     "streamMaxDurationMs": 300000,
+  //     "verifyStrategy": "models-list"
+  //   }
+  // ],
+
+  // Repository intelligence. Mode: "auto", "full", "light", or "off".
+  // "repoIntelligenceMode": "auto",
+  // "repoIntelligenceTrace": false,
+  // "repoIntelligence": {
+  //   "toolWaitMs": 250,
+  //   "workerTimeoutMs": 30000,
+  //   "workerOldSpaceMb": 1024,
+  //   "storageDir": "~/.kodax/repo-intelligence"
+  // },
+
+  // Runtime/provider diagnostics and timeouts.
+  // "streamIdleTimeoutMs": 120000,
+  // "verifierLog": false,
+  // "stallLog": false,
+
+  // Ordered provider fallback for child tasks and optional model tiers used by
+  // workflow/dispatch model hints.
+  // "fallbackProviders": ["ark-coding", "kimi-code"],
+  // "fastProvider": "openai",
+  // "fastModel": "gpt-5-mini",
+  // "deepProvider": "anthropic",
+  // "deepModel": "claude-opus-4-6",
+
+  // Provider/LSP/ACP process settings.
+  // "maxOutputTokens": 8192,
+  // "disablePromptCache": false,
+  // "lsp": true,
+  // "lspAutoDownload": false,
+  // "acpLogLevel": "info",
+
+  // Automatic large compaction is always enabled. Percentage defaults to 75
+  // and is clamped to 15..90. A missing/zero absolute threshold is inactive;
+  // otherwise the smaller percentage, absolute, and physical limit wins.
+  // "compaction": {
+  //   "enabled": true,
+  //   "contextWindow": 128000,
+  //   "triggerPercent": 75,
+  //   "triggerTokens": 0
+  // },
+
+  // 0 disables automatic session pruning.
+  // "sessionRetentionDays": 0,
+
+  // Workflow host concurrency. The Runtime still applies its system cap.
+  // "workflow": { "maxConcurrency": 8 }
+}

package/dist/chunks/agent-ASP4MS3X.js

@@ -0,0 +1,2 @@
+// @kodax-ai/kodax — bundled distribution. See docs/ADR.md ADR-022 + ADR-024.
+import{Ja as g,La as h,Ya as i,a as c,cb as j,ra as d,sa as e,ta as f}from"./chunk-TQDBTTIM.js";import"./chunk-Z3KFRTSB.js";import"./chunk-KQLQYHWU.js";import"./chunk-YAZQTC2L.js";import"./chunk-5NDCSFOP.js";import{qb as a,rb as b}from"./chunk-VAT2QYXM.js";import"./chunk-6XM4B6K2.js";import"./chunk-2CFHBKRE.js";import"./chunk-NXO6GWSY.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,j as runKodaX,i as saveSessionSnapshot,a as validateAndFixToolHistory};

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

@@ -0,0 +1,2 @@
+// @kodax-ai/kodax — bundled distribution. See docs/ADR.md ADR-022 + ADR-024.
+import{Ua as a,Va as b}from"./chunk-YVRYHC4C.js";import"./chunk-6YZUE6NC.js";import"./chunk-7OEBJGHK.js";import"./chunk-5GO6FH7L.js";import"./chunk-TQDBTTIM.js";import"./chunk-UID7BLAB.js";import"./chunk-Z3KFRTSB.js";import"./chunk-6FOJVETH.js";import"./chunk-KQLQYHWU.js";import"./chunk-YAZQTC2L.js";import"./chunk-5NDCSFOP.js";import"./chunk-VAT2QYXM.js";import"./chunk-6XM4B6K2.js";import"./chunk-2CFHBKRE.js";import"./chunk-NXO6GWSY.js";import"./chunk-ONUPGMER.js";export{a as ArgumentCompleter,b as createArgumentCompleter};

package/dist/chunks/{chunk-XSA37BVM.js → chunk-2CFHBKRE.js}

@@ -1,5 +1,5 @@
 // @kodax-ai/kodax — bundled distribution. See docs/ADR.md ADR-022 + ADR-024.
-import{g as R,h as _}from"./chunk-IQT4RPCE.js";import{a as r}from"./chunk-ONUPGMER.js";var g={user:0,background:1};function Z(t,e){return g[t]<=g[e]}r(Z,"priorityWithinMax");function O(t,e){return!(t.agentId!==e.agentId||!Z(t.priority,e.maxPriority)||e.mode!==void 0&&t.mode!==e.mode||e.id!==void 0&&t.id!==e.id||e.predicate&&!e.predicate(t))}r(O,"matchesFilter");var E=class{static{r(this,"MessageQueue")}messages=[];nextSeq=1;listeners=new Set;snapshotRef=Object.freeze([]);notify(e){this.snapshotRef=Object.freeze([...this.messages]);for(let i of this.listeners)try{i(e)}catch{}}subscribe=r(e=>(this.listeners.add(e),()=>{this.listeners.delete(e)}),"subscribe");getSnapshot=r(()=>this.snapshotRef,"getSnapshot");enqueue(e){let i=`msg-${this.nextSeq++}`,o={id:i,priority:e.priority,mode:e.mode,content:e.content,agentId:e.agentId,inputArtifacts:e.inputArtifacts,taskResult:e.taskResult,enqueuedAt:Date.now()};return this.messages=[...this.messages,o],this.notify({kind:"enqueued",message:o}),i}dequeue(e){let i=[];for(let s=0;s<this.messages.length;s++){let m=this.messages[s];m&&O(m,e)&&i.push({originalIndex:s,message:m})}i.sort((s,m)=>{let l=g[s.message.priority]-g[m.message.priority];return l!==0?l:s.originalIndex-m.originalIndex});let o=e.limit,n=typeof o=="number"&&i.length>o?i.slice(0,o):i;if(n.length===0)return[];let a=new Set(n.map(s=>s.originalIndex));this.messages=this.messages.filter((s,m)=>!a.has(m));let d=n.map(s=>s.message);return this.notify({kind:"dequeued",messages:d}),d}peek(e){let i=[];for(let a=0;a<this.messages.length;a++){let d=this.messages[a];d&&O(d,e)&&i.push({originalIndex:a,message:d})}i.sort((a,d)=>{let s=g[a.message.priority]-g[d.message.priority];return s!==0?s:a.originalIndex-d.originalIndex});let o=e.limit;return(typeof o=="number"&&i.length>o?i.slice(0,o):i).map(a=>a.message)}size(){return this.messages.length}count(e){return this.peek(e).length}has(e){return this.count(e)>0}clear(){if(this.messages.length===0)return;let e=this.messages;this.messages=[],this.notify({kind:"cleared",messages:e})}},w;function h(){return w||(w=new E),w}r(h,"getMessageQueue");function ee(){w=void 0}r(ee,"_resetMessageQueueForTests");function A(t,e){return t?`actor:${t}:${e}`:e==="/root"?void 0:e}r(A,"actorQueueId");var f=new Map;function te(t){f.set(t,(f.get(t)??0)+1);let e=!1;return()=>{if(e)return;e=!0;let i=f.get(t);i===void 0||i<=1?f.delete(t):f.set(t,i-1)}}r(te,"registerActiveRootQueueRoute");function x(){if(f.size!==0){if(f.size===1)return f.keys().next().value;throw new Error("Cannot infer queued follow-up target: multiple Actor root sessions are active. Pass sessionId or agentId explicitly.")}}r(x,"resolveActiveRootQueueRoute");function ie(){f.clear()}r(ie,"_resetActiveRootQueueRoutesForTests");var N=new Set(["wait_agent"]);function $(t){return t.some(i=>N.has(i))?"background":"user"}r($,"midTurnDrainPriority");function re(t){let e=$(t.lastTurnToolNames);return h().dequeue({agentId:t.agentId,maxPriority:e,limit:t.limit})}r(re,"maybeDrainMidTurn");var u=class extends Error{static{r(this,"KodaXMediaError")}code;detail;cause;constructor(e,i,o={}){super(i),this.name="KodaXMediaError",this.code=e,this.detail=o.detail,this.cause=o.cause}},p=class extends u{static{r(this,"ImageResizeError")}constructor(e,i={}){super(i.code??"IMAGE_TOO_LARGE",e,i),this.name="ImageResizeError"}};import F from"node:path";var ne={".gif":"image/gif",".jpeg":"image/jpeg",".jpg":"image/jpeg",".png":"image/png",".webp":"image/webp"},oe={".3gp":"video/3gpp",".3gpp":"video/3gpp",".avi":"video/x-msvideo",".flv":"video/x-flv",".mov":"video/quicktime",".mp4":"video/mp4",".mpeg":"video/mpeg",".mpg":"video/mpeg",".webm":"video/webm",".wmv":"video/x-ms-wmv"};function C(t){return ne[F.extname(t).toLowerCase()]}r(C,"inferImageMediaType");function U(t){return oe[F.extname(t).toLowerCase()]}r(U,"inferVideoMediaType");function ae(t,e={}){let i=e.mediaType??C(t);return{kind:"image",path:t,...i?{mediaType:i}:{},...e.source?{source:e.source}:{},...e.description?{description:e.description}:{}}}r(ae,"createImageArtifactFromPath");function se(t,e={}){if(e.mediaType!==void 0&&e.mimeType!==void 0&&e.mediaType!==e.mimeType)throw new u("UNSUPPORTED_MEDIA_TYPE",`File artifact mediaType and mimeType disagree: ${e.mediaType} != ${e.mimeType}.`);return{kind:"file",path:t,...e.mediaType?{mediaType:e.mediaType}:{},...e.mimeType?{mimeType:e.mimeType}:{},...e.name?{name:e.name}:{},...e.source?{source:e.source}:{},...e.description?{description:e.description}:{}}}r(se,"createFileArtifactFromPath");function de(t,e={}){let i=e.mediaType??U(t);if(!i)throw new u("UNSUPPORTED_MEDIA_TYPE",`Cannot infer video media type from path: ${t}.`);return{kind:"video",path:t,mediaType:i,...e.name?{name:e.name}:{},...e.source?{source:e.source}:{},...e.description?{description:e.description}:{}}}r(de,"createVideoArtifactFromPath");import{Jimp as me}from"jimp";var K=2e3,L=Math.floor(3.75*1024*1024),ue=[80,60,40];async function k(t,e={}){let i=e.maxDimension??K,o=e.targetBytes??L;if(t.length===0)throw new p("Empty image buffer.",{code:"IMAGE_DECODE_FAILED"});let n;try{n=await me.read(t)}catch(c){let I=c instanceof Error?c.message:String(c);throw new p(`Failed to decode image: ${I}`,{code:"IMAGE_DECODE_FAILED",cause:c})}let{width:a,height:d}=n.bitmap,s=Math.max(a,d);if(s>i){let c=i/s;n.resize({w:Math.max(1,Math.round(a*c)),h:Math.max(1,Math.round(d*c))})}let m=n.bitmap.width,l=n.bitmap.height;if(e.preferMediaType!=="image/jpeg"){let c=await n.getBuffer("image/png");if(c.length<=o)return{buffer:Buffer.from(c),mediaType:"image/png",width:m,height:l}}for(let c of ue){let I=await n.getBuffer("image/jpeg",{quality:c});if(I.length<=o)return{buffer:Buffer.from(I),mediaType:"image/jpeg",width:m,height:l}}if(e.preferMediaType==="image/jpeg"){let c=await n.getBuffer("image/png");if(c.length<=o)return{buffer:Buffer.from(c),mediaType:"image/png",width:m,height:l}}throw new p(`Image still exceeds budget (${o} bytes raw) after PNG and JPEG q40 compression. Try a smaller image or take a fresh screenshot of a smaller region.`,{code:"IMAGE_TOO_LARGE"})}r(k,"normalizePastedImage");import{spawn as j}from"node:child_process";import{mkdtemp as ce,readFile as fe,rm as pe}from"node:fs/promises";import{tmpdir as le}from"node:os";import q from"node:path";var B=5e3;async function G(){switch(process.platform){case"darwin":return he();case"win32":return Te();case"linux":return ye();default:throw new u("UNSUPPORTED_PLATFORM",`Clipboard image fallback is not supported on platform "${process.platform}".`)}}r(G,"readClipboardImage");async function ge(t={}){let e=await G();return e?k(e,t):null}r(ge,"readAndNormalizeClipboardImage");async function Y(t){let e=await ce(q.join(le(),"kodax-clip-")),i=q.join(e,"clip.png");try{return await t(i)}finally{await pe(e,{recursive:!0,force:!0}).catch(o=>{})}}r(Y,"runWithTempPng");async function he(){return Y(async t=>{let e=`set png_data to (the clipboard as \xABclass PNGf\xBB)
+import{g as R,h as _}from"./chunk-NXO6GWSY.js";import{a as r}from"./chunk-ONUPGMER.js";var g={user:0,background:1};function Z(t,e){return g[t]<=g[e]}r(Z,"priorityWithinMax");function O(t,e){return!(t.agentId!==e.agentId||!Z(t.priority,e.maxPriority)||e.mode!==void 0&&t.mode!==e.mode||e.id!==void 0&&t.id!==e.id||e.predicate&&!e.predicate(t))}r(O,"matchesFilter");var E=class{static{r(this,"MessageQueue")}messages=[];nextSeq=1;listeners=new Set;snapshotRef=Object.freeze([]);notify(e){this.snapshotRef=Object.freeze([...this.messages]);for(let i of this.listeners)try{i(e)}catch{}}subscribe=r(e=>(this.listeners.add(e),()=>{this.listeners.delete(e)}),"subscribe");getSnapshot=r(()=>this.snapshotRef,"getSnapshot");enqueue(e){let i=`msg-${this.nextSeq++}`,o={id:i,priority:e.priority,mode:e.mode,content:e.content,agentId:e.agentId,inputArtifacts:e.inputArtifacts,taskResult:e.taskResult,enqueuedAt:Date.now()};return this.messages=[...this.messages,o],this.notify({kind:"enqueued",message:o}),i}dequeue(e){let i=[];for(let s=0;s<this.messages.length;s++){let m=this.messages[s];m&&O(m,e)&&i.push({originalIndex:s,message:m})}i.sort((s,m)=>{let l=g[s.message.priority]-g[m.message.priority];return l!==0?l:s.originalIndex-m.originalIndex});let o=e.limit,n=typeof o=="number"&&i.length>o?i.slice(0,o):i;if(n.length===0)return[];let a=new Set(n.map(s=>s.originalIndex));this.messages=this.messages.filter((s,m)=>!a.has(m));let d=n.map(s=>s.message);return this.notify({kind:"dequeued",messages:d}),d}peek(e){let i=[];for(let a=0;a<this.messages.length;a++){let d=this.messages[a];d&&O(d,e)&&i.push({originalIndex:a,message:d})}i.sort((a,d)=>{let s=g[a.message.priority]-g[d.message.priority];return s!==0?s:a.originalIndex-d.originalIndex});let o=e.limit;return(typeof o=="number"&&i.length>o?i.slice(0,o):i).map(a=>a.message)}size(){return this.messages.length}count(e){return this.peek(e).length}has(e){return this.count(e)>0}clear(){if(this.messages.length===0)return;let e=this.messages;this.messages=[],this.notify({kind:"cleared",messages:e})}},w;function h(){return w||(w=new E),w}r(h,"getMessageQueue");function ee(){w=void 0}r(ee,"_resetMessageQueueForTests");function A(t,e){return t?`actor:${t}:${e}`:e==="/root"?void 0:e}r(A,"actorQueueId");var f=new Map;function te(t){f.set(t,(f.get(t)??0)+1);let e=!1;return()=>{if(e)return;e=!0;let i=f.get(t);i===void 0||i<=1?f.delete(t):f.set(t,i-1)}}r(te,"registerActiveRootQueueRoute");function x(){if(f.size!==0){if(f.size===1)return f.keys().next().value;throw new Error("Cannot infer queued follow-up target: multiple Actor root sessions are active. Pass sessionId or agentId explicitly.")}}r(x,"resolveActiveRootQueueRoute");function ie(){f.clear()}r(ie,"_resetActiveRootQueueRoutesForTests");var N=new Set(["wait_agent"]);function $(t){return t.some(i=>N.has(i))?"background":"user"}r($,"midTurnDrainPriority");function re(t){let e=$(t.lastTurnToolNames);return h().dequeue({agentId:t.agentId,maxPriority:e,limit:t.limit})}r(re,"maybeDrainMidTurn");var u=class extends Error{static{r(this,"KodaXMediaError")}code;detail;cause;constructor(e,i,o={}){super(i),this.name="KodaXMediaError",this.code=e,this.detail=o.detail,this.cause=o.cause}},p=class extends u{static{r(this,"ImageResizeError")}constructor(e,i={}){super(i.code??"IMAGE_TOO_LARGE",e,i),this.name="ImageResizeError"}};import F from"node:path";var ne={".gif":"image/gif",".jpeg":"image/jpeg",".jpg":"image/jpeg",".png":"image/png",".webp":"image/webp"},oe={".3gp":"video/3gpp",".3gpp":"video/3gpp",".avi":"video/x-msvideo",".flv":"video/x-flv",".mov":"video/quicktime",".mp4":"video/mp4",".mpeg":"video/mpeg",".mpg":"video/mpeg",".webm":"video/webm",".wmv":"video/x-ms-wmv"};function C(t){return ne[F.extname(t).toLowerCase()]}r(C,"inferImageMediaType");function U(t){return oe[F.extname(t).toLowerCase()]}r(U,"inferVideoMediaType");function ae(t,e={}){let i=e.mediaType??C(t);return{kind:"image",path:t,...i?{mediaType:i}:{},...e.source?{source:e.source}:{},...e.description?{description:e.description}:{}}}r(ae,"createImageArtifactFromPath");function se(t,e={}){if(e.mediaType!==void 0&&e.mimeType!==void 0&&e.mediaType!==e.mimeType)throw new u("UNSUPPORTED_MEDIA_TYPE",`File artifact mediaType and mimeType disagree: ${e.mediaType} != ${e.mimeType}.`);return{kind:"file",path:t,...e.mediaType?{mediaType:e.mediaType}:{},...e.mimeType?{mimeType:e.mimeType}:{},...e.name?{name:e.name}:{},...e.source?{source:e.source}:{},...e.description?{description:e.description}:{}}}r(se,"createFileArtifactFromPath");function de(t,e={}){let i=e.mediaType??U(t);if(!i)throw new u("UNSUPPORTED_MEDIA_TYPE",`Cannot infer video media type from path: ${t}.`);return{kind:"video",path:t,mediaType:i,...e.name?{name:e.name}:{},...e.source?{source:e.source}:{},...e.description?{description:e.description}:{}}}r(de,"createVideoArtifactFromPath");import{Jimp as me}from"jimp";var K=2e3,L=Math.floor(3.75*1024*1024),ue=[80,60,40];async function k(t,e={}){let i=e.maxDimension??K,o=e.targetBytes??L;if(t.length===0)throw new p("Empty image buffer.",{code:"IMAGE_DECODE_FAILED"});let n;try{n=await me.read(t)}catch(c){let I=c instanceof Error?c.message:String(c);throw new p(`Failed to decode image: ${I}`,{code:"IMAGE_DECODE_FAILED",cause:c})}let{width:a,height:d}=n.bitmap,s=Math.max(a,d);if(s>i){let c=i/s;n.resize({w:Math.max(1,Math.round(a*c)),h:Math.max(1,Math.round(d*c))})}let m=n.bitmap.width,l=n.bitmap.height;if(e.preferMediaType!=="image/jpeg"){let c=await n.getBuffer("image/png");if(c.length<=o)return{buffer:Buffer.from(c),mediaType:"image/png",width:m,height:l}}for(let c of ue){let I=await n.getBuffer("image/jpeg",{quality:c});if(I.length<=o)return{buffer:Buffer.from(I),mediaType:"image/jpeg",width:m,height:l}}if(e.preferMediaType==="image/jpeg"){let c=await n.getBuffer("image/png");if(c.length<=o)return{buffer:Buffer.from(c),mediaType:"image/png",width:m,height:l}}throw new p(`Image still exceeds budget (${o} bytes raw) after PNG and JPEG q40 compression. Try a smaller image or take a fresh screenshot of a smaller region.`,{code:"IMAGE_TOO_LARGE"})}r(k,"normalizePastedImage");import{spawn as j}from"node:child_process";import{mkdtemp as ce,readFile as fe,rm as pe}from"node:fs/promises";import{tmpdir as le}from"node:os";import q from"node:path";var B=5e3;async function G(){switch(process.platform){case"darwin":return he();case"win32":return Te();case"linux":return ye();default:throw new u("UNSUPPORTED_PLATFORM",`Clipboard image fallback is not supported on platform "${process.platform}".`)}}r(G,"readClipboardImage");async function ge(t={}){let e=await G();return e?k(e,t):null}r(ge,"readAndNormalizeClipboardImage");async function Y(t){let e=await ce(q.join(le(),"kodax-clip-")),i=q.join(e,"clip.png");try{return await t(i)}finally{await pe(e,{recursive:!0,force:!0}).catch(o=>{})}}r(Y,"runWithTempPng");async function he(){return Y(async t=>{let e=`set png_data to (the clipboard as \xABclass PNGf\xBB)
 set fh to open for access POSIX file "${t.replace(/"/g,'\\"')}" with write permission
 write png_data to fh
 close access fh`;return await Q("osascript",["-e",e])?z(t):null})}r(he,"readMacClipboard");async function Te(){return Y(async t=>{let e=["Add-Type -AssemblyName System.Drawing | Out-Null","$img = Get-Clipboard -Format Image","if ($null -eq $img) { exit 1 }",`$img.Save('${t.replace(/'/g,"''")}', [System.Drawing.Imaging.ImageFormat]::Png)`].join("; ");return await Q("powershell",["-NoProfile","-Command",e])?z(t):null})}r(Te,"readWinClipboard");async function ye(){return await X("wl-paste",["--type","image/png"])??X("xclip",["-selection","clipboard","-t","image/png","-o"])}r(ye,"readLinuxClipboard");async function z(t){try{let e=await fe(t);return e.length>0?e:null}catch(e){return null}}r(z,"readNonEmptyFile");function Q(t,e){return new Promise(i=>{let o=!1,n=j(t,[...e],{stdio:"ignore",windowsHide:!0}),a=setTimeout(()=>{o||(o=!0,n.kill(),i(!1))},B);n.once("error",()=>{o||(o=!0,clearTimeout(a),i(!1))}),n.once("exit",d=>{o||(o=!0,clearTimeout(a),i(d===0))})})}r(Q,"runCommand");function X(t,e){return new Promise(i=>{let o=!1,n=[],a=j(t,[...e],{stdio:["ignore","pipe","ignore"],windowsHide:!0}),d=setTimeout(()=>{o||(o=!0,a.kill(),i(null))},B);a.stdout?.on("data",s=>n.push(s)),a.once("error",()=>{o||(o=!0,clearTimeout(d),i(null))}),a.once("exit",s=>{if(o)return;if(o=!0,clearTimeout(d),s!==0){i(null);return}let m=Buffer.concat(n);i(m.length>0?m:null)})})}r(X,"collectStdoutBytes");import{createHash as Ie}from"node:crypto";import{mkdir as we,readdir as Ee,stat as _e,unlink as Ae,writeFile as xe}from"node:fs/promises";import{tmpdir as ke}from"node:os";import M from"node:path";var V="KODAX_PASTE_TMP_DIR",W=1440*60*1e3;function H(){return process.env[V]??M.join(ke(),"kodax-paste")}r(H,"resolvePasteTmpDir");function Me(t){let e=t?.trim().replace(/[^A-Za-z0-9._-]+/g,"-").replace(/^-+|-+$/g,"");return e&&e.length>0?e:"paste"}r(Me,"sanitizeFileNamePrefix");async function De(t,e={}){let i=e.directory??H();await we(i,{recursive:!0});let o=t.mediaType==="image/jpeg"?".jpg":".png",n=Ie("sha256").update(t.buffer).digest("hex").slice(0,16),a=`${Me(e.fileNamePrefix)}-${n}${o}`,d=M.join(i,a);return await xe(d,t.buffer),{type:"image",path:d,mediaType:t.mediaType}}r(De,"persistImageAsBlock");async function Pe(t=Date.now()){let e=H(),i;try{i=await Ee(e)}catch(a){return 0}let o=t-W,n=0;return await Promise.all(i.filter(a=>/-[0-9a-f]{16}\.(?:png|jpg)$/.test(a)).map(async a=>{let d=M.join(e,a);try{(await _e(d)).mtimeMs<o&&(await Ae(d),n+=1)}catch(s){}})),n}r(Pe,"prunePasteTmpDir");var T=["image/png","image/jpeg","image/webp","image/gif"],y=["video/mp4","video/mpeg","video/quicktime","video/x-msvideo","video/x-flv","video/webm","video/x-ms-wmv","video/3gpp"],ve=[],Se=new Set(["anthropic","openai"]),be=new Set(["ark-coding/doubao-seed-2.0-code","ark-coding/doubao-seed-2.0-pro","ark-coding/kimi-k2.6","ark-coding/kimi-k2.7-code","ark-coding/minimax-m3","kimi-code/k3-256k","qwen-token-plan/qwen3.8-max-preview","qwen-token-plan/qwen3.7-plus","qwen-token-plan/qwen3.6-flash"]),Re=new Set(["kimi-code/kimi-for-coding","kimi-code/kimi-for-coding-highspeed","kimi-code/k3","kimi/kimi-k3","kimi/kimi-k2.5","kimi/kimi-k2.6","kimi/kimi-k2.7-code","kimi/kimi-k2.7-code-highspeed","minimax-coding/minimax-m3","minimax/minimax-m3","mimo-coding/mimo-v2.5","mimo/mimo-v2.5"]);function D(t){return{nativeSupported:!1,sdkSupported:!1,status:"unsupported",mediaTypes:[],maxCount:0,reason:t}}r(D,"unsupported");function Oe(t){return{nativeSupported:!0,sdkSupported:!0,status:"supported",mediaTypes:T,nativeMediaTypes:T,reason:t}}r(Oe,"supportedImage");function Ne(t){return{nativeSupported:!0,sdkSupported:!1,status:"provider-native-unwired",mediaTypes:[],nativeMediaTypes:y,maxCount:0,reason:t}}r(Ne,"nativeVideoUnwired");function $e(t){return t.trim().toLowerCase()}r($e,"normalizeProvider");function Fe(t){return _[t]?.model}r(Fe,"resolveProviderDefaultModel");function J(t,e){if(!e)return;let i=e.trim().toLowerCase();if(t==="kimi"){if(i==="k2.5")return"kimi-k2.5";if(i==="k2.6")return"kimi-k2.6";if(i==="k2.7-code")return"kimi-k2.7-code";if(i==="k2.7-code-highspeed")return"kimi-k2.7-code-highspeed"}return(t==="minimax-coding"||t==="minimax")&&i==="minimax-m3"?"minimax-m3":i}r(J,"normalizeModel");function Ce(t){if(!Se.has(t))return!1;let e=_[t];return e?R(e.capabilityProfile).multimodalSupport!=="none":!1}r(Ce,"hasOfficialImageSupport");function Ue(t,e){let i=J(t,e);if(!i)return!1;let o=`${t}/${i}`;return Re.has(o)}r(Ue,"hasSourceBackedNativeMedia");function Ke(t,e){let i=J(t,e);return i?be.has(`${t}/${i}`):!1}r(Ke,"hasSourceBackedImage");function Le(t,e,i){if(i)return"source-backed";if(e){if(t==="openai")return"openai-official";if(t==="anthropic")return"anthropic-official"}}r(Le,"resolveImageCapabilityRoute");function qe(t){switch(t){case"openai-official":return"Model route supports KodaX image input. Direct-path image/gif is sent as image/gif, but OpenAI requires non-animated GIF semantics.";case"anthropic-official":return"Model route supports KodaX image input. Direct-path image/gif is sent as image/gif, but Anthropic uses only the first frame of animated GIFs.";case"source-backed":return"Model route supports KodaX image input. Direct-path image/gif is sent as image/gif; animated-GIF interpretation is provider-owned."}}r(qe,"imageCapabilityReason");function P(t){let e=$e(t.provider),i=t.model?.trim()||Fe(e),o=Ce(e),n=Ue(e,i),a=n||Ke(e,i),d=Le(e,o,a),s=d!==void 0,m=n;return{text:!0,image:s?Oe(qe(d)):D("No verified KodaX image-input route for this provider/model."),video:m?Ne("Model route is native-video capable, but KodaX SDK video sending is not wired yet. Reject or downgrade before send."):D("No verified native video route for this provider/model."),file:D("File artifact contract is stable, but KodaX SDK file sending/extraction is not wired yet. Reject or downgrade before send.")}}r(P,"getModelInputCapabilities");function Xe(t){return T.includes(t)}r(Xe,"isKnownImageMediaType");function je(t){return y.includes(t)}r(je,"isKnownVideoMediaType");function v(t){return`${t.provider}${t.model?`/${t.model}`:""}`}r(v,"routeLabel");function S(t){return t.reason?`${t.status}: ${t.reason}`:t.status}r(S,"capabilityDetail");function b(t,e){if(t.length===0)return;let i=P(e);for(let o of t){let n=o;if(n.kind==="image"){if(!i.image.nativeSupported||!i.image.sdkSupported)throw new u("MODEL_INPUT_UNSUPPORTED",`Provider/model cannot consume image artifacts: ${v(e)}.`,{detail:S(i.image)});if(typeof n.mediaType=="string"&&!Xe(n.mediaType))throw new u("UNSUPPORTED_MEDIA_TYPE",`Unsupported image media type: ${n.mediaType}.`);continue}throw n.kind==="video"?typeof n.mediaType!="string"||!je(n.mediaType)?new u("UNSUPPORTED_MEDIA_TYPE",`Unsupported video media type: ${String(n.mediaType)}.`,{detail:`Supported video media types: ${y.join(", ")}`}):new u("MODEL_INPUT_UNSUPPORTED",`Provider/model cannot consume video artifacts through this SDK runtime: ${v(e)}.`,{detail:S(i.video)}):n.kind==="file"?typeof n.mediaType=="string"&&typeof n.mimeType=="string"&&n.mediaType!==n.mimeType?new u("UNSUPPORTED_MEDIA_TYPE",`File artifact mediaType and mimeType disagree: ${n.mediaType} != ${n.mimeType}.`):new u("MODEL_INPUT_UNSUPPORTED",`Provider/model cannot consume file artifacts through this SDK runtime: ${v(e)}.`,{detail:S(i.file)}):new u("MODEL_INPUT_UNSUPPORTED",`Unsupported input artifact kind: ${String(n.kind)}.`)}}r(b,"validateInputArtifactsForModel");function Be(t){if(b(t.inputArtifacts??[],t),t.agentId!==void 0&&t.sessionId!==void 0)throw new Error("enqueueWithArtifacts accepts either agentId or sessionId, not both.");if(t.sessionId!==void 0&&t.sessionId.trim().length===0)throw new Error("enqueueWithArtifacts sessionId must not be empty.");let e=t.agentId??(t.sessionId!==void 0?A(t.sessionId,"/root"):x());return h().enqueue({priority:t.priority??"user",mode:"prompt",content:t.content,agentId:e,inputArtifacts:t.inputArtifacts})}r(Be,"enqueueWithArtifacts");export{E as a,h as b,ee as c,A as d,te as e,x as f,ie as g,N as h,$ as i,re as j,u as k,p as l,C as m,U as n,ae as o,se as p,de as q,K as r,L as s,k as t,G as u,ge as v,V as w,W as x,De as y,Pe as z,T as A,y as B,ve as C,P as D,b as E,Be as F};