tool

type Admission ¶ added in v0.60.0

type Admission struct {
	IdempotencyKey IdempotencyKey
	// Continuation answers the InputRequest committed by this same logical
	// call; nil starts a new call.
	Continuation *Continuation
}

Admission is what the driving runtime, never the proposer, asserts about one call. It is separate from Request because a model can forge arguments but must not be able to choose the identity external systems deduplicate on.

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() Definition

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, middlewares ...CallMiddleware) (Binding, error)

func (b Binding) Call(ctx context.Context, invocation Invocation) (Result, 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() Output

func (c *CallError) Unwrap() error

func (c *CallError) Validate() error

type CallErrorConfig ¶ added in v0.38.0

type CallErrorConfig struct {
	Cause    error
	Evidence Output
}

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

type CallMiddleware ¶ added in v0.60.0

type CallMiddleware func(Caller) Caller

CallMiddleware may reject or synchronously forward an invocation once. It preserves invocation identity and cannot manufacture a continuation. A middleware that adds business effects needs a new Tool contract; transparent composition cannot inherit replay guarantees for additional external work. Bind invokes the factory for each call, so it must be concurrency-safe and leave the lifetime of shared resources with its constructor or host.

type Caller ¶ added in v0.60.0

type Caller interface {
	Call(context.Context, Invocation) (Result, error)
}

Caller executes one admitted invocation. A completed result is not replaced by cancellation observed after execution; ordinary errors prove no outcome.

type CallerFunc ¶ added in v0.60.0

type CallerFunc func(context.Context, Invocation) (Result, error)

func (c CallerFunc) Call(ctx context.Context, invocation Invocation) (Result, error)

type Continuation ¶ added in v0.54.0

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

Continuation is the immutable checkpoint and validated answer for one logical call. Passing a context does not pass this business input.

func (c Continuation) Response() json.RawMessage

func (c Continuation) State() json.RawMessage

type Contract ¶ added in v0.19.0

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

Contract is the immutable trust boundary from an untrusted Request 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() Definition

func (c Contract) Effect() Effect

func (c Contract) Name() string

func (c Contract) Prepare(call Request, admission Admission) (Invocation, error)

func (c Contract) ValidateResult(result Result) error

type Definition ¶ added in v0.59.0

type Definition struct {
	Name         string          `json:"name"`
	Description  string          `json:"description,omitempty"`
	InputSchema  json.RawMessage `json:"input_schema"`
	OutputSchema json.RawMessage `json:"output_schema,omitzero"`
	Effect       Effect          `json:"effect,omitzero"`
}

Definition is a detached wire snapshot. Validation and executable binding compile the same schema contract, so advertising a tool cannot bypass it.

func (d Definition) Clone() Definition

func (Definition) JSONSchemaModel() any

func (d Definition) MarshalJSON() ([]byte, error)

func (d *Definition) UnmarshalJSON(data []byte) error

func (d Definition) Validate() error

type Effect ¶ added in v0.60.0

type Effect string

Effect is a replay promise, independent of concurrency and the outcome of a particular call. Idempotent requires durable backend deduplication under the same nonzero IdempotencyKey, including intervening calls; assigning a value twice is not sufficient. Safe calls request no mutation of application state; incidental accounting and telemetry do not authorize repeated business effects.

const (
	EffectUnsafe     Effect = ""
	EffectIdempotent Effect = "idempotent"
	EffectSafe       Effect = "safe"
)

func (e Effect) Replayable() bool

func (e Effect) Valid() bool

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 ClassifyFailure(err error) (*Failure, bool)

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

package main

import (
	"errors"
	"fmt"

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

func main() {
	failure, err := tool.NewFailure(tool.FailureConfig{
		Kind: tool.FailureKindRejected, Cause: errors.New("internal authorization diagnostic"),
		Output: tool.NewTextOutput("this operation is not permitted"),
	})
	if err != nil {
		panic(err)
	}
	wrapped := fmt.Errorf("tool call: %w", failure)
	result, found := tool.ClassifyFailure(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() Output

func (f *Failure) Validate() error

type FailureConfig ¶ added in v0.23.0

type FailureConfig struct {
	Kind   FailureKind
	Output Output
	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 composes a Signature with a function of the call's arguments. A Tool whose effect depends on the call itself, such as one deduplicating on its IdempotencyKey or resuming a Continuation, implements Tool around a Signature instead, because those facts belong to the Invocation.

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) (Result, error)

func (f Func[In, Out]) Definition() Definition

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

type FuncConfig ¶

type FuncConfig struct {
	Name        string
	Description string
	Effect      Effect
}

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"
	"fmt"

	"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{
		Authorizer: tool.AuthorizerFunc(func(context.Context, tool.Authorization) (bool, error) {
			return false, nil
		}),
	})
	if err != nil {
		panic(err)
	}
	binding, err := tool.Bind(executable, guard.Call)
	if err != nil {
		panic(err)
	}
	invocation, err := binding.Contract().Prepare(tool.Request{Name: "inspect", Arguments: `{}`}, tool.Admission{})
	if err != nil {
		panic(err)
	}
	_, err = binding.Call(context.Background(), invocation)
	failure, found := tool.ClassifyFailure(err)
	if !found {
		panic(err)
	}
	fmt.Println(failure.Kind())
}

Output:
rejected

func (g Guard) Call(next Caller) Caller

type GuardConfig ¶

type GuardConfig struct {
	Authorizer Authorizer
}

type IdempotencyKey ¶ added in v0.60.0

type IdempotencyKey string

IdempotencyKey names one logical call across its replays and continuations, so a backend with external effects can deduplicate them. It is opaque: a Tool may forward it to third parties, so it never encodes runtime structure. The zero value means the caller has no durable identity for the call.

type InputRejection ¶ added in v0.60.0

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

InputRejection declares model-correctable input with an explicitly public message. Cause is diagnostic only and cannot supply a different rejection, execution outcome, or control signal through errors.Is or errors.As.

func ClassifyInputRejection(err error) (*InputRejection, bool)

func NewInputRejection(config InputRejectionConfig) (*InputRejection, error)

func (i *InputRejection) Cause() error

func (i *InputRejection) Error() string

func (i *InputRejection) Is(target error) bool

func (i *InputRejection) Message() string

func (i *InputRejection) Validate() error

type InputRejectionConfig ¶ added in v0.60.0

type InputRejectionConfig struct {
	Message string
	Cause   error
}

type InputRequest ¶ added in v0.54.0

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

InputRequest freezes the prompt, answer contract, and Tool-owned checkpoint. The driving runtime binds it to one logical call and owns its wait identity.

func NewInputRequest(config InputRequestConfig) (InputRequest, error)

package main

import (
	"fmt"

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

func main() {
	schema, err := jsonschema.Parse([]byte(`{"type":"boolean"}`))
	if err != nil {
		panic(err)
	}
	request, err := tool.NewInputRequest(tool.InputRequestConfig{
		Prompt: []byte(`"Approve the write?"`), ResponseSchema: schema, ContinuationState: []byte(`{"record":"draft"}`),
	})
	if err != nil {
		panic(err)
	}
	result := tool.Result{InputRequest: &request}
	continuation, err := result.InputRequest.Continuation([]byte(`true`))
	if err != nil {
		panic(err)
	}
	// The runtime persists the checkpoint and routes this answer to the same
	// call through binding.Contract().Prepare(call, tool.Admission{Continuation: &continuation}).
	fmt.Println(string(continuation.State()), string(continuation.Response()))
}

Output:
{"record":"draft"} true

func (i InputRequest) Continuation(response json.RawMessage) (Continuation, error)

func (InputRequest) JSONSchemaModel() any

func (i InputRequest) MarshalJSON() ([]byte, error)

func (i InputRequest) Prompt() json.RawMessage

func (i InputRequest) ResponseSchema() jsonschema.Schema

func (i InputRequest) State() json.RawMessage

func (i *InputRequest) UnmarshalJSON(data []byte) error

func (i InputRequest) Valid() bool

type InputRequestConfig ¶ added in v0.54.0

type InputRequestConfig struct {
	Prompt            json.RawMessage
	ResponseSchema    jsonschema.Schema
	ContinuationState json.RawMessage
}

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.
	// Return an InputRejection only for model-correctable input. Its Message is
	// public; ordinary errors and panics are internal validator defects.
	// 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 captures the declaration directly from the executable before composing middleware.

type InputValidationError ¶ added in v0.60.0

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

InputValidationError contains a defect in an input validator. It carries no public input correction or execution outcome. Inspect Cause explicitly for diagnostics, including a contained InputValidationPanicError.

func (i *InputValidationError) Cause() error

func (*InputValidationError) Error() string

type InputValidationPanicError ¶ added in v0.32.0

type InputValidationPanicError struct{ Value any }

InputValidationPanicError identifies a contained panic while declaring or running input validation. It is retained only behind InputValidationError.Cause; this diagnostic cannot turn a panic into public input rejection or execution evidence. 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

func (i Invocation) Continuation() (Continuation, bool)

func (i Invocation) Definition() Definition

func (i Invocation) IdempotencyKey() IdempotencyKey

type Output ¶ added in v0.59.0

type Output struct {
	Content []corecontent.Block `json:"content,omitempty"`
	Details json.RawMessage     `json:"details,omitzero"`
}

Output is the provider-neutral value produced by a Tool. Content is the model-visible ordered text/media representation. Details is optional JSON for structured consumers; providers use its encoded JSON as the model-visible fallback only when Content is empty.

func NewJSONOutput(value json.RawMessage) (Output, error)

func NewTextOutput(text string) Output

func (o Output) Clone() Output

func (Output) JSONSchemaModel() any

func (o Output) MarshalJSON() ([]byte, error)

func (o Output) Text() (string, bool)

func (o *Output) UnmarshalJSON(data []byte) error

func (o Output) Validate() error

type Progress ¶ added in v0.60.0

type Progress struct {
	Completed float64 `json:"completed"`
	Total     float64 `json:"total,omitzero"`
	Message   string  `json:"message,omitzero"`
}

Progress reports how far one call has advanced. Total is zero when the Tool cannot bound its work.

func (p Progress) Validate() error

type ProgressReporter ¶ added in v0.60.0

type ProgressReporter interface {
	ReportProgress(ctx context.Context, progress Progress) error
}

ProgressReporter delivers a call's Progress to the driver that asked for it. Progress is observation only: it never changes the call's outcome.

type ProgressReporterFunc ¶ added in v0.60.0

type ProgressReporterFunc func(ctx context.Context, progress Progress) error

func (p ProgressReporterFunc) ReportProgress(ctx context.Context, progress Progress) error

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 ...Binding) (*Registry, error)

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

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

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

type Request ¶ added in v0.59.0

type Request struct {
	Name      string
	Arguments string
}

Request is an untrusted proposal. A provider correlation ID belongs to its transport; execution requires admission by the exact frozen Contract.

func (r Request) Input() []byte

func (r Request) Validate() error

type Result ¶ added in v0.54.0

type Result struct {
	Output       Output
	InputRequest *InputRequest
}

Result is either a completed output or a request for external input. An input request carries no completed output. Errors describe execution failure, never suspension; the runtime alone owns committing and resuming a logical call. The zero result completes with an empty output.

func (r Result) Validate() error

type Signature ¶ added in v0.60.0

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

Signature owns the typed codec and both of its schema projections. Custom decoders must be deterministic, bounded and free of external effects because admission uses the same decoder before execution. Admission of a typed input is that strict decode followed by the input's own Validate method when it declares one, so a request type states its domain rules once. Validate must explicitly return an InputRejection for model-correctable input; other errors are internal defects. Output bypasses the JSON codec to preserve media. Strings are text-only outputs and declare no Details schema; other values encode into Details under the reflected output schema. The declared output type selects the codec once, so interface values cannot change the advertised output contract at runtime.

func NewSignature[In, Out any]() (Signature[In, Out], error)

func (s Signature[In, Out]) Decode(invocation Invocation) (In, error)

func (s Signature[In, Out]) Encode(output Out) (Output, error)

func (s Signature[In, Out]) InputSchema() json.RawMessage

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

func (s Signature[In, Out]) OutputSchema() json.RawMessage

type Tool ¶

type Tool interface {
	Caller
	// Definition returns a detached, valid schema snapshot. Callers may expose or
	// mutate the returned value without changing subsequent calls or execution.
	Definition() Definition
}

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