@jeffusion/bungee-llms 5.20.0 → 5.21.0

package/dist/index.js

@@ -8509,14 +8509,25 @@ var DEFAULT_RESPONSES_CODEC_LIMITS = Object.freeze({
 
 class ResponsesCodecError extends Error {
   code;
-  constructor(code, message) {
+  param;
+  constructor(code, message, param) {
     super(message);
     this.code = code;
+    this.param = param;
     this.name = "ResponsesCodecError";
   }
 }
-function fail(code, message) {
-  throw new ResponsesCodecError(code, message);
+function fail(code, message, param) {
+  throw new ResponsesCodecError(code, message, param);
+}
+function atParam(param, run) {
+  try {
+    return run();
+  } catch (error) {
+    if (error instanceof ResponsesCodecError && error.param === undefined)
+      throw new ResponsesCodecError(error.code, error.message, param);
+    throw error;
+  }
 }
 function record(value, where) {
   if (!value || typeof value !== "object" || Array.isArray(value))
@@ -8679,8 +8690,94 @@ function responsePayload(id, model, output, end, usage, error, createdAt = Math.
   return result;
 }
 
+// src/responses-codec/request-preferences.ts
+function fields(value, allowed, path) {
+  for (const key of Object.keys(value))
+    if (!allowed.includes(key)) {
+      fail("unsupported_request", "Unrecognized request option", `${path}.${key}`);
+    }
+}
+function applyResponsesPreferences(body, result, protocol, capabilities, maxTokens, diagnostics) {
+  const note = (param, action, reason) => diagnostics.push({ param, action, reason });
+  if (body.stream_options !== undefined)
+    atParam("stream_options", () => {
+      const options = record(body.stream_options, "stream_options");
+      fields(options, ["include_usage", "reasoning_summary_delivery"], "stream_options");
+      if (options.include_usage !== undefined) {
+        if (typeof options.include_usage !== "boolean")
+          fail("invalid_payload", "Usage preference must be boolean", "stream_options.include_usage");
+        note("stream_options.include_usage", protocol === "chat_completions" && body.stream === true ? "mapped" : "omitted", protocol === "chat_completions" && body.stream === true ? "stream_usage_required" : "target_usage_events");
+      }
+      if (options.reasoning_summary_delivery !== undefined) {
+        if (options.reasoning_summary_delivery !== "sequential_cutoff")
+          fail("unsupported_request", "Unsupported summary delivery preference", "stream_options.reasoning_summary_delivery");
+        note("stream_options.reasoning_summary_delivery", "omitted", "source_summary_delivery_not_applicable");
+      }
+    });
+  if (body.access_programs !== undefined)
+    atParam("access_programs", () => {
+      const programs = record(body.access_programs, "access_programs");
+      fields(programs, ["cyber"], "access_programs");
+      if (programs.cyber !== undefined && programs.cyber !== "standard") {
+        if (programs.cyber === "daybreak_blue" || programs.cyber === "daybreak_red") {
+          fail("unsupported_access_program", "Selected access program cannot be represented by the target protocol", "access_programs.cyber");
+        }
+        fail("invalid_payload", "Invalid access program", "access_programs.cyber");
+      }
+      note("access_programs", "omitted", "target_uses_own_access_policy");
+    });
+  if (body.reasoning !== undefined)
+    atParam("reasoning", () => {
+      const reasoning = record(body.reasoning, "reasoning");
+      fields(reasoning, ["effort", "summary", "context"], "reasoning");
+      if (reasoning.summary !== undefined) {
+        if (typeof reasoning.summary !== "string" || !["none", "auto", "concise", "detailed"].includes(reasoning.summary))
+          fail("invalid_payload", "Invalid reasoning summary preference", "reasoning.summary");
+        note("reasoning.summary", "omitted", "target_summary_not_guaranteed");
+      }
+      if (reasoning.context !== undefined) {
+        if (reasoning.context !== "all_turns")
+          fail("unsupported_reasoning", "Unsupported reasoning context preference", "reasoning.context");
+        note("reasoning.context", "omitted", "source_reasoning_context_not_applicable");
+      }
+      if (reasoning.effort !== undefined)
+        atParam("reasoning.effort", () => {
+          const effort = string(reasoning.effort, "reasoning effort", true);
+          if (protocol === "chat_completions" && capabilities.reasoningEffort) {
+            result.reasoning_effort = effort;
+            note("reasoning.effort", "mapped", "target_reasoning_effort");
+          } else if (protocol === "anthropic_messages" && capabilities.anthropicThinkingBudget !== undefined && effort !== "none") {
+            const budget = capabilities.anthropicThinkingBudget;
+            if (!Number.isSafeInteger(budget) || budget < 1024 || typeof maxTokens !== "number" || budget >= maxTokens) {
+              fail("unsupported_reasoning", "Anthropic thinking requires an explicit budget below max_output_tokens");
+            }
+            result.thinking = { type: "enabled", budget_tokens: budget };
+            note("reasoning.effort", "mapped", "explicit_target_thinking_budget");
+          } else
+            note("reasoning.effort", "omitted", "target_reasoning_effort_unavailable");
+        });
+    });
+  if (body.text !== undefined)
+    atParam("text", () => {
+      const text = record(body.text, "text");
+      fields(text, ["verbosity", "format"], "text");
+      if (text.verbosity !== undefined) {
+        if (typeof text.verbosity !== "string" || !["low", "medium", "high"].includes(text.verbosity))
+          fail("invalid_payload", "Invalid text verbosity preference", "text.verbosity");
+        note("text.verbosity", "omitted", "target_verbosity_not_available");
+      }
+    });
+}
+
 // src/responses-codec/request.ts
 var contentNormalizer = new OpenAIProtocolConversion({ trimWhitespace: false });
+function definitionKey(value) {
+  if (Array.isArray(value))
+    return `[${value.map(definitionKey).join(",")}]`;
+  if (value && typeof value === "object")
+    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${definitionKey(value[key])}`).join(",")}}`;
+  return JSON.stringify(value);
+}
 function decodeResponsesRequest(raw, protocol, capabilities = {}) {
   const body = record(raw, "Responses request");
   const budget = limits(capabilities.limits);
@@ -8706,11 +8803,15 @@ function decodeResponsesRequest(raw, protocol, capabilities = {}) {
     "n",
     "truncation",
     "include",
-    "store"
+    "store",
+    "prompt_cache_key",
+    "client_metadata",
+    "stream_options",
+    "access_programs"
   ]);
   for (const key of Object.keys(body))
     if (!supported.has(key))
-      fail("unsupported_request", `Unsupported Responses request field ${key}`);
+      fail("unsupported_request", "Unrecognized Responses request field", key);
   if (body.store === true)
     fail("unsupported_request", "Stored Responses require caller-owned persistence");
   for (const key of ["previous_response_id", "conversation", "response_id"]) {
@@ -8723,17 +8824,28 @@ function decodeResponsesRequest(raw, protocol, capabilities = {}) {
     fail("unsupported_request", "Only one response candidate is supported");
   if (body.truncation !== undefined && body.truncation !== "disabled")
     fail("unsupported_request", "Automatic input truncation cannot be represented");
-  if (body.include !== undefined && list(body.include, "include").length)
+  if (body.include !== undefined && list(body.include, "include").some((field) => field !== "reasoning.encrypted_content"))
     fail("unsupported_request", "Requested extra Responses output fields cannot be represented");
+  if (body.prompt_cache_key !== undefined)
+    string(body.prompt_cache_key, "prompt_cache_key");
+  if (body.client_metadata !== undefined)
+    record(body.client_metadata, "client_metadata");
   const model = string(body.model, "model", true);
+  const diagnostics = [];
+  const input = atParam("input", () => typeof body.input === "string" ? [{ role: "user", content: body.input }] : list(body.input, "input"));
+  if (input.length > budget.maxItems)
+    fail("resource_limit", "Too many input items", "input");
+  const canonicalInput = [];
   const toolNames = new Map;
   const byOriginal = new Map;
+  const definitions = new Map;
+  let examinedTools = 0;
   const tools = [];
   const identity = (name, namespace) => JSON.stringify([namespace ?? null, name]);
   const register = (name, namespace, custom) => {
     const key = identity(name, namespace);
     if (byOriginal.has(key))
-      fail("tool_name_collision", `Duplicate tool ${namespace ? namespace + "." : ""}${name}`);
+      fail("tool_name_collision", "Duplicate tool identity");
     if (toolNames.size >= budget.maxItems)
       fail("resource_limit", "Too many tools");
     const wire = `bungee_tool_${toolNames.size}`;
@@ -8741,18 +8853,29 @@ function decodeResponsesRequest(raw, protocol, capabilities = {}) {
     byOriginal.set(key, wire);
     return wire;
   };
-  const expandTool = (rawTool, namespace) => {
+  const expandTool = (rawTool, namespace, path = "tools") => {
+    if (++examinedTools > budget.maxItems)
+      fail("resource_limit", "Too many tool declarations");
     const tool = record(rawTool, "tool");
+    if (namespace === undefined && capabilities.omitOptionalWebSearch && ["web_search", "web_search_preview"].includes(String(tool.type)) && (body.tool_choice === undefined || body.tool_choice === "auto" || body.tool_choice === "none"))
+      return;
+    const allowed = tool.type === "namespace" ? ["type", "name", "description", "tools"] : tool.type === "custom" ? ["type", "name", "description", "format"] : ["type", "name", "description", "parameters", "strict"];
+    for (const key of Object.keys(tool))
+      if (!allowed.includes(key))
+        fail("unsupported_tool", "Unsupported tool definition field", `${path}.${key}`);
     if (tool.type === "namespace") {
       if (namespace !== undefined)
         fail("unsupported_tool", "Nested tool namespaces are not supported");
       const name = string(tool.name, "namespace name", true);
-      for (const child of list(tool.tools, "namespace tools"))
-        expandTool(child, name);
+      for (const [index, child] of list(tool.tools, "namespace tools").entries()) {
+        const childPath = `${path}.tools[${index}]`;
+        atParam(childPath, () => expandTool(child, name, childPath));
+      }
       return;
     }
     if (tool.type !== "function" && tool.type !== "custom")
-      fail("unsupported_tool", `Hosted tool ${String(tool.type)} cannot be executed by Codex through this protocol`);
+      fail("unsupported_tool", "This tool type cannot be executed by Codex through the target protocol");
+    serialized(tool, budget.maxArgumentBytes, "tool definition");
     const name = string(tool.name, "tool name", true);
     const custom = tool.type === "custom";
     if (tool.strict !== undefined && typeof tool.strict !== "boolean")
@@ -8764,7 +8887,15 @@ function decodeResponsesRequest(raw, protocol, capabilities = {}) {
       if (format.type !== "text" && format.type !== "grammar")
         fail("unsupported_tool", "Unknown custom tool format");
     }
+    const key = identity(name, namespace);
+    const signature = definitionKey(tool);
+    if (definitions.has(key)) {
+      if (definitions.get(key) !== signature)
+        fail("tool_name_collision", "Conflicting definitions for the same tool identity");
+      return;
+    }
     const wire = register(name, namespace, custom);
+    definitions.set(key, signature);
     const parameters = custom ? { type: "object", properties: { input: { type: "string" } }, required: ["input"], additionalProperties: false } : record(tool.parameters ?? { type: "object", properties: {} }, "tool parameters");
     const description = tool.description === undefined ? undefined : string(tool.description, "tool description");
     const customHint = custom ? `Pass the complete original custom tool input verbatim in the input string.${tool.format ? ` Original input format: ${JSON.stringify(tool.format)}` : ""}` : undefined;
@@ -8777,8 +8908,24 @@ function decodeResponsesRequest(raw, protocol, capabilities = {}) {
     }
   };
   if (body.tools !== undefined)
-    for (const tool of list(body.tools, "tools"))
-      expandTool(tool);
+    atParam("tools", () => {
+      for (const [index, tool] of list(body.tools, "tools").entries())
+        atParam(`tools[${index}]`, () => expandTool(tool, undefined, `tools[${index}]`));
+    });
+  for (const [index, rawItem] of input.entries())
+    atParam(`input[${index}]`, () => {
+      const item = record(rawItem, "input item");
+      if (item.type !== "additional_tools") {
+        canonicalInput.push(item);
+        return;
+      }
+      if (item.content !== undefined)
+        fail("invalid_payload", "A tool declaration carrier cannot also contain message content", `input[${index}].content`);
+      for (const [toolIndex, tool] of list(item.tools, "additional tools").entries()) {
+        const toolPath = `input[${index}].tools[${toolIndex}]`;
+        atParam(toolPath, () => expandTool(tool, undefined, toolPath));
+      }
+    });
   const resolve = (item, custom) => {
     const name = string(item.name, "call name", true);
     const namespace = item.namespace === undefined ? undefined : string(item.namespace, "call namespace", true);
@@ -8786,7 +8933,7 @@ function decodeResponsesRequest(raw, protocol, capabilities = {}) {
     if (wire === undefined)
       wire = register(name, namespace, custom);
     if (toolNames.get(wire).custom !== custom)
-      fail("tool_name_collision", `Tool kind changed for ${name}`);
+      fail("tool_name_collision", "Historical tool kind conflicts with its current declaration");
     return wire;
   };
   const normalizeContent = (rawContent, role) => {
@@ -8797,6 +8944,8 @@ function decodeResponsesRequest(raw, protocol, capabilities = {}) {
       const part = record(rawPart, "content part");
       if (part.type === "input_text" || part.type === "output_text" || part.type === "text")
         string(part.text, "content text");
+      else if (part.type === "refusal" && role === "assistant")
+        string(part.refusal, "refusal");
       else if (part.type === "input_image" && role === "user") {
         if (protocol !== "chat_completions")
           fail("unsupported_content", "Anthropic image conversion requires provider-specific URL/data support");
@@ -8804,11 +8953,14 @@ function decodeResponsesRequest(raw, protocol, capabilities = {}) {
         if (part.detail !== undefined && !["auto", "low", "high"].includes(String(part.detail)))
           fail("unsupported_content", "Unknown image detail");
       } else
-        fail("unsupported_content", `Unsupported message content: ${String(part.type)}`);
+        fail("unsupported_content", "Unsupported message content type");
       if (part.annotations !== undefined && list(part.annotations, "annotations").length)
         fail("unsupported_content", "Output annotations cannot be represented in input history");
     }
-    const normalized = contentNormalizer.normalizeResponsesMessageContent(parts);
+    const normalized = contentNormalizer.normalizeResponsesMessageContent(parts.map((raw) => {
+      const part = raw;
+      return part.type === "refusal" ? { type: "output_text", text: part.refusal } : part;
+    }));
     for (let i = 0;i < parts.length; i++) {
       const part = parts[i];
       if (part.type === "input_image" && part.detail !== undefined)
@@ -8817,6 +8969,8 @@ function decodeResponsesRequest(raw, protocol, capabilities = {}) {
     return normalized;
   };
   const chat = [];
+  const messageParams = new WeakMap;
+  let messageParam = "instructions";
   const callIds = new Set;
   const answered = new Set;
   let pendingReasoning = "";
@@ -8824,73 +8978,77 @@ function decodeResponsesRequest(raw, protocol, capabilities = {}) {
     if (chat.length >= budget.maxItems)
       fail("resource_limit", "Too many input messages");
     chat.push(message);
+    messageParams.set(message, messageParam);
   };
   if (body.instructions !== undefined)
     addMessage({ role: "system", content: string(body.instructions, "instructions") });
-  const input = typeof body.input === "string" ? [{ role: "user", content: body.input }] : list(body.input, "input");
-  if (input.length > budget.maxItems)
-    fail("resource_limit", "Too many input items");
-  for (const rawItem of input) {
-    const item = record(rawItem, "input item");
-    if (item.encrypted_content !== undefined || item.type === "compaction")
-      fail("unsupported_content", "Encrypted reasoning and compaction cannot be restored");
-    if (item.type === "item_reference")
-      fail("unresolved_reference", "Input item references must be resolved before conversion");
-    if (item.type === "reasoning") {
-      if (protocol !== "chat_completions" || !capabilities.reasoningEffort)
-        fail("unsupported_reasoning", "Reasoning history requires an explicit compatible reasoning capability");
-      const summary = list(item.summary, "reasoning summary");
-      pendingReasoning += summary.map((part) => {
-        const p = record(part, "reasoning summary");
-        if (p.type !== "summary_text")
-          fail("unsupported_reasoning", "Unknown reasoning summary");
-        return string(p.text, "summary text");
-      }).join("");
-      continue;
-    }
-    if (item.type === "function_call" || item.type === "custom_tool_call") {
-      const custom = item.type === "custom_tool_call";
-      const id = string(item.call_id, "call_id", true);
-      if (callIds.has(id))
-        fail("invalid_tool_history", `Duplicate call_id ${id}`);
-      callIds.add(id);
-      const args = custom ? JSON.stringify({ input: string(item.input, "custom input") }) : string(item.arguments, "arguments");
-      bounded(args, budget.maxArgumentBytes, "arguments");
-      argumentObject(args);
-      const call = { id, type: "function", function: { name: resolve(item, custom), arguments: args } };
-      const previous = chat.at(-1);
-      if (previous?.role === "assistant") {
-        previous.tool_calls = [...previous.tool_calls ?? [], call];
-        if (pendingReasoning)
-          previous.reasoning_content = pendingReasoning;
-      } else
-        addMessage({ role: "assistant", content: null, tool_calls: [call], ...pendingReasoning ? { reasoning_content: pendingReasoning } : {} });
-      pendingReasoning = "";
-      continue;
-    }
-    if (item.type === "function_call_output" || item.type === "custom_tool_call_output") {
-      const id = string(item.call_id, "call_id", true);
-      if (!callIds.has(id) || answered.has(id))
-        fail("invalid_tool_history", `Unmatched or duplicate output ${id}`);
-      answered.add(id);
-      const output = typeof item.output === "string" ? item.output : normalizeContent(item.output, "tool");
-      addMessage({ role: "tool", tool_call_id: id, content: output, ...item.is_error === true ? { is_error: true } : {} });
-      continue;
-    }
-    if (item.type !== undefined && item.type !== "message")
-      fail("unsupported_content", `Unsupported input item ${String(item.type)}`);
-    const role = string(item.role, "message role", true);
-    if (!["user", "assistant", "system", "developer"].includes(role))
-      fail("unsupported_content", `Unknown message role ${role}`);
-    const message = { role, content: normalizeContent(item.content, role) };
-    if (pendingReasoning) {
-      if (role !== "assistant")
-        fail("unsupported_reasoning", "Reasoning must precede an assistant item");
-      message.reasoning_content = pendingReasoning;
-      pendingReasoning = "";
-    }
-    addMessage(message);
-  }
+  for (const [inputIndex, rawItem] of input.entries())
+    atParam(`input[${inputIndex}]`, () => {
+      messageParam = `input[${inputIndex}]`;
+      const item = record(rawItem, "input item");
+      if (item.type === "additional_tools")
+        return;
+      if (item.encrypted_content != null || item.type === "compaction")
+        fail("unsupported_content", "Encrypted reasoning and compaction cannot be restored");
+      if (item.type === "item_reference")
+        fail("unresolved_reference", "Input item references must be resolved before conversion");
+      if (item.type === "reasoning") {
+        if (protocol !== "chat_completions" || !(capabilities.reasoningHistory || capabilities.reasoningEffort))
+          fail("unsupported_reasoning", "Reasoning history requires an explicit compatible reasoning capability");
+        if (item.content != null)
+          fail("unsupported_reasoning", "Reasoning content requires an explicit history mapping", `${messageParam}.content`);
+        const summary = list(item.summary, "reasoning summary");
+        pendingReasoning += summary.map((part) => {
+          const p = record(part, "reasoning summary");
+          if (p.type !== "summary_text")
+            fail("unsupported_reasoning", "Unknown reasoning summary");
+          return string(p.text, "summary text");
+        }).join("");
+        return;
+      }
+      if (item.type === "function_call" || item.type === "custom_tool_call") {
+        const custom = item.type === "custom_tool_call";
+        const id = string(item.call_id, "call_id", true);
+        if (callIds.has(id))
+          fail("invalid_tool_history", "Duplicate tool call identifier");
+        callIds.add(id);
+        const args = custom ? JSON.stringify({ input: string(item.input, "custom input") }) : string(item.arguments, "arguments");
+        bounded(args, budget.maxArgumentBytes, "arguments");
+        argumentObject(args);
+        const call = { id, type: "function", function: { name: resolve(item, custom), arguments: args } };
+        const previous = chat.at(-1);
+        if (previous?.role === "assistant") {
+          previous.tool_calls = [...previous.tool_calls ?? [], call];
+          if (pendingReasoning)
+            previous.reasoning_content = pendingReasoning;
+        } else
+          addMessage({ role: "assistant", content: null, tool_calls: [call], ...pendingReasoning ? { reasoning_content: pendingReasoning } : {} });
+        pendingReasoning = "";
+        return;
+      }
+      if (item.type === "function_call_output" || item.type === "custom_tool_call_output") {
+        const id = string(item.call_id, "call_id", true);
+        if (!callIds.has(id) || answered.has(id))
+          fail("invalid_tool_history", "Unmatched or duplicate tool result");
+        answered.add(id);
+        const output = typeof item.output === "string" ? item.output : normalizeContent(item.output, "tool");
+        addMessage({ role: "tool", tool_call_id: id, content: output, ...item.is_error === true ? { is_error: true } : {} });
+        return;
+      }
+      if (item.type !== undefined && item.type !== "message")
+        fail("unsupported_content", "Unsupported input item type");
+      const role = string(item.role, "message role", true);
+      if (!["user", "assistant", "system", "developer"].includes(role))
+        fail("unsupported_content", "Unknown message role");
+      const message = { role, content: normalizeContent(item.content, role) };
+      if (pendingReasoning) {
+        if (role !== "assistant")
+          fail("unsupported_reasoning", "Reasoning must precede an assistant item");
+        message.reasoning_content = pendingReasoning;
+        pendingReasoning = "";
+      }
+      addMessage(message);
+    });
   if (pendingReasoning)
     fail("unsupported_reasoning", "Orphan reasoning history cannot be represented");
   const result = { model, messages: chat };
@@ -8923,41 +9081,35 @@ function decodeResponsesRequest(raw, protocol, capabilities = {}) {
       result.tool_choice = protocol === "chat_completions" ? { type: "function", function: { name: wire } } : { type: "tool", name: wire };
     }
   }
-  if (body.reasoning !== undefined) {
-    const reasoning = record(body.reasoning, "reasoning");
-    if (reasoning.summary !== undefined && reasoning.summary !== "none")
-      fail("unsupported_reasoning", "Requested reasoning summaries are not guaranteed by this upstream protocol");
-    if (reasoning.effort !== undefined && reasoning.effort !== "none") {
-      const effort = string(reasoning.effort, "reasoning effort", true);
-      if (protocol === "chat_completions") {
-        if (!capabilities.reasoningEffort)
-          fail("unsupported_reasoning", "Upstream does not advertise reasoning effort");
-        result.reasoning_effort = effort;
-      } else {
-        const thinking = capabilities.anthropicThinkingBudget;
-        if (!Number.isSafeInteger(thinking) || thinking < 1024 || typeof maxTokens !== "number" || thinking >= maxTokens)
-          fail("unsupported_reasoning", "Anthropic thinking requires an explicit budget below max_output_tokens");
-        result.thinking = { type: "enabled", budget_tokens: thinking };
-      }
-    }
-  }
-  if (body.text !== undefined) {
-    const text = record(body.text, "text");
-    if (text.verbosity !== undefined)
-      fail("unsupported_request", "Text verbosity cannot be represented");
-    if (text.format !== undefined) {
-      const format = record(text.format, "text format");
-      if (protocol !== "chat_completions" && format.type !== "text")
-        fail("unsupported_request", "Anthropic structured output requires a separate provider capability");
-      if (format.type === "json_schema")
-        result.response_format = { type: "json_schema", json_schema: { name: format.name, schema: format.schema, ...format.strict !== undefined ? { strict: format.strict } : {}, ...format.description !== undefined ? { description: format.description } : {} } };
-      else if (format.type === "json_object" || format.type === "text") {
-        if (protocol === "chat_completions")
-          result.response_format = format;
-      } else
-        fail("unsupported_request", "Unknown text format");
-    }
-  }
+  applyResponsesPreferences(body, result, protocol, capabilities, maxTokens, diagnostics);
+  if (body.text !== undefined)
+    atParam("text.format", () => {
+      const text = record(body.text, "text");
+      if (text.format !== undefined) {
+        const format = record(text.format, "text format");
+        const allowed = format.type === "json_schema" ? ["type", "name", "schema", "strict", "description"] : ["type"];
+        for (const key of Object.keys(format))
+          if (!allowed.includes(key))
+            fail("unsupported_request", "Unsupported output format field", `text.format.${key}`);
+        if (format.type === "json_schema") {
+          atParam("text.format.name", () => string(format.name, "output schema name", true));
+          atParam("text.format.schema", () => record(format.schema, "output schema"));
+          if (format.strict !== undefined && typeof format.strict !== "boolean")
+            fail("invalid_payload", "Output schema strict must be boolean", "text.format.strict");
+          if (format.description !== undefined)
+            atParam("text.format.description", () => string(format.description, "output schema description"));
+        }
+        if (protocol !== "chat_completions" && format.type !== "text")
+          fail("unsupported_request", "Anthropic structured output requires a separate provider capability");
+        if (format.type === "json_schema")
+          result.response_format = { type: "json_schema", json_schema: { name: format.name, schema: format.schema, ...format.strict !== undefined ? { strict: format.strict } : {}, ...format.description !== undefined ? { description: format.description } : {} } };
+        else if (format.type === "json_object" || format.type === "text") {
+          if (protocol === "chat_completions")
+            result.response_format = format;
+        } else
+          fail("unsupported_request", "Unknown text format");
+      }
+    });
   if (protocol === "anthropic_messages") {
     const system = [];
     const messages = [];
@@ -8971,7 +9123,7 @@ function decodeResponsesRequest(raw, protocol, capabilities = {}) {
     for (const msg of chat) {
       if (msg.role === "system" || msg.role === "developer") {
         if (messages.length)
-          fail("unsupported_content", "Mid-conversation system instructions cannot be relocated safely");
+          fail("unsupported_content", "Mid-conversation system instructions cannot be relocated safely", `${messageParams.get(msg)}.role`);
         system.push(typeof msg.content === "string" ? msg.content : msg.content.map((p) => string(p.text, "system text")).join(""));
         continue;
       }
@@ -8997,7 +9149,7 @@ function decodeResponsesRequest(raw, protocol, capabilities = {}) {
       delete result.parallel_tool_calls;
     }
   }
-  return { body: result, toolNames };
+  return { body: result, toolNames, canonicalInput, diagnostics };
 }
 // src/responses-codec/events.ts
 class ResponsesEventEncoder {

package/dist/plugin-api.js

@@ -8515,14 +8515,25 @@ var DEFAULT_RESPONSES_CODEC_LIMITS = Object.freeze({
 
 class ResponsesCodecError extends Error {
   code;
-  constructor(code, message) {
+  param;
+  constructor(code, message, param) {
     super(message);
     this.code = code;
+    this.param = param;
     this.name = "ResponsesCodecError";
   }
 }
-function fail(code, message) {
-  throw new ResponsesCodecError(code, message);
+function fail(code, message, param) {
+  throw new ResponsesCodecError(code, message, param);
+}
+function atParam(param, run) {
+  try {
+    return run();
+  } catch (error) {
+    if (error instanceof ResponsesCodecError && error.param === undefined)
+      throw new ResponsesCodecError(error.code, error.message, param);
+    throw error;
+  }
 }
 function record(value, where) {
   if (!value || typeof value !== "object" || Array.isArray(value))
@@ -8685,8 +8696,94 @@ function responsePayload(id, model, output, end, usage, error, createdAt = Math.
   return result;
 }
 
+// src/responses-codec/request-preferences.ts
+function fields(value, allowed, path) {
+  for (const key of Object.keys(value))
+    if (!allowed.includes(key)) {
+      fail("unsupported_request", "Unrecognized request option", `${path}.${key}`);
+    }
+}
+function applyResponsesPreferences(body, result, protocol, capabilities, maxTokens, diagnostics) {
+  const note = (param, action, reason) => diagnostics.push({ param, action, reason });
+  if (body.stream_options !== undefined)
+    atParam("stream_options", () => {
+      const options = record(body.stream_options, "stream_options");
+      fields(options, ["include_usage", "reasoning_summary_delivery"], "stream_options");
+      if (options.include_usage !== undefined) {
+        if (typeof options.include_usage !== "boolean")
+          fail("invalid_payload", "Usage preference must be boolean", "stream_options.include_usage");
+        note("stream_options.include_usage", protocol === "chat_completions" && body.stream === true ? "mapped" : "omitted", protocol === "chat_completions" && body.stream === true ? "stream_usage_required" : "target_usage_events");
+      }
+      if (options.reasoning_summary_delivery !== undefined) {
+        if (options.reasoning_summary_delivery !== "sequential_cutoff")
+          fail("unsupported_request", "Unsupported summary delivery preference", "stream_options.reasoning_summary_delivery");
+        note("stream_options.reasoning_summary_delivery", "omitted", "source_summary_delivery_not_applicable");
+      }
+    });
+  if (body.access_programs !== undefined)
+    atParam("access_programs", () => {
+      const programs = record(body.access_programs, "access_programs");
+      fields(programs, ["cyber"], "access_programs");
+      if (programs.cyber !== undefined && programs.cyber !== "standard") {
+        if (programs.cyber === "daybreak_blue" || programs.cyber === "daybreak_red") {
+          fail("unsupported_access_program", "Selected access program cannot be represented by the target protocol", "access_programs.cyber");
+        }
+        fail("invalid_payload", "Invalid access program", "access_programs.cyber");
+      }
+      note("access_programs", "omitted", "target_uses_own_access_policy");
+    });
+  if (body.reasoning !== undefined)
+    atParam("reasoning", () => {
+      const reasoning = record(body.reasoning, "reasoning");
+      fields(reasoning, ["effort", "summary", "context"], "reasoning");
+      if (reasoning.summary !== undefined) {
+        if (typeof reasoning.summary !== "string" || !["none", "auto", "concise", "detailed"].includes(reasoning.summary))
+          fail("invalid_payload", "Invalid reasoning summary preference", "reasoning.summary");
+        note("reasoning.summary", "omitted", "target_summary_not_guaranteed");
+      }
+      if (reasoning.context !== undefined) {
+        if (reasoning.context !== "all_turns")
+          fail("unsupported_reasoning", "Unsupported reasoning context preference", "reasoning.context");
+        note("reasoning.context", "omitted", "source_reasoning_context_not_applicable");
+      }
+      if (reasoning.effort !== undefined)
+        atParam("reasoning.effort", () => {
+          const effort = string(reasoning.effort, "reasoning effort", true);
+          if (protocol === "chat_completions" && capabilities.reasoningEffort) {
+            result.reasoning_effort = effort;
+            note("reasoning.effort", "mapped", "target_reasoning_effort");
+          } else if (protocol === "anthropic_messages" && capabilities.anthropicThinkingBudget !== undefined && effort !== "none") {
+            const budget = capabilities.anthropicThinkingBudget;
+            if (!Number.isSafeInteger(budget) || budget < 1024 || typeof maxTokens !== "number" || budget >= maxTokens) {
+              fail("unsupported_reasoning", "Anthropic thinking requires an explicit budget below max_output_tokens");
+            }
+            result.thinking = { type: "enabled", budget_tokens: budget };
+            note("reasoning.effort", "mapped", "explicit_target_thinking_budget");
+          } else
+            note("reasoning.effort", "omitted", "target_reasoning_effort_unavailable");
+        });
+    });
+  if (body.text !== undefined)
+    atParam("text", () => {
+      const text = record(body.text, "text");
+      fields(text, ["verbosity", "format"], "text");
+      if (text.verbosity !== undefined) {
+        if (typeof text.verbosity !== "string" || !["low", "medium", "high"].includes(text.verbosity))
+          fail("invalid_payload", "Invalid text verbosity preference", "text.verbosity");
+        note("text.verbosity", "omitted", "target_verbosity_not_available");
+      }
+    });
+}
+
 // src/responses-codec/request.ts
 var contentNormalizer = new OpenAIProtocolConversion({ trimWhitespace: false });
+function definitionKey(value) {
+  if (Array.isArray(value))
+    return `[${value.map(definitionKey).join(",")}]`;
+  if (value && typeof value === "object")
+    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${definitionKey(value[key])}`).join(",")}}`;
+  return JSON.stringify(value);
+}
 function decodeResponsesRequest(raw, protocol, capabilities = {}) {
   const body = record(raw, "Responses request");
   const budget = limits(capabilities.limits);
@@ -8712,11 +8809,15 @@ function decodeResponsesRequest(raw, protocol, capabilities = {}) {
     "n",
     "truncation",
     "include",
-    "store"
+    "store",
+    "prompt_cache_key",
+    "client_metadata",
+    "stream_options",
+    "access_programs"
   ]);
   for (const key of Object.keys(body))
     if (!supported.has(key))
-      fail("unsupported_request", `Unsupported Responses request field ${key}`);
+      fail("unsupported_request", "Unrecognized Responses request field", key);
   if (body.store === true)
     fail("unsupported_request", "Stored Responses require caller-owned persistence");
   for (const key of ["previous_response_id", "conversation", "response_id"]) {
@@ -8729,17 +8830,28 @@ function decodeResponsesRequest(raw, protocol, capabilities = {}) {
     fail("unsupported_request", "Only one response candidate is supported");
   if (body.truncation !== undefined && body.truncation !== "disabled")
     fail("unsupported_request", "Automatic input truncation cannot be represented");
-  if (body.include !== undefined && list(body.include, "include").length)
+  if (body.include !== undefined && list(body.include, "include").some((field) => field !== "reasoning.encrypted_content"))
     fail("unsupported_request", "Requested extra Responses output fields cannot be represented");
+  if (body.prompt_cache_key !== undefined)
+    string(body.prompt_cache_key, "prompt_cache_key");
+  if (body.client_metadata !== undefined)
+    record(body.client_metadata, "client_metadata");
   const model = string(body.model, "model", true);
+  const diagnostics = [];
+  const input = atParam("input", () => typeof body.input === "string" ? [{ role: "user", content: body.input }] : list(body.input, "input"));
+  if (input.length > budget.maxItems)
+    fail("resource_limit", "Too many input items", "input");
+  const canonicalInput = [];
   const toolNames = new Map;
   const byOriginal = new Map;
+  const definitions = new Map;
+  let examinedTools = 0;
   const tools = [];
   const identity = (name, namespace) => JSON.stringify([namespace ?? null, name]);
   const register = (name, namespace, custom) => {
     const key = identity(name, namespace);
     if (byOriginal.has(key))
-      fail("tool_name_collision", `Duplicate tool ${namespace ? namespace + "." : ""}${name}`);
+      fail("tool_name_collision", "Duplicate tool identity");
     if (toolNames.size >= budget.maxItems)
       fail("resource_limit", "Too many tools");
     const wire = `bungee_tool_${toolNames.size}`;
@@ -8747,18 +8859,29 @@ function decodeResponsesRequest(raw, protocol, capabilities = {}) {
     byOriginal.set(key, wire);
     return wire;
   };
-  const expandTool = (rawTool, namespace) => {
+  const expandTool = (rawTool, namespace, path = "tools") => {
+    if (++examinedTools > budget.maxItems)
+      fail("resource_limit", "Too many tool declarations");
     const tool = record(rawTool, "tool");
+    if (namespace === undefined && capabilities.omitOptionalWebSearch && ["web_search", "web_search_preview"].includes(String(tool.type)) && (body.tool_choice === undefined || body.tool_choice === "auto" || body.tool_choice === "none"))
+      return;
+    const allowed = tool.type === "namespace" ? ["type", "name", "description", "tools"] : tool.type === "custom" ? ["type", "name", "description", "format"] : ["type", "name", "description", "parameters", "strict"];
+    for (const key of Object.keys(tool))
+      if (!allowed.includes(key))
+        fail("unsupported_tool", "Unsupported tool definition field", `${path}.${key}`);
     if (tool.type === "namespace") {
       if (namespace !== undefined)
         fail("unsupported_tool", "Nested tool namespaces are not supported");
       const name = string(tool.name, "namespace name", true);
-      for (const child of list(tool.tools, "namespace tools"))
-        expandTool(child, name);
+      for (const [index, child] of list(tool.tools, "namespace tools").entries()) {
+        const childPath = `${path}.tools[${index}]`;
+        atParam(childPath, () => expandTool(child, name, childPath));
+      }
       return;
     }
     if (tool.type !== "function" && tool.type !== "custom")
-      fail("unsupported_tool", `Hosted tool ${String(tool.type)} cannot be executed by Codex through this protocol`);
+      fail("unsupported_tool", "This tool type cannot be executed by Codex through the target protocol");
+    serialized(tool, budget.maxArgumentBytes, "tool definition");
     const name = string(tool.name, "tool name", true);
     const custom = tool.type === "custom";
     if (tool.strict !== undefined && typeof tool.strict !== "boolean")
@@ -8770,7 +8893,15 @@ function decodeResponsesRequest(raw, protocol, capabilities = {}) {
       if (format.type !== "text" && format.type !== "grammar")
         fail("unsupported_tool", "Unknown custom tool format");
     }
+    const key = identity(name, namespace);
+    const signature = definitionKey(tool);
+    if (definitions.has(key)) {
+      if (definitions.get(key) !== signature)
+        fail("tool_name_collision", "Conflicting definitions for the same tool identity");
+      return;
+    }
     const wire = register(name, namespace, custom);
+    definitions.set(key, signature);
     const parameters = custom ? { type: "object", properties: { input: { type: "string" } }, required: ["input"], additionalProperties: false } : record(tool.parameters ?? { type: "object", properties: {} }, "tool parameters");
     const description = tool.description === undefined ? undefined : string(tool.description, "tool description");
     const customHint = custom ? `Pass the complete original custom tool input verbatim in the input string.${tool.format ? ` Original input format: ${JSON.stringify(tool.format)}` : ""}` : undefined;
@@ -8783,8 +8914,24 @@ function decodeResponsesRequest(raw, protocol, capabilities = {}) {
     }
   };
   if (body.tools !== undefined)
-    for (const tool of list(body.tools, "tools"))
-      expandTool(tool);
+    atParam("tools", () => {
+      for (const [index, tool] of list(body.tools, "tools").entries())
+        atParam(`tools[${index}]`, () => expandTool(tool, undefined, `tools[${index}]`));
+    });
+  for (const [index, rawItem] of input.entries())
+    atParam(`input[${index}]`, () => {
+      const item = record(rawItem, "input item");
+      if (item.type !== "additional_tools") {
+        canonicalInput.push(item);
+        return;
+      }
+      if (item.content !== undefined)
+        fail("invalid_payload", "A tool declaration carrier cannot also contain message content", `input[${index}].content`);
+      for (const [toolIndex, tool] of list(item.tools, "additional tools").entries()) {
+        const toolPath = `input[${index}].tools[${toolIndex}]`;
+        atParam(toolPath, () => expandTool(tool, undefined, toolPath));
+      }
+    });
   const resolve = (item, custom) => {
     const name = string(item.name, "call name", true);
     const namespace = item.namespace === undefined ? undefined : string(item.namespace, "call namespace", true);
@@ -8792,7 +8939,7 @@ function decodeResponsesRequest(raw, protocol, capabilities = {}) {
     if (wire === undefined)
       wire = register(name, namespace, custom);
     if (toolNames.get(wire).custom !== custom)
-      fail("tool_name_collision", `Tool kind changed for ${name}`);
+      fail("tool_name_collision", "Historical tool kind conflicts with its current declaration");
     return wire;
   };
   const normalizeContent = (rawContent, role) => {
@@ -8803,6 +8950,8 @@ function decodeResponsesRequest(raw, protocol, capabilities = {}) {
       const part = record(rawPart, "content part");
       if (part.type === "input_text" || part.type === "output_text" || part.type === "text")
         string(part.text, "content text");
+      else if (part.type === "refusal" && role === "assistant")
+        string(part.refusal, "refusal");
       else if (part.type === "input_image" && role === "user") {
         if (protocol !== "chat_completions")
           fail("unsupported_content", "Anthropic image conversion requires provider-specific URL/data support");
@@ -8810,11 +8959,14 @@ function decodeResponsesRequest(raw, protocol, capabilities = {}) {
         if (part.detail !== undefined && !["auto", "low", "high"].includes(String(part.detail)))
           fail("unsupported_content", "Unknown image detail");
       } else
-        fail("unsupported_content", `Unsupported message content: ${String(part.type)}`);
+        fail("unsupported_content", "Unsupported message content type");
       if (part.annotations !== undefined && list(part.annotations, "annotations").length)
         fail("unsupported_content", "Output annotations cannot be represented in input history");
     }
-    const normalized = contentNormalizer.normalizeResponsesMessageContent(parts);
+    const normalized = contentNormalizer.normalizeResponsesMessageContent(parts.map((raw) => {
+      const part = raw;
+      return part.type === "refusal" ? { type: "output_text", text: part.refusal } : part;
+    }));
     for (let i = 0;i < parts.length; i++) {
       const part = parts[i];
       if (part.type === "input_image" && part.detail !== undefined)
@@ -8823,6 +8975,8 @@ function decodeResponsesRequest(raw, protocol, capabilities = {}) {
     return normalized;
   };
   const chat = [];
+  const messageParams = new WeakMap;
+  let messageParam = "instructions";
   const callIds = new Set;
   const answered = new Set;
   let pendingReasoning = "";
@@ -8830,73 +8984,77 @@ function decodeResponsesRequest(raw, protocol, capabilities = {}) {
     if (chat.length >= budget.maxItems)
       fail("resource_limit", "Too many input messages");
     chat.push(message);
+    messageParams.set(message, messageParam);
   };
   if (body.instructions !== undefined)
     addMessage({ role: "system", content: string(body.instructions, "instructions") });
-  const input = typeof body.input === "string" ? [{ role: "user", content: body.input }] : list(body.input, "input");
-  if (input.length > budget.maxItems)
-    fail("resource_limit", "Too many input items");
-  for (const rawItem of input) {
-    const item = record(rawItem, "input item");
-    if (item.encrypted_content !== undefined || item.type === "compaction")
-      fail("unsupported_content", "Encrypted reasoning and compaction cannot be restored");
-    if (item.type === "item_reference")
-      fail("unresolved_reference", "Input item references must be resolved before conversion");
-    if (item.type === "reasoning") {
-      if (protocol !== "chat_completions" || !capabilities.reasoningEffort)
-        fail("unsupported_reasoning", "Reasoning history requires an explicit compatible reasoning capability");
-      const summary = list(item.summary, "reasoning summary");
-      pendingReasoning += summary.map((part) => {
-        const p = record(part, "reasoning summary");
-        if (p.type !== "summary_text")
-          fail("unsupported_reasoning", "Unknown reasoning summary");
-        return string(p.text, "summary text");
-      }).join("");
-      continue;
-    }
-    if (item.type === "function_call" || item.type === "custom_tool_call") {
-      const custom = item.type === "custom_tool_call";
-      const id = string(item.call_id, "call_id", true);
-      if (callIds.has(id))
-        fail("invalid_tool_history", `Duplicate call_id ${id}`);
-      callIds.add(id);
-      const args = custom ? JSON.stringify({ input: string(item.input, "custom input") }) : string(item.arguments, "arguments");
-      bounded(args, budget.maxArgumentBytes, "arguments");
-      argumentObject(args);
-      const call = { id, type: "function", function: { name: resolve(item, custom), arguments: args } };
-      const previous = chat.at(-1);
-      if (previous?.role === "assistant") {
-        previous.tool_calls = [...previous.tool_calls ?? [], call];
-        if (pendingReasoning)
-          previous.reasoning_content = pendingReasoning;
-      } else
-        addMessage({ role: "assistant", content: null, tool_calls: [call], ...pendingReasoning ? { reasoning_content: pendingReasoning } : {} });
-      pendingReasoning = "";
-      continue;
-    }
-    if (item.type === "function_call_output" || item.type === "custom_tool_call_output") {
-      const id = string(item.call_id, "call_id", true);
-      if (!callIds.has(id) || answered.has(id))
-        fail("invalid_tool_history", `Unmatched or duplicate output ${id}`);
-      answered.add(id);
-      const output = typeof item.output === "string" ? item.output : normalizeContent(item.output, "tool");
-      addMessage({ role: "tool", tool_call_id: id, content: output, ...item.is_error === true ? { is_error: true } : {} });
-      continue;
-    }
-    if (item.type !== undefined && item.type !== "message")
-      fail("unsupported_content", `Unsupported input item ${String(item.type)}`);
-    const role = string(item.role, "message role", true);
-    if (!["user", "assistant", "system", "developer"].includes(role))
-      fail("unsupported_content", `Unknown message role ${role}`);
-    const message = { role, content: normalizeContent(item.content, role) };
-    if (pendingReasoning) {
-      if (role !== "assistant")
-        fail("unsupported_reasoning", "Reasoning must precede an assistant item");
-      message.reasoning_content = pendingReasoning;
-      pendingReasoning = "";
-    }
-    addMessage(message);
-  }
+  for (const [inputIndex, rawItem] of input.entries())
+    atParam(`input[${inputIndex}]`, () => {
+      messageParam = `input[${inputIndex}]`;
+      const item = record(rawItem, "input item");
+      if (item.type === "additional_tools")
+        return;
+      if (item.encrypted_content != null || item.type === "compaction")
+        fail("unsupported_content", "Encrypted reasoning and compaction cannot be restored");
+      if (item.type === "item_reference")
+        fail("unresolved_reference", "Input item references must be resolved before conversion");
+      if (item.type === "reasoning") {
+        if (protocol !== "chat_completions" || !(capabilities.reasoningHistory || capabilities.reasoningEffort))
+          fail("unsupported_reasoning", "Reasoning history requires an explicit compatible reasoning capability");
+        if (item.content != null)
+          fail("unsupported_reasoning", "Reasoning content requires an explicit history mapping", `${messageParam}.content`);
+        const summary = list(item.summary, "reasoning summary");
+        pendingReasoning += summary.map((part) => {
+          const p = record(part, "reasoning summary");
+          if (p.type !== "summary_text")
+            fail("unsupported_reasoning", "Unknown reasoning summary");
+          return string(p.text, "summary text");
+        }).join("");
+        return;
+      }
+      if (item.type === "function_call" || item.type === "custom_tool_call") {
+        const custom = item.type === "custom_tool_call";
+        const id = string(item.call_id, "call_id", true);
+        if (callIds.has(id))
+          fail("invalid_tool_history", "Duplicate tool call identifier");
+        callIds.add(id);
+        const args = custom ? JSON.stringify({ input: string(item.input, "custom input") }) : string(item.arguments, "arguments");
+        bounded(args, budget.maxArgumentBytes, "arguments");
+        argumentObject(args);
+        const call = { id, type: "function", function: { name: resolve(item, custom), arguments: args } };
+        const previous = chat.at(-1);
+        if (previous?.role === "assistant") {
+          previous.tool_calls = [...previous.tool_calls ?? [], call];
+          if (pendingReasoning)
+            previous.reasoning_content = pendingReasoning;
+        } else
+          addMessage({ role: "assistant", content: null, tool_calls: [call], ...pendingReasoning ? { reasoning_content: pendingReasoning } : {} });
+        pendingReasoning = "";
+        return;
+      }
+      if (item.type === "function_call_output" || item.type === "custom_tool_call_output") {
+        const id = string(item.call_id, "call_id", true);
+        if (!callIds.has(id) || answered.has(id))
+          fail("invalid_tool_history", "Unmatched or duplicate tool result");
+        answered.add(id);
+        const output = typeof item.output === "string" ? item.output : normalizeContent(item.output, "tool");
+        addMessage({ role: "tool", tool_call_id: id, content: output, ...item.is_error === true ? { is_error: true } : {} });
+        return;
+      }
+      if (item.type !== undefined && item.type !== "message")
+        fail("unsupported_content", "Unsupported input item type");
+      const role = string(item.role, "message role", true);
+      if (!["user", "assistant", "system", "developer"].includes(role))
+        fail("unsupported_content", "Unknown message role");
+      const message = { role, content: normalizeContent(item.content, role) };
+      if (pendingReasoning) {
+        if (role !== "assistant")
+          fail("unsupported_reasoning", "Reasoning must precede an assistant item");
+        message.reasoning_content = pendingReasoning;
+        pendingReasoning = "";
+      }
+      addMessage(message);
+    });
   if (pendingReasoning)
     fail("unsupported_reasoning", "Orphan reasoning history cannot be represented");
   const result = { model, messages: chat };
@@ -8929,41 +9087,35 @@ function decodeResponsesRequest(raw, protocol, capabilities = {}) {
       result.tool_choice = protocol === "chat_completions" ? { type: "function", function: { name: wire } } : { type: "tool", name: wire };
     }
   }
-  if (body.reasoning !== undefined) {
-    const reasoning = record(body.reasoning, "reasoning");
-    if (reasoning.summary !== undefined && reasoning.summary !== "none")
-      fail("unsupported_reasoning", "Requested reasoning summaries are not guaranteed by this upstream protocol");
-    if (reasoning.effort !== undefined && reasoning.effort !== "none") {
-      const effort = string(reasoning.effort, "reasoning effort", true);
-      if (protocol === "chat_completions") {
-        if (!capabilities.reasoningEffort)
-          fail("unsupported_reasoning", "Upstream does not advertise reasoning effort");
-        result.reasoning_effort = effort;
-      } else {
-        const thinking = capabilities.anthropicThinkingBudget;
-        if (!Number.isSafeInteger(thinking) || thinking < 1024 || typeof maxTokens !== "number" || thinking >= maxTokens)
-          fail("unsupported_reasoning", "Anthropic thinking requires an explicit budget below max_output_tokens");
-        result.thinking = { type: "enabled", budget_tokens: thinking };
-      }
-    }
-  }
-  if (body.text !== undefined) {
-    const text = record(body.text, "text");
-    if (text.verbosity !== undefined)
-      fail("unsupported_request", "Text verbosity cannot be represented");
-    if (text.format !== undefined) {
-      const format = record(text.format, "text format");
-      if (protocol !== "chat_completions" && format.type !== "text")
-        fail("unsupported_request", "Anthropic structured output requires a separate provider capability");
-      if (format.type === "json_schema")
-        result.response_format = { type: "json_schema", json_schema: { name: format.name, schema: format.schema, ...format.strict !== undefined ? { strict: format.strict } : {}, ...format.description !== undefined ? { description: format.description } : {} } };
-      else if (format.type === "json_object" || format.type === "text") {
-        if (protocol === "chat_completions")
-          result.response_format = format;
-      } else
-        fail("unsupported_request", "Unknown text format");
-    }
-  }
+  applyResponsesPreferences(body, result, protocol, capabilities, maxTokens, diagnostics);
+  if (body.text !== undefined)
+    atParam("text.format", () => {
+      const text = record(body.text, "text");
+      if (text.format !== undefined) {
+        const format = record(text.format, "text format");
+        const allowed = format.type === "json_schema" ? ["type", "name", "schema", "strict", "description"] : ["type"];
+        for (const key of Object.keys(format))
+          if (!allowed.includes(key))
+            fail("unsupported_request", "Unsupported output format field", `text.format.${key}`);
+        if (format.type === "json_schema") {
+          atParam("text.format.name", () => string(format.name, "output schema name", true));
+          atParam("text.format.schema", () => record(format.schema, "output schema"));
+          if (format.strict !== undefined && typeof format.strict !== "boolean")
+            fail("invalid_payload", "Output schema strict must be boolean", "text.format.strict");
+          if (format.description !== undefined)
+            atParam("text.format.description", () => string(format.description, "output schema description"));
+        }
+        if (protocol !== "chat_completions" && format.type !== "text")
+          fail("unsupported_request", "Anthropic structured output requires a separate provider capability");
+        if (format.type === "json_schema")
+          result.response_format = { type: "json_schema", json_schema: { name: format.name, schema: format.schema, ...format.strict !== undefined ? { strict: format.strict } : {}, ...format.description !== undefined ? { description: format.description } : {} } };
+        else if (format.type === "json_object" || format.type === "text") {
+          if (protocol === "chat_completions")
+            result.response_format = format;
+        } else
+          fail("unsupported_request", "Unknown text format");
+      }
+    });
   if (protocol === "anthropic_messages") {
     const system = [];
     const messages = [];
@@ -8977,7 +9129,7 @@ function decodeResponsesRequest(raw, protocol, capabilities = {}) {
     for (const msg of chat) {
       if (msg.role === "system" || msg.role === "developer") {
         if (messages.length)
-          fail("unsupported_content", "Mid-conversation system instructions cannot be relocated safely");
+          fail("unsupported_content", "Mid-conversation system instructions cannot be relocated safely", `${messageParams.get(msg)}.role`);
         system.push(typeof msg.content === "string" ? msg.content : msg.content.map((p) => string(p.text, "system text")).join(""));
         continue;
       }
@@ -9003,7 +9155,7 @@ function decodeResponsesRequest(raw, protocol, capabilities = {}) {
       delete result.parallel_tool_calls;
     }
   }
-  return { body: result, toolNames };
+  return { body: result, toolNames, canonicalInput, diagnostics };
 }
 // src/responses-codec/events.ts
 class ResponsesEventEncoder {

package/dist/responses-codec/common.d.ts

@@ -16,16 +16,27 @@ export interface ResponsesCodecLimits {
 export declare const DEFAULT_RESPONSES_CODEC_LIMITS: Readonly<ResponsesCodecLimits>;
 export interface ResponsesCodecCapabilities {
     reasoningEffort?: boolean;
+    /** Plain reasoning history support is independent of effort parameter mapping. */
+    reasoningHistory?: boolean;
+    /** Codex declares optional hosted search even when the selected model has no search backend. */
+    omitOptionalWebSearch?: boolean;
     /** Explicit provider-approved thinking budget; do not guess budgets from effort labels. */
     anthropicThinkingBudget?: number;
     maxOutputTokens?: number;
     limits?: Partial<ResponsesCodecLimits>;
 }
+export interface ResponsesConversionDiagnostic {
+    param: string;
+    action: 'mapped' | 'omitted';
+    reason: string;
+}
 export declare class ResponsesCodecError extends Error {
     readonly code: string;
-    constructor(code: string, message: string);
+    readonly param?: string | undefined;
+    constructor(code: string, message: string, param?: string | undefined);
 }
-export declare function fail(code: string, message: string): never;
+export declare function fail(code: string, message: string, param?: string): never;
+export declare function atParam<T>(param: string, run: () => T): T;
 export declare function record(value: unknown, where: string): JsonRecord;
 export declare function string(value: unknown, where: string, nonempty?: boolean): string;
 export declare function list(value: unknown, where: string): unknown[];

package/dist/responses-codec/index.d.ts

@@ -1,4 +1,4 @@
 export { decodeResponsesRequest, type DecodedResponsesRequest } from './request';
 export { encodeResponsesResult } from './result';
 export { ResponsesEventEncoder } from './events';
-export { ResponsesCodecError, DEFAULT_RESPONSES_CODEC_LIMITS, type ResponsesProtocol, type ResponsesToolName, type ResponsesToolNames, type ResponsesCodecCapabilities, type ResponsesCodecLimits } from './common';
+export { ResponsesCodecError, DEFAULT_RESPONSES_CODEC_LIMITS, type ResponsesProtocol, type ResponsesToolName, type ResponsesToolNames, type ResponsesCodecCapabilities, type ResponsesCodecLimits, type ResponsesConversionDiagnostic } from './common';

package/dist/responses-codec/request-preferences.d.ts

@@ -0,0 +1,3 @@
+import { type JsonRecord, type ResponsesCodecCapabilities, type ResponsesConversionDiagnostic, type ResponsesProtocol } from './common';
+/** Known preferences may be omitted; output constraints are handled by the request renderer. */
+export declare function applyResponsesPreferences(body: JsonRecord, result: JsonRecord, protocol: ResponsesProtocol, capabilities: ResponsesCodecCapabilities, maxTokens: unknown, diagnostics: ResponsesConversionDiagnostic[]): void;

package/dist/responses-codec/request.d.ts

@@ -1,7 +1,9 @@
-import { type JsonRecord, type ResponsesCodecCapabilities, type ResponsesProtocol, type ResponsesToolNames } from './common';
+import { type JsonRecord, type ResponsesCodecCapabilities, type ResponsesConversionDiagnostic, type ResponsesProtocol, type ResponsesToolNames } from './common';
 export interface DecodedResponsesRequest {
     body: JsonRecord;
     toolNames: ResponsesToolNames;
+    canonicalInput: JsonRecord[];
+    diagnostics: ResponsesConversionDiagnostic[];
 }
 /** Converts only self-contained history. Reference resolution belongs to the caller. */
 export declare function decodeResponsesRequest(raw: unknown, protocol: ResponsesProtocol, capabilities?: ResponsesCodecCapabilities): DecodedResponsesRequest;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jeffusion/bungee-llms",
-  "version": "5.20.0",
+  "version": "5.21.0",
   "description": "Extensible LLM adapters and protocol conversion package for Bungee",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -11,7 +11,7 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@jeffusion/bungee-types": "^5.20.0"
+    "@jeffusion/bungee-types": "^5.21.0"
   },
   "devDependencies": {
     "bun-types": "^1.3.2",