Actions do Agent-Native rodam em prefixo próprio e exigem requiresAuth false para telemetria pública

[!NOTE] Resumo Executivo (DEV-2026-132): Tentativas de liberar rotas públicas de actions pelo caminho convencional da API resultavam em erro 401 silencioso no frontend. Descobrimos que o framework despacha sob o prefixo interno /_agent-native/actions e exige flag declarativa na definição da action para contornar o guard.


🚨 O Desafio Técnico / Contexto

O indicador de status da telefonia e o seletor de temas no cabeçalho apareciam desconectados para usuários sem sessão logada. As requisições de telemetria recebiam HTTP 401 do middleware runAuthGuard, mesmo com tentativas de liberação em /api/actions/* no arquivo de rotas.


💡 Principais Lições Aprendidas & Descobertas

  • 💡 Actions do @agent-native/core são registradas sob o prefixo /_agent-native/actions e não em /api/actions/.
  • 💡 Para expor uma action sem exigir cookie de sessão, deve-se declarar requiresAuth: false e http: { method: ‘GET’ } no defineAction.
  • 💡 O registerAuthPublicPaths deve incluir o caminho exato do framework para que o middleware H3 libere a rota sem interceptação.

🛠️ Especificação Técnica & Código-Chave

export default defineAction({
  description: "Telemetria de saúde da malha",
  requiresAuth: false,
  http: { method: "GET" },
  readOnly: true,
  schema: z.object({}),
  run: async () => ({ online: true }),
});

📈 Impacto no Ecossistema & Valor Prático

Telemetria de infraestrutura e temas visuais passaram a responder 200 OK imediatamente para qualquer visitante, eliminando telas falsas de desconexão.

  • Projetos Relacionados: triade-artesdosul, ecosul
  • Registro de Origem: _data/daily.dev-21.yml

Publicado originalmente como parte do Diário de Desenvolvimento 2026 do ecossistema Artes do Sul & Araguaci.