The best way to control Claude Code, Codex and more from any computer or phone

main
ts 2,724 lines 77.1 KB
Raw
1 /**
2 * The `AnthropicTool` module defines Anthropic provider tools and the schemas
3 * for their inputs and results. It covers Anthropic-owned tools such as Bash,
4 * Code Execution, Computer Use, Memory, Text Editor, Web Search, Web Fetch, and
5 * Tool Search, which can be attached to Anthropic-backed Effect AI language
6 * model requests.
7 *
8 * @stability unstable
9 * @since 4.0.0
10 */
11 import * as Tool from "effect/ai/Tool"
12 import * as Context from "effect/Context"
13 import * as Schema from "effect/Schema"
14 import * as Generated from "./Generated.ts"
15
16 /**
17 * Union of all Anthropic provider-defined tool definitions exported by this module.
18 *
19 * **When to use**
20 *
21 * Use when a helper, collection, or option accepts any Anthropic
22 * provider-defined tool value created by this module.
23 *
24 * **Details**
25 *
26 * The union is built from the return types of the exported constructors,
27 * including Bash, Code Execution, Computer Use, Memory, Text Editor, Tool
28 * Search, Web Fetch, and Web Search tool versions.
29 *
30 * @stability unstable
31 * @category models
32 * @since 4.0.0
33 */
34 export type AnthropicTool =
35 | ReturnType<typeof Bash_20241022>
36 | ReturnType<typeof Bash_20250124>
37 | ReturnType<typeof CodeExecution_20250522>
38 | ReturnType<typeof CodeExecution_20250825>
39 | ReturnType<typeof ComputerUse_20241022>
40 | ReturnType<typeof ComputerUse_20250124>
41 | ReturnType<typeof ComputerUse_20251124>
42 | ReturnType<typeof Memory_20250818>
43 | ReturnType<typeof TextEditor_20241022>
44 | ReturnType<typeof TextEditor_20250124>
45 | ReturnType<typeof TextEditor_20250429>
46 | ReturnType<typeof TextEditor_20250728>
47 | ReturnType<typeof ToolSearchRegex_20251119>
48 | ReturnType<typeof ToolSearchBM25_20251119>
49 | ReturnType<typeof WebFetch_20250910>
50 | ReturnType<typeof WebSearch_20250305>
51
52 // =============================================================================
53 // Bash
54 // =============================================================================
55
56 /**
57 * Defines the Anthropic Bash tool (2024-10-22 version).
58 *
59 * **When to use**
60 *
61 * Use when you want the model to execute bash commands with the 2024-10-22
62 * Anthropic computer-use beta.
63 *
64 * **Details**
65 *
66 * Allows the model to execute bash commands in a sandboxed environment.
67 * Requires the "computer-use-2024-10-22" beta header.
68 *
69 * @see {@link Bash_20250124} for the newer 2025-01-24 version of the bash tool
70 *
71 * @stability unstable
72 * @category tools
73 * @since 4.0.0
74 */
75 export const Bash_20241022 = Tool.providerDefined({
76 id: "anthropic.bash_20241022",
77 customName: "AnthropicBash",
78 providerName: "bash",
79 requiresHandler: true,
80 success: Schema.String,
81 parameters: Schema.Struct({
82 command: Schema.String,
83 restart: Schema.optionalKey(Schema.Boolean)
84 })
85 })
86
87 /**
88 * Defines the Anthropic Bash tool (2025-01-24 version).
89 *
90 * **When to use**
91 *
92 * Use when you want the model to execute bash commands with the 2025-01-24
93 * Anthropic computer-use beta.
94 *
95 * **Details**
96 *
97 * Allows the model to execute bash commands in a sandboxed environment.
98 * Requires the "computer-use-2025-01-24" beta header.
99 *
100 * @see {@link Bash_20241022} for the older 2024-10-22 version of the bash tool
101 *
102 * @stability unstable
103 * @category tools
104 * @since 4.0.0
105 */
106 export const Bash_20250124 = Tool.providerDefined({
107 id: "anthropic.bash_20250124",
108 customName: "AnthropicBash",
109 providerName: "bash",
110 requiresHandler: true,
111 success: Schema.String,
112 parameters: Schema.Struct({
113 command: Schema.String,
114 restart: Schema.optionalKey(Schema.Boolean)
115 })
116 })
117
118 // =============================================================================
119 // Code Execution
120 // =============================================================================
121
122 // -----------------------------------------------------------------------------
123 // Code Execution 20250522 Parameters
124 // -----------------------------------------------------------------------------
125
126 /**
127 * Schema for a code execution request that asks Anthropic to run source code as a programmatic tool call.
128 *
129 * **When to use**
130 *
131 * Use when constructing or validating a programmatic tool call for the Anthropic
132 * Code Execution tool.
133 *
134 * @see {@link CodeExecution_20250522} for the parent tool definition
135 *
136 * @stability unstable
137 * @category schemas
138 * @since 4.0.0
139 */
140 export const CodeExecutionProgrammaticToolCall = Schema.Struct({
141 type: Schema.Literal("programmatic-tool-call"),
142 /**
143 * The code to execute.
144 */
145 code: Schema.String
146 })
147 /**
148 * Input payload for a programmatic code execution tool call, including the source code to execute.
149 *
150 * @stability unstable
151 * @category models
152 * @since 4.0.0
153 */
154 export type CodeExecutionProgrammaticToolCall = typeof CodeExecutionProgrammaticToolCall.Type
155
156 /**
157 * Schema for the `bash_code_execution` input variant of Anthropic Code Execution.
158 *
159 * **When to use**
160 *
161 * Use when validating or constructing a bash command request for
162 * `CodeExecution_20250522`.
163 *
164 * **Details**
165 *
166 * The schema requires `type` to be `"bash_code_execution"` and `command` to
167 * contain the bash command sent to Anthropic.
168 *
169 * @see {@link CodeExecution_20250522} for the provider-defined tool that consumes this input variant
170 *
171 * @stability unstable
172 * @category schemas
173 * @since 4.0.0
174 */
175 export const CodeExecutionBashCommand = Schema.Struct({
176 type: Schema.Literal("bash_code_execution"),
177 /**
178 * The bash command to execute.
179 */
180 command: Schema.String
181 })
182 /**
183 * Input payload for a bash command routed through the Anthropic code execution tool.
184 *
185 * **When to use**
186 *
187 * Use when representing a provider-executed bash command request for the
188 * 2025-05-22 code execution tool.
189 *
190 * **Details**
191 *
192 * The payload uses `type: "bash_code_execution"` to distinguish bash execution
193 * from programmatic code and text editor operations, and `command` contains the
194 * bash command to run.
195 *
196 * @see {@link CodeExecutionProgrammaticToolCall} for programmatic code execution input
197 * @see {@link CodeExecutionTextEditorView} for viewing files through text editor code execution
198 * @see {@link CodeExecutionTextEditorCreate} for creating files through text editor code execution
199 * @see {@link CodeExecutionTextEditorStrReplace} for replacing text through text editor code execution
200 * @see {@link CodeExecution_20250522} for the provider-defined tool that consumes this payload
201 *
202 * @stability unstable
203 * @category models
204 * @since 4.0.0
205 */
206 export type CodeExecutionBashCommand = typeof CodeExecutionBashCommand.Type
207
208 /**
209 * Schema for a code execution text editor request that views a file by path.
210 *
211 * **When to use**
212 *
213 * Use when you need the schema for provider-bound code-execution view requests
214 * before distinguishing them from create or replace text-editor commands.
215 *
216 * **Details**
217 *
218 * The encoded payload uses `type: "text_editor_code_execution"`,
219 * `command: "view"`, and a `path` string.
220 *
221 * @see {@link CodeExecutionTextEditorCreate} for the command that creates a file
222 * @see {@link CodeExecutionTextEditorStrReplace} for the command that replaces text in a file
223 *
224 * @stability unstable
225 * @category schemas
226 * @since 4.0.0
227 */
228 export const CodeExecutionTextEditorView = Schema.Struct({
229 type: Schema.Literal("text_editor_code_execution"),
230 command: Schema.Literal("view"),
231 /**
232 * Path to the file to view.
233 */
234 path: Schema.String
235 })
236 /**
237 * Input payload for the `view` command of Anthropic's text editor code execution tool.
238 *
239 * **When to use**
240 *
241 * Use when working at the Anthropic protocol boundary and the code-execution
242 * view request must be distinguished from standalone text-editor view requests.
243 *
244 * **Details**
245 *
246 * The payload is discriminated by `type: "text_editor_code_execution"` and
247 * `command: "view"`. The `path` field identifies the file to view.
248 *
249 * **Gotchas**
250 *
251 * This code execution view payload does not include `view_range`; line ranges
252 * are part of the standalone text editor view payload, not this code execution
253 * payload.
254 *
255 * @see {@link CodeExecution_20250522} for the provider-defined code execution tool that includes this payload
256 * @see {@link TextEditorViewCommand} for the standalone text editor view payload
257 *
258 * @stability unstable
259 * @category models
260 * @since 4.0.0
261 */
262 export type CodeExecutionTextEditorView = typeof CodeExecutionTextEditorView.Type
263
264 /**
265 * Schema for a text editor code execution request that creates a file at a path.
266 *
267 * **When to use**
268 *
269 * Use when validating or constructing an Anthropic `text_editor_code_execution`
270 * tool call that should create a file.
271 *
272 * **Details**
273 *
274 * The request is discriminated by `type: "text_editor_code_execution"` and
275 * `command: "create"`. It requires `path` and accepts optional `file_text`; the
276 * schema allows `file_text` to be omitted, `null`, or a string.
277 *
278 * @see {@link CodeExecution_20250522} for the provider-defined tool that consumes this request
279 * @see {@link CodeExecutionTextEditorView} for the matching view request
280 * @see {@link CodeExecutionTextEditorStrReplace} for the matching replace request
281 *
282 * @stability unstable
283 * @category schemas
284 * @since 4.0.0
285 */
286 export const CodeExecutionTextEditorCreate = Schema.Struct({
287 type: Schema.Literal("text_editor_code_execution"),
288 command: Schema.Literal("create"),
289 /**
290 * Path where the file should be created.
291 */
292 path: Schema.String,
293 /**
294 * The content to write to the new file.
295 */
296 file_text: Schema.optional(Schema.NullOr(Schema.String))
297 })
298 /**
299 * Input payload for creating a file through the text editor code execution tool, optionally including initial file text.
300 *
301 * @stability unstable
302 * @category models
303 * @since 4.0.0
304 */
305 export type CodeExecutionTextEditorCreate = typeof CodeExecutionTextEditorCreate.Type
306
307 /**
308 * Schema for a code execution text editor request that replaces one exact string in a file.
309 *
310 * **When to use**
311 *
312 * Use when validating or constructing the `str_replace` text editor operation
313 * for the 2025-05-22 Anthropic code execution tool.
314 *
315 * **Gotchas**
316 *
317 * The `old_str` must match the file contents exactly, including whitespace and
318 * indentation, and must identify a single occurrence.
319 *
320 * @see {@link CodeExecutionTextEditorView} for reading file contents before choosing the replacement text
321 * @see {@link CodeExecution_20250522} for the provider-defined tool that consumes this payload
322 *
323 * @stability unstable
324 * @category schemas
325 * @since 4.0.0
326 */
327 export const CodeExecutionTextEditorStrReplace = Schema.Struct({
328 type: Schema.Literal("text_editor_code_execution"),
329 command: Schema.Literal("str_replace"),
330 /**
331 * Path to the file to modify.
332 */
333 path: Schema.String,
334 /**
335 * The text to replace.
336 */
337 old_str: Schema.String,
338 /**
339 * The replacement text.
340 */
341 new_str: Schema.String
342 })
343 /**
344 * Input payload for replacing text in a file through the text editor code execution tool.
345 *
346 * @stability unstable
347 * @category models
348 * @since 4.0.0
349 */
350 export type CodeExecutionTextEditorStrReplace = typeof CodeExecutionTextEditorStrReplace.Type
351
352 const CodeExecution_20250522_Parameters = Schema.Union([
353 CodeExecutionProgrammaticToolCall,
354 CodeExecutionBashCommand,
355 CodeExecutionTextEditorView,
356 CodeExecutionTextEditorCreate,
357 CodeExecutionTextEditorStrReplace
358 ])
359
360 // -----------------------------------------------------------------------------
361 // Code Execution 20250825 Parameters
362 // -----------------------------------------------------------------------------
363
364 /**
365 * Schema for the 2025-08-25 code execution tool input, containing the code to execute.
366 *
367 * **When to use**
368 *
369 * Use when you need the schema for code-execution input at the Anthropic
370 * protocol boundary before sending source code to the 2025-08-25 tool.
371 *
372 * @see {@link CodeExecution_20250825} for the provider-defined tool that consumes this schema
373 *
374 * @stability unstable
375 * @category schemas
376 * @since 4.0.0
377 */
378 export const CodeExecution_20250825_Parameters = Schema.Struct({
379 /**
380 * The code to execute.
381 */
382 code: Schema.String
383 })
384 /**
385 * Input payload for the 2025-08-25 Anthropic code execution tool.
386 *
387 * **When to use**
388 *
389 * Use when exposing the 2025-08-25 code-execution payload separately from the
390 * provider tool definition, such as at a transport or persistence boundary.
391 *
392 * **Details**
393 *
394 * The payload has a single `code` field containing the source code string to
395 * execute.
396 *
397 * @see {@link CodeExecution_20250825} for the provider-defined tool that consumes this payload
398 *
399 * @stability unstable
400 * @category models
401 * @since 4.0.0
402 */
403 export type CodeExecution_20250825_Parameters = typeof CodeExecution_20250825_Parameters.Type
404
405 // -----------------------------------------------------------------------------
406 // Code Execution Tool Definitions
407 // -----------------------------------------------------------------------------
408
409 /**
410 * Defines the Anthropic Code Execution tool (2025-05-22 version).
411 *
412 * **When to use**
413 *
414 * Use when you want the model to execute code in a sandboxed environment with
415 * the 2025-05-22 Anthropic code-execution beta.
416 *
417 * **Details**
418 *
419 * Allows the model to execute code in a sandboxed environment with support
420 * for multiple execution types including programmatic tool calls, bash
421 * execution, and text editor operations.
422 *
423 * @see {@link CodeExecutionProgrammaticToolCall} for the programmatic tool call schema
424 *
425 * @stability unstable
426 * @category tools
427 * @since 4.0.0
428 */
429 export const CodeExecution_20250522 = Tool.providerDefined({
430 id: "anthropic.code_execution_20250522",
431 customName: "AnthropicCodeExecution",
432 providerName: "code_execution",
433 parameters: CodeExecution_20250522_Parameters,
434 success: Generated.BetaResponseCodeExecutionResultBlock,
435 failure: Generated.BetaResponseCodeExecutionToolResultError
436 })
437
438 /**
439 * Defines the Anthropic Code Execution tool (2025-08-25 version).
440 *
441 * **When to use**
442 *
443 * Use when you want the model to execute code in a sandboxed environment with
444 * the 2025-08-25 Anthropic code-execution beta.
445 *
446 * **Details**
447 *
448 * Requires the `code-execution-2025-08-25` beta header and uses
449 * `CodeExecution_20250825_Parameters` as its input schema.
450 *
451 * @see {@link CodeExecution_20250522} for the older 2025-05-22 code execution tool
452 * @see {@link CodeExecution_20250825_Parameters} for the input schema consumed by this tool
453 *
454 * @stability unstable
455 * @category tools
456 * @since 4.0.0
457 */
458 export const CodeExecution_20250825 = Tool.providerDefined({
459 id: "anthropic.code_execution_20250825",
460 customName: "AnthropicCodeExecution",
461 providerName: "code_execution",
462 parameters: CodeExecution_20250825_Parameters,
463 success: Schema.Union([
464 Generated.BetaResponseCodeExecutionResultBlock,
465 Generated.BetaResponseBashCodeExecutionResultBlock,
466 Generated.BetaResponseTextEditorCodeExecutionViewResultBlock,
467 Generated.BetaResponseTextEditorCodeExecutionCreateResultBlock,
468 Generated.BetaResponseTextEditorCodeExecutionStrReplaceResultBlock
469 ]),
470 failure: Schema.Union([
471 Generated.BetaResponseCodeExecutionToolResultError,
472 Generated.BetaResponseBashCodeExecutionToolResultError,
473 Generated.BetaResponseTextEditorCodeExecutionToolResultError
474 ])
475 })
476
477 // =============================================================================
478 // Computer Use
479 // =============================================================================
480
481 // -----------------------------------------------------------------------------
482 // Common Types
483 // -----------------------------------------------------------------------------
484
485 /**
486 * Schema for an `[x, y]` screen coordinate in pixels.
487 *
488 * **When to use**
489 *
490 * Use when validating computer-use action payloads that carry a single screen
491 * position and provider-side bounds checks remain acceptable.
492 *
493 * **Details**
494 *
495 * This is a two-number tuple used by computer-use actions that accept screen
496 * positions.
497 *
498 * **Gotchas**
499 *
500 * This schema validates tuple shape only and does not check display bounds.
501 *
502 * @stability unstable
503 * @category schemas
504 * @since 4.0.0
505 */
506 export const Coordinate = Schema.Tuple([Schema.Int, Schema.Int])
507 /**
508 * An `[x, y]` screen coordinate in pixels.
509 *
510 * @stability unstable
511 * @category models
512 * @since 4.0.0
513 */
514 export type Coordinate = typeof Coordinate.Type
515
516 /**
517 * Schema for an `[x1, y1, x2, y2]` screen region in pixels.
518 *
519 * **When to use**
520 *
521 * Use when validating computer-use action payloads that carry a rectangular
522 * screen region and provider-side bounds checks remain acceptable.
523 *
524 * **Details**
525 *
526 * The tuple represents top-left and bottom-right corners.
527 *
528 * **Gotchas**
529 *
530 * This schema validates four numbers only and does not check coordinate ordering
531 * or display bounds.
532 *
533 * @stability unstable
534 * @category schemas
535 * @since 4.0.0
536 */
537 export const Region = Schema.Tuple([Schema.Int, Schema.Int, Schema.Int, Schema.Int])
538 /**
539 * An `[x1, y1, x2, y2]` screen region in pixels, from top-left to bottom-right.
540 *
541 * @stability unstable
542 * @category models
543 * @since 4.0.0
544 */
545 export type Region = typeof Region.Type
546
547 /**
548 * Schema for scroll direction literals: `"up"`, `"down"`, `"left"`, or `"right"`.
549 *
550 * @see {@link ComputerUseScrollAction} for the action payload that consumes this schema
551 *
552 * @stability unstable
553 * @category schemas
554 * @since 4.0.0
555 */
556 export const ScrollDirection = Schema.Literals(["up", "down", "left", "right"])
557 /**
558 * Direction used by computer-use scroll actions: `"up"`, `"down"`, `"left"`, or `"right"`.
559 *
560 * @stability unstable
561 * @category models
562 * @since 4.0.0
563 */
564 export type ScrollDirection = typeof ScrollDirection.Type
565
566 /**
567 * Schema for modifier key literals.
568 *
569 * **Details**
570 *
571 * Allowed values are `"alt"`, `"ctrl"`, `"meta"`, and `"shift"`.
572 *
573 * @stability unstable
574 * @category schemas
575 * @since 4.0.0
576 */
577 export const ModifierKey = Schema.Literals(["alt", "ctrl", "meta", "shift"])
578 /**
579 * Modifier key literals.
580 *
581 * **Details**
582 *
583 * Allowed values are `"alt"`, `"ctrl"`, `"meta"`, and `"shift"`.
584 *
585 * @stability unstable
586 * @category models
587 * @since 4.0.0
588 */
589 export type ModifierKey = typeof ModifierKey.Type
590
591 // -----------------------------------------------------------------------------
592 // ComputerUse_20241022_Args
593 // -----------------------------------------------------------------------------
594
595 const ComputerUse_20241022_Args = Schema.Struct({
596 /**
597 * The width of the display being controlled by the model in pixels.
598 */
599 displayWidthPx: Schema.Int,
600
601 /**
602 * The height of the display being controlled by the model in pixels.
603 */
604 displayHeightPx: Schema.Int,
605
606 /**
607 * The display number to control (only relevant for X11 environments). If
608 * specified, the tool will be provided a display number in the tool
609 * definition.
610 */
611 displayNumber: Schema.optional(Schema.Int)
612 })
613
614 const ComputerUse_20251124_Args = Schema.Struct({
615 ...ComputerUse_20241022_Args.fields,
616 enableZoom: Schema.optional(Schema.Boolean)
617 })
618
619 // -----------------------------------------------------------------------------
620 // Computer Use 20241022 Actions
621 // -----------------------------------------------------------------------------
622
623 /**
624 * Schema for a computer-use action that presses a key or key combination, such
625 * as `"Return"`, `"ctrl+c"`, or `"ctrl+s"`.
626 *
627 * **When to use**
628 *
629 * Use when validating or constructing a computer-use action for keyboard
630 * shortcuts or non-text key presses.
631 *
632 * @see {@link TypeAction} for entering ordinary text strings
633 * @see {@link ComputerUseHoldKeyAction} for holding a key for a duration
634 *
635 * @stability unstable
636 * @category schemas
637 * @since 4.0.0
638 */
639 export const ComputerUseKeyAction = Schema.Struct({
640 action: Schema.Literal("key"),
641 /**
642 * The key to press.
643 */
644 text: Schema.String
645 })
646 /**
647 * Computer-use action payload for pressing a key or key combination.
648 *
649 * **When to use**
650 *
651 * Use when typing parsed computer-use key action payloads after schema
652 * validation, where provider-specific key-name validation is handled outside
653 * TypeScript.
654 *
655 * **Details**
656 *
657 * The payload uses `action: "key"` and stores the key or key combination to
658 * press in `text`, such as `"Return"`, `"ctrl+c"`, or `"ctrl+s"`.
659 *
660 * **Gotchas**
661 *
662 * `text` is typed as `string`; the paired schema does not validate
663 * provider-specific key names or key combinations.
664 *
665 * @stability unstable
666 * @category models
667 * @since 4.0.0
668 */
669 export type ComputerUseKeyAction = typeof ComputerUseKeyAction.Type
670
671 /**
672 * Schema for a computer-use action that performs a left click.
673 *
674 * **When to use**
675 *
676 * Use to validate or construct an Anthropic computer-use payload for clicking
677 * once at the current mouse position or at a specific screen coordinate.
678 *
679 * **Details**
680 *
681 * The encoded payload uses `action: "left_click"`. The optional `coordinate`
682 * field supplies the `[x, y]` pixel position; when omitted, the action uses the
683 * current mouse position.
684 *
685 * **Gotchas**
686 *
687 * The coordinate schema only checks that the value is a two-number tuple. It
688 * does not validate that the point falls within the configured display
689 * dimensions.
690 *
691 * @see {@link ComputerUseDoubleClickAction} for performing a double click
692 * @see {@link ComputerUseMouseMoveAction} for moving the mouse without clicking
693 *
694 * @stability unstable
695 * @category schemas
696 * @since 4.0.0
697 */
698 export const ComputerUseLeftClickAction = Schema.Struct({
699 action: Schema.Literal("left_click"),
700 /**
701 * The `[x, y]` coordinate on the screen to left click (defaults to the current
702 * mouse position if omitted).
703 */
704 coordinate: Schema.optionalKey(Coordinate)
705 })
706 /**
707 * Computer-use action payload for performing a left click, optionally at a specific coordinate.
708 *
709 * @stability unstable
710 * @category models
711 * @since 4.0.0
712 */
713 export type ComputerUseLeftClickAction = typeof ComputerUseLeftClickAction.Type
714
715 /**
716 * Schema for a computer-use action that moves the mouse cursor to a required
717 * `[x, y]` screen coordinate.
718 *
719 * **When to use**
720 *
721 * Use to validate or construct a mouse movement action for an Anthropic
722 * computer-use tool call.
723 *
724 * **Details**
725 *
726 * The encoded payload has action `"mouse_move"` and a required `coordinate`
727 * field containing the target `[x, y]` pixel position.
728 *
729 * **Gotchas**
730 *
731 * The coordinate schema only checks that the value is a two-number tuple. It
732 * does not validate that the point falls within the configured display
733 * dimensions.
734 *
735 * @stability unstable
736 * @category schemas
737 * @since 4.0.0
738 */
739 export const ComputerUseMouseMoveAction = Schema.Struct({
740 action: Schema.Literal("mouse_move"),
741 /**
742 * The `[x, y]` coordinate on the screen to move to.
743 */
744 coordinate: Coordinate
745 })
746 /**
747 * Computer-use action payload for moving the mouse cursor to a specific coordinate.
748 *
749 * @stability unstable
750 * @category models
751 * @since 4.0.0
752 */
753 export type ComputerUseMouseMoveAction = typeof ComputerUseMouseMoveAction.Type
754
755 /**
756 * Schema for a computer-use action that requests a screenshot of the current display.
757 *
758 * **When to use**
759 *
760 * Use to validate or construct a computer-use tool action that asks the handler
761 * to capture the full current display.
762 *
763 * **Details**
764 *
765 * The payload contains only `action: "screenshot"` and does not include
766 * coordinates or other options.
767 *
768 * @see {@link ComputerUseZoomAction} for requesting a zoomed-in screenshot of a specific screen region with the 2025-11-24 computer-use tool
769 *
770 * @stability unstable
771 * @category schemas
772 * @since 4.0.0
773 */
774 export const ComputerUseScreenshotAction = Schema.Struct({
775 action: Schema.Literal("screenshot")
776 })
777 /**
778 * Computer-use action payload for capturing the current display.
779 *
780 * @stability unstable
781 * @category models
782 * @since 4.0.0
783 */
784 export type ComputerUseScreenshotAction = typeof ComputerUseScreenshotAction.Type
785
786 /**
787 * Schema for a computer-use action that enters text.
788 *
789 * **When to use**
790 *
791 * Use to validate or construct a computer-use action for entering ordinary text
792 * strings.
793 *
794 * **Details**
795 *
796 * The payload uses `action: "type"` and a `text` string containing the text to
797 * enter.
798 *
799 * @see {@link ComputerUseKeyAction} for key presses and keyboard shortcuts
800 *
801 * @stability unstable
802 * @category schemas
803 * @since 4.0.0
804 */
805 export const TypeAction = Schema.Struct({
806 action: Schema.Literal("type"),
807 /**
808 * The text to type.
809 */
810 text: Schema.String
811 })
812 /**
813 * Computer-use action payload for typing a text string.
814 *
815 * **Details**
816 *
817 * The payload uses `action: "type"` and a `text` string containing the text to
818 * enter.
819 *
820 * @stability unstable
821 * @category models
822 * @since 4.0.0
823 */
824 export type TypeAction = typeof TypeAction.Type
825
826 const ComputerUse_20241022_Actions = Schema.Union([
827 ComputerUseKeyAction,
828 ComputerUseLeftClickAction,
829 ComputerUseMouseMoveAction,
830 ComputerUseScreenshotAction,
831 TypeAction
832 ])
833
834 // -----------------------------------------------------------------------------
835 // Computer Use 20250124 Actions
836 // -----------------------------------------------------------------------------
837
838 /**
839 * Schema for a computer-use action that performs a double click.
840 *
841 * **When to use**
842 *
843 * Use to validate or construct an Anthropic computer-use payload for double
844 * clicking at the current mouse position or at a specific screen coordinate.
845 *
846 * **Details**
847 *
848 * The encoded payload uses `action: "double_click"`. The optional
849 * `coordinate` field supplies the `[x, y]` pixel position; when omitted, the
850 * action uses the current mouse position.
851 *
852 * **Gotchas**
853 *
854 * The coordinate schema only checks that the value is a two-number tuple. It
855 * does not validate that the point falls within the configured display
856 * dimensions.
857 *
858 * @see {@link ComputerUseLeftClickAction} for performing a single left click
859 *
860 * @stability unstable
861 * @category schemas
862 * @since 4.0.0
863 */
864 export const ComputerUseDoubleClickAction = Schema.Struct({
865 action: Schema.Literal("double_click"),
866 /**
867 * The coordinate to double click (defaults to the current mouse position if
868 * omitted).
869 */
870 coordinate: Schema.optionalKey(Coordinate)
871 })
872 /**
873 * Computer-use action payload for performing a double click, optionally at a specific coordinate.
874 *
875 * @stability unstable
876 * @category models
877 * @since 4.0.0
878 */
879 export type ComputerUseDoubleClickAction = typeof ComputerUseDoubleClickAction.Type
880
881 /**
882 * Keeps a key pressed for a specified duration during computer-use execution.
883 *
884 * **When to use**
885 *
886 * Use to keep a keyboard key depressed for a fixed number of seconds in a
887 * computer-use action sequence.
888 *
889 * **Details**
890 *
891 * The schema describes objects with `action: "hold_key"`, a `text` field
892 * containing the key to hold, and a `duration` field containing the number of
893 * seconds to hold it.
894 *
895 * **Gotchas**
896 *
897 * The schema only checks that `duration` is a number; it does not require a
898 * positive value.
899 *
900 * @see {@link ComputerUseKeyAction} for pressing a key or key combination without holding it
901 * @see {@link ComputerUseWaitAction} for pausing between actions without holding a key
902 *
903 * @stability unstable
904 * @category schemas
905 * @since 4.0.0
906 */
907 export const ComputerUseHoldKeyAction = Schema.Struct({
908 action: Schema.Literal("hold_key"),
909 /**
910 * The key to hold (e.g. `"shift"`, `"ctrl"`).
911 */
912 text: Schema.String,
913 /**
914 * The number of seconds to hold the key.
915 */
916 duration: Schema.Finite
917 })
918 /**
919 * Computer-use action payload for holding a key for a specified duration.
920 *
921 * **When to use**
922 *
923 * Use to represent a key that should remain pressed for a measured interval.
924 *
925 * **Details**
926 *
927 * Set `action` to `"hold_key"`, `text` to the key to hold, and `duration` to
928 * the number of seconds to hold it.
929 *
930 * @see {@link ComputerUseKeyAction} for a single key press or key combination without a hold duration
931 *
932 * @stability unstable
933 * @category models
934 * @since 4.0.0
935 */
936 export type ComputerUseHoldKeyAction = typeof ComputerUseHoldKeyAction.Type
937
938 /**
939 * Schema for a computer-use action that drags with the left mouse button.
940 *
941 * **When to use**
942 *
943 * Use to validate or construct an Anthropic computer-use payload for dragging
944 * from one screen coordinate to another in a single action.
945 *
946 * **Details**
947 *
948 * The encoded payload uses `action: "left_click_drag"` and requires both
949 * `start_coordinate` and `coordinate` as `[x, y]` pixel positions.
950 *
951 * **Gotchas**
952 *
953 * The coordinate schema only checks that each value is a two-number tuple. It
954 * does not validate that either point falls within the configured display
955 * dimensions.
956 *
957 * @see {@link ComputerUseLeftMouseDownAction} for starting a manual drag sequence
958 * @see {@link ComputerUseLeftMouseUpAction} for ending a manual drag sequence
959 *
960 * @stability unstable
961 * @category schemas
962 * @since 4.0.0
963 */
964 export const ComputerUseLeftClickDragAction = Schema.Struct({
965 action: Schema.Literal("left_click_drag"),
966 /**
967 * The `[x, y]` coordinate to start dragging from.
968 */
969 start_coordinate: Coordinate,
970 /**
971 * The `[x, y]` coordinate to drag to.
972 */
973 coordinate: Coordinate
974 })
975 /**
976 * Computer-use action payload for dragging from a start coordinate to an end coordinate.
977 *
978 * @stability unstable
979 * @category models
980 * @since 4.0.0
981 */
982 export type ComputerUseLeftClickDragAction = typeof ComputerUseLeftClickDragAction.Type
983
984 /**
985 * Starts a left mouse button press without releasing it.
986 *
987 * **When to use**
988 *
989 * Use when constructing a manual click or drag sequence that should press and
990 * hold the left mouse button before a later release.
991 *
992 * @stability unstable
993 * @category schemas
994 * @since 4.0.0
995 */
996 export const ComputerUseLeftMouseDownAction = Schema.Struct({
997 action: Schema.Literal("left_mouse_down"),
998 /**
999 * The coordinate at which the left mouse button should be held down (defaults
1000 * to the current mouse position if omitted).
1001 */
1002 coordinate: Schema.optionalKey(Coordinate)
1003 })
1004 /**
1005 * Computer-use action payload for pressing and holding the left mouse button, optionally at a specific coordinate.
1006 *
1007 * @stability unstable
1008 * @category models
1009 * @since 4.0.0
1010 */
1011 export type ComputerUseLeftMouseDownAction = typeof ComputerUseLeftMouseDownAction.Type
1012
1013 /**
1014 * Releases the left mouse button.
1015 *
1016 * **When to use**
1017 *
1018 * Use when constructing a manual click or drag sequence that should release the
1019 * left mouse button after it was previously held down.
1020 *
1021 * @stability unstable
1022 * @category schemas
1023 * @since 4.0.0
1024 */
1025 export const ComputerUseLeftMouseUpAction = Schema.Struct({
1026 action: Schema.Literal("left_mouse_up"),
1027 /**
1028 * The coordinate at which the left mouse button should be released (defaults
1029 * to the current mouse position if omitted).
1030 */
1031 coordinate: Schema.optionalKey(Coordinate)
1032 })
1033 /**
1034 * Computer-use action payload for releasing the left mouse button, optionally at a specific coordinate.
1035 *
1036 * @stability unstable
1037 * @category models
1038 * @since 4.0.0
1039 */
1040 export type ComputerUseLeftMouseUpAction = typeof ComputerUseLeftMouseUpAction.Type
1041
1042 /**
1043 * Schema for a computer-use action that performs a middle click.
1044 *
1045 * **When to use**
1046 *
1047 * Use to validate or construct a middle-button click action for Anthropic
1048 * computer use, optionally targeting a specific screen coordinate.
1049 *
1050 * **Details**
1051 *
1052 * The payload must use `action: "middle_click"`. When `coordinate` is omitted,
1053 * the click occurs at the current mouse position.
1054 *
1055 * **Gotchas**
1056 *
1057 * This action is available in the 2025-01-24 computer-use action set and later;
1058 * it is not part of `ComputerUse_20241022`.
1059 *
1060 * @see {@link ComputerUse_20250124} for the provider-defined tool version that first accepts this action
1061 * @see {@link ComputerUseLeftClickAction} for primary-button clicks
1062 * @see {@link ComputerUseRightClickAction} for secondary-button clicks
1063 *
1064 * @stability unstable
1065 * @category schemas
1066 * @since 4.0.0
1067 */
1068 export const ComputerUseMiddleClickAction = Schema.Struct({
1069 action: Schema.Literal("middle_click"),
1070 /**
1071 * The coordinate to middle click (defaults to the current mouse position if
1072 * omitted).
1073 */
1074 coordinate: Schema.optionalKey(Coordinate)
1075 })
1076 /**
1077 * Computer-use action payload for performing a middle click, optionally at a specific coordinate.
1078 *
1079 * @stability unstable
1080 * @category models
1081 * @since 4.0.0
1082 */
1083 export type ComputerUseMiddleClickAction = typeof ComputerUseMiddleClickAction.Type
1084
1085 /**
1086 * Schema for a computer-use action that performs a right click, optionally at a
1087 * specific screen coordinate.
1088 *
1089 * **When to use**
1090 *
1091 * Use to validate or construct the `right_click` action for an Anthropic
1092 * computer-use tool call.
1093 *
1094 * **Details**
1095 *
1096 * The optional `coordinate` field is an `[x, y]` screen coordinate in pixels.
1097 * When omitted, the right click is performed at the current mouse position.
1098 *
1099 * @see {@link ComputerUse_20250124} for the provider-defined computer-use tool version that introduced this action
1100 * @see {@link ComputerUseLeftClickAction} for the corresponding left-click action
1101 * @see {@link ComputerUseMiddleClickAction} for the corresponding middle-click action
1102 *
1103 * @stability unstable
1104 * @category schemas
1105 * @since 4.0.0
1106 */
1107 export const ComputerUseRightClickAction = Schema.Struct({
1108 action: Schema.Literal("right_click"),
1109 /**
1110 * The coordinate to right click (defaults to the current mouse position if
1111 * omitted).
1112 */
1113 coordinate: Schema.optionalKey(Coordinate)
1114 })
1115 /**
1116 * Computer-use action payload for performing a right click, optionally at a specific coordinate.
1117 *
1118 * @stability unstable
1119 * @category models
1120 * @since 4.0.0
1121 */
1122 export type ComputerUseRightClickAction = typeof ComputerUseRightClickAction.Type
1123
1124 /**
1125 * Schema for a computer-use scroll action.
1126 *
1127 * **When to use**
1128 *
1129 * Use when validating or constructing Anthropic computer-use scroll payloads.
1130 *
1131 * **Details**
1132 *
1133 * The encoded payload uses `action: "scroll"`, an optional `coordinate`,
1134 * `scroll_direction`, and `scroll_amount`.
1135 *
1136 * **Gotchas**
1137 *
1138 * `coordinate` only checks a two-number tuple, and `scroll_amount` is only
1139 * `Schema.Int`.
1140 *
1141 * @see {@link ComputerUse_20250124} for the tool version that accepts this action
1142 * @see {@link ScrollDirection} for the accepted direction literals
1143 *
1144 * @stability unstable
1145 * @category schemas
1146 * @since 4.0.0
1147 */
1148 export const ComputerUseScrollAction = Schema.Struct({
1149 action: Schema.Literal("scroll"),
1150 /**
1151 * The coordinate to start scrolling from (defaults to the current mouse
1152 * position if omitted).
1153 */
1154 coordinate: Schema.optionalKey(Coordinate),
1155 /**
1156 * The direction to scroll.
1157 */
1158 scroll_direction: ScrollDirection,
1159 /**
1160 * The amount to scroll (in pixels or scroll units).
1161 */
1162 scroll_amount: Schema.Int
1163 })
1164 /**
1165 * Computer-use action payload for scrolling by a specified amount in a specified direction, optionally from a coordinate.
1166 *
1167 * @stability unstable
1168 * @category models
1169 * @since 4.0.0
1170 */
1171 export type ComputerUseScrollAction = typeof ComputerUseScrollAction.Type
1172
1173 /**
1174 * Schema for a computer-use triple-click action.
1175 *
1176 * **When to use**
1177 *
1178 * Use when validating or constructing Anthropic computer-use triple-click
1179 * payloads at the current pointer position or an optional coordinate.
1180 *
1181 * **Details**
1182 *
1183 * The encoded payload uses `action: "triple_click"` and an optional
1184 * `coordinate`.
1185 *
1186 * **Gotchas**
1187 *
1188 * `coordinate` only validates as a two-number tuple and does not check display
1189 * bounds.
1190 *
1191 * @see {@link ComputerUse_20250124} for the tool version that accepts this action
1192 * @see {@link ComputerUseDoubleClickAction} for the two-click variant
1193 * @see {@link ComputerUseLeftClickAction} for a single left click
1194 *
1195 * @stability unstable
1196 * @category schemas
1197 * @since 4.0.0
1198 */
1199 export const ComputerUseTripleClickAction = Schema.Struct({
1200 action: Schema.Literal("triple_click"),
1201 /**
1202 * The coordinate to triple click (defaults to the current mouse position if
1203 * omitted).
1204 */
1205 coordinate: Schema.optionalKey(Coordinate)
1206 })
1207 /**
1208 * Computer-use action payload for performing a triple click, optionally at a specific coordinate.
1209 *
1210 * @stability unstable
1211 * @category models
1212 * @since 4.0.0
1213 */
1214 export type ComputerUseTripleClickAction = typeof ComputerUseTripleClickAction.Type
1215
1216 /**
1217 * Schema for a computer-use wait action.
1218 *
1219 * **When to use**
1220 *
1221 * Use when validating or constructing Anthropic computer-use payloads that pause
1222 * between actions.
1223 *
1224 * **Details**
1225 *
1226 * The encoded payload uses `action: "wait"` and a required `duration` in
1227 * seconds.
1228 *
1229 * **Gotchas**
1230 *
1231 * `duration` is only `Schema.Finite`; it is not constrained to positive
1232 * values.
1233 *
1234 * @see {@link ComputerUseHoldKeyAction} for another duration-based computer-use action
1235 * @see {@link ComputerUse_20250124} for the tool version that accepts this action
1236 *
1237 * @stability unstable
1238 * @category schemas
1239 * @since 4.0.0
1240 */
1241 export const ComputerUseWaitAction = Schema.Struct({
1242 action: Schema.Literal("wait"),
1243 /**
1244 * The number of seconds to wait.
1245 */
1246 duration: Schema.Finite
1247 })
1248 /**
1249 * Computer-use action payload for pausing for a specified duration.
1250 *
1251 * @stability unstable
1252 * @category models
1253 * @since 4.0.0
1254 */
1255 export type ComputerUseWaitAction = typeof ComputerUseWaitAction.Type
1256
1257 const ComputerUse_20250124_Actions = Schema.Union([
1258 ...ComputerUse_20241022_Actions.members,
1259 ComputerUseDoubleClickAction,
1260 ComputerUseHoldKeyAction,
1261 ComputerUseLeftClickDragAction,
1262 ComputerUseLeftMouseDownAction,
1263 ComputerUseLeftMouseUpAction,
1264 ComputerUseMiddleClickAction,
1265 ComputerUseRightClickAction,
1266 ComputerUseScrollAction,
1267 ComputerUseTripleClickAction,
1268 ComputerUseWaitAction
1269 ])
1270
1271 // -----------------------------------------------------------------------------
1272 // Computer Use 20251124 Actions
1273 // -----------------------------------------------------------------------------
1274
1275 /**
1276 * Zooms into a specific region of the screen at full resolution.
1277 *
1278 * **When to use**
1279 *
1280 * Use when building or validating the 2025-11-24 computer-use action for a
1281 * zoom-enabled tool definition.
1282 *
1283 * **Details**
1284 *
1285 * The encoded payload uses `action: "zoom"` and a `region` tuple.
1286 *
1287 * **Gotchas**
1288 *
1289 * Requires `enableZoom: true` in the tool definition. `region` is only a
1290 * four-number tuple and does not validate corner ordering or display bounds.
1291 *
1292 * @see {@link ComputerUse_20251124} for the tool version that accepts this action
1293 * @see {@link ComputerUseScreenshotAction} for capturing the full screen instead
1294 *
1295 * @stability unstable
1296 * @category schemas
1297 * @since 4.0.0
1298 */
1299 export const ComputerUseZoomAction = Schema.Struct({
1300 action: Schema.Literal("zoom"),
1301 /**
1302 * Region to zoom into, defined as `[x1, y1, x2, y2]` coordinates where
1303 * `(x1, y1)` is the top-left corner and `(x2, y2)` is the bottom-right corner.
1304 */
1305 region: Region
1306 })
1307 /**
1308 * Computer-use action payload for zooming into a specific screen region.
1309 *
1310 * **Gotchas**
1311 *
1312 * The enclosing computer-use tool must be configured with `enableZoom: true`.
1313 * `region` is only a four-number tuple and does not validate corner ordering or
1314 * display bounds.
1315 *
1316 * @stability unstable
1317 * @category models
1318 * @since 4.0.0
1319 */
1320 export type ComputerUseZoomAction = typeof ComputerUseZoomAction.Type
1321
1322 const ComputerUse_20251124_Actions = Schema.Union([
1323 ...ComputerUse_20250124_Actions.members,
1324 ComputerUseZoomAction
1325 ])
1326
1327 // -----------------------------------------------------------------------------
1328 // Computer Use Tool Definitions
1329 // -----------------------------------------------------------------------------
1330
1331 /**
1332 * Defines the deprecated computer-use tool for Claude 3.5 Sonnet v2.
1333 *
1334 * **Details**
1335 *
1336 * Requires the "computer-use-2024-10-22" beta header.
1337 * Basic actions only: screenshot, left_click, type, key, mouse_move.
1338 *
1339 * @stability unstable
1340 * @category tools
1341 * @since 4.0.0
1342 */
1343 export const ComputerUse_20241022 = Tool.providerDefined({
1344 id: "anthropic.computer_use_20241022",
1345 customName: "AnthropicComputerUse",
1346 providerName: "computer",
1347 requiresHandler: true,
1348 args: ComputerUse_20241022_Args,
1349 parameters: ComputerUse_20241022_Actions,
1350 success: Schema.String
1351 })
1352
1353 /**
1354 * Defines the computer-use tool for Claude 4 models and Claude Sonnet 3.7.
1355 *
1356 * **When to use**
1357 *
1358 * Use when you need Anthropic computer use for Claude 4 models or Claude
1359 * Sonnet 3.7 with the 2025-01-24 action set.
1360 *
1361 * **Details**
1362 *
1363 * Requires the "computer-use-2025-01-24" beta header.
1364 * Includes basic actions plus enhanced actions: scroll, left_click_drag,
1365 * right_click, middle_click, double_click, triple_click, left_mouse_down,
1366 * left_mouse_up, hold_key, wait.
1367 *
1368 * @see {@link ComputerUse_20241022} for the older basic action set
1369 * @see {@link ComputerUse_20251124} for the newer zoom-capable version
1370 *
1371 * @stability unstable
1372 * @category tools
1373 * @since 4.0.0
1374 */
1375 export const ComputerUse_20250124 = Tool.providerDefined({
1376 id: "anthropic.computer_20250124",
1377 customName: "AnthropicComputerUse",
1378 providerName: "computer",
1379 requiresHandler: true,
1380 args: ComputerUse_20241022_Args,
1381 parameters: ComputerUse_20250124_Actions,
1382 success: Schema.String
1383 })
1384
1385 /**
1386 * Defines the computer-use tool for Claude Opus 4.5 only.
1387 *
1388 * **When to use**
1389 *
1390 * Use when you need Anthropic computer use for Claude Opus 4.5 with the
1391 * 2025-11-24 action set and zoom-capable screen inspection.
1392 *
1393 * **Details**
1394 *
1395 * Requires the "computer-use-2025-11-24" beta header.
1396 * Includes all actions from computer_20250124 plus the zoom action for
1397 * detailed screen region inspection.
1398 *
1399 * **Gotchas**
1400 *
1401 * Zoom actions require `enableZoom: true` in args.
1402 *
1403 * @see {@link ComputerUse_20250124} for the previous action set without zoom
1404 * @see {@link ComputerUseZoomAction} for the zoom action payload
1405 *
1406 * @stability unstable
1407 * @category tools
1408 * @since 4.0.0
1409 */
1410 export const ComputerUse_20251124 = Tool.providerDefined({
1411 id: "anthropic.computer_20251124",
1412 customName: "AnthropicComputerUse",
1413 providerName: "computer",
1414 requiresHandler: true,
1415 args: ComputerUse_20251124_Args,
1416 parameters: ComputerUse_20251124_Actions,
1417 success: Schema.String
1418 })
1419
1420 // =============================================================================
1421 // Memory
1422 // =============================================================================
1423
1424 // -----------------------------------------------------------------------------
1425 // Common Types
1426 // -----------------------------------------------------------------------------
1427
1428 /**
1429 * Defines a `[start, end]` line range for viewing file contents.
1430 *
1431 * **When to use**
1432 *
1433 * Use when constructing or validating `view_range` for memory or text editor
1434 * view commands.
1435 *
1436 * **Details**
1437 *
1438 * Lines are 1-indexed. Use `-1` for end to read to the end of the file. For
1439 * example, `[1, 50]` views lines 1-50 and `[100, -1]` views from line 100 to
1440 * the end of the file.
1441 *
1442 * @see {@link MemoryViewCommand} for memory view payloads that use this range
1443 * @see {@link TextEditorViewCommand} for text editor view payloads that use this range
1444 *
1445 * @stability unstable
1446 * @category schemas
1447 * @since 4.0.0
1448 */
1449 export const ViewRange = Schema.Tuple([Schema.Int, Schema.Int])
1450 /**
1451 * A `[start, end]` 1-indexed line range for viewing file contents, using `-1` as the end value to read through the end of the file.
1452 *
1453 * **When to use**
1454 *
1455 * Use when typing `view_range` for memory or text editor view commands.
1456 *
1457 * @stability unstable
1458 * @category models
1459 * @since 4.0.0
1460 */
1461 export type ViewRange = typeof ViewRange.Type
1462
1463 // -----------------------------------------------------------------------------
1464 // Memory 20250818 Commands
1465 // -----------------------------------------------------------------------------
1466
1467 /**
1468 * Schema for the memory tool command that creates a new file at a path.
1469 *
1470 * **Details**
1471 *
1472 * The payload contains `command: "create"`, a `path` string, and the
1473 * `file_text` content to write to the file.
1474 *
1475 * @stability unstable
1476 * @category schemas
1477 * @since 4.0.0
1478 */
1479 export const MemoryCreateCommand = Schema.Struct({
1480 command: Schema.Literal("create"),
1481 /**
1482 * The path to the file that should be created.
1483 */
1484 path: Schema.String,
1485 /**
1486 * The content to write to the file.
1487 */
1488 file_text: Schema.String
1489 })
1490 /**
1491 * Memory tool command payload for creating a new file at a path.
1492 *
1493 * @stability unstable
1494 * @category models
1495 * @since 4.0.0
1496 */
1497 export type MemoryCreateCommand = typeof MemoryCreateCommand.Type
1498
1499 /**
1500 * Schema for a memory command that deletes a file or directory.
1501 *
1502 * @stability unstable
1503 * @category schemas
1504 * @since 4.0.0
1505 */
1506 export const MemoryDeleteCommand = Schema.Struct({
1507 command: Schema.Literal("delete"),
1508 /**
1509 * The path to the file or directory to delete.
1510 */
1511 path: Schema.String
1512 })
1513 /**
1514 * Memory tool command payload for deleting a file or directory at a path.
1515 *
1516 * @stability unstable
1517 * @category models
1518 * @since 4.0.0
1519 */
1520 export type MemoryDeleteCommand = typeof MemoryDeleteCommand.Type
1521
1522 /**
1523 * Schema for the memory `insert` command.
1524 *
1525 * **When to use**
1526 *
1527 * Use when validating or constructing `insert` payloads for `Memory_20250818`.
1528 *
1529 * **Details**
1530 *
1531 * The payload is discriminated by `command: "insert"` and requires `path`,
1532 * `insert_line`, and `insert_text`.
1533 *
1534 * @see {@link Memory_20250818} for the provider-defined tool that consumes this command
1535 * @see {@link MemoryStrReplaceCommand} for replacing existing text instead
1536 *
1537 * @stability unstable
1538 * @category schemas
1539 * @since 4.0.0
1540 */
1541 export const MemoryInsertCommand = Schema.Struct({
1542 command: Schema.Literal("insert"),
1543 /**
1544 * The path to the file to insert text into.
1545 */
1546 path: Schema.String,
1547 /**
1548 * The line at which the text should be inserted.
1549 */
1550 insert_line: Schema.Int,
1551 /**
1552 * The text to insert.
1553 */
1554 insert_text: Schema.String
1555 })
1556 /**
1557 * Memory tool command payload for inserting text at a specific line in a file.
1558 *
1559 * @stability unstable
1560 * @category models
1561 * @since 4.0.0
1562 */
1563 export type MemoryInsertCommand = typeof MemoryInsertCommand.Type
1564
1565 /**
1566 * Schema for the memory command that renames or moves a file or directory.
1567 *
1568 * **Details**
1569 *
1570 * The payload uses `command: "rename"` and requires `old_path` as the current
1571 * path plus `new_path` as the new destination path.
1572 *
1573 * @stability unstable
1574 * @category schemas
1575 * @since 4.0.0
1576 */
1577 export const MemoryRenameCommand = Schema.Struct({
1578 command: Schema.Literal("rename"),
1579 /**
1580 * The old path to the file or directory.
1581 */
1582 old_path: Schema.String,
1583 /**
1584 * The new path to the file or directory.
1585 */
1586 new_path: Schema.String
1587 })
1588 /**
1589 * Memory tool command payload for renaming or moving a file or directory.
1590 *
1591 * @stability unstable
1592 * @category models
1593 * @since 4.0.0
1594 */
1595 export type MemoryRenameCommand = typeof MemoryRenameCommand.Type
1596
1597 /**
1598 * Schema for the memory `str_replace` command.
1599 *
1600 * **When to use**
1601 *
1602 * Use when validating or constructing `str_replace` payloads for
1603 * `Memory_20250818`.
1604 *
1605 * **Details**
1606 *
1607 * The payload is discriminated by `command: "str_replace"` and requires `path`,
1608 * `old_str`, and `new_str`.
1609 *
1610 * @see {@link Memory_20250818} for the provider-defined tool that consumes this command
1611 *
1612 * @stability unstable
1613 * @category schemas
1614 * @since 4.0.0
1615 */
1616 export const MemoryStrReplaceCommand = Schema.Struct({
1617 command: Schema.Literal("str_replace"),
1618 /**
1619 * The path to the file in which the replacement should occur.
1620 */
1621 path: Schema.String,
1622 /**
1623 * The text to replace.
1624 */
1625 old_str: Schema.String,
1626 /**
1627 * The replacement text.
1628 */
1629 new_str: Schema.String
1630 })
1631 /**
1632 * Memory tool command payload for replacing text in a file.
1633 *
1634 * @stability unstable
1635 * @category models
1636 * @since 4.0.0
1637 */
1638 export type MemoryStrReplaceCommand = typeof MemoryStrReplaceCommand.Type
1639
1640 /**
1641 * Shows directory contents or file contents with optional line ranges.
1642 *
1643 * **Details**
1644 *
1645 * When used on a file, returns file contents optionally limited by `view_range`.
1646 * When used on a directory, lists contents.
1647 *
1648 * @stability unstable
1649 * @category schemas
1650 * @since 4.0.0
1651 */
1652 export const MemoryViewCommand = Schema.Struct({
1653 command: Schema.Literal("view"),
1654 /**
1655 * The path to the file or directory to view.
1656 */
1657 path: Schema.String,
1658 /**
1659 * The specific lines to view.
1660 */
1661 view_range: Schema.optionalKey(ViewRange)
1662 })
1663 /**
1664 * Memory tool command payload for viewing a file or directory, optionally with a file line range.
1665 *
1666 * @stability unstable
1667 * @category models
1668 * @since 4.0.0
1669 */
1670 export type MemoryViewCommand = typeof MemoryViewCommand.Type
1671
1672 const Memory_20250818_Commands = Schema.Union([
1673 MemoryCreateCommand,
1674 MemoryDeleteCommand,
1675 MemoryInsertCommand,
1676 MemoryRenameCommand,
1677 MemoryStrReplaceCommand,
1678 MemoryViewCommand
1679 ])
1680
1681 // -----------------------------------------------------------------------------
1682 // Memory Tool Definitions
1683 // -----------------------------------------------------------------------------
1684
1685 /**
1686 * Defines the memory tool for persistent file operations across conversations.
1687 *
1688 * **Details**
1689 *
1690 * Provides commands for creating, viewing, editing, renaming, and deleting
1691 * files within the model's memory space.
1692 *
1693 * @stability unstable
1694 * @category tools
1695 * @since 4.0.0
1696 */
1697 export const Memory_20250818 = Tool.providerDefined({
1698 id: "anthropic.memory_20250818",
1699 customName: "AnthropicMemory",
1700 providerName: "memory",
1701 requiresHandler: true,
1702 parameters: Memory_20250818_Commands,
1703 success: Schema.String
1704 })
1705
1706 // =============================================================================
1707 // Text Editor
1708 // =============================================================================
1709
1710 // -----------------------------------------------------------------------------
1711 // Text Editor Commands
1712 // -----------------------------------------------------------------------------
1713
1714 /**
1715 * Reads the contents of a file or lists directory contents.
1716 *
1717 * **When to use**
1718 *
1719 * Use when validating or constructing the standalone Anthropic Text Editor
1720 * `view` command.
1721 *
1722 * **Details**
1723 *
1724 * When used on a file, returns the file contents, optionally limited to a line
1725 * range. When used on a directory, lists all files and subdirectories.
1726 * `view_range` is a 1-indexed `[start, end]` tuple where `-1` means through
1727 * the end of the file.
1728 *
1729 * @see {@link CodeExecutionTextEditorView} for the code-execution variant without `view_range`
1730 *
1731 * @stability unstable
1732 * @category schemas
1733 * @since 4.0.0
1734 */
1735 export const TextEditorViewCommand = Schema.Struct({
1736 command: Schema.Literal("view"),
1737 /**
1738 * Absolute or relative path to the file or directory to view.
1739 */
1740 path: Schema.String,
1741 /**
1742 * Optional line range to view (only applies to files, not directories).
1743 * Lines are 1-indexed. Use -1 for end to read to end of file.
1744 */
1745 view_range: Schema.optionalKey(ViewRange)
1746 })
1747 /**
1748 * Text editor command payload for viewing file contents or listing directory contents.
1749 *
1750 * **Details**
1751 *
1752 * `view_range` is a 1-indexed `[start, end]` tuple where `-1` means through
1753 * the end of the file.
1754 *
1755 * @stability unstable
1756 * @category models
1757 * @since 4.0.0
1758 */
1759 export type TextEditorViewCommand = typeof TextEditorViewCommand.Type
1760
1761 /**
1762 * Create a new file with specified content.
1763 *
1764 * **When to use**
1765 *
1766 * Use when validating or constructing an Anthropic text editor `create`
1767 * command.
1768 *
1769 * **Details**
1770 *
1771 * The payload is discriminated by `command: "create"` and requires both `path`
1772 * and `file_text`.
1773 *
1774 * **Gotchas**
1775 *
1776 * Fails if the file already exists. Parent directories must exist.
1777 *
1778 * @stability unstable
1779 * @category schemas
1780 * @since 4.0.0
1781 */
1782 export const TextEditorCreateCommand = Schema.Struct({
1783 command: Schema.Literal("create"),
1784 /**
1785 * Path where the file should be created.
1786 */
1787 path: Schema.String,
1788 /**
1789 * The content to write to the new file.
1790 */
1791 file_text: Schema.String
1792 })
1793 /**
1794 * Text editor command payload for creating a new file with the specified content.
1795 *
1796 * **When to use**
1797 *
1798 * Use when typing parsed text-editor create command payloads after schema
1799 * validation and before dispatching to Anthropic tool handlers.
1800 *
1801 * **Gotchas**
1802 *
1803 * The command fails if the file already exists or if parent directories are missing.
1804 *
1805 * @stability unstable
1806 * @category models
1807 * @since 4.0.0
1808 */
1809 export type TextEditorCreateCommand = typeof TextEditorCreateCommand.Type
1810
1811 /**
1812 * Replaces a specific string in a file with a new string.
1813 *
1814 * **When to use**
1815 *
1816 * Use when validating or constructing standalone Anthropic text editor
1817 * `str_replace` commands.
1818 *
1819 * **Details**
1820 *
1821 * The payload uses `command: "str_replace"`, `path`, `old_str`, and `new_str`.
1822 * `new_str` may be empty to delete text.
1823 *
1824 * **Gotchas**
1825 *
1826 * The `old_str` must match exactly (including whitespace and indentation)
1827 * and must be unique in the file.
1828 *
1829 * @see {@link TextEditorViewCommand} for reading contents before choosing `old_str`
1830 * @see {@link CodeExecutionTextEditorStrReplace} for the code-execution variant
1831 *
1832 * @stability unstable
1833 * @category schemas
1834 * @since 4.0.0
1835 */
1836 export const TextEditorStrReplaceCommand = Schema.Struct({
1837 command: Schema.Literal("str_replace"),
1838 /**
1839 * Path to the file to modify.
1840 */
1841 path: Schema.String,
1842 /**
1843 * The exact string to find and replace (must be unique in the file).
1844 */
1845 old_str: Schema.String,
1846 /**
1847 * The string to replace old_str with (can be empty to delete).
1848 */
1849 new_str: Schema.String
1850 })
1851 /**
1852 * Text editor command payload for replacing one exact, unique string in a file.
1853 *
1854 * **When to use**
1855 *
1856 * Use when typing parsed text-editor replace command payloads that must carry
1857 * one exact `old_str` match.
1858 *
1859 * **Gotchas**
1860 *
1861 * The `old_str` must match exactly, including whitespace and indentation, and
1862 * must be unique in the file.
1863 *
1864 * @stability unstable
1865 * @category models
1866 * @since 4.0.0
1867 */
1868 export type TextEditorStrReplaceCommand = typeof TextEditorStrReplaceCommand.Type
1869
1870 /**
1871 * Inserts text at a specific line number in a file.
1872 *
1873 * **Details**
1874 *
1875 * Inserts the new text after the specified line number. Use `0` to insert at
1876 * the beginning of the file; other values are 1-indexed.
1877 *
1878 * **Gotchas**
1879 *
1880 * Used by `text_editor_20241022` and `text_editor_20250124`. Later versions
1881 * send `insert_text` instead.
1882 *
1883 * @see {@link TextEditorInsertTextCommand} for the `insert_text` variant
1884 *
1885 * @stability unstable
1886 * @category schemas
1887 * @since 4.0.0
1888 */
1889 export const TextEditorInsertCommand = Schema.Struct({
1890 command: Schema.Literal("insert"),
1891 /**
1892 * Path to the file to modify.
1893 */
1894 path: Schema.String,
1895 /**
1896 * The line number after which to insert (0 = beginning, 1-indexed).
1897 */
1898 insert_line: Schema.Int,
1899 /**
1900 * The text to insert.
1901 */
1902 new_str: Schema.String
1903 })
1904 /**
1905 * Text editor command payload for inserting text after a specific line number in a file.
1906 *
1907 * @stability unstable
1908 * @category models
1909 * @since 4.0.0
1910 */
1911 export type TextEditorInsertCommand = typeof TextEditorInsertCommand.Type
1912
1913 /**
1914 * Inserts text at a specific line number in a file. Used by
1915 * `text_editor_20250429` and `text_editor_20250728`, which send `insert_text`.
1916 *
1917 * @see {@link TextEditorInsertCommand} for the `new_str` variant
1918 *
1919 * @stability unstable
1920 * @category schemas
1921 * @since 4.1.1
1922 */
1923 export const TextEditorInsertTextCommand = Schema.Struct({
1924 command: Schema.Literal("insert"),
1925 /**
1926 * Path to the file to modify.
1927 */
1928 path: Schema.String,
1929 /**
1930 * The line number after which to insert (0 = beginning, 1-indexed).
1931 */
1932 insert_line: Schema.Int,
1933 /**
1934 * The text to insert.
1935 */
1936 insert_text: Schema.String
1937 })
1938 /**
1939 * Text editor command payload for inserting text after a specific line number in a file.
1940 *
1941 * @stability unstable
1942 * @category models
1943 * @since 4.1.1
1944 */
1945 export type TextEditorInsertTextCommand = typeof TextEditorInsertTextCommand.Type
1946
1947 /**
1948 * Undoes the last edit made to a file.
1949 *
1950 * **Details**
1951 *
1952 * Reverts the most recent `str_replace`, `insert`, or `create` operation on the
1953 * file.
1954 *
1955 * **Gotchas**
1956 *
1957 * This command is available in `text_editor_20241022` and
1958 * `text_editor_20250124`, but not in `text_editor_20250429` or
1959 * `text_editor_20250728`.
1960 *
1961 * @stability unstable
1962 * @category schemas
1963 * @since 4.0.0
1964 */
1965 export const TextEditorUndoEditCommand = Schema.Struct({
1966 command: Schema.Literal("undo_edit"),
1967 /**
1968 * Path to the file to undo the last edit on.
1969 */
1970 path: Schema.String
1971 })
1972 /**
1973 * Text editor command payload for undoing the most recent edit to a file.
1974 *
1975 * **Gotchas**
1976 *
1977 * Available for `text_editor_20241022` and `text_editor_20250124`, but not for
1978 * `text_editor_20250429` or `text_editor_20250728`.
1979 *
1980 * @stability unstable
1981 * @category models
1982 * @since 4.0.0
1983 */
1984 export type TextEditorUndoEditCommand = typeof TextEditorUndoEditCommand.Type
1985
1986 const TextEditor_StrReplaceEditor_Commands = Schema.Union([
1987 TextEditorViewCommand,
1988 TextEditorCreateCommand,
1989 TextEditorStrReplaceCommand,
1990 TextEditorInsertCommand,
1991 TextEditorUndoEditCommand
1992 ])
1993
1994 const TextEditor_StrReplaceBasedEdit_Commands = Schema.Union([
1995 TextEditorViewCommand,
1996 TextEditorCreateCommand,
1997 TextEditorStrReplaceCommand,
1998 TextEditorInsertTextCommand
1999 ])
2000
2001 // -----------------------------------------------------------------------------
2002 // Text Editor Args
2003 // -----------------------------------------------------------------------------
2004
2005 const TextEditor_StrReplaceBasedEdit_Args = Schema.Struct({
2006 /**
2007 * Maximum number of characters to return when viewing large files.
2008 * When a file exceeds this limit, it will be truncated.
2009 */
2010 max_characters: Schema.optional(Schema.Int)
2011 })
2012
2013 // -----------------------------------------------------------------------------
2014 // Text Editor Tool Definitions
2015 // -----------------------------------------------------------------------------
2016
2017 /**
2018 * Defines the deprecated text editor tool for Claude 3.5 Sonnet.
2019 *
2020 * **When to use**
2021 *
2022 * Use when you need the 2024-10-22 `str_replace_editor` compatibility path for
2023 * Claude 3.5 Sonnet.
2024 *
2025 * **Details**
2026 *
2027 * Requires the "computer-use-2024-10-22" beta header and supports `view`,
2028 * `create`, `str_replace`, `insert`, and `undo_edit` commands.
2029 *
2030 * @see {@link TextEditor_20250124} for the newer `str_replace_editor` version
2031 * @see {@link TextEditor_20250728} for the Claude 4 `str_replace_based_edit_tool` line
2032 *
2033 * @stability unstable
2034 * @category tools
2035 * @since 4.0.0
2036 */
2037 export const TextEditor_20241022 = Tool.providerDefined({
2038 id: "anthropic.text_editor_20241022",
2039 customName: "AnthropicTextEditor",
2040 providerName: "str_replace_editor",
2041 requiresHandler: true,
2042 parameters: TextEditor_StrReplaceEditor_Commands,
2043 success: Schema.String
2044 })
2045
2046 /**
2047 * Defines the text editor tool for deprecated Claude Sonnet 3.7.
2048 *
2049 * **When to use**
2050 *
2051 * Use when you need the 2025-01-24 Claude Sonnet 3.7 text editor tool using
2052 * `str_replace_editor`.
2053 *
2054 * **Details**
2055 *
2056 * Requires the "computer-use-2025-01-24" beta header, requires a handler, and
2057 * supports `view`, `create`, `str_replace`, `insert`, and `undo_edit` commands.
2058 *
2059 * @see {@link TextEditor_20241022} for the older `str_replace_editor` version
2060 * @see {@link TextEditor_20250429} for the Claude 4 `str_replace_based_edit_tool` line
2061 *
2062 * @stability unstable
2063 * @category tools
2064 * @since 4.0.0
2065 */
2066 export const TextEditor_20250124 = Tool.providerDefined({
2067 id: "anthropic.text_editor_20250124",
2068 customName: "AnthropicTextEditor",
2069 providerName: "str_replace_editor",
2070 requiresHandler: true,
2071 parameters: TextEditor_StrReplaceEditor_Commands,
2072 success: Schema.String
2073 })
2074
2075 /**
2076 * Defines the text editor tool for Claude 4 models using Anthropic's `str_replace_based_edit_tool`.
2077 *
2078 * **When to use**
2079 *
2080 * Use when you need the 2025-04-29 Claude 4 `str_replace_based_edit_tool`
2081 * version.
2082 *
2083 * **Details**
2084 *
2085 * Requires the "computer-use-2025-01-24" beta header.
2086 *
2087 * **Gotchas**
2088 *
2089 * This version does not support the `undo_edit` command.
2090 *
2091 * @see {@link TextEditor_20250124} for the previous `str_replace_editor` version
2092 * @see {@link TextEditor_20250728} for the later Claude 4 text editor version
2093 *
2094 * @stability unstable
2095 * @category tools
2096 * @since 4.0.0
2097 */
2098 export const TextEditor_20250429 = Tool.providerDefined({
2099 id: "anthropic.text_editor_20250429",
2100 customName: "AnthropicTextEditor",
2101 providerName: "str_replace_based_edit_tool",
2102 requiresHandler: true,
2103 args: TextEditor_StrReplaceBasedEdit_Args,
2104 parameters: TextEditor_StrReplaceBasedEdit_Commands,
2105 success: Schema.String
2106 })
2107
2108 /**
2109 * Defines the text editor tool for Claude 4 models.
2110 *
2111 * **Details**
2112 *
2113 * Uses Anthropic's `str_replace_based_edit_tool`. `max_characters` can limit
2114 * file-view output for this version.
2115 *
2116 * **Gotchas**
2117 *
2118 * This version does not support the `undo_edit` command.
2119 *
2120 * @stability unstable
2121 * @category tools
2122 * @since 4.0.0
2123 */
2124 export const TextEditor_20250728 = Tool.providerDefined({
2125 id: "anthropic.text_editor_20250728",
2126 customName: "AnthropicTextEditor",
2127 providerName: "str_replace_based_edit_tool",
2128 requiresHandler: true,
2129 args: TextEditor_StrReplaceBasedEdit_Args,
2130 parameters: TextEditor_StrReplaceBasedEdit_Commands,
2131 success: Schema.String
2132 })
2133
2134 // =============================================================================
2135 // Web Search
2136 // =============================================================================
2137
2138 // -----------------------------------------------------------------------------
2139 // Web Search Types
2140 // -----------------------------------------------------------------------------
2141
2142 /**
2143 * Describes user location for localizing search results.
2144 *
2145 * **When to use**
2146 *
2147 * Use when you need to localize search results for location-dependent queries
2148 * like weather, local businesses, or events.
2149 *
2150 * **Details**
2151 *
2152 * The schema uses `type: "approximate"` plus optional `city`, `region`,
2153 * `country`, and `timezone`. `country` is an ISO 3166-1 alpha-2 code, and
2154 * `timezone` is an IANA time zone identifier.
2155 *
2156 * @see {@link WebSearch_20250305_Args} for the argument schema that consumes this location
2157 *
2158 * @stability unstable
2159 * @category schemas
2160 * @since 4.0.0
2161 */
2162 export const WebSearchUserLocation = Schema.Struct({
2163 /**
2164 * Location type - currently only "approximate" is supported.
2165 */
2166 type: Schema.Literal("approximate"),
2167 /**
2168 * City name.
2169 */
2170 city: Schema.optional(Schema.String),
2171 /**
2172 * Region/state/province name.
2173 */
2174 region: Schema.optional(Schema.String),
2175 /**
2176 * ISO 3166-1 alpha-2 country code.
2177 */
2178 country: Schema.optional(Schema.String),
2179 /**
2180 * IANA timezone identifier.
2181 */
2182 timezone: Schema.optional(Schema.String)
2183 })
2184
2185 // -----------------------------------------------------------------------------
2186 // Web Search Args
2187 // -----------------------------------------------------------------------------
2188
2189 /**
2190 * Defines configuration arguments for the web search tool.
2191 *
2192 * **When to use**
2193 *
2194 * Use when you need to configure `WebSearch_20250305` with search limits,
2195 * domain filters, or user location.
2196 *
2197 * **Details**
2198 *
2199 * The payload can set `maxUses`, `allowedDomains`, `blockedDomains`, and
2200 * `userLocation`.
2201 *
2202 * **Gotchas**
2203 *
2204 * `allowedDomains` and `blockedDomains` are mutually exclusive.
2205 *
2206 * @see {@link WebSearch_20250305} for the provider-defined tool that consumes these arguments
2207 * @see {@link WebSearchUserLocation} for localizing search results
2208 *
2209 * @stability unstable
2210 * @category schemas
2211 * @since 4.0.0
2212 */
2213 export const WebSearch_20250305_Args = Schema.Struct({
2214 /**
2215 * Maximum number of searches allowed per API request.
2216 */
2217 maxUses: Schema.optional(Schema.Int),
2218 /**
2219 * Restrict search results to only these domains.
2220 *
2221 * Cannot be used together with `blockedDomains`.
2222 */
2223 allowedDomains: Schema.optional(Schema.Array(Schema.String)),
2224 /**
2225 * Exclude results from these domains.
2226 *
2227 * Cannot be used together with `allowedDomains`.
2228 */
2229 blockedDomains: Schema.optional(Schema.Array(Schema.String)),
2230 /**
2231 * User location for localizing search results.
2232 */
2233 userLocation: Schema.optional(WebSearchUserLocation)
2234 })
2235 /**
2236 * Configuration arguments for the Anthropic web search tool, including usage limits, domain filters, and optional user location.
2237 *
2238 * **Gotchas**
2239 *
2240 * `allowedDomains` and `blockedDomains` are mutually exclusive.
2241 *
2242 * @stability unstable
2243 * @category models
2244 * @since 4.0.0
2245 */
2246 export type WebSearch_20250305_Args = typeof WebSearch_20250305_Args.Type
2247
2248 // -----------------------------------------------------------------------------
2249 // Web Search Parameters
2250 // -----------------------------------------------------------------------------
2251
2252 /**
2253 * Schema for Claude-supplied web search tool parameters.
2254 *
2255 * **Details**
2256 *
2257 * The payload contains the generated `query` string and is consumed by
2258 * `WebSearch_20250305`.
2259 *
2260 * @see {@link WebSearch_20250305} for the provider-defined tool that consumes this payload
2261 *
2262 * @stability unstable
2263 * @category schemas
2264 * @since 4.0.0
2265 */
2266 export const WebSearchParameters = Schema.Struct({
2267 /**
2268 * The search query generated by Claude.
2269 */
2270 query: Schema.String
2271 })
2272 /**
2273 * Type of the parameters Claude supplies when invoking the Anthropic web search tool.
2274 *
2275 * **Details**
2276 *
2277 * Contains the generated search query used by `WebSearch_20250305`.
2278 *
2279 * @see {@link WebSearch_20250305} for the provider-defined tool that consumes this payload
2280 *
2281 * @stability unstable
2282 * @category models
2283 * @since 4.0.0
2284 */
2285 export type WebSearchParameters = typeof WebSearchParameters.Type
2286
2287 // -----------------------------------------------------------------------------
2288 // Web Search Tool Definitions
2289 // -----------------------------------------------------------------------------
2290
2291 /**
2292 * Defines the web search tool for Claude models.
2293 *
2294 * **When to use**
2295 *
2296 * Use when you want Claude to search the web for real-time information.
2297 *
2298 * **Details**
2299 *
2300 * Enables Claude to search the web for real-time information. This is a
2301 * server-side tool executed by Anthropic's infrastructure.
2302 * Generally available (no beta header required).
2303 *
2304 * @see {@link WebFetch_20250910} for retrieving known URLs after discovery
2305 *
2306 * @stability unstable
2307 * @category tools
2308 * @since 4.0.0
2309 */
2310 export const WebSearch_20250305 = Tool.providerDefined({
2311 id: "anthropic.web_search_20250305",
2312 customName: "AnthropicWebSearch",
2313 providerName: "web_search",
2314 args: WebSearch_20250305_Args,
2315 parameters: WebSearchParameters,
2316 success: Schema.Array(Generated.BetaResponseWebSearchResultBlock),
2317 failure: Generated.BetaResponseWebSearchToolResultError
2318 })
2319
2320 // =============================================================================
2321 // Web Fetch
2322 // =============================================================================
2323
2324 // -----------------------------------------------------------------------------
2325 // Web Fetch Types
2326 // -----------------------------------------------------------------------------
2327
2328 /**
2329 * Defines citation configuration for web fetch.
2330 *
2331 * **When to use**
2332 *
2333 * Use when you need to enable or disable citations on web fetch results.
2334 *
2335 * **Details**
2336 *
2337 * The payload contains the `enabled` flag. `citations` is optional on
2338 * `WebFetch_20250910_Args`, and citations are disabled by default.
2339 *
2340 * @see {@link WebFetch_20250910_Args} for the argument schema that consumes this configuration
2341 *
2342 * @stability unstable
2343 * @category schemas
2344 * @since 4.0.0
2345 */
2346 export const WebFetchCitationsConfig = Schema.Struct({
2347 /**
2348 * Enable citations for fetched content.
2349 */
2350 enabled: Schema.Boolean
2351 })
2352 /**
2353 * Configuration payload for enabling or disabling citations on web fetch results.
2354 *
2355 * **When to use**
2356 *
2357 * Use when typing parsed web-fetch citation configuration shared between
2358 * request arguments and handler code.
2359 *
2360 * **Details**
2361 *
2362 * The payload contains the `enabled` flag. `citations` is optional on
2363 * `WebFetch_20250910_Args`, and citations are disabled by default.
2364 *
2365 * @see {@link WebFetch_20250910_Args} for the argument schema that consumes this configuration
2366 *
2367 * @stability unstable
2368 * @category models
2369 * @since 4.0.0
2370 */
2371 export type WebFetchCitationsConfig = typeof WebFetchCitationsConfig.Type
2372
2373 // -----------------------------------------------------------------------------
2374 // Web Fetch Args
2375 // -----------------------------------------------------------------------------
2376
2377 /**
2378 * Defines configuration arguments for the web fetch tool.
2379 *
2380 * **When to use**
2381 *
2382 * Use when you need to configure `WebFetch_20250910` with usage limits, domain
2383 * filters, citations, or content token limits.
2384 *
2385 * **Details**
2386 *
2387 * The payload can set `maxUses`, domain filters, `citations`, and
2388 * `maxContentTokens`, which map to Anthropic web fetch request fields.
2389 *
2390 * **Gotchas**
2391 *
2392 * `allowedDomains` and `blockedDomains` are mutually exclusive.
2393 * `maxContentTokens` is approximate and does not apply to binary content such
2394 * as PDFs.
2395 *
2396 * @see {@link WebFetch_20250910} for the provider-defined tool that consumes these arguments
2397 * @see {@link WebFetchCitationsConfig} for configuring citations
2398 *
2399 * @stability unstable
2400 * @category schemas
2401 * @since 4.0.0
2402 */
2403 export const WebFetch_20250910_Args = Schema.Struct({
2404 /**
2405 * Maximum number of fetches allowed per API request.
2406 */
2407 maxUses: Schema.optional(Schema.Int),
2408 /**
2409 * Restrict fetches to only these domains.
2410 *
2411 * Cannot be used together with `blockedDomains`.
2412 */
2413 allowedDomains: Schema.optional(Schema.Array(Schema.String)),
2414 /**
2415 * Exclude fetches from these domains.
2416 *
2417 * Cannot be used together with `allowedDomains`.
2418 */
2419 blockedDomains: Schema.optional(Schema.Array(Schema.String)),
2420 /**
2421 * Enable citations for fetched content.
2422 */
2423 citations: Schema.optional(WebFetchCitationsConfig),
2424 /**
2425 * Maximum content length in tokens.
2426 */
2427 maxContentTokens: Schema.optional(Schema.Int)
2428 })
2429 /**
2430 * Configuration arguments for the Anthropic web fetch tool, including usage limits, domain filters, citation settings, and token limits.
2431 *
2432 * **When to use**
2433 *
2434 * Use when typing parsed web-fetch tool configuration shared by the
2435 * provider-defined tool and request-building code.
2436 *
2437 * **Gotchas**
2438 *
2439 * `allowedDomains` and `blockedDomains` are mutually exclusive.
2440 * `maxContentTokens` is approximate and does not apply to binary content such
2441 * as PDFs.
2442 *
2443 * @stability unstable
2444 * @category models
2445 * @since 4.0.0
2446 */
2447 export type WebFetch_20250910_Args = typeof WebFetch_20250910_Args.Type
2448
2449 // -----------------------------------------------------------------------------
2450 // Web Fetch Parameters
2451 // -----------------------------------------------------------------------------
2452
2453 /**
2454 * Schema for Claude-supplied web fetch parameters.
2455 *
2456 * **When to use**
2457 *
2458 * Use when validating or constructing the `url` payload consumed by
2459 * `WebFetch_20250910`.
2460 *
2461 * **Details**
2462 *
2463 * The payload contains the single `url` parameter for Anthropic web fetch.
2464 *
2465 * **Gotchas**
2466 *
2467 * The URL must be user-provided or from prior search/fetch results. Maximum URL
2468 * length is 250 characters.
2469 *
2470 * @see {@link WebFetch_20250910} for the provider-defined tool that consumes this payload
2471 *
2472 * @stability unstable
2473 * @category schemas
2474 * @since 4.0.0
2475 */
2476 export const WebFetchParameters = Schema.Struct({
2477 /**
2478 * URL to fetch. Must be a URL provided by the user or from prior search/fetch
2479 * results. Maximum URL length: 250 characters.
2480 */
2481 url: Schema.String
2482 })
2483 /**
2484 * Type of the parameters Claude supplies when invoking the Anthropic web fetch tool.
2485 *
2486 * **When to use**
2487 *
2488 * Use when typing Claude-supplied web-fetch tool parameters after schema
2489 * validation, before enforcing URL provenance or length constraints.
2490 *
2491 * **Details**
2492 *
2493 * The payload contains the single `url` parameter for Anthropic web fetch.
2494 *
2495 * **Gotchas**
2496 *
2497 * The URL must be user-provided or from prior search/fetch results. Maximum URL
2498 * length is 250 characters.
2499 *
2500 * @stability unstable
2501 * @category models
2502 * @since 4.0.0
2503 */
2504 export type WebFetchParameters = typeof WebFetchParameters.Type
2505
2506 // -----------------------------------------------------------------------------
2507 // Web Fetch Tool Definitions
2508 // -----------------------------------------------------------------------------
2509
2510 /**
2511 * Defines the web fetch tool for Claude models.
2512 *
2513 * **When to use**
2514 *
2515 * Use when you want Claude to retrieve the content of a specific web page or
2516 * PDF.
2517 *
2518 * **Details**
2519 *
2520 * Allows Claude to retrieve full content from web pages and PDF documents.
2521 * This is a server-side tool executed by Anthropic's infrastructure. Selecting
2522 * this tool adds the "web-fetch-2025-09-10" beta header.
2523 *
2524 * @see {@link WebSearch_20250305} for discovering URLs before fetching specific content
2525 *
2526 * @stability unstable
2527 * @category tools
2528 * @since 4.0.0
2529 */
2530 export const WebFetch_20250910 = Tool.providerDefined({
2531 id: "anthropic.web_fetch_20250910",
2532 customName: "AnthropicWebFetch",
2533 providerName: "web_fetch",
2534 args: WebFetch_20250910_Args,
2535 parameters: WebFetchParameters,
2536 success: Generated.BetaResponseWebFetchResultBlock,
2537 failure: Generated.BetaResponseWebFetchToolResultError
2538 })
2539
2540 // =============================================================================
2541 // Tool Search
2542 // =============================================================================
2543
2544 // -----------------------------------------------------------------------------
2545 // Tool Search Parameters
2546 // -----------------------------------------------------------------------------
2547
2548 /**
2549 * Schema for regex-based tool search input parameters.
2550 *
2551 * **Details**
2552 *
2553 * Claude constructs regex patterns using Python's `re.search()` syntax.
2554 * Maximum pattern length: 200 characters. The optional `limit` caps the
2555 * number of returned tools (1 to 10,000, default 5).
2556 *
2557 * @stability unstable
2558 * @category schemas
2559 * @since 4.0.0
2560 */
2561 export const ToolSearchRegexParameters = Schema.Struct({
2562 /**
2563 * Python regex pattern to search for tools.
2564 */
2565 pattern: Schema.String,
2566 /**
2567 * Maximum number of tools to return.
2568 */
2569 limit: Schema.optionalKey(Schema.Int)
2570 })
2571 /**
2572 * Type of the parameters Claude supplies when invoking regex-based Anthropic tool search.
2573 *
2574 * **Details**
2575 *
2576 * Claude constructs regex patterns using Python's `re.search()` syntax.
2577 * Maximum pattern length: 200 characters.
2578 *
2579 * @stability unstable
2580 * @category models
2581 * @since 4.0.0
2582 */
2583 export type ToolSearchRegexParameters = typeof ToolSearchRegexParameters.Type
2584
2585 /**
2586 * Defines input parameters for BM25/natural language tool search.
2587 *
2588 * **When to use**
2589 *
2590 * Use when validating or constructing the natural-language query payload for
2591 * `ToolSearchBM25_20251119`.
2592 *
2593 * **Details**
2594 *
2595 * The payload contains Claude's natural-language `query`. BM25 searches tool
2596 * names, descriptions, argument names, and argument descriptions. The optional
2597 * `limit` caps the number of returned tools (1 to 10,000, default 5).
2598 *
2599 * @see {@link ToolSearchBM25_20251119} for the provider-defined tool that consumes these parameters
2600 *
2601 * @stability unstable
2602 * @category schemas
2603 * @since 4.0.0
2604 */
2605 export const ToolSearchBM25Parameters = Schema.Struct({
2606 /**
2607 * Natural language query to search for tools.
2608 */
2609 query: Schema.String,
2610 /**
2611 * Maximum number of tools to return.
2612 */
2613 limit: Schema.optionalKey(Schema.Int)
2614 })
2615 /**
2616 * Type of the parameters Claude supplies when invoking BM25 natural-language Anthropic tool search.
2617 *
2618 * @stability unstable
2619 * @category models
2620 * @since 4.0.0
2621 */
2622 export type ToolSearchBM25Parameters = typeof ToolSearchBM25Parameters.Type
2623
2624 // -----------------------------------------------------------------------------
2625 // Tool Search Tool Definitions
2626 // -----------------------------------------------------------------------------
2627
2628 /**
2629 * Annotation that defers loading a user-defined tool until Claude discovers it
2630 * through tool search.
2631 *
2632 * **When to use**
2633 *
2634 * Use with `ToolSearchRegex_20251119` or `ToolSearchBM25_20251119` to keep
2635 * large tool catalogs out of the initial context.
2636 *
2637 * **Details**
2638 *
2639 * When `true`, the tool definition is sent with `defer_loading: true`. The
2640 * default is `false`, which sends no `defer_loading` field.
2641 *
2642 * **Gotchas**
2643 *
2644 * Anthropic requires at least one non-deferred tool, normally the tool search
2645 * tool itself. The annotation has no effect on provider-defined tools.
2646 *
2647 * **Example** (Deferring a tool until it is searched)
2648 *
2649 * ```ts
2650 * import { AnthropicTool } from "@effect/ai-anthropic"
2651 * import { Tool, Toolkit } from "effect/ai"
2652 *
2653 * const ListContacts = Tool.make("ListContacts")
2654 * .annotate(AnthropicTool.DeferLoading, true)
2655 *
2656 * export const toolkit = Toolkit.make(
2657 * ListContacts,
2658 * AnthropicTool.ToolSearchBM25_20251119()
2659 * )
2660 * ```
2661 *
2662 * @see {@link ToolSearchRegex_20251119} for regex-based tool search
2663 * @see {@link ToolSearchBM25_20251119} for natural-language tool search
2664 *
2665 * @stability unstable
2666 * @category annotations
2667 * @since 4.1.2
2668 */
2669 export const DeferLoading = Context.Reference<boolean>("@effect/ai-anthropic/AnthropicTool/DeferLoading", {
2670 defaultValue: () => false
2671 })
2672
2673 /**
2674 * Defines regex-based tool search for Claude models.
2675 *
2676 * **Details**
2677 *
2678 * Claude constructs regex patterns using Python's `re.search()` syntax to
2679 * find tools. The regex is matched against tool names, descriptions,
2680 * argument names, and argument descriptions.
2681 * Requires the "advanced-tool-use-2025-11-20" beta header.
2682 *
2683 * @stability unstable
2684 * @category tools
2685 * @since 4.0.0
2686 */
2687 export const ToolSearchRegex_20251119 = Tool.providerDefined({
2688 id: "anthropic.tool_search_tool_regex_20251119",
2689 customName: "AnthropicToolSearchRegex",
2690 providerName: "tool_search_tool_regex",
2691 parameters: ToolSearchRegexParameters,
2692 success: Schema.Array(Generated.BetaRequestToolReferenceBlock),
2693 failure: Generated.BetaResponseToolSearchToolResultError
2694 })
2695
2696 /**
2697 * Defines BM25/natural language tool search for Claude models.
2698 *
2699 * **When to use**
2700 *
2701 * Use when you want Claude to find relevant tools from a natural-language query
2702 * instead of a regex pattern.
2703 *
2704 * **Details**
2705 *
2706 * Claude uses natural language queries to search for tools using the
2707 * BM25 algorithm. The search is performed against tool names, descriptions,
2708 * argument names, and argument descriptions.
2709 * Requires the "advanced-tool-use-2025-11-20" beta header.
2710 *
2711 * @see {@link ToolSearchRegex_20251119} for the regex-pattern alternative
2712 *
2713 * @stability unstable
2714 * @category tools
2715 * @since 4.0.0
2716 */
2717 export const ToolSearchBM25_20251119 = Tool.providerDefined({
2718 id: "anthropic.tool_search_tool_bm25_20251119",
2719 customName: "AnthropicToolSearchBM25",
2720 providerName: "tool_search_tool_bm25",
2721 parameters: ToolSearchBM25Parameters,
2722 success: Schema.Array(Generated.BetaRequestToolReferenceBlock),
2723 failure: Generated.BetaResponseToolSearchToolResultError
2724 })