@decocms/runtime 1.2.11 → 1.2.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/runtime",
-  "version": "1.2.11",
+  "version": "1.2.12",
   "type": "module",
   "scripts": {
     "check": "tsc --noEmit",

package/src/index.ts

@@ -28,7 +28,9 @@ export {
   type ResourceExecutionContext,
   type ResourceContents,
   type CreatedResource,
+  type WorkflowDefinition,
 } from "./tools.ts";
+export { createWorkflow } from "./workflows.ts";
 import type { Binding } from "./wrangler.ts";
 export { proxyConnectionForId, BindingOf } from "./bindings.ts";
 export { type CORSOptions, type CORSOrigin } from "./cors.ts";

package/src/tools.ts

@@ -17,10 +17,17 @@ import { BindingRegistry } from "./bindings.ts";
 import { Event, type EventHandlers } from "./events.ts";
 import type { DefaultEnv } from "./index.ts";
 import { State } from "./state.ts";
+import {
+  type WorkflowDefinition,
+  Workflow,
+  WORKFLOW_SCOPES,
+  workflowToolId,
+} from "./workflows.ts";
 
 // Re-export EventHandlers type and SELF constant for external use
 export { SELF } from "./events.ts";
 export type { EventHandlers } from "./events.ts";
+export type { WorkflowDefinition } from "./workflows.ts";
 
 export const createRuntimeContext = (prev?: AppContext) => {
   const store = State.getStore();
@@ -42,13 +49,17 @@ export interface ToolExecutionContext<
 
 /**
  * Tool interface with generic schema types for type-safe tool creation.
+ *
+ * TId preserves the literal string type of `id` so consumers (e.g. the
+ * workflow builder) can derive union types of tool names without codegen.
  */
 export interface Tool<
   TSchemaIn extends ZodTypeAny = ZodTypeAny,
   TSchemaOut extends ZodTypeAny | undefined = undefined,
+  TId extends string = string,
 > {
   _meta?: Record<string, unknown>;
-  id: string;
+  id: TId;
   description?: string;
   annotations?: ToolAnnotations;
   inputSchema: TSchemaIn;
@@ -246,7 +257,8 @@ export function createStreamableTool<TSchemaIn extends ZodSchema = ZodSchema>(
 export function createTool<
   TSchemaIn extends ZodSchema = ZodSchema,
   TSchemaOut extends ZodSchema | undefined = undefined,
->(opts: Tool<TSchemaIn, TSchemaOut>): Tool<TSchemaIn, TSchemaOut> {
+  TId extends string = string,
+>(opts: Tool<TSchemaIn, TSchemaOut, TId>): Tool<TSchemaIn, TSchemaOut, TId> {
   return {
     ...opts,
     execute: (input: ToolExecutionContext<TSchemaIn>) => {
@@ -517,6 +529,9 @@ export interface CreateMCPServerOptions<
           | Promise<CreatedResource[]>
       >
     | ((env: TEnv) => CreatedResource[] | Promise<CreatedResource[]>);
+  workflows?:
+    | WorkflowDefinition[]
+    | ((env: TEnv) => WorkflowDefinition[] | Promise<WorkflowDefinition[]>);
 }
 
 export type Fetch<TEnv = unknown> = (
@@ -541,16 +556,34 @@ const getEventBus = (
     : env?.MESH_REQUEST_CONTEXT?.state?.[prop];
 };
 
+// TEnv is erased here because toolsFor() only reads events/workflows/configuration
+// and doesn't need the full env type. Replacing `any` with a proper generic
+// would require threading TEnv through toolsFor, which is a larger refactor.
+type ResolvedMCPServerOptions<TSchema extends ZodTypeAny = never> = Omit<
+  CreateMCPServerOptions<any, TSchema>, // eslint-disable-line @typescript-eslint/no-explicit-any
+  "workflows"
+> & { workflows?: WorkflowDefinition[] };
+
+const getMeshCtx = (input: { runtimeContext: AppContext }) => {
+  const ctx = input.runtimeContext.env.MESH_REQUEST_CONTEXT;
+  return {
+    connectionId: ctx?.connectionId,
+    meshUrl: ctx?.meshUrl,
+    token: ctx?.token,
+  };
+};
+
 const toolsFor = <TSchema extends ZodTypeAny = never>({
   events,
+  workflows,
   configuration: { state: schema, scopes, onChange } = {},
-}: CreateMCPServerOptions<any, TSchema> = {}): CreatedTool[] => {
+}: ResolvedMCPServerOptions<TSchema> = {}): CreatedTool[] => {
   const jsonSchema = schema
     ? z.toJSONSchema(schema)
     : { type: "object", properties: {} };
   const busProp = String(events?.bus ?? "EVENT_BUS");
   return [
-    ...(onChange || events
+    ...(onChange || events || workflows?.length
       ? [
           createTool({
             id: "ON_MCP_CONFIGURATION",
@@ -573,9 +606,7 @@ const toolsFor = <TSchema extends ZodTypeAny = never>({
               });
               const bus = getEventBus(busProp, input.runtimeContext.env);
               if (events && state && bus) {
-                // Get connectionId for SELF subscriptions
-                const connectionId =
-                  input.runtimeContext.env.MESH_REQUEST_CONTEXT?.connectionId;
+                const { connectionId } = getMeshCtx(input);
                 // Sync subscriptions - always call to handle deletions too
                 const subscriptions = Event.subscriptions(
                   events?.handlers ?? ({} as Record<string, never>),
@@ -607,6 +638,23 @@ const toolsFor = <TSchema extends ZodTypeAny = never>({
                   );
                 }
               }
+
+              if (workflows?.length) {
+                const {
+                  connectionId: wfConnectionId,
+                  meshUrl,
+                  token,
+                } = getMeshCtx(input);
+                if (wfConnectionId && meshUrl) {
+                  await Workflow.sync(
+                    workflows,
+                    meshUrl,
+                    wfConnectionId,
+                    token,
+                  );
+                }
+              }
+
               return Promise.resolve({});
             },
           }),
@@ -623,10 +671,8 @@ const toolsFor = <TSchema extends ZodTypeAny = never>({
             outputSchema: OnEventsOutputSchema,
             execute: async (input) => {
               const env = input.runtimeContext.env;
-              // Get state from MESH_REQUEST_CONTEXT - this has the binding values
               const state = env.MESH_REQUEST_CONTEXT?.state as z.infer<TSchema>;
-              // Get connectionId for SELF handlers
-              const connectionId = env.MESH_REQUEST_CONTEXT?.connectionId;
+              const { connectionId } = getMeshCtx(input);
               return Event.execute(
                 events.handlers!,
                 input.context.events,
@@ -652,10 +698,90 @@ const toolsFor = <TSchema extends ZodTypeAny = never>({
           scopes: [
             ...((scopes as string[]) ?? []),
             ...(events ? [`${busProp}::EVENT_SYNC_SUBSCRIPTIONS`] : []),
+            ...(workflows?.length ? [...WORKFLOW_SCOPES] : []),
           ],
         });
       },
     }),
+
+    // Auto-generated trigger tool for each declared workflow.
+    // Calls COLLECTION_WORKFLOW_EXECUTION_CREATE on the mesh and returns the
+    // execution ID immediately (fire-and-forget; poll with
+    // COLLECTION_WORKFLOW_EXECUTION_GET to track progress).
+    ...(workflows?.length
+      ? workflows.map((wf) => {
+          const id = wf.toolId ?? workflowToolId(wf.title);
+          return createTool({
+            id,
+            description: [
+              wf.description
+                ? `Run workflow: ${wf.description}`
+                : `Start the "${wf.title}" workflow.`,
+              "Returns an execution_id immediately. Use COLLECTION_WORKFLOW_EXECUTION_GET to track progress.",
+            ].join(" "),
+            inputSchema: z.object({
+              input: z
+                .record(z.string(), z.unknown())
+                .optional()
+                .describe(
+                  "Input data for the workflow. Steps reference these values via @input.field.",
+                ),
+              virtual_mcp_id: z
+                .string()
+                .optional()
+                .describe(
+                  wf.virtual_mcp_id
+                    ? `Virtual MCP ID to use for execution (defaults to "${wf.virtual_mcp_id}").`
+                    : "Virtual MCP ID that will execute the workflow steps.",
+                ),
+              start_at_epoch_ms: z
+                .number()
+                .int()
+                .min(0)
+                .optional()
+                .describe(
+                  "Unix timestamp (ms) for scheduled execution. Omit to start immediately.",
+                ),
+            }),
+            outputSchema: z.object({
+              execution_id: z
+                .string()
+                .describe("ID of the created workflow execution."),
+            }),
+            execute: async (input) => {
+              const { connectionId, meshUrl, token } = getMeshCtx(input);
+
+              if (!connectionId || !meshUrl) {
+                throw new Error(
+                  `[${id}] Missing MESH_REQUEST_CONTEXT (connectionId or meshUrl).`,
+                );
+              }
+
+              const ctx = input.context as {
+                input?: Record<string, unknown>;
+                virtual_mcp_id?: string;
+                start_at_epoch_ms?: number;
+              };
+
+              const virtualMcpId = ctx.virtual_mcp_id ?? wf.virtual_mcp_id;
+
+              const collectionId = Workflow.workflowId(connectionId, wf.title);
+              const executionId = await Workflow.createExecution(
+                meshUrl,
+                token,
+                {
+                  workflow_collection_id: collectionId,
+                  virtual_mcp_id: virtualMcpId,
+                  input: ctx.input,
+                  start_at_epoch_ms: ctx.start_at_epoch_ms,
+                },
+              );
+
+              return { execution_id: executionId };
+            },
+          });
+        })
+      : []),
   ];
 };
 
@@ -710,7 +836,14 @@ export const createMCPServer = <
           };
     const tools = await toolsFn(bindings);
 
-    tools.push(...toolsFor<TSchema>(options));
+    const resolvedWorkflows =
+      typeof options.workflows === "function"
+        ? await options.workflows(bindings)
+        : options.workflows;
+
+    tools.push(
+      ...toolsFor<TSchema>({ ...options, workflows: resolvedWorkflows }),
+    );
 
     for (const tool of tools) {
       server.registerTool(
@@ -858,6 +991,9 @@ export const createMCPServer = <
           }
 
           // MCP SDK expects either text or blob content, not both
+          const meta =
+            (result as { _meta?: Record<string, unknown> | null })._meta ??
+            undefined;
           if (result.text !== undefined) {
             return {
               contents: [
@@ -865,6 +1001,7 @@ export const createMCPServer = <
                   uri: result.uri,
                   mimeType: result.mimeType,
                   text: result.text,
+                  ...(meta !== undefined ? { _meta: meta } : {}),
                 },
               ],
             };
@@ -875,6 +1012,7 @@ export const createMCPServer = <
                   uri: result.uri,
                   mimeType: result.mimeType,
                   blob: result.blob,
+                  ...(meta !== undefined ? { _meta: meta } : {}),
                 },
               ],
             };

package/src/workflows.ts

@@ -0,0 +1,770 @@
+import type { Step } from "@decocms/bindings/workflow";
+import { z, type ZodTypeAny } from "zod";
+import { proxyConnectionForId } from "./bindings.ts";
+import { MCPClient } from "./mcp.ts";
+
+/**
+ * Declarative workflow definition for MCP servers.
+ * Workflows declared here are automatically synced to the mesh
+ * as workflow_collection entries during ON_MCP_CONFIGURATION, and a
+ * trigger tool is automatically generated for each one.
+ */
+export interface WorkflowDefinition {
+  title: string;
+  description?: string;
+  /**
+   * Virtual MCP ID that will execute this workflow's steps.
+   * Used as the default for the generated trigger tool.
+   * Can be overridden at call time via the tool's `virtual_mcp_id` input.
+   */
+  virtual_mcp_id?: string;
+  steps: Step[];
+  /**
+   * Override the auto-generated tool ID for the workflow trigger tool.
+   * Defaults to START_WORKFLOW_<TITLE_SLUG> (e.g. START_WORKFLOW_FETCH_USERS).
+   */
+  toolId?: string;
+}
+
+interface WorkflowCollectionItem {
+  id: string;
+  title: string;
+  description: string | null;
+  virtual_mcp_id: string | null;
+  created_at: string;
+  updated_at: string;
+}
+
+interface DefaultVirtualMCPItem {
+  id: string;
+  title: string;
+}
+
+/**
+ * Hand-rolled client interface for the workflow collection tools exposed by
+ * the mesh's /mcp/self endpoint.
+ *
+ * TODO: Replace with a generated client derived from WorkflowBinding in
+ * @decocms/bindings/workflow once that binding covers write operations
+ * (CREATE, UPDATE, DELETE) and COLLECTION_WORKFLOW_EXECUTION_CREATE.
+ * Until then, any rename of a tool or field on the server side requires a
+ * matching change here — the bindings system was designed to prevent exactly
+ * this class of silent drift.
+ */
+interface MeshWorkflowClient {
+  COLLECTION_WORKFLOW_LIST: (input: {
+    limit?: number;
+    offset?: number;
+  }) => Promise<{
+    items: WorkflowCollectionItem[];
+    totalCount: number;
+    hasMore: boolean;
+  }>;
+  COLLECTION_WORKFLOW_CREATE: (input: {
+    data: {
+      id: string;
+      title: string;
+      description?: string;
+      virtual_mcp_id?: string;
+      steps: Step[];
+    };
+  }) => Promise<{ item: WorkflowCollectionItem }>;
+  COLLECTION_WORKFLOW_UPDATE: (input: {
+    id: string;
+    data: {
+      title?: string;
+      description?: string;
+      virtual_mcp_id?: string;
+      steps?: Step[];
+    };
+  }) => Promise<{ success: boolean; error?: string }>;
+  COLLECTION_WORKFLOW_DELETE: (input: {
+    id: string;
+  }) => Promise<{ success: boolean; error?: string }>;
+  COLLECTION_WORKFLOW_EXECUTION_CREATE: (input: {
+    workflow_collection_id: string;
+    virtual_mcp_id?: string;
+    input?: Record<string, unknown>;
+    start_at_epoch_ms?: number;
+  }) => Promise<{ item: { id: string } }>;
+  COLLECTION_VIRTUAL_MCP_LIST: (input: {
+    where?: {
+      operator: "and";
+      conditions: Array<{ field: string[]; operator: string; value: unknown }>;
+    };
+    limit?: number;
+    offset?: number;
+  }) => Promise<{
+    items: DefaultVirtualMCPItem[];
+    totalCount: number;
+    hasMore: boolean;
+  }>;
+  COLLECTION_VIRTUAL_MCP_CREATE: (input: {
+    data: {
+      title: string;
+      connections: Array<{
+        connection_id: string;
+        selected_tools: null;
+      }>;
+    };
+  }) => Promise<{ item: DefaultVirtualMCPItem }>;
+}
+
+function slugify(title: string): string {
+  return title
+    .toLowerCase()
+    .trim()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-|-$/g, "");
+}
+
+function workflowId(connectionId: string, title: string): string {
+  return `${connectionId}::${slugify(title)}`;
+}
+
+/**
+ * Derives the auto-generated trigger tool ID for a workflow.
+ * "Fetch Users and Process" → "START_WORKFLOW_FETCH_USERS_AND_PROCESS"
+ */
+export function workflowToolId(title: string): string {
+  return `START_WORKFLOW_${slugify(title).toUpperCase().replace(/-/g, "_")}`;
+}
+
+function createMeshSelfClient(
+  meshUrl: string,
+  token?: string,
+): MeshWorkflowClient {
+  const connection = proxyConnectionForId("self", { meshUrl, token });
+  return MCPClient.forConnection(connection) as unknown as MeshWorkflowClient;
+}
+
+// I7: Per-connectionId mutex — chains incoming syncs so operations never interleave.
+const syncInFlight = new Map<string, Promise<void>>();
+
+// I4: Fingerprint of the last successfully synced declared set, keyed by connectionId.
+// Capped at MAX_FINGERPRINT_CACHE entries to prevent unbounded growth in environments
+// with rotating connection IDs. Oldest entry is evicted when the cap is reached.
+// Callers that own connection lifecycle should call Workflow.clearFingerprint() on teardown.
+const MAX_FINGERPRINT_CACHE = 500;
+const workflowFingerprints = new Map<string, string>();
+
+function setFingerprint(connectionId: string, fingerprint: string) {
+  if (
+    !workflowFingerprints.has(connectionId) &&
+    workflowFingerprints.size >= MAX_FINGERPRINT_CACHE
+  ) {
+    const firstKey = workflowFingerprints.keys().next().value;
+    if (firstKey !== undefined) workflowFingerprints.delete(firstKey);
+  }
+  workflowFingerprints.set(connectionId, fingerprint);
+}
+
+// Derives the title for the auto-generated default Virtual MCP.
+// Embedding the connectionId makes each VMCP identifiable in the UI and
+// uniquely addressable in LIST lookups without relying on the connection_id
+// filter alone (which would match any VMCP that includes this connection).
+function defaultVmcpTitle(connectionId: string): string {
+  return `Workflows Agent (${connectionId})`;
+}
+
+// Cache of connectionId → auto-created default Virtual MCP ID.
+// Capped at the same size as the fingerprint cache.
+const defaultVmcpByConnection = new Map<string, string>();
+
+function setDefaultVmcp(connectionId: string, vmcpId: string) {
+  if (
+    !defaultVmcpByConnection.has(connectionId) &&
+    defaultVmcpByConnection.size >= MAX_FINGERPRINT_CACHE
+  ) {
+    const firstKey = defaultVmcpByConnection.keys().next().value;
+    if (firstKey !== undefined) defaultVmcpByConnection.delete(firstKey);
+  }
+  defaultVmcpByConnection.set(connectionId, vmcpId);
+}
+
+/**
+ * Returns the ID of the "Workflows Agent" Virtual MCP for a connection,
+ * creating one if it does not yet exist.
+ *
+ * Resolution order:
+ *   1. Module-level cache (avoids the round-trip within a process lifetime).
+ *   2. Remote LIST filtered by connection_id + title (survives restarts).
+ *   3. Remote CREATE — only when no matching VMCP is found.
+ *
+ * Any network failure is logged and causes the function to return undefined
+ * so callers continue without a default rather than failing the whole sync.
+ */
+async function resolveDefaultVirtualMcp(
+  connectionId: string,
+  client: MeshWorkflowClient,
+  tag: string,
+): Promise<string | undefined> {
+  const cached = defaultVmcpByConnection.get(connectionId);
+  if (cached) {
+    console.log(`${tag} Using cached default Virtual MCP: ${cached}`);
+    return cached;
+  }
+
+  const title = defaultVmcpTitle(connectionId);
+
+  try {
+    const result = await client.COLLECTION_VIRTUAL_MCP_LIST({
+      where: {
+        operator: "and",
+        conditions: [
+          { field: ["connection_id"], operator: "eq", value: connectionId },
+          { field: ["title"], operator: "eq", value: title },
+        ],
+      },
+      limit: 1,
+    });
+    if (result.items.length > 0) {
+      const vmcpId = result.items[0]!.id;
+      setDefaultVmcp(connectionId, vmcpId);
+      console.log(`${tag} Found existing default Virtual MCP: ${vmcpId}`);
+      return vmcpId;
+    }
+  } catch (err) {
+    console.warn(
+      `${tag} Could not list Virtual MCPs — proceeding without default. Error: ${err instanceof Error ? err.message : String(err)}`,
+    );
+    return undefined;
+  }
+
+  try {
+    const created = await client.COLLECTION_VIRTUAL_MCP_CREATE({
+      data: {
+        title,
+        connections: [{ connection_id: connectionId, selected_tools: null }],
+      },
+    });
+    const vmcpId = created.item.id;
+    setDefaultVmcp(connectionId, vmcpId);
+    console.log(`${tag} Created default Virtual MCP: ${vmcpId}`);
+    return vmcpId;
+  } catch (err) {
+    console.warn(
+      `${tag} Could not create default Virtual MCP — proceeding without default. Error: ${err instanceof Error ? err.message : String(err)}`,
+    );
+    return undefined;
+  }
+}
+
+function fingerprintWorkflows(declared: WorkflowDefinition[]): string {
+  return JSON.stringify(
+    declared.map((w) => ({
+      title: w.title,
+      description: w.description ?? null,
+      virtual_mcp_id: w.virtual_mcp_id ?? null,
+      steps: w.steps,
+      toolId: w.toolId ?? null,
+    })),
+  );
+}
+
+async function doSyncWorkflows(
+  declared: WorkflowDefinition[],
+  meshUrl: string,
+  connectionId: string,
+  token?: string,
+  _clientOverride?: MeshWorkflowClient,
+): Promise<void> {
+  const tag = `[Workflows][${connectionId}]`;
+
+  // I6: Reject any title that slugifies to empty — would produce IDs like "conn_abc::".
+  const emptySlugWf = declared.find((w) => slugify(w.title) === "");
+  if (emptySlugWf !== undefined) {
+    console.warn(
+      `${tag} Workflow title "${emptySlugWf.title}" produces an empty ID. Skipping sync.`,
+    );
+    return;
+  }
+
+  if (declared.length > 0) {
+    const slugs = declared.map((w) => slugify(w.title));
+    const uniqueSlugs = new Set(slugs);
+    if (uniqueSlugs.size !== slugs.length) {
+      const duplicateSlugs = new Set(
+        slugs.filter((s, i) => slugs.indexOf(s) !== i),
+      );
+      const collidingTitles = declared
+        .filter((w) => duplicateSlugs.has(slugify(w.title)))
+        .map((w) => w.title);
+      console.warn(
+        `${tag} Workflow titles that produce duplicate IDs: ${[...new Set(collidingTitles)].join(", ")}. Skipping sync.`,
+      );
+      return;
+    }
+  }
+
+  // I4: Skip the remote round-trip when the declared set is identical to the last sync.
+  const fingerprint = fingerprintWorkflows(declared);
+  const storedFingerprint = workflowFingerprints.get(connectionId);
+  if (storedFingerprint === fingerprint) {
+    console.log(
+      `${tag} Fingerprint unchanged — skipping sync. Declared: ${declared.length} workflow(s): [${declared.map((w) => w.title).join(", ")}]`,
+    );
+    return;
+  }
+  console.log(
+    `${tag} Fingerprint changed (or first sync) — starting sync. Declared: ${declared.length} workflow(s): [${declared.map((w) => w.title).join(", ")}]`,
+    storedFingerprint
+      ? "(previous fingerprint existed)"
+      : "(no previous fingerprint)",
+  );
+
+  const client = _clientOverride ?? createMeshSelfClient(meshUrl, token);
+
+  // Only resolve (or lazily create) the default Virtual MCP when at least one
+  // declared workflow actually needs the fallback `virtual_mcp_id`.
+  const needsDefault = declared.some((w) => w.virtual_mcp_id === undefined);
+  const defaultVmcpId = needsDefault
+    ? await resolveDefaultVirtualMcp(connectionId, client, tag)
+    : undefined;
+
+  let existing: WorkflowCollectionItem[];
+  try {
+    const allItems: WorkflowCollectionItem[] = [];
+    let offset = 0;
+    const limit = 200;
+    while (true) {
+      const page = await client.COLLECTION_WORKFLOW_LIST({ limit, offset });
+      allItems.push(...page.items);
+      if (!page.hasMore || page.items.length === 0) break;
+      offset += page.items.length;
+    }
+    existing = allItems;
+    console.log(
+      `${tag} LIST returned ${existing.length} total workflow(s). IDs owned by this connection: [${
+        existing
+          .filter((w) => w.id.startsWith(`${connectionId}::`))
+          .map((w) => w.id)
+          .join(", ") || "none"
+      }]`,
+    );
+  } catch (err) {
+    const errMsg = err instanceof Error ? err.message : String(err);
+    console.warn(
+      `${tag} Could not list workflows (workflows plugin may not be enabled). Skipping sync. Error: ${errMsg}`,
+    );
+    return;
+  }
+
+  const prefix = `${connectionId}::`;
+  const managed = new Map(
+    existing.filter((w) => w.id.startsWith(prefix)).map((w) => [w.id, w]),
+  );
+
+  // I5: Build ID→definition map synchronously so declaredIds is ready before
+  // parallelizing — the orphan-delete pass needs the complete set upfront.
+  const declaredEntries = declared.map(
+    (wf) => [workflowId(connectionId, wf.title), wf] as const,
+  );
+  const declaredIds = new Set(declaredEntries.map(([id]) => id));
+
+  let hadError = false;
+
+  // I5: Upserts run in parallel — no ordering dependency between workflows.
+  await Promise.all(
+    declaredEntries.map(async ([id, wf]) => {
+      const op = managed.has(id) ? "UPDATE" : "CREATE";
+      console.log(`${tag} ${op} "${wf.title}" (id=${id})`);
+      try {
+        // Explicit declaration wins; fall back to the auto-resolved default.
+        const resolvedVmcpId = wf.virtual_mcp_id ?? defaultVmcpId;
+
+        if (op === "UPDATE") {
+          const result = await client.COLLECTION_WORKFLOW_UPDATE({
+            id,
+            data: {
+              title: wf.title,
+              description: wf.description,
+              ...(resolvedVmcpId !== undefined && {
+                virtual_mcp_id: resolvedVmcpId,
+              }),
+              steps: wf.steps,
+            },
+          });
+          if (!result.success) {
+            hadError = true;
+            console.warn(
+              `${tag} UPDATE "${wf.title}" returned success=false:`,
+              String(result.error ?? "(no error message)"),
+            );
+          } else {
+            console.log(`${tag} UPDATE "${wf.title}" OK`);
+          }
+        } else {
+          await client.COLLECTION_WORKFLOW_CREATE({
+            data: {
+              id,
+              title: wf.title,
+              description: wf.description,
+              virtual_mcp_id: resolvedVmcpId,
+              steps: wf.steps,
+            },
+          });
+          console.log(`${tag} CREATE "${wf.title}" OK`);
+        }
+      } catch (error) {
+        hadError = true;
+        console.warn(
+          `${tag} Failed to ${op} workflow "${wf.title}":`,
+          error instanceof Error ? error.message : String(error),
+        );
+      }
+    }),
+  );
+
+  // I5: Deletes run in parallel — orphans are independent of each other.
+  const orphanIds = [...managed.keys()].filter((id) => !declaredIds.has(id));
+  if (orphanIds.length > 0) {
+    console.log(
+      `${tag} Deleting ${orphanIds.length} orphaned workflow(s): [${orphanIds.join(", ")}]`,
+    );
+  }
+  await Promise.all(
+    orphanIds.map(async (id) => {
+      try {
+        await client.COLLECTION_WORKFLOW_DELETE({ id });
+        console.log(`${tag} DELETE "${id}" OK`);
+      } catch (error) {
+        hadError = true;
+        console.warn(
+          `${tag} Failed to delete orphaned workflow "${id}":`,
+          error instanceof Error ? error.message : String(error),
+        );
+      }
+    }),
+  );
+
+  // I4: Only record the fingerprint when every operation succeeded so that
+  // a follow-up call with an identical declared set retries any failures
+  // rather than silently skipping them.
+  if (!hadError) {
+    setFingerprint(connectionId, fingerprint);
+    console.log(`${tag} Sync complete — fingerprint stored.`);
+  } else {
+    console.warn(
+      `${tag} Sync finished with errors — fingerprint NOT stored so the next call will retry.`,
+    );
+  }
+}
+
+async function syncWorkflows(
+  declared: WorkflowDefinition[],
+  meshUrl: string,
+  connectionId: string,
+  token?: string,
+  /**
+   * @internal Only used in tests to capture payloads without a real server.
+   * Not part of the public API contract; may be removed without notice.
+   */
+  _clientOverride?: MeshWorkflowClient,
+): Promise<void> {
+  // I7: Chain onto any in-flight sync for this connectionId so concurrent calls
+  // never interleave LIST/CREATE/DELETE operations against the same connection.
+  const previous = syncInFlight.get(connectionId) ?? Promise.resolve();
+  const next = previous
+    // Isolate from predecessor's rejection so a failed prior sync doesn't
+    // propagate its error to unrelated callers queued behind it.
+    .catch(() => {})
+    .then(() =>
+      doSyncWorkflows(declared, meshUrl, connectionId, token, _clientOverride),
+    )
+    .finally(() => {
+      if (syncInFlight.get(connectionId) === next) {
+        syncInFlight.delete(connectionId);
+      }
+    });
+  syncInFlight.set(connectionId, next);
+  return next;
+}
+
+/**
+ * Scopes required by a connection that declares workflows.
+ * Co-located here so any rename of a server-side tool name causes a compile
+ * error in the consumer rather than a silent scope mismatch.
+ */
+export const WORKFLOW_SCOPES = [
+  "SELF::COLLECTION_WORKFLOW_LIST",
+  "SELF::COLLECTION_WORKFLOW_CREATE",
+  "SELF::COLLECTION_WORKFLOW_UPDATE",
+  "SELF::COLLECTION_WORKFLOW_DELETE",
+  "SELF::COLLECTION_WORKFLOW_EXECUTION_CREATE",
+  "SELF::COLLECTION_VIRTUAL_MCP_LIST",
+  "SELF::COLLECTION_VIRTUAL_MCP_CREATE",
+] as const;
+
+export const Workflow = {
+  sync: syncWorkflows,
+  slugify,
+  workflowId,
+  toolId: workflowToolId,
+  /**
+   * Creates a workflow execution via the mesh self-endpoint.
+   * Returns the execution ID of the newly created execution.
+   * This keeps the MeshWorkflowClient factory internal to this module.
+   */
+  createExecution: async (
+    meshUrl: string,
+    token: string | undefined,
+    params: {
+      workflow_collection_id: string;
+      virtual_mcp_id?: string;
+      input?: Record<string, unknown>;
+      start_at_epoch_ms?: number;
+    },
+  ): Promise<string> => {
+    const client = createMeshSelfClient(meshUrl, token);
+    const result = await client.COLLECTION_WORKFLOW_EXECUTION_CREATE(params);
+    return result.item.id;
+  },
+  /**
+   * Clears the cached fingerprint and default Virtual MCP ID for a connection
+   * so the next sync performs a full remote round-trip. Call this on connection
+   * teardown or when you need to force a re-sync without changing the declared
+   * workflow set.
+   */
+  clearFingerprint: (connectionId: string) => {
+    workflowFingerprints.delete(connectionId);
+    defaultVmcpByConnection.delete(connectionId);
+  },
+};
+
+// ============================================================================
+// Fluent Workflow Builder
+// ============================================================================
+
+/**
+ * Minimal tool shape for builder type inference and schema injection.
+ * Defined locally to avoid a circular import with tools.ts (which imports
+ * WorkflowDefinition from this file). Includes inputSchema so the builder
+ * can derive per-tool input key suggestions, and outputSchema so the builder
+ * can auto-inject a step's outputSchema to detect schema drift at sync time.
+ */
+type ToolLike<TId extends string = string> = {
+  id: TId;
+  inputSchema: ZodTypeAny;
+  outputSchema?: ZodTypeAny;
+};
+
+/**
+ * All valid @ref strings given the set of declared step names TSteps.
+ *
+ * - `@input` / `@input.field`       — workflow input
+ * - `@stepName` / `@stepName.field` — output of a declared step
+ * - `@item` / `@item.${string}`     — current forEach item
+ * - `@index`                        — current forEach index
+ * - `@ctx.execution_id`             — current execution ID
+ *
+ * `string & {}` keeps the type as `string` so arbitrary values still compile,
+ * but the union members get autocomplete and type-narrowing in editors.
+ */
+type KnownRefs<TSteps extends string> =
+  | `@input`
+  | `@input.${string}`
+  | `@item`
+  | `@item.${string}`
+  | `@index`
+  | `@ctx.execution_id`
+  | `@${TSteps}`
+  | `@${TSteps}.${string}`
+  | (string & {});
+
+type StepInput<TSteps extends string> = Record<
+  string,
+  KnownRefs<TSteps> | unknown
+>;
+
+/**
+ * Derives the `input` type for a tool step.
+ *
+ * Keys are the tool's inputSchema field names (for autocomplete); values are
+ * @refs or any literal. An index signature allows additional arbitrary keys.
+ * Falls back to generic StepInput when the tool is not found in TTools.
+ */
+type InputForTool<
+  TTools extends readonly ToolLike[],
+  TId extends string,
+  TSteps extends string,
+> = Extract<TTools[number], { id: TId }> extends { inputSchema: infer TIn }
+  ? TIn extends ZodTypeAny
+    ? {
+        [K in keyof TIn["_output"]]?: KnownRefs<TSteps> | TIn["_output"][K];
+      } & { [key: string]: KnownRefs<TSteps> | unknown }
+    : StepInput<TSteps>
+  : StepInput<TSteps>;
+
+type BaseStepFields = Omit<Step, "name" | "input" | "action">;
+type BaseForEachFields = Omit<Step, "name" | "forEach" | "input" | "action">;
+
+/**
+ * Tool-call variants of StepOpts — one discriminated member per tool ID so
+ * TypeScript narrows the `input` type based on the value of `toolName`.
+ * Falls back to `string` for toolName when no tools are registered.
+ */
+type ToolCallStepOpts<
+  TSteps extends string,
+  TTools extends readonly ToolLike[],
+> = [TTools[number]] extends [never]
+  ? BaseStepFields & {
+      action: { toolName: string & {}; transformCode?: string };
+      input?: StepInput<TSteps>;
+    }
+  : {
+      [TId in TTools[number]["id"]]: BaseStepFields & {
+        action: { toolName: TId; transformCode?: string };
+        input?: InputForTool<TTools, TId, TSteps>;
+      };
+    }[TTools[number]["id"]];
+
+type StepOpts<TSteps extends string, TTools extends readonly ToolLike[]> =
+  | ToolCallStepOpts<TSteps, TTools>
+  | (BaseStepFields & { action: { code: string }; input?: StepInput<TSteps> });
+
+type ToolCallForEachOpts<
+  TSteps extends string,
+  TTools extends readonly ToolLike[],
+> = [TTools[number]] extends [never]
+  ? BaseForEachFields & {
+      action: { toolName: string & {}; transformCode?: string };
+      input?: StepInput<TSteps>;
+      concurrency?: number;
+    }
+  : {
+      [TId in TTools[number]["id"]]: BaseForEachFields & {
+        action: { toolName: TId; transformCode?: string };
+        input?: InputForTool<TTools, TId, TSteps>;
+        concurrency?: number;
+      };
+    }[TTools[number]["id"]];
+
+type ForEachItemOpts<
+  TSteps extends string,
+  TTools extends readonly ToolLike[],
+> =
+  | ToolCallForEachOpts<TSteps, TTools>
+  | (BaseForEachFields & {
+      action: { code: string };
+      input?: StepInput<TSteps>;
+      concurrency?: number;
+    });
+
+class WorkflowBuilder<
+  TSteps extends string = never,
+  TTools extends readonly ToolLike[] = never[],
+> {
+  private readonly _steps: Step[] = [];
+  private readonly _tools: readonly ToolLike[];
+
+  constructor(
+    private readonly meta: Omit<WorkflowDefinition, "steps">,
+    tools: readonly ToolLike[] = [],
+  ) {
+    this._tools = tools;
+  }
+
+  /**
+   * Auto-injects the referenced tool's outputSchema into the step if:
+   * 1. The step action is a tool call (has toolName)
+   * 2. The matched tool has an outputSchema
+   * 3. The step does not already have an explicit outputSchema
+   *
+   * This ensures that when a tool's outputSchema changes, the workflow
+   * fingerprint changes and the sync correctly updates the stored workflow.
+   */
+  private _withToolSchema(step: Step): Step {
+    const action = step.action as { toolName?: string } | undefined;
+    if (!action?.toolName) return step;
+    const tool = this._tools.find((t) => t.id === action.toolName);
+    if (!tool?.outputSchema || step.outputSchema !== undefined) return step;
+    return {
+      ...step,
+      outputSchema: z.toJSONSchema(tool.outputSchema) as Step["outputSchema"],
+    };
+  }
+
+  step<TName extends string>(
+    name: TName,
+    opts: StepOpts<TSteps, TTools>,
+  ): WorkflowBuilder<TSteps | TName, TTools> {
+    this._steps.push(
+      this._withToolSchema({ name, ...(opts as Omit<Step, "name">) }),
+    );
+    return this as unknown as WorkflowBuilder<TSteps | TName, TTools>;
+  }
+
+  /**
+   * Creates a step that iterates over an array resolved from a @ref.
+   * Maps to the engine's Step.forEach field.
+   *
+   * @param name  - Unique step name
+   * @param ref   - @ref to the array to iterate (e.g. "@fetch_users")
+   * @param opts  - Step definition (action, input, config, outputSchema)
+   */
+  forEachItem<TName extends string>(
+    name: TName,
+    ref: KnownRefs<TSteps>,
+    opts: ForEachItemOpts<TSteps, TTools>,
+  ): WorkflowBuilder<TSteps | TName, TTools> {
+    const { concurrency = 1, ...rest } = opts;
+    this._steps.push(
+      this._withToolSchema({
+        name,
+        ...(rest as Omit<Step, "name" | "forEach">),
+        forEach: { ref, concurrency },
+      }),
+    );
+    return this as unknown as WorkflowBuilder<TSteps | TName, TTools>;
+  }
+
+  /**
+   * Spreads an array of pre-built steps into the workflow.
+   * Step names from the array are not tracked in the type — use .step() for
+   * tracked composition.
+   */
+  addSteps(steps: Step[]): this {
+    this._steps.push(...steps);
+    return this;
+  }
+
+  build(): WorkflowDefinition {
+    return { ...this.meta, steps: [...this._steps] };
+  }
+}
+
+/**
+ * Fluent builder for workflow definitions.
+ *
+ * Pass your locally-declared tools as the second argument to get autocomplete
+ * for `toolName` throughout the workflow. Step names are also tracked so
+ * `@ref` strings autocomplete in `input` after each `.step()` call.
+ *
+ * @example
+ * const GET_USERS = createTool({ id: "GET_USERS", ... });
+ * const PROCESS_USER = createTool({ id: "PROCESS_USER", ... });
+ *
+ * const myWorkflow = createWorkflow(
+ *   { title: "Fetch and Process" },
+ *   [GET_USERS, PROCESS_USER],
+ * )
+ *   .step("fetch_users", {
+ *     action: { toolName: "GET_USERS" },  // ← autocomplete: "GET_USERS" | "PROCESS_USER"
+ *   })
+ *   .forEachItem("process_user", "@fetch_users", {
+ *     //                          ^ autocomplete: @fetch_users, @input, @item...
+ *     action: { toolName: "PROCESS_USER" },
+ *     input: { userId: "@item.id" },
+ *   })
+ *   .build();
+ */
+export function createWorkflow<TTools extends readonly ToolLike[] = never[]>(
+  meta: Omit<WorkflowDefinition, "steps">,
+  tools?: TTools,
+): WorkflowBuilder<never, TTools> {
+  return new WorkflowBuilder(meta, tools ?? []) as unknown as WorkflowBuilder<
+    never,
+    TTools
+  >;
+}