Files
archie/internal/tools/toolentry.go
T
sam f73b2d1c8c feat: memory manager sync/prefetch/scan/shutdown + broad in-flight epic work
Checkpoint commit covering concurrent work across several archie-core-abg
epics to avoid losing in-progress state:

- Memory manager (18.7-18.16): background sync pipeline, prefetch with
  timeout, memory-write notification, threat scanning, shutdown drain
  with abandoned-write tracking, frozen snapshot pattern. Wired
  ScanContent and NotifyMemoryToolWrite into HandleToolCall so scanning
  and notification actually apply to writes, not just exist as unused
  primitives.
- Fixed a literal unresolved merge-conflict that had been committed to
  internal/memory/scrubber/scrubber.go.
- Tool provider/registry, MCP client/transport (stdio, HTTP, SSE),
  multimodal results, disclosure.
- Pairing device auth store, rate limiting.
- Gateway compression, session store, tasks.
- Various workflow, plugin host, and agentexec updates.
2026-07-27 03:34:46 +10:00

196 lines
6.8 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"
)
// 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 is the foundational data type for the tools subsystem. Every
// tool -- built-in, MCP server, plugin-provided, or dynamically registered
//
// -- is represented by a ToolEntry. Fields with `json:"-"` tags are
//
// runtime-only (not serialized).
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"`
// 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))
}