tools

package
v7.3.2 Latest Latest
Warning

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

 Go to latest Published: Sep 8, 2026 License: MIT Imports: 17 Imported by: 0

Documentation

Overview

Package tools defines local tool registration, permission metadata, and authority-gated 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. Host authorization is supplied through runtime.EffectAuthorizationGate; this package does not expose a standalone approval callback. PermissionDeny tools remain callable only as explicit host-side disabled tools and are not exposed to providers. Ordinary calls returned in one model batch execute concurrently; the model expresses dependencies by emitting dependent calls in later turns.

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 (
	AnnotationRepeatPolicy                   = "repeat_policy"
	AnnotationRepeatIdentityIgnoredArguments = "repeat_identity_ignored_arguments"
	RepeatPolicyPolling                      = "polling"
	ResultMetadataProgressToken              = "progress_token"
)
View Source 
const ControlAskUser = "ask_user"
View Source 
const ResultOutcomeDeclined = "declined"

Variables

View Source 
var ErrDuplicate = errors.New("duplicate tool name")
View Source 
var ErrEffectDispatcherRequired = errors.New("tool effect authority dispatcher is required")
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 ActivityDurationMS 

func ActivityDurationMS(in *ActivityPresentation) int64

ActivityDurationMS returns a typed renderer duration when one exists.

func ActivityHasPending 

func ActivityHasPending(in *ActivityPresentation) bool

ActivityHasPending reports whether presentation data still describes unsettled host-owned work.

func ActivityStatus 

func ActivityStatus(in *ActivityPresentation) (string, bool)

ActivityStatus returns renderer-authored status without requiring callers to know which payload variant carries it.

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 PendingToolResultMetadata 

func PendingToolResultMetadata(p PendingToolResult) map[string]any

func PendingToolResultText 

func PendingToolResultText(p PendingToolResult) string

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 ActivityChip 

type ActivityChip struct {
	Kind  string `json:"kind"`
	Label string `json:"label"`
	Value string `json:"value,omitempty"`
	Tone  string `json:"tone,omitempty"`
}

type ActivityError 

type ActivityError struct {
	Message string `json:"message"`
}

type ActivityPayload 

type ActivityPayload interface {
	// contains filtered or unexported methods
}

ActivityPayload is the closed set of renderer-specific presentation data. Downstream packages can consume the variants but cannot add unvalidated ones.

type ActivityPresentation 

type ActivityPresentation struct {
	Label       string              `json:"label,omitempty"`
	Description string              `json:"description,omitempty"`
	Renderer    ActivityRenderer    `json:"renderer,omitempty"`
	Chips       []ActivityChip      `json:"chips,omitempty"`
	TargetRefs  []ActivityTargetRef `json:"target_refs,omitempty"`
	Payload     ActivityPayload     `json:"payload,omitempty"`
}

ActivityPresentation is display data authored by the tool that owns the invocation. Its renderer is the discriminator for exactly one payload type.

func ClearPendingActivity 

func ClearPendingActivity(in *ActivityPresentation) *ActivityPresentation

ClearPendingActivity removes transient pending presentation after a terminal fact.

func CloneActivityPresentation 

func CloneActivityPresentation(in *ActivityPresentation) *ActivityPresentation

CloneActivityPresentation returns a detached copy of tool-authored display data so observers cannot mutate invocation state.

func FinalizeActivityPresentation 

func FinalizeActivityPresentation(in *ActivityPresentation, status string) *ActivityPresentation

FinalizeActivityPresentation applies a terminal status and removes transient pending markers without exposing renderer payload mutation to callers.

func MergeActivityPresentations 

func MergeActivityPresentations(left, right *ActivityPresentation) *ActivityPresentation

MergeActivityPresentations combines successive facts for one invocation. Renderer changes replace the payload; equal renderers merge typed fields.

func PendingToolActivity 

func PendingToolActivity(p PendingToolResult, base *ActivityPresentation) *ActivityPresentation

func (ActivityPresentation) MarshalJSON 

func (presentation ActivityPresentation) MarshalJSON() ([]byte, error)

func (*ActivityPresentation) UnmarshalJSON 

func (presentation *ActivityPresentation) UnmarshalJSON(data []byte) error

func (ActivityPresentation) Validate 

func (presentation ActivityPresentation) Validate() error

type ActivityRenderer 

type ActivityRenderer string
const (
	ActivityRendererStructured ActivityRenderer = "structured"
	ActivityRendererTerminal   ActivityRenderer = "terminal"
	ActivityRendererFile       ActivityRenderer = "file"
	ActivityRendererPatch      ActivityRenderer = "patch"
	ActivityRendererWebSearch  ActivityRenderer = "web_search"
	ActivityRendererWebFetch   ActivityRenderer = "web_fetch"
	ActivityRendererTodos      ActivityRenderer = "todos"
	ActivityRendererQuestion   ActivityRenderer = "question"
	ActivityRendererCompletion ActivityRenderer = "completion"
	ActivityRendererSubAgent   ActivityRenderer = "subagent"
	// ActivityRendererSubAgentOperation renders one management operation over
	// an ordered set of child threads. ActivityRendererSubAgent remains the
	// renderer for one durable child-thread fact.
	ActivityRendererSubAgentOperation ActivityRenderer = "subagent_operation"
)

type ActivityTargetRef 

type ActivityTargetRef struct {
	Kind  string `json:"kind"`
	Label string `json:"label"`
	URI   string `json:"uri,omitempty"`
	Path  string `json:"path,omitempty"`
	Line  int    `json:"line,omitempty"`
}

type ActivityUpdate 

type ActivityUpdate struct {
	Activity *ActivityPresentation
	Metadata map[string]any
}

type ArtifactRef 

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

type CompletionActivityPayload 

type CompletionActivityPayload struct {
	Status  string `json:"status,omitempty"`
	Summary string `json:"summary,omitempty"`
}

type Definition 

type Definition struct {
	Name         string
	Title        string
	Description  string
	InputSchema  map[string]any
	OutputSchema map[string]any
	Activity     func(Invocation[any]) (*ActivityPresentation, error)
	// InvalidActivity may derive presentation-only metadata from a JSON object
	// rejected by InputSchema. It never participates in permission or dispatch.
	InvalidActivity func(Invocation[map[string]any]) (*ActivityPresentation, error)

	Effects     []Effect
	ReadOnly    bool
	Destructive bool
	OpenWorld   bool

	Permission    PermissionSpec
	PermissionFor PermissionResolver
	OutputPolicy  OutputPolicy
	Annotations   map[string]any
}

func ValidateDefinition 

func ValidateDefinition(def Definition) (Definition, error)

type DispatchOptions 

type DispatchOptions struct {
	RunID         identity.RunID
	ThreadID      identity.ThreadID
	TurnID        identity.TurnID
	PromptScopeID identity.PromptScopeID
	Step          int
	BatchIndex    int
	BatchSize     int
	Labels        map[string]string
	HostContext   map[string]string

	DispatchStarted      func(DispatchStart)
	ActivityUpdated      func(ToolActivityUpdate)
	EffectBatchPreflight EffectBatchPreflight
	EffectDispatcher     EffectDispatcher
}

type DispatchStart 

type DispatchStart struct {
	CallID        string
	Name          string
	RawArgs       string
	RunID         identity.RunID
	ThreadID      identity.ThreadID
	TurnID        identity.TurnID
	PromptScopeID identity.PromptScopeID
	Step          int
	Labels        map[string]string
	HostContext   map[string]string
}

type Effect 

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

type EffectBatchPreflight 

type EffectBatchPreflight func(context.Context, []EffectDispatchRequest) error

type EffectDispatchRequest 

type EffectDispatchRequest struct {
	CallID        string
	Name          string
	RawArgs       string
	RunID         identity.RunID
	ThreadID      identity.ThreadID
	TurnID        identity.TurnID
	PromptScopeID identity.PromptScopeID
	Step          int
	BatchIndex    int
	BatchSize     int
	Labels        map[string]string
	HostContext   map[string]string
	// Activity is detached tool-authored display data. It is never authority.
	Activity    *ActivityPresentation
	Resources   []ResourceRef
	Effects     []Effect
	Permission  PermissionSpec
	ReadOnly    bool
	Destructive bool
	OpenWorld   bool
}

type EffectDispatcher 

type EffectDispatcher func(context.Context, EffectDispatchRequest, func(context.Context) Result) Result

EffectDispatcher authorizes one prepared effect and chooses the execution context used by the tool handler. A lifecycle-owning dispatcher is responsible for bounding that selected context by its caller's execution lifetime.

type FileActivityPayload 

type FileActivityPayload struct {
	Path                  string         `json:"path,omitempty"`
	Operation             string         `json:"operation,omitempty"`
	Status                string         `json:"status,omitempty"`
	Summary               string         `json:"summary,omitempty"`
	SizeBytes             int64          `json:"size_bytes,omitempty"`
	DisplayName           string         `json:"display_name,omitempty"`
	Content               string         `json:"content,omitempty"`
	LineOffset            int            `json:"line_offset,omitempty"`
	LineCount             int            `json:"line_count,omitempty"`
	TotalLines            int            `json:"total_lines,omitempty"`
	ChangeType            string         `json:"change_type,omitempty"`
	Additions             int            `json:"additions,omitempty"`
	Deletions             int            `json:"deletions,omitempty"`
	UnifiedDiff           string         `json:"unified_diff,omitempty"`
	DiffUnavailableReason string         `json:"diff_unavailable_reason,omitempty"`
	Truncated             bool           `json:"truncated,omitempty"`
	Error                 *ActivityError `json:"error,omitempty"`
}

type FileMutationActivityPayload 

type FileMutationActivityPayload struct {
	DisplayName           string `json:"display_name,omitempty"`
	ChangeType            string `json:"change_type,omitempty"`
	Additions             int    `json:"additions,omitempty"`
	Deletions             int    `json:"deletions,omitempty"`
	UnifiedDiff           string `json:"unified_diff,omitempty"`
	DiffUnavailableReason string `json:"diff_unavailable_reason,omitempty"`
	Truncated             bool   `json:"truncated,omitempty"`
}

FileMutationActivityPayload is one bounded, product-neutral file mutation rendered by a patch activity. Resource authority remains in TargetRefs.

type FileMutationActivityPayloads 

type FileMutationActivityPayloads []FileMutationActivityPayload

FileMutationActivityPayloads is an ordered set of patch mutations. Patch payloads hold it by pointer to preserve the v5 payload's comparability.

type FullOutputPlan 

type FullOutputPlan struct {
	Text string
	Kind string
	MIME string
}

FullOutputPlan is a side-effect-free request to admit the complete tool output together with its canonical result. It is not a durable artifact ref.

type Invocation 

type Invocation[T any] struct {
	CallID          string
	Name            string
	RawArgs         string
	Args            T
	RunID           identity.RunID
	ThreadID        identity.ThreadID
	TurnID          identity.TurnID
	PromptScopeID   identity.PromptScopeID
	Step            int
	Labels          map[string]string
	HostContext     map[string]string
	ActivityUpdater func(ActivityUpdate)
}

func (Invocation[T]) UpdateActivity 

func (i Invocation[T]) UpdateActivity(update ActivityUpdate)

type OutputPolicy 

type OutputPolicy struct {
	VisibleMaxBytes  int
	VisibleMaxLines  int
	Strategy         OutputStrategy
	PreserveFull     bool
	PreserveFullSet  bool
	ArtifactKind     string
	ArtifactMIME     string
	TruncationNotice 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
	FullOutputPlan *FullOutputPlan
}

func BuildOutputProjection 

func BuildOutputProjection(result Result, policy OutputPolicy) OutputProjection

type OutputStrategy 

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

type PatchActivityPayload 

type PatchActivityPayload struct {
	// Path and Diff remain for v5 source and JSON compatibility. New hosts
	// should use Mutations so multi-file results retain complete typed detail.
	Path             string                        `json:"path,omitempty"`
	Diff             string                        `json:"diff,omitempty"`
	Status           string                        `json:"status,omitempty"`
	Summary          string                        `json:"summary,omitempty"`
	FilesChanged     int                           `json:"files_changed,omitempty"`
	Hunks            int                           `json:"hunks,omitempty"`
	Additions        int                           `json:"additions,omitempty"`
	Deletions        int                           `json:"deletions,omitempty"`
	InputFormat      string                        `json:"input_format,omitempty"`
	NormalizedFormat string                        `json:"normalized_format,omitempty"`
	Mutations        *FileMutationActivityPayloads `json:"mutations,omitempty"`
	Truncated        bool                          `json:"truncated,omitempty"`
	Error            *ActivityError                `json:"error,omitempty"`
}

type PendingToolResult 

type PendingToolResult struct {
	// Handle is the provider-visible continuation token. Hosts should put the
	// exact token here that the model should reuse for later tool calls.
	Handle string
	State  PendingToolResultState
	// Summary and Instruction are provider-visible text.
	Summary     string
	Instruction string
	// Metadata is observation-only pending state. It is not rendered into the
	// provider-visible pending result text.
	Metadata map[string]string
}

PendingToolResult is returned by a tool handler after the host has started work whose lifecycle remains owned by the host application.

func (PendingToolResult) Validate 

func (p PendingToolResult) Validate() error

type PendingToolResultState 

type PendingToolResultState string
const (
	// PendingToolResultRunning marks host-owned work that is still active outside Floret.
	PendingToolResultRunning PendingToolResultState = "running"
)

type PermissionMode 

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

type PermissionRequest 

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

type PermissionResolver 

type PermissionResolver func(PermissionRequest) (PermissionSpec, error)

type PermissionSpec 

type PermissionSpec struct {
	Mode          PermissionMode
	ResourceKinds []string
}

type QuestionActivityAnswer 

type QuestionActivityAnswer struct {
	QuestionID string   `json:"question_id"`
	Values     []string `json:"values,omitempty"`
	Redacted   bool     `json:"redacted,omitempty"`
}

QuestionActivityAnswer is a host-authored, presentation-safe answer summary. Secret answers must set Redacted and omit Values.

type QuestionActivityItem 

type QuestionActivityItem struct {
	ID       string                   `json:"id"`
	Question string                   `json:"question"`
	Options  []QuestionActivityOption `json:"options,omitempty"`
}

type QuestionActivityOption 

type QuestionActivityOption struct {
	Label       string `json:"label"`
	Description string `json:"description,omitempty"`
}

type QuestionActivityPayload 

type QuestionActivityPayload struct {
	PromptID  string                   `json:"prompt_id,omitempty"`
	Questions []QuestionActivityItem   `json:"questions,omitempty"`
	Answers   []QuestionActivityAnswer `json:"answers,omitempty"`
}

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 

func (r *Registry) ActivityForCall(call ToolCall, opts DispatchOptions) (*ActivityPresentation, error)

func (*Registry) Definition 

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

func (*Registry) Definitions 

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

func (*Registry) Dispatch 

func (r *Registry) Dispatch(ctx context.Context, call ToolCall, opts DispatchOptions) Result

func (*Registry) DispatchBatch 

func (r *Registry) DispatchBatch(ctx context.Context, calls []ToolCall, opts DispatchOptions) []Result

func (*Registry) ExposedDefinitions 

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

func (*Registry) OutputPolicyFor 

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

func (*Registry) Register 

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

func (*Registry) Seal 

func (r *Registry) Seal()

Seal prevents further registration while preserving definition reads and dispatch for the existing immutable tool snapshot. It is idempotent.

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     *ActivityPresentation
	Artifacts    []ArtifactRef
	OutputPolicy *OutputPolicy
	Pending      *PendingToolResult
	IsError      bool
	DispatchErr  error
	// contains filtered or unexported fields
}

func DeclinedResult 

func DeclinedResult(callID, name string) Result

DeclinedResult reports a normal user decision that prevented execution. It is provider-visible, but it is not a tool dispatch or execution failure.

func ErrorResult 

func ErrorResult(callID, name, text string) Result

func (Result) RequiresEffectFinalization 

func (r Result) RequiresEffectFinalization() bool

RequiresEffectFinalization reports whether the result crossed the effect authority dispatcher and therefore requires its atomic result finalizer.

type StructuredActivityPayload 

type StructuredActivityPayload struct {
	Status      string                  `json:"status,omitempty"`
	Operation   string                  `json:"operation,omitempty"`
	DisplayName string                  `json:"display_name,omitempty"`
	Summary     string                  `json:"summary,omitempty"`
	DurationMS  int64                   `json:"duration_ms,omitempty"`
	Error       *ActivityError          `json:"error,omitempty"`
	Rows        []StructuredActivityRow `json:"rows,omitempty"`
}

type StructuredActivityRow 

type StructuredActivityRow struct {
	Title   string                      `json:"title,omitempty"`
	Meta    string                      `json:"meta,omitempty"`
	Content string                      `json:"content,omitempty"`
	Format  StructuredActivityRowFormat `json:"format,omitempty"`
}

StructuredActivityRow is one ordered, product-neutral display row for a structured tool activity. Hosts author already-sanitized display text.

type StructuredActivityRowFormat 

type StructuredActivityRowFormat string

StructuredActivityRowFormat describes how a structured activity row's content should be presented by a host. 

const (
	StructuredActivityRowFormatText     StructuredActivityRowFormat = "text"
	StructuredActivityRowFormatMarkdown StructuredActivityRowFormat = "markdown"
	StructuredActivityRowFormatCode     StructuredActivityRowFormat = "code"
)

type SubAgentActivityPayload 

type SubAgentActivityPayload struct {
	ThreadID        identity.ThreadID `json:"thread_id"`
	Path            string            `json:"path,omitempty"`
	TaskName        string            `json:"task_name,omitempty"`
	TaskDescription string            `json:"task_description,omitempty"`
	Title           string            `json:"title,omitempty"`
	HostProfileRef  string            `json:"host_profile_ref,omitempty"`
	ForkMode        string            `json:"fork_mode,omitempty"`
	Status          string            `json:"status"`
	LastMessage     string            `json:"last_message,omitempty"`
	WaitingPrompt   string            `json:"waiting_prompt,omitempty"`
	QueuedInputs    int               `json:"queued_inputs,omitempty"`
	ParentThreadID  identity.ThreadID `json:"parent_thread_id"`
	ParentTurnID    identity.TurnID   `json:"parent_turn_id,omitempty"`
	LatestTurnID    identity.TurnID   `json:"latest_turn_id,omitempty"`
	CreatedAtUnixMS int64             `json:"created_at_unix_ms,omitempty"`
	UpdatedAtUnixMS int64             `json:"updated_at_unix_ms,omitempty"`
	Closed          bool              `json:"closed,omitempty"`
	CanSendInput    bool              `json:"can_send_input"`
	CanInterrupt    bool              `json:"can_interrupt"`
	CanClose        bool              `json:"can_close"`
}

SubAgentActivityPayload describes the durable child-thread fact rendered by a parent activity view. Child execution details remain in the child stream.

type SubAgentOperationAction 

type SubAgentOperationAction string

SubAgentOperationAction identifies one product-neutral child-thread management operation. 

const (
	SubAgentOperationSpawn     SubAgentOperationAction = "spawn"
	SubAgentOperationWait      SubAgentOperationAction = "wait"
	SubAgentOperationList      SubAgentOperationAction = "list"
	SubAgentOperationInspect   SubAgentOperationAction = "inspect"
	SubAgentOperationSendInput SubAgentOperationAction = "send_input"
	SubAgentOperationClose     SubAgentOperationAction = "close"
	SubAgentOperationCloseAll  SubAgentOperationAction = "close_all"
)

type SubAgentOperationActivityPayload 

type SubAgentOperationActivityPayload struct {
	Action         SubAgentOperationAction   `json:"action"`
	Status         string                    `json:"status,omitempty"`
	Targets        []SubAgentOperationTarget `json:"targets,omitempty"`
	RequestedCount int                       `json:"requested_count,omitempty"`
	CompletedCount int                       `json:"completed_count,omitempty"`
	MissingCount   int                       `json:"missing_count,omitempty"`
	TimedOut       bool                      `json:"timed_out,omitempty"`
	Error          *ActivityError            `json:"error,omitempty"`
}

SubAgentOperationActivityPayload preserves the exact management action, ordered targets, and bounded outcome counts for one tool invocation. Child execution details remain in each child thread's own activity stream.

type SubAgentOperationTarget 

type SubAgentOperationTarget struct {
	ThreadID        identity.ThreadID `json:"thread_id,omitempty"`
	TaskName        string            `json:"task_name,omitempty"`
	TaskDescription string            `json:"task_description,omitempty"`
	Status          string            `json:"status,omitempty"`
}

SubAgentOperationTarget is one ordered child target or spawn request shown by a management activity. ThreadID may be empty before a spawn is admitted; in that state TaskName identifies the requested child for presentation.

type TerminalActivityPayload 

type TerminalActivityPayload struct {
	Operation         string         `json:"operation,omitempty"`
	Command           string         `json:"command,omitempty"`
	Status            string         `json:"status,omitempty"`
	ProcessID         string         `json:"process_id,omitempty"`
	InputBytes        int64          `json:"input_bytes,omitempty"`
	LatestOutput      string         `json:"latest_output,omitempty"`
	Output            string         `json:"output,omitempty"`
	Stdout            string         `json:"stdout,omitempty"`
	Stderr            string         `json:"stderr,omitempty"`
	ExitCode          *int           `json:"exit_code,omitempty"`
	DurationMS        int64          `json:"duration_ms,omitempty"`
	FirstSeq          int64          `json:"first_seq,omitempty"`
	LastSeq           int64          `json:"last_seq,omitempty"`
	LatestSeq         int64          `json:"latest_seq,omitempty"`
	HasMore           bool           `json:"has_more,omitempty"`
	TotalBytes        int64          `json:"total_bytes,omitempty"`
	ExecutionLocation string         `json:"execution_location,omitempty"`
	Truncated         bool           `json:"truncated,omitempty"`
	PendingResult     string         `json:"pending_result,omitempty"`
	Terminated        bool           `json:"terminated,omitempty"`
	TimedOut          bool           `json:"timed_out,omitempty"`
	Error             *ActivityError `json:"error,omitempty"`
}

TerminalActivityPayload describes safe terminal execution and interaction facts. Hosts supply a sanitized command display and a public execution-location label; raw stdin, credentials, and private host paths must never enter this payload. Operation is empty for existing v7 presentations, or exec, read, write, terminate. InputBytes counts bytes actually sent. Output cursors are one snapshot: read payloads (or payloads carrying a nonzero cursor) replace all cursor fields and HasMore together, including zero/false values. Status-only updates preserve them.

type TodoActivityItem 

type TodoActivityItem struct {
	Text   string `json:"text"`
	Status string `json:"status"`
}

type TodosActivityPayload 

type TodosActivityPayload struct {
	Operation string             `json:"operation,omitempty"`
	Items     []TodoActivityItem `json:"items,omitempty"`
}

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 ToolActivityUpdate 

type ToolActivityUpdate struct {
	CallID        string
	Name          string
	RawArgs       string
	RunID         identity.RunID
	ThreadID      identity.ThreadID
	TurnID        identity.TurnID
	PromptScopeID identity.PromptScopeID
	Step          int
	Labels        map[string]string
	HostContext   map[string]string
	Activity      *ActivityPresentation
	Metadata      map[string]any
}

type ToolCall 

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

type ToolDefinition 

type ToolDefinition struct {
	Name         string         `json:"name"`
	Title        string         `json:"title,omitempty"`
	Description  string         `json:"description"`
	InputSchema  map[string]any `json:"input_schema"`
	OutputSchema map[string]any `json:"output_schema,omitempty"`
	Strict       bool           `json:"strict,omitempty"`
	Annotations  map[string]any `json:"annotations,omitempty"`
}

type WebFetchActivityIcon deprecated 

type WebFetchActivityIcon struct {
	ContentType string `json:"content_type"`
	Data        []byte `json:"data"`
}

WebFetchActivityIcon is retained for v5 source and JSON compatibility.

Deprecated: web_fetch no longer requests or emits site icons. Hosts should use product-owned static iconography.

type WebFetchActivityPayload 

type WebFetchActivityPayload struct {
	URL              string `json:"url,omitempty"`
	FinalURL         string `json:"final_url,omitempty"`
	Status           string `json:"status,omitempty"`
	StatusCode       int    `json:"status_code,omitempty"`
	ContentType      string `json:"content_type,omitempty"`
	Format           string `json:"format,omitempty"`
	ContentPreview   string `json:"content_preview,omitempty"`
	PreviewTruncated bool   `json:"preview_truncated,omitempty"`
	// Deprecated: web_fetch no longer requests or emits site icons. This field
	// remains available only to read Activity data written by v5.0.9.
	SiteIcon  *WebFetchActivityIcon `json:"site_icon,omitempty"`
	BytesRead int64                 `json:"bytes_read,omitempty"`
	Truncated bool                  `json:"truncated,omitempty"`
	Error     *ActivityError        `json:"error,omitempty"`
}

WebFetchActivityPayload carries bounded public response metadata and a lightweight content preview for a web_fetch activity. Complete fetched page content stays in the tool result and artifact.

type WebSearchActivityPayload 

type WebSearchActivityPayload struct {
	Query   string                    `json:"query,omitempty"`
	Status  string                    `json:"status,omitempty"`
	Results []WebSearchActivityResult `json:"results,omitempty"`
	Error   *ActivityError            `json:"error,omitempty"`
}

type WebSearchActivityResult 

type WebSearchActivityResult struct {
	Title string `json:"title"`
	URL   string `json:"url"`
}

Source Files

View all Source files

Directories

Path Synopsis
Package webfetch provides Floret's secure public-text URL fetch tool.
 Package webfetch provides Floret's secure public-text URL fetch tool.

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.