hobots 4.0.0 → 4.1.0

package/README.md

@@ -91,7 +91,7 @@ A opção passada em `register()`/`start()` tem precedência sobre a env — út
 
 **Um processo = um agente = uma chamada.** A segunda chamada a `register()`/`start()` lança (`o agente já foi iniciado`). Um robô que precisa monitorar uma pasta *e* atender solicitações são dois agentes — dois processos, cada um com o seu Client Secret.
 
-> **Modo start e o limite de logs:** o servidor guarda no máximo **1000 linhas de log por execução**. Num loop que roda por dias, logue o que importa (ciclos com novidade, avisos, erros) e registre o trabalho em `hobots.items` — itens não têm esse teto tão baixo (10.000 por execução).
+> **Modo start e o limite de logs:** o servidor guarda no máximo **1000 linhas de log por execução**. Num loop que roda por dias, logue o que importa (ciclos com novidade, avisos, erros) e registre o trabalho em `hobots.items` — itens não têm teto por execução (só o armazenamento do plano limita). As steps de uma run que não termina só chegam à Central com `hobots.flush()` — chame-o ao fim de cada rodada que processou itens.
 
 ---
 
@@ -103,6 +103,7 @@ A opção passada em `register()`/`start()` tem precedência sobre a env — út
 | `hobots.items.succeeded(payload?, { id, image }?)` · `.failed(msg, payload?, …)` · `.occurrence(msg, payload?, …)` · `.add({...})` | **A entrega do robô**: cada item processado, com status e atributos (viram colunas no app — declare-as com a opção `items: { columns: [...] }` do `register`/`start`). `image` pendura um print no item. Bufferizado, em lotes. |
 | `hobots.items.each(lista, async (el, item) => …, { id, payload }?)` | **Loop com o contrato garantido**: cada elemento vira step + item; exceção no handler = item `failed` com a mensagem e o loop **segue** até o fim; progresso automático. Só cancelamento/timeout interrompem. |
 | `hobots.progress.total(n)` · `.advance(k = 1)` · `.set(atual, total?)` · `.current` · `.snapshot` | Barra, percentual e tempo restante na execução. Sem `total()` nada é enviado. |
+| `hobots.flush(timeoutMs?)` | **Entrega já** o que a execução fez: as steps raiz finalizadas viram transactions parciais (waterfall na Central sem esperar a run terminar) e itens, logs e progresso pendentes saem sem esperar o throttle. O bot decide quando — num agente `start()`, ao fim de cada rodada que processou itens. Aguarda com teto (15 s) e nunca lança. |
 | `hobots.transaction.startChild(op, descrição)` | Uma **step** no waterfall de performance da execução. A transaction da execução (`run`) já existe e é finalizada pelo SDK. `step.setStatus(status, msg?, { image })` / `setError(err, msg?, { image })` penduram um print na step. |
 | `hobots.image(bytes \| caminho, { caption?, contentType? })` | Embrulha um **print** (PNG/JPEG/WEBP, até 5 MB, 20 por execução) para ir junto de um log, item ou step. Puro: o upload roda em segundo plano quando o evento é registrado; nunca lança nem bloqueia. |
 | `hobots.captureException(erro, hint?)` | Abre uma **issue** (módulo Issues). `hint.attachment` anexa um print à linha de log correspondente. |

package/dist/{chunk-5WIIACWC.js → chunk-HKCDMUA3.js}

@@ -9,7 +9,6 @@ var protocol_limits_default = {
   MAX_LOGS_PER_PATCH: 100,
   MAX_ERROR_MESSAGE_CHARS: 1e4,
   MAX_ERROR_STACK_CHARS: 2e4,
-  MAX_ITEMS_PER_RUN: 1e4,
   MAX_ITEMS_PER_REQUEST: 500,
   MAX_ITEM_MESSAGE_CHARS: 2e3,
   MAX_ITEM_PAYLOAD_BYTES: 16384,
@@ -28,4 +27,4 @@ var WIRE_LIMITS = protocol_limits_default;
 export {
   WIRE_LIMITS
 };
-//# sourceMappingURL=chunk-5WIIACWC.js.map
+//# sourceMappingURL=chunk-HKCDMUA3.js.map

package/dist/chunk-HKCDMUA3.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../protocol-limits.json","../src/wire-limits.ts"],"sourcesContent":["{\n  \"MAX_ITEMS_PER_ENVELOPE\": 50,\n  \"HEARTBEAT_DEFAULT_INTERVAL_MS\": 30000,\n  \"HEARTBEAT_MIN_INTERVAL_MS\": 1000,\n  \"HEARTBEAT_MAX_INTERVAL_MS\": 900000,\n  \"MAX_CLAIM_PER_POLL\": 5,\n  \"MAX_LOG_MESSAGE_CHARS\": 10000,\n  \"MAX_LOGS_PER_PATCH\": 100,\n  \"MAX_ERROR_MESSAGE_CHARS\": 10000,\n  \"MAX_ERROR_STACK_CHARS\": 20000,\n  \"MAX_ITEMS_PER_REQUEST\": 500,\n  \"MAX_ITEM_MESSAGE_CHARS\": 2000,\n  \"MAX_ITEM_PAYLOAD_BYTES\": 16384,\n  \"MAX_ITEM_COLUMNS\": 12,\n  \"MAX_ITEM_COLUMN_LABEL_CHARS\": 60,\n  \"MAX_ATTACHMENT_BYTES\": 5242880,\n  \"MAX_ATTACHMENTS_PER_RUN\": 20,\n  \"MAX_ATTACHMENTS_PER_LOG_ENTRY\": 4,\n  \"MAX_CAPTION_CHARS\": 200,\n  \"MAX_IMAGE_DIMENSION_PX\": 20000\n}\n","import limits from '../protocol-limits.json';\n\n/**\n * Limites do wire SDK ↔ servidor — fonte ÚNICA (protocol-limits.json): o SDK\n * Node lê daqui, a @hobots/api importa de `hobots/protocol` e o SDK Python\n * confere a paridade num teste que lê o mesmo JSON. Mudar um limite = mudar o\n * JSON (e, no Python, a constante espelhada — o teste acusa).\n */\nexport const WIRE_LIMITS = limits as Readonly<typeof limits>;\nexport type WireLimits = typeof WIRE_LIMITS;\n"],"mappings":";AAAA;AAAA,EACE,wBAA0B;AAAA,EAC1B,+BAAiC;AAAA,EACjC,2BAA6B;AAAA,EAC7B,2BAA6B;AAAA,EAC7B,oBAAsB;AAAA,EACtB,uBAAyB;AAAA,EACzB,oBAAsB;AAAA,EACtB,yBAA2B;AAAA,EAC3B,uBAAyB;AAAA,EACzB,uBAAyB;AAAA,EACzB,wBAA0B;AAAA,EAC1B,wBAA0B;AAAA,EAC1B,kBAAoB;AAAA,EACpB,6BAA+B;AAAA,EAC/B,sBAAwB;AAAA,EACxB,yBAA2B;AAAA,EAC3B,+BAAiC;AAAA,EACjC,mBAAqB;AAAA,EACrB,wBAA0B;AAC5B;;;ACZO,IAAM,cAAc;","names":[]}

package/dist/index.cjs

@@ -96,7 +96,7 @@ function scrubSecrets(text) {
 
 // src/utils.ts
 var SDK_NAME = "hobots";
-var SDK_VERSION = true ? "4.0.0" : "0.0.0-dev";
+var SDK_VERSION = true ? "4.1.0" : "0.0.0-dev";
 function isNode() {
   return typeof process !== "undefined" && typeof process.versions?.node === "string";
 }
@@ -281,7 +281,6 @@ var protocol_limits_default = {
   MAX_LOGS_PER_PATCH: 100,
   MAX_ERROR_MESSAGE_CHARS: 1e4,
   MAX_ERROR_STACK_CHARS: 2e4,
-  MAX_ITEMS_PER_RUN: 1e4,
   MAX_ITEMS_PER_REQUEST: 500,
   MAX_ITEM_MESSAGE_CHARS: 2e3,
   MAX_ITEM_PAYLOAD_BYTES: 16384,
@@ -1414,7 +1413,6 @@ var MAX_CANCEL_CHECK_INTERVAL_MS = 15e3;
 var MAX_LOG_MESSAGE_CHARS = WIRE_LIMITS.MAX_LOG_MESSAGE_CHARS;
 var MAX_LOGS_PER_PATCH = WIRE_LIMITS.MAX_LOGS_PER_PATCH;
 var FLUSH_AT_BUFFERED = 20;
-var MAX_ITEMS_PER_RUN = WIRE_LIMITS.MAX_ITEMS_PER_RUN;
 var MAX_ITEMS_PER_REQUEST = WIRE_LIMITS.MAX_ITEMS_PER_REQUEST;
 var MAX_ITEM_MESSAGE_CHARS = WIRE_LIMITS.MAX_ITEM_MESSAGE_CHARS;
 var MAX_ITEM_PAYLOAD_BYTES = WIRE_LIMITS.MAX_ITEM_PAYLOAD_BYTES;
@@ -1436,6 +1434,7 @@ var RunReporter = class {
     this.api = api;
     this.runId = runId;
     this.logger = logger;
+    this.tx = tx;
     this.flushIntervalMs = flushIntervalMs ?? DEFAULT_LOG_FLUSH_INTERVAL_MS;
     this.cancelCheckIntervalMs = Math.min(
       MAX_CANCEL_CHECK_INTERVAL_MS,
@@ -1519,6 +1518,7 @@ var RunReporter = class {
       items,
       progress,
       transaction: tx,
+      flush: (timeoutMs) => this.flush(timeoutMs),
       signal,
       throwIfCanceled: checkCanceled,
       sleep: sleep2,
@@ -1528,6 +1528,7 @@ var RunReporter = class {
   api;
   runId;
   logger;
+  tx;
   context;
   buffer = [];
   dead = false;
@@ -1545,7 +1546,6 @@ var RunReporter = class {
   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ó. */
@@ -1668,6 +1668,21 @@ var RunReporter = class {
       this.enqueue({ status: "running", logs: logs.slice(i, i + MAX_LOGS_PER_PATCH) });
     }
   }
+  /**
+   * `hobots.flush()`: o bot decide quando entregar o que já fez — steps raiz finalizadas
+   * viram transactions parciais da run, e itens, logs e progresso pendentes saem já, sem
+   * esperar o throttle. Aguarda a entrega com teto. Nunca lança (pode ir num `finally`).
+   */
+  async flush(timeoutMs = ITEMS_DRAIN_MS) {
+    this.tx.flush();
+    this.flushItems();
+    if (this.progressDirty) this.flushProgress();
+    else this.flushLogs();
+    await Promise.race([
+      Promise.all([this.itemsChain, this.chain, this.tx.drain(timeoutMs)]).catch(() => void 0),
+      new Promise((resolve2) => unrefTimer(setTimeout(resolve2, timeoutMs)))
+    ]);
+  }
   /** Primeiro PATCH (claimed → running). Retorna false se a run já morreu (cancelada). */
   async reportRunning() {
     this.enqueue({ status: "running" });
@@ -1778,14 +1793,6 @@ var RunReporter = class {
    */
   addItem(status, message, payload, id, image3) {
     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);
@@ -2080,6 +2087,7 @@ function currentRunReporter() {
 }
 
 // src/transaction.ts
+var FLUSH_TRANSACTION_OP = "hobots.run.flush";
 var MAX_STEP_MESSAGE_CHARS = 2e3;
 function stepMessage(text) {
   return truncate(scrubSecrets(text), MAX_STEP_MESSAGE_CHARS);
@@ -2301,6 +2309,60 @@ var Transaction = class {
     this.name = name;
     return this;
   }
+  /**
+   * Envia já as steps raiz finalizadas (e todas as descendentes, fechando as que
+   * ficaram abertas) como transactions parciais da mesma run (`op` hobots.run.flush,
+   * `event_id` novo, até 200 steps cada) e as tira da memória. Steps raiz ainda abertas
+   * ficam para o próximo flush ou para o `finish()`. É assim que um agente sempre
+   * ligado (`start()`), cuja run não termina, entrega as etapas enquanto processa.
+   * Devolve quantas steps foram enviadas.
+   */
+  flush() {
+    if (this.finished) return 0;
+    const ready = /* @__PURE__ */ new Set();
+    for (const step of this.steps) {
+      if (step.parentStepId === this.stepId && step.endTimestamp) ready.add(step.stepId);
+    }
+    if (ready.size === 0) return 0;
+    const batch = [];
+    const remaining = [];
+    for (const step of this.steps) {
+      if (ready.has(step.stepId) || ready.has(step.parentStepId)) {
+        ready.add(step.stepId);
+        batch.push(step);
+      } else {
+        remaining.push(step);
+      }
+    }
+    for (const step of batch) step.finish();
+    this.steps.splice(0, this.steps.length, ...remaining);
+    if (this.client) {
+      for (let i = 0; i < batch.length; i += MAX_STEPS) {
+        const chunk = batch.slice(i, i + MAX_STEPS);
+        const startTimestamp = chunk.reduce((min, step) => step.startTimestamp < min ? step.startTimestamp : min, chunk[0].startTimestamp);
+        const status = chunk.some((step) => step.status === "error") ? "error" : "ok";
+        this.client.sendTransaction(this.payload(uuid4(), FLUSH_TRANSACTION_OP, status, startTimestamp, nowISO(), chunk));
+      }
+    }
+    return batch.length;
+  }
+  /** Entrega já (com teto) o que está na fila do transport — as transactions parciais inclusive. */
+  async drain(timeoutMs) {
+    await this.client?.flush(timeoutMs);
+  }
+  payload(eventId, op, status, startTimestamp, timestamp, steps) {
+    return {
+      event_id: eventId,
+      name: this.name,
+      op,
+      status,
+      start_timestamp: startTimestamp,
+      timestamp,
+      steps: steps.map((step) => step.toJSON()),
+      tags: Object.keys(this.tags).length > 0 ? { ...this.tags } : void 0,
+      run_id: this.runId
+    };
+  }
   finish() {
     if (this.finished) return;
     this.finished = true;
@@ -2315,18 +2377,15 @@ var Transaction = class {
       this.status
     );
     if (!this.client) return;
-    const payload = {
-      event_id: this.eventId,
-      name: this.name,
-      op: this.op,
-      status: this.status,
-      start_timestamp: this.startTimestamp,
-      timestamp: endTimestamp,
-      steps: this.steps.map((step) => step.toJSON()),
-      tags: Object.keys(this.tags).length > 0 ? this.tags : void 0,
-      run_id: this.runId
-    };
-    this.client.sendTransaction(payload);
+    const steps = this.steps;
+    let first = 0;
+    while (steps.length - first > MAX_STEPS) {
+      const chunk = steps.slice(first, first + MAX_STEPS);
+      const status = chunk.some((step) => step.status === "error") ? "error" : "ok";
+      this.client.sendTransaction(this.payload(uuid4(), FLUSH_TRANSACTION_OP, status, chunk[0].startTimestamp, endTimestamp, chunk));
+      first += MAX_STEPS;
+    }
+    this.client.sendTransaction(this.payload(this.eventId, this.op, this.status, this.startTimestamp, endTimestamp, steps.slice(first)));
   }
 };
 
@@ -3031,6 +3090,7 @@ var hobots = Object.defineProperties({}, {
   signal: getter("signal", () => neverAborts),
   throwIfCanceled: method(() => resolve("throwIfCanceled")?.throwIfCanceled()),
   sleep: method((ms) => resolve("sleep")?.sleep(ms) ?? sleep(ms)),
+  flush: method((timeoutMs) => resolve("flush")?.flush(timeoutMs) ?? Promise.resolve()),
   retry: method((fn, options) => {
     const reporter = currentReporter();
     return reporter ? reporter.context.retry(fn, options) : retryWithBackoff(fn, options);