hobots 4.1.0 → 4.5.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { RunAttachmentContentType, EventType, EnvironmentInput, MachineSnapshot, EventPayload, TransactionPayload, HeartbeatPayload, StepStatus, RunLogLevel, StepData, RunItemStatus, RunProgress } from './protocol.cjs';
-export { Breadcrumb, BreadcrumbLevel, Envelope, EnvelopeItem, Environment, EventUser, ExceptionData, 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, 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, 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;
@@ -355,6 +391,38 @@ declare class Transaction {
     finish(): void;
 }
 
+interface FileDownloadOptions {
+    /**
+     * Destino da cópia: uma pasta existente (ou terminada em `/`) recebe o arquivo com o nome
+     * original; qualquer outro caminho é o arquivo final. Omitido: pasta temporária da
+     * execução, apagada quando ela termina.
+     */
+    dest?: string;
+}
+/**
+ * Arquivos dos campos de upload do formulário (`hobots.files`). O valor do campo nos
+ * params é um `FileRef` (ou uma lista deles); `download` traz o arquivo para o disco
+ * desta máquina — do S3 (enviado pela Central) ou da pasta do Studio (mesmo computador)
+ * — e o consome na origem: cada arquivo é baixado uma vez.
+ */
+interface RunFiles {
+    /** Todos os arquivos dos params (campos de topo, valor único ou lista), na ordem dos campos. */
+    list(): FileRef[];
+    /** O arquivo do campo (campo único), a lista (campo "vários arquivos") ou undefined. */
+    get(field: string): FileRef | FileRef[] | undefined;
+    /**
+     * Baixa um arquivo e resolve com o caminho local. Aceita o `FileRef` ou o nome de um
+     * campo de arquivo único (para campo com vários arquivos, use `downloadAll`). Só depois
+     * da cópia completa e conferida o arquivo é consumido na origem — uma falha não perde
+     * nada e pode ser tentada de novo. Respeita o cancelamento da execução.
+     */
+    download(refOrField: FileRef | string, options?: FileDownloadOptions): Promise<string>;
+    /** Baixa todos os arquivos do campo (único ou lista), em ordem. `dest` aqui é uma pasta. */
+    downloadAll(field: string, options?: FileDownloadOptions): Promise<string[]>;
+    /** Conteúdo do arquivo em memória — baixa, lê e apaga a cópia temporária. */
+    read(refOrField: FileRef | string): Promise<Buffer>;
+}
+
 /**
  * `hobots.log`: cada método aceita vários argumentos, como `console.log` — cada um vira
  * texto (`safeString`) e são unidos por espaço. Nunca lança, nem com a run cancelada.
@@ -389,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 {
@@ -455,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.
@@ -495,10 +563,17 @@ interface RunContext {
     readonly items: RunItems;
     /** Progresso declarado (barra + ETA no app) — opcional, independente de `items` */
     readonly progress: RunProgressReporter;
+    /**
+     * Arquivos dos campos de upload do formulário: `list()`, `get(campo)`, `download(refOuCampo)`
+     * (caminho local), `downloadAll(campo)` e `read(refOuCampo)` (conteúdo em memória).
+     * Cada arquivo é consumido na origem ao ser baixado — baixe uma vez e reaproveite a cópia.
+     */
+    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;
     /**
@@ -513,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. */
@@ -544,9 +619,11 @@ 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. */
+    isFileRef(value: unknown): value is FileRef;
 }
 declare global {
     var hobots: Hobots;
@@ -558,5 +635,6 @@ declare const close: (timeoutMs?: number) => Promise<boolean>;
 declare const captureException: (error: unknown, hint?: CaptureHint) => string | undefined;
 declare const retry: <T>(fn: (attempt: number) => T | Promise<T>, options?: RetryOptions) => Promise<T>;
 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, 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 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, register, retry, start };
+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 };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { RunAttachmentContentType, EventType, EnvironmentInput, MachineSnapshot, EventPayload, TransactionPayload, HeartbeatPayload, StepStatus, RunLogLevel, StepData, RunItemStatus, RunProgress } from './protocol.js';
-export { Breadcrumb, BreadcrumbLevel, Envelope, EnvelopeItem, Environment, EventUser, ExceptionData, 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';
+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, 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;
@@ -355,6 +391,38 @@ declare class Transaction {
     finish(): void;
 }
 
+interface FileDownloadOptions {
+    /**
+     * Destino da cópia: uma pasta existente (ou terminada em `/`) recebe o arquivo com o nome
+     * original; qualquer outro caminho é o arquivo final. Omitido: pasta temporária da
+     * execução, apagada quando ela termina.
+     */
+    dest?: string;
+}
+/**
+ * Arquivos dos campos de upload do formulário (`hobots.files`). O valor do campo nos
+ * params é um `FileRef` (ou uma lista deles); `download` traz o arquivo para o disco
+ * desta máquina — do S3 (enviado pela Central) ou da pasta do Studio (mesmo computador)
+ * — e o consome na origem: cada arquivo é baixado uma vez.
+ */
+interface RunFiles {
+    /** Todos os arquivos dos params (campos de topo, valor único ou lista), na ordem dos campos. */
+    list(): FileRef[];
+    /** O arquivo do campo (campo único), a lista (campo "vários arquivos") ou undefined. */
+    get(field: string): FileRef | FileRef[] | undefined;
+    /**
+     * Baixa um arquivo e resolve com o caminho local. Aceita o `FileRef` ou o nome de um
+     * campo de arquivo único (para campo com vários arquivos, use `downloadAll`). Só depois
+     * da cópia completa e conferida o arquivo é consumido na origem — uma falha não perde
+     * nada e pode ser tentada de novo. Respeita o cancelamento da execução.
+     */
+    download(refOrField: FileRef | string, options?: FileDownloadOptions): Promise<string>;
+    /** Baixa todos os arquivos do campo (único ou lista), em ordem. `dest` aqui é uma pasta. */
+    downloadAll(field: string, options?: FileDownloadOptions): Promise<string[]>;
+    /** Conteúdo do arquivo em memória — baixa, lê e apaga a cópia temporária. */
+    read(refOrField: FileRef | string): Promise<Buffer>;
+}
+
 /**
  * `hobots.log`: cada método aceita vários argumentos, como `console.log` — cada um vira
  * texto (`safeString`) e são unidos por espaço. Nunca lança, nem com a run cancelada.
@@ -389,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 {
@@ -455,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.
@@ -495,10 +563,17 @@ interface RunContext {
     readonly items: RunItems;
     /** Progresso declarado (barra + ETA no app) — opcional, independente de `items` */
     readonly progress: RunProgressReporter;
+    /**
+     * Arquivos dos campos de upload do formulário: `list()`, `get(campo)`, `download(refOuCampo)`
+     * (caminho local), `downloadAll(campo)` e `read(refOuCampo)` (conteúdo em memória).
+     * Cada arquivo é consumido na origem ao ser baixado — baixe uma vez e reaproveite a cópia.
+     */
+    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;
     /**
@@ -513,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. */
@@ -544,9 +619,11 @@ 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. */
+    isFileRef(value: unknown): value is FileRef;
 }
 declare global {
     var hobots: Hobots;
@@ -558,5 +635,6 @@ declare const close: (timeoutMs?: number) => Promise<boolean>;
 declare const captureException: (error: unknown, hint?: CaptureHint) => string | undefined;
 declare const retry: <T>(fn: (attempt: number) => T | Promise<T>, options?: RetryOptions) => Promise<T>;
 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, 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 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, register, retry, start };
+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 };