rivetkit 2.3.0-rc.8 → 2.3.0

package/src/registry/process-metrics.ts

@@ -11,10 +11,37 @@
  * All data collection happens here in TypeScript. The NAPI bridge is pure
  * type marshalling and the Rust side only registers + stores the metrics.
  */
-import { monitorEventLoopDelay, performance, PerformanceObserver } from "node:perf_hooks";
+import {
+	monitorEventLoopDelay,
+	PerformanceObserver,
+	performance,
+} from "node:perf_hooks";
 import { getHeapStatistics } from "node:v8";
 import * as napi from "@rivetkit/rivetkit-napi";
 
+type OptionalProcessMetricsNapi = typeof napi & {
+	jsObserveGcDuration?: (kind: string, durationSeconds: number) => void;
+	jsSetEventloopHeartbeatTsMs?: (timestampMs: number) => void;
+	jsSetEventloopLagQuantile?: (
+		quantile: string,
+		valueSeconds: number,
+	) => void;
+	jsSetEventloopUtilization?: (utilization: number) => void;
+	jsAddProcessCpuSeconds?: (mode: string, valueSeconds: number) => void;
+	jsSetProcessResidentMemoryBytes?: (bytes: number) => void;
+	jsSetHeapBytes?: (kind: string, bytes: number) => void;
+	jsSetActiveHandles?: (count: number) => void;
+	jsSetActiveRequests?: (count: number) => void;
+};
+
+type GcPerformanceEntry = {
+	duration: number;
+	detail?: { kind?: number };
+	kind?: number;
+};
+
+const processMetricsNapi = napi as OptionalProcessMetricsNapi;
+
 // Some napi process-metrics symbols may be missing on older native binaries
 // (the auto-generated index.js destructures them as `undefined` if the
 // underlying `.node` was built before they were added). Guard each call so
@@ -50,7 +77,9 @@ interface ProcessMetricsState {
 	gcObserver: PerformanceObserver;
 	eventLoopHistogram: ReturnType<typeof monitorEventLoopDelay>;
 	lastCpuUsage: NodeJS.CpuUsage;
-	lastEventLoopUtilization: ReturnType<typeof performance.eventLoopUtilization>;
+	lastEventLoopUtilization: ReturnType<
+		typeof performance.eventLoopUtilization
+	>;
 }
 
 let state: ProcessMetricsState | undefined;
@@ -67,15 +96,17 @@ export function startProcessMetrics(): void {
 
 	const gcObserver = new PerformanceObserver((list) => {
 		for (const entry of list.getEntries()) {
-			const kind =
-				(entry as PerformanceEntry & { detail?: { kind?: number }; kind?: number }).detail
-					?.kind ??
-				(entry as PerformanceEntry & { kind?: number }).kind;
+			const gcEntry = entry as GcPerformanceEntry;
+			const kind = gcEntry.detail?.kind ?? gcEntry.kind;
 			if (typeof kind !== "number") continue;
 			const kindName = GC_KIND_NAMES[kind];
 			if (!kindName) continue;
 			// `entry.duration` is in milliseconds; convert to seconds.
-			callIfFn(napi.jsObserveGcDuration, kindName, entry.duration / 1000);
+			callIfFn(
+				processMetricsNapi.jsObserveGcDuration,
+				kindName,
+				gcEntry.duration / 1000,
+			);
 		}
 	});
 	gcObserver.observe({ entryTypes: ["gc"], buffered: false });
@@ -84,7 +115,7 @@ export function startProcessMetrics(): void {
 	const lastEventLoopUtilization = performance.eventLoopUtilization();
 
 	const heartbeatInterval = setInterval(() => {
-		callIfFn(napi.jsSetEventloopHeartbeatTsMs, Date.now());
+		callIfFn(processMetricsNapi.jsSetEventloopHeartbeatTsMs, Date.now());
 	}, HEARTBEAT_INTERVAL_MS);
 	heartbeatInterval.unref();
 
@@ -108,7 +139,7 @@ export function startProcessMetrics(): void {
 	};
 
 	// Emit one snapshot immediately so freshly-scraped instances have data.
-	callIfFn(napi.jsSetEventloopHeartbeatTsMs, Date.now());
+	callIfFn(processMetricsNapi.jsSetEventloopHeartbeatTsMs, Date.now());
 	try {
 		collectAndPush();
 	} catch {
@@ -134,17 +165,39 @@ function collectAndPush(): void {
 	// nanoseconds; convert to seconds. Reset after reading so the next window
 	// reflects only the new interval.
 	const hist = state.eventLoopHistogram;
-	callIfFn(napi.jsSetEventloopLagQuantile, "p50", hist.percentile(50) / NS_PER_SECOND);
-	callIfFn(napi.jsSetEventloopLagQuantile, "p90", hist.percentile(90) / NS_PER_SECOND);
-	callIfFn(napi.jsSetEventloopLagQuantile, "p99", hist.percentile(99) / NS_PER_SECOND);
-	callIfFn(napi.jsSetEventloopLagQuantile, "max", hist.max / NS_PER_SECOND);
+	callIfFn(
+		processMetricsNapi.jsSetEventloopLagQuantile,
+		"p50",
+		hist.percentile(50) / NS_PER_SECOND,
+	);
+	callIfFn(
+		processMetricsNapi.jsSetEventloopLagQuantile,
+		"p90",
+		hist.percentile(90) / NS_PER_SECOND,
+	);
+	callIfFn(
+		processMetricsNapi.jsSetEventloopLagQuantile,
+		"p99",
+		hist.percentile(99) / NS_PER_SECOND,
+	);
+	callIfFn(
+		processMetricsNapi.jsSetEventloopLagQuantile,
+		"max",
+		hist.max / NS_PER_SECOND,
+	);
 	hist.reset();
 
 	// Event loop utilization delta over the scrape window.
 	const nextElu = performance.eventLoopUtilization();
-	const eluDelta = performance.eventLoopUtilization(nextElu, state.lastEventLoopUtilization);
+	const eluDelta = performance.eventLoopUtilization(
+		nextElu,
+		state.lastEventLoopUtilization,
+	);
 	state.lastEventLoopUtilization = nextElu;
-	callIfFn(napi.jsSetEventloopUtilization, eluDelta.utilization);
+	callIfFn(
+		processMetricsNapi.jsSetEventloopUtilization,
+		eluDelta.utilization,
+	);
 
 	// CPU usage delta. `process.cpuUsage()` returns microseconds.
 	const nextCpu = process.cpuUsage();
@@ -152,19 +205,27 @@ function collectAndPush(): void {
 	const systemDeltaUs = nextCpu.system - state.lastCpuUsage.system;
 	state.lastCpuUsage = nextCpu;
 	if (userDeltaUs > 0) {
-		callIfFn(napi.jsAddProcessCpuSeconds, "user", userDeltaUs / US_PER_SECOND);
+		callIfFn(
+			processMetricsNapi.jsAddProcessCpuSeconds,
+			"user",
+			userDeltaUs / US_PER_SECOND,
+		);
 	}
 	if (systemDeltaUs > 0) {
-		callIfFn(napi.jsAddProcessCpuSeconds, "system", systemDeltaUs / US_PER_SECOND);
+		callIfFn(
+			processMetricsNapi.jsAddProcessCpuSeconds,
+			"system",
+			systemDeltaUs / US_PER_SECOND,
+		);
 	}
 
 	// Memory + heap.
 	const mem = process.memoryUsage();
-	callIfFn(napi.jsSetProcessResidentMemoryBytes, mem.rss);
-	callIfFn(napi.jsSetHeapBytes, "used", mem.heapUsed);
-	callIfFn(napi.jsSetHeapBytes, "total", mem.heapTotal);
+	callIfFn(processMetricsNapi.jsSetProcessResidentMemoryBytes, mem.rss);
+	callIfFn(processMetricsNapi.jsSetHeapBytes, "used", mem.heapUsed);
+	callIfFn(processMetricsNapi.jsSetHeapBytes, "total", mem.heapTotal);
 	const heapLimit = getHeapStatistics().heap_size_limit;
-	callIfFn(napi.jsSetHeapBytes, "limit", heapLimit);
+	callIfFn(processMetricsNapi.jsSetHeapBytes, "limit", heapLimit);
 
 	// libuv active handles + requests. These are unstable Node internals
 	// guarded behind underscore-prefixed names; if a future Node release
@@ -175,9 +236,15 @@ function collectAndPush(): void {
 		_getActiveRequests?: () => unknown[];
 	};
 	if (typeof proc._getActiveHandles === "function") {
-		callIfFn(napi.jsSetActiveHandles, proc._getActiveHandles().length);
+		callIfFn(
+			processMetricsNapi.jsSetActiveHandles,
+			proc._getActiveHandles().length,
+		);
 	}
 	if (typeof proc._getActiveRequests === "function") {
-		callIfFn(napi.jsSetActiveRequests, proc._getActiveRequests().length);
+		callIfFn(
+			processMetricsNapi.jsSetActiveRequests,
+			proc._getActiveRequests().length,
+		);
 	}
 }

package/src/registry/runtime.ts

@@ -1,5 +1,7 @@
+import { stringifyError } from "@/common/utils";
 import type { SqliteNativeMetrics } from "@/common/database/config";
 import type { RegistryConfig } from "./config";
+import { logger } from "./log";
 
 declare const handleBrand: unique symbol;
 
@@ -225,6 +227,22 @@ export interface RuntimeActorConfig {
 	preloadMaxWorkflowBytes?: number;
 	preloadMaxConnectionsBytes?: number;
 	actions?: Array<{ name: string }>;
+	inspectorTabs?: Array<RuntimeInspectorTabEntry>;
+}
+
+export interface RuntimeInspectorTabEntry {
+	id: string;
+	/** Required for custom entries; omitted for built-in hides. */
+	label?: string;
+	/**
+	 * Required for custom entries — absolute path to the source directory.
+	 * Resolved on the TS side before being handed to the runtime.
+	 */
+	source?: string;
+	/** Optional icon id for custom entries. */
+	icon?: string;
+	/** Set to true for built-in hide entries. */
+	hidden?: boolean;
 }
 
 export interface RuntimeServeConfig {
@@ -234,6 +252,8 @@ export interface RuntimeServeConfig {
 	namespace: string;
 	poolName: string;
 	engineBinaryPath?: string;
+	engineHost?: string;
+	enginePort?: number;
 	handleInspectorHttpInRuntime?: boolean;
 	inspectorTestToken?: string;
 	serverlessBasePath?: string;
@@ -257,9 +277,10 @@ export interface RuntimeServerlessResponseHead {
 	headers: Record<string, string>;
 }
 
-export interface RuntimeRegistryDiagnostics {
-	mode: string;
-	envoyActiveActorCount?: number | null;
+export interface RuntimeRegistryRouteResponse {
+	status: number;
+	headers: Record<string, string>;
+	body: RuntimeBytes;
 }
 
 export type RuntimeServerlessStreamEvent =
@@ -319,9 +340,15 @@ export interface CoreRuntime {
 		cancelToken: CancellationTokenHandle,
 		config: RuntimeServeConfig,
 	): Promise<RuntimeServerlessResponseHead>;
-	registryDiagnostics?(
+	registryHealth?(
 		registry: RegistryHandle,
-	): Promise<RuntimeRegistryDiagnostics>;
+	): Promise<RuntimeRegistryRouteResponse>;
+	registryMetadata?(
+		registry: RegistryHandle,
+	): Promise<RuntimeRegistryRouteResponse>;
+	registryMetrics?(
+		registry: RegistryHandle,
+	): Promise<RuntimeRegistryRouteResponse>;
 	createActorFactory(
 		callbacks: object,
 		config?: RuntimeActorConfig | undefined | null,
@@ -392,6 +419,9 @@ export interface CoreRuntime {
 	): void;
 	actorWaitUntil(ctx: ActorContextHandle, promise: Promise<unknown>): void;
 	actorWaitForTrackedShutdownWork(ctx: ActorContextHandle): Promise<boolean>;
+	actorWaitForTrackedShutdownWorkUnbounded(
+		ctx: ActorContextHandle,
+	): Promise<void>;
 	actorKeepAwake(ctx: ActorContextHandle, promise: Promise<unknown>): void;
 	actorBeginKeepAwake(ctx: ActorContextHandle): number;
 	actorEndKeepAwake(ctx: ActorContextHandle, regionId: number): void;
@@ -484,6 +514,7 @@ export interface CoreRuntime {
 		ctx: ActorContextHandle,
 		names: string[],
 		options?: RuntimeQueueWaitOptions | undefined | null,
+		signal?: CancellationTokenHandle | undefined | null,
 	): Promise<void>;
 	actorQueueEnqueueAndWait(
 		ctx: ActorContextHandle,
@@ -570,9 +601,25 @@ export async function buildServeConfig(
 		serverlessMaxStartPayloadBytes: config.serverless.maxStartPayloadBytes,
 	};
 
-	if (config.startEngine) {
+	// Always best-effort resolve the engine binary path and hand it to the core.
+	// The core alone decides whether to actually spawn a local engine, so JS must
+	// not duplicate that decision here. `loadEnginePath` throws when no binary is
+	// available (remote-only install, unsupported platform, optional deps
+	// skipped); in that case leave it unset and let the core report
+	// `engine.binary_unavailable` only if it actually needs one.
+	try {
 		serveConfig.engineBinaryPath = await loadEnginePath();
+	} catch (error) {
+		// The engine binary could not be resolved. The core still decides whether
+		// it needs to spawn a local engine; if it does, it will fail with
+		// engine.binary_unavailable (auto-download is off in the napi runtime).
+		logger().warn({
+			msg: "could not resolve a local engine binary; if a local engine must be spawned it will fail with engine.binary_unavailable — set RIVET_ENGINE_BINARY_PATH or install the @rivetkit/engine-cli platform package",
+			error: stringifyError(error),
+		});
 	}
+	serveConfig.engineHost = config.engineHost;
+	serveConfig.enginePort = config.enginePort;
 	if (config.test?.enabled) {
 		serveConfig.inspectorTestToken =
 			process.env._RIVET_TEST_INSPECTOR_TOKEN ?? "token";

package/src/registry/wasm-runtime.ts

@@ -32,6 +32,7 @@ import type {
 	RuntimeQueueNextBatchOptions,
 	RuntimeQueueTryNextBatchOptions,
 	RuntimeQueueWaitOptions,
+	RuntimeRegistryRouteResponse,
 	RuntimeRequestSaveOpts,
 	RuntimeServeConfig,
 	RuntimeServerlessRequest,
@@ -270,8 +271,18 @@ export class WasmCoreRuntime implements CoreRuntime {
 		await callWasm(() => asWasmRegistry(registry).shutdown());
 	}
 
-	async registryDiagnostics(): Promise<{ mode: string; envoyActiveActorCount: null }> {
-		return { mode: "wasm", envoyActiveActorCount: null };
+	async registryHealth(): Promise<RuntimeRegistryRouteResponse> {
+		return {
+			status: 200,
+			headers: { "content-type": "application/json" },
+			body: new TextEncoder().encode(
+				JSON.stringify({
+					status: "ok",
+					runtime: "rivetkit",
+					version: "wasm",
+				}),
+			),
+		};
 	}
 
 	async handleServerlessRequest(
@@ -508,6 +519,15 @@ export class WasmCoreRuntime implements CoreRuntime {
 		);
 	}
 
+	async actorWaitForTrackedShutdownWorkUnbounded(
+		ctx: ActorContextHandle,
+	): Promise<void> {
+		await callHandle<Promise<void>>(
+			asWasmActorContext(ctx),
+			"waitForTrackedShutdownWorkUnbounded",
+		);
+	}
+
 	actorKeepAwake(ctx: ActorContextHandle, promise: Promise<unknown>): void {
 		const wasmCtx = asWasmActorContext(ctx);
 		const regionId = callHandle<number>(wasmCtx, "beginKeepAwake");
@@ -753,9 +773,16 @@ export class WasmCoreRuntime implements CoreRuntime {
 		ctx: ActorContextHandle,
 		names: string[],
 		options?: RuntimeQueueWaitOptions | undefined | null,
+		signal?: CancellationTokenHandle | undefined | null,
 	): Promise<void> {
 		const queue = childHandle(asWasmActorContext(ctx), "queue");
-		await callHandleAsync(queue, "waitForNamesAvailable", names, options);
+		await callHandleAsync(
+			queue,
+			"waitForNamesAvailable",
+			names,
+			options,
+			signal,
+		);
 	}
 
 	async actorQueueEnqueueAndWait(

package/src/serde.ts

@@ -2,8 +2,8 @@ import * as cbor from "cbor-x";
 import invariant from "invariant";
 import type { VersionedDataHandler } from "vbare";
 import type { z } from "zod/v4";
+import type { Encoding, JsonCompatValue } from "@/common/encoding";
 import { assertUnreachable } from "@/common/utils";
-import type { JsonCompatValue, Encoding } from "@/common/encoding";
 import {
 	encodeJsonCompatValue,
 	jsonParseCompat,

package/src/serverless/configure.ts

@@ -1,9 +1,9 @@
 import { convertRegistryConfigToClientConfig } from "@/client/config";
+import { stringifyError } from "@/common/utils";
 import {
 	getDatacenters,
 	updateRunnerConfig,
 } from "@/engine-client/api-endpoints";
-import { stringifyError } from "@/common/utils";
 import type { RegistryConfig } from "@/registry/config";
 import { logger } from "@/registry/log";
 
@@ -16,11 +16,14 @@ function sleep(ms: number): Promise<void> {
 
 function configureTimeoutMs() {
 	const value = process.env.RIVET_SERVERLESS_CONFIGURE_TIMEOUT_MS;
-	if (value === undefined || value === "") return DEFAULT_CONFIGURE_TIMEOUT_MS;
+	if (value === undefined || value === "")
+		return DEFAULT_CONFIGURE_TIMEOUT_MS;
 
 	const parsed = Number(value);
 	if (!Number.isFinite(parsed) || parsed < 0) {
-		throw new Error("RIVET_SERVERLESS_CONFIGURE_TIMEOUT_MS must be a finite non-negative number");
+		throw new Error(
+			"RIVET_SERVERLESS_CONFIGURE_TIMEOUT_MS must be a finite non-negative number",
+		);
 	}
 
 	return parsed;
@@ -40,13 +43,19 @@ export async function configureServerlessPool(
 		attempts += 1;
 		try {
 			if (!config.namespace) {
-				throw new Error("namespace is required for serverless configuration");
+				throw new Error(
+					"namespace is required for serverless configuration",
+				);
 			}
 			if (!config.endpoint) {
-				throw new Error("endpoint is required for serverless configuration");
+				throw new Error(
+					"endpoint is required for serverless configuration",
+				);
 			}
 			if (!config.configurePool) {
-				throw new Error("configurePool is required for serverless configuration");
+				throw new Error(
+					"configurePool is required for serverless configuration",
+				);
 			}
 
 			const customConfig = config.configurePool;
@@ -55,7 +64,9 @@ export async function configureServerlessPool(
 			const poolName = customConfig.name ?? "default";
 			const serverlessToken = config.token ?? config.publicToken;
 			const headers = {
-				...(serverlessToken ? { "x-rivet-token": serverlessToken } : {}),
+				...(serverlessToken
+					? { "x-rivet-token": serverlessToken }
+					: {}),
 				...(customConfig.headers ?? {}),
 			};
 			const serverlessConfig = {

package/src/test/mod.ts

@@ -1,7 +1,7 @@
 import pRetry from "p-retry";
 import type { TestContext } from "vitest";
-import { type Client, createClient } from "@/client/mod";
 import { convertRegistryConfigToClientConfig } from "@/client/config";
+import { type Client, createClient } from "@/client/mod";
 import { getMetadata } from "@/engine-client/api-endpoints";
 import type { Registry } from "@/registry";
 
@@ -14,13 +14,16 @@ async function waitForRegistryReady(registry: Registry<any>): Promise<void> {
 		registry.parseConfig(),
 	);
 
-	await pRetry(async () => {
-		await getMetadata(clientConfig);
-	}, {
-		retries: 20,
-		minTimeout: 50,
-		maxTimeout: 250,
-	});
+	await pRetry(
+		async () => {
+			await getMetadata(clientConfig);
+		},
+		{
+			retries: 20,
+			minTimeout: 50,
+			maxTimeout: 250,
+		},
+	);
 }
 
 export async function setupTest<A extends Registry<any>>(

package/src/utils/endpoint-parser.ts

@@ -1,4 +1,4 @@
-import { z } from "zod/v4";
+import type { z } from "zod/v4";
 
 export interface ParsedEndpoint {
 	endpoint: string;

package/src/utils/env-vars.ts

@@ -22,6 +22,12 @@ export const getRivetTotalSlots = (): number | undefined => {
 };
 export const getRivetRunEngine = (): boolean =>
 	getEnvUniversal("RIVET_RUN_ENGINE") === "1";
+export const getRivetRunEngineHost = (): string | undefined =>
+	getEnvUniversal("RIVET_RUN_ENGINE_HOST");
+export const getRivetRunEnginePort = (): number | undefined => {
+	const value = getEnvUniversal("RIVET_RUN_ENGINE_PORT");
+	return value !== undefined ? parseInt(value, 10) : undefined;
+};
 export const getRivetRunEngineVersion = (): string | undefined =>
 	getEnvUniversal("RIVET_RUN_ENGINE_VERSION");
 export const getRivetEnvoyKind = (): string | undefined =>

package/src/utils/router.ts

@@ -2,12 +2,12 @@ import { OpenAPIHono } from "@hono/zod-openapi";
 import type { Hono } from "hono";
 import { createMiddleware } from "hono/factory";
 import { cors } from "@/common/cors";
+import { getLogger } from "@/common/log";
 import {
 	handleRouteError,
 	handleRouteNotFound,
 	loggerMiddleware,
 } from "@/common/router";
-import { getLogger } from "@/common/log";
 
 export function logger() {
 	return getLogger("router");

package/src/utils/serve.ts

@@ -1,10 +1,9 @@
-import type { Hono } from "hono";
-import { detectRuntime, stringifyError, type Runtime } from "../utils";
-import { RegistryConfig } from "@/registry/config";
-import { logger } from "@/registry/log";
-
 // TODO: Go back to dynamic import for this
 import getPort from "get-port";
+import type { Hono } from "hono";
+import type { RegistryConfig } from "@/registry/config";
+import { logger } from "@/registry/log";
+import { detectRuntime, type Runtime, stringifyError } from "../utils";
 
 const DEFAULT_PORT = 6421;
 export type ServeStatic =

package/src/utils.ts

@@ -1,6 +1,5 @@
-import { stringifyError } from "@/common/utils";
 import type { Context as HonoContext, Handler as HonoHandler } from "hono";
-import { stringify as uuidstringify } from "uuid";
+import { stringifyError } from "@/common/utils";
 import pkgJson from "../package.json" with { type: "json" };
 import { getLogger } from "./common/log";
 import { assertUnreachable } from "./common/utils";

package/src/workflow/context.ts

@@ -1,41 +1,42 @@
 // @ts-nocheck
-import { RAW_STATE_SYMBOL, type RunContext } from "@/actor/config";
+
+import type {
+	BranchConfig,
+	BranchOutput,
+	EntryKindType,
+	LoopConfig,
+	LoopResult,
+	StepConfig,
+	TryBlockConfig,
+	TryBlockResult,
+	TryStepConfig,
+	TryStepResult,
+	WorkflowContextInterface,
+	WorkflowQueueMessage,
+} from "@rivetkit/workflow-engine";
 import type {
 	QueueFilterName,
 	QueueNextBatchOptions,
 	QueueNextOptions,
 	QueueResultMessageForName,
 } from "@/actor/config";
-import type { Client } from "@/client/client";
-import type { Registry } from "@/registry";
+import { RAW_STATE_SYMBOL, type RunContext } from "@/actor/config";
 import type {
-	BaseActorDefinition,
 	AnyActorDefinition,
+	BaseActorDefinition,
 } from "@/actor/definition";
-import type {
-	AnyDatabaseProvider,
-	InferDatabaseClient,
-} from "@/common/database/config";
 import type {
 	EventSchemaConfig,
 	InferEventArgs,
 	InferSchemaMap,
 	QueueSchemaConfig,
 } from "@/actor/schema";
-import type { WorkflowContextInterface } from "@rivetkit/workflow-engine";
+import type { Client } from "@/client/client";
 import type {
-	BranchConfig,
-	BranchOutput,
-	EntryKindType,
-	LoopConfig,
-	LoopResult,
-	StepConfig,
-	TryBlockConfig,
-	TryBlockResult,
-	TryStepConfig,
-	TryStepResult,
-	WorkflowQueueMessage,
-} from "@rivetkit/workflow-engine";
+	AnyDatabaseProvider,
+	InferDatabaseClient,
+} from "@/common/database/config";
+import type { Registry } from "@/registry";
 import { WORKFLOW_GUARD_KV_KEY } from "./constants";
 
 type WorkflowActorQueueNextOptions<
@@ -80,7 +81,9 @@ type ActorWorkflowLoopConfig<
 			TQueues
 		>,
 		state: S,
-	) => Promise<LoopResult<S, T> | (S extends undefined ? void : never)>;
+	) => Promise<
+		LoopResult<S, T> | (S extends undefined ? undefined | void : never)
+	>;
 };
 
 type ActorWorkflowBranchConfig<
@@ -238,7 +241,7 @@ export class ActorWorkflowContext<
 	}
 
 	async step<T>(
-		nameOrConfig: string | Parameters<WorkflowContextInterface["step"]>[0],
+		nameOrConfig: string | StepConfig<T>,
 		run?: () => Promise<T>,
 	): Promise<T> {
 		if (typeof nameOrConfig === "string") {
@@ -260,9 +263,7 @@ export class ActorWorkflowContext<
 	}
 
 	async tryStep<T>(
-		nameOrConfig:
-			| string
-			| Parameters<WorkflowContextInterface["tryStep"]>[0],
+		nameOrConfig: string | TryStepConfig<T>,
 		run?: () => Promise<T>,
 	): Promise<TryStepResult<T>> {
 		if (typeof nameOrConfig === "string") {
@@ -329,13 +330,13 @@ export class ActorWorkflowContext<
 				TEvents,
 				TQueues
 			>,
-		) => Promise<LoopResult<undefined, T> | void>,
+		) => Promise<LoopResult<undefined, T> | undefined | void>,
 	): Promise<T>;
 	async loop<T>(
 		name: string,
 		run: (
 			ctx: WorkflowContextInterface,
-		) => Promise<LoopResult<undefined, T> | void>,
+		) => Promise<LoopResult<undefined, T> | undefined | void>,
 	): Promise<T>;
 	async loop<S, T>(
 		config: ActorWorkflowLoopConfig<
@@ -379,7 +380,7 @@ export class ActorWorkflowContext<
 				TEvents,
 				TQueues
 			>,
-		) => Promise<LoopResult<undefined, any> | void>,
+		) => Promise<LoopResult<undefined, any> | undefined | void>,
 	): Promise<any> {
 		if (typeof nameOrConfig === "string") {
 			if (!run) {

package/src/workflow/driver.ts

@@ -1,10 +1,5 @@
 // @ts-nocheck
-import type { RunContext } from "@/actor/config";
-import type {
-	AnyActorInstance,
-	AnyStaticActorInstance,
-} from "@/actor/definition";
-import { makeWorkflowKey, workflowStoragePrefix } from "@/actor/keys";
+
 import type {
 	EngineDriver,
 	KVEntry,
@@ -12,6 +7,9 @@ import type {
 	Message,
 	WorkflowMessageDriver,
 } from "@rivetkit/workflow-engine";
+import type { RunContext } from "@/actor/config";
+import type { AnyStaticActorInstance } from "@/actor/definition";
+import { makeWorkflowKey, workflowStoragePrefix } from "@/actor/keys";
 
 const WORKFLOW_STORAGE_PREFIX = workflowStoragePrefix();