feat: add thread steps and thread fork commands

- uwf thread steps <thread-id>: walk CAS chain, list all steps chronologically
- uwf thread fork <thread-id> <step-hash>: create new thread from history point
- New types: StartEntry, StepEntry, ThreadStepsOutput, ThreadForkOutput
- Supports both active and archived threads

Refs #342

packages/cli-uwf/package.json

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

packages/cli-uwf/src/cli.ts

@@ -3,11 +3,13 @@
 import { Command } from "commander";
 
 import {
+  cmdThreadFork,
   cmdThreadKill,
   cmdThreadList,
   cmdThreadShow,
   cmdThreadStart,
   cmdThreadStep,
+  cmdThreadSteps,
 } from "./commands/thread.js";
 import { cmdWorkflowList, cmdWorkflowPut, cmdWorkflowShow } from "./commands/workflow.js";
 import { cmdSetup, cmdSetupInteractive } from "./commands/setup.js";
@@ -144,6 +146,31 @@ thread
     });
   });
 
+thread
+  .command("steps")
+  .description("List all steps in a thread")
+  .argument("<thread-id>", "Thread ULID")
+  .action((threadId: string) => {
+    const storageRoot = resolveStorageRoot();
+    runAction(async () => {
+      const result = await cmdThreadSteps(storageRoot, threadId);
+      writeOutput(result);
+    });
+  });
+
+thread
+  .command("fork")
+  .description("Fork a thread from a specific step")
+  .argument("<thread-id>", "Thread ULID")
+  .argument("<step-hash>", "CAS hash of the step to fork from")
+  .action((threadId: string, stepHash: string) => {
+    const storageRoot = resolveStorageRoot();
+    runAction(async () => {
+      const result = await cmdThreadFork(storageRoot, threadId, stepHash);
+      writeOutput(result);
+    });
+  });
+
 program
   .command("setup")
   .description("Configure provider, model, and agent")

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

@@ -8,13 +8,17 @@ import type {
   AgentConfig,
   CasRef,
   ModeratorContext,
+  StartEntry,
   StartNodePayload,
   StartOutput,
   StepContext,
+  StepEntry,
   StepNodePayload,
   StepOutput,
+  ThreadForkOutput,
   ThreadId,
   ThreadListItem,
+  ThreadStepsOutput,
   WorkflowConfig,
   WorkflowPayload,
 } from "@uncaged/uwf-protocol";
@@ -437,6 +441,131 @@ export async function cmdThreadStep(
   };
 }
 
+async function resolveHeadHash(storageRoot: string, threadId: ThreadId): Promise<CasRef> {
+  const index = await loadThreadsIndex(storageRoot);
+  const activeHead = index[threadId];
+  if (activeHead !== undefined) {
+    return activeHead;
+  }
+  const hist = await findThreadInHistory(storageRoot, threadId);
+  if (hist !== null) {
+    return hist.head;
+  }
+  fail(`thread not found: ${threadId}`);
+}
+
+export async function cmdThreadSteps(
+  storageRoot: string,
+  threadId: ThreadId,
+): Promise<ThreadStepsOutput> {
+  const headHash = await resolveHeadHash(storageRoot, threadId);
+  const uwf = await createUwfStore(storageRoot);
+  const chain = walkChain(uwf, headHash);
+
+  const startNode = uwf.store.get(chain.startHash);
+  if (startNode === null) {
+    fail(`StartNode not found: ${chain.startHash}`);
+  }
+
+  const startEntry: StartEntry = {
+    hash: chain.startHash,
+    workflow: chain.start.workflow,
+    prompt: chain.start.prompt,
+    timestamp: startNode.timestamp,
+  };
+
+  const stepEntries: StepEntry[] = [];
+
+  // Walk again to get hashes for each step
+  let hash: CasRef | null = headHash;
+  const hashToNode = new Map<string, { payload: StepNodePayload; timestamp: number }>();
+  while (hash !== null) {
+    const node = uwf.store.get(hash);
+    if (node === null || node.type !== uwf.schemas.stepNode) {
+      break;
+    }
+    const payload = node.payload as StepNodePayload;
+    hashToNode.set(hash, { payload, timestamp: node.timestamp });
+    hash = payload.prev;
+  }
+
+  // Build chronological list with hashes
+  // Walk from start's next to head
+  let cur: CasRef | null = chain.headIsStart ? null : headHash;
+  const ordered: { hash: CasRef; payload: StepNodePayload; timestamp: number }[] = [];
+  while (cur !== null) {
+    const entry = hashToNode.get(cur);
+    if (entry === undefined) break;
+    ordered.push({ hash: cur, ...entry });
+    cur = entry.payload.prev;
+  }
+  ordered.reverse();
+
+  for (const item of ordered) {
+    stepEntries.push({
+      hash: item.hash,
+      role: item.payload.role,
+      output: expandOutput(uwf, item.payload.output),
+      detail: item.payload.detail,
+      agent: item.payload.agent,
+      timestamp: item.timestamp,
+    });
+  }
+
+  return {
+    thread: threadId,
+    workflow: chain.start.workflow,
+    steps: [startEntry, ...stepEntries],
+  };
+}
+
+export async function cmdThreadFork(
+  storageRoot: string,
+  threadId: ThreadId,
+  stepHash: CasRef,
+): Promise<ThreadForkOutput> {
+  const headHash = await resolveHeadHash(storageRoot, threadId);
+  const uwf = await createUwfStore(storageRoot);
+
+  // Verify stepHash belongs to this thread by walking the chain
+  let found = false;
+  let cur: CasRef | null = headHash;
+  while (cur !== null) {
+    if (cur === stepHash) {
+      found = true;
+      break;
+    }
+    const node = uwf.store.get(cur);
+    if (node === null) break;
+    if (node.type === uwf.schemas.startNode) {
+      // startHash check
+      if (cur === stepHash) {
+        found = true;
+      }
+      break;
+    }
+    const payload = node.payload as StepNodePayload;
+    cur = payload.prev;
+  }
+
+  if (!found) {
+    fail(`step ${stepHash} not found in thread ${threadId}`);
+  }
+
+  const newThreadId = generateUlid(Date.now()) as ThreadId;
+  const index = await loadThreadsIndex(storageRoot);
+  index[newThreadId] = stepHash;
+  await saveThreadsIndex(storageRoot, index);
+
+  return {
+    thread: newThreadId,
+    forkedFrom: {
+      thread: threadId,
+      step: stepHash,
+    },
+  };
+}
+
 export async function cmdThreadKill(storageRoot: string, threadId: ThreadId): Promise<KillOutput> {
   const index = await loadThreadsIndex(storageRoot);
   const head = index[threadId];

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

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

packages/uwf-agent-hermes/package.json

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

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

@@ -1,18 +1,25 @@
 import { spawn } from "node:child_process";
 
-import { type AgentContext, createAgent } from "@uncaged/uwf-agent-kit";
+import { type AgentContext, type AgentRunResult, createAgent } from "@uncaged/uwf-agent-kit";
+
+import {
+  loadHermesSession,
+  parseSessionIdFromStdout,
+  storeHermesRawOutput,
+  storeHermesSessionDetail,
+} from "./session-detail.js";
 
 const HERMES_COMMAND = "hermes";
 const HERMES_MAX_TURNS = 90;
 
-function buildHistorySummary(history: AgentContext["history"]): string {
-  if (history.length === 0) {
+function buildHistorySummary(steps: AgentContext["steps"]): string {
+  if (steps.length === 0) {
     return "";
   }
 
   const lines: string[] = ["## Previous Steps"];
-  for (let i = 0; i < history.length; i++) {
-    const step = history[i];
+  for (let i = 0; i < steps.length; i++) {
+    const step = steps[i];
     if (step === undefined) {
       continue;
     }
@@ -26,8 +33,10 @@ function buildHistorySummary(history: AgentContext["history"]): string {
 
 /** Assemble system prompt, task, and prior step outputs for Hermes. */
 export function buildHermesPrompt(ctx: AgentContext): string {
-  const parts: string[] = [ctx.systemPrompt, "", "## Task", ctx.prompt];
-  const historyBlock = buildHistorySummary(ctx.history);
+  const roleDef = ctx.workflow.roles[ctx.role];
+  const systemPrompt = roleDef?.systemPrompt ?? "";
+  const parts: string[] = [systemPrompt, "", "## Task", ctx.start.prompt];
+  const historyBlock = buildHistorySummary(ctx.steps);
   if (historyBlock !== "") {
     parts.push("", historyBlock);
   }
@@ -76,9 +85,22 @@ function spawnHermesChat(prompt: string): Promise<string> {
   });
 }
 
-async function runHermes(ctx: AgentContext): Promise<string> {
+async function runHermes(ctx: AgentContext): Promise<AgentRunResult> {
   const fullPrompt = buildHermesPrompt(ctx);
-  return spawnHermesChat(fullPrompt);
+  const rawOutput = await spawnHermesChat(fullPrompt);
+  const { store } = ctx;
+
+  const sessionId = parseSessionIdFromStdout(rawOutput);
+  if (sessionId !== null) {
+    const session = await loadHermesSession(sessionId);
+    if (session !== null) {
+      const { detailHash, output } = await storeHermesSessionDetail(store, session);
+      return { output, detailHash };
+    }
+  }
+
+  const detailHash = await storeHermesRawOutput(store, rawOutput);
+  return { output: rawOutput, detailHash };
 }
 
 /** Agent CLI factory: parses argv, runs Hermes, extracts output, writes StepNode. */

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

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

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

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

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

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

packages/uwf-agent-kit/package.json

@@ -18,8 +18,8 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@uncaged/json-cas": "^0.2.0",
-    "@uncaged/json-cas-fs": "^0.2.0",
+    "@uncaged/json-cas": "^0.3.0",
+    "@uncaged/json-cas-fs": "^0.3.0",
     "@uncaged/uwf-protocol": "workspace:^",
     "dotenv": "^16.6.1",
     "yaml": "^2.8.4"

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

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

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

@@ -1,6 +1,5 @@
 export type { BuildContextMeta } from "./context.js";
 export { buildContext, buildContextWithMeta } from "./context.js";
-export { getConfigPath, getEnvPath, loadWorkflowConfig } from "./storage.js";
 export type { ExtractResult, ResolvedLlmProvider } from "./extract.js";
 export {
   extract,
@@ -8,4 +7,5 @@ export {
   resolveModel,
 } from "./extract.js";
 export { createAgent } from "./run.js";
-export type { AgentContext, AgentOptions, AgentRunFn } from "./types.js";
+export { getConfigPath, getEnvPath, loadWorkflowConfig } from "./storage.js";
+export type { AgentContext, AgentOptions, AgentRunFn, AgentRunResult } from "./types.js";

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

@@ -6,7 +6,7 @@ import { buildContextWithMeta } from "./context.js";
 import { extract } from "./extract.js";
 import type { AgentStore } from "./storage.js";
 import { getEnvPath, loadWorkflowConfig, resolveStorageRoot } from "./storage.js";
-import type { AgentContext, AgentOptions } from "./types.js";
+import type { AgentContext, AgentOptions, AgentRunResult } from "./types.js";
 
 function fail(message: string): never {
   process.stderr.write(`${message}\n`);
@@ -65,7 +65,7 @@ async function writeStepNode(options: {
   return hash;
 }
 
-async function runAgent(options: AgentOptions, ctx: AgentContext): Promise<string> {
+async function runAgent(options: AgentOptions, ctx: AgentContext): Promise<AgentRunResult> {
   return runWithMessage("agent run failed", () => options.run(ctx));
 }
 
@@ -85,12 +85,11 @@ async function extractOutput(
 
 async function persistStep(options: {
   ctx: Awaited<ReturnType<typeof buildContextWithMeta>>;
-  rawOutput: string;
   outputHash: CasRef;
+  detailHash: CasRef;
   agentName: string;
 }): Promise<CasRef> {
   const { store, schemas, chain, headHash } = options.ctx.meta;
-  const detailHash = await store.put(null, options.rawOutput);
   return writeStepNode({
     store,
     schemas,
@@ -98,7 +97,7 @@ async function persistStep(options: {
     prevHash: chain.headIsStart ? null : headHash,
     role: options.ctx.role,
     outputHash: options.outputHash,
-    detailHash,
+    detailHash: options.detailHash,
     agentName: options.agentName,
   });
 }
@@ -121,12 +120,12 @@ export function createAgent(options: AgentOptions): () => Promise<void> {
       fail(`unknown role: ${role}`);
     }
 
-    const rawOutput = await runAgent(options, ctx);
-    const outputHash = await extractOutput(rawOutput, roleDef.outputSchema, storageRoot);
+    const agentResult = await runAgent(options, ctx);
+    const outputHash = await extractOutput(agentResult.output, roleDef.outputSchema, storageRoot);
     const stepHash = await persistStep({
       ctx,
-      rawOutput,
       outputHash,
+      detailHash: agentResult.detailHash,
       agentName: agentLabel(options.name),
     });
 

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

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

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

@@ -1,15 +1,19 @@
-import type { StepContext, ThreadId, WorkflowPayload } from "@uncaged/uwf-protocol";
+import type { Store } from "@uncaged/json-cas";
+import type { ModeratorContext, ThreadId, WorkflowPayload } from "@uncaged/uwf-protocol";
 
-export type AgentContext = {
+export type AgentContext = ModeratorContext & {
   threadId: ThreadId;
   role: string;
-  systemPrompt: string;
-  prompt: string;
-  history: StepContext[];
+  store: Store;
   workflow: WorkflowPayload;
 };
 
-export type AgentRunFn = (ctx: AgentContext) => Promise<string>;
+export type AgentRunResult = {
+  output: string;
+  detailHash: string;
+};
+
+export type AgentRunFn = (ctx: AgentContext) => Promise<AgentRunResult>;
 
 export type AgentOptions = {
   name: string;

packages/uwf-protocol/package.json

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

packages/uwf-protocol/src/index.ts

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

packages/uwf-protocol/src/types.ts

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

scripts/mock-agent.ts

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