@zihin/agent-client 0.7.0 → 0.9.0

package/dist/core.d.ts

@@ -0,0 +1,1150 @@
+/**
+ * Primitivas de plataforma que o núcleo usa e que NÃO podem ser globais em todo runtime.
+ *
+ * Por que existe: o scanner de nó verificado do n8n (`@n8n/scan-community-package`) reprova
+ * qualquer referência a `setTimeout`/`clearTimeout`/`globalThis`/`process`/`console` no código
+ * publicado — e o núcleo vai EMBUTIDO no nó. Com o runtime injetável, o entry `./core` não carrega
+ * nenhuma dessas referências; o entry principal (`.`) injeta o runtime Node e segue idêntico.
+ */
+interface ZihinRuntime {
+    /**
+     * Resolve após `ms`. Rejeita (com qualquer erro) se `signal` abortar antes — o núcleo traduz.
+     * Precisa manter o processo vivo enquanto pendente (timer "ref", não `AbortSignal.timeout`):
+     * é o backoff entre tentativas e o relógio do deadline.
+     */
+    sleep(ms: number, signal?: AbortSignal): Promise<void>;
+    /** Aviso não fatal (descontinuação). Ausente = silencioso. */
+    warn?(code: string, message: string): void;
+}
+
+/**
+ * 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' | 'trial_expired' | 'no_subscription' | 'quota_exceeded' | 'not_found' | 'rate_limit' | 'timeout' | 'aborted' | 'server' | 'network' | 'protocol' | 'blocked' | '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;
+    /**
+     * execution_id do turno. Desde agosto/2026 o BE o entrega no sucesso E no erro (§1.2 do
+     * handoff) — é o handle que liga um erro daqui à execução no console/telemetria.
+     */
+    executionId?: string;
+    /** Sessão do turno — para o chamador retomar/inspecionar a conversa depois de um erro. */
+    sessionId?: string;
+    /**
+     * Só em `kind: 'timeout'` vindo do desfecho do turno (`done.timeout_clock`): qual relógio do BE
+     * encerrou o turno — `turn`, `first_signal`, `idle` ou `call`. Ausente num timeout de
+     * transporte/local, onde o turno pode nem ter terminado.
+     */
+    timeoutClock?: TimeoutClock;
+}
+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;
+    readonly executionId?: string;
+    readonly sessionId?: string;
+    readonly timeoutClock?: TimeoutClock;
+    constructor(kind: ZihinErrorKind, message: string, opts?: ZihinErrorOptions);
+}
+/**
+ * true quando o corpo é um bloqueio comercial. Consultado pelo transporte ANTES de retentar:
+ * o 429 de quota é indistinguível de rate limit pelo status, e só o corpo separa os dois.
+ */
+declare function isCommercialBlock(body: unknown): boolean;
+
+/**
+ * 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) — override explícito que vale para TODAS as operações. Deixe vazio
+     * para usar o default de cada uma (`OPERATION_TIMEOUT_MS`): stream 200s, dispatch de trigger
+     * 260s, GETs curtos 35s. Cada default fica acima do orçamento do BE para aquela rota, para que
+     * o desfecho do servidor chegue como erro estruturado em vez de abort do cliente — um valor
+     * único menor que isso reintroduz exatamente esse problema.
+     */
+    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;
+    /**
+     * Timers e avisos da plataforma. O entry principal (`@zihin/agent-client`) já injeta o runtime
+     * padrão (timers globais, `process.emitWarning`); só o entry `@zihin/agent-client/core` exige
+     * este campo — é o que hosts sem timers globais permitidos (nó verificado do n8n) usam.
+     */
+    runtime?: ZihinRuntime;
+    /**
+     * 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 {
+    /**
+     * @deprecated Sem efeito: o `/stream` usa a temperatura da configuração do agente
+     * (`llm_config.temperature`, no console ou via `update_agent`). O servidor ignora o campo e o
+     * reporta em `ignoredFields`. Será retirado do SDK na 1.0.
+     */
+    temperature?: number;
+    /**
+     * @deprecated Sem efeito: o teto de saída é a configuração do agente (`llm_config.max_tokens`,
+     * no console ou via `update_agent`). O servidor ignora o campo e o reporta em `ignoredFields`.
+     * Será retirado do SDK na 1.0.
+     */
+    maxTokens?: number;
+    /**
+     * Teto do TURNO desta chamada (ms); sobrepõe o do cliente. Vai ao BE como `options.timeout_ms`
+     * e o BE o honra (desde 30/09/2026, contrato de tempo §4), mas **só para encurtar**: o prazo
+     * efetivo é `min(prazo da plataforma, pedido)` — no `/stream` o canal chat dá 150s. Pedir mais
+     * não alonga. Um turno cortado por esse prazo sai `TIMEOUT` com `timeoutClock: 'turn'`.
+     *
+     * O relógio do turno no BE só começa DEPOIS da carga (config, tools, MCP frio). O deadline
+     * local soma `DEADLINE_GRACE_MS` a este valor para ainda receber o desfecho do servidor.
+     */
+    timeoutMs?: number;
+    /**
+     * @deprecated Recurso descontinuado no servidor (ago/2026): sem efeito, reportado em
+     * `ignoredFields`. Remova-o. Será retirado do SDK na 1.0.
+     */
+    jitMode?: boolean;
+}
+/**
+ * Blocos estruturados que a sua interface sabe renderizar (`capabilities.blocks`). Valor que o BE
+ * não conhece sai em `ignoredFields` como `capabilities.blocks.<v>` + `not_supported` (aviso, não erro).
+ */
+type ClientBlockType = 'quick_replies' | 'html_report' | (string & {});
+/**
+ * O que a SUA tela sabe mostrar. O agente só oferece o que você declarar — sem declarar, nada é
+ * gerado e nada é cobrado. Não exige privilégio de API key.
+ */
+interface ClientCapabilities {
+    /**
+     * `quick_replies`: até 4 sugestões curtas de resposta ao fim do turno (o usuário toca e o texto
+     * vira a próxima mensagem). Chegam em `AgentResult.suggestions` (e no bloco `quick_replies` de
+     * `blocks`). O dono do agente pode desligá-las (`quick_replies_enabled`); o agente decide quando
+     * vale sugerir — nem todo turno traz sugestões.
+     *
+     * `html_report`: a tela renderiza HTML. Não cria bloco novo: o BE orienta o agente a entregar,
+     * quando couber, um documento HTML completo num bloco de código ```html dentro do `content`
+     * (BE `14d2a43c`, 19/10/2026). Só declare se você realmente renderiza HTML — senão o usuário
+     * recebe markup cru.
+     */
+    blocks?: ClientBlockType[];
+}
+/** A pessoa do outro lado da conversa. Só vale sob API key **admin/owner**. */
+interface ConsumerIdentity {
+    /**
+     * Identificador estável da pessoa no SEU sistema (memória por pessoa, denylist, gate de
+     * engajamento). Para continuar conversas que um webhook já gravava, use o MESMO valor que o
+     * webhook usava. Enviado como `consumer_key`.
+     */
+    key: string;
+    /**
+     * Nome para exibição no console da Zihin (lista de contatos). Enviado como
+     * `consumer_display_name`. Dado pessoal: mande só o que a operação precisa ver.
+     */
+    name?: string;
+}
+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). Não combina com `sessionFrom`. */
+    sessionId?: string;
+    /**
+     * Chave de idempotência do turno (UUID, qualquer versão; BE normaliza para minúsculas).
+     * Reenviar a MESMA mensagem com o mesmo id não roda o agente de novo: enquanto o turno original
+     * está em voo o BE responde `SESSION_BUSY` (`blocked`, retentável); depois de concluído com
+     * `COMPLETED`/`LENGTH` o BE **repete a resposta gravada** (`AgentResult.idempotentReplay: true`,
+     * sem `usage`, por 24 h). Mesmo id com OUTRA mensagem → `IDEMPOTENCY_CONFLICT` (`config`).
+     * Turno que terminou em erro/timeout/gate libera o id: o reenvio roda de novo.
+     *
+     * Com ele, o núcleo passa a **retentar o POST** do `/stream` em erro de rede e 5xx antes do
+     * stream abrir (sem ele, POST nunca retenta em rede — poderia duplicar o turno).
+     *
+     * ⚠️ **O que a garantia cobre:** só não repetir um turno **concluído** (`COMPLETED`/`LENGTH`).
+     * Turno cortado no meio do stream, cancelado, com erro ou timeout **libera o id** e o reenvio
+     * roda de novo — inclusive tools de efeito colateral que já rodaram. É best-effort (Redis do BE
+     * fora → sem dedupe, campo ainda aceito). O escopo é API key + `consumerKey` (não a sessão) e a
+     * comparação é só mensagem+anexos: **nunca use um valor fixo** — um workflow agendado com a
+     * mesma mensagem receberia a mesma resposta por 24 h; reusar o id noutra sessão dá erro
+     * `config` (`IDEMPOTENT_REPLAY_OTHER_SESSION`). O BE devolve o id em minúsculas. Vale sob
+     * qualquer papel de API key. Enviado como `client_message_id`; contra um BE que não o aceite
+     * (`accepted_fields` sem ele) o núcleo recusa o turno (`config`).
+     */
+    clientMessageId?: string;
+    /**
+     * Identidade da pessoa do outro lado (memória por pessoa, denylist, gate de engajamento). Só vale
+     * sob API key **admin/owner**. Para continuar conversas que um webhook já gravava, use o MESMO
+     * valor que o webhook usava. Enviado como `consumer_key`.
+     */
+    consumerKey?: string;
+    /**
+     * A pessoa do outro lado: `{ key, name? }`. `consumer.key` é o mesmo que `consumerKey` (use um
+     * dos dois; se vierem os dois, têm de ser iguais). Só vale sob API key admin/owner.
+     */
+    consumer?: ConsumerIdentity;
+    /** O que a sua interface sabe renderizar — ex.: `{ blocks: ['quick_replies'] }`. */
+    capabilities?: ClientCapabilities;
+    /**
+     * Contexto estruturado que o **modelo lê** — bloco de plataforma junto da mensagem do usuário
+     * (não no system prompt). **Fica gravado** com a mensagem (`declared_context`) e se repete em
+     * todo turno; o BE redige segredos por nome de chave E por formato de valor (ex.: `sk-…`), o
+     * que pode alterar valores legítimos — ids que vão a tools ou ao `sessionFrom` ficam melhor em
+     * `bindings`. Plano, só escalares. Tools também o recebem. Só vale sob key admin/owner.
+     * ⚠️ Credencial não vai aqui nem em `bindings`: use um secret do tenant.
+     */
+    context?: Record<string, ContextValue>;
+    /**
+     * Valores que **só as tools** recebem — nunca vão ao prompt (ex.: id interno de fornecedor).
+     * Plano, só escalares; **nunca gravado** nem redigido (vive só no contexto das tools durante o
+     * turno). Só vale sob key admin/owner.
+     */
+    bindings?: Record<string, ContextValue>;
+    /**
+     * Deriva o `session_id` dos valores destes campos de `context ∪ bindings`, com a MESMA função
+     * do webhook (`derive: [campo]`) — o mesmo valor cai na mesma sessão pelos dois caminhos. Não
+     * combina com `sessionId`. O id derivado volta em `AgentResult.sessionId`.
+     */
+    sessionFrom?: 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;
+}
+/** Valor aceito em `context`/`bindings`: plano e escalar (regra 8 do contrato de entrada). */
+type ContextValue = string | number | boolean | null;
+/** Campo que o BE recebeu e NÃO aplicou (evento `metadata.ignored_fields`). */
+interface IgnoredField {
+    /** Nome no fio (`context`, `bindings`, `session_from`, `consumer_key`, `options.temperature`…). */
+    field: string;
+    /** Motivo reportado pelo BE (ex.: papel da key insuficiente), quando houver. */
+    reason?: string;
+}
+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;
+    /**
+     * De onde veio o `content`:
+     *  - `response`: o evento SSE `response` — o texto que o BE decidiu entregar. No `/stream` isso é
+     *    sempre o modo `final` (só as mensagens sem `tool_calls`). É o texto seguro para publicar.
+     *  - `tokens`: o stream terminou SEM o evento `response` e sobrou apenas a concatenação crua dos
+     *    deltas de todas as iterações — **deliberação interna incluída**. Foi exatamente esse texto
+     *    que vazou para um lead real e que o BE parou de entregar. Trate como parcial de diagnóstico:
+     *    não publique em canal externo sem revisar.
+     */
+    contentSource: 'response' | 'tokens';
+    sessionId?: string;
+    model?: string;
+    usage?: Usage;
+    sources?: Source[];
+    /** Cards/blocos estruturados (SPEC B). */
+    blocks?: Array<{
+        type: string;
+        [k: string]: unknown;
+    }>;
+    /**
+     * Sugestões de resposta do turno (bloco `quick_replies`), já extraídas de `blocks`. Só vêm se
+     * você declarou `capabilities: { blocks: ['quick_replies'] }`. O texto de cada uma é o que o
+     * usuário "diz" ao tocá-la. Num turno só com sugestões, `content` vem vazio.
+     */
+    suggestions?: string[];
+    iterations?: number;
+    executionTimeMs?: number;
+    /**
+     * `execution_id` do turno — handle de correlação no console/telemetria. Lido do `metadata`
+     * (BE desde 17/10/2026) com fallback no `metrics`; ausente num turno barrado por gate.
+     */
+    executionId?: string;
+    /** `client_message_id` que o BE aplicou ao turno (eco do que você mandou, em **minúsculas**). */
+    clientMessageId?: string;
+    /**
+     * `true` = esta é a resposta GRAVADA de um turno anterior com o mesmo `clientMessageId`
+     * (reenvio idempotente). O agente não rodou de novo: sem `usage`/`model`/`iterations`, e
+     * `truncated`/`finishReason` não vêm mesmo que o original fosse `LENGTH`.
+     */
+    idempotentReplay?: boolean;
+    /** Id da mensagem do usuário gravada na sessão (quando o BE o deu). */
+    userMessageId?: string;
+    /** Id da mensagem do agente gravada na sessão (quando o BE o deu). */
+    assistantMessageId?: string;
+    /** Campos do pedido que o BE aplicou (`metadata.accepted_fields`). Ausente = backend antigo. */
+    acceptedFields?: string[];
+    /** Campos do pedido que o BE recebeu e ignorou (`metadata.ignored_fields`). */
+    ignoredFields?: IgnoredField[];
+    /**
+     * `true` = o `content` é a resposta ENLATADA de um gate da plataforma (conversa em atendimento
+     * humano, consumidor bloqueado, sessão suspensa), não do agente: nenhum modelo rodou. Em canal
+     * conversacional ela pode ser entregue à pessoa; numa automação, trate como "não respondido".
+     */
+    gated?: boolean;
+    /**
+     * Desfecho do turno, lido do `done` (`exitReason` do motor). `undefined` = backend antigo ou
+     * stream cortado antes do `done`. Só chegam aqui os desfechos cujo `content` é resposta
+     * (`COMPLETED`, `LENGTH`), o `PAUSED` (aprovação pendente ou agente pausado) e desfechos novos.
+     * `TIMEOUT`, `ERROR`, `CANCELLED`, `SUSPENDED`, `REFUSED`, `CONTEXT_LIMIT` e os de bloqueio
+     * viram `ZihinAgentError` — o `content` desses turnos é a mensagem de falha/recusa do motor
+     * (`errorFromDoneChunk`).
+     */
+    outcome?: AgentOutcome;
+    /** `true` quando a resposta foi cortada pelo teto de saída do modelo (`done.truncated`). */
+    truncated?: boolean;
+    /** Motivo do corte quando `truncated` (ex.: `length`). */
+    finishReason?: string;
+    /** Eventos SSE brutos coletados (para depuração / casos avançados). */
+    raw: AgentStreamChunk[];
+}
+/**
+ * Desfecho do turno (`done.outcome` = `resolveTurnOutcome` do motor). `COMPLETED` e `LENGTH`
+ * contam como sucesso no BE (`isSuccessfulOutcome`); os demais valores são repassados como vêm.
+ * Aberto (`string & {}`) porque o BE pode acrescentar desfechos (ex.: os de bloqueio).
+ */
+type AgentOutcome = 'COMPLETED' | 'LENGTH' | 'TIMEOUT' | 'ERROR' | 'CANCELLED' | 'PAUSED' | 'SUSPENDED' | 'BUDGET_EXCEEDED' | 'QUOTA_EXCEEDED' | 'SESSION_BUSY' | 'CONFLICT'
+/** O provedor do modelo recusou por política (desde 08/10/2026). O `content` é um texto neutro fixo. */
+ | 'REFUSED'
+/** A conversa reuniu mais contexto do que o modelo processa (desde 14/10/2026). No `/stream` chega como `event: error`. */
+ | 'CONTEXT_LIMIT' | (string & {});
+/**
+ * Qual relógio encerrou o turno (contrato de tempo §2): `turn` (prazo do turno, inclusive o
+ * `options.timeoutMs` pedido), `first_signal` (o provedor não começou a responder), `idle`
+ * (silêncio entre pedaços do stream do provedor) ou `call` (chamada ao modelo sem stream).
+ */
+type TimeoutClock = 'turn' | 'first_signal' | 'idle' | 'call' | (string & {});
+/**
+ * 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 = 
+/**
+ * Abertura do stream. `acceptedFields`/`ignoredFields` dizem o que o BE fez com cada campo do
+ * pedido (ausentes = backend anterior ao contrato de entrada). Se o chamador mandou
+ * `context`/`bindings`/`sessionFrom` e o BE não os aceitou, o `streamAgent` lança
+ * `ZihinAgentError('config')` ANTES de entregar este chunk — nunca segue em silêncio.
+ */
+{
+    type: 'metadata';
+    requestId?: string;
+    agentId?: string;
+    sessionId?: string;
+    /** `execution_id` do turno (BE desde 17/10/2026). Ausente num turno barrado por gate. */
+    executionId?: string;
+    clientMessageId?: string;
+    /** `true` = o BE vai repetir a resposta gravada (mesmo `clientMessageId`), sem rodar o agente. */
+    idempotentReplay?: boolean;
+    acceptedFields?: string[];
+    ignoredFields?: IgnoredField[];
+    data: unknown;
+}
+/** `blocked` = motivo do bloqueio do turno (`agent_paused`, `budget_exceeded`…), quando houver. */
+ | {
+    type: 'status';
+    phase?: string;
+    blocked?: 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;
+}
+/** Aprovação humana encaminhada ao aprovador (`{ action_id, kind, title, expires_at }`); o turno fica `PAUSED`. */
+ | {
+    type: 'action_forwarded';
+    actionId?: string;
+    data: unknown;
+} | {
+    type: 'token';
+    content: string;
+    data: unknown;
+} | {
+    type: 'warning';
+    message?: string;
+    data: unknown;
+}
+/**
+ * O BE encerra o stream com `event: error` + `{ error: { type, code, message, request_id,
+ * timed_out? } }` (`utils/sse.js`) — inclusive quando o TURNO morre no deadline. O BE NÃO põe
+ * `status` nem `details` no fio (ficam no servidor): `SESSION_BUSY`, `IDEMPOTENCY_CONFLICT`,
+ * `CONTEXT_LIMIT`, `CONFLICT` e os de quota chegam só com `code`+`message`. Antes isto
+ * caía em `unknown` e o `invokeAgent` ignorava: se já tinha chegado token, devolvia a
+ * deliberação crua como SUCESSO.
+ *
+ * `timedOut` espelha `error.timed_out` (BE desde 26/09/2026, zihin-agent-builder#605): campo
+ * explícito que diz se o turno morreu por timeout, independente do NOME do código — os códigos
+ * vão ser renomeados (zihin-agent-builder#561). `undefined` = backend antigo, sem o campo.
+ */
+ | {
+    type: 'error';
+    code?: string;
+    message?: string;
+    requestId?: string;
+    timedOut?: boolean;
+    data: unknown;
+}
+/**
+ * Emitido no meio do turno SÓ quando o BE cunhou uma sessão diferente da pedida
+ * (`agents-v2.js:931`). É o id em que a conversa realmente vai continuar — vence o `session_id`
+ * do `metadata` e o que o chamador mandou. Visto em produção no E2E de 01/09.
+ */
+ | {
+    type: 'session';
+    sessionId?: string;
+    data: unknown;
+}
+/**
+ * Fim LIMPO do stream (`utils/sse.js`). Sem ele, o stream foi cortado no meio. Carrega o
+ * desfecho do turno: `{ outcome, timed_out?, timeout_clock?, truncated?, finish_reason? }`
+ * (aditivo — backend antigo manda `{}`). Um turno que o motor encerrou por tempo chega aqui
+ * com `outcome: 'TIMEOUT'` (idem ERROR e os bloqueios), DEPOIS de um `response` cujo `content`
+ * é a mensagem de falha — use `errorFromDoneChunk` para não publicá-lo como resposta.
+ */
+ | {
+    type: 'done';
+    outcome?: AgentOutcome;
+    timedOut?: boolean;
+    timeoutClock?: TimeoutClock;
+    truncated?: boolean;
+    finishReason?: string;
+    executionId?: string;
+    clientMessageId?: string;
+    idempotentReplay?: boolean;
+    userMessageId?: string;
+    assistantMessageId?: string;
+    data: unknown;
+} | {
+    type: 'response';
+    content: string;
+    sessionId?: string;
+    sources?: Source[];
+    blocks?: Array<{
+        type: string;
+        [k: string]: unknown;
+    }>;
+    /** Sugestões de resposta (bloco `quick_replies`), extraídas de `blocks`. */
+    suggestions?: string[];
+    /** Resposta ENLATADA de um gate (handoff humano, denylist, sessão suspensa) — não do agente. */
+    gated?: boolean;
+    executionId?: string;
+    clientMessageId?: string;
+    idempotentReplay?: boolean;
+    userMessageId?: string;
+    assistantMessageId?: string;
+    data: unknown;
+} | {
+    type: 'metrics';
+    usage?: Usage;
+    model?: string;
+    iterations?: number;
+    executionTimeMs?: number;
+    executionId?: string;
+    data: unknown;
+} | {
+    type: 'unknown';
+    event: string;
+    data: unknown;
+};
+type TriggerMode = 'sync' | 'async';
+/**
+ * Como o BE monta o texto entregue pelo trigger (`#343/#345`):
+ *  - `final` (default): só as mensagens do agente SEM `tool_calls`. O texto que acompanha uma
+ *    chamada de tool é deliberação interna — vazou para um lead real via WhatsApp.
+ *  - `concat` (legado): concatena todas as iterações. Só peça se você realmente depende da
+ *    narrativa completa e o destino é interno.
+ *
+ * ⚠️ O BE lê isto de `trigger_config.execution.callback.response_transform.mode`, e o validador dele
+ * exige `callback.url` sempre que o objeto `callback` existe. Consequência verificada em 2026-08-31:
+ * **um trigger `sync` não consegue declarar o modo sem uma callbackUrl válida**, mesmo que ela nunca
+ * seja chamada. `createTrigger` falha alto nesse caso em vez de mandar um config que o BE rejeita.
+ */
+type ResponseTransformMode = 'final' | 'concat';
+/**
+ * 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';
+    /**
+     * Modo de extração da resposta do agente. Default do BE: `final`. Exige `callbackUrl` — ver
+     * {@link ResponseTransformMode}.
+     */
+    responseTransform?: ResponseTransformMode;
+    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;
+    /**
+     * Troca o modo de extração da resposta, preservando `strip_markdown`/`max_length` já
+     * configurados. Exige que o trigger já tenha um `callback` (ou que `callbackUrl` venha junto).
+     */
+    responseTransform?: ResponseTransformMode;
+    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` | `email` | `schedule`; `db_event` foi removido do BE em 03/10/2026). */
+    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 aceitou o disparo. Um turno que FALHOU não chega aqui: o BE responde 200
+     * com `{ success:false }` e o núcleo lança — antes isso voltava como disparo aceito com
+     * resposta vazia.
+     */
+    accepted: boolean;
+    triggerId?: string;
+    agentId?: string;
+    /** Id da execução do TRIGGER (`trigger_executions`), não o `execution_id` do turno do agente. */
+    executionId?: string;
+    /** Presente quando o trigger é `sync`: resposta imediata do agente. */
+    agentResponse?: string;
+    /**
+     * Desfecho do turno no modo `sync` (BE desde 14/10/2026; ausente = backend antigo). Só chegam
+     * aqui os desfechos cujo `agentResponse` é resposta (`COMPLETED`, `LENGTH`) e o `PAUSED`; os
+     * demais (`REFUSED`, `CONTEXT_LIMIT`, `TIMEOUT`, `ERROR`…) viram `ZihinAgentError` mesmo com
+     * `success: true` no corpo — o BE mantém `success` como "entregou", e o texto é a frase da
+     * plataforma, não uma resposta. Limite: o sync não traz `status.blocked`, então o `PAUSED` de
+     * agente pausado/arquivado chega aqui com o texto de recusa em `agentResponse`.
+     */
+    outcome?: AgentOutcome;
+    usage?: Usage;
+    /** Iterações do laço de tools no turno (sync). */
+    iterations?: number;
+    /** Latência medida pelo BE, ponta a ponta (sync). */
+    latencyMs?: number;
+    /**
+     * O texto que o BE extraiu do payload e entregou ao agente. É o campo que denuncia um
+     * `query_extraction` mal configurado — mensagem vazia, ou o payload inteiro virando a pergunta.
+     */
+    queryExtracted?: string;
+    raw: unknown;
+}
+interface ExecutionStatus {
+    executionId: string;
+    /**
+     * Status cru do BE. Além de `completed`/`failed`, o `trigger_executions` passou a registrar
+     * `skipped`, `quota_exhausted` e `timeout` de verdade (agosto/2026) — não trate como enum
+     * fechado; use `terminal` para decidir quando parar de esperar.
+     */
+    status: string;
+    /**
+     * false só enquanto a execução está em andamento. Qualquer status desconhecido conta como
+     * terminal, para que o polling pare em vez de girar para sempre num estado novo do BE.
+     */
+    terminal: boolean;
+    startedAt?: string;
+    finishedAt?: string;
+    executionTimeMs?: number;
+    usage?: Usage;
+    result?: string;
+    raw: unknown;
+}
+interface GetExecutionParams {
+    triggerId: string;
+    executionId: string;
+    signal?: AbortSignal;
+}
+interface DelegateTaskParams {
+    /** Agente que vai executar. */
+    agentId: string;
+    /** O que o agente deve fazer (obrigatório; sofre guardrail de tamanho por tier no BE). */
+    instruction: string;
+    /** Título legível para o board. */
+    title?: string;
+    /** Payload congelado junto da task. Objeto, **≤ 64KB** (teto do BE). */
+    payload?: Record<string, unknown>;
+    /**
+     * Quando executar. Omita para disparar imediatamente. Não pode estar no passado (o BE tolera
+     * 60s de diferença de relógio).
+     */
+    scheduledFor?: string | Date;
+    /** Prazo. Precisa ser futuro e posterior a `scheduledFor`; ao vencer, o sweep aborta o turno. */
+    deadlineAt?: string | Date;
+    retryPolicy?: Record<string, unknown>;
+    notify?: Record<string, unknown>;
+    /** Encadeia esta task sob outra (árvore parent/root). */
+    parentTaskId?: string;
+    signal?: AbortSignal;
+}
+/** Task como o BE a devolve. Campos além dos mapeados ficam em `raw`. */
+interface TaskInfo {
+    id: string;
+    agentId?: string;
+    title?: string;
+    instruction?: string;
+    /** `pending` → `running` → `completed` | `failed` | `cancelled` | `expired`. Não é enum fechado. */
+    status: string;
+    /**
+     * false só enquanto a task está em andamento. Status desconhecido conta como terminal (parar é
+     * melhor que girar para sempre); status ausente conta como não-terminal (não lemos o envelope).
+     */
+    terminal: boolean;
+    scheduledFor?: string;
+    deadlineAt?: string;
+    parentTaskId?: string;
+    rootTaskId?: string;
+    sessionId?: string;
+    createdAt?: string;
+    updatedAt?: string;
+    raw: unknown;
+}
+interface ListTasksParams {
+    /** Só estados vivos (board do dia a dia). */
+    live?: boolean;
+    status?: string;
+    agentId?: string;
+    rootTaskId?: string;
+    limit?: number;
+    offset?: number;
+    signal?: AbortSignal;
+}
+interface TaskListPage {
+    items: TaskInfo[];
+    /** Total do tenant para a query. Vem de `meta.total` no envelope novo. */
+    total?: number;
+    raw: unknown;
+}
+/** Uma execução da task (uma task pode ter várias, com retry). */
+interface TaskExecution {
+    id: string;
+    status: string;
+    exitReason?: string;
+    modelUsed?: string;
+    totalCostUsd?: number;
+    executionTimeMs?: number;
+    iterations?: number;
+    startedAt?: string;
+    finishedAt?: string;
+    raw: unknown;
+}
+interface TaskDossier {
+    task: TaskInfo;
+    executions: TaskExecution[];
+    children: TaskInfo[];
+    approvals: unknown[];
+    raw: unknown;
+}
+interface GetTaskParams {
+    taskId: string;
+    signal?: AbortSignal;
+}
+interface CancelTaskParams {
+    taskId: string;
+    /** Registrado na trilha. Default do BE: `user_cancel`. */
+    reason?: string;
+    signal?: AbortSignal;
+}
+interface CancelTaskResult {
+    task: TaskInfo;
+    /** true quando havia um turno em voo que foi realmente derrubado. */
+    aborted: boolean;
+    raw: unknown;
+}
+
+/**
+ * Transporte HTTP do núcleo: resolução/validação de base URL (SSRF), headers de auth,
+ * deadline via AbortController que cobre TODO o request (headers + corpo/stream),
+ * e retry com exponential backoff + jitter.
+ *
+ * Política de retry (evita duplicar efeito colateral):
+ *  - 'idempotent' (GET): retenta em erro de rede, 429 e 5xx.
+ *  - 'side-effecting' (POST: invoke/dispatch/create): retenta SÓ em 429/503 (servidor disse
+ *    "tente depois", sem ter processado). NUNCA em erro de rede — o request pode ter sido
+ *    recebido e processado mesmo com o socket caindo na volta.
+ *
+ * @module http
+ */
+
+/**
+ * Deadline default POR OPERAÇÃO. Cada valor fica ACIMA do orçamento do BE para aquela rota,
+ * porque o BE foi desenhado para entregar o desfecho ao cliente — desistir antes dele troca um
+ * erro estruturado (TURN_TIMEOUT com execution_id/session_id) por um abort cego nosso.
+ *
+ * Verificado contra o BE (`zihin-agent-builder/server-llm`) em 2026-08-31:
+ *  - `stream`   POST /api/v2/agents/:id/stream — o SSE fecha em 180s (`agents-v2.js:690`) e o turno
+ *               do canal `chat` morre em 150s (`turn-deadline.js`). O stream sobrevive ao turno DE
+ *               PROPÓSITO, para entregar o desfecho; 200s deixa essa cauda chegar.
+ *  - `dispatch` POST /api/triggers/webhook/:id — fora do timeout global do Express
+ *               (`express.js:71`); turno de canal `async` = 240s (`turn-deadline.js`).
+ *  - `short`    GETs de listagem/telemetria e CRUD de trigger — timeout global de 30s
+ *               (`express.js:40`), que responde 408. Esperar mais que isso é esperar à toa.
+ *
+ * Mudou o BE? Atualize esta tabela e `docs/CONTRATO-INVOCACAO-AGENTE.md` juntos.
+ */
+declare const OPERATION_TIMEOUT_MS: Readonly<{
+    stream: 200000;
+    dispatch: 260000;
+    short: 35000;
+}>;
+type TimeoutOperation = keyof typeof OPERATION_TIMEOUT_MS;
+/**
+ * Folga somada ao `options.timeoutMs` do chamador para formar o deadline LOCAL. O mesmo número vai
+ * ao BE como `options.timeout_ms` (o teto que ele deve respeitar); sem folga, os dois relógios
+ * disparam juntos e o erro do servidor — que tem request_id — perde a corrida para o nosso abort.
+ *
+ * 30s, não 10s: o relógio do turno no BE só começa DEPOIS da carga (config, tools, gates — um MCP
+ * frio leva dezenas de segundos), então o tempo de parede visto daqui é `carga + prazo` (contrato
+ * de tempo §4). Com 10s, um `timeoutMs: 60000` num agente com MCP abortava aos 70s e trocava o
+ * `done { outcome: 'TIMEOUT' }` do servidor por um abort cego.
+ */
+declare const DEADLINE_GRACE_MS = 30000;
+
+/**
+ * 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>;
+    /**
+     * Delega uma tarefa a um agente (requer key owner/admin). Sem `scheduledFor`, o BE dispara na
+     * hora fora do request e devolve só o handle — acompanhe com `getTask`.
+     */
+    delegateTask(params: DelegateTaskParams): Promise<TaskInfo>;
+    /** Board de tasks do tenant (requer key owner/admin/editor). */
+    listTasks(params?: ListTasksParams): Promise<TaskListPage>;
+    /** Dossiê de uma task: task + execuções + filhos + aprovações. */
+    getTask(params: GetTaskParams): Promise<TaskDossier>;
+    /** Cancela uma task (requer key owner/admin); derruba o turno em voo, se houver. */
+    cancelTask(params: CancelTaskParams): Promise<CancelTaskResult>;
+    /** 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;
+
+/**
+ * Caminho A — invocação direta de agente (POST /api/v2/agents/:id/stream).
+ * `streamAgent` emite deltas ao vivo; `invokeAgent` buffeia o stream e consolida
+ * o evento `response` (content/sources/session_id/blocks) com o `metrics` (usage/model).
+ *
+ * @module invoke
+ */
+
+/**
+ * Decide se o `event: error` terminal do BE foi um timeout do turno (#75).
+ *
+ * Fonte primária é o campo EXPLÍCITO `error.timed_out` (BE `utils/sse.js`, em prod desde
+ * 26/09/2026 — zihin-agent-builder#605): quando presente, é autoritativo nos dois sentidos —
+ * `true` classifica como timeout seja qual for o `code`; `false` classifica como `server` mesmo
+ * que o nome do código contenha "TIMEOUT". O BE vai renomear esses códigos
+ * (zihin-agent-builder#561) e o nome deixa de ser um sinal confiável.
+ *
+ * O regex no nome só vale como FALLBACK para backends que ainda não emitem `timed_out`
+ * (self-hosted/antigos). Some numa major futura, depois do rename no BE.
+ */
+declare function classifyStreamErrorKind(code: string, timedOut?: boolean): ZihinErrorKind;
+/**
+ * Converte o chunk `type: 'error'` (evento terminal do BE) num `ZihinAgentError` — a MESMA regra
+ * que o `invokeAgent` aplica, exportada para quem consome `streamAgent` direto (o adapter do
+ * Paperclip, por exemplo) não reimplementar a classificação por conta e divergir dela.
+ * `ctx` leva os ids já vistos no `metadata` (o `error` em si não os traz).
+ */
+declare function errorFromStreamChunk(chunk: Extract<AgentStreamChunk, {
+    type: 'error';
+}>, ctx?: {
+    executionId?: string;
+    sessionId?: string;
+}): ZihinAgentError;
+/**
+ * Converte um `outcome` cru (fora do `/stream`: `outcome` do webhook sync, `exit_reason` de uma
+ * execução) num `ZihinAgentError`, ou `undefined` quando o texto que o acompanha É resposta
+ * (`COMPLETED`, `LENGTH`, `PAUSED`, desconhecido/ausente). Mesma tabela do `errorFromDoneChunk`,
+ * sem o contexto de `status.blocked` que só o SSE tem.
+ */
+declare function errorFromOutcome(outcome: string | undefined, ctx?: {
+    executionId?: string;
+    sessionId?: string;
+    status?: number;
+    endpoint?: string;
+    attempts?: number;
+}): ZihinAgentError | undefined;
+/**
+ * Converte o `done` de um turno que NÃO produziu resposta num `ZihinAgentError`; devolve
+ * `undefined` quando o `content` é resposta. Mesma regra do `invokeAgent`, exportada para quem
+ * consome `streamAgent` direto (o Paperclip) não reimplementá-la.
+ *
+ * Por que erro e não um campo no resultado: nesses turnos o BE já emitiu um `response` com a
+ * mensagem de falha do motor em `content` (contrato de tempo §6). Como campo, cada shell teria
+ * de lembrar de checá-lo — e o que esquecesse publicaria a falha como resposta, que é o defeito
+ * que isto fecha (#81). Como erro, o caminho seguro é o default.
+ *
+ * TIMEOUT: `outcome: 'TIMEOUT'` é a fonte primária; `timed_out: true` sozinho também conta (o BE
+ * só o emite com TIMEOUT). Vira `kind: 'timeout'`, `code: 'TURN_TIMEOUT'`, com `timeoutClock`.
+ * Nenhum é retentável por default: o turno pode ter executado tools com efeito colateral
+ * (exceção: `SESSION_BUSY`, em que o turno nem começou).
+ */
+declare function errorFromDoneChunk(chunk: Extract<AgentStreamChunk, {
+    type: 'done';
+}>, ctx?: {
+    executionId?: string;
+    sessionId?: string;
+    blocked?: string;
+}): ZihinAgentError | undefined;
+
+/**
+ * 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
+ * suportado (>=20.16). (Todo o resto do núcleo é Web-API puro e roda nos dois.)
+ */
+declare function signRequest(payload: string, secretKey: string, timestamp?: number): SignedRequestHeaders;
+
+/**
+ * Caminho C — delegação assíncrona durável (`/api/v1/tasks`).
+ *
+ * Diferente do Caminho B (triggers), aqui a conexão pode morrer sem levar o trabalho junto: a
+ * task é persistida (`agent_tasks`), executada fora do request e o resultado é notificado. É o
+ * caminho para runs que estouram o teto do host — o passo do Zapier morre em ~30s, e o próprio
+ * app marca isso como pendência desde o primeiro commit.
+ *
+ * Contrato verificado em `routes/tasks.js` (2026-08-31) — ver o Caminho C de
+ * `docs/CONTRATO-INVOCACAO-AGENTE.md`. Três coisas que diferem do resto da API e custaram
+ * retrabalho quando supostas em vez de lidas:
+ *  1. O envelope é o canônico novo: `{ success, data, meta:{request_id} }`. O `request_id` do
+ *     sucesso vive em `meta`, não no topo.
+ *  2. O RBAC é mais estreito do que "admin/editor": delegar e cancelar exigem **owner|admin**;
+ *     editor só lê o board e o dossiê.
+ *  3. Sem `scheduled_for` o BE dispara na hora, fora do request (`setImmediate`), e a resposta
+ *     devolve só o handle — por isso estas rotas são todas de orçamento curto.
+ *
+ * @module tasks
+ */
+
+/**
+ * Teto do `payload` congelado na task. Espelha o `MAX_PAYLOAD_BYTES` do BE
+ * (`routes/tasks.js:26`) — validar aqui evita gastar um round-trip para receber um 400.
+ */
+declare const MAX_TASK_PAYLOAD_BYTES: number;
+
+export { type AgentOutcome, type AgentResult, type AgentStreamChunk, type AgentSummary, type Attachment, type AttachmentType, type CancelTaskParams, type CancelTaskResult, type ClientBlockType, type ClientCapabilities, type ConsumerIdentity, type ContextValue, type CreateTriggerParams, DEADLINE_GRACE_MS, DEFAULT_LIMITS, type DelegateTaskParams, type DeleteTriggerParams, type DispatchAgentParams, type DispatchResult, type ExecutionStatus, type FindOrCreateResult, type GetExecutionParams, type GetTaskParams, type GetTriggerParams, type IgnoredField, type InvokeAgentParams, type InvokeOptions, type ListTasksParams, type ListTriggersParams, MAX_TASK_PAYLOAD_BYTES, OPERATION_TIMEOUT_MS, type QueryExtraction, type ResponseTransformMode, type RetryInfo, type SignedRequestHeaders, type Source, type TaskDossier, type TaskExecution, type TaskInfo, type TaskListPage, type TimeoutClock, type TimeoutOperation, type TriggerInfo, type TriggerMode, type TriggerRef, type UpdateTriggerParams, type Usage, ZihinAgentClient, ZihinAgentError, type ZihinClientConfig, type ZihinErrorKind, type ZihinRuntime, classifyStreamErrorKind, createClient, errorFromDoneChunk, errorFromOutcome, errorFromStreamChunk, isCommercialBlock, sanitizeApiError, signRequest, validateApiKeyFormat, validateBaseUrl, validatePromptSize };