Files
archie/internal/tools/toolentry.go
T

190 lines
6.7 KiB
Go
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
// Package tools is the central tool subsystem for archie-core. It defines
// the ToolEntry data type that every tool -- built-in, MCP, or plugin --
// registers with. The registry (17.2) and guardrails (17.10–17.15) are
// built on top of this type.
package tools
import (
"context"
"encoding/json"
"fmt"
"slices"
)
// JSONSchema represents a JSON Schema document describing a tool's input
// parameters. The zero value (nil) means the tool takes no parameters.
type JSONSchema map[string]any
// Handler is the function signature for executing a tool. It receives the
// caller-provided input (deserialized from JSON) and returns structured
// output. The returned error is surfaced to the caller; the output is
// serialized to JSON and included in the tool result.
type Handler func(ctx context.Context, input map[string]any) (output any, err error)
// CheckFn is a predicate that determines whether a tool is currently
// available. A nil CheckFn means the tool is always available. Return
// false to hide the tool from discovery and reject invocations.
type CheckFn func() bool
// SchemaOverrideFn mutates a tool's JSON Schema at runtime. Use it to
// inject dynamic values -- for example, enumerating MCP server names or
// filesystem paths that aren't known until the daemon starts. A nil
// override means the schema is static.
type SchemaOverrideFn func(schema JSONSchema) JSONSchema
// ToolEntry describes one tool. Fields tagged json:"-" are runtime-only.
type ToolEntry struct {
// Name uniquely identifies this tool (e.g. "read_file", "write_file",
// "mcp.github.search_repos"). Must be non-empty.
Name string `json:"name"`
// Toolset groups related tools together (e.g. "file", "git", "mcp",
// "memory", "http"). Used for progressive disclosure and guardrail
// classification. May be empty for ungrouped tools.
Toolset string `json:"toolset,omitempty"`
// Schema is the JSON Schema for the tool's input parameters. The
// schema is served to LLMs at tool-discovery time so they know how to
// construct valid invocations. nil means no parameters.
Schema JSONSchema `json:"schema,omitempty"`
// Handler executes the tool. It is a runtime field (not serialized).
// Must be non-nil for the tool to be functional.
Handler Handler `json:"-"`
// CheckFn reports whether the tool is currently available -- for
// example, an MCP server might be offline, or a required binary might
// not be installed. A nil CheckFn means always available.
CheckFn CheckFn `json:"-"`
// RequiresEnv lists environment variable names the tool needs at
// runtime (e.g. "GITHUB_TOKEN", "DOCKER_HOST"). Registration logs a
// warning for each missing variable but does not reject the tool
// (the check only matters at invocation time).
RequiresEnv []string `json:"requires_env,omitempty"`
// Classification is a bitmask describing the tool's behavioral
// characteristics (idempotent, mutating, etc.). Zero means no
// special classification. See [ToolClassification] for valid flags.
Classification ToolClassification `json:"classification,omitempty"`
// IsAsync distinguishes synchronous tools (complete immediately) from
// asynchronous ones (start a background operation and return a handle
// for polling). Default (false) is synchronous.
IsAsync bool `json:"is_async"`
// Description is a human-readable explanation of what the tool does,
// shown in tool-discovery listings. Keep to one sentence.
Description string `json:"description"`
// Emoji is a short visual indicator for the tool (e.g. "📁", "🔧",
// "🌐"). Single character or short sequence. May be empty.
Emoji string `json:"emoji,omitempty"`
// BuildApprovalDescription builds the approval prompt from the tool input.
// Nil uses Description. It should name the specific resource affected.
BuildApprovalDescription func(input map[string]any) string `json:"-"`
// MaxResultSizeChars caps this tool's result size in characters.
// Zero means use the global default from [ToolPolicy.MaxResultChars].
MaxResultSizeChars int `json:"max_result_size_chars,omitempty"`
// DynamicSchemaOverrides mutates the schema at discovery time. Use
// it to inject dynamic enum values, current paths, or live service
// lists. A nil override means the schema is served as-is.
DynamicSchemaOverrides SchemaOverrideFn `json:"-"`
}
// Validate checks the entry's required fields. It returns nil when the
// entry can be registered; otherwise an error describing the problem.
func (e ToolEntry) Validate() error {
if e.Name == "" {
return fmt.Errorf("ToolEntry.Name is required")
}
if e.Handler == nil {
return fmt.Errorf("ToolEntry.Handler is required (tool %q)", e.Name)
}
return nil
}
// Available reports whether the tool is currently usable. Returns true
// when CheckFn is nil or returns true.
func (e ToolEntry) Available() bool {
if e.CheckFn == nil {
return true
}
return e.CheckFn()
}
// ResolvedSchema returns the tool's schema after applying any dynamic
// overrides. When DynamicSchemaOverrides is nil the static schema is
// returned unchanged.
func (e ToolEntry) ResolvedSchema() JSONSchema {
if e.DynamicSchemaOverrides == nil {
return e.Schema
}
return e.DynamicSchemaOverrides(e.Schema)
}
// Clone returns a deep copy of the entry. Handler, CheckFn, and
// DynamicSchemaOverrides are shared (not deep-copied). Schema is
// recursively deep-copied so that nested maps and slices are
// independent from the original.
func (e ToolEntry) Clone() ToolEntry {
clone := e
if e.RequiresEnv != nil {
clone.RequiresEnv = make([]string, len(e.RequiresEnv))
copy(clone.RequiresEnv, e.RequiresEnv)
}
if e.Schema != nil {
clone.Schema = deepCopySchema(e.Schema)
}
return clone
}
// deepCopySchema recursively copies a JSONSchema value, ensuring nested
// maps and slices are independent from the source.
func deepCopySchema(s JSONSchema) JSONSchema {
out := make(JSONSchema, len(s))
for k, v := range s {
out[k] = deepCopyAny(v)
}
return out
}
// deepCopyAny copies a value that may be a nested map, slice, or scalar.
func deepCopyAny(v any) any {
switch val := v.(type) {
case JSONSchema:
return deepCopySchema(val)
case map[string]any:
out := make(map[string]any, len(val))
for mk, mv := range val {
out[mk] = deepCopyAny(mv)
}
return out
case []any:
out := make([]any, len(val))
for i, item := range val {
out[i] = deepCopyAny(item)
}
return out
case []string:
return slices.Clone(val)
case []float64:
return slices.Clone(val)
case []bool:
return slices.Clone(val)
default:
return v
}
}
// MarshalJSON implements json.Marshaler, stripping runtime-only fields so
// that a ToolEntry can be serialized for debugging without panicking on
// the function fields.
func (e ToolEntry) MarshalJSON() ([]byte, error) {
type wire ToolEntry // avoid recursion
return json.Marshal(wire(e))
}