feat(hermes): ADR-018 Hermes Agent (Nous Research) integration Phase 1

[UNIFY-MC]

Resumo

• ADR-018 DRAFT — Decisão arquitectural sobre integração do Hermes Agent (Nous Research) como executor externo de recipes CookAI (5002c41).
• Migration Phase 1A — system.api_keys + iam.permission_groups (hermes_executor) + 8 permission_sections + 8 permission_grants whitelist + RPC iam.api_key_can(api_key_id, section, action) (dd100b5).
• Mirror fix migration — 202605240101 sincroniza DB → git (search_path da RPC inclui extensions para evitar regressão futura) (02aa424).
• Edge Function hermes-invoke-recipe — entry point HTTP que valida X-API-Key, resolve api_key_id, chama iam.api_key_can() e despacha para a recipe pedida (a8aa8ab).

Estado actual em produção

Tudo aplicado em V1 Core Hub (hkmvszkpxjbxmnixzqbl) em modo seguro:

Componente	Estado	Notas
system.api_keys (Hermes row)	active = false	Placeholder, sem hash real — bloqueia execução
iam.permission_groups (hermes_executor)	Activo	Whitelist de 8 sections (read-only sobre recipes/skills/missions + execute recipe)
RPC iam.api_key_can()	Security definer	search_path = iam, system, public, extensions
Edge Function hermes-invoke-recipe	v1 ACTIVE (cedcf76e-eb49-4330-a01a-9508617b4c80)	verify_jwt = false (auth via X-API-Key)

Como active = false e não há hash real, qualquer chamada actual à EF devolve 401/403 — não há risco de execução não autorizada.

Pendente para @mario

1. Gerar API key real localmente:

   openssl rand -hex 32

2. Calcular hash (sha256) e fazer UPDATE em system.api_keys:

   UPDATE system.api_keys
   SET key_hash = '<sha256-da-key>',
       active = true,
       activated_at = now()
   WHERE name = 'hermes-agent-primary';

3. Setup do Hermes host (Nous Research) com a key plaintext em variável de ambiente segura (nunca commitar).
4. Smoke test end-to-end (ver checklist abaixo).

Test plan

Validation queries (SQL Editor V1 Core Hub)

• Confirmar row placeholder existe e está inactiva:

  SELECT id, name, active, key_hash IS NULL AS sem_hash
  FROM system.api_keys
  WHERE name = 'hermes-agent-primary';

• Confirmar grupo + 8 grants:

  SELECT pg.name, COUNT(*) AS grants
  FROM iam.permission_groups pg
  JOIN iam.permission_grants g ON g.group_id = pg.id
  WHERE pg.name = 'hermes_executor'
  GROUP BY pg.name;
  -- esperado: hermes_executor | 8

• Confirmar RPC tem search_path correcto:

  SELECT proname, proconfig
  FROM pg_proc
  WHERE proname = 'api_key_can'
    AND pronamespace = 'iam'::regnamespace;
  -- esperado: proconfig contém search_path=iam, system, public, extensions

Edge Function smoke test (após gerar key real)

• Chamar EF sem X-API-Key → 401.
• Chamar EF com X-API-Key inválido → 401.
• Chamar EF com key válido mas section/action fora da whitelist → 403.
• Chamar EF com key válido + section/action permitido (ex: cookai.recipes / read) → 200.
• Verificar audit trail em iam.activity_logs (ou equivalente) após chamada bem-sucedida.

Gate de merge

• Vercel Preview build OK (sem impacto esperado — apenas docs/EF/migrations, sem apps/).
• Validation queries acima retornam o esperado.
• Mário valida ADR-018 (DRAFT → ACCEPTED) ou pede alterações.

Refs

• ADR-018 — .claude/strategy/adrs/ADR-018-hermes-agent-integration.md (DRAFT)
• ADR-013 — IAM cross-vertical pattern reutilizado para hermes_executor
• Memory — project-hermes-agent-nous (contexto Nous Research)
• Migrations — supabase/migrations/202605240100_*.sql + 202605240101_*.sql (mirror fix)
• Edge Function — supabase/functions/hermes-invoke-recipe/

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
proptech-agentic-ops	Error		May 24, 2026 2:06am
proptech-v5-alpha	Error		May 24, 2026 2:06am