@steventsao/agent-session-core 0.1.12 → 0.1.13

package/dist/index.d.ts

@@ -1,10 +1,732 @@
+import { z } from 'zod';
+
 /**
- * @agent-session/core
+ * Centralized WebSocket Events
  *
- * Shared types and protocol for agent-session.
- * Used by both client and server packages.
+ * Single source of truth for all socket event types used across:
+ * - SessionSocket Durable Object (Cloudflare Worker)
+ * - Client applications (React, etc.)
+ * - E2B sandbox communication
  */
-export * from './socket-events';
-export * from './types';
-export * from './session-config';
-//# sourceMappingURL=index.d.ts.map
+
+declare const ClientEventType: {
+    readonly INIT: "INIT";
+    readonly PING: "PING";
+    readonly JOIN_SESSION: "JOIN_SESSION";
+    readonly START_SANDBOX: "START_SANDBOX";
+    readonly STOP_SANDBOX: "STOP_SANDBOX";
+    readonly EXEC: "EXEC";
+    readonly AGENT_MESSAGE: "AGENT_MESSAGE";
+    readonly AGENT_STOP: "AGENT_STOP";
+    readonly AGENT_RESET: "AGENT_RESET";
+};
+type ClientEventType = (typeof ClientEventType)[keyof typeof ClientEventType];
+declare const ServerEventType: {
+    readonly CONNECTED: "CONNECTED";
+    readonly READY: "READY";
+    readonly PONG: "PONG";
+    readonly MESSAGE_ACK: "MESSAGE_ACK";
+    readonly MESSAGE_ERROR: "MESSAGE_ERROR";
+    readonly EVENTS_BATCH: "EVENTS_BATCH";
+    readonly SANDBOX_STATUS: "SANDBOX_STATUS";
+    readonly LIFECYCLE: "LIFECYCLE";
+    readonly TERM_DATA: "TERM_DATA";
+    readonly EXEC_COMPLETE: "EXEC_COMPLETE";
+    readonly SYSTEM: "SYSTEM";
+    readonly ERROR: "ERROR";
+    readonly AGENT_STARTED: "AGENT_STARTED";
+    readonly AGENT_MESSAGE: "AGENT_MESSAGE";
+    readonly AGENT_ACTION: "AGENT_ACTION";
+    readonly AGENT_STEP_COMPLETE: "AGENT_STEP_COMPLETE";
+    readonly AGENT_DONE: "AGENT_DONE";
+    readonly AGENT_ERROR: "AGENT_ERROR";
+    readonly AGENT_EVENT: "AGENT_EVENT";
+    readonly FILE_UPLOADED: "FILE_UPLOADED";
+    readonly FILES_SYNC: "FILES_SYNC";
+    readonly TOC_REQUEST_RECEIVED: "TOC_REQUEST_RECEIVED";
+    readonly TOC_AUTH_COMPLETED: "TOC_AUTH_COMPLETED";
+    readonly TOC_DB_QUERY_STARTED: "TOC_DB_QUERY_STARTED";
+    readonly TOC_DB_QUERY_COMPLETED: "TOC_DB_QUERY_COMPLETED";
+    readonly TOC_GCS_DOWNLOAD_STARTED: "TOC_GCS_DOWNLOAD_STARTED";
+    readonly TOC_GCS_DOWNLOAD_COMPLETED: "TOC_GCS_DOWNLOAD_COMPLETED";
+    readonly TOC_SANDBOX_CREATED: "TOC_SANDBOX_CREATED";
+    readonly TOC_EXTRACTION_STARTED: "TOC_EXTRACTION_STARTED";
+    readonly TOC_EXTRACTION_COMPLETED: "TOC_EXTRACTION_COMPLETED";
+    readonly TOC_RESPONSE_READY: "TOC_RESPONSE_READY";
+};
+type ServerEventType = (typeof ServerEventType)[keyof typeof ServerEventType];
+declare const SandboxStatus: {
+    readonly IDLE: "idle";
+    readonly BOOTING: "booting";
+    readonly READY: "ready";
+    readonly ERROR: "error";
+};
+type SandboxStatus = (typeof SandboxStatus)[keyof typeof SandboxStatus];
+/**
+ * Granular lifecycle phases for UI loading states
+ * Common lifecycle events across different app types:
+ * - idle: No sandbox running
+ * - booting: Creating sandbox instance
+ * - environment_ready: Sandbox created, basic environment up
+ * - files_ready: App files synced/loaded (for app builders)
+ * - installing: Installing dependencies
+ * - starting: Starting services (dev server, etc.)
+ * - interaction_ready: Ready for user interaction (agent can respond)
+ * - ready: Fully ready (deprecated alias for interaction_ready)
+ * - error: Something went wrong
+ */
+declare const SandboxLifecycle: {
+    readonly IDLE: "idle";
+    readonly BOOTING: "booting";
+    readonly ENVIRONMENT_READY: "environment_ready";
+    readonly FILES_READY: "files_ready";
+    readonly INSTALLING: "installing";
+    readonly STARTING: "starting";
+    readonly INTERACTION_READY: "interaction_ready";
+    readonly READY: "ready";
+    readonly ERROR: "error";
+};
+type SandboxLifecycle = (typeof SandboxLifecycle)[keyof typeof SandboxLifecycle];
+/**
+ * Parse SYSTEM message to SandboxLifecycle phase
+ */
+declare function parseSystemMessageToLifecycle(msg: string): SandboxLifecycle | null;
+interface InitEvent {
+    type: 'INIT';
+    userId?: string;
+    metadata?: Record<string, unknown>;
+}
+interface PingEvent {
+    type: 'PING';
+}
+/**
+ * Join session with optional cursor for event resumption (Manus pattern)
+ * On reconnect, client sends lastEventId to receive missed events
+ */
+interface JoinSessionEvent {
+    type: 'JOIN_SESSION';
+    /** Last event ID received - server will send events after this cursor */
+    lastEventId?: string;
+}
+/**
+ * Bootstrap options for sandbox file pre-population
+ *
+ * Supports three strategies (in order of preference):
+ * 1. archiveUrl: Single tar.gz archive - fastest for many files
+ * 2. bootstrapUrl: Fetch file manifest with individual URLs
+ * 3. files: Inline files (legacy, causes WebSocket bloat)
+ */
+interface SandboxBootstrapOptions {
+    /** URL to tar.gz archive containing all workspace files (preferred) */
+    archiveUrl?: string;
+    /** URL to fetch file manifest (returns SandboxFile[]) */
+    bootstrapUrl?: string;
+    /** Inline files to write directly */
+    files?: SandboxFile[];
+    /** Headers to include when fetching bootstrapUrl or archiveUrl */
+    headers?: Record<string, string>;
+}
+interface StartSandboxEvent {
+    type: 'START_SANDBOX';
+    template?: string;
+    /** Bootstrap options for file pre-population before agent starts */
+    bootstrap?: SandboxBootstrapOptions;
+}
+interface StopSandboxEvent {
+    type: 'STOP_SANDBOX';
+}
+interface ExecEvent {
+    type: 'EXEC';
+    cmd: string;
+    cwd?: string;
+}
+/**
+ * Identity of the message sender — enables multi-client attribution
+ * in shared WebSocket sessions (web + CLI + API).
+ */
+interface MessageAuthor {
+    name: string;
+    clientType?: 'web' | 'cli' | 'api';
+    clientId?: string;
+}
+interface AgentMessageClientEvent {
+    type: 'AGENT_MESSAGE';
+    /** Client-generated message ID for deterministic ack handling */
+    clientMessageId?: string;
+    content: string;
+    /** Who sent this message — for multi-client attribution */
+    author?: MessageAuthor;
+    model?: {
+        id: string;
+        provider?: string;
+    };
+    config?: {
+        temperature?: number;
+        maxTokens?: number;
+    };
+    /** Direct system prompt text */
+    systemPrompt?: string;
+    /** Named prompt template (e.g., "claude-code") */
+    systemPromptName?: string;
+    /** Variables to compile into the prompt template */
+    systemPromptVariables?: Record<string, string>;
+    agentType?: string;
+}
+interface AgentStopEvent {
+    type: 'AGENT_STOP';
+}
+interface AgentResetEvent {
+    type: 'AGENT_RESET';
+}
+type ClientEvent = InitEvent | PingEvent | JoinSessionEvent | StartSandboxEvent | StopSandboxEvent | ExecEvent | AgentMessageClientEvent | AgentStopEvent | AgentResetEvent;
+/**
+ * Optional metadata added to persistable server events
+ * Events with eventId can be replayed on reconnection
+ */
+interface ServerEventMeta {
+    /** Unique event identifier for cursor-based resumption */
+    eventId?: string;
+    /** Monotonic event sequence for deterministic replay */
+    eventSequence?: number;
+    /** Server timestamp when event was created */
+    eventTimestamp?: number;
+}
+interface ConnectedServerEvent {
+    type: 'CONNECTED';
+    clientId: string;
+    sessionId: string;
+}
+interface ReadyServerEvent {
+    type: 'READY';
+    sandboxId: string | null;
+    sandboxUrl: string | null;
+}
+/**
+ * Batch of events sent on reconnection (Manus eventsNotifyEventsAfter pattern)
+ * Contains all events since the client's lastEventId cursor
+ */
+interface EventsBatchServerEvent {
+    type: 'EVENTS_BATCH';
+    /** Events since last cursor, in chronological order */
+    events: PersistableServerEvent[];
+    /** Latest event ID - client should use this as next cursor */
+    lastEventId: string;
+    /** Total events in batch */
+    count: number;
+}
+interface PongServerEvent {
+    type: 'PONG';
+    timestamp: number;
+}
+interface SandboxStatusServerEvent {
+    type: 'SANDBOX_STATUS';
+    status: 'idle' | 'booting' | 'ready' | 'error';
+    sandboxId?: string;
+    sandboxUrl?: string;
+    error?: string;
+}
+/**
+ * Lifecycle event - granular phase transitions
+ * Use for loading UI states and progress indicators
+ */
+interface LifecycleServerEvent {
+    type: 'LIFECYCLE';
+    phase: SandboxLifecycle;
+    message?: string;
+    progress?: number;
+    metadata?: Record<string, unknown>;
+}
+interface TermDataServerEvent {
+    type: 'TERM_DATA';
+    data: string;
+    stream: 'stdout' | 'stderr';
+}
+interface ExecCompleteServerEvent {
+    type: 'EXEC_COMPLETE';
+    exitCode: number;
+}
+interface SystemServerEvent {
+    type: 'SYSTEM';
+    msg: string;
+}
+interface ErrorServerEvent {
+    type: 'ERROR';
+    msg: string;
+    code?: string;
+}
+interface MessageAckServerEvent {
+    type: 'MESSAGE_ACK';
+    clientMessageId: string;
+    receivedAt: number;
+}
+interface MessageErrorServerEvent {
+    type: 'MESSAGE_ERROR';
+    clientMessageId: string;
+    error: string;
+}
+interface FileUploadedServerEvent {
+    type: 'FILE_UPLOADED';
+    path: string;
+    filename: string;
+    url: string;
+    mimeType: string;
+    description?: string;
+    sizeBytes?: number;
+}
+/**
+ * File to write to sandbox during bootstrap
+ */
+interface SandboxFile {
+    path: string;
+    content?: string;
+    url?: string;
+    encoding?: 'utf-8' | 'base64';
+}
+interface SandboxFile {
+    path: string;
+    name: string;
+    isDir: boolean;
+    size?: number;
+}
+interface FilesSyncServerEvent {
+    type: 'FILES_SYNC';
+    files: SandboxFile[];
+    dirs: string[];
+}
+interface AgentStartedServerEvent {
+    type: 'AGENT_STARTED';
+    prompt?: string;
+    clientMessageId?: string;
+    /** Who triggered this agent run — copied from client event */
+    author?: MessageAuthor;
+}
+interface TextContentBlock {
+    type: 'text';
+    text: string;
+}
+interface ToolUseContentBlock {
+    type: 'tool_use';
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+}
+interface ToolResultContentBlock {
+    type: 'tool_result';
+    tool_use_id: string;
+    content: string | null;
+    is_error?: boolean;
+}
+type ContentBlock = TextContentBlock | ToolUseContentBlock | ToolResultContentBlock;
+interface AgentMessageServerEvent {
+    type: 'AGENT_MESSAGE';
+    message?: {
+        content: ContentBlock[];
+    };
+    subtype?: string;
+    total_cost_usd?: number | null;
+    duration_ms?: number | null;
+    result?: string | null;
+    clientMessageId?: string;
+}
+interface AgentActionServerEvent {
+    type: 'AGENT_ACTION';
+    action: string;
+    id?: string;
+    input?: unknown;
+    status: 'executing' | 'complete' | 'error';
+    result?: string;
+    error?: string;
+}
+interface AgentStepCompleteServerEvent {
+    type: 'AGENT_STEP_COMPLETE';
+    success?: boolean;
+    cost?: number;
+    duration?: number;
+}
+interface AgentDoneServerEvent {
+    type: 'AGENT_DONE';
+    exitCode?: number;
+    sessionId?: string;
+    clientMessageId?: string;
+}
+interface AgentErrorServerEvent {
+    type: 'AGENT_ERROR';
+    error: string;
+    clientMessageId?: string;
+}
+interface AgentGenericServerEvent {
+    type: 'AGENT_EVENT';
+    [key: string]: unknown;
+}
+interface TocEventServerEvent {
+    type: 'TOC_REQUEST_RECEIVED' | 'TOC_AUTH_COMPLETED' | 'TOC_DB_QUERY_STARTED' | 'TOC_DB_QUERY_COMPLETED' | 'TOC_GCS_DOWNLOAD_STARTED' | 'TOC_GCS_DOWNLOAD_COMPLETED' | 'TOC_SANDBOX_CREATED' | 'TOC_EXTRACTION_STARTED' | 'TOC_EXTRACTION_COMPLETED' | 'TOC_RESPONSE_READY';
+    data?: Record<string, unknown>;
+    cost?: {
+        duration_ms?: number;
+        total_usd?: number;
+        input_tokens?: number;
+        output_tokens?: number;
+    };
+}
+/**
+ * Events that should be persisted and replayed on reconnection
+ * These events have state significance (not ephemeral like PONG)
+ */
+type PersistableServerEvent = (SandboxStatusServerEvent | LifecycleServerEvent | AgentStartedServerEvent | AgentMessageServerEvent | AgentActionServerEvent | AgentDoneServerEvent | AgentErrorServerEvent | SystemServerEvent | TocEventServerEvent) & ServerEventMeta;
+/**
+ * Event types that should NOT be persisted (ephemeral)
+ */
+declare const EPHEMERAL_EVENT_TYPES: Set<string>;
+/**
+ * Check if a server event should be persisted for replay
+ */
+declare function isPersistableEvent(event: ServerEvent): boolean;
+type ServerEvent = ConnectedServerEvent | ReadyServerEvent | EventsBatchServerEvent | PongServerEvent | MessageAckServerEvent | MessageErrorServerEvent | SandboxStatusServerEvent | LifecycleServerEvent | TermDataServerEvent | ExecCompleteServerEvent | SystemServerEvent | ErrorServerEvent | FileUploadedServerEvent | FilesSyncServerEvent | AgentStartedServerEvent | AgentMessageServerEvent | AgentActionServerEvent | AgentStepCompleteServerEvent | AgentDoneServerEvent | AgentErrorServerEvent | AgentGenericServerEvent | TocEventServerEvent;
+declare const ToolUseBlockSchema: z.ZodObject<{
+    type: z.ZodLiteral<"tool_use">;
+    name: z.ZodString;
+    input: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    type: "tool_use";
+    name: string;
+    input?: Record<string, unknown> | undefined;
+}, {
+    type: "tool_use";
+    name: string;
+    input?: Record<string, unknown> | undefined;
+}>;
+declare const TextBlockSchema: z.ZodObject<{
+    type: z.ZodLiteral<"text">;
+    text: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    text: string;
+    type: "text";
+}, {
+    text: string;
+    type: "text";
+}>;
+declare const ContentBlockSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+    type: z.ZodLiteral<"tool_use">;
+    name: z.ZodString;
+    input: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    type: "tool_use";
+    name: string;
+    input?: Record<string, unknown> | undefined;
+}, {
+    type: "tool_use";
+    name: string;
+    input?: Record<string, unknown> | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"text">;
+    text: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    text: string;
+    type: "text";
+}, {
+    text: string;
+    type: "text";
+}>]>;
+declare const AssistantMessageSchema: z.ZodObject<{
+    type: z.ZodLiteral<"assistant">;
+    message: z.ZodObject<{
+        content: z.ZodArray<z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+            type: z.ZodLiteral<"tool_use">;
+            name: z.ZodString;
+            input: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        }, "strip", z.ZodTypeAny, {
+            type: "tool_use";
+            name: string;
+            input?: Record<string, unknown> | undefined;
+        }, {
+            type: "tool_use";
+            name: string;
+            input?: Record<string, unknown> | undefined;
+        }>, z.ZodObject<{
+            type: z.ZodLiteral<"text">;
+            text: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            text: string;
+            type: "text";
+        }, {
+            text: string;
+            type: "text";
+        }>]>, "many">;
+    }, "strip", z.ZodTypeAny, {
+        content: ({
+            type: "tool_use";
+            name: string;
+            input?: Record<string, unknown> | undefined;
+        } | {
+            text: string;
+            type: "text";
+        })[];
+    }, {
+        content: ({
+            type: "tool_use";
+            name: string;
+            input?: Record<string, unknown> | undefined;
+        } | {
+            text: string;
+            type: "text";
+        })[];
+    }>;
+}, "strip", z.ZodTypeAny, {
+    type: "assistant";
+    message: {
+        content: ({
+            type: "tool_use";
+            name: string;
+            input?: Record<string, unknown> | undefined;
+        } | {
+            text: string;
+            type: "text";
+        })[];
+    };
+}, {
+    type: "assistant";
+    message: {
+        content: ({
+            type: "tool_use";
+            name: string;
+            input?: Record<string, unknown> | undefined;
+        } | {
+            text: string;
+            type: "text";
+        })[];
+    };
+}>;
+declare const ResultMessageSchema: z.ZodObject<{
+    type: z.ZodLiteral<"result">;
+    session_id: z.ZodOptional<z.ZodString>;
+    total_cost_usd: z.ZodOptional<z.ZodNumber>;
+    duration_ms: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    type: "result";
+    session_id?: string | undefined;
+    total_cost_usd?: number | undefined;
+    duration_ms?: number | undefined;
+}, {
+    type: "result";
+    session_id?: string | undefined;
+    total_cost_usd?: number | undefined;
+    duration_ms?: number | undefined;
+}>;
+declare const ErrorMessageSchema: z.ZodObject<{
+    type: z.ZodLiteral<"error">;
+    error: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    error: string;
+    type: "error";
+}, {
+    error: string;
+    type: "error";
+}>;
+declare const SystemMessageSchema: z.ZodObject<{
+    type: z.ZodLiteral<"system">;
+    message: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    type: "system";
+    message: string;
+}, {
+    type: "system";
+    message: string;
+}>;
+declare const AgentOutputMessageSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+    type: z.ZodLiteral<"assistant">;
+    message: z.ZodObject<{
+        content: z.ZodArray<z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+            type: z.ZodLiteral<"tool_use">;
+            name: z.ZodString;
+            input: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        }, "strip", z.ZodTypeAny, {
+            type: "tool_use";
+            name: string;
+            input?: Record<string, unknown> | undefined;
+        }, {
+            type: "tool_use";
+            name: string;
+            input?: Record<string, unknown> | undefined;
+        }>, z.ZodObject<{
+            type: z.ZodLiteral<"text">;
+            text: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            text: string;
+            type: "text";
+        }, {
+            text: string;
+            type: "text";
+        }>]>, "many">;
+    }, "strip", z.ZodTypeAny, {
+        content: ({
+            type: "tool_use";
+            name: string;
+            input?: Record<string, unknown> | undefined;
+        } | {
+            text: string;
+            type: "text";
+        })[];
+    }, {
+        content: ({
+            type: "tool_use";
+            name: string;
+            input?: Record<string, unknown> | undefined;
+        } | {
+            text: string;
+            type: "text";
+        })[];
+    }>;
+}, "strip", z.ZodTypeAny, {
+    type: "assistant";
+    message: {
+        content: ({
+            type: "tool_use";
+            name: string;
+            input?: Record<string, unknown> | undefined;
+        } | {
+            text: string;
+            type: "text";
+        })[];
+    };
+}, {
+    type: "assistant";
+    message: {
+        content: ({
+            type: "tool_use";
+            name: string;
+            input?: Record<string, unknown> | undefined;
+        } | {
+            text: string;
+            type: "text";
+        })[];
+    };
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"result">;
+    session_id: z.ZodOptional<z.ZodString>;
+    total_cost_usd: z.ZodOptional<z.ZodNumber>;
+    duration_ms: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    type: "result";
+    session_id?: string | undefined;
+    total_cost_usd?: number | undefined;
+    duration_ms?: number | undefined;
+}, {
+    type: "result";
+    session_id?: string | undefined;
+    total_cost_usd?: number | undefined;
+    duration_ms?: number | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"error">;
+    error: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    error: string;
+    type: "error";
+}, {
+    error: string;
+    type: "error";
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"system">;
+    message: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    type: "system";
+    message: string;
+}, {
+    type: "system";
+    message: string;
+}>]>;
+type ToolUseBlock = z.infer<typeof ToolUseBlockSchema>;
+type TextBlock = z.infer<typeof TextBlockSchema>;
+type AgentContentBlock = z.infer<typeof ContentBlockSchema>;
+type AssistantMessage = z.infer<typeof AssistantMessageSchema>;
+type ResultMessage = z.infer<typeof ResultMessageSchema>;
+type ErrorMessage = z.infer<typeof ErrorMessageSchema>;
+type SystemMessage = z.infer<typeof SystemMessageSchema>;
+type AgentOutputMessage = z.infer<typeof AgentOutputMessageSchema>;
+declare function parseAgentOutputMessage(line: string): AgentOutputMessage | null;
+declare function isClientEvent(data: unknown): data is ClientEvent;
+declare function isServerEvent(data: unknown): data is ServerEvent;
+declare function parseServerEvent(json: string): ServerEvent | null;
+declare function parseClientEvent(json: string): ClientEvent | null;
+type ClientMessage = ClientEvent;
+
+/**
+ * Shared types for agent-session
+ */
+interface SocketAttachment {
+    clientId: string;
+    userId?: string;
+    connectedAt: number;
+}
+interface SessionState {
+    sessionId: string;
+    sandboxId?: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Configuration for connecting to agent-session
+ */
+interface AgentSessionConfig {
+    /** WebSocket URL of the deployed worker */
+    url: string;
+    /** Session ID for this connection */
+    sessionId: string;
+    /** Optional user ID for tracking */
+    userId?: string;
+}
+
+/**
+ * Session Refresh Configuration
+ *
+ * Defines how the client should behave when the sessionId changes.
+ * This is critical for document isolation in multi-document applications.
+ */
+/**
+ * Refresh strategies for session changes
+ *
+ * - 'reset': Clear all client state and connect fresh (recommended for document isolation)
+ * - 'preserve': Attempt to reconnect to existing sandbox (for tab persistence scenarios)
+ */
+type SessionRefreshStrategy = 'reset' | 'preserve';
+interface SessionRefreshConfig {
+    /**
+     * What to do when sessionId changes:
+     *
+     * 'reset' (default, recommended):
+     *   - Clear sandboxId, sandboxUrl, messages, agentSessionId
+     *   - Disconnect from old socket
+     *   - Connect to new session with clean slate
+     *   - Use this when sessionId represents a document UUID
+     *
+     * 'preserve':
+     *   - Keep existing state during reconnection
+     *   - Useful for browser tab persistence where same user returns
+     *   - NOT recommended when switching between documents
+     */
+    onSessionChange: SessionRefreshStrategy;
+    /**
+     * Whether to clear chat messages when session changes (only applies to 'reset' strategy)
+     * Default: true
+     */
+    clearMessagesOnReset?: boolean;
+    /**
+     * Whether to clear agent session ID when session changes (only applies to 'reset' strategy)
+     * Default: true
+     */
+    clearAgentSessionOnReset?: boolean;
+}
+/**
+ * Default configuration - full reset on session change
+ * This is the safest option for document isolation
+ */
+declare const DEFAULT_SESSION_REFRESH_CONFIG: SessionRefreshConfig;
+/**
+ * Preserve configuration - for tab persistence scenarios
+ * Use with caution - only when you know the user is returning to the same document
+ */
+declare const PRESERVE_SESSION_CONFIG: SessionRefreshConfig;
+/**
+ * Helper to determine if state should be reset based on config
+ */
+declare function shouldResetOnSessionChange(config: SessionRefreshConfig, oldSessionId: string | null, newSessionId: string | null): boolean;
+
+export { type AgentActionServerEvent, type AgentContentBlock, type AgentDoneServerEvent, type AgentErrorServerEvent, type AgentGenericServerEvent, type AgentMessageClientEvent, type AgentMessageServerEvent, type AgentOutputMessage, AgentOutputMessageSchema, type AgentResetEvent, type AgentSessionConfig, type AgentStartedServerEvent, type AgentStepCompleteServerEvent, type AgentStopEvent, type AssistantMessage, AssistantMessageSchema, type ClientEvent, ClientEventType, type ClientMessage, type ConnectedServerEvent, type ContentBlock, ContentBlockSchema, DEFAULT_SESSION_REFRESH_CONFIG, EPHEMERAL_EVENT_TYPES, type ErrorMessage, ErrorMessageSchema, type ErrorServerEvent, type EventsBatchServerEvent, type ExecCompleteServerEvent, type ExecEvent, type FileUploadedServerEvent, type FilesSyncServerEvent, type InitEvent, type JoinSessionEvent, type LifecycleServerEvent, type MessageAckServerEvent, type MessageAuthor, type MessageErrorServerEvent, PRESERVE_SESSION_CONFIG, type PersistableServerEvent, type PingEvent, type PongServerEvent, type ReadyServerEvent, type ResultMessage, ResultMessageSchema, type SandboxBootstrapOptions, type SandboxFile, SandboxLifecycle, SandboxStatus, type SandboxStatusServerEvent, type ServerEvent, type ServerEventMeta, ServerEventType, type SessionRefreshConfig, type SessionRefreshStrategy, type SessionState, type SocketAttachment, type StartSandboxEvent, type StopSandboxEvent, type SystemMessage, SystemMessageSchema, type SystemServerEvent, type TermDataServerEvent, type TextBlock, TextBlockSchema, type TextContentBlock, type TocEventServerEvent, type ToolResultContentBlock, type ToolUseBlock, ToolUseBlockSchema, type ToolUseContentBlock, isClientEvent, isPersistableEvent, isServerEvent, parseAgentOutputMessage, parseClientEvent, parseServerEvent, parseSystemMessageToLifecycle, shouldResetOnSessionChange };