@blinkdotnew/dev-sdk 2.2.3 → 2.3.1

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,8 +811,38 @@ 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' | 'google_slides' | 'google_docs' | 'google_sheets' | 'slack' | 'linkedin' | 'hubspot' | 'ai';
+type ConnectorProvider = 'discord' | 'notion' | 'google_drive' | 'google_calendar' | 'ai';
 type ConnectorAuthMode = 'oauth' | 'api_key' | 'blink_managed' | 'hybrid';
 interface ConnectorStatusData {
     connected: boolean;
@@ -1036,6 +1071,94 @@ 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>;
+    /**
+     * RAG AI Search streaming request
+     * Returns raw Response for SSE streaming
+     */
+    ragAiSearchStream(body: {
+        collection_id?: string;
+        collection_name?: string;
+        query: string;
+        model?: string;
+        max_context_chunks?: number;
+        score_threshold?: number;
+        system_prompt?: string;
+        stream: true;
+    }, signal?: AbortSignal): Promise<Response>;
     /**
      * Data-specific requests
      */
@@ -1477,6 +1600,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
      */
@@ -1827,11 +1988,348 @@ 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;
+    /** AbortSignal for cancellation (streaming only) */
+    signal?: AbortSignal;
+}
+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>;
+    /**
+     * Secret names to inject as environment variables.
+     * Secrets are resolved server-side from project secrets vault.
+     * Add secrets via Workspace > Secrets or request_secret tool.
+     * @example ['ANTHROPIC_API_KEY', 'GITHUB_TOKEN']
+     */
+    secrets?: 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
  */
 
+/**
+ * Get the default Blink client instance.
+ * Returns the client created by createClient().
+ *
+ * @throws Error if createClient() hasn't been called yet
+ * @returns The default BlinkClient instance
+ *
+ * @example
+ * ```ts
+ * // First, create client somewhere in your app
+ * createClient({ projectId: '...', secretKey: '...' })
+ *
+ * // Later, get the default client
+ * const client = getDefaultClient()
+ * ```
+ */
+declare function getDefaultClient(): BlinkClientImpl;
 interface BlinkClient {
     auth: BlinkAuth;
     db: BlinkDatabase;
@@ -1843,9 +2341,42 @@ interface BlinkClient {
     analytics: BlinkAnalytics;
     connectors: BlinkConnectors;
     functions: BlinkFunctions;
+    rag: BlinkRAG;
+    sandbox: BlinkSandbox;
+}
+declare class BlinkClientImpl implements BlinkClient {
+    auth: BlinkAuth;
+    db: BlinkDatabase;
+    storage: BlinkStorage;
+    ai: BlinkAI;
+    data: BlinkData;
+    realtime: BlinkRealtime;
+    notifications: BlinkNotifications;
+    analytics: BlinkAnalytics;
+    connectors: BlinkConnectors;
+    functions: BlinkFunctions;
+    rag: BlinkRAG;
+    sandbox: BlinkSandbox;
+    /** @internal HTTP client for Agent auto-binding */
+    _httpClient: HttpClient;
+    constructor(config: BlinkClientConfig);
 }
 /**
- * Create a new Blink client instance
+ * Create a new Blink client instance.
+ * This also sets the default client for Agent auto-binding.
+ *
+ * @example
+ * ```ts
+ * // Create client (call once in your app)
+ * const blink = createClient({
+ *   projectId: 'my-project',
+ *   secretKey: 'sk_...',
+ * })
+ *
+ * // Now Agent works without explicit binding
+ * const agent = new Agent({ model: 'openai/gpt-4o' })
+ * await agent.generate({ prompt: 'Hello!' })
+ * ```
  */
 declare function createClient(config: BlinkClientConfig): BlinkClient;
 
@@ -1944,6 +2475,372 @@ declare class BlinkStorageImpl implements BlinkStorage {
     remove(...paths: string[]): Promise<void>;
 }
 
+/**
+ * Agent Tool Types
+ *
+ * Type definitions for AI agent tools used with blink.ai.agent()
+ */
+/**
+ * JSON Schema type for tool input definitions
+ */
+type JSONSchema = Record<string, any>;
+/**
+ * A custom webhook tool definition
+ *
+ * Webhook tools NEED schemas because the server forwards them to your endpoint.
+ */
+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
+ *
+ * Client tools NEED schemas so the AI knows what inputs to provide.
+ */
+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) */
+    tools?: 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
+ *
+ * Auto-binds to default client when createClient() has been called.
+ */
+
+/**
+ * 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 (tool names) */
+    tools?: 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
+ *
+ * **Auto-binding:** After calling `createClient()`, agents automatically
+ * bind to the default client. No need for `blink.ai.createAgent()`.
+ *
+ * @example
+ * ```ts
+ * import { createClient, Agent, webSearch } from '@blinkdotnew/sdk'
+ *
+ * // Initialize client once
+ * createClient({ projectId: '...', secretKey: '...' })
+ *
+ * // Create agent - auto-binds to default client
+ * const weatherAgent = new Agent({
+ *   model: 'anthropic/claude-sonnet-4-20250514',
+ *   system: 'You are a helpful weather assistant.',
+ *   tools: [webSearch],
+ *   maxSteps: 10,
+ * })
+ *
+ * // Works immediately - no binding needed!
+ * const result = await weatherAgent.generate({
+ *   prompt: 'What is the weather in San Francisco?',
+ * })
+ * console.log(result.text)
+ * ```
+ */
+declare class Agent {
+    private httpClient;
+    private readonly config;
+    /**
+     * Create a new Agent instance.
+     * Auto-binds to default client if createClient() was called.
+     *
+     * @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(): 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
@@ -2484,6 +3381,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;
 }
 
 /**
@@ -2578,4 +3579,147 @@ declare class BlinkConnectorsImpl implements BlinkConnectors {
     saveApiKey<TMetadata = Record<string, unknown>>(provider: ConnectorProvider, request: ConnectorApiKeyRequest<TMetadata>): Promise<ConnectorApiKeyResponse>;
 }
 
-export { 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 BlinkRealtime, BlinkRealtimeChannel, BlinkRealtimeError, BlinkRealtimeImpl, type BlinkStorage, BlinkStorageImpl, BlinkTable, type BlinkUser, type ConnectorApiKeyRequest, type ConnectorApiKeyResponse, type ConnectorAuthMode, type ConnectorExecuteRequest, type ConnectorExecuteResponse, type ConnectorProvider, type ConnectorStatusResponse, 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 };
+/**
+ * Core Agent Tools
+ *
+ * Tool names for web search, URL fetching, and code execution.
+ * The server has the full schemas - SDK just passes tool names.
+ */
+/** Search the web for current information (Exa AI) */
+declare const webSearch = "web_search";
+/** Fetch URL content as clean text (HTML stripped) */
+declare const fetchUrl = "fetch_url";
+/** Execute Python code in isolated sandbox */
+declare const runCode = "run_code";
+/** Core tools for research agents */
+declare const coreTools: readonly ["web_search", "fetch_url", "run_code"];
+
+/**
+ * Sandbox Tools (Cursor-like)
+ *
+ * Tool names for file and command execution in coding agents.
+ * The server has the full schemas - SDK just passes tool names.
+ */
+/** Read file contents from sandbox */
+declare const readFile = "read_file";
+/** List files and directories */
+declare const listDir = "list_dir";
+/** Create/overwrite a file (use search_replace for existing files!) */
+declare const writeFile = "write_file";
+/** Search and replace in files (PREFERRED for editing) */
+declare const searchReplace = "search_replace";
+/** Regex content search using ripgrep */
+declare const grep = "grep";
+/** Find files by name pattern */
+declare const globFileSearch = "glob_file_search";
+/** Execute shell command in sandbox */
+declare const runTerminalCmd = "run_terminal_cmd";
+/** Get public URL for a sandbox port */
+declare const getHost = "get_host";
+/** All sandbox tools for coding agents */
+declare const sandboxTools: readonly ["read_file", "list_dir", "write_file", "search_replace", "grep", "glob_file_search", "run_terminal_cmd", "get_host"];
+
+/**
+ * Database Tools
+ *
+ * Tool names for RLS-enforced database operations.
+ * The server has the full schemas - SDK just passes tool names.
+ */
+/** Insert a new row (user_id auto-set via RLS) */
+declare const dbInsert = "db_insert";
+/** List rows with filtering/pagination (RLS enforced) */
+declare const dbList = "db_list";
+/** Get a single row by ID (RLS enforced) */
+declare const dbGet = "db_get";
+/** Update a row by ID (RLS enforced) */
+declare const dbUpdate = "db_update";
+/** Delete a row by ID (RLS enforced) */
+declare const dbDelete = "db_delete";
+/** All database tools */
+declare const dbTools: readonly ["db_insert", "db_list", "db_get", "db_update", "db_delete"];
+
+/**
+ * Storage Tools
+ *
+ * Tool names for file storage operations.
+ * The server has the full schemas - SDK just passes tool names.
+ */
+/** Upload a file (base64 or URL) */
+declare const storageUpload = "storage_upload";
+/** Download file from storage */
+declare const storageDownload = "storage_download";
+/** List files in a directory */
+declare const storageList = "storage_list";
+/** Delete a file */
+declare const storageDelete = "storage_delete";
+/** Get public URL for a file */
+declare const storagePublicUrl = "storage_public_url";
+/** Move/rename a file */
+declare const storageMove = "storage_move";
+/** Copy a file */
+declare const storageCopy = "storage_copy";
+/** All storage tools */
+declare const storageTools: readonly ["storage_upload", "storage_download", "storage_list", "storage_delete", "storage_public_url", "storage_move", "storage_copy"];
+
+/**
+ * RAG Agent Tool
+ *
+ * Tool name for knowledge base search.
+ * The server has the full schema - SDK just passes tool name.
+ */
+/** Search knowledge base using semantic similarity */
+declare const ragSearch = "rag_search";
+/** All RAG tools */
+declare const ragTools: readonly ["rag_search"];
+
+/**
+ * Media Agent Tools
+ *
+ * Tool names for AI image and video generation.
+ * The server has the full schemas - SDK just passes tool names.
+ */
+/** Generate images from text prompts */
+declare const generateImage = "generate_image";
+/** Edit existing images with text prompts */
+declare const editImage = "edit_image";
+/** Generate videos from text prompts */
+declare const generateVideo = "generate_video";
+/** Animate static images into videos */
+declare const imageToVideo = "image_to_video";
+/** All media generation tools */
+declare const mediaTools: readonly ["generate_image", "edit_image", "generate_video", "image_to_video"];
+
+/**
+ * Agent Tools
+ *
+ * Tool names for use with blink.ai.agent() and useAgent()
+ *
+ * Built-in tools are just string names - the server has the schemas.
+ *
+ * @example
+ * ```ts
+ * import {
+ *   webSearch, fetchUrl, runCode,       // Core tools
+ *   ragSearch,                           // RAG tool
+ *   sandboxTools, dbTools, storageTools, // Tool bundles
+ *   mediaTools                           // Media generation
+ * } from '@blinkdotnew/sdk'
+ *
+ * const agent = blink.ai.createAgent({
+ *   model: 'google/gemini-3-flash',
+ *   tools: [...sandboxTools, webSearch, ragSearch]
+ * })
+ * ```
+ */
+
+/**
+ * Convert tools array for API request
+ *
+ * Since tools are now just strings, this is essentially an identity function.
+ * Kept for backward compatibility.
+ *
+ * @internal Used by SDK to serialize tools for API
+ */
+declare function serializeTools(tools: 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 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, coreTools, createClient, dbDelete, dbGet, dbInsert, dbList, dbTools, dbUpdate, editImage, fetchUrl, generateImage, generateVideo, getDefaultClient, getDefaultStorageAdapter, getHost, globFileSearch, grep, imageToVideo, isBrowser, isDeno, isNode, isReactNative, isServer, isWeb, listDir, mediaTools, platform, ragSearch, ragTools, readFile, runCode, runTerminalCmd, sandboxTools, searchReplace, serializeTools, stepCountIs, storageCopy, storageDelete, storageDownload, storageList, storageMove, storagePublicUrl, storageTools, storageUpload, webSearch, writeFile };