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

package/src/qwen/responses-parser.ts

@@ -0,0 +1,299 @@
+import { randomUUID } from 'node:crypto';
+import type { IToolCall, TTextDeltaCallback, TUniversalMessage } from '@robota-sdk/agent-core';
+import type {
+  IQwenResponsesFunctionCallOutputItem,
+  IQwenResponsesErrorEvent,
+  IQwenResponsesResponse,
+  IQwenResponsesUsage,
+  TQwenBuiltInWebToolName,
+  TQwenResponsesOutputItem,
+  TQwenResponsesStreamEvent,
+} from './types';
+import { streamWithAbort } from './responses-stream-utils';
+
+interface IQwenResponsesParseOptions {
+  enabledBuiltInTools: readonly TQwenBuiltInWebToolName[];
+}
+
+interface IQwenResponsesStreamAssemblyOptions extends IQwenResponsesParseOptions {
+  stream: AsyncIterable<TQwenResponsesStreamEvent>;
+  onTextDelta?: TTextDeltaCallback;
+  signal?: AbortSignal;
+}
+
+interface IQwenProviderToolUsage {
+  webSearchCalls: number;
+  webExtractorCalls: number;
+  unsupportedToolTypes: Set<string>;
+}
+
+interface IQwenResponsesStreamState {
+  textParts: string[];
+  toolCalls: IToolCall[];
+  completedResponse?: IQwenResponsesResponse;
+  usage: IQwenProviderToolUsage;
+}
+
+export function parseQwenResponsesResponse(
+  response: IQwenResponsesResponse,
+  options: IQwenResponsesParseOptions,
+): TUniversalMessage {
+  const output = response.output ?? [];
+  const usage = collectProviderToolUsage(output, response.usage);
+  const toolCalls = extractFunctionToolCalls(output);
+  const content = response.output_text ?? extractMessageText(output);
+
+  return buildAssistantMessage({
+    content,
+    toolCalls,
+    response,
+    usage,
+    enabledBuiltInTools: options.enabledBuiltInTools,
+  });
+}
+
+export async function assembleQwenResponsesStream(
+  options: IQwenResponsesStreamAssemblyOptions,
+): Promise<TUniversalMessage> {
+  const state: IQwenResponsesStreamState = {
+    textParts: [],
+    toolCalls: [],
+    usage: createEmptyToolUsage(),
+  };
+
+  for await (const event of streamWithAbort(options.stream, options.signal)) {
+    applyStreamEvent(state, event, options.onTextDelta);
+  }
+
+  if (state.completedResponse !== undefined) {
+    return buildMessageFromCompletedResponse(state, options.enabledBuiltInTools);
+  }
+
+  return buildAssistantMessage({
+    content: state.textParts.join(''),
+    toolCalls: state.toolCalls,
+    usage: state.usage,
+    enabledBuiltInTools: options.enabledBuiltInTools,
+  });
+}
+
+function applyStreamEvent(
+  state: IQwenResponsesStreamState,
+  event: TQwenResponsesStreamEvent,
+  onTextDelta: TTextDeltaCallback | undefined,
+): void {
+  if (event.type === 'response.output_text.delta') {
+    state.textParts.push(event.delta);
+    onTextDelta?.(event.delta);
+    return;
+  }
+
+  if (event.type === 'response.completed') {
+    state.completedResponse = event.response;
+    mergeToolUsage(
+      state.usage,
+      collectProviderToolUsage(event.response.output ?? [], event.response.usage),
+    );
+    return;
+  }
+
+  if (event.type === 'response.output_item.done') {
+    applyOutputItem(state, event.item);
+    return;
+  }
+
+  if (event.type === 'response.web_search_call.completed') {
+    state.usage.webSearchCalls += 1;
+    return;
+  }
+
+  if (event.type === 'response.error' || event.type === 'response.failed') {
+    throw new Error(`Qwen Responses API failed: ${extractErrorMessage(event)}`);
+  }
+}
+
+function buildMessageFromCompletedResponse(
+  state: IQwenResponsesStreamState,
+  enabledBuiltInTools: readonly TQwenBuiltInWebToolName[],
+): TUniversalMessage {
+  const response = state.completedResponse;
+  if (response === undefined) {
+    throw new Error('Qwen Responses stream completed without response metadata');
+  }
+
+  const output = response.output ?? [];
+  const responseToolCalls = extractFunctionToolCalls(output);
+  const content =
+    state.textParts.length > 0
+      ? state.textParts.join('')
+      : (response.output_text ?? extractMessageText(output));
+  const usage = collectProviderToolUsage(output, response.usage);
+  mergeToolUsage(usage, state.usage);
+
+  return buildAssistantMessage({
+    content,
+    toolCalls: responseToolCalls.length > 0 ? responseToolCalls : state.toolCalls,
+    response,
+    usage,
+    enabledBuiltInTools,
+  });
+}
+
+function applyOutputItem(state: IQwenResponsesStreamState, item: TQwenResponsesOutputItem): void {
+  if (item.type === 'function_call') {
+    if (isFunctionCallOutputItem(item)) {
+      state.toolCalls.push(convertFunctionCall(item));
+    }
+    return;
+  }
+  mergeToolUsage(state.usage, collectProviderToolUsage([item], undefined));
+}
+
+function buildAssistantMessage(input: {
+  content: string;
+  toolCalls: IToolCall[];
+  response?: IQwenResponsesResponse;
+  usage: IQwenProviderToolUsage;
+  enabledBuiltInTools: readonly TQwenBuiltInWebToolName[];
+}): TUniversalMessage {
+  return {
+    id: randomUUID(),
+    role: 'assistant',
+    content: input.content,
+    state: 'complete',
+    timestamp: new Date(),
+    ...(input.toolCalls.length > 0 && { toolCalls: input.toolCalls }),
+    ...(input.response?.usage !== undefined && {
+      usage: {
+        promptTokens: input.response.usage.input_tokens ?? 0,
+        completionTokens: input.response.usage.output_tokens ?? 0,
+        totalTokens: input.response.usage.total_tokens ?? 0,
+      },
+    }),
+    metadata: buildProviderToolMetadata(input.enabledBuiltInTools, input.usage, input.response),
+  };
+}
+
+function buildProviderToolMetadata(
+  enabledBuiltInTools: readonly TQwenBuiltInWebToolName[],
+  usage: IQwenProviderToolUsage,
+  response: IQwenResponsesResponse | undefined,
+): NonNullable<TUniversalMessage['metadata']> {
+  const usedTools = collectUsedToolNames(usage);
+  return {
+    providerToolMode: 'qwen_responses',
+    providerBuiltInToolsEnabled: [...enabledBuiltInTools],
+    ...(usedTools.length > 0 && { providerBuiltInToolsUsed: usedTools }),
+    qwenWebSearchCalls: usage.webSearchCalls,
+    qwenWebExtractorCalls: usage.webExtractorCalls,
+    ...(usage.unsupportedToolTypes.size > 0 && {
+      qwenUnsupportedProviderToolTypes: [...usage.unsupportedToolTypes].sort(),
+    }),
+    ...(response?.id !== undefined && { responseId: response.id }),
+    ...(response?.model !== undefined && { model: response.model }),
+    ...(response?.status !== undefined && { finishReason: response.status }),
+  };
+}
+
+function collectUsedToolNames(usage: IQwenProviderToolUsage): TQwenBuiltInWebToolName[] {
+  const used: TQwenBuiltInWebToolName[] = [];
+  if (usage.webSearchCalls > 0) {
+    used.push('web_search');
+  }
+  if (usage.webExtractorCalls > 0) {
+    used.push('web_extractor');
+  }
+  return used;
+}
+
+function collectProviderToolUsage(
+  output: readonly TQwenResponsesOutputItem[],
+  responseUsage: IQwenResponsesUsage | undefined,
+): IQwenProviderToolUsage {
+  const usage = createEmptyToolUsage();
+  for (const item of output) {
+    if (item.type === 'web_search_call') {
+      usage.webSearchCalls += 1;
+    } else if (item.type === 'web_extractor_call') {
+      usage.webExtractorCalls += 1;
+    } else if (isProviderToolOutput(item.type)) {
+      usage.unsupportedToolTypes.add(item.type);
+    }
+  }
+  applyUsageCounts(usage, responseUsage);
+  return usage;
+}
+
+function applyUsageCounts(
+  usage: IQwenProviderToolUsage,
+  responseUsage: IQwenResponsesUsage | undefined,
+): void {
+  const xTools = responseUsage?.x_tools;
+  if (xTools === undefined) {
+    return;
+  }
+  usage.webSearchCalls = Math.max(usage.webSearchCalls, xTools['web_search']?.count ?? 0);
+  usage.webExtractorCalls = Math.max(usage.webExtractorCalls, xTools['web_extractor']?.count ?? 0);
+  for (const toolName of Object.keys(xTools)) {
+    if (toolName !== 'web_search' && toolName !== 'web_extractor') {
+      usage.unsupportedToolTypes.add(toolName);
+    }
+  }
+}
+
+function mergeToolUsage(target: IQwenProviderToolUsage, source: IQwenProviderToolUsage): void {
+  target.webSearchCalls = Math.max(target.webSearchCalls, source.webSearchCalls);
+  target.webExtractorCalls = Math.max(target.webExtractorCalls, source.webExtractorCalls);
+  for (const toolType of source.unsupportedToolTypes) {
+    target.unsupportedToolTypes.add(toolType);
+  }
+}
+
+function createEmptyToolUsage(): IQwenProviderToolUsage {
+  return {
+    webSearchCalls: 0,
+    webExtractorCalls: 0,
+    unsupportedToolTypes: new Set(),
+  };
+}
+
+function isProviderToolOutput(type: string): boolean {
+  return type.endsWith('_call') && type !== 'function_call';
+}
+
+function extractFunctionToolCalls(output: readonly TQwenResponsesOutputItem[]): IToolCall[] {
+  return output.filter(isFunctionCallOutputItem).map((item) => convertFunctionCall(item));
+}
+
+function isFunctionCallOutputItem(
+  item: TQwenResponsesOutputItem,
+): item is IQwenResponsesFunctionCallOutputItem {
+  return (
+    item.type === 'function_call' && 'call_id' in item && 'name' in item && 'arguments' in item
+  );
+}
+
+function convertFunctionCall(item: IQwenResponsesFunctionCallOutputItem): IToolCall {
+  return {
+    id: item.call_id,
+    type: 'function',
+    function: {
+      name: item.name,
+      arguments: item.arguments,
+    },
+  };
+}
+
+function extractMessageText(output: readonly TQwenResponsesOutputItem[]): string {
+  return output
+    .filter((item): item is Extract<TQwenResponsesOutputItem, { type: 'message' }> => {
+      return item.type === 'message';
+    })
+    .flatMap((item) => item.content)
+    .map((part) => part.text)
+    .join('');
+}
+
+function extractErrorMessage(event: IQwenResponsesErrorEvent): string {
+  return event.message ?? event.error?.message ?? event.response?.error?.message ?? 'unknown error';
+}

package/src/qwen/responses-stream-utils.ts

@@ -0,0 +1,38 @@
+export async function* streamWithAbort<T>(
+  source: AsyncIterable<T>,
+  signal?: AbortSignal,
+): AsyncGenerator<T> {
+  const iterator = source[Symbol.asyncIterator]();
+  try {
+    while (!signal?.aborted) {
+      const item = await nextStreamItem(iterator, signal);
+      if (item.done) break;
+      if (signal?.aborted) break;
+      yield item.value;
+    }
+  } finally {
+    if (signal?.aborted) {
+      await iterator.return?.();
+    }
+  }
+}
+
+async function nextStreamItem<T>(
+  iterator: AsyncIterator<T>,
+  signal?: AbortSignal,
+): Promise<IteratorResult<T>> {
+  if (!signal) return iterator.next();
+  if (signal.aborted) return { done: true, value: undefined as T };
+
+  let abortListener: (() => void) | undefined;
+  const aborted = new Promise<IteratorResult<T>>((resolve) => {
+    abortListener = (): void => resolve({ done: true, value: undefined as T });
+    signal.addEventListener('abort', abortListener, { once: true });
+  });
+
+  try {
+    return await Promise.race([iterator.next(), aborted]);
+  } finally {
+    if (abortListener) signal.removeEventListener('abort', abortListener);
+  }
+}

package/src/qwen/types.ts

@@ -0,0 +1,228 @@
+import type OpenAI from 'openai';
+import type {
+  IExecutor,
+  ILogger,
+  IToolSchema,
+  TProviderOptionValueBase,
+  TUniversalMessage,
+} from '@robota-sdk/agent-core';
+
+export type TQwenBuiltInWebToolName = 'web_search' | 'web_extractor';
+
+export interface IQwenBuiltInWebToolsOptions {
+  webSearch?: boolean;
+  webFetch?: boolean;
+  enableThinking?: boolean;
+}
+
+export interface IQwenResponsesWebSearchTool {
+  type: 'web_search';
+}
+
+export interface IQwenResponsesWebExtractorTool {
+  type: 'web_extractor';
+}
+
+export interface IQwenResponsesFunctionTool {
+  type: 'function';
+  name: string;
+  description?: string;
+  parameters: IToolSchema['parameters'];
+}
+
+export type TQwenResponsesTool =
+  | IQwenResponsesWebSearchTool
+  | IQwenResponsesWebExtractorTool
+  | IQwenResponsesFunctionTool;
+
+export interface IQwenResponsesMessageInput {
+  type?: 'message';
+  role: 'user' | 'assistant' | 'system' | 'developer';
+  content: string;
+}
+
+export interface IQwenResponsesFunctionCallInput {
+  type: 'function_call';
+  call_id: string;
+  name: string;
+  arguments: string;
+}
+
+export interface IQwenResponsesFunctionCallOutputInput {
+  type: 'function_call_output';
+  call_id: string;
+  output: string;
+}
+
+export type TQwenResponsesInputItem =
+  | IQwenResponsesMessageInput
+  | IQwenResponsesFunctionCallInput
+  | IQwenResponsesFunctionCallOutputInput;
+
+export interface IQwenResponsesRequestBase {
+  model: string;
+  input: TQwenResponsesInputItem[];
+  tools?: TQwenResponsesTool[];
+  temperature?: number;
+  max_output_tokens?: number;
+  enable_thinking?: boolean;
+}
+
+export interface IQwenResponsesRequestNonStreaming extends IQwenResponsesRequestBase {
+  stream?: false;
+}
+
+export interface IQwenResponsesRequestStreaming extends IQwenResponsesRequestBase {
+  stream: true;
+}
+
+export interface IQwenResponsesTextContent {
+  type: 'output_text' | 'text' | 'input_text';
+  text: string;
+}
+
+export interface IQwenResponsesMessageOutputItem {
+  type: 'message';
+  content: IQwenResponsesTextContent[];
+}
+
+export interface IQwenResponsesFunctionCallOutputItem {
+  type: 'function_call';
+  call_id: string;
+  name: string;
+  arguments: string;
+  id?: string;
+  status?: string;
+}
+
+export interface IQwenResponsesWebSearchAction {
+  query?: string;
+}
+
+export interface IQwenResponsesWebSearchOutputItem {
+  type: 'web_search_call';
+  id?: string;
+  status?: string;
+  action?: IQwenResponsesWebSearchAction;
+}
+
+export interface IQwenResponsesWebExtractorOutputItem {
+  type: 'web_extractor_call';
+  id?: string;
+  status?: string;
+  goal?: string;
+  output?: string;
+}
+
+export interface IQwenResponsesGenericOutputItem {
+  type: string;
+  id?: string;
+  status?: string;
+}
+
+export type TQwenResponsesOutputItem =
+  | IQwenResponsesMessageOutputItem
+  | IQwenResponsesFunctionCallOutputItem
+  | IQwenResponsesWebSearchOutputItem
+  | IQwenResponsesWebExtractorOutputItem
+  | IQwenResponsesGenericOutputItem;
+
+export interface IQwenResponsesToolUsageCount {
+  count?: number;
+}
+
+export interface IQwenResponsesUsage {
+  input_tokens?: number;
+  output_tokens?: number;
+  total_tokens?: number;
+  x_tools?: Record<string, IQwenResponsesToolUsageCount>;
+}
+
+export interface IQwenResponsesResponse {
+  id?: string;
+  model?: string;
+  output_text?: string;
+  output?: TQwenResponsesOutputItem[];
+  usage?: IQwenResponsesUsage;
+  status?: string;
+}
+
+export interface IQwenResponsesTextDeltaEvent {
+  type: 'response.output_text.delta';
+  delta: string;
+}
+
+export interface IQwenResponsesCompletedEvent {
+  type: 'response.completed';
+  response: IQwenResponsesResponse;
+}
+
+export interface IQwenResponsesOutputItemDoneEvent {
+  type: 'response.output_item.done';
+  item: TQwenResponsesOutputItem;
+}
+
+export interface IQwenResponsesErrorEvent {
+  type: 'response.error' | 'response.failed';
+  message?: string;
+  error?: {
+    message?: string;
+  };
+  response?: {
+    error?: {
+      message?: string;
+    };
+  };
+}
+
+export interface IQwenResponsesWebSearchEvent {
+  type:
+    | 'response.web_search_call.in_progress'
+    | 'response.web_search_call.searching'
+    | 'response.web_search_call.completed';
+}
+
+export interface IQwenResponsesGenericEvent {
+  type: string;
+  item?: TQwenResponsesOutputItem;
+  response?: IQwenResponsesResponse;
+}
+
+export type TQwenResponsesStreamEvent =
+  | IQwenResponsesTextDeltaEvent
+  | IQwenResponsesCompletedEvent
+  | IQwenResponsesOutputItemDoneEvent
+  | IQwenResponsesErrorEvent
+  | IQwenResponsesWebSearchEvent;
+
+export type TQwenMessagesToResponsesInput = (
+  messages: TUniversalMessage[],
+) => TQwenResponsesInputItem[];
+
+export type TQwenProviderOptionValue =
+  | string
+  | number
+  | boolean
+  | undefined
+  | null
+  | IQwenBuiltInWebToolsOptions
+  | OpenAI
+  | ILogger
+  | IExecutor
+  | TProviderOptionValueBase
+  | TQwenProviderOptionValue[]
+  | { [key: string]: TQwenProviderOptionValue };
+
+export interface IQwenProviderOptions {
+  [key: string]: TQwenProviderOptionValue;
+
+  apiKey?: string;
+  baseURL?: string;
+  responsesBaseURL?: string;
+  timeout?: number;
+  defaultModel?: string;
+  builtInWebTools?: IQwenBuiltInWebToolsOptions;
+  client?: OpenAI;
+  executor?: IExecutor;
+  logger?: ILogger;
+}

package/src/shared/openai-compatible/endpoint-probe.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, it } from 'vitest';
+import { probeOpenAICompatibleProfile, type TOpenAICompatibleFetch } from './endpoint-probe';
+
+describe('probeOpenAICompatibleProfile', () => {
+  it('should skip endpoint calls when baseURL is missing', async () => {
+    const result = await probeOpenAICompatibleProfile({});
+
+    expect(result).toEqual({
+      ok: true,
+      message: 'Profile fields are valid; no endpoint probe configured.',
+    });
+  });
+
+  it('should fetch models from the OpenAI-compatible models endpoint', async () => {
+    const requestedUrls: string[] = [];
+    const fetcher: TOpenAICompatibleFetch = async (url) => {
+      requestedUrls.push(url);
+      return {
+        ok: true,
+        status: 200,
+        json: async () => ({ data: [{ id: 'supergemma4' }, { id: undefined }] }),
+      };
+    };
+
+    const result = await probeOpenAICompatibleProfile(
+      { baseURL: 'http://localhost:1234/v1/' },
+      fetcher,
+    );
+
+    expect(requestedUrls).toEqual(['http://localhost:1234/v1/models']);
+    expect(result).toEqual({
+      ok: true,
+      message: '1 model(s) discovered',
+      models: ['supergemma4'],
+    });
+  });
+
+  it('should return HTTP failure status', async () => {
+    const fetcher: TOpenAICompatibleFetch = async () => ({
+      ok: false,
+      status: 503,
+      json: async () => ({}),
+    });
+
+    const result = await probeOpenAICompatibleProfile(
+      { baseURL: 'http://localhost:1234/v1' },
+      fetcher,
+    );
+
+    expect(result).toEqual({ ok: false, message: 'HTTP 503' });
+  });
+});

package/src/shared/openai-compatible/endpoint-probe.ts

@@ -0,0 +1,43 @@
+import type { IProviderProfileConfig, IProviderProbeResult } from '@robota-sdk/agent-core';
+
+export interface IOpenAICompatibleModelsResponse {
+  data?: Array<{ id?: string }>;
+}
+
+export interface IOpenAICompatibleFetchResponse {
+  ok: boolean;
+  status: number;
+  json: () => Promise<IOpenAICompatibleModelsResponse>;
+}
+
+export type TOpenAICompatibleFetch = (url: string) => Promise<IOpenAICompatibleFetchResponse>;
+
+export async function probeOpenAICompatibleProfile(
+  profile: IProviderProfileConfig,
+  fetcher: TOpenAICompatibleFetch = defaultOpenAICompatibleFetch,
+): Promise<IProviderProbeResult> {
+  if (!profile.baseURL) {
+    return { ok: true, message: 'Profile fields are valid; no endpoint probe configured.' };
+  }
+
+  try {
+    const response = await fetcher(`${profile.baseURL.replace(/\/$/, '')}/models`);
+    if (!response.ok) {
+      return { ok: false, message: `HTTP ${response.status}` };
+    }
+    const body = await response.json();
+    const models = (body.data ?? []).map((item) => item.id).filter((id): id is string => !!id);
+    return { ok: true, message: `${models.length} model(s) discovered`, models };
+  } catch (error) {
+    return { ok: false, message: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+async function defaultOpenAICompatibleFetch(url: string): Promise<IOpenAICompatibleFetchResponse> {
+  const response = await fetch(url);
+  return {
+    ok: response.ok,
+    status: response.status,
+    json: () => response.json() as Promise<IOpenAICompatibleModelsResponse>,
+  };
+}

package/src/shared/openai-compatible/index.ts

@@ -0,0 +1,6 @@
+export * from './types';
+export * from './message-converter';
+export * from './response-parser';
+export * from './stream-assembler';
+export * from './native-payload-observer';
+export * from './endpoint-probe';