fix(runtime): honor Alibaba Responses tool choice contract

Permit documented required and allowed_tools choices when they select exactly one tool, while keeping provider-owned store:false finalization and rejecting unsupported forced shapes.\n\nGenerated-by: OpenAI Codex

Author: MoonOld

packages/runtime/src/__tests__/open-responses-compatibility.test.ts

@@ -24,6 +24,7 @@ import { createOpenResponsesCompatibilityFinalizer } from '../open-responses-com
 test('applies the declared Open Responses body policies', () => {
   const finalize = createOpenResponsesCompatibilityFinalizer('alibaba-token-plan');
   assert.ok(finalize);
+  const tool = { type: 'function', name: 'lookup' };
   assert.deepEqual(finalize({ model: 'qwen3.8-max', store: true, tool_choice: 'auto' }), {
     model: 'qwen3.8-max',
     store: false,
@@ -33,10 +34,36 @@ test('applies the declared Open Responses body policies', () => {
     model: 'qwen3.8-max',
     store: false,
   });
-  for (const toolChoice of ['required', { type: 'function', name: 'lookup' }]) {
-    assert.throws(
-      () => finalize({ tool_choice: toolChoice }),
-      /does not support forced tool_choice/,
-    );
-  }
+  assert.deepEqual(finalize({ tools: [tool], tool_choice: 'required' }), {
+    tools: [tool],
+    tool_choice: 'required',
+    store: false,
+  });
+  assert.deepEqual(
+    finalize({
+      tools: [tool],
+      tool_choice: { type: 'allowed_tools', mode: 'required', tools: [tool] },
+    }),
+    {
+      tools: [tool],
+      tool_choice: { type: 'allowed_tools', mode: 'required', tools: [tool] },
+      store: false,
+    },
+  );
+  assert.throws(
+    () => finalize({ tools: [], tool_choice: 'required' }),
+    /requires exactly one tool/,
+  );
+  assert.throws(
+    () =>
+      finalize({
+        tools: [tool],
+        tool_choice: { type: 'allowed_tools', mode: 'required', tools: [] },
+      }),
+    /requires exactly one tool/,
+  );
+  assert.throws(
+    () => finalize({ tools: [tool], tool_choice: tool }),
+    /does not support this tool_choice object/,
+  );
 });

packages/runtime/src/__tests__/responses-wire-contract.test.ts

@@ -366,6 +366,73 @@ describe('responses wire request body', () => {
     assert.deepEqual(bodies[0]?.reasoning, { effort: 'medium' });
   });
 
+  test('Alibaba compatibility preserves documented required tool choices', async () => {
+    const bodies: Array<Record<string, unknown>> = [];
+    const fetch = (async (_url: string | URL | Request, init?: RequestInit) => {
+      bodies.push(JSON.parse(String(init?.body)));
+      return Response.json({
+        id: 'response-required-tool',
+        object: 'response',
+        created_at: 1,
+        model: 'qwen3.8-max',
+        status: 'completed',
+        output: [],
+        usage: { input_tokens: 1, output_tokens: 1, total_tokens: 2 },
+      });
+    }) as unknown as typeof globalThis.fetch;
+    const connection = {
+      ...conn('alibaba-token-plan-cn'),
+      baseUrl: 'https://token-plan.example/compatible-mode/v1',
+    };
+    const model = getAIModel({
+      connection,
+      apiKey: 'token-plan-key',
+      modelId: 'qwen3.8-max',
+      fetch,
+    });
+
+    await model.doGenerate({
+      prompt: [{ role: 'user', content: [{ type: 'text', text: 'look it up' }] }],
+      tools: [
+        {
+          type: 'function',
+          name: 'lookup',
+          inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+        },
+      ],
+      toolChoice: { type: 'required' },
+    });
+
+    const allowedToolsChoice = {
+      type: 'allowed_tools',
+      mode: 'required',
+      tools: [{ type: 'function', name: 'lookup' }],
+    };
+    const overlayModel = getAIModel({
+      connection: { ...connection, requestBodyOverlay: { tool_choice: allowedToolsChoice } },
+      apiKey: 'token-plan-key',
+      modelId: 'qwen3.8-max',
+      fetch,
+    });
+    await overlayModel.doGenerate({
+      prompt: [{ role: 'user', content: [{ type: 'text', text: 'look it up again' }] }],
+      tools: [
+        {
+          type: 'function',
+          name: 'lookup',
+          inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+        },
+      ],
+    });
+
+    assert.equal(bodies[0]?.tool_choice, 'required');
+    assert.equal((bodies[0]?.tools as unknown[] | undefined)?.length, 1);
+    assert.equal(bodies[0]?.store, false);
+    assert.deepEqual(bodies[1]?.tool_choice, allowedToolsChoice);
+    assert.equal((bodies[1]?.tools as unknown[] | undefined)?.length, 1);
+    assert.equal(bodies[1]?.store, false);
+  });
+
   test('Alibaba compatibility survives header-only request customization', async () => {
     let body: Record<string, unknown> | undefined;
     let headers: Headers | undefined;
@@ -402,7 +469,7 @@ describe('responses wire request body', () => {
     assert.equal(headers?.get('x-token-plan-routing'), 'custom');
   });
 
-  test('Alibaba stateless request carries the reconstructed summary item', async () => {
+  test('Alibaba non-stored request carries the reconstructed summary item', async () => {
     let body: Record<string, unknown> | undefined;
     const fetch = (async (_url: string | URL | Request, init?: RequestInit) => {
       body = JSON.parse(String(init?.body));

packages/runtime/src/model-factory.ts

@@ -179,7 +179,7 @@ export function getAIModel(input: ModelFactoryInput): LanguageModelV4 {
         if (reasoningReplay.contract.adapter === 'open-responses') {
           // Request customization is applied first; provider compatibility is
           // the final authority before network dispatch, so an overlay cannot
-          // re-enable storage or force a tool-choice shape the provider rejects.
+          // re-enable storage or violate the provider's tool-choice contract.
           const responsesFetch = createRequestCustomizationFetch(baseFetch, {
             ...requestCustomization,
             finalizeBody: createOpenResponsesCompatibilityFinalizer(

packages/runtime/src/open-responses-compatibility.ts

@@ -19,14 +19,33 @@
 
 import type { OpenResponsesCompatibilityProfile } from './provider-runtime-policy.js';
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function requiredToolCount(body: Record<string, unknown>): number | undefined {
+  const choice = body.tool_choice;
+  if (choice === 'required') {
+    return Array.isArray(body.tools) ? body.tools.length : 0;
+  }
+  if (isRecord(choice) && choice.type === 'allowed_tools' && choice.mode === 'required') {
+    return Array.isArray(choice.tools) ? choice.tools.length : 0;
+  }
+  return undefined;
+}
+
 export function createOpenResponsesCompatibilityFinalizer(
   profile: OpenResponsesCompatibilityProfile | undefined,
 ): ((body: Record<string, unknown>) => Record<string, unknown>) | undefined {
   if (!profile) return undefined;
   return (body) => {
     const choice = body.tool_choice;
-    if (choice === 'required' || (choice !== null && typeof choice === 'object')) {
-      throw new Error('Alibaba Token Plan Responses does not support forced tool_choice');
+    const forcedToolCount = requiredToolCount(body);
+    if (forcedToolCount !== undefined && forcedToolCount !== 1) {
+      throw new Error('Alibaba Token Plan Responses requires exactly one tool for tool_choice');
+    }
+    if (isRecord(choice) && choice.type !== 'allowed_tools') {
+      throw new Error('Alibaba Token Plan Responses does not support this tool_choice object');
     }
     return { ...body, store: false };
   };