hobots 1.9.0 → 1.9.1

package/README.md

@@ -264,7 +264,6 @@ 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
 }
 ```
 
@@ -274,7 +273,6 @@ 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).
 
@@ -282,23 +280,27 @@ interface RunContext {
 
 ### 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.
+Texto de log conta o que o robô fez; um print conta **como estava a tela**. Os métodos de captura (`Hobots.captureException` e `Hobots.captureMessage`) aceitam um `attachment` no hint: dentro de uma execução de task, a imagem vira anexo da linha de log da run que espelha a captura — 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' });
+  Hobots.captureMessage('portal após o login', 'info', {
+    attachment: await page.screenshot(),
+  });
 
   try {
     await emitir(params);
   } catch (erro) {
-    await ctx.attach(await page.screenshot(), { caption: 'tela no momento do erro', level: 'error' });
+    Hobots.captureException(erro, {
+      attachment: { image: await page.screenshot(), caption: 'tela no momento do erro' },
+    });
     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).
+**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). O `attachment` aceita bytes (`Uint8Array`/`ArrayBuffer`/`Buffer`), um caminho de arquivo (só em Node) ou um objeto `{ image, caption?, contentType? }`.
 
 | Limite | Valor |
 | --- | --- |
@@ -307,7 +309,7 @@ Hobots.register('processar-nfe', async (params, ctx) => {
 | 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).
+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 — a captura **nunca bloqueia nem lança** por causa do anexo (falhas viram um aviso no log da run). Fora de uma execução de task não há onde pendurar a imagem: o `attachment` é descartado com um aviso. Detalhes 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.
 

package/dist/index.cjs

@@ -1172,8 +1172,7 @@ var RunReporter = class {
       throwIfCanceled: () => {
         if (signal.aborted) throw runCanceledError();
       },
-      sleep: (ms) => cancelableSleep(ms, signal),
-      attach: (image, options) => this.attach(image, options)
+      sleep: (ms) => cancelableSleep(ms, signal)
     };
   }
   context;
@@ -1318,7 +1317,8 @@ var RunReporter = class {
   /**
    * 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.
+   * 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();
@@ -1505,6 +1505,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"];
@@ -1746,7 +1749,10 @@ 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();
@@ -1836,10 +1842,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) {