@zihin/agent-client 0.6.0 → 0.6.1

package/README.md

@@ -111,6 +111,43 @@ gera **outra** sessão, e a ordem dos campos entra no hash. Chave repetida nos d
 `bindings`. Campo do `sessionFrom` que a redação alterou (no `context`) é recusado com
 `VALIDATION_ERROR` (sai como `config`): mande-o em `bindings`.
 
+### Nome do contato e sugestões de resposta (0.6.1)
+
+> Backend: zihin-agent-builder `1aa752e6` (+ migration `20261001000002`). Contra um backend
+> anterior os dois recursos só não acontecem: o turno roda normalmente.
+
+```ts
+const r = await zihin.invokeAgent({
+  agentId,
+  message: 'Quero canetas azuis',
+  consumer: { key: 'dev-cotai-1410', name: 'Fernando Produtor' }, // nome aparece nos contatos do console
+  capabilities: { blocks: ['quick_replies'] },                     // minha tela mostra sugestões
+});
+r.suggestions; // ['Caneta A', 'Caneta B'] — ou undefined quando o agente não sugeriu
+```
+
+- **`consumer: { key, name? }`** é o `consumerKey` com o nome junto. `consumer.key` e `consumerKey`
+  são o mesmo campo (mande um; se vierem os dois, têm de ser iguais) e seguem a mesma regra: só
+  valem sob API key admin/owner, e o núcleo recusa o turno se o servidor os ignorar. O nome vai como
+  `consumer_display_name` (até 255 caracteres) e vale **do presente em diante**: atualiza o
+  contato e a conversa em andamento; conversas encerradas guardam o nome da época (o histórico não
+  é reescrito). Dado pessoal: mande só o que a operação precisa ver.
+- **Uma `consumer.key` por pessoa.** A chave é a identidade: memória, bloqueio e engajamento são
+  dela. Se várias pessoas usam o mesmo canal (ex.: um WhatsApp comercial que troca de vendedor),
+  dê a cada uma a sua chave — trocar só o `name` não separa as pessoas.
+- **`capabilities: { blocks: ['quick_replies'] }`** diz que a sua tela renderiza sugestões de
+  resposta. Sem declarar, o agente nem recebe a ferramenta — nada é gerado e nada é cobrado. É um
+  **pedido**, não uma exigência: qualquer API key pode mandar, e um servidor que não o conheça só o
+  reporta em `ignoredFields` (o turno não falha). O dono do agente pode desligar as sugestões
+  (`quick_replies_enabled`), e o agente decide quando vale sugerir — nem todo turno traz.
+- **`suggestions`** (em `AgentResult` e no chunk `response`) são os rótulos do bloco `quick_replies`
+  de `blocks`, já filtrados: até 4, curtos. Tocar uma sugestão = mandar o texto dela como a próxima
+  `message`. Num turno só com sugestões, `content` vem **vazio**.
+- **Descontinuados**: `options.jitMode`, `options.temperature` e `options.maxTokens` não têm efeito no
+  `/stream` (temperatura e teto de saída são configuração do agente). Continuam sendo enviados e o
+  servidor os lista em `ignoredFields`; o núcleo emite um `ZihinDeprecationWarning` **uma vez por
+  processo** (`ZIHIN_DEP001`/`ZIHIN_DEP002`). Saem do SDK na 1.0.
+
 ## Uso — caminho assíncrono (triggers)
 
 ```ts

package/dist/index.d.mts

@@ -118,7 +118,17 @@ interface Attachment {
     type: AttachmentType;
 }
 interface InvokeOptions {
+    /**
+     * @deprecated Sem efeito: o `/stream` usa a temperatura da configuração do agente
+     * (`llm_config.temperature`, no console ou via `update_agent`). O servidor ignora o campo e o
+     * reporta em `ignoredFields`. Será retirado do SDK na 1.0.
+     */
     temperature?: number;
+    /**
+     * @deprecated Sem efeito: o teto de saída é a configuração do agente (`llm_config.max_tokens`,
+     * no console ou via `update_agent`). O servidor ignora o campo e o reporta em `ignoredFields`.
+     * Será retirado do SDK na 1.0.
+     */
     maxTokens?: number;
     /**
      * Teto do TURNO desta chamada (ms); sobrepõe o do cliente. Vai ao BE como `options.timeout_ms`
@@ -130,9 +140,41 @@ interface InvokeOptions {
      * local soma `DEADLINE_GRACE_MS` a este valor para ainda receber o desfecho do servidor.
      */
     timeoutMs?: number;
-    /** Just-in-time tool loading (Sprint 33). */
+    /**
+     * @deprecated Recurso descontinuado no servidor (ago/2026): sem efeito, reportado em
+     * `ignoredFields`. Remova-o. Será retirado do SDK na 1.0.
+     */
     jitMode?: boolean;
 }
+/** Blocos estruturados que a sua interface sabe renderizar (`capabilities.blocks`). */
+type ClientBlockType = 'quick_replies';
+/**
+ * O que a SUA tela sabe mostrar. O agente só oferece o que você declarar — sem declarar, nada é
+ * gerado e nada é cobrado. Não exige privilégio de API key.
+ */
+interface ClientCapabilities {
+    /**
+     * `quick_replies`: até 4 sugestões curtas de resposta ao fim do turno (o usuário toca e o texto
+     * vira a próxima mensagem). Chegam em `AgentResult.suggestions` (e no bloco `quick_replies` de
+     * `blocks`). O dono do agente pode desligá-las (`quick_replies_enabled`); o agente decide quando
+     * vale sugerir — nem todo turno traz sugestões.
+     */
+    blocks?: ClientBlockType[];
+}
+/** A pessoa do outro lado da conversa. Só vale sob API key **admin/owner**. */
+interface ConsumerIdentity {
+    /**
+     * Identificador estável da pessoa no SEU sistema (memória por pessoa, denylist, gate de
+     * engajamento). Para continuar conversas que um webhook já gravava, use o MESMO valor que o
+     * webhook usava. Enviado como `consumer_key`.
+     */
+    key: string;
+    /**
+     * Nome para exibição no console da Zihin (lista de contatos). Enviado como
+     * `consumer_display_name`. Dado pessoal: mande só o que a operação precisa ver.
+     */
+    name?: string;
+}
 interface InvokeAgentParams {
     /** UUID do agente (path :agent_id). */
     agentId: string;
@@ -148,6 +190,13 @@ interface InvokeAgentParams {
      * valor que o webhook usava. Enviado como `consumer_key`.
      */
     consumerKey?: string;
+    /**
+     * A pessoa do outro lado: `{ key, name? }`. `consumer.key` é o mesmo que `consumerKey` (use um
+     * dos dois; se vierem os dois, têm de ser iguais). Só vale sob API key admin/owner.
+     */
+    consumer?: ConsumerIdentity;
+    /** O que a sua interface sabe renderizar — ex.: `{ blocks: ['quick_replies'] }`. */
+    capabilities?: ClientCapabilities;
     /**
      * Contexto estruturado que o **modelo lê** — bloco de plataforma junto da mensagem do usuário
      * (não no system prompt). **Fica gravado** com a mensagem (`declared_context`) e se repete em
@@ -228,6 +277,12 @@ interface AgentResult {
         type: string;
         [k: string]: unknown;
     }>;
+    /**
+     * Sugestões de resposta do turno (bloco `quick_replies`), já extraídas de `blocks`. Só vêm se
+     * você declarou `capabilities: { blocks: ['quick_replies'] }`. O texto de cada uma é o que o
+     * usuário "diz" ao tocá-la. Num turno só com sugestões, `content` vem vazio.
+     */
+    suggestions?: string[];
     iterations?: number;
     executionTimeMs?: number;
     /** `execution_id` do turno (evento `metrics`) — handle de correlação no console/telemetria. */
@@ -377,6 +432,8 @@ type AgentStreamChunk =
         type: string;
         [k: string]: unknown;
     }>;
+    /** Sugestões de resposta (bloco `quick_replies`), extraídas de `blocks`. */
+    suggestions?: string[];
     /** Resposta ENLATADA de um gate (handoff humano, denylist, sessão suspensa) — não do agente. */
     gated?: boolean;
     data: unknown;
@@ -965,4 +1022,4 @@ declare function signRequest(payload: string, secretKey: string, timestamp?: num
  */
 declare const MAX_TASK_PAYLOAD_BYTES: number;
 
-export { type AgentOutcome, type AgentResult, type AgentStreamChunk, type AgentSummary, type Attachment, type AttachmentType, type CancelTaskParams, type CancelTaskResult, type ContextValue, 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 IgnoredField, 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 };
+export { type AgentOutcome, type AgentResult, type AgentStreamChunk, type AgentSummary, type Attachment, type AttachmentType, type CancelTaskParams, type CancelTaskResult, type ClientBlockType, type ClientCapabilities, type ConsumerIdentity, type ContextValue, 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 IgnoredField, 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

@@ -118,7 +118,17 @@ interface Attachment {
     type: AttachmentType;
 }
 interface InvokeOptions {
+    /**
+     * @deprecated Sem efeito: o `/stream` usa a temperatura da configuração do agente
+     * (`llm_config.temperature`, no console ou via `update_agent`). O servidor ignora o campo e o
+     * reporta em `ignoredFields`. Será retirado do SDK na 1.0.
+     */
     temperature?: number;
+    /**
+     * @deprecated Sem efeito: o teto de saída é a configuração do agente (`llm_config.max_tokens`,
+     * no console ou via `update_agent`). O servidor ignora o campo e o reporta em `ignoredFields`.
+     * Será retirado do SDK na 1.0.
+     */
     maxTokens?: number;
     /**
      * Teto do TURNO desta chamada (ms); sobrepõe o do cliente. Vai ao BE como `options.timeout_ms`
@@ -130,9 +140,41 @@ interface InvokeOptions {
      * local soma `DEADLINE_GRACE_MS` a este valor para ainda receber o desfecho do servidor.
      */
     timeoutMs?: number;
-    /** Just-in-time tool loading (Sprint 33). */
+    /**
+     * @deprecated Recurso descontinuado no servidor (ago/2026): sem efeito, reportado em
+     * `ignoredFields`. Remova-o. Será retirado do SDK na 1.0.
+     */
     jitMode?: boolean;
 }
+/** Blocos estruturados que a sua interface sabe renderizar (`capabilities.blocks`). */
+type ClientBlockType = 'quick_replies';
+/**
+ * O que a SUA tela sabe mostrar. O agente só oferece o que você declarar — sem declarar, nada é
+ * gerado e nada é cobrado. Não exige privilégio de API key.
+ */
+interface ClientCapabilities {
+    /**
+     * `quick_replies`: até 4 sugestões curtas de resposta ao fim do turno (o usuário toca e o texto
+     * vira a próxima mensagem). Chegam em `AgentResult.suggestions` (e no bloco `quick_replies` de
+     * `blocks`). O dono do agente pode desligá-las (`quick_replies_enabled`); o agente decide quando
+     * vale sugerir — nem todo turno traz sugestões.
+     */
+    blocks?: ClientBlockType[];
+}
+/** A pessoa do outro lado da conversa. Só vale sob API key **admin/owner**. */
+interface ConsumerIdentity {
+    /**
+     * Identificador estável da pessoa no SEU sistema (memória por pessoa, denylist, gate de
+     * engajamento). Para continuar conversas que um webhook já gravava, use o MESMO valor que o
+     * webhook usava. Enviado como `consumer_key`.
+     */
+    key: string;
+    /**
+     * Nome para exibição no console da Zihin (lista de contatos). Enviado como
+     * `consumer_display_name`. Dado pessoal: mande só o que a operação precisa ver.
+     */
+    name?: string;
+}
 interface InvokeAgentParams {
     /** UUID do agente (path :agent_id). */
     agentId: string;
@@ -148,6 +190,13 @@ interface InvokeAgentParams {
      * valor que o webhook usava. Enviado como `consumer_key`.
      */
     consumerKey?: string;
+    /**
+     * A pessoa do outro lado: `{ key, name? }`. `consumer.key` é o mesmo que `consumerKey` (use um
+     * dos dois; se vierem os dois, têm de ser iguais). Só vale sob API key admin/owner.
+     */
+    consumer?: ConsumerIdentity;
+    /** O que a sua interface sabe renderizar — ex.: `{ blocks: ['quick_replies'] }`. */
+    capabilities?: ClientCapabilities;
     /**
      * Contexto estruturado que o **modelo lê** — bloco de plataforma junto da mensagem do usuário
      * (não no system prompt). **Fica gravado** com a mensagem (`declared_context`) e se repete em
@@ -228,6 +277,12 @@ interface AgentResult {
         type: string;
         [k: string]: unknown;
     }>;
+    /**
+     * Sugestões de resposta do turno (bloco `quick_replies`), já extraídas de `blocks`. Só vêm se
+     * você declarou `capabilities: { blocks: ['quick_replies'] }`. O texto de cada uma é o que o
+     * usuário "diz" ao tocá-la. Num turno só com sugestões, `content` vem vazio.
+     */
+    suggestions?: string[];
     iterations?: number;
     executionTimeMs?: number;
     /** `execution_id` do turno (evento `metrics`) — handle de correlação no console/telemetria. */
@@ -377,6 +432,8 @@ type AgentStreamChunk =
         type: string;
         [k: string]: unknown;
     }>;
+    /** Sugestões de resposta (bloco `quick_replies`), extraídas de `blocks`. */
+    suggestions?: string[];
     /** Resposta ENLATADA de um gate (handoff humano, denylist, sessão suspensa) — não do agente. */
     gated?: boolean;
     data: unknown;
@@ -965,4 +1022,4 @@ declare function signRequest(payload: string, secretKey: string, timestamp?: num
  */
 declare const MAX_TASK_PAYLOAD_BYTES: number;
 
-export { type AgentOutcome, type AgentResult, type AgentStreamChunk, type AgentSummary, type Attachment, type AttachmentType, type CancelTaskParams, type CancelTaskResult, type ContextValue, 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 IgnoredField, 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 };
+export { type AgentOutcome, type AgentResult, type AgentStreamChunk, type AgentSummary, type Attachment, type AttachmentType, type CancelTaskParams, type CancelTaskResult, type ClientBlockType, type ClientCapabilities, type ConsumerIdentity, type ContextValue, 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 IgnoredField, 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

@@ -89,6 +89,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 = [
@@ -923,6 +937,16 @@ 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 mapEvent(e) {
   const d = rec(e.data);
   switch (e.event) {
@@ -989,6 +1013,7 @@ 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),
         data: e.data
       };
     case "metrics": {
@@ -1012,6 +1037,8 @@ function buildRequestBody(params, normalizedTimeoutMs) {
   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.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 +1081,7 @@ function validateParams(params) {
     }
   }
   validateStructuredInput(params);
+  warnDeprecatedOptions(params);
   if (params.options?.timeoutMs !== void 0) {
     normalizeTimeoutMs(params.options.timeoutMs, "options.timeoutMs");
   }
@@ -1064,6 +1092,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 +1115,36 @@ 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;
 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) {
@@ -1095,6 +1162,24 @@ function validateStructuredInput(params) {
   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;
@@ -1382,6 +1467,7 @@ 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,

package/dist/index.mjs

@@ -55,6 +55,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 = [
@@ -889,6 +903,16 @@ 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 mapEvent(e) {
   const d = rec(e.data);
   switch (e.event) {
@@ -955,6 +979,7 @@ 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),
         data: e.data
       };
     case "metrics": {
@@ -978,6 +1003,8 @@ function buildRequestBody(params, normalizedTimeoutMs) {
   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.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];
@@ -1020,6 +1047,7 @@ function validateParams(params) {
     }
   }
   validateStructuredInput(params);
+  warnDeprecatedOptions(params);
   if (params.options?.timeoutMs !== void 0) {
     normalizeTimeoutMs(params.options.timeoutMs, "options.timeoutMs");
   }
@@ -1030,6 +1058,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 };
@@ -1037,13 +1081,36 @@ 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;
 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) {
@@ -1061,6 +1128,24 @@ function validateStructuredInput(params) {
   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;
@@ -1348,6 +1433,7 @@ 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,

package/package.json

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