Linux_post_install/AgentsReport/builder/2026-08-27_telegram-ai-prefix.md

Builder Report — Configurable AI-Bridge Trigger Word for the Telegram Listener

Date: 2026-08-27 Status: COMPLETE — implemented, verified, committed (e6fa0a4), pushed

---

TL;DR

• Request: make the Telegram listener's ai → Gemini bridge prefix configurable ("like communication telegram-listener prefix").
• Change: new TELEGRAM_AI_PREFIX config (default ai) + new prefix verb on the listener; live (per-message) reload like the command map; also editable via pos config telegram.
• Files: bin/pos-communication-telegram-listener 566→623, bin/pos-communication-telegram-sender (config-scope field), completions/pos.bash (regen), DOC/AGENT_Context_Project.md (regen filetable row), DOC/POS.md, DOC/howto/ai.md, AGENT_TODO.md.
• Verification: function-level routing harness (green), CLI verb tests, dispatch smoke via pos, pos config telegram render, gates 0 FAIL, 0 WARN.
• Commit: e6fa0a4 — pushed (4306a53..e6fa0a4).

[DONE]

---

1. Design

• Config seam: TELEGRAM_AI_PREFIX in telegram.env (shared by sender + listener). The listener already had a generic load_config; the key needs no code to load. Added to the telegram # POS_CONFIG: scope (in the sender's header, which owns that scope) so pos config telegram renders/edits it — registry-driven, no config-ui code.
• CLI verb: pos communication telegram listener prefix → shows current word; prefix <word> → validates [A-Za-z0-9][A-Za-z0-9_-]* (one word, no spaces/pattern metachars, no leading - to avoid flag ambiguity), writes TELEGRAM_AI_PREFIX= to telegram.env (chmod 600, mktemp+mv, grep -vE old line). Registered via # POS_SUBCMDS: prefix → completions regenerate.
• Hot reload: like the command map (re-read per message), a new ai_bridge_prefix() reads telegram.env per message. Precedence: file > env var from load_config (daemon start) > default ai. No daemon restart needed after prefix <word>.
• Matching: literal, case-insensitive prefix followed by whitespace. case patterns cannot express "literal word + one space + case-insensitive", so the handler uses a scoped shopt -s nocasematch + quoted-literal =~: ^"$prefix"[[:space:]](.*)$ (quoted variable = literal; nocasematch covers AI/Ai/custom BoT…). Unset immediately to keep the rest of the handler case-sensitive.
• Preserved behavior: bare ai (no trailing space) never matched the original ^[Aa][Ii][[:space:]] regex → still falls through to "Unknown command". ai /reset (or <prefix> /reset) clears the session. Usage/Unknown command/log lines now interpolate the actual prefix.

[DONE]

---

2. Files Changed

File	Change
bin/pos-communication-telegram-listener	prefix_cmd() (show/set/validate/write), ai_bridge_prefix() (hot-reload resolver), handle_message uses $prefix with scoped nocasematch + literal =~, --status shows ai prefix:, usage() documents prefix, # POS_SUBCMDS: prefix, updated header comments
bin/pos-communication-telegram-sender	# POS_CONFIG: telegram scope + TELEGRAM_AI_PREFIX=:AI-bridge trigger word in the telegram listener (default ai)::ai
completions/pos.bash	regen: _pos_subcmds[communication-telegram-listener]="prefix"
DOC/AGENT_Context_Project.md	regen filetable: listener row 566→623
DOC/POS.md	listener table: two prefix rows; paragraph now says <prefix> (default ai ) configurable via verb/config; corrected stale claim that AI errors reply "plus a pos config ai hint" — code replies AI error: … only
DOC/howto/ai.md	Telegram section: trigger word configurable, <prefix> /reset, reply-context wording; troubleshooting points at prefix verb
AGENT_TODO.md	dated Done entry

[DONE]

---

3. Tests Performed

Routing harness — /tmp/ai_prefix_routing_test.sh

Extracts the listener's real functions (handle_message + deps) via sed, routes messages through them with a PATH-stub pos (fixed: timeout pos … runs a child process, so a bash-function stub is invisible) and a stub reply.

Case	Result
ai hello → gemini ask (--session telegram-123 --system … hello), answer replied	✅
AI Hello → routed, prompt kept (case-insensitive)	✅
ai (no space) → Unknown command (preserved edge), no ask	✅
ai (trailing space) → Usage reply	✅
ai /reset → pos ai gemini sessions reset telegram-123, "Memory cleared."	✅
hello → Unknown command (not ai-routed)	✅
TELEGRAM_AI_PREFIX=bot: bot hi → routed; BOT Hi → routed; ai hi → Unknown command	✅
bot /reset → sessions reset	✅
var removed → ai back routed again (hot-reload fallback)	✅

CLI verb — real script, temp CONFIG_DIR

Test	Result
prefix (no arg) → AI bridge prefix: ai + usage hint	✅
prefix bot → writes TELEGRAM_AI_PREFIX=bot to telegram.env, rc 0	✅
prefix after set → AI bridge prefix: bot	✅
prefix 'a b' and prefix 'a.b' → rc 1, validation error	✅
prefix 1ok → accepted (leading digit allowed)	✅
--status → ai prefix: <current>	✅
prefix ai → back to default	✅

Dispatch + config UI

• pos communication telegram listener prefix and flat pos communication telegram-listener prefix both show the current prefix (repo bin/pos on PATH). ✅
• pos config telegram (temp dir) renders TELEGRAM_AI_PREFIX with its description. ✅

Gates

bash -n ×2 · make gen idempotent · make check OK · make lint 0 FAIL / 0 WARN. ✅

[DONE]

---

4. Notes / Remaining Risks

• Matrix listener untouched — it has its own hard-coded ai … bridge (session matrix-<room>); the same treatment is a possible follow-up if wanted.
• The daemon still loads TELEGRAM_BOT_TOKEN/TELEGRAM_CHAT_ID once at start (unchanged); only the prefix hot-reloads.
• A prefix change applies to ALL chats the listener serves (there is one owner chat by design).
• Literal prefix matching means a prefix containing regex metacharacters would be matched literally (quoted), but validation restricts to word chars for predictability.

[DONE]

---

Status: COMPLETE. The ai trigger is now TELEGRAM_AI_PREFIX (default ai), configurable via pos communication telegram listener prefix <word> or pos config telegram, applied live.