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.
69 lines
2.2 KiB
Go
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, "|")
|
|
}
|