@kodax-ai/kodax 0.7.57 → 0.7.58

package/README.md

@@ -154,7 +154,7 @@ For CLI defaults, create `~/.kodax/config.json`:
 ```json
 {
   "provider": "zhipu-coding",
-  "reasoningMode": "auto"
+  "effort": "auto"
 }
 ```
 
@@ -170,13 +170,18 @@ If you need a custom base URL or an OpenAI/Anthropic-compatible endpoint, define
       "baseUrl": "https://example.com/v1",
       "apiKeyEnv": "MY_LLM_API_KEY",
       "model": "my-model",
-      "userAgentMode": "compat"
+      "userAgentMode": "compat",
+      "reasoning": {
+        "efforts": ["off", "low", "medium", "high", "max"],
+        "default": "high"
+      }
     }
   ]
 }
 ```
 
 `userAgentMode` defaults to `"compat"`, which sends `KodaX` instead of the official SDK User-Agent. Switch it to `"sdk"` only when your gateway expects the upstream SDK header.
+For custom reasoning models, `reasoning: { efforts, default }` is the preferred v0.7.57 shape; use `"reasoning": "none"` for models without thinking capability. SDK hosts should render effort pickers from `reasoningProfile.supportedEfforts` / `defaultEffort` rather than assuming a fixed five-option ladder.
 
 #### OpenAI-compatible reasoning providers
 
@@ -280,7 +285,7 @@ registerCustomProviders([
 const result = await runKodaX(
   {
     provider: 'my-openai-compatible',
-    reasoningMode: 'auto',
+    effort: 'auto',
   },
   'Explain this codebase'
 );
@@ -304,12 +309,12 @@ kodax --repo-intelligence full --repo-intelligence-trace
 
 ## Architecture
 
-KodaX uses a **monorepo architecture** with npm workspaces. Source layout currently has 4 workspace packages; published as a single bundled npm package `@kodax-ai/kodax` with 7 SDK subpath exports (`/agent`, `/llm`, `/coding`, `/repl`, `/skills`, `/mcp`, `/session`; ADR-024 + ADR-032 + ADR-038, with ADR-036 consolidation):
+KodaX uses a **monorepo architecture** with npm workspaces. Source layout currently has 4 workspace packages; published as a single bundled npm package `@kodax-ai/kodax` with 8 SDK subpath exports (`/agent`, `/llm`, `/coding`, `/media`, `/repl`, `/skills`, `/mcp`, `/session`; ADR-024 + ADR-032 + ADR-038, with ADR-036 consolidation):
 
 ```
 KodaX/
 ├── packages/                # 4 workspace packages (FEATURE_194 v0.7.43)
-│   ├── llm/                 # @kodax-ai/llm - LLM abstraction (14 built-in provider aliases)
+│   ├── llm/                 # @kodax-ai/llm - LLM abstraction (15 built-in provider aliases)
 │   │   └── providers/       # Anthropic, OpenAI, DeepSeek, Kimi, MiMo, MiniMax, Zhipu, Ark, …
 │   │
 │   ├── agent/               # @kodax-ai/agent - Generic Agent framework
@@ -330,7 +335,7 @@ KodaX/
 │
 ├── src/                     # CLI entry + SDK subpath entries
 │   ├── kodax_cli.ts         # Main CLI entry point (bin: `kodax`)
-│   └── sdk-*.ts             # SDK subpath re-exports → @kodax-ai/kodax/{agent,llm,coding,repl,skills,mcp,session}
+│   └── sdk-*.ts             # SDK subpath re-exports → @kodax-ai/kodax/{agent,llm,coding,media,repl,skills,mcp,session}
 │
 └── package.json             # Root workspace config; release.mjs rewrites name + injects subpath exports
 ```
@@ -357,7 +362,7 @@ KodaX/
        ┌──────────────┐ ┌──────────────────────────┐ ┌──────────────┐
        │@kodax-ai/    │ │@kodax-ai/agent           │ │@kodax-ai/llm │
        │coding (via   │ │Runner + fan-out +        │ │LLM Abstract  │
-       │above)        │ │idle-yield + session-     │ │(14 aliases)  │
+       │above)        │ │idle-yield + session-     │ │(15 aliases)  │
        │              │ │lineage + skills + mcp +  │ │              │
        │              │ │tracing (FEATURE_194)     │ │              │
        └──────────────┘ └──────────────────────────┘ └──────────────┘
@@ -369,8 +374,8 @@ Source-side workspace package names (`@kodax-ai/*`). npm consumers install the s
 
 | Workspace package | Purpose | Key Dependencies |
 |---------|---------|------------------|
-| `@kodax-ai/llm` | LLM abstraction (14 built-in provider aliases + custom registration) | @anthropic-ai/sdk, openai |
-| `@kodax-ai/agent` | Generic Agent framework — Runner, fan-out, idle-yield, session-lineage, capabilities (mcp + skills), tracing (ADR-036 v0.7.43 consolidation; subpaths: `/session-lineage`, `/capabilities/mcp`, `/capabilities/skills`, `/tracing`) | @kodax-ai/llm, js-tiktoken, fflate, yaml |
+| `@kodax-ai/llm` | LLM abstraction (15 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/repl` | Complete interactive terminal UI (Ink/React, permission modes, commands, streaming) | @kodax-ai/coding, ink, react |
 
@@ -379,13 +384,13 @@ Source-side workspace package names (`@kodax-ai/*`). npm consumers install the s
 KodaX has two layers that consumers should understand separately:
 
 - **Source-side**: 4 workspace packages above (what developers see when reading the repo).
-- **npm-published**: a single bundled package `@kodax-ai/kodax` with 7 SDK subpaths (what SDK consumers `import` from). The subpaths are split into two roles:
+- **npm-published**: a single bundled package `@kodax-ai/kodax` with 8 SDK subpaths (what SDK consumers `import` from). The subpaths are split into two roles:
   - **Full-package subpaths** (`/agent`, `/llm`, `/coding`, `/repl`) — each one maps 1:1 to a source workspace and exposes its complete public API.
-  - **Narrow-subset subpaths** (`/skills`, `/mcp`, `/session`) — each one exposes only a focused capability slice carved out of `/agent` or `/repl`. This lets consumers who only need (say) the Skills system import a much smaller surface without pulling in the full agent framework.
+  - **Narrow-subset subpaths** (`/media`, `/skills`, `/mcp`, `/session`) — each one exposes only a focused capability slice carved out of `/agent` or `/repl`. This lets consumers who only need (say) the Skills system import a much smaller surface without pulling in the full agent framework.
 
 | Source package | npm subpath | Type | What you get | Example consumer |
 |---|---|---|---|---|
-| `packages/llm`    | `@kodax-ai/kodax/llm`     | Full package | 14-alias LLM abstraction (77 exports) | Standalone LLM clients |
+| `packages/llm`    | `@kodax-ai/kodax/llm`     | Full package | 15-alias LLM abstraction (77 exports) | Standalone LLM clients |
 | `packages/agent`  | `@kodax-ai/kodax/agent`   | Full package | Runner / fan-out / session-lineage / capabilities / tracing (202 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` / ... (11 exports = pre-v0.7.43 `@kodax-ai/mcp` complete API) | MCP server hosts |
@@ -406,7 +411,7 @@ KodaX has two layers that consumers should understand separately:
 ## 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
+- **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
 - **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 Effort** - Effort-first control (`off/auto/low/medium/high` plus model-supported extras) across providers
@@ -488,7 +493,7 @@ process.env.ZHIPU_API_KEY = process.env.ZHIPU_API_KEY ?? 'your_api_key';
 
 const result = await runKodaX({
   provider: 'zhipu-coding',
-  reasoningMode: 'auto',
+  effort: 'auto',
   events: {
     onTextDelta: (text) => process.stdout.write(text),
     onComplete: () => console.log('\nDone!'),
@@ -504,7 +509,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 (14 aliases)
+import { getProvider } from '@kodax-ai/kodax/llm';              // LLM abstraction (15 aliases)
 import { runKodaX } from '@kodax-ai/kodax/coding';              // coding tools + prompts
 import { SkillRegistry } from '@kodax-ai/kodax/skills';         // zero-dep skill loader
 import { loadConfig } from '@kodax-ai/kodax/repl';              // REPL config / session helpers
@@ -512,7 +517,7 @@ import { createMcpManager } from '@kodax-ai/kodax/mcp';         // MCP popout ma
 import { listSessions } from '@kodax-ai/kodax/session';         // session history helpers
 ```
 
-All 8 SDK entries (root + 7 subpaths) share internal code via ESM chunk splitting — importing from `/agent` does not pull in `/repl`'s Ink + React surface.
+All 9 SDK entries (root + 8 subpaths) share internal code via ESM chunk splitting — importing from `/agent` does not pull in `/repl`'s Ink + React surface.
 
 > **ESM-only.** The SDK is published as ES Modules. In a CommonJS context (Electron main process, legacy Webpack CJS bundles, `require()`-based code) you must use `await import(...)` instead of `require()`. See [docs/SDK_EMBEDDER_GUIDE.md §5](docs/SDK_EMBEDDER_GUIDE.md#5-consuming-from-a-commonjs-context-electron-main-cjs-bundles) for the canonical recipe + the technical reason most subpaths cannot ship a dual ESM/CJS build.
 
@@ -732,7 +737,7 @@ const events: KodaXEvents = {
 
 const result = await runKodaX({
   provider: 'zhipu-coding',
-  reasoningMode: 'auto',
+  effort: 'auto',
   events,
 }, 'What is 1+1?');
 
@@ -746,7 +751,7 @@ import { KodaXClient } from '@kodax-ai/kodax';
 
 const client = new KodaXClient({
   provider: 'zhipu-coding',
-  reasoningMode: 'auto',
+  effort: 'auto',
   events: {
     onTextDelta: (t) => process.stdout.write(t),
   },
@@ -799,7 +804,7 @@ await runKodaX({
 
 ## SDK Usage
 
-KodaX ships as a single npm package `@kodax-ai/kodax` with 7 SDK subpath exports (ADR-024 v0.7.39 + ADR-032 v0.7.42 + ADR-038 v0.7.49). Each subpath is tree-shake-friendly so consumers pull only what they need:
+KodaX ships as a single npm package `@kodax-ai/kodax` with 8 SDK subpath exports (ADR-024 v0.7.39 + ADR-032 v0.7.42 + ADR-038 v0.7.49 + v0.7.56 `/media`). Each subpath is tree-shake-friendly so consumers pull only what they need:
 
 ```bash
 npm install @kodax-ai/kodax
@@ -808,8 +813,9 @@ 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';                // 14-alias LLM abstraction
+import { getProvider } from '@kodax-ai/kodax/llm';                // 15-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
 import { SkillRegistry } from '@kodax-ai/kodax/skills';           // zero-dep skill loader
 import { createMcpManager } from '@kodax-ai/kodax/mcp';           // MCP popout manager (v0.7.42)
@@ -820,7 +826,7 @@ import { listSessions } from '@kodax-ai/kodax/session';           // session his
 
 ### `@kodax-ai/kodax/llm` — LLM Abstraction
 
-14 built-in provider aliases (Anthropic, OpenAI, DeepSeek, Kimi, Kimi-Code, Qwen, Zhipu, Zhipu-Coding, MiniMax-Coding, MiMo, MiMo-Coding, Ark-Coding, Gemini-CLI, Codex-CLI) + custom provider registration.
+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.
 
 ```typescript
 import { getProvider, KodaXBaseProvider } from '@kodax-ai/kodax/llm';
@@ -906,14 +912,14 @@ import { runKodaX, KodaXClient, KODAX_TOOLS } from '@kodax-ai/kodax/coding';
 // Single-task helper
 const result = await runKodaX({
   provider: 'zhipu-coding',
-  reasoningMode: 'auto',
+  effort: 'auto',
   events: { onTextDelta: (text) => process.stdout.write(text) },
 }, 'Read package.json and explain the dependencies');
 
 // Continuous session
 const client = new KodaXClient({
   provider: 'anthropic',
-  reasoningMode: 'auto',
+  effort: 'auto',
   events: { /* … */ },
 });
 await client.send('Create a new file');
@@ -935,7 +941,7 @@ import { runInkInteractiveMode } from '@kodax-ai/kodax/repl';
 // - Command system (/help, /mode, /clear, /status, …)
 // - Skills integration
 // - Theme support
-await runInkInteractiveMode({ provider: 'zhipu-coding', reasoningMode: 'auto' });
+await runInkInteractiveMode({ provider: 'zhipu-coding', effort: 'auto' });
 ```
 
 **Key Features**: Ink-based React components · 3 permission modes (auto / plan / accept-edits) · built-in commands · real-time streaming display · context-usage indicator.
@@ -958,7 +964,7 @@ await runInkInteractiveMode({ provider: 'zhipu-coding', reasoningMode: 'auto' })
 
 | Use Case | Subpath | Why |
 |----------|---------|-----|
-| Only need LLM abstraction | `@kodax-ai/kodax/llm` | Minimal deps; 14 built-in aliases |
+| Only need LLM abstraction | `@kodax-ai/kodax/llm` | Minimal deps; 15 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 |

package/README_CN.md

@@ -160,7 +160,7 @@ $env:ZHIPU_API_KEY="your_api_key"
 ```json
 {
   "provider": "zhipu-coding",
-  "reasoningMode": "auto"
+  "effort": "auto"
 }
 ```
 
@@ -194,7 +194,7 @@ import { runKodaX } from '@kodax-ai/kodax';
 const result = await runKodaX(
   {
     provider: 'zhipu-coding',
-    reasoningMode: 'auto',
+    effort: 'auto',
   },
   'Explain this codebase'
 );
@@ -206,15 +206,16 @@ const result = await runKodaX(
 
 ```typescript
 import { Runner } from '@kodax-ai/kodax/agent';                // Agent runtime
-import { getProvider } from '@kodax-ai/kodax/llm';              // LLM 抽象（14 个内置 alias）
+import { getProvider } from '@kodax-ai/kodax/llm';              // LLM 抽象（15 个内置 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
 import { loadConfig } from '@kodax-ai/kodax/repl';              // REPL 配置 / session 工具
 import { createMcpManager } from '@kodax-ai/kodax/mcp';         // MCP popout manager（v0.7.42 起）
 import { listSessions } from '@kodax-ai/kodax/session';         // session 历史工具
 ```
 
-8 个 SDK 入口（root + 7 subpath）通过 ESM 共享 chunk 复用底层代码 —— 只 import `/agent` 不会把 `/repl` 的 Ink + React 一起拉进来。
+9 个 SDK 入口（root + 8 subpath）通过 ESM 共享 chunk 复用底层代码 —— 只 import `/agent` 不会把 `/repl` 的 Ink + React 一起拉进来。
 
 > **SDK 是 ESM-only**。在 CommonJS 上下文（Electron main 进程、传统 Webpack CJS bundle、`require()` 调用方）必须用 `await import('@kodax-ai/kodax/...')` 代替 `require()`。详见 [docs/SDK_EMBEDDER_GUIDE.md §5](docs/SDK_EMBEDDER_GUIDE.md#5-consuming-from-a-commonjs-context-electron-main-cjs-bundles)，含 Electron main 完整 recipe + 为什么大多数 subpath 物理上无法做 dual ESM/CJS bundle。
 
@@ -232,7 +233,11 @@ import { listSessions } from '@kodax-ai/kodax/session';         // session 历
       "baseUrl": "https://example.com/v1",
       "apiKeyEnv": "MY_LLM_API_KEY",
       "model": "my-model",
-      "userAgentMode": "compat"
+      "userAgentMode": "compat",
+      "reasoning": {
+        "efforts": ["off", "low", "medium", "high", "max"],
+        "default": "high"
+      }
     }
   ]
 }
@@ -240,6 +245,8 @@ import { listSessions } from '@kodax-ai/kodax/session';         // session 历
 
 `userAgentMode` 默认 `"compat"`（发送 `KodaX` 而非上游 SDK 的 User-Agent）；如果你的网关要求原生 SDK header，再切到 `"sdk"`。
 
+自定义 reasoning 模型优先使用 v0.7.57 的 `reasoning: { efforts, default }`；无 thinking 能力的模型使用 `"reasoning": "none"`。SDK 宿主的 effort 选择器应从 `reasoningProfile.supportedEfforts` / `defaultEffort` 动态生成，不要假定固定五档。
+
 #### OpenAI 兼容推理模型
 
 部分 OpenAI-compatible 推理模型要求多轮请求时回放上一轮 assistant 的 `reasoning_content`。DeepSeek V4 thinking mode 是已知必须开启的场景；内置 DeepSeek provider 已经默认开启，但自定义 provider 需要显式配置：
@@ -465,29 +472,29 @@ kodax --repo-intelligence full --repo-intelligence-trace
 
 ## 仓库结构
 
-KodaX 是基于 npm workspaces 的 TypeScript monorepo，**源码层 4 个 workspace 包**（FEATURE_194 v0.7.43 包合并 — 9 → 4，ADR-036），npm 上以单 bundle 包 `@kodax-ai/kodax` 发布 + 7 个 SDK subpath exports（`/agent`、`/llm`、`/coding`、`/repl`、`/skills`、`/mcp`、`/session`；ADR-024 + ADR-032 + ADR-038）。核心包：
+KodaX 是基于 npm workspaces 的 TypeScript monorepo，**源码层 4 个 workspace 包**（FEATURE_194 v0.7.43 包合并 — 9 → 4，ADR-036），npm 上以单 bundle 包 `@kodax-ai/kodax` 发布 + 8 个 SDK subpath exports（`/agent`、`/llm`、`/coding`、`/media`、`/repl`、`/skills`、`/mcp`、`/session`；ADR-024 + ADR-032 + ADR-038）。核心包：
 
 | Workspace 包 | 作用 | 主要依赖 |
 |----|------|---------|
-| `@kodax-ai/llm` | LLM 抽象层（14 个内置 provider alias + 自定义 provider 注册），可独立使用 | `@anthropic-ai/sdk`, `openai` |
-| `@kodax-ai/agent` | 通用 Agent 框架 —— Runner / runFanOut / runWithIdleYield / ChildTaskRegistry + 会话管理 + tokenization + 可插拔 compaction + **inline 后**:session-lineage 子树 + capabilities (mcp + skills + builtin) + tracing（subpaths: `/session-lineage`、`/capabilities/mcp`、`/capabilities/skills`、`/tracing`） | `@kodax-ai/llm`, `js-tiktoken`, `fflate`, `yaml` |
+| `@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/repl` | 完整交互式终端 UI（Ink / React、权限模式、命令系统、流式渲染） | `@kodax-ai/coding`, `ink`, `react` |
 
-根目录 `src/kodax_cli.ts` 是 CLI 入口；`src/sdk-{agent,llm,coding,repl,skills,mcp,session}.ts` 是 SDK subpath 入口；构建产物在 `dist/`，单文件二进制在 `dist/binary/<target>/`。
+根目录 `src/kodax_cli.ts` 是 CLI 入口；`src/sdk-{agent,llm,coding,media,repl,skills,mcp,session}.ts` 是 SDK subpath 入口；构建产物在 `dist/`，单文件二进制在 `dist/binary/<target>/`。
 
 ### 源码层 vs npm 发布层
 
 KodaX 有两层结构，SDK 用户需要分开理解：
 
 - **源码层**：上面 4 个 workspace 包（开发者读代码时看到的物理结构）。
-- **npm 发布层**：单个 bundled 包 `@kodax-ai/kodax`，对外暴露 7 个 SDK subpath（SDK 消费者 `import` 时看到的接口）。subpath 分两种角色：
+- **npm 发布层**：单个 bundled 包 `@kodax-ai/kodax`，对外暴露 8 个 SDK subpath（SDK 消费者 `import` 时看到的接口）。subpath 分两种角色：
   - **完整包 subpath**（`/agent`、`/llm`、`/coding`、`/repl`）—— 每个 1:1 对应一个源码包，暴露完整公开 API。
-  - **窄子集 subpath**（`/skills`、`/mcp`、`/session`）—— 从 `/agent` 或 `/repl` 切出聚焦的能力子集，让"只用 Skills/MCP/会话管理"的消费者引入更小的依赖。
+  - **窄子集 subpath**（`/media`、`/skills`、`/mcp`、`/session`）—— 从 `/agent` 或 `/repl` 切出聚焦的能力子集，让"只用 Skills/MCP/会话管理"的消费者引入更小的依赖。
 
 | 源码包 | npm subpath | 类型 | 内容 | 典型消费者 |
 |---|---|---|---|---|
-| `packages/llm`    | `@kodax-ai/kodax/llm`     | 完整包 | 14-alias LLM 抽象 (77 exports) | 独立 LLM 客户端 |
+| `packages/llm`    | `@kodax-ai/kodax/llm`     | 完整包 | 15-alias LLM 抽象 (77 exports) | 独立 LLM 客户端 |
 | `packages/agent`  | `@kodax-ai/kodax/agent`   | 完整包 | Runner / fan-out / session-lineage / capabilities / tracing (202 exports) | 自定义 agent 框架 |
 | `packages/agent`  | `@kodax-ai/kodax/skills`  | **窄子集** | 仅 Skills 系统 —— `SkillRegistry` / `loadFullSkill` / `expandSkillForLLM` 等 (26 exports = v0.7.43 之前 `@kodax-ai/skills` 完整 API) | Skill 加载器、IDE 插件 |
 | `packages/agent`  | `@kodax-ai/kodax/mcp`     | **窄子集** | 仅 MCP —— `McpCapabilityProvider` / `createMcpTransport` / `searchMcpCatalog` 等 (11 exports = v0.7.43 之前 `@kodax-ai/mcp` 完整 API) | MCP server 宿主 |
@@ -504,7 +511,7 @@ KodaX 有两层结构，SDK 用户需要分开理解：
 ```
 KodaX/                       # 4 workspace packages(FEATURE_194 v0.7.43)
 ├── packages/
-│   ├── llm/                 # @kodax-ai/llm —— 14 个内置 provider alias
+│   ├── llm/                 # @kodax-ai/llm —— 15 个内置 provider alias
 │   ├── agent/               # @kodax-ai/agent —— Runner / fan-out / idle-yield + 子树:
 │   │   ├── session-lineage/ # 分支 session tree (v0.7.43 inline)
 │   │   ├── capabilities/
@@ -516,9 +523,9 @@ KodaX/                       # 4 workspace packages(FEATURE_194 v0.7.43)
 │   └── repl/                # @kodax-ai/repl —— Ink TUI
 ├── src/
 │   ├── kodax_cli.ts         # CLI 主入口（bin: `kodax`）
-│   └── sdk-*.ts             # SDK subpath 入口 → @kodax-ai/kodax/{agent,llm,coding,repl,skills,mcp,session}
+│   └── sdk-*.ts             # SDK subpath 入口 → @kodax-ai/kodax/{agent,llm,coding,media,repl,skills,mcp,session}
 ├── scripts/
-│   ├── build-bundle.mjs     # esbuild 单 bundle 多 entry 打包（CLI + root + 7 SDK subpath + chunks）
+│   ├── build-bundle.mjs     # esbuild 单 bundle 多 entry 打包（CLI + root + 8 SDK subpath + chunks）
 │   ├── build-binary.mjs     # Bun --compile 单文件二进制打包
 │   └── release.mjs          # ADR-024 release-time pkg name/exports 注入
 └── .github/workflows/

package/dist/chunks/agent-YJNC2755.js

@@ -0,0 +1,2 @@
+// @kodax-ai/kodax — bundled distribution. See docs/ADR.md ADR-022 + ADR-024.
+import{I as c,J as d,K as e,L as f,Z as g,_ as h,ia as i,oa as j}from"./chunk-CQ6EQG7E.js";import"./chunk-D6QVXQNI.js";import"./chunk-526OILYL.js";import"./chunk-7QB55SYG.js";import"./chunk-HS2K74I4.js";import{mb as a,nb as b}from"./chunk-ZZDC75H4.js";import"./chunk-P4VF3JEP.js";import"./chunk-V4WSBIXB.js";export{d as bucketProviderPayloadSize,g as buildAutoRepoIntelligenceContext,e as checkPromiseSignal,b as cleanupIncompleteToolCalls,h as describeTransientProviderRetry,f as emitResilienceDebug,c as estimateProviderPayloadBytes,j as runKodaX,i as saveSessionSnapshot,a as validateAndFixToolHistory};

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

@@ -0,0 +1,2 @@
+// @kodax-ai/kodax — bundled distribution. See docs/ADR.md ADR-022 + ADR-024.
+import{Aa as b,za as a}from"./chunk-QHWXPJEG.js";import"./chunk-6AU6EPO6.js";import"./chunk-XXEIFNBE.js";import"./chunk-NKHXRN7G.js";import"./chunk-73Z7BK5H.js";import"./chunk-PIQWODWN.js";import"./chunk-CQ6EQG7E.js";import"./chunk-D6QVXQNI.js";import"./chunk-526OILYL.js";import"./chunk-7QB55SYG.js";import"./chunk-HS2K74I4.js";import"./chunk-ZZDC75H4.js";import"./chunk-P4VF3JEP.js";import"./chunk-V4WSBIXB.js";export{a as ArgumentCompleter,b as createArgumentCompleter};

package/dist/chunks/chunk-526OILYL.js

@@ -0,0 +1,2 @@
+// @kodax-ai/kodax — bundled distribution. See docs/ADR.md ADR-022 + ADR-024.
+import{l as o}from"./chunk-HS2K74I4.js";import{a as i}from"./chunk-V4WSBIXB.js";function r(u){let e=o(u?.llm);if(!e)return;let t={};return e.requestTimeoutMs!==void 0&&(t.requestTimeoutMs=e.requestTimeoutMs),e.streamIdleTimeoutMs!==void 0&&(t.streamIdleTimeoutMs=e.streamIdleTimeoutMs),e.chunkTimeoutMs!==void 0&&(t.chunkTimeoutMs=e.chunkTimeoutMs),e.maxRetryDelayMs!==void 0&&(t.maxRetryDelayMs=e.maxRetryDelayMs),Object.keys(t).length>0?t:void 0}i(r,"providerResilienceConfigFromTimeouts");export{r as a};

package/dist/chunks/{chunk-LZKGOR2C.js → chunk-6AU6EPO6.js}

@@ -1,2 +1,2 @@
 // @kodax-ai/kodax — bundled distribution. See docs/ADR.md ADR-022 + ADR-024.
-import{wa as e}from"./chunk-N2N2W3AQ.js";import{a as n}from"./chunk-V4WSBIXB.js";import{readFile as i}from"fs/promises";var c={enabled:!0,triggerPercent:75};async function g(o){let t=e("config.json");try{let r=await a(t);if(r?.compaction)return{...c,...r.compaction}}catch{}return c}n(g,"loadCompactionConfig");async function a(o){try{let t=await i(o,"utf-8");return JSON.parse(t)}catch{return null}}n(a,"readConfigFile");export{g as a};
+import{wa as e}from"./chunk-ZZDC75H4.js";import{a as n}from"./chunk-V4WSBIXB.js";import{readFile as i}from"fs/promises";var c={enabled:!0,triggerPercent:75};async function g(o){let t=e("config.json");try{let r=await a(t);if(r?.compaction)return{...c,...r.compaction}}catch{}return c}n(g,"loadCompactionConfig");async function a(o){try{let t=await i(o,"utf-8");return JSON.parse(t)}catch{return null}}n(a,"readConfigFile");export{g as a};

package/dist/chunks/chunk-73Z7BK5H.js

@@ -0,0 +1,15 @@
+// @kodax-ai/kodax — bundled distribution. See docs/ADR.md ADR-022 + ADR-024.
+import{t as W,z as $}from"./chunk-PIQWODWN.js";import{Da as _,Ea as I}from"./chunk-7QB55SYG.js";import{Ja as b,_a as v,j as k,k as x}from"./chunk-HS2K74I4.js";import{$d as A,Qc as S,Rc as E,Wc as T,ae as w,ce as R,de as O,ee as g}from"./chunk-ZZDC75H4.js";import{a as i}from"./chunk-V4WSBIXB.js";import{join as Re}from"node:path";var L=["You generate KodaX Dynamic Workflow scripts.","Return JSON only. Do not wrap the answer in prose.","For simple tasks that do not benefit from multiple agents, return:",'{"action":"decline","reason":"..."}',"For complex tasks, return:",'{"action":"generate","manifest":{...},"source":"async function run(wf, args) { ... }","approvalSummary":"..."}',"Generated source may only coordinate agents through wf and args.","Generated source must return displayable final text for the user.","Never use import, require, process, fs, child_process, network APIs, shell commands, or direct file access."].join(`
+`),M=12e4,B="KODAX_WORKFLOW_GENERATION_TIMEOUT_SEC",U="KODAX_WORKFLOW_GENERATION_TIMEOUT_MS",J=64,H=2,V=2e3,X=[{name:"default"},{name:"variant-results",finalText:i((e,t)=>`Variant smoke child report from ${e} (${t}).`,"finalText"),synthesizeText:"Variant smoke synthesis report."},{name:"unverified-success",status:i(()=>"completed_unverified","status"),finalText:i(e=>`Smoke result for ${e}: completed with verification warnings.`,"finalText"),synthesizeText:"Smoke synthesis: completed with verification warnings."},{name:"empty-args-rerun",args:i(()=>({}),"args")}],Q=["- classify-and-act: first classify a mixed request, then route to the right worker behavior.","- fan-out-and-synthesize: split independent areas, files, hypotheses, reviewers, or perspectives; run them with wf.parallel, then wf.synthesize.","- adversarial-verification: produce or inspect a candidate, then have an independent verifier attack assumptions, evidence, and edge cases.","- generate-and-filter: ask several generators for distinct candidates, then filter/dedupe/rank before synthesis.","- tournament: compare competing approaches or answers and use synthesis as the judge.","- loop-until-done: run bounded follow-up rounds when findings should drive the next prompt.","- review or audit combines fan-out-and-synthesize with adversarial-verification: fan independent reviewers out across the dimensions, then pipe each finding straight into a verifier that tries to refute it before synthesis. A review with no verification stage ships findings a single reviewer's blind spot would have hidden."],Y=[{id:"import",pattern:/\bimport\s*(?:\(|['"*{]|\w+\s+from\b)/},{id:"require",pattern:/\brequire\s*\(/},{id:"process",pattern:/\bprocess\s*(?:\.|\[)/},{id:"fs",pattern:/\b(?:node:)?fs\b/},{id:"child_process",pattern:/\bchild_process\b/},{id:"shell",pattern:/\b(?:exec|spawn|execFile)\s*\(/},{id:"fetch",pattern:/\bfetch\s*\(/},{id:"Deno",pattern:/\bDeno\s*(?:\.|\[)/},{id:"Bun",pattern:/\bBun\s*(?:\.|\[)/}];function Z(e=process.env,t){let n=k(t?.workflow?.generationTimeoutSec,"timeouts.workflow.generationTimeoutSec");if(n!==void 0)return n;let r=x(e[B]);if(r!==void 0)return r;let s=e[U];if(s===void 0||s.trim().length===0)return M;let o=Number(s);return!Number.isFinite(o)||o<=0?M:Math.floor(o)}i(Z,"resolveWorkflowGenerationTimeoutMs");function ee(e,t){if(typeof e!="object"||e===null)throw new Error(`${t} must be an object`);return e}i(ee,"readRecord");function q(e,t){let n=e[t];if(typeof n!="string"||n.trim().length===0)throw new Error(`workflow generation ${t} must be a non-empty string`);return n}i(q,"readNonEmptyString");function te(e){let t=e.trim(),n=/^```(?:json)?\s*([\s\S]*?)\s*```$/i.exec(t);if(n?.[1])return n[1].trim();let r=t.indexOf("{"),s=t.lastIndexOf("}");if(r>=0&&s>r)return t.slice(r,s+1);throw new Error("workflow generation output did not contain a JSON object")}i(te,"extractJsonText");function ne(e){let t=te(e);return ee(JSON.parse(t),"workflow generation output")}i(ne,"parseGenerationJson");function re(e){if(typeof e=="string"){let n=e.trim();return n.length>0?n:void 0}if(typeof e!="object"||e===null)return;let t=e;for(let n of["name","id","title","phase"]){let r=t[n];if(typeof r=="string"&&r.trim().length>0)return r.trim()}}i(re,"normalizePhaseEntry");function se(e){return e.split(/(?:->|\u2192|,|\n)/).map(t=>t.trim()).filter(t=>t.length>0)}i(se,"splitPhaseString");function oe(e){if(typeof e!="object"||e===null)return e;let t=e,n=t.phases,r;if(Array.isArray(n)){let s=n.map(re);s.every(o=>o!==void 0)&&(r=s)}else if(typeof n=="string"){let s=se(n);s.length>0&&(r=s)}return r?{...t,phases:r}:e}i(oe,"normalizeGeneratedManifestCandidate");function ie(e){return e.match(/\bwf\.(?:runAgent|spawnAgent|synthesize)\s*\(/g)?.length??0}i(ie,"estimateDirectAgentCalls");function ae(e,t){let n=e.maxConcurrency*Math.max(1,e.phases.length)+2,r=ie(t)+2,s=Math.min(J,Math.max(e.maxAgents,n,r));return s>e.maxAgents?{...e,maxAgents:s}:e}i(ae,"reserveGeneratedWorkflowAgentCapacity");function m(e){let t="",n=0;for(;n<e.length;){let r=e[n],s=e[n+1];if(r==="/"&&s==="/"){for(t+="  ",n+=2;n<e.length&&e[n]!==`
+`;)t+=" ",n+=1;continue}if(r==="/"&&s==="*"){for(t+="  ",n+=2;n<e.length;){if(e[n]==="*"&&e[n+1]==="/"){t+="  ",n+=2;break}t+=e[n]===`
+`?`
+`:" ",n+=1}continue}if(r==='"'||r==="'"||r==="`"){let o=r;for(t+=" ",n+=1;n<e.length;){let l=e[n];if(t+=l===`
+`?`
+`:" ",n+=1,l==="\\"){n<e.length&&(t+=e[n]===`
+`?`
+`:" ",n+=1);continue}if(l===o)break}continue}t+=r??"",n+=1}return t}i(m,"stripGeneratedSourceLiterals");function le(e,t){for(let n=t+1;n<e.length;n+=1){let r=e[n];if(r==="\\"){n+=1;continue}if(r==="`")return!1;if(r==="$"&&e[n+1]==="{")return!0}return!1}i(le,"templateLiteralHasExpression");function ce(e){let t=m(e),n=/\bwf\s*\.\s*(wait|snapshot|send|stop)\s*\(/g,r;for(;(r=n.exec(t))!==null;){let s=r[1];if(!s)continue;let o=t.indexOf("(",r.index);if(o<0)continue;let l=o+1;for(;/\s/.test(e[l]??"");)l+=1;let f=e[l];if(!(f==="`"&&le(e,l))&&(f==='"'||f==="'"||f==="`"))return{method:s}}}i(ce,"findLiteralWorkflowTaskTarget");function N(e){return e!==void 0&&/[A-Za-z0-9_$]/.test(e)}i(N,"isIdentifierPart");function j(e){let t=m(e),n=/\basync\s+function\s+run\s*\([^)]*\)\s*\{/.exec(t);if(!n)return;let r=t.indexOf("{",n.index);if(r<0)return;let s=0;for(let o=r;o<t.length;o+=1){let l=t[o];if(l==="{"&&(s+=1),l==="}"&&(s-=1,s===0))return{start:r+1,end:o}}}i(j,"findRunBodyRange");function D(e,t){let n=m(e),r=1;for(let s=t.start;s<t.end;s+=1){let o=n[s];if(o==="{"){r+=1;continue}if(o==="}"){r-=1;continue}if(r===1&&n.startsWith("return",s)&&!N(n[s-1])&&!N(n[s+6])){let l=s+6,f=0;for(let u=l;u<t.end;u+=1){let p=n[u];if((p==="("||p==="["||p==="{")&&(f+=1),(p===")"||p==="]"||p==="}")&&(f-=1),f===0&&(p===";"||p===`
+`||p==="\r"))return e.slice(l,u).trim()}return e.slice(l,t.end).trim()}}}i(D,"findTopLevelReturnExpression");function F(e){let t=j(e);if(t)return D(e,t)}i(F,"findOuterRunReturnExpression");function fe(e){let t=j(e);if(!t)return[];let n=m(e),r=[],s=t.start,o=1;for(let f=t.start;f<t.end;f+=1){let u=n[f];if(u==="{"||u==="("||u==="["){o+=1;continue}if(u==="}"||u===")"||u==="]"){o-=1;continue}if(u===";"&&o===1){let p=e.slice(s,f+1).trim();p&&r.push(p),s=f+1}}let l=e.slice(s,t.end).trim();return l&&r.push(l),r}i(fe,"findOuterRunStatements");function ue(e){return e.replace(/[.*+?^${}()|[\]\\]/g,"\\$&")}i(ue,"escapeRegExp");function de(e,t){let n=/^[A-Za-z_$][A-Za-z0-9_$]*$/.exec(t.trim())?.[0];if(!n)return!1;let r=ue(n),s=new RegExp(`^\\s*(?:const|let|var)\\s+${r}\\s*=\\s*(?:await\\s+)?wf\\s*\\.\\s*artifact\\b`),o=new RegExp(`^\\s*${r}\\s*=\\s*(?:await\\s+)?wf\\s*\\.\\s*artifact\\b`);return fe(e).some(l=>s.test(l)||o.test(l))}i(de,"isReturnedArtifactHandle");function C(e,t,n,r){let s=0;for(let o=t;o<e.length;o+=1){let l=e[o];if(l===n&&(s+=1),l===r&&(s-=1,s===0))return o}}i(C,"findMatchingDelimiter");function pe(e,t,n){let r=0;for(let s=t;s<n;s+=1){let o=e[s];if(o==="("||o==="["||o==="{"){r+=1;continue}if(o===")"||o==="]"||o==="}"){r-=1;continue}if(o===","&&r===0)return s}}i(pe,"findTopLevelComma");function he(e){let t=m(e),n=/^\s*(?:await\s+)?wf\s*\.\s*phase\s*\(/.exec(t);if(!n)return;let r=t.indexOf("(",n.index);if(r<0)return;let s=C(t,r,"(",")");if(s===void 0)return;let o=pe(t,r+1,s);if(o===void 0)return;let l=e.slice(o+1,s).trim(),f=m(l),u=f.indexOf("=>");if(u<0)return;let p=u+2,a=f.slice(p).search(/\S/);if(a<0)return;let c=p+a;if(f[c]!=="{")return l.slice(c).trim();let d=C(f,c,"{","}");if(d!==void 0)return D(l,{start:c+1,end:d})}i(he,"findPhaseCallbackReturnExpression");function P(e,t){return new RegExp(`^(?:await\\s+)?wf\\s*\\.\\s*${t}\\b`).test(e.trim())}i(P,"isDirectWorkflowCall");function G(e,t){let n=t.trim();if(/^(?:undefined|null|void\s+0|\{\s*\}|\[\s*\]|''|""|``)$/.test(n)||P(n,"artifact")||de(e,n))return!1;if(P(n,"phase")){let r=he(n);return r!==void 0&&G(n,r)}return!0}i(G,"isDisplayableReturnExpression");function me(e){let t=F(e);return t?G(e,t):!1}i(me,"hasDisplayableRunReturn");function we(e){try{R(e,{filename:"generated-workflow.js",requireAsyncRun:!0,checkSourcePolicy:!1})}catch(t){let n=t instanceof Error?t.message:String(t),s=/Unexpected (identifier|string|token|end of input)|Invalid or unexpected token/i.test(n)?" \u2014 a prompt string likely has an unescaped quote or apostrophe; wrap that string in double quotes or backticks, or escape the quote, then retry":"";throw new Error(`workflow generation source has invalid JavaScript syntax: ${n}${s}`)}}i(we,"assertGeneratedWorkflowSyntax");function ge(e){let t=0,n=new Map,r=[],s=i(a=>{t+=1;let c=`smoke-task-${t}-${Math.random().toString(36).slice(2,8)}`;return n.set(c,a),{taskId:c,name:a}},"nextHandle"),o=i((a,c)=>{if(n.has(c))return;throw[...n.entries()].find(h=>h[1]===c)?new Error(`wf.${a}("${c}") used an agent name, but workflow task APIs require the taskId returned by spawnAgent/runAgent. Store the handle/result and pass handle.taskId or result.taskId. wf.runAgent already returns the completed result; wf.parallel returns the array of results.`):new Error(`wf.${a}("${c}") references an unknown workflow task id`)},"assertKnownTaskId"),l=i(a=>{for(let c of a.evidenceRefs??[]){if(c.startsWith("file:")||c.startsWith("diff:")||c.startsWith("finding:"))continue;if(c.startsWith("task_id:")){let h=c.slice(8).trim();if(h.length===0)throw new Error(`wf.runAgent("${a.name}") evidenceRefs contains empty task_id: reference`);o("evidenceRefs",h);continue}throw[...n.entries()].find(h=>h[1]===c)?new Error(`wf.runAgent("${a.name}") evidenceRefs contains agent name "${c}". Use "task_id:" + result.taskId from the child result.`):new Error(`wf.runAgent("${a.name}") evidenceRefs contains unsupported ref "${c}". Use file:, diff:, finding:, or task_id:<id>.`)}},"assertEvidenceRefs"),f=i((a,c)=>{o("wait",a);let d=n.get(a)??c??a,h=e.status?.(d,a)??"completed";return{taskId:a,name:d,status:h,finalText:e.finalText?.(d,a)??`Smoke result for ${d}: completed, done, verified.`}},"resultFor"),u=i((a,c)=>{o(a,c);let d=n.get(c)??c;return{taskId:c,name:d,status:"completed",lastText:`Smoke snapshot for ${d}`}},"snapshotFor");return{api:{runId:"run-smoke",args:void 0,budget:{total:null,spent:i(()=>0,"spent"),remaining:i(()=>1/0,"remaining")},phase:i(async(a,c)=>c(),"phase"),spawnAgent:i(async a=>(l(a),s(a.name)),"spawnAgent"),runAgent:i(async a=>{l(a);let c=s(a.name),d=f(c.taskId,a.name);if(d.status==="failed"||d.status==="stopped")throw new Error(`workflow task ${d.name} (${d.taskId}) ${d.status}`);return d},"runAgent"),wait:i(async a=>f(a),"wait"),snapshot:i(async a=>u("snapshot",a),"snapshot"),output:i(async a=>u("output",a),"output"),send:i(async a=>{o("send",a)},"send"),stop:i(async a=>{o("stop",a)},"stop"),parallel:i(async a=>Promise.all(a.map(c=>c())),"parallel"),synthesize:i(async()=>({text:e.synthesizeText??"Smoke synthesis: completed, done, verified."}),"synthesize"),artifact:i(async a=>(r.push(a),{name:a}),"artifact"),log:i(()=>{},"log")},artifactCount:i(()=>r.length,"artifactCount")}}i(ge,"createSmokeWorkflowApi");function ke(e,t){if(t>0)return!0;if(typeof e=="string")return e.trim().length>0;if(e==null)return!1;if(typeof e!="object")return!0;if(Array.isArray(e))return e.length>0;let n=e,r=!1,s=n.synthesis;if(typeof s=="string"&&(r=!0,s.trim().length>0))return!0;if(s&&typeof s=="object"){r=!0;let o=s.text;if(typeof o=="string"&&o.trim().length>0)return!0}for(let o of["summary","report","text","result"]){let l=n[o];if(l!==void 0&&(r=!0),typeof l=="string"&&l.trim().length>0)return!0}return r&&Object.keys(n).every(o=>o==="synthesis"||o==="summary"||o==="report"||o==="text"||o==="result")?!1:Object.keys(n).length>0}i(ke,"isSmokeResultDisplayable");async function ye(e){for(let t of X)try{let n=ge(t),r=await O({source:e.source,wf:n.api,args:t.args?.(e.request)??{request:e.request},filename:"generated-workflow-smoke.js",timeoutMs:V});if(!ke(r,n.artifactCount()))throw new Error("run() returned no displayable result or artifact")}catch(n){let r=n instanceof Error?n.message:String(n);throw new Error(`workflow generation source failed safe smoke validation (${t.name}): ${r}`)}}i(ye,"assertGeneratedWorkflowSmoke");function y(e){if(e.trim().length===0)throw new Error("workflow generation source must be non-empty");if(!/\basync\s+function\s+run\s*\(/.test(e))throw new Error("workflow generation source must define async function run(wf, args)");we(e);let t=m(e);for(let r of Y)if(r.pattern.test(t))throw new Error(`forbidden generated workflow token: ${r.id}`);if(/\.\s*output\b/.test(t))throw/\bwf\s*\.\s*output\s*\(/.test(t)?new Error("workflow generation source must use wf.snapshot(taskId) instead of legacy wf.output(taskId)"):new Error("workflow generation source must use finalText/text instead of non-existent .output");let n=ce(e);if(n)throw new Error(`workflow generation source must pass taskId variables to wf.${n.method}(...) instead of string literals; use handle.taskId from wf.spawnAgent(...) or result.taskId from wf.runAgent(...).`);for(let r of t.split(/\r?\n/)){let s=r.search(/\bwf\.artifact\s*\(/);if(s>=0&&!/\b(?:await|return)\b/.test(r.slice(0,s)))throw new Error("workflow generation source must await wf.artifact(...)")}if(!me(e)){let r=F(e),s=r===void 0?"no top-level `return` was found in run() \u2014 a return inside a wf.phase(...) callback does not count":`the top-level return \`${r.slice(0,80)}\` is not displayable \u2014 do not return undefined/null/{}, a bare wf.artifact(...) write, or a wf.phase(...) without a displayable callback return`;throw new Error(`workflow generation source outer run function must return displayable final text (${s})`)}return e}i(y,"validateGeneratedWorkflowSource");function xe(e){let t=e?.trim();return t?["","Referenced skill instructions (authoritative):",t,"","Skill handling requirements:","- Treat the referenced skill instructions above as binding requirements for this workflow generation.","- Preserve skill-specific file layout, naming, and process requirements in child-agent prompts that do the work.",'- Do not replace concrete skill requirements with vague paths such as "or similar"; choose paths from the skill or instruct the child to invoke the skill before acting.']:[]}i(xe,"buildReferencedSkillPromptSection");function z(e,t){return["Task request:",e,...xe(t),"","Available WorkflowApi calls:","- wf.phase(name, async () => ...)","- wf.spawnAgent({ name, prompt, readOnly, modelHint, isolation, evidenceRefs, verification })","- wf.runAgent({ name, prompt, readOnly, modelHint, isolation, evidenceRefs, verification })","- wf.wait(taskId), wf.snapshot(taskId), wf.send(taskId, content), wf.stop(taskId, reason)","- wf.parallel([() => promise], { concurrency })","- wf.synthesize({ inputs, rubric }); inputs may be an array of materials, one already-formatted string, or a named object of materials","- wf.artifact(name, value), wf.log({ message, data })","- Return shapes: wf.runAgent/wf.wait return { taskId, name, status, finalText, digest?, verification?, usage }; wf.snapshot returns { taskId, name, status, lastText? }; wf.synthesize returns { text }; wf.artifact returns { name, path? }.","- Task identity rule: taskId is the opaque result.taskId/handle.taskId value, never the agent name string. Do not hardcode task IDs or pass string literals to wf.wait/wf.snapshot/wf.send/wf.stop; pass handle.taskId or result.taskId variables.","- Important naming trap: never use anyVariable.output in generated source. Agent results use finalText; synthesis results use text; task snapshots use lastText.","- Always await asynchronous workflow calls, especially wf.artifact(...), before returning.",'- Treat args as optional rerun input. Read request text with a fallback such as String(args.request || "the original request") or bake stable request context into child prompts.',"- For fan-out, prefer wf.parallel with thunks that call wf.runAgent; if using wf.spawnAgent, always wait or stop each handle so maxConcurrency capacity can release.","- Correct fan-out result pattern: const results = await wf.parallel([...].map((item) => () => wf.runAgent({...})), { concurrency }); then use results[n].finalText or results.map((r) => r.finalText). Do not call wf.wait after wf.runAgent.","- Keep intermediate findings in local variables and pass their finalText/text values forward; artifacts are durable outputs, not mutable args.","- File-writing/implementation requests are not report-only workflows. If the user asks to create, update, land, implement, or write project files, set manifest.readOnly=false, use readOnly:false child agents for the writing phases, give exact target paths in the prompt, and include verification:{ requiresMutation:true, requiredChangedPaths:[...], rejectPreparatoryFinalText:true } whenever target paths are knowable.","- Never put placeholder paths such as vNEXT.md or TODO.md in requiredChangedPaths. If the exact path is not knowable, omit requiredChangedPaths and keep requiresMutation:true.","- A write child must not ask the user to confirm routine filenames or version numbers already inferable from the request/context; it should choose the minimal project-consistent target paths, write them, and report what changed.",'- Prefer shared-cwd for write children. Do not set isolation:"worktree" for writing phases unless the workflow has an explicit merge-back strategy; isolated write evidence is not a delivered project change.',"- The outer run function must return displayable final text, preferably { synthesis: finalText }. Returning only inside a wf.phase callback is invalid. Artifact-only or empty returns are invalid.",'- Also await wf.artifact("final-report", { summary/report/text: finalText }) for durable inspection when a final report is produced.','- For multi-line prompts, rubrics, or report templates inside source, use JavaScript template literals (`...`) or arrays joined with "\\n"; never place raw newlines inside single-quoted or double-quoted strings.',"- Do not ask child agents to emit special transcript marker blocks. KodaX derives child-agent transcript digests after each child finishes; child prompts should focus on the actual work product and final report.","","Minimal source field-usage example; use it for result fields/syntax, not as the default workflow shape:","async function run(wf, args) {",'  const first = await wf.runAgent({ name: "first-pass", prompt: String(args.request || ""), readOnly: true });','  const second = await wf.runAgent({ name: "second-pass", prompt: first.finalText, readOnly: true });','  const synthesis = await wf.synthesize({ inputs: [first.finalText, second.finalText], rubric: "Synthesize a final answer." });',"  const finalText = synthesis.text;",'  await wf.artifact("final-report", { report: finalText });',"  return { synthesis: finalText };","}","","Canonical write-and-verify pattern for requests that must land project files:","async function run(wf, args) {",'  const request = String(args.request || "Implement the requested project change.");',"  const targetPaths = Array.isArray(args.targetPaths) ? args.targetPaths.map(String).filter(Boolean) : [];","  const writer = await wf.runAgent({",'    name: "implementation-writer",',"    prompt: [",'      "Implement the requested project change in the real workspace.",','      "Use project conventions, write the files, and do not stop at a plan.",','      targetPaths.length ? "Target paths: " + targetPaths.join(", ") : "Choose the minimal project-consistent target paths.",',"      request",'    ].join("\\n"),',"    readOnly: false,","    verification: {","      requiresMutation: true,","      ...(targetPaths.length ? { requiredChangedPaths: targetPaths } : {}),","      rejectPreparatoryFinalText: true","    }","  });","  const finalText = writer.finalText;",'  await wf.artifact("final-report", { report: finalText, verification: writer.verification });',"  return { synthesis: finalText, verification: writer.verification };","}","",`Supported pattern ids: ${A.join(", ")}`,"","Pattern selection guidance:",...Q,"- Complex multi-part work should normally include at least two work phases plus a final wf.synthesize barrier.","- Do not collapse independent investigation, verification, ranking, generation/filtering, or iteration into one child agent.","- A generated workflow with only one child agent is appropriate only when the request has one indivisible work product; otherwise decline simple tasks or generate a richer pattern.",'- Use evidenceRefs when one child reviews another child result; reference child results as "task_id:" + result.taskId, never as bare agent names. Use modelHint:"deep" for verifiers, judges, and synthesis-critical workers.',"","Manifest requirements:","- name, description, phases, readOnly, maxAgents, maxConcurrency, optional plannedAgents, optional tokenBudget",'- phases must be a JSON array of non-empty string literals, for example ["investigate","verify","synthesize"]; never return phase objects or a single string',"- maxAgents and maxConcurrency must be positive JSON integers","- plannedAgents is the best estimate of how many child agents this script will normally launch; it is for progress display and must be no larger than maxAgents","- maxAgents is a lifetime total cap for every wf.runAgent, wf.spawnAgent, and wf.synthesize call in the whole run, not the parallel lane count; reserve enough for all phases plus synthesis","- Do not set tokenBudget unless the user explicitly asks for a token/resource budget; omit it for normal complex work","- readOnly must be a JSON boolean","- optional mayUseWorktree when child prompts need isolated worktrees","- patterns must use only supported ids","- Use the same natural language as the task request for manifest description, approvalSummary, child agent prompts, synthesis rubric, and artifact text unless the user explicitly asks otherwise","","Return JSON only."].join(`
+`)}i(z,"buildWorkflowGenerationUserPrompt");async function be(e,t){let n=_(e),r=I(e);if(n.length===0&&r.length===0)return;let s=t.context?.gitRoot??t.context?.executionCwd??process.cwd(),o=t.context?.executionCwd??s,l=S(s);l.size===0&&await E(s);let f={workingDirectory:o,projectRoot:s,environment:{}},u=[...n,...r.filter(a=>!n.includes(a)&&l.has(a))];if(u.length===0)return;let p=[];for(let a of n)if(!l.has(a)){let c=l.list().map(d=>d.name).sort().join(", ");throw new Error(`workflow generation referenced unknown skill "${a}". Available skills: ${c||"(none)"}`)}for(let a of u){let c=await l.loadFull(a),d=await T(c,"",f);if(d.disableModelInvocation)throw new Error(`workflow generation referenced disabled skill "${a}"`);p.push(d.content)}return p.join(`
+
+`)}i(be,"buildWorkflowGenerationSkillContext");function ve(e){let t=["- Replace result.output from wf.runAgent(...) or wf.wait(...) with result.finalText.","- Replace result.output from wf.synthesize(...) with result.text.",'- Replace hardcoded wf.wait("...")/wf.snapshot("...")/wf.send("...", ...)/wf.stop("...", ...) calls with handle.taskId/result.taskId variables.','- Replace wf.wait("agent-name") after wf.runAgent(...) with captured runAgent/parallel results; wf.wait only accepts taskId values from spawnAgent handles.',"- Preserve the existing phase, fan-out, cross-review, and synthesis topology unless that topology itself is invalid; fix API usage instead of collapsing the workflow.","- Keep the outer run() return displayable, such as { synthesis: finalText }.",'- Fix generated JavaScript harness errors, including ReferenceError, wrong wf.* argument shapes, and multi-line prompts/rubrics that need template literals or "\\n".'];return(/\bwf\s*\.\s*output\s*\(/.test(e.previousOutput)||e.error.includes("wf.snapshot(taskId)"))&&t.splice(2,0,"- Replace wf.output(taskId) with wf.snapshot(taskId) for in-flight task snapshots."),[z(e.request,e.skillContext),"","Your previous output failed KodaX workflow validation.",`Repair attempt: ${e.attempt} of ${e.maxAttempts}.`,`Validation error: ${e.error}`,"","Common contract fixes:",...t,"","Previous output:",e.previousOutput,"","Return corrected JSON only. Keep the same task intent, but make the manifest and source valid."].join(`
+`)}i(ve,"buildWorkflowGenerationRepairPrompt");function Se(e){return/(?:token\s*(?:budget|limit|cap)|budget\s*(?:for|of)?\s*tokens?|\b\d+(?:\.\d+)?\s*(?:k|m)?\s*tokens?\b|\d+(?:\.\d+)?\s*(?:k|m)?\s*令牌|(?:tokens?|令牌).{0,12}(?:预算|上限|限制)|(?:预算|上限|限制).{0,12}(?:tokens?|令牌))/i.test(e)}i(Se,"requestExplicitlyMentionsTokenBudget");function Ee(e,t){if(e.tokenBudget===void 0||t===void 0||Se(t))return e;let{tokenBudget:n,...r}=e;return r}i(Ee,"stripImplicitTokenBudget");function Te(e,t={}){let n=ne(e),r=n.action;if(r==="decline")return{kind:"declined",reason:q(n,"reason"),rawText:e};if(r!=="generate")throw new Error('workflow generation action must be "generate" or "decline"');let s=y(q(n,"source")),o=Ee(ae(w(oe(n.manifest)),s),t.request),l=typeof n.approvalSummary=="string"&&n.approvalSummary.trim().length>0?n.approvalSummary:o.description;return{kind:"generated",manifest:o,source:s,module:g({manifest:o,source:s}),scriptSnapshot:{manifest:o,source:s},approvalSummary:l,rawText:e}}i(Te,"parseWorkflowGeneration");async function Ae(e){let t=e.request.trim();if(!t)return{kind:"declined",reason:"Workflow request is empty.",rawText:""};let n=H+1,r=z(t,e.skillContext),s="";for(let o=1;o<=n;o+=1){let l=await e.generateText({system:L,prompt:r,...e.signal?{signal:e.signal}:{}});try{let f=Te(l,{request:t});return f.kind==="generated"&&await ye({source:f.source,request:t}),f}catch(f){if(s=f instanceof Error?f.message:String(f),o>=n)break;r=ve({request:t,...e.skillContext?{skillContext:e.skillContext}:{},previousOutput:l,error:s,attempt:o+1,maxAttempts:n})}}throw new Error(`workflow generation did not produce a valid workflow after ${n} attempts. Last validation error: ${s}`)}i(Ae,"generateWorkflow");async function K(e){let t=b(e.options.provider),n=e.options.modelOverride??e.options.model??t.getModel(),r=e.options.effort?.trim();if(e.timeoutMs!==void 0&&e.timeoutSec!==void 0)throw new Error("workflow generation timeoutSec and timeoutMs cannot both be set");let s=e.timeoutMs??k(e.timeoutSec,"workflow generation timeoutSec")??Z(process.env,e.options.timeouts),o=e.skillContext??await be(e.request,e.options);return Ae({request:e.request,...o?{skillContext:o}:{},...e.signal?{signal:e.signal}:{},generateText:i(async l=>{let f=[{role:"user",content:l.prompt}],u=await v({provider:t,model:n,system:l.system,messages:f,querySource:"workflow-generation",timeoutMs:s,...r?{reasoning:{effort:r}}:{},...l.signal?{abortSignal:l.signal}:{}});if(!u.text.trim()){let p=u.error?`: ${u.error.message}`:"",a=u.stopReason==="timeout"?` after ${s}ms`:"";throw new Error(`workflow generation failed (${u.stopReason}${a})${p}`)}return u.text},"generateText")})}i(K,"generateWorkflowFromOptions");async function Oe(e){let t=e.source;if(t.kind==="saved")return{module:t.module};if(t.kind==="inline"){let s=w(t.manifest);return y(t.source),{module:g({manifest:s,source:t.source}),scriptSnapshot:{manifest:s,source:t.source}}}let r=await(e.generateWorkflow??K)({request:t.request,options:e.options});return r.kind==="declined"?{declined:r.reason}:{module:r.module,scriptSnapshot:r.scriptSnapshot}}i(Oe,"resolveModule");async function Fe(e){let t=await Oe(e);if("declined"in t)return{kind:"declined",reason:t.declined};let{module:n,scriptSnapshot:r}=t,s=e.now??(()=>Date.now()),o=e.runId??`run-${s().toString(36)}`,l=Re(e.runsBaseDir,o),f=e.manager??$(),u=W(n,e.options.workflowHostPolicy),p=f.startFromOptions({module:n,args:e.args,options:e.options,runId:o,runDir:l,...r?{scriptSnapshot:r}:{},...e.resumeFromRunDir?{resumeFromRunDir:e.resumeFromRunDir}:{},...e.processMetadata?{processMetadata:e.processMetadata}:{},...e.approval?{approval:e.approval}:{},...e.onEvent?{onEvent:e.onEvent}:{},...e.signal?{signal:e.signal}:{}});return{kind:"started",runId:o,runDir:l,module:n,managed:p,approvalSummary:u,...r?{scriptSnapshot:r}:{}}}i(Fe,"startManagedWorkflow");export{L as a,M as b,Z as c,y as d,z as e,be as f,Te as g,Ae as h,K as i,Fe as j};