@deepstrike/sdk 0.2.6 → 0.2.8

package/dist/providers/minimax.js

@@ -1,5 +1,7 @@
 import { AnthropicProvider } from "./anthropic.js";
+import { OpenAIChatProvider } from "./openai.js";
 import { endpointProfiles } from "./profiles.js";
+import { omitExtensionKeys } from "./base.js";
 const MINIMAX_POLICIES = {
     "MiniMax-M2.7": { maxTurns: 35 },
     "MiniMax-M2.7-highspeed": { maxTurns: 35 },
@@ -10,14 +12,211 @@ const MINIMAX_POLICIES = {
     "MiniMax-M2": { maxTurns: 20 },
     "MiniMax-Text-01": { maxTurns: 20 },
 };
-export class MiniMaxProvider extends AnthropicProvider {
+/**
+ * MiniMax over its Anthropic-compatible endpoint. Replay is carried as Anthropic
+ * `native_blocks` (thinking/text/tool_use), identical to the first-party
+ * Anthropic provider.
+ */
+export class MiniMaxAnthropicProvider extends AnthropicProvider {
     constructor(apiKey, model = "MiniMax-M2.7", retry, baseURL = endpointProfiles["minimax.anthropic"].baseURL) {
         super(apiKey, model, retry, {
             baseURL,
             authMode: "api-key",
         });
     }
+    providerName() {
+        return "minimax";
+    }
+    runtimePolicy() {
+        return MINIMAX_POLICIES[this.model] ?? {};
+    }
+}
+/**
+ * MiniMax over its OpenAI-compatible endpoint. Replay is carried as
+ * `reasoning_content` / `reasoning_details` (split reasoning), and requests
+ * default to `reasoning_split: true` so reasoning is returned out-of-band rather
+ * than embedded in the message content.
+ */
+export class MiniMaxOpenAIProvider extends OpenAIChatProvider {
+    constructor(apiKey, model = "MiniMax-M2.7", retry, baseURL = endpointProfiles["minimax.openai"].baseURL) {
+        super(apiKey, model, retry, baseURL);
+    }
     runtimePolicy() {
         return MINIMAX_POLICIES[this.model] ?? {};
     }
+    descriptor() {
+        return {
+            provider: "minimax",
+            protocol: "openai-chat",
+            model: this.model,
+            reasoning: {
+                supported: true,
+                preserveAcrossToolTurns: true,
+                requiresReplayForToolTurns: true,
+            },
+            toolCalls: {
+                supported: true,
+                requiresStrictPairing: true,
+            },
+        };
+    }
+    requireNonEmptyReasoningReplayForToolTurns(extensions) {
+        if (extensions?.__deepstrikeThinkingEnabled === false)
+            return false;
+        return extensions?.reasoning_split !== false;
+    }
+    buildRequestExtensions(extensions) {
+        const reasoningSplit = extensions?.reasoning_split !== false;
+        return {
+            ...omitExtensionKeys(extensions, ["reasoning_split", "exposeReasoning"]),
+            __deepstrikeThinkingEnabled: reasoningSplit,
+            // Re-thread the degrade control flag (omitExtensionKeys strips internal
+            // keys) so buildChatMessages can honor it; the wire-request omit drops it.
+            ...(extensions?.degradeMissingReasoningReplay === true ? { degradeMissingReasoningReplay: true } : {}),
+            reasoning_split: reasoningSplit,
+        };
+    }
+    async complete(context, tools, extensions) {
+        const requestExtensions = this.buildRequestExtensions(extensions);
+        if (this.circuit.isOpen())
+            throw new Error("Circuit breaker open");
+        const msgs = this.buildChatMessages(context, requestExtensions);
+        let lastErr;
+        for (let i = 0; i < this.maxRetries; i++) {
+            try {
+                const resp = await this.client.chat.completions.create({
+                    ...this.requestExtensions(requestExtensions),
+                    model: this.model,
+                    messages: msgs,
+                    ...(tools.length ? { tools: this.chat.buildTools(tools) } : {}),
+                });
+                this.circuit.recordSuccess();
+                const choice = resp.choices[0].message;
+                const nativeToolCalls = choice.tool_calls ?? [];
+                const toolCalls = this.chat.normalizeToolCalls(nativeToolCalls);
+                const content = choice.content ?? "";
+                this.rememberMiniMaxReplay(content, toolCalls, choice.reasoning_content, choice.reasoning_details, nativeToolCalls);
+                return { role: "assistant", content, tokenCount: resp.usage?.completion_tokens ?? resp.usage?.total_tokens, toolCalls };
+            }
+            catch (err) {
+                lastErr = err;
+                this.circuit.recordFailure();
+                if (i < this.maxRetries - 1)
+                    await new Promise(r => setTimeout(r, this.baseDelay * 2 ** i));
+            }
+        }
+        throw lastErr;
+    }
+    async *stream(context, tools, extensions) {
+        const exposeReasoning = extensions?.exposeReasoning ?? false;
+        const requestExtensions = this.buildRequestExtensions(extensions);
+        const msgs = this.buildChatMessages(context, requestExtensions);
+        const toolCallBufs = {};
+        const emittedToolCallIndexes = new Set();
+        let reasoningContent = "";
+        let reasoningDetails;
+        let finalText = "";
+        const stream = await this.client.chat.completions.create({
+            ...this.requestExtensions(requestExtensions),
+            model: this.model,
+            messages: msgs,
+            ...(tools.length ? { tools: this.chat.buildTools(tools) } : {}),
+            stream: true,
+            stream_options: { include_usage: true },
+        });
+        let totalTokens = 0;
+        let inputTokens = 0;
+        let outputTokens = 0;
+        for await (const chunk of stream) {
+            if (chunk.usage) {
+                totalTokens = chunk.usage.total_tokens;
+                inputTokens = chunk.usage.prompt_tokens ?? 0;
+                outputTokens = chunk.usage.completion_tokens ?? 0;
+                continue;
+            }
+            const choice = chunk.choices[0];
+            if (!choice)
+                continue;
+            const delta = choice.delta;
+            if (!delta)
+                continue;
+            if (exposeReasoning && delta.reasoning_content) {
+                yield { type: "thinking_delta", delta: String(delta.reasoning_content) };
+            }
+            if (delta.reasoning_content)
+                reasoningContent += String(delta.reasoning_content);
+            if (delta.reasoning_details !== undefined && delta.reasoning_details !== null)
+                reasoningDetails = delta.reasoning_details;
+            if (delta.content) {
+                finalText += String(delta.content);
+                yield { type: "text_delta", delta: delta.content };
+            }
+            for (const tc of delta.tool_calls ?? []) {
+                const idx = tc.index;
+                if (!toolCallBufs[idx])
+                    toolCallBufs[idx] = { id: tc.id ?? "", name: "", argsBuf: "" };
+                if (tc.function?.name)
+                    toolCallBufs[idx].name += tc.function.name;
+                toolCallBufs[idx].argsBuf += tc.function?.arguments ?? "";
+            }
+            if (choice.finish_reason === "tool_calls") {
+                const toolCalls = Object.values(toolCallBufs).map(tb => ({ id: tb.id, name: tb.name, arguments: tb.argsBuf || "{}" }));
+                this.rememberMiniMaxReplay(finalText, toolCalls, reasoningContent, reasoningDetails, nativeToolCallsFromBuffers(toolCallBufs));
+                for (const [index, tb] of Object.entries(toolCallBufs)) {
+                    const idx = Number(index);
+                    if (emittedToolCallIndexes.has(idx))
+                        continue;
+                    let args = {};
+                    try {
+                        args = JSON.parse(tb.argsBuf || "{}");
+                    }
+                    catch {
+                        args = {};
+                    }
+                    emittedToolCallIndexes.add(idx);
+                    yield { type: "tool_call", id: tb.id, name: tb.name, arguments: args };
+                }
+            }
+        }
+        const toolCalls = Object.values(toolCallBufs).map(tb => ({ id: tb.id, name: tb.name, arguments: tb.argsBuf || "{}" }));
+        this.rememberMiniMaxReplay(finalText, toolCalls, reasoningContent, reasoningDetails, nativeToolCallsFromBuffers(toolCallBufs));
+        for (const [index, tb] of Object.entries(toolCallBufs)) {
+            const idx = Number(index);
+            if (emittedToolCallIndexes.has(idx))
+                continue;
+            let args = {};
+            try {
+                args = JSON.parse(tb.argsBuf || "{}");
+            }
+            catch {
+                args = {};
+            }
+            emittedToolCallIndexes.add(idx);
+            yield { type: "tool_call", id: tb.id, name: tb.name, arguments: args };
+        }
+        if (totalTokens > 0)
+            yield { type: "usage", totalTokens, inputTokens, outputTokens };
+    }
+    rememberMiniMaxReplay(content, toolCalls, reasoningContent, reasoningDetails, nativeToolCalls) {
+        const hasReasoning = typeof reasoningContent === "string" && reasoningContent.trim().length > 0;
+        const hasDetails = reasoningDetails !== undefined && reasoningDetails !== null;
+        if (!hasReasoning && !hasDetails)
+            return;
+        this.chat.rememberReplayFields({ content, toolCalls }, {
+            schema_version: 2,
+            provider: "minimax",
+            protocol: "openai-chat",
+            model: this.model,
+            ...(hasReasoning ? { reasoning_content: reasoningContent } : {}),
+            ...(hasDetails ? { reasoning_details: reasoningDetails } : {}),
+            ...(nativeToolCalls.length ? { tool_calls: nativeToolCalls } : {}),
+        });
+    }
+}
+function nativeToolCallsFromBuffers(toolCallBufs) {
+    return Object.values(toolCallBufs).map(tb => ({
+        id: tb.id,
+        type: "function",
+        function: { name: tb.name, arguments: tb.argsBuf || "{}" },
+    }));
 }

package/dist/providers/openai-chat.d.ts

@@ -1,5 +1,16 @@
 import type OpenAI from "openai";
-import type { Message, RenderedContext, ToolSchema } from "../types.js";
+import type { Message, ProviderDescriptor, RenderedContext, ToolSchema } from "../types.js";
+import { type ReplayabilityAssessment } from "./replay-validator.js";
+export interface OpenAIChatBuildMessageOptions {
+    descriptor?: ProviderDescriptor;
+    requireNonEmptyReasoningForToolCalls?: boolean;
+    /**
+     * Degrade (rather than throw) when a reasoning-requiring tool-call turn has
+     * no stored reasoning replay: a placeholder reasoning is injected so the
+     * request still goes out in degraded form.
+     */
+    degradeMissingReasoning?: boolean;
+}
 export declare class OpenAIChatAdapter {
     private replayFields;
     buildTools(tools: ToolSchema[]): {
@@ -10,7 +21,12 @@ export declare class OpenAIChatAdapter {
             parameters: any;
         };
     }[];
-    buildMessages(context: RenderedContext): OpenAI.ChatCompletionMessageParam[];
+    buildMessages(context: RenderedContext, options?: OpenAIChatBuildMessageOptions): OpenAI.ChatCompletionMessageParam[];
+    /**
+     * Throw-free pre-flight check: which assistant tool-call turns in `context`
+     * lack the non-empty reasoning replay a reasoning-requiring provider needs.
+     */
+    assessReasoning(context: RenderedContext): ReplayabilityAssessment;
     normalizeToolCalls(toolCalls?: OpenAI.ChatCompletionMessageToolCall[]): Array<{
         id: string;
         name: string;

package/dist/providers/openai-chat.js

@@ -1,5 +1,6 @@
 import { assistantReplayKey } from "../runtime/provider-replay.js";
 import { normalizeToolCall, toOpenAIMessageParams } from "./base.js";
+import { DEGRADED_REASONING_PLACEHOLDER, assessReasoningReplay, validateOpenAIChatReplay, } from "./replay-validator.js";
 export class OpenAIChatAdapter {
     replayFields = new Map();
     buildTools(tools) {
@@ -8,7 +9,14 @@ export class OpenAIChatAdapter {
             function: { name: t.name, description: t.description, parameters: JSON.parse(t.parameters) },
         }));
     }
-    buildMessages(context) {
+    buildMessages(context, options = {}) {
+        validateOpenAIChatReplay(context, {
+            descriptor: options.descriptor,
+            requireNonEmptyReasoningForToolCalls: options.requireNonEmptyReasoningForToolCalls,
+            degradeMissingReasoning: options.degradeMissingReasoning,
+            replayForAssistant: message => this.replayFields.get(assistantReplayKey(message)),
+        });
+        const degradeReasoning = Boolean(options.requireNonEmptyReasoningForToolCalls && options.degradeMissingReasoning);
         // toOpenAIMessageParams prepends systemText as messages[0], then turns.
         const serialized = toOpenAIMessageParams(context);
         // Cursor starts at 1 to skip the system message injected by toOpenAIMessageParams.
@@ -20,13 +28,29 @@ export class OpenAIChatAdapter {
             }
             if (source.role === "assistant") {
                 const replay = this.replayFields.get(assistantReplayKey(source));
-                if (replay)
-                    serialized[cursor] = { ...serialized[cursor], ...replay };
+                let wireReplay = openAIChatWireReplayFields(replay);
+                if (!wireReplay && degradeReasoning && source.toolCalls?.length) {
+                    // Reasoning-requiring provider, no stored reasoning for this tool-call
+                    // turn, caller opted into degradation: inject a placeholder so the
+                    // wire message stays well-formed instead of failing the whole request.
+                    wireReplay = { reasoning_content: DEGRADED_REASONING_PLACEHOLDER };
+                }
+                if (wireReplay)
+                    serialized[cursor] = { ...serialized[cursor], ...wireReplay };
             }
             cursor += 1;
         }
         return serialized;
     }
+    /**
+     * Throw-free pre-flight check: which assistant tool-call turns in `context`
+     * lack the non-empty reasoning replay a reasoning-requiring provider needs.
+     */
+    assessReasoning(context) {
+        return assessReasoningReplay(context.turns, {
+            replayForAssistant: message => this.replayFields.get(assistantReplayKey(message)),
+        });
+    }
     normalizeToolCalls(toolCalls = []) {
         return toolCalls
             .filter((tc) => tc.type === "function")
@@ -40,3 +64,13 @@ export class OpenAIChatAdapter {
         return this.replayFields.get(assistantReplayKey(message));
     }
 }
+function openAIChatWireReplayFields(replay) {
+    if (!replay)
+        return undefined;
+    const fields = {};
+    if (typeof replay.reasoning_content === "string")
+        fields.reasoning_content = replay.reasoning_content;
+    if (replay.reasoning_details !== undefined)
+        fields.reasoning_details = replay.reasoning_details;
+    return Object.keys(fields).length ? fields : undefined;
+}

package/dist/providers/openai.d.ts

@@ -1,7 +1,8 @@
 import OpenAI from "openai";
-import type { Message, ProviderReplay, RenderedContext, ToolSchema, StreamEvent, LLMProvider, RuntimePolicy } from "../types.js";
+import type { Message, ProviderDescriptor, ProviderReplay, RenderedContext, ToolSchema, StreamEvent, LLMProvider, RuntimePolicy } from "../types.js";
 import { CircuitBreaker } from "./base.js";
 import { OpenAIChatAdapter } from "./openai-chat.js";
+import type { ReplayabilityAssessment } from "./replay-validator.js";
 export declare class OpenAIChatProvider implements LLMProvider {
     protected readonly model: string;
     protected client: OpenAI;
@@ -14,6 +15,18 @@ export declare class OpenAIChatProvider implements LLMProvider {
         baseDelay: number;
     }, baseURL?: string);
     runtimePolicy(): RuntimePolicy;
+    descriptor(): ProviderDescriptor;
+    protected requireNonEmptyReasoningReplayForToolTurns(_extensions?: Record<string, unknown>): boolean;
+    protected degradeMissingReasoningReplay(extensions?: Record<string, unknown>): boolean;
+    protected buildChatMessages(context: RenderedContext, extensions?: Record<string, unknown>): OpenAI.Chat.Completions.ChatCompletionMessageParam[];
+    /**
+     * Pre-flight query: would this history validate against this provider with the
+     * given extensions, without sending the request? Lets an embedder route around
+     * a reasoning-replay failure (keep thinking on, disable it, or skip this
+     * candidate) before issuing the request. `ok: true` when this provider does
+     * not require reasoning replay for the current extensions.
+     */
+    assessReplayability(context: RenderedContext, extensions?: Record<string, unknown>): ReplayabilityAssessment;
     peekProviderReplay(message: Pick<Message, "content" | "toolCalls">): ProviderReplay | undefined;
     seedProviderReplay(message: Pick<Message, "content" | "toolCalls">, replay: ProviderReplay): void;
     complete(context: RenderedContext, tools: ToolSchema[], extensions?: Record<string, unknown>): Promise<Message>;

package/dist/providers/openai.js

@@ -42,21 +42,62 @@ export class OpenAIChatProvider {
     runtimePolicy() {
         return OPENAI_POLICIES[this.model] ?? {};
     }
+    descriptor() {
+        return {
+            provider: "openai",
+            protocol: "openai-chat",
+            model: this.model,
+            reasoning: {
+                supported: true,
+                preserveAcrossToolTurns: false,
+            },
+            toolCalls: {
+                supported: true,
+                requiresStrictPairing: true,
+            },
+        };
+    }
+    requireNonEmptyReasoningReplayForToolTurns(_extensions) {
+        return false;
+    }
+    degradeMissingReasoningReplay(extensions) {
+        return extensions?.degradeMissingReasoningReplay === true;
+    }
+    buildChatMessages(context, extensions) {
+        return this.chat.buildMessages(context, {
+            descriptor: this.descriptor(),
+            requireNonEmptyReasoningForToolCalls: this.requireNonEmptyReasoningReplayForToolTurns(extensions),
+            degradeMissingReasoning: this.degradeMissingReasoningReplay(extensions),
+        });
+    }
+    /**
+     * Pre-flight query: would this history validate against this provider with the
+     * given extensions, without sending the request? Lets an embedder route around
+     * a reasoning-replay failure (keep thinking on, disable it, or skip this
+     * candidate) before issuing the request. `ok: true` when this provider does
+     * not require reasoning replay for the current extensions.
+     */
+    assessReplayability(context, extensions) {
+        if (!this.requireNonEmptyReasoningReplayForToolTurns(extensions)) {
+            return { ok: true, offendingCallIds: [] };
+        }
+        return this.chat.assessReasoning(context);
+    }
     peekProviderReplay(message) {
         const fields = this.chat.peekReplayFields(message);
-        if (!fields || !("reasoning_content" in fields))
+        if (!fields || !("reasoning_content" in fields || "reasoning_details" in fields))
             return undefined;
-        return { reasoning_content: String(fields.reasoning_content ?? "") };
+        return fields;
     }
     seedProviderReplay(message, replay) {
-        if (replay.reasoning_content !== undefined) {
-            this.chat.rememberReplayFields(message, { reasoning_content: replay.reasoning_content });
+        if (replay.reasoning_content !== undefined || replay.reasoning_details !== undefined) {
+            this.chat.rememberReplayFields(message, replay);
         }
     }
     async complete(context, tools, extensions) {
         if (this.circuit.isOpen())
             throw new Error("Circuit breaker open");
-        const msgs = this.chat.buildMessages(context);
+        const msgs = this.buildChatMessages(context, extensions);
         let lastErr;
         for (let i = 0; i < this.maxRetries; i++) {
             try {
@@ -81,7 +122,7 @@ export class OpenAIChatProvider {
         throw lastErr;
     }
     async *stream(context, tools, extensions) {
-        const msgs = this.chat.buildMessages(context);
+        const msgs = this.buildChatMessages(context, extensions);
         const toolCallBufs = {};
         const emittedToolCallIndexes = new Set();
         const extractor = new ThinkingTagStreamExtractor();
@@ -190,7 +231,7 @@ export class OpenAIChatProvider {
             yield { type: "usage", totalTokens, inputTokens, outputTokens };
     }
     requestExtensions(extensions) {
-        return omitExtensionKeys(extensions, ["model", "messages", "tools", "stream", "stream_options"]);
+        return omitExtensionKeys(extensions, ["model", "messages", "tools", "stream", "stream_options", "__deepstrikeThinkingEnabled"]);
     }
 }
 export { OpenAIChatProvider as OpenAIProvider };

package/dist/providers/profiles.d.ts

@@ -59,6 +59,12 @@ export declare const endpointProfiles: {
         readonly protocol: "anthropic-messages";
         readonly baseURL: "https://api.minimaxi.com/anthropic";
     };
+    readonly "minimax.openai": {
+        readonly id: "minimax.openai";
+        readonly providerId: "minimax";
+        readonly protocol: "openai-chat";
+        readonly baseURL: "https://api.minimaxi.com/v1";
+    };
     readonly "deepseek.openai": {
         readonly id: "deepseek.openai";
         readonly providerId: "deepseek";

package/dist/providers/profiles.js

@@ -29,6 +29,12 @@ export const endpointProfiles = {
         protocol: "anthropic-messages",
         baseURL: "https://api.minimaxi.com/anthropic",
     },
+    "minimax.openai": {
+        id: "minimax.openai",
+        providerId: "minimax",
+        protocol: "openai-chat",
+        baseURL: "https://api.minimaxi.com/v1",
+    },
     "deepseek.openai": {
         id: "deepseek.openai",
         providerId: "deepseek",

package/dist/providers/qwen.d.ts

@@ -1,5 +1,5 @@
 import OpenAI from "openai";
-import type { LLMProvider, Message, RenderedContext, StreamEvent, ToolSchema, RuntimePolicy, ProviderReplay } from "../types.js";
+import type { LLMProvider, Message, ProviderDescriptor, RenderedContext, StreamEvent, ToolSchema, RuntimePolicy, ProviderReplay } from "../types.js";
 import { CircuitBreaker } from "./base.js";
 import { OpenAIChatAdapter } from "./openai-chat.js";
 export declare class QwenProvider implements LLMProvider {
@@ -14,6 +14,8 @@ export declare class QwenProvider implements LLMProvider {
         baseDelay: number;
     }, baseURL?: string);
     runtimePolicy(): RuntimePolicy;
+    descriptor(): ProviderDescriptor;
+    private buildChatMessages;
     peekProviderReplay(message: Pick<Message, "content" | "toolCalls">): ProviderReplay | undefined;
     seedProviderReplay(message: Pick<Message, "content" | "toolCalls">, replay: ProviderReplay): void;
     complete(context: RenderedContext, tools: ToolSchema[], extensions?: Record<string, unknown>): Promise<Message>;

package/dist/providers/qwen.js

@@ -36,6 +36,24 @@ export class QwenProvider {
     runtimePolicy() {
         return QWEN_POLICIES[this.model] ?? {};
     }
+    descriptor() {
+        return {
+            provider: "qwen",
+            protocol: "openai-chat",
+            model: this.model,
+            reasoning: {
+                supported: true,
+                preserveAcrossToolTurns: true,
+            },
+            toolCalls: {
+                supported: true,
+                requiresStrictPairing: true,
+            },
+        };
+    }
+    buildChatMessages(context) {
+        return this.chat.buildMessages(context, { descriptor: this.descriptor() });
+    }
     peekProviderReplay(message) {
         const fields = this.chat.peekReplayFields(message);
         if (!fields || !("reasoning_content" in fields))
@@ -50,7 +68,7 @@ export class QwenProvider {
     async complete(context, tools, extensions) {
         if (this.circuit.isOpen())
             throw new Error("Circuit breaker open");
-        const msgs = this.chat.buildMessages(context);
+        const msgs = this.buildChatMessages(context);
         const extraBody = this.thinkingExtraBody(extensions);
         let lastErr;
         for (let i = 0; i < this.maxRetries; i++) {
@@ -77,7 +95,7 @@ export class QwenProvider {
         throw lastErr;
     }
     async *stream(context, tools, extensions) {
-        const msgs = this.chat.buildMessages(context);
+        const msgs = this.buildChatMessages(context);
         const toolCallBufs = {};
         const emittedToolCallIndexes = new Set();
         let reasoningContent = "";

package/dist/providers/replay-validator.d.ts

@@ -0,0 +1,32 @@
+import type { Message, ProviderDescriptor, ProviderReplay, RenderedContext, ReplayabilityAssessment } from "../types.js";
+export type { ReplayabilityAssessment };
+export declare class ProviderReplayValidationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Placeholder reasoning injected for an assistant tool-call turn that has no
+ * stored reasoning replay when the caller opted into graceful degradation
+ * (`degradeMissingReasoning`). It keeps the wire message well-formed for a
+ * thinking-on provider without fabricating substantive reasoning.
+ */
+export declare const DEGRADED_REASONING_PLACEHOLDER = "[reasoning unavailable on replay]";
+export interface OpenAIChatReplayValidationOptions {
+    descriptor?: ProviderDescriptor;
+    requireNonEmptyReasoningForToolCalls?: boolean;
+    /**
+     * When true, an assistant tool-call turn that lacks reasoning replay is
+     * degraded (serialized without/with a placeholder reasoning) instead of
+     * throwing. Lets a recovery/fallback request succeed in degraded form
+     * rather than fail outright.
+     */
+    degradeMissingReasoning?: boolean;
+    replayForAssistant?: (message: Pick<Message, "content" | "toolCalls">) => ProviderReplay | Record<string, unknown> | undefined;
+}
+export declare function validateOpenAIChatReplay(context: RenderedContext, options?: OpenAIChatReplayValidationOptions): void;
+/**
+ * Pure, throw-free assessment: which assistant tool-call turns lack the
+ * non-empty reasoning replay a reasoning-requiring provider needs. Lets an
+ * embedder decide per-candidate whether to keep thinking on, disable it, or
+ * skip the candidate — before sending.
+ */
+export declare function assessReasoningReplay(turns: Message[], options: Pick<OpenAIChatReplayValidationOptions, "replayForAssistant">): ReplayabilityAssessment;

package/dist/providers/replay-validator.js

@@ -0,0 +1,90 @@
+export class ProviderReplayValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ProviderReplayValidationError";
+    }
+}
+/**
+ * Placeholder reasoning injected for an assistant tool-call turn that has no
+ * stored reasoning replay when the caller opted into graceful degradation
+ * (`degradeMissingReasoning`). It keeps the wire message well-formed for a
+ * thinking-on provider without fabricating substantive reasoning.
+ */
+export const DEGRADED_REASONING_PLACEHOLDER = "[reasoning unavailable on replay]";
+export function validateOpenAIChatReplay(context, options = {}) {
+    validateStrictToolResultPairing(context.turns);
+    if (options.requireNonEmptyReasoningForToolCalls && !options.degradeMissingReasoning) {
+        const assessment = assessReasoningReplay(context.turns, options);
+        if (!assessment.ok) {
+            throw reasoningReplayError(assessment.offendingCallIds, options.descriptor);
+        }
+    }
+}
+/**
+ * Pure, throw-free assessment: which assistant tool-call turns lack the
+ * non-empty reasoning replay a reasoning-requiring provider needs. Lets an
+ * embedder decide per-candidate whether to keep thinking on, disable it, or
+ * skip the candidate — before sending.
+ */
+export function assessReasoningReplay(turns, options) {
+    const offendingCallIds = [];
+    for (const message of turns) {
+        if (message.role !== "assistant" || !message.toolCalls?.length)
+            continue;
+        const replay = options.replayForAssistant?.(message);
+        const reasoning = typeof replay?.reasoning_content === "string" ? replay.reasoning_content.trim() : "";
+        if (!reasoning) {
+            for (const tc of message.toolCalls)
+                offendingCallIds.push(tc.id);
+        }
+    }
+    return { ok: offendingCallIds.length === 0, offendingCallIds };
+}
+function reasoningReplayError(callIds, descriptor) {
+    const provider = descriptor ? `${descriptor.provider}/${descriptor.model}` : "provider";
+    return new ProviderReplayValidationError(`${provider} replay requires non-empty reasoning_content for assistant tool call turn ${callIds.join(", ")}. ` +
+        "Disable thinking, rebuild this history with provider replay, switch to a provider that can replay this turn, " +
+        "or pass extensions.degradeMissingReasoningReplay to send a degraded turn.");
+}
+function toolResultParts(message) {
+    return (message.contentParts ?? [])
+        .filter((part) => part.type === "tool_result");
+}
+function validateStrictToolResultPairing(turns) {
+    let pendingIds;
+    let completedIds = new Set();
+    const assertAllCompleted = () => {
+        if (!pendingIds)
+            return;
+        const missing = [...pendingIds].filter(id => !completedIds.has(id));
+        if (missing.length) {
+            throw new ProviderReplayValidationError(`OpenAI-compatible replay has assistant tool_calls with no tool result for ${missing.join(", ")}: ` +
+                "every tool_call must be answered by a tool message before the next assistant or user turn.");
+        }
+    };
+    for (const message of turns) {
+        if (message.role === "assistant") {
+            assertAllCompleted();
+            const toolCalls = message.toolCalls ?? [];
+            pendingIds = toolCalls.length ? new Set(toolCalls.map(tc => tc.id)) : undefined;
+            completedIds = new Set();
+            continue;
+        }
+        if (message.role !== "tool") {
+            assertAllCompleted();
+            pendingIds = undefined;
+            completedIds = new Set();
+            continue;
+        }
+        for (const part of toolResultParts(message)) {
+            if (!pendingIds?.has(part.callId)) {
+                throw new ProviderReplayValidationError(`OpenAI-compatible replay has orphan tool result ${part.callId}: no preceding assistant tool_call with the same id.`);
+            }
+            if (completedIds.has(part.callId)) {
+                throw new ProviderReplayValidationError(`OpenAI-compatible replay has duplicate tool result ${part.callId}.`);
+            }
+            completedIds.add(part.callId);
+        }
+    }
+    assertAllCompleted();
+}