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

package/src/shared/openai-compatible/stream-assembler.test.ts

@@ -0,0 +1,266 @@
+import { describe, expect, it, vi } from 'vitest';
+import type OpenAI from 'openai';
+import { assembleOpenAICompatibleStream } from './index';
+
+async function* asyncIterableFrom<T>(items: T[]): AsyncIterable<T> {
+  for (const item of items) {
+    yield item;
+  }
+}
+
+function createHangingChunkStream(
+  onReturn: () => void,
+): AsyncIterable<OpenAI.Chat.ChatCompletionChunk> {
+  return {
+    [Symbol.asyncIterator](): AsyncIterator<OpenAI.Chat.ChatCompletionChunk> {
+      return {
+        next: () => new Promise<IteratorResult<OpenAI.Chat.ChatCompletionChunk>>(() => {}),
+        return: () => {
+          onReturn();
+          return Promise.resolve({
+            done: true,
+            value: createChunk(''),
+          });
+        },
+      };
+    },
+  };
+}
+
+function createChunk(
+  content: string,
+  finishReason: OpenAI.Chat.ChatCompletionChunk.Choice['finish_reason'] = null,
+): OpenAI.Chat.ChatCompletionChunk {
+  return {
+    id: 'chunk-1',
+    object: 'chat.completion.chunk',
+    created: 1,
+    model: 'local-model',
+    choices: [
+      {
+        index: 0,
+        delta: { content },
+        finish_reason: finishReason,
+        logprobs: null,
+      },
+    ],
+  };
+}
+
+describe('assembleOpenAICompatibleStream', () => {
+  it('assembles text deltas and emits projected text deltas', async () => {
+    const onTextDelta = vi.fn();
+    const projector = vi.fn((text: string) => text.replaceAll('[hidden]', ''));
+
+    const result = await assembleOpenAICompatibleStream({
+      stream: asyncIterableFrom([
+        createChunk('Hello '),
+        createChunk('[hidden]world'),
+        createChunk('', 'stop'),
+      ]),
+      onTextDelta,
+      textProjector: projector,
+    });
+
+    expect(result.role).toBe('assistant');
+    expect(result.content).toBe('Hello world');
+    expect(result.metadata?.['model']).toBe('local-model');
+    expect(result.metadata?.['finishReason']).toBe('stop');
+    expect(onTextDelta).toHaveBeenCalledTimes(2);
+    expect(onTextDelta).toHaveBeenNthCalledWith(1, 'Hello ');
+    expect(onTextDelta).toHaveBeenNthCalledWith(2, 'world');
+  });
+
+  it('assembles streamed tool call deltas by index', async () => {
+    const stream = asyncIterableFrom<OpenAI.Chat.ChatCompletionChunk>([
+      {
+        id: 'chunk-1',
+        object: 'chat.completion.chunk',
+        created: 1,
+        model: 'local-model',
+        choices: [
+          {
+            index: 0,
+            delta: {
+              tool_calls: [
+                {
+                  index: 0,
+                  id: 'call-1',
+                  type: 'function',
+                  function: { name: 'search', arguments: '{"q"' },
+                },
+              ],
+            },
+            finish_reason: null,
+            logprobs: null,
+          },
+        ],
+      },
+      {
+        id: 'chunk-2',
+        object: 'chat.completion.chunk',
+        created: 1,
+        model: 'local-model',
+        choices: [
+          {
+            index: 0,
+            delta: {
+              tool_calls: [
+                {
+                  index: 0,
+                  function: { arguments: ':"docs"}' },
+                },
+              ],
+            },
+            finish_reason: 'tool_calls',
+            logprobs: null,
+          },
+        ],
+      },
+    ]);
+
+    const result = await assembleOpenAICompatibleStream({ stream });
+
+    expect(result.role).toBe('assistant');
+    if (result.role !== 'assistant') throw new Error('Expected assistant message');
+    expect(result.toolCalls).toEqual([
+      {
+        id: 'call-1',
+        type: 'function',
+        function: { name: 'search', arguments: '{"q":"docs"}' },
+      },
+    ]);
+  });
+
+  it('passes streamed native tool calls through so core can return a normal tool-result error', async () => {
+    const stream = asyncIterableFrom<OpenAI.Chat.ChatCompletionChunk>([
+      {
+        id: 'chunk-1',
+        object: 'chat.completion.chunk',
+        created: 1,
+        model: 'local-model',
+        choices: [
+          {
+            index: 0,
+            delta: {
+              tool_calls: [
+                {
+                  index: 0,
+                  id: 'call-1',
+                  type: 'function',
+                  function: { name: 'UndeclaredTool', arguments: '{}' },
+                },
+              ],
+            },
+            finish_reason: 'tool_calls',
+            logprobs: null,
+          },
+        ],
+      },
+    ]);
+
+    const result = await assembleOpenAICompatibleStream({ stream });
+
+    if (result.role !== 'assistant') throw new Error('Expected assistant message');
+    expect(result.toolCalls).toEqual([
+      {
+        id: 'call-1',
+        type: 'function',
+        function: { name: 'UndeclaredTool', arguments: '{}' },
+      },
+    ]);
+  });
+
+  it('applies an injected provider-owned text tool-call projector before text deltas', async () => {
+    const onTextDelta = vi.fn();
+    const projector = {
+      project: vi.fn((delta: string) => {
+        if (delta === 'provider native payload') {
+          return {
+            visibleText: '',
+            toolCalls: [
+              {
+                id: 'projected-call-1',
+                type: 'function' as const,
+                function: { name: 'InjectedTool', arguments: '{"value":"ok"}' },
+              },
+            ],
+            removedToolCallText: true,
+            rawToolCallText: delta,
+          };
+        }
+
+        return {
+          visibleText: delta,
+          toolCalls: [],
+          removedToolCallText: false,
+        };
+      }),
+      flush: vi.fn(() => ({
+        visibleText: '',
+        toolCalls: [],
+        removedToolCallText: false,
+      })),
+    };
+
+    const result = await assembleOpenAICompatibleStream({
+      stream: asyncIterableFrom([
+        createChunk('provider native payload'),
+        createChunk('visible', 'tool_calls'),
+      ]),
+      onTextDelta,
+      toolCallTextProjector: projector,
+    });
+
+    expect(onTextDelta).toHaveBeenCalledOnce();
+    expect(onTextDelta).toHaveBeenCalledWith('visible');
+    expect(result.content).toBe('visible');
+    expect(result.metadata?.['toolCallTextProjected']).toBe(true);
+    expect(result.metadata?.['rawToolCallText']).toBe('provider native payload');
+    if (result.role !== 'assistant') throw new Error('Expected assistant message');
+    expect(result.toolCalls).toEqual([
+      {
+        id: 'projected-call-1',
+        type: 'function',
+        function: { name: 'InjectedTool', arguments: '{"value":"ok"}' },
+      },
+    ]);
+  });
+
+  it('flushes projector-held text after the stream ends', async () => {
+    const onTextDelta = vi.fn();
+
+    const result = await assembleOpenAICompatibleStream({
+      stream: asyncIterableFrom([createChunk('Visible'), createChunk('', 'stop')]),
+      onTextDelta,
+      textProjector: (text) => text.slice(0, -1),
+      textProjectorFlush: () => 'e',
+    });
+
+    expect(result.content).toBe('Visible');
+    expect(onTextDelta).toHaveBeenNthCalledWith(1, 'Visibl');
+    expect(onTextDelta).toHaveBeenNthCalledWith(2, 'e');
+  });
+
+  it('settles when aborted while awaiting the next stream chunk', async () => {
+    const controller = new AbortController();
+    let returned = false;
+    const resultPromise = assembleOpenAICompatibleStream({
+      stream: createHangingChunkStream(() => {
+        returned = true;
+      }),
+      signal: controller.signal,
+    });
+
+    setTimeout(() => controller.abort(), 0);
+    const result = await Promise.race([
+      resultPromise,
+      new Promise<never>((_resolve, reject) =>
+        setTimeout(() => reject(new Error('stream abort did not settle')), 100),
+      ),
+    ]);
+
+    expect(result.content).toBe('');
+    expect(returned).toBe(true);
+  });
+});

package/src/shared/openai-compatible/stream-assembler.ts

@@ -0,0 +1,248 @@
+import { randomUUID } from 'node:crypto';
+import type OpenAI from 'openai';
+import type { IToolCall, TUniversalMessage } from '@robota-sdk/agent-core';
+import type {
+  IOpenAICompatibleToolCallTextProjection,
+  IOpenAICompatibleStreamAssemblyOptions,
+  TOpenAICompatibleTextProjector,
+} from './types';
+
+interface IToolCallPart {
+  id: string;
+  name: string;
+  arguments: string;
+}
+
+interface IAssemblyState {
+  textParts: string[];
+  toolCallParts: Map<number, IToolCallPart>;
+  projectedToolCalls: IToolCall[];
+  rawToolCallTextParts: string[];
+  toolCallTextProjected: boolean;
+  model: string;
+  finishReason: string | null;
+}
+
+export async function assembleOpenAICompatibleStream(
+  options: IOpenAICompatibleStreamAssemblyOptions,
+): Promise<TUniversalMessage> {
+  const state: IAssemblyState = {
+    textParts: [],
+    toolCallParts: new Map(),
+    projectedToolCalls: [],
+    rawToolCallTextParts: [],
+    toolCallTextProjected: false,
+    model: '',
+    finishReason: null,
+  };
+
+  for await (const chunk of streamWithAbort(options.stream, options.signal)) {
+    applyChunk(state, chunk, options);
+  }
+  applyProjectedTextFlush(state, options);
+
+  return buildMessage(state, options.metadata);
+}
+
+function applyChunk(
+  state: IAssemblyState,
+  chunk: OpenAI.Chat.ChatCompletionChunk,
+  options: IOpenAICompatibleStreamAssemblyOptions,
+): void {
+  if (chunk.model) {
+    state.model = chunk.model;
+  }
+
+  const choice = chunk.choices?.[0];
+  if (!choice) {
+    return;
+  }
+
+  state.finishReason = choice.finish_reason ?? state.finishReason;
+  applyTextDelta(state, choice.delta.content, options);
+  applyToolCallDeltas(state, choice.delta.tool_calls ?? []);
+}
+
+function applyTextDelta(
+  state: IAssemblyState,
+  content: string | null | undefined,
+  options: IOpenAICompatibleStreamAssemblyOptions,
+): void {
+  if (!content) {
+    return;
+  }
+
+  const toolProjection = projectToolCallText(content, options.toolCallTextProjector);
+  applyToolCallTextProjection(state, toolProjection);
+  const visibleContent = projectText(toolProjection.visibleText, options.textProjector);
+  if (visibleContent.length === 0) {
+    return;
+  }
+
+  state.textParts.push(visibleContent);
+  options.onTextDelta?.(visibleContent);
+}
+
+function projectText(text: string, projector?: TOpenAICompatibleTextProjector): string {
+  return projector ? projector(text) : text;
+}
+
+function applyProjectedTextFlush(
+  state: IAssemblyState,
+  options: IOpenAICompatibleStreamAssemblyOptions,
+): void {
+  const toolProjection = options.toolCallTextProjector?.flush();
+  if (toolProjection) {
+    applyToolCallTextProjection(state, toolProjection);
+    const visibleToolText = projectText(toolProjection.visibleText, options.textProjector);
+    if (visibleToolText.length > 0) {
+      state.textParts.push(visibleToolText);
+      options.onTextDelta?.(visibleToolText);
+    }
+  }
+
+  const visibleContent = options.textProjectorFlush?.();
+  if (!visibleContent) {
+    return;
+  }
+
+  state.textParts.push(visibleContent);
+  options.onTextDelta?.(visibleContent);
+}
+
+function projectToolCallText(
+  text: string,
+  projector: IOpenAICompatibleStreamAssemblyOptions['toolCallTextProjector'],
+): IOpenAICompatibleToolCallTextProjection {
+  return (
+    projector?.project(text) ?? {
+      visibleText: text,
+      toolCalls: [],
+      removedToolCallText: false,
+    }
+  );
+}
+
+function applyToolCallTextProjection(
+  state: IAssemblyState,
+  projection: IOpenAICompatibleToolCallTextProjection,
+): void {
+  if (projection.toolCalls.length > 0) {
+    state.projectedToolCalls.push(...projection.toolCalls);
+  }
+  if (projection.removedToolCallText) {
+    state.toolCallTextProjected = true;
+  }
+  if (projection.rawToolCallText && projection.rawToolCallText.length > 0) {
+    state.rawToolCallTextParts.push(projection.rawToolCallText);
+  }
+}
+
+function applyToolCallDeltas(
+  state: IAssemblyState,
+  deltas: OpenAI.Chat.ChatCompletionChunk.Choice.Delta.ToolCall[],
+): void {
+  for (const delta of deltas) {
+    const index = delta.index ?? 0;
+    const current = state.toolCallParts.get(index) ?? { id: '', name: '', arguments: '' };
+    const nextName = delta.function?.name ?? current.name;
+    state.toolCallParts.set(index, {
+      id: delta.id ?? current.id,
+      name: nextName,
+      arguments: current.arguments + (delta.function?.arguments ?? ''),
+    });
+  }
+}
+
+function buildMessage(
+  state: IAssemblyState,
+  metadata: Record<string, string | number | boolean> = {},
+): TUniversalMessage {
+  const resultMetadata: NonNullable<TUniversalMessage['metadata']> = { ...metadata };
+  if (state.model) {
+    resultMetadata['model'] = state.model;
+  }
+  if (state.finishReason) {
+    resultMetadata['finishReason'] = state.finishReason;
+  }
+  if (state.toolCallTextProjected) {
+    resultMetadata['toolCallTextProjected'] = true;
+  }
+  if (state.rawToolCallTextParts.length > 0) {
+    resultMetadata['rawToolCallText'] = state.rawToolCallTextParts.join('');
+  }
+
+  const toolCalls = buildAllToolCalls(state);
+
+  return {
+    id: randomUUID(),
+    role: 'assistant',
+    content: state.textParts.join(''),
+    state: 'complete',
+    timestamp: new Date(),
+    ...(toolCalls.length > 0 && { toolCalls }),
+    ...(Object.keys(resultMetadata).length > 0 && { metadata: resultMetadata }),
+  };
+}
+
+function buildAllToolCalls(state: IAssemblyState): IToolCall[] {
+  return [...buildToolCalls(state.toolCallParts), ...state.projectedToolCalls];
+}
+
+function buildToolCalls(toolCallParts: Map<number, IToolCallPart>): IToolCall[] {
+  return Array.from(toolCallParts.entries())
+    .sort(([left], [right]) => left - right)
+    .map(([index, toolCall]) => ({
+      id: toolCall.id || `call_${index}`,
+      type: 'function',
+      function: {
+        name: toolCall.name,
+        arguments: toolCall.arguments || '{}',
+      },
+    }));
+}
+
+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;
+      await yieldToMacrotask(signal);
+      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);
+  }
+}
+
+async function yieldToMacrotask(signal?: AbortSignal): Promise<void> {
+  if (signal?.aborted) return;
+  await new Promise<void>((resolve) => setTimeout(resolve, 0));
+}

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

@@ -0,0 +1,59 @@
+import type OpenAI from 'openai';
+import type { IToolCall, TTextDeltaCallback } from '@robota-sdk/agent-core';
+
+export interface IOpenAICompatibleChatRequestParams {
+  model: string;
+  messages: OpenAI.Chat.ChatCompletionMessageParam[];
+  temperature?: number | undefined;
+  max_tokens?: number | undefined;
+  tools?: OpenAI.Chat.ChatCompletionTool[] | undefined;
+  tool_choice?: 'auto' | 'none' | OpenAI.Chat.ChatCompletionNamedToolChoice | undefined;
+  stream?: boolean | undefined;
+}
+
+export interface IOpenAICompatibleStreamRequestParams
+  extends Omit<IOpenAICompatibleChatRequestParams, 'stream'> {
+  stream: true;
+}
+
+export interface IOpenAICompatibleError {
+  message: string;
+  type?: string;
+  param?: string | null;
+  code?: string | null;
+}
+
+export interface IOpenAICompatibleLogData {
+  model: string;
+  messagesCount: number;
+  hasTools: boolean;
+  temperature?: number | undefined;
+  maxTokens?: number | undefined;
+  timestamp: string;
+  requestId?: string | undefined;
+}
+
+export type TOpenAICompatibleTextProjector = (text: string) => string;
+export type TOpenAICompatibleTextProjectorFlush = () => string;
+
+export interface IOpenAICompatibleToolCallTextProjection {
+  visibleText: string;
+  toolCalls: IToolCall[];
+  removedToolCallText: boolean;
+  rawToolCallText?: string | undefined;
+}
+
+export interface IOpenAICompatibleToolCallTextProjector {
+  project(text: string): IOpenAICompatibleToolCallTextProjection;
+  flush(): IOpenAICompatibleToolCallTextProjection;
+}
+
+export interface IOpenAICompatibleStreamAssemblyOptions {
+  stream: AsyncIterable<OpenAI.Chat.ChatCompletionChunk>;
+  onTextDelta?: TTextDeltaCallback;
+  signal?: AbortSignal;
+  textProjector?: TOpenAICompatibleTextProjector;
+  textProjectorFlush?: TOpenAICompatibleTextProjectorFlush;
+  toolCallTextProjector?: IOpenAICompatibleToolCallTextProjector;
+  metadata?: Record<string, string | number | boolean>;
+}