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

package/src/gemma/tool-call-projector.test.ts

@@ -0,0 +1,227 @@
+import { describe, expect, it } from 'vitest';
+import { GemmaToolCallProjector, projectGemmaToolCallText } from './index';
+
+describe('Gemma native tool-call projection', () => {
+  it('projects documented LM Studio/Gemma tool-call blocks for declared tools', () => {
+    const result = projectGemmaToolCallText(
+      'before<|tool_call>call:DeclaredTool{prompt:<|"|>analyze<|"|>,background:true}<tool_call|>after',
+      { toolNames: ['DeclaredTool'] },
+    );
+
+    expect(result.visibleText).toBe('beforeafter');
+    expect(result.removedToolCallText).toBe(true);
+    expect(result.rawToolCallText).toBe(
+      '<|tool_call>call:DeclaredTool{prompt:<|"|>analyze<|"|>,background:true}<tool_call|>',
+    );
+    expect(result.toolCalls).toEqual([
+      {
+        id: 'gemma_call_0',
+        type: 'function',
+        function: {
+          name: 'DeclaredTool',
+          arguments: '{"prompt":"analyze","background":true}',
+        },
+      },
+    ]);
+  });
+
+  it('keeps undeclared tool-call blocks visible and non-executable', () => {
+    const raw = '<|tool_call>call:OtherTool{prompt:<|"|>analyze<|"|>}<tool_call|>';
+    const result = projectGemmaToolCallText(raw, { toolNames: ['DeclaredTool'] });
+
+    expect(result.visibleText).toBe(raw);
+    expect(result.toolCalls).toEqual([]);
+    expect(result.removedToolCallText).toBe(false);
+  });
+
+  it('holds split streamed tool-call blocks until complete', () => {
+    const projector = new GemmaToolCallProjector({ toolNames: ['DeclaredTool'] });
+
+    expect(projector.project('<|tool_call>call:Declar')).toMatchObject({
+      visibleText: '',
+      toolCalls: [],
+      removedToolCallText: false,
+    });
+    const result = projector.project('edTool{prompt:<|"|>analyze<|"|>}<tool_call|>visible');
+
+    expect(result.visibleText).toBe('visible');
+    expect(result.removedToolCallText).toBe(true);
+    expect(result.toolCalls).toEqual([
+      {
+        id: 'gemma_call_0',
+        type: 'function',
+        function: {
+          name: 'DeclaredTool',
+          arguments: '{"prompt":"analyze"}',
+        },
+      },
+    ]);
+    expect(projector.flush().visibleText).toBe('');
+  });
+
+  it('does not re-emit raw tool-call metadata after the block was projected', () => {
+    const projector = new GemmaToolCallProjector({ toolNames: ['DeclaredTool'] });
+    const first = projector.project(
+      '<|tool_call>call:DeclaredTool{prompt:<|"|>analyze<|"|>}<tool_call|>',
+    );
+    const second = projector.project('visible');
+
+    expect(first.rawToolCallText).toBe(
+      '<|tool_call>call:DeclaredTool{prompt:<|"|>analyze<|"|>}<tool_call|>',
+    );
+    expect(second.visibleText).toBe('visible');
+    expect(second.rawToolCallText).toBeUndefined();
+    expect(second.removedToolCallText).toBe(false);
+    expect(second.toolCalls).toEqual([]);
+  });
+
+  it('preserves malformed complete blocks instead of guessing execution', () => {
+    const raw = '<|tool_call>call:DeclaredTool prompt:<|"|>missing braces<|"|><tool_call|>';
+    const result = projectGemmaToolCallText(raw, { toolNames: ['DeclaredTool'] });
+
+    expect(result.visibleText).toBe(raw);
+    expect(result.toolCalls).toEqual([]);
+    expect(result.removedToolCallText).toBe(false);
+  });
+
+  it('projects XML-like tags whose names match declared tools', () => {
+    const result = projectGemmaToolCallText(
+      'before<DeclaredTool prompt="analyze backlog" mode="plan" background="true" />after',
+      { toolNames: ['DeclaredTool'] },
+    );
+
+    expect(result.visibleText).toBe('beforeafter');
+    expect(result.removedToolCallText).toBe(true);
+    expect(result.rawToolCallText).toBe(
+      '<DeclaredTool prompt="analyze backlog" mode="plan" background="true" />',
+    );
+    expect(result.toolCalls).toEqual([
+      {
+        id: 'gemma_call_0',
+        type: 'function',
+        function: {
+          name: 'DeclaredTool',
+          arguments: '{"prompt":"analyze backlog","mode":"plan","background":true}',
+        },
+      },
+    ]);
+  });
+
+  it('strips XML wrapper tags while projecting nested declared tool tags', () => {
+    const result = projectGemmaToolCallText(
+      [
+        '<tool-launch-sequence>internal planning text</tool-launch-sequence>',
+        '<tool-call-1>',
+        '<DeclaredTool prompt="implementation analysis" mode="implementation" />',
+        '</tool-call-1>',
+        'visible',
+      ].join(''),
+      { toolNames: ['DeclaredTool'] },
+    );
+
+    expect(result.visibleText).toBe('visible');
+    expect(result.rawToolCallText).toContain(
+      '<DeclaredTool prompt="implementation analysis" mode="implementation" />',
+    );
+    expect(result.toolCalls).toEqual([
+      {
+        id: 'gemma_call_0',
+        type: 'function',
+        function: {
+          name: 'DeclaredTool',
+          arguments: '{"prompt":"implementation analysis","mode":"implementation"}',
+        },
+      },
+    ]);
+  });
+
+  it('projects JSON command envelopes for declared tools', () => {
+    const result = projectGemmaToolCallText(
+      [
+        '<tool-call-1>',
+        '{"command":"DeclaredTool","args":{"prompt":"analyze implementation","mode":"worker","background":true}}',
+        '</tool-call-1>',
+      ].join(''),
+      { toolNames: ['DeclaredTool'] },
+    );
+
+    expect(result.visibleText).toBe('');
+    expect(result.toolCalls).toEqual([
+      {
+        id: 'gemma_call_0',
+        type: 'function',
+        function: {
+          name: 'DeclaredTool',
+          arguments: '{"prompt":"analyze implementation","mode":"worker","background":true}',
+        },
+      },
+    ]);
+  });
+
+  it('does not infer tool calls from wrapper text or command-like DSL', () => {
+    const result = projectGemmaToolCallText(
+      [
+        '<tool-launch>',
+        'parallel',
+        ' worker=DeclaredTool:"Analyze implementation details."',
+        ' reviewer=DeclaredTool:"Analyze architecture boundaries."',
+        '</tool-launch>',
+      ].join('\n'),
+      { toolNames: ['DeclaredTool'] },
+    );
+
+    expect(result.visibleText).toBe('');
+    expect(result.toolCalls).toEqual([]);
+    expect(result.removedToolCallText).toBe(true);
+  });
+
+  it('does not infer slash-command text inside XML wrappers as tool calls', () => {
+    const result = projectGemmaToolCallText(
+      [
+        '<tool-launch>',
+        '/tool prompt:"Analyze concurrency." mode:"worker"',
+        '/tool prompt:"Analyze UI flow." mode:"reviewer" background:true',
+        '</tool-launch>',
+      ].join('\n'),
+      { toolNames: ['DeclaredTool'] },
+    );
+
+    expect(result.visibleText).toBe('');
+    expect(result.toolCalls).toEqual([]);
+  });
+
+  it('strips generic XML wrapper tags without provider-specific tag names', () => {
+    const result = projectGemmaToolCallText(
+      '<execution-step>The task will be analyzed.</execution-step>visible',
+      { toolNames: ['DeclaredTool'] },
+    );
+
+    expect(result.visibleText).toBe('visible');
+    expect(result.toolCalls).toEqual([]);
+    expect(result.removedToolCallText).toBe(true);
+  });
+
+  it('holds split streamed XML-like declared tool tags until complete', () => {
+    const projector = new GemmaToolCallProjector({ toolNames: ['DeclaredTool'] });
+
+    expect(projector.project('<DeclaredTool prompt="analyze')).toMatchObject({
+      visibleText: '',
+      toolCalls: [],
+      removedToolCallText: false,
+    });
+    const result = projector.project(' backlog" mode="plan" />done');
+
+    expect(result.visibleText).toBe('done');
+    expect(result.toolCalls).toEqual([
+      {
+        id: 'gemma_call_0',
+        type: 'function',
+        function: {
+          name: 'DeclaredTool',
+          arguments: '{"prompt":"analyze backlog","mode":"plan"}',
+        },
+      },
+    ]);
+    expect(projector.flush().visibleText).toBe('');
+  });
+});

package/src/gemma/tool-call-projector.ts

@@ -0,0 +1,264 @@
+import type { IToolCall, IToolSchema } from '@robota-sdk/agent-core';
+import type {
+  IOpenAICompatibleToolCallTextProjection,
+  IOpenAICompatibleToolCallTextProjector,
+} from '../shared/openai-compatible/index.js';
+import { GemmaArgumentParser } from './tool-call-argument-parser';
+import { projectGemmaPseudoToolCallText } from './pseudo-tool-call-projector';
+
+const TOOL_CALL_START = '<|tool_call>';
+const TOOL_CALL_END = '<tool_call|>';
+const CALL_PREFIX = 'call:';
+const DEFAULT_CALL_ID_PREFIX = 'gemma_call';
+
+export interface IGemmaToolCallProjectorOptions {
+  toolNames: readonly string[];
+  callIdPrefix?: string;
+}
+
+export interface IGemmaToolCallProjection extends IOpenAICompatibleToolCallTextProjection {
+  rawText: string;
+}
+
+interface IProjectionOptions {
+  final: boolean;
+}
+
+interface IProjectionState {
+  visibleParts: string[];
+  toolCalls: IToolCall[];
+  rawToolCallTextParts: string[];
+  removedToolCallText: boolean;
+}
+
+export function createGemmaToolCallProjector(
+  tools: readonly IToolSchema[] | undefined,
+): GemmaToolCallProjector | undefined {
+  if (!tools || tools.length === 0) {
+    return undefined;
+  }
+  return new GemmaToolCallProjector({ toolNames: tools.map((tool) => tool.name) });
+}
+
+export function projectGemmaToolCallText(
+  rawText: string,
+  options: IGemmaToolCallProjectorOptions,
+): IGemmaToolCallProjection {
+  const result = projectText(rawText, options, { final: true });
+  return toPublicProjection(rawText, result);
+}
+
+export class GemmaToolCallProjector implements IOpenAICompatibleToolCallTextProjector {
+  private buffer = '';
+  private emittedVisibleText = '';
+  private emittedRawToolCallText = '';
+  private readonly emittedToolCallIds = new Set<string>();
+
+  constructor(private readonly options: IGemmaToolCallProjectorOptions) {}
+
+  project(delta: string): IOpenAICompatibleToolCallTextProjection {
+    if (delta.length === 0) {
+      return emptyProjection();
+    }
+
+    this.buffer += delta;
+    return this.projectVisibleText({ final: false });
+  }
+
+  flush(): IOpenAICompatibleToolCallTextProjection {
+    return this.projectVisibleText({ final: true });
+  }
+
+  private projectVisibleText(options: IProjectionOptions): IOpenAICompatibleToolCallTextProjection {
+    const result = projectText(this.buffer, this.options, options);
+    const nextVisibleText = result.visibleParts.join('');
+    const visibleText = nextVisibleText.slice(this.emittedVisibleText.length);
+    const nextRawToolCallText = result.rawToolCallTextParts.join('');
+    const rawToolCallText = nextRawToolCallText.slice(this.emittedRawToolCallText.length);
+    this.emittedVisibleText = nextVisibleText;
+    this.emittedRawToolCallText = nextRawToolCallText;
+
+    const toolCalls = result.toolCalls.filter((toolCall) => {
+      if (this.emittedToolCallIds.has(toolCall.id)) {
+        return false;
+      }
+      this.emittedToolCallIds.add(toolCall.id);
+      return true;
+    });
+
+    return {
+      visibleText,
+      toolCalls,
+      removedToolCallText: rawToolCallText.length > 0,
+      ...(rawToolCallText.length > 0 && {
+        rawToolCallText,
+      }),
+    };
+  }
+}
+
+function projectText(
+  rawText: string,
+  options: IGemmaToolCallProjectorOptions,
+  projectionOptions: IProjectionOptions,
+): IProjectionState {
+  const nativeProjection = projectNativeToolCallText(rawText, options, projectionOptions);
+  const pseudoProjection = projectGemmaPseudoToolCallText(
+    nativeProjection.visibleParts.join(''),
+    {
+      toolNames: options.toolNames,
+      callIdPrefix: options.callIdPrefix ?? DEFAULT_CALL_ID_PREFIX,
+      startCallIndex: nativeProjection.toolCalls.length,
+    },
+    projectionOptions,
+  );
+
+  return {
+    visibleParts: [pseudoProjection.visibleText],
+    toolCalls: [...nativeProjection.toolCalls, ...pseudoProjection.toolCalls],
+    rawToolCallTextParts: [
+      ...nativeProjection.rawToolCallTextParts,
+      ...pseudoProjection.rawToolCallTextParts,
+    ],
+    removedToolCallText:
+      nativeProjection.removedToolCallText || pseudoProjection.removedToolCallText,
+  };
+}
+
+function projectNativeToolCallText(
+  rawText: string,
+  options: IGemmaToolCallProjectorOptions,
+  projectionOptions: IProjectionOptions,
+): IProjectionState {
+  const state = createProjectionState();
+  const toolNames = new Set(options.toolNames);
+  let cursor = 0;
+  let projectedCallIndex = 0;
+
+  while (cursor < rawText.length) {
+    const nextMarker = rawText.indexOf(TOOL_CALL_START, cursor);
+    if (nextMarker === -1) {
+      appendVisibleTail(state, rawText.slice(cursor), projectionOptions);
+      break;
+    }
+
+    appendVisibleTail(state, rawText.slice(cursor, nextMarker), projectionOptions);
+    const afterStart = nextMarker + TOOL_CALL_START.length;
+    const markerEnd = rawText.indexOf(TOOL_CALL_END, afterStart);
+    if (markerEnd === -1) {
+      if (projectionOptions.final) {
+        state.visibleParts.push(rawText.slice(nextMarker));
+      }
+      break;
+    }
+
+    const rawBlock = rawText.slice(nextMarker, markerEnd + TOOL_CALL_END.length);
+    const blockText = rawText.slice(afterStart, markerEnd);
+    const toolCall = parseToolCallBlock(blockText, toolNames, options, projectedCallIndex);
+    if (!toolCall) {
+      state.visibleParts.push(rawBlock);
+    } else {
+      state.toolCalls.push(toolCall);
+      state.rawToolCallTextParts.push(rawBlock);
+      state.removedToolCallText = true;
+      projectedCallIndex += 1;
+    }
+    cursor = markerEnd + TOOL_CALL_END.length;
+  }
+
+  return state;
+}
+
+function parseToolCallBlock(
+  blockText: string,
+  toolNames: ReadonlySet<string>,
+  options: IGemmaToolCallProjectorOptions,
+  projectedCallIndex: number,
+): IToolCall | undefined {
+  const trimmed = blockText.trim();
+  if (!trimmed.startsWith(CALL_PREFIX)) {
+    return undefined;
+  }
+
+  const callText = trimmed.slice(CALL_PREFIX.length).trimStart();
+  const argsStart = callText.indexOf('{');
+  if (argsStart <= 0) {
+    return undefined;
+  }
+
+  const toolName = callText.slice(0, argsStart).trim();
+  if (!toolNames.has(toolName)) {
+    return undefined;
+  }
+
+  const args = new GemmaArgumentParser(callText.slice(argsStart)).parse();
+  if (!args) {
+    return undefined;
+  }
+
+  return {
+    id: `${options.callIdPrefix ?? DEFAULT_CALL_ID_PREFIX}_${projectedCallIndex}`,
+    type: 'function',
+    function: {
+      name: toolName,
+      arguments: JSON.stringify(args),
+    },
+  };
+}
+
+function createProjectionState(): IProjectionState {
+  return {
+    visibleParts: [],
+    toolCalls: [],
+    rawToolCallTextParts: [],
+    removedToolCallText: false,
+  };
+}
+
+function appendVisibleTail(
+  state: IProjectionState,
+  tail: string,
+  options: IProjectionOptions,
+): void {
+  if (tail.length === 0) {
+    return;
+  }
+
+  if (options.final) {
+    state.visibleParts.push(tail);
+    return;
+  }
+
+  const heldLength = longestStartMarkerPrefixSuffixLength(tail);
+  state.visibleParts.push(tail.slice(0, tail.length - heldLength));
+}
+
+function longestStartMarkerPrefixSuffixLength(text: string): number {
+  const maxLength = Math.min(text.length, TOOL_CALL_START.length - 1);
+  for (let length = maxLength; length > 0; length -= 1) {
+    if (TOOL_CALL_START.startsWith(text.slice(text.length - length))) {
+      return length;
+    }
+  }
+  return 0;
+}
+
+function toPublicProjection(rawText: string, state: IProjectionState): IGemmaToolCallProjection {
+  return {
+    rawText,
+    visibleText: state.visibleParts.join(''),
+    toolCalls: state.toolCalls,
+    removedToolCallText: state.removedToolCallText,
+    ...(state.rawToolCallTextParts.length > 0 && {
+      rawToolCallText: state.rawToolCallTextParts.join(''),
+    }),
+  };
+}
+
+function emptyProjection(): IOpenAICompatibleToolCallTextProjection {
+  return {
+    visibleText: '',
+    toolCalls: [],
+    removedToolCallText: false,
+  };
+}

package/src/gemma/types.ts

@@ -0,0 +1,27 @@
+import type OpenAI from 'openai';
+import type { IExecutor, ILogger, TProviderOptionValueBase } from '@robota-sdk/agent-core';
+
+export type TGemmaProviderOptionValue =
+  | string
+  | number
+  | boolean
+  | undefined
+  | null
+  | OpenAI
+  | ILogger
+  | IExecutor
+  | TProviderOptionValueBase
+  | TGemmaProviderOptionValue[]
+  | { [key: string]: TGemmaProviderOptionValue };
+
+export interface IGemmaProviderOptions {
+  [key: string]: TGemmaProviderOptionValue;
+
+  apiKey?: string;
+  baseURL?: string;
+  timeout?: number;
+  defaultModel?: string;
+  client?: OpenAI;
+  executor?: IExecutor;
+  logger?: ILogger;
+}

package/src/google/index.ts

@@ -0,0 +1,11 @@
+/**
+ * @robota-sdk/agent-provider-google compatibility package.
+ *
+ * New code should import from @robota-sdk/agent-provider/gemini.
+ */
+
+export { GeminiProvider } from '../gemini/index.js';
+export type { IGeminiProviderOptions, TGeminiProviderOptionValue } from '../gemini/index.js';
+export * from './provider.js';
+export * from './provider-definition.js';
+export * from './types.js';

package/src/google/provider-compat.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, it } from 'vitest';
+import { GeminiProvider, createGeminiProviderDefinition } from '../gemini/index.js';
+import { GoogleProvider } from './provider.js';
+
+describe('Google provider compatibility package', () => {
+  it('keeps GoogleProvider as a compatibility subclass of GeminiProvider', () => {
+    const provider = new GoogleProvider({ apiKey: 'test-key' });
+
+    expect(provider).toBeInstanceOf(GeminiProvider);
+    expect(provider.name).toBe('google');
+  });
+
+  it('re-exports the canonical Gemini provider definition metadata', () => {
+    const definition = createGeminiProviderDefinition();
+
+    expect(definition.type).toBe('gemini');
+    expect(definition.aliases).toContain('google');
+  });
+});

package/src/google/provider-definition.ts

@@ -0,0 +1,6 @@
+export {
+  createGeminiProviderDefinition,
+  DEFAULT_GEMINI_PROVIDER_API_KEY_ENV,
+  DEFAULT_GEMINI_PROVIDER_API_KEY_REFERENCE,
+  DEFAULT_GEMINI_PROVIDER_MODEL,
+} from '../gemini/index.js';

package/src/google/provider.ts

@@ -0,0 +1,10 @@
+import { GeminiProvider } from '../gemini/index.js';
+import type { IGoogleProviderOptions } from './types.js';
+
+export class GoogleProvider extends GeminiProvider {
+  override readonly name = 'google';
+
+  constructor(options: IGoogleProviderOptions) {
+    super(options);
+  }
+}

package/src/google/types.ts

@@ -0,0 +1,5 @@
+import type { IGeminiProviderOptions, TGeminiProviderOptionValue } from '../gemini/index.js';
+
+export type TGoogleProviderOptionValue = TGeminiProviderOptionValue;
+
+export interface IGoogleProviderOptions extends IGeminiProviderOptions {}

package/src/index.ts

@@ -0,0 +1,9 @@
+export * from './anthropic/index.js';
+export * from './openai/index.js';
+export * from './deepseek/index.js';
+export * from './gemini/index.js';
+export * from './gemma/index.js';
+export * from './bytedance/index.js';
+export * from './qwen/index.js';
+// google/ omitted: deprecated compatibility alias for gemini, available via sub-path only
+// import { GoogleProvider } from '@robota-sdk/agent-provider/google';