docs/PATCH_INVENTORY.md

# Runtime Patch Inventory (P1-T02)

Critical boot-time integration applied by `scripts/sync_hf.py` when installing the
HermesFace overlay onto upstream [NousResearch/hermes-agent](https://github.com/NousResearch/hermes-agent).

## What is patched vs plugin-based (current state)

| Integration | Mechanism | Status | Notes |
|---|---|---|---|
| Futures + Telegram HTTP routes | `_patch_web_server_futures_dashboard` → `app.include_router(...)` on existing Hermes FastAPI app | **Monkeypatch (deliberate Option A)** | Preserves existing URLs: `/futures`, `/api/futures/*`, `/api/telegram/webhook`. Upstream `_mount_plugin_api_routes` uses a hardcoded prefix and rejects project-local plugins for auto-import, so route mounting remains a text patch. |
| CORS / iframe / CSP headers | `_patch_web_server_cors` | **Monkeypatch** | Required for Hugging Face Spaces iframe embedding. Non-fatal on failure (logged). |
| Telegram webhook public path | `_patch_telegram_webhook_public_path` | **Monkeypatch** | Keeps the documented webhook URL stable. Non-fatal on failure (logged). |
| `futures_trading` tool registration | `$HERMES_HOME/plugins/futures_trading/` via Hermes `PluginManager` + `ctx.register_tool(...)` | **Native plugin (migrated)** | No `toolsets.py` text patch. Six read-only tools + auxiliary task `futures_advisory` are registered through upstream plugin APIs. |
| `futures_trading_tool.py` shim | Compatibility re-exports only | **Shim (no duplicate registration)** | Legacy imports/tests resolve handlers; plugin owns runtime registration. |
| Hermes auxiliary advisory | `agent.auxiliary_client.async_call_llm(task="futures_advisory")` | **Native auxiliary task (migrated)** | Replaces the pre-migration direct `httpx` OpenRouter → Google → Hugging Face chain in `external_ai/advisory.py`. Provider fallback for auxiliary text tasks may still be configured via Hermes `config.yaml` when `HERMES_MANAGE_AUXILIARY_FALLBACKS=true`. |

### Retired / removed patches

- **`toolsets.py` futures_trading registration patch** — removed. Tool registration is plugin-based.
- **`_patch_toolsets_futures_trading`** — removed from `sync_hf.py`.

### Outdated claim (corrected)

Earlier notes suggested that *full replacement with supported hooks requires upstream Hermes plugin APIs not available as stable public surface in this tree*. That was **false for tool registration**: upstream `hermes_cli/plugins.py` exposes stable `ctx.register_tool` and auxiliary task registration, and this migration uses them. It remains **partially true only for dashboard route mounting**, where Option A intentionally keeps the existing monkeypatch to avoid URL breakage.

## Patch table (boot-time text patches)

| Method | Target | Purpose | Failure mode |
|--------|--------|---------|--------------|
| `_patch_web_server_cors` | `hermes_cli/web_server.py` | CORS / X-Frame-Options / CSP for HF iframe | non-fatal log |
| `_patch_web_server_futures_dashboard` | `hermes_cli/web_server.py` | Mount Futures + Telegram routers on existing app | non-fatal log |
| `_patch_telegram_webhook_public_path` | telegram paths | Public webhook path | non-fatal log |

## Hardening status

- Inventory documented (this file).
- Tool registration verified via plugin + `scripts/audit_execution_client_paths.py` (registered tools are read-only; mutation handlers hard-reject).
- Desktop should verify that after boot, `/api/futures/status` is reachable and the tool registry contains only allowed tools.
- Recommendation: convert non-fatal critical patch failures to startup abort once a canary probe confirms expected markers in installed files.