tools

package
v100.0.0-...-39595da Latest Latest
Warning

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

 Go to latest Published: Aug 1, 2026 License: MIT Imports: 40 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// DefaultToolResultChars is the default character cap for tool outputs.
	// Set slightly above the policy default (20000) to give the loop's
	// truncation logic the final word while preventing pathological cases.
	DefaultToolResultChars = 24000

	// DefaultFetchBytes is the default byte cap for HTTP fetches (curl, web_extract).
	// HTML compresses heavily to text, so we allow more bytes than chars.
	// Was previously 128KB (6x policy default) — now 64KB (~3x policy default).
	DefaultFetchBytes int64 = 64 * 1024

	// MaxFetchBytes is the absolute upper bound on HTTP fetch sizes
	// regardless of caller request. Prevents DoS via large remote responses.
	MaxFetchBytes int64 = 2 * 1024 * 1024
)

Default output caps for tools. These are slightly above the policy's MaxToolResultChars default (20000) so the policy's truncation layer has the final say, but tool-layer caps prevent runaway memory/IO from extremely large responses.

View Source 
const (
	// HandoffSchemaStandard is the built-in structured sub-agent result schema.
	HandoffSchemaStandard = "standard"
)

Variables

This section is empty.

Functions

func EnvNames 

func EnvNames(env []string) []string

EnvNames returns the variable names from KEY=value env entries.

func ExtractJSONObject 

func ExtractJSONObject(text string) (json.RawMessage, error)

ExtractJSONObject extracts a JSON object from raw model text. It accepts pure JSON, fenced ```json blocks, or the first balanced object in the text.

func GitHubCLIDiagnostic 

func GitHubCLIDiagnostic(output string, envNames []string) string

GitHubCLIDiagnostic returns an actionable auth diagnostic for common gh errors.

func HandoffSchemaPrompt 

func HandoffSchemaPrompt(name string, schema json.RawMessage) string

HandoffSchemaPrompt returns compact instructions for schema-constrained child runs.

func ResolveHandoffSchema 

func ResolveHandoffSchema(name string, schema json.RawMessage) (json.RawMessage, string, error)

ResolveHandoffSchema returns the schema selected by a caller. Custom schemas take precedence over named schemas. An empty name and empty schema means the legacy markdown handoff contract should be used.

func TruncateOutput 

func TruncateOutput(s string, maxChars int) string

TruncateOutput truncates s to maxChars characters, appending a human-readable suffix indicating how many characters were elided. If maxChars <= 0 or s is already short enough, returns s unchanged.

func ValidEnvName 

func ValidEnvName(name string) bool

ValidEnvName reports whether name is safe to use as an environment key.

func ValidateJSONSchema 

func ValidateJSONSchema(raw json.RawMessage, schema json.RawMessage) []string

ValidateJSONSchema implements the small JSON Schema subset needed by handoff contracts: type, required, properties, items, and enum.

func ValidateStructuredHandoff 

func ValidateStructuredHandoff(text string, schema json.RawMessage) (json.RawMessage, []string)

ValidateStructuredHandoff extracts a JSON object from model text and validates it against a resolved handoff schema.

func WebSearchEnabled 

func WebSearchEnabled() bool

WebSearchEnabled returns true if the Brave Search API key is configured.

Types

type AgentRunFn 

type AgentRunFn func(ctx context.Context, params AgentRunParams) AgentRunResult

AgentRunFn runs a sub-agent with the given parameters and returns the result. It is injected by the wiring layer to avoid import cycles between tools and core.

type AgentRunParams 

type AgentRunParams struct {
	CallID            string
	RunID             string
	StepID            string
	Agent             string
	Pattern           string
	Task              string
	Provider          string
	Model             string
	Tools             []string
	MaxSteps          int
	HandoffSchemaName string
	HandoffSchema     json.RawMessage
	WorkspaceDir      string
	StateDir          string
}

AgentRunParams describes the sub-agent invocation.

type AgentRunResult 

type AgentRunResult struct {
	OK          bool
	AgentRunID  string
	Result      string
	Structured  json.RawMessage
	Diagnostics []string
	UsedSteps   int
	UsedTokens  int
	CostUSD     float64
}

AgentRunResult holds the sub-agent's outcome.

type BlobInfo 

type BlobInfo struct {
	CID  string
	Mime string
	Size int64
}

BlobInfo is the subset of the uploadBlob response needed to embed a blob in a record (e.g. app.bsky.embed.images).

type DangerLevel 

type DangerLevel string

DangerLevel classifies how risky a tool operation is. 

const (
	Safe      DangerLevel = "safe"
	Dangerous DangerLevel = "dangerous"
)

type PathTranslator 

type PathTranslator interface {
	ToSandbox(path string) string
	ToVirtual(path string) string
	SanitizeText(text string) string
	SecurePath(path string) (string, bool)
}

PathTranslator defines the subset of core.PathMapper needed by tools.

type Registry 

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

Registry holds registered tools and enforces the enabled allowlist.

func NewRegistry 

func NewRegistry(enabledNames []string) *Registry

NewRegistry creates a registry with the given tool allowlist.

func (*Registry) Disable 

func (r *Registry) Disable(name string)

Disable removes a tool name from the allowlist.

func (*Registry) Effects 

func (r *Registry) Effects(name string) ToolEffects

Effects returns the execution effects metadata for a registered tool.

func (*Registry) Enable 

func (r *Registry) Enable(name string)

Enable marks a tool name as allowed for access once it is registered.

func (*Registry) EnabledTools 

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

EnabledTools returns all enabled Tool objects.

func (*Registry) Get 

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

Get returns an enabled tool by name.

func (*Registry) IsDangerous 

func (r *Registry) IsDangerous(name string) bool

IsDangerous returns true if the named tool is classified as Dangerous.

func (*Registry) IsEnabled 

func (r *Registry) IsEnabled(name string) bool

IsEnabled reports whether the named tool is currently allowlisted.

func (*Registry) List 

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

List returns all enabled tool names.

func (*Registry) Lookup 

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

Lookup returns a registered tool by name, regardless of enabled state.

func (*Registry) MissingEnabledNames 

func (r *Registry) MissingEnabledNames() []string

MissingEnabledNames returns enabled tool names that are not registered.

func (*Registry) Register 

func (r *Registry) Register(t Tool)

Register adds or replaces a tool in the registry.

func (*Registry) RegisterAndEnable 

func (r *Registry) RegisterAndEnable(t Tool)

RegisterAndEnable adds or replaces a tool in the registry and marks it enabled.

func (*Registry) RegisteredTools 

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

RegisteredTools returns all currently registered Tool objects, regardless of enabled state.

func (*Registry) Specs 

func (r *Registry) Specs() []providers.ToolSpec

Specs returns ToolSpec slices for all enabled tools (used to send to provider).

func (*Registry) Unregister 

func (r *Registry) Unregister(name string)

Unregister removes a tool instance from the registry.

func (*Registry) Validate 

func (r *Registry) Validate() error

Validate ensures all enabled tool names are actually registered and have valid surfaces.

type SecretRedactor 

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

SecretRedactor redacts configured secret values from tool-visible text.

func NewSecretRedactor 

func NewSecretRedactor(patterns []string, toolEnv []string) *SecretRedactor

NewSecretRedactor builds a redactor from explicit tool env entries and the parent env values whose names match configured redact patterns.

func (*SecretRedactor) RedactText 

func (r *SecretRedactor) RedactText(text string) string

type Tool 

type Tool interface {
	Name() string
	Description() string
	InputSchema() json.RawMessage
	OutputSchema() json.RawMessage
	DangerLevel() DangerLevel
	Effects() ToolEffects
	Exec(ctx context.Context, call ToolCallContext, args json.RawMessage) (ToolResult, error)
}

Tool is the interface all agent tools implement.

func ATProtoAnonSynth 

func ATProtoAnonSynth(cfg *config.Config) Tool

ATProtoAnonSynth returns the atproto_anon_synth tool.

func ATProtoCommunityDetect 

func ATProtoCommunityDetect(cfg *config.Config) Tool

ATProtoCommunityDetect returns the atproto_community_detect tool.

func ATProtoCreateRecord 

func ATProtoCreateRecord(cfg *config.Config) Tool

func ATProtoDailyDigest 

func ATProtoDailyDigest(cfg *config.Config) Tool

ATProtoDailyDigest returns the daily_digest tool.

func ATProtoEngagementHealth 

func ATProtoEngagementHealth(cfg *config.Config) Tool

ATProtoEngagementHealth returns the engagement_health tool.

func ATProtoFeed 

func ATProtoFeed(cfg *config.Config) Tool

ATProtoFeed returns the atproto_feed tool.

func ATProtoFollowerMomentum 

func ATProtoFollowerMomentum(cfg *config.Config) Tool

ATProtoFollowerMomentum returns the atproto_follower_momentum tool.

func ATProtoGetFollowers 

func ATProtoGetFollowers(cfg *config.Config) Tool

ATProtoGetFollowers returns the atproto_get_followers tool.

func ATProtoGetFollows 

func ATProtoGetFollows(cfg *config.Config) Tool

ATProtoGetFollows returns the atproto_get_follows tool.

func ATProtoGetProfile 

func ATProtoGetProfile(cfg *config.Config) Tool

ATProtoGetProfile returns the atproto_get_profile tool.

func ATProtoGraphExplorer 

func ATProtoGraphExplorer(cfg *config.Config) Tool

ATProtoGraphExplorer returns the atproto_graph_explorer tool.

func ATProtoIndex 

func ATProtoIndex(cfg *config.Config) Tool

ATProtoIndex returns the atproto_index tool.

func ATProtoNotifications 

func ATProtoNotifications(cfg *config.Config) Tool

ATProtoNotifications returns the atproto_notifications tool.

func ATProtoPost 

func ATProtoPost(cfg *config.Config) Tool

ATProtoPost returns the atproto_post tool.

func ATProtoRecall 

func ATProtoRecall(cfg *config.Config) Tool

ATProtoRecall returns the atproto_recall tool.

func ATProtoResolve 

func ATProtoResolve(cfg *config.Config) Tool

ATProtoResolve returns the atproto_resolve tool.

func ATProtoUploadBlob 

func ATProtoUploadBlob(cfg *config.Config) Tool

ATProtoUploadBlob returns the atproto_upload_blob tool.

func ATProtoVibeCheck 

func ATProtoVibeCheck(cfg *config.Config) Tool

ATProtoVibeCheck returns the vibe_check tool.

func BlackboardRead 

func BlackboardRead() Tool

func BlackboardSearch 

func BlackboardSearch() Tool

func BlackboardStore 

func BlackboardStore() Tool

func BlackboardWrite 

func BlackboardWrite() Tool

func CurlFetch 

func CurlFetch() Tool

func FSList 

func FSList() Tool

func FSMkdir 

func FSMkdir() Tool

func FSOutline 

func FSOutline() Tool

func FSRead 

func FSRead() Tool

func FSRenderImage 

func FSRenderImage() Tool

func FSWrite 

func FSWrite() Tool

func Fingerprint 

func Fingerprint() Tool

func GitCommit 

func GitCommit() Tool

func GitDiff 

func GitDiff() Tool

func GitPush 

func GitPush() Tool

func GitStatus 

func GitStatus() Tool

func InspectTool 

func InspectTool() Tool

func NewAgent 

func NewAgent(runFn AgentRunFn) Tool

NewAgent creates a new agent tool instance. The runFn callback is invoked at Exec time to run the child loop.

func NewDeepResearch 

func NewDeepResearch(runFn AgentRunFn) Tool

NewDeepResearch creates a web research harness that fans out Brave searches, fetches sources, asks model/sub-agent perspectives, and returns a cited report.

func NewDispatch 

func NewDispatch(runFn AgentRunFn, listAgents func() []string) Tool

NewDispatch creates a role-based dispatch tool.

func NewOrchestrate 

func NewOrchestrate(runFn AgentRunFn, listAgents func() []string) Tool

NewOrchestrate creates a coordination tool for fanout/pipeline dispatch.

func NewReflect 

func NewReflect() Tool

NewReflect creates a new 'reflect' tool.

func NewsFetch 

func NewsFetch() Tool

func PatchApply 

func PatchApply() Tool

func ProjectSearch 

func ProjectSearch() Tool

func ProvenanceLookup 

func ProvenanceLookup() Tool

func SemBlame 

func SemBlame() Tool

func SemDiff 

func SemDiff() Tool

func SemImpact 

func SemImpact() Tool

func Sh 

func Sh() Tool

func SourceCode 

func SourceCode() Tool

SourceCode creates a read-only dependency/package source inspection tool.

func Translate 

func Translate() Tool

func WebExtract 

func WebExtract() Tool

func WebSearch 

func WebSearch() Tool

func Wiki 

func Wiki() Tool

type ToolCallContext 

type ToolCallContext struct {
	RunID            string
	StepID           string
	CallID           string
	WorkspaceDir     string // host path to active workspace (sandbox if enabled)
	HostWorkspaceDir string // original source workspace for shared state across runs
	StateDir         string // host path for run-scoped mutable state
	TimeoutMS        int
	Provider         providers.Provider
	EmbedProvider    providers.Provider  // dedicated embedding provider; falls back to Provider if nil
	Registry         *Registry           // access to other enabled tools
	Session          executor.Session    // active sandbox session
	Mapper           PathTranslator      // bidirectional path mapping
	Env              []string            // explicit environment passthrough entries (KEY=value)
	RedactText       func(string) string // redacts secret values from tool-visible output
	EmitOutputDelta  func(stream, text string) error
}

ToolCallContext provides runtime context to a tool execution.

type ToolEffects 

type ToolEffects struct {
	MutatesWorkspace   bool
	MutatesRunState    bool
	NeedsNetwork       bool
	ExternalSideEffect bool
}

ToolEffects captures execution semantics independent of confirmation risk.

type ToolResult 

type ToolResult struct {
	OK         bool            `json:"ok"`
	Output     string          `json:"output"`
	Stdout     string          `json:"stdout,omitempty"`
	Stderr     string          `json:"stderr,omitempty"`
	Structured json.RawMessage `json:"structured,omitempty"`
	TaintLevel string          `json:"taint_level,omitempty"`
	DurationMS int64           `json:"duration_ms"`
}

ToolResult holds the output of a tool execution.

func CapToolResult 

func CapToolResult(r ToolResult) ToolResult

CapToolResult applies DefaultToolResultChars to a ToolResult's Output and Stdout fields. Convenience wrapper for tools that build large string/JSON outputs and want consistent tool-layer truncation.

Source Files

View all Source files

Directories

Path Synopsis

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.