@zihin/agent-client 0.6.0 → 0.7.0

package/dist/index.js

@@ -29,6 +29,7 @@ __export(index_exports, {
   classifyStreamErrorKind: () => classifyStreamErrorKind,
   createClient: () => createClient,
   errorFromDoneChunk: () => errorFromDoneChunk,
+  errorFromOutcome: () => errorFromOutcome,
   errorFromStreamChunk: () => errorFromStreamChunk,
   isCommercialBlock: () => isCommercialBlock,
   sanitizeApiError: () => sanitizeApiError,
@@ -89,6 +90,20 @@ var RUNNING_STATUSES = /* @__PURE__ */ new Set([
 function isTerminalStatus(status) {
   return !RUNNING_STATUSES.has(status.toLowerCase().replace(/-/g, "_"));
 }
+var _warnedDeprecations = /* @__PURE__ */ new Set();
+function warnDeprecatedOnce(code, message) {
+  if (_warnedDeprecations.has(code)) return;
+  _warnedDeprecations.add(code);
+  try {
+    const proc = globalThis.process;
+    if (typeof proc?.emitWarning === "function") {
+      proc.emitWarning(message, { type: "ZihinDeprecationWarning", code });
+      return;
+    }
+    console.warn(`[${code}] ${message}`);
+  } catch {
+  }
+}
 
 // src/security.ts
 var PRIVATE_IP_PATTERNS = [
@@ -408,6 +423,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(
@@ -547,15 +564,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);
@@ -645,7 +662,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();
@@ -664,7 +681,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 });
@@ -673,6 +690,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 {
@@ -684,7 +702,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);
@@ -694,7 +712,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) {
@@ -710,7 +728,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 };
@@ -721,7 +739,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 });
@@ -923,6 +948,25 @@ function parseIgnoredFields(v) {
   }
   return out;
 }
+var MAX_SUGGESTIONS = 10;
+var MAX_SUGGESTION_CHARS = 200;
+function suggestionsFromBlocks(blocks) {
+  if (!Array.isArray(blocks)) return void 0;
+  const qr = [...blocks].reverse().find((b) => rec(b).type === "quick_replies");
+  const labels = rec(rec(qr).data).labels;
+  if (!Array.isArray(labels)) return void 0;
+  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) {
@@ -932,6 +976,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
@@ -954,6 +999,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":
@@ -968,6 +1015,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": {
@@ -989,6 +1037,8 @@ function mapEvent(e) {
         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,
+        suggestions: suggestionsFromBlocks(d.blocks),
+        ...turnIds(d),
         data: e.data
       };
     case "metrics": {
@@ -1011,7 +1061,10 @@ 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] };
   if (params.context) body.context = { ...params.context };
   if (params.bindings) body.bindings = { ...params.bindings };
   if (params.sessionFrom?.length) body.session_from = [...params.sessionFrom];
@@ -1054,6 +1107,7 @@ function validateParams(params) {
     }
   }
   validateStructuredInput(params);
+  warnDeprecatedOptions(params);
   if (params.options?.timeoutMs !== void 0) {
     normalizeTimeoutMs(params.options.timeoutMs, "options.timeoutMs");
   }
@@ -1064,6 +1118,22 @@ function validateParams(params) {
     }
   }
 }
+function warnDeprecatedOptions(params) {
+  const o = params.options;
+  if (!o) return;
+  if (o.jitMode !== void 0) {
+    warnDeprecatedOnce(
+      "ZIHIN_DEP001",
+      "`options.jitMode` is deprecated and has no effect (the server discontinued it). Remove it; it will be dropped from the SDK in 1.0."
+    );
+  }
+  if (o.temperature !== void 0 || o.maxTokens !== void 0) {
+    warnDeprecatedOnce(
+      "ZIHIN_DEP002",
+      "`options.temperature`/`options.maxTokens` have no effect: the agent's own configuration (`llm_config`) decides them \u2014 change it in the Zihin console or with `update_agent`. They will be dropped from the SDK in 1.0."
+    );
+  }
+}
 var MAX_FIELDS = 50;
 var MAX_VALUE_CHARS = 2e3;
 var MAX_TOTAL_CHARS = { context: 2e3, bindings: 16e3 };
@@ -1071,13 +1141,37 @@ var MAX_SESSION_FROM_FIELDS = 5;
 var FIELD_NAME_RE = /^[A-Za-z_][A-Za-z0-9_-]{0,63}$/;
 var PROTOTYPE_KEYS = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
 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 {
     ...params,
+    ...normalizeConsumer(params),
     context: snap(params.context),
     bindings: snap(params.bindings),
-    sessionFrom: Array.isArray(params.sessionFrom) ? [...params.sessionFrom] : params.sessionFrom
+    sessionFrom: Array.isArray(params.sessionFrom) ? [...params.sessionFrom] : params.sessionFrom,
+    capabilities: isPlainObject(params.capabilities) ? {
+      ...params.capabilities,
+      blocks: Array.isArray(params.capabilities.blocks) ? [...params.capabilities.blocks] : params.capabilities.blocks
+    } : params.capabilities
+  };
+}
+function normalizeConsumer(params) {
+  const c = params.consumer;
+  if (c === void 0) return {};
+  if (!isPlainObject(c)) {
+    throw new ZihinAgentError("config", "`consumer` must be an object: `{ key, name? }`.");
+  }
+  const key = c.key;
+  if (params.consumerKey !== void 0 && key !== void 0 && params.consumerKey !== key) {
+    throw new ZihinAgentError("config", "`consumerKey` and `consumer.key` differ \u2014 send only one of them.");
+  }
+  const resolved = key ?? params.consumerKey;
+  return {
+    consumerKey: resolved,
+    consumer: { key: resolved, ...c.name !== void 0 ? { name: c.name } : {} }
   };
 }
 function isPlainObject(v) {
@@ -1089,12 +1183,33 @@ 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.");
   }
   if (typeof params.consumerKey === "string" && params.consumerKey.length > MAX_CONSUMER_KEY_CHARS) {
     throw new ZihinAgentError("config", `\`consumerKey\` is longer than ${MAX_CONSUMER_KEY_CHARS} characters.`);
   }
+  if (params.consumer !== void 0) {
+    if (params.consumerKey === void 0) {
+      throw new ZihinAgentError("config", "`consumer.key` is required (the name has nothing to attach to without it).");
+    }
+    const n = params.consumer.name;
+    if (n !== void 0 && (typeof n !== "string" || !n.trim() || n.length > MAX_CONSUMER_NAME_CHARS)) {
+      throw new ZihinAgentError("config", `\`consumer.name\` must be a non-empty string of up to ${MAX_CONSUMER_NAME_CHARS} characters.`);
+    }
+  }
+  if (params.capabilities !== void 0) {
+    const blocks = isPlainObject(params.capabilities) ? params.capabilities.blocks : null;
+    if (blocks === null || blocks !== void 0 && (!Array.isArray(blocks) || blocks.length > MAX_CLIENT_BLOCKS || blocks.some((b) => typeof b !== "string"))) {
+      throw new ZihinAgentError(
+        "config",
+        `\`capabilities\` must be \`{ blocks: [...] }\` with up to ${MAX_CLIENT_BLOCKS} block names (e.g. \`['quick_replies']\`).`
+      );
+    }
+  }
   for (const name of ["context", "bindings"]) {
     const v = params[name];
     if (v === void 0) continue;
@@ -1148,6 +1263,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) {
@@ -1184,7 +1300,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);
@@ -1203,7 +1319,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) {
@@ -1214,7 +1341,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,
@@ -1237,16 +1364,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 = {
@@ -1267,8 +1440,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: {
@@ -1325,6 +1522,7 @@ async function invokeAgent(cfg, params) {
   const keepRaw = params.includeRaw === true;
   let responseChunk;
   let metricsChunk;
+  let metadataChunk;
   let metadataSessionId;
   let mintedSessionId;
   let doneChunk;
@@ -1335,12 +1533,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;
@@ -1349,9 +1551,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) {
@@ -1367,6 +1583,7 @@ async function invokeAgent(cfg, params) {
         iterations: metricsChunk?.iterations,
         executionTimeMs: metricsChunk?.executionTimeMs,
         executionId,
+        ...ids,
         acceptedFields,
         ignoredFields,
         raw
@@ -1382,10 +1599,12 @@ async function invokeAgent(cfg, params) {
     usage: metricsChunk?.usage,
     sources: responseChunk.sources,
     blocks: responseChunk.blocks,
+    suggestions: responseChunk.suggestions,
     gated: responseChunk.gated,
     iterations: metricsChunk?.iterations,
     executionTimeMs: metricsChunk?.executionTimeMs,
     executionId,
+    ...ids,
     outcome: doneChunk?.outcome,
     truncated: doneChunk?.truncated,
     finishReason: doneChunk?.finishReason,
@@ -1656,22 +1875,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),
@@ -1998,6 +2235,7 @@ function signRequest(payload, secretKey, timestamp) {
   classifyStreamErrorKind,
   createClient,
   errorFromDoneChunk,
+  errorFromOutcome,
   errorFromStreamChunk,
   isCommercialBlock,
   sanitizeApiError,