@kodax-ai/kodax 0.7.72 → 0.7.74

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (91) hide show
  1. package/CHANGELOG.md +226 -0
  2. package/README.md +72 -18
  3. package/README_CN.md +55 -14
  4. package/config-templates/config.example.jsonc +7 -0
  5. package/dist/chunks/agent-2ABIG5NW.js +2 -0
  6. package/dist/chunks/argument-completer-C45DEO34.js +2 -0
  7. package/dist/chunks/chunk-5GH3SVI3.js +74 -0
  8. package/dist/chunks/{chunk-SQODXBLX.js → chunk-64M5HOCA.js} +1 -1
  9. package/dist/chunks/{chunk-PKQOEDHJ.js → chunk-7W6KYJU2.js} +224 -230
  10. package/dist/chunks/chunk-C7TZAT3S.js +369 -0
  11. package/dist/chunks/chunk-F7AIEHSS.js +46 -0
  12. package/dist/chunks/{chunk-E27LHEIP.js → chunk-GAFFYJU3.js} +1 -1
  13. package/dist/chunks/chunk-KPGVY6PF.js +321 -0
  14. package/dist/chunks/{chunk-44QXPEEE.js → chunk-MBAPT2R5.js} +1 -1
  15. package/dist/chunks/{chunk-IR5KIK7E.js → chunk-MVCAFD6M.js} +1 -1
  16. package/dist/chunks/chunk-PP53SIIL.js +5 -0
  17. package/dist/chunks/chunk-QH56WEHK.js +2 -0
  18. package/dist/chunks/chunk-UJS7JAO6.js +770 -0
  19. package/dist/chunks/{chunk-MVARIMQV.js → chunk-VK5QTHS6.js} +6 -6
  20. package/dist/chunks/chunk-VPURXE2F.js +427 -0
  21. package/dist/chunks/chunk-XM724XAA.js +329 -0
  22. package/dist/chunks/{chunk-WIBLZK4G.js → chunk-XMP66YWG.js} +11 -4
  23. package/dist/chunks/chunk-XXQLPTAN.js +78 -0
  24. package/dist/chunks/compaction-config-QYCDOW3Q.js +2 -0
  25. package/dist/chunks/{construction-bootstrap-ZJPXUPXQ.js → construction-bootstrap-BKNPJI7O.js} +1 -1
  26. package/dist/chunks/dist-6EK4H7TP.js +2 -0
  27. package/dist/chunks/{dist-GOUP4YVE.js → dist-EVEJAII2.js} +1 -1
  28. package/dist/chunks/host-KS4TJKWQ.js +2 -0
  29. package/dist/chunks/run-manager-L7MKGQNX.js +2 -0
  30. package/dist/chunks/{utils-OTT5CG5J.js → utils-GTJLL4GT.js} +1 -1
  31. package/dist/index.d.ts +17 -16
  32. package/dist/index.js +5 -5
  33. package/dist/kodax_cli.js +1357 -1294
  34. package/dist/provider-capabilities.json +184 -5
  35. package/dist/runtime-worker.js +1277 -1224
  36. package/dist/sdk-a2a.d.ts +11 -10
  37. package/dist/sdk-a2a.js +1 -1
  38. package/dist/sdk-agent.d.ts +110 -62
  39. package/dist/sdk-agent.js +1 -1
  40. package/dist/sdk-coding.d.ts +114 -32
  41. package/dist/sdk-coding.js +1 -1
  42. package/dist/sdk-experimental-memory.d.ts +1 -1
  43. package/dist/sdk-experimental-memory.js +1 -1
  44. package/dist/sdk-llm.d.ts +8 -49
  45. package/dist/sdk-llm.js +1 -1
  46. package/dist/sdk-mcp.js +1 -1
  47. package/dist/sdk-media.d.ts +1 -1
  48. package/dist/sdk-media.js +1 -1
  49. package/dist/sdk-repl.d.ts +153 -24
  50. package/dist/sdk-repl.js +2 -2
  51. package/dist/sdk-runtime.d.ts +238 -19
  52. package/dist/sdk-runtime.js +1 -1
  53. package/dist/sdk-session.d.ts +6 -6
  54. package/dist/sdk-session.js +1 -1
  55. package/dist/sdk-skills.js +1 -1
  56. package/dist/semantic-worker.js +16 -14
  57. package/dist/types-chunks/{base.d-Cz_rwpOi.d.ts → base.d-ChvpaKjZ.d.ts} +1 -1
  58. package/dist/types-chunks/{bash-prefix-extractor.d-CHJO5y94.d.ts → bash-prefix-extractor.d-r1beOESM.d.ts} +50 -14
  59. package/dist/types-chunks/{capability-learning.d-_lR0J4iR.d.ts → capability-learning.d-DPrYxRjF.d.ts} +1 -1
  60. package/dist/types-chunks/{capsule.d-DxtdE-GD.d.ts → capsule.d-zeqV4IQX.d.ts} +11 -3
  61. package/dist/types-chunks/{commands.d-DZxHzH5-.d.ts → commands.d-DUxnK2TU.d.ts} +67 -8
  62. package/dist/types-chunks/{guardrail.d-DlpMnd-Y.d.ts → guardrail.d-CWYD1bdL.d.ts} +2 -1
  63. package/dist/types-chunks/{guardrail.d-auV61_h5.d.ts → guardrail.d-qjuKJZ31.d.ts} +79 -18
  64. package/dist/types-chunks/history-retrieval.d-BKTJIrVd.d.ts +57 -0
  65. package/dist/types-chunks/{public-api.d--IDNJsu1.d.ts → public-api.d-CX4B11qY.d.ts} +19 -5
  66. package/dist/types-chunks/{run-manager.d-Bh50OdVl.d.ts → run-manager.d-B9fEIjZk.d.ts} +1 -1
  67. package/dist/types-chunks/{sdk-session-Cfw6NFu-.d.ts → sdk-session-B0fhAOPa.d.ts} +3 -3
  68. package/dist/types-chunks/{resolver.d-ssgNSlrh.d.ts → side-query.d-DWTMsndP.d.ts} +68 -5
  69. package/dist/types-chunks/{types.d-EqQmHztg.d.ts → types.d-Bm_y6YuM.d.ts} +16 -9
  70. package/dist/types-chunks/{types.d-Cqaw71Ax.d.ts → types.d-CSmF0t0n.d.ts} +6 -5
  71. package/dist/types-chunks/{types.d-CNZgY52F.d.ts → types.d-DEctY20M.d.ts} +10 -3
  72. package/dist/types-chunks/{types.d-DH1mvdcl.d.ts → types.d-sRLugmjy.d.ts} +64 -15
  73. package/dist/types-chunks/{utils.d-gmn3c5U4.d.ts → utils.d-D0wPxz8y.d.ts} +94 -10
  74. package/docs/SDK_EMBEDDER_GUIDE.md +1952 -1573
  75. package/package.json +9 -2
  76. package/dist/chunks/agent-YKGU4USA.js +0 -2
  77. package/dist/chunks/argument-completer-QZETLNAB.js +0 -2
  78. package/dist/chunks/chunk-23X6REO4.js +0 -46
  79. package/dist/chunks/chunk-2RI252RN.js +0 -2
  80. package/dist/chunks/chunk-CLFP6UGU.js +0 -71
  81. package/dist/chunks/chunk-EDZ5KJFT.js +0 -5
  82. package/dist/chunks/chunk-GIK4SGAT.js +0 -364
  83. package/dist/chunks/chunk-GVWPHE23.js +0 -310
  84. package/dist/chunks/chunk-JSDLBXME.js +0 -755
  85. package/dist/chunks/chunk-VDGCGOQH.js +0 -328
  86. package/dist/chunks/chunk-VVE3UM4F.js +0 -410
  87. package/dist/chunks/chunk-ZJIMT5I3.js +0 -78
  88. package/dist/chunks/compaction-config-TWCDFLX6.js +0 -2
  89. package/dist/chunks/dist-JT4ATXVM.js +0 -2
  90. package/dist/chunks/host-SVEDZUC5.js +0 -2
  91. package/dist/chunks/run-manager-RX42UNEM.js +0 -2
package/README_CN.md CHANGED
@@ -17,7 +17,7 @@
17
17
  <a href="LICENSE"><img alt="license" src="https://img.shields.io/badge/license-KAI--FCL_1.0-orange?style=flat-square"></a>
18
18
  <a href="https://github.com/icetomoyo/KodaX/stargazers"><img alt="GitHub stars" src="https://img.shields.io/github/stars/icetomoyo/KodaX?style=flat-square&logo=github&color=f1c40f"></a>
19
19
  <a href="https://github.com/icetomoyo/KodaX/actions"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/icetomoyo/KodaX/release.yml?style=flat-square&label=release"></a>
20
- <img alt="providers" src="https://img.shields.io/badge/LLMs-15_aliases_+_custom-2ecc71?style=flat-square">
20
+ <img alt="providers" src="https://img.shields.io/badge/LLMs-16_aliases_+_custom-2ecc71?style=flat-square">
21
21
  </p>
22
22
 
23
23
  <p align="center">
@@ -44,12 +44,15 @@ npm i -g @kodax-ai/kodax
44
44
  # 选一个你有 API key 的 provider
45
45
  export ZHIPU_API_KEY=... # 或 KIMI_API_KEY / MINIMAX_API_KEY / MIMO_API_KEY /
46
46
  # ARK_API_KEY / DEEPSEEK_API_KEY / ANTHROPIC_API_KEY /
47
- # OPENAI_API_KEY / QWEN_API_KEY / GEMINI_API_KEY
47
+ # OPENAI_API_KEY / QWEN_API_KEY / QWEN_TOKEN_API_KEY / GEMINI_API_KEY
48
48
 
49
49
  kodax
50
50
  ```
51
51
 
52
- 就这样。进 REPL,自然语言提问。
52
+ 就这样。进 REPL,自然语言提问。如果新机器既没有选择 provider,也没有任何
53
+ 受支持的 API Key 环境变量,直接运行 `kodax` 会先打开只配置元数据的向导;它不会
54
+ 要求输入或保存 Key。选择 provider/model 后,按提示设置对应环境变量、重启终端,
55
+ 再运行 `kodax`。需要主动重新配置时可运行 `kodax setup`。
53
56
 
54
57
  > **不装 Node 的目标机器**:从 [GitHub Releases](https://github.com/icetomoyo/KodaX/releases) 拿 Bun 编译的单文件二进制(Win / macOS / Linux × x64 + arm64)。详见 [docs/release.md](docs/release.md)。
55
58
 
@@ -88,13 +91,23 @@ daemon,不会再次打开 GUI。`ELECTRON_RUN_AS_NODE` 只存在于子进程
88
91
  再使用 attach-only 模式连接。SDK 的 `homeDir` 是拥有 `.kodax` 的 CLI 风格基础目录,
89
92
  不是 `.kodax` 目录本身。
90
93
 
91
- **v0.7.72 Runtime 修正:**Auto Mode 的权限决策由 Runtime Session 持有,
94
+ **v0.7.72–v0.7.73 Runtime 权限契约:**Auto Mode 的权限决策由 Runtime Session 持有,
92
95
  不再由 UI hook 抢先决定。Runtime 会跨 turn 复用 LLM/rules guardrail,先分类、
93
96
  仅在 `escalate` 时创建共享 permission 请求,并把自动降级到 rules 的结果持久化到
94
- session。Session 也可设置 classifier model 和有界 timeout;没有宿主审批回调时,
97
+ session。Session 也可设置 classifier model 和有界 timeout;`auto` 默认使用 LLM
98
+ 分类,没有有效 classifier model 时会在调用 provider 或创建审批前返回可恢复配置错误,
99
+ 绝不静默退回 rules。Runtime 权限请求可给出由 Runtime 生成的精确作用域建议:一次允许、
100
+ 本 Session 允许,或(仅安全场景)持久允许;客户端只能回传不透明 suggestion id,不能从
101
+ 预览内容自行扩大范围。持久授权由 daemon 持有并通过 revision 管理。没有宿主审批回调时,
95
102
  不会向模型暴露 `exit_plan_mode`。完整 SDK 接入见
96
103
  [Runtime Auto Mode 指引](docs/SDK_EMBEDDER_GUIDE.md#24-runtime-owned-auto-mode-and-plan-approval-bridges-v072)。
97
104
 
105
+ **v0.7.74 Auto 切换可靠性:**默认用 `Shift+Tab` 在 `Plan -> Edits -> Auto`
106
+ 之间循环,`Shift+Enter` 仍用于换行。进入 Auto 时状态栏会立即显示已解析的
107
+ `Auto[LLM]` 或 `Auto[RULES]`,同一 Session 的 Runtime 设置按键入顺序串行提交,
108
+ 快速循环不会让较早的异步结果覆盖最后一次选择。`Auto[RULES]` 可能是自动降级或
109
+ 手动选择后的合法粘性状态;使用 `/auto-engine llm` 可显式恢复 LLM 分类。
110
+
98
111
  ## 为什么用 KodaX
99
112
 
100
113
  <table>
@@ -174,7 +187,14 @@ kodax
174
187
 
175
188
  ### 2. 配置模型提供商
176
189
 
177
- 最简单的方式是先设置 API Key:
190
+ 可以先运行不会收集 Key 的交互配置:
191
+
192
+ ```bash
193
+ kodax setup
194
+ ```
195
+
196
+ 命令会保存 provider/model,告诉你准确的环境变量名,然后退出以便重启终端。
197
+ 也可以直接设置 API Key:
178
198
 
179
199
  ```bash
180
200
  # macOS / Linux
@@ -184,6 +204,14 @@ export ZHIPU_API_KEY=your_api_key
184
204
  $env:ZHIPU_API_KEY="your_api_key"
185
205
  ```
186
206
 
207
+ Qwen Token Plan 需要选择 `qwen-token-plan` 并使用单独的凭据;`QWEN_API_KEY`
208
+ 不能用于该路由:
209
+
210
+ ```bash
211
+ export QWEN_TOKEN_API_KEY=your_api_key
212
+ kodax --provider qwen-token-plan
213
+ ```
214
+
187
215
  然后在 `~/.kodax/config.json` 里写一个最小配置:
188
216
 
189
217
  ```json
@@ -235,7 +263,7 @@ const result = await runKodaX(
235
263
 
236
264
  ```typescript
237
265
  import { Runner } from '@kodax-ai/kodax/agent'; // Agent runtime
238
- import { getProvider } from '@kodax-ai/kodax/llm'; // LLM 抽象(15 个内置 alias)
266
+ import { getProvider } from '@kodax-ai/kodax/llm'; // LLM 抽象(16 个内置 alias)
239
267
  import { runKodaX } from '@kodax-ai/kodax/coding'; // Coding tools + prompts
240
268
  import { createImageArtifactFromPath } from '@kodax-ai/kodax/media'; // 输入 artifact helpers
241
269
  import { SkillRegistry } from '@kodax-ai/kodax/skills'; // 零依赖 skill loader
@@ -472,6 +500,7 @@ dist/binary/linux-x64/
472
500
  | kimi | `KIMI_API_KEY` | Native | kimi-k2.7-code(262,144 token;可 `/model` 切换 `kimi-k2.7-code-highspeed` / `kimi-k2.6` / `kimi-k2.5`) |
473
501
  | kimi-code | `KIMI_CODE_API_KEY` | Native | kimi-for-coding(可 `/model` 切换 `k3-256k`〔Moderato,256K〕/ `k3`〔Allegretto+,1M〕/ `kimi-for-coding-highspeed`;两个 K3 选项均请求上游 `k3`) |
474
502
  | qwen | `QWEN_API_KEY` | Native | qwen3.5-plus |
503
+ | qwen-token-plan | `QWEN_TOKEN_API_KEY` | Native | qwen3.8-max-preview(Anthropic 协议;可 `/model` 切换 `qwen3.7-max` / `qwen3.7-plus` / `qwen3.6-flash` / `glm-5.2` / `deepseek-v4-pro`;均为 1M ctx;Qwen 3.8 / 3.7 Plus / 3.6 Flash 支持图片理解) |
475
504
  | zhipu | `ZHIPU_API_KEY` | Native | glm-5(可 `/model` 切换 `glm-5.2` 1M ctx / `glm-5.1` / `glm-5-turbo`) |
476
505
  | zhipu-coding | `ZHIPU_CODING_API_KEY` | Native | glm-5.2(1M ctx;仍可通过 `/model` 显式选择兼容模型 `glm-5.1` / `glm-5-turbo`) |
477
506
  | zai-coding | `ZAI_CODING_API_KEY` | Native | glm-5.2(GLM Coding Plan 海外站,通过 `api.z.ai` 接入,Anthropic 协议 — 模型清单和 `zhipu-coding` 完全一致) |
@@ -543,7 +572,7 @@ KodaX 有 50+ 个内置工具,按类别分组如下(实际暴露给 LLM 是
543
572
  | `spawn_agent` | 创建命名子 Actor,并在继承权限、会话并发和根工作预算约束下启动首个 Turn。 |
544
573
  | `send_message` | 向 Actor 的持久 mailbox 提交有界信息,不启动新 Turn。 |
545
574
  | `followup_task` | 在安全边界加入运行中的 Actor,或为 idle Actor 原子启动新 Turn。 |
546
- | `wait_agent` | 等待一个或多个 Actor 状态变化,不轮询第二套任务注册表。 |
575
+ | `wait_agent` | 等待当前作用域的 mailbox / 用户输入 / 中断 / 超时,只返回唤醒确认,Actor progress 不会唤醒模型。 |
547
576
  | `interrupt_agent` | 请求中断 active Turn,同时保留 Actor 身份。 |
548
577
  | `list_agents` | 查看调用方有权访问的 Actor 子树与 Turn 状态。 |
549
578
  | `agent_output` | 读取有权限的 Actor/Turn 有界持久输出。 |
@@ -568,8 +597,8 @@ KodaX 是基于 npm workspaces 的 TypeScript monorepo,**源码层 4 个 works
568
597
 
569
598
  | Workspace 包 | 作用 | 主要依赖 |
570
599
  |----|------|---------|
571
- | `@kodax-ai/llm` | LLM 抽象层(15 个内置 provider alias + 自定义 provider 注册),可独立使用 | `@anthropic-ai/sdk`, `openai` |
572
- | `@kodax-ai/agent` | 通用 Agent 框架 —— Runner / runFanOut / runWithIdleYield / AgentActorController / AgentTurnScheduler + media/input artifacts + 会话管理 + tokenization + 可插拔 compaction + **inline 后**:session-lineage 子树 + capabilities (mcp + skills + builtin) + tracing(subpaths: `/media`、`/session-lineage`、`/capabilities/mcp`、`/capabilities/skills`、`/tracing`) | `@kodax-ai/llm`, `js-tiktoken`, `fflate`, `jimp`, `yaml` |
600
+ | `@kodax-ai/llm` | LLM 抽象层(16 个内置 provider alias + 自定义 provider 注册),可独立使用 | `@anthropic-ai/sdk`, `openai` |
601
+ | `@kodax-ai/agent` | 通用 Agent 框架 —— Runner / runFanOut / runWithIdleYield / AgentActorController / AgentTurnScheduler + media/input artifacts + 会话管理 + tokenization + 面向自定义 loop 的可插拔 compaction primitive(不关闭 KodaX coding runtime 的始终开启策略)+ **inline 后**:session-lineage 子树 + capabilities (mcp + skills + builtin) + tracing(subpaths: `/media`、`/session-lineage`、`/capabilities/mcp`、`/capabilities/skills`、`/tracing`) | `@kodax-ai/llm`, `js-tiktoken`, `fflate`, `jimp`, `yaml` |
573
602
  | `@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` |
574
603
  | `@kodax-ai/repl` | 完整交互式终端 UI(Ink / React、权限模式、命令系统、流式渲染) | `@kodax-ai/coding`, `ink`, `react` |
575
604
 
@@ -606,6 +635,12 @@ KodaX 有两层结构,SDK 用户需要分开理解:
606
635
 
607
636
  **会话恢复与 ACP 污染修复(FEATURE_261,v0.7.67)**:直接运行 `kodax -r` 会进入可搜索、上下选择、Tab 补全和翻页的交互式会话选择器,并显示当前选中项的完整 session ID;`kodax -r <值>` 优先按完整 ID 恢复,ID 不存在时再按忽略大小写的完整标题匹配。标题唯一则直接恢复,同名标题则进入只包含候选项的选择器,绝不静默选第一条。`listSessions()` / Runtime / daemon 会话列表新增 `surface` 精确过滤和不透明 `cursor` 分页。ACP session 改为收到首个有效 prompt 后才持久化,ACP 测试强制使用临时 runtime home,避免测试记录写入真实 `~/.kodax/sessions`。`kodax -s cleanup-acp` 只预览严格匹配的空 ACP 污染记录;仅显式追加 `--apply-session-cleanup` 时才归档,不做永久删除。
608
637
 
638
+ **v0.7.74 最近会话恢复闭环:**`kodax -c`、Ink/Classic 启动、单次 CLI 与 coding
639
+ runtime auto-resume 都会扫描最多 1000 条最新摘要并跳过 `msgCount=0` 的 ACP/bootstrap
640
+ 占位会话;显式 session ID 始终优先。交互式恢复会在下一轮前恢复保存的 workspace
641
+ runtime、消息、UI 历史、lineage、artifact、extension 状态、标题、tag 与 session ID,
642
+ 因此相对 shell 命令不会错误地落回启动目录。
643
+
609
644
  **实验性 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)。
610
645
 
611
646
  **双向 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)。
@@ -702,14 +737,20 @@ REPL 显示、唤醒或消费。
702
737
 
703
738
  **历史工作流激活分层(FEATURE_248 + FEATURE_249,v0.7.59;F270 于 v0.7.72 取代)**:v0.7.59 引入 AMAW 和 AMA 的显式请求行为。F270 退役 AMAW 及其复杂度驱动指令;SA 保持单独作业,AMA 成为唯一自适应多 Agent 模式,并且只在明确 Workflow 意图下激活 Workflow。详见 [docs/features/v0.7.59.md](docs/features/v0.7.59.md) 与 [docs/features/v0.7.72.md](docs/features/v0.7.72.md)。
704
739
 
705
- **managed 工具路径的渐进披露(FEATURE_250,v0.7.60;F270 模式更新于 v0.7.72)**:deferred-tool 渐进披露机制应用于 AMA managed path。缓存冷启轮次以一行 search hint 替代 13non-mcp 延迟工具的完整描述;F270 退役原 AMAW 模式,但不改变这项披露行为。详见 [docs/features/v0.7.60.md](docs/features/v0.7.60.md)。
740
+ **managed 工具路径的渐进披露(FEATURE_250,v0.7.60;当前策略于 v0.7.74 纠偏)**:deferred-tool 机制同时应用于 AMA managed path SA。当前延迟集合精确包含 11 个工具:6repo-intelligence、4 web/code discovery,以及 `run_workflow`;其 `input_schema` 仍可直接调用,完整描述按需由 `tool_search` 返回。5 个固定 `mcp_*` facade 与 `get_goal` / `create_goal` / `update_goal` 生命周期工具常驻完整契约。v0.7.74 的 Goal 纠偏相对旧 hint 仅增加约 109 个估算 schema token(其中常驻的 `get_goal` 反而少 12 token),消除一次发现往返,并且不改变工具 schema、handler、权限、Goal 状态或压缩保护。详见 [docs/features/v0.7.60.md](docs/features/v0.7.60.md) 与 [docs/features/v0.7.74.md](docs/features/v0.7.74.md#feature_250-v0774-correction-resident-goal-lifecycle-tools)
741
+
742
+ **上下文高效的工具结果 + Workflow 质量预检(FEATURE_251 + FEATURE_252,v0.7.61;2026-07-14 纠偏)**:本地工具先完整采集,只采用契约等价且严格更短的无损规范化;命令专用 Bash 有损过滤默认关闭,compound Bash 不使用语义 adapter。并行结果由唯一 owner 按最终 provider 请求统一判容:先求满足 `Pmax + 输出预留 + max(2048, Pmax 的 3%) <= 上下文窗口` 的最大最终输入,再只使用剩余物理容量。能放下就逐字交付,只有真实溢出才持久化完整结果并返回 `KODAX_RESULT_INCOMPLETE`。历史仍遵守相同的物理容量安全规则:容量内不做默认有损 microcompaction,压力下 summary-first,无法形成可恢复请求时 typed failure,禁止静默删除。FEATURE_272 仅取代 FEATURE_251 的大型压缩默认触发策略;FEATURE_252 的确定性 workflow 启动前合约 lint 保持不变。详见 [docs/features/v0.7.61.md](docs/features/v0.7.61.md) 与 [docs/ADR.md ADR-050](docs/ADR.md)。
743
+
744
+ **可靠且始终开启的上下文压缩(FEATURE_272,v0.7.74)**:自动大型压缩不允许关闭。百分比阈值默认 75%,并限制在 15-90%;可选 `triggerTokens` 未设置或为 0 时不生效,否则百分比、绝对值和物理容量三者取最小。最近原始尾部保护量为有效阈值的 20%。一次事务压缩保护尾部之外的完整 eligible prefix,并用精确 query ledger 保留所有真实用户请求;只有实际减少 token、恢复物理可用且等待持久化提交成功后才发出成功事件。原始正文从内存驱逐前,Session owner 会先持久化并刷盘精确 lineage;sidecar 与精简 Session 通过稳定 entry ID 合并去重。根 Agent 与持久化子 Agent 都可用有界的 `session_history_search` → `session_history_read` 回溯自己的被省略细节;子 Agent 只绑定独立隐藏的 worker Session,永远不能读取根历史。SDK/Runtime 则使用 revision-bound `transcriptSearch`、分页和无损 chunk;隐藏思考、system 指令与合成 checkpoint 不进入模型检索。详见 [功能设计](docs/features/v0.7.74.md)、[SDK 指南第 25 节](docs/SDK_EMBEDDER_GUIDE.md#25-always-on-context-compaction-and-bounded-transcript-recovery-v0774) 与 [ADR-057](docs/ADR.md#adr-057-large-compaction-is-an-always-on-context-scoped-full-coverage-transaction)。
745
+
746
+ **邮箱驱动的 Agent 协作(FEATURE_273,v0.7.74)**:`wait_agent` 现在是真正的模型侧 mailbox yield,只接受一个有界 `timeout_ms`,不再读取 Actor progress/event。它只因当前作用域的 Agent 消息或完成通知、根用户输入、中断或超时而唤醒;progress 仍通过 UI/SDK snapshot、replay 和 long-poll 提供,但不会触发父模型重采样。工具只返回 wake acknowledgement,可信 Agent evidence 与结构化 task metadata 在下一安全边界只注入一次。未确认的根 completion 可在硬重启后恢复,同进程 Runtime 重建按子 `turnId` 去重,已确认或旧版历史 completion 不重放。树状态用 `list_agents`,已知结果用 `agent_output`。详见 [功能设计](docs/features/v0.7.74.md#feature_273-mailbox-driven-agent-wait-and-telemetrycontrol-separation)、[SDK 指南第 26 节](docs/SDK_EMBEDDER_GUIDE.md#26-agent-mailbox-control-versus-sdk-event-telemetry-v0774) 与 [ADR-058](docs/ADR.md#adr-058-model-agent-wait-is-mailbox-control-not-event-telemetry)。
706
747
 
707
- **上下文高效的工具结果 + Workflow 质量预检(FEATURE_251 + FEATURE_252,v0.7.61;2026-07-14 纠偏)**:本地工具先完整采集,只采用契约等价且严格更短的无损规范化;命令专用 Bash 有损过滤默认关闭,compound Bash 不使用语义 adapter。并行结果由唯一 owner 按最终 provider 请求统一判容:先求满足 `Pmax + 输出预留 + max(2048, Pmax 3%) <= 上下文窗口` 的最大最终输入,再只使用剩余物理容量。能放下就逐字交付,只有真实溢出才持久化完整结果并返回 `KODAX_RESULT_INCOMPLETE`。历史压缩使用同一物理容量规则:容量内不做默认有损 microcompaction,真实压力下 summary-first,无法形成可恢复请求时 typed failure,禁止静默删消息;静态提前百分比仅为显式 opt-inFEATURE_252 的确定性 workflow 启动前合约 lint 保持不变。详见 [docs/features/v0.7.61.md](docs/features/v0.7.61.md) [docs/ADR.md ADR-050](docs/ADR.md)
748
+ **活跃 Run 中断输入(v0.7.74)**:embedded Runtime shared daemon 声明 `interruptInput:1`。`runtime.runs.submitInput()` 把不可变、有序的输入排入当前 active Actor Run;同一安全 Runner 边界前接纳的输入按 FIFO 作为独立 user message 一次性交给下一次 LLM 请求,不创建 continuation RunRun snapshot/event 暴露 queued/delivered 状态,确认只匹配实际消费的 ID,终态清理保证未交付输入不会泄漏到后续 Run
708
749
 
709
750
  ```
710
751
  KodaX/ # 4 workspace packages(FEATURE_194 v0.7.43)
711
752
  ├── packages/
712
- │ ├── llm/ # @kodax-ai/llm —— 15 个内置 provider alias
753
+ │ ├── llm/ # @kodax-ai/llm —— 16 个内置 provider alias
713
754
  │ ├── agent/ # @kodax-ai/agent —— Runner / fan-out / idle-yield + 子树:
714
755
  │ │ ├── session-lineage/ # 分支 session tree (v0.7.43 inline)
715
756
  │ │ ├── capabilities/
@@ -817,7 +858,7 @@ KodaX 现在会把 Repo Intelligence 的本地缓存分成内置引擎 profile
817
858
  ## 文档
818
859
 
819
860
  - [README.md](README.md) - 英文版 README
820
- - [docs/SDK_EMBEDDER_GUIDE.md](docs/SDK_EMBEDDER_GUIDE.md) - SDK 宿主集成、shared Runtimev0.7.72 Auto Mode 契约
861
+ - [docs/SDK_EMBEDDER_GUIDE.md](docs/SDK_EMBEDDER_GUIDE.md) - SDK 宿主集成、shared Runtimev0.7.74 压缩/历史恢复、Agent 遥测与活跃 Run 输入契约
821
862
  - [docs/release.md](docs/release.md) - 单文件二进制构建与发布流程
822
863
  - [docs/PRD.md](docs/PRD.md) - 产品需求
823
864
  - [docs/ADR.md](docs/ADR.md) - 架构决策
@@ -21,6 +21,13 @@
21
21
  // }
22
22
  // ],
23
23
  // "repoIntelligenceMode": "auto",
24
+ // Automatic large compaction is always enabled. Percentage defaults to 75
25
+ // and is clamped to 15..90. A missing/zero absolute threshold is inactive;
26
+ // otherwise the smaller percentage, absolute, and physical limit wins.
27
+ // "compaction": {
28
+ // "triggerPercent": 75,
29
+ // "triggerTokens": 0
30
+ // },
24
31
  // "sessionRetentionDays": 0,
25
32
  // "workflow": { "maxConcurrency": 8 }
26
33
  }
@@ -0,0 +1,2 @@
1
+ // @kodax-ai/kodax — bundled distribution. See docs/ADR.md ADR-022 + ADR-024.
2
+ import{Ea as i,Ka as j,da as d,ea as e,fa as f,j as c,ua as g,wa as h}from"./chunk-XM724XAA.js";import"./chunk-64M5HOCA.js";import"./chunk-MBAPT2R5.js";import"./chunk-C7TZAT3S.js";import"./chunk-XXQLPTAN.js";import{sb as a,tb as b}from"./chunk-UJS7JAO6.js";import"./chunk-GAFFYJU3.js";import"./chunk-PP53SIIL.js";import"./chunk-F7AIEHSS.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};
@@ -0,0 +1,2 @@
1
+ // @kodax-ai/kodax — bundled distribution. See docs/ADR.md ADR-022 + ADR-024.
2
+ import{Ja as a,Ka as b}from"./chunk-7W6KYJU2.js";import"./chunk-XMP66YWG.js";import"./chunk-QH56WEHK.js";import"./chunk-VPURXE2F.js";import"./chunk-MVCAFD6M.js";import"./chunk-VK5QTHS6.js";import"./chunk-XM724XAA.js";import"./chunk-64M5HOCA.js";import"./chunk-MBAPT2R5.js";import"./chunk-C7TZAT3S.js";import"./chunk-XXQLPTAN.js";import"./chunk-UJS7JAO6.js";import"./chunk-GAFFYJU3.js";import"./chunk-PP53SIIL.js";import"./chunk-F7AIEHSS.js";import"./chunk-ONUPGMER.js";export{a as ArgumentCompleter,b as createArgumentCompleter};