tools

package module
v0.2.2 Latest Latest
Warning

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

 Go to latest Published: Aug 11, 2026 License: Apache-2.0 Imports: 12 Imported by: 0

Documentation

Overview

Package tools provides a provider-neutral tool catalog and portable tools.

Index

Constants

View Source 
const (
	ToolSourceUnknown   = "unknown"
	ToolSourceBuiltin   = "builtin"
	ToolSourceExtension = "extension"
	ToolSourceProject   = "project"
	ToolSourceCustom    = "custom"
)

Tool source values describe where a catalog entry is owned. They are descriptive metadata only; they do not grant authorization or select a backend.

View Source 
const (
	ToolResultMiddlewareModeObserveOnly = "observe_only"

	ToolResultMiddlewareReasonLargeResult           = "large_result"
	ToolResultMiddlewareReasonRuntimeGuardTruncated = "runtime_guard_truncated"
	ToolResultMiddlewareReasonSensitiveKeyPresent   = "sensitive_key_present"
	ToolResultMiddlewareReasonEmbeddedBinaryPayload = "embedded_binary_payload"

	ToolResultMiddlewareStrategySummarizeWithRawRef = "summarize_with_raw_ref"
	ToolResultMiddlewareStrategyPreserveRawArtifact = "preserve_raw_artifact"
	ToolResultMiddlewareStrategyRedactSensitiveKeys = "redact_sensitive_keys"
	ToolResultMiddlewareStrategyExtractArtifactRef  = "extract_artifact_ref"
)
View Source 
const (
	ToolResultMiddlewareModeControlledTransform = "controlled_transform"

	ToolResultTransformReasonMissingRawResultRef = "missing_raw_result_ref"
)

Variables

This section is empty.

Functions

func AppendToolResultMiddlewareTelemetryAttrs 

func AppendToolResultMiddlewareTelemetryAttrs(attrs map[string]any, event ToolResultMiddlewareEvent) map[string]any

func AppendToolResultTransformTelemetryAttrs 

func AppendToolResultTransformTelemetryAttrs(attrs map[string]any, result ToolResultTransformResult) map[string]any

func NormalizeToolName 

func NormalizeToolName(name string) string

NormalizeToolName returns the stable lower-case catalog name and applies the two legacy aliases already accepted by AgentX hosts.

func SanitizeToolDefinitionForBackendCompatibility 

func SanitizeToolDefinitionForBackendCompatibility(def types.Tool) types.Tool

func SanitizeToolDefinitionsForBackendCompatibility 

func SanitizeToolDefinitionsForBackendCompatibility(defs []types.Tool) []types.Tool

SanitizeToolDefinitionsForBackendCompatibility normalizes tool schemas before they reach model/provider request assembly. It keeps the canonical tool owner unchanged while making the final exposed schema shape backend-friendly.

func SortByName 

func SortByName(definitions []toolcontract.Definition)

SortByName sorts definitions by their normalized function name.

func ToolSessionIDFromContext 

func ToolSessionIDFromContext(ctx context.Context) string

ToolSessionIDFromContext returns the normalized session identity, if any.

func WithToolRuntimeNetworkGuard 

func WithToolRuntimeNetworkGuard(ctx context.Context, guard RuntimeNetworkGuard) context.Context

WithToolRuntimeNetworkGuard returns a context carrying normalized, host-selected network overrides. An empty guard is a no-op.

func WithToolSessionID 

func WithToolSessionID(ctx context.Context, sessionID string) context.Context

WithToolSessionID returns a context carrying the normalized session identity. A nil context or blank identity is preserved unchanged.

Types

type ChainExecutor 

type ChainExecutor struct {
	Executors []toolcontract.Executor
}

ChainExecutor dispatches calls across multiple executors. It falls back only when the current executor does not know the tool.

func (ChainExecutor) Definitions 

func (c ChainExecutor) Definitions() []toolcontract.Definition

func (ChainExecutor) Execute 

func (c ChainExecutor) Execute(ctx context.Context, call toolcontract.Call) (toolcontract.Result, error)

type Executor 

type Executor = toolcontract.Executor

Executor executes tool calls.

func Ensure 

func Ensure(exec Executor) Executor

Ensure returns exec or a new empty Registry when exec is nil.

type Handler 

type Handler = toolcontract.Handler

Handler executes one registered tool.

type OptionalBool 

type OptionalBool struct {
	Set   bool
	Value bool
}

OptionalBool distinguishes an explicit false value from no override.

type OptionalInts 

type OptionalInts struct {
	Set    bool
	Values []int
}

OptionalInts distinguishes an explicitly empty list from no override.

type OptionalStrings 

type OptionalStrings struct {
	Set    bool
	Values []string
}

OptionalStrings distinguishes an explicitly empty list from no override.

type Registry 

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

Registry is a concurrency-safe catalog and executor.

func NewRegistry 

func NewRegistry() *Registry

NewRegistry constructs an empty Registry.

func (*Registry) Definitions 

func (r *Registry) Definitions() []toolcontract.Definition

Definitions returns a stable, name-sorted snapshot.

func (*Registry) Execute 

func (r *Registry) Execute(ctx context.Context, call toolcontract.Call) (toolcontract.Result, error)

Execute invokes a registered handler, including deterministic name repair.

func (*Registry) Register 

func (r *Registry) Register(definition toolcontract.Definition, handler Handler)

Register associates a function name with its handler. Empty or nil values are ignored.

func (*Registry) Reset 

func (r *Registry) Reset()

Reset removes all entries and advances the mutation version.

func (*Registry) Version 

func (r *Registry) Version() uint64

Version reports the catalog mutation version.

type RuntimeNetworkGuard 

type RuntimeNetworkGuard struct {
	WebSearchAllowPrivateHosts    OptionalBool
	WebSearchTrustedEnvProxy      OptionalBool
	WebSearchAllowCIDRs           OptionalStrings
	WebSearchDenyCIDRs            OptionalStrings
	WebSearchAllowPorts           OptionalInts
	WebSearchDenyPorts            OptionalInts
	WebFetchAllowPrivateHosts     OptionalBool
	WebFetchTrustedEnvProxy       OptionalBool
	WebFetchAllowCIDRs            OptionalStrings
	WebFetchDenyCIDRs             OptionalStrings
	WebFetchAllowPorts            OptionalInts
	WebFetchDenyPorts             OptionalInts
	HTTPRequestAllowPrivateHosts  OptionalBool
	HTTPRequestTrustedEnvProxy    OptionalBool
	HTTPRequestAllowCIDRs         OptionalStrings
	HTTPRequestDenyCIDRs          OptionalStrings
	HTTPRequestAllowPorts         OptionalInts
	HTTPRequestDenyPorts          OptionalInts
	BrowserProxyAllowPrivateHosts OptionalBool
	BrowserProxyTrustedEnvProxy   OptionalBool
	BrowserProxyAllowCIDRs        OptionalStrings
	BrowserProxyDenyCIDRs         OptionalStrings
	BrowserProxyAllowPorts        OptionalInts
	BrowserProxyDenyPorts         OptionalInts
	NodesGatewayAllowPrivateHosts OptionalBool
	NodesGatewayTrustedEnvProxy   OptionalBool
	NodesGatewayAllowCIDRs        OptionalStrings
	NodesGatewayDenyCIDRs         OptionalStrings
	NodesGatewayAllowPorts        OptionalInts
	NodesGatewayDenyPorts         OptionalInts
}

RuntimeNetworkGuard carries host-selected per-run network-policy overrides. It does not decide defaults and it does not perform network I/O.

func ToolRuntimeNetworkGuardFromContext 

func ToolRuntimeNetworkGuardFromContext(ctx context.Context) (RuntimeNetworkGuard, bool)

ToolRuntimeNetworkGuardFromContext returns normalized network overrides.

type ToolContentClassifier 

type ToolContentClassifier func(toolName string) (externalContent, untrustedContent bool)

ToolContentClassifier classifies the trust boundary of one tool result. Implementations must be deterministic and must not perform side effects.

type ToolMetadata 

type ToolMetadata struct {
	Plugin          string
	Groups          []string
	Type            string
	Source          string
	Capabilities    []string
	AuditTags       []string
	RiskProfile     string
	ReadOnly        *bool
	ConcurrencySafe *bool
	Destructive     *bool
}

ToolMetadata describes a tool catalog entry without owning authorization, approval, sandbox, credential, or backend policy.

Pointer booleans preserve the distinction between an explicit false value and an unspecified hint.

type ToolNameError 

type ToolNameError struct {
	Requested     string
	NormalizedKey string
	Candidates    []string
	Ambiguous     bool
	Reason        string
}

ToolNameError reports a missing or ambiguous tool name.

func AsToolNameError 

func AsToolNameError(err error) (*ToolNameError, bool)

AsToolNameError extracts a typed tool-name error.

func NewToolNameError 

func NewToolNameError(requested string, resolution ToolNameRepairResolution) *ToolNameError

NewToolNameError constructs a defensive typed error.

func (*ToolNameError) Code 

func (e *ToolNameError) Code() string

Code returns a stable error classification.

func (*ToolNameError) Error 

func (e *ToolNameError) Error() string

func (*ToolNameError) Repairable 

func (e *ToolNameError) Repairable() bool

Repairable reports whether the caller can retry with one suggested candidate.

type ToolNameRepairResolution 

type ToolNameRepairResolution struct {
	Requested     string
	Name          string
	NormalizedKey string
	Candidates    []string
	Repaired      bool
	Ambiguous     bool
	Reason        string
	Confidence    string
}

ToolNameRepairResolution describes deterministic normalization and candidate selection.

func RepairToolName 

func RepairToolName(requested string, registered []string) ToolNameRepairResolution

RepairToolName resolves a model-emitted name against registered names.

type ToolResultArgumentsSummary 

type ToolResultArgumentsSummary struct {
	Bytes            int      `json:"bytes,omitempty"`
	Chars            int      `json:"chars,omitempty"`
	Fingerprint      string   `json:"fingerprint,omitempty"`
	JSONValid        bool     `json:"json_valid,omitempty"`
	JSONTopLevelKeys []string `json:"json_top_level_keys,omitempty"`
}

type ToolResultContentSummary 

type ToolResultContentSummary struct {
	Bytes              int      `json:"bytes"`
	Chars              int      `json:"chars"`
	Lines              int      `json:"lines"`
	LooksBinary        bool     `json:"looks_binary,omitempty"`
	JSONValid          bool     `json:"json_valid,omitempty"`
	JSONTopLevelKeys   []string `json:"json_top_level_keys,omitempty"`
	SensitiveKeyHits   []string `json:"sensitive_key_hits,omitempty"`
	EmbeddedBinaryKeys []string `json:"embedded_binary_keys,omitempty"`
	OriginalBytes      int      `json:"original_bytes,omitempty"`
	KeptBytes          int      `json:"kept_bytes,omitempty"`
	Truncated          bool     `json:"truncated,omitempty"`
	GuardStrategy      string   `json:"guard_strategy,omitempty"`
}

type ToolResultMiddlewareEvent 

type ToolResultMiddlewareEvent struct {
	ToolName              string                                `json:"tool_name"`
	Mode                  string                                `json:"mode"`
	SessionID             string                                `json:"session_id,omitempty"`
	RunID                 string                                `json:"run_id,omitempty"`
	ObservationOnly       bool                                  `json:"observation_only"`
	IsError               bool                                  `json:"is_error,omitempty"`
	ExternalContent       bool                                  `json:"external_content,omitempty"`
	UntrustedContent      bool                                  `json:"untrusted_content,omitempty"`
	Arguments             ToolResultArgumentsSummary            `json:"arguments,omitempty"`
	RawResultRef          string                                `json:"raw_result_ref,omitempty"`
	ArtifactRefs          []string                              `json:"artifact_refs,omitempty"`
	Content               ToolResultContentSummary              `json:"content"`
	OutputSchema          *ToolResultOutputSchema               `json:"output_schema,omitempty"`
	TerminalObservation   *ToolResultTerminalObservationSummary `json:"terminal_observation,omitempty"`
	Details               []string                              `json:"details,omitempty"`
	WouldTransform        bool                                  `json:"would_transform"`
	WouldTransformReasons []string                              `json:"would_transform_reasons,omitempty"`
	SuggestedStrategies   []string                              `json:"suggested_strategies,omitempty"`
}

func BuildToolResultMiddlewareEvent 

func BuildToolResultMiddlewareEvent(input ToolResultMiddlewareInput) ToolResultMiddlewareEvent

type ToolResultMiddlewareInput 

type ToolResultMiddlewareInput struct {
	ToolName            string
	SessionID           string
	RunID               string
	Arguments           string
	Output              string
	OutputSchema        map[string]any
	RawResultRef        string
	ArtifactRefs        []string
	IsError             bool
	OutputOriginalBytes int
	OutputKeptBytes     int
	OutputTruncated     bool
	OutputGuardStrategy string
	LargeResultBytes    int
	LargeResultLines    int
	// ClassifyContent lets a Host preserve product-specific trust classification
	// without moving browser, document, process or network policy into this module.
	ClassifyContent ToolContentClassifier
}

type ToolResultOutputSchema 

type ToolResultOutputSchema struct {
	Present                bool     `json:"present"`
	Closed                 bool     `json:"closed"`
	PropertyCount          int      `json:"property_count,omitempty"`
	Required               []string `json:"required,omitempty"`
	MatchedTopLevelKeys    []string `json:"matched_top_level_keys,omitempty"`
	MissingRequired        []string `json:"missing_required,omitempty"`
	UnexpectedTopLevelKeys []string `json:"unexpected_top_level_keys,omitempty"`
	Drift                  bool     `json:"drift"`
}

type ToolResultTerminalObservationSummary 

type ToolResultTerminalObservationSummary struct {
	Present        bool   `json:"present"`
	Kind           string `json:"kind,omitempty"`
	Visibility     string `json:"visibility,omitempty"`
	Surface        string `json:"surface,omitempty"`
	Action         string `json:"action,omitempty"`
	DisplayCommand string `json:"display_command,omitempty"`
	UserVisible    bool   `json:"user_visible,omitempty"`
	Reason         string `json:"reason,omitempty"`
}

type ToolResultTransformInput 

type ToolResultTransformInput struct {
	Event        ToolResultMiddlewareEvent
	Output       string
	RawResultRef string
	ArtifactRefs []string
}

type ToolResultTransformResult 

type ToolResultTransformResult struct {
	Applied        bool                        `json:"applied"`
	Mode           string                      `json:"mode"`
	Output         string                      `json:"output"`
	RawResultRef   string                      `json:"raw_result_ref,omitempty"`
	ArtifactRefs   []string                    `json:"artifact_refs,omitempty"`
	Reasons        []string                    `json:"reasons,omitempty"`
	Strategies     []string                    `json:"strategies,omitempty"`
	Details        []string                    `json:"details,omitempty"`
	ErrorPreserved bool                        `json:"error_preserved,omitempty"`
	Summary        *ToolResultTransformSummary `json:"summary,omitempty"`
}

func BuildControlledToolResultTransform 

func BuildControlledToolResultTransform(input ToolResultTransformInput) ToolResultTransformResult

type ToolResultTransformSummary 

type ToolResultTransformSummary struct {
	ToolName           string                  `json:"tool_name,omitempty"`
	ContentBytes       int                     `json:"content_bytes,omitempty"`
	ContentChars       int                     `json:"content_chars,omitempty"`
	ContentLines       int                     `json:"content_lines,omitempty"`
	OriginalBytes      int                     `json:"original_bytes,omitempty"`
	KeptBytes          int                     `json:"kept_bytes,omitempty"`
	Truncated          bool                    `json:"truncated,omitempty"`
	GuardStrategy      string                  `json:"guard_strategy,omitempty"`
	JSONValid          bool                    `json:"json_valid,omitempty"`
	JSONTopLevelKeys   []string                `json:"json_top_level_keys,omitempty"`
	SensitiveKeyHits   []string                `json:"sensitive_key_hits,omitempty"`
	EmbeddedBinaryKeys []string                `json:"embedded_binary_keys,omitempty"`
	ExternalContent    bool                    `json:"external_content,omitempty"`
	UntrustedContent   bool                    `json:"untrusted_content,omitempty"`
	RawResultRef       string                  `json:"raw_result_ref,omitempty"`
	ArtifactRefs       []string                `json:"artifact_refs,omitempty"`
	OutputSchema       *ToolResultOutputSchema `json:"output_schema,omitempty"`
}

Source Files

View all Source files

Directories

Path Synopsis
Package agent provides the model-facing Task, Session child and Subagent tool contract over a Host-owned durable lifecycle.
 Package agent provides the model-facing Task, Session child and Subagent tool contract over a Host-owned durable lifecycle.
Package diffs implements the portable text-only diffs tool.
 Package diffs implements the portable text-only diffs tool.
Package filesystem provides portable filesystem tool coordination.
 Package filesystem provides portable filesystem tool coordination.
Package httprequest provides portable HTTP tool request/response coordination.
 Package httprequest provides portable HTTP tool request/response coordination.
Package llmtask provides one bounded, model-only JSON subtask tool.
 Package llmtask provides one bounded, model-only JSON subtask tool.
Package memory provides portable memory search/get tool coordination.
 Package memory provides portable memory search/get tool coordination.
Package message provides the portable AgentX channel message tool.
 Package message provides the portable AgentX channel message tool.
Package process provides an explicit, bounded local process adapter.
 Package process provides an explicit, bounded local process adapter.
Package scheduler provides portable scheduled-command tool coordination.
 Package scheduler provides portable scheduled-command tool coordination.
Package videoframes provides an explicit, opt-in local video-frame adapter.
 Package videoframes provides an explicit, opt-in local video-frame adapter.
web
Package web provides portable Web Search, Fetch, OpenPage and FindInPage tools.
 Package web provides portable Web Search, Fetch, OpenPage and FindInPage tools.
retrieval

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.