document Hermes gateway feature parity

Author: eimexdev

CONTEXT.md

@@ -12,6 +12,9 @@ T3 Agent is the working name for a rich Hermes-native conversation surface and g
 - T3 Code's provider architecture should remain reusable, but the initial product exposes only Hermes.
 - Coding, project, workspace, and specialized sidebar integrations are later capabilities. Existing T3 Code implementations should initially be hidden rather than treated as the core product.
 - V1 targets Discord-like Hermes gateway parity before notification work: Hermes slash commands, streaming and interruption, approvals, clarifications, reconnect/restart recovery, and other core conversational gateway behavior must work end to end.
+- Gateway-visible commands come from Hermes' command/skill/plugin registry. T3 Agent provides searchable `/` autocomplete and forwards the selected command and arguments unchanged; Hermes remains the command implementation.
+- Discord-specific rich formatting and live voice-channel mechanics are not parity requirements. T3 Agent uses its native rich conversation renderer.
+- Voice-message recording/upload and Hermes transcription are the first post-v1 capability. Outbound Hermes TTS is separate and may follow it.
 - Notifications and T3 Connect rollout follow gateway parity rather than compensating for an incomplete interactive surface.
 
 ## Language

docs/research/hermes-gateway-feature-inventory.md

@@ -0,0 +1,83 @@
+# Hermes gateway feature inventory for T3 Agent
+
+Research snapshot: Hermes Agent commit [`e0b9ab5ac5d0b593df4f4a289200fcc116d5f75f`](https://github.com/NousResearch/hermes-agent/tree/e0b9ab5ac5d0b593df4f4a289200fcc116d5f75f), inspected 2026-07-22. Primary source only.
+
+## Decision summary
+
+“Discord parity” is a good semantic v1 target, but it should not mean cloning Discord. T3 Agent should reproduce the Hermes behaviors Discord exposes—durable thread sessions, command execution, streamed turns, interruption, approvals, clarification, model controls, files/voice messages, restart recovery, and proactive delivery—using T3-native UI.
+
+Three important corrections:
+
+1. Discord is already a very complete Hermes gateway. The significant gaps worth borrowing from elsewhere are **structured event transport and session resources from the API server**, **native draft-style streaming from Telegram**, and a few product affordances such as Slack’s private notices and assistant status.
+2. The command source of truth is Hermes’ central `COMMAND_REGISTRY`, not Discord’s command definitions. T3 should fetch/derive autocomplete from Hermes and submit the selected text unchanged. Discord separately mirrors commands into its native picker and is constrained by Discord’s 100-command cap. [Registry and gateway-availability rule](https://github.com/NousResearch/hermes-agent/blob/e0b9ab5ac5d0b593df4f4a289200fcc116d5f75f/hermes_cli/commands.py#L45-L64), [Discord automatic registration](https://github.com/NousResearch/hermes-agent/blob/e0b9ab5ac5d0b593df4f4a289200fcc116d5f75f/plugins/platforms/discord/adapter.py#L5103-L5234)
+3. `/cron` is currently marked CLI-only. Messaging users normally ask the agent to schedule something and Hermes calls the `cronjob` tool; the tool automatically captures the origin chat/thread and can make deliveries continuable. T3 command parity therefore does **not** require exposing `/cron` in v1. [Command registry](https://github.com/NousResearch/hermes-agent/blob/e0b9ab5ac5d0b593df4f4a289200fcc116d5f75f/hermes_cli/commands.py#L195-L200), [cron tool delivery contract](https://github.com/NousResearch/hermes-agent/blob/e0b9ab5ac5d0b593df4f4a289200fcc116d5f75f/tools/cronjob_tools.py#L984-L1087)
+
+## What the Discord gateway actually supports
+
+| Capability | Current behavior | T3 interpretation |
+|---|---|---|
+| Conversation lanes | DMs, guild channels, existing threads, forum posts, `/thread`, and optional automatic thread creation. Thread participation survives restart; first-turn generated titles can rename auto-created threads. | One T3 thread should be one Hermes gateway session. No Discord-style auto-threading is needed because the product is already thread-first. |
+| Admission and context | User and role allowlists, DM lockdown, allowed/ignored/free-response channels, mention gating, bot filtering, per-channel prompts and skill bindings, reply context, and optional recent-channel-history backfill. | Owner authentication is v1; preserve the generic author/source metadata and prompt/skill seams, but guild/mention policy is Discord-specific. |
+| Text commands | Any leading `/command` is normalized into the common gateway command dispatcher. New messages while busy can interrupt, queue, or steer; `/stop` remains an explicit hard escape. | Submit command text to Hermes unchanged. Autocomplete is UI help, not a second implementation. |
+| Native command UI | Handwritten commands cover high-value flows; remaining gateway commands and plugin commands are automatically registered; skills are grouped under `/skill`. | Generate a searchable command palette from Hermes’ registry and installed skills/plugins, with no platform command cap. |
+| Streaming | Sends an initial response and progressively edits it; preserves commentary/tool boundaries as separate segments, rate-limits edits, splits overflow into continuations, stops stale streams after reset/stop, and falls back to a fresh/final send when editing fails. | Render structured deltas/activity when available and retain an edit-based fallback. Never lose the final answer because a preview edit failed. |
+| Working state | Persistent typing refresh plus `👀` on start, replaced by `✅` or `❌` at completion. | Use T3 thread/turn states and activities; emoji reactions are unnecessary. |
+| Approvals | Dangerous commands use buttons for approve once, approve session, approve always (when allowed), or deny; requester/admin authorization, expiry, and `/approve`/`/deny` text fallback are supported. | Native approval cards with the same scopes and a typed-command fallback are core v1. |
+| Clarifications | Multiple-choice questions use buttons plus “Other”; open-ended questions capture the next message. The waiting agent resumes after resolution. | Native T3 user-input cards are core v1; preserve typed replies and timeout/cancellation behavior. |
+| Other components | Confirmation buttons for expensive slash actions, update Yes/No prompts, provider→model picker, and finite-choice pickers for reasoning/fast mode. | Use ordinary T3 dialogs/cards while sending the resulting Hermes command or resolver response. |
+| Inbound media | Images, video, audio, Discord voice-message attachments, arbitrary documents, forwarded/replied attachments, and small text-readable files. Files are cached locally with size and URL-safety checks; voice/audio is transcribed. | Images and files are v1. Voice-message recording/upload + Hermes transcription is the immediate follow-up requested for T3 Agent. |
+| Outbound media | Images/GIFs/video/documents, multi-image batches, audio attachments/native voice-message attempt, and automatic TTS according to `/voice` mode. | Preserve normal attachments in v1; outgoing TTS can ship with or just after voice input. “Audio generation” here means Hermes TTS/media output, not a separate conversation mode. |
+| Live Discord voice | `/voice join|channel|leave|on|tts|off|status`; the bot can join a voice channel, transcribe speakers, speak responses, and optionally mix acknowledgements/ambient audio. | Platform-specific and not needed for T3 parity; a record/send voice-message button is the useful feature. |
+| Proactive work | Background task completions and cron output route through normal adapters. Cron defaults to the originating chat/topic; `attach_to_session` can open and seed a dedicated continuable thread on thread-capable platforms. | T3 must accept outbound deliveries without an open client and map them idempotently to the origin, a dedicated thread, or another configured target. |
+| Handoff | CLI→gateway handoff can create a fresh Discord thread, bind the existing Hermes session, and deliver a continuation notice. | Implement `create_handoff_thread`; it also supplies the thread primitive used by continuable cron. |
+| Restart/reconnect | `/restart` drains work, persists a return destination, restarts, sends “session continues,” and guards against duplicate restart redelivery. Discord has websocket liveness checks, exponential reconnect, event deduplication, durable processing records, and optional missed-message backfill. In-flight Hermes sessions can auto-continue after restart, with a stuck-loop breaker. | Reconnect/replay/idempotency and visible recovery are v1—not operational polish. T3 and Hermes remain independently supervised. |
+| Failures | Sends return explicit success/error metadata; partial overflow can preserve delivered chunks; thread-creation failure is shown and does not silently run in the wrong channel; authorization and expired interactions fail visibly; processing failure gets terminal state. | Every accepted inbound message needs a durable accepted/running/attention/completed/failed state and a retryable vs terminal delivery outcome. |
+
+Discord evidence: [adapter capability summary and state](https://github.com/NousResearch/hermes-agent/blob/e0b9ab5ac5d0b593df4f4a289200fcc116d5f75f/plugins/platforms/discord/adapter.py#L821-L940), [send/edit/overflow](https://github.com/NousResearch/hermes-agent/blob/e0b9ab5ac5d0b593df4f4a289200fcc116d5f75f/plugins/platforms/discord/adapter.py#L2818-L3291), [voice and media senders](https://github.com/NousResearch/hermes-agent/blob/e0b9ab5ac5d0b593df4f4a289200fcc116d5f75f/plugins/platforms/discord/adapter.py#L3293-L4084), [native slash commands](https://github.com/NousResearch/hermes-agent/blob/e0b9ab5ac5d0b593df4f4a289200fcc116d5f75f/plugins/platforms/discord/adapter.py#L4932-L5102), [threads/handoff](https://github.com/NousResearch/hermes-agent/blob/e0b9ab5ac5d0b593df4f4a289200fcc116d5f75f/plugins/platforms/discord/adapter.py#L6126-L6415), [approval and clarify UI](https://github.com/NousResearch/hermes-agent/blob/e0b9ab5ac5d0b593df4f4a289200fcc116d5f75f/plugins/platforms/discord/adapter.py#L6454-L6725), [inbound media normalization](https://github.com/NousResearch/hermes-agent/blob/e0b9ab5ac5d0b593df4f4a289200fcc116d5f75f/plugins/platforms/discord/adapter.py#L7061-L7413), [session/restart behavior](https://github.com/NousResearch/hermes-agent/blob/e0b9ab5ac5d0b593df4f4a289200fcc116d5f75f/docs/session-lifecycle.md#L210-L290).
+
+## Full messaging command inventory
+
+These are the commands currently available to gateways according to the central registry. Aliases resolve on the typed-text path; Discord’s native picker prioritizes handwritten commands and canonical auto-registrations, so it is not itself the complete contract.
+
+- **Session/control:** `/start`; `/new [name]` (`/reset`); `/retry`; `/undo [N]`; `/title [name]`; `/branch [name]` (`/fork`); `/compress ...` (`/compact`); `/rollback [number]`; `/stop`; `/approve [session|always]`; `/deny [all] [reason]`; `/background <prompt>` (`/bg`, `/btw`); `/agents` (`/tasks`); `/queue <prompt>` (`/q`); `/steer <prompt>`; `/goal ...`; `/moa <prompt>`; `/subgoal ...`; `/status`; `/sethome` (`/set-home`); `/resume [name]`; `/sessions`; `/restart`.
+- **Identity/configuration:** `/whoami`; `/profile`; `/model [model] [--provider ...] [--global|--session]`; `/codex-runtime [auto|codex_app_server]`; `/personality [name]`; `/footer [on|off|status]`; `/yolo`; `/reasoning ...`; `/fast ...`; `/voice [on|off|tts|status]`. `/verbose` is gateway-visible only when `display.tool_progress_command` is enabled.
+- **Tools/automation:** `/skills ...` is gateway-visible only when `skills.write_approval` is enabled; `/memory ...`; `/bundles`; `/learn <source>`; `/suggestions ...`; `/blueprint ...`; `/curator ...`; `/kanban ...`; `/reload-mcp`; `/reload-skills`.
+- **Information/operations:** `/commands [page]`; `/help`; `/usage [reset [--force]]`; `/topup`; `/insights [days]`; `/platform <pause|resume|list> [name]`; `/update`; `/version` (`/v`); `/debug [nous|local]`.
+- **Platform-specific:** `/topic [off|help|session-id]` exists for Telegram DM topics. Discord adds `/thread` as a native platform action and extends `/voice` with `join|channel|leave`. Installed skills, bundles, and plugin commands add dynamic slash entries.
+- **Intentionally not messaging commands:** `/cron`, `/tools`, `/toolsets`, `/handoff`, `/history`, `/save`, `/snapshot`, `/config`, `/browser`, and several TUI display/clipboard commands are CLI-only. Their underlying behaviors may still appear through agent tools or gateway internals.
+
+Source: [complete command registry](https://github.com/NousResearch/hermes-agent/blob/e0b9ab5ac5d0b593df4f4a289200fcc116d5f75f/hermes_cli/commands.py#L64-L259), [gateway filter and help generation](https://github.com/NousResearch/hermes-agent/blob/e0b9ab5ac5d0b593df4f4a289200fcc116d5f75f/hermes_cli/commands.py#L444-L481).
+
+## Useful capabilities outside Discord
+
+| Source | Capability stronger than or absent in Discord | Recommendation |
+|---|---|---|
+| Hermes API server | Session list/create/read/update/delete, message history, session fork, persisted-session chat, machine-readable capabilities, asynchronous runs, structured SSE (`message.delta`, tool start/completion, reasoning), approval resolution, and stop endpoints. | Reuse its structured event vocabulary where practical, but it is not full gateway parity by itself: the inspected capabilities advertise approvals but not the gateway’s interactive clarify/proactive-delivery contract. [API surface](https://github.com/NousResearch/hermes-agent/blob/e0b9ab5ac5d0b593df4f4a289200fcc116d5f75f/gateway/platforms/api_server.py#L1-L23), [capability response](https://github.com/NousResearch/hermes-agent/blob/e0b9ab5ac5d0b593df4f4a289200fcc116d5f75f/gateway/platforms/api_server.py#L2074-L2149) |
+| Telegram | Animated native DM drafts instead of repeated message edits; private-DM topics; message deletion for preview cleanup; a command menu generated from the registry. Rich Messages also exceed Discord’s text rendering/size but are intentionally outside this project’s parity goal. | T3 should stream directly into its own message model and support preview cleanup; no need to imitate Telegram UI. [DM topics and handoff](https://github.com/NousResearch/hermes-agent/blob/e0b9ab5ac5d0b593df4f4a289200fcc116d5f75f/plugins/platforms/telegram/adapter.py#L3010-L3077), [command menu](https://github.com/NousResearch/hermes-agent/blob/e0b9ab5ac5d0b593df4f4a289200fcc116d5f75f/plugins/platforms/telegram/adapter.py#L3326-L3370), [native draft streaming](https://github.com/NousResearch/hermes-agent/blob/e0b9ab5ac5d0b593df4f4a289200fcc116d5f75f/plugins/platforms/telegram/adapter.py#L4812-L4893) |
+| Slack | Private/ephemeral notices; multi-workspace routing; Slack Assistant thread status, suggested prompts, and titles; optionally a flat in-channel continuable-cron surface. It also has Block Kit rich rendering, excluded here. | Private owner notices and human-readable activity/status are useful T3 ideas. Multi-workspace and flat-channel semantics are not v1 needs. [Slack capabilities/state](https://github.com/NousResearch/hermes-agent/blob/e0b9ab5ac5d0b593df4f4a289200fcc116d5f75f/plugins/platforms/slack/adapter.py#L631-L745), [private notices](https://github.com/NousResearch/hermes-agent/blob/e0b9ab5ac5d0b593df4f4a289200fcc116d5f75f/plugins/platforms/slack/adapter.py#L1881-L1917), [Assistant prompts/titles](https://github.com/NousResearch/hermes-agent/blob/e0b9ab5ac5d0b593df4f4a289200fcc116d5f75f/plugins/platforms/slack/adapter.py#L3290-L3390) |
+| WhatsApp | Multiple-choice clarification via a native poll and native location pins. | T3 clarification cards already cover the valuable semantic; location can wait. [poll/clarify/location](https://github.com/NousResearch/hermes-agent/blob/e0b9ab5ac5d0b593df4f4a289200fcc116d5f75f/plugins/platforms/whatsapp/adapter.py#L984-L1108) |
+| Matrix | Optional E2EE, read receipts, and reaction-driven approvals/model/choice pickers. | Security and read-state are transport/product concerns, not Hermes parity. T3 native controls are better than reaction commands. [Matrix configuration](https://github.com/NousResearch/hermes-agent/blob/e0b9ab5ac5d0b593df4f4a289200fcc116d5f75f/plugins/platforms/matrix/adapter.py#L1-L20), [reaction controls](https://github.com/NousResearch/hermes-agent/blob/e0b9ab5ac5d0b593df4f4a289200fcc116d5f75f/plugins/platforms/matrix/adapter.py#L2059-L2271), [read receipts](https://github.com/NousResearch/hermes-agent/blob/e0b9ab5ac5d0b593df4f4a289200fcc116d5f75f/plugins/platforms/matrix/adapter.py#L3685-L3718) |
+
+## Generic Hermes contract versus platform affordances
+
+The generic contract is: normalized `MessageEvent` + `SessionSource`; stable platform/chat/thread/profile identity; text/command/media input; authorization; `send` and optional edit/delete/typing/media methods; interactive approval/clarify resolvers; interruption/queueing; session persistence; reconnect; outbound routing; cron/handoff thread creation. [Normalized event](https://github.com/NousResearch/hermes-agent/blob/e0b9ab5ac5d0b593df4f4a289200fcc116d5f75f/gateway/platforms/base.py#L1739-L1853), [source identity](https://github.com/NousResearch/hermes-agent/blob/e0b9ab5ac5d0b593df4f4a289200fcc116d5f75f/gateway/session.py#L148-L205), [optional adapter surface](https://github.com/NousResearch/hermes-agent/blob/e0b9ab5ac5d0b593df4f4a289200fcc116d5f75f/gateway/platforms/base.py#L3037-L3317).
+
+Discord embeds, buttons, emoji status, guild roles, mention rules, forum creation, application-command registration, and live voice channels are platform affordances. T3 must preserve their **meaning** only where it matters: approvals, choices, activity state, access control, command discovery, threads, and voice-message I/O.
+
+## Recommended T3 Agent v1 acceptance checklist
+
+- [ ] Persistent authenticated T3↔Hermes gateway connection; Hermes is already running and independently supervised.
+- [ ] One durable Hermes session per T3 thread; create, list, reopen, title, branch/resume, and continue without CWD/project coupling.
+- [ ] Stream assistant text and commentary/tool activity; final delivery is idempotent and recoverable after disconnect.
+- [ ] Send/cancel/interrupt, busy-message queue/steer behavior, and `/stop` semantics.
+- [ ] Pass every gateway-visible slash command and arguments unchanged; autocomplete is generated from Hermes commands/skills/plugins.
+- [ ] Structured dangerous-command approvals, slash confirmations, clarifications, model picker, reasoning/fast choices, typed fallbacks, authorization, and expiry.
+- [ ] Images and arbitrary file attachments in both directions, including safe caching and visible delivery failures.
+- [ ] Proactive background/cron delivery into the correct existing or newly created thread, including continuable `attach_to_session` behavior.
+- [ ] `/restart` end to end: drain, reconnect, restore the same thread/session, notify success, and suppress duplicate processing.
+- [ ] Durable turn state and explicit retryable/terminal errors; replay/ack sequence prevents duplicate messages after reconnect.
+- [ ] Show active Hermes profile/provider/model read-only; model changes continue through `/model` initially.
+- [ ] Owner-only authentication for v1.
+- [ ] Exclude Discord-specific rich formatting, guild/role/mention policy, forum mechanics, reactions, and live voice-channel participation.
+- [ ] Immediate post-v1: native voice-message record/upload → Hermes transcription; then optional Hermes TTS/audio reply.
+