Documentation
¶
Overview ¶
Package tools defines the structured-tool registry, the Tool interface, and the shared tool-dispatch Result type.
Index ¶
Constants ¶
const BuiltinSource = "built-in"
BuiltinSource is the stable source token built-in tools register under. Built-ins have no file path, so this token stands in for a <path> in the duplicate-name error line when a built-in/built-in collision occurs (a programmer error).
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type DuplicateNameError ¶
DuplicateNameError reports two tools registered under the same name from the same source — a programmer error. Its Error is the exact stderr line, with sources in first-seen-then-duplicate order so the rendered bytes are deterministic.
func (*DuplicateNameError) Error ¶
func (e *DuplicateNameError) Error() string
type Metadata ¶
type Metadata struct {
Description string
Parameters map[string]any
ReadOnly bool
Noncredential bool
}
Metadata is the advertising metadata and read-only classification a Tool exposes. Description is a one-line natural-language summary of what the tool does and when to use it. Parameters is a JSON-Schema object in the OpenAI function-tool shape describing the tool's arguments; it stays a provider-agnostic map so the advertised-tool assembly can translate it onto provider.Request without this package importing the provider. ReadOnly is the single read-only-vs-mutating classification that drives both Plan's advertised-tool filter and the mutating/edit posture; its zero value (false = mutating) is the safe default for sources that are not product-verified read-only code. Noncredential is the product's classification of the operation, not of its target: an ordinary file read stays noncredential for a credential-named path. Its zero value is credential-handling, so a tool that does not advertise the classification cannot join an authorization batch.
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry is a flat, exact-name map of tools. It performs no regex or shell-equivalence matching; Lookup is exact-name only.
func NewRegistry ¶
func NewRegistry() *Registry
NewRegistry returns an empty registry that writes same-name replacement warnings to os.Stderr.
func (*Registry) List ¶
List returns every registered tool in a deterministic order (ascending by Name) so the advertised-tool assembly can enumerate the active registry without depending on map iteration order. A name registered more than once across sources appears once, as the winning (last-registered) tool, because a cross-source replacement overwrites the map entry and a same-source duplicate is rejected without changing it.
func (*Registry) Lookup ¶
Lookup returns the tool registered under name and whether one exists. Matching is exact-name only; there is no pattern or shell-equivalence fallback.
func (*Registry) Register ¶
Register adds t under its Name() from the given source. Load order is built-ins then per-project. A same-name registration from a *different* source replaces the prior tool, keeps the later registration in effect, and emits a single stderr warning naming the replaced tool and the winning source's path. A same-name registration from the *same* source is a hard error: it prints the exact duplicate line, returns a *DuplicateNameError and leaves the registry unchanged.
type Result ¶
type Result struct {
ExitCode int
Stdout []byte
Stderr []byte
Duration time.Duration
DisplayPatch string
// ModelContextImage is the data URI a tool produces from the bytes it already captured for
// this result, so the model context and the reported result cannot describe two different
// reads of the same path. Empty for every tool that produces no image.
ModelContextImage string
}
Result is the shared dispatch/tool result returned by every Tool.Invoke. The direct and structured dispatchers and the vcs_<action> tool return Result after adapting any lower-level runner result; it is mapped onto the tool_exec_* events after stdout/stderr truncation.
type Tool ¶
type Tool interface {
// Name is the exact dispatch name; the registry indexes tools by it.
Name() string
// Invoke runs the tool with decoded arguments and returns its dispatch result.
Invoke(ctx context.Context, args map[string]any) (Result, error)
// SubjectKind returns the permission subject kind for this tool; always "tool".
SubjectKind() string
// Advertise returns the tool's advertising metadata and read-only classification.
Advertise() Metadata
}
Tool is a structured tool dispatched by exact name.
Source Files