Files
archie/internal/tools/toolentry.go
T
sam 6aa3772ce9 feat(gateway): tool-approval gate, session tools for chat, and /delete command
Adds a human-consent gate for tools marked RequiresApproval, exposes
session management as LLM-invokable chat tools, and gives the operator
/delete to retire conversations permanently.

**Tool-approval gate (internal/tools, internal/agentexec)**

- ApprovalRequester contract lives in internal/tools (not gateway) so
  agentexec can import it without pulling in the chat-adapter stack.
- ToolSetOptions.Approval wires the approver through to toolExecute.
- BuildToolSetFrom omits RequiresApproval tools when no approver is
  configured; dispatch paths (invokeTool, tool_call bridge) refuse
  them too, so the invariant holds at every indirection.
- The gate fails closed: only Approved/PermanentlyApproved pass;
  an unknown decision value from a faulty approver does not execute.
- Tool-level timeout (2 min) returns a plain error, not a context
  cancellation, so the model can report "approval timed out" instead
  of the turn aborting.
- BuildApprovalDescription callback lets a tool surface the specific
  resource being acted on ("Delete session \"abc123\"") rather than
  showing a static tool description.

**Session tools (internal/gateware/session_tools.go)**

- session_list (idempotent), session_resume (mutating), session_title
  (mutating), session_delete (mutating + RequiresApproval).
- Scoped to the current platform + channel: GetByChannel replaces
  List() so a model in chat A cannot list or manipulate chat B.
- session_title validates the session belongs to this channel before
  writing; session_resume/session_delete resolve refs against the
  channel-scoped list.
- Shared limit helper extracted to tools.ListLimit.

**Telegram approval adapter (internal/channels/telegram/approval.go)**

- telegramApprover implements ApprovalRequester via the three-button
  inline keyboard (Approve/Permanent/Deny). 2-min token expiry.
- Own map + mutex + "approval:" callback prefix — separate from the
  dangerous-command system.
- Permanent approval uses exact-match (not prefix) lookup keyed by
  action + resource description, so permanently approving "delete
  session abc123" only covers that one session, not every call to
  session_delete for 24h.

**Session lifecycle**

- /delete <session-id>: removes a session and its history. Refuses
  prefixes shorter than 4 chars even when unique. Exact ID wins over
  an ambiguous prefix. sessionTracker.forget sweeps every channel+
  thread pointing at the deleted session.
- Extracted resolveSessionRef and shortSessionID for /resume and
  /delete to share.

**Wiring**

- submitTurn builds the approver onto ctx before the LLM turn.
- chatGenerateOptions reads approver from ctx, passes it through
  ToolSetOptions.
- SessionTools built per turn on the current message, combined with
  taskTools into a single toolset.
2026-08-08 16:42:59 +10:00

207 lines
7.4 KiB
Go
Raw Permalink 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"`
// BuildApprovalDescription is called with the decoded tool inputs to
// build the human-facing prompt shown when approval is required. When
// nil (the default), the tool's Description is used verbatim.
//
// The returned string should identify the specific resource being acted
// on so the human knows what they are consenting to. A prompt that says
// only "Delete a session" is not adequate; "Delete session 'Refactor
// auth' (abc12345)" is. This runs before the handler, so only the raw
// input is available — it cannot resolve references or look up titles.
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))
}