# nmbr for Hermes Agent

> **Beta.** Chat round-trip, typing and the fail-closed `/approve` flow are verified end-to-end inside a real Hermes gateway (0.19.0, macOS). v0.2 adds native approval cards (tap Approve / Reject on the phone) — unit-tested against Hermes' approval registry, awaiting its first live run. If something breaks, tell us at support@nmbr.ai (include the version and the error) — fixes ship fast.

**Give your Hermes agent a number.** This platform adapter connects [Hermes Agent](https://hermes-agent.nousresearch.com) to [nmbr](https://nmbr.ai): your agent gets an `800-xxx-xxx` nmbr and you talk to it from the nmbr app on your phone — replies, typing indicators, cron deliveries and fail-closed approvals, from any machine with outbound internet (no public URL, no webhook).

## Setup (verified flow)

Requires Hermes Agent ≥ 0.19 on Python 3.11–3.13. Heads-up: on Python 3.14, pip silently
resolves an old Hermes (0.15) because 0.16+ pin `<3.14` — install with
`pipx install --python python3.13 hermes-agent`. A configured model provider
(`hermes model`) is also required before the agent can answer.

1. In the nmbr app: **Agents → Yours → Create an agent**. Copy the agent token (shown once).
2. Install the adapter (three files into `~/.hermes/plugins/nmbr/` — `__init__.py` is required, Hermes imports the plugin through it):
   ```bash
   curl -fsSL https://nmbr.ai/developers/hermes/install.sh | sh
   ```
3. Enable the plugin — Hermes quarantines user-installed plugins until you opt in:
   ```bash
   hermes plugins enable nmbr
   ```
   Answer **No** to "allow this plugin to replace built-in tools" — a messaging adapter never needs that privilege.
4. Enable the platform, and keep approvals interactive, in `~/.hermes/config.yaml`:
   ```yaml
   platforms:
     nmbr:
       enabled: true
   approvals:
     mode: manual   # without this, "smart" approval may auto-approve flagged commands
   ```
5. Run it (foreground; `hermes gateway start` supervises via launchd and won't see your shell's env vars — for service mode put the token in `platforms.nmbr.extra.token` instead):
   ```bash
   NMBR_AGENT_TOKEN=agent:… NMBR_ALLOWED_USERS=123-456-789 hermes gateway run
   ```
6. Open the chat with your agent in nmbr and say hi.

## What you get

- **Two-way chat** — nmbr messages become Hermes turns; replies land as normal messages in the same 1:1, quoting (threading) only when the agent answers an older message. Voice notes arrive as their transcript; images/documents as tagged text.
- **Typing indicator** while the agent works, and Hermes' progress notes for long turns.
- **Approvals, fail-closed — as native cards** (v0.2) — when a command trips Hermes' dangerous-command detector (e.g. a recursive delete), an approval card appears in the nmbr chat showing the command and Hermes' reason. Tap **Approve** to run it once, or **Edit** the card's `scope` to `"session"` / `"always"` first to remember the pattern (like `/approve session` / `/approve always`); **Reject** denies it. Only the person in that 1:1 can decide; nobody else sees the card. The card lives as long as Hermes waits (`approvals.timeout`, default 60 s, + 5 s) — a later tap is answered with "too late" and nothing runs. Typing `/approve` / `/deny` still works, and if the card can't be sent Hermes falls back to its text prompt. Requires `approvals.mode: manual` (step 4).
- **Who can talk to the agent** — `NMBR_ALLOWED_USERS` (nmbrs). nmbr itself already limits senders to people who *added your agent as a contact*; `NMBR_ALLOW_ALL_USERS=true` trusts all of them.
- **Cron / notifications** — set `NMBR_HOME_CHANNEL` to your nmbr (or reply `/sethome` in the chat); `deliver=nmbr` jobs and `send_message` reach you even when the gateway isn't running (standalone sender).

## Config reference

| Env | config.yaml `platforms.nmbr.extra` | Meaning |
|---|---|---|
| `NMBR_AGENT_TOKEN` (required) | `token` | The agent token (`agent:…`) |
| `NMBR_BASE_URL` | `base_url` | API base, default `https://nmbr.ai/api` |
| `NMBR_ALLOWED_USERS` | — | Comma-separated nmbrs allowed to talk |
| `NMBR_ALLOW_ALL_USERS` | — | `true` = every contact who added the agent |
| `NMBR_HOME_CHANNEL` / `_NAME` | `home_channel` | Cron/notification target (your nmbr) |

Depends only on `httpx`, which Hermes already ships. Tests: `python -m pytest` (uses a stubbed Hermes runtime and a mocked Agent API).

## Roadmap

- Clarify buttons (Hermes' multiple-choice questions as cards).
- Media in and out.