chore: remove cross-repo json-cas workspace deps, use npm registry

- Remove ../json-cas/packages/* from root workspaces - Change @uncaged/json-cas{,-fs} from workspace:^ to ^0.1.1 - Remove stale pnpm-lock.yaml - Clean Gitea registry from .npmrc
fix: address 3 critical PR review issues
2026-05-18 10:22:36 +00:00 · 2026-05-18 10:05:11 +00:00 · 2026-05-18 09:33:52 +00:00 · 2026-05-18 09:22:12 +00:00 · 2026-05-18 09:19:37 +00:00 · 2026-05-18 09:15:25 +00:00
39 changed files with 3254 additions and 142 deletions
@@ -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[]>
+```
@@ -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.1.1",
+    "@uncaged/json-cas-fs": "^0.1.1",
+    "@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"
+  }
+}
@@ -0,0 +1,137 @@
+#!/usr/bin/env bun
+
+import { Command } from "commander";
+
+import {
+  cmdThreadKill,
+  cmdThreadList,
+  cmdThreadShow,
+  cmdThreadStart,
+  cmdThreadStep,
+} from "./commands/thread.js";
+import { cmdWorkflowList, cmdWorkflowPut, cmdWorkflowShow } from "./commands/workflow.js";
+import { resolveStorageRoot } from "./store.js";
+
+function writeJson(data: unknown): void {
+  process.stdout.write(`${JSON.stringify(data)}\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");
+
+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);
+      writeJson(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);
+      writeJson(result);
+    });
+  });
+
+workflow
+  .command("list")
+  .description("List registered workflows")
+  .action(() => {
+    const storageRoot = resolveStorageRoot();
+    runAction(async () => {
+      const result = await cmdWorkflowList(storageRoot);
+      writeJson(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);
+      writeJson(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);
+      writeJson(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);
+      writeJson(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);
+      writeJson(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);
+      writeJson(result);
+    });
+  });
+
+program.parseAsync(process.argv).catch((e: unknown) => {
+  const message = e instanceof Error ? e.message : String(e);
+  process.stderr.write(`${message}\n`);
+  process.exit(1);
+});
@@ -0,0 +1,465 @@
+import { execFileSync } from "node:child_process";
+
+import { validate } from "@uncaged/json-cas";
+import { getEnvPath, loadWorkflowConfig } from "@uncaged/uwf-agent-kit";
+import { evaluate } from "@uncaged/uwf-moderator";
+import type {
+  AgentAlias,
+  AgentConfig,
+  CasRef,
+  ModeratorContext,
+  StartNodePayload,
+  StartOutput,
+  StepContext,
+  StepNodePayload,
+  StepOutput,
+  ThreadId,
+  ThreadListItem,
+  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";
+
+type ChainState = {
+  startHash: CasRef;
+  start: StartNodePayload;
+  stepsNewestFirst: StepNodePayload[];
+  headIsStart: boolean;
+};
+
+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;
+}
+
+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,
+  };
+}
+
+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 };
+}
@@ -0,0 +1,157 @@
+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 { isCasRef, 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,
+  outputSchema: string | JSONSchema,
+): Promise<CasRef> {
+  if (typeof outputSchema === "string") {
+    if (!isCasRef(outputSchema)) {
+      fail(`invalid outputSchema cas_ref: ${outputSchema}`);
+    }
+    if (!uwf.store.has(outputSchema)) {
+      fail(`outputSchema not found in CAS: ${outputSchema}`);
+    }
+    return outputSchema;
+  }
+  if (!isJsonSchema(outputSchema)) {
+    fail("outputSchema must be a cas_ref string or JSON Schema object");
+  }
+  return putSchema(uwf.store, outputSchema);
+}
+
+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,
+      role.outputSchema as string | JSONSchema,
+    );
+    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 }));
+}
@@ -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 };
+}
@@ -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");
+}
@@ -0,0 +1,73 @@
+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 =
+    typeof outputSchema === "string" ||
+    (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;
+}
@@ -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" }
+  ]
+}
@@ -0,0 +1,32 @@
+{
+  "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/uwf-agent-kit": "workspace:^"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}
@@ -0,0 +1,6 @@
+#!/usr/bin/env bun
+
+import { createHermesAgent } from "./hermes.js";
+
+const main = createHermesAgent();
+void main();
@@ -0,0 +1,90 @@
+import { spawn } from "node:child_process";
+
+import { type AgentContext, createAgent } from "@uncaged/uwf-agent-kit";
+
+const HERMES_COMMAND = "hermes";
+const HERMES_MAX_TURNS = 90;
+
+function buildHistorySummary(history: AgentContext["history"]): string {
+  if (history.length === 0) {
+    return "";
+  }
+
+  const lines: string[] = ["## Previous Steps"];
+  for (let i = 0; i < history.length; i++) {
+    const step = history[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 parts: string[] = [ctx.systemPrompt, "", "## Task", ctx.prompt];
+  const historyBlock = buildHistorySummary(ctx.history);
+  if (historyBlock !== "") {
+    parts.push("", historyBlock);
+  }
+  return parts.join("\n");
+}
+
+function spawnHermesChat(prompt: string): Promise<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);
+        return;
+      }
+      const detail = stderr.trim() !== "" ? ` stderr=${stderr.trim()}` : "";
+      reject(new Error(`hermes exited with code ${code ?? "null"}${detail}`));
+    });
+  });
+}
+
+async function runHermes(ctx: AgentContext): Promise<string> {
+  const fullPrompt = buildHermesPrompt(ctx);
+  return spawnHermesChat(fullPrompt);
+}
+
+/** Agent CLI factory: parses argv, runs Hermes, extracts output, writes StepNode. */
+export function createHermesAgent(): () => Promise<void> {
+  return createAgent({
+    name: "hermes",
+    run: runHermes,
+  });
+}
@@ -0,0 +1 @@
+export { buildHermesPrompt, createHermesAgent } from "./hermes.js";
@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "include": ["src"],
+  "references": [{ "path": "../uwf-agent-kit" }]
+}
@@ -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");
+  });
+});
@@ -0,0 +1,33 @@
+{
+  "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.1.1",
+    "@uncaged/json-cas-fs": "^0.1.1",
+    "@uncaged/uwf-protocol": "workspace:^",
+    "dotenv": "^16.6.1",
+    "yaml": "^2.8.4"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}
@@ -0,0 +1,199 @@
+import type {
+  CasRef,
+  StartNodePayload,
+  StepContext,
+  StepNodePayload,
+  ThreadId,
+} from "@uncaged/uwf-protocol";
+import { createAgentStore, loadThreadsIndex, resolveStorageRoot } 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: Awaited<ReturnType<typeof createAgentStore>>["store"],
+  schemas: Awaited<ReturnType<typeof createAgentStore>>["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: Awaited<ReturnType<typeof createAgentStore>>["store"],
+  outputRef: CasRef,
+): unknown {
+  const node = store.get(outputRef);
+  if (node === null) {
+    return {};
+  }
+  return node.payload;
+}
+
+async function buildHistory(
+  store: Awaited<ReturnType<typeof createAgentStore>>["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: Awaited<ReturnType<typeof createAgentStore>>["store"],
+  schemas: Awaited<ReturnType<typeof createAgentStore>>["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 history = await buildHistory(store, chain.stepsNewestFirst);
+
+  return {
+    threadId,
+    role,
+    systemPrompt: roleDef.systemPrompt,
+    prompt: chain.start.prompt,
+    history,
+    workflow,
+  };
+}
+
+export type BuildContextMeta = {
+  storageRoot: string;
+  store: Awaited<ReturnType<typeof createAgentStore>>["store"];
+  schemas: Awaited<ReturnType<typeof createAgentStore>>["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 history = await buildHistory(store, chain.stepsNewestFirst);
+
+  return {
+    threadId,
+    role,
+    systemPrompt: roleDef.systemPrompt,
+    prompt: chain.start.prompt,
+    history,
+    workflow,
+    meta: { storageRoot, store, schemas, headHash, chain },
+  };
+}
@@ -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 };
+}
@@ -0,0 +1,11 @@
+export type { BuildContextMeta } from "./context.js";
+export { buildContext, buildContextWithMeta } from "./context.js";
+export { getConfigPath, getEnvPath, loadWorkflowConfig } from "./storage.js";
+export type { ExtractResult, ResolvedLlmProvider } from "./extract.js";
+export {
+  extract,
+  resolveExtractModelAlias,
+  resolveModel,
+} from "./extract.js";
+export { createAgent } from "./run.js";
+export type { AgentContext, AgentOptions, AgentRunFn } from "./types.js";
@@ -0,0 +1,135 @@
+import { 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 { extract } from "./extract.js";
+import type { AgentStore } from "./storage.js";
+import { getEnvPath, loadWorkflowConfig, resolveStorageRoot } from "./storage.js";
+import type { AgentContext, AgentOptions } 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<string> {
+  return runWithMessage("agent run failed", () => options.run(ctx));
+}
+
+async function extractOutput(
+  rawOutput: string,
+  outputSchema: CasRef,
+  storageRoot: string,
+): Promise<CasRef> {
+  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>>;
+  rawOutput: string;
+  outputHash: CasRef;
+  agentName: string;
+}): Promise<CasRef> {
+  const { store, schemas, chain, headHash } = options.ctx.meta;
+  const detailHash = await store.put(null, options.rawOutput);
+  return writeStepNode({
+    store,
+    schemas,
+    startHash: chain.startHash,
+    prevHash: chain.headIsStart ? null : headHash,
+    role: options.ctx.role,
+    outputHash: options.outputHash,
+    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 rawOutput = await runAgent(options, ctx);
+    const outputHash = await extractOutput(rawOutput, roleDef.outputSchema, storageRoot);
+    const stepHash = await persistStep({
+      ctx,
+      rawOutput,
+      outputHash,
+      agentName: agentLabel(options.name),
+    });
+
+    process.stdout.write(`${stepHash}\n`);
+  };
+}
@@ -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 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 };
+}
@@ -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;
+  }
+}
@@ -0,0 +1,17 @@
+import type { StepContext, ThreadId, WorkflowPayload } from "@uncaged/uwf-protocol";
+
+export type AgentContext = {
+  threadId: ThreadId;
+  role: string;
+  systemPrompt: string;
+  prompt: string;
+  history: StepContext[];
+  workflow: WorkflowPayload;
+};
+
+export type AgentRunFn = (ctx: AgentContext) => Promise<string>;
+
+export type AgentOptions = {
+  name: string;
+  run: AgentRunFn;
+};
@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "include": ["src"],
+  "references": [{ "path": "../uwf-protocol" }]
+}
@@ -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" });
+  });
+});
@@ -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"
+  }
+}
@@ -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}"`),
+  };
+}
@@ -0,0 +1 @@
+export { evaluate } from "./evaluate.js";
@@ -0,0 +1 @@
+export type Result<T, E> = { ok: true; value: T } | { ok: false; error: E };
@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "include": ["src"],
+  "references": [{ "path": "../uwf-protocol" }]
+}
@@ -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": "^0.1.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}
@@ -0,0 +1,32 @@
+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,
+  StartNodePayload,
+  StartOutput,
+  StepContext,
+  StepNodePayload,
+  StepOutput,
+  StepRecord,
+  ThreadId,
+  ThreadListItem,
+  ThreadsIndex,
+  Transition,
+  WorkflowConfig,
+  WorkflowName,
+  WorkflowPayload,
+} from "./types.js";
@@ -0,0 +1,83 @@
+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 = {
+  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 = {
+  type: "object",
+  required: ["workflow", "prompt"],
+  properties: {
+    workflow: { type: "string", format: "cas_ref" },
+    prompt: { type: "string" },
+  },
+  additionalProperties: false,
+};
+
+export const STEP_NODE_SCHEMA: JSONSchema = {
+  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,
+};
@@ -0,0 +1,127 @@
+// ── 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 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>;
@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "include": ["src"]
+}
@@ -1,141 +0,0 @@
-lockfileVersion: '9.0'
-
-settings:
-  autoInstallPeers: true
-  excludeLinksFromLockfile: false
-
-importers:
-
-  .:
-    devDependencies:
-      '@biomejs/biome':
-        specifier: ^2.4.14
-        version: 2.4.15
-      '@types/xxhashjs':
-        specifier: ^0.2.4
-        version: 0.2.4
-      bun-types:
-        specifier: ^1.3.13
-        version: 1.3.13
-
-packages:
-
-  '@biomejs/biome@2.4.15':
-    resolution: {integrity: sha512-j5VH3a/h/HXTKBM50MDMxRCzkeLv9S2XJcW2WgnZT1+xyisi+0bISrXR82gCX+8S9lvK0skEvHJRN+3Ktr2hlw==}
-    engines: {node: '>=14.21.3'}
-    hasBin: true
-
-  '@biomejs/cli-darwin-arm64@2.4.15':
-    resolution: {integrity: sha512-rF3PPqLq1yoST79zaQbDjVJwsuIeci/O+9bgNmC5QpgOqz6aqYuzA4abyAGx+mgyiDXn4A049xAN8gijbuR1Qg==}
-    engines: {node: '>=14.21.3'}
-    cpu: [arm64]
-    os: [darwin]
-
-  '@biomejs/cli-darwin-x64@2.4.15':
-    resolution: {integrity: sha512-/5KHXYMfSJs1fNXiX30xFtI8JcCFV6zaVVLxOa0M2sfqBKHkpQhRTv94yxQWxeTY2lzo2OuTlNvPC+hDQt2wcQ==}
-    engines: {node: '>=14.21.3'}
-    cpu: [x64]
-    os: [darwin]
-
-  '@biomejs/cli-linux-arm64-musl@2.4.15':
-    resolution: {integrity: sha512-ZPcxznxm0pogHBLZhYntyR3sR+MrZjqJIKEr7ZqVen0Rl+P/4upVmfYXjftizi9RoqZntg33fv/1fbdhbYXpEQ==}
-    engines: {node: '>=14.21.3'}
-    cpu: [arm64]
-    os: [linux]
-    libc: [musl]
-
-  '@biomejs/cli-linux-arm64@2.4.15':
-    resolution: {integrity: sha512-owaAMZD/T4LrD0ELNCk0Km3qrRHuM0X6EAyVE1FSqGY0rbLoiDLrO4Us2tllm6cAeB2Ioa9C2C08NZPdr8+0Ug==}
-    engines: {node: '>=14.21.3'}
-    cpu: [arm64]
-    os: [linux]
-    libc: [glibc]
-
-  '@biomejs/cli-linux-x64-musl@2.4.15':
-    resolution: {integrity: sha512-CNq/9W38SYSH023lfcQ4KKU8K0YX8T//FZUhcgtMMRABDojx5XsMV7jlweAvGSl389wJQB29Qo6Zb/a+jdvt+w==}
-    engines: {node: '>=14.21.3'}
-    cpu: [x64]
-    os: [linux]
-    libc: [musl]
-
-  '@biomejs/cli-linux-x64@2.4.15':
-    resolution: {integrity: sha512-0jj7THz12GbUOLmMibktK6DZjqz2zV64KFxyBtcFTKPiiOIY0a7vns1elpO1dERvxpsZ5ik0oFfz0oGwFde1+g==}
-    engines: {node: '>=14.21.3'}
-    cpu: [x64]
-    os: [linux]
-    libc: [glibc]
-
-  '@biomejs/cli-win32-arm64@2.4.15':
-    resolution: {integrity: sha512-ouhkYdlhp/1GghEJPdWwD/Vi3gQ1nFxuSpMolWsbq3Lsq3QUR4jl6UdhhscdCugKU5vOEuMiJhvKj66O0OCq+w==}
-    engines: {node: '>=14.21.3'}
-    cpu: [arm64]
-    os: [win32]
-
-  '@biomejs/cli-win32-x64@2.4.15':
-    resolution: {integrity: sha512-zBrGq5mx5wwpnow4+2BxUvleDM+GNd4sLbPaMapsSLQLD0NGRCquqPBTgN+7XkUteHvj7M+BstuI8tmnV7+HgQ==}
-    engines: {node: '>=14.21.3'}
-    cpu: [x64]
-    os: [win32]
-
-  '@types/node@25.6.2':
-    resolution: {integrity: sha512-sokuT28dxf9JT5Kady1fsXOvI4HVpjZa95NKT5y9PNTIrs2AsobR4GFAA90ZG8M+nxVRLysCXsVj6eGC7Vbrlw==}
-
-  '@types/xxhashjs@0.2.4':
-    resolution: {integrity: sha512-E2+ZoJY2JjmVPN0iQM5gJvZkk98O2PYXSi6HrciEk3EKF34+mauEk/HgwTeCz+2r8HXHMKpucrwy4qTT12OPaQ==}
-
-  bun-types@1.3.13:
-    resolution: {integrity: sha512-QXKeHLlOLqQX9LgYaHJfzdBaV21T63HhFJnvuRCcjZiaUDpbs5ED1MgxbMra71CsryN/1dAoXuJJJwIv/2drVA==}
-
-  undici-types@7.19.2:
-    resolution: {integrity: sha512-qYVnV5OEm2AW8cJMCpdV20CDyaN3g0AjDlOGf1OW4iaDEx8MwdtChUp4zu4H0VP3nDRF/8RKWH+IPp9uW0YGZg==}
-
-snapshots:
-
-  '@biomejs/biome@2.4.15':
-    optionalDependencies:
-      '@biomejs/cli-darwin-arm64': 2.4.15
-      '@biomejs/cli-darwin-x64': 2.4.15
-      '@biomejs/cli-linux-arm64': 2.4.15
-      '@biomejs/cli-linux-arm64-musl': 2.4.15
-      '@biomejs/cli-linux-x64': 2.4.15
-      '@biomejs/cli-linux-x64-musl': 2.4.15
-      '@biomejs/cli-win32-arm64': 2.4.15
-      '@biomejs/cli-win32-x64': 2.4.15
-
-  '@biomejs/cli-darwin-arm64@2.4.15':
-    optional: true
-
-  '@biomejs/cli-darwin-x64@2.4.15':
-    optional: true
-
-  '@biomejs/cli-linux-arm64-musl@2.4.15':
-    optional: true
-
-  '@biomejs/cli-linux-arm64@2.4.15':
-    optional: true
-
-  '@biomejs/cli-linux-x64-musl@2.4.15':
-    optional: true
-
-  '@biomejs/cli-linux-x64@2.4.15':
-    optional: true
-
-  '@biomejs/cli-win32-arm64@2.4.15':
-    optional: true
-
-  '@biomejs/cli-win32-x64@2.4.15':
-    optional: true
-
-  '@types/node@25.6.2':
-    dependencies:
-      undici-types: 7.19.2
-
-  '@types/xxhashjs@0.2.4':
-    dependencies:
-      '@types/node': 25.6.2
-
-  bun-types@1.3.13:
-    dependencies:
-      '@types/node': 25.6.2
-
-  undici-types@7.19.2: {}
@@ -0,0 +1,12 @@
+#!/usr/bin/env bun
+// Mock agent for smoke testing
+import { createAgent } from "../packages/uwf-agent-kit/src/index.js";
+
+const agent = createAgent({
+  name: "mock",
+  run: async (ctx) => {
+    return `Mock output for role ${ctx.role}: task was "${ctx.prompt}"`;
+  },
+});
+
+await agent();
@@ -0,0 +1,59 @@
+name: "solve-issue"
+description: "End-to-end issue resolution"
+roles:
+  planner:
+    description: "Creates implementation plan"
+    systemPrompt: "You are a planning agent. Analyze the issue and create a step-by-step plan."
+    outputSchema:
+      type: object
+      properties:
+        plan:
+          type: string
+        steps:
+          type: array
+          items:
+            type: string
+      required: [plan, steps]
+  developer:
+    description: "Implements code changes"
+    systemPrompt: "You are a developer agent. Implement the plan."
+    outputSchema:
+      type: object
+      properties:
+        filesChanged:
+          type: array
+          items:
+            type: string
+        summary:
+          type: string
+      required: [filesChanged, summary]
+  reviewer:
+    description: "Reviews code changes"
+    systemPrompt: "You are a code reviewer. Review the implementation."
+    outputSchema:
+      type: object
+      properties:
+        approved:
+          type: boolean
+        comments:
+          type: string
+      required: [approved, comments]
+conditions:
+  notApproved:
+    description: "Reviewer rejected the implementation"
+    expression: "steps[-1].output.approved = false"
+graph:
+  $START:
+    - role: "planner"
+      condition: null
+  planner:
+    - role: "developer"
+      condition: null
+  developer:
+    - role: "reviewer"
+      condition: null
+  reviewer:
+    - role: "developer"
+      condition: "notApproved"
+    - role: "$END"
+      condition: null
@@ -32,6 +32,11 @@
    { "path": "packages/workflow-agent-react" },
    { "path": "packages/cli-workflow" },
    { "path": "packages/workflow-template-solve-issue" },
-    { "path": "packages/workflow-template-develop" }
+    { "path": "packages/workflow-template-develop" },
+    { "path": "packages/uwf-protocol" },
+    { "path": "packages/uwf-moderator" },
+    { "path": "packages/cli-uwf" },
+    { "path": "packages/uwf-agent-kit" },
+    { "path": "packages/uwf-agent-hermes" }
  ]
 }
Author	SHA1	Message	Date
xiaoju	f13fb012d6	chore: remove cross-repo json-cas workspace deps, use npm registry - Remove ../json-cas/packages/* from root workspaces - Change @uncaged/json-cas{,-fs} from workspace:^ to ^0.1.1 - Remove stale pnpm-lock.yaml - Clean Gitea registry from .npmrc	2026-05-18 10:22:36 +00:00
xiaoju	d90e29ad05	fix: address 3 critical PR review issues 1. threads.yaml race condition: reload threads index after agent subprocess completes before updating head pointer (cli-uwf/commands/thread.ts) 2. evaluateJsonata not awaited: jsonata evaluate() returns Promise for async expressions — now properly awaited (uwf-moderator/evaluate.ts) 3. resolveWorkflowHash dead code: function always returns a value, removed impossible null return type and dead null-check branches at call sites (cli-uwf/store.ts, commands/thread.ts, commands/workflow.ts)	2026-05-18 10:05:11 +00:00
xiaoju	0727e0e8d5	fix: reload CAS store after agent spawn + share schemas via uwf-protocol The agent subprocess writes StepNode to CAS on disk, but the parent process had an in-memory cache from createFsStore init. Fix: re-create store after agent spawn to pick up new nodes. Also centralized JSON Schemas in uwf-protocol so cli-uwf and agent-kit produce identical type hashes. E2E smoke test passing: workflow put → thread start → 3x step → done Refs #309	2026-05-18 09:33:52 +00:00
xiaoju	ba012d98bc	feat: add @uncaged/uwf-agent-hermes — Hermes agent CLI adapter Spawns 'hermes chat' with assembled prompt from agent-kit context. Agent-kit handles extract, StepNode write, and stdout output. Refs #309, #316	2026-05-18 09:22:12 +00:00
xiaoju	b165049a13	feat: implement thread step — moderator → agent → update head - Walk CAS chain to build ModeratorContext with expanded output - Call uwf-moderator evaluate() for role decision - Agent resolution: --agent > config overrides > default - Spawn agent CLI, capture StepNode hash - Update threads.yaml, check done via second evaluate - Archive on $END Refs #309, #315	2026-05-18 09:19:37 +00:00
xiaoju	4d477c67c0	feat: add @uncaged/uwf-agent-kit — agent CLI framework - createAgent() API for building agent CLIs - Context builder: reads CAS chain, builds AgentContext - Extract: LLM-based structured output extraction - StepNode writer: writes to CAS without touching threads.yaml - Stdout: outputs StepNode hash Refs #309, #314	2026-05-18 09:15:25 +00:00
xiaoju	0d5678c961	feat: add thread start/show/list/kill commands - thread start: ULID generation, StartNode to CAS, threads.yaml - thread show: active (done:false) or archived (done:true) - thread list: active threads, --all includes history - thread kill: archive to history.jsonl Refs #309, #313	2026-05-18 09:09:10 +00:00
xiaoju	a8e2aa85f8	feat: add @uncaged/cli-uwf with workflow put/show/list commands Refs #309, #312	2026-05-18 09:03:55 +00:00
xiaoju	2a4d35399b	feat: add @uncaged/uwf-moderator with JSONata evaluation engine 5 tests passing: transition, condition match, fallback, missing role error, output expansion. Refs #309, #311	2026-05-18 08:58:21 +00:00
xiaoju	391915411e	feat: add @uncaged/uwf-protocol with all shared types Refs #309, #310	2026-05-18 08:53:37 +00:00
xiaoju	08de1ae5eb	docs: fresh uwf-* packages, depend on @uncaged/json-cas, no reuse	2026-05-18 08:44:04 +00:00
xiaoju	c91a3d1ec6	docs: add description to condition definitions	2026-05-18 08:41:29 +00:00
xiaoju	13d932f69c	docs: config with provider/model/agent registries and alias-based overrides	2026-05-18 08:38:08 +00:00
xiaoju	f84d327410	docs: add .env for API keys, separate from config.yaml	2026-05-18 08:19:48 +00:00
xiaoju	9c2f93629b	docs: add models config (default + extract LLM)	2026-05-18 08:16:03 +00:00
xiaoju	bcefcb9af7	docs: add section 4 — key data types with shared StepRecord	2026-05-18 08:13:18 +00:00
xiaoju	b14dce2bc6	docs: fix inconsistencies — title, terminology, threads.yaml, JSONata context	2026-05-18 08:09:40 +00:00
xiaoju	85c572e770	docs: inline roles/moderator into Workflow, output as cas_ref, detail polymorphic	2026-05-18 08:07:20 +00:00
xiaoju	9a89885ce6	docs: rewrite CAS structure — flatten refs, named conditions, config.yaml, output naming	2026-05-18 07:55:04 +00:00
xiaoju	d095ceaafa	docs: agent CLI takes thread-id + role, outputs CAS hash, step owns pointer	2026-05-18 07:24:14 +00:00
xiaoju	2a0346f48b	docs: simplify show to pure thread-id → head query, all output JSON	2026-05-18 07:18:29 +00:00
xiaoju	b4e25ea002	docs: add done field to step output	2026-05-18 07:12:38 +00:00
xiaoju	77f2060e6b	docs: step on ended thread is an error, not null head	2026-05-18 07:11:50 +00:00
xiaoju	8f9a925179	docs: simplify step output to workflow/thread/head	2026-05-18 07:10:11 +00:00
xiaoju	a7eb9814ae	docs: fix agent invocation format in thread step	2026-05-18 07:05:35 +00:00
xiaoju	a8024e6d42	docs: use full 26-char Crockford Base32 ULIDs for thread IDs	2026-05-18 07:03:40 +00:00
xiaoju	6d94d9c85a	docs: fix hash format to 13-char Crockford Base32 (XXH64)	2026-05-18 07:03:02 +00:00
xiaoju	49a4d08c04	docs: add thread list --all and thread kill	2026-05-18 06:59:47 +00:00
xiaoju	d5773369af	docs: uwf thread subcommands, simplify start output	2026-05-18 06:58:35 +00:00
xiaoju	f49e014f41	docs: update CLI design — uwf naming, simplify commands and agent protocol	2026-05-18 06:56:55 +00:00
xiaoju	ab48a8169d	docs: add stateless workflow CLI design Refs #297	2026-05-18 06:37:25 +00:00
xiaomo	2b707fb44e	Merge pull request 'refactor: replace extractRefs with schema casRef annotations (Phase 2)' (#290 ) from feat/285-phase2-remove-extractrefs into main	2026-05-16 11:50:47 +00:00
				`@@ -0,0 +1 @@`
				`export { buildHermesPrompt, createHermesAgent } from "./hermes.js";`
				`@@ -0,0 +1 @@`
				`export type Result<T, E> = { ok: true; value: T } \| { ok: false; error: E };`