413 lines
12 KiB
Go
413 lines
12 KiB
Go
package tools
|
|
|
|
import (
|
|
"context"
|
|
"fmt"
|
|
"maps"
|
|
"strings"
|
|
"sync"
|
|
)
|
|
|
|
// ---------------------------------------------------------------------------
|
|
// 17.14 -- Progressive tool disclosure (bridge tools)
|
|
// ---------------------------------------------------------------------------
|
|
|
|
// BridgeToolName is the set of reserved tool names used by the progressive
|
|
// disclosure bridge. These names are reserved and must not be used by
|
|
// registered tools.
|
|
const (
|
|
BridgeToolSearch = "tool_search"
|
|
BridgeToolDescribe = "tool_describe"
|
|
BridgeToolCall = "tool_call"
|
|
)
|
|
|
|
// bridgeToolNames is the complete set of reserved bridge tool names.
|
|
var bridgeToolNames = map[string]bool{
|
|
BridgeToolSearch: true,
|
|
BridgeToolDescribe: true,
|
|
BridgeToolCall: true,
|
|
}
|
|
|
|
// IsBridgeTool reports whether name is a reserved bridge tool.
|
|
func IsBridgeTool(name string) bool {
|
|
return bridgeToolNames[name]
|
|
}
|
|
|
|
// ToolSummary is a lightweight representation of a tool used in bridge
|
|
// tool search results. It contains only name, description, and emoji --
|
|
// enough for the LLM to decide whether to call tool_describe for full schema.
|
|
type ToolSummary struct {
|
|
Name string `json:"name"`
|
|
Description string `json:"description"`
|
|
Emoji string `json:"emoji,omitempty"`
|
|
}
|
|
|
|
// bridgeSearchHandler implements the tool_search bridge tool.
|
|
// It searches the registry for tools matching the given keyword.
|
|
func bridgeSearchHandler(reg *Registry) Handler {
|
|
return func(ctx context.Context, input map[string]any) (any, error) {
|
|
keyword, _ := input["keyword"].(string)
|
|
|
|
all := reg.All()
|
|
var matches []ToolEntry
|
|
for _, e := range all {
|
|
if keyword == "" || matchesKeyword(e, keyword) {
|
|
// Never return bridge tools themselves in search results.
|
|
if IsBridgeTool(e.Name) {
|
|
continue
|
|
}
|
|
matches = append(matches, e)
|
|
}
|
|
}
|
|
|
|
// Return lightweight summaries (name + description only).
|
|
summaries := make([]ToolSummary, len(matches))
|
|
for i, m := range matches {
|
|
summaries[i] = ToolSummary{
|
|
Name: m.Name,
|
|
Description: m.Description,
|
|
Emoji: m.Emoji,
|
|
}
|
|
}
|
|
return map[string]any{"tools": summaries}, nil
|
|
}
|
|
}
|
|
|
|
// matchesKeyword reports whether a tool entry matches a search keyword.
|
|
// Matching is case-insensitive and checks name, description, and toolset.
|
|
func matchesKeyword(e ToolEntry, keyword string) bool {
|
|
lower := strings.ToLower(keyword)
|
|
if strings.Contains(strings.ToLower(e.Name), lower) {
|
|
return true
|
|
}
|
|
if strings.Contains(strings.ToLower(e.Description), lower) {
|
|
return true
|
|
}
|
|
if strings.Contains(strings.ToLower(e.Toolset), lower) {
|
|
return true
|
|
}
|
|
return false
|
|
}
|
|
|
|
// bridgeDescribeHandler implements the tool_describe bridge tool.
|
|
// It returns the full schema and metadata for a single tool.
|
|
func bridgeDescribeHandler(reg *Registry) Handler {
|
|
return func(ctx context.Context, input map[string]any) (any, error) {
|
|
name, _ := input["name"].(string)
|
|
if name == "" {
|
|
return nil, fmt.Errorf("tool_describe: 'name' parameter is required")
|
|
}
|
|
|
|
all := reg.All()
|
|
for _, e := range all {
|
|
if e.Name == name {
|
|
return map[string]any{
|
|
"tool": toolDescribeResult(e),
|
|
}, nil
|
|
}
|
|
}
|
|
return nil, fmt.Errorf("tool_describe: tool %q not found", name)
|
|
}
|
|
}
|
|
|
|
// toolDescribeResult builds the describe payload for a tool.
|
|
func toolDescribeResult(e ToolEntry) map[string]any {
|
|
result := map[string]any{
|
|
"name": e.Name,
|
|
"description": e.Description,
|
|
"toolset": e.Toolset,
|
|
"emoji": e.Emoji,
|
|
"is_async": e.IsAsync,
|
|
}
|
|
if e.Schema != nil {
|
|
result["schema"] = e.ResolvedSchema()
|
|
}
|
|
if e.RequiresEnv != nil {
|
|
result["requires_env"] = e.RequiresEnv
|
|
}
|
|
return result
|
|
}
|
|
|
|
// bridgeCallHandler implements the tool_call bridge tool.
|
|
// It invokes a tool by name after discovery.
|
|
func bridgeCallHandler(reg *Registry) Handler {
|
|
return func(ctx context.Context, input map[string]any) (any, error) {
|
|
name, _ := input["name"].(string)
|
|
if name == "" {
|
|
return nil, fmt.Errorf("tool_call: 'name' parameter is required")
|
|
}
|
|
|
|
// Prevent recursive bridge calls.
|
|
if IsBridgeTool(name) {
|
|
return nil, fmt.Errorf("tool_call: cannot invoke bridge tool %q", name)
|
|
}
|
|
|
|
callInput, _ := input["input"].(map[string]any)
|
|
|
|
all := reg.All()
|
|
for _, e := range all {
|
|
if e.Name == name {
|
|
if e.Handler == nil {
|
|
return nil, fmt.Errorf("tool_call: tool %q has no handler", name)
|
|
}
|
|
if e.Classification.IsApprovalRequired() {
|
|
return nil, fmt.Errorf("tool_call: tool %q requires human approval and cannot be invoked through the bridge", name)
|
|
}
|
|
return e.Handler(ctx, callInput)
|
|
}
|
|
}
|
|
return nil, fmt.Errorf("tool_call: tool %q not found", name)
|
|
}
|
|
}
|
|
|
|
// BridgeTools returns tool_search, tool_describe and tool_call over reg.
|
|
func BridgeTools(reg *Registry) []ToolEntry {
|
|
return []ToolEntry{
|
|
{
|
|
Name: BridgeToolSearch,
|
|
Toolset: "bridge",
|
|
Description: "Search available tools by keyword. Returns matching tool names and descriptions.",
|
|
Emoji: "🔍",
|
|
Classification: ClassIdempotent,
|
|
Handler: bridgeSearchHandler(reg),
|
|
Schema: JSONSchema{
|
|
"type": "object",
|
|
"properties": JSONSchema{
|
|
"keyword": JSONSchema{
|
|
"type": "string",
|
|
"description": "Keyword to search for in tool names and descriptions",
|
|
},
|
|
},
|
|
},
|
|
},
|
|
{
|
|
Name: BridgeToolDescribe,
|
|
Toolset: "bridge",
|
|
Description: "Get the full schema and metadata for a specific tool. Use after tool_search to inspect a tool before calling it.",
|
|
Emoji: "📋",
|
|
Classification: ClassIdempotent,
|
|
Handler: bridgeDescribeHandler(reg),
|
|
Schema: JSONSchema{
|
|
"type": "object",
|
|
"properties": JSONSchema{
|
|
"name": JSONSchema{
|
|
"type": "string",
|
|
"description": "The exact name of the tool to describe",
|
|
},
|
|
},
|
|
"required": []any{"name"},
|
|
},
|
|
},
|
|
{
|
|
Name: BridgeToolCall,
|
|
Toolset: "bridge",
|
|
Description: "Invoke a tool by name. Use after tool_describe to confirm the schema.",
|
|
Emoji: "⚡",
|
|
Classification: ClassIdempotent,
|
|
Handler: bridgeCallHandler(reg),
|
|
Schema: JSONSchema{
|
|
"type": "object",
|
|
"properties": JSONSchema{
|
|
"name": JSONSchema{
|
|
"type": "string",
|
|
"description": "The exact name of the tool to invoke",
|
|
},
|
|
"input": JSONSchema{
|
|
"type": "object",
|
|
"description": "Tool input parameters (tool-specific)",
|
|
},
|
|
},
|
|
"required": []any{"name"},
|
|
},
|
|
},
|
|
}
|
|
}
|
|
|
|
// ComposeForTurn returns a new registry with reg's tools, extra and the
|
|
// bridge tools.
|
|
func ComposeForTurn(reg *Registry, extra []ToolEntry) (*Registry, error) {
|
|
composed := NewRegistry()
|
|
if reg != nil {
|
|
for _, e := range reg.All() {
|
|
if err := composed.Register(e); err != nil {
|
|
return nil, err
|
|
}
|
|
}
|
|
}
|
|
for _, e := range extra {
|
|
if err := composed.Register(e); err != nil {
|
|
return nil, err
|
|
}
|
|
}
|
|
if err := composed.RegisterBatch(BridgeTools(composed)); err != nil {
|
|
return nil, err
|
|
}
|
|
return composed, nil
|
|
}
|
|
|
|
// ---------------------------------------------------------------------------
|
|
// 17.15 -- Context-pressure threshold gating
|
|
// ---------------------------------------------------------------------------
|
|
|
|
// DisclosureMode controls whether the tool list is served in full or
|
|
// through the bridge tools (progressive disclosure).
|
|
type DisclosureMode int
|
|
|
|
const (
|
|
// DisclosureFull serves all tool schemas directly to the LLM.
|
|
DisclosureFull DisclosureMode = iota
|
|
|
|
// DisclosureBridge serves only the bridge tools (tool_search,
|
|
// tool_describe, tool_call) plus any critical always-visible tools.
|
|
DisclosureBridge
|
|
)
|
|
|
|
// ContextPressureGate monitors the size of tool schemas relative to the
|
|
// LLM context window and dynamically switches between full disclosure
|
|
// and bridge-tool mode.
|
|
type ContextPressureGate struct {
|
|
mu sync.RWMutex
|
|
|
|
// ThresholdFraction is the fraction of the context window at which
|
|
// the gate switches to bridge mode. Default 0.5 (50%).
|
|
ThresholdFraction float64
|
|
|
|
// ContextWindowSize is the total context window size in characters.
|
|
// Zero means the gate is disabled (always full disclosure).
|
|
ContextWindowSize int
|
|
|
|
// AlwaysVisible is a set of tool names that are always included in
|
|
// the tool list even in bridge mode (e.g. essential system tools).
|
|
AlwaysVisible map[string]bool
|
|
|
|
// currentMode is the active disclosure mode.
|
|
currentMode DisclosureMode
|
|
}
|
|
|
|
// NewContextPressureGate creates a [ContextPressureGate] with sensible
|
|
// defaults: 50% threshold, full disclosure until pressure is detected.
|
|
func NewContextPressureGate(contextWindowSize int) *ContextPressureGate {
|
|
return &ContextPressureGate{
|
|
ThresholdFraction: 0.5,
|
|
ContextWindowSize: contextWindowSize,
|
|
AlwaysVisible: make(map[string]bool),
|
|
currentMode: DisclosureFull,
|
|
}
|
|
}
|
|
|
|
// Evaluate scans the given tool entries and updates the disclosure mode
|
|
// based on the total schema size relative to the context window.
|
|
// Returns the current disclosure mode after evaluation.
|
|
func (g *ContextPressureGate) Evaluate(tools []ToolEntry) DisclosureMode {
|
|
g.mu.Lock()
|
|
defer g.mu.Unlock()
|
|
|
|
if g.ContextWindowSize <= 0 {
|
|
g.currentMode = DisclosureFull
|
|
return g.currentMode
|
|
}
|
|
|
|
totalSchemaChars := totalSchemaSize(tools)
|
|
threshold := int(float64(g.ContextWindowSize) * g.ThresholdFraction)
|
|
|
|
if totalSchemaChars > threshold {
|
|
g.currentMode = DisclosureBridge
|
|
} else {
|
|
g.currentMode = DisclosureFull
|
|
}
|
|
|
|
return g.currentMode
|
|
}
|
|
|
|
// FilterTools returns the set of tools that should be disclosed given the
|
|
// current mode. In full mode, all tools are returned. In bridge mode, only
|
|
// bridge tools and always-visible tools are returned.
|
|
func (g *ContextPressureGate) FilterTools(reg *Registry) []ToolEntry {
|
|
g.mu.RLock()
|
|
mode := g.currentMode
|
|
alwaysVisible := g.alwaysVisibleCopy()
|
|
g.mu.RUnlock()
|
|
|
|
all := reg.All()
|
|
|
|
if mode == DisclosureFull {
|
|
// Full disclosure serves the real arsenal directly. Bridge tools are
|
|
// the on-demand fallback -- they are only exposed under context
|
|
// pressure (bridge mode). Leaking them into full mode would inflate
|
|
// the toolset the model must carry for no benefit.
|
|
out := make([]ToolEntry, 0, len(all))
|
|
for _, e := range all {
|
|
if !IsBridgeTool(e.Name) {
|
|
out = append(out, e)
|
|
}
|
|
}
|
|
return out
|
|
}
|
|
|
|
// Bridge mode: only bridge tools + always-visible tools.
|
|
var filtered []ToolEntry
|
|
for _, e := range all {
|
|
if IsBridgeTool(e.Name) || alwaysVisible[e.Name] {
|
|
filtered = append(filtered, e)
|
|
}
|
|
}
|
|
return filtered
|
|
}
|
|
|
|
// alwaysVisibleCopy returns a copy of the always-visible set.
|
|
func (g *ContextPressureGate) alwaysVisibleCopy() map[string]bool {
|
|
out := make(map[string]bool, len(g.AlwaysVisible))
|
|
maps.Copy(out, g.AlwaysVisible)
|
|
return out
|
|
}
|
|
|
|
// totalSchemaSize estimates the total size in characters of the JSON
|
|
// schema representations for the given tools. This is a conservative
|
|
// estimate -- the actual serialized size may be slightly larger.
|
|
func totalSchemaSize(tools []ToolEntry) int {
|
|
total := 0
|
|
for _, e := range tools {
|
|
if e.Schema != nil {
|
|
total += schemaSizeEstimate(e.Schema)
|
|
}
|
|
// Also account for name + description overhead.
|
|
total += len(e.Name) + len(e.Description)
|
|
}
|
|
return total
|
|
}
|
|
|
|
// schemaSizeEstimate returns a rough character count for a schema value.
|
|
func schemaSizeEstimate(v any) int {
|
|
switch val := v.(type) {
|
|
case JSONSchema:
|
|
n := 0
|
|
for k, sv := range val {
|
|
n += len(k) + schemaSizeEstimate(sv)
|
|
}
|
|
return n
|
|
case map[string]any:
|
|
n := 0
|
|
for k, sv := range val {
|
|
n += len(k) + schemaSizeEstimate(sv)
|
|
}
|
|
return n
|
|
case []any:
|
|
n := 0
|
|
for _, item := range val {
|
|
n += schemaSizeEstimate(item)
|
|
}
|
|
return n
|
|
case string:
|
|
return len(val)
|
|
case float64:
|
|
return 8
|
|
case bool:
|
|
return 5
|
|
default:
|
|
return 20 // conservative fallback
|
|
}
|
|
}
|
|
|
|
// Ensure bridge tools implement the expected interface.
|
|
var _ = BridgeTools // prevent unused warning when bridge tools aren't registered
|