hobots 2.4.0 → 3.2.0

package/docs/getting-started.md

@@ -6,116 +6,70 @@
 pnpm add hobots
 ```
 
-Sem dependências de runtime. Requer **Node 18+** (usa o `fetch` global). A telemetria também funciona no browser para captura de erros.
+Sem dependências de runtime. Requer **Node 18+** (usa o `fetch` global).
 
 ## Conceitos em 2 minutos
 
-Os termos que aparecem nesta página, em uma frase cada. Explicação completa de todos em [Conceitos](./concepts.md).
-
 | Conceito | Em uma frase |
 | --- | --- |
-| [Evento](./concepts.md#evento) | A foto de um erro ou de uma mensagem que você registrou |
-| [Tag](./concepts.md#tag) | Rótulo curto e indexável, para filtrar depois (`cliente`, `regiao`) |
-| [Heartbeat](./concepts.md#heartbeat) | Batimento "estou vivo" — o servidor acusa offline quando ele para |
-| [instanceId](./concepts.md#instanceid) | A identidade da instância do robô; a mesma nos dois canais |
-| [Run](./concepts.md#run) | Uma execução solicitada no app, que um agente pega e executa |
-| [Fila, flush e close](./concepts.md#fila-flush-e-close) | Nada é enviado na hora — vai para uma fila que precisa ser esvaziada antes do processo morrer |
-
-## O Client Secret
-
-Cada agente tem **um único Client Secret** — a mesma credencial autentica a telemetria **e** as tasks:
-
-```
-hb_<64 hex>
-```
+| [Task](./concepts.md#task) | O que o robô sabe fazer, identificado por um slug — registrado com `register` (sob demanda) ou `start` (sempre ligado) |
+| [Execução (run)](./concepts.md#execução-run) | Uma rodada de uma task, com logs, itens, progresso e resultado — uma solicitação no app |
+| [Item](./concepts.md#item) | Uma unidade de trabalho entregue pela execução (nota baixada, boleto emitido) |
+| [Heartbeat](./concepts.md#heartbeat) | Batimento "estou vivo" — sempre ligado; o servidor acusa offline quando para |
+| [instanceId](./concepts.md#instanceid) | A identidade da instância do robô no painel |
+| [Issue](./concepts.md#evento-e-issue) | Erros agrupados — `hobots.captureException` e erros não tratados |
 
-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.
+## Credenciais
 
-O SDK fala com a API oficial `https://api2.hobots.app` automaticamente — não há configuração de host no `init()`. Em desenvolvimento, aponte para outro host com a env `HOBOTS_API_URL`:
+Cada agente tem **um Client Secret** (`hb_<64 hex>`), copiado em **Configurações → Agentes**. O SDK lê do ambiente, como as libs da AWS:
 
 ```bash
-HOBOTS_API_URL=http://localhost:3001 node meu-robo.js
+export HOBOTS_CLIENT_SECRET=hb_<64 hex>
+export HOBOTS_INSTANCE_ID=vm-cliente-01   # opcional — sem ela, o hostname
 ```
 
-Veja [Protocolo & transporte](./protocol.md) para os endpoints derivados da URL base.
+Também dá para passar `clientSecret`/`instanceId` nas opções da task (o snippet do app já vem assim). Em desenvolvimento, `HOBOTS_API_URL=http://localhost:3001` aponta para outra API; em produção é sempre `https://api2.hobots.app`.
 
-## Telemetria e tasks — qual usar
+## Primeira task sob demanda (`register`)
 
-As duas capabilities vivem no mesmo `init()` e você usa **uma, outra ou as duas**:
-
-- Quer só saber se o robô quebrou, quanto demora e se está vivo? → `init({ clientSecret, heartbeat: true })`.
-- Quer 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 cenário do
-  [`full.ts`](../../hobots-sdk-demos/src/full.ts) nos demos do SDK.
-
-## O `init` único
+1. No app, crie um formulário em **Configurações → Formulários** com o `task_slug` `processar-nfe`.
+2. No robô:
 
 ```js
-import * as Hobots from 'hobots';
-
-Hobots.init({
-  clientSecret: 'hb_<64 hex>',
-  environment: 'production',
-  release: 'robo-nfe@1.4.2',
-  instanceId: 'vm-cliente-01', // identidade única: heartbeat + agente de tasks
-  heartbeat: true, // "estou vivo" a cada 30s
+import hobots from 'hobots';
+
+hobots.register('processar-nfe', async params => {
+  hobots.log.info(`lote ${params.lote}`);
+  for (const nota of params.notas) {
+    await baixar(nota);
+    hobots.items.succeeded({ numero_nota: nota }, { id: nota });
+  }
+  hobots.log.success('concluído');
 });
 
-// Erros não tratados são capturados automaticamente.
-// Captura manual:
-try {
-  await processarNota(nota);
-} catch (error) {
-  Hobots.captureException(error, { tags: { cliente: 'acme' } });
-  throw error;
-}
+process.on('SIGINT', () => void hobots.close(15_000).then(() => process.exit(0)));
 ```
 
-Chame `Hobots.init` **uma vez**, o mais cedo possível no processo. Detalhes em [Telemetria](./telemetry.md).
-
-## Primeiro agente (tasks)
+3. Rode o robô: ele aparece online em **Instâncias** e fica aguardando. Crie uma solicitação pelo formulário — a execução aparece em **Solicitações** com logs em tempo real.
 
-Habilite a execução sob demanda com o campo `tasks` no mesmo `init()`:
+## Primeira task sempre ligada (`start`)
 
 ```js
-import * as Hobots from 'hobots';
-
-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}…`);
-  // Hobots.captureMessage('portal após o login', 'info', { attachment: await page.screenshot() }); // print junto do log
-  ctx.log.info('12 notas processadas'); // o retorno do handler é ignorado — reporte por log
+import hobots from 'hobots';
+
+hobots.start('monitor-pasta', async () => {
+  hobots.log.info('monitor iniciado');
+  while (true) {
+    await hobots.sleep(60_000); // cancelável — para se a execução for cancelada no app
+    for (const arquivo of await novosArquivos()) hobots.items.succeeded({ arquivo });
+  }
 });
-Hobots.start(); // mantém o processo vivo até stop()/close()
 ```
 
-> O `instanceId` é a identidade dos **dois** canais (heartbeat e poll de tasks) — o robô aparece como **um agente só** no módulo Agentes do app, sem configuração extra. Com `tasks: true`, o heartbeat é opcional: o próprio poll já marca a presença do agente.
-
-As execuções aparecem no módulo **Solicitações** do app; o `task` do `register()` é o `task_slug` do formulário em **Configurações → Formulários**. Detalhes (cancelamento, concorrência, idempotência) em [Tasks](./tasks.md).
+O robô abre a própria execução ao iniciar e ela aparece em **Solicitações** com origem "agente". Quando o handler retorna (ou é cancelado), a execução fecha; o processo continua vivo pelo heartbeat até `hobots.close()`.
 
 ## Encerramento
 
-`close()` encerra tudo na ordem certa: para o polling de tasks (aguardando a run atual), o heartbeat e faz o flush final do transport.
-
-Sem `start()` chamado, o SDK não segura o processo (timers `unref`'d), mas faça o flush final para não perder eventos em buffer:
-
-```js
-await Hobots.close(2000);
-```
-
-Com as tasks, `start()` segura o processo por design. Encerre de forma graciosa aguardando a run atual:
-
-```js
-process.on('SIGINT', () => {
-  void Hobots.close(15_000).then(() => process.exit(0));
-});
-```
-
-> **Atenção:** o `timeoutMs` do `close()` é gasto **duas vezes, em sequência** — uma esperando as runs de tasks, outra no flush final. O `close(15_000)` acima pode levar até ~30s no pior caso. Se o seu SIGTERM tem prazo curto (Kubernetes, systemd), dimensione por aí. Os defaults, quando você omite o argumento, estão em [Tempos e intervalos](./api-reference.md#tempos-e-intervalos).
+`hobots.close(timeoutMs?)` para o polling, espera as execuções em voo, para o heartbeat e faz o flush final. Sem handler próprio de `SIGINT`/`SIGTERM`, o SDK reporta as execuções ativas como `AgentTerminated` antes do processo morrer.
 
-Para parar de aceitar execuções **sem** derrubar a telemetria, use `Hobots.stop(timeoutMs?)`. Conceito das duas funções em [Fila, flush e close](./concepts.md#fila-flush-e-close).
+Próximos passos: [Tasks](./tasks.md) para itens, progresso, anexos, cancelamento e retry; [Referência de API](./api-reference.md) para todas as opções.

package/docs/protocol.md

@@ -18,7 +18,7 @@ hb_<64 hex>
 | Tasks (execução) | `<baseUrl>/v1/tasks/*` | `Authorization: Bearer <clientSecret>` |
 | Anexos (binário) | URL presignada do S3 (PUT) | assinatura na própria URL — **sem** header `Authorization` |
 
-A resolução da credencial nos endpoints é interna ao `init()` (em `src/config.ts`, com a constante exportada `DEFAULT_BASE_URL = 'https://api2.hobots.app'`); o resultado fica acessível em `getClient()?.config` → `{ key, baseUrl, ingestEndpoint, tasksBaseUrl }`. Em desenvolvimento a env `HOBOTS_API_URL` sobrescreve a URL base — apenas `http(s)`, e `http` para host fora de loopback gera aviso porque o secret trafega sem TLS. A credencial é **secreta** (formato `hb_` + 64 hex — chaves de outro formato são rejeitadas no `init()`) e viaja **só no header** `Authorization: Bearer` — nunca na URL da requisição.
+A credencial vem da opção `clientSecret` ou da env `HOBOTS_CLIENT_SECRET` (resolvida em `src/config.ts` no primeiro `register()`/`start()`, com a URL base `https://api2.hobots.app`). Em desenvolvimento a env `HOBOTS_API_URL` sobrescreve a URL base — apenas `http(s)`, e `http` para host fora de loopback gera aviso porque o secret trafega sem TLS. A credencial é **secreta** (formato `hb_` + 64 hex — outro formato é rejeitado na primeira task, sem ecoar o valor) e viaja **só no header** `Authorization: Bearer` — nunca na URL da requisição.
 
 ## Telemetria — ingestão
 
@@ -38,11 +38,11 @@ Endpoint fixo `POST /v1/ingest` recebe **envelopes** JSON autenticados por Beare
 
 Tipos de item: `event`, `transaction`, `heartbeat` (definidos em `hobots/protocol`).
 
-Um `transaction` pode carregar `run_id`: é assim que a [transaction de uma run](./concepts.md#transaction-de-run-ctxtx) (`ctx.tx`) é correlacionada à execução, e o que permite o app montar o waterfall de performance dentro da solicitação. Transactions abertas com `startTransaction()` fora de uma run não têm esse campo.
+Todo `transaction` carrega `run_id`: é assim que a [transaction da execução](./concepts.md#transaction) (`hobots.transaction`) é correlacionada, e o que permite o app montar o waterfall de performance dentro da solicitação.
 
 `items` aceita de 1 a **50** itens por envelope — acima disso a API responde `422`. O `maxBatchSize` é só o gatilho do flush: quando a fila tem mais que esse teto (burst de captures, ou fila acumulada durante uma janela de rede ruim), o transport a fatia em lotes de 50 e faz um POST por lote.
 
-**Flush & retries:** o transport flusha por `flushIntervalMs` ou ao atingir `maxBatchSize`. Ladder de retry de 3 tentativas; respostas 4xx (exceto 429) são descartadas sem retry; a fila tem teto fixo e descarta os itens **mais antigos** ao encher. Todos os valores em [Tempos e intervalos](./api-reference.md#tempos-e-intervalos).
+**Flush & retries:** o transport flusha a cada 2 s ou ao acumular 10 itens. Ladder de retry de 3 tentativas; respostas 4xx (exceto 429) são descartadas sem retry; a fila tem teto fixo e descarta os itens **mais antigos** ao encher. Todos os valores em [Tempos e intervalos](./api-reference.md#tempos-e-intervalos).
 
 
 ### MachineSnapshot
@@ -52,7 +52,7 @@ Recursos da máquina onde a instância roda. Vai em `HeartbeatPayload.machine`,
 | Campo | Tipo | Descrição |
 | --- | --- | --- |
 | `sampled_at` | ISO 8601 | momento da coleta (relógio do cliente) — chave de dedupe da série |
-| `instance_id` | string | o `instanceId` do `init()` — liga o snapshot de um evento à série da instância |
+| `instance_id` | string | o `instanceId` da instância — liga o snapshot de um evento à série da instância |
 | `hostname`, `os`, `arch` | string | identificação da máquina (`process.platform` / `sys.platform`) |
 | `cpu_count` | int | cores lógicos |
 | `cpu_percent` | number \| null | uso de CPU do sistema — média entre duas coletas; `null` até haver 2 amostras |
@@ -66,9 +66,9 @@ Recursos da máquina onde a instância roda. Vai em `HeartbeatPayload.machine`,
 
 O servidor guarda o último snapshot em `instances.machine` e um ponto por heartbeat/poll (máx. 1 a cada 30s por instância) em `instance_metrics`, expurgado em 14 dias.
 
-## Tasks — polling e reporte
+## Tasks — polling, criação e reporte
 
-Dois endpoints sob `<baseUrl>/v1/tasks`, ambos com `Authorization: Bearer <clientSecret>` (a credencial única do agente):
+Endpoints sob `<baseUrl>/v1/tasks`, todos com `Authorization: Bearer <clientSecret>` (a credencial única do agente):
 
 ### `POST /v1/tasks/poll`
 
@@ -79,22 +79,34 @@ Corpo `PollRequest`:
   "instance": {
     "instance_id": "vm-01",       // identidade canônica da instância (obrigatória)
     "name": "VM 01",
-    "version": "2.0.0",
+    "version": "3.0.0",
     "host": "vm-01",
     "environment": "production", // ambiente da instância: development | testing | staging | production
-    "tasks": ["processar-nfe"]
+    "tasks": ["processar-nfe", "monitor-pasta"], // TODAS as tasks (register + start) — o painel mostra o que o agente sabe fazer
+    "poll_interval_ms": 2000,
+    // colunas de itens declaradas no código (opção `items`) — só as tasks que declararam;
+    // ausente = nada declarado (o servidor nunca apaga a declaração anterior por ausência)
+    "task_items": { "processar-nfe": { "attributes": [{ "key": "numero_nota" }, { "key": "valor", "label": "valor (R$)" }] } }
   },
-  "max": 1,                       // quantas reivindicar (1..5)
-  "tasks": ["processar-nfe"]      // só runs destas tasks registradas
+  "max": 2,                       // soma dos slots livres das tasks remotas (1..5)
+  "tasks": ["processar-nfe"]      // só tasks de register() com slot livre — a concorrência é por task
 }
 ```
 
 Resposta `PollResponse` = `{ runs: RunDescriptor[] }`, cada `{ id, task, params, form, source, created_at }`.
 
-O `instance.instance_id` é a **mesma identidade** do heartbeat de telemetria (`instance_id`): o servidor correlaciona os dois canais numa tabela `instances` por `(agent_id, instance_id)`. Com o `init()` único, os dois derivam do `instanceId` — o robô aparece como um agente só no painel automaticamente. O próprio poll marca a presença da instância (`last_poll_at`), por isso o heartbeat é opcional quando as tasks estão habilitadas.
+O `instance.instance_id` é a **mesma identidade** do heartbeat de telemetria (`instance_id`): o servidor correlaciona os dois canais numa tabela `instances` por `(agent_id, instance_id)`. Os dois derivam do mesmo `instanceId` — o robô aparece como um agente só no painel. O próprio poll também marca a presença da instância (`last_poll_at`). Um processo só com tasks de `start()` nunca faz poll.
 
 **Backoff:** um request por poll; o loop decide o ritmo. HTTP 401 (key rejeitada) → retry lento a 30s com log throttled; outros erros → ladder `[1s, 4s, 16s]`.
 
+### `POST /v1/tasks/runs`
+
+Modo `start`: a instância abre a **própria run**. Corpo `RunCreateRequest` — `{ "task": "monitor-pasta", "instance": { /* InstanceInfo, obrigatório */ } }`. Resposta `201` `RunCreateResponse` = o mesmo `RunDescriptor` do poll, com `params: {}`, `form: null` e `source: 'agent'`.
+
+- A run nasce **`running`** (`started_at`, `claimed_at` e `last_report_at` = agora, `claim_count` 1), sem formulário nem solicitante, vinculada à instância informada. Dali em diante é reportada pelas rotas abaixo exatamente como uma run reivindicada no poll.
+- `touchInstance` roda antes do insert (presença); se falhar, a API responde `503` e o SDK insiste com o ladder do poll (o handler só começa quando a run existe). Corpo vazio, sem `instance.instance_id` ou com `task` fora de 1..255 → `422`.
+- Sem dedupe: um processo reiniciado em menos de 120 s deixa a run anterior `running` até o sweep marcá-la `AgentTerminated`. O app não oferece "reexecutar" para runs `agent` — ninguém faria poll por elas.
+
 ### `PATCH /v1/tasks/runs/{id}`
 
 Corpo `RunUpdateRequest`:
@@ -108,23 +120,23 @@ Corpo `RunUpdateRequest`:
       "attachments": ["<32 hex>"] }                            // opcional; ids de anexo (máx. 4)
   ],
   "error":  { "type": "Error", "message": "…", "stack": "…" },  // só com 'failed'
-  "progress": { "current": 10, "total": 100 }                     // opcional (SDK ≥ 2.1): snapshot de ctx.progress
+  "progress": { "current": 10, "total": 100 }                     // opcional: snapshot de hobots.progress
 }
 ```
 
-- `status: 'running'` pode repetir para enviar **logs incrementais** (throttle por `logFlushIntervalMs`, flush ao acumular 20, chunk de 100, teto de 1000 logs/run, mensagem cap 10k).
-- `progress` é **opcional** e aditivo (SDK ≥ 2.1): snapshot absoluto de `ctx.progress` (`current` 0..total, `total` ≥ 1) — o servidor **sobrescreve** `progress_current`/`progress_total` e grava `progress_started_at` no primeiro PATCH que o traga (relógio do servidor; âncora da ETA no app). `current > total` é clampado; progresso enviado a uma run já terminal é descartado. O SDK anexa o snapshot mais recente a **qualquer** PATCH que saia (logs, heartbeat, terminal) e só dispara um PATCH próprio, no máximo 1/s, quando nada mais está a caminho. Uma API anterior ao recurso descarta o campo (objeto não-strict).
+- `status: 'running'` pode repetir para enviar **logs incrementais** (throttle por `logFlushIntervalMs`, flush ao acumular 20, chunk de 100, teto de 1000 logs/run, mensagem cap 10k). O aviso de cada tentativa do retry do handler é uma dessas linhas.
+- `progress` é **opcional** e aditivo: snapshot absoluto de `hobots.progress` (`current` 0..total, `total` ≥ 1) — o servidor **sobrescreve** `progress_current`/`progress_total` e grava `progress_started_at` no primeiro PATCH que o traga (relógio do servidor; âncora da ETA no app). `current > total` é clampado; progresso enviado a uma run já terminal é descartado. O SDK anexa o snapshot mais recente a **qualquer** PATCH que saia (logs, heartbeat, terminal) e só dispara um PATCH próprio, no máximo 1/s, quando nada mais está a caminho. Uma API anterior ao recurso descarta o campo (objeto não-strict).
 - `attachments` é **opcional** e aditivo: SDKs anteriores à 1.9 simplesmente não enviam o campo, e uma API anterior ao recurso descarta o campo na validação (objeto não-strict) sem rejeitar o PATCH. Os ids são gerados pelo agente **antes** do upload, o que permite enviar a linha de log sem esperar o binário subir.
 - Ordem garantida `running → logs → terminal` (PATCHes serializados numa cadeia de promise).
-- Retry `[1s, 4s, 16s]`; 4xx exceto 429 é terminal (**409** = run cancelada / transição inválida → marca a run como morta e dispara `ctx.signal`).
-- Todo PATCH atualiza `last_report_at` no servidor (relógio do servidor) — é o **sinal de vida da run**. O heartbeat de cancelamento (PATCH `running` vazio a cada `cancelCheckIntervalMs`, máx 15s) garante reporte contínuo; um sweep server-side marca como `failed` com erro `AgentTerminated` ("execução encerrada inesperadamente") toda run `running` sem reporte há **60s**, sem re-entrega. No exit path (sinal/erro fatal com runs ativas), o SDK envia um único PATCH `failed`/`AgentTerminated` com timeout curto (~2s), sem retry — o sweep é o backstop.
+- Retry `[1s, 4s, 16s]`; 4xx exceto 429 é terminal (**409** = run cancelada / transição inválida → marca a run como morta e dispara `hobots.signal`).
+- Todo PATCH atualiza `last_report_at` no servidor (relógio do servidor) — é o **sinal de vida da run**. O heartbeat de cancelamento (PATCH `running` vazio a cada `cancelCheckIntervalMs`, máx 15s) garante reporte contínuo; um sweep server-side marca como `failed` com erro `AgentTerminated` ("execução encerrada inesperadamente") toda run `running` sem reporte há **120s**, sem re-entrega. No exit path (sinal/erro fatal com runs ativas), o SDK envia um único PATCH `failed`/`AgentTerminated` com timeout curto (~2s), sem retry — o sweep é o backstop.
 - O protocolo **não transporta resultado** de execução: o retorno do handler é ignorado pelo SDK e o servidor descarta qualquer campo `result` (dados de negócio podem ser sensíveis e não são coletados).
 
-Ciclo de vida completo da run no servidor (`RunStatus`): `pending → claimed → running → succeeded | failed | canceled`. O agente só transiciona para `running`/`succeeded`/`failed` (`RunUpdateStatus`).
+Ciclo de vida completo da run no servidor (`RunStatus`): `pending → claimed → running → succeeded | failed | canceled` (runs `agent` nascem em `running`). O agente só transiciona para `running`/`succeeded`/`failed` (`RunUpdateStatus`).
 
 ### `POST /v1/tasks/runs/{id}/items`
 
-Registra em lote os **itens de execução** (a entrega do bot — `ctx.items` no SDK). Insert-only: cada item chega com o status final; um `id` repetido na mesma run é ignorado (retry de rede idempotente).
+Registra em lote os **itens de execução** (a entrega do bot — `hobots.items` no SDK). Insert-only: cada item chega com o status final; um `id` repetido na mesma run é ignorado (retry de rede idempotente).
 
 Corpo `RunItemsCreateRequest`:
 
@@ -213,4 +225,4 @@ O `POST /v1/tasks/poll` no app chama `claimPendingRuns()` em
 
 ## Identidade do SDK
 
-`SDK_NAME = 'hobots'` e `SDK_VERSION` ficam em `src/utils.ts` e vão em todo envelope (campo `sdk`) e no `agent.version` do poll. A `SDK_VERSION` é **injetada pelo build** (o `define` do tsup lê a `version` do `package.json`) — não há sincronização manual ao publicar.
+`SDK_NAME = 'hobots'` e `SDK_VERSION` ficam em `src/utils.ts` e vão em todo envelope (campo `sdk`) e no `instance.version` do poll e da criação de run. A `SDK_VERSION` é **injetada pelo build** (o `define` do tsup lê a `version` do `package.json`) — não há sincronização manual ao publicar.