Files
sam f2b8681611 refactor(workflow): stop assuming a human decides
An approval, ask or park can be resolved by an operator, a rule, a
classifier or automatically, so the vocabulary stops naming a person:

- step type human.approve -> workflow.approve
- park class needs_human -> needs_decision (ParkNeedsDecision)
- event kinds human_* -> operator_*
- alert kind task.needs_human -> task.needs_decision
- status grouping "needs you" -> "needs attention"

0061 rewrites the stored values, including the approval step type in the
workflow-definitions resource and each task's pinned definition, with the
digest recomputed so resumed tasks still match.
2026-10-25 17:31:16 +11:00

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 operator 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: ClassMutating, // it can invoke any tool
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