@zihin/agent-client 0.1.0 → 0.4.0

package/dist/index.d.mts

@@ -0,0 +1,789 @@
+/**
+ * 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' | '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;
+}
+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;
+    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;
+    /**
+     * 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;
+    /**
+     * 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;
+    }>;
+    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;
+}
+/**
+ * O BE encerra o stream com `event: error` + `{ error: { type, code, message, request_id } }`
+ * (`utils/sse.js:97`) — inclusive quando o TURNO morre no deadline. Antes isto caía em
+ * `unknown` e o `invokeAgent` ignorava: se já tinha chegado token, devolvia a deliberação
+ * crua como SUCESSO.
+ */
+ | {
+    type: 'error';
+    code?: string;
+    message?: string;
+    requestId?: string;
+    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:92`). Sem ele, o stream foi cortado no meio. */
+ | {
+    type: 'done';
+    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 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 | 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 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;
+    executionId?: string;
+    /** Presente quando o trigger é `sync`: resposta imediata do agente. */
+    agentResponse?: string;
+    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.
+ */
+declare const DEADLINE_GRACE_MS = 10000;
+
+/**
+ * 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;
+
+/**
+ * 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;
+
+/**
+ * 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 AgentResult, type AgentStreamChunk, type AgentSummary, type Attachment, type AttachmentType, type CancelTaskParams, type CancelTaskResult, 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 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 TimeoutOperation, type TriggerInfo, type TriggerMode, type TriggerRef, type UpdateTriggerParams, type Usage, ZihinAgentClient, ZihinAgentError, type ZihinClientConfig, type ZihinErrorKind, createClient, isCommercialBlock, sanitizeApiError, signRequest, validateApiKeyFormat, validateBaseUrl, validatePromptSize };