@zihin/agent-client 0.2.0 → 0.4.1

package/README.md

@@ -118,6 +118,54 @@ await zihin.deleteTrigger({ triggerId });     // remove (requer key admin/owner;
 > `trigger_config` inteiro). Há uma janela entre o GET e o PATCH em que uma escrita concorrente
 > pode ser sobrescrita.
 
+## Uso — delegação assíncrona durável (tasks)
+
+Para runs que estouram o teto do host (o passo do Zapier morre em ~30s) ou que não podem depender
+da conexão viva. A task é persistida no BE, executada fora do request e o resultado notificado.
+Exige key **owner/admin** para delegar e cancelar; editor só lê.
+
+```ts
+const task = await zihin.delegateTask({
+	agentId,
+	instruction: 'Gere o relatório mensal e envie por e-mail',
+	title: 'Relatório de agosto',
+	payload: { mes: '2026-08' },          // objeto, ≤ 64KB — validado localmente
+	deadlineAt: new Date(Date.now() + 3600e3),
+});
+
+// polling: pare quando `terminal` for true — qualquer status desconhecido conta como terminal
+let dossie;
+do {
+	await new Promise((r) => setTimeout(r, 2000));
+	dossie = await zihin.getTask({ taskId: task.id });
+} while (!dossie.task.terminal);
+
+console.log(dossie.task.status, dossie.executions.at(-1)?.totalCostUsd);
+await zihin.cancelTask({ taskId: task.id, reason: 'mudou o plano' }); // 409 se já encerrou
+```
+
+`listTasks({ live: true })` devolve o board (`items` + `total`, este vindo de `meta`).
+
+## O texto que volta — e o que NÃO é resposta
+
+`AgentResult.contentSource` diz de onde veio o `content`:
+
+- **`'response'`** — o evento final do BE, que no `/stream` é sempre o modo `final` (só as mensagens
+  sem `tool_calls`). **É o texto seguro para publicar.**
+- **`'tokens'`** — o stream morreu antes do evento final e sobrou só a concatenação crua dos deltas,
+  **com a deliberação interna do modelo**. Foi exatamente isso que vazou para um lead real via
+  WhatsApp e que o BE parou de entregar. Trate como parcial de diagnóstico; não mande para fora
+  sem revisar.
+
+Um `content` vazio com `contentSource: 'response'` é decisão do BE, não lacuna — o núcleo **não**
+preenche com tokens. E quando o BE fecha o stream com `event: error` (turno morto no deadline, por
+exemplo), o núcleo **lança** (`kind: 'timeout'`, com `code` e `requestId`) em vez de devolver o
+parcial. Se foi timeout ou não vem do campo **explícito `error.timed_out`** do evento (BE desde
+26/09/2026): quando presente ele é autoritativo — `true` é timeout seja qual for o `code`, `false`
+é `server` mesmo com "TIMEOUT" no nome. Sem o campo (backend antigo), cai no fallback por nome
+(`/TIMEOUT/i` no `code`), que será removido numa major futura. Não ramifique no **nome** do código
+de timeout: o BE vai renomeá-los (zihin-agent-builder#561); use `kind`.
+
 ## Dropdown de agentes
 
 ```ts
@@ -140,10 +188,33 @@ suporte correlacionar). Erros de rede carregam a causa-raiz (`ECONNREFUSED`/`ENO
 mensagem. As mensagens redigem **só segredos** (key/Bearer/stack) — `request_id`/`trace_id` são
 preservados. Cancele com `AbortSignal` via `params.signal`.
 
+### Bloqueio comercial não é credencial errada
+
+Trial vencido, assinatura inativa e quota esgotada chegam do BE como 403/429 e, mapeados só pelo
+status, virariam "troque a key" ou "tente de novo". Têm `kind` próprio e **nunca são retentados**:
+
+| `kind` | HTTP | O que fazer |
+|---|---|---|
+| `trial_expired` | 403 | Fazer upgrade do plano — a key está certa |
+| `no_subscription` | 429 | Ativar uma assinatura — a key está certa |
+| `quota_exceeded` | 429 | Esperar o ciclo ou subir o plano — retentar não ajuda |
+
+`isCommercialBlock(body)` é exportado para quem inspeciona respostas por conta própria. O 403 comum
+(`kind: 'auth'`) significa que o **papel** da key não permite a ação — e o papel exigido varia por
+rota (editor cria trigger, mas não delega task), então a mensagem não enumera papéis.
+
+`ZihinAgentError.executionId` vem preenchido quando o BE o entrega (sucesso e erro) — é o handle para
+correlacionar com o console.
+
 ## Robustez (timeout / retry / limites)
 
-- **Timeout cobre tudo** — headers e o corpo/stream inteiro. `timeoutMs` (default 120s, igual ao cap
-  do BE) é o tempo máximo total da chamada; `AbortSignal` do chamador funciona durante todo o stream.
+- **Timeout cobre tudo** — headers e o corpo/stream inteiro. Os defaults são **por operação**
+  (`OPERATION_TIMEOUT_MS`): stream 200s, dispatch de trigger 260s, GETs curtos 35s. Cada um fica
+  ACIMA do orçamento do BE para aquela rota (SSE 180s, turno async 240s, timeout global 30s), para
+  que o desfecho do servidor chegue como erro estruturado em vez de abort cego do cliente.
+  `timeoutMs` na config sobrepõe todos; `options.timeoutMs` por chamada vai ao BE como
+  `timeout_ms` e o deadline local fica um pouco acima dele. Retentativas NÃO encolhem o deadline
+  da tentativa seguinte — o que fica limitado é o tempo gasto com retries.
 - **Retry sem duplicar efeito** — GET (idempotente) retenta em rede/429/5xx; POST com efeito
   (`invokeAgent`/`dispatchAgent`/`createTrigger`) retenta **só em 429/503** e **nunca em erro de
   rede** (o request pode ter sido processado). Backoff exponencial 1s→10s com jitter.

package/dist/index.d.mts

@@ -4,7 +4,7 @@
  *
  * @module errors
  */
-type ZihinErrorKind = 'config' | 'auth' | 'not_found' | 'rate_limit' | 'timeout' | 'aborted' | 'server' | 'network' | 'protocol' | 'unknown';
+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". */
@@ -18,6 +18,11 @@ interface ZihinErrorOptions extends ErrorMeta {
     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;
@@ -27,8 +32,14 @@ declare class ZihinAgentError extends Error {
     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
@@ -42,7 +53,13 @@ interface ZihinClientConfig {
     apiKey: string;
     /** Base URL. Default: https://llm.zihin.ai */
     baseUrl?: string;
-    /** Timeout por request (ms). Default: 120000 (= limite do /stream no BE). */
+    /**
+     * 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;
@@ -137,6 +154,16 @@ interface Source {
  */
 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;
@@ -194,6 +221,39 @@ type AgentStreamChunk = {
     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. 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:92`). Sem ele, o stream foi cortado no meio. */
+ | {
+    type: 'done';
+    data: unknown;
 } | {
     type: 'response';
     content: string;
@@ -217,6 +277,19 @@ type AgentStreamChunk = {
     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]`).
@@ -254,6 +327,11 @@ interface CreateTriggerParams {
     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;
 }
 /**
@@ -273,6 +351,11 @@ interface UpdateTriggerParams {
     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 {
@@ -321,18 +404,42 @@ interface DispatchAgentParams {
     signal?: AbortSignal;
 }
 interface DispatchResult {
-    /** true quando o BE retorna 202 (async) ou 200 (sync). */
+    /**
+     * 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;
@@ -345,6 +452,145 @@ interface GetExecutionParams {
     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)
@@ -404,6 +650,17 @@ declare class ZihinAgentClient {
     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;
@@ -412,6 +669,36 @@ declare class ZihinAgentClient {
 /** 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): 'timeout' | 'server';
+/**
+ * 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.
+ */
+declare function errorFromStreamChunk(chunk: Extract<AgentStreamChunk, {
+    type: 'error';
+}>): ZihinAgentError;
+
 /**
  * Security utilities — portado de n8n-nodes-zihin/src/utils/security.ts (zero-dep).
  * SSRF prevention, payload limits, error sanitization, API-key format.
@@ -507,4 +794,31 @@ interface SignedRequestHeaders {
  */
 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 };
+/**
+ * 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, classifyStreamErrorKind, createClient, errorFromStreamChunk, isCommercialBlock, sanitizeApiError, signRequest, validateApiKeyFormat, validateBaseUrl, validatePromptSize };