hobots 1.3.5 → 1.3.6

package/README.md

@@ -49,7 +49,7 @@ Hobots.init({
 
 Hobots.register('processar-nfe', async (params, ctx) => {
   ctx.log.info('começando…');
-  return { processadas: 12 };
+  ctx.log.info('12 notas processadas'); // o retorno do handler é ignorado — reporte por log
 });
 
 Hobots.start(); // inicia o polling do Manager (segura o processo vivo)
@@ -135,6 +135,8 @@ Trilha do que aconteceu antes do erro; enviada junto do próximo evento (buffer
 Hobots.addBreadcrumb({ category: 'nfe', message: 'Baixou XML da nota 123', level: 'info' });
 ```
 
+A lista **não** é limpa ao enviar um evento e é global. Conceito: [Breadcrumb](./docs/concepts.md#breadcrumb).
+
 ### Escopo: tags, usuário, contexto, extras
 
 Dados anexados a **todos** os eventos seguintes:
@@ -175,7 +177,9 @@ tx.finish();         // só aqui a transaction é enviada (respeitando tracesSam
 
 - `startChild(op?, description?)` existe em `Transaction` **e** `Span` (aninhamento arbitrário).
 - Métodos encadeáveis: `setStatus`, `setData` (span), `setTag`/`setName` (transaction).
-- `finish()` na transaction fecha os spans abertos e envia o payload; nada é enviado se ela não foi amostrada.
+- `finish()` na transaction fecha os spans abertos e envia o payload; nada é enviado se ela não foi amostrada. A amostragem é decidida no `startTransaction()`.
+
+Dentro de um handler do Manager não abra transaction — já existe uma em `ctx.tx`. Conceitos: [Transaction](./docs/concepts.md#transaction) · [Span](./docs/concepts.md#span).
 
 ### Crons (check-ins)
 
@@ -208,7 +212,7 @@ Hobots.init({
 });
 ```
 
-`heartbeat: true` usa os defaults. A identidade é o `instanceId` do `init()`. Campos: `intervalMs` (30000), `name` (default: o `instanceId`), `metadata`.
+`heartbeat: true` usa os defaults. A identidade é o `instanceId` do `init()`; os campos são `intervalMs`, `name` (default: o `instanceId`) e `metadata` — valores em [Tempos e intervalos](./docs/api-reference.md#tempos-e-intervalos). O primeiro batimento sai **na hora** em que o `init()` roda, não depois do primeiro intervalo. Conceito: [Heartbeat](./docs/concepts.md#heartbeat).
 
 ### Flush e close
 
@@ -236,7 +240,7 @@ Hobots.init({
 
 Hobots.register('processar-nfe', async (params, ctx) => {
   ctx.log.info(`processando lote ${params.lote}…`);
-  if (ctx.signal.aborted) return;   // cancelamento cooperativo
+  ctx.throwIfCanceled();            // cancelamento cooperativo
   ctx.log.info('12 notas processadas');
 });
 
@@ -259,6 +263,8 @@ process.on('SIGINT', () => {
 | `concurrency` | `number` | `1` | runs simultâneas (clamp 1..5) |
 | `taskTimeoutMs` | `number` | — | timeout client-side por run (não mata o handler; servidor é o backstop) |
 | `logFlushIntervalMs` | `number` | `2000` | intervalo do envio incremental de logs |
+| `cancelCheckIntervalMs` | `number` | `5000` | heartbeat de cancelamento por run (clamp 1000..15000) — também é o sinal de vida da run |
+| `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 |
 
 O Client Secret, o `debug` e a identidade do agente (`instanceId`) vêm do `init()` — o heartbeat do Monitor e o agente do Manager convergem em **um agente** no painel automaticamente.
 
@@ -272,13 +278,19 @@ interface RunContext {
   runId: string;
   task: string;
   log(level: 'debug' | 'info' | 'warning' | 'error', message: string): void;
+  tx: Transaction; // transaction desta run — correlacionada e finalizada pelo SDK
   signal: AbortSignal;
+  throwIfCanceled(): void; // lança RunCanceled se o signal já disparou
+  sleep(ms: number): Promise<void>; // espera cancelável — rejeita com RunCanceled no abort
 }
 ```
 
 - **`params`** — os dados do formulário configurado no app (JSON validado). Tipável: `Hobots.register<{ lote: number }>(...)`.
-- **`ctx.log.<level>(message)`** — logs enviados **incrementalmente** ao app (PATCHes com throttle), visíveis na run quase em tempo real.
+- **`ctx.log.<level>(message)`** — logs enviados **incrementalmente** ao app (PATCHes com throttle), visíveis na run quase em tempo real; também impressos no terminal local, coloridos por nível.
+- **`ctx.tx`** — a transaction de performance desta run, já correlacionada e finalizada pelo SDK. Use `ctx.tx.startChild(op, description)` para medir as etapas — elas viram o waterfall da execução no app. Conceito: [ctx.tx](./docs/concepts.md#transaction-de-run-ctxtx).
 - **`ctx.signal`** — `AbortSignal` que dispara quando a run é **cancelada no app**, em **timeout** ou no **shutdown**.
+- **`ctx.throwIfCanceled()`** — o ponto de parada de uma linha; lança `RunCanceled` se o `signal` já disparou.
+- **`ctx.sleep(ms)`** — espera que respeita o `signal` (rejeita com `RunCanceled` em vez de dormir até o fim).
 - **Retorno** — **ignorado**: o SDK não captura nem envia o valor retornado pelo handler (resultados podem conter dados sensíveis e não são coletados).
 - **Erro lançado** — a run é reportada como `failed` (mensagem cap 10k, stack 20k).
 
@@ -286,20 +298,21 @@ interface RunContext {
 
 ### Cancelamento cooperativo
 
-Uma run cancelada no app **não mata** o handler — o SDK apenas dispara `ctx.signal`. **Verifique `ctx.signal.aborted`** em loops longos:
+Uma run cancelada no app **não mata** o handler — o SDK apenas dispara `ctx.signal`. Chame **`ctx.throwIfCanceled()`** em loops longos e pontos de parada (e troque esperas longas por `ctx.sleep()`):
 
 ```js
 Hobots.register('processar-nfe', async (params, ctx) => {
   for (const nota of params.notas) {
-    if (ctx.signal.aborted) {
-      ctx.log.warn('cancelamento detectado — parando');
-      return;
-    }
+    ctx.throwIfCanceled(); // lança RunCanceled se cancelada — o handler para aqui
     await processar(nota);
   }
 });
 ```
 
+Quando o cancelamento veio do app, o `RunCanceled` lançado é **suprimido** — a run já está `cancelada` no servidor e nada é reportado por cima. Para limpeza antes de parar (fechar navegador, desfazer estado), use `try/finally`.
+
+> **Atenção:** não use `if (ctx.signal.aborted) return;`. Retornar normalmente faz o SDK reportar a run como **`succeeded`** — uma run cancelada apareceria como sucesso no app. É preciso **lançar**, e é o que o `throwIfCanceled()` faz.
+
 ### Concorrência
 
 `concurrency` (default 1, máx 5) controla quantas runs o agente executa em paralelo. Com 1, as runs são sequenciais. O agente só reivindica o que consegue rodar (`max = concurrency - runs ativas`) e entra em **drain mode**: re-pesquisa imediatamente enquanto vem trabalho; quando não vem, espera `pollIntervalMs`.
@@ -308,9 +321,11 @@ Hobots.register('processar-nfe', async (params, ctx) => {
 
 `taskTimeoutMs` é **client-side**. No estouro o SDK **não mata** o handler — dispara `ctx.signal`, libera o slot e reporta a run como falha (`TaskTimeout`). Respeite o `signal` para parar de verdade. Sem ele, o backstop é o servidor.
 
-### Idempotência (at-least-once)
+### Idempotência (at-least-once até `running`)
+
+Se o agente morrer logo **após capturar** uma run (antes de reportar `running`), ela é re-entregue quando um agente voltar (até 3 tentativas; depois `AgentLost`). A partir do momento em que a run está `running`, a morte do agente **não re-entrega** — a run vira falha `AgentTerminated`, porque o trabalho pode ter efeitos colaterais parciais e re-executar automaticamente não é seguro (reexecute manualmente pelo app).
 
-A entrega é **at-least-once**: se o agente morre logo após capturar uma run (antes de reportar a conclusão), ela é re-entregue quando o agente voltar. Escreva handlers **idempotentes** (use uma chave de deduplicação sua, como o número da nota).
+Ainda assim, escreva handlers **idempotentes**: a janela de re-entrega pós-claim existe, e processar a mesma run duas vezes não pode causar efeito duplicado (use uma chave de deduplicação sua, como o número da nota).
 
 ---
 
@@ -343,9 +358,9 @@ Empacotado em **ESM e CommonJS** com **definições de tipos** (`.d.ts`) para to
 
 ---
 
-## Migração 1.x → 2.x
+## Migração da API antiga (`hobots/manager`)
 
-A 2.0 unifica o Manager no import raiz — `hobots/manager` **foi removido**:
+O Manager foi unificado no import raiz — `hobots/manager` **foi removido**:
 
 ```diff
 -import * as Monitor from 'hobots';
@@ -368,16 +383,19 @@ A 2.0 unifica o Manager no import raiz — `hobots/manager` **foi removido**:
 
 - A `dsn` (mecanismo antigo, `https://<secretKey>@host/<slug>`) não existe mais — passe `clientSecret` (em desenvolvimento, aponte para outro host com a env `HOBOTS_API_URL`). Copie o Client Secret em **Configurações → Projetos**.
 - `agentName` e `serverName` não existem mais — a identidade do agente é o `instanceId` (obrigatório, sem fallback).
-- As opções do Manager (`pollIntervalMs`, `concurrency`, `taskTimeoutMs`, `logFlushIntervalMs`) vão no campo `manager` do `init()`; `clientSecret` e `debug` não se repetem.
+- As opções do Manager (`pollIntervalMs`, `concurrency`, `taskTimeoutMs`, `logFlushIntervalMs`, `cancelCheckIntervalMs`, `installExitHandlers`) vão no campo `manager` do `init()`; `clientSecret` e `debug` não se repetem.
 - Tipos (`ManagerTaskHandler`, `RunContext`, `ManagerOptions`) e classes (`ManagerAgent`, `ManagerApi`) agora vêm de `hobots`; o wire format vem de `hobots/protocol`.
 
 ---
 
 ## Documentação completa
 
-Guias detalhados acompanham o pacote em [`docs/`](./docs/README.md):
+Guias detalhados acompanham o pacote em [`docs/`](./docs/README.md).
+
+Novo no vocabulário de observabilidade (transaction, span, breadcrumb, tag, context, extra, flush, close)? Comece por [Conceitos](./docs/concepts.md) — as outras páginas assumem esses termos.
 
-- [Getting started](./docs/getting-started.md) — instalação, Client Secret, primeiro `init`, Monitor vs Hobots.
+- [Conceitos](./docs/concepts.md) — o que cada coisa é, por que existe e quando escolher uma em vez da outra.
+- [Getting started](./docs/getting-started.md) — instalação, Client Secret, primeiro `init`, Monitor e Manager.
 - [Monitor](./docs/monitor.md) — erros, breadcrumbs, escopo, transactions/spans, crons, heartbeat.
 - [Manager](./docs/manager.md) — handlers, `RunContext`, cancelamento, concorrência, idempotência.
 - [Referência de API](./docs/api-reference.md) — todas as funções e tabelas de opções com defaults.

package/dist/index.cjs

@@ -111,7 +111,7 @@ function parseStacktrace(stack) {
 
 // src/utils.ts
 var SDK_NAME = "hobots";
-var SDK_VERSION = true ? "1.3.4" : "0.0.0-dev";
+var SDK_VERSION = true ? "1.3.5" : "0.0.0-dev";
 function isNode() {
   return typeof process !== "undefined" && typeof process.versions?.node === "string";
 }
@@ -141,11 +141,26 @@ function sleep(ms) {
 var PREFIX = "[hobots-monitor]";
 function makeLogger(enabled, prefix = PREFIX) {
   return {
-    debug: (...args) => enabled && console.debug(prefix, ...args),
-    warn: (...args) => enabled && console.warn(prefix, ...args),
-    error: (...args) => console.error(prefix, ...args)
+    debug: (...args) => enabled && console.debug(colorize(prefix, "gray"), ...args),
+    warn: (...args) => enabled && console.warn(colorize(prefix, "yellow"), ...args),
+    error: (...args) => console.error(colorize(prefix, "red"), ...args)
   };
 }
+var ANSI = {
+  reset: "\x1B[0m",
+  gray: "\x1B[90m",
+  cyan: "\x1B[36m",
+  yellow: "\x1B[33m",
+  red: "\x1B[31m"
+};
+function colorEnabled() {
+  if (!isNode()) return false;
+  return Boolean(process.stdout?.isTTY) && !process.env.NO_COLOR;
+}
+function colorize(text, color) {
+  if (!colorEnabled()) return text;
+  return `${ANSI[color]}${text}${ANSI.reset}`;
+}
 
 // src/eventbuilder.ts
 function safeString(value) {
@@ -617,11 +632,12 @@ var Span = class {
   }
 };
 var Transaction = class {
-  constructor(client2, name, op, sampled = true) {
+  constructor(client2, name, op, sampled = true, runId) {
     this.client = client2;
     this.name = name;
     this.op = op;
     this.sampled = sampled;
+    this.runId = runId;
   }
   eventId = uuid4();
   spanId = spanId();
@@ -664,7 +680,8 @@ var Transaction = class {
       start_timestamp: this.startTimestamp,
       timestamp: nowISO(),
       spans: this.spans.map((span) => span.toJSON()),
-      tags: Object.keys(this.tags).length > 0 ? this.tags : void 0
+      tags: Object.keys(this.tags).length > 0 ? this.tags : void 0,
+      run_id: this.runId
     };
     this.client.sendTransaction(payload);
   }
@@ -799,6 +816,17 @@ var ManagerApi = class {
 };
 
 // src/manager/context.ts
+var LOG_LEVEL_COLOR = {
+  debug: "gray",
+  info: "cyan",
+  warning: "yellow",
+  error: "red"
+};
+function printRunLog(task, level, message) {
+  const line = colorize(`[hobots:${task}] ${level.toUpperCase()}`, LOG_LEVEL_COLOR[level]);
+  const method = level === "warning" ? "warn" : level;
+  console[method](line, message);
+}
 function runCanceledError() {
   return Object.assign(new Error("execu\xE7\xE3o cancelada"), { name: "RunCanceled" });
 }
@@ -828,7 +856,7 @@ var MAX_LOGS_PER_RUN = 500;
 var MAX_LOGS_PER_PATCH = 100;
 var FLUSH_AT_BUFFERED = 20;
 var RunReporter = class {
-  constructor(api, runId, task, logger, flushIntervalMs, cancelCheckIntervalMs) {
+  constructor(api, runId, task, logger, tx, flushIntervalMs, cancelCheckIntervalMs) {
     this.api = api;
     this.runId = runId;
     this.logger = logger;
@@ -848,6 +876,7 @@ var RunReporter = class {
       runId,
       task,
       log,
+      tx,
       signal,
       throwIfCanceled: () => {
         if (signal.aborted) throw runCanceledError();
@@ -888,6 +917,7 @@ var RunReporter = class {
   }
   log(level, message) {
     if (this.dead) return;
+    printRunLog(this.context.task, level, message);
     if (this.loggedCount >= MAX_LOGS_PER_RUN) {
       this.droppedCount++;
       return;
@@ -1062,6 +1092,7 @@ var ManagerAgent = class {
     this.logger = makeLogger(options.debug ?? false, "[hobots-manager]");
     const config = resolveConfig(options, "[hobots-manager]");
     this.api = new ManagerApi({ baseUrl: config.managerBaseUrl, key: config.key, logger: this.logger });
+    this.client = options.client;
     this.pollIntervalMs = Math.max(MIN_POLL_INTERVAL_MS, options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS);
     this.concurrency = Math.min(MAX_CONCURRENCY, Math.max(1, options.concurrency ?? 1));
     this.instanceId = options.instanceId;
@@ -1072,6 +1103,7 @@ var ManagerAgent = class {
   }
   logger;
   api;
+  client;
   pollIntervalMs;
   concurrency;
   instanceId;
@@ -1209,7 +1241,8 @@ var ManagerAgent = class {
     this.activeRuns.add(promise);
   }
   async executeRun(run) {
-    const reporter = new RunReporter(this.api, run.id, run.task, this.logger, this.logFlushIntervalMs, this.cancelCheckIntervalMs);
+    const tx = new Transaction(this.client, `run:${run.task}`, "manager.run", true, run.id);
+    const reporter = new RunReporter(this.api, run.id, run.task, this.logger, tx, this.logFlushIntervalMs, this.cancelCheckIntervalMs);
     this.reporters.add(reporter);
     try {
       const handler = this.registry.get(run.task);
@@ -1219,22 +1252,29 @@ var ManagerAgent = class {
           message: `tarefa n\xE3o registrada no agente: ${run.task}`
         });
         await reporter.finalize();
+        tx.setStatus("error");
+        tx.finish();
         return;
       }
       const ok = await reporter.reportRunning();
       if (!ok) {
         this.logger.debug(`run ${run.id} cancelada antes de iniciar \u2014 handler n\xE3o executado`);
+        tx.setStatus("cancelled");
+        tx.finish();
         return;
       }
       this.logger.debug(`executando run ${run.id} (${run.task})`);
       try {
         await this.invokeWithTimeout(handler, run, reporter);
         reporter.reportSuccess();
+        tx.setStatus("ok");
         this.logger.debug(`run ${run.id} conclu\xEDda`);
       } catch (error) {
         reporter.reportFailure(toRunError(error));
+        tx.setStatus("error");
         this.logger.debug(`run ${run.id} falhou: ${String(error)}`);
       }
+      tx.finish();
       await reporter.finalize();
     } finally {
       this.reporters.delete(reporter);
@@ -1305,7 +1345,7 @@ function init(options) {
   if (options.manager) {
     const managerOptions = options.manager === true ? {} : options.manager;
     agent = new ManagerAgent(
-      { ...managerOptions, clientSecret: options.clientSecret, instanceId: options.instanceId, debug: options.debug },
+      { ...managerOptions, clientSecret: options.clientSecret, instanceId: options.instanceId, debug: options.debug, client },
       registry
     );
   }