tool

type Authorization ¶

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

Authorization carries only the frozen model-visible contract and validated arguments, so policy code cannot bypass Contract validation or execute the invocation.

func (a Authorization) Arguments() []byte

func (a Authorization) Definition() chat.ToolDefinition

type AuthorizationError ¶ added in v0.23.0

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

AuthorizationError means the policy could not establish a decision for the current invocation. The Tool was not executed. Its internal cause is not the Tool's outcome, public output, input request, or execution cancellation. Guard separately preserves cancellation of the execution context.

func (a *AuthorizationError) Cause() error

func (a *AuthorizationError) Error() string

type Authorizer ¶

type Authorizer interface {
	Authorize(ctx context.Context, authorization Authorization) (bool, error)
}

Authorizer is deliberately smaller than an application permission system: identity, consent, tenancy, and policy storage remain caller-owned context. A nil error establishes a decision: true permits execution, false refuses it. Any error means the decision could not be completed; its boolean is ignored. The Tool never executes after refusal or an authorization error. Guard seals policy errors in AuthorizationError; only cancellation of the execution context itself remains an errors.Is-visible control signal.

type AuthorizerFunc ¶

type AuthorizerFunc func(context.Context, Authorization) (bool, error)

func (a AuthorizerFunc) Authorize(ctx context.Context, authorization Authorization) (bool, error)

type Binding ¶

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

Binding associates one immutable Contract with the Tool that executes it. Calls may run concurrently when the underlying Tool supports concurrent use.

func Bind(executable Tool) (Binding, error)

func (b Binding) Call(ctx context.Context, invocation Invocation) (chat.ToolOutput, error)

func (b Binding) Contract() Contract

type CallError ¶ added in v0.38.0

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

CallError preserves evidence that would otherwise be lost when a Tool returns an error. Evidence is available for diagnostics and evaluation; it is not a completed result and must not be submitted to a model as a ToolResult.

CallError assigns no outcome or control meaning. Its transparent cause retains the original error contract; only Failure establishes a definite unsuccessful outcome. Runtimes must not infer retry safety from the presence of evidence.

func NewCallError(config CallErrorConfig) (*CallError, error)

func (c *CallError) Error() string

func (c *CallError) Evidence() chat.ToolOutput

func (c *CallError) Unwrap() error

func (c *CallError) Validate() error

type CallErrorConfig ¶ added in v0.38.0

type CallErrorConfig struct {
	Cause    error
	Evidence chat.ToolOutput
}

CallErrorConfig attaches observed execution evidence to an error. Evidence may acknowledge effects without establishing the invocation's final outcome.

type Contract ¶ added in v0.19.0

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

Contract is the immutable trust boundary from an untrusted chat.ToolCall to an Invocation. It retains the frozen definition, compiled schema, and input validator without retaining an executable Tool. It is safe for concurrent use independently of the Tool.

func (c Contract) Definition() chat.ToolDefinition

func (c Contract) Prepare(call chat.ToolCall) (Invocation, error)

type Failure ¶ added in v0.17.0

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

Failure owns one complete unsuccessful outcome of the current Tool invocation. Output is explicitly public to the model. Cause is diagnostic only: it cannot change Kind, substitute another invocation's output, or issue a control signal. Ordinary errors, including CallError with execution evidence, do not establish a definite outcome.

func NewFailure(config FailureConfig) (*Failure, error)

package main

import (
	"errors"
	"fmt"

	"github.com/Tangerg/scope/core/chat"
	"github.com/Tangerg/scope/core/tool"
)

func main() {
	failure, err := tool.NewFailure(tool.FailureConfig{
		Kind: tool.FailureKindRejected, Cause: errors.New("internal authorization diagnostic"),
		Output: chat.NewTextToolOutput("this operation is not permitted"),
	})
	if err != nil {
		panic(err)
	}
	wrapped := fmt.Errorf("tool call: %w", failure)
	result, found := errors.AsType[*tool.Failure](wrapped)
	if !found {
		panic("missing definite outcome")
	}
	text, _ := result.Output().Text()
	fmt.Println(result.Kind(), text)
	fmt.Println(errors.Is(wrapped, result.Cause()))
}

Output:
rejected this operation is not permitted
false

func (f *Failure) Cause() error

func (f *Failure) Error() string

func (f *Failure) Kind() FailureKind

func (f *Failure) Output() chat.ToolOutput

func (f *Failure) Validate() error

type FailureConfig ¶ added in v0.23.0

type FailureConfig struct {
	Kind   FailureKind
	Output chat.ToolOutput
	Cause  error
}

FailureConfig describes one unsuccessful invocation. NewFailure snapshots Output and retains Cause only for explicit diagnostic inspection.

type FailureKind ¶ added in v0.23.0

type FailureKind string

FailureKind describes the current invocation, independently of its diagnostic cause. Neither kind assigns retry or runtime control policy.

const (
	// FailureKindFailed is a definite unsuccessful outcome. It does not assert
	// that execution began and may describe acknowledged partial effects.
	FailureKindFailed FailureKind = "failed"
	// FailureKindRejected means the invocation was refused permission to execute.
	FailureKindRejected FailureKind = "rejected"
)

type Func ¶

type Func[In, Out any] struct {
	// contains filtered or unexported fields
}

Func adapts a typed Go function to Tool. It is immutable and as safe for concurrent calls as the wrapped function.

A Func validates arguments by strictly decoding them into In, not against a retained compiled schema, so it owns only the canonical input-schema JSON it projects into its Definition. Bind compiles that JSON when it needs schema-level admission for the Tool contract.

func NewFunc[In, Out any](config FuncConfig, function func(context.Context, In) (Out, error)) (Func[In, Out], error)

func (f Func[In, Out]) Call(ctx context.Context, invocation Invocation) (chat.ToolOutput, error)

func (f Func[In, Out]) Definition() chat.ToolDefinition

func (Func[In, Out]) InputValidator() func([]byte) error

type FuncConfig ¶

type FuncConfig struct {
	Name        string
	Description string
}

type Guard ¶

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

Guard keeps authorization at the universal Tool.Call boundary, which makes the same policy work for direct calls, registries, and managed runtimes. Refusal produces a generic FailureKindRejected result. A Tool that owns more specific public feedback uses NewFailure at its own invocation boundary.

func NewGuard(config GuardConfig) (Guard, error)

package main

import (
	"context"
	"errors"
	"fmt"

	"github.com/Tangerg/scope/core/chat"
	"github.com/Tangerg/scope/core/tool"
)

func main() {
	executable, err := tool.NewFunc(tool.FuncConfig{Name: "inspect"}, func(context.Context, struct{}) (string, error) {
		return "inspected", nil
	})
	if err != nil {
		panic(err)
	}
	guard, err := tool.NewGuard(tool.GuardConfig{
		Tool: executable,
		Authorizer: tool.AuthorizerFunc(func(context.Context, tool.Authorization) (bool, error) {
			return false, nil
		}),
	})
	if err != nil {
		panic(err)
	}
	binding, err := tool.Bind(guard)
	if err != nil {
		panic(err)
	}
	invocation, err := binding.Contract().Prepare(chat.ToolCall{ID: "call", Name: "inspect", Arguments: `{}`})
	if err != nil {
		panic(err)
	}
	_, err = binding.Call(context.Background(), invocation)
	failure, found := errors.AsType[*tool.Failure](err)
	if !found {
		panic(err)
	}
	fmt.Println(failure.Kind())
}

Output:
rejected

func (g Guard) Call(ctx context.Context, invocation Invocation) (chat.ToolOutput, error)

func (g Guard) Definition() chat.ToolDefinition

func (g Guard) Unwrap() Tool

type GuardConfig ¶

type GuardConfig struct {
	Tool       Tool
	Authorizer Authorizer
}

type InputValidatingTool ¶ added in v0.19.0

type InputValidatingTool interface {
	// InputValidator returns an independent, immutable validator. Neither the
	// returned function nor anything it captures may retain an executable Tool
	// or execution backend. It must be deterministic, bounded, side-effect-free,
	// safe for concurrent use, and must not mutate or retain its argument.
	// Nil means the schema is the complete input admission contract.
	InputValidator() func([]byte) error
}

InputValidatingTool supplies the input admission rules that JSON Schema cannot express, such as Go numeric syntax or a custom JSON decoder's domain constraints. Bind freezes the declaration through the wrapping chain.

type InputValidationPanicError ¶ added in v0.32.0

type InputValidationPanicError struct{ Value any }

InputValidationPanicError identifies a contained panic while declaring or running input validation. Prepare still rejects the invocation with ErrInvalidInvocation; this diagnostic distinguishes a validator defect from invalid caller input. Value retains the recovered value; an error value remains available through Unwrap.

func (i *InputValidationPanicError) Error() string

func (i *InputValidationPanicError) Unwrap() error

type Invocation ¶

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

Invocation is a complete JSON object admitted by one exact frozen Tool contract. Its fields are intentionally private: only Contract.Prepare can promote an untrusted model proposal into an executable invocation.

func (i Invocation) Arguments() []byte

type Registry ¶

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

Registry is concurrency-safe with a usable zero value. Registration is atomic for the full batch and snapshots definitions; model-visible views are detached and ordered by name.

func NewRegistry(initial ...Tool) (*Registry, error)

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

func (r *Registry) Register(values ...Tool) error

func (r *Registry) Resolve(name string) (Binding, bool)

type Tool ¶

type Tool interface {
	// Definition returns a detached, valid schema snapshot. Callers may expose or
	// mutate the returned value without changing subsequent calls or execution.
	Definition() chat.ToolDefinition
	// Call executes one schema-validated invocation. Implementations still own
	// capability-specific semantic validation. Ordinary failure is returned as
	// error without assigning retry or control-flow meaning. Implementations must
	// honor ctx and must not retain the invocation or its arguments.
	// On error, the returned output is not consumed; use [Failure] to preserve
	// complete failure content, including acknowledged partial effects. Use
	// [CallError] for non-final execution evidence without asserting an outcome.
	Call(ctx context.Context, invocation Invocation) (chat.ToolOutput, error)
}

Tool executes invocations admitted by its exact frozen Contract. Errors carry no retry, pause, or abort policy; the driving runtime owns those decisions.

type WrappingTool ¶

type WrappingTool interface {
	// Unwrap returns the next inner tool in a finite decorator chain. It must
	// return the same tool for the wrapper's lifetime and must not perform I/O;
	// cycles and excessive depth make the chain invalid.
	Unwrap() Tool
}

WrappingTool exposes the decorator chain used to resolve optional capabilities.