@prestyj/ai 5.28.1 → 5.29.0

package/dist/index.d.cts

@@ -186,8 +186,24 @@ interface Usage {
         webFetchRequests?: number;
     };
 }
+interface PreparedContext {
+    /** Read-only observation after generic sanitization/image limiting, before provider encoding.
+     * Do not log or retain these messages: they may contain secrets and image data. */
+    messages: readonly Message[];
+    tools: readonly {
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+    }[];
+    imagesBefore: number;
+    imagesAfter: number;
+    /** First message whose images were removed for this request, or null. */
+    firstImageDropMessage: number | null;
+}
 interface StreamOptions {
     provider: Provider;
+    /** Optional, synchronous diagnostics observer. Exceptions cannot fail a model request. */
+    onContextPrepared?: (context: PreparedContext) => void;
     model: string;
     messages: Message[];
     tools?: Tool[];
@@ -245,6 +261,14 @@ interface StreamOptions {
      *  stalls — broken SSE connections (transient CDN / proxy issues) often
      *  recover when the same request is issued over a plain HTTP request/response. */
     streaming?: boolean;
+    /** Cache prewarm (Anthropic only; other providers ignore it). Sends the exact
+     *  same request prefix (system, tools, messages, thinking, betas) with
+     *  `max_tokens: 1` over a non-streaming request so the prompt cache is written
+     *  before the user's next real turn. If the configured thinking mode cannot be
+     *  kept identical at `max_tokens: 1` (budget thinking requires
+     *  budget_tokens < max_tokens), no request is sent and the response has
+     *  zero usage with stopReason "end_turn". */
+    prewarm?: boolean;
     /** Override the User-Agent sent with OAuth-authenticated Anthropic requests.
      *  Anthropic's OAuth edge rejects requests whose claude-cli version lags too
      *  far behind the real Claude Code release; callers that track the live
@@ -570,18 +594,85 @@ type JsonSchema = Record<string, unknown>;
 /**
  * Resolve a tool's JSON Schema for provider tool definitions: prefer the
  * tool's pre-built `rawInputSchema`, otherwise convert its Zod `parameters`.
+ *
+ * A no-argument tool may declare a bare `{ "type": "object" }` root (common
+ * for MCP servers). OpenAI rejects that root with HTTP 400 "object schema
+ * missing properties", failing the whole request, so an object root without
+ * `properties` gets an explicit empty one. JSON Schema meaning is unchanged.
  */
 declare function resolveToolSchema(tool: Tool): JsonSchema;
 
 /**
- * Cap historical images before provider dispatch, removing the oldest first.
+ * Cap historical images before provider dispatch, removing the oldest first, in batches so the
+ * cached conversation prefix stays byte-identical between requests.
  * The persisted/live conversation is never mutated; only modified messages and
  * tool results are cloned for the outgoing request.
  */
 declare function clampProviderContextImages(messages: Message[], provider: Provider, supportsImages: boolean | undefined): Message[];
+/**
+ * What a provider accepts as a replayed tool-call name. `pattern` already
+ * encodes the length limit where the provider documents one; `maxLength` is
+ * checked separately so the generic rule can cap length without a charset.
+ */
+interface ToolCallNameRule {
+    /** Short identifier, for diagnostics and tests. */
+    id: "anthropic" | "openai-chat" | "openai-responses" | "gemini" | "generic";
+    maxLength: number;
+    pattern?: RegExp;
+}
+/**
+ * Per-transport tool-name rules. A legitimate call always carries the name of a
+ * tool we declared, and tool declarations are validated against these same
+ * rules, so only model-invented names (blank, invocation text stuffed into the
+ * name slot, …) can fail them.
+ */
+declare const TOOL_CALL_NAME_RULES: Record<ToolCallNameRule["id"], ToolCallNameRule>;
+/** True when `name` is a tool-call name the provider described by `rule` will accept. */
+declare function isValidToolCallName(name: unknown, rule: ToolCallNameRule): boolean;
+/**
+ * Pick the tool-name rule for the transport a request will actually use. Mirrors
+ * the routing in `stream.ts`: `openai` with an `accountId` is the Codex
+ * (Responses) endpoint, MiniMax rides the Anthropic transport but is a third
+ * party, and an `openai` pointed at a custom baseUrl is an unknown compatible
+ * server.
+ */
+declare function toolCallNameRuleFor(provider: Provider | string, options?: {
+    accountId?: string;
+    baseUrl?: string;
+}): ToolCallNameRule;
+/**
+ * Drop assistant tool calls whose name (or id) the target provider rejects,
+ * together with the tool results that answer them.
+ *
+ * One malformed call — a blank name, a whole invocation string written into the
+ * name slot, a name over the provider's length limit — would otherwise sit in
+ * history and 400 every later request (`tool_use.name: String should match
+ * pattern`, `string_above_max_length`, …), wedging the session.
+ *
+ * Pairing is positional per window: each assistant turn opens a window, and its
+ * results (role `tool`) are matched FIFO per id until the next assistant or user
+ * message, so a reused id never consumes another turn's result. Valid sibling
+ * calls, text and thinking are kept in place. An assistant turn left with
+ * nothing replayable is removed whole, as is a tool message left empty — every
+ * transport accepts the resulting adjacent user turns (the Anthropic API
+ * combines consecutive same-role turns). A Codex reasoning item orphaned by the
+ * drop is removed too. If the drop would leave the request ENDING on that
+ * pruned assistant turn (its only call was the bad one, so no results follow),
+ * the turn is removed as well: a trailing assistant message is an assistant
+ * prefill, which current Claude models reject and other APIs treat as a
+ * continuation rather than a fresh turn.
+ *
+ * Returns the input array untouched when nothing is malformed.
+ */
+declare function dropInvalidToolCalls(messages: Message[], rule: ToolCallNameRule): Message[];
 declare function toAnthropicMessages(messages: Message[], cacheControl?: {
     type: "ephemeral";
     ttl?: "1h";
+}, options?: {
+    /** Replay server-side refusal `fallback` blocks in place. Only set when the
+     * request carries the server-side-fallback beta; otherwise they are
+     * stripped (after applying the replay rules). Default false. */
+    fallbackBlocks?: boolean;
 }): {
     system: Anthropic.TextBlockParam[] | undefined;
     messages: Anthropic.MessageParam[];
@@ -685,4 +776,4 @@ interface PalsuProviderConfig {
  */
 declare function registerPalsuProvider(config?: PalsuProviderConfig): PalsuProviderHandle;
 
-export { type AssistantMessage, type CacheRetention, type ContentPart, type DoneEvent, EZCoderAIError, type ErrorEvent, type ErrorSource, EventStream, type FormattedError, type ImageContent, type Message, type MessageProvenance, type MessageProvenanceKind, type MessageProvenanceSource, type MessageProvenanceVisibility, type PalsuModelConfig, type PalsuModelHandle, type PalsuProviderConfig, type PalsuProviderHandle, type PalsuProviderState, type PalsuResponse, type PalsuResponseFactory, type Provider, type ProviderDiagnosticFn, type ProviderEntry, ProviderError, type ProviderStreamFn, REDACTED as REDACTION_MARKER, type RawContent, type RedactionOptions, type ServerToolCall, type ServerToolCallEvent, type ServerToolDefinition, type ServerToolResult, type ServerToolResultEvent, type StopReason, type StreamEvent, type StreamOptions, type StreamResponse, StreamResult, type SystemMessage, type TextContent, type TextDeltaEvent, type ThinkingContent, type ThinkingDeltaEvent, type ThinkingLevel, type Tool, type ToolCall, type ToolCallDeltaEvent, type ToolCallDoneEvent, type ToolChoice, type ToolResult, type ToolResultContent, type ToolResultMessage, type Usage, type UserMessage, type VideoContent, clampProviderContextImages, classifyProviderError, environmentSecrets, formatError, formatErrorForDisplay, hasLoneSurrogate, isHardBillingMessage, isUsageLimitError, localWireModelId, palsuAssistantMessage, palsuText, palsuThinking, palsuToolCall, prewarmAnthropicCache, providerRegistry, redactText, redactValue, registerPalsuProvider, resolveToolSchema, sanitizeMessagesForWire, setProviderDiagnostic, sliceHead, sliceTail, stream, toAnthropicMessages, toOpenAIMessages, toWellFormedText };
+export { type AssistantMessage, type CacheRetention, type ContentPart, type DoneEvent, EZCoderAIError, type ErrorEvent, type ErrorSource, EventStream, type FormattedError, type ImageContent, type Message, type MessageProvenance, type MessageProvenanceKind, type MessageProvenanceSource, type MessageProvenanceVisibility, type PalsuModelConfig, type PalsuModelHandle, type PalsuProviderConfig, type PalsuProviderHandle, type PalsuProviderState, type PalsuResponse, type PalsuResponseFactory, type PreparedContext, type Provider, type ProviderDiagnosticFn, type ProviderEntry, ProviderError, type ProviderStreamFn, REDACTED as REDACTION_MARKER, type RawContent, type RedactionOptions, 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, dropInvalidToolCalls, environmentSecrets, formatError, formatErrorForDisplay, hasLoneSurrogate, isHardBillingMessage, isUsageLimitError, isValidToolCallName, localWireModelId, palsuAssistantMessage, palsuText, palsuThinking, palsuToolCall, prewarmAnthropicCache, providerRegistry, redactText, redactValue, registerPalsuProvider, resolveToolSchema, sanitizeMessagesForWire, setProviderDiagnostic, sliceHead, sliceTail, stream, toAnthropicMessages, toOpenAIMessages, toWellFormedText, toolCallNameRuleFor };

package/dist/index.d.ts

@@ -186,8 +186,24 @@ interface Usage {
         webFetchRequests?: number;
     };
 }
+interface PreparedContext {
+    /** Read-only observation after generic sanitization/image limiting, before provider encoding.
+     * Do not log or retain these messages: they may contain secrets and image data. */
+    messages: readonly Message[];
+    tools: readonly {
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+    }[];
+    imagesBefore: number;
+    imagesAfter: number;
+    /** First message whose images were removed for this request, or null. */
+    firstImageDropMessage: number | null;
+}
 interface StreamOptions {
     provider: Provider;
+    /** Optional, synchronous diagnostics observer. Exceptions cannot fail a model request. */
+    onContextPrepared?: (context: PreparedContext) => void;
     model: string;
     messages: Message[];
     tools?: Tool[];
@@ -245,6 +261,14 @@ interface StreamOptions {
      *  stalls — broken SSE connections (transient CDN / proxy issues) often
      *  recover when the same request is issued over a plain HTTP request/response. */
     streaming?: boolean;
+    /** Cache prewarm (Anthropic only; other providers ignore it). Sends the exact
+     *  same request prefix (system, tools, messages, thinking, betas) with
+     *  `max_tokens: 1` over a non-streaming request so the prompt cache is written
+     *  before the user's next real turn. If the configured thinking mode cannot be
+     *  kept identical at `max_tokens: 1` (budget thinking requires
+     *  budget_tokens < max_tokens), no request is sent and the response has
+     *  zero usage with stopReason "end_turn". */
+    prewarm?: boolean;
     /** Override the User-Agent sent with OAuth-authenticated Anthropic requests.
      *  Anthropic's OAuth edge rejects requests whose claude-cli version lags too
      *  far behind the real Claude Code release; callers that track the live
@@ -570,18 +594,85 @@ type JsonSchema = Record<string, unknown>;
 /**
  * Resolve a tool's JSON Schema for provider tool definitions: prefer the
  * tool's pre-built `rawInputSchema`, otherwise convert its Zod `parameters`.
+ *
+ * A no-argument tool may declare a bare `{ "type": "object" }` root (common
+ * for MCP servers). OpenAI rejects that root with HTTP 400 "object schema
+ * missing properties", failing the whole request, so an object root without
+ * `properties` gets an explicit empty one. JSON Schema meaning is unchanged.
  */
 declare function resolveToolSchema(tool: Tool): JsonSchema;
 
 /**
- * Cap historical images before provider dispatch, removing the oldest first.
+ * Cap historical images before provider dispatch, removing the oldest first, in batches so the
+ * cached conversation prefix stays byte-identical between requests.
  * The persisted/live conversation is never mutated; only modified messages and
  * tool results are cloned for the outgoing request.
  */
 declare function clampProviderContextImages(messages: Message[], provider: Provider, supportsImages: boolean | undefined): Message[];
+/**
+ * What a provider accepts as a replayed tool-call name. `pattern` already
+ * encodes the length limit where the provider documents one; `maxLength` is
+ * checked separately so the generic rule can cap length without a charset.
+ */
+interface ToolCallNameRule {
+    /** Short identifier, for diagnostics and tests. */
+    id: "anthropic" | "openai-chat" | "openai-responses" | "gemini" | "generic";
+    maxLength: number;
+    pattern?: RegExp;
+}
+/**
+ * Per-transport tool-name rules. A legitimate call always carries the name of a
+ * tool we declared, and tool declarations are validated against these same
+ * rules, so only model-invented names (blank, invocation text stuffed into the
+ * name slot, …) can fail them.
+ */
+declare const TOOL_CALL_NAME_RULES: Record<ToolCallNameRule["id"], ToolCallNameRule>;
+/** True when `name` is a tool-call name the provider described by `rule` will accept. */
+declare function isValidToolCallName(name: unknown, rule: ToolCallNameRule): boolean;
+/**
+ * Pick the tool-name rule for the transport a request will actually use. Mirrors
+ * the routing in `stream.ts`: `openai` with an `accountId` is the Codex
+ * (Responses) endpoint, MiniMax rides the Anthropic transport but is a third
+ * party, and an `openai` pointed at a custom baseUrl is an unknown compatible
+ * server.
+ */
+declare function toolCallNameRuleFor(provider: Provider | string, options?: {
+    accountId?: string;
+    baseUrl?: string;
+}): ToolCallNameRule;
+/**
+ * Drop assistant tool calls whose name (or id) the target provider rejects,
+ * together with the tool results that answer them.
+ *
+ * One malformed call — a blank name, a whole invocation string written into the
+ * name slot, a name over the provider's length limit — would otherwise sit in
+ * history and 400 every later request (`tool_use.name: String should match
+ * pattern`, `string_above_max_length`, …), wedging the session.
+ *
+ * Pairing is positional per window: each assistant turn opens a window, and its
+ * results (role `tool`) are matched FIFO per id until the next assistant or user
+ * message, so a reused id never consumes another turn's result. Valid sibling
+ * calls, text and thinking are kept in place. An assistant turn left with
+ * nothing replayable is removed whole, as is a tool message left empty — every
+ * transport accepts the resulting adjacent user turns (the Anthropic API
+ * combines consecutive same-role turns). A Codex reasoning item orphaned by the
+ * drop is removed too. If the drop would leave the request ENDING on that
+ * pruned assistant turn (its only call was the bad one, so no results follow),
+ * the turn is removed as well: a trailing assistant message is an assistant
+ * prefill, which current Claude models reject and other APIs treat as a
+ * continuation rather than a fresh turn.
+ *
+ * Returns the input array untouched when nothing is malformed.
+ */
+declare function dropInvalidToolCalls(messages: Message[], rule: ToolCallNameRule): Message[];
 declare function toAnthropicMessages(messages: Message[], cacheControl?: {
     type: "ephemeral";
     ttl?: "1h";
+}, options?: {
+    /** Replay server-side refusal `fallback` blocks in place. Only set when the
+     * request carries the server-side-fallback beta; otherwise they are
+     * stripped (after applying the replay rules). Default false. */
+    fallbackBlocks?: boolean;
 }): {
     system: Anthropic.TextBlockParam[] | undefined;
     messages: Anthropic.MessageParam[];
@@ -685,4 +776,4 @@ interface PalsuProviderConfig {
  */
 declare function registerPalsuProvider(config?: PalsuProviderConfig): PalsuProviderHandle;
 
-export { type AssistantMessage, type CacheRetention, type ContentPart, type DoneEvent, EZCoderAIError, type ErrorEvent, type ErrorSource, EventStream, type FormattedError, type ImageContent, type Message, type MessageProvenance, type MessageProvenanceKind, type MessageProvenanceSource, type MessageProvenanceVisibility, type PalsuModelConfig, type PalsuModelHandle, type PalsuProviderConfig, type PalsuProviderHandle, type PalsuProviderState, type PalsuResponse, type PalsuResponseFactory, type Provider, type ProviderDiagnosticFn, type ProviderEntry, ProviderError, type ProviderStreamFn, REDACTED as REDACTION_MARKER, type RawContent, type RedactionOptions, type ServerToolCall, type ServerToolCallEvent, type ServerToolDefinition, type ServerToolResult, type ServerToolResultEvent, type StopReason, type StreamEvent, type StreamOptions, type StreamResponse, StreamResult, type SystemMessage, type TextContent, type TextDeltaEvent, type ThinkingContent, type ThinkingDeltaEvent, type ThinkingLevel, type Tool, type ToolCall, type ToolCallDeltaEvent, type ToolCallDoneEvent, type ToolChoice, type ToolResult, type ToolResultContent, type ToolResultMessage, type Usage, type UserMessage, type VideoContent, clampProviderContextImages, classifyProviderError, environmentSecrets, formatError, formatErrorForDisplay, hasLoneSurrogate, isHardBillingMessage, isUsageLimitError, localWireModelId, palsuAssistantMessage, palsuText, palsuThinking, palsuToolCall, prewarmAnthropicCache, providerRegistry, redactText, redactValue, registerPalsuProvider, resolveToolSchema, sanitizeMessagesForWire, setProviderDiagnostic, sliceHead, sliceTail, stream, toAnthropicMessages, toOpenAIMessages, toWellFormedText };
+export { type AssistantMessage, type CacheRetention, type ContentPart, type DoneEvent, EZCoderAIError, type ErrorEvent, type ErrorSource, EventStream, type FormattedError, type ImageContent, type Message, type MessageProvenance, type MessageProvenanceKind, type MessageProvenanceSource, type MessageProvenanceVisibility, type PalsuModelConfig, type PalsuModelHandle, type PalsuProviderConfig, type PalsuProviderHandle, type PalsuProviderState, type PalsuResponse, type PalsuResponseFactory, type PreparedContext, type Provider, type ProviderDiagnosticFn, type ProviderEntry, ProviderError, type ProviderStreamFn, REDACTED as REDACTION_MARKER, type RawContent, type RedactionOptions, 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, dropInvalidToolCalls, environmentSecrets, formatError, formatErrorForDisplay, hasLoneSurrogate, isHardBillingMessage, isUsageLimitError, isValidToolCallName, localWireModelId, palsuAssistantMessage, palsuText, palsuThinking, palsuToolCall, prewarmAnthropicCache, providerRegistry, redactText, redactValue, registerPalsuProvider, resolveToolSchema, sanitizeMessagesForWire, setProviderDiagnostic, sliceHead, sliceTail, stream, toAnthropicMessages, toOpenAIMessages, toWellFormedText, toolCallNameRuleFor };