hobots 3.2.2 → 3.3.0

package/README.md

@@ -95,6 +95,7 @@ Os dois podem coexistir no mesmo processo: um monitor sempre ligado + tasks sob
 | --- | --- |
 | `hobots.log.debug/info/warn/error/success(msg, ...rest)` | Log da execução, enviado incrementalmente ao app (e ecoado no terminal). Aceita vários argumentos como `console.log` — `hobots.log.info('nota', numero, 'ok')` — cada um vira texto, unidos por espaço. **Nunca lança** — pode ir em `finally`. |
 | `hobots.items.succeeded(payload?, { id }?)` · `.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`). 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 solicitação. Sem `total()` nada é enviado. |
 | `hobots.transaction.startChild(op, descrição)` | Uma **step** no waterfall de performance da execução. A transaction da execução já existe e é finalizada pelo SDK. |
 | `hobots.attach(imagem, { caption?, level? })` | Pendura um **print** (PNG/JPEG/WEBP, até 5 MB, 20 por execução) na linha de log. Nunca lança nem bloqueia. |

package/dist/chunk-5WIIACWC.js

@@ -0,0 +1,31 @@
+// protocol-limits.json
+var protocol_limits_default = {
+  MAX_ITEMS_PER_ENVELOPE: 50,
+  HEARTBEAT_DEFAULT_INTERVAL_MS: 3e4,
+  HEARTBEAT_MIN_INTERVAL_MS: 1e3,
+  HEARTBEAT_MAX_INTERVAL_MS: 9e5,
+  MAX_CLAIM_PER_POLL: 5,
+  MAX_LOG_MESSAGE_CHARS: 1e4,
+  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,
+  MAX_ITEM_COLUMNS: 12,
+  MAX_ITEM_COLUMN_LABEL_CHARS: 60,
+  MAX_ATTACHMENT_BYTES: 5242880,
+  MAX_ATTACHMENTS_PER_RUN: 20,
+  MAX_ATTACHMENTS_PER_LOG_ENTRY: 4,
+  MAX_CAPTION_CHARS: 200,
+  MAX_IMAGE_DIMENSION_PX: 2e4
+};
+
+// src/wire-limits.ts
+var WIRE_LIMITS = protocol_limits_default;
+
+export {
+  WIRE_LIMITS
+};
+//# sourceMappingURL=chunk-5WIIACWC.js.map

package/dist/chunk-5WIIACWC.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_RUN\": 10000,\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,mBAAqB;AAAA,EACrB,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;;;ACbO,IAAM,cAAc;","names":[]}

package/dist/index.cjs

@@ -95,7 +95,7 @@ function scrubSecrets(text) {
 
 // src/utils.ts
 var SDK_NAME = "hobots";
-var SDK_VERSION = true ? "3.2.2" : "0.0.0-dev";
+var SDK_VERSION = true ? "3.3.0" : "0.0.0-dev";
 function isNode() {
   return typeof process !== "undefined" && typeof process.versions?.node === "string";
 }
@@ -269,12 +269,39 @@ function eventFromException(error, type = "error") {
   };
 }
 
+// protocol-limits.json
+var protocol_limits_default = {
+  MAX_ITEMS_PER_ENVELOPE: 50,
+  HEARTBEAT_DEFAULT_INTERVAL_MS: 3e4,
+  HEARTBEAT_MIN_INTERVAL_MS: 1e3,
+  HEARTBEAT_MAX_INTERVAL_MS: 9e5,
+  MAX_CLAIM_PER_POLL: 5,
+  MAX_LOG_MESSAGE_CHARS: 1e4,
+  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,
+  MAX_ITEM_COLUMNS: 12,
+  MAX_ITEM_COLUMN_LABEL_CHARS: 60,
+  MAX_ATTACHMENT_BYTES: 5242880,
+  MAX_ATTACHMENTS_PER_RUN: 20,
+  MAX_ATTACHMENTS_PER_LOG_ENTRY: 4,
+  MAX_CAPTION_CHARS: 200,
+  MAX_IMAGE_DIMENSION_PX: 2e4
+};
+
+// src/wire-limits.ts
+var WIRE_LIMITS = protocol_limits_default;
+
 // src/transport.ts
 var REQUEST_TIMEOUT_MS = 1e4;
 var DEFAULT_FLUSH_INTERVAL_MS = 2e3;
 var DEFAULT_MAX_BATCH_SIZE = 10;
 var DEFAULT_MAX_QUEUE_SIZE = 200;
-var MAX_ITEMS_PER_ENVELOPE = 50;
+var MAX_ITEMS_PER_ENVELOPE = WIRE_LIMITS.MAX_ITEMS_PER_ENVELOPE;
 var Transport = class {
   endpoint;
   key;
@@ -598,9 +625,9 @@ async function fallbackInstanceId() {
 }
 
 // src/heartbeat.ts
-var DEFAULT_INTERVAL_MS = 3e4;
-var MIN_REPORTED_INTERVAL_MS = 1e3;
-var MAX_REPORTED_INTERVAL_MS = 9e5;
+var DEFAULT_INTERVAL_MS = WIRE_LIMITS.HEARTBEAT_DEFAULT_INTERVAL_MS;
+var MIN_REPORTED_INTERVAL_MS = WIRE_LIMITS.HEARTBEAT_MIN_INTERVAL_MS;
+var MAX_REPORTED_INTERVAL_MS = WIRE_LIMITS.HEARTBEAT_MAX_INTERVAL_MS;
 var Heartbeat = class {
   constructor(client, options = {}, instanceId, sampler) {
     this.client = client;
@@ -1160,6 +1187,88 @@ function isTerminalError(error) {
   return error instanceof Error && TERMINAL_ERROR_NAMES.has(error.name);
 }
 
+// src/tasks/each.ts
+function thrownMessage(error) {
+  if (error instanceof Error) return error.message || error.name;
+  return safeString(error);
+}
+var ItemHandle = class {
+  constructor(index, id, step, basePayload, sink) {
+    this.index = index;
+    this.id = id;
+    this.step = step;
+    this.basePayload = basePayload;
+    this.sink = sink;
+  }
+  index;
+  id;
+  step;
+  basePayload;
+  sink;
+  reported = false;
+  status;
+  succeeded(payload) {
+    this.record("succeeded", void 0, payload);
+  }
+  failed(message, payload) {
+    this.record("failed", message, payload);
+    if (this.step && this.step.status !== "error") this.step.setStatus("error", message);
+  }
+  occurrence(message, payload) {
+    this.record("occurrence", message, payload);
+    if (this.step && this.step.status === "ok") this.step.setStatus("warning", message);
+  }
+  record(status, message, payload) {
+    this.reported = true;
+    this.status = status;
+    const merged = { ...this.basePayload ?? {}, ...payload ?? {} };
+    this.sink.report(status, message, Object.keys(merged).length > 0 ? merged : void 0, this.id);
+  }
+};
+function resolveId(options, element, index) {
+  const raw = options.id?.(element, index);
+  if (raw === null || raw === void 0) return void 0;
+  const text = safeString(raw);
+  return text.length > 0 ? text : void 0;
+}
+function knownLength(list) {
+  const length = list?.length;
+  return typeof length === "number" && Number.isInteger(length) && length >= 1 ? length : void 0;
+}
+async function eachItem(list, handler, options, sink) {
+  const result = { total: 0, succeeded: 0, failed: 0, occurrence: 0 };
+  const length = options.progress === false ? void 0 : knownLength(list);
+  if (length !== void 0) sink.declareTotal(length);
+  let index = 0;
+  for await (const element of list) {
+    sink.checkCanceled();
+    const id = resolveId(options, element, index);
+    const description = options.description?.(element, index) ?? id ?? `#${index + 1}`;
+    const step = sink.startStep(options.op ?? "item", description);
+    const handle = new ItemHandle(index, id, step, options.payload?.(element, index), sink);
+    try {
+      await handler(element, handle, index);
+      if (!handle.reported) handle.succeeded();
+    } catch (error) {
+      if (isTerminalError(error) || sink.isAborted()) {
+        step?.setStatus("cancelled");
+        step?.finish();
+        throw error;
+      }
+      const message = thrownMessage(error);
+      if (!handle.reported) handle.failed(message);
+      step?.setError(error);
+      sink.logError(`item ${description} falhou: ${message}`);
+    }
+    step?.finish();
+    if (options.progress !== false) sink.advance();
+    result.total += 1;
+    result[handle.status ?? "succeeded"] += 1;
+    index += 1;
+  }
+  return result;
+}
+
 // src/retry.ts
 var DEFAULT_RETRIES = 3;
 var DEFAULT_DELAY_MS = 1e3;
@@ -1187,10 +1296,11 @@ async function retryWithBackoff(fn, options = {}) {
 }
 
 // src/tasks/attachments.ts
-var MAX_ATTACHMENT_BYTES = 5242880;
-var MAX_ATTACHMENTS_PER_RUN = 20;
+var MAX_ATTACHMENT_BYTES = WIRE_LIMITS.MAX_ATTACHMENT_BYTES;
+var MAX_ATTACHMENTS_PER_RUN = WIRE_LIMITS.MAX_ATTACHMENTS_PER_RUN;
+var MAX_ATTACHMENTS_PER_LOG_ENTRY = WIRE_LIMITS.MAX_ATTACHMENTS_PER_LOG_ENTRY;
 var MAX_CONCURRENT_UPLOADS = 3;
-var MAX_CAPTION_CHARS = 200;
+var MAX_CAPTION_CHARS = WIRE_LIMITS.MAX_CAPTION_CHARS;
 var ATTACHMENT_DRAIN_MS = 15e3;
 async function readImageFile(path) {
   if (!isNode()) {
@@ -1204,7 +1314,7 @@ function startsWith(bytes, signature, offset = 0) {
   return signature.every((byte, index) => bytes[offset + index] === byte);
 }
 var PNG_MAGIC = [137, 80, 78, 71, 13, 10, 26, 10];
-var MAX_PNG_DIMENSION = 2e4;
+var MAX_PNG_DIMENSION = WIRE_LIMITS.MAX_IMAGE_DIMENSION_PX;
 var JPEG_MAGIC = [255, 216, 255];
 var RIFF_MAGIC = [82, 73, 70, 70];
 var WEBP_MAGIC = [87, 69, 66, 80];
@@ -1267,13 +1377,13 @@ var DEFAULT_LOG_FLUSH_INTERVAL_MS = 2e3;
 var DEFAULT_CANCEL_CHECK_INTERVAL_MS = 5e3;
 var MIN_CANCEL_CHECK_INTERVAL_MS = 1e3;
 var MAX_CANCEL_CHECK_INTERVAL_MS = 15e3;
-var MAX_LOG_MESSAGE_CHARS = 1e4;
-var MAX_LOGS_PER_PATCH = 100;
+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 = 1e4;
-var MAX_ITEMS_PER_REQUEST = 500;
-var MAX_ITEM_MESSAGE_CHARS = 2e3;
-var MAX_ITEM_PAYLOAD_BYTES = 16384;
+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;
 var ITEMS_FLUSH_AT_BUFFERED = 100;
 var ITEMS_DRAIN_MS = 15e3;
 var PROGRESS_FLUSH_MS = 1e3;
@@ -1307,6 +1417,17 @@ var RunReporter = class {
     tx.setLifecycleSink((level, message) => this.push(level, message));
     const checkCanceled = () => this.checkCanceled();
     tx.setStepGuard(checkCanceled);
+    const eachSink = {
+      report: (status, message, payload, id) => this.addItem(status, message, payload, id),
+      startStep: (op, description) => tx.startChild(op, description),
+      declareTotal: (total) => {
+        if (this.progressTotal == null) this.setProgress(this.progressCurrent, total);
+      },
+      advance: () => this.setProgress(this.progressCurrent + 1, this.progressTotal),
+      checkCanceled,
+      isAborted: () => this.abortController.signal.aborted,
+      logError: (message) => this.log("error", message)
+    };
     const items = {
       add: (item) => {
         checkCanceled();
@@ -1323,7 +1444,8 @@ var RunReporter = class {
       occurrence: (message, payload, options) => {
         checkCanceled();
         this.addItem("occurrence", message, payload, options?.id);
-      }
+      },
+      each: (list, handler, options = {}) => eachItem(list, handler, options, eachSink)
     };
     const progress = Object.defineProperties(
       {
@@ -1468,7 +1590,7 @@ var RunReporter = class {
       ts,
       level,
       message: truncate(scrubbed, MAX_LOG_MESSAGE_CHARS),
-      ...attachments && attachments.length > 0 ? { attachments } : {}
+      ...attachments && attachments.length > 0 ? { attachments: attachments.slice(0, WIRE_LIMITS.MAX_ATTACHMENTS_PER_LOG_ENTRY) } : {}
     });
     if (this.buffer.length >= FLUSH_AT_BUFFERED) {
       this.flushLogs();
@@ -2169,6 +2291,7 @@ async function executeRun(input) {
       await runWithRunContext({ reporter }, () => invokeWithRetry(task, run, reporter, logger));
       await reporter.finalizeAttachments();
       await reporter.finalizeItems();
+      warnIncompleteProgress(reporter);
       tx.setStatus("ok");
       tx.finish();
       reporter.reportSuccess();
@@ -2186,6 +2309,13 @@ async function executeRun(input) {
     tracker.remove(reporter);
   }
 }
+function warnIncompleteProgress(reporter) {
+  const snapshot = reporter.context.progress.snapshot;
+  if (!snapshot || snapshot.current >= snapshot.total) return;
+  reporter.context.log.warn(
+    `execu\xE7\xE3o conclu\xEDda com progresso incompleto: ${snapshot.current}/${snapshot.total} \u2014 o handler terminou sem processar (ou sem avan\xE7ar) todos os itens previstos`
+  );
+}
 function invokeWithRetry(task, run, reporter, logger) {
   const { retries, retryDelayMs } = task.options;
   const total = retries + 1;
@@ -2240,8 +2370,8 @@ function waitForCancelGrace(signal, graceMs) {
     signal.addEventListener("abort", () => setTimeout(resolve2, graceMs), { once: true });
   });
 }
-var MAX_ERROR_MESSAGE_CHARS = 1e4;
-var MAX_ERROR_STACK_CHARS = 2e4;
+var MAX_ERROR_MESSAGE_CHARS = WIRE_LIMITS.MAX_ERROR_MESSAGE_CHARS;
+var MAX_ERROR_STACK_CHARS = WIRE_LIMITS.MAX_ERROR_STACK_CHARS;
 function toRunError(error) {
   if (error instanceof Error) {
     return {
@@ -2256,7 +2386,7 @@ function toRunError(error) {
 // src/tasks/agent.ts
 var DEFAULT_POLL_INTERVAL_MS = 2e3;
 var MIN_POLL_INTERVAL_MS = 1e3;
-var MAX_CLAIM_PER_POLL = 5;
+var MAX_CLAIM_PER_POLL = WIRE_LIMITS.MAX_CLAIM_PER_POLL;
 var TaskAgent = class {
   constructor(options) {
     this.options = options;
@@ -2391,8 +2521,8 @@ var TaskAgent = class {
 
 // src/tasks/item-columns.ts
 var KEY_RE = /^[a-zA-Z0-9_.-]{1,100}$/;
-var MAX_COLUMNS = 12;
-var MAX_LABEL_CHARS = 60;
+var MAX_COLUMNS = WIRE_LIMITS.MAX_ITEM_COLUMNS;
+var MAX_LABEL_CHARS = WIRE_LIMITS.MAX_ITEM_COLUMN_LABEL_CHARS;
 function normalizeItemColumns(slug, input, logger) {
   if (input === void 0 || input === null) return void 0;
   const columns = input.columns;
@@ -2900,7 +3030,22 @@ var fallbackLog = {
   success: (message, ...rest) => printRunLog(FALLBACK_TASK, "success", joinLogArgs(message, rest))
 };
 var noop = () => void 0;
-var fallbackItems = { add: noop, succeeded: noop, failed: noop, occurrence: noop };
+var fallbackEachSink = {
+  report: noop,
+  startStep: () => void 0,
+  declareTotal: noop,
+  advance: noop,
+  checkCanceled: noop,
+  isAborted: () => false,
+  logError: (message) => printRunLog(FALLBACK_TASK, "error", message)
+};
+var fallbackItems = {
+  add: noop,
+  succeeded: noop,
+  failed: noop,
+  occurrence: noop,
+  each: (list, handler, options = {}) => eachItem(list, handler, options, fallbackEachSink)
+};
 var fallbackProgress = { total: noop, advance: noop, set: noop, current: 0, snapshot: null };
 var neverAborts = new AbortController().signal;
 var detachedTransaction;