Metadata-Version: 2.4
Name: agentguard-spend-hermes
Version: 0.1.4
Summary: AgentGuard Spend plugin for Hermes Agent (Nous Research). One-step install of local spend caps + signed audit logs for every Anthropic/OpenAI call your Hermes agent makes. No proxy, prompts never leave your machine.
Project-URL: Homepage, https://agentguard.run
Project-URL: AgentGuard SDK (PyPI), https://pypi.org/project/agentguard-spend/
Project-URL: AgentGuard SDK (npm), https://www.npmjs.com/package/@agentguard-run/spend
Project-URL: Hermes Agent, https://github.com/NousResearch/hermes-agent
Project-URL: Source, https://github.com/MerchantGuard/merchantguard-website/tree/main/packages/agentguard-spend-hermes
Author-email: "Dunecrest Ventures Inc." <hello@agentguard.run>
License: AgentGuard(TM) Spend SDK — Alpha License
        Copyright (c) 2026 Dunecrest Ventures Inc.
        
        1. SCOPE.
        This software, including all files under packages/agentguard-spend-python/agentguard_spend/, is
        licensed by Dunecrest Ventures Inc. ("Licensor") subject to the following
        thresholds:
        
          (a) Evaluation Use. Internal evaluation, prototyping, and non-commercial
              development at any call volume.
        
          (b) Free Production Threshold. Production deployments processing 10,000
              or fewer enforcement calls per calendar month, in aggregate across
              all instances operated by the licensee, are permitted under this
              License without additional fee.
        
          (c) Commercial License Required. Production deployments processing more
              than 10,000 enforcement calls per calendar month, deployments
              operated for the benefit of third parties as a service, redistribution,
              sublicensing, public hosting, and republication each require a
              separate commercial license agreement with Licensor.
        
        Commercial-license inquiries: invest@agentguard.run
        
        2. NO PATENT LICENSE GRANTED.
        Nothing in this License grants, expressly or by implication, any patent license
        to any patent, patent application, or other intellectual property right of
        Licensor. All patent rights are expressly reserved. The patent applications
        identified in Section 7 are not licensed by this License.
        
        3. SEPARATE GRANT FOR DEMONSTRATION ASSETS.
        The following assets, and ONLY these assets, are released under the Apache
        License, Version 2.0, the text of which is reproduced or available at
        https://www.apache.org/licenses/LICENSE-2.0:
        
          - The test vectors under packages/agentguard-spend-python/test_vectors/
          - The documentation examples under packages/agentguard-spend-python/examples/
          - The contents of packages/agentguard-spend-python/README.md
        
        The source code under packages/agentguard-spend-python/agentguard_spend/ is NOT included in this
        Apache License 2.0 grant. The Python type definitions, policy engine,
        decision log, store implementation, cost table, and wrapper code under
        agentguard_spend/ are licensed only under the alpha evaluation terms of
        Section 1 above.
        
        4. WARRANTY DISCLAIMER.
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL
        DUNECREST VENTURES INC. BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY
        ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
        DEALINGS IN THE SOFTWARE.
        
        5. SUCCESSORS AND ASSIGNS.
        This License binds and benefits the parties' respective successors and assigns.
        In the event of an asset sale, merger, change of control, or other transfer of
        the Licensor's rights in this software, all rights and obligations under this
        License inure to the benefit of and are binding upon Licensor's successor or
        assignee. Outstanding evaluation grants survive change-of-control, but the
        successor or assignee may, upon thirty (30) days' written notice, terminate
        ongoing evaluation grants in favor of a commercial-license requirement.
        
        6. TERMINATION.
        Licensor may terminate this License with thirty (30) days' written notice for
        any reason or no reason. Upon termination, Licensee shall cease all use of the
        software under agentguard_spend/ and shall destroy all copies in Licensee's possession.
        
        7. PATENT NOTICE (35 U.S.C. § 287).
        Protected by U.S. patent-pending technology, including the following
        provisional patent applications filed with the United States Patent and
        Trademark Office:
        
          - Application No. 63/983,615 (filed February 15, 2026)
          - Application No. 63/983,621 (filed February 15, 2026)
          - Application No. 63/983,843 (filed February 16, 2026)
          - Application No. 63/984,626 (filed February 17, 2026)
          - Application No. 64/071,781 (filed May 21, 2026)
          - Application No. 64/071,789 (filed May 21, 2026)
        
        Additional patents pending. All patent rights expressly reserved per
        Section 2 above.
        
        AgentGuard(TM) is a trademark of Dunecrest Ventures Inc. (USPTO Serial
        No. 99462472, pending). MerchantGuard(TM) is a trademark of Dunecrest
        Ventures Inc. (USPTO Serial No. 99051215, pending).
        
        For commercial licensing: invest@agentguard.run
License-File: LICENSE
Keywords: agent-plugin,agentguard,ai-agent-security,hermes,hermes-agent,llm-governance,nous-research,spend-control
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: agentguard-spend>=0.1.4
Requires-Dist: pyyaml>=6.0
Description-Content-Type: text/markdown

# agentguard-spend-hermes

> One-step install of [AgentGuard™ Spend](https://pypi.org/project/agentguard-spend/) into [Hermes Agent](https://github.com/NousResearch/hermes-agent) (Nous Research).

Adds **local spend caps + Ed25519-signed audit logs** to every Anthropic and OpenAI call your Hermes agent makes. No proxy. No cloud component. Prompts and provider keys never leave your machine.

Built for Hermes's unattended-by-default workflow: cron jobs, sleep loops, multi-platform messaging bridges (Telegram, Discord, Slack, WhatsApp, Signal).

## Install

```bash
# In the same virtualenv as Hermes
uv pip install agentguard-spend-hermes
```

That's it. Hermes's plugin manager auto-discovers the plugin via the `hermes_agent.plugins` entry point on next startup.

## First-run auto-bootstrap

On first Hermes startup after install, the plugin:

1. Generates `~/.hermes/agentguard/private.key` + `public.key` (Ed25519)
2. Writes a default `policy.yaml` ($5/day soft cap downgrades Opus → Sonnet, $20/day hard cap blocks, $2/min burst guard)
3. Monkey-patches the Anthropic and OpenAI client constructors so every LLM call is policy-checked + signed

You'll see in the Hermes log:

```
agentguard-spend: wrote default policy to ~/.hermes/agentguard/policy.yaml (locale: en-US)
agentguard-spend: generated signing keypair (private=..., public=...)
agentguard-spend: active (anthropic=True, openai=early, policy=...)
```

The policy file is localized to your system locale at first-write (`en-US`, `es-419`, or `pt-BR`).

## When a cap fires

**Downgrade (soft cap):**

```
[hermes] anthropic.messages.create model=claude-opus-4-7
[agentguard] downgrade: claude-opus-4-7 -> claude-sonnet-4-6 (daily soft cap)
[hermes] continuing with sonnet
```

**Block (hard cap):**

```
[hermes] anthropic.messages.create model=claude-opus-4-7
[agentguard] block: hard daily ceiling exceeded
[hermes] AgentGuardBlockedError raised — agent halts this turn
```

## Configure

Edit `~/.hermes/agentguard/policy.yaml` and restart Hermes. Example:

```yaml
id: hermes-default-v1
name: Hermes default caps
version: 1
effectiveFrom: "2026-01-01T00:00:00Z"
mode: enforce

scope:
  tenantId: hermes-personal

caps:
  - amountCents: 500     # $5/day soft cap
    window: per_day
    action: downgrade
    downgradeTo: claude-sonnet-4-6
  - amountCents: 2000    # $20/day hard cap
    window: per_day
    action: block
  - amountCents: 200     # $2/minute burst guard
    window: per_minute
    action: block
```

## Disable temporarily

```bash
export AGENTGUARD_DISABLE=1   # plugin loads but does nothing
```

## Per-platform spend caps

Set `HERMES_AGENT_ID` differently in each Hermes process to scope caps:

```bash
# Telegram bridge process
export HERMES_AGENT_ID=hermes-telegram

# Discord bridge process
export HERMES_AGENT_ID=hermes-discord

# Cron job
export HERMES_AGENT_ID=hermes-cron
```

Then write per-agent caps in `policy.yaml`:

```yaml
caps:
  - amountCents: 1000
    window: per_day
    scope: {agentId: hermes-telegram}
    action: block
  - amountCents: 500
    window: per_day
    scope: {agentId: hermes-cron}
    action: block
```

## Verify the audit log

```python
from agentguard_spend import verify_chain
import pathlib, json

public_key = pathlib.Path("~/.hermes/agentguard/public.key").expanduser().read_bytes()
entries_path = pathlib.Path("~/.hermes/agentguard/decisions.ndjson").expanduser()
entries = [json.loads(line) for line in entries_path.read_text().splitlines()]
result = verify_chain(entries, public_key)
print("OK" if result.ok else f"Chain broken at #{result.sequence}: {result.reason}")
```

## What this plugin does NOT change in Hermes

- Hermes's request retry logic
- Hermes's credential refresh flow
- Hermes's interrupt / cancel pattern
- Hermes's MCP / tool-call layer
- Any of the existing skills

Strictly an LLM-call-intercept layer between Hermes and the Anthropic/OpenAI wire.

## Localization

Block traces render in the active locale:
- 🇺🇸 `en-US` (default)
- 🇲🇽 🇦🇷 🇨🇴 🇨🇱 `es-419` (Latin American Spanish)
- 🇧🇷 `pt-BR` (Brazilian Portuguese)

Resolution chain: explicit `AGENTGUARD_LOCALE` env var → `LC_ALL` / `LC_MESSAGES` / `LANG` → system locale → en-US fallback.

## License

BUSL-1.1. Free for production deployments processing **up to 10,000 enforcement calls per calendar month**. Commercial licensing for higher volumes or service redistribution: `invest@agentguard.run`.

## Patents

Protected by 7 U.S. patent-pending applications (App. Nos. 63/983,615; 63/983,621; 63/983,843; 63/984,626; 64/071,781; 64/071,789; plus DV-2026-007 in active filing). See https://agentguard.run/patents.

## Links

- **Homepage:** https://agentguard.run
- **Underlying SDK:** [`agentguard-spend`](https://pypi.org/project/agentguard-spend/) (PyPI)
- **TypeScript counterpart:** [`@agentguard-run/spend`](https://www.npmjs.com/package/@agentguard-run/spend) (npm)
- **Hermes Agent:** https://github.com/NousResearch/hermes-agent
- **Contact:** `invest@agentguard.run`
