PENDING: epic(hermes-agent): add tenant-aware Hermes AI agent management, Telegram integration, module tool gateway, and operations dashboard #668

Context

AWCMS-Mini already provides reusable tenant management, RBAC/ABAC, PostgreSQL RLS, audit logging, workflow approval, module management, reporting, provider hardening, and an admin shell. Hermes Agent provides independent AI-agent profiles, memory, skills, scheduled tasks, messaging gateways, and an authenticated API server.

The initial inference target is OpenCode Go with MiMo-V2.5-Pro:

model:
  provider: opencode-go
  default: mimo-v2.5-pro

Hermes is a Python service, while AWCMS-Mini has a Bun-only backend rule. Therefore Hermes must run as a separate service/container. AWCMS-Mini acts as the tenant-aware control plane and must not embed, fork, or reimplement the Hermes runtime.

This capability is full-online only and optional per tenant.

Objective

Add a reusable hermes_agent system module for:

• registering and governing Hermes Agent profiles/endpoints;
• representing OpenCode Go + MiMo-V2.5-Pro as a validated deployment profile;
• monitoring availability, readiness, resource signals, and safe run telemetry;
• linking Hermes profiles with Telegram users/chats/topics using default-deny policy;
• exposing explicitly allowlisted AWCMS-Mini module capabilities to Hermes;
• applying human approval to high-risk agent actions;
• presenting a tenant-aware operations dashboard;
• retaining safe usage, incident, and audit information.

Validated architecture decisions

• AWCMS-Mini is the control plane; Hermes is a separate runtime.
• No Python runtime is added to the Astro/Bun application process.
• No Docker socket, unrestricted shell, or container lifecycle action is exposed to the web application.
• Profile/container provision, start, stop, and upgrade remain operator/Coolify responsibilities unless a separate, least-privilege orchestrator adapter is designed later.
• Integration uses documented Hermes interfaces only: authenticated API server, health endpoints, and explicitly configured webhooks/events.
• Never read or mutate Hermes SQLite databases, profile files, or private/native-dashboard APIs.
• MiMo-V2.5-Pro is the configurable default, not the only supported model.
• Provider/model calls occur outside database transactions and are timeout-bounded.
• Raw prompts, responses, memory, credentials, and attachments are not logged by default.
• PostgreSQL stores secret references only; raw provider/API/Telegram secrets remain in environment variables or a secret manager.
• Dashboard session information is limited to public aggregate health plus AWCMS-originated runs and explicitly ingested safe telemetry. It must not claim full Hermes/Telegram conversation-history support.
• Telegram conversational integration is separate from social-publishing Telegram adapter feat(social-publishing): add Telegram channel publishing adapter #646; do not share tables, permissions, or bot credentials.

Proposed module contract

• Key: hermes_agent
• Type: system
• API base: /api/v1/hermes
• Admin route: /admin/hermes
• Dependencies: tenant_admin, identity_access, profile_identity, module_management, logging, reporting, workflow

Epic acceptance criteria

• Module follows the existing module descriptor/lifecycle/health/navigation patterns.
• Full-online deployment gate is enforced.
• All tenant-owned data uses tenant_id, PostgreSQL RLS, tenant context, and default-deny ABAC.
• Secret references are used; no raw OpenCode Go, Hermes API-server, or Telegram credentials enter normal settings/logs/audit/API responses.
• Provider client has SSRF defenses, host allowlist, timeout, bounded retry, circuit breaker, and safe error normalization.
• Telegram identity uses immutable numeric IDs, scoped allowlists, and default-deny authorization.
• Agent-to-module access uses capability allowlists and schema validation.
• High-risk mutations require idempotency and reusable workflow approval.
• Dashboard is tenant-aware, permission-gated, accessible, and honest about upstream telemetry limits.
• OpenAPI/AsyncAPI, migrations, tests, docs, changesets, and production-readiness checks remain synchronized.
• bun run check passes for every implementation PR.

Out of scope

• Reimplementing or iframe-embedding the native Hermes dashboard.
• Directly editing Hermes profile/config/state files from AWCMS-Mini.
• Mounting Docker socket or running arbitrary host commands.
• Autonomous publication, email delivery, data deletion, user/role changes, financial actions, or other high-impact action without policy and approval.
• Treating AI output as an authoritative government, health, legal, financial, or security decision.
• Storing or sending NIK, health data, credentials, or other specific personal data to the model by default.

Child issues

• PENDING: docs(hermes-agent): define control-plane architecture, deployment topology, ADR, and threat model #669 — Architecture, ADR, deployment topology, threat model, data classification, and AI/privacy risk assessment.
• PENDING: feat(hermes-agent): scaffold module, tenant schema, RLS, RBAC, and agent registry API #670 — Module scaffold, tenant schema, RLS, RBAC, soft delete, and agent registry API.
• PENDING: feat(hermes-agent): add OpenCode Go and MiMo-V2.5-Pro deployment profile #671 — OpenCode Go + MiMo-V2.5-Pro deployment/model profile with secret-reference-only configuration.
• PENDING: feat(hermes-agent): add authenticated Hermes client, readiness checks, and health collector #672 — Authenticated Hermes client, SSRF-hardened readiness checks, health snapshots, and collector job.
• PENDING: feat(hermes-agent): add secure Telegram identity, chat, topic, and access-policy management #673 — Secure Telegram user/chat/topic identity and desired access-policy management, separate from feat(social-publishing): add Telegram channel publishing adapter #646.
• PENDING: feat(hermes-agent): add capability-based AWCMS module tool gateway #674 — Capability-based AWCMS module tool gateway with HMAC/anti-replay, ABAC/RLS, schema validation, and approval classification.
• PENDING: feat(hermes-agent): add AWCMS-originated agent runs and human approval controls #675 — AWCMS-originated agent runs and reusable human approval controls without claiming full upstream session management.
• PENDING: feat(hermes-agent): add tenant-aware Hermes operations dashboard #676 — Tenant-aware Hermes fleet/detail operations dashboard with explicit unknown/unverified states.
• PENDING: feat(hermes-agent): add usage rollups, budget policies, alerts, incidents, and retention jobs #677 — Provenance-aware usage rollups, configurable budgets, alerts/incidents, and retention/purge jobs.
• PENDING: docs(hermes-agent): add deployment, backup, upgrade, incident-response, and operator SOP #678 — Coolify/container/systemd deployment, backup/restore, upgrade/rollback, secret rotation, incident response, and operator SOP.

Recommended implementation order

#669
  -> #670
     -> #671 -> #672
                 |-> #673
                 |-> #674 -> #675
                 |             |
                 +-------------+-> #676 -> #677
                                      |
                                      +-------> #678

Parallel work is allowed only where the declared dependencies are already complete. Each child remains an atomic PR with its own tests, documentation, and changeset.

Epic completion rule

Close this epic only when all child issues are closed as completed, the module is disabled by default for offline/LAN deployments, production preflight covers enabled Hermes deployments, security review has no unresolved critical/high finding, and end-to-end verification demonstrates tenant isolation, secret redaction, provider failure isolation, Telegram default-deny policy, approval enforcement, and honest dashboard telemetry.

References

• AWCMS-Mini README: https://github.com/ahliweb/awcms-mini/blob/main/README.md
• AWCMS-Mini contributor contract: https://github.com/ahliweb/awcms-mini/blob/main/AGENTS.md
• Hermes providers: https://hermes-agent.nousresearch.com/docs/integrations/providers
• Hermes API server: https://hermes-agent.nousresearch.com/docs/user-guide/features/api-server
• Hermes profiles: https://hermes-agent.nousresearch.com/docs/user-guide/profiles
• Hermes Telegram: https://github.com/NousResearch/hermes-agent/blob/main/website/docs/user-guide/messaging/telegram.md
• OpenCode Go: https://opencode.ai/docs/go/
• MiMo-V2.5-Pro: https://mimo.xiaomi.com/mimo-v2-5-pro/
• UU PDP: https://peraturan.bpk.go.id/Details/229798/uu-no-27-tahun-2022
• PP PSTE: https://peraturan.bpk.go.id/Details/122030/pp-no-71-tahun-2019
• ISO/IEC 42001: https://www.iso.org/standard/42001
• ISO/IEC 23894: https://www.iso.org/standard/77304.html