tools

package
v0.6.13 Latest Latest
Warning

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

 Go to latest Published: May 29, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ErrFromToolError 

func ErrFromToolError(toolErr *ToolError) error

func InvocationRiskInfo 

func InvocationRiskInfo(toolName string, args map[string]any) (string, string)

func InvocationRiskLabel 

func InvocationRiskLabel(toolName string, args map[string]any) string

func IsDangerousInvocation 

func IsDangerousInvocation(toolName string, args map[string]any) bool

func IsMutating 

func IsMutating(toolName string) bool

func IsMutatingForInvocation 

func IsMutatingForInvocation(toolName string, args map[string]any) bool

func MergeNormalizedArgs 

func MergeNormalizedArgs(args map[string]any, normalized map[string]any) map[string]any

func NormalizeTerminalCommand 

func NormalizeTerminalCommand(command string) string

func RequiresApproval 

func RequiresApproval(toolName string) bool

func RequiresApprovalForInvocation 

func RequiresApprovalForInvocation(toolName string, args map[string]any) bool

func ShouldRetryWithNormalizedArgs 

func ShouldRetryWithNormalizedArgs(toolErr *ToolError) bool

ShouldRetryWithNormalizedArgs returns true when the caller should perform one deterministic retry.

func ValidatePresentationSpec added in v0.6.10 

func ValidatePresentationSpec(toolName string, spec ToolPresentationSpec) error

Types

type Definition 

type Definition struct {
	Name             string
	Mutating         bool
	RequiresApproval bool
	Presentation     ToolPresentationSpec
}

Definition describes built-in tool properties used by policies.

func LookupDefinition 

func LookupDefinition(toolName string) (Definition, bool)

type ErrorCode 

type ErrorCode string

ErrorCode is a stable, machine-readable tool error code. 

const (
	ErrorCodeNotFound         ErrorCode = "NOT_FOUND"
	ErrorCodeInvalidPath      ErrorCode = "INVALID_PATH"
	ErrorCodeInvalidArguments ErrorCode = "INVALID_ARGUMENTS"
	ErrorCodePermissionDenied ErrorCode = "PERMISSION_DENIED"
	ErrorCodeTimeout          ErrorCode = "TIMEOUT"
	ErrorCodeCanceled         ErrorCode = "CANCELED"
	ErrorCodeUnknown          ErrorCode = "UNKNOWN"
)

type Event 

type Event struct {
	Kind     EventKind      `json:"kind"`
	RunID    string         `json:"run_id"`
	ToolID   string         `json:"tool_id"`
	ToolName string         `json:"tool_name"`
	AtUnixMs int64          `json:"at_unix_ms"`
	Payload  map[string]any `json:"payload,omitempty"`
}

Event is emitted by the orchestrator and can be forwarded to runtime streams / storage.

func NewEvent 

func NewEvent(kind EventKind, runID string, toolID string, toolName string, payload map[string]any) Event

type EventKind 

type EventKind string

EventKind is a normalized tool lifecycle event type. 

const (
	EventKindBegin    EventKind = "tool.begin"
	EventKindEnd      EventKind = "tool.end"
	EventKindError    EventKind = "tool.error"
	EventKindRecovery EventKind = "tool.recovery"
)

type Invocation 

type Invocation struct {
	ToolName     string
	Args         map[string]any
	WorkingDir   string
	AgentHomeDir string
}

Invocation carries the minimum context required for error classification and retry hints.

type ResultStatus 

type ResultStatus string

ResultStatus is the normalized status returned by the Go tool runtime. 

const (
	ResultStatusSuccess    ResultStatus = "success"
	ResultStatusError      ResultStatus = "error"
	ResultStatusRecovering ResultStatus = "recovering"
)

type TerminalCommandProfile 

type TerminalCommandProfile struct {
	Risk              TerminalCommandRisk
	NormalizedCommand string
	Effects           []string
	Reason            string
}

func InvocationCommandProfile 

func InvocationCommandProfile(toolName string, args map[string]any) TerminalCommandProfile

func ProfileTerminalCommand 

func ProfileTerminalCommand(command string) TerminalCommandProfile

type TerminalCommandRisk 

type TerminalCommandRisk string
const (
	TerminalCommandRiskReadonly  TerminalCommandRisk = "readonly"
	TerminalCommandRiskMutating  TerminalCommandRisk = "mutating"
	TerminalCommandRiskDangerous TerminalCommandRisk = "dangerous"
)

func ClassifyTerminalCommandRisk 

func ClassifyTerminalCommandRisk(command string) TerminalCommandRisk

type ToolError 

type ToolError struct {
	Code           ErrorCode      `json:"code"`
	Message        string         `json:"message"`
	Retryable      bool           `json:"retryable,omitempty"`
	SuggestedFixes []string       `json:"suggested_fixes,omitempty"`
	NormalizedArgs map[string]any `json:"normalized_args,omitempty"`
	Meta           map[string]any `json:"meta,omitempty"`
}

ToolError carries structured tool failure metadata.

func ClassifyError 

func ClassifyError(inv Invocation, err error) *ToolError

func (*ToolError) Normalize 

func (e *ToolError) Normalize()

type ToolGroupingPolicy added in v0.6.10 

type ToolGroupingPolicy struct {
	Enabled        bool     `json:"enabled"`
	GroupKey       string   `json:"group_key"`
	MergeWindowMS  int64    `json:"merge_window_ms,omitempty"`
	MaxInlineItems int      `json:"max_inline_items,omitempty"`
	TargetFields   []string `json:"target_fields,omitempty"`
}

ToolGroupingPolicy describes how adjacent tool activity can be grouped in chat.

type ToolPresentationKind added in v0.6.10 

type ToolPresentationKind string

ToolPresentationKind classifies a tool for compact chat activity rendering. 

const (
	ToolPresentationContext     ToolPresentationKind = "context"
	ToolPresentationCommand     ToolPresentationKind = "command"
	ToolPresentationMutation    ToolPresentationKind = "mutation"
	ToolPresentationResearch    ToolPresentationKind = "research"
	ToolPresentationTodo        ToolPresentationKind = "todo"
	ToolPresentationDelegation  ToolPresentationKind = "delegation"
	ToolPresentationInteraction ToolPresentationKind = "interaction"
	ToolPresentationSignal      ToolPresentationKind = "signal"
)

type ToolPresentationSpec added in v0.6.10 

type ToolPresentationSpec struct {
	Kind           ToolPresentationKind `json:"kind"`
	Risk           string               `json:"risk"` // readonly|mutating|approval|blocking
	Renderer       string               `json:"renderer"`
	Grouping       ToolGroupingPolicy   `json:"grouping"`
	DetailKinds    []string             `json:"detail_kinds,omitempty"`
	Redaction      ToolRedactionSpec    `json:"redaction,omitempty"`
	SummaryVersion int                  `json:"summary_version"`
}

ToolPresentationSpec is the runtime-owned display contract consumed by the chat UI.

func MustPresentationSpec added in v0.6.10 

func MustPresentationSpec(toolName string) ToolPresentationSpec

func PresentationSpec added in v0.6.10 

func PresentationSpec(toolName string) (ToolPresentationSpec, bool)

type ToolRedactionSpec added in v0.6.10 

type ToolRedactionSpec struct {
	ArgFields    []string `json:"arg_fields,omitempty"`
	ResultFields []string `json:"result_fields,omitempty"`
}

ToolRedactionSpec records which fields must stay out of compact activity payloads.

type ToolResultEnvelope 

type ToolResultEnvelope struct {
	RunID  string       `json:"run_id"`
	ToolID string       `json:"tool_id"`
	Status ResultStatus `json:"status"`
	Result any          `json:"result,omitempty"`
	Error  *ToolError   `json:"error,omitempty"`
}

ToolResultEnvelope is the normalized payload for tool call completion.

func (*ToolResultEnvelope) Normalize 

func (e *ToolResultEnvelope) Normalize()

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.