PENDING: feat(hermes-agent): add AWCMS-originated agent runs and human approval controls #675

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

Context

AWCMS-Mini needs to submit bounded agent work and track its own runs, but the public Hermes API does not provide a stable full-session-management surface. The implementation must track only AWCMS-originated work and must not promise global Hermes/Telegram conversation history or reliable remote cancellation.

Objective

Add safe AWCMS-originated run orchestration through the authenticated Hermes API server and connect high-risk tool requests to the reusable workflow approval engine.

Scope

Tables

• awcms_mini_hermes_runs
• awcms_mini_hermes_run_events
• optional safe result/artifact references; no raw response body by default

Run states:

• queued
• awaiting_approval
• running
• succeeded
• failed
• timed_out
• rejected
• unknown

API

• POST /api/v1/hermes/agents/{agentId}/runs
• GET /api/v1/hermes/runs
• GET /api/v1/hermes/runs/{runId}
• approval/rejection continues through existing workflow task/decision endpoints.

Behavior

• Submit through documented Hermes OpenAI-compatible API server.
• Bind every run to tenant, requesting actor, agent, purpose, data classification, correlation ID, timeout, and capability policy.
• Store a prompt hash and safe metadata by default, not raw prompt/response.
• Optional retention of a redacted result requires explicit policy and expiry.
• Preserve provider usage fields when returned, but mark absent fields as unknown.
• High-risk capability requests create workflow tasks and stop until an authorized human decides.
• Reuse self-approval guard; requesting agent/user cannot approve its own high-risk action.
• Result delivery must not directly trigger publish/send/delete/access-change actions.
• Status becomes unknown when upstream completion cannot be proven; never fabricate success.

Security requirements

• Per-user and per-agent rate limits, concurrency limits, max turns/tokens where supported, timeout, and circuit breaker.
• Input size/type validation and sensitive-data policy.
• Prompt injection cannot change capability binding or approval requirements.
• No browser-to-Hermes direct credential exposure.
• No automatic retry of non-idempotent external effects.
• Cancellation is explicitly out of MVP unless a stable documented upstream API exists; timeout/local abandonment is not reported as confirmed remote cancellation.

Acceptance criteria

• Only authorized users can start a run on a tenant-bound agent.
• Run list/detail is RLS- and ABAC-protected.
• Prompt/response bodies are absent from default logs/audit/storage.
• Success, failure, timeout, rejection, and unknown states are distinguished.
• High-risk tool requests require workflow approval and self-approval is blocked.
• Provider failure cannot roll back or block an AWCMS operational transaction.
• Usage fields are stored only when supplied/derived with provenance.
• OpenAPI/AsyncAPI, docs, retention rules, and tests are updated.
• A changeset is added.
• bun run check passes.

Out of scope

• Enumerating all Hermes sessions.
• Reading Telegram chat history.
• Guaranteed remote cancellation without a documented upstream contract.