feat(telegram): publish the full command surface in /help

The menu and /help were generated from a hand-maintained spec list that had
drifted from the executable surface: /approve and /deny are real handlers but
were published nowhere, while /rollback and /stop are Telegram-only.

Registration now reads a single handler table, and a regression test derives
the executable set from messaging.LocalCommands() plus that table, failing when
the published specs and the executable surface disagree in either direction.

/approve and /deny are published with their Telegram meaning, the
dangerous-command approval list, not the shared task-approval copy; that split
is archie-core-ho86. The two tests that pinned them as hidden commands are
updated to the published decision. /help now also asserts it carries every
published command's description, not only its usage.
This commit is contained in:
sam committed 2026-09-22 05:47:54 +10:00
1 parent 001a27fb15
commit 636a17b9db
5 files changed
+90 -31

No files matched your search

+8
View File
@@ -28,6 +28,14 @@ var gatewayCommandSpecs = []commandSpec{
{Command: "spawn", Description: "Create a tracked task", Usage: "/spawn [identity=name] [repo=owner/name] [workflow=name] <title>"},
{Command: "settings", Description: "Inspect or change runtime settings", Usage: "/settings [list|get <kind>|set <kind> <field>=<value> ...]"},
{Command: "cancel", Description: "Cancel a queued or waiting task", Usage: "/cancel [identity=name] <task-id>"},
// /approve and /deny are Telegram's own dangerous-command approval surface:
// dangerous.go lists the pending commands and the inline buttons decide. The
// shared command specs use /approve for task approval instead, and Telegram's
// exact-match handler shadows that path, so /help must describe the Telegram
// meaning. Reconciling the split is archie-core-ho86; do not copy the shared
// task-approval copy here.
{Command: "approve", Description: "Show pending dangerous commands to approve", Usage: "/approve"},
{Command: "deny", Description: "Show pending dangerous commands to deny", Usage: "/deny"},
{Command: "start", Description: "Confirm that Archie is running", Usage: "/start"},
{Command: "new", Description: "Start a fresh session, clearing conversation history", Usage: "/new [title]"},
{Command: "reset", Description: "Alias for /new", Usage: "/reset [title]"},
@@ -7,6 +7,40 @@ import (
"github.com/samcharles93/archie-core/internal/domain/messaging"
)
// The published menu and /help must describe the commands Telegram can actually
// execute, no more and no less. A command that is typeable but unpublished is
// undiscoverable; a published command with no handler is a lie. Both sides are
// derived from their real sources -- the shared router's LocalCommands and the
// local handler table -- so adding either without the other fails here.
func TestPublishedCommandsMatchExecutableSurface(t *testing.T) {
executable := make(map[string]string)
for _, command := range messaging.LocalCommands() {
executable[strings.TrimPrefix(command, "/")] = "the shared router"
}
for _, handler := range telegramTextHandlers {
executable[strings.TrimPrefix(handler.command, "/")] = "a Telegram handler"
}
published := make(map[string]bool, len(gatewayCommandSpecs))
for _, spec := range gatewayCommandSpecs {
if published[spec.Command] {
t.Errorf("gatewayCommandSpecs publishes /%s twice", spec.Command)
}
published[spec.Command] = true
}
for command, source := range executable {
if !published[command] {
t.Errorf("/%s is executable via %s but missing from the menu and /help", command, source)
}
}
for command := range published {
if _, ok := executable[command]; !ok {
t.Errorf("/%s is published but nothing on Telegram executes it", command)
}
}
}
// TestStatusAndTasksCopyMatchesWhatEachCommandDoes pins the operator-facing
// division of labour archie-core-wp9s restored: /status reports daemon health
// and says nothing about the task list, /tasks reports the work view and says
+9 -15
View File
@@ -935,17 +935,11 @@ func TestDangerousCommandHelpContainsNewCommands(t *testing.T) {
if sentText == "" {
t.Fatal("help sent no rich message")
}
for _, want := range []string{"/rollback", "/stop"} {
for _, want := range []string{"/rollback", "/stop", "/approve", "/deny"} {
if !strings.Contains(sentText, want) {
t.Errorf("help text missing %q", want)
}
}
// /approve and /deny should NOT appear in help (they are hidden).
for _, hidden := range []string{"/approve\n", "/deny\n"} {
if strings.Contains(sentText, hidden) {
t.Errorf("help text contains hidden command %q", hidden)
}
}
}
func TestParseDangerousCallback(t *testing.T) {
@@ -973,19 +967,19 @@ func TestParseDangerousCallback(t *testing.T) {
}
}
// Telegram-only commands must be published, not hidden: a command a user can
// type but cannot discover is exactly the omission this surface exists to
// prevent. /approve and /deny used to be deliberately hidden; they are
// published now, and archie-core-ho86 records the split between Telegram's
// dangerous-command /approve and the shared task-approval spec of the same name.
func TestDangerousCommandSpecDescriptions(t *testing.T) {
found := make(map[string]bool)
for _, spec := range gatewayCommandSpecs {
found[spec.Command] = true
}
for _, cmd := range []string{"rollback", "stop"} {
if !found[cmd] {
t.Errorf("/%s is missing from gatewayCommandSpecs", cmd)
}
}
for _, cmd := range []string{"approve", "deny"} {
if found[cmd] {
t.Errorf("/%s should NOT be in gatewayCommandSpecs (hidden command)", cmd)
for _, command := range []string{"rollback", "stop", "approve", "deny"} {
if !found[command] {
t.Errorf("/%s is missing from gatewayCommandSpecs", command)
}
}
}
+36 -16
View File
@@ -250,23 +250,43 @@ func (g *Gateway) Start(ctx context.Context, client messaging.ChatContract, life
}
}
// telegramTextHandler is one text command the Telegram adapter answers itself,
// before the shared router sees it.
type telegramTextHandler struct {
command string
match bot.MatchType
build func(*Gateway, messaging.ChatContract) bot.HandlerFunc
}
// telegramTextHandlers is the single source for the commands Telegram answers
// locally. Registration reads it, and so does
// TestPublishedCommandsMatchExecutableSurface, which proves the published menu
// covers the executable surface: a handler added here without a spec in
// gatewayCommandSpecs fails that test, so a command cannot become typeable
// without becoming discoverable.
var telegramTextHandlers = []telegramTextHandler{
{"/status", bot.MatchTypeExact, func(g *Gateway, c messaging.ChatContract) bot.HandlerFunc { return g.statusHandler(c) }},
{"/whoami", bot.MatchTypeExact, func(g *Gateway, c messaging.ChatContract) bot.HandlerFunc { return g.whoamiHandler(c) }},
{"/profile", bot.MatchTypeExact, func(g *Gateway, c messaging.ChatContract) bot.HandlerFunc { return g.profileHandler(c) }},
{"/sessions", bot.MatchTypeExact, func(g *Gateway, c messaging.ChatContract) bot.HandlerFunc { return g.sessionsHandler(c) }},
{"/resume", bot.MatchTypeExact, func(g *Gateway, c messaging.ChatContract) bot.HandlerFunc { return g.resumeHandler(c) }},
{"/agents", bot.MatchTypeExact, func(g *Gateway, c messaging.ChatContract) bot.HandlerFunc { return g.agentsHandler(c) }},
{"/version", bot.MatchTypeExact, func(g *Gateway, _ messaging.ChatContract) bot.HandlerFunc { return g.versionHandler() }},
{"/update", bot.MatchTypeExact, func(g *Gateway, _ messaging.ChatContract) bot.HandlerFunc { return g.updateHandler() }},
{"/settings", bot.MatchTypePrefix, func(g *Gateway, _ messaging.ChatContract) bot.HandlerFunc { return g.settingsHandler() }},
{"/start", bot.MatchTypeExact, func(g *Gateway, _ messaging.ChatContract) bot.HandlerFunc { return g.startHandler() }},
{"/help", bot.MatchTypeExact, func(g *Gateway, _ messaging.ChatContract) bot.HandlerFunc { return g.helpHandler() }},
{"/restart", bot.MatchTypeExact, func(g *Gateway, _ messaging.ChatContract) bot.HandlerFunc { return g.restartHandler() }},
{"/rollback", bot.MatchTypePrefix, func(g *Gateway, _ messaging.ChatContract) bot.HandlerFunc { return g.rollbackHandler() }},
{"/stop", bot.MatchTypePrefix, func(g *Gateway, c messaging.ChatContract) bot.HandlerFunc { return g.stopHandler(c) }},
{"/approve", bot.MatchTypeExact, func(g *Gateway, _ messaging.ChatContract) bot.HandlerFunc { return g.approveHandler() }},
{"/deny", bot.MatchTypeExact, func(g *Gateway, _ messaging.ChatContract) bot.HandlerFunc { return g.denyHandler() }},
}
func (g *Gateway) registerCommandHandlers(b *bot.Bot, client messaging.ChatContract) {
b.RegisterHandler(bot.HandlerTypeMessageText, "/status", bot.MatchTypeExact, g.statusHandler(client))
b.RegisterHandler(bot.HandlerTypeMessageText, "/whoami", bot.MatchTypeExact, g.whoamiHandler(client))
b.RegisterHandler(bot.HandlerTypeMessageText, "/profile", bot.MatchTypeExact, g.profileHandler(client))
b.RegisterHandler(bot.HandlerTypeMessageText, "/sessions", bot.MatchTypeExact, g.sessionsHandler(client))
b.RegisterHandler(bot.HandlerTypeMessageText, "/resume", bot.MatchTypeExact, g.resumeHandler(client))
b.RegisterHandler(bot.HandlerTypeMessageText, "/agents", bot.MatchTypeExact, g.agentsHandler(client))
b.RegisterHandler(bot.HandlerTypeMessageText, "/version", bot.MatchTypeExact, g.versionHandler())
b.RegisterHandler(bot.HandlerTypeMessageText, "/update", bot.MatchTypeExact, g.updateHandler())
b.RegisterHandler(bot.HandlerTypeMessageText, "/settings", bot.MatchTypePrefix, g.settingsHandler())
b.RegisterHandler(bot.HandlerTypeMessageText, "/start", bot.MatchTypeExact, g.startHandler())
b.RegisterHandler(bot.HandlerTypeMessageText, "/help", bot.MatchTypeExact, g.helpHandler())
b.RegisterHandler(bot.HandlerTypeMessageText, "/restart", bot.MatchTypeExact, g.restartHandler())
b.RegisterHandler(bot.HandlerTypeMessageText, "/rollback", bot.MatchTypePrefix, g.rollbackHandler())
b.RegisterHandler(bot.HandlerTypeMessageText, "/stop", bot.MatchTypePrefix, g.stopHandler(client))
b.RegisterHandler(bot.HandlerTypeMessageText, "/approve", bot.MatchTypeExact, g.approveHandler())
b.RegisterHandler(bot.HandlerTypeMessageText, "/deny", bot.MatchTypeExact, g.denyHandler())
for _, handler := range telegramTextHandlers {
b.RegisterHandler(bot.HandlerTypeMessageText, handler.command, handler.match, handler.build(g, client))
}
}
func (g *Gateway) startListening(ctx context.Context, b *bot.Bot, _ channels.Lifecycle) error {
@@ -76,6 +76,9 @@ func TestHelpDescribesPublishedCommandsAndChat(t *testing.T) {
if !strings.Contains(sentText, spec.Usage) {
t.Errorf("help text does not contain exact usage %q:\n%s", spec.Usage, sentText)
}
if !strings.Contains(sentText, spec.Description) {
t.Errorf("help text does not contain description %q for /%s:\n%s", spec.Description, spec.Command, sentText)
}
}
if strings.Contains(sentText, "not yet wired") {
t.Errorf("help text still claims working LLM chat is not wired:\n%s", sentText)