@yolk-sdk/vercel-workflows 0.1.0-canary.72 → 0.1.0-canary.74

package/README.md

@@ -132,10 +132,40 @@ export async function runAgentWorkflow(input: { request: unknown; context: unkno
 }
 ```
 
-`runModelStep`, `runToolBatchStep`, `closeStream`, and `writeError` are host-owned
-`'use step'` functions. Keep provider calls, tools, persistence, telemetry, and Effect runtimes in
+`runModelStep`, `closeStream`, and `writeError` are host-owned `'use step'` functions.
+`runToolBatchStep` may instead be Workflow orchestration calling concrete per-call steps. Keep provider calls, tools, persistence, telemetry, and Effect runtimes in
 those steps, not in the `'use workflow'` orchestration body.
 
+## Independent children
+
+`orchestrateWorkflowToolBatch` runs a full-batch `preflight` before any `execute` callback,
+limits local concurrency, and returns results in original call order. Both callbacks are host
+seams: perform IO in steps, not in the orchestration helper. The host commits exactly one tool
+result per call. Return a pause value from preflight when any HITL request is pending.
+If an execution rejects, the helper stops dispatching new calls, settles already-active siblings,
+and returns their ordered progress plus `failures`. Hosts must propagate those failures while
+retaining completed results and usage; do not treat a partial batch as successful.
+
+Start child workflows with Workflow 5 `start(childWorkflow, args)` **from orchestration**, not
+inside the parent tool step. A child wrapper runs its own model/tool steps and returns a typed
+application outcome; platform `completed` alone does not prove application success. Foreground
+hosts await that child outcome; background hosts return an accepted handle and continue.
+
+`awaitWorkflowChild({ read, sleep })` polls short durable read steps with a host-provided Workflow
+`sleep` between reads. Both callbacks receive the same zero-based attempt index, so hosts can
+apply capped backoff and end an observation after a bounded number of reads. At that ceiling,
+`read` should return `{ done: true, value: stillRunningObservation }`; this ends polling, not the
+child lifecycle. Preserve an owned handle for eventual result lookup. Existing zero-argument
+callbacks remain supported and the helper has no implicit budget. Hosts must explicitly bound
+long waits to avoid unbounded durable event accumulation. Do not hold a step open awaiting a long
+`run.returnValue` poll.
+
+Hosts own immutable logical reservations, admission/CAS, ownership checks, storage, bounded
+fanout, safe errors, credentials, and cancellation policy. Parent completion/failure must not
+implicitly cancel independent children. Explicit Stop should persist a durable tombstone before
+sweeping admitted child ids, reject late admission, and expose partial sweep failures for retry.
+Give each independent stream and parallel call its own deterministic event-id namespace.
+
 ## Awaiting input
 
 When a tool batch needs HITL input, return `awaitingInput` from `runToolBatchStep`. The package

package/dist/index.d.mts

@@ -1,3 +1,4 @@
 import { SerializableWorkflowState, VercelAgentWorkflowAwaitingInput, VercelAgentWorkflowInput, VercelAgentWorkflowLoopConfig, VercelAgentWorkflowModelStepInput, VercelAgentWorkflowModelStepResult, VercelAgentWorkflowRunResult, VercelAgentWorkflowStepRetryPolicy, VercelAgentWorkflowToolBatchStepInput, VercelAgentWorkflowToolBatchStepResult, WorkflowStepResult, defaultMaxWorkflowTurns, noWorkflowStepRetry, retryWorkflowStep, runVercelAgentWorkflow, settleWorkflowStep } from "./workflow-loop.mjs";
 import { CommitThenWriteTerminalEventInput, CommitThenWriteTerminalEventResult, DurableAgentEvent, DurableAgentEventIdInput, DurableAgentEventSequencerState, SequenceDurableAgentEventInput, SequencedDurableAgentEvent, WriteDurableAgentEventInput, commitThenWriteTerminalEvent, durableAgentEventId, makeDurableAgentEventSequencerState, sequenceDurableAgentEvent, writeDurableAgentEvent } from "./workflow-events.mjs";
-export { type CommitThenWriteTerminalEventInput, type CommitThenWriteTerminalEventResult, type DurableAgentEvent, type DurableAgentEventIdInput, type DurableAgentEventSequencerState, type SequenceDurableAgentEventInput, type SequencedDurableAgentEvent, type SerializableWorkflowState, type VercelAgentWorkflowAwaitingInput, type VercelAgentWorkflowInput, type VercelAgentWorkflowLoopConfig, type VercelAgentWorkflowModelStepInput, type VercelAgentWorkflowModelStepResult, type VercelAgentWorkflowRunResult, type VercelAgentWorkflowStepRetryPolicy, type VercelAgentWorkflowToolBatchStepInput, type VercelAgentWorkflowToolBatchStepResult, type WorkflowStepResult, type WriteDurableAgentEventInput, commitThenWriteTerminalEvent, defaultMaxWorkflowTurns, durableAgentEventId, makeDurableAgentEventSequencerState, noWorkflowStepRetry, retryWorkflowStep, runVercelAgentWorkflow, sequenceDurableAgentEvent, settleWorkflowStep, writeDurableAgentEvent };
+import { awaitWorkflowChild, orchestrateWorkflowToolBatch } from "./workflow-children.mjs";
+export { type CommitThenWriteTerminalEventInput, type CommitThenWriteTerminalEventResult, type DurableAgentEvent, type DurableAgentEventIdInput, type DurableAgentEventSequencerState, type SequenceDurableAgentEventInput, type SequencedDurableAgentEvent, type SerializableWorkflowState, type VercelAgentWorkflowAwaitingInput, type VercelAgentWorkflowInput, type VercelAgentWorkflowLoopConfig, type VercelAgentWorkflowModelStepInput, type VercelAgentWorkflowModelStepResult, type VercelAgentWorkflowRunResult, type VercelAgentWorkflowStepRetryPolicy, type VercelAgentWorkflowToolBatchStepInput, type VercelAgentWorkflowToolBatchStepResult, type WorkflowStepResult, type WriteDurableAgentEventInput, awaitWorkflowChild, commitThenWriteTerminalEvent, defaultMaxWorkflowTurns, durableAgentEventId, makeDurableAgentEventSequencerState, noWorkflowStepRetry, orchestrateWorkflowToolBatch, retryWorkflowStep, runVercelAgentWorkflow, sequenceDurableAgentEvent, settleWorkflowStep, writeDurableAgentEvent };

package/dist/index.mjs

@@ -1,3 +1,4 @@
 import { defaultMaxWorkflowTurns, noWorkflowStepRetry, retryWorkflowStep, runVercelAgentWorkflow, settleWorkflowStep } from "./workflow-loop.mjs";
 import { commitThenWriteTerminalEvent, durableAgentEventId, makeDurableAgentEventSequencerState, sequenceDurableAgentEvent, writeDurableAgentEvent } from "./workflow-events.mjs";
-export { commitThenWriteTerminalEvent, defaultMaxWorkflowTurns, durableAgentEventId, makeDurableAgentEventSequencerState, noWorkflowStepRetry, retryWorkflowStep, runVercelAgentWorkflow, sequenceDurableAgentEvent, settleWorkflowStep, writeDurableAgentEvent };
+import { awaitWorkflowChild, orchestrateWorkflowToolBatch } from "./workflow-children.mjs";
+export { awaitWorkflowChild, commitThenWriteTerminalEvent, defaultMaxWorkflowTurns, durableAgentEventId, makeDurableAgentEventSequencerState, noWorkflowStepRetry, orchestrateWorkflowToolBatch, retryWorkflowStep, runVercelAgentWorkflow, sequenceDurableAgentEvent, settleWorkflowStep, writeDurableAgentEvent };

package/dist/workflow-children.d.mts

@@ -0,0 +1,42 @@
+//#region src/workflow-children.d.ts
+/** Workflow orchestration only. Callbacks must be durable steps (sleep must be Workflow sleep).
+ * A read is short-lived; never put a long returnValue poll inside a step.
+ * Both callbacks receive a deterministic zero-based attempt for host budgets/backoff.
+ * Defaults remain unbounded: hosts end observation at their ceiling by returning done + value.
+ */
+declare function awaitWorkflowChild<A>(input: {
+  readonly read: (attempt: number) => Promise<{
+    readonly done: false;
+  } | {
+    readonly done: true;
+    readonly value: A;
+  }>;
+  readonly sleep: (attempt: number) => Promise<void>;
+}): Promise<A>;
+/** Preflight fences the entire batch. On rejection, stop dispatching new work, settle already
+ * active siblings, and return their ordered progress alongside failures. Hosts must handle failures.
+ */
+declare function orchestrateWorkflowToolBatch<Call, Result, Pause>(input: {
+  readonly calls: ReadonlyArray<Call>;
+  readonly concurrency: number;
+  readonly preflight: () => Promise<{
+    readonly ready: true;
+  } | {
+    readonly ready: false;
+    readonly value: Pause;
+  }>;
+  readonly execute: (call: Call, index: number) => Promise<Result>;
+}): Promise<{
+  readonly ready: true;
+  readonly results: ReadonlyArray<Result>;
+  readonly failures?: ReadonlyArray<{
+    readonly index: number;
+    readonly error: unknown;
+  }>;
+} | {
+  readonly ready: false;
+  readonly value: Pause;
+}>;
+//#endregion
+export { awaitWorkflowChild, orchestrateWorkflowToolBatch };
+//# sourceMappingURL=workflow-children.d.mts.map

package/dist/workflow-children.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-children.d.mts","names":[],"sources":["../src/workflow-children.ts"],"mappings":";;AAKA;;;;iBAAsB,kBAAA,GAAA,CAAsB,KAAA;EAAA,SACjC,IAAA,GACP,OAAA,aACG,OAAA;IAAA,SAAmB,IAAA;EAAA;IAAA,SAA2B,IAAA;IAAA,SAAqB,KAAA,EAAO,CAAA;EAAA;EAAA,SACtE,KAAA,GAAQ,OAAA,aAAoB,OAAA;AAAA,IACnC,OAAA,CAAQ,CAAA;;;;iBAYU,4BAAA,qBAAA,CAAkD,KAAA;EAAA,SAC7D,KAAA,EAAO,aAAA,CAAc,IAAA;EAAA,SACrB,WAAA;EAAA,SACA,SAAA,QAAiB,OAAA;IAAA,SACb,KAAA;EAAA;IAAA,SAA2B,KAAA;IAAA,SAAuB,KAAA,EAAO,KAAA;EAAA;EAAA,SAE7D,OAAA,GAAU,IAAA,EAAM,IAAA,EAAM,KAAA,aAAkB,OAAA,CAAQ,MAAA;AAAA,IACvD,OAAA;EAAA,SAEW,KAAA;EAAA,SACA,OAAA,EAAS,aAAA,CAAc,MAAA;EAAA,SACvB,QAAA,GAAW,aAAA;IAAA,SAAyB,KAAA;IAAA,SAAwB,KAAA;EAAA;AAAA;EAAA,SAE5D,KAAA;EAAA,SAAuB,KAAA,EAAO,KAAA;AAAA"}

package/dist/workflow-children.mjs

@@ -0,0 +1,53 @@
+//#region src/workflow-children.ts
+/** Workflow orchestration only. Callbacks must be durable steps (sleep must be Workflow sleep).
+* A read is short-lived; never put a long returnValue poll inside a step.
+* Both callbacks receive a deterministic zero-based attempt for host budgets/backoff.
+* Defaults remain unbounded: hosts end observation at their ceiling by returning done + value.
+*/
+async function awaitWorkflowChild(input) {
+	const { read, sleep } = input;
+	for (let attempt = 0;; attempt++) {
+		const state = await read(attempt);
+		if (state.done) return state.value;
+		await sleep(attempt);
+	}
+}
+/** Preflight fences the entire batch. On rejection, stop dispatching new work, settle already
+* active siblings, and return their ordered progress alongside failures. Hosts must handle failures.
+*/
+async function orchestrateWorkflowToolBatch(input) {
+	const { calls, concurrency, preflight, execute } = input;
+	const prepared = await preflight();
+	if (!prepared.ready) return prepared;
+	const width = Number.isFinite(concurrency) ? Math.max(1, Math.floor(concurrency)) : 1;
+	const entries = calls.map((call, index) => ({
+		call,
+		index
+	}));
+	let next = 0;
+	const results = /* @__PURE__ */ new Map();
+	const failures = [];
+	await Promise.all(Array.from({ length: Math.min(width, calls.length) }, async () => {
+		while (failures.length === 0) {
+			const entry = entries[next++];
+			if (entry === void 0) return;
+			try {
+				results.set(entry.index, await execute(entry.call, entry.index));
+			} catch (error) {
+				failures.push({
+					index: entry.index,
+					error
+				});
+			}
+		}
+	}));
+	return {
+		ready: true,
+		results: [...results.entries()].sort(([a], [b]) => a - b).map(([, result]) => result),
+		...failures.length === 0 ? {} : { failures: failures.sort((a, b) => a.index - b.index) }
+	};
+}
+//#endregion
+export { awaitWorkflowChild, orchestrateWorkflowToolBatch };
+
+//# sourceMappingURL=workflow-children.mjs.map

package/dist/workflow-children.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-children.mjs","names":[],"sources":["../src/workflow-children.ts"],"sourcesContent":["/** Workflow orchestration only. Callbacks must be durable steps (sleep must be Workflow sleep).\n * A read is short-lived; never put a long returnValue poll inside a step.\n * Both callbacks receive a deterministic zero-based attempt for host budgets/backoff.\n * Defaults remain unbounded: hosts end observation at their ceiling by returning done + value.\n */\nexport async function awaitWorkflowChild<A>(input: {\n  readonly read: (\n    attempt: number\n  ) => Promise<{ readonly done: false } | { readonly done: true; readonly value: A }>\n  readonly sleep: (attempt: number) => Promise<void>\n}): Promise<A> {\n  const { read, sleep } = input\n  for (let attempt = 0; ; attempt++) {\n    const state = await read(attempt)\n    if (state.done) return state.value\n    await sleep(attempt)\n  }\n}\n\n/** Preflight fences the entire batch. On rejection, stop dispatching new work, settle already\n * active siblings, and return their ordered progress alongside failures. Hosts must handle failures.\n */\nexport async function orchestrateWorkflowToolBatch<Call, Result, Pause>(input: {\n  readonly calls: ReadonlyArray<Call>\n  readonly concurrency: number\n  readonly preflight: () => Promise<\n    { readonly ready: true } | { readonly ready: false; readonly value: Pause }\n  >\n  readonly execute: (call: Call, index: number) => Promise<Result>\n}): Promise<\n  | {\n      readonly ready: true\n      readonly results: ReadonlyArray<Result>\n      readonly failures?: ReadonlyArray<{ readonly index: number; readonly error: unknown }>\n    }\n  | { readonly ready: false; readonly value: Pause }\n> {\n  const { calls, concurrency, preflight, execute } = input\n  const prepared = await preflight()\n  if (!prepared.ready) return prepared\n  const width = Number.isFinite(concurrency) ? Math.max(1, Math.floor(concurrency)) : 1\n  const entries = calls.map((call, index) => ({ call, index }))\n  let next = 0\n  const results = new Map<number, Result>()\n  const failures: Array<{ readonly index: number; readonly error: unknown }> = []\n  await Promise.all(\n    Array.from({ length: Math.min(width, calls.length) }, async () => {\n      while (failures.length === 0) {\n        const entry = entries[next++]\n        if (entry === undefined) return\n        try {\n          results.set(entry.index, await execute(entry.call, entry.index))\n        } catch (error) {\n          failures.push({ index: entry.index, error })\n        }\n      }\n    })\n  )\n  return {\n    ready: true,\n    results: [...results.entries()].sort(([a], [b]) => a - b).map(([, result]) => result),\n    ...(failures.length === 0 ? {} : { failures: failures.sort((a, b) => a.index - b.index) })\n  }\n}\n"],"mappings":";;;;;;AAKA,eAAsB,mBAAsB,OAK7B;CACb,MAAM,EAAE,MAAM,UAAU;CACxB,KAAK,IAAI,UAAU,IAAK,WAAW;EACjC,MAAM,QAAQ,MAAM,KAAK,OAAO;EAChC,IAAI,MAAM,MAAM,OAAO,MAAM;EAC7B,MAAM,MAAM,OAAO;CACrB;AACF;;;;AAKA,eAAsB,6BAAkD,OActE;CACA,MAAM,EAAE,OAAO,aAAa,WAAW,YAAY;CACnD,MAAM,WAAW,MAAM,UAAU;CACjC,IAAI,CAAC,SAAS,OAAO,OAAO;CAC5B,MAAM,QAAQ,OAAO,SAAS,WAAW,IAAI,KAAK,IAAI,GAAG,KAAK,MAAM,WAAW,CAAC,IAAI;CACpF,MAAM,UAAU,MAAM,KAAK,MAAM,WAAW;EAAE;EAAM;CAAM,EAAE;CAC5D,IAAI,OAAO;CACX,MAAM,0BAAU,IAAI,IAAoB;CACxC,MAAM,WAAuE,CAAC;CAC9E,MAAM,QAAQ,IACZ,MAAM,KAAK,EAAE,QAAQ,KAAK,IAAI,OAAO,MAAM,MAAM,EAAE,GAAG,YAAY;EAChE,OAAO,SAAS,WAAW,GAAG;GAC5B,MAAM,QAAQ,QAAQ;GACtB,IAAI,UAAU,KAAA,GAAW;GACzB,IAAI;IACF,QAAQ,IAAI,MAAM,OAAO,MAAM,QAAQ,MAAM,MAAM,MAAM,KAAK,CAAC;GACjE,SAAS,OAAO;IACd,SAAS,KAAK;KAAE,OAAO,MAAM;KAAO;IAAM,CAAC;GAC7C;EACF;CACF,CAAC,CACH;CACA,OAAO;EACL,OAAO;EACP,SAAS,CAAC,GAAG,QAAQ,QAAQ,CAAC,EAAE,MAAM,CAAC,IAAI,CAAC,OAAO,IAAI,CAAC,EAAE,KAAK,GAAG,YAAY,MAAM;EACpF,GAAI,SAAS,WAAW,IAAI,CAAC,IAAI,EAAE,UAAU,SAAS,MAAM,GAAG,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE;CAC1F;AACF"}

package/dist/workflow.d.mts

@@ -1,3 +1,4 @@
 import { SerializableWorkflowState, VercelAgentWorkflowAwaitingInput, VercelAgentWorkflowInput, VercelAgentWorkflowLoopConfig, VercelAgentWorkflowModelStepInput, VercelAgentWorkflowModelStepResult, VercelAgentWorkflowRunResult, VercelAgentWorkflowStepRetryPolicy, VercelAgentWorkflowToolBatchStepInput, VercelAgentWorkflowToolBatchStepResult, WorkflowStepResult, defaultMaxWorkflowTurns, noWorkflowStepRetry, retryWorkflowStep, runVercelAgentWorkflow, settleWorkflowStep } from "./workflow-loop.mjs";
 import { CommitThenWriteTerminalEventInput, CommitThenWriteTerminalEventResult, DurableAgentEvent, DurableAgentEventIdInput, DurableAgentEventSequencerState, SequenceDurableAgentEventInput, SequencedDurableAgentEvent, WriteDurableAgentEventInput, commitThenWriteTerminalEvent, durableAgentEventId, makeDurableAgentEventSequencerState, sequenceDurableAgentEvent, writeDurableAgentEvent } from "./workflow-events.mjs";
-export { type CommitThenWriteTerminalEventInput, type CommitThenWriteTerminalEventResult, type DurableAgentEvent, type DurableAgentEventIdInput, type DurableAgentEventSequencerState, type SequenceDurableAgentEventInput, type SequencedDurableAgentEvent, type SerializableWorkflowState, type VercelAgentWorkflowAwaitingInput, type VercelAgentWorkflowInput, type VercelAgentWorkflowLoopConfig, type VercelAgentWorkflowModelStepInput, type VercelAgentWorkflowModelStepResult, type VercelAgentWorkflowRunResult, type VercelAgentWorkflowStepRetryPolicy, type VercelAgentWorkflowToolBatchStepInput, type VercelAgentWorkflowToolBatchStepResult, type WorkflowStepResult, type WriteDurableAgentEventInput, commitThenWriteTerminalEvent, defaultMaxWorkflowTurns, durableAgentEventId, makeDurableAgentEventSequencerState, noWorkflowStepRetry, retryWorkflowStep, runVercelAgentWorkflow, sequenceDurableAgentEvent, settleWorkflowStep, writeDurableAgentEvent };
+import { awaitWorkflowChild, orchestrateWorkflowToolBatch } from "./workflow-children.mjs";
+export { type CommitThenWriteTerminalEventInput, type CommitThenWriteTerminalEventResult, type DurableAgentEvent, type DurableAgentEventIdInput, type DurableAgentEventSequencerState, type SequenceDurableAgentEventInput, type SequencedDurableAgentEvent, type SerializableWorkflowState, type VercelAgentWorkflowAwaitingInput, type VercelAgentWorkflowInput, type VercelAgentWorkflowLoopConfig, type VercelAgentWorkflowModelStepInput, type VercelAgentWorkflowModelStepResult, type VercelAgentWorkflowRunResult, type VercelAgentWorkflowStepRetryPolicy, type VercelAgentWorkflowToolBatchStepInput, type VercelAgentWorkflowToolBatchStepResult, type WorkflowStepResult, type WriteDurableAgentEventInput, awaitWorkflowChild, commitThenWriteTerminalEvent, defaultMaxWorkflowTurns, durableAgentEventId, makeDurableAgentEventSequencerState, noWorkflowStepRetry, orchestrateWorkflowToolBatch, retryWorkflowStep, runVercelAgentWorkflow, sequenceDurableAgentEvent, settleWorkflowStep, writeDurableAgentEvent };

package/dist/workflow.mjs

@@ -1,3 +1,4 @@
 import { defaultMaxWorkflowTurns, noWorkflowStepRetry, retryWorkflowStep, runVercelAgentWorkflow, settleWorkflowStep } from "./workflow-loop.mjs";
 import { commitThenWriteTerminalEvent, durableAgentEventId, makeDurableAgentEventSequencerState, sequenceDurableAgentEvent, writeDurableAgentEvent } from "./workflow-events.mjs";
-export { commitThenWriteTerminalEvent, defaultMaxWorkflowTurns, durableAgentEventId, makeDurableAgentEventSequencerState, noWorkflowStepRetry, retryWorkflowStep, runVercelAgentWorkflow, sequenceDurableAgentEvent, settleWorkflowStep, writeDurableAgentEvent };
+import { awaitWorkflowChild, orchestrateWorkflowToolBatch } from "./workflow-children.mjs";
+export { awaitWorkflowChild, commitThenWriteTerminalEvent, defaultMaxWorkflowTurns, durableAgentEventId, makeDurableAgentEventSequencerState, noWorkflowStepRetry, orchestrateWorkflowToolBatch, retryWorkflowStep, runVercelAgentWorkflow, sequenceDurableAgentEvent, settleWorkflowStep, writeDurableAgentEvent };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yolk-sdk/vercel-workflows",
-  "version": "0.1.0-canary.72",
+  "version": "0.1.0-canary.74",
   "description": "Vercel Workflow orchestration primitives for Yolk agent loops.",
   "license": "MIT",
   "type": "module",

package/src/index.ts

@@ -31,3 +31,4 @@ export type {
   WorkflowStepResult,
   WriteDurableAgentEventInput
 } from './workflow.ts'
+export { awaitWorkflowChild, orchestrateWorkflowToolBatch } from './workflow-children.ts'

package/src/workflow-children.ts

@@ -0,0 +1,64 @@
+/** Workflow orchestration only. Callbacks must be durable steps (sleep must be Workflow sleep).
+ * A read is short-lived; never put a long returnValue poll inside a step.
+ * Both callbacks receive a deterministic zero-based attempt for host budgets/backoff.
+ * Defaults remain unbounded: hosts end observation at their ceiling by returning done + value.
+ */
+export async function awaitWorkflowChild<A>(input: {
+  readonly read: (
+    attempt: number
+  ) => Promise<{ readonly done: false } | { readonly done: true; readonly value: A }>
+  readonly sleep: (attempt: number) => Promise<void>
+}): Promise<A> {
+  const { read, sleep } = input
+  for (let attempt = 0; ; attempt++) {
+    const state = await read(attempt)
+    if (state.done) return state.value
+    await sleep(attempt)
+  }
+}
+
+/** Preflight fences the entire batch. On rejection, stop dispatching new work, settle already
+ * active siblings, and return their ordered progress alongside failures. Hosts must handle failures.
+ */
+export async function orchestrateWorkflowToolBatch<Call, Result, Pause>(input: {
+  readonly calls: ReadonlyArray<Call>
+  readonly concurrency: number
+  readonly preflight: () => Promise<
+    { readonly ready: true } | { readonly ready: false; readonly value: Pause }
+  >
+  readonly execute: (call: Call, index: number) => Promise<Result>
+}): Promise<
+  | {
+      readonly ready: true
+      readonly results: ReadonlyArray<Result>
+      readonly failures?: ReadonlyArray<{ readonly index: number; readonly error: unknown }>
+    }
+  | { readonly ready: false; readonly value: Pause }
+> {
+  const { calls, concurrency, preflight, execute } = input
+  const prepared = await preflight()
+  if (!prepared.ready) return prepared
+  const width = Number.isFinite(concurrency) ? Math.max(1, Math.floor(concurrency)) : 1
+  const entries = calls.map((call, index) => ({ call, index }))
+  let next = 0
+  const results = new Map<number, Result>()
+  const failures: Array<{ readonly index: number; readonly error: unknown }> = []
+  await Promise.all(
+    Array.from({ length: Math.min(width, calls.length) }, async () => {
+      while (failures.length === 0) {
+        const entry = entries[next++]
+        if (entry === undefined) return
+        try {
+          results.set(entry.index, await execute(entry.call, entry.index))
+        } catch (error) {
+          failures.push({ index: entry.index, error })
+        }
+      }
+    })
+  )
+  return {
+    ready: true,
+    results: [...results.entries()].sort(([a], [b]) => a - b).map(([, result]) => result),
+    ...(failures.length === 0 ? {} : { failures: failures.sort((a, b) => a.index - b.index) })
+  }
+}

package/src/workflow.ts

@@ -35,3 +35,4 @@ export type {
   SequencedDurableAgentEvent,
   WriteDurableAgentEventInput
 } from './workflow-events.ts'
+export { awaitWorkflowChild, orchestrateWorkflowToolBatch } from './workflow-children.ts'