refactor(agents): migrate LLM/Hermes/Cursor to createAgentAdapter

- LLM: AgentFn<{prompt}> + createAgentAdapter, chatCompletionText unchanged
- Hermes: AgentFn<{prompt}> + createAgentAdapter, config validation in extract
- Cursor: AgentFn<{prompt, workspace}> + createAgentAdapter, workspace
  extraction moved to extract fn, AgentFn itself only receives resolved options

All public API signatures preserved. createTextAdapter/TextProducerFn retained.

Closes #261, Phase 2 of #252

.changeset/config.json

@@ -2,16 +2,10 @@
   "$schema": "https://unpkg.com/@changesets/config@3.1.4/schema.json",
   "changelog": "@changesets/cli/changelog",
   "commit": false,
-  "fixed": [
-    [
-      "@uncaged/*"
-    ]
-  ],
+  "fixed": [["@uncaged/*"]],
   "linked": [],
   "access": "public",
   "baseBranch": "main",
   "updateInternalDependencies": "patch",
-  "ignore": [
-    "@uncaged/workflow-dashboard"
-  ]
+  "ignore": ["@uncaged/workflow-dashboard"]
 }

biome.json

@@ -1,5 +1,5 @@
 {
-  "$schema": "https://biomejs.dev/schemas/2.4.14/schema.json",
+  "$schema": "https://biomejs.dev/schemas/2.4.15/schema.json",
   "files": {
     "includes": ["**", "!**/dist", "!**/node_modules", "!packages/workflow/workflow"]
   },

develop-entry.ts

@@ -0,0 +1,16 @@
+import { createCursorAgent } from "./packages/workflow-agent-cursor/src/index.js";
+import { createWorkflow } from "./packages/workflow-runtime/src/create-workflow.js";
+import {
+  buildDevelopDescriptor,
+  developWorkflowDefinition,
+} from "./packages/workflow-template-develop/src/index.js";
+
+const agent = createCursorAgent({
+  command: "/home/azureuser/.local/bin/cursor-agent",
+  model: "auto",
+  timeout: 300_000,
+  workspace: null,
+});
+
+export const descriptor = buildDevelopDescriptor();
+export const run = createWorkflow(developWorkflowDefinition, { adapter: agent, overrides: null });

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

@@ -1,36 +1,25 @@
 import { describe, expect, test } from "bun:test";
 import { createCursorAgent, validateCursorAgentConfig } from "../src/index.js";
 
-describe("validateCursorAgentConfig", () => {
-  test("accepts valid config with explicit workspace", () => {
-    const r = validateCursorAgentConfig({
-      command: "/usr/local/bin/cursor-agent",
-      model: null,
-      timeout: 0,
-      workspace: "/tmp/test-project",
-      llmProvider: null,
-    });
-    expect(r.ok).toBe(true);
-  });
+const baseConfig = {
+  command: "/usr/local/bin/cursor-agent",
+  model: null as string | null,
+  timeout: 0,
+  workspace: null as string | null,
+};
 
-  test("accepts valid config with null workspace and llmProvider", () => {
+describe("validateCursorAgentConfig", () => {
+  test("accepts valid config", () => {
     const r = validateCursorAgentConfig({
-      command: "/usr/local/bin/cursor-agent",
-      model: null,
-      timeout: 0,
-      workspace: null,
-      llmProvider: { baseUrl: "http://localhost", apiKey: "test", model: "test" },
+      ...baseConfig,
     });
     expect(r.ok).toBe(true);
   });
 
   test("rejects non-absolute command", () => {
     const r = validateCursorAgentConfig({
+      ...baseConfig,
       command: "cursor-agent",
-      model: null,
-      timeout: 0,
-      workspace: "/tmp/test-project",
-      llmProvider: null,
     });
     expect(r.ok).toBe(false);
     if (!r.ok) {
@@ -38,87 +27,38 @@ describe("validateCursorAgentConfig", () => {
     }
   });
 
-  test("rejects empty workspace string", () => {
+  test("rejects negative timeout", () => {
     const r = validateCursorAgentConfig({
-      command: "/usr/local/bin/cursor-agent",
-      model: null,
-      timeout: 0,
-      workspace: "",
-      llmProvider: 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");
     }
   });
-
-  test("rejects null workspace without llmProvider", () => {
-    const r = validateCursorAgentConfig({
-      command: "/usr/local/bin/cursor-agent",
-      model: null,
-      timeout: 0,
-      workspace: null,
-      llmProvider: null,
-    });
-    expect(r.ok).toBe(false);
-    if (!r.ok) {
-      expect(r.error).toContain("llmProvider");
-    }
-  });
-
-  test("rejects negative timeout", () => {
-    const r = validateCursorAgentConfig({
-      command: "/usr/local/bin/cursor-agent",
-      model: null,
-      timeout: -1,
-      workspace: "/tmp/test-project",
-      llmProvider: null,
-    });
-    expect(r.ok).toBe(false);
-  });
 });
 
 describe("createCursorAgent", () => {
-  test("returns an AdapterFn with explicit workspace", () => {
+  test("returns an AdapterFn", () => {
     const agent = createCursorAgent({
-      command: "/usr/local/bin/cursor-agent",
-      model: null,
-      timeout: 0,
-      workspace: "/tmp/test-project",
-      llmProvider: null,
-    });
-    expect(typeof agent).toBe("function");
-  });
-
-  test("returns an AdapterFn with null workspace and llmProvider", () => {
-    const agent = createCursorAgent({
-      command: "/usr/local/bin/cursor-agent",
-      model: null,
-      timeout: 0,
-      workspace: null,
-      llmProvider: { baseUrl: "http://localhost", apiKey: "test", model: "test" },
+      ...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,
-      workspace: "/tmp/test-project",
-      llmProvider: null,
-    });
-    expect(typeof agent).toBe("function");
-  });
-
-  test("defers validation — null workspace without llmProvider does not throw at construction", () => {
-    const agent = createCursorAgent({
-      command: "/usr/local/bin/cursor-agent",
-      model: null,
-      timeout: 0,
-      workspace: null,
-      llmProvider: null,
     });
     expect(typeof agent).toBe("function");
   });

packages/workflow-agent-cursor/package.json

@@ -12,8 +12,8 @@
     "test": "bun test"
   },
   "dependencies": {
+    "@uncaged/workflow-cas": "workspace:^",
     "@uncaged/workflow-protocol": "workspace:^",
-    "@uncaged/workflow-reactor": "workspace:^",
     "@uncaged/workflow-runtime": "workspace:^",
     "@uncaged/workflow-util": "workspace:^",
     "@uncaged/workflow-util-agent": "workspace:^",

packages/workflow-agent-cursor/src/extract-workspace.ts

@@ -1,5 +1,5 @@
-import type { AgentContext, LlmProvider } from "@uncaged/workflow-protocol";
-import { createLlmFn, createThreadReactor } from "@uncaged/workflow-reactor";
+import { putContentNodeWithRefs } from "@uncaged/workflow-cas";
+import type { ThreadContext, WorkflowRuntime } from "@uncaged/workflow-runtime";
 import type { LogFn } from "@uncaged/workflow-util";
 import * as z from "zod/v4";
 
@@ -7,10 +7,7 @@ const workspaceSchema = z.object({
   workspace: z.string().describe("Absolute filesystem path of the project workspace"),
 });
 
-const EXTRACT_SYSTEM_FN = (_toolName: string) =>
-  `You are a workspace-path extractor. Given a workflow agent context (task description and previous step outputs), identify the absolute filesystem path of the project workspace where code changes should be made. Call the tool with the absolute path.`;
-
-function buildExtractionInput(ctx: AgentContext): string {
+function buildExtractionInput(ctx: ThreadContext): string {
   const lines: string[] = [];
   lines.push("## Task");
   lines.push(ctx.start.content);
@@ -21,48 +18,25 @@ function buildExtractionInput(ctx: AgentContext): string {
     lines.push(`Meta: ${JSON.stringify(step.meta)}`);
   }
 
+  lines.push("");
+  lines.push(
+    "Extract the absolute filesystem path of the project workspace where code changes should be made.",
+  );
+
   return lines.join("\n");
 }
 
 export async function extractWorkspacePath(
-  ctx: AgentContext,
-  provider: LlmProvider,
+  ctx: ThreadContext,
+  runtime: WorkflowRuntime,
   logger: LogFn,
 ): Promise<string | null> {
-  const reactor = createThreadReactor<null>({
-    llm: createLlmFn(provider),
-    maxRounds: 2,
-    staticTools: [],
-    structuredToolFromSchema: (schema) => {
-      const jsonSchema = z.toJSONSchema(schema);
-      return {
-        name: "set_workspace",
-        tool: {
-          type: "function" as const,
-          function: {
-            name: "set_workspace",
-            description: "Set the extracted workspace path",
-            parameters: jsonSchema as Record<string, unknown>,
-          },
-        },
-      };
-    },
-    systemPromptForStructuredTool: EXTRACT_SYSTEM_FN,
-    toolHandler: async () => "unknown tool",
-  });
+  const input = buildExtractionInput(ctx);
+  const contentHash = await putContentNodeWithRefs(runtime.cas, input, []);
 
-  const result = await reactor({
-    thread: null,
-    input: buildExtractionInput(ctx),
-    schema: workspaceSchema,
-  });
+  const result = await runtime.extract(workspaceSchema, contentHash);
+  const workspace = result.meta.workspace.trim();
 
-  if (!result.ok) {
-    logger("W8KN3QYT", `workspace extraction failed: ${result.error}`);
-    return null;
-  }
-
-  const workspace = result.value.workspace.trim();
   if (!workspace.startsWith("/")) {
     logger("H4PM7RXV", `workspace extraction returned non-absolute path: ${workspace}`);
     return null;

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

@@ -1,8 +1,8 @@
-import type { AdapterFn } 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,36 +33,15 @@ function resolveCursorModel(model: string | null): string {
   return model === null ? "auto" : model;
 }
 
-/** Runs `cursor-agent` with workspace from config or extracted from context via LLM. */
-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 createTextAdapter(async (ctx, prompt) => {
-    const validated = validateCursorAgentConfig(config);
-    if (!validated.ok) {
-      throw new Error(validated.error);
-    }
-
-    let workspace: string;
-
-    if (config.workspace !== null) {
-      workspace = config.workspace;
-    } else {
-      if (config.llmProvider === null) {
-        throw new Error("cursor-agent: llmProvider is required when workspace is null");
-      }
-      const agentCtx = { ...ctx, currentRole: { name: "cursor", systemPrompt: prompt } };
-      const extracted = await extractWorkspacePath(agentCtx, config.llmProvider, logger);
-      if (extracted === null) {
-        throw new Error(
-          "cursor-agent: failed to extract workspace path from context. Provide an explicit workspace or ensure previous steps include a repoPath.",
-        );
-      }
-      workspace = extracted;
-    }
+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}`;
@@ -86,5 +65,33 @@ export function createCursorAgent(config: CursorAgentConfig): AdapterFn {
       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

@@ -1,12 +1,11 @@
-import type { LlmProvider } from "@uncaged/workflow-protocol";
-
 export type CursorAgentConfig = {
   /** Absolute path to the cursor-agent CLI binary. */
   command: string;
   model: string | null;
   timeout: number;
-  /** Explicit workspace path. When `null`, the agent extracts workspace from AgentContext via a ReAct LLM call. */
+  /**
+   * When non-null, use this workspace directory for `cursor-agent` instead of resolving it
+   * from the thread via runtime extraction.
+   */
   workspace: string | null;
-  /** Required when `workspace` is `null` — LLM provider used for workspace extraction. */
-  llmProvider: LlmProvider | null;
 };

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

@@ -8,14 +8,11 @@ export function validateCursorAgentConfig(config: CursorAgentConfig): Result<voi
   if (!isAbsolute(config.command)) {
     return err("command must be an absolute path to the cursor-agent CLI binary");
   }
-  if (config.workspace !== null && config.workspace.length === 0) {
-    return err("workspace must be a non-empty string (absolute path) or null for auto-detection");
-  }
-  if (config.workspace === null && config.llmProvider === null) {
-    return err("llmProvider is required when workspace is null (needed for workspace extraction)");
-  }
   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) => {
-    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) => {
+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/components/thread-detail.tsx

@@ -39,7 +39,8 @@ function computeNodeStates(records: readonly ThreadRecord[]): Map<string, NodeSt
     states.set(role, !hasResult && isLast ? "active" : "completed");
   }
 
-  if (roleRecords.length > 0) {
+  const hasStart = records.some((r) => r.type === "thread-start");
+  if (hasStart) {
     states.set("__start__", "completed");
   }
   if (hasResult) {
@@ -79,28 +80,58 @@ export function ThreadDetail({ client, threadId, onBack }: Props) {
   const descriptor = descriptorFetch.status === "ok" ? descriptorFetch.data : null;
   const nodeStates = useMemo(() => computeNodeStates(records), [records]);
 
-  const firstIndexByRole = useMemo(() => {
-    const m = new Map<string, number>();
+  const indicesByRole = useMemo(() => {
+    const m = new Map<string, number[]>();
     for (let i = 0; i < records.length; i++) {
       const r = records[i];
-      if (r.type === "role" && !m.has(r.role)) {
-        m.set(r.role, i);
+      if (r.type === "role") {
+        const list = m.get(r.role) ?? [];
+        list.push(i);
+        m.set(r.role, list);
       }
     }
     return m;
   }, [records]);
 
-  const handleGraphNodeClick = useCallback((roleName: string) => {
-    const el = firstCardByRoleRef.current.get(roleName);
-    if (el == null) return;
-    el.scrollIntoView({ behavior: "smooth", block: "center" });
-    if (highlightTimerRef.current !== null) clearTimeout(highlightTimerRef.current);
-    setHighlightedRole(roleName);
-    highlightTimerRef.current = setTimeout(() => {
-      setHighlightedRole(null);
-      highlightTimerRef.current = null;
-    }, 1500);
-  }, []);
+  // 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;
+
+    // __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;
+    }
+
+    // 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 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 () => {
@@ -237,11 +268,13 @@ export function ThreadDetail({ client, threadId, onBack }: Props) {
               {records.map((r, i) => {
                 const key = `${threadId}-${i}`;
                 if (r.type === "role") {
-                  const isFirstForRole = firstIndexByRole.get(r.role) === i;
+                  const roleIndices = indicesByRole.get(r.role);
+                  const isFirstForRole = roleIndices !== undefined && roleIndices[0] === i;
                   const flash = highlightedRole === r.role;
                   return (
                     <div
                       key={key}
+                      data-record-index={i}
                       ref={(el) => {
                         if (!isFirstForRole) return;
                         if (el !== null) firstCardByRoleRef.current.set(r.role, el);
@@ -252,7 +285,7 @@ export function ThreadDetail({ client, threadId, onBack }: Props) {
                     </div>
                   );
                 }
-                return <RecordCard key={key} record={r} highlighted={false} />;
+                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-graph/condition-edge.tsx

@@ -2,7 +2,7 @@ import { BaseEdge, EdgeLabelRenderer, type EdgeProps, getSmoothStepPath } from "
 import type { ConditionEdgeData } from "./types.ts";
 
 // Must match the FEEDBACK_OFFSET_X in use-layout.ts
-const FEEDBACK_OFFSET_X = 100;
+const FEEDBACK_OFFSET_X = 80;
 // Radius for feedback edge corners
 const FEEDBACK_RADIUS = 16;
 

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

@@ -31,7 +31,7 @@ export function RoleNode(props: NodeProps) {
 
   return (
     <div
-      className={`px-3 py-2 rounded-md border-2 text-xs font-medium ${t.state !== "default" ? "cursor-pointer" : ""} ${isActive ? "wf-node-pulse" : ""}`}
+      className={`px-3 py-2 rounded-md border-2 text-xs font-medium ${data.state !== "default" ? "cursor-pointer" : ""} ${isActive ? "wf-node-pulse" : ""}`}
       style={{
         width: 180,
         height: 60,
@@ -45,7 +45,11 @@ export function RoleNode(props: NodeProps) {
       }}
       title={data.description}
     >
-      <Handle type="target" position={Position.Top} 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
@@ -63,7 +67,7 @@ export function RoleNode(props: NodeProps) {
           {data.description}
         </div>
       )}
-      <Handle type="source" position={Position.Bottom} 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

@@ -31,7 +31,7 @@ export function TerminalNode(props: NodeProps) {
 
   return (
     <div
-      className={`rounded-full border-2 flex items-center justify-center text-[10px] font-bold ${isActive ? "wf-node-pulse" : ""}`}
+      className={`rounded-full border-2 flex items-center justify-center text-[10px] font-bold ${isActive ? "wf-node-pulse" : ""} ${data.state !== "default" ? "cursor-pointer" : ""}`}
       style={{
         width: 40,
         height: 40,
@@ -45,11 +45,12 @@ export function TerminalNode(props: NodeProps) {
         <Handle
           type="source"
           position={Position.Bottom}
+          id="bottom-out"
           style={handleStyle}
           isConnectable={false}
         />
       ) : (
-        <Handle type="target" position={Position.Top} 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

@@ -12,7 +12,7 @@ const TERMINAL_NODE_SIZE = 40;
 // Vertical gap between nodes in the spine
 const LAYER_GAP = 80;
 // Horizontal offset for feedback (back) edges routed on the right side
-const FEEDBACK_OFFSET_X = 100;
+const FEEDBACK_OFFSET_X = 80;
 
 type LayoutInput = {
   edges: readonly WorkflowGraphEdge[];
@@ -216,6 +216,8 @@ function computeLayout(input: LayoutInput): LayoutResult {
       id: edgeKey(e),
       source: e.from,
       target: e.to,
+      sourceHandle: isFeedback ? (feedbackSide === "left" ? "left-out" : "right-out") : "bottom-out",
+      targetHandle: isFeedback ? (feedbackSide === "left" ? "left-in" : "right-in") : "top-in",
       type: "condition",
       data: {
         condition: e.condition,

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

@@ -32,16 +32,16 @@ const edgeTypes: EdgeTypes = {
   condition: ConditionEdge,
 };
 
-function handleRoleNodeClick(onRoleClick: (roleName: string) => void, node: Node): void {
-  if (node.type !== "role") return;
-  onRoleClick(node.id);
+function handleNodeClick(onNodeClick: (nodeId: string) => void, node: Node): void {
+  if (node.type !== "role" && node.type !== "terminal") return;
+  onNodeClick(node.id);
 }
 
 export function WorkflowGraph({ graph, roles, nodeStates, onNodeClick }: Props) {
   const layout = useLayout({ edges: graph.edges, roles, nodeStates });
 
   const onNodeClickHandler: OnNodeClick | undefined =
-    onNodeClick !== null ? (_e, node) => handleRoleNodeClick(onNodeClick, node) : undefined;
+    onNodeClick !== null ? (_e, node) => handleNodeClick(onNodeClick, node) : undefined;
 
   const styledEdges = useMemo(
     () =>

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

@@ -48,10 +48,7 @@ function ExpandedWorkflowBody({
   const hasGraph = descriptor !== null && edgeCount > 0;
 
   return (
-    <div
-      className="pt-3 border-t flex gap-4"
-      style={{ borderColor: "var(--color-border)" }}
-    >
+    <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)" }}>
@@ -83,7 +80,11 @@ function ExpandedWorkflowBody({
       {hasGraph ? (
         <div
           className="rounded-lg border overflow-hidden flex-1"
-          style={{ borderColor: "var(--color-border)", background: "var(--color-bg)", minHeight: 500 }}
+          style={{
+            borderColor: "var(--color-border)",
+            background: "var(--color-bg)",
+            minHeight: 500,
+          }}
         >
           <div
             className="px-3 py-2 text-xs flex justify-between items-center"

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/smoke-greet-entry.ts

@@ -0,0 +1,101 @@
+/**
+ * greet workflow — smoke test entry
+ * Single role: greeter takes a prompt and returns a structured greeting.
+ * 小橘 🍊
+ */
+
+import type {
+  AdapterFn,
+  ModeratorTable,
+  RoleFn,
+  RoleResult,
+  ThreadContext,
+  WorkflowDefinition,
+  WorkflowRuntime,
+} from "@uncaged/workflow-runtime";
+import { createWorkflow, END, START } from "@uncaged/workflow-runtime";
+import * as z from "zod/v4";
+
+type GreetMeta = {
+  greeter: { greeting: string; language: string };
+};
+
+const greeterSchema = z.object({
+  greeting: z.string().describe("A friendly greeting message"),
+  language: z.string().describe("The language of the greeting"),
+});
+
+const roles: WorkflowDefinition<GreetMeta>["roles"] = {
+  greeter: {
+    description: "Generates a friendly greeting",
+    systemPrompt:
+      "You are a friendly greeter. Given a user prompt, produce a warm greeting. Respond in valid JSON with keys: greeting (string), language (string).",
+    schema: greeterSchema,
+    extractRefs: null,
+  },
+};
+
+const table: ModeratorTable<GreetMeta> = {
+  [START]: [{ condition: "FALLBACK", role: "greeter" }],
+  greeter: [{ condition: "FALLBACK", role: END }],
+};
+
+export const descriptor = {
+  name: "greet",
+  description: "A simple greeting workflow for smoke testing",
+  graph: { [START]: ["greeter"], greeter: [END] },
+  roles: { greeter: { description: "Generates a friendly greeting" } },
+};
+
+function createLazyAdapter(): AdapterFn {
+  let cached: { baseUrl: string; apiKey: string; model: string } | null = null;
+  function getProvider() {
+    if (cached !== null) return cached;
+    const apiKey = process.env.DASHSCOPE_API_KEY;
+    if (!apiKey) throw new Error("missing env: DASHSCOPE_API_KEY");
+    cached = {
+      baseUrl: "https://dashscope.aliyuncs.com/compatible-mode/v1",
+      apiKey,
+      model: process.env.WORKFLOW_MODEL ?? "qwen-plus",
+    };
+    return cached;
+  }
+
+  return (<T>(prompt: string, schema: z.ZodType<T>): RoleFn<T> => {
+    return async (ctx: ThreadContext, _runtime: WorkflowRuntime): Promise<RoleResult<T>> => {
+      const provider = getProvider();
+      const response = await fetch(`${provider.baseUrl}/chat/completions`, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${provider.apiKey}`,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+          model: provider.model,
+          messages: [
+            { role: "system", content: prompt },
+            {
+              role: "user",
+              content: `${ctx.start.content}\n\nRespond with JSON: ${JSON.stringify(z.toJSONSchema(schema))}`,
+            },
+          ],
+          response_format: { type: "json_object" },
+        }),
+      });
+      if (!response.ok) {
+        const body = await response.text();
+        throw new Error(`LLM error ${response.status}: ${body.slice(0, 500)}`);
+      }
+      const data = (await response.json()) as { choices: Array<{ message: { content: string } }> };
+      const text = data.choices[0]?.message?.content;
+      if (!text) throw new Error("Empty LLM response");
+      const parsed = schema.parse(JSON.parse(text));
+      return { meta: parsed, childThread: null };
+    };
+  }) as AdapterFn;
+}
+
+export const run = createWorkflow<GreetMeta>(
+  { roles, table },
+  { adapter: createLazyAdapter(), overrides: 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-template-develop/src/roles/planner.ts

@@ -63,5 +63,5 @@ export const plannerRole: RoleDefinition<PlannerMeta> = {
   description: "Breaks the task into sequential phases for the coder.",
   systemPrompt: PLANNER_SYSTEM,
   schema: plannerMetaSchema,
-  extractRefs: (meta) => meta.status === "planned" ? meta.phases.map((p) => p.hash) : [],
+  extractRefs: (meta) => (meta.status === "planned" ? meta.phases.map((p) => p.hash) : []),
 };

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

@@ -7,6 +7,8 @@ import type {
 } 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.
@@ -23,6 +25,7 @@ export type TextAdapterResult = {
 export type TextProducerFn = (
   ctx: ThreadContext,
   prompt: string,
+  runtime: WorkflowRuntime,
 ) => Promise<string | TextAdapterResult>;
 
 /**
@@ -37,7 +40,7 @@ export type TextProducerFn = (
 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);
+      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, []);

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

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

smoke-greet-entry.ts

@@ -0,0 +1,101 @@
+/**
+ * greet workflow — smoke test entry
+ * Single role: greeter takes a prompt and returns a structured greeting.
+ * 小橘 🍊
+ */
+
+import type {
+  AdapterFn,
+  ModeratorTable,
+  RoleFn,
+  RoleResult,
+  ThreadContext,
+  WorkflowDefinition,
+  WorkflowRuntime,
+} from "@uncaged/workflow-runtime";
+import { createWorkflow, END, START } from "@uncaged/workflow-runtime";
+import * as z from "zod/v4";
+
+type GreetMeta = {
+  greeter: { greeting: string; language: string };
+};
+
+const greeterSchema = z.object({
+  greeting: z.string().describe("A friendly greeting message"),
+  language: z.string().describe("The language of the greeting"),
+});
+
+const roles: WorkflowDefinition<GreetMeta>["roles"] = {
+  greeter: {
+    description: "Generates a friendly greeting",
+    systemPrompt:
+      "You are a friendly greeter. Given a user prompt, produce a warm greeting. Respond in valid JSON with keys: greeting (string), language (string).",
+    schema: greeterSchema,
+    extractRefs: null,
+  },
+};
+
+const table: ModeratorTable<GreetMeta> = {
+  [START]: [{ condition: "FALLBACK", role: "greeter" }],
+  greeter: [{ condition: "FALLBACK", role: END }],
+};
+
+export const descriptor = {
+  name: "greet",
+  description: "A simple greeting workflow for smoke testing",
+  graph: { [START]: ["greeter"], greeter: [END] },
+  roles: { greeter: { description: "Generates a friendly greeting" } },
+};
+
+function createLazyAdapter(): AdapterFn {
+  let cached: { baseUrl: string; apiKey: string; model: string } | null = null;
+  function getProvider() {
+    if (cached !== null) return cached;
+    const apiKey = process.env.DASHSCOPE_API_KEY;
+    if (!apiKey) throw new Error("missing env: DASHSCOPE_API_KEY");
+    cached = {
+      baseUrl: "https://dashscope.aliyuncs.com/compatible-mode/v1",
+      apiKey,
+      model: process.env.WORKFLOW_MODEL ?? "qwen-plus",
+    };
+    return cached;
+  }
+
+  return (<T>(prompt: string, schema: z.ZodType<T>): RoleFn<T> => {
+    return async (ctx: ThreadContext, _runtime: WorkflowRuntime): Promise<RoleResult<T>> => {
+      const provider = getProvider();
+      const response = await fetch(`${provider.baseUrl}/chat/completions`, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${provider.apiKey}`,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+          model: provider.model,
+          messages: [
+            { role: "system", content: prompt },
+            {
+              role: "user",
+              content: `${ctx.start.content}\n\nRespond with JSON: ${JSON.stringify(z.toJSONSchema(schema))}`,
+            },
+          ],
+          response_format: { type: "json_object" },
+        }),
+      });
+      if (!response.ok) {
+        const body = await response.text();
+        throw new Error(`LLM error ${response.status}: ${body.slice(0, 500)}`);
+      }
+      const data = (await response.json()) as { choices: Array<{ message: { content: string } }> };
+      const text = data.choices[0]?.message?.content;
+      if (!text) throw new Error("Empty LLM response");
+      const parsed = schema.parse(JSON.parse(text));
+      return { meta: parsed, childThread: null };
+    };
+  }) as AdapterFn;
+}
+
+export const run = createWorkflow<GreetMeta>(
+  { roles, table },
+  { adapter: createLazyAdapter(), overrides: null },
+);