hobots 4.2.0 → 4.5.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 (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":[]}

package/dist/protocol.d.cts

@@ -165,6 +165,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;
@@ -479,4 +490,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

@@ -165,6 +165,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;
@@ -479,4 +490,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/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,6 +18,7 @@ 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. |
 | `isFileRef` / `hobots.isFileRef` | `(value: unknown) => value is FileRef` | Reconhece um arquivo de campo de upload nos params. Puro. |
 
@@ -32,13 +33,13 @@ ESM e CommonJS (`const { hobots } = require('hobots')`), com `.d.ts`. Depois do
 | `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 |
+| `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 |
 | `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).
 
@@ -78,6 +79,7 @@ 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 |
 
 `StartOptions = RunOptions`.
 
@@ -119,9 +121,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

@@ -19,7 +19,7 @@ Defaults numéricos vivem em [Tempos e intervalos](./api-reference.md#tempos-e-i
 | [Cancelamento cooperativo](#cancelamento-cooperativo) | O app pede, o handler para no próximo ponto de parada | Automático em items/progress/steps/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` |
+| [Transaction](#transaction) e [Step](#step) | Quanto demorou e onde o tempo foi | `hobots.transaction.start` |
 | [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,7 +31,7 @@ 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** |
@@ -95,7 +95,7 @@ Uma **transaction** é uma unidade de trabalho **medida**: começa, termina, e o
 
 ## Step
 
-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 **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.
 
 ## 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

package/docs/protocol.md

@@ -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`:
 
@@ -161,7 +169,7 @@ Resposta `200` `RunItemsCreateResponse`: `{ "accepted": 1, "duplicates": 0 }`
 
 - **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 |
 | --- | --- |

package/docs/runs.md

@@ -29,9 +29,9 @@ Dentro do handler — e em **qualquer módulo** chamado por ele — o objeto glo
 ```js
 // notas.js — não recebe ctx nenhum
 export async function baixar(nota) {
-  const step = hobots.transaction.startChild('http.client', `GET /notas/${nota}`);
+  const step = hobots.transaction.start('http.client', `GET /notas/${nota}`);
   const xml = await portal.baixar(nota);
-  step.setData('bytes', xml.length).finish();
+  step.setData('bytes', xml.length).succeeded();
   hobots.items.succeeded({ numero_nota: nota }, { id: nota });
 }
 ```
@@ -43,7 +43,7 @@ Isso funciona com `concurrency > 1` porque cada execução roda no seu contexto
 | `hobots.log.<debug\|info\|warn\|error\|success>(msg, ...rest)` | Enviado incrementalmente (PATCHes com throttle) e ecoado no terminal (`[hobots] INFO …`). Nunca lança. `hobots.image(...)` no último argumento = print da linha. |
 | `hobots.items` | Ver [Itens](#itens-de-execução-hobotsitems) |
 | `hobots.progress` | Ver [Progresso](#progresso-hobotsprogress) |
-| `hobots.transaction` | Transaction da execução (`run`), já correlacionada e finalizada pelo SDK. `startChild(op, descrição)` = uma step no waterfall. |
+| `hobots.transaction` | Transaction da execução (`run`), já correlacionada e finalizada pelo SDK. `start(op, descrição)` = uma step no waterfall. |
 | `hobots.image(imagem, opts?)` | Ver [Imagens](#imagens-screenshots) |
 | `hobots.captureException(erro, hint?)` | Issue no módulo Issues; `hint.attachment` anexa um print à linha de log |
 | `hobots.retry(fn, opts?)` | Ver [Retry](#retry) |
@@ -90,8 +90,8 @@ const resultado = await hobots.items.each(
 // resultado = { total, succeeded, failed, occurrence }
 ```
 
-- Cada elemento vira uma **step** no waterfall (`op` 'item', descrição = `id`; `item.step.startChild(...)` mede sub-etapas) e um **item** com o `id` e o payload base.
-- **Exceção no handler** = item `failed` com a mensagem do erro, `step.setError(erro)`, linha de erro no log da run — e o loop **segue para o próximo**. Nada do que o handler já registrou (`item.failed/occurrence`) é sobrescrito.
+- Cada elemento vira uma **step** no waterfall (`op` 'item', descrição = `id`; `item.step.start(...)` mede sub-etapas) e um **item** com o `id` e o payload base.
+- **Exceção no handler** = item `failed` com a mensagem do erro, `step.failed(erro)`, linha de erro no log da run — e o loop **segue para o próximo**. Nada do que o handler já registrou (`item.failed/occurrence`) é sobrescrito.
 - **Progresso automático**: declara o total pelo tamanho da lista (se o bot ainda não declarou um) e avança a cada elemento, inclusive nos que falharam. `progress: false` deixa o progresso por conta do bot.
 - Só **cancelamento, timeout e shutdown** interrompem o loop: o `RunCanceled` sobe, o item em curso não é registrado e o progresso não avança.
 - Aceita `Iterable` ou `AsyncIterable` (sem `length`, nenhum total é declarado).
@@ -125,11 +125,11 @@ hobots.start(async () => {
   while (true) {
     const lote = await fila.pegar();
     if (lote.length) {
-      const rodada = hobots.transaction.startChild('rodada', `${lote.length} pedido(s)`);
+      const rodada = hobots.transaction.start('rodada', `${lote.length} pedido(s)`);
       try {
         for (const pedido of lote) await processar(pedido, rodada); // steps filhas + hobots.items.*
       } finally {
-        rodada.finish();
+        rodada.succeeded();
         await hobots.flush(); // waterfall e itens desta rodada já na Central
       }
     }
@@ -200,14 +200,14 @@ await hobots.items.each(notas, async (nota, item) => {
 });
 
 // na step
-const step = hobots.transaction.startChild('emitir', numero);
+const step = hobots.transaction.start('emitir', numero);
 try {
   await emitir(numero);
 } catch (erro) {
-  step.setError(erro, undefined, { image: await page.screenshot() });
+  step.failed(erro, undefined, { image: await page.screenshot() });
   throw erro;
 } finally {
-  step.finish();
+  step.succeeded();
 }
 
 // numa issue (módulo Issues) — o print vai na linha de log que espelha o erro
@@ -220,7 +220,7 @@ O SDK não tira o print: aceita bytes (`Uint8Array`/`ArrayBuffer`/`Buffer`) ou u
 
 Cancelar o trabalho no app **não mata** o handler: o SDK detecta (o PATCH periódico recebe 409), dispara `hobots.signal` e o próximo **ponto de parada** lança `RunCanceled`:
 
-- `hobots.items.*`, `hobots.progress.total/advance/set`, `hobots.transaction.startChild()`, `hobots.sleep()` e cada tentativa de `hobots.retry()`.
+- `hobots.items.*`, `hobots.progress.total/advance/set`, `hobots.transaction.start()`, `hobots.sleep()` e cada tentativa de `hobots.retry()`.
 - **Nunca `hobots.log.*`** — log em `finally` de limpeza não pode explodir.
 
 ```js

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hobots",
-  "version": "4.2.0",
+  "version": "4.5.0",
   "description": "SDK JavaScript da Hobots — o agente é a própria tarefa: register() atende solicitações da plataforma (sob demanda), start() roda sempre ligado e reporta logs, itens e progresso. Credenciais por env, heartbeat sempre ligado, objeto global `hobots`.",
   "type": "module",
   "sideEffects": false,