@zihin/agent-client 0.6.0 → 0.7.0

package/dist/index.d.ts

@@ -118,7 +118,17 @@ interface Attachment {
     type: AttachmentType;
 }
 interface InvokeOptions {
+    /**
+     * @deprecated Sem efeito: o `/stream` usa a temperatura da configuração do agente
+     * (`llm_config.temperature`, no console ou via `update_agent`). O servidor ignora o campo e o
+     * reporta em `ignoredFields`. Será retirado do SDK na 1.0.
+     */
     temperature?: number;
+    /**
+     * @deprecated Sem efeito: o teto de saída é a configuração do agente (`llm_config.max_tokens`,
+     * no console ou via `update_agent`). O servidor ignora o campo e o reporta em `ignoredFields`.
+     * Será retirado do SDK na 1.0.
+     */
     maxTokens?: number;
     /**
      * Teto do TURNO desta chamada (ms); sobrepõe o do cliente. Vai ao BE como `options.timeout_ms`
@@ -130,9 +140,49 @@ interface InvokeOptions {
      * local soma `DEADLINE_GRACE_MS` a este valor para ainda receber o desfecho do servidor.
      */
     timeoutMs?: number;
-    /** Just-in-time tool loading (Sprint 33). */
+    /**
+     * @deprecated Recurso descontinuado no servidor (ago/2026): sem efeito, reportado em
+     * `ignoredFields`. Remova-o. Será retirado do SDK na 1.0.
+     */
     jitMode?: boolean;
 }
+/**
+ * Blocos estruturados que a sua interface sabe renderizar (`capabilities.blocks`). Valor que o BE
+ * não conhece sai em `ignoredFields` como `capabilities.blocks.<v>` + `not_supported` (aviso, não erro).
+ */
+type ClientBlockType = 'quick_replies' | 'html_report' | (string & {});
+/**
+ * O que a SUA tela sabe mostrar. O agente só oferece o que você declarar — sem declarar, nada é
+ * gerado e nada é cobrado. Não exige privilégio de API key.
+ */
+interface ClientCapabilities {
+    /**
+     * `quick_replies`: até 4 sugestões curtas de resposta ao fim do turno (o usuário toca e o texto
+     * vira a próxima mensagem). Chegam em `AgentResult.suggestions` (e no bloco `quick_replies` de
+     * `blocks`). O dono do agente pode desligá-las (`quick_replies_enabled`); o agente decide quando
+     * vale sugerir — nem todo turno traz sugestões.
+     *
+     * `html_report`: a tela renderiza HTML. Não cria bloco novo: o BE orienta o agente a entregar,
+     * quando couber, um documento HTML completo num bloco de código ```html dentro do `content`
+     * (BE `14d2a43c`, 19/10/2026). Só declare se você realmente renderiza HTML — senão o usuário
+     * recebe markup cru.
+     */
+    blocks?: ClientBlockType[];
+}
+/** A pessoa do outro lado da conversa. Só vale sob API key **admin/owner**. */
+interface ConsumerIdentity {
+    /**
+     * Identificador estável da pessoa no SEU sistema (memória por pessoa, denylist, gate de
+     * engajamento). Para continuar conversas que um webhook já gravava, use o MESMO valor que o
+     * webhook usava. Enviado como `consumer_key`.
+     */
+    key: string;
+    /**
+     * Nome para exibição no console da Zihin (lista de contatos). Enviado como
+     * `consumer_display_name`. Dado pessoal: mande só o que a operação precisa ver.
+     */
+    name?: string;
+}
 interface InvokeAgentParams {
     /** UUID do agente (path :agent_id). */
     agentId: string;
@@ -142,12 +192,41 @@ 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
      * valor que o webhook usava. Enviado como `consumer_key`.
      */
     consumerKey?: string;
+    /**
+     * A pessoa do outro lado: `{ key, name? }`. `consumer.key` é o mesmo que `consumerKey` (use um
+     * dos dois; se vierem os dois, têm de ser iguais). Só vale sob API key admin/owner.
+     */
+    consumer?: ConsumerIdentity;
+    /** O que a sua interface sabe renderizar — ex.: `{ blocks: ['quick_replies'] }`. */
+    capabilities?: ClientCapabilities;
     /**
      * Contexto estruturado que o **modelo lê** — bloco de plataforma junto da mensagem do usuário
      * (não no system prompt). **Fica gravado** com a mensagem (`declared_context`) e se repete em
@@ -228,10 +307,31 @@ interface AgentResult {
         type: string;
         [k: string]: unknown;
     }>;
+    /**
+     * Sugestões de resposta do turno (bloco `quick_replies`), já extraídas de `blocks`. Só vêm se
+     * você declarou `capabilities: { blocks: ['quick_replies'] }`. O texto de cada uma é o que o
+     * usuário "diz" ao tocá-la. Num turno só com sugestões, `content` vem vazio.
+     */
+    suggestions?: string[];
     iterations?: number;
     executionTimeMs?: number;
-    /** `execution_id` do turno (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`). */
@@ -246,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`). */
@@ -262,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`
@@ -286,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;
@@ -316,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;
@@ -327,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.
  *
@@ -367,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';
@@ -377,8 +500,15 @@ type AgentStreamChunk =
         type: string;
         [k: string]: unknown;
     }>;
+    /** Sugestões de resposta (bloco `quick_replies`), extraídas de `blocks`. */
+    suggestions?: string[];
     /** Resposta ENLATADA de um gate (handoff humano, denylist, sessão suspensa) — não do agente. */
     gated?: boolean;
+    executionId?: string;
+    clientMessageId?: string;
+    idempotentReplay?: boolean;
+    userMessageId?: string;
+    assistantMessageId?: string;
     data: unknown;
 } | {
     type: 'metrics';
@@ -500,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;
@@ -529,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;
@@ -811,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
@@ -965,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 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 };