qlogicagent 1.0.1 → 1.1.0

package/dist/types/llm/transport.d.ts

@@ -9,17 +9,146 @@
  *   - Anthropic Messages API
  */
 import type { ChatMessage, ToolDefinition } from "../agent/types.js";
+export type StructuredOutputConfig = {
+    mode: "json_object";
+} | {
+    mode: "json_schema";
+    name: string;
+    schema: Record<string, unknown>;
+    strict?: boolean;
+};
+export interface CachingConfig {
+    type: "enabled" | "disabled";
+    /** Enable prefix caching mode (§20.3). Requires store=true and stream=false. */
+    prefix?: boolean;
+}
+export type ContextEdit = {
+    type: "clear_thinking";
+    keep?: "all" | {
+        type: "thinking_turns";
+        value: number;
+    };
+} | {
+    type: "clear_tool_uses";
+    trigger?: {
+        type: "tool_uses";
+        value: number;
+    };
+    keep?: {
+        type: "tool_uses";
+        value: number;
+    };
+    excludeTools?: string[];
+    clearToolInput?: boolean;
+};
+export interface ContextManagementConfig {
+    edits: ContextEdit[];
+}
 export interface LLMRequest {
     model: string;
     messages: ChatMessage[];
     tools?: ToolDefinition[];
-    toolChoice?: "auto" | "none" | "required";
+    toolChoice?: "auto" | "none" | "required" | {
+        type: "function";
+        name: string;
+    };
     temperature?: number;
+    /** Nucleus sampling: controls diversity via cumulative probability cutoff. */
+    topP?: number;
     maxTokens?: number;
     reasoning?: {
-        effort: "low" | "medium" | "high";
+        effort: "minimal" | "low" | "medium" | "high";
+        /** Request encrypted original reasoning content (Volcengine §17.7). */
+        includeEncryptedReasoning?: boolean;
     };
+    /** Volcengine: max builtin tool calls per turn (§19.15). */
+    maxToolCalls?: number;
+    /**
+     * DeepSeek prefix completion: force model to continue from this prefix.
+     * Requires `/beta` endpoint; adds a trailing assistant message with `prefix: true`.
+     */
+    prefixMessage?: string;
+    /**
+     * Model requires streaming — disable non-streaming fallback in transports.
+     * When true, transports must NOT fall back to non-streaming requests on failure.
+     * Set for models like QwQ/Omni where the provider rejects non-streaming calls.
+     */
+    streamRequired?: boolean;
+    /**
+     * Disable injection of provider-native builtin tools (web_search, code_interpreter)
+     * for this specific request. Allows session-level control over GLM/Kimi builtin tools.
+     */
+    disableBuiltinTools?: boolean;
+    /**
+     * Volcengine builtin tools to inject (web_search, image_process, knowledge_search).
+     * Each entry specifies a tool type and optional config.
+     * These are platform-executed tools requiring beta headers.
+     */
+    builtinTools?: Array<{
+        type: "builtin_web_search" | "builtin_image_process" | "builtin_knowledge_search" | "builtin_doubao_app";
+        config?: Record<string, unknown>;
+    }>;
+    /**
+     * Server-side context continuation via response chain (§5).
+     * When set, the server automatically includes previous context,
+     * so messages[] only needs to contain the NEW user message.
+     */
+    previousResponseId?: string;
+    /**
+     * Control server-side storage of this request's input/output (§5.1).
+     * Default: true (server stores for 3 days).
+     */
+    store?: boolean;
+    /** Expiration time for stored response (Unix seconds, max 7 days from now) */
+    storeExpireAt?: number;
+    /**
+     * Per-turn system instruction augmentation (§8).
+     * Temporarily overlays persona or adds constraints for this turn only.
+     * NOTE: Incompatible with caching — do not use both together.
+     */
+    instructions?: string;
+    /**
+     * Structured output format (§16).
+     * Forces model to produce JSON conforming to the specified schema.
+     */
+    structuredOutput?: StructuredOutputConfig;
+    /**
+     * Caching configuration (§20).
+     * Controls prefix/session caching behavior.
+     * NOTE: Incompatible with instructions, json_schema, and builtin tools.
+     */
+    caching?: CachingConfig;
+    /**
+     * Context management edits (§21, beta).
+     * Server-side trimming of historical thinking chains and tool call traces.
+     */
+    contextManagement?: ContextManagementConfig;
 }
+/**
+ * FIM completion request — DeepSeek Beta Completions API.
+ * POST /beta/v1/completions with prompt + suffix.
+ * Only works with non-thinking mode.
+ */
+export interface FIMRequest {
+    model: string;
+    /** Text before the cursor (prefix context) */
+    prompt: string;
+    /** Text after the cursor (suffix context) */
+    suffix?: string;
+    /** Max tokens to generate for the infill */
+    maxTokens?: number;
+    /** Sampling temperature */
+    temperature?: number;
+    /** Stop sequences */
+    stop?: string[];
+}
+export type FIMChunk = {
+    type: "delta";
+    text: string;
+} | {
+    type: "done";
+    finishReason: string;
+};
 export type LLMChunk = {
     type: "delta";
     text: string;
@@ -43,6 +172,27 @@ export type LLMChunk = {
     reasoningTokens?: number;
     cacheReadTokens?: number;
     cacheCreationTokens?: number;
+} | {
+    type: "response_id";
+    id: string;
+} | {
+    /** Informational status from platform-executed builtin tools (web_search, image_process). */
+    type: "builtin_tool_status";
+    toolType: string;
+    event: string;
+    data?: Record<string, unknown>;
+} | {
+    /** Web search citation annotations from Volcengine web_search results. */
+    type: "annotations";
+    annotations: Array<{
+        type: string;
+        url?: string;
+        title?: string;
+        [key: string]: unknown;
+    }>;
+} | {
+    type: "error";
+    message: string;
 } | {
     type: "done";
     finishReason: string;
@@ -58,6 +208,11 @@ export interface LLMTransport {
      * apiKey is passed explicitly (from agent.turn.config, not env).
      */
     stream(request: LLMRequest, apiKey: string, signal?: AbortSignal): AsyncGenerator<LLMChunk>;
+    /**
+     * FIM (Fill-In-Middle) completion — optional capability.
+     * Only implemented by providers that support it (DeepSeek /beta endpoint).
+     */
+    complete?(request: FIMRequest, apiKey: string, signal?: AbortSignal): AsyncGenerator<FIMChunk>;
 }
 /**
  * Accumulate tool_call_delta chunks into complete ToolCall objects.

package/dist/types/llm/transports/anthropic-messages.d.ts

@@ -12,6 +12,7 @@
  *   - signature_delta handling for thinking blocks
  */
 import type { LLMChunk, LLMRequest, LLMTransport } from "../transport.js";
+import type { ProviderQuirks } from "../provider-def.js";
 export interface AnthropicTransportConfig {
     baseUrl: string;
     /** anthropic-version header (default "2023-06-01") */
@@ -24,6 +25,10 @@ export interface AnthropicTransportConfig {
     enablePromptCaching?: boolean;
     /** Max retry attempts on transient errors (default 3) */
     maxRetries?: number;
+    /** Omit temperature when it equals 0 — MiniMax rejects temperature=0 */
+    omitZeroTemperature?: boolean;
+    /** Provider-specific quirks for conditional logic (CC/altcode parity) */
+    quirks?: ProviderQuirks;
 }
 export declare class AnthropicMessagesTransport implements LLMTransport {
     private baseUrl;
@@ -32,6 +37,8 @@ export declare class AnthropicMessagesTransport implements LLMTransport {
     private streamIdleTimeoutMs;
     private enablePromptCaching;
     private maxRetries;
+    private omitZeroTemperature;
+    private quirks;
     constructor(config: AnthropicTransportConfig);
     stream(request: LLMRequest, apiKey: string, signal?: AbortSignal): AsyncGenerator<LLMChunk>;
     /**

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

@@ -18,4 +18,9 @@ export declare class MiniMaxMediaTransport implements MediaTransport {
     constructor(config: MiniMaxMediaConfig);
     generate(request: MediaRequest, apiKey: string, signal?: AbortSignal): Promise<MediaResult>;
     private pollTask;
+    /**
+     * Generate lyrics from a text prompt via MiniMax Lyrics Generation API.
+     * POST /v1/lyrics_generation — returns structured lyrics with tags.
+     */
+    generateLyrics(prompt: string, apiKey: string, signal?: AbortSignal): Promise<string>;
 }

package/dist/types/llm/transports/openai-chat.d.ts

@@ -11,7 +11,8 @@
  *
  * Adapted from admin-infer-proxy-client.ts SSE logic + Hermes openai_chat.py transport.
  */
-import type { LLMChunk, LLMRequest, LLMTransport } from "../transport.js";
+import type { LLMChunk, LLMRequest, LLMTransport, FIMRequest, FIMChunk } from "../transport.js";
+import type { ProviderQuirks } from "../provider-def.js";
 export interface OpenAIChatTransportConfig {
     baseUrl: string;
     /** Additional headers (e.g. for specific providers) */
@@ -22,6 +23,8 @@ export interface OpenAIChatTransportConfig {
     supportsStreamOptions?: boolean;
     /** Whether to omit temperature when it equals 0 (e.g. Moonshot rejects 0) */
     omitZeroTemperature?: boolean;
+    /** Provider-specific quirks (CC/altcode parity) */
+    quirks?: ProviderQuirks;
 }
 export declare class OpenAIChatTransport implements LLMTransport {
     private baseUrl;
@@ -29,8 +32,46 @@ export declare class OpenAIChatTransport implements LLMTransport {
     private timeoutMs;
     private supportsStreamOptions;
     private omitZeroTemperature;
+    private quirks;
+    private cumulativeReasoningLen;
+    private cumulativeContentLen;
     constructor(config: OpenAIChatTransportConfig);
     stream(request: LLMRequest, apiKey: string, signal?: AbortSignal): AsyncGenerator<LLMChunk>;
-    private parseSSEStream;
-    private mapChunk;
+    private fetchAndStream;
+    /**
+     * Handle non-streaming JSON response from providers that ignore stream:true.
+     * Synthesize the same LLMChunk events a streaming response would produce.
+     */
+    private handleNonStreamingResponse;
+    /**
+     * Parse SSE stream with 90s idle watchdog (CC parity).
+     * If no data arrives within STREAM_IDLE_TIMEOUT_MS, throw to trigger retry.
+     */
+    private parseSSEStreamWithWatchdog;
+    private processChunk;
+    /**
+     * FIM completion via /beta/v1/completions.
+     * Only works with DeepSeek (requires supportsPrefixCompletion quirk).
+     * Non-thinking mode only; max completion 4K tokens.
+     */
+    complete(request: FIMRequest, apiKey: string, signal?: AbortSignal): AsyncGenerator<FIMChunk>;
+    /**
+     * Upload a file for use in conversations (Kimi File API).
+     * Returns a file_id that can be referenced in user messages.
+     * POST /v1/files with multipart/form-data.
+     */
+    uploadFile(fileBlob: Blob, filename: string, purpose: string, apiKey: string, signal?: AbortSignal): Promise<{
+        fileId: string;
+        filename: string;
+        bytes: number;
+    }>;
+    /**
+     * Get file content/status — GET /v1/files/{file_id}
+     */
+    getFileInfo(fileId: string, apiKey: string, signal?: AbortSignal): Promise<{
+        id: string;
+        filename: string;
+        bytes: number;
+        status: string;
+    }>;
 }

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;
+}