Chat: Hermes target via Runs API (tool-progress + approval)

[mikkisguy]

Parent

Chat Interface — Design Spec (docs/superpowers/specs/2026-06-19-chat-interface-design.md)

What to build

Make the Hermes target work correctly for admin use: stream responses via
Hermes's Runs API, surface tool-progress, and resolve human-in-the-loop
approvals. This is a core reliability requirement (not deferred).

• lib/chat/hermes-runs.ts — client for the Hermes Runs API: createRun,
  streamEvents(runId) (async iterator yielding normalized events),
  resolveApproval(runId, decision). Map Hermes event types
  (e.g. hermes.tool.progress, pending-approval) onto the hub's SSE protocol.
  Verify the exact POST /v1/runs request body against the running Hermes
  instance during implementation — the docs describe the lifecycle but not the
  full request schema (use GET /v1/capabilities or a trial curl).
• /api/chat — when target.provider === 'hermes', use the Runs path instead of
  chat-completions: create a run with the assembled messages, stream events,
  forward tool-progress and approval-requested to the client, and on
  approval-requested pause for the client's decision then call
  resolveApproval.
• SSE events emitted: tool-progress, approval-requested, approval-resolved.
• UI: collapsible tool-progress ("tool activity") blocks; an explicit
  "Admin mode (Hermes)" indicator whenever the Hermes toolset is live;
  inline Approve/Deny on approval-requested. Approval timeout → mark the turn
  awaiting-approval (resumable).
• Config: HERMES_API_BASE (default http://localhost:8642/v1), HERMES_API_KEY.

Acceptance criteria

• hermes-runs.ts implements createRun / streamEvents / resolveApproval; the POST /v1/runs body is verified against the live instance
• target=hermes streams the assistant response via Runs events
• hermes.tool.progress events render as collapsible tool-activity blocks
• approval-requested → inline Approve/Deny; resolving calls POST /v1/runs/{id}/approval
• "Admin mode (Hermes)" indicator shown when target=hermes
• approval timeout → turn marked awaiting-approval and resumable
• HERMES_API_KEY stays server-side; hub is the only caller of Hermes
• tests: a Hermes run with a tool-progress event and an approval-requested → resolved sequence (mocked)

Blocked by

• Chat: provider abstraction + streaming hub + persistence + minimal UI #48 — Chat: provider abstraction + streaming hub + persistence + minimal UI

References

• docs/superpowers/specs/2026-06-19-chat-interface-design.md — §Architecture (Why two transports), §Components (hermes-runs.ts, route.ts), §SSE Event Protocol, §Security
• Hermes API server docs: https://hermes-agent.nousresearch.com/docs/user-guide/features/api-server