hobots 3.2.1 → 3.3.0

package/dist/index.d.cts

@@ -256,7 +256,18 @@ declare class Step {
     endTimestamp?: string;
     data?: Record<string, unknown>;
     constructor(transaction: Transaction, parentStepId: string, op?: string | undefined, description?: string | undefined);
-    setStatus(status: StepStatus): this;
+    /**
+     * Desfecho da step. `message` (opcional) é o motivo legível — vai em `data.message`
+     * e aparece na Central (performance e banner da execução) e no log de FINISH.
+     */
+    setStatus(status: StepStatus, message?: string): this;
+    /**
+     * Marca a step como `error` guardando o motivo em `data.error` ({ type, message }).
+     * Aceita qualquer valor lançado; `message` sobrescreve a mensagem do erro.
+     */
+    setError(error: unknown, message?: string): this;
+    /** Motivo registrado via setStatus(…, message) ou setError — usado no log de FINISH. */
+    private reason;
     setData(key: string, value: unknown): this;
     /** Step aninhada (filha desta step). */
     startChild(op?: string, description?: string): Step;
@@ -292,7 +303,7 @@ declare class Transaction {
      * 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: 'transaction' | 'step', phase: 'start' | 'finish', label: string, startTs?: string, endTs?: string, status?: StepStatus | string): void;
+    emit(kind: 'transaction' | 'step', phase: 'start' | 'finish', label: string, startTs?: string, endTs?: string, status?: StepStatus | string, reason?: string): void;
     /** Conecta o espelho de lifecycle (RunReporter) e faz replay do backlog em ordem. */
     setLifecycleSink(sink: LifecycleSink): void;
     /**
@@ -328,6 +339,51 @@ interface RunItemOptions {
      */
     id?: string;
 }
+/**
+ * O item em processamento dentro de `items.each`: o desfecho (`succeeded`/`failed`/
+ * `occurrence`) com o `id` e o payload base já resolvidos, e a step da etapa para quem
+ * quiser medir sub-etapas (`item.step.startChild(...)`). Sem chamada explícita, o SDK
+ * decide: retornou → `succeeded`; lançou → `failed` com a mensagem do erro.
+ */
+interface RunItemHandle {
+    /** Posição do elemento na lista (0-based). */
+    readonly index: number;
+    /** Identidade de negócio resolvida por `options.id` (undefined = o SDK gera uma). */
+    readonly id: string | undefined;
+    /** Step desta etapa no waterfall de performance; undefined fora de uma execução. */
+    readonly step: Step | undefined;
+    /** true depois do primeiro desfecho registrado (o SDK não sobrescreve o que o handler decidiu). */
+    readonly reported: boolean;
+    /** Item processado com sucesso. `payload` é mesclado sobre o payload base de `options.payload`. */
+    succeeded(payload?: Record<string, unknown>): void;
+    /** Falha sem lançar — o loop segue igual; a step vira `error` com o motivo. */
+    failed(message: string, payload?: Record<string, unknown>): void;
+    /** Ocorrência de negócio — a step vira `warning` com o motivo. */
+    occurrence(message: string, payload?: Record<string, unknown>): void;
+}
+interface RunItemsEachOptions<T> {
+    /** Identidade de negócio do item (ex.: nº do cliente). Omitido/null: o SDK gera um id único. */
+    id?: (element: T, index: number) => string | number | null | undefined;
+    /** Atributos base do item (viram colunas no app) — presentes em qualquer desfecho, inclusive falha. */
+    payload?: (element: T, index: number) => Record<string, unknown> | undefined;
+    /** `op` da step de cada item no waterfall. Default: 'item'. */
+    op?: string;
+    /** Descrição da step de cada item. Default: o `id`, senão `#<posição>`. */
+    description?: (element: T, index: number) => string;
+    /**
+     * Progresso automático: declara o total (tamanho da lista, se o bot ainda não declarou um)
+     * e avança a cada elemento. `false` deixa o progresso por conta do bot. Default: true.
+     */
+    progress?: boolean;
+}
+/** Totalizadores do `items.each`, pelo desfecho final de cada elemento. */
+interface RunItemsEachResult {
+    total: number;
+    succeeded: number;
+    failed: number;
+    occurrence: number;
+}
+type RunItemsEachHandler<T> = (element: T, item: RunItemHandle, index: number) => unknown;
 /**
  * Registro dos itens que a execução processou/gerou (a entrega do bot: notas
  * fiscais baixadas, boletos emitidos...). Chamadas são síncronas — os itens são
@@ -348,6 +404,15 @@ interface RunItems {
     failed(message: string, payload?: Record<string, unknown>, options?: RunItemOptions): void;
     /** Ocorrência de negócio (ex.: "nota nº 10 não encontrada") — não é falha do bot. */
     occurrence(message: string, payload?: Record<string, unknown>, options?: RunItemOptions): void;
+    /**
+     * Processa uma lista item a item com o contrato da plataforma garantido pelo SDK: cada
+     * elemento vira uma step e um item; uma exceção no handler registra o item como `failed`
+     * (com a mensagem do erro), marca a step com `setError` e **segue para o próximo** — a
+     * lista inteira é processada, e o progresso avança a cada elemento. Só cancelamento,
+     * timeout e shutdown interrompem o loop (o erro sobe como em qualquer ponto de parada).
+     * Resolve com os totalizadores por desfecho.
+     */
+    each<T>(list: Iterable<T> | AsyncIterable<T>, handler: RunItemsEachHandler<T>, options?: RunItemsEachOptions<T>): Promise<RunItemsEachResult>;
 }
 /**
  * Progresso da execução (itens processados / total) — opcional e independente de
@@ -434,4 +499,4 @@ declare const close: (timeoutMs?: number) => Promise<boolean>;
 declare const captureException: (error: unknown, hint?: CaptureHint) => string | undefined;
 declare const retry: <T>(fn: (attempt: number) => T | Promise<T>, options?: RetryOptions) => Promise<T>;
 
-export { type AttachFailureReason, type AttachInput, type AttachOptions, type AttachResult, type CaptureAttachment, type CaptureHint, EnvironmentInput, EventPayload, EventType, HeartbeatPayload, type Hobots, type HobotsOptions, type ItemColumnInput, MachineSnapshot, type RegisterOptions, type RetryDelay, type RetryOptions, RunAttachmentContentType, type RunContext, type RunItemOptions, RunItemStatus, type RunItems, RunLogLevel, type RunLogger, RunProgress, type RunProgressReporter, type StartOptions, Step, StepData, StepStatus, type TaskHandler, type TaskItemsOptions, type TaskOptions, Transaction, TransactionPayload, captureException, close, hobots as default, hobots, register, retry, start };
+export { type AttachFailureReason, type AttachInput, type AttachOptions, type AttachResult, type CaptureAttachment, type CaptureHint, EnvironmentInput, EventPayload, EventType, HeartbeatPayload, type Hobots, type HobotsOptions, type ItemColumnInput, MachineSnapshot, type RegisterOptions, type RetryDelay, type RetryOptions, RunAttachmentContentType, type RunContext, type RunItemHandle, type RunItemOptions, RunItemStatus, type RunItems, type RunItemsEachHandler, type RunItemsEachOptions, type RunItemsEachResult, RunLogLevel, type RunLogger, RunProgress, type RunProgressReporter, type StartOptions, Step, StepData, StepStatus, type TaskHandler, type TaskItemsOptions, type TaskOptions, Transaction, TransactionPayload, captureException, close, hobots as default, hobots, register, retry, start };

package/dist/index.d.ts

@@ -256,7 +256,18 @@ declare class Step {
     endTimestamp?: string;
     data?: Record<string, unknown>;
     constructor(transaction: Transaction, parentStepId: string, op?: string | undefined, description?: string | undefined);
-    setStatus(status: StepStatus): this;
+    /**
+     * Desfecho da step. `message` (opcional) é o motivo legível — vai em `data.message`
+     * e aparece na Central (performance e banner da execução) e no log de FINISH.
+     */
+    setStatus(status: StepStatus, message?: string): this;
+    /**
+     * Marca a step como `error` guardando o motivo em `data.error` ({ type, message }).
+     * Aceita qualquer valor lançado; `message` sobrescreve a mensagem do erro.
+     */
+    setError(error: unknown, message?: string): this;
+    /** Motivo registrado via setStatus(…, message) ou setError — usado no log de FINISH. */
+    private reason;
     setData(key: string, value: unknown): this;
     /** Step aninhada (filha desta step). */
     startChild(op?: string, description?: string): Step;
@@ -292,7 +303,7 @@ declare class Transaction {
      * 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: 'transaction' | 'step', phase: 'start' | 'finish', label: string, startTs?: string, endTs?: string, status?: StepStatus | string): void;
+    emit(kind: 'transaction' | 'step', phase: 'start' | 'finish', label: string, startTs?: string, endTs?: string, status?: StepStatus | string, reason?: string): void;
     /** Conecta o espelho de lifecycle (RunReporter) e faz replay do backlog em ordem. */
     setLifecycleSink(sink: LifecycleSink): void;
     /**
@@ -328,6 +339,51 @@ interface RunItemOptions {
      */
     id?: string;
 }
+/**
+ * O item em processamento dentro de `items.each`: o desfecho (`succeeded`/`failed`/
+ * `occurrence`) com o `id` e o payload base já resolvidos, e a step da etapa para quem
+ * quiser medir sub-etapas (`item.step.startChild(...)`). Sem chamada explícita, o SDK
+ * decide: retornou → `succeeded`; lançou → `failed` com a mensagem do erro.
+ */
+interface RunItemHandle {
+    /** Posição do elemento na lista (0-based). */
+    readonly index: number;
+    /** Identidade de negócio resolvida por `options.id` (undefined = o SDK gera uma). */
+    readonly id: string | undefined;
+    /** Step desta etapa no waterfall de performance; undefined fora de uma execução. */
+    readonly step: Step | undefined;
+    /** true depois do primeiro desfecho registrado (o SDK não sobrescreve o que o handler decidiu). */
+    readonly reported: boolean;
+    /** Item processado com sucesso. `payload` é mesclado sobre o payload base de `options.payload`. */
+    succeeded(payload?: Record<string, unknown>): void;
+    /** Falha sem lançar — o loop segue igual; a step vira `error` com o motivo. */
+    failed(message: string, payload?: Record<string, unknown>): void;
+    /** Ocorrência de negócio — a step vira `warning` com o motivo. */
+    occurrence(message: string, payload?: Record<string, unknown>): void;
+}
+interface RunItemsEachOptions<T> {
+    /** Identidade de negócio do item (ex.: nº do cliente). Omitido/null: o SDK gera um id único. */
+    id?: (element: T, index: number) => string | number | null | undefined;
+    /** Atributos base do item (viram colunas no app) — presentes em qualquer desfecho, inclusive falha. */
+    payload?: (element: T, index: number) => Record<string, unknown> | undefined;
+    /** `op` da step de cada item no waterfall. Default: 'item'. */
+    op?: string;
+    /** Descrição da step de cada item. Default: o `id`, senão `#<posição>`. */
+    description?: (element: T, index: number) => string;
+    /**
+     * Progresso automático: declara o total (tamanho da lista, se o bot ainda não declarou um)
+     * e avança a cada elemento. `false` deixa o progresso por conta do bot. Default: true.
+     */
+    progress?: boolean;
+}
+/** Totalizadores do `items.each`, pelo desfecho final de cada elemento. */
+interface RunItemsEachResult {
+    total: number;
+    succeeded: number;
+    failed: number;
+    occurrence: number;
+}
+type RunItemsEachHandler<T> = (element: T, item: RunItemHandle, index: number) => unknown;
 /**
  * Registro dos itens que a execução processou/gerou (a entrega do bot: notas
  * fiscais baixadas, boletos emitidos...). Chamadas são síncronas — os itens são
@@ -348,6 +404,15 @@ interface RunItems {
     failed(message: string, payload?: Record<string, unknown>, options?: RunItemOptions): void;
     /** Ocorrência de negócio (ex.: "nota nº 10 não encontrada") — não é falha do bot. */
     occurrence(message: string, payload?: Record<string, unknown>, options?: RunItemOptions): void;
+    /**
+     * Processa uma lista item a item com o contrato da plataforma garantido pelo SDK: cada
+     * elemento vira uma step e um item; uma exceção no handler registra o item como `failed`
+     * (com a mensagem do erro), marca a step com `setError` e **segue para o próximo** — a
+     * lista inteira é processada, e o progresso avança a cada elemento. Só cancelamento,
+     * timeout e shutdown interrompem o loop (o erro sobe como em qualquer ponto de parada).
+     * Resolve com os totalizadores por desfecho.
+     */
+    each<T>(list: Iterable<T> | AsyncIterable<T>, handler: RunItemsEachHandler<T>, options?: RunItemsEachOptions<T>): Promise<RunItemsEachResult>;
 }
 /**
  * Progresso da execução (itens processados / total) — opcional e independente de
@@ -434,4 +499,4 @@ declare const close: (timeoutMs?: number) => Promise<boolean>;
 declare const captureException: (error: unknown, hint?: CaptureHint) => string | undefined;
 declare const retry: <T>(fn: (attempt: number) => T | Promise<T>, options?: RetryOptions) => Promise<T>;
 
-export { type AttachFailureReason, type AttachInput, type AttachOptions, type AttachResult, type CaptureAttachment, type CaptureHint, EnvironmentInput, EventPayload, EventType, HeartbeatPayload, type Hobots, type HobotsOptions, type ItemColumnInput, MachineSnapshot, type RegisterOptions, type RetryDelay, type RetryOptions, RunAttachmentContentType, type RunContext, type RunItemOptions, RunItemStatus, type RunItems, RunLogLevel, type RunLogger, RunProgress, type RunProgressReporter, type StartOptions, Step, StepData, StepStatus, type TaskHandler, type TaskItemsOptions, type TaskOptions, Transaction, TransactionPayload, captureException, close, hobots as default, hobots, register, retry, start };
+export { type AttachFailureReason, type AttachInput, type AttachOptions, type AttachResult, type CaptureAttachment, type CaptureHint, EnvironmentInput, EventPayload, EventType, HeartbeatPayload, type Hobots, type HobotsOptions, type ItemColumnInput, MachineSnapshot, type RegisterOptions, type RetryDelay, type RetryOptions, RunAttachmentContentType, type RunContext, type RunItemHandle, type RunItemOptions, RunItemStatus, type RunItems, type RunItemsEachHandler, type RunItemsEachOptions, type RunItemsEachResult, RunLogLevel, type RunLogger, RunProgress, type RunProgressReporter, type StartOptions, Step, StepData, StepStatus, type TaskHandler, type TaskItemsOptions, type TaskOptions, Transaction, TransactionPayload, captureException, close, hobots as default, hobots, register, retry, start };

package/dist/index.js

@@ -1,3 +1,7 @@
+import {
+  WIRE_LIMITS
+} from "./chunk-5WIIACWC.js";
+
 // src/stacktrace.ts
 var MAX_FRAMES = 50;
 var MAX_FILENAME_CHARS = 1024;
@@ -53,7 +57,7 @@ function scrubSecrets(text) {
 
 // src/utils.ts
 var SDK_NAME = "hobots";
-var SDK_VERSION = true ? "3.2.0" : "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";
 }
@@ -232,7 +236,7 @@ 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;
@@ -556,9 +560,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;
@@ -569,6 +573,8 @@ var Heartbeat = class {
     this.metadata = options.metadata;
     this.keepAlive = options.keepAlive ?? false;
   }
+  client;
+  sampler;
   intervalMs;
   instanceId;
   name;
@@ -705,6 +711,8 @@ var MachineSampler = class {
     this.instanceId = instanceId;
     this.logger = logger;
   }
+  instanceId;
+  logger;
   os;
   fs;
   ready = false;
@@ -832,6 +840,7 @@ var TasksApiError = class extends Error {
     this.status = status;
     this.name = "TasksApiError";
   }
+  status;
 };
 async function withRequestTimeout(timeoutMs, external, send) {
   const { signal, cleanup } = withTimeoutSignal(timeoutMs, external);
@@ -1072,6 +1081,9 @@ var Backoff = class {
     this.label = label;
     this.floorMs = floorMs;
   }
+  logger;
+  label;
+  floorMs;
   failures = 0;
   authFailures = 0;
   reset() {
@@ -1110,6 +1122,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;
@@ -1137,10 +1231,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()) {
@@ -1154,7 +1249,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];
@@ -1217,13 +1312,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;
@@ -1257,6 +1352,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();
@@ -1273,7 +1379,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(
       {
@@ -1316,6 +1423,9 @@ var RunReporter = class {
       retry: (fn, options) => retryWithBackoff(fn, { ...options, signal, wait: sleep2 })
     };
   }
+  api;
+  runId;
+  logger;
   context;
   buffer = [];
   dead = false;
@@ -1415,7 +1525,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();
@@ -1640,6 +1750,7 @@ var RunReporter = class {
       }
       if (error instanceof TasksApiError) {
         this.logger.error(`lote de ${batch.length} item(ns) rejeitado pelo servidor:`, error);
+        this.log("warning", `${batch.length} item(ns) descartado(s): envio rejeitado pelo servidor (HTTP ${error.status})`);
         return;
       }
       this.itemsBuffer.unshift(...batch);
@@ -1866,6 +1977,10 @@ function currentRunReporter() {
 }
 
 // src/transaction.ts
+var MAX_STEP_MESSAGE_CHARS = 2e3;
+function stepMessage(text) {
+  return truncate(scrubSecrets(text), MAX_STEP_MESSAGE_CHARS);
+}
 function stepId() {
   return uuid4().slice(0, 16);
 }
@@ -1903,15 +2018,41 @@ var Step = class {
     this.op = op;
     this.description = description;
   }
+  transaction;
+  parentStepId;
+  op;
+  description;
   stepId = stepId();
   startTimestamp = nowISO();
   status = "ok";
   endTimestamp;
   data;
-  setStatus(status) {
+  /**
+   * Desfecho da step. `message` (opcional) é o motivo legível — vai em `data.message`
+   * e aparece na Central (performance e banner da execução) e no log de FINISH.
+   */
+  setStatus(status, message) {
     this.status = status;
+    if (message) this.setData("message", stepMessage(message));
+    return this;
+  }
+  /**
+   * Marca a step como `error` guardando o motivo em `data.error` ({ type, message }).
+   * Aceita qualquer valor lançado; `message` sobrescreve a mensagem do erro.
+   */
+  setError(error, message) {
+    this.status = "error";
+    const type = error instanceof Error ? error.name : typeof error === "object" && error !== null ? "Error" : void 0;
+    const raw = message ?? (error instanceof Error ? error.message || error.name : String(error));
+    this.setData("error", { ...type ? { type } : {}, message: stepMessage(raw) });
     return this;
   }
+  /** Motivo registrado via setStatus(…, message) ou setError — usado no log de FINISH. */
+  reason() {
+    const error = this.data?.error;
+    const text = typeof error?.message === "string" ? error.message : this.data?.message;
+    return typeof text === "string" && text ? text : void 0;
+  }
   setData(key, value) {
     this.data = { ...this.data, [key]: value };
     return this;
@@ -1929,7 +2070,8 @@ var Step = class {
       stepLabel(this.op, this.description),
       this.startTimestamp,
       this.endTimestamp,
-      this.status
+      this.status,
+      this.reason()
     );
   }
   toJSON() {
@@ -1953,6 +2095,10 @@ var Transaction = class {
     this.runId = runId;
     this.emit("transaction", "start", op ? `${name} (${op})` : name);
   }
+  client;
+  name;
+  op;
+  runId;
   eventId = uuid4();
   stepId = stepId();
   startTimestamp = nowISO();
@@ -1972,9 +2118,9 @@ var Transaction = class {
    * 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) {
+  emit(kind, phase, label, startTs, endTs, status, reason) {
     const durationMs = startTs && endTs ? new Date(endTs).getTime() - new Date(startTs).getTime() : void 0;
-    const suffix = durationMs != null ? ` (${durationMs}ms)` : "";
+    const suffix = (durationMs != null ? ` (${durationMs}ms)` : "") + (reason ? `: ${reason}` : "");
     if (this.client?.debug) {
       const tag = colorize(`[hobots:${kind}] ${phase.toUpperCase()}`, phase === "finish" ? colorForStatus(status ?? "ok") : "cyan");
       console.log(`${tag} ${label}${suffix}`);
@@ -2080,6 +2226,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();
@@ -2097,6 +2244,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;
@@ -2151,8 +2305,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 {
@@ -2167,7 +2321,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;
@@ -2179,6 +2333,7 @@ var TaskAgent = class {
     this.pollIntervalMs = Math.max(MIN_POLL_INTERVAL_MS, options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS);
     this.backoff = new Backoff(this.logger, "poll", this.pollIntervalMs);
   }
+  options;
   logger;
   pollIntervalMs;
   api;
@@ -2301,8 +2456,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;
@@ -2345,6 +2500,8 @@ var LocalRunner = class {
       this.resolveDone = resolve2;
     });
   }
+  task;
+  deps;
   abort = new AbortController();
   backoff;
   /** Resolve quando a run terminou (ou o runner foi parado antes de abri-la). */
@@ -2430,6 +2587,7 @@ var RunTracker = class {
   constructor(api) {
     this.api = api;
   }
+  api;
   reporters = /* @__PURE__ */ new Set();
   waiters = /* @__PURE__ */ new Set();
   add(reporter) {
@@ -2807,7 +2965,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;