hobots 4.2.0 → 4.5.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import { RunAttachmentContentType, EventType, EnvironmentInput, MachineSnapshot, EventPayload, TransactionPayload, HeartbeatPayload, StepStatus, RunLogLevel, StepData, FileRef, RunItemStatus, RunProgress } from './protocol.cjs';
-export { Breadcrumb, BreadcrumbLevel, Envelope, EnvelopeItem, Environment, EventUser, ExceptionData, FileDownloadResponse, FileStorage, InstanceInfo, InstanceMode, ItemColumn, ItemsDeclaration, MachineProcess, PollRequest, PollResponse, RunAttachmentConfirmRequest, RunAttachmentConfirmResponse, RunAttachmentCreateRequest, RunAttachmentCreateResponse, RunCreateRequest, RunCreateResponse, RunDescriptor, RunError, RunItemInput, RunItemsCreateRequest, RunItemsCreateResponse, RunLogEntry, RunStatus, RunUpdateRequest, RunUpdateResponse, RunUpdateStatus, StackFrame } from './protocol.cjs';
+export { Breadcrumb, BreadcrumbLevel, Envelope, EnvelopeItem, Environment, EventUser, ExceptionData, FileDownloadResponse, FileStorage, InstanceInfo, InstanceMode, ItemColumn, ItemsDeclaration, MachineProcess, PollRequest, PollResponse, RunAttachmentConfirmRequest, RunAttachmentConfirmResponse, RunAttachmentCreateRequest, RunAttachmentCreateResponse, RunCreateRequest, RunCreateResponse, RunDescriptor, RunError, RunItemInput, RunItemsCreateRequest, RunItemsCreateResponse, RunLogEntry, RunStartRequest, RunStartResponse, RunStatus, RunUpdateRequest, RunUpdateResponse, RunUpdateStatus, StackFrame } from './protocol.cjs';
 
 /** Espera entre tentativas: ms fixo ou função do número da tentativa que acabou de falhar (1-based). */
 type RetryDelay = number | ((attempt: number) => number);
@@ -24,7 +24,7 @@ declare const IMAGE_BRAND: unique symbol;
 /**
  * Uma imagem pronta para ser pendurada num evento da run — o retorno de `hobots.image()`.
  * É só um envelope (bytes/caminho + legenda); nenhum I/O acontece até o evento ser
- * registrado por `hobots.log.*`, `hobots.items.*` ou `step.setStatus/setError`.
+ * registrado por `hobots.log.*`, `hobots.items.*` ou `step.setStatus/failed`.
  */
 declare class ImageAttachment {
     readonly input: AttachInput;
@@ -49,11 +49,11 @@ type ItemColumnInput = string | {
 };
 
 /**
- * Opções do processo (telemetria, identidade, handlers globais). Valem as da PRIMEIRA
- * chamada a register()/start(); chamadas seguintes com valores diferentes avisam e são ignoradas.
+ * Opções do processo (telemetria, identidade, handlers globais). Só há uma chamada a
+ * register()/start() por processo — a segunda lança (`o agente já foi iniciado`).
  */
 interface HobotsOptions {
-    /** Client Secret do agente (hb_…). Default: env HOBOTS_CLIENT_SECRET. Copie em Configurações → Agentes. */
+    /** Client Secret do agente (hb_…). Default: env HOBOTS_CLIENT_SECRET. Copie na Central: agente → Configurações → agente → aba credenciais. */
     clientSecret?: string;
     /**
      * Identificador único e estável desta instância — a identidade do agente no painel
@@ -78,7 +78,10 @@ interface HobotsOptions {
      * instância no app) e como `contexts.machine` em cada evento. Só em Node. Default: true
      */
     machineMetrics?: boolean;
-    /** Registra handlers globais de erro (uncaughtException etc.) que abrem issues. Default: true */
+    /**
+     * Erro não tratado vira issue: o que escapa do handler de uma execução (além de falhar a
+     * run; cancelamento fica de fora) e o que escapa fora dele (uncaughtException etc.). Default: true
+     */
     captureUnhandled?: boolean;
     /**
      * Avançado. Instala handlers de SIGINT/SIGTERM/uncaughtException que reportam as runs
@@ -134,6 +137,14 @@ interface RegisterOptions extends RunOptions {
     concurrency?: number;
     /** Intervalo entre polls sem trabalho (mínimo 1_000). Default: 2_000 */
     pollIntervalMs?: number;
+    /**
+     * Avançado. Executa só esta run (já reivindicada para a instância, ex.: pelo Studio) em
+     * vez de fazer poll: anexa-se a ela (`POST /v1/runs/:id/start`), roda o handler uma vez e
+     * encerra o SDK (`close()`), liberando o processo. 404/409 (run inexistente, cancelada, já
+     * iniciada ou de outra instância) encerram sem rodar o handler. Default: env HOBOTS_RUN_ID;
+     * sem ela, poll normal.
+     */
+    runId?: string;
 }
 /** Opções de `start()` — agente sempre ligado, que abre a própria run. */
 type StartOptions = RunOptions;
@@ -209,6 +220,11 @@ interface ClientOptions {
     /** Tags aplicadas a todos os eventos e transactions */
     tags?: Record<string, string>;
     debug?: boolean;
+    /**
+     * O erro final que escapou do handler de uma run também vira issue (além de falhar a run).
+     * Ligado pelo runtime junto com `captureUnhandled`; desligado no client cru (testes).
+     */
+    captureRunErrors?: boolean;
     /** Knobs internos do transport (testes) — não fazem parte da API pública */
     flushIntervalMs?: number;
     maxBatchSize?: number;
@@ -272,23 +288,29 @@ declare class Step {
      */
     setStatus(status: StepStatus, message?: string, options?: StepOutcomeOptions): this;
     /**
-     * Marca a step como `error` guardando o motivo em `data.error` ({ type, message }).
-     * Aceita qualquer valor lançado; `message` sobrescreve a mensagem do erro.
+     * Marca a step como `error` guardando o motivo em `data.error` ({ type, message }) e a
+     * fecha. Aceita qualquer valor lançado; `message` sobrescreve a mensagem do erro.
      * `options.image` pendura um print do estado da tela em `data.attachments`.
+     * Numa step já fechada não faz nada.
      */
-    setError(error: unknown, message?: string, options?: StepOutcomeOptions): this;
+    failed(error: unknown, message?: string, options?: StepOutcomeOptions): this;
     /**
      * Dispara o upload pela run (sink do RunReporter) e referencia o anexo em
      * `data.attachments` (chave reservada; teto igual ao das linhas de log). Fora de uma
      * run não há onde pendurar a imagem — descarta com aviso único.
      */
     private attachImage;
-    /** Motivo registrado via setStatus(…, message) ou setError — usado no log de FINISH. */
+    /** Motivo registrado via setStatus(…, message) ou failed — usado no log de FINISH. */
     private reason;
     setData(key: string, value: unknown): this;
     /** Step aninhada (filha desta step). */
-    startChild(op?: string, description?: string): Step;
-    finish(): void;
+    start(op?: string, description?: string): Step;
+    /**
+     * Fecha a step. O status fica o que estiver (`ok` por padrão, ou o de `setStatus`).
+     * Idempotente; a transaction fecha no fim da run o que ficou aberto.
+     */
+    succeeded(): this;
+    private close;
     toJSON(): StepData;
 }
 /**
@@ -331,12 +353,26 @@ declare class Transaction {
     attachImage(image: ImageInput): string | undefined;
     /**
      * Conecta a checagem de cancelamento chamada antes de cada step nova — é assim que
-     * `hobots.transaction.startChild()` (e `step.startChild()`) param uma run cancelada.
+     * `hobots.transaction.start()` (e `step.start()`) param uma run cancelada.
      */
     setStepGuard(guard: () => void): void;
     createStep(parentStepId: string, op?: string, description?: string): Step;
-    /** Step direta da transaction. */
-    startChild(op?: string, description?: string): Step;
+    /** Step direta da transaction. `op` é o nome usado por `succeeded(name)`/`failed(error, name)`. */
+    start(op?: string, description?: string): Step;
+    /**
+     * Fecha a step aberta mais recente — com `name`, a mais recente aberta com esse `op`.
+     * Sem step aberta (ou sem nenhuma com esse nome), não faz nada e devolve undefined.
+     */
+    succeeded(name?: string): Step | undefined;
+    /**
+     * Marca como `error` e fecha a step aberta mais recente — com `name`, a mais recente
+     * aberta com esse `op`. `options.message` sobrescreve a mensagem do erro e
+     * `options.image` pendura um print. Sem step aberta, não faz nada e devolve undefined.
+     */
+    failed(error: unknown, name?: string, options?: StepOutcomeOptions & {
+        message?: string;
+    }): Step | undefined;
+    private findOpenStep;
     setTag(key: string, value: string): this;
     setStatus(status: string): this;
     setName(name: string): this;
@@ -421,7 +457,7 @@ interface RunItemOptions extends RunItemImageOptions {
 /**
  * O item em processamento dentro de `items.each`: o desfecho (`succeeded`/`failed`/
  * `occurrence`) com o `id` e o payload base já resolvidos, e a step da etapa para quem
- * quiser medir sub-etapas (`item.step.startChild(...)`). Sem chamada explícita, o SDK
+ * quiser medir sub-etapas (`item.step.start(...)`). Sem chamada explícita, o SDK
  * decide: retornou → `succeeded`; lançou → `failed` com a mensagem do erro.
  */
 interface RunItemHandle {
@@ -487,7 +523,7 @@ interface RunItems {
     /**
      * Processa uma lista item a item com o contrato da plataforma garantido pelo SDK: cada
      * elemento vira uma step e um item; uma exceção no handler registra o item como `failed`
-     * (com a mensagem do erro), marca a step com `setError` e **segue para o próximo** — a
+     * (com a mensagem do erro), marca a step com `failed` e **segue para o próximo** — a
      * lista inteira é processada, e o progresso avança a cada elemento. Só cancelamento,
      * timeout e shutdown interrompem o loop (o erro sobe como em qualquer ponto de parada).
      * Resolve com os totalizadores por desfecho.
@@ -535,8 +571,9 @@ interface RunContext {
     readonly files: RunFiles;
     /**
      * Transaction de performance desta execução — já correlacionada à run e finalizada
-     * automaticamente ao fim do handler. Use `transaction.startChild(op, description)` para
-     * medir as etapas (steps); elas aparecem como waterfall na aba de performance da execução.
+     * automaticamente ao fim do handler. Use `transaction.start(op, description)` para
+     * abrir as etapas (steps) e `succeeded(op?)`/`failed(error, op?)` para fechá-las; elas
+     * aparecem como waterfall na aba de performance da execução.
      */
     readonly transaction: Transaction;
     /**
@@ -551,7 +588,7 @@ interface RunContext {
     readonly signal: AbortSignal;
     /**
      * Lança um erro `RunCanceled` se a run foi cancelada/abortada. O SDK já chama isto em
-     * items/progress/transaction.startChild/sleep/retry; use para um controle mais fino.
+     * items/progress/transaction.start/sleep/retry; use para um controle mais fino.
      */
     throwIfCanceled(): void;
     /** Sleep cancelável: rejeita com `RunCanceled` se o signal disparar antes de ms. */
@@ -582,7 +619,7 @@ interface Hobots extends RunContext {
     /**
      * Embrulha um print para ir junto de um log, item ou step — `hobots.log.error('x', hobots.image(png))`,
      * `hobots.items.failed('x', payload, { image: hobots.image(png, { caption }) })`,
-     * `step.setError(err, undefined, { image: png })`. Puro: nenhum I/O até o evento ser registrado.
+     * `step.failed(err, undefined, { image: png })`. Puro: nenhum I/O até o evento ser registrado.
      */
     image(input: AttachInput, options?: ImageOptions): ImageAttachment;
     /** O valor tem a forma de um arquivo de campo de upload (`FileRef`) — puro, sem I/O. */

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { RunAttachmentContentType, EventType, EnvironmentInput, MachineSnapshot, EventPayload, TransactionPayload, HeartbeatPayload, StepStatus, RunLogLevel, StepData, FileRef, RunItemStatus, RunProgress } from './protocol.js';
-export { Breadcrumb, BreadcrumbLevel, Envelope, EnvelopeItem, Environment, EventUser, ExceptionData, FileDownloadResponse, FileStorage, InstanceInfo, InstanceMode, ItemColumn, ItemsDeclaration, MachineProcess, PollRequest, PollResponse, RunAttachmentConfirmRequest, RunAttachmentConfirmResponse, RunAttachmentCreateRequest, RunAttachmentCreateResponse, RunCreateRequest, RunCreateResponse, RunDescriptor, RunError, RunItemInput, RunItemsCreateRequest, RunItemsCreateResponse, RunLogEntry, RunStatus, RunUpdateRequest, RunUpdateResponse, RunUpdateStatus, StackFrame } from './protocol.js';
+export { Breadcrumb, BreadcrumbLevel, Envelope, EnvelopeItem, Environment, EventUser, ExceptionData, FileDownloadResponse, FileStorage, InstanceInfo, InstanceMode, ItemColumn, ItemsDeclaration, MachineProcess, PollRequest, PollResponse, RunAttachmentConfirmRequest, RunAttachmentConfirmResponse, RunAttachmentCreateRequest, RunAttachmentCreateResponse, RunCreateRequest, RunCreateResponse, RunDescriptor, RunError, RunItemInput, RunItemsCreateRequest, RunItemsCreateResponse, RunLogEntry, RunStartRequest, RunStartResponse, RunStatus, RunUpdateRequest, RunUpdateResponse, RunUpdateStatus, StackFrame } from './protocol.js';
 
 /** Espera entre tentativas: ms fixo ou função do número da tentativa que acabou de falhar (1-based). */
 type RetryDelay = number | ((attempt: number) => number);
@@ -24,7 +24,7 @@ declare const IMAGE_BRAND: unique symbol;
 /**
  * Uma imagem pronta para ser pendurada num evento da run — o retorno de `hobots.image()`.
  * É só um envelope (bytes/caminho + legenda); nenhum I/O acontece até o evento ser
- * registrado por `hobots.log.*`, `hobots.items.*` ou `step.setStatus/setError`.
+ * registrado por `hobots.log.*`, `hobots.items.*` ou `step.setStatus/failed`.
  */
 declare class ImageAttachment {
     readonly input: AttachInput;
@@ -49,11 +49,11 @@ type ItemColumnInput = string | {
 };
 
 /**
- * Opções do processo (telemetria, identidade, handlers globais). Valem as da PRIMEIRA
- * chamada a register()/start(); chamadas seguintes com valores diferentes avisam e são ignoradas.
+ * Opções do processo (telemetria, identidade, handlers globais). Só há uma chamada a
+ * register()/start() por processo — a segunda lança (`o agente já foi iniciado`).
  */
 interface HobotsOptions {
-    /** Client Secret do agente (hb_…). Default: env HOBOTS_CLIENT_SECRET. Copie em Configurações → Agentes. */
+    /** Client Secret do agente (hb_…). Default: env HOBOTS_CLIENT_SECRET. Copie na Central: agente → Configurações → agente → aba credenciais. */
     clientSecret?: string;
     /**
      * Identificador único e estável desta instância — a identidade do agente no painel
@@ -78,7 +78,10 @@ interface HobotsOptions {
      * instância no app) e como `contexts.machine` em cada evento. Só em Node. Default: true
      */
     machineMetrics?: boolean;
-    /** Registra handlers globais de erro (uncaughtException etc.) que abrem issues. Default: true */
+    /**
+     * Erro não tratado vira issue: o que escapa do handler de uma execução (além de falhar a
+     * run; cancelamento fica de fora) e o que escapa fora dele (uncaughtException etc.). Default: true
+     */
     captureUnhandled?: boolean;
     /**
      * Avançado. Instala handlers de SIGINT/SIGTERM/uncaughtException que reportam as runs
@@ -134,6 +137,14 @@ interface RegisterOptions extends RunOptions {
     concurrency?: number;
     /** Intervalo entre polls sem trabalho (mínimo 1_000). Default: 2_000 */
     pollIntervalMs?: number;
+    /**
+     * Avançado. Executa só esta run (já reivindicada para a instância, ex.: pelo Studio) em
+     * vez de fazer poll: anexa-se a ela (`POST /v1/runs/:id/start`), roda o handler uma vez e
+     * encerra o SDK (`close()`), liberando o processo. 404/409 (run inexistente, cancelada, já
+     * iniciada ou de outra instância) encerram sem rodar o handler. Default: env HOBOTS_RUN_ID;
+     * sem ela, poll normal.
+     */
+    runId?: string;
 }
 /** Opções de `start()` — agente sempre ligado, que abre a própria run. */
 type StartOptions = RunOptions;
@@ -209,6 +220,11 @@ interface ClientOptions {
     /** Tags aplicadas a todos os eventos e transactions */
     tags?: Record<string, string>;
     debug?: boolean;
+    /**
+     * O erro final que escapou do handler de uma run também vira issue (além de falhar a run).
+     * Ligado pelo runtime junto com `captureUnhandled`; desligado no client cru (testes).
+     */
+    captureRunErrors?: boolean;
     /** Knobs internos do transport (testes) — não fazem parte da API pública */
     flushIntervalMs?: number;
     maxBatchSize?: number;
@@ -272,23 +288,29 @@ declare class Step {
      */
     setStatus(status: StepStatus, message?: string, options?: StepOutcomeOptions): this;
     /**
-     * Marca a step como `error` guardando o motivo em `data.error` ({ type, message }).
-     * Aceita qualquer valor lançado; `message` sobrescreve a mensagem do erro.
+     * Marca a step como `error` guardando o motivo em `data.error` ({ type, message }) e a
+     * fecha. Aceita qualquer valor lançado; `message` sobrescreve a mensagem do erro.
      * `options.image` pendura um print do estado da tela em `data.attachments`.
+     * Numa step já fechada não faz nada.
      */
-    setError(error: unknown, message?: string, options?: StepOutcomeOptions): this;
+    failed(error: unknown, message?: string, options?: StepOutcomeOptions): this;
     /**
      * Dispara o upload pela run (sink do RunReporter) e referencia o anexo em
      * `data.attachments` (chave reservada; teto igual ao das linhas de log). Fora de uma
      * run não há onde pendurar a imagem — descarta com aviso único.
      */
     private attachImage;
-    /** Motivo registrado via setStatus(…, message) ou setError — usado no log de FINISH. */
+    /** Motivo registrado via setStatus(…, message) ou failed — usado no log de FINISH. */
     private reason;
     setData(key: string, value: unknown): this;
     /** Step aninhada (filha desta step). */
-    startChild(op?: string, description?: string): Step;
-    finish(): void;
+    start(op?: string, description?: string): Step;
+    /**
+     * Fecha a step. O status fica o que estiver (`ok` por padrão, ou o de `setStatus`).
+     * Idempotente; a transaction fecha no fim da run o que ficou aberto.
+     */
+    succeeded(): this;
+    private close;
     toJSON(): StepData;
 }
 /**
@@ -331,12 +353,26 @@ declare class Transaction {
     attachImage(image: ImageInput): string | undefined;
     /**
      * Conecta a checagem de cancelamento chamada antes de cada step nova — é assim que
-     * `hobots.transaction.startChild()` (e `step.startChild()`) param uma run cancelada.
+     * `hobots.transaction.start()` (e `step.start()`) param uma run cancelada.
      */
     setStepGuard(guard: () => void): void;
     createStep(parentStepId: string, op?: string, description?: string): Step;
-    /** Step direta da transaction. */
-    startChild(op?: string, description?: string): Step;
+    /** Step direta da transaction. `op` é o nome usado por `succeeded(name)`/`failed(error, name)`. */
+    start(op?: string, description?: string): Step;
+    /**
+     * Fecha a step aberta mais recente — com `name`, a mais recente aberta com esse `op`.
+     * Sem step aberta (ou sem nenhuma com esse nome), não faz nada e devolve undefined.
+     */
+    succeeded(name?: string): Step | undefined;
+    /**
+     * Marca como `error` e fecha a step aberta mais recente — com `name`, a mais recente
+     * aberta com esse `op`. `options.message` sobrescreve a mensagem do erro e
+     * `options.image` pendura um print. Sem step aberta, não faz nada e devolve undefined.
+     */
+    failed(error: unknown, name?: string, options?: StepOutcomeOptions & {
+        message?: string;
+    }): Step | undefined;
+    private findOpenStep;
     setTag(key: string, value: string): this;
     setStatus(status: string): this;
     setName(name: string): this;
@@ -421,7 +457,7 @@ interface RunItemOptions extends RunItemImageOptions {
 /**
  * O item em processamento dentro de `items.each`: o desfecho (`succeeded`/`failed`/
  * `occurrence`) com o `id` e o payload base já resolvidos, e a step da etapa para quem
- * quiser medir sub-etapas (`item.step.startChild(...)`). Sem chamada explícita, o SDK
+ * quiser medir sub-etapas (`item.step.start(...)`). Sem chamada explícita, o SDK
  * decide: retornou → `succeeded`; lançou → `failed` com a mensagem do erro.
  */
 interface RunItemHandle {
@@ -487,7 +523,7 @@ interface RunItems {
     /**
      * Processa uma lista item a item com o contrato da plataforma garantido pelo SDK: cada
      * elemento vira uma step e um item; uma exceção no handler registra o item como `failed`
-     * (com a mensagem do erro), marca a step com `setError` e **segue para o próximo** — a
+     * (com a mensagem do erro), marca a step com `failed` e **segue para o próximo** — a
      * lista inteira é processada, e o progresso avança a cada elemento. Só cancelamento,
      * timeout e shutdown interrompem o loop (o erro sobe como em qualquer ponto de parada).
      * Resolve com os totalizadores por desfecho.
@@ -535,8 +571,9 @@ interface RunContext {
     readonly files: RunFiles;
     /**
      * Transaction de performance desta execução — já correlacionada à run e finalizada
-     * automaticamente ao fim do handler. Use `transaction.startChild(op, description)` para
-     * medir as etapas (steps); elas aparecem como waterfall na aba de performance da execução.
+     * automaticamente ao fim do handler. Use `transaction.start(op, description)` para
+     * abrir as etapas (steps) e `succeeded(op?)`/`failed(error, op?)` para fechá-las; elas
+     * aparecem como waterfall na aba de performance da execução.
      */
     readonly transaction: Transaction;
     /**
@@ -551,7 +588,7 @@ interface RunContext {
     readonly signal: AbortSignal;
     /**
      * Lança um erro `RunCanceled` se a run foi cancelada/abortada. O SDK já chama isto em
-     * items/progress/transaction.startChild/sleep/retry; use para um controle mais fino.
+     * items/progress/transaction.start/sleep/retry; use para um controle mais fino.
      */
     throwIfCanceled(): void;
     /** Sleep cancelável: rejeita com `RunCanceled` se o signal disparar antes de ms. */
@@ -582,7 +619,7 @@ interface Hobots extends RunContext {
     /**
      * Embrulha um print para ir junto de um log, item ou step — `hobots.log.error('x', hobots.image(png))`,
      * `hobots.items.failed('x', payload, { image: hobots.image(png, { caption }) })`,
-     * `step.setError(err, undefined, { image: png })`. Puro: nenhum I/O até o evento ser registrado.
+     * `step.failed(err, undefined, { image: png })`. Puro: nenhum I/O até o evento ser registrado.
      */
     image(input: AttachInput, options?: ImageOptions): ImageAttachment;
     /** O valor tem a forma de um arquivo de campo de upload (`FileRef`) — puro, sem I/O. */