hobots 1.8.1 → 1.9.0

package/README.md

@@ -264,6 +264,7 @@ interface RunContext {
   signal: AbortSignal;
   throwIfCanceled(): void; // lança RunCanceled se o signal já disparou
   sleep(ms: number): Promise<void>; // espera cancelável — rejeita com RunCanceled no abort
+  attach(image, options?): Promise<AttachResult>; // anexa um print a uma linha de log
 }
 ```
 
@@ -273,11 +274,43 @@ interface RunContext {
 - **`ctx.signal`** — `AbortSignal` que dispara quando a run é **cancelada no app**, em **timeout** ou no **shutdown**.
 - **`ctx.throwIfCanceled()`** — o ponto de parada de uma linha; lança `RunCanceled` se o `signal` já disparou.
 - **`ctx.sleep(ms)`** — espera que respeita o `signal` (rejeita com `RunCanceled` em vez de dormir até o fim).
+- **`ctx.attach(image, options?)`** — anexa um print da tela à linha de log (veja [Anexos](#anexos-screenshots) abaixo).
 - **Retorno** — **ignorado**: o SDK não captura nem envia o valor retornado pelo handler (resultados podem conter dados sensíveis e não são coletados).
 - **Erro lançado** — a run é reportada como `failed` (mensagem cap 10k, stack 20k).
 
 > **Dados sensíveis:** `ctx.log` e mensagens/stack de erros **são enviados ao servidor** e ficam visíveis no app. Não inclua senhas, tokens, dados pessoais ou qualquer informação sensível em logs e mensagens de erro.
 
+### Anexos (screenshots)
+
+Texto de log conta o que o robô fez; um print conta **como estava a tela**. `ctx.attach()` anexa uma imagem a uma linha de log — no app ela aparece como miniatura logo abaixo dessa linha, clicável para ampliar.
+
+```js
+Hobots.register('processar-nfe', async (params, ctx) => {
+  await entrar();
+  await ctx.attach(await page.screenshot(), { caption: 'portal após o login' });
+
+  try {
+    await emitir(params);
+  } catch (erro) {
+    await ctx.attach(await page.screenshot(), { caption: 'tela no momento do erro', level: 'error' });
+    throw erro;
+  }
+});
+```
+
+**O SDK não tira o print** — ele recebe a imagem pronta, de onde você quiser (Playwright, Puppeteer, uma lib de captura de desktop, um arquivo em disco). Aceita bytes (`Uint8Array`/`ArrayBuffer`/`Buffer`) ou um caminho de arquivo (só em Node).
+
+| Limite | Valor |
+| --- | --- |
+| formatos | PNG, JPEG, WEBP |
+| tamanho por imagem | 5 MB |
+| anexos por execução | 20 |
+| anexos por linha de log | 4 |
+
+A linha de log é registrada **na hora**; o upload roda em segundo plano e vai direto para o S3 por URL presignada, sem passar pela API. `attach()` **nunca lança** — falhas viram `{ ok: false, reason }` e um aviso no log da run, então `void ctx.attach(...)` é seguro. Detalhes e a lista de `reason` em [Anexos](./docs/tasks.md#anexos-screenshots).
+
+> **Dados sensíveis:** o print é enviado **exatamente como está** — o SDK não borra nem recorta nada, e telas de portal costumam conter CPF, nome e valores. Capture só o necessário. Solicitantes só veem os anexos quando o projeto está com "mostrar logs para solicitantes" ligado, o mesmo gate dos logs.
+
 ### Cancelamento cooperativo
 
 Uma run cancelada no app **não mata** o handler — o SDK apenas dispara `ctx.signal`. Chame **`ctx.throwIfCanceled()`** em loops longos e pontos de parada (e troque esperas longas por `ctx.sleep()`):

package/dist/index.cjs

@@ -161,7 +161,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";
 }
@@ -328,6 +328,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;
@@ -377,7 +378,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(),
@@ -409,7 +418,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) {
@@ -882,6 +891,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);
@@ -976,8 +987,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",
@@ -1046,7 +1172,8 @@ 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;
@@ -1059,6 +1186,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;
   }
@@ -1077,6 +1212,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,
@@ -1094,15 +1231,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;
@@ -1170,6 +1314,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);
@@ -1479,11 +1747,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));