@chucky.cloud/sdk 0.2.7 → 0.3.0

package/dist/index.d.ts

@@ -1,68 +1,1973 @@
 /**
- * @chucky.cloud/sdk
+ * Tool Definition Types
  *
- * SDK for interacting with Chucky sandbox - supports both browser and Node.js.
+ * Types for defining tools that can be executed by Claude.
+ * Supports both server-side and browser-side execution.
+ */
+/**
+ * JSON Schema property types
+ */
+type JsonSchemaType = 'string' | 'number' | 'integer' | 'boolean' | 'array' | 'object' | 'null';
+/**
+ * JSON Schema property definition
+ */
+interface JsonSchemaProperty {
+    /** Property type */
+    type: JsonSchemaType;
+    /** Human-readable description */
+    description?: string;
+    /** Enumeration of allowed values */
+    enum?: string[];
+    /** Default value */
+    default?: unknown;
+    /** For arrays: schema of array items */
+    items?: JsonSchemaProperty;
+    /** For objects: nested properties */
+    properties?: Record<string, JsonSchemaProperty>;
+    /** For objects: required property names */
+    required?: string[];
+    /** Minimum value (for numbers) */
+    minimum?: number;
+    /** Maximum value (for numbers) */
+    maximum?: number;
+    /** Minimum length (for strings/arrays) */
+    minLength?: number;
+    /** Maximum length (for strings/arrays) */
+    maxLength?: number;
+    /** Pattern (for strings) */
+    pattern?: string;
+}
+/**
+ * JSON Schema for tool input
+ */
+interface ToolInputSchema {
+    /** Always 'object' for tool inputs */
+    type: 'object';
+    /** Property definitions */
+    properties: Record<string, JsonSchemaProperty>;
+    /** Required property names */
+    required?: string[];
+    /** Allow additional properties */
+    additionalProperties?: boolean;
+}
+/**
+ * Tool content types for results
+ */
+type ToolContentType = 'text' | 'image' | 'resource';
+/**
+ * Text content in tool result (MCP format)
+ */
+interface ToolTextContent {
+    type: 'text';
+    text: string;
+}
+/**
+ * Image content in tool result (MCP format)
+ */
+interface ToolImageContent {
+    type: 'image';
+    /** Base64-encoded image data */
+    data: string;
+    /** MIME type (e.g., 'image/png') */
+    mimeType: string;
+}
+/**
+ * Resource content in tool result
+ */
+interface ResourceContent {
+    type: 'resource';
+    /** Resource URI */
+    uri: string;
+    /** MIME type */
+    mimeType?: string;
+    /** Resource text content */
+    text?: string;
+    /** Resource binary data (base64) */
+    blob?: string;
+}
+/**
+ * Union type for all tool content
+ */
+type ToolContent = ToolTextContent | ToolImageContent | ResourceContent;
+/**
+ * Tool execution result
+ */
+interface ToolResult {
+    /** Result content */
+    content: ToolContent[];
+    /** Whether this is an error result */
+    isError?: boolean;
+}
+/**
+ * Where the tool should be executed
+ */
+type ToolExecutionLocation = 'server' | 'browser';
+/**
+ * Tool handler function type
+ */
+type ToolHandler<TInput = Record<string, unknown>> = (input: TInput) => ToolResult | Promise<ToolResult>;
+/**
+ * Tool definition
+ */
+interface ToolDefinition<TInput = Record<string, unknown>> {
+    /** Unique tool name */
+    name: string;
+    /** Human-readable description of what the tool does */
+    description: string;
+    /** JSON Schema defining the input parameters */
+    inputSchema: ToolInputSchema;
+    /**
+     * Where the tool should be executed
+     * @default 'server'
+     */
+    executeIn?: ToolExecutionLocation;
+    /**
+     * Handler function (required for browser tools, optional for server tools)
+     */
+    handler?: ToolHandler<TInput>;
+}
+/**
+ * MCP Server with client-side tools (handlers run in your app)
+ * This is our custom format - bridge converts to SDK format
+ */
+interface McpClientToolsServer {
+    /** Server name */
+    name: string;
+    /** Server version */
+    version?: string;
+    /** Tools with handlers that execute client-side */
+    tools: ToolDefinition[];
+}
+/**
+ * MCP Stdio server configuration
+ */
+interface McpStdioServerConfig {
+    /** Server name */
+    name: string;
+    /** Server type */
+    type?: 'stdio';
+    /** Command to run */
+    command: string;
+    /** Command arguments */
+    args?: string[];
+    /** Environment variables */
+    env?: Record<string, string>;
+}
+/**
+ * MCP SSE server configuration
+ */
+interface McpSSEServerConfig {
+    /** Server name */
+    name: string;
+    /** Server type */
+    type: 'sse';
+    /** SSE endpoint URL */
+    url: string;
+    /** Request headers */
+    headers?: Record<string, string>;
+}
+/**
+ * MCP HTTP server configuration
+ */
+interface McpHttpServerConfig {
+    /** Server name */
+    name: string;
+    /** Server type */
+    type: 'http';
+    /** HTTP endpoint URL */
+    url: string;
+    /** Request headers */
+    headers?: Record<string, string>;
+}
+/**
+ * MCP Server definition - all supported server types
+ * Array format - bridge converts to Record<string, config> for official SDK
+ */
+type McpServerDefinition = McpClientToolsServer | McpStdioServerConfig | McpSSEServerConfig | McpHttpServerConfig;
+/**
+ * Tool preset configuration
+ */
+interface ToolPreset {
+    type: 'preset';
+    preset: 'claude_code';
+}
+/**
+ * Tools configuration - either allowlist of names or preset
+ */
+type ToolsConfig = string[] | ToolPreset;
+/**
+ * Tool call from the model
+ */
+interface ToolCall {
+    /** Unique call ID */
+    callId: string;
+    /** Tool name */
+    toolName: string;
+    /** Input arguments */
+    input: Record<string, unknown>;
+}
+/**
+ * Tool call response
+ */
+interface ToolCallResponse {
+    /** Call ID (must match the tool call) */
+    callId: string;
+    /** Tool execution result */
+    result: ToolResult;
+}
+
+/**
+ * SDK Options Types
+ *
+ * These types define all configuration options for sessions and prompts.
+ * Designed for both browser and Node.js environments.
+ */
+
+/**
+ * Available Claude models
+ */
+type Model = 'claude-sonnet-4-5-20250929' | 'claude-opus-4-5-20251101' | 'claude-3-5-sonnet-20241022' | 'claude-3-5-haiku-20241022' | 'claude-3-opus-20240229' | (string & {});
+/**
+ * System prompt configuration
+ */
+type SystemPrompt = string | {
+    /** Use a preset system prompt */
+    type: 'preset';
+    /** The preset name */
+    preset: 'claude_code';
+    /** Additional text to append to the preset */
+    append?: string;
+};
+/**
+ * Output format configuration for structured outputs
+ */
+interface OutputFormat {
+    /** Output format type */
+    type: 'json_schema';
+    /** JSON Schema definition for the expected output */
+    schema: Record<string, unknown>;
+}
+/**
+ * Agent definition for sub-agents
+ */
+interface AgentDefinition {
+    /** Agent name */
+    name: string;
+    /** Agent description */
+    description?: string;
+    /** Model to use for this agent */
+    model?: Model;
+    /** System prompt for this agent */
+    systemPrompt?: SystemPrompt;
+    /** Tools available to this agent */
+    tools?: string[];
+    /** Maximum turns for this agent */
+    maxTurns?: number;
+}
+/**
+ * Base options shared between sessions and prompts
+ */
+interface BaseOptions {
+    /**
+     * The model to use for generation
+     * @default 'claude-sonnet-4-5-20250929'
+     */
+    model?: Model;
+    /**
+     * Fallback model if primary model is unavailable
+     */
+    fallbackModel?: Model;
+    /**
+     * Maximum number of conversation turns
+     */
+    maxTurns?: number;
+    /**
+     * Maximum budget in USD for this session/prompt
+     */
+    maxBudgetUsd?: number;
+    /**
+     * Maximum thinking tokens (for extended thinking)
+     */
+    maxThinkingTokens?: number;
+    /**
+     * System prompt or preset configuration
+     */
+    systemPrompt?: SystemPrompt;
+    /**
+     * Tool configuration - allowlist of tool names or preset
+     * Pass an array of tool names or use the preset to get Claude Code's default tools
+     */
+    tools?: ToolsConfig;
+    /**
+     * List of tool names that are allowed
+     */
+    allowedTools?: string[];
+    /**
+     * List of tool names that are blocked
+     */
+    disallowedTools?: string[];
+    /**
+     * MCP server definitions (array format)
+     * Bridge translates to Record format for official SDK
+     */
+    mcpServers?: McpServerDefinition[];
+    /**
+     * Sub-agent definitions
+     */
+    agents?: Record<string, AgentDefinition>;
+    /**
+     * Beta features to enable
+     */
+    betas?: string[];
+    /**
+     * Permission mode for sandbox operations
+     */
+    permissionMode?: 'default' | 'plan' | 'bypassPermissions';
+    /**
+     * Allow dangerous operations (use with caution)
+     */
+    allowDangerouslySkipPermissions?: boolean;
+    /**
+     * Custom environment variables
+     */
+    env?: Record<string, string>;
+    /**
+     * Output format for structured responses
+     */
+    outputFormat?: OutputFormat;
+    /**
+     * Include partial messages in the stream
+     */
+    includePartialMessages?: boolean;
+}
+/**
+ * Session-specific options
+ */
+interface SessionOptions extends BaseOptions {
+    /**
+     * Session ID for resuming an existing session
+     */
+    sessionId?: string;
+    /**
+     * Fork from an existing session instead of resuming
+     */
+    forkSession?: boolean;
+    /**
+     * Resume session at a specific conversation ID
+     */
+    resumeSessionAt?: string;
+    /**
+     * Continue from where the session left off
+     */
+    continue?: boolean;
+    /**
+     * Settings sources for configuration
+     */
+    settingSources?: Array<'user' | 'project' | 'local'>;
+    /**
+     * Job ID for tracking background/deferred executions
+     */
+    jobId?: string;
+}
+/**
+ * Prompt-specific options (stateless, one-shot)
+ */
+interface PromptOptions extends BaseOptions {
+    /**
+     * The prompt message to send
+     */
+    message: string;
+}
+/**
+ * Client configuration options
+ */
+interface ClientOptions {
+    /**
+     * Base URL for the Chucky service
+     * @default 'wss://box.chucky.cloud'
+     */
+    baseUrl?: string;
+    /**
+     * Authentication token (JWT)
+     */
+    token: string;
+    /**
+     * Enable debug logging
+     */
+    debug?: boolean;
+    /**
+     * Connection timeout in milliseconds
+     * @default 30000
+     */
+    timeout?: number;
+    /**
+     * Keep-alive interval in milliseconds
+     * @default 300000 (5 minutes)
+     */
+    keepAliveInterval?: number;
+    /**
+     * Auto-reconnect on disconnect
+     * @default true
+     */
+    autoReconnect?: boolean;
+    /**
+     * Maximum reconnect attempts
+     * @default 5
+     */
+    maxReconnectAttempts?: number;
+}
+/**
+ * Connection status
+ */
+type ConnectionStatus = 'disconnected' | 'connecting' | 'connected' | 'reconnecting' | 'error';
+/**
+ * Event handlers for client events
+ */
+interface ClientEventHandlers {
+    /** Called when connection status changes */
+    onStatusChange?: (status: ConnectionStatus) => void;
+    /** Called when a raw message is sent or received (for debugging) */
+    onRawMessage?: (direction: 'in' | 'out', message: unknown) => void;
+    /** Called when an error occurs */
+    onError?: (error: Error) => void;
+}
+
+/**
+ * WebSocket Message Types
+ *
+ * Matches the official Claude Agent SDK message format.
+ * See: https://platform.claude.com/docs/en/agent-sdk/typescript
+ */
+
+type UUID = string;
+/**
+ * Anthropic API message content types
+ */
+type TextContent = {
+    type: 'text';
+    text: string;
+};
+type ImageContent = {
+    type: 'image';
+    source: {
+        type: 'base64';
+        media_type: string;
+        data: string;
+    };
+};
+type ToolUseContent = {
+    type: 'tool_use';
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+};
+type ToolResultContent = {
+    type: 'tool_result';
+    tool_use_id: string;
+    content: string | Array<TextContent | ImageContent>;
+    is_error?: boolean;
+};
+type ContentBlock$1 = TextContent | ImageContent | ToolUseContent | ToolResultContent;
+/**
+ * Anthropic API User Message
+ */
+interface APIUserMessage {
+    role: 'user';
+    content: string | ContentBlock$1[];
+}
+/**
+ * Anthropic API Assistant Message
+ */
+interface APIAssistantMessage {
+    role: 'assistant';
+    content: ContentBlock$1[];
+}
+/**
+ * User message - sent by the client
+ */
+interface SDKUserMessage {
+    type: 'user';
+    uuid?: UUID;
+    session_id: string;
+    message: APIUserMessage;
+    parent_tool_use_id: string | null;
+}
+/**
+ * Assistant message - response from Claude
+ */
+interface SDKAssistantMessage {
+    type: 'assistant';
+    uuid: UUID;
+    session_id: string;
+    message: APIAssistantMessage;
+    parent_tool_use_id: string | null;
+}
+/**
+ * Result message subtypes
+ */
+type ResultSubtype = 'success' | 'error_max_turns' | 'error_during_execution' | 'error_max_budget_usd' | 'error_max_structured_output_retries';
+/**
+ * Success result message
+ */
+interface SDKResultMessageSuccess {
+    type: 'result';
+    subtype: 'success';
+    uuid: UUID;
+    session_id: string;
+    duration_ms: number;
+    duration_api_ms: number;
+    is_error: boolean;
+    num_turns: number;
+    result: string;
+    total_cost_usd: number;
+    usage: {
+        input_tokens: number;
+        output_tokens: number;
+        cache_creation_input_tokens: number;
+        cache_read_input_tokens: number;
+    };
+    structured_output?: unknown;
+}
+/**
+ * Error result message
+ */
+interface SDKResultMessageError {
+    type: 'result';
+    subtype: Exclude<ResultSubtype, 'success'>;
+    uuid: UUID;
+    session_id: string;
+    duration_ms: number;
+    duration_api_ms: number;
+    is_error: boolean;
+    num_turns: number;
+    total_cost_usd: number;
+    usage: {
+        input_tokens: number;
+        output_tokens: number;
+        cache_creation_input_tokens: number;
+        cache_read_input_tokens: number;
+    };
+    errors: string[];
+}
+type SDKResultMessage = SDKResultMessageSuccess | SDKResultMessageError;
+/**
+ * System message subtypes
+ */
+type SystemSubtype = 'init' | 'compact_boundary';
+/**
+ * System init message
+ */
+interface SDKSystemMessageInit {
+    type: 'system';
+    subtype: 'init';
+    uuid: UUID;
+    session_id: string;
+    cwd: string;
+    tools: string[];
+    mcp_servers: Array<{
+        name: string;
+        status: string;
+    }>;
+    model: string;
+    permissionMode: string;
+}
+/**
+ * System compact boundary message
+ */
+interface SDKSystemMessageCompact {
+    type: 'system';
+    subtype: 'compact_boundary';
+    uuid: UUID;
+    session_id: string;
+    compact_metadata: {
+        trigger: 'manual' | 'auto';
+        pre_tokens: number;
+    };
+}
+type SDKSystemMessage = SDKSystemMessageInit | SDKSystemMessageCompact;
+/**
+ * Partial assistant message (streaming)
+ */
+interface SDKPartialAssistantMessage {
+    type: 'stream_event';
+    event: unknown;
+    parent_tool_use_id: string | null;
+    uuid: UUID;
+    session_id: string;
+}
+/**
+ * All SDK message types (matching official SDK)
+ */
+type SDKMessage = SDKUserMessage | SDKAssistantMessage | SDKResultMessage | SDKSystemMessage | SDKPartialAssistantMessage;
+/**
+ * WebSocket envelope types for our transport
+ */
+type WsEnvelopeType = 'init' | 'user' | 'assistant' | 'result' | 'system' | 'stream_event' | 'control' | 'error' | 'ping' | 'pong' | 'tool_call' | 'tool_result';
+/**
+ * Init message payload (session initialization)
+ */
+interface InitPayload extends Omit<SessionOptions, 'mcpServers'> {
+    mcpServers?: unknown[];
+}
+/**
+ * Control message actions
+ */
+type ControlAction = 'ready' | 'session_info' | 'end_input' | 'close';
+/**
+ * Control message payload
+ */
+interface ControlPayload {
+    action: ControlAction;
+    data?: Record<string, unknown>;
+}
+/**
+ * Error message payload
+ */
+interface ErrorPayload {
+    message: string;
+    code?: string;
+    details?: Record<string, unknown>;
+}
+/**
+ * Ping/Pong payload
+ */
+interface PingPongPayload {
+    timestamp: number;
+}
+/**
+ * Tool call payload (server -> client)
+ */
+interface ToolCallPayload extends ToolCall {
+}
+/**
+ * Tool result payload (client -> server)
+ */
+interface ToolResultPayload {
+    callId: string;
+    result: ToolResult;
+}
+interface InitEnvelope {
+    type: 'init';
+    payload: InitPayload;
+}
+interface ControlEnvelope {
+    type: 'control';
+    payload: ControlPayload;
+}
+interface ErrorEnvelope {
+    type: 'error';
+    payload: ErrorPayload;
+}
+interface PingEnvelope {
+    type: 'ping';
+    payload: PingPongPayload;
+}
+interface PongEnvelope {
+    type: 'pong';
+    payload: PingPongPayload;
+}
+interface ToolCallEnvelope {
+    type: 'tool_call';
+    payload: ToolCallPayload;
+}
+interface ToolResultEnvelope {
+    type: 'tool_result';
+    payload: ToolResultPayload;
+}
+/**
+ * Outgoing messages (client -> server)
+ */
+type OutgoingMessage = InitEnvelope | SDKUserMessage | ControlEnvelope | PingEnvelope | ToolResultEnvelope;
+/**
+ * Incoming messages (server -> client)
+ */
+type IncomingMessage = SDKAssistantMessage | SDKResultMessage | SDKSystemMessage | SDKPartialAssistantMessage | ControlEnvelope | ErrorEnvelope | PongEnvelope | ToolCallEnvelope;
+/**
+ * All messages
+ */
+type AnyMessage = OutgoingMessage | IncomingMessage;
+/**
+ * Create an init message
+ */
+declare function createInitMessage(payload: InitPayload): InitEnvelope;
+/**
+ * Create a user message (official SDK format)
+ */
+declare function createUserMessage(content: string | ContentBlock$1[], sessionId: string, options?: {
+    uuid?: UUID;
+    parentToolUseId?: string | null;
+}): SDKUserMessage;
+/**
+ * Create a control message
+ */
+declare function createControlMessage(action: ControlAction, data?: Record<string, unknown>): ControlEnvelope;
+/**
+ * Create a ping message
+ */
+declare function createPingMessage(): PingEnvelope;
+/**
+ * Create a tool result message
+ */
+declare function createToolResultMessage(callId: string, result: ToolResult): ToolResultEnvelope;
+/**
+ * Check if message is a user message
+ */
+declare function isUserMessage(message: AnyMessage): message is SDKUserMessage;
+/**
+ * Check if message is an assistant message
+ */
+declare function isAssistantMessage(message: AnyMessage): message is SDKAssistantMessage;
+/**
+ * Check if message is a result message
+ */
+declare function isResultMessage(message: AnyMessage): message is SDKResultMessage;
+/**
+ * Check if message is a success result
+ */
+declare function isSuccessResult(message: AnyMessage): message is SDKResultMessageSuccess;
+/**
+ * Check if message is an error result
+ */
+declare function isErrorResult(message: AnyMessage): message is SDKResultMessageError;
+/**
+ * Check if message is a system message
+ */
+declare function isSystemMessage(message: AnyMessage): message is SDKSystemMessage;
+/**
+ * Check if message is a stream event
+ */
+declare function isStreamEvent(message: AnyMessage): message is SDKPartialAssistantMessage;
+/**
+ * Check if message is a tool call
+ */
+declare function isToolCallMessage(message: AnyMessage): message is ToolCallEnvelope;
+/**
+ * Check if message is a control message
+ */
+declare function isControlMessage(message: AnyMessage): message is ControlEnvelope;
+/**
+ * Check if message is an error message
+ */
+declare function isErrorMessage(message: AnyMessage): message is ErrorEnvelope;
+
+/**
+ * Result Types
+ *
+ * Types for responses from sessions and prompts.
+ */
+/**
+ * Message role
+ */
+type MessageRole = 'user' | 'assistant' | 'system';
+/**
+ * Content block types
+ */
+type ContentBlockType = 'text' | 'tool_use' | 'tool_result' | 'thinking' | 'image';
+/**
+ * Text content block
+ */
+interface TextBlock {
+    type: 'text';
+    text: string;
+}
+/**
+ * Tool use content block
+ */
+interface ToolUseBlock {
+    type: 'tool_use';
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+}
+/**
+ * Tool result content block
+ */
+interface ToolResultBlock {
+    type: 'tool_result';
+    tool_use_id: string;
+    content: string | Array<{
+        type: 'text';
+        text: string;
+    }>;
+    is_error?: boolean;
+}
+/**
+ * Thinking content block (extended thinking)
+ */
+interface ThinkingBlock {
+    type: 'thinking';
+    thinking: string;
+}
+/**
+ * Image content block
+ */
+interface ImageBlock {
+    type: 'image';
+    source: {
+        type: 'base64';
+        media_type: string;
+        data: string;
+    };
+}
+/**
+ * Union type for all content blocks
+ */
+type ContentBlock = TextBlock | ToolUseBlock | ToolResultBlock | ThinkingBlock | ImageBlock;
+/**
+ * A message in the conversation
+ */
+interface Message {
+    /** Message role */
+    role: MessageRole;
+    /** Message content */
+    content: ContentBlock[] | string;
+}
+/**
+ * Usage statistics
+ */
+interface Usage {
+    /** Input tokens used */
+    input_tokens: number;
+    /** Output tokens generated */
+    output_tokens: number;
+    /** Cache creation input tokens */
+    cache_creation_input_tokens?: number;
+    /** Cache read input tokens */
+    cache_read_input_tokens?: number;
+}
+/**
+ * Cost breakdown
+ */
+interface CostBreakdown {
+    /** Input cost in USD */
+    input_cost_usd: number;
+    /** Output cost in USD */
+    output_cost_usd: number;
+    /** Total cost in USD */
+    total_cost_usd: number;
+}
+/**
+ * Session result (returned when session completes)
+ */
+interface SessionResult {
+    /** Result type */
+    type: 'result';
+    /** Result subtype */
+    subtype?: 'success' | 'error' | 'interrupted';
+    /** Final response text */
+    text?: string;
+    /** Conversation messages */
+    messages?: Message[];
+    /** Total cost in USD */
+    total_cost_usd?: number;
+    /** Session duration in seconds */
+    duration_secs?: number;
+    /** Number of conversation turns */
+    turn_count?: number;
+    /** Usage statistics */
+    usage?: Usage;
+    /** Session ID (for resuming) */
+    session_id?: string;
+    /** Error message (if subtype is 'error') */
+    error?: string;
+}
+/**
+ * Prompt result (returned from one-shot prompts)
+ */
+interface PromptResult {
+    /** Result type */
+    type: 'result';
+    /** Result subtype */
+    subtype?: 'success' | 'error';
+    /** Response text */
+    text?: string;
+    /** Structured output (if outputFormat was specified) */
+    output?: unknown;
+    /** Total cost in USD */
+    total_cost_usd?: number;
+    /** Duration in seconds */
+    duration_secs?: number;
+    /** Usage statistics */
+    usage?: Usage;
+    /** Error message (if subtype is 'error') */
+    error?: string;
+}
+/**
+ * Streaming message event
+ */
+interface StreamEvent {
+    /** Event type */
+    type: 'message_start' | 'content_block_start' | 'content_block_delta' | 'content_block_stop' | 'message_delta' | 'message_stop' | 'tool_use' | 'tool_result' | 'error';
+    /** Event data */
+    data: unknown;
+}
+/**
+ * Partial message (during streaming)
+ */
+interface PartialMessage {
+    /** Message role */
+    role: MessageRole;
+    /** Partial content accumulated so far */
+    content: ContentBlock[];
+    /** Whether the message is complete */
+    complete: boolean;
+}
+/**
+ * Session state
+ */
+type SessionState = 'idle' | 'initializing' | 'ready' | 'processing' | 'waiting_tool' | 'completed' | 'error';
+/**
+ * Session info (returned when connecting/resuming)
+ */
+interface SessionInfo {
+    /** Session ID */
+    sessionId?: string;
+    /** Current state */
+    state?: SessionState;
+    /** Number of messages in conversation */
+    messageCount?: number;
+    /** Session creation time (ISO 8601) */
+    createdAt?: string;
+    /** Last activity time (ISO 8601) */
+    lastActivityAt?: string;
+    /** Model being used */
+    model?: string;
+    /** Available tools */
+    tools?: string[];
+}
+
+/**
+ * Transport Interface
+ *
+ * Abstract interface for communication between the SDK and Chucky server.
+ * Implementations can use WebSocket (browser/Node.js) or other protocols.
+ */
+
+/**
+ * Transport event types
+ */
+interface TransportEvents extends ClientEventHandlers {
+    /** Called when a message is received */
+    onMessage?: (message: IncomingMessage) => void;
+    /** Called when the transport is closed */
+    onClose?: (code?: number, reason?: string) => void;
+}
+/**
+ * Transport configuration
+ */
+interface TransportConfig {
+    /** Server URL */
+    url: string;
+    /** Authentication token */
+    token: string;
+    /** Connection timeout in milliseconds */
+    timeout?: number;
+    /** Keep-alive interval in milliseconds */
+    keepAliveInterval?: number;
+    /** Auto-reconnect on disconnect */
+    autoReconnect?: boolean;
+    /** Maximum reconnect attempts */
+    maxReconnectAttempts?: number;
+    /** Debug mode */
+    debug?: boolean;
+}
+/**
+ * Abstract transport interface
+ */
+interface Transport {
+    /** Current connection status */
+    readonly status: ConnectionStatus;
+    /**
+     * Connect to the server
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from the server
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Send a message to the server
+     */
+    send(message: OutgoingMessage): Promise<void>;
+    /**
+     * Set event handlers
+     */
+    setEventHandlers(handlers: TransportEvents): void;
+    /**
+     * Wait for connection to be ready
+     */
+    waitForReady(): Promise<void>;
+}
+/**
+ * Base transport class with common functionality
+ */
+declare abstract class BaseTransport implements Transport {
+    protected _status: ConnectionStatus;
+    protected handlers: TransportEvents;
+    protected config: TransportConfig;
+    constructor(config: TransportConfig);
+    get status(): ConnectionStatus;
+    protected setStatus(status: ConnectionStatus): void;
+    protected log(...args: unknown[]): void;
+    protected logError(...args: unknown[]): void;
+    setEventHandlers(handlers: TransportEvents): void;
+    abstract connect(): Promise<void>;
+    abstract disconnect(): Promise<void>;
+    abstract send(message: OutgoingMessage): Promise<void>;
+    abstract waitForReady(): Promise<void>;
+}
+
+/**
+ * Session
+ *
+ * Represents a conversation session with the Chucky sandbox.
+ * Matches the official Claude Agent SDK V2 interface.
  *
  * @example
  * ```typescript
- * import { ChuckyClient, tool, createBudget, createToken } from '@chucky.cloud/sdk';
+ * const session = createSession({ token, model: 'claude-sonnet-4-5-20250929' });
  *
- * // Server-side: Create a token for your user
- * const token = await createToken({
- *   userId: 'user-123',
- *   projectId: 'your-project-uuid',
- *   secret: 'your-hmac-secret',
- *   budget: createBudget({
- *     aiDollars: 1.00,
- *     computeHours: 1,
- *     window: 'day',
+ * await session.send('Hello!');
+ * for await (const msg of session.stream()) {
+ *   if (msg.type === 'assistant') {
+ *     console.log(getAssistantText(msg));
+ *   }
+ * }
+ * ```
+ */
+
+/**
+ * Session event handlers
+ */
+interface SessionEventHandlers {
+    onSessionInfo?: (info: SessionInfo) => void;
+    onError?: (error: Error) => void;
+}
+/**
+ * Internal session configuration
+ */
+interface SessionConfig {
+    debug?: boolean;
+}
+/**
+ * Session class - matches official V2 SDK interface
+ *
+ * Usage:
+ * ```typescript
+ * const session = createSession({ token, model: 'claude-sonnet-4-5-20250929' });
+ *
+ * // Multi-turn conversation
+ * await session.send('What is 5 + 3?');
+ * for await (const msg of session.stream()) {
+ *   if (msg.type === 'result') console.log(msg.result);
+ * }
+ *
+ * await session.send('Multiply that by 2');
+ * for await (const msg of session.stream()) {
+ *   if (msg.type === 'result') console.log(msg.result);
+ * }
+ *
+ * session.close();
+ * ```
+ */
+declare class Session {
+    private transport;
+    private options;
+    private config;
+    private eventHandlers;
+    private toolHandlers;
+    private messageBuffer;
+    private _state;
+    private _sessionId;
+    private messageResolvers;
+    private connected;
+    private connectPromise;
+    constructor(transport: Transport, options: SessionOptions, config?: SessionConfig);
+    /**
+     * Get the session ID
+     */
+    get sessionId(): string;
+    /**
+     * Set event handlers
+     */
+    on(handlers: SessionEventHandlers): this;
+    /**
+     * Connect and initialize the session (called automatically on first send)
+     */
+    private ensureConnected;
+    private connect;
+    /**
+     * Send a message to the session
+     *
+     * Matches V2 SDK: send() returns Promise<void>
+     * Use stream() to get the response.
+     *
+     * @example
+     * ```typescript
+     * await session.send('Hello!');
+     * for await (const msg of session.stream()) {
+     *   // Handle messages
+     * }
+     * ```
+     */
+    send(message: string): Promise<void>;
+    /**
+     * Stream the response after sending a message
+     *
+     * Matches V2 SDK: Returns AsyncGenerator<SDKMessage>
+     *
+     * @example
+     * ```typescript
+     * await session.send('Hello!');
+     * for await (const msg of session.stream()) {
+     *   if (msg.type === 'assistant') {
+     *     const text = msg.message.content
+     *       .filter(b => b.type === 'text')
+     *       .map(b => b.text)
+     *       .join('');
+     *     console.log(text);
+     *   }
+     *   if (msg.type === 'result') {
+     *     console.log('Done:', msg.result);
+     *   }
+     * }
+     * ```
+     */
+    stream(): AsyncGenerator<SDKMessage, void, unknown>;
+    /**
+     * Receive messages (alias for stream for V2 compatibility)
+     */
+    receive(): AsyncGenerator<SDKMessage, void, unknown>;
+    /**
+     * Close the session
+     */
+    close(): void;
+    /**
+     * Support for `await using` (TypeScript 5.2+)
+     */
+    [Symbol.asyncDispose](): Promise<void>;
+    /**
+     * Build init payload from options
+     */
+    private buildInitPayload;
+    /**
+     * Handle incoming message
+     */
+    private handleMessage;
+    /**
+     * Wait for session to be ready
+     */
+    private waitForReady;
+    /**
+     * Wait for next message
+     */
+    private waitForNextMessage;
+    /**
+     * Handle a tool call
+     */
+    private handleToolCall;
+    /**
+     * Log debug messages
+     */
+    private log;
+}
+/**
+ * Extract text from an assistant message
+ */
+declare function getAssistantText(msg: SDKMessage): string | null;
+/**
+ * Extract result from a result message
+ */
+declare function getResultText(msg: SDKMessage): string | null;
+
+/**
+ * Chucky Client
+ *
+ * Main entry point for the Chucky SDK.
+ * Provides methods to create sessions and execute prompts.
+ * Matches the official Claude Agent SDK V2 interface.
+ */
+
+/**
+ * Chucky client for interacting with the sandbox service
+ *
+ * Matches the official Claude Agent SDK V2 interface.
+ *
+ * @example
+ * ```typescript
+ * import { ChuckyClient } from '@chucky.cloud/sdk';
+ *
+ * const client = new ChuckyClient({
+ *   token: 'your-jwt-token',
+ * });
+ *
+ * // Create a session (V2 style)
+ * const session = client.createSession({
+ *   model: 'claude-sonnet-4-5-20250929',
+ *   systemPrompt: 'You are a helpful assistant.',
+ * });
+ *
+ * // Send messages and stream responses
+ * await session.send('Hello, world!');
+ * for await (const msg of session.stream()) {
+ *   if (msg.type === 'assistant') {
+ *     const text = getAssistantText(msg);
+ *     console.log(text);
+ *   }
+ *   if (msg.type === 'result') {
+ *     console.log('Done:', msg);
+ *   }
+ * }
+ *
+ * session.close();
+ * ```
+ */
+declare class ChuckyClient {
+    private readonly options;
+    private eventHandlers;
+    private activeSessions;
+    /**
+     * Create a new Chucky client
+     */
+    constructor(options: ClientOptions);
+    /**
+     * Set event handlers
+     */
+    on(handlers: ClientEventHandlers): this;
+    /**
+     * Create a new session
+     *
+     * Matches V2 SDK: createSession() returns a Session immediately.
+     * Connection happens automatically on first send().
+     *
+     * @param options - Session configuration options
+     * @returns A new session instance
+     *
+     * @example
+     * ```typescript
+     * const session = client.createSession({
+     *   model: 'claude-sonnet-4-5-20250929',
+     *   systemPrompt: 'You are a helpful coding assistant.',
+     * });
+     *
+     * await session.send('Hello!');
+     * for await (const msg of session.stream()) {
+     *   // Handle messages
+     * }
+     * ```
+     */
+    createSession(options?: SessionOptions): Session;
+    /**
+     * Resume an existing session
+     *
+     * @param sessionId - The session ID to resume
+     * @param options - Additional session options
+     * @returns The resumed session
+     *
+     * @example
+     * ```typescript
+     * const session = client.resumeSession('session-123');
+     * await session.send('Continue our conversation');
+     * ```
+     */
+    resumeSession(sessionId: string, options?: Omit<SessionOptions, 'sessionId'>): Session;
+    /**
+     * Execute a one-shot prompt (stateless)
+     *
+     * Supports two call signatures:
+     * - `prompt('message', { model: '...' })` - positional style
+     * - `prompt({ message: '...', model: '...' })` - object style
+     *
+     * @param messageOrOptions - The message string OR an options object with message
+     * @param options - Prompt configuration (only used with positional style)
+     * @returns The result message
+     *
+     * @example
+     * ```typescript
+     * // Positional style
+     * const result = await client.prompt(
+     *   'Explain quantum computing in simple terms',
+     *   { model: 'claude-sonnet-4-5-20250929' }
+     * );
+     *
+     * // Object style
+     * const result = await client.prompt({
+     *   message: 'Explain quantum computing in simple terms',
+     *   model: 'claude-sonnet-4-5-20250929',
+     * });
+     *
+     * if (result.subtype === 'success') {
+     *   console.log(result.result);
+     * }
+     * ```
+     */
+    prompt(messageOrOptions: string | PromptOptions, options?: SessionOptions): Promise<SDKResultMessage>;
+    /**
+     * Close all active sessions and disconnect
+     */
+    close(): void;
+    /**
+     * Create a new transport instance
+     */
+    private createTransport;
+}
+/**
+ * Create a Chucky client
+ *
+ * @param options - Client configuration
+ * @returns A new ChuckyClient instance
+ *
+ * @example
+ * ```typescript
+ * import { createClient } from '@chucky.cloud/sdk';
+ *
+ * const client = createClient({
+ *   token: 'your-jwt-token',
+ * });
+ * ```
+ */
+declare function createClient(options: ClientOptions): ChuckyClient;
+
+/**
+ * Tool Helper
+ *
+ * Helper functions for defining tools with type safety.
+ * Supports both JSON Schema and Zod for input validation.
+ */
+
+/**
+ * Options for creating a tool
+ */
+interface CreateToolOptions<TInput = Record<string, unknown>> {
+    /** Tool name (must be unique) */
+    name: string;
+    /** Human-readable description */
+    description: string;
+    /** Input schema (JSON Schema or Zod schema) */
+    inputSchema: ToolInputSchema | ZodLikeSchema;
+    /** Where to execute the tool */
+    executeIn?: ToolExecutionLocation;
+    /** Handler function */
+    handler?: ToolHandler<TInput>;
+}
+/**
+ * Zod-like schema interface for compatibility
+ */
+interface ZodLikeSchema {
+    _def?: unknown;
+    shape?: unknown;
+    safeParse?: (data: unknown) => {
+        success: boolean;
+        data?: unknown;
+        error?: unknown;
+    };
+}
+/**
+ * Create a tool definition
+ *
+ * @param options - Tool configuration
+ * @returns Tool definition ready to use
+ *
+ * @example
+ * ```typescript
+ * // With JSON Schema
+ * const weatherTool = createTool({
+ *   name: 'get_weather',
+ *   description: 'Get current weather for a city',
+ *   inputSchema: {
+ *     type: 'object',
+ *     properties: {
+ *       city: { type: 'string', description: 'City name' },
+ *       unit: { type: 'string', enum: ['celsius', 'fahrenheit'] },
+ *     },
+ *     required: ['city'],
+ *   },
+ *   handler: async ({ city, unit }) => ({
+ *     content: [{ type: 'text', text: `Weather in ${city}: Sunny, 72°${unit === 'celsius' ? 'C' : 'F'}` }],
  *   }),
  * });
  *
- * // Create client with the token
- * const client = new ChuckyClient({ token });
+ * // With Zod (optional peer dependency)
+ * import { z } from 'zod';
  *
- * // Create a session with tools
- * const session = await client.createSession({
- *   model: 'claude-sonnet-4-5-20250929',
- *   tools: [
- *     tool('greet', 'Greet someone', {
+ * const calculatorTool = createTool({
+ *   name: 'calculate',
+ *   description: 'Perform a calculation',
+ *   inputSchema: z.object({
+ *     expression: z.string().describe('Math expression to evaluate'),
+ *   }),
+ *   handler: async ({ expression }) => ({
+ *     content: [{ type: 'text', text: `Result: ${eval(expression)}` }],
+ *   }),
+ * });
+ * ```
+ */
+declare function createTool<TInput = Record<string, unknown>>(options: CreateToolOptions<TInput>): ToolDefinition<TInput>;
+/**
+ * Shorthand for creating a tool
+ *
+ * @param name - Tool name
+ * @param description - Tool description
+ * @param inputSchema - Input schema
+ * @param handler - Handler function
+ * @returns Tool definition
+ *
+ * @example
+ * ```typescript
+ * const greetTool = tool(
+ *   'greet',
+ *   'Greet a person by name',
+ *   {
+ *     type: 'object',
+ *     properties: { name: { type: 'string' } },
+ *     required: ['name'],
+ *   },
+ *   async ({ name }) => ({
+ *     content: [{ type: 'text', text: `Hello, ${name}!` }],
+ *   })
+ * );
+ * ```
+ */
+declare function tool<TInput = Record<string, unknown>>(name: string, description: string, inputSchema: ToolInputSchema | ZodLikeSchema, handler?: ToolHandler<TInput>): ToolDefinition<TInput>;
+/**
+ * Create a browser-executed tool
+ *
+ * @param options - Tool configuration
+ * @returns Tool definition that executes in the browser
+ *
+ * @example
+ * ```typescript
+ * const alertTool = browserTool({
+ *   name: 'show_alert',
+ *   description: 'Show an alert dialog',
+ *   inputSchema: {
+ *     type: 'object',
+ *     properties: { message: { type: 'string' } },
+ *     required: ['message'],
+ *   },
+ *   handler: async ({ message }) => {
+ *     alert(message);
+ *     return { content: [{ type: 'text', text: 'Alert shown' }] };
+ *   },
+ * });
+ * ```
+ */
+declare function browserTool<TInput = Record<string, unknown>>(options: Omit<CreateToolOptions<TInput>, 'executeIn'>): ToolDefinition<TInput>;
+/**
+ * Create a server-executed tool
+ *
+ * @param options - Tool configuration (handler is optional for server tools)
+ * @returns Tool definition that executes on the server
+ */
+declare function serverTool<TInput = Record<string, unknown>>(options: Omit<CreateToolOptions<TInput>, 'executeIn' | 'handler'>): ToolDefinition<TInput>;
+/**
+ * Helper to create text content for tool results
+ */
+declare function textResult(text: string): ToolResult;
+/**
+ * Helper to create error result for tools
+ */
+declare function errorResult(message: string): ToolResult;
+/**
+ * Helper to create image content for tool results
+ */
+declare function imageResult(data: string, mimeType: string): ToolResult;
+
+/**
+ * MCP Server Builder
+ *
+ * Builder pattern for creating MCP server definitions with multiple tools.
+ */
+
+/**
+ * MCP Server builder for creating server definitions
+ *
+ * @example
+ * ```typescript
+ * const myServer = new McpServerBuilder('my-tools', '1.0.0')
+ *   .addTool({
+ *     name: 'greet',
+ *     description: 'Greet someone',
+ *     inputSchema: {
  *       type: 'object',
  *       properties: { name: { type: 'string' } },
  *       required: ['name'],
- *     }, async ({ name }) => ({
+ *     },
+ *     handler: async ({ name }) => ({
  *       content: [{ type: 'text', text: `Hello, ${name}!` }],
- *     })),
- *   ],
+ *     }),
+ *   })
+ *   .addTool({
+ *     name: 'farewell',
+ *     description: 'Say goodbye',
+ *     inputSchema: {
+ *       type: 'object',
+ *       properties: { name: { type: 'string' } },
+ *       required: ['name'],
+ *     },
+ *     handler: async ({ name }) => ({
+ *       content: [{ type: 'text', text: `Goodbye, ${name}!` }],
+ *     }),
+ *   })
+ *   .build();
+ * ```
+ */
+declare class McpServerBuilder {
+    private name;
+    private version;
+    private tools;
+    /**
+     * Create a new MCP server builder
+     *
+     * @param name - Server name
+     * @param version - Server version (default: '1.0.0')
+     */
+    constructor(name: string, version?: string);
+    /**
+     * Add a tool to the server
+     *
+     * @param options - Tool configuration
+     * @returns This builder for chaining
+     */
+    addTool<TInput = Record<string, unknown>>(options: CreateToolOptions<TInput>): this;
+    /**
+     * Add an existing tool definition
+     *
+     * @param tool - Tool definition
+     * @returns This builder for chaining
+     */
+    add(tool: ToolDefinition): this;
+    /**
+     * Add multiple tools at once
+     *
+     * @param tools - Array of tool definitions
+     * @returns This builder for chaining
+     */
+    addTools(tools: ToolDefinition[]): this;
+    /**
+     * Build the MCP server definition
+     *
+     * @returns Complete MCP server definition
+     */
+    build(): McpServerDefinition;
+}
+/**
+ * Create an MCP server definition
+ *
+ * @param name - Server name
+ * @param tools - Array of tool definitions
+ * @param version - Server version
+ * @returns MCP server definition
+ *
+ * @example
+ * ```typescript
+ * const server = createMcpServer('my-server', [
+ *   tool('greet', 'Greet someone', { type: 'object', properties: { name: { type: 'string' } } }),
+ *   tool('farewell', 'Say goodbye', { type: 'object', properties: { name: { type: 'string' } } }),
+ * ]);
+ * ```
+ */
+declare function createMcpServer(name: string, tools: ToolDefinition[], version?: string): McpServerDefinition;
+/**
+ * Create an MCP server using the builder pattern
+ *
+ * @param name - Server name
+ * @param version - Server version
+ * @returns MCP server builder
+ *
+ * @example
+ * ```typescript
+ * const server = mcpServer('my-tools')
+ *   .addTool({
+ *     name: 'hello',
+ *     description: 'Say hello',
+ *     inputSchema: { type: 'object', properties: {} },
+ *     handler: async () => ({ content: [{ type: 'text', text: 'Hello!' }] }),
+ *   })
+ *   .build();
+ * ```
+ */
+declare function mcpServer(name: string, version?: string): McpServerBuilder;
+
+/**
+ * Budget Token Types
+ *
+ * Types for JWT tokens used for authentication and budget control.
+ */
+/**
+ * Budget window types
+ */
+type BudgetWindow = 'hour' | 'day' | 'week' | 'month';
+/**
+ * Budget configuration in a token
+ */
+interface TokenBudget {
+    /** AI budget in microdollars (1 USD = 1,000,000 microdollars) */
+    ai: number;
+    /** Compute budget in seconds */
+    compute: number;
+    /** Budget window period */
+    window: BudgetWindow;
+    /** When current period started (ISO 8601) */
+    windowStart: string;
+}
+/**
+ * Permission configuration in a token
+ */
+interface TokenPermissions {
+    /** Allowed tool names */
+    tools?: string[];
+    /** Blocked tool names */
+    blockedTools?: string[];
+    /** Maximum turns per conversation */
+    maxTurns?: number;
+    /** Model restriction */
+    model?: string;
+}
+/**
+ * SDK configuration overrides in a token
+ * When present, these values SUPERSEDE options provided by the SDK client
+ */
+interface TokenSdkConfig {
+    /** Model to use */
+    model?: string;
+    /** System prompt */
+    systemPrompt?: string;
+    /** Tools configuration */
+    tools?: unknown;
+    /** Allowed tools */
+    allowedTools?: string[];
+    /** Disallowed tools */
+    disallowedTools?: string[];
+    /** Maximum turns */
+    maxTurns?: number;
+    /** Maximum budget in USD */
+    maxBudgetUsd?: number;
+    /** Maximum thinking tokens */
+    maxThinkingTokens?: number;
+    /** Permission mode */
+    permissionMode?: string;
+    /** Allow dangerous skip permissions */
+    allowDangerouslySkipPermissions?: boolean;
+    /** MCP servers configuration */
+    mcpServers?: unknown[];
+    /** Agents configuration */
+    agents?: unknown;
+    /** Betas configuration */
+    betas?: string[];
+    /** Output format */
+    outputFormat?: string;
+    /** Environment variables */
+    env?: Record<string, string>;
+}
+/**
+ * Budget token payload (JWT claims)
+ */
+interface BudgetTokenPayload {
+    /** User ID - unique identifier for the end user */
+    sub: string;
+    /** Project/Issuer ID - identifies which project */
+    iss: string;
+    /** Token expiry timestamp (Unix seconds) */
+    exp: number;
+    /** Issued at timestamp (Unix seconds) */
+    iat?: number;
+    /** Budget declaration */
+    budget: TokenBudget;
+    /** Permission configuration (optional) */
+    permissions?: TokenPermissions;
+    /** SDK config overrides (optional) */
+    sdkConfig?: TokenSdkConfig;
+}
+/**
+ * Options for creating a budget token
+ */
+interface CreateTokenOptions {
+    /** User ID */
+    userId: string;
+    /** Project/Issuer ID (UUID) */
+    projectId: string;
+    /** HMAC secret key for signing */
+    secret: string;
+    /** Token expiry duration in seconds (default: 3600 = 1 hour) */
+    expiresIn?: number;
+    /** Budget configuration */
+    budget: TokenBudget;
+    /** Permission configuration */
+    permissions?: TokenPermissions;
+    /** SDK config overrides */
+    sdkConfig?: TokenSdkConfig;
+}
+/**
+ * Decoded token result
+ */
+interface DecodedToken {
+    /** Token header */
+    header: {
+        alg: string;
+        typ: string;
+    };
+    /** Token payload */
+    payload: BudgetTokenPayload;
+    /** Token signature (base64url) */
+    signature: string;
+}
+
+/**
+ * Token Utilities
+ *
+ * Helpers for creating and decoding JWT tokens for authentication.
+ * These are primarily for server-side use (Node.js).
+ */
+
+/**
+ * Create a budget token (JWT) for authenticating with Chucky
+ *
+ * @param options - Token creation options
+ * @returns Signed JWT token
+ *
+ * @example
+ * ```typescript
+ * // Server-side token creation
+ * const token = await createToken({
+ *   userId: 'user-123',
+ *   projectId: '550e8400-e29b-41d4-a716-446655440000',
+ *   secret: 'your-hmac-secret',
+ *   budget: {
+ *     ai: 1_000_000, // $1 in microdollars
+ *     compute: 3600,  // 1 hour
+ *     window: 'day',
+ *     windowStart: new Date().toISOString(),
+ *   },
  * });
+ * ```
+ */
+declare function createToken(options: CreateTokenOptions): Promise<string>;
+/**
+ * Decode a token without verification
  *
- * // Send a message
- * const result = await session.send('Greet the world!');
- * console.log(result.text);
+ * @param token - JWT token to decode
+ * @returns Decoded token parts
  *
- * // Or stream the response
- * for await (const event of session.sendStream('Tell me a story')) {
- *   if (event.type === 'text') {
- *     process.stdout.write(event.text);
- *   }
+ * @example
+ * ```typescript
+ * const decoded = decodeToken(token);
+ * console.log(decoded.payload.sub); // User ID
+ * console.log(decoded.payload.budget); // Budget limits
+ * ```
+ */
+declare function decodeToken(token: string): DecodedToken;
+/**
+ * Verify a token signature
+ *
+ * @param token - JWT token to verify
+ * @param secret - HMAC secret for verification
+ * @returns True if signature is valid
+ *
+ * @example
+ * ```typescript
+ * const isValid = await verifyToken(token, 'your-hmac-secret');
+ * if (!isValid) {
+ *   throw new Error('Invalid token');
  * }
  * ```
+ */
+declare function verifyToken(token: string, secret: string): Promise<boolean>;
+/**
+ * Check if a token is expired
+ *
+ * @param token - JWT token to check
+ * @returns True if token is expired
+ */
+declare function isTokenExpired(token: string): boolean;
+/**
+ * @deprecated The project ID is now separate from the HMAC key for security reasons.
+ * Get your project ID from the Chucky portal (app.chucky.cloud) instead.
+ *
+ * Previously, the HMAC key embedded the project ID, but this exposed the secret
+ * in JWT tokens. Project IDs are now Convex document IDs visible in the portal.
+ *
+ * @param _hmacKey - Ignored (previously used to extract project ID)
+ * @throws Always throws an error directing users to get project ID from portal
+ */
+declare function extractProjectId(_hmacKey: string): never;
+/**
+ * Create a simple budget configuration
+ *
+ * @param options - Budget options
+ * @returns Budget configuration
+ *
+ * @example
+ * ```typescript
+ * const budget = createBudget({
+ *   aiDollars: 1.00,    // $1 AI budget
+ *   computeHours: 1,    // 1 hour compute
+ *   window: 'day',
+ * });
+ * ```
+ */
+declare function createBudget(options: {
+    /** AI budget in dollars */
+    aiDollars: number;
+    /** Compute budget in hours */
+    computeHours: number;
+    /** Budget window */
+    window: 'hour' | 'day' | 'week' | 'month';
+    /** Window start (default: now) */
+    windowStart?: Date;
+}): TokenBudget;
+
+/**
+ * Error Classes
  *
- * @packageDocumentation
- */
-export { ChuckyClient, createClient, getAssistantText, getResultText } from './client/index.js';
-export { Session } from './client/index.js';
-export type { SessionEventHandlers } from './client/index.js';
-export { createTool, tool, browserTool, serverTool, textResult, errorResult, imageResult, McpServerBuilder, createMcpServer, mcpServer, } from './tools/index.js';
-export type { CreateToolOptions } from './tools/index.js';
-export { createToken, decodeToken, verifyToken, isTokenExpired, extractProjectId, createBudget, } from './utils/index.js';
-export { ChuckyError, ConnectionError, AuthenticationError, BudgetExceededError, ConcurrencyLimitError, RateLimitError, SessionError, ToolExecutionError, TimeoutError, ValidationError, createError, } from './utils/index.js';
-export { WebSocketTransport } from './transport/index.js';
-export type { Transport, TransportConfig, TransportEvents } from './transport/index.js';
-export type { Model, SystemPrompt, OutputFormat, AgentDefinition, BaseOptions, SessionOptions, PromptOptions, ClientOptions, ConnectionStatus, ClientEventHandlers, } from './types/index.js';
-export type { JsonSchemaType, JsonSchemaProperty, ToolInputSchema, ToolContentType, ToolTextContent, ToolImageContent, ResourceContent, ToolContent, ToolResult, ToolExecutionLocation, ToolHandler, ToolDefinition, McpServerDefinition, ToolCall, ToolCallResponse, } from './types/index.js';
-export type { UUID, SDKTextContent, SDKImageContent, ToolUseContent, ToolResultContent, SDKContentBlock, APIUserMessage, APIAssistantMessage, SDKUserMessage, SDKAssistantMessage, SDKResultMessage, SDKResultMessageSuccess, SDKResultMessageError, ResultSubtype, SDKSystemMessage, SDKSystemMessageInit, SDKSystemMessageCompact, SystemSubtype, SDKPartialAssistantMessage, SDKMessage, WsEnvelopeType, InitPayload, ControlAction, ControlPayload, ErrorPayload, OutgoingMessage, IncomingMessage, } from './types/index.js';
-export type { BudgetWindow, TokenBudget, TokenPermissions, TokenSdkConfig, BudgetTokenPayload, CreateTokenOptions, DecodedToken, } from './types/index.js';
-export type { MessageRole, ContentBlockType, TextBlock, ToolUseBlock, ToolResultBlock, ThinkingBlock, ImageBlock, Message, Usage, CostBreakdown, SessionResult, PromptResult, StreamEvent, PartialMessage, SessionState, SessionInfo, } from './types/index.js';
-export { createInitMessage, createUserMessage, createControlMessage, createPingMessage, createToolResultMessage, isUserMessage, isAssistantMessage, isResultMessage, isSuccessResult, isErrorResult, isSystemMessage, isStreamEvent, isToolCallMessage, isControlMessage, isErrorMessage, } from './types/index.js';
-//# sourceMappingURL=index.d.ts.map
+ * Custom error types for the Chucky SDK.
+ */
+/**
+ * Base error class for Chucky SDK errors
+ */
+declare class ChuckyError extends Error {
+    /** Error code */
+    readonly code: string;
+    /** Additional error details */
+    readonly details?: Record<string, unknown>;
+    constructor(message: string, code: string, details?: Record<string, unknown>);
+}
+/**
+ * Connection error
+ */
+declare class ConnectionError extends ChuckyError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+/**
+ * Authentication error
+ */
+declare class AuthenticationError extends ChuckyError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+/**
+ * Budget exceeded error
+ */
+declare class BudgetExceededError extends ChuckyError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+/**
+ * Concurrency limit error
+ */
+declare class ConcurrencyLimitError extends ChuckyError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+/**
+ * Rate limit error
+ */
+declare class RateLimitError extends ChuckyError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+/**
+ * Session error
+ */
+declare class SessionError extends ChuckyError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+/**
+ * Tool execution error
+ */
+declare class ToolExecutionError extends ChuckyError {
+    /** Tool name */
+    readonly toolName: string;
+    constructor(message: string, toolName: string, details?: Record<string, unknown>);
+}
+/**
+ * Timeout error
+ */
+declare class TimeoutError extends ChuckyError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+/**
+ * Validation error
+ */
+declare class ValidationError extends ChuckyError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+/**
+ * Create appropriate error from message and optional code
+ */
+declare function createError(message: string, code?: string): ChuckyError;
+
+/**
+ * WebSocket Transport
+ *
+ * WebSocket-based transport that works in both browser and Node.js.
+ * Handles connection management, keep-alive, and reconnection.
+ */
+
+/**
+ * WebSocket transport configuration
+ */
+interface WebSocketTransportConfig extends TransportConfig {
+    /** Protocol to use (default: determined from URL) */
+    protocol?: 'ws' | 'wss';
+}
+/**
+ * WebSocket transport implementation
+ */
+declare class WebSocketTransport extends BaseTransport {
+    private ws;
+    private keepAliveTimer;
+    private reconnectAttempts;
+    private reconnectTimer;
+    private readyPromise;
+    private readyResolve;
+    private readyReject;
+    private messageQueue;
+    constructor(config: WebSocketTransportConfig);
+    /**
+     * Build the WebSocket URL with token
+     */
+    private buildUrl;
+    /**
+     * Connect to the WebSocket server
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from the server
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Send a message to the server
+     */
+    send(message: OutgoingMessage): Promise<void>;
+    /**
+     * Send a message immediately
+     */
+    private sendImmediate;
+    /**
+     * Wait for the connection to be ready
+     */
+    waitForReady(): Promise<void>;
+    /**
+     * Handle incoming message
+     */
+    private handleMessage;
+    /**
+     * Start keep-alive ping
+     */
+    private startKeepAlive;
+    /**
+     * Stop keep-alive ping
+     */
+    private stopKeepAlive;
+    /**
+     * Schedule a reconnection attempt
+     */
+    private scheduleReconnect;
+    /**
+     * Clear reconnect timer
+     */
+    private clearReconnectTimer;
+    /**
+     * Flush queued messages
+     */
+    private flushMessageQueue;
+}
+
+export { type APIAssistantMessage, type APIUserMessage, type AgentDefinition, AuthenticationError, type BaseOptions, BudgetExceededError, type BudgetTokenPayload, type BudgetWindow, ChuckyClient, ChuckyError, type ClientEventHandlers, type ClientOptions, ConcurrencyLimitError, ConnectionError, type ConnectionStatus, type ContentBlockType, type ControlAction, type ControlPayload, type CostBreakdown, type CreateTokenOptions, type CreateToolOptions, type DecodedToken, type ErrorPayload, type ImageBlock, type IncomingMessage, type InitPayload, type JsonSchemaProperty, type JsonSchemaType, McpServerBuilder, type McpServerDefinition, type Message, type MessageRole, type Model, type OutgoingMessage, type OutputFormat, type PartialMessage, type PromptOptions, type PromptResult, RateLimitError, type ResourceContent, type ResultSubtype, type SDKAssistantMessage, type ContentBlock$1 as SDKContentBlock, type ImageContent as SDKImageContent, type SDKMessage, type SDKPartialAssistantMessage, type SDKResultMessage, type SDKResultMessageError, type SDKResultMessageSuccess, type SDKSystemMessage, type SDKSystemMessageCompact, type SDKSystemMessageInit, type TextContent as SDKTextContent, type SDKUserMessage, Session, SessionError, type SessionEventHandlers, type SessionInfo, type SessionOptions, type SessionResult, type SessionState, type StreamEvent, type SystemPrompt, type SystemSubtype, type TextBlock, type ThinkingBlock, TimeoutError, type TokenBudget, type TokenPermissions, type TokenSdkConfig, type ToolCall, type ToolCallResponse, type ToolContent, type ToolContentType, type ToolDefinition, ToolExecutionError, type ToolExecutionLocation, type ToolHandler, type ToolImageContent, type ToolInputSchema, type ToolResult, type ToolResultBlock, type ToolResultContent, type ToolTextContent, type ToolUseBlock, type ToolUseContent, type Transport, type TransportConfig, type TransportEvents, type UUID, type Usage, ValidationError, WebSocketTransport, type WsEnvelopeType, browserTool, createBudget, createClient, createControlMessage, createError, createInitMessage, createMcpServer, createPingMessage, createToken, createTool, createToolResultMessage, createUserMessage, decodeToken, errorResult, extractProjectId, getAssistantText, getResultText, imageResult, isAssistantMessage, isControlMessage, isErrorMessage, isErrorResult, isResultMessage, isStreamEvent, isSuccessResult, isSystemMessage, isTokenExpired, isToolCallMessage, isUserMessage, mcpServer, serverTool, textResult, tool, verifyToken };