195 lines
6.8 KiB
Go
195 lines
6.8 KiB
Go
// 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"
|
||
)
|
||
|
||
// 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:
|
||
out := make([]string, len(val))
|
||
copy(out, val)
|
||
return out
|
||
case []float64:
|
||
out := make([]float64, len(val))
|
||
copy(out, val)
|
||
return out
|
||
case []bool:
|
||
out := make([]bool, len(val))
|
||
copy(out, val)
|
||
return out
|
||
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))
|
||
}
|