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

69 lines
2.2 KiB
Go

package tools
import "strings"
// ToolClassification is a bitmask that describes a tool's behavioral
// characteristics for dispatch gating, guardrail decisions, and budget
// enforcement.
type ToolClassification int
const (
// ClassIdempotent marks a read-only tool. Idempotent tools can be
// safely retried and run in parallel with other idempotent tools.
ClassIdempotent ToolClassification = 1 << iota
// ClassMutating marks a tool that modifies external state (writes files,
// creates resources, sends messages, etc.). Mutating tools require
// serialization, checkpointing, and stricter guardrail monitoring.
ClassMutating
// RequiresApproval marks a tool that must not execute without a human
// consent decision. The dispatch layer blocks the call until an
// ApprovalRequester resolves it (approve, permanently approve, or deny).
//
// It is independent of ClassMutating: writing a file is mutating but
// not necessarily gated (the agent loop's own path enforcement handles
// that), while deleting a session is gated because it is irreversible
// on a path the model controls.
RequiresApproval
)
// IsIdempotent reports whether the classification includes the idempotent
// flag. A zero-value classification reports false.
func (c ToolClassification) IsIdempotent() bool {
return c&ClassIdempotent != 0
}
// IsMutating reports whether the classification includes the mutating flag.
// A zero-value classification reports false.
func (c ToolClassification) IsMutating() bool {
return c&ClassMutating != 0
}
// IsApprovalRequired reports whether the classification includes the
// RequiresApproval flag. A zero-value classification reports false.
func (c ToolClassification) IsApprovalRequired() bool {
return c&RequiresApproval != 0
}
// String returns a human-readable representation of the classification.
func (c ToolClassification) String() string {
if c == 0 {
return "default"
}
var parts []string
if c.IsIdempotent() {
parts = append(parts, "idempotent")
}
if c.IsMutating() {
parts = append(parts, "mutating")
}
if c.IsApprovalRequired() {
parts = append(parts, "requires_approval")
}
if len(parts) == 0 {
return "unknown"
}
return strings.Join(parts, "|")
}