rivetkit 2.0.42 → 2.1.0-rc.1

package/src/actor/config.ts

@@ -1,4 +1,4 @@
-import { z } from "zod";
+import { z } from "zod/v4";
 import type { UniversalWebSocket } from "@/common/websocket-interface";
 import type { Conn } from "./conn/mod";
 import type {
@@ -13,12 +13,14 @@ import type {
 	DestroyContext,
 	DisconnectContext,
 	RequestContext,
+	RunContext,
 	SleepContext,
 	StateChangeContext,
 	WakeContext,
 	WebSocketContext,
 } from "./contexts";
 import type { AnyDatabaseProvider } from "./database";
+import type { EventSchemaConfig, QueueSchemaConfig } from "./schema";
 
 export interface ActorTypes<
 	TState,
@@ -41,6 +43,133 @@ const zFunction = <
 	T extends (...args: any[]) => any = (...args: unknown[]) => unknown,
 >() => z.custom<T>((val) => typeof val === "function");
 
+export type InspectorUnsubscribe = () => void;
+
+export interface WorkflowInspectorConfig<THistory = unknown> {
+	getHistory: () => THistory | null;
+	onHistoryUpdated?: (
+		listener: (history: THistory) => void,
+	) => InspectorUnsubscribe;
+}
+
+export interface RunInspectorConfig<THistory = unknown> {
+	workflow?: WorkflowInspectorConfig<THistory>;
+}
+
+const WorkflowInspectorConfigSchema = z.object({
+	getHistory: zFunction<WorkflowInspectorConfig<unknown>["getHistory"]>(),
+	onHistoryUpdated:
+		zFunction<
+			NonNullable<WorkflowInspectorConfig<unknown>["onHistoryUpdated"]>
+		>().optional(),
+});
+
+const RunInspectorConfigSchema = z
+	.object({
+		workflow: WorkflowInspectorConfigSchema.optional(),
+	})
+	.optional();
+
+// Schema for run handler with metadata
+export const RunConfigSchema = z.object({
+	/** Display name for the actor in the Inspector UI. */
+	name: z.string().optional(),
+	/** Icon for the actor in the Inspector UI. Can be an emoji or FontAwesome icon name. */
+	icon: z.string().optional(),
+	/** The run handler function. */
+	run: zFunction(),
+	/** Inspector integration for long-running run handlers. */
+	inspector: RunInspectorConfigSchema.optional(),
+});
+type RunConfigRuntime = z.infer<typeof RunConfigSchema>;
+export type RunConfig<
+	TState = unknown,
+	TConnParams = unknown,
+	TConnState = unknown,
+	TVars = unknown,
+	TInput = unknown,
+	TDatabase extends AnyDatabaseProvider = AnyDatabaseProvider,
+	TEvents extends EventSchemaConfig = Record<never, never>,
+	TQueues extends QueueSchemaConfig = Record<never, never>,
+> = Omit<RunConfigRuntime, "run"> & {
+	run: (
+		c: RunContext<
+			TState,
+			TConnParams,
+			TConnState,
+			TVars,
+			TInput,
+			TDatabase,
+			TEvents,
+			TQueues
+		>,
+	) => void | Promise<void>;
+};
+
+type AnyRunConfig = RunConfig<
+	any,
+	any,
+	any,
+	any,
+	any,
+	AnyDatabaseProvider,
+	any,
+	any
+>;
+
+export const RUN_FUNCTION_CONFIG_SYMBOL = Symbol.for(
+	"rivetkit.run_function_config",
+);
+
+interface RunFunctionConfig {
+	name?: string;
+	icon?: string;
+	inspector?: RunInspectorConfig;
+}
+
+type RunFunctionWithConfig = ((...args: any[]) => any) & {
+	[RUN_FUNCTION_CONFIG_SYMBOL]?: RunFunctionConfig;
+};
+
+// Run can be either a function or an object with name/icon/run
+const zRunHandler = z.union([zFunction(), RunConfigSchema]).optional();
+
+/** Extract the run function from either a function or RunConfig object. */
+export function getRunFunction(
+	run: ((...args: any[]) => any) | AnyRunConfig | undefined,
+): ((...args: any[]) => any) | undefined {
+	if (!run) return undefined;
+	if (typeof run === "function") return run;
+	return run.run;
+}
+
+/** Extract run metadata (name/icon) from RunConfig if provided. */
+export function getRunMetadata(
+	run: ((...args: any[]) => any) | AnyRunConfig | undefined,
+): { name?: string; icon?: string } {
+	if (!run) return {};
+	if (typeof run === "function") {
+		const config = (run as RunFunctionWithConfig)[
+			RUN_FUNCTION_CONFIG_SYMBOL
+		];
+		if (!config) return {};
+		return { name: config.name, icon: config.icon };
+	}
+	return { name: run.name, icon: run.icon };
+}
+
+/** Extract run inspector configuration if provided. */
+export function getRunInspectorConfig(
+	run: ((...args: any[]) => any) | AnyRunConfig | undefined,
+): RunInspectorConfig | undefined {
+	if (!run) return undefined;
+	if (typeof run === "function") {
+		return (run as RunFunctionWithConfig)[RUN_FUNCTION_CONFIG_SYMBOL]
+			?.inspector;
+	}
+	return run.inspector;
+}
+
 // This schema is used to validate the input at runtime. The generic types are defined below in `ActorConfig`.
 //
 // We don't use Zod generics with `z.custom` because:
@@ -52,6 +181,7 @@ export const ActorConfigSchema = z
 		onDestroy: zFunction().optional(),
 		onWake: zFunction().optional(),
 		onSleep: zFunction().optional(),
+		run: zRunHandler,
 		onStateChange: zFunction().optional(),
 		onBeforeConnect: zFunction().optional(),
 		onConnect: zFunction().optional(),
@@ -60,6 +190,8 @@ export const ActorConfigSchema = z
 		onRequest: zFunction().optional(),
 		onWebSocket: zFunction().optional(),
 		actions: z.record(z.string(), zFunction()).default(() => ({})),
+		events: z.record(z.string(), z.any()).optional(),
+		queues: z.record(z.string(), z.any()).optional(),
 		state: z.any().optional(),
 		createState: zFunction().optional(),
 		connState: z.any().optional(),
@@ -69,20 +201,32 @@ export const ActorConfigSchema = z
 		createVars: zFunction().optional(),
 		options: z
 			.object({
+				/** Display name for the actor in the Inspector UI. */
+				name: z.string().optional(),
+				/** Icon for the actor in the Inspector UI. Can be an emoji or FontAwesome icon name. */
+				icon: z.string().optional(),
 				createVarsTimeout: z.number().positive().default(5000),
 				createConnStateTimeout: z.number().positive().default(5000),
 				onConnectTimeout: z.number().positive().default(5000),
-				// This must be less than ACTOR_STOP_THRESHOLD_MS
+				// This must be less than engine config > pegboard.actor_stop_threshold
 				onSleepTimeout: z.number().positive().default(5000),
+				// This must be less than engine config > pegboard.actor_stop_threshold
 				onDestroyTimeout: z.number().positive().default(5000),
 				stateSaveInterval: z.number().positive().default(10_000),
 				actionTimeout: z.number().positive().default(60_000),
 				// Max time to wait for waitUntil background promises during shutdown
 				waitUntilTimeout: z.number().positive().default(15_000),
+				// Max time to wait for run handler to stop during shutdown
+				runStopTimeout: z.number().positive().default(15_000),
 				connectionLivenessTimeout: z.number().positive().default(2500),
 				connectionLivenessInterval: z.number().positive().default(5000),
 				noSleep: z.boolean().default(false),
 				sleepTimeout: z.number().positive().default(30_000),
+				maxQueueSize: z.number().positive().default(1000),
+				maxQueueMessageSize: z
+					.number()
+					.positive()
+					.default(64 * 1024),
 				/**
 				 * Can hibernate WebSockets for onWebSocket.
 				 *
@@ -139,14 +283,16 @@ type CreateState<
 	TVars,
 	TInput,
 	TDatabase extends AnyDatabaseProvider,
+	TEvents extends EventSchemaConfig,
+	TQueues extends QueueSchemaConfig,
 > =
 	| { state: TState }
 	| {
-			createState: (
-				c: CreateContext<TState, TInput, TDatabase>,
-				input: TInput,
-			) => TState | Promise<TState>;
-	  }
+		createState: (
+			c: CreateContext<TState, TInput, TDatabase, TEvents, TQueues>,
+			input: TInput,
+		) => TState | Promise<TState>;
+	}
 	| Record<never, never>;
 
 // Creates connection state config
@@ -161,14 +307,23 @@ type CreateConnState<
 	TVars,
 	TInput,
 	TDatabase extends AnyDatabaseProvider,
+	TEvents extends EventSchemaConfig,
+	TQueues extends QueueSchemaConfig,
 > =
 	| { connState: TConnState }
 	| {
-			createConnState: (
-				c: CreateConnStateContext<TState, TVars, TInput, TDatabase>,
-				params: TConnParams,
-			) => TConnState | Promise<TConnState>;
-	  }
+		createConnState: (
+			c: CreateConnStateContext<
+				TState,
+				TVars,
+				TInput,
+				TDatabase,
+				TEvents,
+				TQueues
+			>,
+			params: TConnParams,
+		) => TConnState | Promise<TConnState>;
+	}
 	| Record<never, never>;
 
 // Creates vars config
@@ -184,22 +339,30 @@ type CreateVars<
 	TVars,
 	TInput,
 	TDatabase extends AnyDatabaseProvider,
+	TEvents extends EventSchemaConfig,
+	TQueues extends QueueSchemaConfig,
 > =
 	| {
-			/**
-			 * @experimental
-			 */
-			vars: TVars;
-	  }
+		/**
+		 * @experimental
+		 */
+		vars: TVars;
+	}
 	| {
-			/**
-			 * @experimental
-			 */
-			createVars: (
-				c: CreateVarsContext<TState, TInput, TDatabase>,
-				driverCtx: any,
-			) => TVars | Promise<TVars>;
-	  }
+		/**
+		 * @experimental
+		 */
+		createVars: (
+			c: CreateVarsContext<
+				TState,
+				TInput,
+				TDatabase,
+				TEvents,
+				TQueues
+			>,
+			driverCtx: any,
+		) => TVars | Promise<TVars>;
+	}
 	| Record<never, never>;
 
 export interface Actions<
@@ -209,6 +372,8 @@ export interface Actions<
 	TVars,
 	TInput,
 	TDatabase extends AnyDatabaseProvider,
+	TEvents extends EventSchemaConfig = Record<never, never>,
+	TQueues extends QueueSchemaConfig = Record<never, never>,
 > {
 	[Action: string]: (
 		c: ActionContext<
@@ -217,7 +382,9 @@ export interface Actions<
 			TConnState,
 			TVars,
 			TInput,
-			TDatabase
+			TDatabase,
+			TEvents,
+			TQueues
 		>,
 		...args: any[]
 	) => any;
@@ -240,13 +407,17 @@ interface BaseActorConfig<
 	TVars,
 	TInput,
 	TDatabase extends AnyDatabaseProvider,
+	TEvents extends EventSchemaConfig,
+	TQueues extends QueueSchemaConfig,
 	TActions extends Actions<
 		TState,
 		TConnParams,
 		TConnState,
 		TVars,
 		TInput,
-		TDatabase
+		TDatabase,
+		TEvents,
+		TQueues
 	>,
 > {
 	/**
@@ -256,7 +427,7 @@ interface BaseActorConfig<
 	 * This is called before any other lifecycle hooks.
 	 */
 	onCreate?: (
-		c: CreateContext<TState, TInput, TDatabase>,
+		c: CreateContext<TState, TInput, TDatabase, TEvents, TQueues>,
 		input: TInput,
 	) => void | Promise<void>;
 
@@ -270,7 +441,9 @@ interface BaseActorConfig<
 			TConnState,
 			TVars,
 			TInput,
-			TDatabase
+			TDatabase,
+			TEvents,
+			TQueues
 		>,
 	) => void | Promise<void>;
 
@@ -289,7 +462,9 @@ interface BaseActorConfig<
 			TConnState,
 			TVars,
 			TInput,
-			TDatabase
+			TDatabase,
+			TEvents,
+			TQueues
 		>,
 	) => void | Promise<void>;
 
@@ -310,10 +485,59 @@ interface BaseActorConfig<
 			TConnState,
 			TVars,
 			TInput,
-			TDatabase
+			TDatabase,
+			TEvents,
+			TQueues
 		>,
 	) => void | Promise<void>;
 
+	/**
+	 * Called after the actor starts up. Does not block actor startup.
+	 *
+	 * Use this for background tasks like:
+	 * - Reading from queues in a loop
+	 * - Tick loops for periodic work
+	 * - Custom workflow logic
+	 *
+	 * **Important:** The actor may go to sleep at any time during the `run`
+	 * handler. Use `c.keepAwake(promise)` to wrap async operations that should
+	 * not be interrupted by sleep.
+	 *
+	 * The handler receives an abort signal via `c.abortSignal` and a
+	 * `c.aborted` alias for loop checks. Use these to gracefully exit.
+	 *
+	 * If this handler exits or throws, the actor will crash and reschedule.
+	 * On shutdown, the actor waits for this handler to complete with a
+	 * configurable timeout (options.runStopTimeout, default 15s).
+	 *
+	 * Can be either a function or a RunConfig object with optional name/icon metadata.
+	 *
+	 * @returns Void or a Promise. If the promise exits, the actor crashes.
+	 */
+	run?:
+	| ((
+		c: RunContext<
+			TState,
+			TConnParams,
+			TConnState,
+			TVars,
+			TInput,
+			TDatabase,
+			TEvents,
+			TQueues
+		>,
+	) => void | Promise<void>)
+	| RunConfig<
+		TState,
+		TConnParams,
+		TConnState,
+		TVars,
+		TInput,
+		TDatabase,
+		TEvents,
+		TQueues
+	>;
+
 	/**
 	 * Called when the actor's state changes.
 	 *
@@ -332,7 +556,9 @@ interface BaseActorConfig<
 			TConnState,
 			TVars,
 			TInput,
-			TDatabase
+			TDatabase,
+			TEvents,
+			TQueues
 		>,
 		newState: TState,
 	) => void;
@@ -348,7 +574,14 @@ interface BaseActorConfig<
 	 * @throws Throw an error to reject the connection
 	 */
 	onBeforeConnect?: (
-		c: BeforeConnectContext<TState, TVars, TInput, TDatabase>,
+		c: BeforeConnectContext<
+			TState,
+			TVars,
+			TInput,
+			TDatabase,
+			TEvents,
+			TQueues
+		>,
 		params: TConnParams,
 	) => void | Promise<void>;
 
@@ -368,9 +601,20 @@ interface BaseActorConfig<
 			TConnState,
 			TVars,
 			TInput,
-			TDatabase
+			TDatabase,
+			TEvents,
+			TQueues
+		>,
+		conn: Conn<
+			TState,
+			TConnParams,
+			TConnState,
+			TVars,
+			TInput,
+			TDatabase,
+			TEvents,
+			TQueues
 		>,
-		conn: Conn<TState, TConnParams, TConnState, TVars, TInput, TDatabase>,
 	) => void | Promise<void>;
 
 	/**
@@ -389,9 +633,20 @@ interface BaseActorConfig<
 			TConnState,
 			TVars,
 			TInput,
-			TDatabase
+			TDatabase,
+			TEvents,
+			TQueues
+		>,
+		conn: Conn<
+			TState,
+			TConnParams,
+			TConnState,
+			TVars,
+			TInput,
+			TDatabase,
+			TEvents,
+			TQueues
 		>,
-		conn: Conn<TState, TConnParams, TConnState, TVars, TInput, TDatabase>,
 	) => void | Promise<void>;
 
 	/**
@@ -413,7 +668,9 @@ interface BaseActorConfig<
 			TConnState,
 			TVars,
 			TInput,
-			TDatabase
+			TDatabase,
+			TEvents,
+			TQueues
 		>,
 		name: string,
 		args: unknown[],
@@ -438,7 +695,9 @@ interface BaseActorConfig<
 			TConnState,
 			TVars,
 			TInput,
-			TDatabase
+			TDatabase,
+			TEvents,
+			TQueues
 		>,
 		request: Request,
 	) => Response | Promise<Response>;
@@ -460,21 +719,33 @@ interface BaseActorConfig<
 			TConnState,
 			TVars,
 			TInput,
-			TDatabase
+			TDatabase,
+			TEvents,
+			TQueues
 		>,
 		websocket: UniversalWebSocket,
 	) => void | Promise<void>;
 
 	actions?: TActions;
+
+	/**
+	 * Schema map for events broadcasted by this actor.
+	 */
+	events?: TEvents;
+
+	/**
+	 * Schema map for queue payloads sent by this actor.
+	 */
+	queues?: TQueues;
 }
 
 type ActorDatabaseConfig<TDatabase extends AnyDatabaseProvider> =
 	| {
-			/**
-			 * @experimental
-			 */
-			db: TDatabase;
-	  }
+		/**
+		 * @experimental
+		 */
+		db: TDatabase;
+	}
 	| Record<never, never>;
 
 // 1. Infer schema
@@ -487,12 +758,18 @@ export type ActorConfig<
 	TVars,
 	TInput,
 	TDatabase extends AnyDatabaseProvider,
+	TEvents extends EventSchemaConfig = Record<never, never>,
+	TQueues extends QueueSchemaConfig = Record<never, never>,
 > = Omit<
 	z.infer<typeof ActorConfigSchema>,
 	| "actions"
+	| "events"
+	| "queues"
 	| "onCreate"
 	| "onDestroy"
 	| "onWake"
+	| "onSleep"
+	| "run"
 	| "onStateChange"
 	| "onBeforeConnect"
 	| "onConnect"
@@ -515,11 +792,49 @@ export type ActorConfig<
 		TVars,
 		TInput,
 		TDatabase,
-		Actions<TState, TConnParams, TConnState, TVars, TInput, TDatabase>
+		TEvents,
+		TQueues,
+		Actions<
+			TState,
+			TConnParams,
+			TConnState,
+			TVars,
+			TInput,
+			TDatabase,
+			TEvents,
+			TQueues
+		>
+	> &
+	CreateState<
+		TState,
+		TConnParams,
+		TConnState,
+		TVars,
+		TInput,
+		TDatabase,
+		TEvents,
+		TQueues
+	> &
+	CreateConnState<
+		TState,
+		TConnParams,
+		TConnState,
+		TVars,
+		TInput,
+		TDatabase,
+		TEvents,
+		TQueues
+	> &
+	CreateVars<
+		TState,
+		TConnParams,
+		TConnState,
+		TVars,
+		TInput,
+		TDatabase,
+		TEvents,
+		TQueues
 	> &
-	CreateState<TState, TConnParams, TConnState, TVars, TInput, TDatabase> &
-	CreateConnState<TState, TConnParams, TConnState, TVars, TInput, TDatabase> &
-	CreateVars<TState, TConnParams, TConnState, TVars, TInput, TDatabase> &
 	ActorDatabaseConfig<TDatabase>;
 
 // See description on `ActorConfig`
@@ -530,13 +845,17 @@ export type ActorConfigInput<
 	TVars = undefined,
 	TInput = undefined,
 	TDatabase extends AnyDatabaseProvider = undefined,
+	TEvents extends EventSchemaConfig = Record<never, never>,
+	TQueues extends QueueSchemaConfig = Record<never, never>,
 	TActions extends Actions<
 		TState,
 		TConnParams,
 		TConnState,
 		TVars,
 		TInput,
-		TDatabase
+		TDatabase,
+		TEvents,
+		TQueues
 	> = Record<never, never>,
 > = {
 	types?: ActorTypes<
@@ -550,10 +869,13 @@ export type ActorConfigInput<
 } & Omit<
 	z.input<typeof ActorConfigSchema>,
 	| "actions"
+	| "events"
+	| "queues"
 	| "onCreate"
 	| "onDestroy"
 	| "onWake"
 	| "onSleep"
+	| "run"
 	| "onStateChange"
 	| "onBeforeConnect"
 	| "onConnect"
@@ -576,11 +898,40 @@ export type ActorConfigInput<
 		TVars,
 		TInput,
 		TDatabase,
+		TEvents,
+		TQueues,
 		TActions
 	> &
-	CreateState<TState, TConnParams, TConnState, TVars, TInput, TDatabase> &
-	CreateConnState<TState, TConnParams, TConnState, TVars, TInput, TDatabase> &
-	CreateVars<TState, TConnParams, TConnState, TVars, TInput, TDatabase> &
+	CreateState<
+		TState,
+		TConnParams,
+		TConnState,
+		TVars,
+		TInput,
+		TDatabase,
+		TEvents,
+		TQueues
+	> &
+	CreateConnState<
+		TState,
+		TConnParams,
+		TConnState,
+		TVars,
+		TInput,
+		TDatabase,
+		TEvents,
+		TQueues
+	> &
+	CreateVars<
+		TState,
+		TConnParams,
+		TConnState,
+		TVars,
+		TInput,
+		TDatabase,
+		TEvents,
+		TQueues
+	> &
 	ActorDatabaseConfig<TDatabase>;
 
 // For testing type definitions:
@@ -591,13 +942,17 @@ export function test<
 	TVars,
 	TInput,
 	TDatabase extends AnyDatabaseProvider,
+	TEvents extends EventSchemaConfig,
+	TQueues extends QueueSchemaConfig,
 	TActions extends Actions<
 		TState,
 		TConnParams,
 		TConnState,
 		TVars,
 		TInput,
-		TDatabase
+		TDatabase,
+		TEvents,
+		TQueues
 	>,
 >(
 	input: ActorConfigInput<
@@ -607,16 +962,29 @@ export function test<
 		TVars,
 		TInput,
 		TDatabase,
+		TEvents,
+		TQueues,
 		TActions
 	>,
-): ActorConfig<TState, TConnParams, TConnState, TVars, TInput, TDatabase> {
+): ActorConfig<
+	TState,
+	TConnParams,
+	TConnState,
+	TVars,
+	TInput,
+	TDatabase,
+	TEvents,
+	TQueues
+> {
 	const config = ActorConfigSchema.parse(input) as ActorConfig<
 		TState,
 		TConnParams,
 		TConnState,
 		TVars,
 		TInput,
-		TDatabase
+		TDatabase,
+		TEvents,
+		TQueues
 	>;
 	return config;
 }
@@ -627,6 +995,16 @@ export function test<
 
 export const DocActorOptionsSchema = z
 	.object({
+		name: z
+			.string()
+			.optional()
+			.describe("Display name for the actor in the Inspector UI."),
+		icon: z
+			.string()
+			.optional()
+			.describe(
+				"Icon for the actor in the Inspector UI. Can be an emoji (e.g., '🚀') or FontAwesome icon name (e.g., 'rocket').",
+			),
 		createVarsTimeout: z
 			.number()
 			.optional()
@@ -667,6 +1045,12 @@ export const DocActorOptionsSchema = z
 			.describe(
 				"Max time in ms to wait for waitUntil background promises during shutdown. Default: 15000",
 			),
+		runStopTimeout: z
+			.number()
+			.optional()
+			.describe(
+				"Max time in ms to wait for run handler to stop during shutdown. Default: 15000",
+			),
 		connectionLivenessTimeout: z
 			.number()
 			.optional()
@@ -689,6 +1073,18 @@ export const DocActorOptionsSchema = z
 			.describe(
 				"Time in ms of inactivity before the actor sleeps. Default: 30000",
 			),
+		maxQueueSize: z
+			.number()
+			.optional()
+			.describe(
+				"Maximum number of queue messages before rejecting new messages. Default: 1000",
+			),
+		maxQueueMessageSize: z
+			.number()
+			.optional()
+			.describe(
+				"Maximum size of each queue message in bytes. Default: 65536",
+			),
 		canHibernateWebSocket: z
 			.boolean()
 			.optional()
@@ -762,22 +1158,28 @@ export const DocActorConfigSchema = z
 			.describe(
 				"Called when the actor is stopping or sleeping. Use to clean up resources.",
 			),
-		onStateChange: z
+		run: z
 			.unknown()
 			.optional()
 			.describe(
-				"Called when the actor's state changes. State changes within this hook won't trigger recursion.",
+				"Called after actor starts. Does not block startup. Use for background tasks like queue processing or tick loops. If it exits or throws, the actor crashes.",
 			),
-		onBeforeConnect: z
-			.unknown()
-			.optional()
-			.describe(
-				"Called before a client connects. Throw an error to reject the connection.",
-			),
-		onConnect: z
-			.unknown()
-			.optional()
-			.describe("Called when a client successfully connects."),
+			onStateChange: z
+				.unknown()
+				.optional()
+				.describe(
+					"Called when the actor's state changes. State changes within this hook won't trigger recursion.",
+				),
+			onBeforeConnect: z
+				.unknown()
+				.optional()
+				.describe(
+					"Called before a client connects. Throw an error to reject the connection.",
+				),
+			onConnect: z
+				.unknown()
+				.optional()
+				.describe("Called when a client successfully connects."),
 		onDisconnect: z
 			.unknown()
 			.optional()
@@ -806,6 +1208,14 @@ export const DocActorConfigSchema = z
 			.describe(
 				"Map of action name to handler function. Defaults to an empty object.",
 			),
+		events: z
+			.record(z.string(), z.unknown())
+			.optional()
+			.describe("Map of event names to schemas."),
+		queues: z
+			.record(z.string(), z.unknown())
+			.optional()
+			.describe("Map of queue names to schemas."),
 		options: DocActorOptionsSchema.optional(),
 	})
 	.describe("Actor configuration passed to the actor() function.");