@zihin/agent-client 0.6.1 → 0.8.0

package/README.md

@@ -23,7 +23,8 @@ simples, e oferece **dois estilos** de invocação:
 npm install @zihin/agent-client
 ```
 
-Requer Node >= 18 (usa `fetch`/`ReadableStream` globais).
+Requer Node >= 20.16 (usa `fetch`/`ReadableStream` globais; o `signRequest` do build ESM usa
+`process.getBuiltinModule`, 20.16+). Node 18 saiu de suporte em 04/2025 e deixou de ser testado a partir da 0.8.
 
 ## Uso — caminho direto
 
@@ -148,6 +149,55 @@ r.suggestions; // ['Caneta A', 'Caneta B'] — ou undefined quando o agente não
   servidor os lista em `ignoredFields`; o núcleo emite um `ZihinDeprecationWarning` **uma vez por
   processo** (`ZIHIN_DEP001`/`ZIHIN_DEP002`). Saem do SDK na 1.0.
 
+### Idempotência, recusa do provedor e limite de contexto (0.7)
+
+> Backend: zihin-agent-builder `server-llm` de outubro/2026 (`client_message_id` em `121e426f`,
+> `REFUSED` em `4cea8d53`, `CONTEXT_LIMIT` em `e670f530`, trava de sessão em `b67141d7`). Verificado
+> em `9ec79cfc` (03/11/2026).
+
+```ts
+const r = await zihin.invokeAgent({
+  agentId,
+  message: 'Fechar o pedido 42',
+  clientMessageId: crypto.randomUUID(), // um UUID novo por mensagem; reenvie o MESMO para retentar
+});
+r.idempotentReplay; // true = o BE repetiu a resposta gravada (o agente não rodou de novo)
+```
+
+- **`clientMessageId`** (UUID) torna o turno idempotente. 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). Reenviar o mesmo id com a mesma mensagem: turno ainda em voo →
+  `SESSION_BUSY` (`blocked`, retentável); turno concluído com `COMPLETED`/`LENGTH` → o BE repete a
+  resposta gravada por 24 h, com `idempotentReplay: true` e sem `usage`. Mesmo id com **outra**
+  mensagem → `IDEMPOTENCY_CONFLICT` (`config`). **A garantia cobre só o turno concluído**: turno
+  cortado no meio do stream, cancelado, com erro ou timeout libera o id e o reenvio roda de novo
+  (tools incluídas); por isso o retry automático é só pré-stream, e é best-effort (Redis do BE fora →
+  sem dedupe). O escopo é a API key + `consumerKey` (não a sessão) e a comparação é só
+  mensagem+anexos: **nunca use um valor fixo** (uma automação agendada receberia a mesma resposta por
+  24 h); reusar o id noutra sessão dá `config` (`IDEMPOTENT_REPLAY_OTHER_SESSION`; comparação de
+  sessão case-insensitive, o BE devolve o `session_id` em minúsculas). Essa guarda só existe em
+  `invokeAgent` **com `sessionId` explícito**: com `sessionFrom`, sem sessão, ou em `streamAgent`,
+  um id reusado devolve em silêncio a resposta (e o `session_id`) da conversa original. O BE ecoa o id
+  em minúsculas. `SERVICE_UNAVAILABLE` (replay sem resposta recuperável) **não é retentável**: pode
+  durar 24 h e só um `clientMessageId` novo sai dele.
+  Contra um servidor que não liste `client_message_id` em `accepted_fields`, o núcleo recusa o turno
+  (`config`): a garantia que você pediu não existiria.
+- **`REFUSED`**: o provedor do modelo recusou por política. O BE entrega um texto neutro fixo como
+  `response` e marca a execução como erro; o núcleo **lança** `blocked` com `code: 'REFUSED'` (na 0.6
+  o texto neutro saía como resposta). **`CONTEXT_LIMIT`**: a conversa reuniu mais contexto do que o
+  modelo processa — `blocked`, `code: 'CONTEXT_LIMIT'`; peça menos ou abra outra sessão.
+- **Trava de um turno por sessão** (ligada por padrão no BE desde 18/10/2026): mandar a segunda
+  mensagem antes da primeira terminar dá `SESSION_BUSY` como `event: error`. O núcleo o classifica
+  `blocked` **retentável** (o turno nem começou) — antes saía como `server` não retentável.
+- **Ids do turno** em `AgentResult`: `executionId` agora vem do `metadata` (chega mesmo quando o
+  turno morre antes do `metrics`), mais `clientMessageId`, `userMessageId`, `assistantMessageId`.
+- **`capabilities.blocks`** aceita `'html_report'`: a tela renderiza HTML, e o BE orienta o agente a
+  entregar, quando couber, um documento HTML num bloco ```html dentro do `content` (não é bloco novo).
+- **`dispatchAgent` (webhook sync)** lê o `outcome` do corpo: `REFUSED`, `CONTEXT_LIMIT`, `TIMEOUT`,
+  `ERROR`… chegam com `success: true` e a frase da plataforma em `agent_response`; o núcleo lança a
+  mesma classificação do `/stream`. `DispatchResult.outcome` expõe os que respondem.
+- Novo helper exportado `errorFromOutcome(outcome, ctx)` para quem lê desfechos fora do SSE.
+
 ## Uso — caminho assíncrono (triggers)
 
 ```ts
@@ -275,8 +325,8 @@ direto aplica a mesma regra com `errorFromDoneChunk(chunk, { executionId, sessio
 
 O mesmo vale para os outros desfechos em que o `content` é falha ou recusa do motor, e não
 resposta: `ERROR`/`CANCELLED` (pelo servidor) → `kind: 'server'`, `QUOTA_EXCEEDED` → `quota_exceeded`,
-`SUSPENDED`/`BUDGET_EXCEEDED`/`SESSION_BUSY`/`CONFLICT` e o `PAUSED` de agente pausado/arquivado →
-`blocked` (o `code` é o `outcome`; só `SESSION_BUSY` é retentável). Um `ERROR` precedido de
+`SUSPENDED`/`BUDGET_EXCEEDED`/`SESSION_BUSY`/`CONFLICT`/`REFUSED`/`CONTEXT_LIMIT` e o `PAUSED` de
+agente pausado/arquivado → `blocked` (o `code` é o `outcome`; só `SESSION_BUSY` é retentável). Um `ERROR` precedido de
 `status.blocked` (gate da plataforma) também sai `blocked`, com o motivo em `code`
 (`ownership_denied` → `not_found`).
 
@@ -302,8 +352,9 @@ const agents = await zihin.listAgents(); // GET /api/v2/agents
 
 ## Erros
 
-Todos os erros são `ZihinAgentError` com `kind` (`config | auth | not_found | rate_limit | timeout |
-aborted | server | network | protocol | unknown`), `status`, `code`, `retryable` e — para depurar em
+Todos os erros são `ZihinAgentError` com `kind` (`config | auth | trial_expired | no_subscription |
+quota_exceeded | not_found | rate_limit | timeout | aborted | server | network | protocol | blocked |
+unknown`), `status`, `code`, `retryable` e — para depurar em
 produção externa — `endpoint` (`"POST host/path"`), `attempts` e **`requestId`** (handle do BE para o
 suporte correlacionar). Erros de rede carregam a causa-raiz (`ECONNREFUSED`/`ENOTFOUND`/TLS…) na
 mensagem. As mensagens redigem **só segredos** (key/Bearer/stack) — `request_id`/`trace_id` são
@@ -345,7 +396,15 @@ correlacionar com o console.
   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.
+  rede** (o request pode ter sido processado). Exceção: `invokeAgent` com `clientMessageId` retenta
+  também em rede e 5xx, **só antes dos headers do SSE chegarem**. É seguro porque o BE envia os
+  headers antes de reservar o id e antes de qualquer trabalho do turno; se o 1º POST chegou a rodar,
+  a chave transforma o reenvio em `SESSION_BUSY` ou replay. Um stream **cortado no meio** sai
+  `network` com `retryable: false`: o BE cancela o turno e libera o id, então reenviar (mesmo com a
+  chave) roda as tools de novo. Contra um BE antigo que ainda não aceite `client_message_id`, o
+  retry pré-headers acontece sem a chave valer (o turno falha depois em `config`); a ordem
+  headers-antes-do-trabalho é a mesma, mas a garantia depende do BE. Backoff exponencial 1s→10s
+  com jitter.
 - **Anti-DoS de memória** — limites de stream `maxStreamEventBytes` (1MB) e `maxStreamTotalBytes`
   (64MB); estourar aborta com `protocol`. Configuráveis no `createClient`.
 - **`includeRaw`** — por padrão `invokeAgent` não retém os eventos brutos (`raw: []`) para economizar
@@ -360,7 +419,7 @@ correlacionar com o console.
   `delayMs`/`reason`/`status`) e `onError(err)` — chamado quando uma operação falha em definitivo
   (inclusive `aborted`; filtre por `err.kind`). Exceção lançada dentro do hook é engolida e nunca
   mascara o erro original.
-- **`fetch` injetável** — `fetch?` na config; por padrão usa `globalThis.fetch` (Node ≥18). Um
+- **`fetch` injetável** — `fetch?` na config; por padrão usa `globalThis.fetch` (Node ≥20.16). Um
   preflight dá erro `config` claro se não houver fetch.
 - **Portável** — sem `Buffer`; `node:crypto` só é carregado se você usar `signRequest`. Roda em Node;
   para edge/serverless, injete `fetch` se necessário. O pacote publica **CJS e ESM** (`exports` map):

package/dist/index.d.mts

@@ -146,8 +146,11 @@ interface InvokeOptions {
      */
     jitMode?: boolean;
 }
-/** Blocos estruturados que a sua interface sabe renderizar (`capabilities.blocks`). */
-type ClientBlockType = 'quick_replies';
+/**
+ * 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.
@@ -158,6 +161,11 @@ interface ClientCapabilities {
      * 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[];
 }
@@ -184,6 +192,28 @@ interface InvokeAgentParams {
     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
@@ -285,8 +315,23 @@ interface AgentResult {
     suggestions?: string[];
     iterations?: number;
     executionTimeMs?: number;
-    /** `execution_id` do turno (evento `metrics`) — handle de correlação no console/telemetria. */
+    /**
+     * `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`). */
@@ -301,8 +346,9 @@ interface AgentResult {
      * 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` e os de bloqueio viram `ZihinAgentError` — o
-     * `content` desses turnos é a mensagem de falha/recusa do motor (`errorFromDoneChunk`).
+     * `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`). */
@@ -317,7 +363,11 @@ interface AgentResult {
  * 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' | (string & {});
+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`
@@ -341,6 +391,11 @@ type AgentStreamChunk =
     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;
@@ -371,6 +426,12 @@ type AgentStreamChunk =
 } | {
     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;
@@ -382,7 +443,9 @@ type AgentStreamChunk =
 }
 /**
  * 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
+ * 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.
  *
@@ -422,6 +485,11 @@ type AgentStreamChunk =
     timeoutClock?: TimeoutClock;
     truncated?: boolean;
     finishReason?: string;
+    executionId?: string;
+    clientMessageId?: string;
+    idempotentReplay?: boolean;
+    userMessageId?: string;
+    assistantMessageId?: string;
     data: unknown;
 } | {
     type: 'response';
@@ -436,6 +504,11 @@ type AgentStreamChunk =
     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';
@@ -557,7 +630,7 @@ interface TriggerInfo {
 interface ListTriggersParams {
     /** Filtra por agente. */
     agentId?: string;
-    /** Filtra por tipo (webhook | db_event | email | schedule). */
+    /** Filtra por tipo (`webhook` | `email` | `schedule`; `db_event` foi removido do BE em 03/10/2026). */
     triggerType?: string;
     /** Apenas habilitados. */
     enabledOnly?: boolean;
@@ -586,9 +659,19 @@ interface DispatchResult {
     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;
@@ -868,15 +951,32 @@ declare function createClient(config: ZihinClientConfig): ZihinAgentClient;
  * 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' | 'config';
+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';
-}>): ZihinAgentError;
+}>, 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
@@ -991,7 +1091,7 @@ interface SignedRequestHeaders {
  *
  * ⚠️ 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.)
+ * 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;
 
@@ -1022,4 +1122,4 @@ declare function signRequest(payload: string, secretKey: string, timestamp?: num
  */
 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, classifyStreamErrorKind, createClient, errorFromDoneChunk, errorFromStreamChunk, isCommercialBlock, sanitizeApiError, signRequest, validateApiKeyFormat, validateBaseUrl, validatePromptSize };
+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, classifyStreamErrorKind, createClient, errorFromDoneChunk, errorFromOutcome, errorFromStreamChunk, isCommercialBlock, sanitizeApiError, signRequest, validateApiKeyFormat, validateBaseUrl, validatePromptSize };

package/dist/index.d.ts

@@ -146,8 +146,11 @@ interface InvokeOptions {
      */
     jitMode?: boolean;
 }
-/** Blocos estruturados que a sua interface sabe renderizar (`capabilities.blocks`). */
-type ClientBlockType = 'quick_replies';
+/**
+ * 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.
@@ -158,6 +161,11 @@ interface ClientCapabilities {
      * 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[];
 }
@@ -184,6 +192,28 @@ interface InvokeAgentParams {
     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
@@ -285,8 +315,23 @@ interface AgentResult {
     suggestions?: string[];
     iterations?: number;
     executionTimeMs?: number;
-    /** `execution_id` do turno (evento `metrics`) — handle de correlação no console/telemetria. */
+    /**
+     * `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`). */
@@ -301,8 +346,9 @@ interface AgentResult {
      * 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` e os de bloqueio viram `ZihinAgentError` — o
-     * `content` desses turnos é a mensagem de falha/recusa do motor (`errorFromDoneChunk`).
+     * `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`). */
@@ -317,7 +363,11 @@ interface AgentResult {
  * 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' | (string & {});
+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`
@@ -341,6 +391,11 @@ type AgentStreamChunk =
     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;
@@ -371,6 +426,12 @@ type AgentStreamChunk =
 } | {
     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;
@@ -382,7 +443,9 @@ type AgentStreamChunk =
 }
 /**
  * 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
+ * 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.
  *
@@ -422,6 +485,11 @@ type AgentStreamChunk =
     timeoutClock?: TimeoutClock;
     truncated?: boolean;
     finishReason?: string;
+    executionId?: string;
+    clientMessageId?: string;
+    idempotentReplay?: boolean;
+    userMessageId?: string;
+    assistantMessageId?: string;
     data: unknown;
 } | {
     type: 'response';
@@ -436,6 +504,11 @@ type AgentStreamChunk =
     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';
@@ -557,7 +630,7 @@ interface TriggerInfo {
 interface ListTriggersParams {
     /** Filtra por agente. */
     agentId?: string;
-    /** Filtra por tipo (webhook | db_event | email | schedule). */
+    /** Filtra por tipo (`webhook` | `email` | `schedule`; `db_event` foi removido do BE em 03/10/2026). */
     triggerType?: string;
     /** Apenas habilitados. */
     enabledOnly?: boolean;
@@ -586,9 +659,19 @@ interface DispatchResult {
     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;
@@ -868,15 +951,32 @@ declare function createClient(config: ZihinClientConfig): ZihinAgentClient;
  * 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' | 'config';
+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';
-}>): ZihinAgentError;
+}>, 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
@@ -991,7 +1091,7 @@ interface SignedRequestHeaders {
  *
  * ⚠️ 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.)
+ * 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;
 
@@ -1022,4 +1122,4 @@ declare function signRequest(payload: string, secretKey: string, timestamp?: num
  */
 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, classifyStreamErrorKind, createClient, errorFromDoneChunk, errorFromStreamChunk, isCommercialBlock, sanitizeApiError, signRequest, validateApiKeyFormat, validateBaseUrl, validatePromptSize };
+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, classifyStreamErrorKind, createClient, errorFromDoneChunk, errorFromOutcome, errorFromStreamChunk, isCommercialBlock, sanitizeApiError, signRequest, validateApiKeyFormat, validateBaseUrl, validatePromptSize };