@kodax-ai/kodax 0.7.72-hotfix.0 → 0.7.73

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.
 
@@ -94,7 +100,7 @@ That's it. You're in the REPL — ask anything in natural language.
       <h3>🤖 Multi-agent by default</h3>
       <sub>V2 Worker single-loop + Sidecar Verifier + async children</sub>
       <br><br>
-      <code>dispatch_child_task</code>, <code>send_message</code>, <code>task_stop</code>, multi-instance auto-coordination with content-hash safety net.
+      <code>spawn_agent</code>, <code>send_message</code>, <code>followup_task</code>, <code>interrupt_agent</code>, multi-instance auto-coordination with content-hash safety net.
     </td>
     <td align="center" valign="top">
       <h3>🧩 Skills + self-construction</h3>
@@ -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,6 +408,17 @@ 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–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; `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-v072).
+
 ## Repo Intelligence
 
 KodaX ships with built-in repo intelligence (`repo_overview`, `module_context`, `symbol_context`, `process_context`, `impact_estimate`, and related tools) that helps the coding agent understand large codebases without ad-hoc grep/glob exploration.
@@ -404,11 +437,11 @@ 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
-│   │   ├── orchestration/   # Runner, runFanOut, runWithIdleYield, ChildTaskRegistry
+│   │   ├── actors/          # Runtime-owned Actor tree, scheduler, mailbox, events
 │   │   ├── session-lineage/ # branchable session tree (inline v0.7.43)
 │   │   ├── capabilities/
 │   │   │   ├── mcp/         # MCP integration (inline v0.7.43)
@@ -417,7 +450,7 @@ KodaX/
 │   │
 │   ├── coding/              # @kodax-ai/coding - Coding Agent (tools + prompts)
 │   │   ├── tools/           # 50+ tools: read, write, edit, bash, glob, grep, undo,
-│   │   │                    #   dispatch_child_task, send_message, task_stop,
+│   │   │                    #   spawn_agent, send_message, followup_task, wait_agent,
 │   │   │                    #   ask_user_question, repo-intelligence, …
 │   │   └── repo-intelligence/ # incl. protocol.ts (inline v0.7.43)
 │   │
@@ -452,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)     │ │              │
        └──────────────┘ └──────────────────────────┘ └──────────────┘
@@ -464,9 +497,9 @@ 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. `dispatch_child_task` / `send_message` / `task_stop`) + role prompts + auto-continue + repo-intelligence protocol | @kodax-ai/llm, @kodax-ai/agent |
+| `@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 |
 
 ### Source-side vs npm-published surface
@@ -480,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 |
@@ -500,11 +533,11 @@ KodaX has two layers that consumers should understand separately:
 
 **Host Reads Persisted History (FEATURE_230 + FEATURE_234, v0.7.51; v0.7.63 hardening)**: additive closures for hosts that read persisted state. **Durable tool transcript replay** — a resumed session now replays the tool cards the assistant used instead of degrading to text-only. `messages` / `lineage` stay canonical; `SessionData.uiHistory` becomes a bounded, sanitized, terminal-only replay cache. The SDK transcript contract is explicit: `loadSession()` = active model context, `loadFullTranscript()` = append-order host scrollback with typed entries (`message` / `compaction` / `branch_summary` / `rewind_marker` / `client_notice` / `task_result`) plus clone provenance (`logicalId` / `sourceEntryId`), `uiHistory` = optional replay cache, and tool cards can always be reconstructed from canonical messages. Hosts can persist local slash output with `appendClientNotice()` without entering model context, and workflow/child completions expose structured `taskResults[]` instead of requiring `<task-completed>` parsing. `rewind_marker` is an audit entry for host scrollback only and is excluded from model-context messages. **Workflow run host attribution** — `WorkflowProcessTrackerOptions` / `WorkflowProcessSnapshot` gain a host-owned opaque `hostMetadata?: Record<string, string>` that the SDK stores, persists to `run.json`, and echoes back (including after a restart) without interpreting it, so a host can map a run to the session/surface that launched it with zero side table. Unstamped/legacy runs honestly echo `hostMetadata === undefined`. See [docs/features/v0.7.51.md](docs/features/v0.7.51.md).
 
-**Inline Workflow Authoring (FEATURE_246, v0.7.58)**: in AMA/AMAW the Worker can now author and run a workflow inline via a model-callable `run_workflow` tool — it scouts the codebase with its own tools first, then bakes concrete findings into each child prompt, and runs the script through the **unchanged** sandbox + static-validation + postcondition-verification pipeline. This replaces the context-blind `sideQuery` generator as the primary interactive path (the generator survives only as a fallback for the explicit `/workflow create` command and non-interactive / CI hosts that have no investigating Worker). It adds structured child output (`outputSchema`), the no-barrier `wf.pipeline` staged primitive, same-session resume (`resumeFromRunId`), nested `wf.workflow(...)`, and a `/workflow create` redirect to Worker-authored scouting; `run_workflow` is async / idle-yield so the turn is not blocked. The neutral run-lifecycle manager (`createWorkflowRunManager` / `getDefaultWorkflowRunManager`) now lives in `@kodax-ai/kodax/agent` for non-coding SDK hosts. See [docs/features/v0.7.58.md](docs/features/v0.7.58.md) and [docs/ADR.md](docs/ADR.md) ADR-044/046/047/048/049.
+**Inline Workflow Authoring (FEATURE_246, v0.7.58; F270 update in v0.7.72)**: the Worker can author and run a workflow inline via the model-callable `run_workflow` tool when Workflow intent is explicit. It scouts the codebase first, bakes concrete findings into child prompts, and runs the script through the sandbox, static-validation, and postcondition-verification pipeline. F270 retires AMAW and complexity-driven activation; AMA keeps explicit `/workflow`, named/SDK, and natural-language Workflow requests. Workflow child Agents now run on the unified Actor control plane. See [docs/features/v0.7.58.md](docs/features/v0.7.58.md), [docs/features/v0.7.72.md](docs/features/v0.7.72.md), and ADR-044/046/047/048/049/055.
 
-**Workflow Activation Tiers (FEATURE_248 + FEATURE_249, v0.7.59)**: the three agent modes now have a coherent workflow posture. **AMAW** carries a mode-level `ORCHESTRATION DEFAULT` standing directive (mirroring the reference "ultracode" posture): substantive work — a multi-file investigation, a design decision, anything costly to get wrong — defaults to orchestrating multiple cross-checking agents, with a PLAN-TIME COMMITMENT flow-fix that front-loads the orchestrate-vs-solo call to turn 0. **AMA** hosts the same `run_workflow` tool but with no standing directive — it activates a workflow when you ask for orchestration in natural language, never on complexity alone. **SA** stays solo. The directive is leak-closed via `amawOrchestrationAvailable`, so AMA and SA prompts stay byte-identical. See [docs/features/v0.7.59.md](docs/features/v0.7.59.md).
+**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)**: the deferred-tool progressive-disclosure mechanism — previously SA-path-only — now applies to the AMA/AMAW **managed** path too. 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. Transparent to users; validated by two 5-alias eval panels (DEFER_SAFE 5/5, 0% read/grep fallback). 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; 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).
 
 **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).
 
@@ -619,9 +652,9 @@ 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. Async child steering uses `dispatch_child_task` + `send_message` + `task_stop` with idle-yield wait; specialist routing uses `subagent_type`.
+- **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
 - **Streaming Output** - Real-time response display
 - **Session Management** - JSONL format with branchable session lineage tree
@@ -721,7 +754,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
@@ -806,7 +839,12 @@ Bare `-r` opens an interactive picker with incremental search, arrow/PageUp/Page
 navigation, Tab completion, full selected-session ID display, and Enter-to-resume.
 An explicit value checks the complete session ID first, then an exact
 case-insensitive title; duplicate titles open a narrowed picker instead of
-silently choosing one. Cleanup is preview-only unless
+silently choosing one. The picker loads before the full CLI, so session listing
+remains responsive. After selection it hands terminal input to the resumed
+REPL; Esc releases the picker's stdin ownership and immediately returns to the
+invoking shell. Session replay preserves each recorded message/event timestamp.
+
+Cleanup is preview-only unless
 `--apply-session-cleanup` is also provided; matching sessions are archived rather
 than permanently deleted.
 
@@ -862,14 +900,14 @@ KodaX provides 3 permission modes for fine-grained control:
 |------|-------------|------------------------|
 | `plan` | Read-only planning mode | All modification tools blocked |
 | `accept-edits` | Auto-accept file edits | bash only |
-| `auto-in-project` | Full auto within project | None (project-scoped) |
+| `auto` | Runtime-owned LLM/rules classification within the project boundary | Only explicit classifier escalation |
 
 ```bash
 # In REPL, use /mode command
 /mode plan          # Switch to plan mode (read-only)
 /mode accept-edits  # Switch to accept-edits mode
-/mode auto-in-project  # Switch to auto-in-project mode
-/auto                  # Alias for auto-in-project
+/mode auto             # Switch to Runtime-owned Auto Mode
+/auto                  # Alias for auto
 
 # Check current mode
 /mode
@@ -881,6 +919,15 @@ KodaX provides 3 permission modes for fine-grained control:
 - Permanent protection zones: `.kodax/`, `~/.kodax/`, paths outside project
 - Pattern-based permission: Allow specific Bash commands (e.g., `Bash(npm install)`)
 - Unified diff display for write/edit operations
+- 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.
+- 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.
 
 ### CLI Help Topics
 
@@ -1044,7 +1091,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
@@ -1060,7 +1107,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';
@@ -1088,8 +1135,7 @@ import {
   Runner,
   runFanOut,
   runWithIdleYield,
-  registerChildTask,
-  type ChildTaskRegistry,
+  createAgentActorController,
   generateSessionId,
   estimateTokens,
   DefaultSummaryCompaction,
@@ -1102,14 +1148,15 @@ const result = await runFanOut({
   run: async (bundle) => doWork(bundle),
 });
 
-// Idle-yield wait — pause when out of useful work, resume when a wake event arrives
-await runWithIdleYield({ runOnce, computeSnapshot, registry, messageQueue, agentId });
+// Runtime-owned Actor identity tree (inject an executor before starting Turns)
+const actors = await createAgentActorController();
+const tree = actors.list('/root');
 
 // Pluggable compaction policy (FEATURE_081)
 const policy = new DefaultSummaryCompaction({ thresholdRatio: 0.8, keepRecent: 10 });
 ```
 
-**Key Features**: `Runner` + per-step lifecycle · `runFanOut` (bounded-concurrency + abort + progress events) · `runWithIdleYield` (chat-while-waiting) · `ChildTaskRegistry` / `TaskAbortRegistry` · session-id generation · tiktoken-based token estimation · `CompactionPolicy` interface.
+**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
 
@@ -1138,7 +1185,7 @@ const result = await executeSkill({
 
 ### `@kodax-ai/kodax/coding` — Coding Agent
 
-Complete coding agent: 50+ tools (`read`/`write`/`edit`/`bash`/`grep`/`glob`/`dispatch_child_task`/`send_message`/`task_stop`/...) + Worker role prompt + Sidecar Verifier (out-of-band Stop-hook) + agent loop + auto-continue + session management.
+Complete coding agent: 50+ tools (`read`/`write`/`edit`/`bash`/`grep`/`glob` plus `spawn_agent`/`send_message`/`followup_task`/`wait_agent`/`interrupt_agent`/`list_agents`/`agent_output`) + Worker role prompt + Sidecar Verifier (out-of-band Stop-hook) + agent loop + auto-continue + session management.
 
 ```typescript
 import { runKodaX, KodaXClient, KODAX_TOOLS } from '@kodax-ai/kodax/coding';
@@ -1160,7 +1207,7 @@ await client.send('Create a new file');
 await client.send('Add a function to it'); // Has context from previous message
 ```
 
-**Key Features**: 50+ built-in tools (see [Tools](#tools)) · V2 Worker single-loop + Sidecar Verifier (FEATURE_184 v0.7.42 / V1 chain fully retired by FEATURE_193 v0.7.43) · async child steering via `send_message` / `task_stop` (FEATURE_120, v0.7.39) · idle-yield wait mechanic (FEATURE_155, v0.7.38) · specialist routing via `subagent_type` (FEATURE_191, v0.7.43) · auto-continue · session lineage.
+**Key Features**: 50+ built-in tools (see [Tools](#tools)) · V2 Worker single-loop + Sidecar Verifier (FEATURE_184 v0.7.42 / V1 chain fully retired by FEATURE_193 v0.7.43) · Runtime-owned Actor collaboration and safe-boundary steering (FEATURE_270, v0.7.72) · idle-yield waiting · specialist routing via `spawn_agent(agent_id=...)` · auto-continue · session lineage.
 
 ### `@kodax-ai/kodax/repl` — Interactive Terminal UI
 
@@ -1198,7 +1245,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 |
@@ -1214,10 +1261,11 @@ 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 (`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) |
-| minimax-coding | `MINIMAX_CODING_API_KEY` | Native | MiniMax-M2.7 (`MiniMax-M3` Frontier Coding, native multimodal + 1M ctx, plus `MiniMax-M2.7-highspeed` via `/model`) |
+| minimax-coding | `MINIMAX_CODING_API_KEY` | Native | MiniMax-M3 (Frontier Coding, native multimodal + 1M ctx; legacy `MiniMax-M2.7` / `MiniMax-M2.7-highspeed` remain selectable via `/model`) |
 | mimo | `MIMO_API_KEY` | Native | mimo-v2.5-pro (Xiaomi MiMo pay-per-token, Anthropic-compat) |
 | mimo-coding | `MIMO_CODING_API_KEY` | Native | mimo-v2.5-pro (Xiaomi Token Plan, Anthropic-compat) |
 | ark-coding | `ARK_CODING_API_KEY` | Native | glm-5.2 (Volcengine Ark Coding Plan — GLM-5.2 (alias: `glm-latest`) · Kimi K2.7 Code / K2.6 · MiniMax M3 / M2.7 · DeepSeek V4 Pro / V4 Flash · Doubao Seed 2.0 Code / Pro / Lite · Doubao Seed Code) |
@@ -1246,7 +1294,7 @@ kodax --session list
 # Parallel tool execution
 kodax --parallel "Read package.json and tsconfig.json"
 
-# Adaptive multi-agent (AMA) mode — V2 Worker single-loop with `dispatch_child_task` fan-out
+# Adaptive multi-agent (AMA) mode — V2 Worker single-loop with Actor collaboration
 kodax --agent-mode ama "Analyze code structure, check test coverage, find bugs"
 ```
 
@@ -1304,12 +1352,16 @@ KodaX ships 50+ built-in tools, grouped below. They are registered as a single f
 ### Agent control & UX
 | Tool | Description |
 |------|-------------|
-| `dispatch_child_task` | Spawn a sub-agent for an independent investigation/edit task. Optional `model_hint: 'fast' \| 'balanced' \| 'deep'` (advisory; routing no-op until FEATURE_102 v0.7.45). |
-| `send_message` | Append an instruction to an in-flight child's queue — surfaces as `<coordinator-instruction>` at the child's next turn boundary. Coordinator-only. (FEATURE_120, v0.7.39) |
-| `task_stop` | Request graceful exit of a specific child. Current tool finishes atomically, then the child sees a `<coordinator-stop-request>` and emits a final summary. Coordinator-only. (FEATURE_120, v0.7.39) |
+| `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. |
+| `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. |
 | `ask_user_question` | Single/multi-select or free-text prompt back to the user |
-| `exit_plan_mode` | Present a finalized plan for approval (REPL only) |
-| `run_workflow` | Author and run a workflow script inline. Hosted in AMAW (self-activates on complexity via the ORCHESTRATION DEFAULT directive) and AMA (activates on an explicit natural-language request); not in SA. Scouts the codebase first, then bakes findings into child prompts; structured output via `outputSchema`, same-session `resumeFromRunId`, nested `wf.workflow(...)`. Async / idle-yield. (FEATURE_246 v0.7.58; FEATURE_248/249 v0.7.59) |
+| `exit_plan_mode` | Present a finalized plan only when the active REPL/host supplied an approval callback |
+| `run_workflow` | Author and run a deterministic Workflow protocol in AMA only when Workflow intent is explicit; complexity alone never activates it. Child Agents share the Actor control plane. Async / idle-yield. (FEATURE_246; FEATURE_270 v0.7.72) |
 | `emit_managed_protocol` | Internal managed-task protocol side-channel for role payloads (verdict). V2 Worker single-loop + Sidecar Verifier is the default since v0.7.42 (FEATURE_184); V1 chain retired in v0.7.43 (FEATURE_193). |
 
 ---
@@ -1446,6 +1498,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/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

@@ -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,15 @@ npm i -g @kodax-ai/kodax
 # 选一个你有 API key 的 provider
 export ZHIPU_API_KEY=...        # 或 KIMI_API_KEY / MINIMAX_API_KEY / MIMO_API_KEY /
                                 # ARK_API_KEY / DEEPSEEK_API_KEY / ANTHROPIC_API_KEY /
-                                # OPENAI_API_KEY / QWEN_API_KEY / GEMINI_API_KEY
+                                # OPENAI_API_KEY / QWEN_API_KEY / QWEN_TOKEN_API_KEY / GEMINI_API_KEY
 
 kodax
 ```
 
-就这样。进 REPL，自然语言提问。
+就这样。进 REPL，自然语言提问。如果新机器既没有选择 provider，也没有任何
+受支持的 API Key 环境变量，直接运行 `kodax` 会先打开只配置元数据的向导；它不会
+要求输入或保存 Key。选择 provider/model 后，按提示设置对应环境变量、重启终端，
+再运行 `kodax`。需要主动重新配置时可运行 `kodax setup`。
 
 > **不装 Node 的目标机器**：从 [GitHub Releases](https://github.com/icetomoyo/KodaX/releases) 拿 Bun 编译的单文件二进制（Win / macOS / Linux × x64 + arm64）。详见 [docs/release.md](docs/release.md)。
 
@@ -88,6 +91,17 @@ daemon，不会再次打开 GUI。`ELECTRON_RUN_AS_NODE` 只存在于子进程
 再使用 attach-only 模式连接。SDK 的 `homeDir` 是拥有 `.kodax` 的 CLI 风格基础目录，
 不是 `.kodax` 目录本身。
 
+**v0.7.72–v0.7.73 Runtime 权限契约：**Auto Mode 的权限决策由 Runtime Session 持有，
+不再由 UI hook 抢先决定。Runtime 会跨 turn 复用 LLM/rules guardrail，先分类、
+仅在 `escalate` 时创建共享 permission 请求，并把自动降级到 rules 的结果持久化到
+session。Session 也可设置 classifier model 和有界 timeout；`auto` 默认使用 LLM
+分类，没有有效 classifier model 时会在调用 provider 或创建审批前返回可恢复配置错误，
+绝不静默退回 rules。Runtime 权限请求可给出由 Runtime 生成的精确作用域建议：一次允许、
+本 Session 允许，或（仅安全场景）持久允许；客户端只能回传不透明 suggestion id，不能从
+预览内容自行扩大范围。持久授权由 daemon 持有并通过 revision 管理。没有宿主审批回调时，
+不会向模型暴露 `exit_plan_mode`。完整 SDK 接入见
+[Runtime Auto Mode 指引](docs/SDK_EMBEDDER_GUIDE.md#24-runtime-owned-auto-mode-and-plan-approval-bridges-v072)。
+
 ## 为什么用 KodaX
 
 <table>
@@ -116,7 +130,7 @@ daemon，不会再次打开 GUI。`ELECTRON_RUN_AS_NODE` 只存在于子进程
       <h3>🤖 默认多 agent</h3>
       <sub>V2 Worker 单循环 + Sidecar Verifier + 异步子 agent</sub>
       <br><br>
-      <code>dispatch_child_task</code>、<code>send_message</code>、<code>task_stop</code>，多实例自动协调（content-hash safety net）。
+      <code>spawn_agent</code>、<code>send_message</code>、<code>followup_task</code>、<code>interrupt_agent</code>，多实例自动协调（content-hash safety net）。
     </td>
     <td align="center" valign="top">
       <h3>🧩 Skills + 自构造</h3>
@@ -167,7 +181,14 @@ kodax
 
 ### 2. 配置模型提供商
 
-最简单的方式是先设置 API Key：
+可以先运行不会收集 Key 的交互配置：
+
+```bash
+kodax setup
+```
+
+命令会保存 provider/model，告诉你准确的环境变量名，然后退出以便重启终端。
+也可以直接设置 API Key：
 
 ```bash
 # macOS / Linux
@@ -177,6 +198,14 @@ export ZHIPU_API_KEY=your_api_key
 $env:ZHIPU_API_KEY="your_api_key"
 ```
 
+Qwen Token Plan 需要选择 `qwen-token-plan` 并使用单独的凭据；`QWEN_API_KEY`
+不能用于该路由：
+
+```bash
+export QWEN_TOKEN_API_KEY=your_api_key
+kodax --provider qwen-token-plan
+```
+
 然后在 `~/.kodax/config.json` 里写一个最小配置：
 
 ```json
@@ -228,7 +257,7 @@ const result = await runKodaX(
 
 ```typescript
 import { Runner } from '@kodax-ai/kodax/agent';                // Agent runtime
-import { getProvider } from '@kodax-ai/kodax/llm';              // LLM 抽象（15 个内置 alias）
+import { getProvider } from '@kodax-ai/kodax/llm';              // LLM 抽象（16 个内置 alias）
 import { runKodaX } from '@kodax-ai/kodax/coding';              // Coding tools + prompts
 import { createImageArtifactFromPath } from '@kodax-ai/kodax/media'; // 输入 artifact helpers
 import { SkillRegistry } from '@kodax-ai/kodax/skills';         // 零依赖 skill loader
@@ -465,10 +494,11 @@ dist/binary/linux-x64/
 | kimi | `KIMI_API_KEY` | Native | kimi-k2.7-code（262,144 token；可 `/model` 切换 `kimi-k2.7-code-highspeed` / `kimi-k2.6` / `kimi-k2.5`） |
 | kimi-code | `KIMI_CODE_API_KEY` | Native | kimi-for-coding（可 `/model` 切换 `k3-256k`〔Moderato，256K〕/ `k3`〔Allegretto+，1M〕/ `kimi-for-coding-highspeed`；两个 K3 选项均请求上游 `k3`） |
 | qwen | `QWEN_API_KEY` | Native | qwen3.5-plus |
+| 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 支持图片理解） |
 | zhipu | `ZHIPU_API_KEY` | Native | glm-5（可 `/model` 切换 `glm-5.2` 1M ctx / `glm-5.1` / `glm-5-turbo`） |
-| zhipu-coding | `ZHIPU_CODING_API_KEY` | Native | glm-5（GLM Coding Plan；可 `/model` 切换 `glm-5.2` 1M ctx / `glm-5.1` / `glm-5-turbo`） |
+| zhipu-coding | `ZHIPU_CODING_API_KEY` | Native | glm-5.2（1M ctx；仍可通过 `/model` 显式选择兼容模型 `glm-5.1` / `glm-5-turbo`） |
 | zai-coding | `ZAI_CODING_API_KEY` | Native | glm-5.2（GLM Coding Plan 海外站，通过 `api.z.ai` 接入，Anthropic 协议 — 模型清单和 `zhipu-coding` 完全一致） |
-| minimax-coding | `MINIMAX_CODING_API_KEY` | Native | MiniMax-M2.7（可 `/model` 切换 `MiniMax-M3` Frontier Coding，原生多模态 + 1M ctx；以及 `MiniMax-M2.7-highspeed`） |
+| minimax-coding | `MINIMAX_CODING_API_KEY` | Native | MiniMax-M3（Frontier Coding，原生多模态 + 1M ctx；仍可通过 `/model` 显式选择兼容模型 `MiniMax-M2.7` / `MiniMax-M2.7-highspeed`） |
 | mimo | `MIMO_API_KEY` | Native | mimo-v2.5-pro（小米 MiMo 按量计费，Anthropic 协议） |
 | mimo-coding | `MIMO_CODING_API_KEY` | Native | mimo-v2.5-pro（小米 MiMo Token Plan，Anthropic 协议） |
 | ark-coding | `ARK_CODING_API_KEY` | Native | glm-5.2（火山方舟 Coding Plan — GLM-5.2（别名 `glm-latest`） · Kimi K2.7 Code / K2.6 · MiniMax M3 / M2.7 · DeepSeek V4 Pro / V4 Flash · Doubao Seed 2.0 Code / Pro / Lite · Doubao Seed Code） |
@@ -533,11 +563,15 @@ KodaX 有 50+ 个内置工具，按类别分组如下（实际暴露给 LLM 是
 
 | 工具 | 说明 |
 |------|------|
-| `dispatch_child_task` | 派发子 agent 跑独立调研 / 改动任务。可选 `model_hint: 'fast' \| 'balanced' \| 'deep'`（advisory 标记，routing 在 FEATURE_102 v0.7.45 之前是 no-op） |
-| `send_message` | 给在跑 child 队列追加一条 `<coordinator-instruction>` 指令，child 下一个 turn 边界看到。仅 coordinator 可用。(FEATURE_120, v0.7.39) |
-| `task_stop` | 请求指定 child 优雅退出。当前 tool 原子结束后 child 看到 `<coordinator-stop-request>` 并 emit 最终摘要。仅 coordinator 可用。(FEATURE_120, v0.7.39) |
+| `spawn_agent` | 创建命名子 Actor，并在继承权限、会话并发和根工作预算约束下启动首个 Turn。 |
+| `send_message` | 向 Actor 的持久 mailbox 提交有界信息，不启动新 Turn。 |
+| `followup_task` | 在安全边界加入运行中的 Actor，或为 idle Actor 原子启动新 Turn。 |
+| `wait_agent` | 等待一个或多个 Actor 状态变化，不轮询第二套任务注册表。 |
+| `interrupt_agent` | 请求中断 active Turn，同时保留 Actor 身份。 |
+| `list_agents` | 查看调用方有权访问的 Actor 子树与 Turn 状态。 |
+| `agent_output` | 读取有权限的 Actor/Turn 有界持久输出。 |
 | `ask_user_question` | 向用户发起单选 / 多选 / 自由文本提问 |
-| `exit_plan_mode` | Plan 模式下提交最终方案给用户审批（仅 REPL） |
+| `exit_plan_mode` | 仅在当前 REPL/宿主提供审批回调时提交最终方案 |
 | `emit_managed_protocol` | managed-task 协议侧信道（verdict role payload）。v0.7.42 FEATURE_184 起默认走 V2 Worker 单循环 + Sidecar Verifier；v0.7.43 FEATURE_193 退役 V1 chain。 |
 
 ## Repo Intelligence（内置 full/light 引擎）
@@ -557,9 +591,9 @@ KodaX 是基于 npm workspaces 的 TypeScript monorepo，**源码层 4 个 works
 
 | Workspace 包 | 作用 | 主要依赖 |
 |----|------|---------|
-| `@kodax-ai/llm` | LLM 抽象层（15 个内置 provider alias + 自定义 provider 注册），可独立使用 | `@anthropic-ai/sdk`, `openai` |
-| `@kodax-ai/agent` | 通用 Agent 框架 —— Runner / runFanOut / runWithIdleYield / ChildTaskRegistry + 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/coding` | Coding Agent:50+ 工具(含 `dispatch_child_task`/`send_message`/`task_stop`)、role prompts、agent loop、auto-continue + repo-intelligence protocol(v0.7.43 inline) | `@kodax-ai/llm`, `@kodax-ai/agent` |
+| `@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/coding` | Coding Agent:50+ 工具（含 canonical Actor 协作工具）、role prompts、agent loop、auto-continue + repo-intelligence protocol(v0.7.43 inline) | `@kodax-ai/llm`, `@kodax-ai/agent` |
 | `@kodax-ai/repl` | 完整交互式终端 UI（Ink / React、权限模式、命令系统、流式渲染） | `@kodax-ai/coding`, `ink`, `react` |
 
 根目录 `src/kodax_cli.ts` 是 CLI 入口；`src/sdk-{agent,llm,coding,media,repl,skills,mcp,session,runtime,a2a,experimental-memory}.ts` 是 SDK subpath 入口；构建产物在 `dist/`，单文件二进制在 `dist/binary/<target>/`。
@@ -677,22 +711,28 @@ A2A 配置迁移与历史任务 owner 迁移是两件事。如果升级 realm-aw
 精确授权的 Skill 脚本必须使用隔离策略，并通过 `kodax sandbox doctor`；
 Windows 的一次性显式初始化由 `kodax sandbox setup` 完成。
 
+**v0.7.72 会话恢复与队列闭环：**裸 `kodax -r` 先加载可搜索选择器，不为列出
+session 预加载完整 CLI；选中后才把 stdin 交给恢复后的 REPL，Esc 会释放选择器的
+stdin 并立即回到原 shell。历史回放保留每条持久 event 的原始时间。用户 follow-up
+使用 session-root Actor queue scope，避免一个 session/child 的待处理输入被另一个
+REPL 显示、唤醒或消费。
+
 **外部 Agent SDK plane（FEATURE_258，v0.7.67）**：`/agent` 导出协议中立的 executor、registration、policy、credential broker、artifact policy、catalog 和 durable task 契约；`/runtime` 通过 `admin.agentRegistrations`、`agents`、`agentTasks` 向 embedded 与 daemon client 提供同一组 DTO API。Executor factory 是宿主函数，只能装入 inline owner，或在创建新的 in-process daemon owner 时装入；不能通过既有 daemon 连接或 Runtime Worker 边界注入。Plane 关闭后是终态：未完成的 wait 和后续所有服务调用都会拒绝；受限 Workflow 脚本会完整校验并传递 `phase` 与外部 `target`。完整所有权、注册、preflight、启动/等待/继续/取消/对账和安全边界见 [SDK Embedder Guide §18](docs/SDK_EMBEDDER_GUIDE.md#18-external-agent-executor-plane-feature_258-v0767)。
 
 **成本受控 Workflow SDK（FEATURE_259，v0.7.67）**：SDK 调用方用 run-scoped `modelTiers` 与 `workflow.maxConcurrency` 配置路由和并发，workflow 作者只表达 `fast` / `balanced` / `deep` 语义意图。terminal workflow event 回显 tier/source/fallback/usage/duration，持久化 `run.json.efficiencyReport` 给出 token coverage、role/tier 启动数、packet-read 拓扑、review wave 和 quality gate 结果。完整配置与遥测读取方式见 [SDK Embedder Guide §20](docs/SDK_EMBEDDER_GUIDE.md#20-cost-disciplined-workflow-routing-and-telemetry-feature_259-v0767)。
 
-**Inline workflow authoring（FEATURE_246，v0.7.58）**：AMA/AMAW 下 Worker 现在可通过 model-callable 的 `run_workflow` 工具在会话内直接编写并运行工作流——先用自己的工具 scout 代码库，再把具体发现烤进每个 child prompt，然后走**不变的** sandbox + 静态校验 + postcondition 验证流水线。它取代 context-blind 的 `sideQuery` generator 成为主交互路径（generator 仅作为显式 `/workflow create` 命令与无 investigating Worker 的 non-interactive/CI 主机的 fallback 保留）；新增结构化 child 输出（`outputSchema`）、无 barrier 的 `wf.pipeline` 分阶段原语、同会话 resume（`resumeFromRunId`）、嵌套 `wf.workflow(...)`，`/workflow create` 重定向到 Worker 的 scout-then-author；`run_workflow` 为 async / idle-yield，不阻塞当前轮。中立的 run-lifecycle manager（`createWorkflowRunManager`）已移入 `@kodax-ai/kodax/agent` 供非 coding SDK 宿主使用。详见 [docs/features/v0.7.58.md](docs/features/v0.7.58.md) 与 [docs/ADR.md](docs/ADR.md) ADR-044/046/047/048/049。
+**Inline workflow authoring（FEATURE_246，v0.7.58；F270 于 v0.7.72 更新）**：Worker 在明确表达 Workflow 意图时，可通过 model-callable 的 `run_workflow` 工具在会话内编写并运行工作流。F270 退役 AMAW 与复杂度驱动激活；AMA 保留显式 `/workflow`、named/SDK 和自然语言 Workflow 请求。Workflow 子 Agent 统一运行在 Actor 控制面。详见 [docs/features/v0.7.58.md](docs/features/v0.7.58.md)、[docs/features/v0.7.72.md](docs/features/v0.7.72.md) 与 ADR-044/046/047/048/049/055。
 
-**工作流激活分层（FEATURE_248 + FEATURE_249，v0.7.59）**：三种 agent 模式现在有一致的工作流姿态。**AMAW** 携带 mode-level 的 `ORCHESTRATION DEFAULT` 常驻指令（对齐参考实现的 "ultracode" 姿态）：实质性工作——多文件调查、设计决策、任何做错代价高的任务——默认编排多个交叉验证的 agent，并有 PLAN-TIME COMMITMENT 流程修正把 orchestrate-vs-solo 决策前置到第 0 轮。**AMA** 同样 host `run_workflow` 工具但没有常驻指令——当你用自然语言请求编排时才激活，绝不因复杂度独自触发。**SA** 保持单独作业。该指令通过 `amawOrchestrationAvailable` 关闭泄漏，因此 AMA 与 SA 的 prompt 保持逐字节一致。详见 [docs/features/v0.7.59.md](docs/features/v0.7.59.md)。
+**历史工作流激活分层（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）**：deferred-tool 渐进披露机制——此前仅 SA path 拥有——现在也应用于 AMA/AMAW 的 **managed** path。缓存冷启的 managed 轮次对 13 个 non-mcp 延迟工具（repo-intelligence + web/code + goal）携带一行 search hint 而非完整描述；每个工具的 `input_schema` 不变，因此仍可直接调用，完整描述按需通过 `tool_search` 拉取。`mcp_*` 保持常驻，`run_workflow` 不动。对用户透明；由两个 5-alias eval panel 验证（DEFER_SAFE 5/5，0% read/grep 回退）。详见 [docs/features/v0.7.60.md](docs/features/v0.7.60.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)。
 
 **上下文高效的工具结果 + 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)。
 
 ```
 KodaX/                       # 4 workspace packages(FEATURE_194 v0.7.43)
 ├── packages/
-│   ├── llm/                 # @kodax-ai/llm —— 15 个内置 provider alias
+│   ├── llm/                 # @kodax-ai/llm —— 16 个内置 provider alias
 │   ├── agent/               # @kodax-ai/agent —— Runner / fan-out / idle-yield + 子树:
 │   │   ├── session-lineage/ # 分支 session tree (v0.7.43 inline)
 │   │   ├── capabilities/
@@ -800,7 +840,7 @@ KodaX 现在会把 Repo Intelligence 的本地缓存分成内置引擎 profile
 ## 文档
 
 - [README.md](README.md) - 英文版 README
-- [docs/SDK_EMBEDDER_GUIDE.md](docs/SDK_EMBEDDER_GUIDE.md) - SDK 宿主集成与 v0.7.70 公共 API 契约
+- [docs/SDK_EMBEDDER_GUIDE.md](docs/SDK_EMBEDDER_GUIDE.md) - SDK 宿主集成、shared Runtime、v0.7.73 Auto Mode 与精确授权契约
 - [docs/release.md](docs/release.md) - 单文件二进制构建与发布流程
 - [docs/PRD.md](docs/PRD.md) - 产品需求
 - [docs/ADR.md](docs/ADR.md) - 架构决策

package/dist/chunks/agent-T6PGT6AU.js

@@ -0,0 +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};

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

@@ -0,0 +1,2 @@
+// @kodax-ai/kodax — bundled distribution. See docs/ADR.md ADR-022 + ADR-024.
+import{Ea as a,Fa as b}from"./chunk-6JTWXGVU.js";import"./chunk-MLEAQTCD.js";import"./chunk-PFH53O4M.js";import"./chunk-EAD4SF3Z.js";import"./chunk-6RI2RBTF.js";import"./chunk-M7FXNPWV.js";import"./chunk-AGDDM5AW.js";import"./chunk-64M5HOCA.js";import"./chunk-MBAPT2R5.js";import"./chunk-HVCNAZ52.js";import"./chunk-XXQLPTAN.js";import"./chunk-OG6DRNKV.js";import"./chunk-GAFFYJU3.js";import"./chunk-BUPJGG3C.js";import"./chunk-F7AIEHSS.js";import"./chunk-ONUPGMER.js";export{a as ArgumentCompleter,b as createArgumentCompleter};