@shareai-lab/kode-sdk 1.0.0-beta.8 → 2.7.0

package/dist/infra/providers/types.d.ts

@@ -0,0 +1,334 @@
+/**
+ * Provider Adapter Types
+ *
+ * KODE Agent SDK uses Anthropic-style messages as the internal canonical format.
+ * All providers act as adapters that convert to/from this format.
+ *
+ * Internal Flow:
+ *   Internal Message[] (Anthropic-style ContentBlocks)
+ *     -> Provider.formatMessages() -> External API format
+ *     -> API call
+ *     -> Response -> normalizeContent() -> Internal ContentBlock[]
+ *
+ * Provider-Specific Requirements:
+ * - Anthropic: Preserve thinking signatures for multi-turn
+ * - OpenAI Responses: Use previous_response_id for state
+ * - DeepSeek/Qwen: Must NOT include reasoning_content in history
+ * - Gemini: Use thinkingLevel (not thinkingBudget) for 3.x
+ */
+import { Message, ContentBlock } from '../../core/types';
+import { Configurable } from '../../core/config';
+import { UsageStatistics } from './core/usage';
+/**
+ * Standard model response in Anthropic-style format.
+ * All providers convert their responses to this format.
+ */
+export interface ModelResponse {
+    role: 'assistant';
+    content: ContentBlock[];
+    usage?: {
+        input_tokens: number;
+        output_tokens: number;
+        cache_creation_input_tokens?: number;
+        cache_read_input_tokens?: number;
+    };
+    stop_reason?: string;
+    extendedUsage?: UsageStatistics;
+}
+/**
+ * Streaming chunk in Anthropic-style format.
+ * All providers emit chunks in this format.
+ */
+export interface ModelStreamChunk {
+    type: 'content_block_start' | 'content_block_delta' | 'content_block_stop' | 'message_delta' | 'message_stop';
+    index?: number;
+    content_block?: ContentBlock;
+    delta?: {
+        type: 'text_delta' | 'input_json_delta' | 'reasoning_delta';
+        text?: string;
+        partial_json?: string;
+    };
+    usage?: {
+        input_tokens?: number;
+        output_tokens: number;
+    };
+}
+/**
+ * File upload input.
+ */
+export interface UploadFileInput {
+    data: Buffer;
+    mimeType: string;
+    filename?: string;
+    kind: 'image' | 'file';
+}
+/**
+ * File upload result.
+ */
+export interface UploadFileResult {
+    fileId?: string;
+    fileUri?: string;
+}
+/**
+ * Thinking/reasoning configuration options.
+ * Each provider interprets these options according to their API:
+ *
+ * - Anthropic: thinking.budget_tokens, interleaved-thinking-2025-05-14 beta
+ * - OpenAI: reasoning_effort for Responses API (none/minimal/low/medium/high/xhigh)
+ * - Gemini: thinkingBudget (2.5 models) or thinkingLevel (3.x models)
+ */
+export interface ThinkingOptions {
+    /** Enable thinking/reasoning mode */
+    enabled?: boolean;
+    /** Budget tokens for reasoning (Anthropic: budget_tokens, Gemini: thinkingBudget) */
+    budgetTokens?: number;
+    /** Reasoning effort level (OpenAI: reasoning_effort) */
+    effort?: 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh';
+    /** Thinking level preset (Gemini 3.x: thinkingLevel) */
+    level?: 'minimal' | 'low' | 'medium' | 'high';
+}
+/**
+ * How reasoning/thinking content is transported in messages.
+ * - 'provider': Native provider format (Anthropic thinking blocks, OpenAI reasoning tokens)
+ * - 'text': Wrapped in <think></think> tags as text
+ * - 'omit': Excluded from message history
+ */
+export type ReasoningTransport = 'omit' | 'text' | 'provider';
+/**
+ * Multimodal content handling options.
+ */
+export interface MultimodalOptions {
+    /** URL handling mode */
+    mode?: 'url' | 'url+base64';
+    /** Maximum size for base64 encoded content */
+    maxBase64Bytes?: number;
+    /** Allowed MIME types */
+    allowMimeTypes?: string[];
+}
+/**
+ * Core model configuration.
+ * Provider implementations extend this with provider-specific options.
+ */
+export interface ModelConfig {
+    provider: 'anthropic' | 'openai' | 'gemini' | string;
+    model: string;
+    baseUrl?: string;
+    apiKey?: string;
+    proxyUrl?: string;
+    maxTokens?: number;
+    temperature?: number;
+    reasoningTransport?: ReasoningTransport;
+    extraHeaders?: Record<string, string>;
+    extraBody?: Record<string, any>;
+    providerOptions?: Record<string, any>;
+    multimodal?: MultimodalOptions;
+    thinking?: ThinkingOptions;
+}
+/**
+ * Options for model completion requests.
+ */
+export interface CompletionOptions {
+    tools?: any[];
+    maxTokens?: number;
+    temperature?: number;
+    system?: string;
+    stream?: boolean;
+    thinking?: ThinkingOptions;
+}
+/**
+ * Core model provider interface.
+ * All provider implementations must conform to this interface.
+ *
+ * The adapter pattern:
+ * 1. Input: SDK internal Message[] (Anthropic-style ContentBlocks)
+ * 2. Provider converts to external API format
+ * 3. Provider calls external API
+ * 4. Provider converts response back to internal format
+ * 5. Output: ModelResponse with Anthropic-style ContentBlocks
+ */
+export interface ModelProvider extends Configurable<ModelConfig> {
+    /** Model identifier */
+    readonly model: string;
+    /** Maximum context window size in tokens */
+    readonly maxWindowSize: number;
+    /** Maximum output tokens */
+    readonly maxOutputTokens: number;
+    /** Default temperature */
+    readonly temperature: number;
+    /**
+     * Complete a message sequence.
+     * @param messages - Messages in internal Anthropic-style format
+     * @param opts - Completion options
+     * @returns Response in internal format
+     */
+    complete(messages: Message[], opts?: CompletionOptions): Promise<ModelResponse>;
+    /**
+     * Stream a completion.
+     * @param messages - Messages in internal Anthropic-style format
+     * @param opts - Completion options
+     * @returns Async iterable of chunks in internal format
+     */
+    stream(messages: Message[], opts?: CompletionOptions): AsyncIterable<ModelStreamChunk>;
+    /**
+     * Upload a file to the provider (optional).
+     * @param input - File upload input
+     * @returns Upload result or null if not supported
+     */
+    uploadFile?(input: UploadFileInput): Promise<UploadFileResult | null>;
+}
+/**
+ * Provider capabilities declaration.
+ * Used to check feature support before making requests.
+ */
+export interface ProviderCapabilities {
+    supportsThinking: boolean;
+    supportsInterleavedThinking: boolean;
+    supportsImages: boolean;
+    supportsAudio: boolean;
+    supportsFiles: boolean;
+    supportsTools: boolean;
+    supportsStreaming: boolean;
+    supportsCache: boolean;
+    maxContextTokens: number;
+    maxOutputTokens: number;
+    minCacheableTokens?: number;
+    maxCacheBreakpoints?: number;
+}
+/**
+ * Cache control options.
+ */
+export interface CacheControl {
+    type: 'ephemeral';
+    ttl?: '5m' | '1h';
+}
+/**
+ * Provider-specific Anthropic options.
+ */
+export interface AnthropicProviderOptions {
+    reasoningTransport?: ReasoningTransport;
+    extraHeaders?: Record<string, string>;
+    extraBody?: Record<string, any>;
+    providerOptions?: Record<string, any>;
+    multimodal?: MultimodalOptions;
+    thinking?: {
+        enabled: boolean;
+        budgetTokens?: number;
+    };
+    beta?: {
+        interleavedThinking?: boolean;
+        filesApi?: boolean;
+        extendedCacheTtl?: boolean;
+    };
+    cache?: {
+        breakpoints?: number;
+        defaultTtl?: '5m' | '1h';
+    };
+}
+/**
+ * Provider-specific OpenAI options.
+ * For detailed configuration, see openai.ts ReasoningConfig and ResponsesApiConfig.
+ */
+export interface OpenAIProviderOptions {
+    /** API type: 'chat' for Chat Completions, 'responses' for Responses API */
+    api?: 'chat' | 'responses';
+    reasoningTransport?: ReasoningTransport;
+    extraHeaders?: Record<string, string>;
+    extraBody?: Record<string, any>;
+    providerOptions?: Record<string, any>;
+    multimodal?: MultimodalOptions;
+    /**
+     * Reasoning configuration for OpenAI-compatible providers.
+     * Configure field names and request parameters for DeepSeek, GLM, Minimax, Qwen, etc.
+     */
+    reasoning?: {
+        /** Field name: 'reasoning_content' (DeepSeek/GLM/Qwen) or 'reasoning_details' (Minimax) */
+        fieldName?: 'reasoning_content' | 'reasoning_details';
+        /** Request parameters to enable reasoning (e.g., { thinking: { type: 'enabled' } }) */
+        requestParams?: Record<string, any>;
+        /** Strip reasoning from history (required for DeepSeek) */
+        stripFromHistory?: boolean;
+    };
+    /** Responses API specific options */
+    responses?: {
+        reasoning?: {
+            effort: 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh';
+        };
+        store?: boolean;
+        previousResponseId?: string;
+    };
+    /** Streaming options */
+    streamOptions?: {
+        includeUsage?: boolean;
+    };
+}
+/**
+ * Provider-specific Gemini options.
+ */
+export interface GeminiProviderOptions {
+    reasoningTransport?: ReasoningTransport;
+    extraHeaders?: Record<string, string>;
+    extraBody?: Record<string, any>;
+    providerOptions?: Record<string, any>;
+    multimodal?: MultimodalOptions;
+    thinking?: {
+        level: 'minimal' | 'low' | 'medium' | 'high';
+        includeThoughts?: boolean;
+    };
+    cache?: {
+        cachedContentName?: string;
+        createCache?: {
+            displayName: string;
+            ttlSeconds: number;
+        };
+    };
+    mediaResolution?: 'low' | 'medium' | 'high';
+}
+/**
+ * Provider-specific DeepSeek options.
+ */
+export interface DeepSeekProviderOptions {
+    reasoningTransport?: ReasoningTransport;
+    extraHeaders?: Record<string, string>;
+    extraBody?: Record<string, any>;
+    providerOptions?: Record<string, any>;
+    thinking?: {
+        enabled: boolean;
+    };
+}
+/**
+ * Provider-specific Qwen options.
+ */
+export interface QwenProviderOptions {
+    reasoningTransport?: ReasoningTransport;
+    extraHeaders?: Record<string, string>;
+    extraBody?: Record<string, any>;
+    providerOptions?: Record<string, any>;
+    thinking?: {
+        enabled: boolean;
+        budget?: number;
+    };
+    region?: 'beijing' | 'singapore' | 'virginia';
+}
+/**
+ * Provider-specific GLM options.
+ */
+export interface GLMProviderOptions {
+    reasoningTransport?: ReasoningTransport;
+    extraHeaders?: Record<string, string>;
+    extraBody?: Record<string, any>;
+    providerOptions?: Record<string, any>;
+    thinking?: {
+        enabled: boolean;
+    };
+    maxFunctions?: number;
+}
+/**
+ * Provider-specific Minimax options.
+ */
+export interface MinimaxProviderOptions {
+    reasoningTransport?: ReasoningTransport;
+    extraHeaders?: Record<string, string>;
+    extraBody?: Record<string, any>;
+    providerOptions?: Record<string, any>;
+    reasoningSplit?: boolean;
+}

package/dist/infra/providers/types.js

@@ -0,0 +1,20 @@
+"use strict";
+/**
+ * Provider Adapter Types
+ *
+ * KODE Agent SDK uses Anthropic-style messages as the internal canonical format.
+ * All providers act as adapters that convert to/from this format.
+ *
+ * Internal Flow:
+ *   Internal Message[] (Anthropic-style ContentBlocks)
+ *     -> Provider.formatMessages() -> External API format
+ *     -> API call
+ *     -> Response -> normalizeContent() -> Internal ContentBlock[]
+ *
+ * Provider-Specific Requirements:
+ * - Anthropic: Preserve thinking signatures for multi-turn
+ * - OpenAI Responses: Use previous_response_id for state
+ * - DeepSeek/Qwen: Must NOT include reasoning_content in history
+ * - Gemini: Use thinkingLevel (not thinkingBudget) for 3.x
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/infra/providers/utils.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Shared utilities for provider implementations.
+ */
+import { ContentBlock, Message, ImageContentBlock, FileContentBlock } from '../../core/types';
+import { ReasoningTransport } from './types';
+export declare function resolveProxyUrl(explicit?: string): string | undefined;
+export declare function getProxyDispatcher(proxyUrl?: string): any | undefined;
+export declare function withProxy(init: RequestInit, dispatcher?: any): RequestInit;
+export declare function normalizeBaseUrl(url: string): string;
+export declare function normalizeOpenAIBaseUrl(url: string): string;
+export declare function normalizeAnthropicBaseUrl(url: string): string;
+export declare function normalizeGeminiBaseUrl(url: string): string;
+export declare function getMessageBlocks(message: Message): ContentBlock[];
+export declare function markTransportIfDegraded(message: Message, blocks: ContentBlock[]): void;
+export declare function joinTextBlocks(blocks: ContentBlock[]): string;
+export declare function formatToolResult(content: any): string;
+export declare function safeJsonStringify(value: any): string;
+export declare const FILE_UNSUPPORTED_TEXT = "[file unsupported] This model does not support PDF input. Please extract text or images first.";
+export declare const IMAGE_UNSUPPORTED_TEXT = "[image unsupported] This model does not support image URLs; please provide base64 data if supported.";
+export declare const AUDIO_UNSUPPORTED_TEXT = "[audio unsupported] This model does not support audio input; please provide a text transcript instead.";
+export declare function concatTextWithReasoning(blocks: ContentBlock[], reasoningTransport?: ReasoningTransport): string;
+export declare function joinReasoningBlocks(blocks: ContentBlock[]): string;
+/**
+ * Parse <think> tags in text blocks and convert to reasoning blocks.
+ */
+export declare function normalizeThinkBlocks(blocks: ContentBlock[], reasoningTransport?: ReasoningTransport): ContentBlock[];
+export declare function splitThinkText(text: string): ContentBlock[];
+/**
+ * Extract reasoning details from OpenAI response (for reasoning models).
+ */
+export declare function extractReasoningDetails(message: any): ContentBlock[];
+export declare function buildGeminiImagePart(block: ImageContentBlock): any | null;
+export declare function buildGeminiFilePart(block: FileContentBlock): any | null;
+export declare function sanitizeGeminiSchema(schema: any): any;
+export declare function hasAnthropicFileBlocks(messages: Message[]): boolean;
+export declare function mergeAnthropicBetaHeader(existing: string | undefined, entries: string[]): string | undefined;
+/**
+ * Normalize Anthropic response content to internal format.
+ */
+export declare function normalizeAnthropicContent(content: any[], reasoningTransport?: ReasoningTransport): ContentBlock[];
+/**
+ * Normalize a single Anthropic content block.
+ * Handles thinking blocks with signature preservation.
+ */
+export declare function normalizeAnthropicContentBlock(block: any, reasoningTransport?: ReasoningTransport): ContentBlock | null;
+/**
+ * Normalize Anthropic streaming delta.
+ */
+export declare function normalizeAnthropicDelta(delta: any): {
+    type: 'text_delta' | 'input_json_delta' | 'reasoning_delta';
+    text?: string;
+    partial_json?: string;
+};