@alfe.ai/remote 0.0.0 → 0.1.1

package/dist/index.d.cts

@@ -16,9 +16,15 @@
  *   • viewer → plugin: SESSION_OPEN, SESSION_CLOSE, SCREENCAST_ACK, INPUT_*,
  *     RESIZE, TAKEOVER_REQUEST, RELEASE_CONTROL, TERMINAL_INPUT, TERMINAL_RESIZE
  *
- * Keep this file byte-identical with `services/remote/src/remote-protocol.ts`.
+ * Keep agent-facing frame values byte-compatible with
+ * `services/remote/src/remote-protocol.ts`. The relay may define private frame
+ * types that it consumes without forwarding them to the agent.
  */
 declare const REMOTE_HEADER_SIZE = 5;
+/** Maximum complete WebSocket message size, including the five-byte header. */
+declare const REMOTE_MAX_PAYLOAD: number;
+/** Control payloads are deliberately much smaller than media/terminal frames. */
+declare const REMOTE_MAX_JSON_PAYLOAD: number;
 declare const RemoteFrameType: {
   /** viewer→plugin: a viewer attached. Payload: SessionOpenPayload. */
   readonly SESSION_OPEN: 1;
@@ -116,13 +122,14 @@ interface TerminalResizePayload {
   cols: number;
   rows: number;
 }
+declare function isRemoteFrameType(value: unknown): value is RemoteFrameType;
+declare function isRelayToAgentFrameType(value: unknown): value is RemoteFrameType;
+declare function isAgentToRelayFrameType(value: unknown): value is RemoteFrameType;
 declare function isRemoteFrame(data: Buffer): boolean;
 declare function encodeFrame(type: RemoteFrameType, sessionId: number, payload?: Buffer): Buffer;
 declare function decodeFrame(buf: Buffer): RemoteFrame;
 declare function encodeJsonFrame(type: RemoteFrameType, sessionId: number, obj: unknown): Buffer;
-/** Best-effort JSON decode — returns null on a malformed payload so a single
- * corrupt frame can't crash the per-session handler. Callers assert the shape
- * (e.g. `decodeJson(p) as SessionOpenPayload | null`). */
+/** Best-effort bounded JSON decode. Shape-specific callers use the decoders below. */
 declare function decodeJson(payload: Buffer): unknown;
 /** Encode a screencast frame: [metaLen:u16BE][meta JSON][raw JPEG]. The JPEG is
  * forwarded raw (already base64-decoded from CDP) to avoid base64 bloat. */
@@ -131,8 +138,15 @@ declare function decodeScreencastFrame(payload: Buffer): {
   meta: ScreencastFrameMeta;
   jpeg: Buffer;
 } | null;
-/** Maximum WS message size (must align across daemon plugin and relay). */
-declare const REMOTE_MAX_PAYLOAD: number;
+declare function decodeSessionOpenPayload(payload: Buffer): SessionOpenPayload | null;
+declare function decodeScreencastAckPayload(payload: Buffer): {
+  frameSeq: number;
+} | null;
+declare function decodeResizePayload(payload: Buffer): ResizePayload | null;
+declare function decodeMouseInputPayload(payload: Buffer): MouseInputPayload | null;
+declare function decodeWheelInputPayload(payload: Buffer): WheelInputPayload | null;
+declare function decodeKeyInputPayload(payload: Buffer): KeyInputPayload | null;
+declare function decodeTerminalResizePayload(payload: Buffer): TerminalResizePayload | null;
 //#endregion
 //#region src/surface.d.ts
 interface SurfaceHandler {
@@ -163,9 +177,9 @@ interface RemoteServiceClientOptions {
    * dispatches by `frame.sessionId` to the owning surface handler. Kept on the
    * transport as a single callback so this package stays surface-agnostic.
    */
-  onFrame: (frame: RemoteFrame) => void;
+  onFrame: (frame: RemoteFrame) => void | Promise<void>;
   /** Called when the WS connection state changes. */
-  onConnectionChange?: (connected: boolean) => void;
+  onConnectionChange?: (connected: boolean) => void | Promise<void>;
   /** Optional logger (defaults to console). */
   logger?: Logger;
 }
@@ -176,27 +190,31 @@ declare class RemoteServiceClient {
   private ws;
   private stopped;
   private connected;
+  private generation;
   private retryCount;
   private retryTimer;
   private heartbeatTimer;
   private isAlive;
   private readonly log;
+  private readonly relayUrl;
+  private readonly endpointLabel;
   constructor(options: RemoteServiceClientOptions);
   get isConnected(): boolean;
   /** Backpressure signal for the screencast pump — bytes queued but not flushed. */
   get bufferedAmount(): number;
+  /** Start one connection lifecycle. Repeated starts in the same lifecycle are no-ops. */
   start(): void;
+  /** Stop the current lifecycle and invalidate every callback owned by it. */
   stop(): void;
-  /** Send a pre-encoded binary frame. No-op if the socket isn't open. */
+  /** Send a validated pre-encoded agent→relay frame when the socket is open. */
   sendFrame(buf: Buffer): void;
   private doConnect;
   private scheduleReconnect;
-  /**
-   * Detect a silently-dropped connection. Each tick: if no inbound liveness
-   * (pong/ping/message) was seen since the last tick, force-close so the
-   * `close` handler reconnects; otherwise send a fresh ping and arm the next.
-   */
   private startHeartbeat;
+  private setConnected;
+  private isActive;
+  private isCurrent;
+  private clearRetry;
   private clearHeartbeat;
 }
 //#endregion
@@ -240,4 +258,4 @@ declare class TurnController {
   private setOwner;
 }
 //#endregion
-export { KeyInputPayload, type Logger, MouseInputPayload, REMOTE_HEADER_SIZE, REMOTE_MAX_PAYLOAD, RemoteFrame, RemoteFrameType, RemoteServiceClient, type RemoteServiceClientOptions, RemoteSurface, ResizePayload, ScreencastFrameMeta, SessionOpenPayload, SessionStatePayload, type SurfaceHandler, TerminalResizePayload, TurnController, type TurnControllerOptions, type TurnOwner, WheelInputPayload, decodeFrame, decodeJson, decodeScreencastFrame, encodeFrame, encodeJsonFrame, encodeScreencastFrame, isRemoteFrame };
+export { KeyInputPayload, type Logger, MouseInputPayload, REMOTE_HEADER_SIZE, REMOTE_MAX_JSON_PAYLOAD, REMOTE_MAX_PAYLOAD, RemoteFrame, RemoteFrameType, RemoteServiceClient, type RemoteServiceClientOptions, RemoteSurface, ResizePayload, ScreencastFrameMeta, SessionOpenPayload, SessionStatePayload, type SurfaceHandler, TerminalResizePayload, TurnController, type TurnControllerOptions, type TurnOwner, WheelInputPayload, decodeFrame, decodeJson, decodeKeyInputPayload, decodeMouseInputPayload, decodeResizePayload, decodeScreencastAckPayload, decodeScreencastFrame, decodeSessionOpenPayload, decodeTerminalResizePayload, decodeWheelInputPayload, encodeFrame, encodeJsonFrame, encodeScreencastFrame, isAgentToRelayFrameType, isRelayToAgentFrameType, isRemoteFrame, isRemoteFrameType };

package/dist/index.d.ts

@@ -16,9 +16,15 @@
  *   • viewer → plugin: SESSION_OPEN, SESSION_CLOSE, SCREENCAST_ACK, INPUT_*,
  *     RESIZE, TAKEOVER_REQUEST, RELEASE_CONTROL, TERMINAL_INPUT, TERMINAL_RESIZE
  *
- * Keep this file byte-identical with `services/remote/src/remote-protocol.ts`.
+ * Keep agent-facing frame values byte-compatible with
+ * `services/remote/src/remote-protocol.ts`. The relay may define private frame
+ * types that it consumes without forwarding them to the agent.
  */
 declare const REMOTE_HEADER_SIZE = 5;
+/** Maximum complete WebSocket message size, including the five-byte header. */
+declare const REMOTE_MAX_PAYLOAD: number;
+/** Control payloads are deliberately much smaller than media/terminal frames. */
+declare const REMOTE_MAX_JSON_PAYLOAD: number;
 declare const RemoteFrameType: {
   /** viewer→plugin: a viewer attached. Payload: SessionOpenPayload. */
   readonly SESSION_OPEN: 1;
@@ -116,13 +122,14 @@ interface TerminalResizePayload {
   cols: number;
   rows: number;
 }
+declare function isRemoteFrameType(value: unknown): value is RemoteFrameType;
+declare function isRelayToAgentFrameType(value: unknown): value is RemoteFrameType;
+declare function isAgentToRelayFrameType(value: unknown): value is RemoteFrameType;
 declare function isRemoteFrame(data: Buffer): boolean;
 declare function encodeFrame(type: RemoteFrameType, sessionId: number, payload?: Buffer): Buffer;
 declare function decodeFrame(buf: Buffer): RemoteFrame;
 declare function encodeJsonFrame(type: RemoteFrameType, sessionId: number, obj: unknown): Buffer;
-/** Best-effort JSON decode — returns null on a malformed payload so a single
- * corrupt frame can't crash the per-session handler. Callers assert the shape
- * (e.g. `decodeJson(p) as SessionOpenPayload | null`). */
+/** Best-effort bounded JSON decode. Shape-specific callers use the decoders below. */
 declare function decodeJson(payload: Buffer): unknown;
 /** Encode a screencast frame: [metaLen:u16BE][meta JSON][raw JPEG]. The JPEG is
  * forwarded raw (already base64-decoded from CDP) to avoid base64 bloat. */
@@ -131,8 +138,15 @@ declare function decodeScreencastFrame(payload: Buffer): {
   meta: ScreencastFrameMeta;
   jpeg: Buffer;
 } | null;
-/** Maximum WS message size (must align across daemon plugin and relay). */
-declare const REMOTE_MAX_PAYLOAD: number;
+declare function decodeSessionOpenPayload(payload: Buffer): SessionOpenPayload | null;
+declare function decodeScreencastAckPayload(payload: Buffer): {
+  frameSeq: number;
+} | null;
+declare function decodeResizePayload(payload: Buffer): ResizePayload | null;
+declare function decodeMouseInputPayload(payload: Buffer): MouseInputPayload | null;
+declare function decodeWheelInputPayload(payload: Buffer): WheelInputPayload | null;
+declare function decodeKeyInputPayload(payload: Buffer): KeyInputPayload | null;
+declare function decodeTerminalResizePayload(payload: Buffer): TerminalResizePayload | null;
 //#endregion
 //#region src/surface.d.ts
 interface SurfaceHandler {
@@ -163,9 +177,9 @@ interface RemoteServiceClientOptions {
    * dispatches by `frame.sessionId` to the owning surface handler. Kept on the
    * transport as a single callback so this package stays surface-agnostic.
    */
-  onFrame: (frame: RemoteFrame) => void;
+  onFrame: (frame: RemoteFrame) => void | Promise<void>;
   /** Called when the WS connection state changes. */
-  onConnectionChange?: (connected: boolean) => void;
+  onConnectionChange?: (connected: boolean) => void | Promise<void>;
   /** Optional logger (defaults to console). */
   logger?: Logger;
 }
@@ -176,27 +190,31 @@ declare class RemoteServiceClient {
   private ws;
   private stopped;
   private connected;
+  private generation;
   private retryCount;
   private retryTimer;
   private heartbeatTimer;
   private isAlive;
   private readonly log;
+  private readonly relayUrl;
+  private readonly endpointLabel;
   constructor(options: RemoteServiceClientOptions);
   get isConnected(): boolean;
   /** Backpressure signal for the screencast pump — bytes queued but not flushed. */
   get bufferedAmount(): number;
+  /** Start one connection lifecycle. Repeated starts in the same lifecycle are no-ops. */
   start(): void;
+  /** Stop the current lifecycle and invalidate every callback owned by it. */
   stop(): void;
-  /** Send a pre-encoded binary frame. No-op if the socket isn't open. */
+  /** Send a validated pre-encoded agent→relay frame when the socket is open. */
   sendFrame(buf: Buffer): void;
   private doConnect;
   private scheduleReconnect;
-  /**
-   * Detect a silently-dropped connection. Each tick: if no inbound liveness
-   * (pong/ping/message) was seen since the last tick, force-close so the
-   * `close` handler reconnects; otherwise send a fresh ping and arm the next.
-   */
   private startHeartbeat;
+  private setConnected;
+  private isActive;
+  private isCurrent;
+  private clearRetry;
   private clearHeartbeat;
 }
 //#endregion
@@ -240,4 +258,4 @@ declare class TurnController {
   private setOwner;
 }
 //#endregion
-export { KeyInputPayload, type Logger, MouseInputPayload, REMOTE_HEADER_SIZE, REMOTE_MAX_PAYLOAD, RemoteFrame, RemoteFrameType, RemoteServiceClient, type RemoteServiceClientOptions, RemoteSurface, ResizePayload, ScreencastFrameMeta, SessionOpenPayload, SessionStatePayload, type SurfaceHandler, TerminalResizePayload, TurnController, type TurnControllerOptions, type TurnOwner, WheelInputPayload, decodeFrame, decodeJson, decodeScreencastFrame, encodeFrame, encodeJsonFrame, encodeScreencastFrame, isRemoteFrame };
+export { KeyInputPayload, type Logger, MouseInputPayload, REMOTE_HEADER_SIZE, REMOTE_MAX_JSON_PAYLOAD, REMOTE_MAX_PAYLOAD, RemoteFrame, RemoteFrameType, RemoteServiceClient, type RemoteServiceClientOptions, RemoteSurface, ResizePayload, ScreencastFrameMeta, SessionOpenPayload, SessionStatePayload, type SurfaceHandler, TerminalResizePayload, TurnController, type TurnControllerOptions, type TurnOwner, WheelInputPayload, decodeFrame, decodeJson, decodeKeyInputPayload, decodeMouseInputPayload, decodeResizePayload, decodeScreencastAckPayload, decodeScreencastFrame, decodeSessionOpenPayload, decodeTerminalResizePayload, decodeWheelInputPayload, encodeFrame, encodeJsonFrame, encodeScreencastFrame, isAgentToRelayFrameType, isRelayToAgentFrameType, isRemoteFrame, isRemoteFrameType };