@blinkdotnew/sdk 2.2.0 → 2.3.0

package/dist/index.d.ts

@@ -353,7 +353,7 @@ interface StorageDownloadResponse {
     contentType?: string;
     size?: number;
 }
-interface TokenUsage {
+interface TokenUsage$1 {
     promptTokens: number;
     completionTokens: number;
     totalTokens: number;
@@ -386,7 +386,7 @@ interface TextGenerationRequest {
 interface TextGenerationResponse {
     text: string;
     finishReason?: 'stop' | 'length' | 'content_filter' | 'tool_calls';
-    usage?: TokenUsage;
+    usage?: TokenUsage$1;
     files?: any[];
     reasoningDetails?: any[];
     toolCalls?: any[];
@@ -400,7 +400,7 @@ interface TextGenerationResponse {
         stepType?: string;
         text?: string;
         finishReason?: string;
-        usage?: TokenUsage;
+        usage?: TokenUsage$1;
     }>;
     sources?: any[];
     providerMetadata?: any;
@@ -418,7 +418,7 @@ interface ObjectGenerationRequest {
 interface ObjectGenerationResponse {
     object: any;
     finishReason?: 'stop' | 'length' | 'content_filter';
-    usage?: TokenUsage;
+    usage?: TokenUsage$1;
     warnings?: string[];
     providerMetadata?: {
         openai?: {
@@ -561,6 +561,11 @@ interface BlinkAI {
     generateVideo(options: VideoGenerationRequest): Promise<VideoGenerationResponse>;
     generateSpeech(options: SpeechGenerationRequest): Promise<SpeechGenerationResponse>;
     transcribeAudio(options: TranscriptionRequest): Promise<TranscriptionResponse>;
+    agent(options: any): Promise<any>;
+    /** Creates a reusable Agent instance (Vercel AI SDK pattern) */
+    createAgent(options: any): any;
+    /** Binds an existing Agent instance to this client's httpClient */
+    bindAgent(agent: any): any;
 }
 interface DataExtraction {
     chunks: string[];
@@ -806,6 +811,84 @@ interface SendEmailResponse {
 interface BlinkNotifications {
     email(params: SendEmailRequest): Promise<SendEmailResponse>;
 }
+/**
+ * Token type in Blink Auth system
+ * - `access`: Regular user access token (short-lived)
+ * - `service`: Service token for server-side operations (permanent secret key)
+ */
+type BlinkTokenType = 'access' | 'service';
+/**
+ * Result of token introspection
+ * Used by edge functions and server-side code to verify user tokens
+ */
+interface TokenIntrospectionResult {
+    /** Whether the token is valid */
+    valid: boolean;
+    /** Project ID from the token */
+    projectId?: string;
+    /** User ID (Firebase UID) - only present for access tokens */
+    userId?: string;
+    /** User's email - only present for access tokens */
+    email?: string;
+    /** Token type: 'access' or 'service' */
+    tokenType?: BlinkTokenType;
+    /** User's role in the app (if set via app_role claim) */
+    appRole?: string;
+    /** Token expiration timestamp (Unix seconds) - not present for secret keys */
+    exp?: number;
+    /** Legacy service key ID (for JWT-based service tokens) */
+    svcKeyId?: string;
+    /** Error message if token is invalid */
+    error?: string;
+}
+
+type ConnectorProvider = 'discord' | 'notion' | 'google_drive' | 'google_calendar' | 'ai';
+type ConnectorAuthMode = 'oauth' | 'api_key' | 'blink_managed' | 'hybrid';
+interface ConnectorStatusData {
+    connected: boolean;
+    provider: ConnectorProvider;
+    auth_mode?: ConnectorAuthMode;
+    account_id?: string;
+    metadata?: Record<string, unknown>;
+    expires_at?: any;
+    scopes?: string[];
+}
+interface ConnectorStatusResponse {
+    success: boolean;
+    data: ConnectorStatusData;
+}
+interface ConnectorExecuteRequest<TParams = Record<string, unknown>> {
+    method: string;
+    params?: TParams;
+    account_id?: string;
+    http_method?: string;
+}
+interface ConnectorExecuteResponse<TData = any> {
+    success: boolean;
+    data: TData;
+}
+interface ConnectorApiKeyRequest<TMetadata = Record<string, unknown>> {
+    api_key: string;
+    account_id?: string;
+    metadata?: TMetadata;
+}
+interface ConnectorApiKeyResponse {
+    success: boolean;
+    data: {
+        id: string;
+        account_id?: string;
+    };
+}
+interface BlinkConnectors {
+    status(provider: ConnectorProvider, options?: {
+        account_id?: string;
+    }): Promise<ConnectorStatusResponse>;
+    execute<TParams = Record<string, unknown>, TData = any>(provider: ConnectorProvider, request: ConnectorExecuteRequest<TParams>): Promise<ConnectorExecuteResponse<TData>>;
+    saveApiKey<TMetadata = Record<string, unknown>>(provider: ConnectorProvider, request: ConnectorApiKeyRequest<TMetadata>): Promise<ConnectorApiKeyResponse>;
+}
+declare class BlinkConnectorError extends BlinkError {
+    constructor(message: string, status?: number, details?: any);
+}
 
 /**
  * HTTP client for Blink API requests
@@ -988,6 +1071,80 @@ declare class HttpClient {
         cfg_scale?: number;
         signal?: AbortSignal;
     }): Promise<BlinkResponse<any>>;
+    /**
+     * AI Agent request (non-streaming)
+     * Returns JSON response with text, steps, usage, and billing
+     */
+    aiAgent(requestBody: {
+        stream: false;
+        prompt?: string;
+        messages?: Array<{
+            role: string;
+            content: string | any[];
+            parts?: any[];
+        }>;
+        agent: {
+            model: string;
+            system?: string;
+            tools?: string[];
+            webhook_tools?: Array<{
+                name: string;
+                description: string;
+                input_schema: any;
+                webhook_url: string;
+            }>;
+            client_tools?: Array<{
+                name: string;
+                description: string;
+                input_schema: any;
+            }>;
+            tool_choice?: 'auto' | 'required' | 'none';
+            stop_when?: Array<{
+                type: string;
+                count: number;
+            }>;
+            prepare_step?: {
+                context_policy: any;
+            };
+        };
+    }, signal?: AbortSignal): Promise<BlinkResponse<any>>;
+    /**
+     * AI Agent streaming request
+     * Returns raw Response for SSE streaming (compatible with AI SDK useChat)
+     */
+    aiAgentStream(requestBody: {
+        stream: true;
+        prompt?: string;
+        messages?: Array<{
+            role: string;
+            content: string | any[];
+            parts?: any[];
+        }>;
+        agent: {
+            model: string;
+            system?: string;
+            tools?: string[];
+            webhook_tools?: Array<{
+                name: string;
+                description: string;
+                input_schema: any;
+                webhook_url: string;
+            }>;
+            client_tools?: Array<{
+                name: string;
+                description: string;
+                input_schema: any;
+            }>;
+            tool_choice?: 'auto' | 'required' | 'none';
+            stop_when?: Array<{
+                type: string;
+                count: number;
+            }>;
+            prepare_step?: {
+                context_policy: any;
+            };
+        };
+    }, signal?: AbortSignal): Promise<Response>;
     /**
      * Data-specific requests
      */
@@ -997,6 +1154,13 @@ declare class HttpClient {
     dataScreenshot(projectId: string, request: ScreenshotRequest): Promise<BlinkResponse<ScreenshotResponse>>;
     dataFetch(projectId: string, request: FetchRequest): Promise<BlinkResponse<FetchResponse | AsyncFetchResponse>>;
     dataSearch(projectId: string, request: SearchRequest): Promise<BlinkResponse<SearchResponse>>;
+    /**
+     * Connector requests
+     */
+    private formatProviderForPath;
+    connectorStatus(provider: ConnectorProvider): Promise<BlinkResponse<ConnectorStatusResponse>>;
+    connectorExecute<TParams = Record<string, unknown>, TData = any>(provider: ConnectorProvider, request: ConnectorExecuteRequest<TParams>): Promise<BlinkResponse<ConnectorExecuteResponse<TData>>>;
+    connectorSaveApiKey<TMetadata = Record<string, unknown>>(provider: ConnectorProvider, request: ConnectorApiKeyRequest<TMetadata>): Promise<BlinkResponse<ConnectorApiKeyResponse>>;
     /**
      * Realtime-specific requests
      */
@@ -1422,6 +1586,44 @@ declare class BlinkAuth {
         expires_in?: number;
         refresh_expires_in?: number;
     }, persist?: boolean): Promise<BlinkUser>;
+    /**
+     * Verify a Blink Auth token using the introspection endpoint.
+     *
+     * **Server-side / Edge Function use only.**
+     *
+     * This is the recommended way to verify user tokens in Deno Edge Functions
+     * and other server-side contexts. It calls the Blink API introspection
+     * endpoint which validates the token without exposing the JWT secret.
+     *
+     * @param token - The raw JWT token (without "Bearer " prefix) or full Authorization header
+     * @returns Token introspection result with validity and claims
+     *
+     * @example
+     * // Deno Edge Function usage
+     * import { createClient } from "npm:@blinkdotnew/sdk";
+     *
+     * const blink = createClient({
+     *   projectId: Deno.env.get("BLINK_PROJECT_ID")!,
+     *   secretKey: Deno.env.get("BLINK_SECRET_KEY"),
+     * });
+     *
+     * async function handler(req: Request): Promise<Response> {
+     *   const authHeader = req.headers.get("Authorization");
+     *   const result = await blink.auth.verifyToken(authHeader);
+     *
+     *   if (!result.valid) {
+     *     return new Response(JSON.stringify({ error: result.error }), { status: 401 });
+     *   }
+     *
+     *   // User is authenticated
+     *   console.log("User ID:", result.userId);
+     *   console.log("Email:", result.email);
+     *   console.log("Project:", result.projectId);
+     *
+     *   // Continue with your logic...
+     * }
+     */
+    verifyToken(token: string | null): Promise<TokenIntrospectionResult>;
     /**
      * Refresh access token using refresh token
      */
@@ -1772,6 +1974,317 @@ interface BlinkFunctions {
     invoke<T = any>(functionSlug: string, options?: FunctionsInvokeOptions): Promise<FunctionsInvokeResponse<T>>;
 }
 
+/**
+ * Blink RAG Module - Vector Search and AI-powered retrieval
+ *
+ * Provides document ingestion, vector search, and RAG (Retrieval-Augmented Generation) capabilities.
+ */
+
+interface RAGCollection {
+    id: string;
+    name: string;
+    description: string | null;
+    embeddingModel: string;
+    embeddingDimensions: number;
+    indexMetric: 'cosine' | 'l2';
+    chunkMaxTokens: number;
+    chunkOverlapTokens: number;
+    documentCount: number;
+    chunkCount: number;
+    shared: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+interface RAGDocument {
+    id: string;
+    collectionId: string;
+    filename: string;
+    sourceType: 'file' | 'url' | 'text';
+    sourceUrl: string | null;
+    contentType: string | null;
+    fileSize: number | null;
+    status: 'pending' | 'processing' | 'ready' | 'error';
+    errorMessage: string | null;
+    processingStartedAt: string | null;
+    processingCompletedAt: string | null;
+    chunkCount: number;
+    tokenCount: number | null;
+    metadata: Record<string, any>;
+    createdAt: string;
+    updatedAt: string;
+}
+interface RAGSearchResult {
+    chunkId: string;
+    documentId: string;
+    filename: string;
+    content: string;
+    score: number;
+    chunkIndex: number;
+    metadata: Record<string, any>;
+}
+interface RAGSearchResponse {
+    results: RAGSearchResult[];
+    query: string;
+    collectionId: string;
+    totalResults: number;
+}
+interface RAGAISearchSource {
+    documentId: string;
+    filename: string;
+    chunkId: string;
+    excerpt: string;
+    score: number;
+}
+interface RAGAISearchResult {
+    answer: string;
+    sources: RAGAISearchSource[];
+    query: string;
+    model: string;
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+}
+interface CreateCollectionOptions {
+    name: string;
+    description?: string;
+    embeddingModel?: string;
+    embeddingDimensions?: number;
+    indexMetric?: 'cosine' | 'l2';
+    chunkMaxTokens?: number;
+    chunkOverlapTokens?: number;
+    shared?: boolean;
+}
+interface UploadOptions {
+    collectionId?: string;
+    collectionName?: string;
+    filename: string;
+    content?: string;
+    file?: {
+        data: string;
+        contentType: string;
+    };
+    url?: string;
+    metadata?: Record<string, any>;
+}
+interface SearchOptions {
+    collectionId?: string;
+    collectionName?: string;
+    query: string;
+    maxResults?: number;
+    scoreThreshold?: number;
+    filters?: Record<string, any>;
+    includeContent?: boolean;
+}
+interface AISearchOptions {
+    collectionId?: string;
+    collectionName?: string;
+    query: string;
+    model?: string;
+    maxContextChunks?: number;
+    scoreThreshold?: number;
+    systemPrompt?: string;
+    stream?: boolean;
+}
+interface ListDocumentsOptions {
+    collectionId?: string;
+    status?: 'pending' | 'processing' | 'ready' | 'error';
+}
+interface WaitForReadyOptions {
+    timeoutMs?: number;
+    pollIntervalMs?: number;
+}
+declare class BlinkRAGImpl {
+    private httpClient;
+    private projectId;
+    constructor(httpClient: HttpClient);
+    /**
+     * Build URL with project_id prefix
+     */
+    private url;
+    /**
+     * Create a new RAG collection
+     */
+    createCollection(options: CreateCollectionOptions): Promise<RAGCollection>;
+    /**
+     * List all collections accessible to the current user
+     */
+    listCollections(): Promise<RAGCollection[]>;
+    /**
+     * Get a specific collection by ID
+     */
+    getCollection(collectionId: string): Promise<RAGCollection>;
+    /**
+     * Delete a collection and all its documents
+     */
+    deleteCollection(collectionId: string): Promise<void>;
+    /**
+     * Upload a document for processing
+     *
+     * @example
+     * // Upload text content
+     * const doc = await blink.rag.upload({
+     *   collectionName: 'docs',
+     *   filename: 'notes.txt',
+     *   content: 'My document content...'
+     * })
+     *
+     * @example
+     * // Upload from URL
+     * const doc = await blink.rag.upload({
+     *   collectionId: 'col_abc123',
+     *   filename: 'article.html',
+     *   url: 'https://example.com/article'
+     * })
+     *
+     * @example
+     * // Upload a file (base64)
+     * const doc = await blink.rag.upload({
+     *   collectionName: 'docs',
+     *   filename: 'report.pdf',
+     *   file: { data: base64Data, contentType: 'application/pdf' }
+     * })
+     */
+    upload(options: UploadOptions): Promise<RAGDocument>;
+    /**
+     * Get document status and metadata
+     */
+    getDocument(documentId: string): Promise<RAGDocument>;
+    /**
+     * List documents, optionally filtered by collection or status
+     */
+    listDocuments(options?: ListDocumentsOptions): Promise<RAGDocument[]>;
+    /**
+     * Delete a document and its chunks
+     */
+    deleteDocument(documentId: string): Promise<void>;
+    /**
+     * Wait for a document to finish processing
+     *
+     * @example
+     * const doc = await blink.rag.upload({ ... })
+     * const readyDoc = await blink.rag.waitForReady(doc.id)
+     * console.log(`Processed ${readyDoc.chunkCount} chunks`)
+     */
+    waitForReady(documentId: string, options?: WaitForReadyOptions): Promise<RAGDocument>;
+    /**
+     * Search for similar chunks using vector similarity
+     *
+     * @example
+     * const results = await blink.rag.search({
+     *   collectionName: 'docs',
+     *   query: 'How do I configure authentication?',
+     *   maxResults: 5
+     * })
+     */
+    search(options: SearchOptions): Promise<RAGSearchResponse>;
+    /**
+     * Perform RAG: search + LLM answer generation
+     *
+     * @example
+     * // Non-streaming
+     * const result = await blink.rag.aiSearch({
+     *   collectionName: 'docs',
+     *   query: 'What are the main features?'
+     * })
+     * console.log(result.answer)
+     *
+     * @example
+     * // Streaming
+     * const stream = await blink.rag.aiSearch({
+     *   collectionName: 'docs',
+     *   query: 'Explain the architecture',
+     *   stream: true
+     * })
+     */
+    aiSearch(options: AISearchOptions & {
+        stream?: false;
+    }): Promise<RAGAISearchResult>;
+    aiSearch(options: AISearchOptions & {
+        stream: true;
+    }): Promise<ReadableStream<Uint8Array>>;
+}
+type BlinkRAG = BlinkRAGImpl;
+
+/**
+ * Blink Sandbox Module - Persistent coding environments for AI agents
+ *
+ * Provides lifecycle management for E2B sandboxes with auto-pause and resume.
+ * Used with agent.generate({ sandbox }) for AI coding agents.
+ */
+
+interface Sandbox {
+    /** Sandbox ID (sbx_xxx format) - STORE THIS for persistence! */
+    id: string;
+    /** Template used to create the sandbox */
+    template: string;
+    /** Get public URL for any port (sync - computed locally from hostPattern) */
+    getHost(port: number): string;
+}
+interface SandboxCreateOptions {
+    /** E2B template ID (default: 'devtools-base') */
+    template?: string;
+    /** Inactivity timeout in ms (default: 5 min, max: 60 min) */
+    timeoutMs?: number;
+    /** Custom metadata for tracking */
+    metadata?: Record<string, string>;
+}
+interface SandboxConnectOptions {
+    /** Reset inactivity timeout in ms (default: 5 min) */
+    timeoutMs?: number;
+}
+interface BlinkSandbox {
+    /**
+     * Create a new persistent sandbox with auto-pause enabled.
+     *
+     * @example
+     * ```ts
+     * const sandbox = await blink.sandbox.create({ template: 'nextjs-app' })
+     * console.log(sandbox.id) // "sbx_abc123xyz" - Store this!
+     * console.log(sandbox.getHost(3000)) // "3000-sbx_abc123xyz.preview-blink.com"
+     * ```
+     */
+    create(options?: SandboxCreateOptions): Promise<Sandbox>;
+    /**
+     * Connect to an existing sandbox. Auto-resumes if paused.
+     * Built-in retry with exponential backoff (3 retries: 250ms → 500ms → 1000ms).
+     *
+     * @example
+     * ```ts
+     * const sandbox = await blink.sandbox.connect(storedSandboxId)
+     * ```
+     */
+    connect(sandboxId: string, options?: SandboxConnectOptions): Promise<Sandbox>;
+    /**
+     * Permanently kill a sandbox. Cannot be resumed after kill.
+     *
+     * @example
+     * ```ts
+     * await blink.sandbox.kill(sandboxId)
+     * await blink.db.user_sandboxes.delete({ sandbox_id: sandboxId })
+     * ```
+     */
+    kill(sandboxId: string): Promise<void>;
+}
+declare const SANDBOX_TEMPLATES: readonly ["devtools-base", "nextjs-app", "nextjs-app-bun", "vite-react", "vite-react-bun", "expo-app", "desktop", "claude-code"];
+type SandboxTemplate = typeof SANDBOX_TEMPLATES[number];
+declare class SandboxConnectionError extends Error {
+    sandboxId: string;
+    constructor(sandboxId: string, cause?: Error);
+}
+declare class BlinkSandboxImpl implements BlinkSandbox {
+    private httpClient;
+    private projectId;
+    constructor(httpClient: HttpClient);
+    /**
+     * Build URL with project_id prefix
+     */
+    private url;
+    create(options?: SandboxCreateOptions): Promise<Sandbox>;
+    connect(sandboxId: string, options?: SandboxConnectOptions): Promise<Sandbox>;
+    kill(sandboxId: string): Promise<void>;
+}
+
 /**
  * Blink Client - Main SDK entry point
  * Factory function and client class for the Blink SDK
@@ -1786,7 +2299,10 @@ interface BlinkClient {
     realtime: BlinkRealtime;
     notifications: BlinkNotifications;
     analytics: BlinkAnalytics;
+    connectors: BlinkConnectors;
     functions: BlinkFunctions;
+    rag: BlinkRAG;
+    sandbox: BlinkSandbox;
 }
 /**
  * Create a new Blink client instance
@@ -1888,6 +2404,373 @@ declare class BlinkStorageImpl implements BlinkStorage {
     remove(...paths: string[]): Promise<void>;
 }
 
+/**
+ * Agent Tool Types
+ *
+ * Type definitions for AI agent tools used with blink.ai.agent()
+ */
+/**
+ * A tool definition that can be passed to the agent
+ */
+interface AgentTool {
+    /** Tool name (used as identifier) */
+    name: string;
+    /** Human-readable description for the LLM */
+    description: string;
+    /** JSON Schema for tool input parameters */
+    inputSchema: JSONSchema;
+}
+/**
+ * JSON Schema type for tool input definitions
+ */
+type JSONSchema = Record<string, any>;
+/**
+ * A custom webhook tool definition
+ */
+interface WebhookTool {
+    /** Tool name */
+    name: string;
+    /** Human-readable description */
+    description: string;
+    /** JSON Schema for input parameters */
+    input_schema: JSONSchema;
+    /** URL to POST when tool is called */
+    webhook_url: string;
+}
+/**
+ * A client-side tool requiring user confirmation
+ */
+interface ClientTool {
+    /** Tool name */
+    name: string;
+    /** Human-readable description */
+    description: string;
+    /** JSON Schema for input parameters */
+    input_schema: JSONSchema;
+}
+/**
+ * Stop condition for agent loop
+ */
+interface StopCondition {
+    type: 'step_count_is';
+    count: number;
+}
+/**
+ * Context policy for managing conversation history
+ */
+interface ContextPolicy {
+    strategy: 'token_budget';
+    max_input_tokens: number;
+    keep_system: boolean;
+    keep_last_messages: number;
+    trim_order: string[];
+    max_tool_result_bytes: number;
+}
+/**
+ * Agent configuration
+ */
+interface AgentConfig {
+    /** Model ID in Vercel AI Gateway format: "provider/model-id" */
+    model: string;
+    /** System prompt */
+    system?: string;
+    /** Built-in tools to enable (tool names or bundles) */
+    tools?: (AgentTool | string)[];
+    /** Custom webhook tools */
+    webhook_tools?: WebhookTool[];
+    /** Client-side tools for HITL */
+    client_tools?: ClientTool[];
+    /** Tool choice strategy */
+    tool_choice?: 'auto' | 'required' | 'none';
+    /** Stop conditions */
+    stop_when?: StopCondition[];
+    /** Context management */
+    prepare_step?: {
+        context_policy: Partial<ContextPolicy>;
+    };
+}
+/**
+ * UI Message format (AI SDK compatible)
+ */
+interface UIMessage {
+    id?: string;
+    role: 'user' | 'assistant';
+    content: string;
+    parts?: UIMessagePart[];
+}
+type UIMessagePart = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'tool-invocation';
+    toolCallId: string;
+    toolName: string;
+    state: 'pending' | 'result' | 'output-available';
+    input: Record<string, any>;
+    output?: any;
+};
+/**
+ * Agent request for streaming mode
+ */
+interface AgentStreamRequest {
+    stream: true;
+    messages: UIMessage[];
+    agent: AgentConfig;
+}
+/**
+ * Agent request for non-streaming mode with messages
+ */
+interface AgentNonStreamMessagesRequest {
+    stream: false;
+    messages: UIMessage[];
+    agent: AgentConfig;
+}
+/**
+ * Agent request for non-streaming mode with prompt
+ */
+interface AgentNonStreamPromptRequest {
+    stream: false;
+    prompt: string;
+    agent: AgentConfig;
+}
+/**
+ * Union of all agent request types
+ */
+type AgentRequest = AgentStreamRequest | AgentNonStreamMessagesRequest | AgentNonStreamPromptRequest;
+/**
+ * Token usage information
+ */
+interface TokenUsage {
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens?: number;
+}
+/**
+ * Tool call in a step
+ */
+interface ToolCall {
+    toolCallId: string;
+    toolName: string;
+    args: Record<string, any>;
+}
+/**
+ * Tool result in a step
+ */
+interface ToolResult {
+    toolCallId: string;
+    result: any;
+}
+/**
+ * Agent step information
+ */
+interface AgentStep {
+    text: string;
+    toolCalls: ToolCall[];
+    toolResults: ToolResult[];
+    finishReason: string;
+    usage: TokenUsage;
+}
+/**
+ * Billing information
+ */
+interface AgentBilling {
+    model: string;
+    creditsCharged: number;
+    costUSD: number;
+    breakdown?: {
+        ai: {
+            credits: number;
+            costUSD: number;
+        };
+        tools: Record<string, {
+            count: number;
+            credits: number;
+            costUSD: number;
+        }>;
+    };
+}
+/**
+ * Non-streaming agent response
+ */
+interface AgentResponse {
+    text: string;
+    finishReason: 'stop' | 'length' | 'tool-calls' | 'error' | 'content-filter';
+    steps: AgentStep[];
+    usage: TokenUsage;
+    warnings?: Array<{
+        type: string;
+        message: string;
+    }>;
+    _billing: AgentBilling;
+}
+
+/**
+ * Agent Class
+ *
+ * Matches Vercel AI SDK ToolLoopAgent pattern:
+ * - Create agent instance with config
+ * - Call agent.generate() for non-streaming
+ * - Call agent.stream() for streaming
+ */
+
+/**
+ * Options for creating an Agent instance
+ * Matches Vercel AI SDK ToolLoopAgent constructor options
+ */
+interface AgentOptions {
+    /** Model ID in Vercel AI Gateway format: "provider/model-id" */
+    model: string;
+    /** System prompt / instructions */
+    system?: string;
+    /** Alias for system (Vercel AI SDK compatibility) */
+    instructions?: string;
+    /** Built-in tools to enable */
+    tools?: (AgentTool | string)[];
+    /** Custom webhook tools */
+    webhookTools?: WebhookTool[];
+    /** Client-side tools for HITL */
+    clientTools?: ClientTool[];
+    /** Tool choice strategy */
+    toolChoice?: 'auto' | 'required' | 'none';
+    /** Stop conditions */
+    stopWhen?: StopCondition[];
+    /** Maximum number of steps (convenience for stopWhen) */
+    maxSteps?: number;
+}
+/**
+ * Options for agent.generate() call
+ */
+interface GenerateOptions {
+    /** Simple text prompt */
+    prompt?: string;
+    /** Conversation history */
+    messages?: UIMessage[];
+    /** Sandbox for sandbox tools (object with id, or just sandboxId string) */
+    sandbox?: Sandbox | string;
+    /** Abort signal for cancellation */
+    signal?: AbortSignal;
+}
+/**
+ * Options for agent.stream() call
+ */
+interface StreamOptions {
+    /** Simple text prompt */
+    prompt?: string;
+    /** Conversation history */
+    messages?: UIMessage[];
+    /** Sandbox for sandbox tools (object with id, or just sandboxId string) */
+    sandbox?: Sandbox | string;
+    /** Abort signal for cancellation */
+    signal?: AbortSignal;
+}
+/**
+ * AI Agent class following Vercel AI SDK ToolLoopAgent pattern.
+ *
+ * Create an agent instance with configuration, then use:
+ * - `agent.generate({ prompt })` for non-streaming one-shot generation
+ * - `agent.stream({ prompt })` for streaming real-time generation
+ *
+ * @example
+ * ```ts
+ * import { Agent, webSearch, fetchUrl } from '@blinkdotnew/sdk'
+ *
+ * const weatherAgent = new Agent({
+ *   model: 'anthropic/claude-sonnet-4-20250514',
+ *   system: 'You are a helpful weather assistant.',
+ *   tools: [webSearch, fetchUrl],
+ *   maxSteps: 10,
+ * })
+ *
+ * // Non-streaming
+ * const result = await weatherAgent.generate({
+ *   prompt: 'What is the weather in San Francisco?',
+ * })
+ * console.log(result.text)
+ *
+ * // Streaming
+ * const stream = await weatherAgent.stream({
+ *   prompt: 'Tell me about weather patterns',
+ * })
+ * ```
+ */
+declare class Agent {
+    private httpClient;
+    private readonly config;
+    /**
+     * Create a new Agent instance
+     * @param options - Agent configuration options
+     */
+    constructor(options: AgentOptions);
+    /**
+     * Internal: Set the HTTP client (called by BlinkClient)
+     */
+    _setHttpClient(client: HttpClient): void;
+    /**
+     * Internal: Get the agent config for API requests
+     */
+    private getAgentConfig;
+    /**
+     * Generate a response (non-streaming)
+     *
+     * @param options - Generation options (prompt or messages)
+     * @returns Promise<AgentResponse> with text, steps, usage, and billing
+     *
+     * @example
+     * ```ts
+     * const result = await agent.generate({
+     *   prompt: 'What is the weather in San Francisco?',
+     * })
+     * console.log(result.text)
+     * console.log(result.steps)
+     * ```
+     */
+    generate(options: GenerateOptions): Promise<AgentResponse>;
+    /**
+     * Stream a response (real-time)
+     *
+     * @param options - Stream options (prompt or messages)
+     * @returns Promise<Response> - AI SDK UI Message Stream for useChat compatibility
+     *
+     * @example
+     * ```ts
+     * const stream = await agent.stream({
+     *   prompt: 'Tell me a story',
+     * })
+     *
+     * // Process stream
+     * for await (const chunk of stream.body) {
+     *   // Handle chunk
+     * }
+     * ```
+     */
+    stream(options: StreamOptions): Promise<Response>;
+    /**
+     * Get the agent's model
+     */
+    get model(): string;
+    /**
+     * Get the agent's system prompt
+     */
+    get system(): string | undefined;
+    /**
+     * Get the agent's tools
+     */
+    get tools(): (AgentTool | string)[] | undefined;
+}
+/**
+ * Creates a stop condition for maximum step count
+ * Matches Vercel AI SDK's stepCountIs helper
+ *
+ * @example
+ * ```ts
+ * const agent = new Agent({
+ *   model: 'openai/gpt-4o',
+ *   stopWhen: [stepCountIs(10)],
+ * })
+ * ```
+ */
+declare function stepCountIs(count: number): StopCondition;
+
 /**
  * Blink AI Module
  * Provides AI generation capabilities with Vercel AI SDK compatibility
@@ -2428,6 +3311,110 @@ declare class BlinkAIImpl implements BlinkAI {
      *   - `duration`: Audio duration in seconds
      */
     transcribeAudio(options: TranscriptionRequest): Promise<TranscriptionResponse>;
+    /**
+     * Runs an AI agent that can use tools in a loop to accomplish tasks.
+     *
+     * @param options - Agent request options
+     *   - `stream`: Whether to stream the response (true for UI, false for headless)
+     *   - `prompt`: Simple string prompt (for non-streaming, mutually exclusive with messages)
+     *   - `messages`: Array of UI messages (for streaming or non-streaming with history)
+     *   - `agent`: Agent configuration (model, tools, system prompt, etc.)
+     *   - `signal`: AbortSignal for cancellation
+     *
+     * @example Non-streaming with prompt
+     * ```ts
+     * const result = await blink.ai.agent({
+     *   stream: false,
+     *   prompt: 'What is the weather in Tokyo?',
+     *   agent: {
+     *     model: 'openai/gpt-4o',
+     *     tools: ['web_search']
+     *   }
+     * })
+     * console.log(result.text)
+     * ```
+     *
+     * @example Streaming with messages (for useChat integration)
+     * ```ts
+     * const response = await blink.ai.agent({
+     *   stream: true,
+     *   messages: [{ role: 'user', content: 'Search for AI news' }],
+     *   agent: {
+     *     model: 'openai/gpt-4o',
+     *     tools: [webSearch, fetchUrl]
+     *   }
+     * })
+     * // Response is a ReadableStream for SSE
+     * ```
+     *
+     * @returns For non-streaming: Promise<AgentResponse>
+     *          For streaming: Promise<Response> (SSE stream)
+     */
+    agent(options: {
+        stream: false;
+        prompt: string;
+        agent: AgentConfig;
+        signal?: AbortSignal;
+    }): Promise<AgentResponse>;
+    agent(options: {
+        stream: false;
+        messages: UIMessage[];
+        agent: AgentConfig;
+        signal?: AbortSignal;
+    }): Promise<AgentResponse>;
+    agent(options: {
+        stream: true;
+        messages: UIMessage[];
+        agent: AgentConfig;
+        signal?: AbortSignal;
+    }): Promise<Response>;
+    agent(options: {
+        stream: true;
+        prompt: string;
+        agent: AgentConfig;
+        signal?: AbortSignal;
+    }): Promise<Response>;
+    /**
+     * Creates a reusable Agent instance with the Vercel AI SDK pattern.
+     *
+     * The Agent can be used multiple times with different prompts:
+     * - `agent.generate({ prompt })` for non-streaming
+     * - `agent.stream({ prompt })` for streaming
+     *
+     * @param options - Agent configuration (model, tools, system, etc.)
+     * @returns Agent instance
+     *
+     * @example
+     * ```ts
+     * const weatherAgent = blink.ai.createAgent({
+     *   model: 'anthropic/claude-sonnet-4-20250514',
+     *   system: 'You are a helpful weather assistant.',
+     *   tools: [webSearch, fetchUrl],
+     *   maxSteps: 10,
+     * })
+     *
+     * // Non-streaming
+     * const result = await weatherAgent.generate({
+     *   prompt: 'What is the weather in San Francisco?',
+     * })
+     *
+     * // Streaming
+     * const stream = await weatherAgent.stream({
+     *   prompt: 'Tell me about weather patterns',
+     * })
+     * ```
+     */
+    createAgent(options: AgentOptions): Agent;
+    /**
+     * Binds an existing Agent instance to this client's HTTP client.
+     *
+     * Used internally by useAgent() when an Agent instance is passed.
+     * This allows agents created with `new Agent()` to be used with the hook.
+     *
+     * @param agent - Existing Agent instance
+     * @returns The same Agent instance (with httpClient set)
+     */
+    bindAgent(agent: Agent): Agent;
 }
 
 /**
@@ -2512,4 +3499,354 @@ declare class BlinkRealtimeImpl implements BlinkRealtime {
     onPresence(channelName: string, callback: (users: PresenceUser[]) => void): () => void;
 }
 
-export { type AnalyticsEvent, AsyncStorageAdapter, type AuthState, type AuthStateChangeCallback, type AuthTokens, type BlinkAI, BlinkAIImpl, type BlinkAnalytics, BlinkAnalyticsImpl, type BlinkClient, type BlinkClientConfig, type BlinkData, BlinkDataImpl, BlinkDatabase, type BlinkRealtime, BlinkRealtimeChannel, BlinkRealtimeError, BlinkRealtimeImpl, type BlinkStorage, BlinkStorageImpl, BlinkTable, type BlinkUser, type CreateOptions, type DataExtraction, type FileObject, type FilterCondition, type ImageGenerationRequest, type ImageGenerationResponse, type Message, NoOpStorageAdapter, type ObjectGenerationRequest, type ObjectGenerationResponse, type PresenceUser, type QueryOptions, type RealtimeChannel, type RealtimeGetMessagesOptions, type RealtimeMessage, type RealtimePublishOptions, type RealtimeSubscribeOptions, type SearchRequest, type SearchResponse, type SpeechGenerationRequest, type SpeechGenerationResponse, type StorageAdapter, type StorageUploadOptions, type StorageUploadResponse, type TableOperations, type TextGenerationRequest, type TextGenerationResponse, type TokenUsage, type TranscriptionRequest, type TranscriptionResponse, type UpdateOptions, type UpsertOptions, type WebBrowserModule, WebStorageAdapter, createClient, getDefaultStorageAdapter, isBrowser, isDeno, isNode, isReactNative, isServer, isWeb, platform };
+declare class BlinkConnectorsImpl implements BlinkConnectors {
+    private httpClient;
+    constructor(httpClient: HttpClient);
+    status(provider: ConnectorProvider, options?: {
+        account_id?: string;
+    }): Promise<ConnectorStatusResponse>;
+    execute<TParams = Record<string, unknown>, TData = any>(provider: ConnectorProvider, request: ConnectorExecuteRequest<TParams>): Promise<ConnectorExecuteResponse<TData>>;
+    saveApiKey<TMetadata = Record<string, unknown>>(provider: ConnectorProvider, request: ConnectorApiKeyRequest<TMetadata>): Promise<ConnectorApiKeyResponse>;
+}
+
+/**
+ * Core Agent Tools
+ *
+ * Individual tool definitions for web search, URL fetching, scraping, and code execution.
+ */
+
+/**
+ * Web search tool for finding current information
+ *
+ * Powered by Exa AI - performs real-time web searches and returns
+ * relevant results with titles, URLs, and snippets.
+ *
+ * @example
+ * ```ts
+ * import { Agent, webSearch } from '@blinkdotnew/react'
+ *
+ * const researchAgent = new Agent({
+ *   model: 'openai/gpt-4o',
+ *   tools: [webSearch]
+ * })
+ *
+ * const result = await researchAgent.generate({
+ *   prompt: 'What are the latest AI developments?'
+ * })
+ * ```
+ */
+declare const webSearch: AgentTool;
+/**
+ * Fetch URL content as clean text (HTML stripped)
+ *
+ * Fast text extraction from URLs - no JavaScript rendering.
+ * Good for Wikipedia, documentation, articles.
+ *
+ * @example
+ * ```ts
+ * import { fetchUrl } from '@blinkdotnew/react'
+ *
+ * const chat = useAgent({
+ *   agent: {
+ *     model: 'openai/gpt-4o',
+ *     tools: [fetchUrl]
+ *   }
+ * })
+ * ```
+ */
+declare const fetchUrl: AgentTool;
+/**
+ * Python code interpreter for AI-generated scripts
+ *
+ * Executes Python code in an isolated E2B sandbox with Python 3.11+.
+ * Pre-installed libraries: numpy, pandas, matplotlib, scipy, scikit-learn, requests.
+ * Safe for running untrusted LLM-generated code.
+ *
+ * Returns:
+ * - text: Last expression result
+ * - stdout/stderr: Standard output streams
+ * - results: Rich outputs (matplotlib plots as PNG/JPEG, HTML, Markdown, etc.)
+ * - error: Execution errors with traceback
+ *
+ * Matplotlib plots are automatically captured and returned as base64 PNG images
+ * in the results array. Use plt.show() or display(plt.gcf()) to generate plots.
+ *
+ * @example
+ * ```ts
+ * import { runCode } from '@blinkdotnew/react'
+ *
+ * const chat = useAgent({
+ *   agent: {
+ *     model: 'openai/gpt-4o',
+ *     tools: [runCode]
+ *   }
+ * })
+ *
+ * // Agent can create data visualizations:
+ * // "Create a bar chart of sales data"
+ * // "Plot a sine wave"
+ * // "Analyze this CSV and show trends"
+ * ```
+ */
+declare const runCode: AgentTool;
+
+/**
+ * Sandbox Tools (Cursor-like)
+ *
+ * File and command execution tools for AI coding agents.
+ * Modeled after Cursor IDE tools for familiar DX.
+ *
+ * Tools access `sandboxId` from context (NOT input params).
+ */
+
+/**
+ * Read file contents from sandbox
+ * Cursor equivalent: read_file
+ */
+declare const readFile: AgentTool;
+/**
+ * List files and directories
+ * Cursor equivalent: list_dir
+ */
+declare const listDir: AgentTool;
+/**
+ * Create/overwrite a file in sandbox
+ * Cursor equivalent: write
+ *
+ * ⚠️ WARNING: Use search_replace for existing files!
+ */
+declare const writeFile: AgentTool;
+/**
+ * Search and replace in files (PREFERRED editing tool)
+ * Cursor equivalent: search_replace
+ */
+declare const searchReplace: AgentTool;
+/**
+ * Regex content search using ripgrep
+ * Cursor equivalent: grep
+ */
+declare const grep: AgentTool;
+/**
+ * Find files by name pattern
+ * Cursor equivalent: glob_file_search
+ */
+declare const globFileSearch: AgentTool;
+/**
+ * Execute shell command in sandbox
+ * Cursor equivalent: run_terminal_cmd
+ */
+declare const runTerminalCmd: AgentTool;
+/**
+ * Get public URL for a port in sandbox
+ */
+declare const getHost: AgentTool;
+/**
+ * All sandbox tools bundled together (Cursor-like)
+ *
+ * @example
+ * ```ts
+ * import { sandboxTools, Agent } from '@blinkdotnew/sdk'
+ *
+ * const codingAgent = new Agent({
+ *   model: 'anthropic/claude-sonnet-4-20250514',
+ *   tools: sandboxTools,
+ * })
+ *
+ * // Tools include:
+ * // - read_file, list_dir
+ * // - write_file, search_replace
+ * // - grep, glob_file_search
+ * // - run_terminal_cmd, get_host
+ * ```
+ */
+declare const sandboxTools: AgentTool[];
+
+/**
+ * Database Tools
+ *
+ * RLS-enforced database operations for AI agents.
+ * Automatically scoped to the authenticated user.
+ */
+
+/**
+ * Insert a new row into a database table
+ *
+ * RLS automatically sets user_id from JWT.
+ */
+declare const dbInsert: AgentTool;
+/**
+ * List rows from a database table with filtering and pagination
+ *
+ * RLS ensures only the user's rows are returned.
+ */
+declare const dbList: AgentTool;
+/**
+ * Get a single row by ID
+ *
+ * RLS ensures only the user's rows can be retrieved.
+ */
+declare const dbGet: AgentTool;
+/**
+ * Update a row by ID
+ *
+ * RLS ensures only the user's rows can be updated.
+ */
+declare const dbUpdate: AgentTool;
+/**
+ * Delete a row by ID
+ *
+ * RLS ensures only the user's rows can be deleted.
+ */
+declare const dbDelete: AgentTool;
+/**
+ * All database tools bundled together
+ *
+ * @example
+ * ```ts
+ * import { dbTools } from '@blinkdotnew/react'
+ *
+ * const chat = useAgent({
+ *   agent: {
+ *     model: 'openai/gpt-4o',
+ *     tools: [...dbTools]
+ *   }
+ * })
+ * ```
+ */
+declare const dbTools: AgentTool[];
+
+/**
+ * Storage Tools
+ *
+ * RLS-enforced file storage operations for AI agents.
+ * Files are stored under project-scoped paths.
+ */
+
+/**
+ * Upload a file to storage
+ *
+ * Accepts base64-encoded content or a URL to fetch from.
+ */
+declare const storageUpload: AgentTool;
+/**
+ * Download file from storage
+ */
+declare const storageDownload: AgentTool;
+/**
+ * List files in storage
+ */
+declare const storageList: AgentTool;
+/**
+ * Delete file from storage
+ */
+declare const storageDelete: AgentTool;
+/**
+ * Get public URL for a file
+ */
+declare const storagePublicUrl: AgentTool;
+/**
+ * Move/rename a file in storage
+ */
+declare const storageMove: AgentTool;
+/**
+ * Copy a file in storage
+ */
+declare const storageCopy: AgentTool;
+/**
+ * All storage tools bundled together
+ *
+ * @example
+ * ```ts
+ * import { storageTools } from '@blinkdotnew/react'
+ *
+ * const chat = useAgent({
+ *   agent: {
+ *     model: 'openai/gpt-4o',
+ *     tools: [...storageTools]
+ *   }
+ * })
+ * ```
+ */
+declare const storageTools: AgentTool[];
+
+/**
+ * RAG Agent Tool
+ *
+ * Knowledge base search tool using TursoRAG.
+ *
+ * NOTE: Only rag_search is available as an agent tool. Agents ARE AI -
+ * they use rag_search to get relevant chunks, then synthesize answers themselves.
+ * The direct API /api/rag/:project_id/ai-search is available for non-agent use cases.
+ */
+
+/**
+ * Vector search across a knowledge base collection
+ *
+ * Performs semantic similarity search to find relevant chunks from uploaded documents.
+ * The agent receives the chunks and synthesizes an answer from them.
+ * Bills for embedding generation (query vectorization).
+ *
+ * @example
+ * ```ts
+ * import { Agent, ragSearch } from '@blinkdotnew/react'
+ *
+ * const supportAgent = new Agent({
+ *   model: 'openai/gpt-4o',
+ *   tools: [ragSearch],
+ *   system: 'You have access to a knowledge base. Use rag_search to find information, then answer based on the results.'
+ * })
+ *
+ * const result = await supportAgent.generate({
+ *   prompt: 'What is our refund policy?'
+ * })
+ * ```
+ */
+declare const ragSearch: AgentTool;
+/**
+ * All RAG tools bundled together
+ *
+ * @example
+ * ```ts
+ * import { Agent, ragTools } from '@blinkdotnew/react'
+ *
+ * const knowledgeAgent = new Agent({
+ *   model: 'anthropic/claude-sonnet-4-20250514',
+ *   tools: [...ragTools],
+ *   system: 'Search the knowledge base and answer questions based on the results.'
+ * })
+ * ```
+ */
+declare const ragTools: AgentTool[];
+
+/**
+ * Agent Tools
+ *
+ * Tool definitions for use with blink.ai.agent() and useAgent()
+ *
+ * @example
+ * ```ts
+ * import {
+ *   webSearch, fetchUrl, runCode,                   // Core tools
+ *   ragSearch,                                       // RAG tool
+ *   readFile, listDir, writeFile, searchReplace,   // Sandbox (Cursor-like)
+ *   grep, globFileSearch, runTerminalCmd, getHost,
+ *   sandboxTools, dbTools, storageTools, ragTools  // Tool bundles
+ * } from '@blinkdotnew/react'
+ *
+ * const chat = useAgent({
+ *   agent: {
+ *     model: 'openai/gpt-4o',
+ *     tools: [...sandboxTools, webSearch, ragSearch]
+ *   }
+ * })
+ * ```
+ */
+
+/**
+ * Convert tool definitions to tool names for API request
+ *
+ * @internal Used by SDK to serialize tools for API
+ */
+declare function serializeTools(tools: (AgentTool | string)[]): string[];
+
+export { type AISearchOptions, Agent, type AgentBilling, type AgentConfig, type AgentNonStreamMessagesRequest, type AgentNonStreamPromptRequest, type AgentOptions, type AgentRequest, type AgentResponse, type AgentStep, type AgentStreamRequest, type TokenUsage as AgentTokenUsage, type AgentTool, type AnalyticsEvent, AsyncStorageAdapter, type AuthState, type AuthStateChangeCallback, type AuthTokens, type BlinkAI, BlinkAIImpl, type BlinkAnalytics, BlinkAnalyticsImpl, type BlinkClient, type BlinkClientConfig, BlinkConnectorError, type BlinkConnectors, BlinkConnectorsImpl, type BlinkData, BlinkDataImpl, BlinkDatabase, type BlinkRAG, BlinkRAGImpl, type BlinkRealtime, BlinkRealtimeChannel, BlinkRealtimeError, BlinkRealtimeImpl, type BlinkSandbox, BlinkSandboxImpl, type BlinkStorage, BlinkStorageImpl, BlinkTable, type BlinkTokenType, type BlinkUser, type ClientTool, type ConnectorApiKeyRequest, type ConnectorApiKeyResponse, type ConnectorAuthMode, type ConnectorExecuteRequest, type ConnectorExecuteResponse, type ConnectorProvider, type ConnectorStatusResponse, type ContextPolicy, type CreateCollectionOptions, type CreateOptions, type DataExtraction, type FileObject, type FilterCondition, type GenerateOptions, type ImageGenerationRequest, type ImageGenerationResponse, type JSONSchema, type ListDocumentsOptions, type Message, NoOpStorageAdapter, type ObjectGenerationRequest, type ObjectGenerationResponse, type PresenceUser, type QueryOptions, type RAGAISearchResult, type RAGAISearchSource, type RAGCollection, type RAGDocument, type RAGSearchResponse, type RAGSearchResult, type RealtimeChannel, type RealtimeGetMessagesOptions, type RealtimeMessage, type RealtimePublishOptions, type RealtimeSubscribeOptions, SANDBOX_TEMPLATES, type Sandbox, type SandboxConnectOptions, SandboxConnectionError, type SandboxCreateOptions, type SandboxTemplate, type SearchOptions, type SearchRequest, type SearchResponse, type SpeechGenerationRequest, type SpeechGenerationResponse, type StopCondition, type StorageAdapter, type StorageUploadOptions, type StorageUploadResponse, type StreamOptions, type TableOperations, type TextGenerationRequest, type TextGenerationResponse, type TokenIntrospectionResult, type TokenUsage$1 as TokenUsage, type ToolCall, type ToolResult, type TranscriptionRequest, type TranscriptionResponse, type UIMessage, type UIMessagePart, type UpdateOptions, type UploadOptions, type UpsertOptions, type WaitForReadyOptions, type WebBrowserModule, WebStorageAdapter, type WebhookTool, createClient, dbDelete, dbGet, dbInsert, dbList, dbTools, dbUpdate, fetchUrl, getDefaultStorageAdapter, getHost, globFileSearch, grep, isBrowser, isDeno, isNode, isReactNative, isServer, isWeb, listDir, platform, ragSearch, ragTools, readFile, runCode, runTerminalCmd, sandboxTools, searchReplace, serializeTools, stepCountIs, storageCopy, storageDelete, storageDownload, storageList, storageMove, storagePublicUrl, storageTools, storageUpload, webSearch, writeFile };