@zihin/agent-client 0.1.0 → 0.4.0

package/README.md

@@ -75,14 +75,93 @@ const exec = await zihin.getExecution({ triggerId, executionId });
 
 > O modo `sync` do trigger (`mode: 'sync'`) responde 200 + JSON na hora (`dispatchResult.agentResponse`).
 
+### Payload estruturado (não só texto)
+
+O caminho direto (`invokeAgent`) só aceita **texto** — o endpoint `/stream` do BE não tem campo de
+payload estruturado. Para disparar um agente a partir de um JSON rico, use triggers: o payload vai
+inteiro no `dispatchAgent` e o `queryExtraction` define como ele vira a mensagem do agente.
+
+```ts
+// template: compõe a mensagem a partir de campos aninhados do payload
+await zihin.findOrCreateTrigger({
+  agentId,
+  name: 'Pedidos',
+  mode: 'sync',
+  queryExtraction: { mode: 'template', template: 'Pedido {{payload.order.id}}: {{payload.order.note}}' },
+});
+
+// field (default): um campo top-level do payload
+// queryExtraction: { mode: 'field', field: 'texto' }
+// full_body: fallback do BE → payload.message || payload.query || JSON.stringify(payload)
+// queryExtraction: { mode: 'full_body' }
+
+await zihin.dispatchAgent({ triggerId, payload: { order: { id: 42, note: 'urgente' }, cliente: {...} } });
+```
+
+⚠️ O que chega ao agente é **a string extraída**, não o payload inteiro: com `field`/`template`, os
+campos que você não referenciou ficam de fora. Para levar tudo, use `full_body` — e note que ele
+só serializa o payload completo **se não houver** um campo `message`/`query` no topo (nesse caso o
+BE usa esse campo). Precisa de campos extras como contexto estruturado? Isso é `context_mapping`
+no trigger, ainda não exposto pelo núcleo — configure direto no BE.
+
 ### Ciclo de vida do trigger
 
 ```ts
 await zihin.listTriggers({ agentId });        // lista (filtros: agentId/triggerType/enabledOnly)
 await zihin.getTrigger({ triggerId });        // detalhe (inclui webhookUrl)
+await zihin.updateTrigger({ triggerId, enabled: false });          // PATCH parcial
+await zihin.updateTrigger({ triggerId, queryExtraction: { mode: 'full_body' } }); // GET+merge+PATCH
 await zihin.deleteTrigger({ triggerId });     // remove (requer key admin/owner; editor → 403)
 ```
 
+> `updateTrigger` faz GET + merge + PATCH quando você altera config (o BE substitui
+> `trigger_config` inteiro). Há uma janela entre o GET e o PATCH em que uma escrita concorrente
+> pode ser sobrescrita.
+
+## Uso — delegação assíncrona durável (tasks)
+
+Para runs que estouram o teto do host (o passo do Zapier morre em ~30s) ou que não podem depender
+da conexão viva. A task é persistida no BE, executada fora do request e o resultado notificado.
+Exige key **owner/admin** para delegar e cancelar; editor só lê.
+
+```ts
+const task = await zihin.delegateTask({
+	agentId,
+	instruction: 'Gere o relatório mensal e envie por e-mail',
+	title: 'Relatório de agosto',
+	payload: { mes: '2026-08' },          // objeto, ≤ 64KB — validado localmente
+	deadlineAt: new Date(Date.now() + 3600e3),
+});
+
+// polling: pare quando `terminal` for true — qualquer status desconhecido conta como terminal
+let dossie;
+do {
+	await new Promise((r) => setTimeout(r, 2000));
+	dossie = await zihin.getTask({ taskId: task.id });
+} while (!dossie.task.terminal);
+
+console.log(dossie.task.status, dossie.executions.at(-1)?.totalCostUsd);
+await zihin.cancelTask({ taskId: task.id, reason: 'mudou o plano' }); // 409 se já encerrou
+```
+
+`listTasks({ live: true })` devolve o board (`items` + `total`, este vindo de `meta`).
+
+## O texto que volta — e o que NÃO é resposta
+
+`AgentResult.contentSource` diz de onde veio o `content`:
+
+- **`'response'`** — o evento final do BE, que no `/stream` é sempre o modo `final` (só as mensagens
+  sem `tool_calls`). **É o texto seguro para publicar.**
+- **`'tokens'`** — o stream morreu antes do evento final e sobrou só a concatenação crua dos deltas,
+  **com a deliberação interna do modelo**. Foi exatamente isso que vazou para um lead real via
+  WhatsApp e que o BE parou de entregar. Trate como parcial de diagnóstico; não mande para fora
+  sem revisar.
+
+Um `content` vazio com `contentSource: 'response'` é decisão do BE, não lacuna — o núcleo **não**
+preenche com tokens. E quando o BE fecha o stream com `event: error` (turno morto no deadline, por
+exemplo), o núcleo **lança** (`kind: 'timeout'` para `TURN_TIMEOUT`, com `code` e `requestId`) em vez
+de devolver o parcial.
+
 ## Dropdown de agentes
 
 ```ts
@@ -93,8 +172,8 @@ const agents = await zihin.listAgents(); // GET /api/v2/agents
 ## Permissões da API key
 
 - `invokeAgent` / `streamAgent` — qualquer role.
-- `createTrigger` / `getExecution` — exigem key **admin** ou **editor** (default é admin). Keys
-  `member` recebem `ZihinAgentError` com `kind: 'auth'`.
+- `createTrigger` / `updateTrigger` / `getExecution` — exigem key **admin** ou **editor** (default é
+  admin). Keys `member` recebem `ZihinAgentError` com `kind: 'auth'`.
 
 ## Erros
 
@@ -105,10 +184,33 @@ suporte correlacionar). Erros de rede carregam a causa-raiz (`ECONNREFUSED`/`ENO
 mensagem. As mensagens redigem **só segredos** (key/Bearer/stack) — `request_id`/`trace_id` são
 preservados. Cancele com `AbortSignal` via `params.signal`.
 
+### Bloqueio comercial não é credencial errada
+
+Trial vencido, assinatura inativa e quota esgotada chegam do BE como 403/429 e, mapeados só pelo
+status, virariam "troque a key" ou "tente de novo". Têm `kind` próprio e **nunca são retentados**:
+
+| `kind` | HTTP | O que fazer |
+|---|---|---|
+| `trial_expired` | 403 | Fazer upgrade do plano — a key está certa |
+| `no_subscription` | 429 | Ativar uma assinatura — a key está certa |
+| `quota_exceeded` | 429 | Esperar o ciclo ou subir o plano — retentar não ajuda |
+
+`isCommercialBlock(body)` é exportado para quem inspeciona respostas por conta própria. O 403 comum
+(`kind: 'auth'`) significa que o **papel** da key não permite a ação — e o papel exigido varia por
+rota (editor cria trigger, mas não delega task), então a mensagem não enumera papéis.
+
+`ZihinAgentError.executionId` vem preenchido quando o BE o entrega (sucesso e erro) — é o handle para
+correlacionar com o console.
+
 ## Robustez (timeout / retry / limites)
 
-- **Timeout cobre tudo** — headers e o corpo/stream inteiro. `timeoutMs` (default 120s, igual ao cap
-  do BE) é o tempo máximo total da chamada; `AbortSignal` do chamador funciona durante todo o stream.
+- **Timeout cobre tudo** — headers e o corpo/stream inteiro. Os defaults são **por operação**
+  (`OPERATION_TIMEOUT_MS`): stream 200s, dispatch de trigger 260s, GETs curtos 35s. Cada um fica
+  ACIMA do orçamento do BE para aquela rota (SSE 180s, turno async 240s, timeout global 30s), para
+  que o desfecho do servidor chegue como erro estruturado em vez de abort cego do cliente.
+  `timeoutMs` na config sobrepõe todos; `options.timeoutMs` por chamada vai ao BE como
+  `timeout_ms` e o deadline local fica um pouco acima dele. Retentativas NÃO encolhem o deadline
+  da tentativa seguinte — o que fica limitado é o tempo gasto com retries.
 - **Retry sem duplicar efeito** — GET (idempotente) retenta em rede/429/5xx; POST com efeito
   (`invokeAgent`/`dispatchAgent`/`createTrigger`) retenta **só em 429/503** e **nunca em erro de
   rede** (o request pode ter sido processado). Backoff exponencial 1s→10s com jitter.
@@ -123,11 +225,17 @@ preservados. Cancele com `AbortSignal` via `params.signal`.
 ### Observabilidade e portabilidade
 
 - **Hooks** (opt-in, sem `console`): `onRetry(info)` (a cada retentativa, com `endpoint`/`attempt`/
-  `delayMs`/`reason`/`status`) e `onError(err)`.
+  `delayMs`/`reason`/`status`) e `onError(err)` — chamado quando uma operação falha em definitivo
+  (inclusive `aborted`; filtre por `err.kind`). Exceção lançada dentro do hook é engolida e nunca
+  mascara o erro original.
 - **`fetch` injetável** — `fetch?` na config; por padrão usa `globalThis.fetch` (Node ≥18). Um
   preflight dá erro `config` claro se não houver fetch.
 - **Portável** — sem `Buffer`; `node:crypto` só é carregado se você usar `signRequest`. Roda em Node;
-  para edge/serverless, injete `fetch` se necessário.
+  para edge/serverless, injete `fetch` se necessário. O pacote publica **CJS e ESM** (`exports` map):
+  `require()` e `import` funcionam. Duas ressalvas: no build ESM, `signRequest` precisa de Node
+  >=20.16 (`process.getBuiltinModule`) e sem isso lança `ZihinAgentError` com `kind: 'config'`; e
+  carregar **as duas formas no mesmo processo** cria duas classes `ZihinAgentError` distintas, o que
+  faz `instanceof` falhar — padronize `require` **ou** `import` para o núcleo na sua árvore de deps.
 
 ```ts
 const zihin = createClient({
@@ -140,8 +248,14 @@ const zihin = createClient({
 });
 ```
 
-> SSRF: a validação de base/callback URL é por nome de host. Com `allowCustomBaseUrl: true` um host
-> que resolva para IP privado (DNS rebinding) passa — mantenha o whitelist em ambiente sensível.
+> SSRF: a validação de base/callback/attachment URL é por **nome de host** — cobre IPv4 privado
+> (inclusive octal/hex, normalizados pela URL), IPv6 privado **por faixa de bits** (`fc00::/7`,
+> `fe80::/10`, `fec0::/10`, loopback e IPv4 embutido `::ffff:`/`::`), FQDN com ponto final e os
+> hosts de metadata de nuvem.
+>
+> **Limite importante:** é validação por nome, não por IP resolvido. Com `allowCustomBaseUrl: true`,
+> um host que **resolva** para IP privado (DNS rebinding) passa. Isto não substitui bloqueio de
+> egresso na borda de rede — mantenha o whitelist (default) em ambiente sensível.
 
 ## Segurança