@robota-sdk/agent-provider 3.0.0-beta.64

package/src/openai/types.ts

@@ -0,0 +1,194 @@
+import OpenAI from 'openai';
+
+import type { IPayloadLogger } from './interfaces/payload-logger';
+import type { IExecutor, ILogger, TProviderOptionValueBase } from '@robota-sdk/agent-core';
+
+export type TOpenAIApiSurface = 'responses' | 'chat-completions';
+
+export interface IOpenAIJsonSchemaDefinition {
+  name: string;
+  description?: string;
+  schema?: Record<string, TOpenAIProviderOptionValue>;
+  strict?: boolean;
+}
+
+export interface IOpenAIResponsesReasoningOptions {
+  effort?: 'low' | 'medium' | 'high';
+  summary?: 'auto' | 'concise' | 'detailed';
+}
+
+export interface IOpenAINativeWebToolsOptions {
+  webSearch?: boolean;
+  webFetch?: boolean;
+}
+
+/**
+ * Valid provider option value types
+ */
+export type TOpenAIProviderOptionValue =
+  | string
+  | number
+  | boolean
+  | undefined
+  | null
+  | IOpenAIJsonSchemaDefinition
+  | IOpenAINativeWebToolsOptions
+  | IOpenAIResponsesReasoningOptions
+  | OpenAI
+  | IPayloadLogger
+  | ILogger
+  | IExecutor
+  | TProviderOptionValueBase
+  | TOpenAIProviderOptionValue[]
+  | { [key: string]: TOpenAIProviderOptionValue };
+
+/**
+ * OpenAI provider options
+ */
+export interface IOpenAIProviderOptions {
+  /**
+   * Additional provider-specific options
+   */
+  [key: string]: TOpenAIProviderOptionValue;
+
+  /**
+   * OpenAI API key (required when client is not provided)
+   */
+  apiKey?: string;
+
+  /**
+   * OpenAI organization ID (optional)
+   */
+  organization?: string;
+
+  /**
+   * API request timeout (milliseconds)
+   */
+  timeout?: number;
+
+  /**
+   * API base URL (default: 'https://api.openai.com/v1')
+   */
+  baseURL?: string;
+
+  /**
+   * Default model used when chat options do not provide a model.
+   */
+  defaultModel?: string;
+
+  /**
+   * API surface to use for direct OpenAI calls.
+   *
+   * Defaults to Responses for official OpenAI calls. Profiles with baseURL use
+   * Chat Completions by default for OpenAI-compatible endpoint compatibility.
+   */
+  apiSurface?: TOpenAIApiSurface;
+
+  /**
+   * Response format (default: 'text')
+   * - 'text': Plain text response
+   * - 'json_object': JSON object mode (requires system message)
+   * - 'json_schema': Structured Outputs with schema validation
+   */
+  responseFormat?: 'text' | 'json_object' | 'json_schema';
+
+  /**
+   * JSON schema for structured outputs (required when responseFormat is 'json_schema')
+   */
+  jsonSchema?: IOpenAIJsonSchemaDefinition;
+
+  /**
+   * Responses API reasoning controls. Hidden reasoning is never exposed in message
+   * content; only explicit summaries/encrypted items requested here are represented.
+   */
+  reasoning?: IOpenAIResponsesReasoningOptions;
+
+  /**
+   * Whether OpenAI should store Responses API results. Defaults to OpenAI API behavior.
+   */
+  store?: boolean;
+
+  /**
+   * Include encrypted reasoning items for stateless reasoning continuation.
+   */
+  includeEncryptedReasoning?: boolean;
+
+  /**
+   * Opt into strict custom function parameter validation where supported.
+   */
+  strictTools?: boolean;
+
+  /**
+   * Provider-native hosted web tool request from provider profile options.
+   *
+   * OpenAI-compatible Chat Completions endpoints do not support this Robota
+   * native web contract. The provider rejects unsupported configurations before
+   * any model request is sent.
+   */
+  nativeWebTools?: IOpenAINativeWebToolsOptions;
+
+  /**
+   * OpenAI client instance (optional: will be created from apiKey if not provided)
+   */
+  client?: OpenAI;
+
+  /**
+   * Payload logger instance for debugging API requests/responses
+   *
+   * Use different implementations based on your environment:
+   * - FilePayloadLogger: Node.js file-based logging
+   * - ConsolePayloadLogger: Browser console-based logging
+   * - Custom: Implement IPayloadLogger interface
+   *
+   * @example
+   * ```typescript
+   * // Node.js
+   * import { FilePayloadLogger } from '@robota-sdk/agent-provider/openai/loggers';
+   * const provider = new OpenAIProvider({
+   *   client: openaiClient,
+   *   payloadLogger: new FilePayloadLogger({ logDir: './logs/openai' })
+   * });
+   *
+   * // Browser
+   * import { ConsolePayloadLogger } from '@robota-sdk/agent-provider/openai/loggers';
+   * const provider = new OpenAIProvider({
+   *   client: openaiClient,
+   *   payloadLogger: new ConsolePayloadLogger()
+   * });
+   * ```
+   */
+  payloadLogger?: IPayloadLogger;
+
+  /**
+   * Optional executor for handling AI requests
+   *
+   * When provided, the provider will delegate all chat operations to this executor
+   * instead of making direct API calls. This enables remote execution capabilities.
+   *
+   * @example
+   * ```typescript
+   * import { LocalExecutor, RemoteExecutor } from '@robota-sdk/agent-core';
+   *
+   * // Local execution (registers this provider)
+   * const localExecutor = new LocalExecutor();
+   * localExecutor.registerProvider('openai', new OpenAIProvider({ apiKey: 'sk-...' }));
+   *
+   * // Remote execution
+   * const remoteExecutor = new RemoteExecutor({
+   *   serverUrl: 'https://api.robota.io',
+   *   userApiKey: 'user-token-123'
+   * });
+   *
+   * const provider = new OpenAIProvider({
+   *   executor: remoteExecutor // No direct API key needed
+   * });
+   * ```
+   */
+  executor?: IExecutor;
+
+  /**
+   * Logger instance for internal OpenAI provider logging
+   * @defaultValue SilentLogger
+   */
+  logger?: ILogger;
+}

package/src/qwen/defaults.ts

@@ -0,0 +1,26 @@
+export const QWEN_PROVIDER_BASE_URLS = {
+  singapore: 'https://dashscope-intl.aliyuncs.com/compatible-mode/v1',
+  usVirginia: 'https://dashscope-us.aliyuncs.com/compatible-mode/v1',
+  beijing: 'https://dashscope.aliyuncs.com/compatible-mode/v1',
+  hongKong: 'https://cn-hongkong.dashscope.aliyuncs.com/compatible-mode/v1',
+} as const;
+
+export type TQwenProviderRegion = keyof typeof QWEN_PROVIDER_BASE_URLS;
+
+export const QWEN_PROVIDER_RESPONSES_BASE_URLS = {
+  singapore: 'https://dashscope-intl.aliyuncs.com/api/v2/apps/protocols/compatible-mode/v1',
+  usVirginia: 'https://dashscope-us.aliyuncs.com/api/v2/apps/protocols/compatible-mode/v1',
+  beijing: 'https://dashscope.aliyuncs.com/api/v2/apps/protocols/compatible-mode/v1',
+} as const;
+
+export type TQwenProviderResponsesRegion = keyof typeof QWEN_PROVIDER_RESPONSES_BASE_URLS;
+
+export const DEFAULT_QWEN_PROVIDER_MODEL = 'qwen-plus';
+export const DEFAULT_QWEN_PROVIDER_API_KEY_ENV = 'DASHSCOPE_API_KEY';
+export const DEFAULT_QWEN_PROVIDER_API_KEY_REFERENCE = `$ENV:${DEFAULT_QWEN_PROVIDER_API_KEY_ENV}`;
+export const DEFAULT_QWEN_PROVIDER_BASE_URL = QWEN_PROVIDER_BASE_URLS.singapore;
+export const DEFAULT_QWEN_PROVIDER_RESPONSES_BASE_URL = QWEN_PROVIDER_RESPONSES_BASE_URLS.singapore;
+
+export const QWEN_MODEL_SOURCE_URL =
+  'https://www.alibabacloud.com/help/en/model-studio/compatibility-of-openai-with-dashscope';
+export const QWEN_MODEL_LAST_VERIFIED_AT = '2026-05-04';

package/src/qwen/index.ts

@@ -0,0 +1,5 @@
+export * from './defaults';
+export * from './types';
+export * from './provider';
+export * from './provider-definition';
+export * from './model-catalog-refresh';

package/src/qwen/model-catalog-refresh.test.ts

@@ -0,0 +1,91 @@
+import { describe, expect, it, vi } from 'vitest';
+import { refreshQwenModelCatalog } from './model-catalog-refresh';
+
+describe('refreshQwenModelCatalog', () => {
+  it('maps the live Qwen /models response into provider model catalog entries', async () => {
+    const fetcher = vi.fn(async () => ({
+      ok: true,
+      status: 200,
+      json: async () => ({
+        data: [
+          { id: 'qwen-plus', object: 'model', owned_by: 'alibaba-cloud' },
+          { id: 'qwen-max', object: 'model', owned_by: 'alibaba-cloud' },
+          { id: 'qwen-turbo', object: 'model', owned_by: 'alibaba-cloud' },
+        ],
+      }),
+    }));
+
+    const catalog = await refreshQwenModelCatalog(
+      {
+        baseURL: 'https://dashscope-intl.aliyuncs.com/compatible-mode/v1/',
+        apiKey: 'test-api-key',
+      },
+      fetcher,
+    );
+
+    expect(fetcher).toHaveBeenCalledWith(
+      'https://dashscope-intl.aliyuncs.com/compatible-mode/v1/models',
+      {
+        headers: {
+          Authorization: 'Bearer test-api-key',
+        },
+      },
+    );
+    expect(catalog.status).toBe('live');
+    expect(catalog.entries?.map((entry) => entry.id)).toEqual([
+      'qwen-plus',
+      'qwen-max',
+      'qwen-turbo',
+    ]);
+    expect(catalog.entries?.[0]).toMatchObject({
+      id: 'qwen-plus',
+      displayName: 'qwen-plus',
+      lifecycle: 'active',
+    });
+  });
+
+  it('uses the default base URL when profile.baseURL is not set', async () => {
+    const fetcher = vi.fn(async () => ({
+      ok: true,
+      status: 200,
+      json: async () => ({ data: [{ id: 'qwen-flash' }] }),
+    }));
+
+    await refreshQwenModelCatalog({ apiKey: 'test-key' }, fetcher);
+
+    expect(fetcher).toHaveBeenCalledWith(
+      'https://dashscope-intl.aliyuncs.com/compatible-mode/v1/models',
+      expect.anything(),
+    );
+  });
+
+  it('omits Authorization header when no apiKey is provided', async () => {
+    const fetcher = vi.fn(async () => ({
+      ok: true,
+      status: 200,
+      json: async () => ({ data: [] }),
+    }));
+
+    await refreshQwenModelCatalog({}, fetcher);
+
+    expect(fetcher).toHaveBeenCalledWith(
+      'https://dashscope-intl.aliyuncs.com/compatible-mode/v1/models',
+      undefined,
+    );
+  });
+
+  it('returns an unavailable catalog when the live model refresh fails', async () => {
+    const fetcher = vi.fn(async () => ({
+      ok: false,
+      status: 401,
+      json: async () => ({ data: [] }),
+    }));
+
+    const catalog = await refreshQwenModelCatalog({}, fetcher);
+
+    expect(catalog).toMatchObject({
+      status: 'unavailable',
+      message: 'Qwen model refresh failed: HTTP 401',
+    });
+  });
+});

package/src/qwen/model-catalog-refresh.ts

@@ -0,0 +1,97 @@
+import type {
+  IProviderModelCatalog,
+  IProviderModelCatalogEntry,
+  IProviderProfileConfig,
+} from '@robota-sdk/agent-core';
+import {
+  DEFAULT_QWEN_PROVIDER_BASE_URL,
+  QWEN_MODEL_LAST_VERIFIED_AT,
+  QWEN_MODEL_SOURCE_URL,
+} from './defaults';
+
+export interface IQwenModelsResponse {
+  data?: Array<{
+    id?: string;
+    object?: string;
+    owned_by?: string;
+  }>;
+}
+
+export interface IQwenFetchInit {
+  headers?: Record<string, string>;
+}
+
+export interface IQwenFetchResponse {
+  ok: boolean;
+  status: number;
+  json: () => Promise<IQwenModelsResponse>;
+}
+
+export type TQwenFetch = (url: string, init?: IQwenFetchInit) => Promise<IQwenFetchResponse>;
+
+export async function refreshQwenModelCatalog(
+  profile: IProviderProfileConfig,
+  fetcher: TQwenFetch = defaultQwenFetch,
+): Promise<IProviderModelCatalog> {
+  const baseURL = trimTrailingSlash(profile.baseURL ?? DEFAULT_QWEN_PROVIDER_BASE_URL);
+  const url = `${baseURL}/models`;
+  const response = await fetcher(url, buildFetchInit(profile.apiKey));
+
+  if (!response.ok) {
+    return {
+      status: 'unavailable',
+      sourceUrl: QWEN_MODEL_SOURCE_URL,
+      message: `Qwen model refresh failed: HTTP ${response.status}`,
+    };
+  }
+
+  const body = await response.json();
+  const entries = (body.data ?? [])
+    .map((model) => model.id)
+    .filter((id): id is string => typeof id === 'string' && id.length > 0)
+    .map(toModelCatalogEntry);
+
+  return {
+    status: 'live',
+    sourceUrl: QWEN_MODEL_SOURCE_URL,
+    lastVerifiedAt: QWEN_MODEL_LAST_VERIFIED_AT,
+    entries,
+    message: `Loaded ${entries.length} models from Qwen API`,
+  };
+}
+
+function buildFetchInit(apiKey: string | undefined): IQwenFetchInit | undefined {
+  if (!apiKey) {
+    return undefined;
+  }
+  return {
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+    },
+  };
+}
+
+function toModelCatalogEntry(id: string): IProviderModelCatalogEntry {
+  return {
+    id,
+    displayName: id,
+    lifecycle: 'active',
+    sourceUrl: QWEN_MODEL_SOURCE_URL,
+    lastVerifiedAt: QWEN_MODEL_LAST_VERIFIED_AT,
+  };
+}
+
+function trimTrailingSlash(value: string): string {
+  return value.replace(/\/$/, '');
+}
+
+async function defaultQwenFetch(url: string, init?: IQwenFetchInit): Promise<IQwenFetchResponse> {
+  const response = await fetch(url, {
+    ...(init?.headers !== undefined && { headers: init.headers }),
+  });
+  return {
+    ok: response.ok,
+    status: response.status,
+    json: () => response.json() as Promise<IQwenModelsResponse>,
+  };
+}

package/src/qwen/provider-capabilities.ts

@@ -0,0 +1,34 @@
+import type { IProviderCapabilities } from '@robota-sdk/agent-core';
+import type { IQwenProviderOptions } from './types';
+
+const QWEN_RESPONSES_SOURCE = 'qwen-responses';
+const ENABLE_WEB_SEARCH_REASON = 'Enable builtInWebTools.webSearch or builtInWebTools.webFetch.';
+const ENABLE_WEB_FETCH_REASON = 'Enable builtInWebTools.webFetch.';
+
+export function getQwenProviderCapabilities(options: IQwenProviderOptions): IProviderCapabilities {
+  const webTools = options.builtInWebTools;
+  const webSearchEnabled = webTools?.webSearch === true || webTools?.webFetch === true;
+  const webFetchEnabled = webTools?.webFetch === true;
+
+  return {
+    functionCalling: { supported: true },
+    nativeWebTools: {
+      webSearch: webSearchEnabled
+        ? { supported: true, enabled: true, source: QWEN_RESPONSES_SOURCE }
+        : {
+            supported: true,
+            enabled: false,
+            source: QWEN_RESPONSES_SOURCE,
+            reason: ENABLE_WEB_SEARCH_REASON,
+          },
+      webFetch: webFetchEnabled
+        ? { supported: true, enabled: true, source: QWEN_RESPONSES_SOURCE }
+        : {
+            supported: true,
+            enabled: false,
+            source: QWEN_RESPONSES_SOURCE,
+            reason: ENABLE_WEB_FETCH_REASON,
+          },
+    },
+  };
+}

package/src/qwen/provider-definition.test.ts

@@ -0,0 +1,139 @@
+import { describe, expect, it, vi, beforeEach } from 'vitest';
+import {
+  createQwenProviderDefinition,
+  DEFAULT_QWEN_PROVIDER_API_KEY_ENV,
+  DEFAULT_QWEN_PROVIDER_API_KEY_REFERENCE,
+  DEFAULT_QWEN_PROVIDER_BASE_URL,
+  DEFAULT_QWEN_PROVIDER_MODEL,
+  DEFAULT_QWEN_PROVIDER_RESPONSES_BASE_URL,
+  QWEN_PROVIDER_BASE_URLS,
+  QWEN_PROVIDER_RESPONSES_BASE_URLS,
+  QwenProvider,
+} from './index';
+
+vi.mock('openai', () => {
+  const MockOpenAI = vi.fn().mockImplementation(() => ({
+    chat: {
+      completions: {
+        create: vi.fn(),
+      },
+    },
+    responses: {
+      create: vi.fn(),
+    },
+  }));
+  return { default: MockOpenAI };
+});
+
+describe('createQwenProviderDefinition', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('exposes Qwen defaults and setup steps through the provider-definition contract', () => {
+    const definition = createQwenProviderDefinition();
+
+    expect(definition.type).toBe('qwen');
+    expect(definition.requiresApiKey).toBe(true);
+    expect(definition.probeProfile).toBeTypeOf('function');
+    expect(definition.defaults).toEqual({
+      model: DEFAULT_QWEN_PROVIDER_MODEL,
+      apiKey: DEFAULT_QWEN_PROVIDER_API_KEY_REFERENCE,
+      baseURL: DEFAULT_QWEN_PROVIDER_BASE_URL,
+    });
+    expect(definition.setupHelpLinks).toEqual([
+      {
+        kind: 'api-key',
+        label: 'Alibaba Cloud Model Studio API keys',
+        url: 'https://modelstudio.console.alibabacloud.com/?tab=api#/api-key',
+        sourceUrl: 'https://www.alibabacloud.com/help/en/model-studio/get-api-key',
+        lastVerifiedAt: '2026-05-08',
+      },
+    ]);
+    expect(DEFAULT_QWEN_PROVIDER_API_KEY_ENV).toBe('DASHSCOPE_API_KEY');
+    expect(QWEN_PROVIDER_BASE_URLS).toMatchObject({
+      singapore: 'https://dashscope-intl.aliyuncs.com/compatible-mode/v1',
+      usVirginia: 'https://dashscope-us.aliyuncs.com/compatible-mode/v1',
+      beijing: 'https://dashscope.aliyuncs.com/compatible-mode/v1',
+      hongKong: 'https://cn-hongkong.dashscope.aliyuncs.com/compatible-mode/v1',
+    });
+    expect(DEFAULT_QWEN_PROVIDER_RESPONSES_BASE_URL).toBe(
+      'https://dashscope-intl.aliyuncs.com/api/v2/apps/protocols/compatible-mode/v1',
+    );
+    expect(QWEN_PROVIDER_RESPONSES_BASE_URLS).toMatchObject({
+      singapore: 'https://dashscope-intl.aliyuncs.com/api/v2/apps/protocols/compatible-mode/v1',
+      usVirginia: 'https://dashscope-us.aliyuncs.com/api/v2/apps/protocols/compatible-mode/v1',
+      beijing: 'https://dashscope.aliyuncs.com/api/v2/apps/protocols/compatible-mode/v1',
+    });
+    expect(definition.setupSteps).toEqual([
+      {
+        key: 'baseURL',
+        title: 'Qwen OpenAI-compatible base URL',
+        defaultValue: DEFAULT_QWEN_PROVIDER_BASE_URL,
+      },
+      {
+        key: 'model',
+        title: 'Qwen model',
+        defaultValue: DEFAULT_QWEN_PROVIDER_MODEL,
+      },
+      {
+        key: 'apiKey',
+        title: 'Qwen Model Studio API key',
+        defaultValue: DEFAULT_QWEN_PROVIDER_API_KEY_REFERENCE,
+        masked: true,
+      },
+    ]);
+  });
+
+  it('creates a QwenProvider from a resolved provider profile', () => {
+    const definition = createQwenProviderDefinition();
+
+    const provider = definition.createProvider({
+      name: 'qwen',
+      model: 'qwen-plus',
+      apiKey: 'dashscope-key',
+      baseURL: QWEN_PROVIDER_BASE_URLS.usVirginia,
+      timeout: 12_000,
+    });
+
+    expect(provider).toBeInstanceOf(QwenProvider);
+    expect(provider.name).toBe('qwen');
+  });
+
+  it('passes Qwen-owned Responses API options from the generic provider options bag', () => {
+    const definition = createQwenProviderDefinition();
+
+    const provider = definition.createProvider({
+      name: 'qwen',
+      model: 'qwen3.6-plus',
+      apiKey: 'dashscope-key',
+      options: {
+        responsesBaseURL: QWEN_PROVIDER_RESPONSES_BASE_URLS.usVirginia,
+        builtInWebTools: {
+          webSearch: true,
+          webFetch: true,
+          enableThinking: true,
+        },
+      },
+    });
+
+    const options = (provider as unknown as { options: Record<string, unknown> }).options;
+    expect(options['responsesBaseURL']).toBe(QWEN_PROVIDER_RESPONSES_BASE_URLS.usVirginia);
+    expect(options['builtInWebTools']).toEqual({
+      webSearch: true,
+      webFetch: true,
+      enableThinking: true,
+    });
+  });
+
+  it('rejects provider creation without an API key', () => {
+    const definition = createQwenProviderDefinition();
+
+    expect(() =>
+      definition.createProvider({
+        name: 'qwen',
+        model: 'qwen-plus',
+      }),
+    ).toThrow('Provider qwen requires apiKey');
+  });
+});