hobots 1.7.5 → 1.8.0

package/dist/protocol.d.cts

@@ -125,18 +125,18 @@ interface EventPayload {
     release?: string;
     environment?: string;
 }
-/** Status de um span (etapa). `warning` = terminou, mas merece atenção (não é falha). */
-type SpanStatus = 'ok' | 'warning' | 'error' | 'cancelled';
-interface SpanData {
+/** Status de uma step (etapa). `warning` = terminou, mas merece atenção (não é falha). */
+type StepStatus = 'ok' | 'warning' | 'error' | 'cancelled';
+interface StepData {
     /** 16 hex */
-    span_id: string;
-    parent_span_id?: string;
+    step_id: string;
+    parent_step_id?: string;
     op?: string;
     description?: string;
-    status?: SpanStatus;
+    status?: StepStatus;
     /** ISO 8601 */
     start_timestamp: string;
-    /** ISO 8601 (fim do span) */
+    /** ISO 8601 (fim da step) */
     timestamp: string;
     data?: Record<string, unknown>;
 }
@@ -147,26 +147,13 @@ interface TransactionPayload {
     status: string;
     start_timestamp: string;
     timestamp: string;
-    spans: SpanData[];
+    steps: StepData[];
     tags?: Record<string, string>;
     release?: string;
     environment?: string;
     /** 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';
-interface CheckInPayload {
-    /** Mesmo id no par in_progress → ok/error para casar início e fim */
-    check_in_id: string;
-    monitor_slug: string;
-    status: CheckInStatus;
-    duration_ms?: number;
-    /** Expressão cron — permite o servidor criar o monitor automaticamente (upsert) */
-    schedule?: string;
-    timezone?: string;
-    environment?: string;
-    release?: string;
-}
 interface HeartbeatPayload {
     instance_id: string;
     name?: string;
@@ -182,9 +169,6 @@ type EnvelopeItem = {
 } | {
     type: 'transaction';
     payload: TransactionPayload;
-} | {
-    type: 'check_in';
-    payload: CheckInPayload;
 } | {
     type: 'heartbeat';
     payload: HeartbeatPayload;
@@ -199,4 +183,4 @@ interface Envelope {
     items: EnvelopeItem[];
 }
 
-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 };
+export type { AgentInfo, Breadcrumb, Envelope, EnvelopeItem, EventPayload, EventUser, ExceptionData, HeartbeatPayload, PollRequest, PollResponse, RunDescriptor, RunError, RunLogEntry, RunLogLevel, RunStatus, RunUpdateRequest, RunUpdateResponse, RunUpdateStatus, Severity, StackFrame, StepData, StepStatus, TransactionPayload };

package/dist/protocol.d.ts

@@ -125,18 +125,18 @@ interface EventPayload {
     release?: string;
     environment?: string;
 }
-/** Status de um span (etapa). `warning` = terminou, mas merece atenção (não é falha). */
-type SpanStatus = 'ok' | 'warning' | 'error' | 'cancelled';
-interface SpanData {
+/** Status de uma step (etapa). `warning` = terminou, mas merece atenção (não é falha). */
+type StepStatus = 'ok' | 'warning' | 'error' | 'cancelled';
+interface StepData {
     /** 16 hex */
-    span_id: string;
-    parent_span_id?: string;
+    step_id: string;
+    parent_step_id?: string;
     op?: string;
     description?: string;
-    status?: SpanStatus;
+    status?: StepStatus;
     /** ISO 8601 */
     start_timestamp: string;
-    /** ISO 8601 (fim do span) */
+    /** ISO 8601 (fim da step) */
     timestamp: string;
     data?: Record<string, unknown>;
 }
@@ -147,26 +147,13 @@ interface TransactionPayload {
     status: string;
     start_timestamp: string;
     timestamp: string;
-    spans: SpanData[];
+    steps: StepData[];
     tags?: Record<string, string>;
     release?: string;
     environment?: string;
     /** 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';
-interface CheckInPayload {
-    /** Mesmo id no par in_progress → ok/error para casar início e fim */
-    check_in_id: string;
-    monitor_slug: string;
-    status: CheckInStatus;
-    duration_ms?: number;
-    /** Expressão cron — permite o servidor criar o monitor automaticamente (upsert) */
-    schedule?: string;
-    timezone?: string;
-    environment?: string;
-    release?: string;
-}
 interface HeartbeatPayload {
     instance_id: string;
     name?: string;
@@ -182,9 +169,6 @@ type EnvelopeItem = {
 } | {
     type: 'transaction';
     payload: TransactionPayload;
-} | {
-    type: 'check_in';
-    payload: CheckInPayload;
 } | {
     type: 'heartbeat';
     payload: HeartbeatPayload;
@@ -199,4 +183,4 @@ interface Envelope {
     items: EnvelopeItem[];
 }
 
-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 };
+export type { AgentInfo, Breadcrumb, Envelope, EnvelopeItem, EventPayload, EventUser, ExceptionData, HeartbeatPayload, PollRequest, PollResponse, RunDescriptor, RunError, RunLogEntry, RunLogLevel, RunStatus, RunUpdateRequest, RunUpdateResponse, RunUpdateStatus, Severity, StackFrame, StepData, StepStatus, TransactionPayload };

package/docs/README.md

@@ -1,21 +1,21 @@
 # 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+ (a telemetria também roda no browser para captura de erros).
+SDK JavaScript da **Hobots** para instrumentar agentes (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 agente**, configuradas em **um único `init()`** com **um único import** (`import * as Hobots from 'hobots'`):
 
 | Capability | Como habilita | Para quê |
 | --- | --- | --- |
-| **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. |
+| **Telemetria** | sempre ativa no `init()` | O que o programa **emite** sozinho: erros com stack trace (módulo **Issues**), performance (transactions/etapas) e heartbeats de uptime (módulo **Agentes**). 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.
+Se termos como transaction, step, 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, telemetria e tasks.
-- [Telemetria](./monitor.md) — erros, breadcrumbs, escopo, transactions/spans, crons e heartbeat.
+- [Telemetria](./telemetry.md) — erros, breadcrumbs, escopo, transactions/etapas 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.

package/docs/api-reference.md

@@ -4,7 +4,7 @@
 
 | Import | Conteúdo |
 | --- | --- |
-| `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` | Tudo: `init` único, funções de telemetria, `register`/`start`/`stop` de tasks, `close`, classes (`Client`, `Scope`, `Transaction`, `Step`), `DEFAULT_BASE_URL`, `scrubSecrets` e tipos. |
 | `hobots/protocol` | Tipos do wire format (telemetria e tasks). |
 
 ---
@@ -24,8 +24,6 @@
 | `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 (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 polling de tasks (aguarda runs) + heartbeat + flush final do transport |
 
@@ -45,12 +43,10 @@ Os conceitos por trás dessas chamadas estão em [Conceitos](./concepts.md); aqu
 - **`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 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`. 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`:
+Classes exportadas: `Client`, `Scope`, `Transaction`, `Step`. 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
 getClient()?.config; // {
@@ -61,12 +57,12 @@ getClient()?.config; // {
 // }
 ```
 
-### Métodos de `Transaction` / `Span` / `Scope`
+### Métodos de `Transaction` / `Step` / `Scope`
 
 Todos encadeáveis, exceto `finish()` e `toJSON()`.
 
-- **`Transaction`** — `startChild(op?, description?) → Span` abre um [span](./concepts.md#span) direto; `setTag(k, v)` marca a transaction (tags de scope **não** são herdadas); `setStatus(s)` (default `'ok'`); `setName(n)` renomeia antes do envio; `finish()` fecha os spans abertos, monta o payload e envia — é **idempotente** e não envia nada se a transaction não foi amostrada.
-- **`Span`** — `startChild(op?, description?) → Span` aninha um filho (profundidade arbitrária); `setStatus(s)` (default `'ok'`); `setData(k, v)` anexa dados só àquele span; `finish()` marca o fim — **opcional**, porque o `finish()` da transaction fecha o que ficou aberto; `toJSON()` serializa no formato do wire.
+- **`Transaction`** — `startChild(op?, description?) → Step` abre uma [step](./concepts.md#step) direta; `setTag(k, v)` marca a transaction (tags de scope **não** são herdadas); `setStatus(s)` (default `'ok'`); `setName(n)` renomeia antes do envio; `finish()` fecha as etapas abertas, monta o payload e envia — é **idempotente** e não envia nada se a transaction não foi amostrada.
+- **`Step`** — `startChild(op?, description?) → Step` aninha uma filha (profundidade arbitrária); `setStatus(s)` (default `'ok'`); `setData(k, v)` anexa dados só àquela step; `finish()` marca o fim — **opcional**, porque o `finish()` da transaction fecha o que ficou aberto; `toJSON()` serializa no formato do wire.
 - **`Scope`** — `setTag`/`setTags`/`setUser`/`setContext`/`setExtra`/`setExtras`/`setLevel`/`setFingerprint`/`addBreadcrumb`/`clearBreadcrumbs`/`clone`. Alcançável via [`withScope`](./concepts.md#withscope). `setContext(name, null)` apaga o grupo; `setUser(null)` remove o usuário.
   > **Atenção:** `setLevel` **não tem efeito** em `captureException` (que já grava `error`) nem em `captureMessage` (que já grava `info`) — os dois definem o level do evento antes de o scope ser consultado. Use o `hint`.
 
@@ -135,24 +131,6 @@ O teto da fila do transport (200 itens; ao encher, o **mais antigo** é descarta
 
 `Severity = 'fatal' | 'error' | 'warning' | 'info' | 'debug' | 'success'`. O que cada nível significa (e por que `'success'` existe) em [Level](./concepts.md#level-severity).
 
-### CheckInOptions
-
-| Campo | Tipo | Descrição |
-| --- | --- | --- |
-| `monitorSlug` | `string` | **obrigatório**; identifica o monitor |
-| `status` | `'in_progress' \| 'ok' \| 'error'` | **obrigatório** |
-| `checkInId` | `string` | reutilize o id do `in_progress` para fechar a execução |
-| `durationMs` | `number` | duração medida |
-| `schedule` | `string` | expressão cron — cria/atualiza o monitor no servidor (upsert) |
-| `timezone` | `string` | fuso do `schedule` |
-
-### WithMonitorOptions
-
-| Campo | Tipo | Descrição |
-| --- | --- | --- |
-| `schedule` | `string` | expressão cron (upsert do monitor) |
-| `timezone` | `string` | fuso do `schedule` |
-
 ### TasksOptions
 
 Valor do campo `tasks` do `InitOptions`. O Client Secret, o `debug` e a identidade (`instanceId`) vêm do `init()`.

package/docs/concepts.md

@@ -1,6 +1,6 @@
 # Conceitos
 
-Esta página explica **o que cada coisa é** — o vocabulário que as outras páginas usam sem parar: evento, scope, tag, context, extra, breadcrumb, transaction, span, check-in, heartbeat, run, claim, flush, close. As outras páginas mostram **como usar**; aqui está o **por que existe** e **quando você escolhe um em vez do outro**.
+Esta página explica **o que cada coisa é** — o vocabulário que as outras páginas usam sem parar: evento, scope, tag, context, extra, breadcrumb, transaction, step, heartbeat, run, claim, flush, close. As outras páginas mostram **como usar**; aqui está o **por que existe** e **quando você escolhe um em vez do outro**.
 
 Não é preciso ler de ponta a ponta. Se você só quer o mapa, o quadro abaixo resolve; se um termo apareceu numa página e você travou, pule direto para a seção dele.
 
@@ -20,10 +20,9 @@ Os defaults numéricos **não** estão aqui — eles vivem em [Tempos e interval
 | [Extra](#extra)                                         | Depósito livre, sem estrutura                            | Não é filtro nem grupo coerente — é anexo                   |
 | [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                        |
+| [Step](#step)                                           | 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 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 |
@@ -41,11 +40,10 @@ Cada API do SDK alimenta um módulo do app da Hobots (app.hobots.app). O mapa:
 
 | No SDK | No app |
 | --- | --- |
-| **Agente** — o "funcionário digital"; dono do Client Secret (`hb_…`) que autentica tudo | **Configurações → Agentes** (é lá que você copia a credencial) |
+| **Agente** — dono do Client Secret (`hb_…`) que autentica tudo | **Configurações → Agentes** (é lá que você copia a credencial) |
 | **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 |
+| **[Transaction](#transaction) / etapas** — `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**) |
 
 ---
@@ -153,7 +151,7 @@ Tags podem vir de quatro lugares, e em caso de conflito a última vence:
 
 Ou seja: uma tag no `hint` sobrescreve a mesma tag do scope, que sobrescreve a do `init()`. Use o `init()` para o que é verdade em todo o processo (squad, ambiente), o scope para o que é verdade num trecho, e o `hint` para o que é verdade só naquele evento.
 
-> **Atenção:** tags do scope entram em **eventos**, não em [transactions](#transaction). Uma transaction só leva as tags do `init()` mais as que você marcar nela com `tx.setTag()`. [Check-ins](#check-in) e [heartbeats](#heartbeat) não levam tag nenhuma.
+> **Atenção:** tags do scope entram em **eventos**, não em [transactions](#transaction). Uma transaction só leva as tags do `init()` mais as que você marcar nela com `tx.setTag()`. [Heartbeats](#heartbeat) não levam tag nenhuma.
 
 ## Context
 
@@ -218,7 +216,7 @@ Tamanho do buffer: [`maxBreadcrumbs`](./api-reference.md#initoptions).
 
 ## Transaction
 
-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?".
+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 [etapas](#step), para "onde foram esses minutos?".
 
 Enquanto o [evento](#evento) responde _o que quebrou_, a transaction responde _quanto tempo levou_. São os dois eixos da telemetria.
 
@@ -234,37 +232,37 @@ O primeiro argumento é o **nome** (o que agrupa transactions comparáveis no ap
 Três coisas que valem saber:
 
 - **Nada é enviado até o `finish()`.** A transaction vive em memória; o `finish()` é que monta o payload e enfileira. Se o processo morrer antes, ela simplesmente não existe.
-- **`finish()` é idempotente e fecha o resto.** Chamar duas vezes não envia duas; e ele **finaliza automaticamente** todos os spans que ficaram abertos.
+- **`finish()` é idempotente e fecha o resto.** Chamar duas vezes não envia duas; e ele **finaliza automaticamente** todas as etapas que ficaram abertas.
 - **A [amostragem](#amostragem-samplerate-e-tracessamplerate) é decidida no `startTransaction()`**, não no `finish()`. Se aquela transaction não foi sorteada, o `finish()` não envia nada — mas os `startChild` continuam funcionando normalmente e não custam quase nada.
 
 O `status` default é `'ok'`; encadeáveis: `setStatus`, `setName`, `setTag`.
 
 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
+## Step
 
-Um **span** é uma etapa medida **dentro** de uma [transaction](#transaction). A transaction diz que a rotina levou 4 minutos; os spans dizem que 3min40 foram esperando o portal.
+Uma **step** (etapa) é medida **dentro** de uma [transaction](#transaction). A transaction diz que a rotina levou 4 minutos; as etapas dizem que 3min40 foram esperando o portal.
 
 ```js
-const span = tx.startChild('http.client', 'GET /api/notas');
+const step = tx.startChild('http.client', 'GET /api/notas');
 await api.buscarNotas();
-span.setData('notas', 42).finish();
+step.setData('notas', 42).finish();
 ```
 
-`startChild(op?, description?)` existe **tanto na transaction quanto no span**, então você aninha quanto quiser — um span de "processar nota" com filhos de "baixar XML" e "gravar no banco". No app isso vira o **waterfall**: barras encaixadas, cada uma com sua duração.
+`startChild(op?, description?)` existe **tanto na transaction quanto na step**, então você aninha quanto quiser — uma step de "processar nota" com filhas de "baixar XML" e "gravar no banco". No app isso vira o **waterfall**: barras encaixadas, cada uma com sua duração.
 
-O `op` é a categoria (útil para agrupar "todas as queries") e a `description` é o detalhe humano ("`INSERT INTO notas`"). `setData(chave, valor)` anexa dados àquele span específico — contagens, tamanhos, ids.
+O `op` é a categoria (útil para agrupar "todas as queries") e a `description` é o detalhe humano ("`INSERT INTO notas`"). `setData(chave, valor)` anexa dados àquela step específica — contagens, tamanhos, ids.
 
 - Métodos encadeáveis: `setStatus`, `setData`, `finish`.
-- **Status do span:** `'ok'` (default), `'warning'` (terminou, mas merece atenção — não é falha) ou `'error'` (falhou). No waterfall do app cada um tem sua cor: verde/neutro, âmbar e vermelho. Use `span.setStatus('warning')` para etapas que passaram com ressalva (ex.: retry que deu certo, resultado parcial).
-- Esquecer o `finish()` de um span **não perde o dado**: o `finish()` da transaction fecha os spans abertos, marcando o fim naquele instante.
-- Os spans são guardados numa lista plana ligada por `parent_span_id` — o aninhamento que você vê no app é reconstruído a partir dessas referências, não da ordem das chamadas.
+- **Status da step:** `'ok'` (default), `'warning'` (terminou, mas merece atenção — não é falha) ou `'error'` (falhou). No waterfall do app cada um tem sua cor: verde/neutro, âmbar e vermelho. Use `step.setStatus('warning')` para etapas que passaram com ressalva (ex.: retry que deu certo, resultado parcial).
+- Esquecer o `finish()` de uma step **não perde o dado**: o `finish()` da transaction fecha as etapas abertas, marcando o fim naquele instante.
+- As etapas são guardadas numa lista plana ligada por `parent_step_id` — o aninhamento que você vê no app é reconstruído a partir dessas referências, não da ordem das chamadas.
 
 ## Transaction de run (ctx.tx)
 
 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.
+O que sobra para você é a parte interessante: marcar as **etapas** do trabalho com [steps](#step). Cada `startChild` vira uma barra no waterfall da aba de performance daquela execução no app.
 
 ```js
 Hobots.register('processar-nfe', async (params, ctx) => {
@@ -273,17 +271,17 @@ Hobots.register('processar-nfe', async (params, ctx) => {
   login.finish();
 
   for (const nota of params.notas) {
-    const span = ctx.tx.startChild('nfe', `nota ${nota.numero}`);
+    const step = ctx.tx.startChild('nfe', `nota ${nota.numero}`);
     ctx.throwIfCanceled();
     await processar(nota);
-    span.setData('valor', nota.valor).finish();
+    step.setData('valor', nota.valor).finish();
   }
 });
 ```
 
-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".
+Sem nenhum `startChild` a transaction ainda existe e ainda mede o tempo total da run — o waterfall só fica com uma barra. Cada step que você abre é uma resposta a mais para "onde foram os 4 minutos".
 
-- **`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`.
+- **`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 — as etapas 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.
 
@@ -300,39 +298,17 @@ São dois controles independentes, os dois de `0` a `1`:
 
 O sorteio é por item, no momento em que ele é criado — nunca "1 a cada 10", e sim 10% de chance cada.
 
-Quem **nunca** é amostrado: [check-ins](#check-in), [heartbeats](#heartbeat) e a [transaction de run](#transaction-de-run-ctxtx) (`ctx.tx`). São sinais de vida e de agendamento — amostrar transformaria "o robô está offline" num palpite.
+Quem **nunca** é amostrado: [heartbeats](#heartbeat) e a [transaction de run](#transaction-de-run-ctxtx) (`ctx.tx`). São sinais de vida — amostrar transformaria "o robô está offline" num palpite.
 
 > **Atenção:** para erros, comece com `sampleRate` em 1 (o default) e só reduza se o volume virar problema de verdade. Amostrar erro significa não ver a falha que aconteceu três vezes — e três vezes é exatamente onde você ainda consegue agir. Para transactions o cálculo é o oposto: reduzir é quase sempre seguro.
 
 Nos dois casos, o descarte é silencioso do ponto de vista do seu código: `captureException` ainda devolve um `event_id`. Veja a ressalva em [Evento](#evento).
 
-## Check-in
-
-Um **check-in** é um aviso de que um job agendado começou ou terminou. Dois check-ins com o **mesmo id** formam um par: `in_progress` na entrada, `ok` ou `error` na saída — e a diferença entre eles é a duração medida.
-
-Isso responde a uma pergunta que erro e performance não respondem: **"o cron rodou?"**. Um robô que nunca executa nunca lança exceção — o silêncio é o sintoma, e check-in é como o silêncio fica visível.
-
-O jeito recomendado é `withMonitor`, que faz o par sozinho e captura a exceção se houver:
-
-```js
-await Hobots.withMonitor('sync-notas', () => executarSync(), {
-  schedule: '0 */2 * * *',
-  timezone: 'America/Fortaleza',
-});
-```
-
-O **`schedule`** (expressão cron) é o campo que muda o jogo: com ele, o servidor **cria ou atualiza o monitor automaticamente** (upsert — você não precisa cadastrar nada no app) e passa a saber quando a próxima execução era esperada. É isso que habilita a detecção de **execução perdida**: se as 4h da manhã passaram e nenhum `in_progress` chegou, o app avisa.
-
-Detalhes que importam:
-
-- `withMonitor` **relança** a exceção depois de fechar o check-in como `error` e capturar o evento (com a tag `monitor: <slug>`) — o seu `try/catch` em volta continua funcionando igual.
-- Precisa de controle manual (o par não está no mesmo lugar do código)? Use `checkIn` direto e reaproveite o `checkInId` devolvido pelo `in_progress` para fechar a execução.
-
 ## Heartbeat
 
 O **heartbeat** é um batimento periódico dizendo "estou vivo". O servidor conhece a cadência esperada e marca a instância como **offline** quando os batimentos param.
 
-É o complemento do [check-in](#check-in): check-in vigia _execuções agendadas_, heartbeat vigia _o processo_. Um robô que fica de plantão esperando trabalho não tem cron para monitorar — mas você ainda quer saber quando a VM dele caiu.
+Isso responde a uma pergunta que erro e performance não respondem: **"o robô está de pé?"**. Um robô que fica de plantão esperando trabalho pode passar horas sem lançar exceção — o silêncio é o sintoma, e heartbeat é como o silêncio fica visível.
 
 ```js
 Hobots.init({
@@ -361,7 +337,7 @@ O que o torna especial é que ele é a identidade dos **dois** canais ao mesmo t
 
 ## Release e environment
 
-**`release`** é a versão do seu programa (`robo-nfe@1.4.2`) e **`environment`** é o ambiente lógico (`production`, `homologacao`). Os dois são anexados a **todo** item enviado: eventos, transactions e check-ins.
+**`release`** é a versão do seu programa (`robo-nfe@1.4.2`) e **`environment`** é o ambiente lógico (`production`, `homologacao`). Os dois são anexados a **todo** item enviado: eventos e transactions.
 
 Servem a duas perguntas concretas:
 
@@ -409,7 +385,7 @@ Isso também explica por que o intervalo de poll não é a latência típica: el
 
 ## Fila, flush e close
 
-O SDK **não** envia um HTTP por evento. Cada `captureException`, transaction, check-in e heartbeat entra numa **fila em memória**; um timer junta os itens num **envelope** e faz um POST só. É isso que faz a telemetria custar quase nada no caminho crítico do seu robô — e é isso que cria o problema que `flush` e `close` resolvem: **quando o processo morre, a fila morre com ele.**
+O SDK **não** envia um HTTP por evento. Cada `captureException`, transaction e heartbeat entra numa **fila em memória**; um timer junta os itens num **envelope** e faz um POST só. É isso que faz a telemetria custar quase nada no caminho crítico do seu robô — e é isso que cria o problema que `flush` e `close` resolvem: **quando o processo morre, a fila morre com ele.**
 
 A fila esvazia sozinha em três situações: passou o `flushIntervalMs`, acumulou `maxBatchSize` itens, ou você pediu.
 
@@ -423,7 +399,7 @@ Devolve `true` se tudo saiu dentro do tempo e `false` se estourou. `false` **nã
 
 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:** `close()` é **terminal e sem volta**. Depois dele, todo `captureException`, transaction 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 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í.
 
@@ -453,4 +429,4 @@ Onde ele entra na ordem das coisas: a [amostragem](#amostragem-samplerate-e-trac
 
 > **Atenção:** `beforeSend` roda no caminho da captura, de forma síncrona. Mantenha a função rápida e sem I/O — e cuidado para não lançar exceção dentro dela.
 
-Vale só para eventos. Transactions, check-ins e heartbeats não passam pelo `beforeSend`.
+Vale só para eventos. Transactions e heartbeats não passam pelo `beforeSend`.

package/docs/getting-started.md

@@ -71,7 +71,7 @@ try {
 }
 ```
 
-Chame `Hobots.init` **uma vez**, o mais cedo possível no processo. Detalhes em [Telemetria](./monitor.md).
+Chame `Hobots.init` **uma vez**, o mais cedo possível no processo. Detalhes em [Telemetria](./telemetry.md).
 
 ## Primeiro agente (tasks)
 

package/docs/protocol.md

@@ -30,13 +30,12 @@ Endpoint fixo `POST /v1/ingest` recebe **envelopes** JSON autenticados por Beare
   "items": [
     { "type": "event",       "payload": { /* EventPayload */ } },
     { "type": "transaction", "payload": { /* TransactionPayload */ } },
-    { "type": "check_in",    "payload": { /* CheckInPayload */ } },
     { "type": "heartbeat",   "payload": { /* HeartbeatPayload */ } }
   ]
 }
 ```
 
-Tipos de item: `event`, `transaction`, `check_in`, `heartbeat` (definidos em `hobots/protocol`).
+Tipos de item: `event`, `transaction`, `heartbeat` (definidos em `hobots/protocol`).
 
 Um `transaction` pode carregar `run_id`: é assim que a [transaction de uma run](./concepts.md#transaction-de-run-ctxtx) (`ctx.tx`) é correlacionada à execução, e o que permite o app montar o waterfall de performance dentro da solicitação. Transactions abertas com `startTransaction()` fora de uma run não têm esse campo.
 

package/docs/tasks.md

@@ -79,20 +79,20 @@ Hobots.register('processar-nfe', async (params, ctx) => {
   login.finish();
 
   for (const nota of params.notas) {
-    const span = ctx.tx.startChild('nfe', `nota ${nota.numero}`);
+    const step = ctx.tx.startChild('nfe', `nota ${nota.numero}`);
     ctx.throwIfCanceled();
     await processar(nota);
-    span.setData('valor', nota.valor).finish();
+    step.setData('valor', nota.valor).finish();
   }
 });
 ```
 
-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.
+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 nenhuma step, a transaction ainda mede o tempo total da run; o waterfall só fica com uma barra.
 
-- **`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`.
+- **`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 — as etapas 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'`).
+- Step que você esquecer aberta é fechada no `finish()` da transaction, então o dado não se perde.
+- Marque etapas com ressalva usando `step.setStatus('warning')` (ex.: retry que deu certo, resultado parcial): elas aparecem em âmbar no waterfall, distintas de sucesso e de falha (`'error'`).
 
 ## Cancelamento cooperativo
 

package/docs/{monitor.md → telemetry.md}

@@ -1,6 +1,6 @@
 # Telemetria
 
-Capability de telemetria: erros (módulo **Issues**), performance e uptime (módulo **Agentes**), crons (módulo **Monitores**). Sempre ativa no `init()` único:
+Capability de telemetria: erros (módulo **Issues**), performance e uptime (módulo **Agentes**). Sempre ativa no `init()` único:
 
 ```js
 import * as Hobots from 'hobots';
@@ -88,18 +88,18 @@ Hobots.withScope((scope) => {
 
 > **Atenção:** `withScope` é **síncrono** — ele troca o scope global e restaura no fim do callback. Se você der `await` lá dentro, o scope isolado vale para qualquer código que capturar eventos enquanto aquele `await` está pendente. Em código concorrente (várias runs em paralelo), passe as tags no `hint`: `captureException(error, { tags: { lote: '128' } })`. Conceito: [withScope](./concepts.md#withscope).
 
-## Performance: transactions e spans
+## Performance: transactions e etapas
 
-Uma **transaction** é uma unidade de trabalho nomeada e medida ("quanto minha rotina demorou"); os **spans** são as etapas dentro dela ("onde o tempo foi gasto"). Conceitos: [Transaction](./concepts.md#transaction) · [Span](./concepts.md#span).
+Uma **transaction** é uma unidade de trabalho nomeada e medida ("quanto minha rotina demorou"); as **etapas** são as unidades dentro dela ("onde o tempo foi gasto"). Conceitos: [Transaction](./concepts.md#transaction) · [Step](./concepts.md#step).
 
 ```js
 const tx = Hobots.startTransaction('processar-lote', 'rpa.job');
 
-const span = tx.startChild('http.client', 'GET /api/notas');
+const step = tx.startChild('http.client', 'GET /api/notas');
 await api.buscarNotas();
-span.setData('notas', 42).finish();
+step.setData('notas', 42).finish();
 
-const filho = span.startChild('db.query', 'INSERT INTO notas'); // spans aninham
+const filho = step.startChild('db.query', 'INSERT INTO notas'); // etapas aninham
 await gravar();
 filho.finish();
 
@@ -107,37 +107,15 @@ tx.setStatus('ok'); // ou 'error'
 tx.finish(); // só aqui a transaction é enviada (respeitando tracesSampleRate)
 ```
 
-- `startChild(op?, description?)` existe tanto em `Transaction` quanto em `Span` (aninhamento arbitrário).
-- Métodos encadeáveis: `setStatus`, `setData` (span), `setTag`/`setName` (transaction).
-- Status de span: `'ok'` (default), `'warning'` (atenção, não é falha) ou `'error'` — cores distintas no waterfall.
-- `finish()` na transaction fecha spans abertos e envia o payload; nada é enviado se ela não foi amostrada. É **idempotente** — chamar duas vezes não envia duas.
-- 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.
+- `startChild(op?, description?)` existe tanto em `Transaction` quanto em `Step` (aninhamento arbitrário).
+- Métodos encadeáveis: `setStatus`, `setData` (step), `setTag`/`setName` (transaction).
+- Status de step: `'ok'` (default), `'warning'` (atenção, não é falha) ou `'error'` — cores distintas no waterfall.
+- `finish()` na transaction fecha etapas abertas e envia o payload; nada é enviado se ela não foi amostrada. É **idempotente** — chamar duas vezes não envia duas.
+- A decisão de amostragem acontece no **`startTransaction()`**, não no `finish()`. Esquecer o `finish()` de uma step não perde o dado: ela é fechada 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 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 — 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(
-  'sync-notas',
-  () => executarSync(),
-  { schedule: '0 */2 * * *', timezone: 'America/Fortaleza' }
-);
-```
-
-O `schedule` (expressão cron) faz o servidor **criar/atualizar o monitor automaticamente** (upsert) e habilita a detecção de **execução perdida**. Para controle manual, use `checkIn` diretamente (veja [Referência](./api-reference.md#checkinoptions)):
-
-```js
-const id = Hobots.checkIn({ monitorSlug: 'sync-notas', status: 'in_progress' });
-// … trabalho …
-Hobots.checkIn({ monitorSlug: 'sync-notas', status: 'ok', checkInId: id, durationMs: 1234 });
-```
-
-`withMonitor` **relança** a exceção depois de fechar o check-in como `error` e capturar o evento (com a tag `monitor: <slug>`) — o seu `try/catch` em volta continua funcionando igual. Conceito: [Check-in](./concepts.md#check-in).
-
 ## Heartbeat (uptime)
 
 Bate "estou vivo" periodicamente; o servidor acusa o robô **offline** quando os batimentos param.
@@ -157,7 +135,7 @@ Essa identidade é a mesma que o poll de tasks envia (`agent.instance_id`) — o
 
 ## Flush e close
 
-Nada é enviado na hora: cada evento, transaction, check-in e heartbeat entra numa **fila em memória** e sai em lote. É por isso que essas duas funções existem — quando o processo morre, a fila morre com ele. Conceito: [Fila, flush e close](./concepts.md#fila-flush-e-close).
+Nada é enviado na hora: cada evento, transaction e heartbeat entra numa **fila em memória** e sai em lote. É por isso que essas duas funções existem — quando o processo morre, a fila morre com ele. Conceito: [Fila, flush e close](./concepts.md#fila-flush-e-close).
 
 ```js
 await Hobots.flush(2000); // envia o que está em buffer, mantém o SDK vivo
@@ -168,6 +146,6 @@ O `timeoutMs` é opcional nas duas — o default é 5s (veja [Tempos e intervalo
 
 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:** `close()` é **terminal**. Depois dele, todo evento, transaction 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 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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "hobots",
-  "version": "1.7.5",
-  "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().",
+  "version": "1.8.0",
+  "description": "SDK JavaScript da Hobots — telemetria (erros, transactions 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",