fix(dashboard): remove unused onBack prop from Sidebar

- Remove all re-exports from @uncaged/workflow -> @uncaged/workflow-runtime
- Fix cli-workflow imports to use @uncaged/workflow-runtime for types
- Update bundle-validator to allow @uncaged/workflow-runtime imports
- Update init templates to reference @uncaged/workflow-runtime
- 378 tests passing, build + check clean

Refs #121, relates #125

.gitignore

@@ -3,3 +3,4 @@ dist/
 bun.lock
 *.tgz
 tsconfig.tsbuildinfo
+.npmrc

examples/hello-world.ts

@@ -1,45 +0,0 @@
-import { createWorkflow, END, type RoleDefinition } from "@uncaged/workflow";
-import * as z from "zod/v4";
-
-type Roles = {
-  greeter: { greeting: string };
-};
-
-const greeterMetaSchema = z.object({
-  greeting: z.string(),
-});
-
-export const descriptor = {
-  description: "A simple hello world workflow",
-  roles: {
-    greeter: {
-      description: "Generates a greeting",
-      schema: {
-        type: "object",
-        properties: { greeting: { type: "string" } },
-        required: ["greeting"],
-      },
-    },
-  },
-};
-
-const greeter: RoleDefinition<Roles["greeter"]> = {
-  description: "Generates a greeting",
-  systemPrompt: "You greet the user briefly.",
-  extractPrompt: "Extract the greeting string produced for the user.",
-  schema: greeterMetaSchema,
-  extractRefs: null,
-  extractMode: "single",
-};
-
-export const run = createWorkflow<Roles>(
-  {
-    roles: { greeter },
-    moderator(ctx) {
-      return ctx.steps.length === 0 ? "greeter" : END;
-    },
-  },
-  {
-    agent: async (ctx) => `Hello, ${ctx.start.content}`,
-  },
-);

examples/package.json

@@ -1,9 +0,0 @@
-{
-  "name": "@uncaged/workflow-examples",
-  "private": true,
-  "type": "module",
-  "dependencies": {
-    "@uncaged/workflow": "workspace:*",
-    "zod": "^4.0.0"
-  }
-}

package.json

@@ -2,10 +2,10 @@
   "name": "@uncaged/workflow-monorepo",
   "private": true,
   "workspaces": [
-    "packages/*",
-    "examples"
+    "packages/*"
   ],
   "scripts": {
+    "build": "bunx tsc --build",
     "check": "bunx tsc --build && biome check .",
     "typecheck": "bunx tsc --build",
     "format": "biome format --write .",

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

@@ -3,7 +3,13 @@ import { mkdir, mkdtemp, readFile, rm, unlink, writeFile } from "node:fs/promise
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
-import { getGlobalCasDir, getRegisteredWorkflow, readWorkflowRegistry } from "@uncaged/workflow";
+import {
+  createContentMerkleNode,
+  getGlobalCasDir,
+  getRegisteredWorkflow,
+  readWorkflowRegistry,
+  serializeMerkleNode,
+} from "@uncaged/workflow";
 import { cmdCasGet, cmdCasList, cmdCasPut, cmdCasRm } from "../src/commands/cas/index.js";
 import {
   cmdAdd,
@@ -22,6 +28,10 @@ const fixtureDescriptor = `export const descriptor = { description: "fixture", r
 const wfPutImport = `import { putContentMerkleNode } from "@uncaged/workflow";
 `;
 
+function casStoredForm(raw: string): string {
+  return serializeMerkleNode(createContentMerkleNode(raw));
+}
+
 describe("cli workflow commands", () => {
   let prevEnv: string | undefined;
   let storageRoot: string;
@@ -402,21 +412,23 @@ export const run = async function* (input, options) {
   });
 
   test("cas put/get/list/rm use global cas dir (thread id not required for storage)", async () => {
-    const put = await cmdCasPut(storageRoot, "phase doc");
+    const raw = "phase doc";
+    const stored = casStoredForm(raw);
+    const put = await cmdCasPut(storageRoot, raw);
     expect(put.ok).toBe(true);
     if (!put.ok) {
       return;
     }
     const hash = put.value;
     const blobPath = join(getGlobalCasDir(storageRoot), `${hash}.txt`);
-    expect(await readFile(blobPath, "utf8")).toBe("phase doc");
+    expect(await readFile(blobPath, "utf8")).toBe(stored);
 
     const got = await cmdCasGet(storageRoot, hash);
     expect(got.ok).toBe(true);
     if (!got.ok) {
       return;
     }
-    expect(got.value).toBe("phase doc");
+    expect(got.value).toBe(stored);
 
     const listed = await cmdCasList(storageRoot);
     expect(listed.ok).toBe(true);

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

@@ -51,6 +51,7 @@ describe("init template", () => {
     };
     expect(pkg.type).toBe("module");
     expect(pkg.dependencies["@uncaged/workflow"]).toBeDefined();
+    expect(pkg.dependencies["@uncaged/workflow-runtime"]).toBeDefined();
     expect(pkg.dependencies.zod).toBeDefined();
     expect(pkg.name).toContain("review-pr");
 

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

@@ -0,0 +1,104 @@
+import { describe, expect, test } from "bun:test";
+
+import { createContentMerkleNode, serializeMerkleNode } from "@uncaged/workflow";
+
+import { createApp } from "../src/commands/serve/app.js";
+
+function casStoredForm(raw: string): string {
+  return serializeMerkleNode(createContentMerkleNode(raw));
+}
+
+function buildApp(storageRoot: string) {
+  const app = createApp(storageRoot);
+  return {
+    fetch: (path: string, init?: RequestInit) =>
+      app.fetch(new Request(`http://localhost${path}`, init)),
+  };
+}
+
+describe("serve /healthz", () => {
+  test("returns ok", async () => {
+    const { fetch } = buildApp("/tmp/uncaged-serve-test-nonexistent");
+    const res = await fetch("/healthz");
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { ok: boolean };
+    expect(body.ok).toBe(true);
+  });
+});
+
+describe("serve /api/workflows", () => {
+  test("returns empty list for missing storage", async () => {
+    const { fetch } = buildApp("/tmp/uncaged-serve-test-nonexistent");
+    const res = await fetch("/api/workflows");
+    // Registry file won't exist, should return error
+    expect(res.status).toBe(200);
+  });
+});
+
+describe("serve /api/threads", () => {
+  test("returns empty list for missing storage", async () => {
+    const { fetch } = buildApp("/tmp/uncaged-serve-test-nonexistent");
+    const res = await fetch("/api/threads");
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { threads: unknown[] };
+    expect(body.threads).toEqual([]);
+  });
+
+  test("returns 404 for missing thread", async () => {
+    const { fetch } = buildApp("/tmp/uncaged-serve-test-nonexistent");
+    const res = await fetch("/api/threads/nonexistent-id");
+    expect(res.status).toBe(404);
+  });
+});
+
+describe("serve /api/threads/running", () => {
+  test("returns empty list for missing storage", async () => {
+    const { fetch } = buildApp("/tmp/uncaged-serve-test-nonexistent");
+    const res = await fetch("/api/threads/running");
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { threads: unknown[] };
+    expect(body.threads).toEqual([]);
+  });
+});
+
+describe("serve /api/cas", () => {
+  test("returns empty list for missing storage", async () => {
+    const { fetch } = buildApp("/tmp/uncaged-serve-test-nonexistent");
+    const res = await fetch("/api/cas");
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { hashes: unknown[] };
+    expect(body.hashes).toEqual([]);
+  });
+
+  test("returns 404 for missing hash", async () => {
+    const { fetch } = buildApp("/tmp/uncaged-serve-test-nonexistent");
+    const res = await fetch("/api/cas/nonexistent-hash");
+    expect(res.status).toBe(404);
+  });
+});
+
+describe("serve CAS round-trip", () => {
+  const tmpDir = `/tmp/uncaged-serve-cas-test-${Date.now()}`;
+
+  test("put then get", async () => {
+    const { fetch } = buildApp(tmpDir);
+
+    const putRes = await fetch("/api/cas", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ content: "hello world" }),
+    });
+    expect(putRes.status).toBe(201);
+    const putBody = (await putRes.json()) as { hash: string };
+    expect(typeof putBody.hash).toBe("string");
+
+    const getRes = await fetch(`/api/cas/${putBody.hash}`);
+    expect(getRes.status).toBe(200);
+    const getBody = (await getRes.json()) as { content: string };
+    expect(getBody.content).toBe(casStoredForm("hello world"));
+
+    // cleanup
+    const delRes = await fetch(`/api/cas/${putBody.hash}`, { method: "DELETE" });
+    expect(delRes.status).toBe(200);
+  });
+});

packages/cli-workflow/package.json

@@ -1,12 +1,14 @@
 {
   "name": "@uncaged/cli-workflow",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "bin": {
     "uncaged-workflow": "src/cli.ts"
   },
   "dependencies": {
+    "@uncaged/workflow-runtime": "workspace:*",
     "@uncaged/workflow": "workspace:*",
+    "hono": "^4.12.18",
     "yaml": "^2.8.4"
   },
   "scripts": {

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

@@ -4,6 +4,7 @@ import { getCommandRegistry } from "./cli-registry.js";
 import { formatCliUsage as formatCliUsageWithGroups } from "./cli-usage.js";
 import { createCasDispatcher } from "./commands/cas/index.js";
 import { createInitDispatcher } from "./commands/init/index.js";
+import { dispatchServe } from "./commands/serve/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";
@@ -71,6 +72,7 @@ const COMMAND_TABLE: Record<string, DispatchFn> = {
   skill: dispatchSkill,
   run: dispatchRun,
   live: dispatchLive,
+  serve: dispatchServe,
 };
 
 export async function runCli(storageRoot: string, argv: string[]): Promise<number> {

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

@@ -57,6 +57,17 @@ export function formatCliUsage(
   );
   lines.push("");
 
+  lines.push("Server:");
+  lines.push(
+    ...formatUsageCommandLines([
+      {
+        prefix: "serve [--port N] [--host ADDR]",
+        description: "Start HTTP API server (default: 127.0.0.1:7860)",
+      },
+    ]),
+  );
+  lines.push("");
+
   lines.push("Reference:");
   const skillTopicNames = skillTopics.map((t) => t.name).join(", ");
   lines.push(

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

@@ -7,6 +7,7 @@ export function templatePackageJson(templateName: string): string {
       type: "module",
       dependencies: {
         "@uncaged/workflow": "^0.1.0",
+        "@uncaged/workflow-runtime": "^0.1.0",
         zod: "^4.0.0",
       },
     },
@@ -31,7 +32,7 @@ export function templateTsconfigJson(): string {
 }
 
 export function templateRolesTs(): string {
-  return `import type { RoleDefinition } from "@uncaged/workflow";
+  return `import type { RoleDefinition } from "@uncaged/workflow-runtime";
 import * as z from "zod/v4";
 
 export const HELLO_TEMPLATE_DESCRIPTION =
@@ -58,7 +59,7 @@ export const greeterRole: RoleDefinition<HelloTemplateMeta["greeter"]> = {
 }
 
 export function templateModeratorTs(): string {
-  return `import { END, type Moderator, type ModeratorContext } from "@uncaged/workflow";
+  return `import { END, type Moderator, type ModeratorContext } from "@uncaged/workflow-runtime";
 
 import type { HelloTemplateMeta } from "./roles.js";
 
@@ -74,7 +75,7 @@ export const helloTemplateModerator: Moderator<HelloTemplateMeta> = (
 }
 
 export function templateIndexTs(): string {
-  return `import type { WorkflowDefinition } from "@uncaged/workflow";
+  return `import type { WorkflowDefinition } from "@uncaged/workflow-runtime";
 
 import { helloTemplateModerator } from "./moderator.js";
 import {

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

@@ -0,0 +1,20 @@
+import { Hono } from "hono";
+import { cors } from "hono/cors";
+
+import { createCasRoutes } from "./routes-cas.js";
+import { createThreadRoutes } from "./routes-thread.js";
+import { createWorkflowRoutes } from "./routes-workflow.js";
+
+export function createApp(storageRoot: string): Hono {
+  const app = new Hono();
+
+  app.use("*", cors());
+
+  app.get("/healthz", (c) => c.json({ ok: true }));
+
+  app.route("/api/workflows", createWorkflowRoutes(storageRoot));
+  app.route("/api/threads", createThreadRoutes(storageRoot));
+  app.route("/api/cas", createCasRoutes(storageRoot));
+
+  return app;
+}

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

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

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

@@ -0,0 +1,56 @@
+import { createCasStore, garbageCollectCas, getGlobalCasDir } from "@uncaged/workflow";
+import { Hono } from "hono";
+
+export function createCasRoutes(storageRoot: string): Hono {
+  const app = new Hono();
+
+  app.get("/", async (c) => {
+    const casDir = getGlobalCasDir(storageRoot);
+    const cas = createCasStore(casDir);
+    const hashes = await cas.list();
+    return c.json({ hashes });
+  });
+
+  app.get("/:hash", async (c) => {
+    const casDir = getGlobalCasDir(storageRoot);
+    const cas = createCasStore(casDir);
+    const content = await cas.get(c.req.param("hash"));
+    if (content === null) {
+      return c.json({ error: "not found" }, 404);
+    }
+    return c.json({ hash: c.req.param("hash"), content });
+  });
+
+  app.post("/", async (c) => {
+    const body = await c.req.json<{ content: string }>();
+    if (typeof body.content !== "string") {
+      return c.json({ error: "content field required" }, 400);
+    }
+    const casDir = getGlobalCasDir(storageRoot);
+    const cas = createCasStore(casDir);
+    const hash = await cas.put(body.content);
+    return c.json({ hash }, 201);
+  });
+
+  app.delete("/:hash", async (c) => {
+    const casDir = getGlobalCasDir(storageRoot);
+    const cas = createCasStore(casDir);
+    const hash = c.req.param("hash");
+    const content = await cas.get(hash);
+    if (content === null) {
+      return c.json({ error: "not found" }, 404);
+    }
+    await cas.delete(hash);
+    return c.json({ ok: true });
+  });
+
+  app.post("/gc", async (c) => {
+    const result = await garbageCollectCas(storageRoot);
+    if (!result.ok) {
+      return c.json({ error: result.error }, 500);
+    }
+    return c.json(result.value);
+  });
+
+  return app;
+}

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

@@ -0,0 +1,46 @@
+import { Hono } from "hono";
+
+import { readTextFileIfExists } from "../../fs-utils.js";
+import {
+  listHistoricalThreads,
+  listRunningThreads,
+  resolveThreadDataPath,
+} from "../../thread-scan.js";
+
+export function createThreadRoutes(storageRoot: string): Hono {
+  const app = new Hono();
+
+  app.get("/", async (c) => {
+    const nameFilter = c.req.query("workflow") ?? null;
+    const rows = await listHistoricalThreads(storageRoot, nameFilter);
+    return c.json({ threads: rows });
+  });
+
+  app.get("/running", async (c) => {
+    const rows = await listRunningThreads(storageRoot);
+    return c.json({ threads: rows });
+  });
+
+  app.get("/:threadId", async (c) => {
+    const threadId = c.req.param("threadId");
+    const dataPath = await resolveThreadDataPath(storageRoot, threadId);
+    if (dataPath === null) {
+      return c.json({ error: `thread not found: ${threadId}` }, 404);
+    }
+    const text = await readTextFileIfExists(dataPath);
+    if (text === null) {
+      return c.json({ error: `thread data missing: ${threadId}` }, 404);
+    }
+    const lines = text.trim().split("\n");
+    const records = lines.map((line) => {
+      try {
+        return JSON.parse(line) as unknown;
+      } catch {
+        return { raw: line };
+      }
+    });
+    return c.json({ threadId, records });
+  });
+
+  return app;
+}

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

@@ -0,0 +1,55 @@
+import {
+  getRegisteredWorkflow,
+  listRegisteredWorkflowNames,
+  readWorkflowRegistry,
+} from "@uncaged/workflow";
+import { Hono } from "hono";
+
+export function createWorkflowRoutes(storageRoot: string): Hono {
+  const app = new Hono();
+
+  app.get("/", async (c) => {
+    const reg = await readWorkflowRegistry(storageRoot);
+    if (!reg.ok) {
+      return c.json({ error: reg.error.message }, 500);
+    }
+    const names = listRegisteredWorkflowNames(reg.value);
+    const workflows = names.map((name) => {
+      const entry = reg.value.workflows[name];
+      return {
+        name,
+        hash: entry?.hash ?? null,
+        timestamp: entry?.timestamp ?? null,
+      };
+    });
+    return c.json({ workflows });
+  });
+
+  app.get("/:name", async (c) => {
+    const reg = await readWorkflowRegistry(storageRoot);
+    if (!reg.ok) {
+      return c.json({ error: reg.error.message }, 500);
+    }
+    const name = c.req.param("name");
+    const entry = getRegisteredWorkflow(reg.value, name);
+    if (entry === null) {
+      return c.json({ error: `workflow not found: ${name}` }, 404);
+    }
+    return c.json({ name, ...entry });
+  });
+
+  app.get("/:name/history", async (c) => {
+    const reg = await readWorkflowRegistry(storageRoot);
+    if (!reg.ok) {
+      return c.json({ error: reg.error.message }, 500);
+    }
+    const name = c.req.param("name");
+    const entry = getRegisteredWorkflow(reg.value, name);
+    if (entry === null) {
+      return c.json({ error: `workflow not found: ${name}` }, 404);
+    }
+    return c.json({ name, history: entry.history });
+  });
+
+  return app;
+}

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

@@ -0,0 +1,69 @@
+import { err, ok, type Result } from "@uncaged/workflow";
+import { serve } from "bun";
+
+import { printCliLine } from "../../cli-output.js";
+import { createApp } from "./app.js";
+import type { ServeOptions } from "./types.js";
+
+export function startServer(storageRoot: string, options: ServeOptions): void {
+  const app = createApp(storageRoot);
+
+  const server = serve({
+    fetch: app.fetch,
+    port: options.port,
+    hostname: options.hostname,
+  });
+
+  printCliLine(`uncaged-workflow API server listening on http://${server.hostname}:${server.port}`);
+}
+
+function parsePortValue(value: string | undefined): Result<number, string> {
+  if (value === undefined) {
+    return err("--port requires a value");
+  }
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isFinite(parsed) || parsed < 0 || parsed > 65535) {
+    return err(`invalid port: ${value}`);
+  }
+  return ok(parsed);
+}
+
+function parseServeArgv(argv: string[]): Result<ServeOptions, string> {
+  let port = 7860;
+  let hostname = "127.0.0.1";
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--port" || arg === "-p") {
+      const portResult = parsePortValue(argv[i + 1]);
+      if (!portResult.ok) {
+        return portResult;
+      }
+      port = portResult.value;
+      i++;
+    } else if (arg === "--host") {
+      const next = argv[i + 1];
+      if (next === undefined) {
+        return err("--host requires a value");
+      }
+      hostname = next;
+      i++;
+    }
+  }
+
+  return ok({ port, hostname });
+}
+
+export async function dispatchServe(storageRoot: string, argv: string[]): Promise<number> {
+  const parsed = parseServeArgv(argv);
+  if (!parsed.ok) {
+    printCliLine(`error: ${parsed.error}`);
+    return 1;
+  }
+
+  startServer(storageRoot, parsed.value);
+
+  // Keep process alive
+  await new Promise(() => {});
+  return 0;
+}

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

@@ -0,0 +1,4 @@
+export type ServeOptions = {
+  port: number;
+  hostname: string;
+};

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

@@ -9,8 +9,8 @@ import {
   getGlobalCasDir,
   tryParseRoleStepRecord,
   tryParseWorkflowResultRecord,
-  type WorkflowCompletion,
 } from "@uncaged/workflow";
+import type { WorkflowCompletion } from "@uncaged/workflow-runtime";
 
 import { dimGreyLine, highlightLiveRole } from "../../cli-color.js";
 import { printCliError, printCliLine } from "../../cli-output.js";

packages/cli-workflow/tsconfig.json

@@ -17,6 +17,6 @@
     "rootDir": "src",
     "types": ["bun-types"]
   },
-  "references": [{ "path": "../workflow" }],
+  "references": [{ "path": "../workflow-runtime" }, { "path": "../workflow" }],
   "include": ["src/**/*.ts"]
 }

packages/dashboard/README.md

@@ -0,0 +1,24 @@
+# @uncaged/workflow-dashboard
+
+Web dashboard for the Uncaged Workflow engine. Connects to the local
+`uncaged-workflow serve` API to display threads, workflows, and CAS data.
+
+## Development
+
+```bash
+# Start the local API server (in another terminal)
+uncaged-workflow serve
+
+# Start the dashboard dev server
+bun run dev
+```
+
+Opens at http://localhost:5173. Vite proxies `/api/*` to `localhost:7860`.
+
+## Build
+
+```bash
+bun run build
+```
+
+Output goes to `dist/` — static files ready for CF Pages or any host.

packages/dashboard/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Workflow Dashboard</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

packages/dashboard/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@uncaged/workflow-dashboard",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "react": "^19.2.6",
+    "react-dom": "^19.2.6"
+  },
+  "devDependencies": {
+    "@tailwindcss/vite": "^4.2.4",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^6.0.1",
+    "tailwindcss": "^4.2.4",
+    "typescript": "^6.0.3",
+    "vite": "^8.0.11"
+  }
+}

packages/dashboard/src/api.ts

@@ -0,0 +1,51 @@
+const BASE = "/api";
+
+async function fetchJson<T>(path: string): Promise<T> {
+  const res = await fetch(`${BASE}${path}`);
+  if (!res.ok) {
+    throw new Error(`API ${res.status}: ${path}`);
+  }
+  return res.json() as Promise<T>;
+}
+
+export type WorkflowSummary = {
+  name: string;
+  currentHash: string;
+  versions: number;
+};
+
+export type ThreadSummary = {
+  threadId: string;
+  workflow: string | null;
+  hash: string | null;
+  startedAt: string | null;
+  status: string | null;
+};
+
+export type ThreadRecord = {
+  type: string;
+  role: string | null;
+  content: string | null;
+  timestamp: number | null;
+  [key: string]: unknown;
+};
+
+export function listWorkflows(): Promise<{ workflows: WorkflowSummary[] }> {
+  return fetchJson("/workflows");
+}
+
+export function listThreads(): Promise<{ threads: ThreadSummary[] }> {
+  return fetchJson("/threads");
+}
+
+export function listRunningThreads(): Promise<{ threads: ThreadSummary[] }> {
+  return fetchJson("/threads/running");
+}
+
+export function getThread(id: string): Promise<{ records: ThreadRecord[] }> {
+  return fetchJson(`/threads/${id}`);
+}
+
+export function getHealth(): Promise<{ ok: boolean }> {
+  return fetchJson("/healthz");
+}

packages/dashboard/src/app.tsx

@@ -0,0 +1,31 @@
+import { useState } from "react";
+import { Sidebar } from "./components/sidebar.tsx";
+import { ThreadList } from "./components/thread-list.tsx";
+import { ThreadDetail } from "./components/thread-detail.tsx";
+import { WorkflowList } from "./components/workflow-list.tsx";
+import { StatusBar } from "./components/status-bar.tsx";
+
+type View = "threads" | "workflows";
+
+export function App() {
+  const [view, setView] = useState<View>("threads");
+  const [selectedThread, setSelectedThread] = useState<string | null>(null);
+
+  return (
+    <div className="flex h-screen">
+      <Sidebar view={view} onViewChange={setView} />
+      <main className="flex-1 overflow-hidden flex flex-col">
+        <StatusBar />
+        <div className="flex-1 overflow-auto p-6">
+          {view === "threads" && !selectedThread && (
+            <ThreadList onSelect={setSelectedThread} />
+          )}
+          {view === "threads" && selectedThread && (
+            <ThreadDetail threadId={selectedThread} onBack={() => setSelectedThread(null)} />
+          )}
+          {view === "workflows" && <WorkflowList />}
+        </div>
+      </main>
+    </div>
+  );
+}

packages/dashboard/src/components/sidebar.tsx

@@ -0,0 +1,37 @@
+type Props = {
+  view: "threads" | "workflows";
+  onViewChange: (v: "threads" | "workflows") => void;
+};
+
+export function Sidebar({ view, onViewChange }: Props) {
+  const items = [
+    { key: "threads" as const, label: "Threads", icon: "⚡" },
+    { key: "workflows" as const, label: "Workflows", icon: "📦" },
+  ];
+
+  return (
+    <aside className="w-56 border-r flex flex-col" style={{ borderColor: "var(--color-border)", background: "var(--color-surface)" }}>
+      <div className="p-4 border-b" style={{ borderColor: "var(--color-border)" }}>
+        <h1 className="text-lg font-semibold" style={{ color: "var(--color-accent)" }}>
+          ⚙ Workflow
+        </h1>
+        <p className="text-xs mt-1" style={{ color: "var(--color-text-muted)" }}>Dashboard</p>
+      </div>
+      <nav className="flex-1 p-2 space-y-1">
+        {items.map((item) => (
+          <button
+            key={item.key}
+            onClick={() => onViewChange(item.key)}
+            className="w-full text-left px-3 py-2 rounded text-sm transition-colors"
+            style={{
+              background: view === item.key ? "var(--color-accent-dim)" : "transparent",
+              color: view === item.key ? "#fff" : "var(--color-text-muted)",
+            }}
+          >
+            {item.icon} {item.label}
+          </button>
+        ))}
+      </nav>
+    </aside>
+  );
+}

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

@@ -0,0 +1,24 @@
+import { getHealth } from "../api.ts";
+import { useFetch } from "../hooks.ts";
+
+export function StatusBar() {
+  const health = useFetch(() => getHealth(), []);
+
+  return (
+    <div
+      className="flex items-center justify-between px-6 py-2 text-xs border-b"
+      style={{ borderColor: "var(--color-border)", background: "var(--color-surface)" }}
+    >
+      <span style={{ color: "var(--color-text-muted)" }}>Local API: 127.0.0.1:7860</span>
+      <span>
+        {health.status === "loading" && "⏳ Connecting..."}
+        {health.status === "ok" && (
+          <span style={{ color: "var(--color-success)" }}>● Connected</span>
+        )}
+        {health.status === "error" && (
+          <span style={{ color: "var(--color-error)" }}>● Offline</span>
+        )}
+      </span>
+    </div>
+  );
+}

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

@@ -0,0 +1,62 @@
+import { getThread } from "../api.ts";
+import { useFetch } from "../hooks.ts";
+
+type Props = {
+  threadId: string;
+  onBack: () => void;
+};
+
+export function ThreadDetail({ threadId, onBack }: Props) {
+  const { status, data, error } = useFetch(() => getThread(threadId), [threadId]);
+
+  return (
+    <div>
+      <button
+        onClick={onBack}
+        className="text-sm mb-4 hover:underline"
+        style={{ color: "var(--color-accent)" }}
+      >
+        ← Back to threads
+      </button>
+      <h2 className="text-xl font-semibold mb-4 font-mono">{threadId}</h2>
+
+      {status === "loading" && <p style={{ color: "var(--color-text-muted)" }}>Loading...</p>}
+      {status === "error" && <p style={{ color: "var(--color-error)" }}>Error: {error}</p>}
+      {status === "ok" && (
+        <div className="space-y-3">
+          {data.records.map((r, i) => (
+            <div
+              key={i}
+              className="p-3 rounded border text-sm"
+              style={{ background: "var(--color-surface)", borderColor: "var(--color-border)" }}
+            >
+              <div className="flex items-center gap-2 mb-1">
+                <span
+                  className="text-xs px-1.5 py-0.5 rounded font-mono"
+                  style={{ background: "var(--color-border)", color: "var(--color-accent)" }}
+                >
+                  {r.type}
+                </span>
+                {r.role && (
+                  <span className="text-xs" style={{ color: "var(--color-text-muted)" }}>
+                    {r.role}
+                  </span>
+                )}
+                {r.timestamp && (
+                  <span className="text-xs ml-auto" style={{ color: "var(--color-text-muted)" }}>
+                    {new Date(r.timestamp).toLocaleTimeString()}
+                  </span>
+                )}
+              </div>
+              {r.content && (
+                <pre className="whitespace-pre-wrap text-xs mt-1" style={{ color: "var(--color-text)" }}>
+                  {typeof r.content === "string" ? r.content : JSON.stringify(r.content, null, 2)}
+                </pre>
+              )}
+            </div>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}

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

@@ -0,0 +1,67 @@
+import { listThreads } from "../api.ts";
+import { useFetch } from "../hooks.ts";
+
+type Props = {
+  onSelect: (id: string) => void;
+};
+
+export function ThreadList({ onSelect }: Props) {
+  const { status, data, error } = useFetch(() => listThreads(), []);
+
+  if (status === "loading") return <p style={{ color: "var(--color-text-muted)" }}>Loading threads...</p>;
+  if (status === "error") return <p style={{ color: "var(--color-error)" }}>Error: {error}</p>;
+
+  const threads = data.threads;
+
+  return (
+    <div>
+      <h2 className="text-xl font-semibold mb-4">Threads</h2>
+      {threads.length === 0 ? (
+        <p style={{ color: "var(--color-text-muted)" }}>No threads found.</p>
+      ) : (
+        <div className="space-y-2">
+          {threads.map((t) => (
+            <button
+              key={t.threadId}
+              onClick={() => onSelect(t.threadId)}
+              className="w-full text-left p-4 rounded-lg border transition-colors hover:border-[var(--color-accent-dim)]"
+              style={{ background: "var(--color-surface)", borderColor: "var(--color-border)" }}
+            >
+              <div className="flex items-center justify-between">
+                <code className="text-sm font-mono" style={{ color: "var(--color-accent)" }}>
+                  {t.threadId}
+                </code>
+                {t.status && (
+                  <span
+                    className="text-xs px-2 py-0.5 rounded"
+                    style={{
+                      background:
+                        t.status === "running"
+                          ? "var(--color-success)"
+                          : t.status === "failed"
+                            ? "var(--color-error)"
+                            : "var(--color-text-muted)",
+                      color: "#000",
+                    }}
+                  >
+                    {t.status}
+                  </span>
+                )}
+              </div>
+              {t.workflow && (
+                <p className="text-sm mt-1" style={{ color: "var(--color-text-muted)" }}>
+                  {t.workflow}
+                </p>
+              )}
+              {t.startedAt && (
+                <p className="text-xs mt-1" style={{ color: "var(--color-text-muted)" }}>
+                  {t.startedAt}
+                </p>
+              )}
+            </button>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}

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

@@ -0,0 +1,40 @@
+import { listWorkflows } from "../api.ts";
+import { useFetch } from "../hooks.ts";
+
+export function WorkflowList() {
+  const { status, data, error } = useFetch(() => listWorkflows(), []);
+
+  if (status === "loading") return <p style={{ color: "var(--color-text-muted)" }}>Loading workflows...</p>;
+  if (status === "error") return <p style={{ color: "var(--color-error)" }}>Error: {error}</p>;
+
+  const workflows = data.workflows;
+
+  return (
+    <div>
+      <h2 className="text-xl font-semibold mb-4">Workflows</h2>
+      {workflows.length === 0 ? (
+        <p style={{ color: "var(--color-text-muted)" }}>No workflows registered.</p>
+      ) : (
+        <div className="space-y-2">
+          {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/dashboard/src/hooks.ts

@@ -0,0 +1,36 @@
+import { useEffect, useState } from "react";
+
+type FetchState<T> =
+  | { status: "loading"; data: null; error: null }
+  | { status: "ok"; data: T; error: null }
+  | { status: "error"; data: null; error: string };
+
+export function useFetch<T>(fetcher: () => Promise<T>, deps: unknown[] = []): FetchState<T> {
+  const [state, setState] = useState<FetchState<T>>({
+    status: "loading",
+    data: null,
+    error: null,
+  });
+
+  useEffect(() => {
+    let cancelled = false;
+    setState({ status: "loading", data: null, error: null });
+    fetcher()
+      .then((data) => {
+        if (!cancelled) setState({ status: "ok", data, error: null });
+      })
+      .catch((err: unknown) => {
+        if (!cancelled)
+          setState({
+            status: "error",
+            data: null,
+            error: err instanceof Error ? err.message : String(err),
+          });
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, deps);
+
+  return state;
+}

packages/dashboard/src/index.css

@@ -0,0 +1,21 @@
+@import "tailwindcss";
+
+:root {
+  --color-bg: #0a0a0f;
+  --color-surface: #12121a;
+  --color-border: #1e1e2e;
+  --color-text: #e4e4ef;
+  --color-text-muted: #6b6b8a;
+  --color-accent: #7c6df0;
+  --color-accent-dim: #5a4db8;
+  --color-success: #34d399;
+  --color-warning: #fbbf24;
+  --color-error: #f87171;
+}
+
+body {
+  margin: 0;
+  background: var(--color-bg);
+  color: var(--color-text);
+  font-family: "Inter", system-ui, -apple-system, sans-serif;
+}

packages/dashboard/src/main.tsx

@@ -0,0 +1,13 @@
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import "./index.css";
+import { App } from "./app.tsx";
+
+const root = document.getElementById("root");
+if (root) {
+  createRoot(root).render(
+    <StrictMode>
+      <App />
+    </StrictMode>,
+  );
+}

packages/dashboard/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "jsx": "react-jsx",
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true
+  },
+  "include": ["src"]
+}

packages/dashboard/vite.config.ts

@@ -0,0 +1,16 @@
+import tailwindcss from "@tailwindcss/vite";
+import react from "@vitejs/plugin-react";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  plugins: [react(), tailwindcss()],
+  server: {
+    port: 5173,
+    proxy: {
+      "/api": {
+        target: "http://127.0.0.1:7860",
+        changeOrigin: true,
+      },
+    },
+  },
+});

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

@@ -1,5 +1,5 @@
 import { describe, expect, test } from "bun:test";
-import type { ExtractContext, ExtractFn } from "@uncaged/workflow";
+import type { ExtractContext, ExtractFn } from "@uncaged/workflow-runtime";
 import type * as z from "zod/v4";
 import { createCursorAgent, validateCursorAgentConfig } from "../src/index.js";
 

packages/workflow-agent-cursor/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uncaged/workflow-agent-cursor",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -8,7 +8,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@uncaged/workflow": "workspace:*",
+    "@uncaged/workflow-runtime": "workspace:*",
     "@uncaged/workflow-util-agent": "workspace:*",
     "zod": "^4.0.0"
   }

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

@@ -1,4 +1,4 @@
-import type { AgentFn, ExtractContext } from "@uncaged/workflow";
+import type { AgentFn, ExtractContext } from "@uncaged/workflow-runtime";
 import { buildAgentPrompt, type SpawnCliError, spawnCli } from "@uncaged/workflow-util-agent";
 import * as z from "zod/v4";
 

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

@@ -1,4 +1,4 @@
-import type { ExtractFn } from "@uncaged/workflow";
+import type { ExtractFn } from "@uncaged/workflow-runtime";
 
 export type CursorAgentConfig = {
   model: string | null;

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

@@ -1,4 +1,4 @@
-import { err, ok, type Result } from "@uncaged/workflow";
+import { err, ok, type Result } from "@uncaged/workflow-runtime";
 
 import type { CursorAgentConfig } from "./types.js";
 

packages/workflow-agent-hermes/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uncaged/workflow-agent-hermes",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -8,7 +8,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@uncaged/workflow": "workspace:*",
+    "@uncaged/workflow-runtime": "workspace:*",
     "@uncaged/workflow-util-agent": "workspace:*"
   }
 }

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

@@ -1,4 +1,4 @@
-import type { AgentFn } from "@uncaged/workflow";
+import type { AgentFn } from "@uncaged/workflow-runtime";
 import { buildAgentPrompt, type SpawnCliError, spawnCli } from "@uncaged/workflow-util-agent";
 
 import type { HermesAgentConfig } from "./types.js";

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

@@ -1,4 +1,4 @@
-import { err, ok, type Result } from "@uncaged/workflow";
+import { err, ok, type Result } from "@uncaged/workflow-runtime";
 
 import type { HermesAgentConfig } from "./types.js";
 

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

@@ -2,7 +2,8 @@ import { describe, expect, test } from "bun:test";
 import { mkdtempSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { createCasStore, START, type ThreadContext } from "@uncaged/workflow";
+import { createCasStore } from "@uncaged/workflow";
+import { START, type ThreadContext } from "@uncaged/workflow-runtime";
 
 import { createLlmAdapter } from "../src/create-llm-adapter.js";
 

packages/workflow-agent-llm/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uncaged/workflow-agent-llm",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -8,6 +8,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@uncaged/workflow": "workspace:*"
+    "@uncaged/workflow": "workspace:*",
+    "@uncaged/workflow-runtime": "workspace:*"
   }
 }

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

@@ -5,7 +5,7 @@ import {
   type LlmProvider,
   ok,
   type Result,
-} from "@uncaged/workflow";
+} from "@uncaged/workflow-runtime";
 
 /** OpenAI chat completion message shape (passed to `/chat/completions`). */
 export type LlmMessage = { role: "system" | "user" | "assistant"; content: string };

packages/workflow-runtime/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@uncaged/workflow-runtime",
+  "version": "0.2.0",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "scripts": {
+    "test": "bun test"
+  },
+  "peerDependencies": {
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "zod": "^4.0.0"
+  }
+}

packages/workflow-runtime/src/bundle/index.ts

@@ -0,0 +1,2 @@
+export type { WorkflowDescriptor, WorkflowRoleDescriptor, WorkflowRoleSchema } from "./types.js";
+export { validateWorkflowDescriptor } from "./workflow-descriptor.js";

packages/workflow-runtime/src/bundle/types.ts

@@ -0,0 +1,13 @@
+/** JSON Schema fragment describing one role's `meta` shape (subset supported by code generation). */
+export type WorkflowRoleSchema = Record<string, unknown>;
+
+export type WorkflowRoleDescriptor = {
+  description: string;
+  schema: WorkflowRoleSchema;
+};
+
+/** Workflow metadata exported as `export const descriptor` from `.esm.js` bundles. */
+export type WorkflowDescriptor = {
+  description: string;
+  roles: Record<string, WorkflowRoleDescriptor>;
+};

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

@@ -0,0 +1,40 @@
+import { err, ok, type Result } from "../util/index.js";
+
+import type { WorkflowDescriptor, WorkflowRoleDescriptor, WorkflowRoleSchema } from "./types.js";
+
+export function validateWorkflowDescriptor(value: unknown): Result<WorkflowDescriptor, string> {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    return err("descriptor must be a non-array object");
+  }
+  const root = value as Record<string, unknown>;
+  const description = root.description;
+  if (typeof description !== "string") {
+    return err("descriptor.description must be a string");
+  }
+  const rolesRaw = root.roles;
+  if (rolesRaw === null || typeof rolesRaw !== "object" || Array.isArray(rolesRaw)) {
+    return err("descriptor.roles must be a non-array object");
+  }
+
+  const roles: Record<string, WorkflowRoleDescriptor> = {};
+  for (const [roleName, specUnknown] of Object.entries(rolesRaw)) {
+    if (specUnknown === null || typeof specUnknown !== "object" || Array.isArray(specUnknown)) {
+      return err(`descriptor.roles.${roleName} must be a non-array object`);
+    }
+    const spec = specUnknown as Record<string, unknown>;
+    const roleDesc = spec.description;
+    if (typeof roleDesc !== "string") {
+      return err(`descriptor.roles.${roleName}.description must be a string`);
+    }
+    const schema = spec.schema;
+    if (schema === null || typeof schema !== "object" || Array.isArray(schema)) {
+      return err(`descriptor.roles.${roleName}.schema must be a non-array object`);
+    }
+    roles[roleName] = {
+      description: roleDesc,
+      schema: schema as WorkflowRoleSchema,
+    };
+  }
+
+  return ok({ description, roles });
+}

packages/workflow-runtime/src/cas/index.ts

@@ -0,0 +1 @@
+export type { CasStore } from "./types.js";

packages/workflow-runtime/src/cas/types.ts

@@ -0,0 +1,6 @@
+export type CasStore = {
+  put(content: string): Promise<string>;
+  get(hash: string): Promise<string | null>;
+  delete(hash: string): Promise<void>;
+  list(): Promise<string[]>;
+};

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

@@ -0,0 +1,185 @@
+import type { CasStore } from "../cas/types.js";
+import {
+  type AgentBinding,
+  type AgentContext,
+  type AgentFn,
+  END,
+  type ExtractContext,
+  type ModeratorContext,
+  type ResolveRoleMetaFn,
+  type RoleDefinition,
+  type RoleMeta,
+  type RoleOutput,
+  type RoleStep,
+  START,
+  type ThreadInput,
+  type WorkflowCompletion,
+  type WorkflowDefinition,
+  type WorkflowFn,
+  type WorkflowFnOptions,
+} from "../types.js";
+import { mergeRefsWithContentHash } from "../util/index.js";
+
+function isRoleNext<M extends RoleMeta>(
+  next: (keyof M & string) | typeof END,
+): next is keyof M & string {
+  return next !== END;
+}
+
+function resolveExtractedRefs(
+  roleDef: RoleDefinition<Record<string, unknown>>,
+  meta: unknown,
+): string[] {
+  const extractRefsFn = roleDef.extractRefs;
+  if (extractRefsFn === null || typeof extractRefsFn !== "function") {
+    return [];
+  }
+  return extractRefsFn(meta as Record<string, unknown>);
+}
+
+async function putContentBlob(store: CasStore, raw: string): Promise<string> {
+  return store.put(raw);
+}
+
+function agentForRole(binding: AgentBinding, roleName: string): AgentFn {
+  const overrides = binding.overrides;
+  const overrideFn: AgentFn | undefined =
+    overrides !== null ? overrides[roleName as keyof typeof overrides] : undefined;
+  return overrideFn !== undefined ? overrideFn : binding.agent;
+}
+
+type AdvanceOutcome<M extends RoleMeta> =
+  | { kind: "complete"; completion: WorkflowCompletion }
+  | { kind: "yield"; output: RoleOutput; step: RoleStep<M> };
+
+async function advanceOneRound<M extends RoleMeta>(
+  def: Pick<WorkflowDefinition<M>, "roles" | "moderator">,
+  binding: AgentBinding,
+  resolveRoleMeta: ResolveRoleMetaFn<M>,
+  params: {
+    start: ModeratorContext<M>["start"];
+    steps: RoleStep<M>[];
+    options: WorkflowFnOptions;
+  },
+): Promise<AdvanceOutcome<M>> {
+  const { start, steps, options } = params;
+  const modCtx: ModeratorContext<M> = {
+    threadId: options.threadId,
+    depth: options.depth,
+    start,
+    steps,
+  };
+
+  const next = def.moderator(modCtx);
+  if (!isRoleNext(next)) {
+    return {
+      kind: "complete",
+      completion: { returnCode: 0, summary: "completed: moderator returned END" },
+    };
+  }
+
+  const roleDef = def.roles[next];
+  if (roleDef === undefined) {
+    return { kind: "complete", completion: { returnCode: 1, summary: `unknown role: ${next}` } };
+  }
+
+  const agentCtx: AgentContext<M> = {
+    ...modCtx,
+    currentRole: { name: next, systemPrompt: roleDef.systemPrompt },
+    cas: options.cas,
+  };
+
+  const agent = agentForRole(binding, next);
+  const raw = await agent(agentCtx as unknown as AgentContext);
+
+  const extractCtx: ExtractContext<M> = {
+    ...agentCtx,
+    agentContent: raw,
+  };
+
+  const meta = await resolveRoleMeta(
+    roleDef as unknown as RoleDefinition<Record<string, unknown>>,
+    extractCtx,
+    options,
+  );
+
+  const contentHash = await putContentBlob(options.cas, raw);
+  const refs = mergeRefsWithContentHash(
+    resolveExtractedRefs(roleDef as unknown as RoleDefinition<Record<string, unknown>>, meta),
+    contentHash,
+  );
+
+  const step = {
+    role: next,
+    contentHash,
+    meta,
+    refs,
+    timestamp: Date.now(),
+  } as RoleStep<M>;
+
+  return {
+    kind: "yield",
+    output: {
+      role: step.role,
+      contentHash: step.contentHash,
+      meta: step.meta,
+      refs: step.refs,
+    },
+    step,
+  };
+}
+
+/**
+ * Binds pure role definitions + moderator to runtime agents.
+ * Assign with `export const run = createWorkflow(def, binding)` via `@uncaged/workflow-runtime`,
+ * which supplies {@link ResolveRoleMetaFn}.
+ */
+export function createWorkflow<M extends RoleMeta>(
+  def: Pick<WorkflowDefinition<M>, "roles" | "moderator">,
+  binding: AgentBinding,
+  resolveRoleMeta: ResolveRoleMetaFn<M>,
+): WorkflowFn {
+  return async function* workflowLoop(
+    input: ThreadInput,
+    options: WorkflowFnOptions,
+  ): AsyncGenerator<RoleOutput, WorkflowCompletion> {
+    const nowMs = Date.now();
+    const start: ModeratorContext<M>["start"] = {
+      role: START,
+      content: input.prompt,
+      meta: { maxRounds: options.maxRounds },
+      timestamp: nowMs,
+    };
+
+    const baseTs = Date.now();
+    let steps: RoleStep<M>[] = input.steps.map((out, i) => ({
+      role: out.role,
+      contentHash: out.contentHash,
+      meta: out.meta,
+      refs: out.refs,
+      timestamp: baseTs + i,
+    })) as RoleStep<M>[];
+
+    while (true) {
+      if (steps.length >= options.maxRounds) {
+        return {
+          returnCode: 0,
+          summary: `completed: reached maxRounds (${options.maxRounds})`,
+        };
+      }
+
+      const outcome = await advanceOneRound(def, binding, resolveRoleMeta, {
+        start,
+        steps,
+        options,
+      });
+
+      if (outcome.kind === "complete") {
+        return outcome.completion;
+      }
+
+      yield outcome.output;
+      steps = [...steps, outcome.step];
+    }
+  };
+}

packages/workflow-runtime/src/engine/index.ts

@@ -0,0 +1 @@
+export { createWorkflow } from "./create-workflow.js";

packages/workflow-runtime/src/extract/index.ts

@@ -0,0 +1 @@
+export type { ExtractFn } from "./types.js";

packages/workflow-runtime/src/extract/types.ts

@@ -0,0 +1,9 @@
+import type * as z from "zod/v4";
+
+import type { ExtractContext } from "../types.js";
+
+export type ExtractFn = <T extends Record<string, unknown>>(
+  schema: z.ZodType<T>,
+  prompt: string,
+  ctx: ExtractContext,
+) => Promise<T>;

packages/workflow-runtime/src/index.ts

@@ -0,0 +1,35 @@
+export type {
+  WorkflowDescriptor,
+  WorkflowRoleDescriptor,
+  WorkflowRoleSchema,
+} from "./bundle/types.js";
+export { validateWorkflowDescriptor } from "./bundle/workflow-descriptor.js";
+export type { CasStore } from "./cas/index.js";
+export { createWorkflow } from "./engine/index.js";
+export type { ExtractFn } from "./extract/index.js";
+export type {
+  AgentBinding,
+  AgentContext,
+  AgentFn,
+  ExtractContext,
+  ExtractMode,
+  LlmProvider,
+  Moderator,
+  ModeratorContext,
+  ResolveRoleMetaFn,
+  RoleDefinition,
+  RoleMeta,
+  RoleOutput,
+  RoleStep,
+  StartStep,
+  ThreadContext,
+  ThreadInput,
+  WorkflowCompletion,
+  WorkflowDefinition,
+  WorkflowFn,
+  WorkflowFnOptions,
+  WorkflowResult,
+} from "./types.js";
+export { END, START } from "./types.js";
+export type { Result } from "./util/index.js";
+export { err, ok } from "./util/index.js";

packages/workflow-runtime/src/types.ts

@@ -36,7 +36,7 @@ export type WorkflowCompletion = {
   summary: string;
 };
 
-/** Final thread outcome from {@link executeThread}, including Merkle thread root CAS hash. */
+/** Final thread outcome from executeThread, including Merkle thread root CAS hash. */
 export type WorkflowResult = WorkflowCompletion & {
   rootHash: string;
 };
@@ -115,10 +115,10 @@ export type ThreadContext<M extends RoleMeta = RoleMeta> = AgentContext<M>;
 /** Raw string output from an LLM/CLI adapter; meta is extracted by the engine. */
 export type AgentFn = (ctx: AgentContext) => Promise<string>;
 
-/** Runtime agent assignment (optional per-role overrides). */
+/** Runtime agent assignment (explicit null when no per-role overrides). */
 export type AgentBinding = {
   agent: AgentFn;
-  overrides?: Partial<Record<string, AgentFn>>;
+  overrides: Partial<Record<string, AgentFn>> | null;
 };
 
 /** Role wiring: prompts, schema, and human-readable description. */
@@ -148,3 +148,10 @@ export type WorkflowDefinition<M extends RoleMeta> = {
   roles: { [K in keyof M & string]: RoleDefinition<M[K]> };
   moderator: Moderator<M>;
 };
+
+/** Engine-injected meta extraction for workflow loops (single + react modes). */
+export type ResolveRoleMetaFn<M extends RoleMeta = RoleMeta> = (
+  roleDef: RoleDefinition<Record<string, unknown>>,
+  extractCtx: ExtractContext<M>,
+  options: WorkflowFnOptions,
+) => Promise<Record<string, unknown>>;

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

@@ -0,0 +1,3 @@
+export { mergeRefsWithContentHash } from "./refs-field.js";
+export { err, ok } from "./result.js";
+export type { Result } from "./types.js";

packages/workflow-runtime/src/util/refs-field.ts

@@ -0,0 +1,8 @@
+/** Append `contentHash` to `refs` when not already present (dedupe by first occurrence order). */
+export function mergeRefsWithContentHash(refs: string[], contentHash: string): string[] {
+  const out = [...refs];
+  if (!out.includes(contentHash)) {
+    out.push(contentHash);
+  }
+  return out;
+}

packages/workflow-runtime/src/util/result.ts

@@ -0,0 +1,9 @@
+import type { Result } from "./types.js";
+
+export function ok<T>(value: T): Result<T, never> {
+  return { ok: true, value };
+}
+
+export function err<E>(error: E): Result<never, E> {
+  return { ok: false, error };
+}

packages/workflow-runtime/src/util/types.ts

@@ -0,0 +1 @@
+export type Result<T, E = Error> = { ok: true; value: T } | { ok: false; error: E };

packages/workflow-runtime/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022"],
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "exactOptionalPropertyTypes": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "composite": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "types": ["bun-types"]
+  },
+  "include": ["src/**/*.ts"]
+}

packages/workflow-template-develop/__tests__/develop-template.test.ts

@@ -5,7 +5,7 @@ import {
   type RoleStep,
   START,
   validateWorkflowDescriptor,
-} from "@uncaged/workflow";
+} from "@uncaged/workflow-runtime";
 import { buildDevelopDescriptor } from "../src/descriptor.js";
 import { developModerator } from "../src/index.js";
 import type { CommitterMeta, PlannerMeta } from "../src/roles/index.js";

packages/workflow-template-develop/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uncaged/workflow-template-develop",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -9,6 +9,7 @@
   },
   "dependencies": {
     "@uncaged/workflow": "workspace:*",
+    "@uncaged/workflow-runtime": "workspace:*",
     "zod": "^4.0.0"
   }
 }

packages/workflow-template-develop/src/index.ts

@@ -1,9 +1,5 @@
-import {
-  type AgentBinding,
-  createWorkflow,
-  type WorkflowDefinition,
-  type WorkflowFn,
-} from "@uncaged/workflow";
+import { createWorkflow } from "@uncaged/workflow";
+import type { AgentBinding, WorkflowDefinition, WorkflowFn } from "@uncaged/workflow-runtime";
 
 import { developModerator } from "./moderator.js";
 import { DEVELOP_WORKFLOW_DESCRIPTION, type DevelopMeta, developRoles } from "./roles.js";

packages/workflow-template-develop/src/moderator.ts

@@ -1,5 +1,5 @@
-import type { Moderator, ModeratorContext } from "@uncaged/workflow";
-import { END } from "@uncaged/workflow";
+import type { Moderator, ModeratorContext } from "@uncaged/workflow-runtime";
+import { END } from "@uncaged/workflow-runtime";
 
 import type { DevelopMeta } from "./roles.js";
 

packages/workflow-template-develop/src/roles.ts

@@ -1,4 +1,4 @@
-import type { RoleDefinition } from "@uncaged/workflow";
+import type { RoleDefinition } from "@uncaged/workflow-runtime";
 import { type CoderMeta, coderRole } from "./roles/coder.js";
 import { type CommitterMeta, committerRole } from "./roles/committer.js";
 import { type PlannerMeta, plannerRole } from "./roles/planner.js";

packages/workflow-template-develop/src/roles/coder.ts

@@ -1,4 +1,4 @@
-import type { RoleDefinition } from "@uncaged/workflow";
+import type { RoleDefinition } from "@uncaged/workflow-runtime";
 import * as z from "zod/v4";
 
 export const coderMetaSchema = z.object({

packages/workflow-template-develop/src/roles/committer.ts

@@ -1,4 +1,4 @@
-import type { RoleDefinition } from "@uncaged/workflow";
+import type { RoleDefinition } from "@uncaged/workflow-runtime";
 import * as z from "zod/v4";
 
 export const committerMetaSchema = z.discriminatedUnion("status", [

packages/workflow-template-develop/src/roles/planner.ts

@@ -1,4 +1,4 @@
-import type { RoleDefinition } from "@uncaged/workflow";
+import type { RoleDefinition } from "@uncaged/workflow-runtime";
 import * as z from "zod/v4";
 
 export const phaseSchema = z.object({

packages/workflow-template-develop/src/roles/reviewer.ts

@@ -1,4 +1,4 @@
-import type { RoleDefinition } from "@uncaged/workflow";
+import type { RoleDefinition } from "@uncaged/workflow-runtime";
 import * as z from "zod/v4";
 
 export const reviewerMetaSchema = z.discriminatedUnion("status", [

packages/workflow-template-develop/src/roles/tester.ts

@@ -1,4 +1,4 @@
-import type { RoleDefinition } from "@uncaged/workflow";
+import type { RoleDefinition } from "@uncaged/workflow-runtime";
 import * as z from "zod/v4";
 
 export const testerMetaSchema = z.discriminatedUnion("status", [

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

@@ -2,15 +2,14 @@ import { afterEach, describe, expect, test } from "bun:test";
 import { mkdtemp, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { createCasStore, createExtract } from "@uncaged/workflow";
 import {
-  createCasStore,
-  createExtract,
   END,
   type ModeratorContext,
   type RoleStep,
   START,
   validateWorkflowDescriptor,
-} from "@uncaged/workflow";
+} from "@uncaged/workflow-runtime";
 import { buildSolveIssueDescriptor } from "../src/descriptor.js";
 import type { DeveloperMeta } from "../src/developer.js";
 import { createSolveIssueRun, solveIssueModerator } from "../src/index.js";

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

@@ -1,6 +1,6 @@
 {
   "name": "@uncaged/workflow-template-solve-issue",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -9,6 +9,7 @@
   },
   "dependencies": {
     "@uncaged/workflow": "workspace:*",
+    "@uncaged/workflow-runtime": "workspace:*",
     "zod": "^4.0.0"
   }
 }

packages/workflow-template-solve-issue/src/developer.ts

@@ -1,4 +1,4 @@
-import type { RoleDefinition } from "@uncaged/workflow";
+import type { RoleDefinition } from "@uncaged/workflow-runtime";
 import * as z from "zod/v4";
 
 export const developerMetaSchema = z.object({

packages/workflow-template-solve-issue/src/index.ts

@@ -1,10 +1,5 @@
-import {
-  type AgentBinding,
-  createWorkflow,
-  type WorkflowDefinition,
-  type WorkflowFn,
-  workflowAsAgent,
-} from "@uncaged/workflow";
+import { createWorkflow, workflowAsAgent } from "@uncaged/workflow";
+import type { AgentBinding, WorkflowDefinition, WorkflowFn } from "@uncaged/workflow-runtime";
 
 import { solveIssueModerator } from "./moderator.js";
 import { SOLVE_ISSUE_WORKFLOW_DESCRIPTION, type SolveIssueMeta, solveIssueRoles } from "./roles.js";

packages/workflow-template-solve-issue/src/moderator.ts

@@ -1,5 +1,5 @@
-import type { Moderator } from "@uncaged/workflow";
-import { END } from "@uncaged/workflow";
+import type { Moderator } from "@uncaged/workflow-runtime";
+import { END } from "@uncaged/workflow-runtime";
 
 import type { SolveIssueMeta } from "./roles.js";
 

packages/workflow-template-solve-issue/src/roles.ts

@@ -1,4 +1,4 @@
-import type { RoleDefinition } from "@uncaged/workflow";
+import type { RoleDefinition } from "@uncaged/workflow-runtime";
 import { type DeveloperMeta, developerRole } from "./developer.js";
 import { type PreparerMeta, preparerRole } from "./roles/preparer.js";
 import { type SubmitterMeta, submitterRole } from "./roles/submitter.js";

packages/workflow-template-solve-issue/src/roles/preparer.ts

@@ -1,4 +1,4 @@
-import type { RoleDefinition } from "@uncaged/workflow";
+import type { RoleDefinition } from "@uncaged/workflow-runtime";
 import * as z from "zod/v4";
 
 const toolchainSchema = z.object({

packages/workflow-template-solve-issue/src/roles/submitter.ts

@@ -1,4 +1,4 @@
-import type { RoleDefinition } from "@uncaged/workflow";
+import type { RoleDefinition } from "@uncaged/workflow-runtime";
 import * as z from "zod/v4";
 
 export const submitterMetaSchema = z.discriminatedUnion("status", [

packages/workflow-util-agent/__tests__/build-agent-prompt.test.ts

@@ -2,7 +2,8 @@ import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import { mkdtemp, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { createCasStore, putContentMerkleNode, START, type ThreadContext } from "@uncaged/workflow";
+import { createCasStore, putContentMerkleNode } from "@uncaged/workflow";
+import { START, type ThreadContext } from "@uncaged/workflow-runtime";
 
 import { buildAgentPrompt } from "../src/index.js";
 

packages/workflow-util-agent/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uncaged/workflow-util-agent",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -14,6 +14,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@uncaged/workflow": "workspace:*"
+    "@uncaged/workflow": "workspace:*",
+    "@uncaged/workflow-runtime": "workspace:*"
   }
 }

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

@@ -1,5 +1,5 @@
-import type { AgentContext } from "@uncaged/workflow";
 import { getContentMerklePayload } from "@uncaged/workflow";
+import type { AgentContext } from "@uncaged/workflow-runtime";
 
 async function resolveStepText(ctx: AgentContext, contentHash: string): Promise<string> {
   const text = await getContentMerklePayload(ctx.cas, contentHash);

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

@@ -1,6 +1,6 @@
 import { spawn } from "node:child_process";
 
-import { err, ok, type Result } from "@uncaged/workflow";
+import { err, ok, type Result } from "@uncaged/workflow-runtime";
 
 export type SpawnCliError =
   | { kind: "non_zero_exit"; exitCode: number | null; stdout: string; stderr: string }

packages/workflow/__tests__/build-descriptor.test.ts

@@ -1,9 +1,8 @@
 import { describe, expect, test } from "bun:test";
+import { END } from "@uncaged/workflow-runtime";
 import * as z from "zod/v4";
-
 import { buildDescriptor } from "../src/bundle/build-descriptor.js";
 import { validateWorkflowDescriptor } from "../src/bundle/workflow-descriptor.js";
-import { END } from "../src/types.js";
 
 describe("buildDescriptor", () => {
   test("produces a descriptor that validates and includes JSON schemas per role", () => {

packages/workflow/__tests__/bundle-validator.test.ts

@@ -39,6 +39,16 @@ export const run = async function* (_input, options) {
     expect(r.ok).toBe(true);
   });
 
+  test("allows static import of @uncaged/workflow-runtime", () => {
+    const source = `${minimalDescriptor}import { createWorkflow } from "@uncaged/workflow-runtime";
+import { putContentMerkleNode } from "@uncaged/workflow";
+
+export const run = createWorkflow({ description: "x", roles: {}, moderator: () => "END" }, {});
+`;
+    const r = validateWorkflowBundle({ filePath: "/tmp/w.esm.js", source });
+    expect(r.ok).toBe(true);
+  });
+
   test("rejects wrong filename suffix", () => {
     const r = validateWorkflowBundle({
       filePath: "/tmp/w.js",

packages/workflow/__tests__/cas.test.ts

@@ -5,6 +5,11 @@ import { join } from "node:path";
 
 import { createCasStore } from "../src/cas/cas.js";
 import { hashString } from "../src/cas/hash.js";
+import { createContentMerkleNode, serializeMerkleNode } from "../src/cas/merkle.js";
+
+function casStoredForm(raw: string): string {
+  return serializeMerkleNode(createContentMerkleNode(raw));
+}
 
 describe("createCasStore", () => {
   let casDir: string;
@@ -19,25 +24,30 @@ describe("createCasStore", () => {
 
   test("put returns consistent hash for same content", async () => {
     const cas = createCasStore(casDir);
-    const h1 = await cas.put("hello world");
-    const h2 = await cas.put("hello world");
+    const raw = "hello world";
+    const stored = casStoredForm(raw);
+    const h1 = await cas.put(raw);
+    const h2 = await cas.put(raw);
     expect(h1).toBe(h2);
+    expect(h1).toBe(hashString(stored));
     expect(h1).toHaveLength(13);
   });
 
-  test("put returns hash matching hashString", async () => {
+  test("put returns hash matching hashString of merkle-stored form", async () => {
     const cas = createCasStore(casDir);
     const content = "some content to store";
+    const stored = casStoredForm(content);
     const h = await cas.put(content);
-    expect(h).toBe(hashString(content));
+    expect(h).toBe(hashString(stored));
   });
 
-  test("get returns stored content", async () => {
+  test("get returns merkle-serialized blob for raw puts", async () => {
     const cas = createCasStore(casDir);
     const content = "line1\nline2\nline3";
+    const stored = casStoredForm(content);
     const h = await cas.put(content);
     const retrieved = await cas.get(h);
-    expect(retrieved).toBe(content);
+    expect(retrieved).toBe(stored);
   });
 
   test("get returns null for missing hash", async () => {
@@ -76,11 +86,13 @@ describe("createCasStore", () => {
 
   test("put is idempotent — same content written twice causes no error", async () => {
     const cas = createCasStore(casDir);
-    const h1 = await cas.put("idempotent");
-    const h2 = await cas.put("idempotent");
+    const raw = "idempotent";
+    const stored = casStoredForm(raw);
+    const h1 = await cas.put(raw);
+    const h2 = await cas.put(raw);
     expect(h1).toBe(h2);
     const content = await cas.get(h1);
-    expect(content).toBe("idempotent");
+    expect(content).toBe(stored);
   });
 
   test("different content produces different hashes", async () => {

packages/workflow/__tests__/engine.test.ts

@@ -2,8 +2,8 @@ import { afterEach, 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 { END } from "@uncaged/workflow-runtime";
 import * as z from "zod/v4";
-
 import { createCasStore } from "../src/cas/cas.js";
 import {
   createContentMerkleNode,
@@ -13,7 +13,6 @@ import {
 } from "../src/cas/merkle.js";
 import { createWorkflow } from "../src/engine/create-workflow.js";
 import { executeThread } from "../src/engine/engine.js";
-import { END } from "../src/types.js";
 import { createLogger } from "../src/util/logger.js";
 
 const plannerMetaSchema = z.object({
@@ -96,6 +95,98 @@ async function writeExtractRegistryConfig(storageRoot: string): Promise<void> {
   await writeFile(join(storageRoot, "workflow.yaml"), EXTRACT_REGISTRY_YAML, "utf8");
 }
 
+const SUPERVISOR_INTERVAL_REGISTRY_YAML = `config:
+  maxDepth: 3
+  supervisorInterval: 2
+  providers:
+    stub:
+      baseUrl: http://127.0.0.1:9
+      apiKey: test
+  models:
+    extract: stub/model
+    supervisor: stub/supervisor-cheap
+workflows: {}
+`;
+
+const SUPERVISOR_LONG_INTERVAL_REGISTRY_YAML = `config:
+  maxDepth: 3
+  supervisorInterval: 10
+  providers:
+    stub:
+      baseUrl: http://127.0.0.1:9
+      apiKey: test
+  models:
+    extract: stub/model
+    supervisor: stub/supervisor-cheap
+workflows: {}
+`;
+
+async function writeRegistryYaml(storageRoot: string, yaml: string): Promise<void> {
+  await writeFile(join(storageRoot, "workflow.yaml"), yaml, "utf8");
+}
+
+/** Extract rounds use tool_calls; supervisor uses plain `content` (no tools). */
+function installMockExtractThenSupervisor(params: {
+  extractArgs: ReadonlyArray<Record<string, unknown>>;
+  supervisorContent: string;
+  onSupervisorCall?: () => void;
+}): () => void {
+  const origFetch = globalThis.fetch;
+  let extractI = 0;
+  const mockFetch = async (
+    _input: Parameters<typeof fetch>[0],
+    init?: RequestInit,
+  ): Promise<Response> => {
+    const body = init?.body ? (JSON.parse(String(init.body)) as Record<string, unknown>) : {};
+    const tools = body.tools;
+    const hasTools = Array.isArray(tools) && tools.length > 0;
+    if (hasTools) {
+      const args =
+        params.extractArgs[extractI] ?? params.extractArgs[params.extractArgs.length - 1];
+      if (args === undefined) {
+        throw new Error("installMockExtractThenSupervisor: empty extractArgs");
+      }
+      extractI += 1;
+      const firstTool = tools[0] as Record<string, unknown>;
+      const fn = firstTool.function as Record<string, unknown> | undefined;
+      const toolName = typeof fn?.name === "string" ? fn.name : "extract";
+      return new Response(
+        JSON.stringify({
+          choices: [
+            {
+              message: {
+                tool_calls: [
+                  {
+                    type: "function",
+                    function: {
+                      name: toolName,
+                      arguments: JSON.stringify(args),
+                    },
+                  },
+                ],
+              },
+            },
+          ],
+        }),
+        { status: 200, headers: { "Content-Type": "application/json" } },
+      );
+    }
+    params.onSupervisorCall?.();
+    return new Response(
+      JSON.stringify({
+        choices: [{ message: { content: params.supervisorContent } }],
+      }),
+      { status: 200, headers: { "Content-Type": "application/json" } },
+    );
+  };
+  globalThis.fetch = Object.assign(mockFetch, {
+    preconnect: origFetch.preconnect.bind(origFetch),
+  }) as typeof fetch;
+  return () => {
+    globalThis.fetch = origFetch;
+  };
+}
+
 const demoWorkflow = createWorkflow<DemoMeta>(
   {
     roles: {
@@ -577,7 +668,7 @@ describe("executeThread", () => {
           },
           moderator: (ctx) => (ctx.steps.length === 0 ? "walker" : END),
         },
-        { agent: async () => dagRootHash },
+        { agent: async () => dagRootHash, overrides: null },
       );
 
       const threadId = "01KQXKW18CT8G75T53R8F4G7YG";
@@ -623,4 +714,102 @@ describe("executeThread", () => {
       await rm(root, { recursive: true, force: true });
     }
   });
+
+  test("supervisor stops thread when interval elapses and model returns stop", async () => {
+    restoreFetch = installMockExtractThenSupervisor({
+      extractArgs: [{ plan: "do-it", files: ["a.ts"] }, { diff: "+ok" }],
+      supervisorContent: "stop",
+    });
+
+    const root = await mkdtemp(join(tmpdir(), "wf-engine-sup-stop-"));
+    try {
+      const threadId = "01KQXKW18CT8G75T53R8F4G7YG";
+      const hash = "C9NMV6V2TQT81";
+      const dataPath = join(root, "logs", hash, `${threadId}.data.jsonl`);
+      const infoPath = join(root, "logs", hash, `${threadId}.info.jsonl`);
+      await mkdir(join(root, "logs", hash), { recursive: true });
+      await writeRegistryYaml(root, SUPERVISOR_INTERVAL_REGISTRY_YAML);
+      const cas = createCasStore(join(root, "cas"));
+
+      const logger = createLogger({ sink: { kind: "file", path: infoPath } });
+      const ac = new AbortController();
+
+      const result = await executeThread(
+        demoWorkflow,
+        "demo-flow",
+        { prompt: "supervisor-stop-case", steps: [] },
+        {
+          maxRounds: 20,
+          depth: 0,
+          signal: ac.signal,
+          awaitAfterEachYield: async () => {},
+          forkSourceThreadId: null,
+          prefilledDiskSteps: null,
+          storageRoot: root,
+        },
+        { threadId, hash, dataJsonlPath: dataPath, infoJsonlPath: infoPath, cas },
+        logger,
+      );
+
+      expect(result.returnCode).toBe(0);
+      expect(result.summary).toBe("completed: supervisor stopped thread");
+
+      const dataText = await readFile(dataPath, "utf8");
+      const lines = dataText
+        .trim()
+        .split("\n")
+        .filter((l) => l !== "");
+      expect(lines.length).toBe(3);
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
+  test("supervisor is not invoked before supervisorInterval rounds", async () => {
+    let supervisorCalls = 0;
+    restoreFetch = installMockExtractThenSupervisor({
+      extractArgs: [{ plan: "do-it", files: ["a.ts"] }, { diff: "+ok" }],
+      supervisorContent: "stop",
+      onSupervisorCall: () => {
+        supervisorCalls += 1;
+      },
+    });
+
+    const root = await mkdtemp(join(tmpdir(), "wf-engine-sup-skip-"));
+    try {
+      const threadId = "01KQXKW18CT8G75T53R8F4G7YG";
+      const hash = "C9NMV6V2TQT81";
+      const dataPath = join(root, "logs", hash, `${threadId}.data.jsonl`);
+      const infoPath = join(root, "logs", hash, `${threadId}.info.jsonl`);
+      await mkdir(join(root, "logs", hash), { recursive: true });
+      await writeRegistryYaml(root, SUPERVISOR_LONG_INTERVAL_REGISTRY_YAML);
+      const cas = createCasStore(join(root, "cas"));
+
+      const logger = createLogger({ sink: { kind: "file", path: infoPath } });
+      const ac = new AbortController();
+
+      const result = await executeThread(
+        demoWorkflow,
+        "demo-flow",
+        { prompt: "no-supervisor-yet", steps: [] },
+        {
+          maxRounds: 20,
+          depth: 0,
+          signal: ac.signal,
+          awaitAfterEachYield: async () => {},
+          forkSourceThreadId: null,
+          prefilledDiskSteps: null,
+          storageRoot: root,
+        },
+        { threadId, hash, dataJsonlPath: dataPath, infoJsonlPath: infoPath, cas },
+        logger,
+      );
+
+      expect(supervisorCalls).toBe(0);
+      expect(result.returnCode).toBe(0);
+      expect(result.summary).toBe("completed: moderator returned END");
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  });
 });

packages/workflow/__tests__/react-extract.test.ts

@@ -2,12 +2,11 @@ import { afterEach, describe, expect, test } from "bun:test";
 import { mkdtemp, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import type { LlmProvider } from "@uncaged/workflow-runtime";
 import * as z from "zod/v4";
-
 import { createCasStore } from "../src/cas/cas.js";
 import { createContentMerkleNode, serializeMerkleNode } from "../src/cas/merkle.js";
 import { reactExtract } from "../src/extract/react-extract.js";
-import type { LlmProvider } from "../src/types.js";
 
 const metaSchema = z.object({ seen: z.string() });
 

packages/workflow/__tests__/refs-tracking.test.ts

@@ -2,13 +2,12 @@ import { afterEach, 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 { END } from "@uncaged/workflow-runtime";
 import * as z from "zod/v4";
-
 import { createCasStore } from "../src/cas/cas.js";
 import { createWorkflow } from "../src/engine/create-workflow.js";
 import { executeThread } from "../src/engine/engine.js";
 import { buildForkPlan, parseThreadDataJsonl } from "../src/engine/fork-thread.js";
-import { END } from "../src/types.js";
 import { createLogger } from "../src/util/logger.js";
 
 const phaseSchema = z.object({
@@ -102,6 +101,7 @@ const refsDemoWorkflow = createWorkflow<RefsDemoMeta>(
   },
   {
     agent: async () => "plan-output",
+    overrides: null,
   },
 );
 

packages/workflow/__tests__/registry.test.ts

@@ -132,6 +132,65 @@ workflows:
     expect(r.value.config.providers.dashscope?.apiKey).toBe("secret-key");
     expect(r.value.config.models.extract).toBe("dashscope/qwen-plus");
     expect(r.value.config.models.default).toBe("dashscope/qwen-turbo");
+    expect(r.value.config.supervisorInterval).toBe(3);
+  });
+
+  test("defaults supervisorInterval to 3 when omitted", () => {
+    const yaml = `
+config:
+  maxDepth: 0
+  providers:
+    p:
+      baseUrl: https://example.com
+      apiKey: k
+  models:
+    default: p/m
+workflows: {}
+`;
+    const r = parseWorkflowRegistryYaml(yaml);
+    expect(r.ok).toBe(true);
+    if (!r.ok || r.value.config === null) {
+      return;
+    }
+    expect(r.value.config.supervisorInterval).toBe(3);
+  });
+
+  test("parses explicit supervisorInterval", () => {
+    const yaml = `
+config:
+  maxDepth: 0
+  supervisorInterval: 7
+  providers:
+    p:
+      baseUrl: https://example.com
+      apiKey: k
+  models:
+    default: p/m
+workflows: {}
+`;
+    const r = parseWorkflowRegistryYaml(yaml);
+    expect(r.ok).toBe(true);
+    if (!r.ok || r.value.config === null) {
+      return;
+    }
+    expect(r.value.config.supervisorInterval).toBe(7);
+  });
+
+  test("parse errors when supervisorInterval is negative", () => {
+    const yaml = `
+config:
+  maxDepth: 0
+  supervisorInterval: -1
+  providers:
+    p:
+      baseUrl: https://example.com
+      apiKey: k
+  models:
+    default: p/m
+workflows: {}
+`;
+    const r = parseWorkflowRegistryYaml(yaml);
+    expect(r.ok).toBe(false);
   });
 
   test("parses config apiKey env: prefix from process.env", () => {

packages/workflow/__tests__/resolve-model.test.ts

@@ -6,6 +6,7 @@ import type { WorkflowConfig } from "../src/registry/index.js";
 function sampleConfig(): WorkflowConfig {
   return {
     maxDepth: 3,
+    supervisorInterval: 3,
     providers: {
       dashscope: {
         baseUrl: "https://dashscope.aliyuncs.com/compatible-mode/v1",
@@ -50,6 +51,7 @@ describe("resolveModel", () => {
   test("errs when scene missing and no default", () => {
     const config: WorkflowConfig = {
       maxDepth: 1,
+      supervisorInterval: 3,
       providers: {
         p: { baseUrl: "https://x", apiKey: "k" },
       },
@@ -69,6 +71,7 @@ describe("resolveModel", () => {
   test("errs when provider is unknown", () => {
     const config: WorkflowConfig = {
       maxDepth: 1,
+      supervisorInterval: 3,
       providers: {
         p: { baseUrl: "https://x", apiKey: "k" },
       },
@@ -87,6 +90,7 @@ describe("resolveModel", () => {
   test("errs on invalid model reference shape", () => {
     const config: WorkflowConfig = {
       maxDepth: 1,
+      supervisorInterval: 3,
       providers: {
         p: { baseUrl: "https://x", apiKey: "k" },
       },

packages/workflow/__tests__/supervisor.test.ts

@@ -0,0 +1,136 @@
+import { afterEach, describe, expect, test } from "bun:test";
+
+import { parseSupervisorDecisionText, runSupervisor } from "../src/engine/supervisor.js";
+import type { WorkflowConfig } from "../src/registry/index.js";
+import type { LogFn } from "../src/util/index.js";
+
+const noopLogger: LogFn = () => {};
+
+function supervisorOnlyConfig(): WorkflowConfig {
+  return {
+    maxDepth: 3,
+    supervisorInterval: 3,
+    providers: {
+      stub: { baseUrl: "http://127.0.0.1:9/v1", apiKey: "k" },
+    },
+    models: {
+      extract: "stub/extract-model",
+      supervisor: "stub/supervisor-model",
+    },
+  };
+}
+
+describe("parseSupervisorDecisionText", () => {
+  test("reads continue and stop case-insensitively", () => {
+    expect(parseSupervisorDecisionText("continue")).toBe("continue");
+    expect(parseSupervisorDecisionText("CONTINUE")).toBe("continue");
+    expect(parseSupervisorDecisionText("stop")).toBe("stop");
+    expect(parseSupervisorDecisionText("STOP.")).toBe("stop");
+  });
+
+  test("finds token inside a sentence", () => {
+    expect(parseSupervisorDecisionText("Answer: continue")).toBe("continue");
+    expect(parseSupervisorDecisionText("I recommend stop now")).toBe("stop");
+  });
+
+  test("when both appear, earlier token wins", () => {
+    expect(parseSupervisorDecisionText("continue then stop")).toBe("continue");
+    expect(parseSupervisorDecisionText("stop then continue")).toBe("stop");
+  });
+
+  test("defaults to continue when unclear", () => {
+    expect(parseSupervisorDecisionText("maybe later")).toBe("continue");
+  });
+});
+
+describe("runSupervisor", () => {
+  let restoreFetch: (() => void) | null = null;
+
+  afterEach(() => {
+    restoreFetch?.();
+    restoreFetch = null;
+  });
+
+  test("returns continue when supervisor model cannot be resolved (no fetch)", async () => {
+    const origFetch = globalThis.fetch;
+    restoreFetch = () => {
+      globalThis.fetch = origFetch;
+    };
+    globalThis.fetch = Object.assign(
+      async () => {
+        throw new Error("fetch should not run when supervisor is not configured");
+      },
+      { preconnect: origFetch.preconnect.bind(origFetch) },
+    ) as typeof fetch;
+
+    const config: WorkflowConfig = {
+      maxDepth: 1,
+      supervisorInterval: 3,
+      providers: {
+        stub: { baseUrl: "http://127.0.0.1:9/v1", apiKey: "k" },
+      },
+      models: {
+        extract: "stub/m",
+      },
+    };
+
+    const r = await runSupervisor({
+      config,
+      prompt: "task",
+      recentSteps: [{ role: "planner", summary: "{}" }],
+      logger: noopLogger,
+    });
+    expect(r.ok).toBe(true);
+    if (!r.ok) {
+      return;
+    }
+    expect(r.value).toBe("continue");
+  });
+
+  test("returns stop from chat/completions assistant content", async () => {
+    const origFetch = globalThis.fetch;
+    restoreFetch = () => {
+      globalThis.fetch = origFetch;
+    };
+    globalThis.fetch = Object.assign(
+      async () =>
+        new Response(
+          JSON.stringify({
+            choices: [{ message: { content: "stop" } }],
+          }),
+          { status: 200, headers: { "Content-Type": "application/json" } },
+        ),
+      { preconnect: origFetch.preconnect.bind(origFetch) },
+    ) as typeof fetch;
+
+    const r = await runSupervisor({
+      config: supervisorOnlyConfig(),
+      prompt: "do X",
+      recentSteps: [{ role: "a", summary: "{}" }],
+      logger: noopLogger,
+    });
+    expect(r.ok).toBe(true);
+    if (!r.ok) {
+      return;
+    }
+    expect(r.value).toBe("stop");
+  });
+
+  test("returns err on invalid JSON body", async () => {
+    const origFetch = globalThis.fetch;
+    restoreFetch = () => {
+      globalThis.fetch = origFetch;
+    };
+    globalThis.fetch = Object.assign(async () => new Response("not-json", { status: 200 }), {
+      preconnect: origFetch.preconnect.bind(origFetch),
+    }) as typeof fetch;
+
+    const r = await runSupervisor({
+      config: supervisorOnlyConfig(),
+      prompt: "p",
+      recentSteps: [],
+      logger: noopLogger,
+    });
+    expect(r.ok).toBe(false);
+  });
+});

packages/workflow/__tests__/workflow-as-agent-integration.test.ts

@@ -2,8 +2,8 @@ import { afterEach, describe, expect, test } from "bun:test";
 import { mkdir, mkdtemp, readdir, readFile, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { END } from "@uncaged/workflow-runtime";
 import * as z from "zod/v4";
-
 import { createCasStore } from "../src/cas/cas.js";
 import { hashWorkflowBundleBytes } from "../src/cas/hash.js";
 import { getContentMerklePayload, parseMerkleNode } from "../src/cas/merkle.js";
@@ -14,7 +14,6 @@ import {
   registerWorkflowVersion,
   writeWorkflowRegistry,
 } from "../src/registry/registry.js";
-import { END } from "../src/types.js";
 import { createLogger } from "../src/util/logger.js";
 import { workflowAsAgent } from "../src/workflow-as-agent.js";
 
@@ -153,7 +152,7 @@ describe("workflowAsAgent integration", () => {
           },
           moderator: (ctx) => (ctx.steps.length === 0 ? "caller" : END),
         },
-        { agent: workflowAsAgent("child-wf", { storageRoot: root }) },
+        { agent: workflowAsAgent("child-wf", { storageRoot: root }), overrides: null },
       );
 
       const threadId = "01KQXKW18CT8G75T53R8F4G7YG";

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

@@ -2,7 +2,7 @@ import { describe, expect, test } from "bun:test";
 import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-
+import { type AgentContext, START } from "@uncaged/workflow-runtime";
 import { createCasStore } from "../src/cas/cas.js";
 import { hashWorkflowBundleBytes } from "../src/cas/hash.js";
 import { parseMerkleNode } from "../src/cas/merkle.js";
@@ -11,7 +11,6 @@ import {
   registerWorkflowVersion,
   writeWorkflowRegistry,
 } from "../src/registry/registry.js";
-import { type AgentContext, START } from "../src/types.js";
 import { workflowAsAgent } from "../src/workflow-as-agent.js";
 
 function makeAgentCtx(params: {
@@ -155,6 +154,7 @@ workflows: {}
         ...reg.value,
         config: {
           maxDepth: 2,
+          supervisorInterval: 3,
           providers: {
             local: {
               baseUrl: "http://127.0.0.1:9",

packages/workflow/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uncaged/workflow",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -8,6 +8,7 @@
     "test": "bun test"
   },
   "dependencies": {
+    "@uncaged/workflow-runtime": "workspace:*",
     "acorn": "^8.16.0",
     "xxhashjs": "^0.2.2",
     "yaml": "^2.8.4"

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

@@ -1,6 +1,5 @@
+import type { RoleMeta, WorkflowDefinition } from "@uncaged/workflow-runtime";
 import * as z from "zod/v4";
-
-import type { RoleMeta, WorkflowDefinition } from "../types.js";
 import type { WorkflowDescriptor, WorkflowRoleSchema } from "./types.js";
 
 function stripJsonSchemaMeta(json: Record<string, unknown>): WorkflowRoleSchema {

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

@@ -38,7 +38,7 @@ function isAllowedImportSpecifier(spec: string): boolean {
   if (spec.startsWith(".") || spec.startsWith("/") || spec.startsWith("file:")) {
     return false;
   }
-  if (spec === "@uncaged/workflow") {
+  if (spec === "@uncaged/workflow" || spec === "@uncaged/workflow-runtime") {
     return true;
   }
   return isBuiltin(spec);

packages/workflow/src/bundle/extract-bundle-exports.ts

@@ -1,4 +1,4 @@
-import type { WorkflowFn } from "../types.js";
+import type { WorkflowFn } from "@uncaged/workflow-runtime";
 import { err, ok, type Result } from "../util/index.js";
 import { importWorkflowBundleModule } from "./bundle-import-env.js";
 import { ensureUncagedWorkflowSymlink } from "./ensure-uncaged-workflow-symlink.js";