rivetkit 2.3.0-rc.9 → 2.3.1

package/src/registry/native.ts

@@ -2,8 +2,10 @@ import { VirtualWebSocket } from "@rivetkit/virtual-websocket";
 import {
 	ACTOR_CONTEXT_INTERNAL_SYMBOL,
 	CONN_STATE_MANAGER_SYMBOL,
+	disposeRunInspector,
 	getRunFunction,
 	getRunInspectorConfig,
+	RAW_STATE_SYMBOL,
 	type WorkflowInspectorConfig,
 } from "@/actor/config";
 import type { AnyActorDefinition } from "@/actor/definition";
@@ -12,6 +14,7 @@ import {
 	encodeBridgeRivetError,
 	forbiddenError,
 	INTERNAL_ERROR_CODE,
+	isActorAbortedError,
 	isRivetErrorLike,
 	RivetError,
 	type RivetErrorLike,
@@ -32,6 +35,7 @@ import { convertRegistryConfigToClientConfig } from "@/client/config";
 import { HEADER_CONN_PARAMS } from "@/common/actor-router-consts";
 import type { AnyDatabaseProvider } from "@/common/database/config";
 import { wrapJsNativeDatabase } from "@/common/database/native-database";
+import { assertJsonCompatValue, type JsonCompatValue } from "@/common/encoding";
 import { decodeWorkflowHistoryTransport } from "@/common/inspector-transport";
 import { deconstructError, stringifyError } from "@/common/utils";
 import type {
@@ -47,12 +51,13 @@ import type {
 	RuntimeKind,
 	SqliteBackend,
 } from "@/registry/config";
-import {
-	decodeCborCompat,
-	decodeCborJsonCompat,
-	encodeCborCompat,
-} from "@/serde";
+import { decodeCborCompat, encodeCborCompat } from "@/serde";
 import { getEnvUniversal, VERSION } from "@/utils";
+import {
+	getNodeFsSync,
+	getNodePath,
+	importNodeDependencies,
+} from "@/utils/node";
 import { logger } from "./log";
 import { loadNapiRuntime } from "./napi-runtime";
 import {
@@ -73,15 +78,18 @@ import type {
 	RuntimeActorConfig,
 	RuntimeBytes,
 	RuntimeHttpResponse,
+	RuntimeInspectorTabEntry,
 	RuntimeQueueMessage,
 	RuntimeServeConfig,
 	RuntimeStateDeltaPayload,
 	WebSocketHandle,
 } from "./runtime";
 import { loadWasmRuntime } from "./wasm-runtime";
+import { createWriteThroughProxy } from "./write-through-proxy";
 
 const textEncoder = new TextEncoder();
 const textDecoder = new TextDecoder();
+
 type ResolvedRuntimeKind = Exclude<RuntimeKind, "auto">;
 type RuntimeHostKind = "node-like" | "edge-like";
 export type RuntimeLoaders = {
@@ -91,6 +99,7 @@ export type RuntimeLoaders = {
 	) => ReturnType<typeof loadWasmRuntime>;
 	detectHost: () => RuntimeHostKind;
 };
+
 type SerializeStateReason = "save" | "inspector";
 type NativeOnStateChangeHandler = (
 	ctx: ActorContextHandleAdapter,
@@ -345,6 +354,15 @@ function databaseNotConfiguredError(): RivetError {
 	);
 }
 
+function databaseClientNotReadyError(): RivetError {
+	return new RivetError(
+		"actor",
+		"database_client_not_ready",
+		"actor database client was not initialized before user code ran. this is an internal lifecycle error; the migration callback should have pre-warmed the client. file an issue if you can reproduce.",
+		{ public: true },
+	);
+}
+
 function stateNotEnabledError(): RivetError {
 	return new RivetError(
 		"actor",
@@ -413,8 +431,33 @@ function clearNativeRuntimeState(
 async function cleanupNativeSleepRuntimeState(
 	runtime: CoreRuntime,
 	ctx: ActorContextHandle,
+	afterTrackedWorkDrained?: () => Promise<void>,
 ): Promise<void> {
-	await runtime.actorWaitForTrackedShutdownWork(ctx);
+	// The bounded wait gives shutdown work one grace-period chance to finish.
+	// Drained means all tracked shutdown work completed before the deadline, so
+	// we can save final state and clear runtime state immediately. If it did not
+	// drain, close database handles now, then defer the final save and clear until
+	// the tracked work finishes without a deadline.
+	const drained = await runtime.actorWaitForTrackedShutdownWork(ctx);
+	if (!drained) {
+		await closeNativeDatabaseClient(runtime, ctx);
+		await closeNativeSqlDatabase(runtime, ctx);
+		void runtime
+			.actorWaitForTrackedShutdownWorkUnbounded(ctx)
+			.then(async () => {
+				await afterTrackedWorkDrained?.();
+				clearNativeRuntimeState(runtime, ctx);
+			})
+			.catch((error) => {
+				logger().warn({
+					msg: "deferred native sleep cleanup failed",
+					error: stringifyError(error),
+				});
+			});
+		return;
+	}
+
+	await afterTrackedWorkDrained?.();
 	await closeNativeDatabaseClient(runtime, ctx);
 	await closeNativeSqlDatabase(runtime, ctx);
 	clearNativeRuntimeState(runtime, ctx);
@@ -587,11 +630,19 @@ function decodeValue<T>(value?: RuntimeBytes | null): T {
 		return undefined as T;
 	}
 
-	return decodeCborJsonCompat(value);
+	return decodeCborCompat(value);
 }
 
 function encodeValue(value: unknown): RuntimeBytes {
-	return encodeCborCompat(value);
+	return encodeCborCompat(value as JsonCompatValue);
+}
+
+function normalizeArgs(value: unknown): unknown[] {
+	return Array.isArray(value)
+		? value
+		: value === undefined || value === null
+			? []
+			: [value];
 }
 
 function unwrapTsfnPayload<T>(error: unknown, payload: T): T {
@@ -924,6 +975,7 @@ function serializeWorkflowEntryKind(
 	}
 }
 
+// TODO: Switch inspector routes to CBOR encoding
 function serializeWorkflowHistoryForJson(data: ArrayBuffer | null): {
 	nameRegistry: string[];
 	entries: Array<{
@@ -957,7 +1009,7 @@ function serializeWorkflowHistoryForJson(data: ArrayBuffer | null): {
 
 	const history = decodeWorkflowHistoryTransport(data);
 
-	return {
+	return jsonSafe({
 		nameRegistry: [...history.nameRegistry],
 		entries: history.entries.map((entry) => ({
 			id: entry.id,
@@ -987,7 +1039,7 @@ function serializeWorkflowHistoryForJson(data: ArrayBuffer | null): {
 				],
 			),
 		),
-	};
+	});
 }
 
 function toHttpJsonCompatible<T>(value: T): T {
@@ -1059,60 +1111,7 @@ function wrapNativeCallback<Args extends Array<unknown>, Result>(
 
 function decodeArgs(value?: RuntimeBytes | null): unknown[] {
 	const decoded = decodeValue<unknown>(value);
-	return Array.isArray(decoded)
-		? decoded
-		: decoded === undefined
-			? []
-			: [decoded];
-}
-
-function createWriteThroughProxy<T>(
-	value: T,
-	commit: (next: T) => void,
-	beforeChange?: () => void,
-): T {
-	if (!value || typeof value !== "object") {
-		return value;
-	}
-
-	const proxies = new WeakMap<object, object>();
-	const wrap = (target: object): object => {
-		const cached = proxies.get(target);
-		if (cached) {
-			return cached;
-		}
-
-		const proxy = new Proxy(target, {
-			get(innerTarget, property, receiver) {
-				const result = Reflect.get(innerTarget, property, receiver);
-				return result && typeof result === "object"
-					? wrap(result as object)
-					: result;
-			},
-			set(innerTarget, property, nextValue, receiver) {
-				beforeChange?.();
-				const updated = Reflect.set(
-					innerTarget,
-					property,
-					nextValue,
-					receiver,
-				);
-				commit(value);
-				return updated;
-			},
-			deleteProperty(innerTarget, property) {
-				beforeChange?.();
-				const updated = Reflect.deleteProperty(innerTarget, property);
-				commit(value);
-				return updated;
-			},
-		});
-
-		proxies.set(target, proxy);
-		return proxy;
-	};
-
-	return wrap(value as object) as T;
+	return normalizeArgs(decoded);
 }
 
 function buildRequest(init: {
@@ -1204,14 +1203,25 @@ class NativeConnAdapter {
 		);
 	}
 
+	[RAW_STATE_SYMBOL](): unknown {
+		return this.#readState();
+	}
+
 	get state(): unknown {
 		const nextState = this.#readState();
-		return createWriteThroughProxy(nextState, (nextValue) => {
-			this.#writeState(nextValue, { writeNative: true });
-		});
+		return createWriteThroughProxy(
+			nextState,
+			(nextValue) => {
+				this.#writeState(nextValue, { writeNative: true });
+			},
+			(newValue) => {
+				assertJsonCompatValue(newValue);
+			},
+		);
 	}
 
 	set state(value: unknown) {
+		assertJsonCompatValue(value);
 		this.#writeState(value, { writeNative: true });
 	}
 
@@ -1683,7 +1693,12 @@ class NativeQueueAdapter {
 			signal?: AbortSignal;
 		},
 	) {
-		if (!options?.signal) {
+		const { token, cleanup } = await createCancellationTokenHandle(
+			this.#runtime,
+			options?.signal,
+		);
+
+		try {
 			await callNative(() =>
 				this.#runtime.actorQueueWaitForNamesAvailable(
 					this.#ctx,
@@ -1691,57 +1706,11 @@ class NativeQueueAdapter {
 					{
 						timeoutMs: options?.timeout,
 					},
+					token,
 				),
 			);
-			return;
-		}
-
-		const deadline =
-			options.timeout === undefined
-				? undefined
-				: Date.now() + options.timeout;
-
-		for (;;) {
-			if (options.signal.aborted) {
-				throw actorAbortedError();
-			}
-
-			const remainingTimeout =
-				deadline === undefined
-					? undefined
-					: Math.max(0, deadline - Date.now());
-			const sliceTimeout =
-				remainingTimeout === undefined
-					? 100
-					: Math.min(remainingTimeout, 100);
-
-			try {
-				await callNative(() =>
-					this.#runtime.actorQueueWaitForNamesAvailable(
-						this.#ctx,
-						[...names],
-						{
-							timeoutMs: sliceTimeout,
-						},
-					),
-				);
-				return;
-			} catch (error) {
-				if (
-					(error as { group?: string; code?: string }).group ===
-						"queue" &&
-					(error as { group?: string; code?: string }).code ===
-						"timed_out"
-				) {
-					if (
-						remainingTimeout === undefined ||
-						remainingTimeout > 100
-					) {
-						continue;
-					}
-				}
-				throw error;
-			}
+		} finally {
+			cleanup?.();
 		}
 	}
 
@@ -1844,11 +1813,7 @@ class NativeQueueAdapter {
 				}
 				yield message;
 			} catch (error) {
-				if (
-					isRivetErrorLike(error) &&
-					error.group === "actor" &&
-					error.code === "aborted"
-				) {
+				if (isActorAbortedError(error)) {
 					return;
 				}
 				throw error;
@@ -2323,6 +2288,104 @@ class TrackedWebSocketHandleAdapter implements UniversalWebSocket {
 	}
 }
 
+class NativeConnectionMap implements ReadonlyMap<string, NativeConnAdapter> {
+	#runtime: CoreRuntime;
+	#ctx: ActorContextHandle;
+	#schemas: NativeValidationConfig;
+
+	constructor(
+		runtime: CoreRuntime,
+		ctx: ActorContextHandle,
+		schemas: NativeValidationConfig,
+	) {
+		this.#runtime = runtime;
+		this.#ctx = ctx;
+		this.#schemas = schemas;
+	}
+
+	#connToAdapter(conn: ConnHandle): NativeConnAdapter {
+		return new NativeConnAdapter(
+			this.#runtime,
+			conn,
+			this.#schemas,
+			this.#ctx,
+			(connId) =>
+				callNativeSync(() =>
+					this.#runtime.actorQueueHibernationRemoval(
+						this.#ctx,
+						connId,
+					),
+				),
+		);
+	}
+
+	get size(): number {
+		return callNativeSync(() => this.#runtime.actorConns(this.#ctx)).length;
+	}
+
+	get(key: string): NativeConnAdapter | undefined {
+		const conns = callNativeSync(() => this.#runtime.actorConns(this.#ctx));
+		const conn = conns.find((c) => this.#runtime.connId(c) === key);
+		if (!conn) return undefined;
+		return this.#connToAdapter(conn);
+	}
+
+	has(key: string): boolean {
+		const conns = callNativeSync(() => this.#runtime.actorConns(this.#ctx));
+		return conns.some((c) => this.#runtime.connId(c) === key);
+	}
+
+	keys(): MapIterator<string> {
+		const conns = callNativeSync(() => this.#runtime.actorConns(this.#ctx));
+		return conns
+			.map((c) => this.#runtime.connId(c))
+			[Symbol.iterator]() satisfies MapIterator<string>;
+	}
+
+	values(): MapIterator<NativeConnAdapter> {
+		const conns = callNativeSync(() => this.#runtime.actorConns(this.#ctx));
+		return conns
+			.map((c) => this.#connToAdapter(c))
+			[Symbol.iterator]() satisfies MapIterator<NativeConnAdapter>;
+	}
+
+	entries(): MapIterator<[string, NativeConnAdapter]> {
+		const conns = callNativeSync(() => this.#runtime.actorConns(this.#ctx));
+		return conns
+			.map(
+				(c) =>
+					[this.#runtime.connId(c), this.#connToAdapter(c)] as [
+						string,
+						NativeConnAdapter,
+					],
+			)
+			[Symbol.iterator]() satisfies MapIterator<
+			[string, NativeConnAdapter]
+		>;
+	}
+
+	forEach(
+		callback: (
+			value: NativeConnAdapter,
+			key: string,
+			map: ReadonlyMap<string, NativeConnAdapter>,
+		) => void,
+		thisArg?: unknown,
+	): void {
+		const conns = callNativeSync(() => this.#runtime.actorConns(this.#ctx));
+		for (const conn of conns) {
+			const id = this.#runtime.connId(conn);
+			callback.call(thisArg, this.#connToAdapter(conn), id, this);
+		}
+	}
+
+	[Symbol.iterator](): MapIterator<[string, NativeConnAdapter]> {
+		return this.entries();
+	}
+
+	readonly [Symbol.toStringTag] = "NativeConnectionMap";
+}
+
 export class ActorContextHandleAdapter {
 	#runtime: CoreRuntime;
 	#ctx: ActorContextHandle;
@@ -2331,9 +2394,9 @@ export class ActorContextHandleAdapter {
 	#abortSignalCleanup?: () => void;
 	#client?: AnyClient;
 	#clientFactory?: () => AnyClient;
+	#connMap?: NativeConnectionMap;
 	#databaseProvider?: Exclude<AnyDatabaseProvider, undefined>;
 	#db?: unknown;
-	#dbProxy?: unknown;
 	#dispatchCancelToken?: CancellationTokenHandle;
 	#kv?: NativeKvAdapter;
 	#queue?: NativeQueueAdapter;
@@ -2396,32 +2459,25 @@ export class ActorContextHandleAdapter {
 			throw databaseNotConfiguredError();
 		}
 
-		if (!this.#dbProxy) {
-			this.#dbProxy = new Proxy(
-				{},
-				{
-					get: (_target, property) => {
-						if (property === "then") {
-							return undefined;
-						}
+		if (this.#db) {
+			return this.#db;
+		}
 
-						return async (...args: Array<unknown>) => {
-							const client = await this.ensureDatabaseClient();
-							const value = Reflect.get(
-								client as object,
-								property,
-							);
-							if (typeof value !== "function") {
-								return value;
-							}
-							return await value.apply(client, args);
-						};
-					},
-				},
-			);
+		const runtimeState = getNativeRuntimeState(this.#runtime, this.#ctx);
+		const cachedClient = runtimeState.databaseClient;
+		if (cachedClient) {
+			this.#db = cachedClient.client;
+			return this.#db;
 		}
 
-		return this.#dbProxy;
+		throw databaseClientNotReadyError();
+	}
+
+	[RAW_STATE_SYMBOL](): unknown {
+		if (!this.#stateEnabled) {
+			throw stateNotEnabledError();
+		}
+		return this.#readState();
 	}
 
 	get state(): unknown {
@@ -2444,8 +2500,9 @@ export class ActorContextHandleAdapter {
 				(nextValue) => {
 					this.#writeState(nextValue, { scheduleSave: true });
 				},
-				() => {
+				(newValue) => {
 					this.#assertCanMutateState();
+					assertJsonCompatValue(newValue);
 				},
 			);
 		}
@@ -2457,6 +2514,7 @@ export class ActorContextHandleAdapter {
 			throw stateNotEnabledError();
 		}
 		this.#assertCanMutateState();
+		assertJsonCompatValue(value);
 		this.#writeState(value, { scheduleSave: true });
 	}
 
@@ -2523,27 +2581,15 @@ export class ActorContextHandleAdapter {
 		return callNativeSync(() => this.#runtime.actorRegion(this.#ctx));
 	}
 
-	get conns(): Map<string, NativeConnAdapter> {
-		return new Map(
-			callNativeSync(() => this.#runtime.actorConns(this.#ctx)).map(
-				(conn) => [
-					this.#runtime.connId(conn),
-					new NativeConnAdapter(
-						this.#runtime,
-						conn,
-						this.#schemas,
-						this.#ctx,
-						(connId) =>
-							callNativeSync(() =>
-								this.#runtime.actorQueueHibernationRemoval(
-									this.#ctx,
-									connId,
-								),
-							),
-					),
-				],
-			),
-		);
+	get conns(): ReadonlyMap<string, NativeConnAdapter> {
+		if (!this.#connMap) {
+			this.#connMap = new NativeConnectionMap(
+				this.#runtime,
+				this.#ctx,
+				this.#schemas,
+			);
+		}
+		return this.#connMap;
 	}
 
 	get log() {
@@ -2800,7 +2846,15 @@ export class ActorContextHandleAdapter {
 
 	internalKeepAwake<T>(run: Promise<T> | (() => Promise<T>)): Promise<T> {
 		const promise = typeof run === "function" ? run() : run;
-		const trackedPromise = promise.then(() => null);
+		// Track only completion, swallowing the outcome. The real result/error
+		// is delivered through the returned `promise`; without a rejection
+		// handler here every workflow yield (which rejects with SleepError)
+		// would be funneled into the registered task and logged as a spurious
+		// "keep_awake promise rejected" warning.
+		const trackedPromise = promise.then(
+			() => null,
+			() => null,
+		);
 		try {
 			callNativeSync(() =>
 				this.#runtime.actorRegisterTask(this.#ctx, trackedPromise),
@@ -2862,6 +2916,7 @@ export class ActorContextHandleAdapter {
 	}
 
 	sleep(): void {
+		this.#flushStateChange();
 		callNativeSync(() => this.#runtime.actorSleep(this.#ctx));
 	}
 
@@ -3232,6 +3287,7 @@ function withConnContext(
 function buildActorConfig(
 	definition: AnyActorDefinition,
 	registryConfig: RegistryConfig,
+	runtimeKind: "napi" | "wasm",
 ): RuntimeActorConfig {
 	const config = definition.config as unknown as Record<string, unknown>;
 	const options = (config.options ?? {}) as Record<string, unknown>;
@@ -3286,9 +3342,100 @@ function buildActorConfig(
 		actions: Object.keys((config.actions ?? {}) as Record<string, unknown>)
 			.sort()
 			.map((name) => ({ name })),
+		inspectorTabs: buildInspectorTabs(config.inspector, runtimeKind),
 	};
 }
 
+function buildInspectorTabs(
+	inspector: unknown,
+	runtimeKind: "napi" | "wasm",
+): Array<RuntimeInspectorTabEntry> | undefined {
+	if (!inspector || typeof inspector !== "object") return undefined;
+	const tabs = (inspector as { tabs?: unknown }).tabs;
+	if (!Array.isArray(tabs) || tabs.length === 0) return undefined;
+	return tabs.map((raw) => {
+		const entry = raw as {
+			id: string;
+			label?: string;
+			source?: string;
+			icon?: string;
+			hidden?: boolean;
+		};
+		if (entry.hidden === true) {
+			return { id: entry.id, hidden: true };
+		}
+
+		if (runtimeKind === "wasm") {
+			if (entry.source !== undefined) {
+				logger().warn(
+					{
+						tabId: entry.id,
+						runtimeKind,
+					},
+					"inspector.tabs[].source is not supported on wasm runners (current host: wasm). Tab descriptors will still appear in the dashboard strip but the tab body will render a not-available placeholder.",
+				);
+			}
+			return {
+				id: entry.id,
+				label: entry.label,
+				icon: entry.icon,
+				source: undefined,
+			};
+		}
+
+		const resolved =
+			entry.source !== undefined
+				? getNodePath().resolve(entry.source)
+				: undefined;
+		if (resolved !== undefined) {
+			validateInspectorTabSource(entry.id, resolved);
+		}
+		return {
+			id: entry.id,
+			label: entry.label,
+			icon: entry.icon,
+			source: resolved,
+		};
+	});
+}
+
+function validateInspectorTabSource(tabId: string, resolved: string): void {
+	if (resolved === getNodePath().parse(resolved).root) {
+		throw new Error(
+			`inspector.tabs[id="${tabId}"].source resolves to the filesystem root (${resolved}). ` +
+				"Point it at the tab's own static-asset directory instead.",
+		);
+	}
+	let stat: import("node:fs").Stats;
+	try {
+		stat = getNodeFsSync().statSync(resolved);
+	} catch (err) {
+		const code = (err as NodeJS.ErrnoException)?.code;
+		if (code === "ENOENT") {
+			throw new Error(
+				`inspector.tabs[id="${tabId}"].source (${resolved}) does not exist.`,
+			);
+		}
+		if (code === "EACCES") {
+			throw new Error(
+				`inspector.tabs[id="${tabId}"].source (${resolved}) is not readable (EACCES).`,
+			);
+		}
+		throw new Error(
+			`inspector.tabs[id="${tabId}"].source (${resolved}) could not be stat'd: ${
+				(err as Error)?.message ?? err
+			}`,
+		);
+	}
+	if (!stat.isDirectory()) {
+		throw new Error(
+			`inspector.tabs[id="${tabId}"].source (${resolved}) must be a directory, got ${
+				stat.isFile() ? "file" : "non-directory"
+			}.`,
+		);
+	}
+}
+
 export function buildNativeFactory(
 	runtime: CoreRuntime,
 	registryConfig: RegistryConfig,
@@ -3420,15 +3567,23 @@ export function buildNativeFactory(
 				},
 			);
 		};
-		try {
-			await runtime.actorVerifyInspectorAuth(
-				ctx,
-				jsRequest.headers
-					.get("authorization")
-					?.replace(/^Bearer\s+/i, "") ?? null,
-			);
-		} catch (error) {
-			return errorResponse(error, 401);
+
+		const isPublicPerActorPath =
+			jsRequest.method === "GET" &&
+			(url.pathname === "/inspector/tab-config" ||
+				url.pathname.startsWith("/inspector/custom-tabs/"));
+
+		if (!isPublicPerActorPath) {
+			try {
+				await runtime.actorVerifyInspectorAuth(
+					ctx,
+					jsRequest.headers
+						.get("authorization")
+						?.replace(/^Bearer\s+/i, "") ?? null,
+				);
+			} catch (error) {
+				return errorResponse(error, 401);
+			}
 		}
 
 		const workflowHistory = () =>
@@ -3548,6 +3703,10 @@ export function buildNativeFactory(
 							getNativeWorkflowInspector(ctx) !== undefined,
 					});
 				} catch (error) {
+					logger().error({
+						msg: "error replaying workflow history",
+						error,
+					});
 					return errorResponse(error);
 				}
 			}
@@ -3715,18 +3874,46 @@ export function buildNativeFactory(
 						404,
 					);
 				}
-				const body = (await jsRequest.json()) as { args?: unknown[] };
+				const body = (await jsRequest.json()) as {
+					args?: unknown;
+					properties?: unknown;
+				};
+				if (body.args !== undefined && body.properties !== undefined) {
+					return jsonResponse(
+						{ error: "use either args or properties, not both" },
+						{ status: 400 },
+					);
+				}
+				if (
+					body.properties !== undefined &&
+					(body.properties === null ||
+						typeof body.properties !== "object" ||
+						Array.isArray(body.properties))
+				) {
+					return jsonResponse(
+						{ error: "properties must be an object" },
+						{ status: 400 },
+					);
+				}
+				const args =
+					body.properties !== undefined
+						? [body.properties]
+						: normalizeArgs(body.args);
 				try {
 					const output = await action(
 						actorCtx,
 						...validateActionArgs(
 							schemaConfig.actionInputSchemas,
 							actionName,
-							body.args ?? [],
+							args,
 						),
 					);
 					return jsonResponse({ output });
 				} catch (error) {
+					logger().error({
+						msg: "Error handling inspector action request",
+						error,
+					});
 					return errorResponse(error);
 				}
 			}
@@ -3741,6 +3928,10 @@ export function buildNativeFactory(
 				{ status: 404 },
 			);
 		} catch (error) {
+			logger().error({
+				msg: "Error handling inspector request",
+				error,
+			});
 			return errorResponse(error);
 		} finally {
 			await actorCtx.dispose();
@@ -3913,26 +4104,35 @@ export function buildNativeFactory(
 			async (error: unknown, payload: { ctx: ActorContextHandle }) => {
 				const { ctx } = unwrapTsfnPayload(error, payload);
 				const actorCtx = makeActorCtx(ctx);
+				// TODO: Move this save hook into cleanupNativeSleepRuntimeState
+				// so immediate and deferred sleep cleanup share one save-state
+				// path instead of passing a callback through cleanup.
+				const saveActorState = async () => {
+					if (runtime.kind === "wasm") {
+						// Wasm cannot use the native context save helper here because
+						// the runtime owns the serialized state handoff.
+						await runtime.actorSaveState(
+							ctx,
+							actorCtx.serializeForTick("save"),
+						);
+					} else {
+						await actorCtx.saveState({
+							immediate: true,
+						});
+					}
+				};
 				try {
 					if (onSleep) {
-						try {
-							await onSleep(actorCtx);
-						} finally {
-							if (runtime.kind === "wasm") {
-								// Wasm cannot use the native context save helper here because
-								// the runtime owns the serialized state handoff.
-								await runtime.actorSaveState(
-									ctx,
-									actorCtx.serializeForTick("save"),
-								);
-							} else {
-								await actorCtx.saveState({ immediate: true });
-							}
-						}
+						await onSleep(actorCtx);
 					}
+					await saveActorState();
 				} finally {
 					try {
-						await cleanupNativeSleepRuntimeState(runtime, ctx);
+						await cleanupNativeSleepRuntimeState(
+							runtime,
+							ctx,
+							saveActorState,
+						);
 					} finally {
 						await actorCtx.dispose();
 					}
@@ -3948,6 +4148,11 @@ export function buildNativeFactory(
 						await config.onDestroy(actorCtx);
 					}
 				} finally {
+					const actorId = callNativeSync(() => runtime.actorId(ctx));
+					// Release actorId-keyed state so it does not accumulate per
+					// destroyed actor.
+					nativeRunHandlerActiveByActorId.delete(actorId);
+					disposeRunInspector(config.run, actorId);
 					resolveNativeDestroy(runtime, ctx);
 					await actorCtx.closeDatabase();
 					clearNativeRuntimeState(runtime, ctx);
@@ -4351,7 +4556,11 @@ export function buildNativeFactory(
 					try {
 						await run(actorCtx);
 					} finally {
-						nativeRunHandlerActiveByActorId.set(actorId, false);
+						// Delete rather than set(false): an absent entry already
+						// reads as inactive, and deleting keeps this map bounded
+						// to currently-running handlers instead of accumulating an
+						// entry per actor id forever.
+						nativeRunHandlerActiveByActorId.delete(actorId);
 						await actorCtx.dispose();
 					}
 				},
@@ -4562,7 +4771,7 @@ export function buildNativeFactory(
 
 	return runtime.createActorFactory(
 		callbacks,
-		buildActorConfig(definition, registryConfig),
+		buildActorConfig(definition, registryConfig, runtime.kind),
 	);
 }
 
@@ -4589,10 +4798,29 @@ export async function buildServeConfig(
 		serverlessMaxStartPayloadBytes: config.serverless.maxStartPayloadBytes,
 	};
 
-	if (config.startEngine) {
+	// Always best-effort resolve the npm-installed engine binary and hand its
+	// path to the core. The core alone decides whether to actually spawn a local
+	// engine (its `should_manage_engine`, based on the endpoint + spawn mode), so
+	// JS must not duplicate that decision here. Only JS knows the npm
+	// `node_modules` layout, so it resolves the path; if no binary is available
+	// (remote-only install, unsupported platform, optional deps skipped), leave
+	// it unset and let the core report `engine.binary_unavailable` if it actually
+	// needs one.
+	try {
 		const { getEnginePath } = await loadEngineCli();
 		serveConfig.engineBinaryPath = getEnginePath();
+	} catch (error) {
+		// The npm-installed 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). Warn so the cause is actionable.
+		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 =
 			getEnvUniversal("_RIVET_TEST_INSPECTOR_TOKEN") ?? "token";
@@ -4616,6 +4844,13 @@ export async function buildRegistryWithRuntime(
 		trySetProcessEnv("_RIVET_TEST_INSPECTOR_TOKEN", "token");
 	}
 
+	// Custom inspector tab `source` paths are resolved with node:path while
+	// building actor configs below, so the Node modules must be loaded first.
+	// Native (napi) runtime only; wasm has no filesystem.
+	if (runtime.kind === "napi") {
+		importNodeDependencies();
+	}
+
 	const registry = runtime.createRegistry();
 
 	for (const [name, definition] of Object.entries(config.use)) {