@zihin/agent-client 0.4.1 → 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Aionz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -166,6 +166,29 @@ parcial. Se foi timeout ou não vem do campo **explícito `error.timed_out`** do
 (`/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`.
 
+### Turno encerrado por tempo (0.5)
+
+Quando é o **motor** que encerra o turno por tempo, o BE não manda `error`: manda um `response` com a
+mensagem de falha em `content` e fecha com `done { outcome: 'TIMEOUT', timeout_clock }`. O núcleo lê
+o `done` antes do `response` e **lança** `ZihinAgentError` com `kind: 'timeout'`,
+`code: 'TURN_TIMEOUT'`, `timeoutClock` (`turn` · `first_signal` · `idle` · `call`), `executionId` e
+`sessionId` — não retentável, porque o turno pode ter executado tools. Quem consome `streamAgent`
+direto aplica a mesma regra com `errorFromDoneChunk(chunk, { executionId, sessionId })`.
+
+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
+`status.blocked` (gate da plataforma) também sai `blocked`, com o motivo em `code`
+(`ownership_denied` → `not_found`).
+
+Resposta **enlatada** de gate (atendimento humano, denylist, sessão suspensa) não lança: volta com
+`AgentResult.gated: true` — nenhum modelo rodou. Num canal conversacional ela pode ir à pessoa; numa
+automação, trate como "não respondido".
+
+`AgentResult.outcome` traz o desfecho dos turnos que respondem: `COMPLETED`, `LENGTH` (com
+`truncated`/`finishReason`), `PAUSED` de aprovação pendente e desfechos novos. `outcome` ausente = backend antigo.
+
 ## Dropdown de agentes
 
 ```ts
@@ -203,6 +226,10 @@ status, virariam "troque a key" ou "tente de novo". Têm `kind` próprio e **nun
 (`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.
 
+A exceção é o 403 com `details.reason: 'AGENT_ACCESS_DENIED'`: o agente não existe, está inativo ou
+é de outro workspace (o BE não distingue, de propósito). Ele sai como `kind: 'not_found'` — o
+problema é o `agentId`, não a key.
+
 `ZihinAgentError.executionId` vem preenchido quando o BE o entrega (sucesso e erro) — é o handle para
 correlacionar com o console.
 
@@ -213,7 +240,10 @@ correlacionar com o console.
   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
+  `timeout_ms`, que o BE **honra só para encurtar** (`min(prazo da plataforma, pedido)`; o chat dá
+  150s). O deadline local fica 30s acima (`DEADLINE_GRACE_MS`), porque o relógio do turno no BE só
+  começa depois da carga de tools/MCP. Em serverless (Lambda, Vercel, Zapier…), use `timeoutMs` ao menos 30s
+  abaixo do limite da plataforma, ou a plataforma mata a função antes do erro local. 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

package/dist/index.d.mts

@@ -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;
@@ -175,9 +194,41 @@ interface AgentResult {
     }>;
     iterations?: number;
     executionTimeMs?: number;
+    /** `execution_id` do turno (evento `metrics`) — handle de correlação no console/telemetria. */
+    executionId?: string;
+    /**
+     * `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,
@@ -189,9 +240,12 @@ type AgentStreamChunk = {
     agentId?: string;
     sessionId?: string;
     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 +304,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 +328,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 +337,7 @@ type AgentStreamChunk = {
     model?: string;
     iterations?: number;
     executionTimeMs?: number;
+    executionId?: string;
     data: unknown;
 } | {
     type: 'unknown';
@@ -589,8 +657,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)
@@ -698,6 +771,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 +916,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 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 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 };

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;
@@ -175,9 +194,41 @@ interface AgentResult {
     }>;
     iterations?: number;
     executionTimeMs?: number;
+    /** `execution_id` do turno (evento `metrics`) — handle de correlação no console/telemetria. */
+    executionId?: string;
+    /**
+     * `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,
@@ -189,9 +240,12 @@ type AgentStreamChunk = {
     agentId?: string;
     sessionId?: string;
     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 +304,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 +328,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 +337,7 @@ type AgentStreamChunk = {
     model?: string;
     iterations?: number;
     executionTimeMs?: number;
+    executionId?: string;
     data: unknown;
 } | {
     type: 'unknown';
@@ -589,8 +657,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)
@@ -698,6 +771,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 +916,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 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 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 };

package/dist/index.js

@@ -28,6 +28,7 @@ __export(index_exports, {
   ZihinAgentError: () => ZihinAgentError,
   classifyStreamErrorKind: () => classifyStreamErrorKind,
   createClient: () => createClient,
+  errorFromDoneChunk: () => errorFromDoneChunk,
   errorFromStreamChunk: () => errorFromStreamChunk,
   isCommercialBlock: () => isCommercialBlock,
   sanitizeApiError: () => sanitizeApiError,
@@ -46,6 +47,12 @@ function utf8Len(s) {
 function rec(x) {
   return x && typeof x === "object" ? x : {};
 }
+function safeId(x) {
+  return typeof x === "string" && /^[\w.:-]{1,128}$/.test(x) ? x : void 0;
+}
+function safeLabel(x) {
+  return typeof x === "string" && /^[A-Za-z0-9_]{1,64}$/.test(x) ? x : void 0;
+}
 function str(x) {
   return typeof x === "string" ? x : void 0;
 }
@@ -71,8 +78,13 @@ var RUNNING_STATUSES = /* @__PURE__ */ new Set([
   "waiting",
   "retrying",
   "scheduled",
-  "awaiting_approval"
+  "awaiting_approval",
   // HITL: turno pausado esperando decisão humana não terminou
+  // Estados VIVOS reais do backend (zihin-agent-builder `TaskService.LIVE_STATUSES` e
+  // `agent_executions.status`): sem eles, uma task/execução pausada ou aguardando input
+  // era lida como TERMINAL e o polling parava com o trabalho ainda em andamento.
+  "paused",
+  "awaiting_input"
 ]);
 function isTerminalStatus(status) {
   return !RUNNING_STATUSES.has(status.toLowerCase().replace(/-/g, "_"));
@@ -267,6 +279,9 @@ var ERROR_CODE_MAP = {
   INSUFFICIENT_CREDITS: "Insufficient credits. Please check your account balance.",
   CONTEXT_LENGTH_EXCEEDED: "The input exceeds the model context length limit.",
   AGENT_NOT_FOUND: "Agent not found or not active for this tenant.",
+  // Nome novo do `AGENT_NOT_FOUND` (zihin-agent-builder#561, fatia B). `AGENT_ERROR` virou
+  // `INTERNAL_ERROR`, que já está acima.
+  NOT_FOUND: "Resource not found \u2014 check the ID (agent, trigger or execution) and that it belongs to this workspace.",
   // Bloqueios comerciais. As mensagens do BE vêm em português e estes shells são em inglês;
   // além disso cada caso tem uma ação DIFERENTE, e o texto precisa dizer qual.
   TRIAL_EXPIRED: "Your Zihin trial has ended. Upgrade the plan to keep invoking agents \u2014 the API key is fine.",
@@ -337,6 +352,8 @@ var ZihinAgentError = class _ZihinAgentError extends Error {
     this.code = opts.code;
     this.requestId = opts.requestId;
     this.executionId = opts.executionId;
+    this.sessionId = opts.sessionId;
+    this.timeoutClock = opts.timeoutClock;
     this.attempts = opts.attempts;
     this.endpoint = opts.endpoint;
     this.retryable = opts.retryable ?? (kind === "rate_limit" || kind === "server" || kind === "network");
@@ -371,7 +388,7 @@ function commercialKind(body) {
 }
 function extractRequestId(body) {
   const b = rec(body);
-  return str(b.request_id) ?? str(b.requestId) ?? str(rec(b.error).request_id) ?? str(rec(b.meta).request_id);
+  return safeId(b.request_id) ?? safeId(b.requestId) ?? safeId(rec(b.error).request_id) ?? safeId(rec(b.meta).request_id);
 }
 function errorFromResponse(status, body, meta = {}) {
   const sanitized = sanitizeApiError(body);
@@ -381,7 +398,7 @@ function errorFromResponse(status, body, meta = {}) {
     status,
     code,
     requestId: extractRequestId(body),
-    executionId: str(rec(body).execution_id),
+    executionId: safeId(rec(body).execution_id),
     ...meta
   };
   const commercial = commercialKind(body);
@@ -392,6 +409,12 @@ function errorFromResponse(status, body, meta = {}) {
     });
   }
   if (status === 401) return new ZihinAgentError("auth", message || "Authentication failed.", base);
+  if (status === 403 && str(rec(rec(rec(body).error).details).reason) === "AGENT_ACCESS_DENIED")
+    return new ZihinAgentError(
+      "not_found",
+      "Agent not found, inactive, or not accessible with this API key \u2014 check the agent ID and that the key belongs to the same Zihin workspace.",
+      { ...base, retryable: false }
+    );
   if (status === 403)
     return new ZihinAgentError(
       "auth",
@@ -441,7 +464,7 @@ var OPERATION_TIMEOUT_MS = Object.freeze({
   dispatch: 26e4,
   short: 35e3
 });
-var DEADLINE_GRACE_MS = 1e4;
+var DEADLINE_GRACE_MS = 3e4;
 var RETRY_OVERHEAD_MS = 6e4;
 var MIN_TIMEOUT_MS = 1e3;
 var MAX_TIMEOUT_MS = 9e5;
@@ -893,13 +916,13 @@ function mapEvent(e) {
     case "metadata":
       return {
         type: "metadata",
-        requestId: str(d.request_id),
+        requestId: safeId(d.request_id),
         agentId: str(d.agent_id),
-        sessionId: str(d.session_id),
+        sessionId: safeId(d.session_id),
         data: e.data
       };
     case "status":
-      return { type: "status", phase: str(d.phase), data: e.data };
+      return { type: "status", phase: str(d.phase), blocked: safeLabel(d.blocked), data: e.data };
     case "attachments":
       return { type: "attachments", data: e.data };
     case "phase":
@@ -921,16 +944,24 @@ function mapEvent(e) {
     case "warning":
       return { type: "warning", message: str(d.message), data: e.data };
     case "session":
-      return { type: "session", sessionId: str(d.session_id), data: e.data };
+      return { type: "session", sessionId: safeId(d.session_id), data: e.data };
     case "done":
-      return { type: "done", data: e.data };
+      return {
+        type: "done",
+        outcome: safeLabel(d.outcome),
+        timedOut: typeof d.timed_out === "boolean" ? d.timed_out : void 0,
+        timeoutClock: safeLabel(d.timeout_clock),
+        truncated: typeof d.truncated === "boolean" ? d.truncated : void 0,
+        finishReason: str(d.finish_reason),
+        data: e.data
+      };
     case "error": {
       const err = rec(d.error);
       return {
         type: "error",
-        code: str(err.code),
+        code: safeLabel(err.code),
         message: str(err.message),
-        requestId: str(err.request_id),
+        requestId: safeId(err.request_id),
         timedOut: typeof err.timed_out === "boolean" ? err.timed_out : void 0,
         data: e.data
       };
@@ -939,7 +970,8 @@ function mapEvent(e) {
       return {
         type: "response",
         content: str(d.content) ?? "",
-        sessionId: str(d.session_id),
+        sessionId: safeId(d.session_id),
+        gated: d.gated === true ? true : void 0,
         sources: Array.isArray(d.sources) ? d.sources : void 0,
         blocks: Array.isArray(d.blocks) ? d.blocks : void 0,
         data: e.data
@@ -952,6 +984,7 @@ function mapEvent(e) {
         model: str(modelConfig.model) ?? str(d.model),
         iterations: num(d.iterations),
         executionTimeMs: num(d.execution_time_ms),
+        executionId: safeId(d.execution_id),
         data: e.data
       };
     }
@@ -1064,6 +1097,77 @@ function errorFromStreamChunk(chunk) {
     retryable: false
   });
 }
+var FAILED_OUTCOMES = {
+  ERROR: { kind: "server", message: "The agent turn failed on the server; its text is the engine failure notice, not an answer." },
+  // `server`, não `aborted`: `aborted` é o cancelamento do PRÓPRIO chamador, que `onError` manda
+  // filtrar — um cancelamento feito pelo operador sumiria junto.
+  CANCELLED: { kind: "server", message: "The agent turn was cancelled on the server (by an operator or a platform guard)." },
+  // Modo processo drenando/encerrando; o motor retoma depois. Nenhum canal atual o produz.
+  SUSPENDED: { kind: "blocked", message: "The agent turn was suspended by the server and did not answer; retry later." },
+  BUDGET_EXCEEDED: { kind: "blocked", message: "The agent's spending cap was reached; raise the agent budget to keep invoking it." },
+  QUOTA_EXCEEDED: { kind: "quota_exceeded", message: "Your Zihin token quota is exhausted. Upgrade the plan or wait for the next cycle." },
+  SESSION_BUSY: {
+    kind: "blocked",
+    message: "Another turn is still running in this session; retry after it finishes.",
+    retryable: true
+  },
+  // Hoje a rota manda CONFLICT como `event: error` (não chega ao `done`); mapeado por defesa.
+  CONFLICT: {
+    kind: "blocked",
+    message: "The declared consumer identity does not match the one already bound to this session."
+  }
+};
+var PAUSED_BLOCKS = /* @__PURE__ */ new Set(["agent_paused", "agent_archived"]);
+var ERROR_BLOCKS = {
+  ownership_denied: {
+    kind: "not_found",
+    message: "Session not found for this API key \u2014 start a new conversation (omit sessionId) instead of reusing this one."
+  },
+  session_load_failed: { kind: "blocked", message: "The server could not load this conversation right now; retry shortly.", retryable: true },
+  approval_resolve_failed: { kind: "blocked", message: "The server could not route the required approval right now; retry shortly.", retryable: true },
+  approval_no_approver: { kind: "blocked", message: "This action requires approval, but the approval policy has no approver configured." },
+  blocked_schedule: { kind: "blocked", message: "The agent is outside its allowed schedule (security policy)." },
+  owner_inactive: { kind: "blocked", message: "The agent's owner is inactive; the agent cannot be invoked." }
+};
+function own(table, key) {
+  return key !== void 0 && Object.prototype.hasOwnProperty.call(table, key) ? table[key] : void 0;
+}
+function errorFromDoneChunk(chunk, ctx = {}) {
+  const meta = { executionId: ctx.executionId, sessionId: ctx.sessionId };
+  const blockedReason = safeLabel(ctx.blocked);
+  if (chunk.outcome === "TIMEOUT" || chunk.timedOut === true) {
+    const clock = chunk.timeoutClock;
+    const what = clock === "turn" ? "the turn deadline" : clock === "first_signal" ? "the model provider did not start responding in time" : clock === "idle" ? "the model provider stream went silent" : clock === "call" ? "the model call took too long" : "a server-side clock";
+    return new ZihinAgentError("timeout", `The agent turn timed out (${what}).`, {
+      ...meta,
+      code: "TURN_TIMEOUT",
+      retryable: false,
+      timeoutClock: clock
+    });
+  }
+  if (chunk.outcome === "PAUSED" && blockedReason && PAUSED_BLOCKS.has(blockedReason)) {
+    return new ZihinAgentError("blocked", "The agent is paused or archived and did not answer.", {
+      ...meta,
+      code: "PAUSED",
+      retryable: false
+    });
+  }
+  if (chunk.outcome === "ERROR" && blockedReason) {
+    const gate = own(ERROR_BLOCKS, blockedReason);
+    return new ZihinAgentError(gate?.kind ?? "blocked", gate?.message ?? `The agent turn was blocked by the server (${blockedReason}).`, {
+      ...meta,
+      code: blockedReason.toUpperCase(),
+      retryable: gate?.retryable ?? false
+    });
+  }
+  const failed = own(FAILED_OUTCOMES, chunk.outcome);
+  if (!failed) return void 0;
+  return new ZihinAgentError(failed.kind, failed.message, {
+    ...meta,
+    code: chunk.outcome,
+    retryable: failed.retryable ?? false
+  });
+}
 async function invokeAgent(cfg, params) {
   const raw = [];
   const keepRaw = params.includeRaw === true;
@@ -1071,7 +1175,8 @@ async function invokeAgent(cfg, params) {
   let metricsChunk;
   let metadataSessionId;
   let mintedSessionId;
-  let cleanEnd = false;
+  let doneChunk;
+  let blocked;
   let tokenBuffer = "";
   for await (const chunk of streamAgent(cfg, params)) {
     if (keepRaw) raw.push(chunk);
@@ -1083,8 +1188,14 @@ async function invokeAgent(cfg, params) {
     else if (chunk.type === "token") tokenBuffer += chunk.content;
     else if (chunk.type === "metadata" && chunk.sessionId) metadataSessionId = chunk.sessionId;
     else if (chunk.type === "session" && chunk.sessionId) mintedSessionId = chunk.sessionId;
-    else if (chunk.type === "done") cleanEnd = true;
-  }
+    else if (chunk.type === "done") doneChunk = chunk;
+    else if (chunk.type === "status" && chunk.blocked) blocked = chunk.blocked;
+  }
+  const sessionId = mintedSessionId ?? responseChunk?.sessionId ?? metadataSessionId ?? params.sessionId;
+  const executionId = metricsChunk?.executionId;
+  const outcomeError = doneChunk && errorFromDoneChunk(doneChunk, { executionId, sessionId, blocked });
+  if (outcomeError) throw outcomeError;
+  const cleanEnd = doneChunk !== void 0;
   if (!responseChunk) {
     if (cleanEnd) {
       throw new ZihinAgentError("protocol", "Stream ended (done) without a `response` event.");
@@ -1093,11 +1204,12 @@ async function invokeAgent(cfg, params) {
       return {
         content: tokenBuffer,
         contentSource: "tokens",
-        sessionId: mintedSessionId ?? metadataSessionId ?? params.sessionId,
+        sessionId,
         usage: metricsChunk?.usage,
         model: metricsChunk?.model,
         iterations: metricsChunk?.iterations,
         executionTimeMs: metricsChunk?.executionTimeMs,
+        executionId,
         raw
       };
     }
@@ -1106,13 +1218,18 @@ async function invokeAgent(cfg, params) {
   return {
     content: responseChunk.content,
     contentSource: "response",
-    sessionId: mintedSessionId ?? responseChunk.sessionId ?? metadataSessionId ?? params.sessionId,
+    sessionId,
     model: metricsChunk?.model,
     usage: metricsChunk?.usage,
     sources: responseChunk.sources,
     blocks: responseChunk.blocks,
+    gated: responseChunk.gated,
     iterations: metricsChunk?.iterations,
     executionTimeMs: metricsChunk?.executionTimeMs,
+    executionId,
+    outcome: doneChunk?.outcome,
+    truncated: doneChunk?.truncated,
+    finishReason: doneChunk?.finishReason,
     raw
   };
 }
@@ -1719,6 +1836,7 @@ function signRequest(payload, secretKey, timestamp) {
   ZihinAgentError,
   classifyStreamErrorKind,
   createClient,
+  errorFromDoneChunk,
   errorFromStreamChunk,
   isCommercialBlock,
   sanitizeApiError,

package/dist/index.mjs

@@ -13,6 +13,12 @@ function utf8Len(s) {
 function rec(x) {
   return x && typeof x === "object" ? x : {};
 }
+function safeId(x) {
+  return typeof x === "string" && /^[\w.:-]{1,128}$/.test(x) ? x : void 0;
+}
+function safeLabel(x) {
+  return typeof x === "string" && /^[A-Za-z0-9_]{1,64}$/.test(x) ? x : void 0;
+}
 function str(x) {
   return typeof x === "string" ? x : void 0;
 }
@@ -38,8 +44,13 @@ var RUNNING_STATUSES = /* @__PURE__ */ new Set([
   "waiting",
   "retrying",
   "scheduled",
-  "awaiting_approval"
+  "awaiting_approval",
   // HITL: turno pausado esperando decisão humana não terminou
+  // Estados VIVOS reais do backend (zihin-agent-builder `TaskService.LIVE_STATUSES` e
+  // `agent_executions.status`): sem eles, uma task/execução pausada ou aguardando input
+  // era lida como TERMINAL e o polling parava com o trabalho ainda em andamento.
+  "paused",
+  "awaiting_input"
 ]);
 function isTerminalStatus(status) {
   return !RUNNING_STATUSES.has(status.toLowerCase().replace(/-/g, "_"));
@@ -234,6 +245,9 @@ var ERROR_CODE_MAP = {
   INSUFFICIENT_CREDITS: "Insufficient credits. Please check your account balance.",
   CONTEXT_LENGTH_EXCEEDED: "The input exceeds the model context length limit.",
   AGENT_NOT_FOUND: "Agent not found or not active for this tenant.",
+  // Nome novo do `AGENT_NOT_FOUND` (zihin-agent-builder#561, fatia B). `AGENT_ERROR` virou
+  // `INTERNAL_ERROR`, que já está acima.
+  NOT_FOUND: "Resource not found \u2014 check the ID (agent, trigger or execution) and that it belongs to this workspace.",
   // Bloqueios comerciais. As mensagens do BE vêm em português e estes shells são em inglês;
   // além disso cada caso tem uma ação DIFERENTE, e o texto precisa dizer qual.
   TRIAL_EXPIRED: "Your Zihin trial has ended. Upgrade the plan to keep invoking agents \u2014 the API key is fine.",
@@ -304,6 +318,8 @@ var ZihinAgentError = class _ZihinAgentError extends Error {
     this.code = opts.code;
     this.requestId = opts.requestId;
     this.executionId = opts.executionId;
+    this.sessionId = opts.sessionId;
+    this.timeoutClock = opts.timeoutClock;
     this.attempts = opts.attempts;
     this.endpoint = opts.endpoint;
     this.retryable = opts.retryable ?? (kind === "rate_limit" || kind === "server" || kind === "network");
@@ -338,7 +354,7 @@ function commercialKind(body) {
 }
 function extractRequestId(body) {
   const b = rec(body);
-  return str(b.request_id) ?? str(b.requestId) ?? str(rec(b.error).request_id) ?? str(rec(b.meta).request_id);
+  return safeId(b.request_id) ?? safeId(b.requestId) ?? safeId(rec(b.error).request_id) ?? safeId(rec(b.meta).request_id);
 }
 function errorFromResponse(status, body, meta = {}) {
   const sanitized = sanitizeApiError(body);
@@ -348,7 +364,7 @@ function errorFromResponse(status, body, meta = {}) {
     status,
     code,
     requestId: extractRequestId(body),
-    executionId: str(rec(body).execution_id),
+    executionId: safeId(rec(body).execution_id),
     ...meta
   };
   const commercial = commercialKind(body);
@@ -359,6 +375,12 @@ function errorFromResponse(status, body, meta = {}) {
     });
   }
   if (status === 401) return new ZihinAgentError("auth", message || "Authentication failed.", base);
+  if (status === 403 && str(rec(rec(rec(body).error).details).reason) === "AGENT_ACCESS_DENIED")
+    return new ZihinAgentError(
+      "not_found",
+      "Agent not found, inactive, or not accessible with this API key \u2014 check the agent ID and that the key belongs to the same Zihin workspace.",
+      { ...base, retryable: false }
+    );
   if (status === 403)
     return new ZihinAgentError(
       "auth",
@@ -408,7 +430,7 @@ var OPERATION_TIMEOUT_MS = Object.freeze({
   dispatch: 26e4,
   short: 35e3
 });
-var DEADLINE_GRACE_MS = 1e4;
+var DEADLINE_GRACE_MS = 3e4;
 var RETRY_OVERHEAD_MS = 6e4;
 var MIN_TIMEOUT_MS = 1e3;
 var MAX_TIMEOUT_MS = 9e5;
@@ -860,13 +882,13 @@ function mapEvent(e) {
     case "metadata":
       return {
         type: "metadata",
-        requestId: str(d.request_id),
+        requestId: safeId(d.request_id),
         agentId: str(d.agent_id),
-        sessionId: str(d.session_id),
+        sessionId: safeId(d.session_id),
         data: e.data
       };
     case "status":
-      return { type: "status", phase: str(d.phase), data: e.data };
+      return { type: "status", phase: str(d.phase), blocked: safeLabel(d.blocked), data: e.data };
     case "attachments":
       return { type: "attachments", data: e.data };
     case "phase":
@@ -888,16 +910,24 @@ function mapEvent(e) {
     case "warning":
       return { type: "warning", message: str(d.message), data: e.data };
     case "session":
-      return { type: "session", sessionId: str(d.session_id), data: e.data };
+      return { type: "session", sessionId: safeId(d.session_id), data: e.data };
     case "done":
-      return { type: "done", data: e.data };
+      return {
+        type: "done",
+        outcome: safeLabel(d.outcome),
+        timedOut: typeof d.timed_out === "boolean" ? d.timed_out : void 0,
+        timeoutClock: safeLabel(d.timeout_clock),
+        truncated: typeof d.truncated === "boolean" ? d.truncated : void 0,
+        finishReason: str(d.finish_reason),
+        data: e.data
+      };
     case "error": {
       const err = rec(d.error);
       return {
         type: "error",
-        code: str(err.code),
+        code: safeLabel(err.code),
         message: str(err.message),
-        requestId: str(err.request_id),
+        requestId: safeId(err.request_id),
         timedOut: typeof err.timed_out === "boolean" ? err.timed_out : void 0,
         data: e.data
       };
@@ -906,7 +936,8 @@ function mapEvent(e) {
       return {
         type: "response",
         content: str(d.content) ?? "",
-        sessionId: str(d.session_id),
+        sessionId: safeId(d.session_id),
+        gated: d.gated === true ? true : void 0,
         sources: Array.isArray(d.sources) ? d.sources : void 0,
         blocks: Array.isArray(d.blocks) ? d.blocks : void 0,
         data: e.data
@@ -919,6 +950,7 @@ function mapEvent(e) {
         model: str(modelConfig.model) ?? str(d.model),
         iterations: num(d.iterations),
         executionTimeMs: num(d.execution_time_ms),
+        executionId: safeId(d.execution_id),
         data: e.data
       };
     }
@@ -1031,6 +1063,77 @@ function errorFromStreamChunk(chunk) {
     retryable: false
   });
 }
+var FAILED_OUTCOMES = {
+  ERROR: { kind: "server", message: "The agent turn failed on the server; its text is the engine failure notice, not an answer." },
+  // `server`, não `aborted`: `aborted` é o cancelamento do PRÓPRIO chamador, que `onError` manda
+  // filtrar — um cancelamento feito pelo operador sumiria junto.
+  CANCELLED: { kind: "server", message: "The agent turn was cancelled on the server (by an operator or a platform guard)." },
+  // Modo processo drenando/encerrando; o motor retoma depois. Nenhum canal atual o produz.
+  SUSPENDED: { kind: "blocked", message: "The agent turn was suspended by the server and did not answer; retry later." },
+  BUDGET_EXCEEDED: { kind: "blocked", message: "The agent's spending cap was reached; raise the agent budget to keep invoking it." },
+  QUOTA_EXCEEDED: { kind: "quota_exceeded", message: "Your Zihin token quota is exhausted. Upgrade the plan or wait for the next cycle." },
+  SESSION_BUSY: {
+    kind: "blocked",
+    message: "Another turn is still running in this session; retry after it finishes.",
+    retryable: true
+  },
+  // Hoje a rota manda CONFLICT como `event: error` (não chega ao `done`); mapeado por defesa.
+  CONFLICT: {
+    kind: "blocked",
+    message: "The declared consumer identity does not match the one already bound to this session."
+  }
+};
+var PAUSED_BLOCKS = /* @__PURE__ */ new Set(["agent_paused", "agent_archived"]);
+var ERROR_BLOCKS = {
+  ownership_denied: {
+    kind: "not_found",
+    message: "Session not found for this API key \u2014 start a new conversation (omit sessionId) instead of reusing this one."
+  },
+  session_load_failed: { kind: "blocked", message: "The server could not load this conversation right now; retry shortly.", retryable: true },
+  approval_resolve_failed: { kind: "blocked", message: "The server could not route the required approval right now; retry shortly.", retryable: true },
+  approval_no_approver: { kind: "blocked", message: "This action requires approval, but the approval policy has no approver configured." },
+  blocked_schedule: { kind: "blocked", message: "The agent is outside its allowed schedule (security policy)." },
+  owner_inactive: { kind: "blocked", message: "The agent's owner is inactive; the agent cannot be invoked." }
+};
+function own(table, key) {
+  return key !== void 0 && Object.prototype.hasOwnProperty.call(table, key) ? table[key] : void 0;
+}
+function errorFromDoneChunk(chunk, ctx = {}) {
+  const meta = { executionId: ctx.executionId, sessionId: ctx.sessionId };
+  const blockedReason = safeLabel(ctx.blocked);
+  if (chunk.outcome === "TIMEOUT" || chunk.timedOut === true) {
+    const clock = chunk.timeoutClock;
+    const what = clock === "turn" ? "the turn deadline" : clock === "first_signal" ? "the model provider did not start responding in time" : clock === "idle" ? "the model provider stream went silent" : clock === "call" ? "the model call took too long" : "a server-side clock";
+    return new ZihinAgentError("timeout", `The agent turn timed out (${what}).`, {
+      ...meta,
+      code: "TURN_TIMEOUT",
+      retryable: false,
+      timeoutClock: clock
+    });
+  }
+  if (chunk.outcome === "PAUSED" && blockedReason && PAUSED_BLOCKS.has(blockedReason)) {
+    return new ZihinAgentError("blocked", "The agent is paused or archived and did not answer.", {
+      ...meta,
+      code: "PAUSED",
+      retryable: false
+    });
+  }
+  if (chunk.outcome === "ERROR" && blockedReason) {
+    const gate = own(ERROR_BLOCKS, blockedReason);
+    return new ZihinAgentError(gate?.kind ?? "blocked", gate?.message ?? `The agent turn was blocked by the server (${blockedReason}).`, {
+      ...meta,
+      code: blockedReason.toUpperCase(),
+      retryable: gate?.retryable ?? false
+    });
+  }
+  const failed = own(FAILED_OUTCOMES, chunk.outcome);
+  if (!failed) return void 0;
+  return new ZihinAgentError(failed.kind, failed.message, {
+    ...meta,
+    code: chunk.outcome,
+    retryable: failed.retryable ?? false
+  });
+}
 async function invokeAgent(cfg, params) {
   const raw = [];
   const keepRaw = params.includeRaw === true;
@@ -1038,7 +1141,8 @@ async function invokeAgent(cfg, params) {
   let metricsChunk;
   let metadataSessionId;
   let mintedSessionId;
-  let cleanEnd = false;
+  let doneChunk;
+  let blocked;
   let tokenBuffer = "";
   for await (const chunk of streamAgent(cfg, params)) {
     if (keepRaw) raw.push(chunk);
@@ -1050,8 +1154,14 @@ async function invokeAgent(cfg, params) {
     else if (chunk.type === "token") tokenBuffer += chunk.content;
     else if (chunk.type === "metadata" && chunk.sessionId) metadataSessionId = chunk.sessionId;
     else if (chunk.type === "session" && chunk.sessionId) mintedSessionId = chunk.sessionId;
-    else if (chunk.type === "done") cleanEnd = true;
-  }
+    else if (chunk.type === "done") doneChunk = chunk;
+    else if (chunk.type === "status" && chunk.blocked) blocked = chunk.blocked;
+  }
+  const sessionId = mintedSessionId ?? responseChunk?.sessionId ?? metadataSessionId ?? params.sessionId;
+  const executionId = metricsChunk?.executionId;
+  const outcomeError = doneChunk && errorFromDoneChunk(doneChunk, { executionId, sessionId, blocked });
+  if (outcomeError) throw outcomeError;
+  const cleanEnd = doneChunk !== void 0;
   if (!responseChunk) {
     if (cleanEnd) {
       throw new ZihinAgentError("protocol", "Stream ended (done) without a `response` event.");
@@ -1060,11 +1170,12 @@ async function invokeAgent(cfg, params) {
       return {
         content: tokenBuffer,
         contentSource: "tokens",
-        sessionId: mintedSessionId ?? metadataSessionId ?? params.sessionId,
+        sessionId,
         usage: metricsChunk?.usage,
         model: metricsChunk?.model,
         iterations: metricsChunk?.iterations,
         executionTimeMs: metricsChunk?.executionTimeMs,
+        executionId,
         raw
       };
     }
@@ -1073,13 +1184,18 @@ async function invokeAgent(cfg, params) {
   return {
     content: responseChunk.content,
     contentSource: "response",
-    sessionId: mintedSessionId ?? responseChunk.sessionId ?? metadataSessionId ?? params.sessionId,
+    sessionId,
     model: metricsChunk?.model,
     usage: metricsChunk?.usage,
     sources: responseChunk.sources,
     blocks: responseChunk.blocks,
+    gated: responseChunk.gated,
     iterations: metricsChunk?.iterations,
     executionTimeMs: metricsChunk?.executionTimeMs,
+    executionId,
+    outcome: doneChunk?.outcome,
+    truncated: doneChunk?.truncated,
+    finishReason: doneChunk?.finishReason,
     raw
   };
 }
@@ -1685,6 +1801,7 @@ export {
   ZihinAgentError,
   classifyStreamErrorKind,
   createClient,
+  errorFromDoneChunk,
   errorFromStreamChunk,
   isCommercialBlock,
   sanitizeApiError,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zihin/agent-client",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Núcleo de invocação de agentes Zihin.ai — padrão único para n8n, Paperclip e integrações futuras. Stream direto (SSE bufferizado) + triggers assíncronos com callback.",
   "keywords": [
     "zihin",