@yourgpt/llm-sdk 2.5.0 → 2.5.1-beta.1

package/dist/base-BYQKp9TW.d.mts

@@ -0,0 +1,263 @@
+import { k as Message, A as ActionDefinition, d as ToolDefinition, R as ResponseFormat, M as McpServerConfig, g as ReasoningEffort, W as WebSearchConfig, P as ProviderToolRuntimeOptions, h as StreamEvent, O as TokenUsage, Z as LLMConfig, a8 as MessageAttachment } from './types-D774b0dg.mjs';
+
+/**
+ * Request-level LLM configuration overrides
+ */
+interface RequestLLMConfig {
+    model?: string;
+    temperature?: number;
+    maxTokens?: number;
+    responseFormat?: ResponseFormat;
+    /** MCP servers exposed to the model for this request (provider-translated). */
+    mcpServers?: McpServerConfig[];
+    /** Reasoning/thinking effort knob (provider-translated). */
+    reasoningEffort?: ReasoningEffort;
+}
+/**
+ * Chat completion request
+ */
+interface ChatCompletionRequest {
+    /** Conversation messages */
+    messages: Message[];
+    /**
+     * Raw provider-formatted messages (for agent loop with tool calls)
+     * When provided, these are used instead of converting from Message[]
+     * This allows passing messages with tool_calls and tool role
+     */
+    rawMessages?: Array<Record<string, unknown>>;
+    /** Available actions/tools */
+    actions?: ActionDefinition[];
+    /** Full tool definitions for provider-native tool search / deferred loading paths. */
+    toolDefinitions?: ToolDefinition[];
+    /** System prompt */
+    systemPrompt?: string;
+    /** LLM configuration overrides */
+    config?: RequestLLMConfig;
+    /** Abort signal for cancellation */
+    signal?: AbortSignal;
+    /**
+     * Enable native web search for the provider.
+     * When true or configured, the provider's native search is enabled.
+     */
+    webSearch?: boolean | WebSearchConfig;
+    /** Optional provider-specific tool policy hints derived from runtime selection. */
+    providerToolOptions?: ProviderToolRuntimeOptions;
+    /** Enable adapter-level provider payload logging. */
+    debug?: boolean;
+}
+/**
+ * Non-streaming completion result
+ */
+interface CompletionResult {
+    /** Text content */
+    content: string;
+    /** Tool calls */
+    toolCalls: Array<{
+        id: string;
+        name: string;
+        args: Record<string, unknown>;
+        /** Provider-specific metadata (e.g. Gemini 3 thought_signature in extra_content.google) */
+        extra_content?: Record<string, unknown>;
+    }>;
+    /** Thinking content (if extended thinking enabled) */
+    thinking?: string;
+    /** Token usage for billing/tracking */
+    usage?: TokenUsage;
+    /** Raw provider response for debugging */
+    rawResponse: Record<string, unknown>;
+}
+/**
+ * Base LLM adapter interface
+ */
+interface LLMAdapter {
+    /** Provider name */
+    readonly provider: string;
+    /** Model name */
+    readonly model: string;
+    /**
+     * Stream a chat completion
+     */
+    stream(request: ChatCompletionRequest): AsyncGenerator<StreamEvent>;
+    /**
+     * Non-streaming chat completion (for debugging/comparison)
+     */
+    complete?(request: ChatCompletionRequest): Promise<CompletionResult>;
+}
+/**
+ * Adapter factory function type
+ */
+type AdapterFactory = (config: LLMConfig) => LLMAdapter;
+/**
+ * Convert messages to provider format (simple text only)
+ */
+declare function formatMessages(messages: Message[], systemPrompt?: string): Array<{
+    role: string;
+    content: string;
+}>;
+/**
+ * Convert actions to OpenAI tool format
+ */
+declare function formatTools(actions: ActionDefinition[]): Array<{
+    type: "function";
+    function: {
+        name: string;
+        description: string;
+        parameters: object;
+    };
+}>;
+/**
+ * Content block types for multimodal messages
+ */
+type AnthropicContentBlock = {
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    source: {
+        type: "base64";
+        media_type: string;
+        data: string;
+    } | {
+        type: "url";
+        url: string;
+    };
+} | {
+    type: "document";
+    source: {
+        type: "base64";
+        media_type: string;
+        data: string;
+    } | {
+        type: "url";
+        url: string;
+    };
+};
+type OpenAIContentBlock = {
+    type: "text";
+    text: string;
+} | {
+    type: "image_url";
+    image_url: {
+        url: string;
+        detail?: "low" | "high" | "auto";
+    };
+};
+/**
+ * Check if a message has image attachments
+ * Supports both new format (metadata.attachments) and legacy (attachments)
+ */
+declare function hasImageAttachments(message: Message): boolean;
+/**
+ * Check if a message has media attachments (images or PDFs)
+ */
+declare function hasMediaAttachments(message: Message): boolean;
+/**
+ * Convert MessageAttachment to Anthropic image content block
+ *
+ * Anthropic format:
+ * {
+ *   type: "image",
+ *   source: {
+ *     type: "base64",
+ *     media_type: "image/png",
+ *     data: "base64data..."
+ *   }
+ * }
+ */
+declare function attachmentToAnthropicImage(attachment: MessageAttachment): AnthropicContentBlock | null;
+/**
+ * Convert MessageAttachment to OpenAI image_url content block
+ *
+ * OpenAI format:
+ * {
+ *   type: "image_url",
+ *   image_url: {
+ *     url: "data:image/png;base64,..."
+ *   }
+ * }
+ */
+declare function attachmentToOpenAIImage(attachment: MessageAttachment): OpenAIContentBlock | null;
+/**
+ * Convert MessageAttachment (PDF) to Anthropic document content block
+ *
+ * Anthropic format:
+ * {
+ *   type: "document",
+ *   source: {
+ *     type: "base64",
+ *     media_type: "application/pdf",
+ *     data: "base64data..."
+ *   }
+ * }
+ */
+declare function attachmentToAnthropicDocument(attachment: MessageAttachment): AnthropicContentBlock | null;
+/**
+ * Convert a Message to Anthropic multimodal content blocks
+ */
+declare function messageToAnthropicContent(message: Message): string | AnthropicContentBlock[];
+/**
+ * Convert a Message to OpenAI multimodal content blocks
+ */
+declare function messageToOpenAIContent(message: Message): string | OpenAIContentBlock[];
+/**
+ * Anthropic content block types (extended for tools)
+ */
+type AnthropicToolUseBlock = {
+    type: "tool_use";
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+};
+type AnthropicToolResultBlock = {
+    type: "tool_result";
+    tool_use_id: string;
+    content: string;
+};
+type AnthropicMessageContent = string | Array<AnthropicContentBlock | AnthropicToolUseBlock | AnthropicToolResultBlock>;
+/**
+ * Format messages for Anthropic with full tool support
+ * Handles: text, images, tool_use, and tool_result
+ *
+ * Key differences from OpenAI:
+ * - tool_calls become tool_use blocks in assistant content
+ * - tool results become tool_result blocks in user content
+ */
+declare function formatMessagesForAnthropic(messages: Message[], systemPrompt?: string): {
+    system: string;
+    messages: Array<{
+        role: "user" | "assistant";
+        content: AnthropicMessageContent;
+    }>;
+};
+/**
+ * OpenAI message format with tool support
+ */
+type OpenAIMessage = {
+    role: "system";
+    content: string;
+} | {
+    role: "user";
+    content: string | OpenAIContentBlock[];
+} | {
+    role: "assistant";
+    content: string | null;
+    tool_calls?: Array<{
+        id: string;
+        type: "function";
+        function: {
+            name: string;
+            arguments: string;
+        };
+    }>;
+} | {
+    role: "tool";
+    content: string;
+    tool_call_id: string;
+};
+/**
+ * Format messages for OpenAI with full tool support
+ * Handles: text, images, tool_calls, and tool results
+ */
+declare function formatMessagesForOpenAI(messages: Message[], systemPrompt?: string): OpenAIMessage[];
+
+export { type AdapterFactory as A, type ChatCompletionRequest as C, type LLMAdapter as L, type OpenAIContentBlock as O, type CompletionResult as a, formatTools as b, formatMessagesForAnthropic as c, formatMessagesForOpenAI as d, messageToOpenAIContent as e, formatMessages as f, hasMediaAttachments as g, hasImageAttachments as h, attachmentToAnthropicImage as i, attachmentToAnthropicDocument as j, attachmentToOpenAIImage as k, type AnthropicContentBlock as l, messageToAnthropicContent as m };

package/dist/base-Cxq3ni0t.d.ts

@@ -0,0 +1,263 @@
+import { k as Message, A as ActionDefinition, d as ToolDefinition, R as ResponseFormat, M as McpServerConfig, g as ReasoningEffort, W as WebSearchConfig, P as ProviderToolRuntimeOptions, h as StreamEvent, O as TokenUsage, Z as LLMConfig, a8 as MessageAttachment } from './types-D774b0dg.js';
+
+/**
+ * Request-level LLM configuration overrides
+ */
+interface RequestLLMConfig {
+    model?: string;
+    temperature?: number;
+    maxTokens?: number;
+    responseFormat?: ResponseFormat;
+    /** MCP servers exposed to the model for this request (provider-translated). */
+    mcpServers?: McpServerConfig[];
+    /** Reasoning/thinking effort knob (provider-translated). */
+    reasoningEffort?: ReasoningEffort;
+}
+/**
+ * Chat completion request
+ */
+interface ChatCompletionRequest {
+    /** Conversation messages */
+    messages: Message[];
+    /**
+     * Raw provider-formatted messages (for agent loop with tool calls)
+     * When provided, these are used instead of converting from Message[]
+     * This allows passing messages with tool_calls and tool role
+     */
+    rawMessages?: Array<Record<string, unknown>>;
+    /** Available actions/tools */
+    actions?: ActionDefinition[];
+    /** Full tool definitions for provider-native tool search / deferred loading paths. */
+    toolDefinitions?: ToolDefinition[];
+    /** System prompt */
+    systemPrompt?: string;
+    /** LLM configuration overrides */
+    config?: RequestLLMConfig;
+    /** Abort signal for cancellation */
+    signal?: AbortSignal;
+    /**
+     * Enable native web search for the provider.
+     * When true or configured, the provider's native search is enabled.
+     */
+    webSearch?: boolean | WebSearchConfig;
+    /** Optional provider-specific tool policy hints derived from runtime selection. */
+    providerToolOptions?: ProviderToolRuntimeOptions;
+    /** Enable adapter-level provider payload logging. */
+    debug?: boolean;
+}
+/**
+ * Non-streaming completion result
+ */
+interface CompletionResult {
+    /** Text content */
+    content: string;
+    /** Tool calls */
+    toolCalls: Array<{
+        id: string;
+        name: string;
+        args: Record<string, unknown>;
+        /** Provider-specific metadata (e.g. Gemini 3 thought_signature in extra_content.google) */
+        extra_content?: Record<string, unknown>;
+    }>;
+    /** Thinking content (if extended thinking enabled) */
+    thinking?: string;
+    /** Token usage for billing/tracking */
+    usage?: TokenUsage;
+    /** Raw provider response for debugging */
+    rawResponse: Record<string, unknown>;
+}
+/**
+ * Base LLM adapter interface
+ */
+interface LLMAdapter {
+    /** Provider name */
+    readonly provider: string;
+    /** Model name */
+    readonly model: string;
+    /**
+     * Stream a chat completion
+     */
+    stream(request: ChatCompletionRequest): AsyncGenerator<StreamEvent>;
+    /**
+     * Non-streaming chat completion (for debugging/comparison)
+     */
+    complete?(request: ChatCompletionRequest): Promise<CompletionResult>;
+}
+/**
+ * Adapter factory function type
+ */
+type AdapterFactory = (config: LLMConfig) => LLMAdapter;
+/**
+ * Convert messages to provider format (simple text only)
+ */
+declare function formatMessages(messages: Message[], systemPrompt?: string): Array<{
+    role: string;
+    content: string;
+}>;
+/**
+ * Convert actions to OpenAI tool format
+ */
+declare function formatTools(actions: ActionDefinition[]): Array<{
+    type: "function";
+    function: {
+        name: string;
+        description: string;
+        parameters: object;
+    };
+}>;
+/**
+ * Content block types for multimodal messages
+ */
+type AnthropicContentBlock = {
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    source: {
+        type: "base64";
+        media_type: string;
+        data: string;
+    } | {
+        type: "url";
+        url: string;
+    };
+} | {
+    type: "document";
+    source: {
+        type: "base64";
+        media_type: string;
+        data: string;
+    } | {
+        type: "url";
+        url: string;
+    };
+};
+type OpenAIContentBlock = {
+    type: "text";
+    text: string;
+} | {
+    type: "image_url";
+    image_url: {
+        url: string;
+        detail?: "low" | "high" | "auto";
+    };
+};
+/**
+ * Check if a message has image attachments
+ * Supports both new format (metadata.attachments) and legacy (attachments)
+ */
+declare function hasImageAttachments(message: Message): boolean;
+/**
+ * Check if a message has media attachments (images or PDFs)
+ */
+declare function hasMediaAttachments(message: Message): boolean;
+/**
+ * Convert MessageAttachment to Anthropic image content block
+ *
+ * Anthropic format:
+ * {
+ *   type: "image",
+ *   source: {
+ *     type: "base64",
+ *     media_type: "image/png",
+ *     data: "base64data..."
+ *   }
+ * }
+ */
+declare function attachmentToAnthropicImage(attachment: MessageAttachment): AnthropicContentBlock | null;
+/**
+ * Convert MessageAttachment to OpenAI image_url content block
+ *
+ * OpenAI format:
+ * {
+ *   type: "image_url",
+ *   image_url: {
+ *     url: "data:image/png;base64,..."
+ *   }
+ * }
+ */
+declare function attachmentToOpenAIImage(attachment: MessageAttachment): OpenAIContentBlock | null;
+/**
+ * Convert MessageAttachment (PDF) to Anthropic document content block
+ *
+ * Anthropic format:
+ * {
+ *   type: "document",
+ *   source: {
+ *     type: "base64",
+ *     media_type: "application/pdf",
+ *     data: "base64data..."
+ *   }
+ * }
+ */
+declare function attachmentToAnthropicDocument(attachment: MessageAttachment): AnthropicContentBlock | null;
+/**
+ * Convert a Message to Anthropic multimodal content blocks
+ */
+declare function messageToAnthropicContent(message: Message): string | AnthropicContentBlock[];
+/**
+ * Convert a Message to OpenAI multimodal content blocks
+ */
+declare function messageToOpenAIContent(message: Message): string | OpenAIContentBlock[];
+/**
+ * Anthropic content block types (extended for tools)
+ */
+type AnthropicToolUseBlock = {
+    type: "tool_use";
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+};
+type AnthropicToolResultBlock = {
+    type: "tool_result";
+    tool_use_id: string;
+    content: string;
+};
+type AnthropicMessageContent = string | Array<AnthropicContentBlock | AnthropicToolUseBlock | AnthropicToolResultBlock>;
+/**
+ * Format messages for Anthropic with full tool support
+ * Handles: text, images, tool_use, and tool_result
+ *
+ * Key differences from OpenAI:
+ * - tool_calls become tool_use blocks in assistant content
+ * - tool results become tool_result blocks in user content
+ */
+declare function formatMessagesForAnthropic(messages: Message[], systemPrompt?: string): {
+    system: string;
+    messages: Array<{
+        role: "user" | "assistant";
+        content: AnthropicMessageContent;
+    }>;
+};
+/**
+ * OpenAI message format with tool support
+ */
+type OpenAIMessage = {
+    role: "system";
+    content: string;
+} | {
+    role: "user";
+    content: string | OpenAIContentBlock[];
+} | {
+    role: "assistant";
+    content: string | null;
+    tool_calls?: Array<{
+        id: string;
+        type: "function";
+        function: {
+            name: string;
+            arguments: string;
+        };
+    }>;
+} | {
+    role: "tool";
+    content: string;
+    tool_call_id: string;
+};
+/**
+ * Format messages for OpenAI with full tool support
+ * Handles: text, images, tool_calls, and tool results
+ */
+declare function formatMessagesForOpenAI(messages: Message[], systemPrompt?: string): OpenAIMessage[];
+
+export { type AdapterFactory as A, type ChatCompletionRequest as C, type LLMAdapter as L, type OpenAIContentBlock as O, type CompletionResult as a, formatTools as b, formatMessagesForAnthropic as c, formatMessagesForOpenAI as d, messageToOpenAIContent as e, formatMessages as f, hasMediaAttachments as g, hasImageAttachments as h, attachmentToAnthropicImage as i, attachmentToAnthropicDocument as j, attachmentToOpenAIImage as k, type AnthropicContentBlock as l, messageToAnthropicContent as m };

package/dist/fallback/index.d.mts

@@ -1,7 +1,7 @@
-import { L as LLMAdapter } from '../base-D-U61JaB.mjs';
-import { F as FallbackChainConfig, c as FallbackFailure, R as RoutingStore } from '../types-D4YfrQJR.mjs';
-export { d as FallbackInfo, b as RetryBackoff, e as RetryInfo, a as RoutingStrategy } from '../types-D4YfrQJR.mjs';
-import '../types-CR8mi9I0.mjs';
+import { L as LLMAdapter } from '../base-BYQKp9TW.mjs';
+import { F as FallbackChainConfig, c as FallbackFailure, R as RoutingStore } from '../types-mwMhCwOq.mjs';
+export { d as FallbackInfo, b as RetryBackoff, e as RetryInfo, a as RoutingStrategy } from '../types-mwMhCwOq.mjs';
+import '../types-D774b0dg.mjs';
 import 'zod';
 
 /**

package/dist/fallback/index.d.ts

@@ -1,7 +1,7 @@
-import { L as LLMAdapter } from '../base-iGi9Va6Z.js';
-import { F as FallbackChainConfig, c as FallbackFailure, R as RoutingStore } from '../types-38yolWJn.js';
-export { d as FallbackInfo, b as RetryBackoff, e as RetryInfo, a as RoutingStrategy } from '../types-38yolWJn.js';
-import '../types-CR8mi9I0.js';
+import { L as LLMAdapter } from '../base-Cxq3ni0t.js';
+import { F as FallbackChainConfig, c as FallbackFailure, R as RoutingStore } from '../types-ChORafYS.js';
+export { d as FallbackInfo, b as RetryBackoff, e as RetryInfo, a as RoutingStrategy } from '../types-ChORafYS.js';
+import '../types-D774b0dg.js';
 import 'zod';
 
 /**

package/dist/index.d.mts

@@ -1,13 +1,13 @@
-import { G as GenerateTextParams, a as GenerateTextResult, S as StreamTextParams, b as StreamTextResult, T as ToolContext, c as Tool, d as StorageAdapter, e as StorageMessage } from './types-CR8mi9I0.mjs';
-export { A as AssistantMessage, C as CoreMessage, w as DEFAULT_CAPABILITIES, D as DoGenerateParams, f as DoGenerateResult, E as ErrorChunk, F as FilePart, s as FinishChunk, u as FinishReason, m as GenerateStep, I as ImagePart, L as LanguageModel, M as ModelCapabilities, R as ResponseOptions, v as StorageFile, o as StreamChunk, n as StreamPart, g as SystemMessage, p as TextDeltaChunk, j as TextPart, t as TokenUsage, k as ToolCall, q as ToolCallChunk, h as ToolMessage, l as ToolResult, r as ToolResultChunk, i as UserContentPart, U as UserMessage } from './types-CR8mi9I0.mjs';
+import { G as GenerateTextParams, a as GenerateTextResult, S as StreamTextParams, b as StreamTextResult, T as ToolContext, c as Tool, A as ActionDefinition, d as ToolDefinition, e as ToolProfile, K as KnowledgeBaseConfig, W as WebSearchConfig, f as StorageAdapter, R as ResponseFormat, M as McpServerConfig, g as ReasoningEffort, D as DoneEventMessage, h as StreamEvent, i as ToolCallInfo, j as TokenUsageRaw, P as ProviderToolRuntimeOptions, k as Message, l as ToolResponse, m as StorageMessage } from './types-D774b0dg.mjs';
+export { a6 as AnthropicProviderToolOptions, a3 as AnthropicToolSelectionHints, r as AssistantMessage, a7 as Citation, C as CoreMessage, Y as DEFAULT_CAPABILITIES, o as DoGenerateParams, p as DoGenerateResult, N as ErrorChunk, F as FilePart, J as FinishChunk, Q as FinishReason, x as GenerateStep, I as ImagePart, Z as LLMConfig, L as LanguageModel, n as ModelCapabilities, a5 as OpenAIProviderToolOptions, a2 as OpenAIToolSelectionHints, V as ResponseOptions, X as StorageFile, z as StreamChunk, y as StreamPart, q as SystemMessage, B as TextDeltaChunk, u as TextPart, O as TokenUsage, v as ToolCall, E as ToolCallChunk, a1 as ToolExecution, _ as ToolLocation, s as ToolMessage, a4 as ToolNativeProviderHints, w as ToolResult, H as ToolResultChunk, $ as UnifiedToolCall, a0 as UnifiedToolResult, t as UserContentPart, U as UserMessage } from './types-D774b0dg.mjs';
 import { z } from 'zod';
-import { A as ActionDefinition, T as ToolDefinition, a as ToolProfile, K as KnowledgeBaseConfig, W as WebSearchConfig, L as LLMAdapter, D as DoneEventMessage, S as StreamEvent, b as ToolCallInfo, c as TokenUsageRaw, P as ProviderToolRuntimeOptions, M as Message, d as ToolResponse } from './base-D-U61JaB.mjs';
-export { e as AdapterFactory, m as AnthropicProviderToolOptions, j as AnthropicToolSelectionHints, C as ChatCompletionRequest, n as Citation, f as LLMConfig, l as OpenAIProviderToolOptions, O as OpenAIToolSelectionHints, i as ToolExecution, g as ToolLocation, k as ToolNativeProviderHints, U as UnifiedToolCall, h as UnifiedToolResult } from './base-D-U61JaB.mjs';
-import { A as AIProvider } from './types-DRqxMIjF.mjs';
-export { a as AnthropicProviderConfig, f as AnthropicTool, h as AnthropicToolResult, g as AnthropicToolUse, b as AzureProviderConfig, B as BaseProviderConfig, m as GeminiFunctionCall, l as GeminiFunctionDeclaration, n as GeminiFunctionResponse, G as GoogleProviderConfig, d as OllamaModelOptions, c as OllamaProviderConfig, O as OpenAIProviderConfig, i as OpenAITool, j as OpenAIToolCall, k as OpenAIToolResult, P as ProviderCapabilities, e as ProviderFormatter, X as XAIProviderConfig } from './types-DRqxMIjF.mjs';
+import { A as AIProvider } from './types-BvkiJ1dd.mjs';
+export { a as AnthropicProviderConfig, f as AnthropicTool, h as AnthropicToolResult, g as AnthropicToolUse, b as AzureProviderConfig, B as BaseProviderConfig, m as GeminiFunctionCall, l as GeminiFunctionDeclaration, n as GeminiFunctionResponse, G as GoogleProviderConfig, d as OllamaModelOptions, c as OllamaProviderConfig, O as OpenAIProviderConfig, i as OpenAITool, j as OpenAIToolCall, k as OpenAIToolResult, P as ProviderCapabilities, e as ProviderFormatter, X as XAIProviderConfig } from './types-BvkiJ1dd.mjs';
+import { L as LLMAdapter } from './base-BYQKp9TW.mjs';
+export { A as AdapterFactory, C as ChatCompletionRequest } from './base-BYQKp9TW.mjs';
 import * as hono from 'hono';
 import { Hono } from 'hono';
-export { F as FallbackChainConfig, c as FallbackFailure, d as FallbackInfo, b as RetryBackoff, e as RetryInfo, R as RoutingStore, a as RoutingStrategy } from './types-D4YfrQJR.mjs';
+export { F as FallbackChainConfig, c as FallbackFailure, d as FallbackInfo, b as RetryBackoff, e as RetryInfo, R as RoutingStore, a as RoutingStrategy } from './types-mwMhCwOq.mjs';
 
 /**
  * generateText - Generate text using a language model
@@ -388,6 +388,9 @@ interface ChatRequest {
     config?: {
         temperature?: number;
         maxTokens?: number;
+        responseFormat?: ResponseFormat;
+        mcpServers?: McpServerConfig[];
+        reasoningEffort?: ReasoningEffort;
     };
     /** System prompt override */
     systemPrompt?: string;
@@ -797,6 +800,11 @@ declare function createStreamResult(generator: AsyncGenerator<StreamEvent>): Str
  * ```
  */
 
+interface GenerateUsage {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+}
 interface GenerateResultData {
     text: string;
     messages: DoneEventMessage[];
@@ -810,6 +818,7 @@ interface GenerateResultData {
         result: unknown;
     }>;
     requiresAction: boolean;
+    usage?: GenerateUsage;
     error?: {
         message: string;
         code?: string;
@@ -863,6 +872,12 @@ declare class GenerateResult {
      * Whether client action is required (e.g., tool approval)
      */
     get requiresAction(): boolean;
+    /**
+     * Token usage for the call — present when the underlying provider emitted
+     * a usage payload on the `done` event. May be undefined for streaming
+     * responses that don't yield usage (e.g. mid-stream errors).
+     */
+    get usage(): GenerateUsage | undefined;
     /**
      * Error if generation failed
      */
@@ -1122,6 +1137,44 @@ declare class Runtime {
      * ```
      */
     generate(request: ChatRequest, options?: GenerateOptions): Promise<GenerateResult>;
+    /**
+     * One-shot non-streaming call bundling MCP servers, reasoning effort, and
+     * structured output. Thin ergonomic wrapper around `generate()` — uses the
+     * same adapter chain and the same translators, just expressed as a single
+     * prompt-in / text-out call.
+     *
+     * @example
+     * ```ts
+     * const result = await runtime.response({
+     *   prompt: "Extract FAQs from this conversation.",
+     *   mcpServers: [{ label: "kb", url: "https://kb.example.com/sse", headers: { Authorization: token } }],
+     *   reasoningEffort: "high",
+     *   responseFormat: { type: "json_schema", json_schema: { name: "faqs", schema } },
+     * });
+     * const data = JSON.parse(result.text);
+     * ```
+     */
+    response(request: {
+        prompt: string;
+        systemPrompt?: string;
+        mcpServers?: McpServerConfig[];
+        reasoningEffort?: ReasoningEffort;
+        responseFormat?: ResponseFormat;
+        maxTokens?: number;
+        temperature?: number;
+    }): Promise<{
+        text: string;
+        toolCalls: Array<{
+            id: string;
+            name: string;
+            args: Record<string, unknown>;
+        }>;
+        usage?: {
+            promptTokens: number;
+            completionTokens: number;
+            totalTokens: number;
+        };
+    }>;
     /**
      * Create Express-compatible handler middleware
      *
@@ -1536,4 +1589,4 @@ declare function generateThreadId(): string;
  */
 declare function generateToolCallId(): string;
 
-export { AIProvider, ActionDefinition, type ActionRequest, type AgentLoopOptions, type ChatRequest, type CollectedResult, type CopilotChatResponse, DEFAULT_MAX_ITERATIONS, DoneEventMessage, GenerateResult, type GenerateResultData, GenerateTextParams, GenerateTextResult, LLMAdapter, Message, ProviderToolRuntimeOptions, type RequestContext, Runtime, type RuntimeConfig, StorageAdapter, StorageMessage, StreamEvent, StreamResult, type StreamResultOptions, StreamTextParams, StreamTextResult, TokenUsageRaw, Tool, ToolCallInfo, ToolContext, ToolDefinition, ToolProfile, ToolResponse, type ToolSearchMatch, WebSearchConfig, buildProviderToolOptions, createEventStream, createExpressHandler, createExpressMiddleware, createHonoApp, createNextHandler, createNodeHandler, createRuntime, createSSEHeaders, createSSEResponse, createStreamResult, createTextStreamHeaders, createTextStreamResponse, extractInputMessages, formatSSEData, formatToolsForAnthropic, formatToolsForGoogle, formatToolsForOpenAI, generateMessageId, generateText, generateThreadId, generateToolCallId, mapOutputMessages, pipeSSEToResponse, pipeTextToResponse, runAgentLoop, searchTools, selectTools, shouldExposeToolSearch, streamText, tool };
+export { AIProvider, ActionDefinition, type ActionRequest, type AgentLoopOptions, type ChatRequest, type CollectedResult, type CopilotChatResponse, DEFAULT_MAX_ITERATIONS, DoneEventMessage, GenerateResult, type GenerateResultData, GenerateTextParams, GenerateTextResult, LLMAdapter, McpServerConfig, Message, ProviderToolRuntimeOptions, ReasoningEffort, type RequestContext, ResponseFormat, Runtime, type RuntimeConfig, StorageAdapter, StorageMessage, StreamEvent, StreamResult, type StreamResultOptions, StreamTextParams, StreamTextResult, TokenUsageRaw, Tool, ToolCallInfo, ToolContext, ToolDefinition, ToolProfile, ToolResponse, type ToolSearchMatch, WebSearchConfig, buildProviderToolOptions, createEventStream, createExpressHandler, createExpressMiddleware, createHonoApp, createNextHandler, createNodeHandler, createRuntime, createSSEHeaders, createSSEResponse, createStreamResult, createTextStreamHeaders, createTextStreamResponse, extractInputMessages, formatSSEData, formatToolsForAnthropic, formatToolsForGoogle, formatToolsForOpenAI, generateMessageId, generateText, generateThreadId, generateToolCallId, mapOutputMessages, pipeSSEToResponse, pipeTextToResponse, runAgentLoop, searchTools, selectTools, shouldExposeToolSearch, streamText, tool };