hobots 1.6.0 → 1.7.0

package/dist/protocol.d.cts

@@ -1,7 +1,76 @@
-export { ManagerAgentInfo, ManagerPollRequest, ManagerPollResponse, ManagerRunDescriptor, ManagerRunError, ManagerRunStatus, ManagerRunUpdateRequest, ManagerRunUpdateResponse, ManagerRunUpdateStatus, RunLogEntry, RunLogLevel } from './manager/protocol.cjs';
+/**
+ * Tipos do protocolo de tasks do Hobots (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`).
+ */
+/** Ciclo de vida completo de uma run no servidor. */
+type RunStatus = 'pending' | 'claimed' | 'running' | 'succeeded' | 'failed' | 'canceled';
+/** Subconjunto que o agente pode enviar no PATCH. */
+type RunUpdateStatus = '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 AgentInfo {
+    /** Identidade canônica do agente — correlaciona com o heartbeat de telemetria */
+    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/tasks/poll */
+interface PollRequest {
+    agent?: AgentInfo;
+    /** Quantas runs reivindicar de uma vez (1..5). Default: 1 */
+    max?: number;
+    /** Só entrega runs destas tasks (nomes registrados no agente) */
+    tasks?: string[];
+}
+interface RunDescriptor {
+    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 PollResponse {
+    runs: RunDescriptor[];
+}
+interface RunError {
+    /** ex.: nome da classe do erro */
+    type?: string;
+    message: string;
+    stack?: string;
+}
+/** PATCH /v1/tasks/runs/{id} — 'running' pode repetir com logs incrementais */
+interface RunUpdateRequest {
+    status: RunUpdateStatus;
+    /** Apenas com status 'failed' */
+    error?: RunError;
+    /** Delta desde o último envio — o servidor concatena */
+    logs?: RunLogEntry[];
+}
+interface RunUpdateResponse {
+    ok: true;
+}
 
 /**
- * Tipos do protocolo de ingestão do Hobots Monitor (SDK → servidor).
+ * Tipos do protocolo do Hobots (SDK → servidor).
  *
  * Este arquivo é a fonte de verdade do wire format e só pode reexportar tipos:
  * o app valida os payloads com zod e trava o drift via `satisfies z.ZodType<...>`
@@ -82,7 +151,7 @@ interface TransactionPayload {
     tags?: Record<string, string>;
     release?: string;
     environment?: string;
-    /** Correlaciona esta transaction a uma execução do Manager (ctx.tx dentro de um task handler) */
+    /** Correlaciona esta transaction a uma execução de task (ctx.tx dentro de um task handler) */
     run_id?: string;
 }
 type CheckInStatus = 'in_progress' | 'ok' | 'error';
@@ -130,4 +199,4 @@ interface Envelope {
     items: EnvelopeItem[];
 }
 
-export type { Breadcrumb, CheckInPayload, CheckInStatus, Envelope, EnvelopeItem, EventPayload, EventUser, ExceptionData, HeartbeatPayload, Severity, SpanData, SpanStatus, StackFrame, TransactionPayload };
+export type { AgentInfo, Breadcrumb, CheckInPayload, CheckInStatus, Envelope, EnvelopeItem, EventPayload, EventUser, ExceptionData, HeartbeatPayload, PollRequest, PollResponse, RunDescriptor, RunError, RunLogEntry, RunLogLevel, RunStatus, RunUpdateRequest, RunUpdateResponse, RunUpdateStatus, Severity, SpanData, SpanStatus, StackFrame, TransactionPayload };

package/dist/protocol.d.ts

@@ -1,7 +1,76 @@
-export { ManagerAgentInfo, ManagerPollRequest, ManagerPollResponse, ManagerRunDescriptor, ManagerRunError, ManagerRunStatus, ManagerRunUpdateRequest, ManagerRunUpdateResponse, ManagerRunUpdateStatus, RunLogEntry, RunLogLevel } from './manager/protocol.js';
+/**
+ * Tipos do protocolo de tasks do Hobots (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`).
+ */
+/** Ciclo de vida completo de uma run no servidor. */
+type RunStatus = 'pending' | 'claimed' | 'running' | 'succeeded' | 'failed' | 'canceled';
+/** Subconjunto que o agente pode enviar no PATCH. */
+type RunUpdateStatus = '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 AgentInfo {
+    /** Identidade canônica do agente — correlaciona com o heartbeat de telemetria */
+    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/tasks/poll */
+interface PollRequest {
+    agent?: AgentInfo;
+    /** Quantas runs reivindicar de uma vez (1..5). Default: 1 */
+    max?: number;
+    /** Só entrega runs destas tasks (nomes registrados no agente) */
+    tasks?: string[];
+}
+interface RunDescriptor {
+    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 PollResponse {
+    runs: RunDescriptor[];
+}
+interface RunError {
+    /** ex.: nome da classe do erro */
+    type?: string;
+    message: string;
+    stack?: string;
+}
+/** PATCH /v1/tasks/runs/{id} — 'running' pode repetir com logs incrementais */
+interface RunUpdateRequest {
+    status: RunUpdateStatus;
+    /** Apenas com status 'failed' */
+    error?: RunError;
+    /** Delta desde o último envio — o servidor concatena */
+    logs?: RunLogEntry[];
+}
+interface RunUpdateResponse {
+    ok: true;
+}
 
 /**
- * Tipos do protocolo de ingestão do Hobots Monitor (SDK → servidor).
+ * Tipos do protocolo do Hobots (SDK → servidor).
  *
  * Este arquivo é a fonte de verdade do wire format e só pode reexportar tipos:
  * o app valida os payloads com zod e trava o drift via `satisfies z.ZodType<...>`
@@ -82,7 +151,7 @@ interface TransactionPayload {
     tags?: Record<string, string>;
     release?: string;
     environment?: string;
-    /** Correlaciona esta transaction a uma execução do Manager (ctx.tx dentro de um task handler) */
+    /** Correlaciona esta transaction a uma execução de task (ctx.tx dentro de um task handler) */
     run_id?: string;
 }
 type CheckInStatus = 'in_progress' | 'ok' | 'error';
@@ -130,4 +199,4 @@ interface Envelope {
     items: EnvelopeItem[];
 }
 
-export type { Breadcrumb, CheckInPayload, CheckInStatus, Envelope, EnvelopeItem, EventPayload, EventUser, ExceptionData, HeartbeatPayload, Severity, SpanData, SpanStatus, StackFrame, TransactionPayload };
+export type { AgentInfo, Breadcrumb, CheckInPayload, CheckInStatus, Envelope, EnvelopeItem, EventPayload, EventUser, ExceptionData, HeartbeatPayload, PollRequest, PollResponse, RunDescriptor, RunError, RunLogEntry, RunLogLevel, RunStatus, RunUpdateRequest, RunUpdateResponse, RunUpdateStatus, Severity, SpanData, SpanStatus, StackFrame, TransactionPayload };

package/docs/README.md

@@ -1,22 +1,22 @@
 # Documentação — hobots
 
-SDK JavaScript da **Hobots** para instrumentar funcionários digitais (RPAs) e integrações. Cliente HTTP puro, sem dependências de runtime, para Node 18+ (o Monitor também roda no browser para captura de erros).
+SDK JavaScript da **Hobots** para instrumentar funcionários digitais (RPAs) e integrações. Cliente HTTP puro, sem dependências de runtime, para Node 18+ (a telemetria também roda no browser para captura de erros).
 
 O SDK expõe **duas capabilities** autenticadas pelo **mesmo Client Secret do projeto**, configuradas em **um único `init()`** com **um único import** (`import * as Hobots from 'hobots'`):
 
 | Capability | Como habilita | Para quê |
 | --- | --- | --- |
-| **Monitor** | sempre ativo no `init()` | Telemetria que o programa **emite** sozinho: erros com stack trace, performance (transactions/spans), check-ins de cron e heartbeats de uptime. Instala handlers globais de erro; os timers são `unref`'d, então nunca seguram o processo vivo. |
-| **Manager** | `manager: true` (ou opções) no `init()` | Execução **sob demanda**: o agente faz polling no app, executa handlers registrados e reporta status/logs. `start()` **mantém o processo vivo** até `stop()`/`close()`. |
+| **Telemetria** | sempre ativa no `init()` | O que o programa **emite** sozinho: erros com stack trace (módulo **Issues**), performance (transactions/spans) e heartbeats de uptime (módulo **Agentes**), check-ins de cron (módulo **Monitores**). Instala handlers globais de erro; os timers são `unref`'d, então nunca seguram o processo vivo. |
+| **Tasks** | `tasks: true` (ou opções) no `init()` | Execução **sob demanda**: o agente faz polling no app, executa handlers registrados e reporta status/logs — o módulo **Solicitações**. `start()` **mantém o processo vivo** até `stop()`/`close()`. |
 
 ## Páginas
 
 Se termos como transaction, span, breadcrumb, tag, context, extra, flush e close ainda não são familiares, comece por **Conceitos** — as outras páginas assumem esse vocabulário.
 
 - [Conceitos](./concepts.md) — o vocabulário: o que cada coisa é, por que existe e quando escolher uma em vez da outra.
-- [Getting started](./getting-started.md) — instalação, Client Secret, o `init` único, Monitor e Manager.
-- [Monitor](./monitor.md) — erros, breadcrumbs, escopo, transactions/spans, crons e heartbeat.
-- [Manager](./manager.md) — registro de handlers, `RunContext`, cancelamento, concorrência, idempotência.
+- [Getting started](./getting-started.md) — instalação, Client Secret, o `init` único, telemetria e tasks.
+- [Telemetria](./monitor.md) — erros, breadcrumbs, escopo, transactions/spans, crons e heartbeat.
+- [Tasks](./tasks.md) — registro de handlers, `RunContext`, cancelamento, concorrência, idempotência.
 - [Referência de API](./api-reference.md) — todas as funções e tabelas de opções com defaults.
 - [Protocolo & transporte](./protocol.md) — o Client Secret, endpoints, envelope, retries e onde vive o claim atômico.
 
@@ -28,13 +28,13 @@ import * as Hobots from 'hobots';
 // O Client Secret do projeto — copie em Configurações → Projetos no app
 const clientSecret = 'hb_<64 hex>';
 
-// Um init só: telemetria sempre ativa; manager habilita a execução sob demanda.
+// Um init só: telemetria sempre ativa; tasks habilita a execução sob demanda.
 // O instanceId é a identidade única — o robô aparece como um agente só no painel.
 Hobots.init({
   clientSecret,
   instanceId: 'vm-cliente-01',
   heartbeat: true,
-  manager: true,
+  tasks: true,
 });
 
 Hobots.register('processar-nfe', async (params, ctx) => {

package/docs/api-reference.md

@@ -4,12 +4,12 @@
 
 | Import | Conteúdo |
 | --- | --- |
-| `hobots` | Tudo: `init` único, funções do Monitor, `register`/`start`/`stop` do Manager, `close`, classes (`Client`, `Scope`, `Transaction`, `Span`, `ManagerAgent`, `ManagerApi`), `resolveConfig`, `DEFAULT_BASE_URL` e tipos. |
-| `hobots/protocol` | Tipos do wire format (Monitor e Manager). |
+| `hobots` | Tudo: `init` único, funções de telemetria, `register`/`start`/`stop` de tasks, `close`, classes (`Client`, `Scope`, `Transaction`, `Span`), `DEFAULT_BASE_URL`, `scrubSecrets` e tipos. |
+| `hobots/protocol` | Tipos do wire format (telemetria e tasks). |
 
 ---
 
-## Monitor — funções
+## Telemetria — funções
 
 | Função | Assinatura | Retorno |
 | --- | --- | --- |
@@ -23,18 +23,18 @@
 | `setContext` | `setContext(name: string, ctx: Record<string,unknown> \| null): void` | — |
 | `setExtra` | `setExtra(key: string, value: unknown): void` | — |
 | `withScope` | `withScope<T>(cb: (scope: Scope) => T): T` | retorno do callback |
-| `startTransaction` | `startTransaction(name: string, op?: string): Transaction` | transaction |
+| `startTransaction` | `startTransaction(name: string, op?: string): Transaction` | transaction (dentro de um handler de task, a própria `ctx.tx`) |
 | `checkIn` | `checkIn(options: CheckInOptions): string \| undefined` | check_in_id |
 | `withMonitor` | `withMonitor<T>(slug: string, fn: () => T \| Promise<T>, options?: WithMonitorOptions): Promise<T>` | retorno de `fn` |
 | `flush` | `flush(timeoutMs = 5_000): Promise<boolean>` | enviou tudo dentro do prazo? |
-| `close` | `close(timeoutMs = 5_000): Promise<boolean>` | para o Manager (aguarda runs) + heartbeat + flush final do transport |
+| `close` | `close(timeoutMs = 5_000): Promise<boolean>` | para o polling de tasks (aguarda runs) + heartbeat + flush final do transport |
 
 ### O que cada função faz
 
 Os conceitos por trás dessas chamadas estão em [Conceitos](./concepts.md); aqui está o que cada uma **faz** e o que **devolve**.
 
-- **`init(options)`** — cria o cliente, instala os handlers globais de erro (a menos que `captureUnhandled: false`), inicia o heartbeat se configurado e cria o agente do Manager se `manager` foi passado. Chamar de novo **substitui** o cliente e o agente (os handlers registrados com `register` são preservados; o [scope](./concepts.md#scope) **não** é limpo). Chame uma vez, o mais cedo possível.
-- **`getClient()`** — devolve o cliente atual ou `undefined` se o `init()` nunca rodou. Útil para checar se o SDK está ativo.
+- **`init(options)`** — cria o cliente, instala os handlers globais de erro (a menos que `captureUnhandled: false`), inicia o heartbeat se configurado e cria o agente de tasks se `tasks` foi passado. Chamar de novo **substitui** o cliente e o agente (os handlers registrados com `register` são preservados; o [scope](./concepts.md#scope) **não** é limpo). Chame uma vez, o mais cedo possível.
+- **`getClient()`** — devolve o cliente atual ou `undefined` se o `init()` nunca rodou. Útil para checar se o SDK está ativo. A config resolvida (URL base e endpoints) é acessível via `getClient()?.config` (veja abaixo).
 - **`captureException(error, hint?)`** — monta um [evento](./concepts.md#evento) a partir da exceção (tipo, mensagem, stack trace), mescla o scope e enfileira. O `level` é `error` a menos que você passe outro no `hint`.
 - **`captureMessage(message, level = 'info', hint?)`** — mesma coisa, sem exceção: um evento só com texto. Bom para marcos (`'success'`) e avisos que não são erro.
   > **Atenção:** as duas devolvem um `event_id` **mesmo quando o evento foi descartado** por [amostragem](./concepts.md#amostragem-samplerate-e-tracessamplerate) ou por [`beforeSend`](./concepts.md#beforesend). O retorno não prova que algo foi enviado — só é `undefined` quando o `init()` não foi chamado.
@@ -44,21 +44,21 @@ Os conceitos por trás dessas chamadas estão em [Conceitos](./concepts.md); aqu
 - **`setContext(name, ctx | null)`** — define um [context](./concepts.md#context) nomeado. Passar `null` **apaga o grupo inteiro**. Os grupos `runtime` e `os` são injetados pelo SDK em todo evento.
 - **`setExtra(key, value)`** — anexa um dado livre, sem estrutura e sem índice. Conceito e critério de escolha em [Extra](./concepts.md#extra).
 - **`withScope(cb)`** — roda o callback com um **clone** do scope e restaura o original no fim; devolve o que o callback devolver. É **síncrono** — um `await` dentro do callback não isola de código concorrente. Conceito: [withScope](./concepts.md#withscope).
-- **`startTransaction(name, op?)`** — abre uma [transaction](./concepts.md#transaction) de performance. A decisão de [amostragem](./concepts.md#amostragem-samplerate-e-tracessamplerate) acontece **aqui**, não no `finish()`. Nada é enviado até o `finish()`. Dentro de um handler do Manager, use [`ctx.tx`](./concepts.md#transaction-de-run-ctxtx) em vez desta.
+- **`startTransaction(name, op?)`** — abre uma [transaction](./concepts.md#transaction) de performance. A decisão de [amostragem](./concepts.md#amostragem-samplerate-e-tracessamplerate) acontece **aqui**, não no `finish()`. Nada é enviado até o `finish()`. **Dentro de um handler de task**, devolve a [transaction da própria run](./concepts.md#transaction-de-run-ctxtx) (`ctx.tx`) em vez de criar uma segunda — cada execução tem exatamente uma transaction; fora de um handler, cria uma transaction nova, sem `run_id`.
 - **`checkIn(options)`** — envia um [check-in](./concepts.md#check-in) avulso e devolve o `check_in_id`. Reaproveite o id do `in_progress` para fechar a execução com `ok`/`error`.
 - **`withMonitor(slug, fn, options?)`** — envolve `fn` no par de check-ins (`in_progress` → `ok`/`error`) medindo a duração, e devolve o que `fn` devolver. Em caso de erro, fecha como `error`, captura o evento com a tag `monitor: <slug>` e **relança** a exceção. Passe `schedule` para o servidor criar/atualizar o monitor sozinho e detectar execução perdida.
 - **`flush(timeoutMs = 5_000)`** → `Promise<boolean>` — empurra a fila do transport e aguarda os envios em andamento. `true` = tudo saiu no prazo; `false` = o SDK parou de esperar (os envios em voo seguem tentando). O SDK **continua utilizável** depois. Conceito: [Fila, flush e close](./concepts.md#fila-flush-e-close).
 - **`close(timeoutMs = 5_000)`** → `Promise<boolean>` — encerra tudo na ordem agente → heartbeat → flush final. O `timeoutMs` é gasto **duas vezes** (espera das runs, depois flush). Depois do `close()` o transport está fechado e todo item novo é descartado com aviso no console; não há `reopen()`. Conceito: [Fila, flush e close](./concepts.md#fila-flush-e-close).
 
-Classes exportadas: `Client`, `Scope`, `Transaction`, `Span`. Função `resolveConfig({ clientSecret }): ResolvedConfig` — resolve a credencial nos endpoints (constante `DEFAULT_BASE_URL = 'https://api2.hobots.app'`, em `src/config.ts`; em desenvolvimento a env `HOBOTS_API_URL` sobrescreve a URL base):
+Classes exportadas: `Client`, `Scope`, `Transaction`, `Span`. A resolução da credencial nos endpoints é interna ao `init()` (constante `DEFAULT_BASE_URL = 'https://api2.hobots.app'`, exportada; em desenvolvimento a env `HOBOTS_API_URL` sobrescreve a URL base). A config resolvida fica acessível em `getClient()?.config`:
 
 ```ts
-interface ResolvedConfig {
-  key: string;            // Client Secret do projeto (vai no Authorization: Bearer, nunca na URL)
-  baseUrl: string;        // DEFAULT_BASE_URL, ou HOBOTS_API_URL em desenvolvimento
-  ingestEndpoint: string; // <baseUrl>/v1/ingest
-  managerBaseUrl: string; // <baseUrl>/v1/manager
-}
+getClient()?.config; // {
+//   key: string;            — Client Secret do projeto (vai no Authorization: Bearer, nunca na URL)
+//   baseUrl: string;        — DEFAULT_BASE_URL, ou HOBOTS_API_URL em desenvolvimento
+//   ingestEndpoint: string; — <baseUrl>/v1/ingest
+//   tasksBaseUrl: string;   — <baseUrl>/v1/tasks
+// }
 ```
 
 ### Métodos de `Transaction` / `Span` / `Scope`
@@ -72,25 +72,23 @@ Todos encadeáveis, exceto `finish()` e `toJSON()`.
 
 ---
 
-## Manager — funções
+## Tasks — funções
 
-Habilitado com `manager: true` (ou `ManagerOptions`) no `init()` único. Todas exportadas do import raiz `hobots`:
+Habilitadas com `tasks: true` (ou `TasksOptions`) no `init()` único. Todas exportadas do import raiz `hobots`:
 
 | Função | Assinatura |
 | --- | --- |
-| `register` | `register<P>(task: string, handler: ManagerTaskHandler<P>): void` |
-| `start` | `start(): void` — lança se o `init()` não configurou `manager` ou sem tasks registradas |
-| `stop` | `stop(timeoutMs = 30_000): Promise<boolean>` — para só o Manager; a telemetria continua |
+| `register` | `register<P>(task: string, handler: TaskHandler<P>): void` |
+| `start` | `start(): void` — lança se o `init()` não configurou `tasks` ou sem tasks registradas |
+| `stop` | `stop(timeoutMs = 30_000): Promise<boolean>` — para só o polling de tasks; a telemetria continua |
 
 ### O que cada função faz
 
-- **`register(task, handler)`** — associa um handler ao `task_slug` configurado no formulário do app. Registre **antes** de `start()`; pode ser chamado antes do `init()`. Registrar o mesmo `task` duas vezes **sobrescreve** o handler (com aviso no console). Se o `init()` não habilitou o Manager, o SDK avisa e não faz nada. Tipagem dos params: `register<{ lote: number }>(…)`.
-- **`start()`** — começa o polling. **Mantém o processo vivo** até `stop()`/`close()` — o timer não é `unref`'d, ao contrário dos do Monitor. Lança se o `init()` não configurou `manager` ou se nenhuma task foi registrada. Também instala os handlers de saída (SIGINT/SIGTERM/erro fatal) que reportam as runs ativas como `AgentTerminated`, a menos que `installExitHandlers: false`.
-- **`stop(timeoutMs = 30_000)`** → `Promise<boolean>` — encerra o polling e aguarda as [runs](./concepts.md#run) ativas terminarem. Para **só o Manager**: a telemetria (heartbeat, captura de erros) continua funcionando. Devolve `false` se estourou o timeout — as runs que ainda estavam rodando são reportadas como `AgentTerminated`. Para encerrar tudo, use [`close()`](./concepts.md#fila-flush-e-close).
-
-Classes/erros exportados: `ManagerAgent`, `ManagerApi`, `ManagerApiError`.
+- **`register(task, handler)`** — associa um handler ao `task_slug` configurado no formulário do app (**Configurações → Formulários**). Registre **antes** de `start()`; pode ser chamado antes do `init()`. Registrar o mesmo `task` duas vezes **sobrescreve** o handler (com aviso no console). Se o `init()` não habilitou as tasks, o SDK avisa e não faz nada. Tipagem dos params: `register<{ lote: number }>(…)`.
+- **`start()`** — começa o polling. **Mantém o processo vivo** até `stop()`/`close()` — o timer não é `unref`'d, ao contrário dos da telemetria. Lança se o `init()` não configurou `tasks` ou se nenhuma task foi registrada. Também instala os handlers de saída (SIGINT/SIGTERM/erro fatal) que reportam as runs ativas como `AgentTerminated`, a menos que `installExitHandlers: false`.
+- **`stop(timeoutMs = 30_000)`** → `Promise<boolean>` — encerra o polling e aguarda as [runs](./concepts.md#run) ativas terminarem. Para **só as tasks**: a telemetria (heartbeat, captura de erros) continua funcionando. Devolve `false` se estourou o timeout — as runs que ainda estavam rodando são reportadas como `AgentTerminated`. Para encerrar tudo, use [`close()`](./concepts.md#fila-flush-e-close).
 
-No poll, o agente se identifica com `ManagerAgentInfo` (`hobots/protocol`): o campo `instance_id` (o `instanceId` do `init()`) é a identidade canônica do agente — a mesma do heartbeat do Monitor, então os dois canais convergem em um agente no painel.
+No poll, o agente se identifica com `AgentInfo` (`hobots/protocol`): o campo `instance_id` (o `instanceId` do `init()`) é a identidade canônica do agente — a mesma do heartbeat de telemetria, então os dois canais convergem em um agente no painel.
 
 ---
 
@@ -103,14 +101,14 @@ No poll, o agente se identifica com `ManagerAgentInfo` (`hobots/protocol`): o ca
 | `clientSecret` | `string` | — | **obrigatório**; o Client Secret do projeto (`hb_<64 hex>`), copiado em **Configurações → Projetos** |
 | `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 do Monitor e agente do Manager convergem nela |
+| `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 |
 | `heartbeat` | `boolean \| HeartbeatOptions` | `false` | heartbeat periódico |
-| `manager` | `boolean \| ManagerOptions` | `false` | habilita o agente Manager (`true` usa defaults) |
+| `tasks` | `boolean \| TasksOptions` | `false` | habilita a execução sob demanda (`true` usa defaults) |
 | `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 |
@@ -155,9 +153,9 @@ O teto da fila do transport (200 itens; ao encher, o **mais antigo** é descarta
 | `schedule` | `string` | expressão cron (upsert do monitor) |
 | `timezone` | `string` | fuso do `schedule` |
 
-### ManagerOptions
+### TasksOptions
 
-Valor do campo `manager` do `InitOptions`. O Client Secret, o `debug` e a identidade (`instanceId`) vêm do `init()`.
+Valor do campo `tasks` do `InitOptions`. O Client Secret, o `debug` e a identidade (`instanceId`) vêm do `init()`.
 
 | Opção | Tipo | Default | Descrição |
 | --- | --- | --- | --- |
@@ -168,17 +166,17 @@ Valor do campo `manager` do `InitOptions`. O Client Secret, o `debug` e a identi
 | `cancelCheckIntervalMs` | `number` | `5000` | heartbeat de cancelamento por run (clamp 1000..15000) — também é o sinal de vida da run (servidor marca `AgentTerminated` após ~60s sem reporte) |
 | `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 |
 
-### ManagerTaskHandler / RunContext
+### TaskHandler / RunContext
 
 ```ts
 // o retorno do handler é ignorado — nada além de status/logs/erro é enviado ao servidor
-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; // transaction desta run — correlacionada e finalizada pelo SDK
   signal: AbortSignal;
   throwIfCanceled(): void; // lança RunCanceled se o signal já disparou
@@ -187,8 +185,8 @@ interface RunContext {
 ```
 
 - **`runId` / `task`** — identificam a execução; úteis para correlacionar com os seus próprios logs.
-- **`log(level, message)`** — enfileira uma linha de log enviada ao app em PATCHes incrementais, e **também imprime no terminal local**. Conceito: [Run](./concepts.md#run).
-- **`tx`** — a [transaction de performance da run](./concepts.md#transaction-de-run-ctxtx). Use `ctx.tx.startChild(op, description)` para medir as etapas; **não** chame `finish()` nela nem abra uma transaction própria com `startTransaction()`.
+- **`log.<level>(message)`** — níveis `debug`, `info`, `warn`, `error` e `success`; enfileira uma linha de log enviada ao app em PATCHes incrementais, e **também imprime no terminal local**. Conceito: [Run](./concepts.md#run).
+- **`tx`** — a [transaction de performance da run](./concepts.md#transaction-de-run-ctxtx). Use `ctx.tx.startChild(op, description)` para medir as etapas; **não** chame `finish()` nela. `startTransaction()` dentro do handler devolve essa mesma transaction.
 - **`signal`** — `AbortSignal` que dispara em cancelamento no app, timeout ou shutdown.
 - **`throwIfCanceled()`** — o ponto de parada de uma linha: lança `RunCanceled` se o `signal` já disparou.
 - **`sleep(ms)`** — espera que respeita o `signal` (rejeita com `RunCanceled` em vez de dormir até o fim). Use no lugar do seu `sleep` em esperas longas.
@@ -199,7 +197,7 @@ interface RunContext {
 
 Todos os prazos do SDK num lugar só. A coluna **Onde configura** diz se o valor é seu ou fixo — o que está com `—` é comportamento do SDK ou do servidor e não se muda pelo `init()`.
 
-### Monitor — envio de telemetria
+### Telemetria — envio
 
 | Tempo | Default | Onde configura | O que acontece |
 | --- | --- | --- | --- |
@@ -211,20 +209,20 @@ Todos os prazos do SDK num lugar só. A coluna **Onde configura** diz se o valor
 | ladder de retry | `1s, 4s, 16s` | — (fixo) | 3 tentativas por envelope; depois ele é descartado. 4xx (exceto 429) não tem retry |
 | heartbeat | `30000` ms | `init({ heartbeat: { intervalMs } })` | bate **imediatamente** no `init()` e depois a cada intervalo; o valor vai no payload e define quanto silêncio o servidor tolera antes de marcar offline |
 
-### Manager — polling e runs
+### Tasks — polling e runs
 
 | Tempo | Default | Onde configura | O que acontece |
 | --- | --- | --- | --- |
-| poll sem trabalho | `5000` ms (mín. `1000`) | `manager: { pollIntervalMs }` | é só o **teto da espera quando não há nada**: com trabalho na fila o próximo poll é imediato ([drain mode](./concepts.md#drain-mode)) |
-| flush de logs da run | `2000` ms | `manager: { logFlushIntervalMs }` | ou na hora, ao acumular 20 linhas |
-| heartbeat de cancelamento | `5000` ms (clamp `1000`..`15000`) | `manager: { cancelCheckIntervalMs }` | detecta cancelamento feito no app **e** é o sinal de vida da run (veja a nota 2) |
-| timeout por run | sem timeout | `manager: { taskTimeoutMs }` | no estouro dispara `ctx.signal`, libera o slot de concorrência e reporta `TaskTimeout` — **não mata** o handler |
+| poll sem trabalho | `5000` ms (mín. `1000`) | `tasks: { pollIntervalMs }` | é só o **teto da espera quando não há nada**: com trabalho na fila o próximo poll é imediato ([drain mode](./concepts.md#drain-mode)) |
+| flush de logs da run | `2000` ms | `tasks: { logFlushIntervalMs }` | ou na hora, ao acumular 20 linhas |
+| heartbeat de cancelamento | `5000` ms (clamp `1000`..`15000`) | `tasks: { cancelCheckIntervalMs }` | detecta cancelamento feito no app **e** é o sinal de vida da run (veja a nota 2) |
+| timeout por run | sem timeout | `tasks: { taskTimeoutMs }` | no estouro dispara `ctx.signal`, libera o slot de concorrência e reporta `TaskTimeout` — **não mata** o handler |
 | `stop(timeoutMs)` | `30000` ms | argumento | espera as runs ativas; no estouro elas são reportadas como `AgentTerminated` |
 | retry do poll | `1s, 4s, 16s` | — (fixo) | erros de rede/5xx |
 | retry com chave rejeitada (401) | `30000` ms | — (fixo) | segue tentando devagar, com log throttled |
 | PATCH do caminho de saída | `~2500` ms | — (fixo) | melhor esforço, sem retry, ao morrer com run ativa |
 | sweep do servidor | `~60000` ms | — (servidor) | run `running` sem reporte por esse tempo vira `failed`/`AgentTerminated`, sem re-entrega |
 
-**Nota 1 — `close(timeoutMs)` gasta o tempo duas vezes.** Ele espera as runs do Manager (`timeoutMs`) e **depois** faz o flush final (`timeoutMs`), em sequência. Pior caso ≈ `2 × timeoutMs`; `close()` sem argumento pode levar até ~35s (30s aguardando runs + 5s de flush). Se o seu SIGTERM tem prazo curto (Kubernetes, systemd), dimensione por aí.
+**Nota 1 — `close(timeoutMs)` gasta o tempo duas vezes.** Ele espera as runs de tasks (`timeoutMs`) e **depois** faz o flush final (`timeoutMs`), em sequência. Pior caso ≈ `2 × timeoutMs`; `close()` sem argumento pode levar até ~35s (30s aguardando runs + 5s de flush). Se o seu SIGTERM tem prazo curto (Kubernetes, systemd), dimensione por aí.
 
 **Nota 2 — o teto de 15s do `cancelCheckIntervalMs` existe por causa do sweep de 60s.** Esse heartbeat é o que mantém o `last_report_at` da run atualizado; o clamp garante que o intervalo nunca chegue perto do prazo em que o servidor declara a run morta.

package/docs/concepts.md

@@ -21,13 +21,13 @@ Os defaults numéricos **não** estão aqui — eles vivem em [Tempos e interval
 | [Breadcrumb](#breadcrumb)                               | Migalha da trilha que levou até o erro                   | Marcar cada passo relevante do robô                         |
 | [Transaction](#transaction)                             | Unidade de trabalho nomeada, com duração                 | Medir quanto uma rotina inteira demorou                     |
 | [Span](#span)                                           | Uma etapa medida dentro da transaction                   | Descobrir **onde** o tempo foi gasto                        |
-| [ctx.tx](#transaction-de-run-ctxtx)                     | A transaction que o SDK já abriu para a run              | Medir as etapas de um handler do Manager                    |
+| [ctx.tx](#transaction-de-run-ctxtx)                     | A transaction que o SDK já abriu para a run              | Medir as etapas de um handler de task                       |
 | [Amostragem](#amostragem-samplerate-e-tracessamplerate) | Enviar só uma fração do que acontece                     | Volume alto demais para enviar tudo                         |
 | [Check-in](#check-in)                                   | Par de avisos "comecei" / "terminei" de um job agendado  | Cron que precisa ser vigiado                                |
 | [Heartbeat](#heartbeat)                                 | Batimento "estou vivo"                                   | Saber que o robô está de pé, mesmo parado                   |
 | [instanceId](#instanceid)                               | A identidade da instância do robô                        | Sempre — é obrigatório no `init()`                          |
 | [Release e environment](#release-e-environment)         | Qual versão, em qual ambiente                            | Separar produção de homologação; achar a versão que quebrou |
-| [Run](#run)                                             | Uma execução solicitada no app                           | O Manager inteiro gira em volta disso                       |
+| [Run](#run)                                             | Uma execução solicitada no app                           | As tasks inteiras giram em volta disso                      |
 | [Claim](#claim)                                         | O ato de um agente pegar uma run para si                 | Entender por que dois agentes nunca colidem                 |
 | [Drain mode](#drain-mode)                               | O agente acelera o poll enquanto tem trabalho            | Entender o ritmo do polling                                 |
 | [Fila, flush e close](#fila-flush-e-close)              | Nada é enviado na hora — vai para uma fila               | Encerrar o processo sem perder telemetria                   |
@@ -35,15 +35,28 @@ Os defaults numéricos **não** estão aqui — eles vivem em [Tempos e interval
 
 > **Nota de manutenção:** esta página é a fonte canônica das explicações de conceito. As outras páginas da doc, o `README.md` do pacote e os tooltips do app parafraseiam daqui — quando um conceito muda, muda aqui primeiro.
 
+## O SDK e os módulos do app
+
+Cada API do SDK alimenta um módulo do app da Hobots (app.hobots.app). O mapa:
+
+| No SDK | No app |
+| --- | --- |
+| **Projeto** — o "funcionário digital"; dono do Client Secret (`hb_…`) que autentica tudo | **Configurações → Projetos** (é lá que você copia a credencial) |
+| **Agente / instância** — o par `(project_id, instance_id)`; heartbeat e poll de tasks convergem nele | Módulo **Agentes** (uptime, performance) |
+| **[Evento](#evento)** agrupado em **issue** — `captureException` / `captureMessage` | Módulo **Issues** |
+| **Monitor (cron)** — `withMonitor` / `checkIn` com `schedule` | Módulo **Monitores** |
+| **[Transaction](#transaction) / spans** — `startTransaction` (e [`ctx.tx`](#transaction-de-run-ctxtx) dentro de uma run) | Performance no módulo **Agentes**; nas execuções, a aba de performance da solicitação |
+| **Task / [run](#run)** — `register('task-slug', …)` casa com o `task_slug` do formulário | Módulo **Solicitações** (formulários em **Configurações → Formulários**) |
+
 ---
 
 ## Evento
 
-Um **evento** é a foto de um instante que vale a pena registrar: uma exceção que estourou ou uma mensagem que você mandou. É a unidade básica do Monitor.
+Um **evento** é a foto de um instante que vale a pena registrar: uma exceção que estourou ou uma mensagem que você mandou. É a unidade básica da telemetria.
 
 Quando você chama `captureException` ou `captureMessage`, o SDK monta o evento com o que a exceção traz (tipo, mensagem, stack trace com os frames em ordem) e **anexa tudo que está no [scope](#scope)** naquele momento: tags, usuário, contexts, extras e a trilha de [breadcrumbs](#breadcrumb). Depois disso o evento vai para a [fila](#fila-flush-e-close) e é enviado em lote.
 
-No servidor, eventos parecidos são agrupados numa **issue** — é por isso que 4.000 falhas do mesmo timeout não viram 4.000 linhas na sua tela. Quem decide o que é "parecido" é o [fingerprint](#fingerprint).
+No servidor, eventos parecidos são agrupados numa **issue** — o que você vê no módulo Issues do app. É por isso que 4.000 falhas do mesmo timeout não viram 4.000 linhas na sua tela. Quem decide o que é "parecido" é o [fingerprint](#fingerprint).
 
 ```js
 Hobots.captureException(error);
@@ -207,7 +220,7 @@ Tamanho do buffer: [`maxBreadcrumbs`](./api-reference.md#initoptions).
 
 Uma **transaction** é uma unidade de trabalho **nomeada** e **medida**: ela começa, termina, e o que fica registrado é quanto tempo levou. É a resposta para "quanto demora minha rotina de emissão?" — e, quando você adiciona [spans](#span), para "onde foram esses minutos?".
 
-Enquanto o [evento](#evento) responde _o que quebrou_, a transaction responde _quanto tempo levou_. São os dois eixos do Monitor.
+Enquanto o [evento](#evento) responde _o que quebrou_, a transaction responde _quanto tempo levou_. São os dois eixos da telemetria.
 
 ```js
 const tx = Hobots.startTransaction('processar-lote', 'rpa.job');
@@ -226,7 +239,7 @@ Três coisas que valem saber:
 
 O `status` default é `'ok'`; encadeáveis: `setStatus`, `setName`, `setTag`.
 
-Dentro de um handler do Manager você **não** cria transaction — já existe uma em [`ctx.tx`](#transaction-de-run-ctxtx).
+Dentro de um handler de task você **não** cria transaction — já existe uma em [`ctx.tx`](#transaction-de-run-ctxtx), e o `startTransaction()` chamado lá dentro devolve exatamente ela.
 
 ## Span
 
@@ -249,7 +262,7 @@ O `op` é a categoria (útil para agrupar "todas as queries") e a `description`
 
 ## Transaction de run (ctx.tx)
 
-Dentro de um handler do Manager você **não precisa** criar uma transaction: o SDK já abriu uma para aquela execução e entregou em `ctx.tx`. Ela nasce quando o agente captura a run, é **correlacionada** à execução pelo `run_id`, recebe o status conforme o desfecho (`ok`, `error` ou `cancelled`) e é **finalizada automaticamente** quando o handler termina — você nunca chama `ctx.tx.finish()`.
+Dentro de um handler de task você **não precisa** criar uma transaction: o SDK já abriu uma para aquela execução e entregou em `ctx.tx`. Ela nasce quando o agente captura a run, é **correlacionada** à execução pelo `run_id`, recebe o status conforme o desfecho (`ok`, `error` ou `cancelled`) e é **finalizada automaticamente** quando o handler termina — você nunca chama `ctx.tx.finish()`.
 
 O que sobra para você é a parte interessante: marcar as **etapas** do trabalho com [spans](#span). Cada `startChild` vira uma barra no waterfall da aba de performance daquela execução no app.
 
@@ -270,8 +283,8 @@ Hobots.register('processar-nfe', async (params, ctx) => {
 
 Sem nenhum `startChild` a transaction ainda existe e ainda mede o tempo total da run — o waterfall só fica com uma barra. Cada span que você abre é uma resposta a mais para "onde foram os 4 minutos".
 
-- **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 para as transactions que **você** abre com `startTransaction()`.
+- **`Hobots.startTransaction()` dentro de um handler devolve a própria `ctx.tx`.** Cada execução tem exatamente **uma** transaction: o SDK detecta o contexto da run e reutiliza 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 para as transactions que **você** abre com `startTransaction()` fora de uma run.
 - O nome é `run:<task>` e o `op` é `hobots.task`, preenchidos pelo SDK.
 
 ## Amostragem (sampleRate e tracesSampleRate)
@@ -338,11 +351,13 @@ Dois detalhes:
 
 O timer do heartbeat é `unref`'d — ele **não** segura o processo vivo.
 
+Com `tasks: true`, o heartbeat é **opcional**: o próprio poll de tasks já marca a presença do agente no painel. Ele continua essencial para agentes só de telemetria.
+
 ## instanceId
 
 O **`instanceId`** é a identidade da instância do robô: qual VM, qual container, qual máquina. É **obrigatório** no `init()` e deve ser **estável entre reinícios** (`vm-cliente-01`, `container-nfe-3`) — se você gerar um valor novo a cada boot, o app vê uma frota de robôs fantasmas em vez de um robô que reiniciou.
 
-O que o torna especial é que ele é a identidade dos **dois** canais ao mesmo tempo: o [heartbeat](#heartbeat) do Monitor e o agente do [Manager](./manager.md) enviam o mesmo `instanceId`. O servidor correlaciona os dois, e o robô aparece como **um agente só** no painel — sem nenhuma configuração extra.
+O que o torna especial é que ele é a identidade dos **dois** canais ao mesmo tempo: o [heartbeat](#heartbeat) e o agente de [tasks](./tasks.md) enviam o mesmo `instanceId`. O servidor correlaciona os dois, e o robô aparece como **um agente só** no módulo Agentes — sem nenhuma configuração extra.
 
 ## Release e environment
 
@@ -359,7 +374,7 @@ Servem a duas perguntas concretas:
 
 Uma **run** (execução) é um pedido concreto de trabalho criado no app: alguém preencheu o formulário da task, ou uma automação disparou, e agora existe uma solicitação esperando um agente pegar.
 
-É a unidade em volta da qual o [Manager](./manager.md) inteiro gira. O ciclo de vida no servidor:
+É a unidade em volta da qual as [tasks](./tasks.md) inteiras giram — no app, cada run é uma solicitação no módulo **Solicitações**. O ciclo de vida no servidor:
 
 ```
 pending → claimed → running → succeeded | failed | canceled
@@ -372,7 +387,7 @@ pending → claimed → running → succeeded | failed | canceled
 
 O agente só transiciona para `running`, `succeeded` e `failed`. `pending` e `claimed` são do servidor; `canceled` vem de alguém cancelando no app.
 
-Cada run carrega os **`params`** (o JSON validado do formulário) e chega ao seu código como o primeiro argumento do handler, junto de um [`RunContext`](./api-reference.md#managertaskhandler--runcontext) com logs, sinal de cancelamento e a [transaction](#transaction-de-run-ctxtx).
+Cada run carrega os **`params`** (o JSON validado do formulário) e chega ao seu código como o primeiro argumento do handler, junto de um [`RunContext`](./api-reference.md#taskhandler--runcontext) com logs, sinal de cancelamento e a [transaction](#transaction-de-run-ctxtx).
 
 ## Claim
 
@@ -406,13 +421,13 @@ Devolve `true` se tudo saiu dentro do tempo e `false` se estourou. `false` **nã
 
 ### `close(timeoutMs?)` — "acabou, encerra"
 
-Encerra tudo, **nesta ordem**: para o agente do Manager (aguardando as runs em execução) → para o heartbeat → faz o flush final e fecha o transport. É sempre a última linha do seu programa.
+Encerra tudo, **nesta ordem**: para o agente de tasks (aguardando as runs em execução) → para o heartbeat → faz o flush final e fecha o transport. É sempre a última linha do seu programa.
 
 > **Atenção:** `close()` é **terminal e sem volta**. Depois dele, todo `captureException`, transaction, check-in ou heartbeat é **descartado** com um 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()` é aplicado **duas vezes, em sequência** — uma para esperar as runs do Manager, outra para o flush final. `close(15_000)` pode levar até ~30s no pior caso. Se você tem um SIGTERM com prazo curto (Kubernetes, systemd), dimensione por aí.
+> **Atenção:** o `timeoutMs` do `close()` é aplicado **duas vezes, em sequência** — uma para esperar as runs de tasks, outra para o flush final. `close(15_000)` pode levar até ~30s no pior caso. Se você tem um SIGTERM com prazo curto (Kubernetes, systemd), dimensione por aí.
 
-O `flush` cobre a fila do **Monitor**. Os logs de uma run do Manager (`ctx.log`) são um canal separado, com o próprio ritmo — quem espera por eles é o `close()`/`stop()`, ao aguardar a run terminar.
+O `flush` cobre a fila da **telemetria**. Os logs de uma run de task (`ctx.log`) são um canal separado, com o próprio ritmo — quem espera por eles é o `close()`/`stop()`, ao aguardar a run terminar.
 
 Defaults e tempos dos dois: [Tempos e intervalos](./api-reference.md#tempos-e-intervalos).