@zihin/agent-client 0.1.0 → 0.2.0

package/README.md

@@ -75,14 +75,49 @@ const exec = await zihin.getExecution({ triggerId, executionId });
 
 > O modo `sync` do trigger (`mode: 'sync'`) responde 200 + JSON na hora (`dispatchResult.agentResponse`).
 
+### Payload estruturado (não só texto)
+
+O caminho direto (`invokeAgent`) só aceita **texto** — o endpoint `/stream` do BE não tem campo de
+payload estruturado. Para disparar um agente a partir de um JSON rico, use triggers: o payload vai
+inteiro no `dispatchAgent` e o `queryExtraction` define como ele vira a mensagem do agente.
+
+```ts
+// template: compõe a mensagem a partir de campos aninhados do payload
+await zihin.findOrCreateTrigger({
+  agentId,
+  name: 'Pedidos',
+  mode: 'sync',
+  queryExtraction: { mode: 'template', template: 'Pedido {{payload.order.id}}: {{payload.order.note}}' },
+});
+
+// field (default): um campo top-level do payload
+// queryExtraction: { mode: 'field', field: 'texto' }
+// full_body: fallback do BE → payload.message || payload.query || JSON.stringify(payload)
+// queryExtraction: { mode: 'full_body' }
+
+await zihin.dispatchAgent({ triggerId, payload: { order: { id: 42, note: 'urgente' }, cliente: {...} } });
+```
+
+⚠️ O que chega ao agente é **a string extraída**, não o payload inteiro: com `field`/`template`, os
+campos que você não referenciou ficam de fora. Para levar tudo, use `full_body` — e note que ele
+só serializa o payload completo **se não houver** um campo `message`/`query` no topo (nesse caso o
+BE usa esse campo). Precisa de campos extras como contexto estruturado? Isso é `context_mapping`
+no trigger, ainda não exposto pelo núcleo — configure direto no BE.
+
 ### Ciclo de vida do trigger
 
 ```ts
 await zihin.listTriggers({ agentId });        // lista (filtros: agentId/triggerType/enabledOnly)
 await zihin.getTrigger({ triggerId });        // detalhe (inclui webhookUrl)
+await zihin.updateTrigger({ triggerId, enabled: false });          // PATCH parcial
+await zihin.updateTrigger({ triggerId, queryExtraction: { mode: 'full_body' } }); // GET+merge+PATCH
 await zihin.deleteTrigger({ triggerId });     // remove (requer key admin/owner; editor → 403)
 ```
 
+> `updateTrigger` faz GET + merge + PATCH quando você altera config (o BE substitui
+> `trigger_config` inteiro). Há uma janela entre o GET e o PATCH em que uma escrita concorrente
+> pode ser sobrescrita.
+
 ## Dropdown de agentes
 
 ```ts
@@ -93,8 +128,8 @@ const agents = await zihin.listAgents(); // GET /api/v2/agents
 ## Permissões da API key
 
 - `invokeAgent` / `streamAgent` — qualquer role.
-- `createTrigger` / `getExecution` — exigem key **admin** ou **editor** (default é admin). Keys
-  `member` recebem `ZihinAgentError` com `kind: 'auth'`.
+- `createTrigger` / `updateTrigger` / `getExecution` — exigem key **admin** ou **editor** (default é
+  admin). Keys `member` recebem `ZihinAgentError` com `kind: 'auth'`.
 
 ## Erros
 
@@ -123,11 +158,17 @@ preservados. Cancele com `AbortSignal` via `params.signal`.
 ### Observabilidade e portabilidade
 
 - **Hooks** (opt-in, sem `console`): `onRetry(info)` (a cada retentativa, com `endpoint`/`attempt`/
-  `delayMs`/`reason`/`status`) e `onError(err)`.
+  `delayMs`/`reason`/`status`) e `onError(err)` — chamado quando uma operação falha em definitivo
+  (inclusive `aborted`; filtre por `err.kind`). Exceção lançada dentro do hook é engolida e nunca
+  mascara o erro original.
 - **`fetch` injetável** — `fetch?` na config; por padrão usa `globalThis.fetch` (Node ≥18). Um
   preflight dá erro `config` claro se não houver fetch.
 - **Portável** — sem `Buffer`; `node:crypto` só é carregado se você usar `signRequest`. Roda em Node;
-  para edge/serverless, injete `fetch` se necessário.
+  para edge/serverless, injete `fetch` se necessário. O pacote publica **CJS e ESM** (`exports` map):
+  `require()` e `import` funcionam. Duas ressalvas: no build ESM, `signRequest` precisa de Node
+  >=20.16 (`process.getBuiltinModule`) e sem isso lança `ZihinAgentError` com `kind: 'config'`; e
+  carregar **as duas formas no mesmo processo** cria duas classes `ZihinAgentError` distintas, o que
+  faz `instanceof` falhar — padronize `require` **ou** `import` para o núcleo na sua árvore de deps.
 
 ```ts
 const zihin = createClient({
@@ -140,8 +181,14 @@ const zihin = createClient({
 });
 ```
 
-> SSRF: a validação de base/callback URL é por nome de host. Com `allowCustomBaseUrl: true` um host
-> que resolva para IP privado (DNS rebinding) passa — mantenha o whitelist em ambiente sensível.
+> SSRF: a validação de base/callback/attachment URL é por **nome de host** — cobre IPv4 privado
+> (inclusive octal/hex, normalizados pela URL), IPv6 privado **por faixa de bits** (`fc00::/7`,
+> `fe80::/10`, `fec0::/10`, loopback e IPv4 embutido `::ffff:`/`::`), FQDN com ponto final e os
+> hosts de metadata de nuvem.
+>
+> **Limite importante:** é validação por nome, não por IP resolvido. Com `allowCustomBaseUrl: true`,
+> um host que **resolva** para IP privado (DNS rebinding) passa. Isto não substitui bloqueio de
+> egresso na borda de rede — mantenha o whitelist (default) em ambiente sensível.
 
 ## Segurança
 

package/dist/index.d.mts

@@ -0,0 +1,510 @@
+/**
+ * Erros do @zihin/agent-client — sanitizados (sem vazar key/Bearer/stack), mas COMPLETOS:
+ * carregam endpoint, nº de tentativas e request_id do BE para depuração em produção externa.
+ *
+ * @module errors
+ */
+type ZihinErrorKind = 'config' | 'auth' | 'not_found' | 'rate_limit' | 'timeout' | 'aborted' | 'server' | 'network' | 'protocol' | 'unknown';
+/** Contexto opcional anexado a um erro para correlação/depuração. */
+interface ErrorMeta {
+    /** Ex.: "POST llm.zihin.ai/api/v2/agents/abc/stream". */
+    endpoint?: string;
+    /** Número de tentativas feitas antes de falhar. */
+    attempts?: number;
+}
+interface ZihinErrorOptions extends ErrorMeta {
+    status?: number;
+    code?: string;
+    retryable?: boolean;
+    /** request_id do BE (NÃO é segredo) — handle para o suporte correlacionar nos logs. */
+    requestId?: string;
+}
+declare class ZihinAgentError extends Error {
+    readonly kind: ZihinErrorKind;
+    readonly status?: number;
+    readonly code?: string;
+    readonly retryable: boolean;
+    readonly requestId?: string;
+    readonly attempts?: number;
+    readonly endpoint?: string;
+    constructor(kind: ZihinErrorKind, message: string, opts?: ZihinErrorOptions);
+}
+
+/**
+ * Tipos do contrato externo Zihin — fonte de verdade verificada contra o BE
+ * (zihin-agent-builder/server-llm, 2026-06-28).
+ *
+ * @module types
+ */
+
+interface ZihinClientConfig {
+    /** API key `zhn_live_*` (tenant embutido). Para triggers/telemetria use role admin/editor. */
+    apiKey: string;
+    /** Base URL. Default: https://llm.zihin.ai */
+    baseUrl?: string;
+    /** Timeout por request (ms). Default: 120000 (= limite do /stream no BE). */
+    timeoutMs?: number;
+    /** Máximo de retentativas em 5xx/429/erro de rede. Default: 2. */
+    maxRetries?: number;
+    /** Permite base URL fora da whitelist Zihin (default false → SSRF guard). */
+    allowCustomBaseUrl?: boolean;
+    /** Permite http:// (apenas dev/local). Default false. */
+    allowHttp?: boolean;
+    /** Teto de bytes por evento/linha SSE (anti-DoS de memória). Default: 1MB. */
+    maxStreamEventBytes?: number;
+    /** Teto de bytes do stream inteiro (anti-DoS de memória). Default: 64MB. */
+    maxStreamTotalBytes?: number;
+    /**
+     * Implementação de `fetch` a usar. Default: `globalThis.fetch`. Injete em runtimes onde o
+     * fetch não é global (Node <18 com polyfill, testes, proxies).
+     */
+    fetch?: typeof fetch;
+    /**
+     * Observabilidade (opt-in, sem console): chamado antes de cada retentativa.
+     * Para logar backoff/timeouts/falhas transitórias em produção externa.
+     */
+    onRetry?: (info: RetryInfo) => void;
+    /**
+     * Observabilidade: chamado quando uma operação do cliente falha em definitivo (após retries),
+     * inclusive `aborted` — filtre por `error.kind` se quiser ignorar cancelamentos. Uma exceção
+     * lançada dentro do callback é engolida (não mascara o erro original). Não cobre erros de
+     * configuração lançados pelo construtor (o cliente ainda não existe).
+     */
+    onError?: (error: ZihinAgentError) => void;
+}
+interface RetryInfo {
+    /** "POST llm.zihin.ai/api/v2/agents/abc/stream". */
+    endpoint: string;
+    /** Número da tentativa que acabou de falhar (1 = primeira). */
+    attempt: number;
+    /** Atraso até a próxima tentativa, em ms. */
+    delayMs: number;
+    /** Motivo do retry. */
+    reason: 'status' | 'network';
+    /** Status HTTP, quando `reason === 'status'`. */
+    status?: number;
+}
+type AttachmentType = 'image' | 'audio' | 'document';
+interface Attachment {
+    url: string;
+    type: AttachmentType;
+}
+interface InvokeOptions {
+    temperature?: number;
+    maxTokens?: number;
+    /** Timeout específico desta chamada (ms); sobrepõe o do cliente. */
+    timeoutMs?: number;
+    /** Just-in-time tool loading (Sprint 33). */
+    jitMode?: boolean;
+}
+interface InvokeAgentParams {
+    /** UUID do agente (path :agent_id). */
+    agentId: string;
+    /** Mensagem ao agente. `message` OU `attachments` é obrigatório. */
+    message?: string;
+    /** Anexos multimodais. `message` OU `attachments` é obrigatório. */
+    attachments?: Attachment[];
+    /** Continuidade de conversa (Supabase agent_sessions). */
+    sessionId?: string;
+    options?: InvokeOptions;
+    metadata?: {
+        traceId?: string;
+        correlationId?: string;
+        [k: string]: unknown;
+    };
+    /** Cancelamento externo. */
+    signal?: AbortSignal;
+    /**
+     * Retém todos os eventos SSE brutos em `AgentResult.raw`. Default: false (economiza memória
+     * em runs longos). `streamAgent` sempre entrega os chunks ao vivo, independente disto.
+     */
+    includeRaw?: boolean;
+}
+interface Usage {
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+    costUsd?: number;
+}
+interface Source {
+    title?: string;
+    url?: string;
+    [k: string]: unknown;
+}
+/**
+ * Resultado final de `invokeAgent`: consolida o evento SSE `response`
+ * (content/sources/session_id/blocks) com o evento `metrics` (usage/model).
+ */
+interface AgentResult {
+    content: string;
+    sessionId?: string;
+    model?: string;
+    usage?: Usage;
+    sources?: Source[];
+    /** Cards/blocos estruturados (SPEC B). */
+    blocks?: Array<{
+        type: string;
+        [k: string]: unknown;
+    }>;
+    iterations?: number;
+    executionTimeMs?: number;
+    /** Eventos SSE brutos coletados (para depuração / casos avançados). */
+    raw: AgentStreamChunk[];
+}
+/**
+ * Chunk normalizado emitido por `streamAgent`. Mapeia os tipos de evento SSE do BE:
+ * metadata, status, attachments, phase, thinking, tool, action_proposed, token,
+ * warning, response, metrics.
+ */
+type AgentStreamChunk = {
+    type: 'metadata';
+    requestId?: string;
+    agentId?: string;
+    sessionId?: string;
+    data: unknown;
+} | {
+    type: 'status';
+    phase?: string;
+    data: unknown;
+} | {
+    type: 'attachments';
+    data: unknown;
+} | {
+    type: 'phase';
+    phase?: string;
+    data: unknown;
+} | {
+    type: 'thinking';
+    thought?: string;
+    data: unknown;
+} | {
+    type: 'tool';
+    tool?: string;
+    callId?: string;
+    success?: boolean;
+    data: unknown;
+} | {
+    type: 'action_proposed';
+    data: unknown;
+} | {
+    type: 'token';
+    content: string;
+    data: unknown;
+} | {
+    type: 'warning';
+    message?: string;
+    data: unknown;
+} | {
+    type: 'response';
+    content: string;
+    sessionId?: string;
+    sources?: Source[];
+    blocks?: Array<{
+        type: string;
+        [k: string]: unknown;
+    }>;
+    data: unknown;
+} | {
+    type: 'metrics';
+    usage?: Usage;
+    model?: string;
+    iterations?: number;
+    executionTimeMs?: number;
+    data: unknown;
+} | {
+    type: 'unknown';
+    event: string;
+    data: unknown;
+};
+type TriggerMode = 'sync' | 'async';
+/**
+ * Como o BE extrai a mensagem do agente a partir do payload de disparo (webhook):
+ *  - `field`: um campo top-level do payload (`payload[field]`).
+ *  - `template`: compõe a mensagem com placeholders `{{payload.caminho.aninhado}}` —
+ *    é o modo para payloads estruturados ricos.
+ *  - `full_body`: fallback do BE — usa `payload.message || payload.query ||
+ *    JSON.stringify(payload)` (o payload inteiro serializado vira a mensagem).
+ * (Verificado no BE em 2026-08-03: `jmespath` citado em docs antigas NÃO é implementado.)
+ */
+type QueryExtraction = {
+    mode: 'field';
+    field: string;
+} | {
+    mode: 'template';
+    template: string;
+} | {
+    mode: 'full_body';
+};
+interface CreateTriggerParams {
+    agentId: string;
+    /** Nome legível do trigger. */
+    name: string;
+    /** `async` → 202 + callback; `sync` → 200 + JSON na hora. Default: async. */
+    mode?: TriggerMode;
+    /** URL que o BE chama com o resultado (obrigatório no modo async). */
+    callbackUrl?: string;
+    /** Método HTTP do callback. Default: POST. */
+    callbackMethod?: 'POST' | 'PUT';
+    /** Campo do payload de disparo de onde sai a mensagem do agente. Default: "message". */
+    queryField?: string;
+    /**
+     * Extração da mensagem a partir do payload (field/template/full_body). Tem precedência
+     * sobre `queryField` (que equivale a `{ mode: 'field', field: queryField }`).
+     */
+    queryExtraction?: QueryExtraction;
+    /** Auth de disparo aceita. Default: api_key. */
+    dispatchAuth?: 'api_key' | 'signature' | 'none';
+    signal?: AbortSignal;
+}
+/**
+ * Atualização parcial de um trigger (PATCH). Campos de config (queryExtraction/callback/mode)
+ * exigem um GET prévio + merge, porque o PATCH do BE SUBSTITUI `trigger_config` por inteiro.
+ */
+interface UpdateTriggerParams {
+    triggerId: string;
+    name?: string;
+    description?: string;
+    enabled?: boolean;
+    /** Troca a extração de query preservando o restante do trigger_config. */
+    queryExtraction?: QueryExtraction;
+    /** Troca a URL do callback (modo async). */
+    callbackUrl?: string;
+    /** Troca o método do callback. */
+    callbackMethod?: 'POST' | 'PUT';
+    /** Troca o modo de execução (sync/async). */
+    mode?: TriggerMode;
+    signal?: AbortSignal;
+}
+interface TriggerRef {
+    triggerId: string;
+    /** URL completa de disparo: POST {webhookUrl}. */
+    webhookUrl: string;
+}
+/** Resultado de findOrCreateTrigger: o ref + se foi recém-criado ou reaproveitado. */
+interface FindOrCreateResult extends TriggerRef {
+    created: boolean;
+}
+/** Trigger como listado/obtido do BE. */
+interface TriggerInfo {
+    id: string;
+    agentId?: string;
+    name?: string;
+    description?: string;
+    triggerType?: string;
+    enabled?: boolean;
+    triggerCount?: number;
+    lastError?: string;
+    /** Presente para triggers do tipo webhook. */
+    webhookUrl?: string;
+}
+interface ListTriggersParams {
+    /** Filtra por agente. */
+    agentId?: string;
+    /** Filtra por tipo (webhook | db_event | email | schedule). */
+    triggerType?: string;
+    /** Apenas habilitados. */
+    enabledOnly?: boolean;
+    signal?: AbortSignal;
+}
+interface GetTriggerParams {
+    triggerId: string;
+    signal?: AbortSignal;
+}
+interface DeleteTriggerParams {
+    triggerId: string;
+    signal?: AbortSignal;
+}
+interface DispatchAgentParams {
+    triggerId: string;
+    /** Payload entregue ao trigger (a mensagem sai do `queryField` configurado). */
+    payload: Record<string, unknown>;
+    signal?: AbortSignal;
+}
+interface DispatchResult {
+    /** true quando o BE retorna 202 (async) ou 200 (sync). */
+    accepted: boolean;
+    triggerId?: string;
+    executionId?: string;
+    /** Presente quando o trigger é `sync`: resposta imediata do agente. */
+    agentResponse?: string;
+    usage?: Usage;
+    raw: unknown;
+}
+interface ExecutionStatus {
+    executionId: string;
+    status: string;
+    startedAt?: string;
+    finishedAt?: string;
+    executionTimeMs?: number;
+    usage?: Usage;
+    result?: string;
+    raw: unknown;
+}
+interface GetExecutionParams {
+    triggerId: string;
+    executionId: string;
+    signal?: AbortSignal;
+}
+
+/**
+ * Listagem de agentes do tenant (GET /api/v2/agents). Alimenta o dropdown do nó n8n (#17)
+ * e o select de `agentId` no Paperclip (#20). Aceita key `zhn_live_*` (agents:read em todos os roles).
+ *
+ * @module agents
+ */
+
+interface AgentSummary {
+    id: string;
+    name?: string;
+    commercialName?: string;
+    bio?: string;
+    type?: string;
+    status?: string;
+    tags?: string[];
+    toolsCount?: number;
+}
+
+/**
+ * ZihinAgentClient — fachada do núcleo. Carrega a config uma vez (auth, baseUrl, timeout,
+ * retries) e expõe os dois caminhos do padrão híbrido:
+ *   • Direto:    invokeAgent / streamAgent  (POST /stream, SSE bufferizado)
+ *   • Triggers:  createTrigger / dispatchAgent / getExecution  (async + callback)
+ *   • Auxiliar:  listAgents  (dropdown de agentes)
+ *
+ * @module client
+ */
+
+declare class ZihinAgentClient {
+    private readonly cfg;
+    constructor(config: ZihinClientConfig);
+    /** Base URL efetiva (após validação SSRF). */
+    get baseUrl(): string;
+    /** Notifica `config.onError` (falha definitiva); o callback nunca derruba o fluxo. */
+    private report;
+    private guard;
+    /** Invoca o agente e retorna o resultado final consolidado (response + metrics). */
+    invokeAgent(params: InvokeAgentParams): Promise<AgentResult>;
+    /** Emite deltas ao vivo do agente (async iterator). */
+    streamAgent(params: InvokeAgentParams): AsyncGenerator<AgentStreamChunk>;
+    /** Provisiona (1x) um trigger de webhook ligado a um agente. */
+    createTrigger(params: CreateTriggerParams): Promise<TriggerRef>;
+    /** Reaproveita (por agente+nome) ou cria um trigger — evita duplicação. */
+    findOrCreateTrigger(params: CreateTriggerParams): Promise<FindOrCreateResult>;
+    /** Lista os triggers do tenant (filtros opcionais). */
+    listTriggers(params?: ListTriggersParams): Promise<TriggerInfo[]>;
+    /** Obtém um trigger pelo id (inclui webhookUrl). */
+    getTrigger(params: GetTriggerParams): Promise<TriggerInfo>;
+    /** Atualiza um trigger (name/description/enabled/extração/callback) via PATCH. */
+    updateTrigger(params: UpdateTriggerParams): Promise<TriggerInfo>;
+    /** Remove um trigger (requer key admin/owner). */
+    deleteTrigger(params: DeleteTriggerParams): Promise<{
+        deleted: boolean;
+    }>;
+    /** Dispara um trigger: 202 (async) ou JSON imediato (sync). */
+    dispatchAgent(params: DispatchAgentParams): Promise<DispatchResult>;
+    /** Consulta o resultado de uma execução disparada por trigger (polling). */
+    getExecution(params: GetExecutionParams): Promise<ExecutionStatus>;
+    /** Lista os agentes do tenant (dropdown). */
+    listAgents(opts?: {
+        signal?: AbortSignal;
+    }): Promise<AgentSummary[]>;
+}
+/** Açúcar: cria um cliente a partir da config. */
+declare function createClient(config: ZihinClientConfig): ZihinAgentClient;
+
+/**
+ * Security utilities — portado de n8n-nodes-zihin/src/utils/security.ts (zero-dep).
+ * SSRF prevention, payload limits, error sanitization, API-key format.
+ * (A assinatura HMAC vive em `signing.ts` — precisa de ZihinAgentError e criaria ciclo aqui.)
+ *
+ * Núcleo compartilhado: os shells (n8n, Paperclip) reusam estas primitivas via @zihin/agent-client.
+ *
+ * @module security
+ */
+interface UrlValidationResult {
+    valid: boolean;
+    error?: string;
+    sanitizedUrl?: string;
+}
+interface UrlValidationOptions {
+    allowCustomDomains?: boolean;
+    allowHttp?: boolean;
+    allowLocalhost?: boolean;
+}
+/**
+ * Validates a base URL for SSRF prevention.
+ *
+ * NOTA (S4): a checagem é por NOME de host, não pelo IP resolvido. Com `allowCustomDomains: true`,
+ * um host que resolve para IP privado (DNS rebinding) passa. Em ambiente sensível, mantenha o
+ * whitelist (default) ou faça a resolução/checagem de IP na borda de rede.
+ *
+ * @param url - The URL to validate
+ * @param options - Validation options
+ * @returns Validation result with sanitized URL or error
+ */
+declare function validateBaseUrl(url: string, options?: UrlValidationOptions): UrlValidationResult;
+interface PayloadLimits {
+    maxPromptBytes: number;
+    maxMessageCount: number;
+    maxSingleMessageBytes: number;
+    maxTotalPayloadBytes: number;
+}
+declare const DEFAULT_LIMITS: PayloadLimits;
+interface PayloadValidationResult {
+    valid: boolean;
+    error?: string;
+    truncated?: boolean;
+    details?: {
+        promptBytes?: number;
+        messageCount?: number;
+        largestMessageBytes?: number;
+        totalBytes?: number;
+    };
+}
+/**
+ * Validates a single message/prompt size against configured limits.
+ */
+declare function validatePromptSize(prompt: string, limits?: Partial<PayloadLimits>): PayloadValidationResult;
+interface SanitizedError {
+    message: string;
+    code?: string;
+    retryable: boolean;
+    retryAfter?: number;
+}
+/**
+ * Sanitizes API errors to prevent information leakage (keys, request IDs, stack traces).
+ */
+declare function sanitizeApiError(error: unknown): SanitizedError;
+interface ApiKeyValidationResult {
+    valid: boolean;
+    error?: string;
+    environment?: 'live' | 'test' | 'dev';
+}
+/**
+ * Validates API key format (zhn_live_* | zhn_test_* | zhn_dev_*).
+ */
+declare function validateApiKeyFormat(apiKey: string): ApiKeyValidationResult;
+
+/**
+ * Assinatura HMAC opcional de payloads (auth `signature` dos triggers).
+ *
+ * Vive fora de `security.ts` de propósito: precisa de `ZihinAgentError` (errors.ts), e errors.ts
+ * já importa security.ts — juntar os dois criaria um ciclo de import.
+ *
+ * @module signing
+ */
+interface SignedRequestHeaders {
+    'X-Zihin-Signature': string;
+    'X-Zihin-Timestamp': string;
+    'X-Zihin-Nonce': string;
+}
+/**
+ * Assina um payload com HMAC-SHA256 (timestamp + nonce + payload).
+ *
+ * ⚠️ No build ESM depende de `process.getBuiltinModule` (Node >=20.16); em Node mais antigo via
+ * `import` lança `ZihinAgentError` com `kind: 'config'`. O build CJS funciona em qualquer Node
+ * >=18. (Todo o resto do núcleo é Web-API puro e roda nos dois.)
+ */
+declare function signRequest(payload: string, secretKey: string, timestamp?: number): SignedRequestHeaders;
+
+export { type AgentResult, type AgentStreamChunk, type AgentSummary, type Attachment, type AttachmentType, type CreateTriggerParams, DEFAULT_LIMITS, type DeleteTriggerParams, type DispatchAgentParams, type DispatchResult, type ExecutionStatus, type FindOrCreateResult, type GetExecutionParams, type GetTriggerParams, type InvokeAgentParams, type InvokeOptions, type ListTriggersParams, type QueryExtraction, type RetryInfo, type SignedRequestHeaders, type Source, type TriggerInfo, type TriggerMode, type TriggerRef, type UpdateTriggerParams, type Usage, ZihinAgentClient, ZihinAgentError, type ZihinClientConfig, type ZihinErrorKind, createClient, sanitizeApiError, signRequest, validateApiKeyFormat, validateBaseUrl, validatePromptSize };