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

package/src/anthropic/streaming-handler.ts

@@ -0,0 +1,204 @@
+import { randomUUID } from 'node:crypto';
+import Anthropic from '@anthropic-ai/sdk';
+import type {
+  TProviderNativeRawPayloadCallback,
+  TUniversalMessage,
+  TTextDeltaCallback,
+} from '@robota-sdk/agent-core';
+import { formatWebSearchResults } from './message-converter';
+
+/**
+ * Stream the Anthropic API response and assemble a complete TUniversalMessage.
+ *
+ * Calls onTextDelta for each text chunk as it arrives.
+ * Returns the fully assembled TUniversalMessage when the stream is done.
+ */
+export async function streamAndAssemble(
+  client: Anthropic,
+  params: Anthropic.MessageCreateParamsNonStreaming,
+  onTextDelta: TTextDeltaCallback,
+  onServerToolUse: ((toolName: string, input: Record<string, string>) => void) | undefined,
+  signal: AbortSignal | undefined,
+  onProviderNativeRawPayload?: TProviderNativeRawPayloadCallback,
+): Promise<TUniversalMessage> {
+  const streamParams: Anthropic.MessageCreateParamsStreaming = {
+    ...params,
+    stream: true,
+  };
+
+  onProviderNativeRawPayload?.({
+    provider: 'anthropic',
+    apiSurface: 'anthropic-messages',
+    payloadKind: 'request',
+    payload: streamParams,
+  });
+  const stream = await client.messages.create(streamParams, signal ? { signal } : undefined);
+
+  // Accumulate the full response from stream events
+  const textParts: string[] = [];
+  const toolCalls: Array<{
+    id: string;
+    type: 'function';
+    function: { name: string; arguments: string };
+  }> = [];
+  let currentToolId = '';
+  let currentToolName = '';
+  let currentToolJson = '';
+  let usage = { input_tokens: 0, output_tokens: 0 };
+  let model = '';
+  let stopReason: string | null = null;
+
+  try {
+    let sequence = 0;
+    for await (const event of streamWithAbort(stream, signal)) {
+      onProviderNativeRawPayload?.({
+        provider: 'anthropic',
+        apiSurface: 'anthropic-messages',
+        payloadKind: 'stream_event',
+        sequence,
+        payload: event,
+      });
+      sequence++;
+      switch (event.type) {
+        case 'message_start':
+          usage = event.message.usage;
+          model = event.message.model;
+          break;
+
+        case 'content_block_start':
+          if (event.content_block.type === 'tool_use') {
+            currentToolId = event.content_block.id;
+            currentToolName = event.content_block.name;
+            currentToolJson = '';
+          } else if (event.content_block.type === 'server_tool_use') {
+            const serverBlock = event.content_block as {
+              name?: string;
+              input?: { query?: string };
+            };
+            const query = serverBlock.input?.query ?? '';
+            const toolLabel = query
+              ? `\n🔍 Searching: "${query}"\n`
+              : `\n🔍 [${serverBlock.name ?? 'server_tool'}]\n`;
+            textParts.push(toolLabel);
+            onTextDelta(toolLabel);
+            if (onServerToolUse) {
+              onServerToolUse(serverBlock.name ?? 'server_tool', { query });
+            }
+          } else if (event.content_block.type === 'web_search_tool_result') {
+            const resultBlock = event.content_block as Anthropic.Messages.WebSearchToolResultBlock;
+            const formatted = formatWebSearchResults(resultBlock);
+            if (formatted) {
+              textParts.push(`\n${formatted}\n\n`);
+              onTextDelta(`\n${formatted}\n\n`);
+            }
+          }
+          break;
+
+        case 'content_block_delta':
+          if (event.delta.type === 'text_delta') {
+            textParts.push(event.delta.text);
+            onTextDelta(event.delta.text);
+          } else if (event.delta.type === 'input_json_delta') {
+            currentToolJson += event.delta.partial_json;
+          }
+          break;
+
+        case 'content_block_stop':
+          if (currentToolId) {
+            toolCalls.push({
+              id: currentToolId,
+              type: 'function' as const,
+              function: {
+                name: currentToolName,
+                arguments: currentToolJson || '{}',
+              },
+            });
+            currentToolId = '';
+            currentToolName = '';
+            currentToolJson = '';
+          }
+          break;
+
+        case 'message_delta':
+          if (event.usage) {
+            usage.output_tokens = event.usage.output_tokens;
+          }
+          stopReason = event.delta.stop_reason;
+          break;
+      }
+    }
+  } catch (err) {
+    if (err instanceof Error && err.name === 'AbortError') {
+      return buildPartialResult(textParts, toolCalls, usage, model);
+    }
+    throw err;
+  }
+
+  // If aborted via break (not via catch), return partial response
+  if (signal?.aborted) {
+    return buildPartialResult(textParts, toolCalls, usage, model);
+  }
+
+  const textContent = textParts.join('') || '';
+
+  const result: TUniversalMessage = {
+    id: randomUUID(),
+    role: 'assistant',
+    content: textContent,
+    state: 'complete' as const,
+    timestamp: new Date(),
+    ...(toolCalls.length > 0 && { toolCalls }),
+  };
+
+  result.metadata = {
+    inputTokens: usage.input_tokens,
+    outputTokens: usage.output_tokens,
+    model,
+  };
+  if (stopReason) {
+    result.metadata['stopReason'] = stopReason;
+  }
+
+  return result;
+}
+
+function buildPartialResult(
+  textParts: string[],
+  toolCalls: Array<{
+    id: string;
+    type: 'function';
+    function: { name: string; arguments: string };
+  }>,
+  usage: { input_tokens: number; output_tokens: number },
+  model: string,
+): TUniversalMessage {
+  const partialText = textParts.join('') || '';
+  const partialResult: TUniversalMessage = {
+    id: randomUUID(),
+    role: 'assistant',
+    content: partialText,
+    state: 'complete' as const,
+    timestamp: new Date(),
+    ...(toolCalls.length > 0 && { toolCalls }),
+  };
+  partialResult.metadata = {
+    inputTokens: usage.input_tokens,
+    outputTokens: usage.output_tokens,
+    model,
+    stopReason: 'aborted',
+  };
+  return partialResult;
+}
+
+/**
+ * Wrap a stream to support abort signal interruption.
+ */
+async function* streamWithAbort(
+  stream: AsyncIterable<Anthropic.MessageStreamEvent>,
+  signal?: AbortSignal,
+): AsyncIterable<Anthropic.MessageStreamEvent> {
+  for await (const event of stream) {
+    if (signal?.aborted) break;
+    yield event;
+  }
+}

package/src/anthropic/types/api-types.ts

@@ -0,0 +1,158 @@
+/**
+ * Anthropic API-specific type definitions
+ *
+ * This file contains type definitions specific to Anthropic's Claude API,
+ * ensuring complete type safety without any/unknown types.
+ */
+
+// Anthropic Message Types
+export interface IAnthropicMessage {
+  id: string;
+  type: 'message';
+  role: 'assistant' | 'user';
+  content: IAnthropicContent[];
+  model: string;
+  stop_reason: 'end_turn' | 'max_tokens' | 'stop_sequence' | 'tool_use' | null;
+  stop_sequence: string | null;
+  usage: IAnthropicUsage;
+}
+
+export interface IAnthropicContent {
+  type: 'text' | 'tool_use';
+  text?: string;
+  id?: string;
+  name?: string;
+  input?: Record<string, string | number | boolean | object>;
+}
+
+export interface IAnthropicUsage {
+  input_tokens: number;
+  output_tokens: number;
+}
+
+// Request Types
+export interface IAnthropicChatRequestParams {
+  model: string;
+  max_tokens: number;
+  messages: IAnthropicRequestMessage[];
+  system?: string;
+  temperature?: number;
+  top_p?: number;
+  top_k?: number;
+  stop_sequences?: string[];
+  tools?: IAnthropicTool[];
+  stream?: false;
+}
+
+export interface IAnthropicStreamRequestParams extends Omit<IAnthropicChatRequestParams, 'stream'> {
+  stream: true;
+}
+
+export interface IAnthropicRequestMessage {
+  role: 'user' | 'assistant';
+  content: string | IAnthropicRequestContent[];
+}
+
+export interface IAnthropicRequestContent {
+  type: 'text' | 'tool_use' | 'tool_result';
+  text?: string;
+  id?: string;
+  name?: string;
+  input?: Record<string, string | number | boolean | object>;
+  content?: string;
+  tool_use_id?: string;
+}
+
+// Tool Types
+export interface IAnthropicTool {
+  name: string;
+  description?: string;
+  input_schema: {
+    type: 'object';
+    properties: Record<string, IAnthropicToolProperty>;
+    required?: string[];
+  };
+}
+
+export interface IAnthropicToolProperty {
+  type: 'string' | 'number' | 'integer' | 'boolean' | 'array' | 'object';
+  description?: string;
+  enum?: string[];
+  items?: IAnthropicToolProperty;
+  properties?: Record<string, IAnthropicToolProperty>;
+}
+
+export interface IAnthropicToolCall {
+  id: string;
+  type: 'tool_use';
+  name: string;
+  input: Record<string, string | number | boolean | object>;
+}
+
+// Streaming Types
+export interface IAnthropicStreamChunk {
+  type:
+    | 'message_start'
+    | 'message_delta'
+    | 'content_block_start'
+    | 'content_block_delta'
+    | 'content_block_stop'
+    | 'message_stop';
+  message?: Partial<IAnthropicMessage>;
+  delta?: IAnthropicStreamDelta;
+  content_block?: IAnthropicContent;
+  index?: number;
+}
+
+export interface IAnthropicStreamDelta {
+  type?: 'text_delta' | 'input_json_delta';
+  text?: string;
+  partial_json?: string;
+  stop_reason?: 'end_turn' | 'max_tokens' | 'stop_sequence' | 'tool_use';
+  stop_sequence?: string;
+}
+
+// Error Types
+export interface IAnthropicError {
+  type: 'error';
+  error: {
+    type:
+      | 'invalid_request_error'
+      | 'authentication_error'
+      | 'permission_error'
+      | 'not_found_error'
+      | 'rate_limit_error'
+      | 'api_error'
+      | 'overloaded_error';
+    message: string;
+    param?: string;
+    code?: string;
+  };
+}
+
+// Provider Configuration
+export interface IAnthropicLogData {
+  model: string;
+  messagesCount: number;
+  hasTools: boolean;
+  maxTokens?: number;
+  temperature?: number;
+  timestamp: string;
+  requestId?: string;
+  usage?: IAnthropicUsage;
+}
+
+// Response Types for Internal Processing
+export interface IAnthropicProviderResponse {
+  message: IAnthropicMessage;
+  usage: IAnthropicUsage;
+  model: string;
+}
+
+// Stream Handler Types
+export interface IAnthropicStreamContext {
+  currentMessage: string;
+  currentToolCalls: IAnthropicToolCall[];
+  isComplete: boolean;
+  usage?: IAnthropicUsage;
+}

package/src/anthropic/types.ts

@@ -0,0 +1,79 @@
+import Anthropic from '@anthropic-ai/sdk';
+import type { IExecutor, TProviderOptionValueBase } from '@robota-sdk/agent-core';
+
+/**
+ * Valid provider option value types
+ */
+export type TAnthropicProviderOptionValue =
+  | string
+  | number
+  | boolean
+  | undefined
+  | null
+  | Anthropic
+  | IExecutor
+  | TProviderOptionValueBase
+  | TAnthropicProviderOptionValue[]
+  | { [key: string]: TAnthropicProviderOptionValue };
+
+/**
+ * Anthropic provider options
+ *
+ * Note: Anthropic API doesn't support response format configuration.
+ * JSON output can be requested through prompt instructions.
+ */
+export interface IAnthropicProviderOptions {
+  /**
+   * Additional provider-specific options
+   */
+  [key: string]: TAnthropicProviderOptionValue;
+
+  /**
+   * Anthropic API key (required when client and executor are not provided)
+   */
+  apiKey?: string;
+
+  /**
+   * API request timeout (milliseconds)
+   */
+  timeout?: number;
+
+  /**
+   * API base URL
+   */
+  baseURL?: string;
+
+  /**
+   * Anthropic client instance (optional: will be created from apiKey if not provided)
+   * Use this path for advanced Anthropic SDK authentication that is outside
+   * Robota's normal API-key setup flow.
+   */
+  client?: Anthropic;
+
+  /**
+   * 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('anthropic', new AnthropicProvider({ apiKey: 'sk-ant-...' }));
+   *
+   * // Remote execution
+   * const remoteExecutor = new RemoteExecutor({
+   *   serverUrl: 'https://api.robota.io',
+   *   userApiKey: 'user-token-123'
+   * });
+   *
+   * const provider = new AnthropicProvider({
+   *   executor: remoteExecutor // No direct API key needed
+   * });
+   * ```
+   */
+  executor?: IExecutor;
+}