hobots 4.5.0 → 5.1.0

package/dist/protocol.cjs

@@ -40,6 +40,7 @@ var protocol_limits_default = {
   MAX_ITEM_PAYLOAD_BYTES: 16384,
   MAX_ITEM_COLUMNS: 12,
   MAX_ITEM_COLUMN_LABEL_CHARS: 60,
+  MAX_ITEMS_DONE_PER_PAGE: 1e3,
   MAX_ATTACHMENT_BYTES: 5242880,
   MAX_ATTACHMENTS_PER_RUN: 20,
   MAX_ATTACHMENTS_PER_LOG_ENTRY: 4,

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  RunItemsDoneRequest,\n  RunItemsDoneResponse,\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_ITEMS_DONE_PER_PAGE\": 1000,\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,yBAA2B;AAAA,EAC3B,sBAAwB;AAAA,EACxB,yBAA2B;AAAA,EAC3B,+BAAiC;AAAA,EACjC,mBAAqB;AAAA,EACrB,wBAA0B;AAC5B;;;ACbO,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;
@@ -240,6 +243,23 @@ interface RunItemsCreateResponse {
     /** Colapsados por id repetido dentro do mesmo lote (vale o de maior seq) */
     duplicates: number;
 }
+/**
+ * POST /v1/runs/{id}/items/done — ids dos itens já concluídos (`succeeded`/`occurrence`)
+ * no MESMO TRABALHO: a run raiz e todas as suas reexecuções pela Central/Studio. O
+ * `items.each` consulta uma vez, no início, para pular o que já deu certo (só `failed`
+ * roda de novo). Corpo vazio = primeira página.
+ */
+interface RunItemsDoneRequest {
+    /** `next` da página anterior (opaco) */
+    cursor?: string;
+    /** Tamanho da página — teto WIRE_LIMITS.MAX_ITEMS_DONE_PER_PAGE (o default do servidor) */
+    limit?: number;
+}
+interface RunItemsDoneResponse {
+    ids: string[];
+    /** Cursor da próxima página; null = acabou */
+    next: string | null;
+}
 /** Formatos aceitos para anexo. O S3 valida o content-type contra a assinatura. */
 type RunAttachmentContentType = 'image/png' | 'image/jpeg' | 'image/webp';
 /** POST /v1/runs/{id}/attachments */
@@ -327,6 +347,7 @@ var MAX_ITEM_MESSAGE_CHARS = 2000;
 var MAX_ITEM_PAYLOAD_BYTES = 16384;
 var MAX_ITEM_COLUMNS = 12;
 var MAX_ITEM_COLUMN_LABEL_CHARS = 60;
+var MAX_ITEMS_DONE_PER_PAGE = 1000;
 var MAX_ATTACHMENT_BYTES = 5242880;
 var MAX_ATTACHMENTS_PER_RUN = 20;
 var MAX_ATTACHMENTS_PER_LOG_ENTRY = 4;
@@ -347,6 +368,7 @@ var limits = {
 	MAX_ITEM_PAYLOAD_BYTES: MAX_ITEM_PAYLOAD_BYTES,
 	MAX_ITEM_COLUMNS: MAX_ITEM_COLUMNS,
 	MAX_ITEM_COLUMN_LABEL_CHARS: MAX_ITEM_COLUMN_LABEL_CHARS,
+	MAX_ITEMS_DONE_PER_PAGE: MAX_ITEMS_DONE_PER_PAGE,
 	MAX_ATTACHMENT_BYTES: MAX_ATTACHMENT_BYTES,
 	MAX_ATTACHMENTS_PER_RUN: MAX_ATTACHMENTS_PER_RUN,
 	MAX_ATTACHMENTS_PER_LOG_ENTRY: MAX_ATTACHMENTS_PER_LOG_ENTRY,
@@ -454,7 +476,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 {
@@ -490,4 +512,4 @@ interface Envelope {
     items: EnvelopeItem[];
 }
 
-export { type Breadcrumb, type BreadcrumbLevel, type Envelope, type EnvelopeItem, type Environment, type EnvironmentInput, type EventPayload, type EventType, type EventUser, type ExceptionData, type FileDownloadResponse, type FileRef, type FileStorage, type HeartbeatPayload, type InstanceInfo, type InstanceMode, type ItemColumn, type ItemsDeclaration, type MachineProcess, type MachineSnapshot, type PollRequest, type PollResponse, type RunAttachmentConfirmRequest, type RunAttachmentConfirmResponse, type RunAttachmentContentType, type RunAttachmentCreateRequest, type RunAttachmentCreateResponse, type RunCreateRequest, type RunCreateResponse, type RunDescriptor, type RunError, type RunItemInput, type RunItemStatus, type RunItemsCreateRequest, type RunItemsCreateResponse, type RunLogEntry, type RunLogLevel, type RunProgress, type RunStartRequest, type RunStartResponse, type RunStatus, type RunUpdateRequest, type RunUpdateResponse, type RunUpdateStatus, type StackFrame, type StepData, type StepStatus, type TransactionPayload, WIRE_LIMITS, type WireLimits };
+export { type Breadcrumb, type BreadcrumbLevel, type Envelope, type EnvelopeItem, type Environment, type EnvironmentInput, type EventPayload, type EventType, type EventUser, type ExceptionData, type FileDownloadResponse, type FileRef, type FileStorage, type HeartbeatPayload, type InstanceInfo, type InstanceMode, type ItemColumn, type ItemsDeclaration, type MachineProcess, type MachineSnapshot, type PollRequest, type PollResponse, type RunAttachmentConfirmRequest, type RunAttachmentConfirmResponse, type RunAttachmentContentType, type RunAttachmentCreateRequest, type RunAttachmentCreateResponse, type RunCreateRequest, type RunCreateResponse, type RunDescriptor, type RunError, type RunItemInput, type RunItemStatus, type RunItemsCreateRequest, type RunItemsCreateResponse, type RunItemsDoneRequest, type RunItemsDoneResponse, type RunLogEntry, type RunLogLevel, type RunProgress, type RunStartRequest, type RunStartResponse, type RunStatus, type RunUpdateRequest, type RunUpdateResponse, type RunUpdateStatus, type StackFrame, type StepData, type StepStatus, type TransactionPayload, WIRE_LIMITS, type WireLimits };

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;
@@ -240,6 +243,23 @@ interface RunItemsCreateResponse {
     /** Colapsados por id repetido dentro do mesmo lote (vale o de maior seq) */
     duplicates: number;
 }
+/**
+ * POST /v1/runs/{id}/items/done — ids dos itens já concluídos (`succeeded`/`occurrence`)
+ * no MESMO TRABALHO: a run raiz e todas as suas reexecuções pela Central/Studio. O
+ * `items.each` consulta uma vez, no início, para pular o que já deu certo (só `failed`
+ * roda de novo). Corpo vazio = primeira página.
+ */
+interface RunItemsDoneRequest {
+    /** `next` da página anterior (opaco) */
+    cursor?: string;
+    /** Tamanho da página — teto WIRE_LIMITS.MAX_ITEMS_DONE_PER_PAGE (o default do servidor) */
+    limit?: number;
+}
+interface RunItemsDoneResponse {
+    ids: string[];
+    /** Cursor da próxima página; null = acabou */
+    next: string | null;
+}
 /** Formatos aceitos para anexo. O S3 valida o content-type contra a assinatura. */
 type RunAttachmentContentType = 'image/png' | 'image/jpeg' | 'image/webp';
 /** POST /v1/runs/{id}/attachments */
@@ -327,6 +347,7 @@ var MAX_ITEM_MESSAGE_CHARS = 2000;
 var MAX_ITEM_PAYLOAD_BYTES = 16384;
 var MAX_ITEM_COLUMNS = 12;
 var MAX_ITEM_COLUMN_LABEL_CHARS = 60;
+var MAX_ITEMS_DONE_PER_PAGE = 1000;
 var MAX_ATTACHMENT_BYTES = 5242880;
 var MAX_ATTACHMENTS_PER_RUN = 20;
 var MAX_ATTACHMENTS_PER_LOG_ENTRY = 4;
@@ -347,6 +368,7 @@ var limits = {
 	MAX_ITEM_PAYLOAD_BYTES: MAX_ITEM_PAYLOAD_BYTES,
 	MAX_ITEM_COLUMNS: MAX_ITEM_COLUMNS,
 	MAX_ITEM_COLUMN_LABEL_CHARS: MAX_ITEM_COLUMN_LABEL_CHARS,
+	MAX_ITEMS_DONE_PER_PAGE: MAX_ITEMS_DONE_PER_PAGE,
 	MAX_ATTACHMENT_BYTES: MAX_ATTACHMENT_BYTES,
 	MAX_ATTACHMENTS_PER_RUN: MAX_ATTACHMENTS_PER_RUN,
 	MAX_ATTACHMENTS_PER_LOG_ENTRY: MAX_ATTACHMENTS_PER_LOG_ENTRY,
@@ -454,7 +476,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 {
@@ -490,4 +512,4 @@ interface Envelope {
     items: EnvelopeItem[];
 }
 
-export { type Breadcrumb, type BreadcrumbLevel, type Envelope, type EnvelopeItem, type Environment, type EnvironmentInput, type EventPayload, type EventType, type EventUser, type ExceptionData, type FileDownloadResponse, type FileRef, type FileStorage, type HeartbeatPayload, type InstanceInfo, type InstanceMode, type ItemColumn, type ItemsDeclaration, type MachineProcess, type MachineSnapshot, type PollRequest, type PollResponse, type RunAttachmentConfirmRequest, type RunAttachmentConfirmResponse, type RunAttachmentContentType, type RunAttachmentCreateRequest, type RunAttachmentCreateResponse, type RunCreateRequest, type RunCreateResponse, type RunDescriptor, type RunError, type RunItemInput, type RunItemStatus, type RunItemsCreateRequest, type RunItemsCreateResponse, type RunLogEntry, type RunLogLevel, type RunProgress, type RunStartRequest, type RunStartResponse, type RunStatus, type RunUpdateRequest, type RunUpdateResponse, type RunUpdateStatus, type StackFrame, type StepData, type StepStatus, type TransactionPayload, WIRE_LIMITS, type WireLimits };
+export { type Breadcrumb, type BreadcrumbLevel, type Envelope, type EnvelopeItem, type Environment, type EnvironmentInput, type EventPayload, type EventType, type EventUser, type ExceptionData, type FileDownloadResponse, type FileRef, type FileStorage, type HeartbeatPayload, type InstanceInfo, type InstanceMode, type ItemColumn, type ItemsDeclaration, type MachineProcess, type MachineSnapshot, type PollRequest, type PollResponse, type RunAttachmentConfirmRequest, type RunAttachmentConfirmResponse, type RunAttachmentContentType, type RunAttachmentCreateRequest, type RunAttachmentCreateResponse, type RunCreateRequest, type RunCreateResponse, type RunDescriptor, type RunError, type RunItemInput, type RunItemStatus, type RunItemsCreateRequest, type RunItemsCreateResponse, type RunItemsDoneRequest, type RunItemsDoneResponse, type RunLogEntry, type RunLogLevel, type RunProgress, type RunStartRequest, type RunStartResponse, type RunStatus, type RunUpdateRequest, type RunUpdateResponse, type RunUpdateStatus, type StackFrame, type StepData, type StepStatus, type TransactionPayload, WIRE_LIMITS, type WireLimits };

package/dist/protocol.js

@@ -1,6 +1,6 @@
 import {
   WIRE_LIMITS
-} from "./chunk-HKCDMUA3.js";
+} from "./chunk-6YTOYIZM.js";
 export {
   WIRE_LIMITS
 };

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`