hobots 2.4.0 → 3.2.0

package/README.md

@@ -1,11 +1,9 @@
 # hobots
 
-SDK JavaScript/TypeScript da **Hobots** para instrumentar agentes (RPAs) e integrações.
+SDK JavaScript/TypeScript da **Hobots** para robôs (RPAs) e integrações. **Tudo é uma task**: você registra o que o robô faz e a plataforma passa a receber logs, itens processados, progresso, prints, erros e o "estou vivo" do robô.
 
-- **Telemetria** — o que o programa **emite** sozinho: erros com stack trace (módulo **Issues** do app), performance (transactions/etapas) e heartbeats de uptime (módulo **Agentes**).
-- **Tasks** — execução **sob demanda**: o agente faz polling no app da Hobots, executa handlers registrados e reporta status e logs (módulo **Solicitações**).
-
-**Um único import e um único `init()`** cobrem as duas capabilities. Cliente HTTP puro, **sem dependências de runtime**. Requer **Node 18+** (usa o `fetch` global); a telemetria também roda no browser para captura de erros.
+- **`hobots.register(task, handler)`** — **sob demanda**: o robô fica online aguardando **solicitações** criadas no app (formulários e agendamentos) e executa o handler a cada uma. Módulo **Solicitações**.
+- **`hobots.start(task, handler)`** — **sempre ligado**: o robô abre a própria execução ao iniciar e roda o handler (o seu loop) dentro dela; a plataforma só recebe logs, itens e progresso. Sem formulário, sem solicitante.
 
 ---
 
@@ -17,430 +15,181 @@ npm install hobots
 ```
 
 ```js
-import * as Hobots from 'hobots'; // um import só — telemetria e tasks
+import hobots from 'hobots'; // ou: import { hobots, register, start } from 'hobots'
 ```
 
-Também funciona em CommonJS: `const Hobots = require('hobots')`.
+CommonJS: `const { hobots } = require('hobots')`.
 
 ---
 
-## Um SDK, duas capabilities, um `init()`
-
-O SDK expõe **duas capabilities** autenticadas pelo **mesmo Client Secret do agente**, configuradas em um único `init()`:
-
-| Capability | Como habilita | Para quê | Ciclo de vida |
-| --- | --- | --- | --- |
-| **Telemetria** | sempre ativa no `init()` | O que o programa emite sozinho: erros, transactions/etapas, heartbeat. | Timers `unref`'d — **não** segura o processo. Chame `close()` no fim. |
-| **Tasks** | `tasks: true` (ou opções) no `init()` | Execução remota sob demanda via polling. | `start()` **segura o processo vivo** até `stop()`/`close()`. |
-
-Você usa **uma, outra ou as duas**:
-
-- Só saber se o robô quebrou, quanto demora e se está vivo? → `init({ clientSecret, heartbeat: true })`.
-- Disparar o robô sob demanda a partir de um formulário no app? → `init({ clientSecret, tasks: true })` + `register()` + `start()`.
-- Ambos? Passe `heartbeat` e `tasks` no mesmo `init()` — o `instanceId` é a identidade única, e os dois canais convergem em **um agente** no painel. Com `tasks: true`, o heartbeat é **opcional**: o próprio poll de tasks já marca a presença do agente.
+## Em 30 segundos
 
-```js
-Hobots.init({
-  clientSecret: 'hb_<64 hex>',
-  instanceId: 'vm-cliente-01',
-  heartbeat: true,                              // telemetria: "estou vivo" a cada 30s
-  tasks: { pollIntervalMs: 2_000 },             // execução sob demanda
-});
-
-Hobots.register('processar-nfe', async (params, ctx) => {
-  ctx.log.info('começando…');
-  ctx.log.info('12 notas processadas'); // o retorno do handler é ignorado — reporte por log
-});
-
-Hobots.start(); // inicia o polling de tasks (segura o processo vivo)
-```
-
----
-
-## O Client Secret
-
-Cada agente tem **um único Client Secret** — a mesma credencial autentica a telemetria **e** as tasks:
-
-```
-hb_<64 hex>
-```
-
-A credencial é **secreta** e viaja sempre no header `Authorization: Bearer` — nunca na URL. Copie o Client Secret no app, em **Configurações → Agentes** — os snippets de integração já vêm prontos. O SDK fala com a API oficial `https://api2.hobots.app` automaticamente; em desenvolvimento, aponte para outro host com a env `HOBOTS_API_URL` (ex.: `HOBOTS_API_URL=http://localhost:3001`).
-
----
-
-## Telemetria
-
-Todas as funções abaixo são **no-op seguras** se `Hobots.init()` não foi chamado (com aviso no console).
-
-### `init(options)`
-
-Inicialize **uma vez**, o mais cedo possível no processo. Cria o cliente, instala handlers globais de erro (a menos que `captureUnhandled: false`) e inicia o heartbeat se configurado.
-
-```js
-Hobots.init({
-  clientSecret: 'hb_<64 hex>',
-  environment: 'production',
-  release: 'robo-nfe@1.4.2',
-  instanceId: 'vm-cliente-01',
-  tags: { squad: 'automacoes' },
-  heartbeat: true, // "estou vivo" a cada 30s
-});
-```
-
-| Opção | Tipo | Default | Descrição |
-| --- | --- | --- | --- |
-| `clientSecret` | `string` | **obrigatório** | o Client Secret do agente (`hb_<64 hex>`), copiado em **Configurações → Agentes** |
-| `environment` | `string` | `'production'` | ambiente lógico |
-| `release` | `string` | — | versão do programa, ex. `robo-nfe@1.4.2` |
-| `instanceId` | `string` | **obrigatório** | identidade única da instância — heartbeat e poll de tasks convergem nela |
-| `tags` | `Record<string,string>` | — | tags aplicadas a todos os eventos |
-| `sampleRate` | `number` | `1` | amostragem de erros (0..1) |
-| `tracesSampleRate` | `number` | `1` | amostragem de transactions (0..1) |
-| `maxBreadcrumbs` | `number` | `100` | tamanho do buffer de breadcrumbs |
-| `captureUnhandled` | `boolean` | `true` | handlers globais de erro (`uncaughtException`/`unhandledRejection`) |
-| `machineMetrics` | `boolean` | `true` | CPU/memória/disco no heartbeat, no poll e em `contexts.machine` dos eventos |
-| `heartbeat` | `boolean \| HeartbeatOptions` | `false` | heartbeat periódico (`true` usa defaults) |
-| `tasks` | `boolean \| TasksOptions` | `false` | habilita a execução sob demanda (`true` usa defaults) — veja [Tasks](#tasks-execução-sob-demanda) |
-| `beforeSend` | `(event) => event \| null` | — | edita/descarta evento (retorne `null` para descartar) |
-| `debug` | `boolean` | `false` | loga atividade do SDK |
-| `flushIntervalMs` | `number` | `2000` | intervalo do flush automático do transport |
-| `maxBatchSize` | `number` | `10` | itens por envelope antes do flush imediato |
-
-### Captura de erros e mensagens
-
-```js
-try {
-  await processarNota(nota);
-} catch (error) {
-  Hobots.captureException(error, {
-    type: 'error',
-    tags: { cliente: 'acme' },
-    fingerprint: ['sefaz-timeout'], // agrupa manualmente; sem isso o servidor agrupa pelo stack
-  });
-  throw error;
-}
-
-Hobots.captureMessage('Lote processado com sucesso', 'success');
-```
-
-Ambas retornam o `event_id` (ou `undefined` se não inicializado). O hint aceita `type`, `tags`, `extra` e `fingerprint`. Erros **não tratados** são capturados e flushados automaticamente antes do processo sair — desligue com `captureUnhandled: false`. Os eventos aparecem agrupados em issues no módulo **Issues** do app.
-
-`EventType = 'fatal' | 'error' | 'warning' | 'success'`. Não há `'info'`/`'debug'`: narração não abre issue — para isso existem o log da execução e as breadcrumbs. Use `'success'` para reportar itens concluídos com êxito — contam como eventos, mas **não** viram issue nem disparam alertas.
-
-### Breadcrumbs
-
-Trilha do que aconteceu antes do erro; enviada junto do próximo evento (buffer limitado por `maxBreadcrumbs`, mais antigos descartados).
-
-```js
-Hobots.addBreadcrumb({ category: 'nfe', message: 'Baixou XML da nota 123', level: 'info' });
+```bash
+export HOBOTS_CLIENT_SECRET=hb_<64 hex>   # Configurações → Agentes
+export HOBOTS_INSTANCE_ID=vm-cliente-01   # opcional — default: hostname da máquina
+export HOBOTS_ENVIRONMENT=staging         # opcional — default: production
 ```
 
-A lista **não** é limpa ao enviar um evento e é global. Conceito: [Breadcrumb](./docs/concepts.md#breadcrumb).
-
-### Escopo: tags, usuário, contexto, extras
-
-Dados anexados a **todos** os eventos seguintes:
-
 ```js
-Hobots.setTag('regiao', 'nordeste');
-Hobots.setTags({ squad: 'automacoes', cliente: 'acme' });
-Hobots.setUser({ id: 'op-42', email: 'op@acme.com' });
-Hobots.setContext('vm', { cpu: 4, ram: '8GB' });
-Hobots.setExtra('ultimoLote', 128);
-```
-
-Para um escopo **isolado** (sem vazar para o global), use `withScope`:
+import hobots from 'hobots';
 
-```js
-Hobots.withScope((scope) => {
-  scope.setTag('lote', '128').setFingerprint(['reprocessamento']);
-  Hobots.captureMessage('Reprocessando lote 128');
+// sob demanda: uma execução por solicitação do app (o task_slug casa com o formulário)
+hobots.register('processar-nfe', async params => {
+  hobots.log.info(`lote ${params.lote}`);
+  hobots.progress.total(params.notas.length);
+  for (const nota of params.notas) {
+    await baixar(nota);
+    hobots.items.succeeded({ numero_nota: nota }, { id: nota });
+    hobots.progress.advance();
+  }
 });
-```
-
-### Performance: transactions e etapas
-
-```js
-const tx = Hobots.startTransaction('processar-lote', 'rpa.job');
-
-const step = tx.startChild('http.client', 'GET /api/notas');
-await api.buscarNotas();
-step.setData('notas', 42).finish();
-
-const filho = step.startChild('db.query', 'INSERT INTO notas'); // etapas aninham
-await gravar();
-filho.finish();
-
-tx.setStatus('ok');  // ou 'error'
-tx.finish();         // só aqui a transaction é enviada (respeitando tracesSampleRate)
-```
 
-- `startChild(op?, description?)` existe em `Transaction` **e** `Step` (aninhamento arbitrário).
-- Métodos encadeáveis: `setStatus`, `setData` (step), `setTag`/`setName` (transaction).
-- `finish()` na transaction fecha as etapas abertas e envia o payload; nada é enviado se ela não foi amostrada. A amostragem é decidida no `startTransaction()`.
-
-Dentro de um handler de task, `startTransaction()` **retorna a transaction da própria run** (`ctx.tx`) em vez de criar uma segunda — cada execução tem exatamente **uma** transaction. Conceitos: [Transaction](./docs/concepts.md#transaction) · [Step](./docs/concepts.md#step).
-
-### Heartbeat (uptime)
-
-Bate "estou vivo" periodicamente; o servidor acusa o robô **offline** quando os batimentos param.
-
-```js
-Hobots.init({
-  clientSecret,
-  heartbeat: { intervalMs: 30_000, name: 'Robô NFe — VM 01' },
+// sempre ligado: o handler é o loop do robô; cada iteração reporta o que fez
+hobots.start('monitor-pasta', async () => {
+  while (true) {
+    await hobots.sleep(60_000); // cancelável
+    for (const arquivo of await novosArquivos()) hobots.items.succeeded({ arquivo });
+    hobots.log.info('ciclo ok');
+  }
 });
-```
-
-`heartbeat: true` usa os defaults. A identidade é o `instanceId` do `init()`; os campos são `intervalMs`, `name` (default: o `instanceId`) e `metadata` — valores em [Tempos e intervalos](./docs/api-reference.md#tempos-e-intervalos). O primeiro batimento sai **na hora** em que o `init()` roda, não depois do primeiro intervalo.
 
-O heartbeat é **essencial** para agentes só de telemetria; com `tasks: true` ele é **opcional**, porque o poll de tasks já marca a presença do agente no painel. Conceito: [Heartbeat](./docs/concepts.md#heartbeat).
-
-### Recursos da máquina (CPU, memória, disco)
-
-Ligado por padrão em Node (`machineMetrics: true`), o SDK coleta CPU do sistema, memória, disco do volume do bot e RSS/CPU do próprio processo — **sem dependência nova** e sem timer próprio: a leitura pega carona em cada heartbeat e em cada poll de tasks (série da instância em **Instâncias → recursos da máquina**) e vai como `contexts.machine` em cada evento (card **"máquina no momento do erro"** no detalhe da issue). Assim dá para responder se o ambiente tem recurso suficiente e se um erro coincidiu com CPU/memória no limite.
-
-```js
-Hobots.init({ clientSecret, instanceId: 'vm-01', heartbeat: true }); // coleta ligada
-Hobots.init({ clientSecret, instanceId: 'vm-01', machineMetrics: false }); // desliga
-```
-
-O snapshot tem ~600 bytes (teto do servidor: 4 KiB). Formato em [Protocolo → MachineSnapshot](./docs/protocol.md#machinesnapshot).
-
-### Flush e close
-
-```js
-await Hobots.flush(2000); // envia o buffer, mantém o SDK vivo
-await Hobots.close(2000); // flush final + para o heartbeat + fecha o transport
+process.on('SIGINT', () => void hobots.close(15_000).then(() => process.exit(0)));
 ```
 
-Chame `close` antes do processo sair. Os timers da telemetria são `unref`'d — ela **não** segura o processo vivo sozinha.
+O objeto **`hobots`** é global: `hobots.log`, `hobots.items`, `hobots.progress`, `hobots.transaction`… resolvem a execução **atual** de qualquer módulo do programa — sem passar contexto de mão em mão, mesmo com várias execuções em paralelo. Depois da primeira task ele também existe como `globalThis.hobots`.
 
 ---
 
-## Tasks (execução sob demanda)
-
-Capability de **execução remota sob demanda**, habilitada com `tasks: true` (ou opções) no `init()`. O agente faz polling no app, executa os handlers registrados quando aparece trabalho e reporta status e logs incrementais — cada execução aparece no módulo **Solicitações** do app. Mesmo Client Secret, mesmo `debug` e o `instanceId` como identidade — nenhum handler global extra é instalado.
-
-### Ciclo de vida
-
-```js
-Hobots.init({
-  clientSecret: 'hb_<64 hex>',
-  instanceId: 'vm-cliente-01',
-  tasks: true, // ou { pollIntervalMs, concurrency, ... }
-});
-
-Hobots.register('processar-nfe', async (params, ctx) => {
-  ctx.log.info(`processando lote ${params.lote}…`);
-  ctx.throwIfCanceled();            // cancelamento cooperativo
-  ctx.log.info('12 notas processadas');
-});
-
-Hobots.start(); // começa o polling e MANTÉM O PROCESSO VIVO
-
-process.on('SIGINT', () => {
-  void Hobots.close(15_000).then(() => process.exit(0));
-});
-```
-
-- `init({ tasks })` — cria o agente. Chamar `init()` de novo para o agente anterior e o substitui (o registry de handlers é preservado).
-- `register(task, handler)` — `task` é o `task_slug` configurado no formulário do app (**Configurações → Formulários**). Registre **antes** de `start()`. Funciona até antes do `init()`; com as tasks desabilitadas, avisa no console.
-- `start()` — começa o polling. Lança se o `init()` não configurou `tasks` ou se nenhuma task foi registrada.
-- `stop(timeoutMs?)` — para **só o polling de tasks**: encerra o polling e aguarda as runs ativas (default 30s); a telemetria continua. Retorna `false` se estourou o timeout.
-- `close(timeoutMs?)` — encerra **tudo**: agente (aguardando runs em voo) → heartbeat → flush final do transport.
-
-| Opção (`TasksOptions`) | Tipo | Default | Descrição |
-| --- | --- | --- | --- |
-| `pollIntervalMs` | `number` | `2000` | intervalo entre polls sem trabalho (mínimo `1000`) |
-| `concurrency` | `number` | `1` | runs simultâneas (clamp 1..5) |
-| `taskTimeoutMs` | `number` | — | timeout client-side por run (não mata o handler; servidor é o backstop) |
-| `logFlushIntervalMs` | `number` | `2000` | intervalo do envio incremental de logs |
-| `cancelCheckIntervalMs` | `number` | `5000` | heartbeat de cancelamento por run (clamp 1000..15000) — também é o sinal de vida da run |
-| `installExitHandlers` | `boolean` | `true` | handlers de SIGINT/SIGTERM/uncaughtException que reportam as runs ativas como `AgentTerminated` antes do processo morrer; nunca interferem quando o programa tem handler próprio |
-
-O Client Secret, o `debug` e a identidade do agente (`instanceId`) vêm do `init()` — o heartbeat e o poll de tasks convergem em **um agente** no painel automaticamente.
+## Credenciais e identidade
 
-### O handler e o `RunContext`
+| Env | Opção | O que é |
+| --- | --- | --- |
+| `HOBOTS_CLIENT_SECRET` | `clientSecret` | O **Client Secret do agente** (`hb_<64 hex>`), copiado em **Configurações → Agentes**. Viaja só no header `Authorization: Bearer`, nunca na URL. Ausente ou inválido → `register()`/`start()` lança na hora, citando a env (sem ecoar o valor). |
+| `HOBOTS_INSTANCE_ID` | `instanceId` | Identidade **estável** desta instância do robô (`vm-cliente-01`). Sem ela, o hostname. Heartbeat e tasks convergem nela: **um agente só** no painel. |
+| `HOBOTS_ENVIRONMENT` | `environment` | Ambiente lógico do robô (`development` \| `testing` \| `staging` \| `production`). Sem ela, `production`. |
+| `HOBOTS_API_URL` | — | Só em desenvolvimento: aponta o SDK para outro host (`http://localhost:3001`). Em produção é sempre `https://api2.hobots.app`. |
 
-```ts
-type TaskHandler<P = Record<string, unknown>> =
-  (params: P, ctx: RunContext) => void | Promise<void>;
-
-interface RunContext {
-  runId: string;
-  task: string;
-  log: RunLogger; // ctx.log.debug/info/warn/error/success(message)
-  items: RunItems; // ctx.items.succeeded/failed/occurrence — a entrega do bot
-  progress: RunProgressReporter; // ctx.progress.total/advance/set — barra + tempo restante no app
-  tx: Transaction; // transaction desta run — correlacionada e finalizada pelo SDK
-  signal: AbortSignal;
-  throwIfCanceled(): void; // lança RunCanceled se o signal já disparou
-  sleep(ms: number): Promise<void>; // espera cancelável — rejeita com RunCanceled no abort
-}
-```
+A opção passada em `register()`/`start()` tem precedência sobre a env — útil para copiar e colar o snippet do app.
 
-- **`params`** — os dados do formulário configurado no app (JSON validado). Tipável: `Hobots.register<{ lote: number }>(...)`.
-- **`ctx.log.<level>(message)`** — níveis `debug`, `info`, `warn`, `error` e `success`; logs enviados **incrementalmente** ao app (PATCHes com throttle), visíveis na solicitação quase em tempo real; também impressos no terminal local, coloridos por nível.
-- **`ctx.items`** — registra os **itens que a execução processou/gerou** (a entrega do bot: notas fiscais baixadas, boletos emitidos…), cada um com status `succeeded`, `failed` (falha técnica) ou `occurrence` (ocorrência de negócio, ex.: "nota nº 10 não encontrada") e um `payload` de atributos livres. Aparecem na aba **itens** da solicitação, com totalizadores; as colunas exibidas são configuradas por formulário no app. Guia: [Itens de execução](./docs/tasks.md#itens-de-execução-ctxitems).
-- **`ctx.progress`** — **opcional**: declare quantos itens a run vai processar (`ctx.progress.total(n)`) e avance a cada item (`ctx.progress.advance()`); o app mostra barra, percentual e tempo restante estimado na solicitação. Independente de `ctx.items`. Guia: [Progresso](./docs/tasks.md#progresso-da-execução-ctxprogress).
-- **`ctx.tx`** — a transaction de performance desta run, já correlacionada e finalizada pelo SDK. Use `ctx.tx.startChild(op, description)` para medir as etapas — elas viram o waterfall da execução no app. `startTransaction()` chamado dentro do handler retorna essa mesma transaction. Conceito: [ctx.tx](./docs/concepts.md#transaction-de-run-ctxtx).
-- **`ctx.signal`** — `AbortSignal` que dispara quando a run é **cancelada no app**, em **timeout** ou no **shutdown**.
-- **`ctx.throwIfCanceled()`** — o ponto de parada de uma linha; lança `RunCanceled` se o `signal` já disparou.
-- **`ctx.sleep(ms)`** — espera que respeita o `signal` (rejeita com `RunCanceled` em vez de dormir até o fim).
-- **Retorno** — **ignorado**: o SDK não captura nem envia o valor retornado pelo handler (resultados podem conter dados sensíveis e não são coletados).
-- **Erro lançado** — a run é reportada como `failed` (mensagem cap 10k, stack 20k).
-
-> **Dados sensíveis:** `ctx.log` e mensagens/stack de erros **são enviados ao servidor** e ficam visíveis no app. Não inclua senhas, tokens, dados pessoais ou qualquer informação sensível em logs e mensagens de erro.
+---
 
-### Itens de execução (`ctx.items`)
+## Os dois modos
 
-```js
-Hobots.register('baixar-notas', async (params, ctx) => {
-  for (const nota of await listarNotas(params)) {
-    try {
-      await baixar(nota);
-      ctx.items.succeeded({ numero_nota: nota.numero, cnpj_prestador: nota.cnpj }, { id: nota.numero });
-    } catch (erro) {
-      ctx.items.failed(String(erro), { numero_nota: nota.numero }, { id: nota.numero });
-    }
-  }
-  // ocorrência de negócio (não é falha do bot):
-  // ctx.items.occurrence('nota nº 10 não encontrada', { numero_nota: '10' }, { id: '10' })
-});
-```
+| | `register(task, handler, options?)` | `start(task, handler, options?)` |
+| --- | --- | --- |
+| Quem dispara | Uma **solicitação** no app (formulário com esse `task_slug`, ou agendamento) | O próprio robô, ao iniciar |
+| `params` do handler | O JSON validado do formulário | `{}` |
+| Quantas execuções | Uma por solicitação; `concurrency` em paralelo (1..5) | **Uma só** — o handler é o seu loop; quando ele retorna, a execução fecha |
+| O processo | Fica vivo fazendo polling | Fica vivo pelo heartbeat, mesmo depois do handler retornar |
+| Reexecutar pelo app | Sim | Não — só reiniciando o robô |
 
-Chamadas síncronas e bufferizadas (lotes de até 500; dreno antes do reporte final). O `id` opcional é a identidade de negócio do item na run — repetido, é ignorado pelo servidor (registro único, retry idempotente). Limites: 10.000 itens/run, payload 16 KB, mensagem 2.000 caracteres. Detalhes em [Itens de execução](./docs/tasks.md#itens-de-execução-ctxitems).
+Os dois podem coexistir no mesmo processo: um monitor sempre ligado + tasks sob demanda, um heartbeat, uma instância. Cada slug só pode ser registrado uma vez.
 
-### Progresso (`ctx.progress`)
+> **Modo start e o limite de logs:** o servidor guarda no máximo **1000 linhas de log por execução**. Num loop que roda por dias, logue o que importa (ciclos com novidade, avisos, erros) e registre o trabalho em `hobots.items` — itens não têm esse teto tão baixo (10.000 por execução).
 
-Quando a run percorre uma lista conhecida, declare o total e avance a cada item — a solicitação no app ganha barra de progresso, percentual (`10/100 · 10%`) e **tempo restante estimado**:
+---
 
-```js
-Hobots.register('baixar-notas', async (params, ctx) => {
-  const notas = await listarNotas(params);
-  ctx.progress.total(notas.length);
-  for (const nota of notas) {
-    await baixar(nota);
-    ctx.progress.advance();
-  }
-});
-```
+## O objeto `hobots`
 
-Opcional e independente de `ctx.items` (use um, outro ou ambos). Sem `total()` nada é enviado. Chamadas síncronas e baratas: o snapshot pega carona nos PATCHes de log e, no pior caso, sai 1 vez por segundo; o PATCH terminal sempre leva o valor final. `ctx.progress.set(current, total?)` define um valor absoluto; `ctx.progress.current` e `ctx.progress.snapshot` leem o estado. Detalhes em [Progresso da execução](./docs/tasks.md#progresso-da-execução-ctxprogress).
+| Membro | O que faz |
+| --- | --- |
+| `hobots.log.debug/info/warn/error/success(msg, ...rest)` | Log da execução, enviado incrementalmente ao app (e ecoado no terminal). Aceita vários argumentos como `console.log` — `hobots.log.info('nota', numero, 'ok')` — cada um vira texto, unidos por espaço. **Nunca lança** — pode ir em `finally`. |
+| `hobots.items.succeeded(payload?, { id }?)` · `.failed(msg, payload?, …)` · `.occurrence(msg, payload?, …)` · `.add({...})` | **A entrega do robô**: cada item processado, com status e atributos (viram colunas no app — declare-as com a opção `items: { columns: [...] }` do `register`/`start`). Bufferizado, em lotes. |
+| `hobots.progress.total(n)` · `.advance(k = 1)` · `.set(atual, total?)` · `.current` · `.snapshot` | Barra, percentual e tempo restante na solicitação. Sem `total()` nada é enviado. |
+| `hobots.transaction.startChild(op, descrição)` | Uma **step** no waterfall de performance da execução. A transaction da execução já existe e é finalizada pelo SDK. |
+| `hobots.attach(imagem, { caption?, level? })` | Pendura um **print** (PNG/JPEG/WEBP, até 5 MB, 20 por execução) na linha de log. Nunca lança nem bloqueia. |
+| `hobots.captureException(erro, hint?)` | Abre uma **issue** (módulo Issues). `hint.attachment` anexa um print à linha de log correspondente. |
+| `hobots.retry(fn, { retries = 3, delayMs = 1_000, shouldRetry? })` | async-retry ciente do cancelamento da execução. `delayMs` aceita função `(tentativa) => ms`. |
+| `hobots.sleep(ms)` | Espera **cancelável**: rejeita com `RunCanceled` se a execução for cancelada. |
+| `hobots.signal` · `hobots.throwIfCanceled()` | Cancelamento cooperativo manual, para controle fino. |
+| `hobots.runId` · `hobots.task` · `hobots.params` | Identidade da execução atual. |
+| `hobots.register(...)` · `hobots.start(...)` · `hobots.close(timeoutMs?)` | Ciclo de vida do processo. |
+
+O handler também recebe o mesmo contexto como 2º argumento (`(params, ctx) => …`), para quem prefere explícito. Fora de qualquer execução (ex.: antes do boot), os membros de contexto caem em fallbacks seguros e avisam uma vez — `hobots.log` continua imprimindo no terminal. Evite `const { log } = hobots` no topo de um módulo: o valor capturado é o de fora de execução; chame `hobots.log.info(...)`.
 
-### Anexos (screenshots)
+---
 
-Texto de log conta o que o robô fez; um print conta **como estava a tela**. Os métodos de captura (`Hobots.captureException` e `Hobots.captureMessage`) aceitam um `attachment` no hint: dentro de uma execução de task, a imagem vira anexo da linha de log da run que espelha a captura — no app ela aparece como miniatura logo abaixo dessa linha, clicável para ampliar.
+## Cancelamento automático
 
-```js
-Hobots.register('processar-nfe', async (params, ctx) => {
-  await entrar();
-  Hobots.captureMessage('portal após o login', 'info', {
-    attachment: await page.screenshot(),
-  });
-
-  try {
-    await emitir(params);
-  } catch (erro) {
-    Hobots.captureException(erro, {
-      attachment: { image: await page.screenshot(), caption: 'tela no momento do erro' },
-    });
-    throw erro;
-  }
-});
-```
+Uma execução cancelada no app **não mata** o handler — o SDK dispara `hobots.signal` e o próximo ponto de parada lança **`RunCanceled`**:
 
-**O SDK não tira o print** — ele recebe a imagem pronta, de onde você quiser (Playwright, Puppeteer, uma lib de captura de desktop, um arquivo em disco). O `attachment` aceita bytes (`Uint8Array`/`ArrayBuffer`/`Buffer`), um caminho de arquivo (só em Node) ou um objeto `{ image, caption?, contentType? }`.
+- `hobots.items.*`, `hobots.progress.total/advance/set`, `hobots.transaction.startChild()`, `hobots.sleep()` e cada tentativa de `hobots.retry()`.
+- **Nunca `hobots.log.*`** — um log dentro de um `finally` de limpeza não pode explodir.
 
-| Limite | Valor |
-| --- | --- |
-| formatos | PNG, JPEG, WEBP |
-| tamanho por imagem | 5 MB |
-| anexos por execução | 20 |
-| anexos por linha de log | 4 |
+Num loop de itens, isso costuma bastar: registrar o item processado já é o ponto de parada. Para controle fino, `hobots.throwIfCanceled()` e `hobots.signal` continuam disponíveis. Quando o cancelamento veio do app, o `RunCanceled` é **suprimido** — a execução já está `cancelada` no servidor e nada é reportado por cima. Limpeza (fechar navegador, desfazer estado) vai em `try/finally`.
 
-A linha de log é registrada **na hora**; o upload roda em segundo plano e vai direto para o S3 por URL presignada, sem passar pela API — a captura **nunca bloqueia nem lança** por causa do anexo (falhas viram um aviso no log da run). Fora de uma execução de task não há onde pendurar a imagem: o `attachment` é descartado com um aviso. Detalhes em [Anexos](./docs/tasks.md#anexos-screenshots).
+> **Atenção:** não use `if (hobots.signal.aborted) return;`. Retornar normalmente reporta a execução como **`succeeded`**. É preciso **lançar** — e é o que os pontos de parada fazem.
 
-> **Dados sensíveis:** o print é enviado **exatamente como está** — o SDK não borra nem recorta nada, e telas de portal costumam conter CPF, nome e valores. Capture só o necessário. Solicitantes só veem os anexos quando o projeto está com "mostrar logs para solicitantes" ligado, o mesmo gate dos logs.
+---
 
-### Cancelamento cooperativo
+## Retry
 
-Uma run cancelada no app **não mata** o handler — o SDK apenas dispara `ctx.signal`. Chame **`ctx.throwIfCanceled()`** em loops longos e pontos de parada (e troque esperas longas por `ctx.sleep()`):
+Quando o handler lança, o SDK **tenta de novo na mesma execução**: aviso no log (`tentativa 1/2 falhou: … — nova tentativa em 5000ms`), espera cancelável, re-invocação com os mesmos `params`. Default: **1 tentativa extra** com 5 s. Itens e progresso já enviados permanecem — escreva handlers **idempotentes** (use o `id` de negócio nos itens: repetido, o servidor ignora).
 
 ```js
-Hobots.register('processar-nfe', async (params, ctx) => {
-  for (const nota of params.notas) {
-    ctx.throwIfCanceled(); // lança RunCanceled se cancelada — o handler para aqui
-    await processar(nota);
-  }
-});
+hobots.register('processar-nfe', handler, { retries: 3, retryDelayMs: attempt => attempt * 10_000 });
 ```
 
-Quando o cancelamento veio do app, o `RunCanceled` lançado é **suprimido** — a run já está `cancelada` no servidor e nada é reportado por cima. Para limpeza antes de parar (fechar navegador, desfazer estado), use `try/finally`.
-
-> **Atenção:** não use `if (ctx.signal.aborted) return;`. Retornar normalmente faz o SDK reportar a run como **`succeeded`** — uma run cancelada apareceria como sucesso no app. É preciso **lançar**, e é o que o `throwIfCanceled()` faz.
-
-### Concorrência
-
-`concurrency` (default 1, máx 5) controla quantas runs o agente executa em paralelo. Com 1, as runs são sequenciais. O agente só reivindica o que consegue rodar (`max = concurrency - runs ativas`) e entra em **drain mode**: re-pesquisa imediatamente enquanto vem trabalho; quando não vem, espera `pollIntervalMs`.
+Nunca há nova tentativa em **cancelamento**, **timeout** (`TaskTimeout` é terminal) ou execução já cancelada no app. Para uma chamada instável dentro do handler, use `hobots.retry()`.
 
-### Timeout por run
-
-`taskTimeoutMs` é **client-side**. No estouro o SDK **não mata** o handler — dispara `ctx.signal`, libera o slot e reporta a run como falha (`TaskTimeout`). Respeite o `signal` para parar de verdade. Sem ele, o backstop é o servidor.
-
-### Idempotência (at-least-once até `running`)
+---
 
-Se o agente morrer logo **após capturar** uma run (antes de reportar `running`), ela é re-entregue quando um agente voltar (até 3 tentativas; depois `AgentLost`). A partir do momento em que a run está `running`, a morte do agente **não re-entrega** — a run vira falha `AgentTerminated`, porque o trabalho pode ter efeitos colaterais parciais e re-executar automaticamente não é seguro (reexecute manualmente pelo app).
+## Opções
 
-Ainda assim, escreva handlers **idempotentes**: a janela de re-entrega pós-claim existe, e processar a mesma run duas vezes não pode causar efeito duplicado (use uma chave de deduplicação sua, como o número da nota).
+```ts
+hobots.register(task, handler, options?: RegisterOptions);
+hobots.start(task, handler, options?: StartOptions);
+```
+
+| Opção | Default | Descrição |
+| --- | --- | --- |
+| `clientSecret` | env `HOBOTS_CLIENT_SECRET` | Client Secret do agente |
+| `instanceId` | env `HOBOTS_INSTANCE_ID` → hostname | Identidade da instância |
+| `environment` | env `HOBOTS_ENVIRONMENT` → `'production'` | `development` \| `testing` \| `staging` \| `production` — decide quem é alertado |
+| `release` | — | Versão do programa, ex. `robo-nfe@1.4.2` |
+| `tags` | — | Tags de todos os eventos |
+| `debug` | `false` | Loga a atividade do SDK |
+| `machineMetrics` | `true` | CPU/memória/disco no heartbeat e em cada evento |
+| `captureUnhandled` | `true` | `uncaughtException`/`unhandledRejection` viram issues |
+| `retries` | `1` | Tentativas extras do handler (0 desliga) |
+| `retryDelayMs` | `5_000` | ms fixo ou `(tentativa) => ms` |
+| `timeoutMs` | — (infinito) | Timeout por tentativa; terminal (`TaskTimeout`). O handler não é morto: o signal dispara e o slot é liberado |
+| `concurrency` (register) | `1` | Execuções simultâneas desta task (1..5) |
+| `pollIntervalMs` (register) | `2_000` | Intervalo entre polls sem trabalho (mín. 1_000) |
+| avançadas: `installExitHandlers`, `logFlushIntervalMs`, `cancelCheckIntervalMs`, `cancelGraceMs` | `true`, `2_000`, `5_000`, `10_000` | Ver [Referência de API](./docs/api-reference.md) |
+
+As opções de **processo** (`clientSecret`, `instanceId`, `environment`, `release`, `tags`, `debug`, `machineMetrics`, `captureUnhandled`, `installExitHandlers`, `pollIntervalMs`) valem as da **primeira** chamada; chamadas seguintes com valor diferente avisam e são ignoradas.
 
 ---
 
-## Encerramento gracioso
+## Encerramento
 
-`close(timeoutMs?)` encerra tudo na ordem certa: para o polling de tasks (aguardando a run atual), para o heartbeat e faz o flush final do transport.
+O heartbeat mantém o processo vivo por design. `hobots.close(timeoutMs = 30_000)` para o polling, aguarda as execuções em voo, para o heartbeat (libera o processo) e faz o flush final:
 
 ```js
-// só telemetria: não segura o processo, mas faça o flush final para não perder eventos
-await Hobots.close(2_000);
-
-// com tasks: segura o processo por design — aguarde a run atual
 process.on('SIGINT', () => {
-  void Hobots.close(15_000).then(() => process.exit(0));
+  void hobots.close(15_000).then(() => process.exit(0));
 });
 ```
 
-Para parar de aceitar execuções **sem** derrubar a telemetria, use `stop(timeoutMs?)`.
-
----
-
-## Entry points / exports
+Sem handler próprio de sinal, um `SIGINT`/`SIGTERM` (ou erro fatal) com execuções ativas reporta cada uma como `failed`/`AgentTerminated` antes do processo sair — o app mostra a falha na hora.
 
-| Import | Conteúdo |
-| --- | --- |
-| `hobots` | Tudo: `init`, telemetria (captura, transactions, heartbeat), tasks (`register`/`start`/`stop`), `close`, classes e tipos. |
-| `hobots/protocol` | Tipos do wire format (telemetria e tasks). |
-
-Empacotado em **ESM e CommonJS** com **definições de tipos** (`.d.ts`) para todas as entradas.
+> **Dados sensíveis:** logs, itens, mensagens de erro e prints são enviados ao servidor e ficam visíveis no app. O SDK redige padrões óbvios de segredo, mas não borra prints nem filtra dados pessoais. Capture só o necessário.
 
 ---
 
-## Documentação completa
+## Changelog resumido
 
-Guias detalhados acompanham o pacote em [`docs/`](./docs/README.md).
+- **3.1.0** — `hobots.log.*` aceita vários argumentos (como `console.log`); `retries` inválido (`NaN`) cai no default em vez de tentar para sempre; 429 de itens e 429/501/503 de anexo são definitivos (sem esperar a ladder — `quota`/`unsupported` passam a funcionar de fato); timeout **por requisição** nos anexos; truncamento nos limites do servidor (tag 512, fingerprint 10×255, nome de transaction 500, 200 steps, `exception.value` 8192, `filename` 1024); PNG acima de 20 000 px não declara dimensões; PATCH terminal nunca passa de 100 logs.
 
-Novo no vocabulário de observabilidade (transaction, step, breadcrumb, tag, context, extra, flush, close)? Comece por [Conceitos](./docs/concepts.md) — as outras páginas assumem esses termos.
+## Documentação
 
-- [Conceitos](./docs/concepts.md) — o que cada coisa é, por que existe e quando escolher uma em vez da outra.
-- [Getting started](./docs/getting-started.md) — instalação, Client Secret, primeiro `init`, telemetria e tasks.
-- [Telemetria](./docs/telemetry.md) — erros, breadcrumbs, escopo, transactions/etapas, heartbeat.
-- [Tasks](./docs/tasks.md) — handlers, `RunContext`, cancelamento, concorrência, idempotência.
-- [Referência de API](./docs/api-reference.md) — todas as funções e tabelas de opções com defaults.
-- [Protocolo & transporte](./docs/protocol.md) — o Client Secret, endpoints, envelope, retries.
-
----
+- [Getting started](./docs/getting-started.md) — instalação, envs, primeira task nos dois modos.
+- [Tasks](./docs/tasks.md) — handler, `hobots.*`, itens, progresso, anexos, cancelamento, retry, concorrência, idempotência.
+- [Conceitos](./docs/concepts.md) — o vocabulário: task, execução, evento, transaction, step, heartbeat, instância, claim…
+- [Referência de API](./docs/api-reference.md) — assinaturas, tabelas de opções e tempos.
+- [Protocolo & transporte](./docs/protocol.md) — endpoints, envelope, retries, claim.
+- Exemplos runnable em [`packages/hobots-sdk-demos`](../hobots-sdk-demos).
 
 ## Licença