hobots 3.3.0 → 3.4.0

package/README.md

@@ -93,12 +93,12 @@ Os dois podem coexistir no mesmo processo: um monitor sempre ligado + tasks sob
 
 | Membro | O que faz |
 | --- | --- |
-| `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.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. Um `hobots.image(...)` como **último** argumento pendura um print na linha. **Nunca lança** — pode ir em `finally`. |
+| `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 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. |
+| `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. `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. |
 | `hobots.retry(fn, { retries = 3, delayMs = 1_000, shouldRetry? })` | async-retry ciente do cancelamento da execução. `delayMs` aceita função `(tentativa) => ms`. |
 | `hobots.sleep(ms)` | Espera **cancelável**: rejeita com `RunCanceled` se a execução for cancelada. |

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.3.0" : "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";
 }
@@ -377,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),
@@ -554,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 {
@@ -568,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(/\/+$/, "");
 }
@@ -936,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),
@@ -959,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),
@@ -1009,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),
@@ -1030,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),
@@ -1046,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),
@@ -1075,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),
@@ -1107,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
@@ -1125,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),
@@ -1207,22 +1213,22 @@ var ItemHandle = class {
   sink;
   reported = false;
   status;
-  succeeded(payload) {
-    this.record("succeeded", void 0, payload);
+  succeeded(payload, options) {
+    this.record("succeeded", void 0, payload, options?.image);
   }
-  failed(message, payload) {
-    this.record("failed", message, payload);
+  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) {
-    this.record("occurrence", message, payload);
+  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) {
+  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);
+    this.sink.report(status, message, Object.keys(merged).length > 0 ? merged : void 0, this.id, image3);
   }
 };
 function resolveId(options, element, index) {
@@ -1302,6 +1308,27 @@ var MAX_ATTACHMENTS_PER_LOG_ENTRY = WIRE_LIMITS.MAX_ATTACHMENTS_PER_LOG_ENTRY;
 var MAX_CONCURRENT_UPLOADS = 3;
 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");
@@ -1351,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;
@@ -1407,18 +1442,23 @@ 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) => this.addItem(status, message, payload, id),
+      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);
@@ -1431,19 +1471,19 @@ var RunReporter = class {
     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)
     };
@@ -1484,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 })
     };
   }
@@ -1575,15 +1614,21 @@ 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({
@@ -1733,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) {
@@ -1758,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();
@@ -1844,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";
     }
@@ -1927,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";
@@ -2095,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;
@@ -2172,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,
@@ -2202,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.
@@ -2969,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;
@@ -3022,12 +3088,16 @@ 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 fallbackEachSink = {
@@ -3073,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);
@@ -3090,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;
@@ -3101,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;