hobots 4.2.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.2.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";
 }
@@ -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;
@@ -917,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;
@@ -1174,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);
@@ -1200,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) {
@@ -1265,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;
@@ -1716,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);
       },
@@ -1809,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).
@@ -2120,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;
@@ -2133,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})`);
@@ -2417,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;
   }
   /**
@@ -2441,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;
@@ -2452,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(
@@ -2548,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;
@@ -2560,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;
@@ -2601,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) {
@@ -2633,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",
@@ -2695,6 +2808,7 @@ 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)}`);
     }
@@ -2704,6 +2818,11 @@ async function executeRun(input) {
     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;
@@ -2895,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;
@@ -3100,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 });
@@ -3120,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,
@@ -3197,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();
@@ -3216,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;
@@ -3235,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);
 }
@@ -3275,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;
@@ -3284,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`);
@@ -3401,6 +3628,7 @@ var image2 = hobots.image;
 var isFileRef2 = hobots.isFileRef;
 
 // src/index.ts
+loadDotenv();
 var src_default = hobots;
 export {
   captureException2 as captureException,