hobots 1.8.0 → 1.9.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-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';
 
 /** API oficial da Hobots — o SDK sempre fala com ela em produção. */
 declare const DEFAULT_BASE_URL = "https://api2.hobots.app";
@@ -123,6 +123,31 @@ declare class Transaction {
     finish(): void;
 }
 
+interface AttachOptions {
+    /** Legenda curta, exibida sob a miniatura no app. Passa pelo scrub de segredos. */
+    caption?: string;
+    /** Nível da linha de log que carrega o anexo. Default: 'info' */
+    level?: RunLogLevel;
+    /** Texto da linha de log. Default: a legenda, ou 'captura de tela' */
+    message?: string;
+    /** Informe quando os magic bytes não bastarem (o SDK sempre prefere o que detectar). */
+    contentType?: RunAttachmentContentType;
+}
+type AttachFailureReason = 
+/** A instalação do Hobots não tem anexos habilitados (ou a API é anterior ao recurso) */
+'unsupported' | 'too-large' | 'quota' | 'read-failed'
+/** Formato não reconhecido ou fora de PNG/JPEG/WEBP */
+ | 'unsupported-format' | 'upload-failed' | 'canceled';
+interface AttachResult {
+    /** Id do anexo, o mesmo referenciado na linha de log */
+    id: string;
+    ok: boolean;
+    /** Motivo do insucesso — para diagnóstico; `attach` nunca lança */
+    reason?: AttachFailureReason;
+}
+/** Aceita tudo que o handler pode ter em mãos: bytes ou um caminho de arquivo (só Node). */
+type AttachInput = Uint8Array | ArrayBuffer | string;
+
 /** Opções de tasks dentro de `init({ tasks: ... })`. Credencial (clientSecret), identidade (instanceId) e debug vêm do init. */
 interface TasksOptions {
     /** Intervalo entre polls sem trabalho. Default: 5_000 (mínimo 1_000) */
@@ -177,6 +202,22 @@ interface RunContext {
     throwIfCanceled(): void;
     /** Sleep cancelável: rejeita com `RunCanceled` se ctx.signal disparar antes de ms. */
     sleep(ms: number): Promise<void>;
+    /**
+     * Anexa uma imagem (print da tela) a uma linha de log da execução — a evidência
+     * visual aparece como miniatura junto do log, na aba "logs do agente".
+     *
+     * Aceita bytes (`Uint8Array`/`ArrayBuffer`/`Buffer`) ou um caminho de arquivo
+     * (só em Node). A linha de log é registrada imediatamente; o upload roda em
+     * segundo plano e **nunca bloqueia nem lança** — falhas viram um aviso no log da
+     * run e um `{ ok: false, reason }` no retorno, que pode ser ignorado com `void`.
+     *
+     * PNG, JPEG ou WEBP, até 5 MB, no máximo 20 anexos por execução.
+     *
+     * ```ts
+     * await ctx.attach(await page.screenshot(), { caption: 'portal após o login' });
+     * ```
+     */
+    attach(image: AttachInput, options?: AttachOptions): Promise<AttachResult>;
 }
 /** O retorno do handler é ignorado — nada além de status/logs/erro é enviado ao servidor. */
 type TaskHandler<P = Record<string, unknown>> = (params: P, ctx: RunContext) => void | Promise<void>;
@@ -267,4 +308,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 AttachFailureReason, type AttachOptions, type AttachResult, Breadcrumb, type BreadcrumbInput, 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,5 @@
-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';
 
 /** API oficial da Hobots — o SDK sempre fala com ela em produção. */
 declare const DEFAULT_BASE_URL = "https://api2.hobots.app";
@@ -123,6 +123,31 @@ declare class Transaction {
     finish(): void;
 }
 
+interface AttachOptions {
+    /** Legenda curta, exibida sob a miniatura no app. Passa pelo scrub de segredos. */
+    caption?: string;
+    /** Nível da linha de log que carrega o anexo. Default: 'info' */
+    level?: RunLogLevel;
+    /** Texto da linha de log. Default: a legenda, ou 'captura de tela' */
+    message?: string;
+    /** Informe quando os magic bytes não bastarem (o SDK sempre prefere o que detectar). */
+    contentType?: RunAttachmentContentType;
+}
+type AttachFailureReason = 
+/** A instalação do Hobots não tem anexos habilitados (ou a API é anterior ao recurso) */
+'unsupported' | 'too-large' | 'quota' | 'read-failed'
+/** Formato não reconhecido ou fora de PNG/JPEG/WEBP */
+ | 'unsupported-format' | 'upload-failed' | 'canceled';
+interface AttachResult {
+    /** Id do anexo, o mesmo referenciado na linha de log */
+    id: string;
+    ok: boolean;
+    /** Motivo do insucesso — para diagnóstico; `attach` nunca lança */
+    reason?: AttachFailureReason;
+}
+/** Aceita tudo que o handler pode ter em mãos: bytes ou um caminho de arquivo (só Node). */
+type AttachInput = Uint8Array | ArrayBuffer | string;
+
 /** Opções de tasks dentro de `init({ tasks: ... })`. Credencial (clientSecret), identidade (instanceId) e debug vêm do init. */
 interface TasksOptions {
     /** Intervalo entre polls sem trabalho. Default: 5_000 (mínimo 1_000) */
@@ -177,6 +202,22 @@ interface RunContext {
     throwIfCanceled(): void;
     /** Sleep cancelável: rejeita com `RunCanceled` se ctx.signal disparar antes de ms. */
     sleep(ms: number): Promise<void>;
+    /**
+     * Anexa uma imagem (print da tela) a uma linha de log da execução — a evidência
+     * visual aparece como miniatura junto do log, na aba "logs do agente".
+     *
+     * Aceita bytes (`Uint8Array`/`ArrayBuffer`/`Buffer`) ou um caminho de arquivo
+     * (só em Node). A linha de log é registrada imediatamente; o upload roda em
+     * segundo plano e **nunca bloqueia nem lança** — falhas viram um aviso no log da
+     * run e um `{ ok: false, reason }` no retorno, que pode ser ignorado com `void`.
+     *
+     * PNG, JPEG ou WEBP, até 5 MB, no máximo 20 anexos por execução.
+     *
+     * ```ts
+     * await ctx.attach(await page.screenshot(), { caption: 'portal após o login' });
+     * ```
+     */
+    attach(image: AttachInput, options?: AttachOptions): Promise<AttachResult>;
 }
 /** O retorno do handler é ignorado — nada além de status/logs/erro é enviado ao servidor. */
 type TaskHandler<P = Record<string, unknown>> = (params: P, ctx: RunContext) => void | Promise<void>;
@@ -267,4 +308,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 AttachFailureReason, type AttachOptions, type AttachResult, Breadcrumb, type BreadcrumbInput, 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",
@@ -958,7 +1084,6 @@ 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_RUN = 500;
 var MAX_LOGS_PER_PATCH = 100;
 var FLUSH_AT_BUFFERED = 20;
 var RunReporter = class {
@@ -989,13 +1114,12 @@ var RunReporter = class {
       throwIfCanceled: () => {
         if (signal.aborted) throw runCanceledError();
       },
-      sleep: (ms) => cancelableSleep(ms, signal)
+      sleep: (ms) => cancelableSleep(ms, signal),
+      attach: (image, options) => this.attach(image, options)
     };
   }
   context;
   buffer = [];
-  loggedCount = 0;
-  droppedCount = 0;
   dead = false;
   chain = Promise.resolve();
   pendingUpdates = 0;
@@ -1004,6 +1128,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;
   }
@@ -1022,6 +1154,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,
@@ -1039,20 +1173,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);
-    if (this.loggedCount >= MAX_LOGS_PER_RUN) {
-      this.droppedCount++;
-      return;
-    }
-    this.loggedCount++;
-    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;
@@ -1069,16 +1205,7 @@ var RunReporter = class {
     }
   }
   takeLogs() {
-    const logs = this.buffer.splice(0, this.buffer.length);
-    if (this.droppedCount > 0) {
-      logs.push({
-        ts: nowISO(),
-        level: "warning",
-        message: `${this.droppedCount} logs descartados (limite de ${MAX_LOGS_PER_RUN} por execu\xE7\xE3o)`
-      });
-      this.droppedCount = 0;
-    }
-    return logs;
+    return this.buffer.splice(0, this.buffer.length);
   }
   /** Flush incremental: envia o buffer como status 'running' (em chunks). */
   flushLogs() {
@@ -1129,6 +1256,130 @@ 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.
+   */
+  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);
@@ -1438,11 +1689,13 @@ 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 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));