@zihin/agent-client 0.6.1 → 0.8.0

package/dist/index.mjs

@@ -388,6 +388,8 @@ function errorFromResponse(status, body, meta = {}) {
       retryable: false
     });
   }
+  if (code === "PLAN_LIMIT_REACHED")
+    return new ZihinAgentError("blocked", message || "This feature is not available on your Zihin plan.", { ...base, retryable: false });
   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(
@@ -484,7 +486,7 @@ function resolveConfig(config) {
   if (typeof (config.fetch ?? globalThis.fetch) !== "function") {
     throw new ZihinAgentError(
       "config",
-      "Global fetch is unavailable in this runtime. Use Node >=18 or pass a `fetch` implementation in the client config."
+      "Global fetch is unavailable in this runtime. Use Node >=20.16 or pass a `fetch` implementation in the client config."
     );
   }
   return {
@@ -527,15 +529,15 @@ function buildHeaders(apiKey, extra = {}) {
     ...extra
   };
 }
-function delay(ms, signal) {
+function delay(ms, signal, meta) {
   return new Promise((resolve, reject) => {
     if (signal?.aborted) {
-      reject(new ZihinAgentError("aborted", "Request was aborted by the caller."));
+      reject(new ZihinAgentError("aborted", "Request was aborted by the caller.", meta));
       return;
     }
     const onAbort = () => {
       clearTimeout(timer);
-      reject(new ZihinAgentError("aborted", "Request was aborted by the caller."));
+      reject(new ZihinAgentError("aborted", "Request was aborted by the caller.", meta));
     };
     const timer = setTimeout(() => {
       if (signal) signal.removeEventListener("abort", onAbort);
@@ -625,7 +627,7 @@ async function requestBuffered(args) {
         }
         d.dispose();
         args.onRetry?.({ endpoint, attempt: attempt + 1, delayMs: wait, reason: "status", status: res.status });
-        await delay(wait, args.callerSignal);
+        await delay(wait, args.callerSignal, { endpoint, attempts: attempt + 1 });
         continue;
       }
       const text = peeked ?? await res.text();
@@ -644,7 +646,7 @@ async function requestBuffered(args) {
       const wait = backoffMs(attempt);
       if (budget.overheadLeft() <= wait) throw lastError;
       args.onRetry?.({ endpoint, attempt: attempt + 1, delayMs: wait, reason: "network" });
-      await delay(wait, args.callerSignal);
+      await delay(wait, args.callerSignal, { endpoint, attempts: attempt + 1 });
     }
   }
   throw lastError ?? new ZihinAgentError("unknown", "Max retries exceeded.", { endpoint });
@@ -653,6 +655,7 @@ async function openStream(args) {
   const endpoint = endpointLabel("POST", args.url);
   const doFetch = resolveFetch(args.fetchImpl);
   const budget = budgetTracker({ ...args, endpoint });
+  const policy = args.idempotent ? "idempotent" : "side-effecting";
   for (let attempt = 0; attempt <= args.maxRetries; attempt++) {
     const d = createDeadline(args.timeoutMs, args.callerSignal);
     try {
@@ -664,7 +667,7 @@ async function openStream(args) {
         redirect: "error",
         cache: "no-store"
       });
-      let wait = shouldRetryStatus(response.status, "side-effecting") && attempt < args.maxRetries ? retryAfterMs(response.headers) ?? backoffMs(attempt) : null;
+      let wait = shouldRetryStatus(response.status, policy) && attempt < args.maxRetries ? retryAfterMs(response.headers) ?? backoffMs(attempt) : null;
       if (response.status === 429) {
         const text = await response.text().catch(() => "");
         const body = parseBody(text);
@@ -674,7 +677,7 @@ async function openStream(args) {
         }
         d.dispose();
         args.onRetry?.({ endpoint, attempt: attempt + 1, delayMs: wait, reason: "status", status: 429 });
-        await delay(wait, args.callerSignal);
+        await delay(wait, args.callerSignal, { endpoint, attempts: attempt + 1 });
         continue;
       }
       if (wait !== null && budget.overheadLeft() > wait) {
@@ -690,7 +693,7 @@ async function openStream(args) {
           reason: "status",
           status: response.status
         });
-        await delay(wait, args.callerSignal);
+        await delay(wait, args.callerSignal, { endpoint, attempts: attempt + 1 });
         continue;
       }
       return { response, deadline: d, endpoint };
@@ -701,7 +704,14 @@ async function openStream(args) {
       if (d.timedOut()) throw budget.expired(attempt + 1);
       if (d.abortedByCaller())
         throw new ZihinAgentError("aborted", "Request was aborted by the caller.", meta);
-      throw errorFromThrow(err, budget.reported, meta);
+      const netErr = errorFromThrow(err, budget.reported, meta);
+      const wait = backoffMs(attempt);
+      if (policy === "idempotent" && netErr.retryable && attempt < args.maxRetries && budget.overheadLeft() > wait) {
+        args.onRetry?.({ endpoint, attempt: attempt + 1, delayMs: wait, reason: "network" });
+        await delay(wait, args.callerSignal, { endpoint, attempts: attempt + 1 });
+        continue;
+      }
+      throw netErr;
     }
   }
   throw new ZihinAgentError("unknown", "Max retries exceeded.", { endpoint });
@@ -913,6 +923,15 @@ function suggestionsFromBlocks(blocks) {
   const out = labels.filter((l) => typeof l === "string" && l.trim().length > 0 && l.length <= MAX_SUGGESTION_CHARS).slice(0, MAX_SUGGESTIONS);
   return out.length ? out : void 0;
 }
+function turnIds(d) {
+  return {
+    executionId: safeId(d.execution_id),
+    clientMessageId: safeId(d.client_message_id),
+    idempotentReplay: d.idempotent_replay === true ? true : void 0,
+    userMessageId: safeId(d.user_message_id),
+    assistantMessageId: safeId(d.assistant_message_id)
+  };
+}
 function mapEvent(e) {
   const d = rec(e.data);
   switch (e.event) {
@@ -922,6 +941,7 @@ function mapEvent(e) {
         requestId: safeId(d.request_id),
         agentId: str(d.agent_id),
         sessionId: safeId(d.session_id),
+        ...turnIds(d),
         acceptedFields: parseAcceptedFields(d.accepted_fields),
         ignoredFields: parseIgnoredFields(d.ignored_fields),
         data: e.data
@@ -944,6 +964,8 @@ function mapEvent(e) {
       };
     case "action_proposed":
       return { type: "action_proposed", data: e.data };
+    case "action_forwarded":
+      return { type: "action_forwarded", actionId: safeId(d.action_id), data: e.data };
     case "token":
       return { type: "token", content: str(d.content) ?? "", data: e.data };
     case "warning":
@@ -958,6 +980,7 @@ function mapEvent(e) {
         timeoutClock: safeLabel(d.timeout_clock),
         truncated: typeof d.truncated === "boolean" ? d.truncated : void 0,
         finishReason: str(d.finish_reason),
+        ...turnIds(d),
         data: e.data
       };
     case "error": {
@@ -980,6 +1003,7 @@ function mapEvent(e) {
         sources: Array.isArray(d.sources) ? d.sources : void 0,
         blocks: Array.isArray(d.blocks) ? d.blocks : void 0,
         suggestions: suggestionsFromBlocks(d.blocks),
+        ...turnIds(d),
         data: e.data
       };
     case "metrics": {
@@ -1002,6 +1026,7 @@ function buildRequestBody(params, normalizedTimeoutMs) {
   const body = {};
   if (params.message !== void 0) body.message = params.message;
   if (params.sessionId) body.session_id = params.sessionId;
+  if (params.clientMessageId) body.client_message_id = params.clientMessageId;
   if (params.consumerKey) body.consumer_key = params.consumerKey;
   if (params.consumer?.name !== void 0) body.consumer_display_name = params.consumer.name;
   if (params.capabilities?.blocks?.length) body.capabilities = { blocks: [...params.capabilities.blocks] };
@@ -1083,6 +1108,7 @@ var PROTOTYPE_KEYS = /* @__PURE__ */ new Set(["__proto__", "constructor", "proto
 var MAX_CONSUMER_KEY_CHARS = 200;
 var MAX_CONSUMER_NAME_CHARS = 255;
 var MAX_CLIENT_BLOCKS = 10;
+var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 function snapshotStructuredInput(params) {
   const snap = (v) => isPlainObject(v) ? Object.fromEntries(Object.entries(v).filter(([, x]) => x !== void 0)) : v;
   return {
@@ -1122,6 +1148,9 @@ function isScalar(v) {
   return v === null || typeof v === "string" || typeof v === "boolean" || typeof v === "number" && Number.isFinite(v);
 }
 function validateStructuredInput(params) {
+  if (params.clientMessageId !== void 0 && (typeof params.clientMessageId !== "string" || !UUID_RE.test(params.clientMessageId))) {
+    throw new ZihinAgentError("config", "`clientMessageId` must be a UUID (e.g. from `crypto.randomUUID()`).");
+  }
   if (params.consumerKey !== void 0 && (typeof params.consumerKey !== "string" || !params.consumerKey.trim())) {
     throw new ZihinAgentError("config", "`consumerKey` must be a non-empty string.");
   }
@@ -1199,6 +1228,7 @@ function requestedInputFields(params) {
   if (params.context) out.push("context");
   if (params.bindings) out.push("bindings");
   if (params.sessionFrom?.length) out.push("session_from");
+  if (params.clientMessageId) out.push("client_message_id");
   return out;
 }
 function checkInputCapability(params, chunk) {
@@ -1235,7 +1265,7 @@ function checkInputCapability(params, chunk) {
     );
   }
 }
-var TURN_EVENTS = /* @__PURE__ */ new Set(["phase", "thinking", "tool", "action_proposed", "token", "response", "metrics", "done"]);
+var TURN_EVENTS = /* @__PURE__ */ new Set(["phase", "thinking", "tool", "action_proposed", "action_forwarded", "token", "response", "metrics", "done"]);
 async function* streamAgent(cfg, rawParams) {
   const params = snapshotStructuredInput(rawParams);
   validateParams(params);
@@ -1254,7 +1284,18 @@ async function* streamAgent(cfg, rawParams) {
     maxRetries: cfg.maxRetries,
     callerSignal: params.signal,
     fetchImpl: cfg.fetchImpl,
-    onRetry: cfg.onRetry
+    onRetry: cfg.onRetry,
+    // Retry do POST só ANTES dos headers chegarem. O que o torna seguro é a ordem do BE: o SSE faz
+    // `flushHeaders()` antes de reservar o id e antes de qualquer trabalho do turno, então falhar
+    // sem headers quase sempre significa que o handler nem começou. A chave cobre o resto: se o 1º
+    // POST chegou a rodar, o reenvio dá SESSION_BUSY (em voo) ou replay (COMPLETED/LENGTH). A chave
+    // NÃO protege turno cortado no meio: o BE cancela e libera o id, e o reenvio roda de novo com as
+    // tools — por isso o erro mid-stream sai `retryable: false`. Liga antes de ver `accepted_fields`
+    // (chega no `metadata`): contra BE antigo o retry pré-headers acontece sem a chave valer —
+    // aceitável pela mesma ordem (headers antes do trabalho), mas documentado no README.
+    // Resíduo não verificado: proxy que bufferiza headers e devolve 502/504 depois do BE já ter
+    // começado (X-Accel-Buffering: no torna isso improvável).
+    idempotent: !!params.clientMessageId
   });
   try {
     if (!response.ok) {
@@ -1265,7 +1306,7 @@ async function* streamAgent(cfg, rawParams) {
       }
       throw errorFromResponse(response.status, parseBody(text), { endpoint });
     }
-    const onAbortError = () => deadline.timedOut() ? new ZihinAgentError("timeout", `Stream timed out after ${reportedMs}ms.`, { endpoint }) : deadline.abortedByCaller() ? new ZihinAgentError("aborted", "Stream aborted by the caller.", { endpoint }) : new ZihinAgentError("network", "Stream connection interrupted.", { endpoint });
+    const onAbortError = () => deadline.timedOut() ? new ZihinAgentError("timeout", `Stream timed out after ${reportedMs}ms.`, { endpoint }) : deadline.abortedByCaller() ? new ZihinAgentError("aborted", "Stream aborted by the caller.", { endpoint }) : new ZihinAgentError("network", "Stream connection interrupted.", { endpoint, retryable: false });
     for await (const e of parseSse(response, {
       signal: params.signal,
       onAbortError,
@@ -1288,16 +1329,62 @@ async function* streamAgent(cfg, rawParams) {
 function classifyStreamErrorKind(code, timedOut) {
   if (timedOut === true) return "timeout";
   if (code === "VALIDATION_ERROR") return "config";
+  const known = own(STREAM_ERROR_CODES, code);
+  if (known) return known.kind;
   if (timedOut === false) return "server";
   return /TIMEOUT/i.test(code) ? "timeout" : "server";
 }
-function errorFromStreamChunk(chunk) {
+var STREAM_ERROR_CODES = {
+  SESSION_BUSY: {
+    kind: "blocked",
+    message: "Another turn is still running in this session (or the same clientMessageId is still in flight); retry after it finishes.",
+    retryable: true
+  },
+  IDEMPOTENCY_CONFLICT: {
+    kind: "config",
+    message: "This `clientMessageId` was already used with a different message \u2014 use a new UUID per message."
+  },
+  // `keepServerMessage`: a frase do BE diz o que foi e o que NÃO foi feito (tools que rodaram) —
+  // o integrador precisa dela para decidir se reenvia.
+  CONTEXT_LIMIT: {
+    kind: "blocked",
+    message: "The conversation gathered more context than the model can process; send a smaller request or start a new session.",
+    keepServerMessage: true
+  },
+  CONFLICT: {
+    kind: "blocked",
+    message: "The declared consumer identity does not match the one already bound to this session."
+  },
+  NOT_FOUND: {
+    kind: "not_found",
+    message: "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."
+  },
+  // Replay idempotente sem resposta recuperável. Pode persistir por 24 h (turno gravado sem
+  // mensagem do assistente): retentar com o MESMO id bate no mesmo erro, por isso não é
+  // retentável — o aviso diz a saída (novo `clientMessageId`).
+  SERVICE_UNAVAILABLE: {
+    kind: "server",
+    message: "This message was already answered, but the stored answer could not be read; resend with a new clientMessageId.",
+    retryable: false
+  },
+  // Defensivo: não há ponto de emissão in-stream observado no BE @ 9ec79cfc.
+  RATE_LIMIT_EXCEEDED: { kind: "rate_limit", retryable: true },
+  QUOTA_EXCEEDED: { kind: "quota_exceeded" },
+  TRIAL_EXPIRED: { kind: "trial_expired" },
+  NO_ACTIVE_SUBSCRIPTION: { kind: "no_subscription" }
+};
+function errorFromStreamChunk(chunk, ctx = {}) {
   const code = chunk.code ?? "AGENT_ERROR";
   const kind = classifyStreamErrorKind(code, chunk.timedOut);
-  return new ZihinAgentError(kind, sanitizeApiError(chunk.message ?? code).message || code, {
+  const known = chunk.timedOut === true ? void 0 : own(STREAM_ERROR_CODES, code);
+  const serverMsg = chunk.message ? sanitizeApiError(chunk.message).message.replace(/<[^>]*>/g, "").slice(0, 300) : "";
+  const message = known?.message ? known.keepServerMessage && serverMsg ? `${known.message} Server: ${serverMsg}` : known.message : serverMsg || code;
+  return new ZihinAgentError(kind, message, {
     code,
     requestId: chunk.requestId,
-    retryable: false
+    executionId: safeId(ctx.executionId),
+    sessionId: safeId(ctx.sessionId),
+    retryable: known?.retryable ?? false
   });
 }
 var FAILED_OUTCOMES = {
@@ -1318,8 +1405,32 @@ var FAILED_OUTCOMES = {
   CONFLICT: {
     kind: "blocked",
     message: "The declared consumer identity does not match the one already bound to this session."
+  },
+  // O provedor do modelo recusou por política (BE `4cea8d53`, 08/10/2026). O `content` é um texto
+  // neutro FIXO da plataforma ("Não consigo ajudar com esse pedido…"), não uma resposta: o BE
+  // registra a execução como erro. Publicá-lo como resposta era a falha silenciosa da 0.6.
+  REFUSED: {
+    kind: "blocked",
+    message: "The model provider refused this request under its content policy; the agent did not answer."
+  },
+  // No `/stream` chega como `event: error` (ver STREAM_ERROR_CODES); no webhook sync e em
+  // backends futuros pode vir como desfecho.
+  CONTEXT_LIMIT: {
+    kind: "blocked",
+    message: "The conversation gathered more context than the model can process; send a smaller request or start a new session."
   }
 };
+function errorFromOutcome(outcome, ctx = {}) {
+  const label = safeLabel(outcome);
+  if (!label) return void 0;
+  ctx = { ...ctx, executionId: safeId(ctx.executionId), sessionId: safeId(ctx.sessionId) };
+  if (label === "TIMEOUT") {
+    return new ZihinAgentError("timeout", "The agent turn timed out on the server.", { ...ctx, code: "TURN_TIMEOUT", retryable: false });
+  }
+  const failed = own(FAILED_OUTCOMES, label);
+  if (!failed) return void 0;
+  return new ZihinAgentError(failed.kind, failed.message, { ...ctx, code: label, retryable: failed.retryable ?? false });
+}
 var PAUSED_BLOCKS = /* @__PURE__ */ new Set(["agent_paused", "agent_archived"]);
 var ERROR_BLOCKS = {
   ownership_denied: {
@@ -1376,6 +1487,7 @@ async function invokeAgent(cfg, params) {
   const keepRaw = params.includeRaw === true;
   let responseChunk;
   let metricsChunk;
+  let metadataChunk;
   let metadataSessionId;
   let mintedSessionId;
   let doneChunk;
@@ -1386,12 +1498,16 @@ async function invokeAgent(cfg, params) {
   for await (const chunk of streamAgent(cfg, params)) {
     if (keepRaw) raw.push(chunk);
     if (chunk.type === "error") {
-      throw errorFromStreamChunk(chunk);
+      throw errorFromStreamChunk(chunk, {
+        executionId: metadataChunk?.executionId,
+        sessionId: mintedSessionId ?? metadataSessionId ?? params.sessionId
+      });
     }
     if (chunk.type === "response") responseChunk = chunk;
     else if (chunk.type === "metrics") metricsChunk = chunk;
     else if (chunk.type === "token") tokenBuffer += chunk.content;
     else if (chunk.type === "metadata") {
+      metadataChunk = chunk;
       if (chunk.sessionId) metadataSessionId = chunk.sessionId;
       acceptedFields = chunk.acceptedFields;
       ignoredFields = chunk.ignoredFields;
@@ -1400,9 +1516,23 @@ async function invokeAgent(cfg, params) {
     else if (chunk.type === "status" && chunk.blocked) blocked = chunk.blocked;
   }
   const sessionId = mintedSessionId ?? responseChunk?.sessionId ?? metadataSessionId ?? params.sessionId;
-  const executionId = metricsChunk?.executionId;
+  const executionId = metadataChunk?.executionId ?? doneChunk?.executionId ?? responseChunk?.executionId ?? metricsChunk?.executionId;
+  const ids = {
+    clientMessageId: doneChunk?.clientMessageId ?? responseChunk?.clientMessageId ?? metadataChunk?.clientMessageId,
+    idempotentReplay: doneChunk?.idempotentReplay ?? responseChunk?.idempotentReplay ?? metadataChunk?.idempotentReplay,
+    userMessageId: doneChunk?.userMessageId ?? responseChunk?.userMessageId,
+    assistantMessageId: doneChunk?.assistantMessageId ?? responseChunk?.assistantMessageId
+  };
   const outcomeError = doneChunk && errorFromDoneChunk(doneChunk, { executionId, sessionId, blocked });
   if (outcomeError) throw outcomeError;
+  const replaySession = responseChunk?.sessionId ?? metadataSessionId;
+  if (ids.idempotentReplay && params.sessionId && replaySession && replaySession.toLowerCase() !== params.sessionId.toLowerCase()) {
+    throw new ZihinAgentError(
+      "config",
+      "This `clientMessageId` was already used in a different session: the server replayed that session's answer. Use a new UUID per message (never a fixed value).",
+      { code: "IDEMPOTENT_REPLAY_OTHER_SESSION", executionId, sessionId: params.sessionId, retryable: false }
+    );
+  }
   const cleanEnd = doneChunk !== void 0;
   if (!responseChunk) {
     if (cleanEnd) {
@@ -1418,6 +1548,7 @@ async function invokeAgent(cfg, params) {
         iterations: metricsChunk?.iterations,
         executionTimeMs: metricsChunk?.executionTimeMs,
         executionId,
+        ...ids,
         acceptedFields,
         ignoredFields,
         raw
@@ -1438,6 +1569,7 @@ async function invokeAgent(cfg, params) {
     iterations: metricsChunk?.iterations,
     executionTimeMs: metricsChunk?.executionTimeMs,
     executionId,
+    ...ids,
     outcome: doneChunk?.outcome,
     truncated: doneChunk?.truncated,
     finishReason: doneChunk?.finishReason,
@@ -1708,22 +1840,40 @@ async function dispatchAgent(cfg, params) {
   }
   const json = parseBody(res.text);
   const j = rec(json);
+  const preTurnOutcome = safeLabel(j.outcome);
+  if (j.success === false && preTurnOutcome && preTurnOutcome !== "ERROR") {
+    const classified = errorFromOutcome(preTurnOutcome, {
+      status: res.status,
+      endpoint: res.endpoint,
+      attempts: res.attempts,
+      executionId: safeId(j.execution_id)
+    });
+    if (classified) throw classified;
+  }
   if (j.success === false) {
     const detail = sanitizeApiError(str(j.error) ?? "").message;
     throw new ZihinAgentError("server", detail || "The agent run failed.", {
       status: res.status,
       endpoint: res.endpoint,
       attempts: res.attempts,
-      executionId: str(j.execution_id),
+      executionId: safeId(j.execution_id),
       // Não é transitório: o turno rodou e falhou. Repetir gastaria outra execução.
       retryable: false
     });
   }
+  const outcomeError = errorFromOutcome(str(j.outcome), {
+    status: res.status,
+    endpoint: res.endpoint,
+    attempts: res.attempts,
+    executionId: safeId(j.execution_id)
+  });
+  if (outcomeError) throw outcomeError;
   return {
     accepted: true,
+    outcome: safeLabel(j.outcome),
     triggerId: str(j.trigger_id) ?? params.triggerId,
     agentId: str(j.agent_id),
-    executionId: str(j.execution_id),
+    executionId: safeId(j.execution_id),
     agentResponse: str(j.agent_response),
     usage: parseUsage(j.usage),
     iterations: num(j.iterations),
@@ -2049,6 +2199,7 @@ export {
   classifyStreamErrorKind,
   createClient,
   errorFromDoneChunk,
+  errorFromOutcome,
   errorFromStreamChunk,
   isCommercialBlock,
   sanitizeApiError,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zihin/agent-client",
-  "version": "0.6.1",
+  "version": "0.8.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",
@@ -40,7 +40,7 @@
     "dist"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=20.16"
   },
   "publishConfig": {
     "access": "public"
@@ -54,7 +54,7 @@
     "prepublishOnly": "npm run build && npm test"
   },
   "devDependencies": {
-    "@types/node": ">=18",
+    "@types/node": ">=20",
     "tsup": "^8.0.0",
     "typescript": "^5.4.0"
   }