@code-yeongyu/senpi-ai 2026.9.30 → 2026.10.1

package/dist/api/openai-completions.js

@@ -13,8 +13,10 @@ import { awaitProviderTransport, iterateProviderTransport, openAICompatibleProvi
 import { getProviderEnvValue } from "../utils/provider-env.js";
 import { retryProviderStreamRequest } from "../utils/provider-retry.js";
 import { sanitizeSurrogates } from "../utils/sanitize-unicode.js";
+import { getSystemMessageText, renderSystemMessageUpdate } from "../utils/text.js";
 import { sendWithForcedToolChoiceFallback } from "../utils/tool-choice-fallback.js";
 import { normalizeToolParametersForMoonshot, normalizeToolParametersForOpenAICompat, } from "../utils/tool-schema-compat.js";
+import { getCurrentTools, getDeclaredTools, resolveTranscript, resolveTranscriptTools, } from "../utils/transcript.js";
 import { appendGrammarToolInputJsonDelta, createGrammarToolInputProperties, getGrammarToolInput, getJsonSchemaToolParameters, resolveGrammarConstrainedSampling, resolveJsonSchemaStrictSampling, } from "./constrained-sampling.js";
 import { withGitHubCopilotFailureNote } from "./github-copilot-errors.js";
 import { buildCopilotDynamicHeaders, hasCopilotVisionInput } from "./github-copilot-headers.js";
@@ -122,24 +124,26 @@ function hasToolHistory(messages) {
     }
     return false;
 }
-function getDeferredToolNames(messages) {
+/**
+ * Kimi `deferredToolsMode`: a current tool named by any tool result's `addedToolNames` leaves the
+ * top-level `tools` field and is loaded by a Kimi tools system message after that result.
+ */
+function resolveKimiDeferredTools(messages, compat) {
+    const deferred = new Map();
+    if (compat.deferredToolsMode !== "kimi")
+        return deferred;
     const names = new Set();
     for (const message of messages) {
-        if (message.role === "toolResult") {
-            for (const name of message.addedToolNames ?? []) {
-                names.add(name);
-            }
-        }
+        if (message.role !== "toolResult")
+            continue;
+        for (const name of message.addedToolNames ?? [])
+            names.add(name);
     }
-    return names;
-}
-function getToolsByName(tools, names) {
-    if (!tools)
-        return [];
-    const toolsByName = new Map(tools.map((tool) => [tool.name, tool]));
-    return Array.from(names)
-        .map((name) => toolsByName.get(name))
-        .filter((tool) => tool !== undefined);
+    for (const tool of getCurrentTools(messages)) {
+        if (names.has(tool.name))
+            deferred.set(tool.name, tool);
+    }
+    return deferred;
 }
 function isTextContentBlock(block) {
     return block.type === "text";
@@ -297,6 +301,7 @@ function resolveCacheRetention(cacheRetention, env) {
 }
 export const stream = (model, context, options) => {
     const stream = new AssistantMessageEventStream();
+    const normalizedContext = resolveTranscript(context, getCompat(model).supportsMidConvoSystemMessages);
     (async () => {
         const output = {
             role: "assistant",
@@ -326,11 +331,11 @@ export const stream = (model, context, options) => {
         try {
             const clientAuth = resolveOpenAIClientAuth(model.provider, options?.apiKey, options?.headers);
             const compat = getCompat(model);
-            const grammarToolInputProperties = createGrammarToolInputProperties(context.tools, compat.supportsOpenAIGrammarTools);
+            const grammarToolInputProperties = createGrammarToolInputProperties(getDeclaredTools(normalizedContext.messages), compat.supportsOpenAIGrammarTools);
             const cacheRetention = resolveCacheRetention(options?.cacheRetention ?? model.cacheRetention, options?.env);
             const cacheSessionId = cacheRetention === "none" ? undefined : options?.sessionId;
-            const client = createClient(model, context, clientAuth.apiKey, clientAuth.headers, options?.fetch, cacheSessionId, compat);
-            let params = buildParams(model, context, options, compat, cacheRetention, grammarToolInputProperties);
+            const client = createClient(model, normalizedContext, clientAuth.apiKey, clientAuth.headers, options?.fetch, cacheSessionId, compat);
+            let params = buildParams(model, normalizedContext, options, compat, cacheRetention, grammarToolInputProperties);
             const nextParams = await options?.onPayload?.(params, model);
             if (nextParams !== undefined) {
                 params = nextParams;
@@ -579,6 +584,7 @@ export const stream = (model, context, options) => {
                 }
             };
             for await (const chunk of openaiStream) {
+                await options?.onProviderStreamEvent?.(chunk, model);
                 if (!chunk || typeof chunk !== "object")
                     continue;
                 // OpenAI documents ChatCompletionChunk.id as the unique chat completion identifier,
@@ -833,7 +839,10 @@ function createClient(model, context, apiKey, optionsHeaders, fetch, sessionId,
         defaultHeaders: headers,
     });
 }
-function buildParams(model, context, options, compat = getCompat(model), cacheRetention = resolveCacheRetention(options?.cacheRetention ?? model.cacheRetention, options?.env), grammarToolInputProperties = createGrammarToolInputProperties(context.tools, compat.supportsOpenAIGrammarTools)) {
+function buildParams(model, context, options, compat = getCompat(model), cacheRetention = resolveCacheRetention(options?.cacheRetention ?? model.cacheRetention, options?.env), grammarToolInputProperties = createGrammarToolInputProperties(getDeclaredTools(context.messages), compat.supportsOpenAIGrammarTools)) {
+    const transcriptTools = resolveTranscriptTools(context.messages, compat.supportsMidConvoSystemMessages === true && compat.supportsMidConvoToolAdditions === true);
+    const kimiDeferredTools = resolveKimiDeferredTools(context.messages, compat);
+    const requestTools = transcriptTools.requestTools.filter((tool) => !kimiDeferredTools.has(tool.name));
     const messages = convertMessages(model, context, compat, {
         preserveThinking: options?.reasoningEffort !== undefined,
         grammarToolInputProperties,
@@ -864,6 +873,7 @@ function buildParams(model, context, options, compat = getCompat(model), cacheRe
     }
     if (options?.maxTokens) {
         if (compat.maxTokensField === "max_tokens") {
+            // Deprecated by OpenAI, but some OpenAI-compatible providers only accept max_tokens.
             params.max_tokens = options.maxTokens;
         }
         else {
@@ -873,10 +883,8 @@ function buildParams(model, context, options, compat = getCompat(model), cacheRe
     if (options?.temperature !== undefined) {
         params.temperature = options.temperature;
     }
-    const deferredToolNames = compat.deferredToolsMode === "kimi" ? getDeferredToolNames(context.messages) : new Set();
-    const activeTools = context.tools?.filter((tool) => !deferredToolNames.has(tool.name));
-    if (activeTools && activeTools.length > 0) {
-        params.tools = convertTools(activeTools, compat);
+    if (requestTools.length > 0) {
+        params.tools = convertTools(requestTools, compat);
         if (compat.zaiToolStream) {
             params.tool_stream = true;
         }
@@ -1040,10 +1048,8 @@ function buildParams(model, context, options, compat = getCompat(model), cacheRe
         }
     }
     applyExtraBody(params, options?.extraBody, OPENAI_COMPLETIONS_RESERVED_BODY_KEYS);
-    // Last so custom keys override the named request fields.
-    if (options?.samplingParams) {
-        Object.assign(params, options.samplingParams);
-    }
+    // Last so custom keys override the named request fields. Per-request keys override model defaults.
+    Object.assign(params, model.samplingParams, options?.samplingParams);
     return params;
 }
 function resolveThinkingTokenBudgetField(compat) {
@@ -1173,6 +1179,7 @@ function appendUserMessage(params, content, mergeAdjacentUserMessages) {
     previous.content = [...previousContent, ...currentContent];
 }
 export function convertMessages(model, context, compat, options = {}) {
+    const normalizedContext = resolveTranscript(context, compat.supportsMidConvoSystemMessages);
     const params = [];
     const normalizeToolCallId = (id) => {
         // Handle pipe-separated IDs from OpenAI Responses API
@@ -1202,16 +1209,16 @@ export function convertMessages(model, context, compat, options = {}) {
         const prefix = sanitizedId.slice(0, Math.max(1, 40 - hash.length - 1));
         return `${prefix}_${hash}`;
     };
-    const transformedMessages = transformMessages(context.messages, model, (id) => normalizeToolCallId(id), {
+    const transformedMessages = transformMessages(normalizedContext.messages, model, (id) => normalizeToolCallId(id), {
         preserveThinking: options.preserveThinking,
         normalizeSameModelToolCallIds: true,
     });
     const mergeAdjacentUserMessages = !model.baseUrl.includes("api.openai.com");
-    if (context.systemPrompt) {
-        const useDeveloperRole = model.reasoning && compat.supportsDeveloperRole;
-        const role = useDeveloperRole ? "developer" : "system";
-        params.push({ role: role, content: sanitizeSurrogates(context.systemPrompt) });
-    }
+    const transcriptTools = resolveTranscriptTools(normalizedContext.messages, compat.supportsMidConvoSystemMessages === true && compat.supportsMidConvoToolAdditions === true);
+    const kimiDeferredTools = resolveKimiDeferredTools(normalizedContext.messages, compat);
+    // One ledger for both in-place loading paths: transcript system messages and `addedToolNames`.
+    const loadedToolNames = new Set();
+    const instructionRole = model.reasoning && compat.supportsDeveloperRole ? "developer" : "system";
     let lastRole = null;
     for (let i = 0; i < transformedMessages.length; i++) {
         const msg = transformedMessages[i];
@@ -1223,12 +1230,32 @@ export function convertMessages(model, context, compat, options = {}) {
                 content: "I have processed the tool results.",
             });
         }
-        if (msg.role === "user") {
+        if (msg.role === "system") {
+            const addedTools = i > 0 && transcriptTools.anchorsAdditions
+                ? (msg.toolsAdded ?? []).filter((tool) => !loadedToolNames.has(tool.name))
+                : [];
+            for (const tool of addedTools)
+                loadedToolNames.add(tool.name);
+            if (addedTools.length > 0) {
+                const kimiToolMessage = {
+                    role: "system",
+                    tools: convertTools(addedTools, compat),
+                };
+                params.push(kimiToolMessage);
+            }
+            const text = i === 0 ? getSystemMessageText(msg) : renderSystemMessageUpdate(msg);
+            if (text.length > 0) {
+                params.push({ role: instructionRole, content: sanitizeSurrogates(text) });
+            }
+        }
+        else if (msg.role === "user") {
             if (typeof msg.content === "string") {
                 appendUserMessage(params, sanitizeSurrogates(msg.content), mergeAdjacentUserMessages);
             }
             else {
-                const content = msg.content.map((item) => {
+                const content = msg.content
+                    .filter((item) => item.type !== "text" || item.text.length > 0)
+                    .map((item) => {
                     if (item.type === "text") {
                         return {
                             type: "text",
@@ -1361,7 +1388,7 @@ export function convertMessages(model, context, compat, options = {}) {
         }
         else if (msg.role === "toolResult") {
             const imageBlocks = [];
-            const deferredToolNames = new Set();
+            const deferredTools = [];
             let j = i;
             for (; j < transformedMessages.length && transformedMessages[j].role === "toolResult"; j++) {
                 const toolMsg = transformedMessages[j];
@@ -1384,10 +1411,12 @@ export function convertMessages(model, context, compat, options = {}) {
                     Object.assign(toolResultMsg, { name: toolMsg.toolName });
                 }
                 params.push(toolResultMsg);
-                if (compat.deferredToolsMode === "kimi") {
-                    for (const name of toolMsg.addedToolNames ?? []) {
-                        deferredToolNames.add(name);
-                    }
+                for (const name of toolMsg.addedToolNames ?? []) {
+                    const tool = kimiDeferredTools.get(name);
+                    if (!tool || loadedToolNames.has(name))
+                        continue;
+                    loadedToolNames.add(name);
+                    deferredTools.push(tool);
                 }
                 if (hasImages && model.input.includes("image")) {
                     for (const block of toolMsg.content) {
@@ -1425,16 +1454,13 @@ export function convertMessages(model, context, compat, options = {}) {
             else {
                 lastRole = "toolResult";
             }
-            if (deferredToolNames.size > 0) {
-                const deferredTools = getToolsByName(context.tools, deferredToolNames);
-                if (deferredTools.length > 0) {
-                    const kimiToolMessage = {
-                        role: "system",
-                        tools: convertTools(deferredTools, compat),
-                    };
-                    // Kimi accepts a system message with tools but omits the standard content field.
-                    params.push(kimiToolMessage);
-                }
+            if (deferredTools.length > 0) {
+                const kimiToolMessage = {
+                    role: "system",
+                    tools: convertTools(deferredTools, compat),
+                };
+                // Kimi accepts a system message with tools but omits the standard content field.
+                params.push(kimiToolMessage);
             }
             continue;
         }

package/dist/api/openai-images-params.d.ts

@@ -1,6 +1,6 @@
 import type { Uploadable } from "openai";
 import type { ImageGenerateParamsNonStreaming } from "openai/resources/images.js";
-import type { ImageContent, ImagesContext, ImagesModel, ImagesOptions } from "../types.ts";
+import type { ImageApi, ImageContent, ImageModel, ImagesContext, ImagesOptions } from "../types.ts";
 export type OpenAIImageQuality = "auto" | "low" | "medium" | "high" | "xhigh" | "max";
 export type OpenAIImageSize = "auto" | "1024x1024" | "1536x1024" | "1024x1536" | `${number}x${number}`;
 export type OpenAIImageBackground = "auto" | "transparent" | "opaque";
@@ -55,6 +55,6 @@ export type OpenAIImageOutputOptions = {
  * compression is a jpeg/webp-only integer percentage, and a mask edits an image.
  */
 export declare function parseOpenAIImageOutputOptions(input: OpenAIImageOutputOptionsInput): OpenAIImageOutputOptions;
-export declare function buildParams(model: ImagesModel<"openai-images">, context: ImagesContext, options?: OpenAIImagesOptions): OpenAIImageParams;
+export declare function buildParams(model: ImageModel<ImageApi>, context: ImagesContext, options?: OpenAIImagesOptions): OpenAIImageParams;
 export declare function isImageParams(value: unknown): value is OpenAIImageParams;
 //# sourceMappingURL=openai-images-params.d.ts.map

package/dist/api/openai-images.d.ts

@@ -1,5 +1,5 @@
 import type { ImagesFunction } from "../types.ts";
 import { type OpenAIImagesOptions } from "./openai-images-params.ts";
 export { type OpenAIImageBackground, type OpenAIImageModeration, type OpenAIImageOutputFormat, type OpenAIImageQuality, type OpenAIImageSize, type OpenAIImagesOptions, parseOpenAIImageOutputOptions, parseOpenAIImageSize, } from "./openai-images-params.ts";
-export declare const generateImages: ImagesFunction<"openai-images", OpenAIImagesOptions>;
+export declare const generateImages: ImagesFunction<OpenAIImagesOptions>;
 //# sourceMappingURL=openai-images.d.ts.map

package/dist/api/openai-responses-shared.d.ts

@@ -1,19 +1,22 @@
 import type { Tool as OpenAITool, ResponseCreateParamsStreaming, ResponseInput, ResponseStreamEvent } from "openai/resources/responses/responses.js";
-import type { Api, AssistantMessage, Context, Model, Tool, Usage } from "../types.ts";
+import type { Api, AssistantMessage, Message, Model, StreamOptions, Tool, TranscriptContext, Usage } from "../types.ts";
 import type { AssistantMessageEventStream } from "../utils/event-stream.ts";
 export interface OpenAIResponsesStreamOptions {
-    serviceTier?: ResponseCreateParamsStreaming["service_tier"] | "fast";
+    onProviderStreamEvent?: StreamOptions["onProviderStreamEvent"];
+    serviceTier?: ResponseCreateParamsStreaming["service_tier"] | "fast" | "ultrafast";
     grammarToolInputProperties?: ReadonlyMap<string, string>;
-    resolveServiceTier?: (responseServiceTier: ResponseCreateParamsStreaming["service_tier"] | "fast" | undefined, requestServiceTier: ResponseCreateParamsStreaming["service_tier"] | "fast" | undefined) => ResponseCreateParamsStreaming["service_tier"] | "fast" | undefined;
-    applyServiceTierPricing?: (usage: Usage, serviceTier: ResponseCreateParamsStreaming["service_tier"] | "fast" | undefined) => void;
+    resolveServiceTier?: (responseServiceTier: ResponseCreateParamsStreaming["service_tier"] | "fast" | "ultrafast" | undefined, requestServiceTier: ResponseCreateParamsStreaming["service_tier"] | "fast" | "ultrafast" | undefined) => ResponseCreateParamsStreaming["service_tier"] | "fast" | "ultrafast" | undefined;
+    applyServiceTierPricing?: (usage: Usage, serviceTier: ResponseCreateParamsStreaming["service_tier"] | "fast" | "ultrafast" | undefined) => void;
 }
 export interface ConvertResponsesMessagesOptions {
     includeSystemPrompt?: boolean;
     preserveThinking?: boolean;
     preserveTextSignatures?: boolean;
     grammarToolInputProperties?: ReadonlyMap<string, string>;
-    deferredTools?: ReadonlyMap<string, Tool>;
-    deferredToolsMode?: "additional-tools" | "tool-search";
+    /** Whether later system messages are sent in place; otherwise they are folded into the leading prompt. */
+    supportsMidConvoSystemMessages?: boolean;
+    supportsAdditionalTools?: boolean;
+    supportsToolSearch?: boolean;
     toolOptions?: ConvertResponsesToolsOptions;
     /**
      * Send the system prompt as one `input_text` block carrying an explicit
@@ -28,10 +31,30 @@ export interface ConvertResponsesToolsOptions {
     strict?: boolean | null;
     supportsStrictMode?: boolean;
     supportsOpenAIGrammarTools?: boolean;
-    deferLoading?: boolean;
+    toolSearchResult?: boolean;
 }
 export declare const CUSTOM_TOOL_CALL_ITEM_ID_SENTINEL = "custom";
-export declare function convertResponsesMessages<TApi extends Api>(model: Model<TApi>, context: Context, allowedToolCallProviders: ReadonlySet<string>, options?: ConvertResponsesMessagesOptions): ResponseInput;
+export type ResponsesDeferredToolsMode = "additional-tools" | "tool-search";
+/** `additional_tools` items win over client tool search when a model supports both. */
+export declare function resolveResponsesDeferredToolsMode(compat: {
+    supportsAdditionalTools?: boolean;
+    supportsToolSearch?: boolean;
+} | undefined): ResponsesDeferredToolsMode | undefined;
+export interface ResponsesToolPlacement {
+    /** Tools sent in the top-level `tools` field. */
+    requestTools: Tool[];
+    /** Whether later system messages load their own `toolsAdded` in place. */
+    anchorsAdditions: boolean;
+    /** Tools a tool result loads in place through `addedToolNames`. */
+    deferred: ReadonlyMap<string, Tool>;
+}
+/**
+ * Upstream transcript placement plus the fork's `addedToolNames` deferral: a current tool first named by a
+ * tool result's `addedToolNames` (before any call to it) leaves the top-level `tools` field and is loaded
+ * where that result appears, so lazy activation never rewrites the cached prefix.
+ */
+export declare function resolveResponsesToolPlacement(messages: readonly Message[], supportsToolAdditions: boolean): ResponsesToolPlacement;
+export declare function convertResponsesMessages<TApi extends Api>(model: Model<TApi>, context: TranscriptContext, allowedToolCallProviders: ReadonlySet<string>, options?: ConvertResponsesMessagesOptions): ResponseInput;
 export declare function convertResponsesTools(tools: readonly Tool[], options?: ConvertResponsesToolsOptions): OpenAITool[];
 export declare function processResponsesStream<TApi extends Api>(openaiStream: AsyncIterable<ResponseStreamEvent>, output: AssistantMessage, stream: AssistantMessageEventStream, model: Model<TApi>, options?: OpenAIResponsesStreamOptions): Promise<void>;
 //# sourceMappingURL=openai-responses-shared.d.ts.map

package/dist/api/openai-responses-shared.js

@@ -1,8 +1,11 @@
 import { CONTEXT_PROVENANCE_FIELD, contextProvenanceFingerprint, getContextProvenance, } from "../context-provenance.js";
 import { calculateCost, supportsConfigurationUpdate } from "../models.js";
+import { splitDeferredTools } from "../utils/deferred-tools.js";
 import { shortHash } from "../utils/hash.js";
 import { parseStreamingJson } from "../utils/json-parse.js";
 import { sanitizeSurrogates } from "../utils/sanitize-unicode.js";
+import { getSystemMessageText, renderSystemMessageUpdate } from "../utils/text.js";
+import { getCurrentTools, getDeclaredTools, resolveTranscript, resolveTranscriptTools } from "../utils/transcript.js";
 import { appendGrammarToolInputJsonDelta, getGrammarToolInput, getJsonSchemaToolParameters, resolveGrammarConstrainedSampling, resolveJsonSchemaStrictSampling, } from "./constrained-sampling.js";
 import { parsePromptCacheDiagnostics } from "./openai-responses-prompt-cache.js";
 import { withResponsesCompletionGrace } from "./responses-completion-grace.js";
@@ -113,11 +116,36 @@ function withContextProvenance(item, message, seal) {
     }
     return item;
 }
+/** `additional_tools` items win over client tool search when a model supports both. */
+export function resolveResponsesDeferredToolsMode(compat) {
+    if (compat?.supportsAdditionalTools)
+        return "additional-tools";
+    return compat?.supportsToolSearch ? "tool-search" : undefined;
+}
+/**
+ * Upstream transcript placement plus the fork's `addedToolNames` deferral: a current tool first named by a
+ * tool result's `addedToolNames` (before any call to it) leaves the top-level `tools` field and is loaded
+ * where that result appears, so lazy activation never rewrites the cached prefix.
+ */
+export function resolveResponsesToolPlacement(messages, supportsToolAdditions) {
+    const transcriptTools = resolveTranscriptTools(messages, supportsToolAdditions);
+    const { deferred } = splitDeferredTools({ messages: [...messages], tools: getCurrentTools(messages) }, supportsToolAdditions);
+    return {
+        requestTools: transcriptTools.requestTools.filter((tool) => !deferred.has(tool.name)),
+        anchorsAdditions: transcriptTools.anchorsAdditions,
+        deferred,
+    };
+}
 // =============================================================================
 // Message conversion
 // =============================================================================
 export function convertResponsesMessages(model, context, allowedToolCallProviders, options) {
+    const normalizedContext = resolveTranscript(context, options?.supportsMidConvoSystemMessages);
     const messages = [];
+    const deferredToolsMode = resolveResponsesDeferredToolsMode(options);
+    const toolPlacement = resolveResponsesToolPlacement(normalizedContext.messages, deferredToolsMode !== undefined);
+    const declaredTools = getDeclaredTools(normalizedContext.messages);
+    // One ledger for both in-place loading paths: transcript system messages and `addedToolNames`.
     const loadedToolNames = new Set();
     const normalizeIdPart = (part) => {
         const sanitized = part.replace(/[^a-zA-Z0-9_-]/g, "_");
@@ -146,25 +174,52 @@ export function convertResponsesMessages(model, context, allowedToolCallProvider
         }
         return `${normalizedCallId}|${normalizedItemId}`;
     };
-    const transformedMessages = transformMessages(context.messages, model, normalizeToolCallId, {
+    const transformedMessages = transformMessages(normalizedContext.messages, model, normalizeToolCallId, {
         preserveThinking: options?.preserveThinking,
         preserveTextSignatures: options?.preserveTextSignatures,
     });
-    const includeSystemPrompt = options?.includeSystemPrompt ?? true;
-    if (includeSystemPrompt && context.systemPrompt) {
-        const compat = model.compat;
-        const role = model.reasoning && compat?.supportsDeveloperRole !== false ? "developer" : "system";
-        const text = sanitizeSurrogates(context.systemPrompt);
-        if (options?.systemPromptCacheBreakpoint === true) {
-            const block = { type: "input_text", text, prompt_cache_breakpoint: { mode: "explicit" } };
-            messages.push({ role, content: [block] });
-        }
-        else {
-            messages.push({ role, content: text });
+    const appendSystemToolAdditions = (message, seed) => {
+        const tools = toolPlacement.anchorsAdditions
+            ? (message.toolsAdded ?? []).filter((tool) => !loadedToolNames.has(tool.name))
+            : [];
+        if (tools.length === 0)
+            return;
+        for (const tool of tools)
+            loadedToolNames.add(tool.name);
+        if (options?.supportsAdditionalTools) {
+            messages.push({
+                type: "additional_tools",
+                role: "developer",
+                tools: convertResponsesTools(tools, options.toolOptions),
+            });
+            return;
         }
-    }
+        if (!options?.supportsToolSearch)
+            return;
+        const names = tools.map((tool) => tool.name);
+        const callId = `pi_tool_load_${shortHash(`${seed}:${names.join(",")}`)}`;
+        messages.push({
+            type: "tool_search_call",
+            call_id: callId,
+            execution: "client",
+            status: "completed",
+            arguments: { query: names.join(" "), limit: names.length },
+        });
+        messages.push({
+            type: "tool_search_output",
+            call_id: callId,
+            execution: "client",
+            status: "completed",
+            tools: convertResponsesTools(tools, { ...options.toolOptions, toolSearchResult: true }),
+        });
+    };
+    const includeInitialSystemMessage = options?.includeSystemPrompt ?? true;
+    const compat = model.compat;
+    const instructionRole = model.reasoning && compat?.supportsDeveloperRole !== false ? "developer" : "system";
     let msgIndex = 0;
+    let sourceIndex = 0;
     for (const msg of transformedMessages) {
+        const isLeadingSystemMessage = sourceIndex++ === 0 && msg.role === "system";
         if (msg.role === "configurationUpdate") {
             if (!supportsConfigurationUpdate(model))
                 continue;
@@ -180,7 +235,25 @@ export function convertResponsesMessages(model, context, allowedToolCallProvider
             }
             continue;
         }
-        if (msg.role === "user") {
+        if (msg.role === "system") {
+            if (!isLeadingSystemMessage)
+                appendSystemToolAdditions(msg, `system:${msgIndex}`);
+            if (!isLeadingSystemMessage || includeInitialSystemMessage) {
+                const text = isLeadingSystemMessage ? getSystemMessageText(msg) : renderSystemMessageUpdate(msg);
+                if (text.length > 0 && isLeadingSystemMessage && options?.systemPromptCacheBreakpoint === true) {
+                    const block = {
+                        type: "input_text",
+                        text: sanitizeSurrogates(text),
+                        prompt_cache_breakpoint: { mode: "explicit" },
+                    };
+                    messages.push({ role: instructionRole, content: [block] });
+                }
+                else if (text.length > 0) {
+                    messages.push({ role: instructionRole, content: sanitizeSurrogates(text) });
+                }
+            }
+        }
+        else if (msg.role === "user") {
             if (typeof msg.content === "string") {
                 messages.push(withContextProvenance({
                     role: "user",
@@ -259,7 +332,7 @@ export function convertResponsesMessages(model, context, allowedToolCallProvider
                     const [callId, itemIdRaw] = toolCall.id.split("|");
                     const customInputProperty = options?.grammarToolInputProperties?.get(toolCall.name);
                     const isPersistedFreeform = itemIdRaw === CUSTOM_TOOL_CALL_ITEM_ID_SENTINEL;
-                    const isFreeform = isFreeformToolName(toolCall.name, context.tools) || isPersistedFreeform;
+                    const isFreeform = isFreeformToolName(toolCall.name, declaredTools) || isPersistedFreeform;
                     let itemId = isPersistedFreeform ? undefined : itemIdRaw;
                     // An active grammar declaration wins over sentinel recovery below: its
                     // named input property is richer than the persisted freeform fallback.
@@ -272,7 +345,7 @@ export function convertResponsesMessages(model, context, allowedToolCallProvider
                         (!isFreeform && customInputProperty === undefined && !itemId?.startsWith("fc_"))) {
                         itemId = undefined;
                     }
-                    const canReplayNamespace = isSameModel || options?.deferredTools?.has(toolCall.name) === true;
+                    const canReplayNamespace = isSameModel || toolPlacement.deferred.has(toolCall.name);
                     if (customInputProperty !== undefined) {
                         output.push({
                             type: "custom_tool_call",
@@ -326,7 +399,7 @@ export function convertResponsesMessages(model, context, allowedToolCallProvider
                     output,
                 }, msg, options?.sealContextProvenance));
             }
-            else if (isFreeformToolName(msg.toolName, context.tools) || isPersistedFreeform) {
+            else if (isFreeformToolName(msg.toolName, declaredTools) || isPersistedFreeform) {
                 messages.push(withContextProvenance({
                     type: "custom_tool_call_output",
                     call_id: callId,
@@ -339,20 +412,20 @@ export function convertResponsesMessages(model, context, allowedToolCallProvider
             }
             const deferredTools = [];
             for (const name of msg.addedToolNames ?? []) {
-                const tool = options?.deferredTools?.get(name);
+                const tool = toolPlacement.deferred.get(name);
                 if (!tool || loadedToolNames.has(name))
                     continue;
                 loadedToolNames.add(name);
                 deferredTools.push(tool);
             }
-            if (deferredTools.length > 0 && options?.deferredToolsMode === "additional-tools") {
+            if (deferredTools.length > 0 && deferredToolsMode === "additional-tools") {
                 messages.push(withContextProvenance({
                     type: "additional_tools",
                     role: "developer",
-                    tools: convertResponsesTools(deferredTools, options.toolOptions),
-                }, msg, options.sealContextProvenance));
+                    tools: convertResponsesTools(deferredTools, options?.toolOptions),
+                }, msg, options?.sealContextProvenance));
             }
-            else if (deferredTools.length > 0 && options?.deferredToolsMode === "tool-search") {
+            else if (deferredTools.length > 0 && deferredToolsMode === "tool-search") {
                 const names = deferredTools.map((tool) => tool.name);
                 const searchCallId = `pi_tool_load_${shortHash(`${msg.toolCallId}:${names.join(",")}`)}`;
                 messages.push(withContextProvenance({
@@ -369,12 +442,13 @@ export function convertResponsesMessages(model, context, allowedToolCallProvider
                     status: "completed",
                     tools: convertResponsesTools(deferredTools, {
                         ...options?.toolOptions,
-                        deferLoading: true,
+                        toolSearchResult: true,
                     }),
                 }, msg, options?.sealContextProvenance));
             }
         }
-        msgIndex++;
+        if (!isLeadingSystemMessage)
+            msgIndex++;
     }
     return messages;
 }
@@ -397,7 +471,7 @@ export function convertResponsesTools(tools, options) {
                     syntax: grammar.format,
                     definition: grammar.definition,
                 },
-                ...(options?.deferLoading ? { defer_loading: true } : {}),
+                ...(options?.toolSearchResult ? { defer_loading: true } : {}),
             };
         }
         if (tool.freeform) {
@@ -406,7 +480,7 @@ export function convertResponsesTools(tools, options) {
                 name: tool.name,
                 description: tool.description,
                 format: tool.freeform,
-                ...(options?.deferLoading ? { defer_loading: true } : {}),
+                ...(options?.toolSearchResult ? { defer_loading: true } : {}),
             };
         }
         const constrainedStrict = resolveJsonSchemaStrictSampling(tool, supportsStrictMode);
@@ -416,7 +490,7 @@ export function convertResponsesTools(tools, options) {
             name: tool.name,
             description: tool.description,
             parameters: getJsonSchemaToolParameters(tool, strict === true),
-            ...(options?.deferLoading ? { defer_loading: true } : {}),
+            ...(options?.toolSearchResult ? { defer_loading: true } : {}),
         };
         if (supportsStrictMode) {
             functionTool.strict = strict;
@@ -712,6 +786,7 @@ export async function processResponsesStream(openaiStream, output, stream, model
         }
     };
     for await (const event of withResponsesCompletionGrace(openaiStream)) {
+        await options?.onProviderStreamEvent?.(event, model);
         if (event.type === "response.created") {
             output.responseId = event.response.id;
         }
@@ -920,6 +995,19 @@ export async function processResponsesStream(openaiStream, output, stream, model
     if (!sawTerminalResponseEvent && !hasFinalizedToolCall) {
         throw new Error("OpenAI Responses stream ended before a terminal response event");
     }
+    // The agent runs every tool call in the final message. Refuse to hand over calls whose
+    // output_item.done never arrived: their arguments may be cut off or mixed up, e.g. when a
+    // non-compliant server omits output_index. Finished calls have their scratch buffers removed.
+    if (output.stopReason === "toolUse") {
+        for (const block of output.content) {
+            if (block.type !== "toolCall")
+                continue;
+            const toolCall = block;
+            if (toolCall.partialJson !== undefined || toolCall.customInput !== undefined) {
+                throw new Error(`OpenAI Responses stream completed with an unfinished tool call: ${toolCall.name} (${toolCall.id})`);
+            }
+        }
+    }
 }
 function mapStopReason(status, incompleteReason) {
     if (!status)

package/dist/api/openai-responses.d.ts

@@ -17,7 +17,7 @@ export interface CachedWebSocketConnection {
 export interface OpenAIResponsesOptions extends StreamOptions {
     reasoningEffort?: "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
     reasoningSummary?: "auto" | "detailed" | "concise" | null;
-    serviceTier?: ResponseCreateParamsStreaming["service_tier"] | "fast";
+    serviceTier?: ResponseCreateParamsStreaming["service_tier"] | "fast" | "ultrafast";
     toolChoice?: ResponseCreateParamsStreaming["tool_choice"];
 }
 /**