fix(agents): guard OpenAI transport tool descriptors

vincentkoc · vincentkoc · commit 65f9da58e7c7 · 2026-06-01T10:57:42.000+02:00
diff --git a/src/agents/openai-transport-stream.test.ts b/src/agents/openai-transport-stream.test.ts
@@ -4173,6 +4173,65 @@ describe("openai transport stream", () => {
     expect(first.tools).toEqual(second.tools);
   });
 
+  it("materializes OpenAI transport tool descriptors before request conversion", () => {
+    const responsesModel = {
+      id: "gpt-5.4",
+      name: "GPT-5.4",
+      api: "openai-responses",
+      provider: "openai",
+      baseUrl: "https://api.openai.com/v1",
+      reasoning: true,
+      input: ["text"],
+      cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+      contextWindow: 200000,
+      maxTokens: 8192,
+    } satisfies Model<"openai-responses">;
+    const completionsModel = {
+      ...responsesModel,
+      api: "openai-completions",
+    } satisfies Model<"openai-completions">;
+    const toolWithUnreadableDescription = {
+      name: "safe_lookup",
+      get description() {
+        throw new Error("description exploded");
+      },
+      parameters: { type: "object", properties: {}, additionalProperties: false },
+    };
+    const toolWithUnreadableName = {
+      get name() {
+        throw new Error("name exploded");
+      },
+      description: "Skip me",
+      parameters: { type: "object", properties: {}, additionalProperties: false },
+    };
+
+    const responsesParams = buildOpenAIResponsesParams(
+      responsesModel,
+      {
+        systemPrompt: "system",
+        messages: [],
+        tools: [toolWithUnreadableDescription, toolWithUnreadableName],
+      } as never,
+      undefined,
+    ) as { tools?: Array<{ name?: string; description?: string }> };
+    const completionsParams = buildOpenAICompletionsParams(
+      completionsModel,
+      {
+        systemPrompt: "system",
+        messages: [],
+        tools: [toolWithUnreadableDescription, toolWithUnreadableName],
+      } as never,
+      undefined,
+    ) as { tools?: Array<{ function?: { name?: string; description?: string } }> };
+
+    expect(responsesParams.tools).toHaveLength(1);
+    expect(responsesParams.tools?.[0]).toMatchObject({ name: "safe_lookup" });
+    expect(responsesParams.tools?.[0]?.description).toBe("");
+    expect(completionsParams.tools).toHaveLength(1);
+    expect(completionsParams.tools?.[0]?.function).toMatchObject({ name: "safe_lookup" });
+    expect(completionsParams.tools?.[0]?.function?.description).toBe("");
+  });
+
   it("falls back to strict:false when a native OpenAI tool schema is not strict-compatible", () => {
     const params = buildOpenAIResponsesParams(
       {
diff --git a/src/agents/openai-transport-stream.ts b/src/agents/openai-transport-stream.ts
@@ -113,6 +113,13 @@ type ReplayableResponseReasoningItem = Omit<ResponseReasoningItem, "id"> & {
   [OPENAI_RESPONSES_REASONING_REPLAY_META_KEY]?: OpenAIResponsesReasoningReplayMetadata;
 };
 type ResponsesClientLike = ReturnType<typeof createOpenAIResponsesClient>;
+type OpenAITransportTool = NonNullable<Context["tools"]>[number];
+type MaterializedOpenAITransportTool = {
+  name: string;
+  description: string;
+  parameters: unknown;
+  sourceIndex: number;
+};
 
 type BaseStreamOptions = {
   temperature?: number;
@@ -1256,11 +1263,12 @@ function convertResponsesTools(
   model: OpenAIModeModel,
   options?: { strict?: boolean | null },
 ): FunctionTool[] {
-  const strict = resolveOpenAIStrictToolFlagWithDiagnostics(tools, options?.strict, {
+  const materializedTools = materializeOpenAITransportTools(tools);
+  const strict = resolveOpenAIStrictToolFlagWithDiagnostics(materializedTools, options?.strict, {
     transport: "responses",
     model,
   });
-  return sortTransportToolsByName(tools).map((tool): FunctionTool => {
+  return sortTransportToolsByName(materializedTools).map((tool): FunctionTool => {
     const result = {
       type: "function" as const,
       name: tool.name,
@@ -1279,7 +1287,7 @@ function convertResponsesTools(
 }
 
 function resolveOpenAIStrictToolFlagWithDiagnostics(
-  tools: NonNullable<Context["tools"]>,
+  tools: readonly { name?: string; parameters: unknown }[],
   strictSetting: boolean | null | undefined,
   context: { transport: "responses" | "completions"; model: OpenAIModeModel },
 ): boolean | undefined {
@@ -3263,8 +3271,9 @@ function convertTools(
   compat: ReturnType<typeof getCompat>,
   model: OpenAIModeModel,
 ) {
+  const materializedTools = materializeOpenAITransportTools(tools);
   const strict = resolveOpenAIStrictToolFlagWithDiagnostics(
-    tools,
+    materializedTools,
     resolveOpenAIStrictToolSetting(model, {
       transport: "stream",
       supportsStrictMode: compat?.supportsStrictMode,
@@ -3274,7 +3283,7 @@ function convertTools(
       model,
     },
   );
-  return sortTransportToolsByName(tools).map((tool) => {
+  return sortTransportToolsByName(materializedTools).map((tool) => {
     const functionTool: {
       name: string;
       description: string | undefined;
@@ -3299,6 +3308,58 @@ function convertTools(
   });
 }
 
+function readOpenAITransportToolField<TField extends keyof OpenAITransportTool>(
+  tool: OpenAITransportTool,
+  field: TField,
+): { ok: true; value: OpenAITransportTool[TField] } | { ok: false } {
+  try {
+    return { ok: true, value: tool[field] };
+  } catch {
+    return { ok: false };
+  }
+}
+
+function materializeOpenAITransportTools(
+  tools: NonNullable<Context["tools"]>,
+): MaterializedOpenAITransportTool[] {
+  const materializedTools: MaterializedOpenAITransportTool[] = [];
+  const skippedTools: string[] = [];
+  tools.forEach((tool, sourceIndex) => {
+    const nameRead = readOpenAITransportToolField(tool, "name");
+    const name = nameRead.ok && typeof nameRead.value === "string" ? nameRead.value : "";
+    const toolLabel = name || `tool[${sourceIndex}]`;
+    if (!name) {
+      skippedTools.push(toolLabel);
+      return;
+    }
+    const parametersRead = readOpenAITransportToolField(tool, "parameters");
+    if (!parametersRead.ok) {
+      skippedTools.push(toolLabel);
+      return;
+    }
+    const descriptionRead = readOpenAITransportToolField(tool, "description");
+    materializedTools.push({
+      name,
+      description:
+        descriptionRead.ok && typeof descriptionRead.value === "string"
+          ? descriptionRead.value
+          : "",
+      parameters: parametersRead.value,
+      sourceIndex,
+    });
+  });
+  if (skippedTools.length > 0) {
+    log.warn(
+      `OpenAI transport skipped ${skippedTools.length} unreadable tool descriptor${skippedTools.length === 1 ? "" : "s"} before request conversion`,
+      {
+        tools: skippedTools.slice(0, 10),
+        omitted: Math.max(0, skippedTools.length - 10),
+      },
+    );
+  }
+  return materializedTools;
+}
+
 function compareTransportToolText(left: string | undefined, right: string | undefined): number {
   const leftText = left ?? "";
   const rightText = right ?? "";
