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.
322 lines
12 KiB
Go
322 lines
12 KiB
Go
package gateway
|
|
|
|
import (
|
|
"context"
|
|
"fmt"
|
|
"slices"
|
|
"strings"
|
|
"time"
|
|
|
|
"github.com/samcharles93/archie-core/internal/tools"
|
|
)
|
|
|
|
const (
|
|
// defaultSessionListLimit is how many sessions a bare session_list returns.
|
|
defaultSessionListLimit = 20
|
|
|
|
// maxSessionListLimit bounds what the model can ask for. A chat that has
|
|
// churned for months could otherwise land its whole session catalog in the
|
|
// context window whole.
|
|
maxSessionListLimit = 100
|
|
|
|
// maxSessionTitleLen bounds the title session_title will accept. Titles are
|
|
// rendered in command replies and the dashboard; an unbounded one would let
|
|
// a model bloat every surface that shows it.
|
|
maxSessionTitleLen = 80
|
|
)
|
|
|
|
// ChatSessionSummary is the per-session view the session tools return. It is
|
|
// deliberately narrower than a store session: the source tuple (platform, bot,
|
|
// channel, thread) is addressing metadata, not something that helps the model
|
|
// pick which conversation to resume.
|
|
type ChatSessionSummary struct {
|
|
ID string `json:"id"`
|
|
Title string `json:"title"`
|
|
BranchName string `json:"branch_name,omitempty"`
|
|
CreatedAt time.Time `json:"created_at"`
|
|
LastActiveAt time.Time `json:"last_active_at"`
|
|
}
|
|
|
|
// SessionListResult is what session_list returns.
|
|
type SessionListResult struct {
|
|
Sessions []ChatSessionSummary `json:"sessions"`
|
|
}
|
|
|
|
// SessionResumeResult is what session_resume returns.
|
|
type SessionResumeResult struct {
|
|
SessionID string `json:"session_id"`
|
|
Title string `json:"title"`
|
|
Message string `json:"message"`
|
|
}
|
|
|
|
// SessionTitleResult is what session_title returns.
|
|
type SessionTitleResult struct {
|
|
SessionID string `json:"session_id"`
|
|
Title string `json:"title"`
|
|
PreviousTitle string `json:"previous_title"`
|
|
}
|
|
|
|
// SessionDeleteResult is what session_delete returns.
|
|
type SessionDeleteResult struct {
|
|
SessionID string `json:"session_id"`
|
|
Title string `json:"title"`
|
|
Message string `json:"message"`
|
|
}
|
|
|
|
// SessionTools builds the chat tools that let Archie manage its own sessions.
|
|
// Until these existed, /resume, /title and /delete were slash commands only a
|
|
// human could type, so "switch back to that conversation" had no tool path at
|
|
// all.
|
|
//
|
|
// The tools are scoped to the current platform + channel: session_list returns
|
|
// only this channel's sessions (not every session the daemon knows), and
|
|
// session_resume/session_delete resolve references against that same scoped
|
|
// list. A model in chat A cannot list or manipulate chat B's history.
|
|
//
|
|
// msg is captured so the handlers act on the chat they were built for; the
|
|
// model never supplies a channel or thread.
|
|
//
|
|
// A nil store omits every tool rather than registering ones that always fail,
|
|
// so a daemon without session support advertises nothing. A nil tracker omits
|
|
// the two tools that need it (session_resume and session_delete).
|
|
func SessionTools(store SessionStore, tracker *sessionTracker, platform string, msg Message) []tools.ToolEntry {
|
|
if store == nil {
|
|
return nil
|
|
}
|
|
channelID := msg.ChannelID
|
|
var entries []tools.ToolEntry
|
|
entries = append(entries, sessionListTool(store, platform, channelID))
|
|
if tracker != nil {
|
|
entries = append(entries, sessionResumeTool(store, tracker, platform, channelID, msg))
|
|
entries = append(entries, sessionDeleteTool(store, tracker, platform, channelID))
|
|
}
|
|
entries = append(entries, sessionTitleTool(store, platform, channelID))
|
|
return entries
|
|
}
|
|
|
|
func sessionListTool(store SessionStore, platform, channelID string) tools.ToolEntry {
|
|
return tools.ToolEntry{
|
|
Name: "session_list",
|
|
Toolset: "session",
|
|
Description: "List this chat's sessions, most recent first. " +
|
|
"Use it to answer questions about past conversations and to find the " +
|
|
"session_id for session_resume, session_title or session_delete.",
|
|
Classification: tools.ClassIdempotent,
|
|
Schema: tools.JSONSchema{
|
|
"type": "object",
|
|
"properties": map[string]any{
|
|
"limit": map[string]any{
|
|
"type": "integer",
|
|
"description": fmt.Sprintf("Maximum sessions to return. Defaults to %d, capped at %d.", defaultSessionListLimit, maxSessionListLimit),
|
|
},
|
|
},
|
|
},
|
|
Handler: func(ctx context.Context, input map[string]any) (any, error) {
|
|
limit := sessionListLimit(input)
|
|
|
|
all, err := store.GetByChannel(ctx, platform, channelID)
|
|
if err != nil {
|
|
return nil, fmt.Errorf("session_list: %w", err)
|
|
}
|
|
// GetByChannel returns newest first by contract, but sort anyway
|
|
// so the tool never depends on a backend honouring ordering.
|
|
slices.SortStableFunc(all, func(a, b SessionContext) int {
|
|
return sessionRecency(b).Compare(sessionRecency(a))
|
|
})
|
|
if len(all) > limit {
|
|
all = all[:limit]
|
|
}
|
|
// Non-nil even when empty: an empty catalog is an answer, and a
|
|
// null would read to the model as a failed call worth retrying.
|
|
sessions := make([]ChatSessionSummary, 0, len(all))
|
|
for _, s := range all {
|
|
sessions = append(sessions, ChatSessionSummary{
|
|
ID: s.SessionID,
|
|
Title: sessionDisplayTitle(s),
|
|
BranchName: s.BranchName,
|
|
CreatedAt: s.CreatedAt,
|
|
LastActiveAt: s.LastActiveAt,
|
|
})
|
|
}
|
|
return SessionListResult{Sessions: sessions}, nil
|
|
},
|
|
}
|
|
}
|
|
|
|
func sessionResumeTool(store SessionStore, tracker *sessionTracker, platform, channelID string, msg Message) tools.ToolEntry {
|
|
return tools.ToolEntry{
|
|
Name: "session_resume",
|
|
Toolset: "session",
|
|
Description: "Make the named session the active one for this chat, so subsequent messages " +
|
|
"continue that conversation. Use it when the user asks to resume or switch to a " +
|
|
"conversation listed by session_list.",
|
|
Classification: tools.ClassMutating,
|
|
Schema: tools.JSONSchema{
|
|
"type": "object",
|
|
"properties": map[string]any{
|
|
"session_id": map[string]any{
|
|
"type": "string",
|
|
"description": "The session ID or a unique prefix, same as /resume.",
|
|
},
|
|
},
|
|
"required": []any{"session_id"},
|
|
},
|
|
Handler: func(ctx context.Context, input map[string]any) (any, error) {
|
|
ref := strings.TrimSpace(asString(input["session_id"]))
|
|
if ref == "" {
|
|
return nil, fmt.Errorf("session_resume: session_id is required")
|
|
}
|
|
|
|
sessions, err := store.GetByChannel(ctx, platform, channelID)
|
|
if err != nil {
|
|
return nil, fmt.Errorf("session_resume: %w", err)
|
|
}
|
|
match, ambiguous := resolveSessionRef(sessions, ref)
|
|
switch {
|
|
case ambiguous:
|
|
return nil, fmt.Errorf("session_resume: multiple sessions match %q; be more specific", ref)
|
|
case match == nil:
|
|
return nil, fmt.Errorf("session_resume: no session matching %q", ref)
|
|
}
|
|
|
|
// The channel+thread are the ones this tool was built for, never
|
|
// input. Tracker presence is guaranteed: SessionTools omits the
|
|
// tool when no tracker is wired.
|
|
tracker.setActive(msg.ChannelID, msg.ThreadID, match.SessionID)
|
|
return SessionResumeResult{
|
|
SessionID: match.SessionID,
|
|
Title: sessionDisplayTitle(*match),
|
|
Message: fmt.Sprintf("Resumed session %s (%s).",
|
|
shortSessionID(match.SessionID), sessionDisplayTitle(*match)),
|
|
}, nil
|
|
},
|
|
}
|
|
}
|
|
|
|
func sessionTitleTool(store SessionStore, platform, channelID string) tools.ToolEntry {
|
|
return tools.ToolEntry{
|
|
Name: "session_title",
|
|
Toolset: "session",
|
|
Description: "Set a display title on a session. Use it when the user asks to name or " +
|
|
"rename a conversation.",
|
|
Classification: tools.ClassMutating,
|
|
Schema: tools.JSONSchema{
|
|
"type": "object",
|
|
"properties": map[string]any{
|
|
"session_id": map[string]any{
|
|
"type": "string",
|
|
"description": "The session ID, as returned by session_list.",
|
|
},
|
|
"title": map[string]any{
|
|
"type": "string",
|
|
"description": fmt.Sprintf("New title, at most %d characters.", maxSessionTitleLen),
|
|
},
|
|
},
|
|
"required": []any{"session_id", "title"},
|
|
},
|
|
Handler: func(ctx context.Context, input map[string]any) (any, error) {
|
|
sessionID := strings.TrimSpace(asString(input["session_id"]))
|
|
if sessionID == "" {
|
|
return nil, fmt.Errorf("session_title: session_id is required")
|
|
}
|
|
title := strings.TrimSpace(asString(input["title"]))
|
|
if title == "" {
|
|
return nil, fmt.Errorf("session_title: title is required")
|
|
}
|
|
if len([]rune(title)) > maxSessionTitleLen {
|
|
return nil, fmt.Errorf("session_title: title must be at most %d characters", maxSessionTitleLen)
|
|
}
|
|
|
|
sc, err := store.Get(ctx, sessionID)
|
|
if err != nil {
|
|
return nil, fmt.Errorf("session_title: %w", err)
|
|
}
|
|
if sc == nil {
|
|
return nil, fmt.Errorf("session_title: session %q not found", sessionID)
|
|
}
|
|
// Guard against cross-channel writes: the session the model named
|
|
// must belong to the channel this turn is running in.
|
|
if sc.Source.Platform != platform || sc.Source.ChannelID != channelID {
|
|
return nil, fmt.Errorf("session_title: session %q does not belong to this channel", sessionID)
|
|
}
|
|
previous := sc.Title
|
|
sc.Title = title
|
|
if err := store.Save(ctx, *sc); err != nil {
|
|
return nil, fmt.Errorf("session_title: %w", err)
|
|
}
|
|
return SessionTitleResult{
|
|
SessionID: sc.SessionID,
|
|
Title: title,
|
|
PreviousTitle: previous,
|
|
}, nil
|
|
},
|
|
}
|
|
}
|
|
|
|
func sessionDeleteTool(store SessionStore, tracker *sessionTracker, platform, channelID string) tools.ToolEntry {
|
|
return tools.ToolEntry{
|
|
Name: "session_delete",
|
|
Toolset: "session",
|
|
Description: "Permanently delete a session and its message history. " +
|
|
"The dispatch layer asks a human to approve this before it runs.",
|
|
Classification: tools.ClassMutating | tools.RequiresApproval,
|
|
BuildApprovalDescription: func(input map[string]any) string {
|
|
id := strings.TrimSpace(asString(input["session_id"]))
|
|
return fmt.Sprintf("Permanently delete session %q and its message history. This cannot be undone.", id)
|
|
},
|
|
Schema: tools.JSONSchema{
|
|
"type": "object",
|
|
"properties": map[string]any{
|
|
"session_id": map[string]any{
|
|
"type": "string",
|
|
"description": "The session ID or a unique prefix, same as /delete.",
|
|
},
|
|
},
|
|
"required": []any{"session_id"},
|
|
},
|
|
Handler: func(ctx context.Context, input map[string]any) (any, error) {
|
|
ref := strings.TrimSpace(asString(input["session_id"]))
|
|
if ref == "" {
|
|
return nil, fmt.Errorf("session_delete: session_id is required")
|
|
}
|
|
|
|
sessions, err := store.GetByChannel(ctx, platform, channelID)
|
|
if err != nil {
|
|
return nil, fmt.Errorf("session_delete: %w", err)
|
|
}
|
|
target, ambiguous := resolveSessionRef(sessions, ref)
|
|
switch {
|
|
case ambiguous:
|
|
return nil, fmt.Errorf("session_delete: multiple sessions match %q; be more specific", ref)
|
|
case target == nil:
|
|
return nil, fmt.Errorf("session_delete: no session matching %q", ref)
|
|
}
|
|
|
|
if err := store.Delete(ctx, target.SessionID); err != nil {
|
|
return nil, fmt.Errorf("session_delete: %w", err)
|
|
}
|
|
// Only after the store has let go of it, mirroring /delete: a
|
|
// failed delete leaves the session live, and dropping the tracker
|
|
// entry then would strand the operator's conversation for no
|
|
// reason.
|
|
tracker.forget(target.SessionID)
|
|
return SessionDeleteResult{
|
|
SessionID: target.SessionID,
|
|
Title: sessionDisplayTitle(*target),
|
|
Message: fmt.Sprintf("Deleted session %s (%s) and its history.",
|
|
shortSessionID(target.SessionID), sessionDisplayTitle(*target)),
|
|
}, nil
|
|
},
|
|
}
|
|
}
|
|
|
|
// sessionListLimit resolves the requested limit, falling back to the default
|
|
// for anything absent or non-positive and clamping the rest, exactly like the
|
|
// task list limit.
|
|
//
|
|
// JSON numbers decode as float64, but a model that emits an integer through a
|
|
// different provider path can arrive as int, so both are accepted.
|
|
func sessionListLimit(input map[string]any) int {
|
|
return tools.ListLimit(input, defaultSessionListLimit, maxSessionListLimit)
|
|
}
|