hobots 3.2.2 → 3.4.0

package/dist/index.cjs

@@ -34,6 +34,7 @@ __export(src_exports, {
   close: () => close2,
   default: () => src_default,
   hobots: () => hobots,
+  image: () => image2,
   register: () => register2,
   retry: () => retry,
   start: () => start2
@@ -95,7 +96,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.4.0" : "0.0.0-dev";
 function isNode() {
   return typeof process !== "undefined" && typeof process.versions?.node === "string";
 }
@@ -269,12 +270,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;
@@ -350,6 +378,7 @@ var Transport = class {
     try {
       response = await fetchWithRetry(
         () => fetch(this.endpoint, {
+          redirect: "error",
           method: "POST",
           headers: { "content-type": "application/json", authorization: `Bearer ${this.key}` },
           body: JSON.stringify(envelope),
@@ -527,7 +556,6 @@ function envBaseUrl() {
 function isLoopbackHost(hostname2) {
   return hostname2 === "localhost" || hostname2.endsWith(".localhost") || hostname2.startsWith("127.") || hostname2 === "[::1]" || hostname2 === "::1" || hostname2 === "0.0.0.0";
 }
-var warnedInsecureBaseUrl = false;
 function validateBaseUrl(raw, prefix) {
   let url;
   try {
@@ -541,11 +569,8 @@ function validateBaseUrl(raw, prefix) {
   if (url.username || url.password) {
     throw new Error(`${prefix} HOBOTS_API_URL n\xE3o pode conter credenciais na URL \u2014 a autentica\xE7\xE3o \xE9 s\xF3 pelo Client Secret`);
   }
-  if (url.protocol === "http:" && !isLoopbackHost(url.hostname) && !warnedInsecureBaseUrl) {
-    warnedInsecureBaseUrl = true;
-    console.warn(
-      `${prefix} HOBOTS_API_URL usa http para o host remoto "${url.hostname}" \u2014 o Client Secret trafega sem TLS`
-    );
+  if (url.protocol === "http:" && !isLoopbackHost(url.hostname)) {
+    throw new Error(`${prefix} HOBOTS_API_URL usa http para o host remoto "${url.hostname}" \u2014 o Client Secret trafegaria sem TLS; use https`);
   }
   return raw.replace(/\/+$/, "");
 }
@@ -598,9 +623,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;
@@ -909,6 +934,7 @@ var TasksApi = class {
     let response;
     try {
       response = await fetch(`${this.baseUrl}/poll`, {
+        redirect: "error",
         method: "POST",
         headers: this.headers(),
         body: JSON.stringify(request),
@@ -932,6 +958,7 @@ var TasksApi = class {
     let response;
     try {
       response = await fetch(`${this.baseUrl}/runs`, {
+        redirect: "error",
         method: "POST",
         headers: this.headers(),
         body: JSON.stringify(request),
@@ -982,6 +1009,7 @@ var TasksApi = class {
     try {
       response = await fetchWithRetry(
         () => fetch(`${this.baseUrl}/runs/${encodeURIComponent(runId)}`, {
+          redirect: "error",
           method: "PATCH",
           headers: this.headers(),
           body: JSON.stringify(update),
@@ -1003,6 +1031,7 @@ var TasksApi = class {
    */
   async updateRunOnce(runId, update, timeoutMs = 2e3) {
     await fetch(`${this.baseUrl}/runs/${encodeURIComponent(runId)}`, {
+      redirect: "error",
       method: "PATCH",
       headers: this.headers(),
       body: JSON.stringify(update),
@@ -1019,6 +1048,7 @@ var TasksApi = class {
     try {
       response = await fetchWithRetry(
         () => fetch(`${this.baseUrl}/runs/${encodeURIComponent(runId)}/items`, {
+          redirect: "error",
           method: "POST",
           headers: this.headers(),
           body: JSON.stringify(request),
@@ -1048,6 +1078,7 @@ var TasksApi = class {
         UPDATE_TIMEOUT_MS,
         signal,
         (timeoutSignal) => fetch(`${this.baseUrl}/runs/${encodeURIComponent(runId)}/attachments`, {
+          redirect: "error",
           method: "POST",
           headers: this.headers(),
           body: JSON.stringify(request),
@@ -1080,6 +1111,7 @@ var TasksApi = class {
         UPLOAD_TIMEOUT_MS,
         signal,
         (timeoutSignal) => fetch(url, {
+          redirect: "error",
           method: "PUT",
           headers,
           // BodyInit não aceita Uint8Array<ArrayBufferLike> em todos os lib.dom; o buffer é o mesmo
@@ -1098,6 +1130,7 @@ var TasksApi = class {
     const response = await fetch(
       `${this.baseUrl}/runs/${encodeURIComponent(runId)}/attachments/${encodeURIComponent(attachmentId)}`,
       {
+        redirect: "error",
         method: "PATCH",
         headers: this.headers(),
         body: JSON.stringify(request),
@@ -1160,6 +1193,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, options) {
+    this.record("succeeded", void 0, payload, options?.image);
+  }
+  failed(message, payload, options) {
+    this.record("failed", message, payload, options?.image);
+    if (this.step && this.step.status !== "error") this.step.setStatus("error", message);
+  }
+  occurrence(message, payload, options) {
+    this.record("occurrence", message, payload, options?.image);
+    if (this.step && this.step.status === "ok") this.step.setStatus("warning", message);
+  }
+  record(status, message, payload, image3) {
+    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, image3);
+  }
+};
+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,11 +1302,33 @@ 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;
+var IMAGE_BRAND = /* @__PURE__ */ Symbol.for("hobots.image");
+var ImageAttachment = class {
+  constructor(input, caption, contentType) {
+    this.input = input;
+    this.caption = caption;
+    this.contentType = contentType;
+  }
+  input;
+  caption;
+  contentType;
+  [IMAGE_BRAND] = true;
+};
+function image(input, options = {}) {
+  return new ImageAttachment(input, options.caption, options.contentType);
+}
+function isImageAttachment(value) {
+  return typeof value === "object" && value !== null && value[IMAGE_BRAND] === true;
+}
+function toImageAttachment(value) {
+  return isImageAttachment(value) ? value : new ImageAttachment(value);
+}
 async function readImageFile(path) {
   if (!isNode()) {
     throw new Error("caminho de arquivo s\xF3 \xE9 suportado em Node");
@@ -1204,7 +1341,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];
@@ -1241,6 +1378,14 @@ function joinLogArgs(message, rest) {
   if (rest.length === 0) return safeString(message);
   return [message, ...rest].map(safeString).join(" ");
 }
+function splitLogArgs(message, rest) {
+  const args = [message, ...rest];
+  const last = args[args.length - 1];
+  if (!isImageAttachment(last)) return { text: joinLogArgs(message, rest) };
+  const text = args.slice(0, -1);
+  if (text.length === 0) return { text: last.caption !== void 0 ? safeString(last.caption) : "captura de tela", image: last };
+  return { text: joinLogArgs(text[0], text.slice(1)), image: last };
+}
 function printRunLog(task, level, message) {
   const line = colorize(`[hobots:${task}] ${level.toUpperCase()}`, LOG_LEVEL_COLOR[level]);
   const method2 = level === "warning" ? "warn" : level === "success" ? "info" : level;
@@ -1267,13 +1412,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;
@@ -1297,33 +1442,50 @@ var RunReporter = class {
       MAX_CANCEL_CHECK_INTERVAL_MS,
       Math.max(MIN_CANCEL_CHECK_INTERVAL_MS, cancelCheckIntervalMs ?? DEFAULT_CANCEL_CHECK_INTERVAL_MS)
     );
+    const logAt = (level) => (message, ...rest) => {
+      const { text, image: image3 } = splitLogArgs(message, rest);
+      this.log(level, text, image3);
+    };
     const log = {
-      debug: (message, ...rest) => this.log("debug", joinLogArgs(message, rest)),
-      info: (message, ...rest) => this.log("info", joinLogArgs(message, rest)),
-      warn: (message, ...rest) => this.log("warning", joinLogArgs(message, rest)),
-      error: (message, ...rest) => this.log("error", joinLogArgs(message, rest)),
-      success: (message, ...rest) => this.log("success", joinLogArgs(message, rest))
+      debug: logAt("debug"),
+      info: logAt("info"),
+      warn: logAt("warning"),
+      error: logAt("error"),
+      success: logAt("success")
     };
     tx.setLifecycleSink((level, message) => this.push(level, message));
+    tx.setAttachmentSink((image3, ts) => this.queueAttachment(image3, ts));
     const checkCanceled = () => this.checkCanceled();
     tx.setStepGuard(checkCanceled);
+    const eachSink = {
+      report: (status, message, payload, id, image3) => this.addItem(status, message, payload, id, image3),
+      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();
-        this.addItem(item.status, item.message, item.payload, item.id);
+        this.addItem(item.status, item.message, item.payload, item.id, item.image);
       },
       succeeded: (payload, options) => {
         checkCanceled();
-        this.addItem("succeeded", void 0, payload, options?.id);
+        this.addItem("succeeded", void 0, payload, options?.id, options?.image);
       },
       failed: (message, payload, options) => {
         checkCanceled();
-        this.addItem("failed", message, payload, options?.id);
+        this.addItem("failed", message, payload, options?.id, options?.image);
       },
       occurrence: (message, payload, options) => {
         checkCanceled();
-        this.addItem("occurrence", message, payload, options?.id);
-      }
+        this.addItem("occurrence", message, payload, options?.id, options?.image);
+      },
+      each: (list, handler, options = {}) => eachItem(list, handler, options, eachSink)
     };
     const progress = Object.defineProperties(
       {
@@ -1362,7 +1524,6 @@ var RunReporter = class {
       signal,
       throwIfCanceled: checkCanceled,
       sleep: sleep2,
-      attach: (image, options) => this.attach(image, options),
       retry: (fn, options) => retryWithBackoff(fn, { ...options, signal, wait: sleep2 })
     };
   }
@@ -1453,22 +1614,28 @@ var RunReporter = class {
     this.clearFlushTimer();
     return this.takeLogs().slice(-MAX_LOGS_PER_PATCH);
   }
-  log(level, message) {
+  /**
+   * Linha de log da run com eco no terminal. `image` (opcional) vira o anexo da linha:
+   * o id entra na entrada ANTES de qualquer I/O — é isso que mantém a ordem dos logs
+   * intacta e o handler livre da latência do upload.
+   */
+  log(level, message, image3) {
     if (this.dead) return;
     const scrubbed = scrubSecrets(safeString(message));
-    printRunLog(this.context.task, level, scrubbed);
-    this.push(level, scrubbed, true);
+    const ts = nowISO();
+    const attachmentId = image3 === void 0 ? void 0 : this.queueAttachment(image3, ts);
+    printRunLog(this.context.task, level, attachmentId ? `${scrubbed} [imagem]` : scrubbed);
+    this.push(level, scrubbed, true, attachmentId ? [attachmentId] : void 0, ts);
   }
   /** Bufferiza uma entrada de log sem eco no terminal (cap, truncate, flush). */
-  push(level, message, alreadyScrubbed = false, attachments) {
-    const ts = nowISO();
+  push(level, message, alreadyScrubbed = false, attachments, ts = nowISO()) {
     if (this.dead) return ts;
     const scrubbed = alreadyScrubbed ? message : scrubSecrets(message);
     this.buffer.push({
       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();
@@ -1611,7 +1778,7 @@ var RunReporter = class {
    * 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) {
+  addItem(status, message, payload, id, image3) {
     if (this.itemsClosed || this.itemsUnsupported) return;
     if (this.itemCount >= MAX_ITEMS_PER_RUN) {
       if (!this.itemsQuotaExceeded) {
@@ -1636,13 +1803,16 @@ var RunReporter = class {
         scrubbedPayload = void 0;
       }
     }
+    const ts = nowISO();
+    const attachmentId = image3 === void 0 ? void 0 : this.queueAttachment(image3, ts);
     this.itemsBuffer.push({
       id: id ? truncate(String(id), 255) : uuid4(),
       seq: this.itemSeq++,
       status,
       ...message ? { message: truncate(scrubSecrets(safeString(message)), MAX_ITEM_MESSAGE_CHARS) } : {},
       ...scrubbedPayload ? { payload: scrubbedPayload } : {},
-      ts: nowISO()
+      ts,
+      ...attachmentId ? { attachments: [attachmentId] } : {}
     });
     if (this.itemsBuffer.length >= ITEMS_FLUSH_AT_BUFFERED) {
       this.flushItems();
@@ -1722,59 +1892,51 @@ var RunReporter = class {
   }
   // ── Anexos ───────────────────────────────────────────────────────────────────
   /**
-   * Registra a linha de log com o id do anexo (síncrono, na ordem certa) e dispara
-   * o upload em segundo plano. Nunca lança: todo caminho de erro vira `{ ok: false }`
-   * com um aviso no log da run. É o `hobots.attach()`; o hint `attachment` de
-   * `hobots.captureException` também cai aqui via run-context-store.
+   * Pendura uma imagem num evento da run (log, item ou step): faz as checagens que não
+   * dependem de I/O (reporter morto, instalação sem anexos, cota), reserva o id e dispara
+   * o upload em segundo plano. Devolve o id — já referenciável pelo evento — ou undefined
+   * quando a imagem foi descartada (sempre com aviso no log da run). Nunca lança: todo
+   * caminho de erro do upload vira aviso. O hint `attachment` de `hobots.captureException`
+   * também cai aqui via `log()`.
    */
-  async attach(image, options = {}) {
-    const id = uuid4();
-    const level = options.level ?? "info";
-    const rawCaption = options.caption !== void 0 ? safeString(options.caption) : void 0;
-    const rawMessage = options.message !== void 0 ? safeString(options.message) : void 0;
-    const caption = rawCaption ? truncate(scrubSecrets(rawCaption), MAX_CAPTION_CHARS) : void 0;
-    const message = rawMessage ?? rawCaption ?? "captura de tela";
-    if (this.dead) return { id, ok: false, reason: "canceled" };
-    if (this.attachmentsUnsupported) {
-      this.log(level, message);
-      return { id, ok: false, reason: "unsupported" };
-    }
+  queueAttachment(imageIn, ts) {
+    if (this.dead) return void 0;
+    const image3 = toImageAttachment(imageIn);
+    if (this.attachmentsUnsupported) return void 0;
     if (this.attachmentCount >= MAX_ATTACHMENTS_PER_RUN) {
-      this.log(level, message);
-      this.log("warning", `anexo descartado: limite de ${MAX_ATTACHMENTS_PER_RUN} por execu\xE7\xE3o atingido`);
-      return { id, ok: false, reason: "quota" };
+      if (this.attachmentCount === MAX_ATTACHMENTS_PER_RUN) {
+        this.attachmentCount++;
+        this.log("warning", `imagem descartada: limite de ${MAX_ATTACHMENTS_PER_RUN} por execu\xE7\xE3o atingido`);
+      }
+      return void 0;
     }
     this.attachmentCount++;
-    const scrubbed = scrubSecrets(message);
-    printRunLog(this.context.task, level, `${scrubbed} [imagem]`);
-    const logTs = this.push(level, scrubbed, true, [id]);
-    let settle;
-    const result = new Promise((resolve2) => {
-      settle = resolve2;
-    });
-    const work = this.uploadAttachment(id, image, { caption, logTs, contentType: options.contentType }).then((reason) => settle(reason ? { id, ok: false, reason } : { id, ok: true })).catch(() => settle({ id, ok: false, reason: "upload-failed" }));
+    const id = uuid4();
+    const rawCaption = image3.caption !== void 0 ? safeString(image3.caption) : void 0;
+    const caption = rawCaption ? truncate(scrubSecrets(rawCaption), MAX_CAPTION_CHARS) : void 0;
+    const work = this.uploadAttachment(id, image3.input, { caption, logTs: ts, contentType: image3.contentType }).then(() => void 0).catch(() => void 0);
     this.pendingAttachments.add(work);
     void work.finally(() => this.pendingAttachments.delete(work));
-    return result;
+    return id;
   }
   /** Retorna o motivo da falha, ou undefined em sucesso. */
-  async uploadAttachment(id, image, meta) {
+  async uploadAttachment(id, image3, meta) {
     let bytes;
     try {
-      bytes = await toBytes(image);
+      bytes = await toBytes(image3);
     } catch (error) {
-      this.log("warning", `anexo n\xE3o p\xF4de ser lido: ${String(error)}`);
+      this.log("warning", `imagem n\xE3o p\xF4de ser lida: ${String(error)}`);
       return "read-failed";
     }
     const contentType = sniffContentType(bytes) ?? meta.contentType;
     if (!contentType) {
-      this.log("warning", "anexo descartado: formato n\xE3o reconhecido (aceitos: PNG, JPEG, WEBP)");
+      this.log("warning", "imagem descartada: formato n\xE3o reconhecido (aceitos: PNG, JPEG, WEBP)");
       return "unsupported-format";
     }
     if (bytes.byteLength > MAX_ATTACHMENT_BYTES) {
       this.log(
         "warning",
-        `anexo descartado: ${Math.round(bytes.byteLength / 1024)} KB excede o limite de ${MAX_ATTACHMENT_BYTES / 1024 / 1024} MB`
+        `imagem descartada: ${Math.round(bytes.byteLength / 1024)} KB excede o limite de ${MAX_ATTACHMENT_BYTES / 1024 / 1024} MB`
       );
       return "too-large";
     }
@@ -1805,11 +1967,11 @@ var RunReporter = class {
         return "unsupported";
       }
       if (error instanceof TasksApiError && error.status === 429) {
-        this.log("warning", "anexo descartado: limite de anexos por execu\xE7\xE3o atingido no servidor");
+        this.log("warning", "imagem descartada: limite de anexos por execu\xE7\xE3o atingido no servidor");
         return "quota";
       }
       if (this.abortController.signal.aborted) return "canceled";
-      this.log("warning", `falha ao enviar o anexo: ${String(error)}`);
+      this.log("warning", `falha ao enviar a imagem: ${String(error)}`);
       void this.api.confirmAttachment(this.runId, id, { status: "failed" }).catch(() => {
       });
       return "upload-failed";
@@ -1973,23 +2135,39 @@ var Step = class {
   /**
    * 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.
+   * `options.image` pendura um print do estado da tela em `data.attachments`.
    */
-  setStatus(status, message) {
+  setStatus(status, message, options) {
     this.status = status;
     if (message) this.setData("message", stepMessage(message));
+    if (options?.image !== void 0) this.attachImage(options.image);
     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.
+   * `options.image` pendura um print do estado da tela em `data.attachments`.
    */
-  setError(error, message) {
+  setError(error, message, options) {
     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) });
+    if (options?.image !== void 0) this.attachImage(options.image);
     return this;
   }
+  /**
+   * Dispara o upload pela run (sink do RunReporter) e referencia o anexo em
+   * `data.attachments` (chave reservada; teto igual ao das linhas de log). Fora de uma
+   * run não há onde pendurar a imagem — descarta com aviso único.
+   */
+  attachImage(image3) {
+    const current = Array.isArray(this.data?.attachments) ? this.data.attachments : [];
+    if (current.length >= MAX_ATTACHMENTS_PER_LOG_ENTRY) return;
+    const id = this.transaction.attachImage(image3);
+    if (!id) return;
+    this.setData("attachments", [...current, id]);
+  }
   /** Motivo registrado via setStatus(…, message) ou setError — usado no log de FINISH. */
   reason() {
     const error = this.data?.error;
@@ -2050,6 +2228,8 @@ var Transaction = class {
   tags = {};
   finished = false;
   lifecycleSink;
+  attachmentSink;
+  warnedNoAttachmentSink = false;
   // instalado pelo RunReporter: abrir uma step é um ponto de parada cooperativo (lança RunCanceled)
   stepGuard;
   // eventos emitidos antes do sink existir (o START da transaction sai no construtor,
@@ -2080,6 +2260,19 @@ var Transaction = class {
     this.lifecycleBacklog = [];
     for (const [level, message] of backlog) sink(level, message);
   }
+  /** Conecta o pipeline de anexos da run — é o que dá imagem às steps. */
+  setAttachmentSink(sink) {
+    this.attachmentSink = sink;
+  }
+  /** Imagem de uma step → id do anexo pela run; sem run, descarta com aviso único. */
+  attachImage(image3) {
+    if (this.attachmentSink) return this.attachmentSink(image3, nowISO());
+    if (!this.warnedNoAttachmentSink) {
+      this.warnedNoAttachmentSink = true;
+      console.warn("[hobots] imagem de step descartada \u2014 s\xF3 \xE9 suportada dentro de uma execu\xE7\xE3o de task");
+    }
+    return void 0;
+  }
   /**
    * Conecta a checagem de cancelamento chamada antes de cada step nova — é assim que
    * `hobots.transaction.startChild()` (e `step.startChild()`) param uma run cancelada.
@@ -2169,6 +2362,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 +2380,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 +2441,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 +2457,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 +2592,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;
@@ -2839,13 +3040,8 @@ function forwardAttachment(rt, attachment, message, type) {
     rt.logger.warn("attachment descartado \u2014 s\xF3 \xE9 suportado dentro de uma execu\xE7\xE3o de task");
     return;
   }
-  const withMeta = typeof attachment === "object" && "image" in attachment ? attachment : { image: attachment };
-  void reporter.attach(withMeta.image, {
-    message,
-    level: toRunLogLevel(type),
-    caption: withMeta.caption,
-    contentType: withMeta.contentType
-  });
+  const withMeta = typeof attachment === "object" && !isImageAttachment(attachment) && "image" in attachment ? image(attachment.image, { caption: attachment.caption, contentType: attachment.contentType }) : attachment;
+  reporter.log(toRunLogLevel(type), message, withMeta);
 }
 function captureException(error, hint) {
   const rt = runtime;
@@ -2892,15 +3088,34 @@ function warnOutsideRun(member) {
   else console.warn(`[hobots] ${message}`);
 }
 var FALLBACK_TASK = "hobots";
+var fallbackLogAt = (level) => (message, ...rest) => {
+  const { text, image: dropped } = splitLogArgs(message, rest);
+  printRunLog(FALLBACK_TASK, level, dropped ? `${text} [imagem descartada]` : text);
+};
 var fallbackLog = {
-  debug: (message, ...rest) => printRunLog(FALLBACK_TASK, "debug", joinLogArgs(message, rest)),
-  info: (message, ...rest) => printRunLog(FALLBACK_TASK, "info", joinLogArgs(message, rest)),
-  warn: (message, ...rest) => printRunLog(FALLBACK_TASK, "warning", joinLogArgs(message, rest)),
-  error: (message, ...rest) => printRunLog(FALLBACK_TASK, "error", joinLogArgs(message, rest)),
-  success: (message, ...rest) => printRunLog(FALLBACK_TASK, "success", joinLogArgs(message, rest))
+  debug: fallbackLogAt("debug"),
+  info: fallbackLogAt("info"),
+  warn: fallbackLogAt("warning"),
+  error: fallbackLogAt("error"),
+  success: fallbackLogAt("success")
 };
 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;
@@ -2928,9 +3143,6 @@ var hobots = Object.defineProperties({}, {
   signal: getter("signal", () => neverAborts),
   throwIfCanceled: method(() => resolve("throwIfCanceled")?.throwIfCanceled()),
   sleep: method((ms) => resolve("sleep")?.sleep(ms) ?? sleep(ms)),
-  attach: method(
-    (image, options) => resolve("attach")?.attach(image, options) ?? Promise.resolve({ id: "", ok: false, reason: "canceled" })
-  ),
   retry: method((fn, options) => {
     const reporter = currentReporter();
     return reporter ? reporter.context.retry(fn, options) : retryWithBackoff(fn, options);
@@ -2945,7 +3157,8 @@ var hobots = Object.defineProperties({}, {
     installGlobalHobots();
   }),
   close: method((timeoutMs) => close(timeoutMs)),
-  captureException: method((error, hint) => captureException(error, hint))
+  captureException: method((error, hint) => captureException(error, hint)),
+  image: method(image)
 });
 function installGlobalHobots() {
   if (globalThis.hobots === hobots) return;
@@ -2956,6 +3169,7 @@ var start2 = hobots.start;
 var close2 = hobots.close;
 var captureException2 = hobots.captureException;
 var retry = hobots.retry;
+var image2 = hobots.image;
 
 // src/index.ts
 var src_default = hobots;