chat-actions

Chat Actions — voice-to-data and voice-to-navigation

Every application ships a persistent chat command bar. The user says (or types) what they want — "record three sets of bench press at 45 pounds", "navigate to the screen to create a new exercise" — and the assistant does it, using both the utterance and the context of the screen they're on. Input is chat-shaped but voice-first: users dictate via tools like Wispr Flow, so utterances are conversational, unpunctuated, and reference the visible screen ("add ten pounds to that").

Architecture: LLM router → MCP tools → the app's own endpoints

Every screen: fixed bottom command bar (#assistant-bar)
   │ hx-post /assistant/message.php  (+ screen context)
   ▼
PHP handler (session auth, CSRF, activity log; mints a signed action token)
   ▼
Unified assistant service — Python, Claude Agent SDK (the SAME agent as AMA)
   │ LLM processes the utterance and routes it by activating an MCP tool
   ▼
{app}_actions_mcp  (Python + FastMCP, localhost-only)      + the two read servers
   ├─ navigate(screen, …)      → resolves via the screen registry, returns a directive
   ├─ {entity}_{action}(…)     → POSTs to the app's own PHP endpoints (action token)
   └─ undo_last(…)             → inverse action from the manifest + activity log

• One unified assistant. The AMA page and the command bar are two surfaces of the same Agent SDK service: read tools (record/activity MCP servers), action tools, and navigation. One conversation memory per user; questions, actions, and navigation mix freely in a single utterance.
• The router is the LLM; the tools are MCP. The agent never navigates or writes by itself — it activates a tool on the actions MCP server. Tool descriptions carry the routing knowledge (which screen/action serves which intent), so routing quality is a Phase 1 design artifact, not prompt luck.
• Actions go through the app's own controllers. The actions server's tools call the same /var/www/html/{feature}/save.php-style endpoints a human uses — same validation, same authorization, same activity logging. The read MCP servers stay strictly read-only; nothing ever writes around the PHP layer.
• The actions server is localhost-only — unlike the client-facing read servers, it acts as a user and is reachable only by the assistant service. Per-request authority comes from a short-lived HMAC-signed action token minted by the PHP handler (user id + expiry); internal endpoints accept it in place of the session and enforce the same authorization.