hobots 4.1.0 → 4.5.0

package/dist/index.js

@@ -2,62 +2,9 @@ import {
   WIRE_LIMITS
 } from "./chunk-HKCDMUA3.js";
 
-// src/stacktrace.ts
-var MAX_FRAMES = 50;
-var MAX_FILENAME_CHARS = 1024;
-var FRAME_RE = /^\s*at\s+(?:async\s+)?(?:(.+?)\s+\()?(.+?)\)?$/;
-var LOCATION_RE = /^(.*?):(\d+):(\d+)$/;
-function isInApp(filename) {
-  if (!filename) return false;
-  if (filename.startsWith("node:")) return false;
-  if (filename.startsWith("internal/")) return false;
-  if (filename.includes("node_modules")) return false;
-  if (filename === "<anonymous>") return false;
-  return true;
-}
-function parseStacktrace(stack) {
-  if (!stack) return [];
-  const frames = [];
-  for (const line of stack.split("\n")) {
-    if (frames.length >= MAX_FRAMES) break;
-    const match = FRAME_RE.exec(line);
-    if (!match || !line.trimStart().startsWith("at ")) continue;
-    const [, fn, location] = match;
-    const loc = LOCATION_RE.exec(location ?? "");
-    const filename = loc ? loc[1] : location;
-    frames.push({
-      function: fn || "<anonymous>",
-      filename: filename ? filename.slice(0, MAX_FILENAME_CHARS) : void 0,
-      lineno: loc?.[2] ? Number(loc[2]) : void 0,
-      colno: loc?.[3] ? Number(loc[3]) : void 0,
-      in_app: isInApp(filename)
-    });
-  }
-  return frames;
-}
-
-// src/scrub.ts
-var SECRET_PATTERNS = [
-  // client secret da Hobots
-  [/hb_[a-f0-9]{16,}/gi, "[REDACTED]"],
-  // tokens bearer em headers/mensagens
-  [/\b(authorization:?\s*)?bearer\s+[a-z0-9._~+/=-]{8,}/gi, "Bearer [REDACTED]"],
-  // chaves no formato sk-… (OpenAI e afins)
-  [/\bsk-[a-z0-9_-]{16,}\b/gi, "[REDACTED]"],
-  // credenciais embutidas em URL (https://user:pass@host)
-  [/\/\/[^/\s:@]+:[^/\s@]+@/g, "//[REDACTED]@"]
-];
-function scrubSecrets(text) {
-  let out = text;
-  for (const [pattern, replacement] of SECRET_PATTERNS) {
-    out = out.replace(pattern, replacement);
-  }
-  return out;
-}
-
 // src/utils.ts
 var SDK_NAME = "hobots";
-var SDK_VERSION = true ? "4.1.0" : "0.0.0-dev";
+var SDK_VERSION = true ? "4.5.0" : "0.0.0-dev";
 function isNode() {
   return typeof process !== "undefined" && typeof process.versions?.node === "string";
 }
@@ -139,13 +86,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;
@@ -205,6 +152,104 @@ function colorize(text, color) {
   return `${ANSI[color]}${text}${ANSI.reset}`;
 }
 
+// src/env.ts
+var INSTANCE_ID_ENV = "HOBOTS_INSTANCE_ID";
+var ENVIRONMENT_ENV = "HOBOTS_ENVIRONMENT";
+var RUN_ID_ENV = "HOBOTS_RUN_ID";
+var dotenvLoaded = false;
+function loadDotenv() {
+  if (dotenvLoaded) return;
+  dotenvLoaded = true;
+  if (!isNode() || typeof process.loadEnvFile !== "function") return;
+  try {
+    process.loadEnvFile(".env");
+  } catch (err) {
+    const code = err?.code;
+    if (code === "ENOENT") return;
+    console.warn(`[hobots] n\xE3o foi poss\xEDvel ler o .env da pasta de trabalho (${typeof code === "string" ? code : "erro desconhecido"}) \u2014 seguindo s\xF3 com as vari\xE1veis do ambiente`);
+  }
+}
+function resolveInstanceId(option) {
+  const fromOption = option?.trim();
+  if (fromOption) return fromOption;
+  if (typeof process === "undefined" || !process.env) return void 0;
+  return process.env[INSTANCE_ID_ENV]?.trim() || void 0;
+}
+function resolveRunId(option) {
+  const fromOption = option?.trim();
+  if (fromOption) return fromOption;
+  if (typeof process === "undefined" || !process.env) return void 0;
+  return process.env[RUN_ID_ENV]?.trim() || void 0;
+}
+function resolveEnvironmentOption(option) {
+  const fromOption = option?.trim();
+  if (fromOption) return fromOption;
+  if (typeof process === "undefined" || !process.env) return void 0;
+  return process.env[ENVIRONMENT_ENV]?.trim() || void 0;
+}
+async function fallbackInstanceId() {
+  if (!isNode()) return "browser";
+  try {
+    const os = await import("os");
+    return os.hostname() || "unknown-host";
+  } catch {
+    return "unknown-host";
+  }
+}
+
+// src/stacktrace.ts
+var MAX_FRAMES = 50;
+var MAX_FILENAME_CHARS = 1024;
+var FRAME_RE = /^\s*at\s+(?:async\s+)?(?:(.+?)\s+\()?(.+?)\)?$/;
+var LOCATION_RE = /^(.*?):(\d+):(\d+)$/;
+function isInApp(filename) {
+  if (!filename) return false;
+  if (filename.startsWith("node:")) return false;
+  if (filename.startsWith("internal/")) return false;
+  if (filename.includes("node_modules")) return false;
+  if (filename === "<anonymous>") return false;
+  return true;
+}
+function parseStacktrace(stack) {
+  if (!stack) return [];
+  const frames = [];
+  for (const line of stack.split("\n")) {
+    if (frames.length >= MAX_FRAMES) break;
+    const match = FRAME_RE.exec(line);
+    if (!match || !line.trimStart().startsWith("at ")) continue;
+    const [, fn, location] = match;
+    const loc = LOCATION_RE.exec(location ?? "");
+    const filename = loc ? loc[1] : location;
+    frames.push({
+      function: fn || "<anonymous>",
+      filename: filename ? filename.slice(0, MAX_FILENAME_CHARS) : void 0,
+      lineno: loc?.[2] ? Number(loc[2]) : void 0,
+      colno: loc?.[3] ? Number(loc[3]) : void 0,
+      in_app: isInApp(filename)
+    });
+  }
+  return frames;
+}
+
+// src/scrub.ts
+var SECRET_PATTERNS = [
+  // client secret da Hobots
+  [/hb_[a-f0-9]{16,}/gi, "[REDACTED]"],
+  // tokens bearer em headers/mensagens
+  [/\b(authorization:?\s*)?bearer\s+[a-z0-9._~+/=-]{8,}/gi, "Bearer [REDACTED]"],
+  // chaves no formato sk-… (OpenAI e afins)
+  [/\bsk-[a-z0-9_-]{16,}\b/gi, "[REDACTED]"],
+  // credenciais embutidas em URL (https://user:pass@host)
+  [/\/\/[^/\s:@]+:[^/\s@]+@/g, "//[REDACTED]@"]
+];
+function scrubSecrets(text) {
+  let out = text;
+  for (const [pattern, replacement] of SECRET_PATTERNS) {
+    out = out.replace(pattern, replacement);
+  }
+  return out;
+}
+
 // src/eventbuilder.ts
 var MAX_EXCEPTION_VALUE_CHARS = 8192;
 function eventFromException(error, type = "error") {
@@ -356,6 +401,10 @@ function clipFingerprint(fingerprint) {
   if (fingerprint === void 0) return void 0;
   return fingerprint.slice(0, MAX_FINGERPRINT_ITEMS).map((item) => truncate(String(item), MAX_FINGERPRINT_ITEM_CHARS));
 }
+var captured = /* @__PURE__ */ new WeakSet();
+function wasCaptured(error) {
+  return typeof error === "object" && error !== null && captured.has(error);
+}
 function runtimeContexts() {
   if (isNode()) {
     return {
@@ -407,6 +456,7 @@ var Client = class {
     return `Client { baseUrl: '${this.#config.baseUrl}' }`;
   }
   captureException(error, hint) {
+    if (typeof error === "object" && error !== null) captured.add(error);
     return this.captureEvent(eventFromException(error, hint?.type ?? "error"), hint);
   }
   captureEvent(event, hint) {
@@ -514,12 +564,12 @@ function resolveConfig(options = {}, prefix = "[hobots]") {
   const origin = fromOption ? "clientSecret" : `env ${CLIENT_SECRET_ENV}`;
   if (!key) {
     throw new Error(
-      `${prefix} Client Secret ausente \u2014 defina a env ${CLIENT_SECRET_ENV} (ou passe clientSecret nas op\xE7\xF5es do register/start); copie o Client Secret do agente em Configura\xE7\xF5es \u2192 Agentes`
+      `${prefix} Client Secret ausente \u2014 defina a env ${CLIENT_SECRET_ENV} (ou passe clientSecret nas op\xE7\xF5es do register/start); copie o Client Secret na Central: abra o agente \u2192 Configura\xE7\xF5es \u2192 agente \u2192 aba credenciais`
     );
   }
   if (!SECRET_PATTERN.test(key)) {
     throw new Error(
-      `${prefix} ${origin} com formato inv\xE1lido (${key.length} caracteres) \u2014 esperado "hb_" + 64 hex; copie o Client Secret do agente em Configura\xE7\xF5es \u2192 Agentes`
+      `${prefix} ${origin} com formato inv\xE1lido (${key.length} caracteres) \u2014 esperado "hb_" + 64 hex; copie o Client Secret na Central: abra o agente \u2192 Configura\xE7\xF5es \u2192 agente \u2192 aba credenciais`
     );
   }
   const baseUrl = validateBaseUrl(envBaseUrl() ?? DEFAULT_BASE_URL, prefix);
@@ -531,31 +581,6 @@ function resolveConfig(options = {}, prefix = "[hobots]") {
   };
 }
 
-// src/env.ts
-var INSTANCE_ID_ENV = "HOBOTS_INSTANCE_ID";
-var ENVIRONMENT_ENV = "HOBOTS_ENVIRONMENT";
-function resolveInstanceId(option) {
-  const fromOption = option?.trim();
-  if (fromOption) return fromOption;
-  if (typeof process === "undefined" || !process.env) return void 0;
-  return process.env[INSTANCE_ID_ENV]?.trim() || void 0;
-}
-function resolveEnvironmentOption(option) {
-  const fromOption = option?.trim();
-  if (fromOption) return fromOption;
-  if (typeof process === "undefined" || !process.env) return void 0;
-  return process.env[ENVIRONMENT_ENV]?.trim() || void 0;
-}
-async function fallbackInstanceId() {
-  if (!isNode()) return "browser";
-  try {
-    const os = await import("os");
-    return os.hostname() || "unknown-host";
-  } catch {
-    return "unknown-host";
-  }
-}
-
 // src/heartbeat.ts
 var DEFAULT_INTERVAL_MS = WIRE_LIMITS.HEARTBEAT_DEFAULT_INTERVAL_MS;
 var MIN_REPORTED_INTERVAL_MS = WIRE_LIMITS.HEARTBEAT_MIN_INTERVAL_MS;
@@ -831,6 +856,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);
@@ -916,6 +942,42 @@ var TasksApi = class {
       created_at: typeof body.created_at === "string" ? body.created_at : (/* @__PURE__ */ new Date()).toISOString()
     };
   }
+  /**
+   * Anexa o processo a uma run já reivindicada para esta instância (env HOBOTS_RUN_ID):
+   * POST /v1/runs/:id/start. Um request só — quem decide o retry é o AttachedRunner.
+   * 404 (não existe) e 409 (cancelada, já iniciada ou de outra instância) viram
+   * TasksApiError com o status.
+   */
+  async startRun(runId, request, signal) {
+    const { signal: timeoutSignal, cleanup } = withTimeoutSignal(UPDATE_TIMEOUT_MS, signal);
+    let response;
+    try {
+      response = await fetch(`${this.baseUrl}/${encodeURIComponent(runId)}/start`, {
+        redirect: "error",
+        method: "POST",
+        headers: this.headers(),
+        body: JSON.stringify(request),
+        signal: timeoutSignal
+      });
+    } finally {
+      cleanup();
+    }
+    if (!response.ok) {
+      throw new TasksApiError(`in\xEDcio da run falhou (HTTP ${response.status})`, response.status);
+    }
+    const body = await response.json().catch(() => null);
+    if (typeof body?.id !== "string") {
+      throw new TasksApiError("resposta inv\xE1lida do in\xEDcio da run (id ausente)", 0);
+    }
+    const form = body.form;
+    return {
+      id: body.id,
+      params: body.params && typeof body.params === "object" && !Array.isArray(body.params) ? body.params : {},
+      form: typeof form?.id === "string" && typeof form.name === "string" ? { id: form.id, name: form.name } : null,
+      source: typeof body.source === "string" ? body.source : "hobots",
+      created_at: typeof body.created_at === "string" ? body.created_at : (/* @__PURE__ */ new Date()).toISOString()
+    };
+  }
   /** Nunca confia no shape da resposta: runs malformadas são descartadas e o `max` é respeitado. */
   parsePollResponse(body, max) {
     const runs = body?.runs;
@@ -1018,7 +1080,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 +1120,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 +1142,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
@@ -1099,7 +1235,7 @@ var Backoff = class {
       this.authFailures++;
       if (this.authFailures === 1 || this.authFailures % 10 === 0) {
         this.logger.error(
-          error.status === 402 ? "agente fora do limite do plano (402) \u2014 fa\xE7a upgrade em Plano e cobran\xE7a para reativ\xE1-lo" : "chave rejeitada (401) \u2014 verifique o Client Secret do agente em Configura\xE7\xF5es \u2192 Agentes"
+          error.status === 402 ? "agente fora do limite do plano (402) \u2014 fa\xE7a upgrade em Plano e cobran\xE7a para reativ\xE1-lo" : "chave rejeitada (401) \u2014 verifique o Client Secret na Central: abra o agente \u2192 Configura\xE7\xF5es \u2192 agente \u2192 aba credenciais"
         );
       }
       return Math.max(this.floorMs, AUTH_FAILURE_INTERVAL_MS);
@@ -1125,6 +1261,9 @@ var TERMINAL_ERROR_NAMES = /* @__PURE__ */ new Set(["RunCanceled", "AbortError",
 function isTerminalError(error) {
   return error instanceof Error && TERMINAL_ERROR_NAMES.has(error.name);
 }
+function isCancellation(error) {
+  return error instanceof Error && (error.name === "RunCanceled" || error.name === "AbortError");
+}
 
 // src/tasks/each.ts
 function thrownMessage(error) {
@@ -1190,16 +1329,15 @@ async function eachItem(list, handler, options, sink) {
       if (!handle.reported) handle.succeeded();
     } catch (error) {
       if (isTerminalError(error) || sink.isAborted()) {
-        step?.setStatus("cancelled");
-        step?.finish();
+        step?.setStatus("cancelled").succeeded();
         throw error;
       }
       const message = thrownMessage(error);
       if (!handle.reported) handle.failed(message);
-      step?.setError(error);
+      step?.failed(error);
       sink.logError(`item ${description} falhou: ${message}`);
     }
-    step?.finish();
+    step?.succeeded();
     if (options.progress !== false) sink.advance();
     result.total += 1;
     result[handle.status ?? "succeeded"] += 1;
@@ -1208,6 +1346,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;
@@ -1392,7 +1779,7 @@ var RunReporter = class {
     tx.setStepGuard(checkCanceled);
     const eachSink = {
       report: (status, message, payload, id, image3) => this.addItem(status, message, payload, id, image3),
-      startStep: (op, description) => tx.startChild(op, description),
+      startStep: (op, description) => tx.start(op, description),
       declareTotal: (total) => {
         if (this.progressTotal == null) this.setProgress(this.progressCurrent, total);
       },
@@ -1446,12 +1833,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,
@@ -1483,8 +1872,17 @@ var RunReporter = class {
   itemSeq = 0;
   /** Servidor sem o recurso (404) — para de tentar (e de avisar) nesta run. */
   itemsUnsupported = false;
-  /** Cap de itens por run atingido (client-side ou 429) — degrada com um aviso só. */
+  /**
+   * Cota de itens por run do servidor (429, legado — hoje a api não tem teto de itens) —
+   * degrada com um aviso só.
+   */
   itemsQuotaExceeded = false;
+  /**
+   * Armazenamento do plano cheio (402 `storage_limit`): o lote é descartado e o aviso sai
+   * uma vez por episódio. Os envios continuam — num agente `start()` o espaço pode ser
+   * liberado (ou o plano trocado) sem reiniciar; um lote aceito rearma o aviso.
+   */
+  itemsStorageFull = false;
   /**
    * Só o kill() do exit path fecha os itens — `dead` (run cancelada/finalizada no
    * servidor) NÃO fecha: o servidor aceita itens de run terminal (trabalho já feito).
@@ -1506,6 +1904,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;
   }
@@ -1788,6 +2192,7 @@ var RunReporter = class {
     if (this.itemsUnsupported) return;
     try {
       await this.api.createItems(this.runId, { items: batch });
+      this.itemsStorageFull = false;
     } catch (error) {
       if (error instanceof TasksApiError && error.status === 404) {
         this.itemsUnsupported = true;
@@ -1801,6 +2206,13 @@ var RunReporter = class {
         }
         return;
       }
+      if (error instanceof TasksApiError && error.status === 402) {
+        if (!this.itemsStorageFull) {
+          this.itemsStorageFull = true;
+          this.log("warning", "itens descartados: armazenamento do plano cheio \u2014 libere espa\xE7o ou fa\xE7a upgrade em Plano e cobran\xE7a");
+        }
+        return;
+      }
       if (error instanceof TasksApiError) {
         this.logger.error(`lote de ${batch.length} item(ns) rejeitado pelo servidor:`, error);
         this.log("warning", `${batch.length} item(ns) descartado(s): envio rejeitado pelo servidor (HTTP ${error.status})`);
@@ -2085,16 +2497,19 @@ var Step = class {
     return 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, message, options) {
+  failed(error, message, options) {
+    if (this.endTimestamp) return this;
     this.status = "error";
     const type = error instanceof Error ? error.name : typeof error === "object" && error !== null ? "Error" : void 0;
     const raw = message ?? (error instanceof Error ? error.message || error.name : String(error));
     this.setData("error", { ...type ? { type } : {}, message: stepMessage(raw) });
     if (options?.image !== void 0) this.attachImage(options.image);
+    this.close();
     return this;
   }
   /**
@@ -2109,7 +2524,7 @@ var Step = class {
     if (!id) return;
     this.setData("attachments", [...current, id]);
   }
-  /** Motivo registrado via setStatus(…, message) ou setError — usado no log de FINISH. */
+  /** Motivo registrado via setStatus(…, message) ou failed — usado no log de FINISH. */
   reason() {
     const error = this.data?.error;
     const text = typeof error?.message === "string" ? error.message : this.data?.message;
@@ -2120,10 +2535,18 @@ var Step = class {
     return this;
   }
   /** Step aninhada (filha desta step). */
-  startChild(op, description) {
+  start(op, description) {
     return this.transaction.createStep(this.stepId, op, description);
   }
-  finish() {
+  /**
+   * 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.close();
+    return this;
+  }
+  close() {
     if (this.endTimestamp) return;
     this.endTimestamp = nowISO();
     this.transaction.emit(
@@ -2216,7 +2639,7 @@ var Transaction = class {
   }
   /**
    * 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) {
     this.stepGuard = guard;
@@ -2228,10 +2651,32 @@ var Transaction = class {
     this.emit("step", "start", stepLabel(op, description));
     return step;
   }
-  /** Step direta da transaction. */
-  startChild(op, description) {
+  /** Step direta da transaction. `op` é o nome usado por `succeeded(name)`/`failed(error, name)`. */
+  start(op, description) {
     return this.createStep(this.stepId, op, description);
   }
+  /**
+   * 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) {
+    return this.findOpenStep(name)?.succeeded();
+  }
+  /**
+   * 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, name, options) {
+    return this.findOpenStep(name)?.failed(error, options?.message, options);
+  }
+  findOpenStep(name) {
+    for (let i = this.steps.length - 1; i >= 0; i--) {
+      const step = this.steps[i];
+      if (!step.endTimestamp && (name === void 0 || step.op === name)) return step;
+    }
+    return void 0;
+  }
   setTag(key, value) {
     this.tags[key] = value;
     return this;
@@ -2269,7 +2714,7 @@ var Transaction = class {
         remaining.push(step);
       }
     }
-    for (const step of batch) step.finish();
+    for (const step of batch) step.succeeded();
     this.steps.splice(0, this.steps.length, ...remaining);
     if (this.client) {
       for (let i = 0; i < batch.length; i += MAX_STEPS) {
@@ -2301,7 +2746,7 @@ var Transaction = class {
   finish() {
     if (this.finished) return;
     this.finished = true;
-    for (const step of this.steps) step.finish();
+    for (const step of this.steps) step.succeeded();
     const endTimestamp = nowISO();
     this.emit(
       "transaction",
@@ -2363,14 +2808,21 @@ async function executeRun(input) {
       await reporter.finalizeItems();
       tx.setStatus("error");
       tx.finish();
+      captureRunFailure(client, error, reporter);
       reporter.reportFailure(toRunError(error));
       logger.debug(`run ${run.id} falhou: ${String(error)}`);
     }
     await reporter.finalize();
   } finally {
+    await reporter.cleanupFiles();
     tracker.remove(reporter);
   }
 }
+function captureRunFailure(client, error, reporter) {
+  if (!client?.options.captureRunErrors) return;
+  if (reporter.isDead || isCancellation(error) || wasCaptured(error)) return;
+  client.captureException(error, { type: "error", tags: { mechanism: "run_handler", run_id: reporter.runId } });
+}
 function warnIncompleteProgress(reporter) {
   const snapshot = reporter.context.progress.snapshot;
   if (!snapshot || snapshot.current >= snapshot.total) return;
@@ -2562,6 +3014,86 @@ var TaskAgent = class {
   }
 };
 
+// src/tasks/attached.ts
+var START_RETRY_DELAYS_MS = [1e3, 4e3, 16e3];
+function isTransient(error) {
+  if (!(error instanceof TasksApiError)) return true;
+  return error.status >= 500 || error.status === 429;
+}
+function describeRejection(runId, error) {
+  if (error instanceof TasksApiError && error.status === 404) {
+    return `run ${runId} n\xE3o existe na plataforma (404) \u2014 nada a executar`;
+  }
+  if (error instanceof TasksApiError && error.status === 409) {
+    return `run ${runId} n\xE3o pode ser iniciada (409: cancelada, j\xE1 iniciada ou de outra inst\xE2ncia) \u2014 nada a executar`;
+  }
+  return `n\xE3o foi poss\xEDvel iniciar a run ${runId} (${String(error)}) \u2014 nada a executar`;
+}
+var AttachedRunner = class {
+  constructor(runId, handler, deps) {
+    this.runId = runId;
+    this.handler = handler;
+    this.deps = deps;
+    this.done = new Promise((resolve2) => {
+      this.resolveDone = resolve2;
+    });
+  }
+  runId;
+  handler;
+  deps;
+  abort = new AbortController();
+  /** Resolve quando a run terminou (ou não pôde ser iniciada, ou o runner foi parado antes). */
+  done;
+  resolveDone;
+  async run() {
+    try {
+      const run = await this.startRun();
+      if (!run) return;
+      this.deps.logger.debug(`run ${run.id} iniciada (HOBOTS_RUN_ID)`);
+      await executeRun({
+        run,
+        handler: this.handler,
+        api: this.deps.api,
+        client: this.deps.client,
+        logger: this.deps.logger,
+        tracker: this.deps.tracker
+      });
+    } catch (error) {
+      this.deps.logger.error("erro inesperado na execu\xE7\xE3o do agente:", error);
+    } finally {
+      this.resolveDone();
+    }
+  }
+  /** Desiste de iniciar a run (close() antes da plataforma responder). Uma run já iniciada segue pelo tracker. */
+  stop() {
+    this.abort.abort();
+  }
+  async startRun() {
+    for (let attempt = 0; ; attempt++) {
+      if (this.abort.signal.aborted) return void 0;
+      try {
+        return await this.deps.api.startRun(this.runId, { instance: this.deps.instanceInfo() }, this.abort.signal);
+      } catch (error) {
+        if (this.abort.signal.aborted) return void 0;
+        if (!isTransient(error)) {
+          this.deps.logger.error(describeRejection(this.runId, error));
+          return void 0;
+        }
+        const delay = START_RETRY_DELAYS_MS[attempt];
+        if (delay === void 0) {
+          this.deps.logger.error(
+            `n\xE3o foi poss\xEDvel iniciar a run ${this.runId} ap\xF3s ${attempt + 1} tentativas (${String(error)}) \u2014 desistindo`
+          );
+          return void 0;
+        }
+        const wait = jitter(delay);
+        this.deps.logger.warn(`in\xEDcio da run ${this.runId} falhou (${String(error)}), pr\xF3xima tentativa em ${wait}ms`);
+        await abortableSleep(wait, this.abort.signal);
+      }
+    }
+  }
+};
+
 // src/tasks/item-columns.ts
 var KEY_RE = /^[a-zA-Z0-9_.-]{1,100}$/;
 var MAX_COLUMNS = WIRE_LIMITS.MAX_ITEM_COLUMNS;
@@ -2767,11 +3299,18 @@ function hostname() {
   return process.env.HOSTNAME || process.env.COMPUTERNAME || void 0;
 }
 function createRuntime(options, handler) {
+  loadDotenv();
   const config = resolveConfig({ clientSecret: options.clientSecret });
   const logger = makeLogger(options.debug ?? false);
   const environment = resolveEnvironmentOption(options.environment);
   const client = new Client(
-    { environment, release: options.release, tags: options.tags, debug: options.debug },
+    {
+      environment,
+      release: options.release,
+      tags: options.tags,
+      debug: options.debug,
+      captureRunErrors: options.captureUnhandled !== false
+    },
     config
   );
   const api = new TasksApi({ baseUrl: config.runsBaseUrl, key: config.key, logger });
@@ -2787,6 +3326,8 @@ function createRuntime(options, handler) {
     heartbeat: void 0,
     agent: void 0,
     local: void 0,
+    attached: void 0,
+    runId: void 0,
     instanceId: resolveInstanceId(options.instanceId),
     environment,
     pollIntervalMs: void 0,
@@ -2823,7 +3364,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
@@ -2862,6 +3405,20 @@ function launchLocal(rt) {
   rt.local = runner;
   void runner.run();
 }
+function launchAttached(rt, runId) {
+  const runner = new AttachedRunner(runId, rt.handler, {
+    api: rt.api,
+    client: rt.client,
+    logger: rt.logger,
+    tracker: rt.tracker,
+    instanceInfo: () => instanceInfo(rt)
+  });
+  rt.attached = runner;
+  void runner.run();
+  void runner.done.then(() => {
+    if (runtime === rt) void close();
+  });
+}
 async function boot(rt) {
   if (!rt.instanceId) {
     const id = await fallbackInstanceId();
@@ -2881,8 +3438,9 @@ async function boot(rt) {
   if (rt.options.installExitHandlers !== false) {
     rt.uninstallShutdown = installShutdownHandlers(rt.tracker);
   }
-  if (rt.handler.mode === "remote") ensureAgent(rt).start();
-  else launchLocal(rt);
+  if (rt.handler.mode === "local") launchLocal(rt);
+  else if (rt.runId) launchAttached(rt, rt.runId);
+  else ensureAgent(rt).start();
 }
 function scheduleBoot(rt) {
   if (rt.bootScheduled) return;
@@ -2900,6 +3458,7 @@ function startAgent(fn, mode, handler, options) {
   const agentHandler = { mode, handler, options: resolveRunOptions(options, mode, logger) };
   const rt = createRuntime(options, agentHandler);
   if (mode === "remote" && options.pollIntervalMs !== void 0) rt.pollIntervalMs = options.pollIntervalMs;
+  if (mode === "remote") rt.runId = resolveRunId(options.runId);
   runtime = rt;
   scheduleBoot(rt);
 }
@@ -2940,7 +3499,9 @@ function captureException(error, hint) {
     const message = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
     forwardAttachment(rt, hint.attachment, message, hint.type ?? "error");
   }
-  return rt.client.captureException(error, hint);
+  const runId = currentReporter()?.runId;
+  const withRun = runId ? { ...hint, tags: { run_id: runId, ...hint?.tags } } : hint;
+  return rt.client.captureException(error, withRun);
 }
 async function close(timeoutMs = 3e4) {
   const rt = runtime;
@@ -2949,6 +3510,7 @@ async function close(timeoutMs = 3e4) {
   await rt.bootPromise;
   if (rt.agent) await rt.agent.stop(0);
   rt.local?.stop();
+  rt.attached?.stop();
   const idle = await rt.tracker.waitIdle(timeoutMs);
   if (!idle) {
     rt.logger.warn(`${rt.tracker.activeCount} run(s) ainda em execu\xE7\xE3o ap\xF3s ${timeoutMs}ms \u2014 abandonando a espera`);
@@ -3000,6 +3562,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 +3591,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 +3612,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,8 +3625,10 @@ var close2 = hobots.close;
 var captureException2 = hobots.captureException;
 var retry = hobots.retry;
 var image2 = hobots.image;
+var isFileRef2 = hobots.isFileRef;
 
 // src/index.ts
+loadDotenv();
 var src_default = hobots;
 export {
   captureException2 as captureException,
@@ -3062,6 +3636,7 @@ export {
   src_default as default,
   hobots,
   image2 as image,
+  isFileRef2 as isFileRef,
   register2 as register,
   retry,
   start2 as start