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)

AuthorizerFunc adapts a plain function to Authorizer, so a one-off policy does not require a named type.

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 Contract ¶ added in v0.19.0

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

Contract is the immutable trust boundary between an untrusted chat.ToolCall and a validated Invocation. It holds the frozen definition and compiled input schema and independent input validator without retaining an executable Tool. A Contract obtained from Binding.Contract 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 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 owns the derived input contract, strict argument decoding, invocation, and result encoding.

Func is immutable after construction and is safe for concurrent calls when the wrapped function is safe for concurrent calls.

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
}

FuncConfig describes a typed function tool. NewFunc derives the model-visible schema and the independent input validator from In.

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
}

GuardConfig names both collaborators explicitly so neither can be defaulted. A guard silently constructed without an authorizer would report as protected while permitting everything.

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 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 an instance-scoped, concurrency-safe collection of executable tools. Its zero value is ready to use. Each runtime or process owns its registry explicitly; there is no package-global counterpart. Registration is atomic for the full batch, definitions are snapshotted at registration time, and model-visible views are returned as defensive copies in stable name order.

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.
	Call(ctx context.Context, invocation Invocation) (chat.ToolOutput, error)
}

Tool is the minimal executable capability used by model-driven runtimes. Definition returns an independent snapshot safe to expose to a model. Call receives only an Invocation promoted by its exact frozen Contract.

Tool assigns no control-flow meaning to errors. Retry, pause, abort, and ordinary error feedback belong to the runtime driving the tool.

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 is implemented by a decorator that stands in for another tool. Optional capabilities are resolved through this chain, so a decorator states once that it wraps a tool instead of re-implementing every optional interface the inner tool may acquire.