@kodax-ai/kodax 0.7.49 → 0.7.50

package/CHANGELOG.md

@@ -4,6 +4,38 @@ All notable changes to this project will be documented in this file.
 
 > Full history for versions prior to v0.7.0: [CHANGELOG_ARCHIVE.md](docs/CHANGELOG_ARCHIVE.md)
 
+## [0.7.50] - 2026-06-16
+
+> Scope note: v0.7.50 is a single-feature slot for **FEATURE_229**. It does **not** rewrite FEATURE_217 (v0.7.49) — the dynamic JS harness, capsule model, save/rerun, worktree isolation, and permission gates all stay. F229 lifts the v0.7.49 user-visible workflow process into a subscribable Agent-layer event/snapshot model and a Coding/SDK lifecycle surface. `FEATURE_224` was rescheduled to [v0.7.51](docs/features/v0.7.51.md).
+
+### Added
+
+- **FEATURE_229 — Workflow Process Events + SDK/System Progress Surface.** Workflow progress is now a first-class, subscribable process — not private REPL text — so SDK hosts, the REPL inline/fullscreen surface, and future automation all consume one source of truth.
+  - **Agent-layer process model** (`@kodax-ai/agent/workflow`, domain-neutral): `WorkflowProcessSnapshot`, `WorkflowProcessItem` (with `summaryStatus: 'pending' | 'result' | 'notice' | 'unavailable'`), the three-type `WorkflowProcessEvent` (`workflow_started` / `workflow_updated` / `workflow_finished`), `WorkflowEventCorrelation`, and the `isFinalWorkflowProcessStatus` terminal-state helper. A thin reducer folds existing `WorkflowEvent` records into snapshots without making generated scripts aware of process state; token usage, artifacts, counts, and phase/agent progress are tracked per run.
+  - **Async child digest split (§7.1).** Child completion is no longer blocked by digest generation: a finished child immediately emits `completed` + `summaryStatus:'pending'` (interim deterministic excerpt), and the model-authored digest is delivered off the critical path via the runtime's domain-neutral `updateTaskSummary(taskId, { summary, summaryStatus })` channel as a later `workflow_updated` (`result`, or `unavailable` on failure/timeout). Late digests are dropped silently once a run is stopped/cancelled. Worktree-isolated children keep blocking digest semantics so the digest still runs before worktree cleanup.
+  - **Coding/SDK lifecycle controller** (`createWorkflowLifecycleController`): non-slash-command host control — `subscribeWorkflowProcess`, `getWorkflowProcessSnapshot`, `listWorkflowProcessSnapshots`, `preflightWorkflowCapsule`, `stop` / `pause` / `resume`, `readWorkflowResult` / `readWorkflowArtifact`, and terminal-run `delete` / `prune` with active-run protection and malformed-JSONL tolerance. SDK-loaded capsules now run the same preflight (version / skills / MCP / worktree / provider-model policy) as REPL-loaded ones.
+  - **Host policy** (`WorkflowHostPolicy`): `autoStart` (`off` / `confirm` / `on`) governs natural-language AMAW auto-start without weakening explicit `/workflow` semantics, and `maxAgents` / `maxConcurrency` / `tokenBudget` ceilings clamp runtime/approval/process caps (cannot raise above KodaX hard caps or bypass child permission gates).
+  - **Workflow identity & lifecycle**: a shared resolver handles `runId | saved workflow name | display alias` with fail-closed ambiguity handling (preserving v0.7.49 `rerun` semantics for both SDK and REPL). `/workflow rename <runId|name> <newName>` updates run display metadata or a saved capsule without changing run ids; `/workflow revise <runId|name> <change request>` generates a new capsule revision through the existing generator (approval-gated, append-only — never mutates the historical run graph); `/workflow revise --replace <savedName> <change request>` moves a saved capsule name after confirmation and archives the previous capsule under `.revisions/<savedName>/` with revision/replacement provenance.
+  - **SDK callback surface**: `KodaXEvents.onWorkflowProcessEvent` and `KodaXOptions.workflowHostPolicy`. Existing `KodaXEvents` child streams now carry `WorkflowEventCorrelation` (`workflowRunId` / `childAgentId` / `itemId`) from the coding layer — the agent workflow package still does not import `KodaXEvents`. `wf.log()` now emits durable `workflow_log` records folded into snapshot `latestMessage`, so hosts render progress without scraping terminal output. Resolved per-agent provider/model is propagated back through the process item for host correlation (still policy-gated).
+  - **REPL migration**: inline/fullscreen live surface and `/workflow runs|show|stop` are driven by `WorkflowProcessSnapshot` (legacy `WorkflowEvent` folding kept only as a fallback adapter); copy/selection paths stay plain-text (no ANSI in the transcript); argument completion exposes `rename` / `revise` (+ `--replace`) alongside the existing `rerun` / `save` run-id and saved-name candidates.
+  - **Live child-agent telemetry**: `KodaXEvents` callbacks now take an optional trailing metadata arg (`KodaXToolEventMeta` / `KodaXActivityEventMeta` / `KodaXWorkflowEventMeta`) carrying `toolId`, child agent identity, and workflow correlation, so a host can attribute every tool/thinking/text/progress event to its originating child agent and workflow run without a second event protocol. A child agent's activity (incl. an `onChildActivityEnd` boundary when it leaves the executor) streams into a bounded REPL `ChildActivitySurface` live panel instead of polluting the main transcript, and into JSONL output for headless hosts.
+  - **Generated-harness source validation**: generated/saved workflow scripts pass `validateRestrictedWorkflowSource` (JS compile check + source-policy scan over comment/string-stripped code) on generate/save/rename/replace/run, the generator gains a bounded multi-attempt repair loop with syntax + smoke-execution checks, and `wf.output(taskId)` is aliased to `wf.snapshot(taskId)` (`output` kept as a compatibility alias).
+
+  See [docs/features/v0.7.50.md FEATURE_229](docs/features/v0.7.50.md) + [test guide](docs/test-guides/FEATURE_229_v0.7.50_TEST_GUIDE.md). Architecture rationale in [docs/ADR.md ADR-040](docs/ADR.md).
+
+### Changed
+
+- **Provider model documentation refreshed (2026-06-14 snapshot).** README, LLM package docs, and SDK guidance now reflect the capability metadata for OpenAI `gpt-5.4` / `gpt-5.3-codex-spark`, Kimi `kimi-k2.7-code`, Zhipu `glm-5.2`, MiniMax `MiniMax-M3` / `MiniMax-M2.7-highspeed`, DeepSeek V4, and Ark Coding Plan routes for GLM, Kimi, MiniMax, DeepSeek, and Doubao Seed 2.0, while omitting retired MiniMax M2.5/M2.1/M2 ids from current public tables.
+- **Lazy provider client initialization.** Anthropic / OpenAI / custom providers now construct their underlying SDK client on first use (and rebuild it on a stale-connection signal) instead of eagerly at registry construction, so configuring many providers no longer allocates unused clients at startup.
+- **`web_search` defaults to Bing.** The built-in `web_search` tool now uses Bing (with a dedicated result parser that skips ad blocks and tracking redirects) as its default endpoint instead of DuckDuckGo, so search works in network environments where DuckDuckGo is unreachable.
+- **Language-continuity rule in the shared role closing contract.** Role prompts now instruct the agent to match the primary natural language of the original user request for user-visible progress, idle-yield resume summaries, and final answers (tool outputs, code identifiers, and quoted evidence may stay in their source language).
+
+### Fixed
+
+- **`task_output` no longer re-wakes idle-yield for terminal tasks.** When `task_output` reads an already-terminal child task, it now drains the matching `<task-completed>` queue entry so the idle-yield loop is not woken again by a stale completion notification.
+- **FEATURE_229 post-review closure.** `runWorkflowFromOptions` now forwards parent `guardrails` and the live plan-mode block predicate into workflow children, preserving the same SDK/REPL guardrails used by normal child dispatch. `/workflow` argument completion exposes `rename`, `revise`, `revise --replace`, and the relevant run-id / saved-workflow-name targets. Process status transitions are tightened: `activePhaseId` is cleared on phase/run completion, and a cancelled run marks in-flight children `cancelled` (vs `skipped` for never-started items). Capsule-preflight revision provenance resolves the version via `KODAX_VERSION` → `npm_package_version` → minimum-capsule fallback, so a native binary (no npm env) no longer mislabels or falsely rejects a capsule.
+- **Windows background process cleanup hardened.** Workflow / CLI subprocess teardown now waits for the full Windows descendant process tree to exit across the `taskkill` → `SIGTERM` → `SIGKILL` escalation (cycle-safe descendant collection, leaf-first kill order), and the two `process-tree` helpers (`@kodax-ai/agent` runtime + `@kodax-ai/llm` cli-events) are realigned so their `wmic` / PowerShell fallback logic no longer diverges. POSIX teardown is unchanged.
+
 ## [0.7.49] - 2026-06-13
 
 ### Added
@@ -48,7 +80,7 @@ All notable changes to this project will be documented in this file.
 ### Added
 
 - **FEATURE_132 — Native LSP integration: edit-time diagnostics reflux (TS/JS, Python, Go, Rust, Java).** After the `write` / `edit` / `multi_edit` tools change a file, KodaX now opens it through a language server and refluxes any type ERRORs straight back into the tool result, so the agent fixes them the same turn instead of waiting for the next build (saving ≥1 LLM round-trip). Servers are discovered on `PATH` / project `node_modules` (typescript-language-server, pyright, gopls, rust-analyzer, jdtls); when none is installed the feature is **silent** (no nagging), and a one-shot blacklist + spawn-dedup keep it cheap. It is **default-on but self-limiting**: only ERROR severity, ≤20 per file, a 5s per-file wait that runs OUTSIDE the file-mutation lock, and `KODAX_LSP=0` disables it entirely. Auto-installing a missing server is **opt-in** (`KODAX_LSP_DOWNLOAD=1`; `KODAX_LSP_NO_DOWNLOAD=1` hard-off) — KodaX never runs `go install` / `npm i` unprompted. The LSP TypeScript server runs as its own subprocess, isolated from the in-process repo-intelligence TS engine. It also adds four read-only navigation tools — `lsp_definition` / `lsp_hover` / `lsp_references` / `lsp_document_symbols` — for precise, position-anchored, real-time questions about the current code (complementing the repo-scope repo-intelligence symbol tools; the tool descriptions teach the boundary). Implemented under `packages/coding/src/lsp/`; new exports from `@kodax-ai/coding`: `LspService`, `getDefaultLspService`, `shutdownDefaultLspService`, `languageIdForPath`. See [docs/features/v0.7.47.md FEATURE_132](docs/features/v0.7.47.md).
-- **FEATURE_221 — Injectable self-manual for SDK consumers (`selfManual`).** Products built on the KodaX SDK (e.g. KodaX-Space) can now inject their **own** product manual so the built-in `kodax_manual` tool answers *their* users' "how do I use / configure …?" questions on-brand, instead of returning KodaX's internal manual. `runKodaX({ selfManual: { productName, topics } })` re-brands the ≤250-token routing rule + scope anchors to `productName` and **extend-merges** your `KodaXManualTopicInput[]` over KodaX's base topics (same `id` overrides, new `id` appends), so users can still ask about the underlying provider / config / SDK topics. **Opt-in and backward-compatible** — omit `selfManual` and the system prompt is byte-identical to before. Topics stay **tool-on-demand and 4 KB-capped**: nothing large is injected into the prompt, only the short routing rule. New exports from `@kodax-ai/coding`: `KodaXManualTopicInput`, `KodaXSelfManualConfig`, `ResolveKodaXManualOptions`, `buildSelfKnowledgeRoutingRule`. See [SDK Embedder Guide §11](docs/SDK_EMBEDDER_GUIDE.md) + [docs/features/v0.7.47.md FEATURE_221](docs/features/v0.7.47.md).
+- **FEATURE_221 — Injectable self-manual for SDK consumers (`selfManual`).** Products built on the KodaX SDK (e.g. KodaX-Space) can now inject their **own** product manual so the built-in `kodax_manual` tool answers *their* users' "how do I use / configure …?" questions on-brand, instead of returning KodaX's internal manual. `runKodaX({ selfManual: { productName, topics } })` re-brands the ≤250-token routing rule + scope anchors to `productName` and **extend-merges** your `KodaXManualTopicInput[]` over KodaX's base topics (same `id` overrides, new `id` appends), so users can still ask about the underlying provider / config / SDK topics. **Opt-in and backward-compatible** — omit `selfManual` and the system prompt is byte-identical to before. Topics stay **tool-on-demand and 4 KB-capped**: nothing large is injected into the prompt, only the short routing rule. New exports from `@kodax-ai/coding`: `KodaXManualTopicInput`, `KodaXSelfManualConfig`, `ResolveKodaXManualOptions`, `buildSelfKnowledgeRoutingRule`. See [SDK Embedder Guide §13](docs/SDK_EMBEDDER_GUIDE.md#13-inject-your-products-manual--selfmanual-feature_221-v0747) + [docs/features/v0.7.47.md FEATURE_221](docs/features/v0.7.47.md).
 - **FEATURE_218 — KodaX self-knowledge manual + `kodax_manual` help tool.** KodaX now ships a version-bound, structured product manual (17 topics: overview / install / providers / custom-providers / config / permissions / commands / tools / agents / skills / mcp / repo-intelligence / sessions / doctor / sdk / troubleshooting) behind a read-only `kodax_manual` tool, plus a ≤250-token routing rule that tells the model to look up KodaX usage/config questions instead of guessing or mixing in Claude Code / Codex CLI knowledge. The provider list is sourced from the single-source-of-truth capability snapshots (drift-proof, not hand-copied) and each answer is anchored to KodaX scope. REPL `/help <topic>` reuses the same registry. Lookup is deterministic (exact id → alias, incl. Chinese → query token-overlap → index) and never fabricates; single-topic output ≤4 KB, index ≤2 KB. No RAG, no vector DB, no background index, no prompt bloat. See [docs/features/v0.7.47.md FEATURE_218](docs/features/v0.7.47.md).
 - **MCP client — protocol `2025-11-25` compatibility (P0+P1).** KodaX's self-built MCP client now speaks the `2025-11-25` revision. **P0 (protocol compliance):** answers a server `ping` with an empty result instead of `-32601`; emits `notifications/cancelled` when a request times out (the `initialize` request is exempt); and resumes a dropped Streamable-HTTP notification stream via SSE `id`/`retry` + `Last-Event-ID`, with a reconnect cap so an empty-EOF stream can't reconnect-loop forever. **P1 (version + data surface):** advertises protocol `2025-11-25` with negotiation validation + the `MCP-Protocol-Version` header; carries tool/resource/prompt `icons` into descriptors (filtering unsafe URI schemes); and surfaces `execution.taskSupport`, failing fast on task-required tools. Unwired `elicitation` dead code removed. (Reverse / server-side capabilities are planned as FEATURE_222 for v0.7.48.)
 
@@ -127,7 +159,7 @@ shared names — the new name is required for the coding-plan provider to start.
   - **P2 — explicit per-dispatch override.** `dispatch_child_task` gains optional `provider` / `model` params, so the agent can deliberately send a child to another model family — e.g. a second independent review of the same change by a different family, to catch blind spots a single family would share. Resolution priority in `child-executor`: `bundle.provider/model` > specialist's declared model (FEATURE_191) > parent default. Omitting both is byte-identical to the prior behavior. Tolerant parse (empty/whitespace → undefined) so a misuse never fails the dispatch.
   - **P3 — cross-provider fallback + `doctor --ping`.** When a child's primary provider is *exhausted or down* (the LLM layer's same-provider `withRateLimit` retries gave up, a 5xx, or a network error), KodaX re-runs the child once on the next provider in an operator-configured chain instead of failing the whole child. Configured via `/fallback ark-coding,kimi-code` (persists to `~/.kodax/config.json` + mirrors to `KODAX_FALLBACK_PROVIDERS`; `/fallback off` to clear, `/fallback status` to inspect). Empty chain = OFF. Scope is deliberately minimal (per user direction): only hard availability errors trigger fallback — a returned `success:false` is a task outcome (not retried elsewhere) and aborts are never faked over; the speculative tool-call-fidelity / context-overflow / quality-anomaly triggers are unbuilt (YAGNI). `kodax doctor --ping` completes the health check: it sends one minimal request per configured provider (10s timeout, concurrent) to prove the key actually works and the subscription is active — opt-in, small token cost, never on the default `doctor`. 16 tests (11 fallback core + 5 `/fallback` command).
   - **P1-auto — `model_hint` → tier routing.** The previously dormant `model_hint` field (`fast`/`balanced`/`deep`, FEATURE_120) now selects an operator-configured tier: `fast` → `KODAX_FAST_PROVIDER`/`KODAX_FAST_MODEL` (**read-only children only** — the gating eval validated cheap-model quality on read-only investigation but not write/codegen, so write children stay on the parent tier), `deep` → `KODAX_DEEP_PROVIDER`/`KODAX_DEEP_MODEL` (read or write). `balanced`/unset, or any unconfigured tier, falls back to the parent — **routing is OFF by default** and turns on only when you point a tier env var at a model (no separate toggle). Specialist and explicit-P2 overrides both win over the hint. Per KodaX minimalism the original 5-name capability-alias layer (`vision`/`long-context`/…) was descoped to this env-tier form — no consumer exists for the rest yet (YAGNI). Pure routing wiring; the Worker prompt is unchanged (an eval non-trigger per `CLAUDE.md`), so $0 / no panel. Gating eval (`tests/feature-102-model-tier-quality.eval.ts`, canonical 5-alias × 3 read-only investigation × 5 run) kept as permanent regression: cheap floor `ark/v4flash` = 15/15, ≥ strong-mean 92% → cheap PRESERVES read-only quality. New unit + integration tests (7 `model-hint-routing` + 5 child-executor P2/P1-auto priority); also de-flaked the pre-existing `merges findings` child-executor test (parallel children made `mergeChildResults` emit in completion order — now deterministic dispatch order). Design: [docs/features/v0.7.45.md](docs/features/v0.7.45.md#phase-1--model_hint--真实跨-provider-子派发mvp).
-- **FEATURE_216 — `verifyProviderCredential(name)` SDK API + per-provider strategy.** New top-level helper for SDK consumers (KodaX Space, third-party embedders) to validate a provider's API key against the actual upstream — never-throws, mostly zero-token. Closes the "test connection" UI gap: existing `isConfigured()` only checks env presence; `stream()`/`sideQuery()` are too heavy. Three primitives, one per provider, baked into `provider-capabilities.json` `verifyStrategy` field: **`count-tokens`** (Anthropic `messages.countTokens()`, 0 token) for `anthropic` + 4 anthropic-coding providers; **`models-list`** (`models.list()`, 0 token) for `openai`/`deepseek`/`kimi`/`qwen`; **`minimal-message`** (~6-7 token `chat.completions.create({max_tokens:1})`) for `zhipu`/`mimo`/`mimo-coding` (where `models.list()` is publicly-served or `count_tokens` returns 404). CLI-bridge providers (`gemini-cli`, `codex-cli`) return `unsupported` — their credentials live in the CLI binary's token store, outside SDK reach. Top-level `verifyProviderCredential(name, opts?)` short-circuits unknown name / unsupported strategy / missing env var BEFORE instantiating the provider class — avoids the constructor throw on missing key, and ALSO wraps the actual `verifyCredential()` call in try/catch so the never-throws contract survives runtime-registered providers whose 3rd-party overrides might throw instead of returning an envelope. Error categorization (`unauthorized` / `network` / `timeout` / `unsupported` / `unconfigured` / `server_error` / `rate_limited` / `unknown`) is stable for UI consumers to map to user-facing states — `rate_limited` (429) is distinct from `unauthorized` so a transiently throttled key isn't misread as invalid. The error `message` field redacts `sk-...` key fragments before truncation so upstream error bodies that echo the submitted key don't leak the fragment into UI logs. The `kimi-code`-specific 400→`unauthorized` mapping is gated by `providerName` to avoid false-positives on other count-tokens providers that might 400 on a legitimate bad request (bad model id / schema mismatch). Network error detection extended to `ETIMEDOUT` + `ENETUNREACH` + `EHOSTUNREACH` + `ENETDOWN` beyond the original `ENOTFOUND`/`ECONNREFUSED`/`ECONNRESET`/`EAI_AGAIN`/`EPIPE` set. Companion `listProviderModels(name)` returns the static curated list (always `source: 'static'` in v0.7.45 — upstream `/v1/models` is noisy + inconsistent across providers per the 2026-05-28 12-provider probe matrix). Custom providers auto-inherit by `protocol`; explicit `verifyStrategy` overrides allowed. 88 tests total (28 orchestrator + 14 resolver + 38 schema + 10 real-key integration gated on `KODAX_INTEGRATION_TEST=1`). Reference industry validator: opencode's `setup-recording-env.ts` makes the same per-provider decision across 20+ providers — per-provider strategy IS industry standard, no universal 0-token primitive exists. Design + probe data: [docs/features/v0.7.45.md#feature_216](docs/features/v0.7.45.md#feature_216-provider-credential-verification-api). SDK usage guide: [docs/SDK_EMBEDDER_GUIDE.md §10](docs/SDK_EMBEDDER_GUIDE.md#10-provider-credential-verification--verifyprovidercredential-feature_216-v0745).
+- **FEATURE_216 — `verifyProviderCredential(name)` SDK API + per-provider strategy.** New top-level helper for SDK consumers (KodaX Space, third-party embedders) to validate a provider's API key against the actual upstream — never-throws, mostly zero-token. Closes the "test connection" UI gap: existing `isConfigured()` only checks env presence; `stream()`/`sideQuery()` are too heavy. Three primitives, one per provider, baked into `provider-capabilities.json` `verifyStrategy` field: **`count-tokens`** (Anthropic `messages.countTokens()`, 0 token) for `anthropic` + 4 anthropic-coding providers; **`models-list`** (`models.list()`, 0 token) for `openai`/`deepseek`/`kimi`/`qwen`; **`minimal-message`** (~6-7 token `chat.completions.create({max_tokens:1})`) for `zhipu`/`mimo`/`mimo-coding` (where `models.list()` is publicly-served or `count_tokens` returns 404). CLI-bridge providers (`gemini-cli`, `codex-cli`) return `unsupported` — their credentials live in the CLI binary's token store, outside SDK reach. Top-level `verifyProviderCredential(name, opts?)` short-circuits unknown name / unsupported strategy / missing env var BEFORE instantiating the provider class — avoids the constructor throw on missing key, and ALSO wraps the actual `verifyCredential()` call in try/catch so the never-throws contract survives runtime-registered providers whose 3rd-party overrides might throw instead of returning an envelope. Error categorization (`unauthorized` / `network` / `timeout` / `unsupported` / `unconfigured` / `server_error` / `rate_limited` / `unknown`) is stable for UI consumers to map to user-facing states — `rate_limited` (429) is distinct from `unauthorized` so a transiently throttled key isn't misread as invalid. The error `message` field redacts `sk-...` key fragments before truncation so upstream error bodies that echo the submitted key don't leak the fragment into UI logs. The `kimi-code`-specific 400→`unauthorized` mapping is gated by `providerName` to avoid false-positives on other count-tokens providers that might 400 on a legitimate bad request (bad model id / schema mismatch). Network error detection extended to `ETIMEDOUT` + `ENETUNREACH` + `EHOSTUNREACH` + `ENETDOWN` beyond the original `ENOTFOUND`/`ECONNREFUSED`/`ECONNRESET`/`EAI_AGAIN`/`EPIPE` set. Companion `listProviderModels(name)` returns the static curated list (always `source: 'static'` in v0.7.45 — upstream `/v1/models` is noisy + inconsistent across providers per the 2026-05-28 12-provider probe matrix). Custom providers auto-inherit by `protocol`; explicit `verifyStrategy` overrides allowed. 88 tests total (28 orchestrator + 14 resolver + 38 schema + 10 real-key integration gated on `KODAX_INTEGRATION_TEST=1`). Reference industry validator: opencode's `setup-recording-env.ts` makes the same per-provider decision across 20+ providers — per-provider strategy IS industry standard, no universal 0-token primitive exists. Design + probe data: [docs/features/v0.7.45.md#feature_216](docs/features/v0.7.45.md#feature_216-provider-credential-verification-api). SDK usage guide: [docs/SDK_EMBEDDER_GUIDE.md §12](docs/SDK_EMBEDDER_GUIDE.md#12-provider-credential-verification--verifyprovidercredential-feature_216-v0745).
 
 ### Performance
 
@@ -802,7 +834,7 @@ Two features close out v0.7.32 and the Plan B roadmap. **FEATURE_090** is the ro
 ### Documentation
 
 - **EVAL_GUIDELINES rewrite** — `benchmark/EVAL_GUIDELINES.md` now documents the **single-turn probe methodology** as the official KodaX eval pattern and removes end-to-end loop comparisons from the recommended set. Loops conflate prompt quality with tool-availability artefacts (model tries to verify with `read`/`grep`/`bash`, harness can't provide tools, benchmark scores the format-fail). Single-turn probes test the prompt-only contract.
-- **FEATURE_108 design** (`docs/features/v0.7.47.md`) — Session-Driven Reflective Prompt Patcher spec landed for v0.7.47 design preview.（注：版本重排后 FEATURE_108 先于 2026-06-05 迁至 v0.7.54，再于 2026-06-11 顺延至 [`docs/features/v0.7.57.md`](docs/features/v0.7.57.md)；`v0.7.47.md` 现为 FEATURE_218 + FEATURE_132）
+- **FEATURE_108 design** (`docs/features/v0.7.47.md`) — Session-Driven Reflective Prompt Patcher spec landed for v0.7.47 design preview.（注：版本重排后 FEATURE_108 先于 2026-06-05 迁至 v0.7.54，再于 2026-06-11 顺延至 [`docs/features/v0.7.67.md`](docs/features/v0.7.67.md)；`v0.7.47.md` 现为 FEATURE_218 + FEATURE_132）
 - **FEATURE_109 design** (`docs/features/v0.7.48.md`) — Harness Observability Substrate (long-term memory + prediction contract + cross-family prose guard) spec landed for v0.7.48 design preview.
 - **`docs/features/v0.7.29.md` 1496-line expansion** — folds back the historical capability-inventory artifact (`v0.7.29-capability-inventory.md` deleted) and adds deeper FEATURE_103/104/107-related context to the v0.7.29 retrospective.
 - **`docs/CODING_AGENT_PROMPTS.md`** — cross-project prompt-system reference (4 open-source coding agents) for KodaX prompt design comparison. Research artefact, not a project doc.

package/README.md

@@ -400,12 +400,15 @@ KodaX has two layers that consumers should understand separately:
 
 **Dynamic Workflows (FEATURE_217, v0.7.49)**: the domain-neutral workflow runtime is part of `/agent` — `import { createWorkflowRuntime, runWorkflow, WorkflowAbortError, WorkflowLimitError } from '@kodax-ai/kodax/agent'`. The coding-side integration (agent backend + built-in workflows + saved-workflow discovery/generation: `createCodingWorkflowBackend`, `runWorkflowFromOptions`, `parallelInvestigation`, `discoverSavedWorkflows`, `generateWorkflowFromOptions`, …) is part of `/coding`. FEATURE_217 is the v0.7.49 home for the full Dynamic Workflow product loop: `/workflow create <request>` generates restricted scripts, `/workflow save <runId> <name>` stores `.workflow.json` rerunnable workflows, generated/saved scripts coordinate agents through `WorkflowApi`, run lifecycle state stays observable, opt-in `isolation:"worktree"` routes selected children to parent-managed worktrees, and all file/shell effects still pass through agent tools and the existing permission gates. There is **no** separate `@kodax-ai/kodax/agent/workflow` root-package subpath; source-package consumers of `@kodax-ai/agent` can still use that package's `./workflow` subpath.
 
+**Workflow Process Surface (FEATURE_229, v0.7.50 implementation complete; release validation pending)**: workflow progress is now a reusable Agent-layer process contract rather than private REPL text. SDK hosts can subscribe to `WorkflowProcessEvent`/poll `WorkflowProcessSnapshot`, use `createWorkflowRunManager` and `createWorkflowLifecycleController` for stop/pause/resume/result/artifact/delete/prune/identity/preflight controls, and receive ANSI-free provenance fields (`source`, `sourceRunId`, `sourceWorkflowName`, `savedWorkflowName`, `revisionOf`) plus `resultSummary`. `/coding` owns the coding workflow backend and run graph, `/repl` renders the same snapshots, and the terminal UI is not the hidden source of truth. `KodaXEvents` callbacks also take an optional metadata arg (`KodaXToolEventMeta` / `KodaXActivityEventMeta` / `KodaXWorkflowEventMeta`) so a host can attribute every child-agent tool/thinking/progress event to its workflow run and child id without a second event protocol, and generated/saved workflow scripts pass `validateRestrictedWorkflowSource` (compile + source-policy check) plus a generator repair/smoke loop before they run. See [docs/ADR.md ADR-040](docs/ADR.md) for the layering rationale.
+
 ---
 
 ## Features
 
 - **Modular Architecture** - Use as CLI, as a library, or as a Node-free single binary
 - **14 Built-in Provider Aliases** - Anthropic, OpenAI, DeepSeek, Kimi, Kimi Code, Qwen, Zhipu, Zhipu 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`.
 - **Reasoning Modes** - Unified `off/auto/quick/balanced/deep` interface across providers
 - **Streaming Output** - Real-time response display
@@ -959,18 +962,18 @@ await runInkInteractiveMode({ provider: 'zhipu-coding', reasoningMode: 'auto' })
 
 | Provider | Environment Variable | Reasoning Support | Default Model |
 |----------|----------------------|-------------------|---------------|
-| anthropic | `ANTHROPIC_API_KEY` | Native | claude-sonnet-4-6 |
-| openai | `OPENAI_API_KEY` | Native | gpt-5.3-codex |
-| kimi | `KIMI_API_KEY` | Native | kimi-k2.6 |
+| anthropic | `ANTHROPIC_API_KEY` | Native | claude-sonnet-4-6 (`claude-opus-4-6` / `claude-haiku-4-5` via `/model`) |
+| openai | `OPENAI_API_KEY` | Native | gpt-5.3-codex (`gpt-5.4` / `gpt-5.3-codex-spark` via `/model`) |
+| kimi | `KIMI_API_KEY` | Native | kimi-k2.6 (`kimi-k2.7-code` 256K / `k2.5` via `/model`) |
 | kimi-code | `KIMI_CODE_API_KEY` | Native | kimi-for-coding |
 | qwen | `QWEN_API_KEY` | Native | qwen3.5-plus |
-| zhipu | `ZHIPU_API_KEY` | Native | glm-5 |
-| zhipu-coding | `ZHIPU_CODING_API_KEY` | Native | glm-5 |
-| minimax-coding | `MINIMAX_CODING_API_KEY` | Native | MiniMax-M2.7 (M2 family default; `MiniMax-M3` Frontier Coding with native multimodal + 1M ctx available via `/model`, plus M2.7-highspeed / M2.5 / M2.5-highspeed / M2.1 / M2.1-highspeed / M2 on the same gateway) |
+| 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`) |
+| 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`) |
 | 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.1 (Volcengine Ark Coding Plan, multi-model gateway, Anthropic-compat) |
-| deepseek | `DEEPSEEK_API_KEY` | Native | deepseek-v4-flash |
+| ark-coding | `ARK_CODING_API_KEY` | Native | glm-5.1 (Volcengine Ark Coding Plan: GLM, Kimi, MiniMax M3/M2.7, DeepSeek V3.2/V4, Doubao Seed 2.0 routes) |
+| deepseek | `DEEPSEEK_API_KEY` | Native | deepseek-v4-flash (`deepseek-v4-pro` via `/model`) |
 | gemini-cli | `GEMINI_API_KEY` | Prompt-only / CLI bridge | (via gemini CLI) |
 | codex-cli | `OPENAI_API_KEY` | Prompt-only / CLI bridge | (via codex CLI) |
 

package/README_CN.md

@@ -369,18 +369,18 @@ dist/binary/linux-x64/
 
 | Provider | 环境变量 | Reasoning | 默认 Model |
 |----------|----------|-----------|-----------|
-| anthropic | `ANTHROPIC_API_KEY` | Native | claude-sonnet-4-6 |
-| openai | `OPENAI_API_KEY` | Native | gpt-5.3-codex |
-| kimi | `KIMI_API_KEY` | Native | kimi-k2.6 |
+| anthropic | `ANTHROPIC_API_KEY` | Native | claude-sonnet-4-6（可 `/model` 切换 `claude-opus-4-6` / `claude-haiku-4-5`） |
+| openai | `OPENAI_API_KEY` | Native | gpt-5.3-codex（可 `/model` 切换 `gpt-5.4` / `gpt-5.3-codex-spark`） |
+| kimi | `KIMI_API_KEY` | Native | kimi-k2.6（可 `/model` 切换 `kimi-k2.7-code` 256K / `k2.5`） |
 | kimi-code | `KIMI_CODE_API_KEY` | Native | kimi-for-coding |
 | qwen | `QWEN_API_KEY` | Native | qwen3.5-plus |
-| zhipu | `ZHIPU_API_KEY` | Native | glm-5 |
-| zhipu-coding | `ZHIPU_CODING_API_KEY` | Native | glm-5（GLM Coding Plan 端点） |
-| minimax-coding | `MINIMAX_CODING_API_KEY` | Native | MiniMax-M2.7（M2 系列默认；`MiniMax-M3` 原生多模态 + 1M 上下文 Frontier Coding 模型可 `/model` 切换，同网关还有 M2.7-highspeed / M2.5 / M2.5-highspeed / M2.1 / M2.1-highspeed / M2）|
+| 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`） |
+| minimax-coding | `MINIMAX_CODING_API_KEY` | Native | MiniMax-M2.7（可 `/model` 切换 `MiniMax-M3` Frontier Coding，原生多模态 + 1M ctx；以及 `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.1（火山方舟 Coding Plan，多模型网关，Anthropic 协议） |
-| deepseek | `DEEPSEEK_API_KEY` | Native | deepseek-v4-flash |
+| ark-coding | `ARK_CODING_API_KEY` | Native | glm-5.1（火山方舟 Coding Plan：GLM、Kimi、MiniMax M3/M2.7、DeepSeek V3.2/V4、Doubao Seed 2.0 路由） |
+| deepseek | `DEEPSEEK_API_KEY` | Native | deepseek-v4-flash（可 `/model` 切换 `deepseek-v4-pro`） |
 | gemini-cli | `GEMINI_API_KEY` | Prompt-only / CLI bridge | （通过 gemini CLI） |
 | codex-cli | `OPENAI_API_KEY` | Prompt-only / CLI bridge | （通过 codex CLI） |
 
@@ -495,6 +495,8 @@ KodaX 有两层结构，SDK 用户需要分开理解：
 
 **经验法则**：需要 Runner / Agent / fan-out 时从 `/agent` 引入；只需要 skills 或 mcp API 时从 `/skills` 或 `/mcp` 引入，bundle 更小。窄子集是完整包的真子集 —— **不会**有额外符号。
 
+**Workflow process surface（FEATURE_229，v0.7.50 实现已完成，发布验证待跑）**：动态工作流不再只是 REPL 私有文本，而是 Agent 层可复用的 process/event/snapshot 契约。SDK 宿主可以订阅 `WorkflowProcessEvent`、轮询 `WorkflowProcessSnapshot`，并通过 `createWorkflowRunManager` / `createWorkflowLifecycleController` 做 stop/pause/resume、读取 final result/artifact、删除/清理 terminal runs、管理 workflow identity/preflight。`/coding` 负责 coding workflow backend 与 run graph，`/repl` 只是消费同一份 snapshot 渲染 UI；SDK 不需要解析 slash-command 输出或 Ink view-model。`KodaXEvents` 回调新增可选 meta 尾参（`KodaXToolEventMeta` / `KodaXActivityEventMeta` / `KodaXWorkflowEventMeta`），宿主据此把每个子 Agent 的 tool/thinking/progress 事件归因到对应 workflow run 与 child id，无需第二套事件协议；生成/保存的工作流脚本在运行前过 `validateRestrictedWorkflowSource`（编译 + 源策略检查）与 generator 的 repair/smoke 循环。分层取舍见 [docs/ADR.md ADR-040](docs/ADR.md)。
+
 ```
 KodaX/                       # 4 workspace packages(FEATURE_194 v0.7.43)
 ├── packages/

package/dist/chunks/argument-completer-3WX5B42G.js

@@ -0,0 +1,2 @@
+// @kodax-ai/kodax — bundled distribution. See docs/ADR.md ADR-022 + ADR-024.
+import{ia as a,ja as b}from"./chunk-UB5IAZHF.js";import"./chunk-HR64F32V.js";import"./chunk-SK4HOYT2.js";import"./chunk-MFOMFMSK.js";import"./chunk-XZY4CIDV.js";import"./chunk-5UJQ2GKJ.js";import"./chunk-V4WSBIXB.js";export{a as ArgumentCompleter,b as createArgumentCompleter};