tools

package
v0.0.0-...-75ec8e3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 28, 2026 License: MIT Imports: 53 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	ToolNameReadFile             = "read_file"
	ToolNameReadFileSummarized   = "read_file_summarized"
	ToolNameCreateFile           = "create_file"
	ToolNameReplaceFile          = "replace_file"
	ToolNameEditFile             = "edit_file"
	ToolNameShell                = "shell"
	ToolNameCommand              = "command"
	ToolNameStatusProgram        = "status_program"
	ToolNameWaitProgram          = "wait_program"
	ToolNameStopProgram          = "stop_program"
	ToolNameParallel             = "parallel_tool_execution"
	ToolNameGoSandbox            = "go_sandbox"
	ToolNameGoSandboxDomain      = "go_sandbox_domain"
	ToolNameWebSearch            = "web_search"
	ToolNameWebFetch             = "web_fetch"
	ToolNameToolSummarize        = "tool_summarize"
	ToolNameTodo                 = "todo"
	ToolNameSearchFiles          = "search_files"
	ToolNameSearchFileContent    = "search_file_content"
	ToolNameCodebaseInvestigator = "codebase_investigator"
	ToolNameValidateSyntax       = "validate_syntax"
	ToolNameLs                   = "list_dir"
	ToolNameSearchContextFiles   = "search_context_files"
	ToolNameGrepContextFiles     = "grep_context_files"
	ToolNameReadContextFile      = "read_context_file"
	ToolNameAddContextDirectory  = "add_context_directory"
	ToolNameRefactoringAgent     = "refactoring_agent"
)
View Source 
const MIN_SLEEP_SECONDS = 1

MIN_SLEEP_SECONDS is the minimum sleep duration for retries

View Source 
const MaxTimeoutSeconds = 600
View Source 
const ToolNameRequestDirectoryAccess = "request_directory_access"

Variables

This section is empty.

Functions

func CalculateOutputStats 

func CalculateOutputStats(output string) (int, int)

CalculateOutputStats calculates byte and line statistics for output strings

func ContextWithShellBackground 

func ContextWithShellBackground(ctx context.Context, ch chan struct{}) context.Context

func ExtractPlanResult 

func ExtractPlanResult(result interface{}) ([]string, error)

ExtractPlanResult is a helper to extract just the plan array from a result

func ExtractTrivialText 

func ExtractTrivialText(code string) string

ExtractTrivialText extracts the text output from trivial code that only contains fmt.Print*/println calls with literal arguments. Returns the concatenated text, or "" if extraction fails.

func FormatTodoPlanAsText 

func FormatTodoPlanAsText(todos *TodoList) string

FormatTodoPlanAsText formats the todos as a readable plan text for display

func GetBoolParam 

func GetBoolParam(params map[string]interface{}, key string, defaultVal bool) bool

Helper function to get bool parameter

func GetEmbeddedArchive 

func GetEmbeddedArchive() []byte

GetEmbeddedArchive returns the embedded TinyGo archive data

func GetIntParam 

func GetIntParam(params map[string]interface{}, key string, defaultVal int) int

Helper function to get int parameter

func GetStringParam 

func GetStringParam(params map[string]interface{}, key string, defaultVal string) string

Helper function to get string parameter

func HasEmbeddedArchive 

func HasEmbeddedArchive() bool

HasEmbeddedArchive returns true if a TinyGo archive is embedded in the binary

func IsHomeDirectory 

func IsHomeDirectory(path string) (bool, error)

IsHomeDirectory checks if the given path is the user's home directory. It handles path normalization, symlinks, and trailing slashes. Returns true if the path resolves to the home directory, false otherwise. Subdirectories of the home directory (e.g., ~/Documents) are allowed and will return false.

func IsTrivialCode 

func IsTrivialCode(code string) bool

IsTrivialCode checks if the code only contains imports, comments, and fmt print statements without any substantial logic or operations using AST parsing for accurate results

func NewFSAdapter 

func NewFSAdapter(ctx context.Context, filesystem internalfs.FileSystem) fs.FS

NewFSAdapter creates an adapter that wraps our FileSystem to implement fs.FS

func NewTaskSummaryToolFactory 

func NewTaskSummaryToolFactory(sess *session.Session) func(*Registry) ToolExecutor

NewTaskSummaryToolFactory creates a factory function for the task summary tool

func WrapLegacyTool 

func WrapLegacyTool(tool Tool) (ToolSpec, ToolFactory)

WrapLegacyTool creates a spec and factory from a legacy Tool

Types

type AddContextDirectoryTool 

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

AddContextDirectoryTool adds directories to the context configuration

func NewAddContextDirectoryTool 

func NewAddContextDirectoryTool(filesystem fs.FileSystem, cfg *config.Config, sess *session.Session) *AddContextDirectoryTool

func (*AddContextDirectoryTool) Description 

func (t *AddContextDirectoryTool) Description() string

func (*AddContextDirectoryTool) Execute 

func (t *AddContextDirectoryTool) Execute(ctx context.Context, params map[string]interface{}) *ToolResult

func (*AddContextDirectoryTool) Name 

func (t *AddContextDirectoryTool) Name() string

func (*AddContextDirectoryTool) Parameters 

func (t *AddContextDirectoryTool) Parameters() map[string]interface{}

type AddContextDirectoryToolSpec 

type AddContextDirectoryToolSpec struct{}

AddContextDirectoryToolSpec is the static specification for the add_context_directory tool

func (*AddContextDirectoryToolSpec) Description 

func (s *AddContextDirectoryToolSpec) Description() string

func (*AddContextDirectoryToolSpec) Name 

func (s *AddContextDirectoryToolSpec) Name() string

func (*AddContextDirectoryToolSpec) Parameters 

func (s *AddContextDirectoryToolSpec) Parameters() map[string]interface{}

type AuthorizationActor 

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

AuthorizationActor handles policy decisions for tool calls in a centralized manner.

func NewAuthorizationActor 

func NewAuthorizationActor(id string, filesystem fs.FileSystem, sess *session.Session, summarizeClient llm.Client, opts *AuthorizationOptions) *AuthorizationActor

NewAuthorizationActor constructs a new authorization actor instance.

func (*AuthorizationActor) ID 

func (a *AuthorizationActor) ID() string

ID returns the actor identifier.

func (*AuthorizationActor) Receive 

func (a *AuthorizationActor) Receive(ctx context.Context, message actor.Message) error

Receive processes incoming authorization requests.

func (*AuthorizationActor) Start 

func (a *AuthorizationActor) Start(ctx context.Context) error

Start implements the actor.Actor interface. No initialization needed for now.

func (*AuthorizationActor) Stop 

func (a *AuthorizationActor) Stop(ctx context.Context) error

Stop implements the actor.Actor interface. Nothing to clean up currently.

type AuthorizationActorClient 

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

AuthorizationActorClient is the synchronous facade used by callers to reach the actor.

func (*AuthorizationActorClient) Authorize 

func (c *AuthorizationActorClient) Authorize(ctx context.Context, toolName string, params map[string]interface{}) (*AuthorizationDecision, error)

Authorize sends a request to the authorization actor and waits for the decision.

type AuthorizationDecision 

type AuthorizationDecision struct {
	Allowed                bool
	Reason                 string
	RequiresUserInput      bool   // If true, the caller should prompt the user for approval
	SuggestedCommandPrefix string // Optional command prefix that can be authorized for future runs
}

AuthorizationDecision captures the result of an authorization check.

type AuthorizationOptions 

type AuthorizationOptions struct {
	DangerouslyAllowAll bool
	AllowAllNetwork     bool
	AllowedDirs         []string
	AllowedFiles        []string
	AllowedDomains      []string
	AllowedCommands     []string // Command prefixes that are pre-authorized
	RequireSandboxAuth  bool     // Require authorization for every go_sandbox and shell call
}

AuthorizationOptions configure pre-authorizations for the actor.

type AuthorizationPersistenceConfig 

type AuthorizationPersistenceConfig struct {
	Config     *config.Config
	ConfigPath string
}

AuthorizationPersistenceConfig holds references needed to persist authorization decisions

type AuthorizationResponse 

type AuthorizationResponse struct {
	Decision *AuthorizationDecision
	Err      error
}

AuthorizationResponse contains the outcome of an authorization request.

type AuthorizeToolCallMessage 

type AuthorizeToolCallMessage struct {
	ToolName     string
	Params       map[string]interface{}
	RequestCtx   context.Context
	ResponseChan chan AuthorizationResponse
}

AuthorizeToolCallMessage requests authorization for a tool invocation.

func (*AuthorizeToolCallMessage) Type 

func (m *AuthorizeToolCallMessage) Type() string

Type implements actor.Message for AuthorizeToolCallMessage.

type AuthorizedFS 

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

AuthorizedFS wraps a FileSystem and enforces authorization rules It ensures that sandboxed code can only access files that have been previously read via the read_file tool (read-before-write rule)

func NewAuthorizedFS 

func NewAuthorizedFS(underlying internalfs.FileSystem, sess *session.Session, workingDir string) *AuthorizedFS

NewAuthorizedFS creates a new authorized filesystem wrapper

func (*AuthorizedFS) Delete 

func (afs *AuthorizedFS) Delete(ctx context.Context, path string) error

Delete removes a file with authorization check (requires prior read)

func (*AuthorizedFS) DeleteAll 

func (afs *AuthorizedFS) DeleteAll(ctx context.Context, path string) error

DeleteAll removes a directory and contents with authorization check

func (*AuthorizedFS) Exists 

func (afs *AuthorizedFS) Exists(ctx context.Context, path string) (bool, error)

Exists checks if a file exists (always allowed)

func (*AuthorizedFS) ListDir 

func (afs *AuthorizedFS) ListDir(ctx context.Context, path string) ([]*internalfs.FileInfo, error)

ListDir lists directory contents (always allowed)

func (*AuthorizedFS) MkdirAll 

func (afs *AuthorizedFS) MkdirAll(ctx context.Context, path string, perm os.FileMode) error

MkdirAll creates directories (always allowed, no authorization needed)

func (*AuthorizedFS) Move 

func (afs *AuthorizedFS) Move(ctx context.Context, src, dst string) error

Move renames or moves a file/directory with authorization check

func (*AuthorizedFS) ReadFile 

func (afs *AuthorizedFS) ReadFile(ctx context.Context, path string) ([]byte, error)

ReadFile reads a file with authorization check

func (*AuthorizedFS) ReadFileLines 

func (afs *AuthorizedFS) ReadFileLines(ctx context.Context, path string, from, to int) ([]string, error)

ReadFileLines reads file lines with authorization check

func (*AuthorizedFS) Stat 

func (afs *AuthorizedFS) Stat(ctx context.Context, path string) (*internalfs.FileInfo, error)

Stat returns file information (always allowed)

func (*AuthorizedFS) WriteFile 

func (afs *AuthorizedFS) WriteFile(ctx context.Context, path string, data []byte) error

WriteFile writes a file with authorization check (requires prior read)

type Authorizer 

type Authorizer interface {
	Authorize(ctx context.Context, toolName string, params map[string]interface{}) (*AuthorizationDecision, error)
}

Authorizer defines the contract for authorizing tool calls before execution.

func NewAuthorizationActorClient 

func NewAuthorizationActorClient(ref *actor.ActorRef) Authorizer

NewAuthorizationActorClient wraps an actor reference with the Authorizer interface.

type CodebaseInvestigatorTool 

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

CodebaseInvestigatorTool is the executor with runtime dependencies

func NewCodebaseInvestigatorTool 

func NewCodebaseInvestigatorTool(investigator Investigator) *CodebaseInvestigatorTool

func (*CodebaseInvestigatorTool) Description 

func (t *CodebaseInvestigatorTool) Description() string

func (*CodebaseInvestigatorTool) Execute 

func (t *CodebaseInvestigatorTool) Execute(ctx context.Context, params map[string]interface{}) *ToolResult

func (*CodebaseInvestigatorTool) Name 

func (t *CodebaseInvestigatorTool) Name() string

Legacy interface implementation for backward compatibility

func (*CodebaseInvestigatorTool) Parameters 

func (t *CodebaseInvestigatorTool) Parameters() map[string]interface{}

type CodebaseInvestigatorToolSpec 

type CodebaseInvestigatorToolSpec struct{}

CodebaseInvestigatorToolSpec is the static specification for the codebase_investigator tool

func (*CodebaseInvestigatorToolSpec) Description 

func (s *CodebaseInvestigatorToolSpec) Description() string

func (*CodebaseInvestigatorToolSpec) Name 

func (s *CodebaseInvestigatorToolSpec) Name() string

func (*CodebaseInvestigatorToolSpec) Parameters 

func (s *CodebaseInvestigatorToolSpec) Parameters() map[string]interface{}

type CommandTool 

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

CommandTool executes a local command and returns its output.

func NewCommandTool 

func NewCommandTool(cfg *CommandToolConfig) *CommandTool

NewCommandTool constructs a CommandTool from the provided configuration.

func (*CommandTool) Description 

func (c *CommandTool) Description() string

Description implements Tool.

func (*CommandTool) Execute 

func (c *CommandTool) Execute(ctx context.Context, params map[string]interface{}) *ToolResult

Execute runs the configured command with optional STDIN and extra arguments.

func (*CommandTool) Name 

func (c *CommandTool) Name() string

Name implements Tool.

func (*CommandTool) Parameters 

func (c *CommandTool) Parameters() map[string]interface{}

Parameters implements Tool.

type CommandToolConfig 

type CommandToolConfig struct {
	Name        string
	Description string
	Command     []string
	WorkingDir  string
	Env         map[string]string
	Timeout     time.Duration
}

CommandToolConfig captures options required to build a CommandTool.

type CompactionResult 

type CompactionResult struct {
	Output        string `json:"output"`
	WasCompacted  bool   `json:"was_compacted"`
	OriginalSize  int    `json:"original_size"`
	CompactedSize int    `json:"compacted_size"`
	SummaryCount  int    `json:"summary_count"`
	ChunksKept    int    `json:"chunks_kept"`
}

CompactionResult contains the compacted output and metadata

type CreateFileTool 

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

CreateFileTool is the executor with runtime dependencies

func NewCreateFileTool 

func NewCreateFileTool(filesystem fs.FileSystem, sess *session.Session) *CreateFileTool

func (*CreateFileTool) Description 

func (t *CreateFileTool) Description() string

func (*CreateFileTool) Execute 

func (t *CreateFileTool) Execute(ctx context.Context, params map[string]interface{}) *ToolResult

func (*CreateFileTool) Name 

func (t *CreateFileTool) Name() string

Legacy interface implementation for backward compatibility

func (*CreateFileTool) Parameters 

func (t *CreateFileTool) Parameters() map[string]interface{}

type CreateFileToolSpec 

type CreateFileToolSpec struct{}

CreateFileToolSpec is the static specification for the create_file tool

func (*CreateFileToolSpec) Description 

func (s *CreateFileToolSpec) Description() string

func (*CreateFileToolSpec) Name 

func (s *CreateFileToolSpec) Name() string

func (*CreateFileToolSpec) Parameters 

func (s *CreateFileToolSpec) Parameters() map[string]interface{}

type ErrorJudgeActor 

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

ErrorJudgeActor analyzes LLM errors and decides whether to retry

func NewErrorJudgeActor 

func NewErrorJudgeActor(id string, llmClient llm.Client) *ErrorJudgeActor

NewErrorJudgeActor creates a new error judge actor

func (*ErrorJudgeActor) ID 

func (a *ErrorJudgeActor) ID() string

ID implements actor.Actor interface

func (*ErrorJudgeActor) Receive 

func (a *ErrorJudgeActor) Receive(ctx context.Context, message actor.Message) error

Receive implements actor.Actor interface

func (*ErrorJudgeActor) Start 

func (a *ErrorJudgeActor) Start(ctx context.Context) error

Start implements actor.Actor interface

func (*ErrorJudgeActor) Stop 

func (a *ErrorJudgeActor) Stop(ctx context.Context) error

Stop implements actor.Actor interface

type ErrorJudgeActorClient 

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

ErrorJudgeActorClient provides a client interface to the error judge actor

func NewErrorJudgeActorClient 

func NewErrorJudgeActorClient(ref *actor.ActorRef) *ErrorJudgeActorClient

NewErrorJudgeActorClient creates a new error judge actor client

func (*ErrorJudgeActorClient) Judge 

func (c *ErrorJudgeActorClient) Judge(ctx context.Context, err error, attemptNumber int, maxAttempts int, modelID string) (ErrorJudgeDecision, error)

Judge sends an error to the judge and returns the decision

type ErrorJudgeDecision 

type ErrorJudgeDecision struct {
	ShouldRetry       bool
	SleepSeconds      int
	Reason            string
	TriggerCompaction bool // If true, the error is likely due to context size exceeded and compaction should be triggered
}

ErrorJudgeDecision represents the error judge's decision

type ErrorJudgeMessage 

type ErrorJudgeMessage struct {
	Error         error
	AttemptNumber int
	MaxAttempts   int
	ModelID       string
	RequestCtx    context.Context
	ResponseChan  chan ErrorJudgeDecision
}

ErrorJudgeMessage contains information for the error judge

func (*ErrorJudgeMessage) Type 

func (m *ErrorJudgeMessage) Type() string

Type implements actor.Message interface

type ExecDeadline 

type ExecDeadline interface {
	Pause()
	Resume()
	Stop()
	RecordActivity()
}

ExecDeadline is the interface for pausable execution deadlines.

type ExecutionMetadata 

type ExecutionMetadata struct {
	// Timing information
	StartTime  *time.Time `json:"start_time,omitempty"`
	EndTime    *time.Time `json:"end_time,omitempty"`
	DurationMs int64      `json:"duration_ms,omitempty"`

	// Command/process information (for shell, sandbox, etc.)
	Command   string `json:"command,omitempty"`
	ExitCode  int    `json:"exit_code,omitempty"`
	PID       int    `json:"pid,omitempty"`
	ProcessID string `json:"process_id,omitempty"` // For background jobs

	// Output statistics
	OutputSizeBytes int  `json:"output_size_bytes,omitempty"`
	OutputLineCount int  `json:"output_line_count,omitempty"`
	HasStderr       bool `json:"has_stderr,omitempty"`
	StderrSizeBytes int  `json:"stderr_size_bytes,omitempty"`
	StderrLineCount int  `json:"stderr_line_count,omitempty"`

	// Execution context
	WorkingDir      string `json:"working_dir,omitempty"`
	TimeoutSeconds  int    `json:"timeout_seconds,omitempty"`
	WasTimedOut     bool   `json:"was_timed_out,omitempty"`
	WasBackgrounded bool   `json:"was_backgrounded,omitempty"`

	// Adaptive timeout metrics (for go_sandbox)
	AdaptiveTimeoutOriginalSeconds int     `json:"adaptive_timeout_original_seconds,omitempty"` // Original configured timeout
	AdaptiveTimeoutExtensions      int     `json:"adaptive_timeout_extensions,omitempty"`       // Number of times timeout was extended
	AdaptiveTimeoutTotalSeconds    float64 `json:"adaptive_timeout_total_seconds,omitempty"`    // Total timeout after extensions
	AdaptiveTimeoutMaxExtensions   int     `json:"adaptive_timeout_max_extensions,omitempty"`   // Maximum allowed extensions

	// Tool-specific metadata
	ToolType string                 `json:"tool_type,omitempty"`
	Details  map[string]interface{} `json:"details,omitempty"`

	// Error classification
	ErrorType    string `json:"error_type,omitempty"`    // "timeout", "permission", "not_found", "syntax", etc.
	ErrorContext string `json:"error_context,omitempty"` // Additional context for the error
}

ExecutionMetadata captures detailed information about tool execution

type ExecutionState 

type ExecutionState string

ExecutionState represents the current state of tool execution 

const (
	StateStarting  ExecutionState = "starting"
	StateRunning   ExecutionState = "running"
	StateWaiting   ExecutionState = "waiting" // Waiting for user input
	StateCompleted ExecutionState = "completed"
	StateFailed    ExecutionState = "failed"
	StateCancelled ExecutionState = "cancelled"
	StateTimeout   ExecutionState = "timeout"
)

type FeatureFlagsProvider 

type FeatureFlagsProvider interface {
	IsToolEnabled(toolName string) bool
}

FeatureFlagsProvider provides access to feature flags

type GrepContextFilesTool 

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

GrepContextFilesTool searches content in context directories

func NewGrepContextFilesTool 

func NewGrepContextFilesTool(filesystem fs.FileSystem, cfg *config.Config, sess *session.Session) *GrepContextFilesTool

func (*GrepContextFilesTool) Description 

func (t *GrepContextFilesTool) Description() string

func (*GrepContextFilesTool) Execute 

func (t *GrepContextFilesTool) Execute(ctx context.Context, params map[string]interface{}) *ToolResult

func (*GrepContextFilesTool) Name 

func (t *GrepContextFilesTool) Name() string

func (*GrepContextFilesTool) Parameters 

func (t *GrepContextFilesTool) Parameters() map[string]interface{}

type GrepContextFilesToolSpec 

type GrepContextFilesToolSpec struct{}

GrepContextFilesToolSpec is the static specification for the grep_context_files tool

func (*GrepContextFilesToolSpec) Description 

func (s *GrepContextFilesToolSpec) Description() string

func (*GrepContextFilesToolSpec) Name 

func (s *GrepContextFilesToolSpec) Name() string

func (*GrepContextFilesToolSpec) Parameters 

func (s *GrepContextFilesToolSpec) Parameters() map[string]interface{}

type HealthCheckReport 

type HealthCheckReport struct {
	TotalExecutions int                    `json:"total_executions"`
	ActiveCount     int                    `json:"active_count"`
	StuckCount      int                    `json:"stuck_count"`
	Executions      []*ToolExecutionHealth `json:"executions"`
	StuckExecutions []*ToolExecutionHealth `json:"stuck_executions"`
	Timestamp       time.Time              `json:"timestamp"`
}

HealthCheckReport provides a detailed health report for tool executions

func (*HealthCheckReport) FormatHealthReport 

func (r *HealthCheckReport) FormatHealthReport() string

FormatHealthReport returns a human-readable health report

type Investigator 

type Investigator interface {
	Investigate(ctx context.Context, objectives []string) ([]string, error)
}

Investigator defines the interface for the codebase investigation agent.

type LegacyToolSpec 

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

LegacyToolSpec wraps a legacy Tool as a ToolSpec for migration purposes

func (*LegacyToolSpec) Description 

func (s *LegacyToolSpec) Description() string

func (*LegacyToolSpec) Name 

func (s *LegacyToolSpec) Name() string

func (*LegacyToolSpec) Parameters 

func (s *LegacyToolSpec) Parameters() map[string]interface{}

type LsTool 

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

LsTool is the executor with runtime dependencies

func NewLsTool 

func NewLsTool(workingDir string) *LsTool

func (*LsTool) Description 

func (t *LsTool) Description() string

func (*LsTool) Execute 

func (t *LsTool) Execute(ctx context.Context, params map[string]interface{}) *ToolResult

func (*LsTool) Name 

func (t *LsTool) Name() string

Legacy interface implementation for backward compatibility

func (*LsTool) Parameters 

func (t *LsTool) Parameters() map[string]interface{}

type LsToolSpec 

type LsToolSpec struct{}

LsToolSpec is the static specification for the ls tool

func (*LsToolSpec) Description 

func (s *LsToolSpec) Description() string

func (*LsToolSpec) Name 

func (s *LsToolSpec) Name() string

func (*LsToolSpec) Parameters 

func (s *LsToolSpec) Parameters() map[string]interface{}

type ManualSuggestion 

type ManualSuggestion struct {
	// SuggestedTools is a list of tool names to suggest instead
	SuggestedTools []string
	// Reason explains why the original tool shouldn't be used
	Reason string
	// MatchPattern determines how to match (exact, prefix, contains)
	MatchPattern string
}

ManualSuggestion represents a manual override for tool suggestions

type MonitorContext 

type MonitorContext struct {
	context.Context
	// contains filtered or unexported fields
}

MonitorContext wraps a context with health monitoring capabilities

func NewMonitorContext 

func NewMonitorContext(ctx context.Context, monitor *ToolHealthMonitor, toolID, toolName string) (*MonitorContext, context.CancelFunc)

NewMonitorContext creates a monitored context for tool execution

func (*MonitorContext) Complete 

func (m *MonitorContext) Complete(success bool)

Complete marks the execution as completed

func (*MonitorContext) Heartbeat 

func (m *MonitorContext) Heartbeat()

Heartbeat sends a heartbeat for this execution

func (*MonitorContext) SetCustomData 

func (m *MonitorContext) SetCustomData(data interface{})

SetCustomData sets custom data for this execution

func (*MonitorContext) UpdateState 

func (m *MonitorContext) UpdateState(state ExecutionState)

UpdateState updates the execution state

type OpenAITool 

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

OpenAITool invokes an OpenAI or OpenAI-compatible model as a tool action.

func NewOpenAITool 

func NewOpenAITool(cfg *OpenAIToolConfig) *OpenAITool

NewOpenAITool constructs an OpenAITool. Client creation errors are deferred to Execute so that the tool can report user-facing configuration issues at runtime.

func (*OpenAITool) Description 

func (o *OpenAITool) Description() string

Description implements Tool.

func (*OpenAITool) Execute 

func (o *OpenAITool) Execute(ctx context.Context, params map[string]interface{}) *ToolResult

Execute runs the configured OpenAI model and returns the response text.

func (*OpenAITool) Name 

func (o *OpenAITool) Name() string

Name implements Tool.

func (*OpenAITool) Parameters 

func (o *OpenAITool) Parameters() map[string]interface{}

Parameters implements Tool.

type OpenAIToolConfig 

type OpenAIToolConfig struct {
	Name         string
	Description  string
	Model        string
	APIKey       string
	APIKeyEnv    string
	BaseURL      string
	SystemPrompt string
	Temperature  float64
	MaxOutput    int
	ResponseJSON bool
}

OpenAIToolConfig contains the configuration required to create an OpenAITool.

type OpenAPIParameter 

type OpenAPIParameter struct {
	Name        string
	In          string
	Key         string
	Required    bool
	Schema      map[string]interface{}
	Description string
}

OpenAPIParameter describes an OpenAPI parameter exposed to the tool schema.

type OpenAPIRequestBody 

type OpenAPIRequestBody struct {
	Required    bool
	ContentType string
	Schema      map[string]interface{}
}

OpenAPIRequestBody captures body metadata for the tool execution.

type OpenAPITool 

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

OpenAPITool executes HTTP operations defined by an OpenAPI spec.

func NewOpenAPITool 

func NewOpenAPITool(cfg *OpenAPIToolConfig) *OpenAPITool

NewOpenAPITool constructs a new OpenAPITool from config.

func (*OpenAPITool) Description 

func (o *OpenAPITool) Description() string

Description implements Tool.

func (*OpenAPITool) Execute 

func (o *OpenAPITool) Execute(ctx context.Context, params map[string]interface{}) *ToolResult

Execute performs the HTTP request defined by the tool configuration.

func (*OpenAPITool) HTTPMethod 

func (o *OpenAPITool) HTTPMethod() string

HTTPMethod returns the HTTP method used by the OpenAPI tool.

func (*OpenAPITool) Name 

func (o *OpenAPITool) Name() string

Name implements Tool.

func (*OpenAPITool) Parameters 

func (o *OpenAPITool) Parameters() map[string]interface{}

Parameters implements Tool.

type OpenAPIToolConfig 

type OpenAPIToolConfig struct {
	Name           string
	Description    string
	BaseURL        string
	Method         string
	Path           string
	Parameters     []*OpenAPIParameter
	RequestBody    *OpenAPIRequestBody
	DefaultHeaders map[string]string
	DefaultQuery   map[string]string
	HTTPClient     *http.Client
	Timeout        time.Duration
}

OpenAPIToolConfig contains the information required to build an OpenAPITool.

type OutputCompactor 

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

OutputCompactor handles compaction of large sandbox outputs

func NewOutputCompactor 

func NewOutputCompactor(compactionConfig config.SandboxOutputCompactionConfig, contextWindow int) *OutputCompactor

NewOutputCompactor creates a new output compactor

func (*OutputCompactor) Compact 

func (c *OutputCompactor) Compact(ctx context.Context, output string) (*CompactionResult, error)

Compact compacts the output by writing it to a file and returning instructions for the LLM to read it piece by piece, avoiding context window bloat.

func (*OutputCompactor) SetTempDir 

func (c *OutputCompactor) SetTempDir(dir string)

SetTempDir sets the directory for writing large output files

func (*OutputCompactor) ShouldCompact 

func (c *OutputCompactor) ShouldCompact(output string) bool

ShouldCompact determines if output should be compacted based on size. Triggers when output exceeds 10% of the context window OR is >= 128 KiB.

type ParallelTool 

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

func NewParallelTool 

func NewParallelTool(registry *Registry) *ParallelTool

func (*ParallelTool) Description 

func (t *ParallelTool) Description() string

func (*ParallelTool) Execute 

func (t *ParallelTool) Execute(ctx context.Context, params map[string]interface{}) *ToolResult

func (*ParallelTool) ExecuteWithCallbacks 

func (t *ParallelTool) ExecuteWithCallbacks(ctx context.Context, params map[string]interface{}, progressCb progress.Callback, toolCallCb func(string, string, map[string]interface{}) error, toolResultCb func(string, string, string, string) error) *ToolResult

ExecuteWithCallbacks implements the callback-aware execution interface

func (*ParallelTool) Name 

func (t *ParallelTool) Name() string

func (*ParallelTool) Parameters 

func (t *ParallelTool) Parameters() map[string]interface{}

type PlanningAgent 

type PlanningAgent interface {
	// Plan generates a plan for the given objective
	Plan(ctx context.Context, objective, context string, contextFiles []string, allowQuestions bool, maxQuestions int) (*PlanningResult, error)
}

PlanningAgent defines the interface for the planning agent. This is implemented by the orchestrator to avoid import cycles.

type PlanningBoard 

type PlanningBoard struct {
	Description  string         `json:"description,omitempty"`
	PrimaryTasks []PlanningTask `json:"primary_tasks"`
}

PlanningBoard represents a hierarchical planning board

func ExtractBoardResult 

func ExtractBoardResult(result interface{}) (*PlanningBoard, error)

ExtractBoardResult is a helper to extract the board from a result

type PlanningResult 

type PlanningResult struct {
	Mode       string         `json:"mode"`
	Plan       []string       `json:"plan,omitempty"`
	Board      *PlanningBoard `json:"board,omitempty"`
	Questions  []string       `json:"questions,omitempty"`
	NeedsInput bool           `json:"needs_input"`
	Complete   bool           `json:"complete"`
}

PlanningResult represents the result of a planning operation

type PlanningTask 

type PlanningTask struct {
	ID          string         `json:"id"`
	Text        string         `json:"text"`
	Subtasks    []PlanningTask `json:"subtasks,omitempty"`
	Priority    string         `json:"priority,omitempty"`
	Status      string         `json:"status,omitempty"`
	Description string         `json:"description,omitempty"`
}

PlanningTask represents a task in the planning board

type PlanningToolExecutor 

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

PlanningToolExecutor executes the planning agent tool

func NewPlanningTool 

func NewPlanningTool(agent PlanningAgent) *PlanningToolExecutor

NewPlanningTool creates a new planning tool executor

func (*PlanningToolExecutor) Execute 

func (t *PlanningToolExecutor) Execute(ctx context.Context, params map[string]interface{}) *ToolResult

type PlanningToolSpec 

type PlanningToolSpec struct{}

PlanningToolSpec is the static specification for the planning_agent tool

func (*PlanningToolSpec) Description 

func (s *PlanningToolSpec) Description() string

func (*PlanningToolSpec) Name 

func (s *PlanningToolSpec) Name() string

func (*PlanningToolSpec) Parameters 

func (s *PlanningToolSpec) Parameters() map[string]interface{}

type ReadContextFileTool 

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

ReadContextFileTool reads files from context directories

func NewReadContextFileTool 

func NewReadContextFileTool(filesystem fs.FileSystem, cfg *config.Config, sess *session.Session) *ReadContextFileTool

func (*ReadContextFileTool) Description 

func (t *ReadContextFileTool) Description() string

func (*ReadContextFileTool) Execute 

func (t *ReadContextFileTool) Execute(ctx context.Context, params map[string]interface{}) *ToolResult

func (*ReadContextFileTool) Name 

func (t *ReadContextFileTool) Name() string

func (*ReadContextFileTool) Parameters 

func (t *ReadContextFileTool) Parameters() map[string]interface{}

type ReadContextFileToolSpec 

type ReadContextFileToolSpec struct{}

ReadContextFileToolSpec is the static specification for the read_context_file tool

func (*ReadContextFileToolSpec) Description 

func (s *ReadContextFileToolSpec) Description() string

func (*ReadContextFileToolSpec) Name 

func (s *ReadContextFileToolSpec) Name() string

func (*ReadContextFileToolSpec) Parameters 

func (s *ReadContextFileToolSpec) Parameters() map[string]interface{}

type ReadFileNumberedExecutor 

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

ReadFileNumberedExecutor handles the actual execution of the read_file tool with specific runtime dependencies.

func NewReadFileNumberedExecutor 

func NewReadFileNumberedExecutor(filesystem fs.FileSystem, sess *session.Session) *ReadFileNumberedExecutor

NewReadFileNumberedExecutor creates a new executor for the read_file tool.

func (*ReadFileNumberedExecutor) Execute 

func (e *ReadFileNumberedExecutor) Execute(ctx context.Context, params map[string]interface{}) *ToolResult

type ReadFileNumberedSpec 

type ReadFileNumberedSpec struct{}

ReadFileNumberedSpec represents the static specification of the read_file tool. This spec is used for LLM schema generation and does not require runtime dependencies.

func (*ReadFileNumberedSpec) Description 

func (s *ReadFileNumberedSpec) Description() string

func (*ReadFileNumberedSpec) Name 

func (s *ReadFileNumberedSpec) Name() string

func (*ReadFileNumberedSpec) Parameters 

func (s *ReadFileNumberedSpec) Parameters() map[string]interface{}

type ReadFileTool 

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

ReadFileTool is the executor with runtime dependencies

func NewReadFileTool 

func NewReadFileTool(filesystem fs.FileSystem, sess *session.Session) *ReadFileTool

func (*ReadFileTool) Description 

func (t *ReadFileTool) Description() string

func (*ReadFileTool) Execute 

func (t *ReadFileTool) Execute(ctx context.Context, params map[string]interface{}) *ToolResult

func (*ReadFileTool) Name 

func (t *ReadFileTool) Name() string

Legacy interface implementation for backward compatibility

func (*ReadFileTool) Parameters 

func (t *ReadFileTool) Parameters() map[string]interface{}

type ReadFileToolSpec 

type ReadFileToolSpec struct{}

ReadFileToolSpec is the static specification for the read_file tool

func (*ReadFileToolSpec) Description 

func (s *ReadFileToolSpec) Description() string

func (*ReadFileToolSpec) Name 

func (s *ReadFileToolSpec) Name() string

func (*ReadFileToolSpec) Parameters 

func (s *ReadFileToolSpec) Parameters() map[string]interface{}

type RefactoringAgent 

type RefactoringAgent interface {
	Refactor(ctx context.Context, objectives []string) ([]string, error)
}

RefactoringAgent defines the interface for the refactoring agent.

type RefactoringAgentTool 

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

RefactoringAgentTool is the executor with runtime dependencies

func NewRefactoringAgentTool 

func NewRefactoringAgentTool(agent RefactoringAgent) *RefactoringAgentTool

func (*RefactoringAgentTool) Description 

func (t *RefactoringAgentTool) Description() string

func (*RefactoringAgentTool) Execute 

func (t *RefactoringAgentTool) Execute(ctx context.Context, params map[string]interface{}) *ToolResult

func (*RefactoringAgentTool) Name 

func (t *RefactoringAgentTool) Name() string

Legacy interface implementation for backward compatibility

func (*RefactoringAgentTool) Parameters 

func (t *RefactoringAgentTool) Parameters() map[string]interface{}

type RefactoringAgentToolSpec 

type RefactoringAgentToolSpec struct{}

RefactoringAgentToolSpec is the static specification for the refactoring_agent tool

func (*RefactoringAgentToolSpec) Description 

func (s *RefactoringAgentToolSpec) Description() string

func (*RefactoringAgentToolSpec) Name 

func (s *RefactoringAgentToolSpec) Name() string

func (*RefactoringAgentToolSpec) Parameters 

func (s *RefactoringAgentToolSpec) Parameters() map[string]interface{}

type Registry 

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

Registry manages available tools

func NewRegistry 

func NewRegistry(authorizer Authorizer) *Registry

NewRegistry creates a new tool registry with an optional authorizer

func NewRegistryWithSecrets 

func NewRegistryWithSecrets(authorizer Authorizer, detector secretdetect.Detector) *Registry

NewRegistryWithSecrets creates a new tool registry with authorizer and secret detector

func (*Registry) AddManualSuggestion 

func (r *Registry) AddManualSuggestion(pattern string, suggestion *ManualSuggestion)

AddManualSuggestion adds a manual suggestion for a specific tool name pattern

func (*Registry) Execute 

func (r *Registry) Execute(ctx context.Context, call *ToolCall) *ToolResult

Execute executes a tool call

func (*Registry) ExecuteWithApproval 

func (r *Registry) ExecuteWithApproval(ctx context.Context, call *ToolCall) *ToolResult

ExecuteWithApproval executes a tool call, bypassing authorization (used when user has manually approved)

func (*Registry) ExecuteWithCallbacks 

func (r *Registry) ExecuteWithCallbacks(ctx context.Context, call *ToolCall, toolName string, progressCb progress.Callback, toolCallCb func(string, string, map[string]interface{}) error, toolResultCb func(string, string, string, string) error, skipAuthorization bool) *ToolResult

ExecuteWithCallbacks executes a tool call with optional callbacks and optional authorization skipping.

func (*Registry) FormatToolNotFoundError 

func (r *Registry) FormatToolNotFoundError(toolName string) string

FormatToolNotFoundError creates a detailed error message when a tool is not found, including suggestions for similar tool names if available.

func (*Registry) Get 

func (r *Registry) Get(name string) (Tool, bool)

Get retrieves a tool by name (legacy method - returns nil if tool uses new spec/executor pattern)

func (*Registry) GetExecutor 

func (r *Registry) GetExecutor(name string) (ToolExecutor, bool)

GetExecutor retrieves a tool executor by name

func (*Registry) List 

func (r *Registry) List() []Tool

List returns all registered tools (legacy method - only returns tools using old interface)

func (*Registry) ListSpecs 

func (r *Registry) ListSpecs() []ToolSpec

ListSpecs returns all registered tool specs

func (*Registry) Register 

func (r *Registry) Register(tool Tool)

Register adds a tool to the registry (legacy method for backward compatibility)

func (*Registry) RegisterSpec 

func (r *Registry) RegisterSpec(spec ToolSpec, factory ToolFactory)

RegisterSpec adds a tool spec with a factory to the registry

func (*Registry) RemoveByPrefix 

func (r *Registry) RemoveByPrefix(prefix string)

RemoveByPrefix unregisters tools whose names share the provided prefix.

func (*Registry) SetSecretDetector 

func (r *Registry) SetSecretDetector(detector secretdetect.Detector)

SetSecretDetector sets the secret detector for the registry

func (*Registry) ToJSONSchema 

func (r *Registry) ToJSONSchema() []map[string]interface{}

ToJSONSchema converts tools to JSON schema format for LLM

type ReplaceFileTool 

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

ReplaceFileTool is the executor with runtime dependencies

func NewReplaceFileTool 

func NewReplaceFileTool(filesystem fs.FileSystem, sess *session.Session) *ReplaceFileTool

func (*ReplaceFileTool) Description 

func (t *ReplaceFileTool) Description() string

func (*ReplaceFileTool) Execute 

func (t *ReplaceFileTool) Execute(ctx context.Context, params map[string]interface{}) *ToolResult

func (*ReplaceFileTool) Name 

func (t *ReplaceFileTool) Name() string

Legacy interface implementation for backward compatibility

func (*ReplaceFileTool) Parameters 

func (t *ReplaceFileTool) Parameters() map[string]interface{}

func (*ReplaceFileTool) PreCheck 

func (t *ReplaceFileTool) PreCheck(ctx context.Context, params map[string]interface{}) *ToolResult

PreCheck validates that the file has been read before allowing replacements. This runs before the authorization actor to avoid unnecessary user prompts.

type ReplaceFileToolSpec 

type ReplaceFileToolSpec struct{}

ReplaceFileToolSpec is the static specification for the replace_file tool

func (*ReplaceFileToolSpec) Description 

func (s *ReplaceFileToolSpec) Description() string

func (*ReplaceFileToolSpec) Name 

func (s *ReplaceFileToolSpec) Name() string

func (*ReplaceFileToolSpec) Parameters 

func (s *ReplaceFileToolSpec) Parameters() map[string]interface{}

type RequestDirectoryAccessTool 

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

RequestDirectoryAccessTool is the executor with runtime dependencies

func NewRequestDirectoryAccessTool 

func NewRequestDirectoryAccessTool(sb *sandbox.Manager) *RequestDirectoryAccessTool

NewRequestDirectoryAccessTool creates a new request_directory_access tool

func (*RequestDirectoryAccessTool) Description 

func (t *RequestDirectoryAccessTool) Description() string

func (*RequestDirectoryAccessTool) Execute 

func (t *RequestDirectoryAccessTool) Execute(ctx context.Context, params map[string]interface{}) *ToolResult

func (*RequestDirectoryAccessTool) Name 

func (t *RequestDirectoryAccessTool) Name() string

Legacy interface implementation

func (*RequestDirectoryAccessTool) Parameters 

func (t *RequestDirectoryAccessTool) Parameters() map[string]interface{}

type RequestDirectoryAccessToolSpec 

type RequestDirectoryAccessToolSpec struct{}

RequestDirectoryAccessToolSpec is the static specification for the request_directory_access tool

func (*RequestDirectoryAccessToolSpec) Description 

func (s *RequestDirectoryAccessToolSpec) Description() string

func (*RequestDirectoryAccessToolSpec) Name 

func (s *RequestDirectoryAccessToolSpec) Name() string

func (*RequestDirectoryAccessToolSpec) Parameters 

func (s *RequestDirectoryAccessToolSpec) Parameters() map[string]interface{}

type SandboxBuilder 

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

SandboxBuilder provides a fluent interface for building and executing sandboxed Go code.

The builder pattern offers a type-safe, intuitive API for configuring and executing Go code in an isolated WebAssembly environment with full control over:

  • Code execution and timeouts
  • External library dependencies
  • Network access authorization
  • Filesystem access permissions

Key Features:

  • Automatic TinyGo compilation (WASI P2 target)
  • LLM-based domain authorization for network access
  • Controlled filesystem access through session tracking
  • Method chaining for clean, readable code
  • Validation and error accumulation
  • Clone support for batch operations

Basic Usage: 

result, err := tools.NewSandboxBuilder().
    SetCode("package main\nfunc main() { println(\"Hello!\") }").
    SetTimeout(30).
    Execute(context.Background())

With Authorization: 

result, err := tools.NewSandboxBuilder().
    SetCode(networkCode).
    SetAuthorization(authActor).
    AllowDomain("api.github.com").
    Execute(ctx)

Batch Execution: 

base := tools.NewSandboxBuilder().SetTimeout(30)
for _, code := range testCases {
    result, _ := base.Clone().SetCode(code).Execute(ctx)
}

Thread Safety: 

SandboxBuilder instances are NOT thread-safe. Each goroutine should use
its own builder instance or clone an existing one.

Error Handling: 

The builder accumulates errors during configuration. Once an error occurs,
subsequent method calls are no-ops. Check the error in Execute() or Validate().

func NewSandboxBuilder 

func NewSandboxBuilder() *SandboxBuilder

NewSandboxBuilder creates a new sandbox builder with sensible defaults.

Default Configuration:

  • Timeout: 30 seconds
  • Working Directory: "." (current directory)
  • Temp Directory: "/tmp"
  • Libraries: empty
  • No filesystem/session (limited file access)
  • No authorization (no network access)
  • No pre-authorized domains

The builder uses a fluent interface where methods return *SandboxBuilder to enable method chaining: 

builder := tools.NewSandboxBuilder().
    SetCode(code).
    SetTimeout(60).
    AddLibrary("github.com/google/uuid@latest")

Example - Simple execution: 

result, err := tools.NewSandboxBuilder().
    SetCode(`package main
import "fmt"
func main() {
    fmt.Println("Hello, World!")
}`).
    Execute(context.Background())

Example - With timeout and validation: 

builder := tools.NewSandboxBuilder().
    SetCode(code).
    SetTimeout(120)

if err := builder.Validate(); err != nil {
    return fmt.Errorf("invalid config: %w", err)
}

result, err := builder.Execute(ctx)

Example - Reusable configuration: 

base := tools.NewSandboxBuilder().
    SetTimeout(30).
    SetWorkingDir("/project")

// Execute multiple code snippets with same config
for _, code := range codes {
    result, _ := base.Clone().SetCode(code).Execute(ctx)
}

Returns: 

A new SandboxBuilder instance ready for configuration

func (*SandboxBuilder) AddLibraries 

func (b *SandboxBuilder) AddLibraries(libraries ...string) *SandboxBuilder

AddLibraries adds multiple Go module dependencies at once.

This is a convenience method for adding multiple libraries in a single call. Empty strings in the list are automatically filtered out.

Example - Multiple libraries: 

builder.AddLibraries(
    "github.com/google/uuid@v1.3.0",
    "golang.org/x/crypto@latest",
    "github.com/stretchr/testify@v1.8.4",
)

Example - Conditional libraries: 

libs := []string{"github.com/google/uuid@v1.3.0"}
if needsCrypto {
    libs = append(libs, "golang.org/x/crypto@latest")
}
builder.AddLibraries(libs...)

Returns: 

The builder instance for method chaining

func (*SandboxBuilder) AddLibrary 

func (b *SandboxBuilder) AddLibrary(library string) *SandboxBuilder

AddLibrary adds a single Go module dependency to the sandbox.

Format: "module/path@version" Examples:

  • "github.com/google/uuid@v1.3.0"
  • "golang.org/x/crypto@latest"
  • "github.com/gin-gonic/gin@v1.9.1"

IMPORTANT - TinyGo Compatibility: 

TinyGo has limited support for external libraries. Most standard library
packages work, but many third-party libraries may not compile.
Test compatibility before deploying to production.

Supported Libraries:

  • Most stdlib packages (fmt, strings, time, etc.)
  • Simple pure-Go libraries without CGO
  • Libraries that don't use unsupported reflection

Example - Single library: 

builder.AddLibrary("github.com/google/uuid@v1.3.0")

Example - Multiple libraries: 

builder.
    AddLibrary("github.com/google/uuid@v1.3.0").
    AddLibrary("golang.org/x/crypto@latest")

Alternative - Use AddLibraries() for multiple: 

builder.AddLibraries(
    "github.com/google/uuid@v1.3.0",
    "golang.org/x/crypto@latest",
)

Returns: 

The builder instance for method chaining

func (*SandboxBuilder) AllowAllDomains 

func (b *SandboxBuilder) AllowAllDomains() *SandboxBuilder

AllowAllDomains allows unrestricted network access to ALL domains.

⚠️ SECURITY WARNING ⚠️

This method bypasses ALL authorization checks including:

  • LLM-based domain safety analysis
  • User approval prompts
  • Domain allowlists

USE ONLY FOR:

  • Testing in isolated environments
  • Fully trusted code (code you wrote yourself)
  • Development/debugging purposes

NEVER USE FOR:

  • LLM-generated code
  • User-submitted code
  • Production environments
  • Code from untrusted sources

Risks:

  • Code can access any website
  • Data exfiltration possible
  • Malicious API calls
  • DDoS participation
  • Privacy violations

Safer Alternative: 

Use AllowDomains() to explicitly list trusted domains:

builder.AllowDomains("github.com", "googleapis.com")  // Safe

Example - Testing only: 

// Only use in test environments!
builder.
    SetCode(trustedTestCode).
    SetAuthorization(authActor).
    AllowAllDomains()  // ⚠️  Dangerous!

Returns: 

The builder instance for method chaining

func (*SandboxBuilder) AllowDomain 

func (b *SandboxBuilder) AllowDomain(domain string) *SandboxBuilder

AllowDomain pre-authorizes access to a specific domain without LLM checks.

Pre-authorized domains bypass the LLM safety analysis and are allowed immediately. This is useful for:

  • Known safe domains (github.com, googleapis.com, npmjs.org)
  • Internal company APIs
  • Frequently accessed APIs
  • Performance optimization (skip LLM call)

REQUIRES: SetAuthorization() must be called for network access

Domain Format:

  • Use base domain without protocol: "github.com" not "https://github.com"
  • Subdomains are matched exactly: "api.github.com" != "github.com"
  • Wildcards not supported (use multiple calls for subdomains)

Example - Single domain: 

builder.
    SetAuthorization(authActor).
    AllowDomain("github.com")

Example - Multiple domains (method chaining): 

builder.
    SetAuthorization(authActor).
    AllowDomain("github.com").
    AllowDomain("googleapis.com").
    AllowDomain("npmjs.org")

Example - API endpoints: 

builder.
    SetAuthorization(authActor).
    AllowDomain("api.github.com").
    AllowDomain("api.openai.com")

Alternative - Use AllowDomains() for multiple: 

builder.AllowDomains("github.com", "googleapis.com", "npmjs.org")

Security Note: 

Only add domains you trust. Pre-authorized domains bypass all safety checks.

Returns: 

The builder instance for method chaining

func (*SandboxBuilder) AllowDomains 

func (b *SandboxBuilder) AllowDomains(domains ...string) *SandboxBuilder

AllowDomains pre-authorizes access to multiple domains at once.

This is a convenience method for adding multiple trusted domains. Empty strings in the list are automatically filtered out.

Example - Common safe domains: 

builder.
    SetAuthorization(authActor).
    AllowDomains(
        "github.com",
        "googleapis.com",
        "npmjs.org",
        "pkg.go.dev",
    )

Example - API endpoints: 

builder.AllowDomains(
    "api.github.com",
    "api.openai.com",
    "api.anthropic.com",
)

Returns: 

The builder instance for method chaining

func (*SandboxBuilder) Build 

func (b *SandboxBuilder) Build() (*SandboxTool, error)

Build creates a SandboxTool from the builder configuration Returns an error if validation fails

func (*SandboxBuilder) Clone 

func (b *SandboxBuilder) Clone() *SandboxBuilder

Clone creates a copy of the builder with the same configuration Useful for creating variations of a base configuration

func (*SandboxBuilder) Execute 

func (b *SandboxBuilder) Execute(ctx context.Context) (interface{}, error)

Execute builds and executes the sandboxed Go code Returns the execution result or an error

func (*SandboxBuilder) ExecuteWithTimeout 

func (b *SandboxBuilder) ExecuteWithTimeout() (interface{}, error)

ExecuteWithTimeout is a convenience method that creates a context with timeout and executes

func (*SandboxBuilder) MustExecute 

func (b *SandboxBuilder) MustExecute(ctx context.Context) interface{}

MustExecute executes the code and panics if there's an error Useful for testing or scripts where errors should be fatal

func (*SandboxBuilder) Reset 

func (b *SandboxBuilder) Reset() *SandboxBuilder

Reset clears all builder state for reuse

func (*SandboxBuilder) SetAuthorization 

func (b *SandboxBuilder) SetAuthorization(auth Authorizer) *SandboxBuilder

SetAuthorization sets the authorization actor for network access control.

The authorizer enables network access in sandboxed code with LLM-based safety checks. Without an authorizer, all network operations will fail.

How It Works:

  1. Code attempts HTTP request (e.g., http.Get("https://example.com"))
  2. Sandbox intercepts the request before it's sent
  3. Authorizer analyzes the domain using LLM (safety check)
  4. If approved: Request proceeds normally
  5. If denied: Request fails with authorization error

Safety Checks:

  • Analyzes domain reputation and purpose
  • Checks for suspicious patterns
  • Requires user approval for unknown domains
  • Auto-approves common safe domains (github.com, googleapis.com, etc.)

Pre-Authorization: 

Use AllowDomain() or AllowDomains() to bypass LLM checks for trusted domains:

builder.
    SetAuthorization(authActor).
    AllowDomain("api.github.com")  // Bypass LLM check

Example - Basic network access: 

code := `package main
import (
    "fmt"
    "net/http"
)
func main() {
    resp, err := http.Get("https://api.github.com")
    if err != nil {
        fmt.Println("Error:", err)
        return
    }
    fmt.Println("Status:", resp.Status)
}`

builder.
    SetCode(code).
    SetAuthorization(authActor).  // Required for network
    Execute(ctx)

Example - With pre-authorized domains: 

builder.
    SetCode(code).
    SetAuthorization(authActor).
    AllowDomains("github.com", "googleapis.com"). // Skip LLM checks
    Execute(ctx)

Security Warning: 

Without an authorizer, network code will fail at runtime.
With AllowAllDomains(), ALL network access is permitted (dangerous).

Returns: 

The builder instance for method chaining

func (*SandboxBuilder) SetCode 

func (b *SandboxBuilder) SetCode(code string) *SandboxBuilder

SetCode sets the Go code to execute in the sandbox.

The code must be a complete Go program including:

  • package main declaration
  • func main() entry point

The code will be compiled to WebAssembly using TinyGo and executed in an isolated wazero runtime with controlled access to filesystem and network.

Validation:

  • Code cannot be empty (will set builder error)
  • Code should be valid Go syntax (checked during compilation)

Example - Simple code: 

builder.SetCode(`package main
import "fmt"
func main() {
    fmt.Println("Hello!")
}`)

Example - Multi-line with variables: 

code := `package main
import (
    "fmt"
    "time"
)
func main() {
    fmt.Println("Current time:", time.Now())
}`
builder.SetCode(code)

Network Access: 

Network code requires SetAuthorization() for LLM-based safety checks:

code := `package main
import (
    "fmt"
    "net/http"
)
func main() {
    resp, _ := http.Get("https://api.github.com")
    fmt.Println("Status:", resp.Status)
}`
builder.SetCode(code).SetAuthorization(authActor)

Returns: 

The builder instance for method chaining

func (*SandboxBuilder) SetDescription 

func (b *SandboxBuilder) SetDescription(desc string) *SandboxBuilder

SetDescription sets a human-readable description of what the sandbox code does.

The description is optional and will be displayed in the TUI and Web UI to explain what the LLM is doing. This helps users understand the purpose of sandbox executions without needing to read the code.

Example: 

builder.
    SetCode("package main\nfunc main() { fmt.Println(\"Hello\") }").
    SetDescription("Print a greeting message")

Returns: 

The builder instance for method chaining

func (*SandboxBuilder) SetFilesystem 

func (b *SandboxBuilder) SetFilesystem(fs fs.FileSystem) *SandboxBuilder

SetFilesystem sets the filesystem for controlled file access Only files read through this filesystem will be accessible in the sandbox

func (*SandboxBuilder) SetSession 

func (b *SandboxBuilder) SetSession(sess *session.Session) *SandboxBuilder

SetSession sets the session for tracking files read/modified

func (*SandboxBuilder) SetShellExecutor 

func (b *SandboxBuilder) SetShellExecutor(executor ShellExecutor) *SandboxBuilder

SetShellExecutor sets the shell executor for command execution in sandbox

func (*SandboxBuilder) SetTempDir 

func (b *SandboxBuilder) SetTempDir(dir string) *SandboxBuilder

SetTempDir sets the temporary directory for compilation

func (*SandboxBuilder) SetTimeout 

func (b *SandboxBuilder) SetTimeout(seconds int) *SandboxBuilder

SetTimeout sets the execution timeout in seconds.

The timeout applies to the total execution time including:

  • Code compilation (TinyGo build)
  • WASM module execution

Constraints:

  • Minimum: 1 second
  • Maximum: 600 seconds (10 minutes)
  • Default: 30 seconds (if not set)

Timeout Behavior:

  • If execution exceeds timeout, WASM runtime is terminated
  • Result will have timeout=true and exit_code=-1
  • Partial output may still be available in stdout

Recommended Values:

  • Simple scripts: 5-10 seconds
  • I/O operations: 30-60 seconds
  • Complex computations: 60-600 seconds

Example - Quick timeout for tests: 

builder.SetTimeout(5) // 5 seconds

Example - Long timeout for complex operations: 

builder.SetTimeout(600) // 6 minutes (maximum)

Example - Handling timeout results: 

builder.SetTimeout(10)
result, _ := builder.Execute(ctx)
resultMap := result.(map[string]interface{})
if resultMap["timeout"].(bool) {
    log.Println("Execution timed out!")
}

Returns: 

The builder instance for method chaining

func (*SandboxBuilder) SetWorkingDir 

func (b *SandboxBuilder) SetWorkingDir(dir string) *SandboxBuilder

SetWorkingDir sets the working directory for the sandbox

func (*SandboxBuilder) Validate 

func (b *SandboxBuilder) Validate() error

Validate checks if the builder configuration is valid without executing

type SandboxProcessInfo 

type SandboxProcessInfo struct {
	PID       int       `json:"pid,omitempty"`
	StartTime time.Time `json:"start_time"`
	IsRunning bool      `json:"is_running"`
	Command   string    `json:"command"`
}

SandboxProcessInfo contains information about a running sandbox process

type SandboxTool 

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

SandboxTool executes Go code in a sandboxed WebAssembly environment

func NewSandboxTool 

func NewSandboxTool(workingDir, tempDir string) *SandboxTool

func NewSandboxToolWithFS 

func NewSandboxToolWithFS(workingDir, tempDir string, filesystem fs.FileSystem, sess *session.Session, shellExecutor ShellExecutor) *SandboxTool

NewSandboxToolWithFS creates a sandbox with filesystem and session support

func (*SandboxTool) Description 

func (t *SandboxTool) Description() string

func (*SandboxTool) Execute 

func (t *SandboxTool) Execute(ctx context.Context, params map[string]interface{}) *ToolResult

func (*SandboxTool) GetTinyGoManager 

func (t *SandboxTool) GetTinyGoManager() *TinyGoManager

GetTinyGoManager returns the TinyGo manager instance (can be nil)

func (*SandboxTool) ListFilesInDir 

func (t *SandboxTool) ListFilesInDir(dir string) ([]string, error)

ListFilesInDir returns the entries inside the provided directory. Paths are returned relative to the supplied dir (or working directory if dir is empty).

func (*SandboxTool) Mkdir 

func (t *SandboxTool) Mkdir(dir string, recursive bool) error

Mkdir creates a directory, optionally recursively.

func (*SandboxTool) Move 

func (t *SandboxTool) Move(src, dst string) error

Move renames or moves a file or directory.

func (*SandboxTool) Name 

func (t *SandboxTool) Name() string

func (*SandboxTool) Parameters 

func (t *SandboxTool) Parameters() map[string]interface{}

func (*SandboxTool) SetAuthorizationPersistence 

func (t *SandboxTool) SetAuthorizationPersistence(cfg *config.Config, configPath string)

SetAuthorizationPersistence sets the config used to persist authorized commands/domains

func (*SandboxTool) SetAuthorizer 

func (t *SandboxTool) SetAuthorizer(auth Authorizer)

SetAuthorizer sets the authorizer for domain authorization at runtime

func (*SandboxTool) SetCompactionConfig 

func (t *SandboxTool) SetCompactionConfig(compactionConfig config.SandboxOutputCompactionConfig)

SetCompactionConfig sets the output compaction configuration

func (*SandboxTool) SetCompactionOutputDir 

func (t *SandboxTool) SetCompactionOutputDir(dir string)

SetCompactionOutputDir sets the directory where large sandbox output files are stored

func (*SandboxTool) SetContextWindow 

func (t *SandboxTool) SetContextWindow(contextWindow int)

SetContextWindow sets the model's context window in tokens for compaction decisions

func (*SandboxTool) SetFeatureFlags 

func (t *SandboxTool) SetFeatureFlags(featureFlags FeatureFlagsProvider)

SetFeatureFlags sets the feature flags provider

func (*SandboxTool) SetProgressCallback 

func (t *SandboxTool) SetProgressCallback(cb progress.Callback)

SetProgressCallback sets a callback for streaming status/output messages.

func (*SandboxTool) SetSecretDetector 

func (t *SandboxTool) SetSecretDetector(detector secretdetect.Detector)

SetSecretDetector sets the secret detector for scanning web requests

func (*SandboxTool) SetShellExecutor 

func (t *SandboxTool) SetShellExecutor(executor ShellExecutor)

SetShellExecutor sets the shell executor for command execution

func (*SandboxTool) SetSummarizeClient 

func (t *SandboxTool) SetSummarizeClient(client llm.Client)

SetSummarizeClient sets the summarization LLM client

func (*SandboxTool) SetUserInteractionClient 

func (t *SandboxTool) SetUserInteractionClient(clientFunc func() *actor.UserInteractionClient, tabIDFunc func() int)

SetUserInteractionClient sets a lazy accessor for the user interaction client and tab ID function for prompting the user during WASM execution (e.g., for sandbox command/domain authorization). A function is used instead of a direct reference because the client may be set on the orchestrator after the sandbox tool is constructed.

type SandboxToolWithActor 

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

SandboxToolWithActor is the sandbox tool that uses ShellActor for shell operations

func NewSandboxToolWithActor 

func NewSandboxToolWithActor(sess *session.Session, shellActor actor.ShellActor, authorizer Authorizer) *SandboxToolWithActor

func (*SandboxToolWithActor) Description 

func (t *SandboxToolWithActor) Description() string

func (*SandboxToolWithActor) Execute 

func (t *SandboxToolWithActor) Execute(ctx context.Context, params map[string]interface{}) *ToolResult

func (*SandboxToolWithActor) GetShellHostFunction 

func (t *SandboxToolWithActor) GetShellHostFunction() func(context.Context, api.Module, uint32, uint32, uint32, uint32, uint32, uint32, uint32, uint32) int32

GetShellHostFunction returns a function that can be used as the shell host function in WASM

func (*SandboxToolWithActor) Name 

func (t *SandboxToolWithActor) Name() string

func (*SandboxToolWithActor) Parameters 

func (t *SandboxToolWithActor) Parameters() map[string]interface{}

type ScanSecretsToolExecutor 

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

ScanSecretsToolExecutor implements the execution logic

func (*ScanSecretsToolExecutor) Execute 

func (e *ScanSecretsToolExecutor) Execute(ctx context.Context, params map[string]interface{}) *ToolResult

type ScanSecretsToolSpec 

type ScanSecretsToolSpec struct{}

ScanSecretsToolSpec defines the scan_secrets tool

func (*ScanSecretsToolSpec) Description 

func (s *ScanSecretsToolSpec) Description() string

func (*ScanSecretsToolSpec) Name 

func (s *ScanSecretsToolSpec) Name() string

func (*ScanSecretsToolSpec) Parameters 

func (s *ScanSecretsToolSpec) Parameters() map[string]interface{}

type SearchContextFilesTool 

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

SearchContextFilesTool searches files in context directories

func NewSearchContextFilesTool 

func NewSearchContextFilesTool(filesystem fs.FileSystem, cfg *config.Config, sess *session.Session) *SearchContextFilesTool

func (*SearchContextFilesTool) Description 

func (t *SearchContextFilesTool) Description() string

func (*SearchContextFilesTool) Execute 

func (t *SearchContextFilesTool) Execute(ctx context.Context, params map[string]interface{}) *ToolResult

func (*SearchContextFilesTool) Name 

func (t *SearchContextFilesTool) Name() string

func (*SearchContextFilesTool) Parameters 

func (t *SearchContextFilesTool) Parameters() map[string]interface{}

type SearchContextFilesToolSpec 

type SearchContextFilesToolSpec struct{}

SearchContextFilesToolSpec is the static specification for the search_context_files tool

func (*SearchContextFilesToolSpec) Description 

func (s *SearchContextFilesToolSpec) Description() string

func (*SearchContextFilesToolSpec) Name 

func (s *SearchContextFilesToolSpec) Name() string

func (*SearchContextFilesToolSpec) Parameters 

func (s *SearchContextFilesToolSpec) Parameters() map[string]interface{}

type SearchFileContentTool 

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

SearchFileContentTool is the executor with runtime dependencies

func NewSearchFileContentTool 

func NewSearchFileContentTool(filesystem fs.FileSystem) *SearchFileContentTool

func (*SearchFileContentTool) Description 

func (t *SearchFileContentTool) Description() string

func (*SearchFileContentTool) Execute 

func (t *SearchFileContentTool) Execute(ctx context.Context, params map[string]interface{}) *ToolResult

func (*SearchFileContentTool) Name 

func (t *SearchFileContentTool) Name() string

Legacy interface implementation for backward compatibility

func (*SearchFileContentTool) Parameters 

func (t *SearchFileContentTool) Parameters() map[string]interface{}

type SearchFileContentToolSpec 

type SearchFileContentToolSpec struct{}

SearchFileContentToolSpec is the static specification for the search_file_content tool

func (*SearchFileContentToolSpec) Description 

func (s *SearchFileContentToolSpec) Description() string

func (*SearchFileContentToolSpec) Name 

func (s *SearchFileContentToolSpec) Name() string

func (*SearchFileContentToolSpec) Parameters 

func (s *SearchFileContentToolSpec) Parameters() map[string]interface{}

type SearchFilesTool 

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

SearchFilesTool is the executor with runtime dependencies

func NewSearchFilesTool 

func NewSearchFilesTool(filesystem fs.FileSystem) *SearchFilesTool

func (*SearchFilesTool) Description 

func (t *SearchFilesTool) Description() string

func (*SearchFilesTool) Execute 

func (t *SearchFilesTool) Execute(ctx context.Context, params map[string]interface{}) *ToolResult

func (*SearchFilesTool) Name 

func (t *SearchFilesTool) Name() string

Legacy interface implementation for backward compatibility

func (*SearchFilesTool) Parameters 

func (t *SearchFilesTool) Parameters() map[string]interface{}

type SearchFilesToolSpec 

type SearchFilesToolSpec struct{}

SearchFilesToolSpec is the static specification for the search_files tool

func (*SearchFilesToolSpec) Description 

func (s *SearchFilesToolSpec) Description() string

func (*SearchFilesToolSpec) Name 

func (s *SearchFilesToolSpec) Name() string

func (*SearchFilesToolSpec) Parameters 

func (s *SearchFilesToolSpec) Parameters() map[string]interface{}

type SecretAwareAuthorizer 

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

SecretAwareAuthorizer wraps an Authorizer to add secret-based authorization capabilities.

func NewSecretAwareAuthorizer 

func NewSecretAwareAuthorizer(authorizer Authorizer, actor *AuthorizationActor) *SecretAwareAuthorizer

NewSecretAwareAuthorizer creates a new SecretAwareAuthorizer that wraps an existing authorizer.

func (*SecretAwareAuthorizer) Authorize 

func (s *SecretAwareAuthorizer) Authorize(ctx context.Context, toolName string, params map[string]interface{}) (*AuthorizationDecision, error)

Authorize implements the Authorizer interface for normal authorization without secrets.

func (*SecretAwareAuthorizer) AuthorizeWithSecrets 

func (s *SecretAwareAuthorizer) AuthorizeWithSecrets(ctx context.Context, toolName string, params map[string]interface{}, secrets []secretdetect.SecretMatch) (*AuthorizationDecision, error)

AuthorizeWithSecrets handles authorization when secrets are detected.

type ShellExecutor 

type ShellExecutor interface {
	// ExecuteCommand executes a shell command and returns stdout, stderr, and exit code
	ExecuteCommand(ctx context.Context, args []string, workingDir string, timeout time.Duration, stdin string) (stdout string, stderr string, exitCode int, err error)
}

ShellExecutor is an interface for executing shell commands This allows the sandbox to use either direct execution or actor-based execution

type ShellTool 

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

ShellTool is the executor with runtime dependencies

func NewShellTool 

func NewShellTool(sess *session.Session, workingDir string) *ShellTool

func (*ShellTool) Description 

func (t *ShellTool) Description() string

func (*ShellTool) Execute 

func (t *ShellTool) Execute(ctx context.Context, params map[string]interface{}) *ToolResult

func (*ShellTool) Name 

func (t *ShellTool) Name() string

Legacy interface implementation for backward compatibility

func (*ShellTool) Parameters 

func (t *ShellTool) Parameters() map[string]interface{}

type ShellToolSpec 

type ShellToolSpec struct{}

ShellToolSpec is the static specification for the shell tool

func (*ShellToolSpec) Description 

func (s *ShellToolSpec) Description() string

func (*ShellToolSpec) Name 

func (s *ShellToolSpec) Name() string

func (*ShellToolSpec) Parameters 

func (s *ShellToolSpec) Parameters() map[string]interface{}

type ShellToolWithActor 

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

ShellToolWithActor is the shell tool implementation that uses ShellActor

func NewShellToolWithActor 

func NewShellToolWithActor(sess *session.Session, workingDir string, shellActor actor.ShellActor) *ShellToolWithActor

NewShellToolWithActor creates a new shell tool that uses ShellActor

func (*ShellToolWithActor) Description 

func (t *ShellToolWithActor) Description() string

func (*ShellToolWithActor) Execute 

func (t *ShellToolWithActor) Execute(ctx context.Context, params map[string]interface{}) *ToolResult

func (*ShellToolWithActor) Name 

func (t *ShellToolWithActor) Name() string

Legacy interface implementation for backward compatibility

func (*ShellToolWithActor) Parameters 

func (t *ShellToolWithActor) Parameters() map[string]interface{}

type StatusProgramTool 

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

StatusProgramTool is the executor with runtime dependencies

func NewStatusProgramTool 

func NewStatusProgramTool(sess *session.Session) *StatusProgramTool

func (*StatusProgramTool) Description 

func (t *StatusProgramTool) Description() string

func (*StatusProgramTool) Execute 

func (t *StatusProgramTool) Execute(ctx context.Context, params map[string]interface{}) *ToolResult

func (*StatusProgramTool) Name 

func (t *StatusProgramTool) Name() string

Legacy interface implementation for backward compatibility

func (*StatusProgramTool) Parameters 

func (t *StatusProgramTool) Parameters() map[string]interface{}

type StatusProgramToolSpec 

type StatusProgramToolSpec struct{}

StatusProgramToolSpec is the static specification for the status_program tool

func (*StatusProgramToolSpec) Description 

func (s *StatusProgramToolSpec) Description() string

func (*StatusProgramToolSpec) Name 

func (s *StatusProgramToolSpec) Name() string

func (*StatusProgramToolSpec) Parameters 

func (s *StatusProgramToolSpec) Parameters() map[string]interface{}

type StatusProgramToolWithActor 

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

StatusProgramToolWithActor is the status program tool that uses ShellActor

func NewStatusProgramToolWithActor 

func NewStatusProgramToolWithActor(sess *session.Session, shellActor actor.ShellActor) *StatusProgramToolWithActor

func (*StatusProgramToolWithActor) Description 

func (t *StatusProgramToolWithActor) Description() string

func (*StatusProgramToolWithActor) Execute 

func (t *StatusProgramToolWithActor) Execute(ctx context.Context, params map[string]interface{}) *ToolResult

func (*StatusProgramToolWithActor) Name 

func (t *StatusProgramToolWithActor) Name() string

func (*StatusProgramToolWithActor) Parameters 

func (t *StatusProgramToolWithActor) Parameters() map[string]interface{}

type StopProgramTool 

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

StopProgramTool is the executor with runtime dependencies

func NewStopProgramTool 

func NewStopProgramTool(sess *session.Session) *StopProgramTool

func (*StopProgramTool) Description 

func (t *StopProgramTool) Description() string

func (*StopProgramTool) Execute 

func (t *StopProgramTool) Execute(ctx context.Context, params map[string]interface{}) *ToolResult

func (*StopProgramTool) Name 

func (t *StopProgramTool) Name() string

Legacy interface implementation for backward compatibility

func (*StopProgramTool) Parameters 

func (t *StopProgramTool) Parameters() map[string]interface{}

type StopProgramToolSpec 

type StopProgramToolSpec struct{}

StopProgramToolSpec is the static specification for the stop_program tool

func (*StopProgramToolSpec) Description 

func (s *StopProgramToolSpec) Description() string

func (*StopProgramToolSpec) Name 

func (s *StopProgramToolSpec) Name() string

func (*StopProgramToolSpec) Parameters 

func (s *StopProgramToolSpec) Parameters() map[string]interface{}

type StopProgramToolWithActor 

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

StopProgramToolWithActor is the stop program tool that uses ShellActor

func NewStopProgramToolWithActor 

func NewStopProgramToolWithActor(shellActor actor.ShellActor) *StopProgramToolWithActor

func (*StopProgramToolWithActor) Description 

func (t *StopProgramToolWithActor) Description() string

func (*StopProgramToolWithActor) Execute 

func (t *StopProgramToolWithActor) Execute(ctx context.Context, params map[string]interface{}) *ToolResult

func (*StopProgramToolWithActor) Name 

func (t *StopProgramToolWithActor) Name() string

func (*StopProgramToolWithActor) Parameters 

func (t *StopProgramToolWithActor) Parameters() map[string]interface{}

type SummarizeFileTool 

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

SummarizeFileTool is the executor with runtime dependencies

func NewSummarizeFileTool 

func NewSummarizeFileTool(filesystem fs.FileSystem, sess *session.Session, summarizeClient llm.Client) *SummarizeFileTool

func (*SummarizeFileTool) Description 

func (t *SummarizeFileTool) Description() string

func (*SummarizeFileTool) Execute 

func (t *SummarizeFileTool) Execute(ctx context.Context, params map[string]interface{}) *ToolResult

func (*SummarizeFileTool) Name 

func (t *SummarizeFileTool) Name() string

Legacy interface implementation for backward compatibility

func (*SummarizeFileTool) Parameters 

func (t *SummarizeFileTool) Parameters() map[string]interface{}

type SummarizeFileToolSpec 

type SummarizeFileToolSpec struct{}

SummarizeFileToolSpec is the static specification for the read_file_summarized tool

func (*SummarizeFileToolSpec) Description 

func (s *SummarizeFileToolSpec) Description() string

func (*SummarizeFileToolSpec) Name 

func (s *SummarizeFileToolSpec) Name() string

func (*SummarizeFileToolSpec) Parameters 

func (s *SummarizeFileToolSpec) Parameters() map[string]interface{}

type TaskSummaryTool 

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

TaskSummaryTool allows the agent to explicitly report task completion summary

func NewTaskSummaryTool 

func NewTaskSummaryTool(sess *session.Session) *TaskSummaryTool

NewTaskSummaryTool creates a new task summary tool

func (*TaskSummaryTool) Description 

func (t *TaskSummaryTool) Description() string

Description returns the tool description

func (*TaskSummaryTool) Execute 

func (t *TaskSummaryTool) Execute(ctx context.Context, params map[string]interface{}) *ToolResult

Execute executes the task summary tool

func (*TaskSummaryTool) Name 

func (t *TaskSummaryTool) Name() string

Name returns the tool name

func (*TaskSummaryTool) Parameters 

func (t *TaskSummaryTool) Parameters() map[string]interface{}

Parameters returns the tool parameters

type TaskSummaryToolSpec 

type TaskSummaryToolSpec struct{}

TaskSummaryToolSpec is the static specification for the task summary tool

func (*TaskSummaryToolSpec) Description 

func (s *TaskSummaryToolSpec) Description() string

func (*TaskSummaryToolSpec) Name 

func (s *TaskSummaryToolSpec) Name() string

func (*TaskSummaryToolSpec) Parameters 

func (s *TaskSummaryToolSpec) Parameters() map[string]interface{}

type TinyGoManager 

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

TinyGoManager handles downloading and caching TinyGo compiler

func NewTinyGoManager 

func NewTinyGoManager() (*TinyGoManager, error)

NewTinyGoManager creates a new TinyGo manager with platform-specific cache directory

func (*TinyGoManager) CleanCache 

func (m *TinyGoManager) CleanCache() error

CleanCache removes the TinyGo cache directory

func (*TinyGoManager) GetCacheSize 

func (m *TinyGoManager) GetCacheSize() (int64, error)

GetCacheSize returns the size of the TinyGo cache in bytes

func (*TinyGoManager) GetTinyGoBinary 

func (m *TinyGoManager) GetTinyGoBinary(ctx context.Context) (string, error)

GetTinyGoBinary returns the path to the TinyGo binary, downloading it if necessary

func (*TinyGoManager) SetStatusCallback 

func (m *TinyGoManager) SetStatusCallback(callback func(string))

SetStatusCallback sets a callback function for status updates

type TodoActor 

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

TodoActor manages todo items as an actor

func NewTodoActor 

func NewTodoActor(name string) *TodoActor

NewTodoActor creates a new TodoActor

func (*TodoActor) ID 

func (a *TodoActor) ID() string

ID returns the actor's unique identifier

func (*TodoActor) Receive 

func (a *TodoActor) Receive(ctx context.Context, msg actor.Message) error

Receive handles incoming messages

func (*TodoActor) SetChangeCallback 

func (a *TodoActor) SetChangeCallback(callback TodoChangeCallback)

SetChangeCallback sets the callback function to be called when todos change

func (*TodoActor) Start 

func (a *TodoActor) Start(ctx context.Context) error

Start initializes the actor

func (*TodoActor) Stop 

func (a *TodoActor) Stop(ctx context.Context) error

Stop stops the actor gracefully

type TodoActorClient 

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

TodoActorClient provides a convenient interface to interact with TodoActor

func NewTodoActorClient 

func NewTodoActorClient(actorRef interface{ Send(msg actor.Message) error }) *TodoActorClient

NewTodoActorClient creates a new client for interacting with TodoActor

func (*TodoActorClient) Add 

func (c *TodoActorClient) Add(text string, timestamp string, parentID string, status string, priority string) (*TodoItem, error)

Add adds a new todo with status and priority

func (*TodoActorClient) AddMany 

func (c *TodoActorClient) AddMany(inputs []TodoInput, timestamp string) ([]*TodoItem, error)

AddMany adds multiple todos at once (atomic operation) The inputs slice should contain TodoInput structs where ParentID can be:

  • An existing todo ID
  • An array index string (e.g., "0", "1", "2") referencing an item in the same batch

func (*TodoActorClient) Check 

func (c *TodoActorClient) Check(id string, checked bool) error

Check marks a todo as checked or unchecked

func (*TodoActorClient) Clear 

func (c *TodoActorClient) Clear() error

Clear removes all todos

func (*TodoActorClient) Delete 

func (c *TodoActorClient) Delete(id string) error

Delete removes a todo

func (*TodoActorClient) List 

func (c *TodoActorClient) List() (*TodoList, error)

List returns the current list of todos

func (*TodoActorClient) SetStatus 

func (c *TodoActorClient) SetStatus(id string, status string) error

SetStatus sets the status of a todo

type TodoActorInterface 

type TodoActorInterface interface {
	actor.Actor
	SetChangeCallback(callback TodoChangeCallback)
}

TodoActorInterface defines the interface for todo actors

type TodoAddManyMsg 

type TodoAddManyMsg struct {
	Todos        []TodoInput
	Timestamp    string
	ResponseChan chan []*TodoItem
}

TodoAddManyMsg adds multiple todos at once (atomic operation) ParentID can be either:

  • An existing todo ID
  • An array index string (e.g., "0", "1", "2") referencing an item in the same batch

func (TodoAddManyMsg) Type 

func (m TodoAddManyMsg) Type() string

type TodoAddMsg 

type TodoAddMsg struct {
	Text         string
	Timestamp    string
	ParentID     string
	Status       string
	Priority     string
	ResponseChan chan *TodoItem
}

TodoAddMsg adds a new todo

func (TodoAddMsg) Type 

func (m TodoAddMsg) Type() string

type TodoChangeCallback 

type TodoChangeCallback func(todos *TodoList)

TodoChangeCallback is called when todos are modified

type TodoCheckMsg 

type TodoCheckMsg struct {
	ID           string
	Checked      bool
	ResponseChan chan error
}

TodoCheckMsg marks a todo as checked/unchecked

func (TodoCheckMsg) Type 

func (m TodoCheckMsg) Type() string

type TodoClearMsg 

type TodoClearMsg struct {
	ResponseChan chan error
}

TodoClearMsg clears all todos

func (TodoClearMsg) Type 

func (m TodoClearMsg) Type() string

type TodoDeleteMsg 

type TodoDeleteMsg struct {
	ID           string
	ResponseChan chan error
}

TodoDeleteMsg deletes a todo

func (TodoDeleteMsg) Type 

func (m TodoDeleteMsg) Type() string

type TodoInput 

type TodoInput struct {
	Text     string
	ParentID string
	Status   string
	Priority string
}

TodoInput represents a todo item for batch add operations

type TodoItem 

type TodoItem struct {
	ID        string `json:"id"`
	Text      string `json:"text"`
	Completed bool   `json:"completed"` // Deprecated: use Status instead
	Status    string `json:"status"`    // "pending", "in_progress", "completed"
	Priority  string `json:"priority"`  // "high", "medium", "low"
	Created   string `json:"created"`
	ParentID  string `json:"parent_id,omitempty"` // Empty string means top-level todo
}

TodoItem represents a todo item

type TodoList 

type TodoList struct {
	Items []*TodoItem `json:"items"`
}

TodoList represents a list of todos

type TodoListMsg 

type TodoListMsg struct {
	ResponseChan chan *TodoList
}

TodoListMsg requests the current list of todos

func (TodoListMsg) Type 

func (m TodoListMsg) Type() string

Implement actor.Message interface for all message types

type TodoSetStatusMsg 

type TodoSetStatusMsg struct {
	ID           string
	Status       string
	ResponseChan chan error
}

TodoSetStatusMsg sets the status of a todo

func (TodoSetStatusMsg) Type 

func (m TodoSetStatusMsg) Type() string

type TodoTool 

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

TodoTool is the executor with runtime dependencies

func NewTodoTool 

func NewTodoTool(client *TodoActorClient) *TodoTool

func (*TodoTool) Description 

func (t *TodoTool) Description() string

func (*TodoTool) Execute 

func (t *TodoTool) Execute(ctx context.Context, params map[string]interface{}) *ToolResult

func (*TodoTool) Name 

func (t *TodoTool) Name() string

Legacy interface implementation for backward compatibility

func (*TodoTool) Parameters 

func (t *TodoTool) Parameters() map[string]interface{}

type TodoToolSpec 

type TodoToolSpec struct{}

TodoToolSpec is the static specification for the todo tool

func (*TodoToolSpec) Description 

func (s *TodoToolSpec) Description() string

func (*TodoToolSpec) Name 

func (s *TodoToolSpec) Name() string

func (*TodoToolSpec) Parameters 

func (s *TodoToolSpec) Parameters() map[string]interface{}

type Tool 

type Tool interface {
	ToolSpec
	ToolExecutor
}

Tool represents an LLM tool (combines ToolSpec and ToolExecutor for convenience). This interface is maintained for backward compatibility with existing tools.

Migration guide: New tools should use ToolSpec + ToolFactory pattern:

Before (legacy): 

type MyTool struct { deps ... }
func (t *MyTool) Name() string { ... }
func (t *MyTool) Description() string { ... }
func (t *MyTool) Parameters() map[string]interface{} { ... }
func (t *MyTool) Execute(ctx, params) *ToolResult { ... }
registry.Register(NewMyTool(deps))

After (new pattern): 

type MyToolSpec struct{}
func (s *MyToolSpec) Name() string { ... }
func (s *MyToolSpec) Description() string { ... }
func (s *MyToolSpec) Parameters() map[string]interface{} { ... }

type MyToolExecutor struct { deps ... }
func (e *MyToolExecutor) Execute(ctx, params) *ToolResult { ... }

func NewMyToolFactory(deps ...) ToolFactory {
    return func(reg *Registry) ToolExecutor {
        return &MyToolExecutor{deps: deps}
    }
}
registry.RegisterSpec(&MyToolSpec{}, NewMyToolFactory(deps))

type ToolCall 

type ToolCall struct {
	ID         string                 `json:"id"`
	Name       string                 `json:"name"`
	Parameters map[string]interface{} `json:"parameters"`
}

ToolCall represents a tool call from the LLM

type ToolExecutionHealth 

type ToolExecutionHealth struct {
	ToolID        string         `json:"tool_id"`
	ToolName      string         `json:"tool_name"`
	State         ExecutionState `json:"state"`
	StartTime     time.Time      `json:"start_time"`
	LastHeartbeat time.Time      `json:"last_heartbeat"`
	ElapsedTime   time.Duration  `json:"elapsed_time"`
	IsStuck       bool           `json:"is_stuck"`
	IsCancelled   bool           `json:"is_cancelled"`
	CustomData    interface{}    `json:"custom_data,omitempty"`
}

ToolExecutionHealth represents the health status of a tool execution

type ToolExecutionMsg 

type ToolExecutionMsg struct {
	Call               *ToolCall
	ToolName           string
	Approved           bool
	Context            context.Context
	ProgressCallback   progress.Callback
	ToolCallCallback   func(string, string, map[string]interface{}) error
	ToolResultCallback func(string, string, string, string) error
	Heartbeat          time.Duration
	ResponseChannel    chan *ToolResult
}

ToolExecutionMsg requests execution of a tool call.

func (ToolExecutionMsg) Type 

func (m ToolExecutionMsg) Type() string

Type implements actor.Message.

type ToolExecutor 

type ToolExecutor interface {
	Execute(ctx context.Context, params map[string]interface{}) *ToolResult
}

ToolExecutor handles the actual execution of a tool with specific runtime dependencies.

Example: 

type MyToolExecutor struct {
    fs      fs.FileSystem
    session *session.Session
}
func (e *MyToolExecutor) Execute(ctx context.Context, params map[string]interface{}) *ToolResult {
    // Use e.fs and e.session
}

type ToolExecutorActor 

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

ToolExecutorActor serializes tool execution through the actor system.

func NewToolExecutorActor 

func NewToolExecutorActor(id string, registry *Registry) *ToolExecutorActor

NewToolExecutorActor creates a new actor that executes tool calls.

func (*ToolExecutorActor) GetHealthMonitor 

func (a *ToolExecutorActor) GetHealthMonitor() *ToolHealthMonitor

GetHealthMonitor returns the health monitor for this executor

func (*ToolExecutorActor) ID 

func (a *ToolExecutorActor) ID() string

ID returns the actor ID.

func (*ToolExecutorActor) Receive 

func (a *ToolExecutorActor) Receive(ctx context.Context, msg actor.Message) error

Receive handles incoming messages.

func (*ToolExecutorActor) Start 

func (a *ToolExecutorActor) Start(ctx context.Context) error

Start initializes the actor.

func (*ToolExecutorActor) Stop 

func (a *ToolExecutorActor) Stop(ctx context.Context) error

Stop shuts down the actor.

type ToolExecutorActorClient 

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

ToolExecutorActorClient provides a facade for interacting with ToolExecutorActor.

func NewToolExecutorActorClient 

func NewToolExecutorActorClient(ref interface{ Send(actor.Message) error }) *ToolExecutorActorClient

NewToolExecutorActorClient returns a new client.

func (*ToolExecutorActorClient) Execute 

func (c *ToolExecutorActorClient) Execute(ctx context.Context, call *ToolCall, toolName string, progressCallback progress.Callback) (*ToolResult, error)

Execute runs the tool call through the actor.

func (*ToolExecutorActorClient) ExecuteWithApproval 

func (c *ToolExecutorActorClient) ExecuteWithApproval(ctx context.Context, call *ToolCall, toolName string, progressCallback progress.Callback) (*ToolResult, error)

ExecuteWithApproval runs the tool call with prior approval.

func (*ToolExecutorActorClient) ExecuteWithCallbacks 

func (c *ToolExecutorActorClient) ExecuteWithCallbacks(ctx context.Context, call *ToolCall, toolName string, progressCallback progress.Callback, toolCallCb func(string, string, map[string]interface{}) error, toolResultCb func(string, string, string, string) error, approved bool) (*ToolResult, error)

ExecuteWithCallbacks runs the tool call with optional callbacks and optional approval bypass.

func (*ToolExecutorActorClient) SetRegistry 

func (c *ToolExecutorActorClient) SetRegistry(reg *Registry) error

SetRegistry updates the executor's registry.

type ToolExecutorUpdateRegistryMsg 

type ToolExecutorUpdateRegistryMsg struct {
	Registry *Registry
}

ToolExecutorUpdateRegistryMsg updates the registry used by the executor.

func (ToolExecutorUpdateRegistryMsg) Type 

func (m ToolExecutorUpdateRegistryMsg) Type() string

Type implements actor.Message.

type ToolFactory 

type ToolFactory func(registry *Registry) ToolExecutor

ToolFactory creates tool executors with specific runtime dependencies. This allows the same tool spec to be instantiated with different dependencies.

The factory receives the registry as a parameter, enabling tools like parallel_tools to access other registered tools.

Example: 

func NewMyToolFactory(fs fs.FileSystem, sess *session.Session) ToolFactory {
    return func(reg *Registry) ToolExecutor {
        return &MyToolExecutor{fs: fs, session: sess}
    }
}

func NewAddContextDirectoryToolFactory 

func NewAddContextDirectoryToolFactory(filesystem fs.FileSystem, cfg *config.Config, sess *session.Session) ToolFactory

NewAddContextDirectoryToolFactory creates a factory for AddContextDirectoryTool

func NewCodebaseInvestigatorToolFactory 

func NewCodebaseInvestigatorToolFactory(investigator Investigator) ToolFactory

NewCodebaseInvestigatorToolFactory creates a factory for CodebaseInvestigatorTool

func NewCreateFileToolFactory 

func NewCreateFileToolFactory(filesystem fs.FileSystem, sess *session.Session) ToolFactory

NewCreateFileToolFactory creates a factory for CreateFileTool

func NewGrepContextFilesToolFactory 

func NewGrepContextFilesToolFactory(filesystem fs.FileSystem, cfg *config.Config, sess *session.Session) ToolFactory

NewGrepContextFilesToolFactory creates a factory for GrepContextFilesTool

func NewLsToolFactory 

func NewLsToolFactory(workingDir string) ToolFactory

NewLsToolFactory creates a factory for LsTool

func NewPlanningToolFactory 

func NewPlanningToolFactory(agent PlanningAgent) ToolFactory

NewPlanningToolFactory creates a factory for PlanningToolExecutor

func NewReadContextFileToolFactory 

func NewReadContextFileToolFactory(filesystem fs.FileSystem, cfg *config.Config, sess *session.Session) ToolFactory

NewReadContextFileToolFactory creates a factory for ReadContextFileTool

func NewReadFileNumberedFactory 

func NewReadFileNumberedFactory(filesystem fs.FileSystem, sess *session.Session) ToolFactory

NewReadFileNumberedFactory creates a factory for the read_file tool executor. This allows the same tool spec to be instantiated with different dependencies.

func NewReadFileToolFactory 

func NewReadFileToolFactory(filesystem fs.FileSystem, sess *session.Session) ToolFactory

NewReadFileToolFactory creates a factory for ReadFileTool

func NewRefactoringAgentToolFactory 

func NewRefactoringAgentToolFactory(agent RefactoringAgent) ToolFactory

NewRefactoringAgentToolFactory creates a factory for RefactoringAgentTool

func NewReplaceFileToolFactory 

func NewReplaceFileToolFactory(filesystem fs.FileSystem, sess *session.Session) ToolFactory

NewReplaceFileToolFactory creates a factory for ReplaceFileTool

func NewSandboxToolWithActorFactory 

func NewSandboxToolWithActorFactory(shellActor actor.ShellActor, sess *session.Session, authorizer Authorizer, configurer func(*SandboxToolWithActor)) ToolFactory

NewSandboxToolWithActorFactory creates a factory for sandbox tools that use ShellActor

func NewScanSecretsToolFactory 

func NewScanSecretsToolFactory() ToolFactory

NewScanSecretsToolFactory creates a new factory for the scan_secrets tool

func NewSearchContextFilesToolFactory 

func NewSearchContextFilesToolFactory(filesystem fs.FileSystem, cfg *config.Config, sess *session.Session) ToolFactory

NewSearchContextFilesToolFactory creates a factory for SearchContextFilesTool

func NewSearchFileContentToolFactory 

func NewSearchFileContentToolFactory(filesystem fs.FileSystem) ToolFactory

NewSearchFileContentToolFactory creates a factory for SearchFileContentTool

func NewSearchFilesToolFactory 

func NewSearchFilesToolFactory(filesystem fs.FileSystem) ToolFactory

NewSearchFilesToolFactory creates a factory for SearchFilesTool

func NewShellToolFactory 

func NewShellToolFactory(sess *session.Session, workingDir string) ToolFactory

NewShellToolFactory creates a factory for ShellTool

func NewShellToolWithActorFactory 

func NewShellToolWithActorFactory(shellActor actor.ShellActor, sess *session.Session, workingDir string) ToolFactory

NewShellToolWithActorFactory creates a factory for shell tools that use ShellActor

func NewStatusProgramToolFactory 

func NewStatusProgramToolFactory(sess *session.Session) ToolFactory

NewStatusProgramToolFactory creates a factory for StatusProgramTool

func NewStatusProgramToolWithActorFactory 

func NewStatusProgramToolWithActorFactory(shellActor actor.ShellActor, sess *session.Session) ToolFactory

NewStatusProgramToolWithActorFactory creates a factory for status program tools that use ShellActor

func NewStopProgramToolFactory 

func NewStopProgramToolFactory(sess *session.Session) ToolFactory

NewStopProgramToolFactory creates a factory for StopProgramTool

func NewStopProgramToolWithActorFactory 

func NewStopProgramToolWithActorFactory(shellActor actor.ShellActor) ToolFactory

NewStopProgramToolWithActorFactory creates a factory for stop program tools that use ShellActor

func NewSummarizeFileToolFactory 

func NewSummarizeFileToolFactory(filesystem fs.FileSystem, sess *session.Session, summarizeClient llm.Client) ToolFactory

NewSummarizeFileToolFactory creates a factory for SummarizeFileTool

func NewTodoToolFactory 

func NewTodoToolFactory(client *TodoActorClient) ToolFactory

NewTodoToolFactory creates a factory for TodoTool

func NewValidateSyntaxToolFactory 

func NewValidateSyntaxToolFactory(filesystem fs.FileSystem) ToolFactory

NewValidateSyntaxToolFactory creates a factory for ValidateSyntaxTool

func NewWaitProgramToolFactory 

func NewWaitProgramToolFactory(sess *session.Session) ToolFactory

NewWaitProgramToolFactory creates a factory for WaitProgramTool

func NewWaitProgramToolWithActorFactory 

func NewWaitProgramToolWithActorFactory(shellActor actor.ShellActor, sess *session.Session) ToolFactory

NewWaitProgramToolWithActorFactory creates a factory for wait program tools that use ShellActor

func NewWebFetchToolFactory 

func NewWebFetchToolFactory(client *http.Client, summarizeClient llm.Client, authorizer Authorizer, detector secretdetect.Detector, featureFlags FeatureFlagsProvider) ToolFactory

NewWebFetchToolFactory creates a factory for WebFetchTool.

func NewWebSearchToolFactory 

func NewWebSearchToolFactory(cfg *config.Config) ToolFactory

NewWebSearchToolFactory creates a factory for WebSearchTool

func NewWriteFileDiffToolFactory 

func NewWriteFileDiffToolFactory(filesystem fs.FileSystem, sess *session.Session) ToolFactory

NewWriteFileDiffToolFactory creates a factory for WriteFileDiffTool

func NewWriteFileJSONToolFactory 

func NewWriteFileJSONToolFactory(filesystem fs.FileSystem, sess *session.Session) ToolFactory

NewWriteFileJSONToolFactory creates a factory for WriteFileJSONTool

func NewWriteFileReplaceSingleToolFactory 

func NewWriteFileReplaceSingleToolFactory(filesystem fs.FileSystem, sess *session.Session) ToolFactory

NewWriteFileReplaceSingleToolFactory creates a factory for WriteFileReplaceSingleTool

func NewWriteFileReplaceToolFactory 

func NewWriteFileReplaceToolFactory(filesystem fs.FileSystem, sess *session.Session) ToolFactory

NewWriteFileReplaceToolFactory creates a factory for WriteFileReplaceTool

func RequestDirectoryAccessToolFactory 

func RequestDirectoryAccessToolFactory(sb *sandbox.Manager) ToolFactory

RequestDirectoryAccessToolFactory creates a factory for RequestDirectoryAccessTool

type ToolHealthMonitor 

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

ToolHealthMonitor tracks the health of ongoing tool executions

func NewToolHealthMonitor 

func NewToolHealthMonitor() *ToolHealthMonitor

NewToolHealthMonitor creates a new tool health monitor

func (*ToolHealthMonitor) CancelExecution 

func (m *ToolHealthMonitor) CancelExecution(toolID string)

CancelExecution marks a tool execution as cancelled

func (*ToolHealthMonitor) CheckForStuckExecutions 

func (m *ToolHealthMonitor) CheckForStuckExecutions() []*ToolExecutionHealth

CheckForStuckExecutions returns a list of executions that appear to be stuck

func (*ToolHealthMonitor) CompleteExecution 

func (m *ToolHealthMonitor) CompleteExecution(toolID string, success bool)

CompleteExecution marks a tool execution as completed

func (*ToolHealthMonitor) GenerateHealthReport 

func (m *ToolHealthMonitor) GenerateHealthReport() *HealthCheckReport

GenerateHealthReport creates a comprehensive health report

func (*ToolHealthMonitor) GetActiveExecutionsCount 

func (m *ToolHealthMonitor) GetActiveExecutionsCount() int

GetActiveExecutionsCount returns the number of currently active executions

func (*ToolHealthMonitor) GetAllHealth 

func (m *ToolHealthMonitor) GetAllHealth() []*ToolExecutionHealth

GetAllHealth returns health status of all tracked executions

func (*ToolHealthMonitor) GetHealth 

func (m *ToolHealthMonitor) GetHealth(toolID string) (*ToolExecutionHealth, bool)

GetHealth returns the health status of a specific tool execution

func (*ToolHealthMonitor) Heartbeat 

func (m *ToolHealthMonitor) Heartbeat(toolID string)

Heartbeat updates the last heartbeat time for a tool execution

func (*ToolHealthMonitor) RemoveExecution 

func (m *ToolHealthMonitor) RemoveExecution(toolID string)

RemoveExecution removes a tool execution from tracking

func (*ToolHealthMonitor) SetCustomData 

func (m *ToolHealthMonitor) SetCustomData(toolID string, data interface{})

SetCustomData sets custom data for a tool execution (e.g., process info, dialog state)

func (*ToolHealthMonitor) SetMaxExecutionTime 

func (m *ToolHealthMonitor) SetMaxExecutionTime(maxTime time.Duration)

SetMaxExecutionTime updates the maximum allowed execution time

func (*ToolHealthMonitor) SetStuckThreshold 

func (m *ToolHealthMonitor) SetStuckThreshold(threshold time.Duration)

SetStuckThreshold updates the threshold for detecting stuck executions

func (*ToolHealthMonitor) StartExecution 

func (m *ToolHealthMonitor) StartExecution(toolID, toolName string)

StartExecution registers a new tool execution

func (*ToolHealthMonitor) UpdateState 

func (m *ToolHealthMonitor) UpdateState(toolID string, state ExecutionState)

UpdateState updates the state of a tool execution

type ToolPreChecker 

type ToolPreChecker interface {
	PreCheck(ctx context.Context, params map[string]interface{}) *ToolResult
}

ToolPreChecker is an optional interface that tool executors can implement to perform fast validation before the authorization actor is invoked. If PreCheck returns a non-nil *ToolResult, that result is returned immediately without going through authorization or execution. If PreCheck returns nil, the normal authorization and execution flow continues.

type ToolResult 

type ToolResult struct {
	ID                     string      `json:"id"`
	Result                 interface{} `json:"result"`
	Error                  string      `json:"error,omitempty"`
	RequiresUserInput      bool        `json:"requires_user_input,omitempty"`      // If true, user approval is needed
	AuthReason             string      `json:"auth_reason,omitempty"`              // Reason for requiring authorization
	SuggestedCommandPrefix string      `json:"suggested_command_prefix,omitempty"` // Suggested prefix to remember for future use

	// Enhanced execution metadata for better summaries and diagnostics
	ExecutionMetadata *ExecutionMetadata `json:"execution_metadata,omitempty"`

	// Dual response support: separate responses for LLM and UI
	// If UIResult is set, it will be used for UI display instead of Result
	// The LLM will always receive Result in its messages
	UIResult interface{} `json:"ui_result,omitempty"`
}

ToolResult represents the result of a tool execution

func EnhanceToolResult 

func EnhanceToolResult(result *ToolResult, metadata *ExecutionMetadata) *ToolResult

EnhanceToolResult adds metadata to an existing ToolResult

func NewToolResultWithMetadata 

func NewToolResultWithMetadata(id string, result interface{}, err error, metadata *ExecutionMetadata) *ToolResult

NewToolResultWithMetadata creates a ToolResult with execution metadata

type ToolSpec 

type ToolSpec interface {
	Name() string
	Description() string
	Parameters() map[string]interface{}
}

ToolSpec represents the static specification of a tool (name, description, parameters). This is used for LLM schema generation and does not require any runtime dependencies.

Design rationale: Separating specification from execution allows: - Single spec instance shared across multiple registries (memory efficient) - Clear lifecycle: specs are immutable singletons, executors are runtime instances - Flexible dependency injection through factories

Example: 

type MyToolSpec struct{}
func (s *MyToolSpec) Name() string { return "my_tool" }
func (s *MyToolSpec) Description() string { return "Does something" }
func (s *MyToolSpec) Parameters() map[string]interface{} { return ... }

type ToolSummarizeTool 

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

ToolSummarizeTool wraps another tool call and summarizes its output using LLM

func NewToolSummarizeTool 

func NewToolSummarizeTool(registry *Registry, summarizeClient llm.Client) *ToolSummarizeTool

func (*ToolSummarizeTool) Description 

func (t *ToolSummarizeTool) Description() string

func (*ToolSummarizeTool) Execute 

func (t *ToolSummarizeTool) Execute(ctx context.Context, args map[string]interface{}) *ToolResult

func (*ToolSummarizeTool) Name 

func (t *ToolSummarizeTool) Name() string

func (*ToolSummarizeTool) Parameters 

func (t *ToolSummarizeTool) Parameters() map[string]interface{}

type UserDialogInfo 

type UserDialogInfo struct {
	DialogType    string    `json:"dialog_type"` // "ask_user", "ask_user_multiple", "authorization"
	IsDisplayed   bool      `json:"is_displayed"`
	QuestionCount int       `json:"question_count,omitempty"`
	CreatedAt     time.Time `json:"created_at"`
}

UserDialogInfo contains information about a user dialog

type VCSActor 

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

VCSActor manages VCS state as an actor

func NewVCSActor 

func NewVCSActor(name string, vcsInstance vcs.VCS) *VCSActor

NewVCSActor creates a new VCSActor

func (*VCSActor) ID 

func (a *VCSActor) ID() string

ID returns the actor's unique identifier

func (*VCSActor) Receive 

func (a *VCSActor) Receive(ctx context.Context, msg actor.Message) error

Receive handles incoming messages

func (*VCSActor) Start 

func (a *VCSActor) Start(ctx context.Context) error

Start initializes the actor and loads initial branch

func (*VCSActor) Stop 

func (a *VCSActor) Stop(ctx context.Context) error

Stop stops the actor gracefully

type VCSActorClient 

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

VCSActorClient provides a convenient interface to interact with VCSActor

func NewVCSActorClient 

func NewVCSActorClient(actorRef interface{ Send(msg actor.Message) error }) *VCSActorClient

NewVCSActorClient creates a new client for interacting with VCSActor

func (*VCSActorClient) GetCurrentBranch 

func (c *VCSActorClient) GetCurrentBranch() (string, error)

GetCurrentBranch returns the current branch

func (*VCSActorClient) RefreshBranch 

func (c *VCSActorClient) RefreshBranch() (string, error)

RefreshBranch refreshes the current branch from VCS and returns it

type VCSActorInterface 

type VCSActorInterface interface {
	actor.Actor
}

VCSActorInterface defines the interface for VCS actors

type VCSGetCurrentBranchMsg 

type VCSGetCurrentBranchMsg struct {
	ResponseChan chan string
}

VCSGetCurrentBranchMsg requests the current branch

func (VCSGetCurrentBranchMsg) Type 

func (m VCSGetCurrentBranchMsg) Type() string

Implement actor.Message interface for all message types

type VCSRefreshBranchMsg 

type VCSRefreshBranchMsg struct {
	ResponseChan chan string
}

VCSRefreshBranchMsg refreshes the current branch from VCS

func (VCSRefreshBranchMsg) Type 

func (m VCSRefreshBranchMsg) Type() string

type ValidateSyntaxToolExecutor 

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

ValidateSyntaxToolExecutor handles execution of the validate_syntax tool

func (*ValidateSyntaxToolExecutor) Execute 

func (e *ValidateSyntaxToolExecutor) Execute(ctx context.Context, params map[string]interface{}) *ToolResult

type ValidateSyntaxToolSpec 

type ValidateSyntaxToolSpec struct{}

ValidateSyntaxToolSpec is the static specification for the validate_syntax tool

func (*ValidateSyntaxToolSpec) Description 

func (s *ValidateSyntaxToolSpec) Description() string

func (*ValidateSyntaxToolSpec) Name 

func (s *ValidateSyntaxToolSpec) Name() string

func (*ValidateSyntaxToolSpec) Parameters 

func (s *ValidateSyntaxToolSpec) Parameters() map[string]interface{}

type WaitProgramTool 

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

WaitProgramTool is the executor with runtime dependencies

func NewWaitProgramTool 

func NewWaitProgramTool(sess *session.Session) *WaitProgramTool

func (*WaitProgramTool) Description 

func (t *WaitProgramTool) Description() string

func (*WaitProgramTool) Execute 

func (t *WaitProgramTool) Execute(ctx context.Context, params map[string]interface{}) *ToolResult

func (*WaitProgramTool) Name 

func (t *WaitProgramTool) Name() string

Legacy interface implementation for backward compatibility

func (*WaitProgramTool) Parameters 

func (t *WaitProgramTool) Parameters() map[string]interface{}

type WaitProgramToolSpec 

type WaitProgramToolSpec struct{}

WaitProgramToolSpec is the static specification for the wait_program tool

func (*WaitProgramToolSpec) Description 

func (s *WaitProgramToolSpec) Description() string

func (*WaitProgramToolSpec) Name 

func (s *WaitProgramToolSpec) Name() string

func (*WaitProgramToolSpec) Parameters 

func (s *WaitProgramToolSpec) Parameters() map[string]interface{}

type WaitProgramToolWithActor 

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

WaitProgramToolWithActor is the wait program tool that uses ShellActor

func NewWaitProgramToolWithActor 

func NewWaitProgramToolWithActor(sess *session.Session, shellActor actor.ShellActor) *WaitProgramToolWithActor

func (*WaitProgramToolWithActor) Description 

func (t *WaitProgramToolWithActor) Description() string

func (*WaitProgramToolWithActor) Execute 

func (t *WaitProgramToolWithActor) Execute(ctx context.Context, params map[string]interface{}) *ToolResult

func (*WaitProgramToolWithActor) Name 

func (t *WaitProgramToolWithActor) Name() string

func (*WaitProgramToolWithActor) Parameters 

func (t *WaitProgramToolWithActor) Parameters() map[string]interface{}

type WebFetchTool 

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

WebFetchTool performs GET requests with optional summarization.

func NewWebFetchTool 

func NewWebFetchTool(client *http.Client, summarizeClient llm.Client, authorizer Authorizer, detector secretdetect.Detector, featureFlags FeatureFlagsProvider) *WebFetchTool

NewWebFetchTool constructs a WebFetchTool.

func (*WebFetchTool) Description 

func (t *WebFetchTool) Description() string

func (*WebFetchTool) Execute 

func (t *WebFetchTool) Execute(ctx context.Context, params map[string]interface{}) *ToolResult

func (*WebFetchTool) Name 

func (t *WebFetchTool) Name() string

Legacy compatibility helpers.

func (*WebFetchTool) Parameters 

func (t *WebFetchTool) Parameters() map[string]interface{}

type WebFetchToolSpec 

type WebFetchToolSpec struct{}

WebFetchToolSpec defines the schema for the web_fetch tool.

func (*WebFetchToolSpec) Description 

func (s *WebFetchToolSpec) Description() string

func (*WebFetchToolSpec) Name 

func (s *WebFetchToolSpec) Name() string

func (*WebFetchToolSpec) Parameters 

func (s *WebFetchToolSpec) Parameters() map[string]interface{}

type WebSearchTool 

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

WebSearchTool is the executor with runtime dependencies

func NewWebSearchTool 

func NewWebSearchTool(cfg *config.Config) *WebSearchTool

NewWebSearchTool creates a new web search tool

func (*WebSearchTool) Description 

func (t *WebSearchTool) Description() string

func (*WebSearchTool) Execute 

func (t *WebSearchTool) Execute(ctx context.Context, params map[string]interface{}) *ToolResult

func (*WebSearchTool) Name 

func (t *WebSearchTool) Name() string

Legacy interface implementation for backward compatibility

func (*WebSearchTool) Parameters 

func (t *WebSearchTool) Parameters() map[string]interface{}

type WebSearchToolSpec 

type WebSearchToolSpec struct{}

WebSearchToolSpec is the static specification for the web_search tool

func (*WebSearchToolSpec) Description 

func (s *WebSearchToolSpec) Description() string

func (*WebSearchToolSpec) Name 

func (s *WebSearchToolSpec) Name() string

func (*WebSearchToolSpec) Parameters 

func (s *WebSearchToolSpec) Parameters() map[string]interface{}

type WriteFileDiffTool 

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

WriteFileDiffTool applies unified diffs to existing files. This tool required actual git-like diffs with hunk headers which seems to be a big problem in today's LLMs.

func NewWriteFileDiffTool 

func NewWriteFileDiffTool(filesystem fs.FileSystem, sess *session.Session) *WriteFileDiffTool

func (*WriteFileDiffTool) Description 

func (t *WriteFileDiffTool) Description() string

func (*WriteFileDiffTool) Execute 

func (t *WriteFileDiffTool) Execute(ctx context.Context, params map[string]interface{}) *ToolResult

func (*WriteFileDiffTool) Name 

func (t *WriteFileDiffTool) Name() string

Legacy interface implementation for backward compatibility

func (*WriteFileDiffTool) Parameters 

func (t *WriteFileDiffTool) Parameters() map[string]interface{}

func (*WriteFileDiffTool) PreCheck 

func (t *WriteFileDiffTool) PreCheck(ctx context.Context, params map[string]interface{}) *ToolResult

PreCheck validates that the file has been read before allowing edits. This runs before the authorization actor to avoid unnecessary user prompts.

type WriteFileDiffToolSpec 

type WriteFileDiffToolSpec struct{}

WriteFileDiffToolSpec is the static specification for the write_file_diff tool

func (*WriteFileDiffToolSpec) Description 

func (s *WriteFileDiffToolSpec) Description() string

func (*WriteFileDiffToolSpec) Name 

func (s *WriteFileDiffToolSpec) Name() string

func (*WriteFileDiffToolSpec) Parameters 

func (s *WriteFileDiffToolSpec) Parameters() map[string]interface{}

func (*WriteFileDiffToolSpec) RequiresExclusiveExecution 

func (s *WriteFileDiffToolSpec) RequiresExclusiveExecution() bool

type WriteFileJSONTool 

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

WriteFileJSONTool is the executor with runtime dependencies

func NewWriteFileJSONTool 

func NewWriteFileJSONTool(filesystem fs.FileSystem, sess *session.Session) *WriteFileJSONTool

NewWriteFileJSONTool creates a new instance of the JSON file writing tool.

func (*WriteFileJSONTool) Description 

func (t *WriteFileJSONTool) Description() string

func (*WriteFileJSONTool) Execute 

func (t *WriteFileJSONTool) Execute(ctx context.Context, params map[string]interface{}) *ToolResult

func (*WriteFileJSONTool) Name 

func (t *WriteFileJSONTool) Name() string

Legacy interface implementation for backward compatibility

func (*WriteFileJSONTool) Parameters 

func (t *WriteFileJSONTool) Parameters() map[string]interface{}

type WriteFileJSONToolSpec 

type WriteFileJSONToolSpec struct{}

WriteFileJSONToolSpec is the static specification for the write_file_json tool

func (*WriteFileJSONToolSpec) Description 

func (s *WriteFileJSONToolSpec) Description() string

func (*WriteFileJSONToolSpec) Name 

func (s *WriteFileJSONToolSpec) Name() string

func (*WriteFileJSONToolSpec) Parameters 

func (s *WriteFileJSONToolSpec) Parameters() map[string]interface{}

func (*WriteFileJSONToolSpec) RequiresExclusiveExecution 

func (s *WriteFileJSONToolSpec) RequiresExclusiveExecution() bool

type WriteFileReplaceSingleTool 

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

WriteFileReplaceSingleTool is the executor with runtime dependencies.

func NewWriteFileReplaceSingleTool 

func NewWriteFileReplaceSingleTool(filesystem fs.FileSystem, sess *session.Session) *WriteFileReplaceSingleTool

func (*WriteFileReplaceSingleTool) Description 

func (t *WriteFileReplaceSingleTool) Description() string

func (*WriteFileReplaceSingleTool) Execute 

func (t *WriteFileReplaceSingleTool) Execute(ctx context.Context, params map[string]interface{}) *ToolResult

func (*WriteFileReplaceSingleTool) Name 

func (t *WriteFileReplaceSingleTool) Name() string

func (*WriteFileReplaceSingleTool) Parameters 

func (t *WriteFileReplaceSingleTool) Parameters() map[string]interface{}

type WriteFileReplaceSingleToolSpec 

type WriteFileReplaceSingleToolSpec struct{}

WriteFileReplaceSingleToolSpec is the static specification for the write_file_replace_single tool

func (*WriteFileReplaceSingleToolSpec) Description 

func (s *WriteFileReplaceSingleToolSpec) Description() string

func (*WriteFileReplaceSingleToolSpec) Name 

func (s *WriteFileReplaceSingleToolSpec) Name() string

func (*WriteFileReplaceSingleToolSpec) Parameters 

func (s *WriteFileReplaceSingleToolSpec) Parameters() map[string]interface{}

func (*WriteFileReplaceSingleToolSpec) RequiresExclusiveExecution 

func (s *WriteFileReplaceSingleToolSpec) RequiresExclusiveExecution() bool

type WriteFileReplaceTool 

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

WriteFileReplaceTool is the executor with runtime dependencies.

func NewWriteFileReplaceTool 

func NewWriteFileReplaceTool(filesystem fs.FileSystem, sess *session.Session) *WriteFileReplaceTool

func (*WriteFileReplaceTool) Description 

func (t *WriteFileReplaceTool) Description() string

func (*WriteFileReplaceTool) Execute 

func (t *WriteFileReplaceTool) Execute(ctx context.Context, params map[string]interface{}) *ToolResult

func (*WriteFileReplaceTool) Name 

func (t *WriteFileReplaceTool) Name() string

func (*WriteFileReplaceTool) Parameters 

func (t *WriteFileReplaceTool) Parameters() map[string]interface{}

type WriteFileReplaceToolSpec 

type WriteFileReplaceToolSpec struct{}

WriteFileReplaceToolSpec is the static specification for the write_file_replace tool

func (*WriteFileReplaceToolSpec) Description 

func (s *WriteFileReplaceToolSpec) Description() string

func (*WriteFileReplaceToolSpec) Name 

func (s *WriteFileReplaceToolSpec) Name() string

func (*WriteFileReplaceToolSpec) Parameters 

func (s *WriteFileReplaceToolSpec) Parameters() map[string]interface{}

func (*WriteFileReplaceToolSpec) RequiresExclusiveExecution 

func (s *WriteFileReplaceToolSpec) RequiresExclusiveExecution() bool

type WriteFileSimpleDiffTool 

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

WriteFileSimpleDiffTool applies simplified diffs that omit hunk headers. This tool call is more tolerant of LLM output that omits hunk markers or other minor formatting differences.

func NewWriteFileSimpleDiffTool 

func NewWriteFileSimpleDiffTool(filesystem fs.FileSystem, sess *session.Session) *WriteFileSimpleDiffTool

NewWriteFileSimpleDiffTool creates a new instance of the simplified diff tool.

func (*WriteFileSimpleDiffTool) Description 

func (t *WriteFileSimpleDiffTool) Description() string

func (*WriteFileSimpleDiffTool) Execute 

func (t *WriteFileSimpleDiffTool) Execute(ctx context.Context, params map[string]interface{}) *ToolResult

func (*WriteFileSimpleDiffTool) Name 

func (t *WriteFileSimpleDiffTool) Name() string

func (*WriteFileSimpleDiffTool) Parameters 

func (t *WriteFileSimpleDiffTool) Parameters() map[string]interface{}

func (*WriteFileSimpleDiffTool) RequiresExclusiveExecution 

func (t *WriteFileSimpleDiffTool) RequiresExclusiveExecution() bool

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.