Help us shape the future of Go! Take the 2026 Go Developer Survey

tools

package
v0.2.11 Latest Latest
Warning

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

 Go to latest Published: Oct 19, 2026 License: Apache-2.0 Imports: 16 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	ErrKindValidation       = "validation"        // bad/missing params; model should re-call with corrected args
	ErrKindMissing          = "missing"           // referenced resource not found (file, URL, tool)
	ErrKindPermissionDenied = "permission_denied" // gated by policy / OS / approval-rejection
	ErrKindTimeout          = "timeout"           // exceeded an internal deadline
	ErrKindTransient        = "transient"         // network blip / rate limit / overloaded; safe to retry
	ErrKindLoopBlocked      = "loop_blocked"      // orchestrator's loop-detector fired
	ErrKindStaleRead        = "stale_read"        // stale-edit tracker refused the op
	ErrKindCancelled        = "cancelled"         // context cancelled mid-execution
	ErrKindInternal         = "internal"          // tool bug / panic-recovered / unexpected
)

Error kind constants. Small, behavioural taxonomy — each kind triggers a different *code path* in the orchestrator or the model's recovery strategy. Resist adding kinds for every nuance; the Error string is where sub-categories belong.

Variables

This section is empty.

Functions

func SetPageContext 

func SetPageContext(store *sync.Map, paneID string, ctx PageContext)

SetPageContext stores a PageContext for a given pane ID. This is a package-level helper used by BrowserPaneService to inject context before the tool is invoked.

Types

type BrowserActionPublisher 

type BrowserActionPublisher interface {
	// SendBrowserAction publishes a browser action request envelope to the given
	// NATS subject. The implementation is responsible for NATSEnvelope encoding.
	SendBrowserAction(subject string, requestID, action string, params json.RawMessage) error
}

BrowserActionPublisher is the interface the BrowserActionTool needs to send requests. This avoids importing the msg package directly (which causes cross-module import path conflicts with the replace directive).

type BrowserActionTool 

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

BrowserActionTool allows the LLM to control the user's Chrome browser through the Rysh Chrome extension. Actions include navigating to URLs, clicking elements, filling forms, taking screenshots, and extracting page content.

The tool publishes a browser action request to the pane's NATS subject and waits for a response from the extension.

func NewBrowserActionTool 

func NewBrowserActionTool(paneID string, nc *natsclient.Conn, pub BrowserActionPublisher, reqSubject, respSubject string) *BrowserActionTool

NewBrowserActionTool creates a BrowserActionTool for the given pane. subjectFn builds NATS subjects from parts (e.g. msg.T).

func (*BrowserActionTool) Execute 

func (t *BrowserActionTool) Execute(ctx context.Context, params json.RawMessage) (*ToolOutput, error)

Execute sends a browser action request to the Chrome extension via NATS and waits for the response.

func (*BrowserActionTool) RequiresApproval 

func (t *BrowserActionTool) RequiresApproval(params json.RawMessage) bool

RequiresApproval returns true only for execute_js which runs arbitrary code.

func (*BrowserActionTool) Spec 

func (t *BrowserActionTool) Spec() ToolSpec

Spec returns the tool specification for the LLM.

type ListToolsTool 

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

ListToolsTool lists all available tools and their descriptions.

func NewListToolsTool 

func NewListToolsTool(registry *ToolRegistry) *ListToolsTool

NewListToolsTool creates a new ListToolsTool that references the given registry.

func (*ListToolsTool) Execute 

func (t *ListToolsTool) Execute(ctx context.Context, params json.RawMessage) (*ToolOutput, error)

Execute returns a formatted list of all registered tools.

func (*ListToolsTool) RequiresApproval 

func (t *ListToolsTool) RequiresApproval(_ json.RawMessage) bool

RequiresApproval always returns false for list_tools.

func (*ListToolsTool) Spec 

func (t *ListToolsTool) Spec() ToolSpec

Spec returns the tool specification for the LLM.

type PageContext 

type PageContext struct {
	URL          string `json:"url"`
	Title        string `json:"title"`
	SelectedText string `json:"selected_text"`
	BodyText     string `json:"body_text"`
}

PageContext holds the content of the current browser tab, injected by the Chrome extension for each LLM request. The server stores one PageContext per pane ID in a sync.Map and clears it after the tool is invoked (single-use).

type PageContextTool 

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

PageContextTool allows the LLM to read the current browser tab's content. The Chrome plugin injects {url, title, selected_text, body_text} per-request. The server stores the context in a sync.Map keyed by pane ID and clears it after each tool invocation (single-use).

func NewPageContextTool 

func NewPageContextTool(paneID string, store *sync.Map) *PageContextTool

NewPageContextTool creates a PageContextTool for the given pane. store is a shared *sync.Map maintained by BrowserPaneService.

func (*PageContextTool) Execute 

func (t *PageContextTool) Execute(_ context.Context, _ json.RawMessage) (*ToolOutput, error)

Execute returns the stored PageContext for this pane, then clears it (single-use). If no context is set, it returns a message indicating no context is available.

func (*PageContextTool) RequiresApproval 

func (t *PageContextTool) RequiresApproval(_ json.RawMessage) bool

RequiresApproval always returns false for page_context.

func (*PageContextTool) Spec 

func (t *PageContextTool) Spec() ToolSpec

Spec returns the tool specification for the LLM.

type Previewer added in v0.2.11 

type Previewer interface {
	Preview(ctx context.Context, params json.RawMessage) (*ToolOutput, error)
}

Previewer is implemented by file-mutating tools (edit, file_write) that can compute their result — the unified diff — without touching disk. The orchestrator's approval gate calls Preview to show the diff, and calls Execute only after the user approves, so a rejected change is never written. A tool that does not implement Previewer is executed before the approval prompt (legacy behaviour).

type ToolConfig 

type ToolConfig struct {
	WorkDir         string
	BashTimeout     time.Duration
	BlockedCommands []string
	MaxFileSize     int64
	BlockedPaths    []string
}

ToolConfig holds configuration for tool executors.

type ToolExecutor 

type ToolExecutor interface {
	Execute(ctx context.Context, params json.RawMessage) (*ToolOutput, error)
	Spec() ToolSpec
	RequiresApproval(params json.RawMessage) bool
}

ToolExecutor is implemented by each tool.

type ToolOutput 

type ToolOutput struct {
	Content string `json:"content"`
	Error   string `json:"error,omitempty"`
	// ErrorKind is a typed classification of an error: validation,
	// missing, permission_denied, timeout, transient, loop_blocked,
	// stale_read, cancelled, internal. Empty when Error is empty (or for
	// pre-existing callers). Follow-up item 4.
	ErrorKind string            `json:"error_kind,omitempty"`
	ExitCode  int               `json:"exit_code,omitempty"`
	Metadata  map[string]string `json:"metadata,omitempty"`
}

ToolOutput is the result of a tool execution.

func ErrOutput 

func ErrOutput(kind, msg string) *ToolOutput

ErrOutput is a small constructor for an error-only ToolOutput with a typed kind. Tool authors should prefer this over `&ToolOutput{Error:...}` so the kind is captured at the source.

func ErrOutputf 

func ErrOutputf(kind, format string, args ...interface{}) *ToolOutput

ErrOutputf is the printf-flavoured variant of ErrOutput.

type ToolRegistry 

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

ToolRegistry holds all registered tool executors.

A registry may optionally have a parent. Lookups (Get/AllSpecs/Names) consult the registry's own tools first, then fall back to the parent — so a child reads its parent *live*. This is how per-pane / per-agent registries stay in sync with the shared registry: per-pane tools (which need pane-specific handles) live in the child's own map, while shared tools (bash, file, and dynamically enabled forge/mcp tools) are read from the live parent. The child's own entries override the parent on name collision.

parent is set once at construction (NewChildRegistry) and never mutated, so it is safe to read without holding the lock. Clone() always produces a flat, parent-less snapshot (see Clone).

func DefaultRegistry 

func DefaultRegistry(executors ...ToolExecutor) *ToolRegistry

DefaultRegistry creates a ToolRegistry and registers each provided executor using its Spec().Name as the key.

func NewChildRegistry 

func NewChildRegistry(parent *ToolRegistry) *ToolRegistry

NewChildRegistry creates a registry that delegates lookups to parent for any tool it does not hold itself. Register tools into the child to add per-owner tools (or to override a parent tool by name); the parent continues to be read live, so tools added to or removed from the parent after the child is created are immediately visible through the child. parent may be nil (equivalent to NewToolRegistry).

func NewToolRegistry 

func NewToolRegistry() *ToolRegistry

NewToolRegistry creates an empty ToolRegistry.

func (*ToolRegistry) AllSpecs 

func (r *ToolRegistry) AllSpecs() []ToolSpec

AllSpecs returns the ToolSpec for every registered tool, sorted by name. When a parent is set, its specs are merged in (read live); own tools override the parent on name collision.

func (*ToolRegistry) Clone 

func (r *ToolRegistry) Clone() *ToolRegistry

Clone creates a flat, parent-less copy of the registry: the **entire** ancestor chain (read live) is merged in root-first, so a narrower (deeper) scope's tools override wider ones by name. Tools that implement cloneTooler are deep-copied (so per-run working-directory changes are isolated); all other tool references are shared. The map is independent so new tools can be added without affecting the original.

Walking the full chain (not just the immediate parent) is what lets registries be nested into a scope hierarchy — e.g. pane → group → lane → tab → global — and still flatten correctly into one per-run snapshot. Because each ancestor is read live at clone time, cloning a child picks up tools that were added to (or removed from) any ancestor since the child was created. This is what makes ##integration / ##mcp enable/disable (at any scope) take effect on the next run of an existing pane/agent without re-creating it.

func (*ToolRegistry) Get 

func (r *ToolRegistry) Get(name string) (ToolExecutor, bool)

Get retrieves a tool executor by name. Own tools take precedence; if not found and a parent is set, the lookup falls back to the (live) parent.

func (*ToolRegistry) Names 

func (r *ToolRegistry) Names() []string

Names returns the sorted list of registered tool names, including the parent's (read live) when a parent is set.

func (*ToolRegistry) Register 

func (r *ToolRegistry) Register(name string, executor ToolExecutor)

Register adds a tool executor under the given name.

func (*ToolRegistry) SetParent 

func (r *ToolRegistry) SetParent(parent *ToolRegistry)

SetParent re-points this registry's parent (the rest of its scope chain). Used for agent/humanoid registries whose effective scope is the invoking pane's chain, resolved per prompt. Reads (Get/AllSpecs/Names/Clone) observe the change atomically. Pass nil to detach (lookups then see only own tools).

func (*ToolRegistry) SetWorkDir 

func (r *ToolRegistry) SetWorkDir(dir string)

SetWorkDir updates the working directory on every registered tool that implements WorkDirAware. Tools that don't are left untouched. A blank dir is ignored so callers can pass an unresolved cwd without clobbering defaults.

func (*ToolRegistry) Unregister 

func (r *ToolRegistry) Unregister(name string) bool

Unregister removes the tool executor registered under name. It returns true if a tool was removed, false if no tool was registered under that name. It is the inverse of Register and is used to retract dynamically-added tools (e.g. tools discovered from an MCP server that is later removed).

type ToolSpec 

type ToolSpec struct {
	Name             string          `json:"name"`
	Description      string          `json:"description"`
	Parameters       json.RawMessage `json:"parameters"` // JSON Schema
	RequiresApproval bool            `json:"-"`
}

ToolSpec describes a tool for the LLM.

type WebFetchParams 

type WebFetchParams struct {
	URL         string `json:"url"`
	MaxLength   int    `json:"max_length,omitempty"`
	ExtractMode string `json:"extract_mode,omitempty"` // "text", "html", "raw"
}

WebFetchParams holds the parameters for a web fetch request.

type WebFetchTool 

type WebFetchTool struct{}

WebFetchTool fetches and parses content from a specific URL.

func NewWebFetchTool 

func NewWebFetchTool() *WebFetchTool

NewWebFetchTool creates a new WebFetchTool.

func (*WebFetchTool) Execute 

func (t *WebFetchTool) Execute(ctx context.Context, params json.RawMessage) (*ToolOutput, error)

Execute fetches content from the specified URL.

func (*WebFetchTool) RequiresApproval 

func (t *WebFetchTool) RequiresApproval(_ json.RawMessage) bool

RequiresApproval always returns false for web_fetch.

func (*WebFetchTool) Spec 

func (t *WebFetchTool) Spec() ToolSpec

Spec returns the tool specification for the LLM.

type WebSearchParams 

type WebSearchParams struct {
	Query string `json:"query"`
	Count int    `json:"count,omitempty"`
}

type WebSearchTool 

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

func NewWebSearchTool 

func NewWebSearchTool(apiKey string) *WebSearchTool

func (*WebSearchTool) Execute 

func (t *WebSearchTool) Execute(ctx context.Context, params json.RawMessage) (*ToolOutput, error)

func (*WebSearchTool) RequiresApproval 

func (t *WebSearchTool) RequiresApproval(_ json.RawMessage) bool

func (*WebSearchTool) Spec 

func (t *WebSearchTool) Spec() ToolSpec

type WorkDirAware 

type WorkDirAware interface {
	SetWorkDir(dir string)
}

WorkDirAware is implemented by tools whose relative-path resolution is anchored to a working directory that can change at runtime. The orchestrator calls Registry.SetWorkDir at the start of each run so AI-mode tools follow the pane's live shell cwd (e.g. after the user `cd`s in shell mode).

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.