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.

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.