chore: make bundle fully self-contained, no external imports

- Remove uncagedWorkflowExternals() from scaffold build script
- Remove --external from Bun.build config
- Tighten bundle validator: only Node built-ins allowed, all deps must be inlined
- Update skill.ts documentation

Bundles are now deterministic — same Node/Bun version = same behavior,
no dependency resolution at runtime.

.changeset/env-api-unify.md

@@ -0,0 +1,5 @@
+---
+"@uncaged/workflow-util": patch
+---
+
+Replace optionalEnv/requireEnv with unified env(name, fallback) API

.changeset/fix-internal-deps.md

@@ -0,0 +1,5 @@
+---
+"@uncaged/workflow-protocol": patch
+---
+
+fix: correct internal dependency versions for prerelease

.changeset/fix-publish-src.md

@@ -0,0 +1,5 @@
+---
+"@uncaged/workflow-util-agent": patch
+---
+
+fix: include create-agent-adapter.ts in published src

.changeset/fix-workspace-deps.md

@@ -0,0 +1,5 @@
+---
+"@uncaged/workflow-protocol": patch
+---
+
+fix: use npm publish with pinned deps instead of bun publish (workspace:^ resolution bug)

.changeset/pre.json

@@ -0,0 +1,30 @@
+{
+  "mode": "pre",
+  "tag": "alpha",
+  "initialVersions": {
+    "@uncaged/cli-workflow": "0.4.5",
+    "@uncaged/workflow-agent-cursor": "0.4.5",
+    "@uncaged/workflow-agent-hermes": "0.4.5",
+    "@uncaged/workflow-agent-llm": "0.4.5",
+    "@uncaged/workflow-agent-react": "0.4.5",
+    "@uncaged/workflow-cas": "0.4.5",
+    "@uncaged/workflow-dashboard": "0.1.0",
+    "@uncaged/workflow-execute": "0.4.5",
+    "@uncaged/workflow-gateway": "0.4.5",
+    "@uncaged/workflow-protocol": "0.4.5",
+    "@uncaged/workflow-reactor": "0.4.5",
+    "@uncaged/workflow-register": "0.4.5",
+    "@uncaged/workflow-runtime": "0.4.5",
+    "@uncaged/workflow-template-develop": "0.4.5",
+    "@uncaged/workflow-template-solve-issue": "0.4.5",
+    "@uncaged/workflow-util": "0.4.5",
+    "@uncaged/workflow-util-agent": "0.4.5"
+  },
+  "changesets": [
+    "env-api-unify",
+    "fix-internal-deps",
+    "fix-publish-src",
+    "fix-workspace-deps",
+    "rfc-252-agent-fn"
+  ]
+}

.changeset/rfc-252-agent-fn.md

@@ -0,0 +1,5 @@
+---
+"@uncaged/workflow-protocol": minor
+---
+
+feat: AgentFn<Opt> type boundary and createAgentAdapter bridging function (RFC #252)

.env.example

@@ -0,0 +1,40 @@
+# ──────────────────────────────────────────────
+# Workflow Engine — Environment Variables
+# ──────────────────────────────────────────────
+# Copy this file to .env and fill in the values.
+
+# ── Cursor Agent ──
+
+# CLI command to invoke the Cursor agent (required for develop workflow)
+WORKFLOW_CURSOR_COMMAND=
+
+# Model override for Cursor agent
+WORKFLOW_CURSOR_MODEL=
+
+# Timeout in milliseconds for Cursor agent operations
+WORKFLOW_CURSOR_TIMEOUT=
+
+# ── Hermes Agent (used by develop tester/committer + solve-issue) ──
+
+# CLI command to invoke the Hermes agent (absolute path required)
+WORKFLOW_HERMES_COMMAND=
+
+# Model override for Hermes agent
+WORKFLOW_HERMES_MODEL=
+
+# Timeout in milliseconds for Hermes agent operations
+WORKFLOW_HERMES_TIMEOUT=
+
+# ── Storage ──
+
+# Override the workflow storage root directory
+# Default: ~/.uncaged/workflow
+WORKFLOW_STORAGE_ROOT=
+
+# Gateway secret for the serve command
+WORKFLOW_DASHBOARD_SECRET=
+
+# ── Display ──
+
+# Set to any value to disable colored output
+# NO_COLOR=1

.githooks/pre-push

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

.gitignore

@@ -6,3 +6,6 @@ tsconfig.tsbuildinfo
 .npmrc
 
 bunfig.toml
+xiaoju/
+solve-issue-entry.ts
+packages/workflow-template-develop/develop.esm.js

biome.json

@@ -1,7 +1,13 @@
 {
   "$schema": "https://biomejs.dev/schemas/2.4.15/schema.json",
   "files": {
-    "includes": ["**", "!**/dist", "!**/node_modules", "!packages/workflow/workflow"]
+    "includes": [
+      "**",
+      "!**/dist",
+      "!**/node_modules",
+      "!packages/workflow/workflow",
+      "!xiaoju/scripts/bundle.ts"
+    ]
   },
   "assist": { "actions": { "source": { "organizeImports": "on" } } },
   "formatter": {

develop-entry.ts

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

packages/cli-workflow/CHANGELOG.md

@@ -1,5 +1,71 @@
 # @uncaged/cli-workflow
 
+## 0.5.0-alpha.4
+
+### Patch Changes
+
+- Updated dependencies
+- Updated dependencies [f74b482]
+- Updated dependencies [f74b482]
+  - @uncaged/workflow-util@0.5.0-alpha.4
+  - @uncaged/workflow-protocol@0.5.0-alpha.4
+  - @uncaged/workflow-cas@0.5.0-alpha.4
+  - @uncaged/workflow-execute@0.5.0-alpha.4
+  - @uncaged/workflow-gateway@0.5.0-alpha.4
+  - @uncaged/workflow-register@0.5.0-alpha.4
+  - @uncaged/workflow-runtime@0.5.0-alpha.4
+
+## 0.5.0-alpha.3
+
+### Patch Changes
+
+- Updated dependencies
+  - @uncaged/workflow-protocol@0.5.0-alpha.3
+  - @uncaged/workflow-cas@0.5.0-alpha.3
+  - @uncaged/workflow-execute@0.5.0-alpha.3
+  - @uncaged/workflow-gateway@0.5.0-alpha.3
+  - @uncaged/workflow-register@0.5.0-alpha.3
+  - @uncaged/workflow-runtime@0.5.0-alpha.3
+  - @uncaged/workflow-util@0.5.0-alpha.3
+
+## 0.5.0-alpha.2
+
+### Patch Changes
+
+- Updated dependencies
+  - @uncaged/workflow-protocol@0.5.0-alpha.2
+  - @uncaged/workflow-cas@0.5.0-alpha.2
+  - @uncaged/workflow-execute@0.5.0-alpha.2
+  - @uncaged/workflow-gateway@0.5.0-alpha.2
+  - @uncaged/workflow-register@0.5.0-alpha.2
+  - @uncaged/workflow-runtime@0.5.0-alpha.2
+  - @uncaged/workflow-util@0.5.0-alpha.2
+
+## 0.5.0-alpha.1
+
+### Patch Changes
+
+- @uncaged/workflow-cas@0.5.0-alpha.1
+- @uncaged/workflow-execute@0.5.0-alpha.1
+- @uncaged/workflow-gateway@0.5.0-alpha.1
+- @uncaged/workflow-protocol@0.5.0-alpha.1
+- @uncaged/workflow-register@0.5.0-alpha.1
+- @uncaged/workflow-runtime@0.5.0-alpha.1
+- @uncaged/workflow-util@0.5.0-alpha.1
+
+## 0.5.0-alpha.0
+
+### Patch Changes
+
+- Updated dependencies
+  - @uncaged/workflow-protocol@0.5.0-alpha.0
+  - @uncaged/workflow-cas@0.5.0-alpha.0
+  - @uncaged/workflow-execute@0.5.0-alpha.0
+  - @uncaged/workflow-register@0.5.0-alpha.0
+  - @uncaged/workflow-runtime@0.5.0-alpha.0
+  - @uncaged/workflow-util@0.5.0-alpha.0
+  - @uncaged/workflow-gateway@0.5.0-alpha.0
+
 ## 0.4.5
 
 ### Patch Changes

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

@@ -2,14 +2,14 @@ import { describe, expect, test } from "bun:test";
 
 import { createContentMerkleNode, serializeMerkleNode } from "@uncaged/workflow-cas";
 
-import { createApp } from "../src/commands/serve/app.js";
+import { createApp } from "../src/commands/connect/app.js";
 
 function casStoredForm(raw: string): string {
   return serializeMerkleNode(createContentMerkleNode(raw));
 }
 
 function buildApp(storageRoot: string) {
-  const app = createApp(storageRoot);
+  const app = createApp(storageRoot, null);
   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");
+    const app = createApp("/tmp/uncaged-serve-test-nonexistent", null);
     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");
+    const app = createApp("/tmp/uncaged-serve-test-nonexistent", null);
     const res2 = await app.fetch(
       new Request("http://localhost/healthz", {
         headers: { Origin: "http://localhost:5173" },

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

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

packages/cli-workflow/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uncaged/cli-workflow",
-  "version": "0.4.5",
+  "version": "0.5.0-alpha.4",
   "files": [
     "src",
     "dist",

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

@@ -3,8 +3,8 @@ import { printCliError, printCliLine } from "./cli-output.js";
 import { getCommandRegistry } from "./cli-registry.js";
 import { formatCliUsage as formatCliUsageWithGroups } from "./cli-usage.js";
 import { createCasDispatcher } from "./commands/cas/index.js";
+import { dispatchConnect } from "./commands/connect/index.js";
 import { createInitDispatcher } from "./commands/init/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,
-  serve: dispatchServe,
+  connect: dispatchConnect,
 };
 
 export async function runCli(storageRoot: string, argv: string[]): Promise<number> {

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

@@ -59,12 +59,12 @@ export function formatCliUsage(
   );
   lines.push("");
 
-  lines.push("Server:");
+  lines.push("Gateway:");
   lines.push(
     ...formatUsageCommandLines([
       {
-        prefix: "serve [--port N] [--host ADDR]",
-        description: "Start HTTP API server (default: 127.0.0.1:7860)",
+        prefix: "connect [--name NAME] [--gateway URL]",
+        description: "Connect to workflow gateway via WebSocket",
       },
     ]),
   );

packages/cli-workflow/src/commands/connect/app.ts

@@ -8,7 +8,7 @@ import { createWorkflowRoutes } from "./routes-workflow.js";
 
 const MAX_BODY_SIZE = 1_048_576; // 1 MB
 
-export function createApp(storageRoot: string, agentToken: string | null): Hono {
+export function createApp(storageRoot: string, clientToken: string | null): Hono {
   const app = new Hono();
 
   app.onError((_err, c) => {
@@ -37,11 +37,11 @@ export function createApp(storageRoot: string, agentToken: string | null): Hono
     await next();
   });
 
-  // ── Agent token auth (skip healthz) ───────────────────────────────
-  if (agentToken !== null) {
+  // ── Client token auth (skip healthz) ───────────────────────────────
+  if (clientToken !== null) {
     app.use("/api/*", async (c, next) => {
-      const token = c.req.header("X-Agent-Token");
-      if (token !== agentToken) {
+      const token = c.req.header("X-Client-Token");
+      if (token !== clientToken) {
         return c.json({ error: "unauthorized" }, 401);
       }
       await next();

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

@@ -1,63 +1,30 @@
 import { randomUUID } from "node:crypto";
 import { hostname as osHostname } from "node:os";
-import { err, ok, type Result } from "@uncaged/workflow-protocol";
+import { 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 { ServeOptions } from "./types.js";
+import type { ConnectOptions } 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 err(`${flag} requires a value`);
+    return { ok: false, error: `${flag} requires a value` };
   }
   return ok(next);
 }
 
-function parseServeArgv(argv: string[]): Result<ServeOptions, string> {
-  let port = 7860;
-  let hostname = "127.0.0.1";
+function parseConnectArgv(argv: string[]): Result<ConnectOptions, string> {
   let name = osHostname().split(".")[0].toLowerCase();
   let gatewayUrl = DEFAULT_GATEWAY_URL;
-  const gatewaySecret = process.env.WORKFLOW_GATEWAY_SECRET ?? "";
+  const gatewaySecret = process.env.WORKFLOW_DASHBOARD_SECRET ?? "";
   const stringFlags: Record<string, (v: string) => void> = {
-    "--host": (v) => {
-      hostname = v;
-    },
     "--name": (v) => {
       name = v;
     },
@@ -68,12 +35,7 @@ function parseServeArgv(argv: string[]): Result<ServeOptions, string> {
 
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
-    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) {
+    if (arg in stringFlags) {
       const r = requireNextArg(argv, i, arg);
       if (!r.ok) return r;
       stringFlags[arg](r.value);
@@ -81,11 +43,11 @@ function parseServeArgv(argv: string[]): Result<ServeOptions, string> {
     }
   }
 
-  return ok({ port, hostname, name, gatewayUrl, gatewaySecret });
+  return ok({ name, gatewayUrl, gatewaySecret });
 }
 
-export async function dispatchServe(storageRoot: string, argv: string[]): Promise<number> {
-  const parsed = parseServeArgv(argv);
+export async function dispatchConnect(storageRoot: string, argv: string[]): Promise<number> {
+  const parsed = parseConnectArgv(argv);
   if (!parsed.ok) {
     printCliLine(`error: ${parsed.error}`);
     return 1;
@@ -94,36 +56,31 @@ export async function dispatchServe(storageRoot: string, argv: string[]): Promis
   const options = parsed.value;
 
   if (options.gatewaySecret === "") {
-    // No gateway — local-only mode
-    startServer(storageRoot, options, null);
-    printCliLine("no WORKFLOW_GATEWAY_SECRET — running in local-only mode");
-    await new Promise(() => {});
-    return 0;
+    printCliLine("error: WORKFLOW_DASHBOARD_SECRET is required");
+    return 1;
   }
 
-  const agentToken = randomUUID();
-  startServer(storageRoot, options, agentToken);
+  const clientToken = randomUUID();
+  const app = createApp(storageRoot, clientToken);
 
-  // Start WebSocket reverse connection to gateway
   const log = createLogger({ sink: { kind: "stderr" } });
   const stopWsClient = startGatewayWsClient({
     gatewayUrl: options.gatewayUrl,
     name: options.name,
     secret: options.gatewaySecret,
-    localPort: options.port,
+    appFetch: app.fetch,
     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,
-    localUrl,
+    `ws://${options.name}`,
     options.gatewaySecret,
-    agentToken,
+    clientToken,
   );
   if (registered) {
     printCliLine(`registered with gateway as "${options.name}"`);
@@ -132,9 +89,9 @@ export async function dispatchServe(storageRoot: string, argv: string[]): Promis
   const heartbeatTimer = startHeartbeat(
     options.gatewayUrl,
     options.name,
-    localUrl,
+    `ws://${options.name}`,
     options.gatewaySecret,
-    agentToken,
+    clientToken,
     HEARTBEAT_INTERVAL_MS,
   );
 

packages/cli-workflow/src/commands/connect/gateway.ts

@@ -5,13 +5,13 @@ export async function registerWithGateway(
   name: string,
   localUrl: string,
   secret: string,
-  agentToken: string,
+  clientToken: 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, agentToken }),
+      body: JSON.stringify({ name, url: localUrl, secret, clientToken }),
     });
     if (!resp.ok) {
       const body = await resp.text();
@@ -45,10 +45,10 @@ export function startHeartbeat(
   name: string,
   localUrl: string,
   secret: string,
-  agentToken: string,
+  clientToken: string,
   intervalMs: number,
 ): ReturnType<typeof setInterval> {
   return setInterval(() => {
-    registerWithGateway(gatewayUrl, name, localUrl, secret, agentToken).catch(() => {});
+    registerWithGateway(gatewayUrl, name, localUrl, secret, clientToken).catch(() => {});
   }, intervalMs);
 }

packages/cli-workflow/src/commands/connect/index.ts

@@ -0,0 +1,2 @@
+export { dispatchConnect } from "./connect.js";
+export type { ConnectOptions } from "./types.js";

packages/cli-workflow/src/commands/connect/types.ts

@@ -1,6 +1,4 @@
-export type ServeOptions = {
-  port: number;
-  hostname: string;
+export type ConnectOptions = {
   name: string;
   gatewayUrl: string;
   gatewaySecret: string;

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

@@ -5,7 +5,7 @@ export type GatewayWsClientParams = {
   gatewayUrl: string;
   name: string;
   secret: string;
-  localPort: number;
+  appFetch: (request: Request) => Response | Promise<Response>;
   log: LogFn;
 };
 
@@ -44,20 +44,19 @@ async function handleGatewayMessage(
     params.log("ZM8K2PQ1", "gateway WebSocket dropped non-request message");
     return;
   }
-  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);
-  }
+  const localUrl = `http://localhost${req.path}`;
+  const headers = new Headers(req.headers);
   let resp: Response;
   try {
-    resp = await fetch(localUrl, {
-      method: req.method,
-      headers: initHeaders,
-      body: req.body === null ? undefined : req.body,
-    });
+    resp = await params.appFetch(
+      new Request(localUrl, {
+        method: req.method,
+        headers,
+        body: req.body === null ? undefined : req.body,
+      }),
+    );
   } catch (e) {
-    params.log("R4N7BQ3C", `local proxy fetch failed: ${String(e)}`);
+    params.log("R4N7BQ3C", `app.fetch failed: ${String(e)}`);
     const errBody: WsResponse = {
       id: req.id,
       status: 502,

packages/cli-workflow/src/commands/init/workspace.ts

@@ -196,18 +196,13 @@ uncaged-workflow init workspace ${workspaceName}
 
 function bundleTs(): string {
   return [
-    'import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";',
+    'import { mkdir, readdir, writeFile } from "node:fs/promises";',
     'import { join } from "node:path";',
     "",
     'const rootDir = join(import.meta.dir, "..");',
     'const workflowsDir = join(rootDir, "workflows");',
     'const distDir = join(rootDir, "dist");',
     "",
-    "type JsonDeps = {",
-    "  dependencies: Record<string, string> | null;",
-    "  devDependencies: Record<string, string> | null;",
-    "};",
-    "",
     "function isEntryFile(name: string): boolean {",
     '  return name.endsWith("-entry.ts");',
     "}",
@@ -216,36 +211,6 @@ function bundleTs(): string {
     '  return name.slice(0, -".ts".length);',
     "}",
     "",
-    "async function uncagedWorkflowExternals(): Promise<string[]> {",
-    "  const names = new Set<string>();",
-    '  const paths = [join(rootDir, "package.json"), join(workflowsDir, "package.json")];',
-    "  for (const pkgPath of paths) {",
-    "    let raw: string;",
-    "    try {",
-    '      raw = await readFile(pkgPath, "utf8");',
-    "    } catch {",
-    "      continue;",
-    "    }",
-    "    const parsed = JSON.parse(raw) as JsonDeps;",
-    "    const blocks = [parsed.dependencies, parsed.devDependencies];",
-    "    for (const block of blocks) {",
-    "      if (block == null) {",
-    "        continue;",
-    "      }",
-    "      for (const key of Object.keys(block)) {",
-    '        if (key.startsWith("@uncaged/workflow")) {',
-    "          names.add(key);",
-    "        }",
-    "      }",
-    "    }",
-    "  }",
-    "  if (names.size === 0) {",
-    '    names.add("@uncaged/workflow-runtime");',
-    '    names.add("@uncaged/workflow-protocol");',
-    "  }",
-    "  return [...names];",
-    "}",
-    "",
     "async function main(): Promise<void> {",
     "  await mkdir(distDir, { recursive: true });",
     "  let files: string[];",
@@ -261,7 +226,6 @@ function bundleTs(): string {
     '    console.warn("bundle: no *-entry.ts files under workflows/");',
     "    return;",
     "  }",
-    "  const external = await uncagedWorkflowExternals();",
     "  for (const file of entries) {",
     "    const stem = entryStem(file);",
     "    const entryPath = join(workflowsDir, file);",
@@ -272,7 +236,6 @@ function bundleTs(): string {
     '      target: "node",',
     "      splitting: false,",
     '      naming: { entry: "[name].esm.js" },',
-    "      external,",
     "    });",
     "    if (!result.success) {",
     "      for (const log of result.logs) {",

packages/cli-workflow/src/commands/serve/index.ts

@@ -1,3 +0,0 @@
-export { createApp } from "./app.js";
-export { dispatchServe, startServer } from "./serve.js";
-export type { ServeOptions } from "./types.js";

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

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

packages/cli-workflow/src/skill.ts

@@ -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 |
 
-### serve
+### connect
 
 | Command | Args | Description |
 |---------|------|-------------|
-| \`serve\` | \`[--port N] [--host ADDR] [--name NAME]\` | Start HTTP API server with WebSocket gateway connection. \`--name\` registers with the gateway. |
+| \`connect\` | \`[--name NAME] [--gateway URL]\` | Connect to workflow gateway via WebSocket. \`--name\` registers with the gateway. |
 
 ## Typical Workflow
 
@@ -301,13 +301,36 @@ function createLazyAdapter(): AdapterFn {
 }
 \`\`\`
 
+### Agent CLI paths: use env() with absolute path defaults
+
+Every env var in a bundle must have a sensible default — bundles must run without any env vars set. Use \`env(name, fallback)\` from \`@uncaged/workflow-util\`.
+
+Discover the correct CLI path yourself (e.g. \`which cursor-agent\`, \`which hermes\`) and hardcode it as the fallback:
+
+\`\`\`typescript
+import { env } from "@uncaged/workflow-util";
+
+// ❌ WRONG — requireEnv and optionalEnv no longer exist
+const adapter = createCursorAgent({
+  command: requireEnv("WORKFLOW_CURSOR_COMMAND", "set it"),
+  ...
+});
+
+// ✅ CORRECT — env var is an override, fallback is the discovered absolute path
+const adapter = createCursorAgent({
+  command: env("WORKFLOW_CURSOR_COMMAND", "/home/you/.local/bin/cursor-agent"),
+  model: env("WORKFLOW_CURSOR_MODEL", "auto"),
+  timeout: Number(env("WORKFLOW_CURSOR_TIMEOUT", "300000")),
+  ...
+});
+\`\`\`
+
 ### Bundle import restrictions
 
 The bundle validator only allows these import specifiers:
 - Node built-ins (\`node:fs\`, \`node:path\`, etc.)
-- \`@uncaged/workflow-*\` packages
 
-Third-party packages (**including zod**) must be bundled into the \`.esm.js\` file, not left as external imports. When using \`bun build\`, only mark \`@uncaged/*\` as external.
+All other dependencies — including \`@uncaged/workflow-*\` packages, zod, and any third-party code — must be bundled into the \`.esm.js\` file. Bundles are fully self-contained: same Node/Bun version = same behavior.
 
 ### No default exports
 

packages/workflow-agent-cursor/CHANGELOG.md

@@ -1,5 +1,62 @@
 # @uncaged/workflow-agent-cursor
 
+## 0.5.0-alpha.4
+
+### Patch Changes
+
+- Updated dependencies
+- Updated dependencies [f74b482]
+- Updated dependencies [f74b482]
+  - @uncaged/workflow-util@0.5.0-alpha.4
+  - @uncaged/workflow-protocol@0.5.0-alpha.4
+  - @uncaged/workflow-cas@0.5.0-alpha.4
+  - @uncaged/workflow-runtime@0.5.0-alpha.4
+  - @uncaged/workflow-util-agent@0.5.0-alpha.4
+
+## 0.5.0-alpha.3
+
+### Patch Changes
+
+- Updated dependencies
+  - @uncaged/workflow-protocol@0.5.0-alpha.3
+  - @uncaged/workflow-cas@0.5.0-alpha.3
+  - @uncaged/workflow-runtime@0.5.0-alpha.3
+  - @uncaged/workflow-util@0.5.0-alpha.3
+  - @uncaged/workflow-util-agent@0.5.0-alpha.3
+
+## 0.5.0-alpha.2
+
+### Patch Changes
+
+- Updated dependencies
+  - @uncaged/workflow-protocol@0.5.0-alpha.2
+  - @uncaged/workflow-cas@0.5.0-alpha.2
+  - @uncaged/workflow-runtime@0.5.0-alpha.2
+  - @uncaged/workflow-util@0.5.0-alpha.2
+  - @uncaged/workflow-util-agent@0.5.0-alpha.2
+
+## 0.5.0-alpha.1
+
+### Patch Changes
+
+- Updated dependencies
+  - @uncaged/workflow-util-agent@0.5.0-alpha.1
+  - @uncaged/workflow-cas@0.5.0-alpha.1
+  - @uncaged/workflow-protocol@0.5.0-alpha.1
+  - @uncaged/workflow-runtime@0.5.0-alpha.1
+  - @uncaged/workflow-util@0.5.0-alpha.1
+
+## 0.5.0-alpha.0
+
+### Patch Changes
+
+- Updated dependencies
+  - @uncaged/workflow-protocol@0.5.0-alpha.0
+  - @uncaged/workflow-cas@0.5.0-alpha.0
+  - @uncaged/workflow-runtime@0.5.0-alpha.0
+  - @uncaged/workflow-util@0.5.0-alpha.0
+  - @uncaged/workflow-util-agent@0.5.0-alpha.0
+
 ## 0.4.5
 
 ### Patch Changes

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

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

packages/workflow-agent-cursor/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uncaged/workflow-agent-cursor",
-  "version": "0.4.5",
+  "version": "0.5.0-alpha.4",
   "files": [
     "src",
     "dist",

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

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

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

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

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

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

packages/workflow-agent-cursor/tsconfig.json

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

packages/workflow-agent-hermes/CHANGELOG.md

@@ -1,5 +1,41 @@
 # @uncaged/workflow-agent-hermes
 
+## 0.5.0-alpha.4
+
+### Patch Changes
+
+- @uncaged/workflow-runtime@0.5.0-alpha.4
+- @uncaged/workflow-util-agent@0.5.0-alpha.4
+
+## 0.5.0-alpha.3
+
+### Patch Changes
+
+- @uncaged/workflow-runtime@0.5.0-alpha.3
+- @uncaged/workflow-util-agent@0.5.0-alpha.3
+
+## 0.5.0-alpha.2
+
+### Patch Changes
+
+- @uncaged/workflow-runtime@0.5.0-alpha.2
+- @uncaged/workflow-util-agent@0.5.0-alpha.2
+
+## 0.5.0-alpha.1
+
+### Patch Changes
+
+- Updated dependencies
+  - @uncaged/workflow-util-agent@0.5.0-alpha.1
+  - @uncaged/workflow-runtime@0.5.0-alpha.1
+
+## 0.5.0-alpha.0
+
+### Patch Changes
+
+- @uncaged/workflow-runtime@0.5.0-alpha.0
+- @uncaged/workflow-util-agent@0.5.0-alpha.0
+
 ## 0.4.5
 
 ### Patch Changes

packages/workflow-agent-hermes/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uncaged/workflow-agent-hermes",
-  "version": "0.4.5",
+  "version": "0.5.0-alpha.4",
   "files": [
     "src",
     "dist",

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

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

packages/workflow-agent-llm/CHANGELOG.md

@@ -1,5 +1,41 @@
 # @uncaged/workflow-agent-llm
 
+## 0.5.0-alpha.4
+
+### Patch Changes
+
+- @uncaged/workflow-runtime@0.5.0-alpha.4
+- @uncaged/workflow-util-agent@0.5.0-alpha.4
+
+## 0.5.0-alpha.3
+
+### Patch Changes
+
+- @uncaged/workflow-runtime@0.5.0-alpha.3
+- @uncaged/workflow-util-agent@0.5.0-alpha.3
+
+## 0.5.0-alpha.2
+
+### Patch Changes
+
+- @uncaged/workflow-runtime@0.5.0-alpha.2
+- @uncaged/workflow-util-agent@0.5.0-alpha.2
+
+## 0.5.0-alpha.1
+
+### Patch Changes
+
+- Updated dependencies
+  - @uncaged/workflow-util-agent@0.5.0-alpha.1
+  - @uncaged/workflow-runtime@0.5.0-alpha.1
+
+## 0.5.0-alpha.0
+
+### Patch Changes
+
+- @uncaged/workflow-runtime@0.5.0-alpha.0
+- @uncaged/workflow-util-agent@0.5.0-alpha.0
+
 ## 0.4.5
 
 ### Patch Changes

packages/workflow-agent-llm/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uncaged/workflow-agent-llm",
-  "version": "0.4.5",
+  "version": "0.5.0-alpha.4",
   "files": [
     "src",
     "dist",

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

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

packages/workflow-agent-react/CHANGELOG.md

@@ -1,5 +1,51 @@
 # @uncaged/workflow-agent-react
 
+## 0.5.0-alpha.4
+
+### Patch Changes
+
+- Updated dependencies [f74b482]
+- Updated dependencies [f74b482]
+  - @uncaged/workflow-protocol@0.5.0-alpha.4
+  - @uncaged/workflow-reactor@0.5.0-alpha.4
+  - @uncaged/workflow-util-agent@0.5.0-alpha.4
+
+## 0.5.0-alpha.3
+
+### Patch Changes
+
+- Updated dependencies
+  - @uncaged/workflow-protocol@0.5.0-alpha.3
+  - @uncaged/workflow-reactor@0.5.0-alpha.3
+  - @uncaged/workflow-util-agent@0.5.0-alpha.3
+
+## 0.5.0-alpha.2
+
+### Patch Changes
+
+- Updated dependencies
+  - @uncaged/workflow-protocol@0.5.0-alpha.2
+  - @uncaged/workflow-reactor@0.5.0-alpha.2
+  - @uncaged/workflow-util-agent@0.5.0-alpha.2
+
+## 0.5.0-alpha.1
+
+### Patch Changes
+
+- Updated dependencies
+  - @uncaged/workflow-util-agent@0.5.0-alpha.1
+  - @uncaged/workflow-protocol@0.5.0-alpha.1
+  - @uncaged/workflow-reactor@0.5.0-alpha.1
+
+## 0.5.0-alpha.0
+
+### Patch Changes
+
+- Updated dependencies
+  - @uncaged/workflow-protocol@0.5.0-alpha.0
+  - @uncaged/workflow-reactor@0.5.0-alpha.0
+  - @uncaged/workflow-util-agent@0.5.0-alpha.0
+
 ## 0.4.5
 
 ### Patch Changes

packages/workflow-agent-react/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uncaged/workflow-agent-react",
-  "version": "0.4.5",
+  "version": "0.5.0-alpha.4",
   "files": [
     "src",
     "dist",

packages/workflow-cas/CHANGELOG.md

@@ -1,5 +1,46 @@
 # @uncaged/workflow-cas
 
+## 0.5.0-alpha.4
+
+### Patch Changes
+
+- Updated dependencies
+- Updated dependencies [f74b482]
+- Updated dependencies [f74b482]
+  - @uncaged/workflow-util@0.5.0-alpha.4
+  - @uncaged/workflow-protocol@0.5.0-alpha.4
+
+## 0.5.0-alpha.3
+
+### Patch Changes
+
+- Updated dependencies
+  - @uncaged/workflow-protocol@0.5.0-alpha.3
+  - @uncaged/workflow-util@0.5.0-alpha.3
+
+## 0.5.0-alpha.2
+
+### Patch Changes
+
+- Updated dependencies
+  - @uncaged/workflow-protocol@0.5.0-alpha.2
+  - @uncaged/workflow-util@0.5.0-alpha.2
+
+## 0.5.0-alpha.1
+
+### Patch Changes
+
+- @uncaged/workflow-protocol@0.5.0-alpha.1
+- @uncaged/workflow-util@0.5.0-alpha.1
+
+## 0.5.0-alpha.0
+
+### Patch Changes
+
+- Updated dependencies
+  - @uncaged/workflow-protocol@0.5.0-alpha.0
+  - @uncaged/workflow-util@0.5.0-alpha.0
+
 ## 0.4.5
 
 ### Patch Changes

packages/workflow-cas/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uncaged/workflow-cas",
-  "version": "0.4.5",
+  "version": "0.5.0-alpha.4",
   "files": [
     "src",
     "dist",

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/api.ts

@@ -26,11 +26,11 @@ function authHeaders(): Record<string, string> {
   return {};
 }
 
-function agentBase(agent: string): string {
+function clientBase(client: string): string {
   if (GATEWAY_URL) {
-    return `${GATEWAY_URL}/api/agents/${agent}`;
+    return `${GATEWAY_URL}/api/clients/${client}`;
   }
-  // Local dev: proxy via vite, no agent prefix
+  // Local dev: proxy via vite, no client prefix
   return "/api";
 }
 
@@ -57,7 +57,7 @@ async function fetchJson<T>(base: string, path: string): Promise<T> {
 
 // ── Endpoint types ──────────────────────────────────────────────────
 
-export type AgentEndpoint = {
+export type ClientEndpoint = {
   name: string;
   url: string;
   status: string;
@@ -122,6 +122,7 @@ export type WorkflowGraph = {
 
 export type WorkflowRoleDescriptor = {
   description: string;
+  systemPrompt: string;
   schema: Record<string, unknown>;
 };
 
@@ -141,61 +142,61 @@ export type WorkflowDetail = {
 
 // ── Gateway endpoints ───────────────────────────────────────────────
 
-export function listAgents(): Promise<AgentEndpoint[]> {
+export function listClients(): Promise<ClientEndpoint[]> {
   const url = GATEWAY_URL || "";
   return fetchJson(url, "/api/gateway/endpoints");
 }
 
-// ── Agent-scoped endpoints ──────────────────────────────────────────
+// ── Client-scoped endpoints ──────────────────────────────────────────
 
-export function listWorkflows(agent: string): Promise<{ workflows: WorkflowSummary[] }> {
-  return fetchJson(agentBase(agent), "/workflows");
+export function listWorkflows(client: string): Promise<{ workflows: WorkflowSummary[] }> {
+  return fetchJson(clientBase(client), "/workflows");
 }
 
-export async function getWorkflowDetail(agent: string, name: string): Promise<WorkflowDetail> {
-  return fetchJson<WorkflowDetail>(agentBase(agent), `/workflows/${encodeURIComponent(name)}`);
+export async function getWorkflowDetail(client: string, name: string): Promise<WorkflowDetail> {
+  return fetchJson<WorkflowDetail>(clientBase(client), `/workflows/${encodeURIComponent(name)}`);
 }
 
 export async function getWorkflowDescriptor(
-  agent: string,
+  client: string,
   name: string,
 ): Promise<WorkflowDescriptor | null> {
-  const res = await getWorkflowDetail(agent, name);
+  const res = await getWorkflowDetail(client, name);
   return res.descriptor;
 }
 
-export function listThreads(agent: string): Promise<{ threads: ThreadSummary[] }> {
-  return fetchJson(agentBase(agent), "/threads");
+export function listThreads(client: string): Promise<{ threads: ThreadSummary[] }> {
+  return fetchJson(clientBase(client), "/threads");
 }
 
-export function listRunningThreads(agent: string): Promise<{ threads: ThreadSummary[] }> {
-  return fetchJson(agentBase(agent), "/threads/running");
+export function listRunningThreads(client: string): Promise<{ threads: ThreadSummary[] }> {
+  return fetchJson(clientBase(client), "/threads/running");
 }
 
-export function getThread(agent: string, id: string): Promise<{ records: ThreadRecord[] }> {
-  return fetchJson(agentBase(agent), `/threads/${id}`);
+export function getThread(client: string, id: string): Promise<{ records: ThreadRecord[] }> {
+  return fetchJson(clientBase(client), `/threads/${id}`);
 }
 
 export function runThread(
-  agent: string,
+  client: string,
   workflow: string,
   prompt: string,
 ): Promise<{ threadId: string }> {
-  return postJson(agentBase(agent), "/threads", { workflow, prompt });
+  return postJson(clientBase(client), "/threads", { workflow, prompt });
 }
 
-export function killThread(agent: string, threadId: string): Promise<{ ok: boolean }> {
-  return postJson(agentBase(agent), `/threads/${threadId}/kill`, {});
+export function killThread(client: string, threadId: string): Promise<{ ok: boolean }> {
+  return postJson(clientBase(client), `/threads/${threadId}/kill`, {});
 }
 
-export function pauseThread(agent: string, threadId: string): Promise<{ ok: boolean }> {
-  return postJson(agentBase(agent), `/threads/${threadId}/pause`, {});
+export function pauseThread(client: string, threadId: string): Promise<{ ok: boolean }> {
+  return postJson(clientBase(client), `/threads/${threadId}/pause`, {});
 }
 
-export function resumeThread(agent: string, threadId: string): Promise<{ ok: boolean }> {
-  return postJson(agentBase(agent), `/threads/${threadId}/resume`, {});
+export function resumeThread(client: string, threadId: string): Promise<{ ok: boolean }> {
+  return postJson(clientBase(client), `/threads/${threadId}/resume`, {});
 }
 
-export function getAgentHealth(agent: string): Promise<{ ok: boolean }> {
-  return fetchJson(agentBase(agent), "/healthz");
+export function getClientHealth(client: string): Promise<{ ok: boolean }> {
+  return fetchJson(clientBase(client), "/healthz");
 }

packages/workflow-dashboard/src/app.tsx

@@ -6,12 +6,14 @@ import { Sidebar } from "./components/sidebar.tsx";
 import { StatusBar } from "./components/status-bar.tsx";
 import { ThreadDetail } from "./components/thread-detail.tsx";
 import { ThreadList } from "./components/thread-list.tsx";
+import { WorkflowDetail } from "./components/workflow-detail.tsx";
 import { WorkflowList } from "./components/workflow-list.tsx";
 import { useHashRoute } from "./use-hash-route.ts";
 
 export function App() {
   const [authed, setAuthed] = useState(hasApiKey());
-  const { view, agent, threadId, setView, setAgent, setThreadId } = useHashRoute();
+  const { view, client, threadId, workflowName, setView, setClient, setThreadId, setWorkflowName } =
+    useHashRoute();
   const [showRun, setShowRun] = useState(false);
 
   if (!authed) {
@@ -22,36 +24,45 @@ export function App() {
     <div className="flex h-screen">
       <Sidebar
         view={view}
-        agent={agent}
+        client={client}
         onViewChange={setView}
-        onAgentChange={setAgent}
+        onClientChange={setClient}
         onLogout={() => {
           clearApiKey();
           setAuthed(false);
         }}
       />
       <main className="flex-1 overflow-hidden flex flex-col">
-        <StatusBar agent={agent} onRun={() => setShowRun(true)} />
+        <StatusBar client={client} onRun={() => setShowRun(true)} />
         <div className="flex-1 overflow-auto p-6">
-          {!agent && (
+          {!client && (
             <div className="flex items-center justify-center h-full">
               <p style={{ color: "var(--color-text-muted)" }}>
-                Select an agent from the sidebar to get started.
+                Select an client from the sidebar to get started.
               </p>
             </div>
           )}
-          {agent && view === "threads" && threadId === null && (
-            <ThreadList agent={agent} onSelect={setThreadId} />
+          {client && view === "threads" && threadId === null && (
+            <ThreadList client={client} onSelect={setThreadId} />
           )}
-          {agent && view === "threads" && threadId !== null && (
-            <ThreadDetail agent={agent} threadId={threadId} onBack={() => setThreadId(null)} />
+          {client && view === "threads" && threadId !== null && (
+            <ThreadDetail client={client} threadId={threadId} onBack={() => setThreadId(null)} />
+          )}
+          {client && view === "workflows" && workflowName === null && (
+            <WorkflowList client={client} onSelect={setWorkflowName} />
+          )}
+          {client && view === "workflows" && workflowName !== null && (
+            <WorkflowDetail
+              client={client}
+              workflowName={workflowName}
+              onBack={() => setWorkflowName(null)}
+            />
           )}
-          {agent && view === "workflows" && <WorkflowList agent={agent} />}
         </div>
       </main>
-      {showRun && agent && (
+      {showRun && client && (
         <RunDialog
-          agent={agent}
+          client={client}
           onClose={() => setShowRun(false)}
           onCreated={(id) => {
             setShowRun(false);

packages/workflow-dashboard/src/components/record-card.tsx

@@ -3,7 +3,7 @@ import { Markdown } from "./markdown.tsx";
 
 const ROLE_COLORS: Record<string, string> = {
   preparer: "#8b5cf6",
-  agent: "#3b82f6",
+  client: "#3b82f6",
   extractor: "#f59e0b",
 };
 

packages/workflow-dashboard/src/components/run-dialog.tsx

@@ -3,13 +3,13 @@ import { listWorkflows, runThread } from "../api.ts";
 import { useFetch } from "../hooks.ts";
 
 type Props = {
-  agent: string;
+  client: string;
   onClose: () => void;
   onCreated: (threadId: string) => void;
 };
 
-export function RunDialog({ agent, onClose, onCreated }: Props) {
-  const workflows = useFetch(() => listWorkflows(agent), [agent]);
+export function RunDialog({ client, onClose, onCreated }: Props) {
+  const workflows = useFetch(() => listWorkflows(client), [client]);
   const [workflow, setWorkflow] = useState("");
   const [prompt, setPrompt] = useState("");
   const [submitting, setSubmitting] = useState(false);
@@ -21,7 +21,7 @@ export function RunDialog({ agent, onClose, onCreated }: Props) {
     setSubmitting(true);
     setError(null);
     try {
-      const result = await runThread(agent, workflow, prompt);
+      const result = await runThread(client, workflow, prompt);
       onCreated(result.threadId);
     } catch (err) {
       setError(err instanceof Error ? err.message : String(err));
@@ -38,7 +38,7 @@ export function RunDialog({ agent, 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 {agent}</h3>
+        <h3 className="text-lg font-semibold mb-4">Run Thread on {client}</h3>
         <form onSubmit={handleSubmit} className="space-y-4">
           <div>
             <label

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

@@ -1,27 +1,27 @@
 import { useEffect } from "react";
-import type { AgentEndpoint } from "../api.ts";
-import { listAgents } from "../api.ts";
+import type { ClientEndpoint } from "../api.ts";
+import { listClients } from "../api.ts";
 import { useFetch } from "../hooks.ts";
 
 type Props = {
   view: "threads" | "workflows";
-  agent: string | null;
+  client: string | null;
   onViewChange: (v: "threads" | "workflows") => void;
-  onAgentChange: (a: string | null) => void;
+  onClientChange: (a: string | null) => void;
   onLogout: () => void;
 };
 
-export function Sidebar({ view, agent, onViewChange, onAgentChange, onLogout }: Props) {
-  const { status, data } = useFetch(() => listAgents(), []);
+export function Sidebar({ view, client, onViewChange, onClientChange, onLogout }: Props) {
+  const { status, data } = useFetch(() => listClients(), []);
 
-  const agents: AgentEndpoint[] = status === "ok" ? data : [];
+  const clients: ClientEndpoint[] = status === "ok" ? data : [];
 
-  // Auto-select first agent when none is selected
+  // Auto-select first client when none is selected
   useEffect(() => {
-    if (agent === null && agents.length > 0) {
-      onAgentChange(agents[0].name);
+    if (client === null && clients.length > 0) {
+      onClientChange(clients[0].name);
     }
-  }, [agent, agents, onAgentChange]);
+  }, [client, clients, onClientChange]);
 
   const viewItems = [
     { key: "threads" as const, label: "Threads", icon: "⚡" },
@@ -42,33 +42,33 @@ export function Sidebar({ view, agent, onViewChange, onAgentChange, onLogout }:
         </p>
       </div>
 
-      {/* Agent selector */}
+      {/* Client 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="agent-select"
+          htmlFor="client-select"
         >
-          Agent
+          Client
         </label>
         <select
-          id="agent-select"
+          id="client-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={agent ?? ""}
-          onChange={(e) => onAgentChange(e.target.value || null)}
+          value={client ?? ""}
+          onChange={(e) => onClientChange(e.target.value || null)}
           disabled={status === "loading"}
         >
           {status === "loading" ? (
             <option value="">Loading…</option>
-          ) : agents.length === 0 ? (
-            <option value="">No agents online</option>
+          ) : clients.length === 0 ? (
+            <option value="">No clients online</option>
           ) : (
-            agents.map((a) => (
+            clients.map((a) => (
               <option key={a.name} value={a.name}>
                 {a.status === "online" ? "🟢" : "🔴"} {a.name}
               </option>

packages/workflow-dashboard/src/components/status-bar.tsx

@@ -1,10 +1,10 @@
 import { useCallback, useEffect, useRef, useState } from "react";
-import { getAgentHealth } from "../api.ts";
+import { getClientHealth } from "../api.ts";
 
 type HealthStatus = "connected" | "disconnected" | "reconnecting";
 
 type Props = {
-  agent: string | null;
+  client: 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({ agent, onRun }: Props) {
+export function StatusBar({ client, onRun }: Props) {
   const [status, setStatus] = useState<HealthStatus>("disconnected");
   const wasConnectedRef = useRef(false);
 
   const checkHealth = useCallback(async () => {
-    if (!agent) {
+    if (!client) {
       setStatus("disconnected");
       return;
     }
     try {
-      await getAgentHealth(agent);
+      await getClientHealth(client);
       wasConnectedRef.current = true;
       setStatus("connected");
     } catch {
@@ -38,7 +38,7 @@ export function StatusBar({ agent, onRun }: Props) {
         setStatus("disconnected");
       }
     }
-  }, [agent]);
+  }, [client]);
 
   useEffect(() => {
     wasConnectedRef.current = false;
@@ -57,17 +57,17 @@ export function StatusBar({ agent, onRun }: Props) {
     >
       <div className="flex items-center gap-4">
         <span style={{ color: "var(--color-text-muted)" }}>
-          {agent ? `Agent: ${agent}` : "No agent selected"}
+          {client ? `Client: ${client}` : "No client selected"}
         </span>
         <button
           type="button"
           onClick={onRun}
-          disabled={!agent}
+          disabled={!client}
           className="px-3 py-1 rounded text-xs font-medium"
           style={{
-            background: agent ? "var(--color-accent)" : "var(--color-border)",
+            background: client ? "var(--color-accent)" : "var(--color-border)",
             color: "#fff",
-            opacity: agent ? 1 : 0.5,
+            opacity: client ? 1 : 0.5,
           }}
         >
           ▶ Run Thread

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

@@ -14,7 +14,7 @@ import { RecordCard } from "./record-card.tsx";
 import { type NodeState, WorkflowGraph } from "./workflow-graph/index.ts";
 
 type Props = {
-  agent: string;
+  client: string;
   threadId: string;
   onBack: () => void;
 };
@@ -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) {
@@ -52,9 +53,9 @@ function computeNodeStates(records: readonly ThreadRecord[]): Map<string, NodeSt
   return states;
 }
 
-export function ThreadDetail({ agent, threadId, onBack }: Props) {
-  const sse = useSSE(agent, threadId);
-  const { status, data, error } = useFetch(() => getThread(agent, threadId), [agent, threadId]);
+export function ThreadDetail({ client, threadId, onBack }: Props) {
+  const sse = useSSE(client, threadId);
+  const { status, data, error } = useFetch(() => getThread(client, threadId), [client, threadId]);
   const [actionStatus, setActionStatus] = useState<string | null>(null);
   const recordsEndRef = useRef<HTMLDivElement>(null);
   const firstCardByRoleRef = useRef<Map<string, HTMLDivElement>>(new Map());
@@ -72,35 +73,68 @@ export function ThreadDetail({ agent, threadId, onBack }: Props) {
 
   const descriptorFetch = useFetch<WorkflowDescriptor | null>(
     () =>
-      workflowName === null ? Promise.resolve(null) : getWorkflowDescriptor(agent, workflowName),
-    [agent, workflowName],
+      workflowName === null ? Promise.resolve(null) : getWorkflowDescriptor(client, workflowName),
+    [client, workflowName],
   );
 
   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 () => {
@@ -117,7 +151,7 @@ export function ThreadDetail({ agent, threadId, onBack }: Props) {
     setActionStatus(`${action}ing...`);
     try {
       const fn = action === "kill" ? killThread : action === "pause" ? pauseThread : resumeThread;
-      await fn(agent, threadId);
+      await fn(client, threadId);
       setActionStatus(`${action} sent ✓`);
     } catch (e) {
       setActionStatus(`${action} failed: ${e instanceof Error ? e.message : String(e)}`);
@@ -237,11 +271,13 @@ export function ThreadDetail({ agent, 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 +288,11 @@ export function ThreadDetail({ agent, 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/thread-list.tsx

@@ -2,12 +2,12 @@ import { listThreads } from "../api.ts";
 import { useFetch } from "../hooks.ts";
 
 type Props = {
-  agent: string;
+  client: string;
   onSelect: (id: string) => void;
 };
 
-export function ThreadList({ agent, onSelect }: Props) {
-  const { status, data, error } = useFetch(() => listThreads(agent), [agent]);
+export function ThreadList({ client, onSelect }: Props) {
+  const { status, data, error } = useFetch(() => listThreads(client), [client]);
 
   if (status === "loading")
     return <p style={{ color: "var(--color-text-muted)" }}>Loading threads...</p>;

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

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

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

@@ -2,30 +2,40 @@ 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;
 
 /**
- * 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
+ * Build an SVG path for an edge routed to the side of the nodes.
+ * Works for both feedback (bottom→up) and skip-forward (top→down) edges.
+ * The path goes: source → horizontal to side → vertical → horizontal to target
  */
-function feedbackPath(sourceX: number, sourceY: number, targetX: number, targetY: number): string {
-  const rightX = Math.max(sourceX, targetX) + FEEDBACK_OFFSET_X;
+function sidePath(
+  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;
   const r = FEEDBACK_RADIUS;
 
-  // Start from source right side, go right, then up, then left to target right side
+  // Direction: going up (feedback) or down (skip-forward)
+  const goingDown = targetY > sourceY;
+  const vertSourceY = goingDown ? sourceY + r : sourceY - r;
+  const vertTargetY = goingDown ? targetY - r : targetY + r;
+
   const segments = [
     `M ${sourceX} ${sourceY}`,
-    // 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 ${offsetX - d * r} ${sourceY}`,
+    `Q ${offsetX} ${sourceY} ${offsetX} ${vertSourceY}`,
+    `L ${offsetX} ${vertTargetY}`,
+    `Q ${offsetX} ${targetY} ${offsetX - d * r} ${targetY}`,
     `L ${targetX} ${targetY}`,
   ];
 
@@ -57,10 +67,13 @@ export function ConditionEdge(props: EdgeProps) {
   let defaultLabelY: number;
 
   if (isFeedback) {
-    // Custom feedback path routed to the right
-    path = feedbackPath(sourceX, sourceY, targetX, targetY);
-    const rightX = Math.max(sourceX, targetX) + FEEDBACK_OFFSET_X;
-    defaultLabelX = rightX;
+    const side = edgeData?.feedbackSide ?? "right";
+    path = sidePath(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;
     defaultLabelY = (sourceY + targetY) / 2;
   } else {
     const result = getSmoothStepPath({
@@ -78,9 +91,8 @@ export function ConditionEdge(props: EdgeProps) {
     defaultLabelY = result[2];
   }
 
-  const stroke = isFallback ? "var(--color-text-muted)" : "var(--color-accent)";
-  const strokeDasharray = isFallback ? "5 4" : undefined;
-  const label = edgeData?.condition ?? "";
+  const stroke = "var(--color-accent)";
+  const label = isFallback ? "" : (edgeData?.condition ?? "");
 
   // Use pre-computed label position if available, otherwise fall back to default
   const labelX = edgeData?.labelX ?? defaultLabelX;
@@ -88,12 +100,7 @@ export function ConditionEdge(props: EdgeProps) {
 
   return (
     <>
-      <BaseEdge
-        id={id}
-        path={path}
-        markerEnd={markerEnd}
-        style={{ stroke, strokeWidth: 1.5, strokeDasharray }}
-      />
+      <BaseEdge id={id} path={path} markerEnd={markerEnd} style={{ stroke, strokeWidth: 1.5 }} />
       {label !== "" && (
         <EdgeLabelRenderer>
           <div
@@ -102,7 +109,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: isFallback ? "var(--color-text-muted)" : "var(--color-text)",
+              color: "var(--color-text)",
               whiteSpace: "nowrap",
               zIndex: 10,
             }}

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 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,41 @@ 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 +97,13 @@ 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,34 @@ 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}
+          />
+          <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}
+          />
+        </>
       )}
       {isStart ? "▶" : "■"}
     </div>

packages/workflow-dashboard/src/components/workflow-graph/types.ts

@@ -23,6 +23,7 @@ export type ConditionEdgeData = {
   isFallback: boolean;
   isFeedback: boolean;
   isSelfLoop: boolean;
+  feedbackSide: "right" | "left" | null;
   labelX: number | null;
   labelY: number | null;
   [key: string]: unknown;

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[];
@@ -36,13 +36,19 @@ function edgeKey(e: WorkflowGraphEdge): string {
   return `${e.from}->${e.to}::${e.condition}`;
 }
 
+// ── Strategy 1: Longest-path layering (Sugiyama step 1) ─────────────
+
 /**
- * Extract the linear spine from the graph using topological ordering.
- * Forward edges go from lower rank to higher rank; feedback edges go backwards.
- * Self-loops are neither forward nor feedback — they're handled separately.
+ * Assign layers via longest path from sources.
+ *
+ * For each node, rank = max(rank(pred) + 1) over all predecessors.
+ * This guarantees that if a -> b (and not b -> a), rank(a) < rank(b).
+ *
+ * Back-edges (cycles) are detected and excluded from ranking:
+ * we first remove edges that create cycles (DFS-based), compute ranks
+ * on the resulting DAG, then the removed edges become feedback edges.
  */
-// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: topological sort is inherently branchy
-function extractSpine(edges: readonly WorkflowGraphEdge[]): string[] {
+function computeLayersLongestPath(edges: readonly WorkflowGraphEdge[]): string[][] {
   // Collect all node IDs
   const ids = new Set<string>();
   for (const e of edges) {
@@ -50,62 +56,120 @@ function extractSpine(edges: readonly WorkflowGraphEdge[]): string[] {
     ids.add(e.to);
   }
 
-  // Build adjacency for forward edges only (non-self-loop, non-FALLBACK-back)
-  // Strategy: BFS from __start__, picking the first non-FALLBACK forward edge,
-  // or FALLBACK if no other option.
-  const forwardAdj = new Map<string, string[]>();
-  for (const e of edges) {
-    if (e.from === e.to) continue;
-    const existing = forwardAdj.get(e.from) ?? [];
-    existing.push(e.to);
-    forwardAdj.set(e.from, existing);
-  }
-
-  // Walk the main path: prefer non-FALLBACK edges for the spine ordering
-  const visited = new Set<string>();
-  const spine: string[] = [];
-
-  // Build a set of "primary" next targets per node (non-FALLBACK first)
-  const primaryNext = new Map<string, string>();
-  const edgesByFrom = new Map<string, WorkflowGraphEdge[]>();
-  for (const e of edges) {
-    if (e.from === e.to) continue;
-    const list = edgesByFrom.get(e.from) ?? [];
-    list.push(e);
-    edgesByFrom.set(e.from, list);
-  }
-
-  // For each node, the "primary" next is the first non-FALLBACK target,
-  // or the FALLBACK target if all edges are FALLBACK
-  for (const [from, edgeList] of edgesByFrom) {
-    const nonFallback = edgeList.find((e) => e.condition !== "FALLBACK");
-    const fallback = edgeList.find((e) => e.condition === "FALLBACK");
-    primaryNext.set(from, nonFallback?.to ?? fallback?.to ?? "");
-  }
-
-  // Walk the spine from __start__
-  let current: string | null = START_ID;
-  while (current !== null && !visited.has(current)) {
-    visited.add(current);
-    spine.push(current);
-    const next = primaryNext.get(current);
-    if (next !== undefined && next !== "" && !visited.has(next)) {
-      current = next;
-    } else {
-      current = null;
-    }
-  }
-
-  // Add any remaining nodes not on the main path (shouldn't normally happen)
+  // Build adjacency (excluding self-loops)
+  const adj = new Map<string, string[]>();
+  const inEdges = new Map<string, string[]>();
   for (const id of ids) {
-    if (!visited.has(id)) {
-      spine.push(id);
+    adj.set(id, []);
+    inEdges.set(id, []);
+  }
+  // Detect back-edges via DFS to break cycles
+  const backEdges = new Set<string>();
+  {
+    const WHITE = 0;
+    const GRAY = 1;
+    const BLACK = 2;
+    const color = new Map<string, number>();
+    for (const id of ids) color.set(id, WHITE);
+
+    // Temporary full adjacency for cycle detection
+    const fullAdj = new Map<string, string[]>();
+    for (const id of ids) fullAdj.set(id, []);
+    for (const e of edges) {
+      if (e.from !== e.to) fullAdj.get(e.from)?.push(e.to);
+    }
+
+    function dfs(u: string): void {
+      color.set(u, GRAY);
+      for (const v of fullAdj.get(u) ?? []) {
+        const c = color.get(v) ?? WHITE;
+        if (c === GRAY) {
+          // Back-edge: u -> v where v is an ancestor
+          backEdges.add(`${u}->${v}`);
+        } else if (c === WHITE) {
+          dfs(v);
+        }
+      }
+      color.set(u, BLACK);
+    }
+
+    // Start DFS from __start__ first for determinism
+    if (ids.has(START_ID)) dfs(START_ID);
+    for (const id of ids) {
+      if ((color.get(id) ?? WHITE) === WHITE) dfs(id);
     }
   }
 
-  return spine;
+  // Build DAG adjacency (without back-edges)
+  for (const e of edges) {
+    if (e.from === e.to) continue;
+    if (backEdges.has(`${e.from}->${e.to}`)) continue;
+    adj.get(e.from)?.push(e.to);
+    inEdges.get(e.to)?.push(e.from);
+  }
+
+  // Longest-path ranking via topological order (Kahn's algorithm)
+  const inDegree = new Map<string, number>();
+  for (const id of ids) inDegree.set(id, 0);
+  for (const id of ids) {
+    for (const next of adj.get(id) ?? []) {
+      inDegree.set(next, (inDegree.get(next) ?? 0) + 1);
+    }
+  }
+
+  const rank = new Map<string, number>();
+  const queue: string[] = [];
+  for (const id of ids) {
+    if ((inDegree.get(id) ?? 0) === 0) {
+      queue.push(id);
+      rank.set(id, 0);
+    }
+  }
+
+  while (queue.length > 0) {
+    const cur = queue.shift()!;
+    const curRank = rank.get(cur) ?? 0;
+    for (const next of adj.get(cur) ?? []) {
+      // Longest path: take max
+      const prevRank = rank.get(next) ?? 0;
+      if (curRank + 1 > prevRank) {
+        rank.set(next, curRank + 1);
+      }
+      const deg = (inDegree.get(next) ?? 1) - 1;
+      inDegree.set(next, deg);
+      if (deg === 0) {
+        queue.push(next);
+      }
+    }
+  }
+
+  // Group by rank
+  const maxRank = Math.max(...[...rank.values()], 0);
+  const layers: string[][] = [];
+  for (let r = 0; r <= maxRank; r++) {
+    layers.push([]);
+  }
+  for (const [id, r] of rank) {
+    layers[r].push(id);
+  }
+
+  // Sort within layers alphabetically for stability, but __start__ first, __end__ last
+  for (const layer of layers) {
+    layer.sort((a, b) => {
+      if (a === START_ID) return -1;
+      if (b === START_ID) return 1;
+      if (a === END_ID) return 1;
+      if (b === END_ID) return -1;
+      return a.localeCompare(b);
+    });
+  }
+
+  // Remove empty layers
+  return layers.filter((l) => l.length > 0);
 }
 
+// ── Shared helpers ──────────────────────────────────────────────────
+
 function buildRoleNode(
   id: string,
   pos: { x: number; y: number },
@@ -137,83 +201,126 @@ function buildTerminalNode(
   };
 }
 
-function computeLayout(input: LayoutInput): LayoutResult {
-  const spine = extractSpine(input.edges);
+// ── Longest-path layout (uses same edge-building as before) ─────────
+
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: layout logic is inherently branchy
+function computeLayoutLongestPath(input: LayoutInput): LayoutResult {
+  const layers = computeLayersLongestPath(input.edges);
+
+  // Flatten layers into a rank map (layer index = rank)
   const rank = new Map<string, number>();
-  for (let i = 0; i < spine.length; i++) {
-    rank.set(spine[i], i);
+  for (let i = 0; i < layers.length; i++) {
+    for (const id of layers[i]) {
+      rank.set(id, i);
+    }
   }
 
-  // Position nodes along a vertical spine, centered horizontally
-  const centerX = ROLE_NODE_WIDTH / 2; // left edge at x=0, center at width/2
+  // Horizontal gap between nodes in the same layer
+  const H_GAP = 40;
+
+  // Position nodes: each layer is a horizontal row
   const nodePositions = new Map<string, { x: number; y: number; w: number; h: number }>();
 
+  // Find max layer width for centering
+  const layerWidths: number[] = [];
+  for (const layer of layers) {
+    let w = 0;
+    for (const id of layer) {
+      w += nodeSize(id).width;
+    }
+    w += (layer.length - 1) * H_GAP;
+    layerWidths.push(w);
+  }
+  const maxLayerWidth = Math.max(...layerWidths, ROLE_NODE_WIDTH);
+  const centerX = maxLayerWidth / 2;
+
   let y = 0;
-  for (const id of spine) {
-    const size = nodeSize(id);
-    // Center-align all nodes on the spine
-    const x = centerX - size.width / 2;
-    nodePositions.set(id, { x, y, w: size.width, h: size.height });
-    y += size.height + LAYER_GAP;
+  for (let li = 0; li < layers.length; li++) {
+    const layer = layers[li];
+    const totalWidth = layerWidths[li];
+    let x = centerX - totalWidth / 2;
+    let maxH = 0;
+    for (const id of layer) {
+      const size = nodeSize(id);
+      nodePositions.set(id, { x, y, w: size.width, h: size.height });
+      x += size.width + H_GAP;
+      if (size.height > maxH) maxH = size.height;
+    }
+    y += maxH + LAYER_GAP;
   }
 
   // Build nodes
   const nodes: Node[] = [];
-  for (const id of spine) {
-    const pos = nodePositions.get(id);
-    if (pos === undefined) continue;
-    const state = input.nodeStates.get(id) ?? "default";
-    if (id === START_ID || id === END_ID) {
-      nodes.push(buildTerminalNode(id, { x: pos.x, y: pos.y }, state));
-    } else {
-      nodes.push(buildRoleNode(id, { x: pos.x, y: pos.y }, input.roles, state));
+  for (const layer of layers) {
+    for (const id of layer) {
+      const pos = nodePositions.get(id);
+      if (pos === undefined) continue;
+      const state = input.nodeStates.get(id) ?? "default";
+      if (id === START_ID || id === END_ID) {
+        nodes.push(buildTerminalNode(id, { x: pos.x, y: pos.y }, state));
+      } else {
+        nodes.push(buildRoleNode(id, { x: pos.x, y: pos.y }, input.roles, state));
+      }
     }
   }
 
   // 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.
+  const routedCountByTarget = new Map<string, number>();
   const edges: Edge[] = input.edges.map((e) => {
     const isFallback = e.condition === "FALLBACK";
     const isSelfLoop = e.from === e.to;
     const sourceRank = rank.get(e.from) ?? 0;
     const targetRank = rank.get(e.to) ?? 0;
     const isFeedback = !isSelfLoop && targetRank <= sourceRank;
+    const isSkipForward = !isSelfLoop && !isFeedback && targetRank - sourceRank > 1;
 
     const sourcePos = nodePositions.get(e.from);
     const targetPos = nodePositions.get(e.to);
 
     let labelX: number | null = null;
     let labelY: number | null = null;
+    let feedbackSide: "right" | "left" | null = null;
 
     if (sourcePos !== undefined && targetPos !== undefined) {
-      if (isFeedback) {
-        // Label on the right side of the feedback arc
-        const rightX = centerX + ROLE_NODE_WIDTH / 2 + FEEDBACK_OFFSET_X;
+      if (isFeedback || isSkipForward) {
+        const count = routedCountByTarget.get(e.to) ?? 0;
+        routedCountByTarget.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;
         const midY = (sourcePos.y + sourcePos.h / 2 + targetPos.y + targetPos.h / 2) / 2;
-        labelX = rightX;
+        labelX = offsetX;
         labelY = midY;
       } else if (!isSelfLoop) {
-        // Forward edge: label between source bottom and target top
         const midX = centerX;
         const midY = (sourcePos.y + sourcePos.h + targetPos.y) / 2;
         labelX = midX;
         labelY = midY;
       }
-      // Self-loop: let ReactFlow default handle it
     }
 
     return {
       id: edgeKey(e),
       source: e.from,
       target: e.to,
+      sourceHandle:
+        isFeedback || isSkipForward
+          ? feedbackSide === "left"
+            ? "left-out"
+            : "right-out"
+          : "bottom-out",
+      targetHandle:
+        isFeedback || isSkipForward ? (feedbackSide === "left" ? "left-in" : "right-in") : "top-in",
       type: "condition",
       data: {
         condition: e.condition,
         conditionDescription: e.conditionDescription,
         isFallback,
-        isFeedback,
+        isFeedback: isFeedback || isSkipForward,
         isSelfLoop,
+        feedbackSide,
         labelX,
         labelY,
       },
@@ -223,6 +330,8 @@ function computeLayout(input: LayoutInput): LayoutResult {
   return { nodes, edges };
 }
 
+// ── Public hook ─────────────────────────────────────────────────────
+
 export function useLayout(input: LayoutInput): LayoutResult {
-  return useMemo(() => computeLayout(input), [input]);
+  return useMemo(() => computeLayoutLongestPath(input), [input]);
 }

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

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

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

@@ -4,36 +4,42 @@ type View = "threads" | "workflows";
 
 type HashRoute = {
   view: View;
-  agent: string | null;
+  client: string | null;
   threadId: string | null;
+  workflowName: string | null;
 };
 
 function parseHash(hash: string): HashRoute {
   const raw = hash.replace(/^#\/?/, "");
-  // Format: #agent/threads/id or #agent/workflows or #threads or #workflows
+  // Format: #client/threads/id or #client/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,
-      agent: null,
+      client: null,
       threadId: parts[0] === "threads" && parts.length > 1 ? parts.slice(1).join("/") : null,
+      workflowName: parts[0] === "workflows" && parts.length > 1 ? parts.slice(1).join("/") : null,
     };
   }
 
-  // First part is agent name
-  const agent = parts[0] || null;
+  // First part is client name
+  const client = 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;
+  const workflowName = view === "workflows" && parts.length > 2 ? parts.slice(2).join("/") : null;
 
-  return { view, agent, threadId };
+  return { view, client, threadId, workflowName };
 }
 
 function buildHash(route: HashRoute): string {
-  const prefix = route.agent ? `${route.agent}/` : "";
+  const prefix = route.client ? `${route.client}/` : "";
   if (route.view === "workflows") {
+    if (route.workflowName !== null) {
+      return `#${prefix}workflows/${route.workflowName}`;
+    }
     return `#${prefix}workflows`;
   }
   if (route.threadId !== null) {
@@ -44,11 +50,13 @@ function buildHash(route: HashRoute): string {
 
 export function useHashRoute(): {
   view: View;
-  agent: string | null;
+  client: string | null;
   threadId: string | null;
+  workflowName: string | null;
   setView: (v: View) => void;
-  setAgent: (a: string | null) => void;
+  setClient: (a: string | null) => void;
   setThreadId: (id: string | null) => void;
+  setWorkflowName: (name: string | null) => void;
 } {
   const [route, setRoute] = useState<HashRoute>(() => parseHash(window.location.hash));
 
@@ -67,26 +75,36 @@ export function useHashRoute(): {
   }, []);
 
   const setView = useCallback(
-    (v: View) => navigate({ view: v, agent: route.agent, threadId: null }),
-    [navigate, route.agent],
+    (v: View) => navigate({ view: v, client: route.client, threadId: null, workflowName: null }),
+    [navigate, route.client],
   );
 
-  const setAgent = useCallback(
-    (a: string | null) => navigate({ view: route.view, agent: a, threadId: null }),
+  const setClient = useCallback(
+    (a: string | null) =>
+      navigate({ view: route.view, client: a, threadId: null, workflowName: null }),
     [navigate, route.view],
   );
 
   const setThreadId = useCallback(
-    (id: string | null) => navigate({ view: "threads", agent: route.agent, threadId: id }),
-    [navigate, route.agent],
+    (id: string | null) =>
+      navigate({ view: "threads", client: route.client, threadId: id, workflowName: null }),
+    [navigate, route.client],
+  );
+
+  const setWorkflowName = useCallback(
+    (name: string | null) =>
+      navigate({ view: "workflows", client: route.client, threadId: null, workflowName: name }),
+    [navigate, route.client],
   );
 
   return {
     view: route.view,
-    agent: route.agent,
+    client: route.client,
     threadId: route.threadId,
+    workflowName: route.workflowName,
     setView,
-    setAgent,
+    setClient,
     setThreadId,
+    setWorkflowName,
   };
 }

packages/workflow-dashboard/src/use-sse.ts

@@ -57,17 +57,17 @@ function handleRecordEvent(ev: Event, ctx: RecordEventContext): void {
   ctx.cleanupEs();
 }
 
-function sseUrl(agent: string, threadId: string): string {
+function sseUrl(client: 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/${agent}/threads/${encodeURIComponent(threadId)}/live${keyParam}`;
+    return `${gatewayUrl}/api/${client}/threads/${encodeURIComponent(threadId)}/live${keyParam}`;
   }
   return `/api/threads/${encodeURIComponent(threadId)}/live`;
 }
 
-export function useSSE(agent: string | null, threadId: string | null): UseSSEReturn {
+export function useSSE(client: 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(agent: string | null, threadId: string | null): UseSSERet
   const reconnectAttemptsRef = useRef(0);
 
   useEffect(() => {
-    if (threadId === null || agent === null) {
+    if (threadId === null || client === null) {
       completedRef.current = false;
       reconnectAttemptsRef.current = 0;
       setRecords([]);
@@ -86,7 +86,7 @@ export function useSSE(agent: string | null, threadId: string | null): UseSSERet
     }
 
     const tid = threadId;
-    const agentName = agent;
+    const clientName = client;
 
     completedRef.current = false;
     reconnectAttemptsRef.current = 0;
@@ -125,7 +125,7 @@ export function useSSE(agent: string | null, threadId: string | null): UseSSERet
       }
 
       cleanupEs();
-      const url = sseUrl(agentName, tid);
+      const url = sseUrl(clientName, tid);
       es = new EventSource(url);
 
       es.onopen = () => {
@@ -177,7 +177,7 @@ export function useSSE(agent: string | null, threadId: string | null): UseSSERet
       }
       cleanupEs();
     };
-  }, [agent, threadId]);
+  }, [client, threadId]);
 
   return { records, connected, completed };
 }

packages/workflow-execute/CHANGELOG.md

@@ -1,5 +1,66 @@
 # @uncaged/workflow-execute
 
+## 0.5.0-alpha.4
+
+### Patch Changes
+
+- Updated dependencies
+- Updated dependencies [f74b482]
+- Updated dependencies [f74b482]
+  - @uncaged/workflow-util@0.5.0-alpha.4
+  - @uncaged/workflow-protocol@0.5.0-alpha.4
+  - @uncaged/workflow-cas@0.5.0-alpha.4
+  - @uncaged/workflow-reactor@0.5.0-alpha.4
+  - @uncaged/workflow-register@0.5.0-alpha.4
+  - @uncaged/workflow-runtime@0.5.0-alpha.4
+
+## 0.5.0-alpha.3
+
+### Patch Changes
+
+- Updated dependencies
+  - @uncaged/workflow-protocol@0.5.0-alpha.3
+  - @uncaged/workflow-cas@0.5.0-alpha.3
+  - @uncaged/workflow-reactor@0.5.0-alpha.3
+  - @uncaged/workflow-register@0.5.0-alpha.3
+  - @uncaged/workflow-runtime@0.5.0-alpha.3
+  - @uncaged/workflow-util@0.5.0-alpha.3
+
+## 0.5.0-alpha.2
+
+### Patch Changes
+
+- Updated dependencies
+  - @uncaged/workflow-protocol@0.5.0-alpha.2
+  - @uncaged/workflow-cas@0.5.0-alpha.2
+  - @uncaged/workflow-reactor@0.5.0-alpha.2
+  - @uncaged/workflow-register@0.5.0-alpha.2
+  - @uncaged/workflow-runtime@0.5.0-alpha.2
+  - @uncaged/workflow-util@0.5.0-alpha.2
+
+## 0.5.0-alpha.1
+
+### Patch Changes
+
+- @uncaged/workflow-cas@0.5.0-alpha.1
+- @uncaged/workflow-protocol@0.5.0-alpha.1
+- @uncaged/workflow-reactor@0.5.0-alpha.1
+- @uncaged/workflow-register@0.5.0-alpha.1
+- @uncaged/workflow-runtime@0.5.0-alpha.1
+- @uncaged/workflow-util@0.5.0-alpha.1
+
+## 0.5.0-alpha.0
+
+### Patch Changes
+
+- Updated dependencies
+  - @uncaged/workflow-protocol@0.5.0-alpha.0
+  - @uncaged/workflow-cas@0.5.0-alpha.0
+  - @uncaged/workflow-reactor@0.5.0-alpha.0
+  - @uncaged/workflow-register@0.5.0-alpha.0
+  - @uncaged/workflow-runtime@0.5.0-alpha.0
+  - @uncaged/workflow-util@0.5.0-alpha.0
+
 ## 0.4.5
 
 ### Patch Changes

packages/workflow-execute/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uncaged/workflow-execute",
-  "version": "0.4.5",
+  "version": "0.5.0-alpha.4",
   "files": [
     "src",
     "dist",

packages/workflow-gateway/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @uncaged/workflow-gateway
 
+## 0.5.0-alpha.4
+
+## 0.5.0-alpha.3
+
+## 0.5.0-alpha.2
+
+## 0.5.0-alpha.1
+
+## 0.5.0-alpha.0
+
 ## 0.4.5
 
 ## 0.4.4

packages/workflow-gateway/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uncaged/workflow-gateway",
-  "version": "0.4.5",
+  "version": "0.5.0-alpha.4",
   "files": [
     "src",
     "dist",

packages/workflow-gateway/src/client-socket.ts

@@ -1,14 +1,14 @@
-/** One Durable Object instance per agent name; holds the reverse WebSocket from the agent CLI. */
+/** One Durable Object instance per client name; holds the reverse WebSocket from the client CLI. */
 import { DurableObject } from "cloudflare:workers";
 
 import { parseWsRequestJson, parseWsResponseJson, type WsResponse } from "./ws-protocol.js";
 
-type AgentSocketEnv = {
-  GATEWAY_SECRET: string;
+type ClientSocketEnv = {
+  WORKFLOW_DASHBOARD_SECRET: string;
 };
 
-export const AGENT_SOCKET_INTERNAL_STATUS_PATH = "/internal/agent-socket/status";
-export const AGENT_SOCKET_INTERNAL_PROXY_PATH = "/internal/agent-socket/proxy";
+export const CLIENT_SOCKET_INTERNAL_STATUS_PATH = "/internal/client-socket/status";
+export const CLIENT_SOCKET_INTERNAL_PROXY_PATH = "/internal/client-socket/proxy";
 
 const PROXY_TIMEOUT_MS = 30_000;
 
@@ -32,12 +32,12 @@ function wsResponseToHttp(wr: WsResponse): Response {
   return new Response(wr.body, { status: wr.status, headers });
 }
 
-export class AgentSocket extends DurableObject<AgentSocketEnv> {
+export class ClientSocket extends DurableObject<ClientSocketEnv> {
   private readonly pending = new Map<string, PendingEntry>();
 
   private requireAuth(request: Request): Response | null {
     const auth = request.headers.get("Authorization");
-    if (auth !== `Bearer ${this.env.GATEWAY_SECRET}`) {
+    if (auth !== `Bearer ${this.env.WORKFLOW_DASHBOARD_SECRET}`) {
       return jsonResponse(401, { error: "unauthorized" });
     }
     return null;
@@ -100,11 +100,11 @@ export class AgentSocket extends DurableObject<AgentSocketEnv> {
   async fetch(request: Request): Promise<Response> {
     const url = new URL(request.url);
 
-    if (url.pathname === AGENT_SOCKET_INTERNAL_STATUS_PATH && request.method === "GET") {
+    if (url.pathname === CLIENT_SOCKET_INTERNAL_STATUS_PATH && request.method === "GET") {
       return this.handleStatusGet(request);
     }
 
-    if (url.pathname === AGENT_SOCKET_INTERNAL_PROXY_PATH && request.method === "POST") {
+    if (url.pathname === CLIENT_SOCKET_INTERNAL_PROXY_PATH && request.method === "POST") {
       return this.handleProxyPost(request);
     }
 
@@ -144,11 +144,11 @@ export class AgentSocket extends DurableObject<AgentSocketEnv> {
     _reason: string,
     _wasClean: boolean,
   ): Promise<void> {
-    this.rejectAllPending("agent websocket closed");
+    this.rejectAllPending("client websocket closed");
   }
 
   async webSocketError(_ws: WebSocket, _error: unknown): Promise<void> {
-    this.rejectAllPending("agent websocket error");
+    this.rejectAllPending("client websocket error");
   }
 
   private rejectAllPending(message: string): void {

packages/workflow-gateway/src/index.ts

@@ -2,27 +2,26 @@ import { Hono } from "hono";
 import { cors } from "hono/cors";
 
 import {
-  AGENT_SOCKET_INTERNAL_PROXY_PATH,
-  AGENT_SOCKET_INTERNAL_STATUS_PATH,
-  AgentSocket,
-} from "./agent-socket.js";
+  CLIENT_SOCKET_INTERNAL_PROXY_PATH,
+  CLIENT_SOCKET_INTERNAL_STATUS_PATH,
+  ClientSocket,
+} from "./client-socket.js";
 import type { WsRequest } from "./ws-protocol.js";
 
-export { AgentSocket };
+export { ClientSocket };
 
 type Env = {
   Bindings: {
     ENDPOINTS: KVNamespace;
-    GATEWAY_SECRET: string;
-    DASHBOARD_API_KEY: string;
-    AGENT_SOCKET: DurableObjectNamespace<AgentSocket>;
+    WORKFLOW_DASHBOARD_SECRET: string;
+    CLIENT_SOCKET: DurableObjectNamespace<ClientSocket>;
   };
 };
 
 type EndpointRecord = {
   name: string;
   url: string;
-  agentToken: string;
+  clientToken: string;
   registeredAt: number;
   lastHeartbeat: number;
 };
@@ -40,10 +39,10 @@ function checkDashboardAuth(c: {
   const bearer = c.req.header("Authorization")?.replace("Bearer ", "");
   const query = c.req.query("key");
   const key = bearer ?? query;
-  return key === c.env.DASHBOARD_API_KEY;
+  return key === c.env.WORKFLOW_DASHBOARD_SECRET;
 }
 
-function isLocalAgentUrl(url: string): boolean {
+function isLocalClientUrl(url: string): boolean {
   try {
     const u = new URL(url);
     return u.hostname === "localhost" || u.hostname === "127.0.0.1";
@@ -52,7 +51,7 @@ function isLocalAgentUrl(url: string): boolean {
   }
 }
 
-function buildForwardHeaders(raw: Headers, agentToken: string): Record<string, string> {
+function buildForwardHeaders(raw: Headers, clientToken: string): Record<string, string> {
   const out: Record<string, string> = {};
   for (const [key, value] of raw) {
     const lower = key.toLowerCase();
@@ -70,8 +69,8 @@ function buildForwardHeaders(raw: Headers, agentToken: string): Record<string, s
     }
     out[key] = value;
   }
-  if (agentToken !== "") {
-    out["X-Agent-Token"] = agentToken;
+  if (clientToken !== "") {
+    out["X-Client-Token"] = clientToken;
   }
   return out;
 }
@@ -81,7 +80,7 @@ function buildDashboardProxyHeaders(raw: Headers, token: string): Headers {
   headers.delete("host");
   headers.delete("Authorization");
   if (token !== "") {
-    headers.set("X-Agent-Token", token);
+    headers.set("X-Client-Token", token);
   }
   return headers;
 }
@@ -94,15 +93,15 @@ async function readBodyForWsProxy(method: string, req: Request): Promise<string
   return buf.byteLength === 0 ? null : new TextDecoder().decode(buf);
 }
 
-async function fetchThroughAgentSocket(
+async function fetchThroughClientSocket(
   bindings: Env["Bindings"],
-  agent: string,
+  client: string,
   gateSecret: string,
   wsRequest: WsRequest,
 ): Promise<Response> {
-  const stub = bindings.AGENT_SOCKET.get(bindings.AGENT_SOCKET.idFromName(agent));
+  const stub = bindings.CLIENT_SOCKET.get(bindings.CLIENT_SOCKET.idFromName(client));
   return stub.fetch(
-    new Request(`https://do.internal${AGENT_SOCKET_INTERNAL_PROXY_PATH}`, {
+    new Request(`https://do.internal${CLIENT_SOCKET_INTERNAL_PROXY_PATH}`, {
       method: "POST",
       headers: {
         Authorization: `Bearer ${gateSecret}`,
@@ -113,7 +112,7 @@ async function fetchThroughAgentSocket(
   );
 }
 
-async function fetchAgentWithRecordHeaders(
+async function fetchClientWithRecordHeaders(
   targetUrl: string,
   method: string,
   forwardRecord: Record<string, string>,
@@ -130,7 +129,7 @@ async function fetchAgentWithRecordHeaders(
   });
 }
 
-async function fetchAgentWithDashboardHeaders(
+async function fetchClientWithDashboardHeaders(
   targetUrl: string,
   method: string,
   headers: Headers,
@@ -143,17 +142,17 @@ async function fetchAgentWithDashboardHeaders(
   });
 }
 
-async function fetchAgentSocketStatus(
+async function fetchClientSocketStatus(
   env: Env["Bindings"],
   name: string,
 ): Promise<{ ok: true; connected: boolean } | { ok: false }> {
   try {
-    const id = env.AGENT_SOCKET.idFromName(name);
-    const stub = env.AGENT_SOCKET.get(id);
+    const id = env.CLIENT_SOCKET.idFromName(name);
+    const stub = env.CLIENT_SOCKET.get(id);
     const resp = await stub.fetch(
-      new Request(`https://do${AGENT_SOCKET_INTERNAL_STATUS_PATH}`, {
+      new Request(`https://do${CLIENT_SOCKET_INTERNAL_STATUS_PATH}`, {
         method: "GET",
-        headers: { Authorization: `Bearer ${env.GATEWAY_SECRET}` },
+        headers: { Authorization: `Bearer ${env.WORKFLOW_DASHBOARD_SECRET}` },
       }),
     );
     if (!resp.ok) {
@@ -171,7 +170,7 @@ function endpointStatusFromKvAndDo(record: EndpointRecord, doConnected: boolean
     return "online";
   }
   if (doConnected === false) {
-    if (isLocalAgentUrl(record.url)) {
+    if (isLocalClientUrl(record.url)) {
       return "offline";
     }
     const age = Date.now() - record.lastHeartbeat;
@@ -184,25 +183,25 @@ function endpointStatusFromKvAndDo(record: EndpointRecord, doConnected: boolean
 // ── Health ──────────────────────────────────────────────────────────
 app.get("/healthz", (c) => c.json({ ok: true }));
 
-// ── Agent reverse WebSocket (GATEWAY_SECRET query param) ────────────
+// ── Client reverse WebSocket (WORKFLOW_DASHBOARD_SECRET query param) ────────────
 app.get("/ws/connect", async (c) => {
   const secret = c.req.query("secret");
   const name = c.req.query("name");
   if (name === undefined || name === "") {
     return c.json({ error: "name required" }, 400);
   }
-  if (secret !== c.env.GATEWAY_SECRET) {
+  if (secret !== c.env.WORKFLOW_DASHBOARD_SECRET) {
     return c.json({ error: "unauthorized" }, 401);
   }
   if (c.req.header("Upgrade") !== "websocket") {
     return c.text("expected WebSocket upgrade", 426);
   }
-  const id = c.env.AGENT_SOCKET.idFromName(name);
-  const stub = c.env.AGENT_SOCKET.get(id);
+  const id = c.env.CLIENT_SOCKET.idFromName(name);
+  const stub = c.env.CLIENT_SOCKET.get(id);
   return stub.fetch(c.req.raw);
 });
 
-// ── Gateway management (GATEWAY_SECRET auth) ────────────────────────
+// ── Gateway management (WORKFLOW_DASHBOARD_SECRET auth) ────────────────────────
 const gateway = new Hono<Env>();
 
 gateway.post("/register", async (c) => {
@@ -210,14 +209,14 @@ gateway.post("/register", async (c) => {
     name?: string;
     url?: string;
     secret?: string;
-    agentToken?: string;
+    clientToken?: string;
   }>();
-  const { name, url, secret, agentToken } = body;
+  const { name, url, secret, clientToken } = body;
 
   if (!name || !url) {
     return c.json({ error: "name and url required" }, 400);
   }
-  if (secret !== c.env.GATEWAY_SECRET) {
+  if (secret !== c.env.WORKFLOW_DASHBOARD_SECRET) {
     return c.json({ error: "unauthorized" }, 401);
   }
 
@@ -227,7 +226,7 @@ gateway.post("/register", async (c) => {
   const record: EndpointRecord = {
     name,
     url: url.replace(/\/+$/, ""), // strip trailing slash
-    agentToken: agentToken ?? existing?.agentToken ?? "",
+    clientToken: clientToken ?? existing?.clientToken ?? "",
     registeredAt: existing?.registeredAt ?? now,
     lastHeartbeat: now,
   };
@@ -242,7 +241,7 @@ gateway.post("/register", async (c) => {
 
 gateway.delete("/register/:name", async (c) => {
   const auth = c.req.header("Authorization");
-  if (auth !== `Bearer ${c.env.GATEWAY_SECRET}`) {
+  if (auth !== `Bearer ${c.env.WORKFLOW_DASHBOARD_SECRET}`) {
     return c.json({ error: "unauthorized" }, 401);
   }
 
@@ -261,7 +260,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 fetchAgentSocketStatus(c.env, record.name);
+      const doStatus = await fetchClientSocketStatus(c.env, record.name);
       const doConnected = doStatus.ok ? doStatus.connected : null;
       endpoints.push({
         name: record.name,
@@ -277,25 +276,25 @@ gateway.get("/endpoints", async (c) => {
 
 app.route("/api/gateway", gateway);
 
-// ── API proxy: /api/agents/:agent/* → WebSocket (preferred) or agent tunnel URL (dashboard auth) ──
-app.all("/api/agents/:agent/*", async (c) => {
+// ── API proxy: /api/clients/:client/* → WebSocket (preferred) or client tunnel URL (dashboard auth) ──
+app.all("/api/clients/:client/*", async (c) => {
   if (!checkDashboardAuth(c)) return c.json({ error: "unauthorized" }, 401);
-  const agent = c.req.param("agent");
-  const record = await c.env.ENDPOINTS.get<EndpointRecord>(agent, "json");
+  const client = c.req.param("client");
+  const record = await c.env.ENDPOINTS.get<EndpointRecord>(client, "json");
 
   if (!record) {
-    return c.json({ error: "agent not found" }, 404);
+    return c.json({ error: "client not found" }, 404);
   }
 
   const url = new URL(c.req.url);
-  const pathAfterAgent = url.pathname.replace(`/api/agents/${agent}`, "");
-  const targetUrl = `${record.url}/api${pathAfterAgent}${url.search}`;
-  const proxyPath = `/api${pathAfterAgent}${url.search}`;
+  const pathAfterClient = url.pathname.replace(`/api/clients/${client}`, "");
+  const targetUrl = `${record.url}/api${pathAfterClient}${url.search}`;
+  const proxyPath = `/api${pathAfterClient}${url.search}`;
   const method = c.req.method;
-  const token = record.agentToken ?? "";
+  const token = record.clientToken ?? "";
   const forwardRecord = buildForwardHeaders(c.req.raw.headers, token);
 
-  const doStatus = await fetchAgentSocketStatus(c.env, agent);
+  const doStatus = await fetchClientSocketStatus(c.env, client);
   if (doStatus.ok && doStatus.connected) {
     const bodyStr = await readBodyForWsProxy(method, c.req.raw);
     const wsRequest: WsRequest = {
@@ -305,7 +304,12 @@ app.all("/api/agents/:agent/*", async (c) => {
       headers: forwardRecord,
       body: bodyStr,
     };
-    const proxyResp = await fetchThroughAgentSocket(c.env, agent, c.env.GATEWAY_SECRET, wsRequest);
+    const proxyResp = await fetchThroughClientSocket(
+      c.env,
+      client,
+      c.env.WORKFLOW_DASHBOARD_SECRET,
+      wsRequest,
+    );
     if (proxyResp.status !== 503) {
       return new Response(proxyResp.body, {
         status: proxyResp.status,
@@ -313,25 +317,25 @@ app.all("/api/agents/:agent/*", async (c) => {
       });
     }
     try {
-      const resp = await fetchAgentWithRecordHeaders(targetUrl, method, forwardRecord, bodyStr);
+      const resp = await fetchClientWithRecordHeaders(targetUrl, method, forwardRecord, bodyStr);
       return new Response(resp.body, {
         status: resp.status,
         headers: resp.headers,
       });
     } catch (err) {
-      return c.json({ error: "agent unreachable", detail: String(err) }, 502);
+      return c.json({ error: "client unreachable", detail: String(err) }, 502);
     }
   }
 
   const headers = buildDashboardProxyHeaders(c.req.raw.headers, token);
   try {
-    const resp = await fetchAgentWithDashboardHeaders(targetUrl, method, headers, c.req.raw.body);
+    const resp = await fetchClientWithDashboardHeaders(targetUrl, method, headers, c.req.raw.body);
     return new Response(resp.body, {
       status: resp.status,
       headers: resp.headers,
     });
   } catch (err) {
-    return c.json({ error: "agent unreachable", detail: String(err) }, 502);
+    return c.json({ error: "client unreachable", detail: String(err) }, 502);
   }
 });
 

packages/workflow-gateway/wrangler.toml

@@ -7,10 +7,14 @@ binding = "ENDPOINTS"
 id = "88b118d1cfab4c049f9c1684848811a3"
 
 [durable_objects]
-bindings = [{ name = "AGENT_SOCKET", class_name = "AgentSocket" }]
+bindings = [{ name = "CLIENT_SOCKET", class_name = "ClientSocket" }]
 
 [[migrations]]
 tag = "add-agent-socket"
 new_sqlite_classes = ["AgentSocket"]
 
-# GATEWAY_SECRET is set via `wrangler secret put`
+[[migrations]]
+tag = "rename-agent-to-client"
+renamed_classes = [{ from = "AgentSocket", to = "ClientSocket" }]
+
+# WORKFLOW_DASHBOARD_SECRET is set via `wrangler secret put`

packages/workflow-protocol/CHANGELOG.md

@@ -1,5 +1,32 @@
 # @uncaged/workflow-protocol
 
+## 0.5.0-alpha.4
+
+### Patch Changes
+
+- f74b482: fix: correct internal dependency versions for prerelease
+- f74b482: fix: use npm publish with pinned deps instead of bun publish (workspace:^ resolution bug)
+
+## 0.5.0-alpha.3
+
+### Patch Changes
+
+- fix: use npm publish with pinned deps instead of bun publish (workspace:^ resolution bug)
+
+## 0.5.0-alpha.2
+
+### Patch Changes
+
+- fix: correct internal dependency versions for prerelease
+
+## 0.5.0-alpha.1
+
+## 0.5.0-alpha.0
+
+### Minor Changes
+
+- feat: AgentFn<Opt> type boundary and createAgentAdapter bridging function (RFC #252)
+
 ## 0.4.5
 
 ### Patch Changes

packages/workflow-protocol/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uncaged/workflow-protocol",
-  "version": "0.4.5",
+  "version": "0.5.0-alpha.4",
   "files": [
     "src",
     "dist",

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

@@ -24,6 +24,7 @@ export type WorkflowRoleSchema = Record<string, unknown>;
 
 export type WorkflowRoleDescriptor = {
   description: string;
+  systemPrompt: string;
   schema: WorkflowRoleSchema;
 };
 
@@ -151,6 +152,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-reactor/CHANGELOG.md

@@ -1,5 +1,40 @@
 # @uncaged/workflow-reactor
 
+## 0.5.0-alpha.4
+
+### Patch Changes
+
+- Updated dependencies [f74b482]
+- Updated dependencies [f74b482]
+  - @uncaged/workflow-protocol@0.5.0-alpha.4
+
+## 0.5.0-alpha.3
+
+### Patch Changes
+
+- Updated dependencies
+  - @uncaged/workflow-protocol@0.5.0-alpha.3
+
+## 0.5.0-alpha.2
+
+### Patch Changes
+
+- Updated dependencies
+  - @uncaged/workflow-protocol@0.5.0-alpha.2
+
+## 0.5.0-alpha.1
+
+### Patch Changes
+
+- @uncaged/workflow-protocol@0.5.0-alpha.1
+
+## 0.5.0-alpha.0
+
+### Patch Changes
+
+- Updated dependencies
+  - @uncaged/workflow-protocol@0.5.0-alpha.0
+
 ## 0.4.5
 
 ### Patch Changes

packages/workflow-reactor/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uncaged/workflow-reactor",
-  "version": "0.4.5",
+  "version": "0.5.0-alpha.4",
   "files": [
     "src",
     "dist",

packages/workflow-register/CHANGELOG.md

@@ -1,5 +1,46 @@
 # @uncaged/workflow-register
 
+## 0.5.0-alpha.4
+
+### Patch Changes
+
+- Updated dependencies
+- Updated dependencies [f74b482]
+- Updated dependencies [f74b482]
+  - @uncaged/workflow-util@0.5.0-alpha.4
+  - @uncaged/workflow-protocol@0.5.0-alpha.4
+
+## 0.5.0-alpha.3
+
+### Patch Changes
+
+- Updated dependencies
+  - @uncaged/workflow-protocol@0.5.0-alpha.3
+  - @uncaged/workflow-util@0.5.0-alpha.3
+
+## 0.5.0-alpha.2
+
+### Patch Changes
+
+- Updated dependencies
+  - @uncaged/workflow-protocol@0.5.0-alpha.2
+  - @uncaged/workflow-util@0.5.0-alpha.2
+
+## 0.5.0-alpha.1
+
+### Patch Changes
+
+- @uncaged/workflow-protocol@0.5.0-alpha.1
+- @uncaged/workflow-util@0.5.0-alpha.1
+
+## 0.5.0-alpha.0
+
+### Patch Changes
+
+- Updated dependencies
+  - @uncaged/workflow-protocol@0.5.0-alpha.0
+  - @uncaged/workflow-util@0.5.0-alpha.0
+
 ## 0.4.5
 
 ### Patch Changes

packages/workflow-register/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uncaged/workflow-register",
-  "version": "0.4.5",
+  "version": "0.5.0-alpha.4",
   "files": [
     "src",
     "dist",

packages/workflow-register/src/bundle/build-descriptor.ts

@@ -35,11 +35,12 @@ export function buildDescriptor<M extends RoleMeta>(
 ): WorkflowDescriptor {
   const roles: WorkflowDescriptor["roles"] = {};
   for (const [key, roleDef] of Object.entries(def.roles) as Array<
-    [string, { description: string; schema: z.ZodType }]
+    [string, { description: string; systemPrompt: string; schema: z.ZodType }]
   >) {
     const rawJsonSchema = z.toJSONSchema(roleDef.schema) as Record<string, unknown>;
     roles[key] = {
       description: roleDef.description,
+      systemPrompt: roleDef.systemPrompt,
       schema: stripJsonSchemaMeta(rawJsonSchema),
     };
   }

packages/workflow-register/src/bundle/bundle-validator.ts

@@ -37,9 +37,6 @@ function isAllowedImportSpecifier(spec: string): boolean {
   if (spec.startsWith(".") || spec.startsWith("/") || spec.startsWith("file:")) {
     return false;
   }
-  if (spec.startsWith("@uncaged/workflow")) {
-    return true;
-  }
   return isBuiltin(spec);
 }
 
@@ -294,7 +291,7 @@ function validateImportDeclaration(node: ImportDeclaration): string | null {
     return "only static string import specifiers are allowed";
   }
   if (!isAllowedImportSpecifier(spec)) {
-    return `disallowed import specifier "${spec}" (only Node built-ins and @uncaged/workflow-* packages are allowed)`;
+    return `disallowed import specifier "${spec}" (only Node built-ins are allowed; all other dependencies must be bundled)`;
   }
   return null;
 }
@@ -309,7 +306,7 @@ function validateExportSource(
     return staticMessage;
   }
   if (!isAllowedImportSpecifier(spec)) {
-    return `${disallowedPrefix} "${spec}" (only Node built-ins and @uncaged/workflow-* packages are allowed)`;
+    return `${disallowedPrefix} "${spec}" (only Node built-ins are allowed; all other dependencies must be bundled)`;
   }
   return null;
 }

packages/workflow-register/src/bundle/workflow-descriptor.ts

@@ -88,8 +88,10 @@ export function validateWorkflowDescriptor(value: unknown): Result<WorkflowDescr
     if (schema === null || typeof schema !== "object" || Array.isArray(schema)) {
       return err(`descriptor.roles.${roleName}.schema must be a non-array object`);
     }
+    const systemPrompt = typeof spec.systemPrompt === "string" ? spec.systemPrompt : "";
     roles[roleName] = {
       description: roleDesc,
+      systemPrompt,
       schema: schema as WorkflowRoleSchema,
     };
   }

packages/workflow-runtime/CHANGELOG.md

@@ -1,5 +1,45 @@
 # @uncaged/workflow-runtime
 
+## 0.5.0-alpha.4
+
+### Patch Changes
+
+- Updated dependencies [f74b482]
+- Updated dependencies [f74b482]
+  - @uncaged/workflow-protocol@0.5.0-alpha.4
+  - @uncaged/workflow-cas@0.5.0-alpha.4
+
+## 0.5.0-alpha.3
+
+### Patch Changes
+
+- Updated dependencies
+  - @uncaged/workflow-protocol@0.5.0-alpha.3
+  - @uncaged/workflow-cas@0.5.0-alpha.3
+
+## 0.5.0-alpha.2
+
+### Patch Changes
+
+- Updated dependencies
+  - @uncaged/workflow-protocol@0.5.0-alpha.2
+  - @uncaged/workflow-cas@0.5.0-alpha.2
+
+## 0.5.0-alpha.1
+
+### Patch Changes
+
+- @uncaged/workflow-cas@0.5.0-alpha.1
+- @uncaged/workflow-protocol@0.5.0-alpha.1
+
+## 0.5.0-alpha.0
+
+### Patch Changes
+
+- Updated dependencies
+  - @uncaged/workflow-protocol@0.5.0-alpha.0
+  - @uncaged/workflow-cas@0.5.0-alpha.0
+
 ## 0.4.5
 
 ### Patch Changes

packages/workflow-runtime/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uncaged/workflow-runtime",
-  "version": "0.4.5",
+  "version": "0.5.0-alpha.4",
   "files": [
     "src",
     "dist",

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/CHANGELOG.md

@@ -1,5 +1,40 @@
 # @uncaged/workflow-template-develop
 
+## 0.5.0-alpha.4
+
+### Patch Changes
+
+- @uncaged/workflow-register@0.5.0-alpha.4
+- @uncaged/workflow-runtime@0.5.0-alpha.4
+
+## 0.5.0-alpha.3
+
+### Patch Changes
+
+- @uncaged/workflow-register@0.5.0-alpha.3
+- @uncaged/workflow-runtime@0.5.0-alpha.3
+
+## 0.5.0-alpha.2
+
+### Patch Changes
+
+- @uncaged/workflow-register@0.5.0-alpha.2
+- @uncaged/workflow-runtime@0.5.0-alpha.2
+
+## 0.5.0-alpha.1
+
+### Patch Changes
+
+- @uncaged/workflow-register@0.5.0-alpha.1
+- @uncaged/workflow-runtime@0.5.0-alpha.1
+
+## 0.5.0-alpha.0
+
+### Patch Changes
+
+- @uncaged/workflow-register@0.5.0-alpha.0
+- @uncaged/workflow-runtime@0.5.0-alpha.0
+
 ## 0.4.5
 
 ### Patch Changes

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

@@ -1,33 +1,35 @@
 /**
  * develop bundle entry — 小橘 🍊
  *
- * All roles use cursor-agent with workspace auto-extracted from context.
+ * planner/coder/reviewer → cursor-agent (needs code editing)
+ * tester/committer → hermes-agent (lightweight, no editing needed)
  */
 import { createCursorAgent } from "@uncaged/workflow-agent-cursor";
+import { createHermesAgent } from "@uncaged/workflow-agent-hermes";
 import { createWorkflow } from "@uncaged/workflow-runtime";
-import { optionalEnv, requireEnv } from "@uncaged/workflow-util";
+import { env } 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"),
-  timeout: optionalEnv("WORKFLOW_CURSOR_TIMEOUT")
-    ? Number(optionalEnv("WORKFLOW_CURSOR_TIMEOUT"))
-    : 0,
+const cursorAdapter = createCursorAgent({
+  command: env("WORKFLOW_CURSOR_COMMAND", "/home/azureuser/.local/bin/cursor-agent"),
+  model: env("WORKFLOW_CURSOR_MODEL", "auto"),
+  timeout: Number(env("WORKFLOW_CURSOR_TIMEOUT", "0")),
   workspace: null,
-  llmProvider,
 });
 
-const wf = createWorkflow(developWorkflowDefinition, { adapter, overrides: null });
+const hermesAdapter = createHermesAgent({
+  command: env("WORKFLOW_HERMES_COMMAND", "/home/azureuser/.local/bin/hermes"),
+  model: env("WORKFLOW_HERMES_MODEL", "") || null,
+  timeout: Number(env("WORKFLOW_HERMES_TIMEOUT", "0")) || null,
+});
+
+const wf = createWorkflow(developWorkflowDefinition, {
+  adapter: cursorAdapter,
+  overrides: {
+    tester: hermesAdapter,
+    committer: hermesAdapter,
+  },
+});
 
 export const descriptor = buildDevelopDescriptor();
 export const run = wf;

packages/workflow-template-develop/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uncaged/workflow-template-develop",
-  "version": "0.4.5",
+  "version": "0.5.0-alpha.4",
   "files": [
     "src",
     "dist",

packages/workflow-template-solve-issue/CHANGELOG.md

@@ -1,5 +1,40 @@
 # @uncaged/workflow-template-solve-issue
 
+## 0.5.0-alpha.4
+
+### Patch Changes
+
+- @uncaged/workflow-register@0.5.0-alpha.4
+- @uncaged/workflow-runtime@0.5.0-alpha.4
+
+## 0.5.0-alpha.3
+
+### Patch Changes
+
+- @uncaged/workflow-register@0.5.0-alpha.3
+- @uncaged/workflow-runtime@0.5.0-alpha.3
+
+## 0.5.0-alpha.2
+
+### Patch Changes
+
+- @uncaged/workflow-register@0.5.0-alpha.2
+- @uncaged/workflow-runtime@0.5.0-alpha.2
+
+## 0.5.0-alpha.1
+
+### Patch Changes
+
+- @uncaged/workflow-register@0.5.0-alpha.1
+- @uncaged/workflow-runtime@0.5.0-alpha.1
+
+## 0.5.0-alpha.0
+
+### Patch Changes
+
+- @uncaged/workflow-register@0.5.0-alpha.0
+- @uncaged/workflow-runtime@0.5.0-alpha.0
+
 ## 0.4.5
 
 ### Patch Changes

packages/workflow-template-solve-issue/bundle-entry.ts

@@ -7,14 +7,13 @@
 import { createHermesAgent } from "@uncaged/workflow-agent-hermes";
 import { workflowAdapter } from "@uncaged/workflow-execute";
 import { createWorkflow } from "@uncaged/workflow-runtime";
-import { optionalEnv } from "@uncaged/workflow-util";
+import { env } from "@uncaged/workflow-util";
 import { buildSolveIssueDescriptor, solveIssueWorkflowDefinition } from "./src/index.js";
 
 const adapter = createHermesAgent({
-  model: optionalEnv("WORKFLOW_HERMES_MODEL"),
-  timeout: optionalEnv("WORKFLOW_HERMES_TIMEOUT")
-    ? Number(optionalEnv("WORKFLOW_HERMES_TIMEOUT"))
-    : null,
+  command: env("WORKFLOW_HERMES_COMMAND", "/home/azureuser/.local/bin/hermes"),
+  model: env("WORKFLOW_HERMES_MODEL", "") || null,
+  timeout: Number(env("WORKFLOW_HERMES_TIMEOUT", "0")) || null,
 });
 
 const wf = createWorkflow(solveIssueWorkflowDefinition, {

packages/workflow-template-solve-issue/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uncaged/workflow-template-solve-issue",
-  "version": "0.4.5",
+  "version": "0.5.0-alpha.4",
   "files": [
     "src",
     "dist",

packages/workflow-util-agent/CHANGELOG.md

@@ -1,5 +1,41 @@
 # @uncaged/workflow-util-agent
 
+## 0.5.0-alpha.4
+
+### Patch Changes
+
+- @uncaged/workflow-cas@0.5.0-alpha.4
+- @uncaged/workflow-runtime@0.5.0-alpha.4
+
+## 0.5.0-alpha.3
+
+### Patch Changes
+
+- @uncaged/workflow-cas@0.5.0-alpha.3
+- @uncaged/workflow-runtime@0.5.0-alpha.3
+
+## 0.5.0-alpha.2
+
+### Patch Changes
+
+- @uncaged/workflow-cas@0.5.0-alpha.2
+- @uncaged/workflow-runtime@0.5.0-alpha.2
+
+## 0.5.0-alpha.1
+
+### Patch Changes
+
+- fix: include create-agent-adapter.ts in published src
+  - @uncaged/workflow-cas@0.5.0-alpha.1
+  - @uncaged/workflow-runtime@0.5.0-alpha.1
+
+## 0.5.0-alpha.0
+
+### Patch Changes
+
+- @uncaged/workflow-cas@0.5.0-alpha.0
+- @uncaged/workflow-runtime@0.5.0-alpha.0
+
 ## 0.4.5
 
 ### Patch Changes

packages/workflow-util-agent/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uncaged/workflow-util-agent",
-  "version": "0.4.5",
+  "version": "0.5.0-alpha.4",
   "files": [
     "src",
     "dist",

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

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

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

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

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

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