feat: builtin agent session resume via deterministic message reconstruction (#426 )

- StepRecord adds edgePrompt field (backward compat: defaults to "") - StepNode CAS schema includes edgePrompt - writeStepNode persists ctx.edgePrompt - buildHistory exposes edgePrompt in StepContext - buildBuiltinMessages reconstructs multi-turn moderator↔agent conversation: system = role prompt + output format (stable prefix) per prior visit: user (edgePrompt + inter-step summary) + assistant (output) current: user (edgePrompt + recent summary) - Zero extra persistence — pure function of CAS chain - Stable prefix for LLM prompt cache hits - 10 builtin tests pass, all other package tests pass
Merge pull request 'fix(builtin): split prompt into system/user messages' (#425 ) from fix/builtin-agent-system-user-split into main
2026-05-23 17:34:49 +08:00 · 2026-05-23 09:17:13 +00:00 · 2026-05-23 09:16:51 +00:00 · 2026-05-23 17:15:23 +08:00 · 2026-05-23 08:58:05 +00:00 · 2026-05-23 08:31:07 +00:00
57 changed files with 3543 additions and 187 deletions
@@ -0,0 +1,779 @@
+# Built-in Role Agent 调研
+
+## 目标
+
+实现一个内置的 role agent（暂称 `uwf-builtin`），不依赖 hermes/openclaw 等外部 agent 进程。
+直接使用 workflow config 中配置的 model，自己实现 agent run loop 和关键 toolkit。
+
+---
+
+## 关键问题
+
+### Q1: Agent 接口协议
+
+现有 agent 是怎么被 CLI 调用的？输入（argv、环境变量）和输出（stdout、CAS）格式是什么？
+
+**调研要点：**
+- `cli-workflow` 里 `spawnAgent` 的完整实现
+- AgentConfig 类型定义
+- agent 进程的 exit code 约定
+- 环境变量传递（UWF_STORAGE_ROOT 等）
+
+**答案：**
+
+#### 调用链
+
+`uwf thread step` → `cmdThreadStepOnce` → moderator 求值下一 role → `resolveAgentConfig` → `spawnAgent`。
+
+#### AgentConfig 类型
+
+```146:149:packages/workflow-protocol/src/types.ts
+export type AgentConfig = {
+  command: string;
+  args: string[];
+};
+```
+
+在 `config.yaml` 的 `agents` 段注册，例如 `hermes: { command: "uwf-hermes", args: [] }`。
+
+#### spawnAgent 行为
+
+```627:653:packages/cli-workflow/src/commands/thread.ts
+function spawnAgent(agent: AgentConfig, threadId: ThreadId, role: string): CasRef {
+  const argv = [...agent.args, threadId, role];
+  let stdout: string;
+  try {
+    stdout = execFileSync(agent.command, argv, {
+      encoding: "utf8",
+      env: process.env,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+  } catch (e) {
+  // ... stderr 拼进 fail 消息
+  }
+
+  const line = stdout.trim().split("\n").pop()?.trim() ?? "";
+  if (!isCasRef(line)) {
+    fail(`agent stdout is not a valid CAS hash: ${line || "(empty)"}`);
+  }
+  return line;
+}
+```
+
+| 项目 | 约定 |
+|------|------|
+| **argv** | `[...agent.args, <thread-id>, <role>]`，即 `process.argv[2]`=threadId，`process.argv[3]`=role（与 `createAgent` 的 `parseArgv` 一致） |
+| **stdin** | 忽略 |
+| **stdout** | 纯文本，**最后一行**必须是新 `StepNode` 的 CAS hash（13 字符 Crockford Base32） |
+| **stderr** | 失败时 CLI 会附带 stderr；成功时无约定 |
+| **exit code** | `0` = 成功；非 0 时 `execFileSync` 抛错，step 失败 |
+| **环境变量** | 继承父进程 `process.env`（含 storage root、API key 等） |
+| **链头更新** | **不由 agent 负责**；agent 只写 CAS StepNode，CLI 在拿到 stdout hash 后更新 `threads.yaml` |
+
+Agent 解析优先级（`resolveAgentConfig`）：
+
+1. CLI `--agent` override（整段 command + args 字符串）
+2. `config.agentOverrides[workflow.name][role]`
+3. `config.defaultAgent`
+
+#### 环境变量：Storage Root
+
+文档中写的 `UWF_STORAGE_ROOT` **在当前代码中不存在**。实际优先级（`workflow-agent-kit` / `cli-workflow` 一致）：
+
+```33:43:packages/workflow-agent-kit/src/storage.ts
+export function resolveStorageRoot(): string {
+  const internal = process.env.UNCAGED_WORKFLOW_STORAGE_ROOT;
+  if (internal !== undefined && internal !== "") {
+    return internal;
+  }
+  const userOverride = process.env.WORKFLOW_STORAGE_ROOT;
+  if (userOverride !== undefined && userOverride !== "") {
+    return userOverride;
+  }
+  return getDefaultStorageRoot();
+}
+```
+
+Agent 子进程通过继承的 `process.env` 与父 CLI 共享同一 storage root；`createAgent` 内还会 `loadDotenv({ path: getEnvPath(storageRoot) })` 加载 `~/.uncaged/workflow/.env`。
+
+#### Agent 侧职责（设计文档 + 实现）
+
+- 读 `threads.yaml` 链头，构建 context，执行 role
+- 将 `StepNode` 写入 CAS（`output` / `detail` / `agent` / `prev` / `start`）
+- stdout 打印 step hash
+- **不**更新 `threads.yaml`
+
+---
+
+### Q2: createAgent 工厂
+
+workflow-agent-kit 的 `createAgent` 做了什么？它的完整生命周期是什么？
+
+**调研要点：**
+- `AgentOptions` 类型的 `run` 和 `continue` 回调签名
+- `AgentRunResult` 的完整定义
+- retry 逻辑（frontmatter 校验失败后的重试机制）
+- `persistStep` 写入 CAS 的 StepNode 结构
+
+**答案：**
+
+#### 类型定义
+
+```4:35:packages/workflow-agent-kit/src/types.ts
+export type AgentContext = ModeratorContext & {
+  threadId: ThreadId;
+  role: string;
+  store: Store;
+  workflow: WorkflowPayload;
+  outputFormatInstruction: string;
+};
+
+export type AgentRunResult = {
+  output: string;
+  detailHash: CasRef;
+  sessionId: string;
+};
+
+export type AgentContinueFn = (
+  sessionId: string,
+  message: string,
+  store: AgentContext["store"],
+) => Promise<AgentRunResult>;
+
+export type AgentRunFn = (ctx: AgentContext) => Promise<AgentRunResult>;
+
+export type AgentOptions = {
+  name: string;
+  run: AgentRunFn;
+  continue: AgentContinueFn;
+};
+```
+
+- **`run(ctx)`**：首次执行，返回原始 agent 文本 `output`、审计用 `detailHash`、用于续聊的 `sessionId`。
+- **`continue(sessionId, message, store)`**：在同一 session 上追加用户消息（用于 frontmatter 纠错），再次返回 `AgentRunResult`。
+
+`createAgent(options)` 返回 `() => Promise<void>`，作为 agent CLI 的 `main`（见 `uwf-hermes` 的 `cli.ts`）。
+
+#### 生命周期（按执行顺序）
+
+```101:152:packages/workflow-agent-kit/src/run.ts
+export function createAgent(options: AgentOptions): () => Promise<void> {
+  return async function main(): Promise<void> {
+    const { threadId, role } = parseArgv(process.argv);
+    const storageRoot = resolveStorageRoot();
+    loadDotenv({ path: getEnvPath(storageRoot) });
+
+    const ctx = await buildContextWithMeta(threadId, role);
+    // 1. 校验 role 存在
+    // 2. 从 CAS 取 frontmatter JSON Schema → buildOutputFormatInstruction → ctx.outputFormatInstruction
+
+    let agentResult = await options.run(ctx);
+
+    let outputHash = await tryExtractOutput(agentResult.output, roleDef.frontmatter, ctx);
+
+    for (let retry = 0; retry < MAX_FRONTMATTER_RETRIES && outputHash === null; retry++) {
+      const correctionMessage = "Your previous response did not contain valid YAML frontmatter...";
+      agentResult = await options.continue(agentResult.sessionId, correctionMessage, ctx.meta.store);
+      outputHash = await tryExtractOutput(agentResult.output, roleDef.frontmatter, ctx);
+    }
+
+    if (outputHash === null) { fail(...); }
+
+    const stepHash = await persistStep({ ctx, outputHash, detailHash: agentResult.detailHash, agentName });
+    process.stdout.write(`${stepHash}\n`);
+  };
+}
+```
+
+| 阶段 | 行为 |
+|------|------|
+| 解析 argv | `argv[2]=threadId`, `argv[3]=role`，缺失则 `stderr` + `exit(1)` |
+| Context | `buildContextWithMeta` + 可选 `outputFormatInstruction` |
+| Run | `options.run(ctx)` |
+| Extract | **仅** `tryFrontmatterFastPath`（见 Q4）；**不**调用 `extract()` LLM fallback |
+| Retry | 最多 `MAX_FRONTMATTER_RETRIES = 2` 次 `continue` + 再试 fast-path |
+| Persist | `persistStep` → `writeStepNode` |
+| 输出 | stdout 一行 step CAS hash |
+
+#### StepNode 写入结构
+
+```44:68:packages/workflow-agent-kit/src/run.ts
+async function writeStepNode(options: {
+  store: AgentStore["store"];
+  schemas: AgentStore["schemas"];
+  startHash: CasRef;
+  prevHash: CasRef | null;
+  role: string;
+  outputHash: CasRef;
+  detailHash: CasRef;
+  agentName: string;
+}): Promise<CasRef> {
+  const payload: StepNodePayload = {
+    start: options.startHash,
+    prev: options.prevHash,
+    role: options.role,
+    output: options.outputHash,
+    detail: options.detailHash,
+    agent: options.agentName,
+  };
+  // store.put(stepNode schema) + validate
+}
+```
+
+`agentName` 经 `agentLabel(name)` 规范化：已有 `uwf-` 前缀则原样，否则加 `uwf-`（如 `hermes` → `uwf-hermes`）。
+
+`prevHash`：若链头仍是 `StartNode` 则为 `null`，否则为当前 head step hash。
+
+---
+
+### Q3: Context Builder
+
+`buildContextWithMeta` 构建了什么上下文给 agent？
+
+**调研要点：**
+- `AgentContext` 完整类型定义（所有字段）
+- context 构建过程（CAS chain walk）
+- `outputFormatInstruction` 怎么生成的
+- role definition 怎么获取（从 workflow YAML）
+
+**答案：**
+
+#### AgentContext 字段
+
+继承 `ModeratorContext`：
+
+```60:68:packages/workflow-protocol/src/types.ts
+export type ModeratorContext = {
+  start: StartNodePayload;
+  steps: StepContext[];
+};
+```
+
+```48:51:packages/workflow-protocol/src/types.ts
+export type StartNodePayload = {
+  workflow: CasRef;
+  prompt: string;
+};
+```
+
+```61:63:packages/workflow-protocol/src/types.ts
+export type StepContext = Omit<StepRecord, "output"> & {
+  output: unknown;
+};
+```
+
+`AgentContext` 额外字段：
+
+| 字段 | 类型 | 含义 |
+|------|------|------|
+| `threadId` | `ThreadId` | 当前线程 |
+| `role` | `string` | 本步要执行的角色名 |
+| `store` | `Store` | CAS store（读写节点） |
+| `workflow` | `WorkflowPayload` | 已从 CAS 加载的 workflow 定义 |
+| `outputFormatInstruction` | `string` | 由 `createAgent` 根据 role 的 frontmatter schema 生成；`buildContext*` 初始为 `""` |
+
+`buildContextWithMeta` 还返回 `meta`：
+
+```148:154:packages/workflow-agent-kit/src/context.ts
+export type BuildContextMeta = {
+  storageRoot: string;
+  store: Store;
+  schemas: AgentStore["schemas"];
+  headHash: CasRef;
+  chain: ChainState;
+};
+```
+
+#### CAS chain walk
+
+1. 从 `threads.yaml[threadId]` 取 `headHash`
+2. `walkChain`：若 head 是 `StartNode`，`stepsNewestFirst=[]`；否则沿 `prev` 收集所有 `StepNode`， newest-first
+3. `buildHistory`：反转为时间序，`expandOutput` 把每步 `output` CasRef 展开为 JSON payload（供 prompt / JSONata 使用）
+4. `loadWorkflow`：从 `start.workflow` CasRef 加载 `WorkflowPayload`
+
+#### Role definition 来源
+
+- 作者写在 workflow YAML 的 `roles.<name>`（`goal`, `capabilities`, `procedure`, `output`, `frontmatter` 等）
+- `uwf workflow put` 时 `frontmatter` 内联 JSON Schema 经 `putSchema` 存入 CAS，workflow 里存的是 **CasRef**
+- Agent 运行时：`ctx.workflow.roles[ctx.role]` → `RoleDefinition`
+
+#### outputFormatInstruction
+
+在 `createAgent` 中，若 `getSchema(store, roleDef.frontmatter)` 非空，则：
+
+```typescript
+ctx.outputFormatInstruction = buildOutputFormatInstruction(frontmatterSchema);
+```
+
+`buildOutputFormatInstruction` 根据 JSON Schema 的 `properties` 生成「必须以 `---` YAML frontmatter 开头」的说明和示例字段列表（见 `build-output-format-instruction.ts`）。
+
+各 agent 实现（Hermes / Claude Code）在组装 prompt 时把该块放在最前，再接 `buildRolePrompt(roleDef)`。
+
+---
+
+### Q4: Extract Pipeline
+
+agent 输出怎么被处理成结构化数据？
+
+**调研要点：**
+- frontmatter fast-path 的完整逻辑
+- LLM extract fallback 的实现（`extract.ts`）
+- frontmatter schema 从哪里来（role 定义里的 `frontmatter` 字段）
+- 校验失败时的 correction prompt 是什么
+
+**答案：**
+
+#### Schema 来源
+
+Workflow YAML 中每个 role 的 `frontmatter:` 段是 JSON Schema 对象；注册时：
+
+```66:76:packages/cli-workflow/src/commands/workflow.ts
+async function resolveFrontmatterRef(..., frontmatter: unknown): Promise<CasRef> {
+  // 校验为 JSON Schema → putSchema → 返回 CasRef
+}
+```
+
+运行时 `roleDef.frontmatter` 即该 schema 的 CAS hash；structured `output` 节点用**同一 schema** 写入 CAS。
+
+#### Frontmatter fast-path（createAgent 实际使用的路径）
+
+```148:195:packages/workflow-agent-kit/src/frontmatter.ts
+export async function tryFrontmatterFastPath(
+  raw: string,
+  outputSchema: CasRef,
+  store: Store,
+): Promise<FrontmatterFastPathResult | null>
+```
+
+流程：
+
+1. `parseFrontmatterMarkdown(raw)` → 标准 agent 字段（`status`, `next`, `confidence`, `artifacts`, `scope`）+ body
+2. `validateFrontmatter` 失败 → `null`
+3. `getSchema(store, outputSchema)` + `extractSchemaFields` 得到 role 需要的属性名
+4. `buildCandidate`：从标准 frontmatter + YAML 原始字段拼出符合 schema 的对象
+5. `store.put(outputSchema, candidate)` + `validate` → 成功则 `{ body, outputHash }`
+
+**永不抛错**，失败返回 `null`。
+
+#### LLM extract fallback（已实现但未接入 createAgent）
+
+```135:181:packages/workflow-agent-kit/src/extract.ts
+export async function extract(
+  rawOutput: string,
+  outputSchema: CasRef,
+  config: WorkflowConfig,
+): Promise<ExtractResult>
+```
+
+- 模型：`resolveExtractModelAlias(config)` → `modelOverrides.extract` → `models.extract` → `models.default` → `defaultModel`
+- HTTP：`POST {baseUrl}/chat/completions`，`response_format: { type: "json_object" }`
+- System：要求按 JSON Schema 从 agent 输出提取单个 JSON 对象
+- 校验通过后 `store.put(outputSchema, structured)`
+
+**重要：`createAgent` 当前未调用 `extract()`**。fast-path 失败且 2 次 `continue` 仍失败则直接 `fail()`。builtin agent 若希望无 frontmatter 也能跑，需在 kit 或 builtin 层显式接入 `extract()`。
+
+#### Correction prompt（retry）
+
+```125:128:packages/workflow-agent-kit/src/run.ts
+const correctionMessage =
+  "Your previous response did not contain valid YAML frontmatter matching the role schema.\n" +
+  "You MUST begin your response with a YAML frontmatter block (--- delimited).\n" +
+  "Please output ONLY the corrected frontmatter block followed by your work.";
+```
+
+通过 `options.continue(sessionId, correctionMessage, store)` 发给外部 agent；builtin 需在自有 message 历史里 append 同等语义的 user 消息。
+
+---
+
+### Q5: Model 配置与 LLM 调用
+
+workflow 怎么配置和使用 model？
+
+**调研要点：**
+- `WorkflowConfig` 中 providers/models/defaultModel/modelOverrides 的完整定义
+- `resolveModel` 函数的实现
+- `chatCompletionText` 的实现（OpenAI 兼容 HTTP 客户端）
+- 有没有 streaming 支持？tool calling 支持？
+
+**答案：**
+
+#### WorkflowConfig
+
+```136:160:packages/workflow-protocol/src/types.ts
+export type ProviderConfig = {
+  baseUrl: string;
+  apiKeyEnv: string;
+};
+
+export type ModelConfig = {
+  provider: ProviderAlias;
+  name: string;
+};
+
+export type WorkflowConfig = {
+  providers: Record<ProviderAlias, ProviderConfig>;
+  models: Record<ModelAlias, ModelConfig>;
+  agents: Record<AgentAlias, AgentConfig>;
+  defaultAgent: AgentAlias;
+  agentOverrides: Record<WorkflowName, Record<RoleName, AgentAlias>> | null;
+  defaultModel: ModelAlias;
+  modelOverrides: Record<Scenario, ModelAlias> | null;
+};
+```
+
+示例见 `docs/architecture.md`（`providers` / `models` / `defaultModel` / `modelOverrides.extract`）。
+
+#### resolveModel
+
+```32:50:packages/workflow-agent-kit/src/extract.ts
+export function resolveModel(config: WorkflowConfig, alias: ModelAlias): ResolvedLlmProvider {
+  const modelEntry = config.models[alias];
+  const providerEntry = config.providers[modelEntry.provider];
+  const apiKey = process.env[providerEntry.apiKeyEnv];
+  return { baseUrl: providerEntry.baseUrl, apiKey, model: modelEntry.name };
+}
+```
+
+`ResolvedLlmProvider = { baseUrl, apiKey, model }`。
+
+Extract 专用别名解析：
+
+```18:30:packages/workflow-agent-kit/src/extract.ts
+export function resolveExtractModelAlias(config: WorkflowConfig): ModelAlias {
+  return config.modelOverrides?.extract ?? (config.models.extract ? "extract" : config.models.default ? "default" : config.defaultModel);
+}
+```
+
+**尚无** `modelOverrides` 按 role/workflow 解析 agent 主模型的函数；builtin 首版可用 `config.defaultModel`，扩展时可加 `modelOverrides.agent` 或与 `agentOverrides` 对称的表。
+
+#### chatCompletionText
+
+```87:124:packages/workflow-agent-kit/src/extract.ts
+async function chatCompletionText(
+  provider: ResolvedLlmProvider,
+  messages: Array<{ role: "system" | "user"; content: string }>,
+): Promise<string>
+```
+
+| 能力 | 现状 |
+|------|------|
+| 协议 | OpenAI 兼容 `POST /chat/completions` |
+| Streaming | **无**（一次性 `response.text()`） |
+| Tool calling | **无**（无 `tools` / `tool_calls` 字段） |
+| 多模态 | **无**（仅 text `content`） |
+| Extract 专用 | `response_format: { type: "json_object" }` |
+
+builtin agent 的 run loop 需要**新写**带 `tools` 的 completion 客户端（可放在 `workflow-agent-builtin` 或扩展 `workflow-agent-kit` 的 `llm/` 模块），不能复用当前 `chatCompletionText` 而不改。
+
+---
+
+### Q6: Hermes Agent 参考实现
+
+`uwf-hermes` 是怎么实现 `run` 和 `continue` 的？
+
+**调研要点：**
+- prompt 怎么组装的（outputFormatInstruction + rolePrompt + task + history）
+- hermes CLI 的调用参数
+- session management（resume）
+- 输出怎么捕获
+
+**答案：**
+
+#### Prompt 组装
+
+```40:53:packages/workflow-agent-hermes/src/hermes.ts
+export function buildHermesPrompt(ctx: AgentContext): string {
+  const roleDef = ctx.workflow.roles[ctx.role];
+  const rolePrompt = roleDef !== undefined ? buildRolePrompt(roleDef) : "";
+  const parts: string[] = [];
+  if (ctx.outputFormatInstruction !== "") {
+    parts.push(ctx.outputFormatInstruction, "");
+  }
+  parts.push(rolePrompt, "", "## Task", ctx.start.prompt);
+  const historyBlock = buildHistorySummary(ctx.steps);
+  if (historyBlock !== "") {
+    parts.push("", historyBlock);
+  }
+  return parts.join("\n");
+}
+```
+
+`buildRolePrompt` 生成 `## Goal` / `## Capabilities` / `## Prepare`（含 `generateCliReference()`）/ `## Procedure` / `## Output`。
+
+`buildHistorySummary`：每步 `role`、`JSON.stringify(step.output)`、`agent`。
+
+Hermes 把**整段 prompt 作为单条 user 消息**传给 `hermes chat -q`（无独立 system channel）。
+
+#### Hermes CLI 参数
+
+首次：
+
+```88:97:packages/workflow-agent-hermes/src/hermes.ts
+spawnHermes(["chat", "-q", prompt, "--yolo", "--max-turns", "90", "--quiet"]);
+```
+
+续聊：
+
+```100:114:packages/workflow-agent-hermes/src/hermes.ts
+spawnHermes(["chat", "--resume", sessionId, "-q", message, "--yolo", "--max-turns", "90", "--quiet"]);
+```
+
+#### Session
+
+- stdout/stderr 中解析 `session_id: <id>`（`parseSessionIdFromStdout`）
+- 会话文件：`~/.hermes/sessions/session_<id>.json`
+- `loadHermesSession` → `storeHermesSessionDetail`：每 assistant/tool 消息写成 CAS turn 节点，汇总为 `detail`；**output 文本** = 最后一条非空 `assistant` 的 `content`
+
+#### 与 createAgent 的衔接
+
+```157:164:packages/workflow-agent-hermes/src/hermes.ts
+export function createHermesAgent(): () => Promise<void> {
+  return createAgent({ name: "hermes", run: runHermes, continue: continueHermes });
+}
+```
+
+`uwf-hermes` 入口：`createHermesAgent()` 即 main。
+
+Claude Code 包（`workflow-agent-claude-code`）结构相同：`buildClaudeCodePrompt` 同构，`claude -p` + `--resume` + JSON stdout 解析。
+
+---
+
+### Q7: Toolkit 需求分析
+
+要实现一个自给自足的 agent，最少需要哪些 tool？
+
+**调研要点：**
+- 现有 workflow example（solve-issue.yaml）里 role 都做什么任务
+- hermes agent 在 workflow 场景下常用哪些 tool
+- 哪些 tool 是 agent loop 必须的（如 file read/write、shell exec、web fetch）
+
+**答案：**
+
+#### solve-issue.yaml 角色能力
+
+| Role | capabilities | 隐含需求 |
+|------|----------------|----------|
+| planner | issue-analysis, planning | 读上下文/仓库、总结，通常不需写代码 |
+| developer | file-edit, shell, testing | **读文件、写文件、执行命令** |
+| reviewer | code-review, static-analysis | 读 diff/文件、静态分析（可读+可选 shell） |
+
+#### Hermes 侧
+
+Hermes 自带完整 agent runtime（`--yolo`、max-turns），tool 集由 Hermes 项目定义，workflow 不配置。从 session JSON 可见 `tool_calls` 被记入 detail，常见包括文件与 shell 类工具。
+
+#### Builtin 最小 toolkit 建议
+
+| 优先级 | Tool | 用途 |
+|--------|------|------|
+| P0 | `read_file` | 读仓库/配置/issue 上下文 |
+| P0 | `write_file` / `edit_file` | developer 改代码 |
+| P0 | `run_command` | 测试、构建、git（需 cwd + timeout + 输出截断） |
+| P1 | `list_dir` / `glob` | 导航代码库 |
+| P1 | `grep` | 搜索符号/引用 |
+| P2 | `fetch_url` | 查文档（planner 偶尔需要） |
+
+**不需要**在 builtin 里实现 moderator / workflow 路由工具——仍由 `uwf thread step` + JSONata 负责。
+
+#### Agent loop 必须能力
+
+1. 多轮 LLM 调用 + **OpenAI-style tool_calls** 解析与执行
+2. 将 tool 结果 append 回 messages
+3. 终止条件：模型不再请求 tool，或达到 `maxTurns`
+4. 最终响应须含合法 YAML frontmatter（满足 Q4），供 `createAgent` fast-path
+
+---
+
+## 方案草案
+
+（调研完成后基于以上答案撰写）
+
+### 架构设计
+
+```mermaid
+flowchart TB
+  subgraph cli ["cli-workflow"]
+    Step["uwf thread step"]
+    Spawn["spawnAgent(uwf-builtin, threadId, role)"]
+    Step --> Spawn
+  end
+
+  subgraph builtin_pkg ["@uncaged/workflow-agent-builtin"]
+    Main["createBuiltinAgent() = createAgent({...})"]
+    Prompt["buildBuiltinPrompt(ctx)"]
+    Loop["runBuiltinLoop(provider, messages, tools)"]
+    Tools["Toolkit: read/write/exec/..."]
+    Detail["storeBuiltinDetail(turns)"]
+    Main --> Prompt
+    Main --> Loop
+    Loop --> Tools
+    Loop --> Detail
+  end
+
+  subgraph kit ["workflow-agent-kit"]
+    Ctx["buildContextWithMeta"]
+    FM["tryFrontmatterFastPath"]
+    Persist["persistStep"]
+    Ctx --> Main
+    Main --> FM
+    FM --> Persist
+  end
+
+  subgraph cas ["CAS / config"]
+    Config["config.yaml models/providers"]
+    CAS["cas/ + threads.yaml"]
+  end
+
+  Spawn --> Main
+  Config --> Loop
+  CAS --> Ctx
+  Persist --> CAS
+  Spawn -->|"stdout: step hash"| Step
+```
+
+**新包**：`packages/workflow-agent-builtin`，bin `uwf-builtin`，仅依赖 `workflow-agent-kit`、`workflow-protocol`、`workflow-util`（可选 `@uncaged/json-cas` 写 detail schema）。
+
+**分层**：
+
+| 层 | 职责 |
+|----|------|
+| `createAgent`（kit） | argv、context、frontmatter extract、StepNode、stdout 协议 — **不变** |
+| `builtin/agent.ts` | `run` / `continue` 实现 |
+| `builtin/llm.ts` | OpenAI 兼容 chat + tools（可后续抽到 kit） |
+| `builtin/tools/*.ts` | 各 tool 的 JSON Schema + handler |
+| `builtin/prompt.ts` | 复用 Hermes 的 prompt 拼接逻辑（或抽到 kit 的 `buildAgentPrompt`） |
+| `builtin/detail.ts` | 类似 Hermes：每轮 assistant/tool 写入 CAS detail |
+
+**配置集成**：
+
+```yaml
+agents:
+  builtin:
+    command: "uwf-builtin"
+    args: []
+defaultAgent: "builtin"   # 或 agentOverrides 按 role 指定
+```
+
+模型：首版 `resolveModel(config, config.defaultModel)`；后续可增加 `modelOverrides.agent` 或 per-role 映射。
+
+---
+
+### Agent Run Loop
+
+伪代码（单次 `run(ctx)`）：
+
+```
+1. provider ← resolveModel(loadWorkflowConfig(), defaultModel)
+2. system ← buildBuiltinPrompt(ctx)   // outputFormatInstruction + buildRolePrompt + Task + History
+3. messages ← [{ role: "system", content: system }]
+4. sessionId ← newULID()              // 内存或临时目录，供 continue 使用
+5. turns ← []
+
+6. for turn in 1..MAX_TURNS:
+     response ← chatCompletionWithTools(provider, messages, TOOL_DEFINITIONS)
+     record assistant message + tool_calls in turns
+
+     if response has no tool_calls:
+       finalText ← response.content
+       break
+
+     for each tool_call:
+       result ← executeTool(tool_call, { cwd: process.cwd() })
+       messages.push tool result
+       record in turns
+
+7. if no finalText with valid frontmatter after loop:
+     optionally one-shot "finalize" message without tools
+
+8. detailHash ← storeBuiltinDetail(store, sessionId, turns, metadata)
+9. return { output: finalText, detailHash, sessionId }
+```
+
+**`continue(sessionId, message, store)`**：
+
+- 从内存/磁盘恢复 `messages` + `turns`
+- `messages.push({ role: "user", content: message })`（correction 或续聊）
+- 从步骤 6 继续，步数上限可单独设小一点（如 3）
+- 返回新的 `AgentRunResult`
+
+**与 frontmatter 的配合**：
+
+- system prompt 已含 `outputFormatInstruction`；最后一轮可强制 user：`Now output your final answer with YAML frontmatter only if you have not yet.`
+- 仍依赖 `createAgent` 的 fast-path + 最多 2 次 continue
+
+**安全**：
+
+- `run_command`：白名单或需 `UWF_BUILTIN_ALLOW_SHELL=1`，默认工作区限定在 `process.cwd()` 或 `start` 中将来扩展的 `workspace` 字段
+- 路径：禁止 `..` 逃逸出 workspace root
+
+---
+
+### Toolkit 设计
+
+统一注册表：
+
+```typescript
+type BuiltinTool = {
+  name: string;
+  description: string;
+  parameters: JSONSchema; // object type
+  execute: (args: unknown, ctx: ToolContext) => Promise<string>;
+};
+
+type ToolContext = {
+  cwd: string;
+  storageRoot: string;
+};
+```
+
+| Tool name | OpenAI function | 行为摘要 |
+|-----------|-----------------|----------|
+| `read_file` | `read_file` | `{ path }` → UTF-8 文本，大小上限 |
+| `write_file` | `write_file` | `{ path, content }` → 写盘，返回确认 |
+| `edit_file` | 可选 | search/replace 块，减少 token |
+| `run_command` | `run_command` | `{ command, cwd? }` → stdout/stderr 截断 |
+| `list_dir` | `list_dir` | `{ path }` → 条目列表 |
+| `grep` | `grep` | `{ pattern, path? }` → 匹配行 |
+
+**LLM 请求形状**（扩展 extract 客户端）：
+
+```json
+{
+  "model": "...",
+  "messages": [...],
+  "tools": [{ "type": "function", "function": { "name", "description", "parameters" } }],
+  "tool_choice": "auto"
+}
+```
+
+解析 `choices[0].message.tool_calls`，执行后以 `{ role: "tool", tool_call_id, content }` 回传。
+
+**不提供** streaming 首版；detail CAS 记录每轮 tool 名/参数/结果摘要供 `uwf thread step-details` 调试。
+
+---
+
+### 与现有架构的集成
+
+| 集成点 | 方式 |
+|--------|------|
+| CLI 协议 | 实现标准 agent CLI：`uwf-builtin <thread-id> <role>`，stdout 一行 step hash，exit 0/1 |
+| 工厂 | `export function createBuiltinAgent()` → `createAgent({ name: "builtin", run, continue })` |
+| Context / Prompt | 复用 `buildContextWithMeta`、`buildRolePrompt`、`buildOutputFormatInstruction`；prompt 布局对齐 `buildHermesPrompt` |
+| 结构化输出 | 优先 YAML frontmatter fast-path；可选后续在 `createAgent` 增加 `extract()` fallback 开关 |
+| 配置 | `config.yaml` 增加 `agents.builtin`；`uwf setup` 可选默认 agent |
+| 存储 | `resolveStorageRoot()` + `loadWorkflowConfig` + `getEnvPath`；与 Hermes 相同，**不**改 `threads.yaml` 写入方 |
+| 测试 | 单元测试：tool handlers、prompt 组装、mock LLM tool loop；集成测试：临时 storage root + fake provider |
+| 发布 | 新包 `@uncaged/workflow-agent-builtin`，bin `uwf-builtin`，加入 `scripts/publish-all.mjs` |
+
+**明确不做**：
+
+- 不替代 moderator / 不在 agent 内调用 `uwf thread step`
+- 不依赖 Hermes/OpenClaw/Claude Code 二进制
+- 首版不实现 streaming、不实现 MCP
+
+**建议实现顺序**：
+
+1. `llm.ts`：tool calling HTTP 客户端 + 单测
+2. P0 tools + `runBuiltinLoop`
+3. `createBuiltinAgent` + detail CAS
+4. `config` / docs / `examples` 可选 `agentOverrides` 演示
+5. （可选）`createAgent` 接入 `extract()` fallback
@@ -0,0 +1,73 @@
+# Issue #418: ACP session/resume 返回空文本
+
+## 调研日期: 2026-05-23
+
+## 根因
+
+`session/resume` 在 restore 路径下 `_make_agent()` 失败，异常被静默吞掉。
+
+### 完整调用链
+
+```
+resume_session(sid)
+  → update_cwd(sid)
+    → get_session(sid) → _restore(sid)
+      → _make_agent()
+        → resolve_runtime_provider("custom") 失败（line 548-561）
+        → AIAgent() 抛出 "No LLM provider configured"（line 564）
+      → except Exception 静默吞掉（line 482-484）→ return None
+    → return None
+  → state is None → fallback: create_session()（新 sid，无历史）
+```
+
+### 关键代码位置（acp_adapter/session.py）
+
+- `_restore()` line 426-498: 从 DB 恢复 session，但 except 太宽泛
+- `_make_agent()` line 520-568: provider 解析在 restore 路径下不完整
+- Line 548-561: `resolve_runtime_provider("custom")` 失败后，`base_url` 虽然从 DB 取到了但没传给 AIAgent
+
+### 实测行为
+
+1. Phase 1: `session/new` + `prompt` → 正常，有 `agent_message_chunk`
+2. Phase 2: `session/resume` + `prompt`
+   - resume 返回成功，但 `available_commands_update` 里 sessionId 是新的（create_session fallback）
+   - 用原始 sid 发 prompt → `stopReason: "refusal"`（session 不在内存中）
+   - 用新 sid 发 prompt → 能跑但无历史（agent 回答"不知道 secret code"）
+
+### 验证脚本
+
+```python
+# 直接调用 _restore 验证
+cd ~/.hermes/hermes-agent
+python3 -c "
+import sys; sys.path.insert(0, '.')
+from acp_adapter.session import SessionManager
+sm = SessionManager()
+result = sm._restore('SESSION_ID_HERE')
+print(result)  # None — _make_agent 抛异常被吞掉
+"
+```
+
+### 两个 bug
+
+1. **`_make_agent` provider fallback 不完整**: restore 时 DB 里有 `base_url` 和 `api_mode`，但 `resolve_runtime_provider` 失败后这些值没被正确传递给 AIAgent
+2. **`_restore` 的 except 太宽泛**: 静默吞掉所有异常，连 warning 都只在 debug 级别，导致 resume 失败完全无感知
+
+### Hermes 版本
+
+- v0.10.0 (2026.4.16) — 初始测试
+- v0.14.0 (2026.5.16) — 更新后重新测试，bug 仍在
+- 代码路径: ~/.hermes/hermes-agent/acp_adapter/session.py
+
+### v0.14.0 测试结果 (2026-05-23)
+
+- `_restore` 仍因 `custom` provider 解析失败返回 None
+- 日志更清晰了：`WARNING: Failed to recreate agent for ACP session ...`
+- resume fallback 创建新 session（新 sid），但 agent 居然能回答之前的问题（可能通过 memory/session search）
+- 核心问题不变：sessionId 变了，client 用旧 sid 发 prompt → refusal
+
+### 上游 Issue
+
+- https://github.com/NousResearch/hermes-agent/issues/13489 — 已评论根因分析
+- https://github.com/NousResearch/hermes-agent/issues/8083 — resume 静默创建新 session
+- https://github.com/NousResearch/hermes-agent/issues/18452 — _make_agent fallback 不完整
@@ -0,0 +1,77 @@
+name: "debate"
+description: "Structured debate between two sides. Tests cross-process session resume."
+roles:
+  against:
+    description: "Argues against the proposition"
+    goal: |
+      You are a skilled debater arguing AGAINST the proposition.
+      Be logical, cite evidence, and directly address your opponent's points.
+      Keep each argument concise (under 200 words).
+    capabilities:
+      - argumentation
+      - critical-thinking
+    procedure: |
+      1. If this is the opening, present your strongest argument against the proposition.
+      2. If responding to the other side, directly counter their points with evidence and logic.
+      3. If you find yourself genuinely convinced by the other side, you may concede.
+    output: |
+      Provide your argument in the frontmatter.
+      Set conceded to true ONLY if you are genuinely convinced and wish to stop debating.
+    frontmatter:
+      type: object
+      properties:
+        argument:
+          type: string
+        conceded:
+          type: boolean
+      required: [argument, conceded]
+  for:
+    description: "Argues for the proposition"
+    goal: |
+      You are a skilled debater arguing FOR the proposition.
+      Be logical, cite evidence, and directly address your opponent's points.
+      Keep each argument concise (under 200 words).
+    capabilities:
+      - argumentation
+      - critical-thinking
+    procedure: |
+      1. Read the opposing side's latest argument carefully.
+      2. Counter their points with evidence and logic.
+      3. If you find yourself genuinely convinced by the other side, you may concede.
+    output: |
+      Provide your argument in the frontmatter.
+      Set conceded to true ONLY if you are genuinely convinced and wish to stop debating.
+    frontmatter:
+      type: object
+      properties:
+        argument:
+          type: string
+        conceded:
+          type: boolean
+      required: [argument, conceded]
+conditions:
+  againstConceded:
+    description: "The against side conceded"
+    expression: "$last('against').conceded = true"
+  forConceded:
+    description: "The for side conceded"
+    expression: "$last('for').conceded = true"
+graph:
+  $START:
+    - role: "against"
+      condition: null
+      prompt: "Present your opening argument against the proposition."
+  against:
+    - role: "$END"
+      condition: "againstConceded"
+      prompt: "The against side conceded. Debate over."
+    - role: "for"
+      condition: null
+      prompt: "Counter the opposing argument. Address their points directly."
+  for:
+    - role: "$END"
+      condition: "forConceded"
+      prompt: "The for side conceded. Debate over."
+    - role: "against"
+      condition: null
+      prompt: "Counter the opposing argument. Address their points directly."
@@ -3,22 +3,39 @@ description: "End-to-end issue resolution"
 roles:
  planner:
    description: "Creates implementation plan"
-    goal: "You are a planning agent. You analyze issues and create step-by-step plans."
+    goal: "You are a planning agent. You analyze issues and create implementation plans grounded in the actual codebase."
    capabilities:
      - issue-analysis
      - planning
-    procedure: "Analyze the issue and create a detailed, actionable implementation plan."
-    output: "Output the plan summary and list of concrete steps."
+      - file-read
+      - shell
+    procedure: |
+      1. Locate the code repository:
+         - Check if the current working directory is the repo (look for package.json, .git, etc.)
+         - If the task mentions a repo URL, clone it first.
+         - If this is a new project, create the repo and note the path.
+      2. Explore the codebase — read the relevant source files mentioned in the issue. Understand the current architecture, types, and conventions (check CLAUDE.md, CONTRIBUTING.md, .cursor/rules/).
+      3. Identify which files need changes and what the changes should be, with specific code references.
+      4. Output the plan with:
+         - `repoPath`: absolute path to the repository root
+         - `plan`: detailed implementation plan with file paths and code references
+         - `steps`: concrete action items for the developer
+    output: |
+      Provide repoPath, plan summary, and steps in the frontmatter.
+      The plan MUST reference actual file paths and code structures you found by reading the source.
+      Do NOT guess — if you haven't read a file, read it before referencing it.
    frontmatter:
      type: object
      properties:
+        repoPath:
+          type: string
        plan:
          type: string
        steps:
          type: array
          items:
            type: string
-      required: [plan, steps]
+      required: [repoPath, plan, steps]
  developer:
    description: "Implements code changes"
    goal: "You are a developer agent. You implement code changes according to plans."
@@ -26,7 +43,12 @@ roles:
      - file-edit
      - shell
      - testing
-    procedure: "Implement the plan. Write code, tests, and ensure existing tests pass."
+    procedure: |
+      1. Read the planner's output to get the repoPath and implementation plan.
+      2. cd to the repoPath before making any changes.
+      3. Create a feature branch from the default branch.
+      4. Implement the plan — write code, tests, and ensure existing tests pass.
+      5. Commit your changes with a descriptive message referencing the issue.
    output: "List all files changed and provide a summary of the implementation."
    frontmatter:
      type: object
@@ -0,0 +1,181 @@
+import { mkdir, readdir, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import { cmdLogClean, cmdLogList, cmdLogShow } from "../commands/log.js";
+
+let storageRoot: string;
+
+beforeEach(async () => {
+  storageRoot = join(tmpdir(), `uwf-log-test-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+  await mkdir(join(storageRoot, "logs"), { recursive: true });
+});
+
+afterEach(async () => {
+  await rm(storageRoot, { recursive: true, force: true });
+});
+
+const entry1 = JSON.stringify({
+  ts: "2026-05-20T10:00:00.000Z",
+  pid: "1716200000000-1234",
+  tag: "W9F3RK2M",
+  msg: "process start",
+  thread: "01J1234ABCDEF",
+  workflow: "solve-issue",
+});
+
+const entry2 = JSON.stringify({
+  ts: "2026-05-20T10:00:01.000Z",
+  pid: "1716200000000-1234",
+  tag: "ABC12345",
+  msg: "step executed",
+  thread: "01J1234ABCDEF",
+  workflow: "solve-issue",
+});
+
+const entry3 = JSON.stringify({
+  ts: "2026-05-20T10:00:02.000Z",
+  pid: "1716200000000-5678",
+  tag: "XYZ98765",
+  msg: "different process",
+  thread: "01JOTHER000000",
+  workflow: "review-code",
+});
+
+const oldEntry = JSON.stringify({
+  ts: "2026-05-19T08:00:00.000Z",
+  pid: "1716200000000-9999",
+  tag: "OLD1TAG1",
+  msg: "old entry",
+  thread: "01JOLD0000000",
+  workflow: "solve-issue",
+});
+
+const olderEntry = JSON.stringify({
+  ts: "2026-05-18T08:00:00.000Z",
+  pid: "1716200000000-0001",
+  tag: "OLD2TAG2",
+  msg: "older entry",
+  thread: "01JOLDER00000",
+  workflow: "review-code",
+});
+
+async function writeLogFiles(): Promise<void> {
+  const logsDir = join(storageRoot, "logs");
+  await writeFile(join(logsDir, "2026-05-20.jsonl"), [entry1, entry2, entry3].join("\n") + "\n");
+  await writeFile(join(logsDir, "2026-05-19.jsonl"), oldEntry + "\n");
+  await writeFile(join(logsDir, "2026-05-18.jsonl"), olderEntry + "\n");
+}
+
+describe("cmdLogList", () => {
+  test("lists log files with sizes sorted by date descending", async () => {
+    await writeLogFiles();
+    const result = await cmdLogList(storageRoot);
+    expect(result).toHaveLength(3);
+    expect(result[0].name).toBe("2026-05-20.jsonl");
+    expect(result[0].date).toBe("2026-05-20");
+    expect(result[0].size).toBeGreaterThan(0);
+    expect(result[1].name).toBe("2026-05-19.jsonl");
+    expect(result[2].name).toBe("2026-05-18.jsonl");
+  });
+
+  test("returns empty array when no log files exist", async () => {
+    const result = await cmdLogList(storageRoot);
+    expect(result).toEqual([]);
+  });
+
+  test("returns empty array when logs directory does not exist", async () => {
+    const noLogsRoot = join(storageRoot, "nonexistent");
+    await mkdir(noLogsRoot, { recursive: true });
+    const result = await cmdLogList(noLogsRoot);
+    expect(result).toEqual([]);
+  });
+});
+
+describe("cmdLogShow", () => {
+  test("filters by thread ID", async () => {
+    await writeLogFiles();
+    const result = await cmdLogShow(storageRoot, {
+      thread: "01J1234ABCDEF",
+      process: null,
+      date: null,
+    });
+    expect(result).toHaveLength(2);
+    expect(result.every((e) => e.thread === "01J1234ABCDEF")).toBe(true);
+  });
+
+  test("filters by process ID", async () => {
+    await writeLogFiles();
+    const result = await cmdLogShow(storageRoot, {
+      thread: null,
+      process: "1716200000000-1234",
+      date: null,
+    });
+    expect(result).toHaveLength(2);
+    expect(result.every((e) => e.pid === "1716200000000-1234")).toBe(true);
+  });
+
+  test("filters by date", async () => {
+    await writeLogFiles();
+    const result = await cmdLogShow(storageRoot, {
+      thread: null,
+      process: null,
+      date: "2026-05-19",
+    });
+    expect(result).toHaveLength(1);
+    expect(result[0].msg).toBe("old entry");
+  });
+
+  test("reads all files when no date filter", async () => {
+    await writeLogFiles();
+    const result = await cmdLogShow(storageRoot, { thread: null, process: null, date: null });
+    expect(result).toHaveLength(5);
+    // sorted by ts ascending
+    expect(result[0].ts).toBe("2026-05-18T08:00:00.000Z");
+    expect(result[4].ts).toBe("2026-05-20T10:00:02.000Z");
+  });
+
+  test("returns empty when no matches", async () => {
+    await writeLogFiles();
+    const result = await cmdLogShow(storageRoot, {
+      thread: "NONEXISTENT",
+      process: null,
+      date: null,
+    });
+    expect(result).toEqual([]);
+  });
+
+  test("combined thread + date filter", async () => {
+    await writeLogFiles();
+    const result = await cmdLogShow(storageRoot, {
+      thread: "01J1234ABCDEF",
+      process: null,
+      date: "2026-05-20",
+    });
+    expect(result).toHaveLength(2);
+    expect(result.every((e) => e.thread === "01J1234ABCDEF")).toBe(true);
+  });
+});
+
+describe("cmdLogClean", () => {
+  test("deletes files before given date", async () => {
+    await writeLogFiles();
+    const result = await cmdLogClean(storageRoot, "2026-05-20");
+    expect(result.deleted).toBe(2);
+    const remaining = await readdir(join(storageRoot, "logs"));
+    expect(remaining).toEqual(["2026-05-20.jsonl"]);
+  });
+
+  test("deletes nothing when all files are newer", async () => {
+    await writeLogFiles();
+    const result = await cmdLogClean(storageRoot, "2026-05-18");
+    expect(result.deleted).toBe(0);
+  });
+
+  test("handles missing logs directory gracefully", async () => {
+    const noLogsRoot = join(storageRoot, "nonexistent");
+    await mkdir(noLogsRoot, { recursive: true });
+    const result = await cmdLogClean(noLogsRoot, "2026-05-20");
+    expect(result).toEqual({ deleted: 0 });
+  });
+});
@@ -14,6 +14,7 @@ import {
  cmdCasSchemaList,
  cmdCasWalk,
 } from "./commands/cas.js";
+import { cmdLogClean, cmdLogList, cmdLogShow } from "./commands/log.js";
 import { cmdSetup, cmdSetupInteractive } from "./commands/setup.js";
 import { cmdSkillCli } from "./commands/skill.js";
 import {
@@ -379,6 +380,55 @@ casSchema
    });
  });

+const log = program.command("log").description("Process-level debug logs");
+
+log
+  .command("list")
+  .description("List log files with sizes")
+  .action(() => {
+    const storageRoot = resolveStorageRoot();
+    runAction(async () => {
+      const result = await cmdLogList(storageRoot);
+      writeOutput(result);
+    });
+  });
+
+log
+  .command("show")
+  .description("Show and filter log entries")
+  .option("--thread <thread-id>", "Filter by thread ID")
+  .option("--process <pid>", "Filter by process ID")
+  .option("--date <date>", "Filter by date (YYYY-MM-DD)")
+  .action(
+    (opts: {
+      thread: string | undefined;
+      process: string | undefined;
+      date: string | undefined;
+    }) => {
+      const storageRoot = resolveStorageRoot();
+      runAction(async () => {
+        const result = await cmdLogShow(storageRoot, {
+          thread: opts.thread ?? null,
+          process: opts.process ?? null,
+          date: opts.date ?? null,
+        });
+        writeOutput(result);
+      });
+    },
+  );
+
+log
+  .command("clean")
+  .description("Delete log files older than given date")
+  .requiredOption("--before <date>", "Delete files before this date (YYYY-MM-DD)")
+  .action((opts: { before: string }) => {
+    const storageRoot = resolveStorageRoot();
+    runAction(async () => {
+      const result = await cmdLogClean(storageRoot, opts.before);
+      writeOutput(result);
+    });
+  });
+
 program.parseAsync(process.argv).catch((e: unknown) => {
  const message = e instanceof Error ? e.message : String(e);
  process.stderr.write(`${message}\n`);
@@ -0,0 +1,116 @@
+import { readdir, readFile, stat, unlink } from "node:fs/promises";
+import { join } from "node:path";
+
+type LogListItem = {
+  name: string;
+  size: number;
+  date: string;
+};
+
+type LogShowFilter = {
+  thread: string | null;
+  process: string | null;
+  date: string | null;
+};
+
+type LogEntry = {
+  ts: string;
+  pid: string;
+  tag: string;
+  msg: string;
+  thread: string | null;
+  workflow: string | null;
+};
+
+type LogCleanResult = {
+  deleted: number;
+};
+
+function logsDir(storageRoot: string): string {
+  return join(storageRoot, "logs");
+}
+
+async function listLogFiles(dir: string): Promise<Array<string>> {
+  try {
+    const files = await readdir(dir);
+    return files.filter((f) => f.endsWith(".jsonl")).sort();
+  } catch {
+    return [];
+  }
+}
+
+function dateFromFilename(name: string): string {
+  return name.replace(".jsonl", "");
+}
+
+async function parseJsonlFile(path: string): Promise<Array<LogEntry>> {
+  const content = await readFile(path, "utf-8");
+  const lines = content
+    .trim()
+    .split("\n")
+    .filter((l) => l.length > 0);
+  return lines.map((line) => JSON.parse(line) as LogEntry);
+}
+
+export async function cmdLogList(storageRoot: string): Promise<Array<LogListItem>> {
+  const dir = logsDir(storageRoot);
+  const files = await listLogFiles(dir);
+  const items: Array<LogListItem> = [];
+  for (const name of files) {
+    const s = await stat(join(dir, name));
+    items.push({ name, size: s.size, date: dateFromFilename(name) });
+  }
+  // sort by date descending
+  items.sort((a, b) => (a.date > b.date ? -1 : a.date < b.date ? 1 : 0));
+  return items;
+}
+
+export async function cmdLogShow(
+  storageRoot: string,
+  filter: LogShowFilter,
+): Promise<Array<LogEntry>> {
+  const dir = logsDir(storageRoot);
+  let files: Array<string>;
+
+  if (filter.date !== null) {
+    files = [`${filter.date}.jsonl`];
+  } else {
+    files = await listLogFiles(dir);
+  }
+
+  let entries: Array<LogEntry> = [];
+  for (const file of files) {
+    try {
+      const parsed = await parseJsonlFile(join(dir, file));
+      entries = entries.concat(parsed);
+    } catch {
+      // file doesn't exist or is unreadable, skip
+    }
+  }
+
+  if (filter.thread !== null) {
+    entries = entries.filter((e) => e.thread === filter.thread);
+  }
+  if (filter.process !== null) {
+    entries = entries.filter((e) => e.pid === filter.process);
+  }
+
+  entries.sort((a, b) => (a.ts < b.ts ? -1 : a.ts > b.ts ? 1 : 0));
+  return entries;
+}
+
+export async function cmdLogClean(storageRoot: string, before: string): Promise<LogCleanResult> {
+  const dir = logsDir(storageRoot);
+  const files = await listLogFiles(dir);
+  let deleted = 0;
+
+  for (const name of files) {
+    const date = dateFromFilename(name);
+    if (date < before) {
+      await unlink(join(dir, name));
+      deleted++;
+    }
+  }
+
+  return { deleted };
+}
@@ -23,7 +23,7 @@ import type {
  WorkflowConfig,
  WorkflowPayload,
 } from "@uncaged/workflow-protocol";
-import { generateUlid } from "@uncaged/workflow-util";
+import { createProcessLogger, generateUlid, type ProcessLogger } from "@uncaged/workflow-util";
 import { config as loadDotenv } from "dotenv";
 import { parse, stringify } from "yaml";

@@ -47,6 +47,18 @@ import { materializeWorkflowPayload } from "./workflow.js";
 const END_ROLE = "$END";
 export const THREAD_READ_DEFAULT_QUOTA = 4000;

+const PL_THREAD_START = "7HNQ4B2X";
+const PL_MODERATOR = "M3K8V9T1";
+const PL_AGENT_SPAWN = "R5J2W8N4";
+const PL_AGENT_DONE = "C6P9E3H7";
+const PL_THREAD_ARCHIVED = "F4D8Q2K5";
+const PL_STEP_ERROR = "B8T5N1V6";
+
+function failStep(plog: ProcessLogger, message: string): never {
+  plog.log(PL_STEP_ERROR, message, null);
+  fail(message);
+}
+
 type ChainState = {
  startHash: CasRef;
  start: StartNodePayload;
@@ -168,6 +180,10 @@ export async function cmdThreadStart(
  const workflowHash = await resolveWorkflowCasRef(uwf, storageRoot, workflowId, projectRoot);

  const threadId = generateUlid(Date.now()) as ThreadId;
+  const plog = createProcessLogger({
+    storageRoot,
+    context: { thread: threadId, workflow: workflowHash },
+  });
  const startPayload: StartNodePayload = {
    workflow: workflowHash,
    prompt,
@@ -183,6 +199,12 @@ export async function cmdThreadStart(
  index[threadId] = headHash;
  await saveThreadsIndex(storageRoot, index);

+  plog.log(
+    PL_THREAD_START,
+    `thread created workflow=${workflowHash} thread=${threadId} head=${headHash}`,
+    null,
+  );
+
  return { workflow: workflowHash, thread: threadId };
 }

@@ -572,6 +594,7 @@ function buildModeratorContext(uwf: UwfStore, chain: ChainState): ModeratorConte
    output: expandOutput(uwf, step.output),
    detail: step.detail,
    agent: step.agent,
+    edgePrompt: step.edgePrompt ?? "",
  }));
  return { start: chain.start, steps };
 }
@@ -625,6 +648,7 @@ function resolveAgentConfig(
 }

 function spawnAgent(
+  plog: ProcessLogger,
  agent: AgentConfig,
  threadId: ThreadId,
  role: string,
@@ -638,22 +662,23 @@ function spawnAgent(
      encoding: "utf8",
      env,
      stdio: ["ignore", "pipe", "pipe"],
+      maxBuffer: 50 * 1024 * 1024, // 50 MB — stream-json output can be large
    });
  } catch (e) {
-    const err = e as NodeJS.ErrnoException & { stderr?: Buffer | string };
+    const err = e as NodeJS.ErrnoException & { stderr?: Buffer | string | null };
    const stderr =
-      err.stderr === undefined
+      err.stderr == null
        ? ""
        : typeof err.stderr === "string"
          ? err.stderr
          : err.stderr.toString("utf8");
    const detail = stderr.trim() !== "" ? `: ${stderr.trim()}` : "";
-    fail(`agent command failed (${agent.command})${detail}`);
+    failStep(plog, `agent command failed (${agent.command})${detail}`);
  }

  const line = stdout.trim().split("\n").pop()?.trim() ?? "";
  if (!isCasRef(line)) {
-    fail(`agent stdout is not a valid CAS hash: ${line || "(empty)"}`);
+    failStep(plog, `agent stdout is not a valid CAS hash: ${line || "(empty)"}`);
  }
  return line;
 }
@@ -685,9 +710,15 @@ export async function cmdThreadStep(
    fail(`--count must be a positive integer, got: ${count}`);
  }

+  const workflowHash = await resolveActiveThreadWorkflowHash(storageRoot, threadId);
+  const plog = createProcessLogger({
+    storageRoot,
+    context: { thread: threadId, workflow: workflowHash },
+  });
+
  const results: StepOutput[] = [];
  for (let i = 0; i < count; i++) {
-    const result = await cmdThreadStepOnce(storageRoot, threadId, agentOverride);
+    const result = await cmdThreadStepOnce(storageRoot, threadId, agentOverride, plog);
    results.push(result);
    if (result.done) {
      break;
@@ -696,16 +727,31 @@ export async function cmdThreadStep(
  return results;
 }

-async function cmdThreadStepOnce(
+async function resolveActiveThreadWorkflowHash(
  storageRoot: string,
  threadId: ThreadId,
-  agentOverride: string | null,
-): Promise<StepOutput> {
+): Promise<CasRef> {
  const index = await loadThreadsIndex(storageRoot);
  const headHash = index[threadId];
  if (headHash === undefined) {
    fail(`thread not active: ${threadId}`);
  }
+  const uwf = await createUwfStore(storageRoot);
+  const chain = walkChain(uwf, headHash);
+  return chain.start.workflow;
+}
+
+async function cmdThreadStepOnce(
+  storageRoot: string,
+  threadId: ThreadId,
+  agentOverride: string | null,
+  plog: ProcessLogger,
+): Promise<StepOutput> {
+  const index = await loadThreadsIndex(storageRoot);
+  const headHash = index[threadId];
+  if (headHash === undefined) {
+    failStep(plog, `thread not active: ${threadId}`);
+  }

  const uwf = await createUwfStore(storageRoot);
  const chain = walkChain(uwf, headHash);
@@ -715,10 +761,17 @@ async function cmdThreadStepOnce(

  const nextResult = await evaluate(workflow, context);
  if (!nextResult.ok) {
-    fail(nextResult.error.message);
+    failStep(plog, `moderator evaluate failed: ${nextResult.error.message}`);
  }

+  plog.log(
+    PL_MODERATOR,
+    `moderator role=${nextResult.value.role} prompt=${nextResult.value.prompt}`,
+    null,
+  );
+
  if (nextResult.value.role === END_ROLE) {
+    plog.log(PL_THREAD_ARCHIVED, `thread archived head=${headHash}`, null);
    await archiveThread(storageRoot, threadId, workflowHash, headHash);
    return {
      workflow: workflowHash,
@@ -733,14 +786,20 @@ async function cmdThreadStepOnce(
  const config = await loadWorkflowConfig(storageRoot);
  const agent = resolveAgentConfig(config, workflow, role, agentOverride);

+  plog.log(PL_AGENT_SPAWN, `spawning agent command=${agent.command}`, {
+    args: [...agent.args, threadId, role].join(" "),
+  });
+
  loadDotenv({ path: getEnvPath(storageRoot) });
-  const newHead = spawnAgent(agent, threadId, role, edgePrompt);
+  const newHead = spawnAgent(plog, agent, threadId, role, edgePrompt);
+
+  plog.log(PL_AGENT_DONE, `agent returned head=${newHead}`, null);

  // Re-create store to pick up nodes written by the agent subprocess
  const uwfAfter = await createUwfStore(storageRoot);
  const newNode = uwfAfter.store.get(newHead);
  if (newNode === null || newNode.type !== uwfAfter.schemas.stepNode) {
-    fail(`agent returned hash that is not a StepNode: ${newHead}`);
+    failStep(plog, `agent returned hash that is not a StepNode: ${newHead}`);
  }

  // Reload threads index to avoid overwriting changes made by the agent subprocess
@@ -752,11 +811,12 @@ async function cmdThreadStepOnce(
  const contextAfter = buildModeratorContext(uwfAfter, chainAfter);
  const afterResult = await evaluate(workflow, contextAfter);
  if (!afterResult.ok) {
-    fail(afterResult.error.message);
+    failStep(plog, `post-step moderator evaluate failed: ${afterResult.error.message}`);
  }

  const done = afterResult.value.role === END_ROLE;
  if (done) {
+    plog.log(PL_THREAD_ARCHIVED, `thread archived head=${newHead}`, null);
    await archiveThread(storageRoot, threadId, workflowHash, newHead);
  }

@@ -0,0 +1,16 @@
+import { describe, expect, test } from "bun:test";
+
+import type { LlmToolCall } from "../src/llm/types.js";
+
+/** Mirror OpenAI response shape for parser coverage via chatCompletionWithTools integration later. */
+describe("LlmToolCall shape", () => {
+  test("tool call record fields", () => {
+    const call: LlmToolCall = {
+      id: "call_1",
+      name: "read_file",
+      arguments: '{"path":"README.md"}',
+    };
+    expect(call.name).toBe("read_file");
+    expect(JSON.parse(call.arguments)).toEqual({ path: "README.md" });
+  });
+});
@@ -0,0 +1,21 @@
+import { describe, expect, test } from "bun:test";
+import { resolvePath } from "../src/tools/path.js";
+import { resolve } from "node:path";
+
+describe("resolvePath", () => {
+  test("resolves relative paths against cwd", () => {
+    const root = "/workspace/project";
+    const resolved = resolvePath(root, "src/foo.ts");
+    expect(resolved).toBe(resolve(root, "src/foo.ts"));
+  });
+
+  test("resolves absolute paths as-is", () => {
+    const resolved = resolvePath("/workspace", "/etc/hosts");
+    expect(resolved).toBe("/etc/hosts");
+  });
+
+  test("resolves parent traversal normally", () => {
+    const resolved = resolvePath("/workspace/project", "../other/file.ts");
+    expect(resolved).toBe(resolve("/workspace/project", "../other/file.ts"));
+  });
+});
@@ -0,0 +1,236 @@
+import { describe, expect, test } from "bun:test";
+
+import type { AgentContext } from "@uncaged/workflow-agent-kit";
+
+import { buildBuiltinMessages } from "../src/prompt.js";
+
+function minimalContext(overrides: Partial<AgentContext> = {}): AgentContext {
+  return {
+    threadId: "00000000000000000000000000" as AgentContext["threadId"],
+    role: "developer",
+    store: {} as AgentContext["store"],
+    workflow: {
+      name: "test",
+      description: "test workflow",
+      roles: {
+        developer: {
+          description: "Developer role",
+          goal: "Ship the fix",
+          capabilities: ["file-edit"],
+          procedure: "Edit files",
+          output: "A patch",
+          frontmatter: "schema-hash",
+        },
+      },
+      conditions: {},
+      graph: {},
+    },
+    start: { workflow: "wf-hash", prompt: "Fix the bug" },
+    steps: [],
+    outputFormatInstruction: "---\nstatus: done\n---",
+    edgePrompt: "Implement the fix described in the plan.",
+    isFirstVisit: true,
+    ...overrides,
+  };
+}
+
+describe("buildBuiltinMessages", () => {
+  test("system includes output format and role goal", () => {
+    const messages = buildBuiltinMessages(minimalContext());
+    const system = messages[0];
+    expect(system?.role).toBe("system");
+    if (system?.role === "system") {
+      expect(system.content).toContain("status: done");
+      expect(system.content).toContain("## Goal");
+      expect(system.content).toContain("Ship the fix");
+    }
+  });
+
+  test("first visit produces system + single user message with edge prompt", () => {
+    const messages = buildBuiltinMessages(minimalContext());
+    expect(messages).toHaveLength(2);
+    expect(messages[1]?.role).toBe("user");
+    if (messages[1]?.role === "user") {
+      expect(messages[1].content).toContain("Implement the fix");
+      expect(messages[1].content).not.toContain("## What Happened Since Your Last Turn");
+    }
+  });
+
+  test("first visit with prior steps includes inter-step summary in final user message", () => {
+    const messages = buildBuiltinMessages(
+      minimalContext({
+        steps: [
+          {
+            role: "planner",
+            output: { plan: "step 1" },
+            agent: "uwf-builtin",
+            detail: "detail-hash",
+            edgePrompt: "Create a plan.",
+          },
+        ],
+      }),
+    );
+    expect(messages).toHaveLength(2);
+    const finalUser = messages[1];
+    if (finalUser?.role === "user") {
+      expect(finalUser.content).toContain("Implement the fix");
+      expect(finalUser.content).toContain("## What Happened Since Your Last Turn");
+      expect(finalUser.content).toContain("planner");
+    }
+  });
+
+  test("re-entry reconstructs prior user/assistant turns plus current user message", () => {
+    const messages = buildBuiltinMessages(
+      minimalContext({
+        isFirstVisit: false,
+        edgePrompt: "Fix the reviewer's feedback.",
+        steps: [
+          {
+            role: "developer",
+            output: { summary: "Initial fix" },
+            agent: "uwf-builtin",
+            detail: "detail-1",
+            edgePrompt: "Implement the fix.",
+          },
+          {
+            role: "reviewer",
+            output: { approved: false, comments: "Missing tests" },
+            agent: "uwf-builtin",
+            detail: "detail-2",
+            edgePrompt: "Review the implementation.",
+          },
+        ],
+      }),
+    );
+
+    expect(messages).toHaveLength(4);
+    expect(messages[0]?.role).toBe("system");
+    expect(messages[1]?.role).toBe("user");
+    expect(messages[2]?.role).toBe("assistant");
+    expect(messages[3]?.role).toBe("user");
+
+    if (messages[1]?.role === "user") {
+      expect(messages[1].content).toBe("Implement the fix.");
+    }
+    if (messages[2]?.role === "assistant") {
+      expect(messages[2].content).toBe(JSON.stringify({ summary: "Initial fix" }));
+    }
+    if (messages[3]?.role === "user") {
+      expect(messages[3].content).toContain("Fix the reviewer's feedback.");
+      expect(messages[3].content).toContain("## What Happened Since Your Last Turn");
+      expect(messages[3].content).toContain("reviewer");
+      expect(messages[3].content).toContain("Missing tests");
+    }
+  });
+
+  test("prefix is stable across re-entry for LLM cache hits", () => {
+    const firstVisitMessages = buildBuiltinMessages(
+      minimalContext({
+        edgePrompt: "Implement the fix.",
+        steps: [],
+      }),
+    );
+
+    const reEntryMessages = buildBuiltinMessages(
+      minimalContext({
+        isFirstVisit: false,
+        edgePrompt: "Fix the reviewer's feedback.",
+        steps: [
+          {
+            role: "developer",
+            output: { summary: "Initial fix" },
+            agent: "uwf-builtin",
+            detail: "detail-1",
+            edgePrompt: "Implement the fix.",
+          },
+          {
+            role: "reviewer",
+            output: { approved: false },
+            agent: "uwf-builtin",
+            detail: "detail-2",
+            edgePrompt: "Review the code.",
+          },
+        ],
+      }),
+    );
+
+    expect(reEntryMessages[0]).toEqual(firstVisitMessages[0]);
+    expect(reEntryMessages[1]).toEqual(firstVisitMessages[1]);
+    expect(reEntryMessages[2]?.role).toBe("assistant");
+    if (reEntryMessages[2]?.role === "assistant") {
+      expect(reEntryMessages[2].content).toBe(JSON.stringify({ summary: "Initial fix" }));
+    }
+    expect(reEntryMessages[3]?.role).toBe("user");
+    if (reEntryMessages[3]?.role === "user") {
+      expect(reEntryMessages[3].content).toContain("Fix the reviewer's feedback.");
+    }
+  });
+
+  test("multiple prior visits emit one user/assistant pair per visit", () => {
+    const messages = buildBuiltinMessages(
+      minimalContext({
+        isFirstVisit: false,
+        edgePrompt: "Third round fix.",
+        steps: [
+          {
+            role: "developer",
+            output: { round: 1 },
+            agent: "uwf-builtin",
+            detail: "d1",
+            edgePrompt: "First attempt.",
+          },
+          {
+            role: "reviewer",
+            output: { approved: false },
+            agent: "uwf-builtin",
+            detail: "d2",
+            edgePrompt: "Review round 1.",
+          },
+          {
+            role: "developer",
+            output: { round: 2 },
+            agent: "uwf-builtin",
+            detail: "d3",
+            edgePrompt: "Second attempt.",
+          },
+          {
+            role: "reviewer",
+            output: { approved: false },
+            agent: "uwf-builtin",
+            detail: "d4",
+            edgePrompt: "Review round 2.",
+          },
+        ],
+      }),
+    );
+
+    expect(messages).toHaveLength(6);
+    expect(messages.map((m) => m.role)).toEqual([
+      "system",
+      "user",
+      "assistant",
+      "user",
+      "assistant",
+      "user",
+    ]);
+
+    if (messages[1]?.role === "user") {
+      expect(messages[1].content).toBe("First attempt.");
+    }
+    if (messages[2]?.role === "assistant") {
+      expect(messages[2].content).toBe(JSON.stringify({ round: 1 }));
+    }
+    if (messages[3]?.role === "user") {
+      expect(messages[3].content).toContain("Second attempt.");
+      expect(messages[3].content).toContain("reviewer");
+    }
+    if (messages[4]?.role === "assistant") {
+      expect(messages[4].content).toBe(JSON.stringify({ round: 2 }));
+    }
+    if (messages[5]?.role === "user") {
+      expect(messages[5].content).toContain("Third round fix.");
+      expect(messages[5].content).toContain("### Step 4: reviewer");
+      expect(messages[5].content).toContain('"approved":false');
+    }
+  });
+});
@@ -0,0 +1,34 @@
+{
+  "name": "@uncaged/workflow-agent-builtin",
+  "version": "0.5.0",
+  "files": [
+    "src",
+    "dist",
+    "package.json"
+  ],
+  "type": "module",
+  "bin": {
+    "uwf-builtin": "./src/cli.ts"
+  },
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@uncaged/json-cas": "^0.4.0",
+    "@uncaged/workflow-agent-kit": "workspace:^",
+    "@uncaged/workflow-util": "workspace:^"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}
@@ -0,0 +1,122 @@
+import type { Store } from "@uncaged/json-cas";
+import {
+  type AgentContext,
+  type AgentRunResult,
+  createAgent,
+  loadWorkflowConfig,
+  resolveModel,
+  resolveStorageRoot,
+} from "@uncaged/workflow-agent-kit";
+import { generateUlid } from "@uncaged/workflow-util";
+
+import { storeBuiltinDetail } from "./detail.js";
+import type { ChatMessage } from "./llm/index.js";
+import { BUILTIN_CONTINUE_MAX_TURNS, BUILTIN_MAX_TURNS, runBuiltinLoop } from "./loop.js";
+import { buildBuiltinMessages } from "./prompt.js";
+import type { BuiltinSessionState } from "./types.js";
+
+const sessions = new Map<string, BuiltinSessionState>();
+
+function getSession(sessionId: string): BuiltinSessionState {
+  const session = sessions.get(sessionId);
+  if (session === undefined) {
+    throw new Error(`builtin session not found: ${sessionId}`);
+  }
+  return session;
+}
+
+function buildToolContext(storageRoot: string): { cwd: string; storageRoot: string } {
+  return {
+    cwd: process.cwd(),
+    storageRoot,
+  };
+}
+
+async function runBuiltinWithMessages(
+  storageRoot: string,
+  provider: ReturnType<typeof resolveModel>,
+  messages: ChatMessage[],
+  session: BuiltinSessionState,
+  store: Store,
+  maxTurns: number,
+): Promise<AgentRunResult> {
+  const loopResult = await runBuiltinLoop({
+    provider,
+    messages,
+    toolCtx: buildToolContext(storageRoot),
+    maxTurns,
+    existingTurns: session.turns,
+  });
+
+  session.messages = loopResult.messages;
+  session.turns = loopResult.turns;
+
+  const { detailHash, output } = await storeBuiltinDetail(
+    store,
+    session.sessionId,
+    session.model,
+    session.startedAtMs,
+    session.turns,
+  );
+
+  const finalOutput = output !== "" ? output : loopResult.finalText;
+  return { output: finalOutput, detailHash, sessionId: session.sessionId };
+}
+
+async function runBuiltin(ctx: AgentContext): Promise<AgentRunResult> {
+  const storageRoot = resolveStorageRoot();
+  const config = await loadWorkflowConfig(storageRoot);
+  const provider = resolveModel(config, config.defaultModel);
+
+  const sessionId = generateUlid(Date.now());
+  const messages = buildBuiltinMessages(ctx);
+
+  const session: BuiltinSessionState = {
+    sessionId,
+    model: provider.model,
+    startedAtMs: Date.now(),
+    messages,
+    turns: [],
+  };
+  sessions.set(sessionId, session);
+
+  return runBuiltinWithMessages(
+    storageRoot,
+    provider,
+    messages,
+    session,
+    ctx.store,
+    BUILTIN_MAX_TURNS,
+  );
+}
+
+async function continueBuiltin(
+  sessionId: string,
+  message: string,
+  store: Store,
+): Promise<AgentRunResult> {
+  const session = getSession(sessionId);
+  const storageRoot = resolveStorageRoot();
+  const config = await loadWorkflowConfig(storageRoot);
+  const provider = resolveModel(config, config.defaultModel);
+
+  const messages: ChatMessage[] = [...session.messages, { role: "user", content: message }];
+
+  return runBuiltinWithMessages(
+    storageRoot,
+    provider,
+    messages,
+    session,
+    store,
+    BUILTIN_CONTINUE_MAX_TURNS,
+  );
+}
+
+/** Agent CLI factory: built-in LLM loop with file/shell tools. */
+export function createBuiltinAgent(): () => Promise<void> {
+  return createAgent({
+    name: "builtin",
+    run: runBuiltin,
+    continue: continueBuiltin,
+  });
+}
@@ -0,0 +1,6 @@
+#!/usr/bin/env bun
+
+import { createBuiltinAgent } from "./agent.js";
+
+const main = createBuiltinAgent();
+void main();
@@ -0,0 +1,115 @@
+import { bootstrap, putSchema, type Store } from "@uncaged/json-cas";
+
+import { BUILTIN_DETAIL_SCHEMA, BUILTIN_TURN_SCHEMA } from "./schemas.js";
+import type {
+  BuiltinDetailPayload,
+  BuiltinLoopTurn,
+  BuiltinToolCall,
+  BuiltinTurnPayload,
+  BuiltinTurnRole,
+} from "./types.js";
+
+function mapToolCalls(calls: NonNullable<BuiltinLoopTurn["toolCalls"]>): BuiltinToolCall[] {
+  return calls.map((call) => ({
+    name: call.name,
+    args: call.args,
+  }));
+}
+
+function loopTurnToAssistantPayload(turn: BuiltinLoopTurn, index: number): BuiltinTurnPayload {
+  return {
+    index,
+    role: "assistant",
+    content: turn.assistantContent ?? "",
+    toolCalls:
+      turn.toolCalls !== null && turn.toolCalls.length > 0 ? mapToolCalls(turn.toolCalls) : null,
+    reasoning: null,
+  };
+}
+
+function loopTurnToToolPayloads(turn: BuiltinLoopTurn, startIndex: number): BuiltinTurnPayload[] {
+  if (turn.toolResults === null || turn.toolResults.length === 0) {
+    return [];
+  }
+  const payloads: BuiltinTurnPayload[] = [];
+  let index = startIndex;
+  for (const result of turn.toolResults) {
+    payloads.push({
+      index,
+      role: "tool" as BuiltinTurnRole,
+      content: result.content,
+      toolCalls: null,
+      reasoning: null,
+    });
+    index += 1;
+  }
+  return payloads;
+}
+
+/** Last assistant message with non-empty text. */
+export function extractFinalAssistantText(turns: BuiltinLoopTurn[]): string {
+  for (let i = turns.length - 1; i >= 0; i--) {
+    const turn = turns[i];
+    if (turn === undefined) {
+      continue;
+    }
+    const text = turn.assistantContent;
+    if (text !== null && text.trim() !== "") {
+      return text;
+    }
+  }
+  return "";
+}
+
+type BuiltinSchemaHashes = {
+  turn: string;
+  detail: string;
+};
+
+async function registerBuiltinSchemas(store: Store): Promise<BuiltinSchemaHashes> {
+  await bootstrap(store);
+  const [turn, detail] = await Promise.all([
+    putSchema(store, BUILTIN_TURN_SCHEMA),
+    putSchema(store, BUILTIN_DETAIL_SCHEMA),
+  ]);
+  return { turn, detail };
+}
+
+export async function storeBuiltinDetail(
+  store: Store,
+  sessionId: string,
+  model: string,
+  startedAtMs: number,
+  turns: BuiltinLoopTurn[],
+  nowMs: number = Date.now(),
+): Promise<{ detailHash: string; output: string }> {
+  const schemas = await registerBuiltinSchemas(store);
+  const turnHashes: string[] = [];
+  let turnIndex = 0;
+
+  for (const loopTurn of turns) {
+    const assistant = loopTurnToAssistantPayload(loopTurn, turnIndex);
+    const assistantHash = await store.put(schemas.turn, assistant);
+    turnHashes.push(assistantHash);
+    turnIndex += 1;
+
+    const toolPayloads = loopTurnToToolPayloads(loopTurn, turnIndex);
+    for (const toolPayload of toolPayloads) {
+      const toolHash = await store.put(schemas.turn, toolPayload);
+      turnHashes.push(toolHash);
+      turnIndex += 1;
+    }
+  }
+
+  const duration = Math.max(0, nowMs - startedAtMs);
+  const detail: BuiltinDetailPayload = {
+    sessionId,
+    model,
+    duration,
+    turnCount: turnHashes.length,
+    turns: turnHashes,
+  };
+  const detailHash = await store.put(schemas.detail, detail);
+  const output = extractFinalAssistantText(turns);
+  return { detailHash, output };
+}
@@ -0,0 +1,14 @@
+export { createBuiltinAgent } from "./agent.js";
+export { extractFinalAssistantText, storeBuiltinDetail } from "./detail.js";
+export type { ChatMessage, LlmAssistantResponse, LlmToolCall } from "./llm/index.js";
+export { chatCompletionWithTools } from "./llm/index.js";
+export { BUILTIN_CONTINUE_MAX_TURNS, BUILTIN_MAX_TURNS, runBuiltinLoop } from "./loop.js";
+export { buildBuiltinMessages } from "./prompt.js";
+export type { BuiltinTool, ToolContext } from "./tools/index.js";
+export { executeBuiltinTool, getBuiltinTools } from "./tools/index.js";
+export type {
+  BuiltinDetailPayload,
+  BuiltinLoopTurn,
+  BuiltinSessionState,
+  BuiltinTurnPayload,
+} from "./types.js";
@@ -0,0 +1,7 @@
+export { chatCompletionWithTools } from "./llm.js";
+export type {
+  ChatMessage,
+  LlmAssistantResponse,
+  LlmToolCall,
+  OpenAiToolDefinition,
+} from "./types.js";
@@ -0,0 +1,135 @@
+import type { ResolvedLlmProvider } from "@uncaged/workflow-agent-kit";
+
+import type {
+  ChatMessage,
+  LlmAssistantResponse,
+  LlmToolCall,
+  OpenAiToolDefinition,
+} from "./types.js";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function chatUrl(baseUrl: string): string {
+  const trimmed = baseUrl.replace(/\/+$/, "");
+  return `${trimmed}/chat/completions`;
+}
+
+function parseToolCalls(raw: unknown): LlmToolCall[] | null {
+  if (!Array.isArray(raw) || raw.length === 0) {
+    return null;
+  }
+  const calls: LlmToolCall[] = [];
+  for (const entry of raw) {
+    if (!isRecord(entry)) {
+      continue;
+    }
+    const id = entry.id;
+    const fn = entry.function;
+    if (typeof id !== "string" || !isRecord(fn)) {
+      continue;
+    }
+    const name = fn.name;
+    const args = fn.arguments;
+    if (typeof name !== "string" || typeof args !== "string") {
+      continue;
+    }
+    calls.push({ id, name, arguments: args });
+  }
+  return calls.length > 0 ? calls : null;
+}
+
+function parseAssistantMessage(parsed: unknown): LlmAssistantResponse {
+  if (!isRecord(parsed)) {
+    throw new Error("LLM response is not an object");
+  }
+  const choices = parsed.choices;
+  if (!Array.isArray(choices) || choices.length === 0) {
+    throw new Error("LLM response has no choices");
+  }
+  const c0 = choices[0];
+  if (!isRecord(c0)) {
+    throw new Error("LLM choice is not an object");
+  }
+  const messageObj = c0.message;
+  if (!isRecord(messageObj)) {
+    throw new Error("LLM message is not an object");
+  }
+  const contentRaw = messageObj.content;
+  const content =
+    typeof contentRaw === "string"
+      ? contentRaw
+      : contentRaw === null || contentRaw === undefined
+        ? null
+        : null;
+  const toolCalls = parseToolCalls(messageObj.tool_calls);
+  return { content, toolCalls };
+}
+
+function serializeMessage(message: ChatMessage): Record<string, unknown> {
+  if (message.role === "tool") {
+    return {
+      role: "tool",
+      tool_call_id: message.tool_call_id,
+      content: message.content,
+    };
+  }
+  if (message.role === "assistant") {
+    const base: Record<string, unknown> = {
+      role: "assistant",
+      content: message.content,
+    };
+    if (message.tool_calls !== null && message.tool_calls.length > 0) {
+      base.tool_calls = message.tool_calls.map((call) => ({
+        id: call.id,
+        type: "function",
+        function: { name: call.name, arguments: call.arguments },
+      }));
+    }
+    return base;
+  }
+  return { role: message.role, content: message.content };
+}
+
+/** OpenAI-compatible chat completion with tool calling (non-streaming). */
+export async function chatCompletionWithTools(
+  provider: ResolvedLlmProvider,
+  messages: ChatMessage[],
+  tools: OpenAiToolDefinition[],
+): Promise<LlmAssistantResponse> {
+  let response: Response;
+  try {
+    response = await fetch(chatUrl(provider.baseUrl), {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${provider.apiKey}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        model: provider.model,
+        messages: messages.map(serializeMessage),
+        tools,
+        tool_choice: "auto",
+      }),
+    });
+  } catch (cause) {
+    const message = cause instanceof Error ? cause.message : String(cause);
+    throw new Error(`LLM network error: ${message}`);
+  }
+
+  const responseText = await response.text();
+  if (!response.ok) {
+    throw new Error(`LLM HTTP ${response.status}: ${responseText.slice(0, 2000)}`);
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(responseText) as unknown;
+  } catch (cause) {
+    const message = cause instanceof Error ? cause.message : String(cause);
+    throw new Error(`LLM invalid JSON response: ${message}`);
+  }
+
+  return parseAssistantMessage(parsed);
+}
@@ -0,0 +1,29 @@
+export type LlmToolCall = {
+  id: string;
+  name: string;
+  arguments: string;
+};
+
+export type LlmAssistantResponse = {
+  content: string | null;
+  toolCalls: LlmToolCall[] | null;
+};
+
+export type ChatMessage =
+  | { role: "system"; content: string }
+  | { role: "user"; content: string }
+  | {
+      role: "assistant";
+      content: string | null;
+      tool_calls: LlmToolCall[] | null;
+    }
+  | { role: "tool"; tool_call_id: string; content: string };
+
+export type OpenAiToolDefinition = {
+  type: "function";
+  function: {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+  };
+};
@@ -0,0 +1,110 @@
+import type { ResolvedLlmProvider } from "@uncaged/workflow-agent-kit";
+import { createLogger } from "@uncaged/workflow-util";
+
+import { type ChatMessage, chatCompletionWithTools, type LlmToolCall } from "./llm/index.js";
+import {
+  builtinToolsToOpenAi,
+  executeBuiltinTool,
+  getBuiltinTools,
+  type ToolContext,
+} from "./tools/index.js";
+import type { BuiltinLoopTurn, BuiltinToolCallRecord, BuiltinToolResultRecord } from "./types.js";
+
+const log = createLogger({ sink: { kind: "stderr" } });
+
+export const BUILTIN_MAX_TURNS = 30;
+export const BUILTIN_CONTINUE_MAX_TURNS = 5;
+
+export type RunBuiltinLoopOptions = {
+  provider: ResolvedLlmProvider;
+  messages: ChatMessage[];
+  toolCtx: ToolContext;
+  maxTurns: number;
+  existingTurns: BuiltinLoopTurn[];
+};
+
+export type RunBuiltinLoopResult = {
+  finalText: string;
+  messages: ChatMessage[];
+  turns: BuiltinLoopTurn[];
+};
+
+function mapToolCalls(calls: LlmToolCall[]): BuiltinToolCallRecord[] {
+  return calls.map((call) => ({
+    id: call.id,
+    name: call.name,
+    args: call.arguments,
+  }));
+}
+
+/** Agent run loop: LLM ↔ tools until no tool_calls or maxTurns. */
+export async function runBuiltinLoop(
+  options: RunBuiltinLoopOptions,
+): Promise<RunBuiltinLoopResult> {
+  const messages = [...options.messages];
+  const turns = [...options.existingTurns];
+  const openAiTools = builtinToolsToOpenAi(getBuiltinTools());
+  let finalText = "";
+
+  for (let turn = 0; turn < options.maxTurns; turn++) {
+    log("8K2M4N7P", `builtin loop turn ${turn + 1}/${options.maxTurns}`);
+    const response = await chatCompletionWithTools(options.provider, messages, openAiTools);
+
+    const assistantMessage: ChatMessage = {
+      role: "assistant",
+      content: response.content,
+      tool_calls: response.toolCalls,
+    };
+    messages.push(assistantMessage);
+
+    if (response.toolCalls === null || response.toolCalls.length === 0) {
+      finalText = response.content ?? "";
+      turns.push({
+        assistantContent: response.content,
+        toolCalls: null,
+        toolResults: null,
+      });
+      break;
+    }
+
+    const toolCallRecords = mapToolCalls(response.toolCalls);
+    const toolResults: BuiltinToolResultRecord[] = [];
+
+    for (const call of response.toolCalls) {
+      const result = await executeBuiltinTool(call.name, call.arguments, options.toolCtx);
+      toolResults.push({
+        toolCallId: call.id,
+        name: call.name,
+        content: result,
+      });
+      messages.push({
+        role: "tool",
+        tool_call_id: call.id,
+        content: result,
+      });
+    }
+
+    turns.push({
+      assistantContent: response.content,
+      toolCalls: toolCallRecords,
+      toolResults,
+    });
+  }
+
+  if (finalText === "" && messages.length > 0) {
+    for (let i = messages.length - 1; i >= 0; i--) {
+      const msg = messages[i];
+      if (
+        msg !== undefined &&
+        msg.role === "assistant" &&
+        msg.content !== null &&
+        msg.content.trim() !== ""
+      ) {
+        finalText = msg.content;
+        break;
+      }
+    }
+  }
+
+  return { finalText, messages, turns };
+}
@@ -0,0 +1,99 @@
+import { type AgentContext, buildRolePrompt } from "@uncaged/workflow-agent-kit";
+
+import type { ChatMessage } from "./llm/index.js";
+
+type StepContext = AgentContext["steps"][number];
+
+function formatStep(step: StepContext, stepNumber: number): string {
+  return [
+    `### Step ${stepNumber}: ${step.role}`,
+    `Output: ${JSON.stringify(step.output)}`,
+    `Agent: ${step.agent}`,
+  ].join("\n");
+}
+
+function buildStepsSummary(steps: StepContext[], fromIndex: number, toIndex: number): string {
+  if (fromIndex >= toIndex) {
+    return "";
+  }
+
+  const lines: string[] = ["## What Happened Since Your Last Turn"];
+  for (let i = fromIndex; i < toIndex; i++) {
+    const step = steps[i];
+    if (step === undefined) {
+      continue;
+    }
+    lines.push("");
+    lines.push(formatStep(step, i + 1));
+  }
+  return lines.join("\n");
+}
+
+function buildUserTurnContent(edgePrompt: string, summary: string): string {
+  const parts: string[] = [];
+  if (edgePrompt !== "") {
+    parts.push(edgePrompt);
+  }
+  if (summary !== "") {
+    if (parts.length > 0) {
+      parts.push("");
+    }
+    parts.push(summary);
+  }
+  return parts.join("\n");
+}
+
+/**
+ * Reconstruct multi-turn chat messages from thread history for cache-friendly session resume.
+ *
+ * - system: role prompt + output format (stable prefix)
+ * - For each prior visit of this role: user (edgePrompt + inter-step summary) + assistant (output JSON)
+ * - Final user: current edgePrompt + summary since last visit of this role
+ */
+export function buildBuiltinMessages(ctx: AgentContext): ChatMessage[] {
+  const roleDef = ctx.workflow.roles[ctx.role];
+  const rolePrompt = roleDef !== undefined ? buildRolePrompt(roleDef) : "";
+  const systemParts: string[] = [];
+  if (ctx.outputFormatInstruction !== "") {
+    systemParts.push(ctx.outputFormatInstruction, "");
+  }
+  systemParts.push(rolePrompt);
+
+  const messages: ChatMessage[] = [{ role: "system", content: systemParts.join("\n") }];
+
+  const roleVisitIndices: number[] = [];
+  for (let i = 0; i < ctx.steps.length; i++) {
+    const step = ctx.steps[i];
+    if (step !== undefined && step.role === ctx.role) {
+      roleVisitIndices.push(i);
+    }
+  }
+
+  let prevVisitIndex = -1;
+  for (const visitIndex of roleVisitIndices) {
+    const visitStep = ctx.steps[visitIndex];
+    if (visitStep === undefined) {
+      continue;
+    }
+
+    const summary = buildStepsSummary(ctx.steps, prevVisitIndex + 1, visitIndex);
+    messages.push({
+      role: "user",
+      content: buildUserTurnContent(visitStep.edgePrompt, summary),
+    });
+    messages.push({
+      role: "assistant",
+      content: JSON.stringify(visitStep.output),
+      tool_calls: null,
+    });
+    prevVisitIndex = visitIndex;
+  }
+
+  const finalSummary = buildStepsSummary(ctx.steps, prevVisitIndex + 1, ctx.steps.length);
+  messages.push({
+    role: "user",
+    content: buildUserTurnContent(ctx.edgePrompt, finalSummary),
+  });
+
+  return messages;
+}
@@ -0,0 +1,46 @@
+import type { JSONSchema } from "@uncaged/json-cas";
+
+const BUILTIN_TOOL_CALL_SCHEMA: JSONSchema = {
+  type: "object",
+  required: ["name", "args"],
+  properties: {
+    name: { type: "string" },
+    args: { type: "string" },
+  },
+  additionalProperties: false,
+};
+
+export const BUILTIN_TURN_SCHEMA: JSONSchema = {
+  title: "builtin-turn",
+  type: "object",
+  required: ["index", "role", "content"],
+  properties: {
+    index: { type: "integer" },
+    role: { type: "string", enum: ["assistant", "tool"] },
+    content: { type: "string" },
+    toolCalls: {
+      anyOf: [{ type: "array", items: BUILTIN_TOOL_CALL_SCHEMA }, { type: "null" }],
+    },
+    reasoning: {
+      anyOf: [{ type: "string" }, { type: "null" }],
+    },
+  },
+  additionalProperties: false,
+};
+
+export const BUILTIN_DETAIL_SCHEMA: JSONSchema = {
+  title: "builtin-detail",
+  type: "object",
+  required: ["sessionId", "model", "duration", "turnCount", "turns"],
+  properties: {
+    sessionId: { type: "string" },
+    model: { type: "string" },
+    duration: { type: "integer" },
+    turnCount: { type: "integer" },
+    turns: {
+      type: "array",
+      items: { type: "string", format: "cas_ref" },
+    },
+  },
+  additionalProperties: false,
+};
@@ -0,0 +1,44 @@
+import type { OpenAiToolDefinition } from "../llm/index.js";
+
+import { readFileTool } from "./read-file.js";
+import { runCommandTool } from "./run-command.js";
+import type { BuiltinTool, ToolContext } from "./types.js";
+import { writeFileTool } from "./write-file.js";
+
+export { resolvePath } from "./path.js";
+export type { BuiltinTool, ToolContext } from "./types.js";
+
+const BUILTIN_TOOLS: BuiltinTool[] = [readFileTool, writeFileTool, runCommandTool];
+
+export function getBuiltinTools(): readonly BuiltinTool[] {
+  return BUILTIN_TOOLS;
+}
+
+export function builtinToolsToOpenAi(tools: readonly BuiltinTool[]): OpenAiToolDefinition[] {
+  return tools.map((tool) => ({
+    type: "function",
+    function: {
+      name: tool.name,
+      description: tool.description,
+      parameters: tool.parameters as Record<string, unknown>,
+    },
+  }));
+}
+
+export async function executeBuiltinTool(
+  name: string,
+  argsJson: string,
+  ctx: ToolContext,
+): Promise<string> {
+  const tool = BUILTIN_TOOLS.find((t) => t.name === name);
+  if (tool === undefined) {
+    return `Error: unknown tool ${name}`;
+  }
+  let args: unknown;
+  try {
+    args = JSON.parse(argsJson) as unknown;
+  } catch {
+    return "Error: tool arguments must be valid JSON";
+  }
+  return tool.execute(args, ctx);
+}
@@ -0,0 +1,6 @@
+import { resolve } from "node:path";
+
+/** Resolve a path relative to the working directory. */
+export function resolvePath(cwd: string, inputPath: string): string {
+  return resolve(cwd, inputPath);
+}
@@ -0,0 +1,41 @@
+import { readFile, stat } from "node:fs/promises";
+import { resolvePath } from "./path.js";
+import type { BuiltinTool } from "./types.js";
+
+const MAX_READ_BYTES = 512 * 1024;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export const readFileTool: BuiltinTool = {
+  name: "read_file",
+  description: "Read a UTF-8 text file from the workspace.",
+  parameters: {
+    type: "object",
+    required: ["path"],
+    properties: {
+      path: { type: "string", description: "Relative or absolute path within the workspace." },
+    },
+    additionalProperties: false,
+  },
+  execute: async (args, ctx) => {
+    if (!isRecord(args) || typeof args.path !== "string") {
+      return "Error: path must be a string";
+    }
+    const resolved = resolvePath(ctx.cwd, args.path);
+    try {
+      const info = await stat(resolved);
+      if (!info.isFile()) {
+        return "Error: not a file";
+      }
+      if (info.size > MAX_READ_BYTES) {
+        return `Error: file exceeds ${MAX_READ_BYTES} byte limit`;
+      }
+      return await readFile(resolved, "utf8");
+    } catch (cause) {
+      const message = cause instanceof Error ? cause.message : String(cause);
+      return `Error: ${message}`;
+    }
+  },
+};
@@ -0,0 +1,96 @@
+import { spawn } from "node:child_process";
+import { resolvePath } from "./path.js";
+import type { BuiltinTool } from "./types.js";
+
+const COMMAND_TIMEOUT_MS = 60_000;
+const MAX_OUTPUT_CHARS = 32_000;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function truncate(text: string, maxChars: number): string {
+  if (text.length <= maxChars) {
+    return text;
+  }
+  return `${text.slice(0, maxChars)}\n...(truncated)`;
+}
+
+function runShell(
+  command: string,
+  cwd: string,
+): Promise<{ stdout: string; stderr: string; code: number }> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, {
+      cwd,
+      env: process.env,
+      shell: true,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+
+    let stdout = "";
+    let stderr = "";
+    child.stdout?.on("data", (chunk: Buffer) => {
+      stdout += chunk.toString();
+    });
+    child.stderr?.on("data", (chunk: Buffer) => {
+      stderr += chunk.toString();
+    });
+
+    const timer = setTimeout(() => {
+      child.kill("SIGTERM");
+    }, COMMAND_TIMEOUT_MS);
+
+    child.on("error", (cause) => {
+      clearTimeout(timer);
+      const message = cause instanceof Error ? cause.message : String(cause);
+      reject(new Error(message));
+    });
+
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      resolve({ stdout, stderr, code: code ?? 1 });
+    });
+  });
+}
+
+export const runCommandTool: BuiltinTool = {
+  name: "run_command",
+  description:
+    "Run a shell command. Output is truncated to 32KB.",
+  parameters: {
+    type: "object",
+    required: ["command"],
+    properties: {
+      command: { type: "string", description: "Shell command to execute." },
+      cwd: {
+        type: "string",
+        description: "Optional working directory relative to workspace root.",
+      },
+    },
+    additionalProperties: false,
+  },
+  execute: async (args, ctx) => {
+    if (!isRecord(args) || typeof args.command !== "string") {
+      return "Error: command must be a string";
+    }
+    let workDir = ctx.cwd;
+    if (args.cwd !== undefined && args.cwd !== null) {
+      if (typeof args.cwd !== "string") {
+        return "Error: cwd must be a string";
+      }
+      workDir = resolvePath(ctx.cwd, args.cwd);
+    }
+    try {
+      const { stdout, stderr, code } = await runShell(args.command, workDir);
+      const out = truncate(
+        `exit_code: ${code}\n--- stdout ---\n${stdout}\n--- stderr ---\n${stderr}`,
+        MAX_OUTPUT_CHARS,
+      );
+      return out;
+    } catch (cause) {
+      const message = cause instanceof Error ? cause.message : String(cause);
+      return `Error: ${message}`;
+    }
+  },
+};
@@ -0,0 +1,13 @@
+import type { JSONSchema } from "@uncaged/json-cas";
+
+export type ToolContext = {
+  cwd: string;
+  storageRoot: string;
+};
+
+export type BuiltinTool = {
+  name: string;
+  description: string;
+  parameters: JSONSchema;
+  execute: (args: unknown, ctx: ToolContext) => Promise<string>;
+};
@@ -0,0 +1,36 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { resolvePath } from "./path.js";
+import type { BuiltinTool } from "./types.js";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export const writeFileTool: BuiltinTool = {
+  name: "write_file",
+  description: "Write UTF-8 text to a file in the workspace (creates parent directories).",
+  parameters: {
+    type: "object",
+    required: ["path", "content"],
+    properties: {
+      path: { type: "string", description: "Relative or absolute path within the workspace." },
+      content: { type: "string", description: "File contents to write." },
+    },
+    additionalProperties: false,
+  },
+  execute: async (args, ctx) => {
+    if (!isRecord(args) || typeof args.path !== "string" || typeof args.content !== "string") {
+      return "Error: path and content must be strings";
+    }
+    const resolved = resolvePath(ctx.cwd, args.path);
+    try {
+      await mkdir(dirname(resolved), { recursive: true });
+      await writeFile(resolved, args.content, "utf8");
+      return `Wrote ${args.content.length} bytes to ${args.path}`;
+    } catch (cause) {
+      const message = cause instanceof Error ? cause.message : String(cause);
+      return `Error: ${message}`;
+    }
+  },
+};
@@ -0,0 +1,50 @@
+import type { ChatMessage } from "./llm/index.js";
+
+export type BuiltinToolCallRecord = {
+  id: string;
+  name: string;
+  args: string;
+};
+
+export type BuiltinToolResultRecord = {
+  toolCallId: string;
+  name: string;
+  content: string;
+};
+
+export type BuiltinLoopTurn = {
+  assistantContent: string | null;
+  toolCalls: BuiltinToolCallRecord[] | null;
+  toolResults: BuiltinToolResultRecord[] | null;
+};
+
+export type BuiltinSessionState = {
+  sessionId: string;
+  model: string;
+  startedAtMs: number;
+  messages: ChatMessage[];
+  turns: BuiltinLoopTurn[];
+};
+
+export type BuiltinTurnRole = "assistant" | "tool";
+
+export type BuiltinToolCall = {
+  name: string;
+  args: string;
+};
+
+export type BuiltinTurnPayload = {
+  index: number;
+  role: BuiltinTurnRole;
+  content: string;
+  toolCalls: BuiltinToolCall[] | null;
+  reasoning: string | null;
+};
+
+export type BuiltinDetailPayload = {
+  sessionId: string;
+  model: string;
+  duration: number;
+  turnCount: number;
+  turns: string[];
+};
@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "include": ["src"],
+  "references": [{ "path": "../workflow-agent-kit" }, { "path": "../workflow-util" }]
+}
@@ -41,7 +41,15 @@ describe("buildClaudeCodePrompt", () => {

  test("includes previous steps as history summary", () => {
    const ctx = makeCtx({
-      steps: [{ role: "planner", output: '{"plan":"do X"}', agent: "hermes" }],
+      steps: [
+        {
+          role: "planner",
+          output: '{"plan":"do X"}',
+          agent: "hermes",
+          detail: "detail-1",
+          edgePrompt: "Create a plan.",
+        },
+      ],
    });
    const result = buildClaudeCodePrompt(ctx);
    expect(result).toContain("## Previous Steps");
@@ -2,6 +2,7 @@ import { describe, expect, test } from "bun:test";
 import { createMemoryStore, walk } from "@uncaged/json-cas";
 import {
  parseClaudeCodeJsonOutput,
+  parseClaudeCodeStreamOutput,
  storeClaudeCodeDetail,
  storeClaudeCodeRawOutput,
 } from "../src/session-detail.js";
@@ -17,6 +18,8 @@ describe("parseClaudeCodeJsonOutput", () => {
      num_turns: 3,
      total_cost_usd: 0.08,
      duration_ms: 10276,
+      stop_reason: "end_turn",
+      usage: { input_tokens: 100, output_tokens: 50 },
    });
    const parsed = parseClaudeCodeJsonOutput(stdout);
    expect(parsed).not.toBeNull();
@@ -27,22 +30,10 @@ describe("parseClaudeCodeJsonOutput", () => {
    expect(parsed!.numTurns).toBe(3);
    expect(parsed!.totalCostUsd).toBe(0.08);
    expect(parsed!.durationMs).toBe(10276);
-  });
-
-  test("parses error_max_turns result", () => {
-    const stdout = JSON.stringify({
-      type: "result",
-      subtype: "error_max_turns",
-      result: "Ran out of turns",
-      session_id: "abc-def",
-      num_turns: 90,
-      total_cost_usd: 1.5,
-      duration_ms: 50000,
-    });
-    const parsed = parseClaudeCodeJsonOutput(stdout);
-    expect(parsed).not.toBeNull();
-    expect(parsed!.subtype).toBe("error_max_turns");
-    expect(parsed!.result).toBe("Ran out of turns");
+    expect(parsed!.stopReason).toBe("end_turn");
+    expect(parsed!.usage.inputTokens).toBe(100);
+    expect(parsed!.usage.outputTokens).toBe(50);
+    expect(parsed!.turns).toEqual([]);
  });

  test("returns null for non-JSON output", () => {
@@ -57,45 +48,157 @@ describe("parseClaudeCodeJsonOutput", () => {
  });
 });

-describe("storeClaudeCodeDetail", () => {
-  test("stores claude-code-detail CAS node and returns output + detailHash", async () => {
-    const store = createMemoryStore();
-    const parsed: ClaudeCodeParsedResult = {
-      type: "result",
-      subtype: "success",
-      result: "The answer",
-      sessionId: "abc-123",
-      numTurns: 5,
-      totalCostUsd: 0.12,
-      durationMs: 15000,
-    };
+describe("parseClaudeCodeStreamOutput", () => {
+  test("parses stream-json output with turns", () => {
+    const lines = [
+      JSON.stringify({
+        type: "system",
+        subtype: "init",
+        session_id: "sess-123",
+        model: "claude-sonnet-4.5",
+        tools: ["Bash", "Read"],
+      }),
+      JSON.stringify({
+        type: "assistant",
+        message: {
+          role: "assistant",
+          content: [
+            { type: "text", text: "I'll list the files." },
+            { type: "tool_use", id: "tool_1", name: "Bash", input: { command: "ls" } },
+          ],
+        },
+        session_id: "sess-123",
+      }),
+      JSON.stringify({
+        type: "user",
+        message: {
+          role: "user",
+          content: [
+            { type: "tool_result", tool_use_id: "tool_1", content: "file1.ts\nfile2.ts" },
+          ],
+        },
+        session_id: "sess-123",
+      }),
+      JSON.stringify({
+        type: "assistant",
+        message: {
+          role: "assistant",
+          content: [{ type: "text", text: "There are 2 files." }],
+        },
+        session_id: "sess-123",
+      }),
+      JSON.stringify({
+        type: "result",
+        subtype: "success",
+        result: "There are 2 files.",
+        session_id: "sess-123",
+        num_turns: 2,
+        total_cost_usd: 0.05,
+        duration_ms: 5000,
+        stop_reason: "end_turn",
+        usage: {
+          input_tokens: 200,
+          output_tokens: 30,
+          cache_read_input_tokens: 100,
+          cache_creation_input_tokens: 0,
+        },
+      }),
+    ];
+    const stdout = lines.join("\n");
+    const parsed = parseClaudeCodeStreamOutput(stdout);
+
+    expect(parsed).not.toBeNull();
+    expect(parsed!.model).toBe("claude-sonnet-4.5");
+    expect(parsed!.sessionId).toBe("sess-123");
+    expect(parsed!.result).toBe("There are 2 files.");
+    expect(parsed!.stopReason).toBe("end_turn");
+    expect(parsed!.usage.inputTokens).toBe(200);
+    expect(parsed!.usage.outputTokens).toBe(30);
+    expect(parsed!.usage.cacheReadInputTokens).toBe(100);
+
+    // Turns: assistant(text+tool), tool_result, assistant(text)
+    expect(parsed!.turns).toHaveLength(3);
+    expect(parsed!.turns[0]!.role).toBe("assistant");
+    expect(parsed!.turns[0]!.content).toBe("I'll list the files.");
+    expect(parsed!.turns[0]!.toolCalls).toHaveLength(1);
+    expect(parsed!.turns[0]!.toolCalls![0]!.name).toBe("Bash");
+    expect(parsed!.turns[1]!.role).toBe("tool_result");
+    expect(parsed!.turns[1]!.content).toBe("file1.ts\nfile2.ts");
+    expect(parsed!.turns[2]!.role).toBe("assistant");
+    expect(parsed!.turns[2]!.content).toBe("There are 2 files.");
+    expect(parsed!.turns[2]!.toolCalls).toBeNull();
+  });
+
+  test("returns null when no result line", () => {
+    const stdout = JSON.stringify({ type: "system", model: "test" });
+    expect(parseClaudeCodeStreamOutput(stdout)).toBeNull();
+  });
+
+  test("skips invalid JSON lines gracefully", () => {
+    const lines = [
+      "not json",
+      JSON.stringify({
+        type: "result",
+        subtype: "success",
+        result: "ok",
+        session_id: "s1",
+        num_turns: 1,
+        total_cost_usd: 0.01,
+        duration_ms: 1000,
+        stop_reason: "end_turn",
+        usage: {},
+      }),
+    ];
+    const parsed = parseClaudeCodeStreamOutput(lines.join("\n"));
+    expect(parsed).not.toBeNull();
+    expect(parsed!.result).toBe("ok");
+    expect(parsed!.turns).toHaveLength(0);
+  });
+});
+
+describe("storeClaudeCodeDetail", () => {
+  const baseParsed: ClaudeCodeParsedResult = {
+    type: "result",
+    subtype: "success",
+    result: "The answer",
+    sessionId: "abc-123",
+    numTurns: 5,
+    totalCostUsd: 0.12,
+    durationMs: 15000,
+    model: "claude-sonnet-4.5",
+    stopReason: "end_turn",
+    usage: { inputTokens: 100, outputTokens: 50, cacheReadInputTokens: 0, cacheCreationInputTokens: 0 },
+    turns: [
+      { index: 0, role: "assistant", content: "hello", toolCalls: null },
+      { index: 1, role: "tool_result", content: "world", toolCalls: null },
+    ],
+  };
+
+  test("stores detail with per-turn CAS nodes", async () => {
+    const store = createMemoryStore();
+    const { detailHash, output, sessionId } = await storeClaudeCodeDetail(store, baseParsed);

-    const { detailHash, output, sessionId } = await storeClaudeCodeDetail(store, parsed);
    expect(detailHash).toHaveLength(13);
    expect(output).toBe("The answer");
    expect(sessionId).toBe("abc-123");

    const node = await store.get(detailHash);
    expect(node).not.toBeNull();
-    expect(node!.payload.sessionId).toBe("abc-123");
-    expect(node!.payload.numTurns).toBe(5);
-    expect(node!.payload.totalCostUsd).toBe(0.12);
-    expect(node!.payload.durationMs).toBe(15000);
+    expect(node!.payload.model).toBe("claude-sonnet-4.5");
+    expect(node!.payload.stopReason).toBe("end_turn");
+    expect(node!.payload.usage.inputTokens).toBe(100);
+    expect(node!.payload.turns).toHaveLength(2);
+
+    // Verify turn CAS nodes
+    const turn0 = await store.get(node!.payload.turns[0]);
+    expect(turn0).not.toBeNull();
+    expect(turn0!.payload.role).toBe("assistant");
+    expect(turn0!.payload.content).toBe("hello");
  });

  test("detail node is walkable from root", async () => {
    const store = createMemoryStore();
-    const parsed: ClaudeCodeParsedResult = {
-      type: "result",
-      subtype: "success",
-      result: "walkable test",
-      sessionId: "walk-123",
-      numTurns: 1,
-      totalCostUsd: 0.01,
-      durationMs: 1000,
-    };
-
-    const { detailHash } = await storeClaudeCodeDetail(store, parsed);
+    const { detailHash } = await storeClaudeCodeDetail(store, baseParsed);
    const visited: string[] = [];
    walk(store, detailHash, (hash) => visited.push(hash));
    expect(visited.length).toBeGreaterThan(0);
@@ -1,14 +1,20 @@
 import { spawn } from "node:child_process";
 import type { Store } from "@uncaged/json-cas";

+import { createLogger } from "@uncaged/workflow-util";
+
 import {
  type AgentContext,
  type AgentRunResult,
  buildRolePrompt,
  createAgent,
+  getCachedSessionId,
+  setCachedSessionId,
 } from "@uncaged/workflow-agent-kit";

-import { parseClaudeCodeJsonOutput, storeClaudeCodeDetail } from "./session-detail.js";
+import { parseClaudeCodeStreamOutput, storeClaudeCodeDetail } from "./session-detail.js";
+
+const log = createLogger({ sink: { kind: "stderr" } });

 const CLAUDE_COMMAND = "claude";
 const CLAUDE_MAX_TURNS = 90;
@@ -86,7 +92,8 @@ function spawnClaudeRun(prompt: string): Promise<{ stdout: string; stderr: strin
    "-p",
    prompt,
    "--output-format",
-    "json",
+    "stream-json",
+    "--verbose",
    "--dangerously-skip-permissions",
    "--max-turns",
    String(CLAUDE_MAX_TURNS),
@@ -103,7 +110,8 @@ function spawnClaudeResume(
    "--resume",
    sessionId,
    "--output-format",
-    "json",
+    "stream-json",
+    "--verbose",
    "--dangerously-skip-permissions",
    "--max-turns",
    String(CLAUDE_MAX_TURNS),
@@ -111,7 +119,7 @@ function spawnClaudeResume(
 }

 async function processClaudeOutput(stdout: string, store: Store): Promise<AgentRunResult> {
-  const parsed = parseClaudeCodeJsonOutput(stdout);
+  const parsed = parseClaudeCodeStreamOutput(stdout);

  if (parsed !== null) {
    const { detailHash, output, sessionId } = await storeClaudeCodeDetail(store, parsed);
@@ -119,14 +127,36 @@ async function processClaudeOutput(stdout: string, store: Store): Promise<AgentR
  }

  throw new Error(
-    `Claude Code returned non-JSON output (first 200 chars): ${stdout.slice(0, 200)}`,
+    `Claude Code returned unparseable output (first 200 chars): ${stdout.slice(0, 200)}`,
  );
 }

 async function runClaudeCode(ctx: AgentContext): Promise<AgentRunResult> {
  const fullPrompt = buildClaudeCodePrompt(ctx);
+
+  // Try resuming a cached session for re-entry scenarios (e.g. reviewer reject → developer re-entry).
+  if (!ctx.isFirstVisit) {
+    const cachedSessionId = await getCachedSessionId(ctx.threadId, ctx.role);
+    if (cachedSessionId !== null) {
+      try {
+        const { stdout } = await spawnClaudeResume(cachedSessionId, fullPrompt);
+        const result = await processClaudeOutput(stdout, ctx.store);
+        if (result.sessionId !== undefined && result.sessionId !== "") {
+          await setCachedSessionId(ctx.threadId, ctx.role, result.sessionId);
+        }
+        return result;
+      } catch (err) {
+        log("5VKR8N3Q", "resume failed for session %s, falling back to fresh run: %s", cachedSessionId, err);
+      }
+    }
+  }
+
  const { stdout } = await spawnClaudeRun(fullPrompt);
-  return processClaudeOutput(stdout, ctx.store);
+  const result = await processClaudeOutput(stdout, ctx.store);
+  if (result.sessionId !== undefined && result.sessionId !== "") {
+    await setCachedSessionId(ctx.threadId, ctx.role, result.sessionId);
+  }
+  return result;
 }

 async function continueClaudeCode(
@@ -1,6 +1,7 @@
 export { buildClaudeCodePrompt, createClaudeCodeAgent } from "./claude-code.js";
 export {
  parseClaudeCodeJsonOutput,
+  parseClaudeCodeStreamOutput,
  storeClaudeCodeDetail,
  storeClaudeCodeRawOutput,
 } from "./session-detail.js";
@@ -3,13 +3,52 @@ import type { JSONSchema } from "@uncaged/json-cas";
 export const CLAUDE_CODE_DETAIL_SCHEMA: JSONSchema = {
  title: "claude-code-detail",
  type: "object",
-  required: ["sessionId", "numTurns", "totalCostUsd", "durationMs", "subtype"],
+  required: [
+    "sessionId",
+    "model",
+    "subtype",
+    "durationMs",
+    "numTurns",
+    "totalCostUsd",
+    "stopReason",
+    "usage",
+    "turns",
+  ],
  properties: {
    sessionId: { type: "string" },
+    model: { type: "string" },
+    subtype: { type: "string" },
+    durationMs: { type: "integer" },
    numTurns: { type: "integer" },
    totalCostUsd: { type: "number" },
-    durationMs: { type: "integer" },
-    subtype: { type: "string" },
+    stopReason: { type: "string" },
+    usage: {
+      type: "object",
+      properties: {
+        inputTokens: { type: "integer" },
+        outputTokens: { type: "integer" },
+        cacheReadInputTokens: { type: "integer" },
+        cacheCreationInputTokens: { type: "integer" },
+      },
+      required: ["inputTokens", "outputTokens", "cacheReadInputTokens", "cacheCreationInputTokens"],
+    },
+    turns: {
+      type: "array",
+      items: { type: "string" },
+    },
+  },
+  additionalProperties: false,
+};
+
+export const CLAUDE_CODE_TURN_SCHEMA: JSONSchema = {
+  title: "claude-code-turn",
+  type: "object",
+  required: ["index", "role", "content", "toolCalls"],
+  properties: {
+    index: { type: "integer" },
+    role: { type: "string" },
+    content: { type: "string" },
+    toolCalls: {},
  },
  additionalProperties: false,
 };
@@ -1,13 +1,171 @@
 import { bootstrap, putSchema, type Store } from "@uncaged/json-cas";

-import { CLAUDE_CODE_DETAIL_SCHEMA, CLAUDE_CODE_RAW_OUTPUT_SCHEMA } from "./schemas.js";
-import type { ClaudeCodeDetailPayload, ClaudeCodeParsedResult } from "./types.js";
+import {
+  CLAUDE_CODE_DETAIL_SCHEMA,
+  CLAUDE_CODE_RAW_OUTPUT_SCHEMA,
+  CLAUDE_CODE_TURN_SCHEMA,
+} from "./schemas.js";
+import type {
+  ClaudeCodeDetailPayload,
+  ClaudeCodeParsedResult,
+  ClaudeCodeToolCall,
+  ClaudeCodeTurnPayload,
+} from "./types.js";

 function isRecord(value: unknown): value is Record<string, unknown> {
  return typeof value === "object" && value !== null && !Array.isArray(value);
 }

-/** Parse Claude Code JSON stdout (`claude -p --output-format json`). */
+function safeNumber(v: unknown, fallback = 0): number {
+  return typeof v === "number" ? v : fallback;
+}
+
+function safeString(v: unknown, fallback = ""): string {
+  return typeof v === "string" ? v : fallback;
+}
+
+/**
+ * Extract tool calls from an assistant message content array.
+ */
+function extractToolCalls(content: unknown[]): ClaudeCodeToolCall[] {
+  const calls: ClaudeCodeToolCall[] = [];
+  for (const item of content) {
+    if (isRecord(item) && item.type === "tool_use" && typeof item.name === "string") {
+      calls.push({
+        name: item.name,
+        input: typeof item.input === "string" ? item.input : JSON.stringify(item.input ?? {}),
+      });
+    }
+  }
+  return calls;
+}
+
+/**
+ * Extract text content from a message content array.
+ */
+function extractTextContent(content: unknown[]): string {
+  const texts: string[] = [];
+  for (const item of content) {
+    if (isRecord(item) && item.type === "text" && typeof item.text === "string") {
+      texts.push(item.text);
+    }
+  }
+  return texts.join("\n");
+}
+
+/**
+ * Extract tool result content from a user message content array.
+ */
+function extractToolResultContent(content: unknown[]): string {
+  const results: string[] = [];
+  for (const item of content) {
+    if (isRecord(item) && item.type === "tool_result") {
+      const text = typeof item.content === "string" ? item.content : "";
+      results.push(text);
+    }
+  }
+  return results.join("\n");
+}
+
+/**
+ * Parse Claude Code stream-json (NDJSON) output.
+ * Each line is a JSON object with type: "system" | "assistant" | "user" | "result".
+ */
+export function parseClaudeCodeStreamOutput(stdout: string): ClaudeCodeParsedResult | null {
+  const lines = stdout.trim().split("\n");
+  const turns: ClaudeCodeTurnPayload[] = [];
+  let resultLine: Record<string, unknown> | null = null;
+  let model = "";
+  let turnIndex = 0;
+
+  for (const line of lines) {
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (!isRecord(parsed)) continue;
+
+    const type = parsed.type;
+
+    if (type === "system" && typeof parsed.model === "string") {
+      model = parsed.model;
+    }
+
+    if (type === "assistant" && isRecord(parsed.message)) {
+      const msg = parsed.message;
+      const content = Array.isArray(msg.content) ? msg.content : [];
+      const textContent = extractTextContent(content as unknown[]);
+      const toolCalls = extractToolCalls(content as unknown[]);
+
+      // Only record turns that have actual content
+      if (textContent !== "" || toolCalls.length > 0) {
+        turns.push({
+          index: turnIndex++,
+          role: "assistant",
+          content: textContent,
+          toolCalls: toolCalls.length > 0 ? toolCalls : null,
+        });
+      }
+    }
+
+    if (type === "user" && isRecord(parsed.message)) {
+      const msg = parsed.message;
+      const content = Array.isArray(msg.content) ? msg.content : [];
+      const resultContent = extractToolResultContent(content as unknown[]);
+
+      if (resultContent !== "") {
+        turns.push({
+          index: turnIndex++,
+          role: "tool_result",
+          content: resultContent,
+          toolCalls: null,
+        });
+      }
+    }
+
+    if (type === "result") {
+      resultLine = parsed;
+    }
+  }
+
+  if (resultLine === null) return null;
+
+  const sessionId = resultLine.session_id;
+  const result = resultLine.result;
+  const subtype = resultLine.subtype;
+
+  if (typeof sessionId !== "string" || typeof result !== "string" || typeof subtype !== "string") {
+    return null;
+  }
+
+  const usage = isRecord(resultLine.usage) ? resultLine.usage : {};
+
+  return {
+    type: safeString(resultLine.type, "result"),
+    subtype: subtype as ClaudeCodeParsedResult["subtype"],
+    result,
+    sessionId,
+    numTurns: safeNumber(resultLine.num_turns),
+    totalCostUsd: safeNumber(resultLine.total_cost_usd),
+    durationMs: safeNumber(resultLine.duration_ms),
+    model,
+    stopReason: safeString(resultLine.stop_reason),
+    usage: {
+      inputTokens: safeNumber(usage.input_tokens),
+      outputTokens: safeNumber(usage.output_tokens),
+      cacheReadInputTokens: safeNumber(usage.cache_read_input_tokens),
+      cacheCreationInputTokens: safeNumber(usage.cache_creation_input_tokens),
+    },
+    turns,
+  };
+}
+
+/**
+ * Legacy: parse Claude Code plain JSON output (non-streaming).
+ * Falls back when stream-json is not available.
+ */
 export function parseClaudeCodeJsonOutput(stdout: string): ClaudeCodeParsedResult | null {
  let parsed: unknown;
  try {
@@ -16,9 +174,7 @@ export function parseClaudeCodeJsonOutput(stdout: string): ClaudeCodeParsedResul
    return null;
  }

-  if (!isRecord(parsed)) {
-    return null;
-  }
+  if (!isRecord(parsed)) return null;

  const sessionId = parsed.session_id;
  const result = parsed.result;
@@ -28,44 +184,68 @@ export function parseClaudeCodeJsonOutput(stdout: string): ClaudeCodeParsedResul
    return null;
  }

+  const usage = isRecord(parsed.usage) ? parsed.usage : {};
+
  return {
-    type: typeof parsed.type === "string" ? parsed.type : "result",
+    type: safeString(parsed.type, "result"),
    subtype: subtype as ClaudeCodeParsedResult["subtype"],
    result,
    sessionId,
-    numTurns: typeof parsed.num_turns === "number" ? parsed.num_turns : 0,
-    totalCostUsd: typeof parsed.total_cost_usd === "number" ? parsed.total_cost_usd : 0,
-    durationMs: typeof parsed.duration_ms === "number" ? parsed.duration_ms : 0,
+    numTurns: safeNumber(parsed.num_turns),
+    totalCostUsd: safeNumber(parsed.total_cost_usd),
+    durationMs: safeNumber(parsed.duration_ms),
+    model: "",
+    stopReason: safeString(parsed.stop_reason),
+    usage: {
+      inputTokens: safeNumber(usage.input_tokens),
+      outputTokens: safeNumber(usage.output_tokens),
+      cacheReadInputTokens: safeNumber(usage.cache_read_input_tokens),
+      cacheCreationInputTokens: safeNumber(usage.cache_creation_input_tokens),
+    },
+    turns: [],
  };
 }

 type ClaudeCodeSchemaHashes = {
  detail: string;
+  turn: string;
  rawOutput: string;
 };

 async function registerSchemas(store: Store): Promise<ClaudeCodeSchemaHashes> {
  await bootstrap(store);
-  const [detail, rawOutput] = await Promise.all([
+  const [detail, turn, rawOutput] = await Promise.all([
    putSchema(store, CLAUDE_CODE_DETAIL_SCHEMA),
+    putSchema(store, CLAUDE_CODE_TURN_SCHEMA),
    putSchema(store, CLAUDE_CODE_RAW_OUTPUT_SCHEMA),
  ]);
-  return { detail, rawOutput };
+  return { detail, turn, rawOutput };
 }

-/** Store parsed Claude Code result as a CAS detail node. */
+/** Store parsed Claude Code result with per-turn breakdown as CAS detail nodes. */
 export async function storeClaudeCodeDetail(
  store: Store,
  parsed: ClaudeCodeParsedResult,
 ): Promise<{ detailHash: string; output: string; sessionId: string }> {
  const schemas = await registerSchemas(store);

+  // Store each turn as an individual CAS node
+  const turnHashes: string[] = [];
+  for (const turn of parsed.turns) {
+    const hash = await store.put(schemas.turn, turn);
+    turnHashes.push(hash);
+  }
+
  const detail: ClaudeCodeDetailPayload = {
    sessionId: parsed.sessionId,
+    model: parsed.model,
+    subtype: parsed.subtype,
+    durationMs: parsed.durationMs,
    numTurns: parsed.numTurns,
    totalCostUsd: parsed.totalCostUsd,
-    durationMs: parsed.durationMs,
-    subtype: parsed.subtype,
+    stopReason: parsed.stopReason,
+    usage: parsed.usage,
+    turns: turnHashes,
  };

  const detailHash = await store.put(schemas.detail, detail);
@@ -1,5 +1,38 @@
 export type ClaudeCodeResultSubtype = "success" | "error_max_turns" | "error_budget";

+/** A single tool call within an assistant turn. */
+export type ClaudeCodeToolCall = {
+  name: string;
+  input: string;
+};
+
+/** A single turn (assistant text, tool use, or tool result). */
+export type ClaudeCodeTurnPayload = {
+  index: number;
+  role: "assistant" | "tool_result";
+  content: string;
+  toolCalls: ClaudeCodeToolCall[] | null;
+};
+
+/** Top-level detail stored as CAS node. */
+export type ClaudeCodeDetailPayload = {
+  sessionId: string;
+  model: string;
+  subtype: string;
+  durationMs: number;
+  numTurns: number;
+  totalCostUsd: number;
+  stopReason: string;
+  usage: {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadInputTokens: number;
+    cacheCreationInputTokens: number;
+  };
+  turns: string[]; // CAS hashes of ClaudeCodeTurnPayload
+};
+
+/** Intermediate parsed result from stream-json output. */
 export type ClaudeCodeParsedResult = {
  type: string;
  subtype: ClaudeCodeResultSubtype;
@@ -8,12 +41,13 @@ export type ClaudeCodeParsedResult = {
  numTurns: number;
  totalCostUsd: number;
  durationMs: number;
-};
-
-export type ClaudeCodeDetailPayload = {
-  sessionId: string;
-  numTurns: number;
-  totalCostUsd: number;
-  durationMs: number;
-  subtype: string;
+  model: string;
+  stopReason: string;
+  usage: {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadInputTokens: number;
+    cacheCreationInputTokens: number;
+  };
+  turns: ClaudeCodeTurnPayload[];
 };
@@ -49,8 +49,20 @@ describe("buildHermesPrompt", () => {
      isFirstVisit: false,
      edgePrompt: "The reviewer rejected your work. Fix the issues.",
      steps: [
-        { role: "developer", output: { summary: "Initial fix" }, agent: "uwf-hermes" },
-        { role: "reviewer", output: { approved: false }, agent: "uwf-hermes" },
+        {
+          role: "developer",
+          output: { summary: "Initial fix" },
+          agent: "uwf-hermes",
+          detail: "detail-1",
+          edgePrompt: "Implement the fix.",
+        },
+        {
+          role: "reviewer",
+          output: { approved: false },
+          agent: "uwf-hermes",
+          detail: "detail-2",
+          edgePrompt: "Review the code.",
+        },
      ],
    });

@@ -66,7 +78,15 @@ describe("buildHermesPrompt", () => {
    const result = buildHermesPrompt(
      makeCtx({
        isFirstVisit: true,
-        steps: [{ role: "developer", output: { done: true }, agent: "uwf-hermes" }],
+        steps: [
+          {
+            role: "developer",
+            output: { done: true },
+            agent: "uwf-hermes",
+            detail: "detail-1",
+            edgePrompt: "First attempt.",
+          },
+        ],
        edgePrompt: "Retry with a fresh approach.",
      }),
    );
@@ -0,0 +1,56 @@
+import { afterEach, describe, expect, it } from "bun:test";
+
+import { HermesAcpClient } from "../src/acp-client.js";
+
+/**
+ * E2E test for cross-process session resume.
+ *
+ * Simulates the workflow re-entry scenario:
+ * 1. Client A: connect → prompt → close (developer first run)
+ * 2. Client B: resume(sessionId) → prompt (developer re-entry after reviewer reject)
+ *
+ * This is what happens when uwf thread step spawns uwf-hermes twice for the same role.
+ */
+describe("HermesAcpClient cross-process resume", () => {
+  const clients: HermesAcpClient[] = [];
+
+  afterEach(async () => {
+    for (const c of clients) {
+      await c.close();
+    }
+    clients.length = 0;
+  });
+
+  it(
+    "resume() after close — second prompt returns non-empty text",
+    async () => {
+      // --- Client A: first run ---
+      const clientA = new HermesAcpClient();
+      clients.push(clientA);
+
+      await clientA.connect(process.cwd());
+      const first = await clientA.prompt(
+        "Remember the secret code: WATERMELON. Reply with exactly: ACKNOWLEDGED",
+      );
+      expect(first.text.length).toBeGreaterThan(0);
+      const sessionId = first.sessionId;
+
+      // Close client A (simulates uwf-hermes process exit)
+      await clientA.close();
+
+      // --- Client B: resume (simulates re-entry) ---
+      const clientB = new HermesAcpClient();
+      clients.push(clientB);
+
+      await clientB.resume(sessionId, process.cwd());
+      const second = await clientB.prompt(
+        "What was the secret code I told you earlier? Reply with just the code word.",
+      );
+
+      // The critical assertion: resumed session produces non-empty output
+      expect(second.text.length).toBeGreaterThan(0);
+      expect(second.sessionId).toBe(sessionId);
+    },
+    { timeout: 3 * 60 * 1000 },
+  );
+});
@@ -1,70 +1,17 @@
-import { mkdir, readFile, writeFile } from "node:fs/promises";
-import { dirname, join } from "node:path";
-
-import { resolveStorageRoot } from "@uncaged/workflow-agent-kit";
-import type { ThreadId } from "@uncaged/workflow-protocol";
-
-type HermesSessionCache = Record<string, string>;
-
-function getCachePath(): string {
-  return join(resolveStorageRoot(), "cache", "hermes-sessions.json");
-}
-
-function cacheKey(threadId: ThreadId, role: string): string {
-  return `${threadId}:${role}`;
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-async function readCache(): Promise<HermesSessionCache> {
-  const path = getCachePath();
-  try {
-    const text = await readFile(path, "utf8");
-    const raw = JSON.parse(text) as unknown;
-    if (!isRecord(raw)) {
-      return {};
-    }
-    const cache: HermesSessionCache = {};
-    for (const [key, value] of Object.entries(raw)) {
-      if (typeof value === "string" && value !== "") {
-        cache[key] = value;
-      }
-    }
-    return cache;
-  } catch (e) {
-    const err = e as NodeJS.ErrnoException;
-    if (err.code === "ENOENT") {
-      return {};
-    }
-    throw e;
-  }
-}
-
-async function writeCache(cache: HermesSessionCache): Promise<void> {
-  const path = getCachePath();
-  await mkdir(dirname(path), { recursive: true });
-  await writeFile(path, `${JSON.stringify(cache, null, 2)}\n`, "utf8");
-}
+// Re-export session cache from the shared agent-kit package.
+export { getCachedSessionId, setCachedSessionId } from "@uncaged/workflow-agent-kit";

 export function isResumeDisabled(): boolean {
-  const flag = process.env.UWF_NO_RESUME;
-  return flag !== undefined && flag !== "";
-}
-
-export async function getCachedSessionId(threadId: ThreadId, role: string): Promise<string | null> {
-  const cache = await readCache();
-  const sessionId = cache[cacheKey(threadId, role)];
-  return sessionId ?? null;
-}
-
-export async function setCachedSessionId(
-  threadId: ThreadId,
-  role: string,
-  sessionId: string,
-): Promise<void> {
-  const cache = await readCache();
-  cache[cacheKey(threadId, role)] = sessionId;
-  await writeCache(cache);
+  // Hermes ACP session/resume is broken: _restore fails for custom providers
+  // because resolve_runtime_provider("custom") throws and base_url/api_mode
+  // are lost in the fallback path.  Resume silently creates a new session
+  // (different sessionId, no history), causing empty-text responses.
+  // See: https://github.com/NousResearch/hermes-agent/issues/13489
+  // Disable by default until upstream fixes the bug.  Set UWF_HERMES_RESUME=1
+  // to opt back in.
+  const enableFlag = process.env.UWF_HERMES_RESUME;
+  if (enableFlag === "1" || enableFlag === "true") {
+    return false;
+  }
+  return true;
 }
@@ -7,6 +7,7 @@ const reviewerStep: StepContext = {
  output: { approved: false, comments: "Missing tests" },
  detail: "2MXBG6PN4A8JR",
  agent: "uwf-hermes",
+  edgePrompt: "Review the developer's work.",
 };

 const developerStep: StepContext = {
@@ -14,6 +15,7 @@ const developerStep: StepContext = {
  output: { filesChanged: ["src/app.ts"], summary: "Initial fix" },
  detail: "1VPBG9SM5E7WK",
  agent: "uwf-hermes",
+  edgePrompt: "Implement the fix.",
 };

 describe("buildContinuationPrompt", () => {
@@ -26,6 +28,7 @@ describe("buildContinuationPrompt", () => {
        output: { plan: "revise approach" },
        detail: "7BQST3VW9F2MA",
        agent: "uwf-hermes",
+        edgePrompt: "Revise the plan.",
      },
    ];

@@ -102,6 +102,7 @@ async function buildHistory(
      output: expandOutput(store, step.output),
      detail: step.detail,
      agent: step.agent,
+      edgePrompt: step.edgePrompt ?? "",
    });
  }
  return history;
@@ -13,6 +13,7 @@ export type { FrontmatterFastPathResult } from "./frontmatter.js";
 export { tryFrontmatterFastPath } from "./frontmatter.js";
 export { createAgent } from "./run.js";
 export { getConfigPath, getEnvPath, loadWorkflowConfig, resolveStorageRoot } from "./storage.js";
+export { getCachedSessionId, setCachedSessionId } from "./session-cache.js";
 export type {
  AgentContext,
  AgentContinueFn,
@@ -50,6 +50,7 @@ async function writeStepNode(options: {
  outputHash: CasRef;
  detailHash: CasRef;
  agentName: string;
+  edgePrompt: string;
 }): Promise<CasRef> {
  const payload: StepNodePayload = {
    start: options.startHash,
@@ -58,6 +59,7 @@ async function writeStepNode(options: {
    output: options.outputHash,
    detail: options.detailHash,
    agent: options.agentName,
+    edgePrompt: options.edgePrompt,
  };
  const hash = await options.store.put(options.schemas.stepNode, payload);
  const node = options.store.get(hash);
@@ -95,6 +97,7 @@ async function persistStep(options: {
    outputHash: options.outputHash,
    detailHash: options.detailHash,
    agentName: options.agentName,
+    edgePrompt: options.ctx.edgePrompt,
  });
 }

@@ -0,0 +1,75 @@
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { randomBytes } from "node:crypto";
+import { dirname, join } from "node:path";
+
+import type { ThreadId } from "@uncaged/workflow-protocol";
+
+import { resolveStorageRoot } from "./storage.js";
+
+type SessionCache = Record<string, string>;
+
+function getCachePath(): string {
+  return join(resolveStorageRoot(), "cache", "agent-sessions.json");
+}
+
+function cacheKey(threadId: ThreadId, role: string): string {
+  return `${threadId}:${role}`;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+async function readCache(): Promise<SessionCache> {
+  const path = getCachePath();
+  try {
+    const text = await readFile(path, "utf8");
+    const raw = JSON.parse(text) as unknown;
+    if (!isRecord(raw)) {
+      return {};
+    }
+    const cache: SessionCache = {};
+    for (const [key, value] of Object.entries(raw)) {
+      if (typeof value === "string" && value !== "") {
+        cache[key] = value;
+      }
+    }
+    return cache;
+  } catch (e) {
+    const err = e as NodeJS.ErrnoException;
+    if (err.code === "ENOENT") {
+      return {};
+    }
+    throw e;
+  }
+}
+
+async function writeCache(cache: SessionCache): Promise<void> {
+  const path = getCachePath();
+  const dir = dirname(path);
+  await mkdir(dir, { recursive: true });
+  // Atomic write: write to temp file then rename to avoid partial reads on concurrent access.
+  // NOTE: Current workflow execution is serial (execFileSync), so true concurrency doesn't occur.
+  // This is a safety net for future parallel execution.
+  const tmpPath = join(dir, `.agent-sessions.${randomBytes(4).toString("hex")}.tmp`);
+  await writeFile(tmpPath, `${JSON.stringify(cache, null, 2)}\n`, "utf8");
+  await rename(tmpPath, path);
+}
+
+/** Read the cached session ID for a thread+role pair. */
+export async function getCachedSessionId(threadId: ThreadId, role: string): Promise<string | null> {
+  const cache = await readCache();
+  const sessionId = cache[cacheKey(threadId, role)];
+  return sessionId ?? null;
+}
+
+/** Write the session ID for a thread+role pair into the cache. */
+export async function setCachedSessionId(
+  threadId: ThreadId,
+  role: string,
+  sessionId: string,
+): Promise<void> {
+  const cache = await readCache();
+  cache[cacheKey(threadId, role)] = sessionId;
+  await writeCache(cache);
+}
@@ -85,6 +85,7 @@ export const STEP_NODE_SCHEMA: JSONSchema = {
    output: { type: "string", format: "cas_ref" },
    detail: { type: "string", format: "cas_ref" },
    agent: { type: "string" },
+    edgePrompt: { type: "string" },
  },
  additionalProperties: false,
 };
@@ -12,6 +12,8 @@ export type StepRecord = {
  output: CasRef;
  detail: CasRef;
  agent: string;
+  /** Moderator edge prompt that led to this step. Missing in legacy nodes → "". */
+  edgePrompt: string;
 };

 // ── 4.2 Workflow 定义 ───────────────────────────────────────────────
@@ -0,0 +1,81 @@
+import { mkdirSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, test } from "bun:test";
+
+import { createProcessLogger } from "../src/process-logger/index.js";
+
+function logDateKey(date: Date): string {
+  return date.toISOString().slice(0, 10);
+}
+
+describe("createProcessLogger", () => {
+  let tmpDir: string;
+
+  afterEach(() => {
+    if (tmpDir !== undefined) {
+      rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+
+  test("writes init and log lines to dated JSONL under storage root", () => {
+    tmpDir = mkdtempSync(join(tmpdir(), "uwf-process-log-"));
+    const plog = createProcessLogger({
+      storageRoot: tmpDir,
+      context: { thread: "THREAD01", workflow: "WORKFLOW01" },
+    });
+
+    expect(plog.pid).toMatch(/^\d+-\d+$/);
+
+    plog.log("7NQW4HBT", "moderator selected role=planner", null);
+
+    const logPath = join(tmpDir, "logs", `${logDateKey(new Date())}.jsonl`);
+    const lines = readFileSync(logPath, "utf8")
+      .trim()
+      .split("\n")
+      .map((line) => JSON.parse(line) as Record<string, string>);
+
+    expect(lines).toHaveLength(2);
+    expect(lines[0]?.tag).toBe("W9F3RK2M");
+    expect(lines[0]?.pid).toBe(plog.pid);
+    expect(lines[0]?.thread).toBe("THREAD01");
+    expect(lines[0]?.workflow).toBe("WORKFLOW01");
+    expect(lines[0]?.msg).toContain("process start");
+    expect(lines[0]?.msg).toContain("node=");
+
+    expect(lines[1]?.tag).toBe("7NQW4HBT");
+    expect(lines[1]?.msg).toBe("moderator selected role=planner");
+    expect(lines[1]?.thread).toBe("THREAD01");
+    expect(lines[1]?.workflow).toBe("WORKFLOW01");
+  });
+
+  test("creates logs directory when missing", () => {
+    tmpDir = mkdtempSync(join(tmpdir(), "uwf-process-log-"));
+    createProcessLogger({
+      storageRoot: tmpDir,
+      context: { thread: null, workflow: null },
+    });
+    mkdirSync(join(tmpDir, "logs"), { recursive: true });
+    expect(() =>
+      readFileSync(join(tmpDir, "logs", `${logDateKey(new Date())}.jsonl`), "utf8"),
+    ).not.toThrow();
+  });
+
+  test("merges per-call context into the JSONL entry", () => {
+    tmpDir = mkdtempSync(join(tmpdir(), "uwf-process-log-"));
+    const plog = createProcessLogger({
+      storageRoot: tmpDir,
+      context: { thread: "T1", workflow: null },
+    });
+    plog.log("M3K8V9T1", "spawn agent", { command: "uwf-hermes", args: "tid role" });
+
+    const logPath = join(tmpDir, "logs", `${logDateKey(new Date())}.jsonl`);
+    const lines = readFileSync(logPath, "utf8")
+      .trim()
+      .split("\n")
+      .map((line) => JSON.parse(line) as Record<string, string>);
+    const last = lines[lines.length - 1];
+    expect(last?.command).toBe("uwf-hermes");
+    expect(last?.args).toBe("tid role");
+  });
+});
@@ -26,6 +26,7 @@ uwf workflow list                 # list all registered workflows
 uwf thread start <workflow> -p <prompt>           # create a thread (no execution)
 uwf thread step <thread-id>                       # execute one moderator→agent→extract cycle
               [--agent <cmd>]                    # override agent command
+               [-c, --count <number>]             # run multiple steps (default: 1)
 uwf thread show <thread-id>                       # show thread head pointer
 uwf thread list                                   # list active threads
               [--all]                            # include archived threads
@@ -56,6 +57,17 @@ uwf cas schema list               # list all registered schemas
 uwf cas schema get <hash>         # show a schema by its type hash
 \`\`\`

+## Log Commands
+
+\`\`\`
+uwf log list                      # list log files with sizes
+uwf log show                      # show all log entries
+           [--thread <thread-id>] # filter by thread ID
+           [--process <pid>]      # filter by process ID
+           [--date <YYYY-MM-DD>]  # filter by date
+uwf log clean --before <date>     # delete log files before given date
+\`\`\`
+
 ## Global Options

 \`\`\`
@@ -69,6 +81,7 @@ uwf -V, --version                 # print version
 - **Thread**: A single workflow execution (ULID). State is an immutable CAS chain; active threads are indexed in \`threads.yaml\`.
 - **Step**: One moderator→agent→extract cycle. Run \`uwf thread step\` repeatedly until \`$END\`.
 - **CAS**: Content-Addressed Storage — all nodes are immutable and identified by hash.
- **Role**: Named actor with goal, capabilities, procedure, output, and meta; the moderator routes between roles.
+- **Role**: Named actor with goal, capabilities, procedure, output, and frontmatter schema; the moderator routes between roles.
+- **Edge Prompt**: Required instruction on each graph edge — the moderator's dispatch message to the agent.
 `;
 }
@@ -13,6 +13,13 @@ export {
  validateFrontmatter,
 } from "./frontmatter-markdown/index.js";
 export { createLogger } from "./logger.js";
+export { createProcessLogger } from "./process-logger/index.js";
+export type {
+  CreateProcessLoggerOptions,
+  ProcessLogFn,
+  ProcessLogger,
+  ProcessLoggerContext,
+} from "./process-logger/index.js";
 export { normalizeRefsField } from "./refs-field.js";
 export { err, ok } from "./result.js";
 export { getDefaultWorkflowStorageRoot, getGlobalCasDir } from "./storage-root.js";
@@ -1,28 +1,8 @@
 import { appendFileSync } from "node:fs";

-import { CROCKFORD_BASE32_ALPHABET } from "./base32.js";
+import { assertValidLogTag } from "./process-logger/log-tag.js";
 import type { CreateLoggerOptions, LogFn } from "./types.js";

-const TAG_LENGTH = 8;
-
-const TAG_CHAR_SET: ReadonlySet<string> = new Set(CROCKFORD_BASE32_ALPHABET.split(""));
-
-function assertValidLogTag(tag: string): void {
-  if (tag.length !== TAG_LENGTH) {
-    throw new Error(`log tag must be exactly ${TAG_LENGTH} characters`);
-  }
-  for (let i = 0; i < tag.length; i++) {
-    const ch = tag[i];
-    if (ch === undefined) {
-      throw new Error("log tag validation failed");
-    }
-    const upper = ch.toUpperCase();
-    if (!TAG_CHAR_SET.has(upper)) {
-      throw new Error(`invalid Crockford Base32 character in log tag: ${ch}`);
-    }
-  }
-}
-
 /** Append one JSONL log record: `{ tag, content, timestamp }` per RFC-001. */
 export function createLogger(options: CreateLoggerOptions): LogFn {
  if (options.sink.kind === "stderr") {
@@ -0,0 +1,7 @@
+export { createProcessLogger } from "./process-logger.js";
+export type {
+  CreateProcessLoggerOptions,
+  ProcessLogFn,
+  ProcessLogger,
+  ProcessLoggerContext,
+} from "./types.js";
@@ -0,0 +1,21 @@
+import { CROCKFORD_BASE32_ALPHABET } from "../base32.js";
+
+const TAG_LENGTH = 8;
+
+const TAG_CHAR_SET: ReadonlySet<string> = new Set(CROCKFORD_BASE32_ALPHABET.split(""));
+
+export function assertValidLogTag(tag: string): void {
+  if (tag.length !== TAG_LENGTH) {
+    throw new Error(`log tag must be exactly ${TAG_LENGTH} characters`);
+  }
+  for (let i = 0; i < tag.length; i++) {
+    const ch = tag[i];
+    if (ch === undefined) {
+      throw new Error("log tag validation failed");
+    }
+    const upper = ch.toUpperCase();
+    if (!TAG_CHAR_SET.has(upper)) {
+      throw new Error(`invalid Crockford Base32 character in log tag: ${ch}`);
+    }
+  }
+}
@@ -0,0 +1,78 @@
+import { appendFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+
+import { getDefaultWorkflowStorageRoot } from "../storage-root.js";
+import { assertValidLogTag } from "./log-tag.js";
+import type { CreateProcessLoggerOptions, ProcessLogger, ProcessLoggerContext } from "./types.js";
+
+const INIT_TAG = "W9F3RK2M";
+
+function logDateKey(date: Date): string {
+  return date.toISOString().slice(0, 10);
+}
+
+function getProcessLogsDir(storageRoot: string): string {
+  return join(storageRoot, "logs");
+}
+
+function getProcessLogFilePath(storageRoot: string, date: Date): string {
+  return join(getProcessLogsDir(storageRoot), `${logDateKey(date)}.jsonl`);
+}
+
+function buildEntry(
+  processId: string,
+  tag: string,
+  msg: string,
+  baseContext: ProcessLoggerContext,
+  extra: Record<string, string> | null,
+): Record<string, string> {
+  const entry: Record<string, string> = {
+    ts: new Date().toISOString(),
+    pid: processId,
+    tag: tag.toUpperCase(),
+    msg,
+  };
+  if (baseContext.thread !== null) {
+    entry.thread = baseContext.thread;
+  }
+  if (baseContext.workflow !== null) {
+    entry.workflow = baseContext.workflow;
+  }
+  if (extra !== null) {
+    for (const [key, value] of Object.entries(extra)) {
+      entry[key] = value;
+    }
+  }
+  return entry;
+}
+
+function appendEntry(filePath: string, entry: Record<string, string>): void {
+  appendFileSync(filePath, `${JSON.stringify(entry)}\n`, "utf8");
+}
+
+/** Process-scoped debug logger — append-only JSONL under `<storageRoot>/logs/YYYY-MM-DD.jsonl`. */
+export function createProcessLogger(options: CreateProcessLoggerOptions): ProcessLogger {
+  const storageRoot = options.storageRoot ?? getDefaultWorkflowStorageRoot();
+  const processId = `${Date.now()}-${process.pid}`;
+  const baseContext = options.context;
+  const logFilePath = getProcessLogFilePath(storageRoot, new Date());
+
+  mkdirSync(getProcessLogsDir(storageRoot), { recursive: true });
+
+  const log: ProcessLogger["log"] = (tag, msg, context = null) => {
+    assertValidLogTag(tag);
+    appendEntry(logFilePath, buildEntry(processId, tag, msg, baseContext, context));
+  };
+
+  const argvSummary = JSON.stringify(process.argv);
+  const initParts = [`argv=${argvSummary}`, `node=${process.version}`];
+  if (baseContext.thread !== null) {
+    initParts.push(`thread=${baseContext.thread}`);
+  }
+  if (baseContext.workflow !== null) {
+    initParts.push(`workflow=${baseContext.workflow}`);
+  }
+  log(INIT_TAG, `process start ${initParts.join(" ")}`, null);
+
+  return { pid: processId, log };
+}
@@ -0,0 +1,20 @@
+export type ProcessLoggerContext = {
+  thread: string | null;
+  workflow: string | null;
+};
+
+export type CreateProcessLoggerOptions = {
+  storageRoot: string | null;
+  context: ProcessLoggerContext;
+};
+
+export type ProcessLogFn = (
+  tag: string,
+  msg: string,
+  context: Record<string, string> | null,
+) => void;
+
+export type ProcessLogger = {
+  pid: string;
+  log: ProcessLogFn;
+};
@@ -21,6 +21,7 @@ const publishOrder = [
  "workflow-moderator",
  "workflow-agent-kit",
  "workflow-agent-hermes",
+  "workflow-agent-builtin",
  "cli-workflow",
 ];

@@ -23,6 +23,7 @@
    { "path": "packages/workflow-moderator" },
    { "path": "packages/workflow-agent-kit" },
    { "path": "packages/workflow-agent-hermes" },
+    { "path": "packages/workflow-agent-builtin" },
    { "path": "packages/cli-workflow" }
  ]
 }
Author	SHA1	Message	Date
xingyue	080792a6c0	feat: builtin agent session resume via deterministic message reconstruction (#426 ) - StepRecord adds edgePrompt field (backward compat: defaults to "") - StepNode CAS schema includes edgePrompt - writeStepNode persists ctx.edgePrompt - buildHistory exposes edgePrompt in StepContext - buildBuiltinMessages reconstructs multi-turn moderator↔agent conversation: system = role prompt + output format (stable prefix) per prior visit: user (edgePrompt + inter-step summary) + assistant (output) current: user (edgePrompt + recent summary) - Zero extra persistence — pure function of CAS chain - Stable prefix for LLM prompt cache hits - 10 builtin tests pass, all other package tests pass	2026-05-23 17:34:49 +08:00
xiaomo	9f95956e19	Merge pull request 'fix(builtin): split prompt into system/user messages' (#425 ) from fix/builtin-agent-system-user-split into main	2026-05-23 09:17:13 +00:00
xiaoju	65e2305761	improve(solve-issue): planner must locate repo and read code before planning - planner procedure: locate repo (cwd/clone/create), read source files, reference actual code - planner frontmatter: add repoPath as required field - developer procedure: cd to repoPath, create branch, commit with issue ref	2026-05-23 09:16:51 +00:00
xingyue	44147da419	fix(builtin): split prompt into system/user messages System message = agent identity (role prompt + output format instruction) User message = moderator speech (task + edge prompt + history) This reflects the workflow's core model: moderator speaks to agent via the graph's edge prompt. Previously all content was in a single system message with no user message, causing Claude API 400 errors. - buildBuiltinPrompt now returns { system, user } instead of string - agent.ts sends system + user as separate messages - Tests updated accordingly	2026-05-23 17:15:23 +08:00
xiaoju	bc64f2613b	fix(thread): handle null stderr from execFileSync, increase maxBuffer to 50MB - err.stderr can be null (not just undefined) when child process fails - maxBuffer default (1MB) too small for stream-json verbose output	2026-05-23 08:58:05 +00:00
xiaoju	0e5b494e12	chore(debate): remove round limit, let step control drive pacing	2026-05-23 08:31:07 +00:00
xiaomo	747b318cc5	Merge pull request 'feat(claude-code): enrich step details with per-turn breakdown' (#423 ) from feat/422-claude-code-detail-enrichment into main	2026-05-23 08:19:20 +00:00
xiaoju	d16ce44bc3	feat(claude-code): enrich step details with per-turn breakdown Switch from --output-format json to stream-json --verbose to capture per-turn data. Detail now includes: - model name - usage (input/output/cache tokens) - stopReason - turns[] as individual CAS nodes with role, content, tool calls Also addresses PR #421 review fixes: - sessionId guard: skip cache write when sessionId is empty/undefined - silent catch: log resume failures with debug tag 5VKR8N3Q - atomic write: session cache uses temp+rename for crash safety Closes #422	2026-05-23 08:16:47 +00:00
xiaomo	45122bc458	Merge pull request 'fix: disable hermes resume, add claude-code resume support, debate workflow' (#421 ) from test/418-resume-e2e-repro into main	2026-05-23 07:59:53 +00:00
xiaomo	3183b4c879	Merge pull request 'feat: add @uncaged/workflow-agent-builtin package' (#420 ) from feat/builtin-agent into main	2026-05-23 07:57:44 +00:00
xiaoju	03eacbabb2	feat: add debate workflow for resume integration testing Two-role debate (against/for) with up to 3 rounds per side. Each role re-enters with session resume, making this an ideal integration test for cross-process session continuity. Supports early termination via concession (conceded=true in frontmatter). Refs #418	2026-05-23 07:50:38 +00:00
xingyue	cef4db9a87	refactor: remove workspace path sandbox and shell gate - Replace resolvePathInWorkspace with simple resolvePath (no boundary check) - Remove UWF_BUILTIN_ALLOW_SHELL env gate from run_command - Update tests accordingly Per review: sandbox was false security with shell=true, and path restrictions are unnecessary for a trusted agent environment.	2026-05-23 15:50:30 +08:00
xiaoju	1afaeacd57	feat: extract session cache to agent-kit, add resume to claude-code agent Move getCachedSessionId/setCachedSessionId from workflow-agent-hermes into workflow-agent-kit so all agent adapters can share the same session cache logic. Add cross-process session resume to workflow-agent-claude-code: on re-entry (isFirstVisit=false), look up the cached sessionId and use 'claude --resume' to continue with full conversation history. Cache file renamed from hermes-sessions.json to agent-sessions.json to reflect its shared nature. Refs #418	2026-05-23 07:44:02 +00:00
xingyue	deac2336b6	feat: add @uncaged/workflow-agent-builtin package Built-in role agent that uses workflow config models directly, with its own tool-calling run loop. No external agent dependency. - OpenAI-compatible chat completion client with tool_calls support - P0 toolkit: read_file, write_file, run_command - Integrates via createAgent factory from workflow-agent-kit - CAS detail recording for each turn - Path sandboxing and shell opt-in (UWF_BUILTIN_ALLOW_SHELL)	2026-05-23 15:29:55 +08:00
xiaoju	aad2792754	fix(hermes): disable ACP session/resume by default Hermes ACP _restore fails for custom providers — resolve_runtime_provider throws and base_url/api_mode are lost, causing resume to silently create a new session with no history. Prompt then returns empty text or refusal. Disable resume by default. Set UWF_HERMES_RESUME=1 to opt back in. Includes investigation notes in docs/investigations/. Refs #418	2026-05-23 07:23:14 +00:00
scottwei	10642fdc45	Merge pull request 'test: failing e2e test for session resume bug (#418 )' (#419 ) from test/418-resume-e2e-repro into main Reviewed-on: #419	2026-05-23 06:49:54 +00:00
xiaomo	92020d2d78	Merge pull request 'docs: sync cli-reference with recent CLI additions' (#417 ) from chore/update-cli-reference into main	2026-05-23 06:48:20 +00:00
xiaomo	cd0a79d72b	chore: remove accidental pnpm-lock.yaml	2026-05-23 06:47:25 +00:00
xiaoju	3b6aa6525f	test: add failing e2e test for session resume bug (#418 ) Cross-process resume returns empty text on subsequent prompt. This test documents the bug — expected to fail until #418 is fixed.	2026-05-23 06:43:47 +00:00
xiaomo	54631c43c7	docs: update cli-reference with log commands, --count flag, edge prompt concept	2026-05-23 06:32:27 +00:00
xiaomo	655b57c4b5	Merge pull request 'feat: add uwf log subcommands (list, show, clean)' (#415 ) from fix/413-log-subcommands into main	2026-05-23 06:27:15 +00:00
xiaoju	7faa8184ae	feat: add uwf log subcommands (list, show, clean) - uwf log list: list log files with sizes - uwf log show --thread <id>: filter by thread ID - uwf log show --process <pid>: filter by process ID - uwf log clean --before <date>: delete old log files - Tests: 12 new tests covering all subcommands Implemented by solve-issue workflow, biome fixes applied manually. Closes #413 Refs #411, #410	2026-05-23 06:23:56 +00:00
xiaoju	816137315e	feat: add uwf log subcommands (list, show, clean) - cmdLogList: list log files with sizes, sorted by date descending - cmdLogShow: filter entries by thread, process, and/or date - cmdLogClean: delete log files older than given date - 12 tests covering all functions and edge cases Fixes #413	2026-05-23 06:21:06 +00:00
xiaoju	9a111d16c7	fix: invalid Crockford Base32 char 'L' in log tag PL_AGENT_DONE Fixes runtime crash on uwf thread step.	2026-05-23 06:13:29 +00:00
xiaoju	ea6ceafe51	merge: resolve conflict in process-logger test (use null 3rd arg)	2026-05-23 06:10:53 +00:00
xiaoju	d0dc7b5a19	feat: add process-level debug logger (Phase 1) - New ProcessLogger in workflow-util: process-scoped JSONL logger - Entry schema: {ts, pid, tag, msg, thread, workflow} - Storage: ~/.uncaged/workflow/logs/YYYY-MM-DD.jsonl - Auto logs process init info (argv, node version, context) - cli-workflow thread commands fully instrumented: - thread start/step, moderator evaluate, agent spawn/done - thread archived, error paths Refs #411, #412, #410	2026-05-23 06:10:05 +00:00
xiaomo	3b81521e9d	Merge pull request 'feat: add process-level debug logger (Phase 1)' (#414 ) from feat/411-process-logger into main	2026-05-23 06:09:15 +00:00
xiaoju	aa0a23293f	feat: add process-level debug logger (Phase 1) - New ProcessLogger in workflow-util: process-scoped JSONL logger - Entry schema: {ts, pid, tag, msg, thread, workflow} - Storage: ~/.uncaged/workflow/logs/YYYY-MM-DD.jsonl - Auto logs process init info (argv, node version, context) - cli-workflow thread commands fully instrumented: - thread start/step, moderator evaluate, agent spawn/done - thread archived, error paths Refs #411, #412, #410	2026-05-23 06:07:45 +00:00
xiaomo	187dd036e5	Merge pull request 'feat: replace edgePrompt null check with isFirstVisit (Phase 2)' (#409 ) from feat/405-phase2-find-last-role-index into main	2026-05-23 04:55:23 +00:00