@zihin/agent-client 0.4.1 → 0.6.0

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;
@@ -854,19 +876,34 @@ async function* parseSse(response, opts = {}) {
 }
 
 // src/invoke.ts
+function parseAcceptedFields(v) {
+  if (!Array.isArray(v)) return void 0;
+  return v.map((x) => safeId(typeof x === "string" ? x : str(rec(x).field) ?? str(rec(x).name))).filter((x) => !!x);
+}
+function parseIgnoredFields(v) {
+  if (!Array.isArray(v)) return void 0;
+  const out = [];
+  for (const x of v) {
+    const field = safeId(typeof x === "string" ? x : str(rec(x).field) ?? str(rec(x).name));
+    if (field) out.push(typeof x === "string" ? { field } : { field, reason: safeLabel(rec(x).reason) });
+  }
+  return out;
+}
 function mapEvent(e) {
   const d = rec(e.data);
   switch (e.event) {
     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),
+        acceptedFields: parseAcceptedFields(d.accepted_fields),
+        ignoredFields: parseIgnoredFields(d.ignored_fields),
         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 +925,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 +951,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 +965,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
       };
     }
@@ -930,6 +977,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.consumerKey) body.consumer_key = params.consumerKey;
+  if (params.context) body.context = { ...params.context };
+  if (params.bindings) body.bindings = { ...params.bindings };
+  if (params.sessionFrom?.length) body.session_from = [...params.sessionFrom];
   if (params.attachments?.length) {
     body.attachments = params.attachments.map((a) => ({ url: a.url, type: a.type }));
   }
@@ -968,6 +1019,7 @@ function validateParams(params) {
       throw new ZihinAgentError("config", sizeCheck.error || "Message too large.");
     }
   }
+  validateStructuredInput(params);
   if (params.options?.timeoutMs !== void 0) {
     normalizeTimeoutMs(params.options.timeoutMs, "options.timeoutMs");
   }
@@ -978,12 +1030,136 @@ function validateParams(params) {
     }
   }
 }
-async function* streamAgent(cfg, params) {
+var MAX_FIELDS = 50;
+var MAX_VALUE_CHARS = 2e3;
+var MAX_TOTAL_CHARS = { context: 2e3, bindings: 16e3 };
+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;
+function snapshotStructuredInput(params) {
+  const snap = (v) => isPlainObject(v) ? Object.fromEntries(Object.entries(v).filter(([, x]) => x !== void 0)) : v;
+  return {
+    ...params,
+    context: snap(params.context),
+    bindings: snap(params.bindings),
+    sessionFrom: Array.isArray(params.sessionFrom) ? [...params.sessionFrom] : params.sessionFrom
+  };
+}
+function isPlainObject(v) {
+  if (typeof v !== "object" || v === null || Array.isArray(v)) return false;
+  const proto = Object.getPrototypeOf(v);
+  return proto === Object.prototype || proto === null;
+}
+function isScalar(v) {
+  return v === null || typeof v === "string" || typeof v === "boolean" || typeof v === "number" && Number.isFinite(v);
+}
+function validateStructuredInput(params) {
+  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.`);
+  }
+  for (const name of ["context", "bindings"]) {
+    const v = params[name];
+    if (v === void 0) continue;
+    if (!isPlainObject(v)) {
+      throw new ZihinAgentError("config", `\`${name}\` must be a flat plain object.`);
+    }
+    const entries = Object.entries(v);
+    if (entries.length > MAX_FIELDS) {
+      throw new ZihinAgentError("config", `\`${name}\` accepts at most ${MAX_FIELDS} fields.`);
+    }
+    for (const [k, val] of entries) {
+      if (!FIELD_NAME_RE.test(k) || PROTOTYPE_KEYS.has(k)) {
+        throw new ZihinAgentError(
+          "config",
+          `Invalid field name in \`${name}\`: use letters, digits, \`_\` or \`-\`, starting with a letter or \`_\` (max 64 characters; \`constructor\`, \`prototype\` and \`__proto__\` are not allowed).`
+        );
+      }
+      if (typeof val === "string" && val.length > MAX_VALUE_CHARS) {
+        throw new ZihinAgentError("config", `\`${name}.${k}\` is longer than ${MAX_VALUE_CHARS} characters.`);
+      }
+      if (!isScalar(val)) {
+        throw new ZihinAgentError(
+          "config",
+          `\`${name}.${k}\` must be a string, number, boolean or null \u2014 \`${name}\` is flat (no nested objects or arrays).`
+        );
+      }
+    }
+    if (JSON.stringify(v).length > MAX_TOTAL_CHARS[name]) {
+      throw new ZihinAgentError("config", `\`${name}\` is longer than ${MAX_TOTAL_CHARS[name]} characters in total (as JSON).`);
+    }
+  }
+  if (params.sessionFrom !== void 0) {
+    if (!Array.isArray(params.sessionFrom) || params.sessionFrom.length > MAX_SESSION_FROM_FIELDS || params.sessionFrom.some((f) => typeof f !== "string" || !FIELD_NAME_RE.test(f) || PROTOTYPE_KEYS.has(f))) {
+      throw new ZihinAgentError("config", `\`sessionFrom\` must be an array of up to ${MAX_SESSION_FROM_FIELDS} field names.`);
+    }
+    if (params.sessionFrom.length && params.sessionId) {
+      throw new ZihinAgentError("config", "Use either `sessionId` or `sessionFrom`, not both.");
+    }
+    const available = { ...params.context, ...params.bindings };
+    const has = (f) => Object.prototype.hasOwnProperty.call(available, f) && Boolean(available[f]);
+    if (params.sessionFrom.length && !params.sessionFrom.some(has)) {
+      throw new ZihinAgentError(
+        "config",
+        `\`sessionFrom\` names ${params.sessionFrom.map((f) => `"${f}"`).join(", ")}, but none of them has a value in \`context\` or \`bindings\`.`
+      );
+    }
+  }
+}
+function requestedInputFields(params) {
+  const out = [];
+  if (params.context) out.push("context");
+  if (params.bindings) out.push("bindings");
+  if (params.sessionFrom?.length) out.push("session_from");
+  return out;
+}
+function checkInputCapability(params, chunk) {
+  const requested = requestedInputFields(params);
+  const ignored = chunk?.ignoredFields ?? [];
+  const sent = [...requested, ...params.consumerKey ? ["consumer_key"] : []];
+  const blocking = ignored.filter(
+    (f) => f.reason !== "redacted" && sent.some((name) => f.field === name || f.field.startsWith(`${name}.`))
+  );
+  const tail = "the stream was closed to cancel the turn, but the message may already be recorded in the session.";
+  if (blocking.length) {
+    const shown = blocking.slice(0, 5);
+    const more = blocking.length > shown.length ? ` (+${blocking.length - shown.length} more)` : "";
+    const what = shown.map((f) => f.reason ? `\`${f.field}\` (${f.reason})` : `\`${f.field}\``).join(", ") + more;
+    const hint = blocking.some((f) => f.reason === "reserved_key") ? " Reserved keys are names the agent engine uses internally; rename them." : blocking.some((f) => f.reason === "requires_admin_api_key") ? " These fields only apply with an admin/owner API key." : "";
+    throw new ZihinAgentError("config", `The server ignored ${what}.${hint} The answer is not used: ${tail}`, {
+      requestId: chunk?.requestId
+    });
+  }
+  if (requested.length && chunk?.acceptedFields === void 0) {
+    throw new ZihinAgentError(
+      "config",
+      `This Zihin server does not support ${requested.map((f) => `\`${f}\``).join(", ")} on /stream yet (no \`accepted_fields\` in the stream metadata) \u2014 ${tail}`,
+      { requestId: chunk?.requestId }
+    );
+  }
+  const mustAccept = chunk?.acceptedFields !== void 0 && params.consumerKey ? [...requested, "consumer_key"] : requested;
+  const notAccepted = mustAccept.filter((f) => !chunk?.acceptedFields?.includes(f));
+  if (notAccepted.length) {
+    throw new ZihinAgentError(
+      "config",
+      `The server did not accept ${notAccepted.map((f) => `\`${f}\``).join(", ")} (missing from \`accepted_fields\`) \u2014 ${tail}`,
+      { requestId: chunk?.requestId }
+    );
+  }
+}
+var TURN_EVENTS = /* @__PURE__ */ new Set(["phase", "thinking", "tool", "action_proposed", "token", "response", "metrics", "done"]);
+async function* streamAgent(cfg, rawParams) {
+  const params = snapshotStructuredInput(rawParams);
   validateParams(params);
   const callerTimeoutMs = params.options?.timeoutMs !== void 0 ? normalizeTimeoutMs(params.options.timeoutMs, "options.timeoutMs") : void 0;
   const timeoutMs = callerTimeoutMs !== void 0 ? callerTimeoutMs + DEADLINE_GRACE_MS : resolveTimeout(cfg, "stream");
   const reportedMs = callerTimeoutMs ?? timeoutMs;
   const url = `${cfg.baseUrl}/api/v2/agents/${encodeURIComponent(params.agentId)}/stream`;
+  let needsCapability = requestedInputFields(params).length > 0 || !!params.consumerKey;
+  let gated = false;
   const { response, deadline, endpoint } = await openStream({
     url,
     headers: buildHeaders(cfg.apiKey),
@@ -1011,7 +1187,14 @@ async function* streamAgent(cfg, params) {
       maxEventBytes: cfg.maxStreamEventBytes,
       maxTotalBytes: cfg.maxStreamTotalBytes
     })) {
-      yield mapEvent(e);
+      const chunk = mapEvent(e);
+      if (needsCapability) {
+        if (chunk.type === "metadata") checkInputCapability(params, chunk);
+        else if (chunk.type === "status" && chunk.phase === "GATED") gated = true;
+        else if (TURN_EVENTS.has(chunk.type) && !gated) checkInputCapability(params, void 0);
+        if (chunk.type === "metadata" || TURN_EVENTS.has(chunk.type) && !gated) needsCapability = false;
+      }
+      yield chunk;
     }
   } finally {
     deadline.dispose();
@@ -1019,6 +1202,7 @@ async function* streamAgent(cfg, params) {
 }
 function classifyStreamErrorKind(code, timedOut) {
   if (timedOut === true) return "timeout";
+  if (code === "VALIDATION_ERROR") return "config";
   if (timedOut === false) return "server";
   return /TIMEOUT/i.test(code) ? "timeout" : "server";
 }
@@ -1031,6 +1215,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 +1293,10 @@ async function invokeAgent(cfg, params) {
   let metricsChunk;
   let metadataSessionId;
   let mintedSessionId;
-  let cleanEnd = false;
+  let doneChunk;
+  let blocked;
+  let acceptedFields;
+  let ignoredFields;
   let tokenBuffer = "";
   for await (const chunk of streamAgent(cfg, params)) {
     if (keepRaw) raw.push(chunk);
@@ -1048,10 +1306,19 @@ async function invokeAgent(cfg, params) {
     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" && 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 === "metadata") {
+      if (chunk.sessionId) metadataSessionId = chunk.sessionId;
+      acceptedFields = chunk.acceptedFields;
+      ignoredFields = chunk.ignoredFields;
+    } else if (chunk.type === "session" && chunk.sessionId) mintedSessionId = chunk.sessionId;
+    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 +1327,14 @@ 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,
+        acceptedFields,
+        ignoredFields,
         raw
       };
     }
@@ -1073,13 +1343,20 @@ 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,
+    acceptedFields,
+    ignoredFields,
     raw
   };
 }
@@ -1685,6 +1962,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.6.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",