hobots 3.3.0 → 4.0.0

package/docs/concepts.md

@@ -1,6 +1,6 @@
 # Conceitos
 
-Esta página explica **o que cada coisa é** — o vocabulário que as outras páginas usam: task, execução, item, evento, issue, transaction, step, heartbeat, instância, claim. As outras páginas mostram **como usar**; aqui está o **por que existe**.
+Esta página explica **o que cada coisa é** — o vocabulário que as outras páginas usam: agente, execução, item, evento, issue, transaction, step, heartbeat, instância, claim. As outras páginas mostram **como usar**; aqui está o **por que existe**.
 
 Defaults numéricos vivem em [Tempos e intervalos](./api-reference.md#tempos-e-intervalos) e nas [tabelas de opções](./api-reference.md#tabelas-de-opções).
 
@@ -8,14 +8,14 @@ Defaults numéricos vivem em [Tempos e intervalos](./api-reference.md#tempos-e-i
 
 | Conceito | Em uma frase | Quando você usa |
 | --- | --- | --- |
-| [Task](#task) | O que o robô sabe fazer, por slug | `hobots.register` / `hobots.start` |
+| [Agente](#agente) | O seu robô: um processo, uma coisa que ele faz | `hobots.register` / `hobots.start` |
 | [Modo sob demanda](#modo-sob-demanda-register) | Uma execução por solicitação do app | O trabalho é disparado por alguém (formulário, agendamento) |
 | [Modo sempre ligado](#modo-sempre-ligado-start) | O robô abre a própria execução e roda o seu loop | O robô vive rodando e você só quer ver o que ele faz |
-| [Execução (run)](#execução-run) | Uma rodada de uma task, com logs, itens e resultado | A unidade de tudo em Solicitações |
+| [Execução (run)](#execução-run) | Uma rodada do agente, com logs, itens e resultado | A unidade de tudo em Trabalhos |
 | [Item](#item) | Uma unidade de trabalho entregue | Cada nota, boleto, arquivo processado |
 | [Progresso](#progresso) | Quantos de quantos | Barra e tempo restante no app |
 | [Log da execução](#log-da-execução) | Narração do que a execução fez | `hobots.log` — nunca lança |
-| [Anexo](#anexo) | Um print pendurado numa linha de log | "Como estava a tela?" |
+| [Anexo](#anexo) | Um print pendurado num log, item ou step | "Como estava a tela?" |
 | [Cancelamento cooperativo](#cancelamento-cooperativo) | O app pede, o handler para no próximo ponto de parada | Automático em items/progress/steps/sleep/retry |
 | [Retry](#retry) | Tentar de novo na mesma execução | Instabilidade passageira |
 | [Evento e issue](#evento-e-issue) | A foto de um erro, agrupada em issue | `hobots.captureException` e erros não tratados |
@@ -31,39 +31,39 @@ Defaults numéricos vivem em [Tempos e intervalos](./api-reference.md#tempos-e-i
 
 | No SDK | No app |
 | --- | --- |
-| **Agente** — dono do Client Secret (`hb_…`) que autentica tudo | **Configurações → Agentes** |
-| **Instância** — o par `(agente, instanceId)`; heartbeat e tasks convergem nela | Módulo **Instâncias** (uptime, recursos da máquina, performance) |
-| **Task / execução** — `register('slug', …)` casa com o `task_slug` do formulário; `start('slug', …)` abre a própria execução | Módulo **Solicitações** (formulários em **Configurações → Formulários**) |
+| **Agente** — dono do Client Secret (`hb_…`) que autentica tudo; o que ele faz é o handler de `register()`/`start()` | **Configurações → Agentes** (o formulário do agente fica aqui) |
+| **Instância** — o par `(agente, instanceId)`; heartbeat e execuções convergem nela, com o modo (sob demanda / sempre ligado) | Módulo **Instâncias** (uptime, recursos da máquina, performance) |
+| **Execução** — cada solicitação atendida por `register()`, ou a execução que `start()` abre sozinho | Módulo **Trabalhos** |
 | **Evento** agrupado em **issue** — `captureException` e erros não tratados | Módulo **Issues** |
 | **Transaction / steps** — `hobots.transaction` | Aba de performance da execução |
 
 ---
 
-## Task
+## Agente
 
-Uma **task** é uma capacidade nomeada do robô — "processar NF-e", "monitorar a pasta de entrada" — identificada por um **slug** estável. Registrar uma task é a única forma de configurar o SDK: não há `init()`. A primeira chamada a `register()`/`start()` lê as credenciais do ambiente, liga o heartbeat e a captura de erros, e define as opções do processo (`environment`, `release`, `tags`…). Um slug só pode ser registrado uma vez.
+O **agente** é o seu robô: um programa que faz **uma coisa** — "processar NF-e", "monitorar a pasta de entrada". Na plataforma ele é identificado pelo Client Secret, não por um nome no código: o processo que sobe com aquele secret *é* o agente, e o handler que você passa a `register()`/`start()` *é* a tarefa. Essa chamada é a única forma de configurar o SDK: não há `init()`. Ela lê as credenciais do ambiente, liga o heartbeat e a captura de erros, define as opções (`environment`, `release`, `tags`, `items`…) e diz como o robô trabalha. **Uma chamada por processo** — a segunda lança. Um robô que faz duas coisas são dois agentes, cada um com o seu processo e o seu Client Secret.
 
 ## Modo sob demanda (`register`)
 
-O robô fica **online aguardando**: faz polling na plataforma e, quando alguém cria uma solicitação para aquele slug (pelo formulário ou por um agendamento), executa o handler com os `params` do formulário. É o modo para trabalho que **alguém pede**. Várias solicitações podem rodar em paralelo (`concurrency`).
+O robô fica **online aguardando**: faz polling na plataforma e, quando alguém cria uma solicitação para o agente (pelo formulário do agente ou por um agendamento), executa o handler com os `params` do formulário. É o modo para trabalho que **alguém pede**. Várias solicitações podem rodar em paralelo (`concurrency`). No painel a instância aparece como "sob demanda".
 
 ## Modo sempre ligado (`start`)
 
-O robô **não espera ninguém**: ao iniciar, abre a própria execução na plataforma (`source: agent`, sem formulário nem solicitante) e roda o handler dentro dela. O handler é o seu loop — um `while (true)` que vigia uma pasta, uma fila, um portal. A plataforma recebe logs, itens e progresso enquanto ele roda. Quando o handler retorna, a execução fecha; o processo continua vivo pelo heartbeat, então a instância segue online até `hobots.close()`. É **uma execução por processo**: para recomeçar, reinicie o robô. Como o servidor guarda no máximo 1000 linhas de log por execução, o trabalho feito vai em itens, não em log.
+O robô **não espera ninguém**: ao iniciar, abre a própria execução na plataforma (`source: agent`, sem formulário nem solicitante) e roda o handler dentro dela. O handler é o seu loop — um `while (true)` que vigia uma pasta, uma fila, um portal. A plataforma recebe logs, itens e progresso enquanto ele roda. Quando o handler retorna, a execução fecha; o processo continua vivo pelo heartbeat, então a instância segue online até `hobots.close()`. É **uma execução por processo**: para recomeçar, reinicie o robô. Como o servidor guarda no máximo 1000 linhas de log por execução, o trabalho feito vai em itens, não em log. No painel a instância aparece como "sempre ligado".
 
 ## Execução (run)
 
-Uma **execução** é uma rodada concreta de uma task — no app, uma solicitação. Ciclo de vida no servidor:
+Uma **execução** é uma rodada concreta do agente — no app, um trabalho. Ciclo de vida no servidor:
 
 ```
 pending → claimed → running → succeeded | failed | canceled
 ```
 
-No modo sob demanda a execução nasce `pending` (alguém pediu), vira `claimed` quando um agente a [reivindica](#claim) e `running` quando o handler começa. No modo sempre ligado ela já nasce `running`, criada pelo próprio robô. O agente só transiciona para `running`, `succeeded` e `failed`; `canceled` vem de alguém cancelando no app. Cada execução tem a sua transaction de performance, seus logs, itens e progresso — e o objeto `hobots` aponta para a execução **atual**, em qualquer módulo, graças ao contexto async do Node.
+No modo sob demanda a execução nasce `pending` (alguém pediu), vira `claimed` quando um agente a [reivindica](#claim) e `running` quando o handler começa. No modo sempre ligado ela já nasce `running`, criada pelo próprio robô. O agente só transiciona para `running`, `succeeded` e `failed`; `canceled` vem de alguém cancelando no app. Cada execução tem a sua transaction de performance (`run`), seus logs, itens e progresso — e o objeto `hobots` aponta para a execução **atual**, em qualquer módulo, graças ao contexto async do Node.
 
 ## Item
 
-Um **item** é uma unidade de trabalho que a execução entregou: uma nota baixada, um boleto emitido, um arquivo movido. Tem status (`succeeded`, `failed` = falha técnica, `occurrence` = ocorrência de negócio, como "nota não encontrada") e um `payload` de atributos livres que viram colunas na aba de itens da solicitação. O `id` é a identidade de negócio do item na execução — repetido, é ignorado: é isso que torna retries idempotentes. Diferente do log, o item é **dado estruturado**: dá para contar, filtrar e conferir.
+Um **item** é uma unidade de trabalho que a execução entregou: uma nota baixada, um boleto emitido, um arquivo movido. Tem status (`succeeded`, `failed` = falha técnica, `occurrence` = ocorrência de negócio, como "nota não encontrada") e um `payload` de atributos livres que viram colunas na aba de itens da execução — as colunas são declaradas no código, uma vez, pela opção `items` do agente. O `id` é a identidade de negócio do item na execução — repetido, o servidor atualiza em vez de duplicar: é isso que torna retries idempotentes. Diferente do log, o item é **dado estruturado**: dá para contar, filtrar e conferir.
 
 ## Progresso
 
@@ -71,11 +71,11 @@ O **progresso** é "quantos de quantos" (`current/total`). Declare o total antes
 
 ## Log da execução
 
-O **log da execução** narra o que aconteceu, em linhas com nível (`debug`, `info`, `warning`, `error`, `success`), enviadas incrementalmente e visíveis no app quase em tempo real. Ele é o único membro de `hobots` que **nunca lança**, justamente para poder ir num `finally` de limpeza. O servidor guarda até 1000 linhas por execução.
+O **log da execução** narra o que aconteceu, em linhas com nível (`debug`, `info`, `warning`, `error`, `success`), enviadas incrementalmente e visíveis no app quase em tempo real (e ecoadas no terminal como `[hobots] INFO …`). Ele é o único membro de `hobots` que **nunca lança**, justamente para poder ir num `finally` de limpeza. O servidor guarda até 1000 linhas por execução.
 
 ## Anexo
 
-Um **anexo** é uma imagem — na prática, um print — vinculada a uma linha de log. Responde "como estava a tela?" quando texto não basta. Quem captura é o seu código (Playwright, Puppeteer, um arquivo); o SDK sobe direto para o S3 por URL presignada, em segundo plano, sem atrasar o log. Enquanto sobe, o app mostra "enviando imagem…".
+Um **anexo** é uma imagem — na prática, um print — vinculada ao evento que ela ilustra: uma linha de log, um item ou uma step. Responde "como estava a tela?" quando texto não basta. Quem captura é o seu código (Playwright, Puppeteer, um arquivo); o SDK sobe direto para o S3 por URL presignada, em segundo plano, sem atrasar o log. Enquanto sobe, o app mostra "enviando imagem…".
 
 ## Cancelamento cooperativo
 
@@ -91,7 +91,7 @@ Um **evento** é a foto de um erro: tipo, mensagem, stack trace, tags, ambiente,
 
 ## Transaction
 
-Uma **transaction** é uma unidade de trabalho **medida**: começa, termina, e o que fica é quanto tempo levou. Cada execução tem exatamente uma, aberta e finalizada pelo SDK (`hobots.transaction`), correlacionada à execução pelo `run_id`. Você não cria transactions — só adiciona etapas.
+Uma **transaction** é uma unidade de trabalho **medida**: começa, termina, e o que fica é quanto tempo levou. Cada execução tem exatamente uma, chamada `run` (op `hobots.run`), aberta e finalizada pelo SDK (`hobots.transaction`), correlacionada à execução pelo `run_id`. Você não cria transactions — só adiciona etapas.
 
 ## Step
 
@@ -103,7 +103,7 @@ O **heartbeat** é o batimento "estou vivo", a cada 30 s. O servidor conhece a c
 
 ## instanceId
 
-A identidade da **instância** do robô: qual VM, qual container. Vem da env `HOBOTS_INSTANCE_ID` (ou da opção; sem os dois, o hostname) e deve ser **estável entre reinícios** — um valor novo a cada boot vira uma frota de robôs fantasmas. É a mesma identidade no heartbeat, no poll e na criação de execuções: um agente só no painel.
+A identidade da **instância** do robô: qual VM, qual container. Vem da env `HOBOTS_INSTANCE_ID` (ou da opção; sem os dois, o hostname) e deve ser **estável entre reinícios** — um valor novo a cada boot vira uma frota de robôs fantasmas. É a mesma identidade no heartbeat, no poll e na criação de execuções: um agente só no painel. A presença da instância também declara o **modo** (`on_demand` / `always_on`) e as colunas de itens do agente.
 
 ## Release e environment
 
@@ -111,7 +111,7 @@ A identidade da **instância** do robô: qual VM, qual container. Vem da env `HO
 
 ## Claim
 
-O **claim** é o ato de um agente reivindicar uma execução pendente. É **server-side e atômico** (`FOR UPDATE SKIP LOCKED`): dois agentes que fazem poll no mesmo instante recebem conjuntos disjuntos — nenhum lock vive no seu processo. O agente pede só o que consegue rodar (tasks com slot livre), então nunca reivindica trabalho para deixar parado.
+O **claim** é o ato de um agente reivindicar uma execução pendente. É **server-side e atômico** (`FOR UPDATE SKIP LOCKED`): dois agentes que fazem poll no mesmo instante recebem conjuntos disjuntos — nenhum lock vive no seu processo. O agente pede só o que consegue rodar (`max` = slots livres de `concurrency`), então nunca reivindica trabalho para deixar parado.
 
 ## Drain mode
 

package/docs/getting-started.md

@@ -12,8 +12,8 @@ Sem dependências de runtime. Requer **Node 18+** (usa o `fetch` global).
 
 | Conceito | Em uma frase |
 | --- | --- |
-| [Task](./concepts.md#task) | O que o robô sabe fazer, identificado por um slug — registrado com `register` (sob demanda) ou `start` (sempre ligado) |
-| [Execução (run)](./concepts.md#execução-run) | Uma rodada de uma task, com logs, itens, progresso e resultado — uma solicitação no app |
+| [Agente](./concepts.md#agente) | O seu robô — um processo, uma coisa que ele faz, iniciado com `register` (sob demanda) ou `start` (sempre ligado) |
+| [Execução (run)](./concepts.md#execução-run) | Uma rodada do agente, com logs, itens, progresso e resultado — um trabalho no app |
 | [Item](./concepts.md#item) | Uma unidade de trabalho entregue pela execução (nota baixada, boleto emitido) |
 | [Heartbeat](./concepts.md#heartbeat) | Batimento "estou vivo" — sempre ligado; o servidor acusa offline quando para |
 | [instanceId](./concepts.md#instanceid) | A identidade da instância do robô no painel |
@@ -21,24 +21,24 @@ Sem dependências de runtime. Requer **Node 18+** (usa o `fetch` global).
 
 ## Credenciais
 
-Cada agente tem **um Client Secret** (`hb_<64 hex>`), copiado em **Configurações → Agentes**. O SDK lê do ambiente, como as libs da AWS:
+Cada agente tem **um Client Secret** (`hb_<64 hex>`), copiado em **Configurações → Agentes**. O SDK lê do ambiente:
 
 ```bash
 export HOBOTS_CLIENT_SECRET=hb_<64 hex>
 export HOBOTS_INSTANCE_ID=vm-cliente-01   # opcional — sem ela, o hostname
 ```
 
-Também dá para passar `clientSecret`/`instanceId` nas opções da task (o snippet do app já vem assim). Em desenvolvimento, `HOBOTS_API_URL=http://localhost:3001` aponta para outra API; em produção é sempre `https://api2.hobots.app`.
+Também dá para passar `clientSecret`/`instanceId` nas opções de `register()`/`start()` (o snippet do app já vem assim). Em desenvolvimento, `HOBOTS_API_URL=http://localhost:3001` aponta para outra API; em produção é sempre `https://api2.hobots.app`.
 
-## Primeira task sob demanda (`register`)
+## Primeiro agente sob demanda (`register`)
 
-1. No app, crie um formulário em **Configurações → Formulários** com o `task_slug` `processar-nfe`.
+1. No app, abra o agente em **Configurações → Agentes** e monte o **formulário do agente** (os campos que cada solicitação vai carregar).
 2. No robô:
 
 ```js
 import hobots from 'hobots';
 
-hobots.register('processar-nfe', async params => {
+hobots.register(async params => {
   hobots.log.info(`lote ${params.lote}`);
   for (const nota of params.notas) {
     await baixar(nota);
@@ -50,14 +50,14 @@ hobots.register('processar-nfe', async params => {
 process.on('SIGINT', () => void hobots.close(15_000).then(() => process.exit(0)));
 ```
 
-3. Rode o robô: ele aparece online em **Instâncias** e fica aguardando. Crie uma solicitação pelo formulário — a execução aparece em **Solicitações** com logs em tempo real.
+3. Rode o robô: ele aparece online em **Instâncias** (modo "sob demanda") e fica aguardando. Crie uma solicitação pelo formulário — a execução aparece em **Trabalhos** com logs em tempo real.
 
-## Primeira task sempre ligada (`start`)
+## Primeiro agente sempre ligado (`start`)
 
 ```js
 import hobots from 'hobots';
 
-hobots.start('monitor-pasta', async () => {
+hobots.start(async () => {
   hobots.log.info('monitor iniciado');
   while (true) {
     await hobots.sleep(60_000); // cancelável — para se a execução for cancelada no app
@@ -66,10 +66,12 @@ hobots.start('monitor-pasta', async () => {
 });
 ```
 
-O robô abre a própria execução ao iniciar e ela aparece em **Solicitações** com origem "agente". Quando o handler retorna (ou é cancelado), a execução fecha; o processo continua vivo pelo heartbeat até `hobots.close()`.
+O robô abre a própria execução ao iniciar e ela aparece em **Trabalhos** com origem "agente". Quando o handler retorna (ou é cancelado), a execução fecha; o processo continua vivo pelo heartbeat até `hobots.close()`.
+
+> **Uma chamada por processo.** `register()` ou `start()`, nunca os dois — a segunda chamada lança. Um robô que faz duas coisas são dois agentes (dois processos, dois Client Secrets).
 
 ## Encerramento
 
 `hobots.close(timeoutMs?)` para o polling, espera as execuções em voo, para o heartbeat e faz o flush final. Sem handler próprio de `SIGINT`/`SIGTERM`, o SDK reporta as execuções ativas como `AgentTerminated` antes do processo morrer.
 
-Próximos passos: [Tasks](./tasks.md) para itens, progresso, anexos, cancelamento e retry; [Referência de API](./api-reference.md) para todas as opções.
+Próximos passos: [Execuções](./runs.md) para itens, progresso, anexos, cancelamento e retry; [Referência de API](./api-reference.md) para todas as opções.

package/docs/protocol.md

@@ -2,11 +2,11 @@
 
 O SDK é um **cliente HTTP puro**, sem dependências de runtime: ele só fala com o app da Hobots por HTTP. Não abre conexão com banco e **não** roda `SKIP LOCKED` — a reivindicação atômica de runs é server-side (veja o fim desta página).
 
-Os arquivos `src/protocol.ts` e `src/tasks/protocol.ts` são a **fonte de verdade do wire format**: o app valida os payloads com zod travados nesses tipos (`satisfies z.ZodType<...>`), então não podem sofrer drift. Todos os tipos são exportados por `hobots/protocol` (e reexportados pelo import raiz `hobots`).
+Os arquivos `src/protocol.ts` e `src/tasks/protocol.ts` são a **fonte de verdade do wire format**: o app valida os payloads com zod travados nesses tipos (`satisfies z.ZodType<...>`), então não podem sofrer drift. Todos os tipos são exportados por `hobots/protocol` (inclusive `InstanceMode` e `ItemsDeclaration`) (e reexportados pelo import raiz `hobots`).
 
 ## O Client Secret e os endpoints derivados
 
-Cada agente tem **um único Client Secret**, o mesmo para as duas capabilities:
+Cada agente tem **um único Client Secret**, o mesmo para as duas capabilities. O agente é a própria tarefa: não há slug de task no wire — o que o agente faz é identificado pelo secret; a instância só declara **como** trabalha (`mode`).
 
 ```
 hb_<64 hex>
@@ -15,10 +15,10 @@ hb_<64 hex>
 | Canal | Endpoint | Autenticação |
 | --- | --- | --- |
 | Telemetria (ingestão) | `POST <baseUrl>/v1/ingest` | `Authorization: Bearer <clientSecret>` |
-| Tasks (execução) | `<baseUrl>/v1/tasks/*` | `Authorization: Bearer <clientSecret>` |
+| Execuções (poll, runs, itens, anexos) | `<baseUrl>/v1/runs/*` | `Authorization: Bearer <clientSecret>` |
 | Anexos (binário) | URL presignada do S3 (PUT) | assinatura na própria URL — **sem** header `Authorization` |
 
-A credencial vem da opção `clientSecret` ou da env `HOBOTS_CLIENT_SECRET` (resolvida em `src/config.ts` no primeiro `register()`/`start()`, com a URL base `https://api2.hobots.app`). Em desenvolvimento a env `HOBOTS_API_URL` sobrescreve a URL base — apenas `http(s)`, e `http` para host fora de loopback gera aviso porque o secret trafega sem TLS. A credencial é **secreta** (formato `hb_` + 64 hex — outro formato é rejeitado na primeira task, sem ecoar o valor) e viaja **só no header** `Authorization: Bearer` — nunca na URL da requisição.
+A credencial vem da opção `clientSecret` ou da env `HOBOTS_CLIENT_SECRET` (resolvida em `src/config.ts` no primeiro `register()`/`start()`, com a URL base `https://api2.hobots.app`). Em desenvolvimento a env `HOBOTS_API_URL` sobrescreve a URL base — apenas `http(s)`, e `http` para host fora de loopback gera aviso porque o secret trafega sem TLS. A credencial é **secreta** (formato `hb_` + 64 hex — outro formato é rejeitado no `register()`/`start()`, sem ecoar o valor) e viaja **só no header** `Authorization: Bearer` — nunca na URL da requisição.
 
 ## Telemetria — ingestão
 
@@ -47,7 +47,7 @@ Todo `transaction` carrega `run_id`: é assim que a [transaction da execução](
 
 ### MachineSnapshot
 
-Recursos da máquina onde a instância roda. Vai em `HeartbeatPayload.machine`, em `instance.machine` do `POST /v1/tasks/poll` e em `contexts.machine` dos eventos. Bytes em bytes, percentuais 0..100; campo ausente = não mensurável nesta plataforma. Teto: **4 KiB** serializado (heartbeat/poll → 422; `contexts.machine` idem). Chaves desconhecidas são descartadas pelo servidor.
+Recursos da máquina onde a instância roda. Vai em `HeartbeatPayload.machine`, em `instance.machine` do `POST /v1/runs/poll` e em `contexts.machine` dos eventos. Bytes em bytes, percentuais 0..100; campo ausente = não mensurável nesta plataforma. Teto: **4 KiB** serializado (heartbeat/poll → 422; `contexts.machine` idem). Chaves desconhecidas são descartadas pelo servidor.
 
 | Campo | Tipo | Descrição |
 | --- | --- | --- |
@@ -66,11 +66,11 @@ Recursos da máquina onde a instância roda. Vai em `HeartbeatPayload.machine`,
 
 O servidor guarda o último snapshot em `instances.machine` e um ponto por heartbeat/poll (máx. 1 a cada 30s por instância) em `instance_metrics`, expurgado em 14 dias.
 
-## Tasks — polling, criação e reporte
+## Execuções — polling, criação e reporte
 
-Endpoints sob `<baseUrl>/v1/tasks`, todos com `Authorization: Bearer <clientSecret>` (a credencial única do agente):
+Endpoints sob `<baseUrl>/v1/runs`, todos com `Authorization: Bearer <clientSecret>` (a credencial única do agente):
 
-### `POST /v1/tasks/poll`
+### `POST /v1/runs/poll`
 
 Corpo `PollRequest`:
 
@@ -82,32 +82,31 @@ Corpo `PollRequest`:
     "version": "3.0.0",
     "host": "vm-01",
     "environment": "production", // ambiente da instância: development | testing | staging | production
-    "tasks": ["processar-nfe", "monitor-pasta"], // TODAS as tasks (register + start) — o painel mostra o que o agente sabe fazer
+    "mode": "on_demand",          // como a instância trabalha: on_demand (register) | always_on (start)
     "poll_interval_ms": 2000,
-    // colunas de itens declaradas no código (opção `items`) — só as tasks que declararam;
+    // colunas de itens declaradas no código (opção `items`) — uma declaração, do agente;
     // ausente = nada declarado (o servidor nunca apaga a declaração anterior por ausência)
-    "task_items": { "processar-nfe": { "attributes": [{ "key": "numero_nota" }, { "key": "valor", "label": "valor (R$)" }] } }
+    "items": { "attributes": [{ "key": "numero_nota" }, { "key": "valor", "label": "valor (R$)" }] }
   },
-  "max": 2,                       // soma dos slots livres das tasks remotas (1..5)
-  "tasks": ["processar-nfe"]      // só tasks de register() com slot livre — a concorrência é por task
+  "max": 2                        // slots livres de `concurrency` (1..5)
 }
 ```
 
-Resposta `PollResponse` = `{ runs: RunDescriptor[] }`, cada `{ id, task, params, form, source, created_at }`.
+Resposta `PollResponse` = `{ runs: RunDescriptor[] }`, cada `{ id, params, form, source, created_at }`.
 
-O `instance.instance_id` é a **mesma identidade** do heartbeat de telemetria (`instance_id`): o servidor correlaciona os dois canais numa tabela `instances` por `(agent_id, instance_id)`. Os dois derivam do mesmo `instanceId` — o robô aparece como um agente só no painel. O próprio poll também marca a presença da instância (`last_poll_at`). Um processo só com tasks de `start()` nunca faz poll.
+O `instance.instance_id` é a **mesma identidade** do heartbeat de telemetria (`instance_id`): o servidor correlaciona os dois canais numa tabela `instances` por `(agent_id, instance_id)`. Os dois derivam do mesmo `instanceId` — o robô aparece como um agente só no painel. O próprio poll também marca a presença da instância (`last_poll_at`). Um processo no modo `start()` nunca faz poll.
 
 **Backoff:** um request por poll; o loop decide o ritmo. HTTP 401 (key rejeitada) → retry lento a 30s com log throttled; outros erros → ladder `[1s, 4s, 16s]`.
 
-### `POST /v1/tasks/runs`
+### `POST /v1/runs`
 
-Modo `start`: a instância abre a **própria run**. Corpo `RunCreateRequest` — `{ "task": "monitor-pasta", "instance": { /* InstanceInfo, obrigatório */ } }`. Resposta `201` `RunCreateResponse` = o mesmo `RunDescriptor` do poll, com `params: {}`, `form: null` e `source: 'agent'`.
+Modo `start`: a instância abre a **própria run**. Corpo `RunCreateRequest` — `{ "instance": { /* InstanceInfo (com `mode: "always_on"`), obrigatório */ } }`. Resposta `201` `RunCreateResponse` = o mesmo `RunDescriptor` do poll, com `params: {}`, `form: null` e `source: 'agent'`.
 
 - A run nasce **`running`** (`started_at`, `claimed_at` e `last_report_at` = agora, `claim_count` 1), sem formulário nem solicitante, vinculada à instância informada. Dali em diante é reportada pelas rotas abaixo exatamente como uma run reivindicada no poll.
-- `touchInstance` roda antes do insert (presença); se falhar, a API responde `503` e o SDK insiste com o ladder do poll (o handler só começa quando a run existe). Corpo vazio, sem `instance.instance_id` ou com `task` fora de 1..255 → `422`.
+- `touchInstance` roda antes do insert (presença); se falhar, a API responde `503` e o SDK insiste com o ladder do poll (o handler só começa quando a run existe). Corpo vazio ou sem `instance.instance_id` → `422`.
 - Sem dedupe: um processo reiniciado em menos de 120 s deixa a run anterior `running` até o sweep marcá-la `AgentTerminated`. O app não oferece "reexecutar" para runs `agent` — ninguém faria poll por elas.
 
-### `PATCH /v1/tasks/runs/{id}`
+### `PATCH /v1/runs/{id}`
 
 Corpo `RunUpdateRequest`:
 
@@ -117,7 +116,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
@@ -134,7 +133,7 @@ Corpo `RunUpdateRequest`:
 
 Ciclo de vida completo da run no servidor (`RunStatus`): `pending → claimed → running → succeeded | failed | canceled` (runs `agent` nascem em `running`). O agente só transiciona para `running`/`succeeded`/`failed` (`RunUpdateStatus`).
 
-### `POST /v1/tasks/runs/{id}/items`
+### `POST /v1/runs/{id}/items`
 
 Registra em lote os **itens de execução** (a entrega do bot — `hobots.items` no SDK). Insert-only: cada item chega com o status final; um `id` repetido na mesma run é ignorado (retry de rede idempotente).
 
@@ -149,13 +148,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.
@@ -169,7 +171,7 @@ Resposta `200` `RunItemsCreateResponse`: `{ "accepted": 1, "duplicates": 0 }`
 | `422` | payload inválido |
 | `429` | limite de 10.000 itens por execução atingido (lote inteiro rejeitado) |
 
-### `POST /v1/tasks/runs/{id}/attachments`
+### `POST /v1/runs/{id}/attachments`
 
 Registra um anexo de imagem e devolve uma **URL presignada de PUT**. O binário nunca passa pela API: o agente sobe direto no S3.
 
@@ -177,11 +179,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
 }
 ```
@@ -210,17 +212,17 @@ O PUT no S3 precisa mandar exatamente esses headers — eles fazem parte da assi
 | `503` | anexos não habilitados nesta instalação (sem bucket S3 configurado) |
 | `502` | falha ao presignar — o registro é desfeito |
 
-### `PATCH /v1/tasks/runs/{id}/attachments/{attachmentId}`
+### `PATCH /v1/runs/{id}/attachments/{attachmentId}`
 
 Confirma o upload. Corpo `RunAttachmentConfirmRequest`: `{ "status": "uploaded" | "failed", "size_bytes"?, "width"?, "height"? }`; resposta `{ "ok": true }`, ou `404` se o anexo não existe no projeto da chave.
 
 É **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
 
-O `POST /v1/tasks/poll` no app chama `claimPendingRuns()` em
+O `POST /v1/runs/poll` no app chama `claimPendingRuns()` em
 [`apps/api/lib/tasks/claim.ts`](../../../apps/api/lib/tasks/claim.ts): um CTE que seleciona runs `pending` vencidas com `FOR UPDATE SKIP LOCKED` e as promove a `claimed` num único `UPDATE ... RETURNING`. Isso garante que dois agentes concorrentes nunca peguem a mesma run. **Nada disso está no SDK** — ele só faz o HTTP.
 
 ## Identidade do SDK

package/docs/{tasks.md → runs.md}

@@ -1,27 +1,27 @@
-# Tasks
+# Execuções
 
-Uma **task** é o que o robô sabe fazer, identificada por um slug. Cada rodada é uma **execução** (run) na plataforma, com logs, itens, progresso, anexos e resultado. Há dois modos de registrar uma task; tudo o mais (o objeto `hobots`, cancelamento, retry) é igual nos dois.
+O **agente** é o seu robô, e o handler que você passa a `register()`/`start()` é o que ele faz. Cada rodada é uma **execução** (run) na plataforma, com logs, itens, progresso, anexos e resultado. Há dois modos de iniciar o agente; tudo o mais (o objeto `hobots`, cancelamento, retry) é igual nos dois.
 
 ## Os dois modos
 
 ```js
-// sob demanda: uma execução por solicitação do app (formulário com este task_slug ou agendamento)
-hobots.register('processar-nfe', async params => { /* … */ }, { concurrency: 2 });
+// sob demanda: uma execução por solicitação do app (formulário do agente ou agendamento)
+hobots.register(async params => { /* … */ }, { concurrency: 2 });
 
 // sempre ligado: o robô abre a própria execução e roda o handler (o seu loop) uma vez
-hobots.start('monitor-pasta', async () => { /* while (true) { … } */ });
+hobots.start(async () => { /* while (true) { … } */ });
 ```
 
-- `register` — o robô faz polling na plataforma; cada solicitação vira uma execução com os `params` do formulário. Registre antes de haver solicitações; o polling começa sozinho.
-- `start` — ao iniciar, o SDK cria a execução (`POST /v1/tasks/runs`) e roda o handler com `params = {}`. Enquanto a plataforma não responde, insiste com backoff — o handler só começa quando a execução existe. Quando o handler retorna, a execução fecha como `succeeded` (ou `failed` após os retries) e o processo segue vivo pelo heartbeat. **Uma execução por processo** — para "recomeçar", reinicie o robô.
-- Os dois coexistem no mesmo processo. Um slug só pode ser registrado uma vez (lança).
+- `register` — o robô faz polling na plataforma; cada solicitação vira uma execução com os `params` do formulário. O polling começa sozinho.
+- `start` — ao iniciar, o SDK cria a execução (`POST /v1/runs`) e roda o handler com `params = {}`. Enquanto a plataforma não responde, insiste com backoff — o handler só começa quando a execução existe. Quando o handler retorna, a execução fecha como `succeeded` (ou `failed` após os retries) e o processo segue vivo pelo heartbeat. **Uma execução por processo** — para "recomeçar", reinicie o robô.
+- **Uma chamada por processo**: `register` ou `start`. A segunda lança (`o agente já foi iniciado`). Dois trabalhos diferentes são dois agentes.
 
 > No modo start, lembre do teto de **1000 linhas de log por execução** no servidor: logue novidades e use `hobots.items` para o trabalho feito (até 10.000 itens).
 
 ## O handler e o objeto `hobots`
 
 ```ts
-type TaskHandler<P = Record<string, unknown>> = (params: P, ctx: RunContext) => void | Promise<void>;
+type RunHandler<P = Record<string, unknown>> = (params: P, ctx: RunContext) => void | Promise<void>;
 ```
 
 Dentro do handler — e em **qualquer módulo** chamado por ele — o objeto global `hobots` resolve a execução atual:
@@ -40,15 +40,15 @@ 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 (`[hobots] INFO …`). 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.transaction` | Transaction da execução (`run`), já correlacionada e finalizada pelo SDK. `startChild(op, descrição)` = uma step no waterfall. |
+| `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) |
-| `hobots.runId` · `hobots.task` · `hobots.params` | Identidade da execução |
+| `hobots.runId` · `hobots.params` | Identidade da execução |
 
 - **Retorno** do handler: **ignorado** (resultados podem conter dados sensíveis). Reporte por logs e itens.
 - **Erro lançado**: nova tentativa (ver Retry) e, esgotadas, `failed` com tipo, mensagem (cap 10k) e stack (cap 20k), passando pelo scrub de segredos.
@@ -57,7 +57,7 @@ Isso funciona com `concurrency > 1` porque cada execução roda no seu contexto
 
 ## Itens de execução (`hobots.items`)
 
-A **entrega do robô**: cada item processado, com status e atributos livres (viram colunas na aba de itens da execução no app), totalizadores na solicitação.
+A **entrega do robô**: cada item processado, com status e atributos livres (viram colunas na aba de itens da execução no app), totalizadores no trabalho.
 
 ```js
 hobots.items.succeeded({ numero_nota: nota.numero, cnpj: nota.cnpj }, { id: nota.numero });
@@ -96,20 +96,20 @@ const resultado = await hobots.items.each(
 - Só **cancelamento, timeout e shutdown** interrompem o loop: o `RunCanceled` sobe, o item em curso não é registrado e o progresso não avança.
 - Aceita `Iterable` ou `AsyncIterable` (sem `length`, nenhum total é declarado).
 
-> Se o handler da task termina com o progresso parado antes do total declarado (ex.: 45/76), o SDK deixa um aviso no log da execução — e a Central sinaliza o desencontro entre processados e itens reportados.
+> Se o handler termina com o progresso parado antes do total declarado (ex.: 45/76), o SDK deixa um aviso no log da execução — e a Central sinaliza o desencontro entre processados e itens reportados.
 
 ### Colunas da aba de itens
 
-As colunas vêm do código, não do formulário — valem para `register()` (com ou sem formulário) e `start()`:
+As colunas vêm do código, não do formulário — é **uma declaração só, do agente**, válida para `register()` (com ou sem formulário) e `start()`:
 
 ```js
-register('processar-nfe', handler, {
+hobots.register(handler, {
   items: { columns: ['numero_nota', { key: 'cnpj', label: 'CNPJ' }, { key: 'valor', label: 'valor (R$)' }] },
 });
 ```
 
 - Ordem da lista = ordem das colunas; até 12; chave com letras, números, `.`, `-`, `_` (inválidas são descartadas com aviso em `debug`).
-- A declaração vai na presença da instância (poll / abertura de run). No app, **Configurações → agente → itens da execução** pode personalizar as colunas (e restaurar as do código).
+- A declaração vai na presença da instância (`instance.items` no poll / abertura de run). No app, **Configurações → agente → itens da execução** pode personalizar as colunas (e restaurar as do código).
 - Sem declaração nem personalização, o app mostra as chaves encontradas nos próprios payloads.
 
 ## Progresso (`hobots.progress`)
@@ -124,30 +124,49 @@ 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).
 
 ## Cancelamento cooperativo
 
-Cancelar a solicitação no app **não mata** o handler: o SDK detecta (o PATCH periódico recebe 409), dispara `hobots.signal` e o próximo **ponto de parada** lança `RunCanceled`:
+Cancelar o trabalho no app **não mata** o handler: o SDK detecta (o PATCH periódico recebe 409), dispara `hobots.signal` e o próximo **ponto de parada** lança `RunCanceled`:
 
 - `hobots.items.*`, `hobots.progress.total/advance/set`, `hobots.transaction.startChild()`, `hobots.sleep()` e cada tentativa de `hobots.retry()`.
 - **Nunca `hobots.log.*`** — log em `finally` de limpeza não pode explodir.
 
 ```js
-hobots.register('processar-nfe', async params => {
+hobots.register(async params => {
   const browser = await abrir();
   try {
     for (const nota of params.notas) {
@@ -181,7 +200,7 @@ const dados = await hobots.retry(() => portal.buscar(nota), { retries: 3, delayM
 
 ## Concorrência (`register`)
 
-`concurrency` (1..5, default 1) por task. O agente só pede à plataforma o que consegue rodar (tasks com slot livre, `max` = soma dos slots, teto 5) e entra em **drain mode** — re-pesquisa imediatamente enquanto vem trabalho; sem trabalho, espera `pollIntervalMs`.
+`concurrency` (1..5, default 1) é **do agente**: quantas solicitações ele atende ao mesmo tempo. O agente só pede à plataforma o que consegue rodar (`max` = slots livres, teto 5) e entra em **drain mode** — re-pesquisa imediatamente enquanto vem trabalho; sem trabalho, espera `pollIntervalMs`.
 
 ## Timeout
 

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": "4.0.0",
+  "description": "SDK JavaScript da Hobots — o agente é a própria tarefa: register() atende solicitações da plataforma (sob demanda), start() roda sempre ligado 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:*",