qlogicagent 1.0.0 → 1.1.0

package/dist/types/llm/transports/realtime-transport.d.ts

@@ -0,0 +1,183 @@
+/**
+ * Realtime WebSocket Transport — bidirectional audio/voice streaming
+ * via the OpenAI Realtime API protocol (also compatible with GLM Realtime).
+ *
+ * ## Protocol: WebSocket JSON events
+ *
+ * Client → Server:
+ *   - session.update: configure session (model, voice, tools, etc.)
+ *   - input_audio_buffer.append: send audio chunks (base64 PCM16)
+ *   - input_audio_buffer.commit: signal end of audio input
+ *   - conversation.item.create: inject text/function_result items
+ *   - response.create: request a model response
+ *   - response.cancel: abort in-progress response
+ *
+ * Server → Client:
+ *   - session.created: session initialized
+ *   - session.updated: config acknowledged
+ *   - input_audio_buffer.speech_started: VAD detected speech
+ *   - input_audio_buffer.speech_stopped: VAD detected silence
+ *   - response.created: response generation started
+ *   - response.output_item.added: new output item (text/audio/function_call)
+ *   - response.audio.delta: audio chunk (base64 PCM16)
+ *   - response.audio_transcript.delta: transcript of generated speech
+ *   - response.text.delta: text generation delta
+ *   - response.function_call_arguments.delta: tool call args delta
+ *   - response.function_call_arguments.done: tool call complete
+ *   - response.output_item.done: output item finished
+ *   - response.done: full response complete
+ *   - error: server error
+ *
+ * ## Architecture
+ *
+ * RealtimeTransport manages a single persistent WebSocket connection per session.
+ * It exposes an event-driven API (AsyncGenerator) that the agent tool-loop
+ * can consume for voice-enabled interactions.
+ *
+ * Docs:
+ *   - OpenAI: https://platform.openai.com/docs/api-reference/realtime
+ *   - GLM:    https://docs.bigmodel.cn/cn/guide/develop/realtime-api
+ */
+export interface RealtimeConfig {
+    /** WebSocket endpoint (e.g. "wss://api.openai.com/v1/realtime") */
+    baseUrl: string;
+    /** Model to use (e.g. "gpt-4o-realtime-preview", "glm-realtime") */
+    model: string;
+    /** API key */
+    apiKey: string;
+    /** Voice for TTS output */
+    voice?: string;
+    /** Input modalities: "text", "audio", or both */
+    inputModalities?: Array<"text" | "audio">;
+    /** Output modalities: "text", "audio", or both */
+    outputModalities?: Array<"text" | "audio">;
+    /** Temperature for generation */
+    temperature?: number;
+    /** Tool definitions for function calling */
+    tools?: RealtimeTool[];
+    /** Voice Activity Detection mode */
+    vadMode?: "server_vad" | "none";
+    /** VAD threshold (0.0-1.0) */
+    vadThreshold?: number;
+    /** Auth type: "header" (OpenAI) or "query" (GLM) */
+    authMode?: "header" | "query";
+}
+export interface RealtimeTool {
+    type: "function";
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+}
+export type RealtimeEvent = {
+    type: "session_created";
+    sessionId: string;
+} | {
+    type: "speech_started";
+} | {
+    type: "speech_stopped";
+    audioEndMs: number;
+} | {
+    type: "audio_delta";
+    delta: string;
+} | {
+    type: "audio_transcript_delta";
+    delta: string;
+} | {
+    type: "text_delta";
+    delta: string;
+} | {
+    type: "function_call_start";
+    callId: string;
+    name: string;
+} | {
+    type: "function_call_delta";
+    callId: string;
+    delta: string;
+} | {
+    type: "function_call_done";
+    callId: string;
+    name: string;
+    arguments: string;
+} | {
+    type: "response_done";
+    usage?: RealtimeUsage;
+} | {
+    type: "error";
+    code: string;
+    message: string;
+} | {
+    type: "closed";
+    code: number;
+    reason: string;
+};
+export interface RealtimeUsage {
+    inputTokens: number;
+    outputTokens: number;
+    inputAudioTokens?: number;
+    outputAudioTokens?: number;
+}
+/**
+ * Manages a persistent WebSocket connection for real-time audio/voice
+ * interactions with an LLM provider.
+ *
+ * Usage:
+ * ```ts
+ * const rt = new RealtimeTransport(config);
+ * rt.connect();
+ *
+ * // Send audio
+ * rt.appendAudio(base64Chunk);
+ * rt.commitAudio();
+ *
+ * // Or send text
+ * rt.sendText("Hello!");
+ *
+ * // Submit function results
+ * rt.sendFunctionResult(callId, result);
+ *
+ * // Consume events
+ * for await (const event of rt.events()) {
+ *   switch (event.type) {
+ *     case "audio_delta": playAudio(event.delta); break;
+ *     case "function_call_done": handleToolCall(event); break;
+ *   }
+ * }
+ *
+ * rt.close();
+ * ```
+ */
+export declare class RealtimeTransport {
+    private ws;
+    private config;
+    private eventQueue;
+    private waiters;
+    private closed;
+    constructor(config: RealtimeConfig);
+    /** Open WebSocket connection and configure session. */
+    connect(): Promise<void>;
+    /** Send audio data (base64 PCM16). */
+    appendAudio(base64Chunk: string): void;
+    /** Mark end of audio input and trigger response. */
+    commitAudio(): void;
+    /** Send a text message. */
+    sendText(text: string): void;
+    /** Submit a function call result back to the model. */
+    sendFunctionResult(callId: string, output: string): void;
+    /** Trigger a model response (e.g. after sending text). */
+    requestResponse(): void;
+    /** Cancel an in-progress response. */
+    cancelResponse(): void;
+    /** Async iterator of server events. */
+    events(): AsyncGenerator<RealtimeEvent>;
+    /** Close the WebSocket connection. */
+    close(): void;
+    private buildUrl;
+    private sendSessionUpdate;
+    private send;
+    private push;
+    private drainWaiters;
+    /**
+     * Parse a server-sent JSON event into our typed event(s).
+     */
+    private parseServerEvent;
+}

package/dist/types/llm/transports/volcengine-grounding.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Volcengine Grounding — spatial coordinate parser (volcengine-ProviderMax §14).
+ *
+ * Parses model-emitted spatial reference tags from text output:
+ *   - <bbox>x_min y_min x_max y_max</bbox>   → bounding box
+ *   - <point>x y</point>                       → single point
+ *   - <polygon>x1 y1 x2 y2 ...</polygon>       → polygon vertices
+ *
+ * All coordinates are in normalized 1000×1000 space, range [0, 999].
+ * Use `toPixelCoords()` to convert to actual image pixel coordinates.
+ */
+export type SpatialReference = {
+    type: "bbox";
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+    space: "normalized_1000";
+} | {
+    type: "point";
+    x: number;
+    y: number;
+    space: "normalized_1000";
+} | {
+    type: "polygon";
+    points: Array<{
+        x: number;
+        y: number;
+    }>;
+    space: "normalized_1000";
+};
+export interface PixelBbox {
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+}
+export interface PixelPoint {
+    x: number;
+    y: number;
+}
+/**
+ * Extract all spatial references from model output text.
+ * Returns an empty array if no grounding tags are found.
+ */
+export declare function parseGroundingTags(text: string): SpatialReference[];
+/**
+ * Convert a normalized 1000×1000 bounding box to pixel coordinates.
+ */
+export declare function bboxToPixels(ref: Extract<SpatialReference, {
+    type: "bbox";
+}>, width: number, height: number): PixelBbox;
+/**
+ * Convert a normalized 1000×1000 point to pixel coordinates.
+ */
+export declare function pointToPixels(ref: Extract<SpatialReference, {
+    type: "point";
+}>, width: number, height: number): PixelPoint;

package/dist/types/llm/transports/volcengine-media.d.ts

@@ -27,8 +27,58 @@ export declare class VolcengineMediaTransport implements MediaTransport {
      */
     canHandle(request: MediaRequest): boolean;
     private generateImage;
+    /**
+     * Parse streaming image SSE — yields progressive image quality upgrades.
+     * Final event contains the full-quality image URL.
+     */
+    private parseStreamingImage;
     private generateVideo;
     private generate3D;
+    /**
+     * List video generation tasks with optional filters.
+     * GET /v3/contents/generations/tasks
+     */
+    listVideoTasks(apiKey: string, options?: {
+        after?: string;
+        limit?: number;
+        status?: string;
+    }, signal?: AbortSignal): Promise<Record<string, unknown>>;
+    /**
+     * Cancel or delete a video generation task.
+     * DELETE /v3/contents/generations/tasks/{taskId}
+     */
+    deleteVideoTask(taskId: string, apiKey: string, signal?: AbortSignal): Promise<void>;
+    /**
+     * Upload a file to Volcengine Files API for reuse in multimodal requests.
+     * POST /v3/files
+     */
+    uploadFile(file: Blob | Buffer, apiKey: string, options?: {
+        purpose?: string;
+        filename?: string;
+    }, signal?: AbortSignal): Promise<{
+        id: string;
+        status: string;
+    }>;
+    /**
+     * Get file info by ID.
+     * GET /v3/files/{fileId}
+     */
+    getFile(fileId: string, apiKey: string, signal?: AbortSignal): Promise<Record<string, unknown>>;
+    /**
+     * List uploaded files.
+     * GET /v3/files
+     */
+    listFiles(apiKey: string, options?: {
+        after?: string;
+        limit?: number;
+        purpose?: string;
+        order?: "asc" | "desc";
+    }, signal?: AbortSignal): Promise<Record<string, unknown>>;
+    /**
+     * Delete a file.
+     * DELETE /v3/files/{fileId}
+     */
+    deleteFile(fileId: string, apiKey: string, signal?: AbortSignal): Promise<void>;
     private submitTask;
     private pollTask;
 }

package/dist/types/llm/transports/volcengine-responses.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Volcengine Responses API Transport — SSE streaming implementation.
+ *
+ * Implements the fire mountain ark Responses API (`/api/v3/responses`),
+ * which is the officially recommended primary path for Doubao LLM text generation
+ * (250615+ models: doubao-seed-2.0 series).
+ *
+ * Key differences from OpenAI Chat Completions:
+ *   - Endpoint: POST {baseUrl}/v3/responses
+ *   - Request body uses `input` (not `messages`), `instructions`, `thinking`, `reasoning`
+ *   - SSE events: response.output_text.delta, response.reasoning_summary_text.delta,
+ *     response.function_call_arguments.delta, response.completed, etc.
+ *   - Tool calling: function_call / function_call_output with call_id
+ *   - Context persistence: previous_response_id for server-side session continuation
+ *   - Deep thinking: thinking.type (enabled/disabled/auto) + reasoning.effort
+ *
+ * Docs: https://www.volcengine.com/docs/82379/1399008
+ */
+import type { LLMChunk, LLMRequest, LLMTransport } from "../transport.js";
+import type { ProviderQuirks } from "../provider-def.js";
+export interface VolcengineResponsesTransportConfig {
+    baseUrl: string;
+    extraHeaders?: Record<string, string>;
+    timeoutMs?: number;
+    quirks?: ProviderQuirks;
+}
+export declare class VolcengineResponsesTransport implements LLMTransport {
+    private baseUrl;
+    private extraHeaders;
+    private timeoutMs;
+    private quirks;
+    constructor(config: VolcengineResponsesTransportConfig);
+    stream(request: LLMRequest, apiKey: string, signal?: AbortSignal): AsyncGenerator<LLMChunk>;
+    /**
+     * Resolve known Volcengine Responses API incompatibilities:
+     *   - instructions + caching → drop caching (§20.7)
+     *   - caching + json_schema → downgrade to json_object (§20.10)
+     *   - caching + builtin_web_search/image_process → drop those builtin tools
+     * Returns a shallow copy with fields adjusted; never mutates the original.
+     */
+    private resolveConstraints;
+    private buildRequestBody;
+    private fetchAndStream;
+    private handleNonStreamingResponse;
+    /**
+     * Parse Volcengine Responses API SSE stream.
+     *
+     * Event format: "event: <type>\ndata: <json>\n\n"
+     * Key events:
+     *   - response.output_text.delta           → text content delta
+     *   - response.reasoning_summary_text.delta → thinking/reasoning text
+     *   - response.function_call_arguments.delta → tool call arguments streaming
+     *   - response.output_item.added           → new output item started
+     *   - response.output_item.done            → output item completed
+     *   - response.completed                   → full response complete with usage
+     *   - response.failed                      → error
+     */
+    private parseSSEStream;
+    private processEvent;
+}

package/dist/types/llm/transports/zhipu-media.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Zhipu (GLM) Media Transport — CogView (image), CogVideoX (video), TTS, STT, Embedding.
+ *
+ * API reference (docs.bigmodel.cn):
+ *   Image sync:  POST /images/generations          (CogView-4, cogview-3-flash)
+ *   Image async: POST /async/images/generations     (glm-image)
+ *   Video async: POST /videos/generations           (CogVideoX)
+ *   TTS sync:    POST /audio/speech                 (glm-tts, returns audio bytes)
+ *   STT sync:    POST /audio/transcriptions         (glm-asr, multipart/form-data)
+ *   Embedding:   POST /embeddings                   (embedding-3/2)
+ *   Async poll:  GET  /async-result/{id}            (unified poll for all async tasks)
+ *
+ * Base URL: https://open.bigmodel.cn/api/paas/v4
+ * Auth: Authorization: Bearer $ZHIPU_API_KEY
+ */
+import type { MediaTransport, MediaRequest, MediaResult, MediaType } from "../media-transport.js";
+export interface ZhipuMediaConfig {
+    /** Base URL, e.g. "https://open.bigmodel.cn/api/paas/v4" */
+    baseUrl: string;
+    timeoutMs?: number;
+}
+export declare class ZhipuMediaTransport implements MediaTransport {
+    readonly supportedTypes: readonly MediaType[];
+    private baseUrl;
+    private timeoutMs;
+    constructor(config: ZhipuMediaConfig);
+    generate(request: MediaRequest, apiKey: string, signal?: AbortSignal): Promise<MediaResult>;
+    private generateImage;
+    /** CogView-4 / cogview-3-flash — sync, returns URL directly */
+    private generateImageSync;
+    /** glm-image — async submit + poll */
+    private generateImageAsync;
+    private generateVideo;
+    private generateTTS;
+    private generateSTT;
+    private generateEmbedding;
+    private generateVoiceClone;
+    private generateDocumentParsing;
+    private generateRerank;
+    private postJSON;
+    /**
+     * Unified async result polling — GET /async-result/{id}
+     * Returns the result object when task_status === "SUCCESS".
+     * Throws on "FAIL" or timeout.
+     */
+    private pollAsyncResult;
+    /**
+     * List cloned voices — GET /voice/
+     * Returns all voice clones for the current user.
+     */
+    listVoices(apiKey: string, signal?: AbortSignal): Promise<Array<{
+        voice_id: string;
+        voice_name: string;
+        status: string;
+    }>>;
+    /**
+     * Delete a cloned voice — DELETE /voice/{voice_id}
+     */
+    deleteVoice(voiceId: string, apiKey: string, signal?: AbortSignal): Promise<void>;
+}

package/dist/types/llm/transports/zhipu-tool-api.d.ts

@@ -0,0 +1,35 @@
+/**
+ * ZhipuToolAPI — Zhipu-specific utility endpoints.
+ *
+ * Implements ProviderToolAPI for Zhipu GLM platform independent APIs:
+ *   C1: Web Search  — POST /tools/web-search
+ *   C2: Reader      — POST /tools/reader (extract web page content)
+ *   C3: Tokenizer   — POST /tokenizer
+ *   C4: Moderations — POST /moderations
+ *
+ * Base URL: https://open.bigmodel.cn/api/paas/v4
+ * Auth: Authorization: Bearer $ZHIPU_API_KEY
+ *
+ * C5 (File Parser) is handled by document_parsing media handler.
+ * C6 (Realtime API) requires WebSocket — out of scope for this interface.
+ */
+import type { ProviderToolAPI, ProviderToolCapability, WebSearchResult, ReaderResult, TokenizerResult, ModerationResult } from "../provider-tool-api.js";
+export interface ZhipuToolAPIConfig {
+    baseUrl: string;
+    apiKey: string;
+    timeoutMs?: number;
+}
+export declare class ZhipuToolAPI implements ProviderToolAPI {
+    readonly capabilities: readonly ProviderToolCapability[];
+    private baseUrl;
+    private apiKey;
+    private timeoutMs;
+    constructor(config: ZhipuToolAPIConfig);
+    webSearch(query: string, options?: {
+        maxResults?: number;
+    }): Promise<WebSearchResult[]>;
+    reader(pageUrl: string): Promise<ReaderResult>;
+    tokenize(text: string, model: string): Promise<TokenizerResult>;
+    moderate(text: string): Promise<ModerationResult>;
+    private postJSON;
+}

package/dist/types/orchestration/error-handling/error-classification.d.ts

@@ -1,12 +1,3 @@
-import type { FailoverReason } from "./failover-classification.js";
 export type ErrorCategory = "RETRYABLE_TRANSIENT" | "RETRYABLE_DEGRADED" | "NON_RETRYABLE_AUTH" | "NON_RETRYABLE_CONTENT" | "NON_RETRYABLE_QUOTA" | "TOOL_EXECUTION_FAILED";
-export interface RetryStrategy {
-    retryable: boolean;
-    maxRetries: number;
-    baseDelayMs: number;
-    backoffMultiplier: number;
-    switchProvider: boolean;
-}
 export declare function classifyError(status: number | undefined, message?: string): ErrorCategory;
-export declare function classifyErrorFromReason(reason: FailoverReason): ErrorCategory;
-export declare function getRetryStrategy(category: ErrorCategory): RetryStrategy;
+export declare function isRetryableCategory(category: ErrorCategory): boolean;

package/dist/types/orchestration/index.d.ts

@@ -1,5 +1,5 @@
 export { buildAssistantToolCallMessage, buildToolResultMessage, type FunctionToolDefinition, } from "./tool-loop/tool-schema.js";
-export { classifyError, getRetryStrategy, type ErrorCategory, type RetryStrategy, } from "./error-handling/error-classification.js";
+export { classifyError, isRetryableCategory, type ErrorCategory, } from "./error-handling/error-classification.js";
 export { composeStrategies, composeAsyncStrategies, SlidingWindowStrategy, SummarizeOldStrategy, ToolResultTrimStrategy, HeadTailProtectedStrategy, IncrementalCompactStrategy, CacheAwareCompressionStrategy, CompressionMetricsCollector, ContextEngineRegistry, MicroCompactStrategy, postCompactFileRecovery, type PostCompactRecoveryConfig, buildStructuredSummaryPrompt, computeAdaptiveBudget, isAsyncCompressionStrategy, selectCompressionTier, DEFAULT_ADAPTIVE_BUDGET_CONFIG, type AdaptiveBudgetConfig, type AsyncCompressionStrategy, type CacheAwareCompressionConfig, type CompressibleMessage, type CompressionEvent, type CompressionMetrics, type CompressionMetricsSnapshot, type CompressionResult, type CompressionStrategy, type CompressionTier, type ContextEngine, type HeadTailProtectionConfig, type IncrementalCompactConfig, type SummarizeFn, } from "./context/context-compression.js";
 export { snipCompactIfNeeded, type SnipResult, } from "./context/context-compression.js";
 export { applyCollapsesIfNeeded as applyContextCollapsesIfNeeded, recoverFromOverflow as recoverContextCollapseFromOverflow, createCollapseStore, type CollapseStore, type CollapseStage, } from "./context/context-collapse.js";

package/dist/types/orchestration/tool-cascade.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Tool Cascade — provider-native tool augmentation layer.
+ *
+ * When a provider (e.g. Zhipu GLM) offers native utility APIs (web search, reader,
+ * tokenizer, etc.), the tool cascade automatically routes through the provider API
+ * first, falling back to the host-provided implementation (e.g. SearXNG) on failure.
+ *
+ * ## Architecture
+ *
+ * Two levels of provider tool integration:
+ *
+ * 1. **D-level (builtin tools)**: Injected directly into chat completion request
+ *    via `builtinWebSearch` / `builtinCodeInterpreter` quirks.
+ *    The LLM decides to use these inline during generation — no agent intervention.
+ *    → Handled by openai-chat.ts transport layer.
+ *
+ * 2. **C-level (independent APIs)**: Discrete API endpoints the agent calls explicitly
+ *    as tool steps (web_search, reader, tokenizer, moderations).
+ *    → Handled by this cascade layer — wraps host-provided tool deps with
+ *      provider-native backends, falling back on error.
+ *
+ * ## Usage
+ *
+ * ```ts
+ * import { cascadeWebSearch } from "./tool-cascade.js";
+ * import { ZhipuToolAPI } from "../llm/transports/zhipu-tool-api.js";
+ *
+ * const providerApi = new ZhipuToolAPI({ baseUrl, apiKey });
+ * const cascadedSearch = cascadeWebSearch(providerApi, fallbackSearchFn);
+ * const tool = createWebSearchTool({ search: cascadedSearch });
+ * ```
+ */
+import type { ProviderToolAPI } from "../llm/provider-tool-api.js";
+import type { WebSearchToolDeps } from "../skills/tools/web-search-tool.js";
+/**
+ * Cascade web search: provider-native search → host fallback.
+ * Returns a WebSearchToolDeps.search function that tries the provider's
+ * webSearch API first, falling back to the host's search on error.
+ */
+export declare function cascadeWebSearch(providerApi: ProviderToolAPI | undefined, fallbackSearch: WebSearchToolDeps["search"]): WebSearchToolDeps["search"];

package/dist/types/orchestration/tool-loop/tool-schema.d.ts

@@ -29,7 +29,10 @@ export declare function parseOpenAiToolCallsFromChatResponse(responseBody: strin
     toolCalls: OpenAiToolCall[];
     responseText: string;
 };
-export declare function buildAssistantToolCallMessage(toolCalls: OpenAiToolCall[], text?: string): Record<string, unknown>;
+export declare function buildAssistantToolCallMessage(toolCalls: OpenAiToolCall[], text?: string, thinkingBlocks?: Array<{
+    thinking: string;
+    signature: string;
+}>, reasoningContent?: string): Record<string, unknown>;
 export declare function buildToolResultMessage(callId: string, result: {
     ok: boolean;
     payload?: unknown;

package/dist/types/protocol/methods.d.ts

@@ -190,6 +190,21 @@ export interface ToolsListResult {
         parameters?: Record<string, unknown>;
     }>;
 }
+export interface MediaListModelsParams {
+    /** Filter by media type (image/video/music/tts/3d/stt/embedding). Omit to list all. */
+    mediaType?: string;
+}
+export interface MediaListModelsResult {
+    models: Array<{
+        providerId: string;
+        providerName: string;
+        modelId: string;
+        modelName: string;
+        mediaType: string;
+        /** Fine-grained capability metadata (operations, formats, limits) */
+        capabilities?: Record<string, unknown>;
+    }>;
+}
 export interface ConfigGetParams {
     keys?: string[];
 }
@@ -339,6 +354,10 @@ export interface RpcMethodMap {
         params: ToolsListParams;
         result: ToolsListResult;
     };
+    "media.listModels": {
+        params: MediaListModelsParams;
+        result: MediaListModelsResult;
+    };
     "config.get": {
         params: ConfigGetParams;
         result: ConfigGetResult;

package/dist/types/skills/memory/memory-extractor.d.ts

@@ -44,7 +44,7 @@ export type ExtractionCompleteFn = (params: {
     }>;
 }>;
 export interface MemoryExtractorOptions {
-    /** Model to use for extraction (default: "deepseek-chat"). */
+    /** Model to use for extraction (default: "deepseek-v4-flash"). */
     model?: string;
     /** Timeout in ms for the LLM call (default: 30_000). */
     timeoutMs?: number;

package/dist/types/skills/tools/file-management-tool.d.ts

@@ -0,0 +1,90 @@
+import type { PortableTool } from "../portable-tool.js";
+export declare const FILE_UPLOAD_TOOL_NAME: "file_upload";
+export interface FileUploadToolParams {
+    file_path: string;
+    purpose?: string;
+}
+export declare const FILE_UPLOAD_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly file_path: {
+            readonly type: "string";
+            readonly description: string;
+        };
+        readonly purpose: {
+            readonly type: "string";
+            readonly description: string;
+        };
+    };
+    readonly required: readonly ["file_path"];
+};
+export interface FileUploadResult {
+    fileId: string;
+    url?: string;
+    filename: string;
+    bytes: number;
+    provider: string;
+}
+export interface FileUploadToolDeps {
+    uploadFile(params: {
+        filePath: string;
+        purpose?: string;
+    }): Promise<FileUploadResult>;
+}
+export declare function createFileUploadTool(deps: FileUploadToolDeps): PortableTool<FileUploadToolParams>;
+export declare const FILE_QUERY_TOOL_NAME: "file_query";
+export interface FileQueryToolParams {
+    file_id?: string;
+    limit?: number;
+}
+export declare const FILE_QUERY_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly file_id: {
+            readonly type: "string";
+            readonly description: "Query a specific file by ID. If omitted, lists recent uploaded files.";
+        };
+        readonly limit: {
+            readonly type: "number";
+            readonly description: "Max number of files to list when file_id is omitted. Default: 10, max: 100.";
+        };
+    };
+    readonly required: readonly [];
+};
+export interface FileInfo {
+    id: string;
+    filename: string;
+    bytes: number;
+    status: string;
+    createdAt?: string;
+    url?: string;
+}
+export interface FileQueryToolDeps {
+    queryFile(params: {
+        fileId: string;
+    }): Promise<FileInfo>;
+    listFiles(params: {
+        limit?: number;
+    }): Promise<FileInfo[]>;
+}
+export declare function createFileQueryTool(deps: FileQueryToolDeps): PortableTool<FileQueryToolParams>;
+export declare const FILE_DELETE_TOOL_NAME: "file_delete";
+export interface FileDeleteToolParams {
+    file_id: string;
+}
+export declare const FILE_DELETE_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly file_id: {
+            readonly type: "string";
+            readonly description: "ID of the uploaded file to delete.";
+        };
+    };
+    readonly required: readonly ["file_id"];
+};
+export interface FileDeleteToolDeps {
+    deleteFile(params: {
+        fileId: string;
+    }): Promise<void>;
+}
+export declare function createFileDeleteTool(deps: FileDeleteToolDeps): PortableTool<FileDeleteToolParams>;