@zihin/agent-client 0.5.0 → 0.6.0

package/README.md

@@ -50,6 +50,67 @@ for await (const chunk of zihin.streamAgent({ agentId, message: 'Olá' })) {
 }
 ```
 
+### Contexto estruturado, identidade e sessão derivada (0.6)
+
+> Backend: zihin-agent-builder#669 + #676, em produção desde 01/10/2026. Contra um backend
+> anterior, o núcleo **recusa** o turno em vez de rodá-lo sem os campos (ver abaixo).
+
+```ts
+await zihin.invokeAgent({
+  agentId,
+  message: 'Qual o status do meu pedido?',
+  consumerKey: '5511999990000',             // quem é a pessoa — só dígitos, como o webhook grava o telefone
+  context: { cliente: 'Ana', plano: 'pro' }, // o MODELO lê (bloco junto da mensagem do usuário)
+  bindings: { hashFornecedor: 'f-81c2' },    // só as TOOLS recebem; nunca vai ao prompt
+  sessionFrom: ['hashFornecedor'],           // deriva o session_id destes campos
+});
+```
+
+| Campo | Quem vê | Para quê |
+|---|---|---|
+| `context` | modelo + tools | dados que o agente deve considerar na resposta |
+| `bindings` | só tools | ids internos, chaves de busca — nada que o modelo precise ler |
+| `metadata` | ninguém no turno | rastreio opaco (`traceId`, `correlationId`) |
+
+- **Credencial não vai em nenhum deles.** Use um secret do tenant.
+- `context` **fica gravado** junto da mensagem (`declared_context`) e o bloco se repete em toda
+  mensagem do usuário, para o prompt cache ver os mesmos bytes a cada turno. O BE redige segredos
+  no `context` por nome de chave e por formato de valor, e avisa: `ignoredFields` traz
+  `{ field: 'context.<campo>', reason: 'redacted' }`. O campo segue aceito, com o valor alterado; o
+  núcleo **não** recusa o turno, só repassa o aviso. `bindings` **não é gravado nem redigido**: só
+  existe no contexto das tools durante o turno.
+  > Backends anteriores ao zihin-agent-builder#678 redigiam sem aviso e casavam `sk-…` dentro de
+  > valores comuns (`task-1234` → `ta[REDACTED]`). Contra eles, mande ids de tool e de sessão em
+  > `bindings`.
+- `context` e `bindings` são **planos** (só string/number/boolean/null). Os tetos são os do BE,
+  checados no cliente antes de gastar turno: até 50 campos; nome `^[A-Za-z_][A-Za-z0-9_-]{0,63}$`;
+  valor de texto até 2.000 caracteres; total (JSON) até **2.000** no `context` e 16.000 no
+  `bindings`. `sessionFrom` aceita de 1 a 5 nomes.
+- `context`, `bindings`, `sessionFrom` e `consumerKey` só valem sob API key **admin/owner**.
+  `metadata` vale com qualquer key.
+- **Campo descartado não passa em silêncio**: se você mandou `context`/`bindings`/`sessionFrom` e o evento
+  `metadata` não trouxe `accepted_fields` (backend antigo) ou trouxe o campo em `ignored_fields`, o
+  núcleo lança `ZihinAgentError('config')` nomeando o campo e o motivo, e fecha o stream para
+  cancelar o turno. A resposta não é usada, mas a mensagem pode já estar gravada: o turno barrado
+  por gate (handoff, denylist) grava a troca mesmo recusado, então **reenviar depois de corrigir gera
+  duas linhas no histórico** da conversa. Motivos que recusam: `requires_admin_api_key` (JWT ou key
+  sem papel) e `reserved_key` (por chave, ex. `context.branch`: nome reservado do motor, renomeie).
+  `redacted` só avisa (ver acima). Todo campo
+  pedido precisa estar em `accepted_fields` (`consumer_key` também, quando o BE publica a lista).
+  Erro de validação do BE (`VALIDATION_ERROR` no stream) também sai como `config`. `AgentResult.acceptedFields`/`ignoredFields` mostram o que
+  o BE fez; `options.temperature`/`maxTokens` aparecem em `ignoredFields` sem bloquear (o `/stream`
+  não os aplica).
+- `consumerKey` precisa ser o **mesmo valor** que o webhook gravava, para continuar as conversas dele.
+
+**Migrando de webhook `derive`**: um trigger com `session: { derive: ['hashFornecedor'] }` e
+payload `{ hashFornecedor: 'f-81c2', ... }` vira `sessionFrom: ['hashFornecedor']` com o valor em
+`bindings` (ou em `context`, se o modelo deve lê-lo). O BE usa a mesma função de derivação, então o
+mesmo valor cai no **mesmo** `session_id`. `sessionFrom` não combina com `sessionId`. Como no
+webhook: basta **um** campo presente (`0`, `false` e `''` contam como ausentes), um conjunto parcial
+gera **outra** sessão, e a ordem dos campos entra no hash. Chave repetida nos dois: vale o valor de
+`bindings`. Campo do `sessionFrom` que a redação alterou (no `context`) é recusado com
+`VALIDATION_ERROR` (sai como `config`): mande-o em `bindings`.
+
 ## Uso — caminho assíncrono (triggers)
 
 ```ts

package/dist/index.d.mts

@@ -140,8 +140,35 @@ interface InvokeAgentParams {
     message?: string;
     /** Anexos multimodais. `message` OU `attachments` é obrigatório. */
     attachments?: Attachment[];
-    /** Continuidade de conversa (Supabase agent_sessions). */
+    /** Continuidade de conversa (Supabase agent_sessions). Não combina com `sessionFrom`. */
     sessionId?: string;
+    /**
+     * Identidade da pessoa do outro lado (memória por pessoa, denylist, gate de engajamento). Só vale
+     * sob API key **admin/owner**. Para continuar conversas que um webhook já gravava, use o MESMO
+     * valor que o webhook usava. Enviado como `consumer_key`.
+     */
+    consumerKey?: string;
+    /**
+     * 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
+     * todo turno; o BE redige segredos por nome de chave E por formato de valor (ex.: `sk-…`), o
+     * que pode alterar valores legítimos — ids que vão a tools ou ao `sessionFrom` ficam melhor em
+     * `bindings`. Plano, só escalares. Tools também o recebem. Só vale sob key admin/owner.
+     * ⚠️ Credencial não vai aqui nem em `bindings`: use um secret do tenant.
+     */
+    context?: Record<string, ContextValue>;
+    /**
+     * Valores que **só as tools** recebem — nunca vão ao prompt (ex.: id interno de fornecedor).
+     * Plano, só escalares; **nunca gravado** nem redigido (vive só no contexto das tools durante o
+     * turno). Só vale sob key admin/owner.
+     */
+    bindings?: Record<string, ContextValue>;
+    /**
+     * Deriva o `session_id` dos valores destes campos de `context ∪ bindings`, com a MESMA função
+     * do webhook (`derive: [campo]`) — o mesmo valor cai na mesma sessão pelos dois caminhos. Não
+     * combina com `sessionId`. O id derivado volta em `AgentResult.sessionId`.
+     */
+    sessionFrom?: string[];
     options?: InvokeOptions;
     metadata?: {
         traceId?: string;
@@ -156,6 +183,15 @@ interface InvokeAgentParams {
      */
     includeRaw?: boolean;
 }
+/** Valor aceito em `context`/`bindings`: plano e escalar (regra 8 do contrato de entrada). */
+type ContextValue = string | number | boolean | null;
+/** Campo que o BE recebeu e NÃO aplicou (evento `metadata.ignored_fields`). */
+interface IgnoredField {
+    /** Nome no fio (`context`, `bindings`, `session_from`, `consumer_key`, `options.temperature`…). */
+    field: string;
+    /** Motivo reportado pelo BE (ex.: papel da key insuficiente), quando houver. */
+    reason?: string;
+}
 interface Usage {
     inputTokens?: number;
     outputTokens?: number;
@@ -196,6 +232,10 @@ interface AgentResult {
     executionTimeMs?: number;
     /** `execution_id` do turno (evento `metrics`) — handle de correlação no console/telemetria. */
     executionId?: string;
+    /** Campos do pedido que o BE aplicou (`metadata.accepted_fields`). Ausente = backend antigo. */
+    acceptedFields?: string[];
+    /** Campos do pedido que o BE recebeu e ignorou (`metadata.ignored_fields`). */
+    ignoredFields?: IgnoredField[];
     /**
      * `true` = o `content` é a resposta ENLATADA de um gate da plataforma (conversa em atendimento
      * humano, consumidor bloqueado, sessão suspensa), não do agente: nenhum modelo rodou. Em canal
@@ -234,11 +274,20 @@ type TimeoutClock = 'turn' | 'first_signal' | 'idle' | 'call' | (string & {});
  * metadata, status, attachments, phase, thinking, tool, action_proposed, token,
  * warning, response, metrics.
  */
-type AgentStreamChunk = {
+type AgentStreamChunk = 
+/**
+ * Abertura do stream. `acceptedFields`/`ignoredFields` dizem o que o BE fez com cada campo do
+ * pedido (ausentes = backend anterior ao contrato de entrada). Se o chamador mandou
+ * `context`/`bindings`/`sessionFrom` e o BE não os aceitou, o `streamAgent` lança
+ * `ZihinAgentError('config')` ANTES de entregar este chunk — nunca segue em silêncio.
+ */
+{
     type: 'metadata';
     requestId?: string;
     agentId?: string;
     sessionId?: string;
+    acceptedFields?: string[];
+    ignoredFields?: IgnoredField[];
     data: unknown;
 }
 /** `blocked` = motivo do bloqueio do turno (`agent_paused`, `budget_exceeded`…), quando houver. */
@@ -762,7 +811,7 @@ declare function createClient(config: ZihinClientConfig): ZihinAgentClient;
  * O regex no nome só vale como FALLBACK para backends que ainda não emitem `timed_out`
  * (self-hosted/antigos). Some numa major futura, depois do rename no BE.
  */
-declare function classifyStreamErrorKind(code: string, timedOut?: boolean): 'timeout' | 'server';
+declare function classifyStreamErrorKind(code: string, timedOut?: boolean): 'timeout' | 'server' | 'config';
 /**
  * Converte o chunk `type: 'error'` (evento terminal do BE) num `ZihinAgentError` — a MESMA regra
  * que o `invokeAgent` aplica, exportada para quem consome `streamAgent` direto (o adapter do
@@ -916,4 +965,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 CreateTriggerParams, DEADLINE_GRACE_MS, DEFAULT_LIMITS, type DelegateTaskParams, type DeleteTriggerParams, type DispatchAgentParams, type DispatchResult, type ExecutionStatus, type FindOrCreateResult, type GetExecutionParams, type GetTaskParams, type GetTriggerParams, type InvokeAgentParams, type InvokeOptions, type ListTasksParams, type ListTriggersParams, MAX_TASK_PAYLOAD_BYTES, OPERATION_TIMEOUT_MS, type QueryExtraction, type ResponseTransformMode, type RetryInfo, type SignedRequestHeaders, type Source, type TaskDossier, type TaskExecution, type TaskInfo, type TaskListPage, type 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 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

@@ -140,8 +140,35 @@ interface InvokeAgentParams {
     message?: string;
     /** Anexos multimodais. `message` OU `attachments` é obrigatório. */
     attachments?: Attachment[];
-    /** Continuidade de conversa (Supabase agent_sessions). */
+    /** Continuidade de conversa (Supabase agent_sessions). Não combina com `sessionFrom`. */
     sessionId?: string;
+    /**
+     * Identidade da pessoa do outro lado (memória por pessoa, denylist, gate de engajamento). Só vale
+     * sob API key **admin/owner**. Para continuar conversas que um webhook já gravava, use o MESMO
+     * valor que o webhook usava. Enviado como `consumer_key`.
+     */
+    consumerKey?: string;
+    /**
+     * 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
+     * todo turno; o BE redige segredos por nome de chave E por formato de valor (ex.: `sk-…`), o
+     * que pode alterar valores legítimos — ids que vão a tools ou ao `sessionFrom` ficam melhor em
+     * `bindings`. Plano, só escalares. Tools também o recebem. Só vale sob key admin/owner.
+     * ⚠️ Credencial não vai aqui nem em `bindings`: use um secret do tenant.
+     */
+    context?: Record<string, ContextValue>;
+    /**
+     * Valores que **só as tools** recebem — nunca vão ao prompt (ex.: id interno de fornecedor).
+     * Plano, só escalares; **nunca gravado** nem redigido (vive só no contexto das tools durante o
+     * turno). Só vale sob key admin/owner.
+     */
+    bindings?: Record<string, ContextValue>;
+    /**
+     * Deriva o `session_id` dos valores destes campos de `context ∪ bindings`, com a MESMA função
+     * do webhook (`derive: [campo]`) — o mesmo valor cai na mesma sessão pelos dois caminhos. Não
+     * combina com `sessionId`. O id derivado volta em `AgentResult.sessionId`.
+     */
+    sessionFrom?: string[];
     options?: InvokeOptions;
     metadata?: {
         traceId?: string;
@@ -156,6 +183,15 @@ interface InvokeAgentParams {
      */
     includeRaw?: boolean;
 }
+/** Valor aceito em `context`/`bindings`: plano e escalar (regra 8 do contrato de entrada). */
+type ContextValue = string | number | boolean | null;
+/** Campo que o BE recebeu e NÃO aplicou (evento `metadata.ignored_fields`). */
+interface IgnoredField {
+    /** Nome no fio (`context`, `bindings`, `session_from`, `consumer_key`, `options.temperature`…). */
+    field: string;
+    /** Motivo reportado pelo BE (ex.: papel da key insuficiente), quando houver. */
+    reason?: string;
+}
 interface Usage {
     inputTokens?: number;
     outputTokens?: number;
@@ -196,6 +232,10 @@ interface AgentResult {
     executionTimeMs?: number;
     /** `execution_id` do turno (evento `metrics`) — handle de correlação no console/telemetria. */
     executionId?: string;
+    /** Campos do pedido que o BE aplicou (`metadata.accepted_fields`). Ausente = backend antigo. */
+    acceptedFields?: string[];
+    /** Campos do pedido que o BE recebeu e ignorou (`metadata.ignored_fields`). */
+    ignoredFields?: IgnoredField[];
     /**
      * `true` = o `content` é a resposta ENLATADA de um gate da plataforma (conversa em atendimento
      * humano, consumidor bloqueado, sessão suspensa), não do agente: nenhum modelo rodou. Em canal
@@ -234,11 +274,20 @@ type TimeoutClock = 'turn' | 'first_signal' | 'idle' | 'call' | (string & {});
  * metadata, status, attachments, phase, thinking, tool, action_proposed, token,
  * warning, response, metrics.
  */
-type AgentStreamChunk = {
+type AgentStreamChunk = 
+/**
+ * Abertura do stream. `acceptedFields`/`ignoredFields` dizem o que o BE fez com cada campo do
+ * pedido (ausentes = backend anterior ao contrato de entrada). Se o chamador mandou
+ * `context`/`bindings`/`sessionFrom` e o BE não os aceitou, o `streamAgent` lança
+ * `ZihinAgentError('config')` ANTES de entregar este chunk — nunca segue em silêncio.
+ */
+{
     type: 'metadata';
     requestId?: string;
     agentId?: string;
     sessionId?: string;
+    acceptedFields?: string[];
+    ignoredFields?: IgnoredField[];
     data: unknown;
 }
 /** `blocked` = motivo do bloqueio do turno (`agent_paused`, `budget_exceeded`…), quando houver. */
@@ -762,7 +811,7 @@ declare function createClient(config: ZihinClientConfig): ZihinAgentClient;
  * O regex no nome só vale como FALLBACK para backends que ainda não emitem `timed_out`
  * (self-hosted/antigos). Some numa major futura, depois do rename no BE.
  */
-declare function classifyStreamErrorKind(code: string, timedOut?: boolean): 'timeout' | 'server';
+declare function classifyStreamErrorKind(code: string, timedOut?: boolean): 'timeout' | 'server' | 'config';
 /**
  * Converte o chunk `type: 'error'` (evento terminal do BE) num `ZihinAgentError` — a MESMA regra
  * que o `invokeAgent` aplica, exportada para quem consome `streamAgent` direto (o adapter do
@@ -916,4 +965,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 CreateTriggerParams, DEADLINE_GRACE_MS, DEFAULT_LIMITS, type DelegateTaskParams, type DeleteTriggerParams, type DispatchAgentParams, type DispatchResult, type ExecutionStatus, type FindOrCreateResult, type GetExecutionParams, type GetTaskParams, type GetTriggerParams, type InvokeAgentParams, type InvokeOptions, type ListTasksParams, type ListTriggersParams, MAX_TASK_PAYLOAD_BYTES, OPERATION_TIMEOUT_MS, type QueryExtraction, type ResponseTransformMode, type RetryInfo, type SignedRequestHeaders, type Source, type TaskDossier, type TaskExecution, type TaskInfo, type TaskListPage, type 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 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

@@ -910,6 +910,19 @@ 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) {
@@ -919,6 +932,8 @@ function mapEvent(e) {
         requestId: safeId(d.request_id),
         agentId: str(d.agent_id),
         sessionId: safeId(d.session_id),
+        acceptedFields: parseAcceptedFields(d.accepted_fields),
+        ignoredFields: parseIgnoredFields(d.ignored_fields),
         data: e.data
       };
     case "status":
@@ -996,6 +1011,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 }));
   }
@@ -1034,6 +1053,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");
   }
@@ -1044,12 +1064,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),
@@ -1077,7 +1221,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();
@@ -1085,6 +1236,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";
 }
@@ -1177,6 +1329,8 @@ async function invokeAgent(cfg, params) {
   let mintedSessionId;
   let doneChunk;
   let blocked;
+  let acceptedFields;
+  let ignoredFields;
   let tokenBuffer = "";
   for await (const chunk of streamAgent(cfg, params)) {
     if (keepRaw) raw.push(chunk);
@@ -1186,8 +1340,11 @@ 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 === "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;
   }
@@ -1210,6 +1367,8 @@ async function invokeAgent(cfg, params) {
         iterations: metricsChunk?.iterations,
         executionTimeMs: metricsChunk?.executionTimeMs,
         executionId,
+        acceptedFields,
+        ignoredFields,
         raw
       };
     }
@@ -1230,6 +1389,8 @@ async function invokeAgent(cfg, params) {
     outcome: doneChunk?.outcome,
     truncated: doneChunk?.truncated,
     finishReason: doneChunk?.finishReason,
+    acceptedFields,
+    ignoredFields,
     raw
   };
 }

package/dist/index.mjs

@@ -876,6 +876,19 @@ 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) {
@@ -885,6 +898,8 @@ function mapEvent(e) {
         requestId: safeId(d.request_id),
         agentId: str(d.agent_id),
         sessionId: safeId(d.session_id),
+        acceptedFields: parseAcceptedFields(d.accepted_fields),
+        ignoredFields: parseIgnoredFields(d.ignored_fields),
         data: e.data
       };
     case "status":
@@ -962,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 }));
   }
@@ -1000,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");
   }
@@ -1010,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),
@@ -1043,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();
@@ -1051,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";
 }
@@ -1143,6 +1295,8 @@ async function invokeAgent(cfg, params) {
   let mintedSessionId;
   let doneChunk;
   let blocked;
+  let acceptedFields;
+  let ignoredFields;
   let tokenBuffer = "";
   for await (const chunk of streamAgent(cfg, params)) {
     if (keepRaw) raw.push(chunk);
@@ -1152,8 +1306,11 @@ 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 === "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;
   }
@@ -1176,6 +1333,8 @@ async function invokeAgent(cfg, params) {
         iterations: metricsChunk?.iterations,
         executionTimeMs: metricsChunk?.executionTimeMs,
         executionId,
+        acceptedFields,
+        ignoredFields,
         raw
       };
     }
@@ -1196,6 +1355,8 @@ async function invokeAgent(cfg, params) {
     outcome: doneChunk?.outcome,
     truncated: doneChunk?.truncated,
     finishReason: doneChunk?.finishReason,
+    acceptedFields,
+    ignoredFields,
     raw
   };
 }

package/package.json

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