@zihin/piece-zihin

Piece do Activepieces para invocar agentes Zihin — sobre o núcleo @zihin/agent-client. Terceiro shell do padrão (ao lado de n8n e Paperclip).

O que faz

• Auth (Zihin): API Key (zhn_live_*, tenant embutido) + Base URL opcional + Allow custom base URL (opt-in explícito p/ domínio fora da whitelist) + Allow HTTP (dev). Strings de UI em inglês.
• Action Invoke Agent: dropdown de agentes (via listAgents()), Message, Session ID (continuidade), e Options (temperature / max tokens / timeout / include raw). Roda invokeAgent e devolve { content, sessionId, model, usage, sources }.

// pseudo: a action chama
const r = await createClient({ apiKey, baseUrl, allowHttp }).invokeAgent({ agentId, message, sessionId });

Por que depende do núcleo (e não bundla)

Ao contrário do nó verificado do n8n (que não pode ter dependência de runtime → bundla o núcleo), pieces do Activepieces são pacotes npm que podem declarar dependências. Então esta piece depende de @zihin/agent-client normalmente. Quando o núcleo for publicado, fixe ^0.1.0 no lugar do *.

Notas de integração

• Compila para CJS (tsc). Por isso usa named import do núcleo (import { createClient }) — o default import não resolve o núcleo CJS (__esModule sem default).
• logoUrl é um placeholder (https://www.zihin.ai/favicon.svg) — apontar para um logo hospedado.
• Para publicar/usar no Activepieces: alinhar @activepieces/pieces-framework à versão do alvo e empacotar conforme o fluxo deles (nx/pieces), ou instalar como community piece.

Dev

npm run build && npm test   # smoke test offline (mocka fetch) — 11/11 (inclui gate de whitelist)

Validado também headless contra o BE real: dropdown + caminho de erro (ECONNREFUSED → erro limpo com endpoint). Happy path: mesmo caminho /stream já provado no n8n e no Paperclip.