Documentation
¶
Overview ¶
Package tools is the canonical action layer. Single-entity mutations, from a UI button, the command palette, or the MCP server, 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 ¶
Constants ¶
This section is empty.
Variables ¶
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.
var ErrUnknownTool = errors.New("unknown tool")
ErrUnknownTool is returned when a tool name is not registered.
Functions ¶
func HasConsent ¶ added in v0.4.2
HasConsent reports whether ctx was marked human-confirmed via WithConsent. Lets handlers give non-consented (agent / MCP) callers a stricter floor than an interactive user.
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 ¶
EntityResolver checks whether a referenced entity exists in live state.
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 ¶
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 ¶
List returns the tools sorted by name, for the palette and provider context.
func (*Registry) Register ¶
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
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.
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"`
ReadOnly bool `json:"readOnly"` // pure read, no state change (start/stop mutate but aren't destructive)
Handler Handler `json:"-"`
}
Tool is a single registered action.
Source Files