@yolk-sdk/vercel-workflows-runtime 0.0.1-canary.0

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,58 @@
+# @yolk-sdk/vercel-workflows-runtime
+
+Vercel Workflow-specific contracts for durable agent model/tool step loops.
+
+## Install
+
+```bash
+pnpm add @yolk-sdk/vercel-workflows-runtime@canary @yolk-sdk/agent@canary effect workflow
+```
+
+Canary APIs are unstable. Keep all `@yolk-sdk/*` packages on the same version.
+
+## Subpaths
+
+| Subpath | Purpose |
+| --- | --- |
+| `@yolk-sdk/vercel-workflows-runtime` | Empty root export; reserved package entry |
+| `@yolk-sdk/vercel-workflows-runtime/workflow` | Workflow-safe agent loop orchestration APIs |
+
+## Imports
+
+The root export is intentionally empty. Import Workflow APIs from `./workflow`:
+
+```ts
+import {
+  noWorkflowStepRetry,
+  runVercelAgentWorkflow
+} from '@yolk-sdk/vercel-workflows-runtime/workflow'
+```
+
+## 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 between steps
+- close step: flush/close output stream
+- terminal status: completed, step failure, close failure, or max turns exceeded
+
+Continuation state stays plain serializable data for Workflow persistence.
+
+## 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 @@
+export { };

package/dist/index.mjs

@@ -0,0 +1 @@
+export {};

package/dist/workflow-loop.d.mts

@@ -0,0 +1,104 @@
+//#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: '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 modelStepRetry?: VercelAgentWorkflowStepRetryPolicy;
+  readonly toolBatchStepRetry?: 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":";KAAY,wBAAA;EAAA,SACD,OAAA;EAAA,SACA,OAAO;AAAA;AAAA,KAGN,yBAAA;EAAA,SACD,OAAA;EAAA,SACA,QAAA,GAAW,aAAA;EAAA,SACX,eAAA,EAAiB,aAAa;EAAA,SAC9B,KAAA;EAAA,SACA,IAAA;EAAA,SACA,aAAA;AAAA;AAAA,KAGC,iCAAA;EAAA,SACD,OAAA;EAAA,SACA,KAAA,EAAO,yBAAyB;AAAA;AAAA,KAG/B,kCAAA;EAAA,SACD,IAAA;EAAA,SACA,QAAA,EAAU,aAAA;EAAA,SACV,eAAA,EAAiB,aAAA;EAAA,SACjB,SAAA,EAAW,aAAA;EAAA,SACX,KAAA;EAAA,SACA,IAAA;EAAA,SACA,aAAA;AAAA;AAAA,KAGC,qCAAA;EAAA,SACD,OAAA;EAAA,SACA,OAAA;EAAA,SACA,KAAA,EAAO,aAAA;EAAA,SACP,eAAA,EAAiB,aAAA;EAAA,SACjB,aAAA,GAAgB,aAAA;EAAA,SAChB,KAAA;EAAA,SACA,IAAA;EAAA,SACA,aAAA;AAAA;AAAA,KAGC,gCAAA;EAAA,SACD,SAAA;EAAA,SACA,QAAA,EAAU,aAAA;EAAA,SACV,QAAA,EAAU,aAAa;EAAA,SACvB,KAAA;EAAA,SACA,KAAA;EAAA,SACA,aAAA;AAAA;AAAA,KAGC,sCAAA;EAAA,SACD,QAAA,EAAU,aAAA;EAAA,SACV,eAAA,EAAiB,aAAA;EAAA,SACjB,aAAA,GAAgB,gCAAA;EAAA,SAChB,aAAA;AAAA;AAAA,KAGC,kBAAA;EAAA,SAEG,IAAA;EAAA,SACA,KAAA,EAAO,CAAC;AAAA;EAAA,SAGR,IAAA;EAAA,SACA,KAAA;AAAA;AAAA,KAGH,kCAAA;EAAA,SACD,WAAW;AAAA;AAAA,KAGV,4BAAA;EAAA,SAEG,IAAA;EAAA,SACA,KAAA;EAAA,SACA,KAAA,EAAO,yBAAA;AAAA;EAAA,SAGP,IAAA;EAAA,SACA,IAAA;EAAA,SACA,KAAA;EAAA,SACA,KAAA,EAAO,yBAAA;AAAA;EAAA,SAGP,IAAA;EAAA,SACA,IAAA;EAAA,SACA,KAAA;EAAA,SACA,KAAA,EAAO,yBAAA;AAAA;EAAA,SAGP,IAAA;EAAA,SACA,KAAA;EAAA,SACA,KAAA;EAAA,SACA,KAAA,EAAO,yBAAA;AAAA;EAAA,SAGP,IAAA;EAAA,SACA,QAAA;EAAA,SACA,KAAA,EAAO,KAAA;EAAA,SACP,KAAA,EAAO,yBAAA;AAAA;AAAA,KAGV,6BAAA;EAAA,SACD,KAAA,EAAO,wBAAA;EAAA,SACP,QAAA;EAAA,SACA,YAAA,GACP,KAAA,EAAO,iCAAA,KACJ,OAAA,CAAQ,kCAAA;EAAA,SACJ,gBAAA,GACP,KAAA,EAAO,qCAAA,KACJ,OAAA,CAAQ,sCAAA;EAAA,SACJ,WAAA,QAAmB,OAAA;EAAA,SACnB,UAAA,GAAa,KAAA,cAAmB,OAAA;EAAA,SAChC,cAAA,GAAiB,kCAAA;EAAA,SACjB,kBAAA,GAAqB,kCAAA;EAAA,SACrB,gBAAA,GAAmB,kCAAA;AAAA;AAAA,cAGjB,uBAAA;AAAA,cACA,mBAAA,EAAqB,kCAAuD;AAAA,cAE5E,kBAAA,MAAyB,OAAA,EAAS,OAAA,CAAQ,CAAA,MAAK,OAAA,CAAQ,kBAAA,CAAmB,CAAA;AAAA,iBAejE,iBAAA,GAAA,CACpB,OAAA,QAAe,OAAA,CAAQ,CAAA,GACvB,MAAA,GAAS,kCAAA,GACR,OAAA,CAAQ,CAAA;AAAA,iBAiBW,sBAAA,CACpB,MAAA,EAAQ,6BAAA,GACP,OAAA,CAAQ,4BAAA"}

package/dist/workflow-loop.mjs

@@ -0,0 +1,101 @@
+//#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 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) {
+	let state = {
+		request: config.input.request,
+		createdMessages: [],
+		turn: 1,
+		eventSequence: 0
+	};
+	const maxTurns = config.maxTurns ?? 500;
+	for (let step = 0; step < maxTurns; step++) {
+		const modelResult = await settleWorkflowStep(retryWorkflowStep(() => config.runModelStep({
+			context: config.input.context,
+			state
+		}), config.modelStepRetry));
+		if (modelResult._tag === "Failure") {
+			await writeErrorSafely(config.writeError, modelResult.error);
+			return {
+				_tag: "ModelStepFailed",
+				turn: state.turn,
+				error: modelResult.error,
+				state
+			};
+		}
+		if (modelResult.value.done) {
+			const closeResult = await settleWorkflowStep(retryWorkflowStep(config.closeStream, config.closeStreamRetry));
+			if (closeResult._tag === "Failure") {
+				await writeErrorSafely(config.writeError, closeResult.error);
+				return {
+					_tag: "CloseStreamFailed",
+					turns: modelResult.value.turn,
+					error: closeResult.error,
+					state
+				};
+			}
+			return {
+				_tag: "Completed",
+				turns: modelResult.value.turn,
+				state
+			};
+		}
+		const toolsResult = await settleWorkflowStep(retryWorkflowStep(() => config.runToolBatchStep({
+			context: config.input.context,
+			request: config.input.request,
+			calls: modelResult.value.toolCalls,
+			createdMessages: modelResult.value.createdMessages,
+			turn: modelResult.value.turn,
+			eventSequence: modelResult.value.eventSequence ?? state.eventSequence
+		}), config.toolBatchStepRetry));
+		if (toolsResult._tag === "Failure") {
+			await writeErrorSafely(config.writeError, toolsResult.error);
+			return {
+				_tag: "ToolBatchStepFailed",
+				turn: modelResult.value.turn,
+				error: toolsResult.error,
+				state
+			};
+		}
+		state = {
+			request: config.input.request,
+			messages: [...modelResult.value.messages, ...toolsResult.value.messages],
+			createdMessages: toolsResult.value.createdMessages,
+			usage: modelResult.value.usage,
+			turn: modelResult.value.turn + 1,
+			eventSequence: toolsResult.value.eventSequence ?? modelResult.value.eventSequence ?? state.eventSequence
+		};
+	}
+	const error = workflowMaxTurnsError(maxTurns);
+	await writeErrorSafely(config.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: '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 modelStepRetry?: VercelAgentWorkflowStepRetryPolicy\n  readonly toolBatchStepRetry?: 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 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  let state: SerializableWorkflowState = {\n    request: config.input.request,\n    createdMessages: [],\n    turn: 1,\n    eventSequence: 0\n  }\n  const maxTurns = config.maxTurns ?? defaultMaxWorkflowTurns\n\n  for (let step = 0; step < maxTurns; step++) {\n    const modelResult = await settleWorkflowStep(\n      retryWorkflowStep(\n        () => config.runModelStep({ context: config.input.context, state }),\n        config.modelStepRetry\n      )\n    )\n\n    if (modelResult._tag === 'Failure') {\n      await writeErrorSafely(config.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(config.closeStream, config.closeStreamRetry)\n      )\n\n      if (closeResult._tag === 'Failure') {\n        await writeErrorSafely(config.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    const toolsResult = await settleWorkflowStep(\n      retryWorkflowStep(\n        () =>\n          config.runToolBatchStep({\n            context: config.input.context,\n            request: config.input.request,\n            calls: modelResult.value.toolCalls,\n            createdMessages: modelResult.value.createdMessages,\n            turn: modelResult.value.turn,\n            eventSequence: modelResult.value.eventSequence ?? state.eventSequence\n          }),\n        config.toolBatchStepRetry\n      )\n    )\n\n    if (toolsResult._tag === 'Failure') {\n      await writeErrorSafely(config.writeError, toolsResult.error)\n      return {\n        _tag: 'ToolBatchStepFailed',\n        turn: modelResult.value.turn,\n        error: toolsResult.error,\n        state\n      }\n    }\n\n    state = {\n      request: config.input.request,\n      messages: [...modelResult.value.messages, ...toolsResult.value.messages],\n      createdMessages: toolsResult.value.createdMessages,\n      usage: modelResult.value.usage,\n      turn: modelResult.value.turn + 1,\n      eventSequence: toolsResult.value.eventSequence ?? modelResult.value.eventSequence ?? state.eventSequence\n    }\n  }\n\n  const error = workflowMaxTurnsError(maxTurns)\n  await writeErrorSafely(config.writeError, error)\n\n  return {\n    _tag: 'MaxTurnsExceeded',\n    maxTurns,\n    error,\n    state\n  }\n}\n"],"mappings":";AAqHA,MAAa,0BAA0B;AACvC,MAAa,sBAA0D,EAAE,aAAa,EAAE;AAExF,MAAa,sBAAyB,YACpC,QAAQ,MACN,WAAU;CAAE,MAAM;CAAW;AAAM,KACnC,WAAU;CAAE,MAAM;CAAW;AAAM,EACrC;AAEF,MAAM,yBAAyB,6BAC7B,IAAI,MAAM,6CAA6C,UAAU;AAEnE,MAAM,oBAAoB,YAA+C,UACvE,WAAW,KAAK,EAAE,YAAY,KAAA,CAAS;AAEzC,MAAM,oBAAoB,WACxB,KAAK,IAAI,GAAG,KAAK,MAAM,QAAQ,eAAe,oBAAoB,WAAW,CAAC;AAEhF,eAAsB,kBACpB,SACA,QACY;CACZ,MAAM,cAAc,iBAAiB,MAAM;CAC3C,IAAI,UAAU;CAEd,SACE,IAAI;EACF,OAAO,MAAM,QAAQ;CACvB,SAAS,OAAO;EACd,IAAI,WAAW,aACb,MAAM;EAGR,WAAW;CACb;AAEJ;AAEA,eAAsB,uBACpB,QACuC;CACvC,IAAI,QAAmC;EACrC,SAAS,OAAO,MAAM;EACtB,iBAAiB,CAAC;EAClB,MAAM;EACN,eAAe;CACjB;CACA,MAAM,WAAW,OAAO,YAAA;CAExB,KAAK,IAAI,OAAO,GAAG,OAAO,UAAU,QAAQ;EAC1C,MAAM,cAAc,MAAM,mBACxB,wBACQ,OAAO,aAAa;GAAE,SAAS,OAAO,MAAM;GAAS;EAAM,CAAC,GAClE,OAAO,cACT,CACF;EAEA,IAAI,YAAY,SAAS,WAAW;GAClC,MAAM,iBAAiB,OAAO,YAAY,YAAY,KAAK;GAC3D,OAAO;IACL,MAAM;IACN,MAAM,MAAM;IACZ,OAAO,YAAY;IACnB;GACF;EACF;EAEA,IAAI,YAAY,MAAM,MAAM;GAC1B,MAAM,cAAc,MAAM,mBACxB,kBAAkB,OAAO,aAAa,OAAO,gBAAgB,CAC/D;GAEA,IAAI,YAAY,SAAS,WAAW;IAClC,MAAM,iBAAiB,OAAO,YAAY,YAAY,KAAK;IAE3D,OAAO;KACL,MAAM;KACN,OAAO,YAAY,MAAM;KACzB,OAAO,YAAY;KACnB;IACF;GACF;GAEA,OAAO;IACL,MAAM;IACN,OAAO,YAAY,MAAM;IACzB;GACF;EACF;EAEA,MAAM,cAAc,MAAM,mBACxB,wBAEI,OAAO,iBAAiB;GACtB,SAAS,OAAO,MAAM;GACtB,SAAS,OAAO,MAAM;GACtB,OAAO,YAAY,MAAM;GACzB,iBAAiB,YAAY,MAAM;GACnC,MAAM,YAAY,MAAM;GACxB,eAAe,YAAY,MAAM,iBAAiB,MAAM;EAC1D,CAAC,GACH,OAAO,kBACT,CACF;EAEA,IAAI,YAAY,SAAS,WAAW;GAClC,MAAM,iBAAiB,OAAO,YAAY,YAAY,KAAK;GAC3D,OAAO;IACL,MAAM;IACN,MAAM,YAAY,MAAM;IACxB,OAAO,YAAY;IACnB;GACF;EACF;EAEA,QAAQ;GACN,SAAS,OAAO,MAAM;GACtB,UAAU,CAAC,GAAG,YAAY,MAAM,UAAU,GAAG,YAAY,MAAM,QAAQ;GACvE,iBAAiB,YAAY,MAAM;GACnC,OAAO,YAAY,MAAM;GACzB,MAAM,YAAY,MAAM,OAAO;GAC/B,eAAe,YAAY,MAAM,iBAAiB,YAAY,MAAM,iBAAiB,MAAM;EAC7F;CACF;CAEA,MAAM,QAAQ,sBAAsB,QAAQ;CAC5C,MAAM,iBAAiB,OAAO,YAAY,KAAK;CAE/C,OAAO;EACL,MAAM;EACN;EACA;EACA;CACF;AACF"}

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-runtime",
+  "version": "0.0.1-canary.0",
+  "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-runtime"
+  },
+  "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 @@
+export {}

package/src/workflow-loop.ts

@@ -0,0 +1,252 @@
+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: '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 modelStepRetry?: VercelAgentWorkflowStepRetryPolicy
+  readonly toolBatchStepRetry?: 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 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> {
+  let state: SerializableWorkflowState = {
+    request: config.input.request,
+    createdMessages: [],
+    turn: 1,
+    eventSequence: 0
+  }
+  const maxTurns = config.maxTurns ?? defaultMaxWorkflowTurns
+
+  for (let step = 0; step < maxTurns; step++) {
+    const modelResult = await settleWorkflowStep(
+      retryWorkflowStep(
+        () => config.runModelStep({ context: config.input.context, state }),
+        config.modelStepRetry
+      )
+    )
+
+    if (modelResult._tag === 'Failure') {
+      await writeErrorSafely(config.writeError, modelResult.error)
+      return {
+        _tag: 'ModelStepFailed',
+        turn: state.turn,
+        error: modelResult.error,
+        state
+      }
+    }
+
+    if (modelResult.value.done) {
+      const closeResult = await settleWorkflowStep(
+        retryWorkflowStep(config.closeStream, config.closeStreamRetry)
+      )
+
+      if (closeResult._tag === 'Failure') {
+        await writeErrorSafely(config.writeError, closeResult.error)
+
+        return {
+          _tag: 'CloseStreamFailed',
+          turns: modelResult.value.turn,
+          error: closeResult.error,
+          state
+        }
+      }
+
+      return {
+        _tag: 'Completed',
+        turns: modelResult.value.turn,
+        state
+      }
+    }
+
+    const toolsResult = await settleWorkflowStep(
+      retryWorkflowStep(
+        () =>
+          config.runToolBatchStep({
+            context: config.input.context,
+            request: config.input.request,
+            calls: modelResult.value.toolCalls,
+            createdMessages: modelResult.value.createdMessages,
+            turn: modelResult.value.turn,
+            eventSequence: modelResult.value.eventSequence ?? state.eventSequence
+          }),
+        config.toolBatchStepRetry
+      )
+    )
+
+    if (toolsResult._tag === 'Failure') {
+      await writeErrorSafely(config.writeError, toolsResult.error)
+      return {
+        _tag: 'ToolBatchStepFailed',
+        turn: modelResult.value.turn,
+        error: toolsResult.error,
+        state
+      }
+    }
+
+    state = {
+      request: config.input.request,
+      messages: [...modelResult.value.messages, ...toolsResult.value.messages],
+      createdMessages: toolsResult.value.createdMessages,
+      usage: modelResult.value.usage,
+      turn: modelResult.value.turn + 1,
+      eventSequence: toolsResult.value.eventSequence ?? modelResult.value.eventSequence ?? state.eventSequence
+    }
+  }
+
+  const error = workflowMaxTurnsError(maxTurns)
+  await writeErrorSafely(config.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'