tool

Documentation

Overview

Package tool defines the core tool execution framework for ore.

It provides the universal contracts for tool registration (Registry), tool functions (ToolFunc), remote tool sources (RemoteSource), and schema validation (ValidateSchema).

Sandboxes

Sandbox interfaces enable per-tool-call isolation. The handler resolves a sandbox for each tool call and passes it to the ToolFunc. Tools opt into available capabilities via type assertions on the received Sandbox.

• Sandbox — base interface with Name(). A nil Sandbox means no isolation; tools execute against the host filesystem and process space.
• FileSandbox — extends Sandbox with ResolvePath(path) (string, error) and WorkingDirectory() string. Tools type-assert to FileSandbox when they need path resolution and working directory constraints.
• ExecSandbox — extends Sandbox with Run(ctx, cmd, dir, timeout) which delegates command execution to the sandbox. Tools type-assert to ExecSandbox when they need process isolation.

SandboxRegistry (see registry.go) extends Registry with methods to register, look up, and set a default sandbox. Handlers type-assert the registry to SandboxRegistry to resolve sandboxes per tool call. If the registry does not implement SandboxRegistry, all tool calls receive a nil sandbox.

Concrete tool implementations, discovery mechanisms, and the loop.Handler bridge live in the x/tool/ extension packages. This package defines only the contracts that core packages (cognitive/, session/, loop/) can import without creating dependency cycles.

This separation is intentional: placing the handler bridge in x/tool/ prevents the core contracts from importing loop/ or provider/, preserving the framework's cycle-free dependency graph.

The default in-memory Registry implementation is analogous to state.Buffer: it is not goroutine-safe, and concurrency control is a future middleware concern.

Index

• func ValidateSchema(schema map[string]any) error
• type Example
• type ExecSandbox
• type FileSandbox
• type Option
  • func WithMCPServer(source RemoteSource) Option
• type Registry
  • func NewRegistry(opts ...Option) Registry
• type RemoteSource
• type Sandbox
• type SandboxRegistry
• type Tool
• type ToolFunc

Functions

func ValidateSchema

func ValidateSchema(schema map[string]any) error

ValidateSchema checks that a JSON Schema intended for OpenAI-compatible function calling is structurally sound. It returns a descriptive error if the schema violates common requirements.

Rules:

• nil or empty schema is valid (no parameters).
• The schema must be JSON-serializable.
• If the schema has any keys, the root type must be "object".
• All top-level keys must be known JSON Schema keywords; any other key is treated as a misplaced parameter definition and results in an error.

Types

type Example

type Example struct {
	// Input is the JSON arguments passed to the tool.
	Input map[string]any
	// Output is the expected result produced by the tool.
	Output any
	// Explanation is a human-readable note describing why the example
	// produces the given output.
	Explanation string
}

Example describes a single few-shot usage example for a tool.

type ExecSandbox

type ExecSandbox interface {
	Sandbox
	Run(ctx context.Context, cmd, dir string, timeout time.Duration) (stdout, stderr string, exitCode int, err error)
}

ExecSandbox provides process isolation for tool execution. Tools type-assert the received Sandbox to ExecSandbox when they need to delegate command execution to the sandbox.

type FileSandbox

type FileSandbox interface {
	Sandbox
	ResolvePath(path string) (string, error)
	WorkingDirectory() string
}

FileSandbox provides filesystem isolation for tool execution. Tools type-assert the received Sandbox to FileSandbox when they need path resolution or working directory constraints.

type Option

type Option func(*registry)

Option is a functional-options setter that configures a Registry instance at creation time.

func WithMCPServer

func WithMCPServer(source RemoteSource) Option

WithMCPServer registers a remote tool source with the registry. Remote tools are namespaced under the source's Name() prefix.

type Registry

type Registry interface {
	// Register adds a tool to the registry.
	Register(t Tool, fn ToolFunc) error
	// Tools returns a merged list of all registered tools.
	Tools() []Tool
	// Lookup returns the tool descriptor, the tool function, and true if the
	// tool is registered locally.
	Lookup(name string) (Tool, ToolFunc, bool)
	// LookupRemoteSource finds a remote source by its namespace prefix.
	LookupRemoteSource(namespace string) RemoteSource
}

Registry is the interface for tool registration and lookup.

func NewRegistry

func NewRegistry(opts ...Option) Registry

NewRegistry creates an empty tool registry ready for tool registration. The returned registry is not safe for concurrent use; callers must serialize accesses or provide their own synchronization.

type RemoteSource

type RemoteSource interface {
	// Name returns the namespace prefix for tools from this source.
	Name() string
	// Tools returns the list of tools available from this source (un-namespaced).
	Tools() []Tool
	// Call invokes a tool by name with the given arguments.
	Call(ctx context.Context, name string, args map[string]any) (any, error)
}

RemoteSource represents an external source of tools (e.g., an MCP server). The Registry consumes this interface without importing the concrete MCP package, allowing clean extension without import cycles.

type Sandbox

type Sandbox interface {
	Name() string
}

Sandbox is the base interface for all sandbox implementations. A nil sandbox means no isolation (tools execute against the host).

type SandboxRegistry

type SandboxRegistry interface {
	Registry
	// RegisterSandbox adds a named sandbox to the registry. If a sandbox with
	// the same name already exists, it is overwritten.
	RegisterSandbox(name string, sb Sandbox)
	// SetDefaultSandbox sets the default sandbox used when no explicit
	// "sandbox" argument is present in a tool call.
	SetDefaultSandbox(sb Sandbox)
	// LookupSandbox returns the named sandbox and true if found.
	LookupSandbox(name string) (Sandbox, bool)
	// DefaultSandbox returns the default sandbox (may be nil).
	DefaultSandbox() Sandbox
}

SandboxRegistry extends Registry with sandbox management capabilities. Handlers type-assert the registry to SandboxRegistry to resolve sandboxes per tool call. If the registry does not implement this interface, all tool calls receive a nil sandbox.

type Tool

type Tool struct {
	Name        string
	Description string
	// Schema defines the JSON Schema for the tool's parameters.
	Schema map[string]any
	// DisplayHint is an optional formatter that receives parsed JSON
	// arguments and returns a displayable value (implementing
	// MarkdownRenderer / LLMRenderer). When nil, conduits fall back to
	// raw JSON Arguments.
	DisplayHint func(map[string]any) any
	// Examples is an optional list of few-shot input/output pairs that
	// illustrate how the tool should be used. They are not sent to the
	// provider by default; applications may opt-in via systemprompt
	// transforms or other middleware.
	Examples []Example
}

Tool describes a callable tool exposed to an LLM provider.

type ToolFunc

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

ToolFunc is a callable tool implementation. It receives a resolved sandbox (may be nil if no sandbox is configured) and parsed JSON arguments as a map[string]any and returns any result value, which is JSON-serialized before being sent back to the LLM.