Files
archie/internal/gateway/gateway.go
T
sam 708233a538 fix(webhook): keep a route path out of the sender identity
A webhook set SenderID to its configured route path. The turn path reads that
field through a per-channel resolver which refuses webhook, but the session
curator derives its participant from the raw field with no channel filter, so a
webhook session with exactly one distinct sender and one extracted fact wrote
agent-user memory addressed to User: "/hooks/...". Nothing reads it, and every
pass added more, because the facts are identical strings with no dedup.
docs/prds/memory-engine-unification.md criterion 7 requires that a route path
never become a user identity.

Clear it at the producer rather than teaching every consumer which channels are
lying: a route path is a source, not a person, so it no longer enters SenderID.
It still keys the inbound rate limit, where it is the documented per-source
budget for webhooks (config.RateLimitConfig), so it travels in the new
transport-only Inbound.BudgetKey -- carried on the wire beside Page, never
persisted, and never read as an identity.

pb.Message gains budget_key (field 9) for the same reason page (field 7) exists:
transport context that rides with an inbound message and is deliberately absent
from storedProto's rendering of a canonical record.

The curator needs no change. An empty SenderID already fails closed as an
unidentified user message, which is the path a dashboard session takes, and
sessionParticipant's existing skip covers it; the test name now says so.
2026-09-22 03:18:59 +10:00

1122 lines
38 KiB
Go

// Package gateway defines the persistent-connection layer between archie
// and its users. Each gateway implementation (Telegram, web UI, Discord,
// etc.) owns its connection lifecycle and delegates message dispatch to a
// shared CommandRouter.
//
// The router distinguishes gateway-local commands -- handled directly
// without the LLM (model changes, status queries, restart) -- from
// general messages that need LLM processing.
package gateway
import (
"cmp"
"context"
"fmt"
"log/slog"
"slices"
"strconv"
"strings"
"sync"
"time"
"unicode"
"github.com/samcharles93/archie-core/internal/domain/messaging"
"github.com/samcharles93/archie-core/internal/ratelimit"
"github.com/samcharles93/archie-core/internal/releaseupdate"
"github.com/samcharles93/archie-core/internal/taskstate"
)
// Lifecycle receives adapter-owned startup facts.
type Lifecycle = messaging.Lifecycle
// A Gateway owns a persistent connection to a chat channel. Start blocks;
// the gateway should remain running until ctx is cancelled or Stop is called.
type Gateway interface {
Name() string
Start(ctx context.Context, router *Router, lifecycle Lifecycle) error
Stop(ctx context.Context) error
}
// StatusReader is the read-only query surface gateway-local commands
// like /status need. The daemon supplies its store, which satisfies this
// structurally.
type StatusReader interface {
StatusCounts(ctx context.Context) (map[string]int, error)
}
// LLMResponder routes a message to the LLM and returns the reply. When
// nil (not yet wired -- see abg.13), non-command messages get a static
// "LLM not configured" response. Gateways call this for any message the
// router did not handle directly.
type LLMResponder func(ctx context.Context, in Inbound) (string, error)
// LLMStreamResponder is the streaming counterpart of LLMResponder. It
// reports the turn's progress -- text fragments and completed tool calls
// -- to stream as it is generated, and returns the complete reply when the
// turn finishes.
//
// It is optional: a gateway that cannot render partial output, or a
// deployment whose provider does not stream, simply leaves it nil and the
// Router falls back to the blocking LLMResponder. stream is called from the
// generating goroutine and must not block for long -- adapters should
// throttle their own network writes rather than stall the stream.
type LLMStreamResponder func(ctx context.Context, in Inbound, stream TurnStream) (string, error)
// ModelManager provides access to available models and allows switching the
// active LLM model. The daemon supplies an implementation backed by its
// runtime provider catalog. When nil on a Router, /model returns a
// "not configured" message.
type ModelManager interface {
// Models returns all available model references in "provider/model" format.
Models() []string
// ActiveModel returns the currently active model reference.
// Returns empty string when no model is active.
ActiveModel() string
// SetActiveModel switches the active model. Returns an error if the
// reference is unknown.
SetActiveModel(ctx context.Context, ref string) error
}
// ProviderModelManager is the optional provider-aware extension used by
// gateways that offer a provider selector before model selection.
type ProviderModelManager interface {
ModelManager
Providers() []string
ActiveProvider() string
ModelsForProvider(provider string) []string
SetActiveProvider(ctx context.Context, provider string) error
}
// ModelDetails is the catalog metadata rendered after an interactive model
// selection. Limits are zero when the upstream catalog does not publish them.
type ModelDetails = messaging.ModelDetails
// DetailedModelManager is the optional catalog-aware extension used by rich
// model selectors. Runtime routing remains on ModelManager.
type DetailedModelManager interface {
ModelManager
ModelDetails(ref string) (ModelDetails, bool)
}
type ProviderDisplayNamer interface {
ProviderDisplayName(provider string) string
}
// UpdateService is the shared release workflow used by chat adapters. The
// recipient id scopes deferrals; each adapter chooses its own stable id.
type UpdateService interface {
Check(context.Context, int64) (releaseupdate.Snapshot, error)
Defer(context.Context, int64, releaseupdate.Snapshot) error
Install(context.Context, releaseupdate.Snapshot, releaseupdate.InstallMeta, func(string)) (releaseupdate.Result, error)
CanInstall() bool
}
// TaskController approves or cancels a chat-originated task. Both
// methods must enforce authorization (identity must own the task) and
// valid state transitions; see gateway.tasks.go's StoreTaskController
// for the reference implementation. When nil on a Router, /approve and
// /cancel return "not configured".
// AgentInfo is a lightweight agent summary for /agents.
type AgentInfo struct {
ID int64
Title string
Status string
Identity string
}
// AgentReader is the read surface /agents uses.
type AgentReader interface {
AgentList(ctx context.Context) ([]AgentInfo, error)
}
type TaskController interface {
// Approve moves a waiting_human task back to queued. Returns an
// error (surfaced to the user, not the LLM) if the task doesn't
// exist, isn't owned by identity, or isn't in waiting_human.
Approve(ctx context.Context, taskID int64, identity string) error
// Cancel moves an active task to a rejected/cancelled terminal
// state, interrupting it first if it is running. Returns an error if
// the task doesn't exist, isn't owned by identity, or is already
// terminal.
Cancel(ctx context.Context, taskID int64, identity string) error
// StopRunning interrupts every task currently executing for
// identity and returns the IDs it stopped. It is the agent half of
// /stop, so it must not require knowing a task ID: someone reaching
// for the brake is not in a position to look one up.
StopRunning(ctx context.Context, identity string) ([]int64, error)
}
// Router dispatches inbound messages. Gateway-local commands (like
// /status) are handled directly. Everything else is routed to the LLM
// responder. Gateway implementations call Route on every inbound
// message.
type Router struct {
Store StatusReader
Models ModelManager // nil = /model not configured
// ModelPersist persists the active model selection so it survives
// restarts (e.g. writing back to identity config). nil = not configured.
ModelPersist func(ctx context.Context, modelRef string) error
// Personas holds the available personality registry for /personality.
Personas *PersonaRegistry
Tasks TaskCreator // nil = /spawn not configured
Controller TaskController // nil = /approve and /cancel not configured
Settings *messaging.SettingsCommand
// TaskLister backs /tasks: the live work view (id, title, status,
// workflow/stage, age). nil = /tasks not configured.
TaskLister ChatTaskLister
// Health backs /status' daemon-health section (broker, worker pool,
// channels, chat model, last poll). nil = this process wired no health
// source, in which case /status omits the section rather than
// reporting a value it does not have.
Health HealthSource
LLM LLMResponder // nil = LLM not wired yet
// LLMStream is the optional streaming responder. When set, adapters
// that can render partial output (see RouteStream) show the reply as
// it generates; when nil, everything falls back to LLM.
LLMStream LLMStreamResponder
// Identity is the archie identity this router belongs to (empty in
// single-identity deployments). Propagated into SpawnRequest and
// used to scope /approve and /cancel authorization -- a task
// spawned under one identity cannot be controlled from another's
// chat session.
Identity string
// Version is shown by the shared /version command when supplied by the
// composition root. Empty means version information is unavailable.
Version string
// Updates handles the shared /update command. Nil means unavailable.
Updates UpdateService
// Restart requests a scoped chat-adapter reload. It deliberately does not
// restart the daemon; Telegram's /restart has this same boundary.
Restart func(context.Context) error
// Sessions persists session metadata and conversation history.
// When set, session lifecycle commands (/new, /branch, /title,
// /undo, /retry, /compress) are available. When nil, those
// commands report "not configured".
Sessions SessionStore
Agents AgentReader // nil = /agents not configured
// Titles proposes display titles for untitled sessions (see
// TitleGenerator). Nil disables automatic title generation; when set,
// the router asks for a title after a successful turn on a session
// that still has none, in the background, and persists the result.
Titles TitleGenerator
// Log is the optional logger for the best-effort background title
// path. Nil drops those diagnostics silently; nothing on this path is
// important enough to fail the turn over.
Log *slog.Logger
// Limiter enforces a per-(gateway, source) inbound budget when set.
// Nil disables rate limiting entirely. A message is charged against
// Inbound.BudgetKey when the channel set one (a webhook route, which
// has a stable source but no person), else against Message.SenderID.
// A message with neither is never limited: there is no key to charge
// it against.
Limiter *ratelimit.Limiter
sessionTracker *sessionTracker
gatewayName string
// titlingMu guards titling, the set of sessions with a title proposal
// in flight (see claimTitleInFlight). Zero value is ready to use.
titlingMu sync.Mutex
titling map[string]struct{}
}
// NewRouter returns a Router. llm is optional -- when nil, non-command
// messages get a "not configured" response.
func NewRouter(store StatusReader, llm LLMResponder, gatewayName string) *Router {
return &Router{Store: store, LLM: llm, gatewayName: gatewayName}
}
// InitSessions wires the session store and starts tracking sessions.
// Must be called before session commands are used. Idempotent.
func (r *Router) InitSessions(sessions SessionStore) {
r.Sessions = sessions
r.sessionTracker = newSessionTracker(sessions)
}
// SessionTracker exposes the session tracker so that tool constructors
// (SessionTools) can bind session_resume to the active session without
// reaching into the Router's unexported fields.
func (r *Router) SessionTracker() *sessionTracker {
return r.sessionTracker
}
// rateLimitReply is returned to a sender who has exceeded their inbound
// budget, in place of normal dispatch.
const rateLimitReply = "You're sending messages too quickly. Please wait a moment and try again."
// checkRateLimit reports whether in is over its source's inbound budget.
// A nil Limiter (rate limiting not configured) or no key to charge the
// message against (see inboundBudgetKey) always allows.
func (r *Router) checkRateLimit(in Inbound) (blocked bool) {
key := inboundBudgetKey(in)
if r.Limiter == nil || key == "" {
return false
}
return !r.Limiter.Allow(r.gatewayName, key)
}
// inboundBudgetKey returns the key this message's inbound budget is charged
// against: the channel's own transport budget key when it set one, else the
// per-person SenderID. The two are deliberately distinct -- SenderID means
// "who sent this", and a channel whose SenderID is not a person (a webhook
// route path) must not put it there, because several consumers read that
// field as a user identity (docs/prds/memory-engine-unification.md §3).
func inboundBudgetKey(in Inbound) string {
if in.BudgetKey != "" {
return in.BudgetKey
}
return in.Message.SenderID
}
// Route dispatches msg and returns the reply. Gateway-local commands
// are handled directly; everything else goes to the LLM responder.
func (r *Router) Route(ctx context.Context, in Inbound) (string, error) {
if r.checkRateLimit(in) {
return rateLimitReply, nil
}
return r.route(ctx, in)
}
// route is Route's continuation once the caller has already cleared the
// rate-limit check (or is deliberately skipping it, as RouteStream's
// local-command fallthrough does to avoid charging one message twice).
func (r *Router) route(ctx context.Context, in Inbound) (string, error) {
text := strings.TrimSpace(in.Message.Text)
cmd, _ := parseCmd(text, r.gatewayName)
if reply, handled, err := r.dispatchLocal(ctx, in.Message, text, cmd); handled {
return reply, err
}
if strings.HasPrefix(cmd, "/") {
return fmt.Sprintf("Unknown command %s. Try /help.", cmd), nil
}
if r.LLM == nil {
return "I'm running but LLM processing isn't wired yet. Try /status.", nil
}
reply, err := r.LLM(ctx, in)
if err == nil {
r.maybeAutoTitle(ctx, in.Message)
}
return reply, err
}
// dispatchLocal handles recognized local commands. Returns (reply,
// true) when the command was recognized and handled.
func (r *Router) dispatchLocal(ctx context.Context, msg messaging.Message, text, cmd string) (string, bool, error) {
rest := restAfter(text, cmd, r.gatewayName)
switch cmd {
case "/status":
reply, err := r.handleStatus(ctx)
return reply, true, err
case "/tasks":
reply, err := r.handleTasks(ctx)
return reply, true, err
case "/model":
_, arg := parseCmd(text, "")
reply, err := r.handleModel(ctx, arg)
return reply, true, err
case "/spawn":
reply, err := r.handleSpawn(ctx, rest)
return reply, true, err
case "/approve":
reply, err := r.handleApprove(ctx, rest)
return reply, true, err
case "/cancel":
reply, err := r.handleCancel(ctx, rest)
return reply, true, err
case "/settings":
return r.Settings.Execute(ctx, "", rest), true, nil
case "/start":
reply, err := r.handleStart()
return reply, true, err
case "/whoami":
reply, err := r.handleWhoami()
return reply, true, err
case "/profile":
reply, err := r.handleProfile()
return reply, true, err
}
return r.dispatchLocalMisc(ctx, msg, cmd, rest)
}
// dispatchLocalMisc handles the remaining recognized local commands not
// covered by dispatchLocal's first switch. Split out to keep cyclomatic
// complexity down.
func (r *Router) dispatchLocalMisc(ctx context.Context, msg messaging.Message, cmd, rest string) (string, bool, error) {
switch cmd {
case "/sessions":
reply, err := r.handleSessions(ctx, msg)
return reply, true, err
case "/resume":
reply, err := r.handleResume(ctx, msg, rest)
return reply, true, err
case "/agents":
reply, err := r.handleAgents(ctx)
return reply, true, err
case "/personality":
reply, err := r.handlePersonality(ctx, msg, rest)
return reply, true, err
case "/help":
return r.helpText(), true, nil
case "/version":
return r.handleVersion(), true, nil
case "/update":
return r.handleUpdateCheck(ctx), true, nil
case "/restart":
return r.handleRestartAdapter(ctx), true, nil
}
return r.dispatchSessionCommand(ctx, msg, cmd, rest)
}
// handleVersion reports the configured build version.
func (r *Router) handleVersion() string {
if r.Version == "" {
return "Version information is not configured."
}
return r.Version
}
// handleUpdateCheck reports the latest available update snapshot.
func (r *Router) handleUpdateCheck(ctx context.Context) string {
if r.Updates == nil {
return "Updates are not configured."
}
snapshot, err := r.Updates.Check(ctx, 0)
if err != nil {
return fmt.Sprintf("Could not check for updates: %v", err)
}
return releaseupdate.FormatSnapshot(snapshot)
}
// handleRestartAdapter reloads the chat adapter.
func (r *Router) handleRestartAdapter(ctx context.Context) string {
if r.Restart == nil {
return "Chat adapter restart is not configured."
}
if err := r.Restart(ctx); err != nil {
return fmt.Sprintf("Could not restart the chat adapter: %v", err)
}
return "Chat adapter reload requested."
}
// dispatchSessionCommand handles the session-lifecycle command group
// (/new, /topic, /retry, /undo, /title, /branch, /compress and their
// aliases). Split out from dispatchLocal to keep cyclomatic complexity
// down.
func (r *Router) dispatchSessionCommand(ctx context.Context, msg messaging.Message, cmd, rest string) (string, bool, error) {
switch cmd {
case "/new", "/reset":
reply, err := r.handleNew(ctx, msg, rest)
return reply, true, err
case "/topic":
reply, err := r.handleTopic(ctx, msg, rest)
return reply, true, err
case "/retry":
reply, err := r.handleRetry(ctx, msg)
return reply, true, err
case "/undo":
reply, err := r.handleUndo(ctx, msg, rest)
return reply, true, err
case "/title":
reply, err := r.handleTitle(ctx, msg, rest)
return reply, true, err
case "/branch", "/fork":
reply, err := r.handleBranch(ctx, msg, rest)
return reply, true, err
case "/compress", "/compact":
reply, err := r.handleCompress(ctx, msg, rest)
return reply, true, err
case "/delete":
reply, err := r.handleDelete(ctx, msg, rest)
return reply, true, err
}
return "", false, nil
}
// RouteStream is Route for adapters that can render a reply progressively.
// stream receives each new fragment of an LLM reply as it is generated, plus
// each completed tool call, in the order the model produced them; the
// complete reply is returned as usual.
//
// Only free-text messages stream. Gateway-local commands (/status, /model,
// …) answer from local state in a single step, so they return through the
// normal path with no delta callbacks. When no streaming responder is
// configured, RouteStream is exactly Route -- callers get the whole reply
// at the end and simply never see a delta, so an adapter can always call
// RouteStream without checking first.
func (r *Router) RouteStream(ctx context.Context, in Inbound, stream TurnStream) (string, error) {
if r.LLMStream == nil || stream == nil {
return r.Route(ctx, in)
}
if r.checkRateLimit(in) {
return rateLimitReply, nil
}
cmd, _ := parseCmd(strings.TrimSpace(in.Message.Text), r.gatewayName)
if isLocalCommand(cmd) || strings.HasPrefix(cmd, "/") {
return r.route(ctx, in)
}
reply, err := r.LLMStream(ctx, in, stream)
if err == nil {
r.maybeAutoTitle(ctx, in.Message)
}
return reply, err
}
// isLocalCommand reports whether cmd is answered from local state by
// Route rather than handed to the LLM.
func isLocalCommand(cmd string) bool {
return slices.Contains(messaging.LocalCommands(), cmd)
}
// parseCmd extracts the command name from text, stripping an optional
// @gateway mention from the command token, and returns the command and
// its first argument.
func parseCmd(text, gatewayName string) (cmd, arg string) {
fields := strings.Fields(text)
if len(fields) == 0 {
return "", ""
}
raw := fields[0]
if gatewayName != "" {
suffix := "@" + gatewayName
raw = strings.TrimSuffix(raw, suffix)
}
if len(fields) > 1 {
return raw, fields[1]
}
return raw, ""
}
func (r *Router) handleModel(ctx context.Context, arg string) (string, error) {
if r.Models == nil {
return "Model switching is not configured.", nil
}
if arg == "" {
models := r.Models.Models()
if manager, ok := r.Models.(ProviderModelManager); ok {
models = manager.ModelsForProvider(manager.ActiveProvider())
}
if len(models) == 0 {
return "No models configured.\nUsage: /model <provider/model>", nil
}
var b strings.Builder
b.WriteString("Usage: /model <provider/model>\nAvailable models:\n")
active := r.Models.ActiveModel()
for _, m := range models {
if m == active {
fmt.Fprintf(&b, " %s (active)\n", m)
} else {
fmt.Fprintf(&b, " %s\n", m)
}
}
return b.String(), nil
}
if err := r.Models.SetActiveModel(ctx, arg); err != nil {
return fmt.Sprintf("Cannot switch: %v", err), nil
}
return fmt.Sprintf("Active model set to %s.", arg), nil
}
// restAfter returns the text after the command token, stripping the
// optional @gateway mention. E.g. for "/spawn Fix the bug", returns
// "Fix the bug".
func restAfter(text, cmd, gatewayName string) string {
s := text
if gatewayName != "" {
s = strings.TrimPrefix(s, cmd+"@"+gatewayName)
}
s = strings.TrimPrefix(s, cmd)
return strings.TrimSpace(s)
}
// handleSpawn parses optional leading identity, repo, and workflow tokens
// off rest, treating whatever remains as the task title.
func (r *Router) handleSpawn(ctx context.Context, rest string) (string, error) {
if r.Tasks == nil {
return "Task creation is not configured.", nil
}
req := SpawnRequest{Identity: r.Identity}
fields := strings.Fields(rest)
i := 0
for i < len(fields) {
if after, ok := strings.CutPrefix(fields[i], "identity="); ok {
req.Identity = after
i++
continue
}
if after, ok := strings.CutPrefix(fields[i], "repo="); ok {
req.Repo = after
i++
continue
}
if after, ok := strings.CutPrefix(fields[i], "workflow="); ok {
req.Workflow = after
i++
continue
}
break // remaining fields are all title
}
req.Title = strings.TrimSpace(strings.Join(fields[i:], " "))
if req.Title == "" {
return "Usage: /spawn [identity=name] [repo=owner/name] [workflow=name] <title>", nil
}
id, err := r.Tasks.CreateTask(ctx, req)
if err != nil {
return fmt.Sprintf("Failed to create task: %v", err), nil
}
return fmt.Sprintf("Created task %d: %s", id, req.Title), nil
}
// parseTaskID parses a chat command argument as a task database ID.
func parseTaskID(arg string) (int64, error) {
if arg == "" {
return 0, fmt.Errorf("missing task ID")
}
id, err := strconv.ParseInt(arg, 10, 64)
if err != nil {
return 0, fmt.Errorf("%q is not a valid task ID", arg)
}
return id, nil
}
func (r *Router) handleApprove(ctx context.Context, rest string) (string, error) {
if r.Controller == nil {
return "Task control is not configured.", nil
}
identity, arg := parseTaskControl(rest, r.Identity)
id, err := parseTaskID(arg)
if err != nil {
return "Usage: /approve [identity=name] <task-id>", nil //nolint:nilerr // chat commands report problems as text to the human, never as Go errors, which would surface as a gateway fault
}
if err := r.Controller.Approve(ctx, id, identity); err != nil {
return fmt.Sprintf("Cannot approve task %d: %v", id, err), nil
}
return fmt.Sprintf("Task %d approved and requeued.", id), nil
}
func (r *Router) handleCancel(ctx context.Context, rest string) (string, error) {
if r.Controller == nil {
return "Task control is not configured.", nil
}
identity, arg := parseTaskControl(rest, r.Identity)
id, err := parseTaskID(arg)
if err != nil {
return "Usage: /cancel [identity=name] <task-id>", nil //nolint:nilerr // chat commands report problems as text to the human, never as Go errors, which would surface as a gateway fault
}
if err := r.Controller.Cancel(ctx, id, identity); err != nil {
return fmt.Sprintf("Cannot cancel task %d: %v", id, err), nil
}
return fmt.Sprintf("Task %d cancelled.", id), nil
}
func parseTaskControl(rest, defaultIdentity string) (identity, taskID string) {
fields := strings.Fields(rest)
identity = defaultIdentity
if len(fields) > 0 && strings.HasPrefix(fields[0], "identity=") {
identity = strings.TrimPrefix(fields[0], "identity=")
fields = fields[1:]
}
if len(fields) != 1 {
return identity, ""
}
return identity, fields[0]
}
func (r *Router) handleStatus(ctx context.Context) (string, error) {
if r.Store == nil {
return "store not configured", nil
}
counts, err := r.Store.StatusCounts(ctx)
if err != nil {
return "", fmt.Errorf("status: %w", err)
}
report := HealthReport{}
if r.Health != nil {
report = r.Health.Health()
}
return formatStatus(counts, report, r.Models, time.Now()), nil
}
// handleTasks answers /tasks: the live view of this identity's work, with
// enough identity and state to act on it. This is the division of labour
// /status used to blur -- /status now reports health, /tasks reports work.
func (r *Router) handleTasks(ctx context.Context) (string, error) {
if r.TaskLister == nil {
return "task list not configured", nil
}
tasks, err := r.TaskLister.ListChatTasks(ctx, r.Identity, defaultTaskListLimit)
if err != nil {
return "", fmt.Errorf("tasks: %w", err)
}
return formatTasks(tasks, time.Now()), nil
}
// reportLineBreak ends a line of a line-oriented report. A chat report is a
// list of facts, not prose, so every one of its newlines is a real break;
// plain "\n" is CommonMark's soft wrap, which a Markdown-rendering channel
// joins into one run-on paragraph (see the Telegram renderer's
// markdownBlockParser).
const reportLineBreak = " \n"
// parkReasonMaxRunes bounds the park reason shown per task. A reason carries
// whatever the failing stage reported, which for a lint or test gate is a
// whole tool log; unbounded, one parked task pushes every other task out of
// the reply.
const parkReasonMaxRunes = 160
// summarizeParkReason reduces a park reason to one readable line: the first
// non-empty line, bounded. The full reason stays on the task, which /task and
// the dashboard show in full -- this is the list view.
func summarizeParkReason(reason string) string {
line := reason
if first, _, ok := strings.Cut(reason, "\n"); ok {
line = first
}
line = strings.TrimSpace(line)
if line == "" {
line = strings.TrimSpace(reason)
}
runes := []rune(line)
if len(runes) <= parkReasonMaxRunes {
return line
}
return strings.TrimSpace(string(runes[:parkReasonMaxRunes])) + "..."
}
// formatTasks renders each task with enough identity and state to act on
// it: id, title, status, workflow/stage, and age since its last
// transition -- so a task that is running but stuck (old UpdatedAt) reads
// differently from one making progress (recent UpdatedAt), which a bare
// status count could never distinguish.
func formatTasks(tasks []ChatTaskSummary, now time.Time) string {
var b strings.Builder
b.WriteString("🗂 Archie tasks\n\n")
if len(tasks) == 0 {
b.WriteString("No tasks yet\n")
return strings.TrimSpace(b.String())
}
sortTasksByPriority(tasks)
for _, t := range tasks {
icon, label := "•", formatCustomStatus(t.Status)
if d, ok := taskStateDisplays[t.Status]; ok {
icon, label = d.icon, d.label
}
fmt.Fprintf(&b, "%s #%d %s%s", icon, t.ID, t.Title, reportLineBreak)
fmt.Fprintf(&b, " %s", label)
if stage := workflowStage(t.Workflow, t.Stage); stage != "" {
fmt.Fprintf(&b, " · %s", stage)
}
if t.Attempt > 1 {
fmt.Fprintf(&b, " · attempt %d", t.Attempt)
}
if age := relativeAge(t.UpdatedAt, now); age != "" {
fmt.Fprintf(&b, " · updated %s", age)
}
if t.Status == taskstate.Parked && t.ParkReason != "" {
fmt.Fprintf(&b, "%s ↳ %s", reportLineBreak, summarizeParkReason(t.ParkReason))
}
b.WriteString("\n\n")
}
return strings.TrimSpace(b.String())
}
// workflowStage joins a task's workflow and stage for display, degrading
// gracefully when either is unknown (e.g. a task that hasn't started its
// first stage yet).
func workflowStage(workflow, stage string) string {
switch {
case workflow == "" && stage == "":
return ""
case stage == "":
return workflow
case workflow == "":
return stage
default:
return workflow + "/" + stage
}
}
type taskStateDisplay struct {
icon string
label string
}
var taskStateDisplays = map[string]taskStateDisplay{
taskstate.Running: {icon: "▶", label: "Running"},
taskstate.WaitingHuman: {icon: "👤", label: "Waiting"},
taskstate.Parked: {icon: "⏸", label: "Parked"},
taskstate.Queued: {icon: "⏳", label: "Queued"},
taskstate.PROpen: {icon: "🔀", label: "PR open"},
taskstate.Merged: {icon: "✅", label: "Merged"},
taskstate.Rejected: {icon: "❌", label: "Rejected"},
taskstate.Declined: {icon: "🚫", label: "Declined"},
"declined": {icon: "🚫", label: "Declined"},
taskstate.Dead: {icon: "🛑", label: "Dead"},
}
var statusOrder = []string{
taskstate.Running,
taskstate.WaitingHuman,
taskstate.Parked,
taskstate.Queued,
taskstate.PROpen,
taskstate.Merged,
taskstate.Rejected,
taskstate.Declined,
"declined",
taskstate.Dead,
}
// sortTasksByPriority orders tasks so the ones an operator would look for
// first -- running, then waiting on them, then parked -- lead the list,
// with terminal states (merged, rejected, dead, ...) trailing. It is
// stable, so within one status group the lister's own recency order
// survives.
func sortTasksByPriority(tasks []ChatTaskSummary) {
orderMap := make(map[string]int, len(statusOrder))
for i, s := range statusOrder {
orderMap[s] = i
}
slices.SortStableFunc(tasks, func(a, b ChatTaskSummary) int {
idxA, okA := orderMap[a.Status]
idxB, okB := orderMap[b.Status]
if okA && okB {
return cmp.Compare(idxA, idxB)
}
if okA {
return -1
}
if okB {
return 1
}
return strings.Compare(a.Status, b.Status)
})
}
func formatCustomStatus(s string) string {
s = strings.TrimSpace(strings.ReplaceAll(s, "_", " "))
if s == "" {
return "Unknown"
}
r := []rune(s)
r[0] = unicode.ToUpper(r[0])
return string(r)
}
var knownProviderNames = map[string]string{
"openai": "OpenAI",
"openrouter": "OpenRouter",
"anthropic": "Anthropic",
"deepseek": "DeepSeek",
"google": "Google",
"ollama": "Ollama",
"github": "GitHub",
"gh": "GitHub",
"groq": "Groq",
"together": "Together",
"bedrock": "Bedrock",
"azure": "Azure",
}
func formatProviderName(provider string) string {
trimmed := strings.TrimSpace(provider)
if trimmed == "" {
return ""
}
if name, ok := knownProviderNames[strings.ToLower(trimmed)]; ok {
return name
}
if strings.ToLower(trimmed) == trimmed {
r := []rune(trimmed)
r[0] = unicode.ToUpper(r[0])
return string(r)
}
return trimmed
}
func extractRuntimeInfo(models ModelManager) (provider, model string) {
if models == nil {
return "", ""
}
model = strings.TrimSpace(models.ActiveModel())
if pmm, ok := models.(ProviderModelManager); ok {
provider = strings.TrimSpace(pmm.ActiveProvider())
}
if provider == "" && model != "" {
if p, _, ok := strings.Cut(model, "/"); ok {
provider = p
}
}
if pdn, ok := models.(ProviderDisplayNamer); ok && provider != "" {
if name := strings.TrimSpace(pdn.ProviderDisplayName(provider)); name != "" {
return name, model
}
}
return formatProviderName(provider), model
}
// formatRuntimeSection appends the active provider and model as two more
// report lines. They are not given a section header of their own: /status is
// four facts, and a header for the last two made a short report read like a
// document.
func formatRuntimeSection(b *strings.Builder, provider, model string) {
if provider == "" && model == "" {
b.WriteString("Runtime: not configured")
return
}
if provider == "" {
provider = "not configured"
}
if model == "" {
model = "not configured"
}
fmt.Fprintf(b, "Provider: %s%sModel: %s", provider, reportLineBreak, model)
}
// formatStatus formats daemon health into a clean, mobile-friendly summary:
// the aggregate queue line, then the health section (broker, worker pool,
// channels, chat model, last poll) from whatever the process could truthfully
// report, then the runtime block.
//
// It deliberately does not itemize tasks -- that is /tasks' job -- so it
// reduces the task counts to one aggregate health signal (is work backing
// up) rather than duplicating /tasks' per-task list.
func formatStatus(counts map[string]int, report HealthReport, models ModelManager, now time.Time) string {
var b strings.Builder
b.WriteString("📊 Archie status\n\n")
b.WriteString(formatQueueDepth(counts))
b.WriteString(reportLineBreak)
if health := formatHealth(report, now); health != "" {
b.WriteString(health)
b.WriteString(reportLineBreak)
}
provider, model := extractRuntimeInfo(models)
formatRuntimeSection(&b, provider, model)
return b.String()
}
// formatQueueDepth summarizes in-flight work as one line: how many tasks
// are running, waiting on a human reply, or parked. Queued and terminal
// states are excluded -- neither is a health concern an operator needs
// /status to surface.
func formatQueueDepth(counts map[string]int) string {
running := counts[taskstate.Running]
waiting := counts[taskstate.WaitingHuman]
parked := counts[taskstate.Parked]
inFlight := running + waiting + parked
if inFlight == 0 {
return "Queue: idle"
}
var parts []string
if running > 0 {
parts = append(parts, fmt.Sprintf("%d running", running))
}
if waiting > 0 {
parts = append(parts, fmt.Sprintf("%d waiting on you", waiting))
}
if parked > 0 {
parts = append(parts, fmt.Sprintf("%d parked", parked))
}
return fmt.Sprintf("Queue: %d in flight (%s)", inFlight, strings.Join(parts, ", "))
}
func (r *Router) handleWhoami() (string, error) {
if r.Identity == "" {
return "I'm Archie, running without a configured identity.", nil
}
var b strings.Builder
fmt.Fprintf(&b, "I'm %s.", r.Identity)
if r.Models != nil {
if active := r.Models.ActiveModel(); active != "" {
fmt.Fprintf(&b, " Running %s.", active)
}
}
return b.String(), nil
}
func (r *Router) handleProfile() (string, error) {
if r.Identity == "" {
return "Profile is not configured (no identity set).", nil
}
var b strings.Builder
fmt.Fprintf(&b, "Identity: %s\n", r.Identity)
if r.Models != nil {
fmt.Fprintf(&b, "Model: %s\n", r.Models.ActiveModel())
}
return strings.TrimSpace(b.String()), nil
}
func (r *Router) handleSessions(ctx context.Context, msg messaging.Message) (string, error) {
if r.Sessions == nil {
return "Session management is not configured.", nil
}
sessions, err := r.Sessions.List(ctx)
if err != nil {
return "", fmt.Errorf("list sessions: %w", err)
}
active := ""
if r.sessionTracker != nil {
active = r.sessionTracker.getActive(msg.ConversationID.ChannelID, msg.ConversationID.ThreadID)
}
return renderSessionList(sessions, active, time.Now()), nil
}
// renderSessionList formats sessions (already newest-first) as the
// /sessions reply: a count header, then one numbered, column-aligned row
// per session carrying an 8-character id prefix, its title, and a
// recency suffix. The active session (matched by ID) is marked.
func renderSessionList(sessions []SessionContext, active string, now time.Time) string {
if len(sessions) == 0 {
return "No sessions."
}
maxTitle := 0
for _, s := range sessions {
if l := len([]rune(sessionDisplayTitle(s))); l > maxTitle {
maxTitle = l
}
}
numW := len(strconv.Itoa(len(sessions)))
var b strings.Builder
fmt.Fprintf(&b, "Sessions (%d):\n", len(sessions))
for i, s := range sessions {
meta := relativeAge(sessionRecency(s), now)
if s.SessionID == active {
meta = "active · " + meta
}
fmt.Fprintf(&b, " %*d. %s %-*s · %s\n",
numW, i+1, shortSessionID(s.SessionID), maxTitle+1, sessionDisplayTitle(s), meta)
}
return strings.TrimSpace(b.String())
}
// shortSessionIDLen is how much of a session ID the chat surfaces show. It
// is also the shorthand /resume and /delete are given back, so every
// listing must truncate to the same width.
// UUIDv7 stores its timestamp at the front, so no fixed shorter prefix is
// guaranteed to distinguish sessions. UUID session references therefore use
// all 36 characters. The limit only abbreviates longer legacy/non-UUID keys.
const shortSessionIDLen = 36
// shortSessionID renders the abbreviated form of a session ID used
// wherever a session is listed.
//
// Truncation is on a rune boundary: slicing bytes could split a
// multi-byte channel-ID-derived session key mid-rune and emit invalid
// UTF-8. UUID keys are ASCII, so this only differs for the exotic cases --
// where it must stay well-formed.
func shortSessionID(id string) string {
if r := []rune(id); len(r) > shortSessionIDLen {
return string(r[:shortSessionIDLen])
}
return id
}
// resolveSessionRef resolves an operator-supplied session reference
// against a session list, the way /resume and /delete both accept one.
//
// An exact ID wins outright -- a full ID names one session unambiguously
// even when it is also the prefix of a longer one -- otherwise the
// reference must be a prefix of exactly one session. It returns (nil,
// false) when nothing matches and (nil, true) when more than one session
// shares the prefix.
func resolveSessionRef(sessions []SessionContext, ref string) (match *SessionContext, ambiguous bool) {
for i, s := range sessions {
if s.SessionID == ref {
return &sessions[i], false
}
}
var found *SessionContext
for i, s := range sessions {
if !strings.HasPrefix(s.SessionID, ref) {
continue
}
if found != nil {
return nil, true
}
found = &sessions[i]
}
return found, false
}
// sessionDisplayTitle is the title a session is shown under, falling
// back to the standard placeholder when none has been set or generated.
func sessionDisplayTitle(sc SessionContext) string {
if sc.Title != "" {
return sc.Title
}
return "(untitled)"
}
// relativeAge renders an instant as a short human age ("5m ago") for
// session listings. The zero time renders as an empty string.
func relativeAge(t, now time.Time) string {
if t.IsZero() {
return ""
}
d := now.Sub(t)
switch {
case d < time.Minute:
return "just now"
case d < time.Hour:
return fmt.Sprintf("%dm ago", int(d.Minutes()))
case d < 24*time.Hour:
return fmt.Sprintf("%dh ago", int(d.Hours()))
case d < 7*24*time.Hour:
return fmt.Sprintf("%dd ago", int(d.Hours()/24))
default:
return t.Format("Jan 2")
}
}
// handleResume switches the active session for the current channel+thread
// to the session whose ID matches or is uniquely prefixed by arg.
func (r *Router) handleResume(ctx context.Context, msg messaging.Message, arg string) (string, error) {
arg = strings.TrimSpace(arg)
if arg == "" {
return "Usage: /resume <session-id>", nil
}
if r.Sessions == nil {
return "Session management is not configured.", nil
}
sessions, err := r.Sessions.List(ctx)
if err != nil {
return "", fmt.Errorf("list sessions: %w", err)
}
match, ambiguous := resolveSessionRef(sessions, arg)
switch {
case ambiguous:
return fmt.Sprintf("Multiple sessions match %q; be more specific.", arg), nil
case match == nil:
return fmt.Sprintf("No session matching %q.", arg), nil
}
return r.resumeSession(msg, *match), nil
}
func (r *Router) resumeSession(msg messaging.Message, s SessionContext) string {
if r.sessionTracker != nil {
r.sessionTracker.setActive(msg.ConversationID.ChannelID, msg.ConversationID.ThreadID, s.SessionID)
}
return fmt.Sprintf("Resumed session %s.", s.SessionID)
}
func (r *Router) handleAgents(ctx context.Context) (string, error) {
if r.Agents == nil {
return "Agent listing is not configured.", nil
}
agents, err := r.Agents.AgentList(ctx)
if err != nil {
return "", fmt.Errorf("list agents: %w", err)
}
if len(agents) == 0 {
return "No active agents.", nil
}
var b strings.Builder
b.WriteString("Active agents:\n")
for _, a := range agents {
fmt.Fprintf(&b, " #%d %s — %s (%s)\n", a.ID, a.Title, a.Status, a.Identity)
}
return strings.TrimSpace(b.String()), nil
}