@rivetkit/engine-runner 0.0.0-main.d6a0ba8

package/dist/mod.d.cts

@@ -0,0 +1,324 @@
+import * as protocol from '@rivetkit/engine-runner-protocol';
+import { GatewayId, RequestId } from '@rivetkit/engine-runner-protocol';
+import { Logger } from 'pino';
+import WebSocket from 'ws';
+import { UniversalWebSocket } from '@rivetkit/virtual-websocket';
+
+interface PendingRequest {
+    resolve: (response: Response) => void;
+    reject: (error: Error) => void;
+    streamController?: ReadableStreamDefaultController<Uint8Array>;
+    actorId?: string;
+    gatewayId?: GatewayId;
+    requestId?: RequestId;
+    clientMessageIndex: number;
+}
+interface HibernatingWebSocketMetadata {
+    gatewayId: GatewayId;
+    requestId: RequestId;
+    clientMessageIndex: number;
+    serverMessageIndex: number;
+    path: string;
+    headers: Record<string, string>;
+}
+declare class Tunnel {
+    #private;
+    get log(): Logger | undefined;
+    constructor(runner: Runner);
+    start(): void;
+    resendBufferedEvents(): void;
+    shutdown(): void;
+    restoreHibernatingRequests(actorId: string, metaEntries: HibernatingWebSocketMetadata[]): Promise<void>;
+    addRequestToActor(gatewayId: GatewayId, requestId: RequestId, actorId: string): void;
+    getRequestActor(gatewayId: GatewayId, requestId: RequestId): RunnerActor | undefined;
+    getAndWaitForRequestActor(gatewayId: GatewayId, requestId: RequestId): Promise<RunnerActor | undefined>;
+    closeActiveRequests(actor: RunnerActor): void;
+    handleTunnelMessage(message: protocol.ToClientTunnelMessage): Promise<void>;
+    sendHibernatableWebSocketMessageAck(gatewayId: ArrayBuffer, requestId: ArrayBuffer, clientMessageIndex: number): void;
+}
+
+/**
+ * Polyfill for Promise.withResolvers().
+ *
+ * This is specifically for Cloudflare Workers. Their implementation of Promise.withResolvers does not work correctly.
+ */
+declare function promiseWithResolvers<T>(): {
+    promise: Promise<T>;
+    resolve: (value: T | PromiseLike<T>) => void;
+    reject: (reason?: any) => void;
+};
+declare function idToStr(id: ArrayBuffer): string;
+
+declare const HIBERNATABLE_SYMBOL: unique symbol;
+declare class WebSocketTunnelAdapter {
+    #private;
+    readonly request: Request;
+    get [HIBERNATABLE_SYMBOL](): boolean;
+    constructor(tunnel: Tunnel, actorId: string, requestId: string, serverMessageIndex: number, hibernatable: boolean, isRestoringHibernatable: boolean, request: Request, sendCallback: (data: ArrayBuffer | string, isBinary: boolean) => void, closeCallback: (code?: number, reason?: string) => void);
+    get websocket(): UniversalWebSocket;
+    _handleOpen(requestId: ArrayBuffer): void;
+    _handleMessage(requestId: ArrayBuffer, data: string | Uint8Array, serverMessageIndex: number, isBinary: boolean): boolean;
+    _handleClose(_requestId: ArrayBuffer, code?: number, reason?: string): void;
+    _closeWithoutCallback(code?: number, reason?: string): void;
+    close(code?: number, reason?: string): void;
+}
+
+interface ActorConfig {
+    name: string;
+    key: string | null;
+    createTs: bigint;
+    input: Uint8Array | null;
+}
+declare class RunnerActor {
+    /**
+     * List of hibernating requests provided by the gateway on actor start.
+     * This represents the WebSocket connections that the gateway knows about.
+     **/
+    hibernatingRequests: readonly protocol.HibernatingRequest[];
+    actorId: string;
+    generation: number;
+    config: ActorConfig;
+    pendingRequests: Array<{
+        gatewayId: protocol.GatewayId;
+        requestId: protocol.RequestId;
+        request: PendingRequest;
+    }>;
+    webSockets: Array<{
+        gatewayId: protocol.GatewayId;
+        requestId: protocol.RequestId;
+        ws: WebSocketTunnelAdapter;
+    }>;
+    actorStartPromise: ReturnType<typeof promiseWithResolvers<void>>;
+    lastCommandIdx: bigint;
+    nextEventIdx: bigint;
+    eventHistory: protocol.EventWrapper[];
+    /**
+     * If restoreHibernatingRequests has been called. This is used to assert
+     * that the caller is implemented correctly.
+     **/
+    hibernationRestored: boolean;
+    /**
+     * Set when the actor has explicitly requested to stop (e.g. c.destroy()).
+     * Used to send StopCode.Ok (graceful) vs StopCode.Error (ungraceful) so
+     * the engine crash policy handles sleepable actors correctly.
+     **/
+    stopIntentSent: boolean;
+    constructor(actorId: string, generation: number, config: ActorConfig, 
+    /**
+     * List of hibernating requests provided by the gateway on actor start.
+     * This represents the WebSocket connections that the gateway knows about.
+     **/
+    hibernatingRequests: readonly protocol.HibernatingRequest[]);
+    getPendingRequest(gatewayId: protocol.GatewayId, requestId: protocol.RequestId): PendingRequest | undefined;
+    createPendingRequest(gatewayId: protocol.GatewayId, requestId: protocol.RequestId, clientMessageIndex: number): void;
+    createPendingRequestWithStreamController(gatewayId: protocol.GatewayId, requestId: protocol.RequestId, clientMessageIndex: number, streamController: ReadableStreamDefaultController<Uint8Array>): void;
+    deletePendingRequest(gatewayId: protocol.GatewayId, requestId: protocol.RequestId): void;
+    getWebSocket(gatewayId: protocol.GatewayId, requestId: protocol.RequestId): WebSocketTunnelAdapter | undefined;
+    setWebSocket(gatewayId: protocol.GatewayId, requestId: protocol.RequestId, ws: WebSocketTunnelAdapter): void;
+    deleteWebSocket(gatewayId: protocol.GatewayId, requestId: protocol.RequestId): void;
+    handleAckEvents(lastEventIdx: bigint): void;
+    recordEvent(eventWrapper: protocol.EventWrapper): void;
+}
+
+declare class RunnerShutdownError extends Error {
+    constructor();
+}
+interface RunnerConfig {
+    logger?: Logger;
+    version: number;
+    endpoint: string;
+    token?: string;
+    pegboardEndpoint?: string;
+    pegboardRelayEndpoint?: string;
+    namespace: string;
+    totalSlots: number;
+    runnerName: string;
+    prepopulateActorNames: Record<string, {
+        metadata: Record<string, any>;
+    }>;
+    metadata?: Record<string, any>;
+    onConnected: () => void;
+    onDisconnected: (code: number, reason: string) => void;
+    onShutdown: () => void;
+    /** Called when receiving a network request. */
+    fetch: (runner: Runner, actorId: string, gatewayId: protocol.GatewayId, requestId: protocol.RequestId, request: Request) => Promise<Response>;
+    /**
+     * Called when receiving a WebSocket connection.
+     *
+     * All event listeners must be added synchronously inside this function or
+     * else events may be missed. The open event will fire immediately after
+     * this function finishes.
+     *
+     * Any errors thrown here will disconnect the WebSocket immediately.
+     *
+     * While `path` and `headers` are partially redundant to the data in the
+     * `Request`, they may vary slightly from the actual content of `Request`.
+     * Prefer to persist the `path` and `headers` properties instead of the
+     * `Request` itself.
+     *
+     * ## Hibernating Web Sockets
+     *
+     * ### Implementation Requirements
+     *
+     * **Requirement 1: Persist HWS Immediately**
+     *
+     * This is responsible for persisting hibernatable WebSockets immediately
+     * (do not wait for open event). It is not time sensitive to flush the
+     * connection state. If this fails to persist the HWS, the client's
+     * WebSocket will be disconnected on next wake in the call to
+     * `Tunnel::restoreHibernatingRequests` since the connection entry will not
+     * exist.
+     *
+     * **Requirement 2: Persist Message Index On `message`**
+     *
+     * In the `message` event listener, this handler must persist the message
+     * index from the event. The request ID is available at
+     * `event.rivetRequestId` and message index at `event.rivetMessageIndex`.
+     *
+     * The message index should not be flushed immediately. Instead, this
+     * should:
+     *
+     * - Debounce calls to persist the message index
+     * - After each persist, call
+     *   `Runner::sendHibernatableWebSocketMessageAck` to acknowledge the
+     *   message
+     *
+     * This mechanism allows us to buffer messages on the gateway so we can
+     * batch-persist events on our end on a given interval.
+     *
+     * If this fails to persist, then the gateway will replay unacked
+     * messages when the actor starts again.
+     *
+     * **Requirement 3: Remove HWS From Storage On `close`**
+     *
+     * This handler should add an event listener for `close` to remove the
+     * connection from storage.
+     *
+     * If the connection remove fails to persist, the close event will be
+     * called again on the next actor start in
+     * `Tunnel::restoreHibernatingRequests` since there will be no request for
+     * the given connection.
+     *
+     * ### Restoring Connections
+     *
+     * The user of this library is responsible for:
+     * 1. Loading all persisted hibernatable WebSocket metadata for an actor
+     * 2. Calling `Runner::restoreHibernatingRequests` with this metadata at
+     *    the end of `onActorStart`
+     *
+     * `restoreHibernatingRequests` will restore all connections and attach
+     * the appropriate event listeners.
+     *
+     * ### No Open Event On Restoration
+     *
+     * When restoring a HWS, the open event will not be called again. It will
+     * go straight to the message or close event.
+     */
+    websocket: (runner: Runner, actorId: string, ws: any, gatewayId: protocol.GatewayId, requestId: protocol.RequestId, request: Request, path: string, headers: Record<string, string>, isHibernatable: boolean, isRestoringHibernatable: boolean) => Promise<void>;
+    hibernatableWebSocket: {
+        /**
+         * Determines if a WebSocket can continue to live while an actor goes to
+         * sleep.
+         */
+        canHibernate: (actorId: string, gatewayId: ArrayBuffer, requestId: ArrayBuffer, request: Request) => boolean;
+    };
+    /**
+     * Called when an actor starts.
+     *
+     * This callback is responsible for:
+     * 1. Initializing the actor instance
+     * 2. Loading all persisted hibernatable WebSocket metadata for this actor
+     * 3. Calling `Runner::restoreHibernatingRequests` with the loaded metadata
+     *    to restore hibernatable WebSocket connections
+     *
+     * The actor should not be marked as "ready" until after
+     * `restoreHibernatingRequests` completes to ensure all hibernatable
+     * connections are fully restored before the actor processes new requests.
+     */
+    onActorStart: (actorId: string, generation: number, config: ActorConfig) => Promise<void>;
+    onActorStop: (actorId: string, generation: number) => Promise<void>;
+    noAutoShutdown?: boolean;
+    /**
+     * Debug option to inject artificial latency (in ms) into WebSocket
+     * communication. Messages are queued and delivered in order after the
+     * configured delay.
+     *
+     * @experimental For testing only.
+     */
+    debugLatencyMs?: number;
+}
+interface KvListOptions {
+    reverse?: boolean;
+    limit?: number;
+}
+declare class Runner {
+    #private;
+    get config(): RunnerConfig;
+    runnerId?: string;
+    get log(): Logger | undefined;
+    constructor(config: RunnerConfig);
+    sleepActor(actorId: string, generation?: number): void;
+    stopActor(actorId: string, generation?: number): Promise<void>;
+    /**
+     * Like stopActor but marks the actor for graceful destruction.
+     * This ensures the engine destroys the actor instead of sleeping it.
+     *
+     * NOTE: If a drain (GoingAway) occurs after this is called but before the
+     * stop completes, the engine's going_away flag overrides graceful_exit and
+     * the actor will sleep instead of being destroyed. The destroy intent is
+     * lost in this race. This is acceptable since the actor will be rescheduled
+     * elsewhere and can be destroyed on the next wake.
+     */
+    destroyActor(actorId: string, generation?: number): void;
+    forceStopActor(actorId: string, generation?: number): Promise<void>;
+    getActor(actorId: string, generation?: number): RunnerActor | undefined;
+    getAndWaitForActor(actorId: string, generation?: number): Promise<RunnerActor | undefined>;
+    hasActor(actorId: string, generation?: number): boolean;
+    get actors(): Map<string, RunnerActor>;
+    start(): Promise<void>;
+    shutdown(immediate: boolean, exit?: boolean): Promise<void>;
+    get pegboardEndpoint(): string;
+    get pegboardUrl(): string;
+    kvGet(actorId: string, keys: Uint8Array[]): Promise<(Uint8Array | null)[]>;
+    kvListAll(actorId: string, options?: KvListOptions): Promise<[Uint8Array, Uint8Array][]>;
+    kvListRange(actorId: string, start: Uint8Array, end: Uint8Array, exclusive?: boolean, options?: KvListOptions): Promise<[Uint8Array, Uint8Array][]>;
+    kvListPrefix(actorId: string, prefix: Uint8Array, options?: KvListOptions): Promise<[Uint8Array, Uint8Array][]>;
+    kvPut(actorId: string, entries: [Uint8Array, Uint8Array][]): Promise<void>;
+    kvDelete(actorId: string, keys: Uint8Array[]): Promise<void>;
+    kvDeleteRange(actorId: string, start: Uint8Array, end: Uint8Array): Promise<void>;
+    kvDrop(actorId: string): Promise<void>;
+    setAlarm(actorId: string, alarmTs: number | null, generation?: number): void;
+    clearAlarm(actorId: string, generation?: number): void;
+    /** Asserts WebSocket exists and is ready. */
+    getPegboardWebSocketIfReady(): WebSocket | undefined;
+    __sendToServer(message: protocol.ToServer): void;
+    sendHibernatableWebSocketMessageAck(gatewayId: ArrayBuffer, requestId: ArrayBuffer, index: number): void;
+    /**
+     * Restores hibernatable WebSocket connections for an actor.
+     *
+     * This method should be called at the end of `onActorStart` after the
+     * actor instance is fully initialized.
+     *
+     * This method will:
+     * - Restore all provided hibernatable WebSocket connections
+     * - Attach event listeners to the restored WebSockets
+     * - Close any WebSocket connections that failed to restore
+     *
+     * The provided metadata list should include all hibernatable WebSockets
+     * that were persisted for this actor. The gateway will automatically
+     * close any connections that are not restored (i.e., not included in
+     * this list).
+     *
+     * **Important:** This method must be called after `onActorStart` completes
+     * and before marking the actor as "ready" to ensure all hibernatable
+     * connections are fully restored.
+     *
+     * @param actorId - The ID of the actor to restore connections for
+     * @param metaEntries - Array of hibernatable WebSocket metadata to restore
+     */
+    restoreHibernatingRequests(actorId: string, metaEntries: HibernatingWebSocketMetadata[]): Promise<void>;
+    getServerlessInitPacket(): string | undefined;
+    getProtocolMetadata(): protocol.ProtocolMetadata | undefined;
+}
+
+export { type ActorConfig, type HibernatingWebSocketMetadata, type KvListOptions, Runner, RunnerActor, type RunnerConfig, RunnerShutdownError, idToStr };

package/dist/mod.d.ts

@@ -0,0 +1,324 @@
+import * as protocol from '@rivetkit/engine-runner-protocol';
+import { GatewayId, RequestId } from '@rivetkit/engine-runner-protocol';
+import { Logger } from 'pino';
+import WebSocket from 'ws';
+import { UniversalWebSocket } from '@rivetkit/virtual-websocket';
+
+interface PendingRequest {
+    resolve: (response: Response) => void;
+    reject: (error: Error) => void;
+    streamController?: ReadableStreamDefaultController<Uint8Array>;
+    actorId?: string;
+    gatewayId?: GatewayId;
+    requestId?: RequestId;
+    clientMessageIndex: number;
+}
+interface HibernatingWebSocketMetadata {
+    gatewayId: GatewayId;
+    requestId: RequestId;
+    clientMessageIndex: number;
+    serverMessageIndex: number;
+    path: string;
+    headers: Record<string, string>;
+}
+declare class Tunnel {
+    #private;
+    get log(): Logger | undefined;
+    constructor(runner: Runner);
+    start(): void;
+    resendBufferedEvents(): void;
+    shutdown(): void;
+    restoreHibernatingRequests(actorId: string, metaEntries: HibernatingWebSocketMetadata[]): Promise<void>;
+    addRequestToActor(gatewayId: GatewayId, requestId: RequestId, actorId: string): void;
+    getRequestActor(gatewayId: GatewayId, requestId: RequestId): RunnerActor | undefined;
+    getAndWaitForRequestActor(gatewayId: GatewayId, requestId: RequestId): Promise<RunnerActor | undefined>;
+    closeActiveRequests(actor: RunnerActor): void;
+    handleTunnelMessage(message: protocol.ToClientTunnelMessage): Promise<void>;
+    sendHibernatableWebSocketMessageAck(gatewayId: ArrayBuffer, requestId: ArrayBuffer, clientMessageIndex: number): void;
+}
+
+/**
+ * Polyfill for Promise.withResolvers().
+ *
+ * This is specifically for Cloudflare Workers. Their implementation of Promise.withResolvers does not work correctly.
+ */
+declare function promiseWithResolvers<T>(): {
+    promise: Promise<T>;
+    resolve: (value: T | PromiseLike<T>) => void;
+    reject: (reason?: any) => void;
+};
+declare function idToStr(id: ArrayBuffer): string;
+
+declare const HIBERNATABLE_SYMBOL: unique symbol;
+declare class WebSocketTunnelAdapter {
+    #private;
+    readonly request: Request;
+    get [HIBERNATABLE_SYMBOL](): boolean;
+    constructor(tunnel: Tunnel, actorId: string, requestId: string, serverMessageIndex: number, hibernatable: boolean, isRestoringHibernatable: boolean, request: Request, sendCallback: (data: ArrayBuffer | string, isBinary: boolean) => void, closeCallback: (code?: number, reason?: string) => void);
+    get websocket(): UniversalWebSocket;
+    _handleOpen(requestId: ArrayBuffer): void;
+    _handleMessage(requestId: ArrayBuffer, data: string | Uint8Array, serverMessageIndex: number, isBinary: boolean): boolean;
+    _handleClose(_requestId: ArrayBuffer, code?: number, reason?: string): void;
+    _closeWithoutCallback(code?: number, reason?: string): void;
+    close(code?: number, reason?: string): void;
+}
+
+interface ActorConfig {
+    name: string;
+    key: string | null;
+    createTs: bigint;
+    input: Uint8Array | null;
+}
+declare class RunnerActor {
+    /**
+     * List of hibernating requests provided by the gateway on actor start.
+     * This represents the WebSocket connections that the gateway knows about.
+     **/
+    hibernatingRequests: readonly protocol.HibernatingRequest[];
+    actorId: string;
+    generation: number;
+    config: ActorConfig;
+    pendingRequests: Array<{
+        gatewayId: protocol.GatewayId;
+        requestId: protocol.RequestId;
+        request: PendingRequest;
+    }>;
+    webSockets: Array<{
+        gatewayId: protocol.GatewayId;
+        requestId: protocol.RequestId;
+        ws: WebSocketTunnelAdapter;
+    }>;
+    actorStartPromise: ReturnType<typeof promiseWithResolvers<void>>;
+    lastCommandIdx: bigint;
+    nextEventIdx: bigint;
+    eventHistory: protocol.EventWrapper[];
+    /**
+     * If restoreHibernatingRequests has been called. This is used to assert
+     * that the caller is implemented correctly.
+     **/
+    hibernationRestored: boolean;
+    /**
+     * Set when the actor has explicitly requested to stop (e.g. c.destroy()).
+     * Used to send StopCode.Ok (graceful) vs StopCode.Error (ungraceful) so
+     * the engine crash policy handles sleepable actors correctly.
+     **/
+    stopIntentSent: boolean;
+    constructor(actorId: string, generation: number, config: ActorConfig, 
+    /**
+     * List of hibernating requests provided by the gateway on actor start.
+     * This represents the WebSocket connections that the gateway knows about.
+     **/
+    hibernatingRequests: readonly protocol.HibernatingRequest[]);
+    getPendingRequest(gatewayId: protocol.GatewayId, requestId: protocol.RequestId): PendingRequest | undefined;
+    createPendingRequest(gatewayId: protocol.GatewayId, requestId: protocol.RequestId, clientMessageIndex: number): void;
+    createPendingRequestWithStreamController(gatewayId: protocol.GatewayId, requestId: protocol.RequestId, clientMessageIndex: number, streamController: ReadableStreamDefaultController<Uint8Array>): void;
+    deletePendingRequest(gatewayId: protocol.GatewayId, requestId: protocol.RequestId): void;
+    getWebSocket(gatewayId: protocol.GatewayId, requestId: protocol.RequestId): WebSocketTunnelAdapter | undefined;
+    setWebSocket(gatewayId: protocol.GatewayId, requestId: protocol.RequestId, ws: WebSocketTunnelAdapter): void;
+    deleteWebSocket(gatewayId: protocol.GatewayId, requestId: protocol.RequestId): void;
+    handleAckEvents(lastEventIdx: bigint): void;
+    recordEvent(eventWrapper: protocol.EventWrapper): void;
+}
+
+declare class RunnerShutdownError extends Error {
+    constructor();
+}
+interface RunnerConfig {
+    logger?: Logger;
+    version: number;
+    endpoint: string;
+    token?: string;
+    pegboardEndpoint?: string;
+    pegboardRelayEndpoint?: string;
+    namespace: string;
+    totalSlots: number;
+    runnerName: string;
+    prepopulateActorNames: Record<string, {
+        metadata: Record<string, any>;
+    }>;
+    metadata?: Record<string, any>;
+    onConnected: () => void;
+    onDisconnected: (code: number, reason: string) => void;
+    onShutdown: () => void;
+    /** Called when receiving a network request. */
+    fetch: (runner: Runner, actorId: string, gatewayId: protocol.GatewayId, requestId: protocol.RequestId, request: Request) => Promise<Response>;
+    /**
+     * Called when receiving a WebSocket connection.
+     *
+     * All event listeners must be added synchronously inside this function or
+     * else events may be missed. The open event will fire immediately after
+     * this function finishes.
+     *
+     * Any errors thrown here will disconnect the WebSocket immediately.
+     *
+     * While `path` and `headers` are partially redundant to the data in the
+     * `Request`, they may vary slightly from the actual content of `Request`.
+     * Prefer to persist the `path` and `headers` properties instead of the
+     * `Request` itself.
+     *
+     * ## Hibernating Web Sockets
+     *
+     * ### Implementation Requirements
+     *
+     * **Requirement 1: Persist HWS Immediately**
+     *
+     * This is responsible for persisting hibernatable WebSockets immediately
+     * (do not wait for open event). It is not time sensitive to flush the
+     * connection state. If this fails to persist the HWS, the client's
+     * WebSocket will be disconnected on next wake in the call to
+     * `Tunnel::restoreHibernatingRequests` since the connection entry will not
+     * exist.
+     *
+     * **Requirement 2: Persist Message Index On `message`**
+     *
+     * In the `message` event listener, this handler must persist the message
+     * index from the event. The request ID is available at
+     * `event.rivetRequestId` and message index at `event.rivetMessageIndex`.
+     *
+     * The message index should not be flushed immediately. Instead, this
+     * should:
+     *
+     * - Debounce calls to persist the message index
+     * - After each persist, call
+     *   `Runner::sendHibernatableWebSocketMessageAck` to acknowledge the
+     *   message
+     *
+     * This mechanism allows us to buffer messages on the gateway so we can
+     * batch-persist events on our end on a given interval.
+     *
+     * If this fails to persist, then the gateway will replay unacked
+     * messages when the actor starts again.
+     *
+     * **Requirement 3: Remove HWS From Storage On `close`**
+     *
+     * This handler should add an event listener for `close` to remove the
+     * connection from storage.
+     *
+     * If the connection remove fails to persist, the close event will be
+     * called again on the next actor start in
+     * `Tunnel::restoreHibernatingRequests` since there will be no request for
+     * the given connection.
+     *
+     * ### Restoring Connections
+     *
+     * The user of this library is responsible for:
+     * 1. Loading all persisted hibernatable WebSocket metadata for an actor
+     * 2. Calling `Runner::restoreHibernatingRequests` with this metadata at
+     *    the end of `onActorStart`
+     *
+     * `restoreHibernatingRequests` will restore all connections and attach
+     * the appropriate event listeners.
+     *
+     * ### No Open Event On Restoration
+     *
+     * When restoring a HWS, the open event will not be called again. It will
+     * go straight to the message or close event.
+     */
+    websocket: (runner: Runner, actorId: string, ws: any, gatewayId: protocol.GatewayId, requestId: protocol.RequestId, request: Request, path: string, headers: Record<string, string>, isHibernatable: boolean, isRestoringHibernatable: boolean) => Promise<void>;
+    hibernatableWebSocket: {
+        /**
+         * Determines if a WebSocket can continue to live while an actor goes to
+         * sleep.
+         */
+        canHibernate: (actorId: string, gatewayId: ArrayBuffer, requestId: ArrayBuffer, request: Request) => boolean;
+    };
+    /**
+     * Called when an actor starts.
+     *
+     * This callback is responsible for:
+     * 1. Initializing the actor instance
+     * 2. Loading all persisted hibernatable WebSocket metadata for this actor
+     * 3. Calling `Runner::restoreHibernatingRequests` with the loaded metadata
+     *    to restore hibernatable WebSocket connections
+     *
+     * The actor should not be marked as "ready" until after
+     * `restoreHibernatingRequests` completes to ensure all hibernatable
+     * connections are fully restored before the actor processes new requests.
+     */
+    onActorStart: (actorId: string, generation: number, config: ActorConfig) => Promise<void>;
+    onActorStop: (actorId: string, generation: number) => Promise<void>;
+    noAutoShutdown?: boolean;
+    /**
+     * Debug option to inject artificial latency (in ms) into WebSocket
+     * communication. Messages are queued and delivered in order after the
+     * configured delay.
+     *
+     * @experimental For testing only.
+     */
+    debugLatencyMs?: number;
+}
+interface KvListOptions {
+    reverse?: boolean;
+    limit?: number;
+}
+declare class Runner {
+    #private;
+    get config(): RunnerConfig;
+    runnerId?: string;
+    get log(): Logger | undefined;
+    constructor(config: RunnerConfig);
+    sleepActor(actorId: string, generation?: number): void;
+    stopActor(actorId: string, generation?: number): Promise<void>;
+    /**
+     * Like stopActor but marks the actor for graceful destruction.
+     * This ensures the engine destroys the actor instead of sleeping it.
+     *
+     * NOTE: If a drain (GoingAway) occurs after this is called but before the
+     * stop completes, the engine's going_away flag overrides graceful_exit and
+     * the actor will sleep instead of being destroyed. The destroy intent is
+     * lost in this race. This is acceptable since the actor will be rescheduled
+     * elsewhere and can be destroyed on the next wake.
+     */
+    destroyActor(actorId: string, generation?: number): void;
+    forceStopActor(actorId: string, generation?: number): Promise<void>;
+    getActor(actorId: string, generation?: number): RunnerActor | undefined;
+    getAndWaitForActor(actorId: string, generation?: number): Promise<RunnerActor | undefined>;
+    hasActor(actorId: string, generation?: number): boolean;
+    get actors(): Map<string, RunnerActor>;
+    start(): Promise<void>;
+    shutdown(immediate: boolean, exit?: boolean): Promise<void>;
+    get pegboardEndpoint(): string;
+    get pegboardUrl(): string;
+    kvGet(actorId: string, keys: Uint8Array[]): Promise<(Uint8Array | null)[]>;
+    kvListAll(actorId: string, options?: KvListOptions): Promise<[Uint8Array, Uint8Array][]>;
+    kvListRange(actorId: string, start: Uint8Array, end: Uint8Array, exclusive?: boolean, options?: KvListOptions): Promise<[Uint8Array, Uint8Array][]>;
+    kvListPrefix(actorId: string, prefix: Uint8Array, options?: KvListOptions): Promise<[Uint8Array, Uint8Array][]>;
+    kvPut(actorId: string, entries: [Uint8Array, Uint8Array][]): Promise<void>;
+    kvDelete(actorId: string, keys: Uint8Array[]): Promise<void>;
+    kvDeleteRange(actorId: string, start: Uint8Array, end: Uint8Array): Promise<void>;
+    kvDrop(actorId: string): Promise<void>;
+    setAlarm(actorId: string, alarmTs: number | null, generation?: number): void;
+    clearAlarm(actorId: string, generation?: number): void;
+    /** Asserts WebSocket exists and is ready. */
+    getPegboardWebSocketIfReady(): WebSocket | undefined;
+    __sendToServer(message: protocol.ToServer): void;
+    sendHibernatableWebSocketMessageAck(gatewayId: ArrayBuffer, requestId: ArrayBuffer, index: number): void;
+    /**
+     * Restores hibernatable WebSocket connections for an actor.
+     *
+     * This method should be called at the end of `onActorStart` after the
+     * actor instance is fully initialized.
+     *
+     * This method will:
+     * - Restore all provided hibernatable WebSocket connections
+     * - Attach event listeners to the restored WebSockets
+     * - Close any WebSocket connections that failed to restore
+     *
+     * The provided metadata list should include all hibernatable WebSockets
+     * that were persisted for this actor. The gateway will automatically
+     * close any connections that are not restored (i.e., not included in
+     * this list).
+     *
+     * **Important:** This method must be called after `onActorStart` completes
+     * and before marking the actor as "ready" to ensure all hibernatable
+     * connections are fully restored.
+     *
+     * @param actorId - The ID of the actor to restore connections for
+     * @param metaEntries - Array of hibernatable WebSocket metadata to restore
+     */
+    restoreHibernatingRequests(actorId: string, metaEntries: HibernatingWebSocketMetadata[]): Promise<void>;
+    getServerlessInitPacket(): string | undefined;
+    getProtocolMetadata(): protocol.ProtocolMetadata | undefined;
+}
+
+export { type ActorConfig, type HibernatingWebSocketMetadata, type KvListOptions, Runner, RunnerActor, type RunnerConfig, RunnerShutdownError, idToStr };