hobots 1.9.2 → 2.0.0

package/dist/protocol.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/protocol.ts"],"sourcesContent":["/**\n * Tipos do protocolo do Hobots (SDK → servidor).\n *\n * Este arquivo é a fonte de verdade do wire format e só pode reexportar tipos:\n * o app valida os payloads com zod e trava o drift via `satisfies z.ZodType<...>`\n * contra estes tipos (importados de `hobots/protocol`).\n */\n\n// Wire format de tasks (agente ↔ servidor) — reexportado aqui para o app\n// consumir tudo de `hobots/protocol`.\nexport type {\n  RunStatus,\n  RunUpdateStatus,\n  RunLogLevel,\n  RunLogEntry,\n  AgentInfo,\n  PollRequest,\n  RunDescriptor,\n  PollResponse,\n  RunError,\n  RunUpdateRequest,\n  RunUpdateResponse,\n  RunAttachmentContentType,\n  RunAttachmentCreateRequest,\n  RunAttachmentCreateResponse,\n  RunAttachmentConfirmRequest,\n  RunAttachmentConfirmResponse,\n} from './tasks/protocol';\n\nexport type Severity = 'fatal' | 'error' | 'warning' | 'info' | 'debug' | 'success';\n\n/** Frames em ordem innermost-first (mesma ordem impressa pelo V8). */\nexport interface StackFrame {\n  function?: string;\n  filename?: string;\n  lineno?: number;\n  colno?: number;\n  in_app: boolean;\n}\n\nexport interface Breadcrumb {\n  /** ISO 8601 */\n  timestamp: string;\n  type?: string;\n  category?: string;\n  message?: string;\n  level?: Severity;\n  data?: Record<string, unknown>;\n}\n\nexport interface ExceptionData {\n  type: string;\n  value: string;\n  stacktrace?: { frames: StackFrame[] };\n}\n\nexport interface EventUser {\n  id?: string;\n  username?: string;\n  email?: string;\n}\n\nexport interface EventPayload {\n  /** uuid v4 sem hífens (32 hex), gerado pelo SDK */\n  event_id: string;\n  /** ISO 8601 */\n  timestamp: string;\n  level: Severity;\n  message?: string;\n  exception?: ExceptionData;\n  /** Override de agrupamento; quando ausente o servidor calcula pelo stack trace */\n  fingerprint?: string[];\n  breadcrumbs?: Breadcrumb[];\n  tags?: Record<string, string>;\n  user?: EventUser;\n  contexts?: Record<string, Record<string, unknown>>;\n  extra?: Record<string, unknown>;\n  release?: string;\n  environment?: string;\n}\n\n/** Status de uma step (etapa). `warning` = terminou, mas merece atenção (não é falha). */\nexport type StepStatus = 'ok' | 'warning' | 'error' | 'cancelled';\n\nexport interface StepData {\n  /** 16 hex */\n  step_id: string;\n  parent_step_id?: string;\n  op?: string;\n  description?: string;\n  status?: StepStatus;\n  /** ISO 8601 */\n  start_timestamp: string;\n  /** ISO 8601 (fim da step) */\n  timestamp: string;\n  data?: Record<string, unknown>;\n}\n\nexport interface TransactionPayload {\n  event_id: string;\n  name: string;\n  op?: string;\n  status: string;\n  start_timestamp: string;\n  timestamp: string;\n  steps: StepData[];\n  tags?: Record<string, string>;\n  release?: string;\n  environment?: string;\n  /** Correlaciona esta transaction a uma execução de task (ctx.tx dentro de um task handler) */\n  run_id?: string;\n}\n\nexport interface HeartbeatPayload {\n  instance_id: string;\n  name?: string;\n  interval_ms: number;\n  /** ISO 8601 */\n  timestamp: string;\n  metadata?: Record<string, unknown>;\n  release?: string;\n}\n\nexport type EnvelopeItem =\n  | { type: 'event'; payload: EventPayload }\n  | { type: 'transaction'; payload: TransactionPayload }\n  | { type: 'heartbeat'; payload: HeartbeatPayload };\n\nexport interface Envelope {\n  sdk: { name: string; version: string };\n  /** ISO 8601 */\n  sent_at: string;\n  items: EnvelopeItem[];\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAAA;AAAA;","names":[]}
+{"version":3,"sources":["../src/protocol.ts"],"sourcesContent":["/**\n * Tipos do protocolo do Hobots (SDK → servidor).\n *\n * Este arquivo é a fonte de verdade do wire format e só pode reexportar tipos:\n * o app valida os payloads com zod e trava o drift via `satisfies z.ZodType<...>`\n * contra estes tipos (importados de `hobots/protocol`).\n */\n\n// Wire format de tasks (agente ↔ servidor) — reexportado aqui para o app\n// consumir tudo de `hobots/protocol`.\nexport type {\n  RunStatus,\n  RunUpdateStatus,\n  RunLogLevel,\n  RunLogEntry,\n  InstanceInfo,\n  PollRequest,\n  RunDescriptor,\n  PollResponse,\n  RunError,\n  RunUpdateRequest,\n  RunUpdateResponse,\n  RunItemStatus,\n  RunItemInput,\n  RunItemsCreateRequest,\n  RunItemsCreateResponse,\n  RunAttachmentContentType,\n  RunAttachmentCreateRequest,\n  RunAttachmentCreateResponse,\n  RunAttachmentConfirmRequest,\n  RunAttachmentConfirmResponse,\n} from './tasks/protocol';\n\nexport type Severity = 'fatal' | 'error' | 'warning' | 'info' | 'debug' | 'success';\n\n/** Frames em ordem innermost-first (mesma ordem impressa pelo V8). */\nexport interface StackFrame {\n  function?: string;\n  filename?: string;\n  lineno?: number;\n  colno?: number;\n  in_app: boolean;\n}\n\nexport interface Breadcrumb {\n  /** ISO 8601 */\n  timestamp: string;\n  type?: string;\n  category?: string;\n  message?: string;\n  level?: Severity;\n  data?: Record<string, unknown>;\n}\n\nexport interface ExceptionData {\n  type: string;\n  value: string;\n  stacktrace?: { frames: StackFrame[] };\n}\n\nexport interface EventUser {\n  id?: string;\n  username?: string;\n  email?: string;\n}\n\nexport interface EventPayload {\n  /** uuid v4 sem hífens (32 hex), gerado pelo SDK */\n  event_id: string;\n  /** ISO 8601 */\n  timestamp: string;\n  level: Severity;\n  message?: string;\n  exception?: ExceptionData;\n  /** Override de agrupamento; quando ausente o servidor calcula pelo stack trace */\n  fingerprint?: string[];\n  breadcrumbs?: Breadcrumb[];\n  tags?: Record<string, string>;\n  user?: EventUser;\n  contexts?: Record<string, Record<string, unknown>>;\n  extra?: Record<string, unknown>;\n  release?: string;\n  environment?: string;\n}\n\n/** Status de uma step (etapa). `warning` = terminou, mas merece atenção (não é falha). */\nexport type StepStatus = 'ok' | 'warning' | 'error' | 'cancelled';\n\nexport interface StepData {\n  /** 16 hex */\n  step_id: string;\n  parent_step_id?: string;\n  op?: string;\n  description?: string;\n  status?: StepStatus;\n  /** ISO 8601 */\n  start_timestamp: string;\n  /** ISO 8601 (fim da step) */\n  timestamp: string;\n  data?: Record<string, unknown>;\n}\n\nexport interface TransactionPayload {\n  event_id: string;\n  name: string;\n  op?: string;\n  status: string;\n  start_timestamp: string;\n  timestamp: string;\n  steps: StepData[];\n  tags?: Record<string, string>;\n  release?: string;\n  environment?: string;\n  /** Correlaciona esta transaction a uma execução de task (ctx.tx dentro de um task handler) */\n  run_id?: string;\n}\n\nexport interface HeartbeatPayload {\n  instance_id: string;\n  name?: string;\n  interval_ms: number;\n  /** ISO 8601 */\n  timestamp: string;\n  metadata?: Record<string, unknown>;\n  release?: string;\n}\n\nexport type EnvelopeItem =\n  | { type: 'event'; payload: EventPayload }\n  | { type: 'transaction'; payload: TransactionPayload }\n  | { type: 'heartbeat'; payload: HeartbeatPayload };\n\nexport interface Envelope {\n  sdk: { name: string; version: string };\n  /** ISO 8601 */\n  sent_at: string;\n  items: EnvelopeItem[];\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAAA;AAAA;","names":[]}

package/dist/protocol.d.cts

@@ -22,7 +22,7 @@ interface RunLogEntry {
      */
     attachments?: string[];
 }
-interface AgentInfo {
+interface InstanceInfo {
     /** Identidade canônica do agente — correlaciona com o heartbeat de telemetria */
     instance_id: string;
     name?: string;
@@ -32,10 +32,15 @@ interface AgentInfo {
     host?: string;
     /** Tasks registradas no agente */
     tasks?: string[];
+    /**
+     * Intervalo de poll em ms — alimenta a tolerância de offline do servidor (3×) em
+     * agentes poll-only, que sem isso herdariam a tolerância do heartbeat (30s × 3).
+     */
+    poll_interval_ms?: number;
 }
 /** POST /v1/tasks/poll */
 interface PollRequest {
-    agent?: AgentInfo;
+    instance?: InstanceInfo;
     /** Quantas runs reivindicar de uma vez (1..5). Default: 1 */
     max?: number;
     /** Só entrega runs destas tasks (nomes registrados no agente) */
@@ -74,6 +79,39 @@ interface RunUpdateRequest {
 interface RunUpdateResponse {
     ok: true;
 }
+/**
+ * Status de negócio de um item processado pela run:
+ * - 'succeeded': processado com sucesso
+ * - 'failed': falha técnica ao processar o item
+ * - 'occurrence': ocorrência de negócio (ex.: "nota nº 10 não encontrada")
+ */
+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).
+     */
+    id: string;
+    /** Ordem de emissão no agente (contador monotônico por run) */
+    seq: number;
+    status: RunItemStatus;
+    /** Motivo — esperado em 'failed'/'occurrence' */
+    message?: string;
+    /** Atributos definidos pelo dev; chaves configuráveis como colunas na plataforma */
+    payload?: Record<string, unknown>;
+    /** ISO 8601 — relógio do agente, apenas para exibição */
+    ts?: string;
+}
+/** POST /v1/tasks/runs/{id}/items — aceito mesmo com a run cancelada/terminal */
+interface RunItemsCreateRequest {
+    items: RunItemInput[];
+}
+interface RunItemsCreateResponse {
+    /** Itens inseridos */
+    accepted: number;
+    /** Ignorados por id repetido na run (retry de rede é idempotente) */
+    duplicates: number;
+}
 /** Formatos aceitos para anexo. O S3 valida o content-type contra a assinatura. */
 type RunAttachmentContentType = 'image/png' | 'image/jpeg' | 'image/webp';
 /** POST /v1/tasks/runs/{id}/attachments */
@@ -223,4 +261,4 @@ interface Envelope {
     items: EnvelopeItem[];
 }
 
-export type { AgentInfo, Breadcrumb, Envelope, EnvelopeItem, EventPayload, EventUser, ExceptionData, HeartbeatPayload, PollRequest, PollResponse, RunAttachmentConfirmRequest, RunAttachmentConfirmResponse, RunAttachmentContentType, RunAttachmentCreateRequest, RunAttachmentCreateResponse, RunDescriptor, RunError, RunLogEntry, RunLogLevel, RunStatus, RunUpdateRequest, RunUpdateResponse, RunUpdateStatus, Severity, StackFrame, StepData, StepStatus, TransactionPayload };
+export type { Breadcrumb, Envelope, EnvelopeItem, EventPayload, EventUser, ExceptionData, HeartbeatPayload, InstanceInfo, PollRequest, PollResponse, RunAttachmentConfirmRequest, RunAttachmentConfirmResponse, RunAttachmentContentType, RunAttachmentCreateRequest, RunAttachmentCreateResponse, RunDescriptor, RunError, RunItemInput, RunItemStatus, RunItemsCreateRequest, RunItemsCreateResponse, RunLogEntry, RunLogLevel, RunStatus, RunUpdateRequest, RunUpdateResponse, RunUpdateStatus, Severity, StackFrame, StepData, StepStatus, TransactionPayload };

package/dist/protocol.d.ts

@@ -22,7 +22,7 @@ interface RunLogEntry {
      */
     attachments?: string[];
 }
-interface AgentInfo {
+interface InstanceInfo {
     /** Identidade canônica do agente — correlaciona com o heartbeat de telemetria */
     instance_id: string;
     name?: string;
@@ -32,10 +32,15 @@ interface AgentInfo {
     host?: string;
     /** Tasks registradas no agente */
     tasks?: string[];
+    /**
+     * Intervalo de poll em ms — alimenta a tolerância de offline do servidor (3×) em
+     * agentes poll-only, que sem isso herdariam a tolerância do heartbeat (30s × 3).
+     */
+    poll_interval_ms?: number;
 }
 /** POST /v1/tasks/poll */
 interface PollRequest {
-    agent?: AgentInfo;
+    instance?: InstanceInfo;
     /** Quantas runs reivindicar de uma vez (1..5). Default: 1 */
     max?: number;
     /** Só entrega runs destas tasks (nomes registrados no agente) */
@@ -74,6 +79,39 @@ interface RunUpdateRequest {
 interface RunUpdateResponse {
     ok: true;
 }
+/**
+ * Status de negócio de um item processado pela run:
+ * - 'succeeded': processado com sucesso
+ * - 'failed': falha técnica ao processar o item
+ * - 'occurrence': ocorrência de negócio (ex.: "nota nº 10 não encontrada")
+ */
+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).
+     */
+    id: string;
+    /** Ordem de emissão no agente (contador monotônico por run) */
+    seq: number;
+    status: RunItemStatus;
+    /** Motivo — esperado em 'failed'/'occurrence' */
+    message?: string;
+    /** Atributos definidos pelo dev; chaves configuráveis como colunas na plataforma */
+    payload?: Record<string, unknown>;
+    /** ISO 8601 — relógio do agente, apenas para exibição */
+    ts?: string;
+}
+/** POST /v1/tasks/runs/{id}/items — aceito mesmo com a run cancelada/terminal */
+interface RunItemsCreateRequest {
+    items: RunItemInput[];
+}
+interface RunItemsCreateResponse {
+    /** Itens inseridos */
+    accepted: number;
+    /** Ignorados por id repetido na run (retry de rede é idempotente) */
+    duplicates: number;
+}
 /** Formatos aceitos para anexo. O S3 valida o content-type contra a assinatura. */
 type RunAttachmentContentType = 'image/png' | 'image/jpeg' | 'image/webp';
 /** POST /v1/tasks/runs/{id}/attachments */
@@ -223,4 +261,4 @@ interface Envelope {
     items: EnvelopeItem[];
 }
 
-export type { AgentInfo, Breadcrumb, Envelope, EnvelopeItem, EventPayload, EventUser, ExceptionData, HeartbeatPayload, PollRequest, PollResponse, RunAttachmentConfirmRequest, RunAttachmentConfirmResponse, RunAttachmentContentType, RunAttachmentCreateRequest, RunAttachmentCreateResponse, RunDescriptor, RunError, RunLogEntry, RunLogLevel, RunStatus, RunUpdateRequest, RunUpdateResponse, RunUpdateStatus, Severity, StackFrame, StepData, StepStatus, TransactionPayload };
+export type { Breadcrumb, Envelope, EnvelopeItem, EventPayload, EventUser, ExceptionData, HeartbeatPayload, InstanceInfo, PollRequest, PollResponse, RunAttachmentConfirmRequest, RunAttachmentConfirmResponse, RunAttachmentContentType, RunAttachmentCreateRequest, RunAttachmentCreateResponse, RunDescriptor, RunError, RunItemInput, RunItemStatus, RunItemsCreateRequest, RunItemsCreateResponse, RunLogEntry, RunLogLevel, RunStatus, RunUpdateRequest, RunUpdateResponse, RunUpdateStatus, Severity, StackFrame, StepData, StepStatus, TransactionPayload };

package/docs/api-reference.md

@@ -84,7 +84,7 @@ Habilitadas com `tasks: true` (ou `TasksOptions`) no `init()` único. Todas expo
 - **`start()`** — começa o polling. **Mantém o processo vivo** até `stop()`/`close()` — o timer não é `unref`'d, ao contrário dos da telemetria. Lança se o `init()` não configurou `tasks` ou se nenhuma task foi registrada. Também instala os handlers de saída (SIGINT/SIGTERM/erro fatal) que reportam as runs ativas como `AgentTerminated`, a menos que `installExitHandlers: false`.
 - **`stop(timeoutMs = 30_000)`** → `Promise<boolean>` — encerra o polling e aguarda as [runs](./concepts.md#run) ativas terminarem. Para **só as tasks**: a telemetria (heartbeat, captura de erros) continua funcionando. Devolve `false` se estourou o timeout — as runs que ainda estavam rodando são reportadas como `AgentTerminated`. Para encerrar tudo, use [`close()`](./concepts.md#fila-flush-e-close).
 
-No poll, o agente se identifica com `AgentInfo` (`hobots/protocol`): o campo `instance_id` (o `instanceId` do `init()`) é a identidade canônica do agente — a mesma do heartbeat de telemetria, então os dois canais convergem em um agente no painel.
+No poll, o agente se identifica com `InstanceInfo` (`hobots/protocol`): o campo `instance_id` (o `instanceId` do `init()`) é a identidade canônica do agente — a mesma do heartbeat de telemetria, então os dois canais convergem em um agente no painel.
 
 ---
 
@@ -168,15 +168,24 @@ interface RunContext {
   runId: string;
   task: string;
   log: RunLogger; // ctx.log.debug/info/warn/error/success(message)
+  items: RunItems; // ctx.items.add/succeeded/failed/occurrence — a entrega do bot
   tx: Transaction; // transaction desta run — correlacionada e finalizada pelo SDK
   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
 }
+
+interface RunItems {
+  add(item: { status: RunItemStatus; id?: string; message?: string; payload?: Record<string, unknown> }): void;
+  succeeded(payload?: Record<string, unknown>, options?: { id?: string }): void;
+  failed(message: string, payload?: Record<string, unknown>, options?: { id?: string }): void;
+  occurrence(message: string, payload?: Record<string, unknown>, options?: { id?: string }): void;
+}
 ```
 
 - **`runId` / `task`** — identificam a execução; úteis para correlacionar com os seus próprios logs.
 - **`log.<level>(message)`** — níveis `debug`, `info`, `warn`, `error` e `success`; enfileira uma linha de log enviada ao app em PATCHes incrementais, e **também imprime no terminal local**. Conceito: [Run](./concepts.md#run).
+- **`items.<status>(…)`** — registra um item processado/gerado pela execução (síncrono, bufferizado, lotes de até 500). `id` opcional = idempotência dentro da run. Guia: [Itens de execução](./tasks.md#itens-de-execução-ctxitems).
 - **`tx`** — a [transaction de performance da run](./concepts.md#transaction-de-run-ctxtx). Use `ctx.tx.startChild(op, description)` para medir as etapas; **não** chame `finish()` nela. `startTransaction()` dentro do handler devolve essa mesma transaction.
 - **`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.
@@ -209,6 +218,8 @@ Todos os prazos do SDK num lugar só. A coluna **Onde configura** diz se o valor
 | --- | --- | --- | --- |
 | poll sem trabalho | `5000` ms (mín. `1000`) | `tasks: { pollIntervalMs }` | é só o **teto da espera quando não há nada**: com trabalho na fila o próximo poll é imediato ([drain mode](./concepts.md#drain-mode)) |
 | flush de logs da run | `2000` ms | `tasks: { logFlushIntervalMs }` | ou na hora, ao acumular 20 linhas |
+| flush de itens da run | `2000` ms | — (acompanha `logFlushIntervalMs`) | ou na hora, ao acumular 100 itens; POSTs de até 500 |
+| espera pelos itens no fim da run | `15000` ms | — (fixo) | antes do PATCH terminal, drena o buffer de itens — os totalizadores ficam completos quando a run termina |
 | validade da URL de upload de anexo | `900` s | — (servidor) | tempo para o PUT no S3 depois que a API presigna |
 | espera pelos anexos no fim da run | `15000` ms | — (fixo) | antes do PATCH terminal, aguarda os uploads pendentes; no estouro a run termina e o app mostra "imagem não enviada" |
 | uploads de anexo simultâneos | `3` | — (fixo) | por execução; os demais ficam na fila |

package/docs/concepts.md

@@ -41,9 +41,9 @@ Cada API do SDK alimenta um módulo do app da Hobots (app.hobots.app). O mapa:
 | No SDK | No app |
 | --- | --- |
 | **Agente** — dono do Client Secret (`hb_…`) que autentica tudo | **Configurações → Agentes** (é lá que você copia a credencial) |
-| **Instância** — o par `(project_id, instance_id)`; heartbeat e poll de tasks convergem nele | Módulo **Agentes** (uptime, performance) |
+| **Instância** — o par `(agent_id, instance_id)`; heartbeat e poll de tasks convergem nele | Módulo **Instâncias** (uptime, performance) |
 | **[Evento](#evento)** agrupado em **issue** — `captureException` / `captureMessage` | Módulo **Issues** |
-| **[Transaction](#transaction) / etapas** — `startTransaction` (e [`ctx.tx`](#transaction-de-run-ctxtx) dentro de uma run) | Performance no módulo **Agentes**; nas execuções, a aba de performance da solicitação |
+| **[Transaction](#transaction) / etapas** — `startTransaction` (e [`ctx.tx`](#transaction-de-run-ctxtx) dentro de uma run) | Performance no módulo **Instâncias**; nas execuções, a aba de performance da solicitação |
 | **Task / [run](#run)** — `register('task-slug', …)` casa com o `task_slug` do formulário | Módulo **Solicitações** (formulários em **Configurações → Formulários**) |
 
 ---

package/docs/protocol.md

@@ -54,8 +54,8 @@ Corpo `PollRequest`:
 
 ```jsonc
 {
-  "agent": {
-    "instance_id": "vm-01",       // identidade canônica do agente (obrigatória)
+  "instance": {
+    "instance_id": "vm-01",       // identidade canônica da instância (obrigatória)
     "name": "VM 01",
     "version": "2.0.0",
     "host": "vm-01",
@@ -68,7 +68,7 @@ Corpo `PollRequest`:
 
 Resposta `PollResponse` = `{ runs: RunDescriptor[] }`, cada `{ id, task, params, form, source, created_at }`.
 
-O `agent.instance_id` é a **mesma identidade** do heartbeat de telemetria (`instance_id`): o servidor correlaciona os dois canais numa tabela `agents` por `(project_id, instance_id)`. Com o `init()` único, os dois derivam do `instanceId` — o robô aparece como um agente só no painel automaticamente. O próprio poll marca a presença do agente (`last_poll_at`), por isso o heartbeat é opcional quando as tasks estão habilitadas.
+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)`. Com o `init()` único, os dois derivam do `instanceId` — o robô aparece como um agente só no painel automaticamente. O próprio poll marca a presença da instância (`last_poll_at`), por isso o heartbeat é opcional quando as tasks estão habilitadas.
 
 **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]`.
 
@@ -97,6 +97,41 @@ Corpo `RunUpdateRequest`:
 
 Ciclo de vida completo da run no servidor (`RunStatus`): `pending → claimed → running → succeeded | failed | canceled`. O agente só transiciona para `running`/`succeeded`/`failed` (`RunUpdateStatus`).
 
+### `POST /v1/tasks/runs/{id}/items`
+
+Registra em lote os **itens de execução** (a entrega do bot — `ctx.items` no SDK). Insert-only: cada item chega com o status final; um `id` repetido na mesma run é ignorado (retry de rede idempotente).
+
+Corpo `RunItemsCreateRequest`:
+
+```jsonc
+{
+  "items": [                             // 1..500 por request
+    {
+      "id": "12345",                     // identidade do item na run (dev) ou uuid do SDK
+      "seq": 0,                          // ordem de emissão no agente
+      "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
+    }
+  ]
+}
+```
+
+Resposta `200` `RunItemsCreateResponse`: `{ "accepted": 1, "duplicates": 0 }` — `duplicates` conta os ignorados por `(run, id)` repetido.
+
+- **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.
+- Retry `[1s, 4s, 16s]` para rede/5xx; `404` = servidor sem o recurso (o SDK degrada em silêncio); `429` = cap de **10.000 itens por run** (permanente — o SDK descarta com um aviso).
+
+| Status | Quando |
+| --- | --- |
+| `401` | chave do agente inválida ou inativa |
+| `404` | execução inexistente ou de outro projeto |
+| `413` | corpo acima de 1 MB |
+| `422` | payload inválido |
+| `429` | limite de 10.000 itens por execução atingido (lote inteiro rejeitado) |
+
 ### `POST /v1/tasks/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.

package/docs/tasks.md

@@ -48,6 +48,7 @@ interface RunContext {
   runId: string;
   task: string;
   log: RunLogger; // ctx.log.debug/info/warn/error/success(message)
+  items: RunItems; // ctx.items.succeeded/failed/occurrence — a entrega do bot
   tx: Transaction;
   signal: AbortSignal;
   throwIfCanceled(): void;
@@ -57,6 +58,7 @@ interface RunContext {
 
 - **`params`** — os dados do formulário configurado no app (o JSON validado).
 - **`ctx.log.<level>(message)`** — níveis `debug`, `info`, `warn`, `error` e `success`; logs enviados **incrementalmente** ao app (PATCHes com throttle), visíveis na solicitação em tempo quase real. Cada linha também é **impressa no terminal local** como `[hobots:<task>] INFO mensagem`, colorida por nível — útil para acompanhar o robô rodando na VM. A cor é desligada automaticamente fora de um TTY e quando a env `NO_COLOR` está definida; o eco local é independente do envio ao servidor.
+- **`ctx.items`** — registro dos **itens que a execução processou/gerou** (notas fiscais baixadas, boletos emitidos…), com status e atributos. Aparecem na aba "itens" da solicitação, com totalizadores (veja a seção abaixo).
 - **`ctx.tx`** — a [transaction de performance](./concepts.md#transaction-de-run-ctxtx) desta run, já correlacionada e finalizada pelo SDK. Use `ctx.tx.startChild()` para medir as etapas (veja abaixo).
 - **`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.
@@ -68,6 +70,66 @@ Você pode tipar os params: `Hobots.register<{ lote: number }>(...)`.
 
 > **Dados sensíveis:** o que você escreve em `ctx.log` e as mensagens/stack de erros lançados **são enviados ao servidor** e ficam visíveis na execução no app. Não inclua senhas, tokens, documentos, dados pessoais ou qualquer informação sensível em logs e mensagens de erro.
 
+## Itens de execução (`ctx.items`)
+
+Logs contam **como** o bot trabalhou; itens contam **o que** ele entregou. Cada item é uma unidade de negócio processada pela execução — uma nota fiscal baixada, um boleto emitido — registrada com um dos três status:
+
+- **`succeeded`** — processado com sucesso.
+- **`failed`** — falha técnica ao processar o item (ex.: o download quebrou).
+- **`occurrence`** — ocorrência de negócio, que não é falha do bot (ex.: "nota nº 10 não encontrada", "CNPJ do prestador incorreto").
+
+```js
+Hobots.register('baixar-notas', async (params, ctx) => {
+  for (const nota of await listarNotas(params)) {
+    try {
+      if (!(await existeNoPortal(nota))) {
+        ctx.items.occurrence(`nota nº ${nota.numero} não encontrada`, { numero_nota: nota.numero }, { id: nota.numero });
+        continue;
+      }
+      await baixar(nota);
+      ctx.items.succeeded({ numero_nota: nota.numero, cnpj_prestador: nota.cnpj }, { id: nota.numero });
+    } catch (erro) {
+      ctx.items.failed(String(erro), { numero_nota: nota.numero }, { id: nota.numero });
+    }
+  }
+});
+```
+
+Na plataforma, os itens aparecem na aba **itens** da solicitação, com totalizadores (total, sucesso, falhas, ocorrências), filtro por status e paginação. As chaves do `payload` que viram **colunas** da tabela são configuradas por formulário em Configurações → Formulários → itens da execução — o `payload` aceita qualquer atributo que você julgar útil (só as chaves configuradas são exibidas; o restante fica no registro).
+
+### API
+
+```ts
+interface RunItems {
+  add(item: { status: 'succeeded' | 'failed' | 'occurrence'; id?: string; message?: string; payload?: Record<string, unknown> }): void;
+  succeeded(payload?, options?: { id?: string }): void;
+  failed(message, payload?, options?: { id?: string }): void;
+  occurrence(message, payload?, options?: { id?: string }): void;
+}
+```
+
+- **`id`** (opcional) — identidade de negócio do item **dentro da run** (ex.: nº da nota). Registrado uma vez: um `id` repetido na mesma run é **ignorado pelo servidor** (primeiro vence), o que torna o retry de rede idempotente. Sem `id`, o SDK gera um único e cada chamada vira um item novo.
+- **`message`** — o motivo, esperado em `failed`/`occurrence` (cap 2.000 caracteres). Passa por `scrubSecrets`, como os logs.
+- **`payload`** — atributos livres do item (cap 16 KB serializado; acima disso o payload é descartado com aviso e o item mantido). Strings passam por `scrubSecrets`.
+- **Registro único** — o item chega com o status final; não existe "atualizar item". Se o bot reprocessa, use outra run (retry cria uma run nova, com itens próprios).
+
+### Como funciona (e por que não trava a run)
+
+As chamadas são **síncronas** (nunca esperam rede): os itens entram num buffer próprio, separado da fila de status/logs, e sobem em lotes (flush a cada 2s ou 100 itens, POSTs de até 500). Antes do reporte final (`succeeded`/`failed`), o SDK **drena o buffer** (teto de 15s) — os totalizadores da solicitação ficam completos quando ela termina.
+
+Diferente de logs e status, **uma run cancelada continua aceitando itens**: item é fato de trabalho já feito, e o handler pode continuar rodando após o cancelamento cooperativo.
+
+### Limites
+
+| Limite | Valor |
+| --- | --- |
+| Itens por execução | **10.000** (acima disso o SDK descarta com um aviso) |
+| Itens por request | 500 (o SDK fatia sozinho) |
+| `payload` por item | 16 KB serializado |
+| `message` | 2.000 caracteres |
+
+> **Dados sensíveis:** como os logs, `message` e `payload` **são enviados ao servidor** e ficam visíveis na solicitação. Não inclua senhas, tokens ou dados pessoais desnecessários.
+
 ## Anexos (screenshots)
 
 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hobots",
-  "version": "1.9.2",
+  "version": "2.0.0",
   "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,