feat(cli): complete AGENTS.md generation (#36 Phase 3)

- Replace placeholder with comprehensive coding agent instructions
- Covers: project structure, core concepts, dev workflow, coding
  conventions, template reuse, build/test, common pitfalls
- Add test coverage for AGENTS.md sections and terms

Testing: #48

examples/hello-world.ts

@@ -29,6 +29,7 @@ const greeter: RoleDefinition<Roles["greeter"]> = {
   extractPrompt: "Extract the greeting string produced for the user.",
   schema: greeterMetaSchema,
   extractRefs: null,
+  extractMode: "single",
 };
 
 const extract = createExtract({
@@ -48,4 +49,5 @@ export const run = createWorkflow<Roles>(
     agent: async (ctx) => `Hello, ${ctx.start.content}`,
   },
   extract,
+  null,
 );

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

@@ -0,0 +1,142 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdir, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { runCli } from "../src/cli-dispatch.js";
+import { cmdInitTemplate, cmdInitWorkspace } from "../src/cmd-init.js";
+import { pathExists } from "../src/fs-utils.js";
+
+describe("init template", () => {
+  let parent: string;
+
+  beforeEach(async () => {
+    parent = join(
+      tmpdir(),
+      `wf-init-template-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+    );
+    await mkdir(parent, { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(parent, { recursive: true, force: true });
+  });
+
+  test("creates templates/<name> with expected files", async () => {
+    const ws = await cmdInitWorkspace(parent, "my-workflows");
+    expect(ws.ok).toBe(true);
+    if (!ws.ok) {
+      return;
+    }
+    const root = ws.value.rootPath;
+
+    const created = await cmdInitTemplate(root, "review-pr");
+    expect(created.ok).toBe(true);
+    if (!created.ok) {
+      return;
+    }
+
+    const tdir = join(root, "templates", "review-pr");
+    expect(created.value.templatePath).toBe(tdir);
+    expect(await pathExists(join(tdir, "package.json"))).toBe(true);
+    expect(await pathExists(join(tdir, "tsconfig.json"))).toBe(true);
+    expect(await pathExists(join(tdir, "src", "roles.ts"))).toBe(true);
+    expect(await pathExists(join(tdir, "src", "moderator.ts"))).toBe(true);
+    expect(await pathExists(join(tdir, "src", "index.ts"))).toBe(true);
+
+    const pkg = JSON.parse(await readFile(join(tdir, "package.json"), "utf8")) as {
+      name: string;
+      type: string;
+      dependencies: Record<string, string>;
+    };
+    expect(pkg.type).toBe("module");
+    expect(pkg.dependencies["@uncaged/workflow"]).toBeDefined();
+    expect(pkg.dependencies.zod).toBeDefined();
+    expect(pkg.name).toContain("review-pr");
+
+    const idx = await readFile(join(tdir, "src", "index.ts"), "utf8");
+    expect(idx).toContain("WorkflowDefinition");
+
+    const roles = await readFile(join(tdir, "src", "roles.ts"), "utf8");
+    expect(roles).not.toContain("interface ");
+    expect(roles).not.toContain("?:");
+    expect(roles).not.toContain("export default");
+
+    const moder = await readFile(join(tdir, "src", "moderator.ts"), "utf8");
+    expect(moder).not.toContain("export default");
+  });
+
+  test("finds workspace walking up from nested cwd", async () => {
+    const ws = await cmdInitWorkspace(parent, "ws");
+    expect(ws.ok).toBe(true);
+    if (!ws.ok) {
+      return;
+    }
+    const root = ws.value.rootPath;
+    const nested = join(root, "a", "b");
+    await mkdir(nested, { recursive: true });
+
+    const created = await cmdInitTemplate(nested, "nested-tpl");
+    expect(created.ok).toBe(true);
+    if (!created.ok) {
+      return;
+    }
+    expect(await pathExists(join(root, "templates", "nested-tpl", "src", "index.ts"))).toBe(true);
+  });
+
+  test("errors when not inside a workflow workspace", async () => {
+    const orphan = join(parent, "nowhere");
+    await mkdir(orphan, { recursive: true });
+    const r = await cmdInitTemplate(orphan, "x");
+    expect(r.ok).toBe(false);
+    if (!r.ok) {
+      expect(r.error).toContain("templates/*");
+    }
+  });
+
+  test("errors when template directory already exists", async () => {
+    const ws = await cmdInitWorkspace(parent, "ws");
+    expect(ws.ok).toBe(true);
+    if (!ws.ok) {
+      return;
+    }
+    const root = ws.value.rootPath;
+
+    const first = await cmdInitTemplate(root, "dup");
+    expect(first.ok).toBe(true);
+
+    const second = await cmdInitTemplate(root, "dup");
+    expect(second.ok).toBe(false);
+    if (!second.ok) {
+      expect(second.error).toContain("already exists");
+    }
+  });
+
+  test("errors on invalid template name", async () => {
+    const ws = await cmdInitWorkspace(parent, "ws");
+    expect(ws.ok).toBe(true);
+    if (!ws.ok) {
+      return;
+    }
+    const bad = await cmdInitTemplate(ws.value.rootPath, "a/b");
+    expect(bad.ok).toBe(false);
+  });
+
+  test.serial("runCli init template uses cwd and succeeds in workspace", async () => {
+    const ws = await cmdInitWorkspace(parent, "cli-ws");
+    expect(ws.ok).toBe(true);
+    if (!ws.ok) {
+      return;
+    }
+    const root = ws.value.rootPath;
+    const prev = process.cwd();
+    try {
+      process.chdir(root);
+      const code = await runCli(join(parent, "_storage"), ["init", "template", "from-cli"]);
+      expect(code).toBe(0);
+      expect(await pathExists(join(root, "templates", "from-cli", "package.json"))).toBe(true);
+    } finally {
+      process.chdir(prev);
+    }
+  });
+});

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

@@ -0,0 +1,152 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdir, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { formatCliUsage, runCli } from "../src/cli-dispatch.js";
+import { cmdInitWorkspace } from "../src/cmd-init.js";
+import { pathExists } from "../src/fs-utils.js";
+
+describe("init workspace", () => {
+  let parent: string;
+
+  beforeEach(async () => {
+    parent = join(tmpdir(), `wf-init-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    await mkdir(parent, { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(parent, { recursive: true, force: true });
+  });
+
+  test("creates expected files and directories", async () => {
+    const created = await cmdInitWorkspace(parent, "my-workflows");
+    expect(created.ok).toBe(true);
+    if (!created.ok) {
+      return;
+    }
+
+    const root = created.value.rootPath;
+    expect(await pathExists(join(root, "package.json"))).toBe(true);
+    expect(await pathExists(join(root, "biome.json"))).toBe(true);
+    expect(await pathExists(join(root, "tsconfig.json"))).toBe(true);
+    expect(await pathExists(join(root, "AGENTS.md"))).toBe(true);
+    expect(await pathExists(join(root, "README.md"))).toBe(true);
+    expect(await pathExists(join(root, "templates"))).toBe(true);
+    expect(await pathExists(join(root, "templates", ".gitkeep"))).toBe(true);
+    expect(await pathExists(join(root, "workflows", "package.json"))).toBe(true);
+
+    const rootPkg = JSON.parse(await readFile(join(root, "package.json"), "utf8")) as {
+      workspaces: string[];
+    };
+    expect(rootPkg.workspaces).toEqual(["templates/*", "workflows"]);
+
+    const wfPkg = JSON.parse(await readFile(join(root, "workflows", "package.json"), "utf8")) as {
+      type: string;
+      dependencies: Record<string, string>;
+    };
+    expect(wfPkg.type).toBe("module");
+    expect(wfPkg.dependencies["@uncaged/workflow"]).toBeDefined();
+    expect(wfPkg.dependencies.zod).toBeDefined();
+
+    const tsconfig = JSON.parse(await readFile(join(root, "tsconfig.json"), "utf8")) as {
+      compilerOptions: { strict: boolean; module: string; target: string };
+    };
+    expect(tsconfig.compilerOptions.strict).toBe(true);
+    expect(tsconfig.compilerOptions.module).toBe("ESNext");
+    expect(tsconfig.compilerOptions.target).toBe("ESNext");
+  });
+
+  test("AGENTS.md contains coding agent guide sections and terms", async () => {
+    const created = await cmdInitWorkspace(parent, "my-workflows");
+    expect(created.ok).toBe(true);
+    if (!created.ok) {
+      return;
+    }
+
+    const agentsPath = join(created.value.rootPath, "AGENTS.md");
+    const body = await readFile(agentsPath, "utf8");
+
+    for (const section of [
+      "项目结构",
+      "核心概念",
+      "开发流程",
+      "编码规范",
+      "Template",
+      "Build",
+      "常见陷阱",
+    ]) {
+      expect(body).toContain(section);
+    }
+
+    for (const term of [
+      "RoleDefinition",
+      "WorkflowDefinition",
+      "Moderator",
+      "AgentFn",
+      "ExtractFn",
+      "RoleMeta",
+    ]) {
+      expect(body).toContain(term);
+    }
+
+    expect(body).toMatch(/type[\s\S]*interface/i);
+    expect(body).toMatch(/function[\s\S]*class/i);
+    expect(body).toContain("Crockford Base32");
+    expect(body).toMatch(/no[\s\S]*default export/i);
+    expect(body).toMatch(/no[\s\S]*console/i);
+    expect(body).toMatch(/no[\s\S]*dynamic import/i);
+
+    expect(body).toContain("bun run check");
+    expect(body).toContain("bun test");
+    expect(body).toContain("uncaged-workflow");
+    expect(body).toContain("bun build");
+    expect(body).toContain("CLAUDE.md");
+    expect(body).toContain("docs/architecture.md");
+  });
+
+  test("errors when directory already exists", async () => {
+    const first = await cmdInitWorkspace(parent, "dup");
+    expect(first.ok).toBe(true);
+
+    const second = await cmdInitWorkspace(parent, "dup");
+    expect(second.ok).toBe(false);
+    if (!second.ok) {
+      expect(second.error).toContain("already exists");
+    }
+  });
+
+  test("errors on invalid workspace name", async () => {
+    const slash = await cmdInitWorkspace(parent, "a/b");
+    expect(slash.ok).toBe(false);
+
+    const dots = await cmdInitWorkspace(parent, "..");
+    expect(dots.ok).toBe(false);
+
+    const empty = await cmdInitWorkspace(parent, "");
+    expect(empty.ok).toBe(false);
+  });
+
+  test("usage lists init subcommands", () => {
+    const u = formatCliUsage();
+    expect(u).toContain("uncaged-workflow init workspace <name>");
+    expect(u).toContain("uncaged-workflow init template <name>");
+  });
+
+  test("runCli rejects unknown init subcommand", async () => {
+    const code = await runCli(join(parent, "_storage"), ["init", "bogus", "name"]);
+    expect(code).toBe(1);
+  });
+
+  test.serial("runCli init workspace uses cwd", async () => {
+    const prev = process.cwd();
+    try {
+      process.chdir(parent);
+      const code = await runCli(join(parent, "_storage"), ["init", "workspace", "from-cli"]);
+      expect(code).toBe(0);
+      expect(await pathExists(join(parent, "from-cli", "workflows", "package.json"))).toBe(true);
+    } finally {
+      process.chdir(prev);
+    }
+  });
+});

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

@@ -4,6 +4,7 @@ import { cmdCasGet, cmdCasList, cmdCasPut, cmdCasRm } from "./cmd-cas.js";
 import { cmdFork, parseForkArgv } from "./cmd-fork.js";
 import { cmdGc } from "./cmd-gc.js";
 import { cmdHistory } from "./cmd-history.js";
+import { cmdInitTemplate, cmdInitWorkspace } from "./cmd-init.js";
 import { cmdKill } from "./cmd-kill.js";
 import { cmdList, formatListLines } from "./cmd-list.js";
 import { cmdPause } from "./cmd-pause.js";
@@ -17,7 +18,7 @@ import { cmdThreadRemove, cmdThreadShow } from "./cmd-thread.js";
 import { cmdThreads } from "./cmd-threads.js";
 import { parseRunArgv } from "./run-argv.js";
 
-function usage(): string {
+export function formatCliUsage(): string {
   return [
     "Usage:",
     "  uncaged-workflow add <name> <file.esm.js> [--types <path>]",
@@ -40,13 +41,47 @@ function usage(): string {
     "  uncaged-workflow cas put <thread-id> <content>",
     "  uncaged-workflow cas list <thread-id>",
     "  uncaged-workflow cas rm <thread-id> <hash>",
+    "  uncaged-workflow init workspace <name>",
+    "  uncaged-workflow init template <name>",
   ].join("\n");
 }
 
+async function dispatchInit(_storageRoot: string, argv: string[]): Promise<number> {
+  const sub = argv[0];
+  const name = argv[1];
+  if (sub === undefined || name === undefined || argv.length > 2) {
+    printCliError(`${formatCliUsage()}\n\nerror: init requires workspace|template <name>`);
+    return 1;
+  }
+
+  if (sub === "workspace") {
+    const result = await cmdInitWorkspace(process.cwd(), name);
+    if (!result.ok) {
+      printCliError(result.error);
+      return 1;
+    }
+    printCliLine(`initialized workflow workspace at ${result.value.rootPath}`);
+    return 0;
+  }
+
+  if (sub === "template") {
+    const result = await cmdInitTemplate(process.cwd(), name);
+    if (!result.ok) {
+      printCliError(result.error);
+      return 1;
+    }
+    printCliLine(`initialized template at ${result.value.templatePath}`);
+    return 0;
+  }
+
+  printCliError(`${formatCliUsage()}\n\nerror: unknown init subcommand: ${sub}`);
+  return 1;
+}
+
 async function dispatchAdd(storageRoot: string, argv: string[]): Promise<number> {
   const parsed = parseAddArgv(argv);
   if (!parsed.ok) {
-    printCliError(`${usage()}\n\nerror: ${parsed.error}`);
+    printCliError(`${formatCliUsage()}\n\nerror: ${parsed.error}`);
     return 1;
   }
   const result = await cmdAdd(storageRoot, parsed.value);
@@ -63,7 +98,7 @@ async function dispatchAdd(storageRoot: string, argv: string[]): Promise<number>
 
 async function dispatchList(storageRoot: string, argv: string[]): Promise<number> {
   if (argv.length > 0) {
-    printCliError(`${usage()}\n\nerror: list takes no arguments`);
+    printCliError(`${formatCliUsage()}\n\nerror: list takes no arguments`);
     return 1;
   }
   const result = await cmdList(storageRoot);
@@ -80,7 +115,7 @@ async function dispatchList(storageRoot: string, argv: string[]): Promise<number
 async function dispatchShow(storageRoot: string, argv: string[]): Promise<number> {
   const name = argv[0];
   if (name === undefined || argv.length > 1) {
-    printCliError(`${usage()}\n\nerror: show requires <name>`);
+    printCliError(`${formatCliUsage()}\n\nerror: show requires <name>`);
     return 1;
   }
   const result = await cmdShow(storageRoot, name);
@@ -95,7 +130,7 @@ async function dispatchShow(storageRoot: string, argv: string[]): Promise<number
 async function dispatchRemove(storageRoot: string, argv: string[]): Promise<number> {
   const name = argv[0];
   if (name === undefined || argv.length > 1) {
-    printCliError(`${usage()}\n\nerror: remove requires <name>`);
+    printCliError(`${formatCliUsage()}\n\nerror: remove requires <name>`);
     return 1;
   }
   const result = await cmdRemove(storageRoot, name);
@@ -110,7 +145,7 @@ async function dispatchRemove(storageRoot: string, argv: string[]): Promise<numb
 async function dispatchRun(storageRoot: string, argv: string[]): Promise<number> {
   const parsed = parseRunArgv(argv);
   if (!parsed.ok) {
-    printCliError(`${usage()}\n\nerror: ${parsed.error}`);
+    printCliError(`${formatCliUsage()}\n\nerror: ${parsed.error}`);
     return 1;
   }
 
@@ -131,7 +166,7 @@ async function dispatchRun(storageRoot: string, argv: string[]): Promise<number>
 
 async function dispatchPs(storageRoot: string, argv: string[]): Promise<number> {
   if (argv.length > 0) {
-    printCliError(`${usage()}\n\nerror: ps takes no arguments`);
+    printCliError(`${formatCliUsage()}\n\nerror: ps takes no arguments`);
     return 1;
   }
   for (const line of await cmdPs(storageRoot)) {
@@ -143,7 +178,7 @@ async function dispatchPs(storageRoot: string, argv: string[]): Promise<number>
 async function dispatchKill(storageRoot: string, argv: string[]): Promise<number> {
   const threadId = argv[0];
   if (threadId === undefined || argv.length > 1) {
-    printCliError(`${usage()}\n\nerror: kill requires <thread-id>`);
+    printCliError(`${formatCliUsage()}\n\nerror: kill requires <thread-id>`);
     return 1;
   }
   const result = await cmdKill(storageRoot, threadId);
@@ -158,7 +193,7 @@ async function dispatchKill(storageRoot: string, argv: string[]): Promise<number
 async function dispatchHistory(storageRoot: string, argv: string[]): Promise<number> {
   const name = argv[0];
   if (name === undefined || argv.length > 1) {
-    printCliError(`${usage()}\n\nerror: history requires <name>`);
+    printCliError(`${formatCliUsage()}\n\nerror: history requires <name>`);
     return 1;
   }
   const result = await cmdHistory(storageRoot, name);
@@ -175,7 +210,7 @@ async function dispatchHistory(storageRoot: string, argv: string[]): Promise<num
 async function dispatchRollback(storageRoot: string, argv: string[]): Promise<number> {
   const name = argv[0];
   if (name === undefined || argv.length > 2) {
-    printCliError(`${usage()}\n\nerror: rollback requires <name> [hash]`);
+    printCliError(`${formatCliUsage()}\n\nerror: rollback requires <name> [hash]`);
     return 1;
   }
   const hashArg = argv[1];
@@ -191,7 +226,7 @@ async function dispatchRollback(storageRoot: string, argv: string[]): Promise<nu
 async function dispatchPause(storageRoot: string, argv: string[]): Promise<number> {
   const threadId = argv[0];
   if (threadId === undefined || argv.length > 1) {
-    printCliError(`${usage()}\n\nerror: pause requires <thread-id>`);
+    printCliError(`${formatCliUsage()}\n\nerror: pause requires <thread-id>`);
     return 1;
   }
   const result = await cmdPause(storageRoot, threadId);
@@ -206,7 +241,7 @@ async function dispatchPause(storageRoot: string, argv: string[]): Promise<numbe
 async function dispatchResume(storageRoot: string, argv: string[]): Promise<number> {
   const threadId = argv[0];
   if (threadId === undefined || argv.length > 1) {
-    printCliError(`${usage()}\n\nerror: resume requires <thread-id>`);
+    printCliError(`${formatCliUsage()}\n\nerror: resume requires <thread-id>`);
     return 1;
   }
   const result = await cmdResume(storageRoot, threadId);
@@ -233,7 +268,7 @@ async function dispatchThreads(storageRoot: string, argv: string[]): Promise<num
 async function dispatchThread(storageRoot: string, argv: string[]): Promise<number> {
   const id = argv[0];
   if (id === undefined || argv.length > 1) {
-    printCliError(`${usage()}\n\nerror: thread requires <id>`);
+    printCliError(`${formatCliUsage()}\n\nerror: thread requires <id>`);
     return 1;
   }
   const result = await cmdThreadShow(storageRoot, id);
@@ -248,7 +283,7 @@ async function dispatchThread(storageRoot: string, argv: string[]): Promise<numb
 async function dispatchThreadRm(storageRoot: string, argv: string[]): Promise<number> {
   const id = argv[0];
   if (id === undefined || argv.length > 1) {
-    printCliError(`${usage()}\n\nerror: thread rm requires <id>`);
+    printCliError(`${formatCliUsage()}\n\nerror: thread rm requires <id>`);
     return 1;
   }
   const result = await cmdThreadRemove(storageRoot, id);
@@ -270,7 +305,7 @@ async function dispatchThreadBranch(storageRoot: string, rest: string[]): Promis
 
 async function dispatchGc(storageRoot: string, argv: string[]): Promise<number> {
   if (argv.length > 0) {
-    printCliError(`${usage()}\n\nerror: gc takes no arguments`);
+    printCliError(`${formatCliUsage()}\n\nerror: gc takes no arguments`);
     return 1;
   }
   const result = await cmdGc(storageRoot);
@@ -288,7 +323,7 @@ async function dispatchGc(storageRoot: string, argv: string[]): Promise<number>
 async function dispatchFork(storageRoot: string, argv: string[]): Promise<number> {
   const parsed = parseForkArgv(argv);
   if (!parsed.ok) {
-    printCliError(`${usage()}\n\nerror: ${parsed.error}`);
+    printCliError(`${formatCliUsage()}\n\nerror: ${parsed.error}`);
     return 1;
   }
   const result = await cmdFork(storageRoot, parsed.value.threadId, parsed.value.fromRole);
@@ -304,7 +339,7 @@ async function dispatchCasGet(storageRoot: string, rest: string[]): Promise<numb
   const threadId = rest[0];
   const hash = rest[1];
   if (threadId === undefined || hash === undefined || rest.length > 2) {
-    printCliError(`${usage()}\n\nerror: cas get requires <thread-id> <hash>`);
+    printCliError(`${formatCliUsage()}\n\nerror: cas get requires <thread-id> <hash>`);
     return 1;
   }
   const result = await cmdCasGet(storageRoot, threadId, hash);
@@ -320,7 +355,7 @@ async function dispatchCasPut(storageRoot: string, rest: string[]): Promise<numb
   const threadId = rest[0];
   const content = rest[1];
   if (threadId === undefined || content === undefined || rest.length > 2) {
-    printCliError(`${usage()}\n\nerror: cas put requires <thread-id> <content>`);
+    printCliError(`${formatCliUsage()}\n\nerror: cas put requires <thread-id> <content>`);
     return 1;
   }
   const result = await cmdCasPut(storageRoot, threadId, content);
@@ -335,7 +370,7 @@ async function dispatchCasPut(storageRoot: string, rest: string[]): Promise<numb
 async function dispatchCasList(storageRoot: string, rest: string[]): Promise<number> {
   const threadId = rest[0];
   if (threadId === undefined || rest.length > 1) {
-    printCliError(`${usage()}\n\nerror: cas list requires <thread-id>`);
+    printCliError(`${formatCliUsage()}\n\nerror: cas list requires <thread-id>`);
     return 1;
   }
   const result = await cmdCasList(storageRoot, threadId);
@@ -353,7 +388,7 @@ async function dispatchCasRm(storageRoot: string, rest: string[]): Promise<numbe
   const threadId = rest[0];
   const hash = rest[1];
   if (threadId === undefined || hash === undefined || rest.length > 2) {
-    printCliError(`${usage()}\n\nerror: cas rm requires <thread-id> <hash>`);
+    printCliError(`${formatCliUsage()}\n\nerror: cas rm requires <thread-id> <hash>`);
     return 1;
   }
   const result = await cmdCasRm(storageRoot, threadId, hash);
@@ -378,12 +413,12 @@ const CAS_SUBCOMMAND_TABLE: Record<
 async function dispatchCas(storageRoot: string, argv: string[]): Promise<number> {
   const sub = argv[0];
   if (sub === undefined) {
-    printCliError(`${usage()}\n\nerror: unknown cas subcommand: (none)`);
+    printCliError(`${formatCliUsage()}\n\nerror: unknown cas subcommand: (none)`);
     return 1;
   }
   const handler = CAS_SUBCOMMAND_TABLE[sub];
   if (handler === undefined) {
-    printCliError(`${usage()}\n\nerror: unknown cas subcommand: ${sub}`);
+    printCliError(`${formatCliUsage()}\n\nerror: unknown cas subcommand: ${sub}`);
     return 1;
   }
   return handler(storageRoot, argv.slice(1));
@@ -393,6 +428,7 @@ type DispatchFn = (storageRoot: string, argv: string[]) => Promise<number>;
 
 const COMMAND_TABLE: Record<string, DispatchFn> = {
   add: dispatchAdd,
+  init: dispatchInit,
   list: dispatchList,
   show: dispatchShow,
   remove: dispatchRemove,
@@ -412,18 +448,18 @@ const COMMAND_TABLE: Record<string, DispatchFn> = {
 
 export async function runCli(storageRoot: string, argv: string[]): Promise<number> {
   if (argv.length === 0) {
-    printCliError(usage());
+    printCliError(formatCliUsage());
     return 1;
   }
   const command = argv[0];
   if (command === undefined) {
-    printCliError(usage());
+    printCliError(formatCliUsage());
     return 1;
   }
   const rest = argv.slice(1);
   const dispatch = COMMAND_TABLE[command];
   if (dispatch === undefined) {
-    printCliError(`${usage()}\n\nerror: unknown command ${command}`);
+    printCliError(`${formatCliUsage()}\n\nerror: unknown command ${command}`);
     return 1;
   }
   return dispatch(storageRoot, rest);

packages/cli-workflow/src/cmd-init.ts

@@ -0,0 +1,415 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+
+import { err, ok, type Result } from "@uncaged/workflow";
+
+import { pathExists } from "./fs-utils.js";
+
+export type CmdInitWorkspaceSuccess = {
+  rootPath: string;
+};
+
+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);
+}
+
+function rootPackageJson(workspaceName: string): string {
+  return `${JSON.stringify(
+    {
+      name: workspaceName,
+      private: true,
+      type: "module",
+      workspaces: ["templates/*", "workflows"],
+    },
+    null,
+    2,
+  )}\n`;
+}
+
+function workflowsPackageJson(): string {
+  return `${JSON.stringify(
+    {
+      name: "workflows",
+      version: "0.0.0",
+      private: true,
+      type: "module",
+      dependencies: {
+        "@uncaged/workflow": "^0.1.0",
+        zod: "^4.0.0",
+      },
+    },
+    null,
+    2,
+  )}\n`;
+}
+
+function biomeJson(): string {
+  return `${JSON.stringify(
+    {
+      $schema: "https://biomejs.dev/schemas/2.4.14/schema.json",
+      files: {
+        includes: ["**", "!**/node_modules", "!**/dist"],
+      },
+      formatter: {
+        indentWidth: 2,
+      },
+      linter: {
+        enabled: true,
+        rules: {
+          recommended: true,
+        },
+      },
+    },
+    null,
+    2,
+  )}\n`;
+}
+
+function tsconfigJson(): string {
+  return `${JSON.stringify(
+    {
+      compilerOptions: {
+        strict: true,
+        target: "ESNext",
+        module: "ESNext",
+        moduleResolution: "Bundler",
+        skipLibCheck: true,
+      },
+    },
+    null,
+    2,
+  )}\n`;
+}
+
+function agentsMd(): string {
+  return `# AGENTS — Workflow 工作区开发指南
+
+面向在本仓库中编写 workflow 的 coding agent。引擎层术语与架构细节与 **@uncaged/workflow** 上游文档一致，编写时可对照 \`CLAUDE.md\` 与 \`docs/architecture.md\`。
+
+## 1. 项目结构（workspace / template / workflow instance）
+
+| 层级 | 目录 / 产物 | 职责 |
+|------|----------------|------|
+| **Workspace** | 仓库根（\`package.json\` 含 \`workspaces: ["templates/*", "workflows"]\`） | Bun monorepo：统一管理本地模板包与 workflow 实例 |
+| **Template** | \`templates/<name>/\`（如 \`src/roles.ts\`、\`src/moderator.ts\`、\`src/index.ts\`） | 纯数据：**WorkflowDefinition**（各 **RoleDefinition** + **Moderator**），**不绑定**具体 Agent |
+| **Workflow instance** | \`workflows/\`（或单独包） | 把模板与运行时 **AgentFn** / **ExtractFn** 组合，产出可注册的 **单文件 ESM bundle**（\`run\` + \`descriptor\` 命名导出） |
+
+Init 生成的骨架：\`templates/\` 下放可复用定义，\`workflows/\` 下放绑定与打包入口。
+
+## 2. 核心概念
+
+- **RoleMeta**：\`Record<string, Record<string, unknown>>\`，角色名 → 该角色结构化 meta 的形状约定。
+- **RoleDefinition<Meta>**：纯数据——\`description\`、\`systemPrompt\`、\`extractPrompt\`、\`schema\`（Zod v4）。不含执行逻辑。
+- **WorkflowDefinition<M extends RoleMeta>**：\`description\` + \`roles\`（各角色定义）+ **Moderator**。
+- **Moderator**：\`(ctx: ModeratorContext<M>) => (角色名) | END\`。同步、纯函数，只做路由。
+- **AgentFn**：\`(ctx: AgentContext) => Promise<string>\`，原始文本输出；从上下文读取当前角色的 \`systemPrompt\`。
+- **ExtractFn**：从上下文与 prompt 解析结构化数据（引擎与 Agent 都可使用）。
+
+引擎循环简述：**Moderator** → 选角色 → **Agent** 产出文本 → **Extract** 写入 **meta** → 追加 step，重复直至 **END**。详见 \`docs/architecture.md\` 中的三阶段说明。
+
+## 3. 开发流程
+
+1. **定义 RoleMeta**：为每个角色约定 meta 的 TypeScript 类型（与 Zod schema 对齐）。
+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**。
+6. **构建**：打包为单个 **.esm.js** bundle，使用 **uncaged-workflow add** 注册。
+
+## 4. 编码规范
+
+与 **CLAUDE.md** 对齐，摘要如下：
+
+- **Functional-first**：优先 \`function\` + \`type\`，避免面向对象业务模型。
+- **type 而非 interface**：类型别名一律用 \`type\`，不要使用 \`interface\`。
+- **显式可空**：不要用 \`?:\`；可空字段写成 \`T | null\`。
+- **function 而非 class**：不用 class（第三方库要求或 \`Error\` 子类除外）。
+- **Crockford Base32**：日志 tag、bundle hash、thread id 等标识约定（引擎侧）；工作区内自定义日志若沿用引擎 logger，tag 为 8 字符 Crockford Base32，且每个调用点唯一。
+- **Named exports only**：不要使用 **default export**；workflow bundle 须 **export const run** 与 **export const descriptor**。
+- **No console.log**：库代码用结构化 logger；CLI 用户输出可按项目 Biome 规则例外标注。
+- **No dynamic import**：业务与 bundle 内禁止 \`import()\`；例外仅限「运行时路径由用户提供的 bundle 加载器」（引擎内部）。
+
+## 5. Template 复用
+
+- **已发布模板**：可通过 npm 依赖 \`@uncaged/workflow-template-*\` 等包，在 workflow 实例中 import 其 **WorkflowDefinition** 再绑定 Agent。
+- **本地模板**：放在本仓库 \`templates/<name>/\`，由 workspace 协议引用（如 \`"template-foo": "workspace:*"\` 或相对路径），便于同源修改与版本控制。
+
+选择模板时保持 **definition 与 agent 绑定分离**：模板只描述「做什么、顺序如何」，实例决定「谁执行、如何抽取 meta」。
+
+## 6. Build and Test
+
+日常命令：
+
+\`\`\`sh
+bun install
+bun run check    # Biome：lint + format
+bun test
+bun build        # 若包内配置了 build 脚本则用于产出 dist / bundle
+uncaged-workflow add <name> <path/to/bundle.esm.js>
+\`\`\`
+
+提交前至少运行 **bun run check** 与 **bun test**；registry 与本地运行流参见 README 与 CLI 文档。
+
+## 7. 常见陷阱
+
+- **No dynamic import**：bundle 须静态可分析；动态 \`import()\` 会破坏哈希与加载约束。
+- **No default export**：引擎只接受命名导出 \`run\` / \`descriptor\`。
+- **No console.log**：避免在可被 Biome \`noConsole\` 规则覆盖的代码路径直接使用 console。
+- **Single-file ESM bundle**：交付物是单一 \`.esm.js\`；静态 import 仅限 Node 内置（见 architecture 文档中的 Bundle Contract）。
+
+---
+
+编写新 workflow 时，先对齐 **RoleMeta → RoleDefinition（Zod）→ Moderator → 绑定 → 单文件 bundle**，再对照本节规范自检。
+`;
+}
+
+function readmeMd(workspaceName: string): string {
+  return `# ${workspaceName}
+
+Local workflow development workspace (Bun monorepo).
+
+## Layout
+
+- \`templates/\` — reusable workflow definition packages (roles + moderator), no agent binding
+- \`workflows/\` — workflow instances that bind templates to agents and export \`run\` + \`descriptor\`
+
+## Commands
+
+\`\`\`sh
+bun install
+bun run check   # after you add scripts / Biome
+uncaged-workflow add <name> <bundle.esm.js>
+uncaged-workflow run <name>
+\`\`\`
+
+Create this skeleton with:
+
+\`\`\`sh
+uncaged-workflow init workspace ${workspaceName}
+\`\`\`
+`;
+}
+
+export async function cmdInitWorkspace(
+  parentDir: string,
+  workspaceName: string,
+): Promise<Result<CmdInitWorkspaceSuccess, string>> {
+  const validated = validateWorkspaceSegment(workspaceName);
+  if (!validated.ok) {
+    return validated;
+  }
+
+  const rootPath = join(parentDir, workspaceName);
+  if (await pathExists(rootPath)) {
+    return err(`directory already exists: ${rootPath}`);
+  }
+
+  await mkdir(rootPath, { recursive: false });
+  await mkdir(join(rootPath, "templates"), { recursive: false });
+  await mkdir(join(rootPath, "workflows"), { recursive: false });
+
+  await Promise.all([
+    writeFile(join(rootPath, "package.json"), rootPackageJson(workspaceName), "utf8"),
+    writeFile(join(rootPath, "biome.json"), biomeJson(), "utf8"),
+    writeFile(join(rootPath, "tsconfig.json"), tsconfigJson(), "utf8"),
+    writeFile(join(rootPath, "AGENTS.md"), agentsMd(), "utf8"),
+    writeFile(join(rootPath, "README.md"), readmeMd(workspaceName), "utf8"),
+    writeFile(join(rootPath, "templates", ".gitkeep"), "", "utf8"),
+    writeFile(join(rootPath, "workflows", "package.json"), workflowsPackageJson(), "utf8"),
+  ]);
+
+  return ok({ rootPath });
+}
+
+function hasTemplatesWorkspaceGlob(workspaces: unknown): boolean {
+  return Array.isArray(workspaces) && workspaces.includes("templates/*");
+}
+
+async function readPackageJsonWorkspaces(dir: string): Promise<unknown | null> {
+  const pkgPath = join(dir, "package.json");
+  if (!(await pathExists(pkgPath))) {
+    return null;
+  }
+  let raw: string;
+  try {
+    raw = await readFile(pkgPath, "utf8");
+  } catch {
+    return null;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw) as unknown;
+  } catch {
+    return null;
+  }
+  if (typeof parsed !== "object" || parsed === null || !("workspaces" in parsed)) {
+    return null;
+  }
+  return (parsed as { workspaces: unknown }).workspaces;
+}
+
+/** Resolve uncaged-workflow workspace root (package.json with `templates/*` in `workspaces`). */
+async function findWorkflowWorkspaceRoot(startDir: string): Promise<Result<string, string>> {
+  let dir = resolve(startDir);
+  for (;;) {
+    const workspaces = await readPackageJsonWorkspaces(dir);
+    if (workspaces !== null && hasTemplatesWorkspaceGlob(workspaces)) {
+      return ok(dir);
+    }
+    const parent = dirname(dir);
+    if (parent === dir) {
+      return err(
+        'not inside a workflow workspace (no package.json with workspaces containing "templates/*")',
+      );
+    }
+    dir = parent;
+  }
+}
+
+function templatePackageJson(templateName: string): string {
+  return `${JSON.stringify(
+    {
+      name: `template-${templateName}`,
+      version: "0.0.0",
+      private: true,
+      type: "module",
+      dependencies: {
+        "@uncaged/workflow": "^0.1.0",
+        zod: "^4.0.0",
+      },
+    },
+    null,
+    2,
+  )}\n`;
+}
+
+function templateTsconfigJson(): string {
+  return `${JSON.stringify(
+    {
+      extends: "../../tsconfig.json",
+      compilerOptions: {
+        rootDir: "src",
+        outDir: "dist",
+      },
+      include: ["src/**/*.ts"],
+    },
+    null,
+    2,
+  )}\n`;
+}
+
+function templateRolesTs(): string {
+  return `import type { RoleDefinition } from "@uncaged/workflow";
+import * as z from "zod/v4";
+
+export const HELLO_TEMPLATE_DESCRIPTION =
+  "Minimal starter template: one greeter role, then END.";
+
+export type HelloTemplateMeta = {
+  greeter: {
+    message: string;
+  };
+};
+
+const greeterMetaSchema = z.object({
+  message: z.string(),
+});
+
+export const greeterRole: RoleDefinition<HelloTemplateMeta["greeter"]> = {
+  description: "Says hello — replace with your first role.",
+  systemPrompt: "You are a helpful assistant. Reply with one short friendly sentence.",
+  extractPrompt: "Extract the assistant's greeting as message.",
+  schema: greeterMetaSchema,
+  extractRefs: null,
+};
+`;
+}
+
+function templateModeratorTs(): string {
+  return `import { END, type Moderator, type ModeratorContext } from "@uncaged/workflow";
+
+import type { HelloTemplateMeta } from "./roles.js";
+
+export const helloTemplateModerator: Moderator<HelloTemplateMeta> = (
+  ctx: ModeratorContext<HelloTemplateMeta>,
+) => {
+  if (ctx.steps.length === 0) {
+    return "greeter";
+  }
+  return END;
+};
+`;
+}
+
+function templateIndexTs(): string {
+  return `import type { WorkflowDefinition } from "@uncaged/workflow";
+
+import { helloTemplateModerator } from "./moderator.js";
+import {
+  HELLO_TEMPLATE_DESCRIPTION,
+  type HelloTemplateMeta,
+  greeterRole,
+} from "./roles.js";
+
+export {
+  HELLO_TEMPLATE_DESCRIPTION,
+  type HelloTemplateMeta,
+  greeterRole,
+} from "./roles.js";
+export { helloTemplateModerator } from "./moderator.js";
+
+export const helloTemplateWorkflowDefinition: WorkflowDefinition<HelloTemplateMeta> = {
+  description: HELLO_TEMPLATE_DESCRIPTION,
+  roles: {
+    greeter: greeterRole,
+  },
+  moderator: helloTemplateModerator,
+};
+`;
+}
+
+export async function cmdInitTemplate(
+  startDir: string,
+  templateName: string,
+): Promise<Result<CmdInitTemplateSuccess, string>> {
+  const validated = validateWorkspaceSegment(templateName);
+  if (!validated.ok) {
+    return validated;
+  }
+
+  const rootResult = await findWorkflowWorkspaceRoot(startDir);
+  if (!rootResult.ok) {
+    return rootResult;
+  }
+
+  const workspaceRoot = rootResult.value;
+  const templateDir = join(workspaceRoot, "templates", templateName);
+  if (await pathExists(templateDir)) {
+    return err(`template already exists: ${templateDir}`);
+  }
+
+  await mkdir(join(templateDir, "src"), { recursive: true });
+
+  await Promise.all([
+    writeFile(join(templateDir, "package.json"), templatePackageJson(templateName), "utf8"),
+    writeFile(join(templateDir, "tsconfig.json"), templateTsconfigJson(), "utf8"),
+    writeFile(join(templateDir, "src", "roles.ts"), templateRolesTs(), "utf8"),
+    writeFile(join(templateDir, "src", "moderator.ts"), templateModeratorTs(), "utf8"),
+    writeFile(join(templateDir, "src", "index.ts"), templateIndexTs(), "utf8"),
+  ]);
+
+  return ok({ templatePath: templateDir });
+}

packages/workflow-role-coder/src/coder.ts

@@ -39,4 +39,5 @@ export const coderRole: RoleDefinition<CoderMeta> = {
     "Extract completedPhase: the planner phase hash finished this round (exact hash string from the plan). If multiple phases were finished in one round, use the last finished phase hash. Extract filesChanged and a summary of the work.",
   schema: coderMetaSchema,
   extractRefs: (meta) => [meta.completedPhase],
+  extractMode: "single",
 };

packages/workflow-role-committer/src/committer.ts

@@ -32,4 +32,5 @@ export const committerRole: RoleDefinition<CommitterMeta> = {
     "Extract the commit result: committed (with branch and SHA), recoverable failure, or unrecoverable failure. Include error details and log references if applicable.",
   schema: committerMetaSchema,
   extractRefs: null,
+  extractMode: "single",
 };

packages/workflow-role-planner/src/planner.ts

@@ -50,4 +50,5 @@ export const plannerRole: RoleDefinition<PlannerMeta> = {
     "Extract the implementation phases from the agent's output. Each phase has a hash (the CAS content-hash returned by the cas put command) and a title (one-line summary).",
   schema: plannerMetaSchema,
   extractRefs: (meta) => meta.phases.map((p) => p.hash),
+  extractMode: "single",
 };

packages/workflow-role-preparer/src/preparer.ts

@@ -48,4 +48,5 @@ export const preparerRole: RoleDefinition<PreparerMeta> = {
     "Extract repoPath (absolute path), defaultBranch, conventions (summary string or null), and toolchain (packageManager, testCommand, lintCommand, buildCommand — each string or null).",
   schema: preparerMetaSchema,
   extractRefs: null,
+  extractMode: "single",
 };

packages/workflow-role-reviewer/src/reviewer.ts

@@ -22,4 +22,5 @@ export const reviewerRole: RoleDefinition<ReviewerMeta> = {
     "Extract the review verdict: approved or rejected. If rejected, list the blocking issues.",
   schema: reviewerMetaSchema,
   extractRefs: null,
+  extractMode: "single",
 };

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

@@ -313,7 +313,7 @@ describe("createSolveIssueRun", () => {
     casDir = await mkdtemp(join(tmpdir(), "solve-issue-cas-"));
     const cas = createCasStore(casDir);
 
-    const run = createSolveIssueRun({ agent: async () => "" }, stubExtract);
+    const run = createSolveIssueRun({ agent: async () => "" }, stubExtract, null);
     const gen = run(
       { prompt: "task", steps: [] },
       { threadId: "01TEST000000000000000000TR", maxRounds: 20, depth: 0, cas },
@@ -374,6 +374,7 @@ describe("createSolveIssueRun", () => {
         },
       },
       stubExtract,
+      null,
     );
     const gen = run(
       { prompt: "task", steps: [] },

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

@@ -2,6 +2,7 @@ import {
   type AgentBinding,
   createWorkflow,
   type ExtractFn,
+  type LlmProvider,
   type WorkflowDefinition,
   type WorkflowFn,
 } from "@uncaged/workflow";
@@ -50,6 +51,10 @@ export const solveIssueWorkflowDefinition: WorkflowDefinition<SolveIssueMeta> =
   moderator: solveIssueModerator,
 };
 
-export function createSolveIssueRun(binding: AgentBinding, extract: ExtractFn): WorkflowFn {
-  return createWorkflow(solveIssueWorkflowDefinition, binding, extract);
+export function createSolveIssueRun(
+  binding: AgentBinding,
+  extract: ExtractFn,
+  llmProvider: LlmProvider | null,
+): WorkflowFn {
+  return createWorkflow(solveIssueWorkflowDefinition, binding, extract, llmProvider);
 }

packages/workflow/__tests__/build-descriptor.test.ts

@@ -23,6 +23,7 @@ describe("buildDescriptor", () => {
           extractPrompt: "Extract title and count from the analysis.",
           schema,
           extractRefs: null,
+          extractMode: "single",
         },
       },
       moderator: () => END,

packages/workflow/__tests__/engine.test.ts

@@ -15,7 +15,7 @@ import {
   parseMerkleNode,
   serializeMerkleNode,
 } from "../src/merkle.js";
-import { END } from "../src/types.js";
+import { END, type LlmProvider } from "../src/types.js";
 
 const plannerMetaSchema = z.object({
   plan: z.string(),
@@ -97,6 +97,7 @@ const demoWorkflow = createWorkflow<DemoMeta>(
         extractPrompt: "Extract plan text and affected files list.",
         schema: plannerMetaSchema,
         extractRefs: null,
+        extractMode: "single",
       },
       coder: {
         description: "Demo coder",
@@ -104,6 +105,7 @@ const demoWorkflow = createWorkflow<DemoMeta>(
         extractPrompt: "Extract the code diff summary.",
         schema: coderMetaSchema,
         extractRefs: null,
+        extractMode: "single",
       },
     },
     moderator: (ctx) => {
@@ -124,6 +126,7 @@ const demoWorkflow = createWorkflow<DemoMeta>(
     },
   },
   demoExtract,
+  null,
 );
 
 describe("executeThread", () => {
@@ -445,4 +448,169 @@ describe("executeThread", () => {
       await rm(root, { recursive: true, force: true });
     }
   });
+
+  test("extractMode react traverses CAS DAG via cas_get during extraction", async () => {
+    const dagMetaSchema = z.object({ leafPayload: z.string() });
+    type DagDemoMeta = { walker: z.infer<typeof dagMetaSchema> };
+
+    const origFetch = globalThis.fetch;
+    restoreFetch = () => {
+      globalThis.fetch = origFetch;
+    };
+    let fetchRound = 0;
+
+    const root = await mkdtemp(join(tmpdir(), "wf-engine-react-"));
+    try {
+      const cas = createCasStore(join(root, "cas"));
+      const leafYaml = serializeMerkleNode(createContentMerkleNode("needle-from-leaf"));
+      const leafHash = await cas.put(leafYaml);
+      const rootYaml = serializeMerkleNode({
+        type: "thread",
+        payload: {
+          workflow: "dag-demo",
+          threadId: "01DAG00000000000000000001",
+          result: { returnCode: 0, summary: "" },
+        },
+        children: [leafHash],
+      });
+      const dagRootHash = await cas.put(rootYaml);
+
+      globalThis.fetch = Object.assign(
+        async (_input: Parameters<typeof fetch>[0], _init?: RequestInit) => {
+          fetchRound += 1;
+          if (fetchRound === 1) {
+            return new Response(
+              JSON.stringify({
+                choices: [
+                  {
+                    message: {
+                      tool_calls: [
+                        {
+                          id: "c1",
+                          type: "function",
+                          function: {
+                            name: "cas_get",
+                            arguments: JSON.stringify({ hash: dagRootHash }),
+                          },
+                        },
+                      ],
+                    },
+                  },
+                ],
+              }),
+              { status: 200, headers: { "Content-Type": "application/json" } },
+            );
+          }
+          if (fetchRound === 2) {
+            return new Response(
+              JSON.stringify({
+                choices: [
+                  {
+                    message: {
+                      tool_calls: [
+                        {
+                          id: "c2",
+                          type: "function",
+                          function: {
+                            name: "cas_get",
+                            arguments: JSON.stringify({ hash: leafHash }),
+                          },
+                        },
+                      ],
+                    },
+                  },
+                ],
+              }),
+              { status: 200, headers: { "Content-Type": "application/json" } },
+            );
+          }
+          return new Response(
+            JSON.stringify({
+              choices: [
+                {
+                  message: {
+                    tool_calls: [
+                      {
+                        id: "c3",
+                        type: "function",
+                        function: {
+                          name: "extract",
+                          arguments: JSON.stringify({ leafPayload: "needle-from-leaf" }),
+                        },
+                      },
+                    ],
+                  },
+                },
+              ],
+            }),
+            { status: 200, headers: { "Content-Type": "application/json" } },
+          );
+        },
+        { 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: {
+            walker: {
+              description: "DAG walker",
+              systemPrompt: "Output only the root CAS hash.",
+              extractPrompt:
+                "Set leafPayload to the string payload of the content Merkle node under the root.",
+              schema: dagMetaSchema,
+              extractRefs: null,
+              extractMode: "react",
+            },
+          },
+          moderator: (ctx) => (ctx.steps.length === 0 ? "walker" : END),
+        },
+        { agent: async () => dagRootHash },
+        extractFn,
+        llm,
+      );
+
+      const threadId = "01KQXKW18CT8G75T53R8F4G7YG";
+      const hash = "C9NMV6V2TQT81";
+      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 });
+
+      const logger = createLogger({ sink: { kind: "file", path: infoPath } });
+      const ac = new AbortController();
+
+      const result = await executeThread(
+        dagWorkflow,
+        "dag-demo",
+        { prompt: "traverse", steps: [] },
+        {
+          maxRounds: 5,
+          depth: 0,
+          signal: ac.signal,
+          awaitAfterEachYield: async () => {},
+          forkSourceThreadId: null,
+          prefilledDiskSteps: null,
+        },
+        { threadId, hash, dataJsonlPath: dataPath, infoJsonlPath: infoPath, cas },
+        logger,
+      );
+
+      expect(result.returnCode).toBe(0);
+      expect(fetchRound).toBe(3);
+
+      const dataText = await readFile(dataPath, "utf8");
+      const lines = dataText
+        .trim()
+        .split("\n")
+        .filter((l) => l !== "");
+      const roleRec = JSON.parse(lines[1] ?? "{}") as Record<string, unknown>;
+      expect(roleRec.role).toBe("walker");
+      expect(roleRec.meta).toEqual({ leafPayload: "needle-from-leaf" });
+    } finally {
+      globalThis.fetch = origFetch;
+      await rm(root, { recursive: true, force: true });
+    }
+  });
 });

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

@@ -0,0 +1,209 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import * as z from "zod/v4";
+
+import { createCasStore } from "../src/cas.js";
+import { createContentMerkleNode, serializeMerkleNode } from "../src/merkle.js";
+import { reactExtract } from "../src/react-extract.js";
+import type { LlmProvider } from "../src/types.js";
+
+const metaSchema = z.object({ seen: z.string() });
+
+const provider: LlmProvider = {
+  baseUrl: "http://127.0.0.1:9",
+  apiKey: "test",
+  model: "test",
+};
+
+describe("reactExtract", () => {
+  let restoreFetch: (() => void) | null = null;
+
+  afterEach(() => {
+    restoreFetch?.();
+    restoreFetch = null;
+  });
+
+  test("cas_get rounds then extract tool yields validated meta", async () => {
+    const casDir = await mkdtemp(join(tmpdir(), "react-extract-"));
+    const cas = createCasStore(casDir);
+    try {
+      const blob = serializeMerkleNode(createContentMerkleNode("needle"));
+      const h = await cas.put(blob);
+
+      const origFetch = globalThis.fetch;
+      let round = 0;
+      restoreFetch = () => {
+        globalThis.fetch = origFetch;
+      };
+      globalThis.fetch = Object.assign(
+        async (_input: Parameters<typeof fetch>[0], _init?: RequestInit) => {
+          round += 1;
+          if (round === 1) {
+            return new Response(
+              JSON.stringify({
+                choices: [
+                  {
+                    message: {
+                      tool_calls: [
+                        {
+                          id: "t1",
+                          type: "function",
+                          function: {
+                            name: "cas_get",
+                            arguments: JSON.stringify({ hash: h }),
+                          },
+                        },
+                      ],
+                    },
+                  },
+                ],
+              }),
+              { status: 200, headers: { "Content-Type": "application/json" } },
+            );
+          }
+          return new Response(
+            JSON.stringify({
+              choices: [
+                {
+                  message: {
+                    tool_calls: [
+                      {
+                        id: "t2",
+                        type: "function",
+                        function: {
+                          name: "extract",
+                          arguments: JSON.stringify({ seen: "needle" }),
+                        },
+                      },
+                    ],
+                  },
+                },
+              ],
+            }),
+            { status: 200, headers: { "Content-Type": "application/json" } },
+          );
+        },
+        { preconnect: origFetch.preconnect.bind(origFetch) },
+      ) as typeof fetch;
+
+      const text = `## Agent Output\n${h}\n## Extraction Instruction\nExtract seen from CAS.`;
+      const result = await reactExtract({
+        text,
+        schema: metaSchema,
+        provider,
+        cas,
+      });
+
+      expect(result.ok).toBe(true);
+      if (!result.ok) {
+        return;
+      }
+      expect(result.value).toEqual({ seen: "needle" });
+      expect(round).toBe(2);
+    } finally {
+      await rm(casDir, { recursive: true, force: true });
+    }
+  });
+
+  test("stops after max tool rounds when model keeps calling cas_get", async () => {
+    const casDir = await mkdtemp(join(tmpdir(), "react-extract-max-"));
+    const cas = createCasStore(casDir);
+    try {
+      const blob = serializeMerkleNode(createContentMerkleNode("x"));
+      const h = await cas.put(blob);
+
+      const origFetch = globalThis.fetch;
+      let round = 0;
+      restoreFetch = () => {
+        globalThis.fetch = origFetch;
+      };
+      globalThis.fetch = Object.assign(
+        async (_input: Parameters<typeof fetch>[0], _init?: RequestInit) => {
+          round += 1;
+          return new Response(
+            JSON.stringify({
+              choices: [
+                {
+                  message: {
+                    tool_calls: [
+                      {
+                        id: `loop-${round}`,
+                        type: "function",
+                        function: {
+                          name: "cas_get",
+                          arguments: JSON.stringify({ hash: h }),
+                        },
+                      },
+                    ],
+                  },
+                },
+              ],
+            }),
+            { status: 200, headers: { "Content-Type": "application/json" } },
+          );
+        },
+        { preconnect: origFetch.preconnect.bind(origFetch) },
+      ) as typeof fetch;
+
+      const result = await reactExtract({
+        text: "## Agent Output\nnoop\n## Extraction Instruction\nExtract seen.",
+        schema: metaSchema,
+        provider,
+        cas,
+      });
+
+      expect(result.ok).toBe(false);
+      if (result.ok) {
+        return;
+      }
+      expect(result.error).toBe("max_react_rounds_exceeded");
+      expect(round).toBe(10);
+    } finally {
+      await rm(casDir, { recursive: true, force: true });
+    }
+  });
+
+  test("passthrough JSON assistant message without tool calls", async () => {
+    const casDir = await mkdtemp(join(tmpdir(), "react-extract-pass-"));
+    const cas = createCasStore(casDir);
+    try {
+      const origFetch = globalThis.fetch;
+      restoreFetch = () => {
+        globalThis.fetch = origFetch;
+      };
+      globalThis.fetch = Object.assign(
+        async (_input: Parameters<typeof fetch>[0], _init?: RequestInit) =>
+          new Response(
+            JSON.stringify({
+              choices: [
+                {
+                  message: {
+                    content: '{"seen":"direct"}',
+                  },
+                },
+              ],
+            }),
+            { status: 200, headers: { "Content-Type": "application/json" } },
+          ),
+        { preconnect: origFetch.preconnect.bind(origFetch) },
+      ) as typeof fetch;
+
+      const result = await reactExtract({
+        text: "## Agent Output\nok\n## Extraction Instruction\nExtract.",
+        schema: metaSchema,
+        provider,
+        cas,
+      });
+
+      expect(result.ok).toBe(true);
+      if (!result.ok) {
+        return;
+      }
+      expect(result.value).toEqual({ seen: "direct" });
+    } finally {
+      await rm(casDir, { recursive: true, force: true });
+    }
+  });
+});

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

@@ -91,6 +91,7 @@ const refsDemoWorkflow = createWorkflow<RefsDemoMeta>(
         extractPrompt: "Extract phases with CAS hashes.",
         schema: plannerMetaSchema,
         extractRefs: (meta) => meta.phases.map((p) => p.hash),
+        extractMode: "single",
       },
     },
     moderator: (ctx) => (ctx.steps.length === 0 ? "planner" : END),
@@ -99,6 +100,7 @@ const refsDemoWorkflow = createWorkflow<RefsDemoMeta>(
     agent: async () => "plan-output",
   },
   refsDemoExtract,
+  null,
 );
 
 describe("RoleStep refs tracking", () => {

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

@@ -142,12 +142,14 @@ describe("workflowAsAgent integration", () => {
               extractPrompt: "extract done flag",
               schema: callerMetaSchema,
               extractRefs: null,
+              extractMode: "single",
             },
           },
           moderator: (ctx) => (ctx.steps.length === 0 ? "caller" : END),
         },
         { agent: workflowAsAgent("child-wf", { storageRoot: root }) },
         parentExtract,
+        null,
       );
 
       const threadId = "01KQXKW18CT8G75T53R8F4G7YG";

packages/workflow/src/create-workflow.ts

@@ -1,11 +1,14 @@
-import type { ExtractFn } from "./extract-fn.js";
+import type { CasStore } from "./cas.js";
+import { buildExtractUserContent, type ExtractFn } from "./extract-fn.js";
 import { putContentMerkleNode } from "./merkle.js";
+import { reactExtract } from "./react-extract.js";
 import { mergeRefsWithContentHash } from "./refs-field.js";
 import {
   type AgentBinding,
   type AgentContext,
   END,
   type ExtractContext,
+  type LlmProvider,
   type ModeratorContext,
   type RoleDefinition,
   type RoleMeta,
@@ -36,14 +39,51 @@ function resolveExtractedRefs(
   return extractRefsFn(meta as Record<string, unknown>);
 }
 
+async function resolveRoleMeta<M extends RoleMeta>(
+  roleDef: RoleDefinition<Record<string, unknown>>,
+  extractCtx: ExtractContext<M>,
+  extract: ExtractFn,
+  llmProvider: LlmProvider | null,
+  cas: CasStore,
+): Promise<Record<string, unknown>> {
+  if (roleDef.extractMode === "react") {
+    if (llmProvider === null) {
+      throw new Error(
+        'createWorkflow: llmProvider is required when a role uses extractMode "react"',
+      );
+    }
+    const text = await buildExtractUserContent(
+      extractCtx as unknown as ExtractContext,
+      roleDef.extractPrompt,
+    );
+    const reactResult = await reactExtract({
+      text,
+      schema: roleDef.schema,
+      provider: llmProvider,
+      cas,
+    });
+    if (!reactResult.ok) {
+      throw new Error(`react extract failed: ${reactResult.error}`);
+    }
+    return reactResult.value as Record<string, unknown>;
+  }
+  return (await extract(
+    roleDef.schema,
+    roleDef.extractPrompt,
+    extractCtx as unknown as ExtractContext,
+  )) as Record<string, unknown>;
+}
+
 /**
  * Binds pure role definitions + moderator to runtime agents and structured extraction.
- * Assign with `export const run = createWorkflow(def, binding, extract)`.
+ * Assign with `export const run = createWorkflow(def, binding, extract, llmProvider)`.
+ * Pass the same {@link LlmProvider} as {@link createExtract} when any role uses `extractMode: "react"`.
  */
 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,
@@ -107,10 +147,12 @@ export function createWorkflow<M extends RoleMeta>(
         agentContent: raw,
       };
 
-      const meta = await extract(
-        roleDef.schema,
-        roleDef.extractPrompt,
-        extractCtx as unknown as ExtractContext,
+      const meta = await resolveRoleMeta(
+        roleDef as unknown as RoleDefinition<Record<string, unknown>>,
+        extractCtx,
+        extract,
+        llmProvider,
+        options.cas,
       );
 
       const contentHash = await putContentMerkleNode(options.cas, raw);

packages/workflow/src/extract-fn.ts

@@ -10,6 +10,40 @@ export type ExtractFn = <T extends Record<string, unknown>>(
   ctx: ExtractContext,
 ) => Promise<T>;
 
+/** Builds the user-side extraction prompt (thread + agent output + instruction). */
+export async function buildExtractUserContent(
+  ctx: ExtractContext,
+  prompt: string,
+): Promise<string> {
+  const lines: string[] = [];
+  lines.push(`## Role: ${ctx.currentRole.name}`);
+  lines.push(ctx.currentRole.systemPrompt);
+  lines.push("");
+  lines.push("## Task");
+  lines.push(ctx.start.content);
+  lines.push("");
+  if (ctx.steps.length > 0) {
+    lines.push("## Thread History");
+    for (const step of ctx.steps) {
+      const body = await getContentMerklePayload(ctx.cas, step.contentHash);
+      if (body === null) {
+        throw new Error(`extract: missing CAS blob for step ${step.role}: ${step.contentHash}`);
+      }
+      lines.push(`### ${step.role}`);
+      lines.push(body);
+      lines.push(`Meta: ${JSON.stringify(step.meta)}`);
+      lines.push("");
+    }
+  }
+  lines.push("## Agent Output");
+  lines.push(ctx.agentContent);
+  lines.push("");
+  lines.push("## Extraction Instruction");
+  lines.push(prompt);
+
+  return lines.join("\n");
+}
+
 /**
  * Create an ExtractFn backed by an LLM provider.
  * Builds prompt text from {@link ExtractContext} plus `prompt` and calls structured extraction.
@@ -20,33 +54,7 @@ export function createExtract(provider: LlmProvider): ExtractFn {
     prompt: string,
     ctx: ExtractContext,
   ): Promise<T> => {
-    const lines: string[] = [];
-    lines.push(`## Role: ${ctx.currentRole.name}`);
-    lines.push(ctx.currentRole.systemPrompt);
-    lines.push("");
-    lines.push("## Task");
-    lines.push(ctx.start.content);
-    lines.push("");
-    if (ctx.steps.length > 0) {
-      lines.push("## Thread History");
-      for (const step of ctx.steps) {
-        const body = await getContentMerklePayload(ctx.cas, step.contentHash);
-        if (body === null) {
-          throw new Error(`extract: missing CAS blob for step ${step.role}: ${step.contentHash}`);
-        }
-        lines.push(`### ${step.role}`);
-        lines.push(body);
-        lines.push(`Meta: ${JSON.stringify(step.meta)}`);
-        lines.push("");
-      }
-    }
-    lines.push("## Agent Output");
-    lines.push(ctx.agentContent);
-    lines.push("");
-    lines.push("## Extraction Instruction");
-    lines.push(prompt);
-
-    const text = lines.join("\n");
+    const text = await buildExtractUserContent(ctx, prompt);
     const result = await llmExtractWithRetry({ text, schema, provider });
     if (!result.ok) {
       throw new Error(`extract failed: ${JSON.stringify(result.error)}`);

packages/workflow/src/index.ts

@@ -54,6 +54,7 @@ export {
   serializeMerkleNode,
   type ThreadMerklePayload,
 } from "./merkle.js";
+export { type ReactExtractArgs, reactExtract } from "./react-extract.js";
 export {
   type ExtractProviderConfig,
   getRegisteredWorkflow,
@@ -80,6 +81,7 @@ export {
   type AgentFn,
   END,
   type ExtractContext,
+  type ExtractMode,
   type LlmProvider,
   type Moderator,
   type ModeratorContext,

packages/workflow/src/llm-extract.ts

@@ -47,6 +47,21 @@ function readToolDescription(parametersSchema: Record<string, unknown>): string
   return "Extract structured data from the input text.";
 }
 
+/** Builds OpenAI function-tool metadata from a Zod meta schema (same naming rules as single-shot extract). */
+export function extractFunctionToolFromZodSchema(schema: z.ZodType<unknown>): {
+  name: string;
+  description: string;
+  parameters: Record<string, unknown>;
+} {
+  const rawJsonSchema = z.toJSONSchema(schema) as Record<string, unknown>;
+  const parameters = stripJsonSchemaMeta(rawJsonSchema);
+  return {
+    name: readToolName(parameters),
+    description: readToolDescription(parameters),
+    parameters,
+  };
+}
+
 function readToolArgumentsJson(parsed: unknown, previewSource: string): Result<string, LlmError> {
   if (!isRecord(parsed)) {
     return err({ kind: "invalid_response_json", message: "Top-level JSON is not an object" });
@@ -124,10 +139,7 @@ export function llmErrorToCause(error: LlmError): Error {
 async function performLlmExtract<T>(
   options: LlmExtractArgs<T> & { userContent: string },
 ): Promise<Result<T, LlmError>> {
-  const rawJsonSchema = z.toJSONSchema(options.schema) as Record<string, unknown>;
-  const parameters = stripJsonSchemaMeta(rawJsonSchema);
-  const toolName = readToolName(parameters);
-  const toolDescription = readToolDescription(parameters);
+  const extractTool = extractFunctionToolFromZodSchema(options.schema);
 
   const body = {
     model: options.provider.model,
@@ -142,13 +154,13 @@ async function performLlmExtract<T>(
       {
         type: "function" as const,
         function: {
-          name: toolName,
-          description: toolDescription,
-          parameters,
+          name: extractTool.name,
+          description: extractTool.description,
+          parameters: extractTool.parameters,
         },
       },
     ],
-    tool_choice: { type: "function" as const, function: { name: toolName } },
+    tool_choice: { type: "function" as const, function: { name: extractTool.name } },
   };
 
   let response: Response;

packages/workflow/src/react-extract.ts

@@ -0,0 +1,330 @@
+import type * as z from "zod/v4";
+
+import type { CasStore } from "./cas.js";
+import { extractFunctionToolFromZodSchema } from "./llm-extract.js";
+import { err, ok, type Result } from "./result.js";
+import type { LlmProvider } from "./types.js";
+
+export type ReactExtractArgs<T extends Record<string, unknown>> = {
+  text: string;
+  schema: z.ZodType<T>;
+  provider: LlmProvider;
+  cas: CasStore;
+};
+
+const MAX_REACT_ROUNDS = 10;
+
+const CAS_GET_TOOL_DEFINITION = {
+  type: "function" as const,
+  function: {
+    name: "cas_get",
+    description:
+      "Read a Merkle DAG node from content-addressed storage by its hash. Returns YAML-formatted node with type, payload, and children fields.",
+    parameters: {
+      type: "object",
+      properties: {
+        hash: { type: "string", description: "The CAS hash to retrieve" },
+      },
+      required: ["hash"],
+    },
+  },
+};
+
+function chatCompletionsUrl(baseUrl: string): string {
+  const trimmed = baseUrl.replace(/\/+$/, "");
+  return `${trimmed}/chat/completions`;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function tryParseJsonContent(content: string): unknown | null {
+  const trimmed = content.trim();
+  const fenceMatch = /^```(?:json)?\s*([\s\S]*?)```$/m.exec(trimmed);
+  const payload = fenceMatch !== null ? fenceMatch[1].trim() : trimmed;
+  try {
+    return JSON.parse(payload) as unknown;
+  } catch {
+    return null;
+  }
+}
+
+type ToolCall = {
+  id: string;
+  type: "function";
+  function: { name: string; arguments: string };
+};
+
+type ChatMessage =
+  | { role: "system"; content: string }
+  | { role: "user"; content: string }
+  | {
+      role: "assistant";
+      content: string | null;
+      tool_calls: ToolCall[];
+    }
+  | { role: "tool"; tool_call_id: string; content: string };
+
+type AssistantTurn<T> =
+  | { kind: "plain_json"; value: T }
+  | { kind: "tool_calls"; calls: ToolCall[]; assistantContent: string | null };
+
+function firstAssistantMessage(responseText: string): Result<Record<string, unknown>, string> {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(responseText) as unknown;
+  } catch (cause) {
+    const message = cause instanceof Error ? cause.message : String(cause);
+    return err(`invalid_response_json:${message}`);
+  }
+  if (!isRecord(parsed)) {
+    return err("invalid_response_top_level");
+  }
+  const choices = parsed.choices;
+  if (!Array.isArray(choices) || choices.length === 0) {
+    return err("no_choices_in_response");
+  }
+  const firstChoice = choices[0];
+  if (!isRecord(firstChoice)) {
+    return err("invalid_choice");
+  }
+  const messageObj = firstChoice.message;
+  if (!isRecord(messageObj)) {
+    return err("invalid_message");
+  }
+  return ok(messageObj);
+}
+
+function normalizeToolCalls(toolCallsRaw: unknown[]): Result<ToolCall[], string> {
+  const toolCalls: ToolCall[] = [];
+  for (const tc of toolCallsRaw) {
+    if (!isRecord(tc)) {
+      return err("invalid_tool_call");
+    }
+    const id = tc.id;
+    const tcType = tc.type;
+    const fn = tc.function;
+    if (typeof id !== "string" || tcType !== "function" || !isRecord(fn)) {
+      return err("invalid_tool_call_shape");
+    }
+    const name = fn.name;
+    const argumentsStr = fn.arguments;
+    if (typeof name !== "string" || typeof argumentsStr !== "string") {
+      return err("invalid_tool_call_function");
+    }
+    toolCalls.push({ id, type: "function", function: { name, arguments: argumentsStr } });
+  }
+  return ok(toolCalls);
+}
+
+function classifyAssistantTurn<T extends Record<string, unknown>>(
+  messageObj: Record<string, unknown>,
+  schema: z.ZodType<T>,
+): Result<AssistantTurn<T>, string> {
+  const toolCallsRaw = messageObj.tool_calls;
+  if (!Array.isArray(toolCallsRaw) || toolCallsRaw.length === 0) {
+    const content = messageObj.content;
+    if (typeof content !== "string") {
+      return err("no_tool_calls_and_no_string_content");
+    }
+    const jsonParsed = tryParseJsonContent(content);
+    if (jsonParsed === null) {
+      return err("no_tool_calls_and_content_not_json");
+    }
+    const validated = schema.safeParse(jsonParsed);
+    if (!validated.success) {
+      return err(`schema_validation_failed:${validated.error.message}`);
+    }
+    return ok({ kind: "plain_json", value: validated.data });
+  }
+  const callsResult = normalizeToolCalls(toolCallsRaw);
+  if (!callsResult.ok) {
+    return err(callsResult.error);
+  }
+  const assistantContent = messageObj.content;
+  return ok({
+    kind: "tool_calls",
+    calls: callsResult.value,
+    assistantContent: typeof assistantContent === "string" ? assistantContent : null,
+  });
+}
+
+async function appendCasGetToolResult(
+  tc: ToolCall,
+  cas: CasStore,
+  messages: ChatMessage[],
+): Promise<Result<null, string>> {
+  let hash: string;
+  try {
+    const ta = JSON.parse(tc.function.arguments) as unknown;
+    if (!isRecord(ta) || typeof ta.hash !== "string") {
+      return err("cas_get_invalid_arguments");
+    }
+    hash = ta.hash;
+  } catch {
+    return err("cas_get_arguments_not_json");
+  }
+  const blob = await cas.get(hash);
+  const toolContent = blob === null ? "null" : blob;
+  messages.push({
+    role: "tool",
+    tool_call_id: tc.id,
+    content: toolContent,
+  });
+  return ok(null);
+}
+
+async function appendExtractToolResult<T extends Record<string, unknown>>(
+  tc: ToolCall,
+  schema: z.ZodType<T>,
+  messages: ChatMessage[],
+): Promise<Result<T, string>> {
+  let parsedArgs: unknown;
+  try {
+    parsedArgs = JSON.parse(tc.function.arguments) as unknown;
+  } catch {
+    return err("extract_tool_arguments_not_json");
+  }
+  const validated = schema.safeParse(parsedArgs);
+  if (!validated.success) {
+    return err(`schema_validation_failed:${validated.error.message}`);
+  }
+  messages.push({
+    role: "tool",
+    tool_call_id: tc.id,
+    content: '{"ok":true}',
+  });
+  return ok(validated.data);
+}
+
+async function appendToolResults<T extends Record<string, unknown>>(
+  toolCalls: ToolCall[],
+  extractToolName: string,
+  schema: z.ZodType<T>,
+  cas: CasStore,
+  messages: ChatMessage[],
+): Promise<Result<T | null, string>> {
+  let extracted: T | null = null;
+  for (const tc of toolCalls) {
+    if (tc.function.name === "cas_get") {
+      const casRes = await appendCasGetToolResult(tc, cas, messages);
+      if (!casRes.ok) {
+        return casRes;
+      }
+      continue;
+    }
+    if (tc.function.name === extractToolName) {
+      const exRes = await appendExtractToolResult(tc, schema, messages);
+      if (!exRes.ok) {
+        return exRes;
+      }
+      extracted = exRes.value;
+      continue;
+    }
+    return err(`unknown_tool:${tc.function.name}`);
+  }
+  return ok(extracted);
+}
+
+async function postChatCompletion(
+  provider: LlmProvider,
+  messages: ChatMessage[],
+  tools: readonly Record<string, unknown>[],
+): Promise<Result<string, string>> {
+  try {
+    const response = await fetch(chatCompletionsUrl(provider.baseUrl), {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${provider.apiKey}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        model: provider.model,
+        messages,
+        tools,
+        tool_choice: "auto",
+      }),
+    });
+    const responseText = await response.text();
+    if (!response.ok) {
+      return err(`http_error:${String(response.status)}:${responseText.slice(0, 4000)}`);
+    }
+    return ok(responseText);
+  } catch (cause) {
+    const message = cause instanceof Error ? cause.message : String(cause);
+    return err(`network_error:${message}`);
+  }
+}
+
+/**
+ * Multi-turn ReAct extraction with `cas_get` plus a schema-shaped extract tool (OpenAI-compatible).
+ * Final meta comes from a successful extract tool call or from plain JSON in the assistant message.
+ */
+export async function reactExtract<T extends Record<string, unknown>>(
+  args: ReactExtractArgs<T>,
+): Promise<Result<T, string>> {
+  const extractTool = extractFunctionToolFromZodSchema(args.schema);
+  const tools = [
+    CAS_GET_TOOL_DEFINITION,
+    {
+      type: "function" as const,
+      function: {
+        name: extractTool.name,
+        description: extractTool.description,
+        parameters: extractTool.parameters,
+      },
+    },
+  ];
+
+  const systemContent = `You extract structured metadata from the agent output below. Use cas_get to read Merkle DAG nodes from CAS (YAML: type, payload, children) when the agent output references hashes you must traverse. When you have the complete structured object, call the ${extractTool.name} tool with JSON arguments matching the schema. You may instead reply with only a JSON object (no prose) when no tools are needed.`;
+
+  const messages: ChatMessage[] = [
+    { role: "system", content: systemContent },
+    { role: "user", content: args.text },
+  ];
+
+  for (let round = 0; round < MAX_REACT_ROUNDS; round++) {
+    const bodyResult = await postChatCompletion(args.provider, messages, tools);
+    if (!bodyResult.ok) {
+      return bodyResult;
+    }
+
+    const msgResult = firstAssistantMessage(bodyResult.value);
+    if (!msgResult.ok) {
+      return msgResult;
+    }
+
+    const classified = classifyAssistantTurn(msgResult.value, args.schema);
+    if (!classified.ok) {
+      return classified;
+    }
+
+    const turn = classified.value;
+    if (turn.kind === "plain_json") {
+      return ok(turn.value);
+    }
+
+    messages.push({
+      role: "assistant",
+      content: turn.assistantContent,
+      tool_calls: turn.calls,
+    });
+
+    const toolsRound = await appendToolResults(
+      turn.calls,
+      extractTool.name,
+      args.schema,
+      args.cas,
+      messages,
+    );
+    if (!toolsRound.ok) {
+      return toolsRound;
+    }
+    if (toolsRound.value !== null) {
+      return ok(toolsRound.value);
+    }
+  }
+
+  return err("max_react_rounds_exceeded");
+}

packages/workflow/src/types.ts

@@ -16,6 +16,9 @@ export type LlmProvider = {
   model: string;
 };
 
+/** How the engine runs meta extraction for a role after the agent phase. */
+export type ExtractMode = "single" | "react";
+
 /** What each generator yield produces — one role's output (engine adds `timestamp` when persisting). */
 export type RoleOutput = {
   role: string;
@@ -121,6 +124,7 @@ export type RoleDefinition<Meta extends Record<string, unknown>> = {
   schema: z.ZodType<Meta>;
   /** When non-null, produces CAS hashes to persist on this role's steps (see `RoleOutput.refs`). */
   extractRefs: ((meta: Meta) => string[]) | null;
+  extractMode: ExtractMode;
 };
 
 /**