hobots 1.10.0 → 2.0.1

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  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":[]}
+{"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\n/**\n * Tipo de um evento — o que ele é, não o quanto ele fala. Só 'fatal', 'error' e\n * 'warning' viram issue; 'success' é ingerido e nunca abre issue.\n * Ruído de log não é evento: para isso existem os logs da execução (RunLogLevel)\n * e as breadcrumbs, que têm níveis próprios com 'debug'/'info'.\n */\nexport type EventType = 'fatal' | 'error' | 'warning' | 'success';\n\n/** Nível de uma breadcrumb — trilha do que aconteceu antes, aqui log é bem-vindo. */\nexport type BreadcrumbLevel = 'debug' | 'info' | 'warning' | 'error' | 'fatal';\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?: BreadcrumbLevel;\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  type: EventType;\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) */
@@ -150,7 +155,15 @@ interface RunAttachmentConfirmResponse {
  * contra estes tipos (importados de `hobots/protocol`).
  */
 
-type Severity = 'fatal' | 'error' | 'warning' | 'info' | 'debug' | 'success';
+/**
+ * Tipo de um evento — o que ele é, não o quanto ele fala. Só 'fatal', 'error' e
+ * 'warning' viram issue; 'success' é ingerido e nunca abre issue.
+ * Ruído de log não é evento: para isso existem os logs da execução (RunLogLevel)
+ * e as breadcrumbs, que têm níveis próprios com 'debug'/'info'.
+ */
+type EventType = 'fatal' | 'error' | 'warning' | 'success';
+/** Nível de uma breadcrumb — trilha do que aconteceu antes, aqui log é bem-vindo. */
+type BreadcrumbLevel = 'debug' | 'info' | 'warning' | 'error' | 'fatal';
 /** Frames em ordem innermost-first (mesma ordem impressa pelo V8). */
 interface StackFrame {
     function?: string;
@@ -165,7 +178,7 @@ interface Breadcrumb {
     type?: string;
     category?: string;
     message?: string;
-    level?: Severity;
+    level?: BreadcrumbLevel;
     data?: Record<string, unknown>;
 }
 interface ExceptionData {
@@ -185,7 +198,7 @@ interface EventPayload {
     event_id: string;
     /** ISO 8601 */
     timestamp: string;
-    level: Severity;
+    type: EventType;
     message?: string;
     exception?: ExceptionData;
     /** Override de agrupamento; quando ausente o servidor calcula pelo stack trace */
@@ -256,4 +269,4 @@ interface Envelope {
     items: EnvelopeItem[];
 }
 
-export type { AgentInfo, Breadcrumb, Envelope, EnvelopeItem, EventPayload, EventUser, ExceptionData, HeartbeatPayload, PollRequest, PollResponse, RunAttachmentConfirmRequest, RunAttachmentConfirmResponse, RunAttachmentContentType, RunAttachmentCreateRequest, RunAttachmentCreateResponse, RunDescriptor, RunError, RunItemInput, RunItemStatus, RunItemsCreateRequest, RunItemsCreateResponse, RunLogEntry, RunLogLevel, RunStatus, RunUpdateRequest, RunUpdateResponse, RunUpdateStatus, Severity, StackFrame, StepData, StepStatus, TransactionPayload };
+export type { Breadcrumb, BreadcrumbLevel, Envelope, EnvelopeItem, EventPayload, EventType, EventUser, ExceptionData, HeartbeatPayload, InstanceInfo, PollRequest, PollResponse, RunAttachmentConfirmRequest, RunAttachmentConfirmResponse, RunAttachmentContentType, RunAttachmentCreateRequest, RunAttachmentCreateResponse, RunDescriptor, RunError, RunItemInput, RunItemStatus, RunItemsCreateRequest, RunItemsCreateResponse, RunLogEntry, RunLogLevel, RunStatus, RunUpdateRequest, RunUpdateResponse, RunUpdateStatus, 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) */
@@ -150,7 +155,15 @@ interface RunAttachmentConfirmResponse {
  * contra estes tipos (importados de `hobots/protocol`).
  */
 
-type Severity = 'fatal' | 'error' | 'warning' | 'info' | 'debug' | 'success';
+/**
+ * Tipo de um evento — o que ele é, não o quanto ele fala. Só 'fatal', 'error' e
+ * 'warning' viram issue; 'success' é ingerido e nunca abre issue.
+ * Ruído de log não é evento: para isso existem os logs da execução (RunLogLevel)
+ * e as breadcrumbs, que têm níveis próprios com 'debug'/'info'.
+ */
+type EventType = 'fatal' | 'error' | 'warning' | 'success';
+/** Nível de uma breadcrumb — trilha do que aconteceu antes, aqui log é bem-vindo. */
+type BreadcrumbLevel = 'debug' | 'info' | 'warning' | 'error' | 'fatal';
 /** Frames em ordem innermost-first (mesma ordem impressa pelo V8). */
 interface StackFrame {
     function?: string;
@@ -165,7 +178,7 @@ interface Breadcrumb {
     type?: string;
     category?: string;
     message?: string;
-    level?: Severity;
+    level?: BreadcrumbLevel;
     data?: Record<string, unknown>;
 }
 interface ExceptionData {
@@ -185,7 +198,7 @@ interface EventPayload {
     event_id: string;
     /** ISO 8601 */
     timestamp: string;
-    level: Severity;
+    type: EventType;
     message?: string;
     exception?: ExceptionData;
     /** Override de agrupamento; quando ausente o servidor calcula pelo stack trace */
@@ -256,4 +269,4 @@ interface Envelope {
     items: EnvelopeItem[];
 }
 
-export type { AgentInfo, Breadcrumb, Envelope, EnvelopeItem, EventPayload, EventUser, ExceptionData, HeartbeatPayload, PollRequest, PollResponse, RunAttachmentConfirmRequest, RunAttachmentConfirmResponse, RunAttachmentContentType, RunAttachmentCreateRequest, RunAttachmentCreateResponse, RunDescriptor, RunError, RunItemInput, RunItemStatus, RunItemsCreateRequest, RunItemsCreateResponse, RunLogEntry, RunLogLevel, RunStatus, RunUpdateRequest, RunUpdateResponse, RunUpdateStatus, Severity, StackFrame, StepData, StepStatus, TransactionPayload };
+export type { Breadcrumb, BreadcrumbLevel, Envelope, EnvelopeItem, EventPayload, EventType, EventUser, ExceptionData, HeartbeatPayload, InstanceInfo, PollRequest, PollResponse, RunAttachmentConfirmRequest, RunAttachmentConfirmResponse, RunAttachmentContentType, RunAttachmentCreateRequest, RunAttachmentCreateResponse, RunDescriptor, RunError, RunItemInput, RunItemStatus, RunItemsCreateRequest, RunItemsCreateResponse, RunLogEntry, RunLogLevel, RunStatus, RunUpdateRequest, RunUpdateResponse, RunUpdateStatus, StackFrame, StepData, StepStatus, TransactionPayload };

package/docs/api-reference.md

@@ -16,7 +16,7 @@
 | `init` | `init(options: InitOptions): void` | — |
 | `getClient` | `getClient(): Client \| undefined` | cliente atual |
 | `captureException` | `captureException(error: unknown, hint?: CaptureHint)` | `string \| undefined` (event_id — **não** é confirmação de envio) |
-| `captureMessage` | `captureMessage(message: string, level?: Severity, hint?: CaptureHint)` | `string \| undefined` (idem) |
+| `captureMessage` | `captureMessage(message: string, type?: EventType, hint?: CaptureHint)` | `string \| undefined` (idem) |
 | `addBreadcrumb` | `addBreadcrumb(crumb: BreadcrumbInput): void` | — |
 | `setTag` / `setTags` | `setTag(key, value)` · `setTags(tags)` | — |
 | `setUser` | `setUser(user: EventUser \| null): void` | — |
@@ -33,8 +33,8 @@ Os conceitos por trás dessas chamadas estão em [Conceitos](./concepts.md); aqu
 
 - **`init(options)`** — cria o cliente, instala os handlers globais de erro (a menos que `captureUnhandled: false`), inicia o heartbeat se configurado e cria o agente de tasks se `tasks` foi passado. Chamar de novo **substitui** o cliente e o agente (os handlers registrados com `register` são preservados; o [scope](./concepts.md#scope) **não** é limpo). Chame uma vez, o mais cedo possível.
 - **`getClient()`** — devolve o cliente atual ou `undefined` se o `init()` nunca rodou. Útil para checar se o SDK está ativo. A config resolvida (URL base e endpoints) é acessível via `getClient()?.config` (veja abaixo).
-- **`captureException(error, hint?)`** — monta um [evento](./concepts.md#evento) a partir da exceção (tipo, mensagem, stack trace), mescla o scope e enfileira. O `level` é `error` a menos que você passe outro no `hint`.
-- **`captureMessage(message, level = 'info', hint?)`** — mesma coisa, sem exceção: um evento só com texto. Bom para marcos (`'success'`) e avisos que não são erro.
+- **`captureException(error, hint?)`** — monta um [evento](./concepts.md#evento) a partir da exceção (tipo, mensagem, stack trace), mescla o scope e enfileira. O `type` é `error` a menos que você passe outro no `hint`.
+- **`captureMessage(message, type = 'warning', hint?)`** — mesma coisa, sem exceção: um evento só com texto. Bom para marcos (`'success'`) e avisos que não são erro.
   > **Atenção:** as duas devolvem um `event_id` **mesmo quando o evento foi descartado** por [amostragem](./concepts.md#amostragem-samplerate-e-tracessamplerate) ou por [`beforeSend`](./concepts.md#beforesend). O retorno não prova que algo foi enviado — só é `undefined` quando o `init()` não foi chamado.
 - **`addBreadcrumb(crumb)`** — adiciona uma migalha à trilha do [scope](./concepts.md#scope) global. Todos os campos são opcionais menos o `timestamp`, que o SDK preenche. A lista **não** é limpa ao enviar um evento; ela só descarta as mais antigas ao estourar `maxBreadcrumbs`. Conceito: [Breadcrumb](./concepts.md#breadcrumb).
 - **`setTag(key, value)` / `setTags(tags)`** — grava [tags](./concepts.md#tag) no scope global; valem para todos os eventos seguintes. Só `string` → `string`. Precedência: `init.tags` → scope → evento → `hint`.
@@ -63,8 +63,8 @@ Todos encadeáveis, exceto `finish()` e `toJSON()`.
 
 - **`Transaction`** — `startChild(op?, description?) → Step` abre uma [step](./concepts.md#step) direta; `setTag(k, v)` marca a transaction (tags de scope **não** são herdadas); `setStatus(s)` (default `'ok'`); `setName(n)` renomeia antes do envio; `finish()` fecha as etapas abertas, monta o payload e envia — é **idempotente** e não envia nada se a transaction não foi amostrada.
 - **`Step`** — `startChild(op?, description?) → Step` aninha uma filha (profundidade arbitrária); `setStatus(s)` (default `'ok'`); `setData(k, v)` anexa dados só àquela step; `finish()` marca o fim — **opcional**, porque o `finish()` da transaction fecha o que ficou aberto; `toJSON()` serializa no formato do wire.
-- **`Scope`** — `setTag`/`setTags`/`setUser`/`setContext`/`setExtra`/`setExtras`/`setLevel`/`setFingerprint`/`addBreadcrumb`/`clearBreadcrumbs`/`clone`. Alcançável via [`withScope`](./concepts.md#withscope). `setContext(name, null)` apaga o grupo; `setUser(null)` remove o usuário.
-  > **Atenção:** `setLevel` **não tem efeito** em `captureException` (que já grava `error`) nem em `captureMessage` (que já grava `info`) — os dois definem o level do evento antes de o scope ser consultado. Use o `hint`.
+- **`Scope`** — `setTag`/`setTags`/`setUser`/`setContext`/`setExtra`/`setExtras`/`setType`/`setFingerprint`/`addBreadcrumb`/`clearBreadcrumbs`/`clone`. Alcançável via [`withScope`](./concepts.md#withscope). `setContext(name, null)` apaga o grupo; `setUser(null)` remove o usuário.
+  > **Atenção:** `setType` **não tem efeito** em `captureException` (que já grava `error`) nem em `captureMessage` (que já grava `warning`) — os dois definem o tipo do evento antes de o scope ser consultado. Use o `hint`.
 
 ---
 
@@ -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.
 
 ---
 
@@ -124,7 +124,7 @@ O teto da fila do transport (200 itens; ao encher, o **mais antigo** é descarta
 
 | Campo | Tipo | Descrição |
 | --- | --- | --- |
-| `level` | `Severity` | nível do evento |
+| `type` | `EventType` | tipo do evento |
 | `tags` | `Record<string,string>` | tags só deste evento |
 | `extra` | `Record<string,unknown>` | dados extras |
 | `fingerprint` | `string[]` | agrupamento manual |
@@ -142,7 +142,7 @@ O teto da fila do transport (200 itens; ao encher, o **mais antigo** é descarta
 
 O texto da linha de log é a mensagem capturada; o nível vem do `level` da captura (`'fatal'` vira `'error'`). O upload roda em segundo plano e **nunca bloqueia nem faz a captura lançar**. Limites (todos aplicados também no servidor): PNG/JPEG/WEBP, **5 MB** por imagem, **20** anexos por execução, **4** por linha de log.
 
-`Severity = 'fatal' | 'error' | 'warning' | 'info' | 'debug' | 'success'`. O que cada nível significa (e por que `'success'` existe) em [Level](./concepts.md#level-severity).
+`EventType = 'fatal' | 'error' | 'warning' | 'success'`. O que cada tipo significa (e por que `'success'` existe) em [Type](./concepts.md#type-tipo-do-evento).
 
 ### TasksOptions
 

package/docs/concepts.md

@@ -11,7 +11,7 @@ Os defaults numéricos **não** estão aqui — eles vivem em [Tempos e interval
 | Conceito                                                | Em uma frase                                             | Quando você usa                                             |
 | ------------------------------------------------------- | -------------------------------------------------------- | ----------------------------------------------------------- |
 | [Evento](#evento)                                       | Uma foto de algo que aconteceu — um erro ou uma mensagem | `captureException` / `captureMessage`                       |
-| [Level](#level-severity)                                | A gravidade do evento                                    | Para separar o que acorda alguém do que é só registro       |
+| [Type](#type-tipo-do-evento)                            | O que o evento é                                         | Para separar o que acorda alguém do que é só registro       |
 | [Fingerprint](#fingerprint)                             | A chave de agrupamento dos eventos em issues             | Quando o agrupamento automático erra                        |
 | [Scope](#scope)                                         | A mochila de contexto que viaja com todo evento          | Você raramente mexe direto; mexe pelos `set*`               |
 | [withScope](#withscope)                                 | Um scope temporário e isolado                            | Contexto que **não** deve vazar para o resto do programa    |
@@ -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**) |
 
 ---
@@ -58,28 +58,30 @@ No servidor, eventos parecidos são agrupados numa **issue** — o que você vê
 
 ```js
 Hobots.captureException(error);
-Hobots.captureMessage('Lote processado com sucesso', 'info');
+Hobots.captureMessage('Lote processado com sucesso', 'success');
 ```
 
 As duas devolvem o `event_id` (um uuid), útil para você logar junto e depois achar o evento no app.
 
 > **Atenção:** o `event_id` devolvido **não é confirmação de envio**. Se o evento foi descartado por [amostragem](#amostragem-samplerate-e-tracessamplerate) ou por [`beforeSend`](#beforesend), você recebe um id normalmente e nada foi enfileirado. Elas devolvem `undefined` só quando o `init()` nunca foi chamado.
 
-## Level (Severity)
+## Type (tipo do evento)
 
-O **level** é a gravidade do evento. São seis: `fatal`, `error`, `warning`, `info`, `debug` e `success`.
+O **type** é o que o evento é. São quatro: `fatal`, `error`, `warning` e `success`.
 
-Serve para você separar o que precisa acordar alguém do que é só registro histórico. `error` e `fatal` são problemas; `warning` é algo que ainda funciona mas merece olhar; `info` e `debug` são narração.
+Serve para você separar o que precisa acordar alguém do que é só registro. `error` e `fatal` são problemas (e são os únicos que disparam alerta); `warning` é algo que ainda funciona mas merece olhar — aparece nas issues, sem e-mail.
 
 O `success` é o mais incomum e o mais útil no dia a dia de RPA: ele marca uma conclusão **bem-sucedida**. Conta como evento e aparece na timeline do robô, mas **não gera issue nem alerta** — é o jeito de registrar "as 120 notas do dia foram emitidas" sem que isso pareça um problema.
 
-A precedência é: o `level` do `hint` que você passou → o level que a função de captura já definiu → `error`. Na prática:
+Não existe tipo `info` nem `debug`: narração não é problema e não abre issue. Para isso existem o [log da execução](./tasks.md#logs) (`ctx.log.debug/info/...`) e as [breadcrumbs](#breadcrumb), que têm o seu próprio nível.
+
+A precedência é: o `type` do `hint` que você passou → o tipo que a função de captura já definiu → `error`. Na prática:
 
 - `captureException(error)` sem `hint` é sempre `error`.
-- `captureMessage(msg)` sem level explícito é sempre `info`.
-- Para qualquer outra coisa, passe o level: `captureException(error, { level: 'warning' })`.
+- `captureMessage(msg)` sem tipo explícito é sempre `warning`.
+- Para qualquer outra coisa, passe o tipo: `captureException(error, { type: 'warning' })`.
 
-> **Atenção:** `scope.setLevel()` (dentro de um [`withScope`](#withscope)) **não afeta** `captureException` nem `captureMessage` — as duas já definem o level do evento antes de o scope ser consultado. Para mudar o level, use o `hint` (`{ level: … }`) ou o segundo argumento do `captureMessage`.
+> **Atenção:** `scope.setType()` (dentro de um [`withScope`](#withscope)) **não afeta** `captureException` nem `captureMessage` — as duas já definem o tipo do evento antes de o scope ser consultado. Para mudar o tipo, use o `hint` (`{ type: … }`) ou o segundo argumento do `captureMessage`.
 
 ## Fingerprint
 
@@ -100,7 +102,7 @@ O fingerprint é um array de strings — o servidor concatena os pedaços. Prece
 
 ## Scope
 
-O **scope** é a mochila de contexto do SDK: tudo que ele sabe sobre o estado atual do seu programa e que deve viajar junto do próximo evento. Dentro dela: [tags](#tag), [usuário](#scope), [contexts](#context), [extras](#extra), level, [fingerprint](#fingerprint) e a lista de [breadcrumbs](#breadcrumb).
+O **scope** é a mochila de contexto do SDK: tudo que ele sabe sobre o estado atual do seu programa e que deve viajar junto do próximo evento. Dentro dela: [tags](#tag), [usuário](#scope), [contexts](#context), [extras](#extra), tipo, [fingerprint](#fingerprint) e a lista de [breadcrumbs](#breadcrumb).
 
 Você não manipula o scope direto — você usa os `set*`, que escrevem nele:
 
@@ -203,7 +205,7 @@ O SDK mantém em memória a lista dos últimos breadcrumbs. Quando você captura
 Hobots.addBreadcrumb({ category: 'nfe', message: 'Baixou XML da nota 123', level: 'info' });
 ```
 
-Todos os campos são opcionais: `category` agrupa a origem, `message` é o texto lido por humano, `level` colore a linha na timeline, `data` carrega um objeto livre, `type` classifica a migalha. O `timestamp` é preenchido pelo SDK.
+Todos os campos são opcionais: `category` agrupa a origem, `message` é o texto lido por humano, `level` (`debug`, `info`, `warning`, `error`, `fatal`) colore a linha na timeline, `data` carrega um objeto livre, `type` classifica a migalha. O `timestamp` é preenchido pelo SDK.
 
 Dois pontos que costumam surpreender:
 

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]`.
 

package/docs/tasks.md

@@ -171,7 +171,7 @@ O `attachment` pode ser a imagem direto, ou um objeto com metadados:
 | `caption` | `string` | — | legenda curta exibida sob a imagem ampliada (máx. 200 caracteres) |
 | `contentType` | `'image/png' \| 'image/jpeg' \| 'image/webp'` | detectado | só é usado quando os *magic bytes* não bastam |
 
-O texto da linha de log é a própria mensagem capturada (`message` do `captureMessage`, ou `Nome: mensagem` do erro no `captureException`); o nível vem do `level` da captura (`'fatal'` vira `'error'` no log da run).
+O texto da linha de log é a própria mensagem capturada (`message` do `captureMessage`, ou `Nome: mensagem` do erro no `captureException`); o nível vem do `type` da captura (`'fatal'` vira `'error'` no log da run).
 
 ### Limites
 

package/docs/telemetry.md

@@ -29,7 +29,7 @@ Cria o cliente, instala handlers globais de erro (a menos que `captureUnhandled:
 // exceções
 Hobots.captureException(error, {
   tags: { cliente: 'acme' },
-  level: 'error',
+  type: 'error',
   fingerprint: ['sefaz-timeout'], // agrupa manualmente; sem isso o servidor agrupa pelo stack
 });
 
@@ -37,13 +37,13 @@ Hobots.captureException(error, {
 Hobots.captureMessage('Lote processado com sucesso', 'info');
 ```
 
-Ambas retornam o `event_id` (ou `undefined` se não inicializado). O segundo argumento é um [`CaptureHint`](./api-reference.md#capturehint) (`level`, `tags`, `extra`, `fingerprint`).
+Ambas retornam o `event_id` (ou `undefined` se não inicializado). O segundo argumento é um [`CaptureHint`](./api-reference.md#capturehint) (`type`, `tags`, `extra`, `fingerprint`).
 
 > **Atenção:** o `event_id` retornado **não é confirmação de envio** — se o evento foi descartado por amostragem ou por `beforeSend`, você recebe um id normalmente e nada foi enfileirado.
 
 Erros **não tratados** (`uncaughtException` / `unhandledRejection`) são capturados e flushados automaticamente antes do processo sair — desligue com `captureUnhandled: false`.
 
-Conceitos: [Evento](./concepts.md#evento) · [Level](./concepts.md#level-severity) · [Fingerprint](./concepts.md#fingerprint).
+Conceitos: [Evento](./concepts.md#evento) · [Type](./concepts.md#type-tipo-do-evento) · [Fingerprint](./concepts.md#fingerprint).
 
 ## Breadcrumbs
 

package/package.json

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