Skip to content

agent-source-boundary.md

Latest commit

 

History

History
70 lines (57 loc) · 4.98 KB

agent-source-boundary.md

File metadata and controls

70 lines (57 loc) · 4.98 KB

Agent Source Boundary and API Decoupling Inventory

  • Status: Proposed
  • Created: 2026-05-17
  • Tracking issue: #2453

Problem

The WebUI currently depends on Hermes Agent Python source being importable at runtime. In local installs this usually means a neighboring checkout; in the multi-container Docker setup it means the WebUI reads the hermes-agent-src volume that the agent container also uses.

That source mount is a compatibility bridge, not the desired long-term contract. Even when mounted read-only on the WebUI side, it couples WebUI releases to Hermes Agent internal module layout and makes the multi-container setup look more isolated than it really is.

Current safety posture

  • The multi-container compose files mount hermes-agent-src read-only into the WebUI service by default.
  • docker_init.bash prunes the agent source subtree from chown so read-only mounts do not break startup.
  • If an operator overrides the compose files with a mutable agent-source mount, startup now emits a notable warning. The WebUI still starts because local dev checkouts and custom deployments may intentionally be writable, but the warning makes the reduced boundary explicit.

Source-access inventory

These are the current WebUI capabilities that still rely on Agent source or hermes_cli/agent modules being importable. Each item should eventually move behind an explicit, versioned Agent API or a packaged library contract that does not require mounting the live source checkout.

WebUI capability Current dependency Desired API / contract Notes
Browser chat execution run_agent.AIAgent imported by api/streaming.py Run lifecycle API: start, observe, status, cancel, approval, clarify, final usage Covered by the runtime-adapter migration in #1925, but still source-backed today.
Runtime event rendering WebUI callbacks around Agent token/reasoning/tool events Stable event envelope for tokens, reasoning, progress, tool lifecycle, approvals, clarify, errors, and final usage The existing run-adapter RFC describes the browser-facing shape; Agent still needs a durable producer contract.
Profile list/create/delete/seed hermes_cli.profiles from api/profiles.py Profile management API with profile metadata, env/runtime context, seed/delete operations, and validation errors WebUI has fallback filesystem handling for some operations, but feature parity follows Hermes CLI internals.
Goal command state hermes_cli.goals from api/goals.py Goal CRUD/control API: get, save, pause/resume/clear, and status Should preserve current /goal WebUI behavior without direct module import.
Slash command registry and plugin commands hermes_cli.commands and hermes_cli.plugins from api/commands.py Command/plugin capability discovery API scoped by active profile WebUI should render command help from a stable capability response.
Provider/auth/model catalogs hermes_cli.models, hermes_cli.auth, and agent.credential_pool from api/config.py Provider registry, model catalog, auth status, OAuth/credential-pool status APIs WebUI has static fallbacks, but exact parity and custom provider state come from Agent internals.
Redaction helper parity agent.redact.redact_sensitive_text from api/helpers.py Redaction service/library contract with signature/version compatibility WebUI keeps a fallback redactor because this import has changed before.
CLI/Gateway session bridge Agent state.db schema and gateway metadata read by sidebar/session helpers Session listing/transcript/metadata API for non-WebUI-originated sessions Direct SQLite/schema coupling should narrow over time, especially for messaging/email/gateway sessions.

Decoupling task list

  1. Keep the Docker default safe: WebUI-side hermes-agent-src stays read-only in two- and three-container compose files.
  2. Keep documenting the boundary honestly: multi-container isolates process, network, and resources, not filesystem/source compatibility.
  3. Warn loudly when the WebUI container sees a writable agent-source mount in Docker, because that weakens the defense-in-depth posture.
  4. Convert runtime execution first through the #1925 RuntimeAdapter path instead of adding new direct imports.
  5. For each inventory row, file or link a follow-up that defines the Agent API response shape before replacing the import.
  6. Do not claim the source mount can be removed until chat execution, provider catalogs/auth status, profiles, goals, commands/plugins, redaction, and imported Agent/Gateway sessions all have stable replacement contracts.

Non-goals for this slice

  • Do not remove HERMES_WEBUI_AGENT_DIR.
  • Do not break local source-checkout development.
  • Do not fail startup solely because the agent source is writable.
  • Do not replace the runtime adapter or Hermes Agent API in this document-only inventory slice.