@mupt-ai/dari-gateway 0.1.0 → 0.2.1

package/src/providers/pi_options.ts

@@ -1,30 +1,45 @@
 import type { BedrockOptions } from "@mupt-ai/pi-ai/api/bedrock-converse-stream";
 import { isReasoningEffort, isRecord, type ReasoningEffort } from "@mupt-ai/dari-router/policy-engine";
-import type { InteractionRequest, InteractionResponseFormat, InteractionToolChoice } from "../interaction/types";
-import { requiredCapabilitiesFor } from "../interaction/capabilities";
-import { toolWireName, toolsByWireName } from "../interaction/tool_identity";
-import { gatewayFor, payloadWithGatewayFields } from "../models/gateways";
-import { offRequiresWireNone } from "../models/runtime_overrides";
-import { effectiveReasoningForModel, validateReasoningEffortForModel } from "./reasoning";
-import { isBedrockApi, isOpenAIResponsesApi } from "./model_capabilities";
-import type { ResolvedProviderAuth } from "../types";
-import type { ProviderFetch } from "./response_capture";
-import { forwardsAnthropicSafeguards, payloadWithSafeguards } from "./anthropic_safeguards";
+import type { InteractionRequest, InteractionResponseFormat, InteractionToolChoice } from "../interaction/types.js";
+import { requiredCapabilitiesFor } from "../interaction/capabilities.js";
+import { toolWireName, toolsByWireName } from "../interaction/tool_identity.js";
+import { gatewayFor, payloadWithGatewayFields } from "../models/gateways.js";
+import { offRequiresWireNone } from "../models/runtime_overrides.js";
+import { effectiveReasoningForModel, validateReasoningEffortForModel } from "./reasoning.js";
+import { isBedrockApi, isOpenAIResponsesApi } from "./model_capabilities.js";
+import type { ResolvedProviderAuth } from "../types.js";
+import type { ProviderFetch } from "./response_capture.js";
+import { forwardsAnthropicSafeguards, payloadWithSafeguards } from "./anthropic_safeguards.js";
 
 type PiOptionsSupport = {
   getSupportedThinkingLevels?: (model: Record<string, unknown>) => string[];
 };
 
+type Payload = Record<string, unknown>;
+// A patch returns the next payload, or undefined to leave it unchanged.
+type PayloadPatch = (payload: Payload) => unknown;
+type Model = Record<string, unknown>;
+type ImageDetail = "auto" | "low" | "high" | "original";
+
 const ANTHROPIC_FAST_MODE_BETA = "fast-mode-2026-02-01";
+const ANTHROPIC_BINDING_CONTROLS_BETA = "thinking-binding-controls-2026-08-01";
 // Anthropic rejects newer models from older Claude Code versions, so forward
 // the client's own user agent and keep this fallback current for other clients.
 const CLAUDE_CODE_USER_AGENT = "claude-cli/2.1.280";
+const IMAGE_DETAILS: readonly unknown[] = ["auto", "low", "high", "original"];
+
+const isAnthropic = (api: unknown) => api === "anthropic-messages";
+const isCompletions = (api: unknown) => api === "openai-completions";
+// Responses payloads Pi builds from the public OpenAI/Azure APIs (not Codex).
+const isResponses = (api: unknown) => api === "openai-responses" || api === "azure-openai-responses";
+const isOpenAI = (api: unknown) => isResponses(api) || isCompletions(api);
+const isGoogle = (api: unknown) => api === "google-generative-ai" || api === "google-vertex";
 
 export function buildOptions(
   request: InteractionRequest,
   auth: ResolvedProviderAuth | string,
   selectedModel: string,
-  model: Record<string, unknown>,
+  model: Model,
   pi: PiOptionsSupport,
   sessionId?: string,
   selectedReasoningEffort?: ReasoningEffort,
@@ -32,218 +47,153 @@ export function buildOptions(
   signal?: AbortSignal,
   fetch?: ProviderFetch,
 ): Record<string, unknown> {
-  const providerAuth = typeof auth === "string" ? { type: "bearer" as const, apiKey: auth } : auth;
-  const authentication = isBedrockApi(model.api)
-    ? bedrockAuthenticationOptions(providerAuth)
-    : providerAuthenticationOptions(providerAuth);
+  const api = model.api;
+  const providerAuth: ResolvedProviderAuth = typeof auth === "string" ? { type: "bearer", apiKey: auth } : auth;
+  const { generation, toolChoice, parallelToolCalls, responseFormat } = request;
+  const headers: Record<string, string> = {};
   const options: Record<string, unknown> = {
-    ...authentication,
-    ...(isClaudeCodeOAuth(providerAuth, model) ? { headers: { "user-agent": request.claudeCodeUserAgent ?? CLAUDE_CODE_USER_AGENT } } : {}),
+    ...authenticationOptions(providerAuth, api),
     maxRetries: 0,
     timeoutMs,
-    ...(signal === undefined ? {} : { signal }),
-    ...(fetch === undefined ? {} : { fetch }),
-    metadata: {
-      ...(request.metadata ?? {}),
-      ...(request.user ? { user: request.user } : {}),
-    },
+    signal,
+    fetch,
+    metadata: { ...request.metadata, ...(request.user ? { user: request.user } : {}) },
     // Feeds OpenAI prompt_cache_key + session-affinity headers inside pi-ai;
     // ignored by providers without session-based caching.
-    ...(sessionId ? { sessionId } : {}),
+    sessionId: sessionId || undefined,
   };
+  const patches: PayloadPatch[] = [];
+
+  if (isClaudeCodeOAuth(providerAuth, api)) {
+    headers["user-agent"] = request.claudeCodeUserAgent ?? CLAUDE_CODE_USER_AGENT;
+  }
   // Pi's Anthropic transport honors compat.supportsTemperature; the OpenAI
   // transports forward temperature regardless, so drop it here for models
   // that reject it instead of failing the whole request.
-  if (
-    request.generation.temperature !== undefined
-    && !(isRecord(model.compat) && model.compat.supportsTemperature === false)
-  ) {
-    options.temperature = request.generation.temperature;
-  }
-  if (request.generation.maxOutputTokens !== undefined) options.maxTokens = request.generation.maxOutputTokens;
-  const payloadPatches: Array<(payload: Record<string, unknown>) => unknown> = [];
-  if (request.generation.topP !== undefined || request.generation.stop !== undefined) {
-    payloadPatches.push((payload) => payloadWithSamplingControls(payload, request, model));
+  if (!(isRecord(model.compat) && model.compat.supportsTemperature === false)) {
+    options.temperature = generation.temperature;
   }
-  const requestedReasoningBudget = request.reasoning?.budgetTokens;
-  if (request.reasoning?.enabled === false && model.api === "anthropic-messages") {
-    payloadPatches.push((payload) => ({
-      ...payload,
-      thinking: { type: "disabled" },
-    }));
-  } else if (requestedReasoningBudget !== undefined && model.api === "anthropic-messages") {
-    payloadPatches.push((payload) => ({
-      ...payload,
-      thinking: {
-        ...(isRecord(payload.thinking) ? payload.thinking : {}),
-        type: "enabled",
-        budget_tokens: requestedReasoningBudget,
-      },
-    }));
+  options.maxTokens = generation.maxOutputTokens;
+  if (generation.topP !== undefined || generation.stop !== undefined) {
+    patches.push((payload) => payloadWithSamplingControls(payload, request, api));
   }
-  if (model.api === "anthropic-messages") {
-    // Pi sends `thinking.block_binding: {prefix_mismatch_behavior:
-    // "drop_block"}` plus the binding-controls beta on mid-conversation-effort
-    // models (Fable 5.1, Opus 5). That opts every request into the preserved-
-    // thinking prefix check: when a replayed thinking block's recorded prefix
-    // no longer matches (client re-render, retry, or provider refusal in the
-    // loop), the API silently drops the block, which mutates the prompt bytes
-    // from that block onward and re-writes the rest of the conversation at
-    // cache-write prices. On organizations not yet enforced (created before
-    // 2026-08-31), opting out keeps the prefix stable and the cache warm; the
-    // API records the mismatch without acting on it.
-    payloadPatches.push((payload) => {
-      const thinking = payload.thinking;
-      if (!isRecord(thinking) || !isRecord(thinking.block_binding)) return undefined;
-      const { block_binding: _dropped, ...thinkingRest } = thinking;
-      const betas = Array.isArray(payload.betas)
-        ? (payload.betas as string[]).filter((beta) => beta !== "thinking-binding-controls-2026-08-01")
-        : payload.betas;
-      return { ...payload, thinking: thinkingRest, betas };
-    });
+
+  if (isAnthropic(api)) {
+    const budgetTokens = request.reasoning?.budgetTokens;
+    if (request.reasoning?.enabled === false) {
+      patches.push((payload) => ({ ...payload, thinking: { type: "disabled" } }));
+    } else if (budgetTokens !== undefined) {
+      patches.push((payload) => ({
+        ...payload,
+        thinking: { ...asRecord(payload.thinking), type: "enabled", budget_tokens: budgetTokens },
+      }));
+    }
+    patches.push(payloadWithoutThinkingBlockBinding);
   }
-  const gatewayFields = gatewayFor(model.provider)?.requestFields({
-    zdr: model.zeroDataRetention === true,
-  });
+
+  const gatewayFields = gatewayFor(model.provider)?.requestFields({ zdr: model.zeroDataRetention === true });
   if (gatewayFields !== undefined && Object.keys(gatewayFields).length > 0) {
-    payloadPatches.push((payload) => payloadWithGatewayFields(payload, gatewayFields));
+    patches.push((payload) => payloadWithGatewayFields(payload, gatewayFields));
   }
   const safeguards = request.anthropicSafeguards;
   if (safeguards !== undefined && forwardsAnthropicSafeguards(request, model)) {
-    payloadPatches.push((payload) => payloadWithSafeguards(payload, safeguards));
+    patches.push((payload) => payloadWithSafeguards(payload, safeguards));
   }
-  if (
-    requiredCapabilitiesFor(request).includes("openai_hosted_web_search") &&
-    isOpenAIResponsesApi(model.api)
-  ) {
+
+  if (isOpenAIResponsesApi(api) && requiredCapabilitiesFor(request).includes("openai_hosted_web_search")) {
     options.emitProviderEvents = true;
-    if (request.tools.some((tool) => tool.kind === "hosted")) {
-      payloadPatches.push((payload) => payloadWithHostedTools(payload, request));
+    const hosted = request.tools.flatMap((tool) => tool.kind === "hosted" ? [{ ...tool.config }] : []);
+    if (hosted.length > 0) {
+      patches.push((payload) => ({ ...payload, tools: [...asArray(payload.tools), ...hosted] }));
     }
   }
-  if (
-    (
-      model.api === "openai-responses"
-      || model.api === "azure-openai-responses"
-      || model.api === "openai-completions"
-    )
-    && imageDetailQueues(request).size > 0
-  ) {
-    payloadPatches.push((payload) => payloadWithImageDetails(payload, request));
+  if (isOpenAI(api)) {
+    const details = imageDetailQueues(request);
+    if (details.size > 0) patches.push((payload) => payloadWithImageDetails(payload, details));
   }
-  const requestedToolChoice = request.toolChoice;
-  if (requestedToolChoice !== undefined) {
-    if (isBedrockApi(model.api)) {
-      // Bedrock builds its Converse toolConfig from options.toolChoice before
-      // onPayload runs, so the choice must ride on options, not a payload patch.
-      const simpleChoice = bedrockToolChoice(requestedToolChoice);
-      if (simpleChoice !== undefined) options.toolChoice = simpleChoice;
-    } else {
-      payloadPatches.push((payload) => payloadWithToolChoice(payload, requestedToolChoice, model));
-    }
+
+  if (toolChoice !== undefined) {
+    // Bedrock builds its Converse toolConfig from options.toolChoice before
+    // onPayload runs, so the choice must ride on options, not a payload patch.
+    if (isBedrockApi(api)) options.toolChoice = bedrockToolChoice(toolChoice);
+    else patches.push((payload) => ({ ...payload, tool_choice: providerToolChoice(toolChoice, api) }));
   }
-  if (request.tools.some((tool) =>
-    tool.kind === "function" && (tool.strict !== undefined || model.api === "anthropic-messages")
-  )) {
-    payloadPatches.push((payload) => payloadWithStrictTools(payload, request, model));
+  if (request.tools.some((tool) => tool.kind === "function" && (tool.strict !== undefined || isAnthropic(api)))) {
+    patches.push((payload) => payloadWithStrictTools(payload, request, api));
   }
-  const requestedResponseFormat = request.responseFormat;
-  if (requestedResponseFormat !== undefined) {
-    options.responseFormat = responseFormat(requestedResponseFormat);
+  if (responseFormat !== undefined) {
+    options.responseFormat = piResponseFormat(responseFormat);
     // Pi keeps responseFormat in options but does not serialize it in simple
     // OpenAI adapters, so patch the provider payload at the boundary.
-    payloadPatches.push((payload) => payloadWithResponseFormat(payload, requestedResponseFormat, model));
+    patches.push((payload) => payloadWithResponseFormat(payload, responseFormat, api));
   }
-  const parallelToolCalls = request.parallelToolCalls;
   if (parallelToolCalls !== undefined) {
-    payloadPatches.push((payload) => payloadWithParallelToolCalls(payload, parallelToolCalls, model));
+    patches.push((payload) => payloadWithParallelToolCalls(payload, parallelToolCalls, api));
   }
+
   if (model.fastMode === true) {
-    if (model.provider === "openai" && model.api === "openai-responses") {
-      // Pi's simple adapter currently drops serviceTier while lowering its
-      // options, so patch the provider payload as well. Keep the option for
-      // usage-pricing fallback once the adapter preserves it end to end.
-      options.serviceTier = "priority";
-      payloadPatches.push((payload) => ({ ...payload, service_tier: "priority" }));
-    } else if (model.provider === "openai" && model.api === "openai-completions") {
-      payloadPatches.push((payload) => ({ ...payload, service_tier: "priority" }));
-    } else if (model.provider === "anthropic" && model.api === "anthropic-messages") {
-      payloadPatches.push((payload) => ({ ...payload, speed: "fast" }));
-      options.headers = {
-        ...(isRecord(options.headers) ? options.headers : {}),
-        "anthropic-beta": ANTHROPIC_FAST_MODE_BETA,
-      };
+    if (model.provider === "openai" && isOpenAI(api) && api !== "azure-openai-responses") {
+      // Pi's simple Responses adapter drops serviceTier while lowering its
+      // options, so patch the payload too; the option still feeds usage pricing.
+      if (api === "openai-responses") options.serviceTier = "priority";
+      patches.push((payload) => ({ ...payload, service_tier: "priority" }));
+    } else if (model.provider === "anthropic" && isAnthropic(api)) {
+      headers["anthropic-beta"] = ANTHROPIC_FAST_MODE_BETA;
+      patches.push((payload) => ({ ...payload, speed: "fast" }));
     }
   }
 
-  const supportedLevels = supportedThinkingLevels(model, pi);
-  const defaultReasoningEffort = isReasoningEffort(model.defaultThinkingLevel)
-    ? model.defaultThinkingLevel
-    : undefined;
-  const effectiveReasoning = effectiveReasoningForModel({
-    request,
-    selectedModel,
-    supportedLevels,
-    selectedReasoningEffort,
-    defaultReasoningEffort,
-  });
-  const providerReasoning = request.reasoning?.hasConfigurationUpdate
-    ? request.reasoning.baseEffort ?? defaultReasoningEffort
-    : effectiveReasoning;
-  if (request.reasoning?.baseEffort !== undefined) {
-    validateReasoningEffortForModel(
-      request.reasoning.baseEffort,
-      selectedModel,
-      supportedLevels,
-    );
-  }
-  if (providerReasoning !== undefined && providerReasoning !== "off") {
-    options.reasoning = providerReasoning;
-  } else if (
-    providerReasoning === "off" &&
-    offRequiresWireNone(selectedModel) &&
-    model.api === "openai-completions"
-  ) {
-    // These models need explicit "none" rather than the provider default.
-    // Gateways use nested reasoning; direct providers use reasoning_effort.
-    payloadPatches.push((payload) => {
-      if (!gatewayFor(model.provider)) return { ...payload, reasoning_effort: "none" };
-      const { reasoning_effort: _nativeEffort, ...rest } = payload;
-      return {
-        ...rest,
-        reasoning: { ...(isRecord(payload.reasoning) ? payload.reasoning : {}), effort: "none" },
-      };
-    });
-  }
-  if (
-    (requestedToolChoice !== undefined || parallelToolCalls !== undefined) &&
-    !isBedrockApi(model.api)
-  ) {
-    // Some clients send the default tool_choice even after omitting tools for
-    // a turn. OpenAI rejects every tool_choice value when the lowered payload
-    // has no tools, so enforce that provider invariant after all tool patches.
-    payloadPatches.push(payloadWithoutOrphanedToolChoice);
+  const reasoning = providerReasoning(request, selectedModel, model, pi, selectedReasoningEffort);
+  if (reasoning !== undefined && reasoning !== "off") {
+    options.reasoning = reasoning;
+  } else if (reasoning === "off" && isCompletions(api) && offRequiresWireNone(selectedModel)) {
+    patches.push((payload) => payloadWithReasoningNone(payload, model));
   }
+  if (isOpenAIResponsesApi(api)) patches.push(payloadWithDetailedReasoningSummary);
 
-  if (payloadPatches.length > 0) {
-    options.onPayload = (payload: unknown) => applyPayloadPatches(payload, payloadPatches);
+  // Some clients send the default tool_choice even after omitting tools for
+  // a turn. OpenAI rejects every tool_choice value when the lowered payload
+  // has no tools, so enforce that provider invariant after all tool patches.
+  if ((toolChoice !== undefined || parallelToolCalls !== undefined) && !isBedrockApi(api)) {
+    patches.push(payloadWithoutOrphanedToolChoice);
   }
-  return options;
+
+  if (Object.keys(headers).length > 0) options.headers = headers;
+  if (patches.length > 0) options.onPayload = (payload: unknown) => applyPayloadPatches(payload, patches);
+  return Object.fromEntries(Object.entries(options).filter(([, value]) => value !== undefined));
 }
 
-function providerAuthenticationOptions(auth: ResolvedProviderAuth): Record<string, unknown> {
-  if (auth.type === "bearer") return { apiKey: auth.apiKey };
-  throw new Error("AWS SigV4 authentication requires the Bedrock API.");
+export function supportedThinkingLevels(model: Model, pi: PiOptionsSupport): string[] {
+  const levels = Array.isArray(model.supportedThinkingLevels)
+    ? model.supportedThinkingLevels
+    : pi.getSupportedThinkingLevels?.(model);
+  return Array.isArray(levels) ? levels.filter((level) => typeof level === "string") : ["off"];
 }
 
-function isClaudeCodeOAuth(auth: ResolvedProviderAuth, model: Record<string, unknown>): boolean {
-  return auth.type === "bearer"
-    && model.api === "anthropic-messages"
-    && auth.apiKey.includes("sk-ant-oat");
+function providerReasoning(
+  request: InteractionRequest,
+  selectedModel: string,
+  model: Model,
+  pi: PiOptionsSupport,
+  selectedReasoningEffort: ReasoningEffort | undefined,
+): ReasoningEffort | undefined {
+  const supportedLevels = supportedThinkingLevels(model, pi);
+  const defaultReasoningEffort = isReasoningEffort(model.defaultThinkingLevel) ? model.defaultThinkingLevel : undefined;
+  const effective = effectiveReasoningForModel({
+    request,
+    selectedModel,
+    supportedLevels,
+    selectedReasoningEffort,
+    defaultReasoningEffort,
+  });
+  const baseEffort = request.reasoning?.baseEffort;
+  if (baseEffort !== undefined) validateReasoningEffortForModel(baseEffort, selectedModel, supportedLevels);
+  return request.reasoning?.hasConfigurationUpdate ? baseEffort ?? defaultReasoningEffort : effective;
 }
 
-function bedrockAuthenticationOptions(auth: ResolvedProviderAuth): BedrockOptions {
+function authenticationOptions(auth: ResolvedProviderAuth, api: unknown): BedrockOptions | Record<string, unknown> {
   if (auth.type === "bearer") return { apiKey: auth.apiKey };
+  if (!isBedrockApi(api)) throw new Error("AWS SigV4 authentication requires the Bedrock API.");
   return {
     env: {
       AWS_ACCESS_KEY_ID: auth.access_key_id,
@@ -257,18 +207,13 @@ function bedrockAuthenticationOptions(auth: ResolvedProviderAuth): BedrockOption
   };
 }
 
-function bedrockToolChoice(choice: InteractionToolChoice): unknown {
-  if (typeof choice === "object" && choice.kind === "hosted") return undefined;
-  if (typeof choice === "string") return choice;
-  return { type: "function", function: { name: toolWireName(choice.namespace, choice.name) } };
+function isClaudeCodeOAuth(auth: ResolvedProviderAuth, api: unknown): boolean {
+  return auth.type === "bearer" && isAnthropic(api) && auth.apiKey.includes("sk-ant-oat");
 }
 
-// Chains payload patches, preserving each patch's "undefined means leave the
-// payload unchanged" contract for the combined result.
-function applyPayloadPatches(
-  payload: unknown,
-  patches: Array<(payload: Record<string, unknown>) => unknown>
-): unknown {
+// Chains patches, preserving the "undefined means unchanged" contract for the
+// combined result.
+function applyPayloadPatches(payload: unknown, patches: PayloadPatch[]): unknown {
   if (!isRecord(payload)) return undefined;
   let current = payload;
   let changed = false;
@@ -282,305 +227,190 @@ function applyPayloadPatches(
   return changed ? current : undefined;
 }
 
-function payloadWithSamplingControls(
-  payload: Record<string, unknown>,
-  request: InteractionRequest,
-  model: Record<string, unknown>,
-): Record<string, unknown> {
-  const api = model.api;
-  const google = api === "google-generative-ai" || api === "google-vertex";
-  const bedrock = isBedrockApi(api);
-  const stop = request.generation.stop;
-  const stopSequences = typeof stop === "string" ? [stop] : stop;
-  const controls = {
-    // Anthropic rejects top_p with thinking; keep the hosted path aligned
-    // with the router's unsupported Anthropic top_p control.
-    ...(request.generation.topP === undefined || api === "anthropic-messages" ? {} : {
-      [google || bedrock ? "topP" : "top_p"]: request.generation.topP,
-    }),
-    ...(stop === undefined || isOpenAIResponsesApi(api) ? {} : {
-      [google || bedrock ? "stopSequences" : api === "anthropic-messages" ? "stop_sequences" : "stop"]:
-        api === "openai-completions" ? stop : stopSequences,
-    }),
-  };
-  if (google) {
-    return { ...payload, config: { ...(isRecord(payload.config) ? payload.config : {}), ...controls } };
-  }
-  if (bedrock) {
-    return {
-      ...payload,
-      inferenceConfig: {
-        ...(isRecord(payload.inferenceConfig) ? payload.inferenceConfig : {}),
-        ...controls,
-      },
-    };
-  }
+function asRecord(value: unknown): Payload {
+  return isRecord(value) ? value : {};
+}
+
+function asArray(value: unknown): unknown[] {
+  return Array.isArray(value) ? value : [];
+}
+
+function payloadWithSamplingControls(payload: Payload, request: InteractionRequest, api: unknown): Payload {
+  const { topP, stop } = request.generation;
+  const camelCase = isGoogle(api) || isBedrockApi(api);
+  const controls: Payload = {};
+  // Anthropic rejects top_p with thinking; keep the hosted path aligned with
+  // the router's unsupported Anthropic top_p control.
+  if (topP !== undefined && !isAnthropic(api)) controls[camelCase ? "topP" : "top_p"] = topP;
+  if (stop !== undefined && !isOpenAIResponsesApi(api)) {
+    const key = camelCase ? "stopSequences" : isAnthropic(api) ? "stop_sequences" : "stop";
+    controls[key] = isCompletions(api) || typeof stop !== "string" ? stop : [stop];
+  }
+  if (isGoogle(api)) return { ...payload, config: { ...asRecord(payload.config), ...controls } };
+  if (isBedrockApi(api)) return { ...payload, inferenceConfig: { ...asRecord(payload.inferenceConfig), ...controls } };
   return { ...payload, ...controls };
 }
 
-function responseFormat(format: InteractionResponseFormat): Record<string, unknown> {
-  if (format.type !== "json_schema") return format;
-  const { type: _, ...jsonSchema } = format;
-  return {
-    type: "json_schema",
-    jsonSchema,
-  };
+// Pi sends `thinking.block_binding: {prefix_mismatch_behavior: "drop_block"}`
+// plus the binding-controls beta on mid-conversation-effort models (Fable 5.1,
+// Opus 5). That opts every request into the preserved-thinking prefix check:
+// when a replayed thinking block's recorded prefix no longer matches (client
+// re-render, retry, or provider refusal in the loop), the API silently drops
+// the block, which mutates the prompt bytes from that block onward and
+// re-writes the rest of the conversation at cache-write prices. On
+// organizations not yet enforced (created before 2026-08-31), opting out keeps
+// the prefix stable and the cache warm; the API records the mismatch without
+// acting on it.
+function payloadWithoutThinkingBlockBinding(payload: Payload): Payload | undefined {
+  const thinking = payload.thinking;
+  if (!isRecord(thinking) || !isRecord(thinking.block_binding)) return undefined;
+  const { block_binding: _, ...rest } = thinking;
+  const betas = Array.isArray(payload.betas)
+    ? payload.betas.filter((beta) => beta !== ANTHROPIC_BINDING_CONTROLS_BETA)
+    : payload.betas;
+  return { ...payload, thinking: rest, betas };
 }
 
-function payloadWithResponseFormat(
-  payload: unknown,
-  format: InteractionResponseFormat,
-  model: Record<string, unknown>
-): unknown {
-  if (!isRecord(payload)) return undefined;
-  const providerFormat = providerResponseFormat(format, model);
-  if (providerFormat === null) return undefined;
-  if (model.api === "openai-responses" || model.api === "azure-openai-responses") {
-    return {
-      ...payload,
-      text: {
-        ...(isRecord(payload.text) ? payload.text : {}),
-        format: providerFormat,
-      },
-    };
-  }
-  if (model.api === "openai-completions") {
-    return { ...payload, response_format: providerFormat };
-  }
-  if (model.api === "anthropic-messages") {
-    return {
-      ...payload,
-      output_config: {
-        ...(isRecord(payload.output_config) ? payload.output_config : {}),
-        format: providerFormat,
-      },
-    };
-  }
-  return undefined;
+// These models need explicit "none" rather than the provider default.
+// Gateways use nested reasoning; direct providers use reasoning_effort.
+function payloadWithReasoningNone(payload: Payload, model: Model): Payload {
+  if (!gatewayFor(model.provider)) return { ...payload, reasoning_effort: "none" };
+  const { reasoning_effort: _, ...rest } = payload;
+  return { ...rest, reasoning: { ...asRecord(payload.reasoning), effort: "none" } };
 }
 
-function providerResponseFormat(
-  format: InteractionResponseFormat,
-  model: Record<string, unknown>
-): Record<string, unknown> | null {
-  if (format.type === "text") return null;
-  if (model.api === "anthropic-messages") {
-    return {
-      type: "json_schema",
-      schema: format.type === "json_schema" ? format.schema : { type: "object" },
-    };
-  }
-  if (format.type === "json_object") return format;
-  const { type: _, ...jsonSchema } = format;
-  if (model.api === "openai-responses" || model.api === "azure-openai-responses") {
-    return { ...jsonSchema, type: "json_schema" };
-  }
-  return { type: "json_schema", json_schema: jsonSchema };
+// Pi's default "auto" summary leaves many reasoning items empty (93% on the
+// ChatGPT Codex backend). Readable summaries are the only reasoning a later
+// turn on another provider can replay, so ask for detailed ones.
+function payloadWithDetailedReasoningSummary(payload: Payload): Payload | undefined {
+  if (!isRecord(payload.reasoning) || payload.reasoning.summary === undefined) return undefined;
+  return { ...payload, reasoning: { ...payload.reasoning, summary: "detailed" } };
 }
 
-function payloadWithToolChoice(
-  payload: Record<string, unknown>,
-  choice: InteractionToolChoice,
-  model: Record<string, unknown>
-): Record<string, unknown> {
-  if (typeof choice === "object" && choice.kind === "hosted") {
-    return { ...payload, tool_choice: { type: choice.type } };
-  }
-  if (model.api === "anthropic-messages") {
-    const toolChoice = typeof choice === "string"
-      ? anthropicToolChoice(choice)
-      : { type: "tool", name: toolWireName(choice.namespace, choice.name) };
-    return { ...payload, tool_choice: toolChoice };
-  }
-  if (model.api === "openai-responses" || model.api === "azure-openai-responses") {
-    const toolChoice = typeof choice === "string"
-      ? openAiToolChoice(choice)
-      // Pi currently declares both interaction tool kinds as JSON function tools.
-      : { type: "function", name: toolWireName(choice.namespace, choice.name) };
-    return { ...payload, tool_choice: toolChoice };
-  }
-  const toolChoice = typeof choice === "string"
-    ? openAiToolChoice(choice)
-    : { type: "function", function: { name: toolWireName(choice.namespace, choice.name) } };
-  return { ...payload, tool_choice: toolChoice };
+function piResponseFormat(format: InteractionResponseFormat): Payload {
+  if (format.type !== "json_schema") return format;
+  const { type: _, ...jsonSchema } = format;
+  return { type: "json_schema", jsonSchema };
 }
 
-function payloadWithoutOrphanedToolChoice(
-  payload: Record<string, unknown>,
-): Record<string, unknown> | undefined {
-  if (
-    !("tool_choice" in payload) ||
-    (Array.isArray(payload.tools) && payload.tools.length > 0)
-  ) {
+function payloadWithResponseFormat(payload: Payload, format: InteractionResponseFormat, api: unknown): unknown {
+  if (format.type === "text") return undefined;
+  if (isAnthropic(api)) {
+    const schema = format.type === "json_schema" ? format.schema : { type: "object" };
+    return { ...payload, output_config: { ...asRecord(payload.output_config), format: { type: "json_schema", schema } } };
+  }
+  if (format.type === "json_object") {
+    if (isResponses(api)) return { ...payload, text: { ...asRecord(payload.text), format } };
+    if (isCompletions(api)) return { ...payload, response_format: format };
     return undefined;
   }
-  const { tool_choice: _, ...withoutToolChoice } = payload;
-  return withoutToolChoice;
+  const { type: _, ...jsonSchema } = format;
+  if (isResponses(api)) return { ...payload, text: { ...asRecord(payload.text), format: { ...jsonSchema, type: "json_schema" } } };
+  if (isCompletions(api)) return { ...payload, response_format: { type: "json_schema", json_schema: jsonSchema } };
+  return undefined;
 }
 
-function anthropicToolChoice(choice: string): { type: string } {
-  switch (choice) {
-    case "required":
-    case "any":
-      return { type: "any" };
-    default:
-      return { type: choice };
-  }
+function bedrockToolChoice(choice: InteractionToolChoice): unknown {
+  if (typeof choice === "string") return choice;
+  if (choice.kind === "hosted") return undefined;
+  return { type: "function", function: { name: toolWireName(choice.namespace, choice.name) } };
 }
 
-function openAiToolChoice(choice: string): string {
-  return choice === "any" ? "required" : choice;
+function providerToolChoice(choice: InteractionToolChoice, api: unknown): unknown {
+  if (typeof choice === "string") {
+    if (isAnthropic(api)) return { type: choice === "required" ? "any" : choice };
+    return choice === "any" ? "required" : choice;
+  }
+  if (choice.kind === "hosted") return { type: choice.type };
+  const name = toolWireName(choice.namespace, choice.name);
+  if (isAnthropic(api)) return { type: "tool", name };
+  // Pi currently declares both interaction tool kinds as JSON function tools.
+  if (isResponses(api)) return { type: "function", name };
+  return { type: "function", function: { name } };
 }
 
-function payloadWithHostedTools(
-  payload: Record<string, unknown>,
-  request: Pick<InteractionRequest, "tools">
-): Record<string, unknown> {
-  const hosted = request.tools.flatMap((tool) =>
-    tool.kind === "hosted" ? [{ ...tool.config }] : []
-  );
-  if (hosted.length === 0) return payload;
-  return {
-    ...payload,
-    tools: [...(Array.isArray(payload.tools) ? payload.tools : []), ...hosted],
-  };
+function payloadWithoutOrphanedToolChoice(payload: Payload): Payload | undefined {
+  if (!("tool_choice" in payload) || asArray(payload.tools).length > 0) return undefined;
+  const { tool_choice: _, ...rest } = payload;
+  return rest;
 }
 
-function payloadWithStrictTools(
-  payload: Record<string, unknown>,
-  request: Pick<InteractionRequest, "tools">,
-  model: Record<string, unknown>
-): unknown {
-  if (!Array.isArray(payload.tools)) return undefined;
-  if (
-    model.api !== "openai-responses" &&
-    model.api !== "azure-openai-responses" &&
-    model.api !== "openai-completions" &&
-    model.api !== "anthropic-messages"
-  ) {
-    return undefined;
-  }
+function payloadWithStrictTools(payload: Payload, request: Pick<InteractionRequest, "tools">, api: unknown): unknown {
+  if (!Array.isArray(payload.tools) || !(isOpenAI(api) || isAnthropic(api))) return undefined;
   const definitions = toolsByWireName(request.tools);
-  return {
-    ...payload,
-    tools: payload.tools.map((entry) => {
-      if (!isRecord(entry)) return entry;
-      if (model.api === "anthropic-messages") {
-        const tool = typeof entry.name === "string" ? definitions.get(entry.name) : undefined;
-        if (!tool || tool.kind !== "function") return entry;
-        // defer_loading is intentionally not restored from the definition:
-        // Pi decides placement (deferred batch vs force-loaded immediate), and
-        // re-adding it here would recreate the cache_control/defer_loading
-        // combination Anthropic rejects. The entry spread preserves Pi's choice.
-        return {
-          ...entry,
-          ...(tool.parameters !== undefined ? { input_schema: tool.parameters } : {}),
-          ...(tool.strict !== undefined ? { strict: tool.strict } : {}),
-        };
-      }
-      const definition = model.api === "openai-completions" && isRecord(entry.function) ? entry.function : entry;
-      const tool = typeof definition.name === "string" ? definitions.get(definition.name) : undefined;
-      if (!tool || tool.kind !== "function" || tool.strict === undefined) return entry;
-      if (model.api === "openai-completions") {
-        return { ...entry, function: { ...definition, strict: tool.strict } };
-      }
-      return { ...entry, strict: tool.strict };
-    }),
+  const functionTool = (name: unknown) => {
+    const tool = typeof name === "string" ? definitions.get(name) : undefined;
+    return tool?.kind === "function" ? tool : undefined;
   };
+  const tools = payload.tools.map((entry) => {
+    if (!isRecord(entry)) return entry;
+    if (isAnthropic(api)) {
+      const tool = functionTool(entry.name);
+      if (!tool) return entry;
+      // defer_loading is intentionally not restored from the definition: Pi
+      // decides placement (deferred batch vs force-loaded immediate), and
+      // re-adding it here would recreate the cache_control/defer_loading
+      // combination Anthropic rejects. The entry spread preserves Pi's choice.
+      return {
+        ...entry,
+        ...(tool.parameters !== undefined ? { input_schema: tool.parameters } : {}),
+        ...(tool.strict !== undefined ? { strict: tool.strict } : {}),
+      };
+    }
+    if (isCompletions(api) && isRecord(entry.function)) {
+      const strict = functionTool(entry.function.name)?.strict;
+      return strict === undefined ? entry : { ...entry, function: { ...entry.function, strict } };
+    }
+    const strict = functionTool(entry.name)?.strict;
+    return strict === undefined ? entry : { ...entry, strict };
+  });
+  return { ...payload, tools };
 }
 
-function payloadWithParallelToolCalls(
-  payload: Record<string, unknown>,
-  enabled: boolean,
-  model: Record<string, unknown>
-): unknown {
-  if (model.api === "openai-responses" || model.api === "azure-openai-responses" || model.api === "openai-completions") {
-    return { ...payload, parallel_tool_calls: enabled };
-  }
-  if (model.api === "anthropic-messages" && !enabled) {
-    const current = isRecord(payload.tool_choice) ? payload.tool_choice : {};
-    if (current.type === "none") return undefined;
-    return {
-      ...payload,
-      tool_choice: {
-        type: typeof current.type === "string" ? current.type : "auto",
-        ...current,
-        disable_parallel_tool_use: true,
-      },
-    };
-  }
-  return undefined;
+function payloadWithParallelToolCalls(payload: Payload, enabled: boolean, api: unknown): unknown {
+  if (isOpenAI(api)) return { ...payload, parallel_tool_calls: enabled };
+  if (!isAnthropic(api) || enabled) return undefined;
+  const current = asRecord(payload.tool_choice);
+  if (current.type === "none") return undefined;
+  return { ...payload, tool_choice: { type: "auto", ...current, disable_parallel_tool_use: true } };
 }
 
-function payloadWithImageDetails(
-  payload: Record<string, unknown>,
-  request: InteractionRequest
-): unknown {
-  const details = imageDetailQueues(request);
-  if (details.size === 0) return undefined;
+// Fills `detail` on Responses (`input_image`) and Chat (`image_url`) parts,
+// matching request images to payload images by URL in order.
+function payloadWithImageDetails(payload: Payload, details: Map<string, ImageDetail[]>): unknown {
+  const queues = new Map([...details].map(([url, queue]) => [url, [...queue]]));
   let changed = false;
-
   const patch = (value: unknown): unknown => {
     if (Array.isArray(value)) return value.map(patch);
     if (!isRecord(value)) return value;
-
-    const mapped = Object.fromEntries(
-      Object.entries(value).map(([key, entry]) => [key, patch(entry)])
-    );
-    const responseUrl = mapped.type === "input_image" && typeof mapped.image_url === "string"
-      ? mapped.image_url
-      : undefined;
-    const chatImage = mapped.type === "image_url" && isRecord(mapped.image_url)
-      ? mapped.image_url
-      : undefined;
-    const chatUrl = typeof chatImage?.url === "string" ? chatImage.url : undefined;
-    const url = responseUrl ?? chatUrl;
-    if (!url) return mapped;
-
-    const queue = details.get(url);
-    const detail = queue?.shift();
-    if (detail === undefined) return mapped;
-    changed = true;
-    if (responseUrl) return { ...mapped, detail };
-    return { ...mapped, image_url: { ...chatImage, detail } };
+    const node = Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, patch(entry)]));
+    if (node.type === "input_image" && typeof node.image_url === "string") {
+      const detail = queues.get(node.image_url)?.shift();
+      if (detail === undefined) return node;
+      changed = true;
+      return { ...node, detail };
+    }
+    if (node.type === "image_url" && isRecord(node.image_url) && typeof node.image_url.url === "string") {
+      const detail = queues.get(node.image_url.url)?.shift();
+      if (detail === undefined) return node;
+      changed = true;
+      return { ...node, image_url: { ...node.image_url, detail } };
+    }
+    return node;
   };
-
   const patched = patch(payload);
-  return changed && isRecord(patched) ? patched : undefined;
+  return changed ? patched : undefined;
 }
 
-function imageDetailQueues(
-  request: InteractionRequest
-): Map<string, Array<"auto" | "low" | "high" | "original">> {
-  const details = new Map<string, Array<"auto" | "low" | "high" | "original">>();
-  const add = (content: unknown) => {
-    if (!Array.isArray(content)) return;
-    for (const part of content) {
+function imageDetailQueues(request: InteractionRequest): Map<string, ImageDetail[]> {
+  const details = new Map<string, ImageDetail[]>();
+  for (const item of request.items) {
+    const content = item.type === "message" ? item.content : item.type === "tool_result" ? item.output : undefined;
+    for (const part of asArray(content)) {
       if (!isRecord(part) || part.type !== "image" || typeof part.url !== "string") continue;
-      if (part.detail !== "auto" && part.detail !== "low" && part.detail !== "high" && part.detail !== "original") continue;
-      const queue = details.get(part.url) ?? [];
-      queue.push(part.detail);
-      details.set(part.url, queue);
+      if (!IMAGE_DETAILS.includes(part.detail)) continue;
+      details.set(part.url, [...(details.get(part.url) ?? []), part.detail as ImageDetail]);
     }
-  };
-  for (const item of request.items) {
-    if (item.type === "message") add(item.content);
-    if (item.type === "tool_result") add(item.output);
   }
   return details;
 }
-
-export function supportedThinkingLevels(
-  model: Record<string, unknown>,
-  pi: PiOptionsSupport
-): string[] {
-  const explicitLevels = model.supportedThinkingLevels;
-  if (Array.isArray(explicitLevels)) {
-    return explicitLevels.filter((level) => typeof level === "string");
-  }
-  const levels = pi.getSupportedThinkingLevels?.(model);
-  if (Array.isArray(levels)) {
-    return levels.filter((level) => typeof level === "string");
-  }
-  return ["off"];
-}