From 5b60fa6454d0ce6dd6286b1ccab0b89158e866e7 Mon Sep 17 00:00:00 2001
From: Scott Wei <scottwei@shazhou.work>
Date: Fri, 8 May 2026 23:03:53 +0800
Subject: [PATCH] refactor(workflow-runtime): flatten package layout and
 centralize types

Collapse bundle/cas/extract/util stubs into types.ts; move createWorkflow and Result helpers to src root.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 packages/workflow-runtime/src/bundle/index.ts |  1 -
 packages/workflow-runtime/src/bundle/types.ts | 13 -------
 packages/workflow-runtime/src/cas/index.ts    |  1 -
 packages/workflow-runtime/src/cas/types.ts    |  6 ---
 .../src/{engine => }/create-workflow.ts       | 12 +++---
 packages/workflow-runtime/src/engine/index.ts |  1 -
 .../workflow-runtime/src/extract/index.ts     |  1 -
 .../workflow-runtime/src/extract/types.ts     |  9 -----
 packages/workflow-runtime/src/index.ts        | 18 ++++-----
 .../workflow-runtime/src/{util => }/result.ts |  0
 packages/workflow-runtime/src/types.ts        | 38 +++++++++++++++++--
 packages/workflow-runtime/src/util/index.ts   |  3 --
 .../workflow-runtime/src/util/refs-field.ts   |  8 ----
 packages/workflow-runtime/src/util/types.ts   |  1 -
 14 files changed, 49 insertions(+), 63 deletions(-)
 delete mode 100644 packages/workflow-runtime/src/bundle/index.ts
 delete mode 100644 packages/workflow-runtime/src/bundle/types.ts
 delete mode 100644 packages/workflow-runtime/src/cas/index.ts
 delete mode 100644 packages/workflow-runtime/src/cas/types.ts
 rename packages/workflow-runtime/src/{engine => }/create-workflow.ts (93%)
 delete mode 100644 packages/workflow-runtime/src/engine/index.ts
 delete mode 100644 packages/workflow-runtime/src/extract/index.ts
 delete mode 100644 packages/workflow-runtime/src/extract/types.ts
 rename packages/workflow-runtime/src/{util => }/result.ts (100%)
 delete mode 100644 packages/workflow-runtime/src/util/index.ts
 delete mode 100644 packages/workflow-runtime/src/util/refs-field.ts
 delete mode 100644 packages/workflow-runtime/src/util/types.ts

diff --git a/packages/workflow-runtime/src/bundle/index.ts b/packages/workflow-runtime/src/bundle/index.ts
deleted file mode 100644
index fde4867..0000000
--- a/packages/workflow-runtime/src/bundle/index.ts
+++ /dev/null
@@ -1 +0,0 @@
-export type { WorkflowDescriptor, WorkflowRoleDescriptor, WorkflowRoleSchema } from "./types.js";
diff --git a/packages/workflow-runtime/src/bundle/types.ts b/packages/workflow-runtime/src/bundle/types.ts
deleted file mode 100644
index a1b4478..0000000
--- a/packages/workflow-runtime/src/bundle/types.ts
+++ /dev/null
@@ -1,13 +0,0 @@
-/** 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>;
-};
diff --git a/packages/workflow-runtime/src/cas/index.ts b/packages/workflow-runtime/src/cas/index.ts
deleted file mode 100644
index 5bfc042..0000000
--- a/packages/workflow-runtime/src/cas/index.ts
+++ /dev/null
@@ -1 +0,0 @@
-export type { CasStore } from "./types.js";
diff --git a/packages/workflow-runtime/src/cas/types.ts b/packages/workflow-runtime/src/cas/types.ts
deleted file mode 100644
index 2be4d74..0000000
--- a/packages/workflow-runtime/src/cas/types.ts
+++ /dev/null
@@ -1,6 +0,0 @@
-export type CasStore = {
-  put(content: string): Promise<string>;
-  get(hash: string): Promise<string | null>;
-  delete(hash: string): Promise<void>;
-  list(): Promise<string[]>;
-};
diff --git a/packages/workflow-runtime/src/engine/create-workflow.ts b/packages/workflow-runtime/src/create-workflow.ts
similarity index 93%
rename from packages/workflow-runtime/src/engine/create-workflow.ts
rename to packages/workflow-runtime/src/create-workflow.ts
index 186cf26..a899edd 100644
--- a/packages/workflow-runtime/src/engine/create-workflow.ts
+++ b/packages/workflow-runtime/src/create-workflow.ts
@@ -1,10 +1,10 @@
 import type * as z from "zod/v4";
 
-import type { CasStore } from "../cas/types.js";
 import {
   type AgentBinding,
   type AgentContext,
   type AgentFn,
+  type CasStore,
   END,
   type ExtractContext,
   type ModeratorContext,
@@ -18,8 +18,7 @@ import {
   type WorkflowDefinition,
   type WorkflowFn,
   type WorkflowRuntime,
-} from "../types.js";
-import { mergeRefsWithContentHash } from "../util/index.js";
+} from "./types.js";
 
 function isRoleNext<M extends RoleMeta>(
   next: (keyof M & string) | typeof END,
@@ -97,10 +96,11 @@ async function advanceOneRound<M extends RoleMeta>(
   );
 
   const contentHash = await putContentBlob(runtime.cas, raw);
-  const refs = mergeRefsWithContentHash(
-    resolveExtractedRefs(roleDef as unknown as RoleDefinition<Record<string, unknown>>, meta),
-    contentHash,
+  const refsFromMeta = resolveExtractedRefs(
+    roleDef as unknown as RoleDefinition<Record<string, unknown>>,
+    meta,
   );
+  const refs = refsFromMeta.includes(contentHash) ? refsFromMeta : [...refsFromMeta, contentHash];
 
   const step = {
     role: next,
diff --git a/packages/workflow-runtime/src/engine/index.ts b/packages/workflow-runtime/src/engine/index.ts
deleted file mode 100644
index 2b6e901..0000000
--- a/packages/workflow-runtime/src/engine/index.ts
+++ /dev/null
@@ -1 +0,0 @@
-export { createWorkflow } from "./create-workflow.js";
diff --git a/packages/workflow-runtime/src/extract/index.ts b/packages/workflow-runtime/src/extract/index.ts
deleted file mode 100644
index 02695ad..0000000
--- a/packages/workflow-runtime/src/extract/index.ts
+++ /dev/null
@@ -1 +0,0 @@
-export type { ExtractFn } from "./types.js";
diff --git a/packages/workflow-runtime/src/extract/types.ts b/packages/workflow-runtime/src/extract/types.ts
deleted file mode 100644
index 6c04f01..0000000
--- a/packages/workflow-runtime/src/extract/types.ts
+++ /dev/null
@@ -1,9 +0,0 @@
-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>;
diff --git a/packages/workflow-runtime/src/index.ts b/packages/workflow-runtime/src/index.ts
index 317c61b..c1f5c8b 100644
--- a/packages/workflow-runtime/src/index.ts
+++ b/packages/workflow-runtime/src/index.ts
@@ -1,19 +1,16 @@
-export type {
-  WorkflowDescriptor,
-  WorkflowRoleDescriptor,
-  WorkflowRoleSchema,
-} from "./bundle/types.js";
-export type { CasStore } from "./cas/index.js";
-export { createWorkflow } from "./engine/index.js";
-export type { ExtractFn } from "./extract/index.js";
+export { createWorkflow } from "./create-workflow.js";
+export { err, ok } from "./result.js";
 export type {
   AgentBinding,
   AgentContext,
   AgentFn,
+  CasStore,
   ExtractContext,
+  ExtractFn,
   LlmProvider,
   Moderator,
   ModeratorContext,
+  Result,
   RoleDefinition,
   RoleMeta,
   RoleOutput,
@@ -22,10 +19,11 @@ export type {
   ThreadContext,
   WorkflowCompletion,
   WorkflowDefinition,
+  WorkflowDescriptor,
   WorkflowFn,
   WorkflowResult,
+  WorkflowRoleDescriptor,
+  WorkflowRoleSchema,
   WorkflowRuntime,
 } from "./types.js";
 export { END, START } from "./types.js";
-export type { Result } from "./util/index.js";
-export { err, ok } from "./util/index.js";
diff --git a/packages/workflow-runtime/src/util/result.ts b/packages/workflow-runtime/src/result.ts
similarity index 100%
rename from packages/workflow-runtime/src/util/result.ts
rename to packages/workflow-runtime/src/result.ts
diff --git a/packages/workflow-runtime/src/types.ts b/packages/workflow-runtime/src/types.ts
index 1019132..c6f3f2c 100644
--- a/packages/workflow-runtime/src/types.ts
+++ b/packages/workflow-runtime/src/types.ts
@@ -1,12 +1,33 @@
 import type * as z from "zod/v4";
 
-import type { CasStore } from "./cas/index.js";
-import type { ExtractFn } from "./extract/types.js";
-
 /** Sentinel values for automaton control flow. */
 export const START = "__start__" as const;
 export const END = "__end__" as const;
 
+export type CasStore = {
+  put(content: string): Promise<string>;
+  get(hash: string): Promise<string | null>;
+  delete(hash: string): Promise<void>;
+  list(): Promise<string[]>;
+};
+
+/** 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>;
+};
+
+/** Expected success/failure outcome without throwing for recoverable errors. */
+export type Result<T, E = Error> = { ok: true; value: T } | { ok: false; error: E };
+
 /** Maps role names → their meta types. Single generic drives all inference. */
 export type RoleMeta = Record<string, Record<string, unknown>>;
 
@@ -96,6 +117,12 @@ export type ExtractContext<M extends RoleMeta = RoleMeta> = AgentContext<M> & {
   agentContent: string;
 };
 
+export type ExtractFn = <T extends Record<string, unknown>>(
+  schema: z.ZodType<T>,
+  prompt: string,
+  ctx: ExtractContext,
+) => Promise<T>;
+
 /** Raw string output from an LLM/CLI adapter; meta is extracted by the engine. */
 export type AgentFn = (ctx: AgentContext) => Promise<string>;
 
@@ -131,3 +158,8 @@ export type WorkflowDefinition<M extends RoleMeta> = {
   roles: { [K in keyof M & string]: RoleDefinition<M[K]> };
   moderator: Moderator<M>;
 };
+
+/** Internal outcome of advancing one moderator round inside {@link createWorkflow}. */
+export type AdvanceOutcome<M extends RoleMeta> =
+  | { kind: "complete"; completion: WorkflowCompletion }
+  | { kind: "yield"; output: RoleOutput; step: RoleStep<M> };
diff --git a/packages/workflow-runtime/src/util/index.ts b/packages/workflow-runtime/src/util/index.ts
deleted file mode 100644
index 01b6b02..0000000
--- a/packages/workflow-runtime/src/util/index.ts
+++ /dev/null
@@ -1,3 +0,0 @@
-export { mergeRefsWithContentHash } from "./refs-field.js";
-export { err, ok } from "./result.js";
-export type { Result } from "./types.js";
diff --git a/packages/workflow-runtime/src/util/refs-field.ts b/packages/workflow-runtime/src/util/refs-field.ts
deleted file mode 100644
index 687d2d0..0000000
--- a/packages/workflow-runtime/src/util/refs-field.ts
+++ /dev/null
@@ -1,8 +0,0 @@
-/** 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;
-}
diff --git a/packages/workflow-runtime/src/util/types.ts b/packages/workflow-runtime/src/util/types.ts
deleted file mode 100644
index 3a97ab3..0000000
--- a/packages/workflow-runtime/src/util/types.ts
+++ /dev/null
@@ -1 +0,0 @@
-export type Result<T, E = Error> = { ok: true; value: T } | { ok: false; error: E };