hobots 1.9.0 → 1.9.2

package/docs/api-reference.md

@@ -128,6 +128,19 @@ O teto da fila do transport (200 itens; ao encher, o **mais antigo** é descarta
 | `tags` | `Record<string,string>` | tags só deste evento |
 | `extra` | `Record<string,unknown>` | dados extras |
 | `fingerprint` | `string[]` | agrupamento manual |
+| `attachment` | `AttachInput \| CaptureAttachment` | print enviado junto da captura — dentro de uma execução de task, vira anexo da linha de log da run que espelha o evento; fora de uma execução é descartado com aviso. Guia: [Anexos](./tasks.md#anexos-screenshots) |
+
+### CaptureAttachment
+
+`AttachInput = Uint8Array | ArrayBuffer | string` (bytes ou um caminho de arquivo, só em Node). Para legenda ou content-type, passe o objeto:
+
+| Campo | Tipo | Default | O que faz |
+| --- | --- | --- | --- |
+| `image` | `AttachInput` | — | a imagem em si |
+| `caption` | `string` | — | legenda exibida sob a imagem ampliada; truncada em 200 caracteres e passada pelo scrub de segredos |
+| `contentType` | `'image/png' \| 'image/jpeg' \| 'image/webp'` | detectado pelos *magic bytes* | só usado quando a detecção falha; a detecção sempre tem precedência |
+
+O texto da linha de log é a mensagem capturada; o nível vem do `level` da captura (`'fatal'` vira `'error'`). O upload roda em segundo plano e **nunca bloqueia nem faz a captura lançar**. Limites (todos aplicados também no servidor): PNG/JPEG/WEBP, **5 MB** por imagem, **20** anexos por execução, **4** por linha de log.
 
 `Severity = 'fatal' | 'error' | 'warning' | 'info' | 'debug' | 'success'`. O que cada nível significa (e por que `'success'` existe) em [Level](./concepts.md#level-severity).
 
@@ -159,7 +172,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: Uint8Array | ArrayBuffer | string, options?: AttachOptions): Promise<AttachResult>;
 }
 ```
 
@@ -169,26 +181,8 @@ interface RunContext {
 - **`signal`** — `AbortSignal` que dispara em cancelamento no app, timeout ou shutdown.
 - **`throwIfCanceled()`** — o ponto de parada de uma linha: lança `RunCanceled` se o `signal` já disparou.
 - **`sleep(ms)`** — espera que respeita o `signal` (rejeita com `RunCanceled` em vez de dormir até o fim). Use no lugar do seu `sleep` em esperas longas.
-- **`attach(image, options?)`** — anexa um print à linha de log. Aceita bytes (`Uint8Array`/`ArrayBuffer`/`Buffer`) ou um caminho de arquivo (só em Node). A linha de log entra na hora; o upload é em segundo plano e **nunca lança**. Guia: [Anexos](./tasks.md#anexos-screenshots).
-
-### AttachOptions
-
-| Campo | Tipo | Default | O que faz |
-| --- | --- | --- | --- |
-| `caption` | `string` | — | legenda exibida sob a imagem ampliada; truncada em 200 caracteres e passada pelo scrub de segredos |
-| `level` | `RunLogLevel` | `'info'` | nível da linha de log que carrega o anexo |
-| `message` | `string` | `caption` ou `'captura de tela'` | texto da linha de log |
-| `contentType` | `'image/png' \| 'image/jpeg' \| 'image/webp'` | detectado pelos *magic bytes* | só usado quando a detecção falha; a detecção sempre tem precedência |
-
-### AttachResult
-
-| Campo | Tipo | O que é |
-| --- | --- | --- |
-| `id` | `string` | id do anexo — o mesmo referenciado na linha de log |
-| `ok` | `boolean` | `true` quando o binário chegou ao S3 |
-| `reason` | `AttachFailureReason?` | `'too-large' \| 'quota' \| 'unsupported-format' \| 'read-failed' \| 'unsupported' \| 'upload-failed' \| 'canceled'` |
 
-Limites (todos aplicados também no servidor): PNG/JPEG/WEBP, **5 MB** por imagem, **20** anexos por execução, **4** por linha de log.
+Para anexar um print a uma linha de log da run, use o campo `attachment` do [`CaptureHint`](#capturehint) em `captureException`/`captureMessage` dentro do handler. Guia: [Anexos](./tasks.md#anexos-screenshots).
 
 ---
 

package/docs/concepts.md

@@ -369,7 +369,7 @@ Cada run carrega os **`params`** (o JSON validado do formulário) e chega ao seu
 
 Um **anexo** é uma imagem — na prática, um print da tela — vinculada a uma linha de log de uma [run](#run). Serve para responder "como estava a tela quando isso aconteceu?", pergunta que texto de log sozinho não responde. No app, aparece como miniatura logo abaixo da linha de log correspondente, na aba "logs do agente" da execução.
 
-Quem captura é o seu código; o SDK só recebe a imagem pronta via [`ctx.attach()`](./tasks.md#anexos-screenshots).
+Quem captura é o seu código; o SDK só recebe a imagem pronta, via o campo [`attachment`](./tasks.md#anexos-screenshots) de `captureException`/`captureMessage`.
 
 **O binário não passa pela API do Hobots.** O agente pede uma URL presignada, sobe direto no S3 e depois confirma. Isso mantém a API livre de tráfego pesado e permite imagens bem maiores do que o limite de corpo de um PATCH. O ciclo de vida de um anexo é:
 

package/docs/getting-started.md

@@ -88,7 +88,7 @@ Hobots.init({
 
 Hobots.register('processar-nfe', async (params, ctx) => {
   ctx.log.info(`processando lote ${params.lote}…`);
-  // await ctx.attach(await page.screenshot(), { caption: 'portal após o login' }); // print junto do log
+  // Hobots.captureMessage('portal após o login', 'info', { attachment: await page.screenshot() }); // print junto do log
   ctx.log.info('12 notas processadas'); // o retorno do handler é ignorado — reporte por log
 });
 Hobots.start(); // mantém o processo vivo até stop()/close()

package/docs/tasks.md

@@ -52,7 +52,6 @@ interface RunContext {
   signal: AbortSignal;
   throwIfCanceled(): void;
   sleep(ms: number): Promise<void>;
-  attach(image, options?): Promise<AttachResult>; // anexa um print a uma linha de log
 }
 ```
 
@@ -62,7 +61,6 @@ interface RunContext {
 - **`ctx.signal`** — `AbortSignal` que dispara quando a run é **cancelada no app**, em **timeout** ou no **shutdown**. Cancelamento é cooperativo (veja abaixo).
 - **`ctx.throwIfCanceled()`** — lança `RunCanceled` se o `signal` já disparou. O ponto de parada de 1 linha para chamar entre as etapas do trabalho.
 - **`ctx.sleep(ms)`** — sleep que respeita o `signal`: rejeita com `RunCanceled` no cancelamento em vez de esperar até o fim. Use no lugar do seu `sleep` em esperas longas.
-- **`ctx.attach(image, options?)`** — anexa um print da tela a uma linha de log (veja [Anexos](#anexos-screenshots) abaixo).
 - **Retorno** — **ignorado**. O SDK não captura nem envia o valor retornado pelo handler ao servidor — resultados de execução podem conter dados sensíveis e não são coletados.
 - **Erro lançado** — a run é reportada como `failed` com tipo/mensagem/stack (mensagem cap 10k, stack 20k).
 
@@ -72,18 +70,22 @@ Você pode tipar os params: `Hobots.register<{ lote: number }>(...)`.
 
 ## 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, e ela aparece como miniatura logo abaixo dela na aba "logs do agente" da execução — 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(error, hint)` e `Hobots.captureMessage(message, level, hint)` — 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, e aparece como miniatura logo abaixo dela na aba "logs do agente" da execução — 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) {
     // numa falha é justamente quando o print importa
-    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;
   }
 });
@@ -93,20 +95,22 @@ Hobots.register('processar-nfe', async (params, ctx) => {
 
 ### O que aceita
 
+O `attachment` pode ser a imagem direto, ou um objeto com metadados:
+
 | Entrada | Exemplo |
 | --- | --- |
 | bytes | `Uint8Array`, `ArrayBuffer` ou `Buffer` — `await page.screenshot()` |
 | caminho de arquivo | `'C:\\prints\\tela.png'` (só em Node) |
+| objeto | `{ image, caption?, contentType? }` |
 
-### Opções
-
-| Opção | Tipo | Default | O que faz |
+| Campo do objeto | Tipo | Default | O que faz |
 | --- | --- | --- | --- |
+| `image` | bytes ou caminho | — | a imagem em si |
 | `caption` | `string` | — | legenda curta exibida sob a imagem ampliada (máx. 200 caracteres) |
-| `level` | `RunLogLevel` | `'info'` | nível da linha de log que carrega o anexo |
-| `message` | `string` | a legenda, ou `'captura de tela'` | texto da linha de log |
 | `contentType` | `'image/png' \| 'image/jpeg' \| 'image/webp'` | detectado | só é usado quando os *magic bytes* não bastam |
 
+O texto da linha de log é a própria mensagem capturada (`message` do `captureMessage`, ou `Nome: mensagem` do erro no `captureException`); o nível vem do `level` da captura (`'fatal'` vira `'error'` no log da run).
+
 ### Limites
 
 | Limite | Valor |
@@ -121,9 +125,9 @@ Hobots.register('processar-nfe', async (params, ctx) => {
 
 A linha de log é registrada **na hora**, com o id do anexo; o upload roda em segundo plano. O binário vai direto para o S3 por uma URL presignada — não passa pela API do Hobots. Enquanto o upload não termina, o app mostra a miniatura como "enviando imagem…".
 
-`attach()` **nunca lança**. Todo insucesso vira `{ ok: false, reason }` e um aviso no log da run:
+O anexo **nunca faz a captura lançar**. Todo insucesso vira um aviso no log da run:
 
-| `reason` | Quando |
+| Motivo | Quando |
 | --- | --- |
 | `too-large` | acima de 5 MB |
 | `quota` | passou de 20 anexos na execução |
@@ -133,7 +137,9 @@ A linha de log é registrada **na hora**, com o id do anexo; o upload roda em se
 | `upload-failed` | falha de rede depois dos retries |
 | `canceled` | a run foi cancelada ou encerrada durante o upload |
 
-Você pode `await` para saber o desfecho, ou disparar sem esperar (`void ctx.attach(...)`) — antes de reportar o desfecho da run, o SDK aguarda os uploads pendentes por até 15 s, para a execução não terminar com miniaturas em "enviando…".
+O upload é sempre fire-and-forget — a captura retorna na hora. Antes de reportar o desfecho da run, o SDK aguarda os uploads pendentes por até 15 s, para a execução não terminar com miniaturas em "enviando…".
+
+> **Fora de uma execução:** `attachment` só funciona dentro de um handler de task — fora dele não existe log de run para pendurar a imagem, e o SDK descarta o anexo com um aviso no console (o evento em si é capturado normalmente).
 
 > **Dados sensíveis:** o print é enviado ao servidor **exatamente como está** — o SDK não borra nem recorta nada. Uma tela de portal costuma conter CPF, nome, saldo, número de documento. Capture apenas o necessário e evite prints de telas com dados de terceiros. Solicitantes (papel `requester`) só veem os anexos quando o projeto está com "mostrar logs para solicitantes" ligado, o mesmo gate dos logs.
 
@@ -178,6 +184,8 @@ Hobots.register('processar-nfe', async (params, ctx) => {
 
 Quando o cancelamento veio do app, a run já está `cancelada` no servidor — o erro `RunCanceled` lançado pelo handler é suprimido, nada é reportado por cima. Para lógica de limpeza antes de parar (fechar navegador, desfazer estado), use `try/finally` ou escute `ctx.signal` diretamente.
 
+Se o handler **nunca** checar `ctx.signal` (loop sem `throwIfCanceled()`, `sleep()` genérico em vez de `ctx.sleep()`), o SDK ainda assim não trava o agente: depois de `cancelGraceMs` (default `10_000`) a partir do disparo de `ctx.signal`, o agente desiste de esperar aquele handler e libera o slot de concorrência para novas runs — logando um aviso. Isso não mata o handler (ele pode continuar rodando em segundo plano, sem efeito no app já que a run está cancelada), só evita que uma run "zumbi" trave o agente inteiro num `concurrency` baixo.
+
 ## Encerramento inesperado
 
 Se o processo do agente **morre no meio de uma run**, a solicitação vira **falha** no app com erro `AgentTerminated` ("execução encerrada inesperadamente") — sem re-execução automática. Dois caminhos garantem isso:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hobots",
-  "version": "1.9.0",
+  "version": "1.9.2",
   "description": "SDK JavaScript da Hobots — telemetria (erros, transactions e heartbeats) e execução remota de tarefas sob demanda (tasks) para RPAs e integrações. Um único import e um único init().",
   "type": "module",
   "sideEffects": false,