rivetkit 2.3.0-rc.11 → 2.3.0-rc.13

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "rivetkit",
-	"version": "2.3.0-rc.11",
+	"version": "2.3.0-rc.13",
 	"description": "Lightweight libraries for building stateful actors on edge platforms",
 	"license": "Apache-2.0",
 	"keywords": [
@@ -126,6 +126,16 @@
 				"default": "./dist/tsup/inspector/mod.cjs"
 			}
 		},
+		"./inspector-tab": {
+			"import": {
+				"types": "./dist/tsup/inspector-tab/mod.d.ts",
+				"default": "./dist/tsup/inspector-tab/mod.js"
+			},
+			"require": {
+				"types": "./dist/tsup/inspector-tab/mod.d.cts",
+				"default": "./dist/tsup/inspector-tab/mod.cjs"
+			}
+		},
 		"./inspector/client": {
 			"import": {
 				"types": "./dist/browser/inspector/client.d.ts",
@@ -161,7 +171,7 @@
 		"./dist/tsup/chunk-*.cjs"
 	],
 	"scripts": {
-		"build": "tsup src/mod.ts src/client/mod.ts src/common/log.ts src/common/websocket.ts src/actor/errors.ts src/utils.ts src/workflow/mod.ts src/test/mod.ts src/inspector/mod.ts src/db/mod.ts src/db/drizzle.ts src/dynamic/mod.ts && tsup src/agent-os/index.ts --no-clean --out-dir dist/tsup/agent-os",
+		"build": "tsup src/mod.ts src/client/mod.ts src/common/log.ts src/common/websocket.ts src/actor/errors.ts src/utils.ts src/workflow/mod.ts src/test/mod.ts src/inspector/mod.ts src/inspector-tab/mod.ts src/db/mod.ts src/db/drizzle.ts src/dynamic/mod.ts && tsup src/agent-os/index.ts --no-clean --out-dir dist/tsup/agent-os",
 		"build:browser": "tsup --config tsup.browser.config.ts",
 		"check-types": "tsc --noEmit",
 		"lint": "biome check . && pnpm run check:test-skips && pnpm run check:wait-for-comments",
@@ -183,14 +193,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.0-rc.11",
-		"@rivetkit/engine-envoy-protocol": "2.3.0-rc.11",
+		"@rivetkit/engine-cli": "2.3.0-rc.13",
+		"@rivetkit/engine-envoy-protocol": "2.3.0-rc.13",
 		"@rivetkit/on-change": "6.0.1",
-		"@rivetkit/rivetkit-napi": "2.3.0-rc.11",
-		"@rivetkit/rivetkit-wasm": "2.3.0-rc.11",
-		"@rivetkit/traces": "2.3.0-rc.11",
-		"@rivetkit/virtual-websocket": "2.3.0-rc.11",
-		"@rivetkit/workflow-engine": "2.3.0-rc.11",
+		"@rivetkit/rivetkit-napi": "2.3.0-rc.13",
+		"@rivetkit/rivetkit-wasm": "2.3.0-rc.13",
+		"@rivetkit/traces": "2.3.0-rc.13",
+		"@rivetkit/virtual-websocket": "2.3.0-rc.13",
+		"@rivetkit/workflow-engine": "2.3.0-rc.13",
 		"cbor-x": "^1.6.0",
 		"drizzle-orm": "^0.44.2",
 		"get-port": "^7.1.0",

package/src/actor/config.ts

@@ -62,6 +62,10 @@ type ActorKvListOptions<
 
 type ActorClientFor<T> = T extends Registry<any> ? Client<T> : T;
 
+/**
+ * @deprecated Actor KV is deprecated. Use embedded SQLite (`c.db` / `c.sql`)
+ * or actor state instead.
+ */
 export interface ActorKv {
 	get<T extends ActorKvValueType = "text">(
 		key: Uint8Array | string,
@@ -305,6 +309,10 @@ export interface ActorContext<
 	[RAW_STATE_SYMBOL](): TState;
 	state: TState;
 	vars: TVars;
+	/**
+	 * @deprecated Actor KV is deprecated. Use embedded SQLite (`db` / `sql`)
+	 * or actor state instead.
+	 */
 	readonly kv: ActorKv;
 	readonly db: InferDatabaseClient<TDatabase>;
 	readonly schedule: ActorSchedule;
@@ -735,6 +743,88 @@ const RunInspectorConfigSchema = z
 	})
 	.optional();
 
+/**
+ * Built-in inspector tabs the dashboard ships. Used to validate
+ * `hidden: true` entries and reject custom-tab ids that collide with
+ * a built-in.
+ */
+export const BUILTIN_INSPECTOR_TAB_IDS = [
+	"workflow",
+	"database",
+	"state",
+	"queue",
+	"connections",
+	"console",
+] as const;
+
+export const BuiltinInspectorTabIdSchema = z.enum(BUILTIN_INSPECTOR_TAB_IDS);
+
+// Custom tab id grammar — mirrored in Rust at
+// `rivetkit-rust/packages/rivetkit-core/src/inspector/tabs.rs`. Slashes are
+// forbidden because the runtime splits `/inspector/custom-tabs/<id>/<rest>`
+// on the first `/`.
+const CUSTOM_INSPECTOR_TAB_ID_RE = /^[A-Za-z0-9_-]+$/;
+
+export const CustomInspectorTabEntrySchema = z
+	.object({
+		id: z
+			.string()
+			.regex(
+				CUSTOM_INSPECTOR_TAB_ID_RE,
+				"inspector.tabs[].id must contain only letters, digits, underscore, or dash",
+			),
+		label: z.string().min(1),
+		source: z.string().min(1),
+		/**
+		 * Optional icon id. The dashboard maps strings to glyphs (see its
+		 * icon registry); unknown ids fall back to a generic icon.
+		 */
+		icon: z.string().min(1).optional(),
+		hidden: z.literal(false).optional(),
+	})
+	.strict();
+
+export const HideInspectorTabEntrySchema = z
+	.object({
+		id: BuiltinInspectorTabIdSchema,
+		hidden: z.literal(true),
+	})
+	.strict();
+
+export const InspectorTabEntrySchema = z.union([
+	CustomInspectorTabEntrySchema,
+	HideInspectorTabEntrySchema,
+]);
+
+export const ActorInspectorConfigSchema = z
+	.object({
+		tabs: z.array(InspectorTabEntrySchema).default(() => []),
+	})
+	.strict()
+	.refine(
+		(data) => {
+			const ids = data.tabs.map((t) => t.id);
+			return new Set(ids).size === ids.length;
+		},
+		{ message: "Duplicate id in inspector.tabs", path: ["tabs"] },
+	)
+	.refine(
+		(data) => {
+			// A custom entry's id must not collide with a built-in id.
+			const builtinSet = new Set(BUILTIN_INSPECTOR_TAB_IDS);
+			return data.tabs.every(
+				(t) => t.hidden === true || !builtinSet.has(t.id as any),
+			);
+		},
+		{
+			message:
+				"Custom inspector tab id collides with a built-in (use hidden: true to hide a built-in)",
+			path: ["tabs"],
+		},
+	);
+
+export type ActorInspectorConfig = z.input<typeof ActorInspectorConfigSchema>;
+
 // Schema for run handler with metadata
 export const RunConfigSchema = z.object({
 	/** Display name for the actor in the Inspector UI. */
@@ -951,6 +1041,7 @@ export const ActorConfigSchema = z
 		db: z.any().optional(),
 		createVars: zFunction().optional(),
 		options: ActorOptionsSchema,
+		inspector: ActorInspectorConfigSchema.optional(),
 	})
 	.strict()
 	.refine(
@@ -1505,6 +1596,25 @@ export type ActorConfig<
 	TDatabase extends AnyDatabaseProvider,
 	TEvents extends EventSchemaConfig = Record<never, never>,
 	TQueues extends QueueSchemaConfig = Record<never, never>,
+	TActions extends Actions<
+		TState,
+		TConnParams,
+		TConnState,
+		TVars,
+		TInput,
+		TDatabase,
+		TEvents,
+		TQueues
+	> = Actions<
+		TState,
+		TConnParams,
+		TConnState,
+		TVars,
+		TInput,
+		TDatabase,
+		TEvents,
+		TQueues
+	>,
 > = Omit<
 	z.infer<typeof ActorConfigSchema>,
 	| "actions"
@@ -1540,16 +1650,7 @@ export type ActorConfig<
 		TDatabase,
 		TEvents,
 		TQueues,
-		Actions<
-			TState,
-			TConnParams,
-			TConnState,
-			TVars,
-			TInput,
-			TDatabase,
-			TEvents,
-			TQueues
-		>
+		TActions
 	> &
 	CreateState<
 		TState,

package/src/actor/definition.ts

@@ -44,7 +44,7 @@ export interface BaseActorDefinition<
 		Q
 	>,
 > {
-	readonly config: ActorConfig<S, CP, CS, V, I, DB, E, Q>;
+	readonly config: ActorConfig<S, CP, CS, V, I, DB, E, Q, _R>;
 }
 
 export interface AnyActorDefinition {
@@ -84,13 +84,13 @@ export class ActorDefinition<
 	>,
 > implements BaseActorDefinition<S, CP, CS, V, I, DB, E, Q, R>
 {
-	#config: ActorConfig<S, CP, CS, V, I, DB, E, Q>;
+	#config: ActorConfig<S, CP, CS, V, I, DB, E, Q, R>;
 
-	constructor(config: ActorConfig<S, CP, CS, V, I, DB, E, Q>) {
+	constructor(config: ActorConfig<S, CP, CS, V, I, DB, E, Q, R>) {
 		this.#config = config;
 	}
 
-	get config(): ActorConfig<S, CP, CS, V, I, DB, E, Q> {
+	get config(): ActorConfig<S, CP, CS, V, I, DB, E, Q, R> {
 		return this.#config;
 	}
 }
@@ -192,7 +192,8 @@ export function actor<
 		TInput,
 		TDatabase,
 		TEvents,
-		TQueues
+		TQueues,
+		TActions
 	>;
 	return new ActorDefinition(config);
 }

package/src/actor/instance/mod.ts

@@ -1637,10 +1637,10 @@ export class ActorInstance<
 		attributes?: Record<string, unknown>,
 	): Record<string, unknown> {
 		return {
-			"rivet.actor.id": this.#actorId,
-			"rivet.actor.name": this.#name,
-			"rivet.actor.key": this.#actorKeyString,
-			"rivet.actor.region": this.#region,
+			"rivet.actors.actor.id": this.#actorId,
+			"rivet.actors.actor.name": this.#name,
+			"rivet.actors.actor.key": this.#actorKeyString,
+			"rivet.actors.actor.region": this.#region,
 			...(attributes ?? {}),
 		};
 	}

package/src/actor/mod.ts

@@ -52,6 +52,8 @@ export {
 export {
 	ActorError,
 	RivetError,
+	type RivetErrorLike,
+	type RivetErrorOptions,
 	UserError,
 	type UserErrorOptions,
 } from "./errors";

package/src/client/actor-common.ts

@@ -38,6 +38,29 @@ type LooseEventSubscribe = (
 	callback: (...args: any[]) => void,
 ) => () => void;
 
+type ActorActionMap<R> = {
+	[K in keyof NonNullable<R>]: NonNullable<R>[K] extends (
+		...args: infer Args
+	) => infer Return
+		? ActorActionFunction<Args, Awaited<Return>>
+		: never;
+};
+
+type ActionsOf<AD extends AnyActorDefinition> =
+	AD extends BaseActorDefinition<
+		any,
+		any,
+		any,
+		any,
+		any,
+		any,
+		any,
+		any,
+		infer R
+	>
+		? R
+		: never;
+
 export interface ActorGatewayOptions {
 	skipReadyWait?: boolean;
 }
@@ -73,33 +96,7 @@ export type ActorDefinitionActions<AD extends AnyActorDefinition> =
 	// biome-ignore lint/suspicious/noExplicitAny: safe to use any here
 	IsAny<AD> extends true
 		? Record<string, ActorActionFunction<any[], any>>
-		: AD extends { config: { actions?: infer R } }
-			? {
-					[K in keyof R]: R[K] extends (
-						...args: infer Args
-					) => infer Return
-						? ActorActionFunction<Args, Return>
-						: never;
-				}
-			: AD extends BaseActorDefinition<
-						any,
-						any,
-						any,
-						any,
-						any,
-						any,
-						any,
-						any,
-						infer R
-					>
-				? {
-						[K in keyof R]: R[K] extends (
-							...args: infer Args
-						) => infer Return
-							? ActorActionFunction<Args, Return>
-							: never;
-					}
-				: {};
+		: ActorActionMap<ActionsOf<AD>>;
 
 type ActorQueueSend<TQueues extends QueueSchemaConfig> = {
 	<K extends keyof TQueues & string>(

package/src/client/actor-handle.ts

@@ -872,8 +872,9 @@ export class ActorHandleRaw {
 			this.#gatewayOptions,
 			options,
 		);
+		const useQueryTarget = isDynamicActorQuery(this.#actorResolutionState);
 		const target = await this.#resolveGatewayRequestTarget(
-			false,
+			useQueryTarget,
 			gatewayOptions,
 		);
 		return await rawWebSocket(

package/src/common/engine.ts

@@ -1,2 +1,29 @@
+export const ENGINE_HOST = "127.0.0.1";
 export const ENGINE_PORT = 6420;
-export const ENGINE_ENDPOINT = `http://127.0.0.1:${ENGINE_PORT}`;
+export const ENGINE_ENDPOINT = buildEngineEndpoint(ENGINE_HOST, ENGINE_PORT);
+
+export function buildEngineEndpoint(host: string, port: number): string {
+	const urlHost =
+		host.includes(":") && !host.startsWith("[") ? `[${host}]` : host;
+	return `http://${urlHost}:${port}`;
+}
+
+export function isLocalEngineEndpoint(endpoint: string): boolean {
+	let url: URL;
+	try {
+		url = new URL(endpoint);
+	} catch {
+		return false;
+	}
+
+	const hostname = url.hostname.toLowerCase();
+	return (
+		hostname === "localhost" ||
+		hostname === "0.0.0.0" ||
+		hostname === "::" ||
+		hostname === "[::]" ||
+		hostname === "::1" ||
+		hostname === "[::1]" ||
+		/^127(?:\.\d{1,3}){0,3}$/.test(hostname)
+	);
+}

package/src/common/utils.ts

@@ -134,7 +134,7 @@ export function deconstructError(
 			actor = error.actor;
 		}
 		metadata = {
-			//url: `https://hub.rivet.dev/projects/${actorMetadata.project.slug}/environments/${actorMetadata.environment.slug}/actors?actorId=${actorMetadata.actor.id}`,
+			//url: `https://dashboard.rivet.dev/projects/${actorMetadata.project.slug}/environments/${actorMetadata.environment.slug}/actors?actorId=${actorMetadata.actor.id}`,
 		} satisfies errors.InternalErrorMetadata;
 	}
 

package/src/devtools-loader/index.ts

@@ -1,16 +1,11 @@
 import type { ClientConfigInput } from "@/client/client";
-import { VERSION } from "@/utils";
 import { logger } from "./log";
 
 declare global {
 	// Injected via tsup config
-	// biome-ignore lint/style/noVar: required for global declaration
 	var CUSTOM_RIVETKIT_DEVTOOLS_URL: string | undefined;
 }
 
-const DEFAULT_DEVTOOLS_URL = (version = VERSION) =>
-	`https://releases.rivet.dev/rivet/latest/devtools/mod.js?v=${version}`;
-
 const scriptId = "rivetkit-devtools-script";
 
 export function injectDevtools(config: ClientConfigInput) {
@@ -20,10 +15,12 @@ export function injectDevtools(config: ClientConfigInput) {
 	}
 
 	if (!document.getElementById(scriptId)) {
+		const src =
+			globalThis.CUSTOM_RIVETKIT_DEVTOOLS_URL ||
+			`${config.endpoint?.replace(/\/$/, "")}/devtools/mod.js`;
 		const script = document.createElement("script");
 		script.id = scriptId;
-		script.src =
-			globalThis.CUSTOM_RIVETKIT_DEVTOOLS_URL || DEFAULT_DEVTOOLS_URL();
+		script.src = src;
 		script.async = true;
 		document.head.appendChild(script);
 	}

package/src/devtools-loader/serve-devtools.ts

@@ -0,0 +1,26 @@
+import { getNodeFs, getNodePath, getNodeUrl } from "@/utils/node";
+
+export async function getDevtoolsPath(): Promise<string> {
+	const url = getNodeUrl();
+	const path = getNodePath();
+
+	const devtoolsPath = path.join(
+		path.dirname(url.fileURLToPath(import.meta.url)),
+		"../../dist/devtools/mod.js",
+	);
+
+	try {
+		await getNodeFs().access(devtoolsPath);
+	} catch {
+		throw new Error(
+			`Devtools bundle not found at ${devtoolsPath}. Run 'pnpm build:pack-devtools' first.`,
+		);
+	}
+
+	return devtoolsPath;
+}
+
+export async function readDevtoolsBundle(): Promise<Buffer> {
+	const devtoolsPath = await getDevtoolsPath();
+	return getNodeFs().readFile(devtoolsPath);
+}

package/src/drivers/engine/actor-driver.ts

@@ -78,7 +78,7 @@ import {
 import { logger } from "./log";
 
 const ENVOY_SSE_PING_INTERVAL = 1000;
-const ENVOY_STOP_WAIT_MS = 15_000;
+const FALLBACK_ENVOY_STOP_WAIT_MS = 15_000;
 const INITIAL_SLEEP_TIMEOUT_MS = 250;
 const REMOTE_ACK_HOOK_QUERY_PARAM = "__rivetkitAckHook";
 
@@ -835,6 +835,7 @@ export class EngineActorDriver implements ActorDriver {
 			return;
 		}
 		this.#isShuttingDown = true;
+		const envoyStopWaitMs = this.#envoyStopWaitMs();
 
 		logger().info({ msg: "stopping engine actor driver", immediate });
 		if (!immediate) {
@@ -849,7 +850,7 @@ export class EngineActorDriver implements ActorDriver {
 				this.startSleep(actorId);
 			}
 
-			const actorSleepDeadline = Date.now() + ENVOY_STOP_WAIT_MS;
+			const actorSleepDeadline = Date.now() + envoyStopWaitMs;
 			while (this.#actors.size > 0 && Date.now() < actorSleepDeadline) {
 				await new Promise((resolve) => setTimeout(resolve, 50));
 			}
@@ -858,7 +859,7 @@ export class EngineActorDriver implements ActorDriver {
 				logger().warn({
 					msg: "timed out waiting for actors to stop before envoy drain",
 					remainingActors: this.#actors.size,
-					waitMs: ENVOY_STOP_WAIT_MS,
+					waitMs: envoyStopWaitMs,
 				});
 				// Snapshot so concurrent removals from `stopActor` do not
 				// invalidate the iterator.
@@ -900,13 +901,13 @@ export class EngineActorDriver implements ActorDriver {
 		const stopped = await Promise.race([
 			this.#envoyStopped.promise.then(() => true),
 			new Promise<false>((resolve) =>
-				setTimeout(() => resolve(false), ENVOY_STOP_WAIT_MS),
+				setTimeout(() => resolve(false), envoyStopWaitMs),
 			),
 		]);
 		if (!stopped) {
 			logger().warn({
 				msg: "timed out waiting for envoy shutdown",
-				waitMs: ENVOY_STOP_WAIT_MS,
+				waitMs: envoyStopWaitMs,
 			});
 		}
 
@@ -917,6 +918,16 @@ export class EngineActorDriver implements ActorDriver {
 		await this.#envoy.started();
 	}
 
+	#envoyStopWaitMs(): number {
+		const actorStopThreshold = Number(
+			this.#envoy.getProtocolMetadata()?.actorStopThreshold,
+		);
+		if (Number.isFinite(actorStopThreshold) && actorStopThreshold > 0) {
+			return actorStopThreshold;
+		}
+		return FALLBACK_ENVOY_STOP_WAIT_MS;
+	}
+
 	async #bindHibernatableConnectSocket(
 		binding: HibernatableConnectBinding,
 		isRestoringHibernatable: boolean,

package/src/engine-client/actor-http-client.ts

@@ -34,9 +34,9 @@ export async function sendHttpRequestToGateway(
 			bodyToSend = reqBody;
 
 			// If this is a streaming request, we need to convert the headers
-			// for the basic array buffer
+			// for the basic array buffer.
 			guardHeaders.delete("transfer-encoding");
-			guardHeaders.set("content-length", String(bodyToSend.byteLength));
+			guardHeaders.delete("content-length");
 		}
 	}
 

package/src/engine-client/api-endpoints.ts

@@ -143,7 +143,11 @@ export async function getRunnerConfig(
 	config: ClientConfig,
 	name: string,
 ): Promise<RunnerConfigsResponse> {
-	return apiCall<never, RunnerConfigsResponse>(config, "GET", `/runner-configs?runner_name=${name}`);
+	return apiCall<never, RunnerConfigsResponse>(
+		config,
+		"GET",
+		`/runner-configs?runner_name=${name}`,
+	);
 }
 
 // MARK: Update runner config

package/src/engine-client/ws-proxy.ts

@@ -68,6 +68,11 @@ export async function createWebSocketProxy(
 					reject(error);
 				});
 			});
+			// Attach a no-op rejection handler so Node.js does not treat this as
+			// an unhandled rejection if onMessage never runs (e.g. the client
+			// disconnects before sending a message). The rejection still propagates
+			// to any caller that awaits connectPromise directly.
+			state.connectPromise.catch(() => {});
 
 			// Setup bidirectional forwarding
 			state.targetWs.addEventListener("message", (event) => {