fix(workflow): bundle build & register workflow

- Add missing agent deps to template package.json so bun workspace
  resolution works during `bun build` (workflow-agent-cursor for develop,
  workflow-agent-hermes + workflow-execute for solve-issue)
- Create scripts/build-bundles.sh that builds both template bundles into
  dist/*.esm.js with correct --external flags for runtime-symlinked packages
- Add build:bundles script to root package.json
- Extend ensureUncagedWorkflowSymlink to also symlink workflow-util,
  workflow-execute, and workflow-register (needed by externalized bundles)
- Defer agent creation in develop bundle-entry.ts via lazy init so
  requireEnv('WORKFLOW_LLM_API_KEY') only throws at first invocation,
  not at import() time (fixes workflowAsAgent crash)
- Document that env vars must be set before the first worker spawn
  (workers are persistent and don't inherit later env changes)

Fixes #206

Co-authored-by: Cursor <cursoragent@cursor.com>

CLAUDE.md

@@ -245,64 +245,6 @@ bun run format      # biome format --write
 bun test            # run tests
 ```
 
-### Publishing to Gitea npm Registry
-
-All public `@uncaged/*` packages are published to the Gitea npm registry at `git.shazhou.work`. Workflow workspaces consume packages from this registry via `bunfig.toml`.
-
-```bash
-# Publish all packages (bun pm pack resolves workspace:* → actual versions)
-bun run publish:gitea
-
-# Dry run — see what would be published
-bun run publish:gitea:dry
-```
-
-Prerequisites: `.npmrc` in monorepo root with Gitea auth token (`//git.shazhou.work/api/packages/shazhou/npm/:_authToken=<token>`).
-
-### Workflow Workspace Setup
-
-External workflow repos (e.g. `xingyue-workflows`) use the Gitea registry for `@uncaged/*` packages. Add a `bunfig.toml`:
-
-```toml
-[install.scopes]
-"@uncaged" = "https://git.shazhou.work/api/packages/shazhou/npm/"
-```
-
-Then `bun install` resolves `@uncaged/*` from Gitea, all other packages from npmjs.
-
-### Cross-repo Development (bun link)
-
-Alternative for development against un-published local changes:
-
-```bash
-bun run link            # Register all packages (from monorepo root)
-bun run link:consume    # Link into CWD's project (⚠️ don't bun install after)
-bun run link:unlink     # Restore original deps
-```
-
-### End-to-end: Monorepo → Registry → Workspace → Bundle
-
-The recommended development flow for building workflows:
-
-```
-workflow/ (monorepo)           — engine, runtime, templates, agents
-  │  bun run publish:gitea     — auto topo-sort, bun pm pack → npm publish
-  ▼
-git.shazhou.work npm registry  — @uncaged/* scoped packages
-  │  bun install               — via bunfig.toml scoped registry
-  ▼
-my-workflows/ (workspace)     — bunfig.toml + normal package.json
-  │  bun run build:develop     — bun build → single .esm.js
-  ▼
-uncaged-workflow workflow add  — register bundle locally
-uncaged-workflow run           — execute workflow
-```
-
-1. **Monorepo changes** → `bun run publish:gitea` (packages auto-discovered from `packages/*/`, topologically sorted, `workspace:*` resolved to real versions)
-2. **Workspace** → `bun install` fetches latest from Gitea, `bun install` is safe to run anytime
-3. **Build** → produces single-file ESM bundle with `@uncaged/*` as externals
-4. **Register & Run** → `uncaged-workflow workflow add <name> <bundle>` then `uncaged-workflow run <name>`
-
 ## Commit Convention
 
 ```

package.json

@@ -6,15 +6,11 @@
   ],
   "scripts": {
     "build": "bunx tsc --build",
+    "build:bundles": "bash scripts/build-bundles.sh",
     "check": "bunx tsc --build && biome check .",
     "typecheck": "bunx tsc --build",
     "format": "biome format --write .",
-    "test": "bun run --filter '*' test",
-    "link": "./scripts/link-all.sh",
-    "link:consume": "./scripts/link-all.sh --consume",
-    "link:unlink": "./scripts/link-all.sh --unlink",
-    "publish:gitea": "./scripts/publish-all.sh",
-    "publish:gitea:dry": "./scripts/publish-all.sh --dry-run"
+    "test": "bun run --filter '*' test"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.14",

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

@@ -58,11 +58,6 @@ describe("--help flag on groups", () => {
     const code = await runCli(STORAGE_ROOT, ["init", "--help"]);
     expect(code).toBe(0);
   });
-
-  test("setup --help returns 0", async () => {
-    const code = await runCli(STORAGE_ROOT, ["setup", "--help"]);
-    expect(code).toBe(0);
-  });
 });
 
 describe("getSkillTopics", () => {
@@ -95,8 +90,6 @@ describe("formatCliUsage", () => {
     expect(u).toContain("Thread execution:");
     expect(u).toContain("Content-addressable storage:");
     expect(u).toContain("Development:");
-    expect(u).toContain("Configuration:");
-    expect(u).toContain("setup [--provider <name>]");
     expect(u).toContain("Shortcuts:");
     expect(u).toContain("Reference:");
     expect(u).toContain("skill [topic]");
@@ -135,7 +128,6 @@ describe("formatSkillTopic('cli')", () => {
     expect(doc).toContain("### thread");
     expect(doc).toContain("### cas");
     expect(doc).toContain("### init");
-    expect(doc).toContain("### setup");
     expect(doc).toContain("### Top-level shortcuts");
   });
 

packages/cli-workflow/__tests__/init-workspace.test.ts

@@ -38,16 +38,8 @@ describe("init workspace", () => {
 
     const rootPkg = JSON.parse(await readFile(join(root, "package.json"), "utf8")) as {
       workspaces: string[];
-      scripts: { bundle: string };
     };
     expect(rootPkg.workspaces).toEqual(["templates/*", "workflows"]);
-    expect(rootPkg.scripts.bundle).toBe("bun run scripts/bundle.ts");
-
-    expect(await pathExists(join(root, "scripts", "bundle.ts"))).toBe(true);
-    const bundleSrc = await readFile(join(root, "scripts", "bundle.ts"), "utf8");
-    expect(bundleSrc).toContain("Bun.build");
-    expect(bundleSrc).toContain("-entry.ts");
-    expect(bundleSrc).toContain("distDir");
 
     const wfPkg = JSON.parse(await readFile(join(root, "workflows", "package.json"), "utf8")) as {
       type: string;
@@ -125,6 +117,9 @@ describe("init workspace", () => {
   });
 
   test("errors on invalid workspace name", async () => {
+    const slash = await cmdInitWorkspace(parent, "a/b");
+    expect(slash.ok).toBe(false);
+
     const dots = await cmdInitWorkspace(parent, "..");
     expect(dots.ok).toBe(false);
 
@@ -132,14 +127,6 @@ describe("init workspace", () => {
     expect(empty.ok).toBe(false);
   });
 
-  test("accepts nested path as workspace name", async () => {
-    const nested = await cmdInitWorkspace(parent, "a/b");
-    expect(nested.ok).toBe(true);
-    if (nested.ok) {
-      expect(nested.value.rootPath).toContain("a/b");
-    }
-  });
-
   test("usage lists init subcommands", () => {
     const u = formatCliUsage();
     expect(u).toContain("init workspace <name>");

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

@@ -1,131 +0,0 @@
-import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { readWorkflowRegistry } from "@uncaged/workflow-register";
-
-import { runCli } from "../src/cli-dispatch.js";
-import { cmdSetup } from "../src/commands/setup/index.js";
-
-describe("setup command (CLI mode)", () => {
-  let prevEnv: string | undefined;
-  let storageRoot: string;
-
-  beforeEach(async () => {
-    prevEnv = process.env.UNCAGED_WORKFLOW_STORAGE_ROOT;
-    storageRoot = await mkdtemp(join(tmpdir(), "uncaged-setup-"));
-    process.env.UNCAGED_WORKFLOW_STORAGE_ROOT = storageRoot;
-    await mkdir(storageRoot, { recursive: true });
-  });
-
-  afterEach(async () => {
-    if (prevEnv === undefined) {
-      delete process.env.UNCAGED_WORKFLOW_STORAGE_ROOT;
-    } else {
-      process.env.UNCAGED_WORKFLOW_STORAGE_ROOT = prevEnv;
-    }
-    await rm(storageRoot, { recursive: true, force: true });
-  });
-
-  test("writes workflow.yaml with provider, models.default, and depth defaults", async () => {
-    const r = await cmdSetup(storageRoot, {
-      provider: "dashscope",
-      baseUrl: "https://dashscope.aliyuncs.com/compatible-mode/v1",
-      apiKey: "sk-test123",
-      defaultModel: "dashscope/qwen-plus",
-      initWorkspaceName: null,
-    });
-    expect(r.ok).toBe(true);
-    if (!r.ok) {
-      return;
-    }
-
-    const reg = await readWorkflowRegistry(storageRoot);
-    expect(reg.ok).toBe(true);
-    if (!reg.ok) {
-      return;
-    }
-    expect(reg.value.config).not.toBeNull();
-    if (reg.value.config === null) {
-      return;
-    }
-    expect(reg.value.config.providers.dashscope).toEqual({
-      baseUrl: "https://dashscope.aliyuncs.com/compatible-mode/v1",
-      apiKey: "sk-test123",
-    });
-    expect(reg.value.config.models.default).toBe("dashscope/qwen-plus");
-    expect(reg.value.config.maxDepth).toBe(3);
-    expect(reg.value.config.supervisorInterval).toBe(3);
-
-    const raw = await readFile(join(storageRoot, "workflow.yaml"), "utf8");
-    expect(raw).toContain("dashscope");
-    expect(raw).toContain("qwen-plus");
-  });
-
-  test("idempotent: second run updates apiKey and preserves workflows", async () => {
-    const initialYaml = `config:
-  maxDepth: 7
-  supervisorInterval: 2
-  providers:
-    dashscope:
-      baseUrl: https://dashscope.aliyuncs.com/compatible-mode/v1
-      apiKey: sk-old
-  models:
-    default: dashscope/qwen-plus
-workflows:
-  keep-me:
-    hash: "0000000000000"
-    timestamp: 1
-    history: []
-`;
-    await writeFile(join(storageRoot, "workflow.yaml"), initialYaml, "utf8");
-
-    const r2 = await cmdSetup(storageRoot, {
-      provider: "dashscope",
-      baseUrl: "https://dashscope.aliyuncs.com/compatible-mode/v1",
-      apiKey: "sk-newkey",
-      defaultModel: "dashscope/qwen-plus",
-      initWorkspaceName: null,
-    });
-    expect(r2.ok).toBe(true);
-    if (!r2.ok) {
-      return;
-    }
-
-    const reg = await readWorkflowRegistry(storageRoot);
-    expect(reg.ok).toBe(true);
-    if (!reg.ok || reg.value.config === null) {
-      return;
-    }
-    expect(reg.value.config.providers.dashscope.apiKey).toBe("sk-newkey");
-    expect(reg.value.config.maxDepth).toBe(7);
-    expect(reg.value.config.supervisorInterval).toBe(2);
-    expect(reg.value.workflows["keep-me"]).toBeDefined();
-    if (reg.value.workflows["keep-me"] === undefined) {
-      return;
-    }
-    expect(reg.value.workflows["keep-me"].hash).toBe("0000000000000");
-  });
-
-  test("runCli setup dispatches with flags and exits 0", async () => {
-    const code = await runCli(storageRoot, [
-      "setup",
-      "--provider",
-      "openai",
-      "--base-url",
-      "https://api.openai.com/v1",
-      "--api-key",
-      "sk-test",
-      "--default-model",
-      "openai/gpt-4o",
-    ]);
-    expect(code).toBe(0);
-    const reg = await readWorkflowRegistry(storageRoot);
-    expect(reg.ok).toBe(true);
-    if (!reg.ok || reg.value.config === null) {
-      return;
-    }
-    expect(reg.value.config.providers.openai.apiKey).toBe("sk-test");
-    expect(reg.value.config.models.default).toBe("openai/gpt-4o");
-  });
-});

packages/cli-workflow/package.json

@@ -1,12 +1,11 @@
 {
   "name": "@uncaged/cli-workflow",
-  "version": "0.3.5",
+  "version": "0.3.1",
   "type": "module",
   "bin": {
     "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/cli-dispatch.ts

@@ -5,7 +5,6 @@ import { formatCliUsage as formatCliUsageWithGroups } from "./cli-usage.js";
 import { createCasDispatcher } from "./commands/cas/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";
 import { formatSkillIndex, formatSkillTopic, getSkillTopics } from "./skill.js";
@@ -67,7 +66,6 @@ const COMMAND_TABLE: Record<string, DispatchFn> = {
   thread: dispatchThread,
   cas: dispatchCas,
   init: dispatchInit,
-  setup: dispatchSetup,
   skill: dispatchSkill,
   run: dispatchRun,
   live: dispatchLive,

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

@@ -5,15 +5,6 @@ import { INIT_SUBCOMMAND_TABLE } from "./commands/init/index.js";
 import { THREAD_SUBCOMMAND_TABLE } from "./commands/thread/index.js";
 import { WORKFLOW_SUBCOMMAND_TABLE } from "./commands/workflow/index.js";
 
-const SETUP_USAGE_COMMANDS = [
-  {
-    name: "",
-    args: "[--provider <name>] [--base-url <url>] [--api-key <key>] [--default-model <provider/model>] [--init-workspace <name>]",
-    description:
-      "Configure workflow.yaml LLM providers and default model (interactive when no flags)",
-  },
-] as const;
-
 export function getCommandRegistry(): ReadonlyArray<CommandGroup> {
   return [
     {
@@ -48,10 +39,6 @@ export function getCommandRegistry(): ReadonlyArray<CommandGroup> {
         description: e.description,
       })),
     },
-    {
-      name: "setup",
-      commands: [...SETUP_USAGE_COMMANDS],
-    },
   ];
 }
 

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

@@ -12,7 +12,6 @@ const USAGE_SECTION_BY_GROUP: Record<string, string> = {
   thread: "Thread execution:",
   cas: "Content-addressable storage:",
   init: "Development:",
-  setup: "Configuration:",
 };
 
 export function formatUsageCommandLines(
@@ -39,10 +38,9 @@ export function formatCliUsage(
     }
     lines.push(sectionTitle);
     const rows = group.commands.map((cmd) => {
-      const namePart = cmd.name === "" ? "" : ` ${cmd.name}`;
       const args = cmd.args ? ` ${cmd.args}` : "";
       return {
-        prefix: `${group.name}${namePart}${args}`,
+        prefix: `${group.name} ${cmd.name}${args}`,
         description: cmd.description,
       };
     });

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

@@ -6,7 +6,7 @@ export function templatePackageJson(templateName: string): string {
       private: true,
       type: "module",
       dependencies: {
-        "@uncaged/workflow-runtime": "^0.3.1",
+        "@uncaged/workflow-runtime": "^0.1.0",
         zod: "^4.0.0",
       },
     },

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

@@ -1,5 +1,5 @@
 import { mkdir, writeFile } from "node:fs/promises";
-import { basename, join, resolve } from "node:path";
+import { join } from "node:path";
 
 import { err, ok, type Result } from "@uncaged/workflow-protocol";
 
@@ -14,9 +14,6 @@ function rootPackageJson(workspaceName: string): string {
       private: true,
       type: "module",
       workspaces: ["templates/*", "workflows"],
-      scripts: {
-        bundle: "bun run scripts/bundle.ts",
-      },
     },
     null,
     2,
@@ -31,7 +28,7 @@ function workflowsPackageJson(): string {
       private: true,
       type: "module",
       dependencies: {
-        "@uncaged/workflow-runtime": "^0.3.1",
+        "@uncaged/workflow-runtime": "^0.1.0",
         zod: "^4.0.0",
       },
     },
@@ -45,9 +42,7 @@ function biomeJson(): string {
     {
       $schema: "https://biomejs.dev/schemas/2.4.14/schema.json",
       files: {
-        // Exclude generated bundle script — it uses Bun globals and console that
-        // conflict with the workspace's Biome rules (noConsole, etc.).
-        includes: ["**", "!**/node_modules", "!**/dist", "!scripts/bundle.ts"],
+        includes: ["**", "!**/node_modules", "!**/dist"],
       },
       formatter: {
         indentWidth: 2,
@@ -162,12 +157,6 @@ uncaged-workflow add <name> <path/to/bundle.esm.js>
 `;
 }
 
-function bunfigToml(): string {
-  return `[install.scopes]
-"@uncaged" = "https://git.shazhou.work/api/packages/shazhou/npm/"
-`;
-}
-
 function readmeMd(workspaceName: string): string {
   return `# ${workspaceName}
 
@@ -195,137 +184,32 @@ uncaged-workflow init workspace ${workspaceName}
 `;
 }
 
-function bundleTs(): string {
-  return [
-    'import { mkdir, readdir, readFile, 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");',
-    "}",
-    "",
-    "function entryStem(name: string): 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[];",
-    "  try {",
-    "    files = await readdir(workflowsDir);",
-    "  } catch {",
-    '    console.error("bundle: missing workflows/ directory");',
-    "    process.exitCode = 1;",
-    "    return;",
-    "  }",
-    "  const entries = files.filter(isEntryFile);",
-    "  if (entries.length === 0) {",
-    '    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);",
-    "    const result = await Bun.build({",
-    "      entrypoints: [entryPath],",
-    "      outdir: distDir,",
-    '      format: "esm",',
-    '      target: "node",',
-    "      splitting: false,",
-    '      naming: { entry: "[name].esm.js" },',
-    "      external,",
-    "    });",
-    "    if (!result.success) {",
-    "      for (const log of result.logs) {",
-    "        console.error(log);",
-    "      }",
-    `      throw new Error(\`bundle failed for \${file}\`);`,
-    "    }",
-    "    const dts =",
-    `      'export { run, descriptor } from "../workflows/' + stem + '.js";\\n';`,
-    `    await writeFile(join(distDir, \`\${stem}.d.ts\`), dts, "utf8");`,
-    `    console.log(\`bundle: \${stem} -> dist/\${stem}.esm.js\`);`,
-    "  }",
-    "}",
-    "",
-    "await main();",
-    "",
-  ].join("\n");
-}
-
 export async function cmdInitWorkspace(
   parentDir: string,
   workspaceName: string,
 ): Promise<Result<CmdInitWorkspaceSuccess, string>> {
-  // Accept a relative/absolute path: resolve it and derive the dir name for package.json.
-  const resolved = resolve(parentDir, workspaceName);
-  const rootPath = resolved;
-  const dirName = basename(resolved);
-
-  if (dirName === "" || dirName === "." || dirName === "..") {
-    return err(`invalid workspace path: ${workspaceName}`);
+  const validated = validateWorkspaceSegment(workspaceName);
+  if (!validated.ok) {
+    return validated;
   }
 
+  const rootPath = join(parentDir, workspaceName);
   if (await pathExists(rootPath)) {
     return err(`directory already exists: ${rootPath}`);
   }
 
-  await mkdir(rootPath, { recursive: true });
-  await mkdir(join(rootPath, "templates"), { recursive: true });
-  await mkdir(join(rootPath, "workflows"), { recursive: true });
-  await mkdir(join(rootPath, "scripts"), { recursive: true });
+  await mkdir(rootPath, { recursive: false });
+  await mkdir(join(rootPath, "templates"), { recursive: false });
+  await mkdir(join(rootPath, "workflows"), { recursive: false });
 
   await Promise.all([
-    writeFile(join(rootPath, "package.json"), rootPackageJson(dirName), "utf8"),
+    writeFile(join(rootPath, "package.json"), rootPackageJson(workspaceName), "utf8"),
     writeFile(join(rootPath, "biome.json"), biomeJson(), "utf8"),
     writeFile(join(rootPath, "tsconfig.json"), tsconfigJson(), "utf8"),
     writeFile(join(rootPath, "AGENTS.md"), agentsMd(), "utf8"),
-    writeFile(join(rootPath, "README.md"), readmeMd(dirName), "utf8"),
+    writeFile(join(rootPath, "README.md"), readmeMd(workspaceName), "utf8"),
     writeFile(join(rootPath, "templates", ".gitkeep"), "", "utf8"),
     writeFile(join(rootPath, "workflows", "package.json"), workflowsPackageJson(), "utf8"),
-    writeFile(join(rootPath, "workflows", ".gitkeep"), "", "utf8"),
-    writeFile(join(rootPath, "bunfig.toml"), bunfigToml(), "utf8"),
-    writeFile(join(rootPath, "scripts", "bundle.ts"), bundleTs(), "utf8"),
   ]);
 
   return ok({ rootPath });

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

@@ -1,14 +1,17 @@
 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, unregisterFromGateway } from "./tunnel.js";
+import {
+  registerWithGateway,
+  startHeartbeat,
+  startTunnel,
+  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;
@@ -53,7 +56,6 @@ 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> = {
@@ -66,9 +68,6 @@ function parseServeArgv(argv: string[]): Result<ServeOptions, string> {
     "--gateway": (v) => {
       gatewayUrl = v;
     },
-    "--tunnel-url": (v) => {
-      tunnelUrl = v;
-    },
   };
 
   for (let i = 0; i < argv.length; i++) {
@@ -88,7 +87,7 @@ function parseServeArgv(argv: string[]): Result<ServeOptions, string> {
     }
   }
 
-  return ok({ port, hostname, name, noTunnel, tunnelUrl, gatewayUrl, gatewaySecret });
+  return ok({ port, hostname, name, noTunnel, gatewayUrl, gatewaySecret });
 }
 
 export async function dispatchServe(storageRoot: string, argv: string[]): Promise<number> {
@@ -108,64 +107,47 @@ export async function dispatchServe(storageRoot: string, argv: string[]): Promis
     return 0;
   }
 
-  let resolvedTunnelUrl: string;
-  let stopWsClient: (() => void) | null = null;
+  // Start cloudflared quick tunnel
+  printCliLine("starting cloudflared quick tunnel...");
+  const tunnel = await startTunnel(options.port);
 
-  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)");
+  if (!tunnel) {
+    printCliLine("failed to create tunnel — continuing without gateway registration");
+    await new Promise(() => {});
+    return 0;
   }
 
+  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,
-      resolvedTunnelUrl,
+      tunnel.url,
       options.gatewaySecret,
-      token,
+      agentToken!,
     );
     if (registered) {
       printCliLine(`registered with gateway as "${options.name}"`);
     }
 
+    // Start heartbeat
     const heartbeatTimer = startHeartbeat(
       options.gatewayUrl,
       options.name,
-      resolvedTunnelUrl,
+      tunnel.url,
       options.gatewaySecret,
-      token,
+      agentToken!,
       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);
     };
 
@@ -175,6 +157,7 @@ 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,7 +3,6 @@ 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

@@ -1,165 +0,0 @@
-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/cli-workflow/src/commands/setup/dispatch.ts

@@ -1,399 +0,0 @@
-import { existsSync } from "node:fs";
-import { stdin as input, stdout as output } from "node:process";
-import { createInterface } from "node:readline/promises";
-import { resolve as resolvePath } from "node:path";
-
-import { err, ok, type Result } from "@uncaged/workflow-protocol";
-
-import { createLogger } from "@uncaged/workflow-util";
-
-import { printCliError, printCliLine, printCliWarn } from "../../cli-output.js";
-
-const setupDispatchLog = createLogger({ sink: { kind: "stderr" } });
-import { loadPresetProviders } from "./preset-providers.js";
-import { cmdSetup, printSetupSummary } from "./setup.js";
-import type { SetupCliArgs } from "./types.js";
-
-type OpenAiModelEntry = {
-  id: string;
-};
-
-type OpenAiModelsResponse = {
-  data: OpenAiModelEntry[];
-};
-
-function usageSetup(): string {
-  return [
-    "uncaged-workflow setup — configure workflow.yaml providers and default model",
-    "",
-    "Non-interactive (agent mode):",
-    "  uncaged-workflow setup \\",
-    "    --provider <name> \\",
-    "    --base-url <url> \\",
-    "    --api-key <key> \\",
-    "    --default-model <provider/model> \\",
-    "    [--init-workspace <name>]",
-    "",
-    "Interactive: run with no flags (prompts for each value).",
-    "",
-    "Storage: uses the same root as other commands (see UNCAGED_WORKFLOW_STORAGE_ROOT).",
-  ].join("\n");
-}
-
-function requireNext(argv: string[], i: number, flag: string): Result<string, string> {
-  const next = argv[i + 1];
-  if (next === undefined || next.startsWith("--")) {
-    return err(`${flag} requires a value`);
-  }
-  return ok(next);
-}
-
-type ParsedSetup = SetupCliArgs | "interactive" | "help";
-
-type SetupFlagField = "provider" | "baseUrl" | "apiKey" | "defaultModel" | "initWorkspaceName";
-
-const SETUP_FLAG_TO_FIELD: Record<string, SetupFlagField> = {
-  "--provider": "provider",
-  "--base-url": "baseUrl",
-  "--api-key": "apiKey",
-  "--default-model": "defaultModel",
-  "--init-workspace": "initWorkspaceName",
-};
-
-function emptyFlagState(): Record<SetupFlagField, string | null> {
-  return {
-    provider: null,
-    baseUrl: null,
-    apiKey: null,
-    defaultModel: null,
-    initWorkspaceName: null,
-  };
-}
-
-function finalizeParsedSetup(
-  state: Record<SetupFlagField, string | null>,
-): Result<ParsedSetup, string> {
-  const hasAnyFlag =
-    state.provider !== null ||
-    state.baseUrl !== null ||
-    state.apiKey !== null ||
-    state.defaultModel !== null ||
-    state.initWorkspaceName !== null;
-
-  if (!hasAnyFlag) {
-    return ok("interactive");
-  }
-
-  if (state.provider === null) {
-    return err(
-      "non-interactive setup requires --provider (or omit all flags for interactive mode)",
-    );
-  }
-
-  const missing: string[] = [];
-  if (state.baseUrl === null) {
-    missing.push("--base-url");
-  }
-  if (state.apiKey === null) {
-    missing.push("--api-key");
-  }
-  if (state.defaultModel === null) {
-    missing.push("--default-model");
-  }
-  if (missing.length > 0) {
-    return err(`missing required flag(s): ${missing.join(", ")}`);
-  }
-
-  const b = state.baseUrl;
-  const k = state.apiKey;
-  const m = state.defaultModel;
-  if (b === null || k === null || m === null) {
-    return err("internal: missing required flags after validation");
-  }
-
-  return ok({
-    provider: state.provider,
-    baseUrl: b,
-    apiKey: k,
-    defaultModel: m,
-    initWorkspaceName: state.initWorkspaceName,
-  });
-}
-
-function parseSetupArgv(argv: string[]): Result<ParsedSetup, string> {
-  const state = emptyFlagState();
-
-  for (let i = 0; i < argv.length; i++) {
-    const tok = argv[i];
-    if (tok === undefined) {
-      break;
-    }
-    if (tok === "--help" || tok === "-h") {
-      return ok("help");
-    }
-    const field = SETUP_FLAG_TO_FIELD[tok];
-    if (field === undefined) {
-      return err(`unknown argument: ${tok}`);
-    }
-    const v = requireNext(argv, i, tok);
-    if (!v.ok) {
-      return v;
-    }
-    state[field] = v.value;
-    i++;
-  }
-
-  return finalizeParsedSetup(state);
-}
-
-async function promptLine(
-  rl: { question: (q: string) => Promise<string> },
-  label: string,
-): Promise<string> {
-  const raw = await rl.question(label);
-  return raw.trim();
-}
-
-/** Read a line with terminal echo disabled (for secrets). */
-async function promptSecret(label: string): Promise<string> {
-  process.stdout.write(label);
-  return new Promise((fulfill) => {
-    let buf = "";
-    const rawWasSet = process.stdin.isRaw;
-    if (process.stdin.isTTY) {
-      process.stdin.setRawMode(true);
-    }
-    process.stdin.resume();
-    process.stdin.setEncoding("utf8");
-
-    const onData = (chunk: string) => {
-      for (const c of chunk.toString()) {
-        if (c === "\n" || c === "\r" || c === "\u0004") {
-          if (process.stdin.isTTY) {
-            process.stdin.setRawMode(rawWasSet);
-          }
-          process.stdin.pause();
-          process.stdin.removeListener("data", onData);
-          process.stdout.write("\n");
-          fulfill(buf.trim());
-          return;
-        }
-        if (c === "\u007F" || c === "\b") {
-          if (buf.length > 0) {
-            buf = buf.slice(0, -1);
-            process.stdout.write("\b \b");
-          }
-          continue;
-        }
-        if (c === "\u0003") {
-          if (process.stdin.isTTY) {
-            process.stdin.setRawMode(rawWasSet);
-          }
-          process.exit(130);
-        }
-        buf += c;
-        process.stdout.write("*");
-      }
-    };
-
-    process.stdin.on("data", onData);
-  });
-}
-
-/** Fetch available models from an OpenAI-compatible /models endpoint. */
-async function fetchAvailableModels(
-  baseUrl: string,
-  apiKey: string,
-): Promise<string[]> {
-  const url = baseUrl.replace(/\/+$/, "") + "/models";
-  try {
-    const res = await fetch(url, {
-      headers: { Authorization: `Bearer ${apiKey}` },
-      signal: AbortSignal.timeout(10_000),
-    });
-    if (!res.ok) {
-      setupDispatchLog("R5KH7WM3", `GET ${url} returned ${res.status}`);
-      return [];
-    }
-    const body = (await res.json()) as OpenAiModelsResponse;
-    if (!Array.isArray(body.data)) {
-      return [];
-    }
-    // Filter out non-chat models. Some patterns are DashScope-specific (sambert, cosyvoice,
-    // wordart, wanx, wan2, paraformer) but harmless for other providers.
-    const NON_CHAT_RE =
-      /speech|embed|image|video|audio|ocr|rerank|tts|asr|paraformer|sambert|cosyvoice|wordart|wanx|wan2|flux|stable-diffusion|z-image|s2s|livetranslate|realtime|gui-/i;
-    return body.data
-      .map((m) => m.id)
-      .filter((id) => !NON_CHAT_RE.test(id))
-      .sort();
-  } catch (e) {
-    setupDispatchLog("V8NQ4JT6", `fetch models failed: ${e instanceof Error ? e.message : String(e)}`);
-    return [];
-  }
-}
-
-async function collectInteractiveSetup(): Promise<Result<SetupCliArgs, string>> {
-  const rl = createInterface({ input, output });
-  try {
-    printCliLine("Configure the LLM provider that workflow agents will use.\n");
-
-    const presets = loadPresetProviders();
-    const numWidth = String(presets.length + 1).length;
-    printCliLine("Select a provider:\n");
-    for (let i = 0; i < presets.length; i++) {
-      const p = presets[i]!;
-      const num = String(i + 1).padStart(numWidth);
-      printCliLine(`  ${num}) ${p.label.padEnd(28)} ${p.baseUrl}`);
-    }
-    const customNum = String(presets.length + 1).padStart(numWidth);
-    printCliLine(`  ${customNum}) Custom (enter name and URL manually)`);
-    printCliLine("");
-
-    const choice = await promptLine(rl, `Choose [1-${presets.length + 1}]: `);
-    const choiceNum = Number.parseInt(choice, 10);
-    if (Number.isNaN(choiceNum) || choiceNum < 1 || choiceNum > presets.length + 1) {
-      rl.close();
-      return err(`invalid choice: ${choice}`);
-    }
-
-    let provider: string;
-    let baseUrl: string;
-    if (choiceNum <= presets.length) {
-      const selected = presets[choiceNum - 1]!;
-      provider = selected.name;
-      baseUrl = selected.baseUrl;
-      printCliLine(`\n  → ${selected.label} (${baseUrl})\n`);
-    } else {
-      provider = await promptLine(rl, "Provider name (e.g. my-proxy): ");
-      if (provider === "") {
-        return err("provider name must not be empty");
-      }
-      baseUrl = await promptLine(rl, "OpenAI-compatible API base URL: ");
-      if (baseUrl === "") {
-        return err("base URL must not be empty");
-      }
-    }
-
-    // Close readline before raw-mode secret prompt, reopen after.
-    rl.close();
-    const apiKey = await promptSecret("API key for this provider: ");
-    if (apiKey === "") {
-      return err("API key must not be empty");
-    }
-    const rl2 = createInterface({ input, output });
-
-    // Try to list available models from the provider.
-    printCliLine("\nFetching available models...");
-    const models = await fetchAvailableModels(baseUrl, apiKey);
-    let selectedModel: string;
-    if (models.length > 0) {
-      printCliLine(`\nAvailable models (${models.length}):\n`);
-      const cols = process.stdout.columns || 80;
-      const nw = String(models.length).length; // number width
-      // Each cell: "  <num>) <model>  " — prefix is 2 + nw + 2 = nw+4
-      const prefixLen = nw + 4;
-      const maxModelLen = Math.max(...models.map((m) => m.length));
-      const cellWidth = prefixLen + maxModelLen + 2; // +2 gap between columns
-      const numCols = Math.max(1, Math.floor(cols / cellWidth));
-      for (let i = 0; i < models.length; i += numCols) {
-        const cells: string[] = [];
-        for (let j = i; j < Math.min(i + numCols, models.length); j++) {
-          const num = String(j + 1).padStart(nw);
-          cells.push(`  ${num}) ${(models[j]!).padEnd(maxModelLen + 2)}`);
-        }
-        printCliLine(cells.join(""));
-      }
-      printCliLine(`\nChoose a number, or type a model name directly.`);
-      const modelInput = await promptLine(rl2, `Default model [1-${models.length}]: `);
-      if (modelInput === "") {
-        rl2.close();
-        return err("default model must not be empty");
-      }
-      const modelNum = Number.parseInt(modelInput, 10);
-      if (!Number.isNaN(modelNum) && modelNum >= 1 && modelNum <= models.length) {
-        selectedModel = models[modelNum - 1]!;
-      } else {
-        // Treat as a literal model name.
-        selectedModel = modelInput;
-      }
-    } else {
-      printCliWarn("Could not fetch models (API may not support /models endpoint).");
-      const modelInput = await promptLine(rl2, `Default model (e.g. qwen-plus, gpt-4o): `);
-      if (modelInput === "") {
-        rl2.close();
-        return err("default model must not be empty");
-      }
-      selectedModel = modelInput;
-    }
-    // Strip provider prefix if user included one (e.g. pasted "MiniMax/MiniMax-M2.7").
-    const bare = selectedModel.includes("/") ? selectedModel.split("/").pop()! : selectedModel;
-    const defaultModel = `${provider}/${bare}`;
-    printCliLine(`  → ${defaultModel}`);
-
-    let initWorkspaceName: string | null = null;
-    // Loop until a valid workspace path is provided or the user skips.
-    while (true) {
-      const wsPath = await promptLine(
-        rl2,
-        "\nWorkflow workspace path (default: ./workflows, type 'skip' to skip): ",
-      );
-      if (wsPath.toLowerCase() === "skip") {
-        break;
-      }
-      const candidate = wsPath === "" ? "./workflows" : wsPath;
-      // Validate path before passing to cmdSetup.
-      const resolved = resolvePath(process.cwd(), candidate);
-      if (existsSync(resolved)) {
-        printCliWarn(`directory already exists: ${resolved}`);
-        printCliLine("Please enter a different path, or type 'skip' to skip.");
-        continue;
-      }
-      initWorkspaceName = candidate;
-      break;
-    }
-    rl2.close();
-
-    return ok({
-      provider,
-      baseUrl,
-      apiKey,
-      defaultModel,
-      initWorkspaceName,
-    });
-  } catch (e) {
-    return err(e instanceof Error ? e.message : String(e));
-  }
-}
-
-export async function dispatchSetup(storageRoot: string, argv: string[]): Promise<number> {
-  const parsed = parseSetupArgv(argv);
-  if (!parsed.ok) {
-    printCliError(`${parsed.error}\n\n${usageSetup()}`);
-    return 1;
-  }
-  if (parsed.value === "help") {
-    printCliLine(usageSetup());
-    return 0;
-  }
-
-  let args: SetupCliArgs;
-  if (parsed.value === "interactive") {
-    const collected = await collectInteractiveSetup();
-    if (!collected.ok) {
-      printCliError(collected.error);
-      return 1;
-    }
-    args = collected.value;
-  } else {
-    args = parsed.value;
-  }
-
-  const result = await cmdSetup(storageRoot, args);
-  if (!result.ok) {
-    printCliError(result.error);
-    return 1;
-  }
-  printSetupSummary(result.value);
-  return 0;
-}

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

@@ -1,4 +0,0 @@
-export { dispatchSetup } from "./dispatch.js";
-export { loadPresetProviders } from "./preset-providers.js";
-export { cmdSetup, printSetupSummary } from "./setup.js";
-export type { CmdSetupSuccess, PresetProvider, SetupCliArgs } from "./types.js";

packages/cli-workflow/src/commands/setup/preset-providers.ts

@@ -1,49 +0,0 @@
-import { readFileSync } from "node:fs";
-import { join } from "node:path";
-
-import { parse as parseYaml } from "yaml";
-
-import type { PresetProvider } from "./types.js";
-
-
-
-type RawPresetEntry = {
-	name: unknown;
-	label: unknown;
-	baseUrl: unknown;
-};
-
-function isRawEntry(v: unknown): v is RawPresetEntry {
-	if (typeof v !== "object" || v === null) return false;
-	const o = v as Record<string, unknown>;
-	return typeof o.name === "string" && typeof o.label === "string" && typeof o.baseUrl === "string";
-}
-
-let cached: ReadonlyArray<PresetProvider> | null = null;
-
-export function loadPresetProviders(): ReadonlyArray<PresetProvider> {
-	if (cached !== null) return cached;
-
-	const yamlPath = join(import.meta.dirname, "providers.yaml");
-	const raw = readFileSync(yamlPath, "utf8");
-	const parsed: unknown = parseYaml(raw);
-
-	if (!Array.isArray(parsed)) {
-		throw new Error(`providers.yaml: expected array, got ${typeof parsed}`);
-	}
-
-	const result: PresetProvider[] = [];
-	for (const entry of parsed) {
-		if (!isRawEntry(entry)) {
-			throw new Error(`providers.yaml: invalid entry: ${JSON.stringify(entry)}`);
-		}
-		result.push({
-			name: entry.name as string,
-			label: entry.label as string,
-			baseUrl: entry.baseUrl as string,
-		});
-	}
-
-	cached = result;
-	return result;
-}

packages/cli-workflow/src/commands/setup/providers.yaml

@@ -1,73 +0,0 @@
-# Preset LLM providers for `uncaged-workflow setup`.
-# Each entry needs a provider name (used in workflow.yaml) and an OpenAI-compatible base URL.
-# Add new providers here — no code changes required.
-
-# ── International ──────────────────────────────────────────
-
-- name: openai
-  label: OpenAI
-  baseUrl: https://api.openai.com/v1
-
-- name: xai
-  label: xAI
-  baseUrl: https://api.x.ai/v1
-
-- name: openrouter
-  label: OpenRouter
-  baseUrl: https://openrouter.ai/api/v1
-
-- name: venice
-  label: Venice
-  baseUrl: https://api.venice.ai/api/v1
-
-# ── China ──────────────────────────────────────────────────
-
-- name: dashscope
-  label: DashScope (Alibaba)
-  baseUrl: https://dashscope.aliyuncs.com/compatible-mode/v1
-
-- name: deepseek
-  label: DeepSeek
-  baseUrl: https://api.deepseek.com/v1
-
-- name: siliconflow
-  label: SiliconFlow
-  baseUrl: https://api.siliconflow.cn/v1
-
-- name: volcengine
-  label: Volcengine (ByteDance)
-  baseUrl: https://ark.cn-beijing.volces.com/api/v3
-
-- name: kimi
-  label: Kimi (Moonshot)
-  baseUrl: https://api.moonshot.cn/v1
-
-- name: glm
-  label: GLM (Zhipu AI)
-  baseUrl: https://open.bigmodel.cn/api/paas/v4
-
-- name: glm-intl
-  label: GLM (Zhipu AI Intl)
-  baseUrl: https://api.z.ai/api/paas/v4
-
-- name: stepfun
-  label: StepFun
-  baseUrl: https://api.stepfun.com/v1
-
-- name: minimax
-  label: MiniMax
-  baseUrl: https://api.minimax.io/v1
-
-- name: tencent
-  label: Tencent TokenHub
-  baseUrl: https://tokenhub.tencentmaas.com/v1
-
-- name: xiaomi
-  label: Xiaomi MiMo
-  baseUrl: https://api.xiaomimimo.com/v1
-
-# ── Local ──────────────────────────────────────────────────
-
-- name: ollama
-  label: Ollama (local)
-  baseUrl: http://localhost:11434/v1

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

@@ -1,105 +0,0 @@
-import { err, ok, type Result, type WorkflowConfig } from "@uncaged/workflow-protocol";
-import {
-  readWorkflowRegistry,
-  splitProviderModelRef,
-  workflowRegistryPath,
-  writeWorkflowRegistry,
-} from "@uncaged/workflow-register";
-import { createLogger } from "@uncaged/workflow-util";
-
-import { printCliLine } from "../../cli-output.js";
-import { cmdInitWorkspace } from "../init/index.js";
-import type { CmdSetupSuccess, SetupCliArgs } from "./types.js";
-
-const setupLog = createLogger({ sink: { kind: "stderr" } });
-
-
-
-function mergeWorkflowConfig(
-  prev: WorkflowConfig | null,
-  input: SetupCliArgs,
-): Result<WorkflowConfig, string> {
-  const modelSplit = splitProviderModelRef(input.defaultModel);
-  if (!modelSplit.ok) {
-    return err(modelSplit.error);
-  }
-  if (modelSplit.value.providerName !== input.provider) {
-    return err(
-      `default model provider "${modelSplit.value.providerName}" must match --provider "${input.provider}"`,
-    );
-  }
-
-  const maxDepth = prev === null ? 3 : prev.maxDepth;
-  const supervisorInterval = prev === null ? 3 : prev.supervisorInterval;
-  const providers = {
-    ...(prev === null ? {} : prev.providers),
-    [input.provider]: { baseUrl: input.baseUrl, apiKey: input.apiKey },
-  };
-  const models = { ...(prev === null ? {} : prev.models), default: input.defaultModel };
-
-  return ok({
-    maxDepth,
-    supervisorInterval,
-    providers,
-    models,
-  });
-}
-
-export async function cmdSetup(
-  storageRoot: string,
-  input: SetupCliArgs,
-): Promise<Result<CmdSetupSuccess, string>> {
-  const readResult = await readWorkflowRegistry(storageRoot);
-  if (!readResult.ok) {
-    setupLog("W8JH4Q2K", `read workflow registry failed: ${readResult.error.message}`);
-    return err(readResult.error.message);
-  }
-
-  const current = readResult.value;
-  const merged = mergeWorkflowConfig(current.config, input);
-  if (!merged.ok) {
-    return merged;
-  }
-  const nextConfig = merged.value;
-  const nextRegistry = {
-    config: nextConfig,
-    workflows: current.workflows,
-  };
-
-  const written = await writeWorkflowRegistry(storageRoot, nextRegistry);
-  if (!written.ok) {
-    setupLog("M2NB5VX9", `write workflow registry failed: ${written.error.message}`);
-    return err(written.error.message);
-  }
-
-  const registryPath = workflowRegistryPath(storageRoot);
-
-  let initWorkspaceRootPath: string | null = null;
-  if (input.initWorkspaceName !== null) {
-    const initResult = await cmdInitWorkspace(process.cwd(), input.initWorkspaceName);
-    if (!initResult.ok) {
-      setupLog("T7QC4HWP", `init workspace failed: ${initResult.error}`);
-      return err(initResult.error);
-    }
-    initWorkspaceRootPath = initResult.value.rootPath;
-  }
-
-  return ok({
-    registryPath,
-    provider: input.provider,
-    defaultModel: input.defaultModel,
-    maxDepth: nextConfig.maxDepth,
-    supervisorInterval: nextConfig.supervisorInterval,
-    initWorkspaceRootPath,
-  });
-}
-
-export function printSetupSummary(result: CmdSetupSuccess): void {
-  printCliLine(`wrote registry: ${result.registryPath}`);
-  printCliLine(`provider "${result.provider}" (baseUrl + apiKey updated)`);
-  printCliLine(`config.models.default = "${result.defaultModel}"`);
-  printCliLine(`maxDepth=${result.maxDepth}, supervisorInterval=${result.supervisorInterval}`);
-  if (result.initWorkspaceRootPath !== null) {
-    printCliLine(`initialized workflow workspace at ${result.initWorkspaceRootPath}`);
-  }
-}

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

@@ -1,23 +0,0 @@
-/** Parsed non-interactive `setup` CLI arguments (all fields required for agent mode). */
-export type SetupCliArgs = {
-  provider: string;
-  baseUrl: string;
-  apiKey: string;
-  defaultModel: string;
-  initWorkspaceName: string | null;
-};
-
-export type PresetProvider = {
-  name: string;
-  label: string;
-  baseUrl: string;
-};
-
-export type CmdSetupSuccess = {
-  registryPath: string;
-  provider: string;
-  defaultModel: string;
-  maxDepth: number;
-  supervisorInterval: number;
-  initWorkspaceRootPath: string | null;
-};

packages/cli-workflow/src/skill.ts

@@ -54,9 +54,8 @@ function formatSkillCli(): string {
   const commandSections: string[] = [];
   for (const group of groups) {
     const rows = group.commands.map((cmd) => {
-      const namePart = cmd.name === "" ? "" : ` ${cmd.name}`;
       const args = cmd.args ? `\`${cmd.args}\`` : "(none)";
-      return `| \`${group.name}${namePart}\` | ${args} | ${cmd.description} |`;
+      return `| \`${group.name} ${cmd.name}\` | ${args} | ${cmd.description} |`;
     });
     commandSections.push(
       `### ${group.name}\n\n| Command | Args | Description |\n|---------|------|-------------|\n${rows.join("\n")}`,

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

@@ -4,7 +4,6 @@ import { createCursorAgent, validateCursorAgentConfig } from "../src/index.js";
 describe("validateCursorAgentConfig", () => {
   test("accepts valid config with explicit workspace", () => {
     const r = validateCursorAgentConfig({
-      command: "/usr/local/bin/cursor-agent",
       model: null,
       timeout: 0,
       workspace: "/tmp/test-project",
@@ -15,7 +14,6 @@ describe("validateCursorAgentConfig", () => {
 
   test("accepts valid config with null workspace and llmProvider", () => {
     const r = validateCursorAgentConfig({
-      command: "/usr/local/bin/cursor-agent",
       model: null,
       timeout: 0,
       workspace: null,
@@ -24,23 +22,8 @@ describe("validateCursorAgentConfig", () => {
     expect(r.ok).toBe(true);
   });
 
-  test("rejects non-absolute command", () => {
-    const r = validateCursorAgentConfig({
-      command: "cursor-agent",
-      model: null,
-      timeout: 0,
-      workspace: "/tmp/test-project",
-      llmProvider: null,
-    });
-    expect(r.ok).toBe(false);
-    if (!r.ok) {
-      expect(r.error).toContain("absolute path");
-    }
-  });
-
   test("rejects empty workspace string", () => {
     const r = validateCursorAgentConfig({
-      command: "/usr/local/bin/cursor-agent",
       model: null,
       timeout: 0,
       workspace: "",
@@ -54,7 +37,6 @@ describe("validateCursorAgentConfig", () => {
 
   test("rejects null workspace without llmProvider", () => {
     const r = validateCursorAgentConfig({
-      command: "/usr/local/bin/cursor-agent",
       model: null,
       timeout: 0,
       workspace: null,
@@ -68,7 +50,6 @@ describe("validateCursorAgentConfig", () => {
 
   test("rejects negative timeout", () => {
     const r = validateCursorAgentConfig({
-      command: "/usr/local/bin/cursor-agent",
       model: null,
       timeout: -1,
       workspace: "/tmp/test-project",
@@ -81,7 +62,6 @@ describe("validateCursorAgentConfig", () => {
 describe("createCursorAgent", () => {
   test("returns an AgentFn with explicit workspace", () => {
     const agent = createCursorAgent({
-      command: "/usr/local/bin/cursor-agent",
       model: null,
       timeout: 0,
       workspace: "/tmp/test-project",
@@ -92,7 +72,6 @@ describe("createCursorAgent", () => {
 
   test("returns an AgentFn with null workspace and llmProvider", () => {
     const agent = createCursorAgent({
-      command: "/usr/local/bin/cursor-agent",
       model: null,
       timeout: 0,
       workspace: null,
@@ -101,25 +80,25 @@ describe("createCursorAgent", () => {
     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,
-      timeout: -1,
-      workspace: "/tmp/test-project",
-      llmProvider: null,
-    });
-    expect(typeof agent).toBe("function");
+  test("throws on invalid config at construction", () => {
+    expect(() =>
+      createCursorAgent({
+        model: null,
+        timeout: -1,
+        workspace: "/tmp/test-project",
+        llmProvider: null,
+      }),
+    ).toThrow();
   });
 
-  test("defers validation — null workspace without llmProvider does not throw at construction", () => {
-    const agent = createCursorAgent({
-      command: "/usr/local/bin/cursor-agent",
-      model: null,
-      timeout: 0,
-      workspace: null,
-      llmProvider: null,
-    });
-    expect(typeof agent).toBe("function");
+  test("throws when null workspace without llmProvider", () => {
+    expect(() =>
+      createCursorAgent({
+        model: null,
+        timeout: 0,
+        workspace: null,
+        llmProvider: null,
+      }),
+    ).toThrow();
   });
 });

packages/workflow-agent-cursor/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uncaged/workflow-agent-cursor",
-  "version": "0.3.5",
+  "version": "0.3.1",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

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

@@ -30,16 +30,16 @@ function resolveCursorModel(model: string | null): string {
 
 /** Runs `cursor-agent` with workspace from config or extracted from context via LLM. */
 export function createCursorAgent(config: CursorAgentConfig): AgentFn {
+  const validated = validateCursorAgentConfig(config);
+  if (!validated.ok) {
+    throw new Error(validated.error);
+  }
+
   const modelFlag = resolveCursorModel(config.model);
   const timeoutMs = config.timeout > 0 ? config.timeout : null;
   const logger = createLogger({ sink: { kind: "stderr" } });
 
   return async (ctx) => {
-    const validated = validateCursorAgentConfig(config);
-    if (!validated.ok) {
-      throw new Error(validated.error);
-    }
-
     let workspace: string;
 
     if (config.workspace !== null) {
@@ -71,7 +71,7 @@ export function createCursorAgent(config: CursorAgentConfig): AgentFn {
       "--trust",
       "--force",
     ];
-    const run = await spawnCli(config.command, args, {
+    const run = await spawnCli("cursor-agent", args, {
       cwd: workspace,
       timeoutMs,
     });

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

@@ -1,8 +1,6 @@
 import type { LlmProvider } from "@uncaged/workflow-protocol";
 
 export type CursorAgentConfig = {
-  /** Absolute path to the cursor-agent CLI binary. */
-  command: string;
   model: string | null;
   timeout: number;
   /** Explicit workspace path. When `null`, the agent extracts workspace from AgentContext via a ReAct LLM call. */

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

@@ -1,13 +1,8 @@
-import { isAbsolute } from "node:path";
-
 import { err, ok, type Result } from "@uncaged/workflow-protocol";
 
 import type { CursorAgentConfig } from "./types.js";
 
 export function validateCursorAgentConfig(config: CursorAgentConfig): Result<void, string> {
-  if (!isAbsolute(config.command)) {
-    return err("command must be an absolute path to the cursor-agent CLI binary");
-  }
   if (config.workspace !== null && config.workspace.length === 0) {
     return err("workspace must be a non-empty string (absolute path) or null for auto-detection");
   }

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

@@ -4,28 +4,14 @@ import { createHermesAgent, validateHermesAgentConfig } from "../src/index.js";
 describe("validateHermesAgentConfig", () => {
   test("accepts valid config", () => {
     const r = validateHermesAgentConfig({
-      command: "/usr/local/bin/hermes",
       model: null,
       timeout: null,
     });
     expect(r.ok).toBe(true);
   });
 
-  test("rejects non-absolute command", () => {
-    const r = validateHermesAgentConfig({
-      command: "hermes",
-      model: null,
-      timeout: null,
-    });
-    expect(r.ok).toBe(false);
-    if (!r.ok) {
-      expect(r.error).toContain("absolute path");
-    }
-  });
-
   test("rejects negative timeout", () => {
     const r = validateHermesAgentConfig({
-      command: "/usr/local/bin/hermes",
       model: null,
       timeout: -5,
     });
@@ -37,11 +23,10 @@ describe("validateHermesAgentConfig", () => {
 });
 
 describe("createHermesAgent", () => {
-  test("returns an AgentFn even with invalid config (validation deferred to call)", () => {
+  test("returns an AgentFn", () => {
     const agent = createHermesAgent({
-      command: "/usr/local/bin/hermes",
       model: null,
-      timeout: -5,
+      timeout: null,
     });
     expect(typeof agent).toBe("function");
   });

packages/workflow-agent-hermes/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uncaged/workflow-agent-hermes",
-  "version": "0.3.5",
+  "version": "0.3.1",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

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

@@ -26,14 +26,14 @@ function throwHermesSpawnError(error: SpawnCliError): never {
 
 /** Runs `hermes chat` non-interactively with the Nerve-style argv contract (`-q`, `--yolo`, `--quiet`). */
 export function createHermesAgent(config: HermesAgentConfig): AgentFn {
+  const validated = validateHermesAgentConfig(config);
+  if (!validated.ok) {
+    throw new Error(validated.error);
+  }
+
   const timeoutMs = config.timeout;
 
   return async (ctx) => {
-    const validated = validateHermesAgentConfig(config);
-    if (!validated.ok) {
-      throw new Error(validated.error);
-    }
-
     const fullPrompt = await buildAgentPrompt(ctx);
     const args = [
       "chat",
@@ -47,7 +47,7 @@ export function createHermesAgent(config: HermesAgentConfig): AgentFn {
     if (config.model !== null) {
       args.push("--model", config.model);
     }
-    const run = await spawnCli(config.command, args, {
+    const run = await spawnCli("hermes", args, {
       cwd: null,
       timeoutMs,
     });

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

@@ -1,6 +1,4 @@
 export type HermesAgentConfig = {
-  /** Absolute path to the hermes CLI binary. */
-  command: string;
   model: string | null;
   timeout: number | null;
 };

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

@@ -1,13 +1,8 @@
-import { isAbsolute } from "node:path";
-
 import { err, ok, type Result } from "@uncaged/workflow-runtime";
 
 import type { HermesAgentConfig } from "./types.js";
 
 export function validateHermesAgentConfig(config: HermesAgentConfig): Result<void, string> {
-  if (!isAbsolute(config.command)) {
-    return err("command must be an absolute path to the hermes CLI binary");
-  }
   if (config.timeout !== null && config.timeout < 0) {
     return err("timeout must be null or a non-negative number (milliseconds)");
   }

packages/workflow-agent-llm/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uncaged/workflow-agent-llm",
-  "version": "0.3.5",
+  "version": "0.3.1",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

packages/workflow-cas/.gitignore

@@ -0,0 +1 @@
+workflow-cas

packages/workflow-cas/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uncaged/workflow-cas",
-  "version": "0.3.5",
+  "version": "0.3.1",
   "type": "module",
   "scripts": {
     "test": "bun test"

packages/workflow-dashboard/src/api.ts

@@ -66,13 +66,8 @@ export type AgentEndpoint = {
 
 export type WorkflowSummary = {
   name: string;
-  hash: string | null;
-  timestamp: number | null;
-};
-
-export type WorkflowHistoryEntry = {
-  hash: string;
-  timestamp: number;
+  currentHash: string;
+  versions: number;
 };
 
 export type ThreadSummary = {
@@ -135,7 +130,7 @@ export type WorkflowDetail = {
   name: string;
   hash: string;
   timestamp: number;
-  history: readonly WorkflowHistoryEntry[];
+  history: unknown[];
   descriptor: WorkflowDescriptor | null;
 };
 
@@ -152,15 +147,14 @@ export function listWorkflows(agent: string): Promise<{ workflows: WorkflowSumma
   return fetchJson(agentBase(agent), "/workflows");
 }
 
-export async function getWorkflowDetail(agent: string, name: string): Promise<WorkflowDetail> {
-  return fetchJson<WorkflowDetail>(agentBase(agent), `/workflows/${encodeURIComponent(name)}`);
-}
-
 export async function getWorkflowDescriptor(
   agent: string,
   name: string,
 ): Promise<WorkflowDescriptor | null> {
-  const res = await getWorkflowDetail(agent, name);
+  const res = await fetchJson<WorkflowDetail>(
+    agentBase(agent),
+    `/workflows/${encodeURIComponent(name)}`,
+  );
   return res.descriptor;
 }
 

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

@@ -26,6 +26,53 @@ 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(
@@ -180,85 +227,46 @@ export function ThreadDetail({ agent, threadId, onBack }: Props) {
         </p>
       )}
 
-      <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>
-        )}
+      {descriptor !== null && descriptor.graph.edges.length > 0 && (
+        <GraphPanel
+          descriptor={descriptor}
+          workflowName={workflowName}
+          nodeStates={nodeStates}
+          onNodeClick={handleGraphNodeClick}
+        />
+      )}
 
-        <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>
-          )}
+      {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>
   );
 }

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

@@ -1,168 +1,12 @@
-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;
 };
 
-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);
-
-  return (
-    <div className="pt-3 space-y-3 border-t" style={{ borderColor: "var(--color-border)" }}>
-      <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>
-      {descriptor !== null && edgeCount > 0 ? (
-        <div
-          className="rounded-lg border overflow-hidden"
-          style={{ borderColor: "var(--color-border)", background: "var(--color-bg)" }}
-        >
-          <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: 300, 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) {
-    let shouldLoad = false;
-    setExpanded((prev) => {
-      const next = new Set(prev);
-      if (next.has(name)) {
-        next.delete(name);
-        return next;
-      }
-      next.add(name);
-      shouldLoad = true;
-      return next;
-    });
-    if (shouldLoad) {
-      ensureDetailLoaded(name);
-    }
-  }
 
   if (status === "loading")
     return <p style={{ color: "var(--color-text-muted)" }}>Loading workflows...</p>;
@@ -177,58 +21,26 @@ 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) => (
+            <div
+              key={w.name}
+              className="p-4 rounded-lg border"
+              style={{ background: "var(--color-surface)", borderColor: "var(--color-border)" }}
+            >
+              <div className="flex items-center justify-between">
+                <span className="font-medium">{w.name}</span>
+                <span className="text-xs" style={{ color: "var(--color-text-muted)" }}>
+                  {w.versions} version{w.versions !== 1 ? "s" : ""}
+                </span>
               </div>
-            );
-          })}
+              <code
+                className="text-xs mt-1 block font-mono"
+                style={{ color: "var(--color-accent)" }}
+              >
+                {w.currentHash}
+              </code>
+            </div>
+          ))}
         </div>
       )}
     </div>

packages/workflow-execute/.gitignore

@@ -0,0 +1 @@
+workflow-execute

packages/workflow-execute/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uncaged/workflow-execute",
-  "version": "0.3.5",
+  "version": "0.3.1",
   "type": "module",
   "exports": {
     ".": {

packages/workflow-gateway/package.json

@@ -3,10 +3,6 @@
   "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

@@ -1,162 +0,0 @@
-/** 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,21 +1,11 @@
 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>;
   };
 };
 
@@ -43,165 +33,9 @@ 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>();
 
@@ -261,12 +95,11 @@ 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 doConnected = doStatus.ok ? doStatus.connected : null;
+      const age = Date.now() - record.lastHeartbeat;
       endpoints.push({
         name: record.name,
         url: record.url,
-        status: endpointStatusFromKvAndDo(record, doConnected),
+        status: age < TTL_SECONDS * 1000 ? "online" : "offline",
         lastHeartbeat: record.lastHeartbeat,
       });
     }
@@ -277,7 +110,7 @@ gateway.get("/endpoints", async (c) => {
 
 app.route("/api/gateway", gateway);
 
-// ── API proxy: /api/agents/:agent/* → WebSocket (preferred) or agent tunnel URL (dashboard auth) ──
+// ── API proxy: /api/agents/:agent/* → agent's 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");
@@ -287,45 +120,26 @@ 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 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 = 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 headers = buildDashboardProxyHeaders(c.req.raw.headers, token);
   try {
-    const resp = await fetchAgentWithDashboardHeaders(targetUrl, method, headers, c.req.raw.body);
+    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
     return new Response(resp.body, {
       status: resp.status,
       headers: resp.headers,
@@ -335,5 +149,4 @@ 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

@@ -1,93 +0,0 @@
-/** 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,11 +6,4 @@ 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/.gitignore

@@ -0,0 +1 @@
+workflow-protocol

packages/workflow-protocol/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uncaged/workflow-protocol",
-  "version": "0.3.5",
+  "version": "0.3.1",
   "type": "module",
   "exports": {
     ".": {

packages/workflow-reactor/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uncaged/workflow-reactor",
-  "version": "0.3.5",
+  "version": "0.3.1",
   "type": "module",
   "exports": {
     ".": {

packages/workflow-register/.gitignore

@@ -0,0 +1 @@
+workflow-register

packages/workflow-register/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uncaged/workflow-register",
-  "version": "0.3.5",
+  "version": "0.3.1",
   "type": "module",
   "exports": {
     ".": {

packages/workflow-register/src/bundle/ensure-uncaged-workflow-symlink.ts

@@ -48,6 +48,9 @@ export async function ensureUncagedWorkflowSymlink(storageRoot: string): Promise
     { name: "workflow-runtime", dir: siblingPackageDir("workflow-runtime") },
     { name: "workflow-cas", dir: siblingPackageDir("workflow-cas") },
     { name: "workflow-protocol", dir: siblingPackageDir("workflow-protocol") },
+    { name: "workflow-util", dir: siblingPackageDir("workflow-util") },
+    { name: "workflow-execute", dir: siblingPackageDir("workflow-execute") },
+    { name: "workflow-register", dir: siblingPackageDir("workflow-register") },
   ];
 
   for (const pkg of packages) {

packages/workflow-runtime/.gitignore

@@ -0,0 +1 @@
+workflow-runtime

packages/workflow-runtime/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uncaged/workflow-runtime",
-  "version": "0.3.5",
+  "version": "0.3.1",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

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

@@ -2,19 +2,17 @@
  * develop bundle entry — 小橘 🍊
  *
  * All roles use cursor-agent with workspace auto-extracted from context.
+ *
+ * ENV VARS: WORKFLOW_LLM_API_KEY (required), WORKFLOW_LLM_BASE_URL,
+ * WORKFLOW_LLM_MODEL, WORKFLOW_CURSOR_MODEL, WORKFLOW_CURSOR_TIMEOUT.
+ * Must be set before the first worker spawn — workers are persistent and
+ * do not pick up env changes after initial import.
  */
 import { createCursorAgent } from "@uncaged/workflow-agent-cursor";
+import type { AgentContext, AgentFn, AgentFnResult } from "@uncaged/workflow-runtime";
 import { createWorkflow } from "@uncaged/workflow-runtime";
 import { buildDevelopDescriptor, developWorkflowDefinition } from "./src/index.js";
 
-function requireEnv(name: string): string {
-  const value = process.env[name];
-  if (value === undefined || value === "") {
-    throw new Error(`missing required env var: ${name}`);
-  }
-  return value;
-}
-
 function optionalEnv(name: string): string | null {
   const value = process.env[name];
   if (value === undefined || value === "") {
@@ -23,24 +21,39 @@ function optionalEnv(name: string): string | null {
   return value;
 }
 
-const llmProvider = {
-  baseUrl:
-    optionalEnv("WORKFLOW_LLM_BASE_URL") ?? "https://dashscope.aliyuncs.com/compatible-mode/v1",
-  apiKey: requireEnv("WORKFLOW_LLM_API_KEY"),
-  model: optionalEnv("WORKFLOW_LLM_MODEL") ?? "qwen-plus",
-};
+function requireEnv(name: string): string {
+  const value = process.env[name];
+  if (value === undefined || value === "") {
+    throw new Error(`missing required env var: ${name}`);
+  }
+  return value;
+}
 
-const agent = createCursorAgent({
-  command: requireEnv("WORKFLOW_CURSOR_COMMAND"),
-  model: optionalEnv("WORKFLOW_CURSOR_MODEL"),
-  timeout: optionalEnv("WORKFLOW_CURSOR_TIMEOUT")
-    ? Number(optionalEnv("WORKFLOW_CURSOR_TIMEOUT"))
-    : 0,
-  workspace: null,
-  llmProvider,
-});
+function createLazyAgent(): AgentFn {
+  let cached: AgentFn | null = null;
+  return (ctx: AgentContext): Promise<AgentFnResult> => {
+    if (cached === null) {
+      const llmProvider = {
+        baseUrl:
+          optionalEnv("WORKFLOW_LLM_BASE_URL") ??
+          "https://dashscope.aliyuncs.com/compatible-mode/v1",
+        apiKey: requireEnv("WORKFLOW_LLM_API_KEY"),
+        model: optionalEnv("WORKFLOW_LLM_MODEL") ?? "qwen-plus",
+      };
+      cached = createCursorAgent({
+        model: optionalEnv("WORKFLOW_CURSOR_MODEL"),
+        timeout: optionalEnv("WORKFLOW_CURSOR_TIMEOUT")
+          ? Number(optionalEnv("WORKFLOW_CURSOR_TIMEOUT"))
+          : 0,
+        workspace: null,
+        llmProvider,
+      });
+    }
+    return cached(ctx);
+  };
+}
 
-const wf = createWorkflow(developWorkflowDefinition, { agent, overrides: null });
+const wf = createWorkflow(developWorkflowDefinition, { agent: createLazyAgent(), overrides: null });
 
 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.3.5",
+  "version": "0.3.1",
   "type": "module",
   "exports": {
     ".": {
@@ -12,6 +12,7 @@
     "test": "bun test"
   },
   "dependencies": {
+    "@uncaged/workflow-agent-cursor": "workspace:*",
     "@uncaged/workflow-register": "workspace:*",
     "@uncaged/workflow-runtime": "workspace:*",
     "zod": "^4.0.0"

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

@@ -3,6 +3,10 @@
  *
  * preparer + submitter → hermes agent
  * developer → workflow-as-agent (delegates to "develop" workflow)
+ *
+ * ENV VARS: WORKFLOW_HERMES_MODEL, WORKFLOW_HERMES_TIMEOUT.
+ * Must be set before the first worker spawn — workers are persistent and
+ * do not pick up env changes after initial import.
  */
 import { createHermesAgent } from "@uncaged/workflow-agent-hermes";
 import { workflowAsAgent } from "@uncaged/workflow-execute";

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

@@ -1,6 +1,6 @@
 {
   "name": "@uncaged/workflow-template-solve-issue",
-  "version": "0.3.5",
+  "version": "0.3.1",
   "type": "module",
   "exports": {
     ".": {
@@ -12,13 +12,14 @@
     "test": "bun test"
   },
   "dependencies": {
+    "@uncaged/workflow-agent-hermes": "workspace:*",
+    "@uncaged/workflow-execute": "workspace:*",
     "@uncaged/workflow-register": "workspace:*",
     "@uncaged/workflow-runtime": "workspace:*",
     "zod": "^4.0.0"
   },
   "devDependencies": {
     "@uncaged/workflow-cas": "workspace:*",
-    "@uncaged/workflow-execute": "workspace:*",
     "@uncaged/workflow-protocol": "workspace:*"
   }
 }

packages/workflow-util-agent/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uncaged/workflow-util-agent",
-  "version": "0.3.5",
+  "version": "0.3.1",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

packages/workflow-util-agent/src/spawn-cli.ts

@@ -22,7 +22,6 @@ export function spawnCli(
   return new Promise((resolve) => {
     const child = spawn(command, args, {
       cwd: options.cwd === null ? undefined : options.cwd,
-      env: process.env,
       shell: false,
       stdio: ["ignore", "pipe", "pipe"],
     });

packages/workflow-util/.gitignore

@@ -0,0 +1 @@
+workflow-util

packages/workflow-util/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uncaged/workflow-util",
-  "version": "0.3.5",
+  "version": "0.3.1",
   "type": "module",
   "exports": {
     ".": {

scripts/build-bundles.sh

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Packages externalized from bundles — resolved at runtime via symlinks
+# created by ensureUncagedWorkflowSymlink in workflow-register.
+EXTERNAL=(
+  --external @uncaged/workflow-runtime
+  --external @uncaged/workflow-protocol
+  --external @uncaged/workflow-cas
+  --external @uncaged/workflow-util
+  --external @uncaged/workflow-execute
+  --external @uncaged/workflow-register
+)
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+cd "$REPO_ROOT"
+
+mkdir -p dist
+
+echo "Building develop bundle..."
+bun build packages/workflow-template-develop/bundle-entry.ts \
+  --bundle --format esm --target bun \
+  "${EXTERNAL[@]}" \
+  --outfile dist/develop.esm.js
+
+echo "Building solve-issue bundle..."
+bun build packages/workflow-template-solve-issue/bundle-entry.ts \
+  --bundle --format esm --target bun \
+  "${EXTERNAL[@]}" \
+  --outfile dist/solve-issue.esm.js
+
+echo "Done. Bundles written to dist/"
+
+# Register bundles if --register flag is passed
+if [[ "${1:-}" == "--register" ]]; then
+  STORAGE_ROOT="${UNCAGED_WORKFLOW_STORAGE_ROOT:-${WORKFLOW_STORAGE_ROOT:-$HOME/.uncaged/workflow}}"
+  echo "Registering bundles..."
+  for bundle in develop solve-issue; do
+    cp "dist/${bundle}.esm.js" "$STORAGE_ROOT/${bundle}.esm.js"
+    uncaged-workflow workflow add "$bundle" "$STORAGE_ROOT/${bundle}.esm.js"
+  done
+  echo "Bundles registered."
+fi

scripts/link-all.sh

@@ -1,49 +0,0 @@
-#!/usr/bin/env bash
-# Link / unlink all @uncaged/* packages from the workflow monorepo.
-#
-# Usage:
-#   ./scripts/link-all.sh              # Register all packages (run from monorepo root)
-#   ./scripts/link-all.sh --consume    # Link all packages into CWD's project
-#   ./scripts/link-all.sh --unlink     # Unregister all packages and restore CWD's deps
-
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-MONOREPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
-
-# Iterate package dirs, calling callback(dir, name) for each
-each_pkg() {
-  local cb="$1"
-  for dir in "$MONOREPO_ROOT"/packages/*/; do
-    [[ -f "$dir/package.json" ]] || continue
-    local name
-    name=$(grep -m1 '"name"' "$dir/package.json" | sed 's/.*: *"\(.*\)".*/\1/')
-    "$cb" "$dir" "$name"
-  done
-}
-
-do_register() { printf "  register  %s\n" "$2"; (cd "$1" && bun link 2>&1) > /dev/null; }
-do_consume()  { printf "  link      %s\n" "$2"; (bun link "$2" 2>&1) > /dev/null; }
-do_unlink()   { printf "  unlink    %s\n" "$2"; (cd "$1" && bun unlink 2>&1) > /dev/null || true; }
-
-case "${1:-}" in
-  --consume)
-    each_pkg do_consume
-    echo "✅ All @uncaged/* packages linked into $(pwd)"
-    echo "   ⚠️  Do NOT run 'bun install' after this — it will overwrite the links"
-    echo "   To restore: $0 --unlink"
-    ;;
-  --unlink)
-    each_pkg do_unlink
-    if [[ -f "package.json" ]]; then
-      echo "  reinstalling deps..."
-      bun install 2>&1 > /dev/null || true
-    fi
-    echo "✅ All @uncaged/* packages unlinked, deps restored"
-    ;;
-  *)
-    each_pkg do_register
-    echo "✅ All @uncaged/* packages registered"
-    echo "   cd <project> && $0 --consume"
-    ;;
-esac

scripts/publish-all.sh

@@ -1,127 +0,0 @@
-#!/usr/bin/env bash
-# Publish all public @uncaged/* packages to Gitea npm registry.
-#
-# Usage:
-#   ./scripts/publish-all.sh           # Publish all packages
-#   ./scripts/publish-all.sh --dry-run # Show what would be published
-#
-# Package order is auto-resolved via topological sort of workspace:* dependencies.
-#
-# Prerequisites:
-#   - .npmrc in monorepo root with Gitea auth token
-#   - bun (for packing with workspace:* resolution)
-#   - npm (for publishing tarballs)
-
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-MONOREPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
-
-REGISTRY="https://git.shazhou.work/api/packages/shazhou/npm/"
-DRY_RUN=""
-
-if [[ "${1:-}" == "--dry-run" ]]; then
-  DRY_RUN="--dry-run"
-  echo "🔍 Dry run mode — no packages will be published"
-  echo
-fi
-
-# Topological sort: read all package.json files, build dependency graph, emit leaf-first order
-ORDERED=$(python3 -c "
-import json, os, sys
-from pathlib import Path
-
-pkgs_dir = Path('$MONOREPO_ROOT/packages')
-# name -> dir_name, and dependency edges
-name_to_dir = {}
-deps_graph = {}  # name -> set of @uncaged/* dependency names
-
-for d in sorted(pkgs_dir.iterdir()):
-    pj = d / 'package.json'
-    if not pj.exists():
-        continue
-    data = json.loads(pj.read_text())
-    name = data.get('name', '')
-    if not name.startswith('@uncaged/'):
-        continue
-    if data.get('private'):
-        continue
-    name_to_dir[name] = d.name
-    local_deps = set()
-    for section in ('dependencies', 'devDependencies', 'peerDependencies'):
-        for dep, ver in data.get(section, {}).items():
-            if dep.startswith('@uncaged/') and dep in name_to_dir or ver == 'workspace:*':
-                local_deps.add(dep)
-    deps_graph[name] = local_deps
-
-# Kahn's algorithm
-in_degree = {n: 0 for n in deps_graph}
-for n, ds in deps_graph.items():
-    for d in ds:
-        if d in in_degree:
-            in_degree[d] = in_degree.get(d, 0)  # ensure exists
-
-# Recount
-in_degree = {n: 0 for n in deps_graph}
-for n, ds in deps_graph.items():
-    for d in ds:
-        if d in in_degree:
-            in_degree[d] += 1
-
-# Wait, direction is wrong. If A depends on B, B must be published first.
-# So edge is: A -> B means B must come before A.
-# in_degree[A] = number of deps A has (that are in our set)
-in_degree = {n: 0 for n in deps_graph}
-for n, ds in deps_graph.items():
-    for d in ds:
-        if d in in_degree:
-            pass  # d is a dependency of n
-    in_degree[n] = len([d for d in ds if d in deps_graph])
-
-queue = [n for n, deg in in_degree.items() if deg == 0]
-queue.sort()  # stable order
-result = []
-while queue:
-    node = queue.pop(0)
-    result.append(node)
-    for n, ds in deps_graph.items():
-        if node in ds:
-            in_degree[n] -= 1
-            if in_degree[n] == 0:
-                queue.append(n)
-    queue.sort()
-
-for name in result:
-    print(name_to_dir[name])
-")
-
-ok=0
-fail=0
-
-while IFS= read -r pkg; do
-  dir="$MONOREPO_ROOT/packages/$pkg"
-  name=$(grep -m1 '"name"' "$dir/package.json" | sed 's/.*: *"\(.*\)".*/\1/')
-
-  cd "$dir"
-
-  # bun pm pack resolves workspace:* → actual versions
-  tgz=$(bun pm pack 2>&1 | grep '\.tgz' | grep -v packed | head -1 | tr -d ' ')
-
-  if [[ -z "$tgz" || ! -f "$tgz" ]]; then
-    echo "❌ $name — pack failed"
-    ((fail++)) || true
-    continue
-  fi
-
-  if npm publish "$tgz" --registry="$REGISTRY" $DRY_RUN 2>&1 | tail -1 | grep -q '+'; then
-    echo "✅ $name"
-    ((ok++)) || true
-  else
-    echo "⚠️  $name (may already exist at this version)"
-  fi
-
-  rm -f "$tgz"
-done <<< "$ORDERED"
-
-echo
-echo "Published: $ok  Skipped/Failed: $fail"