hobots 4.2.0 → 5.0.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 ? "5.0.0" : "0.0.0-dev";
 function isNode() {
   return typeof process !== "undefined" && typeof process.versions?.node === "string";
 }
@@ -110,8 +57,13 @@ function abortableSleep(ms, signal) {
 function jitter(baseMs) {
   return Math.floor(baseMs / 2 + Math.random() * (baseMs / 2));
 }
+var TRUNCATION_SUFFIX = "\u2026 [truncado]";
 function truncate(value, max) {
-  return value.length > max ? `${value.slice(0, max)}\u2026 [truncado]` : value;
+  return value.length > max ? `${value.slice(0, max)}${TRUNCATION_SUFFIX}` : value;
+}
+function clip(value, max) {
+  if (value.length <= max) return value;
+  return `${value.slice(0, Math.max(0, max - TRUNCATION_SUFFIX.length))}${TRUNCATION_SUFFIX}`;
 }
 function safeString(value) {
   if (typeof value === "string") return value;
@@ -205,6 +157,124 @@ 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 LOCAL_RUN_ENV = "HOBOTS_LOCAL_RUN";
+var RUN_PARAMS_ENV = "HOBOTS_RUN_PARAMS";
+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 isLocalRun() {
+  if (typeof process === "undefined" || !process.env) return false;
+  return process.env[LOCAL_RUN_ENV]?.trim() === "1";
+}
+function resolveLocalRunParams() {
+  const raw = process.env[RUN_PARAMS_ENV]?.trim();
+  if (!raw) return {};
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error(`${RUN_PARAMS_ENV} inv\xE1lido: n\xE3o \xE9 JSON v\xE1lido`);
+  }
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error(`${RUN_PARAMS_ENV} inv\xE1lido: esperado um objeto JSON`);
+  }
+  return parsed;
+}
+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") {
@@ -349,13 +419,26 @@ var MAX_FINGERPRINT_ITEMS = 10;
 var MAX_FINGERPRINT_ITEM_CHARS = 255;
 var MAX_TRANSACTION_NAME_CHARS = 500;
 var MAX_STEPS = 200;
+var MAX_STEP_DESCRIPTION_CHARS = 2048;
+var MAX_STEP_OP_CHARS = 255;
 function clipTags(tags) {
   return Object.fromEntries(Object.entries(tags).map(([key, value]) => [key, truncate(String(value), MAX_TAG_VALUE_CHARS)]));
 }
+function clipStep(step) {
+  return {
+    ...step,
+    ...step.op ? { op: clip(step.op, MAX_STEP_OP_CHARS) } : {},
+    ...step.description ? { description: clip(step.description, MAX_STEP_DESCRIPTION_CHARS) } : {}
+  };
+}
 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 {
@@ -406,11 +489,13 @@ var Client = class {
   [/* @__PURE__ */ Symbol.for("nodejs.util.inspect.custom")]() {
     return `Client { baseUrl: '${this.#config.baseUrl}' }`;
   }
-  captureException(error, hint) {
-    return this.captureEvent(eventFromException(error, hint?.type ?? "error"), hint);
+  /** `contexts` é interno ao SDK (ex.: `contexts.run` com o print do captureException) — o evento ainda pode sobrescrever. */
+  captureException(error, hint, contexts) {
+    if (typeof error === "object" && error !== null) captured.add(error);
+    return this.captureEvent(eventFromException(error, hint?.type ?? "error"), hint, contexts);
   }
-  captureEvent(event, hint) {
-    const final = this.prepareEvent(event, hint);
+  captureEvent(event, hint, contexts) {
+    const final = this.prepareEvent(contexts ? { ...event, contexts: { ...contexts, ...event.contexts } } : event, hint);
     this.transport.enqueue({ type: "event", payload: final });
     return final.event_id;
   }
@@ -433,14 +518,15 @@ var Client = class {
   sendTransaction(payload) {
     let steps = payload.steps;
     if (steps.length > MAX_STEPS) {
-      this.logger.warn(`transaction com ${steps.length} steps \u2014 enviando as primeiras ${MAX_STEPS}`);
+      this.logger.warn(`transaction com ${steps.length} etapas \u2014 enviando as primeiras ${MAX_STEPS}`);
       steps = steps.slice(0, MAX_STEPS);
     }
+    steps = steps.map(clipStep);
     this.transport.enqueue({
       type: "transaction",
       payload: {
         ...payload,
-        name: truncate(payload.name || "(sem nome)", MAX_TRANSACTION_NAME_CHARS),
+        name: clip(payload.name || "(sem nome)", MAX_TRANSACTION_NAME_CHARS),
         steps,
         release: payload.release ?? this.options.release,
         environment: this.resolveEnvironment(payload.environment),
@@ -514,12 +600,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 +617,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 +978,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 +1271,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 +1297,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) {
@@ -1226,11 +1326,11 @@ var ItemHandle = class {
   }
   failed(message, payload, options) {
     this.record("failed", message, payload, options?.image);
-    if (this.step && this.step.status !== "error") this.step.setStatus("error", message);
+    if (this.step && this.step.status !== "error") this.step._setStatus("error", message);
   }
   occurrence(message, payload, options) {
     this.record("occurrence", message, payload, options?.image);
-    if (this.step && this.step.status === "ok") this.step.setStatus("warning", message);
+    if (this.step && this.step.status === "ok") this.step._setStatus("warning", message);
   }
   record(status, message, payload, image3) {
     this.reported = true;
@@ -1261,24 +1361,24 @@ async function eachItem(list, handler, options, sink) {
     const step = sink.startStep(options.op ?? "item", description);
     const handle = new ItemHandle(index, id, step, options.payload?.(element, index), sink);
     try {
-      await handler(element, handle, index);
+      await sink.stepScope(step, async () => handler(element, handle, index));
       if (!handle.reported) handle.succeeded();
     } catch (error) {
       if (isTerminalError(error) || sink.isAborted()) {
-        step?.setStatus("cancelled");
-        step?.finish();
+        step?._setStatus("cancelled")._close();
         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?._close();
     if (options.progress !== false) sink.advance();
     result.total += 1;
     result[handle.status ?? "succeeded"] += 1;
     index += 1;
+    if (options.flush !== false) await sink.flush();
   }
   return result;
 }
@@ -1318,6 +1418,11 @@ function isInsideDir(root, candidate, sep) {
 function unavailableLocal(ref) {
   return new Error(`arquivo "${ref.name}" enviado pelo Studio de outro computador ou j\xE1 consumido`);
 }
+function localRunPath(ref) {
+  if (!isLocalRun()) return void 0;
+  const path = ref.path;
+  return typeof path === "string" && path.trim() !== "" ? path : void 0;
+}
 function errorCode(error) {
   return error?.code;
 }
@@ -1485,8 +1590,16 @@ var RunFileStore = class {
       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. */
+  /**
+   * storage 'local': copia o único arquivo de `$HOBOTS_LOCAL_FILES_DIR/<id>/` e apaga a pasta de
+   * origem. No modo local, um FileRef com `path` copia direto desse caminho, sem apagar a origem.
+   */
   async copyLocal(ref, target) {
+    const direct = localRunPath(ref);
+    if (direct !== void 0) {
+      await this.copyFromPath(ref, direct, target);
+      return;
+    }
     const base = process.env[LOCAL_FILES_DIR_ENV];
     if (!base) throw unavailableLocal(ref);
     const { copyFile, readdir, rename, rm, stat } = await import("fs/promises");
@@ -1520,6 +1633,26 @@ var RunFileStore = class {
     }
     await rm(folder, { recursive: true, force: true });
   }
+  /**
+   * Modo local: cópia do arquivo apontado por `path` (teste roda várias vezes — a fonte fica).
+   * Sem conferência de tamanho: o `size` do FileRef é informativo aqui.
+   */
+  async copyFromPath(ref, path, target) {
+    const { copyFile, rename, rm, stat } = await import("fs/promises");
+    const { resolve: resolve2 } = await import("path");
+    const source = resolve2(path);
+    const info = await stat(source).catch(() => void 0);
+    if (!info?.isFile()) throw new Error(`arquivo "${ref.name}" n\xE3o encontrado em ${path}`);
+    this.checkCanceled();
+    const part = `${target}.part`;
+    try {
+      await copyFile(source, part);
+      await rename(part, target);
+    } catch (error) {
+      await rm(part, { force: true });
+      throw error;
+    }
+  }
   translate(error, ref) {
     if (this.deps.signal.aborted) return runCanceledError();
     if (error instanceof TasksApiError && error.status === 410) {
@@ -1648,6 +1781,11 @@ function printRunLog(level, message) {
   const method2 = level === "warning" ? "warn" : level === "success" ? "info" : level;
   console[method2](line, message);
 }
+var PROGRESS_LINE_PREFIX = "[hobots:progress]";
+var PROGRESS_PRINT_THROTTLE_MS = 250;
+function printRunProgress(current, total) {
+  console.log(`${PROGRESS_LINE_PREFIX} ${current}/${total}`);
+}
 function cancelableSleep(ms, signal) {
   return new Promise((resolve2, reject) => {
     if (signal.aborted) {
@@ -1716,14 +1854,16 @@ 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),
+      stepScope: (step, fn) => tx.scope(step, fn),
       declareTotal: (total) => {
         if (this.progressTotal == null) this.setProgress(this.progressCurrent, total);
       },
       advance: () => this.setProgress(this.progressCurrent + 1, this.progressTotal),
       checkCanceled,
       isAborted: () => this.abortController.signal.aborted,
-      logError: (message) => this.log("error", message)
+      logError: (message) => this.log("error", message),
+      flush: () => this.flush()
     };
     const items = {
       add: (item) => {
@@ -1778,7 +1918,14 @@ var RunReporter = class {
       items,
       progress,
       files: this.fileStore.files,
-      transaction: tx,
+      step: async (name, fn, options) => {
+        const root = tx.currentStep() === void 0;
+        try {
+          return await tx.step(name, fn, { ...options, signal, wait: sleep2, warn: (message) => this.log("warning", message) });
+        } finally {
+          if (options?.flush !== false && root && !signal.aborted) await this.flush();
+        }
+      },
       flush: (timeoutMs) => this.flush(timeoutMs),
       signal,
       throwIfCanceled: checkCanceled,
@@ -1809,8 +1956,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).
@@ -1832,6 +1988,8 @@ var RunReporter = class {
   progressDirty = false;
   progressTimer;
   progressWarned = false;
+  /** Relógio do último eco `[hobots:progress]` no terminal (throttle do eco, não do wire). */
+  progressLastPrint = 0;
   /** 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. */
@@ -1882,15 +2040,17 @@ var RunReporter = class {
   /**
    * Linha de log da run com eco no terminal. `image` (opcional) vira o anexo da linha:
    * o id entra na entrada ANTES de qualquer I/O — é isso que mantém a ordem dos logs
-   * intacta e o handler livre da latência do upload.
+   * intacta e o handler livre da latência do upload. Devolve o id do anexo (quando houve
+   * imagem e ela não foi descartada) — o `captureException` o leva ao evento da issue.
    */
   log(level, message, image3) {
-    if (this.dead) return;
+    if (this.dead) return void 0;
     const scrubbed = scrubSecrets(safeString(message));
     const ts = nowISO();
     const attachmentId = image3 === void 0 ? void 0 : this.queueAttachment(image3, ts);
     printRunLog(level, attachmentId ? `${scrubbed} [imagem]` : scrubbed);
     this.push(level, scrubbed, true, attachmentId ? [attachmentId] : void 0, ts);
+    return attachmentId;
   }
   /** Bufferiza uma entrada de log sem eco no terminal (cap, truncate, flush). */
   push(level, message, alreadyScrubbed = false, attachments, ts = nowISO()) {
@@ -1936,7 +2096,7 @@ var RunReporter = class {
     }
   }
   /**
-   * `hobots.flush()`: o bot decide quando entregar o que já fez — steps raiz finalizadas
+   * `hobots.flush()`: o bot decide quando entregar o que já fez — etapas 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`).
    */
@@ -1994,10 +2154,16 @@ var RunReporter = class {
     }
     const safeCurrent = Number.isFinite(current) ? Math.max(0, Math.floor(current)) : this.progressCurrent;
     const next = total == null ? safeCurrent : Math.min(safeCurrent, total);
-    if (next === this.progressCurrent && total === this.progressTotal) return;
+    const totalChanged = total !== this.progressTotal;
+    if (next === this.progressCurrent && !totalChanged) return;
     this.progressCurrent = next;
     this.progressTotal = total;
     if (total == null) return;
+    const now = Date.now();
+    if (totalChanged || next >= total || now - this.progressLastPrint >= PROGRESS_PRINT_THROTTLE_MS) {
+      this.progressLastPrint = now;
+      printRunProgress(next, total);
+    }
     this.progressDirty = true;
     if (this.progressTimer) return;
     this.progressTimer = setTimeout(() => {
@@ -2120,6 +2286,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 +2300,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})`);
@@ -2164,7 +2338,7 @@ var RunReporter = class {
   }
   // ── Anexos ───────────────────────────────────────────────────────────────────
   /**
-   * Pendura uma imagem num evento da run (log, item ou step): faz as checagens que não
+   * Pendura uma imagem num evento da run (log, item ou etapa): faz as checagens que não
    * dependem de I/O (reporter morto, instalação sem anexos, cota), reserva o id e dispara
    * o upload em segundo plano. Devolve o id — já referenciável pelo evento — ou undefined
    * quando a imagem foi descartada (sempre com aviso no log da run). Nunca lança: todo
@@ -2337,11 +2511,13 @@ var RunReporter = class {
 
 // src/tasks/run-context-store.ts
 var storage;
+var stepStorage;
 var initPromise;
 async function ensureStorage() {
   if (storage || !isNode()) return;
   initPromise ??= import("async_hooks").then(({ AsyncLocalStorage: ALS }) => {
     storage = new ALS();
+    stepStorage = new ALS();
   });
   await initPromise;
 }
@@ -2352,12 +2528,23 @@ async function runWithRunContext(store, fn) {
 function currentRunReporter() {
   return storage?.getStore()?.reporter;
 }
+async function runWithStepScope(scope, fn) {
+  await ensureStorage();
+  return stepStorage ? stepStorage.run(scope, fn) : fn();
+}
+function currentStep(transaction) {
+  const scope = stepStorage?.getStore();
+  return scope?.transaction === transaction ? scope.step : void 0;
+}
 
 // src/transaction.ts
 var FLUSH_TRANSACTION_OP = "hobots.run.flush";
+var DEFAULT_STEP_RETRIES = 1;
+var DEFAULT_STEP_RETRY_DELAY_MS = 5e3;
 var MAX_STEP_MESSAGE_CHARS = 2e3;
+var MAX_BACKLOG = 100;
 function stepMessage(text) {
-  return truncate(scrubSecrets(text), MAX_STEP_MESSAGE_CHARS);
+  return clip(scrubSecrets(text), MAX_STEP_MESSAGE_CHARS);
 }
 function stepId() {
   return uuid4().slice(0, 16);
@@ -2365,6 +2552,13 @@ function stepId() {
 function stepLabel(op, description) {
   return [op, description].filter(Boolean).join(" \u2014 ") || "(sem nome)";
 }
+function errorText(error) {
+  if (error instanceof Error) return error.message || error.name;
+  return safeString(error);
+}
+function errorReason(error) {
+  return error instanceof Error ? `${error.name}: ${errorText(error)}` : errorText(error);
+}
 function levelForStatus(status) {
   switch (status) {
     case "warning":
@@ -2404,58 +2598,68 @@ var Step = class {
   startTimestamp = nowISO();
   status = "ok";
   endTimestamp;
-  data;
-  /**
-   * Desfecho da step. `message` (opcional) é o motivo legível — vai em `data.message`
-   * e aparece na Central (performance e banner da execução) e no log de FINISH.
-   * `options.image` pendura um print do estado da tela em `data.attachments`.
-   */
-  setStatus(status, message, options) {
-    this.status = status;
-    if (message) this.setData("message", stepMessage(message));
+  _data;
+  // ── API do bot ────────────────────────────────────────────────────────────
+  warning(message, options) {
+    if (this.status !== "error") this._setStatus("warning", message);
     if (options?.image !== void 0) this.attachImage(options.image);
     return this;
   }
+  image(image3) {
+    this.attachImage(image3);
+    return this;
+  }
+  data(key, value) {
+    if (key === "attachments") return this;
+    this._setData(key, value);
+    return this;
+  }
+  // ── Internos (chamados pelo SDK) ──────────────────────────────────────────
+  /** `data` da etapa como vai no wire (undefined quando vazio). */
+  get payload() {
+    return this._data;
+  }
+  _setStatus(status, message) {
+    this.status = status;
+    if (message) this._setData("message", stepMessage(safeString(message)));
+    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.
-   * `options.image` pendura um print do estado da tela em `data.attachments`.
+   * Marca `error` guardando `{ type, message }` em `data.error` e fecha a etapa. Aceita qualquer
+   * valor lançado; `message` sobrescreve a mensagem do erro. Numa etapa já fechada não faz nada.
    */
-  setError(error, message, options) {
+  _failed(error, message) {
+    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);
+    const raw = message ?? errorText(error);
+    this._setData("error", { ...type ? { type } : {}, message: stepMessage(safeString(raw)) });
+    this._close();
     return this;
   }
+  _setData(key, value) {
+    this._data = { ...this._data, [key]: value };
+  }
   /**
    * Dispara o upload pela run (sink do RunReporter) e referencia o anexo em
    * `data.attachments` (chave reservada; teto igual ao das linhas de log). Fora de uma
    * run não há onde pendurar a imagem — descarta com aviso único.
    */
   attachImage(image3) {
-    const current = Array.isArray(this.data?.attachments) ? this.data.attachments : [];
+    const current = Array.isArray(this._data?.attachments) ? this._data.attachments : [];
     if (current.length >= MAX_ATTACHMENTS_PER_LOG_ENTRY) return;
     const id = this.transaction.attachImage(image3);
     if (!id) return;
-    this.setData("attachments", [...current, id]);
+    this._setData("attachments", [...current, id]);
   }
-  /** Motivo registrado via setStatus(…, message) ou setError — usado no log de FINISH. */
+  /** Motivo registrado (warning/erro) — usado no log de FINISH. */
   reason() {
-    const error = this.data?.error;
-    const text = typeof error?.message === "string" ? error.message : this.data?.message;
+    const error = this._data?.error;
+    const text = typeof error?.message === "string" ? error.message : this._data?.message;
     return typeof text === "string" && text ? text : void 0;
   }
-  setData(key, value) {
-    this.data = { ...this.data, [key]: value };
-    return this;
-  }
-  /** Step aninhada (filha desta step). */
-  startChild(op, description) {
-    return this.transaction.createStep(this.stepId, op, description);
-  }
-  finish() {
+  /** Fecha a etapa mantendo o status que estiver. Idempotente. */
+  _close() {
     if (this.endTimestamp) return;
     this.endTimestamp = nowISO();
     this.transaction.emit(
@@ -2471,22 +2675,23 @@ var Step = class {
   toJSON() {
     return {
       step_id: this.stepId,
-      parent_step_id: this.parentStepId,
-      op: this.op,
-      description: this.description,
+      ...this.parentStepId ? { parent_step_id: this.parentStepId } : {},
+      ...this.op ? { op: clip(this.op, MAX_STEP_OP_CHARS) } : {},
+      ...this.description ? { description: clip(this.description, MAX_STEP_DESCRIPTION_CHARS) } : {},
       status: this.status,
       start_timestamp: this.startTimestamp,
       timestamp: this.endTimestamp ?? nowISO(),
-      data: this.data
+      ...this._data ? { data: this._data } : {}
     };
   }
 };
 var Transaction = class {
-  constructor(client, name, op, runId) {
+  constructor(client, name, op, runId, options = {}) {
     this.client = client;
     this.name = name;
     this.op = op;
     this.runId = runId;
+    this.echo = options.echo ?? false;
     this.emit("transaction", "start", op ? `${name} (${op})` : name);
   }
   client;
@@ -2498,33 +2703,36 @@ var Transaction = class {
   startTimestamp = nowISO();
   status = "ok";
   steps = [];
-  tags = {};
   finished = false;
   lifecycleSink;
   attachmentSink;
   warnedNoAttachmentSink = false;
-  // instalado pelo RunReporter: abrir uma step é um ponto de parada cooperativo (lança RunCanceled)
+  // instalado pelo RunReporter: abrir uma etapa é um ponto de parada cooperativo (lança RunCanceled)
   stepGuard;
+  // modo local (sem client): o FINISH de cada etapa sai no terminal, como `[hobots:item]`
+  echo;
   // eventos emitidos antes do sink existir (o START da transaction sai no construtor,
   // antes do RunReporter conectar) — replay no setLifecycleSink
   lifecycleBacklog = [];
+  // ── Lifecycle / eco ───────────────────────────────────────────────────────
   /**
-   * Registra o início/fim de uma step ou transaction: espelha a linha no sink de
-   * lifecycle, se conectado (é assim que os eventos de performance aparecem nos
-   * logs da run no app), e ecoa no terminal apenas com `debug: true` — o SDK não
-   * escreve no stdout do processo do usuário sem permissão.
+   * Registra o início/fim de uma etapa ou da transaction: espelha a linha no sink de
+   * lifecycle, se conectado (é assim que os eventos de performance aparecem nos logs da
+   * run no app), e ecoa no terminal com `debug: true` — ou, no modo local, só o FINISH das
+   * etapas (`[hobots:step] FINISH …`), para o Studio e o dev verem.
    */
   emit(kind, phase, label, startTs, endTs, status, reason) {
     const durationMs = startTs && endTs ? new Date(endTs).getTime() - new Date(startTs).getTime() : void 0;
     const suffix = (durationMs != null ? ` (${durationMs}ms)` : "") + (reason ? `: ${reason}` : "");
-    if (this.client?.debug) {
+    const localFinish = this.echo && kind === "step" && phase === "finish";
+    if (this.client?.debug || localFinish) {
       const tag = colorize(`[hobots:${kind}] ${phase.toUpperCase()}`, phase === "finish" ? colorForStatus(status ?? "ok") : "cyan");
       console.log(`${tag} ${label}${suffix}`);
     }
     const level = phase === "finish" ? levelForStatus(status ?? "ok") : "info";
     const message = `[${kind}] ${phase.toUpperCase()} ${label}${suffix}`;
     if (this.lifecycleSink) this.lifecycleSink(level, message);
-    else if (this.lifecycleBacklog.length < 100) this.lifecycleBacklog.push([level, message]);
+    else if (this.lifecycleBacklog.length < MAX_BACKLOG) this.lifecycleBacklog.push([level, message]);
   }
   /** Conecta o espelho de lifecycle (RunReporter) e faz replay do backlog em ordem. */
   setLifecycleSink(sink) {
@@ -2533,59 +2741,111 @@ var Transaction = class {
     this.lifecycleBacklog = [];
     for (const [level, message] of backlog) sink(level, message);
   }
-  /** Conecta o pipeline de anexos da run — é o que dá imagem às steps. */
+  /** Conecta o pipeline de anexos da run — é o que dá imagem às etapas. */
   setAttachmentSink(sink) {
     this.attachmentSink = sink;
   }
-  /** Imagem de uma step → id do anexo pela run; sem run, descarta com aviso único. */
+  /** Imagem de uma etapa → id do anexo pela run; sem run, descarta com aviso único. */
   attachImage(image3) {
     if (this.attachmentSink) return this.attachmentSink(image3, nowISO());
     if (!this.warnedNoAttachmentSink) {
       this.warnedNoAttachmentSink = true;
-      console.warn("[hobots] imagem de step descartada \u2014 s\xF3 \xE9 suportada dentro de uma execu\xE7\xE3o");
+      console.warn("[hobots] imagem de etapa descartada \u2014 s\xF3 \xE9 suportada dentro de uma execu\xE7\xE3o");
     }
     return void 0;
   }
+  // ── Etapas ────────────────────────────────────────────────────────────────
   /**
-   * Conecta a checagem de cancelamento chamada antes de cada step nova — é assim que
-   * `hobots.transaction.startChild()` (e `step.startChild()`) param uma run cancelada.
+   * Conecta a checagem de cancelamento chamada antes de cada etapa nova (inclusive antes de
+   * cada nova tentativa) — é assim que `hobots.step()` para uma run cancelada.
    */
   setStepGuard(guard) {
     this.stepGuard = guard;
   }
-  createStep(parentStepId, op, description) {
+  /** A etapa aberta por `step()` (ou `items.each`) no contexto async atual, se houver. */
+  currentStep() {
+    return currentStep(this);
+  }
+  /** Faz de `step` a etapa corrente durante `fn` (filhas aninham nela). Sem etapa, só roda `fn`. */
+  scope(step, fn) {
+    if (!step) return fn();
+    return runWithStepScope({ transaction: this, step }, fn);
+  }
+  /** Abre uma etapa sob a corrente (ou direta da transaction). Interno: o bot usa `step()`. */
+  start(op, description) {
     this.stepGuard?.();
-    const step = new Step(this, parentStepId, op, description);
+    const parent = this.currentStep();
+    const step = new Step(this, parent ? parent.stepId : this.stepId, op, description);
     this.steps.push(step);
     this.emit("step", "start", stepLabel(op, description));
     return step;
   }
-  /** Step direta da transaction. */
-  startChild(op, description) {
-    return this.createStep(this.stepId, op, description);
+  /**
+   * Registra a etapa `name` executando `fn(etapa)` até dar certo ou esgotar `retries`
+   * tentativas extras (default 1), esperando `retryDelayMs` entre elas (default 5 000).
+   * Resolve com o retorno de `fn`.
+   *
+   * Uma etapa só no waterfall, cobrindo todas as tentativas: `data.attempts` quando houve
+   * mais de uma; `warning` com o motivo quando a última deu certo; `error` (e a exceção
+   * sobe) quando esgotou; `cancelled` em cancelamento/timeout, que nunca repetem.
+   */
+  async step(name, fn, options = {}) {
+    const requested = options.retries ?? DEFAULT_STEP_RETRIES;
+    const totalRetries = Number.isFinite(requested) ? Math.max(0, Math.floor(requested)) : DEFAULT_STEP_RETRIES;
+    const step = this.start(void 0, safeString(name));
+    let attempts = 0;
+    let lastFailure;
+    try {
+      const result = await retryWithBackoff(
+        (attempt) => {
+          attempts = attempt;
+          return this.scope(step, async () => fn(step));
+        },
+        {
+          retries: totalRetries,
+          delayMs: (attempt) => resolveDelay(options.retryDelayMs, attempt, DEFAULT_STEP_RETRY_DELAY_MS),
+          signal: options.signal,
+          wait: options.wait,
+          onRetry: (error, attempt, delayMs) => {
+            lastFailure = { error };
+            options.warn?.(
+              `etapa "${step.description}": tentativa ${attempt}/${totalRetries + 1} falhou: ${truncate(errorReason(error), 500)} \u2014 nova tentativa em ${delayMs}ms`
+            );
+          }
+        }
+      );
+      this.noteAttempts(step, attempts);
+      if (lastFailure && step.status === "ok") {
+        step._setStatus("warning", `tentativa ${attempts - 1}/${totalRetries + 1} falhou: ${errorReason(lastFailure.error)}`);
+      }
+      step._close();
+      return result;
+    } catch (error) {
+      this.noteAttempts(step, attempts);
+      if (isTerminalError(error)) step._setStatus("cancelled")._close();
+      else step._failed(error);
+      throw error;
+    }
   }
-  setTag(key, value) {
-    this.tags[key] = value;
-    return this;
+  noteAttempts(step, attempts) {
+    if (attempts > 1) step._setData("attempts", attempts);
   }
+  // ── Metadados ─────────────────────────────────────────────────────────────
   setStatus(status) {
     this.status = status;
     return this;
   }
-  setName(name) {
-    this.name = name;
-    return this;
-  }
+  // ── Encerramento ──────────────────────────────────────────────────────────
   /**
-   * Envia já as steps raiz finalizadas (e todas as descendentes, fechando as que
+   * Envia já as etapas 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
+   * `event_id` novo, até 200 etapas cada) e as tira da memória. Etapas 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.
+   * Devolve quantas etapas foram enviadas (0 sem client, sem nada terminado ou depois do `finish()`).
    */
   flush() {
-    if (this.finished) return 0;
+    if (!this.client || 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);
@@ -2601,15 +2861,13 @@ var Transaction = class {
         remaining.push(step);
       }
     }
-    for (const step of batch) step.finish();
+    for (const step of batch) step._close();
     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));
-      }
+    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;
   }
@@ -2626,14 +2884,15 @@ var Transaction = class {
       start_timestamp: startTimestamp,
       timestamp,
       steps: steps.map((step) => step.toJSON()),
-      tags: Object.keys(this.tags).length > 0 ? { ...this.tags } : void 0,
+      // sem tags próprias: o client mescla as do processo
+      tags: void 0,
       run_id: this.runId
     };
   }
   finish() {
     if (this.finished) return;
     this.finished = true;
-    for (const step of this.steps) step.finish();
+    for (const step of this.steps) step._close();
     const endTimestamp = nowISO();
     this.emit(
       "transaction",
@@ -2661,7 +2920,7 @@ var DEFAULT_RETRY_DELAY_MS = 5e3;
 async function executeRun(input) {
   const { run, handler, api, client, logger, tracker } = input;
   const options = handler.options;
-  const tx = new Transaction(client, "run", "hobots.run", run.id);
+  const tx = new Transaction(client, "run", "hobots.run", run.id, { echo: !client });
   const reporter = new RunReporter(
     api,
     run.id,
@@ -2695,6 +2954,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 +2964,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 +3160,96 @@ var TaskAgent = class {
   }
 };
 
+// src/tasks/single-run.ts
+var SingleRunRunner = class {
+  constructor(handler, deps) {
+    this.handler = handler;
+    this.deps = deps;
+    this.done = new Promise((resolve2) => {
+      this.resolveDone = resolve2;
+    });
+  }
+  handler;
+  deps;
+  abort = new AbortController();
+  /** Resolve quando a run terminou (ou não pôde começar, ou o runner foi parado antes). */
+  done;
+  resolveDone;
+  async run() {
+    try {
+      const run = await this.openRun();
+      if (!run) return;
+      this.deps.logger.debug(this.opened(run));
+      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 obter a run (close() antes dela existir). Uma run já em execução segue pelo tracker. */
+  stop() {
+    this.abort.abort();
+  }
+};
+
+// 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 extends SingleRunRunner {
+  constructor(runId, handler, deps) {
+    super(handler, deps);
+    this.runId = runId;
+  }
+  runId;
+  opened(run) {
+    return `run ${run.id} iniciada (HOBOTS_RUN_ID)`;
+  }
+  async openRun() {
+    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;
@@ -2932,46 +3287,16 @@ function normalizeItemColumns(input, logger) {
 }
 
 // src/tasks/local.ts
-var LocalRunner = class {
+var LocalRunner = class extends SingleRunRunner {
+  backoff;
   constructor(handler, deps) {
-    this.handler = handler;
-    this.deps = deps;
+    super(handler, deps);
     this.backoff = new Backoff(deps.logger, "cria\xE7\xE3o da run");
-    this.done = new Promise((resolve2) => {
-      this.resolveDone = resolve2;
-    });
-  }
-  handler;
-  deps;
-  abort = new AbortController();
-  backoff;
-  /** Resolve quando a run terminou (ou o runner foi parado antes de abri-la). */
-  done;
-  resolveDone;
-  async run() {
-    try {
-      const run = await this.createRun();
-      if (!run) return;
-      this.deps.logger.debug(`run ${run.id} aberta (modo start)`);
-      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 abrir a run (close() antes da plataforma responder). Uma run já aberta segue pelo tracker. */
-  stop() {
-    this.abort.abort();
+  opened(run) {
+    return `run ${run.id} aberta (modo start)`;
   }
-  async createRun() {
+  async openRun() {
     for (; ; ) {
       if (this.abort.signal.aborted) return void 0;
       try {
@@ -2984,6 +3309,129 @@ var LocalRunner = class {
   }
 };
 
+// src/tasks/local-transport.ts
+var LOCAL_RUN_ID = "local";
+var ITEM_LINE_PREFIX = "[hobots:item]";
+var SUMMARY_LINE_PREFIX = "[hobots:summary]";
+var ATTACHMENTS_DISCARDED_WARNING = "imagens e anexos n\xE3o s\xE3o enviados no modo local (descartados)";
+function unavailable(name) {
+  return new Error(`arquivo "${name}" enviado pela Central n\xE3o est\xE1 dispon\xEDvel no modo local`);
+}
+function cell(value) {
+  return (value ?? "").replace(/\r\n|[\t\r\n]/g, " ");
+}
+var LocalRunTransport = class {
+  constructor(params = {}, out = (line) => void process.stdout.write(`${line}
+`)) {
+    this.params = params;
+    this.out = out;
+  }
+  params;
+  out;
+  counts = { succeeded: 0, occurrence: 0, failed: 0 };
+  warnedAttachments = false;
+  /** Status terminal que o pipeline reportou — `undefined` enquanto a run corre (ou se ela nem reportou). */
+  terminalStatus;
+  async updateRun(_runId, update) {
+    if (update.status === "running") return;
+    this.terminalStatus = update.status;
+    if (update.status === "failed" && update.error && update.error.type !== "RunCanceled") {
+      printRunLog("error", `execu\xE7\xE3o falhou \u2014 ${update.error.type ?? "Error"}: ${update.error.message}`);
+      if (update.error.stack) console.error(update.error.stack);
+    }
+  }
+  async updateRunOnce() {
+  }
+  async createItems(_runId, request) {
+    for (const item of request.items) {
+      this.counts[item.status]++;
+      this.out(`${ITEM_LINE_PREFIX} ${item.status}	${cell(item.id)}	${cell(item.message)}`);
+    }
+    return { accepted: request.items.length, duplicates: 0 };
+  }
+  /** Totais por status — chame uma vez, no fim da run, antes da linha de conclusão. */
+  printSummary() {
+    const { succeeded, occurrence, failed } = this.counts;
+    this.out(
+      `${SUMMARY_LINE_PREFIX} total=${succeeded + occurrence + failed} ok=${succeeded} avisos=${occurrence} falhas=${failed} pulados=0`
+    );
+  }
+  async createAttachment(_runId, request) {
+    if (!this.warnedAttachments) {
+      this.warnedAttachments = true;
+      printRunLog("warning", ATTACHMENTS_DISCARDED_WARNING);
+    }
+    return { id: request.id, upload_url: "", headers: {}, expires_in: 0 };
+  }
+  async uploadAttachment() {
+  }
+  async confirmAttachment() {
+  }
+  /** Nome do arquivo pelo id (nos params); sem ele, o próprio id. */
+  fileName(fileId) {
+    return collectFileRefs(this.params).find((ref) => ref.id === fileId)?.name ?? fileId;
+  }
+  async requestFileDownload(_runId, fileId) {
+    throw unavailable(this.fileName(fileId));
+  }
+  async fetchFile(url) {
+    throw unavailable(url);
+  }
+  async confirmFileDownload(_runId, fileId) {
+    throw unavailable(this.fileName(fileId));
+  }
+};
+
+// src/tasks/local-run.ts
+var LOCAL_RUN_EXIT_CODES = { succeeded: 0, failed: 1, canceled: 130 };
+var LOCAL_RUN_CANCEL_GRACE_MS = 4e3;
+var LOCAL_RUN_BANNER = "modo local \u2014 execu\xE7\xE3o sem a Central; params de HOBOTS_RUN_PARAMS";
+var LocalRunRunner = class extends SingleRunRunner {
+  constructor(params, handler, deps) {
+    super(handler, deps);
+    this.params = params;
+  }
+  params;
+  canceled = false;
+  startedAt = Date.now();
+  finished = false;
+  run() {
+    this.startedAt = Date.now();
+    return super.run();
+  }
+  opened() {
+    return "run local iniciada (HOBOTS_LOCAL_RUN)";
+  }
+  async openRun() {
+    if (this.abort.signal.aborted) return void 0;
+    return { id: LOCAL_RUN_ID, params: this.params, form: null, source: "local", created_at: nowISO() };
+  }
+  /** SIGINT/SIGTERM: dispara o `ctx.signal` da run em voo — o handler para no próximo ponto de parada. */
+  cancel() {
+    this.canceled = true;
+    this.deps.tracker.singleActive()?.abort();
+  }
+  /** Desfecho da run: cancelada pelo sinal, senão o status terminal reportado (sem reporte = falha). */
+  get outcome() {
+    if (this.canceled) return "canceled";
+    return this.deps.api.terminalStatus ?? "failed";
+  }
+  /**
+   * Fecha o relato no terminal — `[hobots:summary]` e a linha de conclusão — e devolve o
+   * desfecho. Idempotente: o runtime chama ao fim da run ou quando a graça do cancelamento
+   * esgota com o handler ainda rodando.
+   */
+  finish() {
+    const outcome = this.outcome;
+    if (this.finished) return outcome;
+    this.finished = true;
+    this.deps.api.printSummary();
+    const seconds = Math.round((Date.now() - this.startedAt) / 1e3);
+    printRunLog("info", `execu\xE7\xE3o local conclu\xEDda (${outcome}) em ${seconds}s`);
+    return outcome;
+  }
+};
+
 // src/tasks/registry.ts
 var RunTracker = class {
   constructor(api) {
@@ -3099,19 +3547,10 @@ function hostname() {
   if (!isNode()) return void 0;
   return process.env.HOSTNAME || process.env.COMPUTERNAME || void 0;
 }
-function createRuntime(options, handler) {
-  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 },
-    config
-  );
-  const api = new TasksApi({ baseUrl: config.runsBaseUrl, key: config.key, logger });
-  const rt = {
+function baseRuntime(options, handler, logger, api) {
+  return {
     options: { ...options, clientSecret: void 0 },
-    config,
-    client,
+    client: void 0,
     logger,
     api,
     handler,
@@ -3120,18 +3559,55 @@ function createRuntime(options, handler) {
     heartbeat: void 0,
     agent: void 0,
     local: void 0,
+    attached: void 0,
+    localRun: void 0,
+    runId: void 0,
     instanceId: resolveInstanceId(options.instanceId),
-    environment,
+    environment: void 0,
     pollIntervalMs: void 0,
     booted: false,
     bootScheduled: false,
     bootPromise: void 0,
-    uninstallGlobalHandlers: options.captureUnhandled !== false ? installGlobalHandlers(client) : void 0,
+    uninstallGlobalHandlers: void 0,
     uninstallShutdown: void 0
   };
+}
+function createRuntime(options, handler, logger) {
+  const config = resolveConfig({ clientSecret: options.clientSecret });
+  const environment = resolveEnvironmentOption(options.environment);
+  const client = new Client(
+    {
+      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 });
+  const rt = baseRuntime(options, handler, logger, api);
+  rt.client = client;
+  rt.environment = environment;
+  rt.uninstallGlobalHandlers = options.captureUnhandled !== false ? installGlobalHandlers(client) : void 0;
   logger.debug("inicializado", { endpoint: config.ingestEndpoint });
   return rt;
 }
+function createLocalRunRuntime(options, handler, logger) {
+  let params;
+  try {
+    params = resolveLocalRunParams();
+  } catch (error) {
+    printRunLog("error", error instanceof Error ? error.message : String(error));
+    process.exit(2);
+    throw error;
+  }
+  const transport = new LocalRunTransport(params);
+  const rt = baseRuntime(options, handler, logger, transport);
+  rt.localRun = new LocalRunRunner(params, handler, { api: transport, client: void 0, logger, tracker: rt.tracker });
+  printRunLog("info", LOCAL_RUN_BANNER);
+  return rt;
+}
 function validateHandler(handler, fn) {
   if (typeof handler !== "function") {
     throw new Error(`[hobots] ${fn}(): o handler precisa ser uma fun\xE7\xE3o \u2014 ${fn}(async (params) => { ... })`);
@@ -3174,9 +3650,12 @@ function instanceInfo(rt) {
     machine: rt.sampler?.sample()
   };
 }
+function platformApi(rt) {
+  return rt.api;
+}
 function ensureAgent(rt) {
   rt.agent ??= new TaskAgent({
-    api: rt.api,
+    api: platformApi(rt),
     client: rt.client,
     logger: rt.logger,
     handler: rt.handler,
@@ -3188,7 +3667,7 @@ function ensureAgent(rt) {
 }
 function launchLocal(rt) {
   const runner = new LocalRunner(rt.handler, {
-    api: rt.api,
+    api: platformApi(rt),
     client: rt.client,
     logger: rt.logger,
     tracker: rt.tracker,
@@ -3197,7 +3676,57 @@ function launchLocal(rt) {
   rt.local = runner;
   void runner.run();
 }
+function launchAttached(rt, runId) {
+  const runner = new AttachedRunner(runId, rt.handler, {
+    api: platformApi(rt),
+    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();
+  });
+}
+function launchLocalRun(rt, runner) {
+  let finished = false;
+  const finish = () => {
+    if (finished) return;
+    finished = true;
+    rt.uninstallShutdown?.();
+    rt.uninstallShutdown = void 0;
+    const code = LOCAL_RUN_EXIT_CODES[runner.finish()];
+    if (runtime === rt) void close(0);
+    process.stdout.write("", () => process.exit(code));
+  };
+  if (rt.options.installExitHandlers !== false) {
+    let signaled = false;
+    const onSignal = (signal) => {
+      if (externalListenerCount(signal) > 0 || signaled) return;
+      signaled = true;
+      runner.cancel();
+      void Promise.race([runner.done, sleep(LOCAL_RUN_CANCEL_GRACE_MS)]).then(finish);
+    };
+    const onInt = markInternal(() => onSignal("SIGINT"));
+    const onTerm = markInternal(() => onSignal("SIGTERM"));
+    process.on("SIGINT", onInt);
+    process.on("SIGTERM", onTerm);
+    rt.uninstallShutdown = () => {
+      process.off("SIGINT", onInt);
+      process.off("SIGTERM", onTerm);
+    };
+  }
+  void runner.run();
+  void runner.done.then(finish);
+}
 async function boot(rt) {
+  if (rt.localRun) {
+    rt.booted = true;
+    launchLocalRun(rt, rt.localRun);
+    return;
+  }
   if (!rt.instanceId) {
     const id = await fallbackInstanceId();
     if (runtime !== rt) return;
@@ -3216,8 +3745,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;
@@ -3233,8 +3763,12 @@ function startAgent(fn, mode, handler, options) {
   }
   const logger = makeLogger(options.debug ?? false);
   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;
+  loadDotenv();
+  const rt = isLocalRun() ? createLocalRunRuntime(options, agentHandler, logger) : createRuntime(options, agentHandler, logger);
+  if (!rt.localRun && mode === "remote") {
+    if (options.pollIntervalMs !== void 0) rt.pollIntervalMs = options.pollIntervalMs;
+    rt.runId = resolveRunId(options.runId);
+  }
   runtime = rt;
   scheduleBoot(rt);
 }
@@ -3257,10 +3791,10 @@ function forwardAttachment(rt, attachment, message, type) {
   const reporter = currentReporter();
   if (!reporter) {
     rt.logger.warn("attachment descartado \u2014 s\xF3 \xE9 suportado dentro de uma execu\xE7\xE3o");
-    return;
+    return void 0;
   }
   const withMeta = typeof attachment === "object" && !isImageAttachment(attachment) && "image" in attachment ? image(attachment.image, { caption: attachment.caption, contentType: attachment.contentType }) : attachment;
-  reporter.log(toRunLogLevel(type), message, withMeta);
+  return reporter.log(toRunLogLevel(type), message, withMeta);
 }
 function captureException(error, hint) {
   const rt = runtime;
@@ -3271,11 +3805,19 @@ function captureException(error, hint) {
     }
     return void 0;
   }
+  let attachmentId;
   if (hint?.attachment) {
     const message = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
-    forwardAttachment(rt, hint.attachment, message, hint.type ?? "error");
+    attachmentId = forwardAttachment(rt, hint.attachment, message, hint.type ?? "error");
   }
-  return rt.client.captureException(error, hint);
+  if (!rt.client) {
+    rt.logger.debug("captureException ignorado no modo local (sem Central)");
+    return void 0;
+  }
+  const runId = currentReporter()?.runId;
+  const withRun = runId ? { ...hint, tags: { run_id: runId, ...hint?.tags } } : hint;
+  const contexts = runId && attachmentId ? { run: { id: runId, attachments: [attachmentId] } } : void 0;
+  return rt.client.captureException(error, withRun, contexts);
 }
 async function close(timeoutMs = 3e4) {
   const rt = runtime;
@@ -3284,6 +3826,8 @@ async function close(timeoutMs = 3e4) {
   await rt.bootPromise;
   if (rt.agent) await rt.agent.stop(0);
   rt.local?.stop();
+  rt.attached?.stop();
+  rt.localRun?.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`);
@@ -3292,7 +3836,7 @@ async function close(timeoutMs = 3e4) {
   rt.heartbeat?.stop();
   rt.uninstallShutdown?.();
   rt.uninstallGlobalHandlers?.();
-  const flushed = await rt.client.close(timeoutMs);
+  const flushed = rt.client ? await rt.client.close(timeoutMs) : true;
   return idle && flushed;
 }
 
@@ -3321,11 +3865,13 @@ var noop = () => void 0;
 var fallbackEachSink = {
   report: noop,
   startStep: () => void 0,
+  stepScope: (_step, fn) => fn(),
   declareTotal: noop,
   advance: noop,
   checkCanceled: noop,
   isAborted: () => false,
-  logError: (message) => printRunLog("error", message)
+  logError: (message) => printRunLog("error", message),
+  flush: () => Promise.resolve()
 };
 var fallbackItems = {
   add: noop,
@@ -3344,7 +3890,6 @@ var fallbackFiles = {
   read: outsideRunFiles
 };
 var neverAborts = new AbortController().signal;
-var detachedTransaction;
 function resolve(member) {
   const reporter = currentReporter();
   if (reporter) return reporter.context;
@@ -3365,8 +3910,12 @@ var hobots = Object.defineProperties({}, {
   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),
+  step: method((name, fn, options) => {
+    const ctx = resolve("step");
+    if (ctx) return ctx.step(name, fn, options);
+    return new Transaction(void 0, "hobots.detached").step(name, fn, options);
+  }),
   throwIfCanceled: method(() => resolve("throwIfCanceled")?.throwIfCanceled()),
   sleep: method((ms) => resolve("sleep")?.sleep(ms) ?? sleep(ms)),
   flush: method((timeoutMs) => resolve("flush")?.flush(timeoutMs) ?? Promise.resolve()),
@@ -3401,6 +3950,7 @@ var image2 = hobots.image;
 var isFileRef2 = hobots.isFileRef;
 
 // src/index.ts
+loadDotenv();
 var src_default = hobots;
 export {
   captureException2 as captureException,