tool

package
v0.1.0-preview.7 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: 9 Imported by: 0

Documentation

Overview

Package tool owns immutable executable-tool values and implementation SPIs.

@import { NamedInterface } from "github.com/spice-framework/spice/annotation/modulith" @NamedInterface("tool")

Index

Constants

View Source 
const (
	// MaximumPayloadBytes bounds one tool schema, call, or result JSON value.
	MaximumPayloadBytes = 1 << 20
	// MaximumProgressBytes bounds one progress message.
	MaximumProgressBytes = 4096
	// MaximumExecutionErrorBytes bounds one tool execution failure message.
	MaximumExecutionErrorBytes = 4096
)

Variables

This section is empty.

Functions

This section is empty.

Types

type Call 

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

Call is one immutable invocation requested by a model.

func NewCall 

func NewCall(id CallID, name string, arguments json.RawMessage) (Call, error)

NewCall validates and copies one call.

func (Call) Arguments 

func (call Call) Arguments() json.RawMessage

Arguments returns a defensive JSON copy.

func (Call) Clone 

func (call Call) Clone() Call

Clone returns a deep defensive copy.

func (Call) ID 

func (call Call) ID() CallID

ID returns the correlation identity.

func (Call) Name 

func (call Call) Name() string

Name returns the canonical tool name.

func (Call) Validate 

func (call Call) Validate() error

Validate rejects a zero or corrupted call.

type CallID 

type CallID string

CallID identifies one tool operation.

type Capability 

type Capability string

Capability declares a security-relevant effect. It is descriptive metadata, not a sandbox or permission boundary. 

const (
	CapabilityFilesystemRead   Capability = "filesystem.read"
	CapabilityFilesystemWrite  Capability = "filesystem.write"
	CapabilityProcessExecute   Capability = "process.execute"
	CapabilityNetworkAccess    Capability = "network.access"
	CapabilitySecretsRead      Capability = "secrets.read"
	CapabilityEnvironmentRead  Capability = "environment.read"
	CapabilityEnvironmentWrite Capability = "environment.write"
)

type Definition 

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

Definition is an immutable model-visible tool description. Capabilities are an unordered set exposed in canonical lexical order.

func NewDefinition 

func NewDefinition(
	name,
	description string,
	inputSchema json.RawMessage,
	effect Effect,
	replaySafety ReplaySafety,
	capabilities ...Capability,
) (Definition, error)

NewDefinition validates and defensively copies a tool definition.

func (Definition) Capabilities 

func (definition Definition) Capabilities() []Capability

Capabilities returns the unordered set in canonical lexical order.

func (Definition) Clone 

func (definition Definition) Clone() Definition

Clone returns a deep defensive copy.

func (Definition) Description 

func (definition Definition) Description() string

Description returns human-facing model guidance.

func (Definition) Effect 

func (definition Definition) Effect() Effect

Effect returns the declared external-state effect.

func (Definition) Fingerprint 

func (definition Definition) Fingerprint() string

Fingerprint returns a deterministic hexadecimal SHA-256 identity for the complete model-visible and security-relevant contract. Capability order is normalized because it does not change the contract's meaning.

func (Definition) InputSchema 

func (definition Definition) InputSchema() json.RawMessage

InputSchema returns a defensive copy.

func (Definition) Name 

func (definition Definition) Name() string

Name returns the canonical Spice bean and model-visible name.

func (Definition) ReplaySafety 

func (definition Definition) ReplaySafety() ReplaySafety

ReplaySafety returns the declared deliberate replay contract.

func (Definition) SizeBytes 

func (definition Definition) SizeBytes() int

SizeBytes returns deterministic request-budget accounting.

func (Definition) Validate 

func (definition Definition) Validate() error

Validate rejects a zero or corrupted definition.

type Effect 

type Effect string

Effect classifies whether a successful invocation can mutate external state. It is mandatory policy metadata, not inferred from capabilities or arguments. 

const (
	EffectReadOnly Effect = "read_only"
	EffectMutating Effect = "mutating"
)

type ExecutionError 

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

ExecutionError is a bounded correlated infrastructure failure. It is never model-visible tool output. Unwrap preserves cancellation and deadline checks.

func NewExecutionError 

func NewExecutionError(
	callID CallID,
	state ExecutionState,
	retry RetryDisposition,
	cause error,
) (*ExecutionError, error)

NewExecutionError constructs a validated infrastructure failure.

func (*ExecutionError) CallID 

func (failure *ExecutionError) CallID() CallID

CallID returns the invocation correlation identity.

func (*ExecutionError) Error 

func (failure *ExecutionError) Error() string

Error returns the bounded underlying failure text.

func (*ExecutionError) RetryDisposition 

func (failure *ExecutionError) RetryDisposition() RetryDisposition

RetryDisposition returns the validated retry advice.

func (*ExecutionError) State 

func (failure *ExecutionError) State() ExecutionState

State returns whether the execution outcome is definitive or uncertain.

func (*ExecutionError) Unwrap 

func (failure *ExecutionError) Unwrap() error

Unwrap preserves errors.Is and errors.As for cancellation and typed causes.

func (*ExecutionError) Validate 

func (failure *ExecutionError) Validate() error

Validate rejects uncorrelated, unbounded, or unsafe outcome combinations.

type ExecutionState 

type ExecutionState string

ExecutionState states whether the tool host knows that an attempted invocation did not commit an external mutation. 

const (
	ExecutionDefinitive ExecutionState = "definitive"
	ExecutionUncertain  ExecutionState = "uncertain"
)

type Progress 

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

Progress is immutable bounded observable progress for a running call.

func NewProgress 

func NewProgress(callID CallID, message string) (Progress, error)

NewProgress validates one progress observation.

func (Progress) CallID 

func (progress Progress) CallID() CallID

CallID returns the active call identity.

func (Progress) Message 

func (progress Progress) Message() string

Message returns the progress text.

func (Progress) Validate 

func (progress Progress) Validate() error

Validate rejects a zero or corrupted progress value.

type ReplaySafety 

type ReplaySafety string

ReplaySafety declares whether an invocation may be deliberately executed again after a definitive infrastructure failure. It never authorizes retry after an uncertain mutation outcome. 

const (
	ReplaySafe       ReplaySafety = "safe"
	ReplayIdempotent ReplaySafety = "idempotent"
	ReplayUnsafe     ReplaySafety = "unsafe"
)

type Reporter 

type Reporter interface {
	Report(context.Context, Progress) error
}

Reporter receives progress synchronously.

type Result 

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

Result is one immutable terminal tool outcome. A problem is model-visible terminal data, not a Go transport error.

func NewErrorResult 

func NewErrorResult(callID CallID, content json.RawMessage, problem string) (Result, error)

NewErrorResult constructs a normalized error result.

func NewResult 

func NewResult(callID CallID, content json.RawMessage) (Result, error)

NewResult constructs a successful terminal result.

func (Result) CallID 

func (result Result) CallID() CallID

CallID returns the active call identity.

func (Result) Clone 

func (result Result) Clone() Result

Clone returns a deep defensive copy.

func (Result) Content 

func (result Result) Content() json.RawMessage

Content returns a defensive JSON copy.

func (Result) IsZero 

func (result Result) IsZero() bool

IsZero reports whether no terminal result was returned. It is used to reject ambiguous implementations that return both output and an execution failure.

func (Result) Problem 

func (result Result) Problem() (string, bool)

Problem returns normalized error text and whether the result is an error.

func (Result) Validate 

func (result Result) Validate() error

Validate rejects a zero or corrupted result.

type RetryDisposition 

type RetryDisposition string

RetryDisposition states whether policy may deliberately invoke the call again. Permission to retry is still bounded by Definition.ReplaySafety. 

const (
	RetryNever   RetryDisposition = "never"
	RetryAllowed RetryDisposition = "allowed"
)

type Tool 

type Tool interface {
	Definition() Definition
	Execute(context.Context, Call, Reporter) (Result, error)
}

Tool is one constructor-injected executable contribution. Implementations are singleton beans by default and must be safe for concurrent Execute calls. Context cancellation is cooperative; Spice cannot forcibly stop trusted in-process code that ignores the context. Execute must not retain or invoke Reporter after it returns. A model-visible tool problem is a Result with a problem and a nil error. Infrastructure failure is a zero Result with exactly one direct, correlated *ExecutionError; wrappers, joins, and returning both result and error are invalid.

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.