hobots 1.5.1 → 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,14 +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/manager/protocol` segue existindo como alias transitório dos tipos do wire format do 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 |
 | --- | --- | --- |
@@ -25,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.
@@ -46,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`
@@ -74,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.
 
 ---
 
@@ -105,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 |
@@ -157,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 |
 | --- | --- | --- | --- |
@@ -170,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
@@ -189,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.
@@ -201,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 |
 | --- | --- | --- | --- |
@@ -213,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.