chore: remove link-all.sh

Local symlink workflow replaced by Gitea npm registry publish flow.

Signed-off-by: 小橘 <xiaoju@shazhou.work>

.gitignore

@@ -5,4 +5,3 @@ bun.lock
 tsconfig.tsbuildinfo
 .npmrc
 
-bunfig.toml

bunfig.toml

@@ -0,0 +1,2 @@
+[test]
+pathIgnorePatterns = ["dist/**"]

package.json

@@ -18,7 +18,6 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.14",
-    "@types/node": "^25.7.0",
     "@types/xxhashjs": "^0.2.4",
     "bun-types": "^1.3.13"
   }

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

@@ -91,7 +91,7 @@ describe("init workspace", () => {
       "RoleDefinition",
       "WorkflowDefinition",
       "ModeratorTable",
-      "AdapterFn",
+      "AgentFn",
       "ExtractFn",
       "RoleMeta",
     ]) {

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

@@ -70,10 +70,10 @@ const cliEntryPath = fileURLToPath(new URL("../src/cli.ts", import.meta.url));
 const abortablePlannerBundleSource = `${threadFixtureDescriptor}
 ${wfPutImport}
 export const run = async function* (input, options) {
+  await new Promise((r) => setTimeout(r, 600));
   const cas = options.cas;
   let h = await putContentMerkleNode(cas, "plan");
   yield { role: "planner", contentHash: h, meta: { plan: input.prompt }, refs: [h] };
-  await new Promise((r) => setTimeout(r, 10000));
   h = await putContentMerkleNode(cas, "code");
   yield { role: "coder", contentHash: h, meta: { diff: "y" }, refs: [h] };
   return { returnCode: 0, summary: "done" };

packages/cli-workflow/package.json

@@ -1,11 +1,6 @@
 {
   "name": "@uncaged/cli-workflow",
-  "version": "0.3.21",
-  "files": [
-    "src",
-    "dist",
-    "package.json"
-  ],
+  "version": "0.3.11",
   "type": "module",
   "bin": {
     "uncaged-workflow": "src/cli.ts"

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

@@ -5,6 +5,7 @@ import { err, ok, type Result } from "@uncaged/workflow-protocol";
 
 import { pathExists } from "../../fs-utils.js";
 import type { CmdInitWorkspaceSuccess } from "./types.js";
+import { validateWorkspaceSegment } from "./validate.js";
 
 function rootPackageJson(workspaceName: string): string {
   return `${JSON.stringify(
@@ -90,7 +91,7 @@ function agentsMd(): string {
 |------|----------------|------|
 | **Workspace** | 仓库根（\`package.json\` 含 \`workspaces: ["templates/*", "workflows"]\`） | Bun monorepo：统一管理本地模板包与 workflow 实例 |
 | **Template** | \`templates/<name>/\`（如 \`src/roles.ts\`、\`src/moderator.ts\`、\`src/index.ts\`） | 纯数据：**WorkflowDefinition**（各 **RoleDefinition** + **ModeratorTable**），**不绑定**具体 Agent |
-| **Workflow instance** | \`workflows/\`（或单独包） | 把模板与运行时 **AdapterFn** / **ExtractFn** 组合，产出可注册的 **单文件 ESM bundle**（\`run\` + \`descriptor\` 命名导出） |
+| **Workflow instance** | \`workflows/\`（或单独包） | 把模板与运行时 **AgentFn** / **ExtractFn** 组合，产出可注册的 **单文件 ESM bundle**（\`run\` + \`descriptor\` 命名导出） |
 
 Init 生成的骨架：\`templates/\` 下放可复用定义，\`workflows/\` 下放绑定与打包入口。
 
@@ -100,10 +101,10 @@ Init 生成的骨架：\`templates/\` 下放可复用定义，\`workflows/\` 下
 - **RoleDefinition<Meta>**：纯数据——\`description\`、\`systemPrompt\`、\`schema\`（Zod v4）。不含执行逻辑。
 - **WorkflowDefinition<M extends RoleMeta>**：\`description\` + \`roles\`（各角色定义）+ **ModeratorTable**（声明式路由表）。
 - **ModeratorTable**：从 \`START\` 与各角色名映射到有序 transition 列表（条件 + 下一角色或 \`END\`）；可序列化，供描述符提取 **graph**。
-- **AdapterFn**：接收系统提示词与 Zod schema，返回角色执行函数（RoleFn）。
-- **ExtractFn**：从 CAS content hash 解析结构化数据（引擎与 Adapter 都可使用）。
+- **AgentFn**：\`(ctx: AgentContext) => Promise<string>\`，原始文本输出；从上下文读取当前角色的 \`systemPrompt\`。
+- **ExtractFn**：从 CAS content hash 解析结构化数据（引擎与 Agent 都可使用）。
 
-引擎循环简述：按 **ModeratorTable** 选下一角色 → **Adapter** 产出 typed meta → 追加 step，重复直至 **END**。详见 \`docs/architecture.md\` 中的三阶段说明。
+引擎循环简述：按 **ModeratorTable** 选下一角色 → **Agent** 产出文本 → **Extract** 写入 **meta** → 追加 step，重复直至 **END**。详见 \`docs/architecture.md\` 中的三阶段说明。
 
 ## 3. 开发流程
 
@@ -111,7 +112,7 @@ Init 生成的骨架：\`templates/\` 下放可复用定义，\`workflows/\` 下
 2. **编写 RoleDefinition**：为每个角色写 Zod \`schema\`，补齐 \`systemPrompt\` / \`description\`。
 3. **编写 ModeratorTable**：为 \`START\` 与各角色声明 transition（\`FALLBACK\` 或命名条件 + \`check\`）。
 4. **组装 WorkflowDefinition**：在模板 \`index\` 中导出 definition（以及必要的角色 / table 导出）。
-5. **实例化**：在 workflow 包中使用 \`createWorkflow(def, binding)\`（或项目约定的封装）绑定 **AdapterFn**；**ExtractFn** 由引擎从 **workflow.yaml** 注入 \`WorkflowRuntime\`。
+5. **实例化**：在 workflow 包中使用 \`createWorkflow(def, binding)\`（或项目约定的封装）绑定 **AgentFn**；**ExtractFn** 由引擎从 **workflow.yaml** 注入 \`WorkflowRuntime\`。
 6. **构建**：打包为单个 **.esm.js** bundle，使用 **uncaged-workflow add** 注册。
 
 ## 4. 编码规范

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

@@ -1,7 +1,7 @@
 import { existsSync } from "node:fs";
-import { resolve as resolvePath } from "node:path";
 import { stdin as input, stdout as output } from "node:process";
 import { createInterface } from "node:readline/promises";
+import { resolve as resolvePath } from "node:path";
 
 import { err, ok, type Result } from "@uncaged/workflow-protocol";
 
@@ -10,7 +10,6 @@ import { createLogger } from "@uncaged/workflow-util";
 import { printCliError, printCliLine, printCliWarn } from "../../cli-output.js";
 
 const setupDispatchLog = createLogger({ sink: { kind: "stderr" } });
-
 import { loadPresetProviders } from "./preset-providers.js";
 import { cmdSetup, printSetupSummary } from "./setup.js";
 import type { SetupCliArgs } from "./types.js";
@@ -155,67 +154,11 @@ async function promptLine(
   return raw.trim();
 }
 
-type SecretInputState = {
-  buf: string;
-  rawWasSet: boolean;
-  onData: (chunk: string) => void;
-  fulfill: (value: string) => void;
-};
-
-function isLineTerminator(c: string): boolean {
-  return c === "\n" || c === "\r" || c === "\u0004";
-}
-
-function handleLineTerminator(state: SecretInputState): void {
-  if (process.stdin.isTTY) {
-    process.stdin.setRawMode(state.rawWasSet);
-  }
-  process.stdin.pause();
-  process.stdin.removeListener("data", state.onData);
-  process.stdout.write("\n");
-  state.fulfill(state.buf.trim());
-}
-
-function handleBackspace(state: SecretInputState): void {
-  if (state.buf.length > 0) {
-    state.buf = state.buf.slice(0, -1);
-    process.stdout.write("\b \b");
-  }
-}
-
-function handleInterrupt(rawWasSet: boolean): void {
-  if (process.stdin.isTTY) {
-    process.stdin.setRawMode(rawWasSet);
-  }
-  process.exit(130);
-}
-
-function isBackspace(c: string): boolean {
-  return c === "\u007F" || c === "\b";
-}
-
-/** Process a single character in secret input. Returns "done" to stop reading. */
-function processSecretChar(c: string, state: SecretInputState): "done" | "skip" | "append" {
-  if (isLineTerminator(c)) {
-    handleLineTerminator(state);
-    return "done";
-  }
-  if (isBackspace(c)) {
-    handleBackspace(state);
-    return "skip";
-  }
-  if (c === "\u0003") {
-    handleInterrupt(state.rawWasSet);
-  }
-  state.buf += c;
-  process.stdout.write("*");
-  return "append";
-}
-
 /** Read a line with terminal echo disabled (for secrets). */
 async function promptSecret(label: string): Promise<string> {
   process.stdout.write(label);
   return new Promise((fulfill) => {
+    let buf = "";
     const rawWasSet = process.stdin.isRaw;
     if (process.stdin.isTTY) {
       process.stdin.setRawMode(true);
@@ -223,22 +166,46 @@ async function promptSecret(label: string): Promise<string> {
     process.stdin.resume();
     process.stdin.setEncoding("utf8");
 
-    const state: SecretInputState = { buf: "", rawWasSet, fulfill, onData: () => {} };
-
     const onData = (chunk: string) => {
       for (const c of chunk.toString()) {
-        if (processSecretChar(c, state) === "done") return;
+        if (c === "\n" || c === "\r" || c === "\u0004") {
+          if (process.stdin.isTTY) {
+            process.stdin.setRawMode(rawWasSet);
+          }
+          process.stdin.pause();
+          process.stdin.removeListener("data", onData);
+          process.stdout.write("\n");
+          fulfill(buf.trim());
+          return;
+        }
+        if (c === "\u007F" || c === "\b") {
+          if (buf.length > 0) {
+            buf = buf.slice(0, -1);
+            process.stdout.write("\b \b");
+          }
+          continue;
+        }
+        if (c === "\u0003") {
+          if (process.stdin.isTTY) {
+            process.stdin.setRawMode(rawWasSet);
+          }
+          process.exit(130);
+        }
+        buf += c;
+        process.stdout.write("*");
       }
     };
 
-    state.onData = onData;
     process.stdin.on("data", onData);
   });
 }
 
 /** Fetch available models from an OpenAI-compatible /models endpoint. */
-async function fetchAvailableModels(baseUrl: string, apiKey: string): Promise<string[]> {
-  const url = `${baseUrl.replace(/\/+$/, "")}/models`;
+async function fetchAvailableModels(
+  baseUrl: string,
+  apiKey: string,
+): Promise<string[]> {
+  const url = baseUrl.replace(/\/+$/, "") + "/models";
   try {
     const res = await fetch(url, {
       headers: { Authorization: `Bearer ${apiKey}` },
@@ -261,158 +228,139 @@ async function fetchAvailableModels(baseUrl: string, apiKey: string): Promise<st
       .filter((id) => !NON_CHAT_RE.test(id))
       .sort();
   } catch (e) {
-    setupDispatchLog(
-      "V8NQ4JT6",
-      `fetch models failed: ${e instanceof Error ? e.message : String(e)}`,
-    );
+    setupDispatchLog("V8NQ4JT6", `fetch models failed: ${e instanceof Error ? e.message : String(e)}`);
     return [];
   }
 }
 
-type PresetProvider = ReturnType<typeof loadPresetProviders>[number];
-
-function printProviderMenu(presets: readonly PresetProvider[]): void {
-  const numWidth = String(presets.length + 1).length;
-  printCliLine("Select a provider:\n");
-  for (let i = 0; i < presets.length; i++) {
-    const p = presets.at(i);
-    if (!p) continue;
-    const num = String(i + 1).padStart(numWidth);
-    printCliLine(`  ${num}) ${p.label.padEnd(28)} ${p.baseUrl}`);
-  }
-  const customNum = String(presets.length + 1).padStart(numWidth);
-  printCliLine(`  ${customNum}) Custom (enter name and URL manually)`);
-  printCliLine("");
-}
-
-async function selectProvider(
-  rl: { question: (q: string) => Promise<string> },
-  presets: readonly PresetProvider[],
-): Promise<Result<{ provider: string; baseUrl: string }, string>> {
-  const choice = await promptLine(rl, `Choose [1-${presets.length + 1}]: `);
-  const choiceNum = Number.parseInt(choice, 10);
-  if (Number.isNaN(choiceNum) || choiceNum < 1 || choiceNum > presets.length + 1) {
-    return err(`invalid choice: ${choice}`);
-  }
-
-  if (choiceNum <= presets.length) {
-    const selected = presets.at(choiceNum - 1);
-    if (!selected) return err(`invalid choice: ${choice}`);
-    printCliLine(`\n  → ${selected.label} (${selected.baseUrl})\n`);
-    return ok({ provider: selected.name, baseUrl: selected.baseUrl });
-  }
-
-  const provider = await promptLine(rl, "Provider name (e.g. my-proxy): ");
-  if (provider === "") return err("provider name must not be empty");
-  const baseUrl = await promptLine(rl, "OpenAI-compatible API base URL: ");
-  if (baseUrl === "") return err("base URL must not be empty");
-  return ok({ provider, baseUrl });
-}
-
-function printModelList(models: string[]): void {
-  const cols = process.stdout.columns || 80;
-  const nw = String(models.length).length;
-  const prefixLen = nw + 4;
-  const maxModelLen = Math.max(...models.map((m) => m.length));
-  const cellWidth = prefixLen + maxModelLen + 2;
-  const numCols = Math.max(1, Math.floor(cols / cellWidth));
-  for (let i = 0; i < models.length; i += numCols) {
-    const cells: string[] = [];
-    for (let j = i; j < Math.min(i + numCols, models.length); j++) {
-      const num = String(j + 1).padStart(nw);
-      const model = models.at(j) ?? "";
-      cells.push(`  ${num}) ${model.padEnd(maxModelLen + 2)}`);
-    }
-    printCliLine(cells.join(""));
-  }
-}
-
-async function selectModel(
-  rl: { question: (q: string) => Promise<string> },
-  models: string[],
-): Promise<Result<string, string>> {
-  if (models.length > 0) {
-    printCliLine(`\nAvailable models (${models.length}):\n`);
-    printModelList(models);
-    printCliLine(`\nChoose a number, or type a model name directly.`);
-    const modelInput = await promptLine(rl, `Default model [1-${models.length}]: `);
-    if (modelInput === "") return err("default model must not be empty");
-    const modelNum = Number.parseInt(modelInput, 10);
-    if (!Number.isNaN(modelNum) && modelNum >= 1 && modelNum <= models.length) {
-      return ok(models.at(modelNum - 1) ?? modelInput);
-    }
-    return ok(modelInput);
-  }
-
-  printCliWarn("Could not fetch models (API may not support /models endpoint).");
-  const modelInput = await promptLine(rl, `Default model (e.g. qwen-plus, gpt-4o): `);
-  if (modelInput === "") return err("default model must not be empty");
-  return ok(modelInput);
-}
-
-async function selectWorkspace(rl: {
-  question: (q: string) => Promise<string>;
-}): Promise<string | null> {
-  while (true) {
-    const wsPath = await promptLine(
-      rl,
-      "\nWorkflow workspace path (default: ./workflows, type 'skip' to skip): ",
-    );
-    if (wsPath.toLowerCase() === "skip") return null;
-    const candidate = wsPath === "" ? "./workflows" : wsPath;
-    const resolved = resolvePath(process.cwd(), candidate);
-    if (existsSync(resolved)) {
-      printCliWarn(`directory already exists: ${resolved}`);
-      printCliLine("Please enter a different path, or type 'skip' to skip.");
-      continue;
-    }
-    return candidate;
-  }
-}
-
-function stripProviderPrefix(model: string): string {
-  if (model.includes("/")) {
-    return model.split("/").pop() ?? model;
-  }
-  return model;
-}
-
 async function collectInteractiveSetup(): Promise<Result<SetupCliArgs, string>> {
   const rl = createInterface({ input, output });
   try {
     printCliLine("Configure the LLM provider that workflow agents will use.\n");
 
     const presets = loadPresetProviders();
-    printProviderMenu(presets);
-
-    const providerResult = await selectProvider(rl, presets);
-    if (!providerResult.ok) {
-      rl.close();
-      return providerResult;
+    const numWidth = String(presets.length + 1).length;
+    printCliLine("Select a provider:\n");
+    for (let i = 0; i < presets.length; i++) {
+      const p = presets[i]!;
+      const num = String(i + 1).padStart(numWidth);
+      printCliLine(`  ${num}) ${p.label.padEnd(28)} ${p.baseUrl}`);
     }
-    const { provider, baseUrl } = providerResult.value;
+    const customNum = String(presets.length + 1).padStart(numWidth);
+    printCliLine(`  ${customNum}) Custom (enter name and URL manually)`);
+    printCliLine("");
 
+    const choice = await promptLine(rl, `Choose [1-${presets.length + 1}]: `);
+    const choiceNum = Number.parseInt(choice, 10);
+    if (Number.isNaN(choiceNum) || choiceNum < 1 || choiceNum > presets.length + 1) {
+      rl.close();
+      return err(`invalid choice: ${choice}`);
+    }
+
+    let provider: string;
+    let baseUrl: string;
+    if (choiceNum <= presets.length) {
+      const selected = presets[choiceNum - 1]!;
+      provider = selected.name;
+      baseUrl = selected.baseUrl;
+      printCliLine(`\n  → ${selected.label} (${baseUrl})\n`);
+    } else {
+      provider = await promptLine(rl, "Provider name (e.g. my-proxy): ");
+      if (provider === "") {
+        return err("provider name must not be empty");
+      }
+      baseUrl = await promptLine(rl, "OpenAI-compatible API base URL: ");
+      if (baseUrl === "") {
+        return err("base URL must not be empty");
+      }
+    }
+
+    // Close readline before raw-mode secret prompt, reopen after.
     rl.close();
     const apiKey = await promptSecret("API key for this provider: ");
-    if (apiKey === "") return err("API key must not be empty");
+    if (apiKey === "") {
+      return err("API key must not be empty");
+    }
     const rl2 = createInterface({ input, output });
 
+    // Try to list available models from the provider.
     printCliLine("\nFetching available models...");
     const models = await fetchAvailableModels(baseUrl, apiKey);
-    const modelResult = await selectModel(rl2, models);
-    if (!modelResult.ok) {
-      rl2.close();
-      return modelResult;
+    let selectedModel: string;
+    if (models.length > 0) {
+      printCliLine(`\nAvailable models (${models.length}):\n`);
+      const cols = process.stdout.columns || 80;
+      const nw = String(models.length).length; // number width
+      // Each cell: "  <num>) <model>  " — prefix is 2 + nw + 2 = nw+4
+      const prefixLen = nw + 4;
+      const maxModelLen = Math.max(...models.map((m) => m.length));
+      const cellWidth = prefixLen + maxModelLen + 2; // +2 gap between columns
+      const numCols = Math.max(1, Math.floor(cols / cellWidth));
+      for (let i = 0; i < models.length; i += numCols) {
+        const cells: string[] = [];
+        for (let j = i; j < Math.min(i + numCols, models.length); j++) {
+          const num = String(j + 1).padStart(nw);
+          cells.push(`  ${num}) ${(models[j]!).padEnd(maxModelLen + 2)}`);
+        }
+        printCliLine(cells.join(""));
+      }
+      printCliLine(`\nChoose a number, or type a model name directly.`);
+      const modelInput = await promptLine(rl2, `Default model [1-${models.length}]: `);
+      if (modelInput === "") {
+        rl2.close();
+        return err("default model must not be empty");
+      }
+      const modelNum = Number.parseInt(modelInput, 10);
+      if (!Number.isNaN(modelNum) && modelNum >= 1 && modelNum <= models.length) {
+        selectedModel = models[modelNum - 1]!;
+      } else {
+        // Treat as a literal model name.
+        selectedModel = modelInput;
+      }
+    } else {
+      printCliWarn("Could not fetch models (API may not support /models endpoint).");
+      const modelInput = await promptLine(rl2, `Default model (e.g. qwen-plus, gpt-4o): `);
+      if (modelInput === "") {
+        rl2.close();
+        return err("default model must not be empty");
+      }
+      selectedModel = modelInput;
     }
-
-    const bare = stripProviderPrefix(modelResult.value);
+    // Strip provider prefix if user included one (e.g. pasted "MiniMax/MiniMax-M2.7").
+    const bare = selectedModel.includes("/") ? selectedModel.split("/").pop()! : selectedModel;
     const defaultModel = `${provider}/${bare}`;
     printCliLine(`  → ${defaultModel}`);
 
-    const initWorkspaceName = await selectWorkspace(rl2);
+    let initWorkspaceName: string | null = null;
+    // Loop until a valid workspace path is provided or the user skips.
+    while (true) {
+      const wsPath = await promptLine(
+        rl2,
+        "\nWorkflow workspace path (default: ./workflows, type 'skip' to skip): ",
+      );
+      if (wsPath.toLowerCase() === "skip") {
+        break;
+      }
+      const candidate = wsPath === "" ? "./workflows" : wsPath;
+      // Validate path before passing to cmdSetup.
+      const resolved = resolvePath(process.cwd(), candidate);
+      if (existsSync(resolved)) {
+        printCliWarn(`directory already exists: ${resolved}`);
+        printCliLine("Please enter a different path, or type 'skip' to skip.");
+        continue;
+      }
+      initWorkspaceName = candidate;
+      break;
+    }
     rl2.close();
 
-    return ok({ provider, baseUrl, apiKey, defaultModel, initWorkspaceName });
+    return ok({
+      provider,
+      baseUrl,
+      apiKey,
+      defaultModel,
+      initWorkspaceName,
+    });
   } catch (e) {
     return err(e instanceof Error ? e.message : String(e));
   }

packages/cli-workflow/src/commands/setup/preset-providers.ts

@@ -5,43 +5,45 @@ import { parse as parseYaml } from "yaml";
 
 import type { PresetProvider } from "./types.js";
 
+
+
 type RawPresetEntry = {
-  name: unknown;
-  label: unknown;
-  baseUrl: unknown;
+	name: unknown;
+	label: unknown;
+	baseUrl: unknown;
 };
 
 function isRawEntry(v: unknown): v is RawPresetEntry {
-  if (typeof v !== "object" || v === null) return false;
-  const o = v as Record<string, unknown>;
-  return typeof o.name === "string" && typeof o.label === "string" && typeof o.baseUrl === "string";
+	if (typeof v !== "object" || v === null) return false;
+	const o = v as Record<string, unknown>;
+	return typeof o.name === "string" && typeof o.label === "string" && typeof o.baseUrl === "string";
 }
 
 let cached: ReadonlyArray<PresetProvider> | null = null;
 
 export function loadPresetProviders(): ReadonlyArray<PresetProvider> {
-  if (cached !== null) return cached;
+	if (cached !== null) return cached;
 
-  const yamlPath = join(import.meta.dirname, "providers.yaml");
-  const raw = readFileSync(yamlPath, "utf8");
-  const parsed: unknown = parseYaml(raw);
+	const yamlPath = join(import.meta.dirname, "providers.yaml");
+	const raw = readFileSync(yamlPath, "utf8");
+	const parsed: unknown = parseYaml(raw);
 
-  if (!Array.isArray(parsed)) {
-    throw new Error(`providers.yaml: expected array, got ${typeof parsed}`);
-  }
+	if (!Array.isArray(parsed)) {
+		throw new Error(`providers.yaml: expected array, got ${typeof parsed}`);
+	}
 
-  const result: PresetProvider[] = [];
-  for (const entry of parsed) {
-    if (!isRawEntry(entry)) {
-      throw new Error(`providers.yaml: invalid entry: ${JSON.stringify(entry)}`);
-    }
-    result.push({
-      name: entry.name as string,
-      label: entry.label as string,
-      baseUrl: entry.baseUrl as string,
-    });
-  }
+	const result: PresetProvider[] = [];
+	for (const entry of parsed) {
+		if (!isRawEntry(entry)) {
+			throw new Error(`providers.yaml: invalid entry: ${JSON.stringify(entry)}`);
+		}
+		result.push({
+			name: entry.name as string,
+			label: entry.label as string,
+			baseUrl: entry.baseUrl as string,
+		});
+	}
 
-  cached = result;
-  return result;
+	cached = result;
+	return result;
 }

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

@@ -13,6 +13,8 @@ import type { CmdSetupSuccess, SetupCliArgs } from "./types.js";
 
 const setupLog = createLogger({ sink: { kind: "stderr" } });
 
+
+
 function mergeWorkflowConfig(
   prev: WorkflowConfig | null,
   input: SetupCliArgs,

packages/cli-workflow/src/skill.ts

@@ -183,63 +183,35 @@ How to build, test, and publish workflow bundles for uncaged-workflow.
 A workflow bundle is a single ESM file (\`.esm.js\`) that exports:
 
 \`\`\`typescript
-// Required named exports (no default export)
+// Required exports
 export const descriptor: WorkflowDescriptor;
-export const run: WorkflowFn;
+export const run: WorkflowRun;
 \`\`\`
 
 ## WorkflowDescriptor
 
-Serialized metadata for the registry. Every role must include both \`description\` and \`schema\` (JSON Schema object). The graph uses an edges array where each edge has \`from\`, \`to\`, and \`condition\`.
+Serialized metadata for the registry (per-role JSON Schema plus a static routing graph):
 
 \`\`\`typescript
 type WorkflowDescriptor = {
   description: string;
-  roles: Record<string, {
-    description: string;
-    schema: object;  // JSON Schema — use z.toJSONSchema(zodSchema) to generate
-  }>;
+  roles: Record<string, { description: string; schema: unknown /* JSON Schema */ }>;
   graph: {
     edges: Array<{
-      from: string;       // role name, or "__start__"
-      to: string;         // role name, or "__end__"
-      condition: string;  // e.g. "FALLBACK"
-      conditionDescription?: string | null;
+      from: string;
+      to: string;
+      condition: string;
+      conditionDescription: string | null;
     }>;
   };
 };
 \`\`\`
 
-**descriptor is static data** — it is read at \`workflow add\` (register) time via \`import()\`. It must NOT trigger any side effects or read environment variables.
-
-## WorkflowFn
+## WorkflowRun
 
 Async generator from \`createWorkflow(definition, binding)\` (**@uncaged/workflow-runtime**) — yields each role output until the workflow completes.
 
-## ModeratorTable
-
-Declarative routing table. Transitions use the \`role\` field (not \`next\`):
-
-\`\`\`typescript
-import { START, END, type ModeratorTable } from "@uncaged/workflow-runtime";
-
-const table: ModeratorTable<MyMeta> = {
-  [START]: [{ condition: "FALLBACK", role: "firstRole" }],
-  firstRole: [{ condition: "FALLBACK", role: END }],
-};
-\`\`\`
-
-## AdapterFn / AdapterBinding
-
-The adapter receives a system prompt and Zod schema, returns a \`RoleFn<T>\` that produces typed meta:
-
-\`\`\`typescript
-type AdapterFn = <T>(prompt: string, schema: ZodType<T>) => RoleFn<T>;
-type AdapterBinding = {
-  adapter: AdapterFn;
-  overrides: Partial<Record<string, AdapterFn>> | null;
-};
-\`\`\`
+The **ModeratorTable** on **WorkflowDefinition** is declarative routing (from each role and \`START\` to the next role or \`END\`); the engine evaluates conditions at runtime.
 
 ## Role Definition
 
@@ -258,16 +230,15 @@ Each role has:
 # 1. Initialize a workspace
 uncaged-workflow init workspace my-workflow
 
-# 2. Write your template (roles + ModeratorTable + definition)
-# 3. Write entry file (workflows/*-entry.ts) with adapter binding + descriptor
+# 2. Write your template (roles + ModeratorTable + descriptor)
 
-# 4. Build the ESM bundle
-bun run bundle   # uses scripts/bundle.ts
+# 3. Build the ESM bundle
+bun run build
 
-# 5. Register locally
-uncaged-workflow workflow add my-workflow ./dist/my-workflow-entry.esm.js
+# 4. Register locally
+uncaged-workflow workflow add my-workflow ./dist/my-workflow.esm.js
 
-# 6. Test
+# 5. Test
 uncaged-workflow run my-workflow --prompt "test task"
 uncaged-workflow live --latest
 \`\`\`
@@ -275,46 +246,5 @@ uncaged-workflow live --latest
 ## Versioning
 
 Bundles are immutable and identified by XXH64 hash. Re-registering a workflow with a new bundle creates a new version. Use \`workflow history\` and \`workflow rollback\` to manage versions.
-
-## Pitfalls
-
-### Lazy initialization is mandatory
-
-The bundle is \`import()\`-ed at register time (\`workflow add\`) to read the descriptor. At that point, no runtime env vars (API keys, etc.) are available.
-
-**Never read env at module top-level.** Wrap provider/adapter creation in a lazy closure:
-
-\`\`\`typescript
-// ❌ WRONG — breaks register
-const provider = { apiKey: process.env.MY_KEY! };
-const adapter = createAdapter(provider);
-
-// ✅ CORRECT — only reads env when run() is called
-function createLazyAdapter(): AdapterFn {
-  let cached: Provider | null = null;
-  return (prompt, schema) => {
-    return async (ctx, runtime) => {
-      if (!cached) cached = { apiKey: process.env.MY_KEY! };
-      // ... use cached provider
-    };
-  };
-}
-\`\`\`
-
-### Bundle import restrictions
-
-The bundle validator only allows these import specifiers:
-- Node built-ins (\`node:fs\`, \`node:path\`, etc.)
-- \`@uncaged/workflow-*\` packages
-
-Third-party packages (**including zod**) must be bundled into the \`.esm.js\` file, not left as external imports. When using \`bun build\`, only mark \`@uncaged/*\` as external.
-
-### No default exports
-
-The engine only reads named exports \`run\` and \`descriptor\`. Using \`export default\` will cause registration to fail silently.
-
-### Single-file ESM
-
-The bundle must be a single \`.esm.js\` file. No dynamic \`import()\` inside the bundle — it breaks hash verification and the loader sandbox.
 `;
 }

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

@@ -79,7 +79,7 @@ describe("validateCursorAgentConfig", () => {
 });
 
 describe("createCursorAgent", () => {
-  test("returns an AdapterFn with explicit workspace", () => {
+  test("returns an AgentFn with explicit workspace", () => {
     const agent = createCursorAgent({
       command: "/usr/local/bin/cursor-agent",
       model: null,
@@ -90,7 +90,7 @@ describe("createCursorAgent", () => {
     expect(typeof agent).toBe("function");
   });
 
-  test("returns an AdapterFn with null workspace and llmProvider", () => {
+  test("returns an AgentFn with null workspace and llmProvider", () => {
     const agent = createCursorAgent({
       command: "/usr/local/bin/cursor-agent",
       model: null,

packages/workflow-agent-cursor/package.json

@@ -1,10 +1,6 @@
 {
   "name": "@uncaged/workflow-agent-cursor",
-  "version": "0.3.21",
-  "files": [
-    "dist",
-    "package.json"
-  ],
+  "version": "0.3.11",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -18,11 +14,5 @@
     "@uncaged/workflow-util": "workspace:*",
     "@uncaged/workflow-util-agent": "workspace:*",
     "zod": "^4.0.0"
-  },
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./src/index.ts"
-    }
   }
 }

packages/workflow-agent-cursor/src/index.ts

@@ -1,11 +1,6 @@
-import type { AdapterFn } from "@uncaged/workflow-runtime";
+import type { AgentFn } from "@uncaged/workflow-runtime";
 import { createLogger } from "@uncaged/workflow-util";
-import {
-  buildThreadInput,
-  createTextAdapter,
-  type SpawnCliError,
-  spawnCli,
-} from "@uncaged/workflow-util-agent";
+import { buildAgentPrompt, type SpawnCliError, spawnCli } from "@uncaged/workflow-util-agent";
 
 import { extractWorkspacePath } from "./extract-workspace.js";
 import type { CursorAgentConfig } from "./types.js";
@@ -34,12 +29,12 @@ function resolveCursorModel(model: string | null): string {
 }
 
 /** Runs `cursor-agent` with workspace from config or extracted from context via LLM. */
-export function createCursorAgent(config: CursorAgentConfig): AdapterFn {
+export function createCursorAgent(config: CursorAgentConfig): AgentFn {
   const modelFlag = resolveCursorModel(config.model);
   const timeoutMs = config.timeout > 0 ? config.timeout : null;
   const logger = createLogger({ sink: { kind: "stderr" } });
 
-  return createTextAdapter(async (ctx, prompt) => {
+  return async (ctx) => {
     const validated = validateCursorAgentConfig(config);
     if (!validated.ok) {
       throw new Error(validated.error);
@@ -53,8 +48,7 @@ export function createCursorAgent(config: CursorAgentConfig): AdapterFn {
       if (config.llmProvider === null) {
         throw new Error("cursor-agent: llmProvider is required when workspace is null");
       }
-      const agentCtx = { ...ctx, currentRole: { name: "cursor", systemPrompt: prompt } };
-      const extracted = await extractWorkspacePath(agentCtx, config.llmProvider, logger);
+      const extracted = await extractWorkspacePath(ctx, config.llmProvider, logger);
       if (extracted === null) {
         throw new Error(
           "cursor-agent: failed to extract workspace path from context. Provide an explicit workspace or ensure previous steps include a repoPath.",
@@ -64,8 +58,7 @@ export function createCursorAgent(config: CursorAgentConfig): AdapterFn {
     }
 
     logger("R5HN3YKQ", `cursor-agent workspace: ${workspace}`);
-    const threadInput = await buildThreadInput(ctx);
-    const fullPrompt = `${prompt}\n\n${threadInput}`;
+    const fullPrompt = await buildAgentPrompt(ctx);
     const args = [
       "-p",
       fullPrompt,
@@ -86,5 +79,5 @@ export function createCursorAgent(config: CursorAgentConfig): AdapterFn {
       throwCursorSpawnError(run.error);
     }
     return run.value;
-  });
+  };
 }

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

@@ -37,7 +37,7 @@ describe("validateHermesAgentConfig", () => {
 });
 
 describe("createHermesAgent", () => {
-  test("returns an AdapterFn even with invalid config (validation deferred to call)", () => {
+  test("returns an AgentFn even with invalid config (validation deferred to call)", () => {
     const agent = createHermesAgent({
       command: "/usr/local/bin/hermes",
       model: null,

packages/workflow-agent-hermes/package.json

@@ -1,10 +1,6 @@
 {
   "name": "@uncaged/workflow-agent-hermes",
-  "version": "0.3.21",
-  "files": [
-    "dist",
-    "package.json"
-  ],
+  "version": "0.3.11",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -14,11 +10,5 @@
   "dependencies": {
     "@uncaged/workflow-runtime": "workspace:*",
     "@uncaged/workflow-util-agent": "workspace:*"
-  },
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./src/index.ts"
-    }
   }
 }

packages/workflow-agent-hermes/src/index.ts

@@ -1,10 +1,5 @@
-import type { AdapterFn } from "@uncaged/workflow-runtime";
-import {
-  buildThreadInput,
-  createTextAdapter,
-  type SpawnCliError,
-  spawnCli,
-} from "@uncaged/workflow-util-agent";
+import type { AgentFn } from "@uncaged/workflow-runtime";
+import { buildAgentPrompt, type SpawnCliError, spawnCli } from "@uncaged/workflow-util-agent";
 
 import type { HermesAgentConfig } from "./types.js";
 import { validateHermesAgentConfig } from "./validate-config.js";
@@ -30,17 +25,16 @@ function throwHermesSpawnError(error: SpawnCliError): never {
 }
 
 /** Runs `hermes chat` non-interactively with the Nerve-style argv contract (`-q`, `--yolo`, `--quiet`). */
-export function createHermesAgent(config: HermesAgentConfig): AdapterFn {
+export function createHermesAgent(config: HermesAgentConfig): AgentFn {
   const timeoutMs = config.timeout;
 
-  return createTextAdapter(async (ctx, prompt) => {
+  return async (ctx) => {
     const validated = validateHermesAgentConfig(config);
     if (!validated.ok) {
       throw new Error(validated.error);
     }
 
-    const threadInput = await buildThreadInput(ctx);
-    const fullPrompt = `${prompt}\n\n${threadInput}`;
+    const fullPrompt = await buildAgentPrompt(ctx);
     const args = [
       "chat",
       "-q",
@@ -61,5 +55,5 @@ export function createHermesAgent(config: HermesAgentConfig): AdapterFn {
       throwHermesSpawnError(run.error);
     }
     return run.value;
-  });
+  };
 }

packages/workflow-agent-llm/__tests__/create-llm-adapter.test.ts

@@ -1,16 +1,9 @@
 import { describe, expect, test } from "bun:test";
-import {
-  type CasStore,
-  type ExtractFn,
-  START,
-  type ThreadContext,
-  type WorkflowRuntime,
-} from "@uncaged/workflow-runtime";
-import * as z from "zod";
+import { type AgentContext, START } from "@uncaged/workflow-runtime";
 
 import { createLlmAdapter } from "../src/create-llm-adapter.js";
 
-function makeCtx(userContent: string): ThreadContext {
+function makeCtx(userContent: string): AgentContext {
   return {
     start: {
       role: START,
@@ -23,34 +16,14 @@ function makeCtx(userContent: string): ThreadContext {
     bundleHash: "TESTHASH00001",
     steps: [],
     threadId: "01TEST000000000000000000TR",
+    currentRole: { name: "planner", systemPrompt: "system instructions" },
   };
 }
 
-const testSchema = z.object({ summary: z.string() });
-
-function makeRuntime(): WorkflowRuntime {
-  let stored = "";
-  const cas: CasStore = {
-    put: async (content: string) => {
-      stored = content;
-      return "HASH001";
-    },
-    get: async () => stored,
-    delete: async () => {},
-    list: async () => [],
-  };
-  const extract: ExtractFn = async (_schema, _contentHash) => ({
-    meta: { summary: "extracted" },
-    contentPayload: stored,
-    refs: [],
-  });
-  return { cas, extract };
-}
-
 describe("createLlmAdapter", () => {
   const originalFetch = globalThis.fetch;
 
-  test("posts system + user (start.content) and returns typed meta with childThread: null", async () => {
+  test("posts system + user (start.content) and returns assistant text", async () => {
     globalThis.fetch = (() =>
       Promise.resolve(
         new Response(JSON.stringify({ choices: [{ message: { content: "model reply" } }] }), {
@@ -61,13 +34,11 @@ describe("createLlmAdapter", () => {
 
     const provider = { baseUrl: "https://api.example/v1", apiKey: "k", model: "m" };
     const adapter = createLlmAdapter(provider);
-    const roleFn = adapter("system instructions", testSchema);
-    const result = await roleFn(makeCtx("trigger text"), makeRuntime());
+    const out = await adapter(makeCtx("trigger text"));
 
     globalThis.fetch = originalFetch;
 
-    expect(result.meta).toEqual({ summary: "extracted" });
-    expect(result.childThread).toBeNull();
+    expect(out).toBe("model reply");
   });
 
   test("throws on non-ok fetch response", async () => {
@@ -81,9 +52,8 @@ describe("createLlmAdapter", () => {
 
     const provider = { baseUrl: "https://api.example/v1", apiKey: "k", model: "m" };
     const adapter = createLlmAdapter(provider);
-    const roleFn = adapter("system", testSchema);
 
-    await expect(roleFn(makeCtx("hi"), makeRuntime())).rejects.toThrow("llm:");
+    await expect(adapter(makeCtx("hi"))).rejects.toThrow("llm:");
     globalThis.fetch = originalFetch;
   });
 
@@ -92,9 +62,8 @@ describe("createLlmAdapter", () => {
 
     const provider = { baseUrl: "https://api.example/v1", apiKey: "k", model: "m" };
     const adapter = createLlmAdapter(provider);
-    const roleFn = adapter("system", testSchema);
 
-    await expect(roleFn(makeCtx("hi"), makeRuntime())).rejects.toThrow();
+    await expect(adapter(makeCtx("hi"))).rejects.toThrow();
     globalThis.fetch = originalFetch;
   });
 });

packages/workflow-agent-llm/package.json

@@ -1,10 +1,6 @@
 {
   "name": "@uncaged/workflow-agent-llm",
-  "version": "0.3.21",
-  "files": [
-    "dist",
-    "package.json"
-  ],
+  "version": "0.3.11",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -12,16 +8,6 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@uncaged/workflow-runtime": "workspace:*",
-    "@uncaged/workflow-util-agent": "workspace:*"
-  },
-  "devDependencies": {
-    "zod": "^4.0.0"
-  },
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./src/index.ts"
-    }
+    "@uncaged/workflow-runtime": "workspace:*"
   }
 }

packages/workflow-agent-llm/src/create-llm-adapter.ts

@@ -1,5 +1,11 @@
-import { type AdapterFn, err, type LlmProvider, ok, type Result } from "@uncaged/workflow-runtime";
-import { createTextAdapter } from "@uncaged/workflow-util-agent";
+import {
+  type AgentContext,
+  type AgentFn,
+  err,
+  type LlmProvider,
+  ok,
+  type Result,
+} from "@uncaged/workflow-runtime";
 
 /** OpenAI chat completion message shape (passed to `/chat/completions`). */
 export type LlmMessage = { role: "system" | "user" | "assistant"; content: string };
@@ -91,13 +97,13 @@ export async function chatCompletionText(options: {
   return parseAssistantText(res.value);
 }
 
-/** Single-turn chat adapter: system prompt is passed by the workflow engine. */
-export function createLlmAdapter(provider: LlmProvider): AdapterFn {
-  return createTextAdapter(async (ctx, prompt) => {
+/** Single-turn chat adapter: system prompt comes from {@link AgentContext.currentRole}. */
+export function createLlmAdapter(provider: LlmProvider): AgentFn {
+  return async (ctx: AgentContext) => {
     const result = await chatCompletionText({
       provider,
       messages: [
-        { role: "system", content: prompt },
+        { role: "system", content: ctx.currentRole.systemPrompt },
         { role: "user", content: ctx.start.content },
       ],
     });
@@ -105,5 +111,5 @@ export function createLlmAdapter(provider: LlmProvider): AdapterFn {
       throw new Error(`llm: ${formatLlmChatError(result.error)}`);
     }
     return result.value;
-  });
+  };
 }

packages/workflow-agent-llm/tsconfig.json

@@ -6,5 +6,5 @@
     "composite": true
   },
   "include": ["src/**/*.ts"],
-  "references": [{ "path": "../workflow-runtime" }, { "path": "../workflow-util-agent" }]
+  "references": [{ "path": "../workflow-runtime" }]
 }

packages/workflow-agent-react/__tests__/create-react-adapter.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, test } from "bun:test";
-import { ok, START, type ThreadContext, type WorkflowRuntime } from "@uncaged/workflow-protocol";
 import type { LlmFn, ToolDefinition } from "@uncaged/workflow-reactor";
+import { ok } from "@uncaged/workflow-protocol";
+import { START, type ThreadContext, type WorkflowRuntime } from "@uncaged/workflow-protocol";
 import * as z from "zod/v4";
 
 import { createReactAdapter } from "../src/create-react-adapter.js";
@@ -38,12 +39,10 @@ const STUB_RUNTIME: WorkflowRuntime = {
   }),
 };
 
-const TEST_SCHEMA = z
-  .object({
-    summary: z.string(),
-    score: z.number(),
-  })
-  .meta({ title: "resolve", description: "Submit the final result." });
+const TEST_SCHEMA = z.object({
+  summary: z.string(),
+  score: z.number(),
+}).meta({ title: "resolve", description: "Submit the final result." });
 
 function makeChatResponse(content: string | null, toolCalls: unknown[] | null): string {
   const message: Record<string, unknown> = { role: "assistant" };
@@ -157,9 +156,7 @@ describe("createReactAdapter", () => {
       callCount += 1;
       if (callCount === 1) {
         // Invalid: score should be number, not string
-        return ok(
-          makeToolCallResponse("resolve", { summary: "bad", score: "not-a-number" }, "call_1"),
-        );
+        return ok(makeToolCallResponse("resolve", { summary: "bad", score: "not-a-number" }, "call_1"));
       }
       return ok(makeToolCallResponse("resolve", { summary: "fixed", score: 10 }, "call_2"));
     };

packages/workflow-agent-react/__tests__/tools.test.ts

@@ -1,9 +1,9 @@
-import { afterAll, describe, expect, test } from "bun:test";
-import { randomBytes } from "node:crypto";
-import { mkdirSync, readFileSync, unlinkSync } from "node:fs";
-import { tmpdir } from "node:os";
+import { describe, test, expect, afterAll } from "bun:test";
+import { readFileTool, writeFileTool, patchFileTool, shellExecTool } from "../src/tools/index.js";
 import { join } from "node:path";
-import { patchFileTool, readFileTool, shellExecTool, writeFileTool } from "../src/tools/index.js";
+import { tmpdir } from "node:os";
+import { readFileSync, unlinkSync, mkdirSync } from "node:fs";
+import { randomBytes } from "node:crypto";
 
 const TMP_DIR = join(tmpdir(), `tools-test-${randomBytes(4).toString("hex")}`);
 mkdirSync(TMP_DIR, { recursive: true });
@@ -14,17 +14,9 @@ const cleanupFiles: string[] = [];
 
 afterAll(() => {
   for (const f of cleanupFiles) {
-    try {
-      unlinkSync(f);
-    } catch {
-      /* ignore */
-    }
-  }
-  try {
-    unlinkSync(TMP_DIR);
-  } catch {
-    /* ignore */
+    try { unlinkSync(f); } catch { /* ignore */ }
   }
+  try { unlinkSync(TMP_DIR); } catch { /* ignore */ }
 });
 
 describe("read_file", () => {
@@ -34,9 +26,7 @@ describe("read_file", () => {
     const content = "line1\nline2\nline3\n";
     require("node:fs").writeFileSync(p, content);
 
-    const result = await readFileTool.handler(
-      JSON.stringify({ path: p, offset: null, limit: null }),
-    );
+    const result = await readFileTool.handler(JSON.stringify({ path: p, offset: null, limit: null }));
     expect(result).toContain("1|line1");
     expect(result).toContain("2|line2");
     expect(result).toContain("3|line3");
@@ -52,9 +42,7 @@ describe("read_file", () => {
   });
 
   test("returns error for missing file", async () => {
-    const result = await readFileTool.handler(
-      JSON.stringify({ path: "/nonexistent/file.txt", offset: null, limit: null }),
-    );
+    const result = await readFileTool.handler(JSON.stringify({ path: "/nonexistent/file.txt", offset: null, limit: null }));
     expect(result).toContain("Error:");
   });
 });
@@ -76,9 +64,7 @@ describe("patch_file", () => {
     cleanupFiles.push(p);
     require("node:fs").writeFileSync(p, "foo bar baz");
 
-    const result = await patchFileTool.handler(
-      JSON.stringify({ path: p, old_string: "bar", new_string: "qux" }),
-    );
+    const result = await patchFileTool.handler(JSON.stringify({ path: p, old_string: "bar", new_string: "qux" }));
     expect(result).toContain("Successfully");
     expect(readFileSync(p, "utf-8")).toBe("foo qux baz");
   });
@@ -88,9 +74,7 @@ describe("patch_file", () => {
     cleanupFiles.push(p);
     require("node:fs").writeFileSync(p, "foo");
 
-    const result = await patchFileTool.handler(
-      JSON.stringify({ path: p, old_string: "xyz", new_string: "abc" }),
-    );
+    const result = await patchFileTool.handler(JSON.stringify({ path: p, old_string: "xyz", new_string: "abc" }));
     expect(result).toContain("not found");
   });
 
@@ -99,18 +83,14 @@ describe("patch_file", () => {
     cleanupFiles.push(p);
     require("node:fs").writeFileSync(p, "aaa bbb aaa");
 
-    const result = await patchFileTool.handler(
-      JSON.stringify({ path: p, old_string: "aaa", new_string: "ccc" }),
-    );
+    const result = await patchFileTool.handler(JSON.stringify({ path: p, old_string: "aaa", new_string: "ccc" }));
     expect(result).toContain("not unique");
   });
 });
 
 describe("shell_exec", () => {
   test("runs echo", async () => {
-    const result = await shellExecTool.handler(
-      JSON.stringify({ command: "echo hello", timeout: null }),
-    );
+    const result = await shellExecTool.handler(JSON.stringify({ command: "echo hello", timeout: null }));
     expect(result.trim()).toBe("hello");
   });
 

packages/workflow-agent-react/package.json

@@ -1,10 +1,6 @@
 {
   "name": "@uncaged/workflow-agent-react",
-  "version": "0.3.21",
-  "files": [
-    "dist",
-    "package.json"
-  ],
+  "version": "0.3.11",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

packages/workflow-agent-react/src/index.ts

@@ -1,4 +1,4 @@
 export { createReactAdapter } from "./create-react-adapter.js";
-export type { ToolEntry, ToolHandler } from "./tools/index.js";
-export { defaultToolHandler, defaultTools } from "./tools/index.js";
 export type { ReactAdapterConfig, ReactToolHandler } from "./types.js";
+export { defaultTools, defaultToolHandler } from "./tools/index.js";
+export type { ToolEntry, ToolHandler } from "./tools/index.js";

packages/workflow-agent-react/src/tools/defaults.ts

@@ -1,9 +1,9 @@
 import type { ToolDefinition } from "@uncaged/workflow-reactor";
-import { patchFileTool } from "./patch-file.js";
-import { readFileTool } from "./read-file.js";
-import { shellExecTool } from "./shell-exec.js";
 import type { ToolEntry } from "./types.js";
+import { readFileTool } from "./read-file.js";
 import { writeFileTool } from "./write-file.js";
+import { patchFileTool } from "./patch-file.js";
+import { shellExecTool } from "./shell-exec.js";
 
 const ALL_TOOLS: ToolEntry[] = [readFileTool, writeFileTool, patchFileTool, shellExecTool];
 

packages/workflow-agent-react/src/tools/index.ts

@@ -1,6 +1,6 @@
-export { defaultToolHandler, defaultTools } from "./defaults.js";
-export { patchFileTool } from "./patch-file.js";
 export { readFileTool } from "./read-file.js";
-export { shellExecTool } from "./shell-exec.js";
-export type { ToolEntry, ToolHandler } from "./types.js";
 export { writeFileTool } from "./write-file.js";
+export { patchFileTool } from "./patch-file.js";
+export { shellExecTool } from "./shell-exec.js";
+export { defaultTools, defaultToolHandler } from "./defaults.js";
+export type { ToolEntry, ToolHandler } from "./types.js";

packages/workflow-agent-react/src/tools/patch-file.ts

@@ -30,10 +30,7 @@ export const patchFileTool: ToolEntry = {
       if (secondIdx !== -1) {
         return `Error: old_string is not unique in ${parsed.path} (found multiple occurrences)`;
       }
-      const updated =
-        content.slice(0, firstIdx) +
-        parsed.new_string +
-        content.slice(firstIdx + parsed.old_string.length);
+      const updated = content.slice(0, firstIdx) + parsed.new_string + content.slice(firstIdx + parsed.old_string.length);
       await writeFile(parsed.path, updated);
       return `Successfully patched ${parsed.path}`;
     } catch (err) {

packages/workflow-agent-react/src/tools/read-file.ts

@@ -11,10 +11,7 @@ export const readFileTool: ToolEntry = {
         type: "object",
         properties: {
           path: { type: "string", description: "Path to the file to read" },
-          offset: {
-            type: ["number", "null"],
-            description: "Start line number (1-indexed, default: 1)",
-          },
+          offset: { type: ["number", "null"], description: "Start line number (1-indexed, default: 1)" },
           limit: { type: ["number", "null"], description: "Max lines to read (default: all)" },
         },
         required: ["path"],
@@ -23,17 +20,12 @@ export const readFileTool: ToolEntry = {
   },
   handler: async (args: string): Promise<string> => {
     try {
-      const parsed = JSON.parse(args) as {
-        path: string;
-        offset: number | null;
-        limit: number | null;
-      };
+      const parsed = JSON.parse(args) as { path: string; offset: number | null; limit: number | null };
       const content = await readFile(parsed.path, "utf-8");
       const allLines = content.split("\n");
       const offset = parsed.offset ?? 1;
       const start = Math.max(0, offset - 1);
-      const end =
-        parsed.limit != null ? Math.min(allLines.length, start + parsed.limit) : allLines.length;
+      const end = parsed.limit != null ? Math.min(allLines.length, start + parsed.limit) : allLines.length;
       const lines = allLines.slice(start, end);
       return lines.map((line, i) => `${start + i + 1}|${line}`).join("\n");
     } catch (err) {

packages/workflow-agent-react/src/tools/shell-exec.ts

@@ -3,27 +3,6 @@ import type { ToolEntry } from "./types.js";
 
 const MAX_OUTPUT = 10000;
 
-function truncate(text: string): string {
-  return text.length > MAX_OUTPUT ? `${text.slice(0, MAX_OUTPUT)}\n...(truncated)` : text;
-}
-
-function classifyExecError(err: unknown): string {
-  if (
-    err &&
-    typeof err === "object" &&
-    "status" in err &&
-    (err as { status: unknown }).status === null
-  ) {
-    return "Error: command timed out";
-  }
-  if (err && typeof err === "object" && "stderr" in err) {
-    const e = err as { stderr: string; stdout: string; status: number };
-    const combined = `${e.stdout ?? ""}${e.stderr ?? ""}`;
-    return truncate(combined) || `Error: command exited with status ${e.status}`;
-  }
-  return `Error: ${err instanceof Error ? err.message : String(err)}`;
-}
-
 export const shellExecTool: ToolEntry = {
   definition: {
     type: "function",
@@ -50,9 +29,17 @@ export const shellExecTool: ToolEntry = {
         stdio: ["pipe", "pipe", "pipe"],
         maxBuffer: MAX_OUTPUT * 2,
       });
-      return truncate(output);
+      return output.length > MAX_OUTPUT ? `${output.slice(0, MAX_OUTPUT)}\n...(truncated)` : output;
     } catch (err: unknown) {
-      return classifyExecError(err);
+      if (err && typeof err === "object" && "status" in err && (err as { status: unknown }).status === null) {
+        return "Error: command timed out";
+      }
+      if (err && typeof err === "object" && "stderr" in err) {
+        const e = err as { stderr: string; stdout: string; status: number };
+        const combined = `${e.stdout ?? ""}${e.stderr ?? ""}`;
+        return combined.length > MAX_OUTPUT ? `${combined.slice(0, MAX_OUTPUT)}\n...(truncated)` : combined || `Error: command exited with status ${e.status}`;
+      }
+      return `Error: ${err instanceof Error ? err.message : String(err)}`;
     }
   },
 };

packages/workflow-cas/package.json

@@ -1,10 +1,6 @@
 {
   "name": "@uncaged/workflow-cas",
-  "version": "0.3.21",
-  "files": [
-    "dist",
-    "package.json"
-  ],
+  "version": "0.3.11",
   "type": "module",
   "scripts": {
     "test": "bun test"

packages/workflow-dashboard/package.json

@@ -1,10 +1,6 @@
 {
   "name": "@uncaged/workflow-dashboard",
   "version": "0.1.0",
-  "files": [
-    "dist",
-    "package.json"
-  ],
   "private": true,
   "type": "module",
   "scripts": {
@@ -13,6 +9,7 @@
     "preview": "vite preview"
   },
   "dependencies": {
+    "@dagrejs/dagre": "^3.0.0",
     "@xyflow/react": "^12.10.2",
     "react": "^19.2.6",
     "react-dom": "^19.2.6",

packages/workflow-dashboard/src/components/login.tsx

@@ -70,6 +70,7 @@ export function LoginPage({ onLogin }: Props) {
               borderColor: "var(--color-border)",
               color: "var(--color-text)",
             }}
+            autoFocus
           />
           {error && (
             <p className="text-xs mb-3" style={{ color: "var(--color-error)" }}>

packages/workflow-dashboard/src/components/workflow-graph/condition-edge.tsx

@@ -2,46 +2,11 @@ import {
   BaseEdge,
   EdgeLabelRenderer,
   type EdgeProps,
+  getBezierPath,
   getSmoothStepPath,
 } from "@xyflow/react";
 import type { ConditionEdgeData } from "./types.ts";
 
-// Must match the FEEDBACK_OFFSET_X in use-layout.ts
-const FEEDBACK_OFFSET_X = 100;
-// Radius for feedback edge corners
-const FEEDBACK_RADIUS = 16;
-
-/**
- * Build an SVG path for a feedback (back) edge that routes to the right of the nodes.
- * The path goes: source right → arc → vertical up → arc → target right
- */
-function feedbackPath(
-  sourceX: number,
-  sourceY: number,
-  targetX: number,
-  targetY: number,
-): string {
-  const rightX = Math.max(sourceX, targetX) + FEEDBACK_OFFSET_X;
-  const r = FEEDBACK_RADIUS;
-
-  // Start from source right side, go right, then up, then left to target right side
-  const segments = [
-    `M ${sourceX} ${sourceY}`,
-    // Horizontal to the right
-    `L ${rightX - r} ${sourceY}`,
-    // Arc turning upward
-    `Q ${rightX} ${sourceY} ${rightX} ${sourceY - r}`,
-    // Vertical upward
-    `L ${rightX} ${targetY + r}`,
-    // Arc turning left
-    `Q ${rightX} ${targetY} ${rightX - r} ${targetY}`,
-    // Horizontal left to target
-    `L ${targetX} ${targetY}`,
-  ];
-
-  return segments.join(" ");
-}
-
 export function ConditionEdge(props: EdgeProps) {
   const {
     id,
@@ -59,41 +24,28 @@ export function ConditionEdge(props: EdgeProps) {
   const edgeData = data as ConditionEdgeData | undefined;
   const isFallback = edgeData?.isFallback ?? false;
   const isSelfLoop = source === target;
-  const isFeedback = edgeData?.isFeedback ?? false;
 
-  let path: string;
-  let defaultLabelX: number;
-  let defaultLabelY: number;
+  const [path, labelX, labelY] = isSelfLoop
+    ? getSmoothStepPath({
+        sourceX,
+        sourceY,
+        targetX,
+        targetY,
+        sourcePosition,
+        targetPosition,
+        borderRadius: 20,
+      })
+    : getBezierPath({
+        sourceX,
+        sourceY,
+        targetX,
+        targetY,
+        sourcePosition,
+        targetPosition,
+      });
 
-  if (isFeedback) {
-    // Custom feedback path routed to the right
-    path = feedbackPath(sourceX, sourceY, targetX, targetY);
-    const rightX = Math.max(sourceX, targetX) + FEEDBACK_OFFSET_X;
-    defaultLabelX = rightX;
-    defaultLabelY = (sourceY + targetY) / 2;
-  } else {
-    const result = getSmoothStepPath({
-      sourceX,
-      sourceY,
-      targetX,
-      targetY,
-      sourcePosition,
-      targetPosition,
-      borderRadius: isSelfLoop ? 20 : 8,
-      offset: isSelfLoop ? 50 : undefined,
-    });
-    path = result[0];
-    defaultLabelX = result[1];
-    defaultLabelY = result[2];
-  }
-
-  const stroke = isFallback ? "var(--color-text-muted)" : "var(--color-accent)";
+  const stroke = isFallback ? "var(--color-text-muted)" : "var(--color-text)";
   const strokeDasharray = isFallback ? "5 4" : undefined;
-  const label = edgeData?.condition ?? "";
-
-  // Use pre-computed label position if available, otherwise fall back to default
-  const labelX = edgeData?.labelX ?? defaultLabelX;
-  const labelY = edgeData?.labelY ?? defaultLabelY;
 
   return (
     <>
@@ -103,21 +55,19 @@ export function ConditionEdge(props: EdgeProps) {
         markerEnd={markerEnd}
         style={{ stroke, strokeWidth: 1.5, strokeDasharray }}
       />
-      {label !== "" && (
+      {edgeData && !isFallback && edgeData.condition !== "" && (
         <EdgeLabelRenderer>
           <div
             className="absolute px-1.5 py-0.5 rounded text-[10px] font-mono pointer-events-auto"
             style={{
               transform: `translate(-50%, -50%) translate(${labelX}px, ${labelY}px)`,
-              background: "var(--color-surface)",
+              background: "var(--color-bg)",
               border: "1px solid var(--color-border)",
-              color: isFallback ? "var(--color-text-muted)" : "var(--color-text)",
-              whiteSpace: "nowrap",
-              zIndex: 10,
+              color: "var(--color-text)",
             }}
-            title={edgeData?.conditionDescription ?? undefined}
+            title={edgeData.conditionDescription ?? undefined}
           >
-            {label}
+            {edgeData.condition}
           </div>
         </EdgeLabelRenderer>
       )}

packages/workflow-dashboard/src/components/workflow-graph/types.ts

@@ -21,10 +21,6 @@ export type ConditionEdgeData = {
   condition: string;
   conditionDescription: string | null;
   isFallback: boolean;
-  isFeedback: boolean;
-  isSelfLoop: boolean;
-  labelX: number | null;
-  labelY: number | null;
   [key: string]: unknown;
 };
 

packages/workflow-dashboard/src/components/workflow-graph/use-layout.ts

@@ -1,3 +1,4 @@
+import Dagre from "@dagrejs/dagre";
 import type { Edge, Node } from "@xyflow/react";
 import { useMemo } from "react";
 import type { WorkflowGraphEdge } from "../../api.ts";
@@ -9,11 +10,6 @@ const ROLE_NODE_WIDTH = 180;
 const ROLE_NODE_HEIGHT = 60;
 const TERMINAL_NODE_SIZE = 40;
 
-// Vertical gap between nodes in the spine
-const LAYER_GAP = 80;
-// Horizontal offset for feedback (back) edges routed on the right side
-const FEEDBACK_OFFSET_X = 100;
-
 type LayoutInput = {
   edges: readonly WorkflowGraphEdge[];
   roles: Record<string, { description: string }>;
@@ -25,84 +21,20 @@ type LayoutResult = {
   edges: Edge[];
 };
 
-function nodeSize(id: string): { width: number; height: number } {
-  if (id === START_ID || id === END_ID) {
-    return { width: TERMINAL_NODE_SIZE, height: TERMINAL_NODE_SIZE };
-  }
-  return { width: ROLE_NODE_WIDTH, height: ROLE_NODE_HEIGHT };
-}
-
-function edgeKey(e: WorkflowGraphEdge): string {
-  return `${e.from}->${e.to}::${e.condition}`;
-}
-
-/**
- * Extract the linear spine from the graph using topological ordering.
- * Forward edges go from lower rank to higher rank; feedback edges go backwards.
- * Self-loops are neither forward nor feedback — they're handled separately.
- */
-function extractSpine(edges: readonly WorkflowGraphEdge[]): string[] {
-  // Collect all node IDs
+function collectNodeIds(edges: readonly WorkflowGraphEdge[]): Set<string> {
   const ids = new Set<string>();
   for (const e of edges) {
     ids.add(e.from);
     ids.add(e.to);
   }
+  return ids;
+}
 
-  // Build adjacency for forward edges only (non-self-loop, non-FALLBACK-back)
-  // Strategy: BFS from __start__, picking the first non-FALLBACK forward edge,
-  // or FALLBACK if no other option.
-  const forwardAdj = new Map<string, string[]>();
-  for (const e of edges) {
-    if (e.from === e.to) continue;
-    const existing = forwardAdj.get(e.from) ?? [];
-    existing.push(e.to);
-    forwardAdj.set(e.from, existing);
+function nodeSize(id: string): { width: number; height: number } {
+  if (id === START_ID || id === END_ID) {
+    return { width: TERMINAL_NODE_SIZE, height: TERMINAL_NODE_SIZE };
   }
-
-  // Walk the main path: prefer non-FALLBACK edges for the spine ordering
-  const visited = new Set<string>();
-  const spine: string[] = [];
-
-  // Build a set of "primary" next targets per node (non-FALLBACK first)
-  const primaryNext = new Map<string, string>();
-  const edgesByFrom = new Map<string, WorkflowGraphEdge[]>();
-  for (const e of edges) {
-    if (e.from === e.to) continue;
-    const list = edgesByFrom.get(e.from) ?? [];
-    list.push(e);
-    edgesByFrom.set(e.from, list);
-  }
-
-  // For each node, the "primary" next is the first non-FALLBACK target,
-  // or the FALLBACK target if all edges are FALLBACK
-  for (const [from, edgeList] of edgesByFrom) {
-    const nonFallback = edgeList.find((e) => e.condition !== "FALLBACK");
-    const fallback = edgeList.find((e) => e.condition === "FALLBACK");
-    primaryNext.set(from, nonFallback?.to ?? fallback?.to ?? "");
-  }
-
-  // Walk the spine from __start__
-  let current: string | null = START_ID;
-  while (current !== null && !visited.has(current)) {
-    visited.add(current);
-    spine.push(current);
-    const next = primaryNext.get(current);
-    if (next !== undefined && next !== "" && !visited.has(next)) {
-      current = next;
-    } else {
-      current = null;
-    }
-  }
-
-  // Add any remaining nodes not on the main path (shouldn't normally happen)
-  for (const id of ids) {
-    if (!visited.has(id)) {
-      spine.push(id);
-    }
-  }
-
-  return spine;
+  return { width: ROLE_NODE_WIDTH, height: ROLE_NODE_HEIGHT };
 }
 
 function buildRoleNode(
@@ -136,95 +68,60 @@ function buildTerminalNode(
   };
 }
 
-function computeLayout(input: LayoutInput): LayoutResult {
-  const spine = extractSpine(input.edges);
-  const rank = new Map<string, number>();
-  for (let i = 0; i < spine.length; i++) {
-    rank.set(spine[i], i);
-  }
+function edgeKey(e: WorkflowGraphEdge): string {
+  return `${e.from}->${e.to}::${e.condition}`;
+}
 
-  // Position nodes along a vertical spine, centered horizontally
-  const centerX = ROLE_NODE_WIDTH / 2; // left edge at x=0, center at width/2
-  const nodePositions = new Map<string, { x: number; y: number; w: number; h: number }>();
-
-  let y = 0;
-  for (const id of spine) {
-    const size = nodeSize(id);
-    // Center-align all nodes on the spine
-    const x = centerX - size.width / 2;
-    nodePositions.set(id, { x, y, w: size.width, h: size.height });
-    y += size.height + LAYER_GAP;
-  }
-
-  // Build nodes
-  const nodes: Node[] = [];
-  for (const id of spine) {
-    const pos = nodePositions.get(id);
-    if (pos === undefined) continue;
-    const state = input.nodeStates.get(id) ?? "default";
-    if (id === START_ID || id === END_ID) {
-      nodes.push(buildTerminalNode(id, { x: pos.x, y: pos.y }, state));
-    } else {
-      nodes.push(buildRoleNode(id, { x: pos.x, y: pos.y }, input.roles, state));
-    }
-  }
-
-  // Build edges with label positions
-  // For feedback edges (target rank < source rank), we'll compute label at midpoint
-  // of the right-side arc. The actual SVG path is drawn by ConditionEdge component.
-  const edges: Edge[] = input.edges.map((e) => {
-    const isFallback = e.condition === "FALLBACK";
-    const isSelfLoop = e.from === e.to;
-    const sourceRank = rank.get(e.from) ?? 0;
-    const targetRank = rank.get(e.to) ?? 0;
-    const isFeedback = !isSelfLoop && targetRank <= sourceRank;
-
-    const sourcePos = nodePositions.get(e.from);
-    const targetPos = nodePositions.get(e.to);
-
-    let labelX: number | null = null;
-    let labelY: number | null = null;
-
-    if (sourcePos !== undefined && targetPos !== undefined) {
-      if (isFeedback) {
-        // Label on the right side of the feedback arc
-        const rightX = centerX + ROLE_NODE_WIDTH / 2 + FEEDBACK_OFFSET_X;
-        const midY = (sourcePos.y + sourcePos.h / 2 + targetPos.y + targetPos.h / 2) / 2;
-        labelX = rightX;
-        labelY = midY;
-      } else if (!isSelfLoop) {
-        // Forward edge: label between source bottom and target top
-        const midX = centerX;
-        const midY = (sourcePos.y + sourcePos.h + targetPos.y) / 2;
-        labelX = midX;
-        labelY = midY;
-      }
-      // Self-loop: let ReactFlow default handle it
-    }
-
-    return {
-      id: edgeKey(e),
-      source: e.from,
-      target: e.to,
-      type: "condition",
-      data: {
-        condition: e.condition,
-        conditionDescription: e.conditionDescription,
-        isFallback,
-        isFeedback,
-        isSelfLoop,
-      labelX,
-      labelY,
-      },
-    };
-  });
-
-  return { nodes, edges };
+function buildEdge(e: WorkflowGraphEdge): Edge<ConditionEdgeData> {
+  const isFallback = e.condition === "FALLBACK";
+  return {
+    id: edgeKey(e),
+    source: e.from,
+    target: e.to,
+    type: "condition",
+    data: {
+      condition: e.condition,
+      conditionDescription: e.conditionDescription,
+      isFallback,
+    },
+  };
 }
 
 export function useLayout(input: LayoutInput): LayoutResult {
-  return useMemo(
-    () => computeLayout(input),
-    [input.edges, input.roles, input.nodeStates],
-  );
+  return useMemo(() => {
+    const ids = collectNodeIds(input.edges);
+
+    const g = new Dagre.graphlib.Graph({ multigraph: true }).setDefaultEdgeLabel(() => ({}));
+    g.setGraph({ rankdir: "TB", nodesep: 60, ranksep: 80 });
+
+    for (const id of ids) {
+      const size = nodeSize(id);
+      g.setNode(id, { width: size.width, height: size.height });
+    }
+    for (const e of input.edges) {
+      if (e.from === e.to) {
+        continue;
+      }
+      g.setEdge(e.from, e.to, {}, edgeKey(e));
+    }
+
+    Dagre.layout(g);
+
+    const nodes: Node[] = [];
+    for (const id of ids) {
+      const dagNode = g.node(id);
+      const size = nodeSize(id);
+      const pos = { x: dagNode.x - size.width / 2, y: dagNode.y - size.height / 2 };
+      const state = input.nodeStates.get(id) ?? "default";
+      if (id === START_ID || id === END_ID) {
+        nodes.push(buildTerminalNode(id, pos, state));
+      } else {
+        nodes.push(buildRoleNode(id, pos, input.roles, state));
+      }
+    }
+
+    const edges: Edge[] = input.edges.map(buildEdge);
+
+    return { nodes, edges };
+  }, [input.edges, input.roles, input.nodeStates]);
 }

packages/workflow-dashboard/src/components/workflow-graph/workflow-graph.tsx

@@ -66,8 +66,6 @@ export function WorkflowGraph({ graph, roles, nodeStates, onNodeClick }: Props)
       onNodeClick={onNodeClickHandler}
       fitView
       fitViewOptions={{ padding: 0.15 }}
-      minZoom={0.3}
-      maxZoom={2}
       nodesDraggable={false}
       nodesConnectable={false}
       elementsSelectable={false}

packages/workflow-dashboard/src/components/workflow-list.tsx

@@ -45,45 +45,38 @@ function ExpandedWorkflowBody({
   const edgeCount = descriptor !== null ? descriptor.graph.edges.length : 0;
   const vc = versionCount(detail);
 
-  const hasGraph = descriptor !== null && edgeCount > 0;
-
   return (
-    <div
-      className="pt-3 border-t flex gap-4"
-      style={{ borderColor: "var(--color-border)" }}
-    >
-      <div className="space-y-3 shrink-0" style={{ minWidth: 200, maxWidth: 280 }}>
-        <div>
-          <p className="text-sm font-medium" style={{ color: "var(--color-text)" }}>
-            {detail.name}
-          </p>
-          <p className="text-xs mt-1 mb-1" style={{ color: "var(--color-text-muted)" }}>
-            Hash
-          </p>
-          <code className="text-xs font-mono block" style={{ color: "var(--color-accent)" }}>
-            {detail.hash}
-          </code>
-        </div>
-        <p className="text-xs" style={{ color: "var(--color-text-muted)" }}>
-          {vc} version{vc !== 1 ? "s" : ""}
+    <div className="pt-3 space-y-3 border-t" style={{ borderColor: "var(--color-border)" }}>
+      <div>
+        <p className="text-sm font-medium" style={{ color: "var(--color-text)" }}>
+          {detail.name}
         </p>
-        <div>
-          <p className="text-xs mb-1 font-medium" style={{ color: "var(--color-text-muted)" }}>
-            Description
-          </p>
-          <p className="text-sm whitespace-pre-wrap" style={{ color: "var(--color-text)" }}>
-            {descriptor !== null && descriptor.description !== ""
-              ? descriptor.description
-              : descriptor !== null
-                ? "—"
-                : "No descriptor available for this workflow version."}
-          </p>
-        </div>
+        <p className="text-xs mt-1 mb-1" style={{ color: "var(--color-text-muted)" }}>
+          Hash
+        </p>
+        <code className="text-xs font-mono block" style={{ color: "var(--color-accent)" }}>
+          {detail.hash}
+        </code>
       </div>
-      {hasGraph ? (
+      <p className="text-xs" style={{ color: "var(--color-text-muted)" }}>
+        {vc} version{vc !== 1 ? "s" : ""}
+      </p>
+      <div>
+        <p className="text-xs mb-1 font-medium" style={{ color: "var(--color-text-muted)" }}>
+          Description
+        </p>
+        <p className="text-sm whitespace-pre-wrap" style={{ color: "var(--color-text)" }}>
+          {descriptor !== null && descriptor.description !== ""
+            ? descriptor.description
+            : descriptor !== null
+              ? "—"
+              : "No descriptor available for this workflow version."}
+        </p>
+      </div>
+      {descriptor !== null && edgeCount > 0 ? (
         <div
-          className="rounded-lg border overflow-hidden flex-1"
-          style={{ borderColor: "var(--color-border)", background: "var(--color-bg)", minHeight: 500 }}
+          className="rounded-lg border overflow-hidden"
+          style={{ borderColor: "var(--color-border)", background: "var(--color-bg)" }}
         >
           <div
             className="px-3 py-2 text-xs flex justify-between items-center"
@@ -94,7 +87,7 @@ function ExpandedWorkflowBody({
               {edgeCount} edge{edgeCount === 1 ? "" : "s"}
             </span>
           </div>
-          <div style={{ height: 600, width: "100%" }}>
+          <div style={{ height: 300, width: "100%" }}>
             <WorkflowGraph
               graph={descriptor.graph}
               roles={descriptor.roles}
@@ -155,17 +148,18 @@ export function WorkflowList({ agent }: Props) {
   );
 
   function toggleExpanded(name: string) {
-    const wasExpanded = expanded.has(name);
+    let shouldLoad = false;
     setExpanded((prev) => {
       const next = new Set(prev);
       if (next.has(name)) {
         next.delete(name);
-      } else {
-        next.add(name);
+        return next;
       }
+      next.add(name);
+      shouldLoad = true;
       return next;
     });
-    if (!wasExpanded) {
+    if (shouldLoad) {
       ensureDetailLoaded(name);
     }
   }

packages/workflow-execute/__tests__/merkle-call-stack.test.ts

@@ -14,7 +14,7 @@ import type {
 } from "@uncaged/workflow-runtime";
 
 import { executeThread } from "../src/engine/engine.js";
-import type { ExecuteThreadOptions } from "../src/engine/types.js";
+import type { ExecuteThreadIo, ExecuteThreadOptions } from "../src/engine/types.js";
 
 const TEST_REGISTRY_YAML = `config:
   maxDepth: 3

packages/workflow-execute/package.json

@@ -1,10 +1,6 @@
 {
   "name": "@uncaged/workflow-execute",
-  "version": "0.3.21",
-  "files": [
-    "dist",
-    "package.json"
-  ],
+  "version": "0.3.11",
   "type": "module",
   "exports": {
     ".": {

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

@@ -299,37 +299,7 @@ async function driveWorkflowGenerator(params: {
       });
     }
 
-    const iterResult = await Promise.race([
-      gen.next(),
-      new Promise<never>((_, reject) => {
-        if (executeOptions.signal.aborted) {
-          reject(new DOMException("The operation was aborted", "AbortError"));
-          return;
-        }
-        executeOptions.signal.addEventListener(
-          "abort",
-          () => reject(new DOMException("The operation was aborted", "AbortError")),
-          { once: true },
-        );
-      }),
-    ]).catch((e) => {
-      if (e instanceof DOMException && e.name === "AbortError") {
-        return { done: true as const, value: { returnCode: 130, summary: "thread aborted" } };
-      }
-      throw e;
-    });
-
-    if (executeOptions.signal.aborted || (iterResult.done && iterResult.value.returnCode === 130)) {
-      return await finalizeAbortedThread({
-        cas,
-        bundleDir,
-        threadId,
-        startHash,
-        chain,
-        logger,
-        abortLogTag: "H4KQ7RW3",
-      });
-    }
+    const iterResult = await gen.next();
 
     if (iterResult.done) {
       logger("F3HN8QKP", `thread ${threadId} generator finished`);

packages/workflow-execute/src/index.ts

@@ -42,7 +42,4 @@ export {
   llmErrorToCause,
   llmExtract,
 } from "./extract/index.js";
-export { type WorkflowAdapterOptions, workflowAdapter } from "./workflow-adapter.js";
-
-/** @deprecated Use {@link workflowAdapter} instead. */
 export { type WorkflowAsAgentOptions, workflowAsAgent } from "./workflow-as-agent.js";

packages/workflow-execute/src/workflow-adapter.ts

@@ -1,165 +0,0 @@
-import { join } from "node:path";
-import { createCasStore, putContentNodeWithRefs } from "@uncaged/workflow-cas";
-import type { WorkflowConfig } from "@uncaged/workflow-register";
-import {
-  extractBundleExports,
-  getRegisteredWorkflow,
-  readWorkflowRegistry,
-} from "@uncaged/workflow-register";
-import type {
-  AdapterFn,
-  RoleResult,
-  ThreadContext,
-  WorkflowFn,
-  WorkflowRuntime,
-} from "@uncaged/workflow-runtime";
-import {
-  createLogger,
-  generateUlid,
-  getDefaultWorkflowStorageRoot,
-  getGlobalCasDir,
-} from "@uncaged/workflow-util";
-import type * as z from "zod/v4";
-import type { ExecuteThreadIo } from "./engine/index.js";
-import { executeThread, getBundleDir, readThreadsIndex } from "./engine/index.js";
-
-const DEFAULT_WORKFLOW_ADAPTER_MAX_DEPTH = 3;
-
-function workflowAdapterMaxDepth(config: WorkflowConfig | null): number {
-  return config === null ? DEFAULT_WORKFLOW_ADAPTER_MAX_DEPTH : config.maxDepth;
-}
-
-export type WorkflowAdapterOptions = {
-  /** When `null`, uses `getDefaultWorkflowStorageRoot()`. */
-  storageRoot: string | null;
-};
-
-function resolveStorageRoot(options: WorkflowAdapterOptions | null): string {
-  if (options !== null && options.storageRoot !== null) {
-    return options.storageRoot;
-  }
-  return getDefaultWorkflowStorageRoot();
-}
-
-async function readParentHeadState(
-  storageRoot: string,
-  ctx: ThreadContext,
-): Promise<string | null> {
-  const bundleDir = getBundleDir(storageRoot, ctx.bundleHash);
-  const index = await readThreadsIndex(bundleDir);
-  const entry = index[ctx.threadId] ?? null;
-  return entry !== null ? entry.head : null;
-}
-
-/** Resolve the workflow bundle and validate depth limits. */
-async function resolveWorkflowBundle(workflowName: string, storageRoot: string, nextDepth: number) {
-  const registryResult = await readWorkflowRegistry(storageRoot);
-  if (!registryResult.ok) {
-    throw new Error(`failed to read workflow registry: ${registryResult.error.message}`);
-  }
-
-  const maxDepth = workflowAdapterMaxDepth(registryResult.value.config);
-  if (nextDepth > maxDepth) {
-    throw new Error(`workflow adapter depth limit exceeded (max ${maxDepth})`);
-  }
-
-  const entry = getRegisteredWorkflow(registryResult.value, workflowName);
-  if (entry === null) {
-    throw new Error(`workflow "${workflowName}" not found in registry`);
-  }
-
-  const bundlePath = join(storageRoot, "bundles", `${entry.hash}.esm.js`);
-  const bundleExportsResult = await extractBundleExports(bundlePath, { storageRoot });
-  if (!bundleExportsResult.ok) {
-    throw new Error(String(bundleExportsResult.error));
-  }
-
-  return { entry, run: bundleExportsResult.value.run };
-}
-
-/** Execute the child workflow thread and return a summary + root hash. */
-async function runChildThread(params: {
-  workflowName: string;
-  storageRoot: string;
-  ctx: ThreadContext;
-  run: WorkflowFn;
-  bundleHash: string;
-  nextDepth: number;
-}) {
-  const { workflowName, storageRoot, ctx, run, bundleHash, nextDepth } = params;
-  const childThreadId = generateUlid(Date.now());
-  const infoJsonlPath = join(storageRoot, "logs", bundleHash, `${childThreadId}.info.jsonl`);
-
-  const io: ExecuteThreadIo = {
-    threadId: childThreadId,
-    hash: bundleHash,
-    infoJsonlPath,
-    cas: createCasStore(getGlobalCasDir(storageRoot)),
-  };
-
-  const logger = createLogger({ sink: { kind: "file", path: infoJsonlPath } });
-  const parentHeadState = await readParentHeadState(storageRoot, ctx);
-
-  const result = await executeThread(
-    run,
-    workflowName,
-    { prompt: ctx.start.content, steps: [] },
-    {
-      depth: nextDepth,
-      parentStateHash: parentHeadState,
-      signal: new AbortController().signal,
-      awaitAfterEachYield: async () => {},
-      forkSourceThreadId: ctx.threadId,
-      prefilledDiskSteps: null,
-      forkContinuation: null,
-      replayTimestamps: null,
-      storageRoot,
-    },
-    io,
-    logger,
-  );
-
-  return {
-    summary: `Child workflow "${workflowName}" completed (returnCode=${result.returnCode}).\n\nSummary: ${result.summary}\n\nChild thread root hash: ${result.rootHash}`,
-    rootHash: result.rootHash,
-  };
-}
-
-/**
- * Returns an {@link AdapterFn} that runs another registered workflow in a new child thread,
- * using the parent thread's initial prompt (`ctx.start.content`) as the child prompt.
- *
- * The child thread's root hash is returned as `childThread` in the result,
- * enabling parent→child tracking in the CAS Merkle tree.
- */
-export function workflowAdapter(
-  workflowName: string,
-  options: WorkflowAdapterOptions | null = null,
-): AdapterFn {
-  return <T>(_prompt: string, schema: z.ZodType<T>) => {
-    return async (ctx: ThreadContext, runtime: WorkflowRuntime): Promise<RoleResult<T>> => {
-      const storageRoot = resolveStorageRoot(options);
-      const { entry, run } = await resolveWorkflowBundle(workflowName, storageRoot, ctx.depth + 1);
-
-      try {
-        const { summary, rootHash } = await runChildThread({
-          workflowName,
-          storageRoot,
-          ctx,
-          run,
-          bundleHash: entry.hash,
-          nextDepth: ctx.depth + 1,
-        });
-        const contentHash = await putContentNodeWithRefs(runtime.cas, summary, []);
-        const extracted = await runtime.extract(
-          schema as z.ZodType<Record<string, unknown>>,
-          contentHash,
-        );
-        return { meta: extracted.meta as T, childThread: rootHash };
-      } catch (e) {
-        const message = e instanceof Error ? e.message : String(e);
-        throw new Error(`child workflow "${workflowName}" failed: ${message}`);
-      }
-    };
-  };
-}

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

@@ -1,8 +1,127 @@
+import { join } from "node:path";
+import { createCasStore } from "@uncaged/workflow-cas";
+import type { WorkflowConfig } from "@uncaged/workflow-register";
+import {
+  extractBundleExports,
+  getRegisteredWorkflow,
+  readWorkflowRegistry,
+} from "@uncaged/workflow-register";
+import type { AgentContext, AgentFn, AgentFnResult } from "@uncaged/workflow-runtime";
+import {
+  createLogger,
+  generateUlid,
+  getDefaultWorkflowStorageRoot,
+  getGlobalCasDir,
+} from "@uncaged/workflow-util";
+import type { ExecuteThreadIo } from "./engine/index.js";
+import { executeThread, getBundleDir, readThreadsIndex } from "./engine/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;
+};
+
+function resolveWorkflowAsAgentStorageRoot(options: WorkflowAsAgentOptions | null): string {
+  if (options !== null && options.storageRoot !== null) {
+    return options.storageRoot;
+  }
+  return getDefaultWorkflowStorageRoot();
+}
+
+async function readParentHeadState(storageRoot: string, ctx: AgentContext): Promise<string | null> {
+  const bundleDir = getBundleDir(storageRoot, ctx.bundleHash);
+  const index = await readThreadsIndex(bundleDir);
+  const entry = index[ctx.threadId] ?? null;
+  return entry !== null ? entry.head : null;
+}
+
 /**
- * @deprecated Use `workflowAdapter` from `./workflow-adapter.js` instead.
- * This module is kept for backward compatibility and will be removed in a future release.
+ * Returns an {@link AgentFn} that runs another registered workflow in a new thread,
+ * using the parent thread's initial prompt (`ctx.start.content`) as the child prompt.
  */
-export {
-  type WorkflowAdapterOptions as WorkflowAsAgentOptions,
-  workflowAdapter as workflowAsAgent,
-} from "./workflow-adapter.js";
+export function workflowAsAgent(
+  workflowName: string,
+  options: WorkflowAsAgentOptions | null = null,
+): AgentFn {
+  return async (ctx: AgentContext): Promise<AgentFnResult> => {
+    const nextDepth = ctx.depth + 1;
+
+    const storageRoot = resolveWorkflowAsAgentStorageRoot(options);
+
+    const registryResult = await readWorkflowRegistry(storageRoot);
+    if (!registryResult.ok) {
+      return { output: `ERROR: failed to read workflow registry: ${registryResult.error.message}`, childThread: null };
+    }
+
+    const maxDepth = workflowAsAgentMaxDepth(registryResult.value.config);
+    if (nextDepth > maxDepth) {
+      return { output: `ERROR: workflow-as-agent depth limit exceeded (max ${maxDepth})`, childThread: null };
+    }
+
+    const entry = getRegisteredWorkflow(registryResult.value, workflowName);
+    if (entry === null) {
+      return { output: `ERROR: workflow "${workflowName}" not found in registry`, childThread: null };
+    }
+
+    const bundlePath = join(storageRoot, "bundles", `${entry.hash}.esm.js`);
+    const bundleExportsResult = await extractBundleExports(bundlePath, { storageRoot });
+    if (!bundleExportsResult.ok) {
+      return { output: `ERROR: ${bundleExportsResult.error}`, childThread: null };
+    }
+
+    const input = {
+      prompt: ctx.start.content,
+      steps: [],
+    };
+
+    const childThreadId = generateUlid(Date.now());
+    const infoJsonlPath = join(storageRoot, "logs", entry.hash, `${childThreadId}.info.jsonl`);
+
+    const io: ExecuteThreadIo = {
+      threadId: childThreadId,
+      hash: entry.hash,
+      infoJsonlPath,
+      cas: createCasStore(getGlobalCasDir(storageRoot)),
+    };
+
+    const logger = createLogger({ sink: { kind: "file", path: infoJsonlPath } });
+    const signalNever = new AbortController();
+
+    const parentHeadState = await readParentHeadState(storageRoot, ctx);
+
+    try {
+      const result = await executeThread(
+        bundleExportsResult.value.run,
+        workflowName,
+        input,
+        {
+          depth: nextDepth,
+          parentStateHash: parentHeadState,
+          signal: signalNever.signal,
+          awaitAfterEachYield: async () => {},
+          forkSourceThreadId: ctx.threadId,
+          prefilledDiskSteps: null,
+          forkContinuation: null,
+          replayTimestamps: null,
+          storageRoot,
+        },
+        io,
+        logger,
+      );
+      const summary = `Child workflow "${workflowName}" completed (returnCode=${result.returnCode}).\n\nSummary: ${result.summary}\n\nChild thread root hash: ${result.rootHash}`;
+      return { output: summary, childThread: result.rootHash };
+    } catch (e) {
+      const message = e instanceof Error ? e.message : String(e);
+      return { output: `ERROR: ${message}`, childThread: null };
+    }
+  };
+}

packages/workflow-gateway/package.json

@@ -1,10 +1,6 @@
 {
   "name": "@uncaged/workflow-gateway",
-  "version": "0.3.21",
-  "files": [
-    "dist",
-    "package.json"
-  ],
+  "version": "0.3.11",
   "type": "module",
   "exports": {
     ".": "./src/index.ts",

packages/workflow-protocol/package.json

@@ -1,10 +1,6 @@
 {
   "name": "@uncaged/workflow-protocol",
-  "version": "0.3.21",
-  "files": [
-    "dist",
-    "package.json"
-  ],
+  "version": "0.3.11",
   "type": "module",
   "exports": {
     ".": {

packages/workflow-protocol/src/index.ts

@@ -12,7 +12,10 @@ export type {
   AdapterBinding,
   AdapterFn,
   AdvanceOutcome,
+  AgentBinding,
   AgentContext,
+  AgentFn,
+  AgentFnResult,
   CasStore,
   ExtractFn,
   ExtractResult,
@@ -27,9 +30,9 @@ export type {
   Result,
   RoleDefinition,
   RoleFn,
+  RoleResult,
   RoleMeta,
   RoleOutput,
-  RoleResult,
   RoleStep,
   StartStep,
   ThreadContext,

packages/workflow-protocol/src/types.ts

@@ -143,6 +143,18 @@ export type ExtractFn = <T extends Record<string, unknown>>(
   contentHash: string,
 ) => Promise<ExtractResult<T>>;
 
+/** @deprecated Use {@link AdapterFn} instead. Will be removed in a future release. */
+export type AgentFnResult = string | { output: string; childThread: string | null };
+
+/** @deprecated Use {@link AdapterFn} instead. Will be removed in a future release. */
+export type AgentFn = (ctx: AgentContext) => Promise<AgentFnResult>;
+
+/** @deprecated Use {@link AdapterBinding} instead. Will be removed in a future release. */
+export type AgentBinding = {
+  agent: AgentFn;
+  overrides: Partial<Record<string, AgentFn>> | null;
+};
+
 // ── Adapter (replaces Agent) ────────────────────────────────────────
 
 export type RoleResult<T> = { meta: T; childThread: string | null };

packages/workflow-reactor/package.json

@@ -1,10 +1,6 @@
 {
   "name": "@uncaged/workflow-reactor",
-  "version": "0.3.21",
-  "files": [
-    "dist",
-    "package.json"
-  ],
+  "version": "0.3.11",
   "type": "module",
   "exports": {
     ".": {

packages/workflow-register/package.json

@@ -1,10 +1,6 @@
 {
   "name": "@uncaged/workflow-register",
-  "version": "0.3.21",
-  "files": [
-    "dist",
-    "package.json"
-  ],
+  "version": "0.3.11",
   "type": "module",
   "exports": {
     ".": {

packages/workflow-runtime/package.json

@@ -1,10 +1,6 @@
 {
   "name": "@uncaged/workflow-runtime",
-  "version": "0.3.21",
-  "files": [
-    "dist",
-    "package.json"
-  ],
+  "version": "0.3.11",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -20,11 +16,5 @@
   },
   "devDependencies": {
     "zod": "^4.0.0"
-  },
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./src/index.ts"
-    }
   }
 }

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

@@ -37,7 +37,7 @@ function resolveExtractedRefs(
   return extractRefsFn(meta as Record<string, unknown>);
 }
 
-function _mergeUniqueHashes(a: readonly string[], b: readonly string[]): string[] {
+function mergeUniqueHashes(a: readonly string[], b: readonly string[]): string[] {
   const seen = new Set<string>();
   const out: string[] = [];
   for (const h of [...a, ...b]) {
@@ -83,10 +83,7 @@ async function advanceOneRound<M extends RoleMeta>(
   }
 
   const adapter = adapterForRole(binding, next);
-  const roleFn = adapter(
-    roleDef.systemPrompt,
-    roleDef.schema as z.ZodType<Record<string, unknown>>,
-  );
+  const roleFn = adapter(roleDef.systemPrompt, roleDef.schema as z.ZodType<Record<string, unknown>>);
   const result = await roleFn(modCtx as unknown as ThreadContext, runtime);
   const meta = result.meta;
 

packages/workflow-runtime/src/index.ts

@@ -4,7 +4,10 @@ export { err, ok } from "./result.js";
 export type {
   AdapterBinding,
   AdapterFn,
+  AgentBinding,
   AgentContext,
+  AgentFn,
+  AgentFnResult,
   CasStore,
   ExtractFn,
   ExtractResult,
@@ -17,9 +20,9 @@ export type {
   Result,
   RoleDefinition,
   RoleFn,
+  RoleResult,
   RoleMeta,
   RoleOutput,
-  RoleResult,
   RoleStep,
   StartStep,
   ThreadContext,

packages/workflow-runtime/src/types.ts

@@ -6,7 +6,10 @@ export type {
   AdapterBinding,
   AdapterFn,
   AdvanceOutcome,
+  AgentBinding,
   AgentContext,
+  AgentFn,
+  AgentFnResult,
   CasStore,
   ExtractFn,
   ExtractResult,
@@ -21,9 +24,9 @@ export type {
   Result,
   RoleDefinition,
   RoleFn,
+  RoleResult,
   RoleMeta,
   RoleOutput,
-  RoleResult,
   RoleStep,
   StartStep,
   ThreadContext,

packages/workflow-template-develop/bundle-entry.ts

@@ -5,20 +5,34 @@
  */
 import { createCursorAgent } from "@uncaged/workflow-agent-cursor";
 import { createWorkflow } from "@uncaged/workflow-runtime";
-import { optionalEnv, requireEnv } from "@uncaged/workflow-util";
+import { wrapAgentAsAdapter } from "@uncaged/workflow-util-agent";
 import { buildDevelopDescriptor, developWorkflowDefinition } from "./src/index.js";
 
+function requireEnv(name: string): string {
+  const value = process.env[name];
+  if (value === undefined || value === "") {
+    throw new Error(`missing required env var: ${name}`);
+  }
+  return value;
+}
+
+function optionalEnv(name: string): string | null {
+  const value = process.env[name];
+  if (value === undefined || value === "") {
+    return null;
+  }
+  return value;
+}
+
 const llmProvider = {
-  baseUrl: optionalEnv(
-    "WORKFLOW_LLM_BASE_URL",
-    "https://dashscope.aliyuncs.com/compatible-mode/v1",
-  ),
-  apiKey: requireEnv("WORKFLOW_LLM_API_KEY", "set WORKFLOW_LLM_API_KEY for meta extraction"),
-  model: optionalEnv("WORKFLOW_LLM_MODEL", "qwen-plus"),
+  baseUrl:
+    optionalEnv("WORKFLOW_LLM_BASE_URL") ?? "https://dashscope.aliyuncs.com/compatible-mode/v1",
+  apiKey: requireEnv("WORKFLOW_LLM_API_KEY"),
+  model: optionalEnv("WORKFLOW_LLM_MODEL") ?? "qwen-plus",
 };
 
-const adapter = createCursorAgent({
-  command: requireEnv("WORKFLOW_CURSOR_COMMAND", "set WORKFLOW_CURSOR_COMMAND (e.g. cursor-agent)"),
+const agent = createCursorAgent({
+  command: requireEnv("WORKFLOW_CURSOR_COMMAND"),
   model: optionalEnv("WORKFLOW_CURSOR_MODEL"),
   timeout: optionalEnv("WORKFLOW_CURSOR_TIMEOUT")
     ? Number(optionalEnv("WORKFLOW_CURSOR_TIMEOUT"))
@@ -27,6 +41,8 @@ const adapter = createCursorAgent({
   llmProvider,
 });
 
+const adapter = wrapAgentAsAdapter(agent);
+
 const wf = createWorkflow(developWorkflowDefinition, { adapter, overrides: null });
 
 export const descriptor = buildDevelopDescriptor();

packages/workflow-template-develop/package.json

@@ -1,10 +1,6 @@
 {
   "name": "@uncaged/workflow-template-develop",
-  "version": "0.3.21",
-  "files": [
-    "dist",
-    "package.json"
-  ],
+  "version": "0.3.11",
   "type": "module",
   "exports": {
     ".": {

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

@@ -215,7 +215,10 @@ describe("solveIssueWorkflowDefinition + createWorkflow", () => {
     });
     const gen = run(makeThread("task"), {
       cas,
-      extract: createExtract({ baseUrl: "http://127.0.0.1:9", apiKey: "", model: "test" }, { cas }),
+      extract: createExtract(
+        { baseUrl: "http://127.0.0.1:9", apiKey: "", model: "test" },
+        { cas },
+      ),
     });
     const first = await gen.next();
     expect(first.done).toBe(false);
@@ -258,7 +261,10 @@ describe("solveIssueWorkflowDefinition + createWorkflow", () => {
     });
     const gen = run(makeThread("task"), {
       cas,
-      extract: createExtract({ baseUrl: "http://127.0.0.1:9", apiKey: "", model: "test" }, { cas }),
+      extract: createExtract(
+        { baseUrl: "http://127.0.0.1:9", apiKey: "", model: "test" },
+        { cas },
+      ),
     });
     await gen.next();
     expect(calls).toEqual(["preparer"]);

packages/workflow-template-solve-issue/bundle-entry.ts

@@ -2,25 +2,38 @@
  * solve-issue bundle entry — 小橘 🍊
  *
  * preparer + submitter → hermes agent
- * developer → workflow adapter (delegates to "develop" workflow)
+ * developer → workflow-as-agent (delegates to "develop" workflow)
  */
 import { createHermesAgent } from "@uncaged/workflow-agent-hermes";
-import { workflowAdapter } from "@uncaged/workflow-execute";
+import { workflowAsAgent } from "@uncaged/workflow-execute";
 import { createWorkflow } from "@uncaged/workflow-runtime";
-import { optionalEnv } from "@uncaged/workflow-util";
+import { wrapAgentAsAdapter } from "@uncaged/workflow-util-agent";
 import { buildSolveIssueDescriptor, solveIssueWorkflowDefinition } from "./src/index.js";
 
-const adapter = createHermesAgent({
+function optionalEnv(name: string): string | null {
+  const value = process.env[name];
+  if (value === undefined || value === "") {
+    return null;
+  }
+  return value;
+}
+
+const hermesAgent = createHermesAgent({
   model: optionalEnv("WORKFLOW_HERMES_MODEL"),
   timeout: optionalEnv("WORKFLOW_HERMES_TIMEOUT")
     ? Number(optionalEnv("WORKFLOW_HERMES_TIMEOUT"))
     : null,
 });
 
+const developerAgent = workflowAsAgent("develop");
+
+const adapter = wrapAgentAsAdapter(hermesAgent);
+const developerAdapter = wrapAgentAsAdapter(developerAgent);
+
 const wf = createWorkflow(solveIssueWorkflowDefinition, {
   adapter,
   overrides: {
-    developer: workflowAdapter("develop"),
+    developer: developerAdapter,
   },
 });
 

packages/workflow-template-solve-issue/package.json

@@ -1,10 +1,6 @@
 {
   "name": "@uncaged/workflow-template-solve-issue",
-  "version": "0.3.21",
-  "files": [
-    "dist",
-    "package.json"
-  ],
+  "version": "0.3.11",
   "type": "module",
   "exports": {
     ".": {

packages/workflow-util-agent/package.json

@@ -1,10 +1,6 @@
 {
   "name": "@uncaged/workflow-util-agent",
-  "version": "0.3.21",
-  "files": [
-    "dist",
-    "package.json"
-  ],
+  "version": "0.3.11",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -19,7 +15,6 @@
   },
   "dependencies": {
     "@uncaged/workflow-runtime": "workspace:*",
-    "@uncaged/workflow-cas": "workspace:*",
-    "zod": "^4.0.0"
+    "@uncaged/workflow-cas": "workspace:*"
   }
 }

packages/workflow-util-agent/src/create-text-adapter.ts

@@ -1,51 +0,0 @@
-import { putContentNodeWithRefs } from "@uncaged/workflow-cas";
-import type {
-  AdapterFn,
-  RoleResult,
-  ThreadContext,
-  WorkflowRuntime,
-} from "@uncaged/workflow-runtime";
-import type * as z from "zod/v4";
-
-/**
- * Result from a text-producing agent (CLI spawn, LLM call, etc.).
- * `output` is the raw text; `childThread` links to a spawned sub-workflow.
- */
-export type TextAdapterResult = {
-  output: string;
-  childThread: string | null;
-};
-
-/**
- * A function that produces raw text output given the thread context and
- * the system prompt for the current role.
- */
-export type TextProducerFn = (
-  ctx: ThreadContext,
-  prompt: string,
-) => Promise<string | TextAdapterResult>;
-
-/**
- * Creates an {@link AdapterFn} from a text-producing function.
- *
- * The adapter:
- * 1. Calls the producer with thread context + system prompt
- * 2. Stores output in CAS
- * 3. Runs the extract phase to produce typed meta
- * 4. Returns `{ meta, childThread }`
- */
-export function createTextAdapter(producer: TextProducerFn): AdapterFn {
-  return <T>(prompt: string, schema: z.ZodType<T>) => {
-    return async (ctx: ThreadContext, runtime: WorkflowRuntime): Promise<RoleResult<T>> => {
-      const result = await producer(ctx, prompt);
-      const output = typeof result === "string" ? result : result.output;
-      const childThread = typeof result === "string" ? null : result.childThread;
-      const contentHash = await putContentNodeWithRefs(runtime.cas, output, []);
-      const extracted = await runtime.extract(
-        schema as z.ZodType<Record<string, unknown>>,
-        contentHash,
-      );
-      return { meta: extracted.meta as T, childThread };
-    };
-  };
-}

packages/workflow-util-agent/src/index.ts

@@ -1,5 +1,4 @@
 export { buildAgentPrompt, buildThreadInput } from "./build-agent-prompt.js";
-export type { TextAdapterResult, TextProducerFn } from "./create-text-adapter.js";
-export { createTextAdapter } from "./create-text-adapter.js";
 export type { SpawnCliConfig, SpawnCliError, SpawnCliResult } from "./spawn-cli.js";
 export { spawnCli } from "./spawn-cli.js";
+export { wrapAgentAsAdapter } from "./wrap-agent-as-adapter.js";

packages/workflow-util-agent/src/wrap-agent-as-adapter.ts

@@ -0,0 +1,31 @@
+import { putContentNodeWithRefs } from "@uncaged/workflow-cas";
+import type {
+  AdapterFn,
+  AgentContext,
+  AgentFnResult,
+  RoleResult,
+  ThreadContext,
+  WorkflowRuntime,
+} from "@uncaged/workflow-runtime";
+import type * as z from "zod/v4";
+
+/**
+ * Wraps a legacy AgentFn into an AdapterFn.
+ * The agent produces a string (or { output, childThread }); the adapter
+ * stores the output in CAS, runs extract, and returns typed meta + childThread.
+ */
+export function wrapAgentAsAdapter(
+  agentFn: (ctx: AgentContext) => Promise<AgentFnResult>,
+): AdapterFn {
+  return <T>(prompt: string, schema: z.ZodType<T>) => {
+    return async (ctx: ThreadContext, runtime: WorkflowRuntime): Promise<RoleResult<T>> => {
+      const agentCtx: AgentContext = { ...ctx, currentRole: { name: "agent", systemPrompt: prompt } };
+      const result = await agentFn(agentCtx);
+      const output = typeof result === "string" ? result : result.output;
+      const childThread = typeof result === "string" ? null : result.childThread;
+      const contentHash = await putContentNodeWithRefs(runtime.cas, output, []);
+      const extracted = await runtime.extract(schema as z.ZodType<Record<string, unknown>>, contentHash);
+      return { meta: extracted.meta as T, childThread };
+    };
+  };
+}

packages/workflow-util/__tests__/env.test.ts

@@ -1,44 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import { optionalEnv, requireEnv } from "../src/env.js";
-
-describe("requireEnv", () => {
-  test("returns value when set", () => {
-    process.env.TEST_REQ = "hello";
-    expect(requireEnv("TEST_REQ", "missing")).toBe("hello");
-    delete process.env.TEST_REQ;
-  });
-
-  test("throws with message when missing", () => {
-    expect(() => requireEnv("TEST_MISSING_XYZ", "need this")).toThrow("need this");
-  });
-
-  test("throws when empty string", () => {
-    process.env.TEST_EMPTY = "";
-    expect(() => requireEnv("TEST_EMPTY", "cannot be empty")).toThrow("cannot be empty");
-    delete process.env.TEST_EMPTY;
-  });
-});
-
-describe("optionalEnv", () => {
-  test("returns value when set", () => {
-    process.env.TEST_OPT = "world";
-    expect(optionalEnv("TEST_OPT")).toBe("world");
-    expect(optionalEnv("TEST_OPT", "default")).toBe("world");
-    delete process.env.TEST_OPT;
-  });
-
-  test("returns null when missing and no fallback", () => {
-    expect(optionalEnv("TEST_MISSING_ABC")).toBeNull();
-  });
-
-  test("returns fallback when missing", () => {
-    expect(optionalEnv("TEST_MISSING_ABC", "fallback")).toBe("fallback");
-  });
-
-  test("returns fallback when empty string", () => {
-    process.env.TEST_EMPTY2 = "";
-    expect(optionalEnv("TEST_EMPTY2", "fb")).toBe("fb");
-    expect(optionalEnv("TEST_EMPTY2")).toBeNull();
-    delete process.env.TEST_EMPTY2;
-  });
-});

packages/workflow-util/package.json

@@ -1,10 +1,6 @@
 {
   "name": "@uncaged/workflow-util",
-  "version": "0.3.21",
-  "files": [
-    "dist",
-    "package.json"
-  ],
+  "version": "0.3.11",
   "type": "module",
   "exports": {
     ".": {

packages/workflow-util/src/env.ts

@@ -1,23 +0,0 @@
-/**
- * Read a required environment variable. Throws with `message` if missing or empty.
- */
-export function requireEnv(name: string, message: string): string {
-  const value = process.env[name];
-  if (value === undefined || value === "") {
-    throw new Error(message);
-  }
-  return value;
-}
-
-/**
- * Read an optional environment variable. Returns `fallback` if missing or empty.
- */
-export function optionalEnv(name: string, fallback: string): string;
-export function optionalEnv(name: string): string | null;
-export function optionalEnv(name: string, fallback?: string): string | null {
-  const value = process.env[name];
-  if (value === undefined || value === "") {
-    return fallback ?? null;
-  }
-  return value;
-}

packages/workflow-util/src/index.ts

@@ -6,7 +6,6 @@ export {
   encodeCrockfordBase32Bits,
   encodeUint64AsCrockford,
 } from "./base32.js";
-export { optionalEnv, requireEnv } from "./env.js";
 export { createLogger } from "./logger.js";
 export { mergeRefsWithContentHash, normalizeRefsField } from "./refs-field.js";
 export { getDefaultWorkflowStorageRoot, getGlobalCasDir } from "./storage-root.js";

scripts/link-all.sh

@@ -1,49 +0,0 @@
-#!/usr/bin/env bash
-# Link / unlink all @uncaged/* packages from the workflow monorepo.
-#
-# Usage:
-#   ./scripts/link-all.sh              # Register all packages (run from monorepo root)
-#   ./scripts/link-all.sh --consume    # Link all packages into CWD's project
-#   ./scripts/link-all.sh --unlink     # Unregister all packages and restore CWD's deps
-
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-MONOREPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
-
-# Iterate package dirs, calling callback(dir, name) for each
-each_pkg() {
-  local cb="$1"
-  for dir in "$MONOREPO_ROOT"/packages/*/; do
-    [[ -f "$dir/package.json" ]] || continue
-    local name
-    name=$(grep -m1 '"name"' "$dir/package.json" | sed 's/.*: *"\(.*\)".*/\1/')
-    "$cb" "$dir" "$name"
-  done
-}
-
-do_register() { printf "  register  %s\n" "$2"; (cd "$1" && bun link 2>&1) > /dev/null; }
-do_consume()  { printf "  link      %s\n" "$2"; (bun link "$2" 2>&1) > /dev/null; }
-do_unlink()   { printf "  unlink    %s\n" "$2"; (cd "$1" && bun unlink 2>&1) > /dev/null || true; }
-
-case "${1:-}" in
-  --consume)
-    each_pkg do_consume
-    echo "✅ All @uncaged/* packages linked into $(pwd)"
-    echo "   ⚠️  Do NOT run 'bun install' after this — it will overwrite the links"
-    echo "   To restore: $0 --unlink"
-    ;;
-  --unlink)
-    each_pkg do_unlink
-    if [[ -f "package.json" ]]; then
-      echo "  reinstalling deps..."
-      bun install 2>&1 > /dev/null || true
-    fi
-    echo "✅ All @uncaged/* packages unlinked, deps restored"
-    ;;
-  *)
-    each_pkg do_register
-    echo "✅ All @uncaged/* packages registered"
-    echo "   cd <project> && $0 --consume"
-    ;;
-esac

scripts/publish-all.sh

@@ -1,11 +1,6 @@
 #!/usr/bin/env bash
 # Publish all public @uncaged/* packages to Gitea npm registry.
 #
-# PITFALL: After bumping versions in package.json, bun pm pack still reads the
-# old bun.lock and resolves workspace:* to the previous (stale) versions.
-# This script deletes bun.lock and runs bun install before packing to force
-# correct resolution of workspace:* dependencies.
-#
 # Usage:
 #   ./scripts/publish-all.sh           # Publish all packages
 #   ./scripts/publish-all.sh --dry-run # Show what would be published
@@ -22,7 +17,7 @@ set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 MONOREPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
 
-REGISTRY="https://git.shazhou.work/api/packages/uncaged/npm/"
+REGISTRY="https://git.shazhou.work/api/packages/shazhou/npm/"
 DRY_RUN=""
 
 if [[ "${1:-}" == "--dry-run" ]]; then
@@ -100,11 +95,6 @@ for name in result:
     print(name_to_dir[name])
 ")
 
-# Regenerate lockfile so bun pm pack resolves workspace:* to freshly-bumped versions
-cd "$MONOREPO_ROOT"
-rm -f bun.lock
-bun install
-
 ok=0
 fail=0
 

scripts/publish.sh

@@ -13,7 +13,8 @@ set -euo pipefail
 REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
 cd "$REPO_ROOT"
 
-GITEA_TOKEN="${GITEA_TOKEN:?GITEA_TOKEN is required}"  # needed by .npmrc
+GITEA_TOKEN="${GITEA_TOKEN:?GITEA_TOKEN is required}"
+GITEA_NPM_REGISTRY="https://git.shazhou.work/api/packages/uncaged/npm/"
 
 # ─── Version ─────────────────────────────────────────────────────────────────
 current_version() {
@@ -35,6 +36,24 @@ CURRENT=$(current_version)
 VERSION=$(bump_version "$CURRENT" "${1:?Usage: publish.sh <version|patch|minor|major>}")
 echo "📦 Publish: $CURRENT → $VERSION"
 
+# ─── Topological publish order ───────────────────────────────────────────────
+PUBLISH_ORDER=(
+  workflow-protocol
+  workflow-util
+  workflow-cas
+  workflow-runtime
+  workflow-reactor
+  workflow-register
+  workflow-execute
+  cli-workflow
+  workflow-util-agent
+  workflow-agent-cursor
+  workflow-agent-hermes
+  workflow-agent-llm
+  workflow-template-develop
+  workflow-template-solve-issue
+)
+
 # ─── Bump version ────────────────────────────────────────────────────────────
 echo "🔢 Bumping versions..."
 for dir in packages/*/; do
@@ -73,16 +92,22 @@ done
 echo "🔨 Building..."
 npm run build
 
-# ─── Self-test ────────────────────────────────────────────────────────────────
-echo "🧪 Running tests..."
-if ! bun test; then
-  echo "❌ Tests failed — aborting publish"
-  exit 1
-fi
+# ─── Publish ─────────────────────────────────────────────────────────────────
+echo "🚀 Publishing..."
+cat > "$REPO_ROOT/.npmrc" <<EOF
+@uncaged:registry=${GITEA_NPM_REGISTRY}
+//${GITEA_NPM_REGISTRY#https://}:_authToken=${GITEA_TOKEN}
+EOF
 
-# ─── Publish (delegate to publish-all.sh) ────────────────────────────────────
-echo "🚀 Publishing via publish-all.sh..."
-"$REPO_ROOT/scripts/publish-all.sh"
+FAIL=0
+for pkg_dir in "${PUBLISH_ORDER[@]}"; do
+  if (cd "packages/$pkg_dir" && npm publish 2>&1); then
+    echo "  ✅ @uncaged/$pkg_dir@$VERSION"
+  else
+    echo "  ❌ @uncaged/$pkg_dir"
+    FAIL=1
+  fi
+done
 
 # ─── Restore workspace:* ─────────────────────────────────────────────────────
 echo "🔄 Restoring workspace:*..."
@@ -111,4 +136,4 @@ git commit -m "chore: publish v${VERSION}
 小橘 <xiaoju@shazhou.work>"
 git push
 
-echo "✅ v${VERSION} published"
+[[ "$FAIL" -eq 0 ]] && echo "✅ v${VERSION} published" || echo "⚠️ v${VERSION} published with errors"

tsconfig.json

@@ -15,7 +15,7 @@
     "sourceMap": true,
     "composite": true,
     "outDir": "dist",
-    "types": ["bun-types", "node"]
+    "types": ["bun-types"]
   },
   "references": [
     { "path": "packages/workflow-runtime" },