hobots 1.9.2 → 2.0.0

package/README.md

@@ -260,6 +260,7 @@ interface RunContext {
   runId: string;
   task: string;
   log: RunLogger; // ctx.log.debug/info/warn/error/success(message)
+  items: RunItems; // ctx.items.succeeded/failed/occurrence — a entrega do bot
   tx: Transaction; // transaction desta run — correlacionada e finalizada pelo SDK
   signal: AbortSignal;
   throwIfCanceled(): void; // lança RunCanceled se o signal já disparou
@@ -269,6 +270,7 @@ interface RunContext {
 
 - **`params`** — os dados do formulário configurado no app (JSON validado). Tipável: `Hobots.register<{ lote: number }>(...)`.
 - **`ctx.log.<level>(message)`** — níveis `debug`, `info`, `warn`, `error` e `success`; logs enviados **incrementalmente** ao app (PATCHes com throttle), visíveis na solicitação quase em tempo real; também impressos no terminal local, coloridos por nível.
+- **`ctx.items`** — registra os **itens que a execução processou/gerou** (a entrega do bot: notas fiscais baixadas, boletos emitidos…), cada um com status `succeeded`, `failed` (falha técnica) ou `occurrence` (ocorrência de negócio, ex.: "nota nº 10 não encontrada") e um `payload` de atributos livres. Aparecem na aba **itens** da solicitação, com totalizadores; as colunas exibidas são configuradas por formulário no app. Guia: [Itens de execução](./docs/tasks.md#itens-de-execução-ctxitems).
 - **`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. `startTransaction()` chamado dentro do handler retorna essa mesma transaction. 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.
@@ -278,6 +280,25 @@ interface RunContext {
 
 > **Dados sensíveis:** `ctx.log` e mensagens/stack de erros **são enviados ao servidor** e ficam visíveis no app. Não inclua senhas, tokens, dados pessoais ou qualquer informação sensível em logs e mensagens de erro.
 
+### Itens de execução (`ctx.items`)
+
+```js
+Hobots.register('baixar-notas', async (params, ctx) => {
+  for (const nota of await listarNotas(params)) {
+    try {
+      await baixar(nota);
+      ctx.items.succeeded({ numero_nota: nota.numero, cnpj_prestador: nota.cnpj }, { id: nota.numero });
+    } catch (erro) {
+      ctx.items.failed(String(erro), { numero_nota: nota.numero }, { id: nota.numero });
+    }
+  }
+  // ocorrência de negócio (não é falha do bot):
+  // ctx.items.occurrence('nota nº 10 não encontrada', { numero_nota: '10' }, { id: '10' })
+});
+```
+
+Chamadas síncronas e bufferizadas (lotes de até 500; dreno antes do reporte final). O `id` opcional é a identidade de negócio do item na run — repetido, é ignorado pelo servidor (registro único, retry idempotente). Limites: 10.000 itens/run, payload 16 KB, mensagem 2.000 caracteres. Detalhes em [Itens de execução](./docs/tasks.md#itens-de-execução-ctxitems).
+
 ### Anexos (screenshots)
 
 Texto de log conta o que o robô fez; um print conta **como estava a tela**. Os métodos de captura (`Hobots.captureException` e `Hobots.captureMessage`) aceitam um `attachment` no hint: dentro de uma execução de task, a imagem vira anexo da linha de log da run que espelha a captura — no app ela aparece como miniatura logo abaixo dessa linha, clicável para ampliar.

package/dist/index.cjs

@@ -161,7 +161,7 @@ function scrubSecrets(text) {
 
 // src/utils.ts
 var SDK_NAME = "hobots";
-var SDK_VERSION = true ? "1.9.1" : "0.0.0-dev";
+var SDK_VERSION = true ? "2.0.0" : "0.0.0-dev";
 function isNode() {
   return typeof process !== "undefined" && typeof process.versions?.node === "string";
 }
@@ -354,7 +354,8 @@ var Transport = class {
       return;
     }
     if (this.buffer.length >= this.maxQueueSize) {
-      this.buffer.shift();
+      const dropIndex = this.buffer.findIndex((queued) => queued.type !== "heartbeat");
+      this.buffer.splice(dropIndex === -1 ? 0 : dropIndex, 1);
       this.logger.warn("fila cheia, item mais antigo descartado");
     }
     this.buffer.push(item);
@@ -445,6 +446,8 @@ function runtimeContexts() {
 }
 var Client = class {
   logger;
+  /** Eco de lifecycle (Transaction.emit) e afins só imprimem no terminal com debug ligado. */
+  debug;
   // campos privados + getters de protótipo: o clientSecret não aparece em
   // JSON.stringify/serialização enumerável do Client (ex.: um objeto capturado
   // que referencie o client), mas client.options/config seguem funcionando
@@ -453,7 +456,8 @@ var Client = class {
   transport;
   constructor(options, config = resolveConfig(options)) {
     this.#options = options;
-    this.logger = makeLogger(!!options.debug);
+    this.debug = !!options.debug;
+    this.logger = makeLogger(this.debug);
     this.#config = config;
     this.transport = new Transport({
       endpoint: this.#config.ingestEndpoint,
@@ -540,6 +544,8 @@ var Client = class {
 
 // src/heartbeat.ts
 var DEFAULT_INTERVAL_MS = 3e4;
+var MIN_REPORTED_INTERVAL_MS = 1e3;
+var MAX_REPORTED_INTERVAL_MS = 9e5;
 var Heartbeat = class {
   constructor(client2, options = {}, instanceId) {
     this.client = client2;
@@ -556,12 +562,22 @@ var Heartbeat = class {
   start() {
     if (this.timer) return;
     this.beat();
-    this.timer = setInterval(() => this.beat(), this.intervalMs);
+    this.schedule();
+  }
+  /** Jitter de ±10%: uma frota iniciada junto não sincroniza todos os beats no mesmo segundo. */
+  schedule() {
+    this.timer = setTimeout(
+      () => {
+        this.beat();
+        this.schedule();
+      },
+      this.intervalMs * (0.9 + Math.random() * 0.2)
+    );
     unrefTimer(this.timer);
   }
   stop() {
     if (this.timer) {
-      clearInterval(this.timer);
+      clearTimeout(this.timer);
       this.timer = void 0;
     }
   }
@@ -569,7 +585,7 @@ var Heartbeat = class {
     this.client.sendHeartbeat({
       instance_id: this.instanceId,
       name: this.name,
-      interval_ms: this.intervalMs,
+      interval_ms: Math.min(Math.max(this.intervalMs, MIN_REPORTED_INTERVAL_MS), MAX_REPORTED_INTERVAL_MS),
       timestamp: nowISO(),
       metadata: this.metadata
     });
@@ -816,15 +832,18 @@ var Transaction = class {
   // antes do RunReporter conectar) — replay no setLifecycleSink
   lifecycleBacklog = [];
   /**
-   * Ecoa no terminal o início/fim de uma step ou transaction (sempre, independente de
-   * sampling ou do debug) e espelha a linha no sink de lifecycle, se conectado — é
-   * assim que os eventos de performance também aparecem nos logs da run no app.
+   * Registra o início/fim de uma step ou transaction: espelha a linha no sink de
+   * lifecycle, se conectado (é assim que os eventos de performance aparecem nos
+   * logs da run no app), e ecoa no terminal apenas com `debug: true` — o SDK não
+   * escreve no stdout do processo do usuário sem permissão.
    */
   emit(kind, phase, label, startTs, endTs, status) {
     const durationMs = startTs && endTs ? new Date(endTs).getTime() - new Date(startTs).getTime() : void 0;
-    const tag = colorize(`[hobots:${kind}] ${phase.toUpperCase()}`, phase === "finish" ? colorForStatus(status ?? "ok") : "cyan");
     const suffix = durationMs != null ? ` (${durationMs}ms)` : "";
-    console.log(`${tag} ${label}${suffix}`);
+    if (this.client?.debug) {
+      const tag = colorize(`[hobots:${kind}] ${phase.toUpperCase()}`, phase === "finish" ? colorForStatus(status ?? "ok") : "cyan");
+      console.log(`${tag} ${label}${suffix}`);
+    }
     const level = phase === "finish" ? levelForStatus(status ?? "ok") : "info";
     const message = `[${kind}] ${phase.toUpperCase()} ${label}${suffix}`;
     if (this.lifecycleSink) this.lifecycleSink(level, message);
@@ -987,6 +1006,38 @@ var TasksApi = class {
       signal: AbortSignal.timeout(timeoutMs)
     });
   }
+  /**
+   * Envia um lote de itens de execução. Retry em falha de rede/5xx/429-transporte;
+   * 4xx é definitivo (404 = servidor sem o recurso, 429 = cap de itens por run) —
+   * o RunReporter trata por status.
+   */
+  async createItems(runId, request) {
+    let response;
+    try {
+      response = await fetchWithRetry(
+        () => fetch(`${this.baseUrl}/runs/${encodeURIComponent(runId)}/items`, {
+          method: "POST",
+          headers: this.headers(),
+          body: JSON.stringify(request),
+          signal: AbortSignal.timeout(UPDATE_TIMEOUT_MS)
+        }),
+        { logger: this.logger, label: `itens da run ${runId}` }
+      );
+    } catch (error) {
+      if (error instanceof Error && error.message === "HTTP 429") {
+        throw new TasksApiError("envio de itens rejeitado (HTTP 429)", 429);
+      }
+      throw new Error(`envio de itens da run ${runId} descartado ap\xF3s retries: ${String(error)}`);
+    }
+    if (!response.ok) {
+      throw new TasksApiError(`envio de itens rejeitado (HTTP ${response.status})`, response.status);
+    }
+    const body = await response.json().catch(() => null);
+    return {
+      accepted: typeof body?.accepted === "number" ? body.accepted : request.items.length,
+      duplicates: typeof body?.duplicates === "number" ? body.duplicates : 0
+    };
+  }
   /**
    * Registra o anexo e obtém a URL presignada de upload. 404/501/503 significam
    * "esta instalação não tem anexos" — o RunReporter degrada em silêncio a partir daí.
@@ -1144,6 +1195,22 @@ var MAX_CANCEL_CHECK_INTERVAL_MS = 15e3;
 var MAX_LOG_MESSAGE_CHARS = 1e4;
 var MAX_LOGS_PER_PATCH = 100;
 var FLUSH_AT_BUFFERED = 20;
+var MAX_ITEMS_PER_RUN = 1e4;
+var MAX_ITEMS_PER_REQUEST = 500;
+var MAX_ITEM_MESSAGE_CHARS = 2e3;
+var MAX_ITEM_PAYLOAD_BYTES = 16384;
+var ITEMS_FLUSH_AT_BUFFERED = 100;
+var ITEMS_DRAIN_MS = 15e3;
+function scrubPayloadValue(value, depth) {
+  if (typeof value === "string") return scrubSecrets(value);
+  if (depth >= 4 || value === null || typeof value !== "object") return value;
+  if (Array.isArray(value)) return value.map((entry) => scrubPayloadValue(entry, depth + 1));
+  const out = {};
+  for (const [key, entry] of Object.entries(value)) {
+    out[key] = scrubPayloadValue(entry, depth + 1);
+  }
+  return out;
+}
 var RunReporter = class {
   constructor(api, runId, task, logger, tx, flushIntervalMs, cancelCheckIntervalMs) {
     this.api = api;
@@ -1162,11 +1229,18 @@ var RunReporter = class {
       success: (message) => this.log("success", message)
     };
     tx.setLifecycleSink((level, message) => this.push(level, message));
+    const items = {
+      add: (item) => this.addItem(item.status, item.message, item.payload, item.id),
+      succeeded: (payload, options) => this.addItem("succeeded", void 0, payload, options?.id),
+      failed: (message, payload, options) => this.addItem("failed", message, payload, options?.id),
+      occurrence: (message, payload, options) => this.addItem("occurrence", message, payload, options?.id)
+    };
     const signal = this.abortController.signal;
     this.context = {
       runId,
       task,
       log,
+      items,
       tx,
       signal,
       throwIfCanceled: () => {
@@ -1185,6 +1259,23 @@ var RunReporter = class {
   abortController = new AbortController();
   flushIntervalMs;
   cancelCheckIntervalMs;
+  // Itens de execução vivem FORA de `this.chain` (status/liveness não pode ficar
+  // atrás de milhares de itens), mas têm cadeia própria serializada — ordem de
+  // envio preservada e sem lotes sobrepostos.
+  itemsBuffer = [];
+  itemsChain = Promise.resolve();
+  itemsTimer;
+  itemSeq = 0;
+  itemCount = 0;
+  /** Servidor sem o recurso (404) — para de tentar (e de avisar) nesta run. */
+  itemsUnsupported = false;
+  /** Cap de itens por run atingido (client-side ou 429) — degrada com um aviso só. */
+  itemsQuotaExceeded = false;
+  /**
+   * Só o kill() do exit path fecha os itens — `dead` (run cancelada/finalizada no
+   * servidor) NÃO fecha: o servidor aceita itens de run terminal (trabalho já feito).
+   */
+  itemsClosed = false;
   // Uploads de anexo vivem FORA de `this.chain`: a cadeia é um FIFO puro de
   // status/logs e não pode ficar bloqueada esperando um binário subir.
   pendingAttachments = /* @__PURE__ */ new Set();
@@ -1211,6 +1302,12 @@ var RunReporter = class {
     this.dead = true;
     this.clearFlushTimer();
     this.buffer = [];
+    this.itemsClosed = true;
+    this.clearItemsTimer();
+    if (this.itemsBuffer.length > 0) {
+      this.logger.warn(`${this.itemsBuffer.length} item(ns) de execu\xE7\xE3o descartados (processo encerrando)`);
+      this.itemsBuffer = [];
+    }
     const waiting = this.uploadQueue.splice(0, this.uploadQueue.length);
     for (const resume of waiting) resume();
   }
@@ -1313,6 +1410,120 @@ var RunReporter = class {
   finalize() {
     return this.chain;
   }
+  // ── Itens de execução ────────────────────────────────────────────────────────
+  /**
+   * Bufferiza um item (síncrono — a chamada nunca espera rede). Diferente do PATCH
+   * de status, o servidor aceita itens mesmo com a run cancelada (trabalho já feito),
+   * então um reporter morto não descarta: só um kill() de exit path descarta.
+   */
+  addItem(status, message, payload, id) {
+    if (this.itemsClosed || this.itemsUnsupported) return;
+    if (this.itemCount >= MAX_ITEMS_PER_RUN) {
+      if (!this.itemsQuotaExceeded) {
+        this.itemsQuotaExceeded = true;
+        this.log("warning", `itens descartados: limite de ${MAX_ITEMS_PER_RUN} por execu\xE7\xE3o atingido`);
+      }
+      return;
+    }
+    this.itemCount++;
+    let scrubbedPayload;
+    if (payload) {
+      scrubbedPayload = scrubPayloadValue(payload, 0);
+      let serializedLength;
+      try {
+        serializedLength = JSON.stringify(scrubbedPayload).length;
+      } catch {
+      }
+      if (serializedLength === void 0 || serializedLength > MAX_ITEM_PAYLOAD_BYTES) {
+        this.logger.warn(
+          `payload do item descartado (${serializedLength === void 0 ? "n\xE3o serializ\xE1vel" : `${serializedLength} bytes > ${MAX_ITEM_PAYLOAD_BYTES}`}) \u2014 o item foi mantido`
+        );
+        scrubbedPayload = void 0;
+      }
+    }
+    this.itemsBuffer.push({
+      id: id ? truncate(String(id), 255) : uuid4(),
+      seq: this.itemSeq++,
+      status,
+      ...message ? { message: truncate(scrubSecrets(message), MAX_ITEM_MESSAGE_CHARS) } : {},
+      ...scrubbedPayload ? { payload: scrubbedPayload } : {},
+      ts: nowISO()
+    });
+    if (this.itemsBuffer.length >= ITEMS_FLUSH_AT_BUFFERED) {
+      this.flushItems();
+    } else {
+      this.scheduleItemsFlush();
+    }
+  }
+  scheduleItemsFlush() {
+    if (this.itemsTimer) return;
+    this.itemsTimer = setTimeout(() => {
+      this.itemsTimer = void 0;
+      this.flushItems();
+    }, this.flushIntervalMs);
+    unrefTimer(this.itemsTimer);
+  }
+  clearItemsTimer() {
+    if (this.itemsTimer) {
+      clearTimeout(this.itemsTimer);
+      this.itemsTimer = void 0;
+    }
+  }
+  /** Envia o buffer de itens em lotes serializados na cadeia própria. */
+  flushItems() {
+    this.clearItemsTimer();
+    if (this.itemsBuffer.length === 0 || this.itemsUnsupported) return;
+    const items = this.itemsBuffer.splice(0, this.itemsBuffer.length);
+    for (let i = 0; i < items.length; i += MAX_ITEMS_PER_REQUEST) {
+      const batch = items.slice(i, i + MAX_ITEMS_PER_REQUEST);
+      this.itemsChain = this.itemsChain.then(() => this.sendItems(batch));
+    }
+  }
+  async sendItems(batch) {
+    if (this.itemsUnsupported) return;
+    try {
+      await this.api.createItems(this.runId, { items: batch });
+    } catch (error) {
+      if (error instanceof TasksApiError && error.status === 404) {
+        this.itemsUnsupported = true;
+        this.logger.warn("itens de execu\xE7\xE3o n\xE3o s\xE3o suportados por este servidor Hobots \u2014 descartados");
+        return;
+      }
+      if (error instanceof TasksApiError && error.status === 429) {
+        if (!this.itemsQuotaExceeded) {
+          this.itemsQuotaExceeded = true;
+          this.log("warning", "itens descartados: limite de itens por execu\xE7\xE3o atingido no servidor");
+        }
+        return;
+      }
+      if (error instanceof TasksApiError) {
+        this.logger.error(`lote de ${batch.length} item(ns) rejeitado pelo servidor:`, error);
+        return;
+      }
+      this.itemsBuffer.unshift(...batch);
+      this.scheduleItemsFlush();
+      this.logger.error(`lote de ${batch.length} item(ns) n\xE3o enviado (devolvido ao buffer):`, error);
+    }
+  }
+  /**
+   * Dreno final de itens antes do PATCH terminal (com teto): garante que os
+   * totalizadores estejam completos quando a run vira succeeded/failed. Como o
+   * servidor aceita itens tardios, perder a corrida aqui não perde dados.
+   */
+  async finalizeItems(timeoutMs = ITEMS_DRAIN_MS) {
+    this.flushItems();
+    await Promise.race([
+      this.itemsChain,
+      new Promise((resolve) => unrefTimer(setTimeout(resolve, timeoutMs)))
+    ]);
+    if (this.itemsBuffer.length > 0 && !this.itemsUnsupported && !this.itemsQuotaExceeded) {
+      this.flushItems();
+      await Promise.race([
+        this.itemsChain,
+        new Promise((resolve) => unrefTimer(setTimeout(resolve, timeoutMs)))
+      ]);
+    }
+  }
   // ── Anexos ───────────────────────────────────────────────────────────────────
   /**
    * Registra a linha de log com o id do anexo (síncrono, na ordem certa) e dispara
@@ -1679,13 +1890,17 @@ var TaskAgent = class {
     try {
       const response = await this.api.poll(
         {
-          agent: {
+          instance: {
             // identidade canônica do agente no painel — o mesmo instanceId do
             // heartbeat da Telemetria, então os dois canais convergem em um agente
             instance_id: this.instanceId,
             version: SDK_VERSION,
             host: hostname(),
-            tasks: [...this.registry.keys()]
+            tasks: [...this.registry.keys()],
+            // o servidor calcula a tolerância de offline (3×) a partir disto em
+            // agentes poll-only — sem o campo, um poll lento flaparia offline/online.
+            // Clampado à faixa aceita pelo schema do poll (1s..15min).
+            poll_interval_ms: Math.min(Math.max(this.pollIntervalMs, 1e3), 9e5)
           },
           max: Math.min(MAX_CONCURRENCY, this.concurrency - this.activeRuns.size),
           tasks: [...this.registry.keys()]
@@ -1757,12 +1972,14 @@ var TaskAgent = class {
           () => this.invokeWithTimeout(handler, run, reporter)
         );
         await reporter.finalizeAttachments();
+        await reporter.finalizeItems();
         tx.setStatus("ok");
         tx.finish();
         reporter.reportSuccess();
         this.logger.debug(`run ${run.id} conclu\xEDda`);
       } catch (error) {
         await reporter.finalizeAttachments();
+        await reporter.finalizeItems();
         tx.setStatus("error");
         tx.finish();
         reporter.reportFailure(toRunError(error));