tools

package
v0.3.9 Latest Latest
Warning

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

 Go to latest Published: Jun 14, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Overview

Package tools defines local tool registration, permission checks, and execution.

Registry is safe for concurrent definition reads and tool execution. Registration validates tool names, effects, permission modes, and reserved control names. Strictly safe read-only tools may omit Permission.Mode and are exposed as allowed tools. Mutating, destructive, open-world, shell, and network tools must declare explicit permission behavior. PermissionDeny tools remain callable only as explicit host-side disabled tools and are not exposed to providers. Parallel scheduling is controlled by Definition.ParallelSafe, which is only valid for strictly read-only tools.

Index

Constants

View Source 
const (
	DefaultToolVisibleMaxBytes = 64 * 1024
	DefaultToolVisibleMaxLines = 0
	DefaultToolOutputStrategy  = OutputTail
	DefaultPreserveFull        = true
	DefaultArtifactKind        = "tool_output"
	DefaultArtifactMIME        = "text/plain; charset=utf-8"
)
View Source 
const (
	ControlAskUser      = "ask_user"
	ControlTaskComplete = "task_complete"
)

Variables

View Source 
var (
	PermissionDecisionAllow = PermissionDecision{State: PermissionDecisionStateAllow}
	PermissionDecisionDeny  = PermissionDecision{State: PermissionDecisionStateDeny}
)
View Source 
var ErrDuplicate = errors.New("duplicate tool name")
View Source 
var ErrInvalid = errors.New("invalid tool")
View Source 
var ErrRejected = errors.New("tool call rejected")
View Source 
var ErrSchema = errors.New("schema validation failed")

Functions

func Array 

func Array(items map[string]any, description string) map[string]any

func Boolean 

func Boolean(description string) map[string]any

func Enum 

func Enum(values ...string) map[string]any

func Integer 

func Integer(description string) map[string]any

func InvalidArgumentsText 

func InvalidArgumentsText(name string, err error) string

func IsReservedName 

func IsReservedName(name string) bool

func NormalizeInputSchema 

func NormalizeInputSchema(schema map[string]any) (map[string]any, error)

func Nullable 

func Nullable(schema map[string]any) map[string]any

func Number 

func Number(description string) map[string]any

func StrictObject 

func StrictObject(properties map[string]any, required []string) map[string]any

func String 

func String(description string) map[string]any

func Validate 

func Validate(schema map[string]any, raw []byte) (map[string]any, error)

func ValidateStructured 

func ValidateStructured(schema map[string]any, value any) error

Types

type ApprovalRequest 

type ApprovalRequest struct {
	ApprovalID    string
	ID            string
	Name          string
	Args          string
	ArgsHash      string
	ValidatedArgs any
	Resources     []ResourceRef
	Effects       []Effect
	Labels        map[string]string
	HostContext   map[string]string
	ReadOnly      bool
	Destructive   bool
	OpenWorld     bool
}

type Approver 

type Approver func(context.Context, ApprovalRequest) (PermissionDecision, error)

type ArtifactRef added in v0.3.0 

type ArtifactRef struct {
	ID        string `json:"id,omitempty"`
	SafeLabel string `json:"safe_label,omitempty"`
	URL       string `json:"url,omitempty"`
	Kind      string `json:"kind,omitempty"`
	MIME      string `json:"mime,omitempty"`
	SizeBytes int64  `json:"size_bytes,omitempty"`
	SHA256    string `json:"sha256,omitempty"`
}

type ArtifactStore added in v0.3.0 

type ArtifactStore interface {
	PutToolOutput(context.Context, ToolOutputArtifact) (ArtifactRef, error)
}

type Definition 

type Definition struct {
	Name         string
	Title        string
	Description  string
	InputSchema  map[string]any
	OutputSchema map[string]any
	Activity     func(Invocation[any]) (*observation.ActivityPresentation, error)

	Effects      []Effect
	ReadOnly     bool
	Destructive  bool
	OpenWorld    bool
	ParallelSafe bool

	Permission   PermissionSpec
	OutputPolicy OutputPolicy
	Annotations  map[string]any
}

func ValidateDefinition 

func ValidateDefinition(def Definition) (Definition, error)

type Effect 

type Effect string
const (
	EffectRead    Effect = "read"
	EffectWrite   Effect = "write"
	EffectShell   Effect = "shell"
	EffectNetwork Effect = "network"
)

type Invocation 

type Invocation[T any] struct {
	CallID        string
	Name          string
	RawArgs       string
	Args          T
	RunID         string
	ThreadID      string
	TurnID        string
	PromptScopeID string
	Step          int
	Labels        map[string]string
	HostContext   map[string]string
}

type OutputPolicy 

type OutputPolicy struct {
	VisibleMaxBytes int
	VisibleMaxLines int
	Strategy        OutputStrategy
	PreserveFull    bool
	PreserveFullSet bool
	ArtifactKind    string
	ArtifactMIME    string
}

func DefaultOutputPolicy 

func DefaultOutputPolicy() OutputPolicy

func MergeOutputPolicy 

func MergeOutputPolicy(base OutputPolicy, override *OutputPolicy) OutputPolicy

func NormalizeOutputPolicy 

func NormalizeOutputPolicy(policy OutputPolicy) OutputPolicy

type OutputProjection 

type OutputProjection struct {
	VisibleText   string
	Truncated     bool
	OriginalBytes int
	VisibleBytes  int
	OriginalLines int
	VisibleLines  int
	Strategy      OutputStrategy
	ContentSHA256 string
	FullOutput    *ArtifactRef
}

func BuildOutputProjection 

func BuildOutputProjection(ctx context.Context, result Result, policy OutputPolicy, store ArtifactStore) (OutputProjection, error)

type OutputStrategy 

type OutputStrategy string
const (
	OutputHead OutputStrategy = "head"
	OutputTail OutputStrategy = "tail"
)

type PermissionDecision 

type PermissionDecision struct {
	State  PermissionDecisionState
	Reason string
}

func PermissionDecisionDenied 

func PermissionDecisionDenied(reason string) PermissionDecision

func (PermissionDecision) Allowed 

func (d PermissionDecision) Allowed() bool

func (PermissionDecision) RejectionReason 

func (d PermissionDecision) RejectionReason() string

type PermissionDecisionState 

type PermissionDecisionState string
const (
	PermissionDecisionStateAllow PermissionDecisionState = "allow"
	PermissionDecisionStateDeny  PermissionDecisionState = "deny"
)

type PermissionMode 

type PermissionMode string
const (
	PermissionAllow PermissionMode = "allow"
	PermissionAsk   PermissionMode = "ask"
	PermissionDeny  PermissionMode = "deny"
)

type PermissionSpec 

type PermissionSpec struct {
	Mode          PermissionMode
	ResourceKinds []string
}

type Registry 

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

func NewRegistry 

func NewRegistry(items ...Tool) *Registry

func NewRegistryE 

func NewRegistryE(items ...Tool) (*Registry, error)

func (*Registry) ActivityForCall added in v0.3.7 

func (r *Registry) ActivityForCall(call ToolCall, opts RunOptions) (*observation.ActivityPresentation, error)

func (*Registry) Definition 

func (r *Registry) Definition(name string) (Definition, bool)

func (*Registry) Definitions 

func (r *Registry) Definitions() []ToolDefinition

func (*Registry) ExposedDefinitions 

func (r *Registry) ExposedDefinitions() []ToolDefinition

func (*Registry) IsParallelSafe 

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

func (*Registry) OutputPolicyFor 

func (r *Registry) OutputPolicyFor(name string) OutputPolicy

func (*Registry) Register 

func (r *Registry) Register(t Tool) error

func (*Registry) Run 

func (r *Registry) Run(ctx context.Context, call ToolCall, approver Approver) Result

func (*Registry) RunBatch 

func (r *Registry) RunBatch(ctx context.Context, calls []ToolCall, approver Approver) []Result

func (*Registry) RunBatchWithOptions 

func (r *Registry) RunBatchWithOptions(ctx context.Context, calls []ToolCall, approver Approver, opts RunOptions) []Result

func (*Registry) RunWithOptions 

func (r *Registry) RunWithOptions(ctx context.Context, call ToolCall, approver Approver, opts RunOptions) Result

type ResourceRef 

type ResourceRef struct {
	Kind  string
	Value string
}

type Result 

type Result struct {
	CallID       string
	Name         string
	Title        string
	Text         string
	Structured   map[string]any
	Metadata     map[string]any
	Activity     *observation.ActivityPresentation
	Artifacts    []ArtifactRef
	OutputPolicy *OutputPolicy
	IsError      bool
}

func ErrorResult 

func ErrorResult(callID, name, text string) Result

func (Result) MetadataInt 

func (r Result) MetadataInt(key string) int

func (Result) MetadataString 

func (r Result) MetadataString(key string) string

type RunOptions 

type RunOptions struct {
	RunID         string
	ThreadID      string
	TurnID        string
	PromptScopeID string
	Step          int
	Labels        map[string]string
	HostContext   map[string]string
}

type Tool 

type Tool struct {
	Definition Definition
	// contains filtered or unexported fields
}

func Define 

func Define[T any](
	def Definition,
	decode func([]byte) (T, error),
	resources func(Invocation[T]) ([]ResourceRef, error),
	handler func(context.Context, Invocation[T]) (Result, error),
) Tool

type ToolCall added in v0.3.0 

type ToolCall struct {
	ID        string
	Name      string
	Args      string
	Reasoning string
}

type ToolDefinition added in v0.3.0 

type ToolDefinition struct {
	Name         string
	Title        string
	Description  string
	InputSchema  map[string]any
	OutputSchema map[string]any
	Strict       bool
	Annotations  map[string]any
}

type ToolOutputArtifact added in v0.3.0 

type ToolOutputArtifact struct {
	RunID         string         `json:"run_id,omitempty"`
	ThreadID      string         `json:"thread_id,omitempty"`
	TurnID        string         `json:"turn_id,omitempty"`
	PromptScopeID string         `json:"prompt_scope_id,omitempty"`
	Step          int            `json:"step,omitempty"`
	CallID        string         `json:"call_id,omitempty"`
	ToolName      string         `json:"tool_name,omitempty"`
	Text          string         `json:"text,omitempty"`
	MIME          string         `json:"mime,omitempty"`
	Kind          string         `json:"kind,omitempty"`
	Metadata      map[string]any `json:"metadata,omitempty"`
}

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.