PersistentSessionsProtocol Specification

1. Introduction

1.1 Motivation

Browser automation tools handle session persistence in fundamentally different ways, creating significant interoperability problems for developers. The PersistentSessionsProtocol establishes a unified method for capturing, storing, transmitting, and replaying browser sessions across Playwright, Selenium, Skyvern, and other major frameworks.

1.2 Goals

• Provide a framework-agnostic method for persisting browser state
• Enable seamless session transfer between different tools and environments
• Support both local and remote session storage
• Ensure security for sensitive session data
• Minimize implementation complexity for framework adapters

2. Core Architecture

PSP employs a layered architecture with four distinct components:

2.1 Session Capture Layer

The capture layer extracts state through:

• Storage APIs: Cookies, localStorage, sessionStorage access
• DOM Introspection: HTML structure and state
• Network Interception: Captured requests and responses
• Browser APIs: Navigation state through History API
• Input Recording: User interactions and timing

Framework adapters translate between PSP's structures and framework implementations.

2.2 Serialization and Transport Layer

Data serialization uses:

• Primary format: Protocol Buffers for efficient binary encoding
• Fallback format: JSON for debugging and compatibility
• Differential updates: Only changed state components transmitted
• Compression: Selective compression for large assets

2.3 Storage Layer

Multiple backend options supported:

• Local filesystem: For single-machine persistence
• Redis: For production deployments
• Databases: SQL/NoSQL for existing infrastructure
• Cloud object storage: For distributed access

2.4 Replay Layer

Session restoration through:

• State restoration: Direct application of serialized state
• Event replay: Chronological event playback
• Network simulation: Mocked or pass-through responses
• Timing control: Options for replay speed

3. Data Model

3.1 Session State

interface BrowserSessionState {
  version: string;
  timestamp: number;
  origin: string;
  storage: StorageState;
  dom?: DOMState;
  history?: HistoryState;
  network?: NetworkState;
  recording?: RecordingState;
}

3.2 Storage State

interface StorageState {
  cookies: Cookie[];
  localStorage: Map>;  // Origin to key-value map
  sessionStorage: Map>;
  indexedDB?: IndexedDBState;
  cacheStorage?: CacheStorageState;
}

interface Cookie {
  name: string;
  value: string;
  domain: string;
  path: string;
  expires: number | null;
  httpOnly: boolean;
  secure: boolean;
  sameSite: "Strict" | "Lax" | "None";
  partitioned: boolean;  // For CHIPS (Cookie Having Independent Partitioned State)
}

3.3 Authentication State

interface AuthenticationState {
  tokens: AuthToken[];
  credentials?: EncryptedCredentials;  // Only with explicit permission
}

interface AuthToken {
  type: string;  // "Bearer", "JWT", "OAuth", etc.
  value: string;
  scope?: string[];
  expiresAt?: number;
  refreshToken?: string;
  isHttpOnly: boolean;
  domain: string;
}

3.4 Navigation State

interface NavigationState {
  currentUrl: string;
  entries: HistoryEntry[];
  currentIndex: number;
}

interface HistoryEntry {
  url: string;
  title: string;
  state?: object;  // History state object
  scrollPosition?: { x: number, y: number };
  timestamp: number;
}

3.5 Recording State

interface RecordingState {
  events: Event[];
  startTime: number;
  duration: number;
}

interface Event {
  type: string;  // "click", "keydown", "timer", "network", etc.
  timestamp: number;
  target?: string;  // CSS selector or XPath
  data: object;  // Event-specific data
}

4. API Specification

4.1 Core Client API

interface PSPSession {
  // Session management
  create(options?: SessionOptions): Promise;
  load(sessionId: string): Promise;
  list(filter?: SessionFilter): Promise;
  delete(sessionId: string): Promise;

  // State operations
  capture(page: BrowserPage): Promise;
  restore(page: BrowserPage): Promise;
  
  // Recording operations
  startRecording(options?: RecordingOptions): Promise;
  stopRecording(): Promise;
  playRecording(options?: PlaybackOptions): Promise;
}

4.2 Server REST API

GET    /sessions                # List sessions
POST   /sessions                # Create a new session
GET    /sessions/:id            # Get session by ID
PUT    /sessions/:id            # Update session
DELETE /sessions/:id            # Delete session
PATCH  /sessions/:id            # Partial update
GET    /sessions/:id/events     # Get recorded events
POST   /sessions/:id/events     # Add events to session

4.3 WebSocket API

// Event types
type PSPWebSocketEvent = 
  | { type: 'session.update', data: BrowserSessionState }
  | { type: 'session.event', data: Event }
  | { type: 'session.deleted', data: { id: string } };

// Connection message for subscribing to session updates
interface PSPWebSocketConnect {
  action: 'subscribe';
  sessionId: string;
  token: string;  // Authentication token
}

5. Implementation Guidelines

5.1 Adapter Implementation

Framework adapters must implement:

1. State capture: Extract browser state via framework APIs
2. State restoration: Apply state to browser context
3. Event recording: Capture user interactions
4. Event replay: Reproduce recorded actions

5.2 Storage Backend Implementation

Storage backends must provide:

1. CRUD operations: Basic session management
2. Query capability: Find sessions by metadata
3. Transaction support: Atomic operations
4. TTL support: Automatic session expiration
5. Compression: Optional data compression