tool

package
v0.11.7 Latest Latest
Warning

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

 Go to latest Published: Jul 20, 2026 License: MIT Imports: 13 Imported by: 0

Documentation

Index

Constants

View Source 
const MaxImageDimension = 8000

MaxImageDimension matches the strictest input-image dimension accepted by supported model providers. Rejecting larger tool results keeps an otherwise valid image from poisoning the next model request.

View Source 
const MaxImageResultBytes = 8 * 1024 * 1024

MaxImageResultBytes bounds a data-URL tool result that may be forwarded to the model as an image attachment; larger payloads stay ordinary text and fall under normal output truncation.

Variables

This section is empty.

Functions

func ElicitHint added in v0.10.1 

func ElicitHint(args map[string]any) string

ElicitHint summarizes an elicit tool call as its first question plus a count of the rest; shared by every surface that labels tool calls.

func ExtractHint added in v0.7.0 

func ExtractHint(argsJSON, toolName string) string

func ImageDimensions added in v0.10.4 

func ImageDimensions(data []byte, mime string) (int, int, error)

ImageDimensions reads image dimensions without decoding the full bitmap.

func IntArg added in v0.6.9 

func IntArg(args map[string]any, key string) (int, bool)

func IntValue added in v0.6.9 

func IntValue(value any) (int, bool)

func IsBackgroundOrigin added in v0.11.2 

func IsBackgroundOrigin(ctx context.Context) bool

func IsImageResult added in v0.10.0 

func IsImageResult(s string) bool

IsImageResult reports whether a tool result is a well-formed image data URL safe to send as an input image: declared type matches the decoded bytes, so a tool echoing an arbitrary data:-prefixed string cannot poison the request.

func NonNegIntArg added in v0.6.9 

func NonNegIntArg(args map[string]any, key string) (value int, present bool, err error)

func OptionalIntArg added in v0.6.9 

func OptionalIntArg(args map[string]any, key string) (int, bool, error)

func PositiveIntArg added in v0.6.9 

func PositiveIntArg(args map[string]any, key string) (value int, present bool, err error)

func Progress added in v0.11.2 

func Progress(ctx context.Context) func(text string)

Progress returns a reporter for transient status text from a running tool call, or nil when no sink is installed. Reported text is display-only and never reaches the model.

func ReportUsage added in v0.11.2 

func ReportUsage(ctx context.Context, d UsageDelta)

ReportUsage reports internally incurred model usage; a no-op without a sink.

func StaticEffect added in v0.6.2 

func StaticEffect(effect Effect) func(map[string]any) Effect

func TodoHint added in v0.10.1 

func TodoHint(argsJSON string) string

TodoHint summarizes a todo call as progress plus the active step.

func WithBackgroundOrigin added in v0.11.2 

func WithBackgroundOrigin(ctx context.Context) context.Context

WithBackgroundOrigin marks ctx as belonging to a detached background agent run, so session-scoped state (e.g. file freshness) can tell its tool calls apart from the main agent's.

func WithProgressCall added in v0.11.2 

func WithProgressCall(ctx context.Context, callID string) context.Context

WithProgressCall tags ctx with the tool-call ID that subsequent Progress reports attribute to.

func WithProgressSink added in v0.11.2 

func WithProgressSink(ctx context.Context, fn func(callID, text string)) context.Context

WithProgressSink installs a UI callback that receives transient status text from running tool calls, keyed by tool-call ID.

func WithUsageSink added in v0.11.2 

func WithUsageSink(ctx context.Context, fn func(UsageDelta)) context.Context

WithUsageSink installs a callback that credits model usage a tool incurred internally (e.g. a subagent run) to the session's accounting.

Types

type Effect added in v0.6.2 

type Effect string
const (
	EffectReadOnly  Effect = "read_only"
	EffectMutates   Effect = "mutates"
	EffectDangerous Effect = "dangerous"
	EffectDynamic   Effect = "dynamic"
)

type ElicitAction added in v0.10.1 

type ElicitAction string
const (
	ElicitAccept  ElicitAction = "accept"
	ElicitDecline ElicitAction = "decline"
	ElicitCancel  ElicitAction = "cancel"
)

type ElicitField added in v0.10.1 

type ElicitField struct {
	Name        string `json:"name"`
	Type        string `json:"type,omitempty"`
	Title       string `json:"title,omitempty"`
	Description string `json:"description,omitempty"`
	Required    bool   `json:"required,omitempty"`

	Enum             []string `json:"enum,omitempty"`
	EnumDescriptions []string `json:"enum_descriptions,omitempty"`
	EnumPreviews     []string `json:"enum_previews,omitempty"`

	// Strict marks enum values as a closed set (MCP requestedSchema contract):
	// UIs must not offer a free-text alternative. The elicit tool's options
	// are advisory and stay non-strict.
	Strict bool `json:"strict,omitempty"`

	// Multiple allows selecting several enum values; the content value is then
	// a []string instead of a string. Never produced by the MCP bridge.
	Multiple bool `json:"multiple,omitempty"`

	Default any `json:"default,omitempty"`
}

ElicitField mirrors the MCP elicitation primitive schema: a flat, typed value request (string, number, integer, or boolean; optionally enum- constrained). EnumDescriptions extends the MCP shape with per-option help text; bridges to MCP drop it.

type ElicitRequest added in v0.10.1 

type ElicitRequest struct {
	Message string        `json:"message"`
	Fields  []ElicitField `json:"fields,omitempty"`
}

type ElicitResult added in v0.10.1 

type ElicitResult struct {
	Action  ElicitAction   `json:"action"`
	Content map[string]any `json:"content,omitempty"`
}

type Elicitation added in v0.6.2 

type Elicitation struct {
	Elicit  func(ctx context.Context, req ElicitRequest) (ElicitResult, error)
	Confirm func(ctx context.Context, message string) (bool, error)
}

type TodoItem added in v0.10.1 

type TodoItem struct {
	Content string `json:"content"`
	Status  string `json:"status"`
}

func ParseTodoItems added in v0.10.1 

func ParseTodoItems(argsJSON string) []TodoItem

ParseTodoItems extracts the checklist from a todo tool call's arguments so UIs can render it richly instead of showing the raw JSON.

type Tool 

type Tool struct {
	Name        string
	Description string
	Parameters  map[string]any
	Execute     func(ctx context.Context, args map[string]any) (string, error)
	Hidden      bool
	Effect      func(args map[string]any) Effect

	// Timeout replaces the harness default tool timeout for this tool.
	// An explicitly configured Config.ToolTimeout takes precedence; negative
	// values disable the deadline.
	Timeout time.Duration
}

type ToolCall added in v0.6.2 

type ToolCall struct {
	ID   string `json:"id"`
	Name string `json:"name"`
	Args string `json:"args,omitempty"`
}

type UsageDelta added in v0.11.2 

type UsageDelta struct {
	InputTokens  int64
	CachedTokens int64
	OutputTokens int64
}

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.