builtin

Documentation

Overview

Package builtin provides a suite of reusable tools for Bond agents that cover common system interactions: shell command execution, HTTP fetching, file I/O, and environment variable access.

Overview

The toolbox is delivered as a bond.Plugin that bundles one or more tools based on configuration. Each tool implements bond.Tool and exposes a typed JSON Schema so LLM providers can generate correct tool calls.

Tools

The following tools are available, referenced by their constant names:

• ToolShell ("shell") — Execute shell commands with configurable timeouts, command allowlists/denylists, and output truncation.
• ToolHTTPFetch ("http_fetch") — Perform HTTP GET or POST requests with configurable timeouts, custom headers, and response body truncation.
• ToolFileRead ("file_read") — Read file contents with optional line-range selection (start_line/end_line) for targeted reading without loading entire files into context.
• ToolFileWrite ("file_write") — Write files in three modes: full-write (create/overwrite), replace (find-and-replace a unique text match), or patch (apply multiple line-range edits in a single operation).
• ToolEnv ("env") — Read environment variables with optional allowlist restrictions.

Usage

Create a toolbox plugin with New and register it with a Bond agent:

plugin, err := builtin.New(builtin.Options{
    Sandbox: &builtin.SandboxConfig{
        BaseDirectory:    "/app/workspace",
        CommandAllowlist: []string{"go", "make", "git"},
    },
})
if err != nil {
    log.Fatal(err)
}

agent := bond.New(provider, bond.WithPlugins(plugin))

Tool Filtering

Use Options.Include to select a subset of tools:

plugin, _ := builtin.New(builtin.Options{
    Sandbox: &builtin.SandboxConfig{BaseDirectory: "/app"},
    Include: []string{builtin.ToolFileRead, builtin.ToolFileWrite},
})

When Include is nil, all five tools are registered.

Sandbox Configuration

A SandboxConfig is required whenever shell or file tools are included. It provides security boundaries:

• BaseDirectory restricts file read/write operations to a directory subtree.
• CommandAllowlist/CommandDenylist control which binaries the shell tool may execute.
• MaxFileSize caps the maximum file size for read operations (default 10 MB).
• EnvAllowlist restricts which environment variables may be accessed.
• ShellTimeout overrides the default 30-second command timeout.

File Write Modes

The file write tool supports three modes selected via the "mode" input parameter:

• "write" (default) — Creates or overwrites the file with the provided content. Parent directories are created automatically.
• "replace" — Finds a unique occurrence of old_text in the file and substitutes it with new_text. Fails if the match is ambiguous (multiple occurrences) or absent.
• "patch" — Applies one or more line-range edits (PatchOperations) to the file. Patches are sorted and applied bottom-up to preserve line numbering. Overlapping patches are rejected.

Error Handling

All tools return sentinel errors that can be checked with errors.Is:

• ErrPermissionDenied — Operation blocked by sandbox or filesystem permissions.
• ErrNotFound — File or resource does not exist.
• ErrValidation — Invalid input parameters.
• ErrTimeout — Operation exceeded its time limit.
• ErrSizeExceeded — File exceeds the configured maximum size.
• ErrConnection — Network connectivity failure (HTTP tool).

Index

• Constants
• Variables
• type EnvInput
• type EnvOutput
• type FileReadInput
• type FileReadOutput
• type FileWriteInput
• type FileWriteOutput
• type HTTPInput
• type HTTPOutput
• type Options
• type PatchOperation
• type Plugin
  • func New(opts Options) (*Plugin, error)
  • func (p *Plugin) Init(registry *bond.HookRegistry)
  • func (p *Plugin) Name() string
  • func (p *Plugin) Tools() []bond.Tool
• type SandboxConfig
• type ShellInput
• type ShellOutput

Constants

const (
	ToolShell     = "shell"
	ToolHTTPFetch = "http_fetch"
	ToolFileRead  = "file_read"
	ToolFileWrite = "file_write"
	ToolEnv       = "env"
)

Tool name constants for use with Options.Include filter.

Variables

var (
	ErrPermissionDenied = errors.New("toolbox: permission denied")
	ErrTimeout          = errors.New("toolbox: timeout")
	ErrNotFound         = errors.New("toolbox: not found")
	ErrValidation       = errors.New("toolbox: validation error")
	ErrSizeExceeded     = errors.New("toolbox: size exceeded")
	ErrConnection       = errors.New("toolbox: connection error")
)

Sentinel errors for type checking.

Types

type EnvInput

type EnvInput struct {
	Name string `json:"name" jsonschema:"required,environment variable name"`
}

EnvInput is the input schema for the env tool.

type EnvOutput

type EnvOutput struct {
	Name  string `json:"name"`
	Value string `json:"value"`
}

EnvOutput is the result of an env variable lookup.

type FileReadInput

type FileReadInput struct {
	Path      string `json:"path" jsonschema:"required,file path to read"`
	StartLine *int   `json:"start_line,omitempty" jsonschema:"start line (1-based inclusive)"`
	EndLine   *int   `json:"end_line,omitempty" jsonschema:"end line (1-based inclusive)"`
}

FileReadInput is the input schema for the file read tool.

type FileReadOutput

type FileReadOutput struct {
	Content    string `json:"content"`
	Path       string `json:"path"`
	TotalLines *int   `json:"total_lines,omitempty"`
}

FileReadOutput is the result of a file read.

type FileWriteInput

type FileWriteInput struct {
	Path    string           `json:"path" jsonschema:"required,file path to write"`
	Mode    string           `json:"mode,omitempty" jsonschema:"write mode: write, replace, or patch"`
	Content string           `json:"content,omitempty" jsonschema:"content to write (for write mode)"`
	OldText string           `json:"old_text,omitempty" jsonschema:"text to find (for replace mode)"`
	NewText string           `json:"new_text,omitempty" jsonschema:"replacement text (for replace mode)"`
	Patches []PatchOperation `json:"patches,omitempty" jsonschema:"patch operations (for patch mode)"`
}

FileWriteInput is the input schema for the file write tool.

type FileWriteOutput

type FileWriteOutput struct {
	BytesWritten int    `json:"bytes_written"`
	Path         string `json:"path"`
}

FileWriteOutput is the result of a file write.

type HTTPInput

type HTTPInput struct {
	URL            string            `json:"url" jsonschema:"required,the URL to fetch"`
	Method         string            `json:"method" jsonschema:"required,HTTP method (GET or POST)"`
	Headers        map[string]string `json:"headers,omitempty" jsonschema:"request headers"`
	Body           string            `json:"body,omitempty" jsonschema:"request body for POST"`
	TimeoutSeconds *int              `json:"timeout_seconds,omitempty" jsonschema:"timeout in seconds (1-300)"`
}

HTTPInput is the input schema for the HTTP tool.

type HTTPOutput

type HTTPOutput struct {
	StatusCode int    `json:"status_code"`
	Body       string `json:"body"`
	Truncated  bool   `json:"truncated,omitempty"`
}

HTTPOutput is the result of an HTTP request.

type Options

type Options struct {
	// Sandbox provides sandboxing configuration for shell and file tools.
	Sandbox *SandboxConfig
	// Include filters which tools are returned. Nil means all tools.
	Include []string
}

Options configures the toolbox plugin.

type PatchOperation

type PatchOperation struct {
	StartLine int    `json:"start_line" jsonschema:"required,start line (1-based inclusive)"`
	EndLine   int    `json:"end_line" jsonschema:"required,end line (1-based inclusive)"`
	Content   string `json:"content" jsonschema:"required,replacement content for the line range"`
}

PatchOperation specifies a single line-range edit.

type Plugin

type Plugin struct {
	// contains filtered or unexported fields
}

Plugin is the toolbox plugin that bundles tools for Bond agents.

func New

func New(opts Options) (*Plugin, error)

New creates a toolbox plugin configured with the given options. It returns an error if:

• sandbox-applicable tools are included but no SandboxConfig is provided (TBOX-6.7)
• the Include filter matches no available tools (TBOX-6.4)

func (*Plugin) Init

func (p *Plugin) Init(registry *bond.HookRegistry)

Init is a no-op; the toolbox plugin does not register any hooks.

func (*Plugin) Name

func (p *Plugin) Name() string

Name returns the plugin identifier.

func (*Plugin) Tools

func (p *Plugin) Tools() []bond.Tool

Tools returns the configured tool set.

type SandboxConfig

type SandboxConfig struct {
	// CommandAllowlist, if non-nil and non-empty, permits only these command binaries.
	CommandAllowlist []string
	// CommandDenylist is checked first and overrides the allowlist.
	CommandDenylist []string
	// ShellTimeout overrides the default 30s shell timeout.
	ShellTimeout time.Duration

	// BaseDirectory is the root directory for file operations.
	BaseDirectory string
	// MaxFileSize is the maximum file size in bytes for read/write operations.
	MaxFileSize int64

	// EnvAllowlist restricts which environment variables may be accessed.
	EnvAllowlist []string
}

SandboxConfig restricts tool behavior for security.

type ShellInput

type ShellInput struct {
	Command          string `json:"command" jsonschema:"required,the command to execute"`
	WorkingDirectory string `json:"working_directory,omitempty" jsonschema:"the working directory for command execution"`
	TimeoutSeconds   *int   `json:"timeout_seconds,omitempty" jsonschema:"timeout in seconds (1-3600)"`
}

ShellInput is the input schema for the shell tool.

type ShellOutput

type ShellOutput struct {
	Output    string `json:"output"`
	ExitCode  int    `json:"exit_code"`
	Truncated bool   `json:"truncated,omitempty"`
}

ShellOutput is the result of a shell command execution.