hobots 4.2.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  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;
@@ -165,6 +168,17 @@ interface RunCreateRequest {
 }
 /** Resposta (201): o mesmo descritor do poll, com params {}, form null e source 'agent'. */
 type RunCreateResponse = RunDescriptor;
+/**
+ * POST /v1/runs/:id/start — a run foi criada já reivindicada para esta instância
+ * (o Studio sobe o bot com HOBOTS_RUN_ID) e o processo se anexa a ela em vez de
+ * fazer poll. 409 = cancelada, já iniciada ou de outra instância; 404 = não existe.
+ */
+interface RunStartRequest {
+    /** presença da instância — a mesma do poll */
+    instance: InstanceInfo;
+}
+/** Resposta (200): o mesmo descritor do poll. */
+type RunStartResponse = RunDescriptor;
 interface RunError {
     /** ex.: nome da classe do erro */
     type?: string;
@@ -443,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 {
@@ -479,4 +493,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 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 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;
@@ -165,6 +168,17 @@ interface RunCreateRequest {
 }
 /** Resposta (201): o mesmo descritor do poll, com params {}, form null e source 'agent'. */
 type RunCreateResponse = RunDescriptor;
+/**
+ * POST /v1/runs/:id/start — a run foi criada já reivindicada para esta instância
+ * (o Studio sobe o bot com HOBOTS_RUN_ID) e o processo se anexa a ela em vez de
+ * fazer poll. 409 = cancelada, já iniciada ou de outra instância; 404 = não existe.
+ */
+interface RunStartRequest {
+    /** presença da instância — a mesma do poll */
+    instance: InstanceInfo;
+}
+/** Resposta (200): o mesmo descritor do poll. */
+type RunStartResponse = RunDescriptor;
 interface RunError {
     /** ex.: nome da classe do erro */
     type?: string;
@@ -443,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 {
@@ -479,4 +493,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 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 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/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

@@ -4,7 +4,7 @@
 
 | Import | Conteúdo |
 | --- | --- |
-| `hobots` | `hobots` (default e named), `register`, `start`, `close`, `captureException`, `retry`, `image` e os tipos. |
+| `hobots` | `hobots` (default e named), `register`, `start`, `close`, `captureException`, `retry`, `image`, `isFileRef` e os tipos. |
 | `hobots/protocol` | Tipos do wire format (telemetria e execuções). |
 
 ESM e CommonJS (`const { hobots } = require('hobots')`), com `.d.ts`. Depois do `register()`/`start()`, `globalThis.hobots` também existe (tipado via `declare global`).
@@ -18,7 +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.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)
@@ -28,17 +30,17 @@ 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`) — `startChild(op?, description?)`, `flush()`, `setTag`, `setStatus`, `setName`; `Step` — `startChild`, `setStatus('ok' \| 'warning' \| 'error', message?, { image }?)`, `setError(err, message?, { image }?)` (motivo em `data.error`, print em `data.attachments`, exibidos na Central), `setData(k, v)`, `finish()` | Finalizada pelo SDK; `startChild` é 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 |
 | `retry(fn, options?)` | como `hobots.retry` | |
 
-`AttachInput = Uint8Array \| ArrayBuffer \| string` (caminho); `ImageOptions = { caption?, contentType? }`; `ImageInput = AttachInput \| ImageAttachment` é o que `log.*` (só o embrulho), `items.*` e `step.setStatus/setError` aceitam. O upload (segundo plano, nunca bloqueia) acontece quando o evento é registrado.
+`AttachInput = Uint8Array \| ArrayBuffer \| string` (caminho); `ImageOptions = { caption?, contentType? }`; `ImageInput = AttachInput \| ImageAttachment` é o que `log.*` (só o embrulho), `items.*` e `step.setStatus/failed` aceitam. O upload (segundo plano, nunca bloqueia) acontece quando o evento é registrado.
 
 Fora de uma execução, `hobots.*` cai em fallbacks seguros com aviso único por membro (log ecoa no terminal, imagem descartada; items/progress no-op; `signal` nunca aborta).
 
@@ -50,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 |
@@ -78,6 +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. 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`.
 
@@ -119,9 +135,9 @@ type RunHandler<P = Record<string, unknown>> = (params: P, ctx: RunContext) => v
 | --- | --- |
 | Heartbeat | 30 s (±10 % de jitter), sempre ligado, timer ref'd (segura o processo) |
 | Flush da telemetria | 2 s ou 10 itens; envelopes de até 50 itens; fila de 200 |
-| Retry HTTP (ingest, PATCH, itens, anexos) | 1 s / 4 s / 16 s com jitter; 4xx ≠ 429 é definitivo |
+| Retry HTTP (ingest, PATCH, itens, anexos) | 1 s / 4 s / 16 s com jitter; 4xx ≠ 429 é definitivo; no registro de anexo, 429/501/503 (cota / anexos desabilitados) também são definitivos |
 | Poll sem trabalho | `pollIntervalMs` (2 s); com trabalho, imediato (drain) |
-| Poll/criação de run com erro | 1 s / 4 s / 16 s; 401 → 30 s com erro logado na 1ª e a cada 10 falhas |
+| Poll/criação de run com erro | 1 s / 4 s / 16 s; 401 (Client Secret rejeitado) e 402 (agente fora do limite do plano) → 30 s com erro logado na 1ª e a cada 10 falhas |
 | Logs da execução | flush a cada `logFlushIntervalMs` (2 s) ou 20 linhas; chunks de 100; 1000 por execução no servidor |
 | Cancel-watch / sinal de vida | `cancelCheckIntervalMs` (5 s); o servidor marca `AgentTerminated` após ~120 s sem PATCH |
 | Retry do handler | `retries` 1, `retryDelayMs` 5 s |

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.startChild` |
+| [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 |
@@ -31,11 +31,11 @@ Defaults numéricos vivem em [Tempos e intervalos](./api-reference.md#tempos-e-i
 
 | No SDK | No app |
 | --- | --- |
-| **Agente** — dono do Client Secret (`hb_…`) que autentica tudo; o que ele faz é o handler de `register()`/`start()` | **Configurações → Agentes** (o formulário do agente fica aqui) |
+| **Agente** — dono do Client Secret (`hb_…`) que autentica tudo; o que ele faz é o handler de `register()`/`start()` | No agente, **Configurações**: aba **agente → credenciais** (Client Secret) e **formulário** |
 | **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.startChild(op, descrição)` abre uma; `step.startChild` aninha; `setData` anexa números; `finish()` fecha (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

@@ -21,7 +21,7 @@ Sem dependências de runtime. Requer **Node 18+** (usa o `fetch` global).
 
 ## Credenciais
 
-Cada agente tem **um Client Secret** (`hb_<64 hex>`), copiado em **Configurações → Agentes**. O SDK lê do ambiente:
+Cada agente tem **um Client Secret** (`hb_<64 hex>`), copiado na Central em **agente → Configurações → agente → aba credenciais**. O SDK lê do ambiente:
 
 ```bash
 export HOBOTS_CLIENT_SECRET=hb_<64 hex>
@@ -30,9 +30,11 @@ export HOBOTS_INSTANCE_ID=vm-cliente-01   # opcional — sem ela, o hostname
 
 Também dá para passar `clientSecret`/`instanceId` nas opções de `register()`/`start()` (o snippet do app já vem assim). Em desenvolvimento, `HOBOTS_API_URL=http://localhost:3001` aponta para outra API; em produção é sempre `https://api2.hobots.app`.
 
+As envs também podem ficar num `.env` na pasta de onde o bot roda: o SDK carrega o arquivo sozinho no import (sem `dotenv`); a env já definida no ambiente vence o arquivo.
+
 ## Primeiro agente sob demanda (`register`)
 
-1. No app, abra o agente em **Configurações → Agentes** e monte o **formulário do agente** (os campos que cada solicitação vai carregar).
+1. No app, abra o agente em **Configurações → formulário** e monte o **formulário do agente** (os campos que cada solicitação vai carregar).
 2. No robô:
 
 ```js
@@ -74,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.
 
@@ -96,7 +96,7 @@ Resposta `PollResponse` = `{ runs: RunDescriptor[] }`, cada `{ id, params, form,
 
 O `instance.instance_id` é a **mesma identidade** do heartbeat de telemetria (`instance_id`): o servidor correlaciona os dois canais numa tabela `instances` por `(agent_id, instance_id)`. Os dois derivam do mesmo `instanceId` — o robô aparece como um agente só no painel. O próprio poll também marca a presença da instância (`last_poll_at`). Um processo no modo `start()` nunca faz poll.
 
-**Backoff:** um request por poll; o loop decide o ritmo. HTTP 401 (key rejeitada) → retry lento a 30s com log throttled; outros erros → ladder `[1s, 4s, 16s]`.
+**Backoff:** um request por poll; o loop decide o ritmo. HTTP 401 (key rejeitada) e 402 (agente fora do limite do plano) → retry lento a 30s com log throttled; outros erros → ladder `[1s, 4s, 16s]`.
 
 ### `POST /v1/runs`
 
@@ -106,6 +106,14 @@ Modo `start`: a instância abre a **própria run**. Corpo `RunCreateRequest` —
 - `touchInstance` roda antes do insert (presença); se falhar, a API responde `503` e o SDK insiste com o ladder do poll (o handler só começa quando a run existe). Corpo vazio ou sem `instance.instance_id` → `422`.
 - Sem dedupe: um processo reiniciado em menos de 120 s deixa a run anterior `running` até o sweep marcá-la `AgentTerminated`. O app não oferece "reexecutar" para runs `agent` — ninguém faria poll por elas.
 
+### `POST /v1/runs/{id}/start`
+
+`register()` com env `HOBOTS_RUN_ID` (ou a opção `runId`): a run já foi criada **reivindicada para esta instância** (o Studio executa o bot sob demanda sem que ele faça poll) e o processo se anexa a ela. Corpo `RunStartRequest` — `{ "instance": { /* InstanceInfo, o mesmo do poll */ } }`. Resposta `200` `RunStartResponse` = o mesmo `RunDescriptor` do poll.
+
+- `404` = a run não existe; `409` = cancelada, já iniciada ou de outra instância. Os dois (e qualquer outro 4xx ≠ 429) encerram o SDK **sem** rodar o handler, com o motivo no log.
+- Rede, timeout, `5xx` e `429`: até 4 tentativas (esperas de 1 s/4 s/16 s com jitter); esgotadas, o SDK desiste e encerra.
+- Dali em diante a run é reportada pelas rotas abaixo; terminada, o SDK faz `close()` e o processo sai.
+
 ### `PATCH /v1/runs/{id}`
 
 Corpo `RunUpdateRequest`:
@@ -135,7 +143,7 @@ Ciclo de vida completo da run no servidor (`RunStatus`): `pending → claimed
 
 ### `POST /v1/runs/{id}/items`
 
-Registra em lote os **itens de execução** (a entrega do bot — `hobots.items` no SDK). Insert-only: cada item chega com o status final; um `id` repetido na mesma run é ignorado (retry de rede idempotente).
+Registra em lote os **itens de execução** (a entrega do bot — `hobots.items` no SDK). Upsert por `(run, id)`: um `id` repetido na mesma run atualiza o item (vale o último reporte — o bot que tenta de novo corrige `failed` → `succeeded`); reenvio idêntico (retry de rede) não mexe nos contadores.
 
 Corpo `RunItemsCreateRequest`:
 
@@ -157,11 +165,11 @@ 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.
-- Retry `[1s, 4s, 16s]` para rede/5xx; `404` = servidor sem o recurso (o SDK degrada em silêncio); `402` = armazenamento do plano esgotado. Não há teto de itens por run.
+- Retry `[1s, 4s, 16s]` para rede/5xx; `404` = servidor sem o recurso (o SDK degrada em silêncio); `402` = armazenamento do plano esgotado (sem retry: o SDK descarta o lote com um aviso por episódio e segue enviando os próximos). Não há teto de itens por run.
 
 | Status | Quando |
 | --- | --- |
@@ -179,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
 }
 ```
@@ -218,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`