feat: engine injects extract provider at runtime (Phase 2)

- createWorkflow(def, binding) — no more extract/llmProvider params
- Engine resolves extract provider from workflow.yaml via resolveModel
- WorkflowFnOptions now carries extract + llmProvider (engine-injected)
- Delete extract-provider.ts, inline maxDepth helper
- Template packages simplified: only take agent binding
- Breaking change: bundles no longer carry provider config

Refs #110

examples/hello-world.ts

@@ -1,4 +1,4 @@
-import { createExtract, createWorkflow, END, type RoleDefinition } from "@uncaged/workflow";
+import { createWorkflow, END, type RoleDefinition } from "@uncaged/workflow";
 import * as z from "zod/v4";
 
 type Roles = {
@@ -32,12 +32,6 @@ const greeter: RoleDefinition<Roles["greeter"]> = {
   extractMode: "single",
 };
 
-const extract = createExtract({
-  baseUrl: "http://127.0.0.1:9",
-  apiKey: "",
-  model: "",
-});
-
 export const run = createWorkflow<Roles>(
   {
     roles: { greeter },
@@ -48,6 +42,4 @@ export const run = createWorkflow<Roles>(
   {
     agent: async (ctx) => `Hello, ${ctx.start.content}`,
   },
-  extract,
-  null,
 );

packages/cli-workflow/__tests__/bundle-fixture.ts

@@ -1,4 +1,4 @@
-import type { ParsedAddArgv } from "../src/commands/workflow/add-argv.js";
+import type { ParsedAddArgv } from "../src/commands/workflow/index.js";
 
 export function addCliArgs(name: string, filePath: string): ParsedAddArgv {
   return { name, filePath, typesPath: null };

packages/cli-workflow/__tests__/commands.test.ts

@@ -4,16 +4,16 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 
 import { getGlobalCasDir, getRegisteredWorkflow, readWorkflowRegistry } from "@uncaged/workflow";
-import { cmdCasGet } from "../src/commands/cas/get.js";
-import { cmdCasList } from "../src/commands/cas/list.js";
-import { cmdCasPut } from "../src/commands/cas/put.js";
-import { cmdCasRm } from "../src/commands/cas/rm.js";
-import { cmdAdd } from "../src/commands/workflow/add.js";
-import { cmdHistory } from "../src/commands/workflow/history.js";
-import { cmdList, formatListLines } from "../src/commands/workflow/list.js";
-import { cmdRemove } from "../src/commands/workflow/rm.js";
-import { cmdRollback } from "../src/commands/workflow/rollback.js";
-import { cmdShow } from "../src/commands/workflow/show.js";
+import { cmdCasGet, cmdCasList, cmdCasPut, cmdCasRm } from "../src/commands/cas/index.js";
+import {
+  cmdAdd,
+  cmdHistory,
+  cmdList,
+  cmdRemove,
+  cmdRollback,
+  cmdShow,
+  formatListLines,
+} from "../src/commands/workflow/index.js";
 import { addCliArgs } from "./bundle-fixture.js";
 
 const fixtureDescriptor = `export const descriptor = { description: "fixture", roles: {} };

packages/cli-workflow/__tests__/fork-cli.test.ts

@@ -3,11 +3,11 @@ import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { createCasStore, getContentMerklePayload, getGlobalCasDir } from "@uncaged/workflow";
-import { cmdFork } from "../src/commands/thread/fork.js";
-import { cmdRun } from "../src/commands/thread/run.js";
-import { cmdAdd } from "../src/commands/workflow/add.js";
+import { cmdFork, cmdRun } from "../src/commands/thread/index.js";
+import { cmdAdd } from "../src/commands/workflow/index.js";
 import { pathExists } from "../src/fs-utils.js";
 import { addCliArgs } from "./bundle-fixture.js";
+import { ensureTestWorkflowRegistryConfig } from "./workflow-registry-fixture.js";
 
 /** Three-role workflow that respects `input.steps` for fork/resume. */
 const threeRoleBundleSource = `import { putContentMerkleNode } from "@uncaged/workflow";
@@ -78,6 +78,7 @@ describe("cli fork", () => {
     prevEnv = process.env.UNCAGED_WORKFLOW_STORAGE_ROOT;
     storageRoot = await mkdtemp(join(tmpdir(), "uncaged-wf-fork-"));
     process.env.UNCAGED_WORKFLOW_STORAGE_ROOT = storageRoot;
+    await ensureTestWorkflowRegistryConfig(storageRoot);
   });
 
   afterEach(async () => {

packages/cli-workflow/__tests__/gc-cli.test.ts

@@ -10,7 +10,7 @@ import {
   getGlobalCasDir,
   putContentMerkleNode,
 } from "@uncaged/workflow";
-import { cmdThreadRemove } from "../src/commands/thread/rm.js";
+import { cmdThreadRemove } from "../src/commands/thread/index.js";
 import { pathExists } from "../src/fs-utils.js";
 
 const cliEntryPath = fileURLToPath(new URL("../src/cli.ts", import.meta.url));

packages/cli-workflow/__tests__/init-template.test.ts

@@ -4,8 +4,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 
 import { runCli } from "../src/cli-dispatch.js";
-import { cmdInitTemplate } from "../src/commands/init/template.js";
-import { cmdInitWorkspace } from "../src/commands/init/workspace.js";
+import { cmdInitTemplate, cmdInitWorkspace } from "../src/commands/init/index.js";
 import { pathExists } from "../src/fs-utils.js";
 
 describe("init template", () => {

packages/cli-workflow/__tests__/init-workspace.test.ts

@@ -4,7 +4,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 
 import { formatCliUsage, runCli } from "../src/cli-dispatch.js";
-import { cmdInitWorkspace } from "../src/commands/init/workspace.js";
+import { cmdInitWorkspace } from "../src/commands/init/index.js";
 import { pathExists } from "../src/fs-utils.js";
 
 describe("init workspace", () => {

packages/cli-workflow/__tests__/live.test.ts

@@ -13,7 +13,7 @@ import {
   LIVE_CONTENT_MAX_LINES,
   type LiveRoleRow,
   renderLiveRoleStepLines,
-} from "../src/commands/thread/live.js";
+} from "../src/commands/thread/index.js";
 import { parseLiveArgv } from "../src/live-argv.js";
 
 const cliEntryPath = fileURLToPath(new URL("../src/cli.ts", import.meta.url));

packages/cli-workflow/__tests__/thread-cli.test.ts

@@ -5,16 +5,21 @@ import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { getGlobalCasDir } from "@uncaged/workflow";
-import { cmdCasPut } from "../src/commands/cas/put.js";
-import { cmdKill, cmdPause, cmdResume } from "../src/commands/thread/control.js";
-import { cmdThreads } from "../src/commands/thread/list.js";
-import { cmdPs } from "../src/commands/thread/ps.js";
-import { cmdThreadRemove } from "../src/commands/thread/rm.js";
-import { cmdRun } from "../src/commands/thread/run.js";
-import { cmdThreadShow } from "../src/commands/thread/show.js";
-import { cmdAdd } from "../src/commands/workflow/add.js";
+import { cmdCasPut } from "../src/commands/cas/index.js";
+import {
+  cmdKill,
+  cmdPause,
+  cmdPs,
+  cmdResume,
+  cmdRun,
+  cmdThreadRemove,
+  cmdThreadShow,
+  cmdThreads,
+} from "../src/commands/thread/index.js";
+import { cmdAdd } from "../src/commands/workflow/index.js";
 import { pathExists, readTextFileIfExists } from "../src/fs-utils.js";
 import { addCliArgs } from "./bundle-fixture.js";
+import { ensureTestWorkflowRegistryConfig } from "./workflow-registry-fixture.js";
 
 const wfPutImport = `import { putContentMerkleNode } from "@uncaged/workflow";
 `;
@@ -138,6 +143,7 @@ describe("cli thread commands", () => {
     prevEnv = process.env.UNCAGED_WORKFLOW_STORAGE_ROOT;
     storageRoot = await mkdtemp(join(tmpdir(), "uncaged-wf-thread-"));
     process.env.UNCAGED_WORKFLOW_STORAGE_ROOT = storageRoot;
+    await ensureTestWorkflowRegistryConfig(storageRoot);
   });
 
   afterEach(async () => {

packages/cli-workflow/__tests__/workflow-registry-fixture.ts

@@ -0,0 +1,18 @@
+import { writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+/** Minimal valid global config so {@link executeThread} can resolve the extract scene (CLI integration tests). */
+export const TEST_WORKFLOW_REGISTRY_YAML = `config:
+  maxDepth: 3
+  providers:
+    stub:
+      baseUrl: http://127.0.0.1:9
+      apiKey: test
+  models:
+    default: stub/m
+workflows: {}
+`;
+
+export async function ensureTestWorkflowRegistryConfig(storageRoot: string): Promise<void> {
+  await writeFile(join(storageRoot, "workflow.yaml"), TEST_WORKFLOW_REGISTRY_YAML, "utf8");
+}

packages/cli-workflow/src/cli-dispatch.ts

@@ -2,8 +2,8 @@ import type { CommandEntry, DispatchFn } from "./cli-command-types.js";
 import { printCliError, printCliLine, printCliWarn } from "./cli-output.js";
 import { getCommandRegistry } from "./cli-registry.js";
 import { formatCliUsage as formatCliUsageWithGroups } from "./cli-usage.js";
-import { createCasDispatcher, dispatchGc } from "./commands/cas/dispatch.js";
-import { createInitDispatcher } from "./commands/init/dispatch.js";
+import { createCasDispatcher, dispatchGc } from "./commands/cas/index.js";
+import { createInitDispatcher } from "./commands/init/index.js";
 import {
   createThreadDispatcher,
   dispatchFork,
@@ -14,7 +14,7 @@ import {
   dispatchResume,
   dispatchRun,
   dispatchThreadList,
-} from "./commands/thread/dispatch.js";
+} from "./commands/thread/index.js";
 import {
   createWorkflowDispatcher,
   dispatchAdd,
@@ -23,7 +23,7 @@ import {
   dispatchRemove,
   dispatchRollback,
   dispatchShow,
-} from "./commands/workflow/dispatch.js";
+} from "./commands/workflow/index.js";
 import { formatSkillIndex, formatSkillTopic, getSkillTopics } from "./skill.js";
 
 export type { CommandEntry, CommandGroup, DispatchFn } from "./cli-command-types.js";

packages/cli-workflow/src/cli-registry.ts

@@ -1,9 +1,9 @@
 import type { CommandGroup } from "./cli-command-types.js";
 import { setCommandGroupsForUsage } from "./cli-usage-context.js";
-import { CAS_SUBCOMMAND_TABLE } from "./commands/cas/dispatch.js";
-import { INIT_SUBCOMMAND_TABLE } from "./commands/init/dispatch.js";
-import { THREAD_SUBCOMMAND_TABLE } from "./commands/thread/dispatch.js";
-import { WORKFLOW_SUBCOMMAND_TABLE } from "./commands/workflow/dispatch.js";
+import { CAS_SUBCOMMAND_TABLE } from "./commands/cas/index.js";
+import { INIT_SUBCOMMAND_TABLE } from "./commands/init/index.js";
+import { THREAD_SUBCOMMAND_TABLE } from "./commands/thread/index.js";
+import { WORKFLOW_SUBCOMMAND_TABLE } from "./commands/workflow/index.js";
 
 export function getCommandRegistry(): ReadonlyArray<CommandGroup> {
   return [

packages/cli-workflow/src/commands/cas/dispatch.ts

@@ -1,4 +1,4 @@
-import type { CommandEntry, DispatchGroupFn } from "../../cli-command-types.js";
+import type { CommandEntry } from "../../cli-command-types.js";
 import { printCliError, printCliLine } from "../../cli-output.js";
 import { formatCliUsage, USAGE_SKILL_TOPIC_ROWS } from "../../cli-usage.js";
 import { getCommandGroupsForUsage } from "../../cli-usage-context.js";
@@ -7,6 +7,7 @@ import { cmdCasGet } from "./get.js";
 import { cmdCasList } from "./list.js";
 import { cmdCasPut } from "./put.js";
 import { cmdCasRm } from "./rm.js";
+import type { CasDispatchDeps } from "./types.js";
 
 function usageText(): string {
   return formatCliUsage(getCommandGroupsForUsage(), USAGE_SKILL_TOPIC_ROWS);
@@ -110,7 +111,7 @@ export const CAS_SUBCOMMAND_TABLE: Record<string, CommandEntry> = {
   gc: { handler: dispatchGc, args: "", description: "Garbage-collect unreferenced CAS entries" },
 };
 
-export function createCasDispatcher(deps: { dispatchGroup: DispatchGroupFn }) {
+export function createCasDispatcher(deps: CasDispatchDeps) {
   const { dispatchGroup } = deps;
   return async function dispatchCas(storageRoot: string, argv: string[]): Promise<number> {
     const result = dispatchGroup("cas", CAS_SUBCOMMAND_TABLE, storageRoot, argv);

packages/cli-workflow/src/commands/cas/index.ts

@@ -1,3 +1,12 @@
+export {
+  CAS_SUBCOMMAND_TABLE,
+  createCasDispatcher,
+  dispatchCasGet,
+  dispatchCasList,
+  dispatchCasPut,
+  dispatchCasRm,
+  dispatchGc,
+} from "./dispatch.js";
 export { cmdGc } from "./gc.js";
 export { cmdCasGet } from "./get.js";
 export { cmdCasList } from "./list.js";

packages/cli-workflow/src/commands/cas/types.ts

@@ -0,0 +1,5 @@
+import type { DispatchGroupFn } from "../../cli-command-types.js";
+
+export type CasDispatchDeps = {
+  dispatchGroup: DispatchGroupFn;
+};

packages/cli-workflow/src/commands/init/dispatch.ts

@@ -1,8 +1,9 @@
-import type { CommandEntry, DispatchGroupFn } from "../../cli-command-types.js";
+import type { CommandEntry } from "../../cli-command-types.js";
 import { printCliError, printCliLine } from "../../cli-output.js";
 import { formatCliUsage, USAGE_SKILL_TOPIC_ROWS } from "../../cli-usage.js";
 import { getCommandGroupsForUsage } from "../../cli-usage-context.js";
 import { cmdInitTemplate } from "./template.js";
+import type { InitDispatchDeps } from "./types.js";
 import { cmdInitWorkspace } from "./workspace.js";
 
 function usageText(): string {
@@ -52,7 +53,7 @@ export const INIT_SUBCOMMAND_TABLE: Record<string, CommandEntry> = {
   },
 };
 
-export function createInitDispatcher(deps: { dispatchGroup: DispatchGroupFn }) {
+export function createInitDispatcher(deps: InitDispatchDeps) {
   const { dispatchGroup } = deps;
   return async function dispatchInit(storageRoot: string, argv: string[]): Promise<number> {
     const result = dispatchGroup("init", INIT_SUBCOMMAND_TABLE, storageRoot, argv);

packages/cli-workflow/src/commands/init/index.ts

@@ -1,4 +1,9 @@
-export type { CmdInitTemplateSuccess } from "./template.js";
+export {
+  createInitDispatcher,
+  dispatchInitTemplate,
+  dispatchInitWorkspace,
+  INIT_SUBCOMMAND_TABLE,
+} from "./dispatch.js";
 export { cmdInitTemplate } from "./template.js";
-export type { CmdInitWorkspaceSuccess } from "./workspace.js";
+export type { CmdInitTemplateSuccess, CmdInitWorkspaceSuccess } from "./types.js";
 export { cmdInitWorkspace } from "./workspace.js";

packages/cli-workflow/src/commands/init/template.ts

@@ -12,23 +12,8 @@ import {
   templateRolesTs,
   templateTsconfigJson,
 } from "./templates.js";
-
-export type CmdInitTemplateSuccess = {
-  templatePath: string;
-};
-
-function validateWorkspaceSegment(name: string): Result<void, string> {
-  if (name.length === 0) {
-    return err("workspace name must not be empty");
-  }
-  if (name === "." || name === "..") {
-    return err("invalid workspace name");
-  }
-  if (name.includes("/") || name.includes("\\")) {
-    return err("workspace name must not contain path separators");
-  }
-  return ok(undefined);
-}
+import type { CmdInitTemplateSuccess } from "./types.js";
+import { validateWorkspaceSegment } from "./validate.js";
 
 function hasTemplatesWorkspaceGlob(workspaces: unknown): boolean {
   return Array.isArray(workspaces) && workspaces.includes("templates/*");

packages/cli-workflow/src/commands/init/types.ts

@@ -0,0 +1,13 @@
+import type { DispatchGroupFn } from "../../cli-command-types.js";
+
+export type CmdInitTemplateSuccess = {
+  templatePath: string;
+};
+
+export type CmdInitWorkspaceSuccess = {
+  rootPath: string;
+};
+
+export type InitDispatchDeps = {
+  dispatchGroup: DispatchGroupFn;
+};

packages/cli-workflow/src/commands/init/validate.ts

@@ -0,0 +1,15 @@
+import { err, ok, type Result } from "@uncaged/workflow";
+
+/** Validates a single path segment for workspace / template names (no separators, not `.` / `..`). */
+export function validateWorkspaceSegment(name: string): Result<void, string> {
+  if (name.length === 0) {
+    return err("workspace name must not be empty");
+  }
+  if (name === "." || name === "..") {
+    return err("invalid workspace name");
+  }
+  if (name.includes("/") || name.includes("\\")) {
+    return err("workspace name must not contain path separators");
+  }
+  return ok(undefined);
+}

packages/cli-workflow/src/commands/init/workspace.ts

@@ -4,23 +4,8 @@ import { join } from "node:path";
 import { err, ok, type Result } from "@uncaged/workflow";
 
 import { pathExists } from "../../fs-utils.js";
-
-export type CmdInitWorkspaceSuccess = {
-  rootPath: string;
-};
-
-function validateWorkspaceSegment(name: string): Result<void, string> {
-  if (name.length === 0) {
-    return err("workspace name must not be empty");
-  }
-  if (name === "." || name === "..") {
-    return err("invalid workspace name");
-  }
-  if (name.includes("/") || name.includes("\\")) {
-    return err("workspace name must not contain path separators");
-  }
-  return ok(undefined);
-}
+import type { CmdInitWorkspaceSuccess } from "./types.js";
+import { validateWorkspaceSegment } from "./validate.js";
 
 function rootPackageJson(workspaceName: string): string {
   return `${JSON.stringify(
@@ -122,7 +107,7 @@ Init 生成的骨架：\`templates/\` 下放可复用定义，\`workflows/\` 下
 2. **编写 RoleDefinition**：为每个角色写 Zod \`schema\`，补齐 \`systemPrompt\` / \`extractPrompt\` / \`description\`。
 3. **编写 Moderator**：根据 \`ctx.steps\` 与业务状态返回下一个角色名或 \`END\`。
 4. **组装 WorkflowDefinition**：在模板 \`index\` 中导出 definition（以及必要的角色 / moderator 导出）。
-5. **实例化**：在 workflow 包中使用 \`createWorkflow(def, binding, extract)\`（或项目约定的封装）绑定 **AgentFn** / **ExtractFn**。
+5. **实例化**：在 workflow 包中使用 \`createWorkflow(def, binding)\`（或项目约定的封装）绑定 **AgentFn**；**ExtractFn** 由引擎从 **workflow.yaml** 注入 \`WorkflowFnOptions\`。
 6. **构建**：打包为单个 **.esm.js** bundle，使用 **uncaged-workflow add** 注册。
 
 ## 4. 编码规范

packages/cli-workflow/src/commands/thread/dispatch.ts

@@ -1,4 +1,4 @@
-import type { CommandEntry, DispatchGroupFn } from "../../cli-command-types.js";
+import type { CommandEntry } from "../../cli-command-types.js";
 import { printCliError, printCliLine } from "../../cli-output.js";
 import { formatCliUsage, USAGE_SKILL_TOPIC_ROWS } from "../../cli-usage.js";
 import { getCommandGroupsForUsage } from "../../cli-usage-context.js";
@@ -13,6 +13,7 @@ import { cmdPs } from "./ps.js";
 import { cmdThreadRemove } from "./rm.js";
 import { cmdRun } from "./run.js";
 import { cmdThreadShow } from "./show.js";
+import type { ThreadDispatchDeps } from "./types.js";
 
 function usageText(): string {
   return formatCliUsage(getCommandGroupsForUsage(), USAGE_SKILL_TOPIC_ROWS);
@@ -191,7 +192,7 @@ export const THREAD_SUBCOMMAND_TABLE: Record<string, CommandEntry> = {
   resume: { handler: dispatchResume, args: "<thread-id>", description: "Resume a paused thread" },
 };
 
-export function createThreadDispatcher(deps: { dispatchGroup: DispatchGroupFn }) {
+export function createThreadDispatcher(deps: ThreadDispatchDeps) {
   const { dispatchGroup } = deps;
   return async function dispatchThread(storageRoot: string, argv: string[]): Promise<number> {
     const result = dispatchGroup("thread", THREAD_SUBCOMMAND_TABLE, storageRoot, argv);

packages/cli-workflow/src/commands/thread/fork-argv.ts

@@ -1,8 +1,8 @@
 import { err, ok, type Result } from "@uncaged/workflow";
 
-export function parseForkArgv(
-  argv: string[],
-): Result<{ threadId: string; fromRole: string | null }, string> {
+import type { ParsedForkArgv } from "./types.js";
+
+export function parseForkArgv(argv: string[]): Result<ParsedForkArgv, string> {
   if (argv.length === 0) {
     return err("fork requires <thread-id>");
   }

packages/cli-workflow/src/commands/thread/index.ts

@@ -1,8 +1,21 @@
 export { cmdKill, cmdPause, cmdResume } from "./control.js";
+export {
+  createThreadDispatcher,
+  dispatchFork,
+  dispatchKill,
+  dispatchLive,
+  dispatchPause,
+  dispatchPs,
+  dispatchResume,
+  dispatchRun,
+  dispatchThreadList,
+  dispatchThreadRm,
+  dispatchThreadShow,
+  THREAD_SUBCOMMAND_TABLE,
+} from "./dispatch.js";
 export { cmdFork } from "./fork.js";
 export { parseForkArgv } from "./fork-argv.js";
 export { cmdThreads } from "./list.js";
-export type { LiveRoleRow } from "./live.js";
 export {
   cmdLive,
   formatLiveDebugLine,
@@ -14,3 +27,4 @@ export { cmdPs } from "./ps.js";
 export { cmdThreadRemove } from "./rm.js";
 export { cmdRun } from "./run.js";
 export { cmdThreadShow } from "./show.js";
+export type { LiveRoleRow } from "./types.js";

packages/cli-workflow/src/commands/thread/live.ts

@@ -17,16 +17,10 @@ import { printCliError, printCliLine } from "../../cli-output.js";
 import { pathExists } from "../../fs-utils.js";
 import type { ParsedLiveArgv } from "../../live-argv.js";
 import { findLatestThreadDataPath, resolveThreadDataPath } from "../../thread-scan.js";
+import type { LiveRoleRow } from "./types.js";
 
 export const LIVE_CONTENT_MAX_LINES = 10;
 
-export type LiveRoleRow = {
-  role: string;
-  content: string;
-  meta: Record<string, unknown>;
-  timestamp: number;
-};
-
 export function formatLiveTimeLabel(timestampMs: number): string {
   const d = new Date(timestampMs);
   const hh = String(d.getHours()).padStart(2, "0");

packages/cli-workflow/src/commands/thread/types.ts

@@ -0,0 +1,17 @@
+import type { DispatchGroupFn } from "../../cli-command-types.js";
+
+export type LiveRoleRow = {
+  role: string;
+  content: string;
+  meta: Record<string, unknown>;
+  timestamp: number;
+};
+
+export type ParsedForkArgv = {
+  threadId: string;
+  fromRole: string | null;
+};
+
+export type ThreadDispatchDeps = {
+  dispatchGroup: DispatchGroupFn;
+};

packages/cli-workflow/src/commands/workflow/add-argv.ts

@@ -1,11 +1,6 @@
 import { err, ok, type Result } from "@uncaged/workflow";
 
-export type ParsedAddArgv = {
-  name: string;
-  filePath: string;
-  /** Override path to `.d.ts` when adding a bundle. */
-  typesPath: string | null;
-};
+import type { ParsedAddArgv } from "./types.js";
 
 type ParsedLongFlag = { advance: 2; kind: "types"; value: string };
 

packages/cli-workflow/src/commands/workflow/add.ts

@@ -17,12 +17,7 @@ import {
 import { storeWorkflowBundleArtifacts } from "../../bundle-store.js";
 import { validateCliWorkflowName } from "../../workflow-name.js";
 
-import type { ParsedAddArgv } from "./add-argv.js";
-
-export type CmdAddSuccess = {
-  hash: string;
-  warnings: ReadonlyArray<string>;
-};
+import type { CmdAddSuccess, ParsedAddArgv } from "./types.js";
 
 function isEsmBundle(path: string): boolean {
   return path.endsWith(".esm.js");

packages/cli-workflow/src/commands/workflow/dispatch.ts

@@ -1,4 +1,4 @@
-import type { CommandEntry, DispatchGroupFn } from "../../cli-command-types.js";
+import type { CommandEntry } from "../../cli-command-types.js";
 import { printCliError, printCliLine, printCliWarn } from "../../cli-output.js";
 import { formatCliUsage, USAGE_SKILL_TOPIC_ROWS } from "../../cli-usage.js";
 import { getCommandGroupsForUsage } from "../../cli-usage-context.js";
@@ -9,6 +9,7 @@ import { cmdList, formatListLines } from "./list.js";
 import { cmdRemove } from "./rm.js";
 import { cmdRollback } from "./rollback.js";
 import { cmdShow, formatShowYaml } from "./show.js";
+import type { WorkflowDispatchDeps } from "./types.js";
 
 function usageText(): string {
   return formatCliUsage(getCommandGroupsForUsage(), USAGE_SKILL_TOPIC_ROWS);
@@ -140,11 +141,6 @@ export const WORKFLOW_SUBCOMMAND_TABLE: Record<string, CommandEntry> = {
   },
 };
 
-type WorkflowDispatchDeps = {
-  dispatchGroup: DispatchGroupFn;
-  printDeprecation: (oldCmd: string, newCmd: string) => void;
-};
-
 export function createWorkflowDispatcher(deps: WorkflowDispatchDeps) {
   const { dispatchGroup, printDeprecation } = deps;
   return async function dispatchWorkflow(storageRoot: string, argv: string[]): Promise<number> {

packages/cli-workflow/src/commands/workflow/index.ts

@@ -1,9 +1,18 @@
-export type { CmdAddSuccess } from "./add.js";
 export { cmdAdd, formatAddSuccess } from "./add.js";
-export type { ParsedAddArgv } from "./add-argv.js";
 export { parseAddArgv } from "./add-argv.js";
+export {
+  createWorkflowDispatcher,
+  dispatchAdd,
+  dispatchHistory,
+  dispatchList,
+  dispatchRemove,
+  dispatchRollback,
+  dispatchShow,
+  WORKFLOW_SUBCOMMAND_TABLE,
+} from "./dispatch.js";
 export { cmdHistory } from "./history.js";
 export { cmdList, formatListLines } from "./list.js";
 export { cmdRemove } from "./rm.js";
 export { cmdRollback } from "./rollback.js";
 export { cmdShow, formatShowYaml } from "./show.js";
+export type { CmdAddSuccess, ParsedAddArgv } from "./types.js";

packages/cli-workflow/src/commands/workflow/types.ts

@@ -0,0 +1,18 @@
+import type { DispatchGroupFn } from "../../cli-command-types.js";
+
+export type ParsedAddArgv = {
+  name: string;
+  filePath: string;
+  /** Override path to `.d.ts` when adding a bundle. */
+  typesPath: string | null;
+};
+
+export type CmdAddSuccess = {
+  hash: string;
+  warnings: ReadonlyArray<string>;
+};
+
+export type WorkflowDispatchDeps = {
+  dispatchGroup: DispatchGroupFn;
+  printDeprecation: (oldCmd: string, newCmd: string) => void;
+};

packages/workflow-template-develop/src/index.ts

@@ -1,8 +1,6 @@
 import {
   type AgentBinding,
   createWorkflow,
-  type ExtractFn,
-  type LlmProvider,
   type WorkflowDefinition,
   type WorkflowFn,
 } from "@uncaged/workflow";
@@ -43,10 +41,6 @@ export const developWorkflowDefinition: WorkflowDefinition<DevelopMeta> = {
   moderator: developModerator,
 };
 
-export function createDevelopRun(
-  binding: AgentBinding,
-  extract: ExtractFn,
-  llmProvider: LlmProvider | null,
-): WorkflowFn {
-  return createWorkflow(developWorkflowDefinition, binding, extract, llmProvider);
+export function createDevelopRun(binding: AgentBinding): WorkflowFn {
+  return createWorkflow(developWorkflowDefinition, binding);
 }

packages/workflow-template-solve-issue/__tests__/solve-issue-template.test.ts

@@ -250,17 +250,20 @@ describe("createSolveIssueRun", () => {
     const cas = createCasStore(casDir);
 
     // Override developer so the test does not spin up a child workflow.
-    const run = createSolveIssueRun(
-      {
-        agent: async () => "",
-        overrides: { developer: async () => "stub-root-hash" },
-      },
-      stubExtract,
-      stubLlmProvider,
-    );
+    const run = createSolveIssueRun({
+      agent: async () => "",
+      overrides: { developer: async () => "stub-root-hash" },
+    });
     const gen = run(
       { prompt: "task", steps: [] },
-      { threadId: "01TEST000000000000000000TR", maxRounds: 20, depth: 0, cas },
+      {
+        threadId: "01TEST000000000000000000TR",
+        maxRounds: 20,
+        depth: 0,
+        cas,
+        extract: stubExtract,
+        llmProvider: stubLlmProvider,
+      },
     );
     const first = await gen.next();
     expect(first.done).toBe(false);
@@ -294,33 +297,36 @@ describe("createSolveIssueRun", () => {
     const cas = createCasStore(casDir);
 
     const calls: string[] = [];
-    const run = createSolveIssueRun(
-      {
-        agent: async () => {
-          calls.push("default");
+    const run = createSolveIssueRun({
+      agent: async () => {
+        calls.push("default");
+        return "";
+      },
+      overrides: {
+        preparer: async () => {
+          calls.push("preparer");
           return "";
         },
-        overrides: {
-          preparer: async () => {
-            calls.push("preparer");
-            return "";
-          },
-          developer: async () => {
-            calls.push("developer");
-            return "stub-root-hash";
-          },
-          submitter: async () => {
-            calls.push("submitter");
-            return "";
-          },
+        developer: async () => {
+          calls.push("developer");
+          return "stub-root-hash";
+        },
+        submitter: async () => {
+          calls.push("submitter");
+          return "";
         },
       },
-      stubExtract,
-      stubLlmProvider,
-    );
+    });
     const gen = run(
       { prompt: "task", steps: [] },
-      { threadId: "01TEST000000000000000000TR", maxRounds: 20, depth: 0, cas },
+      {
+        threadId: "01TEST000000000000000000TR",
+        maxRounds: 20,
+        depth: 0,
+        cas,
+        extract: stubExtract,
+        llmProvider: stubLlmProvider,
+      },
     );
     await gen.next();
     expect(calls).toEqual(["preparer"]);
@@ -353,22 +359,25 @@ describe("createSolveIssueRun", () => {
     const cas = createCasStore(casDir);
 
     let developerInvocations = 0;
-    const run = createSolveIssueRun(
-      {
-        agent: async () => "",
-        overrides: {
-          developer: async () => {
-            developerInvocations += 1;
-            return "stub-root-hash";
-          },
+    const run = createSolveIssueRun({
+      agent: async () => "",
+      overrides: {
+        developer: async () => {
+          developerInvocations += 1;
+          return "stub-root-hash";
         },
       },
-      stubExtract,
-      stubLlmProvider,
-    );
+    });
     const gen = run(
       { prompt: "task", steps: [] },
-      { threadId: "01TEST000000000000000000TR", maxRounds: 20, depth: 0, cas },
+      {
+        threadId: "01TEST000000000000000000TR",
+        maxRounds: 20,
+        depth: 0,
+        cas,
+        extract: stubExtract,
+        llmProvider: stubLlmProvider,
+      },
     );
     // preparer
     await gen.next();

packages/workflow-template-solve-issue/src/index.ts

@@ -1,8 +1,6 @@
 import {
   type AgentBinding,
   createWorkflow,
-  type ExtractFn,
-  type LlmProvider,
   type WorkflowDefinition,
   type WorkflowFn,
   workflowAsAgent,
@@ -46,11 +44,7 @@ export const solveIssueWorkflowDefinition: WorkflowDefinition<SolveIssueMeta> =
  * {@link workflowAsAgent}; if the caller supplies their own `developer` override in
  * `binding.overrides`, it takes precedence so tests and custom hosts can stub it.
  */
-export function createSolveIssueRun(
-  binding: AgentBinding,
-  extract: ExtractFn,
-  llmProvider: LlmProvider | null,
-): WorkflowFn {
+export function createSolveIssueRun(binding: AgentBinding): WorkflowFn {
   const developerOverride = binding.overrides?.developer ?? workflowAsAgent("develop");
   const mergedBinding: AgentBinding = {
     agent: binding.agent,
@@ -59,5 +53,5 @@ export function createSolveIssueRun(
       developer: developerOverride,
     },
   };
-  return createWorkflow(solveIssueWorkflowDefinition, mergedBinding, extract, llmProvider);
+  return createWorkflow(solveIssueWorkflowDefinition, mergedBinding);
 }

packages/workflow/__tests__/engine.test.ts

@@ -1,5 +1,5 @@
 import { afterEach, describe, expect, test } from "bun:test";
-import { mkdir, mkdtemp, readFile, rm } from "node:fs/promises";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import * as z from "zod/v4";
@@ -13,8 +13,7 @@ import {
 } from "../src/cas/merkle.js";
 import { createWorkflow } from "../src/engine/create-workflow.js";
 import { executeThread } from "../src/engine/engine.js";
-import { createExtract } from "../src/extract/extract-fn.js";
-import { END, type LlmProvider } from "../src/types.js";
+import { END } from "../src/types.js";
 import { createLogger } from "../src/util/logger.js";
 
 const plannerMetaSchema = z.object({
@@ -82,11 +81,20 @@ function installMockChatCompletions(sequence: ReadonlyArray<Record<string, unkno
   };
 }
 
-const demoExtract = createExtract({
-  baseUrl: "http://127.0.0.1:9",
-  apiKey: "test",
-  model: "test",
-});
+const EXTRACT_REGISTRY_YAML = `config:
+  maxDepth: 3
+  providers:
+    stub:
+      baseUrl: http://127.0.0.1:9
+      apiKey: test
+  models:
+    default: stub/model
+workflows: {}
+`;
+
+async function writeExtractRegistryConfig(storageRoot: string): Promise<void> {
+  await writeFile(join(storageRoot, "workflow.yaml"), EXTRACT_REGISTRY_YAML, "utf8");
+}
 
 const demoWorkflow = createWorkflow<DemoMeta>(
   {
@@ -125,8 +133,6 @@ const demoWorkflow = createWorkflow<DemoMeta>(
       coder: async () => "code-body",
     },
   },
-  demoExtract,
-  null,
 );
 
 describe("executeThread", () => {
@@ -150,6 +156,7 @@ describe("executeThread", () => {
       const dataPath = join(root, "logs", hash, `${threadId}.data.jsonl`);
       const infoPath = join(root, "logs", hash, `${threadId}.info.jsonl`);
       await mkdir(join(root, "logs", hash), { recursive: true });
+      await writeExtractRegistryConfig(root);
       const cas = createCasStore(join(root, "cas"));
 
       const logger = createLogger({ sink: { kind: "file", path: infoPath } });
@@ -166,6 +173,7 @@ describe("executeThread", () => {
           awaitAfterEachYield: async () => {},
           forkSourceThreadId: null,
           prefilledDiskSteps: null,
+          storageRoot: root,
         },
         { threadId, hash, dataJsonlPath: dataPath, infoJsonlPath: infoPath, cas },
         logger,
@@ -258,6 +266,7 @@ describe("executeThread", () => {
       const dataPath = join(root, "logs", hash, `${threadId}.data.jsonl`);
       const infoPath = join(root, "logs", hash, `${threadId}.info.jsonl`);
       await mkdir(join(root, "logs", hash), { recursive: true });
+      await writeExtractRegistryConfig(root);
       const cas = createCasStore(join(root, "cas"));
       const plannerHash = await cas.put(serializeMerkleNode(createContentMerkleNode("plan-body")));
 
@@ -295,6 +304,7 @@ describe("executeThread", () => {
               timestamp: histTs,
             },
           ],
+          storageRoot: root,
         },
         { threadId, hash, dataJsonlPath: dataPath, infoJsonlPath: infoPath, cas },
         logger,
@@ -354,6 +364,7 @@ describe("executeThread", () => {
           awaitAfterEachYield: async () => {},
           forkSourceThreadId: null,
           prefilledDiskSteps: null,
+          storageRoot: root,
         },
         { threadId, hash, dataJsonlPath: dataPath, infoJsonlPath: infoPath, cas },
         logger,
@@ -391,6 +402,7 @@ describe("executeThread", () => {
       const dataPath = join(root, "logs", hash, `${threadId}.data.jsonl`);
       const infoPath = join(root, "logs", hash, `${threadId}.info.jsonl`);
       await mkdir(join(root, "logs", hash), { recursive: true });
+      await writeExtractRegistryConfig(root);
       const cas = createCasStore(join(root, "cas"));
 
       const logger = createLogger({ sink: { kind: "file", path: infoPath } });
@@ -407,6 +419,7 @@ describe("executeThread", () => {
           awaitAfterEachYield: async () => {},
           forkSourceThreadId: null,
           prefilledDiskSteps: null,
+          storageRoot: root,
         },
         { threadId, hash, dataJsonlPath: dataPath, infoJsonlPath: infoPath, cas },
         logger,
@@ -549,9 +562,6 @@ describe("executeThread", () => {
         { preconnect: origFetch.preconnect.bind(origFetch) },
       ) as typeof fetch;
 
-      const llm: LlmProvider = { baseUrl: "http://127.0.0.1:9", apiKey: "test", model: "test" };
-      const extractFn = createExtract(llm);
-
       const dagWorkflow = createWorkflow<DagDemoMeta>(
         {
           roles: {
@@ -568,8 +578,6 @@ describe("executeThread", () => {
           moderator: (ctx) => (ctx.steps.length === 0 ? "walker" : END),
         },
         { agent: async () => dagRootHash },
-        extractFn,
-        llm,
       );
 
       const threadId = "01KQXKW18CT8G75T53R8F4G7YG";
@@ -577,6 +585,7 @@ describe("executeThread", () => {
       const dataPath = join(root, "logs", hash, `${threadId}.data.jsonl`);
       const infoPath = join(root, "logs", hash, `${threadId}.info.jsonl`);
       await mkdir(join(root, "logs", hash), { recursive: true });
+      await writeExtractRegistryConfig(root);
 
       const logger = createLogger({ sink: { kind: "file", path: infoPath } });
       const ac = new AbortController();
@@ -592,6 +601,7 @@ describe("executeThread", () => {
           awaitAfterEachYield: async () => {},
           forkSourceThreadId: null,
           prefilledDiskSteps: null,
+          storageRoot: root,
         },
         { threadId, hash, dataJsonlPath: dataPath, infoJsonlPath: infoPath, cas },
         logger,

packages/workflow/__tests__/extract-provider.test.ts

@@ -1,87 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-
-import { getExtractProvider } from "../src/extract-provider.js";
-
-describe("getExtractProvider", () => {
-  test("returns provider when config.extract is present", async () => {
-    const root = await mkdtemp(join(tmpdir(), "wf-ext-prov-ok-"));
-    try {
-      await mkdir(root, { recursive: true });
-      await writeFile(
-        join(root, "workflow.yaml"),
-        `config:
-  maxDepth: 3
-  extract:
-    baseUrl: https://dashscope.aliyuncs.com/compatible-mode/v1
-    model: qwen-plus
-    apiKey: literal-key
-workflows: {}
-`,
-        "utf8",
-      );
-      const r = await getExtractProvider(root);
-      expect(r.ok).toBe(true);
-      if (!r.ok) {
-        return;
-      }
-      expect(r.value.baseUrl).toBe("https://dashscope.aliyuncs.com/compatible-mode/v1");
-      expect(r.value.model).toBe("qwen-plus");
-      expect(r.value.apiKey).toBe("literal-key");
-    } finally {
-      await rm(root, { recursive: true, force: true });
-    }
-  });
-
-  test("errs when registry has no config section", async () => {
-    const root = await mkdtemp(join(tmpdir(), "wf-ext-prov-missing-"));
-    try {
-      await mkdir(root, { recursive: true });
-      await writeFile(join(root, "workflow.yaml"), "workflows: {}\n", "utf8");
-      const r = await getExtractProvider(root);
-      expect(r.ok).toBe(false);
-      if (r.ok) {
-        return;
-      }
-      expect(r.error).toContain("no global config");
-    } finally {
-      await rm(root, { recursive: true, force: true });
-    }
-  });
-
-  test("resolves apiKey from env at registry read time", async () => {
-    const root = await mkdtemp(join(tmpdir(), "wf-ext-prov-env-"));
-    const prev = process.env.WF_GET_EXTRACT_PROVIDER_KEY;
-    process.env.WF_GET_EXTRACT_PROVIDER_KEY = "resolved-secret";
-    try {
-      await mkdir(root, { recursive: true });
-      await writeFile(
-        join(root, "workflow.yaml"),
-        `config:
-  maxDepth: 1
-  extract:
-    baseUrl: https://example.com
-    model: m
-    apiKey: env:WF_GET_EXTRACT_PROVIDER_KEY
-workflows: {}
-`,
-        "utf8",
-      );
-      const r = await getExtractProvider(root);
-      expect(r.ok).toBe(true);
-      if (!r.ok) {
-        return;
-      }
-      expect(r.value.apiKey).toBe("resolved-secret");
-    } finally {
-      if (prev === undefined) {
-        delete process.env.WF_GET_EXTRACT_PROVIDER_KEY;
-      } else {
-        process.env.WF_GET_EXTRACT_PROVIDER_KEY = prev;
-      }
-      await rm(root, { recursive: true, force: true });
-    }
-  });
-});

packages/workflow/__tests__/refs-tracking.test.ts

@@ -1,5 +1,5 @@
 import { afterEach, describe, expect, test } from "bun:test";
-import { mkdir, mkdtemp, readFile, rm } from "node:fs/promises";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import * as z from "zod/v4";
@@ -8,7 +8,6 @@ import { createCasStore } from "../src/cas/cas.js";
 import { createWorkflow } from "../src/engine/create-workflow.js";
 import { executeThread } from "../src/engine/engine.js";
 import { buildForkPlan, parseThreadDataJsonl } from "../src/engine/fork-thread.js";
-import { createExtract } from "../src/extract/extract-fn.js";
 import { END } from "../src/types.js";
 import { createLogger } from "../src/util/logger.js";
 
@@ -76,11 +75,16 @@ function installMockChatCompletions(sequence: ReadonlyArray<Record<string, unkno
   };
 }
 
-const refsDemoExtract = createExtract({
-  baseUrl: "http://127.0.0.1:9",
-  apiKey: "test",
-  model: "test",
-});
+const EXTRACT_REGISTRY_YAML = `config:
+  maxDepth: 3
+  providers:
+    stub:
+      baseUrl: http://127.0.0.1:9
+      apiKey: test
+  models:
+    default: stub/model
+workflows: {}
+`;
 
 const refsDemoWorkflow = createWorkflow<RefsDemoMeta>(
   {
@@ -99,8 +103,6 @@ const refsDemoWorkflow = createWorkflow<RefsDemoMeta>(
   {
     agent: async () => "plan-output",
   },
-  refsDemoExtract,
-  null,
 );
 
 describe("RoleStep refs tracking", () => {
@@ -142,6 +144,7 @@ describe("RoleStep refs tracking", () => {
       const dataPath = join(root, "logs", hash, `${threadId}.data.jsonl`);
       const infoPath = join(root, "logs", hash, `${threadId}.info.jsonl`);
       await mkdir(join(root, "logs", hash), { recursive: true });
+      await writeFile(join(root, "workflow.yaml"), EXTRACT_REGISTRY_YAML, "utf8");
       const cas = createCasStore(join(root, "cas"));
 
       const logger = createLogger({ sink: { kind: "file", path: infoPath } });
@@ -158,6 +161,7 @@ describe("RoleStep refs tracking", () => {
           awaitAfterEachYield: async () => {},
           forkSourceThreadId: null,
           prefilledDiskSteps: null,
+          storageRoot: root,
         },
         { threadId, hash, dataJsonlPath: dataPath, infoJsonlPath: infoPath, cas },
         logger,

packages/workflow/__tests__/registry.test.ts

@@ -105,10 +105,13 @@ describe("workflow registry", () => {
     const yaml = `
 config:
   maxDepth: 3
-  extract:
-    baseUrl: https://example.com/v1
-    model: qwen-plus
-    apiKey: secret-key
+  providers:
+    dashscope:
+      baseUrl: https://example.com/v1
+      apiKey: secret-key
+  models:
+    default: dashscope/qwen-turbo
+    extract: dashscope/qwen-plus
 workflows:
   solve-issue:
     hash: SPVR4BDMSGC1W
@@ -125,9 +128,10 @@ workflows:
       return;
     }
     expect(r.value.config.maxDepth).toBe(3);
-    expect(r.value.config.extract.baseUrl).toBe("https://example.com/v1");
-    expect(r.value.config.extract.model).toBe("qwen-plus");
-    expect(r.value.config.extract.apiKey).toBe("secret-key");
+    expect(r.value.config.providers.dashscope?.baseUrl).toBe("https://example.com/v1");
+    expect(r.value.config.providers.dashscope?.apiKey).toBe("secret-key");
+    expect(r.value.config.models.extract).toBe("dashscope/qwen-plus");
+    expect(r.value.config.models.default).toBe("dashscope/qwen-turbo");
   });
 
   test("parses config apiKey env: prefix from process.env", () => {
@@ -137,10 +141,13 @@ workflows:
       const yaml = `
 config:
   maxDepth: 1
-  extract:
-    baseUrl: https://dashscope.aliyuncs.com/compatible-mode/v1
-    model: qwen-plus
-    apiKey: env:WF_REGISTRY_TEST_API_KEY
+  providers:
+    dashscope:
+      baseUrl: https://dashscope.aliyuncs.com/compatible-mode/v1
+      apiKey: env:WF_REGISTRY_TEST_API_KEY
+  models:
+    default: dashscope/qwen-plus
+    extract: dashscope/qwen-plus
 workflows: {}
 `;
       const r = parseWorkflowRegistryYaml(yaml);
@@ -148,7 +155,7 @@ workflows: {}
       if (!r.ok) {
         return;
       }
-      expect(r.value.config?.extract.apiKey).toBe("from-env");
+      expect(r.value.config?.providers.dashscope?.apiKey).toBe("from-env");
     } finally {
       if (prev === undefined) {
         delete process.env.WF_REGISTRY_TEST_API_KEY;
@@ -165,10 +172,12 @@ workflows: {}
       const yaml = `
 config:
   maxDepth: 1
-  extract:
-    baseUrl: https://example.com
-    model: m
-    apiKey: env:WF_REGISTRY_TEST_API_KEY_UNSET
+  providers:
+    p:
+      baseUrl: https://example.com
+      apiKey: env:WF_REGISTRY_TEST_API_KEY_UNSET
+  models:
+    default: p/m
 workflows: {}
 `;
       const r = parseWorkflowRegistryYaml(yaml);

packages/workflow/__tests__/resolve-model.test.ts

@@ -0,0 +1,100 @@
+import { describe, expect, test } from "bun:test";
+
+import { resolveModel } from "../src/config/resolve-model.js";
+import type { WorkflowConfig } from "../src/registry/index.js";
+
+function sampleConfig(): WorkflowConfig {
+  return {
+    maxDepth: 3,
+    providers: {
+      dashscope: {
+        baseUrl: "https://dashscope.aliyuncs.com/compatible-mode/v1",
+        apiKey: "secret",
+      },
+      other: {
+        baseUrl: "https://other.example/v1",
+        apiKey: "k2",
+      },
+    },
+    models: {
+      default: "dashscope/qwen-plus",
+      extract: "other/foo/bar-model",
+    },
+  };
+}
+
+describe("resolveModel", () => {
+  test("uses explicit scene mapping", () => {
+    const config = sampleConfig();
+    const r = resolveModel(config, "extract");
+    expect(r.ok).toBe(true);
+    if (!r.ok) {
+      return;
+    }
+    expect(r.value.baseUrl).toBe("https://other.example/v1");
+    expect(r.value.apiKey).toBe("k2");
+    expect(r.value.model).toBe("foo/bar-model");
+  });
+
+  test("falls back to models.default when scene is missing", () => {
+    const config = sampleConfig();
+    const r = resolveModel(config, "unknown-scene");
+    expect(r.ok).toBe(true);
+    if (!r.ok) {
+      return;
+    }
+    expect(r.value.model).toBe("qwen-plus");
+    expect(r.value.baseUrl).toBe("https://dashscope.aliyuncs.com/compatible-mode/v1");
+  });
+
+  test("errs when scene missing and no default", () => {
+    const config: WorkflowConfig = {
+      maxDepth: 1,
+      providers: {
+        p: { baseUrl: "https://x", apiKey: "k" },
+      },
+      models: {
+        extract: "p/m",
+      },
+    };
+    const r = resolveModel(config, "other");
+    expect(r.ok).toBe(false);
+    if (r.ok) {
+      return;
+    }
+    expect(r.error).toContain("no model mapping");
+    expect(r.error).toContain("default");
+  });
+
+  test("errs when provider is unknown", () => {
+    const config: WorkflowConfig = {
+      maxDepth: 1,
+      providers: {
+        p: { baseUrl: "https://x", apiKey: "k" },
+      },
+      models: {
+        default: "missing/m",
+      },
+    };
+    const r = resolveModel(config, "any");
+    expect(r.ok).toBe(false);
+    if (r.ok) {
+      return;
+    }
+    expect(r.error).toContain("unknown provider");
+  });
+
+  test("errs on invalid model reference shape", () => {
+    const config: WorkflowConfig = {
+      maxDepth: 1,
+      providers: {
+        p: { baseUrl: "https://x", apiKey: "k" },
+      },
+      models: {
+        default: "no-slash-model",
+      },
+    };
+    const r = resolveModel(config, "x");
+    expect(r.ok).toBe(false);
+  });
+});

packages/workflow/__tests__/worker.test.ts

@@ -9,6 +9,17 @@ import { createCasStore } from "../src/cas/cas.js";
 import { createContentMerkleNode, serializeMerkleNode } from "../src/cas/merkle.js";
 import { getWorkerHostScriptPath } from "../src/engine/worker-entry-path.js";
 
+const WORKER_REGISTRY_YAML = `config:
+  maxDepth: 3
+  providers:
+    stub:
+      baseUrl: http://127.0.0.1:9
+      apiKey: test
+  models:
+    default: stub/model
+workflows: {}
+`;
+
 const bundleSource = `import { putContentMerkleNode } from "@uncaged/workflow";
 
 export const descriptor = {
@@ -89,6 +100,7 @@ describe("worker process", () => {
     try {
       const hash = "C9NMV6V2TQT81";
       await mkdir(join(root, "bundles"), { recursive: true });
+      await writeFile(join(root, "workflow.yaml"), WORKER_REGISTRY_YAML, "utf8");
       const bundlePath = join(root, "bundles", `${hash}.esm.js`);
       await writeFile(bundlePath, bundleSource, "utf8");
 
@@ -136,6 +148,7 @@ describe("worker process", () => {
     try {
       const hash = "C9NMV6V2TQT81";
       await mkdir(join(root, "bundles"), { recursive: true });
+      await writeFile(join(root, "workflow.yaml"), WORKER_REGISTRY_YAML, "utf8");
       const bundlePath = join(root, "bundles", `${hash}.esm.js`);
       await writeFile(bundlePath, bundleSource, "utf8");
 

packages/workflow/__tests__/workflow-as-agent-integration.test.ts

@@ -9,7 +9,6 @@ import { hashWorkflowBundleBytes } from "../src/cas/hash.js";
 import { getContentMerklePayload, parseMerkleNode } from "../src/cas/merkle.js";
 import { createWorkflow } from "../src/engine/create-workflow.js";
 import { executeThread } from "../src/engine/engine.js";
-import { createExtract } from "../src/extract/extract-fn.js";
 import {
   readWorkflowRegistry,
   registerWorkflowVersion,
@@ -76,11 +75,16 @@ function installMockChatCompletions(sequence: ReadonlyArray<Record<string, unkno
   };
 }
 
-const parentExtract = createExtract({
-  baseUrl: "http://127.0.0.1:9",
-  apiKey: "test",
-  model: "test",
-});
+const PARENT_REGISTRY_WITH_CONFIG = `config:
+  maxDepth: 3
+  providers:
+    stub:
+      baseUrl: http://127.0.0.1:9
+      apiKey: test
+  models:
+    default: stub/m
+workflows: {}
+`;
 
 const childBundleSource = `import { putContentMerkleNode } from "@uncaged/workflow";
 
@@ -131,6 +135,8 @@ describe("workflowAsAgent integration", () => {
 
     const root = await mkdtemp(join(tmpdir(), "wf-waa-int-"));
     try {
+      await mkdir(root, { recursive: true });
+      await writeFile(join(root, "workflow.yaml"), PARENT_REGISTRY_WITH_CONFIG, "utf8");
       const { hash: childHash } = await installChildWorkflow(root);
 
       const parentWorkflow = createWorkflow<ParentMeta>(
@@ -148,8 +154,6 @@ describe("workflowAsAgent integration", () => {
           moderator: (ctx) => (ctx.steps.length === 0 ? "caller" : END),
         },
         { agent: workflowAsAgent("child-wf", { storageRoot: root }) },
-        parentExtract,
-        null,
       );
 
       const threadId = "01KQXKW18CT8G75T53R8F4G7YG";
@@ -173,6 +177,7 @@ describe("workflowAsAgent integration", () => {
           awaitAfterEachYield: async () => {},
           forkSourceThreadId: null,
           prefilledDiskSteps: null,
+          storageRoot: root,
         },
         { threadId, hash: parentHash, dataJsonlPath: dataPath, infoJsonlPath: infoPath, cas },
         logger,

packages/workflow/__tests__/workflow-as-agent.test.ts

@@ -93,6 +93,21 @@ describe("workflowAsAgent", () => {
   test("runs registered workflow and returns child thread root CAS hash", async () => {
     const root = await mkdtemp(join(tmpdir(), "wf-waa-ok-"));
     try {
+      await mkdir(root, { recursive: true });
+      await writeFile(
+        join(root, "workflow.yaml"),
+        `config:
+  maxDepth: 3
+  providers:
+    stub:
+      baseUrl: http://127.0.0.1:9
+      apiKey: test
+  models:
+    default: stub/m
+workflows: {}
+`,
+        "utf8",
+      );
       await installChildWorkflow(root);
       const agent = workflowAsAgent("child-wf", { storageRoot: root });
       const out = await agent(
@@ -140,10 +155,15 @@ describe("workflowAsAgent", () => {
         ...reg.value,
         config: {
           maxDepth: 2,
-          extract: {
-            baseUrl: "http://127.0.0.1:9",
-            model: "m",
-            apiKey: "k",
+          providers: {
+            local: {
+              baseUrl: "http://127.0.0.1:9",
+              apiKey: "k",
+            },
+          },
+          models: {
+            default: "local/m",
+            extract: "local/m",
           },
         },
       };

packages/workflow/src/config/index.ts

@@ -0,0 +1,3 @@
+export { resolveModel } from "./resolve-model.js";
+export { splitProviderModelRef } from "./split-provider-model-ref.js";
+export type { ProviderConfig, ResolvedModel } from "./types.js";

packages/workflow/src/config/resolve-model.ts

@@ -0,0 +1,30 @@
+import type { WorkflowConfig } from "../registry/index.js";
+import { err, ok, type Result } from "../util/index.js";
+import { splitProviderModelRef } from "./split-provider-model-ref.js";
+import type { ResolvedModel } from "./types.js";
+
+/** Resolves scene → provider endpoint + model using {@link WorkflowConfig.providers} and {@link WorkflowConfig.models}. */
+export function resolveModel(config: WorkflowConfig, scene: string): Result<ResolvedModel, string> {
+  const models = config.models;
+  let ref = models[scene] ?? null;
+  if (ref === null) {
+    ref = models.default ?? null;
+  }
+  if (ref === null) {
+    return err(`no model mapping for scene "${scene}" and no models.default fallback`);
+  }
+  const split = splitProviderModelRef(ref);
+  if (!split.ok) {
+    return split;
+  }
+  const { providerName, modelName } = split.value;
+  const provider = config.providers[providerName] ?? null;
+  if (provider === null) {
+    return err(`unknown provider "${providerName}" referenced by scene "${scene}"`);
+  }
+  return ok({
+    baseUrl: provider.baseUrl,
+    apiKey: provider.apiKey,
+    model: modelName,
+  });
+}

packages/workflow/src/config/split-provider-model-ref.ts

@@ -0,0 +1,17 @@
+import { err, ok, type Result } from "../util/index.js";
+
+/** Parses `providerName/modelName` references used in {@link WorkflowConfig.models}. */
+export function splitProviderModelRef(
+  ref: string,
+): Result<{ providerName: string; modelName: string }, string> {
+  const idx = ref.indexOf("/");
+  if (idx <= 0 || idx === ref.length - 1) {
+    return err(`invalid model reference "${ref}": expected providerName/modelName`);
+  }
+  const providerName = ref.slice(0, idx);
+  const modelName = ref.slice(idx + 1);
+  if (providerName === "" || modelName === "") {
+    return err(`invalid model reference "${ref}": expected providerName/modelName`);
+  }
+  return ok({ providerName, modelName });
+}

packages/workflow/src/config/types.ts

@@ -0,0 +1,10 @@
+export type ProviderConfig = {
+  baseUrl: string;
+  apiKey: string;
+};
+
+export type ResolvedModel = {
+  baseUrl: string;
+  apiKey: string;
+  model: string;
+};

packages/workflow/src/engine/create-workflow.ts

@@ -1,12 +1,10 @@
-import type { CasStore } from "../cas/index.js";
 import { putContentMerkleNode } from "../cas/index.js";
-import { buildExtractUserContent, type ExtractFn, reactExtract } from "../extract/index.js";
+import { buildExtractUserContent, reactExtract } from "../extract/index.js";
 import {
   type AgentBinding,
   type AgentContext,
   END,
   type ExtractContext,
-  type LlmProvider,
   type ModeratorContext,
   type RoleDefinition,
   type RoleMeta,
@@ -41,14 +39,12 @@ function resolveExtractedRefs(
 async function resolveRoleMeta<M extends RoleMeta>(
   roleDef: RoleDefinition<Record<string, unknown>>,
   extractCtx: ExtractContext<M>,
-  extract: ExtractFn,
-  llmProvider: LlmProvider | null,
-  cas: CasStore,
+  options: WorkflowFnOptions,
 ): Promise<Record<string, unknown>> {
   if (roleDef.extractMode === "react") {
-    if (llmProvider === null) {
+    if (options.llmProvider === null) {
       throw new Error(
-        'createWorkflow: llmProvider is required when a role uses extractMode "react"',
+        'createWorkflow: WorkflowFnOptions.llmProvider is required when a role uses extractMode "react"',
       );
     }
     const text = await buildExtractUserContent(
@@ -58,15 +54,15 @@ async function resolveRoleMeta<M extends RoleMeta>(
     const reactResult = await reactExtract({
       text,
       schema: roleDef.schema,
-      provider: llmProvider,
-      cas,
+      provider: options.llmProvider,
+      cas: options.cas,
     });
     if (!reactResult.ok) {
       throw new Error(`react extract failed: ${reactResult.error}`);
     }
     return reactResult.value as Record<string, unknown>;
   }
-  return (await extract(
+  return (await options.extract(
     roleDef.schema,
     roleDef.extractPrompt,
     extractCtx as unknown as ExtractContext,
@@ -74,15 +70,13 @@ async function resolveRoleMeta<M extends RoleMeta>(
 }
 
 /**
- * Binds pure role definitions + moderator to runtime agents and structured extraction.
- * Assign with `export const run = createWorkflow(def, binding, extract, llmProvider)`.
- * Pass the same {@link LlmProvider} as {@link createExtract} when any role uses `extractMode: "react"`.
+ * Binds pure role definitions + moderator to runtime agents.
+ * Assign with `export const run = createWorkflow(def, binding)`.
+ * The engine supplies {@link WorkflowFnOptions.extract} and {@link WorkflowFnOptions.llmProvider} from workflow.yaml.
  */
 export function createWorkflow<M extends RoleMeta>(
   def: Pick<WorkflowDefinition<M>, "roles" | "moderator">,
   binding: AgentBinding,
-  extract: ExtractFn,
-  llmProvider: LlmProvider | null,
 ): WorkflowFn {
   return async function* workflowLoop(
     input: ThreadInput,
@@ -149,9 +143,7 @@ export function createWorkflow<M extends RoleMeta>(
       const meta = await resolveRoleMeta(
         roleDef as unknown as RoleDefinition<Record<string, unknown>>,
         extractCtx,
-        extract,
-        llmProvider,
-        options.cas,
+        options,
       );
 
       const contentHash = await putContentMerkleNode(options.cas, raw);

packages/workflow/src/engine/engine.ts

@@ -7,17 +7,47 @@ import {
   putStepMerkleNode,
   putThreadMerkleNode,
 } from "../cas/index.js";
+import { resolveModel } from "../config/index.js";
+import { createExtract } from "../extract/index.js";
+import { readWorkflowRegistry } from "../registry/index.js";
 import type {
+  LlmProvider,
   ThreadInput,
   WorkflowCompletion,
   WorkflowFn,
   WorkflowFnOptions,
   WorkflowResult,
 } from "../types.js";
-import { type LogFn, normalizeRefsField } from "../util/index.js";
+import { err, type LogFn, normalizeRefsField, ok, type Result } from "../util/index.js";
 
 import type { ExecuteThreadIo, ExecuteThreadOptions } from "./types.js";
 
+async function resolveExtractRuntime(
+  storageRoot: string,
+): Promise<
+  Result<{ extract: ReturnType<typeof createExtract>; llmProvider: LlmProvider }, string>
+> {
+  const reg = await readWorkflowRegistry(storageRoot);
+  if (!reg.ok) {
+    return err(reg.error.message);
+  }
+  const cfg = reg.value.config;
+  if (cfg === null) {
+    return err("workflow registry has no global config section");
+  }
+  const resolved = resolveModel(cfg, "extract");
+  if (!resolved.ok) {
+    return resolved;
+  }
+  const ex = resolved.value;
+  const llmProvider: LlmProvider = {
+    baseUrl: ex.baseUrl,
+    apiKey: ex.apiKey,
+    model: ex.model,
+  };
+  return ok({ extract: createExtract(llmProvider), llmProvider });
+}
+
 async function appendDataLine(path: string, record: unknown): Promise<void> {
   const line = `${JSON.stringify(record)}\n`;
   await appendFile(path, line, "utf8");
@@ -250,11 +280,18 @@ export async function executeThread(
     });
   }
 
+  const extractRuntime = await resolveExtractRuntime(options.storageRoot);
+  if (!extractRuntime.ok) {
+    throw new Error(extractRuntime.error);
+  }
+
   const bundleOptions: WorkflowFnOptions = {
     threadId: io.threadId,
     maxRounds: options.maxRounds,
     depth: options.depth,
     cas: io.cas,
+    extract: extractRuntime.value.extract,
+    llmProvider: extractRuntime.value.llmProvider,
   };
 
   return await driveWorkflowGenerator({

packages/workflow/src/engine/types.ts

@@ -33,6 +33,8 @@ export type ExecuteThreadOptions = {
    * Must match `input.steps` length and order when present.
    */
   prefilledDiskSteps: PrefilledDiskStep[] | null;
+  /** Workspace root containing `workflow.yaml`; used to resolve the `extract` scene for meta extraction. */
+  storageRoot: string;
 };
 
 /** Role steps replayed from `.data.jsonl`, including persisted timestamps. */

packages/workflow/src/engine/worker.ts

@@ -417,6 +417,7 @@ async function main(): Promise<void> {
           awaitAfterEachYield: () => pauseGate.awaitAfterYield(),
           forkSourceThreadId: cmd.forkSourceThreadId,
           prefilledDiskSteps,
+          storageRoot,
         },
         io,
         logger,

packages/workflow/src/extract-provider.ts

@@ -1,34 +0,0 @@
-import type { WorkflowConfig } from "./registry/index.js";
-import { readWorkflowRegistry } from "./registry/index.js";
-import type { LlmProvider } from "./types.js";
-import { err, getDefaultWorkflowStorageRoot, ok, type Result } from "./util/index.js";
-
-const DEFAULT_WORKFLOW_AS_AGENT_MAX_DEPTH = 3;
-
-export function getWorkflowAsAgentMaxDepth(config: WorkflowConfig | null): number {
-  if (config === null) {
-    return DEFAULT_WORKFLOW_AS_AGENT_MAX_DEPTH;
-  }
-  return config.maxDepth;
-}
-
-/** Loads `config.extract` from workflow.yaml (apiKey already resolved at registry parse time). */
-export async function getExtractProvider(
-  storageRoot: string | undefined,
-): Promise<Result<LlmProvider, string>> {
-  const root = storageRoot ?? getDefaultWorkflowStorageRoot();
-  const regResult = await readWorkflowRegistry(root);
-  if (!regResult.ok) {
-    return err(regResult.error.message);
-  }
-  const cfg = regResult.value.config;
-  if (cfg === null) {
-    return err("workflow registry has no global config section");
-  }
-  const ex = cfg.extract;
-  return ok({
-    baseUrl: ex.baseUrl,
-    apiKey: ex.apiKey,
-    model: ex.model,
-  });
-}

packages/workflow/src/index.ts

@@ -28,6 +28,11 @@ export {
   serializeMerkleNode,
   type ThreadMerklePayload,
 } from "./cas/index.js";
+export {
+  type ProviderConfig,
+  type ResolvedModel,
+  resolveModel,
+} from "./config/index.js";
 export {
   buildForkPlan,
   createThreadPauseGate,
@@ -58,9 +63,7 @@ export {
   type ReactExtractArgs,
   reactExtract,
 } from "./extract/index.js";
-export { getExtractProvider } from "./extract-provider.js";
 export {
-  type ExtractProviderConfig,
   getRegisteredWorkflow,
   listRegisteredWorkflowNames,
   parseWorkflowRegistryYaml,

packages/workflow/src/registry/index.ts

@@ -11,7 +11,6 @@ export {
   writeWorkflowRegistry,
 } from "./registry.js";
 export type {
-  ExtractProviderConfig,
   WorkflowConfig,
   WorkflowHistoryEntry,
   WorkflowRegistryEntry,

packages/workflow/src/registry/registry-normalize.ts

@@ -1,49 +1,107 @@
-import { err, ok, type Result } from "../util/index.js";
+import { type ProviderConfig, splitProviderModelRef } from "../config/index.js";
+import { createLogger, err, ok, type Result } from "../util/index.js";
 import type {
-  ExtractProviderConfig,
   WorkflowConfig,
   WorkflowHistoryEntry,
   WorkflowRegistryEntry,
   WorkflowRegistryFile,
 } from "./types.js";
 
-function resolveRegistryApiKey(raw: string): Result<string, Error> {
+const registryNormalizeLog = createLogger({ sink: { kind: "stderr" } });
+
+function resolveRegistryApiKey(raw: string, ctx: string): Result<string, Error> {
   if (raw.startsWith("env:")) {
     const name = raw.slice("env:".length);
     if (name === "") {
-      return err(new Error('config.extract.apiKey "env:" reference must name a variable'));
+      return err(new Error(`${ctx}: "env:" apiKey reference must name a variable`));
     }
     const value = process.env[name];
     if (value === undefined) {
-      return err(new Error(`config.extract.apiKey: environment variable "${name}" is not set`));
+      return err(new Error(`${ctx}: environment variable "${name}" is not set`));
     }
     return ok(value);
   }
   return ok(raw);
 }
 
-function normalizeExtractProviderConfig(raw: unknown): Result<ExtractProviderConfig, Error> {
-  if (raw === null || typeof raw !== "object") {
-    return err(new Error('registry config must contain an "extract" mapping'));
+function normalizeProviderEntry(name: string, entryRaw: unknown): Result<ProviderConfig, Error> {
+  if (name === "") {
+    return err(new Error("config.providers must not contain an empty provider name"));
   }
-  const e = raw as Record<string, unknown>;
+  if (entryRaw === null || typeof entryRaw !== "object" || Array.isArray(entryRaw)) {
+    return err(new Error(`config.providers.${name} must be a mapping`));
+  }
+  const e = entryRaw as Record<string, unknown>;
   const baseUrl = e.baseUrl;
-  const model = e.model;
   const apiKeyRaw = e.apiKey;
   if (typeof baseUrl !== "string" || baseUrl === "") {
-    return err(new Error("config.extract.baseUrl must be a non-empty string"));
-  }
-  if (typeof model !== "string" || model === "") {
-    return err(new Error("config.extract.model must be a non-empty string"));
+    return err(new Error(`config.providers.${name}.baseUrl must be a non-empty string`));
   }
   if (typeof apiKeyRaw !== "string" || apiKeyRaw === "") {
-    return err(new Error("config.extract.apiKey must be a non-empty string"));
+    return err(new Error(`config.providers.${name}.apiKey must be a non-empty string`));
   }
-  const apiKeyResult = resolveRegistryApiKey(apiKeyRaw);
+  const apiKeyCtx = `config.providers.${name}.apiKey`;
+  const apiKeyResult = resolveRegistryApiKey(apiKeyRaw, apiKeyCtx);
   if (!apiKeyResult.ok) {
     return apiKeyResult;
   }
-  return ok({ baseUrl, model, apiKey: apiKeyResult.value });
+  return ok({ baseUrl, apiKey: apiKeyResult.value });
+}
+
+function normalizeProviders(raw: unknown): Result<Record<string, ProviderConfig>, Error> {
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+    return err(new Error('registry config must contain a "providers" mapping'));
+  }
+  const root = raw as Record<string, unknown>;
+  const providers: Record<string, ProviderConfig> = {};
+  for (const [name, entryRaw] of Object.entries(root)) {
+    const next = normalizeProviderEntry(name, entryRaw);
+    if (!next.ok) {
+      return next;
+    }
+    providers[name] = next.value;
+  }
+  return ok(providers);
+}
+
+function normalizeModels(
+  raw: unknown,
+  providers: Record<string, ProviderConfig>,
+): Result<Record<string, string>, Error> {
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+    return err(new Error('registry config must contain a "models" mapping'));
+  }
+  const root = raw as Record<string, unknown>;
+  const models: Record<string, string> = {};
+  const providerKeys = new Set(Object.keys(providers));
+  for (const [scene, refRaw] of Object.entries(root)) {
+    if (scene === "") {
+      return err(new Error("config.models must not contain an empty scene name"));
+    }
+    if (typeof refRaw !== "string" || refRaw === "") {
+      return err(new Error(`config.models.${scene} must be a non-empty string (provider/model)`));
+    }
+    const ctx = `config.models.${scene}`;
+    const parsed = splitProviderModelRef(refRaw);
+    if (!parsed.ok) {
+      return err(new Error(`${ctx}: ${parsed.error}`));
+    }
+    if (!providerKeys.has(parsed.value.providerName)) {
+      return err(
+        new Error(
+          `${ctx}: unknown provider "${parsed.value.providerName}" (not listed under config.providers)`,
+        ),
+      );
+    }
+    models[scene] = refRaw;
+  }
+  if (!Object.hasOwn(models, "default")) {
+    registryNormalizeLog(
+      "Z2KP9NWQ",
+      'registry config: models mapping has no "default" key; scenes without explicit model mappings may fail at resolveModel',
+    );
+  }
+  return ok(models);
 }
 
 function normalizeWorkflowConfig(raw: unknown): Result<WorkflowConfig, Error> {
@@ -52,15 +110,24 @@ function normalizeWorkflowConfig(raw: unknown): Result<WorkflowConfig, Error> {
   }
   const c = raw as Record<string, unknown>;
   const maxDepth = c.maxDepth;
-  const extractRaw = c.extract;
+  const providersRaw = c.providers;
+  const modelsRaw = c.models;
   if (typeof maxDepth !== "number" || !Number.isInteger(maxDepth) || maxDepth < 0) {
     return err(new Error("config.maxDepth must be a non-negative integer"));
   }
-  const extractResult = normalizeExtractProviderConfig(extractRaw);
-  if (!extractResult.ok) {
-    return extractResult;
+  const providersResult = normalizeProviders(providersRaw);
+  if (!providersResult.ok) {
+    return providersResult;
   }
-  return ok({ maxDepth, extract: extractResult.value });
+  const modelsResult = normalizeModels(modelsRaw, providersResult.value);
+  if (!modelsResult.ok) {
+    return modelsResult;
+  }
+  return ok({
+    maxDepth,
+    providers: providersResult.value,
+    models: modelsResult.value,
+  });
 }
 
 export function normalizeWorkflowHistoryEntry(

packages/workflow/src/registry/types.ts

@@ -1,3 +1,5 @@
+import type { ProviderConfig } from "../config/index.js";
+
 export type WorkflowHistoryEntry = {
   hash: string;
   timestamp: number;
@@ -9,16 +11,10 @@ export type WorkflowRegistryEntry = {
   history: WorkflowHistoryEntry[];
 };
 
-/** LLM provider settings under `config.extract` in workflow.yaml (apiKey resolved after parse). */
-export type ExtractProviderConfig = {
-  baseUrl: string;
-  model: string;
-  apiKey: string;
-};
-
 export type WorkflowConfig = {
   maxDepth: number;
-  extract: ExtractProviderConfig;
+  providers: Record<string, ProviderConfig>;
+  models: Record<string, string>;
 };
 
 export type WorkflowRegistryFile = {

packages/workflow/src/types.ts

@@ -1,6 +1,7 @@
 import type * as z from "zod/v4";
 
 import type { CasStore } from "./cas/index.js";
+import type { ExtractFn } from "./extract/types.js";
 
 /** Sentinel values for automaton control flow. */
 export const START = "__start__" as const;
@@ -54,6 +55,10 @@ export type WorkflowFnOptions = {
   depth: number;
   /** Global CAS store for Merkle content blobs (role step bodies). */
   cas: CasStore;
+  /** Structured meta extraction; resolved from workflow.yaml `extract` scene by the engine. */
+  extract: ExtractFn;
+  /** Provider for `extractMode: "react"` roles; same backing config as `extract`. */
+  llmProvider: LlmProvider | null;
 };
 
 /** Bundle contract — named export `run` is a function returning an AsyncGenerator. */

packages/workflow/src/workflow-as-agent.ts

@@ -4,7 +4,7 @@ import { extractBundleExports } from "./bundle/index.js";
 import { createCasStore } from "./cas/index.js";
 import type { ExecuteThreadIo } from "./engine/index.js";
 import { executeThread } from "./engine/index.js";
-import { getWorkflowAsAgentMaxDepth } from "./extract-provider.js";
+import type { WorkflowConfig } from "./registry/index.js";
 import { getRegisteredWorkflow, readWorkflowRegistry } from "./registry/index.js";
 import type { AgentContext, AgentFn, ThreadInput } from "./types.js";
 import {
@@ -14,6 +14,15 @@ import {
   getGlobalCasDir,
 } from "./util/index.js";
 
+const DEFAULT_WORKFLOW_AS_AGENT_MAX_DEPTH = 3;
+
+function workflowAsAgentMaxDepth(config: WorkflowConfig | null): number {
+  if (config === null) {
+    return DEFAULT_WORKFLOW_AS_AGENT_MAX_DEPTH;
+  }
+  return config.maxDepth;
+}
+
 export type WorkflowAsAgentOptions = {
   /** When `null`, uses `getDefaultWorkflowStorageRoot()`. */
   storageRoot: string | null;
@@ -44,7 +53,7 @@ export function workflowAsAgent(
       return `ERROR: failed to read workflow registry: ${registryResult.error.message}`;
     }
 
-    const maxDepth = getWorkflowAsAgentMaxDepth(registryResult.value.config);
+    const maxDepth = workflowAsAgentMaxDepth(registryResult.value.config);
     if (nextDepth > maxDepth) {
       return `ERROR: workflow-as-agent depth limit exceeded (max ${maxDepth})`;
     }
@@ -92,6 +101,7 @@ export function workflowAsAgent(
           awaitAfterEachYield: async () => {},
           forkSourceThreadId: ctx.threadId,
           prefilledDiskSteps: null,
+          storageRoot,
         },
         io,
         logger,