hobots 1.9.0 → 1.9.2

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

@@ -161,7 +161,7 @@ function scrubSecrets(text) {
 
 // src/utils.ts
 var SDK_NAME = "hobots";
-var SDK_VERSION = true ? "1.9.0" : "0.0.0-dev";
+var SDK_VERSION = true ? "1.9.1" : "0.0.0-dev";
 function isNode() {
   return typeof process !== "undefined" && typeof process.versions?.node === "string";
 }
@@ -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"];
@@ -1556,6 +1559,7 @@ var MIN_POLL_INTERVAL_MS = 1e3;
 var MAX_CONCURRENCY = 5;
 var POLL_RETRY_DELAYS_MS = [1e3, 4e3, 16e3];
 var AUTH_FAILURE_INTERVAL_MS = 3e4;
+var DEFAULT_CANCEL_GRACE_MS = 1e4;
 function hostname() {
   if (!isNode()) return void 0;
   return process.env.HOSTNAME || process.env.COMPUTERNAME || void 0;
@@ -1574,6 +1578,7 @@ var TaskAgent = class {
     this.taskTimeoutMs = options.taskTimeoutMs;
     this.logFlushIntervalMs = options.logFlushIntervalMs;
     this.cancelCheckIntervalMs = options.cancelCheckIntervalMs;
+    this.cancelGraceMs = options.cancelGraceMs ?? DEFAULT_CANCEL_GRACE_MS;
     this.logger.debug("agente configurado", { baseUrl: config.tasksBaseUrl });
   }
   logger;
@@ -1585,6 +1590,7 @@ var TaskAgent = class {
   taskTimeoutMs;
   logFlushIntervalMs;
   cancelCheckIntervalMs;
+  cancelGraceMs;
   state = "idle";
   timer;
   pollAbort;
@@ -1746,7 +1752,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();
@@ -1766,14 +1775,26 @@ var TaskAgent = class {
   }
   async invokeWithTimeout(handler, run, reporter) {
     const invocation = Promise.resolve().then(() => handler(run.params, reporter.context));
-    if (!this.taskTimeoutMs || this.taskTimeoutMs <= 0) {
+    const races = [];
+    if (this.taskTimeoutMs && this.taskTimeoutMs > 0) {
+      races.push(sleep(this.taskTimeoutMs).then(() => TIMEOUT_SENTINEL));
+    }
+    if (this.cancelGraceMs > 0) {
+      races.push(waitForCancelGrace(reporter.context.signal, this.cancelGraceMs).then(() => CANCEL_SENTINEL));
+    }
+    if (races.length === 0) {
       await invocation;
       return;
     }
+    const outcome = await Promise.race([invocation, ...races]);
+    if (outcome !== TIMEOUT_SENTINEL && outcome !== CANCEL_SENTINEL) return;
+    if (outcome === CANCEL_SENTINEL) {
+      this.logger.warn(
+        `run ${run.id} cancelada \u2014 handler n\xE3o respondeu a ctx.signal em ${this.cancelGraceMs}ms, liberando o slot (o handler pode continuar rodando em segundo plano)`
+      );
+      return;
+    }
     const timeoutMs = this.taskTimeoutMs;
-    const timeout = sleep(timeoutMs).then(() => TIMEOUT_SENTINEL);
-    const outcome = await Promise.race([invocation, timeout]);
-    if (outcome !== TIMEOUT_SENTINEL) return;
     reporter.abort();
     invocation.then(() => this.logger.warn(`run ${run.id} terminou depois do timeout de ${timeoutMs}ms`)).catch(() => this.logger.warn(`run ${run.id} falhou depois do timeout de ${timeoutMs}ms (erro descartado)`));
     throw Object.assign(new Error(`timeout ap\xF3s ${timeoutMs}ms (o handler pode continuar em background)`), {
@@ -1782,6 +1803,16 @@ var TaskAgent = class {
   }
 };
 var TIMEOUT_SENTINEL = /* @__PURE__ */ Symbol("task-timeout");
+var CANCEL_SENTINEL = /* @__PURE__ */ Symbol("task-canceled");
+function waitForCancelGrace(signal, graceMs) {
+  return new Promise((resolve) => {
+    if (signal.aborted) {
+      setTimeout(resolve, graceMs);
+      return;
+    }
+    signal.addEventListener("abort", () => setTimeout(resolve, graceMs), { once: true });
+  });
+}
 var MAX_ERROR_MESSAGE_CHARS = 1e4;
 var MAX_ERROR_STACK_CHARS = 2e4;
 function toRunError(error) {
@@ -1836,10 +1867,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) {