qlogicagent 2.10.1 → 2.10.3

package/dist/types/provider-core/media-transport.d.ts

@@ -0,0 +1,176 @@
+/**
+ * MediaTransport 鈥?transport interface for generation APIs (image, video, music, 3D).
+ *
+ * Parallel to LLMTransport (chat/reasoning), MediaTransport handles
+ * non-chat generation endpoints that each vendor exposes differently:
+ *   - Sync (OpenAI images, Volcengine Seedream, Gemini generateContent)
+ *   - Async job (Volcengine Seedance/3D, MiniMax music) 鈥?submit 鈫?poll 鈫?result
+ *
+ * Each provider adapter implements this interface and hides vendor-specific
+ * auth, endpoint paths, request shapes, and polling logic.
+ */
+export type MediaType = "image" | "video" | "music" | "music_realtime" | "tts" | "3d" | "stt" | "embedding" | "video_understanding" | "image_understanding" | "voice_clone" | "rerank" | "document_parsing" | "realtime_audio" | "realtime_video";
+export interface MediaRequest {
+    /** Generation model id, e.g. "doubao-seedream-5-0-260128", "gpt-image-2" */
+    model: string;
+    /** What kind of media to generate */
+    mediaType: MediaType;
+    /** Text prompt for generation */
+    prompt: string;
+    /** Optional reference image URL (img2img, i2v, img-to-3d) */
+    imageUrl?: string;
+    /** Desired dimensions, e.g. "1024x1024" */
+    size?: string;
+    /** Aspect ratio for video, e.g. "16:9" */
+    aspectRatio?: string;
+    /** Duration in seconds (video, music) */
+    duration?: number;
+    /** Number of outputs (image) */
+    n?: number;
+    /** Visual/musical style */
+    style?: string;
+    /** Intended use / purpose */
+    purpose?: string;
+    /** Lyrics for music generation */
+    lyrics?: string;
+    /** Text for TTS */
+    text?: string;
+    /** TTS channel hint */
+    channel?: string;
+    /** Source video URLs for edit/merge operations */
+    sourceVideos?: string[];
+    /** Reference images (no role / first_frame / last_frame) */
+    referenceImages?: string[];
+    /** Reference image roles 鈥?parallel array with referenceImages. */
+    imageRoles?: Array<"first_frame" | "last_frame" | "reference_image">;
+    /** Reference video URLs for multimodal reference generation (Seedance 2.0) */
+    referenceVideos?: string[];
+    /** Reference audio URLs for multimodal reference generation (Seedance 2.0) */
+    referenceAudios?: string[];
+    /** Generate synchronized audio track (Seedance 2.0 / 1.5 pro) */
+    generateAudio?: boolean;
+    /** Output resolution for upscale, e.g. "1080p" */
+    resolution?: string;
+    /** Operation variant: generate (default), edit, merge, upscale, multimodal_reference, extend */
+    operation?: "generate" | "edit" | "merge" | "upscale" | "multimodal_reference" | "extend";
+    /** Image/video quality, e.g. "auto", "high", "low", "hd" */
+    quality?: string;
+    /** Seed for reproducible generation */
+    seed?: number;
+    /** TTS voice, e.g. "alloy", "nova", "shimmer" */
+    voice?: string;
+    /** TTS speech speed multiplier */
+    speed?: number;
+    /** Pure instrumental mode (MiniMax music) */
+    isInstrumental?: boolean;
+    /** Source audio URL for cover/remix (MiniMax music) */
+    audioUrl?: string;
+    /** Output audio format, e.g. "mp3", "wav", "flac" */
+    audioFormat?: string;
+    /** Video frames per second */
+    fps?: number;
+    /** Whether to add AI watermark */
+    watermark?: boolean;
+    /** img2img guidance/control strength (0-1), e.g. Volcengine */
+    guidanceScale?: number;
+    /** Auto-generate lyrics when none provided (MiniMax) */
+    lyricsOptimizer?: boolean;
+    /** 3D output format, e.g. "glb", "obj", "usd", "usdz" */
+    outputFormat?: string;
+    /** Image background mode (OpenAI gpt-image-2): "transparent", "opaque", "auto" */
+    background?: string;
+    /** Provider-specific request metadata (e.g. rerank documents, parsing options) */
+    metadata?: Record<string, unknown>;
+    /** Ask the provider to optimize/enhance the prompt before generation */
+    enhancePrompt?: boolean;
+    /**
+     * Progress callback for async polling operations (video gen, 3D gen, etc.).
+     * Called periodically with estimated progress percentage, status text, and
+     * the provider-specific task ID (available once the task is submitted).
+     */
+    onProgress?: (percent: number, status: string, taskId?: string) => void;
+    /** Enable progressive/streaming image generation (Volcengine Seedream stream:true) */
+    streamImage?: boolean;
+    /** Lock camera position (Seedance 1.0/1.5, not Seedance 2.0) */
+    cameraFixed?: boolean;
+    /** Return last frame URL for chaining continuous video segments */
+    returnLastFrame?: boolean;
+    /** Service tier: 'default' (online) or 'flex' (offline, ~50% cost) 鈥?not all models support flex */
+    serviceTier?: "default" | "flex";
+    /** Task expiration in seconds (for flex/offline scheduling) */
+    executionExpiresAfterSeconds?: number;
+    /** Draft mode 鈥?low-cost preview (Seedance 1.5 pro only) */
+    draft?: boolean;
+    /** Draft task ID to promote to final video */
+    draftTaskId?: string;
+    /** Video-level builtin tools, e.g. ["web_search"] (Seedance 2.0) */
+    videoTools?: string[];
+    /** End-user safety identifier for content moderation */
+    safetyIdentifier?: string;
+    /** Callback URL for async task status push notifications */
+    callbackUrl?: string;
+    /** Image detail level control: 'auto' | 'low' | 'high' */
+    detail?: "auto" | "low" | "high";
+    /** Max image pixels budget (Volcengine image_pixel_limit) */
+    imagePixelLimit?: number;
+}
+export interface MediaResult {
+    /** URLs of generated media files */
+    mediaUrls: string[];
+    /** Model actually used */
+    model?: string;
+    /** Output dimensions / format info */
+    size?: string;
+    /** Total generation time in ms */
+    durationMs?: number;
+    /** Billing unit type for non-token models */
+    billingUnit?: "per_call" | "per_second" | "per_character" | "per_pixel" | "per_token";
+    /** Quantity consumed (seconds, characters, pixels, etc.) */
+    billingQuantity?: number;
+    /** Provider-specific metadata */
+    metadata?: Record<string, unknown>;
+    /** Last frame image URL for chaining continuous video generation */
+    lastFrameUrl?: string;
+    /** Task ID (for continuing draft鈫抐inal or querying) */
+    taskId?: string;
+}
+export interface MediaTransport {
+    /**
+     * Generate media content.
+     * Handles sync APIs directly and async job APIs (submit + poll) internally.
+     *
+     * @param request - Generation parameters
+     * @param apiKey  - User API key (passed explicitly, not from env)
+     * @param signal  - Optional abort signal
+     */
+    generate(request: MediaRequest, apiKey: string, signal?: AbortSignal): Promise<MediaResult>;
+    /**
+     * Which media types this transport supports.
+     * Used by the media client factory to route requests.
+     */
+    readonly supportedTypes: readonly MediaType[];
+}
+/**
+ * Extended transport for providers that support async task management
+ * (submit 鈫?poll 鈫?cancel/query). Volcengine Seedance, MiniMax async, etc.
+ */
+export interface AsyncMediaTransport extends MediaTransport {
+    /** Cancel / delete an async task. */
+    deleteVideoTask(taskId: string, apiKey: string, signal?: AbortSignal): Promise<void>;
+    /** List recent tasks for status queries. */
+    listVideoTasks(apiKey: string, options?: {
+        after?: string;
+        limit?: number;
+        status?: string;
+    }, signal?: AbortSignal): Promise<Record<string, unknown>>;
+    /**
+     * Query a single task by ID 鈥?preferred over listVideoTasks for direct lookups.
+     * Not all providers support listing; all async providers support single-task queries.
+     */
+    getTaskStatus?(taskId: string, apiKey: string, signal?: AbortSignal): Promise<{
+        status: string;
+        task: Record<string, unknown>;
+    }>;
+}
+/** Type guard for transports that support async task management. */
+export declare function isAsyncMediaTransport(t: MediaTransport): t is AsyncMediaTransport;

package/dist/types/provider-core/media.d.ts

@@ -0,0 +1,2 @@
+export type { MediaTransport, MediaRequest, MediaResult, MediaType } from "./media-transport.js";
+export { isAsyncMediaTransport } from "./media-transport.js";

package/dist/types/provider-core/model-catalog.d.ts

@@ -0,0 +1,82 @@
+/**
+ * ModelCatalog 鈥?remote model directory with disk cache + fallback.
+ *
+ * Fetches model metadata from models.dev/api.json (community-maintained,
+ * comprehensive single-source catalog with 100+ providers).
+ *
+ * Two-layer fallback:
+ *   1. In-memory cache (process-level, TTL check against disk mtime)
+ *   2. Disk cache (~/.qlogicagent/cache/model_catalog.json)
+ *   3. Remote fetch (models.dev single endpoint)
+ *   4. Stale disk cache (if remote fails)
+ *   5. Empty (caller falls back to builtin-providers.ts hardcoded)
+ *
+ * Non-blocking: first startup without cache returns empty immediately,
+ * triggers background async fetch. Agent uses builtin providers until
+ * catalog arrives.
+ */
+import type { ModelInfo } from "./provider-def.js";
+/** Embedding model metadata from models.dev catalog. */
+export interface EmbeddingModelInfo {
+    id: string;
+    name: string;
+    /** Provider-internal ID (e.g. "openai", "qwen") */
+    providerId: string;
+    /** Output vector dimensions (from limit.output) */
+    dimensions: number;
+    /** Max input context tokens */
+    maxInputTokens: number;
+    /** Cost per million input tokens (USD) */
+    costInput?: number;
+    /** Model family string from models.dev */
+    family: string;
+}
+export declare class ModelCatalog {
+    private cache;
+    private cacheDir;
+    private cacheFile;
+    private ttlMs;
+    private fetching;
+    private lastFetchAttempt;
+    constructor(opts?: {
+        cacheDir?: string;
+        ttlMs?: number;
+    });
+    /**
+     * Get models for a provider. Non-blocking: returns whatever is cached.
+     * Triggers background refresh if stale.
+     */
+    getModels(providerId: string): ModelInfo[];
+    /**
+     * Get a single model by provider + model id.
+     */
+    getModel(providerId: string, modelId: string): ModelInfo | undefined;
+    /**
+     * List all known provider ids from the catalog.
+     */
+    listProviderIds(): string[];
+    /**
+     * Get embedding models for a provider.
+     * Returns models sorted by cost (cheapest first, then largest dims).
+     */
+    getEmbeddingModels(providerId: string): EmbeddingModelInfo[];
+    /**
+     * Get the default embedding model for a provider.
+     * Picks the cheapest model with >=512 dimensions.
+     */
+    getDefaultEmbeddingModel(providerId: string): EmbeddingModelInfo | undefined;
+    /**
+     * Get all embedding models across all providers.
+     */
+    getAllEmbeddingModels(): Map<string, EmbeddingModelInfo[]>;
+    /**
+     * Force refresh from remote. Returns true if successful.
+     */
+    refreshCatalog(): Promise<boolean>;
+    private ensureLoaded;
+    private isStale;
+    private loadFromDisk;
+    private saveToDisk;
+    private backgroundFetch;
+    private fetchRemote;
+}

package/dist/types/provider-core/model-detection.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Model detection helpers shared between OpenAI transport implementations.
+ *
+ * These are used by both openai-chat.ts and openai-responses.ts to detect
+ * model families and apply family-specific constraints:
+ *   - GPT-5.x: unified reasoning, temperature allowed, reasoning object format
+ *   - GPT-5.4-nano: reasoning effort capped at medium
+ *   - o-series (legacy): reasoning_effort flat string, temperature suppressed
+ */
+/** GPT-5.x models (new generation with unified reasoning). */
+export declare function isGPT5xModel(model: string): boolean;
+/**
+ * GPT-5.4-nano models 鈥?reasoning effort capped at medium.
+ * openai-ProviderMax 搂3: gpt-5.4-nano only supports none/low/medium effort.
+ */
+export declare function isGPT5NanoModel(model: string): boolean;
+/**
+ * OpenAI o-series reasoning models (legacy, kept for 3rd-party provider compat).
+ * These suppress temperature/top_p and use reasoning_effort as flat string.
+ * Matches: o1, o1-mini, o1-pro, o3, o3-mini, o3-pro, o4-mini, etc.
+ */
+export declare function isOpenAIReasoningModel(model: string): boolean;

package/dist/types/provider-core/paths.d.ts

@@ -0,0 +1,2 @@
+export declare function getUserCacheDir(): string;
+export declare function getUserDebugLogsDir(): string;

package/dist/types/provider-core/provider-def.d.ts

@@ -0,0 +1,214 @@
+/**
+ * ProviderDef 鈥?defines how to connect to an LLM provider.
+ *
+ * Aligned with Hermes `ProviderDef` dataclass pattern:
+ *   id + name + transport type + baseUrl + auth config + model list
+ *
+ * Three-layer merge strategy (Layer 3 > Layer 2 > Layer 1):
+ *   Layer 1: builtin-providers.ts hardcoded (fallback)
+ *   Layer 2: model-catalog.ts remote (models.dev)
+ *   Layer 3: user config (from agent.turn.config)
+ */
+export type TransportType = "openai-chat" | "openai-responses" | "anthropic-messages" | "volcengine-responses" | "gemini-generatecontent";
+export type AuthType = "bearer" | "x-api-key" | "none";
+export type MediaCapability = "image" | "video" | "music" | "music_realtime" | "tts" | "3d" | "stt" | "embedding" | "video_understanding" | "image_understanding" | "voice_clone" | "rerank" | "document_parsing" | "realtime_audio" | "realtime_video";
+export type VideoOperation = "text2video" | "img2video" | "video2video" | "edit" | "merge" | "upscale";
+export type ImageOperation = "text2image" | "img2img" | "inpainting" | "outpainting";
+export type MusicOperation = "text2music" | "cover" | "realtime";
+export type TtsOperation = "text2speech" | "voice_clone";
+export type ThreeDOperation = "text2_3d" | "img2_3d";
+export interface VideoCapabilities {
+    type: "video";
+    operations: VideoOperation[];
+    maxDurationSeconds?: number;
+    resolutions?: string[];
+    aspectRatios?: string[];
+    fps?: number[];
+}
+export interface ImageCapabilities {
+    type: "image";
+    operations: ImageOperation[];
+    sizes?: string[];
+    transparentBackground?: boolean;
+}
+export interface MusicCapabilities {
+    type: "music";
+    operations: MusicOperation[];
+    maxDurationSeconds?: number;
+    formats?: string[];
+}
+export interface TtsCapabilities {
+    type: "tts";
+    operations?: TtsOperation[];
+    voices?: string[];
+    maxCharacters?: number;
+    formats?: string[];
+}
+export interface ThreeDCapabilities {
+    type: "3d";
+    operations: ThreeDOperation[];
+    outputFormats?: string[];
+}
+export interface SttCapabilities {
+    type: "stt";
+    languages?: string[];
+    maxDurationSeconds?: number;
+    formats?: string[];
+}
+export interface EmbeddingCapabilities {
+    type: "embedding";
+    dimensions?: number;
+    maxTokens?: number;
+}
+export interface VideoUnderstandingCapabilities {
+    type: "video_understanding";
+    maxDurationSeconds?: number;
+    formats?: string[];
+}
+export interface ImageUnderstandingCapabilities {
+    type: "image_understanding";
+    formats?: string[];
+}
+export interface VoiceCloneCapabilities {
+    type: "voice_clone";
+    maxSampleDurationSeconds?: number;
+    maxSampleSizeMB?: number;
+    formats?: string[];
+}
+export interface RerankCapabilities {
+    type: "rerank";
+    maxDocuments?: number;
+    maxQueryLength?: number;
+    maxDocumentLength?: number;
+}
+export interface DocumentParsingCapabilities {
+    type: "document_parsing";
+    supportedFormats?: string[];
+    maxPageCount?: number;
+    maxFileSizeMB?: number;
+}
+export interface RealtimeAudioCapabilities {
+    type: "realtime_audio";
+    voices?: string[];
+    modalities?: Array<"text" | "audio">;
+    vad?: boolean;
+    toolCalling?: boolean;
+}
+export interface RealtimeVideoCapabilities {
+    type: "realtime_video";
+    modalities?: Array<"text" | "audio" | "video">;
+    vad?: boolean;
+    toolCalling?: boolean;
+    maxDurationSeconds?: number;
+}
+export type MediaCapabilities = VideoCapabilities | ImageCapabilities | MusicCapabilities | TtsCapabilities | ThreeDCapabilities | SttCapabilities | EmbeddingCapabilities | VideoUnderstandingCapabilities | ImageUnderstandingCapabilities | VoiceCloneCapabilities | RerankCapabilities | DocumentParsingCapabilities | RealtimeAudioCapabilities | RealtimeVideoCapabilities;
+/**
+ * Provider-specific quirks 鈥?drives conditional logic in transports.
+ * CC parity: provider detection via quirks flags instead of hardcoded if/else.
+ * altcode parity: provider auto-detect + per-provider parameter translation.
+ */
+export interface ProviderQuirks {
+    /** Provider doesn't support thinking content blocks (Qwen) */
+    filterThinkingBlocks?: boolean;
+    /** Provider doesn't support image content blocks 鈥?strip imageUrls before sending (DeepSeek, MiniMax) */
+    filterImageBlocks?: boolean;
+    /** DeepSeek: budget_tokens ignored, use output_config.effort instead */
+    useEffortInsteadOfBudget?: boolean;
+    /** Provider natively supports PDF/document content blocks (Anthropic document, Gemini fileData).
+     *  When false, PDFs are annotated as text labels and the agent must use tools to extract content. */
+    supportsDocumentVision?: boolean;
+    /** Provider supports reasoning_effort param (Kimi K2, OpenAI o-series) */
+    supportsReasoningEffort?: boolean;
+    /** Provider has built-in web search (Kimi: builtin_function.$web_search, GLM: web_search) */
+    builtinWebSearch?: boolean;
+    /** Provider has built-in code interpreter */
+    builtinCodeInterpreter?: boolean;
+    /** Provider supports native URL context fetching (Gemini urlContext tool) */
+    builtinUrlContext?: boolean;
+    /** Provider supports Google Maps Grounding (Gemini googleMaps tool) */
+    builtinMapsGrounding?: boolean;
+    /** Provider supports native file search (Gemini fileSearch tool) */
+    builtinFileSearch?: boolean;
+    /** Supports thinking.type="enabled"/"disabled" body param (Kimi K2, GLM).
+     *  Disambiguation: GLM also sets supportsToolStream; Kimi does not. */
+    supportsThinkingParam?: boolean;
+    /** When true, send thinking.type="disabled" unless the caller explicitly requests reasoning. */
+    disableThinkingByDefault?: boolean;
+    /** GLM-only: supports tool_stream=true for incremental tool call streaming */
+    supportsToolStream?: boolean;
+    /** DeepSeek only maps to "high"|"max"; low/medium鈫抙igh */
+    maxReasoningEffort?: "high" | "max";
+    /** Supports prefix completion via /beta endpoint (DeepSeek Beta) */
+    supportsPrefixCompletion?: boolean;
+    /** MiniMax OpenAI route: inject reasoning_split=true to split thinking into reasoning_details.
+     *  Streaming uses cumulative string updates (not incremental deltas). */
+    supportsReasoningSplit?: boolean;
+}
+export interface ProviderDef {
+    /** Unique provider id, e.g. "deepseek", "openai", "anthropic" */
+    id: string;
+    /** Display name, e.g. "DeepSeek" */
+    name: string;
+    /** Which transport to use for LLM calls */
+    transport: TransportType;
+    /** API base URL, e.g. "https://api.deepseek.com" */
+    baseUrl: string;
+    /**
+     * Logical provider group 鈥?links protocol variants of the same vendor.
+     * e.g. both "zhipu" (anthropic) and "zhipu-openai" share group "zhipu".
+     * Defaults to provider id if unset.
+     */
+    group?: string;
+    /** Env var names for API key (priority order) */
+    apiKeyEnvVars: string[];
+    /** Auth header style */
+    authType: AuthType;
+    /** Is an aggregator (OpenRouter, 纭呭熀) 鈥?model ids may have prefix */
+    isAggregator: boolean;
+    /** Recommended default model */
+    defaultModel?: string;
+    /** Known models for this provider */
+    models?: ModelInfo[];
+    /** Extra headers to send with every request (e.g. aggregator-specific) */
+    extraHeaders?: Record<string, string>;
+    /** Whether this provider supports stream_options (default true for openai-chat) */
+    supportsStreamOptions?: boolean;
+    /** Whether to omit temperature when it equals 0 (some providers reject 0) */
+    omitZeroTemperature?: boolean;
+    /** Provider-specific quirks for transport-level conditional logic */
+    quirks?: ProviderQuirks;
+}
+export interface ModelInfo {
+    /** Model id, e.g. "deepseek-v4-flash" */
+    id: string;
+    /** Stable public aliases exposed by llmrouter or older qlogicagent configs */
+    aliases?: string[];
+    /** Display name, e.g. "DeepSeek Chat V3" */
+    name: string;
+    /** Context window in tokens */
+    contextWindow: number;
+    /** Max output tokens */
+    maxOutput: number;
+    /** Supports function/tool calling */
+    toolCall: boolean;
+    /** Has reasoning/thinking mode */
+    reasoning: boolean;
+    /** Thinking is forced on 鈥?cannot be toggled off (e.g. QwQ, DeepSeek-R1) */
+    reasoningRequired?: boolean;
+    /** Model only supports streaming (non-stream requests will fail) */
+    streamRequired?: boolean;
+    /** Supports vision (image input) */
+    vision: boolean;
+    /** Cost per 1M input tokens (USD) */
+    costInput?: number;
+    /** Cost per 1M output tokens (USD) */
+    costOutput?: number;
+    /** Cost per 1M cache read tokens (USD) */
+    costCacheRead?: number;
+    /** Cost per 1M cache write tokens (USD) */
+    costCacheWrite?: number;
+    /** Media generation capability 鈥?undefined means chat/reasoning model */
+    mediaType?: MediaCapability;
+    /** Fine-grained media capabilities 鈥?operations, formats, limits */
+    mediaCapabilities?: MediaCapabilities;
+}

package/dist/types/provider-core/provider-registry.d.ts

@@ -0,0 +1,59 @@
+/**
+ * ProviderRegistry 鈥?two-layer merge registry for LLM providers.
+ *
+ * Layer 1: builtin-providers.ts hardcoded (lowest priority, ~20 providers)
+ * Layer 2: model-catalog.ts remote (models.dev 鈥?enriches model metadata)
+ * Layer 3: user config override (from agent.turn.config 鈥?highest priority)
+ *
+ * Merge strategy: Layer 3 > Layer 2 > Layer 1 (later layers override same-id fields)
+ *
+ * Aligned with Hermes provider_registry.py.
+ */
+import type { ModelInfo, ProviderDef } from "./provider-def.js";
+import { ModelCatalog } from "./model-catalog.js";
+export declare class ProviderRegistry {
+    /** Layer 1: builtin hardcoded providers */
+    private builtins;
+    /** Layer 2: remote model catalog (models.dev) */
+    private catalog;
+    /** Layer 3: user overrides (from agent.turn.config) */
+    private overrides;
+    constructor(opts?: {
+        catalog?: ModelCatalog;
+    });
+    /**
+     * Apply user config override for a provider.
+     * Typically called when agent.turn.config has baseUrl/apiKey overrides.
+     */
+    applyOverride(providerId: string, override: Partial<ProviderDef>): void;
+    /**
+     * Get merged ProviderDef by id (Layer 3 > Layer 1).
+     * Returns undefined if provider not found.
+     * Supports common aliases (e.g., "claude" 鈫?"anthropic").
+     */
+    getProvider(id: string): ProviderDef | undefined;
+    /**
+     * List all known provider ids.
+     */
+    listProviders(): ProviderDef[];
+    /**
+     * List models for a specific provider.
+     * Merges: Layer 3 override > Layer 1 builtin > Layer 2 catalog enrichment.
+     */
+    listModels(providerId: string): ModelInfo[];
+    /**
+     * Look up a single model's info by provider + model id.
+     * Returns undefined if the model is not found.
+     */
+    getModelInfo(providerId: string, modelId: string): ModelInfo | undefined;
+    /**
+     * Trigger background refresh of the remote model catalog.
+     */
+    refreshCatalog(): Promise<boolean>;
+    /**
+     * Resolve API key for a provider:
+     *   1. Explicit key (from agent.turn.config)
+     *   2. Environment variables (ProviderDef.apiKeyEnvVars)
+     */
+    resolveApiKey(providerId: string, explicitKey?: string): string | undefined;
+}

package/dist/types/provider-core/provider-tool-api.d.ts

@@ -0,0 +1,44 @@
+/**
+ * ProviderToolAPI 鈥?interface for provider-specific utility endpoints
+ * that are neither LLM chat nor media generation.
+ *
+ * Examples: web search, content reader, tokenizer, moderation, realtime voice.
+ * Each provider can expose its own set of tool APIs; the agent's tool cascade
+ * mechanism (Q1) routes to these when the provider has a native capability.
+ */
+export interface WebSearchResult {
+    title: string;
+    url: string;
+    snippet: string;
+    /** Full page content if available */
+    content?: string;
+}
+export interface ReaderResult {
+    title: string;
+    content: string;
+    url: string;
+}
+export interface TokenizerResult {
+    tokenCount: number;
+    model: string;
+}
+export interface ModerationResult {
+    flagged: boolean;
+    categories: Record<string, boolean>;
+    scores?: Record<string, number>;
+}
+export interface ProviderToolAPI {
+    /** Which tool APIs this provider supports */
+    readonly capabilities: readonly ProviderToolCapability[];
+    /** Web search 鈥?returns search result list */
+    webSearch?(query: string, options?: {
+        maxResults?: number;
+    }): Promise<WebSearchResult[]>;
+    /** URL reader 鈥?extracts content from a web page */
+    reader?(url: string): Promise<ReaderResult>;
+    /** Tokenizer 鈥?count tokens for given text/model */
+    tokenize?(text: string, model: string): Promise<TokenizerResult>;
+    /** Content moderation 鈥?check text for policy violations */
+    moderate?(text: string): Promise<ModerationResult>;
+}
+export type ProviderToolCapability = "web_search" | "reader" | "tokenizer" | "moderations";

package/dist/types/provider-core/retry.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Shared retry/backoff utilities for LLM transport implementations.
+ *
+ * Provides common constants and helper functions used by all transports
+ * (anthropic-messages, openai-chat, volcengine-responses) to handle
+ * transient errors with exponential backoff.
+ */
+/** Default maximum number of retry attempts */
+export declare const DEFAULT_MAX_RETRIES = 2;
+/** Base delay for exponential backoff (doubles each attempt, capped at 30s) */
+export declare const RETRY_BASE_DELAY_MS = 1000;
+/** Maximum backoff delay */
+export declare const RETRY_MAX_DELAY_MS = 30000;
+/** HTTP status codes considered transient (worth retrying) */
+export declare const TRANSIENT_STATUS_CODES: Set<number>;
+/** Default timeout for idle stream detection (no data received) */
+export declare const STREAM_IDLE_TIMEOUT_MS = 90000;
+/**
+ * Calculate the delay for a given retry attempt using exponential backoff with jitter.
+ * @param attempt 1-based attempt number (1 = first retry)
+ * @returns delay in milliseconds
+ */
+export declare function retryDelay(attempt: number): number;
+/**
+ * Check if an HTTP status code indicates a transient error worth retrying.
+ */
+export declare function isTransientStatus(status: number | null | undefined): boolean;
+/**
+ * Sleep with abort signal support. Resolves after `ms` milliseconds
+ * or rejects if the signal is aborted.
+ */
+export declare function retrySleep(ms: number, signal?: AbortSignal): Promise<void>;
+/**
+ * Extract HTTP status from various error shapes.
+ * Works with fetch Response errors, Axios errors, and generic errors with status property.
+ */
+export declare function extractHttpStatus(error: unknown): number | null;