@juspay/neurolink 9.5.2 → 9.6.0

package/dist/lib/files/fileTools.d.ts

@@ -0,0 +1,423 @@
+/**
+ * On-Demand File Access Tools
+ *
+ * Exposes file operations as LLM tools via the Vercel AI SDK `tool()` pattern.
+ * These tools allow the LLM to access file content lazily — only reading
+ * the specific sections, lines, or search results it needs.
+ *
+ * Tools:
+ * - list_attached_files: List all registered files with metadata
+ * - read_file_section: Read specific line range with token budget
+ * - search_in_file: Search for patterns within a file
+ * - get_file_preview: Get the preview/summary of a file
+ * - extract_file_content: Targeted extraction for any file type (video frames,
+ *     PDF pages, spreadsheet ranges, archive entries, PPTX slides)
+ *
+ * @module files/fileTools
+ */
+import { z } from "zod";
+import type { FileReferenceRegistry } from "./fileReferenceRegistry.js";
+/**
+ * Create file access tools bound to a FileReferenceRegistry instance.
+ *
+ * These tools follow the same pattern as the existing directAgentTools
+ * (getCurrentTime, readFile, etc.) in src/lib/agent/directTools.ts.
+ * They use `tool()` from the Vercel AI SDK with zod parameter schemas.
+ *
+ * @param registry - The FileReferenceRegistry instance to bind to
+ * @returns Record of tool name to tool definition
+ *
+ * @example
+ * ```typescript
+ * const registry = new FileReferenceRegistry();
+ * const tools = createFileTools(registry);
+ * // tools.list_attached_files, tools.read_file_section, etc.
+ * ```
+ */
+export declare function createFileTools(registry: FileReferenceRegistry): {
+    list_attached_files: import("ai").Tool<z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>, {
+        success: boolean;
+        message: string;
+        fileCount: number;
+        files?: undefined;
+        formatted?: undefined;
+        error?: undefined;
+    } | {
+        success: boolean;
+        fileCount: number;
+        files: {
+            index: number;
+            id: string;
+            filename: string;
+            type: import("../index.js").FileType;
+            size: string;
+            sizeBytes: number;
+            sizeTier: import("./types.js").SizeTier;
+            estimatedTokens: number;
+            status: import("./types.js").FileReferenceStatus;
+            hasPreview: boolean;
+            hasSummary: boolean;
+            totalLines: number | null;
+        }[];
+        formatted: string;
+        message?: undefined;
+        error?: undefined;
+    } | {
+        success: boolean;
+        error: string;
+        message?: undefined;
+        fileCount?: undefined;
+        files?: undefined;
+        formatted?: undefined;
+    }> & {
+        execute: (args: {}, options: import("ai").ToolExecutionOptions) => PromiseLike<{
+            success: boolean;
+            message: string;
+            fileCount: number;
+            files?: undefined;
+            formatted?: undefined;
+            error?: undefined;
+        } | {
+            success: boolean;
+            fileCount: number;
+            files: {
+                index: number;
+                id: string;
+                filename: string;
+                type: import("../index.js").FileType;
+                size: string;
+                sizeBytes: number;
+                sizeTier: import("./types.js").SizeTier;
+                estimatedTokens: number;
+                status: import("./types.js").FileReferenceStatus;
+                hasPreview: boolean;
+                hasSummary: boolean;
+                totalLines: number | null;
+            }[];
+            formatted: string;
+            message?: undefined;
+            error?: undefined;
+        } | {
+            success: boolean;
+            error: string;
+            message?: undefined;
+            fileCount?: undefined;
+            files?: undefined;
+            formatted?: undefined;
+        }>;
+    };
+    read_file_section: import("ai").Tool<z.ZodObject<{
+        file_id: z.ZodString;
+        start_line: z.ZodDefault<z.ZodNumber>;
+        end_line: z.ZodOptional<z.ZodNumber>;
+        token_budget: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        file_id: string;
+        start_line: number;
+        token_budget: number;
+        end_line?: number | undefined;
+    }, {
+        file_id: string;
+        start_line?: number | undefined;
+        end_line?: number | undefined;
+        token_budget?: number | undefined;
+    }>, {
+        success: boolean;
+        error: string;
+        content?: undefined;
+        startLine?: undefined;
+        endLine?: undefined;
+        totalLines?: undefined;
+        truncated?: undefined;
+        estimatedTokens?: undefined;
+        guidance?: undefined;
+    } | {
+        success: boolean;
+        content: string;
+        startLine: number;
+        endLine: number;
+        totalLines: number;
+        truncated: boolean;
+        estimatedTokens: number;
+        guidance: string | undefined;
+        error?: undefined;
+    }> & {
+        execute: (args: {
+            file_id: string;
+            start_line: number;
+            token_budget: number;
+            end_line?: number | undefined;
+        }, options: import("ai").ToolExecutionOptions) => PromiseLike<{
+            success: boolean;
+            error: string;
+            content?: undefined;
+            startLine?: undefined;
+            endLine?: undefined;
+            totalLines?: undefined;
+            truncated?: undefined;
+            estimatedTokens?: undefined;
+            guidance?: undefined;
+        } | {
+            success: boolean;
+            content: string;
+            startLine: number;
+            endLine: number;
+            totalLines: number;
+            truncated: boolean;
+            estimatedTokens: number;
+            guidance: string | undefined;
+            error?: undefined;
+        }>;
+    };
+    search_in_file: import("ai").Tool<z.ZodObject<{
+        file_id: z.ZodString;
+        pattern: z.ZodString;
+        max_matches: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        pattern: string;
+        file_id: string;
+        max_matches: number;
+    }, {
+        pattern: string;
+        file_id: string;
+        max_matches?: number | undefined;
+    }>, {
+        success: boolean;
+        error: string;
+        pattern?: undefined;
+        totalMatches?: undefined;
+        matchesReturned?: undefined;
+        truncated?: undefined;
+        matches?: undefined;
+    } | {
+        success: boolean;
+        pattern: string;
+        totalMatches: number;
+        matchesReturned: number;
+        truncated: boolean;
+        matches: {
+            lineNumber: number;
+            line: string;
+            context: {
+                before: string[];
+                after: string[];
+            } | undefined;
+        }[];
+        error?: undefined;
+    }> & {
+        execute: (args: {
+            pattern: string;
+            file_id: string;
+            max_matches: number;
+        }, options: import("ai").ToolExecutionOptions) => PromiseLike<{
+            success: boolean;
+            error: string;
+            pattern?: undefined;
+            totalMatches?: undefined;
+            matchesReturned?: undefined;
+            truncated?: undefined;
+            matches?: undefined;
+        } | {
+            success: boolean;
+            pattern: string;
+            totalMatches: number;
+            matchesReturned: number;
+            truncated: boolean;
+            matches: {
+                lineNumber: number;
+                line: string;
+                context: {
+                    before: string[];
+                    after: string[];
+                } | undefined;
+            }[];
+            error?: undefined;
+        }>;
+    };
+    get_file_preview: import("ai").Tool<z.ZodObject<{
+        file_id: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        file_id: string;
+    }, {
+        file_id: string;
+    }>, {
+        success: boolean;
+        error: string;
+        filename?: undefined;
+        type?: undefined;
+        size?: undefined;
+        sizeBytes?: undefined;
+        sizeTier?: undefined;
+        mimeType?: undefined;
+        estimatedTokens?: undefined;
+        status?: undefined;
+        totalLines?: undefined;
+        preview?: undefined;
+        summary?: undefined;
+        hasSummary?: undefined;
+    } | {
+        success: boolean;
+        filename: string;
+        type: import("../index.js").FileType;
+        size: string;
+        sizeBytes: number;
+        sizeTier: import("./types.js").SizeTier;
+        mimeType: string;
+        estimatedTokens: number;
+        status: import("./types.js").FileReferenceStatus;
+        totalLines: number | null;
+        preview: string;
+        summary: string | null;
+        hasSummary: boolean;
+        error?: undefined;
+    }> & {
+        execute: (args: {
+            file_id: string;
+        }, options: import("ai").ToolExecutionOptions) => PromiseLike<{
+            success: boolean;
+            error: string;
+            filename?: undefined;
+            type?: undefined;
+            size?: undefined;
+            sizeBytes?: undefined;
+            sizeTier?: undefined;
+            mimeType?: undefined;
+            estimatedTokens?: undefined;
+            status?: undefined;
+            totalLines?: undefined;
+            preview?: undefined;
+            summary?: undefined;
+            hasSummary?: undefined;
+        } | {
+            success: boolean;
+            filename: string;
+            type: import("../index.js").FileType;
+            size: string;
+            sizeBytes: number;
+            sizeTier: import("./types.js").SizeTier;
+            mimeType: string;
+            estimatedTokens: number;
+            status: import("./types.js").FileReferenceStatus;
+            totalLines: number | null;
+            preview: string;
+            summary: string | null;
+            hasSummary: boolean;
+            error?: undefined;
+        }>;
+    };
+    extract_file_content: import("ai").Tool<z.ZodObject<{
+        file_id: z.ZodString;
+        start_time: z.ZodOptional<z.ZodNumber>;
+        end_time: z.ZodOptional<z.ZodNumber>;
+        frame_count: z.ZodOptional<z.ZodNumber>;
+        pages: z.ZodOptional<z.ZodArray<z.ZodNumber, "many">>;
+        page_range: z.ZodOptional<z.ZodObject<{
+            start: z.ZodNumber;
+            end: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            end: number;
+            start: number;
+        }, {
+            end: number;
+            start: number;
+        }>>;
+        sheet: z.ZodOptional<z.ZodString>;
+        row_range: z.ZodOptional<z.ZodObject<{
+            start: z.ZodNumber;
+            end: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            end: number;
+            start: number;
+        }, {
+            end: number;
+            start: number;
+        }>>;
+        columns: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        entry_path: z.ZodOptional<z.ZodString>;
+        format: z.ZodOptional<z.ZodEnum<["text", "detailed", "summary"]>>;
+    }, "strip", z.ZodTypeAny, {
+        file_id: string;
+        format?: "text" | "summary" | "detailed" | undefined;
+        columns?: string[] | undefined;
+        sheet?: string | undefined;
+        start_time?: number | undefined;
+        end_time?: number | undefined;
+        frame_count?: number | undefined;
+        pages?: number[] | undefined;
+        page_range?: {
+            end: number;
+            start: number;
+        } | undefined;
+        row_range?: {
+            end: number;
+            start: number;
+        } | undefined;
+        entry_path?: string | undefined;
+    }, {
+        file_id: string;
+        format?: "text" | "summary" | "detailed" | undefined;
+        columns?: string[] | undefined;
+        sheet?: string | undefined;
+        start_time?: number | undefined;
+        end_time?: number | undefined;
+        frame_count?: number | undefined;
+        pages?: number[] | undefined;
+        page_range?: {
+            end: number;
+            start: number;
+        } | undefined;
+        row_range?: {
+            end: number;
+            start: number;
+        } | undefined;
+        entry_path?: string | undefined;
+    }>, {
+        success: false;
+        error: string | undefined;
+        text: string | undefined;
+        metadata: Record<string, unknown> | undefined;
+        imageCount: number;
+        _images: Buffer[] | undefined;
+    } | {
+        success: true;
+        text: string | undefined;
+        metadata: Record<string, unknown> | undefined;
+        imageCount: number;
+        _images: Buffer<ArrayBufferLike>[] | undefined;
+        error: string | undefined;
+    }> & {
+        execute: (args: {
+            file_id: string;
+            format?: "text" | "summary" | "detailed" | undefined;
+            columns?: string[] | undefined;
+            sheet?: string | undefined;
+            start_time?: number | undefined;
+            end_time?: number | undefined;
+            frame_count?: number | undefined;
+            pages?: number[] | undefined;
+            page_range?: {
+                end: number;
+                start: number;
+            } | undefined;
+            row_range?: {
+                end: number;
+                start: number;
+            } | undefined;
+            entry_path?: string | undefined;
+        }, options: import("ai").ToolExecutionOptions) => PromiseLike<{
+            success: false;
+            error: string | undefined;
+            text: string | undefined;
+            metadata: Record<string, unknown> | undefined;
+            imageCount: number;
+            _images: Buffer[] | undefined;
+        } | {
+            success: true;
+            text: string | undefined;
+            metadata: Record<string, unknown> | undefined;
+            imageCount: number;
+            _images: Buffer<ArrayBufferLike>[] | undefined;
+            error: string | undefined;
+        }>;
+    };
+};