feat(uwf-agent-kit): frontmatter fast path + prompt injection

Port RFC #351 frontmatter markdown to uwf-* path:
- tryFrontmatterFastPath(): parse → validate → JSON Schema check via json-cas
- Happy path skips LLM extract, fallback to existing extract()
- buildOutputFormatInstruction(): generates deliverable format from JSON Schema
- Injected into agent context before execution
- Scope reminder: 'Focus exclusively on YOUR role's deliverable'
- 14 new tests (vitest)

Closes #355

.changeset/env-api-unify.md

@@ -0,0 +1,5 @@
+---
+"@uncaged/workflow-util": patch
+---
+
+Replace optionalEnv/requireEnv with unified env(name, fallback) API

.changeset/fix-internal-deps.md

@@ -0,0 +1,5 @@
+---
+"@uncaged/workflow-protocol": patch
+---
+
+fix: correct internal dependency versions for prerelease

.changeset/fix-publish-src.md

@@ -0,0 +1,5 @@
+---
+"@uncaged/workflow-util-agent": patch
+---
+
+fix: include create-agent-adapter.ts in published src

.changeset/fix-workspace-deps.md

@@ -0,0 +1,5 @@
+---
+"@uncaged/workflow-protocol": patch
+---
+
+fix: use npm publish with pinned deps instead of bun publish (workspace:^ resolution bug)

.changeset/pre.json

@@ -0,0 +1,30 @@
+{
+  "mode": "pre",
+  "tag": "alpha",
+  "initialVersions": {
+    "@uncaged/cli-workflow": "0.4.5",
+    "@uncaged/workflow-agent-cursor": "0.4.5",
+    "@uncaged/workflow-agent-hermes": "0.4.5",
+    "@uncaged/workflow-agent-llm": "0.4.5",
+    "@uncaged/workflow-agent-react": "0.4.5",
+    "@uncaged/workflow-cas": "0.4.5",
+    "@uncaged/workflow-dashboard": "0.1.0",
+    "@uncaged/workflow-execute": "0.4.5",
+    "@uncaged/workflow-gateway": "0.4.5",
+    "@uncaged/workflow-protocol": "0.4.5",
+    "@uncaged/workflow-reactor": "0.4.5",
+    "@uncaged/workflow-register": "0.4.5",
+    "@uncaged/workflow-runtime": "0.4.5",
+    "@uncaged/workflow-template-develop": "0.4.5",
+    "@uncaged/workflow-template-solve-issue": "0.4.5",
+    "@uncaged/workflow-util": "0.4.5",
+    "@uncaged/workflow-util-agent": "0.4.5"
+  },
+  "changesets": [
+    "env-api-unify",
+    "fix-internal-deps",
+    "fix-publish-src",
+    "fix-workspace-deps",
+    "rfc-252-agent-fn"
+  ]
+}

.changeset/rfc-252-agent-fn.md

@@ -0,0 +1,5 @@
+---
+"@uncaged/workflow-protocol": minor
+---
+
+feat: AgentFn<Opt> type boundary and createAgentAdapter bridging function (RFC #252)

.env.example

@@ -0,0 +1,40 @@
+# ──────────────────────────────────────────────
+# Workflow Engine — Environment Variables
+# ──────────────────────────────────────────────
+# Copy this file to .env and fill in the values.
+
+# ── Cursor Agent ──
+
+# CLI command to invoke the Cursor agent (required for develop workflow)
+WORKFLOW_CURSOR_COMMAND=
+
+# Model override for Cursor agent
+WORKFLOW_CURSOR_MODEL=
+
+# Timeout in milliseconds for Cursor agent operations
+WORKFLOW_CURSOR_TIMEOUT=
+
+# ── Hermes Agent (used by develop tester/committer + solve-issue) ──
+
+# CLI command to invoke the Hermes agent (absolute path required)
+WORKFLOW_HERMES_COMMAND=
+
+# Model override for Hermes agent
+WORKFLOW_HERMES_MODEL=
+
+# Timeout in milliseconds for Hermes agent operations
+WORKFLOW_HERMES_TIMEOUT=
+
+# ── Storage ──
+
+# Override the workflow storage root directory
+# Default: ~/.uncaged/workflow
+WORKFLOW_STORAGE_ROOT=
+
+# Gateway secret for the serve command
+WORKFLOW_DASHBOARD_SECRET=
+
+# ── Display ──
+
+# Set to any value to disable colored output
+# NO_COLOR=1

.githooks/pre-push

@@ -1,6 +1,10 @@
 #!/usr/bin/env bash
-# pre-push hook: typecheck + biome + lint-log-tags
 set -euo pipefail
-echo "🔍 pre-push: running checks..."
+
+echo "🔍 Running check (tsc + biome + lint-log-tags)..."
 bun run check
-echo "✅ pre-push: all checks passed"
+
+echo "🧪 Running tests..."
+bun run test
+
+echo "✅ All checks passed!"

.gitignore

@@ -6,3 +6,8 @@ tsconfig.tsbuildinfo
 .npmrc
 
 bunfig.toml
+xiaoju/
+solve-issue-entry.ts
+packages/workflow-template-develop/develop.esm.js
+.DS_Store
+*.py

biome.json

@@ -1,7 +1,13 @@
 {
   "$schema": "https://biomejs.dev/schemas/2.4.15/schema.json",
   "files": {
-    "includes": ["**", "!**/dist", "!**/node_modules", "!packages/workflow/workflow"]
+    "includes": [
+      "**",
+      "!**/dist",
+      "!**/node_modules",
+      "!packages/workflow/workflow",
+      "!xiaoju/scripts/bundle.ts"
+    ]
   },
   "assist": { "actions": { "source": { "organizeImports": "on" } } },
   "formatter": {

develop-entry.ts

@@ -1,15 +0,0 @@
-import { createCursorAgent } from "./packages/workflow-agent-cursor/src/index.js";
-import { createWorkflow } from "./packages/workflow-runtime/src/create-workflow.js";
-import {
-  buildDevelopDescriptor,
-  developWorkflowDefinition,
-} from "./packages/workflow-template-develop/src/index.js";
-
-const agent = createCursorAgent({
-  command: "/home/azureuser/.local/bin/cursor-agent",
-  model: "auto",
-  timeout: 300_000,
-});
-
-export const descriptor = buildDevelopDescriptor();
-export const run = createWorkflow(developWorkflowDefinition, { adapter: agent, overrides: null });

docs/architecture.md

@@ -8,7 +8,7 @@
 
 A workflow engine that executes single-file ESM bundles. Each workflow is a self-contained `.esm.js` file identified by its XXH64 hash (Crockford Base32). No daemon — processes start on demand and exit when done.
 
-The implementation lives in **15** Bun workspace packages under `packages/`, using the `workspace:*` protocol.
+The implementation lives in **21** Bun workspace packages under `packages/`, using the `workspace:*` protocol.
 
 ## Package map
 
@@ -26,10 +26,13 @@ Grouped by responsibility (npm name → folder).
 | CLI | `@uncaged/cli-workflow` → `cli-workflow` | `uncaged-workflow` binary (depends on engine, registry, CAS, protocol, util, runtime). |
 | Agent adapters | `@uncaged/workflow-agent-cursor` → `workflow-agent-cursor` | `AgentFn` via `cursor-agent` CLI + workspace extraction. |
 | | `@uncaged/workflow-agent-hermes` → `workflow-agent-hermes` | `AgentFn` via `hermes chat` CLI. |
+| | `@uncaged/workflow-agent-office` → `workflow-agent-office` | `AdapterFn` via `office-agent` CLI; generates or edits Word documents, stores outputs per threadId. |
+| | `@uncaged/workflow-agent-docx-diff` → `workflow-agent-docx-diff` | `AdapterFn` via `docx-diff` CLI; produces Word-format diff reports for document edit workflows. |
 | | `@uncaged/workflow-agent-llm` → `workflow-agent-llm` | `AgentFn` via OpenAI-compatible HTTP (`LlmProvider` from runtime). |
 | Agent shared | `@uncaged/workflow-util-agent` → `workflow-util-agent` | `buildAgentPrompt`, `spawnCli` for CLI-backed agents. |
 | Templates | `@uncaged/workflow-template-develop` → `workflow-template-develop` | Develop workflow definition, roles, descriptor builder. |
 | | `@uncaged/workflow-template-solve-issue` → `workflow-template-solve-issue` | Solve-issue workflow definition, roles, descriptor builder. |
+| | `@uncaged/workflow-template-document` → `workflow-template-document` | Document generation/editing workflow definition (writer + differ roles, moderator table, descriptor). |
 | Dashboard | `@uncaged/workflow-dashboard` → `workflow-dashboard` | Private Vite + React app (`src/main.tsx`); only `react` / `react-dom` dependencies — no workspace packages. |
 
 ## Dependency graph (workspace packages)
@@ -265,4 +268,4 @@ Tags are 8-char Crockford Base32 (40-bit random), one per call site. `grep "4KNM
 | **Single-file ESM** | Hash = version, self-contained bundle |
 | **No daemon** | OS handles process lifecycle |
 | **Crockford Base32** | Filesystem-safe, readable, compact |
-| **15-package split** | Clear boundaries: protocol ↔ runtime author API ↔ util/CAS/register ↔ execute ↔ CLI ↔ agents/templates/UI |
+| **21-package split** | Clear boundaries: protocol ↔ runtime author API ↔ util/CAS/register ↔ execute ↔ CLI ↔ agents/templates/UI |

docs/superpowers/specs/2026-05-18-office-agent-document-template.md

@@ -0,0 +1,387 @@
+# 设计文档：office-agent 文档生成/编辑 Workflow 体系
+
+**日期：** 2026-05-18
+
+---
+
+## 概述
+
+在 monorepo 中新增三个包，实现通过 `office-agent` CLI 生成或编辑 Word 文档的完整 workflow 体系。
+
+| 包 | npm name | 职责 |
+|---|---|---|
+| `workflow-template-document` | `@uncaged/workflow-template-document` | 纯结构：角色定义、meta schema、调度表、descriptor |
+| `workflow-agent-office` | `@uncaged/workflow-agent-office` | writer 角色执行器：调用 `office-agent` CLI |
+| `workflow-agent-docx-diff` | `@uncaged/workflow-agent-docx-diff` | differ 角色执行器：调用 `docx-diff` CLI |
+
+Template 只定义结构，不含执行逻辑。执行器与 template 解耦。
+
+---
+
+## 一、`workflow-template-document`
+
+### Thread 启动输入
+
+```typescript
+// src/types.ts
+type DocumentStartInput = {
+  prompt: string;           // 用户指令
+  inputDocx: string | null; // null = 生成模式；本机绝对路径 = 编辑模式
+};
+```
+
+start.content 为 JSON `{ prompt, inputDocx }` 或纯文本（fallback：generate 模式，整段作为 prompt）。
+
+### 角色与 Meta
+
+`WriterMeta` 使用 discriminated union，在 schema 层区分两种模式：
+
+```typescript
+const writerMetaSchema = z.discriminatedUnion("mode", [
+  z.object({
+    mode: z.literal("generate"),
+    outputDocx: z.string(),   // 生成产物绝对路径
+    sourceDocx: z.null(),
+  }),
+  z.object({
+    mode: z.literal("edit"),
+    outputDocx: z.string(),   // 修改后产物：<outputDir>/modified.docx
+    sourceDocx: z.string(),   // 原始副本：<outputDir>/original.docx
+  }),
+]);
+type WriterMeta = z.infer<typeof writerMetaSchema>;
+
+// differ：仅编辑模式执行
+const differMetaSchema = z.object({
+  sourceDocx: z.string(),
+  modifiedDocx: z.string(),
+  diffDocx: z.string(),
+});
+type DifferMeta = z.infer<typeof differMetaSchema>;
+```
+
+两个角色的 `systemPrompt` 均为 `""`。
+
+### 调度表
+
+```
+START → writer ──(mode = "edit")──→ differ → END
+               ↘(mode = "generate")→ END
+```
+
+### 公开导出
+
+template 导出两个对象供消费方使用：
+
+- `documentWorkflowDefinition: WorkflowDefinition<DocumentMeta>` — 传入 `createWorkflow` 的 `def` 参数
+- `buildDocumentDescriptor(): WorkflowDescriptor` — bundle 导出用
+
+```typescript
+// bundle 侧用法
+export const descriptor = buildDocumentDescriptor();
+export const run = createWorkflow(documentWorkflowDefinition, { adapter, overrides });
+```
+
+### 包文件结构
+
+```
+packages/workflow-template-document/
+  src/
+    types.ts           # DocumentStartInput
+    roles/
+      writer.ts        # writerMetaSchema, WriterMeta, writerRole
+      differ.ts        # differMetaSchema, DifferMeta, differRole
+      index.ts
+    roles.ts           # DocumentMeta, documentRoles
+    moderator.ts       # writerIsEditMode condition + documentTable
+    definition.ts      # documentWorkflowDefinition
+    descriptor.ts      # buildDocumentDescriptor()
+    index.ts
+  __tests__/
+    moderator.test.ts
+  package.json
+  tsconfig.json
+```
+
+### 依赖
+
+```json
+{
+  "@uncaged/workflow-protocol": "workspace:^",
+  "@uncaged/workflow-runtime": "workspace:^",
+  "@uncaged/workflow-register": "workspace:^",
+  "zod": "^4.0.0"
+}
+```
+
+---
+
+## 二、`workflow-agent-office`
+
+### office-agent CLI 接口
+
+```bash
+# 生成模式：在 CWD 生成 output.docx
+office-agent create "<prompt>" -o output.docx
+
+# 编辑模式：在 CWD 对 modified.docx 进行修改（覆写）
+office-agent edit modified.docx "<instruction>"
+```
+
+- 两个命令均为阻塞调用（CLI 内部消费 SSE，退出即完成）
+- 输出文件落到调用方设定的 CWD
+- 退出码 0 = 成功，非零 = 失败
+
+### 文件命名约定
+
+| 模式 | 文件 | 路径 |
+|---|---|---|
+| generate | 输出 | `<outputDir>/output.docx` |
+| edit | 原始副本（workflow-owned 快照） | `<outputDir>/original.docx` |
+| edit | 修改后产物 | `<outputDir>/modified.docx` |
+
+edit 模式先将 `inputDocx` 复制为 `original.docx`（不可变快照），再复制为 `modified.docx`，对 `modified.docx` 调用 CLI。agent 覆写 `modified.docx`，`original.docx` 保持不变。differ 对比这两个 workflow-owned 文件，不依赖用户原始路径。
+
+### 执行流程
+
+**生成模式（`inputDocx = null`）：**
+1. `mkdir -p <outputDir>`（`<config.outputDir>/<ctx.threadId>`）
+2. `const command = config.command ?? "office-agent"`
+3. `spawnCli(command, ["create", prompt, "-o", "output.docx"], { cwd: outputDir, timeoutMs })`
+4. 验证 `outputDir/output.docx` 存在
+5. 返回 `JSON.stringify({ mode: "generate", outputDocx, sourceDocx: null })`
+
+**编辑模式（`inputDocx ≠ null`）：**
+1. `mkdir -p <outputDir>`
+2. `copyFile(inputDocx, <outputDir>/original.docx)`
+3. `copyFile(inputDocx, <outputDir>/modified.docx)`
+4. `const command = config.command ?? "office-agent"`
+5. `spawnCli(command, ["edit", "modified.docx", prompt], { cwd: outputDir, timeoutMs })`
+6. 验证 `outputDir/modified.docx` 存在
+7. 返回 `JSON.stringify({ mode: "edit", outputDocx: modifiedPath, sourceDocx: originalPath })`
+
+### AdapterFn 实现（直接实现，不经过 runtime.extract）
+
+CLI 产出确定性 JSON，直接 `schema.parse(JSON.parse(raw))` 跳过 LLM extraction：
+
+```typescript
+export function createOfficeAgent(config: OfficeAgentConfig): AdapterFn {
+  return <T>(_systemPrompt: string, schema: z.ZodType<T>) =>
+    async (ctx: ThreadContext, _runtime: WorkflowRuntime): Promise<RoleResult<T>> => {
+      const { prompt, inputDocx } = parseStartInput(ctx.start.content);
+      const raw = await runOfficeAgent(config, ctx.threadId, prompt, inputDocx);
+      const meta = schema.parse(JSON.parse(raw)) as T;
+      return { meta, childThread: null };
+    };
+}
+```
+
+`_systemPrompt` 为 writer 角色的 systemPrompt（空字符串），实际指令从 `ctx.start.content` 解析。
+
+### 配置
+
+```typescript
+type OfficeAgentConfig = {
+  outputDir: string;        // 输出根目录，runner 在此下按 threadId 建子目录
+  command: string | null;   // null → runner 内 resolve 为 "office-agent"
+  timeout: number | null;   // null → 不设超时；单位 ms
+};
+```
+
+### 错误处理
+
+```typescript
+if (!result.ok) {
+  const e = result.error;
+  if (e.kind === "non_zero_exit")
+    throw new Error(`office-agent failed (exit ${e.exitCode}): ${e.stderr}`);
+  if (e.kind === "timeout")
+    throw new Error("office-agent: timed out");
+  // "spawn_failed"
+  throw new Error(`office-agent: spawn failed: ${e.message}`);
+}
+if (!existsSync(expectedPath))
+  throw new Error(`office-agent: output file not found: ${expectedPath}`);
+```
+
+### packageDescriptor
+
+```typescript
+// src/package-descriptor.ts
+export const packageDescriptor: PackageDescriptor = {
+  name: "@uncaged/workflow-agent-office",
+  version: "0.1.0",
+  capabilities: ["office-agent-cli", "docx-generate", "docx-edit"],
+  configSchema: {
+    type: "object",
+    required: ["outputDir"],
+    properties: {
+      outputDir: { type: "string", description: "Root directory for workflow outputs." },
+      command:   { anyOf: [{ type: "string" }, { type: "null" }], description: "Path to office-agent CLI; null uses PATH." },
+      timeout:   { anyOf: [{ type: "number" }, { type: "null" }], description: "Timeout in ms; null means no limit." },
+    },
+    additionalProperties: false,
+  },
+};
+```
+
+### 包文件结构
+
+```
+packages/workflow-agent-office/
+  src/
+    types.ts                # OfficeAgentConfig, OfficeAgentOpt
+    runner.ts               # runOfficeAgent()（spawnCli 封装 + 文件验证）
+    agent.ts                # createOfficeAgent(): AdapterFn
+    package-descriptor.ts   # packageDescriptor
+    index.ts
+  __tests__/
+    runner.test.ts
+    agent.test.ts
+  package.json
+  tsconfig.json
+```
+
+### 依赖
+
+```json
+{
+  "@uncaged/workflow-protocol": "workspace:^",
+  "@uncaged/workflow-util": "workspace:^",
+  "@uncaged/workflow-util-agent": "workspace:^"
+}
+```
+
+---
+
+## 三、`workflow-agent-docx-diff`
+
+`differ` 角色专用执行器。从 `ctx.steps` 读取 `WriterMeta`，调用本地 `docx-diff` CLI。
+
+### docx-diff 退出码约定
+
+| 退出码 | 含义 | runner 处理 |
+|---|---|---|
+| 0 | 无差异 | 正常，验证 diffDocx 存在 |
+| 1 | 有差异 | 正常（显式处理为成功），验证 diffDocx 存在 |
+| 2+ | 错误 | throw |
+
+runner 收到 `SpawnCliError { kind: "non_zero_exit", exitCode: 1 }` 时视为成功，验证文件后继续；`exitCode >= 2` 才 throw。
+
+### 执行流程
+
+```
+1. 从 ctx.steps 找到 writer 步骤，读取 WriterMeta
+2. 验证 mode === "edit"（否则 throw）
+3. diffDocx = join(dirname(writer.outputDocx), "diff.docx")
+4. const command = config.command ?? "docx-diff"
+5. spawnCli(command,
+     [writer.sourceDocx, writer.outputDocx, "--output", "docx", "--out-file", diffDocx],
+     { cwd: null, timeoutMs: null })
+   exit 0 或 1 → 验证 diffDocx 存在
+   exit 2+ → throw
+6. 返回 JSON.stringify({ sourceDocx, modifiedDocx: writer.outputDocx, diffDocx })
+```
+
+### AdapterFn 实现（直接实现，不经过 runtime.extract）
+
+```typescript
+export function createDocxDiffAgent(config: DocxDiffAgentConfig = { command: null }): AdapterFn {
+  return <T>(_prompt: string, schema: z.ZodType<T>) =>
+    async (ctx: ThreadContext, _runtime: WorkflowRuntime): Promise<RoleResult<T>> => {
+      const writerStep = ctx.steps.find(s => s.role === "writer");
+      if (!writerStep) throw new Error("differ: no writer step found");
+      const writerMeta = writerStep.meta as WriterMeta;
+      if (writerMeta.mode !== "edit")
+        throw new Error("differ: writer did not run in edit mode");
+      const raw = await runDocxDiff(config, writerMeta);
+      const meta = schema.parse(JSON.parse(raw)) as T;
+      return { meta, childThread: null };
+    };
+}
+```
+
+### 配置
+
+```typescript
+type DocxDiffAgentConfig = {
+  command: string | null;   // null → runner 内 resolve 为 "docx-diff"
+};
+```
+
+### packageDescriptor
+
+```typescript
+export const packageDescriptor: PackageDescriptor = {
+  name: "@uncaged/workflow-agent-docx-diff",
+  version: "0.1.0",
+  capabilities: ["docx-diff-cli", "docx-diff-report"],
+  configSchema: {
+    type: "object",
+    properties: {
+      command: { anyOf: [{ type: "string" }, { type: "null" }], description: "Path to docx-diff CLI; null uses PATH." },
+    },
+    additionalProperties: false,
+  },
+};
+```
+
+### 包文件结构
+
+```
+packages/workflow-agent-docx-diff/
+  src/
+    types.ts                # DocxDiffAgentConfig
+    runner.ts               # runDocxDiff()（exit 1 处理 + 文件验证）
+    agent.ts                # createDocxDiffAgent(): AdapterFn
+    package-descriptor.ts   # packageDescriptor
+    index.ts
+  __tests__/
+    runner.test.ts
+    agent.test.ts
+  package.json
+  tsconfig.json
+```
+
+### 依赖
+
+```json
+{
+  "@uncaged/workflow-protocol": "workspace:^",
+  "@uncaged/workflow-util-agent": "workspace:^",
+  "@uncaged/workflow-template-document": "workspace:^"
+}
+```
+
+---
+
+## 四、外部 bundle（外部 workspace 消费）
+
+```typescript
+import { createOfficeAgent } from "@uncaged/workflow-agent-office";
+import { createDocxDiffAgent } from "@uncaged/workflow-agent-docx-diff";
+import {
+  buildDocumentDescriptor,
+  documentWorkflowDefinition,
+} from "@uncaged/workflow-template-document";
+import { createWorkflow } from "@uncaged/workflow-runtime";
+import { getDefaultWorkflowStorageRoot } from "@uncaged/workflow-util";
+import { join } from "node:path";
+
+const outputDir = join(getDefaultWorkflowStorageRoot(), "outputs");
+
+export const descriptor = buildDocumentDescriptor();
+export const run = createWorkflow(documentWorkflowDefinition, {
+  adapter: createOfficeAgent({ outputDir, command: null, timeout: null }),
+  overrides: { differ: createDocxDiffAgent() },
+});
+```
+
+---
+
+## 不在范围内
+
+- 重试逻辑（失败直接 throw）
+- office-agent server 的启停管理（假设 server 已在运行）
+- docx-diff HTML/terminal 格式输出（仅 docx）
+- 跨机器执行（`inputDocx` 须为本机有效绝对路径）

docs/wf-stateless-design.md

@@ -0,0 +1,527 @@
+# `uwf` — Stateless Workflow CLI
+
+> 将 workflow 引擎降维为无状态单步 CLI。Workflow 是纯数据（CAS 节点），执行是单步原子操作，agent 是可插拔外部命令。
+
+---
+
+## 1. CLI Design
+
+### 1.1 命令总览
+
+```
+# thread 组
+uwf thread start <workflow> -p <prompt>     # 创建 thread，不执行
+uwf thread step  <thread-id> [--agent]      # 单步执行
+uwf thread show  <thread-id>                # thread-id → head 查询
+uwf thread list  [--all]                    # 列出活跃 threads（--all 含已归档）
+uwf thread kill  <thread-id>                # 终结 thread，归档
+
+# workflow 组
+uwf workflow put   <file.yaml>              # 注册 workflow（YAML → CAS）
+uwf workflow show  <workflow-id>            # 查看 workflow 定义
+uwf workflow list                           # 列出已注册 workflows
+```
+
+两组对称，各 3-4 个子命令。CAS 操作交给 `json-cas` CLI，不在 `uwf` 中重复。
+
+### 1.2 `uwf thread start`
+
+```bash
+uwf thread start <workflow> -p "Fix the login bug described in issue #42"
+```
+
+- `<workflow>` — workflow 名或 CAS hash
+- `-p` — 用户 prompt（必填）
+
+**输出（JSON to stdout）：**
+
+```jsonc
+{
+  "workflow": "4KNM2PXR3B1QW",   // workflow CAS hash (XXH64, 13-char Crockford Base32)
+  "thread": "01J7K9M2XNPQR5VWBCDF8G3H4T"      // ULID
+}
+```
+
+**做的事：**
+1. 解析 workflow（名字查 registry → CAS hash）
+2. 生成 thread ULID
+3. 写 StartNode 到 CAS
+4. 在 threads.yaml 中记录链头 → StartNode hash
+5. 输出 JSON
+
+### 1.3 `uwf thread step`
+
+```bash
+uwf thread step 01J7K9M2XNPQR5VWBCDF8G3H4T
+uwf thread step 01J7K9M2XNPQR5VWBCDF8G3H4T --agent "bunx uwf-cursor"
+```
+
+**输出（JSON to stdout）：**
+
+```jsonc
+{
+  "workflow": "4KNM2PXR3B1QW",
+  "thread": "01J7K9M2XNPQR5VWBCDF8G3H4T",
+  "head": "8FWKR3TN5V1QA",       // 新链头 StepNode 的 CAS hash
+  "done": false                    // true = moderator 返回 END，thread 已归档
+}
+```
+
+`done: true` 时 head 仍然有值（最后一个 StepNode），但 thread 已从 threads.yaml 移除。
+对已结束或不存在的 thread 调用 step 会报错（非 active thread）。
+
+详细信息通过 `uwf thread show <thread-id>` 或 `json-cas get <head>` 查看。
+
+**做的事：**
+1. 读链头 → 当前 StepNode（或 StartNode）
+2. 收集 thread 历史（遍历链）
+3. 调 moderator：评估 JSONata conditions → 得到下一个 role（或 END）
+4. 若 END → 归档 thread，输出最后链头，退出
+5. 确定 agent command（`--agent` override > config.yaml per-workflow/role > config.yaml defaultAgent）
+6. 调用：`<agent-cmd> <thread-id> <role>`，捕获 stdout 得到新 StepNode hash
+7. 更新链头指针
+8. 再次调 moderator（基于新 StepNode）判断 done
+9. 输出 JSON
+
+### 1.4 `uwf thread show`
+
+```bash
+uwf thread show 01J7K9M2XNPQR5VWBCDF8G3H4T
+```
+
+**输出（JSON to stdout）：**
+
+```jsonc
+{
+  "workflow": "4KNM2PXR3B1QW",
+  "thread": "01J7K9M2XNPQR5VWBCDF8G3H4T",
+  "head": "8FWKR3TN5V1QA",
+  "done": false
+}
+```
+
+纯 thread-id → head 查询。详细内容用 `json-cas get <head>` 或 `json-cas walk <head>` 查看。
+
+### 1.5 Agent CLI 协议
+
+每个 agent 是一个命令，接受 thread-id 和 role 两个参数：
+
+```bash
+uwf-hermes <thread-id> <role>
+```
+
+**约定：**
+- `uwf step` 负责 moderator 决策，将 role 传给 agent CLI
+- agent-kit 根据 thread + role 从 CAS 读 systemPrompt / outputSchema
+- agent-kit 组装完整 prompt（role systemPrompt + thread context + user prompt from StartNode）
+- agent 执行实际逻辑，agent-kit 负责 extract
+- agent 将 StepNode 写入 CAS（含 output、detail、agent、prev），但**不挪链头指针**
+- stdout 输出新 StepNode 的 CAS hash（纯文本，一行）
+- 所有配置从环境变量读（LLM model、API key、extractor config）
+- exit 0 = 成功，非 0 = 失败
+
+**stdout 输出：**
+
+```
+8FWKR3TN5V1QA
+```
+
+`uwf step` 拿到这个 hash 后更新链头指针、判断 done。
+
+---
+
+## 2. CAS 结构定义
+
+### 2.1 类型层级
+
+沿用 json-cas 的三层：bootstrap meta-schema → JSON Schema nodes → data nodes。
+
+下面所有 CAS 节点都遵循 `{ type: cas_ref, payload: T, timestamp: number }` 的标准格式。
+`cas_ref` 类型的字符串字段在 json-cas 中已内置支持，不需要额外的 `$ref` 包装。
+
+### 2.2 数据节点
+
+#### `Workflow`
+
+Roles 和 moderator 内联在 Workflow 中，只有 outputSchema 独立为 CAS 节点（方便 json-cas 校验）。
+
+```yaml
+type: <workflow-schema-hash>
+payload:
+  name: "solve-issue"
+  description: "End-to-end issue resolution"
+  roles:
+    planner:
+      description: "Creates implementation plan"
+      systemPrompt: "You are a planning agent..."
+      outputSchema: "5GWKR8TN1V3JA"    # cas_ref → JSON Schema 节点（json-cas 内置）
+    developer:
+      description: "Implements code changes"
+      systemPrompt: "You are a developer agent..."
+      outputSchema: "8CNWT4KR6D1HV"    # cas_ref → JSON Schema 节点
+    reviewer:
+      description: "Reviews code changes"
+      systemPrompt: "You are a code reviewer..."
+      outputSchema: "1VPBG9SM5E7WK"    # cas_ref → JSON Schema 节点
+  conditions:
+    needsClarification:
+      description: "Planner requests clarification from user"
+      expression: "$exists(steps[-1].output.needsClarification)"
+    notApproved:
+      description: "Reviewer rejected the implementation"
+      expression: "steps[-1].output.approved = false"
+  graph:
+    $START:
+      - role: "planner"
+        condition: null                  # 无条件（fallback）
+    planner:
+      - role: "developer"
+        condition: "needsClarification"
+      - role: "$END"
+        condition: null
+    developer:
+      - role: "reviewer"
+        condition: null
+    reviewer:
+      - role: "developer"
+        condition: "notApproved"
+      - role: "$END"
+        condition: null
+```
+
+- `roles` — 内联定义，每个 role 的 `outputSchema` 是独立的 cas_ref（指向 json-cas 内置 JSON Schema 节点）
+- `conditions` — `Record<Name, JSONata>`，命名条件，方便画图描述
+- `graph` — `Record<Role | "$START", Transition[]>`，每个 Transition = `{ role, condition }`
+- `condition` 引用 conditions 中的 key，`null` = fallback
+- 按数组顺序求值，第一个匹配的 transition 胜出
+- 不含 agent binding — agent 配置在 `~/.uncaged/workflow/config.yaml` 中管理
+
+JSONata 表达式的求值上下文：
+
+```jsonc
+{
+  "start": {                          // StartNode 信息
+    "workflow": "4KNM2PXR3B1QW",
+    "prompt": "Fix the login bug..."
+  },
+  "steps": [                          // 所有已完成 steps，从旧到新
+    { "role": "planner", "output": { "phases": [...] }, "detail": "7BQST3VW9F2MA", "agent": "uwf-hermes" },
+    { "role": "developer", "output": { "filesChanged": ["src/auth.ts"], "summary": "Fixed redirect" }, "detail": "9KRVW3TN5F1QA", "agent": "uwf-cursor" },
+    { "role": "reviewer", "output": { "approved": false }, "detail": "2MXBG6PN4A8JR", "agent": "uwf-hermes" }
+  ]
+}
+```
+
+注：`output` 在上下文中会被自动展开为实际的 CAS 节点内容（而非 hash），方便 JSONata 表达式直接访问字段。
+
+#### `StartNode`（Thread 起点）
+
+```yaml
+type: <start-node-schema-hash>
+payload:
+  workflow: "4KNM2PXR3B1QW"        # cas_ref → Workflow
+  prompt: "Fix the login bug..."
+```
+
+- 没有 thread-id — thread-id 是索引层面的事，不进 CAS 内容
+- 没有 agent binding — 运行时从 config.yaml 解析
+
+#### `StepNode`（Thread 每一步）
+
+```yaml
+type: <step-node-schema-hash>
+payload:
+  start: "4TNVW8KR2B3MA"          # cas_ref → StartNode（每个 step 都引用）
+  prev: "2MXBG6PN4A8JR"           # cas_ref → 前一个 StepNode，第一步为 null
+  role: "developer"
+  output: "9KRVW3TN5F1QA"         # cas_ref → 结构化输出节点（符合 role 的 outputSchema）
+  detail: "7BQST3VW9F2MA"         # cas_ref → 执行详情（content node / 子 workflow terminal StepNode / ...）
+  agent: "uwf-cursor"              # 实际使用的 agent 命令（纯字符串）
+```
+
+- `start` — 每个 StepNode 都直接引用 StartNode，方便随机访问
+- `prev` — 前一个 StepNode 的 cas_ref，第一步为 `null`（不指向 StartNode）
+- `output` — cas_ref，指向符合 role outputSchema 的 CAS 节点，可用 json-cas 校验
+- `detail` — cas_ref，指向执行详情。可以是原始 agent 输出（content node），也可以是子 workflow thread 的 terminal StepNode（workflowAsAgent 场景）
+- `agent` — 纯字符串，不是 CAS 节点
+
+### 2.3 链式结构
+
+```
+threads.yaml: { "01J7K9M2XNPQR5VWBCDF8G3H4T": "8FWKR3TN5V1QA" }
+                                      │
+                                      ▼
+                              StepNode (step 3)
+                              ├── start ──→ StartNode
+                              │              ├── workflow → CAS(Workflow)
+                              │              └── prompt: "Fix..."
+                              ├── prev ──→ StepNode (step 2)
+                              │             ├── start ──→ (same StartNode)
+                              │             ├── prev ──→ StepNode (step 1)
+                              │             │             ├── start ──→ (same StartNode)
+                              │             │             ├── prev: null
+                              │             │             ├── role: "planner"
+                              │             │             └── ...
+                              │             ├── role: "developer"
+                              │             └── ...
+                              ├── role: "reviewer"
+                              ├── output → CAS({ approved: true })
+                              ├── detail → CAS(raw output | sub-workflow terminal node)
+                              └── agent: "uwf-hermes"
+```
+
+### 2.4 可变状态
+
+系统两个顶层 YAML 文件和一个 env 文件：
+
+```yaml
+# ~/.uncaged/workflow/config.yaml — 全局配置
+providers:
+  openai:
+    baseUrl: "https://api.openai.com/v1"
+    apiKeyEnv: "OPENAI_API_KEY"
+  anthropic:
+    baseUrl: "https://api.anthropic.com/v1"
+    apiKeyEnv: "ANTHROPIC_API_KEY"
+  openrouter:
+    baseUrl: "https://openrouter.ai/api/v1"
+    apiKeyEnv: "OPENROUTER_API_KEY"
+
+models:
+  sonnet:
+    provider: "openrouter"
+    name: "anthropic/claude-sonnet-4"
+  gpt4o-mini:
+    provider: "openai"
+    name: "gpt-4o-mini"
+
+agents:
+  hermes:
+    command: "uwf-hermes"
+    args: []
+  cursor:
+    command: "uwf-cursor"
+    args: []
+
+defaultAgent: "hermes"
+agentOverrides:
+  solve-issue:
+    developer: "cursor"
+
+defaultModel: "sonnet"
+modelOverrides:
+  extract: "gpt4o-mini"
+```
+
+```yaml
+# ~/.uncaged/workflow/threads.yaml — active thread 链头指针
+01J7K9M2XNPQR5VWBCDF8G3H4T: "8FWKR3TN5V1QA"
+01J8AB3QRMSTV6WKXZ2C4DF7GN: "3CNWT9KR6D2HV"
+```
+
+Thread 结束时从 threads.yaml 移除。可选：追加到 `history.jsonl` 做归档。
+
+```bash
+# ~/.uncaged/workflow/.env — 敏感信息（API keys）
+OPENAI_API_KEY=sk-...
+ANTHROPIC_API_KEY=sk-ant-...
+OPENROUTER_API_KEY=sk-or-...
+```
+
+- `config.yaml` — 非敏感配置（agent 命令、model 名、provider 名）
+- `.env` — 敏感信息（API keys），agent-kit 启动时自动加载
+- `threads.yaml` — 运行时状态
+
+---
+
+## 3. 包结构
+
+全新包，不复用现有 packages，避免命名冲突。CAS 直接依赖 `@uncaged/json-cas`。
+
+```
+packages/
+├── cli-uwf/              # @uncaged/cli-uwf — uwf CLI（thread/workflow 命令）
+├── uwf-moderator/        # @uncaged/uwf-moderator — JSONata moderator 引擎
+├── uwf-agent-kit/        # @uncaged/uwf-agent-kit — Agent CLI 框架（含 extractor）
+├── uwf-agent-hermes/     # @uncaged/uwf-agent-hermes — uwf-hermes CLI
+├── uwf-agent-cursor/     # @uncaged/uwf-agent-cursor — uwf-cursor CLI
+└── uwf-protocol/         # @uncaged/uwf-protocol — 共享类型定义
+```
+
+**外部依赖：**
+- `@uncaged/json-cas` — CAS 存储、hash、schema 校验
+- `@uncaged/json-cas-fs` — 文件系统 CAS 后端
+
+**现有包全部保留不动**，新旧并存，逐步迁移。
+
+---
+
+## 4. 关键数据类型
+
+JSONata 求值上下文本质上是 thread 链表的线性化表达。StepNode payload 和上下文中的 step 共享大量字段，提取为公共类型。
+
+### 4.1 公共类型
+
+```typescript
+/** CAS hash — XXH64, 13-char Crockford Base32 */
+type CasRef = string;
+
+/** Thread ID — ULID, 26-char Crockford Base32 */
+type ThreadId = string;
+
+/** 一个 step 的核心数据，被 StepNode payload 和 JSONata 上下文共享 */
+type StepRecord = {
+  role: string;
+  output: CasRef;                    // cas_ref → 结构化输出节点（符合 role outputSchema）
+  detail: CasRef;                    // cas_ref → 执行详情（content node / 子 workflow terminal StepNode）
+  agent: string;                     // 实际使用的 agent 命令（纯字符串）
+};
+```
+
+### 4.2 Workflow 定义
+
+```typescript
+type RoleDefinition = {
+  description: string;
+  systemPrompt: string;
+  outputSchema: CasRef;              // cas_ref → json-cas 内置 JSON Schema 节点
+};
+
+type Transition = {
+  role: string;                      // 目标 role 名 或 "$END"
+  condition: string | null;          // 引用 conditions 中的 key，null = fallback
+};
+
+type ConditionDefinition = {
+  description: string;
+  expression: string;                           // JSONata expression
+};
+
+type WorkflowPayload = {
+  name: string;
+  description: string;
+  roles: Record<string, RoleDefinition>;
+  conditions: Record<string, ConditionDefinition>;
+  graph: Record<string, Transition[]>;          // Record<Role | "$START", Transition[]>
+};
+```
+
+### 4.3 Thread 节点
+
+```typescript
+type StartNodePayload = {
+  workflow: CasRef;                  // cas_ref → Workflow
+  prompt: string;
+};
+
+type StepNodePayload = StepRecord & {
+  start: CasRef;                     // cas_ref → StartNode（每个 step 都引用）
+  prev: CasRef | null;               // cas_ref → 前一个 StepNode，第一步为 null
+};
+```
+
+### 4.4 JSONata 求值上下文
+
+Thread 链表的线性化。`steps[n]` 的字段和 `StepRecord` 一致，但 `output` 被展开为实际内容。
+
+```typescript
+/** JSONata 上下文中的 step — output 被展开 */
+type StepContext = Omit<StepRecord, "output"> & {
+  output: unknown;                   // 展开后的 CAS 节点内容，非 hash
+};
+
+type ModeratorContext = {
+  start: StartNodePayload;
+  steps: StepContext[];              // 从旧到新
+};
+```
+
+### 4.5 CLI 输出
+
+```typescript
+/** uwf thread start */
+type StartOutput = {
+  workflow: CasRef;
+  thread: ThreadId;
+};
+
+/** uwf thread step / uwf thread show */
+type StepOutput = {
+  workflow: CasRef;
+  thread: ThreadId;
+  head: CasRef;
+  done: boolean;
+};
+
+/** uwf thread list */
+type ThreadListItem = {
+  thread: ThreadId;
+  workflow: CasRef;
+  head: CasRef;
+};
+```
+
+### 4.6 配置
+
+```typescript
+/** Alias types for config references */
+type AgentAlias = string;
+type ModelAlias = string;
+type ProviderAlias = string;
+type WorkflowName = string;
+type RoleName = string;
+type Scenario = string;              // e.g. "extract"
+
+type ProviderConfig = {
+  baseUrl: string;
+  apiKeyEnv: string;                 // env var name to read API key from
+};
+
+type ModelConfig = {
+  provider: ProviderAlias;
+  name: string;                      // e.g. "anthropic/claude-sonnet-4", "gpt-4o-mini"
+};
+
+type AgentConfig = {
+  command: string;
+  args: string[];
+};
+
+/** ~/.uncaged/workflow/config.yaml */
+type WorkflowConfig = {
+  providers: Record<ProviderAlias, ProviderConfig>;
+  models: Record<ModelAlias, ModelConfig>;
+  agents: Record<AgentAlias, AgentConfig>;
+  defaultAgent: AgentAlias;
+  agentOverrides: Record<WorkflowName, Record<RoleName, AgentAlias>> | null;
+  defaultModel: ModelAlias;
+  modelOverrides: Record<Scenario, ModelAlias> | null;
+};
+
+/** ~/.uncaged/workflow/threads.yaml */
+type ThreadsIndex = Record<ThreadId, CasRef>;
+//                         ^ thread-id  ^ head StepNode/StartNode hash
+```
+
+### 4.7 类型关系图
+
+```
+WorkflowConfig (config.yaml)
+ThreadsIndex (threads.yaml)          ← 唯二可变状态
+    │
+    │ thread-id → head hash
+    ▼
+StepNodePayload ──extends──→ StepRecord ←──maps to──→ StepContext
+    │                           │                          │
+    ├── start → StartNodePayload│                          │ (output 展开)
+    ├── prev → StepNodePayload  │                          │
+    │                           ├── role                   ├── role
+    │                           ├── output (CasRef)        ├── output (展开)
+    │                           ├── detail (CasRef)        ├── detail (CasRef)
+    │                           └── agent (string)         └── agent (string)
+    │
+    └── start.workflow → WorkflowPayload
+                             ├── roles: Record<name, RoleDefinition>
+                             ├── conditions: Record<name, JSONata>
+                             └── graph: Record<role, Transition[]>
+```

packages/cli-uwf/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@uncaged/cli-uwf",
+  "version": "0.1.0",
+  "files": [
+    "src",
+    "dist",
+    "package.json"
+  ],
+  "type": "module",
+  "bin": {
+    "uwf": "./src/cli.ts"
+  },
+  "dependencies": {
+    "@uncaged/json-cas": "^0.3.0",
+    "@uncaged/json-cas-fs": "^0.3.0",
+    "@uncaged/uwf-agent-kit": "workspace:^",
+    "@uncaged/uwf-moderator": "workspace:^",
+    "@uncaged/uwf-protocol": "workspace:^",
+    "@uncaged/workflow-util": "workspace:^",
+    "commander": "^14.0.3",
+    "dotenv": "^16.6.1",
+    "yaml": "^2.8.4"
+  },
+  "scripts": {
+    "test": "bun test"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

packages/cli-uwf/src/cli.ts

@@ -0,0 +1,331 @@
+#!/usr/bin/env bun
+
+import { Command } from "commander";
+import type { ThreadId } from "@uncaged/uwf-protocol";
+
+import {
+  cmdThreadFork,
+  cmdThreadKill,
+  cmdThreadList,
+  cmdThreadRead,
+  THREAD_READ_DEFAULT_QUOTA,
+  cmdThreadShow,
+  cmdThreadStart,
+  cmdThreadStep,
+  cmdThreadSteps,
+} from "./commands/thread.js";
+import { cmdWorkflowList, cmdWorkflowPut, cmdWorkflowShow } from "./commands/workflow.js";
+import { cmdSetup, cmdSetupInteractive } from "./commands/setup.js";
+import {
+  cmdCasGet,
+  cmdCasHas,
+  cmdCasPut,
+  cmdCasReindex,
+  cmdCasRefs,
+  cmdCasSchemaGet,
+  cmdCasSchemaList,
+  cmdCasWalk,
+} from "./commands/cas.js";
+import { resolveStorageRoot } from "./store.js";
+import { type OutputFormat, formatOutput } from "./format.js";
+
+function writeOutput(data: unknown): void {
+  const fmt = program.opts().format as OutputFormat;
+  process.stdout.write(`${formatOutput(data, fmt)}\n`);
+}
+
+function runAction(action: () => Promise<void>): void {
+  action().catch((e: unknown) => {
+    const message = e instanceof Error ? e.message : String(e);
+    process.stderr.write(`${message}\n`);
+    process.exit(1);
+  });
+}
+
+const program = new Command();
+
+program.name("uwf").description("Stateless workflow CLI");
+program.option("--format <fmt>", "Output format: json or yaml", "json");
+
+const workflow = program.command("workflow").description("Workflow registry and CAS");
+
+workflow
+  .command("put")
+  .description("Register a workflow from YAML")
+  .argument("<file>", "Workflow YAML file")
+  .action((file: string) => {
+    const storageRoot = resolveStorageRoot();
+    runAction(async () => {
+      const result = await cmdWorkflowPut(storageRoot, file);
+      writeOutput(result);
+    });
+  });
+
+workflow
+  .command("show")
+  .description("Show a workflow by name or CAS hash")
+  .argument("<id>", "Workflow name or hash")
+  .action((id: string) => {
+    const storageRoot = resolveStorageRoot();
+    runAction(async () => {
+      const result = await cmdWorkflowShow(storageRoot, id);
+      writeOutput(result);
+    });
+  });
+
+workflow
+  .command("list")
+  .description("List registered workflows")
+  .action(() => {
+    const storageRoot = resolveStorageRoot();
+    runAction(async () => {
+      const result = await cmdWorkflowList(storageRoot);
+      writeOutput(result);
+    });
+  });
+
+const thread = program.command("thread").description("Thread lifecycle and execution");
+
+thread
+  .command("start")
+  .description("Create a thread without executing")
+  .argument("<workflow>", "Workflow name or hash")
+  .requiredOption("-p, --prompt <text>", "User prompt")
+  .action((workflow: string, opts: { prompt: string }) => {
+    const storageRoot = resolveStorageRoot();
+    runAction(async () => {
+      const result = await cmdThreadStart(storageRoot, workflow, opts.prompt);
+      writeOutput(result);
+    });
+  });
+
+thread
+  .command("step")
+  .description("Execute one step")
+  .argument("<thread-id>", "Thread ULID")
+  .option("--agent <cmd>", "Override agent command")
+  .action((threadId: string, opts: { agent: string | undefined }) => {
+    const storageRoot = resolveStorageRoot();
+    runAction(async () => {
+      const agentOverride = opts.agent ?? null;
+      const result = await cmdThreadStep(storageRoot, threadId, agentOverride);
+      writeOutput(result);
+    });
+  });
+
+thread
+  .command("show")
+  .description("Show thread head pointer")
+  .argument("<thread-id>", "Thread ULID")
+  .action((threadId: string) => {
+    const storageRoot = resolveStorageRoot();
+    runAction(async () => {
+      const result = await cmdThreadShow(storageRoot, threadId);
+      writeOutput(result);
+    });
+  });
+
+thread
+  .command("list")
+  .description("List active threads")
+  .option("--all", "Include archived threads")
+  .action((opts: { all: boolean }) => {
+    const storageRoot = resolveStorageRoot();
+    runAction(async () => {
+      const result = await cmdThreadList(storageRoot, opts.all);
+      writeOutput(result);
+    });
+  });
+
+thread
+  .command("kill")
+  .description("Terminate and archive a thread")
+  .argument("<thread-id>", "Thread ULID")
+  .action((threadId: string) => {
+    const storageRoot = resolveStorageRoot();
+    runAction(async () => {
+      const result = await cmdThreadKill(storageRoot, threadId);
+      writeOutput(result);
+    });
+  });
+
+thread
+  .command("steps")
+  .description("List all steps in a thread")
+  .argument("<thread-id>", "Thread ULID")
+  .action((threadId: string) => {
+    const storageRoot = resolveStorageRoot();
+    runAction(async () => {
+      const result = await cmdThreadSteps(storageRoot, threadId);
+      writeOutput(result);
+    });
+  });
+
+thread
+  .command("read")
+  .description("Read thread context as human-readable markdown")
+  .argument("<thread-id>", "Thread ULID")
+  .option("--quota <chars>", "Max output characters", String(THREAD_READ_DEFAULT_QUOTA))
+  .option("--before <step-hash>", "Load steps before this hash (exclusive)")
+  .option("--start", "Include start step in output")
+  .option("--detail", "Expand detail content for each step")
+  .action((threadId: string, opts: { quota: string; before: string | undefined; start: boolean; detail: boolean }) => {
+    const storageRoot = resolveStorageRoot();
+    runAction(async () => {
+      const quota = Number.parseInt(opts.quota, 10);
+      if (!Number.isFinite(quota) || quota < 1) {
+        process.stderr.write("invalid --quota: must be a positive integer\n");
+        process.exit(1);
+      }
+      const before = opts.before ?? null;
+      const markdown = await cmdThreadRead(storageRoot, threadId as ThreadId, quota, before, opts.start ?? false, opts.detail ?? false);
+      process.stdout.write(markdown.endsWith("\n") ? markdown : `${markdown}\n`);
+    });
+  });
+
+thread
+  .command("fork")
+  .description("Fork a thread from a specific step")
+  .argument("<step-hash>", "CAS hash of the StartNode or StepNode to fork from")
+  .action((stepHash: string) => {
+    const storageRoot = resolveStorageRoot();
+    runAction(async () => {
+      const result = await cmdThreadFork(storageRoot, stepHash);
+      writeOutput(result);
+    });
+  });
+
+program
+  .command("setup")
+  .description("Configure provider, model, and agent")
+  .option("--provider <name>", "Provider name")
+  .option("--base-url <url>", "OpenAI-compatible API base URL")
+  .option("--api-key <key>", "API key")
+  .option("--model <name>", "Default model name")
+  .option("--agent <name>", "Default agent alias")
+  .action((opts: {
+    provider?: string;
+    baseUrl?: string;
+    apiKey?: string;
+    model?: string;
+    agent?: string;
+  }) => {
+    const storageRoot = resolveStorageRoot();
+    runAction(async () => {
+      if (opts.provider && opts.baseUrl && opts.apiKey && opts.model) {
+        const result = await cmdSetup({
+          provider: opts.provider,
+          baseUrl: opts.baseUrl,
+          apiKey: opts.apiKey,
+          model: opts.model,
+          agent: opts.agent ?? undefined,
+          storageRoot,
+        });
+        writeOutput(result);
+      } else if (!opts.provider && !opts.baseUrl && !opts.apiKey && !opts.model) {
+        await cmdSetupInteractive(storageRoot);
+      } else {
+        throw new Error(
+          "Non-interactive setup requires all of: --provider, --base-url, --api-key, --model",
+        );
+      }
+    });
+  });
+
+const cas = program.command("cas").description("Content-addressable storage operations");
+
+cas
+  .command("get")
+  .description("Read a CAS node (type + payload; use --timestamp to include timestamp)")
+  .argument("<hash>", "CAS hash (13 char)")
+  .option("--timestamp", "Include timestamp in output")
+  .action((hash: string, opts: { timestamp?: boolean }) => {
+    const storageRoot = resolveStorageRoot();
+    runAction(async () => {
+      writeOutput(await cmdCasGet(storageRoot, hash, opts));
+    });
+  });
+
+cas
+  .command("put")
+  .description("Store a node, print its hash")
+  .argument("<type-hash>", "Type (schema) hash")
+  .argument("<data>", "JSON file path or inline JSON string")
+  .action((typeHash: string, data: string) => {
+    const storageRoot = resolveStorageRoot();
+    runAction(async () => {
+      writeOutput(await cmdCasPut(storageRoot, typeHash, data));
+    });
+  });
+
+cas
+  .command("has")
+  .description("Check if a hash exists")
+  .argument("<hash>", "CAS hash (13 char)")
+  .action((hash: string) => {
+    const storageRoot = resolveStorageRoot();
+    runAction(async () => {
+      writeOutput(await cmdCasHas(storageRoot, hash));
+    });
+  });
+
+cas
+  .command("refs")
+  .description("List direct CAS references from a node")
+  .argument("<hash>", "CAS hash (13 char)")
+  .action((hash: string) => {
+    const storageRoot = resolveStorageRoot();
+    runAction(async () => {
+      writeOutput(await cmdCasRefs(storageRoot, hash));
+    });
+  });
+
+cas
+  .command("walk")
+  .description("Recursive traversal from a node")
+  .argument("<hash>", "CAS hash (13 char)")
+  .action((hash: string) => {
+    const storageRoot = resolveStorageRoot();
+    runAction(async () => {
+      writeOutput(await cmdCasWalk(storageRoot, hash));
+    });
+  });
+
+cas
+  .command("reindex")
+  .description("Rebuild type index from all CAS nodes")
+  .action(() => {
+    const storageRoot = resolveStorageRoot();
+    runAction(async () => {
+      writeOutput(await cmdCasReindex(storageRoot));
+    });
+  });
+
+const casSchema = cas.command("schema").description("CAS schema operations");
+
+casSchema
+  .command("list")
+  .description("List all registered schemas")
+  .action(() => {
+    const storageRoot = resolveStorageRoot();
+    runAction(async () => {
+      writeOutput(await cmdCasSchemaList(storageRoot));
+    });
+  });
+
+casSchema
+  .command("get")
+  .description("Show a schema by its type hash")
+  .argument("<hash>", "Schema type hash")
+  .action((hash: string) => {
+    const storageRoot = resolveStorageRoot();
+    runAction(async () => {
+      writeOutput(await cmdCasSchemaGet(storageRoot, hash));
+    });
+  });
+
+program.parseAsync(process.argv).catch((e: unknown) => {
+  const message = e instanceof Error ? e.message : String(e);
+  process.stderr.write(`${message}\n`);
+  process.exit(1);
+});

packages/cli-uwf/src/commands/cas.ts

@@ -0,0 +1,139 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import type { Hash, JSONSchema, Store } from "@uncaged/json-cas";
+import { bootstrap, getSchema, refs, walk } from "@uncaged/json-cas";
+import { createFsStore } from "@uncaged/json-cas-fs";
+
+// ---- Helpers ----
+
+function openStore(storageRoot: string): Store {
+  return createFsStore(join(storageRoot, "cas"));
+}
+
+function readJsonArg(fileOrInline: string): unknown {
+  try {
+    return JSON.parse(fileOrInline);
+  } catch {
+    try {
+      return JSON.parse(readFileSync(fileOrInline, "utf-8"));
+    } catch (e) {
+      throw new Error(`Cannot parse JSON from "${fileOrInline}": ${e}`);
+    }
+  }
+}
+
+// ---- Commands (all return JSON-serializable data) ----
+
+export async function cmdCasGet(
+  storageRoot: string,
+  hash: string,
+  opts: { timestamp?: boolean },
+): Promise<unknown> {
+  const store = openStore(storageRoot);
+  const node = store.get(hash);
+  if (node === null) {
+    throw new Error(`Node not found: ${hash}`);
+  }
+  if (opts.timestamp) {
+    return node;
+  }
+  const { timestamp: _, ...rest } = node as Record<string, unknown>;
+  return rest;
+}
+
+export async function cmdCasPut(
+  storageRoot: string,
+  typeHash: string,
+  data: string,
+): Promise<{ hash: string }> {
+  const store = openStore(storageRoot);
+  const payload = readJsonArg(data);
+  const hash = await store.put(typeHash, payload);
+  return { hash };
+}
+
+export async function cmdCasHas(
+  storageRoot: string,
+  hash: string,
+): Promise<{ exists: boolean }> {
+  const store = openStore(storageRoot);
+  return { exists: store.has(hash) };
+}
+
+export async function cmdCasRefs(
+  storageRoot: string,
+  hash: string,
+): Promise<{ refs: string[] }> {
+  const store = openStore(storageRoot);
+  const node = store.get(hash);
+  if (node === null) {
+    throw new Error(`Node not found: ${hash}`);
+  }
+  return { refs: refs(store, node) };
+}
+
+export async function cmdCasWalk(
+  storageRoot: string,
+  hash: string,
+): Promise<{ hashes: string[] }> {
+  const store = openStore(storageRoot);
+  const result: string[] = [];
+  walk(store, hash, (h) => {
+    result.push(h);
+  });
+  return { hashes: result };
+}
+
+export type SchemaListEntry = {
+  hash: string;
+  title: string;
+};
+
+export async function cmdCasSchemaList(
+  storageRoot: string,
+): Promise<SchemaListEntry[]> {
+  const store = openStore(storageRoot);
+  const metaHash = await bootstrap(store);
+  const entries: SchemaListEntry[] = [];
+
+  // Include meta-schema itself
+  entries.push({ hash: metaHash, title: "(meta-schema)" });
+
+  for (const hash of store.listByType(metaHash)) {
+    if (hash === metaHash) continue;
+    const node = store.get(hash);
+    if (node !== null) {
+      const schema = node.payload as JSONSchema;
+      const title =
+        (schema.title as string | undefined) ??
+        (schema.description as string | undefined) ??
+        "(unnamed)";
+      entries.push({ hash, title });
+    }
+  }
+  return entries;
+}
+
+export async function cmdCasReindex(
+  storageRoot: string,
+): Promise<{ status: string }> {
+  const indexDir = join(storageRoot, "cas", "_index");
+  const { rmSync } = await import("node:fs");
+  rmSync(indexDir, { recursive: true, force: true });
+  // Re-open store to trigger migration rebuild
+  openStore(storageRoot);
+  return { status: "reindexed" };
+}
+
+export async function cmdCasSchemaGet(
+  storageRoot: string,
+  hash: string,
+): Promise<unknown> {
+  const store = openStore(storageRoot);
+  const schema = getSchema(store, hash);
+  if (schema === null) {
+    throw new Error(`Schema not found: ${hash}`);
+  }
+  return schema;
+}

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

@@ -0,0 +1,332 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+
+import { stringify, parse } from "yaml";
+
+/**
+ * Preset provider list — embedded to avoid runtime YAML loading dependency.
+ * Keep in sync with providers.yaml in cli-workflow.
+ */
+const PRESET_PROVIDERS = [
+  // International
+  { name: "openai", label: "OpenAI", baseUrl: "https://api.openai.com/v1" },
+  { name: "xai", label: "xAI", baseUrl: "https://api.x.ai/v1" },
+  { name: "openrouter", label: "OpenRouter", baseUrl: "https://openrouter.ai/api/v1" },
+  { name: "venice", label: "Venice", baseUrl: "https://api.venice.ai/api/v1" },
+  // China
+  { name: "dashscope", label: "DashScope (Alibaba)", baseUrl: "https://dashscope.aliyuncs.com/compatible-mode/v1" },
+  { name: "deepseek", label: "DeepSeek", baseUrl: "https://api.deepseek.com/v1" },
+  { name: "siliconflow", label: "SiliconFlow", baseUrl: "https://api.siliconflow.cn/v1" },
+  { name: "volcengine", label: "Volcengine (ByteDance)", baseUrl: "https://ark.cn-beijing.volces.com/api/v3" },
+  { name: "kimi", label: "Kimi (Moonshot)", baseUrl: "https://api.moonshot.cn/v1" },
+  { name: "glm", label: "GLM (Zhipu AI)", baseUrl: "https://open.bigmodel.cn/api/paas/v4" },
+  { name: "stepfun", label: "StepFun", baseUrl: "https://api.stepfun.com/v1" },
+  { name: "minimax", label: "MiniMax", baseUrl: "https://api.minimax.io/v1" },
+  // Local
+  { name: "ollama", label: "Ollama (local)", baseUrl: "http://localhost:11434/v1" },
+] as const;
+
+type SetupArgs = {
+  provider: string;
+  baseUrl: string;
+  apiKey: string;
+  model: string;
+  agent?: string | undefined;
+  storageRoot: string;
+};
+
+function getConfigPath(root: string): string {
+  return join(root, "config.yaml");
+}
+
+function getEnvPath(root: string): string {
+  return join(root, ".env");
+}
+
+/**
+ * Load existing config.yaml or return empty structure.
+ */
+function loadExistingConfig(configPath: string): Record<string, unknown> {
+  try {
+    if (existsSync(configPath)) {
+      const raw = parse(readFileSync(configPath, "utf8")) as unknown;
+      if (typeof raw === "object" && raw !== null && !Array.isArray(raw)) {
+        return raw as Record<string, unknown>;
+      }
+    }
+  } catch {
+    // ignore parse errors, start fresh
+  }
+  return {};
+}
+
+/**
+ * Load existing .env as key=value map.
+ */
+function loadEnvFile(envPath: string): Record<string, string> {
+  const env: Record<string, string> = {};
+  try {
+    if (existsSync(envPath)) {
+      for (const line of readFileSync(envPath, "utf8").split("\n")) {
+        const trimmed = line.trim();
+        if (trimmed === "" || trimmed.startsWith("#")) continue;
+        const eq = trimmed.indexOf("=");
+        if (eq > 0) {
+          env[trimmed.slice(0, eq)] = trimmed.slice(eq + 1);
+        }
+      }
+    }
+  } catch {
+    // ignore
+  }
+  return env;
+}
+
+function saveEnvFile(envPath: string, env: Record<string, string>): void {
+  const lines = Object.entries(env).map(([k, v]) => `${k}=${v}`);
+  writeFileSync(envPath, `${lines.join("\n")}\n`, "utf8");
+}
+
+function apiKeyEnvName(providerName: string): string {
+  return `${providerName.toUpperCase().replace(/[^A-Z0-9]/g, "_")}_API_KEY`;
+}
+
+/**
+ * Merge setup args into config.yaml structure. Non-destructive — preserves existing entries.
+ */
+function mergeConfig(existing: Record<string, unknown>, args: SetupArgs): Record<string, unknown> {
+  const providers = (typeof existing.providers === "object" && existing.providers !== null
+    ? { ...(existing.providers as Record<string, unknown>) }
+    : {}) as Record<string, unknown>;
+
+  const envName = apiKeyEnvName(args.provider);
+  providers[args.provider] = { baseUrl: args.baseUrl, apiKeyEnv: envName };
+
+  const models = (typeof existing.models === "object" && existing.models !== null
+    ? { ...(existing.models as Record<string, unknown>) }
+    : {}) as Record<string, unknown>;
+  models.default = { provider: args.provider, name: args.model };
+
+  const agents = (typeof existing.agents === "object" && existing.agents !== null
+    ? { ...(existing.agents as Record<string, unknown>) }
+    : {}) as Record<string, unknown>;
+
+  const agentName = args.agent ?? "hermes";
+  if (Object.keys(agents).length === 0) {
+    agents.hermes = { command: "uwf-hermes", args: [] };
+  }
+
+  return {
+    ...existing,
+    providers,
+    models,
+    agents,
+    defaultAgent: existing.defaultAgent ?? agentName,
+    defaultModel: existing.defaultModel ?? "default",
+  };
+}
+
+/**
+ * Non-interactive setup. All required args provided via CLI flags.
+ */
+export async function cmdSetup(args: SetupArgs): Promise<Record<string, unknown>> {
+  const { storageRoot } = args;
+  mkdirSync(storageRoot, { recursive: true });
+
+  const configPath = getConfigPath(storageRoot);
+  const envPath = getEnvPath(storageRoot);
+
+  const existing = loadExistingConfig(configPath);
+  const merged = mergeConfig(existing, args);
+
+  writeFileSync(configPath, stringify(merged, { indent: 2 }), "utf8");
+
+  // Write API key to .env
+  const envName = apiKeyEnvName(args.provider);
+  const envData = loadEnvFile(envPath);
+  envData[envName] = args.apiKey;
+  saveEnvFile(envPath, envData);
+
+  return {
+    configPath,
+    envPath,
+    provider: args.provider,
+    model: args.model,
+    defaultAgent: merged.defaultAgent,
+  };
+}
+
+/** Read a line with terminal echo disabled (for secrets). */
+async function promptSecret(label: string): Promise<string> {
+  process.stdout.write(label);
+  return new Promise((resolve) => {
+    const rawWasSet = process.stdin.isRaw;
+    if (process.stdin.isTTY) {
+      process.stdin.setRawMode(true);
+    }
+    process.stdin.resume();
+    process.stdin.setEncoding("utf8");
+
+    let buf = "";
+    const onData = (chunk: string) => {
+      for (const c of chunk.toString()) {
+        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");
+          resolve(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("*");
+      }
+    };
+    process.stdin.on("data", onData);
+  });
+}
+
+/** Fetch available models from an OpenAI-compatible /models endpoint. */
+async function fetchModels(baseUrl: string, apiKey: string): Promise<string[]> {
+  try {
+    const url = `${baseUrl.replace(/\/+$/, "")}/models`;
+    const res = await fetch(url, {
+      headers: { Authorization: `Bearer ${apiKey}` },
+      signal: AbortSignal.timeout(10_000),
+    });
+    if (!res.ok) return [];
+    const body = (await res.json()) as { data?: { id: string }[] };
+    if (!Array.isArray(body.data)) return [];
+    const NON_CHAT = /speech|embed|image|video|audio|ocr|rerank|tts|asr|paraformer|sambert|cosyvoice|wordart|wanx|wan2|flux|stable-diffusion|gui-/i;
+    return body.data.map((m) => m.id).filter((id) => !NON_CHAT.test(id)).sort();
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Interactive setup — prompts user for provider, API key, model.
+ */
+export async function cmdSetupInteractive(storageRoot: string): Promise<Record<string, unknown>> {
+  const rl = createInterface({ input, output });
+
+  try {
+    console.log("Configure LLM provider for uwf workflow agents.\n");
+
+    // 1. Provider selection
+    const numWidth = String(PRESET_PROVIDERS.length + 1).length;
+    console.log("Select a provider:\n");
+    for (let i = 0; i < PRESET_PROVIDERS.length; i++) {
+      const p = PRESET_PROVIDERS[i];
+      if (!p) continue;
+      const num = String(i + 1).padStart(numWidth);
+      console.log(`  ${num}) ${p.label.padEnd(28)} ${p.baseUrl}`);
+    }
+    const customNum = String(PRESET_PROVIDERS.length + 1).padStart(numWidth);
+    console.log(`  ${customNum}) Custom (enter name and URL manually)\n`);
+
+    const choice = (await rl.question(`Choose [1-${PRESET_PROVIDERS.length + 1}]: `)).trim();
+    const choiceNum = Number.parseInt(choice, 10);
+    if (Number.isNaN(choiceNum) || choiceNum < 1 || choiceNum > PRESET_PROVIDERS.length + 1) {
+      throw new Error(`Invalid choice: ${choice}`);
+    }
+
+    let providerName: string;
+    let baseUrl: string;
+
+    if (choiceNum <= PRESET_PROVIDERS.length) {
+      const selected = PRESET_PROVIDERS[choiceNum - 1];
+      if (!selected) throw new Error("Invalid selection");
+      providerName = selected.name;
+      baseUrl = selected.baseUrl;
+      console.log(`\n  → ${selected.label} (${selected.baseUrl})\n`);
+    } else {
+      providerName = (await rl.question("Provider name (e.g. my-proxy): ")).trim();
+      if (!providerName) throw new Error("Provider name required");
+      baseUrl = (await rl.question("OpenAI-compatible API base URL: ")).trim();
+      if (!baseUrl) throw new Error("Base URL required");
+    }
+
+    // 2. API key
+    rl.close();
+    const apiKey = await promptSecret("API key: ");
+    if (!apiKey) throw new Error("API key required");
+
+    // 3. Model selection
+    const rl2 = createInterface({ input, output });
+    console.log("\nFetching available models...");
+    const models = await fetchModels(baseUrl, apiKey);
+
+    let model: string;
+    if (models.length > 0) {
+      console.log(`\nAvailable models (${models.length}):\n`);
+      const nw = String(models.length).length;
+      // Multi-column layout
+      const maxLen = models.reduce((m, s) => Math.max(m, s.length), 0);
+      const colWidth = nw + 2 + maxLen + 4; // "  N) name    "
+      const termCols = process.stdout.columns || 100;
+      const cols = Math.max(1, Math.floor(termCols / colWidth));
+      const rows = Math.ceil(models.length / cols);
+      for (let r = 0; r < rows; r++) {
+        let line = "";
+        for (let c = 0; c < cols; c++) {
+          const idx = c * rows + r;
+          if (idx >= models.length) break;
+          const num = String(idx + 1).padStart(nw);
+          const name = (models[idx] ?? "").padEnd(maxLen);
+          line += `  ${num}) ${name}  `;
+        }
+        console.log(line.trimEnd());
+      }
+      console.log(`\nChoose a number, or type a model name directly.`);
+      const modelInput = (await rl2.question(`Default model [1-${models.length}]: `)).trim();
+      if (!modelInput) throw new Error("Model required");
+      const modelNum = Number.parseInt(modelInput, 10);
+      if (!Number.isNaN(modelNum) && modelNum >= 1 && modelNum <= models.length) {
+        model = models[modelNum - 1] ?? modelInput;
+      } else {
+        model = modelInput;
+      }
+    } else {
+      console.log("Could not fetch models. Enter model name manually.");
+      model = (await rl2.question("Default model (e.g. qwen-plus, gpt-4o): ")).trim();
+      if (!model) throw new Error("Model required");
+    }
+
+    rl2.close();
+
+    console.log(`  → ${providerName}/${model}\n`);
+
+    await cmdSetup({
+      provider: providerName,
+      baseUrl,
+      apiKey,
+      model,
+      storageRoot,
+    });
+
+    console.log("Setup complete! Get started:\n");
+    console.log("  uwf workflow put <workflow.yaml>   Register a workflow");
+    console.log('  uwf thread start <name> -p "..."   Start a thread');
+    console.log("  uwf thread step <thread-id>        Execute next step");
+    console.log("");
+
+    return null as unknown as Record<string, unknown>;
+  } finally {
+    rl.close();
+  }
+}

packages/cli-uwf/src/commands/thread.ts

@@ -0,0 +1,796 @@
+import { execFileSync } from "node:child_process";
+
+import { getSchema, validate } from "@uncaged/json-cas";
+import type { JSONSchema, Store as CasStore } from "@uncaged/json-cas";
+import { stringify } from "yaml";
+import { getEnvPath, loadWorkflowConfig } from "@uncaged/uwf-agent-kit";
+import { evaluate } from "@uncaged/uwf-moderator";
+import type {
+  AgentAlias,
+  AgentConfig,
+  CasRef,
+  ModeratorContext,
+  StartEntry,
+  StartNodePayload,
+  StartOutput,
+  StepContext,
+  StepEntry,
+  StepNodePayload,
+  StepOutput,
+  ThreadForkOutput,
+  ThreadId,
+  ThreadListItem,
+  ThreadStepsOutput,
+  WorkflowConfig,
+  WorkflowPayload,
+} from "@uncaged/uwf-protocol";
+import { generateUlid } from "@uncaged/workflow-util";
+import { config as loadDotenv } from "dotenv";
+
+import {
+  appendThreadHistory,
+  createUwfStore,
+  findThreadInHistory,
+  loadThreadHistory,
+  loadThreadsIndex,
+  loadWorkflowRegistry,
+  resolveWorkflowHash,
+  saveThreadsIndex,
+  type ThreadHistoryLine,
+  type UwfStore,
+} from "../store.js";
+import { isCasRef } from "../validate.js";
+
+const END_ROLE = "$END";
+export const THREAD_READ_DEFAULT_QUOTA = 4000;
+
+type ChainState = {
+  startHash: CasRef;
+  start: StartNodePayload;
+  stepsNewestFirst: StepNodePayload[];
+  headIsStart: boolean;
+};
+
+type OrderedStepItem = {
+  hash: CasRef;
+  payload: StepNodePayload;
+  timestamp: number;
+};
+
+export type KillOutput = {
+  thread: ThreadId;
+  archived: boolean;
+};
+
+function fail(message: string): never {
+  process.stderr.write(`${message}\n`);
+  process.exit(1);
+}
+
+async function resolveWorkflowCasRef(
+  uwf: UwfStore,
+  storageRoot: string,
+  workflowId: string,
+): Promise<CasRef> {
+  const registry = await loadWorkflowRegistry(storageRoot);
+  const hash = resolveWorkflowHash(registry, workflowId);
+  if (!isCasRef(hash)) {
+    fail(`workflow not found: ${workflowId}`);
+  }
+  const node = uwf.store.get(hash);
+  if (node === null) {
+    fail(`CAS node not found: ${hash}`);
+  }
+  if (node.type !== uwf.schemas.workflow) {
+    fail(`node ${hash} is not a Workflow (type ${node.type})`);
+  }
+  return hash;
+}
+
+function resolveWorkflowFromHead(uwf: UwfStore, head: CasRef): CasRef | null {
+  const node = uwf.store.get(head);
+  if (node === null) {
+    return null;
+  }
+
+  if (node.type === uwf.schemas.startNode) {
+    const payload = node.payload as StartNodePayload;
+    return payload.workflow;
+  }
+
+  const payload = node.payload as StepNodePayload;
+  if (typeof payload.start !== "string") {
+    return null;
+  }
+
+  const startNode = uwf.store.get(payload.start);
+  if (startNode === null || startNode.type !== uwf.schemas.startNode) {
+    return null;
+  }
+
+  return (startNode.payload as StartNodePayload).workflow;
+}
+
+export async function cmdThreadStart(
+  storageRoot: string,
+  workflowId: string,
+  prompt: string,
+): Promise<StartOutput> {
+  const uwf = await createUwfStore(storageRoot);
+  const workflowHash = await resolveWorkflowCasRef(uwf, storageRoot, workflowId);
+
+  const threadId = generateUlid(Date.now()) as ThreadId;
+  const startPayload: StartNodePayload = {
+    workflow: workflowHash,
+    prompt,
+  };
+
+  const headHash = await uwf.store.put(uwf.schemas.startNode, startPayload);
+  const node = uwf.store.get(headHash);
+  if (node === null || !validate(uwf.store, node)) {
+    fail("stored StartNode failed schema validation");
+  }
+
+  const index = await loadThreadsIndex(storageRoot);
+  index[threadId] = headHash;
+  await saveThreadsIndex(storageRoot, index);
+
+  return { workflow: workflowHash, thread: threadId };
+}
+
+export async function cmdThreadShow(storageRoot: string, threadId: ThreadId): Promise<StepOutput> {
+  const index = await loadThreadsIndex(storageRoot);
+  const activeHead = index[threadId];
+  if (activeHead !== undefined) {
+    const uwf = await createUwfStore(storageRoot);
+    const workflow = resolveWorkflowFromHead(uwf, activeHead);
+    if (workflow === null) {
+      fail(`failed to resolve workflow from head: ${activeHead}`);
+    }
+    return {
+      workflow,
+      thread: threadId,
+      head: activeHead,
+      done: false,
+    };
+  }
+
+  const hist = await findThreadInHistory(storageRoot, threadId);
+  if (hist !== null) {
+    return {
+      workflow: hist.workflow,
+      thread: threadId,
+      head: hist.head,
+      done: true,
+    };
+  }
+
+  fail(`thread not found: ${threadId}`);
+}
+
+async function threadListItemFromActive(
+  uwf: UwfStore,
+  threadId: ThreadId,
+  head: CasRef,
+): Promise<ThreadListItem | null> {
+  const workflow = resolveWorkflowFromHead(uwf, head);
+  if (workflow === null) {
+    return null;
+  }
+  return { thread: threadId, workflow, head };
+}
+
+export async function cmdThreadList(
+  storageRoot: string,
+  includeAll: boolean,
+): Promise<ThreadListItem[]> {
+  const uwf = await createUwfStore(storageRoot);
+  const index = await loadThreadsIndex(storageRoot);
+  const items: ThreadListItem[] = [];
+
+  for (const [threadId, head] of Object.entries(index)) {
+    const item = await threadListItemFromActive(uwf, threadId as ThreadId, head);
+    if (item !== null) {
+      items.push(item);
+    }
+  }
+
+  if (!includeAll) {
+    return items;
+  }
+
+  const activeIds = new Set(items.map((i) => i.thread));
+  const history = await loadThreadHistory(storageRoot);
+  for (const entry of history) {
+    if (!activeIds.has(entry.thread)) {
+      items.push({
+        thread: entry.thread,
+        workflow: entry.workflow,
+        head: entry.head,
+      });
+    }
+  }
+
+  return items;
+}
+
+function walkChain(uwf: UwfStore, headHash: CasRef): ChainState {
+  const headNode = uwf.store.get(headHash);
+  if (headNode === null) {
+    fail(`CAS node not found: ${headHash}`);
+  }
+
+  if (headNode.type === uwf.schemas.startNode) {
+    return {
+      startHash: headHash,
+      start: headNode.payload as StartNodePayload,
+      stepsNewestFirst: [],
+      headIsStart: true,
+    };
+  }
+
+  if (headNode.type !== uwf.schemas.stepNode) {
+    fail(`head ${headHash} is not a StartNode or StepNode`);
+  }
+
+  const stepsNewestFirst: StepNodePayload[] = [];
+  let hash: CasRef | null = headHash;
+
+  while (hash !== null) {
+    const node = uwf.store.get(hash);
+    if (node === null) {
+      fail(`CAS node not found while walking chain: ${hash}`);
+    }
+    if (node.type !== uwf.schemas.stepNode) {
+      break;
+    }
+    const payload = node.payload as StepNodePayload;
+    stepsNewestFirst.push(payload);
+    hash = payload.prev;
+  }
+
+  const newest = stepsNewestFirst[0];
+  if (newest === undefined) {
+    fail(`empty step chain at head ${headHash}`);
+  }
+
+  const startNode = uwf.store.get(newest.start);
+  if (startNode === null || startNode.type !== uwf.schemas.startNode) {
+    fail(`StartNode not found: ${newest.start}`);
+  }
+
+  return {
+    startHash: newest.start,
+    start: startNode.payload as StartNodePayload,
+    stepsNewestFirst,
+    headIsStart: false,
+  };
+}
+
+function expandOutput(uwf: UwfStore, outputRef: CasRef): unknown {
+  const node = uwf.store.get(outputRef);
+  if (node === null) {
+    return {};
+  }
+  return node.payload;
+}
+
+/**
+ * Recursively expand all cas_ref fields in a CAS node's payload,
+ * replacing hash strings with the referenced node's expanded payload.
+ */
+function expandDeep(store: CasStore, hash: CasRef, visited?: Set<string>): unknown {
+  const seen = visited ?? new Set<string>();
+  if (seen.has(hash)) return hash; // cycle guard
+  seen.add(hash);
+
+  const node = store.get(hash);
+  if (node === null) return hash;
+
+  const schema = getSchema(store, node.type);
+  if (schema === null) return node.payload;
+
+  return expandValue(store, schema, node.payload, seen);
+}
+
+function expandValue(store: CasStore, schema: JSONSchema, value: unknown, visited: Set<string>): unknown {
+  // If this field is a cas_ref, expand it
+  if (schema.format === "cas_ref") {
+    if (typeof value === "string") {
+      return expandDeep(store, value as CasRef, visited);
+    }
+    return value;
+  }
+
+  // anyOf (nullable refs)
+  if (Array.isArray(schema.anyOf)) {
+    for (const sub of schema.anyOf as JSONSchema[]) {
+      if (sub.format === "cas_ref" && typeof value === "string") {
+        return expandDeep(store, value as CasRef, visited);
+      }
+    }
+    return value;
+  }
+
+  // Array of cas_ref items
+  if (schema.type === "array" && schema.items && Array.isArray(value)) {
+    const itemSchema = schema.items as JSONSchema;
+    return (value as unknown[]).map((item) => expandValue(store, itemSchema, item, visited));
+  }
+
+  // Object with properties
+  if (value !== null && typeof value === "object" && !Array.isArray(value) && schema.properties) {
+    const props = schema.properties as Record<string, JSONSchema>;
+    const obj = value as Record<string, unknown>;
+    const result: Record<string, unknown> = {};
+    for (const [key, val] of Object.entries(obj)) {
+      const propSchema = props[key];
+      result[key] = propSchema ? expandValue(store, propSchema, val, visited) : val;
+    }
+    return result;
+  }
+
+  return value;
+}
+
+function collectOrderedSteps(
+  uwf: UwfStore,
+  headHash: CasRef,
+  chain: ChainState,
+): OrderedStepItem[] {
+  let hash: CasRef | null = headHash;
+  const hashToNode = new Map<string, { payload: StepNodePayload; timestamp: number }>();
+  while (hash !== null) {
+    const node = uwf.store.get(hash);
+    if (node === null || node.type !== uwf.schemas.stepNode) {
+      break;
+    }
+    const payload = node.payload as StepNodePayload;
+    hashToNode.set(hash, { payload, timestamp: node.timestamp });
+    hash = payload.prev;
+  }
+
+  let cur: CasRef | null = chain.headIsStart ? null : headHash;
+  const ordered: OrderedStepItem[] = [];
+  while (cur !== null) {
+    const entry = hashToNode.get(cur);
+    if (entry === undefined) {
+      break;
+    }
+    ordered.push({ hash: cur, ...entry });
+    cur = entry.payload.prev;
+  }
+  ordered.reverse();
+  return ordered;
+}
+
+function formatYaml(value: unknown): string {
+  return stringify(value).trimEnd();
+}
+
+function formatCompactStep(index: number, item: OrderedStepItem, outputYaml: string): string {
+  return [
+    `## Step ${index}: ${item.payload.role}`,
+    "",
+    `- **Hash:** \`${item.hash}\``,
+    `- **Agent:** ${item.payload.agent}`,
+    "",
+    "### Output",
+    "",
+    "```yaml",
+    outputYaml,
+    "```",
+  ].join("\n");
+}
+
+function formatThreadReadMarkdown(options: {
+  threadId: ThreadId;
+  workflowName: string;
+  workflowHash: CasRef;
+  prompt: string;
+  ordered: OrderedStepItem[];
+  uwf: UwfStore;
+  workflow: WorkflowPayload;
+  quota: number;
+  before: CasRef | null;
+  showStart: boolean;
+  showDetail: boolean;
+}): string {
+  const { ordered, uwf, workflow, quota, before, showStart, showDetail } = options;
+
+  // Determine which steps to consider
+  let candidates = ordered;
+  if (before !== null) {
+    const idx = candidates.findIndex((s) => s.hash === before);
+    if (idx === -1) {
+      fail(`step ${before} not found in thread ${options.threadId}`);
+    }
+    candidates = candidates.slice(0, idx);
+  }
+
+  // Walk backward from newest, accumulating chars until quota exceeded
+  const selected: OrderedStepItem[] = [];
+  let totalChars = 0;
+  for (let i = candidates.length - 1; i >= 0; i--) {
+    const item = candidates[i];
+    if (item === undefined) continue;
+    const outputYaml = formatYaml(expandOutput(uwf, item.payload.output));
+    const blockLen = formatCompactStep(i + 1, item, outputYaml).length;
+    selected.unshift(item);
+    totalChars += blockLen;
+    if (totalChars > quota) break;
+  }
+
+  const skippedCount = candidates.length - selected.length;
+  const parts: string[] = [];
+
+  // Start section
+  if (before === null || showStart) {
+    parts.push(
+      [
+        `# Thread \`${options.threadId}\``,
+        "",
+        `**Workflow:** ${options.workflowName} (\`${options.workflowHash}\`)`,
+        "",
+        "## Task",
+        "",
+        options.prompt,
+      ].join("\n"),
+    );
+  }
+
+  // Skip hint
+  if (skippedCount > 0 && selected.length > 0) {
+    const firstSelected = selected[0];
+    if (firstSelected !== undefined) {
+      parts.push(
+        `*(${skippedCount} earlier step${skippedCount > 1 ? "s" : ""}, load with \`uwf thread read ${options.threadId} --before ${firstSelected.hash}\`)*`,
+      );
+    }
+  }
+
+  // Step blocks
+  const startIndex = candidates.length - selected.length;
+  for (let i = 0; i < selected.length; i++) {
+    const item = selected[i];
+    if (item === undefined) continue;
+    const stepNum = startIndex + i + 1;
+    const outputYaml = formatYaml(expandOutput(uwf, item.payload.output));
+    const ts = new Date(item.timestamp).toISOString().replace("T", " ").replace(/\.\d+Z$/, "");
+    const stepLines = [
+      `## Step ${stepNum}: ${item.payload.role} \`${item.hash}\``,
+      `**Agent:** ${item.payload.agent} | **Time:** ${ts}`,
+    ];
+    const roleDef = workflow.roles[item.payload.role];
+    if (roleDef) {
+      stepLines.push("", "### Prompt", "", roleDef.systemPrompt);
+    }
+    stepLines.push(
+      "",
+      "### Output",
+      "",
+      "```yaml",
+      outputYaml,
+      "```",
+    );
+    if (showDetail && item.payload.detail) {
+      const detailExpanded = expandDeep(uwf.store, item.payload.detail);
+      const detailYaml = formatYaml(detailExpanded);
+      stepLines.push("", "### Detail", "", "```yaml", detailYaml, "```");
+    }
+    parts.push(stepLines.join("\n"));
+  }
+
+  return parts.join("\n\n---\n\n");
+}
+
+function buildModeratorContext(uwf: UwfStore, chain: ChainState): ModeratorContext {
+  const chronological = [...chain.stepsNewestFirst].reverse();
+  const steps: StepContext[] = chronological.map((step) => ({
+    role: step.role,
+    output: expandOutput(uwf, step.output),
+    detail: step.detail,
+    agent: step.agent,
+  }));
+  return { start: chain.start, steps };
+}
+
+function loadWorkflowPayload(uwf: UwfStore, workflowRef: CasRef): WorkflowPayload {
+  const node = uwf.store.get(workflowRef);
+  if (node === null) {
+    fail(`workflow CAS node not found: ${workflowRef}`);
+  }
+  if (node.type !== uwf.schemas.workflow) {
+    fail(`node ${workflowRef} is not a Workflow`);
+  }
+  return node.payload as WorkflowPayload;
+}
+
+function parseAgentOverride(override: string): AgentConfig {
+  const parts = override
+    .trim()
+    .split(/\s+/)
+    .filter((p) => p.length > 0);
+  const command = parts[0];
+  if (command === undefined) {
+    fail("agent override must not be empty");
+  }
+  return { command, args: parts.slice(1) };
+}
+
+function resolveAgentConfig(
+  config: WorkflowConfig,
+  workflow: WorkflowPayload,
+  role: string,
+  agentOverride: string | null,
+): AgentConfig {
+  if (agentOverride !== null) {
+    return parseAgentOverride(agentOverride);
+  }
+
+  let alias: AgentAlias = config.defaultAgent;
+  if (config.agentOverrides !== null) {
+    const roleOverrides = config.agentOverrides[workflow.name];
+    if (roleOverrides !== undefined && roleOverrides[role] !== undefined) {
+      alias = roleOverrides[role];
+    }
+  }
+
+  const agentConfig = config.agents[alias];
+  if (agentConfig === undefined) {
+    fail(`unknown agent alias in config: ${alias}`);
+  }
+  return agentConfig;
+}
+
+function spawnAgent(agent: AgentConfig, threadId: ThreadId, role: string): CasRef {
+  const argv = [...agent.args, threadId, role];
+  let stdout: string;
+  try {
+    stdout = execFileSync(agent.command, argv, {
+      encoding: "utf8",
+      env: process.env,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+  } catch (e) {
+    const err = e as NodeJS.ErrnoException & { stderr?: Buffer | string };
+    const stderr =
+      err.stderr === undefined
+        ? ""
+        : typeof err.stderr === "string"
+          ? err.stderr
+          : err.stderr.toString("utf8");
+    const detail = stderr.trim() !== "" ? `: ${stderr.trim()}` : "";
+    fail(`agent command failed (${agent.command})${detail}`);
+  }
+
+  const line = stdout.trim().split("\n").pop()?.trim() ?? "";
+  if (!isCasRef(line)) {
+    fail(`agent stdout is not a valid CAS hash: ${line || "(empty)"}`);
+  }
+  return line;
+}
+
+async function archiveThread(
+  storageRoot: string,
+  threadId: ThreadId,
+  workflow: CasRef,
+  head: CasRef,
+): Promise<void> {
+  const index = await loadThreadsIndex(storageRoot);
+  delete index[threadId];
+  await saveThreadsIndex(storageRoot, index);
+  await appendThreadHistory(storageRoot, {
+    thread: threadId,
+    workflow,
+    head,
+    completedAt: Date.now(),
+  });
+}
+
+export async function cmdThreadStep(
+  storageRoot: string,
+  threadId: ThreadId,
+  agentOverride: string | null,
+): Promise<StepOutput> {
+  const index = await loadThreadsIndex(storageRoot);
+  const headHash = index[threadId];
+  if (headHash === undefined) {
+    fail(`thread not active: ${threadId}`);
+  }
+
+  const uwf = await createUwfStore(storageRoot);
+  const chain = walkChain(uwf, headHash);
+  const workflowHash = chain.start.workflow;
+  const workflow = loadWorkflowPayload(uwf, workflowHash);
+  const context = buildModeratorContext(uwf, chain);
+
+  const nextResult = await evaluate(workflow, context);
+  if (!nextResult.ok) {
+    fail(nextResult.error.message);
+  }
+
+  if (nextResult.value === END_ROLE) {
+    await archiveThread(storageRoot, threadId, workflowHash, headHash);
+    return {
+      workflow: workflowHash,
+      thread: threadId,
+      head: headHash,
+      done: true,
+    };
+  }
+
+  const role = nextResult.value;
+  const config = await loadWorkflowConfig(storageRoot);
+  const agent = resolveAgentConfig(config, workflow, role, agentOverride);
+
+  loadDotenv({ path: getEnvPath(storageRoot) });
+  const newHead = spawnAgent(agent, threadId, role);
+
+  // Re-create store to pick up nodes written by the agent subprocess
+  const uwfAfter = await createUwfStore(storageRoot);
+  const newNode = uwfAfter.store.get(newHead);
+  if (newNode === null || newNode.type !== uwfAfter.schemas.stepNode) {
+    fail(`agent returned hash that is not a StepNode: ${newHead}`);
+  }
+
+  // Reload threads index to avoid overwriting changes made by the agent subprocess
+  const freshIndex = await loadThreadsIndex(storageRoot);
+  freshIndex[threadId] = newHead;
+  await saveThreadsIndex(storageRoot, freshIndex);
+
+  const chainAfter = walkChain(uwfAfter, newHead);
+  const contextAfter = buildModeratorContext(uwfAfter, chainAfter);
+  const afterResult = await evaluate(workflow, contextAfter);
+  if (!afterResult.ok) {
+    fail(afterResult.error.message);
+  }
+
+  const done = afterResult.value === END_ROLE;
+  if (done) {
+    await archiveThread(storageRoot, threadId, workflowHash, newHead);
+  }
+
+  return {
+    workflow: workflowHash,
+    thread: threadId,
+    head: newHead,
+    done,
+  };
+}
+
+async function resolveHeadHash(storageRoot: string, threadId: ThreadId): Promise<CasRef> {
+  const index = await loadThreadsIndex(storageRoot);
+  const activeHead = index[threadId];
+  if (activeHead !== undefined) {
+    return activeHead;
+  }
+  const hist = await findThreadInHistory(storageRoot, threadId);
+  if (hist !== null) {
+    return hist.head;
+  }
+  fail(`thread not found: ${threadId}`);
+}
+
+export async function cmdThreadSteps(
+  storageRoot: string,
+  threadId: ThreadId,
+): Promise<ThreadStepsOutput> {
+  const headHash = await resolveHeadHash(storageRoot, threadId);
+  const uwf = await createUwfStore(storageRoot);
+  const chain = walkChain(uwf, headHash);
+
+  const startNode = uwf.store.get(chain.startHash);
+  if (startNode === null) {
+    fail(`StartNode not found: ${chain.startHash}`);
+  }
+
+  const startEntry: StartEntry = {
+    hash: chain.startHash,
+    workflow: chain.start.workflow,
+    prompt: chain.start.prompt,
+    timestamp: startNode.timestamp,
+  };
+
+  const stepEntries: StepEntry[] = [];
+  const ordered = collectOrderedSteps(uwf, headHash, chain);
+
+  for (const item of ordered) {
+    stepEntries.push({
+      hash: item.hash,
+      role: item.payload.role,
+      output: expandOutput(uwf, item.payload.output),
+      detail: item.payload.detail,
+      agent: item.payload.agent,
+      timestamp: item.timestamp,
+    });
+  }
+
+  return {
+    thread: threadId,
+    workflow: chain.start.workflow,
+    steps: [startEntry, ...stepEntries],
+  };
+}
+
+export async function cmdThreadRead(
+  storageRoot: string,
+  threadId: ThreadId,
+  quota: number = THREAD_READ_DEFAULT_QUOTA,
+  before: CasRef | null = null,
+  showStart: boolean = false,
+  showDetail: boolean = false,
+): Promise<string> {
+  const headHash = await resolveHeadHash(storageRoot, threadId);
+  const uwf = await createUwfStore(storageRoot);
+  const chain = walkChain(uwf, headHash);
+  const workflow = loadWorkflowPayload(uwf, chain.start.workflow);
+  const ordered = collectOrderedSteps(uwf, headHash, chain);
+
+  return formatThreadReadMarkdown({
+    threadId,
+    workflowName: workflow.name,
+    workflowHash: chain.start.workflow,
+    prompt: chain.start.prompt,
+    ordered,
+    uwf,
+    workflow,
+    quota,
+    before,
+    showStart,
+    showDetail,
+  });
+}
+
+export async function cmdThreadFork(
+  storageRoot: string,
+  stepHash: CasRef,
+): Promise<ThreadForkOutput> {
+  const uwf = await createUwfStore(storageRoot);
+  const node = uwf.store.get(stepHash);
+  if (node === null) {
+    fail(`CAS node not found: ${stepHash}`);
+  }
+  if (node.type !== uwf.schemas.startNode && node.type !== uwf.schemas.stepNode) {
+    fail(`node ${stepHash} is not a StartNode or StepNode`);
+  }
+
+  const newThreadId = generateUlid(Date.now()) as ThreadId;
+  const index = await loadThreadsIndex(storageRoot);
+  index[newThreadId] = stepHash;
+  await saveThreadsIndex(storageRoot, index);
+
+  return {
+    thread: newThreadId,
+    forkedFrom: {
+      step: stepHash,
+    },
+  };
+}
+
+export async function cmdThreadKill(storageRoot: string, threadId: ThreadId): Promise<KillOutput> {
+  const index = await loadThreadsIndex(storageRoot);
+  const head = index[threadId];
+  if (head === undefined) {
+    fail(`thread not active: ${threadId}`);
+  }
+
+  const uwf = await createUwfStore(storageRoot);
+  const workflow = resolveWorkflowFromHead(uwf, head);
+  if (workflow === null) {
+    fail(`failed to resolve workflow from head: ${head}`);
+  }
+
+  delete index[threadId];
+  await saveThreadsIndex(storageRoot, index);
+
+  const historyEntry: ThreadHistoryLine = {
+    thread: threadId,
+    workflow,
+    head,
+    completedAt: Date.now(),
+  };
+  await appendThreadHistory(storageRoot, historyEntry);
+
+  return { thread: threadId, archived: true };
+}

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

@@ -0,0 +1,153 @@
+import { readFile } from "node:fs/promises";
+
+import type { JSONSchema } from "@uncaged/json-cas";
+import { putSchema, validate } from "@uncaged/json-cas";
+import type { CasRef, RoleDefinition, WorkflowPayload } from "@uncaged/uwf-protocol";
+import { parse } from "yaml";
+
+import {
+  createUwfStore,
+  findRegistryName,
+  loadWorkflowRegistry,
+  resolveWorkflowHash,
+  saveWorkflowRegistry,
+  type UwfStore,
+} from "../store.js";
+import { parseWorkflowPayload } from "../validate.js";
+
+export type WorkflowListEntry = {
+  name: string;
+  hash: CasRef;
+};
+
+export type WorkflowPutOutput = {
+  name: string;
+  hash: CasRef;
+};
+
+export type WorkflowShowOutput = {
+  hash: CasRef;
+  name: string | null;
+  type: CasRef;
+  payload: WorkflowPayload;
+  timestamp: number;
+};
+
+function fail(message: string): never {
+  process.stderr.write(`${message}\n`);
+  process.exit(1);
+}
+
+function isJsonSchema(value: unknown): value is JSONSchema {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+async function resolveOutputSchemaRef(
+  uwf: UwfStore,
+  roleName: string,
+  outputSchema: unknown,
+): Promise<CasRef> {
+  if (!isJsonSchema(outputSchema)) {
+    fail(`role "${roleName}": outputSchema must be a JSON Schema object`);
+  }
+  const schema: JSONSchema = outputSchema.title === undefined
+    ? { ...outputSchema, title: roleName }
+    : outputSchema;
+  return putSchema(uwf.store, schema);
+}
+
+async function materializeWorkflowPayload(
+  uwf: UwfStore,
+  raw: WorkflowPayload,
+): Promise<WorkflowPayload> {
+  const roles: Record<string, RoleDefinition> = {};
+  for (const [roleName, role] of Object.entries(raw.roles)) {
+    const outputSchema = await resolveOutputSchemaRef(
+      uwf,
+      `${raw.name}.${roleName}`,
+      role.outputSchema,
+    );
+    roles[roleName] = {
+      description: role.description,
+      systemPrompt: role.systemPrompt,
+      outputSchema,
+    };
+  }
+  return {
+    name: raw.name,
+    description: raw.description,
+    roles,
+    conditions: raw.conditions,
+    graph: raw.graph,
+  };
+}
+
+export async function cmdWorkflowPut(
+  storageRoot: string,
+  filePath: string,
+): Promise<WorkflowPutOutput> {
+  let text: string;
+  try {
+    text = await readFile(filePath, "utf8");
+  } catch {
+    fail(`file not found: ${filePath}`);
+  }
+
+  let raw: unknown;
+  try {
+    raw = parse(text) as unknown;
+  } catch (e) {
+    fail(`invalid YAML: ${e instanceof Error ? e.message : String(e)}`);
+  }
+
+  const payload = parseWorkflowPayload(raw);
+  if (payload === null) {
+    fail("invalid workflow YAML: expected WorkflowPayload shape");
+  }
+
+  const uwf = await createUwfStore(storageRoot);
+  const materialized = await materializeWorkflowPayload(uwf, payload);
+
+  const hash = await uwf.store.put(uwf.schemas.workflow, materialized);
+  const node = uwf.store.get(hash);
+  if (node === null || !validate(uwf.store, node)) {
+    fail("stored workflow failed schema validation");
+  }
+
+  const registry = await loadWorkflowRegistry(storageRoot);
+  registry[materialized.name] = hash;
+  await saveWorkflowRegistry(storageRoot, registry);
+
+  return { name: materialized.name, hash };
+}
+
+export async function cmdWorkflowShow(
+  storageRoot: string,
+  id: string,
+): Promise<WorkflowShowOutput> {
+  const uwf = await createUwfStore(storageRoot);
+  const registry = await loadWorkflowRegistry(storageRoot);
+  const hash = resolveWorkflowHash(registry, id);
+
+  const node = uwf.store.get(hash);
+  if (node === null) {
+    fail(`CAS node not found: ${hash}`);
+  }
+  if (node.type !== uwf.schemas.workflow) {
+    fail(`node ${hash} is not a Workflow (type ${node.type})`);
+  }
+
+  const payload = node.payload as WorkflowPayload;
+  return {
+    hash,
+    name: findRegistryName(registry, hash),
+    type: node.type,
+    payload,
+    timestamp: node.timestamp,
+  };
+}
+
+export async function cmdWorkflowList(storageRoot: string): Promise<WorkflowListEntry[]> {
+  const registry = await loadWorkflowRegistry(storageRoot);
+  return Object.entries(registry).map(([name, hash]) => ({ name, hash }));
+}

packages/cli-uwf/src/format.ts

@@ -0,0 +1,12 @@
+import { stringify } from "yaml";
+
+export type OutputFormat = "json" | "yaml";
+
+export function formatOutput(data: unknown, format: OutputFormat): string {
+  switch (format) {
+    case "json":
+      return JSON.stringify(data);
+    case "yaml":
+      return stringify(data).trimEnd();
+  }
+}

packages/cli-uwf/src/schemas.ts

@@ -0,0 +1,26 @@
+import type { Hash, Store } from "@uncaged/json-cas";
+import { putSchema } from "@uncaged/json-cas";
+import {
+  START_NODE_SCHEMA,
+  STEP_NODE_SCHEMA,
+  WORKFLOW_SCHEMA,
+} from "@uncaged/uwf-protocol";
+
+export type UwfSchemaHashes = {
+  workflow: Hash;
+  startNode: Hash;
+  stepNode: Hash;
+};
+
+/**
+ * Register Workflow, StartNode, and StepNode JSON Schemas in the CAS store.
+ * Idempotent: safe to call on every CLI invocation.
+ */
+export async function registerUwfSchemas(store: Store): Promise<UwfSchemaHashes> {
+  const [workflow, startNode, stepNode] = await Promise.all([
+    putSchema(store, WORKFLOW_SCHEMA),
+    putSchema(store, START_NODE_SCHEMA),
+    putSchema(store, STEP_NODE_SCHEMA),
+  ]);
+  return { workflow, startNode, stepNode };
+}

packages/cli-uwf/src/store.ts

@@ -0,0 +1,212 @@
+import { appendFile, mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import type { Hash, Store } from "@uncaged/json-cas";
+import { createFsStore } from "@uncaged/json-cas-fs";
+import type { CasRef, ThreadId, ThreadListItem, ThreadsIndex } from "@uncaged/uwf-protocol";
+import { parse, stringify } from "yaml";
+
+import { registerUwfSchemas, type UwfSchemaHashes } from "./schemas.js";
+
+export type WorkflowRegistry = Record<string, CasRef>;
+
+/** Default filesystem root for uwf data (`~/.uncaged/workflow`). */
+export function getDefaultStorageRoot(): string {
+  return join(homedir(), ".uncaged", "workflow");
+}
+
+/**
+ * Resolve storage root.
+ * Priority: `UNCAGED_WORKFLOW_STORAGE_ROOT` → `WORKFLOW_STORAGE_ROOT` → default.
+ */
+export function resolveStorageRoot(): string {
+  const internal = process.env.UNCAGED_WORKFLOW_STORAGE_ROOT;
+  if (internal !== undefined && internal !== "") {
+    return internal;
+  }
+  const userOverride = process.env.WORKFLOW_STORAGE_ROOT;
+  if (userOverride !== undefined && userOverride !== "") {
+    return userOverride;
+  }
+  return getDefaultStorageRoot();
+}
+
+export function getCasDir(storageRoot: string): string {
+  return join(storageRoot, "cas");
+}
+
+export function getRegistryPath(storageRoot: string): string {
+  return join(storageRoot, "workflows.yaml");
+}
+
+export function getThreadsPath(storageRoot: string): string {
+  return join(storageRoot, "threads.yaml");
+}
+
+export function getHistoryPath(storageRoot: string): string {
+  return join(storageRoot, "history.jsonl");
+}
+
+export type ThreadHistoryLine = ThreadListItem & {
+  completedAt: number;
+};
+
+export type UwfStore = {
+  storageRoot: string;
+  store: Store;
+  schemas: UwfSchemaHashes;
+};
+
+export async function createUwfStore(storageRoot: string): Promise<UwfStore> {
+  const casDir = getCasDir(storageRoot);
+  await mkdir(casDir, { recursive: true });
+  const store = createFsStore(casDir);
+  const schemas = await registerUwfSchemas(store);
+  return { storageRoot, store, schemas };
+}
+
+export async function loadWorkflowRegistry(storageRoot: string): Promise<WorkflowRegistry> {
+  const path = getRegistryPath(storageRoot);
+  try {
+    const text = await readFile(path, "utf8");
+    const raw = parse(text) as unknown;
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+      return {};
+    }
+    const registry: WorkflowRegistry = {};
+    for (const [name, hash] of Object.entries(raw as Record<string, unknown>)) {
+      if (typeof hash === "string") {
+        registry[name] = hash;
+      }
+    }
+    return registry;
+  } catch (e) {
+    const err = e as NodeJS.ErrnoException;
+    if (err.code === "ENOENT") {
+      return {};
+    }
+    throw e;
+  }
+}
+
+export async function saveWorkflowRegistry(
+  storageRoot: string,
+  registry: WorkflowRegistry,
+): Promise<void> {
+  const path = getRegistryPath(storageRoot);
+  await mkdir(storageRoot, { recursive: true });
+  const text = stringify(registry, { indent: 2 });
+  await writeFile(path, text, "utf8");
+}
+
+export function resolveWorkflowHash(registry: WorkflowRegistry, id: string): CasRef {
+  return registry[id] !== undefined ? registry[id] : id;
+}
+
+export function findRegistryName(registry: WorkflowRegistry, hash: Hash): string | null {
+  for (const [name, h] of Object.entries(registry)) {
+    if (h === hash) {
+      return name;
+    }
+  }
+  return null;
+}
+
+export async function loadThreadsIndex(storageRoot: string): Promise<ThreadsIndex> {
+  const path = getThreadsPath(storageRoot);
+  try {
+    const text = await readFile(path, "utf8");
+    const raw = parse(text) as unknown;
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+      return {};
+    }
+    const index: ThreadsIndex = {};
+    for (const [threadId, head] of Object.entries(raw as Record<string, unknown>)) {
+      if (typeof head === "string") {
+        index[threadId as ThreadId] = head;
+      }
+    }
+    return index;
+  } catch (e) {
+    const err = e as NodeJS.ErrnoException;
+    if (err.code === "ENOENT") {
+      return {};
+    }
+    throw e;
+  }
+}
+
+export async function saveThreadsIndex(storageRoot: string, index: ThreadsIndex): Promise<void> {
+  const path = getThreadsPath(storageRoot);
+  await mkdir(storageRoot, { recursive: true });
+  const text = stringify(index, { indent: 2 });
+  await writeFile(path, text, "utf8");
+}
+
+export async function loadThreadHistory(storageRoot: string): Promise<ThreadHistoryLine[]> {
+  const path = getHistoryPath(storageRoot);
+  try {
+    const text = await readFile(path, "utf8");
+    const lines: ThreadHistoryLine[] = [];
+    for (const line of text.split("\n")) {
+      const trimmed = line.trim();
+      if (trimmed === "") {
+        continue;
+      }
+      let raw: unknown;
+      try {
+        raw = JSON.parse(trimmed) as unknown;
+      } catch {
+        continue;
+      }
+      if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+        continue;
+      }
+      const rec = raw as Record<string, unknown>;
+      const thread = rec.thread;
+      const workflow = rec.workflow;
+      const head = rec.head;
+      const completedAt = rec.completedAt;
+      if (
+        typeof thread === "string" &&
+        typeof workflow === "string" &&
+        typeof head === "string" &&
+        typeof completedAt === "number"
+      ) {
+        lines.push({ thread: thread as ThreadId, workflow, head, completedAt });
+      }
+    }
+    return lines;
+  } catch (e) {
+    const err = e as NodeJS.ErrnoException;
+    if (err.code === "ENOENT") {
+      return [];
+    }
+    throw e;
+  }
+}
+
+export async function findThreadInHistory(
+  storageRoot: string,
+  threadId: ThreadId,
+): Promise<ThreadHistoryLine | null> {
+  const history = await loadThreadHistory(storageRoot);
+  for (let i = history.length - 1; i >= 0; i--) {
+    const entry = history[i];
+    if (entry !== undefined && entry.thread === threadId) {
+      return entry;
+    }
+  }
+  return null;
+}
+
+export async function appendThreadHistory(
+  storageRoot: string,
+  entry: ThreadHistoryLine,
+): Promise<void> {
+  const path = getHistoryPath(storageRoot);
+  await mkdir(storageRoot, { recursive: true });
+  const line = `${JSON.stringify(entry)}\n`;
+  await appendFile(path, line, "utf8");
+}

packages/cli-uwf/src/validate.ts

@@ -0,0 +1,71 @@
+import type { CasRef, WorkflowPayload } from "@uncaged/uwf-protocol";
+
+const CAS_REF_PATTERN = /^[0-9A-HJKMNP-TV-Z]{13}$/;
+
+export function isCasRef(value: string): value is CasRef {
+  return CAS_REF_PATTERN.test(value);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isRoleDefinition(value: unknown): boolean {
+  if (!isRecord(value)) {
+    return false;
+  }
+  const outputSchema = value.outputSchema;
+  const schemaOk = isRecord(outputSchema) && typeof outputSchema.type === "string";
+  return (
+    typeof value.description === "string" && typeof value.systemPrompt === "string" && schemaOk
+  );
+}
+
+function isConditionDefinition(value: unknown): boolean {
+  if (!isRecord(value)) {
+    return false;
+  }
+  return typeof value.description === "string" && typeof value.expression === "string";
+}
+
+function isTransition(value: unknown): boolean {
+  if (!isRecord(value)) {
+    return false;
+  }
+  const condition = value.condition;
+  return typeof value.role === "string" && (condition === null || typeof condition === "string");
+}
+
+function isStringRecord(value: unknown, itemCheck: (item: unknown) => boolean): boolean {
+  if (!isRecord(value)) {
+    return false;
+  }
+  return Object.values(value).every(itemCheck);
+}
+
+function isGraph(value: unknown): boolean {
+  if (!isRecord(value)) {
+    return false;
+  }
+  return Object.values(value).every(
+    (transitions) => Array.isArray(transitions) && transitions.every((t) => isTransition(t)),
+  );
+}
+
+/** Validate YAML-parsed workflow document shape (outputSchema may be inline JSON Schema). */
+export function parseWorkflowPayload(raw: unknown): WorkflowPayload | null {
+  if (!isRecord(raw)) {
+    return null;
+  }
+  if (typeof raw.name !== "string" || typeof raw.description !== "string") {
+    return null;
+  }
+  if (
+    !isStringRecord(raw.roles, isRoleDefinition) ||
+    !isStringRecord(raw.conditions, isConditionDefinition) ||
+    !isGraph(raw.graph)
+  ) {
+    return null;
+  }
+  return raw as WorkflowPayload;
+}

packages/cli-uwf/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "include": ["src"],
+  "references": [
+    { "path": "../uwf-protocol" },
+    { "path": "../uwf-moderator" },
+    { "path": "../uwf-agent-kit" }
+  ]
+}

packages/cli-workflow/CHANGELOG.md

@@ -1,5 +1,71 @@
 # @uncaged/cli-workflow
 
+## 0.5.0-alpha.4
+
+### Patch Changes
+
+- Updated dependencies
+- Updated dependencies [f74b482]
+- Updated dependencies [f74b482]
+  - @uncaged/workflow-util@0.5.0-alpha.4
+  - @uncaged/workflow-protocol@0.5.0-alpha.4
+  - @uncaged/workflow-cas@0.5.0-alpha.4
+  - @uncaged/workflow-execute@0.5.0-alpha.4
+  - @uncaged/workflow-gateway@0.5.0-alpha.4
+  - @uncaged/workflow-register@0.5.0-alpha.4
+  - @uncaged/workflow-runtime@0.5.0-alpha.4
+
+## 0.5.0-alpha.3
+
+### Patch Changes
+
+- Updated dependencies
+  - @uncaged/workflow-protocol@0.5.0-alpha.3
+  - @uncaged/workflow-cas@0.5.0-alpha.3
+  - @uncaged/workflow-execute@0.5.0-alpha.3
+  - @uncaged/workflow-gateway@0.5.0-alpha.3
+  - @uncaged/workflow-register@0.5.0-alpha.3
+  - @uncaged/workflow-runtime@0.5.0-alpha.3
+  - @uncaged/workflow-util@0.5.0-alpha.3
+
+## 0.5.0-alpha.2
+
+### Patch Changes
+
+- Updated dependencies
+  - @uncaged/workflow-protocol@0.5.0-alpha.2
+  - @uncaged/workflow-cas@0.5.0-alpha.2
+  - @uncaged/workflow-execute@0.5.0-alpha.2
+  - @uncaged/workflow-gateway@0.5.0-alpha.2
+  - @uncaged/workflow-register@0.5.0-alpha.2
+  - @uncaged/workflow-runtime@0.5.0-alpha.2
+  - @uncaged/workflow-util@0.5.0-alpha.2
+
+## 0.5.0-alpha.1
+
+### Patch Changes
+
+- @uncaged/workflow-cas@0.5.0-alpha.1
+- @uncaged/workflow-execute@0.5.0-alpha.1
+- @uncaged/workflow-gateway@0.5.0-alpha.1
+- @uncaged/workflow-protocol@0.5.0-alpha.1
+- @uncaged/workflow-register@0.5.0-alpha.1
+- @uncaged/workflow-runtime@0.5.0-alpha.1
+- @uncaged/workflow-util@0.5.0-alpha.1
+
+## 0.5.0-alpha.0
+
+### Patch Changes
+
+- Updated dependencies
+  - @uncaged/workflow-protocol@0.5.0-alpha.0
+  - @uncaged/workflow-cas@0.5.0-alpha.0
+  - @uncaged/workflow-execute@0.5.0-alpha.0
+  - @uncaged/workflow-register@0.5.0-alpha.0
+  - @uncaged/workflow-runtime@0.5.0-alpha.0
+  - @uncaged/workflow-util@0.5.0-alpha.0
+  - @uncaged/workflow-gateway@0.5.0-alpha.0
+
 ## 0.4.5
 
 ### Patch Changes

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

@@ -20,9 +20,6 @@ import { addCliArgs } from "./bundle-fixture.js";
 const fixtureDescriptor = `export const descriptor = { description: "fixture", roles: {}, graph: { edges: [] } };
 `;
 
-const wfPutImport = `import { putContentMerkleNode } from "@uncaged/workflow-cas";
-`;
-
 function casStoredForm(raw: string): string {
   return serializeMerkleNode(createContentMerkleNode(raw));
 }
@@ -52,12 +49,12 @@ describe("cli workflow commands", () => {
     const bundlePath = join(bundleDir, "demo.esm.js");
     await writeFile(
       bundlePath,
-      `${fixtureDescriptor}${wfPutImport}import fs from "node:fs";
+      `${fixtureDescriptor}import fs from "node:fs";
 
 export const run = async function* (input, options) {
   fs.existsSync(".");
   const cas = options.cas;
-  const h = await putContentMerkleNode(cas, input.prompt);
+  const h = await cas.put(input.prompt);
   yield { role: "noop", contentHash: h, meta: { done: true }, refs: [h] };
   return { returnCode: 0, summary: "done" };
 }
@@ -155,10 +152,9 @@ export const run = async function* (input) { return { returnCode: 0, summary: in
   },
   graph: { edges: [] },
 };
-${wfPutImport}
 export const run = async function* (input, options) {
   const cas = options.cas;
-  const h = await putContentMerkleNode(cas, input.prompt);
+  const h = await cas.put( input.prompt);
   yield { role: "greeter", contentHash: h, meta: { greeting: "hi" }, refs: [h] };
   return { returnCode: 0, summary: "ok" };
 };
@@ -197,9 +193,9 @@ export const run = async function* (input, options) {
     const bundlePath = join(bundleDir, "demo.esm.js");
     await writeFile(
       bundlePath,
-      `${fixtureDescriptor}${wfPutImport}export const run = async function* (_input, options) {
+      `${fixtureDescriptor}export const run = async function* (_input, options) {
   const cas = options.cas;
-  const h = await putContentMerkleNode(cas, "x");
+  const h = await cas.put( "x");
   yield { role: "a", contentHash: h, meta: {}, refs: [h] };
   return { returnCode: 0, summary: "x" };
 }
@@ -228,9 +224,9 @@ export const run = async function* (input, options) {
     const dtsPath = join(bundleDir, "types.d.ts");
     await writeFile(
       bundlePath,
-      `${fixtureDescriptor}${wfPutImport}export const run = async function* (_input, options) {
+      `${fixtureDescriptor}export const run = async function* (_input, options) {
   const cas = options.cas;
-  const h = await putContentMerkleNode(cas, "x");
+  const h = await cas.put( "x");
   yield { role: "a", contentHash: h, meta: {}, refs: [h] };
   return { returnCode: 0, summary: "x" };
 }
@@ -261,9 +257,9 @@ export const run = async function* (input, options) {
     const bundlePath = join(bundleDir, "demo.esm.js");
     await writeFile(
       bundlePath,
-      `${fixtureDescriptor}${wfPutImport}export const run = async function* (_input, options) {
+      `${fixtureDescriptor}export const run = async function* (_input, options) {
   const cas = options.cas;
-  const h = await putContentMerkleNode(cas, "x");
+  const h = await cas.put( "x");
   yield { role: "a", contentHash: h, meta: {}, refs: [h] };
   return { returnCode: 0, summary: "x" };
 }
@@ -284,16 +280,16 @@ export const run = async function* (input, options) {
     const bundleDir = join(storageRoot, "src");
     await mkdir(bundleDir, { recursive: true });
     const bundlePath = join(bundleDir, "demo.esm.js");
-    const v1 = `${fixtureDescriptor}${wfPutImport}export const run = async function* (_input, options) {
+    const v1 = `${fixtureDescriptor}export const run = async function* (_input, options) {
   const cas = options.cas;
-  const h = await putContentMerkleNode(cas, "v1");
+  const h = await cas.put( "v1");
   yield { role: "a", contentHash: h, meta: {}, refs: [h] };
   return { returnCode: 0, summary: "v1" };
 }
 `;
-    const v2 = `${fixtureDescriptor}${wfPutImport}export const run = async function* (_input, options) {
+    const v2 = `${fixtureDescriptor}export const run = async function* (_input, options) {
   const cas = options.cas;
-  const h = await putContentMerkleNode(cas, "v2");
+  const h = await cas.put( "v2");
   yield { role: "a", contentHash: h, meta: {}, refs: [h] };
   return { returnCode: 0, summary: "v2" };
 }
@@ -326,16 +322,16 @@ export const run = async function* (input, options) {
     const bundleDir = join(storageRoot, "src");
     await mkdir(bundleDir, { recursive: true });
     const bundlePath = join(bundleDir, "demo.esm.js");
-    const v1 = `${fixtureDescriptor}${wfPutImport}export const run = async function* (_input, options) {
+    const v1 = `${fixtureDescriptor}export const run = async function* (_input, options) {
   const cas = options.cas;
-  const h = await putContentMerkleNode(cas, "v1");
+  const h = await cas.put( "v1");
   yield { role: "a", contentHash: h, meta: {}, refs: [h] };
   return { returnCode: 0, summary: "v1" };
 }
 `;
-    const v2 = `${fixtureDescriptor}${wfPutImport}export const run = async function* (_input, options) {
+    const v2 = `${fixtureDescriptor}export const run = async function* (_input, options) {
   const cas = options.cas;
-  const h = await putContentMerkleNode(cas, "v2");
+  const h = await cas.put( "v2");
   yield { role: "a", contentHash: h, meta: {}, refs: [h] };
   return { returnCode: 0, summary: "v2" };
 }
@@ -378,9 +374,9 @@ export const run = async function* (input, options) {
     const bundlePath = join(bundleDir, "demo.esm.js");
     await writeFile(
       bundlePath,
-      `${fixtureDescriptor}${wfPutImport}export const run = async function* (_input, options) {
+      `${fixtureDescriptor}export const run = async function* (_input, options) {
   const cas = options.cas;
-  const h = await putContentMerkleNode(cas, "x");
+  const h = await cas.put( "x");
   yield { role: "a", contentHash: h, meta: {}, refs: [h] };
   return { returnCode: 0, summary: "x" };
 }
@@ -391,9 +387,9 @@ export const run = async function* (input, options) {
     expect(add1.ok).toBe(true);
     await writeFile(
       bundlePath,
-      `${fixtureDescriptor}${wfPutImport}export const run = async function* (_input, options) {
+      `${fixtureDescriptor}export const run = async function* (_input, options) {
   const cas = options.cas;
-  const h = await putContentMerkleNode(cas, "y");
+  const h = await cas.put( "y");
   yield { role: "a", contentHash: h, meta: {}, refs: [h] };
   return { returnCode: 0, summary: "y" };
 }
@@ -446,9 +442,9 @@ export const run = async function* (input, options) {
     const bundlePath = join(bundleDir, "demo.esm.js");
     await writeFile(
       bundlePath,
-      `${fixtureDescriptor}${wfPutImport}export const run = async function* (_input, options) {
+      `${fixtureDescriptor}export const run = async function* (_input, options) {
   const cas = options.cas;
-  const h = await putContentMerkleNode(cas, "x");
+  const h = await cas.put( "x");
   yield { role: "a", contentHash: h, meta: {}, refs: [h] };
   return { returnCode: 0, summary: "x" };
 }
@@ -463,9 +459,9 @@ export const run = async function* (input, options) {
     const hash1 = add1.value.hash;
     await writeFile(
       bundlePath,
-      `${fixtureDescriptor}${wfPutImport}export const run = async function* (_input, options) {
+      `${fixtureDescriptor}export const run = async function* (_input, options) {
   const cas = options.cas;
-  const h = await putContentMerkleNode(cas, "y");
+  const h = await cas.put( "y");
   yield { role: "a", contentHash: h, meta: {}, refs: [h] };
   return { returnCode: 0, summary: "y" };
 }

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

@@ -15,9 +15,7 @@ import { addCliArgs } from "./bundle-fixture.js";
 import { ensureTestWorkflowRegistryConfig } from "./workflow-registry-fixture.js";
 
 /** Three-role workflow that respects `input.steps` for fork/resume. */
-const threeRoleBundleSource = `import { putContentMerkleNode } from "@uncaged/workflow-cas";
-
-export const descriptor = {
+const threeRoleBundleSource = `export const descriptor = {
   description: "fork-cli",
   roles: {
     planner: { description: "planner", schema: {} },
@@ -30,16 +28,16 @@ export const run = async function* (input, options) {
   const cas = options.cas;
   const has = (r) => input.steps.some((s) => s.role === r);
   if (!has("planner")) {
-    const h = await putContentMerkleNode(cas, "p1");
+    const h = await cas.put( "p1");
     yield { role: "planner", contentHash: h, meta: { k: "planner" }, refs: [h] };
   }
   if (!has("coder")) {
-    const h = await putContentMerkleNode(cas, "c1");
+    const h = await cas.put( "c1");
     yield { role: "coder", contentHash: h, meta: { k: "coder" }, refs: [h] };
   }
   if (!has("reviewer")) {
     const body = "rev-" + String(input.steps.length);
-    const h = await putContentMerkleNode(cas, body);
+    const h = await cas.put( body);
     yield { role: "reviewer", contentHash: h, meta: { k: "reviewer" }, refs: [h] };
   }
   return { returnCode: 0, summary: "done" };

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

@@ -23,9 +23,6 @@ import { resolveThreadRecord } from "../src/thread-scan.js";
 import { addCliArgs } from "./bundle-fixture.js";
 import { ensureTestWorkflowRegistryConfig } from "./workflow-registry-fixture.js";
 
-const wfPutImport = `import { putContentMerkleNode } from "@uncaged/workflow-cas";
-`;
-
 const threadFixtureDescriptor = `export const descriptor = {
   description: "thread-cli",
   roles: {
@@ -41,25 +38,23 @@ const threadFixtureDescriptor = `export const descriptor = {
 `;
 
 const fastBundleSource = `${threadFixtureDescriptor}
-${wfPutImport}
 export const run = async function* (input, options) {
   const cas = options.cas;
-  let h = await putContentMerkleNode(cas, "plan");
+  let h = await cas.put( "plan");
   yield { role: "planner", contentHash: h, meta: { plan: input.prompt }, refs: [h] };
-  h = await putContentMerkleNode(cas, "code");
+  h = await cas.put( "code");
   yield { role: "coder", contentHash: h, meta: { diff: "y" }, refs: [h] };
   return { returnCode: 0, summary: "done" };
 };
 `;
 
 const slowPlannerBundleSource = `${threadFixtureDescriptor}
-${wfPutImport}
 export const run = async function* (input, options) {
   await new Promise((r) => setTimeout(r, 400));
   const cas = options.cas;
-  let h = await putContentMerkleNode(cas, "plan");
+  let h = await cas.put( "plan");
   yield { role: "planner", contentHash: h, meta: { plan: input.prompt }, refs: [h] };
-  h = await putContentMerkleNode(cas, "code");
+  h = await cas.put( "code");
   yield { role: "coder", contentHash: h, meta: { diff: "y" }, refs: [h] };
   return { returnCode: 0, summary: "done" };
 };
@@ -68,37 +63,34 @@ export const run = async function* (input, options) {
 const cliEntryPath = fileURLToPath(new URL("../src/cli.ts", import.meta.url));
 
 const abortablePlannerBundleSource = `${threadFixtureDescriptor}
-${wfPutImport}
 export const run = async function* (input, options) {
   const cas = options.cas;
-  let h = await putContentMerkleNode(cas, "plan");
+  let h = await cas.put( "plan");
   yield { role: "planner", contentHash: h, meta: { plan: input.prompt }, refs: [h] };
   await new Promise((r) => setTimeout(r, 10000));
-  h = await putContentMerkleNode(cas, "code");
+  h = await cas.put( "code");
   yield { role: "coder", contentHash: h, meta: { diff: "y" }, refs: [h] };
   return { returnCode: 0, summary: "done" };
 };
 `;
 
 const pauseResumeBundleSource = `${threadFixtureDescriptor}
-${wfPutImport}
 export const run = async function* (_input, options) {
   const cas = options.cas;
-  let h = await putContentMerkleNode(cas, "f");
+  let h = await cas.put( "f");
   yield { role: "first", contentHash: h, meta: {}, refs: [h] };
   await new Promise((r) => setTimeout(r, 1500));
-  h = await putContentMerkleNode(cas, "s");
+  h = await cas.put( "s");
   yield { role: "second", contentHash: h, meta: {}, refs: [h] };
   return { returnCode: 0, summary: "done" };
 };
 `;
 
 const delayedFirstYieldBundleSource = `${threadFixtureDescriptor}
-${wfPutImport}
 export const run = async function* (_input, options) {
   await new Promise((r) => setTimeout(r, 900));
   const cas = options.cas;
-  const h = await putContentMerkleNode(cas, "x");
+  const h = await cas.put( "x");
   yield { role: "only", contentHash: h, meta: {}, refs: [h] };
   return { returnCode: 0, summary: "done" };
 };
@@ -180,6 +172,9 @@ describe("cli thread commands", () => {
     }
     expect(threads.value.some((l) => l.includes(threadId))).toBe(true);
 
+    const runningPath = join(storageRoot, "logs", added.value.hash, `${threadId}.running`);
+    await waitUntilRunningFileAbsent(runningPath, 120);
+
     const shown = await cmdThreadShow(storageRoot, threadId);
     expect(shown.ok).toBe(true);
     if (!shown.ok) {

packages/cli-workflow/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uncaged/cli-workflow",
-  "version": "0.4.5",
+  "version": "0.5.0-alpha.4",
   "files": [
     "src",
     "dist",

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

@@ -3,8 +3,8 @@ import { printCliError, printCliLine } from "./cli-output.js";
 import { getCommandRegistry } from "./cli-registry.js";
 import { formatCliUsage as formatCliUsageWithGroups } from "./cli-usage.js";
 import { createCasDispatcher } from "./commands/cas/index.js";
-import { createInitDispatcher } from "./commands/init/index.js";
 import { dispatchConnect } from "./commands/connect/index.js";
+import { createInitDispatcher } from "./commands/init/index.js";
 import { dispatchSetup } from "./commands/setup/index.js";
 import { createThreadDispatcher, dispatchLive, dispatchRun } from "./commands/thread/index.js";
 import { createWorkflowDispatcher } from "./commands/workflow/index.js";

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

@@ -23,7 +23,7 @@ function requireNextArg(argv: string[], i: number, flag: string): Result<string,
 function parseConnectArgv(argv: string[]): Result<ConnectOptions, string> {
   let name = osHostname().split(".")[0].toLowerCase();
   let gatewayUrl = DEFAULT_GATEWAY_URL;
-  const gatewaySecret = process.env.WORKFLOW_GATEWAY_SECRET ?? "";
+  const gatewaySecret = process.env.WORKFLOW_DASHBOARD_SECRET ?? "";
   const stringFlags: Record<string, (v: string) => void> = {
     "--name": (v) => {
       name = v;
@@ -56,7 +56,7 @@ export async function dispatchConnect(storageRoot: string, argv: string[]): Prom
   const options = parsed.value;
 
   if (options.gatewaySecret === "") {
-    printCliLine("error: WORKFLOW_GATEWAY_SECRET is required");
+    printCliLine("error: WORKFLOW_DASHBOARD_SECRET is required");
     return 1;
   }
 

packages/cli-workflow/src/commands/connect/ws-client.ts

@@ -48,11 +48,13 @@ async function handleGatewayMessage(
   const headers = new Headers(req.headers);
   let resp: Response;
   try {
-    resp = await params.appFetch(new Request(localUrl, {
-      method: req.method,
-      headers,
-      body: req.body === null ? undefined : req.body,
-    }));
+    resp = await params.appFetch(
+      new Request(localUrl, {
+        method: req.method,
+        headers,
+        body: req.body === null ? undefined : req.body,
+      }),
+    );
   } catch (e) {
     params.log("R4N7BQ3C", `app.fetch failed: ${String(e)}`);
     const errBody: WsResponse = {

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

@@ -51,7 +51,6 @@ export const greeterRole: RoleDefinition<HelloTemplateMeta["greeter"]> = {
   description: "Says hello — replace with your first role.",
   systemPrompt: "You are a helpful assistant. Reply with one short friendly sentence.",
   schema: greeterMetaSchema,
-  extractRefs: null,
 };
 `;
 }

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

@@ -196,18 +196,13 @@ uncaged-workflow init workspace ${workspaceName}
 
 function bundleTs(): string {
   return [
-    'import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";',
+    'import { mkdir, readdir, writeFile } from "node:fs/promises";',
     'import { join } from "node:path";',
     "",
     'const rootDir = join(import.meta.dir, "..");',
     'const workflowsDir = join(rootDir, "workflows");',
     'const distDir = join(rootDir, "dist");',
     "",
-    "type JsonDeps = {",
-    "  dependencies: Record<string, string> | null;",
-    "  devDependencies: Record<string, string> | null;",
-    "};",
-    "",
     "function isEntryFile(name: string): boolean {",
     '  return name.endsWith("-entry.ts");',
     "}",
@@ -216,36 +211,6 @@ function bundleTs(): string {
     '  return name.slice(0, -".ts".length);',
     "}",
     "",
-    "async function uncagedWorkflowExternals(): Promise<string[]> {",
-    "  const names = new Set<string>();",
-    '  const paths = [join(rootDir, "package.json"), join(workflowsDir, "package.json")];',
-    "  for (const pkgPath of paths) {",
-    "    let raw: string;",
-    "    try {",
-    '      raw = await readFile(pkgPath, "utf8");',
-    "    } catch {",
-    "      continue;",
-    "    }",
-    "    const parsed = JSON.parse(raw) as JsonDeps;",
-    "    const blocks = [parsed.dependencies, parsed.devDependencies];",
-    "    for (const block of blocks) {",
-    "      if (block == null) {",
-    "        continue;",
-    "      }",
-    "      for (const key of Object.keys(block)) {",
-    '        if (key.startsWith("@uncaged/workflow")) {',
-    "          names.add(key);",
-    "        }",
-    "      }",
-    "    }",
-    "  }",
-    "  if (names.size === 0) {",
-    '    names.add("@uncaged/workflow-runtime");',
-    '    names.add("@uncaged/workflow-protocol");',
-    "  }",
-    "  return [...names];",
-    "}",
-    "",
     "async function main(): Promise<void> {",
     "  await mkdir(distDir, { recursive: true });",
     "  let files: string[];",
@@ -261,7 +226,6 @@ function bundleTs(): string {
     '    console.warn("bundle: no *-entry.ts files under workflows/");',
     "    return;",
     "  }",
-    "  const external = await uncagedWorkflowExternals();",
     "  for (const file of entries) {",
     "    const stem = entryStem(file);",
     "    const entryPath = join(workflowsDir, file);",
@@ -272,7 +236,6 @@ function bundleTs(): string {
     '      target: "node",',
     "      splitting: false,",
     '      naming: { entry: "[name].esm.js" },',
-    "      external,",
     "    });",
     "    if (!result.success) {",
     "      for (const log of result.logs) {",

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

@@ -18,13 +18,13 @@ export async function cmdThreadRemove(
     return err(`thread not found: ${threadId}`);
   }
 
-  if (resolved.source === "active") {
-    await removeThreadEntry(resolved.bundleDir, threadId);
-  } else {
-    const hist = await removeThreadHistoryEntries(resolved.bundleDir, threadId);
-    if (!hist.ok) {
-      return hist;
-    }
+  // Always clear both stores: between resolve and delete the worker may finish and
+  // move the thread from threads.json into history; branching only on resolved.source
+  // would skip history removal and leave a dangling row.
+  await removeThreadEntry(resolved.bundleDir, threadId);
+  const hist = await removeThreadHistoryEntries(resolved.bundleDir, threadId);
+  if (!hist.ok) {
+    return hist;
   }
 
   const infoPath = join(storageRoot, "logs", resolved.bundleHash, `${threadId}.info.jsonl`);

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

@@ -110,7 +110,7 @@ export async function cmdAdd(
     return validated;
   }
 
-  const extracted = await extractBundleExports(resolvedPath, { storageRoot });
+  const extracted = await extractBundleExports(resolvedPath);
   if (!extracted.ok) {
     return extracted;
   }

packages/cli-workflow/src/skill.ts

@@ -249,8 +249,7 @@ Each role has:
 |-------|------|---------|
 | \`description\` | string | What the role does |
 | \`systemPrompt\` | string | System prompt for the agent |
-| \`schema\` | ZodSchema | Validates the extracted meta |
-| \`extractRefs\` | fn or null | Extracts CAS hashes from meta for DAG linking |
+| \`schema\` | ZodSchema | Validates meta; annotate CAS hash strings with \`.meta({ casRef: true })\` for DAG linking |
 
 ## Development Workflow
 
@@ -301,13 +300,36 @@ function createLazyAdapter(): AdapterFn {
 }
 \`\`\`
 
+### Agent CLI paths: use env() with absolute path defaults
+
+Every env var in a bundle must have a sensible default — bundles must run without any env vars set. Use \`env(name, fallback)\` from \`@uncaged/workflow-util\`.
+
+Discover the correct CLI path yourself (e.g. \`which cursor-agent\`, \`which hermes\`) and hardcode it as the fallback:
+
+\`\`\`typescript
+import { env } from "@uncaged/workflow-util";
+
+// ❌ WRONG — requireEnv and optionalEnv no longer exist
+const adapter = createCursorAgent({
+  command: requireEnv("WORKFLOW_CURSOR_COMMAND", "set it"),
+  ...
+});
+
+// ✅ CORRECT — env var is an override, fallback is the discovered absolute path
+const adapter = createCursorAgent({
+  command: env("WORKFLOW_CURSOR_COMMAND", "/home/you/.local/bin/cursor-agent"),
+  model: env("WORKFLOW_CURSOR_MODEL", "auto"),
+  timeout: Number(env("WORKFLOW_CURSOR_TIMEOUT", "300000")),
+  ...
+});
+\`\`\`
+
 ### 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.
+All other dependencies — including \`@uncaged/workflow-*\` packages, zod, and any third-party code — must be bundled into the \`.esm.js\` file. Bundles are fully self-contained: same Node/Bun version = same behavior.
 
 ### No default exports
 

packages/uwf-agent-hermes/__tests__/session-detail.test.ts

@@ -0,0 +1,126 @@
+import { describe, expect, test } from "bun:test";
+import { createMemoryStore, refs, validate, walk } from "@uncaged/json-cas";
+
+import {
+  computeDurationMs,
+  extractLastAssistantContent,
+  messageToTurnPayload,
+  parseSessionIdFromStdout,
+  storeHermesSessionDetail,
+} from "../src/session-detail.js";
+import type { HermesSessionJson, HermesSessionMessage } from "../src/types.js";
+
+describe("parseSessionIdFromStdout", () => {
+  test("reads session_id from the last non-empty line", () => {
+    const stdout = "Done.\n\nsession_id: 20260518_223724_45ab80\n";
+    expect(parseSessionIdFromStdout(stdout)).toBe("20260518_223724_45ab80");
+  });
+
+  test("reads session_id from the first line (quiet mode)", () => {
+    const stdout = "session_id: 20260518_165315_3467a1\nHello world\n";
+    expect(parseSessionIdFromStdout(stdout)).toBe("20260518_165315_3467a1");
+  });
+
+  test("returns null when no session_id line present", () => {
+    expect(parseSessionIdFromStdout("only assistant text\n")).toBeNull();
+  });
+});
+
+describe("messageToTurnPayload", () => {
+  test("maps assistant tool_calls to toolCalls", () => {
+    const msg: HermesSessionMessage = {
+      role: "assistant",
+      content: "",
+      reasoning: null,
+      tool_calls: [{ function: { name: "read_file", arguments: '{"path":"x"}' } }],
+    };
+    const turn = messageToTurnPayload(msg, 0);
+    expect(turn).toEqual({
+      index: 0,
+      role: "assistant",
+      content: "",
+      toolCalls: [{ name: "read_file", args: '{"path":"x"}' }],
+      reasoning: null,
+    });
+  });
+
+  test("skips user messages", () => {
+    const msg: HermesSessionMessage = {
+      role: "user",
+      content: "hi",
+      reasoning: null,
+      tool_calls: null,
+    };
+    expect(messageToTurnPayload(msg, 0)).toBeNull();
+  });
+});
+
+describe("extractLastAssistantContent", () => {
+  test("returns the last non-empty assistant content", () => {
+    const messages: HermesSessionMessage[] = [
+      { role: "assistant", content: "first", reasoning: null, tool_calls: null },
+      { role: "tool", content: "tool output", reasoning: null, tool_calls: null },
+      { role: "assistant", content: "", reasoning: null, tool_calls: null },
+      { role: "assistant", content: "final answer", reasoning: null, tool_calls: null },
+    ];
+    expect(extractLastAssistantContent(messages)).toBe("final answer");
+  });
+});
+
+describe("computeDurationMs", () => {
+  test("computes elapsed time from session_start", () => {
+    const now = Date.parse("2026-05-18T13:32:59.028640Z");
+    const duration = computeDurationMs("2026-05-18T13:31:59.028640Z", now);
+    expect(duration).toBe(60_000);
+  });
+});
+
+describe("storeHermesSessionDetail", () => {
+  test("stores hermes-detail root with cas_ref turns walkable", async () => {
+    const session: HermesSessionJson = {
+      session_id: "20260518_133159_6a84e8",
+      model: "claude-opus-4.6",
+      session_start: "2026-05-18T13:31:59.028640",
+      messages: [
+        { role: "user", content: "task", reasoning: null, tool_calls: null },
+        {
+          role: "assistant",
+          content: "",
+          reasoning: "thinking",
+          tool_calls: [{ function: { name: "terminal", arguments: "{}" } }],
+        },
+        { role: "tool", content: "ok", reasoning: null, tool_calls: null },
+        { role: "assistant", content: "done", reasoning: null, tool_calls: null },
+      ],
+    };
+
+    const store = createMemoryStore();
+    const now = Date.parse("2026-05-18T13:32:59.028640");
+    const { detailHash, output } = await storeHermesSessionDetail(store, session, now);
+
+    expect(output).toBe("done");
+
+    const detailNode = store.get(detailHash);
+    expect(detailNode).not.toBeNull();
+    if (detailNode === null) {
+      return;
+    }
+    expect(validate(store, detailNode)).toBe(true);
+    expect(detailNode.payload).toMatchObject({
+      sessionId: "20260518_133159_6a84e8",
+      model: "claude-opus-4.6",
+      duration: 60_000,
+      turnCount: 3,
+    });
+
+    const turnRefs = refs(store, detailNode);
+    expect(turnRefs).toHaveLength(3);
+
+    const visited: string[] = [];
+    walk(store, detailHash, (hash) => visited.push(hash));
+    expect(visited).toContain(detailHash);
+    for (const turnHash of turnRefs) {
+      expect(visited).toContain(turnHash);
+    }
+  });
+});

packages/uwf-agent-hermes/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@uncaged/uwf-agent-hermes",
+  "version": "0.1.0",
+  "files": [
+    "src",
+    "dist",
+    "package.json"
+  ],
+  "type": "module",
+  "bin": {
+    "uwf-hermes": "./src/cli.ts"
+  },
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@uncaged/json-cas": "^0.3.0",
+    "@uncaged/uwf-agent-kit": "workspace:^"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

packages/uwf-agent-hermes/src/cli.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env bun
+
+import { createHermesAgent } from "./hermes.js";
+
+const main = createHermesAgent();
+void main();

packages/uwf-agent-hermes/src/hermes.ts

@@ -0,0 +1,113 @@
+import { spawn } from "node:child_process";
+
+import { type AgentContext, type AgentRunResult, createAgent } from "@uncaged/uwf-agent-kit";
+
+import {
+  loadHermesSession,
+  parseSessionIdFromStdout,
+  storeHermesRawOutput,
+  storeHermesSessionDetail,
+} from "./session-detail.js";
+
+const HERMES_COMMAND = "hermes";
+const HERMES_MAX_TURNS = 90;
+
+function buildHistorySummary(steps: AgentContext["steps"]): string {
+  if (steps.length === 0) {
+    return "";
+  }
+
+  const lines: string[] = ["## Previous Steps"];
+  for (let i = 0; i < steps.length; i++) {
+    const step = steps[i];
+    if (step === undefined) {
+      continue;
+    }
+    lines.push("");
+    lines.push(`### Step ${i + 1}: ${step.role}`);
+    lines.push(`Output: ${JSON.stringify(step.output)}`);
+    lines.push(`Agent: ${step.agent}`);
+  }
+  return lines.join("\n");
+}
+
+/** Assemble system prompt, task, and prior step outputs for Hermes. */
+export function buildHermesPrompt(ctx: AgentContext): string {
+  const roleDef = ctx.workflow.roles[ctx.role];
+  const systemPrompt = roleDef?.systemPrompt ?? "";
+  const parts: string[] = [systemPrompt, "", "## Task", ctx.start.prompt];
+  const historyBlock = buildHistorySummary(ctx.steps);
+  if (historyBlock !== "") {
+    parts.push("", historyBlock);
+  }
+  return parts.join("\n");
+}
+
+function spawnHermesChat(prompt: string): Promise<{ stdout: string; stderr: string }> {
+  return new Promise((resolve, reject) => {
+    const args = [
+      "chat",
+      "-q",
+      prompt,
+      "--yolo",
+      "--max-turns",
+      String(HERMES_MAX_TURNS),
+      "--quiet",
+    ];
+    const child = spawn(HERMES_COMMAND, args, {
+      env: process.env,
+      shell: false,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+
+    let stdout = "";
+    let stderr = "";
+    child.stdout?.on("data", (chunk: Buffer) => {
+      stdout += chunk.toString();
+    });
+    child.stderr?.on("data", (chunk: Buffer) => {
+      stderr += chunk.toString();
+    });
+
+    child.on("error", (cause) => {
+      const message = cause instanceof Error ? cause.message : String(cause);
+      reject(new Error(`hermes spawn failed: ${message}`));
+    });
+
+    child.on("close", (code) => {
+      if (code === 0) {
+        resolve({ stdout, stderr });
+        return;
+      }
+      const detail = stderr.trim() !== "" ? ` stderr=${stderr.trim()}` : "";
+      reject(new Error(`hermes exited with code ${code ?? "null"}${detail}`));
+    });
+  });
+}
+
+async function runHermes(ctx: AgentContext): Promise<AgentRunResult> {
+  const fullPrompt = buildHermesPrompt(ctx);
+  const { stdout, stderr } = await spawnHermesChat(fullPrompt);
+  const { store } = ctx;
+
+  // --quiet mode: session_id may be on stdout or stderr
+  const sessionId = parseSessionIdFromStdout(stderr) ?? parseSessionIdFromStdout(stdout);
+  if (sessionId !== null) {
+    const session = await loadHermesSession(sessionId);
+    if (session !== null) {
+      const { detailHash, output } = await storeHermesSessionDetail(store, session);
+      return { output, detailHash };
+    }
+  }
+
+  const detailHash = await storeHermesRawOutput(store, stdout);
+  return { output: stdout, detailHash };
+}
+
+/** Agent CLI factory: parses argv, runs Hermes, extracts output, writes StepNode. */
+export function createHermesAgent(): () => Promise<void> {
+  return createAgent({
+    name: "hermes",
+    run: runHermes,
+  });
+}

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

@@ -0,0 +1 @@
+export { buildHermesPrompt, createHermesAgent } from "./hermes.js";

packages/uwf-agent-hermes/src/schemas.ts

@@ -0,0 +1,57 @@
+import type { JSONSchema } from "@uncaged/json-cas";
+
+const HERMES_TOOL_CALL_SCHEMA: JSONSchema = {
+  type: "object",
+  required: ["name", "args"],
+  properties: {
+    name: { type: "string" },
+    args: { type: "string" },
+  },
+  additionalProperties: false,
+};
+
+export const HERMES_TURN_SCHEMA: JSONSchema = {
+  title: "hermes-turn",
+  type: "object",
+  required: ["index", "role", "content"],
+  properties: {
+    index: { type: "integer" },
+    role: { type: "string", enum: ["assistant", "tool"] },
+    content: { type: "string" },
+    toolCalls: {
+      anyOf: [{ type: "array", items: HERMES_TOOL_CALL_SCHEMA }, { type: "null" }],
+    },
+    reasoning: {
+      anyOf: [{ type: "string" }, { type: "null" }],
+    },
+  },
+  additionalProperties: false,
+};
+
+export const HERMES_DETAIL_SCHEMA: JSONSchema = {
+  title: "hermes-detail",
+  type: "object",
+  required: ["sessionId", "model", "duration", "turnCount", "turns"],
+  properties: {
+    sessionId: { type: "string" },
+    model: { type: "string" },
+    duration: { type: "integer" },
+    turnCount: { type: "integer" },
+    turns: {
+      type: "array",
+      items: { type: "string", format: "cas_ref" },
+    },
+  },
+  additionalProperties: false,
+};
+
+/** Fallback detail when Hermes session file is unavailable. */
+export const HERMES_RAW_OUTPUT_SCHEMA: JSONSchema = {
+  title: "hermes-raw-output",
+  type: "object",
+  required: ["text"],
+  properties: {
+    text: { type: "string" },
+  },
+  additionalProperties: false,
+};

packages/uwf-agent-hermes/src/session-detail.ts

@@ -0,0 +1,223 @@
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import { bootstrap, putSchema, type Store } from "@uncaged/json-cas";
+
+import { HERMES_DETAIL_SCHEMA, HERMES_RAW_OUTPUT_SCHEMA, HERMES_TURN_SCHEMA } from "./schemas.js";
+import type {
+  HermesDetailPayload,
+  HermesSessionJson,
+  HermesSessionMessage,
+  HermesToolCall,
+  HermesTurnPayload,
+  HermesTurnRole,
+} from "./types.js";
+
+const SESSION_ID_LINE = /^session_id:\s*(\S+)\s*$/i;
+
+export function getHermesSessionsDir(): string {
+  return join(homedir(), ".hermes", "sessions");
+}
+
+export function getHermesSessionPath(sessionId: string): string {
+  return join(getHermesSessionsDir(), `session_${sessionId}.json`);
+}
+
+/** Parse `session_id: …` from any line of Hermes stdout. */
+export function parseSessionIdFromStdout(stdout: string): string | null {
+  const lines = stdout.split(/\r?\n/);
+  for (const line of lines) {
+    const match = SESSION_ID_LINE.exec(line.trim());
+    if (match?.[1] !== undefined) {
+      return match[1];
+    }
+  }
+  return null;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function parseToolCalls(raw: unknown): HermesSessionMessage["tool_calls"] {
+  if (!Array.isArray(raw) || raw.length === 0) {
+    return null;
+  }
+  const calls: NonNullable<HermesSessionMessage["tool_calls"]> = [];
+  for (const entry of raw) {
+    if (!isRecord(entry)) {
+      continue;
+    }
+    const fn = entry.function;
+    if (!isRecord(fn)) {
+      continue;
+    }
+    const name = fn.name;
+    const args = fn.arguments;
+    if (typeof name !== "string" || typeof args !== "string") {
+      continue;
+    }
+    calls.push({ function: { name, arguments: args } });
+  }
+  return calls.length > 0 ? calls : null;
+}
+
+function normalizeMessage(raw: unknown): HermesSessionMessage | null {
+  if (!isRecord(raw)) {
+    return null;
+  }
+  const role = raw.role;
+  if (role !== "assistant" && role !== "tool" && role !== "user") {
+    return null;
+  }
+  const content = typeof raw.content === "string" ? raw.content : raw.content === null ? null : "";
+  const reasoning =
+    typeof raw.reasoning === "string"
+      ? raw.reasoning
+      : raw.reasoning === null || raw.reasoning === undefined
+        ? null
+        : null;
+  const tool_calls = parseToolCalls(raw.tool_calls);
+  return { role, content, reasoning, tool_calls };
+}
+
+function parseSessionJson(raw: unknown): HermesSessionJson | null {
+  if (!isRecord(raw)) {
+    return null;
+  }
+  const session_id = raw.session_id;
+  const model = raw.model;
+  const session_start = raw.session_start;
+  const messagesRaw = raw.messages;
+  if (
+    typeof session_id !== "string" ||
+    typeof model !== "string" ||
+    typeof session_start !== "string" ||
+    !Array.isArray(messagesRaw)
+  ) {
+    return null;
+  }
+  const messages: HermesSessionMessage[] = [];
+  for (const entry of messagesRaw) {
+    const msg = normalizeMessage(entry);
+    if (msg !== null) {
+      messages.push(msg);
+    }
+  }
+  return { session_id, model, session_start, messages };
+}
+
+export async function loadHermesSession(sessionId: string): Promise<HermesSessionJson | null> {
+  const path = getHermesSessionPath(sessionId);
+  try {
+    const text = await readFile(path, "utf8");
+    const raw = JSON.parse(text) as unknown;
+    return parseSessionJson(raw);
+  } catch {
+    return null;
+  }
+}
+
+export function computeDurationMs(sessionStart: string, nowMs: number = Date.now()): number {
+  const startMs = Date.parse(sessionStart);
+  if (Number.isNaN(startMs)) {
+    return 0;
+  }
+  return Math.max(0, nowMs - startMs);
+}
+
+function mapSessionToolCalls(
+  toolCalls: HermesSessionMessage["tool_calls"],
+): HermesToolCall[] | null {
+  if (toolCalls === null || toolCalls.length === 0) {
+    return null;
+  }
+  return toolCalls.map((call) => ({
+    name: call.function.name,
+    args: call.function.arguments,
+  }));
+}
+
+export function messageToTurnPayload(
+  message: HermesSessionMessage,
+  index: number,
+): HermesTurnPayload | null {
+  if (message.role !== "assistant" && message.role !== "tool") {
+    return null;
+  }
+  const role = message.role as HermesTurnRole;
+  return {
+    index,
+    role,
+    content: message.content ?? "",
+    toolCalls: mapSessionToolCalls(message.tool_calls),
+    reasoning: message.reasoning,
+  };
+}
+
+/** Last assistant message with non-empty text content (walks backward). */
+export function extractLastAssistantContent(messages: HermesSessionMessage[]): string {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const msg = messages[i];
+    if (msg === undefined) {
+      continue;
+    }
+    if (msg.role === "assistant" && msg.content !== null && msg.content.trim() !== "") {
+      return msg.content;
+    }
+  }
+  return "";
+}
+
+type HermesSchemaHashes = {
+  turn: string;
+  detail: string;
+  rawOutput: string;
+};
+
+async function registerHermesSchemas(store: Store): Promise<HermesSchemaHashes> {
+  await bootstrap(store);
+  const [turn, detail, rawOutput] = await Promise.all([
+    putSchema(store, HERMES_TURN_SCHEMA),
+    putSchema(store, HERMES_DETAIL_SCHEMA),
+    putSchema(store, HERMES_RAW_OUTPUT_SCHEMA),
+  ]);
+  return { turn, detail, rawOutput };
+}
+
+export async function storeHermesSessionDetail(
+  store: Store,
+  session: HermesSessionJson,
+  nowMs: number = Date.now(),
+): Promise<{ detailHash: string; output: string }> {
+  const schemas = await registerHermesSchemas(store);
+  const turnHashes: string[] = [];
+  let turnIndex = 0;
+
+  for (const message of session.messages) {
+    const turn = messageToTurnPayload(message, turnIndex);
+    if (turn === null) {
+      continue;
+    }
+    const hash = await store.put(schemas.turn, turn);
+    turnHashes.push(hash);
+    turnIndex += 1;
+  }
+
+  const detail: HermesDetailPayload = {
+    sessionId: session.session_id,
+    model: session.model,
+    duration: computeDurationMs(session.session_start, nowMs),
+    turnCount: turnHashes.length,
+    turns: turnHashes,
+  };
+  const detailHash = await store.put(schemas.detail, detail);
+  const output = extractLastAssistantContent(session.messages);
+  return { detailHash, output };
+}
+
+export async function storeHermesRawOutput(store: Store, rawOutput: string): Promise<string> {
+  const schemas = await registerHermesSchemas(store);
+  return store.put(schemas.rawOutput, { text: rawOutput });
+}

packages/uwf-agent-hermes/src/types.ts

@@ -0,0 +1,43 @@
+export type HermesTurnRole = "assistant" | "tool";
+
+export type HermesToolCall = {
+  name: string;
+  args: string;
+};
+
+export type HermesTurnPayload = {
+  index: number;
+  role: HermesTurnRole;
+  content: string;
+  toolCalls: HermesToolCall[] | null;
+  reasoning: string | null;
+};
+
+export type HermesDetailPayload = {
+  sessionId: string;
+  model: string;
+  duration: number;
+  turnCount: number;
+  turns: string[];
+};
+
+export type HermesSessionToolCall = {
+  function: {
+    name: string;
+    arguments: string;
+  };
+};
+
+export type HermesSessionMessage = {
+  role: string;
+  content: string | null;
+  tool_calls: HermesSessionToolCall[] | null;
+  reasoning: string | null;
+};
+
+export type HermesSessionJson = {
+  session_id: string;
+  model: string;
+  session_start: string;
+  messages: HermesSessionMessage[];
+};

packages/uwf-agent-hermes/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "include": ["src"],
+  "references": [{ "path": "../uwf-agent-kit" }]
+}

packages/uwf-agent-kit/__tests__/build-output-format-instruction.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, test } from "vitest";
+
+import { buildOutputFormatInstruction } from "../src/build-output-format-instruction.js";
+
+describe("buildOutputFormatInstruction", () => {
+  test("always includes the frontmatter example block", () => {
+    const result = buildOutputFormatInstruction({});
+    expect(result).toContain("---");
+    expect(result).toContain("status: done");
+    expect(result).toContain("confidence:");
+    expect(result).toContain("scope: role");
+  });
+
+  test("always marks frontmatter as the primary deliverable", () => {
+    const result = buildOutputFormatInstruction({});
+    expect(result).toContain("primary deliverable");
+  });
+
+  test("lists fields from a flat object schema", () => {
+    const schema = {
+      type: "object",
+      properties: {
+        status: { type: "string" },
+        confidence: { type: "number" },
+      },
+    };
+    const result = buildOutputFormatInstruction(schema);
+    expect(result).toContain("`status`");
+    expect(result).toContain("`confidence`");
+  });
+
+  test("lists union of fields from an anyOf schema", () => {
+    const schema = {
+      anyOf: [
+        {
+          type: "object",
+          properties: { alpha: { type: "string" } },
+        },
+        {
+          type: "object",
+          properties: { beta: { type: "number" } },
+        },
+      ],
+    };
+    const result = buildOutputFormatInstruction(schema);
+    expect(result).toContain("`alpha`");
+    expect(result).toContain("`beta`");
+  });
+
+  test("lists union of fields from a oneOf schema", () => {
+    const schema = {
+      oneOf: [
+        {
+          type: "object",
+          properties: { foo: { type: "string" } },
+        },
+        {
+          type: "object",
+          properties: { bar: { type: "boolean" } },
+        },
+      ],
+    };
+    const result = buildOutputFormatInstruction(schema);
+    expect(result).toContain("`foo`");
+    expect(result).toContain("`bar`");
+  });
+
+  test("falls back gracefully for a non-object schema with no properties", () => {
+    const result = buildOutputFormatInstruction({ type: "string" });
+    expect(result).toContain("schema fields will be extracted automatically");
+  });
+
+  test("does not list a field more than once for a union with overlapping keys", () => {
+    const schema = {
+      anyOf: [
+        { type: "object", properties: { shared: { type: "string" } } },
+        { type: "object", properties: { shared: { type: "number" } } },
+      ],
+    };
+    const result = buildOutputFormatInstruction(schema);
+    const matches = [...result.matchAll(/`shared`/g)];
+    expect(matches.length).toBe(1);
+  });
+
+  test("includes focus reminder about role scope", () => {
+    const result = buildOutputFormatInstruction({});
+    expect(result).toContain("Focus exclusively on YOUR role");
+  });
+});

packages/uwf-agent-kit/__tests__/frontmatter-fast-path.test.ts

@@ -0,0 +1,136 @@
+import { describe, expect, test } from "vitest";
+
+import { createMemoryStore, putSchema } from "@uncaged/json-cas";
+
+import { tryFrontmatterFastPath } from "../src/frontmatter.js";
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+/** JSON Schema that exactly matches the AgentFrontmatter fields. */
+const FRONTMATTER_SCHEMA = {
+  type: "object",
+  properties: {
+    status: { anyOf: [{ type: "string" }, { type: "null" }] },
+    next: { anyOf: [{ type: "string" }, { type: "null" }] },
+    confidence: { anyOf: [{ type: "number" }, { type: "null" }] },
+    artifacts: { type: "array", items: { type: "string" } },
+    scope: { type: "string" },
+  },
+  required: ["status", "next", "confidence", "artifacts", "scope"],
+  additionalProperties: false,
+};
+
+/** JSON Schema that requires a non-frontmatter field — fast path must not satisfy it. */
+const STRICT_SCHEMA = {
+  type: "object",
+  properties: {
+    requiredField: { type: "string" },
+  },
+  required: ["requiredField"],
+  additionalProperties: false,
+};
+
+async function makeStoreWithSchema(schema: Record<string, unknown>) {
+  const store = createMemoryStore();
+  const schemaHash = await putSchema(store, schema);
+  return { store, schemaHash };
+}
+
+// ── Happy path ─────────────────────────────────────────────────────────────────
+
+describe("tryFrontmatterFastPath — happy path", () => {
+  test("parses valid frontmatter and returns outputHash + stripped body", async () => {
+    const { store, schemaHash } = await makeStoreWithSchema(FRONTMATTER_SCHEMA);
+
+    const raw = [
+      "---",
+      "status: done",
+      "next: reviewer",
+      "confidence: 0.9",
+      "artifacts: [src/foo.ts]",
+      "scope: role",
+      "---",
+      "",
+      "## Summary",
+      "Work is complete.",
+    ].join("\n");
+
+    const result = await tryFrontmatterFastPath(raw, schemaHash, store);
+
+    expect(result).not.toBeNull();
+    expect(result?.body).toContain("## Summary");
+    expect(result?.body).toContain("Work is complete.");
+    expect(result?.body).not.toContain("status: done");
+    expect(typeof result?.outputHash).toBe("string");
+    expect((result?.outputHash ?? "").length).toBeGreaterThan(0);
+  });
+
+  test("stored CAS node payload matches frontmatter fields", async () => {
+    const { store, schemaHash } = await makeStoreWithSchema(FRONTMATTER_SCHEMA);
+
+    const raw = "---\nstatus: done\nnext: null\nconfidence: null\nartifacts: []\nscope: role\n---\n\nBody.";
+
+    const result = await tryFrontmatterFastPath(raw, schemaHash, store);
+    expect(result).not.toBeNull();
+
+    const node = store.get(result!.outputHash);
+    expect(node).not.toBeNull();
+    const payload = node!.payload as Record<string, unknown>;
+    expect(payload.status).toBe("done");
+    expect(payload.next).toBeNull();
+    expect(payload.confidence).toBeNull();
+    expect(payload.artifacts).toEqual([]);
+    expect(payload.scope).toBe("role");
+  });
+});
+
+// ── Fallback: no frontmatter ───────────────────────────────────────────────────
+
+describe("tryFrontmatterFastPath — fallback: no frontmatter", () => {
+  test("returns null for plain markdown without frontmatter block", async () => {
+    const { store, schemaHash } = await makeStoreWithSchema(FRONTMATTER_SCHEMA);
+
+    const result = await tryFrontmatterFastPath(
+      "This is plain markdown without any frontmatter.",
+      schemaHash,
+      store,
+    );
+
+    expect(result).toBeNull();
+  });
+});
+
+// ── Fallback: invalid frontmatter ─────────────────────────────────────────────
+
+describe("tryFrontmatterFastPath — fallback: invalid frontmatter", () => {
+  test("returns null when confidence is out of range [0, 1]", async () => {
+    const { store, schemaHash } = await makeStoreWithSchema(FRONTMATTER_SCHEMA);
+
+    const raw = "---\nstatus: done\nconfidence: 1.5\nscope: role\n---\n\nBody.";
+
+    const result = await tryFrontmatterFastPath(raw, schemaHash, store);
+    expect(result).toBeNull();
+  });
+
+  test("returns null when next contains whitespace", async () => {
+    const { store, schemaHash } = await makeStoreWithSchema(FRONTMATTER_SCHEMA);
+
+    const raw = "---\nstatus: done\nnext: some role\nscope: role\n---\n\nBody.";
+
+    const result = await tryFrontmatterFastPath(raw, schemaHash, store);
+    expect(result).toBeNull();
+  });
+});
+
+// ── Fallback: schema mismatch ─────────────────────────────────────────────────
+
+describe("tryFrontmatterFastPath — fallback: schema mismatch", () => {
+  test("returns null when outputSchema requires fields not in frontmatter", async () => {
+    const { store, schemaHash } = await makeStoreWithSchema(STRICT_SCHEMA);
+
+    const raw = "---\nstatus: done\nscope: role\n---\n\nBody.";
+
+    const result = await tryFrontmatterFastPath(raw, schemaHash, store);
+    expect(result).toBeNull();
+  });
+});

packages/uwf-agent-kit/__tests__/resolve-extract-model.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, test } from "bun:test";
+import type { WorkflowConfig } from "@uncaged/uwf-protocol";
+import { resolveExtractModelAlias } from "../src/extract.js";
+
+function baseConfig(overrides: Partial<WorkflowConfig> = {}): WorkflowConfig {
+  return {
+    providers: {},
+    models: {
+      sonnet: { provider: "openrouter", name: "anthropic/claude-sonnet-4" },
+      "gpt4o-mini": { provider: "openai", name: "gpt-4o-mini" },
+    },
+    agents: {},
+    defaultAgent: "hermes",
+    agentOverrides: null,
+    defaultModel: "sonnet",
+    modelOverrides: null,
+    ...overrides,
+  };
+}
+
+describe("resolveExtractModelAlias", () => {
+  test("uses modelOverrides.extract when set", () => {
+    const config = baseConfig({
+      modelOverrides: { extract: "gpt4o-mini" },
+    });
+    expect(resolveExtractModelAlias(config)).toBe("gpt4o-mini");
+  });
+
+  test("falls back to models.extract alias when present", () => {
+    const config = baseConfig({
+      models: {
+        extract: { provider: "openai", name: "gpt-4o-mini" },
+        sonnet: { provider: "openrouter", name: "anthropic/claude-sonnet-4" },
+      },
+    });
+    expect(resolveExtractModelAlias(config)).toBe("extract");
+  });
+
+  test("falls back to defaultModel", () => {
+    expect(resolveExtractModelAlias(baseConfig())).toBe("sonnet");
+  });
+});

packages/uwf-agent-kit/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@uncaged/uwf-agent-kit",
+  "version": "0.1.0",
+  "files": [
+    "src",
+    "dist",
+    "package.json"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@uncaged/json-cas": "^0.3.0",
+    "@uncaged/json-cas-fs": "^0.3.0",
+    "@uncaged/uwf-protocol": "workspace:^",
+    "@uncaged/workflow-util": "workspace:^",
+    "dotenv": "^16.6.1",
+    "yaml": "^2.8.4"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

packages/uwf-agent-kit/src/build-output-format-instruction.ts

@@ -0,0 +1,75 @@
+import type { JSONSchema } from "@uncaged/json-cas";
+
+/**
+ * Extract top-level property names from a JSON Schema object.
+ *
+ * Handles:
+ * - Object schemas with a `properties` key
+ * - Union schemas via `anyOf` / `oneOf` — union of all variant property names
+ *
+ * Returns an empty array for schemas with no inspectable property definitions.
+ */
+function extractSchemaFields(schema: JSONSchema): string[] {
+  if (typeof schema.properties === "object" && schema.properties !== null) {
+    return Object.keys(schema.properties as Record<string, unknown>);
+  }
+
+  const unionKey = Array.isArray(schema.anyOf)
+    ? "anyOf"
+    : Array.isArray(schema.oneOf)
+      ? "oneOf"
+      : null;
+
+  if (unionKey !== null) {
+    const variants = schema[unionKey] as JSONSchema[];
+    const fieldSet = new Set<string>();
+    for (const variant of variants) {
+      for (const field of extractSchemaFields(variant)) {
+        fieldSet.add(field);
+      }
+    }
+    return [...fieldSet];
+  }
+
+  return [];
+}
+
+/**
+ * Build a concise output format instruction block for an agent role.
+ *
+ * The instruction describes the expected frontmatter markdown format and lists
+ * the meta fields derived from the JSON Schema.  It is prepended to the agent's
+ * system prompt so the deliverable format is the first thing the agent sees.
+ */
+export function buildOutputFormatInstruction(schema: JSONSchema): string {
+  const fields = extractSchemaFields(schema);
+
+  const fieldList =
+    fields.length > 0
+      ? fields.map((f) => `  - \`${f}\``).join("\n")
+      : "  (schema fields will be extracted automatically)";
+
+  return `## Deliverable Format
+
+Your response MUST begin with a YAML frontmatter block followed by your markdown work:
+
+\`\`\`
+---
+status: done          # done | needs_input | in_progress | failed
+next: <role-name>     # suggested next role, or omit
+confidence: 0.9       # 0.0–1.0, your self-assessed confidence
+artifacts:            # list of file paths or CAS hashes you produced
+  - path/to/file.ts
+scope: role           # role | thread
+---
+
+... your markdown work here ...
+\`\`\`
+
+The frontmatter is the **primary deliverable** — the engine reads it directly.
+Your meta output must satisfy these fields:
+
+${fieldList}
+
+Focus exclusively on YOUR role's deliverable. Do not perform actions outside your role's scope.`;
+}

packages/uwf-agent-kit/src/context.ts

@@ -0,0 +1,203 @@
+import type { Store } from "@uncaged/json-cas";
+import type {
+  CasRef,
+  StartNodePayload,
+  StepContext,
+  StepNodePayload,
+  ThreadId,
+} from "@uncaged/uwf-protocol";
+import { createAgentStore, loadThreadsIndex, resolveStorageRoot } from "./storage.js";
+import type { AgentStore } from "./storage.js";
+import type { AgentContext } from "./types.js";
+
+type ChainState = {
+  startHash: CasRef;
+  start: StartNodePayload;
+  stepsNewestFirst: StepNodePayload[];
+  headIsStart: boolean;
+};
+
+function fail(message: string): never {
+  throw new Error(message);
+}
+
+function walkChain(
+  store: Store,
+  schemas: AgentStore["schemas"],
+  headHash: CasRef,
+): ChainState {
+  const headNode = store.get(headHash);
+  if (headNode === null) {
+    fail(`CAS node not found: ${headHash}`);
+  }
+
+  if (headNode.type === schemas.startNode) {
+    return {
+      startHash: headHash,
+      start: headNode.payload as StartNodePayload,
+      stepsNewestFirst: [],
+      headIsStart: true,
+    };
+  }
+
+  if (headNode.type !== schemas.stepNode) {
+    fail(`head ${headHash} is not a StartNode or StepNode`);
+  }
+
+  const stepsNewestFirst: StepNodePayload[] = [];
+  let hash: CasRef | null = headHash;
+
+  while (hash !== null) {
+    const node = store.get(hash);
+    if (node === null) {
+      fail(`CAS node not found while walking chain: ${hash}`);
+    }
+    if (node.type !== schemas.stepNode) {
+      break;
+    }
+    const payload = node.payload as StepNodePayload;
+    stepsNewestFirst.push(payload);
+    hash = payload.prev;
+  }
+
+  const newest = stepsNewestFirst[0];
+  if (newest === undefined) {
+    fail(`empty step chain at head ${headHash}`);
+  }
+
+  const startNode = store.get(newest.start);
+  if (startNode === null || startNode.type !== schemas.startNode) {
+    fail(`StartNode not found: ${newest.start}`);
+  }
+
+  return {
+    startHash: newest.start,
+    start: startNode.payload as StartNodePayload,
+    stepsNewestFirst,
+    headIsStart: false,
+  };
+}
+
+function expandOutput(
+  store: Store,
+  outputRef: CasRef,
+): unknown {
+  const node = store.get(outputRef);
+  if (node === null) {
+    return {};
+  }
+  return node.payload;
+}
+
+async function buildHistory(
+  store: Store,
+  stepsNewestFirst: StepNodePayload[],
+): Promise<StepContext[]> {
+  const chronological = [...stepsNewestFirst].reverse();
+  const history: StepContext[] = [];
+  for (const step of chronological) {
+    history.push({
+      role: step.role,
+      output: expandOutput(store, step.output),
+      detail: step.detail,
+      agent: step.agent,
+    });
+  }
+  return history;
+}
+
+async function loadWorkflow(
+  store: Store,
+  schemas: AgentStore["schemas"],
+  workflowRef: CasRef,
+) {
+  const node = store.get(workflowRef);
+  if (node === null) {
+    fail(`workflow CAS node not found: ${workflowRef}`);
+  }
+  if (node.type !== schemas.workflow) {
+    fail(`node ${workflowRef} is not a Workflow`);
+  }
+  return node.payload as AgentContext["workflow"];
+}
+
+/**
+ * Build agent execution context from thread head in threads.yaml.
+ * Walks the CAS chain from head to StartNode and expands step outputs.
+ */
+export async function buildContext(threadId: ThreadId, role: string): Promise<AgentContext> {
+  const storageRoot = resolveStorageRoot();
+  const agentStore = await createAgentStore(storageRoot);
+  const { store, schemas } = agentStore;
+
+  const index = await loadThreadsIndex(storageRoot);
+  const headHash = index[threadId];
+  if (headHash === undefined) {
+    fail(`thread not found in threads.yaml: ${threadId}`);
+  }
+
+  const chain = walkChain(store, schemas, headHash);
+  const workflow = await loadWorkflow(store, schemas, chain.start.workflow);
+  const roleDef = workflow.roles[role];
+  if (roleDef === undefined) {
+    fail(`unknown role "${role}" in workflow "${workflow.name}"`);
+  }
+
+  const steps = await buildHistory(store, chain.stepsNewestFirst);
+
+  return {
+    threadId,
+    role,
+    start: chain.start,
+    steps,
+    workflow,
+    store,
+    outputFormatInstruction: "",
+  };
+}
+
+export type BuildContextMeta = {
+  storageRoot: string;
+  store: Store;
+  schemas: AgentStore["schemas"];
+  headHash: CasRef;
+  chain: ChainState;
+};
+
+/**
+ * Same as {@link buildContext} but also returns chain metadata for writing the next StepNode.
+ */
+export async function buildContextWithMeta(
+  threadId: ThreadId,
+  role: string,
+): Promise<AgentContext & { meta: BuildContextMeta }> {
+  const storageRoot = resolveStorageRoot();
+  const agentStore = await createAgentStore(storageRoot);
+  const { store, schemas } = agentStore;
+
+  const index = await loadThreadsIndex(storageRoot);
+  const headHash = index[threadId];
+  if (headHash === undefined) {
+    fail(`thread not found in threads.yaml: ${threadId}`);
+  }
+
+  const chain = walkChain(store, schemas, headHash);
+  const workflow = await loadWorkflow(store, schemas, chain.start.workflow);
+  const roleDef = workflow.roles[role];
+  if (roleDef === undefined) {
+    fail(`unknown role "${role}" in workflow "${workflow.name}"`);
+  }
+
+  const steps = await buildHistory(store, chain.stepsNewestFirst);
+
+  return {
+    threadId,
+    role,
+    start: chain.start,
+    steps,
+    workflow,
+    store,
+    outputFormatInstruction: "",
+    meta: { storageRoot, store, schemas, headHash, chain },
+  };
+}

packages/uwf-agent-kit/src/extract.ts

@@ -0,0 +1,181 @@
+import { getSchema, validate } from "@uncaged/json-cas";
+
+import type { CasRef, ModelAlias, WorkflowConfig } from "@uncaged/uwf-protocol";
+import { config as loadDotenv } from "dotenv";
+import { createAgentStore, getEnvPath, resolveStorageRoot } from "./storage.js";
+
+export type ResolvedLlmProvider = {
+  baseUrl: string;
+  apiKey: string;
+  model: string;
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Resolve model alias for extract: modelOverrides.extract → models.extract → defaultModel. */
+export function resolveExtractModelAlias(config: WorkflowConfig): ModelAlias {
+  const fromOverride = config.modelOverrides?.extract ?? null;
+  if (fromOverride !== null) {
+    return fromOverride;
+  }
+  if (config.models.extract !== undefined) {
+    return "extract";
+  }
+  if (config.models.default !== undefined) {
+    return "default";
+  }
+  return config.defaultModel;
+}
+
+export function resolveModel(config: WorkflowConfig, alias: ModelAlias): ResolvedLlmProvider {
+  const modelEntry = config.models[alias];
+  if (modelEntry === undefined) {
+    throw new Error(`unknown model alias: ${alias}`);
+  }
+  const providerEntry = config.providers[modelEntry.provider];
+  if (providerEntry === undefined) {
+    throw new Error(`unknown provider "${modelEntry.provider}" for model "${alias}"`);
+  }
+  const apiKey = process.env[providerEntry.apiKeyEnv];
+  if (apiKey === undefined || apiKey === "") {
+    throw new Error(`missing API key env var: ${providerEntry.apiKeyEnv}`);
+  }
+  return {
+    baseUrl: providerEntry.baseUrl,
+    apiKey,
+    model: modelEntry.name,
+  };
+}
+
+function chatUrl(baseUrl: string): string {
+  const trimmed = baseUrl.replace(/\/+$/, "");
+  return `${trimmed}/chat/completions`;
+}
+
+function extractJsonFromAssistantText(text: string): unknown {
+  const trimmed = text.trim();
+  const fenceMatch = /^```(?:json)?\s*([\s\S]*?)```$/m.exec(trimmed);
+  const candidate = fenceMatch !== null ? fenceMatch[1].trim() : trimmed;
+  return JSON.parse(candidate) as unknown;
+}
+
+function parseAssistantText(parsed: unknown): string {
+  if (!isRecord(parsed)) {
+    throw new Error("LLM response is not an object");
+  }
+  const choices = parsed.choices;
+  if (!Array.isArray(choices) || choices.length === 0) {
+    throw new Error("LLM response has no choices");
+  }
+  const c0 = choices[0];
+  if (!isRecord(c0)) {
+    throw new Error("LLM choice is not an object");
+  }
+  const messageObj = c0.message;
+  if (!isRecord(messageObj)) {
+    throw new Error("LLM message is not an object");
+  }
+  const content = messageObj.content;
+  if (typeof content !== "string") {
+    throw new Error("LLM message has no text content");
+  }
+  return content;
+}
+
+async function chatCompletionText(
+  provider: ResolvedLlmProvider,
+  messages: Array<{ role: "system" | "user"; content: string }>,
+): Promise<string> {
+  let response: Response;
+  try {
+    response = await fetch(chatUrl(provider.baseUrl), {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${provider.apiKey}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        model: provider.model,
+        messages,
+        response_format: { type: "json_object" },
+      }),
+    });
+  } catch (cause) {
+    const message = cause instanceof Error ? cause.message : String(cause);
+    throw new Error(`LLM network error: ${message}`);
+  }
+
+  const responseText = await response.text();
+  if (!response.ok) {
+    throw new Error(`LLM HTTP ${response.status}: ${responseText.slice(0, 2000)}`);
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(responseText) as unknown;
+  } catch (cause) {
+    const message = cause instanceof Error ? cause.message : String(cause);
+    throw new Error(`LLM invalid JSON response: ${message}`);
+  }
+
+  return parseAssistantText(parsed);
+}
+
+export type ExtractResult = {
+  value: unknown;
+  hash: CasRef;
+};
+
+/**
+ * Call an OpenAI-compatible LLM to extract structured output matching outputSchema.
+ * Loads config.yaml and .env from the workflow storage root.
+ */
+export async function extract(
+  rawOutput: string,
+  outputSchema: CasRef,
+  config: WorkflowConfig,
+): Promise<ExtractResult> {
+  const storageRoot = resolveStorageRoot();
+  loadDotenv({ path: getEnvPath(storageRoot) });
+
+  const { store } = await createAgentStore(storageRoot);
+  const schema = getSchema(store, outputSchema);
+  if (schema === null) {
+    throw new Error(`output schema not found in CAS: ${outputSchema}`);
+  }
+
+  const modelAlias = resolveExtractModelAlias(config);
+  const provider = resolveModel(config, modelAlias);
+
+  const schemaText = JSON.stringify(schema, null, 2);
+  const assistantText = await chatCompletionText(provider, [
+    {
+      role: "system",
+      content:
+        "Extract structured data from the agent output. Reply with a single JSON object only, no markdown or prose. The JSON must validate against this JSON Schema:\n" +
+        schemaText,
+    },
+    {
+      role: "user",
+      content: rawOutput,
+    },
+  ]);
+
+  let structured: unknown;
+  try {
+    structured = extractJsonFromAssistantText(assistantText);
+  } catch (cause) {
+    const message = cause instanceof Error ? cause.message : String(cause);
+    throw new Error(`failed to parse extracted JSON: ${message}`);
+  }
+
+  const outputHash = await store.put(outputSchema, structured);
+  const node = store.get(outputHash);
+  if (node === null || !validate(store, node)) {
+    throw new Error("extracted output failed JSON Schema validation");
+  }
+
+  return { value: structured, hash: outputHash };
+}

packages/uwf-agent-kit/src/frontmatter.ts

@@ -0,0 +1,61 @@
+import { validate } from "@uncaged/json-cas";
+import type { Store } from "@uncaged/json-cas";
+import type { CasRef } from "@uncaged/uwf-protocol";
+import { parseFrontmatterMarkdown, validateFrontmatter } from "@uncaged/workflow-util";
+
+export type FrontmatterFastPathResult = {
+  body: string;
+  outputHash: CasRef;
+};
+
+/**
+ * Try to satisfy `outputSchema` from frontmatter fields alone.
+ *
+ * Returns a result containing the stored CAS hash and stripped body on success,
+ * or `null` when frontmatter is absent, invalid, or does not satisfy the schema.
+ * Never throws.
+ *
+ * The candidate object is put into the real CAS store (idempotent content-addressed
+ * write) and validated against the output schema.  If validation fails the node
+ * is orphaned — it will be GC'd on the next collection pass.
+ */
+export async function tryFrontmatterFastPath(
+  raw: string,
+  outputSchema: CasRef,
+  store: Store,
+): Promise<FrontmatterFastPathResult | null> {
+  const { frontmatter, body } = parseFrontmatterMarkdown(raw);
+
+  if (frontmatter === null) {
+    return null;
+  }
+
+  const validationErrors = validateFrontmatter(frontmatter);
+  if (validationErrors.length > 0) {
+    return null;
+  }
+
+  const candidate: Record<string, unknown> = {
+    status: frontmatter.status,
+    next: frontmatter.next,
+    confidence: frontmatter.confidence,
+    artifacts: [...frontmatter.artifacts],
+    scope: frontmatter.scope,
+  };
+
+  let outputHash: CasRef;
+  let node: ReturnType<Store["get"]>;
+
+  try {
+    outputHash = await store.put(outputSchema, candidate);
+    node = store.get(outputHash);
+  } catch {
+    return null;
+  }
+
+  if (node === null || !validate(store, node)) {
+    return null;
+  }
+
+  return { body, outputHash };
+}

packages/uwf-agent-kit/src/index.ts

@@ -0,0 +1,14 @@
+export type { BuildContextMeta } from "./context.js";
+export { buildContext, buildContextWithMeta } from "./context.js";
+export type { ExtractResult, ResolvedLlmProvider } from "./extract.js";
+export {
+  extract,
+  resolveExtractModelAlias,
+  resolveModel,
+} from "./extract.js";
+export { buildOutputFormatInstruction } from "./build-output-format-instruction.js";
+export type { FrontmatterFastPathResult } from "./frontmatter.js";
+export { tryFrontmatterFastPath } from "./frontmatter.js";
+export { createAgent } from "./run.js";
+export { getConfigPath, getEnvPath, loadWorkflowConfig } from "./storage.js";
+export type { AgentContext, AgentOptions, AgentRunFn, AgentRunResult } from "./types.js";

packages/uwf-agent-kit/src/run.ts

@@ -0,0 +1,150 @@
+import { getSchema, validate } from "@uncaged/json-cas";
+import type { CasRef, StepNodePayload, ThreadId } from "@uncaged/uwf-protocol";
+import { config as loadDotenv } from "dotenv";
+
+import { buildContextWithMeta } from "./context.js";
+import { buildOutputFormatInstruction } from "./build-output-format-instruction.js";
+import { extract } from "./extract.js";
+import { tryFrontmatterFastPath } from "./frontmatter.js";
+import type { AgentStore } from "./storage.js";
+import { getEnvPath, loadWorkflowConfig, resolveStorageRoot } from "./storage.js";
+import type { AgentContext, AgentOptions, AgentRunResult } from "./types.js";
+
+function fail(message: string): never {
+  process.stderr.write(`${message}\n`);
+  process.exit(1);
+}
+
+function agentLabel(name: string): string {
+  if (name.startsWith("uwf-")) {
+    return name;
+  }
+  return `uwf-${name}`;
+}
+
+function parseArgv(argv: string[]): { threadId: ThreadId; role: string } {
+  const threadId = argv[2];
+  const role = argv[3];
+  if (threadId === undefined || threadId === "") {
+    fail("usage: <agent-cli> <thread-id> <role>");
+  }
+  if (role === undefined || role === "") {
+    fail("usage: <agent-cli> <thread-id> <role>");
+  }
+  return { threadId: threadId as ThreadId, role };
+}
+
+function runWithMessage<T>(label: string, fn: () => Promise<T>): Promise<T> {
+  return fn().catch((e: unknown) => {
+    const message = e instanceof Error ? e.message : String(e);
+    fail(`${label}: ${message}`);
+  });
+}
+
+async function writeStepNode(options: {
+  store: AgentStore["store"];
+  schemas: AgentStore["schemas"];
+  startHash: CasRef;
+  prevHash: CasRef | null;
+  role: string;
+  outputHash: CasRef;
+  detailHash: CasRef;
+  agentName: string;
+}): Promise<CasRef> {
+  const payload: StepNodePayload = {
+    start: options.startHash,
+    prev: options.prevHash,
+    role: options.role,
+    output: options.outputHash,
+    detail: options.detailHash,
+    agent: options.agentName,
+  };
+  const hash = await options.store.put(options.schemas.stepNode, payload);
+  const node = options.store.get(hash);
+  if (node === null || !validate(options.store, node)) {
+    fail("stored StepNode failed schema validation");
+  }
+  return hash;
+}
+
+async function runAgent(options: AgentOptions, ctx: AgentContext): Promise<AgentRunResult> {
+  return runWithMessage("agent run failed", () => options.run(ctx));
+}
+
+async function extractOutput(
+  rawOutput: string,
+  outputSchema: CasRef,
+  storageRoot: string,
+  ctx: Awaited<ReturnType<typeof buildContextWithMeta>>,
+): Promise<CasRef> {
+  const fastPath = await runWithMessage("frontmatter fast path", () =>
+    tryFrontmatterFastPath(rawOutput, outputSchema, ctx.meta.store),
+  ).catch(() => null);
+
+  if (fastPath !== null) {
+    return fastPath.outputHash;
+  }
+
+  const config = await runWithMessage("failed to load config", () =>
+    loadWorkflowConfig(storageRoot),
+  );
+  const extracted = await runWithMessage("extract failed", () =>
+    extract(rawOutput, outputSchema, config),
+  );
+  return extracted.hash;
+}
+
+async function persistStep(options: {
+  ctx: Awaited<ReturnType<typeof buildContextWithMeta>>;
+  outputHash: CasRef;
+  detailHash: CasRef;
+  agentName: string;
+}): Promise<CasRef> {
+  const { store, schemas, chain, headHash } = options.ctx.meta;
+  return writeStepNode({
+    store,
+    schemas,
+    startHash: chain.startHash,
+    prevHash: chain.headIsStart ? null : headHash,
+    role: options.ctx.role,
+    outputHash: options.outputHash,
+    detailHash: options.detailHash,
+    agentName: options.agentName,
+  });
+}
+
+/**
+ * Create an agent CLI entrypoint.
+ * Parses argv (`<thread-id> <role>`), runs the agent, extracts structured output,
+ * writes StepNode to CAS, and prints the new node hash to stdout.
+ */
+export function createAgent(options: AgentOptions): () => Promise<void> {
+  return async function main(): Promise<void> {
+    const { threadId, role } = parseArgv(process.argv);
+    const storageRoot = resolveStorageRoot();
+    loadDotenv({ path: getEnvPath(storageRoot) });
+
+    const ctx = await runWithMessage("context", () => buildContextWithMeta(threadId, role));
+
+    const roleDef = ctx.workflow.roles[role];
+    if (roleDef === undefined) {
+      fail(`unknown role: ${role}`);
+    }
+
+    const outputSchema = getSchema(ctx.meta.store, roleDef.outputSchema);
+    if (outputSchema !== null) {
+      ctx.outputFormatInstruction = buildOutputFormatInstruction(outputSchema);
+    }
+
+    const agentResult = await runAgent(options, ctx);
+    const outputHash = await extractOutput(agentResult.output, roleDef.outputSchema, storageRoot, ctx);
+    const stepHash = await persistStep({
+      ctx,
+      outputHash,
+      detailHash: agentResult.detailHash,
+      agentName: agentLabel(options.name),
+    });
+
+    process.stdout.write(`${stepHash}\n`);
+  };
+}

packages/uwf-agent-kit/src/schemas.ts

@@ -0,0 +1,22 @@
+import type { Hash, Store } from "@uncaged/json-cas";
+import { putSchema } from "@uncaged/json-cas";
+import { START_NODE_SCHEMA, STEP_NODE_SCHEMA, WORKFLOW_SCHEMA } from "@uncaged/uwf-protocol";
+
+export type UwfAgentSchemaHashes = {
+  workflow: Hash;
+  startNode: Hash;
+  stepNode: Hash;
+};
+
+/**
+ * Register Workflow, StartNode, and StepNode JSON Schemas in the CAS store.
+ * Idempotent: safe to call on every agent invocation.
+ */
+export async function registerAgentSchemas(store: Store): Promise<UwfAgentSchemaHashes> {
+  const [workflow, startNode, stepNode] = await Promise.all([
+    putSchema(store, WORKFLOW_SCHEMA),
+    putSchema(store, START_NODE_SCHEMA),
+    putSchema(store, STEP_NODE_SCHEMA),
+  ]);
+  return { workflow, startNode, stepNode };
+}

packages/uwf-agent-kit/src/storage.ts

@@ -0,0 +1,227 @@
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import type { Store } from "@uncaged/json-cas";
+import { createFsStore } from "@uncaged/json-cas-fs";
+import type {
+  AgentAlias,
+  AgentConfig,
+  ModelAlias,
+  ModelConfig,
+  ProviderAlias,
+  ProviderConfig,
+  Scenario,
+  ThreadId,
+  ThreadsIndex,
+  WorkflowConfig,
+  WorkflowName,
+} from "@uncaged/uwf-protocol";
+import { parse } from "yaml";
+
+import { registerAgentSchemas } from "./schemas.js";
+
+/** Default filesystem root for uwf data (`~/.uncaged/workflow`). */
+export function getDefaultStorageRoot(): string {
+  return join(homedir(), ".uncaged", "workflow");
+}
+
+/**
+ * Resolve storage root.
+ * Priority: `UNCAGED_WORKFLOW_STORAGE_ROOT` → `WORKFLOW_STORAGE_ROOT` → default.
+ */
+export function resolveStorageRoot(): string {
+  const internal = process.env.UNCAGED_WORKFLOW_STORAGE_ROOT;
+  if (internal !== undefined && internal !== "") {
+    return internal;
+  }
+  const userOverride = process.env.WORKFLOW_STORAGE_ROOT;
+  if (userOverride !== undefined && userOverride !== "") {
+    return userOverride;
+  }
+  return getDefaultStorageRoot();
+}
+
+export function getCasDir(storageRoot: string): string {
+  return join(storageRoot, "cas");
+}
+
+export function getConfigPath(storageRoot: string): string {
+  return join(storageRoot, "config.yaml");
+}
+
+export function getEnvPath(storageRoot: string): string {
+  return join(storageRoot, ".env");
+}
+
+export function getThreadsPath(storageRoot: string): string {
+  return join(storageRoot, "threads.yaml");
+}
+
+export type AgentStore = {
+  storageRoot: string;
+  store: Store;
+  schemas: Awaited<ReturnType<typeof registerAgentSchemas>>;
+};
+
+export async function createAgentStore(storageRoot: string): Promise<AgentStore> {
+  const store = createFsStore(getCasDir(storageRoot));
+  const schemas = await registerAgentSchemas(store);
+  return { storageRoot, store, schemas };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function normalizeProviders(raw: unknown): Record<ProviderAlias, ProviderConfig> {
+  if (!isRecord(raw)) {
+    throw new Error("config.providers must be a mapping");
+  }
+  const providers: Record<ProviderAlias, ProviderConfig> = {};
+  for (const [name, entry] of Object.entries(raw)) {
+    if (!isRecord(entry)) {
+      throw new Error(`config.providers.${name} must be a mapping`);
+    }
+    const baseUrl = entry.baseUrl;
+    const apiKeyEnv = entry.apiKeyEnv;
+    if (typeof baseUrl !== "string" || typeof apiKeyEnv !== "string") {
+      throw new Error(`config.providers.${name} requires baseUrl and apiKeyEnv`);
+    }
+    providers[name] = { baseUrl, apiKeyEnv };
+  }
+  return providers;
+}
+
+function normalizeModels(raw: unknown): Record<ModelAlias, ModelConfig> {
+  if (!isRecord(raw)) {
+    throw new Error("config.models must be a mapping");
+  }
+  const models: Record<ModelAlias, ModelConfig> = {};
+  for (const [name, entry] of Object.entries(raw)) {
+    if (!isRecord(entry)) {
+      throw new Error(`config.models.${name} must be a mapping`);
+    }
+    const provider = entry.provider;
+    const modelName = entry.name;
+    if (typeof provider !== "string" || typeof modelName !== "string") {
+      throw new Error(`config.models.${name} requires provider and name`);
+    }
+    models[name] = { provider, name: modelName };
+  }
+  return models;
+}
+
+function normalizeAgents(raw: unknown): Record<AgentAlias, AgentConfig> {
+  if (!isRecord(raw)) {
+    throw new Error("config.agents must be a mapping");
+  }
+  const agents: Record<AgentAlias, AgentConfig> = {};
+  for (const [name, entry] of Object.entries(raw)) {
+    if (!isRecord(entry)) {
+      throw new Error(`config.agents.${name} must be a mapping`);
+    }
+    const command = entry.command;
+    const argsRaw = entry.args;
+    if (typeof command !== "string") {
+      throw new Error(`config.agents.${name} requires command`);
+    }
+    const args = Array.isArray(argsRaw)
+      ? argsRaw.filter((a): a is string => typeof a === "string")
+      : [];
+    agents[name] = { command, args };
+  }
+  return agents;
+}
+
+function normalizeModelOverrides(raw: unknown): Record<Scenario, ModelAlias> | null {
+  if (raw === undefined || raw === null) {
+    return null;
+  }
+  if (!isRecord(raw)) {
+    throw new Error("config.modelOverrides must be a mapping or null");
+  }
+  const overrides: Record<Scenario, ModelAlias> = {};
+  for (const [scene, alias] of Object.entries(raw)) {
+    if (typeof alias === "string") {
+      overrides[scene] = alias;
+    }
+  }
+  return overrides;
+}
+
+function normalizeAgentOverrides(
+  raw: unknown,
+): Record<WorkflowName, Record<string, AgentAlias>> | null {
+  if (raw === undefined || raw === null) {
+    return null;
+  }
+  if (!isRecord(raw)) {
+    throw new Error("config.agentOverrides must be a mapping or null");
+  }
+  const overrides: Record<WorkflowName, Record<string, AgentAlias>> = {};
+  for (const [workflowName, rolesRaw] of Object.entries(raw)) {
+    if (!isRecord(rolesRaw)) {
+      continue;
+    }
+    const roles: Record<string, AgentAlias> = {};
+    for (const [roleName, alias] of Object.entries(rolesRaw)) {
+      if (typeof alias === "string") {
+        roles[roleName] = alias;
+      }
+    }
+    overrides[workflowName] = roles;
+  }
+  return overrides;
+}
+
+export function normalizeWorkflowConfig(raw: unknown): WorkflowConfig {
+  if (!isRecord(raw)) {
+    throw new Error("config.yaml root must be a mapping");
+  }
+  const defaultAgent = raw.defaultAgent;
+  const defaultModel = raw.defaultModel;
+  if (typeof defaultAgent !== "string" || typeof defaultModel !== "string") {
+    throw new Error("config requires defaultAgent and defaultModel");
+  }
+  return {
+    providers: normalizeProviders(raw.providers),
+    models: normalizeModels(raw.models),
+    agents: normalizeAgents(raw.agents),
+    defaultAgent,
+    agentOverrides: normalizeAgentOverrides(raw.agentOverrides),
+    defaultModel,
+    modelOverrides: normalizeModelOverrides(raw.modelOverrides),
+  };
+}
+
+export async function loadWorkflowConfig(storageRoot: string): Promise<WorkflowConfig> {
+  const path = getConfigPath(storageRoot);
+  const text = await readFile(path, "utf8");
+  const raw = parse(text) as unknown;
+  return normalizeWorkflowConfig(raw);
+}
+
+export async function loadThreadsIndex(storageRoot: string): Promise<ThreadsIndex> {
+  const path = getThreadsPath(storageRoot);
+  try {
+    const text = await readFile(path, "utf8");
+    const raw = parse(text) as unknown;
+    if (!isRecord(raw)) {
+      return {};
+    }
+    const index: ThreadsIndex = {};
+    for (const [threadId, head] of Object.entries(raw)) {
+      if (typeof head === "string") {
+        index[threadId as ThreadId] = head;
+      }
+    }
+    return index;
+  } catch (e) {
+    const err = e as NodeJS.ErrnoException;
+    if (err.code === "ENOENT") {
+      return {};
+    }
+    throw e;
+  }
+}

packages/uwf-agent-kit/src/types.ts

@@ -0,0 +1,27 @@
+import type { Store } from "@uncaged/json-cas";
+import type { ModeratorContext, ThreadId, WorkflowPayload } from "@uncaged/uwf-protocol";
+
+export type AgentContext = ModeratorContext & {
+  threadId: ThreadId;
+  role: string;
+  store: Store;
+  workflow: WorkflowPayload;
+  /**
+   * Prepend to the role's systemPrompt when building the agent prompt.
+   * Contains the frontmatter deliverable format instruction derived from the
+   * role's output schema.  Populated by `createAgent` at run time.
+   */
+  outputFormatInstruction: string;
+};
+
+export type AgentRunResult = {
+  output: string;
+  detailHash: string;
+};
+
+export type AgentRunFn = (ctx: AgentContext) => Promise<AgentRunResult>;
+
+export type AgentOptions = {
+  name: string;
+  run: AgentRunFn;
+};

packages/uwf-agent-kit/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "include": ["src"],
+  "references": [{ "path": "../uwf-protocol" }]
+}

packages/uwf-moderator/__tests__/evaluate.test.ts

@@ -0,0 +1,120 @@
+import { describe, expect, test } from "bun:test";
+import type { ModeratorContext, WorkflowPayload } from "@uncaged/uwf-protocol";
+
+import { evaluate } from "../src/evaluate.js";
+
+const solveIssueWorkflow: WorkflowPayload = {
+  name: "solve-issue",
+  description: "End-to-end issue resolution",
+  roles: {
+    planner: {
+      description: "Creates implementation plan",
+      systemPrompt: "You are a planning agent...",
+      outputSchema: "5GWKR8TN1V3JA",
+    },
+    developer: {
+      description: "Implements code changes",
+      systemPrompt: "You are a developer agent...",
+      outputSchema: "8CNWT4KR6D1HV",
+    },
+    reviewer: {
+      description: "Reviews code changes",
+      systemPrompt: "You are a code reviewer...",
+      outputSchema: "1VPBG9SM5E7WK",
+    },
+  },
+  conditions: {
+    needsClarification: {
+      description: "Planner requests clarification from user",
+      expression: "$exists(steps[-1].output.needsClarification)",
+    },
+    notApproved: {
+      description: "Reviewer rejected the implementation",
+      expression: "steps[-1].output.approved = false",
+    },
+  },
+  graph: {
+    $START: [{ role: "planner", condition: null }],
+    planner: [
+      { role: "developer", condition: "needsClarification" },
+      { role: "$END", condition: null },
+    ],
+    developer: [{ role: "reviewer", condition: null }],
+    reviewer: [
+      { role: "developer", condition: "notApproved" },
+      { role: "$END", condition: null },
+    ],
+  },
+};
+
+function makeContext(steps: ModeratorContext["steps"]): ModeratorContext {
+  return {
+    start: {
+      workflow: "4KNM2PXR3B1QW",
+      prompt: "Fix the login bug",
+    },
+    steps,
+  };
+}
+
+describe("evaluate", () => {
+  test("$START → first role (fallback)", async () => {
+    const result = await evaluate(solveIssueWorkflow, makeContext([]));
+    expect(result).toEqual({ ok: true, value: "planner" });
+  });
+
+  test("condition match (notApproved → developer)", async () => {
+    const context = makeContext([
+      {
+        role: "reviewer",
+        output: { approved: false },
+        detail: "2MXBG6PN4A8JR",
+        agent: "uwf-hermes",
+      },
+    ]);
+    const result = await evaluate(solveIssueWorkflow, context);
+    expect(result).toEqual({ ok: true, value: "developer" });
+  });
+
+  test("fallback when condition does not match → $END", async () => {
+    const context = makeContext([
+      {
+        role: "reviewer",
+        output: { approved: true },
+        detail: "2MXBG6PN4A8JR",
+        agent: "uwf-hermes",
+      },
+    ]);
+    const result = await evaluate(solveIssueWorkflow, context);
+    expect(result).toEqual({ ok: true, value: "$END" });
+  });
+
+  test("missing role in graph → error", async () => {
+    const context = makeContext([
+      {
+        role: "unknown-role",
+        output: {},
+        detail: "2MXBG6PN4A8JR",
+        agent: "uwf-hermes",
+      },
+    ]);
+    const result = await evaluate(solveIssueWorkflow, context);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.message).toBe('no transitions defined for role "unknown-role"');
+    }
+  });
+
+  test("output expansion in context works with JSONata", async () => {
+    const context = makeContext([
+      {
+        role: "planner",
+        output: { needsClarification: true },
+        detail: "7BQST3VW9F2MA",
+        agent: "uwf-hermes",
+      },
+    ]);
+    const result = await evaluate(solveIssueWorkflow, context);
+    expect(result).toEqual({ ok: true, value: "developer" });
+  });
+});

packages/uwf-moderator/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@uncaged/uwf-moderator",
+  "version": "0.1.0",
+  "files": [
+    "src",
+    "dist",
+    "package.json"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@uncaged/uwf-protocol": "workspace:^",
+    "jsonata": "^1.8.7"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

packages/uwf-moderator/src/evaluate.ts

@@ -0,0 +1,82 @@
+import type { ModeratorContext, WorkflowPayload } from "@uncaged/uwf-protocol";
+import jsonata from "jsonata";
+
+import type { Result } from "./types.js";
+
+const START_ROLE = "$START";
+
+function isTruthy(value: unknown): boolean {
+  if (value === null || value === undefined) {
+    return false;
+  }
+  if (typeof value === "boolean") {
+    return value;
+  }
+  if (typeof value === "number") {
+    return value !== 0 && !Number.isNaN(value);
+  }
+  if (typeof value === "string") {
+    return value.length > 0;
+  }
+  return true;
+}
+
+async function evaluateJsonata(expression: string, context: ModeratorContext): Promise<Result<unknown, Error>> {
+  try {
+    const result = await jsonata(expression).evaluate(context);
+    return { ok: true, value: result };
+  } catch (error) {
+    return {
+      ok: false,
+      error: error instanceof Error ? error : new Error(String(error)),
+    };
+  }
+}
+
+function currentRole(context: ModeratorContext): string {
+  if (context.steps.length === 0) {
+    return START_ROLE;
+  }
+  return context.steps[context.steps.length - 1].role;
+}
+
+export async function evaluate(
+  workflow: WorkflowPayload,
+  context: ModeratorContext,
+): Promise<Result<string, Error>> {
+  const role = currentRole(context);
+  const transitions = workflow.graph[role];
+  if (transitions === undefined) {
+    return {
+      ok: false,
+      error: new Error(`no transitions defined for role "${role}"`),
+    };
+  }
+
+  for (const transition of transitions) {
+    if (transition.condition === null) {
+      return { ok: true, value: transition.role };
+    }
+
+    const conditionDef = workflow.conditions[transition.condition];
+    if (conditionDef === undefined) {
+      return {
+        ok: false,
+        error: new Error(`unknown condition "${transition.condition}"`),
+      };
+    }
+
+    const evalResult = await evaluateJsonata(conditionDef.expression, context);
+    if (!evalResult.ok) {
+      return evalResult;
+    }
+    if (isTruthy(evalResult.value)) {
+      return { ok: true, value: transition.role };
+    }
+  }
+
+  return {
+    ok: false,
+    error: new Error(`no transition matched for role "${role}"`),
+  };
+}

packages/uwf-moderator/src/index.ts

@@ -0,0 +1 @@
+export { evaluate } from "./evaluate.js";

packages/uwf-moderator/src/types.ts

@@ -0,0 +1 @@
+export type Result<T, E> = { ok: true; value: T } | { ok: false; error: E };

packages/uwf-moderator/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "include": ["src"],
+  "references": [{ "path": "../uwf-protocol" }]
+}

packages/uwf-protocol/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@uncaged/uwf-protocol",
+  "version": "0.1.0",
+  "files": [
+    "src",
+    "dist",
+    "package.json"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+"@uncaged/json-cas-fs": "^0.3.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

packages/uwf-protocol/src/index.ts

@@ -0,0 +1,36 @@
+export {
+  START_NODE_SCHEMA,
+  STEP_NODE_SCHEMA,
+  WORKFLOW_SCHEMA,
+} from "./schemas.js";
+export type {
+  AgentAlias,
+  AgentConfig,
+  CasRef,
+  ConditionDefinition,
+  ModelAlias,
+  ModelConfig,
+  ModeratorContext,
+  ProviderAlias,
+  ProviderConfig,
+  RoleDefinition,
+  RoleName,
+  Scenario,
+  StartEntry,
+  StartNodePayload,
+  StartOutput,
+  StepContext,
+  StepEntry,
+  StepNodePayload,
+  StepOutput,
+  StepRecord,
+  ThreadForkOutput,
+  ThreadId,
+  ThreadListItem,
+  ThreadStepsOutput,
+  ThreadsIndex,
+  Transition,
+  WorkflowConfig,
+  WorkflowName,
+  WorkflowPayload,
+} from "./types.js";

packages/uwf-protocol/src/schemas.ts

@@ -0,0 +1,86 @@
+import type { JSONSchema } from "@uncaged/json-cas";
+
+const ROLE_DEFINITION: JSONSchema = {
+  type: "object",
+  required: ["description", "systemPrompt", "outputSchema"],
+  properties: {
+    description: { type: "string" },
+    systemPrompt: { type: "string" },
+    outputSchema: { type: "string", format: "cas_ref" },
+  },
+  additionalProperties: false,
+};
+
+const CONDITION_DEFINITION: JSONSchema = {
+  type: "object",
+  required: ["description", "expression"],
+  properties: {
+    description: { type: "string" },
+    expression: { type: "string" },
+  },
+  additionalProperties: false,
+};
+
+const TRANSITION: JSONSchema = {
+  type: "object",
+  required: ["role", "condition"],
+  properties: {
+    role: { type: "string" },
+    condition: { anyOf: [{ type: "string" }, { type: "null" }] },
+  },
+  additionalProperties: false,
+};
+
+export const WORKFLOW_SCHEMA: JSONSchema = {
+  title: "Workflow",
+  type: "object",
+  required: ["name", "description", "roles", "conditions", "graph"],
+  properties: {
+    name: { type: "string" },
+    description: { type: "string" },
+    roles: {
+      type: "object",
+      additionalProperties: ROLE_DEFINITION,
+    },
+    conditions: {
+      type: "object",
+      additionalProperties: CONDITION_DEFINITION,
+    },
+    graph: {
+      type: "object",
+      additionalProperties: {
+        type: "array",
+        items: TRANSITION,
+      },
+    },
+  },
+  additionalProperties: false,
+};
+
+export const START_NODE_SCHEMA: JSONSchema = {
+  title: "StartNode",
+  type: "object",
+  required: ["workflow", "prompt"],
+  properties: {
+    workflow: { type: "string", format: "cas_ref" },
+    prompt: { type: "string" },
+  },
+  additionalProperties: false,
+};
+
+export const STEP_NODE_SCHEMA: JSONSchema = {
+  title: "StepNode",
+  type: "object",
+  required: ["start", "prev", "role", "output", "detail", "agent"],
+  properties: {
+    start: { type: "string", format: "cas_ref" },
+    prev: {
+      anyOf: [{ type: "string", format: "cas_ref" }, { type: "null" }],
+    },
+    role: { type: "string" },
+    output: { type: "string", format: "cas_ref" },
+    detail: { type: "string", format: "cas_ref" },
+    agent: { type: "string" },
+  },
+  additionalProperties: false,
+};

packages/uwf-protocol/src/types.ts

@@ -0,0 +1,160 @@
+// ── 4.1 公共类型 ────────────────────────────────────────────────────
+
+/** CAS hash — XXH64, 13-char Crockford Base32 */
+export type CasRef = string;
+
+/** Thread ID — ULID, 26-char Crockford Base32 */
+export type ThreadId = string;
+
+/** 一个 step 的核心数据，被 StepNode payload 和 JSONata 上下文共享 */
+export type StepRecord = {
+  role: string;
+  output: CasRef;
+  detail: CasRef;
+  agent: string;
+};
+
+// ── 4.2 Workflow 定义 ───────────────────────────────────────────────
+
+export type RoleDefinition = {
+  description: string;
+  systemPrompt: string;
+  outputSchema: CasRef;
+};
+
+export type Transition = {
+  role: string;
+  condition: string | null;
+};
+
+export type ConditionDefinition = {
+  description: string;
+  expression: string;
+};
+
+export type WorkflowPayload = {
+  name: string;
+  description: string;
+  roles: Record<string, RoleDefinition>;
+  conditions: Record<string, ConditionDefinition>;
+  graph: Record<string, Transition[]>;
+};
+
+// ── 4.3 Thread 节点 ─────────────────────────────────────────────────
+
+export type StartNodePayload = {
+  workflow: CasRef;
+  prompt: string;
+};
+
+export type StepNodePayload = StepRecord & {
+  start: CasRef;
+  prev: CasRef | null;
+};
+
+// ── 4.4 JSONata 求值上下文 ──────────────────────────────────────────
+
+/** JSONata 上下文中的 step — output 被展开 */
+export type StepContext = Omit<StepRecord, "output"> & {
+  output: unknown;
+};
+
+export type ModeratorContext = {
+  start: StartNodePayload;
+  steps: StepContext[];
+};
+
+// ── 4.5 CLI 输出 ────────────────────────────────────────────────────
+
+/** uwf thread start */
+export type StartOutput = {
+  workflow: CasRef;
+  thread: ThreadId;
+};
+
+/** uwf thread step / uwf thread show */
+export type StepOutput = {
+  workflow: CasRef;
+  thread: ThreadId;
+  head: CasRef;
+  done: boolean;
+};
+
+/** uwf thread steps — single step entry */
+export type StepEntry = {
+  hash: CasRef;
+  role: string;
+  output: unknown;
+  detail: CasRef;
+  agent: string;
+  timestamp: number;
+};
+
+/** uwf thread steps — start entry */
+export type StartEntry = {
+  hash: CasRef;
+  workflow: CasRef;
+  prompt: string;
+  timestamp: number;
+};
+
+/** uwf thread steps output */
+export type ThreadStepsOutput = {
+  thread: ThreadId;
+  workflow: CasRef;
+  steps: [StartEntry, ...StepEntry[]];
+};
+
+/** uwf thread fork output */
+export type ThreadForkOutput = {
+  thread: ThreadId;
+  forkedFrom: {
+    step: CasRef;
+  };
+};
+
+/** uwf thread list */
+export type ThreadListItem = {
+  thread: ThreadId;
+  workflow: CasRef;
+  head: CasRef;
+};
+
+// ── 4.6 配置 ────────────────────────────────────────────────────────
+
+/** Alias types for config references */
+export type AgentAlias = string;
+export type ModelAlias = string;
+export type ProviderAlias = string;
+export type WorkflowName = string;
+export type RoleName = string;
+export type Scenario = string;
+
+export type ProviderConfig = {
+  baseUrl: string;
+  apiKeyEnv: string;
+};
+
+export type ModelConfig = {
+  provider: ProviderAlias;
+  name: string;
+};
+
+export type AgentConfig = {
+  command: string;
+  args: string[];
+};
+
+/** ~/.uncaged/workflow/config.yaml */
+export type WorkflowConfig = {
+  providers: Record<ProviderAlias, ProviderConfig>;
+  models: Record<ModelAlias, ModelConfig>;
+  agents: Record<AgentAlias, AgentConfig>;
+  defaultAgent: AgentAlias;
+  agentOverrides: Record<WorkflowName, Record<RoleName, AgentAlias>> | null;
+  defaultModel: ModelAlias;
+  modelOverrides: Record<Scenario, ModelAlias> | null;
+};
+
+/** ~/.uncaged/workflow/threads.yaml */
+export type ThreadsIndex = Record<ThreadId, CasRef>;

packages/uwf-protocol/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "include": ["src"]
+}

packages/workflow-agent-cursor/CHANGELOG.md

@@ -1,5 +1,62 @@
 # @uncaged/workflow-agent-cursor
 
+## 0.5.0-alpha.4
+
+### Patch Changes
+
+- Updated dependencies
+- Updated dependencies [f74b482]
+- Updated dependencies [f74b482]
+  - @uncaged/workflow-util@0.5.0-alpha.4
+  - @uncaged/workflow-protocol@0.5.0-alpha.4
+  - @uncaged/workflow-cas@0.5.0-alpha.4
+  - @uncaged/workflow-runtime@0.5.0-alpha.4
+  - @uncaged/workflow-util-agent@0.5.0-alpha.4
+
+## 0.5.0-alpha.3
+
+### Patch Changes
+
+- Updated dependencies
+  - @uncaged/workflow-protocol@0.5.0-alpha.3
+  - @uncaged/workflow-cas@0.5.0-alpha.3
+  - @uncaged/workflow-runtime@0.5.0-alpha.3
+  - @uncaged/workflow-util@0.5.0-alpha.3
+  - @uncaged/workflow-util-agent@0.5.0-alpha.3
+
+## 0.5.0-alpha.2
+
+### Patch Changes
+
+- Updated dependencies
+  - @uncaged/workflow-protocol@0.5.0-alpha.2
+  - @uncaged/workflow-cas@0.5.0-alpha.2
+  - @uncaged/workflow-runtime@0.5.0-alpha.2
+  - @uncaged/workflow-util@0.5.0-alpha.2
+  - @uncaged/workflow-util-agent@0.5.0-alpha.2
+
+## 0.5.0-alpha.1
+
+### Patch Changes
+
+- Updated dependencies
+  - @uncaged/workflow-util-agent@0.5.0-alpha.1
+  - @uncaged/workflow-cas@0.5.0-alpha.1
+  - @uncaged/workflow-protocol@0.5.0-alpha.1
+  - @uncaged/workflow-runtime@0.5.0-alpha.1
+  - @uncaged/workflow-util@0.5.0-alpha.1
+
+## 0.5.0-alpha.0
+
+### Patch Changes
+
+- Updated dependencies
+  - @uncaged/workflow-protocol@0.5.0-alpha.0
+  - @uncaged/workflow-cas@0.5.0-alpha.0
+  - @uncaged/workflow-runtime@0.5.0-alpha.0
+  - @uncaged/workflow-util@0.5.0-alpha.0
+  - @uncaged/workflow-util-agent@0.5.0-alpha.0
+
 ## 0.4.5
 
 ### Patch Changes

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

@@ -1,21 +1,25 @@
 import { describe, expect, test } from "bun:test";
 import { createCursorAgent, validateCursorAgentConfig } from "../src/index.js";
 
+const baseConfig = {
+  command: "/usr/local/bin/cursor-agent",
+  model: null as string | null,
+  timeout: 0,
+  workspace: null as string | null,
+};
+
 describe("validateCursorAgentConfig", () => {
   test("accepts valid config", () => {
     const r = validateCursorAgentConfig({
-      command: "/usr/local/bin/cursor-agent",
-      model: null,
-      timeout: 0,
+      ...baseConfig,
     });
     expect(r.ok).toBe(true);
   });
 
   test("rejects non-absolute command", () => {
     const r = validateCursorAgentConfig({
+      ...baseConfig,
       command: "cursor-agent",
-      model: null,
-      timeout: 0,
     });
     expect(r.ok).toBe(false);
     if (!r.ok) {
@@ -25,28 +29,35 @@ describe("validateCursorAgentConfig", () => {
 
   test("rejects negative timeout", () => {
     const r = validateCursorAgentConfig({
-      command: "/usr/local/bin/cursor-agent",
-      model: null,
+      ...baseConfig,
       timeout: -1,
     });
     expect(r.ok).toBe(false);
   });
+
+  test("rejects non-absolute workspace when set", () => {
+    const r = validateCursorAgentConfig({
+      ...baseConfig,
+      workspace: "relative/path",
+    });
+    expect(r.ok).toBe(false);
+    if (!r.ok) {
+      expect(r.error).toContain("workspace");
+    }
+  });
 });
 
 describe("createCursorAgent", () => {
   test("returns an AdapterFn", () => {
     const agent = createCursorAgent({
-      command: "/usr/local/bin/cursor-agent",
-      model: null,
-      timeout: 0,
+      ...baseConfig,
     });
     expect(typeof agent).toBe("function");
   });
 
   test("defers validation to call time (invalid config does not throw at construction)", () => {
     const agent = createCursorAgent({
-      command: "/usr/local/bin/cursor-agent",
-      model: null,
+      ...baseConfig,
       timeout: -1,
     });
     expect(typeof agent).toBe("function");

packages/workflow-agent-cursor/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uncaged/workflow-agent-cursor",
-  "version": "0.4.5",
+  "version": "0.5.0-alpha.4",
   "files": [
     "src",
     "dist",

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

@@ -1,8 +1,8 @@
-import type { WorkflowRuntime } from "@uncaged/workflow-runtime";
-import { createLogger } from "@uncaged/workflow-util";
+import type { AdapterFn, AgentFn, WorkflowRuntime } from "@uncaged/workflow-runtime";
+import { createLogger, type LogFn } from "@uncaged/workflow-util";
 import {
   buildThreadInput,
-  createTextAdapter,
+  createAgentAdapter,
   type SpawnCliError,
   spawnCli,
 } from "@uncaged/workflow-util-agent";
@@ -33,25 +33,15 @@ function resolveCursorModel(model: string | null): string {
   return model === null ? "auto" : model;
 }
 
-/** Runs `cursor-agent` with workspace extracted from thread context via runtime.extract. */
-export function createCursorAgent(config: CursorAgentConfig) {
-  const modelFlag = resolveCursorModel(config.model);
-  const timeoutMs = config.timeout > 0 ? config.timeout : null;
-  const logger = createLogger({ sink: { kind: "stderr" } });
-
-  return createTextAdapter(async (ctx, prompt, runtime: WorkflowRuntime) => {
-    const validated = validateCursorAgentConfig(config);
-    if (!validated.ok) {
-      throw new Error(validated.error);
-    }
-
-    const workspace = await extractWorkspacePath(ctx, runtime, logger);
-    if (workspace === null) {
-      throw new Error(
-        "cursor-agent: failed to extract workspace path from context. Ensure the task prompt or previous steps include a project path.",
-      );
-    }
+type CursorAgentOpt = { prompt: string; workspace: string };
 
+function createCursorAgentFn(
+  config: CursorAgentConfig,
+  modelFlag: string,
+  timeoutMs: number | null,
+  logger: LogFn,
+): AgentFn<CursorAgentOpt> {
+  return async (ctx, { prompt, workspace }) => {
     logger("R5HN3YKQ", `cursor-agent workspace: ${workspace}`);
     const threadInput = await buildThreadInput(ctx);
     const fullPrompt = `${prompt}\n\n${threadInput}`;
@@ -75,5 +65,33 @@ export function createCursorAgent(config: CursorAgentConfig) {
       throwCursorSpawnError(run.error);
     }
     return run.value;
-  });
+  };
+}
+
+/** Runs `cursor-agent` with workspace from config or extracted from thread context via runtime.extract. */
+export function createCursorAgent(config: CursorAgentConfig): AdapterFn {
+  const modelFlag = resolveCursorModel(config.model);
+  const timeoutMs = config.timeout > 0 ? config.timeout : null;
+  const logger = createLogger({ sink: { kind: "stderr" } });
+
+  return createAgentAdapter(
+    createCursorAgentFn(config, modelFlag, timeoutMs, logger),
+    async (ctx, prompt, runtime: WorkflowRuntime) => {
+      const validated = validateCursorAgentConfig(config);
+      if (!validated.ok) {
+        throw new Error(validated.error);
+      }
+
+      const workspace =
+        config.workspace !== null
+          ? config.workspace
+          : await extractWorkspacePath(ctx, runtime, logger);
+      if (workspace === null) {
+        throw new Error(
+          "cursor-agent: failed to extract workspace path from context. Ensure the task prompt or previous steps include a project path.",
+        );
+      }
+      return { prompt, workspace };
+    },
+  );
 }

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

@@ -3,4 +3,9 @@ export type CursorAgentConfig = {
   command: string;
   model: string | null;
   timeout: number;
+  /**
+   * When non-null, use this workspace directory for `cursor-agent` instead of resolving it
+   * from the thread via runtime extraction.
+   */
+  workspace: string | null;
 };

packages/workflow-agent-cursor/src/validate-config.ts

@@ -11,5 +11,8 @@ export function validateCursorAgentConfig(config: CursorAgentConfig): Result<voi
   if (config.timeout < 0) {
     return err("timeout must be a non-negative number (milliseconds); use 0 for no limit");
   }
+  if (config.workspace !== null && !isAbsolute(config.workspace)) {
+    return err("workspace must be an absolute filesystem path when set");
+  }
   return ok(undefined);
 }

packages/workflow-agent-docx-diff/__tests__/agent.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, test } from "bun:test";
+import { packageDescriptor } from "../src/package-descriptor.js";
+import { createDocxDiffAgent } from "../src/agent.js";
+
+describe("createDocxDiffAgent", () => {
+  test("returns an AdapterFn (function)", () => {
+    const agent = createDocxDiffAgent({ command: null });
+    expect(typeof agent).toBe("function");
+  });
+
+  test("AdapterFn returns a RoleFn (function)", () => {
+    const agent = createDocxDiffAgent({ command: null });
+    const roleFn = agent("", expect.anything() as never);
+    expect(typeof roleFn).toBe("function");
+  });
+});
+
+describe("packageDescriptor", () => {
+  test("has correct name", () => {
+    expect(packageDescriptor.name).toBe("@uncaged/workflow-agent-docx-diff");
+  });
+});

packages/workflow-agent-docx-diff/__tests__/runner.test.ts

@@ -0,0 +1,113 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { describe, expect, mock, test } from "bun:test";
+import { ok, err } from "@uncaged/workflow-util";
+import type { SpawnCliConfig } from "@uncaged/workflow-util-agent";
+import { runDocxDiff } from "../src/runner.js";
+
+type MockSpawnResult = Awaited<ReturnType<typeof import("@uncaged/workflow-util-agent").spawnCli>>;
+
+function makeSpawn(result: MockSpawnResult) {
+  return mock(async (_cmd: string, _args: string[], _opts: SpawnCliConfig) => result);
+}
+
+function tempDir(): string {
+  const dir = join(tmpdir(), `diff-test-${Date.now()}`);
+  mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+describe("runDocxDiff", () => {
+  test("exit 0: success, returns DifferMeta JSON", async () => {
+    const dir = tempDir();
+    const sourceDocx = join(dir, "original.docx");
+    const modifiedDocx = join(dir, "modified.docx");
+    const diffDocx = join(dir, "diff.docx");
+    writeFileSync(sourceDocx, "");
+    writeFileSync(modifiedDocx, "");
+
+    const spawnFn = makeSpawn(ok("") as MockSpawnResult);
+    // simulate docx-diff creating the diff file
+    writeFileSync(diffDocx, "");
+
+    const raw = await runDocxDiff(
+      { command: "docx-diff" },
+      sourceDocx,
+      modifiedDocx,
+      diffDocx,
+      spawnFn,
+    );
+    const meta = JSON.parse(raw);
+    expect(meta.sourceDocx).toBe(sourceDocx);
+    expect(meta.modifiedDocx).toBe(modifiedDocx);
+    expect(meta.diffDocx).toBe(diffDocx);
+
+    expect(spawnFn.mock.calls[0][1]).toEqual([
+      sourceDocx,
+      modifiedDocx,
+      "--output",
+      "docx",
+      "--out-file",
+      diffDocx,
+    ]);
+  });
+
+  test("exit 1 (changes found): treated as success", async () => {
+    const dir = tempDir();
+    const sourceDocx = join(dir, "s.docx");
+    const modifiedDocx = join(dir, "m.docx");
+    const diffDocx = join(dir, "diff.docx");
+    writeFileSync(sourceDocx, "");
+    writeFileSync(modifiedDocx, "");
+    writeFileSync(diffDocx, "");
+
+    const spawnFn = makeSpawn(
+      err({ kind: "non_zero_exit", exitCode: 1, stdout: "", stderr: "" }) as MockSpawnResult,
+    );
+
+    await expect(
+      runDocxDiff({ command: "docx-diff" }, sourceDocx, modifiedDocx, diffDocx, spawnFn),
+    ).resolves.toBeDefined();
+  });
+
+  test("exit 2: throws error", async () => {
+    const dir = tempDir();
+    const spawnFn = makeSpawn(
+      err({ kind: "non_zero_exit", exitCode: 2, stdout: "", stderr: "fatal error" }) as MockSpawnResult,
+    );
+
+    await expect(
+      runDocxDiff({ command: null }, "s.docx", "m.docx", "diff.docx", spawnFn),
+    ).rejects.toThrow("docx-diff failed");
+  });
+
+  test("timeout: throws error", async () => {
+    const spawnFn = makeSpawn(err({ kind: "timeout" }) as MockSpawnResult);
+
+    await expect(
+      runDocxDiff({ command: null }, "s.docx", "m.docx", "diff.docx", spawnFn),
+    ).rejects.toThrow("timed out");
+  });
+
+  test("throws when diff file not created", async () => {
+    const dir = tempDir();
+    const spawnFn = makeSpawn(ok("") as MockSpawnResult);
+    // do NOT create diffDocx
+
+    await expect(
+      runDocxDiff({ command: null }, "s.docx", "m.docx", join(dir, "missing.docx"), spawnFn),
+    ).rejects.toThrow("diff file not found");
+  });
+
+  test("uses PATH docx-diff when command is null", async () => {
+    const dir = tempDir();
+    const diffDocx = join(dir, "diff.docx");
+    writeFileSync(diffDocx, "");
+    const spawnFn = makeSpawn(ok("") as MockSpawnResult);
+
+    await runDocxDiff({ command: null }, "s.docx", "m.docx", diffDocx, spawnFn);
+
+    expect(spawnFn.mock.calls[0][0]).toBe("docx-diff");
+  });
+});

packages/workflow-agent-docx-diff/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@uncaged/workflow-agent-docx-diff",
+  "version": "0.1.0",
+  "files": ["src", "dist", "package.json"],
+  "type": "module",
+  "types": "src/index.ts",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@uncaged/workflow-runtime": "workspace:^",
+    "@uncaged/workflow-util-agent": "workspace:^",
+    "@uncaged/workflow-template-document": "workspace:^",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@uncaged/workflow-util": "workspace:^"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

packages/workflow-agent-docx-diff/src/agent.ts

@@ -0,0 +1,29 @@
+import * as z from "zod/v4";
+import { dirname, join } from "node:path";
+import type { AdapterFn, RoleResult, ThreadContext, WorkflowRuntime } from "@uncaged/workflow-runtime";
+import type { WriterMeta } from "@uncaged/workflow-template-document";
+import { runDocxDiff } from "./runner.js";
+import type { DocxDiffAgentConfig } from "./types.js";
+
+export function createDocxDiffAgent(config: DocxDiffAgentConfig): AdapterFn {
+  return <T>(_prompt: string, schema: z.ZodType<T>) =>
+    async (ctx: ThreadContext, _runtime: WorkflowRuntime): Promise<RoleResult<T>> => {
+      const writerStep = ctx.steps.find((s) => s.role === "writer");
+      if (writerStep === undefined) throw new Error("differ: no writer step found");
+
+      const writerMeta = writerStep.meta as WriterMeta;
+      if (writerMeta.mode !== "edit")
+        throw new Error("differ: writer did not run in edit mode");
+
+      const diffDocx = join(dirname(writerMeta.outputDocx), "diff.docx");
+      const raw = await runDocxDiff(
+        config,
+        writerMeta.sourceDocx,
+        writerMeta.outputDocx,
+        diffDocx,
+      );
+
+      const meta = schema.parse(JSON.parse(raw)) as T;
+      return { meta, childThread: null };
+    };
+}

packages/workflow-agent-docx-diff/src/index.ts

@@ -0,0 +1,3 @@
+export { createDocxDiffAgent } from "./agent.js";
+export { packageDescriptor } from "./package-descriptor.js";
+export type { DocxDiffAgentConfig } from "./types.js";

packages/workflow-agent-docx-diff/src/package-descriptor.ts

@@ -0,0 +1,17 @@
+import type { PackageDescriptor } from "@uncaged/workflow-runtime";
+
+export const packageDescriptor: PackageDescriptor = {
+  name: "@uncaged/workflow-agent-docx-diff",
+  version: "0.1.0",
+  capabilities: ["docx-diff-cli", "docx-diff-report"],
+  configSchema: {
+    type: "object",
+    properties: {
+      command: {
+        anyOf: [{ type: "string" }, { type: "null" }],
+        description: "Path to docx-diff CLI binary; null uses PATH.",
+      },
+    },
+    additionalProperties: false,
+  },
+};

packages/workflow-agent-docx-diff/src/runner.ts

@@ -0,0 +1,47 @@
+import { stat } from "node:fs/promises";
+import { spawnCli } from "@uncaged/workflow-util-agent";
+import type { SpawnCliError } from "@uncaged/workflow-util-agent";
+import type { DocxDiffAgentConfig } from "./types.js";
+
+type SpawnCliFn = typeof spawnCli;
+
+function throwSpawnError(e: SpawnCliError): never {
+  if (e.kind === "non_zero_exit")
+    throw new Error(`docx-diff failed (exit ${e.exitCode}): ${e.stderr}`);
+  if (e.kind === "timeout")
+    throw new Error("docx-diff: timed out");
+  throw new Error(`docx-diff: spawn failed: ${e.message}`);
+}
+
+export async function runDocxDiff(
+  config: DocxDiffAgentConfig,
+  sourceDocx: string,
+  modifiedDocx: string,
+  diffDocx: string,
+  spawnCliFn: SpawnCliFn = spawnCli,
+): Promise<string> {
+  const command = config.command ?? "docx-diff";
+  const result = await spawnCliFn(
+    command,
+    [sourceDocx, modifiedDocx, "--output", "docx", "--out-file", diffDocx],
+    { cwd: null, timeoutMs: null },
+  );
+
+  if (!result.ok) {
+    const e = result.error;
+    // exit 1 = changes found (normal for docx-diff)
+    if (e.kind === "non_zero_exit" && e.exitCode === 1) {
+      // fall through to file check
+    } else {
+      throwSpawnError(e);
+    }
+  }
+
+  try {
+    await stat(diffDocx);
+  } catch {
+    throw new Error(`docx-diff: diff file not found: ${diffDocx}`);
+  }
+
+  return JSON.stringify({ sourceDocx, modifiedDocx, diffDocx });
+}

packages/workflow-agent-docx-diff/src/types.ts

@@ -0,0 +1,3 @@
+export type DocxDiffAgentConfig = {
+  command: string | null;
+};

packages/workflow-agent-docx-diff/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist",
+    "composite": true
+  },
+  "include": ["src/**/*.ts"],
+  "references": [
+    { "path": "../workflow-protocol" },
+    { "path": "../workflow-runtime" },
+    { "path": "../workflow-util-agent" },
+    { "path": "../workflow-template-document" }
+  ]
+}

packages/workflow-agent-hermes/CHANGELOG.md

@@ -1,5 +1,41 @@
 # @uncaged/workflow-agent-hermes
 
+## 0.5.0-alpha.4
+
+### Patch Changes
+
+- @uncaged/workflow-runtime@0.5.0-alpha.4
+- @uncaged/workflow-util-agent@0.5.0-alpha.4
+
+## 0.5.0-alpha.3
+
+### Patch Changes
+
+- @uncaged/workflow-runtime@0.5.0-alpha.3
+- @uncaged/workflow-util-agent@0.5.0-alpha.3
+
+## 0.5.0-alpha.2
+
+### Patch Changes
+
+- @uncaged/workflow-runtime@0.5.0-alpha.2
+- @uncaged/workflow-util-agent@0.5.0-alpha.2
+
+## 0.5.0-alpha.1
+
+### Patch Changes
+
+- Updated dependencies
+  - @uncaged/workflow-util-agent@0.5.0-alpha.1
+  - @uncaged/workflow-runtime@0.5.0-alpha.1
+
+## 0.5.0-alpha.0
+
+### Patch Changes
+
+- @uncaged/workflow-runtime@0.5.0-alpha.0
+- @uncaged/workflow-util-agent@0.5.0-alpha.0
+
 ## 0.4.5
 
 ### Patch Changes

packages/workflow-agent-hermes/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uncaged/workflow-agent-hermes",
-  "version": "0.4.5",
+  "version": "0.5.0-alpha.4",
   "files": [
     "src",
     "dist",

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

@@ -1,7 +1,7 @@
-import type { AdapterFn } from "@uncaged/workflow-runtime";
+import type { AdapterFn, AgentFn } from "@uncaged/workflow-runtime";
 import {
   buildThreadInput,
-  createTextAdapter,
+  createAgentAdapter,
   type SpawnCliError,
   spawnCli,
 } from "@uncaged/workflow-util-agent";
@@ -11,6 +11,8 @@ import { validateHermesAgentConfig } from "./validate-config.js";
 
 const HERMES_DEFAULT_MAX_TURNS = 90;
 
+type HermesAgentOpt = { prompt: string };
+
 export type { HermesAgentConfig } from "./types.js";
 export { validateHermesAgentConfig } from "./validate-config.js";
 
@@ -29,16 +31,10 @@ function throwHermesSpawnError(error: SpawnCliError): never {
   throw new Error("hermes: unknown spawn error");
 }
 
-/** Runs `hermes chat` non-interactively with the Nerve-style argv contract (`-q`, `--yolo`, `--quiet`). */
-export function createHermesAgent(config: HermesAgentConfig): AdapterFn {
+function createHermesAgentFn(config: HermesAgentConfig): AgentFn<HermesAgentOpt> {
   const timeoutMs = config.timeout;
 
-  return createTextAdapter(async (ctx, prompt, _runtime) => {
-    const validated = validateHermesAgentConfig(config);
-    if (!validated.ok) {
-      throw new Error(validated.error);
-    }
-
+  return async (ctx, { prompt }) => {
     const threadInput = await buildThreadInput(ctx);
     const fullPrompt = `${prompt}\n\n${threadInput}`;
     const args = [
@@ -61,5 +57,16 @@ export function createHermesAgent(config: HermesAgentConfig): AdapterFn {
       throwHermesSpawnError(run.error);
     }
     return run.value;
+  };
+}
+
+/** Runs `hermes chat` non-interactively with the Nerve-style argv contract (`-q`, `--yolo`, `--quiet`). */
+export function createHermesAgent(config: HermesAgentConfig): AdapterFn {
+  return createAgentAdapter(createHermesAgentFn(config), async (_ctx, prompt, _runtime) => {
+    const validated = validateHermesAgentConfig(config);
+    if (!validated.ok) {
+      throw new Error(validated.error);
+    }
+    return { prompt };
   });
 }

packages/workflow-agent-llm/CHANGELOG.md

@@ -1,5 +1,41 @@
 # @uncaged/workflow-agent-llm
 
+## 0.5.0-alpha.4
+
+### Patch Changes
+
+- @uncaged/workflow-runtime@0.5.0-alpha.4
+- @uncaged/workflow-util-agent@0.5.0-alpha.4
+
+## 0.5.0-alpha.3
+
+### Patch Changes
+
+- @uncaged/workflow-runtime@0.5.0-alpha.3
+- @uncaged/workflow-util-agent@0.5.0-alpha.3
+
+## 0.5.0-alpha.2
+
+### Patch Changes
+
+- @uncaged/workflow-runtime@0.5.0-alpha.2
+- @uncaged/workflow-util-agent@0.5.0-alpha.2
+
+## 0.5.0-alpha.1
+
+### Patch Changes
+
+- Updated dependencies
+  - @uncaged/workflow-util-agent@0.5.0-alpha.1
+  - @uncaged/workflow-runtime@0.5.0-alpha.1
+
+## 0.5.0-alpha.0
+
+### Patch Changes
+
+- @uncaged/workflow-runtime@0.5.0-alpha.0
+- @uncaged/workflow-util-agent@0.5.0-alpha.0
+
 ## 0.4.5
 
 ### Patch Changes

packages/workflow-agent-llm/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uncaged/workflow-agent-llm",
-  "version": "0.4.5",
+  "version": "0.5.0-alpha.4",
   "files": [
     "src",
     "dist",

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

@@ -1,5 +1,12 @@
-import { type AdapterFn, err, type LlmProvider, ok, type Result } from "@uncaged/workflow-runtime";
-import { createTextAdapter } from "@uncaged/workflow-util-agent";
+import {
+  type AdapterFn,
+  type AgentFn,
+  err,
+  type LlmProvider,
+  ok,
+  type Result,
+} from "@uncaged/workflow-runtime";
+import { createAgentAdapter } from "@uncaged/workflow-util-agent";
 
 /** OpenAI chat completion message shape (passed to `/chat/completions`). */
 export type LlmMessage = { role: "system" | "user" | "assistant"; content: string };
@@ -91,9 +98,10 @@ 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, _runtime) => {
+type LlmAgentOpt = { prompt: string };
+
+function createLlmAgent(provider: LlmProvider): AgentFn<LlmAgentOpt> {
+  return async (ctx, { prompt }) => {
     const result = await chatCompletionText({
       provider,
       messages: [
@@ -105,5 +113,12 @@ export function createLlmAdapter(provider: LlmProvider): AdapterFn {
       throw new Error(`llm: ${formatLlmChatError(result.error)}`);
     }
     return result.value;
-  });
+  };
+}
+
+/** Single-turn chat adapter: system prompt is passed by the workflow engine. */
+export function createLlmAdapter(provider: LlmProvider): AdapterFn {
+  return createAgentAdapter(createLlmAgent(provider), async (_ctx, prompt, _runtime) => ({
+    prompt,
+  }));
 }

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

@@ -0,0 +1,27 @@
+import { describe, expect, test } from "bun:test";
+import { packageDescriptor } from "../src/package-descriptor.js";
+import { createOfficeAgent } from "../src/agent.js";
+
+describe("createOfficeAgent", () => {
+  test("returns an AdapterFn (function)", () => {
+    const agent = createOfficeAgent({ outputDir: "/tmp", command: null, timeout: null });
+    expect(typeof agent).toBe("function");
+  });
+
+  test("AdapterFn returns a RoleFn (function)", () => {
+    const agent = createOfficeAgent({ outputDir: "/tmp", command: null, timeout: null });
+    const roleFn = agent("", expect.anything() as never);
+    expect(typeof roleFn).toBe("function");
+  });
+});
+
+describe("packageDescriptor", () => {
+  test("has correct name", () => {
+    expect(packageDescriptor.name).toBe("@uncaged/workflow-agent-office");
+  });
+
+  test("has outputDir in configSchema required", () => {
+    const schema = packageDescriptor.configSchema as { required: string[] };
+    expect(schema.required).toContain("outputDir");
+  });
+});

packages/workflow-agent-office/__tests__/runner.test.ts

@@ -0,0 +1,129 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { describe, expect, mock, test } from "bun:test";
+import { ok, err } from "@uncaged/workflow-util";
+import type { SpawnCliConfig } from "@uncaged/workflow-util-agent";
+import { editDocument, generateDocument } from "../src/runner.js";
+
+type MockSpawnResult = Awaited<ReturnType<typeof import("@uncaged/workflow-util-agent").spawnCli>>;
+
+function makeSpawn(result: MockSpawnResult) {
+  return mock(async (_cmd: string, _args: string[], _opts: SpawnCliConfig) => result);
+}
+
+function tempDir(): string {
+  const dir = join(tmpdir(), `office-test-${Date.now()}`);
+  mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+describe("generateDocument", () => {
+  test("calls office-agent create with correct args and returns outputDocx path", async () => {
+    const base = tempDir();
+    const spawnFn = makeSpawn(ok("agent reply") as MockSpawnResult);
+    // Simulate CLI creating the file
+    const outFile = join(base, "thread1", "output.docx");
+    mkdirSync(join(base, "thread1"), { recursive: true });
+    writeFileSync(outFile, "");
+
+    const result = await generateDocument(
+      { outputDir: base, command: "office-agent", timeout: null },
+      "thread1",
+      "Write a report",
+      spawnFn,
+    );
+
+    expect(result.outputDocx).toBe(outFile);
+    expect(result.sourceDocx).toBeNull();
+    expect(spawnFn.mock.calls[0][0]).toBe("office-agent");
+    expect(spawnFn.mock.calls[0][1]).toEqual(["create", "Write a report", "-o", "output.docx"]);
+    expect(spawnFn.mock.calls[0][2].cwd).toBe(join(base, "thread1"));
+  });
+
+  test("uses PATH office-agent when command is null", async () => {
+    const base = tempDir();
+    const spawnFn = makeSpawn(ok("") as MockSpawnResult);
+    mkdirSync(join(base, "t2"), { recursive: true });
+    writeFileSync(join(base, "t2", "output.docx"), "");
+
+    await generateDocument(
+      { outputDir: base, command: null, timeout: null },
+      "t2",
+      "Generate",
+      spawnFn,
+    );
+
+    expect(spawnFn.mock.calls[0][0]).toBe("office-agent");
+  });
+
+  test("throws on non_zero_exit", async () => {
+    const base = tempDir();
+    const spawnFn = makeSpawn(
+      err({ kind: "non_zero_exit", exitCode: 1, stdout: "", stderr: "error" }) as MockSpawnResult,
+    );
+
+    await expect(
+      generateDocument({ outputDir: base, command: null, timeout: null }, "t3", "fail", spawnFn),
+    ).rejects.toThrow("office-agent failed (exit 1)");
+  });
+
+  test("throws on timeout", async () => {
+    const base = tempDir();
+    const spawnFn = makeSpawn(err({ kind: "timeout" }) as MockSpawnResult);
+
+    await expect(
+      generateDocument({ outputDir: base, command: null, timeout: null }, "t4", "slow", spawnFn),
+    ).rejects.toThrow("office-agent: timed out");
+  });
+
+  test("throws when output file not created", async () => {
+    const base = tempDir();
+    const spawnFn = makeSpawn(ok("") as MockSpawnResult);
+    // Do NOT create output.docx
+
+    await expect(
+      generateDocument({ outputDir: base, command: null, timeout: null }, "t5", "no file", spawnFn),
+    ).rejects.toThrow("output file not found");
+  });
+});
+
+describe("editDocument", () => {
+  test("copies input to original.docx and modified.docx, calls edit, returns paths", async () => {
+    const base = tempDir();
+    // Create a fake inputDocx
+    const inputFile = join(base, "source.docx");
+    writeFileSync(inputFile, "original content");
+
+    const spawnFn = makeSpawn(ok("") as MockSpawnResult);
+    // Simulate CLI overwriting modified.docx
+    const outDir = join(base, "te1");
+    mkdirSync(outDir, { recursive: true });
+    writeFileSync(join(outDir, "modified.docx"), "modified content");
+
+    const result = await editDocument(
+      { outputDir: base, command: "office-agent", timeout: null },
+      "te1",
+      "Edit the doc",
+      inputFile,
+      spawnFn,
+    );
+
+    expect(result.outputDocx).toBe(join(outDir, "modified.docx"));
+    expect(result.sourceDocx).toBe(join(outDir, "original.docx"));
+    expect(spawnFn.mock.calls[0][1]).toEqual(["edit", "modified.docx", "Edit the doc"]);
+  });
+
+  test("throws on spawn_failed", async () => {
+    const base = tempDir();
+    const inputFile = join(base, "src.docx");
+    writeFileSync(inputFile, "");
+    const spawnFn = makeSpawn(
+      err({ kind: "spawn_failed", message: "not found" }) as MockSpawnResult,
+    );
+
+    await expect(
+      editDocument({ outputDir: base, command: null, timeout: null }, "te2", "edit", inputFile, spawnFn),
+    ).rejects.toThrow("spawn failed");
+  });
+});

packages/workflow-agent-office/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@uncaged/workflow-agent-office",
+  "version": "0.1.0",
+  "files": ["src", "dist", "package.json"],
+  "type": "module",
+  "types": "src/index.ts",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@uncaged/workflow-runtime": "workspace:^",
+    "@uncaged/workflow-util": "workspace:^",
+    "@uncaged/workflow-util-agent": "workspace:^"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

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

@@ -0,0 +1,44 @@
+import * as z from "zod/v4";
+import type { AdapterFn, RoleResult, ThreadContext, WorkflowRuntime } from "@uncaged/workflow-runtime";
+import { createLogger } from "@uncaged/workflow-util";
+import { editDocument, generateDocument } from "./runner.js";
+import type { OfficeAgentConfig } from "./types.js";
+
+const log = createLogger({ sink: { kind: "stderr" } });
+
+type ParsedInput = { prompt: string; inputDocx: string | null };
+
+function parseStartInput(content: string): ParsedInput {
+  try {
+    const parsed = JSON.parse(content) as Record<string, unknown>;
+    if (typeof parsed.prompt === "string") {
+      return {
+        prompt: parsed.prompt,
+        inputDocx: typeof parsed.inputDocx === "string" ? parsed.inputDocx : null,
+      };
+    }
+  } catch {
+    // not JSON — treat whole content as prompt, generate mode
+  }
+  return { prompt: content, inputDocx: null };
+}
+
+export function createOfficeAgent(config: OfficeAgentConfig): AdapterFn {
+  return <T>(_systemPrompt: string, schema: z.ZodType<T>) =>
+    async (ctx: ThreadContext, _runtime: WorkflowRuntime): Promise<RoleResult<T>> => {
+      const { prompt, inputDocx } = parseStartInput(ctx.start.content);
+      log("8FQKP3NV", `office-agent: mode=${inputDocx === null ? "generate" : "edit"} thread=${ctx.threadId}`);
+
+      let raw: string;
+      if (inputDocx === null) {
+        const result = await generateDocument(config, ctx.threadId, prompt);
+        raw = JSON.stringify({ mode: "generate", outputDocx: result.outputDocx, sourceDocx: null });
+      } else {
+        const result = await editDocument(config, ctx.threadId, prompt, inputDocx);
+        raw = JSON.stringify({ mode: "edit", outputDocx: result.outputDocx, sourceDocx: result.sourceDocx });
+      }
+
+      const meta = schema.parse(JSON.parse(raw)) as T;
+      return { meta, childThread: null };
+    };
+}

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

@@ -0,0 +1,3 @@
+export { createOfficeAgent } from "./agent.js";
+export { packageDescriptor } from "./package-descriptor.js";
+export type { OfficeAgentConfig } from "./types.js";

packages/workflow-agent-office/src/package-descriptor.ts

@@ -0,0 +1,26 @@
+import type { PackageDescriptor } from "@uncaged/workflow-runtime";
+
+export const packageDescriptor: PackageDescriptor = {
+  name: "@uncaged/workflow-agent-office",
+  version: "0.1.0",
+  capabilities: ["office-agent-cli", "docx-generate", "docx-edit"],
+  configSchema: {
+    type: "object",
+    required: ["outputDir"],
+    properties: {
+      outputDir: {
+        type: "string",
+        description: "Root directory for workflow outputs; subdirs are created per threadId.",
+      },
+      command: {
+        anyOf: [{ type: "string" }, { type: "null" }],
+        description: "Path to office-agent CLI binary; null uses PATH.",
+      },
+      timeout: {
+        anyOf: [{ type: "number" }, { type: "null" }],
+        description: "Timeout in milliseconds; null means no limit.",
+      },
+    },
+    additionalProperties: false,
+  },
+};