hobots 4.0.0 → 4.2.0

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.0.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;
@@ -281,7 +282,6 @@ var protocol_limits_default = {
   MAX_LOGS_PER_PATCH: 100,
   MAX_ERROR_MESSAGE_CHARS: 1e4,
   MAX_ERROR_STACK_CHARS: 2e4,
-  MAX_ITEMS_PER_RUN: 1e4,
   MAX_ITEMS_PER_REQUEST: 500,
   MAX_ITEM_MESSAGE_CHARS: 2e3,
   MAX_ITEM_PAYLOAD_BYTES: 16384,
@@ -897,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);
@@ -1084,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);
@@ -1118,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);
@@ -1140,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
@@ -1274,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;
@@ -1414,7 +1738,6 @@ var MAX_CANCEL_CHECK_INTERVAL_MS = 15e3;
 var MAX_LOG_MESSAGE_CHARS = WIRE_LIMITS.MAX_LOG_MESSAGE_CHARS;
 var MAX_LOGS_PER_PATCH = WIRE_LIMITS.MAX_LOGS_PER_PATCH;
 var FLUSH_AT_BUFFERED = 20;
-var MAX_ITEMS_PER_RUN = WIRE_LIMITS.MAX_ITEMS_PER_RUN;
 var MAX_ITEMS_PER_REQUEST = WIRE_LIMITS.MAX_ITEMS_PER_REQUEST;
 var MAX_ITEM_MESSAGE_CHARS = WIRE_LIMITS.MAX_ITEM_MESSAGE_CHARS;
 var MAX_ITEM_PAYLOAD_BYTES = WIRE_LIMITS.MAX_ITEM_PAYLOAD_BYTES;
@@ -1436,6 +1759,7 @@ var RunReporter = class {
     this.api = api;
     this.runId = runId;
     this.logger = logger;
+    this.tx = tx;
     this.flushIntervalMs = flushIntervalMs ?? DEFAULT_LOG_FLUSH_INTERVAL_MS;
     this.cancelCheckIntervalMs = Math.min(
       MAX_CANCEL_CHECK_INTERVAL_MS,
@@ -1512,13 +1836,16 @@ 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,
       throwIfCanceled: checkCanceled,
       sleep: sleep2,
@@ -1528,6 +1855,7 @@ var RunReporter = class {
   api;
   runId;
   logger;
+  tx;
   context;
   buffer = [];
   dead = false;
@@ -1545,7 +1873,6 @@ var RunReporter = class {
   itemsChain = Promise.resolve();
   itemsTimer;
   itemSeq = 0;
-  itemCount = 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ó. */
@@ -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;
   }
@@ -1668,6 +2001,21 @@ var RunReporter = class {
       this.enqueue({ status: "running", logs: logs.slice(i, i + MAX_LOGS_PER_PATCH) });
     }
   }
+  /**
+   * `hobots.flush()`: o bot decide quando entregar o que já fez — steps raiz finalizadas
+   * viram transactions parciais da run, e itens, logs e progresso pendentes saem já, sem
+   * esperar o throttle. Aguarda a entrega com teto. Nunca lança (pode ir num `finally`).
+   */
+  async flush(timeoutMs = ITEMS_DRAIN_MS) {
+    this.tx.flush();
+    this.flushItems();
+    if (this.progressDirty) this.flushProgress();
+    else this.flushLogs();
+    await Promise.race([
+      Promise.all([this.itemsChain, this.chain, this.tx.drain(timeoutMs)]).catch(() => void 0),
+      new Promise((resolve2) => unrefTimer(setTimeout(resolve2, timeoutMs)))
+    ]);
+  }
   /** Primeiro PATCH (claimed → running). Retorna false se a run já morreu (cancelada). */
   async reportRunning() {
     this.enqueue({ status: "running" });
@@ -1778,14 +2126,6 @@ var RunReporter = class {
    */
   addItem(status, message, payload, id, image3) {
     if (this.itemsClosed || this.itemsUnsupported) return;
-    if (this.itemCount >= MAX_ITEMS_PER_RUN) {
-      if (!this.itemsQuotaExceeded) {
-        this.itemsQuotaExceeded = true;
-        this.log("warning", `itens descartados: limite de ${MAX_ITEMS_PER_RUN} por execu\xE7\xE3o atingido`);
-      }
-      return;
-    }
-    this.itemCount++;
     let scrubbedPayload;
     if (payload) {
       scrubbedPayload = scrubPayloadValue(payload, 0);
@@ -2080,6 +2420,7 @@ function currentRunReporter() {
 }
 
 // src/transaction.ts
+var FLUSH_TRANSACTION_OP = "hobots.run.flush";
 var MAX_STEP_MESSAGE_CHARS = 2e3;
 function stepMessage(text) {
   return truncate(scrubSecrets(text), MAX_STEP_MESSAGE_CHARS);
@@ -2301,6 +2642,60 @@ var Transaction = class {
     this.name = name;
     return this;
   }
+  /**
+   * Envia já as steps raiz finalizadas (e todas as descendentes, fechando as que
+   * ficaram abertas) como transactions parciais da mesma run (`op` hobots.run.flush,
+   * `event_id` novo, até 200 steps cada) e as tira da memória. Steps raiz ainda abertas
+   * ficam para o próximo flush ou para o `finish()`. É assim que um agente sempre
+   * ligado (`start()`), cuja run não termina, entrega as etapas enquanto processa.
+   * Devolve quantas steps foram enviadas.
+   */
+  flush() {
+    if (this.finished) return 0;
+    const ready = /* @__PURE__ */ new Set();
+    for (const step of this.steps) {
+      if (step.parentStepId === this.stepId && step.endTimestamp) ready.add(step.stepId);
+    }
+    if (ready.size === 0) return 0;
+    const batch = [];
+    const remaining = [];
+    for (const step of this.steps) {
+      if (ready.has(step.stepId) || ready.has(step.parentStepId)) {
+        ready.add(step.stepId);
+        batch.push(step);
+      } else {
+        remaining.push(step);
+      }
+    }
+    for (const step of batch) step.finish();
+    this.steps.splice(0, this.steps.length, ...remaining);
+    if (this.client) {
+      for (let i = 0; i < batch.length; i += MAX_STEPS) {
+        const chunk = batch.slice(i, i + MAX_STEPS);
+        const startTimestamp = chunk.reduce((min, step) => step.startTimestamp < min ? step.startTimestamp : min, chunk[0].startTimestamp);
+        const status = chunk.some((step) => step.status === "error") ? "error" : "ok";
+        this.client.sendTransaction(this.payload(uuid4(), FLUSH_TRANSACTION_OP, status, startTimestamp, nowISO(), chunk));
+      }
+    }
+    return batch.length;
+  }
+  /** Entrega já (com teto) o que está na fila do transport — as transactions parciais inclusive. */
+  async drain(timeoutMs) {
+    await this.client?.flush(timeoutMs);
+  }
+  payload(eventId, op, status, startTimestamp, timestamp, steps) {
+    return {
+      event_id: eventId,
+      name: this.name,
+      op,
+      status,
+      start_timestamp: startTimestamp,
+      timestamp,
+      steps: steps.map((step) => step.toJSON()),
+      tags: Object.keys(this.tags).length > 0 ? { ...this.tags } : void 0,
+      run_id: this.runId
+    };
+  }
   finish() {
     if (this.finished) return;
     this.finished = true;
@@ -2315,18 +2710,15 @@ var Transaction = class {
       this.status
     );
     if (!this.client) return;
-    const payload = {
-      event_id: this.eventId,
-      name: this.name,
-      op: this.op,
-      status: this.status,
-      start_timestamp: this.startTimestamp,
-      timestamp: endTimestamp,
-      steps: this.steps.map((step) => step.toJSON()),
-      tags: Object.keys(this.tags).length > 0 ? this.tags : void 0,
-      run_id: this.runId
-    };
-    this.client.sendTransaction(payload);
+    const steps = this.steps;
+    let first = 0;
+    while (steps.length - first > MAX_STEPS) {
+      const chunk = steps.slice(first, first + MAX_STEPS);
+      const status = chunk.some((step) => step.status === "error") ? "error" : "ok";
+      this.client.sendTransaction(this.payload(uuid4(), FLUSH_TRANSACTION_OP, status, chunk[0].startTimestamp, endTimestamp, chunk));
+      first += MAX_STEPS;
+    }
+    this.client.sendTransaction(this.payload(this.eventId, this.op, this.status, this.startTimestamp, endTimestamp, steps.slice(first)));
   }
 };
 
@@ -2374,6 +2766,7 @@ async function executeRun(input) {
     }
     await reporter.finalize();
   } finally {
+    await reporter.cleanupFiles();
     tracker.remove(reporter);
   }
 }
@@ -2829,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
@@ -3006,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) {
@@ -3027,10 +3430,12 @@ 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()),
   sleep: method((ms) => resolve("sleep")?.sleep(ms) ?? sleep(ms)),
+  flush: method((timeoutMs) => resolve("flush")?.flush(timeoutMs) ?? Promise.resolve()),
   retry: method((fn, options) => {
     const reporter = currentReporter();
     return reporter ? reporter.context.retry(fn, options) : retryWithBackoff(fn, options);
@@ -3046,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;
@@ -3058,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;