@yolk-sdk/vercel-workflows 0.1.0-canary.15

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yolk SDK contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,103 @@
+# @yolk-sdk/vercel-workflows
+
+Vercel Workflow-specific contracts for durable agent model/tool step loops.
+
+## Install
+
+```bash
+pnpm add @yolk-sdk/vercel-workflows@canary effect workflow
+```
+
+Canary APIs are unstable. Keep all `@yolk-sdk/*` packages on the same version.
+
+## Subpaths
+
+| Subpath | Purpose |
+| --- | --- |
+| `@yolk-sdk/vercel-workflows` | Workflow-safe agent loop orchestration APIs |
+| `@yolk-sdk/vercel-workflows/workflow` | Explicit equivalent subpath |
+
+## Imports
+
+Import Workflow APIs from the package root:
+
+```ts
+import {
+  noWorkflowStepRetry,
+  runVercelAgentWorkflow
+} from '@yolk-sdk/vercel-workflows'
+```
+
+The `./workflow` subpath is also exported for explicit imports.
+
+## Runtime model
+
+`runVercelAgentWorkflow` coordinates host-provided callbacks:
+
+- model step: produce model events/tool calls
+- tool batch step: execute requested tools
+- awaiting-input state: carry pending HITL hook data, wait through `awaitInput`, then rerun the
+  same tool batch with accumulated responses
+- close step: flush/close output stream
+- terminal status: completed, step failure, await-input failure, close failure, or max turns exceeded
+
+Continuation state stays plain serializable data for Workflow persistence.
+
+## Minimal workflow wrapper
+
+Host apps keep concrete Workflow directives local and pass them into the package loop:
+
+```ts
+import { createHook } from 'workflow'
+import { runVercelAgentWorkflow } from '@yolk-sdk/vercel-workflows'
+
+export async function runAgentWorkflow(input: { request: unknown; context: unknown }) {
+  'use workflow'
+
+  return await runVercelAgentWorkflow({
+    input,
+    runModelStep,
+    runToolBatchStep,
+    closeStream,
+    writeError,
+    awaitInput: async awaitingInput => {
+      using hook = createHook<unknown>({ token: awaitingInput.hookToken })
+
+      return await hook
+    }
+  })
+}
+```
+
+`runModelStep`, `runToolBatchStep`, `closeStream`, and `writeError` are host-owned
+`'use step'` functions. Keep provider calls, tools, persistence, telemetry, and Effect runtimes in
+those steps, not in the `'use workflow'` orchestration body.
+
+## Awaiting input
+
+When a tool batch needs HITL input, return `awaitingInput` from `runToolBatchStep`. The package
+loop will:
+
+1. pass that payload to `awaitInput`
+2. wait for the hook/webhook response
+3. rerun the same tool batch with `hitlResponses: [...previous, response]`
+
+The host owns `hookToken` construction, auth, resume routes, and response decoding. Use stable
+tokens that the resume side can reconstruct or store.
+
+## Retry policy
+
+Default retry policy is `noWorkflowStepRetry` (`maxAttempts: 1`). Retries are opt-in because streamed retries can duplicate chunks unless host/client de-dupe is ready.
+
+## Host responsibilities
+
+- Own Next/Vercel routes, auth, providers, tools, persistence, and telemetry.
+- Encode/decode app transcript/session state into serializable Workflow inputs.
+- Decide cancellation/resume/conflict UX.
+- Own hook tokens and response validation for HITL resume.
+- Test directive behavior with `@workflow/vitest` when changing package-owned Workflow files.
+
+## Boundaries
+
+- No Next routes, server actions, auth, app tools, DB, UI, or provider SDKs.
+- Effect may run inside host/package step callbacks; workflow orchestration keeps plain data contracts.

package/dist/index.d.mts

@@ -0,0 +1,2 @@
+import { SerializableWorkflowState, VercelAgentWorkflowAwaitingInput, VercelAgentWorkflowInput, VercelAgentWorkflowLoopConfig, VercelAgentWorkflowModelStepInput, VercelAgentWorkflowModelStepResult, VercelAgentWorkflowRunResult, VercelAgentWorkflowStepRetryPolicy, VercelAgentWorkflowToolBatchStepInput, VercelAgentWorkflowToolBatchStepResult, WorkflowStepResult, defaultMaxWorkflowTurns, noWorkflowStepRetry, retryWorkflowStep, runVercelAgentWorkflow, settleWorkflowStep } from "./workflow-loop.mjs";
+export { type SerializableWorkflowState, type VercelAgentWorkflowAwaitingInput, type VercelAgentWorkflowInput, type VercelAgentWorkflowLoopConfig, type VercelAgentWorkflowModelStepInput, type VercelAgentWorkflowModelStepResult, type VercelAgentWorkflowRunResult, type VercelAgentWorkflowStepRetryPolicy, type VercelAgentWorkflowToolBatchStepInput, type VercelAgentWorkflowToolBatchStepResult, type WorkflowStepResult, defaultMaxWorkflowTurns, noWorkflowStepRetry, retryWorkflowStep, runVercelAgentWorkflow, settleWorkflowStep };

package/dist/index.mjs

@@ -0,0 +1,2 @@
+import { defaultMaxWorkflowTurns, noWorkflowStepRetry, retryWorkflowStep, runVercelAgentWorkflow, settleWorkflowStep } from "./workflow-loop.mjs";
+export { defaultMaxWorkflowTurns, noWorkflowStepRetry, retryWorkflowStep, runVercelAgentWorkflow, settleWorkflowStep };

package/dist/workflow-loop.d.mts

@@ -0,0 +1,112 @@
+//#region src/workflow-loop.d.ts
+type VercelAgentWorkflowInput = {
+  readonly request: unknown;
+  readonly context: unknown;
+};
+type SerializableWorkflowState = {
+  readonly request: unknown;
+  readonly messages?: ReadonlyArray<unknown>;
+  readonly createdMessages: ReadonlyArray<unknown>;
+  readonly usage?: unknown;
+  readonly turn: number;
+  readonly eventSequence?: number;
+};
+type VercelAgentWorkflowModelStepInput = {
+  readonly context: unknown;
+  readonly state: SerializableWorkflowState;
+};
+type VercelAgentWorkflowModelStepResult = {
+  readonly done: boolean;
+  readonly messages: ReadonlyArray<unknown>;
+  readonly createdMessages: ReadonlyArray<unknown>;
+  readonly toolCalls: ReadonlyArray<unknown>;
+  readonly usage: unknown;
+  readonly turn: number;
+  readonly eventSequence?: number;
+};
+type VercelAgentWorkflowToolBatchStepInput = {
+  readonly context: unknown;
+  readonly request: unknown;
+  readonly calls: ReadonlyArray<unknown>;
+  readonly createdMessages: ReadonlyArray<unknown>;
+  readonly hitlResponses?: ReadonlyArray<unknown>;
+  readonly usage?: unknown;
+  readonly turn?: number;
+  readonly eventSequence?: number;
+};
+type VercelAgentWorkflowAwaitingInput = {
+  readonly hookToken: string;
+  readonly requests: ReadonlyArray<unknown>;
+  readonly messages: ReadonlyArray<unknown>;
+  readonly usage: unknown;
+  readonly turns: number;
+  readonly eventSequence?: number;
+};
+type VercelAgentWorkflowToolBatchStepResult = {
+  readonly messages: ReadonlyArray<unknown>;
+  readonly createdMessages: ReadonlyArray<unknown>;
+  readonly awaitingInput?: VercelAgentWorkflowAwaitingInput;
+  readonly eventSequence?: number;
+};
+type WorkflowStepResult<A> = {
+  readonly _tag: 'Success';
+  readonly value: A;
+} | {
+  readonly _tag: 'Failure';
+  readonly error: unknown;
+};
+type VercelAgentWorkflowStepRetryPolicy = {
+  readonly maxAttempts: number;
+};
+type VercelAgentWorkflowRunResult = {
+  readonly _tag: 'Completed';
+  readonly turns: number;
+  readonly state: SerializableWorkflowState;
+} | {
+  readonly _tag: 'ModelStepFailed';
+  readonly turn: number;
+  readonly error: unknown;
+  readonly state: SerializableWorkflowState;
+} | {
+  readonly _tag: 'ToolBatchStepFailed';
+  readonly turn: number;
+  readonly error: unknown;
+  readonly state: SerializableWorkflowState;
+} | {
+  readonly _tag: 'AwaitInputFailed';
+  readonly turn: number;
+  readonly error: unknown;
+  readonly awaitingInput: VercelAgentWorkflowAwaitingInput;
+  readonly state: SerializableWorkflowState;
+} | {
+  readonly _tag: 'CloseStreamFailed';
+  readonly turns: number;
+  readonly error: unknown;
+  readonly state: SerializableWorkflowState;
+} | {
+  readonly _tag: 'MaxTurnsExceeded';
+  readonly maxTurns: number;
+  readonly error: Error;
+  readonly state: SerializableWorkflowState;
+};
+type VercelAgentWorkflowLoopConfig = {
+  readonly input: VercelAgentWorkflowInput;
+  readonly maxTurns?: number;
+  readonly runModelStep: (input: VercelAgentWorkflowModelStepInput) => Promise<VercelAgentWorkflowModelStepResult>;
+  readonly runToolBatchStep: (input: VercelAgentWorkflowToolBatchStepInput) => Promise<VercelAgentWorkflowToolBatchStepResult>;
+  readonly closeStream: () => Promise<void>;
+  readonly writeError: (error: unknown) => Promise<void>;
+  readonly awaitInput?: (input: VercelAgentWorkflowAwaitingInput) => Promise<unknown>;
+  readonly modelStepRetry?: VercelAgentWorkflowStepRetryPolicy;
+  readonly toolBatchStepRetry?: VercelAgentWorkflowStepRetryPolicy;
+  readonly awaitInputRetry?: VercelAgentWorkflowStepRetryPolicy;
+  readonly closeStreamRetry?: VercelAgentWorkflowStepRetryPolicy;
+};
+declare const defaultMaxWorkflowTurns = 500;
+declare const noWorkflowStepRetry: VercelAgentWorkflowStepRetryPolicy;
+declare const settleWorkflowStep: <A>(promise: Promise<A>) => Promise<WorkflowStepResult<A>>;
+declare function retryWorkflowStep<A>(runStep: () => Promise<A>, policy?: VercelAgentWorkflowStepRetryPolicy): Promise<A>;
+declare function runVercelAgentWorkflow(config: VercelAgentWorkflowLoopConfig): Promise<VercelAgentWorkflowRunResult>;
+//#endregion
+export { SerializableWorkflowState, VercelAgentWorkflowAwaitingInput, VercelAgentWorkflowInput, VercelAgentWorkflowLoopConfig, VercelAgentWorkflowModelStepInput, VercelAgentWorkflowModelStepResult, VercelAgentWorkflowRunResult, VercelAgentWorkflowStepRetryPolicy, VercelAgentWorkflowToolBatchStepInput, VercelAgentWorkflowToolBatchStepResult, WorkflowStepResult, defaultMaxWorkflowTurns, noWorkflowStepRetry, retryWorkflowStep, runVercelAgentWorkflow, settleWorkflowStep };
+//# sourceMappingURL=workflow-loop.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-loop.d.mts","names":[],"sources":["../src/workflow-loop.ts"],"mappings":"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"}

package/dist/workflow-loop.mjs

@@ -0,0 +1,141 @@
+//#region src/workflow-loop.ts
+const defaultMaxWorkflowTurns = 500;
+const noWorkflowStepRetry = { maxAttempts: 1 };
+const settleWorkflowStep = (promise) => promise.then((value) => ({
+	_tag: "Success",
+	value
+}), (error) => ({
+	_tag: "Failure",
+	error
+}));
+const workflowMaxTurnsError = (maxTurns) => /* @__PURE__ */ new Error(`Vercel agent workflow exceeded max turns: ${maxTurns}`);
+const writeErrorSafely = (writeError, error) => writeError(error).catch(() => void 0);
+const missingAwaitInputHandlerError = () => /* @__PURE__ */ new Error("Vercel agent workflow awaiting input requested but no awaitInput handler is configured");
+const maxRetryAttempts = (policy) => Math.max(1, Math.floor(policy?.maxAttempts ?? noWorkflowStepRetry.maxAttempts));
+async function retryWorkflowStep(runStep, policy) {
+	const maxAttempts = maxRetryAttempts(policy);
+	let attempt = 1;
+	for (;;) try {
+		return await runStep();
+	} catch (error) {
+		if (attempt >= maxAttempts) throw error;
+		attempt += 1;
+	}
+}
+async function runVercelAgentWorkflow(config) {
+	const { input, maxTurns: configuredMaxTurns, runModelStep, runToolBatchStep, closeStream, writeError, awaitInput, modelStepRetry, toolBatchStepRetry, awaitInputRetry, closeStreamRetry } = config;
+	let state = {
+		request: input.request,
+		createdMessages: [],
+		turn: 1,
+		eventSequence: 0
+	};
+	const maxTurns = configuredMaxTurns ?? 500;
+	for (let step = 0; step < maxTurns; step++) {
+		const modelResult = await settleWorkflowStep(retryWorkflowStep(() => runModelStep({
+			context: input.context,
+			state
+		}), modelStepRetry));
+		if (modelResult._tag === "Failure") {
+			await writeErrorSafely(writeError, modelResult.error);
+			return {
+				_tag: "ModelStepFailed",
+				turn: state.turn,
+				error: modelResult.error,
+				state
+			};
+		}
+		if (modelResult.value.done) {
+			const closeResult = await settleWorkflowStep(retryWorkflowStep(closeStream, closeStreamRetry));
+			if (closeResult._tag === "Failure") {
+				await writeErrorSafely(writeError, closeResult.error);
+				return {
+					_tag: "CloseStreamFailed",
+					turns: modelResult.value.turn,
+					error: closeResult.error,
+					state
+				};
+			}
+			return {
+				_tag: "Completed",
+				turns: modelResult.value.turn,
+				state
+			};
+		}
+		let completedToolsResult;
+		let toolHitlResponses = [];
+		let toolEventSequence = modelResult.value.eventSequence ?? state.eventSequence;
+		for (;;) {
+			const toolsResult = await settleWorkflowStep(retryWorkflowStep(() => runToolBatchStep({
+				context: input.context,
+				request: input.request,
+				calls: modelResult.value.toolCalls,
+				createdMessages: modelResult.value.createdMessages,
+				hitlResponses: toolHitlResponses,
+				usage: modelResult.value.usage,
+				turn: modelResult.value.turn,
+				eventSequence: toolEventSequence
+			}), toolBatchStepRetry));
+			if (toolsResult._tag === "Failure") {
+				await writeErrorSafely(writeError, toolsResult.error);
+				return {
+					_tag: "ToolBatchStepFailed",
+					turn: modelResult.value.turn,
+					error: toolsResult.error,
+					state
+				};
+			}
+			if (toolsResult.value.awaitingInput === void 0) {
+				completedToolsResult = toolsResult.value;
+				break;
+			}
+			const awaitingInput = toolsResult.value.awaitingInput;
+			toolEventSequence = awaitingInput.eventSequence ?? toolsResult.value.eventSequence ?? toolEventSequence;
+			const hitlResponse = await settleWorkflowStep(retryWorkflowStep(() => {
+				if (awaitInput === void 0) return Promise.reject(missingAwaitInputHandlerError());
+				return awaitInput(awaitingInput);
+			}, awaitInputRetry));
+			if (hitlResponse._tag === "Failure") {
+				await writeErrorSafely(writeError, hitlResponse.error);
+				return {
+					_tag: "AwaitInputFailed",
+					turn: modelResult.value.turn,
+					error: hitlResponse.error,
+					awaitingInput,
+					state
+				};
+			}
+			toolHitlResponses = [...toolHitlResponses, hitlResponse.value];
+		}
+		if (completedToolsResult === void 0) {
+			const error = /* @__PURE__ */ new Error("Vercel agent workflow tool batch did not complete");
+			await writeErrorSafely(writeError, error);
+			return {
+				_tag: "ToolBatchStepFailed",
+				turn: modelResult.value.turn,
+				error,
+				state
+			};
+		}
+		state = {
+			request: input.request,
+			messages: [...modelResult.value.messages, ...completedToolsResult.messages],
+			createdMessages: completedToolsResult.createdMessages,
+			usage: modelResult.value.usage,
+			turn: modelResult.value.turn + 1,
+			eventSequence: completedToolsResult.eventSequence ?? toolEventSequence
+		};
+	}
+	const error = workflowMaxTurnsError(maxTurns);
+	await writeErrorSafely(writeError, error);
+	return {
+		_tag: "MaxTurnsExceeded",
+		maxTurns,
+		error,
+		state
+	};
+}
+//#endregion
+export { defaultMaxWorkflowTurns, noWorkflowStepRetry, retryWorkflowStep, runVercelAgentWorkflow, settleWorkflowStep };
+
+//# sourceMappingURL=workflow-loop.mjs.map

package/dist/workflow-loop.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-loop.mjs","names":[],"sources":["../src/workflow-loop.ts"],"sourcesContent":["export type VercelAgentWorkflowInput = {\n  readonly request: unknown\n  readonly context: unknown\n}\n\nexport type SerializableWorkflowState = {\n  readonly request: unknown\n  readonly messages?: ReadonlyArray<unknown>\n  readonly createdMessages: ReadonlyArray<unknown>\n  readonly usage?: unknown\n  readonly turn: number\n  readonly eventSequence?: number\n}\n\nexport type VercelAgentWorkflowModelStepInput = {\n  readonly context: unknown\n  readonly state: SerializableWorkflowState\n}\n\nexport type VercelAgentWorkflowModelStepResult = {\n  readonly done: boolean\n  readonly messages: ReadonlyArray<unknown>\n  readonly createdMessages: ReadonlyArray<unknown>\n  readonly toolCalls: ReadonlyArray<unknown>\n  readonly usage: unknown\n  readonly turn: number\n  readonly eventSequence?: number\n}\n\nexport type VercelAgentWorkflowToolBatchStepInput = {\n  readonly context: unknown\n  readonly request: unknown\n  readonly calls: ReadonlyArray<unknown>\n  readonly createdMessages: ReadonlyArray<unknown>\n  readonly hitlResponses?: ReadonlyArray<unknown>\n  readonly usage?: unknown\n  readonly turn?: number\n  readonly eventSequence?: number\n}\n\nexport type VercelAgentWorkflowAwaitingInput = {\n  readonly hookToken: string\n  readonly requests: ReadonlyArray<unknown>\n  readonly messages: ReadonlyArray<unknown>\n  readonly usage: unknown\n  readonly turns: number\n  readonly eventSequence?: number\n}\n\nexport type VercelAgentWorkflowToolBatchStepResult = {\n  readonly messages: ReadonlyArray<unknown>\n  readonly createdMessages: ReadonlyArray<unknown>\n  readonly awaitingInput?: VercelAgentWorkflowAwaitingInput\n  readonly eventSequence?: number\n}\n\nexport type WorkflowStepResult<A> =\n  | {\n      readonly _tag: 'Success'\n      readonly value: A\n    }\n  | {\n      readonly _tag: 'Failure'\n      readonly error: unknown\n    }\n\nexport type VercelAgentWorkflowStepRetryPolicy = {\n  readonly maxAttempts: number\n}\n\nexport type VercelAgentWorkflowRunResult =\n  | {\n      readonly _tag: 'Completed'\n      readonly turns: number\n      readonly state: SerializableWorkflowState\n    }\n  | {\n      readonly _tag: 'ModelStepFailed'\n      readonly turn: number\n      readonly error: unknown\n      readonly state: SerializableWorkflowState\n    }\n  | {\n      readonly _tag: 'ToolBatchStepFailed'\n      readonly turn: number\n      readonly error: unknown\n      readonly state: SerializableWorkflowState\n    }\n  | {\n      readonly _tag: 'AwaitInputFailed'\n      readonly turn: number\n      readonly error: unknown\n      readonly awaitingInput: VercelAgentWorkflowAwaitingInput\n      readonly state: SerializableWorkflowState\n    }\n  | {\n      readonly _tag: 'CloseStreamFailed'\n      readonly turns: number\n      readonly error: unknown\n      readonly state: SerializableWorkflowState\n    }\n  | {\n      readonly _tag: 'MaxTurnsExceeded'\n      readonly maxTurns: number\n      readonly error: Error\n      readonly state: SerializableWorkflowState\n    }\n\nexport type VercelAgentWorkflowLoopConfig = {\n  readonly input: VercelAgentWorkflowInput\n  readonly maxTurns?: number\n  readonly runModelStep: (\n    input: VercelAgentWorkflowModelStepInput\n  ) => Promise<VercelAgentWorkflowModelStepResult>\n  readonly runToolBatchStep: (\n    input: VercelAgentWorkflowToolBatchStepInput\n  ) => Promise<VercelAgentWorkflowToolBatchStepResult>\n  readonly closeStream: () => Promise<void>\n  readonly writeError: (error: unknown) => Promise<void>\n  readonly awaitInput?: (input: VercelAgentWorkflowAwaitingInput) => Promise<unknown>\n  readonly modelStepRetry?: VercelAgentWorkflowStepRetryPolicy\n  readonly toolBatchStepRetry?: VercelAgentWorkflowStepRetryPolicy\n  readonly awaitInputRetry?: VercelAgentWorkflowStepRetryPolicy\n  readonly closeStreamRetry?: VercelAgentWorkflowStepRetryPolicy\n}\n\nexport const defaultMaxWorkflowTurns = 500\nexport const noWorkflowStepRetry: VercelAgentWorkflowStepRetryPolicy = { maxAttempts: 1 }\n\nexport const settleWorkflowStep = <A>(promise: Promise<A>): Promise<WorkflowStepResult<A>> =>\n  promise.then(\n    value => ({ _tag: 'Success', value }),\n    error => ({ _tag: 'Failure', error })\n  )\n\nconst workflowMaxTurnsError = (maxTurns: number) =>\n  new Error(`Vercel agent workflow exceeded max turns: ${maxTurns}`)\n\nconst writeErrorSafely = (writeError: (error: unknown) => Promise<void>, error: unknown) =>\n  writeError(error).catch(() => undefined)\n\nconst missingAwaitInputHandlerError = () =>\n  new Error('Vercel agent workflow awaiting input requested but no awaitInput handler is configured')\n\nconst maxRetryAttempts = (policy: VercelAgentWorkflowStepRetryPolicy | undefined) =>\n  Math.max(1, Math.floor(policy?.maxAttempts ?? noWorkflowStepRetry.maxAttempts))\n\nexport async function retryWorkflowStep<A>(\n  runStep: () => Promise<A>,\n  policy?: VercelAgentWorkflowStepRetryPolicy\n): Promise<A> {\n  const maxAttempts = maxRetryAttempts(policy)\n  let attempt = 1\n\n  for (;;) {\n    try {\n      return await runStep()\n    } catch (error) {\n      if (attempt >= maxAttempts) {\n        throw error\n      }\n\n      attempt += 1\n    }\n  }\n}\n\nexport async function runVercelAgentWorkflow(\n  config: VercelAgentWorkflowLoopConfig\n): Promise<VercelAgentWorkflowRunResult> {\n  const {\n    input,\n    maxTurns: configuredMaxTurns,\n    runModelStep,\n    runToolBatchStep,\n    closeStream,\n    writeError,\n    awaitInput,\n    modelStepRetry,\n    toolBatchStepRetry,\n    awaitInputRetry,\n    closeStreamRetry\n  } = config\n  let state: SerializableWorkflowState = {\n    request: input.request,\n    createdMessages: [],\n    turn: 1,\n    eventSequence: 0\n  }\n  const maxTurns = configuredMaxTurns ?? defaultMaxWorkflowTurns\n\n  for (let step = 0; step < maxTurns; step++) {\n    const modelResult = await settleWorkflowStep(\n      retryWorkflowStep(\n        () => runModelStep({ context: input.context, state }),\n        modelStepRetry\n      )\n    )\n\n    if (modelResult._tag === 'Failure') {\n      await writeErrorSafely(writeError, modelResult.error)\n      return {\n        _tag: 'ModelStepFailed',\n        turn: state.turn,\n        error: modelResult.error,\n        state\n      }\n    }\n\n    if (modelResult.value.done) {\n      const closeResult = await settleWorkflowStep(\n        retryWorkflowStep(closeStream, closeStreamRetry)\n      )\n\n      if (closeResult._tag === 'Failure') {\n        await writeErrorSafely(writeError, closeResult.error)\n\n        return {\n          _tag: 'CloseStreamFailed',\n          turns: modelResult.value.turn,\n          error: closeResult.error,\n          state\n        }\n      }\n\n      return {\n        _tag: 'Completed',\n        turns: modelResult.value.turn,\n        state\n      }\n    }\n\n    let completedToolsResult: VercelAgentWorkflowToolBatchStepResult | undefined\n    let toolHitlResponses: ReadonlyArray<unknown> = []\n    let toolEventSequence = modelResult.value.eventSequence ?? state.eventSequence\n\n    for (;;) {\n      const toolsResult = await settleWorkflowStep(\n        retryWorkflowStep(\n          () =>\n            runToolBatchStep({\n              context: input.context,\n              request: input.request,\n              calls: modelResult.value.toolCalls,\n              createdMessages: modelResult.value.createdMessages,\n              hitlResponses: toolHitlResponses,\n              usage: modelResult.value.usage,\n              turn: modelResult.value.turn,\n              eventSequence: toolEventSequence\n            }),\n          toolBatchStepRetry\n        )\n      )\n\n      if (toolsResult._tag === 'Failure') {\n        await writeErrorSafely(writeError, toolsResult.error)\n\n        return {\n          _tag: 'ToolBatchStepFailed',\n          turn: modelResult.value.turn,\n          error: toolsResult.error,\n          state\n        }\n      }\n\n      if (toolsResult.value.awaitingInput === undefined) {\n        completedToolsResult = toolsResult.value\n        break\n      }\n\n      const awaitingInput = toolsResult.value.awaitingInput\n      toolEventSequence = awaitingInput.eventSequence ?? toolsResult.value.eventSequence ?? toolEventSequence\n\n      const hitlResponse = await settleWorkflowStep(\n        retryWorkflowStep(\n          () => {\n            if (awaitInput === undefined) {\n              return Promise.reject(missingAwaitInputHandlerError())\n            }\n\n            return awaitInput(awaitingInput)\n          },\n          awaitInputRetry\n        )\n      )\n\n      if (hitlResponse._tag === 'Failure') {\n        await writeErrorSafely(writeError, hitlResponse.error)\n\n        return {\n          _tag: 'AwaitInputFailed',\n          turn: modelResult.value.turn,\n          error: hitlResponse.error,\n          awaitingInput,\n          state\n        }\n      }\n\n      toolHitlResponses = [...toolHitlResponses, hitlResponse.value]\n    }\n\n    if (completedToolsResult === undefined) {\n      const error = new Error('Vercel agent workflow tool batch did not complete')\n      await writeErrorSafely(writeError, error)\n\n      return {\n        _tag: 'ToolBatchStepFailed',\n        turn: modelResult.value.turn,\n        error,\n        state\n      }\n    }\n\n    state = {\n      request: input.request,\n      messages: [...modelResult.value.messages, ...completedToolsResult.messages],\n      createdMessages: completedToolsResult.createdMessages,\n      usage: modelResult.value.usage,\n      turn: modelResult.value.turn + 1,\n      eventSequence: completedToolsResult.eventSequence ?? toolEventSequence\n    }\n  }\n\n  const error = workflowMaxTurnsError(maxTurns)\n  await writeErrorSafely(writeError, error)\n\n  return {\n    _tag: 'MaxTurnsExceeded',\n    maxTurns,\n    error,\n    state\n  }\n}\n"],"mappings":"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"}

package/dist/workflow.d.mts

@@ -0,0 +1,2 @@
+import { SerializableWorkflowState, VercelAgentWorkflowAwaitingInput, VercelAgentWorkflowInput, VercelAgentWorkflowLoopConfig, VercelAgentWorkflowModelStepInput, VercelAgentWorkflowModelStepResult, VercelAgentWorkflowRunResult, VercelAgentWorkflowStepRetryPolicy, VercelAgentWorkflowToolBatchStepInput, VercelAgentWorkflowToolBatchStepResult, WorkflowStepResult, defaultMaxWorkflowTurns, noWorkflowStepRetry, retryWorkflowStep, runVercelAgentWorkflow, settleWorkflowStep } from "./workflow-loop.mjs";
+export { type SerializableWorkflowState, type VercelAgentWorkflowAwaitingInput, type VercelAgentWorkflowInput, type VercelAgentWorkflowLoopConfig, type VercelAgentWorkflowModelStepInput, type VercelAgentWorkflowModelStepResult, type VercelAgentWorkflowRunResult, type VercelAgentWorkflowStepRetryPolicy, type VercelAgentWorkflowToolBatchStepInput, type VercelAgentWorkflowToolBatchStepResult, type WorkflowStepResult, defaultMaxWorkflowTurns, noWorkflowStepRetry, retryWorkflowStep, runVercelAgentWorkflow, settleWorkflowStep };

package/dist/workflow.mjs

@@ -0,0 +1,2 @@
+import { defaultMaxWorkflowTurns, noWorkflowStepRetry, retryWorkflowStep, runVercelAgentWorkflow, settleWorkflowStep } from "./workflow-loop.mjs";
+export { defaultMaxWorkflowTurns, noWorkflowStepRetry, retryWorkflowStep, runVercelAgentWorkflow, settleWorkflowStep };

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@yolk-sdk/vercel-workflows",
+  "version": "0.1.0-canary.15",
+  "description": "Vercel Workflow orchestration primitives for Yolk agent loops.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/magoz/yolk-sdk.git",
+    "directory": "packages/vercel-workflows"
+  },
+  "bugs": {
+    "url": "https://github.com/magoz/yolk-sdk/issues"
+  },
+  "homepage": "https://github.com/magoz/yolk-sdk#readme",
+  "keywords": [
+    "vercel",
+    "workflow",
+    "agents",
+    "runtime",
+    "effect"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    },
+    "./workflow": {
+      "types": "./dist/workflow.d.mts",
+      "import": "./dist/workflow.mjs",
+      "default": "./dist/workflow.mjs"
+    }
+  },
+  "files": [
+    "src/**/*.ts",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "dist/**/*",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "effect": "4.0.0-beta.65",
+    "workflow": "^4.2.4"
+  },
+  "devDependencies": {
+    "@effect/vitest": "4.0.0-beta.65",
+    "@workflow/vitest": "^4.0.5",
+    "vitest": "^4.0.17"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "check": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "test:workflow": "vitest run --config vitest.workflow.config.ts",
+    "test:run": "vitest run --passWithNoTests"
+  }
+}

package/src/index.ts

@@ -0,0 +1,20 @@
+export {
+  defaultMaxWorkflowTurns,
+  noWorkflowStepRetry,
+  retryWorkflowStep,
+  runVercelAgentWorkflow,
+  settleWorkflowStep
+} from './workflow.ts'
+export type {
+  SerializableWorkflowState,
+  VercelAgentWorkflowAwaitingInput,
+  VercelAgentWorkflowInput,
+  VercelAgentWorkflowLoopConfig,
+  VercelAgentWorkflowModelStepInput,
+  VercelAgentWorkflowModelStepResult,
+  VercelAgentWorkflowRunResult,
+  VercelAgentWorkflowStepRetryPolicy,
+  VercelAgentWorkflowToolBatchStepInput,
+  VercelAgentWorkflowToolBatchStepResult,
+  WorkflowStepResult
+} from './workflow.ts'

package/src/workflow-loop.ts

@@ -0,0 +1,333 @@
+export type VercelAgentWorkflowInput = {
+  readonly request: unknown
+  readonly context: unknown
+}
+
+export type SerializableWorkflowState = {
+  readonly request: unknown
+  readonly messages?: ReadonlyArray<unknown>
+  readonly createdMessages: ReadonlyArray<unknown>
+  readonly usage?: unknown
+  readonly turn: number
+  readonly eventSequence?: number
+}
+
+export type VercelAgentWorkflowModelStepInput = {
+  readonly context: unknown
+  readonly state: SerializableWorkflowState
+}
+
+export type VercelAgentWorkflowModelStepResult = {
+  readonly done: boolean
+  readonly messages: ReadonlyArray<unknown>
+  readonly createdMessages: ReadonlyArray<unknown>
+  readonly toolCalls: ReadonlyArray<unknown>
+  readonly usage: unknown
+  readonly turn: number
+  readonly eventSequence?: number
+}
+
+export type VercelAgentWorkflowToolBatchStepInput = {
+  readonly context: unknown
+  readonly request: unknown
+  readonly calls: ReadonlyArray<unknown>
+  readonly createdMessages: ReadonlyArray<unknown>
+  readonly hitlResponses?: ReadonlyArray<unknown>
+  readonly usage?: unknown
+  readonly turn?: number
+  readonly eventSequence?: number
+}
+
+export type VercelAgentWorkflowAwaitingInput = {
+  readonly hookToken: string
+  readonly requests: ReadonlyArray<unknown>
+  readonly messages: ReadonlyArray<unknown>
+  readonly usage: unknown
+  readonly turns: number
+  readonly eventSequence?: number
+}
+
+export type VercelAgentWorkflowToolBatchStepResult = {
+  readonly messages: ReadonlyArray<unknown>
+  readonly createdMessages: ReadonlyArray<unknown>
+  readonly awaitingInput?: VercelAgentWorkflowAwaitingInput
+  readonly eventSequence?: number
+}
+
+export type WorkflowStepResult<A> =
+  | {
+      readonly _tag: 'Success'
+      readonly value: A
+    }
+  | {
+      readonly _tag: 'Failure'
+      readonly error: unknown
+    }
+
+export type VercelAgentWorkflowStepRetryPolicy = {
+  readonly maxAttempts: number
+}
+
+export type VercelAgentWorkflowRunResult =
+  | {
+      readonly _tag: 'Completed'
+      readonly turns: number
+      readonly state: SerializableWorkflowState
+    }
+  | {
+      readonly _tag: 'ModelStepFailed'
+      readonly turn: number
+      readonly error: unknown
+      readonly state: SerializableWorkflowState
+    }
+  | {
+      readonly _tag: 'ToolBatchStepFailed'
+      readonly turn: number
+      readonly error: unknown
+      readonly state: SerializableWorkflowState
+    }
+  | {
+      readonly _tag: 'AwaitInputFailed'
+      readonly turn: number
+      readonly error: unknown
+      readonly awaitingInput: VercelAgentWorkflowAwaitingInput
+      readonly state: SerializableWorkflowState
+    }
+  | {
+      readonly _tag: 'CloseStreamFailed'
+      readonly turns: number
+      readonly error: unknown
+      readonly state: SerializableWorkflowState
+    }
+  | {
+      readonly _tag: 'MaxTurnsExceeded'
+      readonly maxTurns: number
+      readonly error: Error
+      readonly state: SerializableWorkflowState
+    }
+
+export type VercelAgentWorkflowLoopConfig = {
+  readonly input: VercelAgentWorkflowInput
+  readonly maxTurns?: number
+  readonly runModelStep: (
+    input: VercelAgentWorkflowModelStepInput
+  ) => Promise<VercelAgentWorkflowModelStepResult>
+  readonly runToolBatchStep: (
+    input: VercelAgentWorkflowToolBatchStepInput
+  ) => Promise<VercelAgentWorkflowToolBatchStepResult>
+  readonly closeStream: () => Promise<void>
+  readonly writeError: (error: unknown) => Promise<void>
+  readonly awaitInput?: (input: VercelAgentWorkflowAwaitingInput) => Promise<unknown>
+  readonly modelStepRetry?: VercelAgentWorkflowStepRetryPolicy
+  readonly toolBatchStepRetry?: VercelAgentWorkflowStepRetryPolicy
+  readonly awaitInputRetry?: VercelAgentWorkflowStepRetryPolicy
+  readonly closeStreamRetry?: VercelAgentWorkflowStepRetryPolicy
+}
+
+export const defaultMaxWorkflowTurns = 500
+export const noWorkflowStepRetry: VercelAgentWorkflowStepRetryPolicy = { maxAttempts: 1 }
+
+export const settleWorkflowStep = <A>(promise: Promise<A>): Promise<WorkflowStepResult<A>> =>
+  promise.then(
+    value => ({ _tag: 'Success', value }),
+    error => ({ _tag: 'Failure', error })
+  )
+
+const workflowMaxTurnsError = (maxTurns: number) =>
+  new Error(`Vercel agent workflow exceeded max turns: ${maxTurns}`)
+
+const writeErrorSafely = (writeError: (error: unknown) => Promise<void>, error: unknown) =>
+  writeError(error).catch(() => undefined)
+
+const missingAwaitInputHandlerError = () =>
+  new Error('Vercel agent workflow awaiting input requested but no awaitInput handler is configured')
+
+const maxRetryAttempts = (policy: VercelAgentWorkflowStepRetryPolicy | undefined) =>
+  Math.max(1, Math.floor(policy?.maxAttempts ?? noWorkflowStepRetry.maxAttempts))
+
+export async function retryWorkflowStep<A>(
+  runStep: () => Promise<A>,
+  policy?: VercelAgentWorkflowStepRetryPolicy
+): Promise<A> {
+  const maxAttempts = maxRetryAttempts(policy)
+  let attempt = 1
+
+  for (;;) {
+    try {
+      return await runStep()
+    } catch (error) {
+      if (attempt >= maxAttempts) {
+        throw error
+      }
+
+      attempt += 1
+    }
+  }
+}
+
+export async function runVercelAgentWorkflow(
+  config: VercelAgentWorkflowLoopConfig
+): Promise<VercelAgentWorkflowRunResult> {
+  const {
+    input,
+    maxTurns: configuredMaxTurns,
+    runModelStep,
+    runToolBatchStep,
+    closeStream,
+    writeError,
+    awaitInput,
+    modelStepRetry,
+    toolBatchStepRetry,
+    awaitInputRetry,
+    closeStreamRetry
+  } = config
+  let state: SerializableWorkflowState = {
+    request: input.request,
+    createdMessages: [],
+    turn: 1,
+    eventSequence: 0
+  }
+  const maxTurns = configuredMaxTurns ?? defaultMaxWorkflowTurns
+
+  for (let step = 0; step < maxTurns; step++) {
+    const modelResult = await settleWorkflowStep(
+      retryWorkflowStep(
+        () => runModelStep({ context: input.context, state }),
+        modelStepRetry
+      )
+    )
+
+    if (modelResult._tag === 'Failure') {
+      await writeErrorSafely(writeError, modelResult.error)
+      return {
+        _tag: 'ModelStepFailed',
+        turn: state.turn,
+        error: modelResult.error,
+        state
+      }
+    }
+
+    if (modelResult.value.done) {
+      const closeResult = await settleWorkflowStep(
+        retryWorkflowStep(closeStream, closeStreamRetry)
+      )
+
+      if (closeResult._tag === 'Failure') {
+        await writeErrorSafely(writeError, closeResult.error)
+
+        return {
+          _tag: 'CloseStreamFailed',
+          turns: modelResult.value.turn,
+          error: closeResult.error,
+          state
+        }
+      }
+
+      return {
+        _tag: 'Completed',
+        turns: modelResult.value.turn,
+        state
+      }
+    }
+
+    let completedToolsResult: VercelAgentWorkflowToolBatchStepResult | undefined
+    let toolHitlResponses: ReadonlyArray<unknown> = []
+    let toolEventSequence = modelResult.value.eventSequence ?? state.eventSequence
+
+    for (;;) {
+      const toolsResult = await settleWorkflowStep(
+        retryWorkflowStep(
+          () =>
+            runToolBatchStep({
+              context: input.context,
+              request: input.request,
+              calls: modelResult.value.toolCalls,
+              createdMessages: modelResult.value.createdMessages,
+              hitlResponses: toolHitlResponses,
+              usage: modelResult.value.usage,
+              turn: modelResult.value.turn,
+              eventSequence: toolEventSequence
+            }),
+          toolBatchStepRetry
+        )
+      )
+
+      if (toolsResult._tag === 'Failure') {
+        await writeErrorSafely(writeError, toolsResult.error)
+
+        return {
+          _tag: 'ToolBatchStepFailed',
+          turn: modelResult.value.turn,
+          error: toolsResult.error,
+          state
+        }
+      }
+
+      if (toolsResult.value.awaitingInput === undefined) {
+        completedToolsResult = toolsResult.value
+        break
+      }
+
+      const awaitingInput = toolsResult.value.awaitingInput
+      toolEventSequence = awaitingInput.eventSequence ?? toolsResult.value.eventSequence ?? toolEventSequence
+
+      const hitlResponse = await settleWorkflowStep(
+        retryWorkflowStep(
+          () => {
+            if (awaitInput === undefined) {
+              return Promise.reject(missingAwaitInputHandlerError())
+            }
+
+            return awaitInput(awaitingInput)
+          },
+          awaitInputRetry
+        )
+      )
+
+      if (hitlResponse._tag === 'Failure') {
+        await writeErrorSafely(writeError, hitlResponse.error)
+
+        return {
+          _tag: 'AwaitInputFailed',
+          turn: modelResult.value.turn,
+          error: hitlResponse.error,
+          awaitingInput,
+          state
+        }
+      }
+
+      toolHitlResponses = [...toolHitlResponses, hitlResponse.value]
+    }
+
+    if (completedToolsResult === undefined) {
+      const error = new Error('Vercel agent workflow tool batch did not complete')
+      await writeErrorSafely(writeError, error)
+
+      return {
+        _tag: 'ToolBatchStepFailed',
+        turn: modelResult.value.turn,
+        error,
+        state
+      }
+    }
+
+    state = {
+      request: input.request,
+      messages: [...modelResult.value.messages, ...completedToolsResult.messages],
+      createdMessages: completedToolsResult.createdMessages,
+      usage: modelResult.value.usage,
+      turn: modelResult.value.turn + 1,
+      eventSequence: completedToolsResult.eventSequence ?? toolEventSequence
+    }
+  }
+
+  const error = workflowMaxTurnsError(maxTurns)
+  await writeErrorSafely(writeError, error)
+
+  return {
+    _tag: 'MaxTurnsExceeded',
+    maxTurns,
+    error,
+    state
+  }
+}

package/src/workflow.ts

@@ -0,0 +1,20 @@
+export {
+  defaultMaxWorkflowTurns,
+  noWorkflowStepRetry,
+  retryWorkflowStep,
+  runVercelAgentWorkflow,
+  settleWorkflowStep
+} from './workflow-loop.ts'
+export type {
+  SerializableWorkflowState,
+  VercelAgentWorkflowAwaitingInput,
+  VercelAgentWorkflowInput,
+  VercelAgentWorkflowLoopConfig,
+  VercelAgentWorkflowModelStepInput,
+  VercelAgentWorkflowModelStepResult,
+  VercelAgentWorkflowRunResult,
+  VercelAgentWorkflowStepRetryPolicy,
+  VercelAgentWorkflowToolBatchStepInput,
+  VercelAgentWorkflowToolBatchStepResult,
+  WorkflowStepResult
+} from './workflow-loop.ts'