@rivetkit/engine-runner 2.0.24-rc.1 → 2.0.24

package/dist/mod.d.cts

@@ -1,19 +1,147 @@
 import * as protocol from '@rivetkit/engine-runner-protocol';
+import { GatewayId, RequestId } from '@rivetkit/engine-runner-protocol';
 import { Logger } from 'pino';
+import WebSocket from 'ws';
 
-interface ActorInstance {
-    actorId: string;
-    generation: number;
-    config: ActorConfig;
-    requests: Set<string>;
-    webSockets: Set<string>;
+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;
+    /** @experimental */
+    readonly request: Request;
+    get [HIBERNATABLE_SYMBOL](): boolean;
+    constructor(tunnel: Tunnel, actorId: string, requestId: string, serverMessageIndex: number, hibernatable: boolean, isRestoringHibernatable: boolean, 
+    /** @experimental */
+    request: Request, sendCallback: (data: ArrayBuffer | string, isBinary: boolean) => void, closeCallback: (code?: number, reason?: string) => void);
+    get bufferedAmount(): number;
+    _handleOpen(requestId: ArrayBuffer): void;
+    _handleMessage(requestId: ArrayBuffer, data: string | Uint8Array, serverMessageIndex: number, isBinary: boolean): boolean;
+    _handleClose(_requestId: ArrayBuffer, code?: number, reason?: string): void;
+    _handleError(error: Error): void;
+    _closeWithoutCallback(code?: number, reason?: string): void;
+    get readyState(): number;
+    get binaryType(): string;
+    set binaryType(value: string);
+    get extensions(): string;
+    get protocol(): string;
+    get url(): string;
+    get onopen(): ((this: any, ev: any) => any) | null;
+    set onopen(value: ((this: any, ev: any) => any) | null);
+    get onclose(): ((this: any, ev: any) => any) | null;
+    set onclose(value: ((this: any, ev: any) => any) | null);
+    get onerror(): ((this: any, ev: any) => any) | null;
+    set onerror(value: ((this: any, ev: any) => any) | null);
+    get onmessage(): ((this: any, ev: any) => any) | null;
+    set onmessage(value: ((this: any, ev: any) => any) | null);
+    send(data: string | ArrayBuffer | ArrayBufferView | Blob | Buffer): void;
+    close(code?: number, reason?: string): void;
+    addEventListener(type: string, listener: (event: any) => void, options?: boolean | any): void;
+    removeEventListener(type: string, listener: (event: any) => void, options?: boolean | any): void;
+    dispatchEvent(event: any): boolean;
+    static readonly CONNECTING = 0;
+    static readonly OPEN = 1;
+    static readonly CLOSING = 2;
+    static readonly CLOSED = 3;
+    readonly CONNECTING = 0;
+    readonly OPEN = 1;
+    readonly CLOSING = 2;
+    readonly CLOSED = 3;
+    ping(data?: any, mask?: boolean, cb?: (err: Error) => void): void;
+    pong(data?: any, mask?: boolean, cb?: (err: Error) => void): void;
+    /** @experimental */
+    terminate(): 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>>;
+    /**
+     * If restoreHibernatingRequests has been called. This is used to assert
+     * that the caller is implemented correctly.
+     **/
+    hibernationRestored: 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;
+}
+
 interface RunnerConfig {
     logger?: Logger;
     version: number;
@@ -32,17 +160,105 @@ interface RunnerConfig {
     onConnected: () => void;
     onDisconnected: (code: number, reason: string) => void;
     onShutdown: () => void;
-    fetch: (runner: Runner, actorId: string, requestId: protocol.RequestId, request: Request) => Promise<Response>;
-    websocket?: (runner: Runner, actorId: string, ws: any, requestId: protocol.RequestId, request: Request) => Promise<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>;
-    getActorHibernationConfig: (actorId: string, requestId: ArrayBuffer, request: Request) => HibernationConfig;
     noAutoShutdown?: boolean;
 }
-interface HibernationConfig {
-    enabled: boolean;
-    lastMsgIndex: number | undefined;
-}
 interface KvListOptions {
     reverse?: boolean;
     limit?: number;
@@ -50,14 +266,17 @@ interface KvListOptions {
 declare class Runner {
     #private;
     get config(): RunnerConfig;
+    __pegboardWebSocket?: WebSocket;
     runnerId?: string;
     get log(): Logger | undefined;
     constructor(config: RunnerConfig);
     sleepActor(actorId: string, generation?: number): void;
     stopActor(actorId: string, generation?: number): Promise<void>;
     forceStopActor(actorId: string, generation?: number): Promise<void>;
-    getActor(actorId: string, generation?: number): ActorInstance | undefined;
+    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;
@@ -71,10 +290,37 @@ declare class Runner {
     kvDrop(actorId: string): Promise<void>;
     setAlarm(actorId: string, alarmTs: number | null, generation?: number): void;
     clearAlarm(actorId: string, generation?: number): void;
-    __webSocketReady(): boolean;
+    /** Asserts WebSocket exists and is ready. */
+    __webSocketReady(): this is this & {
+        __pegboardWebSocket: NonNullable<Runner["__pegboardWebSocket"]>;
+    };
     __sendToServer(message: protocol.ToServer): void;
-    sendWebsocketMessageAck(requestId: ArrayBuffer, index: number): 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;
 }
 
-export { type ActorConfig, type ActorInstance, type HibernationConfig, type KvListOptions, Runner, type RunnerConfig };
+export { type ActorConfig, type HibernatingWebSocketMetadata, type KvListOptions, Runner, RunnerActor, type RunnerConfig, idToStr };

package/dist/mod.d.ts

@@ -1,19 +1,147 @@
 import * as protocol from '@rivetkit/engine-runner-protocol';
+import { GatewayId, RequestId } from '@rivetkit/engine-runner-protocol';
 import { Logger } from 'pino';
+import WebSocket from 'ws';
 
-interface ActorInstance {
-    actorId: string;
-    generation: number;
-    config: ActorConfig;
-    requests: Set<string>;
-    webSockets: Set<string>;
+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;
+    /** @experimental */
+    readonly request: Request;
+    get [HIBERNATABLE_SYMBOL](): boolean;
+    constructor(tunnel: Tunnel, actorId: string, requestId: string, serverMessageIndex: number, hibernatable: boolean, isRestoringHibernatable: boolean, 
+    /** @experimental */
+    request: Request, sendCallback: (data: ArrayBuffer | string, isBinary: boolean) => void, closeCallback: (code?: number, reason?: string) => void);
+    get bufferedAmount(): number;
+    _handleOpen(requestId: ArrayBuffer): void;
+    _handleMessage(requestId: ArrayBuffer, data: string | Uint8Array, serverMessageIndex: number, isBinary: boolean): boolean;
+    _handleClose(_requestId: ArrayBuffer, code?: number, reason?: string): void;
+    _handleError(error: Error): void;
+    _closeWithoutCallback(code?: number, reason?: string): void;
+    get readyState(): number;
+    get binaryType(): string;
+    set binaryType(value: string);
+    get extensions(): string;
+    get protocol(): string;
+    get url(): string;
+    get onopen(): ((this: any, ev: any) => any) | null;
+    set onopen(value: ((this: any, ev: any) => any) | null);
+    get onclose(): ((this: any, ev: any) => any) | null;
+    set onclose(value: ((this: any, ev: any) => any) | null);
+    get onerror(): ((this: any, ev: any) => any) | null;
+    set onerror(value: ((this: any, ev: any) => any) | null);
+    get onmessage(): ((this: any, ev: any) => any) | null;
+    set onmessage(value: ((this: any, ev: any) => any) | null);
+    send(data: string | ArrayBuffer | ArrayBufferView | Blob | Buffer): void;
+    close(code?: number, reason?: string): void;
+    addEventListener(type: string, listener: (event: any) => void, options?: boolean | any): void;
+    removeEventListener(type: string, listener: (event: any) => void, options?: boolean | any): void;
+    dispatchEvent(event: any): boolean;
+    static readonly CONNECTING = 0;
+    static readonly OPEN = 1;
+    static readonly CLOSING = 2;
+    static readonly CLOSED = 3;
+    readonly CONNECTING = 0;
+    readonly OPEN = 1;
+    readonly CLOSING = 2;
+    readonly CLOSED = 3;
+    ping(data?: any, mask?: boolean, cb?: (err: Error) => void): void;
+    pong(data?: any, mask?: boolean, cb?: (err: Error) => void): void;
+    /** @experimental */
+    terminate(): 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>>;
+    /**
+     * If restoreHibernatingRequests has been called. This is used to assert
+     * that the caller is implemented correctly.
+     **/
+    hibernationRestored: 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;
+}
+
 interface RunnerConfig {
     logger?: Logger;
     version: number;
@@ -32,17 +160,105 @@ interface RunnerConfig {
     onConnected: () => void;
     onDisconnected: (code: number, reason: string) => void;
     onShutdown: () => void;
-    fetch: (runner: Runner, actorId: string, requestId: protocol.RequestId, request: Request) => Promise<Response>;
-    websocket?: (runner: Runner, actorId: string, ws: any, requestId: protocol.RequestId, request: Request) => Promise<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>;
-    getActorHibernationConfig: (actorId: string, requestId: ArrayBuffer, request: Request) => HibernationConfig;
     noAutoShutdown?: boolean;
 }
-interface HibernationConfig {
-    enabled: boolean;
-    lastMsgIndex: number | undefined;
-}
 interface KvListOptions {
     reverse?: boolean;
     limit?: number;
@@ -50,14 +266,17 @@ interface KvListOptions {
 declare class Runner {
     #private;
     get config(): RunnerConfig;
+    __pegboardWebSocket?: WebSocket;
     runnerId?: string;
     get log(): Logger | undefined;
     constructor(config: RunnerConfig);
     sleepActor(actorId: string, generation?: number): void;
     stopActor(actorId: string, generation?: number): Promise<void>;
     forceStopActor(actorId: string, generation?: number): Promise<void>;
-    getActor(actorId: string, generation?: number): ActorInstance | undefined;
+    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;
@@ -71,10 +290,37 @@ declare class Runner {
     kvDrop(actorId: string): Promise<void>;
     setAlarm(actorId: string, alarmTs: number | null, generation?: number): void;
     clearAlarm(actorId: string, generation?: number): void;
-    __webSocketReady(): boolean;
+    /** Asserts WebSocket exists and is ready. */
+    __webSocketReady(): this is this & {
+        __pegboardWebSocket: NonNullable<Runner["__pegboardWebSocket"]>;
+    };
     __sendToServer(message: protocol.ToServer): void;
-    sendWebsocketMessageAck(requestId: ArrayBuffer, index: number): 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;
 }
 
-export { type ActorConfig, type ActorInstance, type HibernationConfig, type KvListOptions, Runner, type RunnerConfig };
+export { type ActorConfig, type HibernatingWebSocketMetadata, type KvListOptions, Runner, RunnerActor, type RunnerConfig, idToStr };