hobots 1.6.0 → 1.7.0

package/docs/getting-started.md

@@ -6,7 +6,7 @@
 pnpm add hobots
 ```
 
-Sem dependências de runtime. Requer **Node 18+** (usa o `fetch` global). O Monitor também funciona no browser para captura de erros.
+Sem dependências de runtime. Requer **Node 18+** (usa o `fetch` global). A telemetria também funciona no browser para captura de erros.
 
 ## Conceitos em 2 minutos
 
@@ -23,7 +23,7 @@ Os termos que aparecem nesta página, em uma frase cada. Explicação completa d
 
 ## O Client Secret
 
-Cada projeto tem **um único Client Secret** — a mesma credencial autentica o Monitor **e** o Manager:
+Cada projeto tem **um único Client Secret** — a mesma credencial autentica a telemetria **e** as tasks:
 
 ```
 hb_<64 hex>
@@ -39,13 +39,13 @@ HOBOTS_API_URL=http://localhost:3001 node meu-robo.js
 
 Veja [Protocolo & transporte](./protocol.md) para os endpoints derivados da URL base.
 
-## Monitor e Manager — qual usar
+## Telemetria e tasks — qual usar
 
 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, manager: true })` + `register()` + `start()`.
-- Ambos? Passe `heartbeat` e `manager` no **mesmo `init()`**. É o cenário do
+- 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
@@ -57,7 +57,7 @@ Hobots.init({
   clientSecret: 'hb_<64 hex>',
   environment: 'production',
   release: 'robo-nfe@1.4.2',
-  instanceId: 'vm-cliente-01', // identidade única: heartbeat + agente Manager
+  instanceId: 'vm-cliente-01', // identidade única: heartbeat + agente de tasks
   heartbeat: true, // "estou vivo" a cada 30s
 });
 
@@ -71,11 +71,11 @@ try {
 }
 ```
 
-Chame `Hobots.init` **uma vez**, o mais cedo possível no processo. Detalhes em [Monitor](./monitor.md).
+Chame `Hobots.init` **uma vez**, o mais cedo possível no processo. Detalhes em [Telemetria](./monitor.md).
 
-## Primeiro agente (Manager)
+## Primeiro agente (tasks)
 
-Habilite a execução sob demanda com o campo `manager` no mesmo `init()`:
+Habilite a execução sob demanda com o campo `tasks` no mesmo `init()`:
 
 ```js
 import * as Hobots from 'hobots';
@@ -83,7 +83,7 @@ import * as Hobots from 'hobots';
 Hobots.init({
   clientSecret: 'hb_<64 hex>',
   instanceId: 'vm-cliente-01',
-  manager: true, // ou { pollIntervalMs, concurrency, ... }
+  tasks: true, // ou { pollIntervalMs, concurrency, ... }
 });
 
 Hobots.register('processar-nfe', async (params, ctx) => {
@@ -93,21 +93,21 @@ Hobots.register('processar-nfe', async (params, ctx) => {
 Hobots.start(); // mantém o processo vivo até stop()/close()
 ```
 
-> O `instanceId` é a identidade dos **dois** canais (heartbeat do Monitor e agente do Manager) — o robô aparece como **um agente só** no painel, sem configuração extra.
+> 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.
 
-Detalhes (cancelamento, concorrência, idempotência) em [Manager](./manager.md).
+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).
 
 ## Encerramento
 
-`close()` encerra tudo na ordem certa: para o Manager (aguardando a run atual), o heartbeat e faz o flush final do transport.
+`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 Manager iniciado, o SDK não segura o processo (timers `unref`'d), mas faça o flush final para não perder eventos em buffer:
+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 o Manager, `start()` segura o processo por design. Encerre de forma graciosa aguardando a run atual:
+Com as tasks, `start()` segura o processo por design. Encerre de forma graciosa aguardando a run atual:
 
 ```js
 process.on('SIGINT', () => {
@@ -115,6 +115,6 @@ process.on('SIGINT', () => {
 });
 ```
 
-> **Atenção:** o `timeoutMs` do `close()` é gasto **duas vezes, em sequência** — uma esperando as runs do Manager, 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).
+> **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).
 
 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).

package/docs/monitor.md

@@ -1,6 +1,6 @@
-# Monitor
+# Telemetria
 
-Capability de telemetria: erros, performance, crons e uptime. Sempre ativa no `init()` único:
+Capability de telemetria: erros (módulo **Issues**), performance e uptime (módulo **Agentes**), crons (módulo **Monitores**). Sempre ativa no `init()` único:
 
 ```js
 import * as Hobots from 'hobots';
@@ -114,11 +114,11 @@ tx.finish(); // só aqui a transaction é enviada (respeitando tracesSampleRate)
 - A decisão de amostragem acontece no **`startTransaction()`**, não no `finish()`. Esquecer o `finish()` de um span não perde o dado: ele é fechado no instante em que a transaction fecha.
 - Uma transaction leva as tags do `init()` e as que você marcar com `tx.setTag()` — ela **não** herda as tags do scope.
 
-Dentro de um handler do Manager não abra transaction: já existe uma em [`ctx.tx`](./concepts.md#transaction-de-run-ctxtx).
+Dentro de um handler de task, `startTransaction()` **retorna a transaction da própria run** ([`ctx.tx`](./concepts.md#transaction-de-run-ctxtx)) em vez de criar uma segunda — cada execução tem exatamente **uma** transaction. Fora de um handler, ela cria uma transaction nova, sem correlação com run nenhuma.
 
 ## Crons (check-ins)
 
-Monitora jobs agendados: um check-in `in_progress` na entrada, `ok`/`error` na saída, com duração medida. O jeito recomendado é `withMonitor`, que faz o par e captura exceções:
+Monitora jobs agendados — o módulo **Monitores** do app: um check-in `in_progress` na entrada, `ok`/`error` na saída, com duração medida. O jeito recomendado é `withMonitor`, que faz o par e captura exceções:
 
 ```js
 await Hobots.withMonitor(
@@ -153,7 +153,7 @@ Hobots.init({
 
 O primeiro batimento sai **na hora** em que o `init()` roda — não depois do primeiro intervalo. O batimento também carrega o intervalo configurado: é assim que o servidor sabe quanto silêncio é normal antes de declarar o robô offline.
 
-Essa identidade é a mesma que o Manager envia no poll (`agent.instance_id`) — os dois canais derivam do `instanceId` do `init()`, então o robô aparece como **um agente só** em Monitor → Agentes automaticamente.
+Essa identidade é a mesma que o poll de tasks envia (`agent.instance_id`) — os dois canais derivam do `instanceId` do `init()`, então o robô aparece como **um agente só** no módulo Agentes automaticamente. Por isso, com `tasks: true` o heartbeat é **opcional** (o poll já marca a presença do agente); ele é essencial para agentes só de telemetria.
 
 ## Flush e close
 
@@ -161,13 +161,13 @@ Nada é enviado na hora: cada evento, transaction, check-in e heartbeat entra nu
 
 ```js
 await Hobots.flush(2000); // envia o que está em buffer, mantém o SDK vivo
-await Hobots.close(2000); // para o Manager (se ativo) + heartbeat + flush final do transport
+await Hobots.close(2000); // para o polling de tasks (se ativo) + heartbeat + flush final do transport
 ```
 
 O `timeoutMs` é opcional nas duas — o default é 5s (veja [Tempos e intervalos](./api-reference.md#tempos-e-intervalos)). As duas devolvem `false` quando estouram o prazo, o que significa que o SDK parou de esperar, **não** que os dados foram perdidos: os envios em voo continuam tentando enquanto o processo existir.
 
-Chame `close` antes do processo sair. Os timers do Monitor são `unref`'d, então a telemetria **não** segura o processo vivo sozinha (só o `start()` do Manager segura).
+Chame `close` antes do processo sair. Os timers da telemetria são `unref`'d, então ela **não** segura o processo vivo sozinha (só o `start()` das tasks segura).
 
 > **Atenção:** `close()` é **terminal**. Depois dele, todo evento, transaction, check-in ou heartbeat novo é **descartado** com aviso no console — não existe `reopen()`. Se o programa precisar voltar a emitir telemetria, chame `Hobots.init()` de novo.
 
-> **Atenção:** o `timeoutMs` do `close()` é gasto **duas vezes, em sequência** — uma esperando as runs do Manager, outra no flush final. `close(15_000)` pode levar até ~30s no pior caso. Dimensione por aí se o seu SIGTERM tem prazo curto.
+> **Atenção:** o `timeoutMs` do `close()` é gasto **duas vezes, em sequência** — uma esperando as runs de tasks, outra no flush final. `close(15_000)` pode levar até ~30s no pior caso. Dimensione por aí se o seu SIGTERM tem prazo curto.

package/docs/protocol.md

@@ -2,7 +2,7 @@
 
 O SDK é um **cliente HTTP puro**, sem dependências de runtime: ele só fala com o app da Hobots por HTTP. Não abre conexão com banco e **não** roda `SKIP LOCKED` — a reivindicação atômica de runs é server-side (veja o fim desta página).
 
-Os arquivos `src/protocol.ts` e `src/manager/protocol.ts` são a **fonte de verdade do wire format**: o app valida os payloads com zod travados nesses tipos (`satisfies z.ZodType<...>`), então não podem sofrer drift.
+Os arquivos `src/protocol.ts` e `src/tasks/protocol.ts` são a **fonte de verdade do wire format**: o app valida os payloads com zod travados nesses tipos (`satisfies z.ZodType<...>`), então não podem sofrer drift. Todos os tipos são exportados por `hobots/protocol` (e reexportados pelo import raiz `hobots`).
 
 ## O Client Secret e os endpoints derivados
 
@@ -14,18 +14,18 @@ hb_<64 hex>
 
 | Canal | Endpoint | Autenticação |
 | --- | --- | --- |
-| Monitor (ingestão) | `POST <baseUrl>/v1/ingest` | `Authorization: Bearer <clientSecret>` |
-| Manager (execução) | `<baseUrl>/v1/manager/*` | `Authorization: Bearer <clientSecret>` |
+| Telemetria (ingestão) | `POST <baseUrl>/v1/ingest` | `Authorization: Bearer <clientSecret>` |
+| Tasks (execução) | `<baseUrl>/v1/tasks/*` | `Authorization: Bearer <clientSecret>` |
 
-`resolveConfig({ clientSecret }) → { key, baseUrl, ingestEndpoint, managerBaseUrl }` (em `src/config.ts`, com a constante `DEFAULT_BASE_URL = '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>`) e viaja **só no header** `Authorization: Bearer` — nunca na URL da requisição.
+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.
 
-## Monitor — ingestão
+## Telemetria — ingestão
 
 Endpoint fixo `POST /v1/ingest` recebe **envelopes** JSON autenticados por Bearer. O transport mantém uma fila em memória, agrupa itens em envelopes e faz POST via `fetch`.
 
 ```jsonc
 {
-  "sdk": { "name": "hobots", "version": "1.0.0" },
+  "sdk": { "name": "hobots", "version": "2.0.0" },
   "sent_at": "2024-01-01T00:00:00.000Z",
   "items": [
     { "type": "event",       "payload": { /* EventPayload */ } },
@@ -38,24 +38,24 @@ Endpoint fixo `POST /v1/ingest` recebe **envelopes** JSON autenticados por Beare
 
 Tipos de item: `event`, `transaction`, `check_in`, `heartbeat` (definidos em `hobots/protocol`).
 
-Um `transaction` pode carregar `run_id`: é assim que a [transaction de uma run do Manager](./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()` não têm esse campo.
+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.
 
 **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).
 
-## Manager — polling e reporte
+## Tasks — polling e reporte
 
-Dois endpoints sob `<baseUrl>/v1/manager`, ambos com `Authorization: Bearer <clientSecret>` (a credencial única do projeto):
+Dois endpoints sob `<baseUrl>/v1/tasks`, ambos com `Authorization: Bearer <clientSecret>` (a credencial única do projeto):
 
-### `POST /v1/manager/poll`
+### `POST /v1/tasks/poll`
 
-Corpo `ManagerPollRequest`:
+Corpo `PollRequest`:
 
 ```jsonc
 {
   "agent": {
     "instance_id": "vm-01",       // identidade canônica do agente (obrigatória)
     "name": "VM 01",
-    "version": "1.0.0",
+    "version": "2.0.0",
     "host": "vm-01",
     "tasks": ["processar-nfe"]
   },
@@ -64,15 +64,15 @@ Corpo `ManagerPollRequest`:
 }
 ```
 
-Resposta `ManagerPollResponse` = `{ runs: ManagerRunDescriptor[] }`, cada `{ id, task, params, form, source, created_at }`.
+Resposta `PollResponse` = `{ runs: RunDescriptor[] }`, cada `{ id, task, params, form, source, created_at }`.
 
-O `agent.instance_id` é a **mesma identidade** do heartbeat do Monitor (`instance_id`): o servidor correlaciona os dois canais numa tabela `agents` por `(project_id, instance_id)`. Com o `init()` único, os dois derivam do `instanceId` — o robô aparece como um agente só no painel automaticamente.
+O `agent.instance_id` é a **mesma identidade** do heartbeat de telemetria (`instance_id`): o servidor correlaciona os dois canais numa tabela `agents` por `(project_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 do agente (`last_poll_at`), por isso o heartbeat é opcional quando as tasks estão habilitadas.
 
 **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]`.
 
-### `PATCH /v1/manager/runs/{id}`
+### `PATCH /v1/tasks/runs/{id}`
 
-Corpo `ManagerRunUpdateRequest`:
+Corpo `RunUpdateRequest`:
 
 ```jsonc
 {
@@ -88,15 +88,13 @@ Corpo `ManagerRunUpdateRequest`:
 - 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.
 - 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: `pending → claimed → running → succeeded | failed | canceled`. O agente só transiciona para `running`/`succeeded`/`failed`.
+Ciclo de vida completo da run no servidor (`RunStatus`): `pending → claimed → running → succeeded | failed | canceled`. O agente só transiciona para `running`/`succeeded`/`failed` (`RunUpdateStatus`).
 
 ## Onde vive o claim atômico
 
-O `POST /v1/manager/poll` no app chama `claimPendingRuns()` em
-[`apps/api/lib/manager/claim.ts`](../../../apps/api/lib/manager/claim.ts): um CTE que seleciona runs `pending` vencidas com `FOR UPDATE SKIP LOCKED` e as promove a `claimed` num único `UPDATE ... RETURNING`. Isso garante que dois agentes concorrentes nunca peguem a mesma run. **Nada disso está no SDK** — ele só faz o HTTP.
+O `POST /v1/tasks/poll` no app chama `claimPendingRuns()` em
+[`apps/api/lib/tasks/claim.ts`](../../../apps/api/lib/tasks/claim.ts): um CTE que seleciona runs `pending` vencidas com `FOR UPDATE SKIP LOCKED` e as promove a `claimed` num único `UPDATE ... RETURNING`. Isso garante que dois agentes concorrentes nunca peguem a mesma run. **Nada disso está no SDK** — ele só faz o HTTP.
 
 ## 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.
-
-> **Nota de manutenção:** `SDK_VERSION` é uma constante fixa e precisa ser mantida em sincronia com a `version` do `package.json` manualmente ao publicar.
+`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.

package/docs/{manager.md → tasks.md}

@@ -1,6 +1,6 @@
-# Manager
+# Tasks (execução sob demanda)
 
-Capability de **execução remota sob demanda**, habilitada com `manager: true` (ou opções) no `init()` único. O agente faz polling no app, executa os handlers registrados quando aparece trabalho e reporta status e logs incrementais. Usa o mesmo Client Secret, o mesmo `debug` e o `instanceId` como identidade — nenhum handler global extra é instalado.
+Capability de **execução remota sob demanda**, habilitada com `tasks: true` (ou opções) no `init()` único. O agente faz polling no app, executa os handlers registrados quando aparece trabalho e reporta status e logs incrementais — é o que alimenta o módulo **Solicitações** do app. Usa o mesmo Client Secret, o mesmo `debug` e o `instanceId` como identidade — nenhum handler global extra é instalado.
 
 O vocabulário desta página ([run](./concepts.md#run), [claim](./concepts.md#claim), [drain mode](./concepts.md#drain-mode), [ctx.tx](./concepts.md#transaction-de-run-ctxtx)) está explicado em [Conceitos](./concepts.md).
 
@@ -12,7 +12,7 @@ import * as Hobots from 'hobots';
 Hobots.init({
   clientSecret: 'hb_<64 hex>',
   instanceId: 'vm-cliente-01',
-  manager: true, // ou { pollIntervalMs, concurrency, taskTimeoutMs, logFlushIntervalMs }
+  tasks: true, // ou { pollIntervalMs, concurrency, taskTimeoutMs, logFlushIntervalMs }
 });
 
 Hobots.register('processar-nfe', async (params, ctx) => {
@@ -28,26 +28,26 @@ process.on('SIGINT', () => {
 });
 ```
 
-- `init({ manager })` — cria o agente. Chamar `init()` de novo para o agente anterior e o substitui (os handlers registrados são preservados). Se havia runs em execução, elas são interrompidas **sem espera** e reportadas como `AgentTerminated` na hora — `init()` não é um jeito gracioso de reconfigurar um agente ocupado; para isso use `stop()` antes.
-- `register(task, handler)` — `task` é o `task_slug` configurado no formulário do app. Registre **antes** de `start()`. Pode ser chamado antes do `init()`; se o `init()` não habilitou o Manager, o SDK avisa no console.
-- `start()` — começa o polling. Lança se o `init()` não configurou `manager` ou se nenhuma task foi registrada.
-- `stop(timeoutMs?)` — para **só o Manager**: encerra o polling e aguarda as runs ativas ([default](./api-reference.md#tempos-e-intervalos)); a telemetria continua. Retorna `false` se estourou o timeout.
+- `init({ tasks })` — cria o agente. Chamar `init()` de novo para o agente anterior e o substitui (os handlers registrados são preservados). Se havia runs em execução, elas são interrompidas **sem espera** e reportadas como `AgentTerminated` na hora — `init()` não é um jeito gracioso de reconfigurar um agente ocupado; para isso use `stop()` antes.
+- `register(task, handler)` — `task` é o `task_slug` configurado no formulário do app (**Configurações → Formulários**). Registre **antes** de `start()`. Pode ser chamado antes do `init()`; se o `init()` não habilitou as tasks, o SDK 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](./api-reference.md#tempos-e-intervalos)); a telemetria continua. Retorna `false` se estourou o timeout.
 - `close(timeoutMs?)` — encerra **tudo**: agente (aguardando runs em voo) → heartbeat → flush final.
 
-O `instanceId` (obrigatório) é a identidade do agente no painel — o poll o envia como `agent.instance_id`, a **mesma identidade** do heartbeat do Monitor. Com o `init()` único, os dois canais convergem em **um agente** automaticamente.
+O `instanceId` (obrigatório) é a identidade do agente no painel — o poll o envia como `agent.instance_id`, a **mesma identidade** do heartbeat de telemetria. Com o `init()` único, os dois canais convergem em **um agente** no módulo Agentes automaticamente. Com `tasks: true`, o heartbeat é **opcional**: o próprio poll já marca a presença do agente; o heartbeat continua essencial para agentes só de telemetria.
 
 > **Atenção:** ao contrário da telemetria, `start()` **segura o processo vivo** aguardando trabalho até `stop()`/`close()` — o agente é a razão do processo existir.
 
 ## O handler e o `RunContext`
 
 ```ts
-type ManagerTaskHandler<P = Record<string, unknown>> =
+type TaskHandler<P = Record<string, unknown>> =
   (params: P, ctx: RunContext) => void | Promise<void>;
 
 interface RunContext {
   runId: string;
   task: string;
-  log(level: 'debug' | 'info' | 'warning' | 'error', message: string): void;
+  log: RunLogger; // ctx.log.debug/info/warn/error/success(message)
   tx: Transaction;
   signal: AbortSignal;
   throwIfCanceled(): void;
@@ -56,7 +56,7 @@ interface RunContext {
 ```
 
 - **`params`** — os dados do formulário configurado no app (o JSON validado).
-- **`ctx.log.<level>(message)`** — logs enviados **incrementalmente** ao app (PATCHes com throttle), visíveis na run em tempo quase real. Cada linha também é **impressa no terminal local** como `[hobots:<task>] INFO mensagem`, colorida por nível — útil para acompanhar o robô rodando na VM. A cor é desligada automaticamente fora de um TTY e quando a env `NO_COLOR` está definida; o eco local é independente do envio ao servidor.
+- **`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 em tempo quase real. Cada linha também é **impressa no terminal local** como `[hobots:<task>] INFO mensagem`, colorida por nível — útil para acompanhar o robô rodando na VM. A cor é desligada automaticamente fora de um TTY e quando a env `NO_COLOR` está definida; o eco local é independente do envio ao servidor.
 - **`ctx.tx`** — a [transaction de performance](./concepts.md#transaction-de-run-ctxtx) desta run, já correlacionada e finalizada pelo SDK. Use `ctx.tx.startChild()` para medir as etapas (veja abaixo).
 - **`ctx.signal`** — `AbortSignal` que dispara quando a run é **cancelada no app**, em **timeout** ou no **shutdown**. Cancelamento é cooperativo (veja abaixo).
 - **`ctx.throwIfCanceled()`** — lança `RunCanceled` se o `signal` já disparou. O ponto de parada de 1 linha para chamar entre as etapas do trabalho.
@@ -66,7 +66,7 @@ interface RunContext {
 
 Você pode tipar os params: `Hobots.register<{ lote: number }>(...)`.
 
-> **Dados sensíveis:** o que você escreve em `ctx.log()` e as mensagens/stack de erros lançados **são enviados ao servidor** e ficam visíveis na execução no app. Não inclua senhas, tokens, documentos, dados pessoais ou qualquer informação sensível em logs e mensagens de erro.
+> **Dados sensíveis:** o que você escreve em `ctx.log` e as mensagens/stack de erros lançados **são enviados ao servidor** e ficam visíveis na execução no app. Não inclua senhas, tokens, documentos, dados pessoais ou qualquer informação sensível em logs e mensagens de erro.
 
 ## Performance da run (`ctx.tx`)
 
@@ -89,14 +89,14 @@ Hobots.register('processar-nfe', async (params, ctx) => {
 
 Cada `startChild` vira uma barra no waterfall da aba de performance daquela execução no app — é como você responde "onde foram os 4 minutos". Sem nenhum span, a transaction ainda mede o tempo total da run; o waterfall só fica com uma barra.
 
-- **Não chame `Hobots.startTransaction()` dentro de um handler.** Você criaria uma segunda transaction, sem correlação com a run, e ela não apareceria na execução.
-- `ctx.tx` **não respeita o `tracesSampleRate`** — toda run gera uma transaction. A amostragem vale só para as transactions que você abre com `startTransaction()`.
+- **`startTransaction()` dentro do handler devolve a própria `ctx.tx`.** Cada execução tem exatamente **uma** transaction: se o seu código (ou uma lib sua já instrumentada) chamar `Hobots.startTransaction()` dentro de um handler, o SDK detecta o contexto da run e retorna a transaction dela em vez de criar uma segunda — os spans caem no mesmo waterfall. Fora de um handler, `startTransaction()` cria uma transaction nova, sem `run_id`.
+- `ctx.tx` **não respeita o `tracesSampleRate`** — toda run gera uma transaction. A amostragem vale só para as transactions abertas com `startTransaction()` fora de uma run.
 - Span que você esquecer aberto é fechado no `finish()` da transaction, então o dado não se perde.
 - Marque etapas com ressalva usando `span.setStatus('warning')` (ex.: retry que deu certo, resultado parcial): elas aparecem em âmbar no waterfall, distintas de sucesso e de falha (`'error'`).
 
 ## Cancelamento cooperativo
 
-Uma run cancelada no app **não mata** o seu handler — o SDK não interrompe código em execução. Ele apenas dispara `ctx.signal`. Enquanto o handler roda, o SDK mantém um **heartbeat de cancelamento** (a cada `cancelCheckIntervalMs`, veja [Tempos e intervalos](./api-reference.md#tempos-e-intervalos)): a run cancelada no app é detectada em segundos, mesmo que o handler nunca chame `ctx.log()`. Chame **`ctx.throwIfCanceled()`** em loops longos e pontos de parada (e troque esperas por `ctx.sleep()`):
+Uma run cancelada no app **não mata** o seu handler — o SDK não interrompe código em execução. Ele apenas dispara `ctx.signal`. Enquanto o handler roda, o SDK mantém um **heartbeat de cancelamento** (a cada `cancelCheckIntervalMs`, veja [Tempos e intervalos](./api-reference.md#tempos-e-intervalos)): a run cancelada no app é detectada em segundos, mesmo que o handler nunca chame `ctx.log`. Chame **`ctx.throwIfCanceled()`** em loops longos e pontos de parada (e troque esperas por `ctx.sleep()`):
 
 ```js
 Hobots.register('processar-nfe', async (params, ctx) => {
@@ -113,7 +113,7 @@ Quando o cancelamento veio do app, a run já está `cancelada` no servidor — o
 
 Se o processo do agente **morre no meio de uma run**, a solicitação vira **falha** no app com erro `AgentTerminated` ("execução encerrada inesperadamente") — sem re-execução automática. Dois caminhos garantem isso:
 
-- **Morte capturável** (SIGINT/SIGTERM sem handler próprio do programa, erro não tratado): o SDK reporta a falha na hora (~2s, um PATCH best-effort com timeout curto) e então deixa o processo morrer com a semântica default do sinal. Os handlers são instalados no `start()` e **nunca interferem** quando o programa tem handler próprio para o sinal (o shutdown gracioso via `close()` continua sendo o caminho normal). Desative com `manager: { installExitHandlers: false }`.
+- **Morte capturável** (SIGINT/SIGTERM sem handler próprio do programa, erro não tratado): o SDK reporta a falha na hora (~2s, um PATCH best-effort com timeout curto) e então deixa o processo morrer com a semântica default do sinal. Os handlers são instalados no `start()` e **nunca interferem** quando o programa tem handler próprio para o sinal (o shutdown gracioso via `close()` continua sendo o caminho normal). Desative com `tasks: { installExitHandlers: false }`.
 - **Morte dura** (kill -9, queda de energia, rede fora): nada roda no cliente. O heartbeat de cancelamento é também o **sinal de vida da run** — o servidor marca a run como falha ao notar silêncio prolongado (o [sweep](./api-reference.md#tempos-e-intervalos) server-side).
 
 `close(timeoutMs)` que estoura o timeout com runs ainda em execução também reporta essas runs como `AgentTerminated` — o processo vai morrer em seguida e o app não deve mostrar a run como "executando" para sempre.
@@ -130,8 +130,8 @@ Se o agente morrer logo **após capturar** uma run (antes de reportar `running`)
 
 `taskTimeoutMs` é um timeout **client-side**. No estouro o SDK **não mata** o handler — ele dispara `ctx.signal`, libera o slot de concorrência e reporta a run como falha (`TaskTimeout`). O handler pode continuar rodando em background; respeite o `signal` para parar de verdade. Sem `taskTimeoutMs`, o backstop é o servidor.
 
-Todas as opções em [Referência de API → ManagerOptions](./api-reference.md#manageroptions).
+Todas as opções em [Referência de API → TasksOptions](./api-reference.md#tasksoptions).
 
 ## Como o claim funciona (resumo)
 
-O SDK é um cliente HTTP: ele faz `POST /v1/manager/poll` e o **servidor** reivindica as runs pendentes de forma atômica com `FOR UPDATE SKIP LOCKED` — dois agentes nunca pegam a mesma run. Conceito em [Claim](./concepts.md#claim), detalhes em [Protocolo & transporte](./protocol.md).
+O SDK é um cliente HTTP: ele faz `POST /v1/tasks/poll` e o **servidor** reivindica as runs pendentes de forma atômica com `FOR UPDATE SKIP LOCKED` — dois agentes nunca pegam a mesma run. Conceito em [Claim](./concepts.md#claim), detalhes em [Protocolo & transporte](./protocol.md).

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "hobots",
-  "version": "1.6.0",
-  "description": "SDK JavaScript da Hobots — captura de erros, transactions, check-ins de cron e heartbeats (Monitor) e execução remota de tarefas sob demanda (Manager) para RPAs e integrações. Um único import e um único init().",
+  "version": "1.7.0",
+  "description": "SDK JavaScript da Hobots — telemetria (erros, transactions, check-ins de cron e heartbeats) e execução remota de tarefas sob demanda (tasks) para RPAs e integrações. Um único import e um único init().",
   "type": "module",
   "sideEffects": false,
   "license": "MIT",
@@ -25,11 +25,6 @@
       "types": "./dist/protocol.d.ts",
       "import": "./dist/protocol.js",
       "require": "./dist/protocol.cjs"
-    },
-    "./manager/protocol": {
-      "types": "./dist/manager/protocol.d.ts",
-      "import": "./dist/manager/protocol.js",
-      "require": "./dist/manager/protocol.cjs"
     }
   },
   "scripts": {

package/dist/manager/protocol.cjs

@@ -1,19 +0,0 @@
-"use strict";
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-
-// src/manager/protocol.ts
-var protocol_exports = {};
-module.exports = __toCommonJS(protocol_exports);
-//# sourceMappingURL=protocol.cjs.map

package/dist/manager/protocol.cjs.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../../src/manager/protocol.ts"],"sourcesContent":["/**\n * Tipos do protocolo do Hobots Manager (agente SDK ↔ servidor).\n *\n * Este arquivo é a fonte de verdade do wire format e não pode importar nada:\n * o app valida os payloads com zod e trava o drift via `satisfies z.ZodType<...>`\n * contra estes tipos (reexportados por `hobots/protocol`; `hobots/manager/protocol` é alias de compatibilidade).\n */\n\n/** Ciclo de vida completo de uma run no servidor. */\nexport type ManagerRunStatus = 'pending' | 'claimed' | 'running' | 'succeeded' | 'failed' | 'canceled';\n\n/** Subconjunto que o agente pode enviar no PATCH. */\nexport type ManagerRunUpdateStatus = 'running' | 'succeeded' | 'failed';\n\nexport type RunLogLevel = 'debug' | 'info' | 'warning' | 'error' | 'success';\n\nexport interface RunLogEntry {\n  /** ISO 8601 — relógio do agente, apenas para exibição */\n  ts: string;\n  level: RunLogLevel;\n  message: string;\n}\n\nexport interface ManagerAgentInfo {\n  /** Identidade canônica do agente — correlaciona com o heartbeat do Monitor */\n  instance_id: string;\n  name?: string;\n  /** Versão do SDK */\n  version?: string;\n  /** Hostname da máquina */\n  host?: string;\n  /** Tasks registradas no agente */\n  tasks?: string[];\n}\n\n/** POST /v1/manager/poll */\nexport interface ManagerPollRequest {\n  agent?: ManagerAgentInfo;\n  /** Quantas runs reivindicar de uma vez (1..5). Default: 1 */\n  max?: number;\n  /** Só entrega runs destas tasks (nomes registrados no agente) */\n  tasks?: string[];\n}\n\nexport interface ManagerRunDescriptor {\n  id: string;\n  task: string;\n  params: Record<string, unknown>;\n  form: { id: string; name: string } | null;\n  /** Origem da run: 'hobots' | 'link' | 'schedule' (informativo) */\n  source: string;\n  /** ISO 8601 (relógio do servidor) */\n  created_at: string;\n}\n\nexport interface ManagerPollResponse {\n  runs: ManagerRunDescriptor[];\n}\n\nexport interface ManagerRunError {\n  /** ex.: nome da classe do erro */\n  type?: string;\n  message: string;\n  stack?: string;\n}\n\n/** PATCH /v1/manager/runs/{id} — 'running' pode repetir com logs incrementais */\nexport interface ManagerRunUpdateRequest {\n  status: ManagerRunUpdateStatus;\n  /** Apenas com status 'failed' */\n  error?: ManagerRunError;\n  /** Delta desde o último envio — o servidor concatena */\n  logs?: RunLogEntry[];\n}\n\nexport interface ManagerRunUpdateResponse {\n  ok: true;\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAAA;AAAA;","names":[]}

package/dist/manager/protocol.d.cts

@@ -1,72 +0,0 @@
-/**
- * Tipos do protocolo do Hobots Manager (agente SDK ↔ servidor).
- *
- * Este arquivo é a fonte de verdade do wire format e não pode importar nada:
- * o app valida os payloads com zod e trava o drift via `satisfies z.ZodType<...>`
- * contra estes tipos (reexportados por `hobots/protocol`; `hobots/manager/protocol` é alias de compatibilidade).
- */
-/** Ciclo de vida completo de uma run no servidor. */
-type ManagerRunStatus = 'pending' | 'claimed' | 'running' | 'succeeded' | 'failed' | 'canceled';
-/** Subconjunto que o agente pode enviar no PATCH. */
-type ManagerRunUpdateStatus = 'running' | 'succeeded' | 'failed';
-type RunLogLevel = 'debug' | 'info' | 'warning' | 'error' | 'success';
-interface RunLogEntry {
-    /** ISO 8601 — relógio do agente, apenas para exibição */
-    ts: string;
-    level: RunLogLevel;
-    message: string;
-}
-interface ManagerAgentInfo {
-    /** Identidade canônica do agente — correlaciona com o heartbeat do Monitor */
-    instance_id: string;
-    name?: string;
-    /** Versão do SDK */
-    version?: string;
-    /** Hostname da máquina */
-    host?: string;
-    /** Tasks registradas no agente */
-    tasks?: string[];
-}
-/** POST /v1/manager/poll */
-interface ManagerPollRequest {
-    agent?: ManagerAgentInfo;
-    /** Quantas runs reivindicar de uma vez (1..5). Default: 1 */
-    max?: number;
-    /** Só entrega runs destas tasks (nomes registrados no agente) */
-    tasks?: string[];
-}
-interface ManagerRunDescriptor {
-    id: string;
-    task: string;
-    params: Record<string, unknown>;
-    form: {
-        id: string;
-        name: string;
-    } | null;
-    /** Origem da run: 'hobots' | 'link' | 'schedule' (informativo) */
-    source: string;
-    /** ISO 8601 (relógio do servidor) */
-    created_at: string;
-}
-interface ManagerPollResponse {
-    runs: ManagerRunDescriptor[];
-}
-interface ManagerRunError {
-    /** ex.: nome da classe do erro */
-    type?: string;
-    message: string;
-    stack?: string;
-}
-/** PATCH /v1/manager/runs/{id} — 'running' pode repetir com logs incrementais */
-interface ManagerRunUpdateRequest {
-    status: ManagerRunUpdateStatus;
-    /** Apenas com status 'failed' */
-    error?: ManagerRunError;
-    /** Delta desde o último envio — o servidor concatena */
-    logs?: RunLogEntry[];
-}
-interface ManagerRunUpdateResponse {
-    ok: true;
-}
-
-export type { ManagerAgentInfo, ManagerPollRequest, ManagerPollResponse, ManagerRunDescriptor, ManagerRunError, ManagerRunStatus, ManagerRunUpdateRequest, ManagerRunUpdateResponse, ManagerRunUpdateStatus, RunLogEntry, RunLogLevel };

package/dist/manager/protocol.d.ts

@@ -1,72 +0,0 @@
-/**
- * Tipos do protocolo do Hobots Manager (agente SDK ↔ servidor).
- *
- * Este arquivo é a fonte de verdade do wire format e não pode importar nada:
- * o app valida os payloads com zod e trava o drift via `satisfies z.ZodType<...>`
- * contra estes tipos (reexportados por `hobots/protocol`; `hobots/manager/protocol` é alias de compatibilidade).
- */
-/** Ciclo de vida completo de uma run no servidor. */
-type ManagerRunStatus = 'pending' | 'claimed' | 'running' | 'succeeded' | 'failed' | 'canceled';
-/** Subconjunto que o agente pode enviar no PATCH. */
-type ManagerRunUpdateStatus = 'running' | 'succeeded' | 'failed';
-type RunLogLevel = 'debug' | 'info' | 'warning' | 'error' | 'success';
-interface RunLogEntry {
-    /** ISO 8601 — relógio do agente, apenas para exibição */
-    ts: string;
-    level: RunLogLevel;
-    message: string;
-}
-interface ManagerAgentInfo {
-    /** Identidade canônica do agente — correlaciona com o heartbeat do Monitor */
-    instance_id: string;
-    name?: string;
-    /** Versão do SDK */
-    version?: string;
-    /** Hostname da máquina */
-    host?: string;
-    /** Tasks registradas no agente */
-    tasks?: string[];
-}
-/** POST /v1/manager/poll */
-interface ManagerPollRequest {
-    agent?: ManagerAgentInfo;
-    /** Quantas runs reivindicar de uma vez (1..5). Default: 1 */
-    max?: number;
-    /** Só entrega runs destas tasks (nomes registrados no agente) */
-    tasks?: string[];
-}
-interface ManagerRunDescriptor {
-    id: string;
-    task: string;
-    params: Record<string, unknown>;
-    form: {
-        id: string;
-        name: string;
-    } | null;
-    /** Origem da run: 'hobots' | 'link' | 'schedule' (informativo) */
-    source: string;
-    /** ISO 8601 (relógio do servidor) */
-    created_at: string;
-}
-interface ManagerPollResponse {
-    runs: ManagerRunDescriptor[];
-}
-interface ManagerRunError {
-    /** ex.: nome da classe do erro */
-    type?: string;
-    message: string;
-    stack?: string;
-}
-/** PATCH /v1/manager/runs/{id} — 'running' pode repetir com logs incrementais */
-interface ManagerRunUpdateRequest {
-    status: ManagerRunUpdateStatus;
-    /** Apenas com status 'failed' */
-    error?: ManagerRunError;
-    /** Delta desde o último envio — o servidor concatena */
-    logs?: RunLogEntry[];
-}
-interface ManagerRunUpdateResponse {
-    ok: true;
-}
-
-export type { ManagerAgentInfo, ManagerPollRequest, ManagerPollResponse, ManagerRunDescriptor, ManagerRunError, ManagerRunStatus, ManagerRunUpdateRequest, ManagerRunUpdateResponse, ManagerRunUpdateStatus, RunLogEntry, RunLogLevel };

package/dist/manager/protocol.js

@@ -1 +0,0 @@
-//# sourceMappingURL=protocol.js.map

package/dist/manager/protocol.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}