rivetkit 2.3.11 → 2.3.12-rc.2

package/dist/tsup/workflow/mod.d.cts

@@ -1,9 +1,9 @@
 import { WorkflowErrorEvent } from '@rivetkit/workflow-engine';
 export { Loop, TryBlockCatchKind, TryBlockConfig, TryBlockFailure, TryBlockResult, TryStepCatchKind, TryStepConfig, TryStepFailure, TryStepResult, WorkflowError, WorkflowErrorEvent } from '@rivetkit/workflow-engine';
-import { E as EventSchemaConfig, Q as QueueSchemaConfig, h as RunContext } from '../config-DTGoWdkG.cjs';
+import { E as EventSchemaConfig, Q as QueueSchemaConfig, h as RunContext } from '../config-BXSV17G7.cjs';
 import { A as AnyDatabaseProvider } from '../config-ey2I2zz5.cjs';
-import { d as WorkflowContext } from '../context-C6cvDNyk.cjs';
-export { e as WorkflowBranchConfig, W as WorkflowBranchContextOf, a as WorkflowContextOf, f as WorkflowLoopConfig, b as WorkflowLoopContextOf, g as WorkflowStepConfig, h as WorkflowStepContext, c as WorkflowStepContextOf, i as WorkflowTryConfig, j as WorkflowTryStepConfig } from '../context-C6cvDNyk.cjs';
+import { d as WorkflowContext } from '../context-4fJemY0D.cjs';
+export { e as WorkflowBranchConfig, W as WorkflowBranchContextOf, a as WorkflowContextOf, f as WorkflowLoopConfig, b as WorkflowLoopContextOf, g as WorkflowStepConfig, h as WorkflowStepContext, c as WorkflowStepContextOf, i as WorkflowTryConfig, j as WorkflowTryStepConfig } from '../context-4fJemY0D.cjs';
 import 'zod/v4';
 import '@rivetkit/rivetkit-wasm';
 import 'zod';
@@ -11,9 +11,9 @@ import 'pino';
 import '@rivetkit/virtual-websocket';
 import '../inspector/workflow.cjs';
 import '@standard-schema/spec';
-import '../utils-DQDCphrl.cjs';
+import '../utils-Bbz-3411.cjs';
 import 'hono';
-import '../utils-CqDnC_PS.cjs';
+import '../utils-vvJQyygr.cjs';
 import 'hono/utils/http-status';
 
 interface WorkflowOptions<TState, TConnParams, TConnState, TVars, TInput, TDatabase extends AnyDatabaseProvider, TEvents extends EventSchemaConfig = Record<never, never>, TQueues extends QueueSchemaConfig = Record<never, never>> {

package/dist/tsup/workflow/mod.d.ts

@@ -1,9 +1,9 @@
 import { WorkflowErrorEvent } from '@rivetkit/workflow-engine';
 export { Loop, TryBlockCatchKind, TryBlockConfig, TryBlockFailure, TryBlockResult, TryStepCatchKind, TryStepConfig, TryStepFailure, TryStepResult, WorkflowError, WorkflowErrorEvent } from '@rivetkit/workflow-engine';
-import { E as EventSchemaConfig, Q as QueueSchemaConfig, h as RunContext } from '../config-C4OSv0QP.js';
+import { E as EventSchemaConfig, Q as QueueSchemaConfig, h as RunContext } from '../config-Bi1r6gI7.js';
 import { A as AnyDatabaseProvider } from '../config-ey2I2zz5.js';
-import { d as WorkflowContext } from '../context-CMygeBxS.js';
-export { e as WorkflowBranchConfig, W as WorkflowBranchContextOf, a as WorkflowContextOf, f as WorkflowLoopConfig, b as WorkflowLoopContextOf, g as WorkflowStepConfig, h as WorkflowStepContext, c as WorkflowStepContextOf, i as WorkflowTryConfig, j as WorkflowTryStepConfig } from '../context-CMygeBxS.js';
+import { d as WorkflowContext } from '../context-D4sNYboo.js';
+export { e as WorkflowBranchConfig, W as WorkflowBranchContextOf, a as WorkflowContextOf, f as WorkflowLoopConfig, b as WorkflowLoopContextOf, g as WorkflowStepConfig, h as WorkflowStepContext, c as WorkflowStepContextOf, i as WorkflowTryConfig, j as WorkflowTryStepConfig } from '../context-D4sNYboo.js';
 import 'zod/v4';
 import '@rivetkit/rivetkit-wasm';
 import 'zod';
@@ -11,9 +11,9 @@ import 'pino';
 import '@rivetkit/virtual-websocket';
 import '../inspector/workflow.js';
 import '@standard-schema/spec';
-import '../utils-CV0akuDD.js';
+import '../utils-BqdWVlzm.js';
 import 'hono';
-import '../utils-CqDnC_PS.js';
+import '../utils-vvJQyygr.js';
 import 'hono/utils/http-status';
 
 interface WorkflowOptions<TState, TConnParams, TConnState, TVars, TInput, TDatabase extends AnyDatabaseProvider, TEvents extends EventSchemaConfig = Record<never, never>, TQueues extends QueueSchemaConfig = Record<never, never>> {

package/dist/tsup/workflow/mod.js

@@ -1,23 +1,23 @@
 import {
   createWorkflowInspectorAdapter
-} from "../chunk-MO2SSUOR.js";
-import "../chunk-5UYWLCRO.js";
-import "../chunk-QFJ24MBU.js";
+} from "../chunk-3JBE7REK.js";
+import "../chunk-6XR7IKBZ.js";
 import {
   ACTOR_CONTEXT_INTERNAL_SYMBOL,
   defineRunHandler
 } from "../chunk-6W5VGLFT.js";
+import "../chunk-KPZQI3TG.js";
 import {
   makeWorkflowKey,
   workflowStoragePrefix
 } from "../chunk-JI6GZ2C2.js";
 import {
   stringifyError
-} from "../chunk-OUENKQHB.js";
+} from "../chunk-YW75TS76.js";
 import {
   RivetError,
   isActorAbortedError
-} from "../chunk-ZZ3WBRPD.js";
+} from "../chunk-IXBD7BXC.js";
 
 // src/workflow/mod.ts
 import {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "rivetkit",
-	"version": "2.3.11",
+	"version": "2.3.12-rc.2",
 	"description": "Lightweight libraries for building stateful actors on edge platforms",
 	"license": "Apache-2.0",
 	"keywords": [
@@ -211,14 +211,14 @@
 		"@hono/zod-openapi": "^1.1.5",
 		"@rivet-dev/agent-os-core": "^0.1.1",
 		"@rivetkit/bare-ts": "^0.6.2",
-		"@rivetkit/engine-cli": "2.3.11",
-		"@rivetkit/engine-envoy-protocol": "2.3.11",
+		"@rivetkit/engine-cli": "2.3.12-rc.2",
+		"@rivetkit/engine-envoy-protocol": "2.3.12-rc.2",
 		"@rivetkit/on-change": "6.0.1",
-		"@rivetkit/rivetkit-napi": "2.3.11",
-		"@rivetkit/rivetkit-wasm": "2.3.11",
-		"@rivetkit/traces": "2.3.11",
-		"@rivetkit/virtual-websocket": "2.3.11",
-		"@rivetkit/workflow-engine": "2.3.11",
+		"@rivetkit/rivetkit-napi": "2.3.12-rc.2",
+		"@rivetkit/rivetkit-wasm": "2.3.12-rc.2",
+		"@rivetkit/traces": "2.3.12-rc.2",
+		"@rivetkit/virtual-websocket": "2.3.12-rc.2",
+		"@rivetkit/workflow-engine": "2.3.12-rc.2",
 		"cbor-x": "^1.6.0",
 		"drizzle-orm": "^0.44.2",
 		"hono": "^4.7.0",

package/src/actor/errors.ts

@@ -12,6 +12,8 @@ export interface RivetErrorOptions extends ErrorOptions {
 	public?: boolean;
 	/** Metadata associated with this error. */
 	metadata?: unknown;
+	/** Request identifier used to correlate this error with engine logs. */
+	rayId?: string;
 	/** Explicit HTTP status override for router responses. */
 	statusCode?: number;
 	/** Actor context associated with this error. */
@@ -31,6 +33,7 @@ export interface RivetErrorLike {
 	code: string;
 	message: string;
 	metadata?: unknown;
+	rayId?: string;
 	public?: boolean;
 	statusCode?: number;
 	actor?: ActorSpecifier;
@@ -38,6 +41,14 @@ export interface RivetErrorLike {
 
 export interface BridgeRivetErrorPayload extends RivetErrorLike {}
 
+/**
+ * Shape as it arrives from the native bridge, where an absent ray ID serializes
+ * to null. Normalized to a BridgeRivetErrorPayload before validation.
+ */
+interface NativeBridgeErrorPayload extends Omit<BridgeRivetErrorPayload, "rayId"> {
+	rayId?: string | null;
+}
+
 export interface UserErrorOptions extends ErrorOptions {
 	/**
 	 * Machine readable code for this error. Useful for catching different types of
@@ -59,6 +70,7 @@ function looksLikeRivetErrorOptions(
 		value !== null &&
 		("public" in value ||
 			"metadata" in value ||
+			"rayId" in value ||
 			"statusCode" in value ||
 			"actor" in value ||
 			"cause" in value)
@@ -94,6 +106,9 @@ export function isRivetErrorLike(
 		typeof error.code === "string" &&
 		"message" in error &&
 		typeof error.message === "string" &&
+		(!("rayId" in error) ||
+			error.rayId === undefined ||
+			typeof error.rayId === "string") &&
 		(!("__type" in error) || isTypedErrorTag(error.__type))
 	);
 }
@@ -128,6 +143,7 @@ export class RivetError extends Error {
 
 	public public: boolean;
 	public metadata?: unknown;
+	public readonly rayId?: string;
 	public statusCode: number;
 	public actor?: ActorSpecifier;
 	public readonly group: string;
@@ -161,6 +177,7 @@ export class RivetError extends Error {
 		this.code = code;
 		this.public = normalized.public ?? false;
 		this.metadata = normalized.metadata;
+		this.rayId = normalized.rayId ?? undefined;
 		this.statusCode = normalized.statusCode ?? (this.public ? 400 : 500);
 		this.actor = normalized.actor;
 	}
@@ -205,6 +222,7 @@ export function toRivetError(
 			public: error.public,
 			statusCode: error.statusCode,
 			metadata: error.metadata,
+			rayId: error.rayId,
 			actor: error.actor,
 			cause: error instanceof Error ? error.cause : undefined,
 		});
@@ -218,6 +236,7 @@ export function toRivetError(
 			public: fallback?.public,
 			statusCode: fallback?.statusCode,
 			metadata: fallback?.metadata,
+			rayId: fallback?.rayId,
 			actor: fallback?.actor,
 			cause: error instanceof Error ? error : undefined,
 		},
@@ -230,6 +249,7 @@ export function encodeBridgeRivetError(error: RivetErrorLike): string {
 		code: error.code,
 		message: error.message,
 		metadata: error.metadata,
+		rayId: error.rayId,
 		public: error.public,
 		statusCode: error.statusCode,
 		actor: error.actor,
@@ -244,9 +264,14 @@ export function decodeBridgeRivetErrorPayload(
 	}
 
 	try {
-		const payload = JSON.parse(
+		const raw = JSON.parse(
 			value.slice(BRIDGE_RIVET_ERROR_PREFIX.length),
-		) as BridgeRivetErrorPayload;
+		) as NativeBridgeErrorPayload;
+		// Coerce the native bridge's null ray ID to undefined before validation.
+		const payload: BridgeRivetErrorPayload = {
+			...raw,
+			rayId: raw.rayId ?? undefined,
+		};
 		if (!isRivetErrorLike(payload)) {
 			return undefined;
 		}
@@ -272,6 +297,7 @@ export function decodeBridgeRivetError(value: string): RivetError | undefined {
 
 	return new RivetError(payload.group, payload.code, payload.message, {
 		metadata: payload.metadata,
+		rayId: payload.rayId,
 		public: payload.public,
 		statusCode: payload.statusCode,
 		actor: payload.actor ?? undefined,
@@ -303,6 +329,7 @@ export function internalError(
 			public: options?.public,
 			statusCode: options?.statusCode,
 			metadata: options?.metadata,
+			rayId: options?.rayId,
 			actor: options?.actor,
 			cause: options?.cause,
 		},

package/src/client/actor-conn.ts

@@ -874,7 +874,7 @@ export class ActorConnRaw {
 			const parsed = parseWebSocketCloseReason(reason);
 
 			if (parsed) {
-				const { group, code } = parsed;
+				const { group, code, rayId } = parsed;
 
 				if (this.#shouldReconnectForStaleActor(group, code)) {
 					this.#clearResolvedActorIdentity();
@@ -883,7 +883,7 @@ export class ActorConnRaw {
 							group,
 							code,
 							`Connection closed: ${reason}`,
-							undefined,
+							{ rayId },
 						),
 					);
 					return;
@@ -897,6 +897,7 @@ export class ActorConnRaw {
 						this.#actorId,
 						this.#actorResolutionState,
 						this.#driver,
+						rayId,
 					);
 					if (schedulingError) {
 						error = schedulingError;
@@ -905,7 +906,7 @@ export class ActorConnRaw {
 							group,
 							code,
 							`Connection closed: ${reason}`,
-							undefined,
+							{ rayId },
 						);
 					}
 				} else {
@@ -913,7 +914,7 @@ export class ActorConnRaw {
 						group,
 						code,
 						`Connection closed: ${reason}`,
-						undefined,
+						{ rayId },
 					);
 				}
 

package/src/client/actor-handle.ts

@@ -166,7 +166,7 @@ export class ActorHandleRaw {
 						},
 					}).send(name, body, options as any);
 				} catch (err) {
-					const { group, code, message, metadata, actor } =
+					const { group, code, message, metadata, rayId, actor } =
 						deconstructError(err, true);
 
 					if (
@@ -189,6 +189,7 @@ export class ActorHandleRaw {
 							actorId,
 							attempt,
 							maxAttempts,
+							rayId,
 						)
 					) {
 						useQueryTarget = true;
@@ -227,6 +228,7 @@ export class ActorHandleRaw {
 
 					throw new ActorError(group, code, message, {
 						metadata,
+						rayId,
 						actor,
 					});
 				}
@@ -357,7 +359,7 @@ export class ActorHandleRaw {
 				}
 				return output;
 			} catch (err) {
-				const { group, code, message, metadata, actor } =
+				const { group, code, message, metadata, rayId, actor } =
 					deconstructError(err, true);
 
 				if (
@@ -367,6 +369,7 @@ export class ActorHandleRaw {
 						actorId,
 						attempt,
 						maxAttempts,
+						rayId,
 					)
 				) {
 					useQueryTarget = true;
@@ -398,7 +401,7 @@ export class ActorHandleRaw {
 						"actor",
 						"not_found",
 						"The actor does not exist or was destroyed.",
-						{ metadata, actor },
+						{ metadata, rayId, actor },
 					);
 				}
 
@@ -419,7 +422,11 @@ export class ActorHandleRaw {
 					continue;
 				}
 
-				throw new ActorError(group, code, message, { metadata, actor });
+				throw new ActorError(group, code, message, {
+					metadata,
+					rayId,
+					actor,
+				});
 			}
 		}
 
@@ -514,6 +521,7 @@ export class ActorHandleRaw {
 		actorId: string | undefined,
 		attempt: number,
 		maxAttempts: number,
+		rayId?: string,
 	): Promise<boolean> {
 		if (
 			!isDynamicActorQuery(this.#actorResolutionState) ||
@@ -530,6 +538,7 @@ export class ActorHandleRaw {
 				actorId,
 				this.#actorResolutionState,
 				this.#driver,
+				rayId,
 			);
 			if (schedulingError) {
 				throw schedulingError;
@@ -679,7 +688,7 @@ export class ActorHandleRaw {
 				}
 				return response;
 			} catch (err) {
-				const { group, code, message, metadata, actor } =
+				const { group, code, message, metadata, rayId, actor } =
 					deconstructError(err, true);
 
 				if (
@@ -689,6 +698,7 @@ export class ActorHandleRaw {
 						actorId,
 						attempt,
 						maxAttempts,
+						rayId,
 					)
 				) {
 					useQueryTarget = true;
@@ -725,7 +735,11 @@ export class ActorHandleRaw {
 					continue;
 				}
 
-				throw new ActorError(group, code, message, { metadata, actor });
+				throw new ActorError(group, code, message, {
+					metadata,
+					rayId,
+					actor,
+				});
 			}
 		}
 
@@ -750,7 +764,7 @@ export class ActorHandleRaw {
 			return null;
 		}
 
-		const { group, code } = error;
+		const { group, code, rayId } = error;
 
 		if (
 			await this.#shouldRetrySchedulingError(
@@ -759,6 +773,7 @@ export class ActorHandleRaw {
 				actorId,
 				attempt,
 				maxAttempts,
+				rayId,
 			)
 		) {
 			return {
@@ -802,6 +817,7 @@ export class ActorHandleRaw {
 		code: string;
 		message: string;
 		metadata?: unknown;
+		rayId?: string;
 		actor?: ActorSpecifier;
 	} | null> {
 		if (response.ok) {
@@ -814,7 +830,7 @@ export class ActorHandleRaw {
 			: this.#encoding;
 
 		try {
-			return deserializeWithEncoding<
+			const error = deserializeWithEncoding<
 				protocol.HttpResponseError,
 				HttpResponseErrorJson,
 				{
@@ -822,6 +838,7 @@ export class ActorHandleRaw {
 					code: string;
 					message: string;
 					metadata?: unknown;
+					rayId?: string;
 					actor?: ActorSpecifier;
 				}
 			>(
@@ -854,6 +871,10 @@ export class ActorHandleRaw {
 						: undefined,
 				}),
 			);
+			return {
+				...error,
+				rayId: response.headers.get("x-rivet-ray-id") ?? undefined,
+			};
 		} catch {
 			return null;
 		}
@@ -927,7 +948,9 @@ export class ActorHandleRaw {
 				"actor",
 				"reload_failed",
 				`reload failed with status ${response.status}: ${body}`,
-				{},
+				{
+					rayId: response.headers.get("x-rivet-ray-id") ?? undefined,
+				},
 			);
 		}
 	}

package/src/client/actor-query.ts

@@ -67,6 +67,7 @@ export async function checkForSchedulingError(
 	actorId: string,
 	query: ActorQuery,
 	driver: EngineControlClient,
+	rayId?: string,
 ): Promise<ActorSchedulingError | null> {
 	const name = getActorNameFromQuery(query);
 
@@ -79,7 +80,13 @@ export async function checkForSchedulingError(
 				actorId,
 				error: actor.error,
 			});
-			return actorSchedulingError(group, code, actorId, actor.error);
+			return actorSchedulingError(
+				group,
+				code,
+				actorId,
+				actor.error,
+				rayId,
+			);
 		}
 	} catch (err) {
 		logger().warn({

package/src/client/errors.ts

@@ -51,12 +51,13 @@ export function actorSchedulingError(
 	code: string,
 	actorId: string,
 	details: unknown,
+	rayId?: string,
 ): RivetError {
 	return new RivetError(
 		group,
 		code,
 		`Actor failed to start (${actorId}): ${JSON.stringify(details)}`,
-		{ metadata: { actorId, details } },
+		{ metadata: { actorId, details }, rayId },
 	);
 }
 

package/src/client/raw-utils.ts

@@ -99,11 +99,9 @@ export async function rawHttpFetch(
 		return driver.sendRequest(target, proxyRequest, options);
 	} catch (err) {
 		// Standardize to ClientActorError instead of the native backend error
-		const { group, code, message, metadata, actor } = deconstructError(
-			err,
-			true,
-		);
-		throw new ActorError(group, code, message, { metadata, actor });
+		const { group, code, message, metadata, rayId, actor } =
+			deconstructError(err, true);
+		throw new ActorError(group, code, message, { metadata, rayId, actor });
 	}
 }
 

package/src/client/utils.ts

@@ -215,6 +215,7 @@ export async function sendHttpRequest<
 				code: responseData.code,
 				message: responseData.message,
 				metadata: responseData.metadata,
+				rayId,
 				actorId: responseData.actor?.actorId,
 				generation: responseData.actor?.generation,
 				actorKey: responseData.actor?.key,
@@ -226,6 +227,7 @@ export async function sendHttpRequest<
 				responseData.message,
 				{
 					metadata: responseData.metadata,
+					rayId: rayId ?? undefined,
 					actor: responseData.actor,
 				},
 			);

package/src/common/utils.ts

@@ -44,6 +44,7 @@ export interface DeconstructedError {
 	code: string;
 	message: string;
 	metadata?: unknown;
+	rayId?: string;
 	actor?: errors.ActorSpecifier;
 }
 
@@ -80,6 +81,7 @@ export function deconstructError(
 	let code: string;
 	let message: string;
 	let metadata: unknown;
+	let rayId: string | undefined;
 	let actor: errors.ActorSpecifier | undefined;
 	// Structured errors from core or from pre-built `RivetError` instances are canonical.
 	// Only unstructured errors go through the classifier below.
@@ -96,6 +98,7 @@ export function deconstructError(
 		code = error.code;
 		message = error.message;
 		metadata = error.metadata;
+		rayId = error.rayId;
 		actor = error.actor;
 	} else if (errors.ActorError.isActorError(error) && error.public) {
 		// Check if error has statusCode (could be ActorError instance or DeconstructedError)
@@ -107,6 +110,7 @@ export function deconstructError(
 		code = error.code;
 		message = getErrorMessage(error);
 		metadata = error.metadata;
+		rayId = error.rayId;
 		actor = error.actor;
 	} else if (exposeInternalError) {
 		if (errors.ActorError.isActorError(error)) {
@@ -116,6 +120,7 @@ export function deconstructError(
 			code = error.code;
 			message = getErrorMessage(error);
 			metadata = error.metadata;
+			rayId = error.rayId;
 			actor = error.actor;
 		} else {
 			statusCode = 500;
@@ -146,6 +151,7 @@ export function deconstructError(
 		code,
 		message,
 		metadata,
+		rayId,
 		actor,
 	};
 }

package/src/registry/native.ts

@@ -835,6 +835,7 @@ function encodeNativeCallbackError(error: unknown): Error {
 		group: structuredError.group,
 		code: structuredError.code,
 		metadata: structuredError.metadata,
+		rayId: structuredError.rayId,
 	});
 }