eve 0.24.4 → 0.24.6

package/dist/src/client/session.d.ts

@@ -1,6 +1,6 @@
 import type { HandleMessageStreamEvent } from "#protocol/message.js";
 import { MessageResponse } from "#client/message-response.js";
-import type { ClientRedirectPolicy, SendTurnInput, SessionState, StreamOptions } from "#client/types.js";
+import type { CancelSessionResult, ClientRedirectPolicy, SendTurnInput, SessionState, StreamOptions } from "#client/types.js";
 /**
  * Internal interface that a {@link ClientSession} uses to access client-level
  * configuration without depending on the full {@link Client} class.
@@ -24,8 +24,9 @@ export declare class ClientSession {
     /** @internal */
     constructor(context: SessionContext, state: SessionState);
     /**
-     * Current session cursor. Always reflects the latest state after each
-     * completed turn. Serialize this to persist and resume later.
+     * Current session cursor. The assigned session ID appears as soon as a send
+     * is accepted; the continuation token and stream index advance as its event
+     * stream is consumed. Serialize this to persist and resume later.
      */
     get state(): SessionState;
     /**
@@ -36,6 +37,21 @@ export declare class ClientSession {
      * headers in a single request.
      */
     send<TOutput = unknown>(input: SendTurnInput<TOutput>): Promise<MessageResponse<TOutput>>;
+    /**
+     * Requests cooperative cancellation of this session's active turn.
+     *
+     * Both `accepted` and `no_active_turn` are successful outcomes. The latter
+     * means the active turn settled before the request arrived or the session is
+     * already parked. `turnId` limits the request to the turn the caller
+     * observed; a stale guard is consumed as a benign no-op. Credentials are
+     * resolved immediately before the request.
+     *
+     * @throws {Error} If this handle has not started or attached to a session.
+     * @throws {ClientError} If the cancel route returns a non-successful status.
+     */
+    cancel(options?: {
+        turnId?: string;
+    }): Promise<CancelSessionResult>;
     /**
      * Opens this session's event stream for the current session ID.
      *

package/dist/src/client/session.js

@@ -1 +1 @@
-import{EVE_CREATE_SESSION_ROUTE_PATH,createEveContinueSessionRoutePath}from"#protocol/routes.js";import{ClientError}from"#client/client-error.js";import{advanceSession}from"#client/session-utils.js";import{createClientUrl}from"#client/url.js";import{MessageResponse}from"#client/message-response.js";import{EVE_SESSION_ID_HEADER,isCurrentTurnBoundaryEvent}from"#protocol/message.js";import{normalizeOutputSchemaForRequest}from"#client/output-schema.js";import{isStreamDisconnectError,readNdjsonStream}from"#client/ndjson.js";import{openStreamBody,openStreamIterable}from"#client/open-stream.js";var ClientSession=class{#e;#t;constructor(e,t){this.#e=e,this.#t=t}get state(){return this.#t}async send(e){let t=normalizeSendTurnInput(e),n=this.#t,{continuationToken:r,sessionId:i}=await this.#n(t,n);return new MessageResponse({continuationToken:r,createStream:()=>this.#r(i,r,n,t),sessionId:i})}stream(e){let t=this.#t.sessionId;if(!t)throw Error(`Session has no session ID. Send a message first.`);return this.#a(t,e)}async#n(n,r){let a=r.sessionId?createEveContinueSessionRoutePath(r.sessionId):EVE_CREATE_SESSION_ROUTE_PATH,s=createClientUrl(this.#e.host,a),c=await this.#e.resolveHeaders(n.headers);c.set(`content-type`,`application/json`);let l=createHandleMessageBody({input:n,outputSchema:normalizeOutputSchemaForRequest(n.outputSchema),session:r});if(l===null)throw Error(`Session.send requires a non-empty message, inputResponses, or both.`);let u=await postTurnWithRetry({body:JSON.stringify(l),headers:c,mustDeliver:(n.inputResponses?.length??0)>0,redirect:this.#e.redirect,signal:n.signal,url:s}),d=await u.json(),f=(typeof d.sessionId==`string`?d.sessionId:void 0)??u.headers.get(EVE_SESSION_ID_HEADER)?.trim()??r.sessionId;if(!f)throw Error(`Message route did not return a session id.`);return{continuationToken:typeof d.continuationToken==`string`?d.continuationToken:void 0,sessionId:f}}async*#r(e,t,n,i){let a=[];try{let t=n.sessionId===e?n.streamIndex:0,r=this.#e.maxReconnectAttempts;for(;;){let n=await this.#i(e,t,i.signal,i.headers),o=!1;try{for await(let e of readNdjsonStream(n))if(a.push(e),t+=1,yield e,isCurrentTurnBoundaryEvent(e)){o=!0;break}}catch(e){if(!isStreamDisconnectError(e))throw e}if(o||i.signal?.aborted||r<=0)break;--r}}finally{this.#t=advanceSession({continuationToken:t,events:a,preserveCompletedSessions:this.#e.preserveCompletedSessions,sessionId:e,session:n})}}async#i(e,t,n,r){return await openStreamBody({host:this.#e.host,resolveHeaders:()=>this.#e.resolveHeaders(r),redirect:this.#e.redirect,sessionId:e,signal:n,startIndex:t})}async*#a(e,t){let n=this.#t,i=t?.startIndex??n.streamIndex,a=[];try{for await(let n of openStreamIterable({host:this.#e.host,maxReconnectAttempts:this.#e.maxReconnectAttempts,resolveHeaders:()=>this.#e.resolveHeaders(),redirect:this.#e.redirect,sessionId:e,signal:t?.signal,startIndex:i}))a.push(n),yield n}finally{i>=0&&(this.#t=advanceSession({continuationToken:n.continuationToken,events:a,preserveCompletedSessions:this.#e.preserveCompletedSessions,session:{...n,sessionId:e,streamIndex:i},sessionId:e}))}}};async function postTurnWithRetry(e){let t=e.mustDeliver?10:1,r,i,a;for(let o=0;o<t;o+=1){let s=await fetch(e.url,{body:e.body,headers:e.headers,method:`POST`,redirect:e.redirect,signal:e.signal??null});if(s.ok)return s;if(r=s.status,i=await s.text(),a=s.headers,!isRetryableDeliveryFailure(s.status,i))throw new ClientError(s.status,i,s.headers);o<t-1&&await sleep(200)}throw new ClientError(r??0,i??`Failed to deliver session turn.`,a)}function isRetryableDeliveryFailure(e,t){return e===500&&/target session was not found/i.test(t)}async function sleep(e){await new Promise(t=>setTimeout(t,e))}function normalizeSendTurnInput(e){return typeof e==`string`?{message:e}:e}function createHandleMessageBody(e){let t={};return e.input.message!==void 0&&(t.message=e.input.message),e.input.inputResponses!==void 0&&e.input.inputResponses.length>0&&(t.inputResponses=e.input.inputResponses),e.input.clientContext!==void 0&&(t.clientContext=e.input.clientContext),e.outputSchema!==void 0&&(t.outputSchema=e.outputSchema),e.session.continuationToken!==void 0&&(t.continuationToken=e.session.continuationToken),Object.keys(t).length===0||e.session.continuationToken===void 0&&t.message===void 0||e.session.continuationToken!==void 0&&t.message===void 0&&t.inputResponses===void 0?null:t}export{ClientSession};
+import{EVE_CREATE_SESSION_ROUTE_PATH,createEveCancelTurnRoutePath,createEveContinueSessionRoutePath}from"#protocol/routes.js";import{ClientError}from"#client/client-error.js";import{advanceSession}from"#client/session-utils.js";import{createClientUrl}from"#client/url.js";import{MessageResponse}from"#client/message-response.js";import{EVE_SESSION_ID_HEADER,isCurrentTurnBoundaryEvent}from"#protocol/message.js";import{normalizeOutputSchemaForRequest}from"#client/output-schema.js";import{isStreamDisconnectError,readNdjsonStream}from"#client/ndjson.js";import{CancelTurnResponseSchema}from"#protocol/cancel-turn.js";import{openStreamBody,openStreamIterable}from"#client/open-stream.js";var ClientSession=class{#e;#t;constructor(e,t){this.#e=e,this.#t=t}get state(){return this.#t}async send(e){let t=normalizeSendTurnInput(e),n=this.#t,{continuationToken:r,sessionId:i}=await this.#n(t,n);return this.#t===n&&(this.#t={...n,sessionId:i}),new MessageResponse({continuationToken:r,createStream:()=>this.#r(i,r,n,t),sessionId:i})}async cancel(e){let n=this.#t.sessionId;if(!n)throw Error(`Session has no session ID. Send a message first.`);let i=createClientUrl(this.#e.host,createEveCancelTurnRoutePath(n)),o=await this.#e.resolveHeaders();o.set(`content-type`,`application/json`);let s=await fetch(i,withRedirectPolicy({headers:o,method:`POST`,body:e?JSON.stringify(e):void 0},this.#e.redirect)),c=await s.text();if(!s.ok)throw new ClientError(s.status,c,s.headers);let l;try{l=JSON.parse(c)}catch{throw Error(`Cancel route returned invalid JSON (${s.status}).`)}let u=CancelTurnResponseSchema.safeParse(l);if(!u.success||u.data.sessionId!==n)throw Error(`Cancel route returned an invalid response (${s.status}).`);return{sessionId:u.data.sessionId,status:u.data.status}}stream(e){let t=this.#t.sessionId;if(!t)throw Error(`Session has no session ID. Send a message first.`);return this.#a(t,e)}async#n(t,r){let i=r.sessionId?createEveContinueSessionRoutePath(r.sessionId):EVE_CREATE_SESSION_ROUTE_PATH,o=createClientUrl(this.#e.host,i),c=await this.#e.resolveHeaders(t.headers);c.set(`content-type`,`application/json`);let u=createHandleMessageBody({input:t,outputSchema:normalizeOutputSchemaForRequest(t.outputSchema),session:r});if(u===null)throw Error(`Session.send requires a non-empty message, inputResponses, or both.`);let d=await postTurnWithRetry({body:JSON.stringify(u),headers:c,mustDeliver:(t.inputResponses?.length??0)>0,redirect:this.#e.redirect,signal:t.signal,url:o}),f=await d.json(),p=(typeof f.sessionId==`string`?f.sessionId:void 0)??d.headers.get(EVE_SESSION_ID_HEADER)?.trim()??r.sessionId;if(!p)throw Error(`Message route did not return a session id.`);return{continuationToken:typeof f.continuationToken==`string`?f.continuationToken:void 0,sessionId:p}}async*#r(e,t,n,r){let a=[];try{let t=n.sessionId===e?n.streamIndex:0,i=this.#e.maxReconnectAttempts;for(;;){let n=await this.#i(e,t,r.signal,r.headers),o=!1;try{for await(let e of readNdjsonStream(n))if(a.push(e),t+=1,yield e,isCurrentTurnBoundaryEvent(e)){o=!0;break}}catch(e){if(!isStreamDisconnectError(e))throw e}if(o||r.signal?.aborted||i<=0)break;--i}}finally{this.#t=advanceSession({continuationToken:t,events:a,preserveCompletedSessions:this.#e.preserveCompletedSessions,sessionId:e,session:n})}}async#i(e,t,n,r){return await openStreamBody({host:this.#e.host,resolveHeaders:()=>this.#e.resolveHeaders(r),redirect:this.#e.redirect,sessionId:e,signal:n,startIndex:t})}async*#a(e,t){let n=this.#t,r=t?.startIndex??n.streamIndex,a=[];try{for await(let n of openStreamIterable({host:this.#e.host,maxReconnectAttempts:this.#e.maxReconnectAttempts,resolveHeaders:()=>this.#e.resolveHeaders(),redirect:this.#e.redirect,sessionId:e,signal:t?.signal,startIndex:r}))a.push(n),yield n}finally{r>=0&&(this.#t=advanceSession({continuationToken:n.continuationToken,events:a,preserveCompletedSessions:this.#e.preserveCompletedSessions,session:{...n,sessionId:e,streamIndex:r},sessionId:e}))}}};async function postTurnWithRetry(e){let t=e.mustDeliver?10:1,n,i,a;for(let o=0;o<t;o+=1){let s=await fetch(e.url,{body:e.body,headers:e.headers,method:`POST`,redirect:e.redirect,signal:e.signal??null});if(s.ok)return s;if(n=s.status,i=await s.text(),a=s.headers,!isRetryableDeliveryFailure(s.status,i))throw new ClientError(s.status,i,s.headers);o<t-1&&await sleep(200)}throw new ClientError(n??0,i??`Failed to deliver session turn.`,a)}function isRetryableDeliveryFailure(e,t){return e===500&&/target session was not found/i.test(t)}async function sleep(e){await new Promise(t=>setTimeout(t,e))}function normalizeSendTurnInput(e){return typeof e==`string`?{message:e}:e}function createHandleMessageBody(e){let t={};return e.input.message!==void 0&&(t.message=e.input.message),e.input.inputResponses!==void 0&&e.input.inputResponses.length>0&&(t.inputResponses=e.input.inputResponses),e.input.clientContext!==void 0&&(t.clientContext=e.input.clientContext),e.outputSchema!==void 0&&(t.outputSchema=e.outputSchema),e.session.continuationToken!==void 0&&(t.continuationToken=e.session.continuationToken),Object.keys(t).length===0||e.session.continuationToken===void 0&&t.message===void 0||e.session.continuationToken!==void 0&&t.message===void 0&&t.inputResponses===void 0?null:t}function withRedirectPolicy(e,t){return t===void 0?e:{...e,redirect:t}}export{ClientSession};

package/dist/src/client/types.d.ts

@@ -1,6 +1,7 @@
 import type { UserContent } from "ai";
 import type { StandardJSONSchemaV1 } from "#compiled/@standard-schema/spec/index.js";
 import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import type { CancelTurnStatus } from "#protocol/cancel-turn.js";
 import type { InputRequest, InputResponse } from "#runtime/input/types.js";
 import type { JsonObject } from "#shared/json.js";
 export type { AgentInfoChannelEntry, AgentInfoChannels, AgentInfoConnectionEntry, AgentInfoDynamicResolverEntry, AgentInfoEntry, AgentInfoFrameworkChannelEntry, AgentInfoFrameworkToolEntry, AgentInfoHookEntry, AgentInfoInstructions, AgentInfoInstructionsEntry, AgentInfoResult, AgentInfoSandboxEntry, AgentInfoScheduleEntry, AgentInfoSkillEntry, AgentInfoSource, AgentInfoSubagentEntry, AgentInfoToolEntry, AgentInfoTools, } from "./agent-info-schema.js";
@@ -147,6 +148,13 @@ export interface StreamOptions {
      */
     readonly signal?: AbortSignal;
 }
+/** Result of requesting cancellation for a client session's active turn. */
+export interface CancelSessionResult {
+    /** Session whose active turn was targeted. */
+    readonly sessionId: string;
+    /** Both outcomes are successful; `no_active_turn` means there was nothing left to cancel. */
+    readonly status: CancelTurnStatus;
+}
 /**
  * Aggregated result of one message turn, returned by
  * {@link MessageResponse.result}.

package/dist/src/compiled/.vendor-stamp.json

@@ -28,12 +28,12 @@
     "@vercel/detect-agent": "1.2.3",
     "@vercel/oidc": "3.5.0",
     "@vercel/sandbox": "2.3.0",
-    "@workflow/core": "5.0.0-beta.34",
-    "@workflow/errors": "5.0.0-beta.10",
+    "@workflow/core": "5.0.0-beta.35",
+    "@workflow/errors": "5.0.0-beta.11",
     "@workflow/serde": "5.0.0-beta.2",
-    "@workflow/world": "5.0.0-beta.20",
-    "@workflow/world-local": "5.0.0-beta.28",
-    "@workflow/world-vercel": "5.0.0-beta.30",
+    "@workflow/world": "5.0.0-beta.21",
+    "@workflow/world-local": "5.0.0-beta.29",
+    "@workflow/world-vercel": "5.0.0-beta.31",
     "zod": "4.4.3",
     "zod-validation-error": "5.0.0"
   },

package/dist/src/compiled/@workflow/core/index.js

@@ -1,2 +1,2 @@
-import{c as e,i as t}from"../../_chunks/workflow/dist-DpDDcpTl.js";import{An as n,C as r,Cn as i,Dn as a,En as o,Mn as s,R as c,T as l,Tn as u,fn as d,h as f,jn as p,mn as m,pn as h,t as g,z as _}from"../../_chunks/workflow/attribute-changes-MGTOG_uX.js";import"../../_chunks/workflow/dist-Blxnyb7-.js";import{n as v}from"../../_chunks/workflow/resume-hook-DHP5ql3-.js";import{t as y}from"../../_chunks/workflow/sleep-uA9pS-PT.js";function b(e){p(`createHook()`,`https://workflow-sdk.dev/docs/api-reference/workflow/create-hook`,b)}function x(e){p(`createWebhook()`,`https://workflow-sdk.dev/docs/api-reference/workflow/create-webhook`,x)}function S({schema:e}={}){function t(e){p(`defineHook().create()`,`https://workflow-sdk.dev/docs/api-reference/workflow/define-hook`,t)}return{create:t,async resume(t,n){if(!e?.[`~standard`])return await v(t,n);let r=e[`~standard`].validate(n);if(r instanceof Promise&&(r=await r),r.issues){let e=r.issues.map(e=>{let t=e.path?.map(e=>String(typeof e==`object`&&e?e.key:e)).join(`.`);return t?`  at "${t}": ${e.message}`:`  ${e.message}`});throw Error(`Hook payload did not match the defined schema:\n${e.join(`
-`)}`)}return await v(t,r.value)}}}async function C(e,n={}){let r=_.getStore(),a=r?.workflowMetadata?.workflowRunId;if(!a)throw new t(`setAttributes() must be called from a 'use workflow' or 'use step' function. Calling it from plain host code is not supported.`);let o=g(e,n);if(o.length!==0){if(r.runReadyBarrier)try{await r.runReadyBarrier}catch{}await(await i()).events.create(a,{eventType:`attr_set`,specVersion:5,eventData:{changes:o,writer:{type:`step`,stepId:r.stepMetadata.stepId,attempt:r.stepMetadata.attempt},...n.allowReservedAttributes===!0?{allowReservedAttributes:!0}:{}}})}}const w=C;function T(){let e=_.getStore();return e||n(`getStepMetadata()`,`https://workflow-sdk.dev/docs/api-reference/workflow/get-step-metadata`,T),e.stepMetadata}function E(){let e=_.getStore();return e||s(`getWorkflowMetadata()`,`https://workflow-sdk.dev/docs/api-reference/workflow/get-workflow-metadata`,E),e.workflowMetadata}function D(e={}){let t=_.getStore();t||s(`getWritable()`,`https://workflow-sdk.dev/docs/api-reference/workflow/get-writable`,D);let{namespace:n}=e,i=t.workflowMetadata.workflowRunId,p=c(i,n),g=t.writables??=new Map,v=g.get(p);if(v)return v.writable;let y=l(r(globalThis,t.ops,i,t.encryptionKey,!0,t.runReadyBarrier),t.encryptionKey),b=new f(i,p,t.runReadyBarrier),x=u();return t.ops.push(x.promise),o(y.readable,b,x).catch(()=>{}),a(y.writable,x),Object.defineProperty(y.writable,d,{value:p,writable:!1}),Object.defineProperty(y.writable,m,{value:i,writable:!1}),t.workflowDeploymentId&&Object.defineProperty(y.writable,h,{value:t.workflowDeploymentId,writable:!1}),g.set(p,{writable:y.writable,state:x}),y.writable}export{t as FatalError,e as RetryableError,b as createHook,x as createWebhook,S as defineHook,w as experimental_setAttributes,T as getStepMetadata,E as getWorkflowMetadata,D as getWritable,C as setAttributes,y as sleep};
+import{i as e,l as t}from"../../_chunks/workflow/dist-BYo8Gno2.js";import{An as n,B as r,D as i,Dn as a,Fn as o,In as s,Pn as c,T as l,V as u,_ as d,_n as f,gn as p,jn as m,kn as h,t as g,vn as _}from"../../_chunks/workflow/attribute-changes-DXbmITuI.js";import"../../_chunks/workflow/dist-CSfKNxQW.js";import{n as v}from"../../_chunks/workflow/resume-hook-DvvgYsRt.js";import{t as y}from"../../_chunks/workflow/sleep-DzxrwWTs.js";function b(e){o(`createHook()`,`https://workflow-sdk.dev/docs/api-reference/workflow/create-hook`,b)}function x(e){o(`createWebhook()`,`https://workflow-sdk.dev/docs/api-reference/workflow/create-webhook`,x)}function S({schema:e}={}){function t(e){o(`defineHook().create()`,`https://workflow-sdk.dev/docs/api-reference/workflow/define-hook`,t)}return{create:t,async resume(t,n){if(!e?.[`~standard`])return await v(t,n);let r=e[`~standard`].validate(n);if(r instanceof Promise&&(r=await r),r.issues){let e=r.issues.map(e=>{let t=e.path?.map(e=>String(typeof e==`object`&&e?e.key:e)).join(`.`);return t?`  at "${t}": ${e.message}`:`  ${e.message}`});throw Error(`Hook payload did not match the defined schema:\n${e.join(`
+`)}`)}return await v(t,r.value)}}}async function C(t,n={}){let r=u.getStore(),i=r?.workflowMetadata?.workflowRunId;if(!i)throw new e(`setAttributes() must be called from a 'use workflow' or 'use step' function. Calling it from plain host code is not supported.`);let o=g(t,n);if(o.length!==0){if(r.runReadyBarrier)try{await r.runReadyBarrier}catch{}await(await a()).events.create(i,{eventType:`attr_set`,specVersion:5,eventData:{changes:o,writer:{type:`step`,stepId:r.stepMetadata.stepId,attempt:r.stepMetadata.attempt},...n.allowReservedAttributes===!0?{allowReservedAttributes:!0}:{}}})}}const w=C;function T(){let e=u.getStore();return e||c(`getStepMetadata()`,`https://workflow-sdk.dev/docs/api-reference/workflow/get-step-metadata`,T),e.stepMetadata}function E(){let e=u.getStore();return e||s(`getWorkflowMetadata()`,`https://workflow-sdk.dev/docs/api-reference/workflow/get-workflow-metadata`,E),e.workflowMetadata}function D(e={}){let t=u.getStore();t||s(`getWritable()`,`https://workflow-sdk.dev/docs/api-reference/workflow/get-writable`,D);let{namespace:a}=e,o=t.workflowMetadata.workflowRunId,c=r(o,a),g=t.writables??=new Map,v=g.get(c);if(v)return v.writable;let y=i(l(globalThis,t.ops,o,t.encryptionKey,!0,t.runReadyBarrier),t.encryptionKey),b=new d(o,c,t.runReadyBarrier),x=h();return t.ops.push(x.promise),n(y.readable,b,x).catch(()=>{}),m(y.writable,x),Object.defineProperty(y.writable,p,{value:c,writable:!1}),Object.defineProperty(y.writable,_,{value:o,writable:!1}),t.workflowDeploymentId&&Object.defineProperty(y.writable,f,{value:t.workflowDeploymentId,writable:!1}),g.set(c,{writable:y.writable,state:x}),y.writable}export{e as FatalError,t as RetryableError,b as createHook,x as createWebhook,S as defineHook,w as experimental_setAttributes,T as getStepMetadata,E as getWorkflowMetadata,D as getWritable,C as setAttributes,y as sleep};

package/dist/src/compiled/@workflow/core/runtime/helpers.d.ts

@@ -72,6 +72,61 @@ export declare function loadWorkflowRunEvents(runId: string, afterCursor?: strin
     events: Event[];
     cursor: string | null;
 }>;
+/**
+ * Maximum number of times a replay-context event creation will reload the
+ * event log and retry after the backend rejects it as stale (412). After this
+ * many failed reloads the precondition error propagates so the run is
+ * re-invoked from the queue with a fresh replay.
+ */
+export declare const PRECONDITION_MAX_RELOAD_RETRIES = 2;
+/**
+ * A mutable view of the runtime's in-memory event log. `withPreconditionRetry`
+ * appends freshly-loaded events to `events` (in place) and advances `cursor`
+ * when it reloads, so the caller's loaded snapshot stays current.
+ */
+export interface MutableEventLog {
+    events: Event[];
+    cursor: string | null;
+}
+/**
+ * Whether the optimistic-concurrency guard for event creation is enabled
+ * (`WORKFLOW_PRECONDITION_GUARD=1`, set where the runtime executes). Off by
+ * default: replay-context creates only send a `stateUpdatedAt` snapshot (and
+ * can therefore be rejected with 412 by the backend) when it is enabled.
+ */
+export declare function isPreconditionGuardEnabled(): boolean;
+/**
+ * The `stateUpdatedAt` value to send with a replay-context event creation: the
+ * ULID time (epoch ms) of the latest event the runtime has loaded. Events are
+ * stored in ascending order, so the last one is the newest. Returns `undefined`
+ * when there are no events or the latest id is not a decodable ULID.
+ *
+ * Granularity: snapshots are epoch-milliseconds, and the backend allows an
+ * equal-timestamp snapshot (an up-to-date client must not be rejected). Two
+ * out-of-band events landing in the same millisecond where only the first was
+ * loaded therefore pass the guard undetected — the guard is best-effort by
+ * design, and fails open rather than livelocking.
+ */
+export declare function latestEventStateUpdatedAt(events: Event[]): number | undefined;
+/**
+ * The `stateUpdatedAt` to attach to a replay-context event creation:
+ * the loaded snapshot's ULID time when the precondition guard is enabled,
+ * `undefined` (no guard, backend behaves as before) otherwise.
+ */
+export declare function stateUpdatedAtForCreate(events: Event[]): number | undefined;
+/**
+ * Runs a replay-context event creation with the optimistic-concurrency guard.
+ *
+ * `op` receives the current `stateUpdatedAt` (the ULID time of the latest
+ * loaded event) to pass to `world.events.create`. If the backend rejects the
+ * creation as stale (`PreconditionFailedError` / 412), the event log is
+ * reloaded to completion from the last cursor, merged into `log` in place, and
+ * `op` is retried with the now-newer snapshot — up to
+ * `PRECONDITION_MAX_RELOAD_RETRIES` times. If it still fails, the error is
+ * rethrown so the run falls back to a queue re-invocation. Non-precondition
+ * errors are rethrown immediately.
+ */
+export declare function withPreconditionRetry<T>(runId: string, log: MutableEventLog, op: (stateUpdatedAt: number | undefined) => Promise<T>): Promise<T>;
 /**
  * Wraps a request/response handler and adds a health check "mode"
  * based on the presence of a `__health` query parameter.

package/dist/src/compiled/@workflow/core/runtime/run-id-time.d.ts

@@ -2,6 +2,15 @@
  * Extracts the run's creation timestamp (epoch milliseconds) from a `wrun_`
  * run ID by decoding the embedded ULID time component.
  *
+ * `@workflow/world-vercel`'s region-tagged run IDs mark an ID as carrying
+ * metadata by setting the most-significant bit of the ULID's 48-bit
+ * timestamp, which would otherwise skew the decoded time past the year 6400.
+ * The tag-bit handling is delegated to the scheme's own codec —
+ * `decode()` returns the ULID with the tag bit cleared — so if the tagged
+ * layout ever evolves (the scheme carries a 5-bit version field for exactly
+ * that), this anchor keeps tracking the codec instead of silently diverging.
+ * For untagged input `decode()` is a passthrough.
+ *
  * Returns `undefined` when `runId` is not a decodable `wrun_<ulid>` (e.g. a
  * legacy/non-ULID id, or a test fixture like `wrun_test`); callers fall back to
  * an authoritative timestamp from the run snapshot (`createdAt`) in that case.

package/dist/src/compiled/@workflow/core/runtime/step-executor.d.ts

@@ -8,6 +8,8 @@ export interface StepExecutorParams {
     workflowDeploymentId?: string;
     workflowName: string;
     workflowStartedAt: number;
+    /** Root run id of this run's lineage, carried into the step context. */
+    rootRunId?: string;
     stepId: string;
     stepName: string;
     encryptionKey?: CryptoKey;

package/dist/src/compiled/@workflow/core/runtime/step-latency.d.ts

@@ -1,13 +1,21 @@
 import type { Event } from '#compiled/@workflow/world/index.js';
 /**
- * Client-side latency measurement (TTFS / STSO) threaded from the
+ * Client-side latency measurement (TTFS / STSO / RSFS) threaded from the
  * orchestrator's inline execution path into `executeStep`.
  *
  * TTFS (time-to-first-step) measures run creation → the first step's body
  * beginning to execute. STSO (step-to-step overhead) measures the previous
- * step's terminal event → the next step's body beginning to execute. Both are
- * attached to the step's terminal event so a backend can emit latency metrics
- * from the event write alone, without extra event-log queries.
+ * step's terminal event → the next step's body beginning to execute. RSFS
+ * (run-started-to-first-step) measures the `run_started` response landing →
+ * the first step's start POST being issued — a sub-window of TTFS that
+ * isolates replay overhead from the run-creation queue hop; `finalSchedulingReplay`
+ * is the synchronous workflow-function-execution duration of only the FINAL
+ * replay pass within that window (the pass that reached and scheduled the
+ * first step) — it is NOT accumulated across earlier pre-first-step passes
+ * (see {@link StepLatencyTracking.replayMs}), so it must not be read as "the
+ * replay portion of RSFS". All are attached to the step's terminal
+ * event so a backend can emit latency metrics from the event write alone,
+ * without extra event-log queries.
  *
  * Eligibility is decided by the orchestrator (which owns the event log) via
  * {@link computeStepLatencyTracking}; the final values are computed by
@@ -49,6 +57,36 @@ export interface StepLatencyTracking {
     stepCount?: number;
     /** Number of events already in the event log. */
     eventCount?: number;
+    /**
+     * Epoch ms the `run_started` response was received/parsed by the SDK.
+     * Present only when the step qualifies for RSFS — the same eligibility as
+     * TTFS (see {@link computeStepLatencyTracking}), plus a recoverable
+     * anchor. In turbo mode, `run_started` is backgrounded rather than
+     * awaited, so this is stamped at the point the runtime synthesizes the
+     * run locally and begins replay instead of at the real response; the
+     * first step's start POST is still chained on the real `run_started`
+     * promise (see step-executor.ts), so RSFS still ends up measuring the
+     * genuine run_started-to-first-step-POST stretch even though the two
+     * halves overlap under turbo.
+     */
+    rsfsAnchorMs?: number;
+    /**
+     * Wall-clock ms this invocation's synchronous workflow-function replay
+     * took: from calling `runWorkflow` to it throwing the suspension that
+     * scheduled this batch. Excludes awaited network I/O (the suspension's
+     * event commits, the step's own start POST). Present only alongside
+     * `rsfsAnchorMs`.
+     *
+     * This is the FINAL replay pass only — the invocation that reached and
+     * scheduled the first step. Valid RSFS paths can replay more than once
+     * before the first step (e.g. a workflow-body `setAttributes()` detour
+     * replays twice), and a redelivery omits earlier invocations' replay work
+     * entirely; this value is not accumulated across those earlier passes.
+     * Do not read it as "the replay portion of RSFS" — RSFS
+     * ({@link rsfsAnchorMs}) covers the whole run_started-to-first-step
+     * window, this covers only the last pass.
+     */
+    replayMs?: number;
     /** Whether turbo mode is active for this invocation. */
     turbo: boolean;
 }
@@ -58,6 +96,15 @@ export interface StepLatencyEventData {
     stso?: number;
     stepCount?: number;
     eventCount?: number;
+    /** Client-measured run_started → first step's start POST, ms. */
+    rsfs?: number;
+    /**
+     * Client-measured wall-clock ms of the FINAL replay pass that scheduled
+     * the first step (see {@link StepLatencyTracking.replayMs}) — not
+     * accumulated across earlier pre-first-step passes, so it must not be
+     * read as "the replay portion of `rsfs`".
+     */
+    finalSchedulingReplay?: number;
     optimizations?: string[];
 }
 /**
@@ -82,6 +129,19 @@ export declare function computeStepLatencyTracking(params: {
     invocationStartedClean: boolean;
     /** Epoch ms of run creation, if recoverable. Absent disqualifies TTFS. */
     runCreatedAtMs: number | undefined;
+    /**
+     * Epoch ms the `run_started` response was received/parsed by the SDK (or,
+     * under turbo, the instant the run was synthesized locally — see
+     * {@link StepLatencyTracking.rsfsAnchorMs}). Absent disqualifies RSFS.
+     */
+    runStartedReceivedAtMs: number | undefined;
+    /**
+     * Wall-clock ms this suspension's `runWorkflow` call spent executing
+     * synchronously before throwing — the FINAL replay pass only, not
+     * accumulated across earlier passes. See
+     * {@link StepLatencyTracking.replayMs}.
+     */
+    replayMs: number;
     /** See {@link StepLatencyTracking.preStepBlockingMs}. */
     preStepBlockingMs: number;
     /**
@@ -122,6 +182,12 @@ export declare function computeStepLatencyEventData(params: {
     tracking: StepLatencyTracking | undefined;
     /** `Date.now()` taken immediately before user step code began executing. */
     stepCodeStartedAtMs: number;
+    /**
+     * `Date.now()` taken immediately before the first step's start POST
+     * (`step_started`) was issued. Present only for the lazy inline steps RSFS
+     * cares about; see the call sites in step-executor.ts.
+     */
+    stepStartPostSentAtMs: number | undefined;
     attempt: number;
     /** Whether this step was started lazily (no separate step_created write). */
     lazyStepStart: boolean;

package/dist/src/compiled/@workflow/core/runtime/suspension-handler.d.ts

@@ -1,12 +1,21 @@
 import type { Span } from '#compiled/@opentelemetry/api/index.js';
 import { type SerializedData, type WorkflowRun, type World } from '#compiled/@workflow/world/index.js';
 import type { StepInvocationQueueItem, WorkflowSuspension } from '../global.js';
+import { type MutableEventLog } from './helpers.js';
 export interface SuspensionHandlerParams {
     suspension: WorkflowSuspension;
     world: World;
     run: WorkflowRun;
     span?: Span;
     requestId?: string;
+    /**
+     * The runtime's loaded event log. Each event creation is sent with this
+     * snapshot's `stateUpdatedAt` and, if the backend rejects it as stale (412),
+     * the log is reloaded in place and the create is retried — see
+     * `withPreconditionRetry`. Guarding per-create (rather than the whole
+     * suspension) ensures a retry never re-issues an already-created event.
+     */
+    eventLog?: MutableEventLog;
     /**
      * Turbo mode only: a promise that resolves once the backgrounded
      * `run_started` has landed (the run exists). When present, every world write
@@ -94,5 +103,5 @@ export interface SuspensionHandlerResult {
  * 1. Hooks are processed first to prevent race conditions with webhook receivers
  * 2. Step events and wait events are created in parallel
  */
-export declare function handleSuspension({ suspension, world, run, span, requestId, runReadyBarrier, }: SuspensionHandlerParams): Promise<SuspensionHandlerResult>;
+export declare function handleSuspension({ suspension, world, run, span, requestId, eventLog, runReadyBarrier, }: SuspensionHandlerParams): Promise<SuspensionHandlerResult>;
 //# sourceMappingURL=suspension-handler.d.ts.map