@yolk-sdk/vercel-workflows 0.1.0-canary.27 → 0.1.0-canary.29

package/README.md

@@ -23,6 +23,7 @@ Import Workflow APIs from the package root:
 
 ```ts
 import {
+  commitThenWriteTerminalEvent,
   makeDurableAgentEventSequencerState,
   noWorkflowStepRetry,
   runVercelAgentWorkflow,
@@ -118,6 +119,37 @@ The id format is `${streamId}:${turn}:${eventSequence}`. Keep `eventSequence` in
 Resume route reads should use `startIndex` when available. Host apps still own active-run locking,
 stale-run guards, and cancellation behavior.
 
+## Terminal barriers
+
+For durable host streams, terminal events are commit barriers. Emit live/progress events first,
+commit canonical host state, then write the terminal event, then close the writer:
+
+```txt
+live events -> host durable commit -> terminal event -> close
+```
+
+This lets clients stop consuming at a protocol-terminal event and immediately revalidate or reconnect
+from durable state. Hosts that emit terminal events before persistence should not rely on
+`streamAgentEventsUntilTerminal()` as a durable-settled signal.
+
+Use `commitThenWriteTerminalEvent` when a step must commit host state before writing its terminal
+event:
+
+```ts
+const result = await commitThenWriteTerminalEvent({
+  terminal,
+  commit: () => persistState(),
+  write: event => writeDurableAgentEvent({ writer, event, streamId, turn, state }),
+  writeCommitError: error =>
+    writeDurableAgentEvent({ writer, event: commitErrorEvent(error), streamId, turn, state }),
+  close: () => writer.close()
+})
+```
+
+The helper never writes the success terminal before `commit` succeeds. If `commit` fails, it writes
+the host-provided terminal error event instead. Terminal write failures still attempt `close`; close
+failures are returned separately and do not turn a successful durable commit into a failed commit.
+
 ## Host responsibilities
 
 - Own Next/Vercel routes, auth, providers, tools, persistence, and telemetry.
@@ -126,6 +158,7 @@ stale-run guards, and cancellation behavior.
 - 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.
+- Write durable terminal events only after host persistence has settled.
 - Test directive behavior with `@workflow/vitest` when changing package-owned Workflow files.
 
 ## Boundaries

package/dist/index.d.mts

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

package/dist/index.mjs

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

package/dist/workflow-events.d.mts

@@ -27,10 +27,43 @@ type SequencedDurableAgentEvent<Event extends object = object> = {
 type WriteDurableAgentEventInput<Event extends object = object> = SequenceDurableAgentEventInput<Event> & {
   readonly writer: WritableStreamDefaultWriter<Uint8Array>;
 };
+type TerminalEventCloseResult = {
+  readonly _tag: 'Closed';
+} | {
+  readonly _tag: 'CloseFailed';
+  readonly error: unknown;
+};
+type CommitThenWriteTerminalEventInput<TerminalEvent extends object, TerminalWriteResult, CommitErrorWriteResult> = {
+  readonly commit: () => Promise<void>;
+  readonly terminal: TerminalEvent;
+  readonly write: (event: TerminalEvent) => Promise<TerminalWriteResult>;
+  readonly writeCommitError: (error: unknown) => Promise<CommitErrorWriteResult>;
+  readonly close: () => Promise<void>;
+};
+type CommitThenWriteTerminalEventResult<TerminalWriteResult, CommitErrorWriteResult> = {
+  readonly _tag: 'Committed';
+  readonly writeResult: TerminalWriteResult;
+  readonly closeResult: TerminalEventCloseResult;
+} | {
+  readonly _tag: 'CommitFailed';
+  readonly commitError: unknown;
+  readonly writeResult: CommitErrorWriteResult;
+  readonly closeResult: TerminalEventCloseResult;
+} | {
+  readonly _tag: 'TerminalWriteFailed';
+  readonly error: unknown;
+  readonly closeResult: TerminalEventCloseResult;
+} | {
+  readonly _tag: 'CommitErrorWriteFailed';
+  readonly commitError: unknown;
+  readonly error: unknown;
+  readonly closeResult: TerminalEventCloseResult;
+};
 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>>;
+declare const commitThenWriteTerminalEvent: <TerminalEvent extends object, TerminalWriteResult, CommitErrorWriteResult>(input: CommitThenWriteTerminalEventInput<TerminalEvent, TerminalWriteResult, CommitErrorWriteResult>) => Promise<CommitThenWriteTerminalEventResult<TerminalWriteResult, CommitErrorWriteResult>>;
 //#endregion
-export { DurableAgentEvent, DurableAgentEventIdInput, DurableAgentEventSequencerState, SequenceDurableAgentEventInput, SequencedDurableAgentEvent, WriteDurableAgentEventInput, durableAgentEventId, makeDurableAgentEventSequencerState, sequenceDurableAgentEvent, writeDurableAgentEvent };
+export { CommitThenWriteTerminalEventInput, CommitThenWriteTerminalEventResult, DurableAgentEvent, DurableAgentEventIdInput, DurableAgentEventSequencerState, SequenceDurableAgentEventInput, SequencedDurableAgentEvent, TerminalEventCloseResult, WriteDurableAgentEventInput, commitThenWriteTerminalEvent, durableAgentEventId, makeDurableAgentEventSequencerState, sequenceDurableAgentEvent, writeDurableAgentEvent };
 //# sourceMappingURL=workflow-events.d.mts.map

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

@@ -1 +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"}
+{"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,KAGrC,wBAAA;EAAA,SACG,IAAA;AAAA;EAAA,SACA,IAAA;EAAA,SAA8B,KAAA;AAAA;AAAA,KAEjC,iCAAA;EAAA,SAKD,MAAA,QAAc,OAAA;EAAA,SACd,QAAA,EAAU,aAAA;EAAA,SACV,KAAA,GAAQ,KAAA,EAAO,aAAA,KAAkB,OAAA,CAAQ,mBAAA;EAAA,SACzC,gBAAA,GAAmB,KAAA,cAAmB,OAAA,CAAQ,sBAAA;EAAA,SAC9C,KAAA,QAAa,OAAA;AAAA;AAAA,KAGZ,kCAAA;EAAA,SAEG,IAAA;EAAA,SACA,WAAA,EAAa,mBAAA;EAAA,SACb,WAAA,EAAa,wBAAA;AAAA;EAAA,SAGb,IAAA;EAAA,SACA,WAAA;EAAA,SACA,WAAA,EAAa,sBAAA;EAAA,SACb,WAAA,EAAa,wBAAA;AAAA;EAAA,SAGb,IAAA;EAAA,SACA,KAAA;EAAA,SACA,WAAA,EAAa,wBAAA;AAAA;EAAA,SAGb,IAAA;EAAA,SACA,WAAA;EAAA,SACA,KAAA;EAAA,SACA,WAAA,EAAa,wBAAA;AAAA;AAAA,cAKf,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;AAAA,cAmBzB,4BAAA,8EAKX,KAAA,EAAO,iCAAA,CACL,aAAA,EACA,mBAAA,EACA,sBAAA,MAED,OAAA,CAAQ,kCAAA,CAAmC,mBAAA,EAAqB,sBAAA"}

package/dist/workflow-events.mjs

@@ -26,7 +26,52 @@ const writeDurableAgentEvent = async (input) => {
 	await input.writer.write(encodeDurableAgentEventNdjson(sequenced.event));
 	return sequenced;
 };
+const closeTerminalEventWriter = async (close) => {
+	try {
+		await close();
+		return { _tag: "Closed" };
+	} catch (error) {
+		return {
+			_tag: "CloseFailed",
+			error
+		};
+	}
+};
+const commitThenWriteTerminalEvent = async (input) => {
+	try {
+		await input.commit();
+	} catch (commitError) {
+		try {
+			return {
+				_tag: "CommitFailed",
+				commitError,
+				writeResult: await input.writeCommitError(commitError),
+				closeResult: await closeTerminalEventWriter(input.close)
+			};
+		} catch (error) {
+			return {
+				_tag: "CommitErrorWriteFailed",
+				commitError,
+				error,
+				closeResult: await closeTerminalEventWriter(input.close)
+			};
+		}
+	}
+	try {
+		return {
+			_tag: "Committed",
+			writeResult: await input.write(input.terminal),
+			closeResult: await closeTerminalEventWriter(input.close)
+		};
+	} catch (error) {
+		return {
+			_tag: "TerminalWriteFailed",
+			error,
+			closeResult: await closeTerminalEventWriter(input.close)
+		};
+	}
+};
 //#endregion
-export { durableAgentEventId, makeDurableAgentEventSequencerState, sequenceDurableAgentEvent, writeDurableAgentEvent };
+export { commitThenWriteTerminalEvent, durableAgentEventId, makeDurableAgentEventSequencerState, sequenceDurableAgentEvent, writeDurableAgentEvent };
 
 //# sourceMappingURL=workflow-events.mjs.map

package/dist/workflow-events.mjs.map

@@ -1 +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"}
+{"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\nexport type TerminalEventCloseResult =\n  | { readonly _tag: 'Closed' }\n  | { readonly _tag: 'CloseFailed'; readonly error: unknown }\n\nexport type CommitThenWriteTerminalEventInput<\n  TerminalEvent extends object,\n  TerminalWriteResult,\n  CommitErrorWriteResult\n> = {\n  readonly commit: () => Promise<void>\n  readonly terminal: TerminalEvent\n  readonly write: (event: TerminalEvent) => Promise<TerminalWriteResult>\n  readonly writeCommitError: (error: unknown) => Promise<CommitErrorWriteResult>\n  readonly close: () => Promise<void>\n}\n\nexport type CommitThenWriteTerminalEventResult<TerminalWriteResult, CommitErrorWriteResult> =\n  | {\n      readonly _tag: 'Committed'\n      readonly writeResult: TerminalWriteResult\n      readonly closeResult: TerminalEventCloseResult\n    }\n  | {\n      readonly _tag: 'CommitFailed'\n      readonly commitError: unknown\n      readonly writeResult: CommitErrorWriteResult\n      readonly closeResult: TerminalEventCloseResult\n    }\n  | {\n      readonly _tag: 'TerminalWriteFailed'\n      readonly error: unknown\n      readonly closeResult: TerminalEventCloseResult\n    }\n  | {\n      readonly _tag: 'CommitErrorWriteFailed'\n      readonly commitError: unknown\n      readonly error: unknown\n      readonly closeResult: TerminalEventCloseResult\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\nconst closeTerminalEventWriter = async (\n  close: () => Promise<void>\n): Promise<TerminalEventCloseResult> => {\n  try {\n    await close()\n\n    return { _tag: 'Closed' }\n  } catch (error) {\n    return { _tag: 'CloseFailed', error }\n  }\n}\n\nexport const commitThenWriteTerminalEvent = async <\n  TerminalEvent extends object,\n  TerminalWriteResult,\n  CommitErrorWriteResult\n>(\n  input: CommitThenWriteTerminalEventInput<\n    TerminalEvent,\n    TerminalWriteResult,\n    CommitErrorWriteResult\n  >\n): Promise<CommitThenWriteTerminalEventResult<TerminalWriteResult, CommitErrorWriteResult>> => {\n  try {\n    await input.commit()\n  } catch (commitError) {\n    try {\n      const writeResult = await input.writeCommitError(commitError)\n      const closeResult = await closeTerminalEventWriter(input.close)\n\n      return { _tag: 'CommitFailed', commitError, writeResult, closeResult }\n    } catch (error) {\n      const closeResult = await closeTerminalEventWriter(input.close)\n\n      return { _tag: 'CommitErrorWriteFailed', commitError, error, closeResult }\n    }\n  }\n\n  try {\n    const writeResult = await input.write(input.terminal)\n    const closeResult = await closeTerminalEventWriter(input.close)\n\n    return { _tag: 'Committed', writeResult, closeResult }\n  } catch (error) {\n    const closeResult = await closeTerminalEventWriter(input.close)\n\n    return { _tag: 'TerminalWriteFailed', error, closeResult }\n  }\n}\n"],"mappings":";AA2EA,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;AAEA,MAAM,2BAA2B,OAC/B,UACsC;CACtC,IAAI;EACF,MAAM,MAAM;EAEZ,OAAO,EAAE,MAAM,SAAS;CAC1B,SAAS,OAAO;EACd,OAAO;GAAE,MAAM;GAAe;EAAM;CACtC;AACF;AAEA,MAAa,+BAA+B,OAK1C,UAK6F;CAC7F,IAAI;EACF,MAAM,MAAM,OAAO;CACrB,SAAS,aAAa;EACpB,IAAI;GAIF,OAAO;IAAE,MAAM;IAAgB;IAAa,aAAA,MAHlB,MAAM,iBAAiB,WAAW;IAGH,aAAA,MAF/B,yBAAyB,MAAM,KAAK;GAEO;EACvE,SAAS,OAAO;GAGd,OAAO;IAAE,MAAM;IAA0B;IAAa;IAAO,aAAA,MAFnC,yBAAyB,MAAM,KAAK;GAEW;EAC3E;CACF;CAEA,IAAI;EAIF,OAAO;GAAE,MAAM;GAAa,aAAA,MAHF,MAAM,MAAM,MAAM,QAAQ;GAGX,aAAA,MAFf,yBAAyB,MAAM,KAAK;EAET;CACvD,SAAS,OAAO;EAGd,OAAO;GAAE,MAAM;GAAuB;GAAO,aAAA,MAFnB,yBAAyB,MAAM,KAAK;EAEL;CAC3D;AACF"}

package/dist/workflow.d.mts

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

package/dist/workflow.mjs

@@ -1,3 +1,3 @@
 import { defaultMaxWorkflowTurns, noWorkflowStepRetry, retryWorkflowStep, runVercelAgentWorkflow, settleWorkflowStep } from "./workflow-loop.mjs";
-import { durableAgentEventId, makeDurableAgentEventSequencerState, sequenceDurableAgentEvent, writeDurableAgentEvent } from "./workflow-events.mjs";
-export { defaultMaxWorkflowTurns, durableAgentEventId, makeDurableAgentEventSequencerState, noWorkflowStepRetry, retryWorkflowStep, runVercelAgentWorkflow, sequenceDurableAgentEvent, settleWorkflowStep, writeDurableAgentEvent };
+import { commitThenWriteTerminalEvent, durableAgentEventId, makeDurableAgentEventSequencerState, sequenceDurableAgentEvent, writeDurableAgentEvent } from "./workflow-events.mjs";
+export { commitThenWriteTerminalEvent, 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.27",
+  "version": "0.1.0-canary.29",
   "description": "Vercel Workflow orchestration primitives for Yolk agent loops.",
   "license": "MIT",
   "type": "module",

package/src/index.ts

@@ -1,4 +1,5 @@
 export {
+  commitThenWriteTerminalEvent,
   durableAgentEventId,
   defaultMaxWorkflowTurns,
   makeDurableAgentEventSequencerState,
@@ -10,6 +11,8 @@ export {
   writeDurableAgentEvent
 } from './workflow.ts'
 export type {
+  CommitThenWriteTerminalEventInput,
+  CommitThenWriteTerminalEventResult,
   DurableAgentEvent,
   DurableAgentEventIdInput,
   DurableAgentEventSequencerState,
@@ -25,6 +28,7 @@ export type {
   VercelAgentWorkflowStepRetryPolicy,
   VercelAgentWorkflowToolBatchStepInput,
   VercelAgentWorkflowToolBatchStepResult,
+  TerminalEventCloseResult,
   WorkflowStepResult,
   WriteDurableAgentEventInput
 } from './workflow.ts'

package/src/workflow-events.ts

@@ -33,6 +33,46 @@ export type WriteDurableAgentEventInput<Event extends object = object> =
     readonly writer: WritableStreamDefaultWriter<Uint8Array>
   }
 
+export type TerminalEventCloseResult =
+  | { readonly _tag: 'Closed' }
+  | { readonly _tag: 'CloseFailed'; readonly error: unknown }
+
+export type CommitThenWriteTerminalEventInput<
+  TerminalEvent extends object,
+  TerminalWriteResult,
+  CommitErrorWriteResult
+> = {
+  readonly commit: () => Promise<void>
+  readonly terminal: TerminalEvent
+  readonly write: (event: TerminalEvent) => Promise<TerminalWriteResult>
+  readonly writeCommitError: (error: unknown) => Promise<CommitErrorWriteResult>
+  readonly close: () => Promise<void>
+}
+
+export type CommitThenWriteTerminalEventResult<TerminalWriteResult, CommitErrorWriteResult> =
+  | {
+      readonly _tag: 'Committed'
+      readonly writeResult: TerminalWriteResult
+      readonly closeResult: TerminalEventCloseResult
+    }
+  | {
+      readonly _tag: 'CommitFailed'
+      readonly commitError: unknown
+      readonly writeResult: CommitErrorWriteResult
+      readonly closeResult: TerminalEventCloseResult
+    }
+  | {
+      readonly _tag: 'TerminalWriteFailed'
+      readonly error: unknown
+      readonly closeResult: TerminalEventCloseResult
+    }
+  | {
+      readonly _tag: 'CommitErrorWriteFailed'
+      readonly commitError: unknown
+      readonly error: unknown
+      readonly closeResult: TerminalEventCloseResult
+    }
+
 const textEncoder = new TextEncoder()
 
 export const makeDurableAgentEventSequencerState = (
@@ -78,3 +118,53 @@ export const writeDurableAgentEvent = async <Event extends object>(
 
   return sequenced
 }
+
+const closeTerminalEventWriter = async (
+  close: () => Promise<void>
+): Promise<TerminalEventCloseResult> => {
+  try {
+    await close()
+
+    return { _tag: 'Closed' }
+  } catch (error) {
+    return { _tag: 'CloseFailed', error }
+  }
+}
+
+export const commitThenWriteTerminalEvent = async <
+  TerminalEvent extends object,
+  TerminalWriteResult,
+  CommitErrorWriteResult
+>(
+  input: CommitThenWriteTerminalEventInput<
+    TerminalEvent,
+    TerminalWriteResult,
+    CommitErrorWriteResult
+  >
+): Promise<CommitThenWriteTerminalEventResult<TerminalWriteResult, CommitErrorWriteResult>> => {
+  try {
+    await input.commit()
+  } catch (commitError) {
+    try {
+      const writeResult = await input.writeCommitError(commitError)
+      const closeResult = await closeTerminalEventWriter(input.close)
+
+      return { _tag: 'CommitFailed', commitError, writeResult, closeResult }
+    } catch (error) {
+      const closeResult = await closeTerminalEventWriter(input.close)
+
+      return { _tag: 'CommitErrorWriteFailed', commitError, error, closeResult }
+    }
+  }
+
+  try {
+    const writeResult = await input.write(input.terminal)
+    const closeResult = await closeTerminalEventWriter(input.close)
+
+    return { _tag: 'Committed', writeResult, closeResult }
+  } catch (error) {
+    const closeResult = await closeTerminalEventWriter(input.close)
+
+    return { _tag: 'TerminalWriteFailed', error, closeResult }
+  }
+}

package/src/workflow.ts

@@ -6,6 +6,7 @@ export {
   settleWorkflowStep
 } from './workflow-loop.ts'
 export {
+  commitThenWriteTerminalEvent,
   durableAgentEventId,
   makeDurableAgentEventSequencerState,
   sequenceDurableAgentEvent,
@@ -28,7 +29,10 @@ export type {
   DurableAgentEvent,
   DurableAgentEventIdInput,
   DurableAgentEventSequencerState,
+  CommitThenWriteTerminalEventInput,
+  CommitThenWriteTerminalEventResult,
   SequenceDurableAgentEventInput,
   SequencedDurableAgentEvent,
+  TerminalEventCloseResult,
   WriteDurableAgentEventInput
 } from './workflow-events.ts'