Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 44 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ You: Have they paid?
Hermes: Yes, paid in full today.
```

**Demo (70 s):** link in the catalog PR · **Install:** `hermes plugins install ueddy/obol`
**Demo (70 s):** [watch on X](https://x.com/DeFiRanch/status/2118752233315791051) · **Install:** `hermes plugins install ueddy/obol` · Listed in the [official plugin catalog](https://github.com/NousResearch/hermes-agent/pull/149915)

---

Expand Down Expand Up @@ -108,13 +108,53 @@ checks your bank details.

Requires Hermes Agent 0.22+. No extra Python dependencies.

## Going live

Out of the box Obol refuses live Stripe keys (`sk_live_…`, `rk_live_…`), both in the provider client and again in
the approval hook. Once you turn live mode on, it runs exactly the same code as test mode: the same Stripe calls,
the same approval prompts, the same scam checks. Bank-transfer mode needs no Stripe key, so none of this applies
to it.

1. **Activate your Stripe account.** Stripe won't accept live invoices until the account is activated (business
details and a payout bank account). That happens on Stripe's side, not in Obol.
2. **Use a restricted key.** A restricted key (`rk_live_…`) is safer than a full secret key. Create one in the
Stripe dashboard with only what Obol uses:

| Resource | Access |
|---|---|
| Customers | Write |
| Invoices (includes invoice items) | Write |
| Charges | Read (fraud-risk level on paid invoices) |
| Disputes | Read |
| Events | Read (recent contact or payment-detail changes) |

3. **Set the key and allow live mode:**

```bash
hermes config set STRIPE_API_KEY rk_live_…
hermes config set plugins.entries.obol.settings.allow_live true
hermes obol doctor # should report live mode and Stripe reachable
```

4. **Do one small real run before you rely on it.** Send yourself a small real invoice (for example $1 to your
own email), pay it, then void it or refund it in the Stripe dashboard. Obol's live path is the same code as
test mode, but the automated suite (`tests/test_stripe_live.py`) only runs against test keys, so this is the
check that confirms your account and key work end to end.

> **In live mode, Stripe emails your client for real.** In test mode, sending only produces a payment link. With
> a live key, approving a send or a reminder makes Stripe email the actual customer, so one approval puts a real
> email in front of a real person. The approval prompt says so too; read the recipient before you approve.

Two things stay test-only on purpose: `hermes obol demo` refuses anything but a test key, and syncing invoices from
Stripe test clocks only exists in test mode.

## For judges

| Check | How |
|---|---|
| Try it in two minutes | `hermes obol demo` with a Stripe test key: sample clients, then four prompts to try |
| Installs cleanly | `hermes plugins validate . --install-deps && hermes plugins doctor . --ci` → 8 tools, 1 hook, install scan **safe** |
| Tests | `python -m pytest`: 234 tests, no keys needed (unit, adversarial, recorded real responses, gateway, Hermes integration) |
| Tests | `python -m pytest`: 231 tests, no keys needed (unit, adversarial, recorded real responses, gateway, Hermes integration) |
| Claims are proven | `tests/test_readme_claims.py` fails if any test named in this README doesn't exist |
| Real, not mocked | live test-mode suite (`tests/test_stripe_live.py`), real-model intake suite (`tests/test_intake_live.py`), recorded real responses, live Telegram run |
| More than a skill | tools, an approval hook, structured extraction via `ctx.llm`, dashboard tab + API, slash command, CLI, automation blueprint, skill |
Expand Down Expand Up @@ -173,7 +213,7 @@ Settings live under `plugins.entries.obol.settings` (Hermes Desktop shows them a

| Setting | Default | Meaning |
|---|---|---|
| `allow_live` | `false` | Must be `true` before a live key is accepted |
| `allow_live` | `false` | Must be `true` before a live key is accepted (see [Going live](#going-live)) |
| `default_currency` | `usd` | Currency when a request doesn't name one |
| `default_days_until_due` | `14` | Payment terms for new invoices |
| `risk_duplicate_window_days` | `30` | Same customer and amount within this many days (`0` = off) |
Expand All @@ -195,7 +235,7 @@ Injection detection is always on.
- **Your model:** `obol_draft_from_message` sends the forwarded message to the model Hermes is configured to use, through `ctx.llm`.
- **Emails:** sending and reminding make the payment provider email your client. In bank-transfer mode nobody is emailed; PDFs are written to `<HERMES_HOME>/plugin-data/obol/invoices/`.
- **Credentials:** `STRIPE_API_KEY` (optional, Stripe mode only; install doesn't ask for it), read only through Hermes's secret route; never logged or stored. Without it, Stripe-mode tools answer "Stripe key not set" and do nothing.
- **Local data:** `<HERMES_HOME>/plugin-data/obol/data.db`: cached invoice metadata, risk findings, and hash-chained activity and security logs (forwarded message text is not stored). Delete the file to clear it.
- **Local data:** `<HERMES_HOME>/plugin-data/obol/data.db`: cached invoice metadata, risk findings, and hash-chained activity and security logs (forwarded message text is not stored). Delete the file to clear it. Bank-transfer details (account name, number, bank, routing) are plugin settings, stored in plain text in Hermes's `config.yaml`. The full number appears only there and on the PDFs: Obol's logs and database hold a fingerprint of the details and the account's last four digits, never the number itself.
- **No telemetry, shell commands, background processes or self-updating code.**

## Development
Expand Down
11 changes: 11 additions & 0 deletions src/obol_lib/gate.py
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,15 @@
_VERBS = {"obol_send_invoice": "finalize and email", "obol_send_reminder": "re-send the payment email for",
"obol_void_invoice": "VOID (cannot be undone)", "obol_mark_paid": "mark as PAID (money received outside the payment page)"}

LIVE_EMAIL_WARNING = "LIVE: approving makes Stripe email this real client now. Check the address."


def _emails_client(tool_name: str, args: dict) -> bool:
"""True for the writes that make Stripe email the customer."""
if tool_name == "obol_create_invoice":
return bool(args.get("send"))
return tool_name in ("obol_send_invoice", "obol_send_reminder")


def describe_create(args: dict, default_currency: str, bank: bool = False) -> str:
cur = str(args.get("currency") or default_currency).lower()
Expand Down Expand Up @@ -84,4 +93,6 @@ def decide(tool_name: str, args: dict, *, mode: str, allow_live: bool, unattende
"message": f"Risk checks could not run ({exc.__class__.__name__}); review carefully."}]
tag = {"live": "LIVE MONEY", "bank": "BANK TRANSFER"}.get(mode, "TEST mode")
message = f"Obol ({tag}): {summary()}.\n{format_flags(flags)}"
if mode == "live" and _emails_client(tool_name, args):
message += f"\n{LIVE_EMAIL_WARNING}"
return {"action": "approve", "message": message, "rule_key": f"obol:{tool_name}:{uuid.uuid4().hex}"}
10 changes: 10 additions & 0 deletions tests/test_gate.py
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,16 @@ def test_live_key_blocked_unless_allowed():
assert allowed["action"] == "approve" and "LIVE MONEY" in allowed["message"]


def test_live_sends_warn_that_a_real_client_is_emailed():
for tool in ("obol_create_invoice", "obol_send_invoice", "obol_send_reminder"):
assert gate.LIVE_EMAIL_WARNING in _decide(tool=tool, mode="live", allow_live=True)["message"], tool
for tool in ("obol_void_invoice", "obol_mark_paid"):
assert gate.LIVE_EMAIL_WARNING not in _decide(tool=tool, mode="live", allow_live=True)["message"], tool
assert gate.LIVE_EMAIL_WARNING not in _decide(args={**CREATE, "send": False}, mode="live",
allow_live=True)["message"]
assert gate.LIVE_EMAIL_WARNING not in _decide()["message"]


def test_unattended_runs_are_blocked_cleanly():
d = _decide(unattended=True)
assert d["action"] == "block" and "unattended" in d["message"] and "Nothing was sent" in d["message"]
Expand Down
Loading