@zihin/agent-client 0.4.0 → 0.4.1

package/README.md

@@ -159,8 +159,12 @@ await zihin.cancelTask({ taskId: task.id, reason: 'mudou o plano' }); // 409 se
 
 Um `content` vazio com `contentSource: 'response'` é decisão do BE, não lacuna — o núcleo **não**
 preenche com tokens. E quando o BE fecha o stream com `event: error` (turno morto no deadline, por
-exemplo), o núcleo **lança** (`kind: 'timeout'` para `TURN_TIMEOUT`, com `code` e `requestId`) em vez
-de devolver o parcial.
+exemplo), o núcleo **lança** (`kind: 'timeout'`, com `code` e `requestId`) em vez de devolver o
+parcial. Se foi timeout ou não vem do campo **explícito `error.timed_out`** do evento (BE desde
+26/09/2026): quando presente ele é autoritativo — `true` é timeout seja qual for o `code`, `false`
+é `server` mesmo com "TIMEOUT" no nome. Sem o campo (backend antigo), cai no fallback por nome
+(`/TIMEOUT/i` no `code`), que será removido numa major futura. Não ramifique no **nome** do código
+de timeout: o BE vai renomeá-los (zihin-agent-builder#561); use `kind`.
 
 ## Dropdown de agentes
 

package/dist/index.d.mts

@@ -223,16 +223,21 @@ type AgentStreamChunk = {
     data: unknown;
 }
 /**
- * O BE encerra o stream com `event: error` + `{ error: { type, code, message, request_id } }`
- * (`utils/sse.js:97`) — inclusive quando o TURNO morre no deadline. Antes isto caía em
- * `unknown` e o `invokeAgent` ignorava: se já tinha chegado token, devolvia a deliberação
- * crua como SUCESSO.
+ * O BE encerra o stream com `event: error` + `{ error: { type, code, message, request_id,
+ * timed_out? } }` (`utils/sse.js`) — inclusive quando o TURNO morre no deadline. Antes isto
+ * caía em `unknown` e o `invokeAgent` ignorava: se já tinha chegado token, devolvia a
+ * deliberação crua como SUCESSO.
+ *
+ * `timedOut` espelha `error.timed_out` (BE desde 26/09/2026, zihin-agent-builder#605): campo
+ * explícito que diz se o turno morreu por timeout, independente do NOME do código — os códigos
+ * vão ser renomeados (zihin-agent-builder#561). `undefined` = backend antigo, sem o campo.
  */
  | {
     type: 'error';
     code?: string;
     message?: string;
     requestId?: string;
+    timedOut?: boolean;
     data: unknown;
 }
 /**
@@ -664,6 +669,36 @@ declare class ZihinAgentClient {
 /** Açúcar: cria um cliente a partir da config. */
 declare function createClient(config: ZihinClientConfig): ZihinAgentClient;
 
+/**
+ * Caminho A — invocação direta de agente (POST /api/v2/agents/:id/stream).
+ * `streamAgent` emite deltas ao vivo; `invokeAgent` buffeia o stream e consolida
+ * o evento `response` (content/sources/session_id/blocks) com o `metrics` (usage/model).
+ *
+ * @module invoke
+ */
+
+/**
+ * Decide se o `event: error` terminal do BE foi um timeout do turno (#75).
+ *
+ * Fonte primária é o campo EXPLÍCITO `error.timed_out` (BE `utils/sse.js`, em prod desde
+ * 26/09/2026 — zihin-agent-builder#605): quando presente, é autoritativo nos dois sentidos —
+ * `true` classifica como timeout seja qual for o `code`; `false` classifica como `server` mesmo
+ * que o nome do código contenha "TIMEOUT". O BE vai renomear esses códigos
+ * (zihin-agent-builder#561) e o nome deixa de ser um sinal confiável.
+ *
+ * O regex no nome só vale como FALLBACK para backends que ainda não emitem `timed_out`
+ * (self-hosted/antigos). Some numa major futura, depois do rename no BE.
+ */
+declare function classifyStreamErrorKind(code: string, timedOut?: boolean): 'timeout' | 'server';
+/**
+ * Converte o chunk `type: 'error'` (evento terminal do BE) num `ZihinAgentError` — a MESMA regra
+ * que o `invokeAgent` aplica, exportada para quem consome `streamAgent` direto (o adapter do
+ * Paperclip, por exemplo) não reimplementar a classificação por conta e divergir dela.
+ */
+declare function errorFromStreamChunk(chunk: Extract<AgentStreamChunk, {
+    type: 'error';
+}>): ZihinAgentError;
+
 /**
  * Security utilities — portado de n8n-nodes-zihin/src/utils/security.ts (zero-dep).
  * SSRF prevention, payload limits, error sanitization, API-key format.
@@ -786,4 +821,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, createClient, isCommercialBlock, sanitizeApiError, signRequest, validateApiKeyFormat, validateBaseUrl, validatePromptSize };
+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 };

package/dist/index.d.ts

@@ -223,16 +223,21 @@ type AgentStreamChunk = {
     data: unknown;
 }
 /**
- * O BE encerra o stream com `event: error` + `{ error: { type, code, message, request_id } }`
- * (`utils/sse.js:97`) — inclusive quando o TURNO morre no deadline. Antes isto caía em
- * `unknown` e o `invokeAgent` ignorava: se já tinha chegado token, devolvia a deliberação
- * crua como SUCESSO.
+ * O BE encerra o stream com `event: error` + `{ error: { type, code, message, request_id,
+ * timed_out? } }` (`utils/sse.js`) — inclusive quando o TURNO morre no deadline. Antes isto
+ * caía em `unknown` e o `invokeAgent` ignorava: se já tinha chegado token, devolvia a
+ * deliberação crua como SUCESSO.
+ *
+ * `timedOut` espelha `error.timed_out` (BE desde 26/09/2026, zihin-agent-builder#605): campo
+ * explícito que diz se o turno morreu por timeout, independente do NOME do código — os códigos
+ * vão ser renomeados (zihin-agent-builder#561). `undefined` = backend antigo, sem o campo.
  */
  | {
     type: 'error';
     code?: string;
     message?: string;
     requestId?: string;
+    timedOut?: boolean;
     data: unknown;
 }
 /**
@@ -664,6 +669,36 @@ declare class ZihinAgentClient {
 /** Açúcar: cria um cliente a partir da config. */
 declare function createClient(config: ZihinClientConfig): ZihinAgentClient;
 
+/**
+ * Caminho A — invocação direta de agente (POST /api/v2/agents/:id/stream).
+ * `streamAgent` emite deltas ao vivo; `invokeAgent` buffeia o stream e consolida
+ * o evento `response` (content/sources/session_id/blocks) com o `metrics` (usage/model).
+ *
+ * @module invoke
+ */
+
+/**
+ * Decide se o `event: error` terminal do BE foi um timeout do turno (#75).
+ *
+ * Fonte primária é o campo EXPLÍCITO `error.timed_out` (BE `utils/sse.js`, em prod desde
+ * 26/09/2026 — zihin-agent-builder#605): quando presente, é autoritativo nos dois sentidos —
+ * `true` classifica como timeout seja qual for o `code`; `false` classifica como `server` mesmo
+ * que o nome do código contenha "TIMEOUT". O BE vai renomear esses códigos
+ * (zihin-agent-builder#561) e o nome deixa de ser um sinal confiável.
+ *
+ * O regex no nome só vale como FALLBACK para backends que ainda não emitem `timed_out`
+ * (self-hosted/antigos). Some numa major futura, depois do rename no BE.
+ */
+declare function classifyStreamErrorKind(code: string, timedOut?: boolean): 'timeout' | 'server';
+/**
+ * Converte o chunk `type: 'error'` (evento terminal do BE) num `ZihinAgentError` — a MESMA regra
+ * que o `invokeAgent` aplica, exportada para quem consome `streamAgent` direto (o adapter do
+ * Paperclip, por exemplo) não reimplementar a classificação por conta e divergir dela.
+ */
+declare function errorFromStreamChunk(chunk: Extract<AgentStreamChunk, {
+    type: 'error';
+}>): ZihinAgentError;
+
 /**
  * Security utilities — portado de n8n-nodes-zihin/src/utils/security.ts (zero-dep).
  * SSRF prevention, payload limits, error sanitization, API-key format.
@@ -786,4 +821,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, createClient, isCommercialBlock, sanitizeApiError, signRequest, validateApiKeyFormat, validateBaseUrl, validatePromptSize };
+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 };

package/dist/index.js

@@ -26,7 +26,9 @@ __export(index_exports, {
   OPERATION_TIMEOUT_MS: () => OPERATION_TIMEOUT_MS,
   ZihinAgentClient: () => ZihinAgentClient,
   ZihinAgentError: () => ZihinAgentError,
+  classifyStreamErrorKind: () => classifyStreamErrorKind,
   createClient: () => createClient,
+  errorFromStreamChunk: () => errorFromStreamChunk,
   isCommercialBlock: () => isCommercialBlock,
   sanitizeApiError: () => sanitizeApiError,
   signRequest: () => signRequest,
@@ -929,6 +931,7 @@ function mapEvent(e) {
         code: str(err.code),
         message: str(err.message),
         requestId: str(err.request_id),
+        timedOut: typeof err.timed_out === "boolean" ? err.timed_out : void 0,
         data: e.data
       };
     }
@@ -1047,6 +1050,20 @@ async function* streamAgent(cfg, params) {
     deadline.dispose();
   }
 }
+function classifyStreamErrorKind(code, timedOut) {
+  if (timedOut === true) return "timeout";
+  if (timedOut === false) return "server";
+  return /TIMEOUT/i.test(code) ? "timeout" : "server";
+}
+function errorFromStreamChunk(chunk) {
+  const code = chunk.code ?? "AGENT_ERROR";
+  const kind = classifyStreamErrorKind(code, chunk.timedOut);
+  return new ZihinAgentError(kind, sanitizeApiError(chunk.message ?? code).message || code, {
+    code,
+    requestId: chunk.requestId,
+    retryable: false
+  });
+}
 async function invokeAgent(cfg, params) {
   const raw = [];
   const keepRaw = params.includeRaw === true;
@@ -1059,13 +1076,7 @@ async function invokeAgent(cfg, params) {
   for await (const chunk of streamAgent(cfg, params)) {
     if (keepRaw) raw.push(chunk);
     if (chunk.type === "error") {
-      const code = chunk.code ?? "AGENT_ERROR";
-      const kind = /TIMEOUT/i.test(code) ? "timeout" : "server";
-      throw new ZihinAgentError(kind, sanitizeApiError(chunk.message ?? code).message || code, {
-        code,
-        requestId: chunk.requestId,
-        retryable: false
-      });
+      throw errorFromStreamChunk(chunk);
     }
     if (chunk.type === "response") responseChunk = chunk;
     else if (chunk.type === "metrics") metricsChunk = chunk;
@@ -1706,7 +1717,9 @@ function signRequest(payload, secretKey, timestamp) {
   OPERATION_TIMEOUT_MS,
   ZihinAgentClient,
   ZihinAgentError,
+  classifyStreamErrorKind,
   createClient,
+  errorFromStreamChunk,
   isCommercialBlock,
   sanitizeApiError,
   signRequest,

package/dist/index.mjs

@@ -898,6 +898,7 @@ function mapEvent(e) {
         code: str(err.code),
         message: str(err.message),
         requestId: str(err.request_id),
+        timedOut: typeof err.timed_out === "boolean" ? err.timed_out : void 0,
         data: e.data
       };
     }
@@ -1016,6 +1017,20 @@ async function* streamAgent(cfg, params) {
     deadline.dispose();
   }
 }
+function classifyStreamErrorKind(code, timedOut) {
+  if (timedOut === true) return "timeout";
+  if (timedOut === false) return "server";
+  return /TIMEOUT/i.test(code) ? "timeout" : "server";
+}
+function errorFromStreamChunk(chunk) {
+  const code = chunk.code ?? "AGENT_ERROR";
+  const kind = classifyStreamErrorKind(code, chunk.timedOut);
+  return new ZihinAgentError(kind, sanitizeApiError(chunk.message ?? code).message || code, {
+    code,
+    requestId: chunk.requestId,
+    retryable: false
+  });
+}
 async function invokeAgent(cfg, params) {
   const raw = [];
   const keepRaw = params.includeRaw === true;
@@ -1028,13 +1043,7 @@ async function invokeAgent(cfg, params) {
   for await (const chunk of streamAgent(cfg, params)) {
     if (keepRaw) raw.push(chunk);
     if (chunk.type === "error") {
-      const code = chunk.code ?? "AGENT_ERROR";
-      const kind = /TIMEOUT/i.test(code) ? "timeout" : "server";
-      throw new ZihinAgentError(kind, sanitizeApiError(chunk.message ?? code).message || code, {
-        code,
-        requestId: chunk.requestId,
-        retryable: false
-      });
+      throw errorFromStreamChunk(chunk);
     }
     if (chunk.type === "response") responseChunk = chunk;
     else if (chunk.type === "metrics") metricsChunk = chunk;
@@ -1674,7 +1683,9 @@ export {
   OPERATION_TIMEOUT_MS,
   ZihinAgentClient,
   ZihinAgentError,
+  classifyStreamErrorKind,
   createClient,
+  errorFromStreamChunk,
   isCommercialBlock,
   sanitizeApiError,
   signRequest,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zihin/agent-client",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "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",