fix(combo): skip Meta Muse targets for mandatory tool_choice

docs-site/src/content/docs/guides/combos.md

@@ -152,6 +152,10 @@ native routing and catalog identity on the next sync.
 
 ### Failover: ordered primary and backups
 
+For Responses requests that require a tool, Meta Responses targets are skipped before sending
+because Meta does not support mandatory `tool_choice`. An eligible later target receives the
+original choice. If every target is incompatible for this reason, the combo reports the constraint.
+
 `failover` selects the first eligible target in configuration order. A target is eligible when its
 provider exists, is enabled, is not cooling down, and can handle any special request constraint.
 Weights and `stickyLimit` do not affect this strategy.

src/server/responses/combo-required-tool-contract.ts

@@ -10,6 +10,33 @@ export type RequiredToolContract =
   | { kind: "any"; hostedCallTypes: ReadonlySet<string> }
   | { kind: "named"; name: string };
 
+const allowedHostedSelectors = new Set([
+  "web_search", "web_search_preview", "file_search", "computer_use_preview", "computer_use",
+  "code_interpreter", "image_generation", "image_gen", "tool_search",
+]);
+
+/** Only definite, well-formed mandatory selectors justify excluding a destination. */
+export function hasMandatoryToolChoice(rawBody: unknown): boolean {
+  if (!rawBody || typeof rawBody !== "object" || Array.isArray(rawBody)) return false;
+  const choice = (rawBody as Record<string, unknown>).tool_choice;
+  if (choice === "required") return true;
+  if (!choice || typeof choice !== "object" || Array.isArray(choice)) return false;
+  const selector = choice as Record<string, unknown>;
+  if (selector.type === "function" || selector.type === "custom") {
+    return typeof selector.name === "string" && selector.name.trim().length > 0;
+  }
+  return selector.type === "allowed_tools" && selector.mode === "required"
+    && Array.isArray(selector.tools) && selector.tools.length > 0
+    && selector.tools.every((tool: unknown) => {
+      if (!tool || typeof tool !== "object" || Array.isArray(tool)) return false;
+      const entry = tool as Record<string, unknown>;
+      if (entry.name !== undefined && (typeof entry.name !== "string" || !entry.name.trim())) return false;
+      if (entry.type === "function" || entry.type === "custom") return typeof entry.name === "string";
+      if (entry.type === "mcp") return typeof entry.server_label === "string" && !!entry.server_label.trim();
+      return typeof entry.type === "string" && allowedHostedSelectors.has(entry.type);
+    });
+}
+
 const hostedCalls = new Map([
   ["web_search", "web_search_call"], ["web_search_preview", "web_search_call"],
   ["file_search", "file_search_call"], ["code_interpreter", "code_interpreter_call"],

src/server/responses/core-combo.ts

@@ -1,4 +1,7 @@
 import { effectiveAzureOutputBudget } from "../../adapters/azure";
+import { buildResponsesTransport } from "../../adapters/openai-responses/transport";
+import { isMetaAiResponsesDestination } from "../../responses/muse-tool-name-alias";
+import { hasMandatoryToolChoice } from "./combo-required-tool-contract";
 import { isCodexAccountCooldownResponse } from "../../codex/account-cooldown-response";
 import { resolveWireProtocolOverride } from "../adapter-resolve";
 import { comboCooldownRetryAfterSeconds, isDefiniteContextOverflow, type CodexAccountModelRefusal } from "../../combos/failover";
@@ -56,7 +59,7 @@ import {
   previousResponseProviderState,
 } from "../../responses/state";
 import { hasUnreadableEncryptedAgentTask } from "./encrypted-payload";
-import { routeConcreteModel, comboRouteDecisionTrace } from "../../router";
+import { captureRouteStaticPolicy, routeConcreteModel, comboRouteDecisionTrace } from "../../router";
 import { memoryModelRouteReason } from "./memory-models";
 import { baseProviderLabel, poolAccountProviderLabel } from "../../providers/label";
 import { getAccountSet } from "../../oauth/store";
@@ -533,10 +536,29 @@ export async function executeComboResponses(
   const payloadEligible = (target: (typeof combo.targets)[number]): boolean =>
     comboPayloadReadable || !unreadableEncryptedAgentTask || canDecryptUnreadableAgentTask(target);
   const meteredAllowed = admissionMayUseMeteredComboTargets(config, options.admission, combo);
+  const museToolEligible = (target: (typeof combo.targets)[number]): boolean => {
+    if (!hasMandatoryToolChoice(body)) return true;
+    try {
+      const route = routeConcreteModel(config, `${target.provider}/${target.model}`);
+      const inboundWire = options.inboundWire ?? "responses";
+      const policy = captureRouteStaticPolicy(route.providerName, route.modelId, route.provider,
+        route.staticPolicy.effectiveAlias, inboundWire);
+      const provider = resolveWireProtocolOverride(route.providerName, route.modelId, route.provider, inboundWire, policy);
+      return provider.adapter !== "openai-responses"
+        || !isMetaAiResponsesDestination(buildResponsesTransport(provider, { headers: req.headers }).url);
+    } catch {
+      return true;
+    }
+  };
+  const onlyMuseToolIncompatible = (): boolean => {
+    const enabled = combo.targets.filter(target => config.providers[target.provider]?.disabled !== true);
+    return enabled.length > 0 && enabled.every(target => !museToolEligible(target));
+  };
   // Recovery can replace unreadable encrypted input, but cannot relax other admission checks.
   const recoveryEligible = (target: (typeof combo.targets)[number]): boolean =>
     (meteredAllowed || !target.metered)
     && (combo.strategy !== "jev" || target.provider !== JEV_PROVIDER_ID)
+    && museToolEligible(target)
     && reasoningReplayEligible(target)
     && (protocolLanes?.pickable(target) ?? true);
   const targetEligible = (target: (typeof combo.targets)[number]): boolean =>
@@ -651,6 +673,9 @@ export async function executeComboResponses(
         config,
         { parentThreadId: inboundClientThreadId },
       );
+      if (!options.abortSignal?.aborted && onlyMuseToolIncompatible()) {
+        return comboUnavailableResponse(`No available targets for combo: ${comboId}; Meta Responses does not support mandatory tool_choice`);
+      }
       return options.abortSignal?.aborted
         ? clientCancelledResponse()
         : comboUnavailable(comboId, undefined,
@@ -668,6 +693,9 @@ export async function executeComboResponses(
     const protocolRefusal = protocolLanes?.refusal();
     if (protocolRefusal) return protocolRefusal;
     if (onlyReplayIncompatibleTargetsRemain()) return targetIncompatibleResponse();
+    if (!options.abortSignal?.aborted && onlyMuseToolIncompatible()) {
+      return comboUnavailableResponse(`No available targets for combo: ${comboId}; Meta Responses does not support mandatory tool_choice`);
+    }
     return options.abortSignal?.aborted
       ? clientCancelledResponse()
       : comboUnavailable(comboId, undefined, comboExclusionReasons(config, comboId, targetEligible));

structure/transports/responses-combo-boundaries.md

@@ -20,6 +20,13 @@ and `tests/responses/responses-combo-exhausted-error.test.ts`.
 
 ## Buffered required-tool contract
 
+Before selection, `src/server/responses/core-combo.ts` excludes resolved Meta Responses destinations
+for well-formed mandatory `tool_choice` selectors, including required allowed-tools lists. Normal and
+recovery picks share the check, resolving the inbound wire's static model policy and actual Responses
+transport URL; malformed and unknown selectors retain their ordinary error path. The next target
+receives the original selector, and an all-Meta exhaustion names the constraint before any send.
+Coverage: `tests/server/server-combo-required-tool-contract.test.ts`.
+
 Before combo success bookkeeping, native delivery in `src/server/responses/passthrough-delivery.ts`
 uses `src/server/responses/combo-required-tool-contract.ts` to check successful native
 `openai-responses` JSON children with explicit required or named function/custom choices.

tests/server/server-combo-required-tool-contract.test.ts

@@ -21,6 +21,7 @@ import type { OcxConfig } from "../../src/types";
 import { item as hostedImage } from "../fixtures/hosted-image-display";
 import { createTestTranslatorBudget } from "../helpers/translator-budget";
 import { deliverPassthroughResponse } from "../../src/server/responses/passthrough-delivery";
+import { encryptedInput } from "../helpers/agent-task-recovery";
 
 /**
  * #7456: a Responses combo child that answers a `tool_choice`-required request with a buffered
@@ -164,6 +165,146 @@ function requiredRequest(extra: Record<string, unknown> = {}): Request {
 }
 
 describe("combo required-tool contract on buffered children (#7456)", () => {
+  for (const choice of ["required", { type: "function", name: "shell" },
+    { type: "allowed_tools", mode: "required", tools: [{ type: "function", name: "shell" }] }]) {
+  test(`Meta mandatory tool choice selects the next target before send (#7964): ${JSON.stringify(choice)}`, async () => {
+    const bodies: unknown[] = [];
+    let metaSends = 0;
+    const b = serve(async request => {
+      bodies.push(await request.json());
+      return Response.json(completedWithCall("m2", "shell"));
+    });
+    const response = await handleResponsesWith(comboConfig({
+      a: provider("openai-responses", "https://api.meta.ai/v1", "key-a", { fetch: (async () => { metaSends++; throw new Error("unexpected Meta send"); }) as typeof fetch }),
+      b: provider("openai-responses", baseUrl(b), "key-b"),
+    }), requiredRequest({ tool_choice: choice }));
+    expect(response.status).toBe(200);
+    expect(bodies).toHaveLength(1);
+    expect(metaSends).toBe(0);
+    expect(bodies[0]).toMatchObject({ tool_choice: choice });
+  });
+  }
+  for (const choice of ["auto", "none"]) {
+    test(`Meta accepts ${choice} without a hop`, async () => {
+      let sends = 0;
+      const meta = provider("openai-responses", "https://api.meta.ai/v1", "key-a", {
+        fetch: (async () => { sends++; return Response.json(completedNoCall("m1", "meta")); }) as typeof fetch,
+      });
+      const response = await handleResponsesWith(comboConfig({ a: meta }), requiredRequest({ tool_choice: choice }));
+      expect(response.status).toBe(200);
+      expect(sends).toBe(1);
+    });
+  }
+  test("malformed choice remains a local Meta 400", async () => {
+    let sends = 0;
+    const meta = provider("openai-responses", "https://api.meta.ai/v1", "key-a", {
+      fetch: (async () => { sends++; throw new Error("unexpected send"); }) as typeof fetch,
+    });
+    const response = await handleResponsesWith(comboConfig({ a: meta }), requiredRequest({ tool_choice: { type: "function" } }));
+    expect(response.status).toBe(400);
+    expect(sends).toBe(0);
+  });
+  test("#7982 chat configuration with Responses override skips Meta", async () => {
+    const bodies: unknown[] = [];
+    const next = serve(async request => { bodies.push(await request.json()); return Response.json(completedWithCall("m2", "shell")); });
+    const response = await handleResponsesWith(comboConfig({
+      a: provider("openai-chat", "https://api.meta.ai/v1", "key-a", { modelAdapters: { m1: "openai-responses" } }),
+      b: provider("openai-responses", baseUrl(next), "key-b"),
+    }), requiredRequest({ tool_choice: "required" }));
+    expect(response.status).toBe(200);
+    expect(bodies).toHaveLength(1);
+    expect(bodies[0]).toMatchObject({ tool_choice: "required" });
+  });
+  test("#7982 Responses configuration with Chat override sends to Meta Chat", async () => {
+    let sends = 0;
+    const response = await handleResponsesWith(comboConfig({
+      a: provider("openai-responses", "https://api.meta.ai/v1", "key-a", {
+        modelAdapters: { m1: "openai-chat" },
+        fetch: (async () => { sends++; return Response.json({ id: "chat-1", object: "chat.completion", model: "m1", choices: [{ index: 0, finish_reason: "tool_calls", message: { role: "assistant", content: null, tool_calls: [{ id: "call_a", type: "function", function: { name: "shell", arguments: "{}" } }] } }] }); }) as typeof fetch,
+      }),
+    }), requiredRequest({ tool_choice: "required" }));
+    expect(response.status).toBe(200);
+    await response.text();
+    expect(sends).toBe(1);
+  });
+  test("#7982 unknown and malformed hosted selectors do not exclude Meta", async () => {
+    const { hasMandatoryToolChoice } = await import("../../src/server/responses/combo-required-tool-contract");
+    for (const entry of [{ type: "not_a_tool" }, { type: "web_search", name: 5 }, { type: "mcp" }, { type: "mcp", server_label: 5 }]) {
+      const choice = { type: "allowed_tools", mode: "required", tools: [entry] };
+      expect(hasMandatoryToolChoice({ tool_choice: choice })).toBe(false);
+      const response = await handleResponsesWith(comboConfig({ a: provider("openai-responses", "https://api.meta.ai/v1", "key-a") }), requiredRequest({ tool_choice: choice }));
+      expect(response.status).toBe(400);
+    }
+    for (const entry of [{ type: "web_search" }, { type: "mcp", server_label: "docs" }]) {
+      expect(hasMandatoryToolChoice({ tool_choice: { type: "allowed_tools", mode: "required", tools: [entry] } })).toBe(true);
+    }
+  });
+  test("#7982 encrypted recovery selection cannot pick a Meta target", async () => {
+    const response = await handleResponsesWith(comboConfig({ a: provider("openai-responses", "https://api.meta.ai/v1", "key-a") }),
+      requiredRequest({ input: encryptedInput(), tool_choice: "required" }));
+    expect(response.status).toBe(503);
+    expect(await response.text()).toContain("mandatory tool_choice");
+  });
+  for (const [extra, expectedUrl] of [
+    [{ responsesPath: "/other/responses" }, "https://api.meta.ai/other/responses"],
+    [{ authMode: "forward" as const, responsesPath: "/ignored" }, "https://api.meta.ai/responses"],
+  ] as const) {
+    test(`#7982 resolved Meta URL excludes mandatory choice: ${JSON.stringify(extra)}`, async () => {
+      const response = await handleResponsesWith(comboConfig({ a: provider("openai-responses", "https://api.meta.ai", "key-a", extra) }), requiredRequest({ tool_choice: "required" }));
+      expect(response.status).toBe(503);
+      expect(await response.text()).toContain("mandatory tool_choice");
+      let sentUrl = "";
+      const auto = await handleResponsesWith(comboConfig({ a: provider("openai-responses", "https://api.meta.ai", "key-a", {
+        ...extra, fetch: (async input => { sentUrl = String(input); return Response.json(completedNoCall("m1", "meta")); }) as typeof fetch,
+      }) }), requiredRequest({ tool_choice: "auto" }));
+      expect(auto.status).toBe(200);
+      expect(sentUrl).toBe(expectedUrl);
+    });
+  }
+  test("selector eligibility recognizes custom choices and abstains on malformed allowed lists", async () => {
+    const { hasMandatoryToolChoice } = await import("../../src/server/responses/combo-required-tool-contract");
+    expect(hasMandatoryToolChoice({ tool_choice: { type: "custom", name: "shell" } })).toBe(true);
+    for (const choice of [
+      { type: "function", name: "" },
+      { type: "allowed_tools", mode: "required", tools: [] },
+      { type: "allowed_tools", mode: "required", tools: [{ type: "function" }] },
+      { type: "allowed_tools", mode: "required", tools: [{ type: 5 }] },
+      { type: "allowed_tools", mode: "auto", tools: [{ type: "function", name: "shell" }] },
+    ]) expect(hasMandatoryToolChoice({ tool_choice: choice })).toBe(false);
+  });
+  test("all Meta targets report the mandatory choice constraint", async () => {
+    const meta = provider("openai-responses", "https://api.meta.ai/v1", "key-a");
+    const response = await handleResponsesWith(comboConfig({ a: meta, b: meta }), requiredRequest({ tool_choice: "required" }));
+    expect(response.status).toBe(503);
+    expect(await response.text()).toContain("mandatory tool_choice");
+  });
+  test("a non-Meta first target remains eligible for mandatory tools", async () => {
+    let sends = 0;
+    const upstream = serve(() => { sends++; return Response.json(completedWithCall("m1", "shell")); });
+    const response = await handleResponsesWith(comboConfig({
+      a: provider("openai-responses", baseUrl(upstream), "key-a"),
+      b: provider("openai-responses", "https://api.meta.ai/v1", "key-b"),
+    }), requiredRequest({ tool_choice: "required" }));
+    expect(response.status).toBe(200);
+    expect(sends).toBe(1);
+  });
+  test("streaming mandatory choice skips Meta before the first send", async () => {
+    const bodies: Record<string, unknown>[] = [];
+    const upstream = serve(async request => {
+      bodies.push(await request.json() as Record<string, unknown>);
+      const payload = completedWithCall("m2", "shell");
+      return new Response(`data: ${JSON.stringify({ type: "response.completed", response: payload })}\n\n`,
+        { headers: { "content-type": "text/event-stream" } });
+    });
+    const response = await handleResponsesWith(comboConfig({
+      a: provider("openai-responses", "https://api.meta.ai/v1", "key-a"),
+      b: provider("openai-responses", baseUrl(upstream), "key-b"),
+    }), requiredRequest({ stream: true, tool_choice: "required" }));
+    expect(response.status).toBe(200);
+    await response.text();
+    expect(bodies).toHaveLength(1);
+    expect(bodies[0]!.tool_choice).toBe("required");
+  });
   test("a folded-SSE contract failure settles reported usage without completion effects", async () => {
     let effects = 0;
     let settled: unknown;