chore: add pre-push hook (check + test) and fix lint-log-tags for macOS

Two fixes:
1. cmdThreadRemove: always call both removeThreadEntry and
   removeThreadHistoryEntries regardless of resolved source,
   preventing race where thread moves from active to history
   between resolve and delete.
2. Test: add waitUntilRunningFileAbsent before thread show/rm,
   matching the pattern used by adjacent test cases.

Verified 5x consecutive runs with 0 failures.

Closes #265

.githooks/pre-push

@@ -1,6 +1,10 @@
 #!/usr/bin/env bash
-# pre-push hook: typecheck + biome + lint-log-tags
 set -euo pipefail
-echo "🔍 pre-push: running checks..."
+
+echo "🔍 Running check (tsc + biome + lint-log-tags)..."
 bun run check
-echo "✅ pre-push: all checks passed"
+
+echo "🧪 Running tests..."
+bun run test
+
+echo "✅ All checks passed!"

develop-entry.ts

@@ -9,6 +9,7 @@ const agent = createCursorAgent({
   command: "/home/azureuser/.local/bin/cursor-agent",
   model: "auto",
   timeout: 300_000,
+  workspace: null,
 });
 
 export const descriptor = buildDevelopDescriptor();

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

@@ -180,6 +180,9 @@ describe("cli thread commands", () => {
     }
     expect(threads.value.some((l) => l.includes(threadId))).toBe(true);
 
+    const runningPath = join(storageRoot, "logs", added.value.hash, `${threadId}.running`);
+    await waitUntilRunningFileAbsent(runningPath, 120);
+
     const shown = await cmdThreadShow(storageRoot, threadId);
     expect(shown.ok).toBe(true);
     if (!shown.ok) {

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

@@ -3,8 +3,8 @@ import { printCliError, printCliLine } from "./cli-output.js";
 import { getCommandRegistry } from "./cli-registry.js";
 import { formatCliUsage as formatCliUsageWithGroups } from "./cli-usage.js";
 import { createCasDispatcher } from "./commands/cas/index.js";
-import { createInitDispatcher } from "./commands/init/index.js";
 import { dispatchConnect } from "./commands/connect/index.js";
+import { createInitDispatcher } from "./commands/init/index.js";
 import { dispatchSetup } from "./commands/setup/index.js";
 import { createThreadDispatcher, dispatchLive, dispatchRun } from "./commands/thread/index.js";
 import { createWorkflowDispatcher } from "./commands/workflow/index.js";

packages/cli-workflow/src/commands/connect/ws-client.ts

@@ -48,11 +48,13 @@ async function handleGatewayMessage(
   const headers = new Headers(req.headers);
   let resp: Response;
   try {
-    resp = await params.appFetch(new Request(localUrl, {
-      method: req.method,
-      headers,
-      body: req.body === null ? undefined : req.body,
-    }));
+    resp = await params.appFetch(
+      new Request(localUrl, {
+        method: req.method,
+        headers,
+        body: req.body === null ? undefined : req.body,
+      }),
+    );
   } catch (e) {
     params.log("R4N7BQ3C", `app.fetch failed: ${String(e)}`);
     const errBody: WsResponse = {

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

@@ -18,13 +18,13 @@ export async function cmdThreadRemove(
     return err(`thread not found: ${threadId}`);
   }
 
-  if (resolved.source === "active") {
-    await removeThreadEntry(resolved.bundleDir, threadId);
-  } else {
-    const hist = await removeThreadHistoryEntries(resolved.bundleDir, threadId);
-    if (!hist.ok) {
-      return hist;
-    }
+  // Always clear both stores: between resolve and delete the worker may finish and
+  // move the thread from threads.json into history; branching only on resolved.source
+  // would skip history removal and leave a dangling row.
+  await removeThreadEntry(resolved.bundleDir, threadId);
+  const hist = await removeThreadHistoryEntries(resolved.bundleDir, threadId);
+  if (!hist.ok) {
+    return hist;
   }
 
   const infoPath = join(storageRoot, "logs", resolved.bundleHash, `${threadId}.info.jsonl`);

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

@@ -1,21 +1,25 @@
 import { describe, expect, test } from "bun:test";
 import { createCursorAgent, validateCursorAgentConfig } from "../src/index.js";
 
+const baseConfig = {
+  command: "/usr/local/bin/cursor-agent",
+  model: null as string | null,
+  timeout: 0,
+  workspace: null as string | null,
+};
+
 describe("validateCursorAgentConfig", () => {
   test("accepts valid config", () => {
     const r = validateCursorAgentConfig({
-      command: "/usr/local/bin/cursor-agent",
-      model: null,
-      timeout: 0,
+      ...baseConfig,
     });
     expect(r.ok).toBe(true);
   });
 
   test("rejects non-absolute command", () => {
     const r = validateCursorAgentConfig({
+      ...baseConfig,
       command: "cursor-agent",
-      model: null,
-      timeout: 0,
     });
     expect(r.ok).toBe(false);
     if (!r.ok) {
@@ -25,28 +29,35 @@ describe("validateCursorAgentConfig", () => {
 
   test("rejects negative timeout", () => {
     const r = validateCursorAgentConfig({
-      command: "/usr/local/bin/cursor-agent",
-      model: null,
+      ...baseConfig,
       timeout: -1,
     });
     expect(r.ok).toBe(false);
   });
+
+  test("rejects non-absolute workspace when set", () => {
+    const r = validateCursorAgentConfig({
+      ...baseConfig,
+      workspace: "relative/path",
+    });
+    expect(r.ok).toBe(false);
+    if (!r.ok) {
+      expect(r.error).toContain("workspace");
+    }
+  });
 });
 
 describe("createCursorAgent", () => {
   test("returns an AdapterFn", () => {
     const agent = createCursorAgent({
-      command: "/usr/local/bin/cursor-agent",
-      model: null,
-      timeout: 0,
+      ...baseConfig,
     });
     expect(typeof agent).toBe("function");
   });
 
   test("defers validation to call time (invalid config does not throw at construction)", () => {
     const agent = createCursorAgent({
-      command: "/usr/local/bin/cursor-agent",
-      model: null,
+      ...baseConfig,
       timeout: -1,
     });
     expect(typeof agent).toBe("function");

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

@@ -1,8 +1,8 @@
-import type { WorkflowRuntime } from "@uncaged/workflow-runtime";
-import { createLogger } from "@uncaged/workflow-util";
+import type { AdapterFn, AgentFn, WorkflowRuntime } from "@uncaged/workflow-runtime";
+import { createLogger, type LogFn } from "@uncaged/workflow-util";
 import {
   buildThreadInput,
-  createTextAdapter,
+  createAgentAdapter,
   type SpawnCliError,
   spawnCli,
 } from "@uncaged/workflow-util-agent";
@@ -33,25 +33,15 @@ function resolveCursorModel(model: string | null): string {
   return model === null ? "auto" : model;
 }
 
-/** Runs `cursor-agent` with workspace extracted from thread context via runtime.extract. */
-export function createCursorAgent(config: CursorAgentConfig) {
-  const modelFlag = resolveCursorModel(config.model);
-  const timeoutMs = config.timeout > 0 ? config.timeout : null;
-  const logger = createLogger({ sink: { kind: "stderr" } });
-
-  return createTextAdapter(async (ctx, prompt, runtime: WorkflowRuntime) => {
-    const validated = validateCursorAgentConfig(config);
-    if (!validated.ok) {
-      throw new Error(validated.error);
-    }
-
-    const workspace = await extractWorkspacePath(ctx, runtime, logger);
-    if (workspace === null) {
-      throw new Error(
-        "cursor-agent: failed to extract workspace path from context. Ensure the task prompt or previous steps include a project path.",
-      );
-    }
+type CursorAgentOpt = { prompt: string; workspace: string };
 
+function createCursorAgentFn(
+  config: CursorAgentConfig,
+  modelFlag: string,
+  timeoutMs: number | null,
+  logger: LogFn,
+): AgentFn<CursorAgentOpt> {
+  return async (ctx, { prompt, workspace }) => {
     logger("R5HN3YKQ", `cursor-agent workspace: ${workspace}`);
     const threadInput = await buildThreadInput(ctx);
     const fullPrompt = `${prompt}\n\n${threadInput}`;
@@ -75,5 +65,33 @@ export function createCursorAgent(config: CursorAgentConfig) {
       throwCursorSpawnError(run.error);
     }
     return run.value;
-  });
+  };
+}
+
+/** Runs `cursor-agent` with workspace from config or extracted from thread context via runtime.extract. */
+export function createCursorAgent(config: CursorAgentConfig): AdapterFn {
+  const modelFlag = resolveCursorModel(config.model);
+  const timeoutMs = config.timeout > 0 ? config.timeout : null;
+  const logger = createLogger({ sink: { kind: "stderr" } });
+
+  return createAgentAdapter(
+    createCursorAgentFn(config, modelFlag, timeoutMs, logger),
+    async (ctx, prompt, runtime: WorkflowRuntime) => {
+      const validated = validateCursorAgentConfig(config);
+      if (!validated.ok) {
+        throw new Error(validated.error);
+      }
+
+      const workspace =
+        config.workspace !== null
+          ? config.workspace
+          : await extractWorkspacePath(ctx, runtime, logger);
+      if (workspace === null) {
+        throw new Error(
+          "cursor-agent: failed to extract workspace path from context. Ensure the task prompt or previous steps include a project path.",
+        );
+      }
+      return { prompt, workspace };
+    },
+  );
 }

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

@@ -3,4 +3,9 @@ export type CursorAgentConfig = {
   command: string;
   model: string | null;
   timeout: number;
+  /**
+   * When non-null, use this workspace directory for `cursor-agent` instead of resolving it
+   * from the thread via runtime extraction.
+   */
+  workspace: string | null;
 };

packages/workflow-agent-cursor/src/validate-config.ts

@@ -11,5 +11,8 @@ export function validateCursorAgentConfig(config: CursorAgentConfig): Result<voi
   if (config.timeout < 0) {
     return err("timeout must be a non-negative number (milliseconds); use 0 for no limit");
   }
+  if (config.workspace !== null && !isAbsolute(config.workspace)) {
+    return err("workspace must be an absolute filesystem path when set");
+  }
   return ok(undefined);
 }

packages/workflow-agent-cursor/tsconfig.json

@@ -6,5 +6,9 @@
     "composite": true
   },
   "include": ["src/**/*.ts"],
-  "references": [{ "path": "../workflow-runtime" }, { "path": "../workflow-util-agent" }]
+  "references": [
+    { "path": "../workflow-cas" },
+    { "path": "../workflow-runtime" },
+    { "path": "../workflow-util-agent" }
+  ]
 }

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

@@ -1,7 +1,7 @@
-import type { AdapterFn } from "@uncaged/workflow-runtime";
+import type { AdapterFn, AgentFn } from "@uncaged/workflow-runtime";
 import {
   buildThreadInput,
-  createTextAdapter,
+  createAgentAdapter,
   type SpawnCliError,
   spawnCli,
 } from "@uncaged/workflow-util-agent";
@@ -11,6 +11,8 @@ import { validateHermesAgentConfig } from "./validate-config.js";
 
 const HERMES_DEFAULT_MAX_TURNS = 90;
 
+type HermesAgentOpt = { prompt: string };
+
 export type { HermesAgentConfig } from "./types.js";
 export { validateHermesAgentConfig } from "./validate-config.js";
 
@@ -29,16 +31,10 @@ function throwHermesSpawnError(error: SpawnCliError): never {
   throw new Error("hermes: unknown spawn error");
 }
 
-/** Runs `hermes chat` non-interactively with the Nerve-style argv contract (`-q`, `--yolo`, `--quiet`). */
-export function createHermesAgent(config: HermesAgentConfig): AdapterFn {
+function createHermesAgentFn(config: HermesAgentConfig): AgentFn<HermesAgentOpt> {
   const timeoutMs = config.timeout;
 
-  return createTextAdapter(async (ctx, prompt, _runtime) => {
-    const validated = validateHermesAgentConfig(config);
-    if (!validated.ok) {
-      throw new Error(validated.error);
-    }
-
+  return async (ctx, { prompt }) => {
     const threadInput = await buildThreadInput(ctx);
     const fullPrompt = `${prompt}\n\n${threadInput}`;
     const args = [
@@ -61,5 +57,16 @@ export function createHermesAgent(config: HermesAgentConfig): AdapterFn {
       throwHermesSpawnError(run.error);
     }
     return run.value;
+  };
+}
+
+/** Runs `hermes chat` non-interactively with the Nerve-style argv contract (`-q`, `--yolo`, `--quiet`). */
+export function createHermesAgent(config: HermesAgentConfig): AdapterFn {
+  return createAgentAdapter(createHermesAgentFn(config), async (_ctx, prompt, _runtime) => {
+    const validated = validateHermesAgentConfig(config);
+    if (!validated.ok) {
+      throw new Error(validated.error);
+    }
+    return { prompt };
   });
 }

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

@@ -1,5 +1,12 @@
-import { type AdapterFn, err, type LlmProvider, ok, type Result } from "@uncaged/workflow-runtime";
-import { createTextAdapter } from "@uncaged/workflow-util-agent";
+import {
+  type AdapterFn,
+  type AgentFn,
+  err,
+  type LlmProvider,
+  ok,
+  type Result,
+} from "@uncaged/workflow-runtime";
+import { createAgentAdapter } from "@uncaged/workflow-util-agent";
 
 /** OpenAI chat completion message shape (passed to `/chat/completions`). */
 export type LlmMessage = { role: "system" | "user" | "assistant"; content: string };
@@ -91,9 +98,10 @@ export async function chatCompletionText(options: {
   return parseAssistantText(res.value);
 }
 
-/** Single-turn chat adapter: system prompt is passed by the workflow engine. */
-export function createLlmAdapter(provider: LlmProvider): AdapterFn {
-  return createTextAdapter(async (ctx, prompt, _runtime) => {
+type LlmAgentOpt = { prompt: string };
+
+function createLlmAgent(provider: LlmProvider): AgentFn<LlmAgentOpt> {
+  return async (ctx, { prompt }) => {
     const result = await chatCompletionText({
       provider,
       messages: [
@@ -105,5 +113,12 @@ export function createLlmAdapter(provider: LlmProvider): AdapterFn {
       throw new Error(`llm: ${formatLlmChatError(result.error)}`);
     }
     return result.value;
-  });
+  };
+}
+
+/** Single-turn chat adapter: system prompt is passed by the workflow engine. */
+export function createLlmAdapter(provider: LlmProvider): AdapterFn {
+  return createAgentAdapter(createLlmAgent(provider), async (_ctx, prompt, _runtime) => ({
+    prompt,
+  }));
 }

packages/workflow-cas/tsconfig.json

@@ -2,7 +2,8 @@
   "extends": "../../tsconfig.json",
   "compilerOptions": {
     "rootDir": "src",
-    "outDir": "dist"
+    "outDir": "dist",
+    "composite": true
   },
   "include": ["src"],
   "references": [{ "path": "../workflow-protocol" }, { "path": "../workflow-util" }]

packages/workflow-dashboard/src/app.tsx

@@ -6,12 +6,14 @@ import { Sidebar } from "./components/sidebar.tsx";
 import { StatusBar } from "./components/status-bar.tsx";
 import { ThreadDetail } from "./components/thread-detail.tsx";
 import { ThreadList } from "./components/thread-list.tsx";
+import { WorkflowDetail } from "./components/workflow-detail.tsx";
 import { WorkflowList } from "./components/workflow-list.tsx";
 import { useHashRoute } from "./use-hash-route.ts";
 
 export function App() {
   const [authed, setAuthed] = useState(hasApiKey());
-  const { view, client, threadId, setView, setClient, setThreadId } = useHashRoute();
+  const { view, client, threadId, workflowName, setView, setClient, setThreadId, setWorkflowName } =
+    useHashRoute();
   const [showRun, setShowRun] = useState(false);
 
   if (!authed) {
@@ -46,7 +48,16 @@ export function App() {
           {client && view === "threads" && threadId !== null && (
             <ThreadDetail client={client} threadId={threadId} onBack={() => setThreadId(null)} />
           )}
-          {client && view === "workflows" && <WorkflowList client={client} />}
+          {client && view === "workflows" && workflowName === null && (
+            <WorkflowList client={client} onSelect={setWorkflowName} />
+          )}
+          {client && view === "workflows" && workflowName !== null && (
+            <WorkflowDetail
+              client={client}
+              workflowName={workflowName}
+              onBack={() => setWorkflowName(null)}
+            />
+          )}
         </div>
       </main>
       {showRun && client && (

packages/workflow-dashboard/src/components/thread-detail.tsx

@@ -96,42 +96,45 @@ export function ThreadDetail({ client, threadId, onBack }: Props) {
   // Track which occurrence to jump to next per role (cycling)
   const clickCycleRef = useRef<Map<string, number>>(new Map());
 
-  const handleGraphNodeClick = useCallback((nodeId: string) => {
-    // Only allow clicks on lit (non-default) nodes
-    if (nodeStates.get(nodeId) === undefined || nodeStates.get(nodeId) === "default") return;
+  const handleGraphNodeClick = useCallback(
+    (nodeId: string) => {
+      // Only allow clicks on lit (non-default) nodes
+      if (nodeStates.get(nodeId) === undefined || nodeStates.get(nodeId) === "default") return;
 
-    // __start__: scroll to the first record (thread-start prompt)
-    if (nodeId === "__start__") {
-      const firstCard = document.querySelector('[data-record-index="0"]');
-      if (firstCard !== null) firstCard.scrollIntoView({ behavior: "smooth", block: "center" });
-      return;
-    }
+      // __start__: scroll to the first record (thread-start prompt)
+      if (nodeId === "__start__") {
+        const firstCard = document.querySelector('[data-record-index="0"]');
+        if (firstCard !== null) firstCard.scrollIntoView({ behavior: "smooth", block: "center" });
+        return;
+      }
 
-    // __end__: scroll to bottom
-    if (nodeId === "__end__") {
-      recordsEndRef.current?.scrollIntoView({ behavior: "smooth", block: "end" });
-      return;
-    }
+      // __end__: scroll to bottom
+      if (nodeId === "__end__") {
+        recordsEndRef.current?.scrollIntoView({ behavior: "smooth", block: "end" });
+        return;
+      }
 
-    // Role nodes: cycle through occurrences
-    const indices = indicesByRole.get(nodeId);
-    if (indices === undefined || indices.length === 0) return;
+      // Role nodes: cycle through occurrences
+      const indices = indicesByRole.get(nodeId);
+      if (indices === undefined || indices.length === 0) return;
 
-    const cycle = clickCycleRef.current.get(nodeId) ?? 0;
-    const idx = indices[cycle % indices.length];
-    clickCycleRef.current.set(nodeId, cycle + 1);
+      const cycle = clickCycleRef.current.get(nodeId) ?? 0;
+      const idx = indices[cycle % indices.length];
+      clickCycleRef.current.set(nodeId, cycle + 1);
 
-    const el = document.querySelector(`[data-record-index="${idx}"]`);
-    if (el !== null) {
-      el.scrollIntoView({ behavior: "smooth", block: "center" });
-      if (highlightTimerRef.current !== null) clearTimeout(highlightTimerRef.current);
-      setHighlightedRole(nodeId);
-      highlightTimerRef.current = setTimeout(() => {
-        setHighlightedRole(null);
-        highlightTimerRef.current = null;
-      }, 1500);
-    }
-  }, [nodeStates, indicesByRole]);
+      const el = document.querySelector(`[data-record-index="${idx}"]`);
+      if (el !== null) {
+        el.scrollIntoView({ behavior: "smooth", block: "center" });
+        if (highlightTimerRef.current !== null) clearTimeout(highlightTimerRef.current);
+        setHighlightedRole(nodeId);
+        highlightTimerRef.current = setTimeout(() => {
+          setHighlightedRole(null);
+          highlightTimerRef.current = null;
+        }, 1500);
+      }
+    },
+    [nodeStates, indicesByRole],
+  );
 
   useEffect(() => {
     return () => {
@@ -285,7 +288,11 @@ export function ThreadDetail({ client, threadId, onBack }: Props) {
                     </div>
                   );
                 }
-                return <div key={key} data-record-index={i}><RecordCard record={r} highlighted={false} /></div>;
+                return (
+                  <div key={key} data-record-index={i}>
+                    <RecordCard record={r} highlighted={false} />
+                  </div>
+                );
               })}
               <div ref={recordsEndRef} aria-hidden />
             </div>

packages/workflow-dashboard/src/components/workflow-detail.tsx

@@ -0,0 +1,401 @@
+import { useMemo, useRef, useState } from "react";
+import type { WorkflowDetail as WorkflowDetailData, WorkflowRoleDescriptor } from "../api.ts";
+import { getWorkflowDetail } from "../api.ts";
+import { useFetch } from "../hooks.ts";
+import { type NodeState, WorkflowGraph } from "./workflow-graph/index.ts";
+
+type Props = {
+  client: string;
+  workflowName: string;
+  onBack: () => void;
+};
+
+function versionCount(detail: WorkflowDetailData): number {
+  return detail.history.length + 1;
+}
+
+// ── Schema rendering helpers ────────────────────────────────────────
+
+type SchemaRow = {
+  key: string;
+  name: string;
+  type: string;
+  description: string;
+  depth: number;
+  prefix: string;
+  isVariantHeader: boolean;
+};
+
+function resolveType(prop: Record<string, unknown>): string {
+  if (prop.type === "array") {
+    const items = prop.items as Record<string, unknown> | undefined;
+    if (items !== undefined) {
+      const itemType = String(items.type ?? "unknown");
+      return `${itemType}[]`;
+    }
+    return "array";
+  }
+  return String(prop.type ?? "unknown");
+}
+
+function flattenSchema(
+  schema: Record<string, unknown>,
+  depth: number,
+  parentPrefix: string,
+  keyPrefix: string,
+): SchemaRow[] {
+  const rows: SchemaRow[] = [];
+
+  // Handle oneOf / discriminatedUnion
+  const oneOf = schema.oneOf as Array<Record<string, unknown>> | undefined;
+  if (Array.isArray(oneOf) && oneOf.length > 0) {
+    for (let vi = 0; vi < oneOf.length; vi++) {
+      const variant = oneOf[vi];
+      const variantProps = (variant.properties ?? {}) as Record<string, Record<string, unknown>>;
+      let variantLabel = `Variant ${vi + 1}`;
+      for (const [pName, pDef] of Object.entries(variantProps)) {
+        if (pDef.const !== undefined) {
+          variantLabel = `${pName}: ${String(pDef.const)}`;
+          break;
+        }
+      }
+      const isLast = vi === oneOf.length - 1;
+      const connector = isLast ? "└" : "├";
+      rows.push({
+        key: `${keyPrefix}variant-${vi}`,
+        name: `${parentPrefix}${connector} ${variantLabel}`,
+        type: "",
+        description: "",
+        depth,
+        prefix: parentPrefix,
+        isVariantHeader: true,
+      });
+      const childPrefix = `${parentPrefix}${isLast ? "  " : "│ "}`;
+      const variantRequired = new Set<string>(
+        Array.isArray(variant.required) ? (variant.required as string[]) : [],
+      );
+      for (const [pName, pDef] of Object.entries(variantProps)) {
+        if (pDef.const !== undefined) continue;
+        const subRows = flattenProperty(
+          pName,
+          pDef,
+          depth + 1,
+          childPrefix,
+          `${keyPrefix}v${vi}-`,
+          variantRequired,
+        );
+        rows.push(...subRows);
+      }
+    }
+    return rows;
+  }
+
+  const props = (schema.properties ?? {}) as Record<string, Record<string, unknown>>;
+  const required = new Set<string>(
+    Array.isArray(schema.required) ? (schema.required as string[]) : [],
+  );
+  for (const [name, prop] of Object.entries(props)) {
+    const subRows = flattenProperty(name, prop, depth, parentPrefix, keyPrefix, required);
+    rows.push(...subRows);
+  }
+  return rows;
+}
+
+function flattenProperty(
+  name: string,
+  prop: Record<string, unknown>,
+  depth: number,
+  parentPrefix: string,
+  keyPrefix: string,
+  required: Set<string>,
+): SchemaRow[] {
+  const rows: SchemaRow[] = [];
+  const hasOneOf = Array.isArray(prop.oneOf) && (prop.oneOf as unknown[]).length > 0;
+  let type = hasOneOf ? "⊕ oneOf" : resolveType(prop);
+  if (!required.has(name)) type += "?";
+  const description = String(prop.description ?? "");
+  const displayName = depth > 0 ? `${parentPrefix}└─ ${name}` : name;
+
+  rows.push({
+    key: `${keyPrefix}${name}`,
+    name: displayName,
+    type,
+    description,
+    depth,
+    prefix: parentPrefix,
+    isVariantHeader: false,
+  });
+
+  if (prop.type === "object" && prop.properties !== undefined) {
+    const childPrefix = depth > 0 ? `${parentPrefix}   ` : "  ";
+    rows.push(
+      ...flattenSchema(
+        prop as Record<string, unknown>,
+        depth + 1,
+        childPrefix,
+        `${keyPrefix}${name}-`,
+      ),
+    );
+  }
+
+  if (prop.type === "array") {
+    const items = prop.items as Record<string, unknown> | undefined;
+    if (items !== undefined && items.type === "object" && items.properties !== undefined) {
+      const childPrefix = depth > 0 ? `${parentPrefix}   ` : "  ";
+      rows.push(...flattenSchema(items, depth + 1, childPrefix, `${keyPrefix}${name}-`));
+    }
+  }
+
+  if (hasOneOf) {
+    const childPrefix = depth > 0 ? `${parentPrefix}   ` : "  ";
+    rows.push(
+      ...flattenSchema(
+        prop as Record<string, unknown>,
+        depth + 1,
+        childPrefix,
+        `${keyPrefix}${name}-`,
+      ),
+    );
+  }
+
+  return rows;
+}
+
+// ── Components ──────────────────────────────────────────────────────
+
+function RoleCard({ roleName, role }: { roleName: string; role: WorkflowRoleDescriptor }) {
+  const rows = flattenSchema(role.schema, 0, "", `${roleName}-`);
+  return (
+    <div
+      id={`role-${roleName}`}
+      className="rounded-lg border p-4"
+      style={{ borderColor: "var(--color-border)", background: "var(--color-surface)" }}
+    >
+      <h4 className="text-sm font-semibold font-mono mb-1" style={{ color: "var(--color-text)" }}>
+        {roleName}
+      </h4>
+      {role.description !== "" && (
+        <p className="text-xs mb-3" style={{ color: "var(--color-text-muted)" }}>
+          {role.description}
+        </p>
+      )}
+      {rows.length > 0 && (
+        <div>
+          <p
+            className="text-[10px] uppercase tracking-wider mb-1 font-medium"
+            style={{ color: "var(--color-text-muted)" }}
+          >
+            Meta Schema
+          </p>
+          <table className="w-full text-xs" style={{ borderCollapse: "collapse" }}>
+            <thead>
+              <tr style={{ borderBottom: "1px solid var(--color-border)" }}>
+                <th
+                  className="text-left py-1 pr-3 font-medium"
+                  style={{ color: "var(--color-text-muted)" }}
+                >
+                  Field
+                </th>
+                <th
+                  className="text-left py-1 pr-3 font-medium"
+                  style={{ color: "var(--color-text-muted)" }}
+                >
+                  Type
+                </th>
+                <th
+                  className="text-left py-1 font-medium"
+                  style={{ color: "var(--color-text-muted)" }}
+                >
+                  Description
+                </th>
+              </tr>
+            </thead>
+            <tbody>
+              {rows.map((r) => (
+                <tr
+                  key={r.key}
+                  style={{
+                    borderBottom: r.isVariantHeader ? "none" : "1px solid var(--color-border)",
+                  }}
+                >
+                  <td
+                    className="py-1 pr-3 font-mono whitespace-pre"
+                    style={{
+                      color: r.isVariantHeader ? "var(--color-text-muted)" : "var(--color-accent)",
+                      fontStyle: r.isVariantHeader ? "italic" : "normal",
+                    }}
+                  >
+                    {r.name}
+                  </td>
+                  <td className="py-1 pr-3 font-mono" style={{ color: "var(--color-text-muted)" }}>
+                    {r.type}
+                  </td>
+                  <td className="py-1" style={{ color: "var(--color-text)" }}>
+                    {r.description || (r.isVariantHeader ? "" : "—")}
+                  </td>
+                </tr>
+              ))}
+            </tbody>
+          </table>
+        </div>
+      )}
+      {rows.length === 0 && Object.keys(role.schema).length > 0 && (
+        <pre
+          className="text-[10px] font-mono p-2 rounded overflow-x-auto"
+          style={{ background: "var(--color-bg)", color: "var(--color-text-muted)" }}
+        >
+          {JSON.stringify(role.schema, null, 2)}
+        </pre>
+      )}
+    </div>
+  );
+}
+
+// ── Main component ──────────────────────────────────────────────────
+
+export function WorkflowDetail({ client, workflowName, onBack }: Props) {
+  const { status, data, error } = useFetch(
+    () => getWorkflowDetail(client, workflowName),
+    [client, workflowName],
+  );
+
+  const [highlightedRole, setHighlightedRole] = useState<string | null>(null);
+  const highlightTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const detail = status === "ok" ? data : null;
+  const descriptor = detail?.descriptor ?? null;
+  const roleEntries = descriptor !== null ? Object.entries(descriptor.roles) : [];
+  const edgeCount = descriptor !== null ? descriptor.graph.edges.length : 0;
+  const hasGraph = descriptor !== null && edgeCount > 0;
+
+  const allLitStates = useMemo(() => {
+    const m = new Map<string, NodeState>();
+    m.set("__start__", "completed");
+    m.set("__end__", "completed");
+    for (const [name] of roleEntries) {
+      m.set(name, "completed");
+    }
+    return m;
+  }, [roleEntries]);
+
+  function handleGraphNodeClick(nodeId: string) {
+    const el = document.getElementById(`role-${nodeId}`);
+    if (el === null) return;
+    el.scrollIntoView({ behavior: "smooth", block: "center" });
+    if (highlightTimerRef.current !== null) clearTimeout(highlightTimerRef.current);
+    setHighlightedRole(nodeId);
+    highlightTimerRef.current = setTimeout(() => {
+      setHighlightedRole(null);
+      highlightTimerRef.current = null;
+    }, 1500);
+  }
+
+  return (
+    <div>
+      <div className="flex items-center justify-between mb-4">
+        <button
+          type="button"
+          onClick={onBack}
+          className="text-sm hover:underline"
+          style={{ color: "var(--color-accent)" }}
+        >
+          ← Back to workflows
+        </button>
+      </div>
+
+      <h2 className="text-xl font-semibold mb-4 font-mono">{workflowName}</h2>
+
+      {status === "loading" && <p style={{ color: "var(--color-text-muted)" }}>Loading...</p>}
+      {status === "error" && <p style={{ color: "var(--color-error)" }}>Error: {error}</p>}
+
+      {detail !== null && (
+        <div className="flex gap-4" style={{ minHeight: "calc(100vh - 160px)" }}>
+          {/* Left: fixed graph sidebar */}
+          {hasGraph && (
+            <div
+              className="shrink-0"
+              style={{
+                width: 280,
+                position: "sticky",
+                top: 16,
+                height: "calc(100vh - 160px)",
+                alignSelf: "flex-start",
+              }}
+            >
+              <div
+                className="rounded-lg border h-full flex flex-col overflow-hidden"
+                style={{ borderColor: "var(--color-border)", background: "var(--color-surface)" }}
+              >
+                <div
+                  className="flex items-center justify-between px-3 py-2 text-xs"
+                  style={{ color: "var(--color-text-muted)" }}
+                >
+                  <span className="font-mono">Workflow graph</span>
+                  <span>
+                    {edgeCount} edge{edgeCount === 1 ? "" : "s"}
+                  </span>
+                </div>
+                <div className="flex-1">
+                  <WorkflowGraph
+                    graph={descriptor.graph}
+                    roles={descriptor.roles}
+                    nodeStates={allLitStates}
+                    onNodeClick={handleGraphNodeClick}
+                  />
+                </div>
+              </div>
+            </div>
+          )}
+
+          {/* Right: scrollable content */}
+          <div className="flex-1 min-w-0 space-y-4">
+            {/* Workflow overview */}
+            <div
+              className="rounded-lg border p-4"
+              style={{ borderColor: "var(--color-border)", background: "var(--color-surface)" }}
+            >
+              <p
+                className="text-sm whitespace-pre-wrap mb-3"
+                style={{ color: "var(--color-text)" }}
+              >
+                {descriptor !== null && descriptor.description !== ""
+                  ? descriptor.description
+                  : "—"}
+              </p>
+              <div className="flex gap-4 text-xs" style={{ color: "var(--color-text-muted)" }}>
+                <span>
+                  Hash:{" "}
+                  <code className="font-mono" style={{ color: "var(--color-accent)" }}>
+                    {detail.hash}
+                  </code>
+                </span>
+                <span>
+                  {versionCount(detail)} version{versionCount(detail) !== 1 ? "s" : ""}
+                </span>
+                {roleEntries.length > 0 && (
+                  <span>
+                    {roleEntries.length} role{roleEntries.length !== 1 ? "s" : ""}
+                  </span>
+                )}
+              </div>
+            </div>
+
+            {/* Role cards */}
+            {roleEntries.map(([name, role]) => (
+              <div
+                key={name}
+                style={{
+                  transition: "box-shadow 0.3s",
+                  boxShadow: highlightedRole === name ? "0 0 0 2px var(--color-accent)" : "none",
+                  borderRadius: 8,
+                }}
+              >
+                <RoleCard roleName={name} role={role} />
+              </div>
+            ))}
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}

packages/workflow-dashboard/src/components/workflow-graph/condition-edge.tsx

@@ -10,7 +10,13 @@ const FEEDBACK_RADIUS = 16;
  * Build an SVG path for a feedback (back) edge that routes to the given side of the nodes.
  * The path goes: source → arc → vertical up → arc → target
  */
-function feedbackPath(sourceX: number, sourceY: number, targetX: number, targetY: number, side: "right" | "left"): string {
+function feedbackPath(
+  sourceX: number,
+  sourceY: number,
+  targetX: number,
+  targetY: number,
+  side: "right" | "left",
+): string {
   const d = side === "right" ? 1 : -1;
   const offsetX =
     side === "right"
@@ -88,12 +94,7 @@ export function ConditionEdge(props: EdgeProps) {
 
   return (
     <>
-      <BaseEdge
-        id={id}
-        path={path}
-        markerEnd={markerEnd}
-        style={{ stroke, strokeWidth: 1.5 }}
-      />
+      <BaseEdge id={id} path={path} markerEnd={markerEnd} style={{ stroke, strokeWidth: 1.5 }} />
       {label !== "" && (
         <EdgeLabelRenderer>
           <div

packages/workflow-dashboard/src/components/workflow-graph/role-node.tsx

@@ -45,11 +45,41 @@ export function RoleNode(props: NodeProps) {
       }}
       title={data.description}
     >
-      <Handle type="target" position={Position.Top} id="top-in" style={handleStyle} isConnectable={false} />
-      <Handle type="target" position={Position.Left} id="left-in" style={handleStyle} isConnectable={false} />
-      <Handle type="target" position={Position.Right} id="right-in" style={handleStyle} isConnectable={false} />
-      <Handle type="source" position={Position.Left} id="left-out" style={handleStyle} isConnectable={false} />
-      <Handle type="source" position={Position.Right} id="right-out" style={handleStyle} isConnectable={false} />
+      <Handle
+        type="target"
+        position={Position.Top}
+        id="top-in"
+        style={handleStyle}
+        isConnectable={false}
+      />
+      <Handle
+        type="target"
+        position={Position.Left}
+        id="left-in"
+        style={handleStyle}
+        isConnectable={false}
+      />
+      <Handle
+        type="target"
+        position={Position.Right}
+        id="right-in"
+        style={handleStyle}
+        isConnectable={false}
+      />
+      <Handle
+        type="source"
+        position={Position.Left}
+        id="left-out"
+        style={handleStyle}
+        isConnectable={false}
+      />
+      <Handle
+        type="source"
+        position={Position.Right}
+        id="right-out"
+        style={handleStyle}
+        isConnectable={false}
+      />
       <div className="flex items-center gap-1.5 font-mono">
         {icon !== null && (
           <span
@@ -67,7 +97,13 @@ export function RoleNode(props: NodeProps) {
           {data.description}
         </div>
       )}
-      <Handle type="source" position={Position.Bottom} id="bottom-out" style={handleStyle} isConnectable={false} />
+      <Handle
+        type="source"
+        position={Position.Bottom}
+        id="bottom-out"
+        style={handleStyle}
+        isConnectable={false}
+      />
     </div>
   );
 }

packages/workflow-dashboard/src/components/workflow-graph/terminal-node.tsx

@@ -50,7 +50,13 @@ export function TerminalNode(props: NodeProps) {
           isConnectable={false}
         />
       ) : (
-        <Handle type="target" position={Position.Top} id="top-in" style={handleStyle} isConnectable={false} />
+        <Handle
+          type="target"
+          position={Position.Top}
+          id="top-in"
+          style={handleStyle}
+          isConnectable={false}
+        />
       )}
       {isStart ? "▶" : "■"}
     </div>

packages/workflow-dashboard/src/components/workflow-graph/use-layout.ts

@@ -216,7 +216,11 @@ function computeLayout(input: LayoutInput): LayoutResult {
       id: edgeKey(e),
       source: e.from,
       target: e.to,
-      sourceHandle: isFeedback ? (feedbackSide === "left" ? "left-out" : "right-out") : "bottom-out",
+      sourceHandle: isFeedback
+        ? feedbackSide === "left"
+          ? "left-out"
+          : "right-out"
+        : "bottom-out",
       targetHandle: isFeedback ? (feedbackSide === "left" ? "left-in" : "right-in") : "top-in",
       type: "condition",
       data: {

packages/workflow-dashboard/src/components/workflow-list.tsx

@@ -1,175 +1,13 @@
-import { useCallback, useEffect, useMemo, useState } from "react";
-import type { WorkflowDetail } from "../api.ts";
-import { getWorkflowDetail, listWorkflows } from "../api.ts";
+import { listWorkflows } from "../api.ts";
 import { useFetch } from "../hooks.ts";
-import { type NodeState, WorkflowGraph } from "./workflow-graph/index.ts";
 
 type Props = {
   client: string;
+  onSelect: (name: string) => void;
 };
 
-type DetailCacheEntry =
-  | { status: "loading" }
-  | { status: "error"; message: string }
-  | { status: "ok"; detail: WorkflowDetail };
-
-function versionCount(detail: WorkflowDetail): number {
-  return detail.history.length + 1;
-}
-
-function ExpandedWorkflowBody({
-  cacheEntry,
-  staticNodeStates,
-}: {
-  cacheEntry: DetailCacheEntry | undefined;
-  staticNodeStates: Map<string, NodeState>;
-}) {
-  if (cacheEntry === undefined || cacheEntry.status === "loading") {
-    return (
-      <p className="text-sm py-2" style={{ color: "var(--color-text-muted)" }}>
-        Loading workflow details...
-      </p>
-    );
-  }
-
-  if (cacheEntry.status === "error") {
-    return (
-      <p className="text-sm py-2" style={{ color: "var(--color-error)" }}>
-        {cacheEntry.message}
-      </p>
-    );
-  }
-
-  const { detail } = cacheEntry;
-  const descriptor = detail.descriptor;
-  const edgeCount = descriptor !== null ? descriptor.graph.edges.length : 0;
-  const vc = versionCount(detail);
-
-  const hasGraph = descriptor !== null && edgeCount > 0;
-
-  return (
-    <div className="pt-3 border-t flex gap-4" style={{ borderColor: "var(--color-border)" }}>
-      <div className="space-y-3 shrink-0" style={{ minWidth: 200, maxWidth: 280 }}>
-        <div>
-          <p className="text-sm font-medium" style={{ color: "var(--color-text)" }}>
-            {detail.name}
-          </p>
-          <p className="text-xs mt-1 mb-1" style={{ color: "var(--color-text-muted)" }}>
-            Hash
-          </p>
-          <code className="text-xs font-mono block" style={{ color: "var(--color-accent)" }}>
-            {detail.hash}
-          </code>
-        </div>
-        <p className="text-xs" style={{ color: "var(--color-text-muted)" }}>
-          {vc} version{vc !== 1 ? "s" : ""}
-        </p>
-        <div>
-          <p className="text-xs mb-1 font-medium" style={{ color: "var(--color-text-muted)" }}>
-            Description
-          </p>
-          <p className="text-sm whitespace-pre-wrap" style={{ color: "var(--color-text)" }}>
-            {descriptor !== null && descriptor.description !== ""
-              ? descriptor.description
-              : descriptor !== null
-                ? "—"
-                : "No descriptor available for this workflow version."}
-          </p>
-        </div>
-      </div>
-      {hasGraph ? (
-        <div
-          className="rounded-lg border overflow-hidden flex-1"
-          style={{
-            borderColor: "var(--color-border)",
-            background: "var(--color-bg)",
-            minHeight: 500,
-          }}
-        >
-          <div
-            className="px-3 py-2 text-xs flex justify-between items-center"
-            style={{ color: "var(--color-text-muted)", background: "var(--color-surface)" }}
-          >
-            <span className="font-mono">Workflow graph</span>
-            <span>
-              {edgeCount} edge{edgeCount === 1 ? "" : "s"}
-            </span>
-          </div>
-          <div style={{ height: 600, width: "100%" }}>
-            <WorkflowGraph
-              graph={descriptor.graph}
-              roles={descriptor.roles}
-              nodeStates={staticNodeStates}
-              onNodeClick={null}
-            />
-          </div>
-        </div>
-      ) : null}
-    </div>
-  );
-}
-
-export function WorkflowList({ client }: Props) {
+export function WorkflowList({ client, onSelect }: Props) {
   const { status, data, error } = useFetch(() => listWorkflows(client), [client]);
-  const [expanded, setExpanded] = useState<Set<string>>(() => new Set());
-  const [detailsByName, setDetailsByName] = useState<Map<string, DetailCacheEntry>>(
-    () => new Map(),
-  );
-
-  const staticNodeStates = useMemo(() => new Map<string, NodeState>(), []);
-
-  // biome-ignore lint/correctness/useExhaustiveDependencies: reset expansion when switching clients
-  useEffect(() => {
-    setExpanded(new Set());
-    setDetailsByName(new Map());
-  }, [client]);
-
-  const ensureDetailLoaded = useCallback(
-    (name: string) => {
-      setDetailsByName((prev) => {
-        const cur = prev.get(name);
-        if (cur !== undefined && (cur.status === "ok" || cur.status === "loading")) {
-          return prev;
-        }
-        return new Map(prev).set(name, { status: "loading" });
-      });
-
-      void (async () => {
-        try {
-          const detail = await getWorkflowDetail(client, name);
-          setDetailsByName((prev) => {
-            const next = new Map(prev);
-            next.set(name, { status: "ok", detail });
-            return next;
-          });
-        } catch (e) {
-          const message = e instanceof Error ? e.message : String(e);
-          setDetailsByName((prev) => {
-            const next = new Map(prev);
-            next.set(name, { status: "error", message });
-            return next;
-          });
-        }
-      })();
-    },
-    [client],
-  );
-
-  function toggleExpanded(name: string) {
-    const wasExpanded = expanded.has(name);
-    setExpanded((prev) => {
-      const next = new Set(prev);
-      if (next.has(name)) {
-        next.delete(name);
-      } else {
-        next.add(name);
-      }
-      return next;
-    });
-    if (!wasExpanded) {
-      ensureDetailLoaded(name);
-    }
-  }
 
   if (status === "loading")
     return <p style={{ color: "var(--color-text-muted)" }}>Loading workflows...</p>;
@@ -184,58 +22,34 @@ export function WorkflowList({ client }: Props) {
         <p style={{ color: "var(--color-text-muted)" }}>No workflows registered.</p>
       ) : (
         <div className="space-y-2">
-          {workflows.map((w) => {
-            const isOpen = expanded.has(w.name);
-            return (
-              <div
-                key={w.name}
-                className="rounded-lg border overflow-hidden"
-                style={{ background: "var(--color-surface)", borderColor: "var(--color-border)" }}
-              >
-                <button
-                  type="button"
-                  onClick={() => toggleExpanded(w.name)}
-                  className="w-full text-left p-4 flex items-start justify-between gap-3 hover:opacity-90"
-                  style={{ color: "var(--color-text)" }}
-                  aria-expanded={isOpen}
-                >
-                  <div className="min-w-0 flex-1">
-                    <div className="flex items-center gap-2">
-                      <span
-                        className="text-xs font-mono"
-                        style={{ color: "var(--color-text-muted)" }}
-                      >
-                        {isOpen ? "▼" : "▶"}
-                      </span>
-                      <span className="font-medium">{w.name}</span>
-                    </div>
-                    <code
-                      className="text-xs mt-1 block font-mono truncate"
-                      style={{ color: "var(--color-accent)" }}
-                    >
-                      {w.hash !== null ? w.hash : "—"}
-                    </code>
-                    {w.timestamp !== null ? (
-                      <span
-                        className="text-xs mt-1 block"
-                        style={{ color: "var(--color-text-muted)" }}
-                      >
-                        Updated {new Date(w.timestamp).toLocaleString()}
-                      </span>
-                    ) : null}
-                  </div>
-                </button>
-                {isOpen ? (
-                  <div className="px-4 pb-4">
-                    <ExpandedWorkflowBody
-                      cacheEntry={detailsByName.get(w.name)}
-                      staticNodeStates={staticNodeStates}
-                    />
-                  </div>
-                ) : null}
+          {workflows.map((w) => (
+            <button
+              key={w.name}
+              type="button"
+              onClick={() => onSelect(w.name)}
+              className="w-full text-left p-4 rounded-lg border hover:opacity-90"
+              style={{
+                background: "var(--color-surface)",
+                borderColor: "var(--color-border)",
+                color: "var(--color-text)",
+              }}
+            >
+              <div className="flex items-center gap-2">
+                <span className="font-medium">{w.name}</span>
               </div>
-            );
-          })}
+              <code
+                className="text-xs mt-1 block font-mono truncate"
+                style={{ color: "var(--color-accent)" }}
+              >
+                {w.hash !== null ? w.hash : "—"}
+              </code>
+              {w.timestamp !== null ? (
+                <span className="text-xs mt-1 block" style={{ color: "var(--color-text-muted)" }}>
+                  Updated {new Date(w.timestamp).toLocaleString()}
+                </span>
+              ) : null}
+            </button>
+          ))}
         </div>
       )}
     </div>

packages/workflow-dashboard/src/use-hash-route.ts

@@ -6,6 +6,7 @@ type HashRoute = {
   view: View;
   client: string | null;
   threadId: string | null;
+  workflowName: string | null;
 };
 
 function parseHash(hash: string): HashRoute {
@@ -19,6 +20,7 @@ function parseHash(hash: string): HashRoute {
       view: parts[0] as View,
       client: null,
       threadId: parts[0] === "threads" && parts.length > 1 ? parts.slice(1).join("/") : null,
+      workflowName: parts[0] === "workflows" && parts.length > 1 ? parts.slice(1).join("/") : null,
     };
   }
 
@@ -27,13 +29,17 @@ function parseHash(hash: string): HashRoute {
   const viewPart = parts[1] ?? "threads";
   const view: View = viewPart === "workflows" ? "workflows" : "threads";
   const threadId = view === "threads" && parts.length > 2 ? parts.slice(2).join("/") : null;
+  const workflowName = view === "workflows" && parts.length > 2 ? parts.slice(2).join("/") : null;
 
-  return { view, client, threadId };
+  return { view, client, threadId, workflowName };
 }
 
 function buildHash(route: HashRoute): string {
   const prefix = route.client ? `${route.client}/` : "";
   if (route.view === "workflows") {
+    if (route.workflowName !== null) {
+      return `#${prefix}workflows/${route.workflowName}`;
+    }
     return `#${prefix}workflows`;
   }
   if (route.threadId !== null) {
@@ -46,9 +52,11 @@ export function useHashRoute(): {
   view: View;
   client: string | null;
   threadId: string | null;
+  workflowName: string | null;
   setView: (v: View) => void;
   setClient: (a: string | null) => void;
   setThreadId: (id: string | null) => void;
+  setWorkflowName: (name: string | null) => void;
 } {
   const [route, setRoute] = useState<HashRoute>(() => parseHash(window.location.hash));
 
@@ -67,17 +75,25 @@ export function useHashRoute(): {
   }, []);
 
   const setView = useCallback(
-    (v: View) => navigate({ view: v, client: route.client, threadId: null }),
+    (v: View) => navigate({ view: v, client: route.client, threadId: null, workflowName: null }),
     [navigate, route.client],
   );
 
   const setClient = useCallback(
-    (a: string | null) => navigate({ view: route.view, client: a, threadId: null }),
+    (a: string | null) =>
+      navigate({ view: route.view, client: a, threadId: null, workflowName: null }),
     [navigate, route.view],
   );
 
   const setThreadId = useCallback(
-    (id: string | null) => navigate({ view: "threads", client: route.client, threadId: id }),
+    (id: string | null) =>
+      navigate({ view: "threads", client: route.client, threadId: id, workflowName: null }),
+    [navigate, route.client],
+  );
+
+  const setWorkflowName = useCallback(
+    (name: string | null) =>
+      navigate({ view: "workflows", client: route.client, threadId: null, workflowName: name }),
     [navigate, route.client],
   );
 
@@ -85,8 +101,10 @@ export function useHashRoute(): {
     view: route.view,
     client: route.client,
     threadId: route.threadId,
+    workflowName: route.workflowName,
     setView,
     setClient,
     setThreadId,
+    setWorkflowName,
   };
 }

packages/workflow-gateway/src/index.ts

@@ -305,7 +305,12 @@ app.all("/api/clients/:client/*", async (c) => {
       headers: forwardRecord,
       body: bodyStr,
     };
-    const proxyResp = await fetchThroughClientSocket(c.env, client, c.env.GATEWAY_SECRET, wsRequest);
+    const proxyResp = await fetchThroughClientSocket(
+      c.env,
+      client,
+      c.env.GATEWAY_SECRET,
+      wsRequest,
+    );
     if (proxyResp.status !== 503) {
       return new Response(proxyResp.body, {
         status: proxyResp.status,

packages/workflow-protocol/src/index.ts

@@ -13,6 +13,7 @@ export type {
   AdapterFn,
   AdvanceOutcome,
   AgentContext,
+  AgentFn,
   CasStore,
   ExtractFn,
   ExtractResult,

packages/workflow-protocol/src/types.ts

@@ -151,6 +151,15 @@ export type RoleFn<T> = (ctx: ThreadContext, runtime: WorkflowRuntime) => Promis
 
 export type AdapterFn = <T>(prompt: string, schema: z.ZodType<T>) => RoleFn<T>;
 
+/**
+ * Core agent function. Input is always {@link ThreadContext}, output is always string.
+ * `Opt` captures agent-specific structured options.
+ * Agents with no extra options use `AgentFn` (Opt defaults to void).
+ */
+export type AgentFn<Opt = void> = Opt extends void
+  ? (ctx: ThreadContext) => Promise<string>
+  : (ctx: ThreadContext, options: Opt) => Promise<string>;
+
 export type AdapterBinding = {
   adapter: AdapterFn;
   overrides: Partial<Record<string, AdapterFn>> | null;

packages/workflow-runtime/src/index.ts

@@ -5,6 +5,7 @@ export type {
   AdapterBinding,
   AdapterFn,
   AgentContext,
+  AgentFn,
   CasStore,
   ExtractFn,
   ExtractResult,

packages/workflow-runtime/src/types.ts

@@ -7,6 +7,7 @@ export type {
   AdapterFn,
   AdvanceOutcome,
   AgentContext,
+  AgentFn,
   CasStore,
   ExtractFn,
   ExtractResult,

packages/workflow-template-develop/bundle-entry.ts

@@ -8,15 +8,6 @@ import { createWorkflow } from "@uncaged/workflow-runtime";
 import { optionalEnv, requireEnv } from "@uncaged/workflow-util";
 import { buildDevelopDescriptor, developWorkflowDefinition } from "./src/index.js";
 
-const llmProvider = {
-  baseUrl: optionalEnv(
-    "WORKFLOW_LLM_BASE_URL",
-    "https://dashscope.aliyuncs.com/compatible-mode/v1",
-  ),
-  apiKey: requireEnv("WORKFLOW_LLM_API_KEY", "set WORKFLOW_LLM_API_KEY for meta extraction"),
-  model: optionalEnv("WORKFLOW_LLM_MODEL", "qwen-plus"),
-};
-
 const adapter = createCursorAgent({
   command: requireEnv("WORKFLOW_CURSOR_COMMAND", "set WORKFLOW_CURSOR_COMMAND (e.g. cursor-agent)"),
   model: optionalEnv("WORKFLOW_CURSOR_MODEL"),
@@ -24,7 +15,6 @@ const adapter = createCursorAgent({
     ? Number(optionalEnv("WORKFLOW_CURSOR_TIMEOUT"))
     : 0,
   workspace: null,
-  llmProvider,
 });
 
 const wf = createWorkflow(developWorkflowDefinition, { adapter, overrides: null });

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

@@ -0,0 +1,48 @@
+import { putContentNodeWithRefs } from "@uncaged/workflow-cas";
+import type {
+  AdapterFn,
+  AgentFn,
+  RoleResult,
+  ThreadContext,
+  WorkflowRuntime,
+} from "@uncaged/workflow-runtime";
+import type * as z from "zod/v4";
+
+export type ExtractOptionsFn<Opt> = (
+  ctx: ThreadContext,
+  prompt: string,
+  runtime: WorkflowRuntime,
+) => Promise<Opt>;
+
+/**
+ * Bridges {@link AgentFn} to {@link AdapterFn}.
+ *
+ * 1. extract(ctx, prompt, runtime) → Opt
+ * 2. agent(ctx, options) → raw string
+ * 3. Store raw string in CAS
+ * 4. runtime.extract(schema, contentHash) → typed meta T
+ */
+export function createAgentAdapter<Opt>(
+  agent: AgentFn<Opt>,
+  extract: ExtractOptionsFn<Opt>,
+): AdapterFn {
+  return <T>(prompt: string, schema: z.ZodType<T>) => {
+    return async (ctx: ThreadContext, runtime: WorkflowRuntime): Promise<RoleResult<T>> => {
+      const options = await extract(ctx, prompt, runtime);
+      const raw = await (agent as (ctx: ThreadContext, optionsParam: Opt) => Promise<string>)(
+        ctx,
+        options,
+      );
+      const contentHash = await putContentNodeWithRefs(runtime.cas, raw, []);
+      const extracted = await runtime.extract(
+        schema as z.ZodType<Record<string, unknown>>,
+        contentHash,
+      );
+      return { meta: extracted.meta as T, childThread: null };
+    };
+  };
+}
+
+export function createSimpleAgentAdapter(agent: AgentFn<void>): AdapterFn {
+  return createAgentAdapter(agent, async () => undefined as unknown as undefined);
+}

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

@@ -1,54 +0,0 @@
-import { putContentNodeWithRefs } from "@uncaged/workflow-cas";
-import type {
-  AdapterFn,
-  RoleResult,
-  ThreadContext,
-  WorkflowRuntime,
-} from "@uncaged/workflow-runtime";
-import type * as z from "zod/v4";
-
-export type { WorkflowRuntime } from "@uncaged/workflow-runtime";
-
-/**
- * Result from a text-producing agent (CLI spawn, LLM call, etc.).
- * `output` is the raw text; `childThread` links to a spawned sub-workflow.
- */
-export type TextAdapterResult = {
-  output: string;
-  childThread: string | null;
-};
-
-/**
- * A function that produces raw text output given the thread context and
- * the system prompt for the current role.
- */
-export type TextProducerFn = (
-  ctx: ThreadContext,
-  prompt: string,
-  runtime: WorkflowRuntime,
-) => Promise<string | TextAdapterResult>;
-
-/**
- * Creates an {@link AdapterFn} from a text-producing function.
- *
- * The adapter:
- * 1. Calls the producer with thread context + system prompt
- * 2. Stores output in CAS
- * 3. Runs the extract phase to produce typed meta
- * 4. Returns `{ meta, childThread }`
- */
-export function createTextAdapter(producer: TextProducerFn): AdapterFn {
-  return <T>(prompt: string, schema: z.ZodType<T>) => {
-    return async (ctx: ThreadContext, runtime: WorkflowRuntime): Promise<RoleResult<T>> => {
-      const result = await producer(ctx, prompt, runtime);
-      const output = typeof result === "string" ? result : result.output;
-      const childThread = typeof result === "string" ? null : result.childThread;
-      const contentHash = await putContentNodeWithRefs(runtime.cas, output, []);
-      const extracted = await runtime.extract(
-        schema as z.ZodType<Record<string, unknown>>,
-        contentHash,
-      );
-      return { meta: extracted.meta as T, childThread };
-    };
-  };
-}

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

@@ -1,5 +1,5 @@
 export { buildAgentPrompt, buildThreadInput } from "./build-agent-prompt.js";
-export type { TextAdapterResult, TextProducerFn } from "./create-text-adapter.js";
-export { createTextAdapter } from "./create-text-adapter.js";
+export type { ExtractOptionsFn } from "./create-agent-adapter.js";
+export { createAgentAdapter, createSimpleAgentAdapter } from "./create-agent-adapter.js";
 export type { SpawnCliConfig, SpawnCliError, SpawnCliResult } from "./spawn-cli.js";
 export { spawnCli } from "./spawn-cli.js";

scripts/lint-log-tags.sh

@@ -10,7 +10,7 @@ while IFS= read -r match; do
   file="${match%%:*}"
   rest="${match#*:}"
   line="${rest%%:*}"
-  tag=$(echo "$rest" | grep -oP '\.log\(\s*"\K[A-Za-z0-9]+')
+  tag=$(echo "$rest" | sed -n 's/.*\.log( *"\([A-Za-z0-9]*\)".*/\1/p')
   if echo "$tag" | grep -qiE '[ILOU]'; then
     echo "  ❌ ${file}:${line}  tag \"${tag}\" contains invalid Crockford Base32 char (I/L/O/U)"
     BAD=1