@robota-sdk/agent-provider-openai 3.0.0-beta.63 → 3.0.0-beta.82

package/src/openai/__tests__/tool-schema-projection.test.ts

@@ -0,0 +1,302 @@
+/**
+ * MCP-005 (TC-08) — conformance: the real `OpenAIProvider` over the shared MCP-005 fixture set.
+ *
+ * With `strictTools` off both the Responses and Chat Completions surfaces carry the permissive
+ * projection; with it on both carry the strict projection (§ Profiles — both surfaces honor
+ * `strictTools` identically). Adopted/adapted fixtures reach the request in projected form (compared
+ * against `projectToolSchema` directly, not hand-computed); rejected fixtures are absent; one
+ * `tool_schema_quarantined` warn per absent fixture names it. Both `chat` and `chatStream` request
+ * paths of each converter are exercised.
+ */
+import {
+  PERMISSIVE_TOOL_SCHEMA_PROFILE,
+  projectToolSchema,
+  setGlobalLoggerSink,
+  STRICT_TOOL_SCHEMA_PROFILE,
+} from '@robota-sdk/agent-core';
+import { loadToolSchemaProjectionFixtures } from '@robota-sdk/agent-core/testing';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { OpenAIProvider } from '../provider';
+
+import type { IToolSchema, ILogger, TUniversalMessage } from '@robota-sdk/agent-core';
+
+vi.mock('openai', () => {
+  const MockOpenAI = vi.fn().mockImplementation(() => ({
+    chat: { completions: { create: vi.fn() } },
+    responses: { create: vi.fn() },
+  }));
+  return { default: MockOpenAI };
+});
+
+const fixtures = loadToolSchemaProjectionFixtures();
+const PERMISSIVE_PROFILE = { ...PERMISSIVE_TOOL_SCHEMA_PROFILE, providerName: 'openai' };
+const STRICT_PROFILE = { ...STRICT_TOOL_SCHEMA_PROFILE, providerName: 'openai' };
+
+function recordingSink(): { sink: ILogger; lines: string[] } {
+  const lines: string[] = [];
+  const record =
+    (level: string) =>
+    (...args: unknown[]): void => {
+      lines.push(`${level} ${args.map((value) => String(value)).join(' ')}`);
+    };
+  return {
+    lines,
+    sink: {
+      debug: record('debug'),
+      info: record('info'),
+      warn: record('warn'),
+      error: record('error'),
+      log: record('log'),
+    },
+  };
+}
+
+function createUserMessage(content: string): TUniversalMessage {
+  return { id: 'msg-1', state: 'complete' as const, role: 'user', content, timestamp: new Date() };
+}
+
+interface IFakeClient {
+  responses: { create: ReturnType<typeof vi.fn> };
+  chat: { completions: { create: ReturnType<typeof vi.fn> } };
+}
+
+function fakeClient(provider: OpenAIProvider): IFakeClient {
+  return (provider as unknown as { client: IFakeClient }).client;
+}
+
+function respondResponses(client: IFakeClient): void {
+  client.responses.create.mockResolvedValue({
+    id: 'resp-tool-schema-projection',
+    model: 'gpt-4o',
+    output_text: '',
+    output: [],
+    status: 'completed',
+  });
+}
+
+function respondChatCompletions(client: IFakeClient): void {
+  client.chat.completions.create.mockResolvedValue({
+    id: 'chatcmpl-tool-schema-projection',
+    object: 'chat.completion',
+    created: Date.now(),
+    model: 'gpt-4',
+    choices: [
+      {
+        index: 0,
+        message: { role: 'assistant', content: '', refusal: null },
+        finish_reason: 'stop',
+        logprobs: null,
+      },
+    ],
+  });
+}
+
+async function* streamResponsesResult() {
+  yield {
+    type: 'response.completed',
+    response: { id: 'resp-stream', output_text: '', output: [], status: 'completed' },
+  };
+}
+
+async function* streamChatCompletionsResult() {
+  yield {
+    id: 'chunk-1',
+    object: 'chat.completion.chunk',
+    created: Date.now(),
+    model: 'gpt-4',
+    choices: [{ index: 0, delta: { content: '' }, finish_reason: 'stop', logprobs: null }],
+  };
+}
+
+interface ISentTool {
+  name: string;
+  description: string;
+  parameters: unknown;
+}
+
+function sentToolsFromResponses(client: IFakeClient): ISentTool[] {
+  const [requestParams] = client.responses.create.mock.calls[
+    client.responses.create.mock.calls.length - 1
+  ] as [{ tools?: Array<{ name: string; description: string; parameters: unknown }> }];
+  return (requestParams.tools ?? []).map((tool) => ({
+    name: tool.name,
+    description: tool.description,
+    parameters: tool.parameters,
+  }));
+}
+
+function sentToolsFromChatCompletions(client: IFakeClient): ISentTool[] {
+  const [requestParams] = client.chat.completions.create.mock.calls[
+    client.chat.completions.create.mock.calls.length - 1
+  ] as [
+    {
+      tools?: Array<{ function: { name: string; description: string; parameters: unknown } }>;
+    },
+  ];
+  return (requestParams.tools ?? []).map((tool) => ({
+    name: tool.function.name,
+    description: tool.function.description,
+    parameters: tool.function.parameters,
+  }));
+}
+
+describe.each([
+  {
+    apiSurface: 'responses' as const,
+    respond: respondResponses,
+    sentTools: sentToolsFromResponses,
+  },
+  {
+    apiSurface: 'chat-completions' as const,
+    respond: respondChatCompletions,
+    sentTools: sentToolsFromChatCompletions,
+  },
+])(
+  'MCP-005 TC-08 — OpenAI $apiSurface, permissive profile (strictTools off)',
+  ({ apiSurface, respond, sentTools }) => {
+    afterEach(() => {
+      setGlobalLoggerSink(undefined);
+    });
+
+    it('reaches the request in projected form for adopted/adapted fixtures', async () => {
+      const provider = new OpenAIProvider({ apiKey: 'sk-test', apiSurface });
+      const client = fakeClient(provider);
+      respond(client);
+
+      const tools: IToolSchema[] = [
+        fixtures.subsetOnly,
+        fixtures.unknownKeywords,
+        fixtures.arrayItemsObject,
+      ];
+      await provider.chat([createUserMessage('hello')], { model: 'gpt-4o', tools });
+
+      const sent = sentTools(client);
+      expect(sent).toHaveLength(3);
+      for (const [index, tool] of tools.entries()) {
+        const projection = projectToolSchema(tool, PERMISSIVE_PROFILE);
+        expect(sent[index]?.parameters).toEqual(projection.tool.parameters);
+        expect(sent[index]?.description).toEqual(projection.tool.description);
+      }
+    });
+
+    it('omits a rejected fixture and reports one quarantine warn (chat)', async () => {
+      const recorder = recordingSink();
+      setGlobalLoggerSink(recorder.sink);
+      const provider = new OpenAIProvider({ apiKey: 'sk-test', apiSurface });
+      const client = fakeClient(provider);
+      respond(client);
+
+      const tools = [...fixtures.oneInvalidAmongMany] as IToolSchema[];
+      await provider.chat([createUserMessage('hello')], { model: 'gpt-4o', tools });
+
+      const sent = sentTools(client);
+      expect(sent.map((tool) => tool.name)).toEqual(['good_tool_one', 'good_tool_two']);
+
+      const quarantineLines = recorder.lines.filter((line) =>
+        line.includes('tool_schema_quarantined'),
+      );
+      expect(quarantineLines).toHaveLength(1);
+      expect(quarantineLines[0]).toContain('provider=openai');
+      expect(quarantineLines[0]).toContain('tool=bad_tool');
+    });
+
+    it('every documented rejection kind is absent from the request', async () => {
+      const recorder = recordingSink();
+      setGlobalLoggerSink(recorder.sink);
+      const provider = new OpenAIProvider({ apiKey: 'sk-test', apiSurface });
+      const client = fakeClient(provider);
+      respond(client);
+
+      const rejected: IToolSchema[] = [
+        fixtures.rootAnyOf,
+        fixtures.prototypeKey,
+        fixtures.deepNesting,
+        fixtures.oversized,
+      ];
+      await provider.chat([createUserMessage('hello')], { model: 'gpt-4o', tools: rejected });
+
+      expect(sentTools(client)).toHaveLength(0);
+      const quarantineLines = recorder.lines.filter((line) =>
+        line.includes('tool_schema_quarantined'),
+      );
+      expect(quarantineLines).toHaveLength(rejected.length);
+    });
+
+    it('projects tools on the chatStream request path too', async () => {
+      const provider = new OpenAIProvider({ apiKey: 'sk-test', apiSurface });
+      const client = fakeClient(provider);
+      if (apiSurface === 'responses') {
+        client.responses.create.mockResolvedValue(streamResponsesResult());
+      } else {
+        client.chat.completions.create.mockResolvedValue(streamChatCompletionsResult());
+      }
+
+      const tools = [...fixtures.oneInvalidAmongMany] as IToolSchema[];
+      for await (const _chunk of provider.chatStream([createUserMessage('hello')], {
+        model: 'gpt-4o',
+        tools,
+      })) {
+        // drain
+      }
+
+      const sent = sentTools(client);
+      expect(sent.map((tool) => tool.name)).toEqual(['good_tool_one', 'good_tool_two']);
+    });
+  },
+);
+
+describe.each([
+  {
+    apiSurface: 'responses' as const,
+    respond: respondResponses,
+    sentTools: sentToolsFromResponses,
+  },
+  {
+    apiSurface: 'chat-completions' as const,
+    respond: respondChatCompletions,
+    sentTools: sentToolsFromChatCompletions,
+  },
+])(
+  'MCP-005 TC-08 — OpenAI $apiSurface, strict profile (strictTools on)',
+  ({ apiSurface, respond, sentTools }) => {
+    it('reaches the request in strictly-projected form', async () => {
+      const provider = new OpenAIProvider({ apiKey: 'sk-test', apiSurface, strictTools: true });
+      const client = fakeClient(provider);
+      respond(client);
+
+      const tools: IToolSchema[] = [fixtures.subsetOnly, fixtures.nestedAnyOfOptional];
+      await provider.chat([createUserMessage('hello')], { model: 'gpt-4o', tools });
+
+      const sent = sentTools(client);
+      expect(sent).toHaveLength(2);
+      for (const [index, tool] of tools.entries()) {
+        const projection = projectToolSchema(tool, STRICT_PROFILE);
+        expect(sent[index]?.parameters).toEqual(projection.tool.parameters);
+        expect(sent[index]?.description).toEqual(projection.tool.description);
+      }
+    });
+
+    it('projects strictly on the chatStream request path too', async () => {
+      const provider = new OpenAIProvider({ apiKey: 'sk-test', apiSurface, strictTools: true });
+      const client = fakeClient(provider);
+      if (apiSurface === 'responses') {
+        client.responses.create.mockResolvedValue(streamResponsesResult());
+      } else {
+        client.chat.completions.create.mockResolvedValue(streamChatCompletionsResult());
+      }
+
+      const tools: IToolSchema[] = [fixtures.subsetOnly];
+      for await (const _chunk of provider.chatStream([createUserMessage('hello')], {
+        model: 'gpt-4o',
+        tools,
+      })) {
+        // drain
+      }
+
+      const sent = sentTools(client);
+      const projection = projectToolSchema(fixtures.subsetOnly, STRICT_PROFILE);
+      expect(sent[0]?.parameters).toEqual(projection.tool.parameters);
+    });
+  },
+);

package/src/openai/__tests__/trace-context-wire.test.ts

@@ -0,0 +1,114 @@
+/**
+ * Trusted `traceparent` on the wire: captured at the SDK's own fetch, for every call site on both
+ * API surfaces.
+ */
+import OpenAI from 'openai';
+import { describe, expect, it } from 'vitest';
+
+import { OpenAIProvider } from '../provider';
+
+import type { IChatOptions, IOutboundTraceContext, TUniversalMessage } from '@robota-sdk/agent-core';
+
+const TRACEPARENT = '00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01';
+
+const completion = {
+  id: 'c1', object: 'chat.completion', created: 0, model: 'gpt-test',
+  choices: [{ index: 0, message: { role: 'assistant', content: 'hi' }, finish_reason: 'stop' }],
+};
+const completionChunks = [
+  { id: 'c1', object: 'chat.completion.chunk', created: 0, model: 'gpt-test', choices: [{ index: 0, delta: { role: 'assistant', content: 'hi' }, finish_reason: null }] },
+  { id: 'c1', object: 'chat.completion.chunk', created: 0, model: 'gpt-test', choices: [{ index: 0, delta: {}, finish_reason: 'stop' }] },
+];
+const response = {
+  id: 'resp_1', object: 'response', created_at: 0, model: 'gpt-test', status: 'completed',
+  output: [{ type: 'message', id: 'msg_1', role: 'assistant', status: 'completed', content: [{ type: 'output_text', text: 'hi', annotations: [] }] }],
+  usage: { input_tokens: 1, output_tokens: 1, total_tokens: 2 },
+};
+const responseEvents = [
+  { type: 'response.output_text.delta', item_id: 'msg_1', output_index: 0, content_index: 0, delta: 'hi', sequence_number: 1 },
+  { type: 'response.completed', response, sequence_number: 2 },
+];
+
+function sse(events: readonly object[], done: boolean): string {
+  return events.map((event) => `data: ${JSON.stringify(event)}\n\n`).join('') + (done ? 'data: [DONE]\n\n' : '');
+}
+
+function wire(baseURL?: string) {
+  const seen: Array<{ url: string; traceparent: string | null }> = [];
+  const fetch = async (url: RequestInfo | URL, init?: RequestInit): Promise<Response> => {
+    const target = String(url);
+    seen.push({ url: target, traceparent: new Headers(init?.headers as HeadersInit).get('traceparent') });
+    const body = JSON.parse(String(init?.body)) as { stream?: boolean };
+    const responses = target.endsWith('/responses');
+    if (body.stream) {
+      return new Response(sse(responses ? responseEvents : completionChunks, !responses), {
+        status: 200, headers: { 'content-type': 'text/event-stream', 'x-request-id': 'req_1' },
+      });
+    }
+    return new Response(JSON.stringify(responses ? response : completion), {
+      status: 200, headers: { 'content-type': 'application/json', 'x-request-id': 'req_1' },
+    });
+  };
+  const client = new OpenAI({ apiKey: 'test-key', ...(baseURL ? { baseURL } : {}), fetch: fetch as never, maxRetries: 0 });
+  return { client, seen };
+}
+
+const messages: TUniversalMessage[] = [{ id: 'u1', role: 'user', content: 'hello', state: 'complete', timestamp: new Date() }];
+
+function traceTo(...allowedOrigins: string[]): IOutboundTraceContext {
+  return { traceparent: TRACEPARENT, allowedOrigins };
+}
+
+/** chat() without and with a delta callback, then chatStream(): every call site of one surface. */
+async function everyCallSite(provider: OpenAIProvider, options: IChatOptions): Promise<void> {
+  await provider.chat(messages, { model: 'gpt-test', ...options });
+  await provider.chat(messages, { model: 'gpt-test', onTextDelta: () => undefined, ...options });
+  for await (const _chunk of provider.chatStream(messages, { model: 'gpt-test', ...options })) {
+    // drain
+  }
+}
+
+describe('OpenAI trusted trace context', () => {
+  for (const apiSurface of ['chat-completions', 'responses'] as const) {
+    it(`sends traceparent from every ${apiSurface} call site when the client origin is listed`, async () => {
+      const { client, seen } = wire('https://gateway.example.com/v1');
+      const provider = new OpenAIProvider({ client, apiSurface });
+      const raw: unknown[] = [];
+      await everyCallSite(provider, {
+        outboundTraceContext: traceTo('https://gateway.example.com'),
+        onProviderNativeRawPayload: (event) => raw.push(event),
+      });
+      expect(provider.canPropagateTraceContext()).toBe(true);
+      expect(seen).toHaveLength(3);
+      expect(seen.map((request) => request.traceparent)).toEqual([TRACEPARENT, TRACEPARENT, TRACEPARENT]);
+      expect(raw.length).toBeGreaterThan(0);
+      expect(JSON.stringify(raw)).not.toContain('traceparent');
+      expect(JSON.stringify(raw)).not.toContain(TRACEPARENT);
+    });
+
+    it(`sends nothing from ${apiSurface} to the default vendor origin unless it is listed`, async () => {
+      const unlisted = wire();
+      await everyCallSite(new OpenAIProvider({ client: unlisted.client, apiSurface }), {
+        outboundTraceContext: traceTo('https://gateway.example.com'),
+      });
+      expect(unlisted.seen.map((request) => request.traceparent)).toEqual([null, null, null]);
+
+      const listed = wire();
+      await everyCallSite(new OpenAIProvider({ client: listed.client, apiSurface }), {
+        outboundTraceContext: traceTo('https://api.openai.com'),
+      });
+      expect(listed.seen.map((request) => request.traceparent)).toEqual([TRACEPARENT, TRACEPARENT, TRACEPARENT]);
+
+      const none = wire();
+      await everyCallSite(new OpenAIProvider({ client: none.client, apiSurface }), {});
+      expect(none.seen.map((request) => request.traceparent)).toEqual([null, null, null]);
+    });
+  }
+
+  it('cannot propagate through an executor or a client whose base URL is unreadable', () => {
+    const executor = { name: 'remote', version: '1', executeChat: async () => ({}), supportsTools: () => true, validateConfig: () => true };
+    expect(new OpenAIProvider({ executor } as never).canPropagateTraceContext()).toBe(false);
+    const opaque = { chat: { completions: { create: () => undefined } } } as unknown as OpenAI;
+    expect(new OpenAIProvider({ client: opaque }).canPropagateTraceContext()).toBe(false);
+  });
+});