qlogicagent 0.5.2 → 0.5.3

package/dist/types/skills/tools/mcp-tool.d.ts

@@ -0,0 +1,249 @@
+import type { PortableTool } from "../portable-tool.js";
+import type { McpServerConfig, McpConnectionStatus, McpServerCapabilities, McpToolAnnotations, McpToolsChangedEvent, McpPromptDefinition, McpPromptMessage, McpElicitResult, McpAuthState, McpLogEntry, McpLogLevel } from "./mcp-client-types.js";
+export type { McpServerConfig, McpStdioConfig, McpSseConfig, McpHttpConfig, McpWsConfig, McpInProcessConfig, McpServerState, McpConnectionStatus, McpServerCapabilities, McpExternalTool, McpToolAnnotations, McpToolIdentifier, McpToolsChangedEvent, McpResourceDefinition, McpResourceTemplate, McpPersistedResourceContent, McpResourceContentItem, McpPromptDefinition, McpPromptArgument, McpPromptMessage, McpPromptContent, McpElicitResult, McpElicitRequest, McpOAuthConfig, McpOAuthTokens, McpAuthState, McpLogEntry, McpLogLevel, McpTransportType, } from "./mcp-client-types.js";
+export { normalizeNameForMcp, buildMcpToolName, getMcpServerPrefix, parseMcpToolName, isMcpToolName, MCP_CONNECTION_TIMEOUT_MS, MCP_REQUEST_TIMEOUT_MS, MCP_TOOL_CALL_TIMEOUT_MS, MCP_MAX_RECONNECT_ATTEMPTS, MCP_MAX_DESCRIPTION_LENGTH, } from "./mcp-client-types.js";
+export declare const MCP_TOOL_NAME: "mcp";
+export type McpAction = "list_servers" | "list_tools" | "call_tool" | "list_resources" | "read_resource" | "list_prompts" | "get_prompt" | "authenticate" | "manage_server";
+export interface McpToolParams {
+    action: McpAction;
+    /** Server name (required for most actions) */
+    server?: string;
+    /** Tool name on the MCP server (for call_tool) */
+    toolName?: string;
+    /** Arguments for the MCP tool call or prompt arguments */
+    arguments?: Record<string, unknown>;
+    /** Resource URI (for read_resource) */
+    uri?: string;
+    /** Prompt name (for get_prompt) */
+    promptName?: string;
+    /** Server management sub-action */
+    manageAction?: McpManageAction;
+    /** Server config (for manage_server add) */
+    config?: McpServerConfig;
+}
+export type McpManageAction = "add" | "remove" | "restart" | "health_check" | "enable" | "disable";
+export declare const MCP_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly action: {
+            readonly type: "string";
+            readonly enum: readonly ["list_servers", "list_tools", "call_tool", "list_resources", "read_resource", "list_prompts", "get_prompt", "authenticate", "manage_server"];
+            readonly description: string;
+        };
+        readonly server: {
+            readonly type: "string";
+            readonly description: "MCP server name. Required for all actions except list_servers.";
+        };
+        readonly toolName: {
+            readonly type: "string";
+            readonly description: "Tool name on the MCP server. Required for call_tool.";
+        };
+        readonly arguments: {
+            readonly type: "object";
+            readonly description: "Arguments for the tool call or prompt. Used with call_tool and get_prompt.";
+        };
+        readonly uri: {
+            readonly type: "string";
+            readonly description: "Resource URI. Required for read_resource.";
+        };
+        readonly promptName: {
+            readonly type: "string";
+            readonly description: "Prompt name. Required for get_prompt.";
+        };
+        readonly manageAction: {
+            readonly type: "string";
+            readonly enum: readonly ["add", "remove", "restart", "health_check", "enable", "disable"];
+            readonly description: "Sub-action for manage_server.";
+        };
+        readonly config: {
+            readonly type: "object";
+            readonly description: "Server configuration. Required for manage_server add.";
+        };
+    };
+    readonly required: readonly ["action"];
+};
+export interface McpServer {
+    name: string;
+    status: McpConnectionStatus;
+    transport: string;
+    toolCount: number;
+    resourceCount: number;
+    promptCount: number;
+    capabilities?: McpServerCapabilities;
+    serverVersion?: string;
+    error?: string;
+    connectedAt?: number;
+}
+export interface McpToolInfo {
+    name: string;
+    description?: string;
+    inputSchema?: Record<string, unknown>;
+    annotations?: McpToolAnnotations;
+    /** Prefixed name used in tool list */
+    prefixedName?: string;
+}
+export interface McpResource {
+    uri: string;
+    name: string;
+    mimeType?: string;
+    description?: string;
+    server?: string;
+}
+export interface McpResourceContent {
+    uri: string;
+    mimeType?: string;
+    text?: string;
+    blobSavedTo?: string;
+    blobSize?: number;
+}
+export interface McpCallResult {
+    success: boolean;
+    content?: string;
+    error?: string;
+    isError?: boolean;
+    /** Structured content blocks (images, resources) */
+    contentBlocks?: Array<{
+        type: "text" | "image" | "resource";
+        text?: string;
+        data?: string;
+        mimeType?: string;
+    }>;
+}
+export interface McpAuthResult {
+    status: "auth_url" | "already_authenticated" | "unsupported" | "step_up_required" | "error";
+    authUrl?: string;
+    message?: string;
+    /** Required scopes for step-up auth */
+    requiredScopes?: string[];
+}
+export interface McpPromptResult {
+    description?: string;
+    messages: McpPromptMessage[];
+}
+export interface McpManageResult {
+    success: boolean;
+    message: string;
+    /** Updated server state after the operation */
+    serverState?: McpServer;
+}
+/**
+ * Host-provided MCP client backend — full lifecycle management.
+ *
+ * Implements the complete MCP client SDK contract:
+ * - Transport abstraction (stdio/SSE/HTTP/WS/in-process)
+ * - Connection lifecycle (connect/disconnect/reconnect/health)
+ * - OAuth authentication with PKCE + token refresh
+ * - Dynamic tool injection (tools/list_changed notification)
+ * - Resource management with binary blob persistence
+ * - Prompt support
+ * - Server configuration CRUD
+ */
+export interface McpToolDeps {
+    /** List all configured MCP servers with full state */
+    listServers(): Promise<McpServer[]>;
+    /**
+     * List tools from a specific server.
+     * Results are cached; invalidated on tools/list_changed notification.
+     */
+    listTools(server: string): Promise<McpToolInfo[]>;
+    /**
+     * Call a tool on an MCP server.
+     * Handles: connection ensure → permission check → execute → parse result.
+     */
+    callTool(server: string, toolName: string, args?: Record<string, unknown>, signal?: AbortSignal): Promise<McpCallResult>;
+    /**
+     * List resources from a server (or all servers if not specified).
+     * Uses LRU cache; invalidated on resources/list_changed.
+     */
+    listResources(server?: string): Promise<McpResource[]>;
+    /**
+     * Read a specific resource by URI.
+     * Handles binary blob persistence: base64 → disk file → returns path.
+     */
+    readResource(server: string, uri: string): Promise<McpResourceContent[]>;
+    /**
+     * List prompts available from a server.
+     * Prompts are reusable templates that servers expose.
+     */
+    listPrompts?(server: string): Promise<McpPromptDefinition[]>;
+    /**
+     * Get a specific prompt with arguments expanded.
+     * Returns the prompt messages ready for injection into conversation.
+     */
+    getPrompt?(server: string, promptName: string, args?: Record<string, string>): Promise<McpPromptResult>;
+    /**
+     * Initiate OAuth authentication with a server.
+     * Supports: PKCE flow, token refresh, step-up auth.
+     *
+     * For stdio servers: returns "not_applicable".
+     * For SSE/HTTP servers: returns auth_url or triggers silent auth.
+     */
+    authenticate(server: string): Promise<McpAuthResult>;
+    /**
+     * Check current auth state of a server (without initiating a flow).
+     * Optional — host may not track auth state for all servers.
+     */
+    getAuthState?(server: string): Promise<McpAuthState>;
+    /**
+     * Add a new MCP server configuration.
+     * Optionally auto-connects after adding.
+     */
+    addServer?(name: string, config: McpServerConfig): Promise<McpManageResult>;
+    /**
+     * Remove an MCP server (disconnect + delete config).
+     * Also removes all injected tools with the server's prefix.
+     */
+    removeServer?(name: string): Promise<McpManageResult>;
+    /**
+     * Restart (disconnect + reconnect) a server.
+     * Clears caches and re-fetches tools/resources/prompts.
+     */
+    restartServer?(name: string): Promise<McpManageResult>;
+    /**
+     * Health check a server's connection.
+     * Returns the updated server state with latency info.
+     */
+    healthCheck?(server: string): Promise<McpManageResult>;
+    /**
+     * Enable/disable a server (disabled servers don't auto-connect).
+     */
+    setServerEnabled?(name: string, enabled: boolean): Promise<McpManageResult>;
+    /**
+     * Register a callback for when a server's tool list changes.
+     * The host calls this when it receives tools/list_changed notifications.
+     *
+     * The callback receives the event with previous and current tool lists,
+     * enabling the orchestration layer to hot-swap injected tools.
+     */
+    onToolsChanged?(callback: (event: McpToolsChangedEvent) => void): void;
+    /**
+     * Get all currently injected MCP tools across all servers.
+     * Returns the flattened list of tools with their prefixed names.
+     */
+    getInjectedTools?(): Promise<McpToolInfo[]>;
+    /**
+     * Handle an elicitation request from an MCP server.
+     * The server asks the user for input/consent; the host presents UI.
+     * Optional — defaults to deny if not implemented.
+     */
+    handleElicitation?(server: string, message: string, schema?: Record<string, unknown>): Promise<McpElicitResult>;
+    /**
+     * Get recent log entries from MCP servers.
+     * Optional — useful for debugging server-side issues.
+     */
+    getServerLogs?(server: string, level?: McpLogLevel, limit?: number): Promise<McpLogEntry[]>;
+}
+export declare function createMcpTool(deps: McpToolDeps): PortableTool<McpToolParams>;
+export interface McpAuthProxyDeps {
+    /** Initiate OAuth for the specified server */
+    authenticate(server: string): Promise<McpAuthResult>;
+    /** Optional callback after successful auth — e.g. reconnect, refresh tools */
+    onAuthComplete?(server: string): Promise<void>;
+}
+/**
+ * Create a dynamic per-server authentication proxy tool.
+ * One instance per unauthenticated MCP server.
+ *
+ * Tool name follows CC convention: `mcp__<normalizedServer>__authenticate`
+ */
+export declare function createMcpAuthProxy(serverName: string, deps: McpAuthProxyDeps): PortableTool<Record<string, never>>;

package/dist/types/skills/tools/memory-tool.d.ts

@@ -0,0 +1,74 @@
+import type { PortableTool } from "../portable-tool.js";
+export declare const MEMORY_SEARCH_TOOL_NAME: "memory_search";
+export type MemorySource = "memory" | "sessions" | "all";
+export interface MemorySearchToolParams {
+    /** Search query */
+    query: string;
+    /** Source to search in */
+    source?: MemorySource;
+    /** Maximum results to return */
+    maxResults?: number;
+    /** Filter by time range (ISO date string, sessions only) */
+    after?: string;
+    /** Filter by time range (ISO date string, sessions only) */
+    before?: string;
+}
+export declare const MEMORY_SEARCH_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly query: {
+            readonly type: "string";
+            readonly description: "Search query. Supports natural language and keywords.";
+        };
+        readonly source: {
+            readonly type: "string";
+            readonly enum: readonly ["memory", "sessions", "all"];
+            readonly description: string;
+        };
+        readonly maxResults: {
+            readonly type: "number";
+            readonly description: "Maximum results to return (default: 5).";
+        };
+        readonly after: {
+            readonly type: "string";
+            readonly description: "Only return sessions after this date (ISO format). Sessions source only.";
+        };
+        readonly before: {
+            readonly type: "string";
+            readonly description: "Only return sessions before this date (ISO format). Sessions source only.";
+        };
+    };
+    readonly required: readonly ["query"];
+};
+export interface MemoryEntry {
+    content: string;
+    source: "memory" | "session";
+    relevance: number;
+    metadata?: {
+        sessionId?: string;
+        timestamp?: string;
+        summary?: string;
+    };
+}
+export interface MemoryQueryOutput {
+    results: MemoryEntry[];
+    query: string;
+    sources: MemorySource[];
+}
+/**
+ * Host-provided memory search backend.
+ */
+export interface MemorySearchToolDeps {
+    /**
+     * Search memory/sessions.
+     * The host routes to QMemory vector search, FTS session search, or both.
+     */
+    searchMemory(params: {
+        query: string;
+        source: MemorySource;
+        maxResults: number;
+        after?: string;
+        before?: string;
+    }): Promise<MemoryQueryOutput>;
+}
+export declare function createMemorySearchTool(deps: MemorySearchToolDeps): PortableTool<MemorySearchToolParams>;

package/dist/types/skills/tools/monitor-tool.d.ts

@@ -0,0 +1,113 @@
+import type { PortableTool } from "../portable-tool.js";
+export declare const MONITOR_TOOL_NAME: "monitor";
+/** The kind of event source the agent can monitor. */
+export type MonitorSource = "process" | "file" | "task" | "custom";
+export type MonitorAction = "start" | "stop" | "list";
+export interface MonitorToolParams {
+    action: MonitorAction;
+    /** Required for start/stop — identifies the monitor instance. */
+    monitorId?: string;
+    /** Required for start — what kind of event source to watch. */
+    source?: MonitorSource;
+    /** Required for start — selector for the target (pid, path, taskId, custom key). */
+    target?: string;
+    /** Optional for start — conditions that should trigger wake-up. */
+    conditions?: MonitorCondition[];
+    /** Optional for start — max time to monitor in seconds before auto-stop. */
+    timeoutSeconds?: number;
+}
+export interface MonitorCondition {
+    /** What to check: exit code, stdout pattern, file modification, task status. */
+    type: "exit" | "output_match" | "file_changed" | "task_status";
+    /** Pattern or value to match (regex for output_match, status name for task_status). */
+    value?: string;
+}
+export declare const MONITOR_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly action: {
+            readonly type: "string";
+            readonly enum: readonly ["start", "stop", "list"];
+            readonly description: "Action to perform: start a new monitor, stop an existing one, or list active monitors.";
+        };
+        readonly monitorId: {
+            readonly type: "string";
+            readonly description: "Identifier for the monitor instance. Required for start/stop.";
+        };
+        readonly source: {
+            readonly type: "string";
+            readonly enum: readonly ["process", "file", "task", "custom"];
+            readonly description: "Type of event source to watch.";
+        };
+        readonly target: {
+            readonly type: "string";
+            readonly description: string;
+        };
+        readonly conditions: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly type: {
+                        readonly type: "string";
+                        readonly enum: readonly ["exit", "output_match", "file_changed", "task_status"];
+                    };
+                    readonly value: {
+                        readonly type: "string";
+                    };
+                };
+                readonly required: readonly ["type"];
+            };
+            readonly description: "Conditions that trigger a wake-up notification.";
+        };
+        readonly timeoutSeconds: {
+            readonly type: "number";
+            readonly description: "Auto-stop after this many seconds (default: 3600).";
+            readonly minimum: 1;
+            readonly maximum: 86400;
+        };
+    };
+    readonly required: readonly ["action"];
+};
+/** Info about an active monitor. */
+export interface MonitorInfo {
+    monitorId: string;
+    source: MonitorSource;
+    target: string;
+    conditions: MonitorCondition[];
+    startedAt: number;
+    timeoutSeconds: number;
+    /** Events received so far. */
+    eventCount: number;
+}
+/** Result of monitor operations. */
+export interface MonitorResult {
+    action: MonitorAction;
+    success: boolean;
+    monitorId?: string;
+    monitors?: MonitorInfo[];
+    error?: string;
+}
+/**
+ * Runtime dependencies injected by the host.
+ *
+ * The host is responsible for:
+ * 1. Actually watching the event source (polling, inotify, process hooks, etc.)
+ * 2. Delivering notifications back to the agent loop (via tick or wake-up)
+ * 3. Cleaning up monitors when they time out or are stopped.
+ */
+export interface MonitorToolDeps {
+    /** Start monitoring a target. Returns the created monitor info. */
+    startMonitor(params: {
+        monitorId: string;
+        source: MonitorSource;
+        target: string;
+        conditions: MonitorCondition[];
+        timeoutSeconds: number;
+    }): Promise<MonitorResult>;
+    /** Stop an active monitor. */
+    stopMonitor(monitorId: string): Promise<MonitorResult>;
+    /** List all active monitors for this session. */
+    listMonitors(): Promise<MonitorInfo[]>;
+}
+export declare function createMonitorTool(deps: MonitorToolDeps): PortableTool<MonitorToolParams>;

package/dist/types/skills/tools/music-generate-tool.d.ts

@@ -0,0 +1,55 @@
+import type { PortableTool } from "../portable-tool.js";
+export declare const MUSIC_GENERATE_TOOL_NAME: "music_generate";
+export interface MusicGenerateToolParams {
+    prompt: string;
+    purpose?: string;
+    style?: string;
+    lyrics?: string;
+    duration?: number;
+}
+export declare const MUSIC_GENERATE_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly prompt: {
+            readonly type: "string";
+            readonly description: string;
+        };
+        readonly purpose: {
+            readonly type: "string";
+            readonly description: "Intended use: 'background-music', 'ringtone', 'short-video-bgm', 'full-song', 'notification-sound', etc.";
+        };
+        readonly style: {
+            readonly type: "string";
+            readonly description: "Musical style/genre: 'lo-fi', 'pop', 'rock', 'jazz', 'classical', 'electronic', 'ambient', etc.";
+        };
+        readonly lyrics: {
+            readonly type: "string";
+            readonly description: "Optional lyrics for vocal music. Structure with [verse], [chorus], [bridge] tags if desired.";
+        };
+        readonly duration: {
+            readonly type: "number";
+            readonly description: "Duration in seconds (5-300). Infer from purpose: ringtone 15-30s, BGM 30-60s, full song 120-180s.";
+        };
+    };
+    readonly required: readonly ["prompt"];
+};
+export interface MusicGenerateResult {
+    mediaUrls: string[];
+    model?: string;
+    durationMs?: number;
+}
+/** Deps injected by the host runtime for music generation. */
+export interface MusicGenerateToolDeps {
+    /**
+     * Generate music via the configured backend.
+     * The host handles model selection, failover, and storage.
+     */
+    generateMusic(params: {
+        prompt: string;
+        purpose?: string;
+        style?: string;
+        lyrics?: string;
+        duration?: number;
+    }): Promise<MusicGenerateResult>;
+}
+export declare function createMusicGenerateTool(deps: MusicGenerateToolDeps): PortableTool<MusicGenerateToolParams>;

package/dist/types/skills/tools/notebook-edit-tool.d.ts

@@ -0,0 +1,15 @@
+import type { PortableTool } from "../portable-tool.js";
+export type NotebookEditMode = "replace" | "insert" | "delete";
+export interface NotebookEditParams {
+    /** Absolute path to the .ipynb file */
+    notebook_path: string;
+    /** Cell number (1-based) to operate on */
+    cell_number: number;
+    /** New cell source content (required for replace/insert) */
+    new_source?: string;
+    /** Cell type for insert (default: "code") */
+    cell_type?: "code" | "markdown";
+    /** Edit mode (default: "replace") */
+    edit_mode?: NotebookEditMode;
+}
+export declare function createNotebookEditTool(): PortableTool<NotebookEditParams>;

package/dist/types/skills/tools/notify-tool.d.ts

@@ -0,0 +1,53 @@
+import type { PortableTool } from "../portable-tool.js";
+export declare const NOTIFY_TOOL_NAME: "notify";
+export interface NotifyToolParams {
+    /** Notification message */
+    message: string;
+    /** Optional title/subject */
+    title?: string;
+    /** Priority level */
+    priority?: "low" | "normal" | "high";
+    /** Target channel override (default: user's primary channel) */
+    channel?: string;
+}
+export declare const NOTIFY_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly message: {
+            readonly type: "string";
+            readonly description: "Notification content to send to the user.";
+        };
+        readonly title: {
+            readonly type: "string";
+            readonly description: "Optional notification title/subject line.";
+        };
+        readonly priority: {
+            readonly type: "string";
+            readonly enum: readonly ["low", "normal", "high"];
+            readonly description: "Notification priority (default: normal). High may trigger sound/vibration.";
+        };
+        readonly channel: {
+            readonly type: "string";
+            readonly description: "Target delivery channel (e.g. 'wechat', 'feishu', 'discord'). Default: user's primary.";
+        };
+    };
+    readonly required: readonly ["message"];
+};
+export interface NotifyResult {
+    delivered: boolean;
+    channel: string;
+    error?: string;
+}
+/**
+ * Host-provided notification delivery backend.
+ */
+export interface NotifyToolDeps {
+    /** Send notification to user. Host routes to correct platform. */
+    sendNotification(params: {
+        message: string;
+        title?: string;
+        priority?: string;
+        channel?: string;
+    }): Promise<NotifyResult>;
+}
+export declare function createNotifyTool(deps: NotifyToolDeps): PortableTool<NotifyToolParams>;

package/dist/types/skills/tools/patch-tool.d.ts

@@ -0,0 +1,45 @@
+import type { PortableTool } from "../portable-tool.js";
+export declare const PATCH_TOOL_NAME: "patch";
+export interface PatchToolParams {
+    /** V4A unified diff or simple find-replace */
+    input: string;
+    /** When true, replace all occurrences in each file (default: false) */
+    replaceAll?: boolean;
+}
+export declare const PATCH_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly input: {
+            readonly type: "string";
+            readonly description: string;
+        };
+        readonly replaceAll: {
+            readonly type: "boolean";
+            readonly description: "Replace all occurrences instead of first only (default: false).";
+        };
+    };
+    readonly required: readonly ["input"];
+};
+export interface PatchResult {
+    filesModified: string[];
+    filesAdded: string[];
+    filesDeleted: string[];
+    strategies: Record<string, string>;
+    errors: string[];
+}
+export interface PatchToolDeps {
+    readFile(path: string): Promise<string>;
+    writeFile(path: string, content: string): Promise<void>;
+    deleteFile(path: string): Promise<void>;
+    fileExists(path: string): Promise<boolean>;
+    resolvePath(input: string): string;
+}
+export type MatchStrategy = "exact" | "line_trimmed" | "whitespace_normalized" | "indentation_flexible" | "escape_normalized" | "trimmed_boundary" | "unicode_normalized" | "block_anchor" | "context_aware";
+interface MatchResult {
+    start: number;
+    end: number;
+    strategy: MatchStrategy;
+}
+declare function fuzzyFind(content: string, search: string, replaceAll: boolean): MatchResult[];
+export declare function createPatchTool(deps: PatchToolDeps): PortableTool<PatchToolParams>;
+export { fuzzyFind, type MatchResult };

package/dist/types/skills/tools/pdf-tool.d.ts

@@ -0,0 +1,66 @@
+import type { PortableTool } from "../portable-tool.js";
+export declare const PDF_TOOL_NAME: "pdf";
+export interface PdfToolParams {
+    prompt?: string;
+    pdf?: string;
+    pdfs?: string[];
+    pages?: string;
+}
+export declare const PDF_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly prompt: {
+            readonly type: "string";
+            readonly description: "Describe what to analyze or extract from the PDF(s).";
+        };
+        readonly pdf: {
+            readonly type: "string";
+            readonly description: "Single PDF path or URL.";
+        };
+        readonly pdfs: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+            readonly description: "Multiple PDF paths or URLs (up to 10).";
+        };
+        readonly pages: {
+            readonly type: "string";
+            readonly description: "Page range to process, e.g. \"1-5\", \"1,3,5-7\". Defaults to all pages.";
+        };
+    };
+    readonly required: readonly [];
+};
+/** Deps injected by the host runtime for PDF analysis. */
+export interface PdfToolDeps {
+    /**
+     * Extract text and/or page images from a PDF.
+     * The host decides how to load (local FS, HTTP, etc.).
+     */
+    extractPdf(source: string, options?: {
+        pages?: string;
+    }): Promise<{
+        text: string;
+        pageImages?: Array<{
+            page: number;
+            base64: string;
+            mimeType: string;
+        }>;
+    }>;
+    /**
+     * Optional: analyze extracted content via LLM.
+     * If not provided, the tool returns raw extracted text.
+     */
+    analyzePdfContent?(prompt: string, content: {
+        text: string;
+        images?: Array<{
+            base64: string;
+            mimeType: string;
+        }>;
+    }): Promise<{
+        text: string;
+        model?: string;
+        provider?: string;
+    }>;
+}
+export declare function createPdfTool(deps: PdfToolDeps): PortableTool<PdfToolParams>;