@kodax-ai/kodax 0.7.72 → 0.7.74

package/CHANGELOG.md

@@ -6,6 +6,232 @@ 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
+
+- **Qwen Token Plan provider.** The new `qwen-token-plan` alias uses the
+  Anthropic-compatible Alibaba Cloud Token Plan endpoint and
+  `QWEN_TOKEN_API_KEY`. It defaults to `qwen3.8-max-preview`, exposes the
+  supported Qwen 3.7/3.6, GLM-5.2, and DeepSeek V4 Pro routes with one-million-
+  token context metadata, and declares verified reasoning, image-input, and
+  nominal subscription-cost capabilities without changing the existing `qwen`
+  provider.
+- **First-run provider setup (FEATURE_271).** A bare interactive `kodax`
+  launch with no selected provider and no supported local credential now opens
+  a focused provider/model setup flow before Runtime, daemon, session, or REPL
+  startup. `kodax setup` reruns the same flow explicitly. It stores only
+  non-secret metadata, preserves unrelated config through a revision-checked
+  atomic write, refuses malformed existing custom providers and credential-
+  bearing endpoint URLs, and then names the required environment variable and
+  terminal restart steps.
+- **Typed Auto Mode SDK contract (FEATURE_271).** The root and REPL SDK
+  entries now export one pure `resolveAutoModeSettings()` plus the authoritative
+  loader and related types; `loadConfig().autoMode` is declared, Runtime Session
+  settings persist `autoModeSpeculativeWindowMs` (including `0`), and side
+  queries return prompt-free provider/model/timing/retry/phase diagnostics.
+- **Runtime-owned concrete permission grants.** Embedded and daemon SDK clients
+  can submit concrete `toolInput` and `executionCwd`, receive only opaque
+  Runtime-issued Session/persistent grant suggestions, and select a suggestion
+  without constructing or widening its hidden matcher. Exact command, known
+  file-tool path, and generic exact-call matchers remain revisioned and audited;
+  dynamic or dangerous shell calls never receive a persistent suggestion.
+
+### Fixed
+
+- **Reasoning, Auto Mode, and confirmation regressions.** Native
+  disabled-thinking requests now send the provider's explicit disabled form
+  only for models that declare support (including verified Qwen Token Plan 3.7
+  routes); always-thinking variants retain their declared behavior. Sidecar
+  queries preserve a supported `none` effort, persisted Runtime Auto engines
+  are not overwritten by a fresh REPL, `/mode` synchronizes before reporting
+  success, and concurrent confirmation prompts are serialized instead of
+  replacing one another.
+- **Legacy permission-grant upgrade safety.** Matcherless grants persisted by
+  older releases remain visible and revocable but can no longer authorize a
+  concrete tool call. The next invocation requires a fresh Runtime-issued
+  matcher, so old coarse Bash grants cannot bypass exact-command, dynamic-shell,
+  or absolute-deny protections.
+- **Classifier credential boundary.** Auto[LLM] now redacts explicitly named
+  credential values inside shell-escaped JSON before sending an action to its
+  side provider, while retaining adjacent operational fields. Redaction is
+  documented as defense in depth; arbitrary Base64/hex values are not treated
+  as secrets without a credential signal.
+- **Todo/Actor semantic progress checkpoint (FEATURE_270 follow-up).** Worker
+  guidance now treats Todo rows as user-visible milestones rather than Actor
+  instances and requires timely updates at milestone boundaries. Structured
+  terminal child results arm one deduplicated, warn-only reconciliation
+  reminder; transcript scans are append-incremental with safe compaction
+  fallback, and Sidecar accept-time residual reconciliation emits a diagnostic
+  without changing its existing bridge contract.
+- **Auto LLM classifier timeout and missing-model escalation.** Runtime now
+  treats omitted Auto engine as the documented LLM default and still owns the
+  guardrail, while a missing/blank/malformed effective classifier model fails
+  as a typed recoverable Runtime error or a local block in the shared
+  `createAutoModeToolGuardrail` boundary. The final guardrail check runs before
+  provider lookup and cannot invoke `askUser`, record a circuit-breaker error,
+  or downgrade to rules. Classifier requests strip assistant prose/thinking,
+  cap normalized transcript/tool-result/action/prompt bytes, remove image
+  paths, and cap the structured response at 256 tokens. The 20-second deadline remains bounded:
+  a four-call `zai-coding/glm-5.2` probe completed representative Windows
+  permission verdicts in 1.9–2.8 seconds, while the matching production session
+  revealed a 1.625 MB tool result that had bypassed the existing sanitizer.
+- **Auto guardrail daemon and tracing semantics.** Auto-started Runtime clients
+  now require `runtimeAutoModeGuardrail:3`. It retains v2's effective
+  timeout/window defaults, bounded classifier input, and diagnostics metadata,
+  and adds opaque concrete-grant semantics. Capability negotiation is monotonic
+  (v3 satisfies v2/v1); idle older daemons use the existing fenced upgrade path,
+  while busy daemons are left untouched with a recoverable error. Guardrail
+  spans now cover the awaited callback instead of timing only final verdict
+  emission.
+- **Concurrent daemon startup publication race.** A cleanly exiting loser now
+  gives the elected owner a bounded publication grace period, preventing an
+  SDK starter from reporting failure during the short lock/state handoff gap.
+- **Guardrail/permission execution parity.** Both Runner paths now commit each
+  guardrail rewrite before permission policy and execution, reject correlation-
+  id rewrites, propagate blocks as visible audited tool results, and preserve
+  embedded host policy hooks while rejecting non-transportable daemon hooks.
+  Calls rewritten into Bash retain serialized shell ordering.
+- **Managed-run capacity and tool-dispatch accounting.** A complete system
+  prompt override no longer double-counts Skills, missing provider usage rebases
+  from the final request envelope, and authoritative provider usage remains
+  intact. Non-Bash tool calls keep parallel dispatch, Bash remains sequential,
+  and aggregate tool-result spill decisions use the complete batch budget.
+
 ## [0.7.72] - 2026-07-19
 
 ### Added

package/README.md

@@ -17,7 +17,7 @@
   <a href="LICENSE"><img alt="license" src="https://img.shields.io/badge/license-KAI--FCL_1.0-orange?style=flat-square"></a>
   <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>
   <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>
-  <img alt="providers" src="https://img.shields.io/badge/LLMs-15_aliases_+_custom-2ecc71?style=flat-square">
+  <img alt="providers" src="https://img.shields.io/badge/LLMs-16_aliases_+_custom-2ecc71?style=flat-square">
 </p>
 
 <p align="center">
@@ -44,12 +44,18 @@ npm i -g @kodax-ai/kodax
 # Pick any one you have an API key for:
 export ZHIPU_API_KEY=...        # or ANTHROPIC_API_KEY / OPENAI_API_KEY / KIMI_API_KEY /
                                 # MINIMAX_API_KEY / MIMO_API_KEY / ARK_API_KEY / QWEN_API_KEY /
+                                # QWEN_TOKEN_API_KEY /
                                 # DEEPSEEK_API_KEY / GEMINI_API_KEY
 
 kodax
 ```
 
-That's it. You're in the REPL — ask anything in natural language.
+That's it. You're in the REPL — ask anything in natural language. If this is a
+new machine with no provider selection or supported API-key environment
+variable, the bare `kodax` launch opens a metadata-only setup flow first. It
+never asks for the key itself; after choosing a provider/model, set the named
+environment variable, restart the terminal, and run `kodax` again. Use
+`kodax setup` to rerun that flow explicitly.
 
 > **No-Node target machines:** download a Bun-compiled single binary for Windows / macOS / Linux × x64 + arm64 from the [GitHub Releases](https://github.com/icetomoyo/KodaX/releases) page. See [docs/release.md](docs/release.md) for the build pipeline.
 
@@ -141,6 +147,14 @@ npm link
 
 KodaX reads API keys from environment variables. For built-in providers, the fastest path is:
 
+```bash
+# Interactive metadata-only provider/model setup (does not collect a key)
+kodax setup
+```
+
+The command tells you the exact environment-variable name to set and exits so
+you can restart the terminal. You can also configure it directly:
+
 ```bash
 # macOS / Linux
 export ZHIPU_API_KEY=your_api_key
@@ -149,6 +163,14 @@ export ZHIPU_API_KEY=your_api_key
 $env:ZHIPU_API_KEY="your_api_key"
 ```
 
+For Qwen Token Plan, select `qwen-token-plan` and use its separate credential;
+`QWEN_API_KEY` does not authenticate this route:
+
+```bash
+export QWEN_TOKEN_API_KEY=your_api_key
+kodax --provider qwen-token-plan
+```
+
 For CLI defaults, create `~/.kodax/config.json`:
 
 ```json
@@ -386,12 +408,16 @@ context diagnostics, and daemon protocol schemas, see
 The Space/IDE shared-daemon contract is documented in
 [SDK Embedder Guide section 23](docs/SDK_EMBEDDER_GUIDE.md#23-shared-coder-daemon-for-space-and-ide-hosts-feature_269-v0769).
 
-**v0.7.72 Runtime correction:** Auto Mode is now owned by the Runtime session,
+**v0.7.72–v0.7.73 Runtime permission contract:** Auto Mode is owned by the Runtime session,
 not by a UI hook. It reuses its LLM/rules guardrail across turns, classifies
 before the shared permission bridge, and persists an automatic fallback to
 rules. The same session settings can select a classifier model and bounded
-timeout. 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).
+timeout; `auto` defaults to LLM classification and fails with a recoverable
+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-v0772v0773).
 
 ## Repo Intelligence
 
@@ -411,7 +437,7 @@ KodaX uses a **monorepo architecture** with npm workspaces. Source layout curren
 ```
 KodaX/
 ├── packages/                # 4 workspace packages (FEATURE_194 v0.7.43)
-│   ├── llm/                 # @kodax-ai/llm - LLM abstraction (15 built-in provider aliases)
+│   ├── llm/                 # @kodax-ai/llm - LLM abstraction (16 built-in provider aliases)
 │   │   └── providers/       # Anthropic, OpenAI, DeepSeek, Kimi, MiMo, MiniMax, Zhipu, Ark, …
 │   │
 │   ├── agent/               # @kodax-ai/agent - Generic Agent framework
@@ -459,7 +485,7 @@ KodaX/
        ┌──────────────┐ ┌──────────────────────────┐ ┌──────────────┐
        │@kodax-ai/    │ │@kodax-ai/agent           │ │@kodax-ai/llm │
        │coding (via   │ │Runner + fan-out +        │ │LLM Abstract  │
-       │above)        │ │idle-yield + session-     │ │(15 aliases)  │
+       │above)        │ │idle-yield + session-     │ │(16 aliases)  │
        │              │ │lineage + skills + mcp +  │ │              │
        │              │ │tracing (FEATURE_194)     │ │              │
        └──────────────┘ └──────────────────────────┘ └──────────────┘
@@ -471,7 +497,7 @@ Source-side workspace package names (`@kodax-ai/*`). npm consumers install the s
 
 | Workspace package | Purpose | Key Dependencies |
 |---------|---------|------------------|
-| `@kodax-ai/llm` | LLM abstraction (15 built-in provider aliases + custom registration) | @anthropic-ai/sdk, openai |
+| `@kodax-ai/llm` | LLM abstraction (16 built-in provider aliases + custom registration) | @anthropic-ai/sdk, openai |
 | `@kodax-ai/agent` | Generic Agent framework — Runner, fan-out, idle-yield, media/input artifacts, session-lineage, capabilities (mcp + skills), tracing (ADR-036 v0.7.43 consolidation; subpaths: `/media`, `/session-lineage`, `/capabilities/mcp`, `/capabilities/skills`, `/tracing`) | @kodax-ai/llm, js-tiktoken, fflate, jimp, yaml |
 | `@kodax-ai/coding` | Coding Agent — 50+ tools (incl. canonical Actor collaboration tools) + role prompts + auto-continue + repo-intelligence protocol | @kodax-ai/llm, @kodax-ai/agent |
 | `@kodax-ai/repl` | Complete interactive terminal UI (Ink/React, permission modes, commands, streaming) | @kodax-ai/coding, ink, react |
@@ -487,7 +513,7 @@ KodaX has two layers that consumers should understand separately:
 
 | Source package | npm subpath | Type | What you get | Example consumer |
 |---|---|---|---|---|
-| `packages/llm`    | `@kodax-ai/kodax/llm`     | Full package | 15-alias LLM abstraction (108 exports) | Standalone LLM clients |
+| `packages/llm`    | `@kodax-ai/kodax/llm`     | Full package | 16-alias LLM abstraction (108 exports) | Standalone LLM clients |
 | `packages/agent`  | `@kodax-ai/kodax/agent`   | Full package | Runner / fan-out / external-agent plane / session-lineage / capabilities / tracing (331 exports) | Custom agent frameworks |
 | `packages/agent`  | `@kodax-ai/kodax/skills`  | **Narrow subset** | Skills system only — `SkillRegistry` / `loadFullSkill` / `expandSkillForLLM` / ... (26 exports = pre-v0.7.43 `@kodax-ai/skills` complete API) | Skill loaders, IDE plugins |
 | `packages/agent`  | `@kodax-ai/kodax/mcp`     | **Narrow subset** | MCP only — `McpCapabilityProvider` / `createMcpTransport` / `searchMcpCatalog` / ... (23 exports) | MCP server hosts |
@@ -511,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 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).
 
-**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).
+**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).
 
@@ -626,7 +658,7 @@ one-time provisioning).
 ## Features
 
 - **Modular Architecture** - Use as CLI, as a library, or as a Node-free single binary
-- **15 Built-in Provider Aliases** - Anthropic, OpenAI, DeepSeek, Kimi, Kimi Code, Qwen, Zhipu, Zhipu Coding, Zai Coding, MiniMax Coding, MiMo Coding, MiMo, Ark Coding, Gemini CLI, Codex CLI - plus user-defined OpenAI/Anthropic-compatible providers
+- **16 Built-in Provider Aliases** - Anthropic, OpenAI, DeepSeek, Kimi, Kimi Code, Qwen, Qwen Token Plan, Zhipu, Zhipu Coding, Zai Coding, MiniMax Coding, MiMo Coding, MiMo, Ark Coding, Gemini CLI, Codex CLI - plus user-defined OpenAI/Anthropic-compatible providers
 - **Dynamic Workflows + SDK Process Surface** - Generate/reuse capability-routed workflows, observe live progress through `WorkflowProcessSnapshot`, and control workflow lifecycle from SDK hosts without parsing REPL output
 - **V2 Worker single-loop + Sidecar Verifier (default)** - Single-agent main loop with an out-of-band Sidecar Verifier as Stop-hook (claudecode-shape; FEATURE_184 v0.7.42, ADR-030). Verifier returns accept/revise/blocked verdict on Worker text-only termination. The pre-v0.7.43 V1 chain is retired, `emit_handoff` is deleted, accept-verdict UI silently passes through, and content-aware gating skips trivial-chat sidecar calls. Adaptive child steering uses the canonical Actor collaboration tools with idle-yield waiting; specialist routing uses `spawn_agent(agent_id=...)`.
 - **Reasoning Effort** - Effort-first control (`off/auto/low/medium/high` plus model-supported extras) across providers
@@ -728,7 +760,7 @@ For smaller surface and tree-shake-friendly imports, the SDK is also exposed via
 
 ```typescript
 import { Runner } from '@kodax-ai/kodax/agent';                // agent runtime
-import { getProvider } from '@kodax-ai/kodax/llm';              // LLM abstraction (15 aliases)
+import { getProvider } from '@kodax-ai/kodax/llm';              // LLM abstraction (16 aliases)
 import { runKodaX } from '@kodax-ai/kodax/coding';              // coding tools + prompts
 import { createImageArtifactFromPath } from '@kodax-ai/kodax/media'; // input artifacts
 import { SkillRegistry } from '@kodax-ai/kodax/skills';         // zero-dep skill loader
@@ -855,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
@@ -896,6 +928,22 @@ 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.
+  Persistent grants are daemon-owned, revisioned, and can be listed/revoked
+  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
 
@@ -1059,7 +1107,7 @@ npm install @kodax-ai/kodax
 ```typescript
 import { runKodaX } from '@kodax-ai/kodax';                       // root: CLI helpers + runKodaX
 import { Runner, runFanOut } from '@kodax-ai/kodax/agent';        // generic Agent framework
-import { getProvider } from '@kodax-ai/kodax/llm';                // 15-alias LLM abstraction
+import { getProvider } from '@kodax-ai/kodax/llm';                // 16-alias LLM abstraction
 import { KODAX_TOOLS } from '@kodax-ai/kodax/coding';             // tools + prompts + agent loop
 import { createImageArtifactFromPath } from '@kodax-ai/kodax/media'; // input artifact helpers
 import { runInkInteractiveMode } from '@kodax-ai/kodax/repl';     // Ink TUI entrypoint
@@ -1075,7 +1123,7 @@ import { createMemoryAgent } from '@kodax-ai/kodax/experimental-memory'; // opt-
 
 ### `@kodax-ai/kodax/llm` — LLM Abstraction
 
-15 built-in provider aliases (Anthropic, OpenAI, DeepSeek, Kimi, Kimi-Code, Qwen, Zhipu, Zhipu-Coding, Zai-Coding, MiniMax-Coding, MiMo, MiMo-Coding, Ark-Coding, Gemini-CLI, Codex-CLI) + custom provider registration.
+16 built-in provider aliases (Anthropic, OpenAI, DeepSeek, Kimi, Kimi-Code, Qwen, Qwen-Token-Plan, Zhipu, Zhipu-Coding, Zai-Coding, MiniMax-Coding, MiMo, MiMo-Coding, Ark-Coding, Gemini-CLI, Codex-CLI) + custom provider registration.
 
 ```typescript
 import { getProvider, KodaXBaseProvider } from '@kodax-ai/kodax/llm';
@@ -1124,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
@@ -1213,7 +1265,7 @@ await runInkInteractiveMode({ provider: 'zhipu-coding', effort: 'auto' });
 
 | Use Case | Subpath | Why |
 |----------|---------|-----|
-| Only need LLM abstraction | `@kodax-ai/kodax/llm` | Minimal deps; 15 built-in aliases |
+| Only need LLM abstraction | `@kodax-ai/kodax/llm` | Minimal deps; 16 built-in aliases |
 | Building custom agent | `@kodax-ai/kodax/agent` | Runner + fan-out + idle-yield + session-lineage + capabilities |
 | Coding tasks | `@kodax-ai/kodax/coding` | Complete coding agent + tools |
 | Terminal app | `@kodax-ai/kodax/repl` | Full interactive experience |
@@ -1229,6 +1281,7 @@ await runInkInteractiveMode({ provider: 'zhipu-coding', effort: 'auto' });
 | kimi | `KIMI_API_KEY` | Native | kimi-k2.7-code (262,144-token context; `kimi-k2.7-code-highspeed` / `kimi-k2.6` / `kimi-k2.5` via `/model`) |
 | kimi-code | `KIMI_CODE_API_KEY` | Native | kimi-for-coding (`k3-256k` for Moderato / `k3` 1M for Allegretto+ / `kimi-for-coding-highspeed` via `/model`; both K3 choices use upstream `k3`) |
 | qwen | `QWEN_API_KEY` | Native | qwen3.5-plus |
+| qwen-token-plan | `QWEN_TOKEN_API_KEY` | Native | qwen3.8-max-preview (Anthropic-compat; `qwen3.7-max` / `qwen3.7-plus` / `qwen3.6-flash` / `glm-5.2` / `deepseek-v4-pro` via `/model`; all 1M context; image input on Qwen 3.8 / 3.7 Plus / 3.6 Flash) |
 | zhipu | `ZHIPU_API_KEY` | Native | glm-5 (`glm-5.2` 1M ctx / `glm-5.1` / `glm-5-turbo` via `/model`) |
 | zhipu-coding | `ZHIPU_CODING_API_KEY` | Native | glm-5.2 (1M ctx; legacy `glm-5.1` and `glm-5-turbo` remain selectable via `/model`) |
 | zai-coding | `ZAI_CODING_API_KEY` | Native | glm-5.2 (Zhipu Coding Plan overseas mirror via `api.z.ai`, Anthropic-compat — same model lineup as `zhipu-coding`, served from outside CN) |
@@ -1322,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. |
@@ -1465,6 +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, 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