tools

Documentation

Index

• Constants
• Variables
• func Bash(msg json.RawMessage, onData func(data string)) (string, error)
• func DiffApply(input json.RawMessage, onData func(data string)) (string, error)
• func EditFile(input json.RawMessage, onData func(data string)) (string, error)
• func GenerateSchema[T any]() json.RawMessage
• func Glob(msg json.RawMessage, onData func(data string)) (string, error)
• func InitWebFetch(headless bool)
• func InjectSkill(loader *skills.Loader, input json.RawMessage, onData func(data string)) (string, error)
• func IsCommandExists(cmd string) bool
• func ParseInput[T any](msg json.RawMessage) (*T, error)
• func ReadFile(msg json.RawMessage, onData func(data string)) (string, error)
• func TUIInput(msg json.RawMessage, onData func(data string)) (string, error)
• func TodoUpdate(input json.RawMessage, onData func(data string)) (string, error)
• func ValidateTUIInputInput(in *TUIInputInput) error
• func WebFetch(input json.RawMessage, onData func(data string)) (string, error)
• func WebSearch(input json.RawMessage, onData func(data string)) (string, error)
• func WriteFile(input json.RawMessage, onData func(data string)) (string, error)
• type BashInput
• type BashSandbox
• type DiffApplyInput
• type EditFileInput
• type GlobInput
• type InjectSkillInput
• type ReadFileInput
• type TUIInputInput
• type TaskInput
• type TodoItem
• type TodoList
  • func NewTodoList() *TodoList
  • func (tl *TodoList) Render() string
  • func (tl *TodoList) RenderTUI() string
  • func (tl *TodoList) Update(items []TodoItem) (string, error)
• type TodoUpdateInput
• type Tool
  • func GenerateBashToolDef() Tool
  • func GenerateSkillToolDef(skillLoader *skills.Loader) Tool
  • func GenerateTaskToolDef(agentDescriptions string) Tool
  • func GenerateWebSearchToolDef(n int, headless bool) Tool
  • func (t Tool) ToAI() ai.ToolDef
• type WebFetchInput
• type WebSearchInput
• type WriteFileInput

Constants

const (
	// DefaultBashTimeout is used when BashInput.timeout_ms is omitted.
	DefaultBashTimeout = 300 * time.Second
	// MinBashTimeout is the lower bound for effective timeout (after clamping).
	MinBashTimeout = 100 * time.Millisecond
	// MaxBashTimeout is the upper bound for effective timeout (after clamping).
	MaxBashTimeout = 24 * time.Hour
)

const (
	PendingTodo   = "pending"
	CompletedTodo = "completed"
	InProgress    = "in_progress"
)

const (
	SkillToolDescription = `` /* 343-byte string literal not displayed */

)

Variables

var (
	// Timeout is the package default duration when the model omits timeout_ms.
	// It is applied before MinBashTimeout/MaxBashTimeout clamping.
	Timeout = DefaultBashTimeout

	// MaxOutputBytes caps merged stdout+stderr in memory (strings.Builder).
	// There is no spill-to-disk or image special-casing; hosts that need Claude-style
	// overflow files or token budgeting should wrap Bash() or post-process the string.
	MaxOutputBytes   = 512 * 1024 // 512KB; tail -f / long output truncated
	GracefulKillWait = 2 * time.Second
)

var (
	MaxTodoItems  = 20
	MaxInProgress = 1

	Todos = NewTodoList()
)

var (
	CurlHostnames = collections.NewSetOf("api.github.com", "wttr.in")
	CurlRoots     = collections.NewSetOf("github.io", "wikipedia.org")
	CurlSuffixes  = collections.NewSetOf("html", "htm", "md", "json", "txt", "shtml", "xml")
)

var (
	SearchFetcherType = webfetch.FetcherTypeChrome
	Headless          = true
)

var BashToolDef = Tool{
	Name:        "bash",
	Description: "Run a bash command",
	InputSchema: GenerateSchema[BashInput](),
	Function:    Bash,
}

var DiffApplyToolDef = Tool{
	Name:        "diff_apply",
	Description: "Apply a diff to a single file",
	InputSchema: GenerateSchema[DiffApplyInput](),
	Function:    DiffApply,
}

var EditFileInputSchema = GenerateSchema[EditFileInput]()

var EditFileToolDef = Tool{
	Name: "edit_file",
	Description: `Make edits to a text file.

Replaces 'old_str' with 'new_str' in the given file. 'old_str' and 'new_str' MUST be different from each other.

If the file specified with path doesn't exist, it will be created.`,
	InputSchema: GenerateSchema[EditFileInput](),
	Function:    EditFile,
}

var (
	Fetcher webfetch.Fetcher
)

var GlobToolDef = Tool{
	Name: "glob",
	Description: "Find files by glob pattern (supports **). " +
		"Default: search under workspace root. Results are limited to 100 and sorted by modification time (newest first).",
	InputSchema: GenerateSchema[GlobInput](),
	Function:    Glob,
}

var (
	PresetTools = map[string]Tool{
		"bash":        BashToolDef,
		"glob":        GlobToolDef,
		"read_file":   ReadFileToolDef,
		"edit_file":   EditFileToolDef,
		"write_file":  WriteFileToolDef,
		"todo_update": TodoUpdateToolDef,
		"diff_apply":  DiffApplyToolDef,
		"web_fetch":   WebFetchToolDef,
		"tui_input":   TUIInputToolDef,
	}
)

var ReadFileToolDef = Tool{
	Name:        "read_file",
	Description: "Read a text file by relative path. Default: read from the start for up to 1000 lines—pass only path. For long files, use offset (0-based lines to skip) and limit (max lines per call), e.g. second page offset=1000. Numeric fields must be JSON numbers. Not for directories.",
	InputSchema: GenerateSchema[ReadFileInput](),
	Function:    ReadFile,
}

var (
	ReadMaxLines = 1000
)

var TUIInputToolDef = Tool{
	Name:        "tui_input",
	Description: "Ask the user via the host UI (preferred over embedding a raw <hitl>{...}</hitl> block in prose).",
	InputSchema: GenerateSchema[TUIInputInput](),
	Function:    TUIInput,
}

var TodoUpdateToolDef = Tool{
	Name:        "todo_update",
	Description: "Update the task list. Use to plan and track progress. The status can be `pending`, `completed`, `in_progress`.",
	InputSchema: GenerateSchema[TodoUpdateInput](),
	Function:    TodoUpdate,
}

var WebFetchToolDef = Tool{
	Name:        "web_fetch",
	Description: "Fetch the contents of a given URL and return the text content.",
	InputSchema: GenerateSchema[WebFetchInput](),
	Function:    WebFetch,
}

var (
	Workdir = "."
)

var WriteFileToolDef = Tool{
	Name:        "write_file",
	Description: "Write the given content to the file at the given path.",
	InputSchema: GenerateSchema[WriteFileInput](),
	Function:    WriteFile,
}

Functions

func Bash

func Bash(msg json.RawMessage, onData func(data string)) (string, error)

func DiffApply

func DiffApply(input json.RawMessage, onData func(data string)) (string, error)

func EditFile

func EditFile(input json.RawMessage, onData func(data string)) (string, error)

func GenerateSchema

func GenerateSchema[T any]() json.RawMessage

func Glob

func Glob(msg json.RawMessage, onData func(data string)) (string, error)

func InitWebFetch

func InitWebFetch(headless bool)

func InjectSkill

func InjectSkill(loader *skills.Loader, input json.RawMessage, onData func(data string)) (string, error)

func IsCommandExists

func IsCommandExists(cmd string) bool

func ParseInput

func ParseInput[T any](msg json.RawMessage) (*T, error)

func ReadFile

func ReadFile(msg json.RawMessage, onData func(data string)) (string, error)

func TUIInput

func TUIInput(msg json.RawMessage, onData func(data string)) (string, error)

func TodoUpdate

func TodoUpdate(input json.RawMessage, onData func(data string)) (string, error)

func ValidateTUIInputInput

func ValidateTUIInputInput(in *TUIInputInput) error

ValidateTUIInputInput 校验与 tui_input 工具一致的字段（供工具与 hitl 文本兜底共用）。

func WebFetch

func WebFetch(input json.RawMessage, onData func(data string)) (string, error)

func WebSearch

func WebSearch(input json.RawMessage, onData func(data string)) (string, error)

func WriteFile

func WriteFile(input json.RawMessage, onData func(data string)) (string, error)

Types

type BashInput

type BashInput struct {
	// Command is the shell command to run (e.g. "apt-get install -y foo").
	Command string `json:"command" jsonschema_description:"The command to run."`
	// Stdin is optional input fed to the command. Use "y\n" for confirmations.
	// For passwords, use "@env:VAR" (e.g. "@env:SUDO_PASSWORD"); the user must set VAR in the process environment. Prefer sudo -S for sudo.
	Stdin string `` /* 187-byte string literal not displayed */
	// TimeoutMS overrides the package default Timeout when set (milliseconds).
	TimeoutMS *int `` /* 170-byte string literal not displayed */
	// UseSandbox requests sandboxed execution when DefaultBashSandbox is configured.
	UseSandbox bool `` /* 166-byte string literal not displayed */
}

type BashSandbox

type BashSandbox interface {
	NewCommand(ctx context.Context, script string, workDir string) (*exec.Cmd, error)
}

BashSandbox is an optional extension point for sandboxed bash execution (e.g. Linux namespaces, bubblewrap, containers). Hosts set DefaultBashSandbox to a concrete implementation; there is no default implementation in this package.

When non-nil and the tool input has use_sandbox=true, Bash calls NewCommand instead of building exec.CommandContext(..., "bash", "-c", script). Implementations should attach the same cancellation semantics (CommandContext) and set Dir to workDir when appropriate.

var DefaultBashSandbox BashSandbox

DefaultBashSandbox is the optional sandbox implementation used when use_sandbox is true. Nil means sandboxing is never applied (default).

type DiffApplyInput

type DiffApplyInput struct {
	Path string `json:"path" jsonschema_description:"The relative path to the file to apply the diff to."`
	Diff string `json:"diff" jsonschema_description:"The diff to apply to the file."`
}

type EditFileInput

type EditFileInput struct {
	Path   string `json:"path" jsonschema_description:"The relative path to the file to edit."`
	OldStr string `json:"old_str" jsonschema_description:"The old string to replace."`
	NewStr string `json:"new_str" jsonschema_description:"The new string to replace with."`
}

type GlobInput

type GlobInput struct {
	Pattern string `json:"pattern" jsonschema_description:"The glob pattern to match files against."`
	Path    string `json:"path,omitempty" jsonschema_description:"The directory to search in. Omit to use the current workspace root."`
}

GlobInput matches Cursor/Claude style Glob tools: pattern + optional path. Note: keep semantics aligned with TS reference in claude-code-main.

type InjectSkillInput

type InjectSkillInput struct {
	Skill string `json:"skill" jsonschema_description:"The name of the skill to inject."`
}

type ReadFileInput

type ReadFileInput struct {
	Path   string `json:"path" jsonschema_description:"Relative path to a text file under the workspace (not a directory)."`
	Offset int    `` /* 265-byte string literal not displayed */
	Limit  int    `` /* 171-byte string literal not displayed */
}

ReadFileInput matches common agent Read tools: path plus optional offset (lines to skip) and limit (max lines).

type TUIInputInput

type TUIInputInput struct {
	Type     string   `` /* 212-byte string literal not displayed */
	Question string   `json:"question" jsonschema_description:"The question to ask the user."`
	Options  []string `` /* 143-byte string literal not displayed */
}

type TaskInput

type TaskInput struct {
	AgentName   string `json:"agent_name" jsonschema_description:"The name of the agent to use."`
	Description string `json:"description" jsonschema_description:"Short task description (3-5 words)."`
	Prompt      string `json:"prompt" jsonschema_description:"Detailed instructions for the subagent."`
}

type TodoItem

type TodoItem struct {
	Content    string `json:"content"`
	Status     string `json:"status"`
	ActiveForm string `json:"active_form" jsonschema_description:"Present tense action, e.g. 'Reading files'"`
}

type TodoList

type TodoList struct {
	Items []TodoItem `json:"items"`
}

func NewTodoList

func NewTodoList() *TodoList

func (*TodoList) Render

func (tl *TodoList) Render() string

func (*TodoList) RenderTUI

func (tl *TodoList) RenderTUI() string

func (*TodoList) Update

func (tl *TodoList) Update(items []TodoItem) (string, error)

type TodoUpdateInput

type TodoUpdateInput struct {
	Items []TodoItem `json:"items"`
}

type Tool

type Tool struct {
	Name        string                                                                `json:"name"`
	Description string                                                                `json:"description"`
	InputSchema json.RawMessage                                                       `json:"input_schema"`
	FuncName    string                                                                `json:"func_name"`
	Function    func(input json.RawMessage, onData func(data string)) (string, error) // (result, error)
	// contains filtered or unexported fields
}

func GenerateBashToolDef

func GenerateBashToolDef() Tool

func GenerateSkillToolDef

func GenerateSkillToolDef(skillLoader *skills.Loader) Tool

func GenerateTaskToolDef

func GenerateTaskToolDef(agentDescriptions string) Tool

func GenerateWebSearchToolDef

func GenerateWebSearchToolDef(n int, headless bool) Tool

func (Tool) ToAI

func (t Tool) ToAI() ai.ToolDef

type WebFetchInput

type WebFetchInput struct {
	URL string `json:"url" jsonschema_description:"The URL to fetch."`
}

type WebSearchInput

type WebSearchInput struct {
	Query string `json:"query" jsonschema_description:"The query to search for."`
	N     int    `json:"n" jsonschema_description:"The number of results to return."`
}

type WriteFileInput

type WriteFileInput struct {
	Path    string `json:"path" jsonschema_description:"The relative path to the file to write."`
	Content string `json:"content" jsonschema_description:"The content to write to the file."`
}