hobots 4.1.0 → 4.2.0

package/README.md

@@ -110,6 +110,7 @@ A opção passada em `register()`/`start()` tem precedência sobre a env — út
 | `hobots.retry(fn, { retries = 3, delayMs = 1_000, shouldRetry? })` | async-retry ciente do cancelamento da execução. `delayMs` aceita função `(tentativa) => ms`. |
 | `hobots.sleep(ms)` | Espera **cancelável**: rejeita com `RunCanceled` se a execução for cancelada. |
 | `hobots.signal` · `hobots.throwIfCanceled()` | Cancelamento cooperativo manual, para controle fino. |
+| `hobots.files.list()` · `.get(campo)` · `.download(refOuCampo, { dest }?)` · `.downloadAll(campo)` · `.read(refOuCampo)` | **Arquivos dos campos de upload** do formulário: baixa para o disco (ou para a memória) e consome na origem — ver [Arquivos do formulário](#arquivos-do-formulário). `isFileRef(valor)` reconhece um arquivo nos params. |
 | `hobots.runId` · `hobots.params` | Identidade da execução atual. |
 | `hobots.register(...)` · `hobots.start(...)` · `hobots.close(timeoutMs?)` | Ciclo de vida do processo. |
 
@@ -117,6 +118,35 @@ O handler também recebe o mesmo contexto como 2º argumento (`(params, ctx) =>
 
 ---
 
+## Arquivos do formulário
+
+Um campo de **upload** no formulário do agente chega nos `params` como um `FileRef` — `{ id, name, size, contentType, storage }` — ou uma lista deles (campo "vários arquivos"). O bot não precisa saber de onde o arquivo veio: `hobots.files.download` traz para o disco desta máquina e devolve o caminho.
+
+```js
+import { hobots } from 'hobots';
+
+hobots.register(async () => {
+  // campo único: o caminho do arquivo baixado (pasta temporária da execução)
+  const planilha = await hobots.files.download('planilha');
+  await importarPlanilha(planilha);
+
+  // campo "vários arquivos": um caminho por arquivo, na ordem, na pasta escolhida
+  const notas = await hobots.files.downloadAll('notas', { dest: './entrada' });
+  for (const nota of notas) await lancarNota(nota);
+
+  // ou direto em memória (Buffer) — a cópia temporária é apagada
+  const contrato = await hobots.files.read('contrato');
+});
+```
+
+- **Cada arquivo é baixado uma vez.** O download consome a origem: enviado pela Central (`storage: 's3'`), o SDK pede uma URL temporária, baixa em streaming, confere o tamanho e **só então** confirma — o servidor apaga o arquivo na hora; uma segunda tentativa recebe `arquivo "x" já baixado ou expirado` (`TasksApiError` com `status` 410). Escolhido no Studio (`storage: 'local'`), o arquivo nunca sai do computador: o SDK copia de `$HOBOTS_LOCAL_FILES_DIR/<id>/` e apaga a pasta de origem — num bot de outro computador (sem a env ou sem a pasta), o erro é `arquivo "x" enviado pelo Studio de outro computador ou já consumido`.
+- **Falha não perde o arquivo:** rede caiu, tamanho divergente, execução cancelada — nada é confirmado e o `download` pode ser tentado de novo (ex.: dentro de `hobots.retry`).
+- **Onde o arquivo vai parar:** sem `dest`, numa pasta temporária **da execução, apagada quando ela termina** — guarde o que precisar além disso com `dest`. `dest` pasta (existente ou terminada em `/`) recebe o nome original; outro caminho vira o nome do arquivo final.
+- `hobots.files.list()` lista todos os arquivos dos params; `hobots.files.get('campo')` devolve o `FileRef` (ou a lista); `download` aceita o nome do campo ou o próprio `FileRef` (um item da lista, por exemplo). Para campo com vários arquivos use `downloadAll` (o `download('campo')` lança, apontando para ele).
+- Respeita o cancelamento: uma execução cancelada no meio do download lança `RunCanceled` e não consome o arquivo.
+
+---
+
 ## Cancelamento automático
 
 Uma execução cancelada no app **não mata** o handler — o SDK dispara `hobots.signal` e o próximo ponto de parada lança **`RunCanceled`**:
@@ -189,6 +219,7 @@ Sem handler próprio de sinal, um `SIGINT`/`SIGTERM` (ou erro fatal) com execuç
 
 ## Changelog resumido
 
+- **4.2.0** — **arquivos do formulário**: `hobots.files` (`list`, `get`, `download`, `downloadAll`, `read`) e `isFileRef`; tipos `FileRef`, `FileStorage`, `FileDownloadResponse` em `hobots/protocol`.
 - **4.0.0** — **o agente é a própria tarefa** (breaking): `register(handler, options?)`/`start(handler, options?)` **sem slug**; **uma chamada por processo** (a segunda lança); `hobots.task`/`ctx.task` removidos; tipos `TaskHandler`→`RunHandler`, `TaskOptions`→`RunOptions`, `TaskItemsOptions`→`ItemsOptions`; wire: `InstanceInfo.mode` (`on_demand` \| `always_on`) e `InstanceInfo.items` no lugar de `tasks`/`task_items`, endpoints em `/v1/runs/*`; eco no terminal `[hobots] INFO …`. Guia de migração no [CHANGELOG](./CHANGELOG.md).
 - **3.4.0** — `hobots.attach()` removido; o print vai junto do evento: `hobots.image(...)` no último argumento de `log.*`, `{ image }` em itens e steps.
 - **3.1.0** — `hobots.log.*` aceita vários argumentos (como `console.log`); `retries` inválido (`NaN`) cai no default em vez de tentar para sempre; 429 de itens e 429/501/503 de anexo são definitivos (sem esperar a ladder — `quota`/`unsupported` passam a funcionar de fato); timeout **por requisição** nos anexos; truncamento nos limites do servidor (tag 512, fingerprint 10×255, nome de transaction 500, 200 steps, `exception.value` 8192, `filename` 1024); PNG acima de 20 000 px não declara dimensões; PATCH terminal nunca passa de 100 logs.

package/dist/index.cjs

@@ -35,6 +35,7 @@ __export(src_exports, {
   default: () => src_default,
   hobots: () => hobots,
   image: () => image2,
+  isFileRef: () => isFileRef2,
   register: () => register2,
   retry: () => retry,
   start: () => start2
@@ -96,7 +97,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";
 }
@@ -178,13 +179,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;
@@ -896,6 +897,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);
@@ -1083,7 +1085,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);
@@ -1117,7 +1125,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);
@@ -1139,6 +1147,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
@@ -1273,6 +1349,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;
@@ -1511,12 +1836,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,
@@ -1571,6 +1898,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;
   }
@@ -2433,6 +2766,7 @@ async function executeRun(input) {
     }
     await reporter.finalize();
   } finally {
+    await reporter.cleanupFiles();
     tracker.remove(reporter);
   }
 }
@@ -2888,7 +3222,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
@@ -3065,6 +3401,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) {
@@ -3086,6 +3430,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()),
@@ -3106,7 +3451,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;
@@ -3118,6 +3464,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;