PENDING: feat(hermes-agent): add capability-based AWCMS module tool gateway #674

Parent epic: #668
Depends on: #670, #672

Context

“Integration with other modules” must not mean giving Hermes a database connection, admin cookie, unrestricted OpenAPI access, or shell access. The safe boundary is a narrow capability broker with per-agent scopes, schemas, risk classification, anti-replay controls, and audit.

Objective

Add a provider-neutral agent tool gateway that exposes explicitly registered AWCMS capabilities to a Hermes profile without bypassing module services, ABAC, RLS, workflow, idempotency, or audit.

Scope

Capability registry

Each capability declares:

• stable key and owning module;
• description and version;
• request/response JSON schema;
• risk class: read, draft, mutation, or prohibited;
• required AWCMS permission;
• whether human approval and Idempotency-Key are mandatory;
• timeout, result-size, and rate limits;
• data classifications accepted/returned;
• enabled deployment/tenant conditions.

Tables/API

• awcms_mini_hermes_capabilities
• awcms_mini_hermes_module_bindings
• awcms_mini_hermes_service_credentials containing hashes/IDs or secret references only
• GET /api/v1/hermes/agents/{agentId}/capabilities
• POST /api/v1/hermes/tool-calls using dedicated agent service authentication

Initial safe examples

• Read module catalog/health.
• Read aggregate visitor analytics, never raw IP/user-agent by default.
• Read safe audit/operational summaries.
• Create a blog/news draft suggestion, never publish.
• Create an email announcement draft, never dispatch.
• Read workflow tasks visible to the linked actor.

All capability handlers must call existing application services; no direct table shortcut.

Authentication and security

• Dedicated per-agent HMAC/service credential, separate from user session and Hermes API-server key.
• Timestamp, nonce, body hash, maximum skew, replay store, and constant-time verification; reuse the existing sync-HMAC pattern where appropriate.
• Capability allowlist + actor/tenant binding + ABAC/RLS.
• Prompt text is untrusted input; validate structured arguments against schema.
• Reject unknown fields, oversized values, URLs/files outside explicit policy, and secret-shaped content.
• High-risk actions route to workflow approval; no “agent is admin” shortcut.
• Log capability key/status/latency/correlation ID, not raw prompt or secret data.

Acceptance criteria

• An unbound agent cannot discover or call tenant capabilities.
• A bound agent sees only explicitly enabled capability keys.
• Replay, expired timestamp, wrong signature, wrong tenant, and disabled module calls fail.
• Initial capabilities use existing module service layers.
• Draft capability cannot publish/send/approve.
• Aggregate analytics capability cannot return raw visitor identifiers by default.
• Mutation risk requires idempotency and workflow approval.
• OpenAPI/AsyncAPI, capability docs, threat model, and tests are updated.
• A changeset is added.
• bun run check passes.

Out of scope

• General-purpose SQL, shell, filesystem, Docker, or arbitrary URL tools.
• Exposing every OpenAPI endpoint automatically.
• Bypassing module business rules.