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

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

Closes #355

.gitignore

@@ -9,3 +9,5 @@ bunfig.toml
 xiaoju/
 solve-issue-entry.ts
 packages/workflow-template-develop/develop.esm.js
+.DS_Store
+*.py

docs/architecture.md

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

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

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

packages/cli-uwf/package.json

@@ -11,8 +11,8 @@
     "uwf": "./src/cli.ts"
   },
   "dependencies": {
-    "@uncaged/json-cas": "^0.1.3",
-    "@uncaged/json-cas-fs": "^0.1.2",
+    "@uncaged/json-cas": "^0.3.0",
+    "@uncaged/json-cas-fs": "^0.3.0",
     "@uncaged/uwf-agent-kit": "workspace:^",
     "@uncaged/uwf-moderator": "workspace:^",
     "@uncaged/uwf-protocol": "workspace:^",

packages/cli-uwf/src/cli.ts

@@ -1,30 +1,37 @@
 #!/usr/bin/env bun
 
 import { Command } from "commander";
+import type { ThreadId } from "@uncaged/uwf-protocol";
 
 import {
+  cmdThreadFork,
   cmdThreadKill,
   cmdThreadList,
+  cmdThreadRead,
+  THREAD_READ_DEFAULT_QUOTA,
   cmdThreadShow,
   cmdThreadStart,
   cmdThreadStep,
+  cmdThreadSteps,
 } from "./commands/thread.js";
 import { cmdWorkflowList, cmdWorkflowPut, cmdWorkflowShow } from "./commands/workflow.js";
 import { cmdSetup, cmdSetupInteractive } from "./commands/setup.js";
 import {
-  cmdCasCat,
   cmdCasGet,
   cmdCasHas,
   cmdCasPut,
+  cmdCasReindex,
   cmdCasRefs,
   cmdCasSchemaGet,
   cmdCasSchemaList,
   cmdCasWalk,
 } from "./commands/cas.js";
 import { resolveStorageRoot } from "./store.js";
+import { type OutputFormat, formatOutput } from "./format.js";
 
-function writeJson(data: unknown): void {
-  process.stdout.write(`${JSON.stringify(data)}\n`);
+function writeOutput(data: unknown): void {
+  const fmt = program.opts().format as OutputFormat;
+  process.stdout.write(`${formatOutput(data, fmt)}\n`);
 }
 
 function runAction(action: () => Promise<void>): void {
@@ -38,6 +45,7 @@ function runAction(action: () => Promise<void>): void {
 const program = new Command();
 
 program.name("uwf").description("Stateless workflow CLI");
+program.option("--format <fmt>", "Output format: json or yaml", "json");
 
 const workflow = program.command("workflow").description("Workflow registry and CAS");
 
@@ -49,7 +57,7 @@ workflow
     const storageRoot = resolveStorageRoot();
     runAction(async () => {
       const result = await cmdWorkflowPut(storageRoot, file);
-      writeJson(result);
+      writeOutput(result);
     });
   });
 
@@ -61,7 +69,7 @@ workflow
     const storageRoot = resolveStorageRoot();
     runAction(async () => {
       const result = await cmdWorkflowShow(storageRoot, id);
-      writeJson(result);
+      writeOutput(result);
     });
   });
 
@@ -72,7 +80,7 @@ workflow
     const storageRoot = resolveStorageRoot();
     runAction(async () => {
       const result = await cmdWorkflowList(storageRoot);
-      writeJson(result);
+      writeOutput(result);
     });
   });
 
@@ -87,7 +95,7 @@ thread
     const storageRoot = resolveStorageRoot();
     runAction(async () => {
       const result = await cmdThreadStart(storageRoot, workflow, opts.prompt);
-      writeJson(result);
+      writeOutput(result);
     });
   });
 
@@ -101,7 +109,7 @@ thread
     runAction(async () => {
       const agentOverride = opts.agent ?? null;
       const result = await cmdThreadStep(storageRoot, threadId, agentOverride);
-      writeJson(result);
+      writeOutput(result);
     });
   });
 
@@ -113,7 +121,7 @@ thread
     const storageRoot = resolveStorageRoot();
     runAction(async () => {
       const result = await cmdThreadShow(storageRoot, threadId);
-      writeJson(result);
+      writeOutput(result);
     });
   });
 
@@ -125,7 +133,7 @@ thread
     const storageRoot = resolveStorageRoot();
     runAction(async () => {
       const result = await cmdThreadList(storageRoot, opts.all);
-      writeJson(result);
+      writeOutput(result);
     });
   });
 
@@ -137,7 +145,53 @@ thread
     const storageRoot = resolveStorageRoot();
     runAction(async () => {
       const result = await cmdThreadKill(storageRoot, threadId);
-      writeJson(result);
+      writeOutput(result);
+    });
+  });
+
+thread
+  .command("steps")
+  .description("List all steps in a thread")
+  .argument("<thread-id>", "Thread ULID")
+  .action((threadId: string) => {
+    const storageRoot = resolveStorageRoot();
+    runAction(async () => {
+      const result = await cmdThreadSteps(storageRoot, threadId);
+      writeOutput(result);
+    });
+  });
+
+thread
+  .command("read")
+  .description("Read thread context as human-readable markdown")
+  .argument("<thread-id>", "Thread ULID")
+  .option("--quota <chars>", "Max output characters", String(THREAD_READ_DEFAULT_QUOTA))
+  .option("--before <step-hash>", "Load steps before this hash (exclusive)")
+  .option("--start", "Include start step in output")
+  .option("--detail", "Expand detail content for each step")
+  .action((threadId: string, opts: { quota: string; before: string | undefined; start: boolean; detail: boolean }) => {
+    const storageRoot = resolveStorageRoot();
+    runAction(async () => {
+      const quota = Number.parseInt(opts.quota, 10);
+      if (!Number.isFinite(quota) || quota < 1) {
+        process.stderr.write("invalid --quota: must be a positive integer\n");
+        process.exit(1);
+      }
+      const before = opts.before ?? null;
+      const markdown = await cmdThreadRead(storageRoot, threadId as ThreadId, quota, before, opts.start ?? false, opts.detail ?? false);
+      process.stdout.write(markdown.endsWith("\n") ? markdown : `${markdown}\n`);
+    });
+  });
+
+thread
+  .command("fork")
+  .description("Fork a thread from a specific step")
+  .argument("<step-hash>", "CAS hash of the StartNode or StepNode to fork from")
+  .action((stepHash: string) => {
+    const storageRoot = resolveStorageRoot();
+    runAction(async () => {
+      const result = await cmdThreadFork(storageRoot, stepHash);
+      writeOutput(result);
     });
   });
 
@@ -167,7 +221,7 @@ program
           agent: opts.agent ?? undefined,
           storageRoot,
         });
-        writeJson(result);
+        writeOutput(result);
       } else if (!opts.provider && !opts.baseUrl && !opts.apiKey && !opts.model) {
         await cmdSetupInteractive(storageRoot);
       } else {
@@ -182,23 +236,14 @@ const cas = program.command("cas").description("Content-addressable storage oper
 
 cas
   .command("get")
-  .description("Read a CAS node as JSON")
+  .description("Read a CAS node (type + payload; use --timestamp to include timestamp)")
   .argument("<hash>", "CAS hash (13 char)")
-  .option("--json", "Compact JSON output")
-  .action((hash: string, opts: { json?: boolean }) => {
+  .option("--timestamp", "Include timestamp in output")
+  .action((hash: string, opts: { timestamp?: boolean }) => {
     const storageRoot = resolveStorageRoot();
-    runAction(() => cmdCasGet(storageRoot, hash, opts));
-  });
-
-cas
-  .command("cat")
-  .description("Output a CAS node (--payload for payload only)")
-  .argument("<hash>", "CAS hash (13 char)")
-  .option("--payload", "Output only the payload")
-  .option("--json", "Compact JSON output")
-  .action((hash: string, opts: { payload?: boolean; json?: boolean }) => {
-    const storageRoot = resolveStorageRoot();
-    runAction(() => cmdCasCat(storageRoot, hash, opts));
+    runAction(async () => {
+      writeOutput(await cmdCasGet(storageRoot, hash, opts));
+    });
   });
 
 cas
@@ -206,19 +251,22 @@ cas
   .description("Store a node, print its hash")
   .argument("<type-hash>", "Type (schema) hash")
   .argument("<data>", "JSON file path or inline JSON string")
-  .option("--json", "Compact JSON output")
-  .action((typeHash: string, data: string, opts: { json?: boolean }) => {
+  .action((typeHash: string, data: string) => {
     const storageRoot = resolveStorageRoot();
-    runAction(() => cmdCasPut(storageRoot, typeHash, data, opts));
+    runAction(async () => {
+      writeOutput(await cmdCasPut(storageRoot, typeHash, data));
+    });
   });
 
 cas
   .command("has")
-  .description("Check if a hash exists (prints true/false)")
+  .description("Check if a hash exists")
   .argument("<hash>", "CAS hash (13 char)")
   .action((hash: string) => {
     const storageRoot = resolveStorageRoot();
-    runAction(() => cmdCasHas(storageRoot, hash));
+    runAction(async () => {
+      writeOutput(await cmdCasHas(storageRoot, hash));
+    });
   });
 
 cas
@@ -227,37 +275,53 @@ cas
   .argument("<hash>", "CAS hash (13 char)")
   .action((hash: string) => {
     const storageRoot = resolveStorageRoot();
-    runAction(() => cmdCasRefs(storageRoot, hash));
+    runAction(async () => {
+      writeOutput(await cmdCasRefs(storageRoot, hash));
+    });
   });
 
 cas
   .command("walk")
   .description("Recursive traversal from a node")
   .argument("<hash>", "CAS hash (13 char)")
-  .option("--format <fmt>", "Output format: flat (default) or tree")
-  .action((hash: string, opts: { format?: string }) => {
+  .action((hash: string) => {
     const storageRoot = resolveStorageRoot();
-    runAction(() => cmdCasWalk(storageRoot, hash, opts));
+    runAction(async () => {
+      writeOutput(await cmdCasWalk(storageRoot, hash));
+    });
+  });
+
+cas
+  .command("reindex")
+  .description("Rebuild type index from all CAS nodes")
+  .action(() => {
+    const storageRoot = resolveStorageRoot();
+    runAction(async () => {
+      writeOutput(await cmdCasReindex(storageRoot));
+    });
   });
 
 const casSchema = cas.command("schema").description("CAS schema operations");
 
 casSchema
   .command("list")
-  .description("List all registered schemas (hash + name)")
+  .description("List all registered schemas")
   .action(() => {
     const storageRoot = resolveStorageRoot();
-    runAction(() => cmdCasSchemaList(storageRoot));
+    runAction(async () => {
+      writeOutput(await cmdCasSchemaList(storageRoot));
+    });
   });
 
 casSchema
   .command("get")
   .description("Show a schema by its type hash")
   .argument("<hash>", "Schema type hash")
-  .option("--json", "Compact JSON output")
-  .action((hash: string, opts: { json?: boolean }) => {
+  .action((hash: string) => {
     const storageRoot = resolveStorageRoot();
-    runAction(() => cmdCasSchemaGet(storageRoot, hash, opts));
+    runAction(async () => {
+      writeOutput(await cmdCasSchemaGet(storageRoot, hash));
+    });
   });
 
 program.parseAsync(process.argv).catch((e: unknown) => {

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

@@ -11,12 +11,7 @@ function openStore(storageRoot: string): Store {
   return createFsStore(join(storageRoot, "cas"));
 }
 
-function out(data: unknown, compact = false): void {
-  console.log(compact ? JSON.stringify(data) : JSON.stringify(data, null, 2));
-}
-
 function readJsonArg(fileOrInline: string): unknown {
-  // Try as inline JSON first, then as file path
   try {
     return JSON.parse(fileOrInline);
   } catch {
@@ -28,138 +23,117 @@ function readJsonArg(fileOrInline: string): unknown {
   }
 }
 
-// ---- Commands ----
+// ---- Commands (all return JSON-serializable data) ----
 
 export async function cmdCasGet(
   storageRoot: string,
   hash: string,
-  opts: { json?: boolean },
-): Promise<void> {
+  opts: { timestamp?: boolean },
+): Promise<unknown> {
   const store = openStore(storageRoot);
   const node = store.get(hash);
   if (node === null) {
     throw new Error(`Node not found: ${hash}`);
   }
-  out(node, opts.json);
-}
-
-export async function cmdCasCat(
-  storageRoot: string,
-  hash: string,
-  opts: { payload?: boolean; json?: boolean },
-): Promise<void> {
-  const store = openStore(storageRoot);
-  const node = store.get(hash);
-  if (node === null) {
-    throw new Error(`Node not found: ${hash}`);
+  if (opts.timestamp) {
+    return node;
   }
-  out(opts.payload ? node.payload : node, opts.json);
+  const { timestamp: _, ...rest } = node as Record<string, unknown>;
+  return rest;
 }
 
 export async function cmdCasPut(
   storageRoot: string,
   typeHash: string,
   data: string,
-  opts: { json?: boolean },
-): Promise<void> {
+): Promise<{ hash: string }> {
   const store = openStore(storageRoot);
   const payload = readJsonArg(data);
-  const hash = store.put(typeHash, payload);
-  console.log(hash);
+  const hash = await store.put(typeHash, payload);
+  return { hash };
 }
 
 export async function cmdCasHas(
   storageRoot: string,
   hash: string,
-): Promise<void> {
+): Promise<{ exists: boolean }> {
   const store = openStore(storageRoot);
-  console.log(String(store.has(hash)));
+  return { exists: store.has(hash) };
 }
 
-export async function cmdCasList(storageRoot: string): Promise<void> {
-  const store = openStore(storageRoot);
-  for (const hash of store.list()) {
-    console.log(hash);
-  }
-}
-
-export async function cmdCasRefs(storageRoot: string, hash: string): Promise<void> {
+export async function cmdCasRefs(
+  storageRoot: string,
+  hash: string,
+): Promise<{ refs: string[] }> {
   const store = openStore(storageRoot);
   const node = store.get(hash);
   if (node === null) {
     throw new Error(`Node not found: ${hash}`);
   }
-  const refHashes = refs(store, node);
-  for (const r of refHashes) {
-    console.log(r);
-  }
+  return { refs: refs(store, node) };
 }
 
 export async function cmdCasWalk(
   storageRoot: string,
   hash: string,
-  opts: { format?: string },
-): Promise<void> {
+): Promise<{ hashes: string[] }> {
   const store = openStore(storageRoot);
-
-  if (opts.format === "tree") {
-    const childMap = new Map<Hash, Hash[]>();
-    walk(store, hash, (h, node) => {
-      childMap.set(h, refs(store, node));
-    });
-
-    const printed = new Set<Hash>();
-
-    function printNode(h: Hash, prefix: string, isLast: boolean): void {
-      const connector = prefix === "" ? "" : isLast ? "└── " : "├── ";
-      if (printed.has(h)) {
-        console.log(`${prefix}${connector}${h} (seen)`);
-        return;
-      }
-      printed.add(h);
-      console.log(`${prefix}${connector}${h}`);
-
-      const kids = childMap.get(h) ?? [];
-      const childPrefix = prefix === "" ? "" : prefix + (isLast ? "    " : "│   ");
-      for (let i = 0; i < kids.length; i++) {
-        printNode(kids[i] as Hash, childPrefix, i === kids.length - 1);
-      }
-    }
-
-    printNode(hash, "", true);
-  } else {
-    walk(store, hash, (h) => {
-      console.log(h);
-    });
-  }
+  const result: string[] = [];
+  walk(store, hash, (h) => {
+    result.push(h);
+  });
+  return { hashes: result };
 }
 
-export async function cmdCasSchemaList(storageRoot: string): Promise<void> {
+export type SchemaListEntry = {
+  hash: string;
+  title: string;
+};
+
+export async function cmdCasSchemaList(
+  storageRoot: string,
+): Promise<SchemaListEntry[]> {
   const store = openStore(storageRoot);
   const metaHash = await bootstrap(store);
-  for (const hash of store.list()) {
+  const entries: SchemaListEntry[] = [];
+
+  // Include meta-schema itself
+  entries.push({ hash: metaHash, title: "(meta-schema)" });
+
+  for (const hash of store.listByType(metaHash)) {
     if (hash === metaHash) continue;
     const node = store.get(hash);
-    if (node !== null && node.type === metaHash) {
+    if (node !== null) {
       const schema = node.payload as JSONSchema;
-      const name =
+      const title =
         (schema.title as string | undefined) ??
         (schema.description as string | undefined) ??
         "(unnamed)";
-      console.log(`${hash}  ${name}`);
+      entries.push({ hash, title });
     }
   }
+  return entries;
+}
+
+export async function cmdCasReindex(
+  storageRoot: string,
+): Promise<{ status: string }> {
+  const indexDir = join(storageRoot, "cas", "_index");
+  const { rmSync } = await import("node:fs");
+  rmSync(indexDir, { recursive: true, force: true });
+  // Re-open store to trigger migration rebuild
+  openStore(storageRoot);
+  return { status: "reindexed" };
 }
 
 export async function cmdCasSchemaGet(
   storageRoot: string,
   hash: string,
-  opts: { json?: boolean },
-): Promise<void> {
+): Promise<unknown> {
   const store = openStore(storageRoot);
   const schema = getSchema(store, hash);
   if (schema === null) {
     throw new Error(`Schema not found: ${hash}`);
   }
-  out(schema, opts.json);
+  return schema;
 }

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

@@ -1,6 +1,8 @@
 import { execFileSync } from "node:child_process";
 
-import { validate } from "@uncaged/json-cas";
+import { getSchema, validate } from "@uncaged/json-cas";
+import type { JSONSchema, Store as CasStore } from "@uncaged/json-cas";
+import { stringify } from "yaml";
 import { getEnvPath, loadWorkflowConfig } from "@uncaged/uwf-agent-kit";
 import { evaluate } from "@uncaged/uwf-moderator";
 import type {
@@ -8,13 +10,17 @@ import type {
   AgentConfig,
   CasRef,
   ModeratorContext,
+  StartEntry,
   StartNodePayload,
   StartOutput,
   StepContext,
+  StepEntry,
   StepNodePayload,
   StepOutput,
+  ThreadForkOutput,
   ThreadId,
   ThreadListItem,
+  ThreadStepsOutput,
   WorkflowConfig,
   WorkflowPayload,
 } from "@uncaged/uwf-protocol";
@@ -36,6 +42,7 @@ import {
 import { isCasRef } from "../validate.js";
 
 const END_ROLE = "$END";
+export const THREAD_READ_DEFAULT_QUOTA = 4000;
 
 type ChainState = {
   startHash: CasRef;
@@ -44,6 +51,12 @@ type ChainState = {
   headIsStart: boolean;
 };
 
+type OrderedStepItem = {
+  hash: CasRef;
+  payload: StepNodePayload;
+  timestamp: number;
+};
+
 export type KillOutput = {
   thread: ThreadId;
   archived: boolean;
@@ -262,6 +275,215 @@ function expandOutput(uwf: UwfStore, outputRef: CasRef): unknown {
   return node.payload;
 }
 
+/**
+ * Recursively expand all cas_ref fields in a CAS node's payload,
+ * replacing hash strings with the referenced node's expanded payload.
+ */
+function expandDeep(store: CasStore, hash: CasRef, visited?: Set<string>): unknown {
+  const seen = visited ?? new Set<string>();
+  if (seen.has(hash)) return hash; // cycle guard
+  seen.add(hash);
+
+  const node = store.get(hash);
+  if (node === null) return hash;
+
+  const schema = getSchema(store, node.type);
+  if (schema === null) return node.payload;
+
+  return expandValue(store, schema, node.payload, seen);
+}
+
+function expandValue(store: CasStore, schema: JSONSchema, value: unknown, visited: Set<string>): unknown {
+  // If this field is a cas_ref, expand it
+  if (schema.format === "cas_ref") {
+    if (typeof value === "string") {
+      return expandDeep(store, value as CasRef, visited);
+    }
+    return value;
+  }
+
+  // anyOf (nullable refs)
+  if (Array.isArray(schema.anyOf)) {
+    for (const sub of schema.anyOf as JSONSchema[]) {
+      if (sub.format === "cas_ref" && typeof value === "string") {
+        return expandDeep(store, value as CasRef, visited);
+      }
+    }
+    return value;
+  }
+
+  // Array of cas_ref items
+  if (schema.type === "array" && schema.items && Array.isArray(value)) {
+    const itemSchema = schema.items as JSONSchema;
+    return (value as unknown[]).map((item) => expandValue(store, itemSchema, item, visited));
+  }
+
+  // Object with properties
+  if (value !== null && typeof value === "object" && !Array.isArray(value) && schema.properties) {
+    const props = schema.properties as Record<string, JSONSchema>;
+    const obj = value as Record<string, unknown>;
+    const result: Record<string, unknown> = {};
+    for (const [key, val] of Object.entries(obj)) {
+      const propSchema = props[key];
+      result[key] = propSchema ? expandValue(store, propSchema, val, visited) : val;
+    }
+    return result;
+  }
+
+  return value;
+}
+
+function collectOrderedSteps(
+  uwf: UwfStore,
+  headHash: CasRef,
+  chain: ChainState,
+): OrderedStepItem[] {
+  let hash: CasRef | null = headHash;
+  const hashToNode = new Map<string, { payload: StepNodePayload; timestamp: number }>();
+  while (hash !== null) {
+    const node = uwf.store.get(hash);
+    if (node === null || node.type !== uwf.schemas.stepNode) {
+      break;
+    }
+    const payload = node.payload as StepNodePayload;
+    hashToNode.set(hash, { payload, timestamp: node.timestamp });
+    hash = payload.prev;
+  }
+
+  let cur: CasRef | null = chain.headIsStart ? null : headHash;
+  const ordered: OrderedStepItem[] = [];
+  while (cur !== null) {
+    const entry = hashToNode.get(cur);
+    if (entry === undefined) {
+      break;
+    }
+    ordered.push({ hash: cur, ...entry });
+    cur = entry.payload.prev;
+  }
+  ordered.reverse();
+  return ordered;
+}
+
+function formatYaml(value: unknown): string {
+  return stringify(value).trimEnd();
+}
+
+function formatCompactStep(index: number, item: OrderedStepItem, outputYaml: string): string {
+  return [
+    `## Step ${index}: ${item.payload.role}`,
+    "",
+    `- **Hash:** \`${item.hash}\``,
+    `- **Agent:** ${item.payload.agent}`,
+    "",
+    "### Output",
+    "",
+    "```yaml",
+    outputYaml,
+    "```",
+  ].join("\n");
+}
+
+function formatThreadReadMarkdown(options: {
+  threadId: ThreadId;
+  workflowName: string;
+  workflowHash: CasRef;
+  prompt: string;
+  ordered: OrderedStepItem[];
+  uwf: UwfStore;
+  workflow: WorkflowPayload;
+  quota: number;
+  before: CasRef | null;
+  showStart: boolean;
+  showDetail: boolean;
+}): string {
+  const { ordered, uwf, workflow, quota, before, showStart, showDetail } = options;
+
+  // Determine which steps to consider
+  let candidates = ordered;
+  if (before !== null) {
+    const idx = candidates.findIndex((s) => s.hash === before);
+    if (idx === -1) {
+      fail(`step ${before} not found in thread ${options.threadId}`);
+    }
+    candidates = candidates.slice(0, idx);
+  }
+
+  // Walk backward from newest, accumulating chars until quota exceeded
+  const selected: OrderedStepItem[] = [];
+  let totalChars = 0;
+  for (let i = candidates.length - 1; i >= 0; i--) {
+    const item = candidates[i];
+    if (item === undefined) continue;
+    const outputYaml = formatYaml(expandOutput(uwf, item.payload.output));
+    const blockLen = formatCompactStep(i + 1, item, outputYaml).length;
+    selected.unshift(item);
+    totalChars += blockLen;
+    if (totalChars > quota) break;
+  }
+
+  const skippedCount = candidates.length - selected.length;
+  const parts: string[] = [];
+
+  // Start section
+  if (before === null || showStart) {
+    parts.push(
+      [
+        `# Thread \`${options.threadId}\``,
+        "",
+        `**Workflow:** ${options.workflowName} (\`${options.workflowHash}\`)`,
+        "",
+        "## Task",
+        "",
+        options.prompt,
+      ].join("\n"),
+    );
+  }
+
+  // Skip hint
+  if (skippedCount > 0 && selected.length > 0) {
+    const firstSelected = selected[0];
+    if (firstSelected !== undefined) {
+      parts.push(
+        `*(${skippedCount} earlier step${skippedCount > 1 ? "s" : ""}, load with \`uwf thread read ${options.threadId} --before ${firstSelected.hash}\`)*`,
+      );
+    }
+  }
+
+  // Step blocks
+  const startIndex = candidates.length - selected.length;
+  for (let i = 0; i < selected.length; i++) {
+    const item = selected[i];
+    if (item === undefined) continue;
+    const stepNum = startIndex + i + 1;
+    const outputYaml = formatYaml(expandOutput(uwf, item.payload.output));
+    const ts = new Date(item.timestamp).toISOString().replace("T", " ").replace(/\.\d+Z$/, "");
+    const stepLines = [
+      `## Step ${stepNum}: ${item.payload.role} \`${item.hash}\``,
+      `**Agent:** ${item.payload.agent} | **Time:** ${ts}`,
+    ];
+    const roleDef = workflow.roles[item.payload.role];
+    if (roleDef) {
+      stepLines.push("", "### Prompt", "", roleDef.systemPrompt);
+    }
+    stepLines.push(
+      "",
+      "### Output",
+      "",
+      "```yaml",
+      outputYaml,
+      "```",
+    );
+    if (showDetail && item.payload.detail) {
+      const detailExpanded = expandDeep(uwf.store, item.payload.detail);
+      const detailYaml = formatYaml(detailExpanded);
+      stepLines.push("", "### Detail", "", "```yaml", detailYaml, "```");
+    }
+    parts.push(stepLines.join("\n"));
+  }
+
+  return parts.join("\n\n---\n\n");
+}
+
 function buildModeratorContext(uwf: UwfStore, chain: ChainState): ModeratorContext {
   const chronological = [...chain.stepsNewestFirst].reverse();
   const steps: StepContext[] = chronological.map((step) => ({
@@ -437,6 +659,115 @@ export async function cmdThreadStep(
   };
 }
 
+async function resolveHeadHash(storageRoot: string, threadId: ThreadId): Promise<CasRef> {
+  const index = await loadThreadsIndex(storageRoot);
+  const activeHead = index[threadId];
+  if (activeHead !== undefined) {
+    return activeHead;
+  }
+  const hist = await findThreadInHistory(storageRoot, threadId);
+  if (hist !== null) {
+    return hist.head;
+  }
+  fail(`thread not found: ${threadId}`);
+}
+
+export async function cmdThreadSteps(
+  storageRoot: string,
+  threadId: ThreadId,
+): Promise<ThreadStepsOutput> {
+  const headHash = await resolveHeadHash(storageRoot, threadId);
+  const uwf = await createUwfStore(storageRoot);
+  const chain = walkChain(uwf, headHash);
+
+  const startNode = uwf.store.get(chain.startHash);
+  if (startNode === null) {
+    fail(`StartNode not found: ${chain.startHash}`);
+  }
+
+  const startEntry: StartEntry = {
+    hash: chain.startHash,
+    workflow: chain.start.workflow,
+    prompt: chain.start.prompt,
+    timestamp: startNode.timestamp,
+  };
+
+  const stepEntries: StepEntry[] = [];
+  const ordered = collectOrderedSteps(uwf, headHash, chain);
+
+  for (const item of ordered) {
+    stepEntries.push({
+      hash: item.hash,
+      role: item.payload.role,
+      output: expandOutput(uwf, item.payload.output),
+      detail: item.payload.detail,
+      agent: item.payload.agent,
+      timestamp: item.timestamp,
+    });
+  }
+
+  return {
+    thread: threadId,
+    workflow: chain.start.workflow,
+    steps: [startEntry, ...stepEntries],
+  };
+}
+
+export async function cmdThreadRead(
+  storageRoot: string,
+  threadId: ThreadId,
+  quota: number = THREAD_READ_DEFAULT_QUOTA,
+  before: CasRef | null = null,
+  showStart: boolean = false,
+  showDetail: boolean = false,
+): Promise<string> {
+  const headHash = await resolveHeadHash(storageRoot, threadId);
+  const uwf = await createUwfStore(storageRoot);
+  const chain = walkChain(uwf, headHash);
+  const workflow = loadWorkflowPayload(uwf, chain.start.workflow);
+  const ordered = collectOrderedSteps(uwf, headHash, chain);
+
+  return formatThreadReadMarkdown({
+    threadId,
+    workflowName: workflow.name,
+    workflowHash: chain.start.workflow,
+    prompt: chain.start.prompt,
+    ordered,
+    uwf,
+    workflow,
+    quota,
+    before,
+    showStart,
+    showDetail,
+  });
+}
+
+export async function cmdThreadFork(
+  storageRoot: string,
+  stepHash: CasRef,
+): Promise<ThreadForkOutput> {
+  const uwf = await createUwfStore(storageRoot);
+  const node = uwf.store.get(stepHash);
+  if (node === null) {
+    fail(`CAS node not found: ${stepHash}`);
+  }
+  if (node.type !== uwf.schemas.startNode && node.type !== uwf.schemas.stepNode) {
+    fail(`node ${stepHash} is not a StartNode or StepNode`);
+  }
+
+  const newThreadId = generateUlid(Date.now()) as ThreadId;
+  const index = await loadThreadsIndex(storageRoot);
+  index[newThreadId] = stepHash;
+  await saveThreadsIndex(storageRoot, index);
+
+  return {
+    thread: newThreadId,
+    forkedFrom: {
+      step: stepHash,
+    },
+  };
+}
+
 export async function cmdThreadKill(storageRoot: string, threadId: ThreadId): Promise<KillOutput> {
   const index = await loadThreadsIndex(storageRoot);
   const head = index[threadId];

packages/cli-uwf/src/format.ts

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

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

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

packages/uwf-agent-hermes/package.json

@@ -21,6 +21,7 @@
     "test": "bun test"
   },
   "dependencies": {
+    "@uncaged/json-cas": "^0.3.0",
     "@uncaged/uwf-agent-kit": "workspace:^"
   },
   "devDependencies": {

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

@@ -1,18 +1,25 @@
 import { spawn } from "node:child_process";
 
-import { type AgentContext, createAgent } from "@uncaged/uwf-agent-kit";
+import { type AgentContext, type AgentRunResult, createAgent } from "@uncaged/uwf-agent-kit";
+
+import {
+  loadHermesSession,
+  parseSessionIdFromStdout,
+  storeHermesRawOutput,
+  storeHermesSessionDetail,
+} from "./session-detail.js";
 
 const HERMES_COMMAND = "hermes";
 const HERMES_MAX_TURNS = 90;
 
-function buildHistorySummary(history: AgentContext["history"]): string {
-  if (history.length === 0) {
+function buildHistorySummary(steps: AgentContext["steps"]): string {
+  if (steps.length === 0) {
     return "";
   }
 
   const lines: string[] = ["## Previous Steps"];
-  for (let i = 0; i < history.length; i++) {
-    const step = history[i];
+  for (let i = 0; i < steps.length; i++) {
+    const step = steps[i];
     if (step === undefined) {
       continue;
     }
@@ -26,15 +33,17 @@ function buildHistorySummary(history: AgentContext["history"]): string {
 
 /** Assemble system prompt, task, and prior step outputs for Hermes. */
 export function buildHermesPrompt(ctx: AgentContext): string {
-  const parts: string[] = [ctx.systemPrompt, "", "## Task", ctx.prompt];
-  const historyBlock = buildHistorySummary(ctx.history);
+  const roleDef = ctx.workflow.roles[ctx.role];
+  const systemPrompt = roleDef?.systemPrompt ?? "";
+  const parts: string[] = [systemPrompt, "", "## Task", ctx.start.prompt];
+  const historyBlock = buildHistorySummary(ctx.steps);
   if (historyBlock !== "") {
     parts.push("", historyBlock);
   }
   return parts.join("\n");
 }
 
-function spawnHermesChat(prompt: string): Promise<string> {
+function spawnHermesChat(prompt: string): Promise<{ stdout: string; stderr: string }> {
   return new Promise((resolve, reject) => {
     const args = [
       "chat",
@@ -67,7 +76,7 @@ function spawnHermesChat(prompt: string): Promise<string> {
 
     child.on("close", (code) => {
       if (code === 0) {
-        resolve(stdout);
+        resolve({ stdout, stderr });
         return;
       }
       const detail = stderr.trim() !== "" ? ` stderr=${stderr.trim()}` : "";
@@ -76,9 +85,23 @@ function spawnHermesChat(prompt: string): Promise<string> {
   });
 }
 
-async function runHermes(ctx: AgentContext): Promise<string> {
+async function runHermes(ctx: AgentContext): Promise<AgentRunResult> {
   const fullPrompt = buildHermesPrompt(ctx);
-  return spawnHermesChat(fullPrompt);
+  const { stdout, stderr } = await spawnHermesChat(fullPrompt);
+  const { store } = ctx;
+
+  // --quiet mode: session_id may be on stdout or stderr
+  const sessionId = parseSessionIdFromStdout(stderr) ?? parseSessionIdFromStdout(stdout);
+  if (sessionId !== null) {
+    const session = await loadHermesSession(sessionId);
+    if (session !== null) {
+      const { detailHash, output } = await storeHermesSessionDetail(store, session);
+      return { output, detailHash };
+    }
+  }
+
+  const detailHash = await storeHermesRawOutput(store, stdout);
+  return { output: stdout, detailHash };
 }
 
 /** Agent CLI factory: parses argv, runs Hermes, extracts output, writes StepNode. */

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

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

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

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

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

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

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

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

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

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

packages/uwf-agent-kit/package.json

@@ -18,9 +18,10 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@uncaged/json-cas": "^0.1.3",
-    "@uncaged/json-cas-fs": "^0.1.2",
+    "@uncaged/json-cas": "^0.3.0",
+    "@uncaged/json-cas-fs": "^0.3.0",
     "@uncaged/uwf-protocol": "workspace:^",
+    "@uncaged/workflow-util": "workspace:^",
     "dotenv": "^16.6.1",
     "yaml": "^2.8.4"
   },

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

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

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

@@ -1,3 +1,4 @@
+import type { Store } from "@uncaged/json-cas";
 import type {
   CasRef,
   StartNodePayload,
@@ -6,6 +7,7 @@ import type {
   ThreadId,
 } from "@uncaged/uwf-protocol";
 import { createAgentStore, loadThreadsIndex, resolveStorageRoot } from "./storage.js";
+import type { AgentStore } from "./storage.js";
 import type { AgentContext } from "./types.js";
 
 type ChainState = {
@@ -20,8 +22,8 @@ function fail(message: string): never {
 }
 
 function walkChain(
-  store: Awaited<ReturnType<typeof createAgentStore>>["store"],
-  schemas: Awaited<ReturnType<typeof createAgentStore>>["schemas"],
+  store: Store,
+  schemas: AgentStore["schemas"],
   headHash: CasRef,
 ): ChainState {
   const headNode = store.get(headHash);
@@ -77,7 +79,7 @@ function walkChain(
 }
 
 function expandOutput(
-  store: Awaited<ReturnType<typeof createAgentStore>>["store"],
+  store: Store,
   outputRef: CasRef,
 ): unknown {
   const node = store.get(outputRef);
@@ -88,7 +90,7 @@ function expandOutput(
 }
 
 async function buildHistory(
-  store: Awaited<ReturnType<typeof createAgentStore>>["store"],
+  store: Store,
   stepsNewestFirst: StepNodePayload[],
 ): Promise<StepContext[]> {
   const chronological = [...stepsNewestFirst].reverse();
@@ -105,8 +107,8 @@ async function buildHistory(
 }
 
 async function loadWorkflow(
-  store: Awaited<ReturnType<typeof createAgentStore>>["store"],
-  schemas: Awaited<ReturnType<typeof createAgentStore>>["schemas"],
+  store: Store,
+  schemas: AgentStore["schemas"],
   workflowRef: CasRef,
 ) {
   const node = store.get(workflowRef);
@@ -141,22 +143,23 @@ export async function buildContext(threadId: ThreadId, role: string): Promise<Ag
     fail(`unknown role "${role}" in workflow "${workflow.name}"`);
   }
 
-  const history = await buildHistory(store, chain.stepsNewestFirst);
+  const steps = await buildHistory(store, chain.stepsNewestFirst);
 
   return {
     threadId,
     role,
-    systemPrompt: roleDef.systemPrompt,
-    prompt: chain.start.prompt,
-    history,
+    start: chain.start,
+    steps,
     workflow,
+    store,
+    outputFormatInstruction: "",
   };
 }
 
 export type BuildContextMeta = {
   storageRoot: string;
-  store: Awaited<ReturnType<typeof createAgentStore>>["store"];
-  schemas: Awaited<ReturnType<typeof createAgentStore>>["schemas"];
+  store: Store;
+  schemas: AgentStore["schemas"];
   headHash: CasRef;
   chain: ChainState;
 };
@@ -185,15 +188,16 @@ export async function buildContextWithMeta(
     fail(`unknown role "${role}" in workflow "${workflow.name}"`);
   }
 
-  const history = await buildHistory(store, chain.stepsNewestFirst);
+  const steps = await buildHistory(store, chain.stepsNewestFirst);
 
   return {
     threadId,
     role,
-    systemPrompt: roleDef.systemPrompt,
-    prompt: chain.start.prompt,
-    history,
+    start: chain.start,
+    steps,
     workflow,
+    store,
+    outputFormatInstruction: "",
     meta: { storageRoot, store, schemas, headHash, chain },
   };
 }

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

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

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

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

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

@@ -1,12 +1,14 @@
-import { validate } from "@uncaged/json-cas";
+import { getSchema, validate } from "@uncaged/json-cas";
 import type { CasRef, StepNodePayload, ThreadId } from "@uncaged/uwf-protocol";
 import { config as loadDotenv } from "dotenv";
 
 import { buildContextWithMeta } from "./context.js";
+import { buildOutputFormatInstruction } from "./build-output-format-instruction.js";
 import { extract } from "./extract.js";
+import { tryFrontmatterFastPath } from "./frontmatter.js";
 import type { AgentStore } from "./storage.js";
 import { getEnvPath, loadWorkflowConfig, resolveStorageRoot } from "./storage.js";
-import type { AgentContext, AgentOptions } from "./types.js";
+import type { AgentContext, AgentOptions, AgentRunResult } from "./types.js";
 
 function fail(message: string): never {
   process.stderr.write(`${message}\n`);
@@ -65,7 +67,7 @@ async function writeStepNode(options: {
   return hash;
 }
 
-async function runAgent(options: AgentOptions, ctx: AgentContext): Promise<string> {
+async function runAgent(options: AgentOptions, ctx: AgentContext): Promise<AgentRunResult> {
   return runWithMessage("agent run failed", () => options.run(ctx));
 }
 
@@ -73,7 +75,16 @@ async function extractOutput(
   rawOutput: string,
   outputSchema: CasRef,
   storageRoot: string,
+  ctx: Awaited<ReturnType<typeof buildContextWithMeta>>,
 ): Promise<CasRef> {
+  const fastPath = await runWithMessage("frontmatter fast path", () =>
+    tryFrontmatterFastPath(rawOutput, outputSchema, ctx.meta.store),
+  ).catch(() => null);
+
+  if (fastPath !== null) {
+    return fastPath.outputHash;
+  }
+
   const config = await runWithMessage("failed to load config", () =>
     loadWorkflowConfig(storageRoot),
   );
@@ -85,12 +96,11 @@ async function extractOutput(
 
 async function persistStep(options: {
   ctx: Awaited<ReturnType<typeof buildContextWithMeta>>;
-  rawOutput: string;
   outputHash: CasRef;
+  detailHash: CasRef;
   agentName: string;
 }): Promise<CasRef> {
   const { store, schemas, chain, headHash } = options.ctx.meta;
-  const detailHash = await store.put(null, options.rawOutput);
   return writeStepNode({
     store,
     schemas,
@@ -98,7 +108,7 @@ async function persistStep(options: {
     prevHash: chain.headIsStart ? null : headHash,
     role: options.ctx.role,
     outputHash: options.outputHash,
-    detailHash,
+    detailHash: options.detailHash,
     agentName: options.agentName,
   });
 }
@@ -121,12 +131,17 @@ export function createAgent(options: AgentOptions): () => Promise<void> {
       fail(`unknown role: ${role}`);
     }
 
-    const rawOutput = await runAgent(options, ctx);
-    const outputHash = await extractOutput(rawOutput, roleDef.outputSchema, storageRoot);
+    const outputSchema = getSchema(ctx.meta.store, roleDef.outputSchema);
+    if (outputSchema !== null) {
+      ctx.outputFormatInstruction = buildOutputFormatInstruction(outputSchema);
+    }
+
+    const agentResult = await runAgent(options, ctx);
+    const outputHash = await extractOutput(agentResult.output, roleDef.outputSchema, storageRoot, ctx);
     const stepHash = await persistStep({
       ctx,
-      rawOutput,
       outputHash,
+      detailHash: agentResult.detailHash,
       agentName: agentLabel(options.name),
     });
 

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

@@ -1,10 +1,6 @@
 import type { Hash, Store } from "@uncaged/json-cas";
 import { putSchema } from "@uncaged/json-cas";
-import {
-  START_NODE_SCHEMA,
-  STEP_NODE_SCHEMA,
-  WORKFLOW_SCHEMA,
-} from "@uncaged/uwf-protocol";
+import { START_NODE_SCHEMA, STEP_NODE_SCHEMA, WORKFLOW_SCHEMA } from "@uncaged/uwf-protocol";
 
 export type UwfAgentSchemaHashes = {
   workflow: Hash;

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

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

packages/uwf-protocol/package.json

@@ -15,7 +15,7 @@
     }
   },
   "dependencies": {
-"@uncaged/json-cas-fs": "^0.1.3"
+"@uncaged/json-cas-fs": "^0.3.0"
   },
   "devDependencies": {
     "typescript": "^5.8.3"

packages/uwf-protocol/src/index.ts

@@ -16,14 +16,18 @@ export type {
   RoleDefinition,
   RoleName,
   Scenario,
+  StartEntry,
   StartNodePayload,
   StartOutput,
   StepContext,
+  StepEntry,
   StepNodePayload,
   StepOutput,
   StepRecord,
+  ThreadForkOutput,
   ThreadId,
   ThreadListItem,
+  ThreadStepsOutput,
   ThreadsIndex,
   Transition,
   WorkflowConfig,

packages/uwf-protocol/src/types.ts

@@ -80,6 +80,39 @@ export type StepOutput = {
   done: boolean;
 };
 
+/** uwf thread steps — single step entry */
+export type StepEntry = {
+  hash: CasRef;
+  role: string;
+  output: unknown;
+  detail: CasRef;
+  agent: string;
+  timestamp: number;
+};
+
+/** uwf thread steps — start entry */
+export type StartEntry = {
+  hash: CasRef;
+  workflow: CasRef;
+  prompt: string;
+  timestamp: number;
+};
+
+/** uwf thread steps output */
+export type ThreadStepsOutput = {
+  thread: ThreadId;
+  workflow: CasRef;
+  steps: [StartEntry, ...StepEntry[]];
+};
+
+/** uwf thread fork output */
+export type ThreadForkOutput = {
+  thread: ThreadId;
+  forkedFrom: {
+    step: CasRef;
+  };
+};
+
 /** uwf thread list */
 export type ThreadListItem = {
   thread: ThreadId;

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

packages/workflow-agent-office/package.json

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

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

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

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

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

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

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

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

@@ -0,0 +1,65 @@
+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 type { OfficeAgentConfig } from "./types.js";
+
+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");
+  throw new Error(`office-agent: spawn failed: ${e.message}`);
+}
+
+async function assertFileExists(path: string): Promise<void> {
+  try {
+    await stat(path);
+  } catch {
+    throw new Error(`office-agent: output file not found: ${path}`);
+  }
+}
+
+export async function generateDocument(
+  config: OfficeAgentConfig,
+  threadId: string,
+  prompt: string,
+  spawnCliFn: SpawnCliFn = spawnCli,
+): Promise<{ outputDocx: string; sourceDocx: null }> {
+  const outputDir = join(config.outputDir, threadId);
+  await mkdir(outputDir, { recursive: true });
+  const command = config.command ?? "office-agent";
+  const result = await spawnCliFn(command, ["create", prompt, "-o", "output.docx"], {
+    cwd: outputDir,
+    timeoutMs: config.timeout,
+  });
+  if (!result.ok) throwSpawnError(result.error);
+  const outputDocx = join(outputDir, "output.docx");
+  await assertFileExists(outputDocx);
+  return { outputDocx, sourceDocx: null };
+}
+
+export async function editDocument(
+  config: OfficeAgentConfig,
+  threadId: string,
+  prompt: string,
+  inputDocx: string,
+  spawnCliFn: SpawnCliFn = spawnCli,
+): Promise<{ outputDocx: string; sourceDocx: string }> {
+  const outputDir = join(config.outputDir, threadId);
+  await mkdir(outputDir, { recursive: true });
+  const originalDocx = join(outputDir, "original.docx");
+  const modifiedDocx = join(outputDir, "modified.docx");
+  await copyFile(inputDocx, originalDocx);
+  await copyFile(inputDocx, modifiedDocx);
+  const command = config.command ?? "office-agent";
+  const result = await spawnCliFn(command, ["edit", "modified.docx", prompt], {
+    cwd: outputDir,
+    timeoutMs: config.timeout,
+  });
+  if (!result.ok) throwSpawnError(result.error);
+  await assertFileExists(modifiedDocx);
+  return { outputDocx: modifiedDocx, sourceDocx: originalDocx };
+}

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

@@ -0,0 +1,5 @@
+export type OfficeAgentConfig = {
+  outputDir: string;
+  command: string | null;
+  timeout: number | null;
+};

packages/workflow-agent-office/tsconfig.json

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

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

@@ -0,0 +1,87 @@
+import { describe, expect, test } from "bun:test";
+import { tableToModerator } from "@uncaged/workflow-protocol/moderator-table.js";
+import { validateWorkflowDescriptor } from "@uncaged/workflow-register";
+import { END, type ModeratorContext, type RoleStep, START } from "@uncaged/workflow-runtime";
+import { buildDocumentDescriptor } from "../src/descriptor.js";
+import { documentTable } from "../src/moderator.js";
+import type { DifferMeta, WriterMeta } from "../src/roles/index.js";
+import type { DocumentMeta } from "../src/roles.js";
+
+const documentModerator = tableToModerator(documentTable);
+
+function makeCtx(
+  steps: ModeratorContext<DocumentMeta>["steps"],
+): ModeratorContext<DocumentMeta> {
+  return {
+    threadId: "01TEST000000000000000000TR",
+    depth: 0,
+    bundleHash: "TESTHASH00001",
+    start: { role: START, content: "", meta: {}, timestamp: 0, parentState: null },
+    steps,
+  };
+}
+
+function writerGenerateStep(): RoleStep<DocumentMeta> {
+  return {
+    role: "writer",
+    contentHash: "STUBHASHWRITER001",
+    meta: { mode: "generate", outputDocx: "/out/output.docx", sourceDocx: null } satisfies WriterMeta,
+    refs: [],
+    timestamp: 1,
+  };
+}
+
+function writerEditStep(): RoleStep<DocumentMeta> {
+  return {
+    role: "writer",
+    contentHash: "STUBHASHWRITER002",
+    meta: { mode: "edit", outputDocx: "/out/modified.docx", sourceDocx: "/out/original.docx" } satisfies WriterMeta,
+    refs: [],
+    timestamp: 1,
+  };
+}
+
+function differStep(): RoleStep<DocumentMeta> {
+  return {
+    role: "differ",
+    contentHash: "STUBHASHDIFF001",
+    meta: {
+      sourceDocx: "/out/original.docx",
+      modifiedDocx: "/out/modified.docx",
+      diffDocx: "/out/diff.docx",
+    } satisfies DifferMeta,
+    refs: [],
+    timestamp: 2,
+  };
+}
+
+describe("documentTable", () => {
+  test("START → writer", () => {
+    expect(documentModerator(makeCtx([]))).toBe("writer");
+  });
+
+  test("writer (generate) → END", () => {
+    expect(documentModerator(makeCtx([writerGenerateStep()]))).toBe(END);
+  });
+
+  test("writer (edit) → differ", () => {
+    expect(documentModerator(makeCtx([writerEditStep()]))).toBe("differ");
+  });
+
+  test("differ → END", () => {
+    expect(documentModerator(makeCtx([writerEditStep(), differStep()]))).toBe(END);
+  });
+});
+
+describe("buildDocumentDescriptor", () => {
+  test("descriptor passes validation", () => {
+    const descriptor = buildDocumentDescriptor();
+    expect(() => validateWorkflowDescriptor(descriptor)).not.toThrow();
+  });
+
+  test("descriptor has writer and differ roles", () => {
+    const descriptor = buildDocumentDescriptor();
+    expect(Object.keys(descriptor.roles)).toContain("writer");
+    expect(Object.keys(descriptor.roles)).toContain("differ");
+  });
+});

packages/workflow-template-document/package.json

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

packages/workflow-template-document/src/descriptor.ts

@@ -0,0 +1,11 @@
+import { buildDescriptor } from "@uncaged/workflow-register";
+import { documentTable } from "./moderator.js";
+import { DOCUMENT_WORKFLOW_DESCRIPTION, documentRoles } from "./roles.js";
+
+export function buildDocumentDescriptor() {
+  return buildDescriptor({
+    description: DOCUMENT_WORKFLOW_DESCRIPTION,
+    roles: documentRoles,
+    table: documentTable,
+  });
+}

packages/workflow-template-document/src/index.ts

@@ -0,0 +1,27 @@
+import type { WorkflowDefinition } from "@uncaged/workflow-runtime";
+import { documentTable } from "./moderator.js";
+import { DOCUMENT_WORKFLOW_DESCRIPTION, type DocumentMeta, documentRoles } from "./roles.js";
+
+export { buildDocumentDescriptor } from "./descriptor.js";
+export { documentTable } from "./moderator.js";
+export {
+  type DifferMeta,
+  differMetaSchema,
+  differRole,
+  type WriterMeta,
+  writerMetaSchema,
+  writerRole,
+} from "./roles/index.js";
+export {
+  DOCUMENT_WORKFLOW_DESCRIPTION,
+  type DocumentMeta,
+  type DocumentRoles,
+  documentRoles,
+} from "./roles.js";
+export type { DocumentStartInput } from "./types.js";
+
+export const documentWorkflowDefinition: WorkflowDefinition<DocumentMeta> = {
+  description: DOCUMENT_WORKFLOW_DESCRIPTION,
+  roles: documentRoles,
+  table: documentTable,
+};

packages/workflow-template-document/src/moderator.ts

@@ -0,0 +1,27 @@
+import {
+  END,
+  type ModeratorCondition,
+  type ModeratorTable,
+  START,
+} from "@uncaged/workflow-runtime";
+import type { WriterMeta } from "./roles/writer.js";
+import type { DocumentMeta } from "./roles.js";
+
+const writerIsEditMode: ModeratorCondition<DocumentMeta> = {
+  name: "writerIsEditMode",
+  description: "Writer ran in edit mode and produced a modified document",
+  check: (ctx) => {
+    const writerStep = ctx.steps.find((s) => s.role === "writer");
+    if (writerStep === undefined) return false;
+    return (writerStep.meta as WriterMeta).mode === "edit";
+  },
+};
+
+export const documentTable: ModeratorTable<DocumentMeta> = {
+  [START]: [{ condition: "FALLBACK", role: "writer" }],
+  writer: [
+    { condition: writerIsEditMode, role: "differ" },
+    { condition: "FALLBACK", role: END },
+  ],
+  differ: [{ condition: "FALLBACK", role: END }],
+};

packages/workflow-template-document/src/roles.ts

@@ -0,0 +1,20 @@
+import type { RoleDefinition } from "@uncaged/workflow-runtime";
+import { type DifferMeta, differRole } from "./roles/differ.js";
+import { type WriterMeta, writerRole } from "./roles/writer.js";
+
+export const DOCUMENT_WORKFLOW_DESCRIPTION =
+  "Generates a new Word document from a prompt, or edits an existing one and produces a diff report.";
+
+export type DocumentMeta = {
+  writer: WriterMeta;
+  differ: DifferMeta;
+};
+
+export type DocumentRoles = {
+  [K in keyof DocumentMeta]: RoleDefinition<DocumentMeta[K]>;
+};
+
+export const documentRoles: DocumentRoles = {
+  writer: writerRole,
+  differ: differRole,
+};

packages/workflow-template-document/src/roles/differ.ts

@@ -0,0 +1,16 @@
+import type { RoleDefinition } from "@uncaged/workflow-runtime";
+import * as z from "zod/v4";
+
+export const differMetaSchema = z.object({
+  sourceDocx: z.string(),
+  modifiedDocx: z.string(),
+  diffDocx: z.string(),
+});
+
+export type DifferMeta = z.infer<typeof differMetaSchema>;
+
+export const differRole: RoleDefinition<DifferMeta> = {
+  description: "Produces a Word-format diff report of the writer's changes (edit mode only).",
+  systemPrompt: "",
+  schema: differMetaSchema,
+};

packages/workflow-template-document/src/roles/index.ts

@@ -0,0 +1,4 @@
+export type { DifferMeta } from "./differ.js";
+export { differMetaSchema, differRole } from "./differ.js";
+export type { WriterMeta } from "./writer.js";
+export { writerMetaSchema, writerRole } from "./writer.js";

packages/workflow-template-document/src/roles/writer.ts

@@ -0,0 +1,23 @@
+import type { RoleDefinition } from "@uncaged/workflow-runtime";
+import * as z from "zod/v4";
+
+export const writerMetaSchema = z.discriminatedUnion("mode", [
+  z.object({
+    mode: z.literal("generate"),
+    outputDocx: z.string(),
+    sourceDocx: z.null(),
+  }),
+  z.object({
+    mode: z.literal("edit"),
+    outputDocx: z.string(),
+    sourceDocx: z.string(),
+  }),
+]);
+
+export type WriterMeta = z.infer<typeof writerMetaSchema>;
+
+export const writerRole: RoleDefinition<WriterMeta> = {
+  description: "Generates or modifies a Word document via an external agent.",
+  systemPrompt: "",
+  schema: writerMetaSchema,
+};

packages/workflow-template-document/src/types.ts

@@ -0,0 +1,4 @@
+export type DocumentStartInput = {
+  prompt: string;
+  inputDocx: string | null;
+};

packages/workflow-template-document/tsconfig.json

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

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

@@ -0,0 +1,80 @@
+import { describe, expect, test } from "vitest";
+import * as z from "zod/v4";
+
+import { buildOutputFormatInstruction } from "../src/build-output-format-instruction.js";
+
+describe("buildOutputFormatInstruction", () => {
+  test("always includes the frontmatter example block", () => {
+    const schema = z.object({ status: z.string() });
+    const result = buildOutputFormatInstruction(schema);
+    expect(result).toContain("## Deliverable Format");
+    expect(result).toContain("status:");
+    expect(result).toContain("confidence:");
+    expect(result).toContain("artifacts:");
+    expect(result).toContain("scope:");
+  });
+
+  test("always includes scope reminder", () => {
+    const schema = z.object({ status: z.string() });
+    const result = buildOutputFormatInstruction(schema);
+    expect(result).toContain("Focus exclusively on YOUR role's deliverable");
+    expect(result).toContain("Do not perform actions outside your role's scope");
+  });
+
+  test("lists fields from a flat ZodObject schema", () => {
+    const schema = z.object({
+      title: z.string(),
+      phases: z.array(z.string()),
+      reason: z.union([z.string(), z.null()]),
+    });
+    const result = buildOutputFormatInstruction(schema);
+    expect(result).toContain("`title`");
+    expect(result).toContain("`phases`");
+    expect(result).toContain("`reason`");
+  });
+
+  test("lists union of fields from a discriminated union schema", () => {
+    const schema = z.discriminatedUnion("status", [
+      z.object({ status: z.literal("planned"), phases: z.array(z.string()) }),
+      z.object({ status: z.literal("aborted"), reason: z.string() }),
+    ]);
+    const result = buildOutputFormatInstruction(schema);
+    expect(result).toContain("`status`");
+    expect(result).toContain("`phases`");
+    expect(result).toContain("`reason`");
+  });
+
+  test("lists fields from a plain ZodUnion schema", () => {
+    const schema = z.union([
+      z.object({ kind: z.literal("a"), valueA: z.string() }),
+      z.object({ kind: z.literal("b"), valueB: z.number() }),
+    ]);
+    const result = buildOutputFormatInstruction(schema);
+    expect(result).toContain("`kind`");
+    expect(result).toContain("`valueA`");
+    expect(result).toContain("`valueB`");
+  });
+
+  test("falls back gracefully for a non-object schema (no field list crash)", () => {
+    const schema = z.string();
+    const result = buildOutputFormatInstruction(schema);
+    expect(result).toContain("## Deliverable Format");
+    expect(result).toContain("schema fields will be extracted automatically");
+  });
+
+  test("marks frontmatter as the primary deliverable", () => {
+    const schema = z.object({ done: z.boolean() });
+    const result = buildOutputFormatInstruction(schema);
+    expect(result).toContain("primary deliverable");
+  });
+
+  test("no field is listed more than once for a union with overlapping keys", () => {
+    const schema = z.union([
+      z.object({ status: z.literal("a"), shared: z.string() }),
+      z.object({ status: z.literal("b"), shared: z.string() }),
+    ]);
+    const result = buildOutputFormatInstruction(schema);
+    const matches = [...result.matchAll(/`shared`/g)];
+    expect(matches.length).toBe(1);
+  });
+});

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

@@ -0,0 +1,238 @@
+import { describe, expect, test, vi } from "vitest";
+
+const mock = vi.fn;
+
+import type { CasStore } from "@uncaged/workflow-cas";
+import type { ThreadContext, WorkflowRuntime } from "@uncaged/workflow-runtime";
+import * as z from "zod/v4";
+
+import { createAgentAdapter } from "../src/index.js";
+
+// ── Minimal test fixtures ─────────────────────────────────────────────────────
+
+function makeCtx(): ThreadContext {
+  return {
+    threadId: "01TEST000000000000000000TR",
+    depth: 0,
+    bundleHash: "TESTHASH00001",
+    start: {
+      role: "START" as const,
+      content: "test task",
+      meta: {},
+      timestamp: 1,
+      parentState: null,
+    },
+    steps: [],
+  };
+}
+
+function makeCas(): CasStore & { store: Map<string, string> } {
+  const store = new Map<string, string>();
+  let seq = 0;
+  return {
+    store,
+    async put(content: string) {
+      const hash = `HASH${String(++seq).padStart(9, "0")}`;
+      store.set(hash, content);
+      return hash;
+    },
+    async get(hash: string) {
+      return store.get(hash) ?? null;
+    },
+    async delete(hash: string) {
+      store.delete(hash);
+    },
+    async list() {
+      return [...store.keys()];
+    },
+  };
+}
+
+// ── Frontmatter-compatible schema ─────────────────────────────────────────────
+
+// Schema that maps directly to AgentFrontmatter fields so happy path works.
+const FrontmatterSchema = z.object({
+  status: z.union([
+    z.literal("done"),
+    z.literal("needs_input"),
+    z.literal("in_progress"),
+    z.literal("failed"),
+    z.null(),
+  ]),
+  next: z.union([z.string(), z.null()]),
+  confidence: z.union([z.number(), z.null()]),
+  artifacts: z.array(z.string()),
+  scope: z.union([z.literal("role"), z.literal("thread")]),
+});
+
+type FrontmatterMeta = z.infer<typeof FrontmatterSchema>;
+
+// ── Happy path ────────────────────────────────────────────────────────────────
+
+describe("createAgentAdapter — happy path (valid frontmatter satisfies schema)", () => {
+  test("returns meta from frontmatter without calling runtime.extract", async () => {
+    const cas = makeCas();
+    const extractMock = mock(async () => {
+      throw new Error("runtime.extract must not be called in happy path");
+    });
+    const runtime: WorkflowRuntime = { cas, extract: extractMock as WorkflowRuntime["extract"] };
+
+    const rawOutput = [
+      "---",
+      "status: done",
+      "next: reviewer",
+      "confidence: 0.9",
+      "artifacts: [src/foo.ts]",
+      "scope: role",
+      "---",
+      "",
+      "## Summary",
+      "Work is complete.",
+    ].join("\n");
+
+    const agentFn = mock(async (_ctx: ThreadContext, _opts: null) => rawOutput);
+    const extractOpts = mock(async () => null);
+
+    const adapter = createAgentAdapter<null>(agentFn, extractOpts);
+    const roleFn = adapter<FrontmatterMeta>("test prompt", FrontmatterSchema);
+    const result = await roleFn(makeCtx(), runtime);
+
+    // Meta must come from frontmatter
+    expect(result.meta.status).toBe("done");
+    expect(result.meta.next).toBe("reviewer");
+    expect(result.meta.confidence).toBe(0.9);
+    expect(result.meta.artifacts).toEqual(["src/foo.ts"]);
+    expect(result.meta.scope).toBe("role");
+    expect(result.childThread).toBeNull();
+
+    // LLM extract must NOT have been called
+    expect(extractMock).not.toHaveBeenCalled();
+
+    // CAS should store the body (without frontmatter) as the CAS node payload
+    const storedContent = [...cas.store.values()][0] ?? "";
+    expect(storedContent).toContain("## Summary");
+    expect(storedContent).toContain("Work is complete.");
+    // The frontmatter block itself must not appear in the stored payload
+    expect(storedContent).not.toContain("status: done\n");
+  });
+
+  test("body stored in CAS does not include the frontmatter block", async () => {
+    const cas = makeCas();
+    const runtime: WorkflowRuntime = {
+      cas,
+      extract: mock(async () => {
+        throw new Error("must not be called");
+      }) as WorkflowRuntime["extract"],
+    };
+
+    const rawOutput =
+      "---\nstatus: done\nnext: null\nconfidence: null\nscope: role\n---\n\nThe actual work content here.";
+
+    const adapter = createAgentAdapter<null>(
+      mock(async () => rawOutput),
+      mock(async () => null),
+    );
+    const roleFn = adapter<FrontmatterMeta>("prompt", FrontmatterSchema);
+    await roleFn(makeCtx(), runtime);
+
+    // CAS node wraps content as `payload: <body>`; check the payload contains only body
+    const stored = [...cas.store.values()][0] ?? "";
+    expect(stored).toContain("The actual work content here.");
+    // The frontmatter block must be stripped
+    expect(stored).not.toContain("status: done");
+  });
+});
+
+// ── Fallback path ─────────────────────────────────────────────────────────────
+
+describe("createAgentAdapter — fallback path (no frontmatter)", () => {
+  test("calls runtime.extract when output has no frontmatter block", async () => {
+    const cas = makeCas();
+    const expectedMeta: FrontmatterMeta = {
+      status: "done",
+      next: null,
+      confidence: null,
+      artifacts: [],
+      scope: "role",
+    };
+
+    const extractFn = mock(async (_schema: unknown, _hash: string) => ({
+      meta: expectedMeta as Record<string, unknown>,
+      contentPayload: "plain text output",
+      refs: [],
+    }));
+    const runtime: WorkflowRuntime = { cas, extract: extractFn as WorkflowRuntime["extract"] };
+
+    const rawOutput = "This is plain markdown without any frontmatter.";
+    const adapter = createAgentAdapter<null>(
+      mock(async () => rawOutput),
+      mock(async () => null),
+    );
+    const roleFn = adapter<FrontmatterMeta>("prompt", FrontmatterSchema);
+    const result = await roleFn(makeCtx(), runtime);
+
+    // runtime.extract must have been called once
+    expect(extractFn).toHaveBeenCalledTimes(1);
+    expect(result.meta).toEqual(expectedMeta);
+    expect(result.childThread).toBeNull();
+
+    // CAS should store the full raw output (as CAS node payload)
+    const stored = [...cas.store.values()][0] ?? "";
+    expect(stored).toContain(rawOutput);
+  });
+
+  test("falls back to runtime.extract when frontmatter is structurally invalid", async () => {
+    const cas = makeCas();
+    const expectedMeta: FrontmatterMeta = {
+      status: null,
+      next: null,
+      confidence: null,
+      artifacts: [],
+      scope: "role",
+    };
+    const extractFn = mock(async () => ({
+      meta: expectedMeta as Record<string, unknown>,
+      contentPayload: "",
+      refs: [],
+    }));
+    const runtime: WorkflowRuntime = { cas, extract: extractFn as WorkflowRuntime["extract"] };
+
+    // confidence out of range — validateFrontmatter will reject
+    const rawOutput = "---\nstatus: done\nconfidence: 1.5\nscope: role\n---\n\nBody.";
+    const adapter = createAgentAdapter<null>(
+      mock(async () => rawOutput),
+      mock(async () => null),
+    );
+    const roleFn = adapter<FrontmatterMeta>("prompt", FrontmatterSchema);
+    await roleFn(makeCtx(), runtime);
+
+    expect(extractFn).toHaveBeenCalledTimes(1);
+  });
+
+  test("falls back when frontmatter fields do not satisfy schema", async () => {
+    const cas = makeCas();
+
+    // Schema requires a mandatory non-null string field that frontmatter cannot provide
+    const StrictSchema = z.object({
+      requiredField: z.string(),
+    });
+
+    const extractFn = mock(async () => ({
+      meta: { requiredField: "from-llm" } as Record<string, unknown>,
+      contentPayload: "",
+      refs: [],
+    }));
+    const runtime: WorkflowRuntime = { cas, extract: extractFn as WorkflowRuntime["extract"] };
+
+    const rawOutput = "---\nstatus: done\nscope: role\n---\n\nBody.";
+    const adapter = createAgentAdapter<null>(
+      mock(async () => rawOutput),
+      mock(async () => null),
+    );
+    const roleFn = adapter<{ requiredField: string }>("prompt", StrictSchema);
+    await roleFn(makeCtx(), runtime);
+
+    // frontmatter has no `requiredField`, so schema parse fails → fallback
+    expect(extractFn).toHaveBeenCalledTimes(1);
+  });
+});

packages/workflow-util-agent/package.json

@@ -21,6 +21,7 @@
   "dependencies": {
     "@uncaged/workflow-runtime": "workspace:^",
     "@uncaged/workflow-cas": "workspace:^",
+    "@uncaged/workflow-util": "workspace:^",
     "zod": "^4.0.0"
   },
   "publishConfig": {

packages/workflow-util-agent/src/build-agent-prompt.ts

@@ -3,30 +3,20 @@ import type { AgentContext, ThreadContext } from "@uncaged/workflow-runtime";
 /**
  * Builds a user-message string from thread context: task, previous steps, and tool hints.
  * Does NOT include a system prompt — that is passed separately via the adapter.
+ *
+ * Ordering: Task → Previous Steps → Parent Context → Tools
+ * The "Deliverable" section lives in the system prompt (injected by createAgentAdapter).
  */
 export async function buildThreadInput(ctx: ThreadContext): Promise<string> {
   const lines: string[] = [];
 
-  if (ctx.start.parentState !== null) {
-    lines.push("## Parent Context");
-    lines.push(
-      "This workflow was spawned by a parent workflow. The parent's state at spawn time is available at hash: " +
-        ctx.start.parentState,
-    );
-    lines.push(
-      `Use \`uncaged-workflow cas get ${ctx.start.parentState}\` to inspect the parent's context and trace back through its steps.`,
-    );
-    lines.push("");
-  }
-
+  // 1. Task — what to do
   lines.push("## Task");
   lines.push(ctx.start.content);
 
   const { steps } = ctx;
-  if (steps.length === 0) {
-    return lines.join("\n");
-  }
 
+  // 2. Context — previous steps
   if (steps.length === 1) {
     const s = steps[0];
     lines.push("");
@@ -34,7 +24,7 @@ export async function buildThreadInput(ctx: ThreadContext): Promise<string> {
     lines.push("");
     lines.push(`ContentHash: ${s.contentHash}`);
     lines.push(`Meta: ${JSON.stringify(s.meta)}`);
-  } else {
+  } else if (steps.length > 1) {
     lines.push("");
     lines.push("## Previous Steps");
     for (let i = 0; i < steps.length - 1; i++) {
@@ -51,6 +41,24 @@ export async function buildThreadInput(ctx: ThreadContext): Promise<string> {
     lines.push(`Meta: ${JSON.stringify(last.meta)}`);
   }
 
+  // 3. Parent context — available when this workflow was spawned by another
+  if (ctx.start.parentState !== null) {
+    lines.push("");
+    lines.push("## Parent Context");
+    lines.push(
+      "This workflow was spawned by a parent workflow. The parent's state at spawn time is available at hash: " +
+        ctx.start.parentState,
+    );
+    lines.push(
+      `Use \`uncaged-workflow cas get ${ctx.start.parentState}\` to inspect the parent's context and trace back through its steps.`,
+    );
+  }
+
+  if (steps.length === 0 && ctx.start.parentState === null) {
+    return lines.join("\n");
+  }
+
+  // 4. Tools — available commands
   lines.push("");
   lines.push("## Tools");
   lines.push(

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

@@ -0,0 +1,79 @@
+import type * as z from "zod/v4";
+
+type ZodSchema = z.ZodType;
+
+/**
+ * Extract the top-level field names from a Zod schema.
+ *
+ * Handles:
+ * - ZodObject → its `.shape` keys
+ * - ZodDiscriminatedUnion / ZodUnion → union of all variant shapes
+ *
+ * Returns an empty array for schemas that have no inspectable shape
+ * (e.g. primitives, ZodAny).
+ */
+function extractSchemaFields(schema: ZodSchema): string[] {
+  const def = schema.def as {
+    type: string;
+    shape?: Record<string, ZodSchema>;
+    options?: ZodSchema[];
+  };
+
+  if (def.type === "object" && def.shape !== undefined) {
+    return Object.keys(def.shape);
+  }
+
+  if ((def.type === "discriminated_union" || def.type === "union") && Array.isArray(def.options)) {
+    const fieldSet = new Set<string>();
+    for (const option of def.options) {
+      for (const field of extractSchemaFields(option as ZodSchema)) {
+        fieldSet.add(field);
+      }
+    }
+    return [...fieldSet];
+  }
+
+  return [];
+}
+
+/**
+ * Build a concise output format instruction block for an agent role.
+ *
+ * The instruction describes the expected frontmatter markdown format and lists
+ * the meta fields derived from `schema`. It is injected at the top of the
+ * system prompt so the deliverable format is the first thing the agent sees.
+ *
+ * Focus on YOUR role's deliverable. Do not perform actions outside your role's scope.
+ */
+export function buildOutputFormatInstruction(schema: ZodSchema): string {
+  const fields = extractSchemaFields(schema);
+
+  const fieldList =
+    fields.length > 0
+      ? fields.map((f) => `  - \`${f}\``).join("\n")
+      : "  (schema fields will be extracted automatically)";
+
+  return `## Deliverable Format
+
+Your response MUST begin with a YAML frontmatter block followed by your markdown work:
+
+\`\`\`
+---
+status: done          # done | needs_input | in_progress | failed
+next: <role-name>     # suggested next role, or omit
+confidence: 0.9       # 0.0–1.0, your self-assessed confidence
+artifacts:            # list of file paths or CAS hashes you produced
+  - path/to/file.ts
+scope: role           # role | thread
+---
+
+... your markdown work here ...
+\`\`\`
+
+The frontmatter is the **primary deliverable** — the engine reads it directly.
+Your meta output must satisfy these fields:
+
+${fieldList}
+
+Focus exclusively on YOUR role's deliverable. Do not perform actions outside your role's scope.`;
+}

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

@@ -6,7 +6,15 @@ import type {
   ThreadContext,
   WorkflowRuntime,
 } from "@uncaged/workflow-runtime";
+import {
+  createLogger,
+  parseFrontmatterMarkdown,
+  validateFrontmatter,
+} from "@uncaged/workflow-util";
 import type * as z from "zod/v4";
+import { buildOutputFormatInstruction } from "./build-output-format-instruction.js";
+
+const log = createLogger({ sink: { kind: "stderr" } });
 
 export type ExtractOptionsFn<Opt> = (
   ctx: ThreadContext,
@@ -14,22 +22,82 @@ export type ExtractOptionsFn<Opt> = (
   runtime: WorkflowRuntime,
 ) => Promise<Opt>;
 
+/**
+ * Try to satisfy `schema` from frontmatter fields alone.
+ *
+ * Returns the parsed value on success, or `null` when the frontmatter does not
+ * cover all required fields of the schema.  Never throws.
+ */
+function tryFrontmatterMeta<T>(
+  raw: string,
+  schema: z.ZodType<T>,
+): { meta: T; body: string } | null {
+  const { frontmatter, body } = parseFrontmatterMarkdown(raw);
+
+  if (frontmatter === null) {
+    return null;
+  }
+
+  const validationErrors = validateFrontmatter(frontmatter);
+  if (validationErrors.length > 0) {
+    log(
+      "4KNMR2PX",
+      `frontmatter validation errors: ${validationErrors.map((e) => e.message).join("; ")}`,
+    );
+    return null;
+  }
+
+  // Coerce frontmatter into the plain object shape the schema expects.
+  const candidate: Record<string, unknown> = {
+    status: frontmatter.status,
+    next: frontmatter.next,
+    confidence: frontmatter.confidence,
+    artifacts: frontmatter.artifacts,
+    scope: frontmatter.scope,
+  };
+
+  const result = schema.safeParse(candidate);
+  if (!result.success) {
+    log("7BQST3VW", "frontmatter does not satisfy schema; falling back to extract");
+    return null;
+  }
+
+  return { meta: result.data, body };
+}
+
 /**
  * Bridges {@link AgentFn} to {@link AdapterFn}.
  *
- * 1. extract(ctx, prompt, runtime) → Opt
- * 2. agent(ctx, options) → raw string
- * 3. Store raw string in CAS
- * 4. runtime.extract(schema, contentHash) → typed meta T
+ * Happy path (zero LLM cost):
+ *   1. extract(ctx, prompt, runtime) → Opt
+ *   2. agent(ctx, options) → raw string
+ *   3. Parse raw as frontmatter markdown
+ *   4. If frontmatter is valid AND satisfies `schema` → use as meta directly
+ *      CAS stores the body (without frontmatter block)
+ *
+ * Fallback (safety net):
+ *   4b. Store full raw in CAS
+ *   5b. runtime.extract(schema, contentHash) → typed meta via LLM
  */
 export function createAgentAdapter<Opt>(
   agent: AgentFn<Opt>,
   extract: ExtractOptionsFn<Opt>,
 ): AdapterFn {
   return <T>(prompt: string, schema: z.ZodType<T>) => {
+    const augmentedPrompt = `${buildOutputFormatInstruction(schema)}\n\n${prompt}`;
     return async (ctx: ThreadContext, runtime: WorkflowRuntime): Promise<RoleResult<T>> => {
-      const options = await extract(ctx, prompt, runtime);
+      const options = await extract(ctx, augmentedPrompt, runtime);
       const raw = await agent(ctx, options);
+
+      const frontmatterResult = tryFrontmatterMeta(raw, schema);
+
+      if (frontmatterResult !== null) {
+        log("3VXPW8QR", "frontmatter satisfied schema — skipping LLM extract");
+        await putContentNodeWithRefs(runtime.cas, frontmatterResult.body, []);
+        return { meta: frontmatterResult.meta, childThread: null };
+      }
+
+      log("8MTNJ5YK", "no valid frontmatter — falling back to runtime.extract");
       const contentHash = await putContentNodeWithRefs(runtime.cas, raw, []);
       const extracted = await runtime.extract(
         schema as z.ZodType<Record<string, unknown>>,

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

@@ -1,4 +1,5 @@
 export { buildAgentPrompt, buildThreadInput } from "./build-agent-prompt.js";
+export { buildOutputFormatInstruction } from "./build-output-format-instruction.js";
 export { createAgentAdapter } from "./create-agent-adapter.js";
 export type { SpawnCliError } from "./spawn-cli.js";
 export { spawnCli } from "./spawn-cli.js";

packages/workflow-util/__tests__/frontmatter-markdown.test.ts

@@ -0,0 +1,343 @@
+import { describe, expect, it } from "vitest";
+import type { AgentFrontmatter } from "../src/index.js";
+import { parseFrontmatterMarkdown, validateFrontmatter } from "../src/index.js";
+
+// ── parseFrontmatterMarkdown ─────────────────────────────────────────────────
+
+describe("parseFrontmatterMarkdown", () => {
+  describe("no frontmatter", () => {
+    it("returns null frontmatter and full text as body when no fence", () => {
+      const raw = "Just some markdown text.\n\n## Section\n\nContent.";
+      const result = parseFrontmatterMarkdown(raw);
+      expect(result.frontmatter).toBeNull();
+      expect(result.body).toBe(raw);
+    });
+
+    it("returns null frontmatter when --- appears mid-document", () => {
+      const raw = "# Heading\n\n---\n\nContent.";
+      const result = parseFrontmatterMarkdown(raw);
+      expect(result.frontmatter).toBeNull();
+      expect(result.body).toBe(raw);
+    });
+
+    it("returns null frontmatter when opening fence is not followed by newline", () => {
+      const raw = "--- inline content ---\nbody";
+      const result = parseFrontmatterMarkdown(raw);
+      expect(result.frontmatter).toBeNull();
+      expect(result.body).toBe(raw);
+    });
+
+    it("returns null frontmatter when no closing fence", () => {
+      const raw = "---\nstatus: done\nbody without close";
+      const result = parseFrontmatterMarkdown(raw);
+      expect(result.frontmatter).toBeNull();
+      expect(result.body).toBe(raw);
+    });
+
+    it("handles empty string", () => {
+      const result = parseFrontmatterMarkdown("");
+      expect(result.frontmatter).toBeNull();
+      expect(result.body).toBe("");
+    });
+  });
+
+  describe("full frontmatter document", () => {
+    it("parses all fields from a well-formed document", () => {
+      const raw = `---
+status: done
+next: reviewer
+confidence: 0.9
+artifacts:
+  - src/foo.ts
+  - src/bar.ts
+scope: thread
+---
+
+## Summary
+
+Everything looks good.`;
+
+      const result = parseFrontmatterMarkdown(raw);
+      expect(result.frontmatter).not.toBeNull();
+      const fm = result.frontmatter!;
+      expect(fm.status).toBe("done");
+      expect(fm.next).toBe("reviewer");
+      expect(fm.confidence).toBe(0.9);
+      expect(fm.artifacts).toEqual(["src/foo.ts", "src/bar.ts"]);
+      expect(fm.scope).toBe("thread");
+      expect(result.body).toBe("## Summary\n\nEverything looks good.");
+    });
+
+    it("strips leading newline from body", () => {
+      const raw = "---\nstatus: done\n---\n\nbody here";
+      const result = parseFrontmatterMarkdown(raw);
+      expect(result.body).toBe("body here");
+    });
+
+    it("body is empty string when nothing after closing fence", () => {
+      const raw = "---\nstatus: done\n---\n";
+      const result = parseFrontmatterMarkdown(raw);
+      expect(result.body).toBe("");
+    });
+
+    it("body is empty string when document ends exactly at closing fence", () => {
+      const raw = "---\nstatus: done\n---";
+      const result = parseFrontmatterMarkdown(raw);
+      expect(result.body).toBe("");
+    });
+  });
+
+  describe("status field", () => {
+    it.each([
+      "done",
+      "needs_input",
+      "in_progress",
+      "failed",
+    ] as const)('parses status "%s"', (status) => {
+      const raw = `---\nstatus: ${status}\n---\nbody`;
+      const result = parseFrontmatterMarkdown(raw);
+      expect(result.frontmatter?.status).toBe(status);
+    });
+
+    it("returns null status for unknown value", () => {
+      const raw = "---\nstatus: unknown_value\n---\nbody";
+      const result = parseFrontmatterMarkdown(raw);
+      expect(result.frontmatter?.status).toBeNull();
+    });
+
+    it("returns null status when omitted", () => {
+      const raw = "---\nconfidence: 0.5\n---\nbody";
+      const result = parseFrontmatterMarkdown(raw);
+      expect(result.frontmatter?.status).toBeNull();
+    });
+  });
+
+  describe("confidence field", () => {
+    it("parses integer as number", () => {
+      const raw = "---\nconfidence: 1\n---\nbody";
+      const result = parseFrontmatterMarkdown(raw);
+      expect(result.frontmatter?.confidence).toBe(1);
+    });
+
+    it("parses decimal", () => {
+      const raw = "---\nconfidence: 0.75\n---\nbody";
+      const result = parseFrontmatterMarkdown(raw);
+      expect(result.frontmatter?.confidence).toBe(0.75);
+    });
+
+    it("returns null when omitted", () => {
+      const raw = "---\nstatus: done\n---\nbody";
+      const result = parseFrontmatterMarkdown(raw);
+      expect(result.frontmatter?.confidence).toBeNull();
+    });
+
+    it("returns null for non-numeric value", () => {
+      const raw = "---\nconfidence: high\n---\nbody";
+      const result = parseFrontmatterMarkdown(raw);
+      expect(result.frontmatter?.confidence).toBeNull();
+    });
+  });
+
+  describe("artifacts field", () => {
+    it("parses block sequence", () => {
+      const raw = "---\nartifacts:\n  - a.ts\n  - b.ts\n---\nbody";
+      const result = parseFrontmatterMarkdown(raw);
+      expect(result.frontmatter?.artifacts).toEqual(["a.ts", "b.ts"]);
+    });
+
+    it("parses inline sequence", () => {
+      const raw = "---\nartifacts: [a.ts, b.ts]\n---\nbody";
+      const result = parseFrontmatterMarkdown(raw);
+      expect(result.frontmatter?.artifacts).toEqual(["a.ts", "b.ts"]);
+    });
+
+    it("returns empty array when omitted", () => {
+      const raw = "---\nstatus: done\n---\nbody";
+      const result = parseFrontmatterMarkdown(raw);
+      expect(result.frontmatter?.artifacts).toEqual([]);
+    });
+
+    it("wraps single scalar in array", () => {
+      const raw = "---\nartifacts: only-one.ts\n---\nbody";
+      const result = parseFrontmatterMarkdown(raw);
+      expect(result.frontmatter?.artifacts).toEqual(["only-one.ts"]);
+    });
+  });
+
+  describe("scope field", () => {
+    it('parses scope "role"', () => {
+      const raw = "---\nscope: role\n---\nbody";
+      const result = parseFrontmatterMarkdown(raw);
+      expect(result.frontmatter?.scope).toBe("role");
+    });
+
+    it('parses scope "thread"', () => {
+      const raw = "---\nscope: thread\n---\nbody";
+      const result = parseFrontmatterMarkdown(raw);
+      expect(result.frontmatter?.scope).toBe("thread");
+    });
+
+    it('defaults to "role" when omitted', () => {
+      const raw = "---\nstatus: done\n---\nbody";
+      const result = parseFrontmatterMarkdown(raw);
+      expect(result.frontmatter?.scope).toBe("role");
+    });
+
+    it('defaults to "role" for unknown scope value', () => {
+      const raw = "---\nscope: global\n---\nbody";
+      const result = parseFrontmatterMarkdown(raw);
+      expect(result.frontmatter?.scope).toBe("role");
+    });
+  });
+
+  describe("next field", () => {
+    it("parses a role name", () => {
+      const raw = "---\nnext: planner\n---\nbody";
+      const result = parseFrontmatterMarkdown(raw);
+      expect(result.frontmatter?.next).toBe("planner");
+    });
+
+    it("returns null when omitted", () => {
+      const raw = "---\nstatus: done\n---\nbody";
+      const result = parseFrontmatterMarkdown(raw);
+      expect(result.frontmatter?.next).toBeNull();
+    });
+  });
+
+  describe("unknown fields", () => {
+    it("ignores unknown keys silently", () => {
+      const raw = "---\nunknown_field: some_value\nstatus: done\n---\nbody";
+      const result = parseFrontmatterMarkdown(raw);
+      expect(result.frontmatter?.status).toBe("done");
+    });
+  });
+
+  describe("YAML comments", () => {
+    it("ignores YAML comment lines", () => {
+      const raw = "---\n# this is a comment\nstatus: done\n---\nbody";
+      const result = parseFrontmatterMarkdown(raw);
+      expect(result.frontmatter?.status).toBe("done");
+    });
+  });
+
+  describe("empty frontmatter block", () => {
+    it("parses empty frontmatter and uses all defaults", () => {
+      const raw = "---\n---\nbody";
+      const result = parseFrontmatterMarkdown(raw);
+      expect(result.frontmatter).not.toBeNull();
+      const fm = result.frontmatter!;
+      expect(fm.status).toBeNull();
+      expect(fm.next).toBeNull();
+      expect(fm.confidence).toBeNull();
+      expect(fm.artifacts).toEqual([]);
+      expect(fm.scope).toBe("role");
+      expect(result.body).toBe("body");
+    });
+  });
+});
+
+// ── validateFrontmatter ──────────────────────────────────────────────────────
+
+function validFm(overrides: Partial<AgentFrontmatter> = {}): AgentFrontmatter {
+  return {
+    status: "done",
+    next: null,
+    confidence: null,
+    artifacts: [],
+    scope: "role",
+    ...overrides,
+  };
+}
+
+describe("validateFrontmatter", () => {
+  it("returns no errors for a fully valid frontmatter", () => {
+    const errors = validateFrontmatter(validFm());
+    expect(errors).toHaveLength(0);
+  });
+
+  it("returns no errors when all nullable fields are null", () => {
+    const fm: AgentFrontmatter = {
+      status: null,
+      next: null,
+      confidence: null,
+      artifacts: [],
+      scope: "role",
+    };
+    expect(validateFrontmatter(fm)).toHaveLength(0);
+  });
+
+  describe("confidence validation", () => {
+    it("accepts 0.0", () => {
+      expect(validateFrontmatter(validFm({ confidence: 0 }))).toHaveLength(0);
+    });
+
+    it("accepts 1.0", () => {
+      expect(validateFrontmatter(validFm({ confidence: 1 }))).toHaveLength(0);
+    });
+
+    it("rejects value below 0", () => {
+      const errors = validateFrontmatter(validFm({ confidence: -0.1 }));
+      expect(errors).toHaveLength(1);
+      expect(errors[0]?.field).toBe("confidence");
+    });
+
+    it("rejects value above 1", () => {
+      const errors = validateFrontmatter(validFm({ confidence: 1.01 }));
+      expect(errors).toHaveLength(1);
+      expect(errors[0]?.field).toBe("confidence");
+    });
+  });
+
+  describe("next validation", () => {
+    it("accepts a simple role name", () => {
+      expect(validateFrontmatter(validFm({ next: "reviewer" }))).toHaveLength(0);
+    });
+
+    it("accepts kebab-case role name", () => {
+      expect(validateFrontmatter(validFm({ next: "code-reviewer" }))).toHaveLength(0);
+    });
+
+    it("rejects role name with whitespace", () => {
+      const errors = validateFrontmatter(validFm({ next: "role name" }));
+      expect(errors).toHaveLength(1);
+      expect(errors[0]?.field).toBe("next");
+    });
+  });
+
+  describe("artifacts validation", () => {
+    it("accepts non-empty path strings", () => {
+      expect(
+        validateFrontmatter(validFm({ artifacts: ["src/foo.ts", "src/bar.ts"] })),
+      ).toHaveLength(0);
+    });
+
+    it("rejects empty string artifact entries", () => {
+      const errors = validateFrontmatter(validFm({ artifacts: [""] }));
+      expect(errors).toHaveLength(1);
+      expect(errors[0]?.field).toBe("artifacts");
+    });
+
+    it("rejects whitespace-only artifact entries", () => {
+      const errors = validateFrontmatter(validFm({ artifacts: ["   "] }));
+      expect(errors).toHaveLength(1);
+      expect(errors[0]?.field).toBe("artifacts");
+    });
+  });
+
+  describe("multiple errors", () => {
+    it("reports multiple violations at once", () => {
+      const fm: AgentFrontmatter = {
+        status: "done",
+        next: "bad role",
+        confidence: 2,
+        artifacts: [""],
+        scope: "role",
+      };
+      const errors = validateFrontmatter(fm);
+      const fields = errors.map((e) => e.field);
+      expect(fields).toContain("next");
+      expect(fields).toContain("confidence");
+      expect(fields).toContain("artifacts");
+    });
+  });
+});

packages/workflow-util/src/frontmatter-markdown/frontmatter-markdown.ts

@@ -0,0 +1,291 @@
+import type {
+  AgentFrontmatter,
+  FrontmatterScope,
+  FrontmatterStatus,
+  FrontmatterValidationError,
+  ParsedFrontmatterMarkdown,
+} from "./types.js";
+
+// ── YAML frontmatter extractor ───────────────────────────────────────────────
+
+const FENCE = "---";
+
+/**
+ * Split a raw agent response into a YAML string (or null) and a markdown body.
+ *
+ * A frontmatter block MUST:
+ *   1. Start at character position 0 with `---` (no leading whitespace / BOM).
+ *   2. Be closed by a second `---` on its own line.
+ *
+ * Anything that doesn't match this shape is returned verbatim as the body.
+ */
+function splitFrontmatter(raw: string): { yaml: string | null; body: string } {
+  if (!raw.startsWith(FENCE)) {
+    return { yaml: null, body: raw };
+  }
+
+  const rest = raw.slice(FENCE.length);
+  // The opening `---` must be followed immediately by a newline (or end-of-string).
+  if (rest.length > 0 && rest[0] !== "\n" && rest[0] !== "\r") {
+    return { yaml: null, body: raw };
+  }
+  // Consume the newline after the opening fence so that `afterOpen` starts at the
+  // first line of YAML content (not a leading empty line).
+  const afterOpen = rest.startsWith("\n") ? rest.slice(1) : rest;
+
+  const closeIndex = afterOpen.indexOf(`\n${FENCE}`);
+  if (closeIndex === -1) {
+    // Also handle the edge case where frontmatter is empty: `---\n---`
+    if (afterOpen.startsWith(FENCE)) {
+      const afterClose = afterOpen.slice(FENCE.length);
+      const body = afterClose.replace(/^\n+/, "");
+      return { yaml: "", body };
+    }
+    return { yaml: null, body: raw };
+  }
+
+  const yaml = afterOpen.slice(0, closeIndex);
+  // Skip past `\n---` and strip any leading blank separator lines from the body.
+  const afterClose = afterOpen.slice(closeIndex + 1 + FENCE.length);
+  const body = afterClose.replace(/^\n+/, "");
+
+  return { yaml, body };
+}
+
+// ── Minimal YAML scalar parser ───────────────────────────────────────────────
+//
+// We intentionally avoid a full YAML library dependency inside workflow-util.
+// The frontmatter schema is flat and uses only scalars + simple string lists.
+// This parser handles exactly what the spec needs and nothing more.
+
+type YamlValue = string | number | boolean | null | string[];
+
+function parseYamlScalar(raw: string): YamlValue {
+  const trimmed = raw.trim();
+
+  // Quoted string
+  if (
+    (trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+    (trimmed.startsWith("'") && trimmed.endsWith("'"))
+  ) {
+    return trimmed.slice(1, -1);
+  }
+
+  const lower = trimmed.toLowerCase();
+  if (lower === "true") return true;
+  if (lower === "false") return false;
+  if (lower === "null" || lower === "~" || lower === "") return null;
+
+  const num = Number(trimmed);
+  if (!Number.isNaN(num) && trimmed !== "") return num;
+
+  return trimmed;
+}
+
+function collectBlockSequence(
+  lines: string[],
+  startIdx: number,
+): { items: string[]; nextIdx: number } {
+  const items: string[] = [];
+  let i = startIdx;
+  while (i < lines.length) {
+    const itemTrimmed = (lines[i] ?? "").trimStart();
+    if (!itemTrimmed.startsWith("- ")) break;
+    items.push(itemTrimmed.slice(2).trim());
+    i++;
+  }
+  return { items, nextIdx: i };
+}
+
+function parseInlineSequence(restTrimmed: string): string[] {
+  const inner = restTrimmed.slice(1, -1);
+  return inner
+    .split(",")
+    .map((s) => s.trim())
+    .filter((s) => s !== "");
+}
+
+function parseKeyValue(
+  lines: string[],
+  i: number,
+): { key: string; value: YamlValue; nextIdx: number } | null {
+  const line = lines[i] ?? "";
+  if (line.trim() === "" || line.trimStart().startsWith("#")) {
+    return null;
+  }
+  const colonIdx = line.indexOf(":");
+  if (colonIdx === -1) {
+    return null;
+  }
+  const key = line.slice(0, colonIdx).trim();
+  const restTrimmed = line.slice(colonIdx + 1).trim();
+
+  if (restTrimmed === "") {
+    const { items, nextIdx } = collectBlockSequence(lines, i + 1);
+    return { key, value: items, nextIdx };
+  }
+  if (restTrimmed.startsWith("[") && restTrimmed.endsWith("]")) {
+    return { key, value: parseInlineSequence(restTrimmed), nextIdx: i + 1 };
+  }
+  return { key, value: parseYamlScalar(restTrimmed), nextIdx: i + 1 };
+}
+
+/**
+ * Parse a minimal flat YAML document.  Only supports:
+ * - Scalar key: value pairs
+ * - Block sequences under a key (items prefixed with `  - `)
+ *
+ * Returns a plain object.  Never throws — unparseable lines are silently skipped.
+ */
+function parseMinimalYaml(yaml: string): Record<string, YamlValue> {
+  const result: Record<string, YamlValue> = {};
+  const lines = yaml.split("\n");
+
+  let i = 0;
+  while (i < lines.length) {
+    const entry = parseKeyValue(lines, i);
+    if (entry === null) {
+      i++;
+      continue;
+    }
+    result[entry.key] = entry.value;
+    i = entry.nextIdx;
+  }
+
+  return result;
+}
+
+// ── Field coercers ───────────────────────────────────────────────────────────
+
+const VALID_STATUS: readonly FrontmatterStatus[] = ["done", "needs_input", "in_progress", "failed"];
+
+const VALID_SCOPE: readonly FrontmatterScope[] = ["role", "thread"];
+
+function coerceStatus(raw: YamlValue): FrontmatterStatus | null {
+  if (raw === null || raw === undefined) return null;
+  const s = String(raw).trim().toLowerCase();
+  return VALID_STATUS.includes(s as FrontmatterStatus) ? (s as FrontmatterStatus) : null;
+}
+
+function coerceNext(raw: YamlValue): string | null {
+  if (raw === null || raw === undefined) return null;
+  const s = String(raw).trim();
+  return s === "" ? null : s;
+}
+
+function coerceConfidence(raw: YamlValue): number | null {
+  if (raw === null || raw === undefined) return null;
+  const n = typeof raw === "number" ? raw : Number(String(raw).trim());
+  if (Number.isNaN(n)) return null;
+  return n;
+}
+
+function coerceArtifacts(raw: YamlValue): readonly string[] {
+  if (raw === null || raw === undefined) return [];
+  if (Array.isArray(raw)) return raw.map(String).filter((s) => s !== "");
+  const s = String(raw).trim();
+  return s === "" ? [] : [s];
+}
+
+function coerceScope(raw: YamlValue): FrontmatterScope {
+  if (raw === null || raw === undefined) return "role";
+  const s = String(raw).trim().toLowerCase();
+  return VALID_SCOPE.includes(s as FrontmatterScope) ? (s as FrontmatterScope) : "role";
+}
+
+// ── Public API ───────────────────────────────────────────────────────────────
+
+/**
+ * Parse a raw agent response string into structured frontmatter + body.
+ *
+ * - Never throws: malformed YAML is silently treated as "no frontmatter".
+ * - The returned `frontmatter` is `null` when no valid `---…---` block was found.
+ * - Unknown YAML keys are silently ignored.
+ * - Invalid scalar values for known keys are coerced to their null/default.
+ */
+export function parseFrontmatterMarkdown(raw: string): ParsedFrontmatterMarkdown {
+  const { yaml, body } = splitFrontmatter(raw);
+
+  if (yaml === null) {
+    return { frontmatter: null, body };
+  }
+
+  let fields: Record<string, YamlValue>;
+  try {
+    fields = parseMinimalYaml(yaml);
+  } catch {
+    // Unparseable YAML → treat as no frontmatter; keep full raw as body.
+    return { frontmatter: null, body: raw };
+  }
+
+  const frontmatter: AgentFrontmatter = {
+    status: coerceStatus(fields.status ?? null),
+    next: coerceNext(fields.next ?? null),
+    confidence: coerceConfidence(fields.confidence ?? null),
+    artifacts: coerceArtifacts(fields.artifacts ?? null),
+    scope: coerceScope(fields.scope ?? null),
+  };
+
+  return { frontmatter, body };
+}
+
+/**
+ * Validate a parsed `AgentFrontmatter` and return a list of violations.
+ *
+ * An empty array means the frontmatter is valid.
+ *
+ * Validated constraints:
+ * - `status`     — must be one of the FrontmatterStatus literals (if non-null)
+ * - `confidence` — must be in [0.0, 1.0] (if non-null)
+ * - `next`       — must be a non-empty string with no whitespace (if non-null)
+ * - `artifacts`  — each entry must be a non-empty string
+ * - `scope`      — must be one of the FrontmatterScope literals
+ */
+export function validateFrontmatter(
+  frontmatter: AgentFrontmatter,
+): readonly FrontmatterValidationError[] {
+  const errors: FrontmatterValidationError[] = [];
+
+  if (frontmatter.status !== null && !VALID_STATUS.includes(frontmatter.status)) {
+    errors.push({
+      field: "status",
+      message: `invalid status "${frontmatter.status}"; must be one of: ${VALID_STATUS.join(", ")}`,
+    });
+  }
+
+  if (frontmatter.confidence !== null) {
+    if (frontmatter.confidence < 0 || frontmatter.confidence > 1) {
+      errors.push({
+        field: "confidence",
+        message: `confidence ${frontmatter.confidence} is out of range; must be between 0.0 and 1.0 inclusive`,
+      });
+    }
+  }
+
+  if (frontmatter.next !== null) {
+    if (frontmatter.next.trim() === "") {
+      errors.push({ field: "next", message: "next must be a non-empty string when present" });
+    } else if (/\s/.test(frontmatter.next)) {
+      errors.push({
+        field: "next",
+        message: `next "${frontmatter.next}" must not contain whitespace`,
+      });
+    }
+  }
+
+  for (const artifact of frontmatter.artifacts) {
+    if (artifact.trim() === "") {
+      errors.push({ field: "artifacts", message: "artifact entries must be non-empty strings" });
+      break;
+    }
+  }
+
+  if (!VALID_SCOPE.includes(frontmatter.scope)) {
+    errors.push({
+      field: "scope",
+      message: `invalid scope "${frontmatter.scope}"; must be one of: ${VALID_SCOPE.join(", ")}`,
+    });
+  }
+
+  return errors;
+}

packages/workflow-util/src/frontmatter-markdown/index.ts

@@ -0,0 +1,8 @@
+export { parseFrontmatterMarkdown, validateFrontmatter } from "./frontmatter-markdown.js";
+export type {
+  AgentFrontmatter,
+  FrontmatterScope,
+  FrontmatterStatus,
+  FrontmatterValidationError,
+  ParsedFrontmatterMarkdown,
+} from "./types.js";

packages/workflow-util/src/frontmatter-markdown/types.ts

@@ -0,0 +1,111 @@
+/**
+ * Frontmatter Markdown — agent output format (RFC #351 Phase 1).
+ *
+ * An agent response is a Markdown document with an optional YAML frontmatter
+ * block at the top.  The frontmatter carries structured signals that the
+ * moderator and engine can consume without running a full LLM extract pass.
+ *
+ * Wire format:
+ *
+ *   ---
+ *   status: done
+ *   next: reviewer
+ *   confidence: 0.9
+ *   artifacts:
+ *     - src/foo.ts
+ *   scope: role
+ *   ---
+ *
+ *   ... free-form markdown body ...
+ *
+ * All frontmatter fields are optional at the parse level.  `validateFrontmatter`
+ * enforces the constraints documented on each field below.
+ */
+
+// ── Vocabulary types ─────────────────────────────────────────────────────────
+
+/**
+ * High-level signal from the agent about where work stands.
+ *
+ * - `done`        — role completed its objective; moderator may advance
+ * - `needs_input` — agent is blocked and requires human or peer clarification
+ * - `in_progress` — work is underway but the agent chose to yield early
+ * - `failed`      — agent cannot complete the task and explains why in the body
+ */
+export type FrontmatterStatus = "done" | "needs_input" | "in_progress" | "failed";
+
+/**
+ * Scope of frontmatter signals.
+ *
+ * - `role`   — signals apply to the current role execution only (default)
+ * - `thread` — signals are suggestions for the entire thread moderator
+ */
+export type FrontmatterScope = "role" | "thread";
+
+// ── Core frontmatter schema ──────────────────────────────────────────────────
+
+/**
+ * Parsed and validated frontmatter from an agent response.
+ *
+ * All fields use explicit `T | null` (no optional `?:` per convention).
+ */
+export type AgentFrontmatter = {
+  /**
+   * Completion status signal from the agent.
+   * Null when omitted — engine treats it as "done" for backward compatibility.
+   */
+  status: FrontmatterStatus | null;
+
+  /**
+   * Suggested next role name for the moderator.
+   * The moderator is NOT obligated to follow this — it is advisory only.
+   * Null when the agent has no preference.
+   */
+  next: string | null;
+
+  /**
+   * Agent's self-assessed confidence in its output (0.0 – 1.0 inclusive).
+   * Null when omitted.
+   */
+  confidence: number | null;
+
+  /**
+   * Relative file paths or CAS hashes the agent considers its primary outputs.
+   * Used for GC ref-tracing and human-readable summaries.
+   * Empty array when omitted (never null — an absent list is an empty list).
+   */
+  artifacts: readonly string[];
+
+  /**
+   * Scope of the frontmatter signals.
+   * Defaults to "role" when omitted.
+   */
+  scope: FrontmatterScope;
+};
+
+// ── Parse output ─────────────────────────────────────────────────────────────
+
+/**
+ * Result of `parseFrontmatterMarkdown`: the structured frontmatter (if present)
+ * and the body (everything after the closing `---` fence, or the whole input
+ * if no frontmatter was found).
+ */
+export type ParsedFrontmatterMarkdown = {
+  /**
+   * Parsed frontmatter fields.  Null when no frontmatter block was detected
+   * (i.e. the document does not start with `---`).
+   */
+  frontmatter: AgentFrontmatter | null;
+
+  /** Markdown body with frontmatter block stripped. Leading newline removed. */
+  body: string;
+};
+
+// ── Validation error ─────────────────────────────────────────────────────────
+
+export type FrontmatterValidationError =
+  | { field: "status"; message: string }
+  | { field: "next"; message: string }
+  | { field: "confidence"; message: string }
+  | { field: "artifacts"; message: string }
+  | { field: "scope"; message: string };

packages/workflow-util/src/index.ts

@@ -1,6 +1,17 @@
 export { err, ok } from "@uncaged/workflow-protocol";
 export { encodeUint64AsCrockford } from "./base32.js";
 export { env } from "./env.js";
+export {
+  parseFrontmatterMarkdown,
+  validateFrontmatter,
+} from "./frontmatter-markdown/index.js";
+export type {
+  AgentFrontmatter,
+  FrontmatterScope,
+  FrontmatterStatus,
+  FrontmatterValidationError,
+  ParsedFrontmatterMarkdown,
+} from "./frontmatter-markdown/index.js";
 export { createLogger } from "./logger.js";
 export { normalizeRefsField } from "./refs-field.js";
 export { getDefaultWorkflowStorageRoot, getGlobalCasDir } from "./storage-root.js";

scripts/mock-agent.ts

@@ -1,11 +1,27 @@
 #!/usr/bin/env bun
 // Mock agent for smoke testing
+import { bootstrap, type JSONSchema, putSchema } from "@uncaged/json-cas";
 import { createAgent } from "../packages/uwf-agent-kit/src/index.js";
 
+const MOCK_RAW_OUTPUT_SCHEMA: JSONSchema = {
+  title: "mock-raw-output",
+  type: "object",
+  required: ["text"],
+  properties: {
+    text: { type: "string" },
+  },
+  additionalProperties: false,
+};
+
 const agent = createAgent({
   name: "mock",
   run: async (ctx) => {
-    return `Mock output for role ${ctx.role}: task was "${ctx.prompt}"`;
+    const output = `Mock output for role ${ctx.role}: task was "${ctx.start.prompt}"`;
+    const { store } = ctx;
+    await bootstrap(store);
+    const schemaHash = await putSchema(store, MOCK_RAW_OUTPUT_SCHEMA);
+    const detailHash = await store.put(schemaHash, { text: output });
+    return { output, detailHash };
   },
 });
 

tsconfig.json

@@ -37,6 +37,9 @@
     { "path": "packages/uwf-moderator" },
     { "path": "packages/cli-uwf" },
     { "path": "packages/uwf-agent-kit" },
-    { "path": "packages/uwf-agent-hermes" }
+    { "path": "packages/uwf-agent-hermes" },
+    { "path": "packages/workflow-template-document" },
+    { "path": "packages/workflow-agent-office" },
+    { "path": "packages/workflow-agent-docx-diff" }
   ]
 }