tools

package

v0.5.0 Latest Latest Go to latest Published: Jun 23, 2026 License: Apache-2.0 Imports: 5 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/ParadoxInfinite/oriel

Links

Open Source Insights

Documentation ¶

Overview ¶

Package tools is the canonical action layer. Single-entity mutations — from a UI button, the command palette, the MCP server, or a future NL provider — route through Registry.Execute, which validates arguments and entity references and gates destructive tools before running the handler. (Bulk prune runs as a background job over a user-selected list; see internal/server/ops.go.) Safety lives here, in the base.

Index ¶

Variables
func HasConsent(ctx context.Context) bool
func WithConsent(ctx context.Context) context.Context
type EntityRef
type EntityResolver
type Handler
type Prop
type Registry
- func NewRegistry(resolver EntityResolver) *Registry
type Schema
- func (s Schema) Validate(args map[string]any) error
type Tool

Constants ¶

This section is empty.

Variables ¶

View Source

var ErrDestructiveLocked = errors.New("destructive action locked: open a grant window (`oriel ai allow-destructive --for 6h`) or run it from the Oriel UI")

ErrDestructiveLocked is returned when a Destructive tool is invoked by a non-interactive caller (no consent) while no grant window is open. The message tells an MCP client / assistant how to unlock.

View Source

var ErrUnknownTool = errors.New("unknown tool")

ErrUnknownTool is returned when a tool name is not registered.

Functions ¶

func HasConsent ¶ added in v0.4.2

func HasConsent(ctx context.Context) bool

HasConsent reports whether ctx was marked human-confirmed via WithConsent. Lets handlers give non-consented (agent / NL-provider) callers a stricter floor than an interactive user.

func WithConsent ¶ added in v0.4.0

func WithConsent(ctx context.Context) context.Context

WithConsent marks ctx as a human-confirmed call, allowing Destructive tools without a grant window. Set it only on genuinely interactive surfaces.

Types ¶

type EntityRef ¶

type EntityRef struct {
	Param string // argument key holding the id/name
	Kind  string // "container", "image", "volume", "network", "stack"
}

EntityRef declares that one argument references a live entity that must exist before the handler runs. The executor enforces existence via the resolver.

type EntityResolver ¶

type EntityResolver interface {
	Exists(ctx context.Context, kind, idOrName string) (bool, error)
}

EntityResolver checks whether a referenced entity exists in live state.

type Handler ¶

type Handler func(ctx context.Context, args map[string]any) (any, error)

Handler performs an action. args have already been schema-validated.

type Prop ¶

type Prop struct {
	Type        string   `json:"type"`           // "string" | "number" | "boolean"
	Enum        []string `json:"enum,omitempty"` // allowed values (strings only)
	Description string   `json:"description,omitempty"`
}

type Registry ¶

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

Registry holds the tool set and the optional entity resolver.

func NewRegistry ¶

func NewRegistry(resolver EntityResolver) *Registry

func (*Registry) Execute ¶

func (r *Registry) Execute(ctx context.Context, name string, args map[string]any) (any, error)

Execute gates, validates, and runs a single tool call: it locks destructive tools without consent or an open grant window, schema-validates args, and checks entity existence before invoking the handler.

func (*Registry) List ¶

func (r *Registry) List() []*Tool

List returns the tools sorted by name, for the palette and provider context.

func (*Registry) Register ¶

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

Register adds a tool. It panics on a duplicate name or a malformed entity ref — both programming errors caught at startup rather than at call time. The handlers rely on the schema guaranteeing the entity param is a present string, so enforce that invariant here.

func (*Registry) SetDestructiveWindow ¶ added in v0.4.0

func (r *Registry) SetDestructiveWindow(open func() bool)

SetDestructiveWindow injects the grant-window check used to authorize Destructive tools for non-interactive callers.

type Schema ¶

type Schema struct {
	Required []string        `json:"required,omitempty"`
	Props    map[string]Prop `json:"properties,omitempty"`
}

Schema is a deliberately tiny JSON-Schema subset — enough to validate the flat, typed argument maps our tools take, without pulling in a dependency.

func (Schema) Validate ¶

func (s Schema) Validate(args map[string]any) error

Validate checks required presence, types, and enum membership.

type Tool ¶

type Tool struct {
	Name        string     `json:"name"`
	Title       string     `json:"title"`
	Description string     `json:"description"`
	Schema      Schema     `json:"schema"`
	Entity      *EntityRef `json:"-"`
	Destructive bool       `json:"destructive"`
	Handler     Handler    `json:"-"`
}

Tool is a single registered action.

Source Files ¶

View all Source files

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL