@yolk-sdk/vercel-workflows 0.1.0-canary.25 → 0.1.0-canary.26

package/README.md

@@ -23,8 +23,10 @@ Import Workflow APIs from the package root:
 
 ```ts
 import {
+  makeDurableAgentEventSequencerState,
   noWorkflowStepRetry,
-  runVercelAgentWorkflow
+  runVercelAgentWorkflow,
+  writeDurableAgentEvent
 } from '@yolk-sdk/vercel-workflows'
 ```
 
@@ -88,7 +90,33 @@ 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.
+Default retry policy is `noWorkflowStepRetry` (`maxAttempts: 1`). Retries are opt-in because
+streamed retries can duplicate chunks unless host/client de-dupe is ready.
+
+## Durable stream events
+
+Workflow streams can replay old chunks after retries or reconnects. Durable streams should emit an
+`eventId` on every JSON-serializable event, typically `AgentEvent`, including errors. Clients should
+track seen ids.
+
+Use `writeDurableAgentEvent` to assign deterministic ids and write NDJSON:
+
+```ts
+const state = makeDurableAgentEventSequencerState(eventSequence)
+const sequenced = await writeDurableAgentEvent({
+  writer,
+  event,
+  streamId: 'workflow',
+  turn,
+  state
+})
+
+eventSequence = sequenced.nextEventSequence
+```
+
+The id format is `${streamId}:${turn}:${eventSequence}`. Keep `eventSequence` in Workflow state.
+Resume route reads should use `startIndex` when available. Host apps still own active-run locking,
+stale-run guards, and cancellation behavior.
 
 ## Host responsibilities
 
@@ -97,6 +125,7 @@ Default retry policy is `noWorkflowStepRetry` (`maxAttempts: 1`). Retries are op
 - Preserve tool result order and never advance the next model step with dangling host tool calls.
 - Decide cancellation/resume/conflict UX.
 - Own hook tokens and response validation for HITL resume.
+- Emit replay-safe event ids for durable streams and de-dupe by `eventId` client-side.
 - Test directive behavior with `@workflow/vitest` when changing package-owned Workflow files.
 
 ## Boundaries

package/dist/index.d.mts

@@ -1,2 +1,3 @@
 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 };
+import { DurableAgentEvent, DurableAgentEventIdInput, DurableAgentEventSequencerState, SequenceDurableAgentEventInput, SequencedDurableAgentEvent, WriteDurableAgentEventInput, durableAgentEventId, makeDurableAgentEventSequencerState, sequenceDurableAgentEvent, writeDurableAgentEvent } from "./workflow-events.mjs";
+export { 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, defaultMaxWorkflowTurns, durableAgentEventId, makeDurableAgentEventSequencerState, noWorkflowStepRetry, retryWorkflowStep, runVercelAgentWorkflow, sequenceDurableAgentEvent, settleWorkflowStep, writeDurableAgentEvent };

package/dist/index.mjs

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

package/dist/workflow-events.d.mts

@@ -0,0 +1,36 @@
+//#region src/workflow-events.d.ts
+type DurableAgentEventSequencerState = {
+  readonly eventSequence: number;
+};
+type DurableAgentEvent<Event extends object = object> = Event & {
+  readonly eventId: string;
+  readonly createdAtMs?: number;
+};
+type DurableAgentEventIdInput = {
+  readonly streamId: string;
+  readonly turn: number;
+  readonly eventSequence: number;
+};
+type SequenceDurableAgentEventInput<Event extends object = object> = {
+  readonly state: DurableAgentEventSequencerState;
+  readonly streamId: string;
+  readonly turn: number;
+  readonly event: Event;
+  readonly createdAtMs?: number;
+};
+type SequencedDurableAgentEvent<Event extends object = object> = {
+  readonly event: DurableAgentEvent<Event>;
+  readonly eventSequence: number;
+  readonly nextEventSequence: number;
+  readonly nextState: DurableAgentEventSequencerState;
+};
+type WriteDurableAgentEventInput<Event extends object = object> = SequenceDurableAgentEventInput<Event> & {
+  readonly writer: WritableStreamDefaultWriter<Uint8Array>;
+};
+declare const makeDurableAgentEventSequencerState: (eventSequence?: number) => DurableAgentEventSequencerState;
+declare const durableAgentEventId: (input: DurableAgentEventIdInput) => string;
+declare const sequenceDurableAgentEvent: <Event extends object>(input: SequenceDurableAgentEventInput<Event>) => SequencedDurableAgentEvent<Event>;
+declare const writeDurableAgentEvent: <Event extends object>(input: WriteDurableAgentEventInput<Event>) => Promise<SequencedDurableAgentEvent<Event>>;
+//#endregion
+export { DurableAgentEvent, DurableAgentEventIdInput, DurableAgentEventSequencerState, SequenceDurableAgentEventInput, SequencedDurableAgentEvent, WriteDurableAgentEventInput, durableAgentEventId, makeDurableAgentEventSequencerState, sequenceDurableAgentEvent, writeDurableAgentEvent };
+//# sourceMappingURL=workflow-events.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-events.d.mts","names":[],"sources":["../src/workflow-events.ts"],"mappings":";KAAY,+BAAA;EAAA,SACD,aAAa;AAAA;AAAA,KAGZ,iBAAA,kCAAmD,KAAK;EAAA,SACzD,OAAA;EAAA,SACA,WAAA;AAAA;AAAA,KAGC,wBAAA;EAAA,SACD,QAAA;EAAA,SACA,IAAA;EAAA,SACA,aAAA;AAAA;AAAA,KAGC,8BAAA;EAAA,SACD,KAAA,EAAO,+BAAA;EAAA,SACP,QAAA;EAAA,SACA,IAAA;EAAA,SACA,KAAA,EAAO,KAAK;EAAA,SACZ,WAAA;AAAA;AAAA,KAGC,0BAAA;EAAA,SACD,KAAA,EAAO,iBAAA,CAAkB,KAAA;EAAA,SACzB,aAAA;EAAA,SACA,iBAAA;EAAA,SACA,SAAA,EAAW,+BAAA;AAAA;AAAA,KAGV,2BAAA,kCACV,8BAAA,CAA+B,KAAA;EAAA,SACpB,MAAA,EAAQ,2BAAA,CAA4B,UAAA;AAAA;AAAA,cAKpC,mCAAA,GACX,aAAA,cACC,+BAAsD;AAAA,cAE5C,mBAAA,GAAuB,KAA+B,EAAxB,wBAAwB;AAAA,cAGtD,yBAAA,yBACX,KAAA,EAAO,8BAAA,CAA+B,KAAA,MACrC,0BAAA,CAA2B,KAAA;AAAA,cA0BjB,sBAAA,yBACX,KAAA,EAAO,2BAAA,CAA4B,KAAA,MAClC,OAAA,CAAQ,0BAAA,CAA2B,KAAA"}

package/dist/workflow-events.mjs

@@ -0,0 +1,32 @@
+//#region src/workflow-events.ts
+const textEncoder = new TextEncoder();
+const makeDurableAgentEventSequencerState = (eventSequence = 0) => ({ eventSequence });
+const durableAgentEventId = (input) => `${input.streamId}:${input.turn}:${input.eventSequence}`;
+const sequenceDurableAgentEvent = (input) => {
+	const eventSequence = input.state.eventSequence;
+	const nextEventSequence = eventSequence + 1;
+	return {
+		event: {
+			...input.event,
+			eventId: durableAgentEventId({
+				streamId: input.streamId,
+				turn: input.turn,
+				eventSequence
+			}),
+			...input.createdAtMs === void 0 ? {} : { createdAtMs: input.createdAtMs }
+		},
+		eventSequence,
+		nextEventSequence,
+		nextState: makeDurableAgentEventSequencerState(nextEventSequence)
+	};
+};
+const encodeDurableAgentEventNdjson = (event) => textEncoder.encode(`${JSON.stringify(event)}\n`);
+const writeDurableAgentEvent = async (input) => {
+	const sequenced = sequenceDurableAgentEvent(input);
+	await input.writer.write(encodeDurableAgentEventNdjson(sequenced.event));
+	return sequenced;
+};
+//#endregion
+export { durableAgentEventId, makeDurableAgentEventSequencerState, sequenceDurableAgentEvent, writeDurableAgentEvent };
+
+//# sourceMappingURL=workflow-events.mjs.map

package/dist/workflow-events.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-events.mjs","names":[],"sources":["../src/workflow-events.ts"],"sourcesContent":["export type DurableAgentEventSequencerState = {\n  readonly eventSequence: number\n}\n\nexport type DurableAgentEvent<Event extends object = object> = Event & {\n  readonly eventId: string\n  readonly createdAtMs?: number\n}\n\nexport type DurableAgentEventIdInput = {\n  readonly streamId: string\n  readonly turn: number\n  readonly eventSequence: number\n}\n\nexport type SequenceDurableAgentEventInput<Event extends object = object> = {\n  readonly state: DurableAgentEventSequencerState\n  readonly streamId: string\n  readonly turn: number\n  readonly event: Event\n  readonly createdAtMs?: number\n}\n\nexport type SequencedDurableAgentEvent<Event extends object = object> = {\n  readonly event: DurableAgentEvent<Event>\n  readonly eventSequence: number\n  readonly nextEventSequence: number\n  readonly nextState: DurableAgentEventSequencerState\n}\n\nexport type WriteDurableAgentEventInput<Event extends object = object> =\n  SequenceDurableAgentEventInput<Event> & {\n    readonly writer: WritableStreamDefaultWriter<Uint8Array>\n  }\n\nconst textEncoder = new TextEncoder()\n\nexport const makeDurableAgentEventSequencerState = (\n  eventSequence = 0\n): DurableAgentEventSequencerState => ({ eventSequence })\n\nexport const durableAgentEventId = (input: DurableAgentEventIdInput) =>\n  `${input.streamId}:${input.turn}:${input.eventSequence}`\n\nexport const sequenceDurableAgentEvent = <Event extends object>(\n  input: SequenceDurableAgentEventInput<Event>\n): SequencedDurableAgentEvent<Event> => {\n  const eventSequence = input.state.eventSequence\n  const nextEventSequence = eventSequence + 1\n  const event = {\n    ...input.event,\n    eventId: durableAgentEventId({\n      streamId: input.streamId,\n      turn: input.turn,\n      eventSequence\n    }),\n    ...(input.createdAtMs === undefined ? {} : { createdAtMs: input.createdAtMs })\n  }\n\n  return {\n    event,\n    eventSequence,\n    nextEventSequence,\n    nextState: makeDurableAgentEventSequencerState(nextEventSequence)\n  }\n}\n\nconst encodeDurableAgentEventNdjson = <Event extends object>(\n  event: DurableAgentEvent<Event>\n) =>\n  textEncoder.encode(`${JSON.stringify(event)}\\n`)\n\nexport const writeDurableAgentEvent = async <Event extends object>(\n  input: WriteDurableAgentEventInput<Event>\n): Promise<SequencedDurableAgentEvent<Event>> => {\n  const sequenced = sequenceDurableAgentEvent(input)\n  await input.writer.write(encodeDurableAgentEventNdjson(sequenced.event))\n\n  return sequenced\n}\n"],"mappings":";AAmCA,MAAM,cAAc,IAAI,YAAY;AAEpC,MAAa,uCACX,gBAAgB,OACqB,EAAE,cAAc;AAEvD,MAAa,uBAAuB,UAClC,GAAG,MAAM,SAAS,GAAG,MAAM,KAAK,GAAG,MAAM;AAE3C,MAAa,6BACX,UACsC;CACtC,MAAM,gBAAgB,MAAM,MAAM;CAClC,MAAM,oBAAoB,gBAAgB;CAW1C,OAAO;EACL,OAAA;GAVA,GAAG,MAAM;GACT,SAAS,oBAAoB;IAC3B,UAAU,MAAM;IAChB,MAAM,MAAM;IACZ;GACF,CAAC;GACD,GAAI,MAAM,gBAAgB,KAAA,IAAY,CAAC,IAAI,EAAE,aAAa,MAAM,YAAY;EAIxE;EACJ;EACA;EACA,WAAW,oCAAoC,iBAAiB;CAClE;AACF;AAEA,MAAM,iCACJ,UAEA,YAAY,OAAO,GAAG,KAAK,UAAU,KAAK,EAAE,GAAG;AAEjD,MAAa,yBAAyB,OACpC,UAC+C;CAC/C,MAAM,YAAY,0BAA0B,KAAK;CACjD,MAAM,MAAM,OAAO,MAAM,8BAA8B,UAAU,KAAK,CAAC;CAEvE,OAAO;AACT"}

package/dist/workflow.d.mts

@@ -1,2 +1,3 @@
 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 };
+import { DurableAgentEvent, DurableAgentEventIdInput, DurableAgentEventSequencerState, SequenceDurableAgentEventInput, SequencedDurableAgentEvent, WriteDurableAgentEventInput, durableAgentEventId, makeDurableAgentEventSequencerState, sequenceDurableAgentEvent, writeDurableAgentEvent } from "./workflow-events.mjs";
+export { 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, defaultMaxWorkflowTurns, durableAgentEventId, makeDurableAgentEventSequencerState, noWorkflowStepRetry, retryWorkflowStep, runVercelAgentWorkflow, sequenceDurableAgentEvent, settleWorkflowStep, writeDurableAgentEvent };

package/dist/workflow.mjs

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

package/package.json

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

package/src/index.ts

@@ -1,11 +1,20 @@
 export {
+  durableAgentEventId,
   defaultMaxWorkflowTurns,
+  makeDurableAgentEventSequencerState,
   noWorkflowStepRetry,
   retryWorkflowStep,
   runVercelAgentWorkflow,
-  settleWorkflowStep
+  sequenceDurableAgentEvent,
+  settleWorkflowStep,
+  writeDurableAgentEvent
 } from './workflow.ts'
 export type {
+  DurableAgentEvent,
+  DurableAgentEventIdInput,
+  DurableAgentEventSequencerState,
+  SequenceDurableAgentEventInput,
+  SequencedDurableAgentEvent,
   SerializableWorkflowState,
   VercelAgentWorkflowAwaitingInput,
   VercelAgentWorkflowInput,
@@ -16,5 +25,6 @@ export type {
   VercelAgentWorkflowStepRetryPolicy,
   VercelAgentWorkflowToolBatchStepInput,
   VercelAgentWorkflowToolBatchStepResult,
-  WorkflowStepResult
+  WorkflowStepResult,
+  WriteDurableAgentEventInput
 } from './workflow.ts'

package/src/workflow-events.ts

@@ -0,0 +1,80 @@
+export type DurableAgentEventSequencerState = {
+  readonly eventSequence: number
+}
+
+export type DurableAgentEvent<Event extends object = object> = Event & {
+  readonly eventId: string
+  readonly createdAtMs?: number
+}
+
+export type DurableAgentEventIdInput = {
+  readonly streamId: string
+  readonly turn: number
+  readonly eventSequence: number
+}
+
+export type SequenceDurableAgentEventInput<Event extends object = object> = {
+  readonly state: DurableAgentEventSequencerState
+  readonly streamId: string
+  readonly turn: number
+  readonly event: Event
+  readonly createdAtMs?: number
+}
+
+export type SequencedDurableAgentEvent<Event extends object = object> = {
+  readonly event: DurableAgentEvent<Event>
+  readonly eventSequence: number
+  readonly nextEventSequence: number
+  readonly nextState: DurableAgentEventSequencerState
+}
+
+export type WriteDurableAgentEventInput<Event extends object = object> =
+  SequenceDurableAgentEventInput<Event> & {
+    readonly writer: WritableStreamDefaultWriter<Uint8Array>
+  }
+
+const textEncoder = new TextEncoder()
+
+export const makeDurableAgentEventSequencerState = (
+  eventSequence = 0
+): DurableAgentEventSequencerState => ({ eventSequence })
+
+export const durableAgentEventId = (input: DurableAgentEventIdInput) =>
+  `${input.streamId}:${input.turn}:${input.eventSequence}`
+
+export const sequenceDurableAgentEvent = <Event extends object>(
+  input: SequenceDurableAgentEventInput<Event>
+): SequencedDurableAgentEvent<Event> => {
+  const eventSequence = input.state.eventSequence
+  const nextEventSequence = eventSequence + 1
+  const event = {
+    ...input.event,
+    eventId: durableAgentEventId({
+      streamId: input.streamId,
+      turn: input.turn,
+      eventSequence
+    }),
+    ...(input.createdAtMs === undefined ? {} : { createdAtMs: input.createdAtMs })
+  }
+
+  return {
+    event,
+    eventSequence,
+    nextEventSequence,
+    nextState: makeDurableAgentEventSequencerState(nextEventSequence)
+  }
+}
+
+const encodeDurableAgentEventNdjson = <Event extends object>(
+  event: DurableAgentEvent<Event>
+) =>
+  textEncoder.encode(`${JSON.stringify(event)}\n`)
+
+export const writeDurableAgentEvent = async <Event extends object>(
+  input: WriteDurableAgentEventInput<Event>
+): Promise<SequencedDurableAgentEvent<Event>> => {
+  const sequenced = sequenceDurableAgentEvent(input)
+  await input.writer.write(encodeDurableAgentEventNdjson(sequenced.event))
+
+  return sequenced
+}

package/src/workflow.ts

@@ -5,6 +5,12 @@ export {
   runVercelAgentWorkflow,
   settleWorkflowStep
 } from './workflow-loop.ts'
+export {
+  durableAgentEventId,
+  makeDurableAgentEventSequencerState,
+  sequenceDurableAgentEvent,
+  writeDurableAgentEvent
+} from './workflow-events.ts'
 export type {
   SerializableWorkflowState,
   VercelAgentWorkflowAwaitingInput,
@@ -18,3 +24,11 @@ export type {
   VercelAgentWorkflowToolBatchStepResult,
   WorkflowStepResult
 } from './workflow-loop.ts'
+export type {
+  DurableAgentEvent,
+  DurableAgentEventIdInput,
+  DurableAgentEventSequencerState,
+  SequenceDurableAgentEventInput,
+  SequencedDurableAgentEvent,
+  WriteDurableAgentEventInput
+} from './workflow-events.ts'