190proof 1.0.96 → 1.0.97

package/dist/index.d.mts

@@ -55,12 +55,94 @@ declare enum GeminiModel {
     GEMINI_3_FLASH_PREVIEW = "gemini-3-flash-preview",
     GEMINI_3_1_FLASH_LITE_PREVIEW = "gemini-3.1-flash-lite-preview"
 }
+/**
+ * A single conversation turn passed to `callWithRetries`. The SDK serializes
+ * these into each provider's native message format.
+ *
+ * ## Multi-turn tool calls
+ * To continue after the model calls a tool, append the model's own assistant
+ * turn and then the tool result, then call again:
+ *
+ * 1. Read the assistant turn off the response: `function_calls` (each with an
+ *    `id`) and — for reasoning models — `reasoning` / `reasoningDetails`.
+ * 2. Push back an `assistant` message carrying those same `functionCalls` (and,
+ *    to keep the model's chain-of-thought, the captured reasoning fields).
+ * 3. Push back one `role: "tool"` message whose `toolResults` answer each call
+ *    by `toolCallId`.
+ *
+ * The SDK is a pure transport: it does NOT echo reasoning or pair results for
+ * you — it serializes exactly what you put here. Every tool/reasoning field is
+ * optional, so a plain `{ role, content }` message behaves as before.
+ *
+ * @example
+ * // turn 1 — model asks for the weather
+ * const a = await callWithRetries(id, { model, messages, functions });
+ * // a.function_calls -> [{ id: "call_abc", name: "get_weather", arguments: { city: "Tokyo" } }]
+ *
+ * // turn 2 — feed the call + its result back
+ * const next = await callWithRetries(id, { model, functions, messages: [
+ *   ...messages,
+ *   { role: "assistant", content: a.content ?? "", functionCalls: a.function_calls,
+ *     reasoning: a.reasoning, reasoningDetails: a.reasoningDetails },
+ *   { role: "tool", content: "", toolResults: [
+ *     { toolCallId: "call_abc", name: "get_weather", content: '{"tempC":22}' } ] },
+ * ]});
+ */
 interface GenericMessage {
-    role: "user" | "assistant" | "system";
+    /**
+     * `"tool"` carries tool results (see `toolResults`) back to the model and
+     * must immediately follow the `assistant` turn that made the matching calls.
+     */
+    role: "user" | "assistant" | "system" | "tool";
+    /** Plain-text content. Use `""` for a tool-call-only or tool-result turn. */
     content: string;
     timestamp?: string;
     files?: File[];
+    /**
+     * Tool calls the model made on an `assistant` turn. Pass back the `id`s you
+     * received in `ParsedResponseMessage.function_calls` so the provider can pair
+     * them with the `toolResults` that follow.
+     */
     functionCalls?: FunctionCall[];
+    /**
+     * Tool outputs on a `role: "tool"` message — one entry per call (parallel
+     * calls produce several). Each `toolCallId` must match a `FunctionCall.id`
+     * from the preceding assistant turn.
+     */
+    toolResults?: ToolResult[];
+    /**
+     * Optional reasoning string to echo back on an `assistant` turn (e.g.
+     * OpenRouter/DeepSeek `reasoning`). Round-tripping it keeps the model's
+     * chain-of-thought across tool calls; some thinking models (DeepSeek V4)
+     * require it to avoid a 400 on the next turn.
+     */
+    reasoning?: string;
+    /**
+     * Optional structured reasoning to echo back on an `assistant` turn
+     * (OpenRouter `reasoning_details`, or Anthropic `thinking` /
+     * `redacted_thinking` blocks captured in
+     * `ParsedResponseMessage.reasoningDetails`). Preserves the signatures /
+     * encrypted payloads that providers validate on round-trip.
+     */
+    reasoningDetails?: any;
+}
+/**
+ * The result of executing one tool call, fed back to the model on a
+ * `role: "tool"` message. The SDK maps this to each provider's native shape:
+ * OpenAI/Groq/OpenRouter `{ role: "tool", tool_call_id, content }`, Anthropic a
+ * `tool_result` block, Google a `functionResponse` part.
+ */
+interface ToolResult {
+    /** The `id` of the `FunctionCall` this answers (from the prior assistant turn). */
+    toolCallId: string;
+    /**
+     * The tool/function name. Required by Anthropic and Google on round-trip; the
+     * SDK falls back to the matching call's name when omitted, but supplying it is
+     * recommended.
+     */
+    name?: string;
+    /** The tool output, serialized to a string (JSON or plain text). */
+    content: string;
 }
 interface File {
     mimeType: string;
@@ -70,9 +152,24 @@ interface File {
 interface ParsedResponseMessage {
     role: "assistant";
     content: string | null;
+    /** First of `function_calls` (backward-compat); carries `id` when the provider returns one. */
     function_call: FunctionCall | null;
+    /** All tool calls the model made this turn, each with an `id` for round-tripping. */
     function_calls: FunctionCall[];
     files: File[];
+    /**
+     * Reasoning string from reasoning models (OpenRouter/DeepSeek `reasoning`).
+     * Echo back via `GenericMessage.reasoning` to preserve chain-of-thought across
+     * tool calls. Undefined when the model/provider returns none.
+     */
+    reasoning?: string;
+    /**
+     * Structured reasoning (OpenRouter `reasoning_details`, or Anthropic
+     * `thinking` / `redacted_thinking` blocks). Echo back verbatim via
+     * `GenericMessage.reasoningDetails` — it carries signatures some providers
+     * validate. Undefined when the model/provider returns none.
+     */
+    reasoningDetails?: any;
     usage: {
         prompt_tokens: number;
         completion_tokens: number;
@@ -82,12 +179,22 @@ interface ParsedResponseMessage {
     } | null;
 }
 interface FunctionCall {
+    /**
+     * Provider tool-call id, surfaced on responses and used to pair a call with
+     * its `ToolResult.toolCallId` on the next turn. The SDK synthesizes
+     * `call_<index>` for providers that don't return one (e.g. Google).
+     */
+    id?: string;
     name: string;
     arguments: Record<string, any>;
-}
-interface FunctionCall {
-    name: string;
-    arguments: Record<string, any>;
+    /**
+     * Opaque per-call signature that must be echoed back verbatim on round-trip.
+     * Currently Google's `thoughtSignature` — Gemini REQUIRES it on functionCall
+     * parts in multi-turn tool use (a missing one 400s the next request). The SDK
+     * captures it on responses and re-emits it when you pass the call back;
+     * undefined for providers that don't use one.
+     */
+    thoughtSignature?: string;
 }
 interface OpenAIConfig {
     service: "azure" | "openai";
@@ -158,4 +265,4 @@ declare function parseModelString(model: string): {
 };
 declare function callWithRetries(id: string | string[], aiPayload: GenericPayload, aiConfig?: OpenAIConfig | AnthropicAIConfig, retries?: number, chunkTimeoutMs?: number): Promise<ParsedResponseMessage>;
 
-export { type AnyModel, ClaudeModel, type FunctionDefinition, GPTModel, GeminiModel, type GenericMessage, type GenericPayload, GroqModel, type OpenAIConfig, OpenRouterModel, type Provider, callWithRetries, parseModelString };
+export { type AnyModel, ClaudeModel, type FunctionCall, type FunctionDefinition, GPTModel, GeminiModel, type GenericMessage, type GenericPayload, GroqModel, type OpenAIConfig, OpenRouterModel, type OpenRouterProviderPreferences, type ParsedResponseMessage, type Provider, type ToolResult, callWithRetries, parseModelString };

package/dist/index.d.ts

@@ -55,12 +55,94 @@ declare enum GeminiModel {
     GEMINI_3_FLASH_PREVIEW = "gemini-3-flash-preview",
     GEMINI_3_1_FLASH_LITE_PREVIEW = "gemini-3.1-flash-lite-preview"
 }
+/**
+ * A single conversation turn passed to `callWithRetries`. The SDK serializes
+ * these into each provider's native message format.
+ *
+ * ## Multi-turn tool calls
+ * To continue after the model calls a tool, append the model's own assistant
+ * turn and then the tool result, then call again:
+ *
+ * 1. Read the assistant turn off the response: `function_calls` (each with an
+ *    `id`) and — for reasoning models — `reasoning` / `reasoningDetails`.
+ * 2. Push back an `assistant` message carrying those same `functionCalls` (and,
+ *    to keep the model's chain-of-thought, the captured reasoning fields).
+ * 3. Push back one `role: "tool"` message whose `toolResults` answer each call
+ *    by `toolCallId`.
+ *
+ * The SDK is a pure transport: it does NOT echo reasoning or pair results for
+ * you — it serializes exactly what you put here. Every tool/reasoning field is
+ * optional, so a plain `{ role, content }` message behaves as before.
+ *
+ * @example
+ * // turn 1 — model asks for the weather
+ * const a = await callWithRetries(id, { model, messages, functions });
+ * // a.function_calls -> [{ id: "call_abc", name: "get_weather", arguments: { city: "Tokyo" } }]
+ *
+ * // turn 2 — feed the call + its result back
+ * const next = await callWithRetries(id, { model, functions, messages: [
+ *   ...messages,
+ *   { role: "assistant", content: a.content ?? "", functionCalls: a.function_calls,
+ *     reasoning: a.reasoning, reasoningDetails: a.reasoningDetails },
+ *   { role: "tool", content: "", toolResults: [
+ *     { toolCallId: "call_abc", name: "get_weather", content: '{"tempC":22}' } ] },
+ * ]});
+ */
 interface GenericMessage {
-    role: "user" | "assistant" | "system";
+    /**
+     * `"tool"` carries tool results (see `toolResults`) back to the model and
+     * must immediately follow the `assistant` turn that made the matching calls.
+     */
+    role: "user" | "assistant" | "system" | "tool";
+    /** Plain-text content. Use `""` for a tool-call-only or tool-result turn. */
     content: string;
     timestamp?: string;
     files?: File[];
+    /**
+     * Tool calls the model made on an `assistant` turn. Pass back the `id`s you
+     * received in `ParsedResponseMessage.function_calls` so the provider can pair
+     * them with the `toolResults` that follow.
+     */
     functionCalls?: FunctionCall[];
+    /**
+     * Tool outputs on a `role: "tool"` message — one entry per call (parallel
+     * calls produce several). Each `toolCallId` must match a `FunctionCall.id`
+     * from the preceding assistant turn.
+     */
+    toolResults?: ToolResult[];
+    /**
+     * Optional reasoning string to echo back on an `assistant` turn (e.g.
+     * OpenRouter/DeepSeek `reasoning`). Round-tripping it keeps the model's
+     * chain-of-thought across tool calls; some thinking models (DeepSeek V4)
+     * require it to avoid a 400 on the next turn.
+     */
+    reasoning?: string;
+    /**
+     * Optional structured reasoning to echo back on an `assistant` turn
+     * (OpenRouter `reasoning_details`, or Anthropic `thinking` /
+     * `redacted_thinking` blocks captured in
+     * `ParsedResponseMessage.reasoningDetails`). Preserves the signatures /
+     * encrypted payloads that providers validate on round-trip.
+     */
+    reasoningDetails?: any;
+}
+/**
+ * The result of executing one tool call, fed back to the model on a
+ * `role: "tool"` message. The SDK maps this to each provider's native shape:
+ * OpenAI/Groq/OpenRouter `{ role: "tool", tool_call_id, content }`, Anthropic a
+ * `tool_result` block, Google a `functionResponse` part.
+ */
+interface ToolResult {
+    /** The `id` of the `FunctionCall` this answers (from the prior assistant turn). */
+    toolCallId: string;
+    /**
+     * The tool/function name. Required by Anthropic and Google on round-trip; the
+     * SDK falls back to the matching call's name when omitted, but supplying it is
+     * recommended.
+     */
+    name?: string;
+    /** The tool output, serialized to a string (JSON or plain text). */
+    content: string;
 }
 interface File {
     mimeType: string;
@@ -70,9 +152,24 @@ interface File {
 interface ParsedResponseMessage {
     role: "assistant";
     content: string | null;
+    /** First of `function_calls` (backward-compat); carries `id` when the provider returns one. */
     function_call: FunctionCall | null;
+    /** All tool calls the model made this turn, each with an `id` for round-tripping. */
     function_calls: FunctionCall[];
     files: File[];
+    /**
+     * Reasoning string from reasoning models (OpenRouter/DeepSeek `reasoning`).
+     * Echo back via `GenericMessage.reasoning` to preserve chain-of-thought across
+     * tool calls. Undefined when the model/provider returns none.
+     */
+    reasoning?: string;
+    /**
+     * Structured reasoning (OpenRouter `reasoning_details`, or Anthropic
+     * `thinking` / `redacted_thinking` blocks). Echo back verbatim via
+     * `GenericMessage.reasoningDetails` — it carries signatures some providers
+     * validate. Undefined when the model/provider returns none.
+     */
+    reasoningDetails?: any;
     usage: {
         prompt_tokens: number;
         completion_tokens: number;
@@ -82,12 +179,22 @@ interface ParsedResponseMessage {
     } | null;
 }
 interface FunctionCall {
+    /**
+     * Provider tool-call id, surfaced on responses and used to pair a call with
+     * its `ToolResult.toolCallId` on the next turn. The SDK synthesizes
+     * `call_<index>` for providers that don't return one (e.g. Google).
+     */
+    id?: string;
     name: string;
     arguments: Record<string, any>;
-}
-interface FunctionCall {
-    name: string;
-    arguments: Record<string, any>;
+    /**
+     * Opaque per-call signature that must be echoed back verbatim on round-trip.
+     * Currently Google's `thoughtSignature` — Gemini REQUIRES it on functionCall
+     * parts in multi-turn tool use (a missing one 400s the next request). The SDK
+     * captures it on responses and re-emits it when you pass the call back;
+     * undefined for providers that don't use one.
+     */
+    thoughtSignature?: string;
 }
 interface OpenAIConfig {
     service: "azure" | "openai";
@@ -158,4 +265,4 @@ declare function parseModelString(model: string): {
 };
 declare function callWithRetries(id: string | string[], aiPayload: GenericPayload, aiConfig?: OpenAIConfig | AnthropicAIConfig, retries?: number, chunkTimeoutMs?: number): Promise<ParsedResponseMessage>;
 
-export { type AnyModel, ClaudeModel, type FunctionDefinition, GPTModel, GeminiModel, type GenericMessage, type GenericPayload, GroqModel, type OpenAIConfig, OpenRouterModel, type Provider, callWithRetries, parseModelString };
+export { type AnyModel, ClaudeModel, type FunctionCall, type FunctionDefinition, GPTModel, GeminiModel, type GenericMessage, type GenericPayload, GroqModel, type OpenAIConfig, OpenRouterModel, type OpenRouterProviderPreferences, type ParsedResponseMessage, type Provider, type ToolResult, callWithRetries, parseModelString };