Documentation
¶
Overview ¶
Package tool provides librecode-style built-in coding tools for local agent turns.
Index ¶
- Constants
- Variables
- func ExpandPath(filePath string) string
- func FormatSize(byteCount int) string
- func ResolveReadPath(filePath, cwd string) (string, error)
- func ResolveToCWD(filePath, cwd string) (string, error)
- func TruncateLine(line string, maxCharacters int) (text string, wasTruncated bool)
- type ASTInput
- type ASTTool
- type Arguments
- func (arguments Arguments) Decode(target any) error
- func (arguments Arguments) Fields() (map[string]json.RawMessage, error)
- func (arguments Arguments) HasField(name string) bool
- func (arguments Arguments) IsEmpty() bool
- func (arguments Arguments) IsZero() bool
- func (arguments Arguments) MarshalJSON() ([]byte, error)
- func (arguments Arguments) RawMessage() json.RawMessage
- func (arguments Arguments) String() string
- type BashInput
- type BashTool
- type ContentBlock
- type Coordinator
- type Definition
- type EditDetails
- type EditInput
- type EditTool
- type Executor
- type FetchInput
- type FetchTool
- type FindInput
- type FindTool
- type GrepInput
- type GrepTool
- type LSInput
- type LSTool
- type Name
- type PreparedCall
- type ReadInput
- type ReadTool
- type Registry
- func (registry *Registry) CWD() string
- func (registry *Registry) Definitions() []Definition
- func (registry *Registry) DenyMutations()
- func (registry *Registry) Execute(ctx context.Context, name string, input Arguments) (Result, error)
- func (registry *Registry) ExecuteJSON(ctx context.Context, name string, payload []byte) (Result, error)
- func (registry *Registry) Has(name Name) bool
- func (registry *Registry) Prepare(name string, input Arguments) (PreparedCall, error)
- func (registry *Registry) Register(executor Executor) error
- func (registry *Registry) Wrap(name Name, decorate func(Executor) Executor) error
- type Replacement
- type Result
- type Schema
- type TruncatedBy
- type TruncationOptions
- type TruncationResult
- type WriteInput
- type WriteTool
Constants ¶
const ( // DefaultMaxLines is the default line limit for tool outputs. DefaultMaxLines = 2000 // DefaultMaxBytes is the default byte limit for tool outputs. DefaultMaxBytes = 50 * units.KiB // GrepMaxLineLength is the maximum displayed length for one grep match line. GrepMaxLineLength = 500 )
const ( // ContentTypeText is a plain text tool result block. ContentTypeText = "text" // ContentTypeImage is an inline base64 image result block. ContentTypeImage = "image" )
Variables ¶
var ErrDuplicateTool = errors.New("tool: duplicate tool")
ErrDuplicateTool is returned when a registry already has an executor for a tool name.
var ErrUnknownTool = errors.New("tool: unknown tool")
ErrUnknownTool is returned when a registry cannot resolve a tool name.
Functions ¶
func ExpandPath ¶
ExpandPath normalizes model-supplied path shorthands.
func FormatSize ¶
FormatSize formats bytes for user-facing truncation notices.
func ResolveReadPath ¶
ResolveReadPath resolves a read path and tries common macOS filename variants.
func ResolveToCWD ¶
ResolveToCWD resolves relative paths against cwd after path shorthand expansion.
Types ¶
type ASTInput ¶
type ASTInput struct {
Line *int `json:"line,omitempty"`
Depth *int `json:"depth,omitempty"`
Path string `json:"path"`
Mode string `json:"mode,omitempty" jsonschema:"enum=outline,enum=symbols,enum=query,enum=node,enum=tree"`
Query string `json:"query,omitempty"`
AllowIgnored bool `json:"allow_ignored,omitempty"`
}
ASTInput contains arguments for the ast tool.
type ASTTool ¶
type ASTTool struct {
// contains filtered or unexported fields
}
ASTTool inspects a source file's syntax tree via a pure-Go tree-sitter.
func (*ASTTool) Definition ¶
func (astTool *ASTTool) Definition() Definition
Definition returns ast tool metadata.
type Arguments ¶
type Arguments struct {
// contains filtered or unexported fields
}
Arguments is an immutable raw JSON object for tool input arguments.
func ArgumentsFromRaw ¶
ArgumentsFromRaw validates and stores raw JSON object arguments.
func EmptyArguments ¶
func EmptyArguments() Arguments
EmptyArguments returns an empty JSON object argument payload.
func (Arguments) Fields ¶
func (arguments Arguments) Fields() (map[string]json.RawMessage, error)
Fields decodes arguments as raw JSON object fields.
func (Arguments) MarshalJSON ¶
MarshalJSON implements json.Marshaler.
func (Arguments) RawMessage ¶
func (arguments Arguments) RawMessage() json.RawMessage
RawMessage returns a defensive copy of the raw JSON object.
type BashInput ¶
type BashInput struct {
Timeout *float64 `json:"timeout,omitempty"`
Command string `json:"command"`
}
BashInput contains arguments for the bash tool.
type BashTool ¶
type BashTool struct {
// contains filtered or unexported fields
}
BashTool executes shell commands in the configured working directory.
func NewBashTool ¶
NewBashTool creates the bash tool for cwd.
func (*BashTool) Definition ¶
func (bashTool *BashTool) Definition() Definition
Definition returns bash tool metadata.
type ContentBlock ¶
type ContentBlock struct {
Type string `json:"type"`
Text string `json:"text,omitempty"`
Data string `json:"data,omitempty"`
MIMEType string `json:"mime_type,omitempty"`
}
ContentBlock is one model-facing piece of tool output.
type Coordinator ¶
type Coordinator struct {
// contains filtered or unexported fields
}
Coordinator owns process-wide queues for conflicting workspace mutations. It coordinates one librecode process; SQLite task leases remain independent.
func NewCoordinator ¶
func NewCoordinator() *Coordinator
NewCoordinator creates a process-local mutation coordinator.
type Definition ¶
type Definition struct {
Schema Schema `json:"schema"`
Name Name `json:"name"`
Label string `json:"label"`
Description string `json:"description"`
PromptSnippet string `json:"prompt_snippet"`
PromptGuidelines []string `json:"prompt_guidelines"`
ReadOnly bool `json:"read_only"`
}
Definition describes a built-in coding tool.
func AllDefinitions ¶
func AllDefinitions() []Definition
AllDefinitions returns the definitions for all built-in tools.
type EditDetails ¶
type EditDetails struct {
Diff string `json:"diff"`
FirstChangedLine int `json:"first_changed_line,omitempty"`
Truncated bool `json:"truncated,omitempty"`
}
EditDetails describes the applied edit diff.
type EditInput ¶
type EditInput struct {
Path string `json:"path"`
Edits []Replacement `json:"edits"`
}
EditInput contains arguments for the edit tool.
type EditTool ¶
type EditTool struct {
// contains filtered or unexported fields
}
EditTool applies exact text replacements to files.
func NewEditTool ¶
NewEditTool creates the edit tool for cwd.
func (*EditTool) Definition ¶
func (editTool *EditTool) Definition() Definition
Definition returns edit tool metadata.
type Executor ¶
type Executor interface {
Definition() Definition
Execute(ctx context.Context, input Arguments) (Result, error)
}
Executor runs a built-in tool with raw JSON object input.
type FetchInput ¶
type FetchInput struct {
Timeout *int `json:"timeout,omitempty"`
Offset *int `json:"offset,omitempty"`
Limit *int `json:"limit,omitempty"`
URL string `json:"url"`
Format string `json:"format,omitempty" jsonschema:"enum=markdown,enum=text,enum=html"`
}
FetchInput contains arguments for the fetch tool.
type FetchTool ¶
type FetchTool struct {
// contains filtered or unexported fields
}
FetchTool fetches explicit HTTP(S) URLs.
func (*FetchTool) Definition ¶
func (fetchTool *FetchTool) Definition() Definition
Definition returns fetch tool metadata.
type FindInput ¶
type FindInput struct {
Limit *int `json:"limit,omitempty"`
Pattern string `json:"pattern"`
Path string `json:"path,omitempty"`
}
FindInput contains arguments for the find tool.
type FindTool ¶
type FindTool struct {
// contains filtered or unexported fields
}
FindTool searches file paths by glob pattern.
func NewFindTool ¶
NewFindTool creates the find tool for cwd.
func (*FindTool) Definition ¶
func (findTool *FindTool) Definition() Definition
Definition returns find tool metadata.
type GrepInput ¶
type GrepInput struct {
Context *int `json:"context,omitempty"`
Limit *int `json:"limit,omitempty"`
Pattern string `json:"pattern"`
Path string `json:"path,omitempty"`
Glob string `json:"glob,omitempty"`
IgnoreCase bool `json:"ignore_case,omitempty"`
Literal bool `json:"literal,omitempty"`
}
GrepInput contains arguments for the grep tool.
type GrepTool ¶
type GrepTool struct {
// contains filtered or unexported fields
}
GrepTool searches text files for patterns.
func NewGrepTool ¶
NewGrepTool creates the grep tool for cwd.
func (*GrepTool) Definition ¶
func (grepTool *GrepTool) Definition() Definition
Definition returns grep tool metadata.
type LSTool ¶
type LSTool struct {
// contains filtered or unexported fields
}
LSTool lists directory entries.
func (*LSTool) Definition ¶
func (lsTool *LSTool) Definition() Definition
Definition returns ls tool metadata.
type Name ¶
type Name string
Name identifies a built-in coding tool.
const ( // NameRead reads a file from disk. NameRead Name = "read" // NameBash executes a shell command. NameBash Name = "bash" // NameEdit applies exact text replacements to one file. NameEdit Name = "edit" // NameWrite writes a complete file. NameWrite Name = "write" // NameGrep searches file contents. NameGrep Name = "grep" // NameFind finds file paths by glob. NameFind Name = "find" // NameLS lists directory entries. NameLS Name = "ls" // NameAST inspects a file's syntax tree structure. NameAST Name = "ast" // NameFetch fetches explicit HTTP(S) URLs. NameFetch Name = "fetch" )
type PreparedCall ¶
type PreparedCall struct {
// contains filtered or unexported fields
}
PreparedCall is a validated tool invocation ready for execution. A call must not be used by multiple goroutines concurrently. Batch callers may Admit in source order, Execute on a worker, then Release after execution completes.
func (*PreparedCall) Admit ¶
func (call *PreparedCall) Admit()
Admit reserves any source-ordered resources needed by the call. Callers preparing a batch must admit calls in source order before executing them concurrently.
func (*PreparedCall) Execute ¶
func (call *PreparedCall) Execute(ctx context.Context) (Result, error)
Execute runs the prepared call.
func (*PreparedCall) Release ¶
func (call *PreparedCall) Release()
Release abandons resources reserved by Admit. It is safe to call after Execute.
func (PreparedCall) Sequential ¶
func (call PreparedCall) Sequential() bool
Sequential reports whether this call requires the whole batch to run in source order.
func (*PreparedCall) TryAdmit ¶
func (call *PreparedCall) TryAdmit() bool
TryAdmit reserves resources only when they are immediately available. A false result leaves the call prepared and may be retried later.
type ReadInput ¶
type ReadInput struct {
Offset *int `json:"offset,omitempty"`
Limit *int `json:"limit,omitempty"`
Path string `json:"path"`
AllowIgnored bool `json:"allow_ignored,omitempty"`
}
ReadInput contains arguments for the read tool.
type ReadTool ¶
type ReadTool struct {
// contains filtered or unexported fields
}
ReadTool reads text and image files from disk.
func NewReadTool ¶
NewReadTool creates the read tool for cwd.
func (*ReadTool) Definition ¶
func (readTool *ReadTool) Definition() Definition
Definition returns read tool metadata.
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry owns built-in tool executors for a working directory.
func NewRegistry ¶
NewRegistry creates a registry with every built-in tool enabled.
func NewRegistryWithCoordinator ¶
func NewRegistryWithCoordinator(cwd string, names []Name, coordinator *Coordinator) (*Registry, error)
NewRegistryWithCoordinator creates a registry sharing process-wide mutation coordination.
func NewRegistryWithTools ¶
NewRegistryWithTools creates a registry containing only the named built-in tools.
func (*Registry) Definitions ¶
func (registry *Registry) Definitions() []Definition
Definitions returns sorted tool definitions.
func (*Registry) DenyMutations ¶
func (registry *Registry) DenyMutations()
DenyMutations makes the registry reject tools not marked read-only. It is intended for non-interactive background executions that cannot ask for approval.
func (*Registry) Execute ¶
func (registry *Registry) Execute(ctx context.Context, name string, input Arguments) (Result, error)
Execute runs a named tool with raw JSON object arguments.
func (*Registry) ExecuteJSON ¶
func (registry *Registry) ExecuteJSON(ctx context.Context, name string, payload []byte) (Result, error)
ExecuteJSON runs a named tool with raw JSON object arguments.
func (*Registry) Prepare ¶
func (registry *Registry) Prepare(name string, input Arguments) (PreparedCall, error)
Prepare resolves and validates a named tool invocation without executing it.
type Replacement ¶
Replacement is one exact text replacement for the edit tool.
type Result ¶
type Result struct {
Details map[string]any `json:"details"`
Content []ContentBlock `json:"content"`
}
Result is returned by every built-in tool.
func TextResult ¶
TextResult creates a text-only tool result.
type Schema ¶
type Schema struct {
// contains filtered or unexported fields
}
Schema is an immutable JSON Schema document.
func EmptySchema ¶
func EmptySchema() Schema
EmptySchema returns the zero schema, meaning no explicit schema was provided.
func SchemaFromRaw ¶
SchemaFromRaw validates and stores a raw JSON Schema document.
func (Schema) MarshalJSON ¶
MarshalJSON implements json.Marshaler.
func (Schema) RawMessage ¶
func (schema Schema) RawMessage() json.RawMessage
RawMessage returns a defensive copy of the raw JSON schema.
type TruncatedBy ¶
type TruncatedBy string
TruncatedBy identifies the limit that caused truncation.
const ( // TruncatedByNone means content was not truncated. TruncatedByNone TruncatedBy = "" // TruncatedByLines means the line limit was reached first. TruncatedByLines TruncatedBy = "lines" // TruncatedByBytes means the byte limit was reached first. TruncatedByBytes TruncatedBy = "bytes" )
type TruncationOptions ¶
TruncationOptions controls head or tail truncation.
type TruncationResult ¶
type TruncationResult struct {
TruncatedBy TruncatedBy `json:"truncated_by"`
Content string `json:"content"`
TotalLines int `json:"total_lines"`
TotalBytes int `json:"total_bytes"`
OutputLines int `json:"output_lines"`
OutputBytes int `json:"output_bytes"`
MaxLines int `json:"max_lines"`
MaxBytes int `json:"max_bytes"`
Truncated bool `json:"truncated"`
LastLinePartial bool `json:"last_line_partial"`
FirstLineExceedsLimit bool `json:"first_line_exceeds_limit"`
}
TruncationResult describes how content was truncated.
func TruncateHead ¶
func TruncateHead(content string, options TruncationOptions) TruncationResult
TruncateHead keeps the first complete lines that fit within both limits.
func TruncateTail ¶
func TruncateTail(content string, options TruncationOptions) TruncationResult
TruncateTail keeps the last complete lines that fit within both limits.
type WriteInput ¶
WriteInput contains arguments for the write tool.
type WriteTool ¶
type WriteTool struct {
// contains filtered or unexported fields
}
WriteTool creates or overwrites complete files.
func NewWriteTool ¶
NewWriteTool creates the write tool for cwd.
func (*WriteTool) Definition ¶
func (writeTool *WriteTool) Definition() Definition
Definition returns write tool metadata.
Source Files
¶
- arguments.go
- ast.go
- ast_naming.go
- ast_outline.go
- ast_query.go
- ast_symbols.go
- bash.go
- bash_unix.go
- coordinator.go
- diff.go
- edit.go
- edit_diff.go
- errors.go
- fetch.go
- find.go
- grep.go
- helper.go
- ignore.go
- input_validation.go
- ls.go
- mutation_queue.go
- path.go
- read.go
- registry.go
- schema.go
- schema_generated.go
- tool_constants.go
- truncate.go
- types.go
- write.go