@zihin/agent-client 0.4.1 → 0.6.0

package/dist/index.d.ts

@@ -4,7 +4,8 @@
  *
  * @module errors
  */
-type ZihinErrorKind = 'config' | 'auth' | 'trial_expired' | 'no_subscription' | 'quota_exceeded' | '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' | 'blocked' | 'unknown';
 /** Contexto opcional anexado a um erro para correlação/depuração. */
 interface ErrorMeta {
     /** Ex.: "POST llm.zihin.ai/api/v2/agents/abc/stream". */
@@ -23,6 +24,14 @@ interface ZihinErrorOptions extends ErrorMeta {
      * handoff) — é o handle que liga um erro daqui à execução no console/telemetria.
      */
     executionId?: string;
+    /** Sessão do turno — para o chamador retomar/inspecionar a conversa depois de um erro. */
+    sessionId?: string;
+    /**
+     * Só em `kind: 'timeout'` vindo do desfecho do turno (`done.timeout_clock`): qual relógio do BE
+     * encerrou o turno — `turn`, `first_signal`, `idle` ou `call`. Ausente num timeout de
+     * transporte/local, onde o turno pode nem ter terminado.
+     */
+    timeoutClock?: TimeoutClock;
 }
 declare class ZihinAgentError extends Error {
     readonly kind: ZihinErrorKind;
@@ -33,6 +42,8 @@ declare class ZihinAgentError extends Error {
     readonly attempts?: number;
     readonly endpoint?: string;
     readonly executionId?: string;
+    readonly sessionId?: string;
+    readonly timeoutClock?: TimeoutClock;
     constructor(kind: ZihinErrorKind, message: string, opts?: ZihinErrorOptions);
 }
 /**
@@ -109,7 +120,15 @@ interface Attachment {
 interface InvokeOptions {
     temperature?: number;
     maxTokens?: number;
-    /** Timeout específico desta chamada (ms); sobrepõe o do cliente. */
+    /**
+     * Teto do TURNO desta chamada (ms); sobrepõe o do cliente. Vai ao BE como `options.timeout_ms`
+     * e o BE o honra (desde 30/09/2026, contrato de tempo §4), mas **só para encurtar**: o prazo
+     * efetivo é `min(prazo da plataforma, pedido)` — no `/stream` o canal chat dá 150s. Pedir mais
+     * não alonga. Um turno cortado por esse prazo sai `TIMEOUT` com `timeoutClock: 'turn'`.
+     *
+     * O relógio do turno no BE só começa DEPOIS da carga (config, tools, MCP frio). O deadline
+     * local soma `DEADLINE_GRACE_MS` a este valor para ainda receber o desfecho do servidor.
+     */
     timeoutMs?: number;
     /** Just-in-time tool loading (Sprint 33). */
     jitMode?: boolean;
@@ -121,8 +140,35 @@ interface InvokeAgentParams {
     message?: string;
     /** Anexos multimodais. `message` OU `attachments` é obrigatório. */
     attachments?: Attachment[];
-    /** Continuidade de conversa (Supabase agent_sessions). */
+    /** Continuidade de conversa (Supabase agent_sessions). Não combina com `sessionFrom`. */
     sessionId?: 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;
+    /**
+     * Contexto estruturado que o **modelo lê** — bloco de plataforma junto da mensagem do usuário
+     * (não no system prompt). **Fica gravado** com a mensagem (`declared_context`) e se repete em
+     * todo turno; o BE redige segredos por nome de chave E por formato de valor (ex.: `sk-…`), o
+     * que pode alterar valores legítimos — ids que vão a tools ou ao `sessionFrom` ficam melhor em
+     * `bindings`. Plano, só escalares. Tools também o recebem. Só vale sob key admin/owner.
+     * ⚠️ Credencial não vai aqui nem em `bindings`: use um secret do tenant.
+     */
+    context?: Record<string, ContextValue>;
+    /**
+     * Valores que **só as tools** recebem — nunca vão ao prompt (ex.: id interno de fornecedor).
+     * Plano, só escalares; **nunca gravado** nem redigido (vive só no contexto das tools durante o
+     * turno). Só vale sob key admin/owner.
+     */
+    bindings?: Record<string, ContextValue>;
+    /**
+     * Deriva o `session_id` dos valores destes campos de `context ∪ bindings`, com a MESMA função
+     * do webhook (`derive: [campo]`) — o mesmo valor cai na mesma sessão pelos dois caminhos. Não
+     * combina com `sessionId`. O id derivado volta em `AgentResult.sessionId`.
+     */
+    sessionFrom?: string[];
     options?: InvokeOptions;
     metadata?: {
         traceId?: string;
@@ -137,6 +183,15 @@ interface InvokeAgentParams {
      */
     includeRaw?: boolean;
 }
+/** Valor aceito em `context`/`bindings`: plano e escalar (regra 8 do contrato de entrada). */
+type ContextValue = string | number | boolean | null;
+/** Campo que o BE recebeu e NÃO aplicou (evento `metadata.ignored_fields`). */
+interface IgnoredField {
+    /** Nome no fio (`context`, `bindings`, `session_from`, `consumer_key`, `options.temperature`…). */
+    field: string;
+    /** Motivo reportado pelo BE (ex.: papel da key insuficiente), quando houver. */
+    reason?: string;
+}
 interface Usage {
     inputTokens?: number;
     outputTokens?: number;
@@ -175,23 +230,71 @@ interface AgentResult {
     }>;
     iterations?: number;
     executionTimeMs?: number;
+    /** `execution_id` do turno (evento `metrics`) — handle de correlação no console/telemetria. */
+    executionId?: string;
+    /** Campos do pedido que o BE aplicou (`metadata.accepted_fields`). Ausente = backend antigo. */
+    acceptedFields?: string[];
+    /** Campos do pedido que o BE recebeu e ignorou (`metadata.ignored_fields`). */
+    ignoredFields?: IgnoredField[];
+    /**
+     * `true` = o `content` é a resposta ENLATADA de um gate da plataforma (conversa em atendimento
+     * humano, consumidor bloqueado, sessão suspensa), não do agente: nenhum modelo rodou. Em canal
+     * conversacional ela pode ser entregue à pessoa; numa automação, trate como "não respondido".
+     */
+    gated?: boolean;
+    /**
+     * Desfecho do turno, lido do `done` (`exitReason` do motor). `undefined` = backend antigo ou
+     * stream cortado antes do `done`. Só chegam aqui os desfechos cujo `content` é resposta
+     * (`COMPLETED`, `LENGTH`), o `PAUSED` (aprovação pendente ou agente pausado) e desfechos novos.
+     * `TIMEOUT`, `ERROR`, `CANCELLED`, `SUSPENDED` e os de bloqueio viram `ZihinAgentError` — o
+     * `content` desses turnos é a mensagem de falha/recusa do motor (`errorFromDoneChunk`).
+     */
+    outcome?: AgentOutcome;
+    /** `true` quando a resposta foi cortada pelo teto de saída do modelo (`done.truncated`). */
+    truncated?: boolean;
+    /** Motivo do corte quando `truncated` (ex.: `length`). */
+    finishReason?: string;
     /** Eventos SSE brutos coletados (para depuração / casos avançados). */
     raw: AgentStreamChunk[];
 }
+/**
+ * Desfecho do turno (`done.outcome` = `resolveTurnOutcome` do motor). `COMPLETED` e `LENGTH`
+ * contam como sucesso no BE (`isSuccessfulOutcome`); os demais valores são repassados como vêm.
+ * Aberto (`string & {}`) porque o BE pode acrescentar desfechos (ex.: os de bloqueio).
+ */
+type AgentOutcome = 'COMPLETED' | 'LENGTH' | 'TIMEOUT' | 'ERROR' | 'CANCELLED' | 'PAUSED' | 'SUSPENDED' | 'BUDGET_EXCEEDED' | 'QUOTA_EXCEEDED' | 'SESSION_BUSY' | 'CONFLICT' | (string & {});
+/**
+ * Qual relógio encerrou o turno (contrato de tempo §2): `turn` (prazo do turno, inclusive o
+ * `options.timeoutMs` pedido), `first_signal` (o provedor não começou a responder), `idle`
+ * (silêncio entre pedaços do stream do provedor) ou `call` (chamada ao modelo sem stream).
+ */
+type TimeoutClock = 'turn' | 'first_signal' | 'idle' | 'call' | (string & {});
 /**
  * Chunk normalizado emitido por `streamAgent`. Mapeia os tipos de evento SSE do BE:
  * metadata, status, attachments, phase, thinking, tool, action_proposed, token,
  * warning, response, metrics.
  */
-type AgentStreamChunk = {
+type AgentStreamChunk = 
+/**
+ * Abertura do stream. `acceptedFields`/`ignoredFields` dizem o que o BE fez com cada campo do
+ * pedido (ausentes = backend anterior ao contrato de entrada). Se o chamador mandou
+ * `context`/`bindings`/`sessionFrom` e o BE não os aceitou, o `streamAgent` lança
+ * `ZihinAgentError('config')` ANTES de entregar este chunk — nunca segue em silêncio.
+ */
+{
     type: 'metadata';
     requestId?: string;
     agentId?: string;
     sessionId?: string;
+    acceptedFields?: string[];
+    ignoredFields?: IgnoredField[];
     data: unknown;
-} | {
+}
+/** `blocked` = motivo do bloqueio do turno (`agent_paused`, `budget_exceeded`…), quando houver. */
+ | {
     type: 'status';
     phase?: string;
+    blocked?: string;
     data: unknown;
 } | {
     type: 'attachments';
@@ -250,9 +353,20 @@ type AgentStreamChunk = {
     sessionId?: string;
     data: unknown;
 }
-/** Fim LIMPO do stream (`utils/sse.js:92`). Sem ele, o stream foi cortado no meio. */
+/**
+ * Fim LIMPO do stream (`utils/sse.js`). Sem ele, o stream foi cortado no meio. Carrega o
+ * desfecho do turno: `{ outcome, timed_out?, timeout_clock?, truncated?, finish_reason? }`
+ * (aditivo — backend antigo manda `{}`). Um turno que o motor encerrou por tempo chega aqui
+ * com `outcome: 'TIMEOUT'` (idem ERROR e os bloqueios), DEPOIS de um `response` cujo `content`
+ * é a mensagem de falha — use `errorFromDoneChunk` para não publicá-lo como resposta.
+ */
  | {
     type: 'done';
+    outcome?: AgentOutcome;
+    timedOut?: boolean;
+    timeoutClock?: TimeoutClock;
+    truncated?: boolean;
+    finishReason?: string;
     data: unknown;
 } | {
     type: 'response';
@@ -263,6 +377,8 @@ type AgentStreamChunk = {
         type: string;
         [k: string]: unknown;
     }>;
+    /** Resposta ENLATADA de um gate (handoff humano, denylist, sessão suspensa) — não do agente. */
+    gated?: boolean;
     data: unknown;
 } | {
     type: 'metrics';
@@ -270,6 +386,7 @@ type AgentStreamChunk = {
     model?: string;
     iterations?: number;
     executionTimeMs?: number;
+    executionId?: string;
     data: unknown;
 } | {
     type: 'unknown';
@@ -589,8 +706,13 @@ type TimeoutOperation = keyof typeof OPERATION_TIMEOUT_MS;
  * Folga somada ao `options.timeoutMs` do chamador para formar o deadline LOCAL. O mesmo número vai
  * ao BE como `options.timeout_ms` (o teto que ele deve respeitar); sem folga, os dois relógios
  * disparam juntos e o erro do servidor — que tem request_id — perde a corrida para o nosso abort.
+ *
+ * 30s, não 10s: o relógio do turno no BE só começa DEPOIS da carga (config, tools, gates — um MCP
+ * frio leva dezenas de segundos), então o tempo de parede visto daqui é `carga + prazo` (contrato
+ * de tempo §4). Com 10s, um `timeoutMs: 60000` num agente com MCP abortava aos 70s e trocava o
+ * `done { outcome: 'TIMEOUT' }` do servidor por um abort cego.
  */
-declare const DEADLINE_GRACE_MS = 10000;
+declare const DEADLINE_GRACE_MS = 30000;
 
 /**
  * Listagem de agentes do tenant (GET /api/v2/agents). Alimenta o dropdown do nó n8n (#17)
@@ -689,7 +811,7 @@ 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';
+declare function classifyStreamErrorKind(code: string, timedOut?: boolean): 'timeout' | 'server' | 'config';
 /**
  * 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
@@ -698,6 +820,28 @@ declare function classifyStreamErrorKind(code: string, timedOut?: boolean): 'tim
 declare function errorFromStreamChunk(chunk: Extract<AgentStreamChunk, {
     type: 'error';
 }>): ZihinAgentError;
+/**
+ * Converte o `done` de um turno que NÃO produziu resposta num `ZihinAgentError`; devolve
+ * `undefined` quando o `content` é resposta. Mesma regra do `invokeAgent`, exportada para quem
+ * consome `streamAgent` direto (o Paperclip) não reimplementá-la.
+ *
+ * Por que erro e não um campo no resultado: nesses turnos o BE já emitiu um `response` com a
+ * mensagem de falha do motor em `content` (contrato de tempo §6). Como campo, cada shell teria
+ * de lembrar de checá-lo — e o que esquecesse publicaria a falha como resposta, que é o defeito
+ * que isto fecha (#81). Como erro, o caminho seguro é o default.
+ *
+ * TIMEOUT: `outcome: 'TIMEOUT'` é a fonte primária; `timed_out: true` sozinho também conta (o BE
+ * só o emite com TIMEOUT). Vira `kind: 'timeout'`, `code: 'TURN_TIMEOUT'`, com `timeoutClock`.
+ * Nenhum é retentável por default: o turno pode ter executado tools com efeito colateral
+ * (exceção: `SESSION_BUSY`, em que o turno nem começou).
+ */
+declare function errorFromDoneChunk(chunk: Extract<AgentStreamChunk, {
+    type: 'done';
+}>, ctx?: {
+    executionId?: string;
+    sessionId?: string;
+    blocked?: string;
+}): ZihinAgentError | undefined;
 
 /**
  * Security utilities — portado de n8n-nodes-zihin/src/utils/security.ts (zero-dep).
@@ -821,4 +965,4 @@ declare function signRequest(payload: string, secretKey: string, timestamp?: num
  */
 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 };
+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 };