refactor(dashboard): replace vertical layout with side-by-side graph+cards

Change thread-detail from vertical (graph on top, cards below) to a
side-by-side layout:
- Left panel (280px, sticky): workflow graph, always visible
- Right panel (flex-1, scrollable): record cards
- Remove collapsible GraphPanel wrapper
- Graph acts as navigation (click node → scroll to card)

Refs: workflow thread 06F1NX4C9ET6HPXJAH7CWWF8MR

docs/plans/2026-05-12-react-agent.md

@@ -1,191 +0,0 @@
-# workflow-agent-react — ReAct Agent Package
-
-**Status**: RFC v3
-**Author**: 小橘 🍊
-
-## Problem
-
-现有的 agent 包都依赖外部 CLI 进程：
-
-| Package | 机制 | 能力 |
-|---------|------|------|
-| `workflow-agent-hermes` | spawn `hermes chat` | 完整工具链（文件、终端、浏览器…） |
-| `workflow-agent-cursor` | spawn `cursor-agent` | IDE 级别代码编辑 |
-| `workflow-agent-llm` | 单轮 chat completion | 纯文本，无工具 |
-
-缺少一个 **内置 ReAct agent**：用 LLM + tool calling 循环执行任务，不依赖外部 CLI，工具集由调用方注入。
-
-## 核心设计变更：AdapterFn 替代 AgentFn
-
-### 现状的问题
-
-当前 `AgentFn` 返回 `string`，engine 再用额外一轮 LLM 调用 extract meta：
-
-```
-Agent(ctx) → string → Extract(string, schema) → meta   // 浪费一轮 LLM
-```
-
-### 新抽象：AdapterFn
-
-```typescript
-type RoleFn<T> = (ctx: ThreadContext) => Promise<T>;
-
-type AdapterFn = <T>(prompt: string, schema: z.ZodType<T>) => RoleFn<T>;
-```
-
-- **`prompt`** — role 的 system prompt，描述角色职责和输出要求
-- **`schema`** — role 的 meta schema，定义输出格式
-- **`ThreadContext`** — threadId, depth, bundleHash, start, steps
-
-prompt 和 schema 是一对：prompt 说"你要输出什么"，schema 定义"输出的格式"。它们属于 role definition，由 `createWorkflow` 在每个 role 执行时传给 adapter。
-
-### AgentContext 不再需要
-
-`AgentContext` 在 `ThreadContext` 上扩展了 `currentRole: { name, systemPrompt }`。prompt 现在直接传给 adapter，`AgentContext` 可以删除。
-
-### createWorkflow 签名变更
-
-```typescript
-// Before
-type AgentBinding = {
-  agent: AgentFn;
-  overrides: Partial<Record<string, AgentFn>> | null;
-};
-
-// After
-type AdapterBinding = {
-  adapter: AdapterFn;
-  overrides: Partial<Record<string, AdapterFn>> | null;
-};
-```
-
-engine 对每个 role 的执行逻辑：
-
-```typescript
-// Before
-const result = await agent({ ...threadCtx, currentRole: { name, systemPrompt } });
-const meta = await extract(result, role.metaSchema, provider);  // 额外一轮 LLM
-
-// After
-const roleFn = adapter(role.systemPrompt, role.metaSchema);
-const meta = await roleFn(threadCtx);  // 直接拿到类型安全的 T
-```
-
-## `createReactAdapter` — 复用 workflow-reactor
-
-AdapterFn 的终止条件是"拿到符合 schema 的 T"——和 `workflow-reactor` 的 `ThreadReactorFn` 完全一致。因此 react adapter 是对 reactor 的**薄包装**，不需要自己实现 ReAct 循环。
-
-```typescript
-import { createLlmFn, createThreadReactor } from "@uncaged/workflow-reactor";
-import type { ThreadContext, LlmProvider } from "@uncaged/workflow-protocol";
-import type { ToolDefinition } from "@uncaged/workflow-reactor";
-
-type ReactToolHandler = (name: string, args: string) => Promise<string>;
-
-type ReactAdapterConfig = {
-  provider: LlmProvider;
-  tools: readonly ToolDefinition[];
-  toolHandler: ReactToolHandler;
-  maxRounds: number;
-};
-
-function createReactAdapter(config: ReactAdapterConfig): AdapterFn {
-  return <T>(prompt: string, schema: z.ZodType<T>) => {
-    const reactor = createThreadReactor<ThreadContext>({
-      llm: createLlmFn(config.provider),
-      staticTools: config.tools,
-      structuredToolFromSchema: (s) => buildStructuredTool(s),
-      systemPromptForStructuredTool: () => prompt,
-      toolHandler: (call, ctx) =>
-        config.toolHandler(call.function.name, call.function.arguments),
-      maxRounds: config.maxRounds,
-    });
-
-    return async (ctx: ThreadContext): Promise<T> => {
-      const input = buildThreadInput(ctx);
-      const result = await reactor({ thread: ctx, input, schema });
-      if (!result.ok) throw new Error(result.error);
-      return result.value;
-    };
-  };
-}
-```
-
-整个包就是：**一个工厂函数 + 类型定义 + thread 输入构造**。
-
-## `agentToAdapter` — 向后兼容
-
-把现有 `AgentFn`（hermes/cursor）包装成 `AdapterFn`：
-
-```typescript
-function agentToAdapter(agent: AgentFn, extractProvider: LlmProvider): AdapterFn {
-  return <T>(prompt: string, schema: z.ZodType<T>): RoleFn<T> => {
-    return async (ctx: ThreadContext): Promise<T> => {
-      const agentCtx = { ...ctx, currentRole: { name: "agent", systemPrompt: prompt } };
-      const result = await agent(agentCtx);
-      const output = typeof result === "string" ? result : result.output;
-      return extract(output, schema, extractProvider);
-    };
-  };
-}
-```
-
-hermes/cursor agent 内部不改，bundle-entry 层多包一层即可。
-
-## 包结构
-
-```
-packages/workflow-agent-react/
-  src/
-    types.ts                 # ReactAdapterConfig, ReactToolHandler
-    create-react-adapter.ts  # AdapterFn 工厂（包装 reactor）
-    thread-input.ts          # ThreadContext → user message string
-    index.ts
-  __tests__/
-    create-react-adapter.test.ts
-  package.json
-```
-
-依赖：
-- `@uncaged/workflow-protocol` — `ThreadContext`, `LlmProvider`
-- `@uncaged/workflow-reactor` — `createLlmFn`, `createThreadReactor`, types
-
-## 影响范围
-
-### Breaking Changes
-
-| 改动 | 影响 |
-|------|------|
-| `AgentBinding` → `AdapterBinding` | `createWorkflow` 调用方（所有 bundle-entry） |
-| `AgentContext` 删除 | `buildAgentPrompt`（util-agent）改为接收 `ThreadContext` |
-| extract 从 engine 下沉到 adapter | `workflow-execute` 简化 |
-
-### 需修改的包
-
-1. `workflow-protocol` — 删除 `AgentContext`/`AgentFn`/`AgentFnResult`/`AgentBinding`，新增 `AdapterFn`/`RoleFn`/`AdapterBinding`
-2. `workflow-runtime` — 更新 re-export
-3. `workflow-execute` — engine 调用 `adapter(prompt, schema)` 替代 `agent(ctx) + extract`
-4. `workflow-util-agent` — `buildAgentPrompt` → `buildThreadInput`，接收 `ThreadContext`
-5. 所有 bundle-entry — `agent:` → `adapter:`
-
-### 不受影响
-
-- `workflow-cas` / `workflow-register` / `workflow-reactor` / `workflow-dashboard`
-- `workflow-agent-hermes` / `workflow-agent-cursor`（内部不改，外部用 `agentToAdapter` 包装）
-
-## Phases
-
-1. **Phase 1**: protocol 类型 + `createWorkflow` 签名变更 + `agentToAdapter`
-2. **Phase 2**: `workflow-agent-react` 包（包装 reactor）
-3. **Phase 3**: 工具集实现（read/write/patch/shell） + smoke test 闭环
-
-## 工具集（后续讨论）
-
-| 工具 | 说明 | 优先级 |
-|------|------|--------|
-| `read_file` | 读文件 | P0 |
-| `write_file` | 写文件 | P0 |
-| `patch_file` | find-and-replace 编辑 | P0 |
-| `shell_exec` | 执行 shell 命令 | P0 |
-| `search_files` | grep / find | P1 |
-| `list_files` | ls | P1 |

packages/cli-workflow/package.json

@@ -6,6 +6,7 @@
     "uncaged-workflow": "src/cli.ts"
   },
   "dependencies": {
+    "@uncaged/workflow-gateway": "workspace:*",
     "@uncaged/workflow-protocol": "workspace:*",
     "@uncaged/workflow-util": "workspace:*",
     "@uncaged/workflow-cas": "workspace:*",

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

@@ -1,17 +1,14 @@
 import { randomUUID } from "node:crypto";
 import { hostname as osHostname } from "node:os";
 import { err, ok, type Result } from "@uncaged/workflow-protocol";
+import { createLogger } from "@uncaged/workflow-util";
 import { serve } from "bun";
 
 import { printCliLine } from "../../cli-output.js";
 import { createApp } from "./app.js";
-import {
-  registerWithGateway,
-  startHeartbeat,
-  startTunnel,
-  unregisterFromGateway,
-} from "./tunnel.js";
+import { registerWithGateway, startHeartbeat, unregisterFromGateway } from "./tunnel.js";
 import type { ServeOptions } from "./types.js";
+import { startGatewayWsClient } from "./ws-client.js";
 
 const DEFAULT_GATEWAY_URL = "https://workflow-gateway.shazhou.workers.dev";
 const HEARTBEAT_INTERVAL_MS = 60_000;
@@ -56,6 +53,7 @@ function parseServeArgv(argv: string[]): Result<ServeOptions, string> {
   let hostname = "127.0.0.1";
   let name = osHostname().split(".")[0].toLowerCase();
   let noTunnel = false;
+  let tunnelUrl: string | null = null;
   let gatewayUrl = DEFAULT_GATEWAY_URL;
   const gatewaySecret = process.env.WORKFLOW_GATEWAY_SECRET ?? "";
   const stringFlags: Record<string, (v: string) => void> = {
@@ -68,6 +66,9 @@ function parseServeArgv(argv: string[]): Result<ServeOptions, string> {
     "--gateway": (v) => {
       gatewayUrl = v;
     },
+    "--tunnel-url": (v) => {
+      tunnelUrl = v;
+    },
   };
 
   for (let i = 0; i < argv.length; i++) {
@@ -87,7 +88,7 @@ function parseServeArgv(argv: string[]): Result<ServeOptions, string> {
     }
   }
 
-  return ok({ port, hostname, name, noTunnel, gatewayUrl, gatewaySecret });
+  return ok({ port, hostname, name, noTunnel, tunnelUrl, gatewayUrl, gatewaySecret });
 }
 
 export async function dispatchServe(storageRoot: string, argv: string[]): Promise<number> {
@@ -107,47 +108,64 @@ export async function dispatchServe(storageRoot: string, argv: string[]): Promis
     return 0;
   }
 
-  // Start cloudflared quick tunnel
-  printCliLine("starting cloudflared quick tunnel...");
-  const tunnel = await startTunnel(options.port);
+  let resolvedTunnelUrl: string;
+  let stopWsClient: (() => void) | null = null;
 
-  if (!tunnel) {
-    printCliLine("failed to create tunnel — continuing without gateway registration");
-    await new Promise(() => {});
-    return 0;
+  if (options.tunnelUrl !== null) {
+    resolvedTunnelUrl = options.tunnelUrl;
+    printCliLine(`using tunnel URL: ${resolvedTunnelUrl}`);
+  } else {
+    if (options.gatewaySecret === "") {
+      printCliLine(
+        "WORKFLOW_GATEWAY_SECRET not set — cannot use WebSocket gateway connection (set env or pass --tunnel-url)",
+      );
+      await new Promise(() => {});
+      return 0;
+    }
+    resolvedTunnelUrl = `http://127.0.0.1:${options.port}`;
+    const log = createLogger({ sink: { kind: "stderr" } });
+    stopWsClient = startGatewayWsClient({
+      gatewayUrl: options.gatewayUrl,
+      name: options.name,
+      secret: options.gatewaySecret,
+      localPort: options.port,
+      log,
+    });
+    printCliLine("gateway WebSocket reverse connection (no cloudflared)");
   }
 
-  printCliLine(`tunnel: ${tunnel.url}`);
-
-  // Register with gateway
   if (options.gatewaySecret) {
+    if (agentToken === null) {
+      printCliLine("internal error: agent token missing");
+      await new Promise(() => {});
+      return 1;
+    }
+    const token = agentToken;
     const registered = await registerWithGateway(
       options.gatewayUrl,
       options.name,
-      tunnel.url,
+      resolvedTunnelUrl,
       options.gatewaySecret,
-      agentToken!,
+      token,
     );
     if (registered) {
       printCliLine(`registered with gateway as "${options.name}"`);
     }
 
-    // Start heartbeat
     const heartbeatTimer = startHeartbeat(
       options.gatewayUrl,
       options.name,
-      tunnel.url,
+      resolvedTunnelUrl,
       options.gatewaySecret,
-      agentToken!,
+      token,
       HEARTBEAT_INTERVAL_MS,
     );
 
-    // Cleanup on exit
     const cleanup = async () => {
       clearInterval(heartbeatTimer);
+      stopWsClient?.();
       printCliLine("unregistering from gateway...");
       await unregisterFromGateway(options.gatewayUrl, options.name, options.gatewaySecret);
-      tunnel.process.kill();
       process.exit(0);
     };
 
@@ -157,7 +175,6 @@ export async function dispatchServe(storageRoot: string, argv: string[]): Promis
     printCliLine("WORKFLOW_GATEWAY_SECRET not set — skipping gateway registration");
   }
 
-  // Keep process alive
   await new Promise(() => {});
   return 0;
 }

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

@@ -3,6 +3,7 @@ export type ServeOptions = {
   hostname: string;
   name: string;
   noTunnel: boolean;
+  tunnelUrl: string | null;
   gatewayUrl: string;
   gatewaySecret: string;
 };

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

@@ -0,0 +1,165 @@
+import { parseWsRequestJson, type WsResponse } from "@uncaged/workflow-gateway/ws-protocol";
+import type { LogFn } from "@uncaged/workflow-util";
+
+export type GatewayWsClientParams = {
+  gatewayUrl: string;
+  name: string;
+  secret: string;
+  localPort: number;
+  log: LogFn;
+};
+
+const INITIAL_BACKOFF_MS = 1000;
+const MAX_BACKOFF_MS = 30_000;
+
+export function buildGatewayWsConnectUrl(gatewayUrl: string, name: string, secret: string): string {
+  const u = new URL(gatewayUrl);
+  if (u.protocol === "https:") {
+    u.protocol = "wss:";
+  } else if (u.protocol === "http:") {
+    u.protocol = "ws:";
+  }
+  u.pathname = "/ws/connect";
+  u.search = "";
+  u.searchParams.set("name", name);
+  u.searchParams.set("secret", secret);
+  return u.href;
+}
+
+function headersToRecord(h: Headers): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [k, v] of h) {
+    out[k] = v;
+  }
+  return out;
+}
+
+async function handleGatewayMessage(
+  ws: WebSocket,
+  raw: string,
+  params: GatewayWsClientParams,
+): Promise<void> {
+  const req = parseWsRequestJson(raw);
+  if (req === null) {
+    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);
+  }
+  let resp: Response;
+  try {
+    resp = await fetch(localUrl, {
+      method: req.method,
+      headers: initHeaders,
+      body: req.body === null ? undefined : req.body,
+    });
+  } catch (e) {
+    params.log("R4N7BQ3C", `local proxy fetch failed: ${String(e)}`);
+    const errBody: WsResponse = {
+      id: req.id,
+      status: 502,
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ error: "local fetch failed", detail: String(e) }),
+    };
+    ws.send(JSON.stringify(errBody));
+    return;
+  }
+  const bodyText = await resp.text();
+  const headerRecord = headersToRecord(resp.headers);
+  const out: WsResponse = {
+    id: req.id,
+    status: resp.status,
+    headers: headerRecord,
+    body: bodyText,
+  };
+  ws.send(JSON.stringify(out));
+}
+
+/** Maintains a reverse WebSocket to the workflow gateway; reconnects with exponential backoff. */
+export function startGatewayWsClient(params: GatewayWsClientParams): () => void {
+  const wsUrl = buildGatewayWsConnectUrl(params.gatewayUrl, params.name, params.secret);
+  let socket: WebSocket | null = null;
+  let reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  let stopped = false;
+  let attempt = 0;
+
+  const clearReconnectTimer = (): void => {
+    if (reconnectTimer !== null) {
+      clearTimeout(reconnectTimer);
+      reconnectTimer = null;
+    }
+  };
+
+  const scheduleReconnect = (): void => {
+    if (stopped) {
+      return;
+    }
+    clearReconnectTimer();
+    const delayMs = Math.min(INITIAL_BACKOFF_MS * 2 ** attempt, MAX_BACKOFF_MS);
+    attempt++;
+    params.log("6CJX2RLP", `gateway WebSocket reconnect in ${delayMs}ms (attempt ${attempt})`);
+    reconnectTimer = setTimeout(connect, delayMs);
+  };
+
+  const connect = (): void => {
+    if (stopped) {
+      return;
+    }
+    clearReconnectTimer();
+    params.log("2XK7HM9Q", "gateway WebSocket connecting...");
+    try {
+      socket = new WebSocket(wsUrl);
+    } catch (e) {
+      params.log("7NQW4HBT", `gateway WebSocket create failed: ${String(e)}`);
+      scheduleReconnect();
+      return;
+    }
+
+    const ws = socket;
+
+    ws.addEventListener("open", () => {
+      attempt = 0;
+      params.log("4PWN3V82", "gateway WebSocket connected");
+    });
+
+    ws.addEventListener("close", (ev) => {
+      socket = null;
+      params.log(
+        "8QTR6ZKC",
+        `gateway WebSocket closed code=${String(ev.code)} reason=${ev.reason} wasClean=${String(ev.wasClean)}`,
+      );
+      if (!stopped) {
+        scheduleReconnect();
+      }
+    });
+
+    ws.addEventListener("error", () => {
+      params.log("9BWS1M7F", "gateway WebSocket error");
+    });
+
+    ws.addEventListener("message", (ev) => {
+      const data = ev.data;
+      if (typeof data !== "string") {
+        params.log("T9W2KL5H", "gateway WebSocket non-text frame ignored");
+        return;
+      }
+      void handleGatewayMessage(ws, data, params).catch((e: unknown) => {
+        params.log("V7KX2M9P", `gateway WebSocket handler error: ${String(e)}`);
+      });
+    });
+  };
+
+  connect();
+
+  return (): void => {
+    stopped = true;
+    clearReconnectTimer();
+    if (socket !== null && socket.readyState === WebSocket.OPEN) {
+      socket.close(1000, "shutdown");
+    }
+    socket = null;
+  };
+}

packages/workflow-agent-react/__tests__/create-react-adapter.test.ts

@@ -1,208 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import type { LlmFn, ToolDefinition } from "@uncaged/workflow-reactor";
-import { ok } from "@uncaged/workflow-protocol";
-import { START, type ThreadContext, type WorkflowRuntime } from "@uncaged/workflow-protocol";
-import * as z from "zod/v4";
-
-import { createReactAdapter } from "../src/create-react-adapter.js";
-import type { ReactAdapterConfig } from "../src/types.js";
-
-// ── Helpers ─────────────────────────────────────────────────────────
-
-function makeThread(prompt: string): ThreadContext {
-  return {
-    threadId: "01TEST000000000000000000TR",
-    depth: 0,
-    bundleHash: "TESTHASH00001",
-    start: {
-      role: START,
-      content: prompt,
-      meta: {},
-      timestamp: Date.now(),
-      parentState: null,
-    },
-    steps: [],
-  };
-}
-
-const STUB_RUNTIME: WorkflowRuntime = {
-  cas: {
-    put: async (_content: string) => "STUBHASH",
-    get: async (_hash: string) => null,
-    delete: async (_hash: string) => {},
-    list: async () => [],
-  },
-  extract: async (_schema, _contentHash) => ({
-    meta: {},
-    contentPayload: "",
-    refs: [],
-  }),
-};
-
-const TEST_SCHEMA = z.object({
-  summary: z.string(),
-  score: z.number(),
-}).meta({ title: "resolve", description: "Submit the final result." });
-
-function makeChatResponse(content: string | null, toolCalls: unknown[] | null): string {
-  const message: Record<string, unknown> = { role: "assistant" };
-  if (content !== null) {
-    message.content = content;
-  }
-  if (toolCalls !== null) {
-    message.tool_calls = toolCalls;
-  }
-  return JSON.stringify({ choices: [{ message }] });
-}
-
-function makeToolCallResponse(name: string, args: Record<string, unknown>, id: string): string {
-  return makeChatResponse(null, [
-    {
-      id,
-      type: "function",
-      function: { name, arguments: JSON.stringify(args) },
-    },
-  ]);
-}
-
-// ── Tests ───────────────────────────────────────────────────────────
-
-describe("createReactAdapter", () => {
-  test("direct resolve: LLM immediately calls resolve tool with valid args", async () => {
-    const llm: LlmFn = async (_input) => {
-      return ok(makeToolCallResponse("resolve", { summary: "done", score: 42 }, "call_1"));
-    };
-
-    const config: ReactAdapterConfig = {
-      llm,
-      tools: [],
-      toolHandler: async () => "unused",
-      maxRounds: 5,
-    };
-
-    const adapter = createReactAdapter(config);
-    const roleFn = adapter("You are a test agent.", TEST_SCHEMA);
-    const result = await roleFn(makeThread("test task"), STUB_RUNTIME);
-
-    expect(result.meta).toEqual({ summary: "done", score: 42 });
-    expect(result.childThread).toBeNull();
-  });
-
-  test("tool call then resolve: LLM calls user tool first, then resolves", async () => {
-    let callCount = 0;
-    const llm: LlmFn = async (_input) => {
-      callCount += 1;
-      if (callCount === 1) {
-        return ok(makeToolCallResponse("search", { query: "test" }, "call_1"));
-      }
-      return ok(makeToolCallResponse("resolve", { summary: "found it", score: 99 }, "call_2"));
-    };
-
-    const searchTool: ToolDefinition = {
-      type: "function",
-      function: {
-        name: "search",
-        description: "Search for information",
-        parameters: {
-          type: "object",
-          properties: { query: { type: "string" } },
-          required: ["query"],
-        },
-      },
-    };
-
-    const toolResults: string[] = [];
-    const config: ReactAdapterConfig = {
-      llm,
-      tools: [searchTool],
-      toolHandler: async (name, args) => {
-        toolResults.push(`${name}:${args}`);
-        return "search result: found the answer";
-      },
-      maxRounds: 5,
-    };
-
-    const adapter = createReactAdapter(config);
-    const roleFn = adapter("You are a test agent.", TEST_SCHEMA);
-    const result = await roleFn(makeThread("test task"), STUB_RUNTIME);
-
-    expect(result.meta).toEqual({ summary: "found it", score: 99 });
-    expect(toolResults).toHaveLength(1);
-    expect(toolResults[0]).toContain("search:");
-  });
-
-  test("plain JSON response accepted", async () => {
-    const llm: LlmFn = async (_input) => {
-      return ok(makeChatResponse(JSON.stringify({ summary: "plain", score: 7 }), null));
-    };
-
-    const config: ReactAdapterConfig = {
-      llm,
-      tools: [],
-      toolHandler: async () => "unused",
-      maxRounds: 5,
-    };
-
-    const adapter = createReactAdapter(config);
-    const roleFn = adapter("You are a test agent.", TEST_SCHEMA);
-    const result = await roleFn(makeThread("test task"), STUB_RUNTIME);
-
-    expect(result.meta).toEqual({ summary: "plain", score: 7 });
-  });
-
-  test("schema validation failure + retry: invalid args then valid args", async () => {
-    let callCount = 0;
-    const llm: LlmFn = async (_input) => {
-      callCount += 1;
-      if (callCount === 1) {
-        // Invalid: score should be number, not string
-        return ok(makeToolCallResponse("resolve", { summary: "bad", score: "not-a-number" }, "call_1"));
-      }
-      return ok(makeToolCallResponse("resolve", { summary: "fixed", score: 10 }, "call_2"));
-    };
-
-    const config: ReactAdapterConfig = {
-      llm,
-      tools: [],
-      toolHandler: async () => "unused",
-      maxRounds: 5,
-    };
-
-    const adapter = createReactAdapter(config);
-    const roleFn = adapter("You are a test agent.", TEST_SCHEMA);
-    const result = await roleFn(makeThread("test task"), STUB_RUNTIME);
-
-    expect(result.meta).toEqual({ summary: "fixed", score: 10 });
-    expect(callCount).toBe(2);
-  });
-
-  test("max rounds exceeded: throws error", async () => {
-    const searchTool: ToolDefinition = {
-      type: "function",
-      function: {
-        name: "search",
-        description: "Search",
-        parameters: { type: "object", properties: {}, required: [] },
-      },
-    };
-
-    const llm: LlmFn = async (_input) => {
-      // Always call search, never resolve
-      return ok(makeToolCallResponse("search", {}, "call_n"));
-    };
-
-    const config: ReactAdapterConfig = {
-      llm,
-      tools: [searchTool],
-      toolHandler: async () => "still searching...",
-      maxRounds: 3,
-    };
-
-    const adapter = createReactAdapter(config);
-    const roleFn = adapter("You are a test agent.", TEST_SCHEMA);
-
-    await expect(roleFn(makeThread("test task"), STUB_RUNTIME)).rejects.toThrow(
-      "max_react_rounds_exceeded",
-    );
-  });
-});

packages/workflow-agent-react/package.json

@@ -1,27 +0,0 @@
-{
-  "name": "@uncaged/workflow-agent-react",
-  "version": "0.3.5",
-  "type": "module",
-  "main": "src/index.ts",
-  "types": "src/index.ts",
-  "exports": {
-    ".": {
-      "types": "./src/index.ts",
-      "default": "./src/index.ts"
-    }
-  },
-  "scripts": {
-    "test": "bun test"
-  },
-  "dependencies": {
-    "@uncaged/workflow-protocol": "workspace:*",
-    "@uncaged/workflow-reactor": "workspace:*",
-    "@uncaged/workflow-util-agent": "workspace:*"
-  },
-  "devDependencies": {
-    "zod": "^4.0.0"
-  },
-  "peerDependencies": {
-    "zod": "^4.0.0"
-  }
-}

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

@@ -1,69 +0,0 @@
-import type {
-  AdapterFn,
-  RoleResult,
-  ThreadContext,
-  WorkflowRuntime,
-} from "@uncaged/workflow-protocol";
-import { createThreadReactor } from "@uncaged/workflow-reactor";
-import { buildThreadInput } from "@uncaged/workflow-util-agent";
-import * as z from "zod/v4";
-
-import type { ReactAdapterConfig } from "./types.js";
-
-function stripJsonSchemaMeta(json: Record<string, unknown>): Record<string, unknown> {
-  const { $schema: _drop, ...rest } = json;
-  return rest;
-}
-
-function readToolName(parametersSchema: Record<string, unknown>): string {
-  const title = parametersSchema.title;
-  if (typeof title === "string" && title.trim().length > 0) {
-    return title.trim();
-  }
-  return "resolve";
-}
-
-function readToolDescription(parametersSchema: Record<string, unknown>): string {
-  const d = parametersSchema.description;
-  if (typeof d === "string" && d.trim().length > 0) {
-    return d.trim();
-  }
-  return "Submit the final structured result.";
-}
-
-export function createReactAdapter(config: ReactAdapterConfig): AdapterFn {
-  return <T>(prompt: string, schema: z.ZodType<T>) => {
-    const reactor = createThreadReactor<ThreadContext>({
-      llm: config.llm,
-      staticTools: config.tools,
-      structuredToolFromSchema: (s) => {
-        const rawJsonSchema = z.toJSONSchema(s) as Record<string, unknown>;
-        const parameters = stripJsonSchemaMeta(rawJsonSchema);
-        const name = readToolName(parameters);
-        return {
-          name,
-          tool: {
-            type: "function" as const,
-            function: {
-              name,
-              description: readToolDescription(parameters),
-              parameters,
-            },
-          },
-        };
-      },
-      systemPromptForStructuredTool: (_name) => prompt,
-      toolHandler: async (call, _thread) => {
-        return config.toolHandler(call.function.name, call.function.arguments);
-      },
-      maxRounds: config.maxRounds,
-    });
-
-    return async (ctx: ThreadContext, _runtime: WorkflowRuntime): Promise<RoleResult<T>> => {
-      const input = await buildThreadInput(ctx);
-      const result = await reactor({ thread: ctx, input, schema });
-      if (!result.ok) throw new Error(result.error);
-      return { meta: result.value, childThread: null };
-    };
-  };
-}

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

@@ -1,2 +0,0 @@
-export { createReactAdapter } from "./create-react-adapter.js";
-export type { ReactAdapterConfig, ReactToolHandler } from "./types.js";

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

@@ -1,10 +0,0 @@
-import type { LlmFn, ToolDefinition } from "@uncaged/workflow-reactor";
-
-export type ReactToolHandler = (name: string, args: string) => Promise<string>;
-
-export type ReactAdapterConfig = {
-  llm: LlmFn;
-  tools: readonly ToolDefinition[];
-  toolHandler: ReactToolHandler;
-  maxRounds: number;
-};

packages/workflow-agent-react/tsconfig.json

@@ -1,14 +0,0 @@
-{
-  "extends": "../../tsconfig.json",
-  "compilerOptions": {
-    "rootDir": "src",
-    "outDir": "dist",
-    "composite": true
-  },
-  "include": ["src/**/*.ts"],
-  "references": [
-    { "path": "../workflow-protocol" },
-    { "path": "../workflow-reactor" },
-    { "path": "../workflow-util-agent" }
-  ]
-}

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

@@ -26,53 +26,6 @@ function extractWorkflowName(records: readonly ThreadRecord[]): string | null {
   return null;
 }
 
-type GraphPanelProps = {
-  descriptor: WorkflowDescriptor;
-  workflowName: string | null;
-  nodeStates: Map<string, NodeState>;
-  onNodeClick: ((roleName: string) => void) | null;
-};
-
-function GraphPanel({ descriptor, workflowName, nodeStates, onNodeClick }: GraphPanelProps) {
-  const [open, setOpen] = useState(true);
-  const edgeCount = descriptor.graph.edges.length;
-  return (
-    <div
-      className="mb-4 rounded-lg border overflow-hidden"
-      style={{ borderColor: "var(--color-border)", background: "var(--color-surface)" }}
-    >
-      <button
-        type="button"
-        onClick={() => setOpen((v) => !v)}
-        className="w-full flex items-center justify-between px-3 py-2 text-xs"
-        style={{ color: "var(--color-text-muted)" }}
-      >
-        <span className="font-mono">
-          {open ? "▼" : "▶"} Workflow graph
-          {workflowName !== null && (
-            <span className="ml-2" style={{ color: "var(--color-text)" }}>
-              {workflowName}
-            </span>
-          )}
-        </span>
-        <span>
-          {edgeCount} edge{edgeCount === 1 ? "" : "s"}
-        </span>
-      </button>
-      {open && (
-        <div style={{ height: 300, width: "100%" }}>
-          <WorkflowGraph
-            graph={descriptor.graph}
-            roles={descriptor.roles}
-            nodeStates={nodeStates}
-            onNodeClick={onNodeClick}
-          />
-        </div>
-      )}
-    </div>
-  );
-}
-
 function computeNodeStates(records: readonly ThreadRecord[]): Map<string, NodeState> {
   const states = new Map<string, NodeState>();
   const roleRecords = records.filter(
@@ -227,46 +180,85 @@ export function ThreadDetail({ agent, threadId, onBack }: Props) {
         </p>
       )}
 
-      {descriptor !== null && descriptor.graph.edges.length > 0 && (
-        <GraphPanel
-          descriptor={descriptor}
-          workflowName={workflowName}
-          nodeStates={nodeStates}
-          onNodeClick={handleGraphNodeClick}
-        />
-      )}
+      <div className="flex gap-4" style={{ minHeight: "calc(100vh - 120px)" }}>
+        {descriptor !== null && descriptor.graph.edges.length > 0 && (
+          <div
+            className="shrink-0"
+            style={{
+              width: 280,
+              position: "sticky",
+              top: 16,
+              height: "calc(100vh - 120px)",
+              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
+                  {workflowName !== null && (
+                    <span className="ml-2" style={{ color: "var(--color-text)" }}>
+                      {workflowName}
+                    </span>
+                  )}
+                </span>
+                <span>
+                  {descriptor.graph.edges.length} edge
+                  {descriptor.graph.edges.length === 1 ? "" : "s"}
+                </span>
+              </div>
+              <div className="flex-1">
+                <WorkflowGraph
+                  graph={descriptor.graph}
+                  roles={descriptor.roles}
+                  nodeStates={nodeStates}
+                  onNodeClick={handleGraphNodeClick}
+                />
+              </div>
+            </div>
+          </div>
+        )}
 
-      {status === "loading" && !liveActive && records.length === 0 && (
-        <p style={{ color: "var(--color-text-muted)" }}>Loading...</p>
-      )}
-      {status === "error" && !liveActive && (
-        <p style={{ color: "var(--color-error)" }}>Error: {error}</p>
-      )}
-      {(status === "ok" || liveActive || records.length > 0) && (
-        <div className="space-y-3">
-          {records.map((r, i) => {
-            const key = `${threadId}-${i}`;
-            if (r.type === "role") {
-              const isFirstForRole = firstIndexByRole.get(r.role) === i;
-              const flash = highlightedRole === r.role;
-              return (
-                <div
-                  key={key}
-                  ref={(el) => {
-                    if (!isFirstForRole) return;
-                    if (el !== null) firstCardByRoleRef.current.set(r.role, el);
-                    else firstCardByRoleRef.current.delete(r.role);
-                  }}
-                >
-                  <RecordCard record={r} highlighted={flash} />
-                </div>
-              );
-            }
-            return <RecordCard key={key} record={r} highlighted={false} />;
-          })}
-          <div ref={recordsEndRef} aria-hidden />
+        <div className="flex-1 min-w-0">
+          {status === "loading" && !liveActive && records.length === 0 && (
+            <p style={{ color: "var(--color-text-muted)" }}>Loading...</p>
+          )}
+          {status === "error" && !liveActive && (
+            <p style={{ color: "var(--color-error)" }}>Error: {error}</p>
+          )}
+          {(status === "ok" || liveActive || records.length > 0) && (
+            <div className="space-y-3">
+              {records.map((r, i) => {
+                const key = `${threadId}-${i}`;
+                if (r.type === "role") {
+                  const isFirstForRole = firstIndexByRole.get(r.role) === i;
+                  const flash = highlightedRole === r.role;
+                  return (
+                    <div
+                      key={key}
+                      ref={(el) => {
+                        if (!isFirstForRole) return;
+                        if (el !== null) firstCardByRoleRef.current.set(r.role, el);
+                        else firstCardByRoleRef.current.delete(r.role);
+                      }}
+                    >
+                      <RecordCard record={r} highlighted={flash} />
+                    </div>
+                  );
+                }
+                return <RecordCard key={key} record={r} highlighted={false} />;
+              })}
+              <div ref={recordsEndRef} aria-hidden />
+            </div>
+          )}
         </div>
-      )}
+      </div>
     </div>
   );
 }

packages/workflow-gateway/package.json

@@ -3,6 +3,10 @@
   "version": "0.1.0",
   "private": true,
   "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./ws-protocol": "./src/ws-protocol.ts"
+  },
   "scripts": {
     "dev": "wrangler dev",
     "deploy": "wrangler deploy"

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

@@ -0,0 +1,162 @@
+/** One Durable Object instance per agent name; holds the reverse WebSocket from the agent CLI. */
+import { DurableObject } from "cloudflare:workers";
+
+import { parseWsRequestJson, parseWsResponseJson, type WsResponse } from "./ws-protocol.js";
+
+type AgentSocketEnv = {
+  GATEWAY_SECRET: string;
+};
+
+export const AGENT_SOCKET_INTERNAL_STATUS_PATH = "/internal/agent-socket/status";
+export const AGENT_SOCKET_INTERNAL_PROXY_PATH = "/internal/agent-socket/proxy";
+
+const PROXY_TIMEOUT_MS = 30_000;
+
+type PendingEntry = {
+  resolve: (r: Response) => void;
+  timer: ReturnType<typeof setTimeout>;
+};
+
+function jsonResponse(status: number, body: unknown): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+function wsResponseToHttp(wr: WsResponse): Response {
+  const headers = new Headers();
+  for (const [k, v] of Object.entries(wr.headers)) {
+    headers.set(k, v);
+  }
+  return new Response(wr.body, { status: wr.status, headers });
+}
+
+export class AgentSocket extends DurableObject<AgentSocketEnv> {
+  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}`) {
+      return jsonResponse(401, { error: "unauthorized" });
+    }
+    return null;
+  }
+
+  private handleStatusGet(request: Request): Response {
+    const denied = this.requireAuth(request);
+    if (denied !== null) {
+      return denied;
+    }
+    const sockets = this.ctx.getWebSockets();
+    const connected = sockets.length > 0;
+    return new Response(JSON.stringify({ connected, connectedCount: sockets.length }), {
+      headers: { "Content-Type": "application/json" },
+    });
+  }
+
+  private async handleProxyPost(request: Request): Promise<Response> {
+    const denied = this.requireAuth(request);
+    if (denied !== null) {
+      return denied;
+    }
+    const raw = await request.text();
+    const wsRequest = parseWsRequestJson(raw);
+    if (wsRequest === null) {
+      return jsonResponse(400, { error: "invalid proxy body" });
+    }
+
+    const sockets = this.ctx.getWebSockets();
+    const ws = sockets[0];
+    if (ws === undefined) {
+      return jsonResponse(503, { error: "no active websocket" });
+    }
+
+    return await new Promise<Response>((resolve) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(wsRequest.id);
+        resolve(jsonResponse(504, { error: "gateway timeout" }));
+      }, PROXY_TIMEOUT_MS);
+
+      this.pending.set(wsRequest.id, {
+        resolve: (r: Response) => {
+          clearTimeout(timer);
+          this.pending.delete(wsRequest.id);
+          resolve(r);
+        },
+        timer,
+      });
+
+      try {
+        ws.send(JSON.stringify(wsRequest));
+      } catch {
+        clearTimeout(timer);
+        this.pending.delete(wsRequest.id);
+        resolve(jsonResponse(502, { error: "websocket send failed" }));
+      }
+    });
+  }
+
+  async fetch(request: Request): Promise<Response> {
+    const url = new URL(request.url);
+
+    if (url.pathname === AGENT_SOCKET_INTERNAL_STATUS_PATH && request.method === "GET") {
+      return this.handleStatusGet(request);
+    }
+
+    if (url.pathname === AGENT_SOCKET_INTERNAL_PROXY_PATH && request.method === "POST") {
+      return this.handleProxyPost(request);
+    }
+
+    if (request.headers.get("Upgrade") !== "websocket") {
+      return new Response("expected WebSocket upgrade", { status: 426 });
+    }
+
+    for (const ws of this.ctx.getWebSockets()) {
+      ws.close(1000, "replaced by new connection");
+    }
+
+    const pair = new WebSocketPair();
+    const client = pair[0];
+    const server = pair[1];
+    this.ctx.acceptWebSocket(server);
+    return new Response(null, { status: 101, webSocket: client });
+  }
+
+  async webSocketMessage(_ws: WebSocket, message: string | ArrayBuffer): Promise<void> {
+    const text = typeof message === "string" ? message : new TextDecoder().decode(message);
+    const wr = parseWsResponseJson(text);
+    if (wr === null) {
+      return;
+    }
+    const entry = this.pending.get(wr.id);
+    if (entry === undefined) {
+      return;
+    }
+    clearTimeout(entry.timer);
+    this.pending.delete(wr.id);
+    entry.resolve(wsResponseToHttp(wr));
+  }
+
+  async webSocketClose(
+    _ws: WebSocket,
+    _code: number,
+    _reason: string,
+    _wasClean: boolean,
+  ): Promise<void> {
+    this.rejectAllPending("agent websocket closed");
+  }
+
+  async webSocketError(_ws: WebSocket, _error: unknown): Promise<void> {
+    this.rejectAllPending("agent websocket error");
+  }
+
+  private rejectAllPending(message: string): void {
+    const entries = [...this.pending.values()];
+    this.pending.clear();
+    for (const entry of entries) {
+      clearTimeout(entry.timer);
+      entry.resolve(jsonResponse(502, { error: message }));
+    }
+  }
+}

packages/workflow-gateway/src/index.ts

@@ -1,11 +1,21 @@
 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";
+import type { WsRequest } from "./ws-protocol.js";
+
+export { AgentSocket };
+
 type Env = {
   Bindings: {
     ENDPOINTS: KVNamespace;
     GATEWAY_SECRET: string;
     DASHBOARD_API_KEY: string;
+    AGENT_SOCKET: DurableObjectNamespace<AgentSocket>;
   };
 };
 
@@ -33,9 +43,165 @@ function checkDashboardAuth(c: {
   return key === c.env.DASHBOARD_API_KEY;
 }
 
+function isLocalAgentUrl(url: string): boolean {
+  try {
+    const u = new URL(url);
+    return u.hostname === "localhost" || u.hostname === "127.0.0.1";
+  } catch {
+    return false;
+  }
+}
+
+function buildForwardHeaders(raw: Headers, agentToken: string): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [key, value] of raw) {
+    const lower = key.toLowerCase();
+    if (lower === "host" || lower === "authorization") {
+      continue;
+    }
+    if (
+      lower === "connection" ||
+      lower === "keep-alive" ||
+      lower === "proxy-connection" ||
+      lower === "transfer-encoding" ||
+      lower === "upgrade"
+    ) {
+      continue;
+    }
+    out[key] = value;
+  }
+  if (agentToken !== "") {
+    out["X-Agent-Token"] = agentToken;
+  }
+  return out;
+}
+
+function buildDashboardProxyHeaders(raw: Headers, token: string): Headers {
+  const headers = new Headers(raw);
+  headers.delete("host");
+  headers.delete("Authorization");
+  if (token !== "") {
+    headers.set("X-Agent-Token", token);
+  }
+  return headers;
+}
+
+async function readBodyForWsProxy(method: string, req: Request): Promise<string | null> {
+  if (method === "GET" || method === "HEAD") {
+    return null;
+  }
+  const buf = await req.arrayBuffer();
+  return buf.byteLength === 0 ? null : new TextDecoder().decode(buf);
+}
+
+async function fetchThroughAgentSocket(
+  bindings: Env["Bindings"],
+  agent: string,
+  gateSecret: string,
+  wsRequest: WsRequest,
+): Promise<Response> {
+  const stub = bindings.AGENT_SOCKET.get(bindings.AGENT_SOCKET.idFromName(agent));
+  return stub.fetch(
+    new Request(`https://do.internal${AGENT_SOCKET_INTERNAL_PROXY_PATH}`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${gateSecret}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify(wsRequest),
+    }),
+  );
+}
+
+async function fetchAgentWithRecordHeaders(
+  targetUrl: string,
+  method: string,
+  forwardRecord: Record<string, string>,
+  bodyStr: string | null,
+): Promise<Response> {
+  const headers = new Headers();
+  for (const [k, v] of Object.entries(forwardRecord)) {
+    headers.set(k, v);
+  }
+  return fetch(targetUrl, {
+    method,
+    headers,
+    body: method !== "GET" && method !== "HEAD" ? (bodyStr ?? undefined) : undefined,
+  });
+}
+
+async function fetchAgentWithDashboardHeaders(
+  targetUrl: string,
+  method: string,
+  headers: Headers,
+  rawBody: BodyInit | null | undefined,
+): Promise<Response> {
+  return fetch(targetUrl, {
+    method,
+    headers,
+    body: method !== "GET" && method !== "HEAD" ? rawBody : undefined,
+  });
+}
+
+async function fetchAgentSocketStatus(
+  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 resp = await stub.fetch(
+      new Request(`https://do${AGENT_SOCKET_INTERNAL_STATUS_PATH}`, {
+        method: "GET",
+        headers: { Authorization: `Bearer ${env.GATEWAY_SECRET}` },
+      }),
+    );
+    if (!resp.ok) {
+      return { ok: false };
+    }
+    const body = (await resp.json()) as { connected: boolean };
+    return { ok: true, connected: body.connected };
+  } catch {
+    return { ok: false };
+  }
+}
+
+function endpointStatusFromKvAndDo(record: EndpointRecord, doConnected: boolean | null): string {
+  if (doConnected === true) {
+    return "online";
+  }
+  if (doConnected === false) {
+    if (isLocalAgentUrl(record.url)) {
+      return "offline";
+    }
+    const age = Date.now() - record.lastHeartbeat;
+    return age < TTL_SECONDS * 1000 ? "online" : "offline";
+  }
+  const age = Date.now() - record.lastHeartbeat;
+  return age < TTL_SECONDS * 1000 ? "online" : "offline";
+}
+
 // ── Health ──────────────────────────────────────────────────────────
 app.get("/healthz", (c) => c.json({ ok: true }));
 
+// ── Agent reverse WebSocket (GATEWAY_SECRET query param) ────────────
+app.get("/ws/connect", async (c) => {
+  const secret = c.req.query("secret");
+  const name = c.req.query("name");
+  if (name === undefined || name === "") {
+    return c.json({ error: "name required" }, 400);
+  }
+  if (secret !== c.env.GATEWAY_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);
+  return stub.fetch(c.req.raw);
+});
+
 // ── Gateway management (GATEWAY_SECRET auth) ────────────────────────
 const gateway = new Hono<Env>();
 
@@ -95,11 +261,12 @@ 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 age = Date.now() - record.lastHeartbeat;
+      const doStatus = await fetchAgentSocketStatus(c.env, record.name);
+      const doConnected = doStatus.ok ? doStatus.connected : null;
       endpoints.push({
         name: record.name,
         url: record.url,
-        status: age < TTL_SECONDS * 1000 ? "online" : "offline",
+        status: endpointStatusFromKvAndDo(record, doConnected),
         lastHeartbeat: record.lastHeartbeat,
       });
     }
@@ -110,7 +277,7 @@ gateway.get("/endpoints", async (c) => {
 
 app.route("/api/gateway", gateway);
 
-// ── API proxy: /api/agents/:agent/* → agent's tunnel URL (dashboard auth) ──
+// ── API proxy: /api/agents/:agent/* → WebSocket (preferred) or agent tunnel URL (dashboard auth) ──
 app.all("/api/agents/:agent/*", async (c) => {
   if (!checkDashboardAuth(c)) return c.json({ error: "unauthorized" }, 401);
   const agent = c.req.param("agent");
@@ -120,26 +287,45 @@ app.all("/api/agents/:agent/*", async (c) => {
     return c.json({ error: "agent not found" }, 404);
   }
 
-  // Build target URL: strip /api/:agent prefix, forward the rest
   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 method = c.req.method;
+  const token = record.agentToken ?? "";
+  const forwardRecord = buildForwardHeaders(c.req.raw.headers, token);
 
-  const headers = new Headers(c.req.raw.headers);
-  headers.delete("host");
-  headers.delete("Authorization"); // don't forward dashboard key to agent
-  if (record.agentToken) {
-    headers.set("X-Agent-Token", record.agentToken);
+  const doStatus = await fetchAgentSocketStatus(c.env, agent);
+  if (doStatus.ok && doStatus.connected) {
+    const bodyStr = await readBodyForWsProxy(method, c.req.raw);
+    const wsRequest: WsRequest = {
+      id: crypto.randomUUID(),
+      method,
+      path: proxyPath,
+      headers: forwardRecord,
+      body: bodyStr,
+    };
+    const proxyResp = await fetchThroughAgentSocket(c.env, agent, c.env.GATEWAY_SECRET, wsRequest);
+    if (proxyResp.status !== 503) {
+      return new Response(proxyResp.body, {
+        status: proxyResp.status,
+        headers: proxyResp.headers,
+      });
+    }
+    try {
+      const resp = await fetchAgentWithRecordHeaders(targetUrl, method, forwardRecord, bodyStr);
+      return new Response(resp.body, {
+        status: resp.status,
+        headers: resp.headers,
+      });
+    } catch (err) {
+      return c.json({ error: "agent unreachable", detail: String(err) }, 502);
+    }
   }
 
+  const headers = buildDashboardProxyHeaders(c.req.raw.headers, token);
   try {
-    const resp = await fetch(targetUrl, {
-      method: c.req.method,
-      headers,
-      body: c.req.method !== "GET" && c.req.method !== "HEAD" ? c.req.raw.body : undefined,
-    });
-
-    // Stream response back
+    const resp = await fetchAgentWithDashboardHeaders(targetUrl, method, headers, c.req.raw.body);
     return new Response(resp.body, {
       status: resp.status,
       headers: resp.headers,
@@ -149,4 +335,5 @@ app.all("/api/agents/:agent/*", async (c) => {
   }
 });
 
+// biome-ignore lint/style/noDefaultExport: Cloudflare Workers entry expects default export
 export default app;

packages/workflow-gateway/src/ws-protocol.ts

@@ -0,0 +1,93 @@
+/** Wire format for HTTP-over-WebSocket proxy between gateway Durable Object and local serve. */
+
+export type WsRequest = {
+  id: string;
+  method: string;
+  path: string;
+  headers: Record<string, string>;
+  body: string | null;
+};
+
+export type WsResponse = {
+  id: string;
+  status: number;
+  headers: Record<string, string>;
+  body: string;
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isNonEmptyString(value: unknown): value is string {
+  return typeof value === "string" && value.length > 0;
+}
+
+/** Parse and validate a JSON payload as {@link WsRequest}. */
+export function parseWsRequestJson(raw: string): WsRequest | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw) as unknown;
+  } catch {
+    return null;
+  }
+  if (!isRecord(parsed)) {
+    return null;
+  }
+  const id = parsed.id;
+  const method = parsed.method;
+  const path = parsed.path;
+  const headers = parsed.headers;
+  const body = parsed.body;
+  if (!isNonEmptyString(id) || !isNonEmptyString(method) || !isNonEmptyString(path)) {
+    return null;
+  }
+  if (!isRecord(headers)) {
+    return null;
+  }
+  const headerRecord: Record<string, string> = {};
+  for (const [k, v] of Object.entries(headers)) {
+    if (typeof v !== "string") {
+      return null;
+    }
+    headerRecord[k] = v;
+  }
+  if (body !== null && typeof body !== "string") {
+    return null;
+  }
+  return { id, method, path, headers: headerRecord, body: body === null ? null : body };
+}
+
+/** Parse and validate a JSON payload as {@link WsResponse}. */
+export function parseWsResponseJson(raw: string): WsResponse | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw) as unknown;
+  } catch {
+    return null;
+  }
+  if (!isRecord(parsed)) {
+    return null;
+  }
+  const id = parsed.id;
+  const status = parsed.status;
+  const headers = parsed.headers;
+  const respBody = parsed.body;
+  if (!isNonEmptyString(id) || typeof status !== "number" || !Number.isFinite(status)) {
+    return null;
+  }
+  if (!isRecord(headers)) {
+    return null;
+  }
+  const headerRecord: Record<string, string> = {};
+  for (const [k, v] of Object.entries(headers)) {
+    if (typeof v !== "string") {
+      return null;
+    }
+    headerRecord[k] = v;
+  }
+  if (typeof respBody !== "string") {
+    return null;
+  }
+  return { id, status: Math.trunc(status), headers: headerRecord, body: respBody };
+}

packages/workflow-gateway/wrangler.toml

@@ -6,4 +6,11 @@ compatibility_date = "2025-04-01"
 binding = "ENDPOINTS"
 id = "88b118d1cfab4c049f9c1684848811a3"
 
+[durable_objects]
+bindings = [{ name = "AGENT_SOCKET", class_name = "AgentSocket" }]
+
+[[migrations]]
+tag = "add-agent-socket"
+new_sqlite_classes = ["AgentSocket"]
+
 # GATEWAY_SECRET is set via `wrangler secret put`

packages/workflow-protocol/src/index.ts

@@ -9,8 +9,6 @@ export type {
 } from "./cas-types.js";
 
 export type {
-  AdapterBinding,
-  AdapterFn,
   AdvanceOutcome,
   AgentBinding,
   AgentContext,
@@ -29,8 +27,6 @@ export type {
   ResolvedModel,
   Result,
   RoleDefinition,
-  RoleFn,
-  RoleResult,
   RoleMeta,
   RoleOutput,
   RoleStep,

packages/workflow-protocol/src/types.ts

@@ -143,31 +143,15 @@ export type ExtractFn = <T extends Record<string, unknown>>(
   contentHash: string,
 ) => Promise<ExtractResult<T>>;
 
-/** @deprecated Use {@link AdapterFn} instead. Will be removed in a future release. */
 export type AgentFnResult = string | { output: string; childThread: string | null };
 
-/** @deprecated Use {@link AdapterFn} instead. Will be removed in a future release. */
 export type AgentFn = (ctx: AgentContext) => Promise<AgentFnResult>;
 
-/** @deprecated Use {@link AdapterBinding} instead. Will be removed in a future release. */
 export type AgentBinding = {
   agent: AgentFn;
   overrides: Partial<Record<string, AgentFn>> | null;
 };
 
-// ── Adapter (replaces Agent) ────────────────────────────────────────
-
-export type RoleResult<T> = { meta: T; childThread: string | null };
-
-export type RoleFn<T> = (ctx: ThreadContext, runtime: WorkflowRuntime) => Promise<RoleResult<T>>;
-
-export type AdapterFn = <T>(prompt: string, schema: z.ZodType<T>) => RoleFn<T>;
-
-export type AdapterBinding = {
-  adapter: AdapterFn;
-  overrides: Partial<Record<string, AdapterFn>> | null;
-};
-
 // ── Workflow Runtime & Definition ──────────────────────────────────
 
 export type WorkflowRuntime = {

packages/workflow-runtime/src/create-workflow.ts

@@ -3,9 +3,11 @@ import { tableToModerator } from "@uncaged/workflow-protocol/moderator-table.js"
 import type * as z from "zod/v4";
 
 import {
-  type AdapterBinding,
-  type AdapterFn,
   type AdvanceOutcome,
+  type AgentBinding,
+  type AgentContext,
+  type AgentFn,
+  type AgentFnResult,
   END,
   type ModeratorContext,
   type RoleDefinition,
@@ -49,18 +51,28 @@ function mergeUniqueHashes(a: readonly string[], b: readonly string[]): string[]
   return out;
 }
 
-function adapterForRole(binding: AdapterBinding, roleName: string): AdapterFn {
+function normalizeAgentResult(result: AgentFnResult): {
+  output: string;
+  childThread: string | null;
+} {
+  if (typeof result === "string") {
+    return { output: result, childThread: null };
+  }
+  return result;
+}
+
+function agentForRole(binding: AgentBinding, roleName: string): AgentFn {
   const overrides = binding.overrides;
-  const overrideFn: AdapterFn | undefined =
+  const overrideFn: AgentFn | undefined =
     overrides !== null ? overrides[roleName as keyof typeof overrides] : undefined;
-  return overrideFn !== undefined ? overrideFn : binding.adapter;
+  return overrideFn !== undefined ? overrideFn : binding.agent;
 }
 
 async function advanceOneRound<M extends RoleMeta>(
   def: Pick<WorkflowDefinition<M>, "roles"> & {
     pickNext: (ctx: ModeratorContext<M>) => (keyof M & string) | typeof END;
   },
-  binding: AdapterBinding,
+  binding: AgentBinding,
   params: {
     thread: ModeratorContext<M>;
     runtime: WorkflowRuntime;
@@ -82,24 +94,37 @@ async function advanceOneRound<M extends RoleMeta>(
     return { kind: "complete", completion: { returnCode: 1, summary: `unknown role: ${next}` } };
   }
 
-  const adapter = adapterForRole(binding, next);
-  const roleFn = adapter(roleDef.systemPrompt, roleDef.schema as z.ZodType<Record<string, unknown>>);
-  const result = await roleFn(modCtx as unknown as ThreadContext, runtime);
-  const meta = result.meta;
+  const agentCtx: AgentContext<M> = {
+    ...modCtx,
+    currentRole: { name: next, systemPrompt: roleDef.systemPrompt },
+  };
+
+  const agent = agentForRole(binding, next);
+  const agentResult = normalizeAgentResult(await agent(agentCtx as unknown as AgentContext));
+
+  const agentContentHash = await putContentNodeWithRefs(runtime.cas, agentResult.output, []);
+
+  const extracted = await runtime.extract(
+    roleDef.schema as z.ZodType<Record<string, unknown>>,
+    agentContentHash,
+  );
 
   const refsFromMeta = resolveExtractedRefs(
     roleDef as unknown as RoleDefinition<Record<string, unknown>>,
-    meta,
+    extracted.meta,
   );
+  const artifactRefs = mergeUniqueHashes(extracted.refs, refsFromMeta);
 
-  const contentPayload = JSON.stringify(meta);
-  const contentHash = await putContentNodeWithRefs(runtime.cas, contentPayload, refsFromMeta);
-  const refs = refsFromMeta.length === 0 ? [contentHash] : [...refsFromMeta, contentHash];
+  const contentHash =
+    artifactRefs.length === 0
+      ? agentContentHash
+      : await putContentNodeWithRefs(runtime.cas, extracted.contentPayload, artifactRefs);
+  const refs = artifactRefs.includes(contentHash) ? artifactRefs : [...artifactRefs, contentHash];
 
   const step = {
     role: next,
     contentHash,
-    meta,
+    meta: extracted.meta,
     refs,
     timestamp: Date.now(),
   } as RoleStep<M>;
@@ -111,22 +136,22 @@ async function advanceOneRound<M extends RoleMeta>(
       contentHash: step.contentHash,
       meta: step.meta,
       refs: step.refs,
-      childThread: result.childThread,
+      childThread: agentResult.childThread,
     },
     step,
   };
 }
 
 /**
- * Binds pure role definitions + moderator table to an adapter.
+ * Binds pure role definitions + moderator table to runtime agents.
  * Assign with `export const run = createWorkflow(def, binding)`.
  *
- * The adapter is responsible for returning typed meta directly — no separate
- * extract call is needed.
+ * Structured meta extraction is delegated to {@link WorkflowRuntime.extract}, which the
+ * engine resolves from the workflow registry's `extract` scene.
  */
 export function createWorkflow<M extends RoleMeta>(
   def: Pick<WorkflowDefinition<M>, "roles" | "table">,
-  binding: AdapterBinding,
+  binding: AgentBinding,
 ): WorkflowFn {
   const pickNext = tableToModerator(def.table);
   const loopDef = { roles: def.roles, pickNext };

packages/workflow-runtime/src/index.ts

@@ -2,8 +2,6 @@ export { buildThreadContext } from "./build-context.js";
 export { createWorkflow } from "./create-workflow.js";
 export { err, ok } from "./result.js";
 export type {
-  AdapterBinding,
-  AdapterFn,
   AgentBinding,
   AgentContext,
   AgentFn,
@@ -19,8 +17,6 @@ export type {
   ModeratorTransition,
   Result,
   RoleDefinition,
-  RoleFn,
-  RoleResult,
   RoleMeta,
   RoleOutput,
   RoleStep,

packages/workflow-runtime/src/types.ts

@@ -3,8 +3,6 @@
 // imports from "@uncaged/workflow-runtime" continues to work.
 
 export type {
-  AdapterBinding,
-  AdapterFn,
   AdvanceOutcome,
   AgentBinding,
   AgentContext,
@@ -23,8 +21,6 @@ export type {
   ResolvedModel,
   Result,
   RoleDefinition,
-  RoleFn,
-  RoleResult,
   RoleMeta,
   RoleOutput,
   RoleStep,

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

@@ -5,7 +5,6 @@
  */
 import { createCursorAgent } from "@uncaged/workflow-agent-cursor";
 import { createWorkflow } from "@uncaged/workflow-runtime";
-import { wrapAgentAsAdapter } from "@uncaged/workflow-util-agent";
 import { buildDevelopDescriptor, developWorkflowDefinition } from "./src/index.js";
 
 function requireEnv(name: string): string {
@@ -41,9 +40,7 @@ const agent = createCursorAgent({
   llmProvider,
 });
 
-const adapter = wrapAgentAsAdapter(agent);
-
-const wf = createWorkflow(developWorkflowDefinition, { adapter, overrides: null });
+const wf = createWorkflow(developWorkflowDefinition, { agent, overrides: null });
 
 export const descriptor = buildDevelopDescriptor();
 export const run = wf;

packages/workflow-template-solve-issue/__tests__/solve-issue-template.test.ts

@@ -7,17 +7,12 @@ import { createExtract } from "@uncaged/workflow-execute";
 import { tableToModerator } from "@uncaged/workflow-protocol/moderator-table.js";
 import { validateWorkflowDescriptor } from "@uncaged/workflow-register";
 import {
-  type AdapterFn,
   createWorkflow,
   END,
   type ModeratorContext,
-  type RoleResult,
   type RoleStep,
   START,
-  type ThreadContext,
-  type WorkflowRuntime,
 } from "@uncaged/workflow-runtime";
-import type * as z from "zod/v4";
 import { buildSolveIssueDescriptor } from "../src/descriptor.js";
 import type { DeveloperMeta } from "../src/developer.js";
 import { solveIssueTable, solveIssueWorkflowDefinition } from "../src/index.js";
@@ -26,6 +21,86 @@ import type { SolveIssueMeta } from "../src/roles.js";
 
 const solveIssueModerator = tableToModerator(solveIssueTable);
 
+function jsonResponse(payload: Record<string, unknown>): Response {
+  return new Response(JSON.stringify(payload), {
+    status: 200,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+function buildPlainJsonResponse(args: Record<string, unknown>): Response {
+  return jsonResponse({
+    choices: [{ message: { content: JSON.stringify(args) } }],
+  });
+}
+
+function installMockChatCompletions(sequence: ReadonlyArray<Record<string, unknown>>): () => void {
+  const origFetch = globalThis.fetch;
+  let i = 0;
+  const mockFetch = async (
+    _input: Parameters<typeof fetch>[0],
+    _init?: RequestInit,
+  ): Promise<Response> => {
+    const args = sequence[i] ?? sequence[sequence.length - 1];
+    if (args === undefined) {
+      throw new Error("installMockChatCompletions: empty sequence");
+    }
+    i += 1;
+    return buildPlainJsonResponse(args);
+  };
+  globalThis.fetch = Object.assign(mockFetch, {
+    preconnect: origFetch.preconnect.bind(origFetch),
+  }) as typeof fetch;
+  return () => {
+    globalThis.fetch = origFetch;
+  };
+}
+
+function buildToolCallResponse(args: Record<string, unknown>): Response {
+  return jsonResponse({
+    choices: [
+      {
+        message: {
+          tool_calls: [
+            {
+              id: "tc_extract_1",
+              type: "function",
+              function: {
+                name: "extract",
+                arguments: JSON.stringify(args),
+              },
+            },
+          ],
+        },
+      },
+    ],
+  });
+}
+
+function installMockToolCallCompletions(
+  sequence: ReadonlyArray<Record<string, unknown>>,
+): () => void {
+  const origFetch = globalThis.fetch;
+  let i = 0;
+  const mockFetch = async (
+    _input: Parameters<typeof fetch>[0],
+    _init?: RequestInit,
+  ): Promise<Response> => {
+    const args = sequence[i] ?? sequence[sequence.length - 1];
+    if (args === undefined) {
+      throw new Error("installMockToolCallCompletions: empty sequence");
+    }
+    i += 1;
+    return buildToolCallResponse(args);
+  };
+  globalThis.fetch = Object.assign(mockFetch, {
+    preconnect: origFetch.preconnect.bind(origFetch),
+  }) as typeof fetch;
+  return () => {
+    globalThis.fetch = origFetch;
+  };
+}
+
 function makeStart(): ModeratorContext<SolveIssueMeta>["start"] {
   return {
     role: START,
@@ -93,6 +168,17 @@ function submitterStep(meta: SubmitterMeta): RoleStep<SolveIssueMeta> {
   };
 }
 
+function createStubExtract(casDir: string) {
+  return createExtract(
+    {
+      baseUrl: "http://127.0.0.1:9",
+      apiKey: "",
+      model: "test",
+    },
+    { cas: createCasStore(casDir) },
+  );
+}
+
 function makeThread(prompt: string) {
   return {
     threadId: "01TEST000000000000000000TR",
@@ -109,35 +195,6 @@ function makeThread(prompt: string) {
   };
 }
 
-/** Creates an AdapterFn that returns a fixed sequence of meta values. */
-function createSequenceAdapter(sequence: ReadonlyArray<Record<string, unknown>>): AdapterFn {
-  let i = 0;
-  return <T>(_prompt: string, _schema: z.ZodType<T>) => {
-    return async (_ctx: ThreadContext, _runtime: WorkflowRuntime): Promise<RoleResult<T>> => {
-      const meta = sequence[i] ?? sequence[sequence.length - 1];
-      if (meta === undefined) {
-        throw new Error("createSequenceAdapter: empty sequence");
-      }
-      i += 1;
-      return { meta: meta as T, childThread: null };
-    };
-  };
-}
-
-/** Creates an AdapterFn that tracks calls and returns fixed meta. */
-function createTrackingAdapter(
-  name: string,
-  calls: string[],
-  meta: Record<string, unknown>,
-): AdapterFn {
-  return <T>(_prompt: string, _schema: z.ZodType<T>) => {
-    return async (_ctx: ThreadContext, _runtime: WorkflowRuntime): Promise<RoleResult<T>> => {
-      calls.push(name);
-      return { meta: meta as T, childThread: null };
-    };
-  };
-}
-
 describe("solveIssueModerator", () => {
   test("routes initial → preparer → developer → submitter → END", () => {
     expect(solveIssueModerator(makeCtx([]))).toBe("preparer");
@@ -170,6 +227,8 @@ describe("solveIssueModerator", () => {
   });
 
   test("returns END for any unexpected last step (defensive)", () => {
+    // A submitter step with a pseudo-unknown future status would still be
+    // routed to END, since the moderator is a closed switch over known roles.
     expect(
       solveIssueModerator(
         makeCtx([
@@ -183,16 +242,19 @@ describe("solveIssueModerator", () => {
 });
 
 describe("solveIssueWorkflowDefinition + createWorkflow", () => {
+  let restoreFetch: (() => void) | null = null;
   let casDir: string | undefined;
 
   afterEach(async () => {
+    restoreFetch?.();
+    restoreFetch = null;
     if (casDir !== undefined) {
       await rm(casDir, { recursive: true, force: true }).catch(() => {});
       casDir = undefined;
     }
   });
 
-  test("adapter yields preparer meta directly", async () => {
+  test("structured extraction yields preparer meta from mocked chat completions", async () => {
     const EXPECT_PREPARER_META: PreparerMeta = {
       repoPath: "/home/user/repos/test",
       defaultBranch: "main",
@@ -204,21 +266,18 @@ describe("solveIssueWorkflowDefinition + createWorkflow", () => {
         buildCommand: "bun run build",
       },
     };
+    restoreFetch = installMockChatCompletions([EXPECT_PREPARER_META]);
 
     casDir = await mkdtemp(join(tmpdir(), "solve-issue-cas-"));
     const cas = createCasStore(casDir);
 
-    const adapter = createSequenceAdapter([EXPECT_PREPARER_META]);
     const run = createWorkflow(solveIssueWorkflowDefinition, {
-      adapter,
-      overrides: null,
+      agent: async () => "",
+      overrides: { developer: async () => "stub-root-hash" },
     });
     const gen = run(makeThread("task"), {
       cas,
-      extract: createExtract(
-        { baseUrl: "http://127.0.0.1:9", apiKey: "", model: "test" },
-        { cas },
-      ),
+      extract: createStubExtract(casDir),
     });
     const first = await gen.next();
     expect(first.done).toBe(false);
@@ -229,7 +288,41 @@ describe("solveIssueWorkflowDefinition + createWorkflow", () => {
     expect(first.value.meta).toEqual(EXPECT_PREPARER_META);
   });
 
-  test("per-role adapter overrides default", async () => {
+  test("structured extraction also accepts tool_calls extraction path", async () => {
+    const EXPECT_PREPARER_META: PreparerMeta = {
+      repoPath: "/home/user/repos/tool-call",
+      defaultBranch: "main",
+      conventions: null,
+      toolchain: {
+        packageManager: "bun",
+        testCommand: "bun test",
+        lintCommand: null,
+        buildCommand: "bun run build",
+      },
+    };
+    restoreFetch = installMockToolCallCompletions([EXPECT_PREPARER_META]);
+
+    casDir = await mkdtemp(join(tmpdir(), "solve-issue-cas-"));
+    const cas = createCasStore(casDir);
+
+    const run = createWorkflow(solveIssueWorkflowDefinition, {
+      agent: async () => "",
+      overrides: { developer: async () => "stub-root-hash" },
+    });
+    const gen = run(makeThread("task"), {
+      cas,
+      extract: createStubExtract(casDir),
+    });
+    const first = await gen.next();
+    expect(first.done).toBe(false);
+    if (first.done) {
+      throw new Error("expected yield");
+    }
+    expect(first.value.role).toBe("preparer");
+    expect(first.value.meta).toEqual(EXPECT_PREPARER_META);
+  });
+
+  test("per-role agent overrides default", async () => {
     const PREPARER_META: PreparerMeta = {
       repoPath: "/tmp/r",
       defaultBranch: "main",
@@ -246,25 +339,35 @@ describe("solveIssueWorkflowDefinition + createWorkflow", () => {
       status: "submitted",
       prUrl: "https://github.com/example/repo/pull/2",
     };
+    restoreFetch = installMockChatCompletions([PREPARER_META, DEVELOPER_META, SUBMITTER_META]);
 
     casDir = await mkdtemp(join(tmpdir(), "solve-issue-cas-"));
     const cas = createCasStore(casDir);
 
     const calls: string[] = [];
     const run = createWorkflow(solveIssueWorkflowDefinition, {
-      adapter: createTrackingAdapter("default", calls, PREPARER_META),
+      agent: async () => {
+        calls.push("default");
+        return "";
+      },
       overrides: {
-        preparer: createTrackingAdapter("preparer", calls, PREPARER_META),
-        developer: createTrackingAdapter("developer", calls, DEVELOPER_META),
-        submitter: createTrackingAdapter("submitter", calls, SUBMITTER_META),
+        preparer: async () => {
+          calls.push("preparer");
+          return "";
+        },
+        developer: async () => {
+          calls.push("developer");
+          return "stub-root-hash";
+        },
+        submitter: async () => {
+          calls.push("submitter");
+          return "";
+        },
       },
     });
     const gen = run(makeThread("task"), {
       cas,
-      extract: createExtract(
-        { baseUrl: "http://127.0.0.1:9", apiKey: "", model: "test" },
-        { cas },
-      ),
+      extract: createStubExtract(casDir),
     });
     await gen.next();
     expect(calls).toEqual(["preparer"]);

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

@@ -7,7 +7,6 @@
 import { createHermesAgent } from "@uncaged/workflow-agent-hermes";
 import { workflowAsAgent } from "@uncaged/workflow-execute";
 import { createWorkflow } from "@uncaged/workflow-runtime";
-import { wrapAgentAsAdapter } from "@uncaged/workflow-util-agent";
 import { buildSolveIssueDescriptor, solveIssueWorkflowDefinition } from "./src/index.js";
 
 function optionalEnv(name: string): string | null {
@@ -27,13 +26,10 @@ const hermesAgent = createHermesAgent({
 
 const developerAgent = workflowAsAgent("develop");
 
-const adapter = wrapAgentAsAdapter(hermesAgent);
-const developerAdapter = wrapAgentAsAdapter(developerAgent);
-
 const wf = createWorkflow(solveIssueWorkflowDefinition, {
-  adapter,
+  agent: hermesAgent,
   overrides: {
-    developer: developerAdapter,
+    developer: developerAgent,
   },
 });
 

packages/workflow-util-agent/package.json

@@ -14,7 +14,6 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@uncaged/workflow-runtime": "workspace:*",
-    "@uncaged/workflow-cas": "workspace:*"
+    "@uncaged/workflow-runtime": "workspace:*"
   }
 }

packages/workflow-util-agent/src/build-agent-prompt.ts

@@ -1,11 +1,10 @@
-import type { AgentContext, ThreadContext } from "@uncaged/workflow-runtime";
+import type { AgentContext } from "@uncaged/workflow-runtime";
 
-/**
- * Builds a user-message string from thread context: task, previous steps, and tool hints.
- * Does NOT include a system prompt — that is passed separately via the adapter.
- */
-export async function buildThreadInput(ctx: ThreadContext): Promise<string> {
+/** Builds the full agent prompt: system instructions plus summarized thread history. */
+export async function buildAgentPrompt(ctx: AgentContext): Promise<string> {
   const lines: string[] = [];
+  lines.push(ctx.currentRole.systemPrompt);
+  lines.push("");
 
   if (ctx.start.parentState !== null) {
     lines.push("## Parent Context");
@@ -59,12 +58,3 @@ export async function buildThreadInput(ctx: ThreadContext): Promise<string> {
 
   return lines.join("\n");
 }
-
-/**
- * @deprecated Use {@link buildThreadInput} instead. This wrapper prepends the system prompt
- * from `ctx.currentRole` for backward compatibility with existing agents.
- */
-export async function buildAgentPrompt(ctx: AgentContext): Promise<string> {
-  const threadInput = await buildThreadInput(ctx);
-  return `${ctx.currentRole.systemPrompt}\n\n${threadInput}`;
-}

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

@@ -1,4 +1,3 @@
-export { buildAgentPrompt, buildThreadInput } from "./build-agent-prompt.js";
+export { buildAgentPrompt } from "./build-agent-prompt.js";
 export type { SpawnCliConfig, SpawnCliError, SpawnCliResult } from "./spawn-cli.js";
 export { spawnCli } from "./spawn-cli.js";
-export { wrapAgentAsAdapter } from "./wrap-agent-as-adapter.js";

packages/workflow-util-agent/src/wrap-agent-as-adapter.ts

@@ -1,31 +0,0 @@
-import { putContentNodeWithRefs } from "@uncaged/workflow-cas";
-import type {
-  AdapterFn,
-  AgentContext,
-  AgentFnResult,
-  RoleResult,
-  ThreadContext,
-  WorkflowRuntime,
-} from "@uncaged/workflow-runtime";
-import type * as z from "zod/v4";
-
-/**
- * Wraps a legacy AgentFn into an AdapterFn.
- * The agent produces a string (or { output, childThread }); the adapter
- * stores the output in CAS, runs extract, and returns typed meta + childThread.
- */
-export function wrapAgentAsAdapter(
-  agentFn: (ctx: AgentContext) => Promise<AgentFnResult>,
-): AdapterFn {
-  return <T>(prompt: string, schema: z.ZodType<T>) => {
-    return async (ctx: ThreadContext, runtime: WorkflowRuntime): Promise<RoleResult<T>> => {
-      const agentCtx: AgentContext = { ...ctx, currentRole: { name: "agent", systemPrompt: prompt } };
-      const result = await agentFn(agentCtx);
-      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/tsconfig.json

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

tsconfig.json

@@ -29,7 +29,6 @@
     { "path": "packages/workflow-agent-cursor" },
     { "path": "packages/workflow-agent-hermes" },
     { "path": "packages/workflow-util-agent" },
-    { "path": "packages/workflow-agent-react" },
     { "path": "packages/cli-workflow" },
     { "path": "packages/workflow-template-solve-issue" },
     { "path": "packages/workflow-template-develop" }