hobots 4.5.0 → 5.0.0

package/dist/protocol.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/protocol.ts","../protocol-limits.json","../src/wire-limits.ts"],"sourcesContent":["/**\n * Tipos do protocolo do Hobots (SDK → servidor).\n *\n * Este arquivo é a fonte de verdade do wire format: reexporta tipos (o app valida\n * os payloads com zod e trava o drift via `satisfies z.ZodType<...>` contra eles)\n * e os LIMITES numéricos do wire (WIRE_LIMITS, de protocol-limits.json) — o único\n * valor de runtime daqui, para a api aplicar exatamente os caps que o SDK aplica.\n */\n\nexport { WIRE_LIMITS, type WireLimits } from './wire-limits';\n\nimport type { EnvironmentInput } from './environment-protocol';\nimport type { MachineSnapshot } from './machine-protocol';\n\n// Wire format de execuções (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  RunCreateRequest,\n  RunCreateResponse,\n  RunStartRequest,\n  RunStartResponse,\n  RunError,\n  RunProgress,\n  RunUpdateRequest,\n  RunUpdateResponse,\n  RunItemStatus,\n  RunItemInput,\n  RunItemsCreateRequest,\n  RunItemsCreateResponse,\n  ItemColumn,\n  ItemsDeclaration,\n  InstanceMode,\n  RunAttachmentContentType,\n  RunAttachmentCreateRequest,\n  RunAttachmentCreateResponse,\n  RunAttachmentConfirmRequest,\n  RunAttachmentConfirmResponse,\n  FileStorage,\n  FileRef,\n  FileDownloadResponse,\n} from './tasks/protocol';\n\n// Snapshot de recursos da máquina — usado no heartbeat, no poll e em contexts.machine.\nexport type { MachineProcess, MachineSnapshot } from './machine-protocol';\nexport type { Environment, EnvironmentInput } from './environment-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?: EnvironmentInput;\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?: EnvironmentInput;\n  /** Correlaciona esta transaction a uma execução do agente (hobots.transaction dentro do 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  /** Ambiente da instância — é ele que o app exibe e que as regras de alerta filtram */\n  environment?: EnvironmentInput;\n  /** Recursos da máquina no momento do beat (CPU, memória, disco, processo) */\n  machine?: MachineSnapshot;\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","{\n  \"MAX_ITEMS_PER_ENVELOPE\": 50,\n  \"HEARTBEAT_DEFAULT_INTERVAL_MS\": 30000,\n  \"HEARTBEAT_MIN_INTERVAL_MS\": 1000,\n  \"HEARTBEAT_MAX_INTERVAL_MS\": 900000,\n  \"MAX_CLAIM_PER_POLL\": 5,\n  \"MAX_LOG_MESSAGE_CHARS\": 10000,\n  \"MAX_LOGS_PER_PATCH\": 100,\n  \"MAX_ERROR_MESSAGE_CHARS\": 10000,\n  \"MAX_ERROR_STACK_CHARS\": 20000,\n  \"MAX_ITEMS_PER_REQUEST\": 500,\n  \"MAX_ITEM_MESSAGE_CHARS\": 2000,\n  \"MAX_ITEM_PAYLOAD_BYTES\": 16384,\n  \"MAX_ITEM_COLUMNS\": 12,\n  \"MAX_ITEM_COLUMN_LABEL_CHARS\": 60,\n  \"MAX_ATTACHMENT_BYTES\": 5242880,\n  \"MAX_ATTACHMENTS_PER_RUN\": 20,\n  \"MAX_ATTACHMENTS_PER_LOG_ENTRY\": 4,\n  \"MAX_CAPTION_CHARS\": 200,\n  \"MAX_IMAGE_DIMENSION_PX\": 20000\n}\n","import limits from '../protocol-limits.json';\n\n/**\n * Limites do wire SDK ↔ servidor — fonte ÚNICA (protocol-limits.json): o SDK\n * Node lê daqui, a @hobots/api importa de `hobots/protocol` e o SDK Python\n * confere a paridade num teste que lê o mesmo JSON. Mudar um limite = mudar o\n * JSON (e, no Python, a constante espelhada — o teste acusa).\n */\nexport const WIRE_LIMITS = limits as Readonly<typeof limits>;\nexport type WireLimits = typeof WIRE_LIMITS;\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACAA;AAAA,EACE,wBAA0B;AAAA,EAC1B,+BAAiC;AAAA,EACjC,2BAA6B;AAAA,EAC7B,2BAA6B;AAAA,EAC7B,oBAAsB;AAAA,EACtB,uBAAyB;AAAA,EACzB,oBAAsB;AAAA,EACtB,yBAA2B;AAAA,EAC3B,uBAAyB;AAAA,EACzB,uBAAyB;AAAA,EACzB,wBAA0B;AAAA,EAC1B,wBAA0B;AAAA,EAC1B,kBAAoB;AAAA,EACpB,6BAA+B;AAAA,EAC/B,sBAAwB;AAAA,EACxB,yBAA2B;AAAA,EAC3B,+BAAiC;AAAA,EACjC,mBAAqB;AAAA,EACrB,wBAA0B;AAC5B;;;ACZO,IAAM,cAAc;","names":[]}
+{"version":3,"sources":["../src/protocol.ts","../protocol-limits.json","../src/wire-limits.ts"],"sourcesContent":["/**\n * Tipos do protocolo do Hobots (SDK → servidor).\n *\n * Este arquivo é a fonte de verdade do wire format: reexporta tipos (o app valida\n * os payloads com zod e trava o drift via `satisfies z.ZodType<...>` contra eles)\n * e os LIMITES numéricos do wire (WIRE_LIMITS, de protocol-limits.json) — o único\n * valor de runtime daqui, para a api aplicar exatamente os caps que o SDK aplica.\n */\n\nexport { WIRE_LIMITS, type WireLimits } from './wire-limits';\n\nimport type { EnvironmentInput } from './environment-protocol';\nimport type { MachineSnapshot } from './machine-protocol';\n\n// Wire format de execuções (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  RunCreateRequest,\n  RunCreateResponse,\n  RunStartRequest,\n  RunStartResponse,\n  RunError,\n  RunProgress,\n  RunUpdateRequest,\n  RunUpdateResponse,\n  RunItemStatus,\n  RunItemInput,\n  RunItemsCreateRequest,\n  RunItemsCreateResponse,\n  ItemColumn,\n  ItemsDeclaration,\n  InstanceMode,\n  RunAttachmentContentType,\n  RunAttachmentCreateRequest,\n  RunAttachmentCreateResponse,\n  RunAttachmentConfirmRequest,\n  RunAttachmentConfirmResponse,\n  FileStorage,\n  FileRef,\n  FileDownloadResponse,\n} from './tasks/protocol';\n\n// Snapshot de recursos da máquina — usado no heartbeat, no poll e em contexts.machine.\nexport type { MachineProcess, MachineSnapshot } from './machine-protocol';\nexport type { Environment, EnvironmentInput } from './environment-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?: EnvironmentInput;\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?: EnvironmentInput;\n  /** Correlaciona esta transaction a uma execução do agente (as etapas de hobots.step dentro do 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  /** Ambiente da instância — é ele que o app exibe e que as regras de alerta filtram */\n  environment?: EnvironmentInput;\n  /** Recursos da máquina no momento do beat (CPU, memória, disco, processo) */\n  machine?: MachineSnapshot;\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","{\n  \"MAX_ITEMS_PER_ENVELOPE\": 50,\n  \"HEARTBEAT_DEFAULT_INTERVAL_MS\": 30000,\n  \"HEARTBEAT_MIN_INTERVAL_MS\": 1000,\n  \"HEARTBEAT_MAX_INTERVAL_MS\": 900000,\n  \"MAX_CLAIM_PER_POLL\": 5,\n  \"MAX_LOG_MESSAGE_CHARS\": 10000,\n  \"MAX_LOGS_PER_PATCH\": 100,\n  \"MAX_ERROR_MESSAGE_CHARS\": 10000,\n  \"MAX_ERROR_STACK_CHARS\": 20000,\n  \"MAX_ITEMS_PER_REQUEST\": 500,\n  \"MAX_ITEM_MESSAGE_CHARS\": 2000,\n  \"MAX_ITEM_PAYLOAD_BYTES\": 16384,\n  \"MAX_ITEM_COLUMNS\": 12,\n  \"MAX_ITEM_COLUMN_LABEL_CHARS\": 60,\n  \"MAX_ATTACHMENT_BYTES\": 5242880,\n  \"MAX_ATTACHMENTS_PER_RUN\": 20,\n  \"MAX_ATTACHMENTS_PER_LOG_ENTRY\": 4,\n  \"MAX_CAPTION_CHARS\": 200,\n  \"MAX_IMAGE_DIMENSION_PX\": 20000\n}\n","import limits from '../protocol-limits.json';\n\n/**\n * Limites do wire SDK ↔ servidor — fonte ÚNICA (protocol-limits.json): o SDK\n * Node lê daqui, a @hobots/api importa de `hobots/protocol` e o SDK Python\n * confere a paridade num teste que lê o mesmo JSON. Mudar um limite = mudar o\n * JSON (e, no Python, a constante espelhada — o teste acusa).\n */\nexport const WIRE_LIMITS = limits as Readonly<typeof limits>;\nexport type WireLimits = typeof WIRE_LIMITS;\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACAA;AAAA,EACE,wBAA0B;AAAA,EAC1B,+BAAiC;AAAA,EACjC,2BAA6B;AAAA,EAC7B,2BAA6B;AAAA,EAC7B,oBAAsB;AAAA,EACtB,uBAAyB;AAAA,EACzB,oBAAsB;AAAA,EACtB,yBAA2B;AAAA,EAC3B,uBAAyB;AAAA,EACzB,uBAAyB;AAAA,EACzB,wBAA0B;AAAA,EAC1B,wBAA0B;AAAA,EAC1B,kBAAoB;AAAA,EACpB,6BAA+B;AAAA,EAC/B,sBAAwB;AAAA,EACxB,yBAA2B;AAAA,EAC3B,+BAAiC;AAAA,EACjC,mBAAqB;AAAA,EACrB,wBAA0B;AAC5B;;;ACZO,IAAM,cAAc;","names":[]}

package/dist/protocol.d.cts

@@ -146,7 +146,10 @@ interface RunDescriptor {
         id: string;
         name: string;
     } | null;
-    /** Origem da run: 'hobots' | 'link' | 'schedule' | 'agent' (informativo; 'agent' = aberta pelo próprio SDK, modo start) */
+    /**
+     * Origem da run: 'hobots' | 'link' | 'schedule' | 'agent' | 'local' (informativo; 'agent' = aberta pelo
+     * próprio SDK no modo start; 'local' = modo local, sem Central — nunca chega ao servidor)
+     */
     source: string;
     /** ISO 8601 (relógio do servidor) */
     created_at: string;
@@ -454,7 +457,7 @@ interface TransactionPayload {
     tags?: Record<string, string>;
     release?: string;
     environment?: EnvironmentInput;
-    /** Correlaciona esta transaction a uma execução do agente (hobots.transaction dentro do handler) */
+    /** Correlaciona esta transaction a uma execução do agente (as etapas de hobots.step dentro do handler) */
     run_id?: string;
 }
 interface HeartbeatPayload {

package/dist/protocol.d.ts

@@ -146,7 +146,10 @@ interface RunDescriptor {
         id: string;
         name: string;
     } | null;
-    /** Origem da run: 'hobots' | 'link' | 'schedule' | 'agent' (informativo; 'agent' = aberta pelo próprio SDK, modo start) */
+    /**
+     * Origem da run: 'hobots' | 'link' | 'schedule' | 'agent' | 'local' (informativo; 'agent' = aberta pelo
+     * próprio SDK no modo start; 'local' = modo local, sem Central — nunca chega ao servidor)
+     */
     source: string;
     /** ISO 8601 (relógio do servidor) */
     created_at: string;
@@ -454,7 +457,7 @@ interface TransactionPayload {
     tags?: Record<string, string>;
     release?: string;
     environment?: EnvironmentInput;
-    /** Correlaciona esta transaction a uma execução do agente (hobots.transaction dentro do handler) */
+    /** Correlaciona esta transaction a uma execução do agente (as etapas de hobots.step dentro do handler) */
     run_id?: string;
 }
 interface HeartbeatPayload {

package/docs/README.md

@@ -2,7 +2,7 @@
 
 SDK JavaScript da **Hobots** para robôs (RPAs) e integrações. Cliente HTTP puro, sem dependências de runtime, Node 18+.
 
-**O agente é a própria tarefa.** Não existe `init()` nem slug: a única chamada a `register()`/`start()` configura o processo (credenciais do ambiente, heartbeat sempre ligado, captura de erros não tratados) e diz o que o robô faz. O objeto global `hobots` expõe a execução atual — `hobots.log`, `hobots.items`, `hobots.progress`, `hobots.transaction`… — de qualquer lugar do programa.
+**O agente é a própria tarefa.** Não existe `init()` nem slug: a única chamada a `register()`/`start()` configura o processo (credenciais do ambiente, heartbeat sempre ligado, captura de erros não tratados) e diz o que o robô faz. O objeto global `hobots` expõe a execução atual — `hobots.log`, `hobots.items`, `hobots.progress`, `hobots.step`… — de qualquer lugar do programa.
 
 | Modo | Chamada | Para quê |
 | --- | --- | --- |
@@ -15,7 +15,7 @@ Uma chamada por processo: um processo é um agente, e um agente faz uma coisa.
 
 - [Getting started](./getting-started.md) — instalação, envs, o primeiro agente nos dois modos, encerramento.
 - [Execuções](./runs.md) — handler, o objeto `hobots`, itens, progresso, anexos, cancelamento automático, retry, concorrência, idempotência.
-- [Conceitos](./concepts.md) — o vocabulário: agente, execução, evento, issue, transaction, step, heartbeat, instância, claim.
+- [Conceitos](./concepts.md) — o vocabulário: agente, execução, evento, issue, etapa, heartbeat, instância, claim.
 - [Referência de API](./api-reference.md) — assinaturas, tabelas de opções e tempos.
 - [Protocolo & transporte](./protocol.md) — Client Secret, endpoints (`/v1/ingest`, `/v1/runs/*`), envelope, retries, claim atômico.
 

package/docs/api-reference.md

@@ -18,8 +18,9 @@ ESM e CommonJS (`const { hobots } = require('hobots')`), com `.d.ts`. Depois do
 | `hobots.close` | `(timeoutMs = 30_000) => Promise<boolean>` | Para o polling, espera as execuções em voo (até `timeoutMs`; as restantes viram `AgentTerminated`), para o heartbeat e faz o flush final. `false` se estourou. Um `register`/`start` depois inicia um runtime novo. |
 | `hobots.captureException` | `(error: unknown, hint?: CaptureHint) => string \| undefined` | Issue no módulo Issues; devolve o `event_id`. Antes de iniciar o agente: descarta com aviso. |
 | `hobots.retry` | `<T>(fn: (attempt: number) => T \| Promise<T>, options?: RetryOptions) => Promise<T>` | async-retry; dentro de uma execução usa o signal dela. |
-| `hobots.flush` | `(timeoutMs = 15_000) => Promise<void>` | Envia **agora** o que a execução atual acumulou: steps raiz finalizadas viram transactions parciais (op `hobots.run.flush`), itens, logs e progresso pendentes saem sem esperar o throttle. Aguarda a entrega até `timeoutMs`. Nunca lança; fora de uma execução não faz nada. Feito para o modo start, a cada ciclo. |
-| `hobots.image` | `(input: AttachInput, options?: ImageOptions) => ImageAttachment` | Embrulha um print para ir junto de um log, item ou step. Puro, nunca lança. |
+| `hobots.step` | `<T>(name: string, fn: (etapa: StepHandle) => T \| Promise<T>, options?: StepOptions) => Promise<T>` | Registra a etapa `name` executando `fn`, com nova tentativa quando ela lança (`retries` default 1, `retryDelayMs` default 5_000). Resolve com o retorno de `fn`. Fora de uma execução: aviso único e roda `fn` com o mesmo retry, sem registrar nada. Ver [Execuções](./runs.md#etapas-hobotsstep). |
+| `hobots.flush` | `(timeoutMs = 15_000) => Promise<void>` | Envia **agora** o que a execução atual acumulou: etapas raiz finalizadas viram transactions parciais (op `hobots.run.flush`), itens, logs e progresso pendentes saem sem esperar o throttle. Aguarda a entrega até `timeoutMs`. Nunca lança; fora de uma execução não faz nada. Feito para o modo start, a cada ciclo. |
+| `hobots.image` | `(input: AttachInput, options?: ImageOptions) => ImageAttachment` | Embrulha um print para ir junto de um log, item ou etapa. Puro, nunca lança. |
 | `isFileRef` / `hobots.isFileRef` | `(value: unknown) => value is FileRef` | Reconhece um arquivo de campo de upload nos params. Puro. |
 
 ## Contexto da execução (`RunContext` — os membros de `hobots` e o `ctx` do handler)
@@ -29,11 +30,11 @@ ESM e CommonJS (`const { hobots } = require('hobots')`), com `.d.ts`. Depois do
 | `runId` | `string` | Identidade da execução (`''` fora de uma execução) |
 | `params` | `Record<string, unknown>` | Params da solicitação (formulário do agente); `{}` no modo start |
 | `log` | `RunLogger` — `debug/info/warn/error/success(message, ...rest)` | Nunca lança. Vários argumentos viram texto unidos por espaço (como `console.log`); um `hobots.image(...)` no **último** argumento vira o print da linha. Eco no terminal: `[hobots] INFO …` |
-| `items` | `RunItems` — `add(item)`, `succeeded(payload?, opts?)`, `failed(message, payload?, opts?)`, `occurrence(message, payload?, opts?)`; `opts.id` = identidade de negócio, `opts.image` = print do item. `each(list, (element, item, index) => …, { id?, payload?, op?, description?, progress? }) => Promise<{ total, succeeded, failed, occurrence }>` processa a lista inteira: exceção no handler vira item `failed` + step em erro e o loop segue; `item: RunItemHandle` = `succeeded(payload?, { image }?)/failed(msg, payload?, { image }?)/occurrence(…)`, `id`, `index`, `step`, `reported` | Ponto de parada cooperativo (o `each` para só em cancelamento/timeout) |
+| `items` | `RunItems` — `add(item)`, `succeeded(payload?, opts?)`, `failed(message, payload?, opts?)`, `occurrence(message, payload?, opts?)`; `opts.id` = identidade de negócio, `opts.image` = print do item. `each(list, (element, item, index) => …, { id?, payload?, op?, description?, progress? }) => Promise<{ total, succeeded, failed, occurrence }>` processa a lista inteira: exceção no handler vira item `failed` + etapa em erro e o loop segue; `item: RunItemHandle` = `succeeded(payload?, { image }?)/failed(msg, payload?, { image }?)/occurrence(…)`, `id`, `index`, `step` (`StepHandle` da etapa do item), `reported` | Ponto de parada cooperativo (o `each` para só em cancelamento/timeout) |
 | `progress` | `RunProgressReporter` — `total(n)`, `advance(count = 1)`, `set(current, total?)`, `current`, `snapshot` | `total/advance/set` são pontos de parada |
 | `files` | `RunFiles` — `list(): FileRef[]`, `get(field): FileRef \| FileRef[] \| undefined`, `download(refOrField: FileRef \| string, { dest? }?): Promise<string>`, `downloadAll(field, { dest? }?): Promise<string[]>`, `read(refOrField): Promise<Buffer>` | Arquivos do formulário; o download consome a origem (S3 confirmado/apagado, pasta do Studio removida). Cópias sem `dest` são apagadas no fim da execução. Respeita o `signal`. Ver [Execuções](./runs.md#arquivos-do-formulário-hobotsfiles) |
-| `flush` | `(timeoutMs = 15_000) => Promise<void>` — envia já as steps raiz finalizadas (transactions parciais, op `hobots.run.flush`) e os itens/logs/progresso pendentes | Nunca lança |
-| `transaction` | `Transaction` (`run`, op `hobots.run`) — `start(op?, description?)`, `succeeded(op?)` / `failed(err, op?, { message, image }?)` (fecham a step aberta mais recente — com aquele `op` quando informado; sem step aberta, undefined), `flush()`, `setTag`, `setStatus`, `setName`; `Step` — `start`, `setStatus('ok' \| 'warning' \| 'error', message?, { image }?)`, `failed(err, message?, { image }?)` (marca `error` e fecha; motivo em `data.error`, print em `data.attachments`, exibidos na Central), `setData(k, v)`, `succeeded()` (fecha mantendo o status) | Finalizada pelo SDK; `start` é ponto de parada |
+| `step(name, fn, options?)` | `<T>(name: string, fn: StepFn<T>, options?: { retries?: number; retryDelayMs?: RetryDelay }) => Promise<T>` — uma etapa no waterfall: abre, roda `fn(etapa)`, tenta de novo se lançar (`retries` default 1; 0 desliga), fecha. `warning` + `data.message` + `data.attempts` quando a nova tentativa deu certo; `error` + `data.error = { type, message }` quando esgotou (a exceção sobe); `cancelled` em cancelamento/timeout. `StepHandle` = `warning(message, { image }?)`, `image(png)`, `data(key, value)` (`attachments` reservada). Aninha automaticamente na etapa corrente. | Ponto de parada (lança `RunCanceled`) |
+| `flush` | `(timeoutMs = 15_000) => Promise<void>` — envia já as etapas raiz finalizadas (transactions parciais, op `hobots.run.flush`) e os itens/logs/progresso pendentes | Nunca lança |
 | `signal` | `AbortSignal` | Cancelamento (app, timeout, shutdown) |
 | `throwIfCanceled()` | `() => void` | Lança `RunCanceled` se o signal disparou |
 | `sleep(ms)` | `(ms: number) => Promise<void>` | Rejeita com `RunCanceled` no cancelamento |
@@ -51,7 +52,7 @@ Só há uma chamada por processo, então todas as opções são **do agente**. O
 
 | Opção | Tipo | Default | Descrição |
 | --- | --- | --- | --- |
-| `clientSecret` | `string` | env `HOBOTS_CLIENT_SECRET` | `hb_<64 hex>`; ausente/inválido lança citando a env (sem ecoar o valor) |
+| `clientSecret` | `string` | env `HOBOTS_CLIENT_SECRET` | `hb_<64 hex>`; ausente/inválido lança citando a env (sem ecoar o valor). Ignorado com `HOBOTS_LOCAL_RUN=1` ([modo local](./runs.md#modo-local-teste-sem-a-central)) |
 | `instanceId` | `string` | env `HOBOTS_INSTANCE_ID` → `os.hostname()` | identidade estável da instância |
 | `environment` | `'development' \| 'testing' \| 'staging' \| 'production' \| string` | `'production'` | vai em eventos, transactions e na instância; filtra alertas |
 | `release` | `string` | — | versão do programa |
@@ -79,7 +80,20 @@ Só há uma chamada por processo, então todas as opções são **do agente**. O
 | --- | --- | --- | --- |
 | `concurrency` | `number` | `1` | execuções simultâneas do agente (1..5) |
 | `pollIntervalMs` | `number` | `2_000` (mín. 1_000) | intervalo entre polls sem trabalho |
-| `runId` | `string` | env `HOBOTS_RUN_ID` | avançado: executa só esta run (já reivindicada para a instância, ex.: pelo Studio) em vez de fazer poll — `POST /v1/runs/{id}/start`, handler uma vez e `close()`; 404/409 encerram sem rodar o handler |
+| `runId` | `string` | env `HOBOTS_RUN_ID` | avançado: executa só esta run (já reivindicada para a instância, ex.: pelo Studio) em vez de fazer poll — `POST /v1/runs/{id}/start`, handler uma vez e `close()`; 404/409 encerram sem rodar o handler. Ignorado no modo local |
+
+### Envs sem opção equivalente
+
+| Env | Efeito |
+| --- | --- |
+| `HOBOTS_API_URL` | só em desenvolvimento: outro host da API |
+| `HOBOTS_LOCAL_RUN` | `1` = modo local (teste sem a Central): handler uma vez, sem rede, exit code pelo desfecho — ver [Execuções](./runs.md#modo-local-teste-sem-a-central) |
+| `HOBOTS_RUN_PARAMS` | modo local: objeto JSON dos params (ausente = `{}`); inválido → stderr + exit 2 |
+| `HOBOTS_LOCAL_FILES_DIR` | pasta dos arquivos `storage: 'local'` deixados pelo Studio (`<dir>/<uuid>/<nome>`) |
+
+### CLI
+
+`npx hobots run <entry.js> [--params <arquivo.json>] [--param <chave>=<valor>]... [--file <campo>=<caminho>]... [--reset-ledger] [-- <args do bot>]` — roda o bot no modo local com o mesmo Node; exit code do bot (2 em uso errado). Detalhes em [Execuções → Modo local](./runs.md#a-cli-hobots-run).
 
 `StartOptions = RunOptions`.
 

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: 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**.
+Esta página explica **o que cada coisa é** — o vocabulário que as outras páginas usam: agente, execução, item, evento, issue, etapa, 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).
 
@@ -15,11 +15,11 @@ Defaults numéricos vivem em [Tempos e intervalos](./api-reference.md#tempos-e-i
 | [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 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 |
+| [Anexo](#anexo) | Um print pendurado num log, item ou etapa | "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/step/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 |
-| [Transaction](#transaction) e [Step](#step) | Quanto demorou e onde o tempo foi | `hobots.transaction.start` |
+| [Etapa](#etapa) (e a [transaction](#transaction) por trás) | Quanto demorou e onde o tempo foi — com nova tentativa | `hobots.step` |
 | [Heartbeat](#heartbeat) | Batimento "estou vivo", sempre ligado | Saber que o robô está de pé |
 | [instanceId](#instanceid) | A identidade da instância do robô | Env `HOBOTS_INSTANCE_ID` |
 | [Release e environment](#release-e-environment) | Qual versão, em qual ambiente | Separar produção de homologação |
@@ -35,7 +35,7 @@ Defaults numéricos vivem em [Tempos e intervalos](./api-reference.md#tempos-e-i
 | **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 |
+| **Etapas** — `hobots.step` | Aba de performance da execução (waterfall) |
 
 ---
 
@@ -75,11 +75,11 @@ O **log da execução** narra o que aconteceu, em linhas com nível (`debug`, `i
 
 ## Anexo
 
-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…".
+Um **anexo** é uma imagem — na prática, um print — vinculada ao evento que ela ilustra: uma linha de log, um item ou uma etapa. 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
 
-Cancelar no app **não mata** o handler — o SDK não tem como interromper código arbitrário com segurança (um navegador aberto, uma transação pela metade). O que ele faz: detecta o cancelamento (o PATCH periódico recebe 409), dispara `hobots.signal` e faz o próximo **ponto de parada** lançar `RunCanceled`. Os pontos de parada são as fronteiras naturais de trabalho: registrar um item, avançar o progresso, abrir uma step, dormir, tentar de novo. Por isso, num loop comum, o cancelamento funciona sem nenhuma linha extra. `hobots.log` nunca é ponto de parada. Se o handler ignorar o signal por tempo demais (`cancelGraceMs`), o SDK libera o slot e o handler vira um zumbi cujos reportes são descartados.
+Cancelar no app **não mata** o handler — o SDK não tem como interromper código arbitrário com segurança (um navegador aberto, uma transação pela metade). O que ele faz: detecta o cancelamento (o PATCH periódico recebe 409), dispara `hobots.signal` e faz o próximo **ponto de parada** lançar `RunCanceled`. Os pontos de parada são as fronteiras naturais de trabalho: registrar um item, avançar o progresso, abrir uma etapa, dormir, tentar de novo. Por isso, num loop comum, o cancelamento funciona sem nenhuma linha extra. `hobots.log` nunca é ponto de parada. Se o handler ignorar o signal por tempo demais (`cancelGraceMs`), o SDK libera o slot e o handler vira um zumbi cujos reportes são descartados.
 
 ## Retry
 
@@ -89,13 +89,13 @@ Uma falha do handler costuma ser passageira (portal instável, rede). O SDK **te
 
 Um **evento** é a foto de um erro: tipo, mensagem, stack trace, tags, ambiente, release e como estava a máquina. `hobots.captureException(erro)` cria um; erros não tratados (`uncaughtException`, `unhandledRejection`) também. Eventos parecidos são agrupados em uma **issue** pelo servidor (por stack trace, ou pelo `fingerprint` que você definir). O `type` diz o que ele é: `fatal`, `error` e `warning` abrem issue e podem alertar; `success` é registrado e nunca alerta. Log não é evento — narração fica no log da execução.
 
-## Transaction
+## Etapa
 
-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.
+Uma **etapa** é um trecho medido da execução com nome de negócio — "Entrar no portal", "Buscar pedido 123". A execução diz que levou 4 minutos; as etapas dizem que 3min40 foram esperando o portal. `hobots.step(nome, fn)` é a única chamada: o SDK abre a etapa, roda `fn`, **tenta de novo** se ela lançar (1 tentativa extra por padrão; `retries: 0` desliga) e fecha. Uma etapa só na Central cobre todas as tentativas: `warning` com o motivo quando a nova tentativa deu certo (e `attempts`), `error` quando esgotou (a exceção sobe), `cancelled` em cancelamento/timeout. `hobots.step` dentro de outra etapa vira sub-etapa; dentro do handler de `items.each`, sub-etapa da etapa do item. A função recebe o handle `etapa` para o que o SDK não vê sozinho: `warning(motivo)`, `image(png)`, `data(chave, valor)`. No app isso vira o **waterfall** da execução. Abrir uma etapa é um ponto de parada cooperativo. A etapa não entra no aviso de erro no topo do trabalho — ela aparece na aba de performance.
 
-## Step
+## Transaction
 
-Uma **step** é uma etapa medida dentro da transaction. A transaction diz que a execução levou 4 minutos; as steps dizem que 3min40 foram esperando o portal. `hobots.transaction.start(op, descrição)` abre uma; `step.start` aninha; `setData` anexa números; `succeeded()` fecha e `failed(erro)` marca erro e fecha — ou, sem guardar a step, `hobots.transaction.succeeded(op?)`/`failed(erro, op?)` fecham a aberta mais recente (com aquele `op`) (steps abertas são fechadas com a transaction). Status `ok`, `warning` (passou com ressalva) ou `error`. No app isso vira o **waterfall** da execução. Abrir uma step é um ponto de parada cooperativo.
+Uma **transaction** é o envelope do wire que carrega as etapas: cada execução tem exatamente uma, chamada `run` (op `hobots.run`), aberta e finalizada pelo SDK e correlacionada à execução pelo `run_id`. Você não a vê nem cria — só registra etapas com `hobots.step`. Num agente sempre ligado, `hobots.flush()` envia as etapas raiz já terminadas como transactions parciais (op `hobots.run.flush`).
 
 ## Heartbeat
 

package/docs/getting-started.md

@@ -76,4 +76,4 @@ O robô abre a própria execução ao iniciar e ela aparece em **Trabalhos** com
 
 `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: [Execuções](./runs.md) para itens, progresso, anexos, cancelamento e retry; [Referência de API](./api-reference.md) para todas as opções.
+A seguir: [Execuções](./runs.md) para etapas, itens, progresso, anexos, cancelamento e retry; [Referência de API](./api-reference.md) para todas as opções.

package/docs/protocol.md

@@ -38,7 +38,7 @@ Endpoint fixo `POST /v1/ingest` recebe **envelopes** JSON autenticados por Beare
 
 Tipos de item: `event`, `transaction`, `heartbeat` (definidos em `hobots/protocol`).
 
-Todo `transaction` carrega `run_id`: é assim que a [transaction da execução](./concepts.md#transaction) (`hobots.transaction`) é correlacionada, e o que permite o app montar o waterfall de performance dentro da solicitação.
+Todo `transaction` carrega `run_id`: é assim que a [transaction da execução](./concepts.md#transaction) (aberta pelo SDK; as etapas vêm de `hobots.step`) é correlacionada, e o que permite o app montar o waterfall de performance dentro da solicitação. Cada etapa (`StepData`) vai sem `op`, com `description` = nome (recortado em 2048 no cliente) e, quando houve mais de uma tentativa, `data.attempts`.
 
 `items` aceita de 1 a **50** itens por envelope — acima disso a API responde `422`. O `maxBatchSize` é só o gatilho do flush: quando a fila tem mais que esse teto (burst de captures, ou fila acumulada durante uma janela de rede ruim), o transport a fatia em lotes de 50 e faz um POST por lote.
 
@@ -165,7 +165,7 @@ Corpo `RunItemsCreateRequest`:
 
 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.
+- `attachments` é **opcional** e aditivo (uma API anterior ao recurso descarta o campo). As etapas 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.
@@ -187,11 +187,11 @@ Corpo `RunAttachmentCreateRequest`:
 
 ```jsonc
 {
-  "id": "<32 hex>",              // gerado pelo agente, já referenciado no log/item/step
+  "id": "<32 hex>",              // gerado pelo agente, já referenciado no log/item/etapa
   "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 do evento (log/item/step)
+  "log_ts": "…",                 // opcional, ISO 8601 — ts do evento (log/item/etapa)
   "width": 1920, "height": 1080  // opcionais
 }
 ```
@@ -226,7 +226,7 @@ Confirma o upload. Corpo `RunAttachmentConfirmRequest`: `{ "status": "uploaded"
 
 É **conforto de UX**, não correção: enquanto não confirmado, o app mostra a miniatura como "enviando imagem…". O agente engole falhas desta chamada.
 
-Limites de anexo (aplicados no SDK **e** no servidor): PNG/JPEG/WEBP, 5 MB por imagem, 20 por execução, 4 por evento (linha de log, item ou step).
+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 etapa).
 
 ### `POST /v1/runs/{id}/files/{fileId}/download`
 

package/docs/runs.md

@@ -29,9 +29,11 @@ Dentro do handler — e em **qualquer módulo** chamado por ele — o objeto glo
 ```js
 // notas.js — não recebe ctx nenhum
 export async function baixar(nota) {
-  const step = hobots.transaction.start('http.client', `GET /notas/${nota}`);
-  const xml = await portal.baixar(nota);
-  step.setData('bytes', xml.length).succeeded();
+  const xml = await hobots.step(`GET /notas/${nota}`, async etapa => {
+    const xml = await portal.baixar(nota); // lançou? o SDK tenta de novo uma vez
+    etapa.data('bytes', xml.length);
+    return xml;
+  });
   hobots.items.succeeded({ numero_nota: nota }, { id: nota });
 }
 ```
@@ -43,7 +45,7 @@ Isso funciona com `concurrency > 1` porque cada execução roda no seu contexto
 | `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 (`run`), já correlacionada e finalizada pelo SDK. `start(op, descrição)` = uma step no waterfall. |
+| `hobots.step(nome, fn, opts?)` | Ver [Etapas](#etapas-hobotsstep) |
 | `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) |
@@ -52,6 +54,7 @@ Isso funciona com `concurrency > 1` porque cada execução roda no seu contexto
 
 - **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.
+- Para rodar o handler na sua máquina sem a Central, ver [Modo local](#modo-local-teste-sem-a-central).
 
 > **Dados sensíveis:** logs, itens, erros e prints são enviados ao servidor e ficam visíveis no app.
 
@@ -79,7 +82,7 @@ O contrato da plataforma — **todo item previsto termina com um desfecho regist
 const resultado = await hobots.items.each(
   contas,
   async (conta, item) => {
-    await login(conta);                       // lançou → item `failed` com a mensagem, step em erro, segue
+    await login(conta);                       // lançou → item `failed` com a mensagem, etapa em erro, segue
     const fatura = await baixar(conta);
     if (!fatura) return item.occurrence('sem fatura no mês');   // ocorrência de negócio
     item.succeeded({ fatura: fatura.numero, valor: fatura.valor }); // mescla com o payload base
@@ -90,8 +93,8 @@ const resultado = await hobots.items.each(
 // resultado = { total, succeeded, failed, occurrence }
 ```
 
-- Cada elemento vira uma **step** no waterfall (`op` 'item', descrição = `id`; `item.step.start(...)` mede sub-etapas) e um **item** com o `id` e o payload base.
-- **Exceção no handler** = item `failed` com a mensagem do erro, `step.failed(erro)`, linha de erro no log da run — e o loop **segue para o próximo**. Nada do que o handler já registrou (`item.failed/occurrence`) é sobrescrito.
+- Cada elemento vira uma **etapa** no waterfall (`op` 'item', descrição = `id`; `hobots.step(...)` dentro do handler vira sub-etapa dela, e `item.step` é o handle `warning`/`image`/`data`) e um **item** com o `id` e o payload base.
+- **Exceção no handler** = item `failed` com a mensagem do erro, etapa em `error`, linha de erro no log da run — e o loop **segue para o próximo**. Nada do que o handler já registrou (`item.failed/occurrence`) é sobrescrito. O `each` não repete o item: para tentar de novo um trecho, use `hobots.step` dentro do handler.
 - **Progresso automático**: declara o total pelo tamanho da lista (se o bot ainda não declarou um) e avança a cada elemento, inclusive nos que falharam. `progress: false` deixa o progresso por conta do bot.
 - 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).
@@ -112,11 +115,41 @@ hobots.register(handler, {
 - 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.
 
+## Etapas (`hobots.step`)
+
+Uma **etapa** é um trecho da execução com nome de negócio, medido no waterfall da aba de performance. Uma chamada só: o SDK abre a etapa, roda a função, **tenta de novo** se ela lançar e fecha.
+
+```js
+// retries = 1 e retryDelayMs = 5_000 por padrão
+const pedido = await hobots.step('Buscar pedido', () => portal.buscar(numero));
+
+// etapa não idempotente (enviar, pagar, emitir): sem repetir
+await hobots.step(`Emitir nota ${numero}`, () => portal.emitir(numero), { retries: 0 });
+
+// mais tentativas, espera própria (número ou função da tentativa, 1-based)
+await hobots.step('Entrar no portal', login, { retries: 3, retryDelayMs: attempt => attempt * 2_000 });
+
+// a função recebe o handle `etapa` para o que o SDK não vê sozinho
+await hobots.step('Conferir anexos', async etapa => {
+  const anexos = await portal.anexos(numero);
+  etapa.data('total', anexos.length);
+  if (anexos.length === 0) etapa.warning('pedido sem anexos', { image: await page.screenshot() });
+});
+```
+
+- **Uma etapa só na Central**, cobrindo todas as tentativas: `data.attempts` quando houve mais de uma; status `warning` com o motivo (`data.message = "tentativa 1/2 falhou: Tipo: mensagem"`) quando a nova tentativa deu certo — a menos que a função já tenha marcado `warning`; `error` com `data.error = { type, message }` quando esgotou (a exceção original sobe); `cancelled` em cancelamento, timeout ou shutdown (nunca repetem).
+- Cada tentativa falhada vai para o **log da run**: `etapa "Buscar pedido": tentativa 1/2 falhou: Error: portal caiu — nova tentativa em 5000ms`. A espera é cancelável: uma execução cancelada no app não espera a próxima tentativa.
+- **Aninhamento automático**: `hobots.step` dentro da função vira sub-etapa da etapa corrente — inclusive dentro do handler de `items.each`, onde aninha na etapa do item.
+- O handle `etapa` (`StepHandle`): `warning(motivo, { image }?)` (uma etapa com erro não volta para aviso), `image(png)` (até 4 por etapa; vai em `data.attachments`), `data(chave, valor)` (`attachments` é reservada). Nada de abrir, fechar ou mudar status — isso é do SDK.
+- Abrir a etapa é um **ponto de parada** (`RunCanceled` se a execução foi cancelada). O nome é recortado em 2048 caracteres no cliente.
+- Fora de uma execução (aviso único), `hobots.step` roda a função com o mesmo retry, sem registrar nada. No [modo local](#modo-local-teste-sem-a-central) a etapa fica só na memória e o FINISH ecoa no terminal: `[hobots:step] FINISH Buscar pedido (812ms): tentativa 1/2 falhou: …`.
+- `hobots.retry(fn)` continua existindo para repetir **sem etapa**; `retries` de `register()`/`start()` repete o **trabalho inteiro**.
+
 ## Entregar enquanto processa (`hobots.flush()`)
 
 A transaction da execução só é enviada quando a run termina — num agente sempre ligado (`start()`) isso é nunca. `hobots.flush()` deixa o **bot** decidir quando entregar o que já fez:
 
-- cada step **raiz** já finalizada (com todas as filhas; as filhas ainda abertas são fechadas) vai numa transaction parcial da mesma run (`op` `hobots.run.flush`, `event_id` novo, até 200 steps cada) e sai da memória do SDK; steps raiz ainda abertas ficam para o próximo flush;
+- cada etapa **raiz** já finalizada (com todas as sub-etapas; as ainda abertas são fechadas) vai numa transaction parcial da mesma run (`op` `hobots.run.flush`, `event_id` novo, até 200 etapas cada) e sai da memória do SDK; etapas raiz ainda abertas ficam para o próximo flush;
 - itens, logs e progresso pendentes saem já, sem esperar o throttle;
 - aguarda a entrega com teto (`timeoutMs`, default 15 s) e **nunca lança** — pode ir num `finally`.
 
@@ -125,11 +158,11 @@ hobots.start(async () => {
   while (true) {
     const lote = await fila.pegar();
     if (lote.length) {
-      const rodada = hobots.transaction.start('rodada', `${lote.length} pedido(s)`);
       try {
-        for (const pedido of lote) await processar(pedido, rodada); // steps filhas + hobots.items.*
+        await hobots.step(`rodada: ${lote.length} pedido(s)`, async () => {
+          for (const pedido of lote) await processar(pedido); // sub-etapas (hobots.step) + hobots.items.*
+        }, { retries: 0 });
       } finally {
-        rodada.succeeded();
         await hobots.flush(); // waterfall e itens desta rodada já na Central
       }
     }
@@ -138,7 +171,7 @@ hobots.start(async () => {
 });
 ```
 
-Fila vazia → não abra step: cada step também vira duas linhas (START/FINISH) no log da execução, que guarda no máximo 1000.
+Fila vazia → não abra etapa: cada etapa também vira duas linhas (START/FINISH) no log da execução, que guarda no máximo 1000.
 
 ## Progresso (`hobots.progress`)
 
@@ -182,9 +215,54 @@ for (const ref of hobots.files.list()) hobots.log.info(ref.name, ref.size);
 
 `isFileRef(valor)` (export do pacote, também `hobots.isFileRef`) reconhece a forma de um `FileRef` — útil para percorrer params aninhados.
 
+## Modo local (teste sem a Central)
+
+Para testar o robô na sua máquina sem Client Secret, sem Central e sem rede, rode-o com a env **`HOBOTS_LOCAL_RUN=1`**. `register()` e `start()` se comportam igual neste modo: o handler roda **uma vez**, com `params = JSON.parse(HOBOTS_RUN_PARAMS || '{}')`, e o processo encerra. O código do bot não muda — `hobots.log`, `hobots.items`, `hobots.progress`, `hobots.files`, `items.each`, `hobots.step` (o FINISH de cada etapa ecoa como `[hobots:step] FINISH <nome> (123ms): <motivo>`), cancelamento e retry são os mesmos de produção; só o transporte é trocado por um que não fala com ninguém.
+
+```bash
+HOBOTS_LOCAL_RUN=1 HOBOTS_RUN_PARAMS='{"lote": 3}' node bot.js
+```
+
+- `HOBOTS_CLIENT_SECRET`, `HOBOTS_RUN_ID` e `HOBOTS_API_URL` são ignoradas. Nenhuma requisição sai: sem heartbeat, sem poll, sem issues (`hobots.captureException` devolve `undefined`).
+- `hobots.runId` é `'local'`; `HOBOTS_RUN_PARAMS` que não seja um objeto JSON válido imprime `[hobots] ERROR HOBOTS_RUN_PARAMS inválido: <motivo>` no stderr e encerra com código **2**.
+- **Exit code** pelo desfecho: **0** handler terminou; **1** lançou (depois dos retries configurados) — no stderr sai `[hobots] ERROR execução falhou — <Tipo>: <mensagem>` e a stack completa; **130** cancelado — `SIGINT`/`SIGTERM` disparam `hobots.signal` na execução em voo e esperam o handler parar por até 4 s (com `installExitHandlers: false`, ou com handler próprio do programa para o sinal, o SDK não intervém).
+
+O que sai no **stdout** (linhas estáveis, pensadas para quem lê a saída por script):
+
+| Linha | Quando |
+| --- | --- |
+| `[hobots] INFO modo local — execução sem a Central; params de HOBOTS_RUN_PARAMS` | primeira linha, ao entrar no modo |
+| `[hobots] INFO <mensagem>` (e `WARNING`/`ERROR` no stderr) | cada `hobots.log.*`, como sempre |
+| `[hobots:progress] <current>/<total>` | `hobots.progress` (também fora do modo local) |
+| `[hobots:item] <status>\t<id>\t<message>` | um item por linha, `status` = `succeeded` \| `occurrence` \| `failed`; tab e quebra de linha em id/mensagem viram espaço |
+| `[hobots:summary] total=<n> ok=<n> avisos=<n> falhas=<n> pulados=0` | no fim, contagem dos itens por status |
+| `[hobots] INFO execução local concluída (<succeeded\|failed\|canceled>) em <N>s` | última linha |
+
+Imagens e anexos (`hobots.image`, `{ image }` em itens e steps) são **descartados**, com um aviso único: `imagens e anexos não são enviados no modo local (descartados)`.
+
+**Arquivos.** `hobots.files` funciona com `storage: 'local'`; o formato `$HOBOTS_LOCAL_FILES_DIR/<id>/<nome>` continua valendo, e só no modo local o `FileRef` aceita a chave extra **`path`** (caminho absoluto ou relativo à pasta de trabalho): `download` copia de `path` **sem apagar a origem** (o teste roda quantas vezes quiser) e sem conferir `size`. `path` inexistente ou que não é arquivo regular: `arquivo "<nome>" não encontrado em <path>`. Um arquivo enviado pela Central (`storage: 's3'`) não existe aqui: `arquivo "<nome>" enviado pela Central não está disponível no modo local`. Fora do modo local a chave `path` é ignorada.
+
+### A CLI `hobots run`
+
+A CLI monta as envs e os params por você — e roda o entry com o **mesmo Node** (`process.execPath`), na mesma pasta de trabalho, herdando o terminal; o exit code do bot é o da CLI:
+
+```bash
+npx hobots run bot.js --params entrada.json --param lote=3 --param nome='"ACME"' --file planilha=./dados.xlsx -- --verbose
+```
+
+| Opção | Efeito |
+| --- | --- |
+| `--params <arquivo.json>` | objeto JSON base dos params |
+| `--param <chave>=<valor>` (repetível) | valor parseado como JSON quando for JSON válido (`3`, `true`, `"x"`, `[1]`), senão string crua; sobrescreve `--params` |
+| `--file <campo>=<caminho>` (repetível) | vira um `FileRef` `{ id: <uuid>, name, size, contentType, storage: 'local', path: <caminho absoluto> }`; o mesmo campo repetido vira uma lista; `contentType` pela extensão (`xlsx`, `xls`, `csv`, `ods`, `pdf`, `json`, `txt`, `xml`, `png`, `jpg`/`jpeg`, `zip`; demais `application/octet-stream`); caminho inexistente → `arquivo não encontrado: <caminho>`, exit 2 |
+| `--reset-ledger` | define `HOBOTS_LEDGER_RESET=1` no ambiente do bot (o ledger é do esqueleto do bot, não do SDK) |
+| `-- <args>` | tudo depois de `--` vai para o bot |
+
+`--help`/`-h` imprime a linha de uso no stdout (exit 0). Uso errado (sem entry, flag desconhecida, `--param` sem `=`): mensagem curta + linha de uso no stderr e exit **2**; entry inexistente → `arquivo não encontrado: <entry>`; `--params` com arquivo inexistente, JSON inválido ou que não é objeto → `--params: <motivo>` (exit 2). A CLI repassa `SIGINT`/`SIGTERM` ao bot e espera ele encerrar. O SDK Python tem a mesma CLI: `python -m hobots run bot.py …`.
+
 ## Imagens (screenshots)
 
-Um print vai **junto do evento** que ele ilustra — a linha de log, o item ou a step — para o
+Um print vai **junto do evento** que ele ilustra — a linha de log, o item ou a etapa — para o
 usuário ver o estado do robô no momento em que aquilo aconteceu (botão de imagem no app):
 
 ```js
@@ -199,16 +277,12 @@ 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.start('emitir', numero);
-try {
+// na etapa
+await hobots.step(`emitir ${numero}`, async etapa => {
   await emitir(numero);
-} catch (erro) {
-  step.failed(erro, undefined, { image: await page.screenshot() });
-  throw erro;
-} finally {
-  step.succeeded();
-}
+  etapa.image(await page.screenshot()); // print do estado da tela
+  if (await page.isVisible('.aviso')) etapa.warning('portal demorou a responder', { image: await page.screenshot() });
+}, { retries: 0 });
 
 // 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' }) });
@@ -220,7 +294,7 @@ O SDK não tira o print: aceita bytes (`Uint8Array`/`ArrayBuffer`/`Buffer`) ou u
 
 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.start()`, `hobots.sleep()` e cada tentativa de `hobots.retry()`.
+- `hobots.items.*`, `hobots.progress.total/advance/set`, `hobots.step()`, `hobots.sleep()` e cada tentativa de `hobots.retry()`.
 - **Nunca `hobots.log.*`** — log em `finally` de limpeza não pode explodir.
 
 ```js

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hobots",
-  "version": "4.5.0",
+  "version": "5.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,
@@ -12,6 +12,9 @@
     "dist",
     "docs"
   ],
+  "bin": {
+    "hobots": "./dist/cli.cjs"
+  },
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",