@providerprotocol/ai 0.0.14 → 0.0.15

package/dist/anthropic/index.d.ts

@@ -50,7 +50,432 @@ interface AnthropicLLMParams {
      * - `standard_only`: Only use standard capacity, never priority
      */
     service_tier?: 'auto' | 'standard_only';
+    /**
+     * Built-in tools for server-side execution.
+     *
+     * Use the tool helper constructors from the `tools` namespace:
+     * - `tools.webSearch()` - Web search capability
+     * - `tools.computer()` - Computer use (mouse, keyboard, screenshots)
+     * - `tools.textEditor()` - File viewing and editing
+     * - `tools.bash()` - Shell command execution
+     * - `tools.codeExecution()` - Sandboxed Python/Bash execution
+     * - `tools.toolSearch()` - Dynamic tool catalog search
+     *
+     * @example
+     * ```typescript
+     * import { anthropic, tools } from 'provider-protocol/anthropic';
+     *
+     * const model = llm({
+     *   model: anthropic('claude-sonnet-4-20250514'),
+     *   params: {
+     *     builtInTools: [
+     *       tools.webSearch({ max_uses: 5 }),
+     *       tools.codeExecution(),
+     *     ],
+     *   },
+     * });
+     * ```
+     */
+    builtInTools?: AnthropicBuiltInTool[];
+    /**
+     * Container ID for code execution tool reuse.
+     * Pass the container ID from a previous response to reuse the same environment.
+     */
+    container?: string;
+}
+/**
+ * Anthropic-specific HTTP headers for API requests.
+ *
+ * @example
+ * ```typescript
+ * const headers: AnthropicHeaders = {
+ *   'anthropic-beta': 'extended-cache-ttl-2025-04-11',
+ * };
+ * ```
+ */
+interface AnthropicHeaders {
+    /**
+     * Beta features header.
+     *
+     * Comma-separated list of beta feature flags:
+     * - `extended-cache-ttl-2025-04-11` - Enable 1-hour cache TTL
+     * - `token-efficient-tools-2025-02-19` - Token-efficient tool encoding
+     * - `computer-use-2025-01-24` - Computer use tool (Claude 4 models)
+     * - `computer-use-2025-11-24` - Computer use tool (Claude Opus 4.5)
+     * - `code-execution-2025-08-25` - Code execution tool
+     * - `advanced-tool-use-2025-11-20` - Tool search tool
+     */
+    'anthropic-beta'?: string;
+    [key: string]: string | undefined;
+}
+/**
+ * User location for web search context.
+ *
+ * Used to localize web search results based on the user's approximate location.
+ */
+interface AnthropicUserLocation {
+    /** Location type - must be 'approximate' */
+    type: 'approximate';
+    /** City name */
+    city?: string;
+    /** Region/state name */
+    region?: string;
+    /** ISO 3166-1 alpha-2 country code (e.g., "US") */
+    country?: string;
+    /** IANA timezone (e.g., "America/New_York") */
+    timezone?: string;
+}
+/**
+ * Web search tool for real-time web information retrieval.
+ *
+ * Enables Claude to search the web for up-to-date information.
+ * No beta header required - this is a GA feature.
+ *
+ * @example
+ * ```typescript
+ * const tool: AnthropicWebSearchTool = {
+ *   type: 'web_search_20250305',
+ *   name: 'web_search',
+ *   max_uses: 5,
+ *   allowed_domains: ['wikipedia.org', 'github.com'],
+ * };
+ * ```
+ */
+interface AnthropicWebSearchTool {
+    /** Tool type identifier */
+    type: 'web_search_20250305';
+    /** Tool name - must be 'web_search' */
+    name: 'web_search';
+    /** Maximum searches per request (default: unlimited) */
+    max_uses?: number;
+    /** Whitelist domains (mutually exclusive with blocked_domains) */
+    allowed_domains?: string[];
+    /** Blacklist domains (mutually exclusive with allowed_domains) */
+    blocked_domains?: string[];
+    /** User location for localized results */
+    user_location?: AnthropicUserLocation;
+}
+/**
+ * Computer use tool for desktop automation.
+ *
+ * Enables Claude to interact with computer interfaces through
+ * mouse clicks, keyboard input, and screenshots.
+ *
+ * Requires beta header:
+ * - `computer-use-2025-11-24` for Claude Opus 4.5
+ * - `computer-use-2025-01-24` for other Claude 4 models
+ *
+ * @example
+ * ```typescript
+ * const tool: AnthropicComputerTool = {
+ *   type: 'computer_20250124',
+ *   name: 'computer',
+ *   display_width_px: 1920,
+ *   display_height_px: 1080,
+ * };
+ * ```
+ */
+interface AnthropicComputerTool {
+    /** Tool type identifier (version-specific) */
+    type: 'computer_20251124' | 'computer_20250124';
+    /** Tool name - must be 'computer' */
+    name: 'computer';
+    /** Display width in pixels */
+    display_width_px: number;
+    /** Display height in pixels */
+    display_height_px: number;
+    /** X11 display number (optional) */
+    display_number?: number;
+    /** Enable zoom action (Opus 4.5 only with 20251124 version) */
+    enable_zoom?: boolean;
+}
+/**
+ * Text editor tool for file viewing and editing.
+ *
+ * Enables Claude to view, create, and edit files with
+ * commands like view, str_replace, create, and insert.
+ *
+ * No beta header required.
+ *
+ * @example
+ * ```typescript
+ * const tool: AnthropicTextEditorTool = {
+ *   type: 'text_editor_20250728',
+ *   name: 'str_replace_based_edit_tool',
+ *   max_characters: 10000,
+ * };
+ * ```
+ */
+interface AnthropicTextEditorTool {
+    /** Tool type identifier (version-specific) */
+    type: 'text_editor_20250728' | 'text_editor_20250124';
+    /** Tool name (version-specific) */
+    name: 'str_replace_based_edit_tool' | 'str_replace_editor';
+    /** Max characters for view truncation (20250728+ only) */
+    max_characters?: number;
+}
+/**
+ * Bash tool for shell command execution.
+ *
+ * Enables Claude to execute bash commands in a shell session.
+ * The session persists within the conversation.
+ *
+ * No beta header required.
+ *
+ * @example
+ * ```typescript
+ * const tool: AnthropicBashTool = {
+ *   type: 'bash_20250124',
+ *   name: 'bash',
+ * };
+ * ```
+ */
+interface AnthropicBashTool {
+    /** Tool type identifier */
+    type: 'bash_20250124';
+    /** Tool name - must be 'bash' */
+    name: 'bash';
 }
+/**
+ * Code execution tool for sandboxed Python/Bash execution.
+ *
+ * Enables Claude to write and execute code in a secure container
+ * with pre-installed data science libraries.
+ *
+ * Requires beta header: `code-execution-2025-08-25`
+ *
+ * @example
+ * ```typescript
+ * const tool: AnthropicCodeExecutionTool = {
+ *   type: 'code_execution_20250825',
+ *   name: 'code_execution',
+ * };
+ * ```
+ */
+interface AnthropicCodeExecutionTool {
+    /** Tool type identifier */
+    type: 'code_execution_20250825';
+    /** Tool name - must be 'code_execution' */
+    name: 'code_execution';
+}
+/**
+ * Tool search tool for dynamic tool discovery.
+ *
+ * Enables Claude to search through large tool catalogs
+ * using regex or natural language (BM25) queries.
+ *
+ * Requires beta header: `advanced-tool-use-2025-11-20`
+ *
+ * @example
+ * ```typescript
+ * const tool: AnthropicToolSearchTool = {
+ *   type: 'tool_search_tool_regex_20251119',
+ *   name: 'tool_search_tool_regex',
+ * };
+ * ```
+ */
+interface AnthropicToolSearchTool {
+    /** Tool type identifier (regex or BM25 variant) */
+    type: 'tool_search_tool_regex_20251119' | 'tool_search_tool_bm25_20251119';
+    /** Tool name (must match type variant) */
+    name: 'tool_search_tool_regex' | 'tool_search_tool_bm25';
+}
+/**
+ * Union type for all Anthropic built-in tools.
+ *
+ * Built-in tools run server-side and have special handling
+ * different from user-defined function tools.
+ */
+type AnthropicBuiltInTool = AnthropicWebSearchTool | AnthropicComputerTool | AnthropicTextEditorTool | AnthropicBashTool | AnthropicCodeExecutionTool | AnthropicToolSearchTool;
+/**
+ * Creates a web search tool configuration.
+ *
+ * The web search tool enables Claude to search the web for up-to-date information.
+ * Pricing: $10 per 1,000 searches plus standard token costs.
+ *
+ * @param options - Optional configuration for search behavior
+ * @returns A web search tool configuration object
+ *
+ * @example
+ * ```typescript
+ * // Basic web search
+ * const search = webSearchTool();
+ *
+ * // With configuration
+ * const searchWithOptions = webSearchTool({
+ *   max_uses: 5,
+ *   allowed_domains: ['wikipedia.org', 'github.com'],
+ *   user_location: {
+ *     type: 'approximate',
+ *     city: 'San Francisco',
+ *     country: 'US',
+ *   },
+ * });
+ * ```
+ */
+declare function webSearchTool(options?: {
+    max_uses?: number;
+    allowed_domains?: string[];
+    blocked_domains?: string[];
+    user_location?: AnthropicUserLocation;
+}): AnthropicWebSearchTool;
+/**
+ * Creates a computer use tool configuration.
+ *
+ * The computer tool enables Claude to interact with computer interfaces
+ * through mouse clicks, keyboard input, and screenshots.
+ *
+ * Requires beta header (automatically injected when using this tool):
+ * - `computer-use-2025-11-24` for Claude Opus 4.5
+ * - `computer-use-2025-01-24` for other models
+ *
+ * @param options - Display configuration and optional settings
+ * @returns A computer tool configuration object
+ *
+ * @example
+ * ```typescript
+ * const computer = computerTool({
+ *   display_width_px: 1920,
+ *   display_height_px: 1080,
+ * });
+ *
+ * // For Opus 4.5 with zoom support
+ * const computerOpus = computerTool({
+ *   display_width_px: 1920,
+ *   display_height_px: 1080,
+ *   version: '20251124',
+ *   enable_zoom: true,
+ * });
+ * ```
+ */
+declare function computerTool(options: {
+    display_width_px: number;
+    display_height_px: number;
+    display_number?: number;
+    enable_zoom?: boolean;
+    /** Use '20251124' for Claude Opus 4.5, '20250124' for other models */
+    version?: '20251124' | '20250124';
+}): AnthropicComputerTool;
+/**
+ * Creates a text editor tool configuration.
+ *
+ * The text editor tool enables Claude to view, create, and edit files
+ * using commands like view, str_replace, create, and insert.
+ *
+ * Token overhead: ~700 tokens per tool definition.
+ *
+ * @param options - Optional configuration
+ * @returns A text editor tool configuration object
+ *
+ * @example
+ * ```typescript
+ * const editor = textEditorTool();
+ *
+ * // With max characters for view truncation
+ * const editorWithLimit = textEditorTool({
+ *   max_characters: 10000,
+ * });
+ * ```
+ */
+declare function textEditorTool(options?: {
+    max_characters?: number;
+    /** Use '20250728' for Claude 4, '20250124' for Claude 3.7 */
+    version?: '20250728' | '20250124';
+}): AnthropicTextEditorTool;
+/**
+ * Creates a bash tool configuration.
+ *
+ * The bash tool enables Claude to execute shell commands.
+ * Sessions persist within the conversation.
+ *
+ * Token overhead: ~245 tokens per tool definition.
+ *
+ * @returns A bash tool configuration object
+ *
+ * @example
+ * ```typescript
+ * const bash = bashTool();
+ * ```
+ */
+declare function bashTool(): AnthropicBashTool;
+/**
+ * Creates a code execution tool configuration.
+ *
+ * The code execution tool enables Claude to write and execute
+ * Python/Bash code in a secure sandboxed container.
+ *
+ * Requires beta header: `code-execution-2025-08-25` (automatically injected).
+ *
+ * Pricing:
+ * - Free tier: 1,550 hours/month per organization
+ * - Additional: $0.05 per hour, per container
+ *
+ * @returns A code execution tool configuration object
+ *
+ * @example
+ * ```typescript
+ * const codeExec = codeExecutionTool();
+ * ```
+ */
+declare function codeExecutionTool(): AnthropicCodeExecutionTool;
+/**
+ * Creates a tool search tool configuration.
+ *
+ * The tool search tool enables Claude to search through large
+ * tool catalogs (up to 10,000 tools) using regex or natural language.
+ *
+ * Requires beta header: `advanced-tool-use-2025-11-20` (automatically injected).
+ *
+ * @param options - Optional mode selection
+ * @returns A tool search tool configuration object
+ *
+ * @example
+ * ```typescript
+ * // Regex-based search (default)
+ * const search = toolSearchTool();
+ *
+ * // Natural language (BM25) search
+ * const nlSearch = toolSearchTool({ mode: 'bm25' });
+ * ```
+ */
+declare function toolSearchTool(options?: {
+    /** Search mode: 'regex' for pattern matching, 'bm25' for natural language */
+    mode?: 'regex' | 'bm25';
+}): AnthropicToolSearchTool;
+/**
+ * Namespace object containing all Anthropic tool helper constructors.
+ *
+ * Provides a convenient way to create built-in tool configurations.
+ *
+ * @example
+ * ```typescript
+ * import { anthropic, tools } from 'provider-protocol/anthropic';
+ *
+ * const model = llm({
+ *   model: anthropic('claude-sonnet-4-20250514'),
+ *   params: {
+ *     builtInTools: [
+ *       tools.webSearch({ max_uses: 5 }),
+ *       tools.codeExecution(),
+ *     ],
+ *   },
+ * });
+ * ```
+ */
+declare const tools: {
+    /** Creates a web search tool configuration */
+    webSearch: typeof webSearchTool;
+    /** Creates a computer use tool configuration */
+    computer: typeof computerTool;
+    /** Creates a text editor tool configuration */
+    textEditor: typeof textEditorTool;
+    /** Creates a bash tool configuration */
+    bash: typeof bashTool;
+    /** Creates a code execution tool configuration */
+    codeExecution: typeof codeExecutionTool;
+    /** Creates a tool search tool configuration */
+    toolSearch: typeof toolSearchTool;
+};
 
 /**
  * Anthropic provider instance for the Universal Provider Protocol.
@@ -74,4 +499,4 @@ interface AnthropicLLMParams {
  */
 declare const anthropic: Provider<unknown>;
 
-export { type AnthropicLLMParams, anthropic };
+export { type AnthropicBashTool, type AnthropicBuiltInTool, type AnthropicCodeExecutionTool, type AnthropicComputerTool, type AnthropicHeaders, type AnthropicLLMParams, type AnthropicTextEditorTool, type AnthropicToolSearchTool, type AnthropicUserLocation, type AnthropicWebSearchTool, anthropic, tools };

package/dist/anthropic/index.js

@@ -21,16 +21,24 @@ import {
 // src/providers/anthropic/transform.ts
 function transformRequest(request, modelId) {
   const params = request.params ?? {};
+  const { builtInTools, ...restParams } = params;
   const anthropicRequest = {
-    ...params,
+    ...restParams,
     model: modelId,
     messages: request.messages.map(transformMessage)
   };
   if (request.system) {
     anthropicRequest.system = request.system;
   }
+  const allTools = [];
   if (request.tools && request.tools.length > 0) {
-    anthropicRequest.tools = request.tools.map(transformTool);
+    allTools.push(...request.tools.map(transformTool));
+  }
+  if (builtInTools && builtInTools.length > 0) {
+    allTools.push(...builtInTools);
+  }
+  if (allTools.length > 0) {
+    anthropicRequest.tools = allTools;
     anthropicRequest.tool_choice = { type: "auto" };
   }
   if (request.structure) {
@@ -188,6 +196,20 @@ function transformResponse(data) {
         toolName: block.name,
         arguments: block.input
       });
+    } else if (block.type === "bash_code_execution_tool_result") {
+      if (block.content.type === "bash_code_execution_result" && block.content.stdout) {
+        textContent.push({ type: "text", text: `
+\`\`\`
+${block.content.stdout}\`\`\`
+` });
+      }
+    } else if (block.type === "text_editor_code_execution_tool_result") {
+      if (block.content.type === "text_editor_code_execution_result" && block.content.content) {
+        textContent.push({ type: "text", text: `
+\`\`\`
+${block.content.content}\`\`\`
+` });
+      }
     }
   }
   const message = new AssistantMessage(
@@ -249,6 +271,27 @@ function transformStreamEvent(event, state) {
           name: event.content_block.name,
           input: ""
         };
+      } else if (event.content_block.type === "server_tool_use") {
+        state.content[event.index] = {
+          type: "server_tool_use",
+          id: event.content_block.id,
+          name: event.content_block.name,
+          input: ""
+        };
+      } else if (event.content_block.type === "bash_code_execution_tool_result") {
+        const resultBlock = event.content_block;
+        state.content[event.index] = {
+          type: "bash_code_execution_tool_result",
+          tool_use_id: resultBlock.tool_use_id,
+          stdout: resultBlock.content?.stdout ?? ""
+        };
+      } else if (event.content_block.type === "text_editor_code_execution_tool_result") {
+        const resultBlock = event.content_block;
+        state.content[event.index] = {
+          type: "text_editor_code_execution_tool_result",
+          tool_use_id: resultBlock.tool_use_id,
+          fileContent: resultBlock.content?.content ?? ""
+        };
       }
       return { type: "content_block_start", index: event.index, delta: {} };
     case "content_block_delta": {
@@ -306,6 +349,7 @@ function buildResponseFromState(state) {
   const toolCalls = [];
   let structuredData;
   for (const block of state.content) {
+    if (!block) continue;
     if (block.type === "text" && block.text) {
       textContent.push({ type: "text", text: block.text });
     } else if (block.type === "tool_use" && block.id && block.name) {
@@ -324,6 +368,16 @@ function buildResponseFromState(state) {
         toolName: block.name,
         arguments: args
       });
+    } else if (block.type === "bash_code_execution_tool_result" && block.stdout) {
+      textContent.push({ type: "text", text: `
+\`\`\`
+${block.stdout}\`\`\`
+` });
+    } else if (block.type === "text_editor_code_execution_tool_result" && block.fileContent) {
+      textContent.push({ type: "text", text: `
+\`\`\`
+${block.fileContent}\`\`\`
+` });
     }
   }
   const message = new AssistantMessage(
@@ -518,6 +572,64 @@ function createLLMHandler() {
   };
 }
 
+// src/providers/anthropic/types.ts
+function webSearchTool(options) {
+  return {
+    type: "web_search_20250305",
+    name: "web_search",
+    ...options
+  };
+}
+function computerTool(options) {
+  const { version = "20250124", ...rest } = options;
+  return {
+    type: version === "20251124" ? "computer_20251124" : "computer_20250124",
+    name: "computer",
+    ...rest
+  };
+}
+function textEditorTool(options) {
+  const version = options?.version ?? "20250728";
+  return {
+    type: version === "20250728" ? "text_editor_20250728" : "text_editor_20250124",
+    name: version === "20250728" ? "str_replace_based_edit_tool" : "str_replace_editor",
+    ...options?.max_characters !== void 0 && { max_characters: options.max_characters }
+  };
+}
+function bashTool() {
+  return {
+    type: "bash_20250124",
+    name: "bash"
+  };
+}
+function codeExecutionTool() {
+  return {
+    type: "code_execution_20250825",
+    name: "code_execution"
+  };
+}
+function toolSearchTool(options) {
+  const mode = options?.mode ?? "regex";
+  return {
+    type: mode === "regex" ? "tool_search_tool_regex_20251119" : "tool_search_tool_bm25_20251119",
+    name: mode === "regex" ? "tool_search_tool_regex" : "tool_search_tool_bm25"
+  };
+}
+var tools = {
+  /** Creates a web search tool configuration */
+  webSearch: webSearchTool,
+  /** Creates a computer use tool configuration */
+  computer: computerTool,
+  /** Creates a text editor tool configuration */
+  textEditor: textEditorTool,
+  /** Creates a bash tool configuration */
+  bash: bashTool,
+  /** Creates a code execution tool configuration */
+  codeExecution: codeExecutionTool,
+  /** Creates a tool search tool configuration */
+  toolSearch: toolSearchTool
+};
+
 // src/providers/anthropic/index.ts
 var anthropic = createProvider({
   name: "anthropic",
@@ -527,6 +639,7 @@ var anthropic = createProvider({
   }
 });
 export {
-  anthropic
+  anthropic,
+  tools
 };
 //# sourceMappingURL=index.js.map