refactor: cursor-agent uses runtime.extract for workspace detection

- Remove llmProvider and workspace from CursorAgentConfig (now just command/model/timeout) - extractWorkspacePath uses runtime.extract + runtime.cas instead of standalone reactor - TextProducerFn signature gains runtime parameter: (ctx, prompt, runtime) - develop-entry.ts hardcodes cursor-agent path, no more env var dependency - Drop @uncaged/workflow-reactor dep from workflow-agent-cursor - Update tests for simplified config 小橘 <xiaoju@shazhou.work>
2026-05-13 15:51:43 +00:00
48 changed files with 555 additions and 426 deletions
@@ -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"]
 }
@@ -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"]
  },
@@ -0,0 +1,15 @@
+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,
+});
+
+export const descriptor = buildDevelopDescriptor();
+export const run = createWorkflow(developWorkflowDefinition, { adapter: agent, overrides: null });
@@ -2,14 +2,14 @@ import { describe, expect, test } from "bun:test";

 import { createContentMerkleNode, serializeMerkleNode } from "@uncaged/workflow-cas";

-import { createApp } from "../src/commands/connect/app.js";
+import { createApp } from "../src/commands/serve/app.js";

 function casStoredForm(raw: string): string {
  return serializeMerkleNode(createContentMerkleNode(raw));
 }

 function buildApp(storageRoot: string) {
-  const app = createApp(storageRoot, null);
+  const app = createApp(storageRoot);
  return {
    fetch: (path: string, init?: RequestInit) =>
      app.fetch(new Request(`http://localhost${path}`, init)),
@@ -115,7 +115,7 @@ describe("serve error handling", () => {
  });

  test("global error handler returns 500 with JSON", async () => {
-    const app = createApp("/tmp/uncaged-serve-test-nonexistent", null);
+    const app = createApp("/tmp/uncaged-serve-test-nonexistent");
    app.get("/test-error", () => {
      throw new Error("boom");
    });
@@ -128,7 +128,7 @@ describe("serve error handling", () => {

 describe("serve security", () => {
  test("CORS headers present on responses", async () => {
-    const app = createApp("/tmp/uncaged-serve-test-nonexistent", null);
+    const app = createApp("/tmp/uncaged-serve-test-nonexistent");
    const res2 = await app.fetch(
      new Request("http://localhost/healthz", {
        headers: { Origin: "http://localhost:5173" },
@@ -4,7 +4,7 @@ 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 { dispatchServe } from "./commands/serve/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";
@@ -71,7 +71,7 @@ const COMMAND_TABLE: Record<string, DispatchFn> = {
  skill: dispatchSkill,
  run: dispatchRun,
  live: dispatchLive,
-  connect: dispatchConnect,
+  serve: dispatchServe,
 };

 export async function runCli(storageRoot: string, argv: string[]): Promise<number> {
@@ -59,12 +59,12 @@ export function formatCliUsage(
  );
  lines.push("");

-  lines.push("Gateway:");
+  lines.push("Server:");
  lines.push(
    ...formatUsageCommandLines([
      {
-        prefix: "connect [--name NAME] [--gateway URL]",
-        description: "Connect to workflow gateway via WebSocket",
+        prefix: "serve [--port N] [--host ADDR]",
+        description: "Start HTTP API server (default: 127.0.0.1:7860)",
      },
    ]),
  );
@@ -1,2 +0,0 @@
-export { dispatchConnect } from "./connect.js";
-export type { ConnectOptions } from "./types.js";
@@ -8,7 +8,7 @@ import { createWorkflowRoutes } from "./routes-workflow.js";

 const MAX_BODY_SIZE = 1_048_576; // 1 MB

-export function createApp(storageRoot: string, clientToken: string | null): Hono {
+export function createApp(storageRoot: string, agentToken: string | null): Hono {
  const app = new Hono();

  app.onError((_err, c) => {
@@ -37,11 +37,11 @@ export function createApp(storageRoot: string, clientToken: string | null): Hono
    await next();
  });

-  // ── Client token auth (skip healthz) ───────────────────────────────
-  if (clientToken !== null) {
+  // ── Agent token auth (skip healthz) ───────────────────────────────
+  if (agentToken !== null) {
    app.use("/api/*", async (c, next) => {
-      const token = c.req.header("X-Client-Token");
-      if (token !== clientToken) {
+      const token = c.req.header("X-Agent-Token");
+      if (token !== agentToken) {
        return c.json({ error: "unauthorized" }, 401);
      }
      await next();
@@ -5,13 +5,13 @@ export async function registerWithGateway(
  name: string,
  localUrl: string,
  secret: string,
-  clientToken: string,
+  agentToken: string,
 ): Promise<boolean> {
  try {
    const resp = await fetch(`${gatewayUrl}/api/gateway/register`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ name, url: localUrl, secret, clientToken }),
+      body: JSON.stringify({ name, url: localUrl, secret, agentToken }),
    });
    if (!resp.ok) {
      const body = await resp.text();
@@ -45,10 +45,10 @@ export function startHeartbeat(
  name: string,
  localUrl: string,
  secret: string,
-  clientToken: string,
+  agentToken: string,
  intervalMs: number,
 ): ReturnType<typeof setInterval> {
  return setInterval(() => {
-    registerWithGateway(gatewayUrl, name, localUrl, secret, clientToken).catch(() => {});
+    registerWithGateway(gatewayUrl, name, localUrl, secret, agentToken).catch(() => {});
  }, intervalMs);
 }
@@ -0,0 +1,3 @@
+export { createApp } from "./app.js";
+export { dispatchServe, startServer } from "./serve.js";
+export type { ServeOptions } from "./types.js";
@@ -1,30 +1,63 @@
 import { randomUUID } from "node:crypto";
 import { hostname as osHostname } from "node:os";
-import { ok, type Result } from "@uncaged/workflow-protocol";
+import { err, ok, type Result } from "@uncaged/workflow-protocol";
 import { createLogger } from "@uncaged/workflow-util";
+import { serve } from "bun";

 import { printCliLine } from "../../cli-output.js";
 import { createApp } from "./app.js";
 import { registerWithGateway, startHeartbeat, unregisterFromGateway } from "./gateway.js";
-import type { ConnectOptions } from "./types.js";
+import type { ServeOptions } from "./types.js";
 import { startGatewayWsClient } from "./ws-client.js";

 const DEFAULT_GATEWAY_URL = "https://workflow-gateway.shazhou.workers.dev";
 const HEARTBEAT_INTERVAL_MS = 60_000;

+export function startServer(
+  storageRoot: string,
+  options: ServeOptions,
+  agentToken: string | null,
+): void {
+  const app = createApp(storageRoot, agentToken);
+
+  const server = serve({
+    fetch: app.fetch,
+    port: options.port,
+    hostname: options.hostname,
+  });
+
+  printCliLine(`uncaged-workflow API server listening on http://${server.hostname}:${server.port}`);
+}
+
+function parsePortValue(value: string | undefined): Result<number, string> {
+  if (value === undefined) {
+    return err("--port requires a value");
+  }
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isFinite(parsed) || parsed < 0 || parsed > 65535) {
+    return err(`invalid port: ${value}`);
+  }
+  return ok(parsed);
+}
+
 function requireNextArg(argv: string[], i: number, flag: string): Result<string, string> {
  const next = argv[i + 1];
  if (next === undefined) {
-    return { ok: false, error: `${flag} requires a value` };
+    return err(`${flag} requires a value`);
  }
  return ok(next);
 }

-function parseConnectArgv(argv: string[]): Result<ConnectOptions, string> {
+function parseServeArgv(argv: string[]): Result<ServeOptions, string> {
+  let port = 7860;
+  let hostname = "127.0.0.1";
  let name = osHostname().split(".")[0].toLowerCase();
  let gatewayUrl = DEFAULT_GATEWAY_URL;
  const gatewaySecret = process.env.WORKFLOW_GATEWAY_SECRET ?? "";
  const stringFlags: Record<string, (v: string) => void> = {
+    "--host": (v) => {
+      hostname = v;
+    },
    "--name": (v) => {
      name = v;
    },
@@ -35,7 +68,12 @@ function parseConnectArgv(argv: string[]): Result<ConnectOptions, string> {

  for (let i = 0; i < argv.length; i++) {
    const arg = argv[i];
-    if (arg in stringFlags) {
+    if (arg === "--port" || arg === "-p") {
+      const portResult = parsePortValue(argv[i + 1]);
+      if (!portResult.ok) return portResult;
+      port = portResult.value;
+      i++;
+    } else if (arg in stringFlags) {
      const r = requireNextArg(argv, i, arg);
      if (!r.ok) return r;
      stringFlags[arg](r.value);
@@ -43,11 +81,11 @@ function parseConnectArgv(argv: string[]): Result<ConnectOptions, string> {
    }
  }

-  return ok({ name, gatewayUrl, gatewaySecret });
+  return ok({ port, hostname, name, gatewayUrl, gatewaySecret });
 }

-export async function dispatchConnect(storageRoot: string, argv: string[]): Promise<number> {
-  const parsed = parseConnectArgv(argv);
+export async function dispatchServe(storageRoot: string, argv: string[]): Promise<number> {
+  const parsed = parseServeArgv(argv);
  if (!parsed.ok) {
    printCliLine(`error: ${parsed.error}`);
    return 1;
@@ -56,31 +94,36 @@ export async function dispatchConnect(storageRoot: string, argv: string[]): Prom
  const options = parsed.value;

  if (options.gatewaySecret === "") {
-    printCliLine("error: WORKFLOW_GATEWAY_SECRET is required");
-    return 1;
+    // No gateway — local-only mode
+    startServer(storageRoot, options, null);
+    printCliLine("no WORKFLOW_GATEWAY_SECRET — running in local-only mode");
+    await new Promise(() => {});
+    return 0;
  }

-  const clientToken = randomUUID();
-  const app = createApp(storageRoot, clientToken);
+  const agentToken = randomUUID();
+  startServer(storageRoot, options, agentToken);

+  // Start WebSocket reverse connection to gateway
  const log = createLogger({ sink: { kind: "stderr" } });
  const stopWsClient = startGatewayWsClient({
    gatewayUrl: options.gatewayUrl,
    name: options.name,
    secret: options.gatewaySecret,
-    appFetch: app.fetch,
+    localPort: options.port,
    log,
  });

  printCliLine("connected to gateway via WebSocket");

  // Register with gateway for discovery
+  const localUrl = `http://127.0.0.1:${options.port}`;
  const registered = await registerWithGateway(
    options.gatewayUrl,
    options.name,
-    `ws://${options.name}`,
+    localUrl,
    options.gatewaySecret,
-    clientToken,
+    agentToken,
  );
  if (registered) {
    printCliLine(`registered with gateway as "${options.name}"`);
@@ -89,9 +132,9 @@ export async function dispatchConnect(storageRoot: string, argv: string[]): Prom
  const heartbeatTimer = startHeartbeat(
    options.gatewayUrl,
    options.name,
-    `ws://${options.name}`,
+    localUrl,
    options.gatewaySecret,
-    clientToken,
+    agentToken,
    HEARTBEAT_INTERVAL_MS,
  );

@@ -1,4 +1,6 @@
-export type ConnectOptions = {
+export type ServeOptions = {
+  port: number;
+  hostname: string;
  name: string;
  gatewayUrl: string;
  gatewaySecret: string;
@@ -5,7 +5,7 @@ export type GatewayWsClientParams = {
  gatewayUrl: string;
  name: string;
  secret: string;
-  appFetch: (request: Request) => Response | Promise<Response>;
+  localPort: number;
  log: LogFn;
 };

@@ -44,17 +44,20 @@ async function handleGatewayMessage(
    params.log("ZM8K2PQ1", "gateway WebSocket dropped non-request message");
    return;
  }
-  const localUrl = `http://localhost${req.path}`;
-  const headers = new Headers(req.headers);
+  const localUrl = `http://127.0.0.1:${String(params.localPort)}${req.path}`;
+  const initHeaders = new Headers();
+  for (const [k, v] of Object.entries(req.headers)) {
+    initHeaders.set(k, v);
+  }
  let resp: Response;
  try {
-    resp = await params.appFetch(new Request(localUrl, {
+    resp = await fetch(localUrl, {
      method: req.method,
-      headers,
+      headers: initHeaders,
      body: req.body === null ? undefined : req.body,
-    }));
+    });
  } catch (e) {
-    params.log("R4N7BQ3C", `app.fetch failed: ${String(e)}`);
+    params.log("R4N7BQ3C", `local proxy fetch failed: ${String(e)}`);
    const errBody: WsResponse = {
      id: req.id,
      status: 502,
@@ -86,11 +86,11 @@ ${commandSections.join("\n\n")}
 | \`run\` | \`thread run\` | Shortcut to start a thread |
 | \`live\` | \`thread live\` | Shortcut to attach to a thread |

-### connect
+### serve

 | Command | Args | Description |
 |---------|------|-------------|
-| \`connect\` | \`[--name NAME] [--gateway URL]\` | Connect to workflow gateway via WebSocket. \`--name\` registers with the gateway. |
+| \`serve\` | \`[--port N] [--host ADDR] [--name NAME]\` | Start HTTP API server with WebSocket gateway connection. \`--name\` registers with the gateway. |

 ## Typical Workflow

@@ -2,24 +2,11 @@ import { describe, expect, test } from "bun:test";
 import { createCursorAgent, validateCursorAgentConfig } from "../src/index.js";

 describe("validateCursorAgentConfig", () => {
-  test("accepts valid config with explicit workspace", () => {
+  test("accepts valid config", () => {
    const r = validateCursorAgentConfig({
      command: "/usr/local/bin/cursor-agent",
      model: null,
      timeout: 0,
-      workspace: "/tmp/test-project",
-      llmProvider: null,
-    });
-    expect(r.ok).toBe(true);
-  });
-
-  test("accepts valid config with null workspace and llmProvider", () => {
-    const r = validateCursorAgentConfig({
-      command: "/usr/local/bin/cursor-agent",
-      model: null,
-      timeout: 0,
-      workspace: null,
-      llmProvider: { baseUrl: "http://localhost", apiKey: "test", model: "test" },
    });
    expect(r.ok).toBe(true);
  });
@@ -29,8 +16,6 @@ describe("validateCursorAgentConfig", () => {
      command: "cursor-agent",
      model: null,
      timeout: 0,
-      workspace: "/tmp/test-project",
-      llmProvider: null,
    });
    expect(r.ok).toBe(false);
    if (!r.ok) {
@@ -38,65 +23,22 @@ describe("validateCursorAgentConfig", () => {
    }
  });

-  test("rejects empty workspace string", () => {
-    const r = validateCursorAgentConfig({
-      command: "/usr/local/bin/cursor-agent",
-      model: null,
-      timeout: 0,
-      workspace: "",
-      llmProvider: null,
-    });
-    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" },
    });
    expect(typeof agent).toBe("function");
  });
@@ -106,19 +48,6 @@ describe("createCursorAgent", () => {
      command: "/usr/local/bin/cursor-agent",
      model: null,
      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");
  });
@@ -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:^",
@@ -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;
@@ -1,4 +1,4 @@
-import type { AdapterFn } from "@uncaged/workflow-runtime";
+import type { WorkflowRuntime } from "@uncaged/workflow-runtime";
 import { createLogger } from "@uncaged/workflow-util";
 import {
  buildThreadInput,
@@ -33,34 +33,23 @@ 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 {
+/** 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) => {
+  return createTextAdapter(async (ctx, prompt, runtime: WorkflowRuntime) => {
    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;
+    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.",
+      );
    }

    logger("R5HN3YKQ", `cursor-agent workspace: ${workspace}`);
@@ -1,12 +1,6 @@
-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. */
-  workspace: string | null;
-  /** Required when `workspace` is `null` — LLM provider used for workspace extraction. */
-  llmProvider: LlmProvider | null;
 };
@@ -8,12 +8,6 @@ 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");
  }
@@ -33,7 +33,7 @@ function throwHermesSpawnError(error: SpawnCliError): never {
 export function createHermesAgent(config: HermesAgentConfig): AdapterFn {
  const timeoutMs = config.timeout;

-  return createTextAdapter(async (ctx, prompt) => {
+  return createTextAdapter(async (ctx, prompt, _runtime) => {
    const validated = validateHermesAgentConfig(config);
    if (!validated.ok) {
      throw new Error(validated.error);
@@ -93,7 +93,7 @@ export async function chatCompletionText(options: {

 /** Single-turn chat adapter: system prompt is passed by the workflow engine. */
 export function createLlmAdapter(provider: LlmProvider): AdapterFn {
-  return createTextAdapter(async (ctx, prompt) => {
+  return createTextAdapter(async (ctx, prompt, _runtime) => {
    const result = await chatCompletionText({
      provider,
      messages: [
@@ -26,11 +26,11 @@ function authHeaders(): Record<string, string> {
  return {};
 }

-function clientBase(client: string): string {
+function agentBase(agent: string): string {
  if (GATEWAY_URL) {
-    return `${GATEWAY_URL}/api/clients/${client}`;
+    return `${GATEWAY_URL}/api/agents/${agent}`;
  }
-  // Local dev: proxy via vite, no client prefix
+  // Local dev: proxy via vite, no agent prefix
  return "/api";
 }

@@ -57,7 +57,7 @@ async function fetchJson<T>(base: string, path: string): Promise<T> {

 // ── Endpoint types ──────────────────────────────────────────────────

-export type ClientEndpoint = {
+export type AgentEndpoint = {
  name: string;
  url: string;
  status: string;
@@ -141,61 +141,61 @@ export type WorkflowDetail = {

 // ── Gateway endpoints ───────────────────────────────────────────────

-export function listClients(): Promise<ClientEndpoint[]> {
+export function listAgents(): Promise<AgentEndpoint[]> {
  const url = GATEWAY_URL || "";
  return fetchJson(url, "/api/gateway/endpoints");
 }

-// ── Client-scoped endpoints ──────────────────────────────────────────
+// ── Agent-scoped endpoints ──────────────────────────────────────────

-export function listWorkflows(client: string): Promise<{ workflows: WorkflowSummary[] }> {
-  return fetchJson(clientBase(client), "/workflows");
+export function listWorkflows(agent: string): Promise<{ workflows: WorkflowSummary[] }> {
+  return fetchJson(agentBase(agent), "/workflows");
 }

-export async function getWorkflowDetail(client: string, name: string): Promise<WorkflowDetail> {
-  return fetchJson<WorkflowDetail>(clientBase(client), `/workflows/${encodeURIComponent(name)}`);
+export async function getWorkflowDetail(agent: string, name: string): Promise<WorkflowDetail> {
+  return fetchJson<WorkflowDetail>(agentBase(agent), `/workflows/${encodeURIComponent(name)}`);
 }

 export async function getWorkflowDescriptor(
-  client: string,
+  agent: string,
  name: string,
 ): Promise<WorkflowDescriptor | null> {
-  const res = await getWorkflowDetail(client, name);
+  const res = await getWorkflowDetail(agent, name);
  return res.descriptor;
 }

-export function listThreads(client: string): Promise<{ threads: ThreadSummary[] }> {
-  return fetchJson(clientBase(client), "/threads");
+export function listThreads(agent: string): Promise<{ threads: ThreadSummary[] }> {
+  return fetchJson(agentBase(agent), "/threads");
 }

-export function listRunningThreads(client: string): Promise<{ threads: ThreadSummary[] }> {
-  return fetchJson(clientBase(client), "/threads/running");
+export function listRunningThreads(agent: string): Promise<{ threads: ThreadSummary[] }> {
+  return fetchJson(agentBase(agent), "/threads/running");
 }

-export function getThread(client: string, id: string): Promise<{ records: ThreadRecord[] }> {
-  return fetchJson(clientBase(client), `/threads/${id}`);
+export function getThread(agent: string, id: string): Promise<{ records: ThreadRecord[] }> {
+  return fetchJson(agentBase(agent), `/threads/${id}`);
 }

 export function runThread(
-  client: string,
+  agent: string,
  workflow: string,
  prompt: string,
 ): Promise<{ threadId: string }> {
-  return postJson(clientBase(client), "/threads", { workflow, prompt });
+  return postJson(agentBase(agent), "/threads", { workflow, prompt });
 }

-export function killThread(client: string, threadId: string): Promise<{ ok: boolean }> {
-  return postJson(clientBase(client), `/threads/${threadId}/kill`, {});
+export function killThread(agent: string, threadId: string): Promise<{ ok: boolean }> {
+  return postJson(agentBase(agent), `/threads/${threadId}/kill`, {});
 }

-export function pauseThread(client: string, threadId: string): Promise<{ ok: boolean }> {
-  return postJson(clientBase(client), `/threads/${threadId}/pause`, {});
+export function pauseThread(agent: string, threadId: string): Promise<{ ok: boolean }> {
+  return postJson(agentBase(agent), `/threads/${threadId}/pause`, {});
 }

-export function resumeThread(client: string, threadId: string): Promise<{ ok: boolean }> {
-  return postJson(clientBase(client), `/threads/${threadId}/resume`, {});
+export function resumeThread(agent: string, threadId: string): Promise<{ ok: boolean }> {
+  return postJson(agentBase(agent), `/threads/${threadId}/resume`, {});
 }

-export function getClientHealth(client: string): Promise<{ ok: boolean }> {
-  return fetchJson(clientBase(client), "/healthz");
+export function getAgentHealth(agent: string): Promise<{ ok: boolean }> {
+  return fetchJson(agentBase(agent), "/healthz");
 }
@@ -11,7 +11,7 @@ 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, agent, threadId, setView, setAgent, setThreadId } = useHashRoute();
  const [showRun, setShowRun] = useState(false);

  if (!authed) {
@@ -22,36 +22,36 @@ export function App() {
    <div className="flex h-screen">
      <Sidebar
        view={view}
-        client={client}
+        agent={agent}
        onViewChange={setView}
-        onClientChange={setClient}
+        onAgentChange={setAgent}
        onLogout={() => {
          clearApiKey();
          setAuthed(false);
        }}
      />
      <main className="flex-1 overflow-hidden flex flex-col">
-        <StatusBar client={client} onRun={() => setShowRun(true)} />
+        <StatusBar agent={agent} onRun={() => setShowRun(true)} />
        <div className="flex-1 overflow-auto p-6">
-          {!client && (
+          {!agent && (
            <div className="flex items-center justify-center h-full">
              <p style={{ color: "var(--color-text-muted)" }}>
-                Select an client from the sidebar to get started.
+                Select an agent from the sidebar to get started.
              </p>
            </div>
          )}
-          {client && view === "threads" && threadId === null && (
-            <ThreadList client={client} onSelect={setThreadId} />
+          {agent && view === "threads" && threadId === null && (
+            <ThreadList agent={agent} onSelect={setThreadId} />
          )}
-          {client && view === "threads" && threadId !== null && (
-            <ThreadDetail client={client} threadId={threadId} onBack={() => setThreadId(null)} />
+          {agent && view === "threads" && threadId !== null && (
+            <ThreadDetail agent={agent} threadId={threadId} onBack={() => setThreadId(null)} />
          )}
-          {client && view === "workflows" && <WorkflowList client={client} />}
+          {agent && view === "workflows" && <WorkflowList agent={agent} />}
        </div>
      </main>
-      {showRun && client && (
+      {showRun && agent && (
        <RunDialog
-          client={client}
+          agent={agent}
          onClose={() => setShowRun(false)}
          onCreated={(id) => {
            setShowRun(false);
@@ -3,7 +3,7 @@ import { Markdown } from "./markdown.tsx";

 const ROLE_COLORS: Record<string, string> = {
  preparer: "#8b5cf6",
-  client: "#3b82f6",
+  agent: "#3b82f6",
  extractor: "#f59e0b",
 };

@@ -3,13 +3,13 @@ import { listWorkflows, runThread } from "../api.ts";
 import { useFetch } from "../hooks.ts";

 type Props = {
-  client: string;
+  agent: string;
  onClose: () => void;
  onCreated: (threadId: string) => void;
 };

-export function RunDialog({ client, onClose, onCreated }: Props) {
-  const workflows = useFetch(() => listWorkflows(client), [client]);
+export function RunDialog({ agent, onClose, onCreated }: Props) {
+  const workflows = useFetch(() => listWorkflows(agent), [agent]);
  const [workflow, setWorkflow] = useState("");
  const [prompt, setPrompt] = useState("");
  const [submitting, setSubmitting] = useState(false);
@@ -21,7 +21,7 @@ export function RunDialog({ client, onClose, onCreated }: Props) {
    setSubmitting(true);
    setError(null);
    try {
-      const result = await runThread(client, workflow, prompt);
+      const result = await runThread(agent, workflow, prompt);
      onCreated(result.threadId);
    } catch (err) {
      setError(err instanceof Error ? err.message : String(err));
@@ -38,7 +38,7 @@ export function RunDialog({ client, onClose, onCreated }: Props) {
        className="w-full max-w-lg p-6 rounded-lg border"
        style={{ background: "var(--color-surface)", borderColor: "var(--color-border)" }}
      >
-        <h3 className="text-lg font-semibold mb-4">Run Thread on {client}</h3>
+        <h3 className="text-lg font-semibold mb-4">Run Thread on {agent}</h3>
        <form onSubmit={handleSubmit} className="space-y-4">
          <div>
            <label
@@ -1,27 +1,27 @@
 import { useEffect } from "react";
-import type { ClientEndpoint } from "../api.ts";
-import { listClients } from "../api.ts";
+import type { AgentEndpoint } from "../api.ts";
+import { listAgents } from "../api.ts";
 import { useFetch } from "../hooks.ts";

 type Props = {
  view: "threads" | "workflows";
-  client: string | null;
+  agent: string | null;
  onViewChange: (v: "threads" | "workflows") => void;
-  onClientChange: (a: string | null) => void;
+  onAgentChange: (a: string | null) => void;
  onLogout: () => void;
 };

-export function Sidebar({ view, client, onViewChange, onClientChange, onLogout }: Props) {
-  const { status, data } = useFetch(() => listClients(), []);
+export function Sidebar({ view, agent, onViewChange, onAgentChange, onLogout }: Props) {
+  const { status, data } = useFetch(() => listAgents(), []);

-  const clients: ClientEndpoint[] = status === "ok" ? data : [];
+  const agents: AgentEndpoint[] = status === "ok" ? data : [];

-  // Auto-select first client when none is selected
+  // Auto-select first agent when none is selected
  useEffect(() => {
-    if (client === null && clients.length > 0) {
-      onClientChange(clients[0].name);
+    if (agent === null && agents.length > 0) {
+      onAgentChange(agents[0].name);
    }
-  }, [client, clients, onClientChange]);
+  }, [agent, agents, onAgentChange]);

  const viewItems = [
    { key: "threads" as const, label: "Threads", icon: "⚡" },
@@ -42,33 +42,33 @@ export function Sidebar({ view, client, onViewChange, onClientChange, onLogout }
        </p>
      </div>

-      {/* Client selector */}
+      {/* Agent selector */}
      <div className="px-4 py-3 border-b" style={{ borderColor: "var(--color-border)" }}>
        <label
          className="block text-xs font-medium mb-1"
          style={{ color: "var(--color-text-muted)" }}
-          htmlFor="client-select"
+          htmlFor="agent-select"
        >
-          Client
+          Agent
        </label>
        <select
-          id="client-select"
+          id="agent-select"
          className="w-full rounded px-2 py-1.5 text-xs"
          style={{
            background: "var(--color-bg)",
            color: "var(--color-text)",
            border: "1px solid var(--color-border)",
          }}
-          value={client ?? ""}
-          onChange={(e) => onClientChange(e.target.value || null)}
+          value={agent ?? ""}
+          onChange={(e) => onAgentChange(e.target.value || null)}
          disabled={status === "loading"}
        >
          {status === "loading" ? (
            <option value="">Loading…</option>
-          ) : clients.length === 0 ? (
-            <option value="">No clients online</option>
+          ) : agents.length === 0 ? (
+            <option value="">No agents online</option>
          ) : (
-            clients.map((a) => (
+            agents.map((a) => (
              <option key={a.name} value={a.name}>
                {a.status === "online" ? "🟢" : "🔴"} {a.name}
              </option>
@@ -1,10 +1,10 @@
 import { useCallback, useEffect, useRef, useState } from "react";
-import { getClientHealth } from "../api.ts";
+import { getAgentHealth } from "../api.ts";

 type HealthStatus = "connected" | "disconnected" | "reconnecting";

 type Props = {
-  client: string | null;
+  agent: string | null;
  onRun: () => void;
 };

@@ -18,17 +18,17 @@ function statusLabel(status: HealthStatus): { text: string; color: string } {
  return { text: "● Offline", color: "var(--color-error)" };
 }

-export function StatusBar({ client, onRun }: Props) {
+export function StatusBar({ agent, onRun }: Props) {
  const [status, setStatus] = useState<HealthStatus>("disconnected");
  const wasConnectedRef = useRef(false);

  const checkHealth = useCallback(async () => {
-    if (!client) {
+    if (!agent) {
      setStatus("disconnected");
      return;
    }
    try {
-      await getClientHealth(client);
+      await getAgentHealth(agent);
      wasConnectedRef.current = true;
      setStatus("connected");
    } catch {
@@ -38,7 +38,7 @@ export function StatusBar({ client, onRun }: Props) {
        setStatus("disconnected");
      }
    }
-  }, [client]);
+  }, [agent]);

  useEffect(() => {
    wasConnectedRef.current = false;
@@ -57,17 +57,17 @@ export function StatusBar({ client, onRun }: Props) {
    >
      <div className="flex items-center gap-4">
        <span style={{ color: "var(--color-text-muted)" }}>
-          {client ? `Client: ${client}` : "No client selected"}
+          {agent ? `Agent: ${agent}` : "No agent selected"}
        </span>
        <button
          type="button"
          onClick={onRun}
-          disabled={!client}
+          disabled={!agent}
          className="px-3 py-1 rounded text-xs font-medium"
          style={{
-            background: client ? "var(--color-accent)" : "var(--color-border)",
+            background: agent ? "var(--color-accent)" : "var(--color-border)",
            color: "#fff",
-            opacity: client ? 1 : 0.5,
+            opacity: agent ? 1 : 0.5,
          }}
        >
          ▶ Run Thread
@@ -14,7 +14,7 @@ import { RecordCard } from "./record-card.tsx";
 import { type NodeState, WorkflowGraph } from "./workflow-graph/index.ts";

 type Props = {
-  client: string;
+  agent: string;
  threadId: string;
  onBack: () => void;
 };
@@ -52,9 +52,9 @@ function computeNodeStates(records: readonly ThreadRecord[]): Map<string, NodeSt
  return states;
 }

-export function ThreadDetail({ client, threadId, onBack }: Props) {
-  const sse = useSSE(client, threadId);
-  const { status, data, error } = useFetch(() => getThread(client, threadId), [client, threadId]);
+export function ThreadDetail({ agent, threadId, onBack }: Props) {
+  const sse = useSSE(agent, threadId);
+  const { status, data, error } = useFetch(() => getThread(agent, threadId), [agent, threadId]);
  const [actionStatus, setActionStatus] = useState<string | null>(null);
  const recordsEndRef = useRef<HTMLDivElement>(null);
  const firstCardByRoleRef = useRef<Map<string, HTMLDivElement>>(new Map());
@@ -72,8 +72,8 @@ export function ThreadDetail({ client, threadId, onBack }: Props) {

  const descriptorFetch = useFetch<WorkflowDescriptor | null>(
    () =>
-      workflowName === null ? Promise.resolve(null) : getWorkflowDescriptor(client, workflowName),
-    [client, workflowName],
+      workflowName === null ? Promise.resolve(null) : getWorkflowDescriptor(agent, workflowName),
+    [agent, workflowName],
  );

  const descriptor = descriptorFetch.status === "ok" ? descriptorFetch.data : null;
@@ -117,7 +117,7 @@ export function ThreadDetail({ client, threadId, onBack }: Props) {
    setActionStatus(`${action}ing...`);
    try {
      const fn = action === "kill" ? killThread : action === "pause" ? pauseThread : resumeThread;
-      await fn(client, threadId);
+      await fn(agent, threadId);
      setActionStatus(`${action} sent ✓`);
    } catch (e) {
      setActionStatus(`${action} failed: ${e instanceof Error ? e.message : String(e)}`);
@@ -2,12 +2,12 @@ import { listThreads } from "../api.ts";
 import { useFetch } from "../hooks.ts";

 type Props = {
-  client: string;
+  agent: string;
  onSelect: (id: string) => void;
 };

-export function ThreadList({ client, onSelect }: Props) {
-  const { status, data, error } = useFetch(() => listThreads(client), [client]);
+export function ThreadList({ agent, onSelect }: Props) {
+  const { status, data, error } = useFetch(() => listThreads(agent), [agent]);

  if (status === "loading")
    return <p style={{ color: "var(--color-text-muted)" }}>Loading threads...</p>;
@@ -7,23 +7,25 @@ const FEEDBACK_OFFSET_X = 100;
 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
+ * Build an SVG path for a feedback (back) edge that routes to the right of the nodes.
+ * The path goes: source right → arc → vertical up → arc → target right
 */
-function feedbackPath(sourceX: number, sourceY: number, targetX: number, targetY: number, side: "right" | "left"): string {
-  const d = side === "right" ? 1 : -1;
-  const offsetX =
-    side === "right"
-      ? Math.max(sourceX, targetX) + FEEDBACK_OFFSET_X
-      : Math.min(sourceX, targetX) - FEEDBACK_OFFSET_X;
+function feedbackPath(sourceX: number, sourceY: number, targetX: number, targetY: number): string {
+  const rightX = Math.max(sourceX, targetX) + FEEDBACK_OFFSET_X;
  const r = FEEDBACK_RADIUS;

+  // Start from source right side, go right, then up, then left to target right side
  const segments = [
    `M ${sourceX} ${sourceY}`,
-    `L ${offsetX - d * r} ${sourceY}`,
-    `Q ${offsetX} ${sourceY} ${offsetX} ${sourceY - r}`,
-    `L ${offsetX} ${targetY + r}`,
-    `Q ${offsetX} ${targetY} ${offsetX - d * r} ${targetY}`,
+    // Horizontal to the right
+    `L ${rightX - r} ${sourceY}`,
+    // Arc turning upward
+    `Q ${rightX} ${sourceY} ${rightX} ${sourceY - r}`,
+    // Vertical upward
+    `L ${rightX} ${targetY + r}`,
+    // Arc turning left
+    `Q ${rightX} ${targetY} ${rightX - r} ${targetY}`,
+    // Horizontal left to target
    `L ${targetX} ${targetY}`,
  ];

@@ -55,13 +57,10 @@ export function ConditionEdge(props: EdgeProps) {
  let defaultLabelY: number;

  if (isFeedback) {
-    const side = edgeData?.feedbackSide ?? "right";
-    path = feedbackPath(sourceX, sourceY, targetX, targetY, side);
-    const offsetX =
-      side === "right"
-        ? Math.max(sourceX, targetX) + FEEDBACK_OFFSET_X
-        : Math.min(sourceX, targetX) - FEEDBACK_OFFSET_X;
-    defaultLabelX = offsetX;
+    // Custom feedback path routed to the right
+    path = feedbackPath(sourceX, sourceY, targetX, targetY);
+    const rightX = Math.max(sourceX, targetX) + FEEDBACK_OFFSET_X;
+    defaultLabelX = rightX;
    defaultLabelY = (sourceY + targetY) / 2;
  } else {
    const result = getSmoothStepPath({
@@ -79,8 +78,9 @@ export function ConditionEdge(props: EdgeProps) {
    defaultLabelY = result[2];
  }

-  const stroke = "var(--color-accent)";
-  const label = isFallback ? "" : (edgeData?.condition ?? "");
+  const stroke = isFallback ? "var(--color-text-muted)" : "var(--color-accent)";
+  const strokeDasharray = isFallback ? "5 4" : undefined;
+  const label = edgeData?.condition ?? "";

  // Use pre-computed label position if available, otherwise fall back to default
  const labelX = edgeData?.labelX ?? defaultLabelX;
@@ -92,7 +92,7 @@ export function ConditionEdge(props: EdgeProps) {
        id={id}
        path={path}
        markerEnd={markerEnd}
-        style={{ stroke, strokeWidth: 1.5 }}
+        style={{ stroke, strokeWidth: 1.5, strokeDasharray }}
      />
      {label !== "" && (
        <EdgeLabelRenderer>
@@ -102,7 +102,7 @@ export function ConditionEdge(props: EdgeProps) {
              transform: `translate(-50%, -50%) translate(${labelX}px, ${labelY}px)`,
              background: "var(--color-surface)",
              border: "1px solid var(--color-border)",
-              color: "var(--color-text)",
+              color: isFallback ? "var(--color-text-muted)" : "var(--color-text)",
              whiteSpace: "nowrap",
              zIndex: 10,
            }}
@@ -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 cursor-pointer ${isActive ? "wf-node-pulse" : ""}`}
      style={{
        width: 180,
        height: 60,
@@ -23,7 +23,6 @@ export type ConditionEdgeData = {
  isFallback: boolean;
  isFeedback: boolean;
  isSelfLoop: boolean;
-  feedbackSide: "right" | "left" | null;
  labelX: number | null;
  labelY: number | null;
  [key: string]: unknown;
@@ -173,8 +173,6 @@ function computeLayout(input: LayoutInput): LayoutResult {
  // Build edges with label positions
  // For feedback edges (target rank < source rank), we'll compute label at midpoint
  // of the right-side arc. The actual SVG path is drawn by ConditionEdge component.
-  // Track feedback edge count per target node for alternating sides
-  const feedbackCountByTarget = new Map<string, number>();
  const edges: Edge[] = input.edges.map((e) => {
    const isFallback = e.condition === "FALLBACK";
    const isSelfLoop = e.from === e.to;
@@ -187,20 +185,13 @@ function computeLayout(input: LayoutInput): LayoutResult {

    let labelX: number | null = null;
    let labelY: number | null = null;
-    let feedbackSide: "right" | "left" | null = null;

    if (sourcePos !== undefined && targetPos !== undefined) {
      if (isFeedback) {
-        // Alternate feedback edges left/right per target node
-        const count = feedbackCountByTarget.get(e.to) ?? 0;
-        feedbackCountByTarget.set(e.to, count + 1);
-        feedbackSide = count % 2 === 0 ? "right" : "left";
-        const offsetX =
-          feedbackSide === "right"
-            ? centerX + ROLE_NODE_WIDTH / 2 + FEEDBACK_OFFSET_X
-            : centerX - ROLE_NODE_WIDTH / 2 - FEEDBACK_OFFSET_X;
+        // Label on the right side of the feedback arc
+        const rightX = centerX + ROLE_NODE_WIDTH / 2 + FEEDBACK_OFFSET_X;
        const midY = (sourcePos.y + sourcePos.h / 2 + targetPos.y + targetPos.h / 2) / 2;
-        labelX = offsetX;
+        labelX = rightX;
        labelY = midY;
      } else if (!isSelfLoop) {
        // Forward edge: label between source bottom and target top
@@ -223,7 +214,6 @@ function computeLayout(input: LayoutInput): LayoutResult {
        isFallback,
        isFeedback,
        isSelfLoop,
-        feedbackSide,
        labelX,
        labelY,
      },
@@ -5,7 +5,7 @@ import { useFetch } from "../hooks.ts";
 import { type NodeState, WorkflowGraph } from "./workflow-graph/index.ts";

 type Props = {
-  client: string;
+  agent: string;
 };

 type DetailCacheEntry =
@@ -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"
@@ -108,8 +109,8 @@ function ExpandedWorkflowBody({
  );
 }

-export function WorkflowList({ client }: Props) {
-  const { status, data, error } = useFetch(() => listWorkflows(client), [client]);
+export function WorkflowList({ agent }: Props) {
+  const { status, data, error } = useFetch(() => listWorkflows(agent), [agent]);
  const [expanded, setExpanded] = useState<Set<string>>(() => new Set());
  const [detailsByName, setDetailsByName] = useState<Map<string, DetailCacheEntry>>(
    () => new Map(),
@@ -117,11 +118,11 @@ export function WorkflowList({ client }: Props) {

  const staticNodeStates = useMemo(() => new Map<string, NodeState>(), []);

-  // biome-ignore lint/correctness/useExhaustiveDependencies: reset expansion when switching clients
+  // biome-ignore lint/correctness/useExhaustiveDependencies: reset expansion when switching agents
  useEffect(() => {
    setExpanded(new Set());
    setDetailsByName(new Map());
-  }, [client]);
+  }, [agent]);

  const ensureDetailLoaded = useCallback(
    (name: string) => {
@@ -135,7 +136,7 @@ export function WorkflowList({ client }: Props) {

      void (async () => {
        try {
-          const detail = await getWorkflowDetail(client, name);
+          const detail = await getWorkflowDetail(agent, name);
          setDetailsByName((prev) => {
            const next = new Map(prev);
            next.set(name, { status: "ok", detail });
@@ -151,7 +152,7 @@ export function WorkflowList({ client }: Props) {
        }
      })();
    },
-    [client],
+    [agent],
  );

  function toggleExpanded(name: string) {
@@ -4,35 +4,35 @@ type View = "threads" | "workflows";

 type HashRoute = {
  view: View;
-  client: string | null;
+  agent: string | null;
  threadId: string | null;
 };

 function parseHash(hash: string): HashRoute {
  const raw = hash.replace(/^#\/?/, "");
-  // Format: #client/threads/id or #client/workflows or #threads or #workflows
+  // Format: #agent/threads/id or #agent/workflows or #threads or #workflows
  const parts = raw.split("/");

  // Check if first part is a known view
  if (parts[0] === "threads" || parts[0] === "workflows") {
    return {
      view: parts[0] as View,
-      client: null,
+      agent: null,
      threadId: parts[0] === "threads" && parts.length > 1 ? parts.slice(1).join("/") : null,
    };
  }

-  // First part is client name
-  const client = parts[0] || null;
+  // First part is agent name
+  const agent = parts[0] || null;
  const viewPart = parts[1] ?? "threads";
  const view: View = viewPart === "workflows" ? "workflows" : "threads";
  const threadId = view === "threads" && parts.length > 2 ? parts.slice(2).join("/") : null;

-  return { view, client, threadId };
+  return { view, agent, threadId };
 }

 function buildHash(route: HashRoute): string {
-  const prefix = route.client ? `${route.client}/` : "";
+  const prefix = route.agent ? `${route.agent}/` : "";
  if (route.view === "workflows") {
    return `#${prefix}workflows`;
  }
@@ -44,10 +44,10 @@ function buildHash(route: HashRoute): string {

 export function useHashRoute(): {
  view: View;
-  client: string | null;
+  agent: string | null;
  threadId: string | null;
  setView: (v: View) => void;
-  setClient: (a: string | null) => void;
+  setAgent: (a: string | null) => void;
  setThreadId: (id: string | null) => void;
 } {
  const [route, setRoute] = useState<HashRoute>(() => parseHash(window.location.hash));
@@ -67,26 +67,26 @@ export function useHashRoute(): {
  }, []);

  const setView = useCallback(
-    (v: View) => navigate({ view: v, client: route.client, threadId: null }),
-    [navigate, route.client],
+    (v: View) => navigate({ view: v, agent: route.agent, threadId: null }),
+    [navigate, route.agent],
  );

-  const setClient = useCallback(
-    (a: string | null) => navigate({ view: route.view, client: a, threadId: null }),
+  const setAgent = useCallback(
+    (a: string | null) => navigate({ view: route.view, agent: a, threadId: null }),
    [navigate, route.view],
  );

  const setThreadId = useCallback(
-    (id: string | null) => navigate({ view: "threads", client: route.client, threadId: id }),
-    [navigate, route.client],
+    (id: string | null) => navigate({ view: "threads", agent: route.agent, threadId: id }),
+    [navigate, route.agent],
  );

  return {
    view: route.view,
-    client: route.client,
+    agent: route.agent,
    threadId: route.threadId,
    setView,
-    setClient,
+    setAgent,
    setThreadId,
  };
 }
@@ -57,17 +57,17 @@ function handleRecordEvent(ev: Event, ctx: RecordEventContext): void {
  ctx.cleanupEs();
 }

-function sseUrl(client: string, threadId: string): string {
+function sseUrl(agent: string, threadId: string): string {
  const gatewayUrl = import.meta.env.VITE_GATEWAY_URL || "";
  const key = getApiKey();
  const keyParam = key ? `?key=${encodeURIComponent(key)}` : "";
  if (gatewayUrl) {
-    return `${gatewayUrl}/api/${client}/threads/${encodeURIComponent(threadId)}/live${keyParam}`;
+    return `${gatewayUrl}/api/${agent}/threads/${encodeURIComponent(threadId)}/live${keyParam}`;
  }
  return `/api/threads/${encodeURIComponent(threadId)}/live`;
 }

-export function useSSE(client: string | null, threadId: string | null): UseSSEReturn {
+export function useSSE(agent: string | null, threadId: string | null): UseSSEReturn {
  const [records, setRecords] = useState<ThreadRecord[]>([]);
  const [connected, setConnected] = useState(false);
  const [completed, setCompleted] = useState(false);
@@ -76,7 +76,7 @@ export function useSSE(client: string | null, threadId: string | null): UseSSERe
  const reconnectAttemptsRef = useRef(0);

  useEffect(() => {
-    if (threadId === null || client === null) {
+    if (threadId === null || agent === null) {
      completedRef.current = false;
      reconnectAttemptsRef.current = 0;
      setRecords([]);
@@ -86,7 +86,7 @@ export function useSSE(client: string | null, threadId: string | null): UseSSERe
    }

    const tid = threadId;
-    const clientName = client;
+    const agentName = agent;

    completedRef.current = false;
    reconnectAttemptsRef.current = 0;
@@ -125,7 +125,7 @@ export function useSSE(client: string | null, threadId: string | null): UseSSERe
      }

      cleanupEs();
-      const url = sseUrl(clientName, tid);
+      const url = sseUrl(agentName, tid);
      es = new EventSource(url);

      es.onopen = () => {
@@ -177,7 +177,7 @@ export function useSSE(client: string | null, threadId: string | null): UseSSERe
      }
      cleanupEs();
    };
-  }, [client, threadId]);
+  }, [agent, threadId]);

  return { records, connected, completed };
 }
@@ -1,14 +1,14 @@
-/** One Durable Object instance per client name; holds the reverse WebSocket from the client CLI. */
+/** One Durable Object instance per agent name; holds the reverse WebSocket from the agent CLI. */
 import { DurableObject } from "cloudflare:workers";

 import { parseWsRequestJson, parseWsResponseJson, type WsResponse } from "./ws-protocol.js";

-type ClientSocketEnv = {
+type AgentSocketEnv = {
  GATEWAY_SECRET: string;
 };

-export const CLIENT_SOCKET_INTERNAL_STATUS_PATH = "/internal/client-socket/status";
-export const CLIENT_SOCKET_INTERNAL_PROXY_PATH = "/internal/client-socket/proxy";
+export const AGENT_SOCKET_INTERNAL_STATUS_PATH = "/internal/agent-socket/status";
+export const AGENT_SOCKET_INTERNAL_PROXY_PATH = "/internal/agent-socket/proxy";

 const PROXY_TIMEOUT_MS = 30_000;

@@ -32,7 +32,7 @@ function wsResponseToHttp(wr: WsResponse): Response {
  return new Response(wr.body, { status: wr.status, headers });
 }

-export class ClientSocket extends DurableObject<ClientSocketEnv> {
+export class AgentSocket extends DurableObject<AgentSocketEnv> {
  private readonly pending = new Map<string, PendingEntry>();

  private requireAuth(request: Request): Response | null {
@@ -100,11 +100,11 @@ export class ClientSocket extends DurableObject<ClientSocketEnv> {
  async fetch(request: Request): Promise<Response> {
    const url = new URL(request.url);

-    if (url.pathname === CLIENT_SOCKET_INTERNAL_STATUS_PATH && request.method === "GET") {
+    if (url.pathname === AGENT_SOCKET_INTERNAL_STATUS_PATH && request.method === "GET") {
      return this.handleStatusGet(request);
    }

-    if (url.pathname === CLIENT_SOCKET_INTERNAL_PROXY_PATH && request.method === "POST") {
+    if (url.pathname === AGENT_SOCKET_INTERNAL_PROXY_PATH && request.method === "POST") {
      return this.handleProxyPost(request);
    }

@@ -144,11 +144,11 @@ export class ClientSocket extends DurableObject<ClientSocketEnv> {
    _reason: string,
    _wasClean: boolean,
  ): Promise<void> {
-    this.rejectAllPending("client websocket closed");
+    this.rejectAllPending("agent websocket closed");
  }

  async webSocketError(_ws: WebSocket, _error: unknown): Promise<void> {
-    this.rejectAllPending("client websocket error");
+    this.rejectAllPending("agent websocket error");
  }

  private rejectAllPending(message: string): void {
@@ -2,27 +2,27 @@ import { Hono } from "hono";
 import { cors } from "hono/cors";

 import {
-  CLIENT_SOCKET_INTERNAL_PROXY_PATH,
-  CLIENT_SOCKET_INTERNAL_STATUS_PATH,
-  ClientSocket,
-} from "./client-socket.js";
+  AGENT_SOCKET_INTERNAL_PROXY_PATH,
+  AGENT_SOCKET_INTERNAL_STATUS_PATH,
+  AgentSocket,
+} from "./agent-socket.js";
 import type { WsRequest } from "./ws-protocol.js";

-export { ClientSocket };
+export { AgentSocket };

 type Env = {
  Bindings: {
    ENDPOINTS: KVNamespace;
    GATEWAY_SECRET: string;
    DASHBOARD_API_KEY: string;
-    CLIENT_SOCKET: DurableObjectNamespace<ClientSocket>;
+    AGENT_SOCKET: DurableObjectNamespace<AgentSocket>;
  };
 };

 type EndpointRecord = {
  name: string;
  url: string;
-  clientToken: string;
+  agentToken: string;
  registeredAt: number;
  lastHeartbeat: number;
 };
@@ -43,7 +43,7 @@ function checkDashboardAuth(c: {
  return key === c.env.DASHBOARD_API_KEY;
 }

-function isLocalClientUrl(url: string): boolean {
+function isLocalAgentUrl(url: string): boolean {
  try {
    const u = new URL(url);
    return u.hostname === "localhost" || u.hostname === "127.0.0.1";
@@ -52,7 +52,7 @@ function isLocalClientUrl(url: string): boolean {
  }
 }

-function buildForwardHeaders(raw: Headers, clientToken: string): Record<string, string> {
+function buildForwardHeaders(raw: Headers, agentToken: string): Record<string, string> {
  const out: Record<string, string> = {};
  for (const [key, value] of raw) {
    const lower = key.toLowerCase();
@@ -70,8 +70,8 @@ function buildForwardHeaders(raw: Headers, clientToken: string): Record<string,
    }
    out[key] = value;
  }
-  if (clientToken !== "") {
-    out["X-Client-Token"] = clientToken;
+  if (agentToken !== "") {
+    out["X-Agent-Token"] = agentToken;
  }
  return out;
 }
@@ -81,7 +81,7 @@ function buildDashboardProxyHeaders(raw: Headers, token: string): Headers {
  headers.delete("host");
  headers.delete("Authorization");
  if (token !== "") {
-    headers.set("X-Client-Token", token);
+    headers.set("X-Agent-Token", token);
  }
  return headers;
 }
@@ -94,15 +94,15 @@ async function readBodyForWsProxy(method: string, req: Request): Promise<string
  return buf.byteLength === 0 ? null : new TextDecoder().decode(buf);
 }

-async function fetchThroughClientSocket(
+async function fetchThroughAgentSocket(
  bindings: Env["Bindings"],
-  client: string,
+  agent: string,
  gateSecret: string,
  wsRequest: WsRequest,
 ): Promise<Response> {
-  const stub = bindings.CLIENT_SOCKET.get(bindings.CLIENT_SOCKET.idFromName(client));
+  const stub = bindings.AGENT_SOCKET.get(bindings.AGENT_SOCKET.idFromName(agent));
  return stub.fetch(
-    new Request(`https://do.internal${CLIENT_SOCKET_INTERNAL_PROXY_PATH}`, {
+    new Request(`https://do.internal${AGENT_SOCKET_INTERNAL_PROXY_PATH}`, {
      method: "POST",
      headers: {
        Authorization: `Bearer ${gateSecret}`,
@@ -113,7 +113,7 @@ async function fetchThroughClientSocket(
  );
 }

-async function fetchClientWithRecordHeaders(
+async function fetchAgentWithRecordHeaders(
  targetUrl: string,
  method: string,
  forwardRecord: Record<string, string>,
@@ -130,7 +130,7 @@ async function fetchClientWithRecordHeaders(
  });
 }

-async function fetchClientWithDashboardHeaders(
+async function fetchAgentWithDashboardHeaders(
  targetUrl: string,
  method: string,
  headers: Headers,
@@ -143,15 +143,15 @@ async function fetchClientWithDashboardHeaders(
  });
 }

-async function fetchClientSocketStatus(
+async function fetchAgentSocketStatus(
  env: Env["Bindings"],
  name: string,
 ): Promise<{ ok: true; connected: boolean } | { ok: false }> {
  try {
-    const id = env.CLIENT_SOCKET.idFromName(name);
-    const stub = env.CLIENT_SOCKET.get(id);
+    const id = env.AGENT_SOCKET.idFromName(name);
+    const stub = env.AGENT_SOCKET.get(id);
    const resp = await stub.fetch(
-      new Request(`https://do${CLIENT_SOCKET_INTERNAL_STATUS_PATH}`, {
+      new Request(`https://do${AGENT_SOCKET_INTERNAL_STATUS_PATH}`, {
        method: "GET",
        headers: { Authorization: `Bearer ${env.GATEWAY_SECRET}` },
      }),
@@ -171,7 +171,7 @@ function endpointStatusFromKvAndDo(record: EndpointRecord, doConnected: boolean
    return "online";
  }
  if (doConnected === false) {
-    if (isLocalClientUrl(record.url)) {
+    if (isLocalAgentUrl(record.url)) {
      return "offline";
    }
    const age = Date.now() - record.lastHeartbeat;
@@ -184,7 +184,7 @@ function endpointStatusFromKvAndDo(record: EndpointRecord, doConnected: boolean
 // ── Health ──────────────────────────────────────────────────────────
 app.get("/healthz", (c) => c.json({ ok: true }));

-// ── Client reverse WebSocket (GATEWAY_SECRET query param) ────────────
+// ── Agent reverse WebSocket (GATEWAY_SECRET query param) ────────────
 app.get("/ws/connect", async (c) => {
  const secret = c.req.query("secret");
  const name = c.req.query("name");
@@ -197,8 +197,8 @@ app.get("/ws/connect", async (c) => {
  if (c.req.header("Upgrade") !== "websocket") {
    return c.text("expected WebSocket upgrade", 426);
  }
-  const id = c.env.CLIENT_SOCKET.idFromName(name);
-  const stub = c.env.CLIENT_SOCKET.get(id);
+  const id = c.env.AGENT_SOCKET.idFromName(name);
+  const stub = c.env.AGENT_SOCKET.get(id);
  return stub.fetch(c.req.raw);
 });

@@ -210,9 +210,9 @@ gateway.post("/register", async (c) => {
    name?: string;
    url?: string;
    secret?: string;
-    clientToken?: string;
+    agentToken?: string;
  }>();
-  const { name, url, secret, clientToken } = body;
+  const { name, url, secret, agentToken } = body;

  if (!name || !url) {
    return c.json({ error: "name and url required" }, 400);
@@ -227,7 +227,7 @@ gateway.post("/register", async (c) => {
  const record: EndpointRecord = {
    name,
    url: url.replace(/\/+$/, ""), // strip trailing slash
-    clientToken: clientToken ?? existing?.clientToken ?? "",
+    agentToken: agentToken ?? existing?.agentToken ?? "",
    registeredAt: existing?.registeredAt ?? now,
    lastHeartbeat: now,
  };
@@ -261,7 +261,7 @@ gateway.get("/endpoints", async (c) => {
  for (const key of list.keys) {
    const record = await c.env.ENDPOINTS.get<EndpointRecord>(key.name, "json");
    if (record) {
-      const doStatus = await fetchClientSocketStatus(c.env, record.name);
+      const doStatus = await fetchAgentSocketStatus(c.env, record.name);
      const doConnected = doStatus.ok ? doStatus.connected : null;
      endpoints.push({
        name: record.name,
@@ -277,25 +277,25 @@ gateway.get("/endpoints", async (c) => {

 app.route("/api/gateway", gateway);

-// ── API proxy: /api/clients/:client/* → WebSocket (preferred) or client tunnel URL (dashboard auth) ──
-app.all("/api/clients/:client/*", async (c) => {
+// ── API proxy: /api/agents/:agent/* → WebSocket (preferred) or agent tunnel URL (dashboard auth) ──
+app.all("/api/agents/:agent/*", async (c) => {
  if (!checkDashboardAuth(c)) return c.json({ error: "unauthorized" }, 401);
-  const client = c.req.param("client");
-  const record = await c.env.ENDPOINTS.get<EndpointRecord>(client, "json");
+  const agent = c.req.param("agent");
+  const record = await c.env.ENDPOINTS.get<EndpointRecord>(agent, "json");

  if (!record) {
-    return c.json({ error: "client not found" }, 404);
+    return c.json({ error: "agent not found" }, 404);
  }

  const url = new URL(c.req.url);
-  const pathAfterClient = url.pathname.replace(`/api/clients/${client}`, "");
-  const targetUrl = `${record.url}/api${pathAfterClient}${url.search}`;
-  const proxyPath = `/api${pathAfterClient}${url.search}`;
+  const pathAfterAgent = url.pathname.replace(`/api/agents/${agent}`, "");
+  const targetUrl = `${record.url}/api${pathAfterAgent}${url.search}`;
+  const proxyPath = `/api${pathAfterAgent}${url.search}`;
  const method = c.req.method;
-  const token = record.clientToken ?? "";
+  const token = record.agentToken ?? "";
  const forwardRecord = buildForwardHeaders(c.req.raw.headers, token);

-  const doStatus = await fetchClientSocketStatus(c.env, client);
+  const doStatus = await fetchAgentSocketStatus(c.env, agent);
  if (doStatus.ok && doStatus.connected) {
    const bodyStr = await readBodyForWsProxy(method, c.req.raw);
    const wsRequest: WsRequest = {
@@ -305,7 +305,7 @@ 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 fetchThroughAgentSocket(c.env, agent, c.env.GATEWAY_SECRET, wsRequest);
    if (proxyResp.status !== 503) {
      return new Response(proxyResp.body, {
        status: proxyResp.status,
@@ -313,25 +313,25 @@ app.all("/api/clients/:client/*", async (c) => {
      });
    }
    try {
-      const resp = await fetchClientWithRecordHeaders(targetUrl, method, forwardRecord, bodyStr);
+      const resp = await fetchAgentWithRecordHeaders(targetUrl, method, forwardRecord, bodyStr);
      return new Response(resp.body, {
        status: resp.status,
        headers: resp.headers,
      });
    } catch (err) {
-      return c.json({ error: "client unreachable", detail: String(err) }, 502);
+      return c.json({ error: "agent unreachable", detail: String(err) }, 502);
    }
  }

  const headers = buildDashboardProxyHeaders(c.req.raw.headers, token);
  try {
-    const resp = await fetchClientWithDashboardHeaders(targetUrl, method, headers, c.req.raw.body);
+    const resp = await fetchAgentWithDashboardHeaders(targetUrl, method, headers, c.req.raw.body);
    return new Response(resp.body, {
      status: resp.status,
      headers: resp.headers,
    });
  } catch (err) {
-    return c.json({ error: "client unreachable", detail: String(err) }, 502);
+    return c.json({ error: "agent unreachable", detail: String(err) }, 502);
  }
 });

@@ -7,14 +7,10 @@ binding = "ENDPOINTS"
 id = "88b118d1cfab4c049f9c1684848811a3"

 [durable_objects]
-bindings = [{ name = "CLIENT_SOCKET", class_name = "ClientSocket" }]
+bindings = [{ name = "AGENT_SOCKET", class_name = "AgentSocket" }]

 [[migrations]]
 tag = "add-agent-socket"
 new_sqlite_classes = ["AgentSocket"]

-[[migrations]]
-tag = "rename-agent-to-client"
-renamed_classes = [{ from = "AgentSocket", to = "ClientSocket" }]
-
 # GATEWAY_SECRET is set via `wrangler secret put`
@@ -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 },
+);
@@ -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) : []),
 };
@@ -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, []);
@@ -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 },
+);