hobots 4.1.0 → 4.2.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, 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);
@@ -355,6 +355,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.
@@ -495,6 +527,12 @@ 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
@@ -547,6 +585,8 @@ interface Hobots extends RunContext {
      * `step.setError(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 +598,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, 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);
@@ -355,6 +355,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.
@@ -495,6 +527,12 @@ 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
@@ -547,6 +585,8 @@ interface Hobots extends RunContext {
      * `step.setError(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 +598,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.js

@@ -57,7 +57,7 @@ function scrubSecrets(text) {
 
 // src/utils.ts
 var SDK_NAME = "hobots";
-var SDK_VERSION = true ? "4.1.0" : "0.0.0-dev";
+var SDK_VERSION = true ? "4.2.0" : "0.0.0-dev";
 function isNode() {
   return typeof process !== "undefined" && typeof process.versions?.node === "string";
 }
@@ -139,13 +139,13 @@ async function fetchWithRetry(send, options) {
     } catch (error) {
       retriable = error;
     }
+    const failure = retriable instanceof Error ? retriable : new Error(String(retriable));
     const base = delays[attempt];
-    if (base === void 0) {
-      throw retriable instanceof Error ? retriable : new Error(String(retriable));
-    }
+    if (base === void 0 || options.signal?.aborted) throw failure;
     const delay = serverDelay ?? jitter(base);
     options.logger.warn(`${options.label}: falha (${String(retriable)}), retry em ${delay}ms`);
-    await sleep(delay);
+    await (options.signal ? abortableSleep(delay, options.signal) : sleep(delay));
+    if (options.signal?.aborted) throw failure;
   }
 }
 var MAX_RETRY_AFTER_MS = 6e4;
@@ -831,6 +831,7 @@ var ATTACHMENT_TERMINAL_STATUSES = [429, 501, 503];
 var ITEMS_TERMINAL_STATUSES = [429];
 var UPLOAD_TIMEOUT_MS = 3e4;
 var UPLOAD_RETRY_DELAYS_MS = [1e3, 4e3];
+var FILE_RETRY_DELAYS_MS = [1e3, 4e3];
 var TasksApiError = class extends Error {
   constructor(message, status) {
     super(message);
@@ -1018,7 +1019,13 @@ var TasksApi = class {
           signal: timeoutSignal
         })
       ),
-      { logger: this.logger, label: `anexo da run ${runId}`, noRetryStatuses: ATTACHMENT_TERMINAL_STATUSES }
+      {
+        logger: this.logger,
+        label: `anexo da run ${runId}`,
+        noRetryStatuses: ATTACHMENT_TERMINAL_STATUSES,
+        // run abortada (timeout, 409, kill): o create em voo rejeita por abort e não entra na ladder
+        signal
+      }
     );
     if (!response.ok) {
       throw new TasksApiError(`cria\xE7\xE3o de anexo rejeitada (HTTP ${response.status})`, response.status);
@@ -1052,7 +1059,7 @@ var TasksApi = class {
           signal: timeoutSignal
         })
       ),
-      { delays: UPLOAD_RETRY_DELAYS_MS, logger: this.logger, label: "upload de anexo" }
+      { delays: UPLOAD_RETRY_DELAYS_MS, logger: this.logger, label: "upload de anexo", signal }
     );
     if (!response.ok) {
       throw new TasksApiError(`upload de anexo rejeitado (HTTP ${response.status})`, response.status);
@@ -1074,6 +1081,74 @@ var TasksApi = class {
       throw new TasksApiError(`confirma\xE7\xE3o de anexo rejeitada (HTTP ${response.status})`, response.status);
     }
   }
+  /**
+   * Pede a URL pré-assinada de GET de um arquivo do formulário. 404 (não existe nesta run)
+   * e 410 (já baixado/expirado) viram `TasksApiError` com o status — quem chama traduz.
+   */
+  async requestFileDownload(runId, fileId, signal) {
+    const response = await fetchWithRetry(
+      () => withRequestTimeout(
+        UPDATE_TIMEOUT_MS,
+        signal,
+        (timeoutSignal) => fetch(`${this.baseUrl}/${encodeURIComponent(runId)}/files/${encodeURIComponent(fileId)}/download`, {
+          redirect: "error",
+          method: "POST",
+          headers: this.headers(),
+          signal: timeoutSignal
+        })
+      ),
+      { delays: FILE_RETRY_DELAYS_MS, logger: this.logger, label: `download do arquivo ${fileId}`, signal }
+    );
+    if (!response.ok) {
+      throw new TasksApiError(`download de arquivo rejeitado (HTTP ${response.status})`, response.status);
+    }
+    const body = await response.json().catch(() => null);
+    if (typeof body?.url !== "string") {
+      throw new TasksApiError("resposta inv\xE1lida do download de arquivo (url ausente)", 0);
+    }
+    return {
+      url: body.url,
+      expires_in: typeof body.expires_in === "number" ? body.expires_in : 0,
+      name: typeof body.name === "string" ? body.name : "",
+      size: typeof body.size === "number" ? body.size : -1,
+      content_type: typeof body.content_type === "string" ? body.content_type : ""
+    };
+  }
+  /**
+   * GET do binário direto no S3 — deliberadamente sem `authorization` (a autorização
+   * está na assinatura da URL; mandar o client secret para fora da API seria vazamento).
+   * Devolve a Response com o corpo ainda não lido: quem chama faz o streaming para o disco.
+   */
+  async fetchFile(url, signal) {
+    const response = await fetchWithRetry(() => fetch(url, { redirect: "error", method: "GET", signal }), {
+      delays: FILE_RETRY_DELAYS_MS,
+      logger: this.logger,
+      label: "download de arquivo",
+      signal
+    });
+    if (!response.ok) {
+      throw new TasksApiError(`download de arquivo falhou (HTTP ${response.status})`, response.status);
+    }
+    return response;
+  }
+  /**
+   * Confirma o download: o servidor apaga o objeto do S3 na hora. Idempotente (204);
+   * 404/410 também significam "não há mais nada a apagar" e contam como confirmado.
+   */
+  async confirmFileDownload(runId, fileId) {
+    const response = await fetchWithRetry(
+      () => fetch(`${this.baseUrl}/${encodeURIComponent(runId)}/files/${encodeURIComponent(fileId)}`, {
+        redirect: "error",
+        method: "DELETE",
+        headers: this.headers(),
+        signal: AbortSignal.timeout(UPDATE_TIMEOUT_MS)
+      }),
+      { delays: FILE_RETRY_DELAYS_MS, logger: this.logger, label: `confirma\xE7\xE3o do arquivo ${fileId}` }
+    );
+    if (!response.ok && response.status !== 404 && response.status !== 410) {
+      throw new TasksApiError(`confirma\xE7\xE3o de download rejeitada (HTTP ${response.status})`, response.status);
+    }
+  }
 };
 
 // src/tasks/backoff.ts
@@ -1208,6 +1283,255 @@ async function eachItem(list, handler, options, sink) {
   return result;
 }
 
+// src/tasks/files.ts
+var LOCAL_FILES_DIR_ENV = "HOBOTS_LOCAL_FILES_DIR";
+var FILE_DOWNLOAD_IDLE_TIMEOUT_MS = 6e4;
+var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function isFileRef(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const ref = value;
+  return typeof ref.id === "string" && typeof ref.name === "string" && typeof ref.size === "number" && typeof ref.contentType === "string" && (ref.storage === "s3" || ref.storage === "local");
+}
+function fileField(params, field) {
+  if (!Object.prototype.hasOwnProperty.call(params, field)) return void 0;
+  const value = params[field];
+  if (isFileRef(value)) return value;
+  if (Array.isArray(value) && value.every(isFileRef)) return value;
+  return void 0;
+}
+function collectFileRefs(params) {
+  const refs = [];
+  for (const field of Object.keys(params)) {
+    const value = fileField(params, field);
+    if (value !== void 0) refs.push(...Array.isArray(value) ? value : [value]);
+  }
+  return refs;
+}
+function safeFileName(name, fallback) {
+  const cleaned = name.replace(/^.*[\\/]/, "").replace(/[\u0000-\u001f<>:"|?*]/g, "_").trim();
+  return cleaned === "" || cleaned === "." || cleaned === ".." ? fallback : cleaned;
+}
+function isInsideDir(root, candidate, sep) {
+  const base = root.endsWith(sep) ? root : root + sep;
+  return candidate.startsWith(base) && candidate.length > base.length;
+}
+function unavailableLocal(ref) {
+  return new Error(`arquivo "${ref.name}" enviado pelo Studio de outro computador ou j\xE1 consumido`);
+}
+function errorCode(error) {
+  return error?.code;
+}
+var RunFileStore = class {
+  constructor(deps) {
+    this.deps = deps;
+    this.files = {
+      list: () => collectFileRefs(deps.params),
+      get: (field) => fileField(deps.params, field),
+      // async: erro de uso (campo sem arquivo, valor inválido) chega como Promise rejeitada, nunca síncrono
+      download: async (refOrField, options) => this.download(this.single(refOrField), options?.dest),
+      downloadAll: async (field, options) => this.downloadAll(field, options?.dest),
+      read: async (refOrField) => this.read(this.single(refOrField))
+    };
+  }
+  deps;
+  files;
+  tempDir;
+  /** Apaga a pasta temporária da execução (cópias que o bot não levou para `dest`). Nunca lança. */
+  async cleanup() {
+    const pending = this.tempDir;
+    this.tempDir = void 0;
+    if (!pending) return;
+    try {
+      const { rm } = await import("fs/promises");
+      await rm(await pending, { recursive: true, force: true });
+    } catch {
+    }
+  }
+  field(field) {
+    const value = fileField(this.deps.params, field);
+    if (value === void 0) throw new Error(`campo "${field}" n\xE3o tem arquivo nos params`);
+    return value;
+  }
+  single(refOrField) {
+    if (typeof refOrField === "string") {
+      const value = this.field(refOrField);
+      if (Array.isArray(value)) {
+        throw new Error(`campo "${refOrField}" tem v\xE1rios arquivos \u2014 use downloadAll("${refOrField}") ou passe um item da lista`);
+      }
+      return value;
+    }
+    if (!isFileRef(refOrField)) throw new TypeError("esperado um FileRef ou o nome de um campo de arquivo");
+    return refOrField;
+  }
+  async downloadAll(field, dest) {
+    const value = this.field(field);
+    const refs = Array.isArray(value) ? value : [value];
+    const paths = [];
+    for (const ref of refs) paths.push(await this.download(ref, dest, true));
+    return paths;
+  }
+  async read(ref) {
+    const { readFile, rm } = await import("fs/promises");
+    const { dirname } = await import("path");
+    const path = await this.download(ref, void 0);
+    try {
+      return await readFile(path);
+    } finally {
+      await rm(dirname(path), { recursive: true, force: true });
+    }
+  }
+  async download(ref, dest, destIsDir = false) {
+    this.checkCanceled();
+    const target = await this.resolveTarget(ref, dest, destIsDir);
+    if (ref.storage === "local") await this.copyLocal(ref, target);
+    else await this.downloadS3(ref, target);
+    return target;
+  }
+  checkCanceled() {
+    if (this.deps.signal.aborted) throw runCanceledError();
+  }
+  runTempDir() {
+    this.tempDir ??= (async () => {
+      const { mkdtemp } = await import("fs/promises");
+      const { tmpdir } = await import("os");
+      const { join } = await import("path");
+      return mkdtemp(join(tmpdir(), "hobots-files-"));
+    })();
+    return this.tempDir;
+  }
+  async resolveTarget(ref, dest, destIsDir) {
+    const { mkdir, mkdtemp, stat } = await import("fs/promises");
+    const { dirname, join, resolve: resolve2 } = await import("path");
+    const name = safeFileName(ref.name, "arquivo");
+    if (dest === void 0) {
+      return join(await mkdtemp(join(await this.runTempDir(), "f-")), name);
+    }
+    const isDir = destIsDir || dest.endsWith("/") || dest.endsWith("\\") || (await stat(dest).catch(() => void 0))?.isDirectory() === true;
+    if (isDir) {
+      await mkdir(dest, { recursive: true });
+      return resolve2(dest, name);
+    }
+    await mkdir(dirname(resolve2(dest)), { recursive: true });
+    return resolve2(dest);
+  }
+  /** storage 's3': URL pré-assinada → GET em streaming → confere o tamanho → só então DELETE. */
+  async downloadS3(ref, target) {
+    const { api, runId, signal } = this.deps;
+    let expected;
+    let url;
+    try {
+      const info = await api.requestFileDownload(runId, ref.id, signal);
+      expected = info.size >= 0 ? info.size : ref.size;
+      url = info.url;
+    } catch (error) {
+      throw this.translate(error, ref);
+    }
+    const { open, rename, rm } = await import("fs/promises");
+    const part = `${target}.part`;
+    const idleTimeoutMs = this.deps.idleTimeoutMs ?? FILE_DOWNLOAD_IDLE_TIMEOUT_MS;
+    const controller = new AbortController();
+    let timedOut = false;
+    let timer;
+    const arm = () => {
+      clearTimeout(timer);
+      timer = setTimeout(() => {
+        timedOut = true;
+        controller.abort();
+      }, idleTimeoutMs);
+    };
+    const onCancel = () => controller.abort();
+    signal.addEventListener("abort", onCancel, { once: true });
+    try {
+      arm();
+      const response = await api.fetchFile(url, controller.signal);
+      const handle = await open(part, "w");
+      let written = 0;
+      try {
+        const reader = response.body?.getReader();
+        const stopReading = () => void reader?.cancel().catch(() => void 0);
+        controller.signal.addEventListener("abort", stopReading, { once: true });
+        for (; ; ) {
+          const chunk = reader ? await reader.read() : { done: true, value: void 0 };
+          if (chunk.done) break;
+          arm();
+          written += chunk.value.byteLength;
+          if (written > expected) {
+            stopReading();
+            break;
+          }
+          await handle.write(chunk.value);
+        }
+      } finally {
+        await handle.close();
+      }
+      if (written !== expected) {
+        throw new Error(`tamanho divergente no download de "${ref.name}": recebidos ${written} bytes, esperados ${expected}`);
+      }
+      await rename(part, target);
+    } catch (error) {
+      await rm(part, { force: true });
+      if (signal.aborted) throw runCanceledError();
+      if (timedOut) {
+        throw new Error(`download de "${ref.name}" parado h\xE1 ${idleTimeoutMs / 1e3}s \u2014 tente de novo`);
+      }
+      throw this.translate(error, ref);
+    } finally {
+      clearTimeout(timer);
+      signal.removeEventListener("abort", onCancel);
+    }
+    try {
+      await api.confirmFileDownload(runId, ref.id);
+    } catch (error) {
+      this.deps.warn(`arquivo "${ref.name}" baixado, mas a confirma\xE7\xE3o ao servidor falhou: ${String(error)}`);
+    }
+  }
+  /** storage 'local': copia o único arquivo de `$HOBOTS_LOCAL_FILES_DIR/<id>/` e apaga a pasta de origem. */
+  async copyLocal(ref, target) {
+    const base = process.env[LOCAL_FILES_DIR_ENV];
+    if (!base) throw unavailableLocal(ref);
+    const { copyFile, readdir, rename, rm, stat } = await import("fs/promises");
+    const { join, resolve: resolve2, sep } = await import("path");
+    const root = resolve2(base);
+    const folder = resolve2(root, ref.id);
+    if (!isInsideDir(root, folder, sep) || !UUID_RE.test(ref.id)) {
+      throw new Error(`id de arquivo local inv\xE1lido: ${JSON.stringify(ref.id)}`);
+    }
+    let names;
+    try {
+      names = (await readdir(folder, { withFileTypes: true })).filter((entry) => entry.isFile()).map((entry) => entry.name);
+    } catch (error) {
+      if (errorCode(error) === "ENOENT" || errorCode(error) === "ENOTDIR") throw unavailableLocal(ref);
+      throw error;
+    }
+    if (names.length === 0) throw unavailableLocal(ref);
+    if (names.length > 1) throw new Error(`pasta do arquivo "${ref.name}" tem ${names.length} arquivos \u2014 esperado 1`);
+    this.checkCanceled();
+    const part = `${target}.part`;
+    try {
+      await copyFile(join(folder, names[0]), part);
+      const { size } = await stat(part);
+      if (size !== ref.size) {
+        throw new Error(`tamanho divergente na c\xF3pia de "${ref.name}": copiados ${size} bytes, esperados ${ref.size}`);
+      }
+      await rename(part, target);
+    } catch (error) {
+      await rm(part, { force: true });
+      throw error;
+    }
+    await rm(folder, { recursive: true, force: true });
+  }
+  translate(error, ref) {
+    if (this.deps.signal.aborted) return runCanceledError();
+    if (error instanceof TasksApiError && error.status === 410) {
+      return new TasksApiError(`arquivo "${ref.name}" j\xE1 baixado ou expirado`, 410);
+    }
+    if (error instanceof TasksApiError && error.status === 404) {
+      return new TasksApiError(`arquivo "${ref.name}" n\xE3o encontrado nesta execu\xE7\xE3o`, 404);
+    }
+    return error;
+  }
+};
+
 // src/retry.ts
 var DEFAULT_RETRIES = 3;
 var DEFAULT_DELAY_MS = 1e3;
@@ -1446,12 +1770,14 @@ var RunReporter = class {
     );
     const signal = this.abortController.signal;
     const sleep2 = (ms) => cancelableSleep(ms, signal);
+    this.fileStore = new RunFileStore({ api, runId, params, signal, warn: (message) => this.log("warning", message) });
     this.context = {
       runId,
       params,
       log,
       items,
       progress,
+      files: this.fileStore.files,
       transaction: tx,
       flush: (timeoutMs) => this.flush(timeoutMs),
       signal,
@@ -1506,6 +1832,12 @@ var RunReporter = class {
   progressDirty = false;
   progressTimer;
   progressWarned = false;
+  /** Arquivos do formulário desta run (`ctx.files`) — a pasta temporária é apagada no fim. */
+  fileStore;
+  /** Apaga as cópias de arquivo que ficaram na pasta temporária da run. Nunca lança. */
+  cleanupFiles() {
+    return this.fileStore.cleanup();
+  }
   get isDead() {
     return this.dead;
   }
@@ -2368,6 +2700,7 @@ async function executeRun(input) {
     }
     await reporter.finalize();
   } finally {
+    await reporter.cleanupFiles();
     tracker.remove(reporter);
   }
 }
@@ -2823,7 +3156,9 @@ function resolveRunOptions(options, mode, logger) {
 }
 function instanceInfo(rt) {
   return {
+    /* v8 ignore start -- defensivo: o boot define o instanceId antes de qualquer poll/criação de run */
     instance_id: rt.instanceId ?? "unknown",
+    /* v8 ignore stop */
     version: SDK_VERSION,
     host: hostname(),
     // ambiente da instância: junto do heartbeat, é como o servidor sabe onde o robô roda
@@ -3000,6 +3335,14 @@ var fallbackItems = {
   each: (list, handler, options = {}) => eachItem(list, handler, options, fallbackEachSink)
 };
 var fallbackProgress = { total: noop, advance: noop, set: noop, current: 0, snapshot: null };
+var outsideRunFiles = () => Promise.reject(new Error("hobots.files s\xF3 baixa arquivos dentro de uma execu\xE7\xE3o (handler do register()/start())"));
+var fallbackFiles = {
+  list: () => [],
+  get: () => void 0,
+  download: outsideRunFiles,
+  downloadAll: outsideRunFiles,
+  read: outsideRunFiles
+};
 var neverAborts = new AbortController().signal;
 var detachedTransaction;
 function resolve(member) {
@@ -3021,6 +3364,7 @@ var hobots = Object.defineProperties({}, {
   log: getter("log", () => fallbackLog),
   items: getter("items", () => fallbackItems),
   progress: getter("progress", () => fallbackProgress),
+  files: getter("files", () => fallbackFiles),
   transaction: getter("transaction", () => detachedTransaction ??= new Transaction(void 0, "hobots.detached")),
   signal: getter("signal", () => neverAborts),
   throwIfCanceled: method(() => resolve("throwIfCanceled")?.throwIfCanceled()),
@@ -3041,7 +3385,8 @@ var hobots = Object.defineProperties({}, {
   }),
   close: method((timeoutMs) => close(timeoutMs)),
   captureException: method((error, hint) => captureException(error, hint)),
-  image: method(image)
+  image: method(image),
+  isFileRef: method(isFileRef)
 });
 function installGlobalHobots() {
   if (globalThis.hobots === hobots) return;
@@ -3053,6 +3398,7 @@ var close2 = hobots.close;
 var captureException2 = hobots.captureException;
 var retry = hobots.retry;
 var image2 = hobots.image;
+var isFileRef2 = hobots.isFileRef;
 
 // src/index.ts
 var src_default = hobots;
@@ -3062,6 +3408,7 @@ export {
   src_default as default,
   hobots,
   image2 as image,
+  isFileRef2 as isFileRef,
   register2 as register,
   retry,
   start2 as start