Files
canina/docs/hermes-runtime-integration.md
T

8.2 KiB

Orchestration v4: Hermes runtime seam (review-only)

Installed evidence / compatibility

Read-only inspection of canina-hermes source at /opt/hermes and Docker metadata:

  • Running image ID: sha256:373ddd5e6649f525b17993e1c885cdf1352127f8e98fd329140a73237125e52f.
  • Registry digest (pinned template): nousresearch/hermes-agent@sha256:9774f4f39a9bb8c2f68ce728ed5e99ddbad282163be56764afacf88ed952b784.
  • Current command is gateway run, not serve. Loopback 9119 connection refused. This implementation does not claim a live dashboard integration or start one.
  • Existing /opt/data mount is external volume canina-hermes_canina_hermes_data; preserve it. Read-only cron JSON count: 17 jobs, 0 enabled. Paused state is enabled:false, not a paused boolean. No cron/runtime/config mutation was made.
  • Existing untracked /opt/services/ai/canina-hermes/compose.yml remains untouched.

Sources inspected: hermes_cli/web_routers/{status,profiles,models,sessions,analytics,cron,chat_ws}.py, cron scoping helpers, cron/jobs.py, hermes_cli/inventory.py, hermes_cli/dashboard_auth/{routes,middleware}.py, hermes_cli/web_server{,_chat}.py, tui_gateway/ws.py.

Supported allowlist

Service method Installed upstream contract Public projection
health GET /api/health ok/version/commit/auth_required
status GET /api/status?profile= version/gateway_running/gateway_state/overall/active_agents
profiles GET /api/profiles -> {profiles:[]} name/is_default/gateway_running, filtered by backend scope
modelInfo GET /api/model/info?profile= model/provider/effective_context_length
modelOptions GET /api/model/options?profile= provider slug/name + model ID strings
usage GET /api/analytics/usage?profile=&days= period_days and four numeric totals
sessions GET /api/sessions?profile=&limit=&offset=&full=false&order=recent ID/profile/source/is_active, total
crons GET /api/cron/jobs?profile= -> array ID/profile/enabled
pauseCron POST /api/cron/jobs/{id}/pause?profile= ID/profile/enabled
resumeCron POST /api/cron/jobs/{id}/resume?profile= implemented adapter; disabled in registered service

No generic route/HTTP/RPC proxy. No model setter, config, secrets, PTY, trigger, deletion, raw transcript or raw logs. Status is not fabricated if unavailable. Numeric nulls/malformed/missing required fields produce CONTRACT (some empty analytics stores may therefore be unavailable). Unknown upstream fields are dropped, never forwarded; this is intentional forward-compatible redaction, not raw JSON passthrough. Scope mismatch is forbidden. Arrays cap at 1000, upstream bytes at 256 KiB, in-flight requests at 4, whole request/token budget at 5 seconds, no retries, redirects forbidden. The production fetch honors AbortSignal. Error messages never include upstream response/URL/token/exception. Do not log request headers or config objects.

Upstream GET /api/sessions can auto-archive internally; we inspected source only and did not call it against production. Some model inventory endpoints warm caches/probe providers. Classify these as managed reads, not guaranteed filesystem-pure operations.

Authentication and WS discovery

  • Non-loopback dashboard binds engage the provider-verified auth gate. REST supports provider-verified Bearer session tokens. Legacy loopback accepts session header/Bearer; a Canina JWT or API_SERVER_KEY is not interchangeable.
  • POST /api/auth/ws-ticket needs verified request.state.session; response {ticket,ttl_seconds} is single-use / 30 seconds. Do not mint tickets for a browser or copy credentials into browser URLs.
  • Installed WS: /api/ws, /api/console, /api/events, /api/pub, /api/pty; no assumed /api/chat/ws.
  • /api/ws uses newline-delimited JSON-RPC and gateway.ready; same dispatcher as TUI, broad privilege. Gated admission supports a ticket, including subprotocols hermes-gateway-v1 and hermes-gateway-ticket.<ticket>; legacy process token is rejected in gated mode. Internal process credentials must never be extracted.
  • We deliberately do not bridge a powerful socket without a verified session/run ownership and event allowlist contract. chat/control return UNSUPPORTED after policy; event dispatch returns FORBIDDEN even with policy approval. No WS dependency, background connection, reconnect, or ticket endpoint is exposed.

Wiring (owner integration step, no app.module.ts changes here)

Import HermesManagementModule.register(config, authorizer) in the owning backend module, then inject HermesIntegrationService, never the adapter into browser controllers. Registration exports the service only and defaults to deny-all policy. Example configuration:

HermesManagementModule.register({
  origin: 'http://canina-hermes:9119',
  token: () => secretStore.read('hermes_dashboard_access_token'),
}, backendRuntimeAuthorizer)

Supply a provider-verified, short-lived Hermes token through backend secret storage (template references /run/secrets/hermes_dashboard_access_token only). Provision/refresh is an operator responsibility; this change neither extracts existing runtime secrets nor invents a login flow. No token in database/UI/env templates.

Controllers must verify Canina admin JWT, resolve subject/profile scopes from trusted backend data (not request DTO), enforce permission and rate limit/audit, translate HermesError codes to safe API errors (AUTH_REQUIRED/UNAVAILABLE -> 503, FORBIDDEN ->403, LIMIT ->429, CONTRACT/UNSUPPORTED ->502/501). Never forward upstream errors. RuntimePrincipal is an internal context, not a user input DTO. Authorizer must independently verify subject/action/profile. Missing/throwing authorizer denies. Registered module hard-disables resume; enabling requires an explicit reviewed code change. Resume can immediately make overdue recurring jobs due: never test it on production.

Disabled event dispatch design

No listener, cron, poller, outbox consumer or webhook is registered. A future dispatcher must use backend-verified event identity, durable outbox and idempotency, server-resolved department/profile/run ownership, permission per action, payload minimization/redaction, budget and approval policy. Then use a tested narrow execution transport; never map arbitrary event text to TUI RPC or /api/pub. Unknown event/schema/principal/approval/ownership -> reject with no IO. Do not enable before isolated acceptance proves interruption, stream bounds and safe tool-output projection.

Manifests and verification

infra/hermes-runtime/compose.template.yml is not a deployable replacement yet: manual-only profile, no automatic restart/public ports/socket/credentials, preserves external data volume, dedicated external backend network. It intentionally retains gateway run; dashboard/auth/network topology and gateway egress need an approved migration design. Do not run alongside current service sharing the same writable state. Never down -v.

.gitea/workflows/hermes-runtime-contract.yml is manual contract review only, no deploy job, SSH, runtime secret or event dispatch. Existing deploy workflow untouched. Compose parsed with docker compose ... config --quiet; no containers deployed.

Tests: cd backend && npm test -- --runInBand hermes-management (14 assertions across 4 suites); strict isolated typecheck/build npx tsc -p src/hermes-management/tsconfig.contract.json [--noEmit]; full backend npm run build after isolated npx prisma generate. All passed. Local HTTP transport is exercised on ephemeral loopback, not production. TDD failures were observed for missing adapter, inventory methods, integration service, module and concurrency limit before implementations. No live authenticated dashboard or WS execution was exercised. Host has no Node; disposable node:22-bookworm runners used. Initial shared dependency resolution and offline Prisma binary download failed; fresh worktree dependencies and isolated network-enabled Prisma generation resolved them, without DB connection/migration.

Final verification: full backend Jest regression 93 suites / 771 tests passed; scoped ESLint and strict typecheck passed, full tsc -b build passed. Existing SSL/payment negative tests print expected error logs despite passing. No deploy or production action performed.