tool

Documentation

Overview

Package tool defines ub's local tool surface: a Tool interface, risk taxonomy, preview protocol and a Registry for assembling the set of tools an agent loop can call.

This package only carries interfaces, value types and a plain map-backed Registry. It does not implement any concrete tool, does not dispatch calls, does not enforce mode or permission policy, and is NOT safe for concurrent registration: callers are expected to wire the Registry during process startup before any goroutine consumes it.

Index

• Constants
• func RelToRoot(root, abs string) (string, error)
• func Resolve(root, path string) (string, error)
• func SessionIDFromContext(ctx context.Context) string
• func SubagentDepthFromContext(ctx context.Context) int
• func UnmarshalArgs(raw json.RawMessage, dst any) error
• func WithSessionID(ctx context.Context, sessionID string) context.Context
• func WithSubagentDepth(ctx context.Context, depth int) context.Context
• func WithSubagentRunner(ctx context.Context, runner SubagentRunner) context.Context
• type BoolArg
  • func (BoolArg) JSONSchemaAlias() any
  • func (a *BoolArg) UnmarshalJSON(raw []byte) error
• type FileChange
• type FileDiff
• type IntArg
  • func (IntArg) JSONSchemaAlias() any
  • func (a *IntArg) UnmarshalJSON(raw []byte) error
• type Preview
• type PreviewableTool
• type Registry
  • func New() *Registry
  • func (r *Registry) All() []Tool
  • func (r *Registry) Get(name string) (Tool, bool)
  • func (r *Registry) Register(t Tool) error
  • func (r *Registry) Schemas() map[string]*jsonschema.Schema
• type Result
• type Risk
• type StreamEvent
• type StreamEventKind
• type StreamingTool
• type SubagentRunner
  • func SubagentRunnerFromContext(ctx context.Context) SubagentRunner
• type Tool

Constants

const (
	// KindCreate marks a file that will be (or was) newly created.
	KindCreate = "create"
	// KindModify marks an in-place modification of an existing file.
	KindModify = "modify"
	// KindDelete marks a file that will be (or was) removed.
	KindDelete = "delete"
)

Functions

func RelToRoot

func RelToRoot(root, abs string) (string, error)

RelToRoot returns the POSIX-style relative path from root to abs. abs MUST already be a path under root (e.g. produced by Resolve).

func Resolve

func Resolve(root, path string) (string, error)

Resolve normalizes path relative to root and returns its cleaned absolute form. It rejects any path that escapes root via "..", whether the input was relative or absolute. The returned path is always an absolute path under root.

Resolve is shared by the local tool packages (fs, search, ...) so every tool enforces the same workspace sandbox.

func SessionIDFromContext

func SessionIDFromContext(ctx context.Context) string

SessionIDFromContext returns the session id previously installed by WithSessionID, or "" if none.

func SubagentDepthFromContext

func SubagentDepthFromContext(ctx context.Context) int

SubagentDepthFromContext returns the current depth, defaulting to 0 (= root agent) when no value has been installed.

func UnmarshalArgs

func UnmarshalArgs(raw json.RawMessage, dst any) error

UnmarshalArgs decodes model-emitted tool arguments. Some providers/models occasionally wrap the entire argument object as a JSON string; accept that form while preserving normal JSON object schemas.

func WithSessionID

func WithSessionID(ctx context.Context, sessionID string) context.Context

WithSessionID returns a child context that carries the agent session id. Empty session ids are dropped: callers can blindly call this without branching, and consumers will simply see "no session id" instead of an empty string they need to special-case.

func WithSubagentDepth

func WithSubagentDepth(ctx context.Context, depth int) context.Context

WithSubagentDepth marks how many levels of nested task tool calls have stacked up on this ctx so far. The task tool uses this to reject recursive sub-agents beyond the depth budget.

func WithSubagentRunner

func WithSubagentRunner(ctx context.Context, runner SubagentRunner) context.Context

WithSubagentRunner returns a child context that carries runner. A nil runner is dropped: callers can blindly forward an unset runner without branching, and tools see "no runner" instead of a typed-nil interface.

Types

type BoolArg

type BoolArg bool

BoolArg is a boolean tool argument that tolerates "true"/"false" strings while still advertising a boolean JSON schema.

func (BoolArg) JSONSchemaAlias

func (BoolArg) JSONSchemaAlias() any

func (*BoolArg) UnmarshalJSON

func (a *BoolArg) UnmarshalJSON(raw []byte) error

type FileChange

type FileChange struct {
	Path        string `json:"path"`
	Kind        string `json:"kind"`
	UnifiedDiff string `json:"unified_diff,omitempty"`
}

FileChange mirrors FileDiff at execution time. UnifiedDiff is optional because non-file tools, read-only tools, or external integrations may only be able to report a path/kind summary.

type FileDiff

type FileDiff struct {
	Path        string `json:"path"`
	Kind        string `json:"kind"`
	UnifiedDiff string `json:"unified_diff,omitempty"`
}

FileDiff describes one file's planned change. Kind is one of the Kind* constants below.

type IntArg

type IntArg int

IntArg is an integer tool argument that tolerates model-emitted numeric strings while still advertising an integer JSON schema.

func (IntArg) JSONSchemaAlias

func (IntArg) JSONSchemaAlias() any

func (*IntArg) UnmarshalJSON

func (a *IntArg) UnmarshalJSON(raw []byte) error

type Preview

type Preview struct {
	Summary string     `json:"summary"`
	Files   []FileDiff `json:"files,omitempty"`
}

Preview is the human-facing description of what a write-class tool is about to do. It is computed without touching disk state.

type PreviewableTool

type PreviewableTool interface {
	Tool
	Preview(ctx context.Context, args json.RawMessage) (Preview, error)
}

PreviewableTool is an optional interface implemented by write-class tools. The dispatcher detects it via a type assertion (not via Risk) and calls Preview before Execute so the permission UI can render a diff/summary for the user to approve.

type Registry

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

Registry stores Tool instances keyed by Name().

Registry is intentionally not safe for concurrent registration: callers register the full tool set during startup, then hand a read-only view to the agent runtime. Concurrent reads of Get/All/Schemas are safe as long as no Register happens in parallel.

func New

func New() *Registry

New returns an empty Registry.

func (*Registry) All

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

All returns all registered tools in stable order (ascending by name).

func (*Registry) Get

func (r *Registry) Get(name string) (Tool, bool)

Get returns the tool registered under name. The boolean reports whether the lookup hit.

func (*Registry) Register

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

Register adds t to the registry. Returns a non-nil error if a tool with the same Name() is already registered; in that case the original instance is kept.

func (*Registry) Schemas

func (r *Registry) Schemas() map[string]*jsonschema.Schema

Schemas returns the input JSON Schema for every registered tool, keyed by tool name. The keys are exactly the names returned by All().

type Result

type Result struct {
	Content        string       `json:"content"`
	IsError        bool         `json:"is_error,omitempty"`
	Files          []FileChange `json:"files,omitempty"`
	FullContent    string       `json:"-"`
	Truncated      bool         `json:"truncated,omitempty"`
	OriginalBytes  int          `json:"original_bytes,omitempty"`
	FullOutputPath string       `json:"full_output_path,omitempty"`
}

Result is the value a tool returns from Execute. Content is the text that will be fed back to the model as the tool_result. IsError lets a tool report a business-level failure without raising a Go error, so the dispatcher still routes the message to the model. Files is an optional summary of disk changes (post-execution) that the dispatcher may surface in the UI.

type Risk

type Risk string

Risk classifies a tool's side-effect profile. The agent dispatcher uses it to decide whether a call goes through plan-mode gating, permission approval, or executes directly.

const (
	// RiskSafe tools are read-only over local state (read, ls, grep, glob).
	RiskSafe Risk = "safe"
	// RiskWrite tools mutate workspace files (write, edit).
	RiskWrite Risk = "write"
	// RiskExec tools spawn external processes (bash, job_run).
	RiskExec Risk = "exec"
)

type StreamEvent

type StreamEvent struct {
	Kind StreamEventKind
	Data string
}

StreamEvent is one incremental output chunk from a streaming tool. The dispatcher forwards each event into the agent EventSink as an EventToolPartialOutput so the TUI can render running progress.

type StreamEventKind

type StreamEventKind string

StreamEventKind classifies a streamed chunk.

const (
	// StreamStdout marks a chunk that came out of the tool's stdout-like
	// channel.
	StreamStdout StreamEventKind = "stdout"
	// StreamStderr marks an stderr-like channel chunk.
	StreamStderr StreamEventKind = "stderr"
	// StreamInfo marks an out-of-band tool progress note (start, kill
	// reason, etc.).
	StreamInfo StreamEventKind = "info"
)

type StreamingTool

type StreamingTool interface {
	Tool
	ExecuteStream(ctx context.Context, args json.RawMessage, events chan<- StreamEvent) (Result, error)
}

StreamingTool is an optional interface implemented by long-running tools (bash, future job_output --follow) that want to push partial output to the TUI before Execute finishes. Implementations MUST still implement Execute as a fallback for callers that don't drive streaming. The dispatcher detects StreamingTool via a type assertion; tools that don't implement it keep their existing blocking Execute semantics.

type SubagentRunner

type SubagentRunner interface {
	RunSubagent(ctx context.Context, prompt string, maxTurns int) (string, error)
}

SubagentRunner is implemented by the agent runtime layer to dispatch a child agent run for one prompt. The `task` tool calls into it via the ctx helpers below so the tool package does not import `agent`.

func SubagentRunnerFromContext

func SubagentRunnerFromContext(ctx context.Context) SubagentRunner

SubagentRunnerFromContext returns the previously installed runner, or nil if none.

type Tool

type Tool interface {
	Name() string
	Description() string
	Schema() *jsonschema.Schema
	Risk() Risk
	Execute(ctx context.Context, args json.RawMessage) (Result, error)
}

Tool is the contract every local or MCP-backed tool implements.

Schema returns the JSON Schema of the tool's input arguments. The returned value MUST marshal to valid JSON; agent loops forward it to providers as part of the request's tool definitions.