105 lines
5.4 KiB
Markdown
105 lines
5.4 KiB
Markdown
---
|
||
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.
|