Files
agent-estate-wiki/systems/hermes-hq-push.md
T

105 lines
5.4 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
title: hermes-hq-push (Hermes HQ iPhone app plugin)
type: system
status: active
created: 2026-11-04
updated: 2026-11-04
verified_on: 2026-11-04
review_after: 2026-12-04
confidence: medium
tags: [push, notifications, plugins, ios, desktop, device-access]
sources: [live-hermes-plugins-list, live-plugin-manifest, live-config]
---
# hermes-hq-push (Hermes HQ iPhone app plugin)
## What it is
`hermes-hq-push` is a **standalone Hermes plugin** (`kind: standalone`, **v0.9.27**, author *Hermes HQ*)
living at `~/.hermes/plugins/hermes-hq-push/` (tree mtime **2026-11-03 11:06**). It is the host-side half
of the **Hermes HQ iPhone app**: Apple push, phone device access, the desktop-app theme, the app's Terminal
page, and Grok Live voice token minting.
Its own manifest states it **replaces `dispatch-push`**, and that *"its registered phones carry over."*
## Verified state (2026-11-04)
| Check | Result |
|---|---|
| `hermes plugins list` | `hermes-hq-push` — **enabled**, `0.9.27`, state `user` |
| `config.yaml` → `plugins.enabled` | line **7556**: `- hermes-hq-push` |
| `~/.hermes/plugins/dispatch-push/` | **absent** — and no `dispatch-push` reference survives in `config.yaml` |
| live tree | `~/.hermes/plugins/hermes-hq-push/` (module files + `dashboard/` subdir + its own test suite) |
| README | none — the manifest `description` is the only prose |
The replacement is therefore **clean**: nothing references the retired plugin, and the new one is explicitly
enabled. Enablement and version are config-verified; individual hook firing was not separately captured.
## Surfaces (grouped from the plugin manifest)
**Push / approvals**
- Finished turns — who replied and what they said.
- Approvals with the command shown, **Approve / Deny from the lock screen**.
- A bot waiting for a password, login, code or answer — the site or the question, **never the value**.
- **Live Lock Screen cards:** every step the bot takes (e.g. *Running npm test…*, the two before it, how
many) is pushed to the card, *sealed so only the phone can read it*; the card says **Done** when the turn
ends.
- Tells the app which scheduled jobs a bot is still working on.
**Device access** (app *Settings › Device Access*) — contacts lookup, location, reminders and events, alarms
and timers, photos, Health, motion, music, and leaving an email or text for Anthony to send. This is what
backs the Conduit-style phone sharing on the Hermes HQ app.
**Desktop app** — adds the **Hermes HQ theme**; opens a shell on the host for the app's Terminal page (the
login shell, as an SSH login would; `plugin-data`'s `terminal.off` disables it); lets a Nous sign-in delete,
archive and rename the chats it created (Hermes refuses them otherwise) and lets the desktop app open chats
the app made (Hermes answers `not_found` otherwise); keeps a bot's **Sessions list fast** on a host that has
run many scheduled jobs; lets the app send into a chat the desktop app has open; page previews; and keeps
the app's performance log on this computer at **`~/.hermes/hq-logs`**.
**Voice** — mints the app's **Grok Live** voice session a short-lived xAI token (subscription sign-in or
`XAI_API_KEY`; the bearer itself never reaches the phone).
**Restart guard** — stops a bot's one-off macOS launchd restart job from looping (those jobs are KeepAlive,
so a one-time restart re-runs forever and locks the app out), and tells a restart script which in-app chats
are mid-reply so a restart can wait.
**Cross-posting** — on request, posts the bot's answer back to the Telegram or Discord chat a conversation
came from.
## Interface
- **Tools:** `device_contacts_search`, `device_request_result`.
- **Hooks:** `pre_approval_request`, `post_approval_response`, `pre_tool_call`, `on_human_input_request`,
`on_human_input_resolved`, `pre_llm_call`, `on_session_end`.
## Configuration
All environment variables are optional. `DISPATCH_*` spellings of the APNs/relay names still work.
| Variable | Purpose |
|---|---|
| `HERMES_HQ_APNS_KEY_PATH`, `HERMES_HQ_APNS_KEY_ID`, `HERMES_HQ_APNS_TEAM_ID` | **Direct APNs mode** — path to the app's `.p8` auth key, its Key ID, and the Apple Developer Team ID that owns the app. *Only the app's developer has these.* |
| `HERMES_HQ_PUSH_RELAY_URL` | Another push relay's HTTPS URL, or `off` to send nothing. **Unset = alerts go through the public Hermes HQ relay, sealed so it cannot read them.** |
| `HERMES_HQ_PUSH_RELAY_KEY` | Only for a private relay that asks for a key. |
No key material is recorded on this page and none appears in the manifest — the relay key is declared
`password: true` and is supplied by environment only.
## Relationship to the other push stacks
- [[systems/push-notifications]] documents the **Cadu/Vory** bridge (`hermes-push`, `vory-push`,
`~/.hermes/push/hermes_push.py`) — a **separate** stack, untouched by this plugin and still `degraded`.
- `dispatch-push`, the previous relay plugin for the same app, is **retired and fully removed** (see the
verification table above).
## Open
- `~/.hermes/hq-logs` retention is not documented anywhere yet — check its growth before it becomes a disk
item.
- The plugin carries a very large surface under one name; if it misbehaves the manifest `description` is the
only capability index.
- **Operational note:** the plugin's `pre_tool_call` guard rejects any tool call whose arguments contain the
literal text of a launchd one-off-restart command — writing *about* that command into a file is blocked
too. Describe it, don't quote it.