hobots 4.2.0 → 5.0.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';
+import { RunAttachmentContentType, EnvironmentInput, EventType, FileRef, RunItemStatus, RunProgress } from './protocol.cjs';
+export { Breadcrumb, BreadcrumbLevel, Envelope, EnvelopeItem, Environment, EventPayload, EventUser, ExceptionData, FileDownloadResponse, FileStorage, HeartbeatPayload, InstanceInfo, InstanceMode, ItemColumn, ItemsDeclaration, MachineProcess, MachineSnapshot, PollRequest, PollResponse, RunAttachmentConfirmRequest, RunAttachmentConfirmResponse, RunAttachmentCreateRequest, RunAttachmentCreateResponse, RunCreateRequest, RunCreateResponse, RunDescriptor, RunError, RunItemInput, RunItemsCreateRequest, RunItemsCreateResponse, RunLogEntry, RunLogLevel, RunStartRequest, RunStartResponse, RunStatus, RunUpdateRequest, RunUpdateResponse, RunUpdateStatus, StackFrame, StepData, StepStatus, TransactionPayload } 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;
@@ -36,24 +36,55 @@ declare class ImageAttachment {
 /** O que os métodos com imagem aceitam: bytes/caminho crus ou o envelope de `hobots.image()`. */
 type ImageInput = AttachInput | ImageAttachment;
 
-interface Logger {
-    debug: (...args: unknown[]) => void;
-    warn: (...args: unknown[]) => void;
-    error: (...args: unknown[]) => void;
-}
-
 /** Coluna de itens como o dev declara: só a chave, ou chave + rótulo. */
 type ItemColumnInput = string | {
     key: string;
     label?: string;
 };
 
+/** Opções de `hobots.step(nome, fn, opções)`. */
+interface StepOptions {
+    /**
+     * Tentativas extras da etapa quando `fn` lança (uma etapa só na Central, com `data.attempts`).
+     * Cancelamento e timeout nunca são re-tentados. Default: 1 (tenta 2 vezes no total); 0 desliga —
+     * use 0 em etapas com efeito colateral não idempotente (enviar, pagar, emitir).
+     */
+    retries?: number;
+    /** Espera entre tentativas: ms fixo ou função da tentativa que falhou (1-based). Default: 5_000 */
+    retryDelayMs?: RetryDelay;
+    /**
+     * Ao terminar (deu certo ou esgotou), a etapa raiz faz `hobots.flush()` — ela, os itens e os
+     * logs aparecem na Central na hora. Sub-etapas saem no flush da etapa-mãe (ou do ciclo do
+     * `items.each`). `false` desliga. Default: true.
+     */
+    flush?: boolean;
+}
+/**
+ * A etapa em andamento — o handle que a função de `hobots.step(nome, fn)` recebe. O bot só
+ * registra o que o SDK não vê sozinho: um aviso de negócio, um print da tela e dados livres.
+ * Abrir, repetir e fechar a etapa é do SDK.
+ */
+interface StepHandle {
+    /**
+     * Marca a etapa como `warning` com o motivo (aparece no waterfall da Central e no log de
+     * FINISH). Uma etapa que já falhou não volta para aviso. `options.image` pendura um print.
+     */
+    warning(message: string, options?: {
+        image?: ImageInput;
+    }): StepHandle;
+    /** Pendura um print do estado da tela na etapa (até 4 por etapa) — botão de imagem no app. */
+    image(image: ImageInput): StepHandle;
+    /** Dado livre da etapa (`data.<key>` no waterfall). A chave `attachments` é reservada. */
+    data(key: string, value: unknown): StepHandle;
+}
+/** A função de uma etapa: recebe o handle (pode ignorá-lo) e devolve o resultado da etapa. */
+type StepFn<T> = (etapa: StepHandle) => T | Promise<T>;
 /**
- * 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 +109,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 +168,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;
@@ -153,7 +195,7 @@ interface CaptureHint {
     fingerprint?: string[];
     /**
      * Print da tela enviado junto da captura. Dentro de uma execução, a imagem vira anexo
-     * da linha de log que espelha o evento — miniatura na aba "logs do agente". Fora de uma
+     * da linha de log que espelha o evento (aba "logs do agente") e aparece na issue. Fora de uma
      * execução não há onde pendurar a imagem: o SDK descarta com um aviso. O upload roda
      * em segundo plano e **nunca bloqueia nem lança**. PNG, JPEG ou WEBP, até 5 MB, 20 por execução.
      *
@@ -164,197 +206,6 @@ interface CaptureHint {
     attachment?: ImageInput | CaptureAttachment;
 }
 
-interface ResolvedConfig {
-    /** Client Secret do agente (enviado como Authorization: Bearer, nunca na URL) */
-    key: string;
-    baseUrl: string;
-    /** Ingestão de telemetria: <baseUrl>/v1/ingest */
-    ingestEndpoint: string;
-    /** API de execuções (poll, runs, itens, anexos): <baseUrl>/v1/runs */
-    runsBaseUrl: string;
-}
-
-/**
- * Coleta CPU/memória/disco da máquina e do processo — só em Node (no browser é no-op).
- *
- * Os módulos `node:*` entram por import dinâmico (o bundle é `platform: neutral`), e
- * `sample()` é síncrono e barato: `os.cpus()` + `statfsSync` + `process.memoryUsage()`.
- * Nunca lança — telemetria de recurso não pode derrubar o bot nem o capture de um erro.
- */
-declare class MachineSampler {
-    private readonly instanceId;
-    private readonly logger;
-    private os;
-    private fs;
-    private ready;
-    private prevCpu;
-    private prevProcessCpu;
-    private prevAt;
-    private lastCpuPercent;
-    private lastProcessCpuPercent;
-    constructor(instanceId: string, logger: Logger);
-    /** Carrega os módulos e tira a leitura-base de CPU (a primeira amostra ainda sai com cpu_percent null). */
-    start(): Promise<void>;
-    sample(): MachineSnapshot | undefined;
-    private cpuTotals;
-    /** Média desde a leitura anterior; leituras com menos de 1s de janela reutilizam a última média. */
-    private updateCpu;
-    private diskUsage;
-}
-
-/** Opções de telemetria resolvidas pelo runtime a partir do primeiro register()/start(). */
-interface ClientOptions {
-    environment?: EnvironmentInput;
-    release?: string;
-    /** Tags aplicadas a todos os eventos e transactions */
-    tags?: Record<string, string>;
-    debug?: boolean;
-    /** Knobs internos do transport (testes) — não fazem parte da API pública */
-    flushIntervalMs?: number;
-    maxBatchSize?: number;
-}
-declare class Client {
-    #private;
-    readonly logger: Logger;
-    /** Eco de lifecycle (Transaction.emit) e afins só imprimem no terminal com debug ligado. */
-    readonly debug: boolean;
-    private readonly transport;
-    private machine;
-    constructor(options: ClientOptions, config: ResolvedConfig);
-    get options(): ClientOptions;
-    get config(): ResolvedConfig;
-    /** Sampler de recursos da máquina — cada evento passa a levar `contexts.machine`. */
-    attachMachineSampler(sampler: MachineSampler | undefined): void;
-    /** Serialização explícita nunca inclui o secret. */
-    toJSON(): Record<string, unknown>;
-    captureException(error: unknown, hint?: CaptureHint): string;
-    captureEvent(event: EventPayload, hint?: CaptureHint): string;
-    private prepareEvent;
-    sendTransaction(payload: TransactionPayload): void;
-    sendHeartbeat(payload: HeartbeatPayload): void;
-    /**
-     * Ambiente do item: o dele, senão o das opções, senão produção. Centralizado
-     * porque evento, transaction e heartbeat precisam responder igual — o servidor
-     * normaliza apelidos legados, então aqui basta repassar.
-     */
-    private resolveEnvironment;
-    flush(timeoutMs?: number): Promise<boolean>;
-    close(timeoutMs?: number): Promise<boolean>;
-}
-
-/** Recebe os eventos de lifecycle da transaction para espelhá-los nos logs da run. */
-type LifecycleSink = (level: RunLogLevel, message: string) => void;
-/**
- * Recebe a imagem de uma step e dispara o upload pela run; devolve o id do anexo
- * (já referenciável em `data.attachments`) ou undefined quando descartada.
- */
-type AttachmentSink = (image: ImageInput, ts: string) => string | undefined;
-/** Opções dos desfechos de step que aceitam um print do estado da tela. */
-interface StepOutcomeOptions {
-    /** Print da step (bytes/caminho ou `hobots.image(bytes, { caption })`) — botão de imagem no app. */
-    image?: ImageInput;
-}
-declare class Step {
-    private readonly transaction;
-    readonly parentStepId: string;
-    readonly op?: string | undefined;
-    readonly description?: string | undefined;
-    readonly stepId: string;
-    readonly startTimestamp: string;
-    status: StepStatus;
-    endTimestamp?: string;
-    data?: Record<string, unknown>;
-    constructor(transaction: Transaction, parentStepId: string, op?: string | undefined, description?: string | undefined);
-    /**
-     * Desfecho da step. `message` (opcional) é o motivo legível — vai em `data.message`
-     * e aparece na Central (performance e banner da execução) e no log de FINISH.
-     * `options.image` pendura um print do estado da tela em `data.attachments`.
-     */
-    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.
-     * `options.image` pendura um print do estado da tela em `data.attachments`.
-     */
-    setError(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. */
-    private reason;
-    setData(key: string, value: unknown): this;
-    /** Step aninhada (filha desta step). */
-    startChild(op?: string, description?: string): Step;
-    finish(): void;
-    toJSON(): StepData;
-}
-/**
- * Uma unidade de trabalho nomeada (ex.: uma execução de rotina, uma sincronização).
- * Steps filhas medem as etapas internas (chamadas HTTP, queries, etc.).
- */
-declare class Transaction {
-    private readonly client;
-    name: string;
-    readonly op?: string | undefined;
-    /** Correlaciona a uma execução do agente — preenchido automaticamente em hobots.transaction */
-    private readonly runId?;
-    readonly eventId: string;
-    readonly stepId: string;
-    readonly startTimestamp: string;
-    status: string;
-    private readonly steps;
-    private readonly tags;
-    private finished;
-    private lifecycleSink?;
-    private attachmentSink?;
-    private warnedNoAttachmentSink;
-    private stepGuard?;
-    private lifecycleBacklog;
-    constructor(client: Client | undefined, name: string, op?: string | undefined, 
-    /** Correlaciona a uma execução do agente — preenchido automaticamente em hobots.transaction */
-    runId?: string | undefined);
-    /**
-     * Registra o início/fim de uma step ou transaction: espelha a linha no sink de
-     * lifecycle, se conectado (é assim que os eventos de performance aparecem nos
-     * logs da run no app), e ecoa no terminal apenas com `debug: true` — o SDK não
-     * escreve no stdout do processo do usuário sem permissão.
-     */
-    emit(kind: 'transaction' | 'step', phase: 'start' | 'finish', label: string, startTs?: string, endTs?: string, status?: StepStatus | string, reason?: string): void;
-    /** Conecta o espelho de lifecycle (RunReporter) e faz replay do backlog em ordem. */
-    setLifecycleSink(sink: LifecycleSink): void;
-    /** Conecta o pipeline de anexos da run — é o que dá imagem às steps. */
-    setAttachmentSink(sink: AttachmentSink): void;
-    /** Imagem de uma step → id do anexo pela run; sem run, descarta com aviso único. */
-    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.
-     */
-    setStepGuard(guard: () => void): void;
-    createStep(parentStepId: string, op?: string, description?: string): Step;
-    /** Step direta da transaction. */
-    startChild(op?: string, description?: string): Step;
-    setTag(key: string, value: string): this;
-    setStatus(status: string): this;
-    setName(name: string): this;
-    /**
-     * Envia já as steps raiz finalizadas (e todas as descendentes, fechando as que
-     * ficaram abertas) como transactions parciais da mesma run (`op` hobots.run.flush,
-     * `event_id` novo, até 200 steps cada) e as tira da memória. Steps raiz ainda abertas
-     * ficam para o próximo flush ou para o `finish()`. É assim que um agente sempre
-     * ligado (`start()`), cuja run não termina, entrega as etapas enquanto processa.
-     * Devolve quantas steps foram enviadas.
-     */
-    flush(): number;
-    /** Entrega já (com teto) o que está na fila do transport — as transactions parciais inclusive. */
-    drain(timeoutMs: number): Promise<void>;
-    private payload;
-    finish(): void;
-}
-
 interface FileDownloadOptions {
     /**
      * Destino da cópia: uma pasta existente (ou terminada em `/`) recebe o arquivo com o nome
@@ -420,24 +271,25 @@ 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
- * decide: retornou → `succeeded`; lançou → `failed` com a mensagem do erro.
+ * `occurrence`) com o `id` e o payload base já resolvidos, e o handle `step` da etapa do
+ * item (`warning`/`image`/`data`). Sub-etapas: `hobots.step(...)` dentro do handler já
+ * aninha na etapa do item. Sem chamada explícita, o SDK decide: retornou → `succeeded`;
+ * lançou → `failed` com a mensagem do erro.
  */
 interface RunItemHandle {
     /** Posição do elemento na lista (0-based). */
     readonly index: number;
     /** Identidade de negócio resolvida por `options.id` (undefined = o SDK gera uma). */
     readonly id: string | undefined;
-    /** Step desta etapa no waterfall de performance; undefined fora de uma execução. */
-    readonly step: Step | undefined;
+    /** Handle da etapa deste item no waterfall de performance; undefined fora de uma execução. */
+    readonly step: StepHandle | undefined;
     /** true depois do primeiro desfecho registrado (o SDK não sobrescreve o que o handler decidiu). */
     readonly reported: boolean;
     /** Item processado com sucesso. `payload` é mesclado sobre o payload base de `options.payload`. */
     succeeded(payload?: Record<string, unknown>, options?: RunItemImageOptions): void;
-    /** Falha sem lançar — o loop segue igual; a step vira `error` com o motivo. A imagem vai no item. */
+    /** Falha sem lançar — o loop segue igual; a etapa vira `error` com o motivo. A imagem vai no item. */
     failed(message: string, payload?: Record<string, unknown>, options?: RunItemImageOptions): void;
-    /** Ocorrência de negócio — a step vira `warning` com o motivo. A imagem vai no item. */
+    /** Ocorrência de negócio — a etapa vira `warning` com o motivo. A imagem vai no item. */
     occurrence(message: string, payload?: Record<string, unknown>, options?: RunItemImageOptions): void;
 }
 interface RunItemsEachOptions<T> {
@@ -445,15 +297,20 @@ interface RunItemsEachOptions<T> {
     id?: (element: T, index: number) => string | number | null | undefined;
     /** Atributos base do item (viram colunas no app) — presentes em qualquer desfecho, inclusive falha. */
     payload?: (element: T, index: number) => Record<string, unknown> | undefined;
-    /** `op` da step de cada item no waterfall. Default: 'item'. */
+    /** `op` da etapa de cada item no waterfall. Default: 'item'. */
     op?: string;
-    /** Descrição da step de cada item. Default: o `id`, senão `#<posição>`. */
+    /** Descrição da etapa de cada item. Default: o `id`, senão `#<posição>`. */
     description?: (element: T, index: number) => string;
     /**
      * Progresso automático: declara o total (tamanho da lista, se o bot ainda não declarou um)
      * e avança a cada elemento. `false` deixa o progresso por conta do bot. Default: true.
      */
     progress?: boolean;
+    /**
+     * Ao fim de cada ciclo, `hobots.flush()`: a etapa, o item e os logs do elemento aparecem na
+     * Central na hora. `false` desliga (tudo sai no envio periódico ou no fim da run). Default: true.
+     */
+    flush?: boolean;
 }
 /** Totalizadores do `items.each`, pelo desfecho final de cada elemento. */
 interface RunItemsEachResult {
@@ -486,8 +343,8 @@ interface RunItems {
     occurrence(message: string, payload?: Record<string, unknown>, options?: RunItemOptions): void;
     /**
      * 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
+     * elemento vira uma etapa e um item; uma exceção no handler registra o item como `failed`
+     * (com a mensagem do erro), marca a etapa como `error` 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.
@@ -534,24 +391,29 @@ 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.
+     * Registra a etapa `name` da execução executando `fn(etapa)` — o handle tem `warning`,
+     * `image` e `data`. Resolve com o retorno de `fn`. Falhou? Tenta de novo até `retries`
+     * vezes (default 1; `retries: 0` desliga), esperando `retryDelayMs` (default 5_000) entre
+     * as tentativas. Uma etapa só na Central: `warning` com o motivo quando a nova tentativa
+     * deu certo, `error` quando esgotou (a exceção sobe), `cancelled` em cancelamento/timeout
+     * (nunca repetem). `hobots.step` dentro de outra etapa vira sub-etapa. Abrir a etapa é um
+     * ponto de parada cooperativo (lança `RunCanceled` se a run foi cancelada). Ao terminar, a
+     * etapa raiz faz `flush()` (aparece na Central na hora); `flush: false` desliga.
      */
-    readonly transaction: Transaction;
+    step<T>(name: string, fn: StepFn<T>, options?: StepOptions): Promise<T>;
     /**
-     * Entrega já o que a execução fez: as steps raiz finalizadas viram transactions parciais
+     * Entrega já o que a execução fez: as etapas raiz finalizadas viram transactions parciais
      * (waterfall da Central sem esperar a run terminar) e itens, logs e progresso pendentes
-     * saem sem esperar o throttle. Quem decide quando chamar é o bot — num agente sempre
-     * ligado (`start()`), ao fim de cada rodada que processou itens. Aguarda a entrega com
-     * teto (`timeoutMs`, default 15s) e nunca lança.
+     * saem sem esperar o throttle. `step` (raiz) e cada ciclo de `items.each` já fazem isto
+     * sozinhos; chame à mão só para o que roda fora deles (ex.: no `start()`, uma rodada que
+     * só loga). Aguarda a entrega com teto (`timeoutMs`, default 15s) e nunca lança.
      */
     flush(timeoutMs?: number): Promise<void>;
     /** Dispara em cancelamento (run cancelada no app), timeout ou shutdown — cancelamento cooperativo */
     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/step/sleep/retry; use para um controle mais fino.
      */
     throwIfCanceled(): void;
     /** Sleep cancelável: rejeita com `RunCanceled` se o signal disparar antes de ms. */
@@ -564,7 +426,7 @@ type RunHandler<P = Record<string, unknown>> = (params: P, ctx: RunContext) => v
 
 /**
  * O objeto global do SDK: as funções do processo (register/start/close/captureException/
- * retry) e o contexto da execução ATUAL (log, items, progress, transaction, signal…),
+ * retry) e o contexto da execução ATUAL (log, items, progress, step, signal…),
  * resolvido a cada acesso — funciona de qualquer módulo, sem passar `ctx` de mão em mão.
  */
 interface Hobots extends RunContext {
@@ -580,9 +442,9 @@ interface Hobots extends RunContext {
     /** Captura uma exceção como issue (módulo Issues). Retorna o event_id. */
     captureException(error: unknown, hint?: CaptureHint): string | undefined;
     /**
-     * Embrulha um print para ir junto de um log, item ou step — `hobots.log.error('x', hobots.image(png))`,
+     * Embrulha um print para ir junto de um log, item ou etapa — `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.
+     * `etapa.warning('x', { 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. */
@@ -600,4 +462,4 @@ declare const retry: <T>(fn: (attempt: number) => T | Promise<T>, options?: Retr
 declare const image: (input: AttachInput, options?: ImageOptions) => ImageAttachment;
 declare const isFileRef: (value: unknown) => value is FileRef;
 
-export { type AttachInput, type CaptureAttachment, type CaptureHint, EnvironmentInput, EventPayload, EventType, type FileDownloadOptions, FileRef, HeartbeatPayload, type Hobots, type HobotsOptions, ImageAttachment, type ImageInput, type ImageOptions, type ItemColumnInput, type ItemsOptions, MachineSnapshot, type RegisterOptions, type RetryDelay, type RetryOptions, RunAttachmentContentType, type RunContext, type RunFiles, type RunHandler, type RunItemHandle, type RunItemImageOptions, type RunItemOptions, RunItemStatus, type RunItems, type RunItemsEachHandler, type RunItemsEachOptions, type RunItemsEachResult, RunLogLevel, type RunLogger, type RunOptions, RunProgress, type RunProgressReporter, type StartOptions, Step, StepData, type StepOutcomeOptions, StepStatus, Transaction, TransactionPayload, captureException, close, hobots as default, hobots, image, isFileRef, register, retry, start };
+export { type AttachInput, type CaptureAttachment, type CaptureHint, EnvironmentInput, EventType, type FileDownloadOptions, FileRef, type Hobots, type HobotsOptions, ImageAttachment, type ImageInput, type ImageOptions, type ItemColumnInput, type ItemsOptions, type RegisterOptions, type RetryDelay, type RetryOptions, RunAttachmentContentType, type RunContext, type RunFiles, type RunHandler, type RunItemHandle, type RunItemImageOptions, type RunItemOptions, RunItemStatus, type RunItems, type RunItemsEachHandler, type RunItemsEachOptions, type RunItemsEachResult, type RunLogger, type RunOptions, RunProgress, type RunProgressReporter, type StartOptions, type StepFn, type StepHandle, type StepOptions, captureException, close, hobots as default, hobots, image, isFileRef, register, retry, start };