hobots 3.3.0 → 3.4.0

package/dist/protocol.d.cts

@@ -204,7 +204,7 @@ type RunItemStatus = 'succeeded' | 'failed' | 'occurrence';
 interface RunItemInput {
     /**
      * Identidade do item dentro da run — id de negócio do dev (ex.: nº da nota)
-     * ou uuid4-hex gerado pelo SDK. Repetido na mesma run = ignorado (primeiro vence).
+     * ou uuid4-hex gerado pelo SDK. Repetido na mesma run = upsert (vale o último reporte).
      */
     id: string;
     /** Ordem de emissão no agente (contador monotônico por run) */
@@ -216,6 +216,8 @@ interface RunItemInput {
     payload?: Record<string, unknown>;
     /** ISO 8601 — relógio do agente, apenas para exibição */
     ts?: string;
+    /** Ids de anexo (print do item) — opcional; mesmo teto por entrada das linhas de log */
+    attachments?: string[];
 }
 /** POST /v1/tasks/runs/{id}/items — aceito mesmo com a run cancelada/terminal */
 interface RunItemsCreateRequest {
@@ -231,13 +233,13 @@ interface RunItemsCreateResponse {
 type RunAttachmentContentType = 'image/png' | 'image/jpeg' | 'image/webp';
 /** POST /v1/tasks/runs/{id}/attachments */
 interface RunAttachmentCreateRequest {
-    /** Id do anexo gerado pelo agente (32 hex) — já referenciado na linha de log */
+    /** Id do anexo gerado pelo agente (32 hex) — já referenciado no log/item/step que o carrega */
     id: string;
     content_type: RunAttachmentContentType;
     /** Tamanho exato do binário; o PUT presignado é assinado com este Content-Length */
     size_bytes: number;
     caption?: string;
-    /** ISO 8601 — ts da linha de log que referencia o anexo */
+    /** ISO 8601 — ts do evento (log/item/step) que referencia o anexo */
     log_ts?: string;
     width?: number;
     height?: number;

package/dist/protocol.d.ts

@@ -204,7 +204,7 @@ type RunItemStatus = 'succeeded' | 'failed' | 'occurrence';
 interface RunItemInput {
     /**
      * Identidade do item dentro da run — id de negócio do dev (ex.: nº da nota)
-     * ou uuid4-hex gerado pelo SDK. Repetido na mesma run = ignorado (primeiro vence).
+     * ou uuid4-hex gerado pelo SDK. Repetido na mesma run = upsert (vale o último reporte).
      */
     id: string;
     /** Ordem de emissão no agente (contador monotônico por run) */
@@ -216,6 +216,8 @@ interface RunItemInput {
     payload?: Record<string, unknown>;
     /** ISO 8601 — relógio do agente, apenas para exibição */
     ts?: string;
+    /** Ids de anexo (print do item) — opcional; mesmo teto por entrada das linhas de log */
+    attachments?: string[];
 }
 /** POST /v1/tasks/runs/{id}/items — aceito mesmo com a run cancelada/terminal */
 interface RunItemsCreateRequest {
@@ -231,13 +233,13 @@ interface RunItemsCreateResponse {
 type RunAttachmentContentType = 'image/png' | 'image/jpeg' | 'image/webp';
 /** POST /v1/tasks/runs/{id}/attachments */
 interface RunAttachmentCreateRequest {
-    /** Id do anexo gerado pelo agente (32 hex) — já referenciado na linha de log */
+    /** Id do anexo gerado pelo agente (32 hex) — já referenciado no log/item/step que o carrega */
     id: string;
     content_type: RunAttachmentContentType;
     /** Tamanho exato do binário; o PUT presignado é assinado com este Content-Length */
     size_bytes: number;
     caption?: string;
-    /** ISO 8601 — ts da linha de log que referencia o anexo */
+    /** ISO 8601 — ts do evento (log/item/step) que referencia o anexo */
     log_ts?: string;
     width?: number;
     height?: number;

package/docs/api-reference.md

@@ -25,17 +25,18 @@ ESM e CommonJS (`const { hobots } = require('hobots')`), com `.d.ts`. Depois da
 | --- | --- | --- |
 | `runId`, `task` | `string` | Identidade da execução (`''` fora de uma execução) |
 | `params` | `Record<string, unknown>` | Params da solicitação; `{}` no modo start |
-| `log` | `RunLogger` — `debug/info/warn/error/success(message, ...rest)` | Nunca lança. Vários argumentos viram texto unidos por espaço (como `console.log`) |
-| `items` | `RunItems` — `add(item)`, `succeeded(payload?, opts?)`, `failed(message, payload?, opts?)`, `occurrence(message, payload?, opts?)`; `opts.id` = identidade de negócio. `each(list, (element, item, index) => …, { id?, payload?, op?, description?, progress? }) => Promise<{ total, succeeded, failed, occurrence }>` processa a lista inteira: exceção no handler vira item `failed` + step em erro e o loop segue; `item: RunItemHandle` = `succeeded/failed/occurrence`, `id`, `index`, `step`, `reported` | Ponto de parada cooperativo (o `each` para só em cancelamento/timeout) |
+| `log` | `RunLogger` — `debug/info/warn/error/success(message, ...rest)` | Nunca lança. Vários argumentos viram texto unidos por espaço (como `console.log`); um `hobots.image(...)` no **último** argumento vira o print da linha |
+| `items` | `RunItems` — `add(item)`, `succeeded(payload?, opts?)`, `failed(message, payload?, opts?)`, `occurrence(message, payload?, opts?)`; `opts.id` = identidade de negócio, `opts.image` = print do item. `each(list, (element, item, index) => …, { id?, payload?, op?, description?, progress? }) => Promise<{ total, succeeded, failed, occurrence }>` processa a lista inteira: exceção no handler vira item `failed` + step em erro e o loop segue; `item: RunItemHandle` = `succeeded(payload?, { image }?)/failed(msg, payload?, { image }?)/occurrence(…)`, `id`, `index`, `step`, `reported` | Ponto de parada cooperativo (o `each` para só em cancelamento/timeout) |
 | `progress` | `RunProgressReporter` — `total(n)`, `advance(count = 1)`, `set(current, total?)`, `current`, `snapshot` | `total/advance/set` são pontos de parada |
-| `transaction` | `Transaction` — `startChild(op?, description?)`, `setTag`, `setStatus`, `setName`; `Step` — `startChild`, `setStatus('ok' \| 'warning' \| 'error', message?)`, `setError(err, message?)` (motivo em `data.error`, exibido na Central), `setData(k, v)`, `finish()` | Finalizada pelo SDK; `startChild` é ponto de parada |
+| `transaction` | `Transaction` — `startChild(op?, description?)`, `setTag`, `setStatus`, `setName`; `Step` — `startChild`, `setStatus('ok' \| 'warning' \| 'error', message?, { image }?)`, `setError(err, message?, { image }?)` (motivo em `data.error`, print em `data.attachments`, exibidos na Central), `setData(k, v)`, `finish()` | Finalizada pelo SDK; `startChild` é ponto de parada |
 | `signal` | `AbortSignal` | Cancelamento (app, timeout, shutdown) |
 | `throwIfCanceled()` | `() => void` | Lança `RunCanceled` se o signal disparou |
 | `sleep(ms)` | `(ms: number) => Promise<void>` | Rejeita com `RunCanceled` no cancelamento |
-| `attach(image, options?)` | `(image: AttachInput, options?: AttachOptions) => Promise<AttachResult>` | `AttachInput = Uint8Array \| ArrayBuffer \| string` (caminho); `AttachOptions = { caption?, level?, message?, contentType? }`; `AttachResult = { id, ok, reason? }`. Nunca lança |
 | `retry(fn, options?)` | como `hobots.retry` | |
 
-Fora de uma execução, `hobots.*` cai em fallbacks seguros com aviso único por membro (log ecoa no terminal; items/progress no-op; `signal` nunca aborta; `attach` resolve `{ ok: false }`).
+`hobots.image(input, options?)` — `(input: AttachInput, options?: ImageOptions) => ImageAttachment`; `AttachInput = Uint8Array \| ArrayBuffer \| string` (caminho); `ImageOptions = { caption?, contentType? }`; `ImageInput = AttachInput \| ImageAttachment` é o que `log.*` (só o embrulho), `items.*` e `step.setStatus/setError` aceitam. Puro, nunca lança; o upload (segundo plano, nunca bloqueia) acontece quando o evento é registrado.
+
+Fora de uma execução, `hobots.*` cai em fallbacks seguros com aviso único por membro (log ecoa no terminal, imagem descartada; items/progress no-op; `signal` nunca aborta).
 
 ## Tabelas de opções
 
@@ -88,7 +89,7 @@ Fora de uma execução, `hobots.*` cai em fallbacks seguros com aviso único por
 | --- | --- | --- |
 | `type` | `'fatal' \| 'error' \| 'warning' \| 'success'` | default `'error'` |
 | `tags`, `extra`, `fingerprint` | | metadados do evento (`fingerprint` sobrescreve o agrupamento) |
-| `attachment` | `AttachInput \| { image, caption?, contentType? }` | print anexado à linha de log da execução atual |
+| `attachment` | `ImageInput \| { image, caption?, contentType? }` | print anexado à linha de log da execução atual |
 
 ### `TaskHandler`
 

package/docs/protocol.md

@@ -117,7 +117,7 @@ Corpo `RunUpdateRequest`:
   "logs":   [
     { "ts": "…", "level": "info", "message": "…" },            // delta; o servidor concatena
     { "ts": "…", "level": "info", "message": "portal após o login",
-      "attachments": ["<32 hex>"] }                            // opcional; ids de anexo (máx. 4)
+      "attachments": ["<32 hex>"] }                            // opcional; ids de anexo (máx. 4) — hobots.image() no log
   ],
   "error":  { "type": "Error", "message": "…", "stack": "…" },  // só com 'failed'
   "progress": { "current": 10, "total": 100 }                     // opcional: snapshot de hobots.progress
@@ -149,13 +149,16 @@ Corpo `RunItemsCreateRequest`:
       "status": "succeeded",             // 'succeeded' | 'failed' | 'occurrence'
       "message": "…",                    // opcional — motivo (failed/occurrence), máx. 2100
       "payload": { "numero_nota": "12345", "cnpj_prestador": "…" },  // opcional, máx. 16 KB
-      "ts": "2026-08-10T12:00:00.000Z"   // opcional — relógio do agente, só exibição
+      "ts": "2026-08-10T12:00:00.000Z",  // opcional — relógio do agente, só exibição
+      "attachments": ["<32 hex>"]        // opcional — ids de anexo (máx. 4): print do item
     }
   ]
 }
 ```
 
-Resposta `200` `RunItemsCreateResponse`: `{ "accepted": 1, "duplicates": 0 }` — `duplicates` conta os ignorados por `(run, id)` repetido.
+Resposta `200` `RunItemsCreateResponse`: `{ "accepted": 1, "duplicates": 0 }` — `duplicates` conta os colapsados por `(run, id)` repetido no mesmo lote (vale o último reporte; no banco é upsert).
+
+- `attachments` é **opcional** e aditivo (uma API anterior ao recurso descarta o campo). As steps carregam o print do mesmo jeito, em `data.attachments` do `StepData` que vai no `POST /v1/ingest` da transaction — sem campo novo no wire.
 
 - **Run cancelada/terminal aceita itens** (200): item é fato de trabalho já feito — mesmo racional do log tardio. Esta rota não tem 409.
 - O insert e os **contadores materializados** da run (`items_total/succeeded/failed/occurrence`, que alimentam os totalizadores no app) saem num único statement atômico no servidor.
@@ -177,11 +180,11 @@ Corpo `RunAttachmentCreateRequest`:
 
 ```jsonc
 {
-  "id": "<32 hex>",              // gerado pelo agente, já referenciado na linha de log
+  "id": "<32 hex>",              // gerado pelo agente, já referenciado no log/item/step
   "content_type": "image/png",   // 'image/png' | 'image/jpeg' | 'image/webp'
   "size_bytes": 184320,          // exato — entra na assinatura da URL
   "caption": "portal após o login",  // opcional, máx. 500
-  "log_ts": "…",                 // opcional, ISO 8601 — ts da linha de log
+  "log_ts": "…",                 // opcional, ISO 8601 — ts do evento (log/item/step)
   "width": 1920, "height": 1080  // opcionais
 }
 ```
@@ -216,7 +219,7 @@ Confirma o upload. Corpo `RunAttachmentConfirmRequest`: `{ "status": "uploaded"
 
 É **conforto de UX**, não correção: enquanto não confirmado, o app mostra a miniatura como "enviando imagem…". O agente engole falhas desta chamada.
 
-Limites de anexo (aplicados no SDK **e** no servidor): PNG/JPEG/WEBP, 5 MB por imagem, 20 por execução, 4 por linha de log.
+Limites de anexo (aplicados no SDK **e** no servidor): PNG/JPEG/WEBP, 5 MB por imagem, 20 por execução, 4 por evento (linha de log, item ou step).
 
 ## Onde vive o claim atômico
 

package/docs/tasks.md

@@ -40,11 +40,11 @@ Isso funciona com `concurrency > 1` porque cada execução roda no seu contexto
 
 | Membro | Notas |
 | --- | --- |
-| `hobots.log.<debug\|info\|warn\|error\|success>(msg)` | Enviado incrementalmente (PATCHes com throttle) e ecoado no terminal. Nunca lança. |
+| `hobots.log.<debug\|info\|warn\|error\|success>(msg, ...rest)` | Enviado incrementalmente (PATCHes com throttle) e ecoado no terminal. Nunca lança. `hobots.image(...)` no último argumento = print da linha. |
 | `hobots.items` | Ver [Itens](#itens-de-execução-hobotsitems) |
 | `hobots.progress` | Ver [Progresso](#progresso-hobotsprogress) |
 | `hobots.transaction` | Transaction da execução, já correlacionada e finalizada pelo SDK. `startChild(op, descrição)` = uma step no waterfall. |
-| `hobots.attach(imagem, opts?)` | Ver [Anexos](#anexos-screenshots) |
+| `hobots.image(imagem, opts?)` | Ver [Imagens](#imagens-screenshots) |
 | `hobots.captureException(erro, hint?)` | Issue no módulo Issues; `hint.attachment` anexa um print à linha de log |
 | `hobots.retry(fn, opts?)` | Ver [Retry](#retry) |
 | `hobots.sleep(ms)` · `hobots.signal` · `hobots.throwIfCanceled()` | Ver [Cancelamento](#cancelamento-cooperativo) |
@@ -124,20 +124,39 @@ for (const nota of notas) {
 
 Opcional e independente de `items`. Sem `total()` nada é enviado. Snapshot absoluto que pega carona nos PATCHes de log (no pior caso 1/s); o PATCH terminal leva o valor final. `set(atual, total?)`, `current` e `snapshot` completam a API. `total/advance/set` são pontos de parada cooperativos; `current`/`snapshot` nunca lançam.
 
-## Anexos (screenshots)
+## Imagens (screenshots)
+
+Um print vai **junto do evento** que ele ilustra — a linha de log, o item ou a step — para o
+usuário ver o estado do robô no momento em que aquilo aconteceu (botão de imagem no app):
 
 ```js
-await hobots.attach(await page.screenshot(), { caption: 'portal após o login' });
+// na linha de log: hobots.image(...) como ÚLTIMO argumento
+hobots.log.info('portal após o login', hobots.image(await page.screenshot()));
+hobots.log.error('login falhou', hobots.image(await page.screenshot(), { caption: 'tela do erro' }));
+
+// no item
+hobots.items.failed('nota rejeitada', { numero }, { image: await page.screenshot() });
+await hobots.items.each(notas, async (nota, item) => {
+  …
+  item.occurrence('sem fatura no mês', undefined, { image: await page.screenshot() });
+});
 
+// na step
+const step = hobots.transaction.startChild('emitir', numero);
 try {
-  await emitir(params);
+  await emitir(numero);
 } catch (erro) {
-  hobots.captureException(erro, { attachment: { image: await page.screenshot(), caption: 'tela no momento do erro' } });
+  step.setError(erro, undefined, { image: await page.screenshot() });
   throw erro;
+} finally {
+  step.finish();
 }
+
+// numa issue (módulo Issues) — o print vai na linha de log que espelha o erro
+hobots.captureException(erro, { attachment: hobots.image(await page.screenshot(), { caption: 'tela no momento do erro' }) });
 ```
 
-O SDK não tira o print: aceita bytes (`Uint8Array`/`ArrayBuffer`/`Buffer`) ou um caminho de arquivo. A linha de log entra na hora; o upload sobe em segundo plano direto para o S3 (URL presignada) e **nunca lança nem bloqueia** — falhas viram um aviso no log da execução. Limites: PNG/JPEG/WEBP, 5 MB, 20 por execução, 4 por linha de log. Fora de uma execução não há onde pendurar a imagem (descartada com aviso).
+O SDK não tira o print: aceita bytes (`Uint8Array`/`ArrayBuffer`/`Buffer`) ou um caminho de arquivo, crus ou embrulhados por `hobots.image(bytes, { caption?, contentType? })` (só o embrulho leva legenda; em `log.*` ele é obrigatório para distinguir a imagem de um argumento comum). O evento entra na hora com o id do anexo; o upload sobe em segundo plano direto para o S3 (URL presignada) e **nunca lança nem bloqueia** — falhas viram um aviso no log da execução. Limites: PNG/JPEG/WEBP, 5 MB, 20 por execução, 4 por evento. Fora de uma execução não há onde pendurar a imagem (descartada com aviso). O `hobots.attach` das versões anteriores foi removido nesta API.
 
 ## Cancelamento cooperativo
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "hobots",
-  "version": "3.3.0",
-  "description": "SDK JavaScript da Hobots \u2014 tudo \u00e9 uma task: register() atende solicita\u00e7\u00f5es da plataforma, start() roda sempre e reporta logs, itens e progresso. Credenciais por env, heartbeat sempre ligado, objeto global `hobots`.",
+  "version": "3.4.0",
+  "description": "SDK JavaScript da Hobots — tudo é uma task: register() atende solicitações da plataforma, start() roda sempre e reporta logs, itens e progresso. Credenciais por env, heartbeat sempre ligado, objeto global `hobots`.",
   "type": "module",
   "sideEffects": false,
   "license": "MIT",
@@ -33,11 +33,13 @@
     "dev": "tsup --watch",
     "lint": "eslint . --max-warnings 0",
     "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit"
   },
   "devDependencies": {
     "@types/node": "^20",
+    "@vitest/coverage-v8": "^4.1.10",
     "@workspace/eslint-config": "workspace:*",
     "@workspace/typescript-config": "workspace:*",
     "@workspace/utils": "workspace:*",