@kenkaiiii/gg-ai 5.87.3 → 5.88.0

package/dist/index.d.cts

@@ -60,6 +60,13 @@ interface ToolResult {
         /** Which budget triggered the trim. */
         scope: "per-result" | "per-turn";
     };
+    /**
+     * Deferred tools (names from `StreamOptions.deferredTools`) that became
+     * callable while this tool ran. Providers with transcript-anchored tool
+     * loading (Anthropic `tool_reference`, OpenAI client `tool_search_output`)
+     * load them here instead of growing the cached `tools` block.
+     */
+    loadedTools?: string[];
 }
 interface ServerToolCall {
     type: "server_tool_call";
@@ -219,6 +226,14 @@ interface StreamOptions {
     model: string;
     messages: Message[];
     tools?: Tool[];
+    /**
+     * Stable, ordered catalog of on-demand tools (a superset of any of them that
+     * are live in `tools`). Providers that support deferred tool loading send
+     * the whole catalog from the first request and load a tool through the
+     * transcript (see `ToolResult.loadedTools`), so the cached tools block never
+     * changes. Others ignore it and send `tools` only.
+     */
+    deferredTools?: Tool[];
     toolChoice?: ToolChoice;
     serverTools?: ServerToolDefinition[];
     maxTokens?: number;
@@ -685,6 +700,36 @@ declare class ProviderRegistryImpl {
 /** Global provider registry. Import this to register custom providers. */
 declare const providerRegistry: ProviderRegistryImpl;
 
+/**
+ * How long a pre-opened origin counts as warm. Matches the pool's idle
+ * keep-alive (PROVIDER_KEEP_ALIVE_TIMEOUT_MS): inside this window the socket a
+ * previous request or pre-open left is still pooled, so another one is waste.
+ */
+declare const PRECONNECT_INTERVAL_MS = 30000;
+/** The https origin a route's connections pool under, or undefined when none is worth opening. */
+declare function preconnectOrigin(options: {
+    provider: Provider;
+    baseUrl?: string;
+    accountId?: string;
+}): string | undefined;
+interface PreconnectOptions {
+    provider: Provider;
+    baseUrl?: string;
+    accountId?: string;
+    /** Last pre-open per origin (ms). Callers own it, so state is never module-global. */
+    warmedAt: Map<string, number>;
+    now?: number;
+    fetch?: typeof globalThis.fetch;
+}
+/**
+ * Open the DNS+TCP+TLS connection to the provider's origin ahead of the first
+ * real request, through the same keep-alive pool those requests use. Sends a
+ * bodiless, unauthenticated `HEAD <baseUrl>` — no credentials, no tokens, no side
+ * effects — and drops whatever comes back. Fire-and-forget: never throws.
+ * Returns the origin it opened, or undefined when it skipped.
+ */
+declare function preconnectProvider(options: PreconnectOptions): string | undefined;
+
 /**
  * Error model for gg-ai and downstream consumers.
  *
@@ -976,6 +1021,9 @@ declare function toAnthropicMessages(messages: Message[], cacheControl?: {
      * request carries the server-side-fallback beta; otherwise they are
      * stripped (after applying the replay rules). Default false. */
     fallbackBlocks?: boolean;
+    /** Deferred tools to load in place: a tool result that names one in
+     * `loadedTools` carries `tool_reference` blocks (see planDeferredTools). */
+    toolReferences?: ReadonlySet<string>;
 }): {
     system: Anthropic.TextBlockParam[] | undefined;
     messages: Anthropic.MessageParam[];
@@ -1117,4 +1165,4 @@ declare function palsuEmbedding(text: string, dimensions?: number): number[];
 /** Deterministic fake relevance: the share of distinct query words found in the document (0–1). */
 declare function palsuRerankScore(query: string, document: string): number;
 
-export { type AssistantMessage, CLAUDE_CODE_FALLBACK_VERSION, CODEX_CLIENT_VERSION, type CacheRetention, type ChatErrorReason, type ContentPart, type DoneEvent, type EmbedInputType, type EmbedOptions, type EmbedResult, type EmbedUsage, type ErrorEvent, type ErrorSource, EventStream, FAST_MODE_SUFFIX, type FastModeRejection, type FastModeResolution, type FormattedChatError, type FormattedError, GGAIError, type ImageContent, type Message, type MessageProvenance, type MessageProvenanceKind, type MessageProvenanceSource, type MessageProvenanceVisibility, type OpenRouterProviderPreferences, type PalsuModelConfig, type PalsuModelHandle, type PalsuProviderConfig, type PalsuProviderHandle, type PalsuProviderState, type PalsuResponse, type PalsuResponseFactory, type PreparedContext, type Provider, type ProviderCapability, type ProviderDiagnosticFn, type ProviderEmbedFn, type ProviderEmbedRequest, type ProviderEmbedResponse, type ProviderEntry, ProviderError, type ProviderOptions, type ProviderRerankFn, type ProviderRerankRequest, type ProviderRerankResponse, type ProviderStreamFn, REDACTED as REDACTION_MARKER, type RawContent, type RedactionOptions, type RerankOptions, type RerankResponse, type RerankResult, type RerankUsage, ResponseStalledError, type ServerToolCall, type ServerToolCallEvent, type ServerToolDefinition, type ServerToolResult, type ServerToolResultEvent, type StopReason, type StreamEvent, type StreamOptions, type StreamResponse, StreamResult, type SystemMessage, TOOL_CALL_NAME_RULES, type TextContent, type TextDeltaEvent, type ThinkingContent, type ThinkingDeltaEvent, type ThinkingLevel, type Tool, type ToolCall, type ToolCallDeltaEvent, type ToolCallDoneEvent, type ToolCallNameRule, type ToolChoice, type ToolResult, type ToolResultContent, type ToolResultMessage, type Usage, type UserMessage, type VideoContent, clampProviderContextImages, classifyProviderError, continuesTurn, describeFastModeRejection, dropInvalidToolCalls, embed, environmentSecrets, formatChatError, formatError, formatErrorForDisplay, getClaudeCliUserAgent, getClaudeCodeVersion, hasLoneSurrogate, isHardBillingMessage, isUsageLimitError, isValidToolCallName, localWireModelId, opensTurn, palsuAssistantMessage, palsuEmbedding, palsuRerankScore, palsuText, palsuThinking, palsuToolCall, parseFastModeRejection, pendingClaudeCodeVersionRefresh, prewarmAnthropicCache, providerRegistry, redactText, redactValue, registerPalsuProvider, rerank, resolveFastModeModel, resolveToolSchema, sanitizeMessagesForWire, setProviderDiagnostic, sliceHead, sliceTail, stream, toAnthropicMessages, toOpenAIMessages, toWellFormedText, toolCallNameRuleFor, usesResponsesLite };
+export { type AssistantMessage, CLAUDE_CODE_FALLBACK_VERSION, CODEX_CLIENT_VERSION, type CacheRetention, type ChatErrorReason, type ContentPart, type DoneEvent, type EmbedInputType, type EmbedOptions, type EmbedResult, type EmbedUsage, type ErrorEvent, type ErrorSource, EventStream, FAST_MODE_SUFFIX, type FastModeRejection, type FastModeResolution, type FormattedChatError, type FormattedError, GGAIError, type ImageContent, type Message, type MessageProvenance, type MessageProvenanceKind, type MessageProvenanceSource, type MessageProvenanceVisibility, type OpenRouterProviderPreferences, PRECONNECT_INTERVAL_MS, type PalsuModelConfig, type PalsuModelHandle, type PalsuProviderConfig, type PalsuProviderHandle, type PalsuProviderState, type PalsuResponse, type PalsuResponseFactory, type PreconnectOptions, type PreparedContext, type Provider, type ProviderCapability, type ProviderDiagnosticFn, type ProviderEmbedFn, type ProviderEmbedRequest, type ProviderEmbedResponse, type ProviderEntry, ProviderError, type ProviderOptions, type ProviderRerankFn, type ProviderRerankRequest, type ProviderRerankResponse, type ProviderStreamFn, REDACTED as REDACTION_MARKER, type RawContent, type RedactionOptions, type RerankOptions, type RerankResponse, type RerankResult, type RerankUsage, ResponseStalledError, type ServerToolCall, type ServerToolCallEvent, type ServerToolDefinition, type ServerToolResult, type ServerToolResultEvent, type StopReason, type StreamEvent, type StreamOptions, type StreamResponse, StreamResult, type SystemMessage, TOOL_CALL_NAME_RULES, type TextContent, type TextDeltaEvent, type ThinkingContent, type ThinkingDeltaEvent, type ThinkingLevel, type Tool, type ToolCall, type ToolCallDeltaEvent, type ToolCallDoneEvent, type ToolCallNameRule, type ToolChoice, type ToolResult, type ToolResultContent, type ToolResultMessage, type Usage, type UserMessage, type VideoContent, clampProviderContextImages, classifyProviderError, continuesTurn, describeFastModeRejection, dropInvalidToolCalls, embed, environmentSecrets, formatChatError, formatError, formatErrorForDisplay, getClaudeCliUserAgent, getClaudeCodeVersion, hasLoneSurrogate, isHardBillingMessage, isUsageLimitError, isValidToolCallName, localWireModelId, opensTurn, palsuAssistantMessage, palsuEmbedding, palsuRerankScore, palsuText, palsuThinking, palsuToolCall, parseFastModeRejection, pendingClaudeCodeVersionRefresh, preconnectOrigin, preconnectProvider, prewarmAnthropicCache, providerRegistry, redactText, redactValue, registerPalsuProvider, rerank, resolveFastModeModel, resolveToolSchema, sanitizeMessagesForWire, setProviderDiagnostic, sliceHead, sliceTail, stream, toAnthropicMessages, toOpenAIMessages, toWellFormedText, toolCallNameRuleFor, usesResponsesLite };

package/dist/index.d.ts

@@ -60,6 +60,13 @@ interface ToolResult {
         /** Which budget triggered the trim. */
         scope: "per-result" | "per-turn";
     };
+    /**
+     * Deferred tools (names from `StreamOptions.deferredTools`) that became
+     * callable while this tool ran. Providers with transcript-anchored tool
+     * loading (Anthropic `tool_reference`, OpenAI client `tool_search_output`)
+     * load them here instead of growing the cached `tools` block.
+     */
+    loadedTools?: string[];
 }
 interface ServerToolCall {
     type: "server_tool_call";
@@ -219,6 +226,14 @@ interface StreamOptions {
     model: string;
     messages: Message[];
     tools?: Tool[];
+    /**
+     * Stable, ordered catalog of on-demand tools (a superset of any of them that
+     * are live in `tools`). Providers that support deferred tool loading send
+     * the whole catalog from the first request and load a tool through the
+     * transcript (see `ToolResult.loadedTools`), so the cached tools block never
+     * changes. Others ignore it and send `tools` only.
+     */
+    deferredTools?: Tool[];
     toolChoice?: ToolChoice;
     serverTools?: ServerToolDefinition[];
     maxTokens?: number;
@@ -685,6 +700,36 @@ declare class ProviderRegistryImpl {
 /** Global provider registry. Import this to register custom providers. */
 declare const providerRegistry: ProviderRegistryImpl;
 
+/**
+ * How long a pre-opened origin counts as warm. Matches the pool's idle
+ * keep-alive (PROVIDER_KEEP_ALIVE_TIMEOUT_MS): inside this window the socket a
+ * previous request or pre-open left is still pooled, so another one is waste.
+ */
+declare const PRECONNECT_INTERVAL_MS = 30000;
+/** The https origin a route's connections pool under, or undefined when none is worth opening. */
+declare function preconnectOrigin(options: {
+    provider: Provider;
+    baseUrl?: string;
+    accountId?: string;
+}): string | undefined;
+interface PreconnectOptions {
+    provider: Provider;
+    baseUrl?: string;
+    accountId?: string;
+    /** Last pre-open per origin (ms). Callers own it, so state is never module-global. */
+    warmedAt: Map<string, number>;
+    now?: number;
+    fetch?: typeof globalThis.fetch;
+}
+/**
+ * Open the DNS+TCP+TLS connection to the provider's origin ahead of the first
+ * real request, through the same keep-alive pool those requests use. Sends a
+ * bodiless, unauthenticated `HEAD <baseUrl>` — no credentials, no tokens, no side
+ * effects — and drops whatever comes back. Fire-and-forget: never throws.
+ * Returns the origin it opened, or undefined when it skipped.
+ */
+declare function preconnectProvider(options: PreconnectOptions): string | undefined;
+
 /**
  * Error model for gg-ai and downstream consumers.
  *
@@ -976,6 +1021,9 @@ declare function toAnthropicMessages(messages: Message[], cacheControl?: {
      * request carries the server-side-fallback beta; otherwise they are
      * stripped (after applying the replay rules). Default false. */
     fallbackBlocks?: boolean;
+    /** Deferred tools to load in place: a tool result that names one in
+     * `loadedTools` carries `tool_reference` blocks (see planDeferredTools). */
+    toolReferences?: ReadonlySet<string>;
 }): {
     system: Anthropic.TextBlockParam[] | undefined;
     messages: Anthropic.MessageParam[];
@@ -1117,4 +1165,4 @@ declare function palsuEmbedding(text: string, dimensions?: number): number[];
 /** Deterministic fake relevance: the share of distinct query words found in the document (0–1). */
 declare function palsuRerankScore(query: string, document: string): number;
 
-export { type AssistantMessage, CLAUDE_CODE_FALLBACK_VERSION, CODEX_CLIENT_VERSION, type CacheRetention, type ChatErrorReason, type ContentPart, type DoneEvent, type EmbedInputType, type EmbedOptions, type EmbedResult, type EmbedUsage, type ErrorEvent, type ErrorSource, EventStream, FAST_MODE_SUFFIX, type FastModeRejection, type FastModeResolution, type FormattedChatError, type FormattedError, GGAIError, type ImageContent, type Message, type MessageProvenance, type MessageProvenanceKind, type MessageProvenanceSource, type MessageProvenanceVisibility, type OpenRouterProviderPreferences, type PalsuModelConfig, type PalsuModelHandle, type PalsuProviderConfig, type PalsuProviderHandle, type PalsuProviderState, type PalsuResponse, type PalsuResponseFactory, type PreparedContext, type Provider, type ProviderCapability, type ProviderDiagnosticFn, type ProviderEmbedFn, type ProviderEmbedRequest, type ProviderEmbedResponse, type ProviderEntry, ProviderError, type ProviderOptions, type ProviderRerankFn, type ProviderRerankRequest, type ProviderRerankResponse, type ProviderStreamFn, REDACTED as REDACTION_MARKER, type RawContent, type RedactionOptions, type RerankOptions, type RerankResponse, type RerankResult, type RerankUsage, ResponseStalledError, type ServerToolCall, type ServerToolCallEvent, type ServerToolDefinition, type ServerToolResult, type ServerToolResultEvent, type StopReason, type StreamEvent, type StreamOptions, type StreamResponse, StreamResult, type SystemMessage, TOOL_CALL_NAME_RULES, type TextContent, type TextDeltaEvent, type ThinkingContent, type ThinkingDeltaEvent, type ThinkingLevel, type Tool, type ToolCall, type ToolCallDeltaEvent, type ToolCallDoneEvent, type ToolCallNameRule, type ToolChoice, type ToolResult, type ToolResultContent, type ToolResultMessage, type Usage, type UserMessage, type VideoContent, clampProviderContextImages, classifyProviderError, continuesTurn, describeFastModeRejection, dropInvalidToolCalls, embed, environmentSecrets, formatChatError, formatError, formatErrorForDisplay, getClaudeCliUserAgent, getClaudeCodeVersion, hasLoneSurrogate, isHardBillingMessage, isUsageLimitError, isValidToolCallName, localWireModelId, opensTurn, palsuAssistantMessage, palsuEmbedding, palsuRerankScore, palsuText, palsuThinking, palsuToolCall, parseFastModeRejection, pendingClaudeCodeVersionRefresh, prewarmAnthropicCache, providerRegistry, redactText, redactValue, registerPalsuProvider, rerank, resolveFastModeModel, resolveToolSchema, sanitizeMessagesForWire, setProviderDiagnostic, sliceHead, sliceTail, stream, toAnthropicMessages, toOpenAIMessages, toWellFormedText, toolCallNameRuleFor, usesResponsesLite };
+export { type AssistantMessage, CLAUDE_CODE_FALLBACK_VERSION, CODEX_CLIENT_VERSION, type CacheRetention, type ChatErrorReason, type ContentPart, type DoneEvent, type EmbedInputType, type EmbedOptions, type EmbedResult, type EmbedUsage, type ErrorEvent, type ErrorSource, EventStream, FAST_MODE_SUFFIX, type FastModeRejection, type FastModeResolution, type FormattedChatError, type FormattedError, GGAIError, type ImageContent, type Message, type MessageProvenance, type MessageProvenanceKind, type MessageProvenanceSource, type MessageProvenanceVisibility, type OpenRouterProviderPreferences, PRECONNECT_INTERVAL_MS, type PalsuModelConfig, type PalsuModelHandle, type PalsuProviderConfig, type PalsuProviderHandle, type PalsuProviderState, type PalsuResponse, type PalsuResponseFactory, type PreconnectOptions, type PreparedContext, type Provider, type ProviderCapability, type ProviderDiagnosticFn, type ProviderEmbedFn, type ProviderEmbedRequest, type ProviderEmbedResponse, type ProviderEntry, ProviderError, type ProviderOptions, type ProviderRerankFn, type ProviderRerankRequest, type ProviderRerankResponse, type ProviderStreamFn, REDACTED as REDACTION_MARKER, type RawContent, type RedactionOptions, type RerankOptions, type RerankResponse, type RerankResult, type RerankUsage, ResponseStalledError, type ServerToolCall, type ServerToolCallEvent, type ServerToolDefinition, type ServerToolResult, type ServerToolResultEvent, type StopReason, type StreamEvent, type StreamOptions, type StreamResponse, StreamResult, type SystemMessage, TOOL_CALL_NAME_RULES, type TextContent, type TextDeltaEvent, type ThinkingContent, type ThinkingDeltaEvent, type ThinkingLevel, type Tool, type ToolCall, type ToolCallDeltaEvent, type ToolCallDoneEvent, type ToolCallNameRule, type ToolChoice, type ToolResult, type ToolResultContent, type ToolResultMessage, type Usage, type UserMessage, type VideoContent, clampProviderContextImages, classifyProviderError, continuesTurn, describeFastModeRejection, dropInvalidToolCalls, embed, environmentSecrets, formatChatError, formatError, formatErrorForDisplay, getClaudeCliUserAgent, getClaudeCodeVersion, hasLoneSurrogate, isHardBillingMessage, isUsageLimitError, isValidToolCallName, localWireModelId, opensTurn, palsuAssistantMessage, palsuEmbedding, palsuRerankScore, palsuText, palsuThinking, palsuToolCall, parseFastModeRejection, pendingClaudeCodeVersionRefresh, preconnectOrigin, preconnectProvider, prewarmAnthropicCache, providerRegistry, redactText, redactValue, registerPalsuProvider, rerank, resolveFastModeModel, resolveToolSchema, sanitizeMessagesForWire, setProviderDiagnostic, sliceHead, sliceTail, stream, toAnthropicMessages, toOpenAIMessages, toWellFormedText, toolCallNameRuleFor, usesResponsesLite };