@yourgpt/copilot-sdk 0.1.0

package/dist/thread-C2FjuGLb.d.cts

@@ -0,0 +1,1225 @@
+/**
+ * Tool types for App Context Awareness
+ */
+interface ScreenshotOptions {
+    /** Target element to capture (defaults to document.body) */
+    element?: HTMLElement;
+    /** Image quality (0.1-1.0, default 0.8) */
+    quality?: number;
+    /** Image format */
+    format?: "png" | "jpeg" | "webp";
+    /** Max width to scale down to */
+    maxWidth?: number;
+    /** Max height to scale down to */
+    maxHeight?: number;
+    /** Whether to include cursor */
+    includeCursor?: boolean;
+}
+interface ScreenshotResult {
+    /** Base64-encoded image data */
+    data: string;
+    /** Image format */
+    format: "png" | "jpeg" | "webp";
+    /** Image width */
+    width: number;
+    /** Image height */
+    height: number;
+    /** Timestamp of capture */
+    timestamp: number;
+}
+type ConsoleLogType = "log" | "info" | "warn" | "error" | "debug";
+interface ConsoleLogEntry {
+    /** Type of console method */
+    type: ConsoleLogType;
+    /** Log message(s) */
+    message: string;
+    /** Additional arguments passed to console */
+    args?: unknown[];
+    /** Stack trace (for errors) */
+    stack?: string;
+    /** Timestamp */
+    timestamp: number;
+}
+interface ConsoleLogOptions {
+    /** Types of logs to capture */
+    types?: ConsoleLogType[];
+    /** Maximum number of logs to store */
+    limit?: number;
+    /** Filter function */
+    filter?: (entry: ConsoleLogEntry) => boolean;
+}
+interface ConsoleLogResult {
+    /** Captured log entries */
+    logs: ConsoleLogEntry[];
+    /** Total logs captured (before limit) */
+    totalCaptured: number;
+}
+type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
+interface NetworkRequestEntry {
+    /** Request URL */
+    url: string;
+    /** HTTP method */
+    method: HttpMethod;
+    /** Response status code */
+    status: number;
+    /** Status text */
+    statusText: string;
+    /** Whether request failed (non-2xx or error) */
+    failed: boolean;
+    /** Request headers (sanitized) */
+    requestHeaders?: Record<string, string>;
+    /** Response headers (sanitized) */
+    responseHeaders?: Record<string, string>;
+    /** Request body (if captured) */
+    requestBody?: unknown;
+    /** Response body (if captured and failed) */
+    responseBody?: unknown;
+    /** Request duration in ms */
+    duration: number;
+    /** Timestamp of request start */
+    timestamp: number;
+    /** Error message if request failed */
+    error?: string;
+}
+interface NetworkRequestOptions {
+    /** Maximum number of requests to store */
+    limit?: number;
+    /** Only capture failed requests (default: true) */
+    failedOnly?: boolean;
+    /** HTTP methods to capture */
+    methods?: HttpMethod[];
+    /** URL patterns to include (regex) */
+    includeUrls?: RegExp[];
+    /** URL patterns to exclude (regex) */
+    excludeUrls?: RegExp[];
+    /** Whether to capture request body */
+    captureRequestBody?: boolean;
+    /** Whether to capture response body */
+    captureResponseBody?: boolean;
+    /** Max body size to capture (bytes) */
+    maxBodySize?: number;
+}
+interface NetworkRequestResult {
+    /** Captured network requests */
+    requests: NetworkRequestEntry[];
+    /** Total requests captured (before limit) */
+    totalCaptured: number;
+}
+type ToolType = "screenshot" | "console" | "network";
+interface IntentDetectionResult {
+    /** Detected tools that might be helpful */
+    suggestedTools: ToolType[];
+    /** Confidence score (0-1) for each tool */
+    confidence: Record<ToolType, number>;
+    /** Keywords that triggered detection */
+    matchedKeywords: Record<ToolType, string[]>;
+}
+interface ToolsConfig {
+    /** Enable screenshot capture */
+    screenshot?: boolean;
+    /** Enable console log capture */
+    console?: boolean;
+    /** Enable network request capture */
+    network?: boolean;
+    /** Always require user consent before capturing (default: true) */
+    requireConsent?: boolean;
+    /** Screenshot-specific options */
+    screenshotOptions?: ScreenshotOptions;
+    /** Console-specific options */
+    consoleOptions?: ConsoleLogOptions;
+    /** Network-specific options */
+    networkOptions?: NetworkRequestOptions;
+}
+interface ToolConsentRequest {
+    /** Tools being requested */
+    tools: ToolType[];
+    /** Reason for request (from intent detection) */
+    reason: string;
+    /** Keywords that triggered this request */
+    keywords: string[];
+}
+interface ToolConsentResponse {
+    /** Tools user approved */
+    approved: ToolType[];
+    /** Tools user denied */
+    denied: ToolType[];
+    /** Remember preference for session */
+    remember?: boolean;
+}
+interface CapturedContext {
+    /** Screenshot data (if captured) */
+    screenshot?: ScreenshotResult;
+    /** Console logs (if captured) */
+    consoleLogs?: ConsoleLogResult;
+    /** Network requests (if captured) */
+    networkRequests?: NetworkRequestResult;
+    /** Timestamp of capture */
+    timestamp: number;
+}
+
+/**
+ * Intent Detector
+ *
+ * Detects user intent from messages to suggest relevant tools.
+ * Framework-agnostic implementation using keyword matching.
+ */
+
+/**
+ * Detect user intent from a message
+ *
+ * @param message - User message to analyze
+ * @returns Detection result with suggested tools
+ *
+ * @example
+ * ```typescript
+ * const result = detectIntent("I'm seeing an error on my screen");
+ * // Returns:
+ * // {
+ * //   suggestedTools: ['screenshot', 'console'],
+ * //   confidence: { screenshot: 0.6, console: 0.8, network: 0 },
+ * //   matchedKeywords: { screenshot: ['seeing', 'screen'], console: ['error'] }
+ * // }
+ * ```
+ */
+declare function detectIntent(message: string): IntentDetectionResult;
+/**
+ * Check if a message suggests any tools
+ */
+declare function hasToolSuggestions(message: string): boolean;
+/**
+ * Get the primary suggested tool (highest confidence)
+ */
+declare function getPrimaryTool(message: string): ToolType | null;
+/**
+ * Generate a reason string for why tools are being suggested
+ */
+declare function generateSuggestionReason(result: IntentDetectionResult): string;
+/**
+ * Custom keyword configuration
+ */
+interface CustomKeywords {
+    screenshot?: string[];
+    console?: string[];
+    network?: string[];
+}
+/**
+ * Create a custom intent detector with additional keywords
+ */
+declare function createCustomDetector(customKeywords: CustomKeywords): (message: string) => IntentDetectionResult;
+
+/**
+ * Tool-related types for the agentic loop
+ */
+/**
+ * Supported AI providers for tool calling
+ */
+type AIProvider = "anthropic" | "openai" | "xai" | "grok" | "gemini" | "groq" | "ollama";
+/**
+ * Where the tool executes
+ */
+type ToolLocation = "server" | "client";
+/**
+ * JSON Schema property definition
+ */
+interface JSONSchemaProperty {
+    type: "string" | "number" | "boolean" | "object" | "array" | "integer" | "null";
+    description?: string;
+    enum?: (string | number | boolean)[];
+    items?: JSONSchemaProperty;
+    properties?: Record<string, JSONSchemaProperty>;
+    required?: string[];
+    default?: unknown;
+    minLength?: number;
+    maxLength?: number;
+    minimum?: number;
+    maximum?: number;
+    pattern?: string;
+}
+/**
+ * JSON Schema for tool input
+ */
+interface ToolInputSchema {
+    type: "object";
+    properties: Record<string, JSONSchemaProperty>;
+    required?: string[];
+    additionalProperties?: boolean;
+}
+/**
+ * Tool execution context
+ *
+ * Provides runtime information to tool handlers including cancellation signals,
+ * request metadata, and custom context data.
+ */
+interface ToolContext {
+    /** Abort signal for cancellation */
+    signal?: AbortSignal;
+    /** Thread ID if using threads */
+    threadId?: string;
+    /** Custom context data passed from runtime config */
+    data?: Record<string, unknown>;
+    /**
+     * Unique ID for this specific tool call.
+     * Useful for logging, tracing, and correlating tool executions.
+     */
+    toolCallId?: string;
+    /**
+     * Request headers (for auth in server tools).
+     * Contains headers from the original HTTP request.
+     *
+     * @example
+     * ```typescript
+     * handler: async (params, context) => {
+     *   const token = context?.headers?.authorization;
+     *   if (!token) return failure('Authentication required');
+     *   // ...
+     * }
+     * ```
+     */
+    headers?: Record<string, string>;
+    /**
+     * Full request metadata for server-side tools.
+     * Provides access to HTTP method, URL, and headers.
+     *
+     * @example
+     * ```typescript
+     * handler: async (params, context) => {
+     *   console.log(`Tool called from: ${context?.request?.url}`);
+     *   // Forward auth to internal service
+     *   const authHeader = context?.request?.headers?.authorization;
+     * }
+     * ```
+     */
+    request?: {
+        /** HTTP method (GET, POST, etc.) */
+        method?: string;
+        /** Request URL path */
+        url?: string;
+        /** Request headers */
+        headers?: Record<string, string>;
+    };
+}
+/**
+ * AI response behavior for tool results.
+ *
+ * Controls what the AI sees after a tool executes and renders UI.
+ *
+ * - `'none'`: AI generates minimal response, UI component handles display
+ * - `'brief'`: AI gets summary context (via aiContext), gives brief acknowledgment
+ * - `'full'`: AI receives full data and responds accordingly (default)
+ */
+type AIResponseMode = "none" | "brief" | "full";
+/**
+ * Multimodal content for AI to analyze
+ */
+type AIContent = {
+    type: "image";
+    data: string;
+    mediaType: string;
+} | {
+    type: "text";
+    text: string;
+};
+/**
+ * Tool response format
+ */
+interface ToolResponse<T = unknown> {
+    /** Whether the tool succeeded */
+    success: boolean;
+    /** Human-readable message */
+    message?: string;
+    /** Error message if failed */
+    error?: string;
+    /** Result data */
+    data?: T;
+    /**
+     * Override AI context for this specific result.
+     * Takes precedence over tool-level aiContext config.
+     * If set, this message is sent to AI instead of full result data.
+     *
+     * @example
+     * ```typescript
+     * return {
+     *   success: true,
+     *   data: sensitiveData,
+     *   _aiContext: '[Data retrieved - contains sensitive info, displayed to user]'
+     * };
+     * ```
+     */
+    _aiContext?: string;
+    /**
+     * Override AI response mode for this specific result.
+     * Takes precedence over tool-level aiResponseMode config.
+     */
+    _aiResponseMode?: AIResponseMode;
+    /**
+     * Content for AI to analyze (images, documents, etc.).
+     * When present, these are included as multimodal content for AI analysis.
+     *
+     * @example
+     * ```typescript
+     * // Screenshot for AI to analyze
+     * return {
+     *   success: true,
+     *   message: 'Screenshot captured',
+     *   _aiContent: [{ type: 'image', data: base64, mediaType: 'image/png' }]
+     * };
+     * ```
+     */
+    _aiContent?: AIContent[];
+}
+/**
+ * Props passed to tool render function
+ */
+interface ToolRenderProps<TParams = Record<string, unknown>> {
+    /** Current execution status */
+    status: "pending" | "executing" | "completed" | "error";
+    /** Arguments passed to the tool */
+    args: TParams;
+    /** Result if completed */
+    result?: ToolResponse;
+    /** Error if failed */
+    error?: string;
+}
+/**
+ * Tool definition with JSON Schema
+ */
+interface ToolDefinition<TParams = Record<string, unknown>> {
+    /** Unique tool name */
+    name: string;
+    /** Tool description for LLM */
+    description: string;
+    /** Where the tool executes (server or client) */
+    location: ToolLocation;
+    /**
+     * Human-readable title for UI display.
+     * Can be a static string or a function that generates title from args.
+     *
+     * @example
+     * ```typescript
+     * title: "Get order details"
+     * // or dynamic:
+     * title: (args) => `Order #${args.orderId}`
+     * ```
+     */
+    title?: string | ((args: TParams) => string);
+    /**
+     * Title shown while executing (present tense with "...").
+     * If not provided, uses `title` with "..." appended.
+     *
+     * @example
+     * ```typescript
+     * executingTitle: (args) => `Fetching order #${args.orderId}...`
+     * ```
+     */
+    executingTitle?: string | ((args: TParams) => string);
+    /**
+     * Title shown after completion.
+     * If not provided, defaults to `title`.
+     *
+     * @example
+     * ```typescript
+     * completedTitle: (args) => `Retrieved order #${args.orderId}`
+     * ```
+     */
+    completedTitle?: string | ((args: TParams) => string);
+    /** JSON Schema for input parameters */
+    inputSchema: ToolInputSchema;
+    /** Handler function (optional for client tools registered on server) */
+    handler?: (params: TParams, context?: ToolContext) => Promise<ToolResponse> | ToolResponse;
+    /** Optional render function for UI */
+    render?: (props: ToolRenderProps<TParams>) => unknown;
+    /** Whether the tool is available (for conditional registration) */
+    available?: boolean;
+    /**
+     * Require user approval before execution.
+     * Can be:
+     * - `true`: Always require approval
+     * - `false` or `undefined`: No approval needed (default)
+     * - `(params) => boolean`: Conditional approval based on input
+     *
+     * Similar to Vercel AI SDK v6's needsApproval pattern.
+     */
+    needsApproval?: boolean | ((params: TParams) => boolean | Promise<boolean>);
+    /**
+     * Custom message shown in the approval UI.
+     * Can be a string or a function that generates a message from params.
+     * If not provided, a default message with the tool name is shown.
+     */
+    approvalMessage?: string | ((params: TParams) => string);
+    /**
+     * How the AI should respond when this tool's result is rendered as UI.
+     *
+     * - `'none'`: AI generates minimal response ("[Result displayed to user]").
+     *   Use for tools where UI component fully handles the display (stats cards, etc.)
+     *
+     * - `'brief'`: AI receives summary context (from aiContext) and gives brief acknowledgment.
+     *   Use for charts/visualizations where AI should acknowledge but not repeat data.
+     *
+     * - `'full'`: AI receives complete data and responds accordingly (default).
+     *   Use for tools where AI should analyze and elaborate on results.
+     *
+     * @default 'full'
+     *
+     * @example
+     * ```typescript
+     * // Chart tool - AI acknowledges without repeating data
+     * const chartTool: ToolDefinition = {
+     *   name: 'get_chart',
+     *   aiResponseMode: 'brief',
+     *   aiContext: (result) => `[Chart displayed: ${result.data.title}]`,
+     *   handler: async () => ({ success: true, data: chartData })
+     * };
+     * ```
+     */
+    aiResponseMode?: AIResponseMode;
+    /**
+     * Context/summary sent to AI instead of (or along with) full result.
+     *
+     * Used when:
+     * - `aiResponseMode: 'brief'` - This becomes the only thing AI sees
+     * - `aiResponseMode: 'full'` - This is prepended to full data for context
+     *
+     * Can be:
+     * - `string`: Static message (e.g., "[Weather data displayed]")
+     * - `function`: Dynamic based on result (e.g., (result) => `[Chart: ${result.data.title}]`)
+     *
+     * @example
+     * ```typescript
+     * // Static context
+     * aiContext: '[Analytics chart displayed to user]'
+     *
+     * // Dynamic context based on result
+     * aiContext: (result, args) => {
+     *   const { title, currentValue } = result.data;
+     *   return `[Chart displayed: ${title}, showing ${currentValue}]`;
+     * }
+     * ```
+     */
+    aiContext?: string | ((result: ToolResponse, args: Record<string, unknown>) => string);
+}
+/**
+ * Unified tool call format (internal representation)
+ */
+interface UnifiedToolCall {
+    /** Unique tool call ID */
+    id: string;
+    /** Tool name */
+    name: string;
+    /** Tool input arguments */
+    input: Record<string, unknown>;
+}
+/**
+ * Unified tool result format
+ */
+interface UnifiedToolResult {
+    /** Tool call ID this result is for */
+    toolCallId: string;
+    /** Serialized result content (JSON string) */
+    content: string;
+    /** Whether the tool succeeded */
+    success: boolean;
+    /** Error message if failed */
+    error?: string;
+}
+/**
+ * Tool execution status
+ */
+type ToolExecutionStatus = "pending" | "executing" | "completed" | "error";
+/**
+ * Tool approval status (for human-in-the-loop)
+ *
+ * Similar to Vercel AI SDK v6's tool approval pattern.
+ */
+type ToolApprovalStatus = "none" | "required" | "approved" | "rejected";
+/**
+ * Permission level for tool execution
+ *
+ * Controls whether approval is needed and how the choice is remembered:
+ * - "ask" - Always prompt user (default)
+ * - "allow_always" - Auto-approve, persisted to storage
+ * - "deny_always" - Auto-reject, persisted to storage
+ * - "session" - Auto-approve for current session only
+ */
+type PermissionLevel = "ask" | "allow_always" | "deny_always" | "session";
+/**
+ * Stored tool permission record
+ */
+interface ToolPermission {
+    /** Tool name (unique identifier) */
+    toolName: string;
+    /** Permission level */
+    level: PermissionLevel;
+    /** When permission was set */
+    createdAt: number;
+    /** Last time this permission was used */
+    lastUsedAt?: number;
+}
+/**
+ * Permission storage configuration
+ */
+interface PermissionStorageConfig {
+    /**
+     * Storage type:
+     * - "localStorage" - Persists across browser sessions
+     * - "sessionStorage" - Clears when tab closes
+     * - "memory" - In-memory only (for SSR or testing)
+     */
+    type: "localStorage" | "sessionStorage" | "memory";
+    /** Storage key prefix (default: "yourgpt-permissions") */
+    keyPrefix?: string;
+}
+/**
+ * Permission storage adapter interface (for custom implementations)
+ */
+interface PermissionStorageAdapter {
+    /** Get permission for a tool */
+    get(toolName: string): Promise<ToolPermission | null>;
+    /** Set permission for a tool */
+    set(permission: ToolPermission): Promise<void>;
+    /** Remove permission for a tool */
+    remove(toolName: string): Promise<void>;
+    /** Get all permissions */
+    getAll(): Promise<ToolPermission[]>;
+    /** Clear all permissions */
+    clear(): Promise<void>;
+}
+/**
+ * Tool execution record (for UI tracking)
+ */
+interface ToolExecution {
+    /** Tool call ID */
+    id: string;
+    /** Tool name */
+    name: string;
+    /** Tool arguments */
+    args: Record<string, unknown>;
+    /** Execution status */
+    status: ToolExecutionStatus;
+    /** Result if completed */
+    result?: ToolResponse;
+    /** Error message if failed */
+    error?: string;
+    /** Timestamp when execution started */
+    timestamp: number;
+    /** Duration in ms (set when completed) */
+    duration?: number;
+    /** Approval status for this execution */
+    approvalStatus: ToolApprovalStatus;
+    /** Message shown in approval UI (from tool's approvalMessage) */
+    approvalMessage?: string;
+    /** Timestamp when user responded to approval request */
+    approvalTimestamp?: number;
+}
+/**
+ * Agentic loop configuration
+ */
+interface AgentLoopConfig {
+    /** Maximum iterations before stopping (default: 20) */
+    maxIterations?: number;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Whether to enable the agentic loop (default: true) */
+    enabled?: boolean;
+}
+/**
+ * Agent loop state (for tracking)
+ */
+interface AgentLoopState {
+    /** Current iteration number */
+    iteration: number;
+    /** Maximum iterations allowed */
+    maxIterations: number;
+    /** Whether the loop is currently running */
+    running: boolean;
+    /** Whether max iterations was reached */
+    maxIterationsReached: boolean;
+    /** Whether the loop was aborted */
+    aborted: boolean;
+}
+/**
+ * A set of tools, keyed by tool name
+ *
+ * @example
+ * ```typescript
+ * const myTools: ToolSet = {
+ *   capture_screenshot: screenshotTool,
+ *   get_weather: weatherTool,
+ * };
+ * ```
+ */
+type ToolSet = Record<string, ToolDefinition>;
+/**
+ * Configuration for creating a tool
+ */
+interface ToolConfig<TParams = Record<string, unknown>> {
+    /** Tool description for LLM */
+    description: string;
+    /** Where the tool executes (default: 'client') */
+    location?: ToolLocation;
+    /** Human-readable title for UI display */
+    title?: string | ((args: TParams) => string);
+    /** Title shown while executing */
+    executingTitle?: string | ((args: TParams) => string);
+    /** Title shown after completion */
+    completedTitle?: string | ((args: TParams) => string);
+    /** JSON Schema for input parameters */
+    inputSchema?: ToolInputSchema;
+    /** Handler function */
+    handler?: (params: TParams, context?: ToolContext) => Promise<ToolResponse> | ToolResponse;
+    /** Optional render function for UI */
+    render?: (props: ToolRenderProps<TParams>) => unknown;
+    /** Whether the tool is available */
+    available?: boolean;
+    /** Require user approval before execution */
+    needsApproval?: boolean | ((params: TParams) => boolean | Promise<boolean>);
+    /** Custom message shown in the approval UI */
+    approvalMessage?: string | ((params: TParams) => string);
+    /** AI response mode for this tool (default: 'full') */
+    aiResponseMode?: AIResponseMode;
+    /** Context/summary sent to AI instead of full result */
+    aiContext?: string | ((result: ToolResponse, args: Record<string, unknown>) => string);
+}
+/**
+ * Create a tool definition (similar to Vercel AI SDK's tool())
+ *
+ * @example
+ * ```typescript
+ * const weatherTool = tool({
+ *   description: 'Get weather for a location',
+ *   inputSchema: {
+ *     type: 'object',
+ *     properties: {
+ *       location: { type: 'string', description: 'City name' },
+ *     },
+ *     required: ['location'],
+ *   },
+ *   handler: async ({ location }) => {
+ *     const weather = await fetchWeather(location);
+ *     return success(weather);
+ *   },
+ * });
+ * ```
+ */
+declare function tool<TParams = Record<string, unknown>>(config: ToolConfig<TParams>): Omit<ToolDefinition<TParams>, "name">;
+/**
+ * Convert ToolDefinition to OpenAI tool format
+ */
+declare function toolToOpenAIFormat(tool: ToolDefinition): object;
+/**
+ * Convert ToolDefinition to Anthropic tool format
+ */
+declare function toolToAnthropicFormat(tool: ToolDefinition): object;
+/**
+ * Create a tool result response
+ */
+declare function createToolResult(toolCallId: string, response: ToolResponse): UnifiedToolResult;
+/**
+ * Create a successful tool response
+ */
+declare function success<T = unknown>(data?: T, message?: string): ToolResponse<T>;
+/**
+ * Create a failed tool response
+ */
+declare function failure(error: string): ToolResponse;
+
+/**
+ * Message roles in a conversation (OpenAI format)
+ */
+type MessageRole = "user" | "assistant" | "system" | "tool";
+/**
+ * A source document from knowledge base
+ */
+interface Source {
+    /** Unique identifier */
+    id: string;
+    /** Source title or filename */
+    title: string;
+    /** Relevant content snippet */
+    content: string;
+    /** URL if available */
+    url?: string;
+    /** Relevance score (0-1) */
+    score?: number;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Tool/function call in OpenAI format
+ * Used in assistant messages when AI wants to call tools
+ */
+interface ToolCall {
+    /** Unique identifier for this call */
+    id: string;
+    /** Always "function" for OpenAI compatibility */
+    type: "function";
+    /** Function details */
+    function: {
+        /** Name of the function/tool */
+        name: string;
+        /** Arguments as JSON string (OpenAI format) */
+        arguments: string;
+    };
+}
+/**
+ * Attachment in a message (images, files, etc.)
+ *
+ * Attachments can be stored as:
+ * - Base64 data (free tier, embedded in message)
+ * - URL (premium cloud storage, lighter payload)
+ */
+interface MessageAttachment {
+    /** Type of attachment */
+    type: "image" | "file" | "audio" | "video";
+    /** Base64 data (for embedded attachments) */
+    data?: string;
+    /** URL for cloud-stored attachments (managed cloud storage) */
+    url?: string;
+    /** MIME type */
+    mimeType: string;
+    /** Optional filename */
+    filename?: string;
+}
+/**
+ * Token usage information
+ */
+interface TokenUsage {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens?: number;
+}
+/**
+ * Message metadata (flexible container for provider-specific data)
+ */
+interface MessageMetadata {
+    /** Extended thinking/reasoning (Claude, DeepSeek) */
+    thinking?: string;
+    /** Knowledge base sources */
+    sources?: Source[];
+    /** Attachments (images, files) */
+    attachments?: MessageAttachment[];
+    /** Model used to generate this message */
+    model?: string;
+    /** Token usage */
+    usage?: TokenUsage;
+    /** Any additional data */
+    [key: string]: unknown;
+}
+/**
+ * A message in the conversation (OpenAI format)
+ *
+ * This format is compatible with OpenAI's Chat Completions API
+ * and can be stored directly in a database (1 row per message).
+ *
+ * Message types:
+ * - user: User's input message
+ * - assistant: AI's response (may include tool_calls)
+ * - tool: Result of a tool execution (has tool_call_id)
+ * - system: System prompt (usually first message)
+ *
+ * @example
+ * // User message
+ * { role: "user", content: "What's the weather?" }
+ *
+ * // Assistant requesting tool
+ * { role: "assistant", content: null, tool_calls: [{...}] }
+ *
+ * // Tool result
+ * { role: "tool", content: '{"temp": 72}', tool_call_id: "call_abc" }
+ *
+ * // Final assistant response
+ * { role: "assistant", content: "The temperature is 72°F" }
+ */
+interface Message {
+    /** Unique identifier */
+    id: string;
+    /** Thread/conversation ID (for multi-session apps) */
+    thread_id?: string;
+    /** Role of the message sender */
+    role: MessageRole;
+    /** Text content (null for tool-calling assistant messages) */
+    content: string | null;
+    /**
+     * Tool calls made by assistant (OpenAI format)
+     * Only present when role is "assistant" and AI wants to call tools
+     */
+    tool_calls?: ToolCall[];
+    /**
+     * Tool call ID this message is responding to
+     * Only present when role is "tool"
+     */
+    tool_call_id?: string;
+    /**
+     * Flexible metadata container
+     * Contains: thinking, sources, attachments, model, usage, etc.
+     */
+    metadata?: MessageMetadata;
+    /** When the message was created */
+    created_at: Date;
+}
+/**
+ * Helper to parse tool call arguments
+ */
+declare function parseToolCallArgs<T = Record<string, unknown>>(toolCall: ToolCall): T;
+/**
+ * Helper to create a tool call
+ */
+declare function createToolCall(id: string, name: string, args: Record<string, unknown>): ToolCall;
+/**
+ * Create a new message with defaults
+ */
+declare function createMessage(partial: Partial<Message> & Pick<Message, "role"> & {
+    content?: string | null;
+}): Message;
+/**
+ * Create a user message
+ */
+declare function createUserMessage(content: string, options?: {
+    id?: string;
+    thread_id?: string;
+    attachments?: MessageAttachment[];
+}): Message;
+/**
+ * Create an assistant message
+ */
+declare function createAssistantMessage(content: string | null, options?: {
+    id?: string;
+    thread_id?: string;
+    tool_calls?: ToolCall[];
+    thinking?: string;
+    sources?: Source[];
+    model?: string;
+}): Message;
+/**
+ * Create a tool result message
+ */
+declare function createToolMessage(toolCallId: string, result: {
+    success: boolean;
+    data?: unknown;
+    error?: string;
+    message?: string;
+}, options?: {
+    id?: string;
+    thread_id?: string;
+}): Message;
+/**
+ * Check if a message has tool calls
+ */
+declare function hasToolCalls(message: Message): boolean;
+/**
+ * Check if a message is a tool result
+ */
+declare function isToolResult(message: Message): boolean;
+
+/**
+ * Supported LLM providers
+ */
+type LLMProvider = "openai" | "anthropic" | "google" | "groq" | "ollama" | "custom";
+/**
+ * LLM configuration
+ */
+interface LLMConfig {
+    /** LLM provider */
+    provider: LLMProvider;
+    /** Model name (e.g., 'gpt-4o', 'claude-3-5-sonnet-latest') */
+    model?: string;
+    /** API key for the provider */
+    apiKey?: string;
+    /** Base URL for custom/self-hosted models */
+    baseUrl?: string;
+    /** Temperature (0-2) */
+    temperature?: number;
+    /** Maximum tokens in response */
+    maxTokens?: number;
+    /** Top P sampling */
+    topP?: number;
+    /** Frequency penalty */
+    frequencyPenalty?: number;
+    /** Presence penalty */
+    presencePenalty?: number;
+    /** Enable streaming responses (default: true) */
+    streaming?: boolean;
+}
+/**
+ * Cloud configuration (for managed hosting)
+ */
+interface CloudConfig {
+    /** API key */
+    apiKey: string;
+    /** Bot ID */
+    botId: string;
+    /** Custom API endpoint (optional) */
+    endpoint?: string;
+}
+/**
+ * Extension configuration
+ */
+interface Extension {
+    /** Extension name */
+    name: string;
+    /** Extension configuration */
+    config: Record<string, unknown>;
+    /** Initialize the extension */
+    init?: () => Promise<void>;
+}
+/**
+ * Main SDK configuration
+ */
+interface CopilotConfig {
+    /** LLM configuration (for self-hosted) */
+    config?: LLMConfig;
+    /** Cloud configuration (for managed hosting) */
+    cloud?: CloudConfig;
+    /** Runtime URL for self-hosted backend */
+    runtimeUrl?: string;
+    /** System prompt */
+    systemPrompt?: string;
+    /** Extensions (like knowledge base) */
+    extensions?: Extension[];
+    /** Enable debug logging */
+    debug?: boolean;
+}
+/**
+ * Default LLM configurations per provider
+ */
+declare const DEFAULT_MODELS: Record<LLMProvider, string>;
+/**
+ * Get default model for a provider
+ */
+declare function getDefaultModel(provider: LLMProvider): string;
+
+/**
+ * Parameter types for actions
+ */
+type ParameterType = "string" | "number" | "boolean" | "object" | "array";
+/**
+ * Action parameter definition
+ */
+interface ActionParameter {
+    /** Parameter type */
+    type: ParameterType;
+    /** Description of the parameter */
+    description?: string;
+    /** Whether the parameter is required */
+    required?: boolean;
+    /** Default value */
+    default?: unknown;
+    /** Enum values for string type */
+    enum?: string[];
+    /** Properties for object type */
+    properties?: Record<string, ActionParameter>;
+    /** Items schema for array type */
+    items?: ActionParameter;
+}
+/**
+ * Action definition
+ */
+interface ActionDefinition<TParams = Record<string, unknown>> {
+    /** Unique name for the action */
+    name: string;
+    /** Description of what the action does */
+    description: string;
+    /** Parameter definitions */
+    parameters?: Record<string, ActionParameter>;
+    /** Handler function */
+    handler: (params: TParams) => unknown | Promise<unknown>;
+    /** Optional render function for UI */
+    render?: (props: ActionRenderProps<TParams>) => unknown;
+}
+/**
+ * Props passed to action render function
+ */
+interface ActionRenderProps<TParams = Record<string, unknown>> {
+    /** Current status */
+    status: "pending" | "executing" | "completed" | "error";
+    /** Arguments passed to the action */
+    args: TParams;
+    /** Result if completed */
+    result?: unknown;
+    /** Error if failed */
+    error?: string;
+}
+/**
+ * Convert action definition to OpenAI tool format
+ */
+declare function actionToTool(action: ActionDefinition): object;
+
+/**
+ * Knowledge Base Types
+ *
+ * Configuration and types for Knowledge Base (RAG) integration.
+ * Currently a placeholder - full implementation coming soon.
+ */
+/**
+ * Supported vector database providers
+ */
+type KnowledgeBaseProvider = "pinecone" | "qdrant" | "chroma" | "supabase" | "weaviate" | "custom";
+/**
+ * Knowledge Base configuration
+ */
+interface KnowledgeBaseConfig {
+    /** Unique identifier for this knowledge base */
+    id: string;
+    /** Display name */
+    name?: string;
+    /** Vector database provider */
+    provider: KnowledgeBaseProvider;
+    /** API key for the vector database */
+    apiKey?: string;
+    /** Index/collection name */
+    index?: string;
+    /** Namespace within the index */
+    namespace?: string;
+    /** Custom endpoint URL (for self-hosted or custom providers) */
+    endpoint?: string;
+    /** Number of results to return (default: 5) */
+    topK?: number;
+    /** Minimum similarity score threshold (0-1) */
+    scoreThreshold?: number;
+    /** Whether to include source metadata in results */
+    includeMetadata?: boolean;
+}
+/**
+ * Knowledge Base search result
+ */
+interface KnowledgeBaseResult {
+    /** Result content/text */
+    content: string;
+    /** Similarity score (0-1) */
+    score: number;
+    /** Source metadata */
+    metadata?: {
+        /** Source document/URL */
+        source?: string;
+        /** Document title */
+        title?: string;
+        /** Page number (for PDFs) */
+        page?: number;
+        /** Chunk index */
+        chunk?: number;
+        /** Any additional metadata */
+        [key: string]: unknown;
+    };
+}
+/**
+ * Knowledge Base search request
+ */
+interface KnowledgeBaseSearchRequest {
+    /** Search query */
+    query: string;
+    /** Knowledge base ID to search */
+    knowledgeBaseId: string;
+    /** Number of results (overrides config) */
+    limit?: number;
+    /** Filter by metadata */
+    filter?: Record<string, unknown>;
+}
+/**
+ * Knowledge Base search response
+ */
+interface KnowledgeBaseSearchResponse {
+    /** Search results */
+    results: KnowledgeBaseResult[];
+    /** Knowledge base ID */
+    knowledgeBaseId: string;
+    /** Query that was searched */
+    query: string;
+    /** Search duration in ms */
+    durationMs?: number;
+}
+/**
+ * Internal Knowledge Base configuration
+ * Used for managed cloud searchIndexDocument API
+ */
+interface InternalKnowledgeBaseConfig {
+    /** Project UID for the knowledge base */
+    projectUid: string;
+    /** Auth token for API calls */
+    token: string;
+    /** App ID (default: "1") */
+    appId?: string;
+    /** Results limit (default: 5) */
+    limit?: number;
+    /** Whether KB is enabled (default: true) */
+    enabled?: boolean;
+}
+/**
+ * Internal Knowledge Base search result
+ */
+interface InternalKnowledgeBaseResult {
+    /** Document ID */
+    id: string;
+    /** Document title */
+    title?: string;
+    /** Matched content snippet */
+    content: string;
+    /** Relevance score */
+    score?: number;
+    /** Source URL if available */
+    url?: string;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Internal Knowledge Base search response
+ */
+interface InternalKnowledgeBaseSearchResponse {
+    /** Whether the search was successful */
+    success: boolean;
+    /** Search results */
+    results: InternalKnowledgeBaseResult[];
+    /** Total number of results */
+    total?: number;
+    /** Error message if failed */
+    error?: string;
+}
+
+/**
+ * Thread metadata (for listing threads)
+ */
+interface Thread {
+    /** Unique thread identifier */
+    id: string;
+    /** Thread title (auto-generated from first message or manual) */
+    title?: string;
+    /** When thread was created */
+    createdAt: Date;
+    /** When thread was last updated */
+    updatedAt: Date;
+}
+/**
+ * Full thread data including messages
+ */
+interface ThreadData extends Thread {
+    /** Messages in this thread */
+    messages: Message[];
+    /** Sources from knowledge base for this thread */
+    sources: Source[];
+}
+/**
+ * Persistence storage interface for custom adapters
+ */
+interface ThreadStorageAdapter {
+    /** Save threads to storage */
+    save: (threads: ThreadData[]) => Promise<void>;
+    /** Load threads from storage */
+    load: () => Promise<ThreadData[]>;
+    /** Clear all threads from storage */
+    clear: () => Promise<void>;
+}
+/**
+ * Persistence configuration
+ */
+interface PersistenceConfig {
+    /** Enable persistence (default: false) */
+    enabled: boolean;
+    /** Storage type */
+    storage?: "localStorage" | "custom";
+    /** Custom storage adapter (required if storage is 'custom') */
+    customStorage?: ThreadStorageAdapter;
+}
+/**
+ * Generate a thread title from message content
+ */
+declare function generateThreadTitle(content: string): string;
+
+export { type Thread as $, type ToolCall as A, type TokenUsage as B, type ConsoleLogOptions as C, type LLMConfig as D, type CloudConfig as E, type Extension as F, type CopilotConfig as G, type HttpMethod as H, type IntentDetectionResult as I, type JSONSchemaProperty as J, type ActionParameter as K, type LLMProvider as L, type MessageAttachment as M, type NetworkRequestOptions as N, type ActionDefinition as O, type ParameterType as P, type ActionRenderProps as Q, type KnowledgeBaseProvider as R, type ScreenshotOptions as S, type ToolDefinition as T, type KnowledgeBaseConfig as U, type KnowledgeBaseResult as V, type KnowledgeBaseSearchRequest as W, type KnowledgeBaseSearchResponse as X, type InternalKnowledgeBaseConfig as Y, type InternalKnowledgeBaseResult as Z, type InternalKnowledgeBaseSearchResponse as _, type ScreenshotResult as a, type ThreadData as a0, type PersistenceConfig as a1, type ThreadStorageAdapter as a2, type AIProvider as a3, type ToolRenderProps as a4, type ToolConfig as a5, type ToolSet as a6, type UnifiedToolCall as a7, type UnifiedToolResult as a8, type ToolApprovalStatus as a9, failure as aA, type ToolExecution as aa, type AgentLoopConfig as ab, type AgentLoopState as ac, type AIResponseMode as ad, type AIContent as ae, type PermissionLevel as af, type ToolPermission as ag, type PermissionStorageConfig as ah, type PermissionStorageAdapter as ai, generateThreadTitle as aj, createMessage as ak, createUserMessage as al, createAssistantMessage as am, createToolMessage as an, createToolCall as ao, parseToolCallArgs as ap, hasToolCalls as aq, isToolResult as ar, actionToTool as as, getDefaultModel as at, DEFAULT_MODELS as au, tool as av, toolToOpenAIFormat as aw, toolToAnthropicFormat as ax, createToolResult as ay, success as az, type ConsoleLogResult as b, type ConsoleLogEntry as c, type NetworkRequestResult as d, type NetworkRequestEntry as e, type Source as f, type ToolExecutionStatus as g, type ToolResponse as h, type ToolInputSchema as i, type ToolLocation as j, type ToolContext as k, detectIntent as l, hasToolSuggestions as m, getPrimaryTool as n, generateSuggestionReason as o, createCustomDetector as p, type ConsoleLogType as q, type ToolType as r, type ToolsConfig as s, type ToolConsentRequest as t, type ToolConsentResponse as u, type CapturedContext as v, type CustomKeywords as w, type MessageRole as x, type Message as y, type MessageMetadata as z };