hobots 1.8.1 → 1.9.1

package/dist/index.d.cts

@@ -1,5 +1,8 @@
-import { Breadcrumb, EventUser, Severity, EventPayload, TransactionPayload, HeartbeatPayload, StepStatus, RunLogLevel, StepData } from './protocol.cjs';
-export { AgentInfo, Envelope, EnvelopeItem, ExceptionData, PollRequest, PollResponse, RunDescriptor, RunError, RunLogEntry, RunStatus, RunUpdateRequest, RunUpdateResponse, RunUpdateStatus, StackFrame } from './protocol.cjs';
+import { Breadcrumb, EventUser, Severity, EventPayload, TransactionPayload, HeartbeatPayload, StepStatus, RunLogLevel, StepData, RunAttachmentContentType } from './protocol.cjs';
+export { AgentInfo, Envelope, EnvelopeItem, ExceptionData, PollRequest, PollResponse, RunAttachmentConfirmRequest, RunAttachmentConfirmResponse, RunAttachmentCreateRequest, RunAttachmentCreateResponse, RunDescriptor, RunError, RunLogEntry, RunStatus, RunUpdateRequest, RunUpdateResponse, RunUpdateStatus, StackFrame } from './protocol.cjs';
+
+/** Aceita tudo que o handler pode ter em mãos: bytes ou um caminho de arquivo (só Node). */
+type AttachInput = Uint8Array | ArrayBuffer | string;
 
 /** API oficial da Hobots — o SDK sempre fala com ela em produção. */
 declare const DEFAULT_BASE_URL = "https://api2.hobots.app";
@@ -224,17 +227,43 @@ interface InitOptions {
     /** Itens por envelope antes de flush imediato. Default: 10 */
     maxBatchSize?: number;
 }
+/** Imagem enviada junto de um capture* — com legenda e content-type opcionais. */
+interface CaptureAttachment {
+    /** Bytes (`Uint8Array`/`ArrayBuffer`/`Buffer`) ou um caminho de arquivo (só em Node) */
+    image: AttachInput;
+    /** Legenda curta, exibida sob a miniatura no app. Passa pelo scrub de segredos. */
+    caption?: string;
+    /** Informe quando os magic bytes não bastarem (o SDK sempre prefere o que detectar). */
+    contentType?: RunAttachmentContentType;
+}
 interface CaptureHint {
     level?: Severity;
     tags?: Record<string, string>;
     extra?: Record<string, unknown>;
     fingerprint?: string[];
+    /**
+     * Print da tela enviado junto da captura. Dentro de uma execução de task, a imagem
+     * vira anexo da linha de log da execução que espelha o evento — miniatura na aba
+     * "logs do agente". Fora de uma execução não há onde pendurar a imagem: o SDK
+     * descarta com um aviso. O upload roda em segundo plano e **nunca bloqueia nem lança**.
+     *
+     * PNG, JPEG ou WEBP, até 5 MB, no máximo 20 anexos por execução.
+     *
+     * ```ts
+     * Hobots.captureException(error, { attachment: { image: await page.screenshot(), caption: 'tela no momento do erro' } });
+     * ```
+     */
+    attachment?: AttachInput | CaptureAttachment;
 }
 
 /** Inicializa o SDK. Chame uma vez, o mais cedo possível no programa. */
 declare function init(options: InitOptions): void;
 declare function getClient(): Client | undefined;
-/** Captura uma exceção e retorna o event_id (undefined se o SDK não foi inicializado). */
+/**
+ * Captura uma exceção e retorna o event_id (undefined se o SDK não foi inicializado).
+ * `hint.attachment` envia um print junto — dentro de uma execução de task, ele aparece
+ * como miniatura na linha de log da run correspondente ao erro.
+ */
 declare function captureException(error: unknown, hint?: CaptureHint): string | undefined;
 declare function captureMessage(message: string, level?: Severity, hint?: CaptureHint): string | undefined;
 /** Registra um breadcrumb — anexado aos próximos eventos como trilha do que aconteceu antes. */
@@ -267,4 +296,4 @@ declare function close(timeoutMs?: number): Promise<boolean>;
 
 declare function scrubSecrets(text: string): string;
 
-export { Breadcrumb, type BreadcrumbInput, type CaptureHint, Client, DEFAULT_BASE_URL, EventPayload, EventUser, type HeartbeatOptions, HeartbeatPayload, type InitOptions, type RunContext, RunLogLevel, Scope, Severity, Step, StepData, type TaskHandler, type TasksOptions, Transaction, TransactionPayload, addBreadcrumb, captureException, captureMessage, close, flush, getClient, init, register, scrubSecrets, setContext, setExtra, setTag, setTags, setUser, start, startTransaction, stop, withScope };
+export { type AttachInput, Breadcrumb, type BreadcrumbInput, type CaptureAttachment, type CaptureHint, Client, DEFAULT_BASE_URL, EventPayload, EventUser, type HeartbeatOptions, HeartbeatPayload, type InitOptions, RunAttachmentContentType, type RunContext, RunLogLevel, Scope, Severity, Step, StepData, type TaskHandler, type TasksOptions, Transaction, TransactionPayload, addBreadcrumb, captureException, captureMessage, close, flush, getClient, init, register, scrubSecrets, setContext, setExtra, setTag, setTags, setUser, start, startTransaction, stop, withScope };

package/dist/index.d.ts

@@ -1,5 +1,8 @@
-import { Breadcrumb, EventUser, Severity, EventPayload, TransactionPayload, HeartbeatPayload, StepStatus, RunLogLevel, StepData } from './protocol.js';
-export { AgentInfo, Envelope, EnvelopeItem, ExceptionData, PollRequest, PollResponse, RunDescriptor, RunError, RunLogEntry, RunStatus, RunUpdateRequest, RunUpdateResponse, RunUpdateStatus, StackFrame } from './protocol.js';
+import { Breadcrumb, EventUser, Severity, EventPayload, TransactionPayload, HeartbeatPayload, StepStatus, RunLogLevel, StepData, RunAttachmentContentType } from './protocol.js';
+export { AgentInfo, Envelope, EnvelopeItem, ExceptionData, PollRequest, PollResponse, RunAttachmentConfirmRequest, RunAttachmentConfirmResponse, RunAttachmentCreateRequest, RunAttachmentCreateResponse, RunDescriptor, RunError, RunLogEntry, RunStatus, RunUpdateRequest, RunUpdateResponse, RunUpdateStatus, StackFrame } from './protocol.js';
+
+/** Aceita tudo que o handler pode ter em mãos: bytes ou um caminho de arquivo (só Node). */
+type AttachInput = Uint8Array | ArrayBuffer | string;
 
 /** API oficial da Hobots — o SDK sempre fala com ela em produção. */
 declare const DEFAULT_BASE_URL = "https://api2.hobots.app";
@@ -224,17 +227,43 @@ interface InitOptions {
     /** Itens por envelope antes de flush imediato. Default: 10 */
     maxBatchSize?: number;
 }
+/** Imagem enviada junto de um capture* — com legenda e content-type opcionais. */
+interface CaptureAttachment {
+    /** Bytes (`Uint8Array`/`ArrayBuffer`/`Buffer`) ou um caminho de arquivo (só em Node) */
+    image: AttachInput;
+    /** Legenda curta, exibida sob a miniatura no app. Passa pelo scrub de segredos. */
+    caption?: string;
+    /** Informe quando os magic bytes não bastarem (o SDK sempre prefere o que detectar). */
+    contentType?: RunAttachmentContentType;
+}
 interface CaptureHint {
     level?: Severity;
     tags?: Record<string, string>;
     extra?: Record<string, unknown>;
     fingerprint?: string[];
+    /**
+     * Print da tela enviado junto da captura. Dentro de uma execução de task, a imagem
+     * vira anexo da linha de log da execução que espelha o evento — miniatura na aba
+     * "logs do agente". Fora de uma execução não há onde pendurar a imagem: o SDK
+     * descarta com um aviso. O upload roda em segundo plano e **nunca bloqueia nem lança**.
+     *
+     * PNG, JPEG ou WEBP, até 5 MB, no máximo 20 anexos por execução.
+     *
+     * ```ts
+     * Hobots.captureException(error, { attachment: { image: await page.screenshot(), caption: 'tela no momento do erro' } });
+     * ```
+     */
+    attachment?: AttachInput | CaptureAttachment;
 }
 
 /** Inicializa o SDK. Chame uma vez, o mais cedo possível no programa. */
 declare function init(options: InitOptions): void;
 declare function getClient(): Client | undefined;
-/** Captura uma exceção e retorna o event_id (undefined se o SDK não foi inicializado). */
+/**
+ * Captura uma exceção e retorna o event_id (undefined se o SDK não foi inicializado).
+ * `hint.attachment` envia um print junto — dentro de uma execução de task, ele aparece
+ * como miniatura na linha de log da run correspondente ao erro.
+ */
 declare function captureException(error: unknown, hint?: CaptureHint): string | undefined;
 declare function captureMessage(message: string, level?: Severity, hint?: CaptureHint): string | undefined;
 /** Registra um breadcrumb — anexado aos próximos eventos como trilha do que aconteceu antes. */
@@ -267,4 +296,4 @@ declare function close(timeoutMs?: number): Promise<boolean>;
 
 declare function scrubSecrets(text: string): string;
 
-export { Breadcrumb, type BreadcrumbInput, type CaptureHint, Client, DEFAULT_BASE_URL, EventPayload, EventUser, type HeartbeatOptions, HeartbeatPayload, type InitOptions, type RunContext, RunLogLevel, Scope, Severity, Step, StepData, type TaskHandler, type TasksOptions, Transaction, TransactionPayload, addBreadcrumb, captureException, captureMessage, close, flush, getClient, init, register, scrubSecrets, setContext, setExtra, setTag, setTags, setUser, start, startTransaction, stop, withScope };
+export { type AttachInput, Breadcrumb, type BreadcrumbInput, type CaptureAttachment, type CaptureHint, Client, DEFAULT_BASE_URL, EventPayload, EventUser, type HeartbeatOptions, HeartbeatPayload, type InitOptions, RunAttachmentContentType, type RunContext, RunLogLevel, Scope, Severity, Step, StepData, type TaskHandler, type TasksOptions, Transaction, TransactionPayload, addBreadcrumb, captureException, captureMessage, close, flush, getClient, init, register, scrubSecrets, setContext, setExtra, setTag, setTags, setUser, start, startTransaction, stop, withScope };

package/dist/index.js

@@ -103,7 +103,7 @@ function scrubSecrets(text) {
 
 // src/utils.ts
 var SDK_NAME = "hobots";
-var SDK_VERSION = true ? "1.8.0" : "0.0.0-dev";
+var SDK_VERSION = true ? "1.9.0" : "0.0.0-dev";
 function isNode() {
   return typeof process !== "undefined" && typeof process.versions?.node === "string";
 }
@@ -270,6 +270,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 Transport = class {
   endpoint;
   key;
@@ -319,7 +320,15 @@ var Transport = class {
       this.timer = void 0;
     }
     if (this.buffer.length === 0) return Promise.resolve();
-    const items = this.buffer.splice(0, this.buffer.length);
+    const taken = this.buffer.splice(0, this.buffer.length);
+    const sends = [];
+    for (let offset = 0; offset < taken.length; offset += MAX_ITEMS_PER_ENVELOPE) {
+      sends.push(this.send(taken.slice(offset, offset + MAX_ITEMS_PER_ENVELOPE)));
+    }
+    return Promise.all(sends).then(() => void 0);
+  }
+  /** Registra o envio em `this.pending` para que `flush()` aguarde todos os envelopes. */
+  send(items) {
     const envelope = {
       sdk: { name: SDK_NAME, version: SDK_VERSION },
       sent_at: nowISO(),
@@ -351,7 +360,7 @@ var Transport = class {
       this.logger.debug(`envelope enviado (${envelope.items.length} itens)`);
       return;
     }
-    this.logger.error(`envelope rejeitado (HTTP ${response.status}), descartado`);
+    this.logger.error(`envelope rejeitado (HTTP ${response.status}), descartado (${envelope.items.length} itens)`);
   }
   /** Envia o que estiver na fila e aguarda envios em andamento (até timeoutMs). */
   async flush(timeoutMs = 5e3) {
@@ -824,6 +833,8 @@ var Transaction = class {
 // src/tasks/api.ts
 var POLL_TIMEOUT_MS = 3e4;
 var UPDATE_TIMEOUT_MS = 1e4;
+var UPLOAD_TIMEOUT_MS = 3e4;
+var UPLOAD_RETRY_DELAYS_MS = [1e3, 4e3];
 var TasksApiError = class extends Error {
   constructor(message, status) {
     super(message);
@@ -918,8 +929,123 @@ var TasksApi = class {
       signal: AbortSignal.timeout(timeoutMs)
     });
   }
+  /**
+   * Registra o anexo e obtém a URL presignada de upload. 404/501/503 significam
+   * "esta instalação não tem anexos" — o RunReporter degrada em silêncio a partir daí.
+   */
+  async createAttachment(runId, request, signal) {
+    const { signal: timeoutSignal, cleanup } = withTimeoutSignal(UPDATE_TIMEOUT_MS, signal);
+    let response;
+    try {
+      response = await fetchWithRetry(
+        () => fetch(`${this.baseUrl}/runs/${encodeURIComponent(runId)}/attachments`, {
+          method: "POST",
+          headers: this.headers(),
+          body: JSON.stringify(request),
+          signal: timeoutSignal
+        }),
+        { logger: this.logger, label: `anexo da run ${runId}` }
+      );
+    } finally {
+      cleanup();
+    }
+    if (!response.ok) {
+      throw new TasksApiError(`cria\xE7\xE3o de anexo rejeitada (HTTP ${response.status})`, response.status);
+    }
+    const body = await response.json();
+    if (typeof body?.upload_url !== "string") {
+      throw new TasksApiError("resposta inv\xE1lida do anexo (upload_url ausente)", 0);
+    }
+    return {
+      id: body.id ?? request.id,
+      upload_url: body.upload_url,
+      headers: body.headers ?? { "content-type": request.content_type },
+      expires_in: body.expires_in ?? 900
+    };
+  }
+  /**
+   * PUT do binário direto no S3. Deliberadamente sem `authorization`: a autorização
+   * está na assinatura da URL, e mandar o client secret para fora da API seria vazamento.
+   */
+  async uploadAttachment(url, headers, body, signal) {
+    const { signal: timeoutSignal, cleanup } = withTimeoutSignal(UPLOAD_TIMEOUT_MS, signal);
+    let response;
+    try {
+      response = await fetchWithRetry(
+        () => fetch(url, {
+          method: "PUT",
+          headers,
+          // BodyInit não aceita Uint8Array<ArrayBufferLike> em todos os lib.dom; o buffer é o mesmo
+          body,
+          signal: timeoutSignal
+        }),
+        { delays: UPLOAD_RETRY_DELAYS_MS, logger: this.logger, label: "upload de anexo" }
+      );
+    } finally {
+      cleanup();
+    }
+    if (!response.ok) {
+      throw new TasksApiError(`upload de anexo rejeitado (HTTP ${response.status})`, response.status);
+    }
+  }
+  /** Marca o anexo como enviado (ou falho). Best-effort — a leitura não depende disso. */
+  async confirmAttachment(runId, attachmentId, request) {
+    const response = await fetch(
+      `${this.baseUrl}/runs/${encodeURIComponent(runId)}/attachments/${encodeURIComponent(attachmentId)}`,
+      {
+        method: "PATCH",
+        headers: this.headers(),
+        body: JSON.stringify(request),
+        signal: AbortSignal.timeout(UPDATE_TIMEOUT_MS)
+      }
+    );
+    if (!response.ok) {
+      throw new TasksApiError(`confirma\xE7\xE3o de anexo rejeitada (HTTP ${response.status})`, response.status);
+    }
+  }
 };
 
+// src/tasks/attachments.ts
+var MAX_ATTACHMENT_BYTES = 5242880;
+var MAX_ATTACHMENTS_PER_RUN = 20;
+var MAX_CONCURRENT_UPLOADS = 3;
+var MAX_CAPTION_CHARS = 200;
+var ATTACHMENT_DRAIN_MS = 15e3;
+async function readImageFile(path) {
+  if (!isNode()) {
+    throw new Error("caminho de arquivo s\xF3 \xE9 suportado em Node");
+  }
+  const { readFile } = await import("fs/promises");
+  return new Uint8Array(await readFile(path));
+}
+function startsWith(bytes, signature, offset = 0) {
+  if (bytes.length < offset + signature.length) return false;
+  return signature.every((byte, index) => bytes[offset + index] === byte);
+}
+var PNG_MAGIC = [137, 80, 78, 71, 13, 10, 26, 10];
+var JPEG_MAGIC = [255, 216, 255];
+var RIFF_MAGIC = [82, 73, 70, 70];
+var WEBP_MAGIC = [87, 69, 66, 80];
+function sniffContentType(bytes) {
+  if (startsWith(bytes, PNG_MAGIC)) return "image/png";
+  if (startsWith(bytes, JPEG_MAGIC)) return "image/jpeg";
+  if (startsWith(bytes, RIFF_MAGIC) && startsWith(bytes, WEBP_MAGIC, 8)) return "image/webp";
+  return void 0;
+}
+function readPngDimensions(bytes) {
+  if (!startsWith(bytes, PNG_MAGIC) || bytes.length < 24) return void 0;
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const width = view.getUint32(16);
+  const height = view.getUint32(20);
+  if (width === 0 || height === 0) return void 0;
+  return { width, height };
+}
+async function toBytes(input) {
+  if (typeof input === "string") return readImageFile(input);
+  if (input instanceof Uint8Array) return input;
+  return new Uint8Array(input);
+}
+
 // src/tasks/context.ts
 var LOG_LEVEL_COLOR = {
   debug: "gray",
@@ -1001,6 +1127,14 @@ var RunReporter = class {
   abortController = new AbortController();
   flushIntervalMs;
   cancelCheckIntervalMs;
+  // Uploads de anexo vivem FORA de `this.chain`: a cadeia é um FIFO puro de
+  // status/logs e não pode ficar bloqueada esperando um binário subir.
+  pendingAttachments = /* @__PURE__ */ new Set();
+  attachmentCount = 0;
+  uploadSlots = MAX_CONCURRENT_UPLOADS;
+  uploadQueue = [];
+  /** Uma vez que a instalação recusa anexos, para de tentar (e de avisar) nesta run. */
+  attachmentsUnsupported = false;
   get isDead() {
     return this.dead;
   }
@@ -1019,6 +1153,8 @@ var RunReporter = class {
     this.dead = true;
     this.clearFlushTimer();
     this.buffer = [];
+    const waiting = this.uploadQueue.splice(0, this.uploadQueue.length);
+    for (const resume of waiting) resume();
   }
   /**
    * Drena o buffer pendente para o PATCH único do exit path (chame ANTES de kill,
@@ -1036,15 +1172,22 @@ var RunReporter = class {
     this.push(level, scrubbed, true);
   }
   /** Bufferiza uma entrada de log sem eco no terminal (cap, truncate, flush). */
-  push(level, message, alreadyScrubbed = false) {
-    if (this.dead) return;
+  push(level, message, alreadyScrubbed = false, attachments) {
+    const ts = nowISO();
+    if (this.dead) return ts;
     const scrubbed = alreadyScrubbed ? message : scrubSecrets(message);
-    this.buffer.push({ ts: nowISO(), level, message: truncate(scrubbed, MAX_LOG_MESSAGE_CHARS) });
+    this.buffer.push({
+      ts,
+      level,
+      message: truncate(scrubbed, MAX_LOG_MESSAGE_CHARS),
+      ...attachments && attachments.length > 0 ? { attachments } : {}
+    });
     if (this.buffer.length >= FLUSH_AT_BUFFERED) {
       this.flushLogs();
     } else {
       this.scheduleFlush();
     }
+    return ts;
   }
   scheduleFlush() {
     if (this.timer) return;
@@ -1112,6 +1255,131 @@ var RunReporter = class {
   finalize() {
     return this.chain;
   }
+  // ── 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. Chega ao handler pelos capture* do SDK — o hint
+   * `attachment` de Hobots.captureException/captureMessage cai aqui via run-context-store.
+   */
+  async attach(image, options = {}) {
+    const id = uuid4();
+    const level = options.level ?? "info";
+    const caption = options.caption ? truncate(scrubSecrets(options.caption), MAX_CAPTION_CHARS) : void 0;
+    const message = options.message ?? options.caption ?? "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" };
+    }
+    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" };
+    }
+    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((resolve) => {
+      settle = resolve;
+    });
+    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" }));
+    this.pendingAttachments.add(work);
+    void work.finally(() => this.pendingAttachments.delete(work));
+    return result;
+  }
+  /** Retorna o motivo da falha, ou undefined em sucesso. */
+  async uploadAttachment(id, image, meta) {
+    let bytes;
+    try {
+      bytes = await toBytes(image);
+    } catch (error) {
+      this.log("warning", `anexo n\xE3o p\xF4de ser lido: ${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)");
+      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`
+      );
+      return "too-large";
+    }
+    const dimensions = readPngDimensions(bytes);
+    const release = await this.acquireUploadSlot();
+    try {
+      if (this.abortController.signal.aborted || this.dead) return "canceled";
+      const created = await this.api.createAttachment(
+        this.runId,
+        {
+          id,
+          content_type: contentType,
+          size_bytes: bytes.byteLength,
+          log_ts: meta.logTs,
+          ...meta.caption ? { caption: meta.caption } : {},
+          ...dimensions ?? {}
+        },
+        this.abortController.signal
+      );
+      await this.api.uploadAttachment(created.upload_url, created.headers, bytes, this.abortController.signal);
+      await this.api.confirmAttachment(this.runId, id, { status: "uploaded", size_bytes: bytes.byteLength, ...dimensions ?? {} }).catch(() => {
+      });
+      return void 0;
+    } catch (error) {
+      if (this.isUnsupported(error)) {
+        this.attachmentsUnsupported = true;
+        this.log("warning", "anexos n\xE3o est\xE3o habilitados nesta instala\xE7\xE3o do Hobots \u2014 imagem n\xE3o enviada");
+        return "unsupported";
+      }
+      if (error instanceof TasksApiError && error.status === 429) {
+        this.log("warning", "anexo descartado: 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)}`);
+      void this.api.confirmAttachment(this.runId, id, { status: "failed" }).catch(() => {
+      });
+      return "upload-failed";
+    } finally {
+      release();
+    }
+  }
+  /** 404 = API anterior ao recurso; 501/503 = instalação sem S3 configurado. */
+  isUnsupported(error) {
+    return error instanceof TasksApiError && (error.status === 404 || error.status === 501 || error.status === 503);
+  }
+  /** Semáforo simples: no máximo MAX_CONCURRENT_UPLOADS binários em voo por run. */
+  acquireUploadSlot() {
+    const release = () => {
+      const next = this.uploadQueue.shift();
+      if (next) next();
+      else this.uploadSlots++;
+    };
+    if (this.uploadSlots > 0) {
+      this.uploadSlots--;
+      return Promise.resolve(release);
+    }
+    return new Promise((resolve) => {
+      this.uploadQueue.push(() => resolve(release));
+    });
+  }
+  /**
+   * Espera os uploads pendentes antes do PATCH terminal, para a run não terminar
+   * exibindo miniaturas em "enviando…". Capado: um upload lento não segura a run.
+   */
+  async finalizeAttachments(timeoutMs = ATTACHMENT_DRAIN_MS) {
+    if (this.pendingAttachments.size === 0) return;
+    await Promise.race([
+      Promise.allSettled([...this.pendingAttachments]),
+      new Promise((resolve) => unrefTimer(setTimeout(resolve, timeoutMs)))
+    ]);
+  }
   enqueue(update) {
     if (this.dead) {
       this.salvageLogs(update.logs);
@@ -1179,6 +1447,9 @@ async function runWithRunContext(store, fn) {
 function currentRunTransaction() {
   return storage?.getStore()?.tx;
 }
+function currentRunAttach() {
+  return storage?.getStore()?.attach;
+}
 
 // src/tasks/shutdown.ts
 var WATCHED_SIGNALS = ["SIGINT", "SIGTERM"];
@@ -1420,12 +1691,17 @@ var TaskAgent = class {
       }
       this.logger.debug(`executando run ${run.id} (${run.task})`);
       try {
-        await runWithRunContext({ runId: run.id, tx }, () => this.invokeWithTimeout(handler, run, reporter));
+        await runWithRunContext(
+          { runId: run.id, tx, attach: (image, options) => reporter.attach(image, options) },
+          () => this.invokeWithTimeout(handler, run, reporter)
+        );
+        await reporter.finalizeAttachments();
         tx.setStatus("ok");
         tx.finish();
         reporter.reportSuccess();
         this.logger.debug(`run ${run.id} conclu\xEDda`);
       } catch (error) {
+        await reporter.finalizeAttachments();
         tx.setStatus("error");
         tx.finish();
         reporter.reportFailure(toRunError(error));
@@ -1508,10 +1784,34 @@ function init(options) {
 function getClient() {
   return client;
 }
+function toRunLogLevel(level) {
+  return level === "fatal" ? "error" : level;
+}
+function forwardAttachment(attachment, message, level) {
+  const attach = currentRunAttach();
+  if (!attach) {
+    client?.logger.warn("attachment descartado \u2014 s\xF3 \xE9 suportado dentro de uma execu\xE7\xE3o de task (register/start)");
+    return;
+  }
+  const withMeta = typeof attachment === "object" && "image" in attachment ? attachment : { image: attachment };
+  void attach(withMeta.image, {
+    message,
+    level: toRunLogLevel(level),
+    caption: withMeta.caption,
+    contentType: withMeta.contentType
+  });
+}
 function captureException(error, hint) {
+  if (hint?.attachment) {
+    const message = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+    forwardAttachment(hint.attachment, message, hint.level ?? "error");
+  }
   return client?.captureException(error, hint, scope);
 }
 function captureMessage(message, level = "info", hint) {
+  if (hint?.attachment) {
+    forwardAttachment(hint.attachment, message, hint.level ?? level);
+  }
   return client?.captureMessage(message, level, hint, scope);
 }
 function addBreadcrumb(crumb) {