@standardagents/builder 0.9.17 → 0.10.1-dev.616ec2e

package/dist/index.d.ts

@@ -305,6 +305,7 @@ interface Message {
     reasoning_details?: string | null;
     parent_id?: string | null;
     depth?: number;
+    attachments?: string | null;
 }
 /**
  * Tool call from OpenAI format
@@ -355,6 +356,12 @@ interface ThreadInstance {
     loadAgent(name: string): Promise<any>;
     getPromptNames(): string[];
     getAgentNames(): string[];
+    insertOrphanedToolCall(params: {
+        content?: string;
+        toolCallId: string;
+        toolName: string;
+        toolArgs: string;
+    }): Promise<Response>;
 }
 /**
  * Tool call for internal flow management
@@ -417,6 +424,8 @@ interface PromptData {
     reasoning_max_tokens: number | null;
     reasoning_exclude: boolean;
     include_reasoning: boolean;
+    maxImagePixels: number | null;
+    recentImageThreshold: number | null;
     _tools?: (string | ToolConfig$1)[];
     _handoffAgents?: string[];
     _requiredSchema?: any;
@@ -480,13 +489,38 @@ interface FlowState {
     pendingMessageId?: string;
     allowedTools?: ToolDefinition[];
 }
+/**
+ * Text content part for multimodal messages
+ */
+interface TextContentPart {
+    type: "text";
+    text: string;
+}
+/**
+ * Image URL content part for multimodal messages (OpenAI/OpenRouter format)
+ */
+interface ImageContentPart {
+    type: "image_url";
+    image_url: {
+        url: string;
+        detail?: "auto" | "low" | "high";
+    };
+}
+/**
+ * Multimodal content - array of text and image parts
+ */
+type MultimodalContent = Array<TextContentPart | ImageContentPart>;
+/**
+ * Message content - can be string (text only) or array (multimodal)
+ */
+type MessageContent = string | MultimodalContent;
 /**
  * Request context for LLM calls
  */
 interface RequestContext {
     messages: Array<{
         role: "system" | "user" | "assistant" | "tool";
-        content?: string;
+        content?: MessageContent;
         tool_calls?: ToolCall[];
         tool_call_id?: string;
         name?: string;
@@ -509,6 +543,7 @@ interface RequestContext {
         max_tokens?: number;
         exclude?: boolean;
     };
+    imagePathMap?: Map<string, string>;
 }
 /**
  * Tool definition for LLM requests
@@ -665,6 +700,82 @@ interface LogData {
     retry_of_log_id?: string | null;
     created_at: number;
 }
+/**
+ * Base environment interface for StandardAgents.
+ * Extends ThreadEnv with optional provider API keys.
+ *
+ * User's Env interface should extend this or include these bindings.
+ */
+interface Env extends ThreadEnv {
+    OPENAI_API_KEY?: string;
+    ANTHROPIC_API_KEY?: string;
+    OPENROUTER_API_KEY?: string;
+    GOOGLE_API_KEY?: string;
+    UI_DEV_SERVER?: string;
+    ASSETS?: {
+        fetch(request: Request | string): Promise<Response>;
+    };
+    GITHUB_TOKEN?: string;
+    GITHUB_REPO?: string;
+    GITHUB_BRANCH?: string;
+    SUPER_ADMIN_PASSWORD?: string;
+    ENCRYPTION_KEY?: string;
+    [key: string]: unknown;
+}
+/**
+ * Storage backend types for files
+ */
+type StorageBackend = "local" | "url" | "s3" | "r2";
+/**
+ * File record stored in the files table
+ */
+interface FileRecord {
+    path: string;
+    name: string;
+    mimeType: string;
+    storage: StorageBackend;
+    location?: string | null;
+    size: number;
+    metadata?: Record<string, unknown> | null;
+    isDirectory: boolean;
+    createdAt: number;
+}
+/**
+ * Image-specific metadata stored in FileRecord.metadata
+ */
+interface ImageMetadata {
+    width: number;
+    height: number;
+}
+/**
+ * Attachment reference stored in messages.attachments (JSON array)
+ */
+interface AttachmentRef {
+    id: string;
+    type: "file";
+    path: string;
+    name: string;
+    mimeType: string;
+    width?: number;
+    height?: number;
+    description?: string;
+}
+/**
+ * Grep search result
+ */
+interface GrepResult {
+    path: string;
+    name: string;
+    matches: string[];
+    lineNumbers?: number[];
+}
+/**
+ * File stats for storage tracking
+ */
+interface FileStats {
+    totalSize: number;
+    fileCount: number;
+}
 
 /**
  * Minimum required environment bindings for thread endpoints.
@@ -879,7 +990,7 @@ declare class DurableThread<Env extends ThreadEnv = ThreadEnv> extends DurableOb
      * Send a new message to the thread (RPC method)
      * Enqueues the message processing to be handled by the alarm handler
      */
-    sendMessage(threadId: string, content: string, role?: string): Promise<Response>;
+    sendMessage(threadId: string, content: string, role?: string, attachments?: string): Promise<Response>;
     /**
      * Check if execution should be stopped (called by FlowEngine)
      * Reads from SQLite for persistence across hibernation
@@ -926,6 +1037,7 @@ declare class DurableThread<Env extends ThreadEnv = ThreadEnv> extends DurableOb
             status: "pending" | "completed" | "failed" | null;
             reasoning_content: string | null;
             reasoning_details: string | null;
+            attachments: any;
         }[];
         total: number;
         hasMore: boolean;
@@ -1074,6 +1186,8 @@ declare class DurableThread<Env extends ThreadEnv = ThreadEnv> extends DurableOb
             id: any;
             title: any;
             type: any;
+            description: any;
+            icon: any;
             side_a_label: any;
             side_b_label: any;
         } | null;
@@ -1212,6 +1326,220 @@ declare class DurableThread<Env extends ThreadEnv = ThreadEnv> extends DurableOb
      * Internal method called by alarm queue
      */
     private testOperation;
+    /**
+     * Get file storage helper instance
+     */
+    private getFileStorage;
+    /**
+     * Write a file to storage (RPC method)
+     */
+    writeFile(path: string, data: string, // base64 encoded
+    mimeType: string, options?: {
+        metadata?: Record<string, unknown>;
+        thumbnail?: string;
+    }): Promise<{
+        success: boolean;
+        file: any;
+        error?: undefined;
+    } | {
+        success: boolean;
+        error: any;
+        file?: undefined;
+    }>;
+    /**
+     * Write a text file to storage (RPC method)
+     */
+    writeTextFile(path: string, content: string, mimeType?: string, options?: {
+        metadata?: Record<string, unknown>;
+    }): Promise<{
+        success: boolean;
+        file: any;
+        error?: undefined;
+    } | {
+        success: boolean;
+        error: any;
+        file?: undefined;
+    }>;
+    /**
+     * Process an image using sip (WASM-based image processing)
+     * This runs inside the DO where WASM is properly initialized.
+     *
+     * @param data - base64 encoded image data
+     * @param mimeType - MIME type of the input image
+     * @returns Processed image data, dimensions, and mimeType
+     */
+    processImage(data: string, mimeType: string): Promise<{
+        success: boolean;
+        data?: string;
+        mimeType?: string;
+        width?: number;
+        height?: number;
+        error?: string;
+    }>;
+    /**
+     * Link to an external file (RPC method)
+     */
+    linkFile(path: string, location: string, options?: {
+        mimeType?: string;
+        size?: number;
+        metadata?: Record<string, unknown>;
+    }): Promise<{
+        success: boolean;
+        file: any;
+        error?: undefined;
+    } | {
+        success: boolean;
+        error: any;
+        file?: undefined;
+    }>;
+    /**
+     * Read a file from storage (RPC method)
+     * Returns base64-encoded data
+     */
+    readFile(path: string): Promise<{
+        success: boolean;
+        data: string;
+        error?: undefined;
+    } | {
+        success: boolean;
+        error: any;
+        data?: undefined;
+    }>;
+    /**
+     * Read a text file from storage (RPC method)
+     */
+    readTextFile(path: string): Promise<{
+        success: boolean;
+        content: any;
+        error?: undefined;
+    } | {
+        success: boolean;
+        error: any;
+        content?: undefined;
+    }>;
+    /**
+     * Get file metadata (RPC method)
+     */
+    statFile(path: string): Promise<{
+        success: boolean;
+        file: any;
+        error?: undefined;
+    } | {
+        success: boolean;
+        error: any;
+        file?: undefined;
+    }>;
+    /**
+     * Check if file exists (RPC method)
+     */
+    fileExists(path: string): Promise<{
+        success: boolean;
+        exists: any;
+        error?: undefined;
+    } | {
+        success: boolean;
+        error: any;
+        exists?: undefined;
+    }>;
+    /**
+     * Delete a file (RPC method)
+     */
+    unlinkFile(path: string): Promise<{
+        success: boolean;
+        error?: undefined;
+    } | {
+        success: boolean;
+        error: any;
+    }>;
+    /**
+     * Create a directory (RPC method)
+     */
+    mkdirFile(path: string): Promise<{
+        success: boolean;
+        directory: any;
+        error?: undefined;
+    } | {
+        success: boolean;
+        error: any;
+        directory?: undefined;
+    }>;
+    /**
+     * List directory contents (RPC method)
+     */
+    readdirFile(path: string): Promise<{
+        success: boolean;
+        files: any;
+        error?: undefined;
+    } | {
+        success: boolean;
+        error: any;
+        files?: undefined;
+    }>;
+    /**
+     * Remove empty directory (RPC method)
+     */
+    rmdirFile(path: string): Promise<{
+        success: boolean;
+        error?: undefined;
+    } | {
+        success: boolean;
+        error: any;
+    }>;
+    /**
+     * Get file storage statistics (RPC method)
+     */
+    getFileStats(): Promise<{
+        success: boolean;
+        stats: any;
+        error?: undefined;
+    } | {
+        success: boolean;
+        error: any;
+        stats?: undefined;
+    }>;
+    /**
+     * Get thumbnail for an image (RPC method)
+     * Returns base64-encoded data
+     */
+    getFileThumbnail(path: string): Promise<{
+        success: boolean;
+        data: string;
+        error?: undefined;
+    } | {
+        success: boolean;
+        error: any;
+        data?: undefined;
+    }>;
+    /**
+     * Search file contents using FTS5 (RPC method)
+     */
+    grepFiles(pattern: string, options?: {
+        path?: string;
+        limit?: number;
+    }): Promise<{
+        success: boolean;
+        results: any;
+        error?: undefined;
+    } | {
+        success: boolean;
+        error: any;
+        results?: undefined;
+    }>;
+    /**
+     * Find files by path pattern (RPC method)
+     */
+    findFiles(pattern: string, options?: {
+        type?: "file" | "directory" | "all";
+        limit?: number;
+    }): Promise<{
+        success: boolean;
+        files: any;
+        error?: undefined;
+    } | {
+        success: boolean;
+        error: any;
+        files?: undefined;
+    }>;
 }
 
 /**
@@ -1627,6 +1955,26 @@ interface ModelDefinition<N extends string = string> {
      * Some providers offer reduced pricing for cached/repeated prompts.
      */
     cachedPrice?: number;
+    /**
+     * Model capabilities - features this model supports.
+     */
+    capabilities?: {
+        /**
+         * Whether the model supports vision (image understanding).
+         * When true, image attachments will be sent to the model as part of the request.
+         * Models like GPT-4o, Claude 3, and Gemini support vision.
+         */
+        vision?: boolean;
+        /**
+         * Whether the model supports function calling (tool use).
+         * Most modern models support this, defaults to true if not specified.
+         */
+        functionCalling?: boolean;
+        /**
+         * Whether the model supports structured outputs (JSON mode).
+         */
+        structuredOutputs?: boolean;
+    };
 }
 /**
  * Defines an LLM model configuration.
@@ -1972,6 +2320,49 @@ interface PromptDefinition<N extends string = string, S extends z.ZodTypeAny = z
      * Configure effort level, token limits, and visibility of reasoning.
      */
     reasoning?: ReasoningConfig;
+    /**
+     * Maximum pixels for image attachments before client-side resize.
+     * Images exceeding this limit are scaled down while preserving aspect ratio.
+     * Images smaller than this limit are not resized up.
+     *
+     * Common values:
+     * - 262144 (256K): 512x512 equivalent - thumbnails, low cost
+     * - 1048576 (1M): 1024x1024 equivalent - good quality (default)
+     * - 2073600 (2M): 1440x1440 equivalent - high quality
+     * - 4194304 (4M): 2048x2048 equivalent - maximum detail
+     *
+     * @default 1048576 (1M pixels, ~1024x1024)
+     *
+     * @example
+     * ```typescript
+     * // High quality images for detailed analysis
+     * maxImagePixels: 2073600
+     *
+     * // Lower quality for cost-sensitive applications
+     * maxImagePixels: 262144
+     * ```
+     */
+    maxImagePixels?: number;
+    /**
+     * Number of recent messages to keep actual images for in context.
+     * Messages older than this threshold will have their images replaced
+     * with text descriptions to save context window space.
+     *
+     * This helps manage context window usage in long conversations with
+     * many image attachments by summarizing older images.
+     *
+     * @default 10
+     *
+     * @example
+     * ```typescript
+     * // Keep more images in context for image-heavy workflows
+     * recentImageThreshold: 20
+     *
+     * // Aggressively summarize to save context
+     * recentImageThreshold: 5
+     * ```
+     */
+    recentImageThreshold?: number;
 }
 /**
  * Helper type to extract the inferred input type from a prompt's Zod schema.
@@ -2184,6 +2575,20 @@ interface AgentDefinition<N extends string = string> {
      * @example ['customer-service', 'tier-1', 'english']
      */
     tags?: string[];
+    /**
+     * Brief description of what this agent does.
+     * Useful for UIs and documentation.
+     *
+     * @example 'Handles customer support inquiries and resolves issues'
+     */
+    description?: string;
+    /**
+     * Icon URL or absolute path for the agent.
+     * Absolute paths (starting with `/`) are converted to full URLs in API responses.
+     *
+     * @example 'https://example.com/icon.svg' or '/icons/support.svg'
+     */
+    icon?: string;
 }
 /**
  * Defines an agent configuration.
@@ -2608,6 +3013,327 @@ declare function updateThread(thread: ThreadContext, params: {
     tags: string[];
     created_at: number;
 } | null>;
+/**
+ * Write a file to thread storage
+ *
+ * @param flow - The current FlowState
+ * @param path - File path (e.g., "/images/photo.jpg")
+ * @param data - File data as ArrayBuffer or string
+ * @param mimeType - MIME type of the file
+ * @param options - Optional metadata and thumbnail
+ * @returns The created file record
+ *
+ * @example
+ * ```typescript
+ * import { writeFile } from '@standardagents/builder';
+ *
+ * // Write binary file
+ * const imageData = new Uint8Array([...]);
+ * await writeFile(flow, "/images/photo.jpg", imageData.buffer, "image/jpeg");
+ *
+ * // Write text file
+ * await writeFile(flow, "/docs/readme.md", "# Hello", "text/markdown");
+ * ```
+ */
+declare function writeFile(flow: FlowState, path: string, data: ArrayBuffer | string, mimeType: string, options?: {
+    metadata?: Record<string, unknown>;
+    thumbnail?: ArrayBuffer;
+}): Promise<FileRecord>;
+/**
+ * Write an image file with optional thumbnail
+ *
+ * @param flow - The current FlowState
+ * @param path - File path
+ * @param data - Image data as ArrayBuffer
+ * @param mimeType - Image MIME type
+ * @param options - Image metadata (width, height) and optional thumbnail
+ * @returns The created file record
+ *
+ * @example
+ * ```typescript
+ * import { writeImage } from '@standardagents/builder';
+ *
+ * await writeImage(flow, "/images/photo.jpg", imageBuffer, "image/jpeg", {
+ *   metadata: { width: 1024, height: 768 },
+ *   thumbnail: thumbnailBuffer
+ * });
+ * ```
+ */
+declare function writeImage(flow: FlowState, path: string, data: ArrayBuffer, mimeType: string, options?: {
+    metadata?: {
+        width: number;
+        height: number;
+        [key: string]: unknown;
+    };
+    thumbnail?: ArrayBuffer;
+}): Promise<FileRecord>;
+/**
+ * Link to an external file (URL, S3, R2)
+ *
+ * Creates a file entry pointing to an external location without storing the data locally.
+ *
+ * @param flow - The current FlowState
+ * @param path - File path in thread storage
+ * @param location - External location (https://, s3://, r2://)
+ * @param options - Optional MIME type, size, and metadata
+ * @returns The created file record
+ *
+ * @example
+ * ```typescript
+ * import { linkFile } from '@standardagents/builder';
+ *
+ * // Link to a URL
+ * await linkFile(flow, "/images/hero.jpg", "https://cdn.example.com/hero.jpg");
+ *
+ * // Link to S3
+ * await linkFile(flow, "/data/large.csv", "s3://mybucket/data/large.csv", {
+ *   mimeType: "text/csv",
+ *   size: 10 * 1024 * 1024 * 1024 // 10GB
+ * });
+ * ```
+ */
+declare function linkFile(flow: FlowState, path: string, location: string, options?: {
+    mimeType?: string;
+    size?: number;
+    metadata?: Record<string, unknown>;
+}): Promise<FileRecord>;
+/**
+ * Read a file from thread storage
+ *
+ * @param flow - The current FlowState
+ * @param path - File path
+ * @returns File data as ArrayBuffer, or null if not found/external
+ *
+ * @example
+ * ```typescript
+ * import { readFile } from '@standardagents/builder';
+ *
+ * const data = await readFile(flow, "/images/photo.jpg");
+ * if (data) {
+ *   // Process binary data
+ * }
+ * ```
+ */
+declare function readFile(flow: FlowState, path: string): Promise<ArrayBuffer | null>;
+/**
+ * Get file metadata
+ *
+ * @param flow - The current FlowState
+ * @param path - File path
+ * @returns File record or null if not found
+ *
+ * @example
+ * ```typescript
+ * import { stat } from '@standardagents/builder';
+ *
+ * const file = await stat(flow, "/images/photo.jpg");
+ * if (file) {
+ *   console.log(`Size: ${file.size}, Type: ${file.mimeType}`);
+ * }
+ * ```
+ */
+declare function stat(flow: FlowState, path: string): Promise<FileRecord | null>;
+/**
+ * Check if file or directory exists
+ *
+ * @param flow - The current FlowState
+ * @param path - File path
+ * @returns true if exists, false otherwise
+ *
+ * @example
+ * ```typescript
+ * import { exists } from '@standardagents/builder';
+ *
+ * if (await exists(flow, "/config.json")) {
+ *   // File exists
+ * }
+ * ```
+ */
+declare function exists(flow: FlowState, path: string): Promise<boolean>;
+/**
+ * Delete a file
+ *
+ * @param flow - The current FlowState
+ * @param path - File path
+ *
+ * @example
+ * ```typescript
+ * import { unlink } from '@standardagents/builder';
+ *
+ * await unlink(flow, "/temp/draft.txt");
+ * ```
+ */
+declare function unlink(flow: FlowState, path: string): Promise<void>;
+/**
+ * Create a directory
+ *
+ * @param flow - The current FlowState
+ * @param path - Directory path
+ * @returns The created directory record
+ *
+ * @example
+ * ```typescript
+ * import { mkdir } from '@standardagents/builder';
+ *
+ * await mkdir(flow, "/uploads/2024");
+ * ```
+ */
+declare function mkdir(flow: FlowState, path: string): Promise<FileRecord>;
+/**
+ * List directory contents
+ *
+ * @param flow - The current FlowState
+ * @param path - Directory path
+ * @returns Array of file records in the directory
+ *
+ * @example
+ * ```typescript
+ * import { readdir } from '@standardagents/builder';
+ *
+ * const files = await readdir(flow, "/images");
+ * for (const file of files) {
+ *   console.log(file.name, file.size);
+ * }
+ * ```
+ */
+declare function readdir(flow: FlowState, path: string): Promise<FileRecord[]>;
+/**
+ * Remove an empty directory
+ *
+ * @param flow - The current FlowState
+ * @param path - Directory path
+ *
+ * @example
+ * ```typescript
+ * import { rmdir } from '@standardagents/builder';
+ *
+ * await rmdir(flow, "/temp");
+ * ```
+ */
+declare function rmdir(flow: FlowState, path: string): Promise<void>;
+/**
+ * Get file storage statistics
+ *
+ * @param flow - The current FlowState
+ * @returns Storage statistics (total size and file count)
+ *
+ * @example
+ * ```typescript
+ * import { getFileStats } from '@standardagents/builder';
+ *
+ * const stats = await getFileStats(flow);
+ * console.log(`Total: ${stats.totalSize} bytes, Files: ${stats.fileCount}`);
+ * ```
+ */
+declare function getFileStats(flow: FlowState): Promise<FileStats>;
+/**
+ * Get thumbnail for an image file
+ *
+ * @param flow - The current FlowState
+ * @param path - Image file path
+ * @returns Thumbnail data as ArrayBuffer, or null if not found
+ *
+ * @example
+ * ```typescript
+ * import { getThumbnail } from '@standardagents/builder';
+ *
+ * const thumb = await getThumbnail(flow, "/images/photo.jpg");
+ * ```
+ */
+declare function getThumbnail(flow: FlowState, path: string): Promise<ArrayBuffer | null>;
+/**
+ * Read a text file as string
+ *
+ * @param flow - The current FlowState
+ * @param path - File path
+ * @returns File content as string, or null if not found
+ *
+ * @example
+ * ```typescript
+ * import { cat } from '@standardagents/builder';
+ *
+ * const content = await cat(flow, "/docs/readme.md");
+ * ```
+ */
+declare function cat(flow: FlowState, path: string): Promise<string | null>;
+/**
+ * Read first N lines of a text file
+ *
+ * @param flow - The current FlowState
+ * @param path - File path
+ * @param lines - Number of lines to read (default: 10)
+ * @returns First N lines as string, or null if not found
+ *
+ * @example
+ * ```typescript
+ * import { head } from '@standardagents/builder';
+ *
+ * const firstLines = await head(flow, "/logs/app.log", 20);
+ * ```
+ */
+declare function head(flow: FlowState, path: string, lines?: number): Promise<string | null>;
+/**
+ * Read last N lines of a text file
+ *
+ * @param flow - The current FlowState
+ * @param path - File path
+ * @param lines - Number of lines to read (default: 10)
+ * @returns Last N lines as string, or null if not found
+ *
+ * @example
+ * ```typescript
+ * import { tail } from '@standardagents/builder';
+ *
+ * const lastLines = await tail(flow, "/logs/app.log", 50);
+ * ```
+ */
+declare function tail(flow: FlowState, path: string, lines?: number): Promise<string | null>;
+/**
+ * Search text file contents using FTS5 full-text search
+ *
+ * @param flow - The current FlowState
+ * @param pattern - Search pattern (FTS5 syntax)
+ * @param options - Search options
+ * @returns Array of matching results with snippets
+ *
+ * @example
+ * ```typescript
+ * import { grep } from '@standardagents/builder';
+ *
+ * // Search all files
+ * const results = await grep(flow, "error");
+ *
+ * // Search in specific directory
+ * const results = await grep(flow, "TODO", { path: "/src" });
+ * ```
+ */
+declare function grep(flow: FlowState, pattern: string, options?: {
+    path?: string;
+    limit?: number;
+}): Promise<GrepResult[]>;
+/**
+ * Find files by path pattern
+ *
+ * @param flow - The current FlowState
+ * @param pattern - Glob-like pattern (e.g., "*.md", "/docs/subdir/*.txt")
+ * @param options - Find options
+ * @returns Array of matching file records
+ *
+ * @example
+ * ```typescript
+ * import { find } from '@standardagents/builder';
+ *
+ * // Find all markdown files
+ * const mdFiles = await find(flow, "*.md");
+ *
+ * // Find all files in docs
+ * const docFiles = await find(flow, "/docs/*", { type: "file" });
+ * ```
+ */
+declare function find(flow: FlowState, pattern: string, options?: {
+    type?: "file" | "directory" | "all";
+    limit?: number;
+}): Promise<FileRecord[]>;
 
 /**
  * Options for injecting a message
@@ -2854,6 +3580,67 @@ interface FlowStateWithSdk extends FlowState {
  */
 declare function enhanceFlowState(flow: FlowState): FlowStateWithSdk;
 
+/**
+ * Context Management for Image Attachments
+ *
+ * Handles auto-summarization of old images to reduce context window usage
+ * while preserving the semantic meaning of image content.
+ */
+
+/**
+ * Configuration for image context management
+ */
+interface ImageContextConfig {
+    /** Number of recent messages to keep images for (default: 10) */
+    recentMessageThreshold: number;
+    /** System prompt for generating image descriptions */
+    descriptionPrompt: string;
+}
+/**
+ * Check if a message has image attachments that could be summarized
+ */
+declare function hasImageAttachments(message: Message): boolean;
+/**
+ * Get image attachments from a message that don't have descriptions yet
+ */
+declare function getUnsummarizedImageAttachments(message: Message): AttachmentRef[];
+/**
+ * Determine which messages should have their images replaced with descriptions.
+ * Returns indices of messages that are old enough to be summarized.
+ */
+declare function getMessagesToSummarize(messages: Message[], config?: ImageContextConfig): number[];
+/**
+ * Build text representation for an image attachment (used when image is too old)
+ */
+declare function buildImageDescription(attachment: AttachmentRef): string;
+/**
+ * Transform message content to replace old images with text descriptions.
+ * This modifies the content array for LLM context building.
+ */
+declare function replaceImagesWithDescriptions(content: MessageContent, attachments: AttachmentRef[]): MessageContent;
+/**
+ * Process message history to optimize context window usage.
+ * Old images are replaced with their text descriptions.
+ *
+ * @param messages - Full message history
+ * @param config - Context management configuration
+ * @returns Processed messages with old images replaced by descriptions
+ */
+declare function optimizeImageContext(messages: Message[], config?: ImageContextConfig): Message[];
+/**
+ * Generate a description for an image using a vision model.
+ * This should be called when storing new messages with images.
+ *
+ * Note: This function is a placeholder for the actual LLM call.
+ * The actual implementation would need to make an API call to a vision model.
+ *
+ * @param imageBase64 - Base64-encoded image data
+ * @param mimeType - MIME type of the image
+ * @param state - Flow state for LLM access
+ * @returns Generated description
+ */
+declare function generateImageDescription(_imageBase64: string, _mimeType: string, _state: FlowState): Promise<string | null>;
+
 /**
  * Types for GitHub REST API integration.
  */
@@ -3022,4 +3809,4 @@ declare class GitHubApiError extends Error {
     constructor(message: string, status: number, details?: unknown);
 }
 
-export { type Agent, type AgentBuilderEnv, type AgentDefinition, type AgentType, type AuthContext, type AuthUser, type BroadcastOptions, type Controller, type ControllerContext, DurableAgentBuilder, DurableThread, type FlowResult, type FlowState, FlowStateSdk, type FlowStateWithSdk, GitHubApiError, GitHubClient, type GitHubCommitResult, type GitHubConfig, type GitHubFileChange, type HookSignatures, type ImageContent, type InjectMessageOptions$1 as InjectMessageOptions, type LLMResponse, type Message, type ModelDefinition, type ModelProvider, type PromptContent, type PromptDefinition, type PromptIncludePart, type PromptInput, type PromptPart, type PromptTextPart, type Provider, type ReasoningConfig, type RequestContext, type SideConfig, type StructuredPrompt, type StructuredToolReturn, type TelemetryEvent, type TextContent, type ThreadEndpointContext, type ThreadEnv, type ThreadInstance, type ThreadMetadata, type ThreadRegistryEntry, type Tool, type ToolArgs, type ToolArgsNode, type ToolArgsRawShape, type ToolCall, type ToolConfig, type ToolContent, type ToolResult, type UpdateThreadParams, type User, authenticate, defineAgent, defineController, defineHook, defineModel, definePrompt, defineThreadEndpoint, defineTool, emitThreadEvent, enhanceFlowState, forceTurn, generateAgentFile, generateModelFile, generatePromptFile, getMessages, injectMessage, queueTool, reloadHistory, requireAdmin, requireAuth, updateThread };
+export { type Agent, type AgentBuilderEnv, type AgentDefinition, type AgentType, type AttachmentRef, type AuthContext, type AuthUser, type BroadcastOptions, type Controller, type ControllerContext, DurableAgentBuilder, DurableThread, type Env, type FileRecord, type FileStats, type FlowResult, type FlowState, FlowStateSdk, type FlowStateWithSdk, GitHubApiError, GitHubClient, type GitHubCommitResult, type GitHubConfig, type GitHubFileChange, type GrepResult, type HookSignatures, type ImageContent, type ImageContentPart, type ImageContextConfig, type ImageMetadata, type InjectMessageOptions$1 as InjectMessageOptions, type LLMResponse, type Message, type MessageContent, type ModelDefinition, type ModelProvider, type MultimodalContent, type PromptContent, type PromptDefinition, type PromptIncludePart, type PromptInput, type PromptPart, type PromptTextPart, type Provider, type ReasoningConfig, type RequestContext, type SideConfig, type StorageBackend, type StructuredPrompt, type StructuredToolReturn, type TelemetryEvent, type TextContent, type TextContentPart, type ThreadEndpointContext, type ThreadEnv, type ThreadInstance, type ThreadMetadata, type ThreadRegistryEntry, type Tool, type ToolArgs, type ToolArgsNode, type ToolArgsRawShape, type ToolCall, type ToolConfig, type ToolContent, type ToolResult, type UpdateThreadParams, type User, authenticate, buildImageDescription, cat, defineAgent, defineController, defineHook, defineModel, definePrompt, defineThreadEndpoint, defineTool, emitThreadEvent, enhanceFlowState, exists, find, forceTurn, generateAgentFile, generateImageDescription, generateModelFile, generatePromptFile, getFileStats, getMessages, getMessagesToSummarize, getThumbnail, getUnsummarizedImageAttachments, grep, hasImageAttachments, head, injectMessage, linkFile, mkdir, optimizeImageContext, queueTool, readFile, readdir, reloadHistory, replaceImagesWithDescriptions, requireAdmin, requireAuth, rmdir, stat, tail, unlink, updateThread, writeFile, writeImage };