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: Tool that dispatches enriched-sprint generation across a JSONL plan. ABOUTME: Reads {path, description} per line and invokes WriteEnrichedSprintTool.RunOne for each, returning an aggregate summary.
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: 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.
ABOUTME: Tool that writes one enriched sprint markdown file per call from a project-wide contract + per-sprint description. ABOUTME: Architect (strong model) supplies the project map; this tool calls a mid-tier model (e.g. Sonnet) once per sprint.
Index ¶
- func IsToolTerminal(t Tool) bool
- type ApplyPatchTool
- type BashTool
- type CachePolicy
- type CachePolicyProvider
- type Completer
- type DispatchSprintsTool
- type EditTool
- type GenerateCodeOption
- type GenerateCodeTool
- type GlobTool
- type GrepSearchTool
- type ReadTool
- type Registry
- type SessionRunner
- type SpawnAgentTool
- type SprintRunResult
- type TerminalTool
- type Tool
- type WriteEnrichedSprintOption
- type WriteEnrichedSprintTool
- func (t *WriteEnrichedSprintTool) Description() string
- func (t *WriteEnrichedSprintTool) Execute(ctx context.Context, input json.RawMessage) (string, error)
- func (t *WriteEnrichedSprintTool) LoadContract(contractFile string) (string, error)
- func (t *WriteEnrichedSprintTool) Name() string
- func (t *WriteEnrichedSprintTool) Parameters() json.RawMessage
- func (t *WriteEnrichedSprintTool) RunOne(ctx context.Context, contract, path, description, outputDir string) (*SprintRunResult, error)
- 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.
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 DispatchSprintsTool ¶
type DispatchSprintsTool struct {
// contains filtered or unexported fields
}
DispatchSprintsTool reads a JSONL plan and runs the per-sprint author+audit pipeline once per line. The loop is mechanical — there is no LLM agency between sprints. The contract file is loaded once and shared across all sprints.
func NewDispatchSprintsTool ¶
func NewDispatchSprintsTool(inner *WriteEnrichedSprintTool, workDir string) *DispatchSprintsTool
NewDispatchSprintsTool wraps a WriteEnrichedSprintTool with a deterministic JSONL-driven loop.
func (*DispatchSprintsTool) Description ¶
func (t *DispatchSprintsTool) Description() string
func (*DispatchSprintsTool) Execute ¶
func (t *DispatchSprintsTool) Execute(ctx context.Context, input json.RawMessage) (string, error)
func (*DispatchSprintsTool) IsTerminal ¶
func (t *DispatchSprintsTool) IsTerminal() bool
IsTerminal flags this tool as the terminal step in the architect agent's session. When dispatch_sprints succeeds, the agent runtime ends the session immediately — there is no meaningful follow-up for the model. JSONL/contract validation errors still bubble back as tool errors so the agent can retry.
func (*DispatchSprintsTool) Name ¶
func (t *DispatchSprintsTool) Name() string
func (*DispatchSprintsTool) Parameters ¶
func (t *DispatchSprintsTool) Parameters() json.RawMessage
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 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 SprintRunResult ¶
type SprintRunResult struct {
Path string
Bytes int
Verdict string
PatchesApplied int
Model string
AuthorIn int
AuthorOut int
AuditIn int
AuditOut int
}
SprintRunResult captures the per-sprint outcome of RunOne. Used by callers (Execute and dispatch_sprints) to format summaries and aggregate counts.
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 WriteEnrichedSprintOption ¶
type WriteEnrichedSprintOption func(*WriteEnrichedSprintTool)
WriteEnrichedSprintOption configures the WriteEnrichedSprintTool.
func WithSprintWriterEnv ¶
func WithSprintWriterEnv(env exec.ExecutionEnvironment) WriteEnrichedSprintOption
WithSprintWriterEnv routes file writes through the supplied ExecutionEnvironment so the writable_paths fs-jail (#272) can intercept generated sprint 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 WithSprintWriterWorkDir would get filepath.Rel(env.WorkingDir(), absPath) producing a leading "../..." that env.WriteFile rejects — the tool would silently stop writing files (#275 review, Copilot write_enriched_sprint.go:57).
func WithSprintWriterModel ¶
func WithSprintWriterModel(model string) WriteEnrichedSprintOption
WithSprintWriterModel sets the model used to write each sprint.
func WithSprintWriterProvider ¶
func WithSprintWriterProvider(provider string) WriteEnrichedSprintOption
WithSprintWriterProvider sets the provider used to write each sprint.
func WithSprintWriterWorkDir ¶
func WithSprintWriterWorkDir(dir string) WriteEnrichedSprintOption
WithSprintWriterWorkDir sets the base directory for writing sprint files.
type WriteEnrichedSprintTool ¶
type WriteEnrichedSprintTool struct {
// contains filtered or unexported fields
}
WriteEnrichedSprintTool calls a mid-tier LLM once per sprint to write an enriched sprint markdown file from a project-wide architectural contract plus a per-sprint description.
func NewWriteEnrichedSprintTool ¶
func NewWriteEnrichedSprintTool(client Completer, opts ...WriteEnrichedSprintOption) *WriteEnrichedSprintTool
NewWriteEnrichedSprintTool creates a tool that writes enriched sprint markdown.
func (*WriteEnrichedSprintTool) Description ¶
func (t *WriteEnrichedSprintTool) Description() string
func (*WriteEnrichedSprintTool) Execute ¶
func (t *WriteEnrichedSprintTool) Execute(ctx context.Context, input json.RawMessage) (string, error)
Execute is the LLM-tool entry point. Parses args, loads contract, runs one sprint.
func (*WriteEnrichedSprintTool) LoadContract ¶
func (t *WriteEnrichedSprintTool) LoadContract(contractFile string) (string, error)
LoadContract reads the contract file from disk. Resolves relative paths against workDir. Empty contractFile defaults to ".ai/contract.md".
When a workDir is set, validates that the resolved path stays inside it. The contract content is shipped to the LLM provider as prompt context, so a traversal here is a data-exfiltration vector. Both relative paths with ".." segments and absolute paths pointing outside workDir are rejected.
func (*WriteEnrichedSprintTool) Name ¶
func (t *WriteEnrichedSprintTool) Name() string
func (*WriteEnrichedSprintTool) Parameters ¶
func (t *WriteEnrichedSprintTool) Parameters() json.RawMessage
func (*WriteEnrichedSprintTool) RunOne ¶
func (t *WriteEnrichedSprintTool) RunOne(ctx context.Context, contract, path, description, outputDir string) (*SprintRunResult, error)
RunOne authors + audits + writes one sprint file. Caller supplies the contract (already loaded) and a fully-resolved output directory. Returns a structured result so callers (Execute, dispatch_sprints) can format their own summaries.
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