fix: add workspace path sandboxing and UWF_BUILTIN_ALLOW_SHELL check

- Add resolvePathInWorkspace() to reject paths escaping workspace root
- Apply sandboxing to read_file, write_file, and run_command tools
- Gate run_command behind UWF_BUILTIN_ALLOW_SHELL=1 env var
- Add tests for resolvePathInWorkspace escape detection

.gitignore

@@ -11,3 +11,5 @@ solve-issue-entry.ts
 packages/workflow-template-develop/develop.esm.js
 .DS_Store
 *.py
+.claude
+tmp

.plan/335-setup-validate.md

@@ -0,0 +1,83 @@
+# Test Spec: uwf setup model connectivity validation (#335)
+
+## Context
+
+File: `packages/cli-workflow/src/commands/setup.ts`
+Test file: `packages/cli-workflow/src/__tests__/setup-validate.test.ts`
+
+After `cmdSetup` writes config, it should send a test chat completion request to verify the configured model is reachable. If validation fails, warn the user (don't abort — config is already saved).
+
+## Implementation Notes
+
+- Add a `validateModel(baseUrl, apiKey, model)` function that sends a minimal chat completion request (`POST /chat/completions` with `messages: [{role:"user",content:"hi"}]`, `max_tokens: 1`)
+- Returns `Result<void, string>` — ok if 2xx response, error with reason string otherwise
+- Use `AbortSignal.timeout(15_000)` for the request
+- Both `cmdSetup` and `cmdSetupInteractive` should call it after saving config
+- `cmdSetup` returns validation result in its return object: `{ ...existing, validation: { ok: true } | { ok: false, error: string } }`
+- `cmdSetupInteractive` prints a warning to console if validation fails, success message if it passes
+- Use the project logger (`createLogger`) — no raw `console.log` except in interactive CLI output (per CLAUDE.md)
+
+## Test Cases (vitest)
+
+### 1. `validateModel` — success path
+- Mock `fetch` to return `{ status: 200, ok: true, json: () => ({}) }`
+- Call `validateModel(baseUrl, apiKey, model)`
+- Assert returns `{ ok: true, value: undefined }`
+- Assert fetch was called with correct URL (`${baseUrl}/chat/completions`), correct headers (`Authorization: Bearer ${apiKey}`), correct body (model, messages, max_tokens: 1)
+
+### 2. `validateModel` — HTTP error (401 unauthorized)
+- Mock `fetch` to return `{ status: 401, ok: false, statusText: "Unauthorized" }`
+- Call `validateModel(baseUrl, apiKey, model)`
+- Assert returns `{ ok: false, error: <string containing "401"> }`
+
+### 3. `validateModel` — HTTP error (404 model not found)
+- Mock `fetch` to return `{ status: 404, ok: false, statusText: "Not Found" }`
+- Assert returns `{ ok: false, error: <string containing "404"> }`
+
+### 4. `validateModel` — network timeout
+- Mock `fetch` to throw `DOMException` with name `AbortError`
+- Assert returns `{ ok: false, error: <string containing "timeout" or "unreachable"> }`
+
+### 5. `validateModel` — network error (DNS failure, connection refused)
+- Mock `fetch` to throw `TypeError("fetch failed")`
+- Assert returns `{ ok: false, error: <string mentioning connectivity> }`
+
+### 6. `cmdSetup` — includes validation result on success
+- Mock global `fetch` for `/chat/completions` to succeed
+- Call `cmdSetup({ provider, baseUrl, apiKey, model, storageRoot })`
+- Assert returned object has `validation: { ok: true, value: undefined }`
+- Assert config files are still written (existing behavior preserved)
+
+### 7. `cmdSetup` — includes validation result on failure (config still saved)
+- Mock global `fetch` for `/chat/completions` to return 401
+- Call `cmdSetup({ ... })`
+- Assert returned object has `validation: { ok: false, error: ... }`
+- Assert `config.yaml` and `.env` are still written (validation failure doesn't prevent saving)
+
+### 8. `cmdSetupInteractive` — prints success message on validation pass
+- Mock `fetch` for both `/models` and `/chat/completions` to succeed
+- Mock stdin to provide valid selections
+- Capture console output
+- Assert output contains a success message like "Model verified" or "✓"
+
+### 9. `cmdSetupInteractive` — prints warning on validation failure
+- Mock `fetch`: `/models` succeeds, `/chat/completions` returns 401
+- Mock stdin for valid selections
+- Capture console output
+- Assert output contains a warning about model not being reachable and suggests trying a different model
+
+### 10. `validateModel` — request body correctness
+- Mock `fetch` to capture the request body
+- Call `validateModel(baseUrl, apiKey, "test-model")`
+- Assert body is `{ model: "test-model", messages: [{role: "user", content: "hi"}], max_tokens: 1 }`
+
+## Export Requirements
+
+- `validateModel` must be exported (for direct unit testing)
+- Signature: `async function validateModel(baseUrl: string, apiKey: string, model: string): Promise<Result<void, string>>`
+- `Result` type: `{ ok: true; value: T } | { ok: false; error: E }` (project convention)
+
+## Files to Create/Modify
+
+- **New**: `packages/cli-workflow/src/__tests__/setup-validate.test.ts` — all test cases above
+- **Modify**: `packages/cli-workflow/src/commands/setup.ts` — add `validateModel`, integrate into `cmdSetup` and `cmdSetupInteractive`

.workflows/solve-issue.yaml

@@ -0,0 +1,196 @@
+name: "solve-issue"
+description: "TDD-driven issue resolution for small, focused changes. Loop protection relies on engine maxRounds."
+roles:
+  planner:
+    description: "Analyzes issue and outputs a TDD test spec"
+    goal: "You are a planning agent. You analyze Gitea issues and produce a TDD test specification that downstream roles will implement and verify."
+    capabilities:
+      - issue-analysis
+      - planning
+    procedure: |
+      On first run (no previous steps):
+      1. Read the issue and all comments from Gitea using `tea issues <number> -r <owner/repo>`
+      2. Read CLAUDE.md (or equivalent project conventions file) to understand coding standards
+      3. Assess whether the issue has enough information to produce a test spec
+      4. If insufficient info: comment on the issue via `echo "..." | tea comment <number> -r <owner/repo>` (skip if you already commented), then output status=insufficient_info and terminate
+      5. If sufficient: produce a detailed TDD test spec in markdown covering all scenarios
+
+      On subsequent runs (bounced back by tester with fix_spec):
+      1. Read the tester's output from the previous step to understand what's wrong with the spec
+      2. Revise the test spec accordingly
+
+      After producing the test spec:
+      1. Store it via `uwf cas put-text "<markdown content>"` and capture the returned hash
+      2. Put the hash in frontmatter.plan (required when status=ready)
+    output: "Output a brief summary of the test spec. Frontmatter must include: status (ready or insufficient_info) and plan (CAS hash of the test spec, required when status=ready)."
+    frontmatter:
+      type: object
+      properties:
+        status:
+          type: string
+          enum: [ready, insufficient_info]
+        plan:
+          type: string
+      required: [status]
+  developer:
+    description: "TDD implementation per test spec"
+    goal: "You are a developer agent. You implement code changes following TDD — write tests first, then implementation."
+    capabilities:
+      - coding
+    procedure: |
+      Before starting any work, ensure a clean worktree:
+      1. `git checkout main && git pull` to get the latest code
+      2. `git checkout -b fix/<issue-number>-<short-description>` to create a fresh branch
+         - If bounced back from reviewer or tester, reuse the existing branch instead
+
+      Then implement TDD:
+      3. Read the test spec from CAS: `uwf cas get <plan hash>` (find the hash from the latest planner step's frontmatter.plan)
+      4. If bounced back from reviewer or tester: read the previous role's output to understand what needs fixing
+      5. Write tests first based on the spec
+      6. Implement the code to make tests pass
+      7. Ensure `bun run build` passes with no errors
+      8. Run `bun test` to verify all tests pass
+    output: "List all files changed and provide a summary. Frontmatter must include: status (done or failed)."
+    frontmatter:
+      type: object
+      properties:
+        status:
+          type: string
+          enum: [done, failed]
+      required: [status]
+  reviewer:
+    description: "Code standards compliance check"
+    goal: "You are a code reviewer. You verify code standards compliance — NOT functionality (that's the tester's job)."
+    capabilities:
+      - code-review
+      - static-analysis
+    procedure: |
+      Before reviewing, verify the git branch:
+      1. Run `git branch --show-current` — confirm the branch name references the issue number being worked on
+      2. If the branch doesn't correspond to the issue, flag it in your output and reject
+
+      Then perform code review:
+      Hard checks (must all pass):
+      3. `bun run build` — no build errors
+      4. `bunx biome check` — no lint violations
+      5. TypeScript strict mode — no type errors
+
+      Soft checks (review against CLAUDE.md conventions):
+      - Functional-first: `function` + `type`, not `class` + `interface`
+      - No optional properties (`?:`) — use `T | null`
+      - Naming conventions (kebab-case files, PascalCase types, camelCase functions)
+      - Module boundary discipline (folder exports via index.ts)
+      - No `console.log` (use structured logger)
+      - No dynamic imports in production code
+
+      Only review standards compliance. Do NOT test functionality.
+      If rejecting, you MUST explain the specific reason in your output.
+    output: "Explain your decision with specific file/line references. Frontmatter must include: approved (true or false)."
+    frontmatter:
+      type: object
+      properties:
+        approved:
+          type: boolean
+      required: [approved]
+  tester:
+    description: "Functional correctness verification"
+    goal: "You are a tester agent. You verify that the implementation correctly satisfies every scenario in the test spec."
+    capabilities:
+      - testing
+    procedure: |
+      1. Run `bun test` for automated test verification
+      2. Read the test spec from CAS: `uwf cas get <plan hash>` (find the hash from the latest planner step's frontmatter.plan)
+      3. Verify each scenario in the spec is covered and passing
+      4. Determine outcome:
+         - passed: all scenarios verified, tests pass
+         - fix_code: tests fail or implementation doesn't match spec → send back to developer
+         - fix_spec: the spec itself is wrong or incomplete → send back to planner
+    output: "Report test results per scenario. Frontmatter must include: status (passed, fix_code, or fix_spec)."
+    frontmatter:
+      type: object
+      properties:
+        status:
+          type: string
+          enum: [passed, fix_code, fix_spec]
+      required: [status]
+  committer:
+    description: "Commits and creates PR"
+    goal: "You are a committer agent. You create a clean commit and push a PR linking the original issue."
+    capabilities: []
+    procedure: |
+      Note: You inherit the developer's worktree and branch. Do NOT create a new branch.
+      1. Stage all changes: `git add -A`
+      2. Commit with a descriptive message referencing the issue: `git commit -m "type: description\n\nFixes #N"`
+      3. Push the branch: `git push -u origin <branch-name>`
+         - If push hook fails: capture the error log in your output, mark hook_failed
+      4. On push success: create a PR via `tea pr create --title "..." --description "..."`
+         - PR description must follow the project template: What / Why / Changes / Ref sections, with `Fixes #N` in Ref
+    output: "Include PR URL on success or error log on failure. Frontmatter must include: success (true or false)."
+    frontmatter:
+      type: object
+      properties:
+        success:
+          type: boolean
+      required: [success]
+conditions:
+  insufficientInfo:
+    description: "Planner determined there's not enough info to proceed"
+    expression: "$last('planner').status = 'insufficient_info'"
+  devFailed:
+    description: "Developer failed to implement"
+    expression: "$last('developer').status = 'failed'"
+  rejected:
+    description: "Reviewer rejected the implementation"
+    expression: "$last('reviewer').approved = false"
+  fixCode:
+    description: "Tester found code issues"
+    expression: "$last('tester').status = 'fix_code'"
+  fixSpec:
+    description: "Tester found spec issues"
+    expression: "$last('tester').status = 'fix_spec'"
+  hookFailed:
+    description: "Push hook failed"
+    expression: "$last('committer').success = false"
+graph:
+  $START:
+    - role: "planner"
+      condition: null
+      prompt: "Analyze the issue and produce an implementation plan."
+  planner:
+    - role: "$END"
+      condition: "insufficientInfo"
+      prompt: "Insufficient information to proceed; end the workflow."
+    - role: "developer"
+      condition: null
+      prompt: "Implement the plan from the planner."
+  developer:
+    - role: "$END"
+      condition: "devFailed"
+      prompt: "Development failed; end the workflow."
+    - role: "reviewer"
+      condition: null
+      prompt: "Send the implementation to the reviewer."
+  reviewer:
+    - role: "developer"
+      condition: "rejected"
+      prompt: "Reviewer rejected the implementation; fix the issues."
+    - role: "tester"
+      condition: null
+      prompt: "Review passed; run tests on the implementation."
+  tester:
+    - role: "developer"
+      condition: "fixCode"
+      prompt: "Tests found code issues; return to developer."
+    - role: "planner"
+      condition: "fixSpec"
+      prompt: "Tests found spec issues; return to planner."
+    - role: "committer"
+      condition: null
+      prompt: "Tests passed; commit and push the changes."
+  committer:
+    - role: "developer"
+      condition: "hookFailed"
+      prompt: "Push hook failed; return to developer to fix."
+    - role: "$END"
+      condition: null
+      prompt: "Commit succeeded; complete the workflow."

biome.json

@@ -5,6 +5,8 @@
       "**",
       "!**/dist",
       "!**/node_modules",
+      "!**/legacy-packages",
+      "!scripts",
       "!packages/workflow/workflow",
       "!xiaoju/scripts/bundle.ts"
     ]
@@ -36,7 +38,7 @@
       }
     },
     {
-      "includes": ["**/*.d.ts"],
+      "includes": ["**/*.d.ts", "**/vitest.config.*"],
       "linter": {
         "rules": {
           "style": {
@@ -44,6 +46,16 @@
           }
         }
       }
+    },
+    {
+      "includes": ["**/cli.ts", "**/setup.ts"],
+      "linter": {
+        "rules": {
+          "suspicious": {
+            "noConsole": "off"
+          }
+        }
+      }
     }
   ],
   "linter": {

docs/architecture.md

@@ -85,8 +85,13 @@ 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:
+    goal: "You are a planning agent. Analyze the issue and create a step-by-step plan."
+    capabilities:
+      - issue-analysis
+      - planning
+    procedure: "Analyze the issue and create a detailed, actionable implementation plan."
+    output: "Output the plan summary and list of concrete steps."
+    meta:
       type: object
       properties:
         plan: { type: string }
@@ -94,8 +99,13 @@ roles:
       required: [plan, steps]
   developer:
     description: "Implements code changes"
-    systemPrompt: "You are a developer agent. Implement the plan."
-    outputSchema:
+    goal: "You are a developer agent. Implement the plan."
+    capabilities:
+      - file-edit
+      - shell
+    procedure: "Implement the plan. Write code, tests, and ensure existing tests pass."
+    output: "List all files changed and provide a summary of the implementation."
+    meta:
       type: object
       properties:
         filesChanged: { type: array, items: { type: string } }
@@ -103,8 +113,12 @@ roles:
       required: [filesChanged, summary]
   reviewer:
     description: "Reviews code changes"
-    systemPrompt: "You are a code reviewer. Review the implementation."
-    outputSchema:
+    goal: "You are a code reviewer. Review the implementation."
+    capabilities:
+      - code-review
+    procedure: "Review the implementation against the plan."
+    output: "Approve or reject with detailed comments."
+    meta:
       type: object
       properties:
         approved: { type: boolean }
@@ -133,7 +147,7 @@ graph:
 
 Key properties:
 
-- **`roles`** — inline role definitions; each `outputSchema` is a JSON Schema (stored as its own CAS node on registration)
+- **`roles`** — inline role definitions; each `meta` is a JSON Schema (stored as its own CAS node on registration)
 - **`conditions`** — named JSONata expressions evaluated against the `ModeratorContext`
 - **`graph`** — `Record<Role | "$START", Transition[]>` — first matching transition wins; `condition: null` = fallback
 - **No agent binding** — agent selection is a deployment concern, configured in `config.yaml`
@@ -156,7 +170,7 @@ Each `uwf thread step` runs exactly one cycle: moderator → agent → extract.
 │   Output: raw string (frontmatter markdown)
 │
 │   Phase 3: EXTRACT
-│   Input:  raw agent output + role's outputSchema
+│   Input:  raw agent output + role's meta schema
 │   Engine: two-layer extract (frontmatter fast path → LLM fallback)
 │   Output: CasRef to structured output node
 │
@@ -213,7 +227,7 @@ Contract:
    - Parses argv
    - Loads `.env` from storage root
    - Builds `AgentContext` by walking the CAS chain from `threads.yaml` head
-   - Resolves the role's `outputSchema` and builds `outputFormatInstruction`
+   - Resolves the role's `meta` schema and builds `outputFormatInstruction`
    - Calls the agent's `run` function
    - Runs two-layer extract on the raw output
    - Writes `StepNode` to CAS (output + detail + prev link)
@@ -242,7 +256,7 @@ scope: role
 Fixed the login redirect by updating the auth middleware...
 ```
 
-The `outputFormatInstruction` (built by `buildOutputFormatInstruction` in `workflow-agent-kit`) is prepended to the role's system prompt, so the deliverable format is the first thing the agent sees. It lists the expected frontmatter fields derived from the role's JSON Schema.
+The `outputFormatInstruction` (built by `buildOutputFormatInstruction` in `workflow-agent-kit`) is prepended to the role's system prompt, so the deliverable format is the first thing the agent sees. It lists the expected frontmatter fields derived from the role's `meta` JSON Schema.
 
 ## Two-layer extract
 
@@ -253,7 +267,7 @@ Structured output extraction uses a two-layer strategy (`workflow-agent-kit`):
 1. Parse YAML frontmatter from raw agent output (`parseFrontmatterMarkdown`)
 2. Validate required fields (`validateFrontmatter`)
 3. Build a candidate object from frontmatter fields (`status`, `next`, `confidence`, `artifacts`, `scope`)
-4. `store.put()` the candidate against the role's `outputSchema`
+4. `store.put()` the candidate against the role's `meta` schema
 5. Validate with `json-cas` schema validation
 6. If valid → return `outputHash` (zero LLM cost)
 
@@ -272,7 +286,7 @@ If the fast path returns `null` (no frontmatter, invalid, or doesn't satisfy sch
 
 `workflow-agent-kit` prepends two pieces of context to the agent's system prompt:
 
-1. **Deliverable format instruction** — generated from the role's `outputSchema`, tells the agent exactly what frontmatter fields to produce and the expected format
+1. **Deliverable format instruction** — generated from the role's `meta` schema, tells the agent exactly what frontmatter fields to produce and the expected format
 2. **Scope constraint** — "Focus exclusively on YOUR role's deliverable. Do not perform actions outside your role's scope."
 
 This ensures agents produce parseable frontmatter output without requiring per-agent format knowledge.
@@ -289,8 +303,11 @@ payload:
   roles:
     planner:
       description: "Creates implementation plan"
-      systemPrompt: "You are a planning agent..."
-      outputSchema: "5GWKR8TN1V3JA"    # cas_ref → JSON Schema node
+      goal: "You are a planning agent..."
+      capabilities: [planning, issue-analysis]
+      procedure: "Analyze the issue and create a plan."
+      output: "Output the plan summary."
+      meta: "5GWKR8TN1V3JA"    # cas_ref → JSON Schema node
   conditions:
     notApproved:
       description: "Reviewer rejected"
@@ -318,7 +335,7 @@ payload:
   start: "4TNVW8KR2B3MA"      # cas_ref → StartNode
   prev: "2MXBG6PN4A8JR"       # cas_ref → previous StepNode (null for first step)
   role: "developer"
-  output: "9KRVW3TN5F1QA"     # cas_ref → structured output (validated against outputSchema)
+  output: "9KRVW3TN5F1QA"     # cas_ref → structured output (validated against meta schema)
   detail: "7BQST3VW9F2MA"     # cas_ref → execution detail (raw turns, session data)
   agent: "uwf-hermes"         # agent command used (plain string)
 ```

docs/builtin-agent-research.md

@@ -0,0 +1,779 @@
+# Built-in Role Agent 调研
+
+## 目标
+
+实现一个内置的 role agent（暂称 `uwf-builtin`），不依赖 hermes/openclaw 等外部 agent 进程。
+直接使用 workflow config 中配置的 model，自己实现 agent run loop 和关键 toolkit。
+
+---
+
+## 关键问题
+
+### Q1: Agent 接口协议
+
+现有 agent 是怎么被 CLI 调用的？输入（argv、环境变量）和输出（stdout、CAS）格式是什么？
+
+**调研要点：**
+- `cli-workflow` 里 `spawnAgent` 的完整实现
+- AgentConfig 类型定义
+- agent 进程的 exit code 约定
+- 环境变量传递（UWF_STORAGE_ROOT 等）
+
+**答案：**
+
+#### 调用链
+
+`uwf thread step` → `cmdThreadStepOnce` → moderator 求值下一 role → `resolveAgentConfig` → `spawnAgent`。
+
+#### AgentConfig 类型
+
+```146:149:packages/workflow-protocol/src/types.ts
+export type AgentConfig = {
+  command: string;
+  args: string[];
+};
+```
+
+在 `config.yaml` 的 `agents` 段注册，例如 `hermes: { command: "uwf-hermes", args: [] }`。
+
+#### spawnAgent 行为
+
+```627:653:packages/cli-workflow/src/commands/thread.ts
+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) {
+  // ... stderr 拼进 fail 消息
+  }
+
+  const line = stdout.trim().split("\n").pop()?.trim() ?? "";
+  if (!isCasRef(line)) {
+    fail(`agent stdout is not a valid CAS hash: ${line || "(empty)"}`);
+  }
+  return line;
+}
+```
+
+| 项目 | 约定 |
+|------|------|
+| **argv** | `[...agent.args, <thread-id>, <role>]`，即 `process.argv[2]`=threadId，`process.argv[3]`=role（与 `createAgent` 的 `parseArgv` 一致） |
+| **stdin** | 忽略 |
+| **stdout** | 纯文本，**最后一行**必须是新 `StepNode` 的 CAS hash（13 字符 Crockford Base32） |
+| **stderr** | 失败时 CLI 会附带 stderr；成功时无约定 |
+| **exit code** | `0` = 成功；非 0 时 `execFileSync` 抛错，step 失败 |
+| **环境变量** | 继承父进程 `process.env`（含 storage root、API key 等） |
+| **链头更新** | **不由 agent 负责**；agent 只写 CAS StepNode，CLI 在拿到 stdout hash 后更新 `threads.yaml` |
+
+Agent 解析优先级（`resolveAgentConfig`）：
+
+1. CLI `--agent` override（整段 command + args 字符串）
+2. `config.agentOverrides[workflow.name][role]`
+3. `config.defaultAgent`
+
+#### 环境变量：Storage Root
+
+文档中写的 `UWF_STORAGE_ROOT` **在当前代码中不存在**。实际优先级（`workflow-agent-kit` / `cli-workflow` 一致）：
+
+```33:43:packages/workflow-agent-kit/src/storage.ts
+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();
+}
+```
+
+Agent 子进程通过继承的 `process.env` 与父 CLI 共享同一 storage root；`createAgent` 内还会 `loadDotenv({ path: getEnvPath(storageRoot) })` 加载 `~/.uncaged/workflow/.env`。
+
+#### Agent 侧职责（设计文档 + 实现）
+
+- 读 `threads.yaml` 链头，构建 context，执行 role
+- 将 `StepNode` 写入 CAS（`output` / `detail` / `agent` / `prev` / `start`）
+- stdout 打印 step hash
+- **不**更新 `threads.yaml`
+
+---
+
+### Q2: createAgent 工厂
+
+workflow-agent-kit 的 `createAgent` 做了什么？它的完整生命周期是什么？
+
+**调研要点：**
+- `AgentOptions` 类型的 `run` 和 `continue` 回调签名
+- `AgentRunResult` 的完整定义
+- retry 逻辑（frontmatter 校验失败后的重试机制）
+- `persistStep` 写入 CAS 的 StepNode 结构
+
+**答案：**
+
+#### 类型定义
+
+```4:35:packages/workflow-agent-kit/src/types.ts
+export type AgentContext = ModeratorContext & {
+  threadId: ThreadId;
+  role: string;
+  store: Store;
+  workflow: WorkflowPayload;
+  outputFormatInstruction: string;
+};
+
+export type AgentRunResult = {
+  output: string;
+  detailHash: CasRef;
+  sessionId: string;
+};
+
+export type AgentContinueFn = (
+  sessionId: string,
+  message: string,
+  store: AgentContext["store"],
+) => Promise<AgentRunResult>;
+
+export type AgentRunFn = (ctx: AgentContext) => Promise<AgentRunResult>;
+
+export type AgentOptions = {
+  name: string;
+  run: AgentRunFn;
+  continue: AgentContinueFn;
+};
+```
+
+- **`run(ctx)`**：首次执行，返回原始 agent 文本 `output`、审计用 `detailHash`、用于续聊的 `sessionId`。
+- **`continue(sessionId, message, store)`**：在同一 session 上追加用户消息（用于 frontmatter 纠错），再次返回 `AgentRunResult`。
+
+`createAgent(options)` 返回 `() => Promise<void>`，作为 agent CLI 的 `main`（见 `uwf-hermes` 的 `cli.ts`）。
+
+#### 生命周期（按执行顺序）
+
+```101:152:packages/workflow-agent-kit/src/run.ts
+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 buildContextWithMeta(threadId, role);
+    // 1. 校验 role 存在
+    // 2. 从 CAS 取 frontmatter JSON Schema → buildOutputFormatInstruction → ctx.outputFormatInstruction
+
+    let agentResult = await options.run(ctx);
+
+    let outputHash = await tryExtractOutput(agentResult.output, roleDef.frontmatter, ctx);
+
+    for (let retry = 0; retry < MAX_FRONTMATTER_RETRIES && outputHash === null; retry++) {
+      const correctionMessage = "Your previous response did not contain valid YAML frontmatter...";
+      agentResult = await options.continue(agentResult.sessionId, correctionMessage, ctx.meta.store);
+      outputHash = await tryExtractOutput(agentResult.output, roleDef.frontmatter, ctx);
+    }
+
+    if (outputHash === null) { fail(...); }
+
+    const stepHash = await persistStep({ ctx, outputHash, detailHash: agentResult.detailHash, agentName });
+    process.stdout.write(`${stepHash}\n`);
+  };
+}
+```
+
+| 阶段 | 行为 |
+|------|------|
+| 解析 argv | `argv[2]=threadId`, `argv[3]=role`，缺失则 `stderr` + `exit(1)` |
+| Context | `buildContextWithMeta` + 可选 `outputFormatInstruction` |
+| Run | `options.run(ctx)` |
+| Extract | **仅** `tryFrontmatterFastPath`（见 Q4）；**不**调用 `extract()` LLM fallback |
+| Retry | 最多 `MAX_FRONTMATTER_RETRIES = 2` 次 `continue` + 再试 fast-path |
+| Persist | `persistStep` → `writeStepNode` |
+| 输出 | stdout 一行 step CAS hash |
+
+#### StepNode 写入结构
+
+```44:68:packages/workflow-agent-kit/src/run.ts
+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,
+  };
+  // store.put(stepNode schema) + validate
+}
+```
+
+`agentName` 经 `agentLabel(name)` 规范化：已有 `uwf-` 前缀则原样，否则加 `uwf-`（如 `hermes` → `uwf-hermes`）。
+
+`prevHash`：若链头仍是 `StartNode` 则为 `null`，否则为当前 head step hash。
+
+---
+
+### Q3: Context Builder
+
+`buildContextWithMeta` 构建了什么上下文给 agent？
+
+**调研要点：**
+- `AgentContext` 完整类型定义（所有字段）
+- context 构建过程（CAS chain walk）
+- `outputFormatInstruction` 怎么生成的
+- role definition 怎么获取（从 workflow YAML）
+
+**答案：**
+
+#### AgentContext 字段
+
+继承 `ModeratorContext`：
+
+```60:68:packages/workflow-protocol/src/types.ts
+export type ModeratorContext = {
+  start: StartNodePayload;
+  steps: StepContext[];
+};
+```
+
+```48:51:packages/workflow-protocol/src/types.ts
+export type StartNodePayload = {
+  workflow: CasRef;
+  prompt: string;
+};
+```
+
+```61:63:packages/workflow-protocol/src/types.ts
+export type StepContext = Omit<StepRecord, "output"> & {
+  output: unknown;
+};
+```
+
+`AgentContext` 额外字段：
+
+| 字段 | 类型 | 含义 |
+|------|------|------|
+| `threadId` | `ThreadId` | 当前线程 |
+| `role` | `string` | 本步要执行的角色名 |
+| `store` | `Store` | CAS store（读写节点） |
+| `workflow` | `WorkflowPayload` | 已从 CAS 加载的 workflow 定义 |
+| `outputFormatInstruction` | `string` | 由 `createAgent` 根据 role 的 frontmatter schema 生成；`buildContext*` 初始为 `""` |
+
+`buildContextWithMeta` 还返回 `meta`：
+
+```148:154:packages/workflow-agent-kit/src/context.ts
+export type BuildContextMeta = {
+  storageRoot: string;
+  store: Store;
+  schemas: AgentStore["schemas"];
+  headHash: CasRef;
+  chain: ChainState;
+};
+```
+
+#### CAS chain walk
+
+1. 从 `threads.yaml[threadId]` 取 `headHash`
+2. `walkChain`：若 head 是 `StartNode`，`stepsNewestFirst=[]`；否则沿 `prev` 收集所有 `StepNode`， newest-first
+3. `buildHistory`：反转为时间序，`expandOutput` 把每步 `output` CasRef 展开为 JSON payload（供 prompt / JSONata 使用）
+4. `loadWorkflow`：从 `start.workflow` CasRef 加载 `WorkflowPayload`
+
+#### Role definition 来源
+
+- 作者写在 workflow YAML 的 `roles.<name>`（`goal`, `capabilities`, `procedure`, `output`, `frontmatter` 等）
+- `uwf workflow put` 时 `frontmatter` 内联 JSON Schema 经 `putSchema` 存入 CAS，workflow 里存的是 **CasRef**
+- Agent 运行时：`ctx.workflow.roles[ctx.role]` → `RoleDefinition`
+
+#### outputFormatInstruction
+
+在 `createAgent` 中，若 `getSchema(store, roleDef.frontmatter)` 非空，则：
+
+```typescript
+ctx.outputFormatInstruction = buildOutputFormatInstruction(frontmatterSchema);
+```
+
+`buildOutputFormatInstruction` 根据 JSON Schema 的 `properties` 生成「必须以 `---` YAML frontmatter 开头」的说明和示例字段列表（见 `build-output-format-instruction.ts`）。
+
+各 agent 实现（Hermes / Claude Code）在组装 prompt 时把该块放在最前，再接 `buildRolePrompt(roleDef)`。
+
+---
+
+### Q4: Extract Pipeline
+
+agent 输出怎么被处理成结构化数据？
+
+**调研要点：**
+- frontmatter fast-path 的完整逻辑
+- LLM extract fallback 的实现（`extract.ts`）
+- frontmatter schema 从哪里来（role 定义里的 `frontmatter` 字段）
+- 校验失败时的 correction prompt 是什么
+
+**答案：**
+
+#### Schema 来源
+
+Workflow YAML 中每个 role 的 `frontmatter:` 段是 JSON Schema 对象；注册时：
+
+```66:76:packages/cli-workflow/src/commands/workflow.ts
+async function resolveFrontmatterRef(..., frontmatter: unknown): Promise<CasRef> {
+  // 校验为 JSON Schema → putSchema → 返回 CasRef
+}
+```
+
+运行时 `roleDef.frontmatter` 即该 schema 的 CAS hash；structured `output` 节点用**同一 schema** 写入 CAS。
+
+#### Frontmatter fast-path（createAgent 实际使用的路径）
+
+```148:195:packages/workflow-agent-kit/src/frontmatter.ts
+export async function tryFrontmatterFastPath(
+  raw: string,
+  outputSchema: CasRef,
+  store: Store,
+): Promise<FrontmatterFastPathResult | null>
+```
+
+流程：
+
+1. `parseFrontmatterMarkdown(raw)` → 标准 agent 字段（`status`, `next`, `confidence`, `artifacts`, `scope`）+ body
+2. `validateFrontmatter` 失败 → `null`
+3. `getSchema(store, outputSchema)` + `extractSchemaFields` 得到 role 需要的属性名
+4. `buildCandidate`：从标准 frontmatter + YAML 原始字段拼出符合 schema 的对象
+5. `store.put(outputSchema, candidate)` + `validate` → 成功则 `{ body, outputHash }`
+
+**永不抛错**，失败返回 `null`。
+
+#### LLM extract fallback（已实现但未接入 createAgent）
+
+```135:181:packages/workflow-agent-kit/src/extract.ts
+export async function extract(
+  rawOutput: string,
+  outputSchema: CasRef,
+  config: WorkflowConfig,
+): Promise<ExtractResult>
+```
+
+- 模型：`resolveExtractModelAlias(config)` → `modelOverrides.extract` → `models.extract` → `models.default` → `defaultModel`
+- HTTP：`POST {baseUrl}/chat/completions`，`response_format: { type: "json_object" }`
+- System：要求按 JSON Schema 从 agent 输出提取单个 JSON 对象
+- 校验通过后 `store.put(outputSchema, structured)`
+
+**重要：`createAgent` 当前未调用 `extract()`**。fast-path 失败且 2 次 `continue` 仍失败则直接 `fail()`。builtin agent 若希望无 frontmatter 也能跑，需在 kit 或 builtin 层显式接入 `extract()`。
+
+#### Correction prompt（retry）
+
+```125:128:packages/workflow-agent-kit/src/run.ts
+const correctionMessage =
+  "Your previous response did not contain valid YAML frontmatter matching the role schema.\n" +
+  "You MUST begin your response with a YAML frontmatter block (--- delimited).\n" +
+  "Please output ONLY the corrected frontmatter block followed by your work.";
+```
+
+通过 `options.continue(sessionId, correctionMessage, store)` 发给外部 agent；builtin 需在自有 message 历史里 append 同等语义的 user 消息。
+
+---
+
+### Q5: Model 配置与 LLM 调用
+
+workflow 怎么配置和使用 model？
+
+**调研要点：**
+- `WorkflowConfig` 中 providers/models/defaultModel/modelOverrides 的完整定义
+- `resolveModel` 函数的实现
+- `chatCompletionText` 的实现（OpenAI 兼容 HTTP 客户端）
+- 有没有 streaming 支持？tool calling 支持？
+
+**答案：**
+
+#### WorkflowConfig
+
+```136:160:packages/workflow-protocol/src/types.ts
+export type ProviderConfig = {
+  baseUrl: string;
+  apiKeyEnv: string;
+};
+
+export type ModelConfig = {
+  provider: ProviderAlias;
+  name: string;
+};
+
+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;
+};
+```
+
+示例见 `docs/architecture.md`（`providers` / `models` / `defaultModel` / `modelOverrides.extract`）。
+
+#### resolveModel
+
+```32:50:packages/workflow-agent-kit/src/extract.ts
+export function resolveModel(config: WorkflowConfig, alias: ModelAlias): ResolvedLlmProvider {
+  const modelEntry = config.models[alias];
+  const providerEntry = config.providers[modelEntry.provider];
+  const apiKey = process.env[providerEntry.apiKeyEnv];
+  return { baseUrl: providerEntry.baseUrl, apiKey, model: modelEntry.name };
+}
+```
+
+`ResolvedLlmProvider = { baseUrl, apiKey, model }`。
+
+Extract 专用别名解析：
+
+```18:30:packages/workflow-agent-kit/src/extract.ts
+export function resolveExtractModelAlias(config: WorkflowConfig): ModelAlias {
+  return config.modelOverrides?.extract ?? (config.models.extract ? "extract" : config.models.default ? "default" : config.defaultModel);
+}
+```
+
+**尚无** `modelOverrides` 按 role/workflow 解析 agent 主模型的函数；builtin 首版可用 `config.defaultModel`，扩展时可加 `modelOverrides.agent` 或与 `agentOverrides` 对称的表。
+
+#### chatCompletionText
+
+```87:124:packages/workflow-agent-kit/src/extract.ts
+async function chatCompletionText(
+  provider: ResolvedLlmProvider,
+  messages: Array<{ role: "system" | "user"; content: string }>,
+): Promise<string>
+```
+
+| 能力 | 现状 |
+|------|------|
+| 协议 | OpenAI 兼容 `POST /chat/completions` |
+| Streaming | **无**（一次性 `response.text()`） |
+| Tool calling | **无**（无 `tools` / `tool_calls` 字段） |
+| 多模态 | **无**（仅 text `content`） |
+| Extract 专用 | `response_format: { type: "json_object" }` |
+
+builtin agent 的 run loop 需要**新写**带 `tools` 的 completion 客户端（可放在 `workflow-agent-builtin` 或扩展 `workflow-agent-kit` 的 `llm/` 模块），不能复用当前 `chatCompletionText` 而不改。
+
+---
+
+### Q6: Hermes Agent 参考实现
+
+`uwf-hermes` 是怎么实现 `run` 和 `continue` 的？
+
+**调研要点：**
+- prompt 怎么组装的（outputFormatInstruction + rolePrompt + task + history）
+- hermes CLI 的调用参数
+- session management（resume）
+- 输出怎么捕获
+
+**答案：**
+
+#### Prompt 组装
+
+```40:53:packages/workflow-agent-hermes/src/hermes.ts
+export function buildHermesPrompt(ctx: AgentContext): string {
+  const roleDef = ctx.workflow.roles[ctx.role];
+  const rolePrompt = roleDef !== undefined ? buildRolePrompt(roleDef) : "";
+  const parts: string[] = [];
+  if (ctx.outputFormatInstruction !== "") {
+    parts.push(ctx.outputFormatInstruction, "");
+  }
+  parts.push(rolePrompt, "", "## Task", ctx.start.prompt);
+  const historyBlock = buildHistorySummary(ctx.steps);
+  if (historyBlock !== "") {
+    parts.push("", historyBlock);
+  }
+  return parts.join("\n");
+}
+```
+
+`buildRolePrompt` 生成 `## Goal` / `## Capabilities` / `## Prepare`（含 `generateCliReference()`）/ `## Procedure` / `## Output`。
+
+`buildHistorySummary`：每步 `role`、`JSON.stringify(step.output)`、`agent`。
+
+Hermes 把**整段 prompt 作为单条 user 消息**传给 `hermes chat -q`（无独立 system channel）。
+
+#### Hermes CLI 参数
+
+首次：
+
+```88:97:packages/workflow-agent-hermes/src/hermes.ts
+spawnHermes(["chat", "-q", prompt, "--yolo", "--max-turns", "90", "--quiet"]);
+```
+
+续聊：
+
+```100:114:packages/workflow-agent-hermes/src/hermes.ts
+spawnHermes(["chat", "--resume", sessionId, "-q", message, "--yolo", "--max-turns", "90", "--quiet"]);
+```
+
+#### Session
+
+- stdout/stderr 中解析 `session_id: <id>`（`parseSessionIdFromStdout`）
+- 会话文件：`~/.hermes/sessions/session_<id>.json`
+- `loadHermesSession` → `storeHermesSessionDetail`：每 assistant/tool 消息写成 CAS turn 节点，汇总为 `detail`；**output 文本** = 最后一条非空 `assistant` 的 `content`
+
+#### 与 createAgent 的衔接
+
+```157:164:packages/workflow-agent-hermes/src/hermes.ts
+export function createHermesAgent(): () => Promise<void> {
+  return createAgent({ name: "hermes", run: runHermes, continue: continueHermes });
+}
+```
+
+`uwf-hermes` 入口：`createHermesAgent()` 即 main。
+
+Claude Code 包（`workflow-agent-claude-code`）结构相同：`buildClaudeCodePrompt` 同构，`claude -p` + `--resume` + JSON stdout 解析。
+
+---
+
+### Q7: Toolkit 需求分析
+
+要实现一个自给自足的 agent，最少需要哪些 tool？
+
+**调研要点：**
+- 现有 workflow example（solve-issue.yaml）里 role 都做什么任务
+- hermes agent 在 workflow 场景下常用哪些 tool
+- 哪些 tool 是 agent loop 必须的（如 file read/write、shell exec、web fetch）
+
+**答案：**
+
+#### solve-issue.yaml 角色能力
+
+| Role | capabilities | 隐含需求 |
+|------|----------------|----------|
+| planner | issue-analysis, planning | 读上下文/仓库、总结，通常不需写代码 |
+| developer | file-edit, shell, testing | **读文件、写文件、执行命令** |
+| reviewer | code-review, static-analysis | 读 diff/文件、静态分析（可读+可选 shell） |
+
+#### Hermes 侧
+
+Hermes 自带完整 agent runtime（`--yolo`、max-turns），tool 集由 Hermes 项目定义，workflow 不配置。从 session JSON 可见 `tool_calls` 被记入 detail，常见包括文件与 shell 类工具。
+
+#### Builtin 最小 toolkit 建议
+
+| 优先级 | Tool | 用途 |
+|--------|------|------|
+| P0 | `read_file` | 读仓库/配置/issue 上下文 |
+| P0 | `write_file` / `edit_file` | developer 改代码 |
+| P0 | `run_command` | 测试、构建、git（需 cwd + timeout + 输出截断） |
+| P1 | `list_dir` / `glob` | 导航代码库 |
+| P1 | `grep` | 搜索符号/引用 |
+| P2 | `fetch_url` | 查文档（planner 偶尔需要） |
+
+**不需要**在 builtin 里实现 moderator / workflow 路由工具——仍由 `uwf thread step` + JSONata 负责。
+
+#### Agent loop 必须能力
+
+1. 多轮 LLM 调用 + **OpenAI-style tool_calls** 解析与执行
+2. 将 tool 结果 append 回 messages
+3. 终止条件：模型不再请求 tool，或达到 `maxTurns`
+4. 最终响应须含合法 YAML frontmatter（满足 Q4），供 `createAgent` fast-path
+
+---
+
+## 方案草案
+
+（调研完成后基于以上答案撰写）
+
+### 架构设计
+
+```mermaid
+flowchart TB
+  subgraph cli ["cli-workflow"]
+    Step["uwf thread step"]
+    Spawn["spawnAgent(uwf-builtin, threadId, role)"]
+    Step --> Spawn
+  end
+
+  subgraph builtin_pkg ["@uncaged/workflow-agent-builtin"]
+    Main["createBuiltinAgent() = createAgent({...})"]
+    Prompt["buildBuiltinPrompt(ctx)"]
+    Loop["runBuiltinLoop(provider, messages, tools)"]
+    Tools["Toolkit: read/write/exec/..."]
+    Detail["storeBuiltinDetail(turns)"]
+    Main --> Prompt
+    Main --> Loop
+    Loop --> Tools
+    Loop --> Detail
+  end
+
+  subgraph kit ["workflow-agent-kit"]
+    Ctx["buildContextWithMeta"]
+    FM["tryFrontmatterFastPath"]
+    Persist["persistStep"]
+    Ctx --> Main
+    Main --> FM
+    FM --> Persist
+  end
+
+  subgraph cas ["CAS / config"]
+    Config["config.yaml models/providers"]
+    CAS["cas/ + threads.yaml"]
+  end
+
+  Spawn --> Main
+  Config --> Loop
+  CAS --> Ctx
+  Persist --> CAS
+  Spawn -->|"stdout: step hash"| Step
+```
+
+**新包**：`packages/workflow-agent-builtin`，bin `uwf-builtin`，仅依赖 `workflow-agent-kit`、`workflow-protocol`、`workflow-util`（可选 `@uncaged/json-cas` 写 detail schema）。
+
+**分层**：
+
+| 层 | 职责 |
+|----|------|
+| `createAgent`（kit） | argv、context、frontmatter extract、StepNode、stdout 协议 — **不变** |
+| `builtin/agent.ts` | `run` / `continue` 实现 |
+| `builtin/llm.ts` | OpenAI 兼容 chat + tools（可后续抽到 kit） |
+| `builtin/tools/*.ts` | 各 tool 的 JSON Schema + handler |
+| `builtin/prompt.ts` | 复用 Hermes 的 prompt 拼接逻辑（或抽到 kit 的 `buildAgentPrompt`） |
+| `builtin/detail.ts` | 类似 Hermes：每轮 assistant/tool 写入 CAS detail |
+
+**配置集成**：
+
+```yaml
+agents:
+  builtin:
+    command: "uwf-builtin"
+    args: []
+defaultAgent: "builtin"   # 或 agentOverrides 按 role 指定
+```
+
+模型：首版 `resolveModel(config, config.defaultModel)`；后续可增加 `modelOverrides.agent` 或 per-role 映射。
+
+---
+
+### Agent Run Loop
+
+伪代码（单次 `run(ctx)`）：
+
+```
+1. provider ← resolveModel(loadWorkflowConfig(), defaultModel)
+2. system ← buildBuiltinPrompt(ctx)   // outputFormatInstruction + buildRolePrompt + Task + History
+3. messages ← [{ role: "system", content: system }]
+4. sessionId ← newULID()              // 内存或临时目录，供 continue 使用
+5. turns ← []
+
+6. for turn in 1..MAX_TURNS:
+     response ← chatCompletionWithTools(provider, messages, TOOL_DEFINITIONS)
+     record assistant message + tool_calls in turns
+
+     if response has no tool_calls:
+       finalText ← response.content
+       break
+
+     for each tool_call:
+       result ← executeTool(tool_call, { cwd: process.cwd() })
+       messages.push tool result
+       record in turns
+
+7. if no finalText with valid frontmatter after loop:
+     optionally one-shot "finalize" message without tools
+
+8. detailHash ← storeBuiltinDetail(store, sessionId, turns, metadata)
+9. return { output: finalText, detailHash, sessionId }
+```
+
+**`continue(sessionId, message, store)`**：
+
+- 从内存/磁盘恢复 `messages` + `turns`
+- `messages.push({ role: "user", content: message })`（correction 或续聊）
+- 从步骤 6 继续，步数上限可单独设小一点（如 3）
+- 返回新的 `AgentRunResult`
+
+**与 frontmatter 的配合**：
+
+- system prompt 已含 `outputFormatInstruction`；最后一轮可强制 user：`Now output your final answer with YAML frontmatter only if you have not yet.`
+- 仍依赖 `createAgent` 的 fast-path + 最多 2 次 continue
+
+**安全**：
+
+- `run_command`：白名单或需 `UWF_BUILTIN_ALLOW_SHELL=1`，默认工作区限定在 `process.cwd()` 或 `start` 中将来扩展的 `workspace` 字段
+- 路径：禁止 `..` 逃逸出 workspace root
+
+---
+
+### Toolkit 设计
+
+统一注册表：
+
+```typescript
+type BuiltinTool = {
+  name: string;
+  description: string;
+  parameters: JSONSchema; // object type
+  execute: (args: unknown, ctx: ToolContext) => Promise<string>;
+};
+
+type ToolContext = {
+  cwd: string;
+  storageRoot: string;
+};
+```
+
+| Tool name | OpenAI function | 行为摘要 |
+|-----------|-----------------|----------|
+| `read_file` | `read_file` | `{ path }` → UTF-8 文本，大小上限 |
+| `write_file` | `write_file` | `{ path, content }` → 写盘，返回确认 |
+| `edit_file` | 可选 | search/replace 块，减少 token |
+| `run_command` | `run_command` | `{ command, cwd? }` → stdout/stderr 截断 |
+| `list_dir` | `list_dir` | `{ path }` → 条目列表 |
+| `grep` | `grep` | `{ pattern, path? }` → 匹配行 |
+
+**LLM 请求形状**（扩展 extract 客户端）：
+
+```json
+{
+  "model": "...",
+  "messages": [...],
+  "tools": [{ "type": "function", "function": { "name", "description", "parameters" } }],
+  "tool_choice": "auto"
+}
+```
+
+解析 `choices[0].message.tool_calls`，执行后以 `{ role: "tool", tool_call_id, content }` 回传。
+
+**不提供** streaming 首版；detail CAS 记录每轮 tool 名/参数/结果摘要供 `uwf thread step-details` 调试。
+
+---
+
+### 与现有架构的集成
+
+| 集成点 | 方式 |
+|--------|------|
+| CLI 协议 | 实现标准 agent CLI：`uwf-builtin <thread-id> <role>`，stdout 一行 step hash，exit 0/1 |
+| 工厂 | `export function createBuiltinAgent()` → `createAgent({ name: "builtin", run, continue })` |
+| Context / Prompt | 复用 `buildContextWithMeta`、`buildRolePrompt`、`buildOutputFormatInstruction`；prompt 布局对齐 `buildHermesPrompt` |
+| 结构化输出 | 优先 YAML frontmatter fast-path；可选后续在 `createAgent` 增加 `extract()` fallback 开关 |
+| 配置 | `config.yaml` 增加 `agents.builtin`；`uwf setup` 可选默认 agent |
+| 存储 | `resolveStorageRoot()` + `loadWorkflowConfig` + `getEnvPath`；与 Hermes 相同，**不**改 `threads.yaml` 写入方 |
+| 测试 | 单元测试：tool handlers、prompt 组装、mock LLM tool loop；集成测试：临时 storage root + fake provider |
+| 发布 | 新包 `@uncaged/workflow-agent-builtin`，bin `uwf-builtin`，加入 `scripts/publish-all.mjs` |
+
+**明确不做**：
+
+- 不替代 moderator / 不在 agent 内调用 `uwf thread step`
+- 不依赖 Hermes/OpenClaw/Claude Code 二进制
+- 首版不实现 streaming、不实现 MCP
+
+**建议实现顺序**：
+
+1. `llm.ts`：tool calling HTTP 客户端 + 单测
+2. P0 tools + `runBuiltinLoop`
+3. `createBuiltinAgent` + detail CAS
+4. `config` / docs / `examples` 可选 `agentOverrides` 演示
+5. （可选）`createAgent` 接入 `extract()` fallback

docs/wf-stateless-design.md

@@ -112,8 +112,8 @@ 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-kit 根据 thread + role 从 CAS 读 goal / capabilities / procedure / output / meta
+- agent-kit 组装完整 prompt（role goal/capabilities/procedure/output + thread context + user prompt from StartNode）
 - agent 执行实际逻辑，agent-kit 负责 extract
 - agent 将 StepNode 写入 CAS（含 output、detail、agent、prev），但**不挪链头指针**
 - stdout 输出新 StepNode 的 CAS hash（纯文本，一行）
@@ -143,7 +143,7 @@ uwf-hermes <thread-id> <role>
 
 #### `Workflow`
 
-Roles 和 moderator 内联在 Workflow 中，只有 outputSchema 独立为 CAS 节点（方便 json-cas 校验）。
+Roles 和 moderator 内联在 Workflow 中，只有 meta 独立为 CAS 节点（方便 json-cas 校验）。
 
 ```yaml
 type: <workflow-schema-hash>
@@ -153,16 +153,25 @@ payload:
   roles:
     planner:
       description: "Creates implementation plan"
-      systemPrompt: "You are a planning agent..."
-      outputSchema: "5GWKR8TN1V3JA"    # cas_ref → JSON Schema 节点（json-cas 内置）
+      goal: "You are a planning agent..."
+      capabilities: [planning, issue-analysis]
+      procedure: "Analyze the issue and create a plan."
+      output: "Output the plan summary."
+      meta: "5GWKR8TN1V3JA"    # cas_ref → JSON Schema 节点（json-cas 内置）
     developer:
       description: "Implements code changes"
-      systemPrompt: "You are a developer agent..."
-      outputSchema: "8CNWT4KR6D1HV"    # cas_ref → JSON Schema 节点
+      goal: "You are a developer agent..."
+      capabilities: [file-edit, shell]
+      procedure: "Implement the plan."
+      output: "List all files changed."
+      meta: "8CNWT4KR6D1HV"    # cas_ref → JSON Schema 节点
     reviewer:
       description: "Reviews code changes"
-      systemPrompt: "You are a code reviewer..."
-      outputSchema: "1VPBG9SM5E7WK"    # cas_ref → JSON Schema 节点
+      goal: "You are a code reviewer..."
+      capabilities: [code-review]
+      procedure: "Review the implementation."
+      output: "Approve or reject with comments."
+      meta: "1VPBG9SM5E7WK"    # cas_ref → JSON Schema 节点
   conditions:
     needsClarification:
       description: "Planner requests clarification from user"
@@ -189,7 +198,7 @@ payload:
         condition: null
 ```
 
-- `roles` — 内联定义，每个 role 的 `outputSchema` 是独立的 cas_ref（指向 json-cas 内置 JSON Schema 节点）
+- `roles` — 内联定义，每个 role 的 `meta` 是独立的 cas_ref（指向 json-cas 内置 JSON Schema 节点）
 - `conditions` — `Record<Name, JSONata>`，命名条件，方便画图描述
 - `graph` — `Record<Role | "$START", Transition[]>`，每个 Transition = `{ role, condition }`
 - `condition` 引用 conditions 中的 key，`null` = fallback
@@ -234,14 +243,14 @@ payload:
   start: "4TNVW8KR2B3MA"          # cas_ref → StartNode（每个 step 都引用）
   prev: "2MXBG6PN4A8JR"           # cas_ref → 前一个 StepNode，第一步为 null
   role: "developer"
-  output: "9KRVW3TN5F1QA"         # cas_ref → 结构化输出节点（符合 role 的 outputSchema）
+  output: "9KRVW3TN5F1QA"         # cas_ref → 结构化输出节点（符合 role 的 meta schema）
   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 校验
+- `output` — cas_ref，指向符合 role meta schema 的 CAS 节点，可用 json-cas 校验
 - `detail` — cas_ref，指向执行详情。可以是原始 agent 输出（content node），也可以是子 workflow thread 的 terminal StepNode（workflowAsAgent 场景）
 - `agent` — 纯字符串，不是 CAS 节点
 
@@ -372,7 +381,7 @@ type ThreadId = string;
 /** 一个 step 的核心数据，被 StepNode payload 和 JSONata 上下文共享 */
 type StepRecord = {
   role: string;
-  output: CasRef;                    // cas_ref → 结构化输出节点（符合 role outputSchema）
+  output: CasRef;                    // cas_ref → 结构化输出节点（符合 role meta schema）
   detail: CasRef;                    // cas_ref → 执行详情（content node / 子 workflow terminal StepNode）
   agent: string;                     // 实际使用的 agent 命令（纯字符串）
 };
@@ -383,8 +392,11 @@ type StepRecord = {
 ```typescript
 type RoleDefinition = {
   description: string;
-  systemPrompt: string;
-  outputSchema: CasRef;              // cas_ref → json-cas 内置 JSON Schema 节点
+  goal: string;
+  capabilities: string[];
+  procedure: string;
+  output: string;
+  meta: CasRef;                      // cas_ref → json-cas 内置 JSON Schema 节点
 };
 
 type Transition = {

examples/analyze-topic.yaml

@@ -3,22 +3,23 @@ description: "Single-role topic analysis using four-phase role description"
 roles:
   analyst:
     description: "Analyzes a given topic and produces a structured summary"
-    identity: |
+    goal: |
       You are a research analyst with expertise in breaking down complex topics
       into clear, structured summaries. You think critically and cite key points.
-    prepare: |
-      Review the topic carefully. Consider multiple perspectives and identify
-      the core question being asked.
-    execute: |
+    capabilities:
+      - research
+      - critical-thinking
+      - structured-writing
+    procedure: |
       Analyze the topic by:
       1. Identifying the main thesis or question
       2. Listing 3-5 key points with brief explanations
       3. Noting any counterarguments or caveats
       Keep your analysis concise (under 500 words).
-    report: |
+    output: |
       Provide your analysis as markdown under the frontmatter.
       The frontmatter must include your structured findings.
-    outputSchema:
+    frontmatter:
       type: object
       properties:
         thesis:
@@ -35,6 +36,8 @@ graph:
   $START:
     - role: "analyst"
       condition: null
+      prompt: "Analyze the topic in the task and produce a structured summary with key points."
   analyst:
     - role: "$END"
       condition: null
+      prompt: "Analysis complete. Finish the workflow."

examples/solve-issue.yaml

@@ -3,11 +3,13 @@ description: "End-to-end issue resolution"
 roles:
   planner:
     description: "Creates implementation plan"
-    identity: "You are a planning agent. You analyze issues and create step-by-step plans."
-    prepare: "Read the issue description and any linked context carefully."
-    execute: "Analyze the issue and create a detailed, actionable implementation plan."
-    report: "Output the plan summary and list of concrete steps."
-    outputSchema:
+    goal: "You are a planning agent. You analyze issues and create step-by-step plans."
+    capabilities:
+      - issue-analysis
+      - planning
+    procedure: "Analyze the issue and create a detailed, actionable implementation plan."
+    output: "Output the plan summary and list of concrete steps."
+    frontmatter:
       type: object
       properties:
         plan:
@@ -19,11 +21,14 @@ roles:
       required: [plan, steps]
   developer:
     description: "Implements code changes"
-    identity: "You are a developer agent. You implement code changes according to plans."
-    prepare: "Load coding tools and review the project structure and conventions."
-    execute: "Implement the plan. Write code, tests, and ensure existing tests pass."
-    report: "List all files changed and provide a summary of the implementation."
-    outputSchema:
+    goal: "You are a developer agent. You implement code changes according to plans."
+    capabilities:
+      - file-edit
+      - shell
+      - testing
+    procedure: "Implement the plan. Write code, tests, and ensure existing tests pass."
+    output: "List all files changed and provide a summary of the implementation."
+    frontmatter:
       type: object
       properties:
         filesChanged:
@@ -35,11 +40,13 @@ roles:
       required: [filesChanged, summary]
   reviewer:
     description: "Reviews code changes"
-    identity: "You are a code reviewer. You review implementations for correctness and quality."
-    prepare: "Review the project's coding standards and conventions."
-    execute: "Review the implementation against the plan. Check for bugs, edge cases, and style."
-    report: "Approve or reject with detailed comments explaining your decision."
-    outputSchema:
+    goal: "You are a code reviewer. You review implementations for correctness and quality."
+    capabilities:
+      - code-review
+      - static-analysis
+    procedure: "Review the implementation against the plan. Check for bugs, edge cases, and style."
+    output: "Approve or reject with detailed comments explaining your decision."
+    frontmatter:
       type: object
       properties:
         approved:
@@ -50,19 +57,24 @@ roles:
 conditions:
   notApproved:
     description: "Reviewer rejected the implementation"
-    expression: "steps[-1].output.approved = false"
+    expression: "$last('reviewer').approved = false"
 graph:
   $START:
     - role: "planner"
       condition: null
+      prompt: "Analyze the issue described in the task and produce a detailed implementation plan."
   planner:
     - role: "developer"
       condition: null
+      prompt: "Implement the plan from the planner. Write code, tests, and ensure existing tests pass."
   developer:
     - role: "reviewer"
       condition: null
+      prompt: "Review the developer's implementation against the plan for correctness and quality."
   reviewer:
     - role: "developer"
       condition: "notApproved"
+      prompt: "The reviewer rejected your implementation. Read their feedback and fix the issues."
     - role: "$END"
       condition: null
+      prompt: "The review passed. Complete the workflow."

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

@@ -1,6 +1,6 @@
 import { describe, expect, test } from "bun:test";
-import { packageDescriptor } from "../src/package-descriptor.js";
 import { createDocxDiffAgent } from "../src/agent.js";
+import { packageDescriptor } from "../src/package-descriptor.js";
 
 describe("createDocxDiffAgent", () => {
   test("returns an AdapterFn (function)", () => {

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

@@ -1,8 +1,8 @@
-import { mkdirSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-import { tmpdir } from "node:os";
 import { describe, expect, mock, test } from "bun:test";
-import { ok, err } from "@uncaged/workflow-util";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { err, ok } from "@uncaged/workflow-util";
 import type { SpawnCliConfig } from "@uncaged/workflow-util-agent";
 import { runDocxDiff } from "../src/runner.js";
 
@@ -74,7 +74,12 @@ describe("runDocxDiff", () => {
   test("exit 2: throws error", async () => {
     const dir = tempDir();
     const spawnFn = makeSpawn(
-      err({ kind: "non_zero_exit", exitCode: 2, stdout: "", stderr: "fatal error" }) as MockSpawnResult,
+      err({
+        kind: "non_zero_exit",
+        exitCode: 2,
+        stdout: "",
+        stderr: "fatal error",
+      }) as MockSpawnResult,
     );
 
     await expect(

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

@@ -1,7 +1,11 @@
 {
   "name": "@uncaged/workflow-agent-docx-diff",
   "version": "0.1.0",
-  "files": ["src", "dist", "package.json"],
+  "files": [
+    "src",
+    "dist",
+    "package.json"
+  ],
   "type": "module",
   "types": "src/index.ts",
   "exports": {

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

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

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

@@ -1,6 +1,6 @@
 import { stat } from "node:fs/promises";
-import { spawnCli } from "@uncaged/workflow-util-agent";
 import type { SpawnCliError } from "@uncaged/workflow-util-agent";
+import { spawnCli } from "@uncaged/workflow-util-agent";
 import type { DocxDiffAgentConfig } from "./types.js";
 
 type SpawnCliFn = typeof spawnCli;
@@ -8,8 +8,7 @@ type SpawnCliFn = typeof spawnCli;
 function throwSpawnError(e: SpawnCliError): never {
   if (e.kind === "non_zero_exit")
     throw new Error(`docx-diff failed (exit ${e.exitCode}): ${e.stderr}`);
-  if (e.kind === "timeout")
-    throw new Error("docx-diff: timed out");
+  if (e.kind === "timeout") throw new Error("docx-diff: timed out");
   throw new Error(`docx-diff: spawn failed: ${e.message}`);
 }
 

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

@@ -1,6 +1,6 @@
 import { describe, expect, test } from "bun:test";
-import { packageDescriptor } from "../src/package-descriptor.js";
 import { createOfficeAgent } from "../src/agent.js";
+import { packageDescriptor } from "../src/package-descriptor.js";
 
 describe("createOfficeAgent", () => {
   test("returns an AdapterFn (function)", () => {

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

@@ -1,8 +1,8 @@
-import { mkdirSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-import { tmpdir } from "node:os";
 import { describe, expect, mock, test } from "bun:test";
-import { ok, err } from "@uncaged/workflow-util";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { err, ok } from "@uncaged/workflow-util";
 import type { SpawnCliConfig } from "@uncaged/workflow-util-agent";
 import { editDocument, generateDocument } from "../src/runner.js";
 
@@ -123,7 +123,13 @@ describe("editDocument", () => {
     );
 
     await expect(
-      editDocument({ outputDir: base, command: null, timeout: null }, "te2", "edit", inputFile, spawnFn),
+      editDocument(
+        { outputDir: base, command: null, timeout: null },
+        "te2",
+        "edit",
+        inputFile,
+        spawnFn,
+      ),
     ).rejects.toThrow("spawn failed");
   });
 });

legacy-packages/workflow-agent-office/package.json

@@ -1,7 +1,11 @@
 {
   "name": "@uncaged/workflow-agent-office",
   "version": "0.1.0",
-  "files": ["src", "dist", "package.json"],
+  "files": [
+    "src",
+    "dist",
+    "package.json"
+  ],
   "type": "module",
   "types": "src/index.ts",
   "exports": {

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

@@ -1,6 +1,11 @@
-import * as z from "zod/v4";
-import type { AdapterFn, RoleResult, ThreadContext, WorkflowRuntime } from "@uncaged/workflow-runtime";
+import type {
+  AdapterFn,
+  RoleResult,
+  ThreadContext,
+  WorkflowRuntime,
+} from "@uncaged/workflow-runtime";
 import { createLogger } from "@uncaged/workflow-util";
+import type * as z from "zod/v4";
 import { editDocument, generateDocument } from "./runner.js";
 import type { OfficeAgentConfig } from "./types.js";
 
@@ -27,7 +32,10 @@ export function createOfficeAgent(config: OfficeAgentConfig): AdapterFn {
   return <T>(_systemPrompt: string, schema: z.ZodType<T>) =>
     async (ctx: ThreadContext, _runtime: WorkflowRuntime): Promise<RoleResult<T>> => {
       const { prompt, inputDocx } = parseStartInput(ctx.start.content);
-      log("8FQKP3NV", `office-agent: mode=${inputDocx === null ? "generate" : "edit"} thread=${ctx.threadId}`);
+      log(
+        "8FQKP3NV",
+        `office-agent: mode=${inputDocx === null ? "generate" : "edit"} thread=${ctx.threadId}`,
+      );
 
       let raw: string;
       if (inputDocx === null) {
@@ -35,7 +43,11 @@ export function createOfficeAgent(config: OfficeAgentConfig): AdapterFn {
         raw = JSON.stringify({ mode: "generate", outputDocx: result.outputDocx, sourceDocx: null });
       } else {
         const result = await editDocument(config, ctx.threadId, prompt, inputDocx);
-        raw = JSON.stringify({ mode: "edit", outputDocx: result.outputDocx, sourceDocx: result.sourceDocx });
+        raw = JSON.stringify({
+          mode: "edit",
+          outputDocx: result.outputDocx,
+          sourceDocx: result.sourceDocx,
+        });
       }
 
       const meta = schema.parse(JSON.parse(raw)) as T;

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

@@ -1,7 +1,7 @@
 import { copyFile, mkdir, stat } from "node:fs/promises";
 import { join } from "node:path";
-import { spawnCli } from "@uncaged/workflow-util-agent";
 import type { SpawnCliError } from "@uncaged/workflow-util-agent";
+import { spawnCli } from "@uncaged/workflow-util-agent";
 import type { OfficeAgentConfig } from "./types.js";
 
 type SpawnCliFn = typeof spawnCli;
@@ -9,8 +9,7 @@ type SpawnCliFn = typeof spawnCli;
 function throwSpawnError(e: SpawnCliError): never {
   if (e.kind === "non_zero_exit")
     throw new Error(`office-agent failed (exit ${e.exitCode}): ${e.stderr}`);
-  if (e.kind === "timeout")
-    throw new Error("office-agent: timed out");
+  if (e.kind === "timeout") throw new Error("office-agent: timed out");
   throw new Error(`office-agent: spawn failed: ${e.message}`);
 }
 

legacy-packages/workflow-dashboard/index.html

@@ -5,7 +5,7 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>Workflow Dashboard</title>
     <script>
-      (function () {
+      (() => {
         var t = localStorage.getItem("theme");
         if (t === "dark" || (!t && matchMedia("(prefers-color-scheme: dark)").matches)) {
           document.documentElement.classList.add("dark");

legacy-packages/workflow-dashboard/plugins/vite-limit-line-plugin.ts

@@ -54,10 +54,14 @@ type CallExpression = {
   arguments: Array<AstExpression>;
 };
 
-type AstExpression = Identifier | MemberExpression | CallExpression | {
-  type: string;
-  [key: string]: unknown;
-};
+type AstExpression =
+  | Identifier
+  | MemberExpression
+  | CallExpression
+  | {
+      type: string;
+      [key: string]: unknown;
+    };
 
 type VariableDeclarator = {
   id: Identifier | null;
@@ -258,15 +262,21 @@ function createLimitResolver(options: LimitLineOptions): (id: string) => Resolve
 }
 
 function shouldProcess(id: string, options: LimitLineOptions): boolean {
-  return options.include.test(id) && !id.includes("node_modules") && (options.exclude === null || !options.exclude.test(id));
+  return (
+    options.include.test(id) &&
+    !id.includes("node_modules") &&
+    (options.exclude === null || !options.exclude.test(id))
+  );
 }
 
 // --- Plugin ---
 
-function viteLimitLinePlugin(
-  userOptions: Partial<LimitLineOptions> = {},
-): Array<Plugin> {
-  const options: LimitLineOptions = { ...DEFAULT_OPTIONS, ...userOptions, overrides: userOptions.overrides ?? [] };
+function viteLimitLinePlugin(userOptions: Partial<LimitLineOptions> = {}): Array<Plugin> {
+  const options: LimitLineOptions = {
+    ...DEFAULT_OPTIONS,
+    ...userOptions,
+    overrides: userOptions.overrides ?? [],
+  };
   const resolve = createLimitResolver(options);
 
   const rawCodeCache = new Map<string, string>();
@@ -358,5 +368,5 @@ function viteLimitLinePlugin(
   ];
 }
 
-export { viteLimitLinePlugin };
 export type { LimitLineOptions, LimitLineOverride };
+export { viteLimitLinePlugin };

legacy-packages/workflow-dashboard/src/components/ui/resizable-panel.tsx

@@ -55,10 +55,7 @@ export function ResizablePanel({
   }, []);
 
   return (
-    <div
-      className={cn("relative shrink-0", className)}
-      style={{ ...style, width }}
-    >
+    <div className={cn("relative shrink-0", className)} style={{ ...style, width }}>
       {children}
       <div
         className="absolute top-0 -right-1 w-2 h-full cursor-col-resize z-10 group"

legacy-packages/workflow-template-document/__tests__/document-template.test.ts

@@ -9,9 +9,7 @@ import type { DocumentMeta } from "../src/roles.js";
 
 const documentModerator = tableToModerator(documentTable);
 
-function makeCtx(
-  steps: ModeratorContext<DocumentMeta>["steps"],
-): ModeratorContext<DocumentMeta> {
+function makeCtx(steps: ModeratorContext<DocumentMeta>["steps"]): ModeratorContext<DocumentMeta> {
   return {
     threadId: "01TEST000000000000000000TR",
     depth: 0,
@@ -25,7 +23,11 @@ function writerGenerateStep(): RoleStep<DocumentMeta> {
   return {
     role: "writer",
     contentHash: "STUBHASHWRITER001",
-    meta: { mode: "generate", outputDocx: "/out/output.docx", sourceDocx: null } satisfies WriterMeta,
+    meta: {
+      mode: "generate",
+      outputDocx: "/out/output.docx",
+      sourceDocx: null,
+    } satisfies WriterMeta,
     refs: [],
     timestamp: 1,
   };
@@ -35,7 +37,11 @@ function writerEditStep(): RoleStep<DocumentMeta> {
   return {
     role: "writer",
     contentHash: "STUBHASHWRITER002",
-    meta: { mode: "edit", outputDocx: "/out/modified.docx", sourceDocx: "/out/original.docx" } satisfies WriterMeta,
+    meta: {
+      mode: "edit",
+      outputDocx: "/out/modified.docx",
+      sourceDocx: "/out/original.docx",
+    } satisfies WriterMeta,
     refs: [],
     timestamp: 1,
   };

legacy-packages/workflow-template-document/package.json

@@ -1,7 +1,11 @@
 {
   "name": "@uncaged/workflow-template-document",
   "version": "0.1.0",
-  "files": ["src", "dist", "package.json"],
+  "files": [
+    "src",
+    "dist",
+    "package.json"
+  ],
   "type": "module",
   "types": "src/index.ts",
   "exports": {

package.json

@@ -15,10 +15,12 @@
     "release": "bun run build && bun test && node scripts/publish-all.mjs"
   },
   "devDependencies": {
+    "@agentclientprotocol/sdk": "^0.22.1",
     "@biomejs/biome": "^2.4.14",
     "@changesets/cli": "^2.31.0",
     "@types/node": "^25.7.0",
     "@types/xxhashjs": "^0.2.4",
+    "@uncaged/workflow-agent-hermes": "workspace:*",
     "bun-types": "^1.3.13"
   }
 }

packages/cli-workflow/src/__tests__/log.test.ts

@@ -0,0 +1,181 @@
+import { mkdir, readdir, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import { cmdLogClean, cmdLogList, cmdLogShow } from "../commands/log.js";
+
+let storageRoot: string;
+
+beforeEach(async () => {
+  storageRoot = join(tmpdir(), `uwf-log-test-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+  await mkdir(join(storageRoot, "logs"), { recursive: true });
+});
+
+afterEach(async () => {
+  await rm(storageRoot, { recursive: true, force: true });
+});
+
+const entry1 = JSON.stringify({
+  ts: "2026-05-20T10:00:00.000Z",
+  pid: "1716200000000-1234",
+  tag: "W9F3RK2M",
+  msg: "process start",
+  thread: "01J1234ABCDEF",
+  workflow: "solve-issue",
+});
+
+const entry2 = JSON.stringify({
+  ts: "2026-05-20T10:00:01.000Z",
+  pid: "1716200000000-1234",
+  tag: "ABC12345",
+  msg: "step executed",
+  thread: "01J1234ABCDEF",
+  workflow: "solve-issue",
+});
+
+const entry3 = JSON.stringify({
+  ts: "2026-05-20T10:00:02.000Z",
+  pid: "1716200000000-5678",
+  tag: "XYZ98765",
+  msg: "different process",
+  thread: "01JOTHER000000",
+  workflow: "review-code",
+});
+
+const oldEntry = JSON.stringify({
+  ts: "2026-05-19T08:00:00.000Z",
+  pid: "1716200000000-9999",
+  tag: "OLD1TAG1",
+  msg: "old entry",
+  thread: "01JOLD0000000",
+  workflow: "solve-issue",
+});
+
+const olderEntry = JSON.stringify({
+  ts: "2026-05-18T08:00:00.000Z",
+  pid: "1716200000000-0001",
+  tag: "OLD2TAG2",
+  msg: "older entry",
+  thread: "01JOLDER00000",
+  workflow: "review-code",
+});
+
+async function writeLogFiles(): Promise<void> {
+  const logsDir = join(storageRoot, "logs");
+  await writeFile(join(logsDir, "2026-05-20.jsonl"), [entry1, entry2, entry3].join("\n") + "\n");
+  await writeFile(join(logsDir, "2026-05-19.jsonl"), oldEntry + "\n");
+  await writeFile(join(logsDir, "2026-05-18.jsonl"), olderEntry + "\n");
+}
+
+describe("cmdLogList", () => {
+  test("lists log files with sizes sorted by date descending", async () => {
+    await writeLogFiles();
+    const result = await cmdLogList(storageRoot);
+    expect(result).toHaveLength(3);
+    expect(result[0].name).toBe("2026-05-20.jsonl");
+    expect(result[0].date).toBe("2026-05-20");
+    expect(result[0].size).toBeGreaterThan(0);
+    expect(result[1].name).toBe("2026-05-19.jsonl");
+    expect(result[2].name).toBe("2026-05-18.jsonl");
+  });
+
+  test("returns empty array when no log files exist", async () => {
+    const result = await cmdLogList(storageRoot);
+    expect(result).toEqual([]);
+  });
+
+  test("returns empty array when logs directory does not exist", async () => {
+    const noLogsRoot = join(storageRoot, "nonexistent");
+    await mkdir(noLogsRoot, { recursive: true });
+    const result = await cmdLogList(noLogsRoot);
+    expect(result).toEqual([]);
+  });
+});
+
+describe("cmdLogShow", () => {
+  test("filters by thread ID", async () => {
+    await writeLogFiles();
+    const result = await cmdLogShow(storageRoot, {
+      thread: "01J1234ABCDEF",
+      process: null,
+      date: null,
+    });
+    expect(result).toHaveLength(2);
+    expect(result.every((e) => e.thread === "01J1234ABCDEF")).toBe(true);
+  });
+
+  test("filters by process ID", async () => {
+    await writeLogFiles();
+    const result = await cmdLogShow(storageRoot, {
+      thread: null,
+      process: "1716200000000-1234",
+      date: null,
+    });
+    expect(result).toHaveLength(2);
+    expect(result.every((e) => e.pid === "1716200000000-1234")).toBe(true);
+  });
+
+  test("filters by date", async () => {
+    await writeLogFiles();
+    const result = await cmdLogShow(storageRoot, {
+      thread: null,
+      process: null,
+      date: "2026-05-19",
+    });
+    expect(result).toHaveLength(1);
+    expect(result[0].msg).toBe("old entry");
+  });
+
+  test("reads all files when no date filter", async () => {
+    await writeLogFiles();
+    const result = await cmdLogShow(storageRoot, { thread: null, process: null, date: null });
+    expect(result).toHaveLength(5);
+    // sorted by ts ascending
+    expect(result[0].ts).toBe("2026-05-18T08:00:00.000Z");
+    expect(result[4].ts).toBe("2026-05-20T10:00:02.000Z");
+  });
+
+  test("returns empty when no matches", async () => {
+    await writeLogFiles();
+    const result = await cmdLogShow(storageRoot, {
+      thread: "NONEXISTENT",
+      process: null,
+      date: null,
+    });
+    expect(result).toEqual([]);
+  });
+
+  test("combined thread + date filter", async () => {
+    await writeLogFiles();
+    const result = await cmdLogShow(storageRoot, {
+      thread: "01J1234ABCDEF",
+      process: null,
+      date: "2026-05-20",
+    });
+    expect(result).toHaveLength(2);
+    expect(result.every((e) => e.thread === "01J1234ABCDEF")).toBe(true);
+  });
+});
+
+describe("cmdLogClean", () => {
+  test("deletes files before given date", async () => {
+    await writeLogFiles();
+    const result = await cmdLogClean(storageRoot, "2026-05-20");
+    expect(result.deleted).toBe(2);
+    const remaining = await readdir(join(storageRoot, "logs"));
+    expect(remaining).toEqual(["2026-05-20.jsonl"]);
+  });
+
+  test("deletes nothing when all files are newer", async () => {
+    await writeLogFiles();
+    const result = await cmdLogClean(storageRoot, "2026-05-18");
+    expect(result.deleted).toBe(0);
+  });
+
+  test("handles missing logs directory gracefully", async () => {
+    const noLogsRoot = join(storageRoot, "nonexistent");
+    await mkdir(noLogsRoot, { recursive: true });
+    const result = await cmdLogClean(noLogsRoot, "2026-05-20");
+    expect(result).toEqual({ deleted: 0 });
+  });
+});

packages/cli-workflow/src/__tests__/setup-validate.test.ts

@@ -0,0 +1,150 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import { cmdSetup, validateModel } from "../commands/setup.js";
+
+describe("validateModel", () => {
+  const BASE_URL = "https://api.example.com/v1";
+  const API_KEY = "sk-test-key";
+  const MODEL = "test-model";
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  test("success path — returns ok on 200", async () => {
+    const mockFetch = vi
+      .spyOn(globalThis, "fetch")
+      .mockResolvedValue(new Response(JSON.stringify({}), { status: 200 }));
+
+    const result = await validateModel(BASE_URL, API_KEY, MODEL);
+
+    expect(result).toEqual({ ok: true, value: undefined });
+    expect(mockFetch).toHaveBeenCalledOnce();
+
+    const [url, opts] = mockFetch.mock.calls[0]!;
+    expect(url).toBe(`${BASE_URL}/chat/completions`);
+    expect((opts as RequestInit).headers).toEqual(
+      expect.objectContaining({ Authorization: `Bearer ${API_KEY}` }),
+    );
+    const body = JSON.parse((opts as RequestInit).body as string);
+    expect(body).toEqual({
+      model: MODEL,
+      messages: [{ role: "user", content: "hi" }],
+      max_tokens: 1,
+    });
+  });
+
+  test("HTTP 401 — returns error containing 401", async () => {
+    vi.spyOn(globalThis, "fetch").mockResolvedValue(
+      new Response("Unauthorized", { status: 401, statusText: "Unauthorized" }),
+    );
+
+    const result = await validateModel(BASE_URL, API_KEY, MODEL);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toContain("401");
+    }
+  });
+
+  test("HTTP 404 — returns error containing 404", async () => {
+    vi.spyOn(globalThis, "fetch").mockResolvedValue(
+      new Response("Not Found", { status: 404, statusText: "Not Found" }),
+    );
+
+    const result = await validateModel(BASE_URL, API_KEY, MODEL);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toContain("404");
+    }
+  });
+
+  test("network timeout — returns error mentioning timeout", async () => {
+    const err = new DOMException("signal timed out", "AbortError");
+    vi.spyOn(globalThis, "fetch").mockRejectedValue(err);
+
+    const result = await validateModel(BASE_URL, API_KEY, MODEL);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.toLowerCase()).toMatch(/timeout|timed out/);
+    }
+  });
+
+  test("network error (DNS/connection) — returns error mentioning connectivity", async () => {
+    vi.spyOn(globalThis, "fetch").mockRejectedValue(new TypeError("fetch failed"));
+
+    const result = await validateModel(BASE_URL, API_KEY, MODEL);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.toLowerCase()).toMatch(/connect|reach|network/);
+    }
+  });
+
+  test("request body correctness", async () => {
+    const mockFetch = vi
+      .spyOn(globalThis, "fetch")
+      .mockResolvedValue(new Response(JSON.stringify({}), { status: 200 }));
+
+    await validateModel(BASE_URL, API_KEY, "my-special-model");
+
+    const body = JSON.parse((mockFetch.mock.calls[0]![1] as RequestInit).body as string);
+    expect(body).toEqual({
+      model: "my-special-model",
+      messages: [{ role: "user", content: "hi" }],
+      max_tokens: 1,
+    });
+  });
+});
+
+describe("cmdSetup with validation", () => {
+  let storageRoot: string;
+
+  beforeEach(async () => {
+    storageRoot = await mkdtemp(join(tmpdir(), "uwf-setup-validate-"));
+  });
+
+  afterEach(async () => {
+    vi.restoreAllMocks();
+    await rm(storageRoot, { recursive: true, force: true });
+  });
+
+  const setupArgs = () => ({
+    provider: "testprovider",
+    baseUrl: "https://api.test.com/v1",
+    apiKey: "sk-test",
+    model: "test-model",
+    storageRoot,
+  });
+
+  test("includes validation result on success", async () => {
+    vi.spyOn(globalThis, "fetch").mockResolvedValue(
+      new Response(JSON.stringify({}), { status: 200 }),
+    );
+
+    const result = await cmdSetup(setupArgs());
+
+    expect(result.validation).toEqual({ ok: true, value: undefined });
+    // Config files should still be written
+    expect(result.configPath).toBeTruthy();
+    expect(result.envPath).toBeTruthy();
+  });
+
+  test("includes validation failure — config still saved", async () => {
+    vi.spyOn(globalThis, "fetch").mockResolvedValue(
+      new Response("Unauthorized", { status: 401, statusText: "Unauthorized" }),
+    );
+
+    const result = await cmdSetup(setupArgs());
+
+    expect(result.validation).toBeDefined();
+    expect((result.validation as { ok: boolean }).ok).toBe(false);
+    // Config files should still be written despite validation failure
+    expect(result.configPath).toBeTruthy();
+    expect(result.envPath).toBeTruthy();
+  });
+});

packages/cli-workflow/src/__tests__/thread-step-count.test.ts

@@ -0,0 +1,71 @@
+import { execFileSync } from "node:child_process";
+import { join } from "node:path";
+import { describe, expect, test } from "vitest";
+
+const CLI_PATH = join(import.meta.dirname, "..", "cli.js");
+
+function runCli(args: string[]): { stdout: string; stderr: string; exitCode: number } {
+  try {
+    const stdout = execFileSync("bun", ["run", CLI_PATH, ...args], {
+      encoding: "utf8",
+      env: { ...process.env, WORKFLOW_STORAGE_ROOT: "/tmp/uwf-test-nonexistent" },
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    return { stdout, stderr: "", exitCode: 0 };
+  } catch (e: unknown) {
+    const err = e as NodeJS.ErrnoException & { stdout?: string; stderr?: string; status?: number };
+    return {
+      stdout: err.stdout ?? "",
+      stderr: err.stderr ?? "",
+      exitCode: err.status ?? 1,
+    };
+  }
+}
+
+describe("thread step --count CLI parsing", () => {
+  test("--help shows -c/--count option", () => {
+    const result = runCli(["thread", "step", "--help"]);
+    expect(result.stdout).toContain("--count");
+    expect(result.stdout).toContain("-c");
+  });
+
+  test("description says 'one or more steps'", () => {
+    const result = runCli(["thread", "step", "--help"]);
+    expect(result.stdout).toContain("one or more steps");
+  });
+});
+
+describe("cmdThreadStep count logic", () => {
+  test("count=0 fails with validation error", () => {
+    const result = runCli(["thread", "step", "FAKE_THREAD_ID", "-c", "0"]);
+    expect(result.exitCode).not.toBe(0);
+    expect(result.stderr).toContain("positive integer");
+  });
+
+  test("negative count fails with validation error", () => {
+    const result = runCli(["thread", "step", "FAKE_THREAD_ID", "-c", "-1"]);
+    expect(result.exitCode).not.toBe(0);
+    expect(result.stderr).toContain("positive integer");
+  });
+
+  test("non-integer count fails with validation error", () => {
+    const result = runCli(["thread", "step", "FAKE_THREAD_ID", "-c", "1.5"]);
+    expect(result.exitCode).not.toBe(0);
+    expect(result.stderr).toContain("positive integer");
+  });
+
+  test("count=1 is the default (no -c flag)", () => {
+    // Without -c, it should attempt to run 1 step (failing on missing thread, not on count validation)
+    const result = runCli(["thread", "step", "FAKE_THREAD_ID"]);
+    expect(result.exitCode).not.toBe(0);
+    // Should NOT contain "positive integer" error — should fail on thread lookup instead
+    expect(result.stderr).not.toContain("positive integer");
+  });
+
+  test("count=3 passes validation (fails on thread lookup)", () => {
+    const result = runCli(["thread", "step", "FAKE_THREAD_ID", "-c", "3"]);
+    expect(result.exitCode).not.toBe(0);
+    // Should NOT contain "positive integer" error — should fail on thread/storage lookup
+    expect(result.stderr).not.toContain("positive integer");
+  });
+});

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

@@ -211,11 +211,11 @@ describe("cmdThreadRead ### Content section", () => {
       roles: {
         writer: {
           description: "Write",
-          identity: "You are a writer.",
-          prepare: "",
-          execute: "Write content as requested.",
-          report: "Summarize what was written.",
-          outputSchema: "placeholder00" as CasRef,
+          goal: "You are a writer.",
+          capabilities: [],
+          procedure: "Write content as requested.",
+          output: "Summarize what was written.",
+          meta: "placeholder00" as CasRef,
         },
       },
       conditions: {},

packages/cli-workflow/src/cli.ts

@@ -7,13 +7,16 @@ import {
   cmdCasGet,
   cmdCasHas,
   cmdCasPut,
+  cmdCasPutText,
   cmdCasRefs,
   cmdCasReindex,
   cmdCasSchemaGet,
   cmdCasSchemaList,
   cmdCasWalk,
 } from "./commands/cas.js";
+import { cmdLogClean, cmdLogList, cmdLogShow } from "./commands/log.js";
 import { cmdSetup, cmdSetupInteractive } from "./commands/setup.js";
+import { cmdSkillCli } from "./commands/skill.js";
 import {
   cmdThreadFork,
   cmdThreadKill,
@@ -47,7 +50,10 @@ const program = new Command();
 
 // eslint-disable-next-line -- dynamic import for version
 const pkg = await import("../package.json", { with: { type: "json" } });
-program.name("uwf").description("Stateless workflow CLI").version(pkg.default.version, "-V, --version");
+program
+  .name("uwf")
+  .description("Stateless workflow CLI")
+  .version(pkg.default.version, "-V, --version");
 program.option("--format <fmt>", "Output format: json or yaml", "json");
 
 const workflow = program.command("workflow").description("Workflow registry and CAS");
@@ -82,7 +88,7 @@ workflow
   .action(() => {
     const storageRoot = resolveStorageRoot();
     runAction(async () => {
-      const result = await cmdWorkflowList(storageRoot);
+      const result = await cmdWorkflowList(storageRoot, process.cwd());
       writeOutput(result);
     });
   });
@@ -97,22 +103,28 @@ thread
   .action((workflow: string, opts: { prompt: string }) => {
     const storageRoot = resolveStorageRoot();
     runAction(async () => {
-      const result = await cmdThreadStart(storageRoot, workflow, opts.prompt);
+      const result = await cmdThreadStart(storageRoot, workflow, opts.prompt, process.cwd());
       writeOutput(result);
     });
   });
 
 thread
   .command("step")
-  .description("Execute one step")
+  .description("Execute one or more steps")
   .argument("<thread-id>", "Thread ULID")
   .option("--agent <cmd>", "Override agent command")
-  .action((threadId: string, opts: { agent: string | undefined }) => {
+  .option("-c, --count <number>", "Number of steps to run (default: 1)")
+  .action((threadId: string, opts: { agent: string | undefined; count: string | undefined }) => {
     const storageRoot = resolveStorageRoot();
     runAction(async () => {
       const agentOverride = opts.agent ?? null;
-      const result = await cmdThreadStep(storageRoot, threadId, agentOverride);
-      writeOutput(result);
+      const count = opts.count !== undefined ? Number(opts.count) : 1;
+      const results = await cmdThreadStep(storageRoot, threadId, agentOverride, count);
+      if (results.length === 1) {
+        writeOutput(results[0]);
+      } else {
+        writeOutput(results);
+      }
     });
   });
 
@@ -217,6 +229,15 @@ thread
     });
   });
 
+const skill = program.command("skill").description("Built-in skill references for agents");
+
+skill
+  .command("cli")
+  .description("Print a markdown reference of all uwf commands")
+  .action(() => {
+    console.log(cmdSkillCli());
+  });
+
 program
   .command("setup")
   .description("Configure provider, model, and agent")
@@ -282,6 +303,17 @@ cas
     });
   });
 
+cas
+  .command("put-text")
+  .description("Store a plain text string, print its hash")
+  .argument("<text>", "Text content to store")
+  .action((text: string) => {
+    const storageRoot = resolveStorageRoot();
+    runAction(async () => {
+      writeOutput(await cmdCasPutText(storageRoot, text));
+    });
+  });
+
 cas
   .command("has")
   .description("Check if a hash exists")
@@ -348,6 +380,55 @@ casSchema
     });
   });
 
+const log = program.command("log").description("Process-level debug logs");
+
+log
+  .command("list")
+  .description("List log files with sizes")
+  .action(() => {
+    const storageRoot = resolveStorageRoot();
+    runAction(async () => {
+      const result = await cmdLogList(storageRoot);
+      writeOutput(result);
+    });
+  });
+
+log
+  .command("show")
+  .description("Show and filter log entries")
+  .option("--thread <thread-id>", "Filter by thread ID")
+  .option("--process <pid>", "Filter by process ID")
+  .option("--date <date>", "Filter by date (YYYY-MM-DD)")
+  .action(
+    (opts: {
+      thread: string | undefined;
+      process: string | undefined;
+      date: string | undefined;
+    }) => {
+      const storageRoot = resolveStorageRoot();
+      runAction(async () => {
+        const result = await cmdLogShow(storageRoot, {
+          thread: opts.thread ?? null,
+          process: opts.process ?? null,
+          date: opts.date ?? null,
+        });
+        writeOutput(result);
+      });
+    },
+  );
+
+log
+  .command("clean")
+  .description("Delete log files older than given date")
+  .requiredOption("--before <date>", "Delete files before this date (YYYY-MM-DD)")
+  .action((opts: { before: string }) => {
+    const storageRoot = resolveStorageRoot();
+    runAction(async () => {
+      const result = await cmdLogClean(storageRoot, opts.before);
+      writeOutput(result);
+    });
+  });
+
 program.parseAsync(process.argv).catch((e: unknown) => {
   const message = e instanceof Error ? e.message : String(e);
   process.stderr.write(`${message}\n`);

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

@@ -1,10 +1,12 @@
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 
-import type { Hash, JSONSchema, Store } from "@uncaged/json-cas";
-import { bootstrap, getSchema, refs, walk } from "@uncaged/json-cas";
+import type { JSONSchema, Store } from "@uncaged/json-cas";
+import { bootstrap, getSchema, putSchema, refs, walk } from "@uncaged/json-cas";
 import { createFsStore } from "@uncaged/json-cas-fs";
 
+import { TEXT_SCHEMA } from "../schemas.js";
+
 // ---- Helpers ----
 
 function openStore(storageRoot: string): Store {
@@ -53,18 +55,12 @@ export async function cmdCasPut(
   return { hash };
 }
 
-export async function cmdCasHas(
-  storageRoot: string,
-  hash: string,
-): Promise<{ exists: boolean }> {
+export async function cmdCasHas(storageRoot: string, hash: string): Promise<{ exists: boolean }> {
   const store = openStore(storageRoot);
   return { exists: store.has(hash) };
 }
 
-export async function cmdCasRefs(
-  storageRoot: string,
-  hash: string,
-): Promise<{ refs: string[] }> {
+export async function cmdCasRefs(storageRoot: string, hash: string): Promise<{ refs: string[] }> {
   const store = openStore(storageRoot);
   const node = store.get(hash);
   if (node === null) {
@@ -73,10 +69,7 @@ export async function cmdCasRefs(
   return { refs: refs(store, node) };
 }
 
-export async function cmdCasWalk(
-  storageRoot: string,
-  hash: string,
-): Promise<{ hashes: string[] }> {
+export async function cmdCasWalk(storageRoot: string, hash: string): Promise<{ hashes: string[] }> {
   const store = openStore(storageRoot);
   const result: string[] = [];
   walk(store, hash, (h) => {
@@ -90,9 +83,7 @@ export type SchemaListEntry = {
   title: string;
 };
 
-export async function cmdCasSchemaList(
-  storageRoot: string,
-): Promise<SchemaListEntry[]> {
+export async function cmdCasSchemaList(storageRoot: string): Promise<SchemaListEntry[]> {
   const store = openStore(storageRoot);
   const metaHash = await bootstrap(store);
   const entries: SchemaListEntry[] = [];
@@ -115,9 +106,7 @@ export async function cmdCasSchemaList(
   return entries;
 }
 
-export async function cmdCasReindex(
-  storageRoot: string,
-): Promise<{ status: string }> {
+export async function cmdCasReindex(storageRoot: string): Promise<{ status: string }> {
   const indexDir = join(storageRoot, "cas", "_index");
   const { rmSync } = await import("node:fs");
   rmSync(indexDir, { recursive: true, force: true });
@@ -126,10 +115,7 @@ export async function cmdCasReindex(
   return { status: "reindexed" };
 }
 
-export async function cmdCasSchemaGet(
-  storageRoot: string,
-  hash: string,
-): Promise<unknown> {
+export async function cmdCasSchemaGet(storageRoot: string, hash: string): Promise<unknown> {
   const store = openStore(storageRoot);
   const schema = getSchema(store, hash);
   if (schema === null) {
@@ -137,3 +123,10 @@ export async function cmdCasSchemaGet(
   }
   return schema;
 }
+
+export async function cmdCasPutText(storageRoot: string, text: string): Promise<{ hash: string }> {
+  const store = openStore(storageRoot);
+  const typeHash = await putSchema(store, TEXT_SCHEMA);
+  const hash = await store.put(typeHash, text);
+  return { hash };
+}

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

@@ -0,0 +1,116 @@
+import { readdir, readFile, stat, unlink } from "node:fs/promises";
+import { join } from "node:path";
+
+type LogListItem = {
+  name: string;
+  size: number;
+  date: string;
+};
+
+type LogShowFilter = {
+  thread: string | null;
+  process: string | null;
+  date: string | null;
+};
+
+type LogEntry = {
+  ts: string;
+  pid: string;
+  tag: string;
+  msg: string;
+  thread: string | null;
+  workflow: string | null;
+};
+
+type LogCleanResult = {
+  deleted: number;
+};
+
+function logsDir(storageRoot: string): string {
+  return join(storageRoot, "logs");
+}
+
+async function listLogFiles(dir: string): Promise<Array<string>> {
+  try {
+    const files = await readdir(dir);
+    return files.filter((f) => f.endsWith(".jsonl")).sort();
+  } catch {
+    return [];
+  }
+}
+
+function dateFromFilename(name: string): string {
+  return name.replace(".jsonl", "");
+}
+
+async function parseJsonlFile(path: string): Promise<Array<LogEntry>> {
+  const content = await readFile(path, "utf-8");
+  const lines = content
+    .trim()
+    .split("\n")
+    .filter((l) => l.length > 0);
+  return lines.map((line) => JSON.parse(line) as LogEntry);
+}
+
+export async function cmdLogList(storageRoot: string): Promise<Array<LogListItem>> {
+  const dir = logsDir(storageRoot);
+  const files = await listLogFiles(dir);
+  const items: Array<LogListItem> = [];
+  for (const name of files) {
+    const s = await stat(join(dir, name));
+    items.push({ name, size: s.size, date: dateFromFilename(name) });
+  }
+  // sort by date descending
+  items.sort((a, b) => (a.date > b.date ? -1 : a.date < b.date ? 1 : 0));
+  return items;
+}
+
+export async function cmdLogShow(
+  storageRoot: string,
+  filter: LogShowFilter,
+): Promise<Array<LogEntry>> {
+  const dir = logsDir(storageRoot);
+  let files: Array<string>;
+
+  if (filter.date !== null) {
+    files = [`${filter.date}.jsonl`];
+  } else {
+    files = await listLogFiles(dir);
+  }
+
+  let entries: Array<LogEntry> = [];
+  for (const file of files) {
+    try {
+      const parsed = await parseJsonlFile(join(dir, file));
+      entries = entries.concat(parsed);
+    } catch {
+      // file doesn't exist or is unreadable, skip
+    }
+  }
+
+  if (filter.thread !== null) {
+    entries = entries.filter((e) => e.thread === filter.thread);
+  }
+  if (filter.process !== null) {
+    entries = entries.filter((e) => e.pid === filter.process);
+  }
+
+  entries.sort((a, b) => (a.ts < b.ts ? -1 : a.ts > b.ts ? 1 : 0));
+  return entries;
+}
+
+export async function cmdLogClean(storageRoot: string, before: string): Promise<LogCleanResult> {
+  const dir = logsDir(storageRoot);
+  const files = await listLogFiles(dir);
+  let deleted = 0;
+
+  for (const name of files) {
+    const date = dateFromFilename(name);
+    if (date < before) {
+      await unlink(join(dir, name));
+      deleted++;
+    }
+  }
+
+  return { deleted };
+}

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

@@ -1,10 +1,45 @@
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
-import { homedir } from "node:os";
-import { join, resolve } from "node:path";
-import { createInterface } from "node:readline/promises";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
 import { stdin as input, stdout as output } from "node:process";
+import { createInterface } from "node:readline/promises";
+import type { Result } from "@uncaged/workflow-util";
+import { parse, stringify } from "yaml";
 
-import { stringify, parse } from "yaml";
+/**
+ * Send a minimal chat completion request to verify the model is reachable.
+ * Returns ok on 2xx, error with reason string otherwise.
+ */
+export async function validateModel(
+  baseUrl: string,
+  apiKey: string,
+  model: string,
+): Promise<Result<void, string>> {
+  try {
+    const url = `${baseUrl.replace(/\/+$/, "")}/chat/completions`;
+    const res = await fetch(url, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        model,
+        messages: [{ role: "user", content: "hi" }],
+        max_tokens: 1,
+      }),
+      signal: AbortSignal.timeout(15_000),
+    });
+    if (!res.ok) {
+      return { ok: false, error: `HTTP ${res.status} ${res.statusText}` };
+    }
+    return { ok: true, value: undefined };
+  } catch (err: unknown) {
+    if (err instanceof DOMException && err.name === "AbortError") {
+      return { ok: false, error: "Request timed out — model endpoint unreachable" };
+    }
+    return { ok: false, error: `Network error — could not reach endpoint (${String(err)})` };
+  }
+}
 
 /**
  * Preset provider list — embedded to avoid runtime YAML loading dependency.
@@ -17,10 +52,18 @@ const PRESET_PROVIDERS = [
   { name: "openrouter", label: "OpenRouter", baseUrl: "https://openrouter.ai/api/v1" },
   { name: "venice", label: "Venice", baseUrl: "https://api.venice.ai/api/v1" },
   // China
-  { name: "dashscope", label: "DashScope (Alibaba)", baseUrl: "https://dashscope.aliyuncs.com/compatible-mode/v1" },
+  {
+    name: "dashscope",
+    label: "DashScope (Alibaba)",
+    baseUrl: "https://dashscope.aliyuncs.com/compatible-mode/v1",
+  },
   { name: "deepseek", label: "DeepSeek", baseUrl: "https://api.deepseek.com/v1" },
   { name: "siliconflow", label: "SiliconFlow", baseUrl: "https://api.siliconflow.cn/v1" },
-  { name: "volcengine", label: "Volcengine (ByteDance)", baseUrl: "https://ark.cn-beijing.volces.com/api/v3" },
+  {
+    name: "volcengine",
+    label: "Volcengine (ByteDance)",
+    baseUrl: "https://ark.cn-beijing.volces.com/api/v3",
+  },
   { name: "kimi", label: "Kimi (Moonshot)", baseUrl: "https://api.moonshot.cn/v1" },
   { name: "glm", label: "GLM (Zhipu AI)", baseUrl: "https://open.bigmodel.cn/api/paas/v4" },
   { name: "stepfun", label: "StepFun", baseUrl: "https://api.stepfun.com/v1" },
@@ -98,21 +141,27 @@ function apiKeyEnvName(providerName: string): string {
  * Merge setup args into config.yaml structure. Non-destructive — preserves existing entries.
  */
 function mergeConfig(existing: Record<string, unknown>, args: SetupArgs): Record<string, unknown> {
-  const providers = (typeof existing.providers === "object" && existing.providers !== null
-    ? { ...(existing.providers as Record<string, unknown>) }
-    : {}) as Record<string, unknown>;
+  const providers = (
+    typeof existing.providers === "object" && existing.providers !== null
+      ? { ...(existing.providers as Record<string, unknown>) }
+      : {}
+  ) as Record<string, unknown>;
 
   const envName = apiKeyEnvName(args.provider);
   providers[args.provider] = { baseUrl: args.baseUrl, apiKeyEnv: envName };
 
-  const models = (typeof existing.models === "object" && existing.models !== null
-    ? { ...(existing.models as Record<string, unknown>) }
-    : {}) as Record<string, unknown>;
+  const models = (
+    typeof existing.models === "object" && existing.models !== null
+      ? { ...(existing.models as Record<string, unknown>) }
+      : {}
+  ) as Record<string, unknown>;
   models.default = { provider: args.provider, name: args.model };
 
-  const agents = (typeof existing.agents === "object" && existing.agents !== null
-    ? { ...(existing.agents as Record<string, unknown>) }
-    : {}) as Record<string, unknown>;
+  const agents = (
+    typeof existing.agents === "object" && existing.agents !== null
+      ? { ...(existing.agents as Record<string, unknown>) }
+      : {}
+  ) as Record<string, unknown>;
 
   const agentName = args.agent ?? "hermes";
   if (Object.keys(agents).length === 0) {
@@ -150,12 +199,16 @@ export async function cmdSetup(args: SetupArgs): Promise<Record<string, unknown>
   envData[envName] = args.apiKey;
   saveEnvFile(envPath, envData);
 
+  // Validate model connectivity
+  const validation = await validateModel(args.baseUrl, args.apiKey, args.model);
+
   return {
     configPath,
     envPath,
     provider: args.provider,
     model: args.model,
     defaultAgent: merged.defaultAgent,
+    validation,
   };
 }
 
@@ -211,8 +264,12 @@ async function fetchModels(baseUrl: string, apiKey: string): Promise<string[]> {
     if (!res.ok) return [];
     const body = (await res.json()) as { data?: { id: string }[] };
     if (!Array.isArray(body.data)) return [];
-    const NON_CHAT = /speech|embed|image|video|audio|ocr|rerank|tts|asr|paraformer|sambert|cosyvoice|wordart|wanx|wan2|flux|stable-diffusion|gui-/i;
-    return body.data.map((m) => m.id).filter((id) => !NON_CHAT.test(id)).sort();
+    const NON_CHAT =
+      /speech|embed|image|video|audio|ocr|rerank|tts|asr|paraformer|sambert|cosyvoice|wordart|wanx|wan2|flux|stable-diffusion|gui-/i;
+    return body.data
+      .map((m) => m.id)
+      .filter((id) => !NON_CHAT.test(id))
+      .sort();
   } catch {
     return [];
   }
@@ -311,7 +368,7 @@ export async function cmdSetupInteractive(storageRoot: string): Promise<Record<s
 
     console.log(`  → ${providerName}/${model}\n`);
 
-    await cmdSetup({
+    const setupResult = await cmdSetup({
       provider: providerName,
       baseUrl,
       apiKey,
@@ -319,6 +376,19 @@ export async function cmdSetupInteractive(storageRoot: string): Promise<Record<s
       storageRoot,
     });
 
+    // Show validation result
+    if (setupResult.validation && typeof setupResult.validation === "object") {
+      const v = setupResult.validation as { ok: boolean; error?: string };
+      if (v.ok) {
+        console.log("✓ Model verified — connection successful.\n");
+      } else {
+        console.log(`\n⚠ Warning: Could not reach model — ${v.error}`);
+        console.log(
+          "  Config saved, but you may want to try a different model or check your API key.\n",
+        );
+      }
+    }
+
     console.log("Setup complete! Get started:\n");
     console.log("  uwf workflow put <workflow.yaml>   Register a workflow");
     console.log('  uwf thread start <name> -p "..."   Start a thread');

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

@@ -0,0 +1 @@
+export { generateCliReference as cmdSkillCli } from "@uncaged/workflow-util";

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

@@ -1,4 +1,5 @@
 import { execFileSync } from "node:child_process";
+import { readFile } from "node:fs/promises";
 import type { Store as CasStore, JSONSchema } from "@uncaged/json-cas";
 import { getSchema, validate } from "@uncaged/json-cas";
 import { getEnvPath, loadWorkflowConfig } from "@uncaged/workflow-agent-kit";
@@ -22,27 +23,42 @@ import type {
   WorkflowConfig,
   WorkflowPayload,
 } from "@uncaged/workflow-protocol";
-import { generateUlid } from "@uncaged/workflow-util";
+import { createProcessLogger, generateUlid, type ProcessLogger } from "@uncaged/workflow-util";
 import { config as loadDotenv } from "dotenv";
-import { stringify } from "yaml";
+import { parse, stringify } from "yaml";
 
 import {
   appendThreadHistory,
   createUwfStore,
+  discoverProjectWorkflows,
   findThreadInHistory,
   loadThreadHistory,
   loadThreadsIndex,
   loadWorkflowRegistry,
+  resolveProjectWorkflowFile,
   resolveWorkflowHash,
   saveThreadsIndex,
   type ThreadHistoryLine,
   type UwfStore,
 } from "../store.js";
-import { isCasRef } from "../validate.js";
+import { checkWorkflowFilenameConsistency, isCasRef, parseWorkflowPayload } from "../validate.js";
+import { materializeWorkflowPayload } from "./workflow.js";
 
 const END_ROLE = "$END";
 export const THREAD_READ_DEFAULT_QUOTA = 4000;
 
+const PL_THREAD_START = "7HNQ4B2X";
+const PL_MODERATOR = "M3K8V9T1";
+const PL_AGENT_SPAWN = "R5J2W8N4";
+const PL_AGENT_DONE = "C6P9E3H7";
+const PL_THREAD_ARCHIVED = "F4D8Q2K5";
+const PL_STEP_ERROR = "B8T5N1V6";
+
+function failStep(plog: ProcessLogger, message: string): never {
+  plog.log(PL_STEP_ERROR, message, null);
+  fail(message);
+}
+
 type ChainState = {
   startHash: CasRef;
   start: StartNodePayload;
@@ -66,11 +82,55 @@ function fail(message: string): never {
   process.exit(1);
 }
 
+async function materializeLocalWorkflow(uwf: UwfStore, filePath: string): Promise<CasRef> {
+  let text: string;
+  try {
+    text = await readFile(filePath, "utf8");
+  } catch {
+    fail(`project workflow file not found: ${filePath}`);
+  }
+
+  let raw: unknown;
+  try {
+    raw = parse(text) as unknown;
+  } catch (e) {
+    fail(`invalid YAML in ${filePath}: ${e instanceof Error ? e.message : String(e)}`);
+  }
+
+  const payload = parseWorkflowPayload(raw);
+  if (payload === null) {
+    fail(`invalid workflow YAML in ${filePath}: expected WorkflowPayload shape`);
+  }
+
+  const filenameError = checkWorkflowFilenameConsistency(filePath, payload);
+  if (filenameError !== null) {
+    fail(filenameError);
+  }
+
+  const materialized = await materializeWorkflowPayload(uwf, payload);
+  const hash = await uwf.store.put(uwf.schemas.workflow, materialized);
+  const stored = uwf.store.get(hash);
+  if (stored === null || !validate(uwf.store, stored)) {
+    fail("stored local workflow failed schema validation");
+  }
+
+  return hash;
+}
+
 async function resolveWorkflowCasRef(
   uwf: UwfStore,
   storageRoot: string,
   workflowId: string,
+  projectRoot: string,
 ): Promise<CasRef> {
+  // Project-local resolution: check .workflows/<workflowId>.yaml first
+  const localEntries = await discoverProjectWorkflows(projectRoot);
+  const localFile = resolveProjectWorkflowFile(localEntries, workflowId);
+  if (localFile !== null) {
+    return materializeLocalWorkflow(uwf, localFile);
+  }
+
+  // Global registry fallback
   const registry = await loadWorkflowRegistry(storageRoot);
   const hash = resolveWorkflowHash(registry, workflowId);
   if (!isCasRef(hash)) {
@@ -114,11 +174,16 @@ export async function cmdThreadStart(
   storageRoot: string,
   workflowId: string,
   prompt: string,
+  projectRoot: string,
 ): Promise<StartOutput> {
   const uwf = await createUwfStore(storageRoot);
-  const workflowHash = await resolveWorkflowCasRef(uwf, storageRoot, workflowId);
+  const workflowHash = await resolveWorkflowCasRef(uwf, storageRoot, workflowId, projectRoot);
 
   const threadId = generateUlid(Date.now()) as ThreadId;
+  const plog = createProcessLogger({
+    storageRoot,
+    context: { thread: threadId, workflow: workflowHash },
+  });
   const startPayload: StartNodePayload = {
     workflow: workflowHash,
     prompt,
@@ -134,6 +199,12 @@ export async function cmdThreadStart(
   index[threadId] = headHash;
   await saveThreadsIndex(storageRoot, index);
 
+  plog.log(
+    PL_THREAD_START,
+    `thread created workflow=${workflowHash} thread=${threadId} head=${headHash}`,
+    null,
+  );
+
   return { workflow: workflowHash, thread: threadId };
 }
 
@@ -500,7 +571,7 @@ function formatThreadReadMarkdown(options: {
     ];
     const roleDef = workflow.roles[item.payload.role];
     if (roleDef) {
-      const prompt = roleDef.identity;
+      const prompt = roleDef.goal;
       stepLines.push("", "### Prompt", "", prompt);
     }
     if (item.payload.detail) {
@@ -575,13 +646,20 @@ function resolveAgentConfig(
   return agentConfig;
 }
 
-function spawnAgent(agent: AgentConfig, threadId: ThreadId, role: string): CasRef {
+function spawnAgent(
+  plog: ProcessLogger,
+  agent: AgentConfig,
+  threadId: ThreadId,
+  role: string,
+  edgePrompt: string,
+): CasRef {
   const argv = [...agent.args, threadId, role];
+  const env = { ...process.env, UWF_EDGE_PROMPT: edgePrompt };
   let stdout: string;
   try {
     stdout = execFileSync(agent.command, argv, {
       encoding: "utf8",
-      env: process.env,
+      env,
       stdio: ["ignore", "pipe", "pipe"],
     });
   } catch (e) {
@@ -593,12 +671,12 @@ function spawnAgent(agent: AgentConfig, threadId: ThreadId, role: string): CasRe
           ? err.stderr
           : err.stderr.toString("utf8");
     const detail = stderr.trim() !== "" ? `: ${stderr.trim()}` : "";
-    fail(`agent command failed (${agent.command})${detail}`);
+    failStep(plog, `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)"}`);
+    failStep(plog, `agent stdout is not a valid CAS hash: ${line || "(empty)"}`);
   }
   return line;
 }
@@ -624,12 +702,54 @@ export async function cmdThreadStep(
   storageRoot: string,
   threadId: ThreadId,
   agentOverride: string | null,
-): Promise<StepOutput> {
+  count: number,
+): Promise<StepOutput[]> {
+  if (count < 1 || !Number.isInteger(count)) {
+    fail(`--count must be a positive integer, got: ${count}`);
+  }
+
+  const workflowHash = await resolveActiveThreadWorkflowHash(storageRoot, threadId);
+  const plog = createProcessLogger({
+    storageRoot,
+    context: { thread: threadId, workflow: workflowHash },
+  });
+
+  const results: StepOutput[] = [];
+  for (let i = 0; i < count; i++) {
+    const result = await cmdThreadStepOnce(storageRoot, threadId, agentOverride, plog);
+    results.push(result);
+    if (result.done) {
+      break;
+    }
+  }
+  return results;
+}
+
+async function resolveActiveThreadWorkflowHash(
+  storageRoot: string,
+  threadId: ThreadId,
+): Promise<CasRef> {
   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);
+  return chain.start.workflow;
+}
+
+async function cmdThreadStepOnce(
+  storageRoot: string,
+  threadId: ThreadId,
+  agentOverride: string | null,
+  plog: ProcessLogger,
+): Promise<StepOutput> {
+  const index = await loadThreadsIndex(storageRoot);
+  const headHash = index[threadId];
+  if (headHash === undefined) {
+    failStep(plog, `thread not active: ${threadId}`);
+  }
 
   const uwf = await createUwfStore(storageRoot);
   const chain = walkChain(uwf, headHash);
@@ -639,10 +759,17 @@ export async function cmdThreadStep(
 
   const nextResult = await evaluate(workflow, context);
   if (!nextResult.ok) {
-    fail(nextResult.error.message);
+    failStep(plog, `moderator evaluate failed: ${nextResult.error.message}`);
   }
 
-  if (nextResult.value === END_ROLE) {
+  plog.log(
+    PL_MODERATOR,
+    `moderator role=${nextResult.value.role} prompt=${nextResult.value.prompt}`,
+    null,
+  );
+
+  if (nextResult.value.role === END_ROLE) {
+    plog.log(PL_THREAD_ARCHIVED, `thread archived head=${headHash}`, null);
     await archiveThread(storageRoot, threadId, workflowHash, headHash);
     return {
       workflow: workflowHash,
@@ -652,18 +779,25 @@ export async function cmdThreadStep(
     };
   }
 
-  const role = nextResult.value;
+  const role = nextResult.value.role;
+  const edgePrompt = nextResult.value.prompt;
   const config = await loadWorkflowConfig(storageRoot);
   const agent = resolveAgentConfig(config, workflow, role, agentOverride);
 
+  plog.log(PL_AGENT_SPAWN, `spawning agent command=${agent.command}`, {
+    args: [...agent.args, threadId, role].join(" "),
+  });
+
   loadDotenv({ path: getEnvPath(storageRoot) });
-  const newHead = spawnAgent(agent, threadId, role);
+  const newHead = spawnAgent(plog, agent, threadId, role, edgePrompt);
+
+  plog.log(PL_AGENT_DONE, `agent returned head=${newHead}`, null);
 
   // 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}`);
+    failStep(plog, `agent returned hash that is not a StepNode: ${newHead}`);
   }
 
   // Reload threads index to avoid overwriting changes made by the agent subprocess
@@ -675,11 +809,12 @@ export async function cmdThreadStep(
   const contextAfter = buildModeratorContext(uwfAfter, chainAfter);
   const afterResult = await evaluate(workflow, contextAfter);
   if (!afterResult.ok) {
-    fail(afterResult.error.message);
+    failStep(plog, `post-step moderator evaluate failed: ${afterResult.error.message}`);
   }
 
-  const done = afterResult.value === END_ROLE;
+  const done = afterResult.value.role === END_ROLE;
   if (done) {
+    plog.log(PL_THREAD_ARCHIVED, `thread archived head=${newHead}`, null);
     await archiveThread(storageRoot, threadId, workflowHash, newHead);
   }
 

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

@@ -2,22 +2,31 @@ 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/workflow-protocol";
+import type {
+  CasRef,
+  RoleDefinition,
+  Transition,
+  WorkflowPayload,
+} from "@uncaged/workflow-protocol";
 import { parse } from "yaml";
 
 import {
   createUwfStore,
+  discoverProjectWorkflows,
   findRegistryName,
   loadWorkflowRegistry,
   resolveWorkflowHash,
   saveWorkflowRegistry,
   type UwfStore,
 } from "../store.js";
-import { parseWorkflowPayload } from "../validate.js";
+import { checkWorkflowFilenameConsistency, parseWorkflowPayload } from "../validate.js";
+
+export type WorkflowOrigin = "local" | "global";
 
 export type WorkflowListEntry = {
   name: string;
   hash: CasRef;
+  origin: WorkflowOrigin;
 };
 
 export type WorkflowPutOutput = {
@@ -42,38 +51,55 @@ function isJsonSchema(value: unknown): value is JSONSchema {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
-async function resolveOutputSchemaRef(
+/** Normalize graph transitions: ensure condition is null (not undefined) for fallback entries. */
+function normalizeGraph(graph: Record<string, Transition[]>): Record<string, Transition[]> {
+  const result: Record<string, Transition[]> = {};
+  for (const [node, transitions] of Object.entries(graph)) {
+    result[node] = transitions.map((t) => {
+      if (typeof t.prompt !== "string" || t.prompt.trim() === "") {
+        fail(`graph[${node}] transition to "${t.role}": prompt is required (non-empty string)`);
+      }
+      return {
+        role: t.role,
+        condition: t.condition ?? null,
+        prompt: t.prompt,
+      };
+    });
+  }
+  return result;
+}
+
+async function resolveFrontmatterRef(
   uwf: UwfStore,
   roleName: string,
-  outputSchema: unknown,
+  frontmatter: unknown,
 ): Promise<CasRef> {
-  if (!isJsonSchema(outputSchema)) {
-    fail(`role "${roleName}": outputSchema must be a JSON Schema object`);
+  if (!isJsonSchema(frontmatter)) {
+    fail(`role "${roleName}": frontmatter must be a JSON Schema object`);
   }
-  const schema: JSONSchema = outputSchema.title === undefined
-    ? { ...outputSchema, title: roleName }
-    : outputSchema;
+  const schema: JSONSchema =
+    frontmatter.title === undefined ? { ...frontmatter, title: roleName } : frontmatter;
   return putSchema(uwf.store, schema);
 }
 
-async function materializeWorkflowPayload(
+export 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(
+    const frontmatter = await resolveFrontmatterRef(
       uwf,
       `${raw.name}.${roleName}`,
-      role.outputSchema,
+      role.frontmatter,
     );
     roles[roleName] = {
       description: role.description,
-      identity: role.identity,
-      prepare: role.prepare,
-      execute: role.execute,
-      report: role.report,
-      outputSchema,
+      goal: role.goal,
+      capabilities: role.capabilities,
+      procedure: role.procedure,
+      output: role.output,
+      frontmatter,
     };
   }
   return {
@@ -81,7 +107,7 @@ async function materializeWorkflowPayload(
     description: raw.description,
     roles,
     conditions: raw.conditions,
-    graph: raw.graph,
+    graph: normalizeGraph(raw.graph),
   };
 }
 
@@ -108,6 +134,11 @@ export async function cmdWorkflowPut(
     fail("invalid workflow YAML: expected WorkflowPayload shape");
   }
 
+  const filenameError = checkWorkflowFilenameConsistency(filePath, payload);
+  if (filenameError !== null) {
+    fail(filenameError);
+  }
+
   const uwf = await createUwfStore(storageRoot);
   const materialized = await materializeWorkflowPayload(uwf, payload);
 
@@ -150,7 +181,26 @@ export async function cmdWorkflowShow(
   };
 }
 
-export async function cmdWorkflowList(storageRoot: string): Promise<WorkflowListEntry[]> {
+export async function cmdWorkflowList(
+  storageRoot: string,
+  projectRoot: string,
+): Promise<WorkflowListEntry[]> {
+  const localEntries = await discoverProjectWorkflows(projectRoot);
   const registry = await loadWorkflowRegistry(storageRoot);
-  return Object.entries(registry).map(([name, hash]) => ({ name, hash }));
+
+  const result: WorkflowListEntry[] = [];
+  const localNames = new Set<string>();
+
+  for (const entry of localEntries) {
+    localNames.add(entry.name);
+    result.push({ name: entry.name, hash: "(local)", origin: "local" });
+  }
+
+  for (const [name, hash] of Object.entries(registry)) {
+    if (!localNames.has(name)) {
+      result.push({ name, hash, origin: "global" });
+    }
+  }
+
+  return result;
 }

packages/cli-workflow/src/schemas.ts

@@ -1,15 +1,14 @@
 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/workflow-protocol";
+import { START_NODE_SCHEMA, STEP_NODE_SCHEMA, WORKFLOW_SCHEMA } from "@uncaged/workflow-protocol";
+
+export const TEXT_SCHEMA = { type: "string" as const };
 
 export type UwfSchemaHashes = {
   workflow: Hash;
   startNode: Hash;
   stepNode: Hash;
+  text: Hash;
 };
 
 /**
@@ -17,10 +16,11 @@ export type UwfSchemaHashes = {
  * Idempotent: safe to call on every CLI invocation.
  */
 export async function registerUwfSchemas(store: Store): Promise<UwfSchemaHashes> {
-  const [workflow, startNode, stepNode] = await Promise.all([
+  const [workflow, startNode, stepNode, text] = await Promise.all([
     putSchema(store, WORKFLOW_SCHEMA),
     putSchema(store, START_NODE_SCHEMA),
     putSchema(store, STEP_NODE_SCHEMA),
+    putSchema(store, TEXT_SCHEMA),
   ]);
-  return { workflow, startNode, stepNode };
+  return { workflow, startNode, stepNode, text };
 }

packages/cli-workflow/src/store.ts

@@ -1,4 +1,4 @@
-import { appendFile, mkdir, readFile, writeFile } from "node:fs/promises";
+import { appendFile, mkdir, readdir, readFile, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
 
@@ -11,6 +11,44 @@ import { registerUwfSchemas, type UwfSchemaHashes } from "./schemas.js";
 
 export type WorkflowRegistry = Record<string, CasRef>;
 
+/** A workflow entry discovered from the project-local .workflows/ directory. */
+export type ProjectWorkflowEntry = {
+  /** Workflow name (from YAML `name` field, equals filename stem). */
+  name: string;
+  /** Absolute path to the YAML file. */
+  filePath: string;
+};
+
+/**
+ * Scan `<projectRoot>/.workflows/*.yaml` (non-recursive) and return discovered entries.
+ * Returns an empty array if the directory does not exist.
+ */
+export async function discoverProjectWorkflows(
+  projectRoot: string,
+): Promise<ProjectWorkflowEntry[]> {
+  const dir = join(projectRoot, ".workflows");
+  let entries: string[];
+  try {
+    entries = await readdir(dir);
+  } catch (e) {
+    const err = e as NodeJS.ErrnoException;
+    if (err.code === "ENOENT" || err.code === "ENOTDIR") {
+      return [];
+    }
+    throw e;
+  }
+
+  const result: ProjectWorkflowEntry[] = [];
+  for (const entry of entries) {
+    if (!entry.endsWith(".yaml") && !entry.endsWith(".yml")) {
+      continue;
+    }
+    const stem = entry.endsWith(".yaml") ? entry.slice(0, -5) : entry.slice(0, -4);
+    result.push({ name: stem, filePath: join(dir, entry) });
+  }
+  return result;
+}
+
 /** Default filesystem root for uwf data (`~/.uncaged/workflow`). */
 export function getDefaultStorageRoot(): string {
   return join(homedir(), ".uncaged", "workflow");
@@ -104,6 +142,22 @@ export function resolveWorkflowHash(registry: WorkflowRegistry, id: string): Cas
   return registry[id] !== undefined ? registry[id] : id;
 }
 
+/**
+ * Resolve a workflow name to a project-local YAML file path.
+ * Returns null if the name is not found in the local entries.
+ */
+export function resolveProjectWorkflowFile(
+  localEntries: ProjectWorkflowEntry[],
+  name: string,
+): string | null {
+  for (const entry of localEntries) {
+    if (entry.name === name) {
+      return entry.filePath;
+    }
+  }
+  return null;
+}
+
 export function findRegistryName(registry: WorkflowRegistry, hash: Hash): string | null {
   for (const [name, h] of Object.entries(registry)) {
     if (h === hash) {

packages/cli-workflow/src/validate.ts

@@ -1,3 +1,4 @@
+import { basename } from "node:path";
 import type { CasRef, WorkflowPayload } from "@uncaged/workflow-protocol";
 
 const CAS_REF_PATTERN = /^[0-9A-HJKMNP-TV-Z]{13}$/;
@@ -14,15 +15,18 @@ function isRoleDefinition(value: unknown): boolean {
   if (!isRecord(value)) {
     return false;
   }
-  const outputSchema = value.outputSchema;
-  const schemaOk = isRecord(outputSchema) && typeof outputSchema.type === "string";
+  const frontmatter = value.frontmatter;
+  const frontmatterOk = isRecord(frontmatter) && typeof frontmatter.type === "string";
+  const capabilities = value.capabilities;
+  const capabilitiesOk =
+    Array.isArray(capabilities) && capabilities.every((c) => typeof c === "string");
   return (
     typeof value.description === "string" &&
-    typeof value.identity === "string" &&
-    typeof value.prepare === "string" &&
-    typeof value.execute === "string" &&
-    typeof value.report === "string" &&
-    schemaOk
+    typeof value.goal === "string" &&
+    capabilitiesOk &&
+    typeof value.procedure === "string" &&
+    typeof value.output === "string" &&
+    frontmatterOk
   );
 }
 
@@ -38,7 +42,12 @@ function isTransition(value: unknown): boolean {
     return false;
   }
   const condition = value.condition;
-  return typeof value.role === "string" && (condition === null || typeof condition === "string");
+  return (
+    typeof value.role === "string" &&
+    typeof value.prompt === "string" &&
+    value.prompt.trim() !== "" &&
+    (condition === null || condition === undefined || typeof condition === "string")
+  );
 }
 
 function isStringRecord(value: unknown, itemCheck: (item: unknown) => boolean): boolean {
@@ -57,6 +66,33 @@ function isGraph(value: unknown): boolean {
   );
 }
 
+/**
+ * Derive the expected workflow name from a file path (stem without extension).
+ * Returns the stem for `.yaml` / `.yml` files.
+ */
+export function workflowNameFromPath(filePath: string): string {
+  const base = basename(filePath);
+  if (base.endsWith(".yaml")) return base.slice(0, -5);
+  if (base.endsWith(".yml")) return base.slice(0, -4);
+  return base;
+}
+
+/**
+ * Check that the `name` field in a parsed payload matches the expected name
+ * derived from the file path.  Returns an error message string on mismatch,
+ * or null when the names are consistent.
+ */
+export function checkWorkflowFilenameConsistency(
+  filePath: string,
+  payload: WorkflowPayload,
+): string | null {
+  const expected = workflowNameFromPath(filePath);
+  if (payload.name !== expected) {
+    return `workflow name mismatch: file "${basename(filePath)}" implies name "${expected}" but YAML declares name "${payload.name}"`;
+  }
+  return null;
+}
+
 /** Validate YAML-parsed workflow document shape (outputSchema may be inline JSON Schema). */
 export function parseWorkflowPayload(raw: unknown): WorkflowPayload | null {
   if (!isRecord(raw)) {

packages/workflow-agent-builtin/__tests__/llm-parse.test.ts

@@ -0,0 +1,16 @@
+import { describe, expect, test } from "bun:test";
+
+import type { LlmToolCall } from "../src/llm/types.js";
+
+/** Mirror OpenAI response shape for parser coverage via chatCompletionWithTools integration later. */
+describe("LlmToolCall shape", () => {
+  test("tool call record fields", () => {
+    const call: LlmToolCall = {
+      id: "call_1",
+      name: "read_file",
+      arguments: '{"path":"README.md"}',
+    };
+    expect(call.name).toBe("read_file");
+    expect(JSON.parse(call.arguments)).toEqual({ path: "README.md" });
+  });
+});

packages/workflow-agent-builtin/__tests__/path.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, test } from "bun:test";
+import { resolve } from "node:path";
+import { resolvePath, resolvePathInWorkspace } from "../src/tools/path.js";
+
+describe("resolvePath", () => {
+  test("resolves relative paths against cwd", () => {
+    const root = "/workspace/project";
+    const resolved = resolvePath(root, "src/foo.ts");
+    expect(resolved).toBe(resolve(root, "src/foo.ts"));
+  });
+
+  test("resolves absolute paths as-is", () => {
+    const resolved = resolvePath("/workspace", "/etc/hosts");
+    expect(resolved).toBe("/etc/hosts");
+  });
+
+  test("resolves parent traversal normally", () => {
+    const resolved = resolvePath("/workspace/project", "../other/file.ts");
+    expect(resolved).toBe(resolve("/workspace/project", "../other/file.ts"));
+  });
+});
+
+describe("resolvePathInWorkspace", () => {
+  test("allows relative paths within workspace", () => {
+    const resolved = resolvePathInWorkspace("/workspace", "src/foo.ts");
+    expect(resolved).toBe(resolve("/workspace", "src/foo.ts"));
+  });
+
+  test("rejects path that escapes workspace root", () => {
+    const resolved = resolvePathInWorkspace("/workspace", "../etc/passwd");
+    expect(resolved).toBeNull();
+  });
+
+  test("rejects absolute path escape via double-dot", () => {
+    const resolved = resolvePathInWorkspace("/workspace/project", "../../outside");
+    expect(resolved).toBeNull();
+  });
+
+  test("allows deep nested path", () => {
+    const resolved = resolvePathInWorkspace("/workspace", "a/b/c/file.txt");
+    expect(resolved).toBe(resolve("/workspace", "a/b/c/file.txt"));
+  });
+});

packages/workflow-agent-builtin/__tests__/prompt.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, test } from "bun:test";
+
+import type { AgentContext } from "@uncaged/workflow-agent-kit";
+
+import { buildBuiltinPrompt } from "../src/prompt.js";
+
+function minimalContext(overrides: Partial<AgentContext> = {}): AgentContext {
+  return {
+    threadId: "00000000000000000000000000" as AgentContext["threadId"],
+    role: "developer",
+    store: {} as AgentContext["store"],
+    workflow: {
+      name: "test",
+      roles: {
+        developer: {
+          goal: "Ship the fix",
+          capabilities: ["file-edit"],
+          procedure: ["Edit files"],
+          output: "A patch",
+          frontmatter: "schema-hash",
+        },
+      },
+      conditions: {},
+      graph: {},
+    },
+    start: { workflow: "wf-hash", prompt: "Fix the bug" },
+    steps: [],
+    outputFormatInstruction: "---\nstatus: done\n---",
+    ...overrides,
+  };
+}
+
+describe("buildBuiltinPrompt", () => {
+  test("includes output format, task, and role goal", () => {
+    const prompt = buildBuiltinPrompt(minimalContext());
+    expect(prompt).toContain("status: done");
+    expect(prompt).toContain("## Goal");
+    expect(prompt).toContain("Ship the fix");
+    expect(prompt).toContain("## Task");
+    expect(prompt).toContain("Fix the bug");
+  });
+
+  test("includes history when steps exist", () => {
+    const prompt = buildBuiltinPrompt(
+      minimalContext({
+        steps: [
+          {
+            role: "planner",
+            output: { plan: "step 1" },
+            agent: "uwf-builtin",
+            detail: "detail-hash",
+          },
+        ],
+      }),
+    );
+    expect(prompt).toContain("## Previous Steps");
+    expect(prompt).toContain("planner");
+  });
+});

packages/workflow-agent-builtin/package.json

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

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

@@ -0,0 +1,123 @@
+import type { Store } from "@uncaged/json-cas";
+import {
+  type AgentContext,
+  type AgentRunResult,
+  createAgent,
+  loadWorkflowConfig,
+  resolveModel,
+  resolveStorageRoot,
+} from "@uncaged/workflow-agent-kit";
+import { generateUlid } from "@uncaged/workflow-util";
+
+import { storeBuiltinDetail } from "./detail.js";
+import type { ChatMessage } from "./llm/index.js";
+import { BUILTIN_CONTINUE_MAX_TURNS, BUILTIN_MAX_TURNS, runBuiltinLoop } from "./loop.js";
+import { buildBuiltinPrompt } from "./prompt.js";
+import type { BuiltinSessionState } from "./types.js";
+
+const sessions = new Map<string, BuiltinSessionState>();
+
+function getSession(sessionId: string): BuiltinSessionState {
+  const session = sessions.get(sessionId);
+  if (session === undefined) {
+    throw new Error(`builtin session not found: ${sessionId}`);
+  }
+  return session;
+}
+
+function buildToolContext(storageRoot: string): { cwd: string; storageRoot: string } {
+  return {
+    cwd: process.cwd(),
+    storageRoot,
+  };
+}
+
+async function runBuiltinWithMessages(
+  storageRoot: string,
+  provider: ReturnType<typeof resolveModel>,
+  messages: ChatMessage[],
+  session: BuiltinSessionState,
+  store: Store,
+  maxTurns: number,
+): Promise<AgentRunResult> {
+  const loopResult = await runBuiltinLoop({
+    provider,
+    messages,
+    toolCtx: buildToolContext(storageRoot),
+    maxTurns,
+    existingTurns: session.turns,
+  });
+
+  session.messages = loopResult.messages;
+  session.turns = loopResult.turns;
+
+  const { detailHash, output } = await storeBuiltinDetail(
+    store,
+    session.sessionId,
+    session.model,
+    session.startedAtMs,
+    session.turns,
+  );
+
+  const finalOutput = output !== "" ? output : loopResult.finalText;
+  return { output: finalOutput, detailHash, sessionId: session.sessionId };
+}
+
+async function runBuiltin(ctx: AgentContext): Promise<AgentRunResult> {
+  const storageRoot = resolveStorageRoot();
+  const config = await loadWorkflowConfig(storageRoot);
+  const provider = resolveModel(config, config.defaultModel);
+
+  const sessionId = generateUlid(Date.now());
+  const systemPrompt = buildBuiltinPrompt(ctx);
+  const messages: ChatMessage[] = [{ role: "system", content: systemPrompt }];
+
+  const session: BuiltinSessionState = {
+    sessionId,
+    model: provider.model,
+    startedAtMs: Date.now(),
+    messages,
+    turns: [],
+  };
+  sessions.set(sessionId, session);
+
+  return runBuiltinWithMessages(
+    storageRoot,
+    provider,
+    messages,
+    session,
+    ctx.store,
+    BUILTIN_MAX_TURNS,
+  );
+}
+
+async function continueBuiltin(
+  sessionId: string,
+  message: string,
+  store: Store,
+): Promise<AgentRunResult> {
+  const session = getSession(sessionId);
+  const storageRoot = resolveStorageRoot();
+  const config = await loadWorkflowConfig(storageRoot);
+  const provider = resolveModel(config, config.defaultModel);
+
+  const messages: ChatMessage[] = [...session.messages, { role: "user", content: message }];
+
+  return runBuiltinWithMessages(
+    storageRoot,
+    provider,
+    messages,
+    session,
+    store,
+    BUILTIN_CONTINUE_MAX_TURNS,
+  );
+}
+
+/** Agent CLI factory: built-in LLM loop with file/shell tools. */
+export function createBuiltinAgent(): () => Promise<void> {
+  return createAgent({
+    name: "builtin",
+    run: runBuiltin,
+    continue: continueBuiltin,
+  });
+}

packages/workflow-agent-builtin/src/cli.ts

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

packages/workflow-agent-builtin/src/detail.ts

@@ -0,0 +1,115 @@
+import { bootstrap, putSchema, type Store } from "@uncaged/json-cas";
+
+import { BUILTIN_DETAIL_SCHEMA, BUILTIN_TURN_SCHEMA } from "./schemas.js";
+import type {
+  BuiltinDetailPayload,
+  BuiltinLoopTurn,
+  BuiltinToolCall,
+  BuiltinTurnPayload,
+  BuiltinTurnRole,
+} from "./types.js";
+
+function mapToolCalls(calls: NonNullable<BuiltinLoopTurn["toolCalls"]>): BuiltinToolCall[] {
+  return calls.map((call) => ({
+    name: call.name,
+    args: call.args,
+  }));
+}
+
+function loopTurnToAssistantPayload(turn: BuiltinLoopTurn, index: number): BuiltinTurnPayload {
+  return {
+    index,
+    role: "assistant",
+    content: turn.assistantContent ?? "",
+    toolCalls:
+      turn.toolCalls !== null && turn.toolCalls.length > 0 ? mapToolCalls(turn.toolCalls) : null,
+    reasoning: null,
+  };
+}
+
+function loopTurnToToolPayloads(turn: BuiltinLoopTurn, startIndex: number): BuiltinTurnPayload[] {
+  if (turn.toolResults === null || turn.toolResults.length === 0) {
+    return [];
+  }
+  const payloads: BuiltinTurnPayload[] = [];
+  let index = startIndex;
+  for (const result of turn.toolResults) {
+    payloads.push({
+      index,
+      role: "tool" as BuiltinTurnRole,
+      content: result.content,
+      toolCalls: null,
+      reasoning: null,
+    });
+    index += 1;
+  }
+  return payloads;
+}
+
+/** Last assistant message with non-empty text. */
+export function extractFinalAssistantText(turns: BuiltinLoopTurn[]): string {
+  for (let i = turns.length - 1; i >= 0; i--) {
+    const turn = turns[i];
+    if (turn === undefined) {
+      continue;
+    }
+    const text = turn.assistantContent;
+    if (text !== null && text.trim() !== "") {
+      return text;
+    }
+  }
+  return "";
+}
+
+type BuiltinSchemaHashes = {
+  turn: string;
+  detail: string;
+};
+
+async function registerBuiltinSchemas(store: Store): Promise<BuiltinSchemaHashes> {
+  await bootstrap(store);
+  const [turn, detail] = await Promise.all([
+    putSchema(store, BUILTIN_TURN_SCHEMA),
+    putSchema(store, BUILTIN_DETAIL_SCHEMA),
+  ]);
+  return { turn, detail };
+}
+
+export async function storeBuiltinDetail(
+  store: Store,
+  sessionId: string,
+  model: string,
+  startedAtMs: number,
+  turns: BuiltinLoopTurn[],
+  nowMs: number = Date.now(),
+): Promise<{ detailHash: string; output: string }> {
+  const schemas = await registerBuiltinSchemas(store);
+  const turnHashes: string[] = [];
+  let turnIndex = 0;
+
+  for (const loopTurn of turns) {
+    const assistant = loopTurnToAssistantPayload(loopTurn, turnIndex);
+    const assistantHash = await store.put(schemas.turn, assistant);
+    turnHashes.push(assistantHash);
+    turnIndex += 1;
+
+    const toolPayloads = loopTurnToToolPayloads(loopTurn, turnIndex);
+    for (const toolPayload of toolPayloads) {
+      const toolHash = await store.put(schemas.turn, toolPayload);
+      turnHashes.push(toolHash);
+      turnIndex += 1;
+    }
+  }
+
+  const duration = Math.max(0, nowMs - startedAtMs);
+  const detail: BuiltinDetailPayload = {
+    sessionId,
+    model,
+    duration,
+    turnCount: turnHashes.length,
+    turns: turnHashes,
+  };
+  const detailHash = await store.put(schemas.detail, detail);
+  const output = extractFinalAssistantText(turns);
+  return { detailHash, output };
+}

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

@@ -0,0 +1,14 @@
+export { createBuiltinAgent } from "./agent.js";
+export { extractFinalAssistantText, storeBuiltinDetail } from "./detail.js";
+export type { ChatMessage, LlmAssistantResponse, LlmToolCall } from "./llm/index.js";
+export { chatCompletionWithTools } from "./llm/index.js";
+export { BUILTIN_CONTINUE_MAX_TURNS, BUILTIN_MAX_TURNS, runBuiltinLoop } from "./loop.js";
+export { buildBuiltinPrompt } from "./prompt.js";
+export type { BuiltinTool, ToolContext } from "./tools/index.js";
+export { executeBuiltinTool, getBuiltinTools } from "./tools/index.js";
+export type {
+  BuiltinDetailPayload,
+  BuiltinLoopTurn,
+  BuiltinSessionState,
+  BuiltinTurnPayload,
+} from "./types.js";

packages/workflow-agent-builtin/src/llm/index.ts

@@ -0,0 +1,7 @@
+export { chatCompletionWithTools } from "./llm.js";
+export type {
+  ChatMessage,
+  LlmAssistantResponse,
+  LlmToolCall,
+  OpenAiToolDefinition,
+} from "./types.js";

packages/workflow-agent-builtin/src/llm/llm.ts

@@ -0,0 +1,135 @@
+import type { ResolvedLlmProvider } from "@uncaged/workflow-agent-kit";
+
+import type {
+  ChatMessage,
+  LlmAssistantResponse,
+  LlmToolCall,
+  OpenAiToolDefinition,
+} from "./types.js";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function chatUrl(baseUrl: string): string {
+  const trimmed = baseUrl.replace(/\/+$/, "");
+  return `${trimmed}/chat/completions`;
+}
+
+function parseToolCalls(raw: unknown): LlmToolCall[] | null {
+  if (!Array.isArray(raw) || raw.length === 0) {
+    return null;
+  }
+  const calls: LlmToolCall[] = [];
+  for (const entry of raw) {
+    if (!isRecord(entry)) {
+      continue;
+    }
+    const id = entry.id;
+    const fn = entry.function;
+    if (typeof id !== "string" || !isRecord(fn)) {
+      continue;
+    }
+    const name = fn.name;
+    const args = fn.arguments;
+    if (typeof name !== "string" || typeof args !== "string") {
+      continue;
+    }
+    calls.push({ id, name, arguments: args });
+  }
+  return calls.length > 0 ? calls : null;
+}
+
+function parseAssistantMessage(parsed: unknown): LlmAssistantResponse {
+  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 contentRaw = messageObj.content;
+  const content =
+    typeof contentRaw === "string"
+      ? contentRaw
+      : contentRaw === null || contentRaw === undefined
+        ? null
+        : null;
+  const toolCalls = parseToolCalls(messageObj.tool_calls);
+  return { content, toolCalls };
+}
+
+function serializeMessage(message: ChatMessage): Record<string, unknown> {
+  if (message.role === "tool") {
+    return {
+      role: "tool",
+      tool_call_id: message.tool_call_id,
+      content: message.content,
+    };
+  }
+  if (message.role === "assistant") {
+    const base: Record<string, unknown> = {
+      role: "assistant",
+      content: message.content,
+    };
+    if (message.tool_calls !== null && message.tool_calls.length > 0) {
+      base.tool_calls = message.tool_calls.map((call) => ({
+        id: call.id,
+        type: "function",
+        function: { name: call.name, arguments: call.arguments },
+      }));
+    }
+    return base;
+  }
+  return { role: message.role, content: message.content };
+}
+
+/** OpenAI-compatible chat completion with tool calling (non-streaming). */
+export async function chatCompletionWithTools(
+  provider: ResolvedLlmProvider,
+  messages: ChatMessage[],
+  tools: OpenAiToolDefinition[],
+): Promise<LlmAssistantResponse> {
+  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: messages.map(serializeMessage),
+        tools,
+        tool_choice: "auto",
+      }),
+    });
+  } 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 parseAssistantMessage(parsed);
+}

packages/workflow-agent-builtin/src/llm/types.ts

@@ -0,0 +1,29 @@
+export type LlmToolCall = {
+  id: string;
+  name: string;
+  arguments: string;
+};
+
+export type LlmAssistantResponse = {
+  content: string | null;
+  toolCalls: LlmToolCall[] | null;
+};
+
+export type ChatMessage =
+  | { role: "system"; content: string }
+  | { role: "user"; content: string }
+  | {
+      role: "assistant";
+      content: string | null;
+      tool_calls: LlmToolCall[] | null;
+    }
+  | { role: "tool"; tool_call_id: string; content: string };
+
+export type OpenAiToolDefinition = {
+  type: "function";
+  function: {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+  };
+};

packages/workflow-agent-builtin/src/loop.ts

@@ -0,0 +1,110 @@
+import type { ResolvedLlmProvider } from "@uncaged/workflow-agent-kit";
+import { createLogger } from "@uncaged/workflow-util";
+
+import { type ChatMessage, chatCompletionWithTools, type LlmToolCall } from "./llm/index.js";
+import {
+  builtinToolsToOpenAi,
+  executeBuiltinTool,
+  getBuiltinTools,
+  type ToolContext,
+} from "./tools/index.js";
+import type { BuiltinLoopTurn, BuiltinToolCallRecord, BuiltinToolResultRecord } from "./types.js";
+
+const log = createLogger({ sink: { kind: "stderr" } });
+
+export const BUILTIN_MAX_TURNS = 30;
+export const BUILTIN_CONTINUE_MAX_TURNS = 5;
+
+export type RunBuiltinLoopOptions = {
+  provider: ResolvedLlmProvider;
+  messages: ChatMessage[];
+  toolCtx: ToolContext;
+  maxTurns: number;
+  existingTurns: BuiltinLoopTurn[];
+};
+
+export type RunBuiltinLoopResult = {
+  finalText: string;
+  messages: ChatMessage[];
+  turns: BuiltinLoopTurn[];
+};
+
+function mapToolCalls(calls: LlmToolCall[]): BuiltinToolCallRecord[] {
+  return calls.map((call) => ({
+    id: call.id,
+    name: call.name,
+    args: call.arguments,
+  }));
+}
+
+/** Agent run loop: LLM ↔ tools until no tool_calls or maxTurns. */
+export async function runBuiltinLoop(
+  options: RunBuiltinLoopOptions,
+): Promise<RunBuiltinLoopResult> {
+  const messages = [...options.messages];
+  const turns = [...options.existingTurns];
+  const openAiTools = builtinToolsToOpenAi(getBuiltinTools());
+  let finalText = "";
+
+  for (let turn = 0; turn < options.maxTurns; turn++) {
+    log("8K2M4N7P", `builtin loop turn ${turn + 1}/${options.maxTurns}`);
+    const response = await chatCompletionWithTools(options.provider, messages, openAiTools);
+
+    const assistantMessage: ChatMessage = {
+      role: "assistant",
+      content: response.content,
+      tool_calls: response.toolCalls,
+    };
+    messages.push(assistantMessage);
+
+    if (response.toolCalls === null || response.toolCalls.length === 0) {
+      finalText = response.content ?? "";
+      turns.push({
+        assistantContent: response.content,
+        toolCalls: null,
+        toolResults: null,
+      });
+      break;
+    }
+
+    const toolCallRecords = mapToolCalls(response.toolCalls);
+    const toolResults: BuiltinToolResultRecord[] = [];
+
+    for (const call of response.toolCalls) {
+      const result = await executeBuiltinTool(call.name, call.arguments, options.toolCtx);
+      toolResults.push({
+        toolCallId: call.id,
+        name: call.name,
+        content: result,
+      });
+      messages.push({
+        role: "tool",
+        tool_call_id: call.id,
+        content: result,
+      });
+    }
+
+    turns.push({
+      assistantContent: response.content,
+      toolCalls: toolCallRecords,
+      toolResults,
+    });
+  }
+
+  if (finalText === "" && messages.length > 0) {
+    for (let i = messages.length - 1; i >= 0; i--) {
+      const msg = messages[i];
+      if (
+        msg !== undefined &&
+        msg.role === "assistant" &&
+        msg.content !== null &&
+        msg.content.trim() !== ""
+      ) {
+        finalText = msg.content;
+        break;
+      }
+    }
+  }
+
+  return { finalText, messages, turns };
+}

packages/workflow-agent-builtin/src/prompt.ts

@@ -0,0 +1,36 @@
+import { type AgentContext, buildRolePrompt } from "@uncaged/workflow-agent-kit";
+
+function buildHistorySummary(steps: AgentContext["steps"]): string {
+  if (steps.length === 0) {
+    return "";
+  }
+
+  const lines: string[] = ["## Previous Steps"];
+  for (let i = 0; i < steps.length; i++) {
+    const step = steps[i];
+    if (step === undefined) {
+      continue;
+    }
+    lines.push("");
+    lines.push(`### Step ${i + 1}: ${step.role}`);
+    lines.push(`Output: ${JSON.stringify(step.output)}`);
+    lines.push(`Agent: ${step.agent}`);
+  }
+  return lines.join("\n");
+}
+
+/** Assemble output format, role prompt, task, and history (aligned with buildHermesPrompt). */
+export function buildBuiltinPrompt(ctx: AgentContext): string {
+  const roleDef = ctx.workflow.roles[ctx.role];
+  const rolePrompt = roleDef !== undefined ? buildRolePrompt(roleDef) : "";
+  const parts: string[] = [];
+  if (ctx.outputFormatInstruction !== "") {
+    parts.push(ctx.outputFormatInstruction, "");
+  }
+  parts.push(rolePrompt, "", "## Task", ctx.start.prompt);
+  const historyBlock = buildHistorySummary(ctx.steps);
+  if (historyBlock !== "") {
+    parts.push("", historyBlock);
+  }
+  return parts.join("\n");
+}

packages/workflow-agent-builtin/src/schemas.ts

@@ -0,0 +1,46 @@
+import type { JSONSchema } from "@uncaged/json-cas";
+
+const BUILTIN_TOOL_CALL_SCHEMA: JSONSchema = {
+  type: "object",
+  required: ["name", "args"],
+  properties: {
+    name: { type: "string" },
+    args: { type: "string" },
+  },
+  additionalProperties: false,
+};
+
+export const BUILTIN_TURN_SCHEMA: JSONSchema = {
+  title: "builtin-turn",
+  type: "object",
+  required: ["index", "role", "content"],
+  properties: {
+    index: { type: "integer" },
+    role: { type: "string", enum: ["assistant", "tool"] },
+    content: { type: "string" },
+    toolCalls: {
+      anyOf: [{ type: "array", items: BUILTIN_TOOL_CALL_SCHEMA }, { type: "null" }],
+    },
+    reasoning: {
+      anyOf: [{ type: "string" }, { type: "null" }],
+    },
+  },
+  additionalProperties: false,
+};
+
+export const BUILTIN_DETAIL_SCHEMA: JSONSchema = {
+  title: "builtin-detail",
+  type: "object",
+  required: ["sessionId", "model", "duration", "turnCount", "turns"],
+  properties: {
+    sessionId: { type: "string" },
+    model: { type: "string" },
+    duration: { type: "integer" },
+    turnCount: { type: "integer" },
+    turns: {
+      type: "array",
+      items: { type: "string", format: "cas_ref" },
+    },
+  },
+  additionalProperties: false,
+};

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

@@ -0,0 +1,44 @@
+import type { OpenAiToolDefinition } from "../llm/index.js";
+
+import { readFileTool } from "./read-file.js";
+import { runCommandTool } from "./run-command.js";
+import type { BuiltinTool, ToolContext } from "./types.js";
+import { writeFileTool } from "./write-file.js";
+
+export { resolvePath } from "./path.js";
+export type { BuiltinTool, ToolContext } from "./types.js";
+
+const BUILTIN_TOOLS: BuiltinTool[] = [readFileTool, writeFileTool, runCommandTool];
+
+export function getBuiltinTools(): readonly BuiltinTool[] {
+  return BUILTIN_TOOLS;
+}
+
+export function builtinToolsToOpenAi(tools: readonly BuiltinTool[]): OpenAiToolDefinition[] {
+  return tools.map((tool) => ({
+    type: "function",
+    function: {
+      name: tool.name,
+      description: tool.description,
+      parameters: tool.parameters as Record<string, unknown>,
+    },
+  }));
+}
+
+export async function executeBuiltinTool(
+  name: string,
+  argsJson: string,
+  ctx: ToolContext,
+): Promise<string> {
+  const tool = BUILTIN_TOOLS.find((t) => t.name === name);
+  if (tool === undefined) {
+    return `Error: unknown tool ${name}`;
+  }
+  let args: unknown;
+  try {
+    args = JSON.parse(argsJson) as unknown;
+  } catch {
+    return "Error: tool arguments must be valid JSON";
+  }
+  return tool.execute(args, ctx);
+}

packages/workflow-agent-builtin/src/tools/path.ts

@@ -0,0 +1,17 @@
+import { isAbsolute, relative, resolve } from "node:path";
+
+/** Resolve a path relative to the working directory. */
+export function resolvePath(cwd: string, inputPath: string): string {
+  return resolve(cwd, inputPath);
+}
+
+/** Reject paths that escape the workspace root via `..` segments. */
+export function resolvePathInWorkspace(cwd: string, inputPath: string): string | null {
+  const root = resolve(cwd);
+  const target = resolve(root, inputPath);
+  const rel = relative(root, target);
+  if (rel.startsWith("..") || isAbsolute(rel)) {
+    return null;
+  }
+  return target;
+}

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

@@ -0,0 +1,44 @@
+import { readFile, stat } from "node:fs/promises";
+import { resolvePathInWorkspace } from "./path.js";
+import type { BuiltinTool } from "./types.js";
+
+const MAX_READ_BYTES = 512 * 1024;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export const readFileTool: BuiltinTool = {
+  name: "read_file",
+  description: "Read a UTF-8 text file from the workspace.",
+  parameters: {
+    type: "object",
+    required: ["path"],
+    properties: {
+      path: { type: "string", description: "Relative or absolute path within the workspace." },
+    },
+    additionalProperties: false,
+  },
+  execute: async (args, ctx) => {
+    if (!isRecord(args) || typeof args.path !== "string") {
+      return "Error: path must be a string";
+    }
+    const resolved = resolvePathInWorkspace(ctx.cwd, args.path);
+    if (resolved === null) {
+      return "Error: path escapes workspace root";
+    }
+    try {
+      const info = await stat(resolved);
+      if (!info.isFile()) {
+        return "Error: not a file";
+      }
+      if (info.size > MAX_READ_BYTES) {
+        return `Error: file exceeds ${MAX_READ_BYTES} byte limit`;
+      }
+      return await readFile(resolved, "utf8");
+    } catch (cause) {
+      const message = cause instanceof Error ? cause.message : String(cause);
+      return `Error: ${message}`;
+    }
+  },
+};

packages/workflow-agent-builtin/src/tools/run-command.ts

@@ -0,0 +1,103 @@
+import { spawn } from "node:child_process";
+import { resolvePathInWorkspace } from "./path.js";
+import type { BuiltinTool } from "./types.js";
+
+const COMMAND_TIMEOUT_MS = 60_000;
+const MAX_OUTPUT_CHARS = 32_000;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function truncate(text: string, maxChars: number): string {
+  if (text.length <= maxChars) {
+    return text;
+  }
+  return `${text.slice(0, maxChars)}\n...(truncated)`;
+}
+
+function runShell(
+  command: string,
+  cwd: string,
+): Promise<{ stdout: string; stderr: string; code: number }> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, {
+      cwd,
+      env: process.env,
+      shell: true,
+      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();
+    });
+
+    const timer = setTimeout(() => {
+      child.kill("SIGTERM");
+    }, COMMAND_TIMEOUT_MS);
+
+    child.on("error", (cause) => {
+      clearTimeout(timer);
+      const message = cause instanceof Error ? cause.message : String(cause);
+      reject(new Error(message));
+    });
+
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      resolve({ stdout, stderr, code: code ?? 1 });
+    });
+  });
+}
+
+export const runCommandTool: BuiltinTool = {
+  name: "run_command",
+  description:
+    "Run a shell command in the workspace. Requires UWF_BUILTIN_ALLOW_SHELL=1. Output is truncated.",
+  parameters: {
+    type: "object",
+    required: ["command"],
+    properties: {
+      command: { type: "string", description: "Shell command to execute." },
+      cwd: {
+        type: "string",
+        description: "Optional working directory relative to workspace root.",
+      },
+    },
+    additionalProperties: false,
+  },
+  execute: async (args, ctx) => {
+    if (process.env.UWF_BUILTIN_ALLOW_SHELL !== "1") {
+      return "Error: run_command disabled. Set UWF_BUILTIN_ALLOW_SHELL=1 to enable.";
+    }
+    if (!isRecord(args) || typeof args.command !== "string") {
+      return "Error: command must be a string";
+    }
+    let workDir = ctx.cwd;
+    if (args.cwd !== undefined && args.cwd !== null) {
+      if (typeof args.cwd !== "string") {
+        return "Error: cwd must be a string";
+      }
+      const resolved = resolvePathInWorkspace(ctx.cwd, args.cwd);
+      if (resolved === null) {
+        return "Error: cwd escapes workspace root";
+      }
+      workDir = resolved;
+    }
+    try {
+      const { stdout, stderr, code } = await runShell(args.command, workDir);
+      const out = truncate(
+        `exit_code: ${code}\n--- stdout ---\n${stdout}\n--- stderr ---\n${stderr}`,
+        MAX_OUTPUT_CHARS,
+      );
+      return out;
+    } catch (cause) {
+      const message = cause instanceof Error ? cause.message : String(cause);
+      return `Error: ${message}`;
+    }
+  },
+};

packages/workflow-agent-builtin/src/tools/types.ts

@@ -0,0 +1,13 @@
+import type { JSONSchema } from "@uncaged/json-cas";
+
+export type ToolContext = {
+  cwd: string;
+  storageRoot: string;
+};
+
+export type BuiltinTool = {
+  name: string;
+  description: string;
+  parameters: JSONSchema;
+  execute: (args: unknown, ctx: ToolContext) => Promise<string>;
+};

packages/workflow-agent-builtin/src/tools/write-file.ts

@@ -0,0 +1,39 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { resolvePathInWorkspace } from "./path.js";
+import type { BuiltinTool } from "./types.js";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export const writeFileTool: BuiltinTool = {
+  name: "write_file",
+  description: "Write UTF-8 text to a file in the workspace (creates parent directories).",
+  parameters: {
+    type: "object",
+    required: ["path", "content"],
+    properties: {
+      path: { type: "string", description: "Relative or absolute path within the workspace." },
+      content: { type: "string", description: "File contents to write." },
+    },
+    additionalProperties: false,
+  },
+  execute: async (args, ctx) => {
+    if (!isRecord(args) || typeof args.path !== "string" || typeof args.content !== "string") {
+      return "Error: path and content must be strings";
+    }
+    const resolved = resolvePathInWorkspace(ctx.cwd, args.path);
+    if (resolved === null) {
+      return "Error: path escapes workspace root";
+    }
+    try {
+      await mkdir(dirname(resolved), { recursive: true });
+      await writeFile(resolved, args.content, "utf8");
+      return `Wrote ${args.content.length} bytes to ${args.path}`;
+    } catch (cause) {
+      const message = cause instanceof Error ? cause.message : String(cause);
+      return `Error: ${message}`;
+    }
+  },
+};

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

@@ -0,0 +1,50 @@
+import type { ChatMessage } from "./llm/index.js";
+
+export type BuiltinToolCallRecord = {
+  id: string;
+  name: string;
+  args: string;
+};
+
+export type BuiltinToolResultRecord = {
+  toolCallId: string;
+  name: string;
+  content: string;
+};
+
+export type BuiltinLoopTurn = {
+  assistantContent: string | null;
+  toolCalls: BuiltinToolCallRecord[] | null;
+  toolResults: BuiltinToolResultRecord[] | null;
+};
+
+export type BuiltinSessionState = {
+  sessionId: string;
+  model: string;
+  startedAtMs: number;
+  messages: ChatMessage[];
+  turns: BuiltinLoopTurn[];
+};
+
+export type BuiltinTurnRole = "assistant" | "tool";
+
+export type BuiltinToolCall = {
+  name: string;
+  args: string;
+};
+
+export type BuiltinTurnPayload = {
+  index: number;
+  role: BuiltinTurnRole;
+  content: string;
+  toolCalls: BuiltinToolCall[] | null;
+  reasoning: string | null;
+};
+
+export type BuiltinDetailPayload = {
+  sessionId: string;
+  model: string;
+  duration: number;
+  turnCount: number;
+  turns: string[];
+};

packages/workflow-agent-builtin/tsconfig.json

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

packages/workflow-agent-claude-code/__tests__/claude-code.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, test } from "bun:test";
+import type { AgentContext } from "@uncaged/workflow-agent-kit";
+import type { ThreadId } from "@uncaged/workflow-protocol";
+import { buildClaudeCodePrompt } from "../src/claude-code.js";
+
+function makeCtx(overrides: Partial<AgentContext> = {}): AgentContext {
+  return {
+    threadId: "01JTEST0000000000000000000" as ThreadId,
+    edgePrompt: "Proceed with the assigned role.",
+    isFirstVisit: true,
+    workflow: {
+      roles: {
+        developer: {
+          description: "TDD implementation per test spec",
+          goal: "Write code",
+          capabilities: ["coding"],
+          procedure: "1. Read spec\n2. Write code",
+          output: "List files changed",
+          frontmatter: "",
+        },
+      },
+      conditions: {},
+      graph: {},
+    },
+    role: "developer",
+    start: { prompt: "Fix the bug", workflowHash: "abc123", threadId: "t1" },
+    steps: [],
+    store: {} as AgentContext["store"],
+    outputFormatInstruction: "Use YAML frontmatter",
+    ...overrides,
+  };
+}
+
+describe("buildClaudeCodePrompt", () => {
+  test("assembles outputFormatInstruction + role prompt + task prompt", () => {
+    const result = buildClaudeCodePrompt(makeCtx());
+    expect(result).toMatch(/^Use YAML frontmatter/);
+    expect(result).toContain("Write code");
+    expect(result).toContain("## Task\nFix the bug");
+  });
+
+  test("includes previous steps as history summary", () => {
+    const ctx = makeCtx({
+      steps: [{ role: "planner", output: '{"plan":"do X"}', agent: "hermes" }],
+    });
+    const result = buildClaudeCodePrompt(ctx);
+    expect(result).toContain("## Previous Steps");
+    expect(result).toContain("Step 1: planner");
+    expect(result).toContain("do X");
+  });
+
+  test("omits history section when steps array is empty", () => {
+    const result = buildClaudeCodePrompt(makeCtx({ steps: [] }));
+    expect(result).not.toContain("## Previous Steps");
+  });
+
+  test("works without outputFormatInstruction", () => {
+    const result = buildClaudeCodePrompt(makeCtx({ outputFormatInstruction: "" }));
+    expect(result).not.toMatch(/^\s*\n/);
+    expect(result).toContain("Write code");
+    expect(result).toContain("## Task");
+  });
+});

packages/workflow-agent-claude-code/__tests__/session-detail.test.ts

@@ -0,0 +1,115 @@
+import { describe, expect, test } from "bun:test";
+import { createMemoryStore, walk } from "@uncaged/json-cas";
+import {
+  parseClaudeCodeJsonOutput,
+  storeClaudeCodeDetail,
+  storeClaudeCodeRawOutput,
+} from "../src/session-detail.js";
+import type { ClaudeCodeParsedResult } from "../src/types.js";
+
+describe("parseClaudeCodeJsonOutput", () => {
+  test("parses valid claude -p --output-format json output", () => {
+    const stdout = JSON.stringify({
+      type: "result",
+      subtype: "success",
+      result: "Done fixing bug",
+      session_id: "75e2167f-abc",
+      num_turns: 3,
+      total_cost_usd: 0.08,
+      duration_ms: 10276,
+    });
+    const parsed = parseClaudeCodeJsonOutput(stdout);
+    expect(parsed).not.toBeNull();
+    expect(parsed!.type).toBe("result");
+    expect(parsed!.subtype).toBe("success");
+    expect(parsed!.result).toBe("Done fixing bug");
+    expect(parsed!.sessionId).toBe("75e2167f-abc");
+    expect(parsed!.numTurns).toBe(3);
+    expect(parsed!.totalCostUsd).toBe(0.08);
+    expect(parsed!.durationMs).toBe(10276);
+  });
+
+  test("parses error_max_turns result", () => {
+    const stdout = JSON.stringify({
+      type: "result",
+      subtype: "error_max_turns",
+      result: "Ran out of turns",
+      session_id: "abc-def",
+      num_turns: 90,
+      total_cost_usd: 1.5,
+      duration_ms: 50000,
+    });
+    const parsed = parseClaudeCodeJsonOutput(stdout);
+    expect(parsed).not.toBeNull();
+    expect(parsed!.subtype).toBe("error_max_turns");
+    expect(parsed!.result).toBe("Ran out of turns");
+  });
+
+  test("returns null for non-JSON output", () => {
+    const parsed = parseClaudeCodeJsonOutput("Some random text\nwithout JSON");
+    expect(parsed).toBeNull();
+  });
+
+  test("returns null when session_id is missing", () => {
+    const stdout = JSON.stringify({ type: "result", result: "hi", subtype: "success" });
+    const parsed = parseClaudeCodeJsonOutput(stdout);
+    expect(parsed).toBeNull();
+  });
+});
+
+describe("storeClaudeCodeDetail", () => {
+  test("stores claude-code-detail CAS node and returns output + detailHash", async () => {
+    const store = createMemoryStore();
+    const parsed: ClaudeCodeParsedResult = {
+      type: "result",
+      subtype: "success",
+      result: "The answer",
+      sessionId: "abc-123",
+      numTurns: 5,
+      totalCostUsd: 0.12,
+      durationMs: 15000,
+    };
+
+    const { detailHash, output, sessionId } = await storeClaudeCodeDetail(store, parsed);
+    expect(detailHash).toHaveLength(13);
+    expect(output).toBe("The answer");
+    expect(sessionId).toBe("abc-123");
+
+    const node = await store.get(detailHash);
+    expect(node).not.toBeNull();
+    expect(node!.payload.sessionId).toBe("abc-123");
+    expect(node!.payload.numTurns).toBe(5);
+    expect(node!.payload.totalCostUsd).toBe(0.12);
+    expect(node!.payload.durationMs).toBe(15000);
+  });
+
+  test("detail node is walkable from root", async () => {
+    const store = createMemoryStore();
+    const parsed: ClaudeCodeParsedResult = {
+      type: "result",
+      subtype: "success",
+      result: "walkable test",
+      sessionId: "walk-123",
+      numTurns: 1,
+      totalCostUsd: 0.01,
+      durationMs: 1000,
+    };
+
+    const { detailHash } = await storeClaudeCodeDetail(store, parsed);
+    const visited: string[] = [];
+    walk(store, detailHash, (hash) => visited.push(hash));
+    expect(visited.length).toBeGreaterThan(0);
+  });
+});
+
+describe("storeClaudeCodeRawOutput", () => {
+  test("stores raw text when JSON parsing fails", async () => {
+    const store = createMemoryStore();
+    const rawText = "Claude produced plain text without JSON";
+    const hash = await storeClaudeCodeRawOutput(store, rawText);
+    expect(hash).toHaveLength(13);
+    const node = await store.get(hash);
+    expect(node).not.toBeNull();
+    expect(node!.payload.text).toBe(rawText);
+  });
+});

packages/workflow-agent-claude-code/package.json

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

packages/workflow-agent-claude-code/src/claude-code.ts

@@ -0,0 +1,148 @@
+import { spawn } from "node:child_process";
+import type { Store } from "@uncaged/json-cas";
+
+import {
+  type AgentContext,
+  type AgentRunResult,
+  buildRolePrompt,
+  createAgent,
+} from "@uncaged/workflow-agent-kit";
+
+import { parseClaudeCodeJsonOutput, storeClaudeCodeDetail } from "./session-detail.js";
+
+const CLAUDE_COMMAND = "claude";
+const CLAUDE_MAX_TURNS = 90;
+
+function buildHistorySummary(steps: AgentContext["steps"]): string {
+  if (steps.length === 0) {
+    return "";
+  }
+
+  const lines: string[] = ["## Previous Steps"];
+  for (let i = 0; i < steps.length; i++) {
+    const step = steps[i];
+    if (step === undefined) {
+      continue;
+    }
+    lines.push("");
+    lines.push(`### Step ${i + 1}: ${step.role}`);
+    lines.push(`Output: ${JSON.stringify(step.output)}`);
+    lines.push(`Agent: ${step.agent}`);
+  }
+  return lines.join("\n");
+}
+
+/** Assemble system prompt, task, and prior step outputs for Claude Code. */
+export function buildClaudeCodePrompt(ctx: AgentContext): string {
+  const roleDef = ctx.workflow.roles[ctx.role];
+  const rolePrompt = roleDef !== undefined ? buildRolePrompt(roleDef) : "";
+  const parts: string[] = [];
+  if (ctx.outputFormatInstruction !== undefined && ctx.outputFormatInstruction !== "") {
+    parts.push(ctx.outputFormatInstruction, "");
+  }
+  parts.push(rolePrompt, "", "## Task", ctx.start.prompt);
+  const historyBlock = buildHistorySummary(ctx.steps);
+  if (historyBlock !== "") {
+    parts.push("", historyBlock);
+  }
+  return parts.join("\n");
+}
+
+function spawnClaude(args: string[]): Promise<{ stdout: string; stderr: string }> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(CLAUDE_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(`claude spawn failed: ${message}`));
+    });
+
+    child.on("close", (code) => {
+      if (code === 0) {
+        resolve({ stdout, stderr });
+        return;
+      }
+      const detail = stderr.trim() !== "" ? ` stderr=${stderr.trim()}` : "";
+      reject(new Error(`claude exited with code ${code ?? "null"}${detail}`));
+    });
+  });
+}
+
+function spawnClaudeRun(prompt: string): Promise<{ stdout: string; stderr: string }> {
+  return spawnClaude([
+    "-p",
+    prompt,
+    "--output-format",
+    "json",
+    "--dangerously-skip-permissions",
+    "--max-turns",
+    String(CLAUDE_MAX_TURNS),
+  ]);
+}
+
+function spawnClaudeResume(
+  sessionId: string,
+  message: string,
+): Promise<{ stdout: string; stderr: string }> {
+  return spawnClaude([
+    "-p",
+    message,
+    "--resume",
+    sessionId,
+    "--output-format",
+    "json",
+    "--dangerously-skip-permissions",
+    "--max-turns",
+    String(CLAUDE_MAX_TURNS),
+  ]);
+}
+
+async function processClaudeOutput(stdout: string, store: Store): Promise<AgentRunResult> {
+  const parsed = parseClaudeCodeJsonOutput(stdout);
+
+  if (parsed !== null) {
+    const { detailHash, output, sessionId } = await storeClaudeCodeDetail(store, parsed);
+    return { output, detailHash, sessionId };
+  }
+
+  throw new Error(
+    `Claude Code returned non-JSON output (first 200 chars): ${stdout.slice(0, 200)}`,
+  );
+}
+
+async function runClaudeCode(ctx: AgentContext): Promise<AgentRunResult> {
+  const fullPrompt = buildClaudeCodePrompt(ctx);
+  const { stdout } = await spawnClaudeRun(fullPrompt);
+  return processClaudeOutput(stdout, ctx.store);
+}
+
+async function continueClaudeCode(
+  sessionId: string,
+  message: string,
+  store: Store,
+): Promise<AgentRunResult> {
+  const { stdout } = await spawnClaudeResume(sessionId, message);
+  return processClaudeOutput(stdout, store);
+}
+
+/** Agent CLI factory: parses argv, runs Claude Code, extracts output, writes StepNode. */
+export function createClaudeCodeAgent(): () => Promise<void> {
+  return createAgent({
+    name: "claude-code",
+    run: runClaudeCode,
+    continue: continueClaudeCode,
+  });
+}

packages/workflow-agent-claude-code/src/cli.ts

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

packages/workflow-agent-claude-code/src/index.ts

@@ -0,0 +1,6 @@
+export { buildClaudeCodePrompt, createClaudeCodeAgent } from "./claude-code.js";
+export {
+  parseClaudeCodeJsonOutput,
+  storeClaudeCodeDetail,
+  storeClaudeCodeRawOutput,
+} from "./session-detail.js";

packages/workflow-agent-claude-code/src/schemas.ts

@@ -0,0 +1,25 @@
+import type { JSONSchema } from "@uncaged/json-cas";
+
+export const CLAUDE_CODE_DETAIL_SCHEMA: JSONSchema = {
+  title: "claude-code-detail",
+  type: "object",
+  required: ["sessionId", "numTurns", "totalCostUsd", "durationMs", "subtype"],
+  properties: {
+    sessionId: { type: "string" },
+    numTurns: { type: "integer" },
+    totalCostUsd: { type: "number" },
+    durationMs: { type: "integer" },
+    subtype: { type: "string" },
+  },
+  additionalProperties: false,
+};
+
+export const CLAUDE_CODE_RAW_OUTPUT_SCHEMA: JSONSchema = {
+  title: "claude-code-raw-output",
+  type: "object",
+  required: ["text"],
+  properties: {
+    text: { type: "string" },
+  },
+  additionalProperties: false,
+};

packages/workflow-agent-claude-code/src/session-detail.ts

@@ -0,0 +1,79 @@
+import { bootstrap, putSchema, type Store } from "@uncaged/json-cas";
+
+import { CLAUDE_CODE_DETAIL_SCHEMA, CLAUDE_CODE_RAW_OUTPUT_SCHEMA } from "./schemas.js";
+import type { ClaudeCodeDetailPayload, ClaudeCodeParsedResult } from "./types.js";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Parse Claude Code JSON stdout (`claude -p --output-format json`). */
+export function parseClaudeCodeJsonOutput(stdout: string): ClaudeCodeParsedResult | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(stdout.trim());
+  } catch {
+    return null;
+  }
+
+  if (!isRecord(parsed)) {
+    return null;
+  }
+
+  const sessionId = parsed.session_id;
+  const result = parsed.result;
+  const subtype = parsed.subtype;
+
+  if (typeof sessionId !== "string" || typeof result !== "string" || typeof subtype !== "string") {
+    return null;
+  }
+
+  return {
+    type: typeof parsed.type === "string" ? parsed.type : "result",
+    subtype: subtype as ClaudeCodeParsedResult["subtype"],
+    result,
+    sessionId,
+    numTurns: typeof parsed.num_turns === "number" ? parsed.num_turns : 0,
+    totalCostUsd: typeof parsed.total_cost_usd === "number" ? parsed.total_cost_usd : 0,
+    durationMs: typeof parsed.duration_ms === "number" ? parsed.duration_ms : 0,
+  };
+}
+
+type ClaudeCodeSchemaHashes = {
+  detail: string;
+  rawOutput: string;
+};
+
+async function registerSchemas(store: Store): Promise<ClaudeCodeSchemaHashes> {
+  await bootstrap(store);
+  const [detail, rawOutput] = await Promise.all([
+    putSchema(store, CLAUDE_CODE_DETAIL_SCHEMA),
+    putSchema(store, CLAUDE_CODE_RAW_OUTPUT_SCHEMA),
+  ]);
+  return { detail, rawOutput };
+}
+
+/** Store parsed Claude Code result as a CAS detail node. */
+export async function storeClaudeCodeDetail(
+  store: Store,
+  parsed: ClaudeCodeParsedResult,
+): Promise<{ detailHash: string; output: string; sessionId: string }> {
+  const schemas = await registerSchemas(store);
+
+  const detail: ClaudeCodeDetailPayload = {
+    sessionId: parsed.sessionId,
+    numTurns: parsed.numTurns,
+    totalCostUsd: parsed.totalCostUsd,
+    durationMs: parsed.durationMs,
+    subtype: parsed.subtype,
+  };
+
+  const detailHash = await store.put(schemas.detail, detail);
+  return { detailHash, output: parsed.result, sessionId: parsed.sessionId };
+}
+
+/** Fallback: store raw text output when JSON parsing fails. */
+export async function storeClaudeCodeRawOutput(store: Store, rawOutput: string): Promise<string> {
+  const schemas = await registerSchemas(store);
+  return store.put(schemas.rawOutput, { text: rawOutput });
+}

packages/workflow-agent-claude-code/src/types.ts

@@ -0,0 +1,19 @@
+export type ClaudeCodeResultSubtype = "success" | "error_max_turns" | "error_budget";
+
+export type ClaudeCodeParsedResult = {
+  type: string;
+  subtype: ClaudeCodeResultSubtype;
+  result: string;
+  sessionId: string;
+  numTurns: number;
+  totalCostUsd: number;
+  durationMs: number;
+};
+
+export type ClaudeCodeDetailPayload = {
+  sessionId: string;
+  numTurns: number;
+  totalCostUsd: number;
+  durationMs: number;
+  subtype: string;
+};

packages/workflow-agent-claude-code/tsconfig.json

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

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

@@ -0,0 +1,77 @@
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+
+import { HermesAcpClient } from "../src/acp-client.js";
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+describe("HermesAcpClient", () => {
+  let client: HermesAcpClient;
+
+  beforeEach(() => {
+    client = new HermesAcpClient();
+  });
+
+  afterEach(async () => {
+    await client.close();
+  });
+
+  it(
+    "connect() returns a UUID sessionId",
+    async () => {
+      const sessionId = await client.connect(process.cwd());
+      expect(typeof sessionId).toBe("string");
+      expect(sessionId).toMatch(UUID_RE);
+    },
+    { timeout: 2 * 60 * 1000 },
+  );
+
+  it(
+    "prompt() returns a non-empty text response",
+    async () => {
+      await client.connect(process.cwd());
+      const result = await client.prompt("Reply with exactly the word: PONG");
+      expect(typeof result.text).toBe("string");
+      expect(result.text.length).toBeGreaterThan(0);
+      expect(typeof result.sessionId).toBe("string");
+      expect(result.sessionId).toMatch(UUID_RE);
+    },
+    { timeout: 2 * 60 * 1000 },
+  );
+
+  it(
+    "prompt() can be called twice on the same session (resume)",
+    async () => {
+      await client.connect(process.cwd());
+
+      const first = await client.prompt("Say the word ALPHA and nothing else.");
+      expect(first.text.length).toBeGreaterThan(0);
+
+      const second = await client.prompt("Now say the word BETA and nothing else.");
+      expect(second.text.length).toBeGreaterThan(0);
+
+      expect(first.sessionId).toBe(second.sessionId);
+    },
+    { timeout: 2 * 60 * 1000 },
+  );
+
+  it(
+    "prompt() collects structured messages including tool calls",
+    async () => {
+      await client.connect(process.cwd());
+      const result = await client.prompt("Run this command: echo TOOL_DETAIL_TEST");
+      expect(result.messages.length).toBeGreaterThan(0);
+      // Should have at least one tool message (the echo command)
+      const toolMessages = result.messages.filter((m) => m.role === "tool");
+      expect(toolMessages.length).toBeGreaterThan(0);
+      // Tool message should contain the output
+      const toolContent = toolMessages[0]?.content ?? "";
+      expect(toolContent).toContain("TOOL_DETAIL_TEST");
+      // Should have assistant messages with tool_calls
+      const assistantWithTools = result.messages.filter(
+        (m) => m.role === "assistant" && m.tool_calls !== null,
+      );
+      expect(assistantWithTools.length).toBeGreaterThan(0);
+    },
+    { timeout: 2 * 60 * 1000 },
+  );
+});

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

@@ -0,0 +1,78 @@
+import { describe, expect, test } from "bun:test";
+import type { AgentContext } from "@uncaged/workflow-agent-kit";
+import type { ThreadId } from "@uncaged/workflow-protocol";
+import { buildHermesPrompt } from "../src/hermes.js";
+
+function makeCtx(overrides: Partial<AgentContext> = {}): AgentContext {
+  return {
+    threadId: "01JTEST0000000000000000000" as ThreadId,
+    edgePrompt: "Proceed with the assigned role.",
+    isFirstVisit: true,
+    workflow: {
+      roles: {
+        developer: {
+          description: "TDD implementation per test spec",
+          goal: "Write code",
+          capabilities: ["coding"],
+          procedure: "1. Read spec\n2. Write code",
+          output: "List files changed",
+          frontmatter: "",
+        },
+      },
+      conditions: {},
+      graph: {},
+    },
+    role: "developer",
+    start: { prompt: "Fix the bug", workflowHash: "abc123", threadId: "t1" },
+    steps: [],
+    store: {} as AgentContext["store"],
+    outputFormatInstruction: "Use YAML frontmatter",
+    ...overrides,
+  };
+}
+
+describe("buildHermesPrompt", () => {
+  test("first visit uses full role prompt and includes moderator instruction", () => {
+    const result = buildHermesPrompt(
+      makeCtx({ edgePrompt: "Focus on the failing test.", isFirstVisit: true }),
+    );
+
+    expect(result).toMatch(/^Use YAML frontmatter/);
+    expect(result).toContain("Write code");
+    expect(result).toContain("## Task\nFix the bug");
+    expect(result).toContain("## Moderator Instruction");
+    expect(result).toContain("Focus on the failing test.");
+  });
+
+  test("re-entry uses continuation prompt with edge instruction", () => {
+    const ctx = makeCtx({
+      isFirstVisit: false,
+      edgePrompt: "The reviewer rejected your work. Fix the issues.",
+      steps: [
+        { role: "developer", output: { summary: "Initial fix" }, agent: "uwf-hermes" },
+        { role: "reviewer", output: { approved: false }, agent: "uwf-hermes" },
+      ],
+    });
+
+    const result = buildHermesPrompt(ctx);
+
+    expect(result).not.toContain("## Task");
+    expect(result).toContain("## What Happened Since Your Last Turn");
+    expect(result).toContain("## Moderator Instruction");
+    expect(result).toContain("The reviewer rejected your work.");
+  });
+
+  test("forced first visit via isFirstVisit uses initial prompt even when role appears in history", () => {
+    const result = buildHermesPrompt(
+      makeCtx({
+        isFirstVisit: true,
+        steps: [{ role: "developer", output: { done: true }, agent: "uwf-hermes" }],
+        edgePrompt: "Retry with a fresh approach.",
+      }),
+    );
+
+    expect(result).toContain("## Task");
+    expect(result).toContain("Retry with a fresh approach.");
+    expect(result).not.toContain("## What Happened Since Your Last Turn");
+  });
+});

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

@@ -0,0 +1,56 @@
+import { afterEach, describe, expect, it } from "bun:test";
+
+import { HermesAcpClient } from "../src/acp-client.js";
+
+/**
+ * E2E test for cross-process session resume.
+ *
+ * Simulates the workflow re-entry scenario:
+ * 1. Client A: connect → prompt → close (developer first run)
+ * 2. Client B: resume(sessionId) → prompt (developer re-entry after reviewer reject)
+ *
+ * This is what happens when uwf thread step spawns uwf-hermes twice for the same role.
+ */
+describe("HermesAcpClient cross-process resume", () => {
+  const clients: HermesAcpClient[] = [];
+
+  afterEach(async () => {
+    for (const c of clients) {
+      await c.close();
+    }
+    clients.length = 0;
+  });
+
+  it(
+    "resume() after close — second prompt returns non-empty text",
+    async () => {
+      // --- Client A: first run ---
+      const clientA = new HermesAcpClient();
+      clients.push(clientA);
+
+      await clientA.connect(process.cwd());
+      const first = await clientA.prompt(
+        "Remember the secret code: WATERMELON. Reply with exactly: ACKNOWLEDGED",
+      );
+      expect(first.text.length).toBeGreaterThan(0);
+      const sessionId = first.sessionId;
+
+      // Close client A (simulates uwf-hermes process exit)
+      await clientA.close();
+
+      // --- Client B: resume (simulates re-entry) ---
+      const clientB = new HermesAcpClient();
+      clients.push(clientB);
+
+      await clientB.resume(sessionId, process.cwd());
+      const second = await clientB.prompt(
+        "What was the secret code I told you earlier? Reply with just the code word.",
+      );
+
+      // The critical assertion: resumed session produces non-empty output
+      expect(second.text.length).toBeGreaterThan(0);
+      expect(second.sessionId).toBe(sessionId);
+    },
+    { timeout: 3 * 60 * 1000 },
+  );
+});

packages/workflow-agent-hermes/package.json

@@ -22,7 +22,9 @@
   },
   "dependencies": {
     "@uncaged/json-cas": "^0.4.0",
-    "@uncaged/workflow-agent-kit": "workspace:^"
+    "@uncaged/workflow-agent-kit": "workspace:^",
+    "@uncaged/workflow-protocol": "workspace:^",
+    "@uncaged/workflow-util": "workspace:^"
   },
   "devDependencies": {
     "typescript": "^5.8.3"

packages/workflow-agent-hermes/src/acp-client.ts

@@ -0,0 +1,393 @@
+import type { ChildProcess } from "node:child_process";
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+
+import type { HermesSessionMessage } from "./types.js";
+
+const HERMES_COMMAND = "hermes";
+const PROTOCOL_VERSION = 1;
+
+type JsonRpcResponse = {
+  jsonrpc: "2.0";
+  id: number;
+  result?: unknown;
+  error?: { code: number; message: string };
+};
+
+type PendingRequest = {
+  resolve: (value: JsonRpcResponse) => void;
+  reject: (reason: Error) => void;
+};
+
+/** Tracks in-flight tool calls so we can build complete messages when they finish. */
+type PendingToolCall = {
+  name: string;
+  args: string;
+};
+
+export type AcpPromptResult = {
+  text: string;
+  sessionId: string;
+  messages: HermesSessionMessage[];
+};
+
+export class HermesAcpClient {
+  private process: ChildProcess | null = null;
+  private nextId = 1;
+  private sessionId: string | null = null;
+  private stderrBuffer = "";
+  private pending = new Map<number, PendingRequest>();
+
+  // Message collection state
+  private messageChunks: string[] = [];
+  private reasoningChunks: string[] = [];
+  private pendingTools = new Map<string, PendingToolCall>();
+  messages: HermesSessionMessage[] = [];
+
+  /** Spawn hermes acp, initialize, create session */
+  async connect(cwd: string): Promise<string> {
+    await this.ensureProcess();
+    await this.initialize();
+
+    const sessionResponse = (await this.sendRequest("session/new", {
+      cwd,
+      mcpServers: [],
+    })) as { result: { sessionId: string } };
+
+    const sessionId = sessionResponse.result?.sessionId;
+    if (typeof sessionId !== "string" || sessionId === "") {
+      throw new Error(`session/new did not return a sessionId: ${JSON.stringify(sessionResponse)}`);
+    }
+
+    this.sessionId = sessionId;
+    return sessionId;
+  }
+
+  /** Spawn hermes acp, initialize, resume an existing session */
+  async resume(sessionId: string, cwd: string): Promise<string> {
+    await this.ensureProcess();
+    await this.initialize();
+
+    const response = await this.sendRequest("session/resume", {
+      cwd,
+      sessionId,
+      mcpServers: [],
+    });
+
+    if ((response as { error?: unknown }).error !== undefined) {
+      throw new Error(
+        `session/resume failed: ${JSON.stringify((response as { error: unknown }).error)}`,
+      );
+    }
+
+    this.sessionId = sessionId;
+    return sessionId;
+  }
+
+  /** Send prompt and collect full response text + structured messages. */
+  async prompt(text: string): Promise<AcpPromptResult> {
+    if (this.sessionId === null) {
+      throw new Error("Not connected — call connect() first");
+    }
+
+    this.messageChunks = [];
+    this.reasoningChunks = [];
+
+    const response = await this.sendRequest("session/prompt", {
+      sessionId: this.sessionId,
+      prompt: [{ type: "text", text }],
+    });
+
+    if ((response as { error?: unknown }).error !== undefined) {
+      throw new Error(
+        `session/prompt failed: ${JSON.stringify((response as { error: unknown }).error)}`,
+      );
+    }
+
+    // Flush any trailing assistant text that wasn't followed by a tool call.
+    this.flushAssistantMessage();
+
+    // Extract the final assistant text from collected messages.
+    let finalText = "";
+    for (let i = this.messages.length - 1; i >= 0; i--) {
+      const msg = this.messages[i];
+      if (
+        msg !== undefined &&
+        msg.role === "assistant" &&
+        msg.content !== null &&
+        msg.content.trim() !== ""
+      ) {
+        finalText = msg.content;
+        break;
+      }
+    }
+
+    return {
+      text: finalText,
+      sessionId: this.sessionId,
+      messages: this.messages,
+    };
+  }
+
+  /** Close the connection */
+  async close(): Promise<void> {
+    if (this.process === null) {
+      return;
+    }
+    this.sessionId = null;
+    this.process.stdin?.end();
+    const proc = this.process;
+    await new Promise<void>((resolve) => {
+      proc.on("close", () => resolve());
+      setTimeout(resolve, 5000);
+    });
+    this.process = null;
+  }
+
+  // ---- JSON-RPC transport ----
+
+  private sendRequest(
+    method: string,
+    params: Record<string, unknown>,
+    timeoutMs = 10 * 60 * 1000,
+  ): Promise<JsonRpcResponse> {
+    const id = this.nextId++;
+    return new Promise<JsonRpcResponse>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error(`Timeout waiting for response to ${method} (id=${id})`));
+      }, timeoutMs);
+
+      this.pending.set(id, {
+        resolve: (value) => {
+          clearTimeout(timer);
+          resolve(value);
+        },
+        reject: (err) => {
+          clearTimeout(timer);
+          reject(err);
+        },
+      });
+
+      this.writeLine(JSON.stringify({ jsonrpc: "2.0", id, method, params }));
+    });
+  }
+
+  private sendNotification(method: string, params?: Record<string, unknown>): void {
+    const message: Record<string, unknown> = { jsonrpc: "2.0", method };
+    if (params !== undefined) {
+      message.params = params;
+    }
+    this.writeLine(JSON.stringify(message));
+  }
+
+  private writeLine(line: string): void {
+    if (this.process?.stdin === null || this.process?.stdin === undefined) {
+      throw new Error("Cannot write: hermes acp process stdin not available");
+    }
+    this.process.stdin.write(`${line}\n`);
+  }
+
+  private handleLine(line: string): void {
+    if (line === "") {
+      return;
+    }
+
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(line);
+    } catch {
+      return;
+    }
+
+    const msg = parsed as Record<string, unknown>;
+
+    const hasId = "id" in msg && msg.id !== undefined && msg.id !== null;
+    const hasMethod = typeof msg.method === "string";
+
+    // JSON-RPC response to one of our requests (has "id" but no "method")
+    if (hasId && !hasMethod) {
+      const response = msg as unknown as JsonRpcResponse;
+      const handler = this.pending.get(response.id);
+      if (handler !== undefined) {
+        this.pending.delete(response.id);
+        handler.resolve(response);
+      }
+      return;
+    }
+
+    // Server-initiated JSON-RPC request: session/request_permission (has "id" + "method")
+    if (msg.method === "session/request_permission" && hasId) {
+      const params = msg.params as Record<string, unknown> | undefined;
+      const options = (params?.options ?? []) as Array<{ optionId?: string }>;
+      const firstOptionId = options[0]?.optionId ?? "";
+      this.writeLine(
+        JSON.stringify({
+          jsonrpc: "2.0",
+          id: msg.id,
+          result: { outcome: { outcome: "selected", optionId: firstOptionId } },
+        }),
+      );
+      return;
+    }
+
+    // JSON-RPC notification — session/update (no "id")
+    if (msg.method === "session/update") {
+      const params = msg.params as Record<string, unknown> | undefined;
+      const update = params?.update as Record<string, unknown> | undefined;
+      if (update !== undefined) {
+        this.handleSessionUpdate(update);
+      }
+      return;
+    }
+  }
+
+  // ---- Session update → structured messages ----
+
+  private handleSessionUpdate(update: Record<string, unknown>): void {
+    const updateType = update.sessionUpdate as string;
+
+    switch (updateType) {
+      case "agent_message_chunk": {
+        const content = update.content as { type?: string; text?: string } | undefined;
+        if (content?.type === "text" && typeof content.text === "string") {
+          this.messageChunks.push(content.text);
+        }
+        break;
+      }
+
+      case "agent_thought_chunk": {
+        const content = update.content as { type?: string; text?: string } | undefined;
+        if (content?.type === "text" && typeof content.text === "string") {
+          this.reasoningChunks.push(content.text);
+        }
+        break;
+      }
+
+      case "tool_call": {
+        const title = (update.title as string) ?? "";
+        const rawInput = update.rawInput;
+        const args =
+          rawInput !== undefined && rawInput !== null ? JSON.stringify(rawInput) : "";
+        const toolCallId = update.toolCallId as string;
+        this.pendingTools.set(toolCallId, { name: title, args });
+
+        // Flush accumulated assistant text before tool call
+        this.flushAssistantMessage();
+        break;
+      }
+
+      case "tool_call_update": {
+        const status = update.status as string | undefined;
+        if (status === "completed" || status === "failed") {
+          const toolCallId = update.toolCallId as string;
+          const pending = this.pendingTools.get(toolCallId);
+          const toolName = pending?.name ?? toolCallId;
+          const rawOutput = update.rawOutput;
+          const outputStr =
+            rawOutput !== undefined && rawOutput !== null
+              ? typeof rawOutput === "string"
+                ? rawOutput
+                : JSON.stringify(rawOutput)
+              : "";
+          this.messages.push({
+            role: "assistant",
+            content: null,
+            reasoning: null,
+            tool_calls: [{ function: { name: toolName, arguments: pending?.args ?? "" } }],
+          });
+          this.messages.push({
+            role: "tool",
+            content: outputStr,
+            reasoning: null,
+            tool_calls: null,
+          });
+          this.pendingTools.delete(toolCallId);
+        }
+        break;
+      }
+
+      default:
+        break;
+    }
+  }
+
+  /** Flush any accumulated text/reasoning into an assistant message. */
+  private flushAssistantMessage(): void {
+    const text = this.messageChunks.join("");
+    const reasoning = this.reasoningChunks.join("");
+    if (text !== "" || reasoning !== "") {
+      this.messages.push({
+        role: "assistant",
+        content: text || null,
+        reasoning: reasoning || null,
+        tool_calls: null,
+      });
+    }
+    this.messageChunks = [];
+    this.reasoningChunks = [];
+  }
+
+  private rejectAll(err: Error): void {
+    for (const handler of this.pending.values()) {
+      handler.reject(err);
+    }
+    this.pending.clear();
+  }
+
+  private async ensureProcess(): Promise<void> {
+    if (this.process !== null) {
+      return;
+    }
+
+    const child = spawn(HERMES_COMMAND, ["acp"], {
+      env: process.env,
+      shell: false,
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+
+    this.process = child;
+
+    child.stderr?.on("data", (chunk: Buffer) => {
+      this.stderrBuffer += chunk.toString();
+    });
+
+    child.on("error", (cause) => {
+      const message = cause instanceof Error ? cause.message : String(cause);
+      this.rejectAll(new Error(`hermes acp spawn failed: ${message}`));
+    });
+
+    child.on("close", (code) => {
+      if (code !== 0 && this.pending.size > 0) {
+        const detail = this.stderrBuffer.trim() !== "" ? ` stderr=${this.stderrBuffer.trim()}` : "";
+        this.rejectAll(
+          new Error(`hermes acp exited unexpectedly with code ${code ?? "null"}${detail}`),
+        );
+      }
+    });
+
+    if (child.stdout === null) {
+      throw new Error("hermes acp process stdout is not available");
+    }
+    const rl = createInterface({ input: child.stdout });
+    rl.on("line", (line) => {
+      this.handleLine(line.trim());
+    });
+  }
+
+  private async initialize(): Promise<void> {
+    const initResponse = await this.sendRequest("initialize", {
+      protocolVersion: PROTOCOL_VERSION,
+      clientInfo: { name: "uwf", version: "0.1.0" },
+      capabilities: {},
+    });
+
+    if ((initResponse as { error?: unknown }).error !== undefined) {
+      throw new Error(
+        `initialize failed: ${JSON.stringify((initResponse as { error: unknown }).error)}`,
+      );
+    }
+
+    this.sendNotification("initialized");
+  }
+}

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

@@ -1,16 +1,18 @@
-import { spawn } from "node:child_process";
-
-import { type AgentContext, type AgentRunResult, buildRolePrompt, createAgent } from "@uncaged/workflow-agent-kit";
-
+import type { Store } from "@uncaged/json-cas";
 import {
-  loadHermesSession,
-  parseSessionIdFromStdout,
-  storeHermesRawOutput,
-  storeHermesSessionDetail,
-} from "./session-detail.js";
+  type AgentContext,
+  type AgentRunResult,
+  buildContinuationPrompt,
+  buildRolePrompt,
+  createAgent,
+} from "@uncaged/workflow-agent-kit";
+import { createLogger } from "@uncaged/workflow-util";
 
-const HERMES_COMMAND = "hermes";
-const HERMES_MAX_TURNS = 90;
+import { HermesAcpClient } from "./acp-client.js";
+import { getCachedSessionId, isResumeDisabled, setCachedSessionId } from "./session-cache.js";
+import { storeHermesSessionDetail } from "./session-detail.js";
+
+const log = createLogger({ sink: { kind: "stderr" } });
 
 function buildHistorySummary(steps: AgentContext["steps"]): string {
   if (steps.length === 0) {
@@ -31,12 +33,11 @@ function buildHistorySummary(steps: AgentContext["steps"]): string {
   return lines.join("\n");
 }
 
-/** Assemble system prompt, task, and prior step outputs for Hermes. */
-export function buildHermesPrompt(ctx: AgentContext): string {
+function buildInitialPrompt(ctx: AgentContext): string {
   const roleDef = ctx.workflow.roles[ctx.role];
   const rolePrompt = roleDef !== undefined ? buildRolePrompt(roleDef) : "";
   const parts: string[] = [];
-  if (ctx.outputFormatInstruction !== undefined && ctx.outputFormatInstruction !== "") {
+  if (ctx.outputFormatInstruction !== "") {
     parts.push(ctx.outputFormatInstruction, "");
   }
   parts.push(rolePrompt, "", "## Task", ctx.start.prompt);
@@ -44,74 +45,145 @@ export function buildHermesPrompt(ctx: AgentContext): string {
   if (historyBlock !== "") {
     parts.push("", historyBlock);
   }
+  parts.push("", "## Moderator Instruction", "", ctx.edgePrompt);
   return parts.join("\n");
 }
 
-function spawnHermesChat(prompt: string): Promise<{ stdout: string; stderr: string }> {
-  return new Promise((resolve, reject) => {
-    const args = [
-      "chat",
-      "-q",
-      prompt,
-      "--yolo",
-      "--max-turns",
-      String(HERMES_MAX_TURNS),
-      "--quiet",
-    ];
-    const child = spawn(HERMES_COMMAND, args, {
-      env: process.env,
-      shell: false,
-      stdio: ["ignore", "pipe", "pipe"],
-    });
+/** Assemble system prompt, task, and prior step outputs for Hermes. */
+export function buildHermesPrompt(ctx: AgentContext): string {
+  if (!ctx.isFirstVisit) {
+    const parts: string[] = [];
+    if (ctx.outputFormatInstruction !== "") {
+      parts.push(ctx.outputFormatInstruction, "");
+    }
+    parts.push(buildContinuationPrompt(ctx.steps, ctx.role, ctx.edgePrompt));
+    return parts.join("\n");
+  }
 
-    let stdout = "";
-    let stderr = "";
-    child.stdout?.on("data", (chunk: Buffer) => {
-      stdout += chunk.toString();
-    });
-    child.stderr?.on("data", (chunk: Buffer) => {
-      stderr += chunk.toString();
-    });
-
-    child.on("error", (cause) => {
-      const message = cause instanceof Error ? cause.message : String(cause);
-      reject(new Error(`hermes spawn failed: ${message}`));
-    });
-
-    child.on("close", (code) => {
-      if (code === 0) {
-        resolve({ stdout, stderr });
-        return;
-      }
-      const detail = stderr.trim() !== "" ? ` stderr=${stderr.trim()}` : "";
-      reject(new Error(`hermes exited with code ${code ?? "null"}${detail}`));
-    });
-  });
+  return buildInitialPrompt(ctx);
 }
 
-async function runHermes(ctx: AgentContext): Promise<AgentRunResult> {
-  const fullPrompt = buildHermesPrompt(ctx);
-  const { stdout, stderr } = await spawnHermesChat(fullPrompt);
-  const { store } = ctx;
+async function storePromptResult(
+  store: Store,
+  sessionId: string,
+  messages: Awaited<ReturnType<HermesAcpClient["prompt"]>>["messages"],
+): Promise<{ detailHash: string }> {
+  const session = {
+    session_id: sessionId,
+    model: "",
+    session_start: new Date().toISOString(),
+    messages,
+  };
+  return storeHermesSessionDetail(store, session);
+}
 
-  // --quiet mode: session_id may be on stdout or stderr
-  const sessionId = parseSessionIdFromStdout(stderr) ?? parseSessionIdFromStdout(stdout);
-  if (sessionId !== null) {
-    const session = await loadHermesSession(sessionId);
-    if (session !== null) {
-      const { detailHash, output } = await storeHermesSessionDetail(store, session);
-      return { output, detailHash };
+type PromptAttempt = {
+  useContinuation: boolean;
+  resumed: boolean;
+};
+
+async function prepareSession(
+  client: HermesAcpClient,
+  ctx: AgentContext,
+  cwd: string,
+): Promise<PromptAttempt> {
+  if (ctx.isFirstVisit || isResumeDisabled()) {
+    await client.connect(cwd);
+    return { useContinuation: false, resumed: false };
+  }
+
+  const cachedSessionId = await getCachedSessionId(ctx.threadId, ctx.role);
+  if (cachedSessionId === null) {
+    log("6RWK3N8Q", `no cached session for ${ctx.threadId}:${ctx.role}, starting new session`);
+    await client.connect(cwd);
+    return { useContinuation: false, resumed: false };
+  }
+
+  try {
+    await client.resume(cachedSessionId, cwd);
+    log("9MHT4V2P", `resumed hermes session ${cachedSessionId} for ${ctx.threadId}:${ctx.role}`);
+    return { useContinuation: true, resumed: true };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    log("3XPN7K4W", `session resume failed, falling back to new session: ${message}`);
+    await client.close();
+    await client.connect(cwd);
+    return { useContinuation: false, resumed: false };
+  }
+}
+
+/**
+ * Agent CLI factory: parses argv, runs Hermes, extracts output, writes StepNode.
+ *
+ * A single ACP client is shared across run() and continue() calls so that
+ * frontmatter retry loops keep the same Hermes session context.  The client
+ * is closed once the agent process exits (via process.on("exit")).
+ */
+export function createHermesAgent(): () => Promise<void> {
+  const client = new HermesAcpClient();
+
+  // Ensure cleanup regardless of how the process exits.
+  process.on("exit", () => {
+    void client.close();
+  });
+
+  async function runPrompt(ctx: AgentContext, useContinuation: boolean): Promise<AgentRunResult> {
+    const effectiveCtx = useContinuation ? ctx : { ...ctx, isFirstVisit: true };
+    const fullPrompt = buildHermesPrompt(effectiveCtx);
+    const { text, sessionId, messages } = await client.prompt(fullPrompt);
+    const { detailHash } = await storePromptResult(ctx.store, sessionId, messages);
+
+    if (!isResumeDisabled()) {
+      await setCachedSessionId(ctx.threadId, ctx.role, sessionId);
+    }
+
+    return { output: text, detailHash, sessionId };
+  }
+
+  async function runHermes(ctx: AgentContext): Promise<AgentRunResult> {
+    const cwd = process.cwd();
+    const attempt = await prepareSession(client, ctx, cwd);
+
+    try {
+      return await runPrompt(ctx, attempt.useContinuation);
+    } catch (error) {
+      if (!attempt.resumed) {
+        throw error;
+      }
+
+      const message = error instanceof Error ? error.message : String(error);
+      log("8FQW2R6N", `continuation prompt failed, retrying with initial prompt: ${message}`);
+      await client.close();
+      await client.connect(cwd);
+      return runPrompt(ctx, false);
     }
   }
 
-  const detailHash = await storeHermesRawOutput(store, stdout);
-  return { output: stdout, detailHash };
-}
+  async function continueHermes(
+    _sessionId: string,
+    message: string,
+    store: Store,
+  ): Promise<AgentRunResult> {
+    // Client is already connected from runHermes — same ACP session,
+    // so the agent sees the full conversation history (crucial for retries).
+    const { text, sessionId, messages } = await client.prompt(message);
+    const { detailHash } = await storePromptResult(store, sessionId, messages);
+    return { output: text, detailHash, sessionId };
+  }
 
-/** Agent CLI factory: parses argv, runs Hermes, extracts output, writes StepNode. */
-export function createHermesAgent(): () => Promise<void> {
-  return createAgent({
+  const agentMain = createAgent({
     name: "hermes",
     run: runHermes,
+    continue: continueHermes,
   });
+
+  // Wrap to ensure ACP client is closed after agent completes,
+  // so the hermes subprocess exits and bun can terminate.
+  return async () => {
+    try {
+      await agentMain();
+    } finally {
+      await client.close();
+    }
+  };
 }

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

@@ -1 +1,2 @@
+export { HermesAcpClient } from "./acp-client.js";
 export { buildHermesPrompt, createHermesAgent } from "./hermes.js";

packages/workflow-agent-hermes/src/session-cache.ts

@@ -0,0 +1,70 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+
+import { resolveStorageRoot } from "@uncaged/workflow-agent-kit";
+import type { ThreadId } from "@uncaged/workflow-protocol";
+
+type HermesSessionCache = Record<string, string>;
+
+function getCachePath(): string {
+  return join(resolveStorageRoot(), "cache", "hermes-sessions.json");
+}
+
+function cacheKey(threadId: ThreadId, role: string): string {
+  return `${threadId}:${role}`;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+async function readCache(): Promise<HermesSessionCache> {
+  const path = getCachePath();
+  try {
+    const text = await readFile(path, "utf8");
+    const raw = JSON.parse(text) as unknown;
+    if (!isRecord(raw)) {
+      return {};
+    }
+    const cache: HermesSessionCache = {};
+    for (const [key, value] of Object.entries(raw)) {
+      if (typeof value === "string" && value !== "") {
+        cache[key] = value;
+      }
+    }
+    return cache;
+  } catch (e) {
+    const err = e as NodeJS.ErrnoException;
+    if (err.code === "ENOENT") {
+      return {};
+    }
+    throw e;
+  }
+}
+
+async function writeCache(cache: HermesSessionCache): Promise<void> {
+  const path = getCachePath();
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, `${JSON.stringify(cache, null, 2)}\n`, "utf8");
+}
+
+export function isResumeDisabled(): boolean {
+  const flag = process.env.UWF_NO_RESUME;
+  return flag !== undefined && flag !== "";
+}
+
+export async function getCachedSessionId(threadId: ThreadId, role: string): Promise<string | null> {
+  const cache = await readCache();
+  const sessionId = cache[cacheKey(threadId, role)];
+  return sessionId ?? null;
+}
+
+export async function setCachedSessionId(
+  threadId: ThreadId,
+  role: string,
+  sessionId: string,
+): Promise<void> {
+  const cache = await readCache();
+  cache[cacheKey(threadId, role)] = sessionId;
+  await writeCache(cache);
+}

packages/workflow-agent-kit/__tests__/build-continuation-prompt.test.ts

@@ -0,0 +1,70 @@
+import type { StepContext } from "@uncaged/workflow-protocol";
+import { describe, expect, test } from "vitest";
+import { buildContinuationPrompt } from "../src/build-continuation-prompt.js";
+
+const reviewerStep: StepContext = {
+  role: "reviewer",
+  output: { approved: false, comments: "Missing tests" },
+  detail: "2MXBG6PN4A8JR",
+  agent: "uwf-hermes",
+};
+
+const developerStep: StepContext = {
+  role: "developer",
+  output: { filesChanged: ["src/app.ts"], summary: "Initial fix" },
+  detail: "1VPBG9SM5E7WK",
+  agent: "uwf-hermes",
+};
+
+describe("buildContinuationPrompt", () => {
+  test("includes steps after the last matching role and the edge prompt", () => {
+    const steps: StepContext[] = [
+      developerStep,
+      reviewerStep,
+      {
+        role: "planner",
+        output: { plan: "revise approach" },
+        detail: "7BQST3VW9F2MA",
+        agent: "uwf-hermes",
+      },
+    ];
+
+    const result = buildContinuationPrompt(
+      steps,
+      "developer",
+      "The reviewer rejected your implementation. Read their feedback and fix the issues.",
+    );
+
+    expect(result).toContain("## What Happened Since Your Last Turn");
+    expect(result).toContain("### Step 2: reviewer");
+    expect(result).toContain("Missing tests");
+    expect(result).toContain("### Step 3: planner");
+    expect(result).toContain("## Moderator Instruction");
+    expect(result).toContain("The reviewer rejected your implementation.");
+    expect(result).not.toContain("Initial fix");
+  });
+
+  test("uses all steps when the role has not run before", () => {
+    const result = buildContinuationPrompt(
+      [developerStep, reviewerStep],
+      "planner",
+      "Continue from the reviewer feedback.",
+    );
+
+    expect(result).toContain("### Step 1: developer");
+    expect(result).toContain("### Step 2: reviewer");
+    expect(result).toContain("Continue from the reviewer feedback.");
+  });
+
+  test("still includes moderator instruction when there are no intervening steps", () => {
+    const result = buildContinuationPrompt(
+      [developerStep],
+      "developer",
+      "Please revise your work.",
+    );
+
+    expect(result).not.toContain("## What Happened Since Your Last Turn");
+    expect(result).toContain("## Moderator Instruction");
+    expect(result).toContain("Please revise your work.");
+  });
+});

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

@@ -2,13 +2,32 @@ import { describe, expect, test } from "vitest";
 
 import { buildOutputFormatInstruction } from "../src/build-output-format-instruction.js";
 
+const PLANNER_SCHEMA = {
+  type: "object",
+  properties: {
+    status: { type: "string", enum: ["ready", "insufficient_info"] },
+    plan: { type: "string" },
+  },
+  required: ["status"],
+  additionalProperties: false,
+};
+
+const REVIEWER_SCHEMA = {
+  type: "object",
+  properties: {
+    approved: { type: "boolean" },
+  },
+  required: ["approved"],
+  additionalProperties: false,
+};
+
 describe("buildOutputFormatInstruction", () => {
   test("always includes the frontmatter example block", () => {
     const result = buildOutputFormatInstruction({});
     expect(result).toContain("---");
-    expect(result).toContain("status: done");
-    expect(result).toContain("confidence:");
-    expect(result).toContain("scope: role");
+    expect(result).not.toContain("status: done");
+    expect(result).not.toContain("confidence:");
+    expect(result).not.toContain("scope: role");
   });
 
   test("always marks frontmatter as the primary deliverable", () => {
@@ -16,17 +35,36 @@ describe("buildOutputFormatInstruction", () => {
     expect(result).toContain("primary deliverable");
   });
 
-  test("lists fields from a flat object schema", () => {
+  test("generates planner-specific YAML example from schema", () => {
+    const result = buildOutputFormatInstruction(PLANNER_SCHEMA);
+    expect(result).toContain("status: ready  # required | ready | insufficient_info");
+    expect(result).toContain("plan: <string>");
+    expect(result).not.toContain("status: done");
+    expect(result).not.toContain("confidence:");
+    expect(result).not.toContain("artifacts:");
+  });
+
+  test("generates reviewer-specific YAML example from schema", () => {
+    const result = buildOutputFormatInstruction(REVIEWER_SCHEMA);
+    expect(result).toContain("approved: true  # required | true | false");
+    expect(result).not.toContain("status:");
+  });
+
+  test("lists fields from a flat object schema with required marker", () => {
     const schema = {
       type: "object",
       properties: {
         status: { type: "string" },
         confidence: { type: "number" },
       },
+      required: ["status"],
     };
     const result = buildOutputFormatInstruction(schema);
-    expect(result).toContain("`status`");
+    expect(result).toContain("`status` (required)");
     expect(result).toContain("`confidence`");
+    expect(result).not.toContain("`confidence` (required)");
+    expect(result).toContain("status: <string>  # required");
+    expect(result).toContain("confidence: <number>");
   });
 
   test("lists union of fields from an anyOf schema", () => {
@@ -45,6 +83,8 @@ describe("buildOutputFormatInstruction", () => {
     const result = buildOutputFormatInstruction(schema);
     expect(result).toContain("`alpha`");
     expect(result).toContain("`beta`");
+    expect(result).toContain("alpha: <string>");
+    expect(result).toContain("beta: <number>");
   });
 
   test("lists union of fields from a oneOf schema", () => {
@@ -63,6 +103,8 @@ describe("buildOutputFormatInstruction", () => {
     const result = buildOutputFormatInstruction(schema);
     expect(result).toContain("`foo`");
     expect(result).toContain("`bar`");
+    expect(result).toContain("foo: <string>");
+    expect(result).toContain("bar: true  # true | false");
   });
 
   test("falls back gracefully for a non-object schema with no properties", () => {
@@ -80,6 +122,45 @@ describe("buildOutputFormatInstruction", () => {
     const result = buildOutputFormatInstruction(schema);
     const matches = [...result.matchAll(/`shared`/g)];
     expect(matches.length).toBe(1);
+    expect(result).toContain("shared: <string>");
+  });
+
+  test("marks required when any union variant requires the field", () => {
+    const schema = {
+      anyOf: [
+        {
+          type: "object",
+          properties: { shared: { type: "string" } },
+          required: ["shared"],
+        },
+        { type: "object", properties: { shared: { type: "number" } } },
+      ],
+    };
+    const result = buildOutputFormatInstruction(schema);
+    expect(result).toContain("`shared` (required)");
+    expect(result).toContain("shared: <string>  # required");
+  });
+
+  test("explicitly forbids extra frontmatter fields", () => {
+    const result = buildOutputFormatInstruction(PLANNER_SCHEMA);
+    expect(result).toMatch(/\b(only|exclusively)\b.*fields/i);
+    expect(result).toMatch(/do not add (extra|additional|other) fields/i);
+  });
+
+  test("forbids extra fields even for empty schema", () => {
+    const result = buildOutputFormatInstruction({});
+    expect(result).toMatch(/do not add (extra|additional|other) fields/i);
+  });
+
+  test("forbids extra fields for anyOf/oneOf schemas", () => {
+    const schema = {
+      anyOf: [
+        { type: "object", properties: { alpha: { type: "string" } } },
+        { type: "object", properties: { beta: { type: "number" } } },
+      ],
+    };
+    const result = buildOutputFormatInstruction(schema);
+    expect(result).toMatch(/do not add (extra|additional|other) fields/i);
   });
 
   test("includes focus reminder about role scope", () => {

packages/workflow-agent-kit/__tests__/build-role-prompt.test.ts

@@ -1,54 +1,81 @@
-import { describe, expect, test } from "vitest";
 import type { RoleDefinition } from "@uncaged/workflow-protocol";
+import { describe, expect, test } from "vitest";
 import { buildRolePrompt } from "../src/build-role-prompt.js";
 
 describe("buildRolePrompt", () => {
   test("all fields present", () => {
     const role: RoleDefinition = {
       description: "A coder",
-      identity: "You are a senior developer.",
-      prepare: "Load cursor-agent skill.",
-      execute: "Implement the feature.",
-      report: "Summarize changes.",
-      outputSchema: "placeholder00000" as string,
+      goal: "You are a senior developer.",
+      capabilities: ["cursor-agent", "file-edit"],
+      procedure: "Implement the feature.",
+      output: "Summarize changes.",
+      meta: "placeholder00000" as string,
     };
     const result = buildRolePrompt(role);
-    expect(result).toContain("## Identity");
+    expect(result).toContain("## Goal");
     expect(result).toContain("You are a senior developer.");
+    expect(result).toContain("## Capabilities");
+    expect(result).toContain("- cursor-agent");
+    expect(result).toContain("- file-edit");
     expect(result).toContain("## Prepare");
-    expect(result).toContain("Load cursor-agent skill.");
-    expect(result).toContain("## Execute");
+    expect(result).toContain("uwf CLI Reference");
+    expect(result).toContain("cursor-agent, file-edit");
+    expect(result).toContain("## Procedure");
     expect(result).toContain("Implement the feature.");
-    expect(result).toContain("## Report");
+    expect(result).toContain("## Output");
     expect(result).toContain("Summarize changes.");
   });
 
-  test("empty fields are omitted", () => {
+  test("empty fields are omitted but Prepare is always present", () => {
     const role: RoleDefinition = {
       description: "A reviewer",
-      identity: "You are a code reviewer.",
-      prepare: "",
-      execute: "Review the PR diff carefully.",
-      report: "",
-      outputSchema: "placeholder00000" as string,
+      goal: "You are a code reviewer.",
+      capabilities: [],
+      procedure: "Review the PR diff carefully.",
+      output: "",
+      meta: "placeholder00000" as string,
     };
     const result = buildRolePrompt(role);
-    expect(result).toContain("## Identity");
-    expect(result).toContain("## Execute");
-    expect(result).not.toContain("## Prepare");
-    expect(result).not.toContain("## Report");
+    expect(result).toContain("## Goal");
+    expect(result).toContain("## Prepare");
+    expect(result).toContain("uwf CLI Reference");
+    expect(result).toContain("## Procedure");
+    expect(result).not.toContain("## Capabilities");
+    expect(result).not.toContain("## Output");
   });
 
-  test("all empty returns empty string", () => {
+  test("all empty still includes Prepare section", () => {
     const role: RoleDefinition = {
       description: "Minimal",
-      identity: "",
-      prepare: "",
-      execute: "",
-      report: "",
-      outputSchema: "placeholder00000" as string,
+      goal: "",
+      capabilities: [],
+      procedure: "",
+      output: "",
+      meta: "placeholder00000" as string,
     };
     const result = buildRolePrompt(role);
-    expect(result).toBe("");
+    expect(result).toContain("## Prepare");
+    expect(result).toContain("uwf CLI Reference");
+    expect(result).not.toContain("## Goal");
+    expect(result).not.toContain("## Capabilities");
+    expect(result).not.toContain("## Procedure");
+    expect(result).not.toContain("## Output");
+  });
+
+  test("capabilities rendered as bullet list", () => {
+    const role: RoleDefinition = {
+      description: "Agent",
+      goal: "",
+      capabilities: ["search", "code", "browse"],
+      procedure: "",
+      output: "",
+      meta: "placeholder00000" as string,
+    };
+    const result = buildRolePrompt(role);
+    expect(result).toContain("## Capabilities");
+    expect(result).toContain("- search");
+    expect(result).toContain("- code");
+    expect(result).toContain("- browse");
   });
 });

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

@@ -1,6 +1,5 @@
-import { describe, expect, test } from "vitest";
-
 import { createMemoryStore, putSchema } from "@uncaged/json-cas";
+import { describe, expect, test } from "vitest";
 
 import { tryFrontmatterFastPath } from "../src/frontmatter.js";
 
@@ -30,6 +29,27 @@ const STRICT_SCHEMA = {
   additionalProperties: false,
 };
 
+/** Role-specific schema (reviewer) — only approved, no standard agent fields. */
+const REVIEWER_SCHEMA = {
+  type: "object",
+  properties: {
+    approved: { type: "boolean" },
+  },
+  required: ["approved"],
+  additionalProperties: false,
+};
+
+/** Role-specific schema (planner) — custom status enum + plan hash. */
+const PLANNER_SCHEMA = {
+  type: "object",
+  properties: {
+    status: { type: "string", enum: ["ready", "insufficient_info"] },
+    plan: { type: "string" },
+  },
+  required: ["status"],
+  additionalProperties: false,
+};
+
 async function makeStoreWithSchema(schema: Record<string, unknown>) {
   const store = createMemoryStore();
   const schemaHash = await putSchema(store, schema);
@@ -68,7 +88,8 @@ describe("tryFrontmatterFastPath — happy path", () => {
   test("stored CAS node payload matches frontmatter fields", async () => {
     const { store, schemaHash } = await makeStoreWithSchema(FRONTMATTER_SCHEMA);
 
-    const raw = "---\nstatus: done\nnext: null\nconfidence: null\nartifacts: []\nscope: role\n---\n\nBody.";
+    const raw =
+      "---\nstatus: done\nnext: null\nconfidence: null\nartifacts: []\nscope: role\n---\n\nBody.";
 
     const result = await tryFrontmatterFastPath(raw, schemaHash, store);
     expect(result).not.toBeNull();
@@ -134,3 +155,48 @@ describe("tryFrontmatterFastPath — fallback: schema mismatch", () => {
     expect(result).toBeNull();
   });
 });
+
+// ── Role-specific schema fields ───────────────────────────────────────────────
+
+describe("tryFrontmatterFastPath — role-specific fields", () => {
+  test("extracts approved only for reviewer schema (no extra standard fields)", async () => {
+    const { store, schemaHash } = await makeStoreWithSchema(REVIEWER_SCHEMA);
+
+    const raw = "---\napproved: true\n---\n\nReview passed.";
+
+    const result = await tryFrontmatterFastPath(raw, schemaHash, store);
+    expect(result).not.toBeNull();
+
+    const node = store.get(result!.outputHash);
+    expect(node).not.toBeNull();
+    const payload = node!.payload as Record<string, unknown>;
+    expect(payload).toEqual({ approved: true });
+    expect(payload.status).toBeUndefined();
+    expect(payload.scope).toBeUndefined();
+  });
+
+  test("extracts plan and role-specific status for planner schema", async () => {
+    const { store, schemaHash } = await makeStoreWithSchema(PLANNER_SCHEMA);
+
+    const raw = "---\nstatus: ready\nplan: 01HASHPLANNER0001\n---\n\nSpec summary.";
+
+    const result = await tryFrontmatterFastPath(raw, schemaHash, store);
+    expect(result).not.toBeNull();
+
+    const node = store.get(result!.outputHash);
+    expect(node).not.toBeNull();
+    const payload = node!.payload as Record<string, unknown>;
+    expect(payload.status).toBe("ready");
+    expect(payload.plan).toBe("01HASHPLANNER0001");
+    expect(payload.scope).toBeUndefined();
+  });
+
+  test("returns null when required role-specific field is missing", async () => {
+    const { store, schemaHash } = await makeStoreWithSchema(REVIEWER_SCHEMA);
+
+    const raw = "---\nstatus: done\nscope: role\n---\n\nBody.";
+
+    const result = await tryFrontmatterFastPath(raw, schemaHash, store);
+    expect(result).toBeNull();
+  });
+});

packages/workflow-agent-kit/src/build-continuation-prompt.ts

@@ -0,0 +1,53 @@
+import type { StepContext } from "@uncaged/workflow-protocol";
+
+function formatStep(step: StepContext, stepNumber: number): string {
+  return [
+    `### Step ${stepNumber}: ${step.role}`,
+    `Output: ${JSON.stringify(step.output)}`,
+    `Agent: ${step.agent}`,
+  ].join("\n");
+}
+
+function findLastRoleIndex(steps: StepContext[], role: string): number {
+  for (let i = steps.length - 1; i >= 0; i--) {
+    const step = steps[i];
+    if (step !== undefined && step.role === role) {
+      return i;
+    }
+  }
+  return -1;
+}
+
+/**
+ * Build a continuation prompt for a role re-entry.
+ *
+ * Finds the most recent step for `role`, collects everything after it as context,
+ * and appends the moderator edge prompt as the instruction.
+ */
+export function buildContinuationPrompt(
+  steps: StepContext[],
+  role: string,
+  edgePrompt: string,
+): string {
+  const lastIndex = findLastRoleIndex(steps, role);
+  const sinceSteps = lastIndex >= 0 ? steps.slice(lastIndex + 1) : steps;
+
+  const parts: string[] = [];
+
+  if (sinceSteps.length > 0) {
+    parts.push("## What Happened Since Your Last Turn");
+    const baseStepNumber = lastIndex >= 0 ? lastIndex + 2 : 1;
+    for (let i = 0; i < sinceSteps.length; i++) {
+      const step = sinceSteps[i];
+      if (step === undefined) {
+        continue;
+      }
+      parts.push("");
+      parts.push(formatStep(step, baseStepNumber + i));
+    }
+    parts.push("");
+  }
+
+  parts.push("## Moderator Instruction", "", edgePrompt);
+  return parts.join("\n");
+}

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

@@ -1,5 +1,11 @@
 import type { JSONSchema } from "@uncaged/json-cas";
 
+type SchemaProperty = {
+  name: string;
+  schema: JSONSchema;
+  required: boolean;
+};
+
 /**
  * Extract top-level property names from a JSON Schema object.
  *
@@ -9,9 +15,44 @@ import type { JSONSchema } from "@uncaged/json-cas";
  *
  * Returns an empty array for schemas with no inspectable property definitions.
  */
-function extractSchemaFields(schema: JSONSchema): string[] {
+export function extractSchemaFields(schema: JSONSchema): string[] {
+  return extractSchemaProperties(schema).map((p) => p.name);
+}
+
+function extractSchemaProperties(schema: JSONSchema): SchemaProperty[] {
+  const objectSchemas = collectObjectSchemas(schema);
+  if (objectSchemas.length === 0) {
+    return [];
+  }
+
+  const byName = new Map<string, SchemaProperty>();
+
+  for (const objectSchema of objectSchemas) {
+    const requiredSet = new Set(
+      Array.isArray(objectSchema.required) ? (objectSchema.required as string[]) : [],
+    );
+    const properties = objectSchema.properties as Record<string, JSONSchema> | null | undefined;
+    if (typeof properties !== "object" || properties === null) {
+      continue;
+    }
+
+    for (const [name, propSchema] of Object.entries(properties)) {
+      const required = requiredSet.has(name);
+      const existing = byName.get(name);
+      if (existing === undefined) {
+        byName.set(name, { name, schema: propSchema, required });
+      } else if (required) {
+        byName.set(name, { ...existing, required: true });
+      }
+    }
+  }
+
+  return [...byName.values()];
+}
+
+function collectObjectSchemas(schema: JSONSchema): JSONSchema[] {
   if (typeof schema.properties === "object" && schema.properties !== null) {
-    return Object.keys(schema.properties as Record<string, unknown>);
+    return [schema];
   }
 
   const unionKey = Array.isArray(schema.anyOf)
@@ -20,18 +61,109 @@ function extractSchemaFields(schema: JSONSchema): string[] {
       ? "oneOf"
       : null;
 
-  if (unionKey !== null) {
-    const variants = schema[unionKey] as JSONSchema[];
-    const fieldSet = new Set<string>();
-    for (const variant of variants) {
-      for (const field of extractSchemaFields(variant)) {
-        fieldSet.add(field);
-      }
-    }
-    return [...fieldSet];
+  if (unionKey === null) {
+    return [];
   }
 
-  return [];
+  const variants = schema[unionKey] as JSONSchema[];
+  const result: JSONSchema[] = [];
+  for (const variant of variants) {
+    result.push(...collectObjectSchemas(variant));
+  }
+  return result;
+}
+
+function resolvePropertySchema(prop: JSONSchema): JSONSchema {
+  if (Array.isArray(prop.enum) && prop.enum.length > 0) {
+    return prop;
+  }
+
+  const unionKey = Array.isArray(prop.anyOf) ? "anyOf" : Array.isArray(prop.oneOf) ? "oneOf" : null;
+
+  if (unionKey !== null) {
+    const variants = prop[unionKey] as JSONSchema[];
+    const nonNull = variants.filter((v) => v.type !== "null");
+    if (nonNull.length === 1) {
+      return nonNull[0];
+    }
+  }
+
+  return prop;
+}
+
+function formatYamlScalar(value: unknown): string {
+  if (typeof value === "boolean") {
+    return String(value);
+  }
+  if (typeof value === "number") {
+    return String(value);
+  }
+  return String(value);
+}
+
+function buildPropertyComment(parts: string[]): string {
+  const filtered = parts.filter((p) => p.length > 0);
+  return filtered.length > 0 ? `  # ${filtered.join(" | ")}` : "";
+}
+
+function buildPropertyExampleLine(prop: SchemaProperty): string {
+  const resolved = resolvePropertySchema(prop.schema);
+  const commentParts: string[] = [];
+  if (prop.required) {
+    commentParts.push("required");
+  }
+
+  if (Array.isArray(resolved.enum) && resolved.enum.length > 0) {
+    const enumValues = resolved.enum.map((v) => String(v));
+    commentParts.push(...enumValues);
+    const first = resolved.enum[0];
+    return `${prop.name}: ${formatYamlScalar(first)}${buildPropertyComment(commentParts)}`;
+  }
+
+  if (resolved.type === "boolean") {
+    commentParts.push("true", "false");
+    return `${prop.name}: true${buildPropertyComment(commentParts)}`;
+  }
+
+  if (resolved.type === "string") {
+    return `${prop.name}: <string>${buildPropertyComment(commentParts)}`;
+  }
+
+  if (resolved.type === "number" || resolved.type === "integer") {
+    return `${prop.name}: <number>${buildPropertyComment(commentParts)}`;
+  }
+
+  if (resolved.type === "array") {
+    return `${prop.name}:\n  - <item>${buildPropertyComment(commentParts)}`;
+  }
+
+  if (resolved.type === "object") {
+    return `${prop.name}: <object>${buildPropertyComment(commentParts)}`;
+  }
+
+  return `${prop.name}: <value>${buildPropertyComment(commentParts)}`;
+}
+
+function buildYamlExampleBlock(properties: SchemaProperty[]): string {
+  if (properties.length === 0) {
+    return "---\n\n... your markdown work here ...";
+  }
+
+  const lines = properties.map((p) => buildPropertyExampleLine(p));
+  return `---\n${lines.join("\n")}\n---\n\n... your markdown work here ...`;
+}
+
+function buildFieldList(properties: SchemaProperty[]): string {
+  if (properties.length === 0) {
+    return "  (schema fields will be extracted automatically)";
+  }
+
+  return properties
+    .map((p) => {
+      const suffix = p.required ? " (required)" : "";
+      return `  - \`${p.name}\`${suffix}`;
+    })
+    .join("\n");
 }
 
 /**
@@ -42,28 +174,16 @@ function extractSchemaFields(schema: JSONSchema): string[] {
  * system prompt so the deliverable format is the first thing the agent sees.
  */
 export function buildOutputFormatInstruction(schema: JSONSchema): string {
-  const fields = extractSchemaFields(schema);
-
-  const fieldList =
-    fields.length > 0
-      ? fields.map((f) => `  - \`${f}\``).join("\n")
-      : "  (schema fields will be extracted automatically)";
+  const properties = extractSchemaProperties(schema);
+  const yamlExample = buildYamlExampleBlock(properties);
+  const fieldList = buildFieldList(properties);
 
   return `## Deliverable Format
 
 Your response MUST begin with a YAML frontmatter block followed by your markdown work:
 
 \`\`\`
----
-status: done          # done | needs_input | in_progress | failed
-next: <role-name>     # suggested next role, or omit
-confidence: 0.9       # 0.0–1.0, your self-assessed confidence
-artifacts:            # list of file paths or CAS hashes you produced
-  - path/to/file.ts
-scope: role           # role | thread
----
-
-... your markdown work here ...
+${yamlExample}
 \`\`\`
 
 The frontmatter is the **primary deliverable** — the engine reads it directly.
@@ -71,5 +191,7 @@ Your meta output must satisfy these fields:
 
 ${fieldList}
 
+Output ONLY the fields listed above. Do not add extra fields that are not specified in the schema.
+
 Focus exclusively on YOUR role's deliverable. Do not perform actions outside your role's scope.`;
 }

packages/workflow-agent-kit/src/build-role-prompt.ts

@@ -1,28 +1,43 @@
 import type { RoleDefinition } from "@uncaged/workflow-protocol";
+import { generateCliReference } from "@uncaged/workflow-util";
 
 /**
  * Build the role prompt from a RoleDefinition.
  *
- * Assembles structured sections: Identity, Prepare, Execute, Report.
- * Empty strings are omitted from the output.
+ * Assembles structured sections: Goal, Capabilities, Prepare, Procedure, Output.
+ * Empty strings and empty arrays are omitted from the output.
+ *
+ * The Prepare section always inlines the uwf CLI reference so the agent has
+ * workflow knowledge without needing to run an external command. The capabilities
+ * array is rendered as keyword hints for implicit skill loading.
  */
 export function buildRolePrompt(role: RoleDefinition): string {
   const sections: string[] = [];
 
-  if (role.identity !== "") {
-    sections.push(`## Identity\n\n${role.identity}`);
+  if (role.goal !== "") {
+    sections.push(`## Goal\n\n${role.goal}`);
   }
 
-  if (role.prepare !== "") {
-    sections.push(`## Prepare\n\n${role.prepare}`);
+  if (role.capabilities.length > 0) {
+    const list = role.capabilities.map((c) => `- ${c}`).join("\n");
+    sections.push(`## Capabilities\n\n${list}`);
   }
 
-  if (role.execute !== "") {
-    sections.push(`## Execute\n\n${role.execute}`);
+  const prepareLines: string[] = [generateCliReference()];
+  if (role.capabilities.length > 0) {
+    const keywords = role.capabilities.join(", ");
+    prepareLines.push(
+      `You have the following capabilities: ${keywords}. Load relevant skills matching these keywords before starting work.`,
+    );
+  }
+  sections.push(`## Prepare\n\n${prepareLines.join("\n\n")}`);
+
+  if (role.procedure !== "") {
+    sections.push(`## Procedure\n\n${role.procedure}`);
   }
 
-  if (role.report !== "") {
-    sections.push(`## Report\n\n${role.report}`);
+  if (role.output !== "") {
+    sections.push(`## Output\n\n${role.output}`);
   }
 
   return sections.join("\n\n");

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

@@ -6,8 +6,8 @@ import type {
   StepNodePayload,
   ThreadId,
 } from "@uncaged/workflow-protocol";
-import { createAgentStore, loadThreadsIndex, resolveStorageRoot } from "./storage.js";
 import type { AgentStore } from "./storage.js";
+import { createAgentStore, loadThreadsIndex, resolveStorageRoot } from "./storage.js";
 import type { AgentContext } from "./types.js";
 
 type ChainState = {
@@ -21,11 +21,15 @@ function fail(message: string): never {
   throw new Error(message);
 }
 
-function walkChain(
-  store: Store,
-  schemas: AgentStore["schemas"],
-  headHash: CasRef,
-): ChainState {
+function readEdgePrompt(): string {
+  const value = process.env.UWF_EDGE_PROMPT;
+  if (value === undefined || value === "") {
+    fail("UWF_EDGE_PROMPT environment variable is required");
+  }
+  return value;
+}
+
+function walkChain(store: Store, schemas: AgentStore["schemas"], headHash: CasRef): ChainState {
   const headNode = store.get(headHash);
   if (headNode === null) {
     fail(`CAS node not found: ${headHash}`);
@@ -78,10 +82,7 @@ function walkChain(
   };
 }
 
-function expandOutput(
-  store: Store,
-  outputRef: CasRef,
-): unknown {
+function expandOutput(store: Store, outputRef: CasRef): unknown {
   const node = store.get(outputRef);
   if (node === null) {
     return {};
@@ -106,11 +107,7 @@ async function buildHistory(
   return history;
 }
 
-async function loadWorkflow(
-  store: Store,
-  schemas: AgentStore["schemas"],
-  workflowRef: CasRef,
-) {
+async function loadWorkflow(store: Store, schemas: AgentStore["schemas"], workflowRef: CasRef) {
   const node = store.get(workflowRef);
   if (node === null) {
     fail(`workflow CAS node not found: ${workflowRef}`);
@@ -144,6 +141,8 @@ export async function buildContext(threadId: ThreadId, role: string): Promise<Ag
   }
 
   const steps = await buildHistory(store, chain.stepsNewestFirst);
+  const edgePrompt = readEdgePrompt();
+  const isFirstVisit = !steps.some((s) => s.role === role);
 
   return {
     threadId,
@@ -153,6 +152,8 @@ export async function buildContext(threadId: ThreadId, role: string): Promise<Ag
     workflow,
     store,
     outputFormatInstruction: "",
+    edgePrompt,
+    isFirstVisit,
   };
 }
 
@@ -189,6 +190,8 @@ export async function buildContextWithMeta(
   }
 
   const steps = await buildHistory(store, chain.stepsNewestFirst);
+  const edgePrompt = readEdgePrompt();
+  const isFirstVisit = !steps.some((s) => s.role === role);
 
   return {
     threadId,
@@ -198,6 +201,8 @@ export async function buildContextWithMeta(
     workflow,
     store,
     outputFormatInstruction: "",
+    edgePrompt,
+    isFirstVisit,
     meta: { storageRoot, store, schemas, headHash, chain },
   };
 }

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

@@ -1,13 +1,139 @@
-import { validate } from "@uncaged/json-cas";
 import type { Store } from "@uncaged/json-cas";
+import { getSchema, validate } from "@uncaged/json-cas";
 import type { CasRef } from "@uncaged/workflow-protocol";
-import { parseFrontmatterMarkdown, validateFrontmatter } from "@uncaged/workflow-util";
+import {
+  type AgentFrontmatter,
+  createLogger,
+  parseFrontmatterMarkdown,
+  validateFrontmatter,
+} from "@uncaged/workflow-util";
+import { parse as parseYaml } from "yaml";
+
+import { extractSchemaFields } from "./build-output-format-instruction.js";
+
+const log = createLogger({ sink: { kind: "stderr" } });
+
+const STANDARD_KEYS = ["status", "next", "confidence", "artifacts", "scope"] as const;
+
+type StandardKey = (typeof STANDARD_KEYS)[number];
 
 export type FrontmatterFastPathResult = {
   body: string;
   outputHash: CasRef;
 };
 
+function extractYamlBlock(raw: string): string | null {
+  const fence = "---";
+  if (!raw.startsWith(fence)) {
+    return null;
+  }
+
+  const rest = raw.slice(fence.length);
+  if (rest.length > 0 && rest[0] !== "\n" && rest[0] !== "\r") {
+    return null;
+  }
+
+  const afterOpen = rest.startsWith("\n") ? rest.slice(1) : rest;
+  const closeIndex = afterOpen.indexOf(`\n${fence}`);
+  if (closeIndex === -1) {
+    return null;
+  }
+
+  return afterOpen.slice(0, closeIndex);
+}
+
+function parseRawFrontmatterFields(raw: string): Record<string, unknown> {
+  const yamlText = extractYamlBlock(raw);
+  if (yamlText === null) {
+    return {};
+  }
+
+  try {
+    const parsed = parseYaml(yamlText);
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      return {};
+    }
+    return parsed as Record<string, unknown>;
+  } catch {
+    return {};
+  }
+}
+
+function defaultCandidate(frontmatter: AgentFrontmatter): Record<string, unknown> {
+  return {
+    status: frontmatter.status,
+    next: frontmatter.next,
+    confidence: frontmatter.confidence,
+    artifacts: [...frontmatter.artifacts],
+    scope: frontmatter.scope,
+  };
+}
+
+function pickStandardField(frontmatter: AgentFrontmatter, key: StandardKey): unknown {
+  switch (key) {
+    case "status":
+      return frontmatter.status;
+    case "next":
+      return frontmatter.next;
+    case "confidence":
+      return frontmatter.confidence;
+    case "artifacts":
+      return [...frontmatter.artifacts];
+    case "scope":
+      return frontmatter.scope;
+  }
+}
+
+function isStandardKey(key: string): key is StandardKey {
+  return (STANDARD_KEYS as readonly string[]).includes(key);
+}
+
+function pickFieldValue(
+  field: string,
+  frontmatter: AgentFrontmatter,
+  rawFields: Record<string, unknown>,
+): unknown | undefined {
+  if (!isStandardKey(field)) {
+    return Object.hasOwn(rawFields, field) ? rawFields[field] : undefined;
+  }
+
+  const coerced = pickStandardField(frontmatter, field);
+  if (field === "artifacts" || field === "scope") {
+    return coerced;
+  }
+  if (coerced !== null) {
+    return coerced;
+  }
+  return Object.hasOwn(rawFields, field) ? rawFields[field] : coerced;
+}
+
+/**
+ * Build a CAS candidate object from schema property keys and parsed frontmatter.
+ *
+ * When the schema has no inspectable properties, falls back to the five standard
+ * agent frontmatter fields for backward compatibility.
+ */
+function buildCandidate(
+  frontmatter: AgentFrontmatter,
+  rawFields: Record<string, unknown>,
+  schemaFields: string[],
+): Record<string, unknown> {
+  if (schemaFields.length === 0) {
+    return defaultCandidate(frontmatter);
+  }
+
+  const candidate: Record<string, unknown> = {};
+
+  for (const field of schemaFields) {
+    const value = pickFieldValue(field, frontmatter, rawFields);
+    if (value !== undefined) {
+      candidate[field] = value;
+    }
+  }
+
+  return candidate;
+}
+
 /**
  * Try to satisfy `outputSchema` from frontmatter fields alone.
  *
@@ -32,16 +158,22 @@ export async function tryFrontmatterFastPath(
 
   const validationErrors = validateFrontmatter(frontmatter);
   if (validationErrors.length > 0) {
+    log(
+      "9GNPS4WY",
+      `frontmatter validation errors: ${validationErrors.map((e) => e.message).join("; ")}`,
+    );
     return null;
   }
 
-  const candidate: Record<string, unknown> = {
-    status: frontmatter.status,
-    next: frontmatter.next,
-    confidence: frontmatter.confidence,
-    artifacts: [...frontmatter.artifacts],
-    scope: frontmatter.scope,
-  };
+  const schema = getSchema(store, outputSchema);
+  if (schema === null) {
+    log("8FHMR2QX", `output schema not found in CAS: ${outputSchema}`);
+    return null;
+  }
+
+  const schemaFields = extractSchemaFields(schema);
+  const rawFields = parseRawFrontmatterFields(raw);
+  const candidate = buildCandidate(frontmatter, rawFields, schemaFields);
 
   let outputHash: CasRef;
   let node: ReturnType<Store["get"]>;
@@ -50,10 +182,12 @@ export async function tryFrontmatterFastPath(
     outputHash = await store.put(outputSchema, candidate);
     node = store.get(outputHash);
   } catch {
+    log("2KMQT7NR", "failed to store frontmatter candidate in CAS");
     return null;
   }
 
   if (node === null || !validate(store, node)) {
+    log("2KMQT7NR", "stored frontmatter candidate failed schema validation");
     return null;
   }
 

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

@@ -1,3 +1,6 @@
+export { buildContinuationPrompt } from "./build-continuation-prompt.js";
+export { buildOutputFormatInstruction } from "./build-output-format-instruction.js";
+export { buildRolePrompt } from "./build-role-prompt.js";
 export type { BuildContextMeta } from "./context.js";
 export { buildContext, buildContextWithMeta } from "./context.js";
 export type { ExtractResult, ResolvedLlmProvider } from "./extract.js";
@@ -6,10 +9,14 @@ export {
   resolveExtractModelAlias,
   resolveModel,
 } from "./extract.js";
-export { buildOutputFormatInstruction } from "./build-output-format-instruction.js";
-export { buildRolePrompt } from "./build-role-prompt.js";
 export type { FrontmatterFastPathResult } from "./frontmatter.js";
 export { tryFrontmatterFastPath } from "./frontmatter.js";
 export { createAgent } from "./run.js";
-export { getConfigPath, getEnvPath, loadWorkflowConfig } from "./storage.js";
-export type { AgentContext, AgentOptions, AgentRunFn, AgentRunResult } from "./types.js";
+export { getConfigPath, getEnvPath, loadWorkflowConfig, resolveStorageRoot } from "./storage.js";
+export type {
+  AgentContext,
+  AgentContinueFn,
+  AgentOptions,
+  AgentRunFn,
+  AgentRunResult,
+} from "./types.js";

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

@@ -1,14 +1,14 @@
 import { getSchema, validate } from "@uncaged/json-cas";
 import type { CasRef, StepNodePayload, ThreadId } from "@uncaged/workflow-protocol";
 import { config as loadDotenv } from "dotenv";
-
-import { buildContextWithMeta } from "./context.js";
 import { buildOutputFormatInstruction } from "./build-output-format-instruction.js";
-import { extract } from "./extract.js";
+import { buildContextWithMeta } from "./context.js";
 import { tryFrontmatterFastPath } from "./frontmatter.js";
 import type { AgentStore } from "./storage.js";
-import { getEnvPath, loadWorkflowConfig, resolveStorageRoot } from "./storage.js";
-import type { AgentContext, AgentOptions, AgentRunResult } from "./types.js";
+import { getEnvPath, resolveStorageRoot } from "./storage.js";
+import type { AgentOptions } from "./types.js";
+
+const MAX_FRONTMATTER_RETRIES = 2;
 
 function fail(message: string): never {
   process.stderr.write(`${message}\n`);
@@ -67,31 +67,16 @@ async function writeStepNode(options: {
   return hash;
 }
 
-async function runAgent(options: AgentOptions, ctx: AgentContext): Promise<AgentRunResult> {
-  return runWithMessage("agent run failed", () => options.run(ctx));
-}
-
-async function extractOutput(
+async function tryExtractOutput(
   rawOutput: string,
   outputSchema: CasRef,
-  storageRoot: string,
   ctx: Awaited<ReturnType<typeof buildContextWithMeta>>,
-): Promise<CasRef> {
-  const fastPath = await runWithMessage("frontmatter fast path", () =>
-    tryFrontmatterFastPath(rawOutput, outputSchema, ctx.meta.store),
-  ).catch(() => null);
-
+): Promise<CasRef | null> {
+  const fastPath = await tryFrontmatterFastPath(rawOutput, outputSchema, ctx.meta.store);
   if (fastPath !== null) {
     return fastPath.outputHash;
   }
-
-  const config = await runWithMessage("failed to load config", () =>
-    loadWorkflowConfig(storageRoot),
-  );
-  const extracted = await runWithMessage("extract failed", () =>
-    extract(rawOutput, outputSchema, config),
-  );
-  return extracted.hash;
+  return null;
 }
 
 async function persistStep(options: {
@@ -113,11 +98,6 @@ async function persistStep(options: {
   });
 }
 
-/**
- * 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);
@@ -131,13 +111,36 @@ export function createAgent(options: AgentOptions): () => Promise<void> {
       fail(`unknown role: ${role}`);
     }
 
-    const outputSchema = getSchema(ctx.meta.store, roleDef.outputSchema);
-    if (outputSchema !== null) {
-      ctx.outputFormatInstruction = buildOutputFormatInstruction(outputSchema);
+    const frontmatterSchema = getSchema(ctx.meta.store, roleDef.frontmatter);
+    if (frontmatterSchema !== null) {
+      ctx.outputFormatInstruction = buildOutputFormatInstruction(frontmatterSchema);
+    }
+
+    let agentResult = await runWithMessage("agent run failed", () => options.run(ctx));
+
+    // Try to extract frontmatter; retry via continue if it fails
+    let outputHash = await tryExtractOutput(agentResult.output, roleDef.frontmatter, ctx);
+
+    for (let retry = 0; retry < MAX_FRONTMATTER_RETRIES && outputHash === null; retry++) {
+      const correctionMessage =
+        "Your previous response did not contain valid YAML frontmatter matching the role schema.\n" +
+        "You MUST begin your response with a YAML frontmatter block (--- delimited).\n" +
+        "Please output ONLY the corrected frontmatter block followed by your work.";
+
+      agentResult = await runWithMessage("agent continue failed", () =>
+        options.continue(agentResult.sessionId, correctionMessage, ctx.meta.store),
+      );
+      outputHash = await tryExtractOutput(agentResult.output, roleDef.frontmatter, ctx);
+    }
+
+    if (outputHash === null) {
+      fail(
+        "Agent output does not contain valid YAML frontmatter matching the role schema " +
+          `after ${MAX_FRONTMATTER_RETRIES} retries.\n` +
+          `Raw output (first 500 chars): ${agentResult.output.slice(0, 500)}`,
+      );
     }
 
-    const agentResult = await runAgent(options, ctx);
-    const outputHash = await extractOutput(agentResult.output, roleDef.outputSchema, storageRoot, ctx);
     const stepHash = await persistStep({
       ctx,
       outputHash,

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

@@ -12,16 +12,33 @@ export type AgentContext = ModeratorContext & {
    * role's output schema.  Populated by `createAgent` at run time.
    */
   outputFormatInstruction: string;
+  /**
+   * Edge prompt from the graph transition that led to this role (UWF_EDGE_PROMPT).
+   * Always the real moderator instruction for this step.
+   */
+  edgePrompt: string;
+  /**
+   * True when the current role has not appeared in steps history before this invocation.
+   */
+  isFirstVisit: boolean;
 };
 
 export type AgentRunResult = {
   output: string;
   detailHash: string;
+  sessionId: string;
 };
 
+export type AgentContinueFn = (
+  sessionId: string,
+  message: string,
+  store: AgentContext["store"],
+) => Promise<AgentRunResult>;
+
 export type AgentRunFn = (ctx: AgentContext) => Promise<AgentRunResult>;
 
 export type AgentOptions = {
   name: string;
   run: AgentRunFn;
+  continue: AgentContinueFn;
 };

packages/workflow-dashboard/components.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "base-nova",
+  "rsc": false,
+  "tsx": true,
+  "tailwind": {
+    "config": "",
+    "css": "src/index.css",
+    "baseColor": "neutral",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "iconLibrary": "lucide",
+  "rtl": false,
+  "aliases": {
+    "components": "@/components",
+    "utils": "@/lib/utils",
+    "ui": "@/components/ui",
+    "lib": "@/lib",
+    "hooks": "@/hooks"
+  },
+  "menuColor": "default",
+  "menuAccent": "subtle",
+  "registries": {}
+}

packages/workflow-dashboard/context.md

@@ -0,0 +1,400 @@
+
+# Workflow UI — 开发上下文文档
+
+## 1. 项目定位
+
+workflow-dashboard 是一个 Web 图形编辑器，用于可视化展示和编辑工作流（Workflow）的结构。
+
+**核心场景**：
+- 用户本地执行 `uwf connect` 命令，通过 WebSocket 连接到此 Web 服务
+- CLI 将本地 YAML 工作流文件发送到 server
+- Server 解析后，提供图形化界面展示工作流的节点拓扑，允许用户进行逻辑编排和节点编辑
+- 编辑完成后，数据可回传给 CLI 或持久化
+
+## 2. 技术栈
+
+| 层 | 技术 | 说明 |
+|---|------|------|
+| 图编辑器 | @xyflow/react v12 | 节点/边渲染、拖拽、连线（strict 连接模式） |
+| 前端框架 | React 19 | UI 组件 |
+| 路由 | react-router v7 | Hash 模式路由 |
+| 状态管理 | 自研 (context.tsx) | 基于 useSyncExternalStore + Immer |
+| 样式 | Tailwind CSS v4 | 原子化 CSS |
+| 图标 | lucide-react | 图标库 |
+| 构建工具 | Vite 8 | Dev server + 打包 |
+| 后端框架 | Elysia | 轻量 REST API（当前为 stub） |
+
+## 3. 目录结构
+
+```
+workflow-dashboard/
+├── server.ts                 # Vite dev server 入口 (port 3000)
+├── vite.config.ts            # Vite 配置（react + tailwind + elysia 插件 + @ 别名）
+├── vite-dev.ts               # 自定义 Vite 插件
+├── components.json           # shadcn 配置
+├── server/
+│   ├── api.ts                # Elysia REST API (health + workflow CRUD)
+│   └── workflow.ts           # Workflow 文件读写 + 格式转换
+├── tmp/workflow/             # Workflow YAML 存储目录（开发阶段）
+├── src/
+│   ├── main.tsx              # React DOM 入口
+│   ├── router.tsx            # React Router 配置
+│   ├── app.tsx               # 根布局组件
+│   ├── lib/utils.ts          # Tailwind cn() 工具
+│   ├── components/ui/        # shadcn 组件（button, card, dialog, input, textarea）
+│   ├── pages/
+│   │   ├── home.tsx          # Home 列表页（workflow 管理）
+│   │   └── detail.tsx        # Workflow 详情/编辑页
+│   └── editor/               # ★ 核心编辑器
+│       ├── flow.tsx          # FlowEditor 组件 + 公开 API 导出
+│       ├── type.ts           # 内部类型定义
+│       ├── context.tsx       # 自研状态管理框架
+│       ├── injection.ts      # DI 容器（FlowModel / Injection）
+│       ├── model/            # 状态模型层
+│       ├── nodes/            # 节点渲染组件
+│       ├── edges/            # 边渲染组件
+│       ├── panel/            # UI 面板（工具栏、添加/编辑面板）
+│       ├── trans/            # 数据转换层（内外格式互转）
+│       ├── layout/           # 自动布局算法
+│       └── utils/            # 工具函数
+```
+
+## 4. 数据模型
+
+### 4.1 外部格式 — WorkFlowSteps（与 CLI 交换的数据）
+
+`WorkFlowSteps` 是 `WorkFlowStep[]`，每个 step 描述一个角色节点及其转移关系：
+
+```typescript
+type WorkFlowRole = {
+  name: string;          // 角色名称（唯一标识）
+  description: string;   // 角色描述
+  identity: string;      // 身份定义（system prompt）
+  prepare: string;       // 执行前准备指令
+  execute: string;       // 核心执行指令
+  report: string;        // 输出格式指令
+};
+
+type WorkFlowTransition = {
+  target: string;           // 目标角色名 或 'END'
+  condition: string | null; // 条件表达式，null 为 else（无条件兜底）
+};
+
+type WorkFlowStep = {
+  role: WorkFlowRole;
+  transitions: WorkFlowTransition[];
+};
+```
+
+### 4.2 内部格式 — ReactFlow Nodes & Edges
+
+编辑器内部使用 ReactFlow 的 Node/Edge 模型：
+
+**节点类型**：
+- `start` → 起始节点（右侧 1 个 source handle）
+- `end` → 结束节点（左侧 1 个 target handle）
+- `role` → 角色节点（6 个 handle，见下方）
+
+**Role 节点 Handle 布局**：
+
+| 位置 | 类型 | ID | 颜色 |
+|------|------|----|------|
+| 左侧 | target (in) | `input` | 蓝色 |
+| 上方 30% | target (in) | `input-top` | 蓝色 |
+| 下方 30% | target (in) | `input-bottom` | 蓝色 |
+| 右侧 | source (out) | `output` | 绿色 |
+| 上方 70% | source (out) | `output-top` | 绿色 |
+| 下方 70% | source (out) | `output-bottom` | 绿色 |
+
+- target handle 设置了 `isConnectableStart`，可以从 in 拖向 out 发起连线（`onConnect` 自动纠正方向）
+- source handle 设置了 `isConnectableEnd`
+
+**RoleNodeData** 对齐上游 `RoleDefinition`：
+```typescript
+type RoleNodeData = {
+  name: string;
+  description: string;
+  identity: string;
+  prepare: string;
+  execute: string;
+  report: string;
+};
+```
+
+**边类型**：
+- `default`（GradientEdge）→ 渐变色边（绿→蓝），节点仅有一条出边时使用
+- `conditional`（ConditionalEdge）→ 带条件标签的渐变色边，节点有多条出边时使用
+
+**边渲染特性**：
+- 渐变色：SVG linearGradient，从 source 端绿色（#10b981）到 target 端蓝色（#3b82f6）
+- 选中时：变为琥珀色（#f59e0b）单色，方便识别
+- 缺少条件时：红色（#ff5252）
+- 交互区域：20px 宽透明路径用于点击
+
+### 4.3 Else 分支机制
+
+当一个节点有多条 conditional 出边时：
+- **edges 数组中排第一个的 conditional 边自动成为 else**（兜底分支）
+- else 边显示灰色 `else` badge（不可点击，无需设置条件）
+- 其余边显示 `if` badge（需要设置条件，可点击编辑）
+- 只有一条 conditional 出边时不显示 else 标签
+- else 边在有 if 兄弟存在时不能被删除（`onBeforeDelete` 保护）
+- 序列化时 else 边输出 `condition: null`
+- 反序列化时 `condition: null` 的 transition 排序到第一个
+
+### 4.4 条件边自动升级与降级
+
+- **升级**：当用户从某节点拖出第二条边时，`edgesModel.onConnect` 自动将该节点所有出边升级为 `conditional` 类型。
+- **降级**：当删除 conditional 边后，若该 source 仅剩一条 conditional 出边，`handlers.onDelete` 自动将其降级回 `default` 类型。
+
+### 4.5 连线约束
+
+`onConnect` 中的校验逻辑：
+1. 禁止自连（source === target）
+2. 禁止同一对节点之间的重复边（source+target 去重）
+3. 方向归一化：从 input handle 拖到 output handle 时自动反转 source/target
+4. Handle 类型校验：source 端必须是 output handle，target 端必须是 input handle
+
+### 4.6 数据转换层（trans/）
+
+```
+WorkFlowSteps  ──transIn()──→  { nodes, edges }  ──transOut()──→  WorkFlowSteps
+                 （反序列化）                           （序列化）
+```
+
+- `transIn(steps)`: 外部步骤列表 → ReactFlow 节点和边
+- `transOut(nodes, edges)`: ReactFlow 节点和边 → 外部步骤列表
+- `validate(nodes, edges)`: 校验图结构合法性
+
+三个函数都是**纯函数**。
+
+### 4.7 验证规则
+
+1. start 恰好 1 个，输出恰好 1 条
+2. end 恰好 1 个，输入 ≥1 条，输出 0 条
+3. role 节点：输入 ≥1、输出 ≥1
+4. 多输出时：第一条 conditional 边为 else（跳过 condition 检查），其余必须有非空 condition
+5. role 节点总数 ≥2
+6. 无孤立节点（正向 BFS 从 start 可达 + 反向 BFS 从 end 可达）
+
+## 5. 架构分层
+
+### 5.1 状态管理框架（context.tsx）
+
+自研的轻量响应式系统，核心概念：
+
+| 概念 | 说明 |
+|------|------|
+| `generate<T>()` | 创建响应式 store（get/set/use/listen） |
+| `SubModel<T, A>` | 状态切片模板（name + make() + create()） |
+| `Model` | 事务管理器 + undo/redo 栈 |
+| `define.model()` | 定义有状态有 actions 的模型 |
+| `define.view()` | 定义只读视图模型 |
+| `define.memoize()` | 定义缓存计算模型 |
+| `define.compute()` | 定义响应式依赖计算（自动追踪） |
+
+使用 `useSyncExternalStore` 桥接 React 渲染。
+
+### 5.2 模型层（model/）
+
+| 模型 | 文件 | 职责 |
+|------|------|------|
+| `nodesModel` | nodes.ts | 节点数组状态 + CRUD 操作 |
+| `edgesModel` | edges.ts | 边数组状态 + 连线 + conditional 自动升级 + 连线约束 |
+| `addNodeViewModel` | add-node-view.ts | 添加节点面板的 UI 状态 |
+| `editNodeViewModel` | edit-node-view.ts | 编辑节点面板的 UI 状态 |
+| `injection` | inject.ts | DI 实例视图模型 |
+| `handlers` | handlers.ts | 事件处理器集合（拖拽、连线、删除保护、快捷键、布局、加载/保存） |
+
+### 5.3 DI 容器（injection.ts）
+
+```
+FlowModel（公开 API）          Injection（内部实现）
+  ├─ load(steps)  ──emit──→     emit('load', steps)  → handlers.loadSteps()
+  ├─ on('save', cb)              emit('save', steps)  ← handlers.saveData()
+  └─ 持有 Injection 实例
+```
+
+- `FlowModel` 是外部消费者唯一接触的类，提供 `load()` 和 `on('save')` 接口
+- 构造函数接受可选的 `inital_steps` 参数，用于加载默认工作流
+- `Injection` 是内部事件总线，解耦 server 通信与 UI 状态
+
+### 5.4 事务与 Undo/Redo
+
+Model 提供事务机制：
+- `startTransaction()` 快照当前状态
+- `endTransaction()` 将快照推入 undo 栈
+- Ctrl+Z / Ctrl+Y 触发撤销/重做
+- 拖拽、添加节点、删除等操作自动包裹在事务中
+
+## 6. 节点体系
+
+### 6.1 渲染组件
+
+```
+ReactFlow
+  ├─ nodeTypes: { start: NodeStart, end: NodeEnd, role: NodeRole }
+  └─ edgeTypes: { default: GradientEdge, conditional: ConditionalEdge }
+```
+
+`NodeRole` 显示角色名（data.name），使用 teal 色系图标和标签。Handle 分蓝色（in）和绿色（out）两种颜色。
+
+### 6.2 节点编辑
+
+角色节点的编辑器直接内联在 AddNodePanel 和 EditNodePanel 中，可编辑字段：
+- name（必填）
+- description、identity、prepare、execute、report（textarea）
+
+## 7. UI 面板
+
+| 面板 | 位置 | 内容 |
+|------|------|------|
+| Toolbar | 顶部居中 | Undo/Redo、添加角色、自动布局、保存 |
+| AddNodePanel | 右下角 | 角色节点创建表单（name + 6 字段 → 确认） |
+| EditNodePanel | 右下角 | 角色节点编辑表单（预填当前数据 → 确认） |
+
+AddNodePanel 和 EditNodePanel 互斥显示，点击外部自动关闭。
+
+## 8. 自动布局（layout/）
+
+`LayoutLR(nodes, edges)` 算法：
+1. 拓扑排序分层（BFS，start → layer 0，end → max+1）
+2. 按层分组
+3. 计算 X/Y 坐标（水平间距 80px，垂直间距 40px）
+4. 无变化时返回原数组（避免无效重渲染）
+
+## 9. 核心数据流
+
+### 加载工作流
+
+```
+FlowModel.load(steps) / FlowModel(initialSteps)
+  → Injection.emit('load', steps)
+  → handlers.loadSteps()
+  → transIn(steps) → { nodes, edges }
+    （condition: null 的 transition 排序到第一个，成为 else）
+  → nodesModel.set(nodes)
+  → edgesModel.set(edges)
+  → autoLayoutLR()
+  → model.reset()（清空 undo/redo）
+```
+
+### 保存工作流
+
+```
+用户点击 Save
+  → handlers.saveData()
+  → validate(nodes, edges)
+  → 校验失败 → Toast 提示错误
+  → 校验通过 → transOut(nodes, edges) → WorkFlowSteps
+    （第一条 conditional 边序列化为 condition: null）
+  → Injection.emit('save', steps)
+  → FlowModel.emit('save', steps)
+  → 外部消费者（server/CLI）接收
+```
+
+### 连线与条件边升级
+
+```
+用户拖线连接两个节点
+  → edgesModel.onConnect(params)
+  → normalizeConnection（方向纠正）
+  → 校验（自连、重复、handle 类型）
+  → 检查 source 已有出边数量
+  → 已有出边 → 新边 + 已有边全部升级为 conditional
+  → 首条出边 → 创建普通边
+```
+
+### 删除保护
+
+```
+用户选中节点/边按 Delete
+  → handlers.onBeforeDelete({ nodes, edges })
+  → start/end 节点 → 阻止
+  → else 边（有 if 兄弟时）→ 阻止
+  → 其他 → 允许
+```
+
+## 10. 上游数据模型参考
+
+workflow-dashboard 消费的 YAML 工作流最终映射自 `WorkflowPayload`（定义在 workflow-protocol）：
+
+```typescript
+type WorkflowPayload = {
+  name: string;
+  description: string;
+  roles: Record<string, RoleDefinition>;       // 角色定义（4 段式：identity/prepare/execute/report）
+  conditions: Record<string, ConditionDefinition>; // JSONata 条件表达式
+  graph: Record<string, Transition[]>;          // 角色间的转移图
+};
+```
+
+workflow-dashboard 使用 `WorkFlowSteps` 格式作为交换数据，其中 `WorkFlowRole` 的字段与 `RoleDefinition` 对齐（description/identity/prepare/execute/report），`WorkFlowTransition` 对应 graph 中的 `Transition`。外部（CLI/server）负责 `WorkflowPayload` ↔ `WorkFlowSteps` 的转换。
+
+## 11. 当前状态与待完善项
+
+- **WebSocket 集成**: 尚未实现，CLI connect 的 WebSocket 通信待开发
+- **验证**: 图结构校验 + 可达性检测 + else 分支规则已实现
+- **只读模式**: Detail 页面有"编辑/预览"切换按钮，但编辑器尚未实现真正的只读模式（禁止交互）
+
+## 12. 业务系统
+
+### 12.1 路由
+
+| 路由 | 页面 | 文件 |
+|------|------|------|
+| `/` | Home — Workflow 列表 | `src/pages/home.tsx` |
+| `/workflow/:name` | Detail — 预览/编辑 | `src/pages/detail.tsx` |
+
+### 12.2 后端 API
+
+Elysia REST API（`server/api.ts`），通过 Vite 插件（`vite-dev.ts`）集成到 dev server。
+
+| Method | Path | 说明 |
+|--------|------|------|
+| GET | `/api/workflows` | 列出所有 workflow（name + description） |
+| GET | `/api/workflows/:name` | 获取单个 workflow（返回 WorkFlowSteps JSON） |
+| POST | `/api/workflows` | 新建 workflow（body: `{name, description}`） |
+| PUT | `/api/workflows/:name` | 保存 workflow（body: WorkFlowSteps JSON） |
+| DELETE | `/api/workflows/:name` | 删除 workflow |
+
+### 12.3 数据存储
+
+- 存储目录：`tmp/workflow/`，文件名 `{name}.yaml`
+- 存储格式：WorkflowPayload YAML（与上游 workflow-protocol 一致）
+- Server 端负责 WorkflowPayload ↔ WorkFlowSteps 转换（`server/workflow.ts`）
+
+字段映射：
+| WorkFlowRole | RoleDefinition |
+|--------------|---------------|
+| name | roles map key |
+| description | description |
+| identity | goal |
+| prepare | capabilities (join/split by `\n`) |
+| execute | procedure |
+| report | output |
+
+条件映射：WorkFlowTransition.condition 存储表达式字符串，保存时提取为 named conditions map。
+
+### 12.4 shadcn/ui
+
+已初始化 shadcn（`components.json`），使用 `@` 路径别名。已安装组件：
+- button、card、dialog、input、textarea
+- 组件位于 `src/components/ui/`
+
+### 12.5 目录结构更新
+
+```
+workflow-dashboard/
+├── server/
+│   ├── api.ts                # Elysia REST API（health + workflow CRUD）
+│   └── workflow.ts           # Workflow 文件读写 + 格式转换
+├── src/
+│   ├── components/ui/        # shadcn 组件
+│   ├── pages/
+│   │   ├── home.tsx          # Home 列表页
+│   │   └── detail.tsx        # Workflow 详情/编辑页
+│   └── ...
+├── tmp/workflow/             # Workflow YAML 存储目录（开发阶段）
+└── components.json           # shadcn 配置
+```

packages/workflow-dashboard/index.html

@@ -0,0 +1,21 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Workflow UI</title>
+    <link rel="stylesheet" href="./src/index.css" />
+    <script>
+      (function () {
+        var t = localStorage.getItem("theme");
+        if (t === "dark" || (!t && matchMedia("(prefers-color-scheme: dark)").matches)) {
+          document.documentElement.classList.add("dark");
+        }
+      })();
+    </script>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="./src/main.tsx"></script>
+  </body>
+</html>

packages/workflow-dashboard/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@uncaged/workflow-dashboard",
+  "version": "0.5.0-alpha.4",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "bun server.ts",
+    "build": "vite build"
+  },
+  "dependencies": {
+    "@base-ui/react": "^1.5.0",
+    "@fontsource-variable/geist": "^5.2.9",
+    "@uncaged/workflow-protocol": "workspace:*",
+    "@xyflow/react": "^12.10.2",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "elysia": "^1.4.28",
+    "immer": "^11.1.8",
+    "lucide-react": "^1.16.0",
+    "react": "^19.2.6",
+    "react-dom": "^19.2.6",
+    "react-router": "^7.15.1",
+    "shadcn": "^4.8.0",
+    "tailwind-merge": "^3.6.0",
+    "tw-animate-css": "^1.4.0",
+    "yaml": "^2.9.0"
+  },
+  "devDependencies": {
+    "@tailwindcss/vite": "^4.3.0",
+    "@types/bun": "^1.2.14",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^6.0.2",
+    "tailwindcss": "^4.2.4",
+    "typescript": "^5.8.3",
+    "vite": "^8.0.13"
+  }
+}

packages/workflow-dashboard/server.ts

@@ -0,0 +1,12 @@
+import { createServer } from "vite";
+
+const PORT = 3000;
+
+const server = await createServer({
+  server: { port: PORT },
+});
+
+await server.listen();
+
+// biome-ignore lint/nursery/noConsole: CLI user-facing output
+console.log(`Workflow UI running at http://localhost:${PORT}`);

packages/workflow-dashboard/server/api.ts

@@ -0,0 +1,78 @@
+import { Elysia, t } from "elysia";
+import type { WorkFlowSteps } from "../shared/types.ts";
+import {
+  listWorkflows,
+  getWorkflow,
+  createWorkflow,
+  saveWorkflow,
+  deleteWorkflow,
+} from "./workflow.ts";
+
+export function createApi() {
+  return new Elysia({ prefix: "/api" })
+    .get("/health", () => ({ status: "ok" }))
+    .get("/workflows", () => listWorkflows())
+    .get("/workflows/:name", async ({ params }) => {
+      try {
+        const steps = await getWorkflow(params.name);
+        return steps;
+      } catch {
+        return new Response(JSON.stringify({ error: "not found" }), {
+          status: 404,
+          headers: { "Content-Type": "application/json" },
+        });
+      }
+    })
+    .post(
+      "/workflows",
+      async ({ body }) => {
+        await createWorkflow(body.name, body.description);
+        return { ok: true };
+      },
+      {
+        body: t.Object({
+          name: t.String(),
+          description: t.String(),
+        }),
+      },
+    )
+    .put(
+      "/workflows/:name",
+      async ({ params, body }) => {
+        const steps: WorkFlowSteps = typeof body === "string" ? JSON.parse(body) : body;
+        await saveWorkflow(params.name, steps);
+        return { ok: true };
+      },
+      {
+        body: t.Array(
+          t.Object({
+            role: t.Object({
+              name: t.String(),
+              description: t.String(),
+              identity: t.String(),
+              prepare: t.String(),
+              execute: t.String(),
+              report: t.String(),
+            }),
+            transitions: t.Array(
+              t.Object({
+                target: t.String(),
+                condition: t.Union([t.String(), t.Null()]),
+              }),
+            ),
+          }),
+        ),
+      },
+    )
+    .delete("/workflows/:name", async ({ params }) => {
+      try {
+        await deleteWorkflow(params.name);
+        return { ok: true };
+      } catch {
+        return new Response(JSON.stringify({ error: "not found" }), {
+          status: 404,
+          headers: { "Content-Type": "application/json" },
+        });
+      }
+    });
+}

packages/workflow-dashboard/server/workflow.ts

@@ -0,0 +1,154 @@
+import { readdir, readFile, writeFile, unlink, mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import YAML from "yaml";
+import type {
+  WorkflowPayload,
+  RoleDefinition,
+  Transition,
+} from "@uncaged/workflow-protocol";
+import type { WorkFlowSteps, WorkFlowTransition, WorkflowSummary } from "../shared/types.ts";
+
+const WORKFLOW_DIR = join(import.meta.dirname, "..", "tmp", "workflow");
+
+async function ensureDir() {
+  await mkdir(WORKFLOW_DIR, { recursive: true });
+}
+
+function payloadToSteps(payload: WorkflowPayload): WorkFlowSteps {
+  const conditionMap = new Map<string, string>();
+  for (const [name, def] of Object.entries(payload.conditions)) {
+    conditionMap.set(name, def.expression);
+  }
+
+  const steps: WorkFlowSteps = [];
+  for (const [roleName, roleDef] of Object.entries(payload.roles)) {
+    const graphTransitions = payload.graph[roleName] ?? [];
+    const transitions: WorkFlowTransition[] = graphTransitions.map((t) => ({
+      target: t.role === "$END" ? "END" : t.role,
+      condition: t.condition ? (conditionMap.get(t.condition) ?? t.condition) : null,
+    }));
+
+    steps.push({
+      role: {
+        name: roleName,
+        description: roleDef.description,
+        identity: roleDef.goal,
+        prepare: roleDef.capabilities.join("\n"),
+        execute: roleDef.procedure,
+        report: roleDef.output,
+      },
+      transitions,
+    });
+  }
+
+  return steps;
+}
+
+function stepsToPayload(name: string, description: string, steps: WorkFlowSteps): WorkflowPayload {
+  const roles: Record<string, RoleDefinition> = {};
+  const conditions: WorkflowPayload["conditions"] = {};
+  const graph: Record<string, Transition[]> = {};
+
+  const expressionToName = new Map<string, string>();
+  let condIdx = 0;
+
+  for (const step of steps) {
+    const r = step.role;
+    roles[r.name] = {
+      description: r.description,
+      goal: r.identity,
+      capabilities: r.prepare ? r.prepare.split("\n").filter(Boolean) : [],
+      procedure: r.execute,
+      output: r.report,
+      frontmatter: "",
+    };
+
+    const transitions: Transition[] = step.transitions.map((t) => {
+      let condName: string | null = null;
+      if (t.condition) {
+        if (expressionToName.has(t.condition)) {
+          condName = expressionToName.get(t.condition)!;
+        } else {
+          condName = `cond${condIdx++}`;
+          expressionToName.set(t.condition, condName);
+          conditions[condName] = {
+            description: "",
+            expression: t.condition,
+          };
+        }
+      }
+      const targetRole = t.target === "END" ? "$END" : t.target;
+      return {
+        role: targetRole,
+        condition: condName,
+        prompt: `Transition to ${targetRole}.`,
+      };
+    });
+
+    graph[r.name] = transitions;
+  }
+
+  if (steps.length > 0) {
+    const firstRole = steps[0].role.name;
+    graph["$START"] = [
+      {
+        role: firstRole,
+        condition: null,
+        prompt: `Begin workflow at role ${firstRole}.`,
+      },
+    ];
+  }
+
+  return { name, description, roles, conditions, graph };
+}
+
+export async function listWorkflows(): Promise<WorkflowSummary[]> {
+  await ensureDir();
+  const files = await readdir(WORKFLOW_DIR);
+  const results: WorkflowSummary[] = [];
+
+  for (const file of files) {
+    if (!file.endsWith(".yaml")) continue;
+    const content = await readFile(join(WORKFLOW_DIR, file), "utf-8");
+    const payload = YAML.parse(content) as WorkflowPayload;
+    results.push({ name: payload.name, description: payload.description });
+  }
+
+  return results;
+}
+
+export async function getWorkflow(name: string): Promise<WorkFlowSteps> {
+  const content = await readFile(join(WORKFLOW_DIR, `${name}.yaml`), "utf-8");
+  const payload = YAML.parse(content) as WorkflowPayload;
+  return payloadToSteps(payload);
+}
+
+export async function createWorkflow(name: string, description: string): Promise<void> {
+  await ensureDir();
+  const payload: WorkflowPayload = {
+    name,
+    description,
+    roles: {},
+    conditions: {},
+    graph: {},
+  };
+  await writeFile(join(WORKFLOW_DIR, `${name}.yaml`), YAML.stringify(payload), "utf-8");
+}
+
+export async function saveWorkflow(name: string, steps: WorkFlowSteps): Promise<void> {
+  const filePath = join(WORKFLOW_DIR, `${name}.yaml`);
+  let description = "";
+  try {
+    const existing = await readFile(filePath, "utf-8");
+    const existingPayload = YAML.parse(existing) as WorkflowPayload;
+    description = existingPayload.description;
+  } catch {
+    // file doesn't exist, use empty description
+  }
+  const payload = stepsToPayload(name, description, steps);
+  await writeFile(filePath, YAML.stringify(payload), "utf-8");
+}
+
+export async function deleteWorkflow(name: string): Promise<void> {
+  await unlink(join(WORKFLOW_DIR, `${name}.yaml`));
+}

packages/workflow-dashboard/shared/types.ts

@@ -0,0 +1,25 @@
+export type WorkFlowRole = {
+  name: string;
+  description: string;
+  identity: string;
+  prepare: string;
+  execute: string;
+  report: string;
+};
+
+export type WorkFlowTransition = {
+  target: string;
+  condition: string | null;
+};
+
+export type WorkFlowStep = {
+  role: WorkFlowRole;
+  transitions: WorkFlowTransition[];
+};
+
+export type WorkFlowSteps = WorkFlowStep[];
+
+export type WorkflowSummary = {
+  name: string;
+  description: string;
+};

packages/workflow-dashboard/src/app.tsx

@@ -0,0 +1,10 @@
+import type { ReactNode } from "react";
+import { Outlet } from "react-router";
+
+export function Layout(): ReactNode {
+  return (
+    <div className="h-screen w-screen bg-background text-foreground">
+      <Outlet />
+    </div>
+  );
+}