Files
archie/internal/tools/dispatch.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

458 lines
13 KiB
Go

package tools
import (
"context"
"fmt"
"sync"
"time"
)
// ExecutionClass defines how a tool interacts with the dispatch gating engine.
type ExecutionClass int
const (
// ExecNeverParallel marks tools that must run alone -- typically state
// mutators where concurrent execution could cause corruption.
ExecNeverParallel ExecutionClass = iota
// ExecParallelSafe marks tools that can run concurrently with any
// other tool. Read-only tools (idempotent classification) are
// automatically promoted to this class.
ExecParallelSafe
// ExecPathScoped marks tools that can run in parallel with tools
// targeting different paths/scopes, but must serialize with tools
// targeting the same path.
ExecPathScoped
)
// String returns a human-readable representation of the execution class.
func (c ExecutionClass) String() string {
switch c {
case ExecNeverParallel:
return "never-parallel"
case ExecParallelSafe:
return "parallel-safe"
case ExecPathScoped:
return "path-scoped"
default:
return "unknown"
}
}
// ClassifyEntry derives the [ExecutionClass] from a [ToolEntry]'s
// classification flags. Idempotent tools are parallel-safe. Mutating
// tools are never-parallel unless explicitly marked otherwise.
// Unclassified tools default to never-parallel (conservative).
func ClassifyEntry(e ToolEntry) ExecutionClass {
if e.Classification.IsIdempotent() {
return ExecParallelSafe
}
if e.Classification.IsMutating() {
return ExecNeverParallel
}
// Conservative default: treat unclassified tools as never-parallel.
return ExecNeverParallel
}
// ---------------------------------------------------------------------------
// Dispatch types
// ---------------------------------------------------------------------------
// DispatchResult holds the outcome of a single tool invocation.
type DispatchResult struct {
// ToolName is the name of the tool that was invoked.
ToolName string
// Output is the value returned by the tool's Handler. nil when
// IsError is true.
Output any
// Preview is a truncated version of the output suitable for
// inclusion in the conversation context. It is at most 500 chars.
Preview string
// Error is the error returned by the handler, or a dispatch-level
// error (e.g. tool not found, budget exceeded).
Error error
// Duration is the wall-clock time spent executing the tool
// (handler execution only; does not include spill time).
Duration time.Duration
}
// IsError reports whether the result represents a failed invocation.
func (r DispatchResult) IsError() bool { return r.Error != nil }
// previewChars is the maximum length of a result preview.
const previewChars = 500
// truncatePreview returns a short summary of the output suitable for
// the conversation context.
func truncatePreview(output any) string {
if output == nil {
return ""
}
s := fmt.Sprint(output)
if len(s) <= previewChars {
return s
}
return s[:previewChars] + "... [truncated]"
}
// ---------------------------------------------------------------------------
// Tool invocation
// ---------------------------------------------------------------------------
// ToolCall represents a single pending tool invocation.
type ToolCall struct {
// Entry is the tool to invoke. Handler must be non-nil.
Entry ToolEntry
// Input is the deserialized JSON input to pass to the handler.
Input map[string]any
// PathScope is an optional key used by ExecPathScoped gating.
// Tools with the same non-empty PathScope are serialized.
PathScope string
}
// invokeTool executes a single tool and returns a [DispatchResult].
//
// Tools that require human approval are refused. The dispatch path has no
// ApprovalRequester — it is used by the agent execution loop, which runs
// without a human in the loop. The chat path gates approval through
// BuildToolSetFrom → toolExecute, which has the approver wired.
func invokeTool(ctx context.Context, call ToolCall) DispatchResult {
start := time.Now()
result := DispatchResult{ToolName: call.Entry.Name}
if call.Entry.Classification.IsApprovalRequired() {
result.Error = fmt.Errorf("tool %s: requires human approval and cannot be invoked through the agent dispatch path", call.Entry.Name)
return result
}
output, err := call.Entry.Handler(ctx, call.Input)
result.Duration = time.Since(start)
if err != nil {
result.Error = err
return result
}
result.Output = output
result.Preview = truncatePreview(output)
return result
}
// ---------------------------------------------------------------------------
// 17.5 -- Sequential dispatch
// ---------------------------------------------------------------------------
// DispatchSequential invokes tools one at a time, capturing per-result
// previews and classifying errors. Each result includes a truncated
// preview for inclusion in the conversation context.
//
// If budget is non-nil, each result's output size is consumed from the
// budget. When the budget is exceeded, remaining calls are skipped with
// a budget-exceeded error.
//
// If guardrail is non-nil, failures are recorded and the dispatch may
// abort early on a hard-stop decision.
func DispatchSequential(
ctx context.Context,
calls []ToolCall,
budget *TurnBudget,
guardrail *GuardrailEngine,
) []DispatchResult {
results := make([]DispatchResult, 0, len(calls))
for _, call := range calls {
// Check for hard-stop before dispatching.
if guardrail != nil && guardrail.HardStopped() {
results = append(results, DispatchResult{
ToolName: call.Entry.Name,
Error: fmt.Errorf("guardrail hard-stop active"),
})
break
}
// Check budget before dispatching. Once exceeded, skip all
// remaining calls (break, not continue -- no point appending
// redundant budget-exceeded errors for every remaining call).
if budget != nil && budget.Exceeded() {
results = append(results, DispatchResult{
ToolName: call.Entry.Name,
Error: fmt.Errorf("turn budget exceeded (%d chars)", budget.MaxChars),
})
break
}
result := dispatchOne(ctx, call, budget, guardrail)
results = append(results, result)
// Abort on hard-stop.
if guardrail != nil && guardrail.HardStopped() {
break
}
}
return results
}
// ---------------------------------------------------------------------------
// 17.6 -- Concurrent dispatch
// ---------------------------------------------------------------------------
// gatedGroup holds a set of calls that must run sequentially within the
// group but can run concurrently with other groups.
type gatedGroup struct {
calls []ToolCall
class ExecutionClass
scope string // non-empty only for ExecPathScoped
}
// DispatchConcurrent invokes tools concurrently where safe, applying
// execution gating:
//
// - ExecNeverParallel: runs alone, blocking all other execution.
// - ExecParallelSafe: runs concurrently with any other tool.
// - ExecPathScoped: same-path tools serialize, different paths run
// in parallel.
//
// Results are returned in the same order as calls.
func DispatchConcurrent(
ctx context.Context,
calls []ToolCall,
budget *TurnBudget,
guardrail *GuardrailEngine,
) []DispatchResult {
if len(calls) == 0 {
return nil
}
// Classify each call and build gating groups.
groups := buildGatingGroups(calls)
// Execute groups: never-parallel groups block all concurrency.
// Others run in parallel within their group, sequentially between groups.
results := make([]DispatchResult, len(calls))
resultIdx := 0
for _, group := range groups {
if group.class == ExecNeverParallel || len(group.calls) == 1 {
// Run sequentially.
for _, call := range group.calls {
results[resultIdx] = dispatchOne(ctx, call, budget, guardrail)
resultIdx++
}
} else {
// Run in parallel within group.
res := dispatchParallel(ctx, group.calls, budget, guardrail)
for _, r := range res {
results[resultIdx] = r
resultIdx++
}
}
}
return results
}
// buildGatingGroups partitions calls into groups based on their execution
// class. Never-parallel calls get isolated groups. Path-scoped calls share
// a group if they have the same path; otherwise they get separate groups.
// Parallel-safe calls all share one group.
//
// Groups are tracked by index (not pointer) to avoid the value-copy bug
// where appending to a map-stored pointer was invisible to the slice copy.
func buildGatingGroups(calls []ToolCall) []gatedGroup {
if len(calls) == 0 {
return nil
}
var groups []gatedGroup
// Track path-scoped groups by scope key to index in the groups slice.
pathScopedIdx := make(map[string]int)
for _, call := range calls {
class := ClassifyEntry(call.Entry)
switch class {
case ExecNeverParallel:
// Isolate: one group per never-parallel call.
groups = append(groups, gatedGroup{
calls: []ToolCall{call},
class: ExecNeverParallel,
})
case ExecPathScoped:
scope := call.PathScope
if scope == "" {
// No scope specified -- treat as never-parallel.
groups = append(groups, gatedGroup{
calls: []ToolCall{call},
class: ExecNeverParallel,
})
continue
}
if idx, ok := pathScopedIdx[scope]; ok {
// Update existing group in-place through the index.
groups[idx].calls = append(groups[idx].calls, call)
} else {
idx := len(groups)
groups = append(groups, gatedGroup{
calls: []ToolCall{call},
class: ExecPathScoped,
scope: scope,
})
pathScopedIdx[scope] = idx
}
case ExecParallelSafe:
// Batch all parallel-safe calls into one group.
if idx, ok := firstParallelSafeIdx(groups); ok {
groups[idx].calls = append(groups[idx].calls, call)
} else {
groups = append(groups, gatedGroup{
calls: []ToolCall{call},
class: ExecParallelSafe,
})
}
}
}
return groups
}
// firstParallelSafeIdx returns the index of the first parallel-safe group
// in the slice. Used by buildGatingGroups to batch parallel-safe calls.
func firstParallelSafeIdx(groups []gatedGroup) (int, bool) {
for i := range groups {
if groups[i].class == ExecParallelSafe {
return i, true
}
}
return 0, false
}
// dispatchOne runs a single call with budget, guardrail, and per-tool
// limit checks.
//
// Callers that do not own the batch cannot use this: it caps
// DispatchResult.Preview, whereas a caller handing the result straight to a
// model has to cap the payload it actually sends. [CapPayload] is the shared
// rule between the two; this sequence is specific to batch dispatch.
func dispatchOne(
ctx context.Context,
call ToolCall,
budget *TurnBudget,
guardrail *GuardrailEngine,
) DispatchResult {
// Check budget.
if budget != nil && budget.Exceeded() {
return DispatchResult{
ToolName: call.Entry.Name,
Error: fmt.Errorf("turn budget exceeded (%d chars)", budget.MaxChars),
}
}
if guardrail != nil && guardrail.HardStopped() {
return DispatchResult{
ToolName: call.Entry.Name,
Error: fmt.Errorf("guardrail hard-stop active"),
}
}
result := invokeTool(ctx, call)
// Enforce per-tool result size limit (17.4).
capped := enforcePerToolLimit(&result, call.Entry, budget)
// Track guardrail.
if guardrail != nil {
if result.IsError() {
_ = guardrail.RecordFailure(call.Entry.Name, result.Error)
} else {
_ = guardrail.RecordSuccess(call.Entry.Name)
}
}
// Consume budget.
if budget != nil && !result.IsError() {
consumeBudgetForResult(&result, call.Entry, budget, capped)
}
return result
}
// enforcePerToolLimit replaces the preview when the result exceeds the tool's
// MaxResultSizeChars, spilling to disk when the budget offers a directory and
// truncating inline otherwise. [CapPayload] owns that rule; this only decides
// whether it applies.
//
// Returns whether the result was capped, so the budget accounting below does
// not spill the same output a second time.
func enforcePerToolLimit(result *DispatchResult, entry ToolEntry, budget *TurnBudget) bool {
if result.IsError() || entry.MaxResultSizeChars <= 0 || result.Output == nil {
return false
}
fullOutput := fmt.Sprint(result.Output)
capped := CapPayload(entry.Name, fullOutput, entry.MaxResultSizeChars, budget)
if capped == fullOutput {
return false
}
result.Preview = capped
return true
}
// consumeBudgetForResult accounts for the result against the turn budget.
// When the budget is exceeded during consumption, the full output is
// spilled to disk and the preview is replaced with a spill reference.
func consumeBudgetForResult(result *DispatchResult, entry ToolEntry, budget *TurnBudget, alreadyCapped bool) {
if budget == nil || result.IsError() {
return
}
if budget.Consume(len(result.Preview)) {
return
}
// Budget exhausted on this result. Spill the full output so it is
// displaced rather than lost -- unless the per-tool limit already did,
// in which case repeating it would write a second identical file and
// orphan the first, whose path the preview already names.
if alreadyCapped || result.Output == nil {
return
}
fullOutput := fmt.Sprint(result.Output)
if ref := budget.WriteSpill(entry.Name, []byte(fullOutput)); ref.Path != "" {
result.Preview = fmt.Sprintf("[spilled to %s, %d chars]", ref.Path, ref.SizeChars)
}
}
// dispatchParallel runs multiple calls concurrently and returns results
// in the same order.
func dispatchParallel(
ctx context.Context,
calls []ToolCall,
budget *TurnBudget,
guardrail *GuardrailEngine,
) []DispatchResult {
results := make([]DispatchResult, len(calls))
var wg sync.WaitGroup
wg.Add(len(calls))
for i, call := range calls {
go func(idx int, c ToolCall) {
defer wg.Done()
results[idx] = dispatchOne(ctx, c, budget, guardrail)
}(i, call)
}
wg.Wait()
return results
}