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

package/src/anthropic/__tests__/response-parser.test.ts

@@ -0,0 +1,326 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import type Anthropic from '@anthropic-ai/sdk';
+
+// Mock the logger from @robota-sdk/agent-core
+vi.mock('@robota-sdk/agent-core', async () => {
+  const actual = await vi.importActual('@robota-sdk/agent-core');
+  return {
+    ...actual,
+    logger: {
+      error: vi.fn(),
+      warn: vi.fn(),
+      info: vi.fn(),
+      debug: vi.fn(),
+    },
+  };
+});
+
+import { AnthropicResponseParser } from '../parsers/response-parser';
+import { logger } from '@robota-sdk/agent-core';
+import type { IAssistantMessage } from '@robota-sdk/agent-core';
+import type { IAnthropicMessage } from '../types/api-types';
+
+/** Helper to cast parseResponse result to IAssistantMessage with usage for test assertions */
+type TAssistantWithUsage = IAssistantMessage & {
+  usage?: { promptTokens: number; completionTokens: number; totalTokens: number };
+};
+
+// Helper: build a minimal IAnthropicMessage
+function makeMessage(overrides: Partial<IAnthropicMessage> = {}): IAnthropicMessage {
+  return {
+    id: 'msg_123',
+    type: 'message',
+    role: 'assistant',
+    content: [{ type: 'text', text: 'Hello' }],
+    model: 'claude-3-opus-20240229',
+    stop_reason: 'end_turn',
+    stop_sequence: null,
+    usage: { input_tokens: 10, output_tokens: 20 },
+    ...overrides,
+  };
+}
+
+describe('AnthropicResponseParser', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  // ── parseResponse ────────────────────────────────────────────
+
+  describe('parseResponse', () => {
+    it('should parse a basic text response', () => {
+      const msg = makeMessage();
+      const result = AnthropicResponseParser.parseResponse(msg);
+
+      expect(result.role).toBe('assistant');
+      expect(result.content).toBe('Hello');
+      expect(result.timestamp).toBeInstanceOf(Date);
+      expect(result.metadata?.model).toBe('claude-3-opus-20240229');
+      expect(result.metadata?.finishReason).toBe('end_turn');
+    });
+
+    it('should extract token usage', () => {
+      const msg = makeMessage({
+        usage: { input_tokens: 50, output_tokens: 100 },
+      });
+      const result = AnthropicResponseParser.parseResponse(msg) as TAssistantWithUsage;
+
+      expect(result.usage).toEqual({
+        promptTokens: 50,
+        completionTokens: 100,
+        totalTokens: 150,
+      });
+    });
+
+    it('should handle missing usage gracefully', () => {
+      const msg = makeMessage();
+      // Remove usage to test undefined path
+      (msg as unknown as Record<string, unknown>).usage = undefined;
+      const result = AnthropicResponseParser.parseResponse(msg) as TAssistantWithUsage;
+
+      expect(result.usage).toBeUndefined();
+    });
+
+    it('should parse tool_use blocks into toolCalls', () => {
+      const msg = makeMessage({
+        content: [
+          { type: 'text', text: '' },
+          {
+            type: 'tool_use',
+            id: 'tool_call_1',
+            name: 'get_weather',
+            input: { city: 'Seoul' },
+          },
+        ],
+      });
+
+      const result = AnthropicResponseParser.parseResponse(msg) as IAssistantMessage;
+
+      expect(result.toolCalls).toHaveLength(1);
+      expect(result.toolCalls![0]).toEqual({
+        id: 'tool_call_1',
+        type: 'function',
+        function: {
+          name: 'get_weather',
+          arguments: JSON.stringify({ city: 'Seoul' }),
+        },
+      });
+    });
+
+    it('should filter out tool_use blocks without id or name', () => {
+      const msg = makeMessage({
+        content: [
+          { type: 'text', text: 'Hi' },
+          { type: 'tool_use' }, // missing id and name
+        ],
+      });
+
+      const result = AnthropicResponseParser.parseResponse(msg) as IAssistantMessage;
+      expect(result.toolCalls).toBeUndefined();
+    });
+
+    it('should handle empty content array by returning empty string', () => {
+      const msg = makeMessage({ content: [] });
+      const result = AnthropicResponseParser.parseResponse(msg);
+      expect(result.content).toBe('');
+    });
+
+    it('should use "unknown" as finishReason when stop_reason is null', () => {
+      const msg = makeMessage({ stop_reason: null });
+      const result = AnthropicResponseParser.parseResponse(msg);
+      expect(result.metadata?.finishReason).toBe('unknown');
+    });
+
+    it('should default input to empty object when missing from tool_use block', () => {
+      const msg = makeMessage({
+        content: [
+          {
+            type: 'tool_use',
+            id: 'tool_1',
+            name: 'noop',
+            // no input
+          },
+        ],
+      });
+
+      const result = AnthropicResponseParser.parseResponse(msg) as IAssistantMessage;
+      expect(result.toolCalls![0].function.arguments).toBe('{}');
+    });
+
+    it('should re-throw and log errors during parsing', () => {
+      // Force an error by passing an object that will fail during parsing
+      const badMsg = null as unknown as IAnthropicMessage;
+      expect(() => AnthropicResponseParser.parseResponse(badMsg)).toThrow();
+      expect(logger.error).toHaveBeenCalled();
+    });
+  });
+
+  // ── parseStreamingChunk ──────────────────────────────────────
+
+  describe('parseStreamingChunk', () => {
+    it('should handle content_block_start with text type', () => {
+      const chunk = {
+        type: 'content_block_start' as const,
+        index: 0,
+        content_block: { type: 'text', text: '' },
+      } as Anthropic.MessageStreamEvent;
+
+      const result = AnthropicResponseParser.parseStreamingChunk(chunk);
+
+      expect(result).not.toBeNull();
+      expect(result!.role).toBe('assistant');
+      expect(result!.content).toBe('');
+      expect(result!.metadata?.isStreamChunk).toBe(true);
+      expect(result!.metadata?.isComplete).toBe(false);
+    });
+
+    it('should handle content_block_start with tool_use type', () => {
+      const chunk = {
+        type: 'content_block_start' as const,
+        index: 0,
+        content_block: {
+          type: 'tool_use',
+          id: 'tool_1',
+          name: 'search',
+          input: {},
+        },
+      } as Anthropic.MessageStreamEvent;
+
+      const result = AnthropicResponseParser.parseStreamingChunk(chunk);
+
+      expect(result).not.toBeNull();
+      const assistantResult = result as IAssistantMessage;
+      expect(assistantResult.toolCalls).toHaveLength(1);
+      expect(assistantResult.toolCalls![0].id).toBe('tool_1');
+      expect(assistantResult.toolCalls![0].function.name).toBe('search');
+    });
+
+    it('should handle content_block_delta with text_delta', () => {
+      const chunk = {
+        type: 'content_block_delta' as const,
+        index: 0,
+        delta: { type: 'text_delta', text: 'Hello world' },
+      } as Anthropic.MessageStreamEvent;
+
+      const result = AnthropicResponseParser.parseStreamingChunk(chunk);
+
+      expect(result).not.toBeNull();
+      expect(result!.content).toBe('Hello world');
+      expect(result!.metadata?.isStreamChunk).toBe(true);
+    });
+
+    it('should handle content_block_delta with input_json_delta', () => {
+      const chunk = {
+        type: 'content_block_delta' as const,
+        index: 0,
+        delta: { type: 'input_json_delta', partial_json: '{"key' },
+      } as Anthropic.MessageStreamEvent;
+
+      const result = AnthropicResponseParser.parseStreamingChunk(chunk);
+
+      expect(result).not.toBeNull();
+      expect(result!.content).toBeNull();
+      expect(result!.metadata?.isStreamChunk).toBe(true);
+    });
+
+    it('should handle content_block_stop', () => {
+      const chunk = {
+        type: 'content_block_stop' as const,
+        index: 0,
+      } as Anthropic.MessageStreamEvent;
+
+      const result = AnthropicResponseParser.parseStreamingChunk(chunk);
+
+      expect(result).not.toBeNull();
+      expect(result!.metadata?.isStreamChunk).toBe(true);
+      expect(result!.metadata?.isComplete).toBe(false);
+    });
+
+    it('should handle message_stop with isComplete true', () => {
+      const chunk = {
+        type: 'message_stop' as const,
+      } as Anthropic.MessageStreamEvent;
+
+      const result = AnthropicResponseParser.parseStreamingChunk(chunk);
+
+      expect(result).not.toBeNull();
+      expect(result!.metadata?.isComplete).toBe(true);
+    });
+
+    it('should return null for unknown chunk types', () => {
+      const chunk = {
+        type: 'message_start' as const,
+        message: {},
+      } as Anthropic.MessageStreamEvent;
+
+      const result = AnthropicResponseParser.parseStreamingChunk(chunk);
+      expect(result).toBeNull();
+    });
+
+    it('should return null for content_block_start with unrecognized block type', () => {
+      const chunk = {
+        type: 'content_block_start' as const,
+        index: 0,
+        content_block: { type: 'image' },
+      } as unknown as Anthropic.MessageStreamEvent;
+
+      const result = AnthropicResponseParser.parseStreamingChunk(chunk);
+      expect(result).toBeNull();
+    });
+
+    it('should return null for content_block_delta with unrecognized delta type', () => {
+      const chunk = {
+        type: 'content_block_delta' as const,
+        index: 0,
+        delta: { type: 'unknown_delta' },
+      } as unknown as Anthropic.MessageStreamEvent;
+
+      const result = AnthropicResponseParser.parseStreamingChunk(chunk);
+      expect(result).toBeNull();
+    });
+
+    it('should return null and log error on exception', () => {
+      // Force an error by making the chunk cause an exception
+      const chunk = {
+        type: 'content_block_start',
+        get content_block() {
+          throw new Error('forced error');
+        },
+      } as unknown as Anthropic.MessageStreamEvent;
+
+      const result = AnthropicResponseParser.parseStreamingChunk(chunk);
+      expect(result).toBeNull();
+      expect(logger.error).toHaveBeenCalled();
+    });
+
+    it('should handle content_block_start tool_use with empty name', () => {
+      const chunk = {
+        type: 'content_block_start' as const,
+        index: 0,
+        content_block: {
+          type: 'tool_use',
+          id: 'tool_2',
+          name: '',
+          input: {},
+        },
+      } as Anthropic.MessageStreamEvent;
+
+      const result = AnthropicResponseParser.parseStreamingChunk(chunk);
+
+      expect(result).not.toBeNull();
+      expect((result as IAssistantMessage).toolCalls![0].function.name).toBe('');
+    });
+
+    it('should handle text_delta with empty text', () => {
+      const chunk = {
+        type: 'content_block_delta' as const,
+        index: 0,
+        delta: { type: 'text_delta', text: '' },
+      } as Anthropic.MessageStreamEvent;
+
+      const result = AnthropicResponseParser.parseStreamingChunk(chunk);
+      expect(result).not.toBeNull();
+      expect(result!.content).toBe('');
+    });
+  });
+});

package/src/anthropic/index.ts

@@ -0,0 +1,22 @@
+/**
+ * @robota-sdk/agent-provider (anthropic)
+ *
+ * Provides Provider implementation for using Anthropic API with provider-agnostic TUniversalMessage.
+ */
+
+// Main exports
+export * from './provider';
+export * from './types';
+export * from './provider-definition';
+export * from './model-catalog-refresh';
+
+import type { IAnthropicProviderOptions } from './types';
+
+/**
+ * Factory function for creating an AnthropicProvider instance.
+ * @param _options - Configuration options for the Anthropic provider
+ * @returns An AnthropicProvider instance
+ */
+export function createAnthropicProvider(_options: IAnthropicProviderOptions) {
+  // Implementation of createAnthropicProvider function
+}

package/src/anthropic/message-converter.ts

@@ -0,0 +1,181 @@
+import { randomUUID } from 'node:crypto';
+import Anthropic from '@anthropic-ai/sdk';
+import type {
+  TUniversalMessage,
+  IToolSchema,
+  IAssistantMessage,
+  IToolMessage,
+} from '@robota-sdk/agent-core';
+
+/**
+ * Convert TUniversalMessage array to Anthropic message format.
+ *
+ * CRITICAL: Anthropic API requires specific content handling:
+ * - tool_use messages: content MUST be null
+ * - regular messages: content should be a string
+ */
+export function convertToAnthropicFormat(messages: TUniversalMessage[]): Anthropic.MessageParam[] {
+  return messages.map((msg) => {
+    if (msg.role === 'user') {
+      return {
+        role: 'user',
+        content: msg.content || '',
+      };
+    } else if (msg.role === 'assistant') {
+      const assistantMsg = msg as IAssistantMessage;
+
+      // Anthropic uses content blocks — include both text and tool_use
+      if (assistantMsg.toolCalls && assistantMsg.toolCalls.length > 0) {
+        const contentBlocks: Array<Anthropic.TextBlockParam | Anthropic.ToolUseBlockParam> = [];
+
+        // Include text content if present alongside tool calls
+        if (assistantMsg.content) {
+          contentBlocks.push({
+            type: 'text' as const,
+            text: assistantMsg.content,
+          });
+        }
+
+        for (const tc of assistantMsg.toolCalls) {
+          contentBlocks.push({
+            type: 'tool_use' as const,
+            id: tc.id,
+            name: tc.function.name,
+            input: JSON.parse(tc.function.arguments),
+          });
+        }
+
+        return {
+          role: 'assistant' as const,
+          content: contentBlocks,
+        };
+      }
+
+      // Regular assistant message (no tool calls)
+      return {
+        role: 'assistant',
+        content: assistantMsg.content || '',
+      };
+    } else if (msg.role === 'tool') {
+      // Tool result message — convert to Anthropic tool_result content block
+      const toolMsg = msg as IToolMessage;
+      return {
+        role: 'user' as const,
+        content: [
+          {
+            type: 'tool_result' as const,
+            tool_use_id: toolMsg.toolCallId ?? '',
+            content: msg.content || '',
+          },
+        ],
+      };
+    } else {
+      // System messages
+      return {
+        role: 'user', // Anthropic doesn't have system role, use user
+        content: msg.content || '',
+      };
+    }
+  });
+}
+
+/**
+ * Convert Anthropic response to TUniversalMessage.
+ *
+ * Anthropic responses can contain multiple content blocks:
+ * e.g., [text("I'll read the file"), tool_use(Read, {...}), tool_use(Bash, {...})]
+ * We must extract ALL text and ALL tool_use blocks.
+ */
+export function convertFromAnthropicResponse(response: Anthropic.Message): TUniversalMessage {
+  if (!response.content || response.content.length === 0) {
+    throw new Error('No content in Anthropic response');
+  }
+
+  let textParts: string[] = [];
+  const toolCalls: Array<{
+    id: string;
+    type: 'function';
+    function: { name: string; arguments: string };
+  }> = [];
+
+  for (const block of response.content) {
+    if (block.type === 'text') {
+      const textBlock = block as Anthropic.TextBlock;
+      if (textBlock.text) {
+        textParts.push(textBlock.text);
+      }
+    } else if (block.type === 'tool_use') {
+      const toolBlock = block as Anthropic.ToolUseBlock;
+      toolCalls.push({
+        id: toolBlock.id,
+        type: 'function' as const,
+        function: {
+          name: toolBlock.name,
+          arguments: JSON.stringify(toolBlock.input),
+        },
+      });
+    } else if (block.type === 'server_tool_use') {
+      // Server tool invocation (e.g., web_search) — results come in a separate block
+    } else if (block.type === 'web_search_tool_result') {
+      const resultBlock = block as Anthropic.Messages.WebSearchToolResultBlock;
+      const searchResults = formatWebSearchResults(resultBlock);
+      if (searchResults) {
+        textParts.push(searchResults);
+      }
+    }
+  }
+
+  // Use empty string instead of null so agent-core's buildFinalResult
+  // doesn't reject the message. Tool-only responses have no text.
+  const textContent = textParts.join('\n') || '';
+
+  const result: TUniversalMessage = {
+    id: randomUUID(),
+    role: 'assistant',
+    content: textContent,
+    state: 'complete' as const,
+    timestamp: new Date(),
+    ...(toolCalls.length > 0 && { toolCalls }),
+  };
+
+  // Add metadata if available
+  if (response.usage) {
+    result.metadata = {
+      inputTokens: response.usage.input_tokens,
+      outputTokens: response.usage.output_tokens,
+      model: response.model,
+    };
+
+    if (response.stop_reason) {
+      result.metadata['stopReason'] = response.stop_reason;
+    }
+  }
+
+  return result;
+}
+
+/** Format a WebSearchToolResultBlock into readable text. */
+export function formatWebSearchResults(block: Anthropic.Messages.WebSearchToolResultBlock): string {
+  if (!Array.isArray(block.content)) return '';
+
+  const results = block.content
+    .filter(
+      (r): r is Anthropic.Messages.WebSearchResultBlock =>
+        r.type === 'web_search_result' && 'title' in r && 'url' in r,
+    )
+    .map((r, i) => `${i + 1}. ${r.title}\n   ${r.url}`)
+    .join('\n');
+
+  return results ? `[Web Search Results]\n${results}` : '';
+}
+
+/**
+ * Convert tool schemas to Anthropic format.
+ */
+export function convertToolsToAnthropicFormat(tools: IToolSchema[]): Anthropic.Tool[] {
+  return tools.map((tool) => ({
+    name: tool.name,
+    description: tool.description,
+    input_schema: tool.parameters as Anthropic.Tool.InputSchema,
+  }));
+}

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

@@ -0,0 +1,128 @@
+import type {
+  IProviderModelCatalog,
+  IProviderModelCatalogEntry,
+  IProviderProfileConfig,
+} from '@robota-sdk/agent-core';
+import {
+  ANTHROPIC_MODEL_SOURCE_URL,
+  ANTHROPIC_MODEL_LAST_VERIFIED_AT,
+} from './provider-definition';
+
+const ANTHROPIC_MODELS_API_URL = 'https://api.anthropic.com/v1/models';
+const ANTHROPIC_API_VERSION = '2023-06-01';
+
+export interface IAnthropicModelsResponse {
+  data?: Array<{
+    id?: string;
+    display_name?: string;
+    type?: string;
+  }>;
+  has_more?: boolean;
+}
+
+export interface IAnthropicFetchInit {
+  headers?: Record<string, string>;
+}
+
+export interface IAnthropicFetchResponse {
+  ok: boolean;
+  status: number;
+  json: () => Promise<IAnthropicModelsResponse>;
+}
+
+export type TAnthropicFetch = (
+  url: string,
+  init?: IAnthropicFetchInit,
+) => Promise<IAnthropicFetchResponse>;
+
+export async function refreshAnthropicModelCatalog(
+  profile: IProviderProfileConfig,
+  fetcher: TAnthropicFetch = defaultAnthropicFetch,
+): Promise<IProviderModelCatalog> {
+  return fetchModelCatalog(profile, fetcher);
+}
+
+async function fetchModelCatalog(
+  profile: IProviderProfileConfig,
+  fetcher: TAnthropicFetch,
+): Promise<IProviderModelCatalog> {
+  const response = await fetcher(ANTHROPIC_MODELS_API_URL, buildFetchInit(profile.apiKey)).catch(
+    (err: unknown) => {
+      // allow-fallback: catalog refresh is non-terminal; callers expect IProviderModelCatalog
+      const message = err instanceof Error ? err.message : String(err);
+      return {
+        ok: false as const,
+        status: 0,
+        json: (): Promise<IAnthropicModelsResponse> => Promise.resolve({ data: [] }),
+        errorMessage: `Anthropic model refresh failed: ${message}`,
+      };
+    },
+  );
+
+  if ('errorMessage' in response) {
+    return {
+      status: 'unavailable',
+      sourceUrl: ANTHROPIC_MODEL_SOURCE_URL,
+      message: response.errorMessage,
+    };
+  }
+
+  if (!response.ok) {
+    return {
+      status: 'unavailable',
+      sourceUrl: ANTHROPIC_MODEL_SOURCE_URL,
+      message: `Anthropic model refresh failed: HTTP ${response.status}`,
+    };
+  }
+
+  const body = await response.json();
+  const now = new Date().toISOString();
+  const entries: IProviderModelCatalogEntry[] = (body.data ?? [])
+    .filter(
+      (item): item is { id: string; display_name?: string; type?: string } =>
+        typeof item.id === 'string' && item.id.length > 0,
+    )
+    .map(
+      (item): IProviderModelCatalogEntry => ({
+        id: item.id,
+        displayName: item.display_name ?? item.id,
+        lifecycle: 'active',
+        sourceUrl: ANTHROPIC_MODEL_SOURCE_URL,
+        lastVerifiedAt: now,
+      }),
+    );
+
+  return {
+    status: 'live',
+    sourceUrl: ANTHROPIC_MODEL_SOURCE_URL,
+    lastVerifiedAt: ANTHROPIC_MODEL_LAST_VERIFIED_AT,
+    entries,
+    message: `Fetched ${entries.length} models from Anthropic API`,
+  };
+}
+
+function buildFetchInit(apiKey: string | undefined): IAnthropicFetchInit | undefined {
+  if (!apiKey) {
+    return undefined;
+  }
+  return {
+    headers: {
+      'x-api-key': apiKey,
+      'anthropic-version': ANTHROPIC_API_VERSION,
+    },
+  };
+}
+
+async function defaultAnthropicFetch(
+  url: string,
+  init?: IAnthropicFetchInit,
+): Promise<IAnthropicFetchResponse> {
+  const response = await fetch(url, {
+    ...(init?.headers !== undefined && { headers: init.headers }),
+  });
+  return {
+    ok: response.ok,
+    status: response.status,
+    json: () => response.json() as Promise<IAnthropicModelsResponse>,
+  };
+}