Documentation
¶
Overview ¶
ABOUTME: Bash tool executes shell commands in the working directory. ABOUTME: Supports configurable default/max timeouts and returns stdout+stderr+exit code.
ABOUTME: Canonical Completer interface used by tools that need direct LLM ABOUTME: access (generate_code, write_enriched_sprint). Re-exported by the ABOUTME: agent package as a type alias so the two are identical, not parallel.
ABOUTME: EditFile tool performs exact search/replace on files in the working directory. ABOUTME: Requires unique match of old_string. Empty old_string with missing file creates a new file.
ABOUTME: Tool that generates code via a cheap/fast LLM from a structured contract. ABOUTME: Implements the hybrid architect/executor pattern — strong model writes contract, this tool calls cheap model.
ABOUTME: Glob tool searches for files matching a pattern in the working directory. ABOUTME: Returns matching file paths separated by newlines, or a "no matches" message.
ABOUTME: GrepSearch tool searches for regex patterns in files within the working directory. ABOUTME: Returns matching lines formatted as filepath:linenum:content, with a configurable result limit.
ABOUTME: ReadFile tool reads the contents of a file in the working directory. ABOUTME: Accepts path, offset, and limit parameters and returns file contents as a string.
ABOUTME: Tool interface and Registry for agent tool dispatch. ABOUTME: Tools register by name, export LLM tool definitions, and execute via ToolCallData.
ABOUTME: report_status — the agent narrates high-level progress in its own words, ABOUTME: piggybacked on a normal turn (no dedicated LLM call), surfaced as a first-class event (#494).
ABOUTME: Built-in tool that spawns a child agent session for delegated subtasks. ABOUTME: The child runs to completion and its final text output becomes the tool result.
ABOUTME: Output truncation for agent tool results. ABOUTME: Keeps the tail of long outputs to preserve error messages, with a marker showing truncated amount.
ABOUTME: WriteFile tool creates or overwrites a file in the working directory. ABOUTME: Accepts path and content parameters, creates parent directories as needed.
Index ¶
- func IsToolTerminal(t Tool) bool
- func ResolveUnderRoot(root, rel string) (string, error)
- type ApplyPatchTool
- type BashTool
- type CachePolicy
- type CachePolicyProvider
- type Completer
- type EditTool
- type GenerateCodeOption
- type GenerateCodeTool
- type GlobTool
- type GrepSearchTool
- type ReadTool
- type Registry
- type ReportStatusTool
- type SessionRunner
- type SpawnAgentTool
- type TerminalTool
- type Tool
- type WriteTool
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func IsToolTerminal ¶
IsToolTerminal reports whether the given tool implements TerminalTool and has flagged itself as terminal. Returns false for tools that don't implement the interface.
func ResolveUnderRoot ¶ added in v0.53.0
ResolveUnderRoot is the exported seam for the sibling domain package agent/tools/sprintwriter (built on this primitive tool library) so it can reuse the same path-confinement check without duplicating the symlink-aware logic. It delegates to the unexported resolveUnderRoot.
Types ¶
type ApplyPatchTool ¶
type ApplyPatchTool struct {
// contains filtered or unexported fields
}
func NewApplyPatchTool ¶
func NewApplyPatchTool(env exec.ExecutionEnvironment) *ApplyPatchTool
func (*ApplyPatchTool) CachePolicy ¶
func (t *ApplyPatchTool) CachePolicy() CachePolicy
CachePolicy declares that apply_patch is mutating and invalidates caches.
func (*ApplyPatchTool) Description ¶
func (t *ApplyPatchTool) Description() string
func (*ApplyPatchTool) Execute ¶
func (t *ApplyPatchTool) Execute(ctx context.Context, input json.RawMessage) (string, error)
func (*ApplyPatchTool) Name ¶
func (t *ApplyPatchTool) Name() string
func (*ApplyPatchTool) Parameters ¶
func (t *ApplyPatchTool) Parameters() json.RawMessage
type BashTool ¶
type BashTool struct {
// contains filtered or unexported fields
}
BashTool runs shell commands via the execution environment.
func NewBashTool ¶
func NewBashTool(env exec.ExecutionEnvironment, defaultTimeout, maxTimeout time.Duration) *BashTool
NewBashTool creates a BashTool with the given environment and timeout bounds.
func (*BashTool) CachePolicy ¶
func (t *BashTool) CachePolicy() CachePolicy
CachePolicy declares that bash execution is mutating and invalidates caches.
func (*BashTool) Description ¶
func (*BashTool) Parameters ¶
func (t *BashTool) Parameters() json.RawMessage
type CachePolicy ¶
type CachePolicy int
CachePolicy declares how a tool's results may be cached.
const ( // CachePolicyNone means the tool has no caching opinion (default). CachePolicyNone CachePolicy = iota // CachePolicyCacheable means results can be cached for identical inputs. CachePolicyCacheable // CachePolicyMutating means the tool modifies state and invalidates caches. CachePolicyMutating )
func GetCachePolicy ¶
func GetCachePolicy(t Tool) CachePolicy
GetCachePolicy returns the CachePolicy for a tool. If the tool implements CachePolicyProvider, its declared policy is returned; otherwise CachePolicyNone.
type CachePolicyProvider ¶
type CachePolicyProvider interface {
CachePolicy() CachePolicy
}
CachePolicyProvider is an optional interface tools can implement to declare caching behavior.
type Completer ¶
Completer is the minimal LLM-call surface a tool needs to invoke the model directly (e.g. for an audit pass or per-file generation). The agent package re-exports this as a type alias so the two interfaces are literally the same type, preventing silent divergence.
type EditTool ¶
type EditTool struct {
// contains filtered or unexported fields
}
EditTool implements the Tool interface for search/replace editing of files.
func NewEditTool ¶
func NewEditTool(env exec.ExecutionEnvironment) *EditTool
NewEditTool creates an EditTool backed by the given execution environment.
func (*EditTool) CachePolicy ¶
func (t *EditTool) CachePolicy() CachePolicy
CachePolicy declares that edit is mutating and invalidates caches.
func (*EditTool) Description ¶
func (*EditTool) Parameters ¶
func (t *EditTool) Parameters() json.RawMessage
type GenerateCodeOption ¶
type GenerateCodeOption func(*GenerateCodeTool)
GenerateCodeOption configures the GenerateCodeTool.
func WithGenerateEnv ¶
func WithGenerateEnv(env exec.ExecutionEnvironment) GenerateCodeOption
WithGenerateEnv routes file writes through the supplied ExecutionEnvironment so the writable_paths fs-jail (#272) can intercept generated-file writes alongside the openat2-protected env.WriteFile path. When nil (default), the tool falls back to direct os.WriteFile — fine for the unjailed code path but bypasses the jail when writable_paths is set (#275 audit pass).
If workDir is still empty when this option fires, defaults it to env.WorkingDir(). Without that default, a caller that supplies env but not WithGenerateWorkDir would get filepath.Rel(env.WorkingDir(), absPath) producing a leading "../..." that env.WriteFile rejects — the tool would silently stop writing files (#275 review, Copilot generate_code.go:51).
func WithGenerateModel ¶
func WithGenerateModel(model string) GenerateCodeOption
WithGenerateModel sets the model used for code generation.
func WithGenerateProvider ¶
func WithGenerateProvider(provider string) GenerateCodeOption
WithGenerateProvider sets the provider used for code generation.
func WithGenerateWorkDir ¶
func WithGenerateWorkDir(dir string) GenerateCodeOption
WithGenerateWorkDir sets the base directory for writing generated files.
type GenerateCodeTool ¶
type GenerateCodeTool struct {
// contains filtered or unexported fields
}
GenerateCodeTool calls a cheap LLM to generate code from a structured contract.
func NewGenerateCodeTool ¶
func NewGenerateCodeTool(client Completer, opts ...GenerateCodeOption) *GenerateCodeTool
NewGenerateCodeTool creates a tool that generates code via a cheap model. Callers should override the model with WithGenerateModel — there is no universally-correct default. The env-gated registration in pipeline/handlers/backend_native.go always supplies one, so this default only matters for direct construction.
func (*GenerateCodeTool) Description ¶
func (t *GenerateCodeTool) Description() string
func (*GenerateCodeTool) Execute ¶
func (t *GenerateCodeTool) Execute(ctx context.Context, input json.RawMessage) (string, error)
func (*GenerateCodeTool) Name ¶
func (t *GenerateCodeTool) Name() string
func (*GenerateCodeTool) Parameters ¶
func (t *GenerateCodeTool) Parameters() json.RawMessage
type GlobTool ¶
type GlobTool struct {
// contains filtered or unexported fields
}
GlobTool finds files matching a glob pattern relative to the working directory.
func NewGlobTool ¶
func NewGlobTool(env exec.ExecutionEnvironment) *GlobTool
NewGlobTool creates a GlobTool bound to the given execution environment.
func (*GlobTool) CachePolicy ¶
func (t *GlobTool) CachePolicy() CachePolicy
CachePolicy declares that glob results are cacheable for identical inputs.
func (*GlobTool) Description ¶
func (*GlobTool) Parameters ¶
func (t *GlobTool) Parameters() json.RawMessage
type GrepSearchTool ¶
type GrepSearchTool struct {
// contains filtered or unexported fields
}
GrepSearchTool searches for regex patterns across files in the working directory.
func NewGrepSearchTool ¶
func NewGrepSearchTool(env exec.ExecutionEnvironment) *GrepSearchTool
NewGrepSearchTool creates a GrepSearchTool bound to the given execution environment.
func (*GrepSearchTool) CachePolicy ¶
func (t *GrepSearchTool) CachePolicy() CachePolicy
CachePolicy declares that grep results are cacheable for identical inputs.
func (*GrepSearchTool) Description ¶
func (t *GrepSearchTool) Description() string
func (*GrepSearchTool) Execute ¶
func (t *GrepSearchTool) Execute(ctx context.Context, input json.RawMessage) (string, error)
func (*GrepSearchTool) Name ¶
func (t *GrepSearchTool) Name() string
func (*GrepSearchTool) Parameters ¶
func (t *GrepSearchTool) Parameters() json.RawMessage
type ReadTool ¶
type ReadTool struct {
// contains filtered or unexported fields
}
ReadTool implements the Tool interface for reading file contents.
func NewReadTool ¶
func NewReadTool(env exec.ExecutionEnvironment) *ReadTool
NewReadTool creates a ReadTool backed by the given execution environment.
func (*ReadTool) CachePolicy ¶
func (t *ReadTool) CachePolicy() CachePolicy
CachePolicy declares that read results are cacheable for identical inputs.
func (*ReadTool) Description ¶
func (*ReadTool) Parameters ¶
func (t *ReadTool) Parameters() json.RawMessage
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry holds registered tools and dispatches execution requests.
func (*Registry) Definitions ¶
func (r *Registry) Definitions() []llm.ToolDefinition
Definitions returns LLM-compatible tool definitions for all registered tools, sorted alphabetically by name for deterministic ordering.
func (*Registry) Execute ¶
func (r *Registry) Execute(ctx context.Context, call llm.ToolCallData) llm.ToolResultData
Execute dispatches a tool call to the appropriate registered tool and returns the result. Returns an error result if the tool is not found or execution fails.
func (*Registry) SetOutputLimits ¶
SetOutputLimits configures per-tool output truncation limits.
type ReportStatusTool ¶ added in v0.47.0
type ReportStatusTool struct {
// contains filtered or unexported fields
}
ReportStatusTool lets the agent emit a plain-language status update — "what I'm doing / what I just finished / where I am in the job" — as a first-class event, distinct from the turn/tool firehose. It's cheap by design: the agent calls it as part of work it's already doing, and it makes no LLM call itself.
func NewReportStatusTool ¶ added in v0.47.0
func NewReportStatusTool(emit func(status string)) *ReportStatusTool
NewReportStatusTool builds the tool with the session's status-emit callback.
func (*ReportStatusTool) CachePolicy ¶ added in v0.47.0
func (t *ReportStatusTool) CachePolicy() CachePolicy
CachePolicy: never cache — a status is a point-in-time side effect.
func (*ReportStatusTool) Description ¶ added in v0.47.0
func (t *ReportStatusTool) Description() string
func (*ReportStatusTool) Execute ¶ added in v0.47.0
func (t *ReportStatusTool) Execute(_ context.Context, input json.RawMessage) (string, error)
func (*ReportStatusTool) Name ¶ added in v0.47.0
func (t *ReportStatusTool) Name() string
func (*ReportStatusTool) Parameters ¶ added in v0.47.0
func (t *ReportStatusTool) Parameters() json.RawMessage
type SessionRunner ¶
type SessionRunner interface {
RunChild(ctx context.Context, task string, systemPrompt string, maxTurns int) (string, error)
}
SessionRunner abstracts the ability to run a child agent session. This interface breaks the circular dependency between agent/tools and agent packages: the tools package defines what it needs, and the agent package provides the implementation.
type SpawnAgentTool ¶
type SpawnAgentTool struct {
// contains filtered or unexported fields
}
SpawnAgentTool delegates a subtask to a child agent session and returns its output.
func NewSpawnAgentTool ¶
func NewSpawnAgentTool(runner SessionRunner) *SpawnAgentTool
NewSpawnAgentTool creates a SpawnAgentTool backed by the given SessionRunner.
func (*SpawnAgentTool) CachePolicy ¶
func (t *SpawnAgentTool) CachePolicy() CachePolicy
CachePolicy declares that spawn_agent is mutating and invalidates caches.
func (*SpawnAgentTool) Description ¶
func (t *SpawnAgentTool) Description() string
func (*SpawnAgentTool) Execute ¶
func (t *SpawnAgentTool) Execute(ctx context.Context, input json.RawMessage) (string, error)
func (*SpawnAgentTool) Name ¶
func (t *SpawnAgentTool) Name() string
func (*SpawnAgentTool) Parameters ¶
func (t *SpawnAgentTool) Parameters() json.RawMessage
type TerminalTool ¶
type TerminalTool interface {
IsTerminal() bool
}
TerminalTool is implemented by tools whose successful invocation should end the agent session immediately. The agent runtime checks this flag after executing the tool's call: if the call succeeded (no error) AND the tool is terminal, the session loop breaks before requesting another LLM turn.
On tool error the loop continues normally so the model can react to the failure (fix args, retry, give up by emitting text-only).
Use this for deterministic last-step tools that have no meaningful follow-up for the agent — e.g., tools that complete a multi-step pipeline phase.
type Tool ¶
type Tool interface {
Name() string
Description() string
Parameters() json.RawMessage
Execute(ctx context.Context, input json.RawMessage) (string, error)
}
Tool defines the interface that all agent tools must implement.
type WriteTool ¶
type WriteTool struct {
// contains filtered or unexported fields
}
WriteTool implements the Tool interface for writing file contents.
func NewWriteTool ¶
func NewWriteTool(env exec.ExecutionEnvironment) *WriteTool
NewWriteTool creates a WriteTool backed by the given execution environment.
func (*WriteTool) CachePolicy ¶
func (t *WriteTool) CachePolicy() CachePolicy
CachePolicy declares that write is mutating and invalidates caches.
func (*WriteTool) Description ¶
func (*WriteTool) Parameters ¶
func (t *WriteTool) Parameters() json.RawMessage
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
ABOUTME: Auditor-response parsing: tolerant verdict detection and Aider-style ABOUTME: SEARCH/REPLACE block extraction for the enriched-sprint audit pass.
|
ABOUTME: Auditor-response parsing: tolerant verdict detection and Aider-style ABOUTME: SEARCH/REPLACE block extraction for the enriched-sprint audit pass. |