@kodax-ai/kodax 0.7.73 → 0.7.74

package/CHANGELOG.md

@@ -6,6 +6,140 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [0.7.74] - 2026-07-23
+
+> Git tag and GitHub Release are published by the release workflow. npm
+> publication remains a separate manual operator step.
+
+### Added
+
+- **Absolute automatic-compaction threshold (FEATURE_272).** SDK, Runtime
+  Session settings, daemon protocol, REPL, and KodaX Space now expose an
+  optional token threshold. Missing/zero is inactive; otherwise the smaller of
+  the absolute limit, bounded percentage policy, and physical provider capacity
+  triggers compaction. Percentage defaults to 75% and clamps to 15-90%, while
+  automatic large compaction remains always enabled.
+- **Context-owned compaction telemetry and transcript paging.** Root and child
+  turns now carry stable `contextId`/revision ownership. The canonical
+  `context.compaction.finished` event reports committed before/after and
+  component metrics. Runtime observations use bounded transcript slices,
+  revision-bound pages, and lossless chunks for oversized entries; clients can
+  require `contextCompaction:3`, `transcriptPaging:1`, and
+  `transcriptSearch:1`.
+- **Durable exact-history recovery.** The root host now persists and flushes
+  exact pre-compaction lineage before evicting raw bodies. Island sidecars are
+  committed before the slim main Session, stable entry IDs deduplicate overlap,
+  and failures preserve the last exact live or persisted copy. Root Agents gain
+  bounded `session_history_search` / `session_history_read`; SDK and daemon
+  clients gain revision-bound `sessions.transcriptSearch()`.
+- **Runtime active-run interrupt input.** Embedded Runtime and the shared daemon
+  now advertise `interruptInput:1`. `runtime.runs.submitInput()` queues cloned,
+  ordered input for the current active Actor Run, delivers one FIFO batch as
+  separate user messages at the next safe Runner boundary, and exposes durable
+  queued/delivered lifecycle facts without creating a continuation Run or
+  leaking terminalized input into a later Run.
+
+### Changed
+
+- **Mailbox-driven Agent coordination (FEATURE_273).** Model-visible
+  `wait_agent` now accepts only a bounded timeout and yields on the caller's
+  mailbox, root user input, interruption, or expiry. Progress remains available
+  through Actor snapshots, event replay, and SDK long-poll without waking and
+  resampling the parent model. The tool returns only a wake acknowledgement;
+  authenticated Agent messages and structured completion metadata enter the
+  transcript once at the next safe boundary. `list_agents` owns tree-state
+  inspection and `agent_output` owns targeted result reads.
+- **Resident Goal lifecycle contracts.** `get_goal`, `create_goal`, and
+  `update_goal` keep their complete descriptions on both SA and managed AMA
+  paths. This removes an avoidable discovery round trip while preserving the
+  explicit-create and three-turn blocked-state rules. The remaining deferred
+  set stays at exactly 11 tools; schemas, handlers, permissions, Goal state, and
+  compaction-protected receipts are unchanged.
+
+### Fixed
+
+- **Large compaction coverage and protected-tail basis.** Major compaction now
+  protects 20% of the effective trigger rather than 20% of the model maximum,
+  summarizes the complete eligible prefix in one transaction, and uses
+  map-once/reduce-once only for physical overflow. Exact main-request prefix
+  reuse preserves prompt/KV cache on both ordinary and managed-task paths while
+  explicitly excluding the protected raw tail from the summary.
+- **User intent retention across repeated and degraded compaction.** Genuine
+  user queries are mechanically retained in a stable JSONL checkpoint ledger,
+  including text carried beside tool results. A query is represented exactly
+  once: raw while it remains in the protected tail, then in the ledger when its
+  prefix is compacted. The explicit emergency-pruning fallback installs query
+  recovery before removing old raw evidence.
+- **SDK/UI accounting and daemon frame safety.** The legacy compact callback now
+  reports post-compact tokens on both execution paths, and automatic managed
+  compaction emits the same post-commit canonical event/report as the standard
+  agent path. Persisted anchors include admitted post-compact attachments.
+  Space ignores child context metrics for the root gauge/activity/cost display,
+  displays the last root transition, labels active model input separately from
+  complete visible history, and reads transcripts directly through bounded
+  page/chunk calls. The legacy full-transcript daemon method rejects responses
+  above 512 KiB instead of risking the 8 MiB frame.
+- **Compacted-history loss and maintenance replay.** Full-lineage loads now
+  merge exact sidecar entries over slim placeholders, compaction writes use a
+  durable-before-evict boundary, child compaction cannot overwrite root
+  lineage, and maintenance preserves its append watermark instead of archiving
+  the same island entries again.
+- **Agent completion delivery and resumed transcripts.** Unacknowledged root
+  completions persist an explicit pending-delivery set and are republished after
+  a hard restart; same-process Runtime reconstruction deduplicates the projected
+  queue by child turn ID, while acknowledged and legacy historical completions
+  are not replayed. Completion acknowledgement remains after authoritative
+  transcript persistence. Session restore also deduplicates and canonically
+  repositions tool groups by tool-use ID and binds repeated text to the latest
+  persisted suffix.
+- **Deterministic reads, bounded tool attention, and compaction round exits.**
+  Auto Mode now handles complete risk-free static reads deterministically while
+  sensitive paths, credential stores, process environments, and named secret
+  variables require confirmation. Grep clips pathological lines and exposes
+  bounded offset continuation; one batch-admission owner separates physical
+  capacity from tool-attention spill. Current user-shaped and legacy compaction
+  checkpoints no longer cause a compacted query/final pair to be appended twice.
+- **Release-review boundary fixes.** Emergency compaction fallback accounts for
+  system/tool overhead and response reserve before pruning and reports no
+  success for unchanged or still-oversized candidates. Runtime-backed REPL paths
+  use one Session writer, first-run headless compaction seeds Session metadata,
+  persistence failure rolls back tentative context revision, and history search
+  consistently excludes system/hidden/checkpoint/placeholder content. Auto
+  permission analysis samples the middle of long operation lists, POSIX paths
+  are not mistaken for Windows switches, and continuation errors identify
+  `runtime.runs.submitInput` accurately.
+- **Release-candidate checkpoint and PowerShell boundary closure.** Session
+  lineage now consumes and re-renders the exact compaction checkpoint bytes,
+  including recovery guidance, so the compaction entry, first-kept pointer, and
+  post-compact attachments remain on the active path; legacy suffix-free
+  checkpoints still resume. Auto Mode treats bracket wildcards on PowerShell
+  path parameters as incomplete and escalates them, while exact `LiteralPath`
+  filenames containing brackets remain supported.
+- **Reliable continue-most-recent selection.** `kodax -c`, classic/Ink startup,
+  one-shot CLI execution, and coding-runtime auto-resume now scan beyond the
+  legacy ten-session window, skip zero-message ACP/bootstrap placeholders, and
+  preserve an explicit session ID. Interactive resume restores the saved
+  workspace runtime together with messages, UI history, lineage, artifacts,
+  extensions, title, tag, and session identity before the next turn.
+- **Deterministic Auto mode switching.** Entering Auto now displays the resolved
+  configured engine immediately instead of a transient bare `Auto`, and Runtime
+  setting writes are serialized per Session so rapid shortcut cycling is
+  last-action-wins. Persisted or automatic `Auto[RULES]` fallback remains sticky
+  by design and can be changed explicitly with `/auto-engine llm`.
+- **Release-review debt closure.** Imperative manual compaction now reconciles
+  the exact flat Session history into lineage before creating the compaction
+  island. A failed durable interrupt-delivery event leaves the input queued,
+  rethrows the persistence error, and emits a bounded `runtime.warning` without
+  copying user input content into diagnostics.
+
+### Documentation
+
+- Root and generated JSONC templates, both READMEs, architecture/design docs,
+  the SDK embedder guide, feature/issue trackers, release verification guide,
+  package READMEs, and `kodax_manual` now describe the complete v0.7.74
+  compaction, mailbox-wait, active-run input, Goal-tool, resume, Auto-switch,
+  and recovery contracts.
+
 ## [0.7.73] - 2026-07-20
 
 ### Added

package/README.md

@@ -417,7 +417,7 @@ configuration error when no effective classifier model exists, rather than
 silently falling back. Runtime permission prompts now offer opaque, exact
 allow-once/session/persistent grant suggestions; persistent grants are
 daemon-owned and revisioned. Host plan exit is exposed only when the host
-supplies an approval callback. See the [Runtime Auto Mode integration guide](docs/SDK_EMBEDDER_GUIDE.md#24-runtime-owned-auto-mode-and-plan-approval-bridges-v072).
+supplies an approval callback. See the [Runtime Auto Mode integration guide](docs/SDK_EMBEDDER_GUIDE.md#24-runtime-owned-auto-mode-and-plan-approval-bridges-v0772v0773).
 
 ## Repo Intelligence
 
@@ -537,9 +537,15 @@ KodaX has two layers that consumers should understand separately:
 
 **Historical Workflow Activation Tiers (FEATURE_248 + FEATURE_249, v0.7.59; superseded by F270 in v0.7.72)**: v0.7.59 introduced AMAW and explicit-request AMA behavior. F270 retires AMAW and its complexity-driven directive. SA remains solo; AMA is the single adaptive multi-Agent mode and activates Workflow only from explicit Workflow intent. See [docs/features/v0.7.59.md](docs/features/v0.7.59.md) and [docs/features/v0.7.72.md](docs/features/v0.7.72.md).
 
-**Progressive Disclosure on the Managed Tool Path (FEATURE_250, v0.7.60; F270 mode update in v0.7.72)**: the deferred-tool progressive-disclosure mechanism applies to the managed AMA path. Cache-cold managed turns carry one-line search hints instead of full descriptions for the 13 non-mcp deferred tools (repo-intelligence + web/code + goal); each tool's `input_schema` is unchanged, so it stays directly callable and the full description is fetched on demand via `tool_search`. `mcp_*` stay resident and `run_workflow` is untouched. F270 retires the former AMAW mode without changing this disclosure behavior. See [docs/features/v0.7.60.md](docs/features/v0.7.60.md).
+**Progressive Disclosure on the Managed Tool Path (FEATURE_250, v0.7.60; current policy corrected in v0.7.74)**: the deferred-tool mechanism applies to the managed AMA path as well as SA. The current deferred set contains exactly 11 tools: six repo-intelligence tools, four web/code discovery tools, and `run_workflow`. Their `input_schema` remains directly callable while `tool_search` provides the full description on demand. The five fixed `mcp_*` facades and the `get_goal` / `create_goal` / `update_goal` lifecycle tools stay resident with their complete contracts. The v0.7.74 goal correction adds only about 109 estimated schema tokens versus the former hints (`get_goal` is actually 12 tokens smaller when resident), removes a discovery round trip, and changes no tool schema, handler, permission, goal state, or compaction-protection behavior. See [docs/features/v0.7.60.md](docs/features/v0.7.60.md) and [docs/features/v0.7.74.md](docs/features/v0.7.74.md#feature_250-v0774-correction-resident-goal-lifecycle-tools).
 
-**Context-Efficient Tool Results + Workflow Quality Preflight (FEATURE_251 + FEATURE_252, v0.7.61; corrected 2026-07-14)**: local tools collect complete output and apply only contract-equivalent normalization that is strictly shorter; command-specific lossy Bash filters are off by default, and compound Bash uses no semantic adapter. One owner evaluates the complete parallel-result batch against the final provider request: it solves the largest final input `Pmax` for which `Pmax + output reserve + max(2048, 3% of Pmax) <= context window`, then admits only the remaining physical capacity. Results stay verbatim whenever they fit; only real overflow persists the complete value and emits `KODAX_RESULT_INCOMPLETE`. History follows the same physical-capacity rule: no default lossy microcompaction below capacity, summary-first at actual pressure, and typed failure without silent message deletion when a recoverable request cannot be formed. Static early percentages are explicit opt-ins. FEATURE_252's deterministic pre-start workflow contract lint is unchanged. See [docs/features/v0.7.61.md](docs/features/v0.7.61.md) and [docs/ADR.md ADR-050](docs/ADR.md).
+**Context-Efficient Tool Results + Workflow Quality Preflight (FEATURE_251 + FEATURE_252, v0.7.61; corrected 2026-07-14)**: local tools collect complete output and apply only contract-equivalent normalization that is strictly shorter; command-specific lossy Bash filters are off by default, and compound Bash uses no semantic adapter. One owner evaluates the complete parallel-result batch against the final provider request: it solves the largest final input `Pmax` for which `Pmax + output reserve + max(2048, 3% of Pmax) <= context window`, then admits only the remaining physical capacity. Results stay verbatim whenever they fit; only real overflow persists the complete value and emits `KODAX_RESULT_INCOMPLETE`. History keeps the same physical-capacity safety rule: no default lossy microcompaction below capacity, summary-first at pressure, and typed failure without silent deletion when a recoverable request cannot be formed. FEATURE_272 supersedes FEATURE_251 only for the default major-compaction trigger. FEATURE_252's deterministic pre-start workflow contract lint is unchanged. See [docs/features/v0.7.61.md](docs/features/v0.7.61.md) and [docs/ADR.md ADR-050](docs/ADR.md).
+
+**Reliable Always-On Context Compaction (FEATURE_272, v0.7.74)**: automatic major compaction cannot be disabled. Its percentage trigger defaults to 75% and clamps to 15-90%; optional `triggerTokens` is inactive when omitted/zero, otherwise the smaller percentage, absolute, and physical-capacity threshold wins. The protected raw tail is 20% of that effective trigger. One transaction summarizes the complete eligible prefix, preserves every genuine user request through an exact ledger, and emits success only after a physically valid token reduction and awaited durable commit. Before raw bodies are evicted, the Session owner durably flushes their exact lineage; stable entry IDs merge the sidecar and slim Session without duplicates. Root and persistent child Agents can recover omitted user/assistant/tool details through bounded `session_history_search` → `session_history_read`, with children isolated to hidden worker Sessions and never granted root-history access. SDK/Runtime clients use revision-bound `transcriptSearch`, pages, and lossless chunks. Hidden reasoning, system instructions, and synthetic checkpoints are excluded from model search. See [the feature design](docs/features/v0.7.74.md), [SDK guide §25](docs/SDK_EMBEDDER_GUIDE.md#25-always-on-context-compaction-and-bounded-transcript-recovery-v0774), and [ADR-057](docs/ADR.md#adr-057-large-compaction-is-an-always-on-context-scoped-full-coverage-transaction).
+
+**Mailbox-Driven Agent Coordination (FEATURE_273, v0.7.74)**: `wait_agent` is now a true model-facing mailbox yield with one bounded `timeout_ms`, not an Actor progress/event reader. It wakes for scoped Agent messages or completions, root user input, interruption, or timeout; progress remains available to UI/SDK snapshot, replay, and long-poll consumers without resampling the parent model. The tool returns only a wake acknowledgement, while authenticated Agent evidence and structured task metadata enter the next safe model boundary once. Unacknowledged root completions survive a hard restart, same-process Runtime rebuilds deduplicate by child turn ID, and acknowledged or legacy historical completions are not replayed. Use `list_agents` for tree state and `agent_output` for a targeted known result. See [the feature design](docs/features/v0.7.74.md#feature_273-mailbox-driven-agent-wait-and-telemetrycontrol-separation), [SDK guide §26](docs/SDK_EMBEDDER_GUIDE.md#26-agent-mailbox-control-versus-sdk-event-telemetry-v0774), and [ADR-058](docs/ADR.md#adr-058-model-agent-wait-is-mailbox-control-not-event-telemetry).
+
+**Active-Run Interrupt Input (v0.7.74)**: embedded Runtime and the shared daemon advertise `interruptInput:1`. `runtime.runs.submitInput()` queues an immutable, ordered input for the current active Actor Run; all inputs admitted before one safe Runner boundary are delivered FIFO as separate user messages in the next LLM request, without creating continuation Runs. Queued/delivered state is visible in typed Run snapshots/events, delivery is acknowledged against the exact consumed IDs, and terminal cleanup prevents undelivered input from leaking into later Runs.
 
 **External Agent SDK Plane (FEATURE_258, v0.7.67)**: `/agent` exports the protocol-neutral executor, registration, policy, credential-broker, artifact-policy, catalog, and durable task contracts. `/runtime` exposes the installed plane through `admin.agentRegistrations`, `agents`, and `agentTasks`, with the same DTO service methods over embedded and daemon clients. Executor factories are host functions: install them in an inline owner or while creating a new in-process daemon owner; they cannot be injected through an existing daemon connection or across a Runtime Worker boundary. Plane shutdown is terminal: pending waits and all later service calls reject. Restricted Workflow scripts preserve validated `phase` and external `target` routing. See the [complete owner/consumer recipes and safety contract](docs/SDK_EMBEDDER_GUIDE.md#18-external-agent-executor-plane-feature_258-v0767).
 
@@ -881,7 +887,7 @@ kodax --session todo-app "Write tests"
 kodax                    Start the interactive REPL
 -h, --help [topic]   Show help or topic help
 -p, --print <text>   Run a single task and exit
--c, --continue       Continue the most recent conversation in this directory
+-c, --continue       Continue the most recent non-empty conversation in this directory
 -r, --resume [value] Resume by ID/exact title, or open the searchable picker
 -m, --provider       Provider to use
 --model <name>       Override the model
@@ -922,6 +928,10 @@ KodaX provides 3 permission modes for fine-grained control:
 - Auto Mode runs guardrail classification before the permission UI; a safe
   allow verdict does not create a pending approval request. The session records
   an automatic LLM-to-rules fallback for later turns.
+- Shift-Tab cycles `Plan -> Edits -> Auto`; Shift+Enter inserts a newline. Auto
+  immediately displays `Auto[LLM]` or `Auto[RULES]`, and rapid mode changes are
+  persisted in input order. `Auto[RULES]` is a valid sticky fallback/manual
+  state; use `/auto-engine llm` to opt back into LLM classification.
 - Runtime-backed prompts can offer exact `allow once`, `allow this session`,
   and `always allow` choices. Return the Runtime-issued opaque suggestion;
   never derive or widen a permission rule from the displayed command or path.
@@ -929,6 +939,12 @@ KodaX provides 3 permission modes for fine-grained control:
   through `runtime.permissions` by an authorized SDK host. Dynamic shell
   commands deliberately receive no persistent-grant suggestion.
 
+`kodax -c` skips zero-message ACP/bootstrap placeholders even when they are
+newer than the last real conversation. The same newest non-empty rule applies
+to Ink, classic, one-shot CLI, and coding-runtime auto-resume; an explicit
+session ID always wins. Interactive resume also restores the saved workspace
+runtime before relative shell commands or the next model turn.
+
 ### CLI Help Topics
 
 Get detailed help for specific topics:
@@ -1156,6 +1172,10 @@ const tree = actors.list('/root');
 const policy = new DefaultSummaryCompaction({ thresholdRatio: 0.8, keepRecent: 10 });
 ```
 
+`DefaultSummaryCompaction` is a standalone agent-layer primitive for custom
+loops. It does not replace or disable KodaX's always-on coding-runtime policy
+described under FEATURE_272 above.
+
 **Key Features**: `Runner` + per-step lifecycle · `runFanOut` (bounded-concurrency + abort + progress events) · `runWithIdleYield` (chat-while-waiting) · `AgentActorController` / `AgentTurnScheduler` · session-id generation · tiktoken-based token estimation · `CompactionPolicy` interface.
 
 ### `@kodax-ai/kodax/skills` — Skills System
@@ -1355,7 +1375,7 @@ KodaX ships 50+ built-in tools, grouped below. They are registered as a single f
 | `spawn_agent` | Create a named child Actor and start its first Turn under inherited capabilities, session capacity, and root work budget. |
 | `send_message` | Commit bounded information to an Actor mailbox without starting a new Turn. |
 | `followup_task` | Join a running Actor at a safe boundary or atomically start a new Turn for an idle Actor. |
-| `wait_agent` | Wait for one or more Actor state changes without polling a second task registry. |
+| `wait_agent` | Yield on scoped mailbox/user/interruption/timeout activity; returns a wake acknowledgement and never uses Actor progress as a model wake source. |
 | `interrupt_agent` | Request interruption of an active Turn while preserving Actor identity. |
 | `list_agents` | Inspect the caller-visible Actor subtree and Turn states. |
 | `agent_output` | Read bounded durable output for an authorized Actor/Turn. |
@@ -1498,7 +1518,7 @@ KodaX uses an **English-first** comment style with selective Chinese brief notes
 ## Documentation
 
 - [README_CN.md](README_CN.md) - Chinese Documentation
-- [docs/SDK_EMBEDDER_GUIDE.md](docs/SDK_EMBEDDER_GUIDE.md) - SDK hosting, shared Runtime daemon, Auto Mode, and permission-grant contracts
+- [docs/SDK_EMBEDDER_GUIDE.md](docs/SDK_EMBEDDER_GUIDE.md) - SDK hosting, shared Runtime daemon, Auto Mode, v0.7.74 compaction/history recovery, Agent telemetry, and active-run input contracts
 - [docs/release.md](docs/release.md) - Standalone binary build & release pipeline
 - [docs/PRD.md](docs/PRD.md) - Product Requirements
 - [docs/ADR.md](docs/ADR.md) - Architecture Decisions

package/README_CN.md

@@ -102,6 +102,12 @@ session。Session 也可设置 classifier model 和有界 timeout；`auto` 默
 不会向模型暴露 `exit_plan_mode`。完整 SDK 接入见
 [Runtime Auto Mode 指引](docs/SDK_EMBEDDER_GUIDE.md#24-runtime-owned-auto-mode-and-plan-approval-bridges-v072)。
 
+**v0.7.74 Auto 切换可靠性：**默认用 `Shift+Tab` 在 `Plan -> Edits -> Auto`
+之间循环，`Shift+Enter` 仍用于换行。进入 Auto 时状态栏会立即显示已解析的
+`Auto[LLM]` 或 `Auto[RULES]`，同一 Session 的 Runtime 设置按键入顺序串行提交，
+快速循环不会让较早的异步结果覆盖最后一次选择。`Auto[RULES]` 可能是自动降级或
+手动选择后的合法粘性状态；使用 `/auto-engine llm` 可显式恢复 LLM 分类。
+
 ## 为什么用 KodaX
 
 <table>
@@ -566,7 +572,7 @@ KodaX 有 50+ 个内置工具，按类别分组如下（实际暴露给 LLM 是
 | `spawn_agent` | 创建命名子 Actor，并在继承权限、会话并发和根工作预算约束下启动首个 Turn。 |
 | `send_message` | 向 Actor 的持久 mailbox 提交有界信息，不启动新 Turn。 |
 | `followup_task` | 在安全边界加入运行中的 Actor，或为 idle Actor 原子启动新 Turn。 |
-| `wait_agent` | 等待一个或多个 Actor 状态变化，不轮询第二套任务注册表。 |
+| `wait_agent` | 等待当前作用域的 mailbox / 用户输入 / 中断 / 超时，只返回唤醒确认，Actor progress 不会唤醒模型。 |
 | `interrupt_agent` | 请求中断 active Turn，同时保留 Actor 身份。 |
 | `list_agents` | 查看调用方有权访问的 Actor 子树与 Turn 状态。 |
 | `agent_output` | 读取有权限的 Actor/Turn 有界持久输出。 |
@@ -592,7 +598,7 @@ KodaX 是基于 npm workspaces 的 TypeScript monorepo，**源码层 4 个 works
 | Workspace 包 | 作用 | 主要依赖 |
 |----|------|---------|
 | `@kodax-ai/llm` | LLM 抽象层（16 个内置 provider alias + 自定义 provider 注册），可独立使用 | `@anthropic-ai/sdk`, `openai` |
-| `@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` |
+| `@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` |
 | `@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` |
 
@@ -629,6 +635,12 @@ KodaX 有两层结构，SDK 用户需要分开理解：
 
 **会话恢复与 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` 时才归档，不做永久删除。
 
+**v0.7.74 最近会话恢复闭环：**`kodax -c`、Ink/Classic 启动、单次 CLI 与 coding
+runtime auto-resume 都会扫描最多 1000 条最新摘要并跳过 `msgCount=0` 的 ACP/bootstrap
+占位会话；显式 session ID 始终优先。交互式恢复会在下一轮前恢复保存的 workspace
+runtime、消息、UI 历史、lineage、artifact、extension 状态、标题、tag 与 session ID，
+因此相对 shell 命令不会错误地落回启动目录。
+
 **实验性 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)。
@@ -725,9 +737,15 @@ REPL 显示、唤醒或消费。
 
 **历史工作流激活分层（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)。
 
-**managed 工具路径的渐进披露（FEATURE_250，v0.7.60；F270 模式更新于 v0.7.72）**：deferred-tool 渐进披露机制应用于 AMA 的 managed path。缓存冷启轮次以一行 search hint 替代 13 个 non-mcp 延迟工具的完整描述；F270 退役原 AMAW 模式，但不改变这项披露行为。详见 [docs/features/v0.7.60.md](docs/features/v0.7.60.md)。
+**managed 工具路径的渐进披露（FEATURE_250，v0.7.60；当前策略于 v0.7.74 纠偏）**：deferred-tool 机制同时应用于 AMA managed path 与 SA。当前延迟集合精确包含 11 个工具：6 个 repo-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)。
+
+**上下文高效的工具结果 + 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)。
+
+**可靠且始终开启的上下文压缩（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)。
+
+**邮箱驱动的 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)。
 
-**上下文高效的工具结果 + 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-in。FEATURE_252 的确定性 workflow 启动前合约 lint 保持不变。详见 [docs/features/v0.7.61.md](docs/features/v0.7.61.md) 与 [docs/ADR.md ADR-050](docs/ADR.md)。
+**活跃 Run 中断输入（v0.7.74）**：embedded Runtime 与 shared daemon 声明 `interruptInput:1`。`runtime.runs.submitInput()` 把不可变、有序的输入排入当前 active Actor Run；同一安全 Runner 边界前接纳的输入按 FIFO 作为独立 user message 一次性交给下一次 LLM 请求，不创建 continuation Run。Run snapshot/event 暴露 queued/delivered 状态，确认只匹配实际消费的 ID，终态清理保证未交付输入不会泄漏到后续 Run。
 
 ```
 KodaX/                       # 4 workspace packages(FEATURE_194 v0.7.43)
@@ -840,7 +858,7 @@ KodaX 现在会把 Repo Intelligence 的本地缓存分成内置引擎 profile
 ## 文档
 
 - [README.md](README.md) - 英文版 README
-- [docs/SDK_EMBEDDER_GUIDE.md](docs/SDK_EMBEDDER_GUIDE.md) - SDK 宿主集成、shared Runtime、v0.7.73 Auto Mode 与精确授权契约
+- [docs/SDK_EMBEDDER_GUIDE.md](docs/SDK_EMBEDDER_GUIDE.md) - SDK 宿主集成、shared Runtime、v0.7.74 压缩/历史恢复、Agent 遥测与活跃 Run 输入契约
 - [docs/release.md](docs/release.md) - 单文件二进制构建与发布流程
 - [docs/PRD.md](docs/PRD.md) - 产品需求
 - [docs/ADR.md](docs/ADR.md) - 架构决策

package/config-templates/config.example.jsonc

@@ -21,6 +21,13 @@
   //   }
   // ],
   // "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 }
 }

package/dist/chunks/{agent-T6PGT6AU.js → agent-2ABIG5NW.js}

@@ -1,2 +1,2 @@
 // @kodax-ai/kodax — bundled distribution. See docs/ADR.md ADR-022 + ADR-024.
-import{Ga as i,Ma as j,da as d,ea as e,fa as f,j as c,ua as g,va as h}from"./chunk-AGDDM5AW.js";import"./chunk-64M5HOCA.js";import"./chunk-MBAPT2R5.js";import"./chunk-HVCNAZ52.js";import"./chunk-XXQLPTAN.js";import{sb as a,tb as b}from"./chunk-OG6DRNKV.js";import"./chunk-GAFFYJU3.js";import"./chunk-BUPJGG3C.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};
+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};

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

@@ -0,0 +1,2 @@
+// @kodax-ai/kodax — bundled distribution. See docs/ADR.md ADR-022 + ADR-024.
+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};