hobots 2.4.0 → 3.2.0

package/dist/index.cjs

@@ -30,85 +30,19 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var src_exports = {};
 __export(src_exports, {
-  Client: () => Client,
-  DEFAULT_BASE_URL: () => DEFAULT_BASE_URL,
-  Scope: () => Scope,
-  Step: () => Step,
-  Transaction: () => Transaction,
-  addBreadcrumb: () => addBreadcrumb,
-  captureException: () => captureException,
-  captureMessage: () => captureMessage,
-  close: () => close,
-  flush: () => flush,
-  getClient: () => getClient,
-  init: () => init,
-  register: () => register,
-  scrubSecrets: () => scrubSecrets,
-  setContext: () => setContext,
-  setExtra: () => setExtra,
-  setTag: () => setTag,
-  setTags: () => setTags,
-  setUser: () => setUser,
-  start: () => start,
-  startTransaction: () => startTransaction,
-  stop: () => stop,
-  withScope: () => withScope
+  captureException: () => captureException2,
+  close: () => close2,
+  default: () => src_default,
+  hobots: () => hobots,
+  register: () => register2,
+  retry: () => retry,
+  start: () => start2
 });
 module.exports = __toCommonJS(src_exports);
 
-// src/config.ts
-var DEFAULT_BASE_URL = "https://api2.hobots.app";
-var SECRET_PATTERN = /^hb_[a-f0-9]{64}$/i;
-function envBaseUrl() {
-  if (typeof process === "undefined" || !process.env) return void 0;
-  return process.env.HOBOTS_API_URL?.trim() || void 0;
-}
-function isLoopbackHost(hostname2) {
-  return hostname2 === "localhost" || hostname2.endsWith(".localhost") || hostname2.startsWith("127.") || hostname2 === "[::1]" || hostname2 === "::1" || hostname2 === "0.0.0.0";
-}
-var warnedInsecureBaseUrl = false;
-function validateBaseUrl(raw, prefix) {
-  let url;
-  try {
-    url = new URL(raw);
-  } catch {
-    throw new Error(`${prefix} HOBOTS_API_URL inv\xE1lida \u2014 esperado URL http(s), ex.: http://localhost:3001`);
-  }
-  if (url.protocol !== "http:" && url.protocol !== "https:") {
-    throw new Error(`${prefix} HOBOTS_API_URL com esquema "${url.protocol}" n\xE3o suportado \u2014 use http(s)`);
-  }
-  if (url.username || url.password) {
-    throw new Error(`${prefix} HOBOTS_API_URL n\xE3o pode conter credenciais na URL \u2014 a autentica\xE7\xE3o \xE9 s\xF3 pelo Client Secret`);
-  }
-  if (url.protocol === "http:" && !isLoopbackHost(url.hostname) && !warnedInsecureBaseUrl) {
-    warnedInsecureBaseUrl = true;
-    console.warn(
-      `${prefix} HOBOTS_API_URL usa http para o host remoto "${url.hostname}" \u2014 o Client Secret trafega sem TLS`
-    );
-  }
-  return raw.replace(/\/+$/, "");
-}
-function resolveConfig(options, prefix = "[hobots]") {
-  const key = options.clientSecret?.trim();
-  if (!key) {
-    throw new Error(`${prefix} clientSecret ausente \u2014 copie o Client Secret do agente em Configura\xE7\xF5es \u2192 Agentes`);
-  }
-  if (!SECRET_PATTERN.test(key)) {
-    throw new Error(
-      `${prefix} clientSecret com formato inv\xE1lido (${key.length} caracteres) \u2014 esperado "hb_" + 64 hex; copie o Client Secret do agente em Configura\xE7\xF5es \u2192 Agentes`
-    );
-  }
-  const baseUrl = validateBaseUrl(envBaseUrl() ?? DEFAULT_BASE_URL, prefix);
-  return {
-    key,
-    baseUrl,
-    ingestEndpoint: `${baseUrl}/v1/ingest`,
-    tasksBaseUrl: `${baseUrl}/v1/tasks`
-  };
-}
-
 // 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) {
@@ -131,7 +65,7 @@ function parseStacktrace(stack) {
     const filename = loc ? loc[1] : location;
     frames.push({
       function: fn || "<anonymous>",
-      filename: filename || void 0,
+      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)
@@ -161,7 +95,7 @@ function scrubSecrets(text) {
 
 // src/utils.ts
 var SDK_NAME = "hobots";
-var SDK_VERSION = true ? "2.4.0" : "0.0.0-dev";
+var SDK_VERSION = true ? "3.2.0" : "0.0.0-dev";
 function isNode() {
   return typeof process !== "undefined" && typeof process.versions?.node === "string";
 }
@@ -189,20 +123,47 @@ function unrefTimer(timer) {
   timer?.unref?.();
 }
 function sleep(ms) {
-  return new Promise((resolve) => {
-    const timer = setTimeout(resolve, ms);
+  return new Promise((resolve2) => {
+    const timer = setTimeout(resolve2, ms);
     unrefTimer(timer);
   });
 }
+function abortableSleep(ms, signal) {
+  return new Promise((resolve2) => {
+    if (signal?.aborted) {
+      resolve2();
+      return;
+    }
+    const onAbort = () => {
+      clearTimeout(timer);
+      resolve2();
+    };
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve2();
+    }, ms);
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
 function jitter(baseMs) {
   return Math.floor(baseMs / 2 + Math.random() * (baseMs / 2));
 }
 function truncate(value, max) {
   return value.length > max ? `${value.slice(0, max)}\u2026 [truncado]` : value;
 }
+function safeString(value) {
+  if (typeof value === "string") return value;
+  try {
+    const json = JSON.stringify(value);
+    if (json && json !== "{}") return json;
+  } catch {
+  }
+  return String(value);
+}
 var DEFAULT_RETRY_DELAYS_MS = [1e3, 4e3, 16e3];
 async function fetchWithRetry(send, options) {
   const delays = options.delays ?? DEFAULT_RETRY_DELAYS_MS;
+  const noRetry = options.noRetryStatuses ?? [];
   for (let attempt = 0; ; attempt++) {
     let retriable;
     let serverDelay;
@@ -210,6 +171,7 @@ async function fetchWithRetry(send, options) {
       const response = await send();
       if (response.ok) return response;
       if (response.status >= 400 && response.status < 500 && response.status !== 429) return response;
+      if (noRetry.includes(response.status)) return response;
       if (response.status === 429) serverDelay = retryAfterMs(response);
       retriable = new Error(`HTTP ${response.status}`);
     } catch (error) {
@@ -282,26 +244,18 @@ function colorize(text, color) {
 }
 
 // src/eventbuilder.ts
-function safeString(value) {
-  if (typeof value === "string") return value;
-  try {
-    const json = JSON.stringify(value);
-    if (json && json !== "{}") return json;
-  } catch {
-  }
-  return String(value);
-}
+var MAX_EXCEPTION_VALUE_CHARS = 8192;
 function eventFromException(error, type = "error") {
   let exceptionType;
   let value;
   let frames = [];
   if (error instanceof Error) {
     exceptionType = error.name || "Error";
-    value = scrubSecrets(error.message);
+    value = truncate(scrubSecrets(error.message), MAX_EXCEPTION_VALUE_CHARS);
     frames = parseStacktrace(error.stack);
   } else {
     exceptionType = "NonError";
-    value = scrubSecrets(safeString(error));
+    value = truncate(scrubSecrets(safeString(error)), MAX_EXCEPTION_VALUE_CHARS);
   }
   return {
     event_id: uuid4(),
@@ -314,14 +268,6 @@ function eventFromException(error, type = "error") {
     }
   };
 }
-function eventFromMessage(message, type = "warning") {
-  return {
-    event_id: uuid4(),
-    timestamp: nowISO(),
-    type,
-    message: scrubSecrets(message)
-  };
-}
 
 // src/transport.ts
 var REQUEST_TIMEOUT_MS = 1e4;
@@ -435,6 +381,18 @@ var Transport = class {
 };
 
 // src/client.ts
+var MAX_TAG_VALUE_CHARS = 512;
+var MAX_FINGERPRINT_ITEMS = 10;
+var MAX_FINGERPRINT_ITEM_CHARS = 255;
+var MAX_TRANSACTION_NAME_CHARS = 500;
+var MAX_STEPS = 200;
+function clipTags(tags) {
+  return Object.fromEntries(Object.entries(tags).map(([key, value]) => [key, truncate(String(value), MAX_TAG_VALUE_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));
+}
 function runtimeContexts() {
   if (isNode()) {
     return {
@@ -455,7 +413,7 @@ var Client = class {
   #config;
   transport;
   machine;
-  constructor(options, config = resolveConfig(options)) {
+  constructor(options, config) {
     this.#options = options;
     this.debug = !!options.debug;
     this.logger = makeLogger(this.debug);
@@ -485,53 +443,45 @@ var Client = class {
   [/* @__PURE__ */ Symbol.for("nodejs.util.inspect.custom")]() {
     return `Client { baseUrl: '${this.#config.baseUrl}' }`;
   }
-  captureException(error, hint, scope2) {
-    return this.captureEvent(eventFromException(error, hint?.type ?? "error"), hint, scope2);
-  }
-  captureMessage(message, type, hint, scope2) {
-    return this.captureEvent(eventFromMessage(message, type), hint, scope2);
+  captureException(error, hint) {
+    return this.captureEvent(eventFromException(error, hint?.type ?? "error"), hint);
   }
-  captureEvent(event, hint, scope2) {
-    const sampleRate = this.options.sampleRate ?? 1;
-    if (sampleRate < 1 && Math.random() >= sampleRate) {
-      this.logger.debug("evento descartado por sampleRate");
-      return event.event_id;
-    }
-    const prepared = this.prepareEvent(event, hint, scope2);
-    const final = this.options.beforeSend ? this.options.beforeSend(prepared) : prepared;
-    if (!final) {
-      this.logger.debug("evento descartado por beforeSend");
-      return event.event_id;
-    }
+  captureEvent(event, hint) {
+    const final = this.prepareEvent(event, hint);
     this.transport.enqueue({ type: "event", payload: final });
     return final.event_id;
   }
-  prepareEvent(event, hint, scope2) {
-    const tags = { ...this.options.tags, ...scope2.tags, ...event.tags, ...hint?.tags };
-    const extra = { ...scope2.extra, ...event.extra, ...hint?.extra };
+  prepareEvent(event, hint) {
+    const tags = { ...this.options.tags, ...event.tags, ...hint?.tags };
+    const extra = { ...event.extra, ...hint?.extra };
     const sampled = this.machine?.sample();
     const machine = sampled ? { machine: sampled } : {};
     return {
       ...event,
-      type: hint?.type ?? event.type ?? scope2.type ?? "error",
+      type: hint?.type ?? event.type ?? "error",
       release: event.release ?? this.options.release,
       environment: this.resolveEnvironment(event.environment),
-      tags: Object.keys(tags).length > 0 ? tags : void 0,
+      tags: Object.keys(tags).length > 0 ? clipTags(tags) : void 0,
       extra: Object.keys(extra).length > 0 ? extra : void 0,
-      user: event.user ?? scope2.user,
-      contexts: { ...runtimeContexts(), ...machine, ...scope2.contexts, ...event.contexts },
-      breadcrumbs: scope2.breadcrumbs.length > 0 ? [...scope2.breadcrumbs] : event.breadcrumbs,
-      fingerprint: hint?.fingerprint ?? event.fingerprint ?? scope2.fingerprint
+      contexts: { ...runtimeContexts(), ...machine, ...event.contexts },
+      fingerprint: clipFingerprint(hint?.fingerprint ?? event.fingerprint)
     };
   }
   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}`);
+      steps = steps.slice(0, MAX_STEPS);
+    }
     this.transport.enqueue({
       type: "transaction",
       payload: {
         ...payload,
+        name: truncate(payload.name || "(sem nome)", MAX_TRANSACTION_NAME_CHARS),
+        steps,
         release: payload.release ?? this.options.release,
         environment: this.resolveEnvironment(payload.environment),
-        tags: { ...this.options.tags, ...payload.tags }
+        tags: clipTags({ ...this.options.tags, ...payload.tags })
       }
     });
   }
@@ -547,7 +497,7 @@ var Client = class {
     });
   }
   /**
-   * Ambiente do item: o dele, senão o do init(), senão produção. Centralizado
+   * Ambiente do item: o dele, senão o das opções, senão produção. Centralizado
    * porque evento, transaction e heartbeat precisam responder igual — o servidor
    * normaliza apelidos legados, então aqui basta repassar.
    */
@@ -562,23 +512,110 @@ var Client = class {
   }
 };
 
+// src/config.ts
+var DEFAULT_BASE_URL = "https://api2.hobots.app";
+var CLIENT_SECRET_ENV = "HOBOTS_CLIENT_SECRET";
+function envClientSecret() {
+  if (typeof process === "undefined" || !process.env) return void 0;
+  return process.env[CLIENT_SECRET_ENV]?.trim() || void 0;
+}
+var SECRET_PATTERN = /^hb_[a-f0-9]{64}$/i;
+function envBaseUrl() {
+  if (typeof process === "undefined" || !process.env) return void 0;
+  return process.env.HOBOTS_API_URL?.trim() || void 0;
+}
+function isLoopbackHost(hostname2) {
+  return hostname2 === "localhost" || hostname2.endsWith(".localhost") || hostname2.startsWith("127.") || hostname2 === "[::1]" || hostname2 === "::1" || hostname2 === "0.0.0.0";
+}
+var warnedInsecureBaseUrl = false;
+function validateBaseUrl(raw, prefix) {
+  let url;
+  try {
+    url = new URL(raw);
+  } catch {
+    throw new Error(`${prefix} HOBOTS_API_URL inv\xE1lida \u2014 esperado URL http(s), ex.: http://localhost:3001`);
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new Error(`${prefix} HOBOTS_API_URL com esquema "${url.protocol}" n\xE3o suportado \u2014 use http(s)`);
+  }
+  if (url.username || url.password) {
+    throw new Error(`${prefix} HOBOTS_API_URL n\xE3o pode conter credenciais na URL \u2014 a autentica\xE7\xE3o \xE9 s\xF3 pelo Client Secret`);
+  }
+  if (url.protocol === "http:" && !isLoopbackHost(url.hostname) && !warnedInsecureBaseUrl) {
+    warnedInsecureBaseUrl = true;
+    console.warn(
+      `${prefix} HOBOTS_API_URL usa http para o host remoto "${url.hostname}" \u2014 o Client Secret trafega sem TLS`
+    );
+  }
+  return raw.replace(/\/+$/, "");
+}
+function resolveConfig(options = {}, prefix = "[hobots]") {
+  const fromOption = options.clientSecret?.trim();
+  const key = fromOption || envClientSecret();
+  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 da task); copie o Client Secret do agente em Configura\xE7\xF5es \u2192 Agentes`
+    );
+  }
+  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`
+    );
+  }
+  const baseUrl = validateBaseUrl(envBaseUrl() ?? DEFAULT_BASE_URL, prefix);
+  return {
+    key,
+    baseUrl,
+    ingestEndpoint: `${baseUrl}/v1/ingest`,
+    tasksBaseUrl: `${baseUrl}/v1/tasks`
+  };
+}
+
+// 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 = 3e4;
 var MIN_REPORTED_INTERVAL_MS = 1e3;
 var MAX_REPORTED_INTERVAL_MS = 9e5;
 var Heartbeat = class {
-  constructor(client2, options = {}, instanceId, sampler) {
-    this.client = client2;
+  constructor(client, options = {}, instanceId, sampler) {
+    this.client = client;
     this.sampler = sampler;
     this.intervalMs = options.intervalMs ?? DEFAULT_INTERVAL_MS;
     this.instanceId = instanceId;
     this.name = options.name ?? instanceId;
     this.metadata = options.metadata;
+    this.keepAlive = options.keepAlive ?? false;
   }
   intervalMs;
   instanceId;
   name;
   metadata;
+  keepAlive;
   timer;
   start() {
     if (this.timer) return;
@@ -594,7 +631,7 @@ var Heartbeat = class {
       },
       this.intervalMs * (0.9 + Math.random() * 0.2)
     );
-    unrefTimer(this.timer);
+    if (!this.keepAlive) unrefTimer(this.timer);
   }
   stop() {
     if (this.timer) {
@@ -628,6 +665,11 @@ function externalListenerCount(event) {
 var emergencyTasks = [];
 function addEmergencyTask(task) {
   emergencyTasks.push(task);
+  const forget = () => {
+    const index = emergencyTasks.indexOf(task);
+    if (index !== -1) emergencyTasks.splice(index, 1);
+  };
+  task.then(forget, forget);
 }
 async function awaitEmergencyTasks(capMs) {
   if (emergencyTasks.length === 0) return;
@@ -640,13 +682,13 @@ var installed = false;
 function hasInstalledGlobalHandlers() {
   return installed;
 }
-function installGlobalHandlers(client2, getScope) {
+function installGlobalHandlers(client) {
   if (installed) return () => void 0;
   installed = true;
   if (isNode()) {
     const onUncaught = markInternal((error) => {
-      client2.captureException(error, { type: "fatal", tags: { mechanism: "uncaughtException" } }, getScope());
-      void client2.flush(2e3).then(async () => {
+      client.captureException(error, { type: "fatal", tags: { mechanism: "uncaughtException" } });
+      void client.flush(2e3).then(async () => {
         if (externalListenerCount("uncaughtException") === 0) {
           await awaitEmergencyTasks(EMERGENCY_REPORT_CAP_MS);
           console.error(error);
@@ -655,11 +697,11 @@ function installGlobalHandlers(client2, getScope) {
       });
     });
     const onRejection = markInternal((reason) => {
-      client2.captureException(reason, { type: "error", tags: { mechanism: "unhandledRejection" } }, getScope());
-      void client2.flush(2e3);
+      client.captureException(reason, { type: "error", tags: { mechanism: "unhandledRejection" } });
+      void client.flush(2e3);
     });
     const onBeforeExit = markInternal(() => {
-      void client2.flush(2e3);
+      void client.flush(2e3);
     });
     process.on("uncaughtException", onUncaught);
     process.on("unhandledRejection", onRejection);
@@ -673,13 +715,13 @@ function installGlobalHandlers(client2, getScope) {
   }
   if (typeof window !== "undefined") {
     const onError = (event) => {
-      client2.captureException(event.error ?? event.message, { tags: { mechanism: "onerror" } }, getScope());
+      client.captureException(event.error ?? event.message, { tags: { mechanism: "onerror" } });
     };
     const onRejection = (event) => {
-      client2.captureException(event.reason, { tags: { mechanism: "onunhandledrejection" } }, getScope());
+      client.captureException(event.reason, { tags: { mechanism: "onunhandledrejection" } });
     };
     const onPageHide = () => {
-      void client2.flush(1e3);
+      void client.flush(1e3);
     };
     window.addEventListener("error", onError);
     window.addEventListener("unhandledrejection", onRejection);
@@ -819,313 +861,112 @@ var MachineSampler = class {
   }
 };
 
-// src/scope.ts
-var Scope = class _Scope {
-  tags = {};
-  user;
-  contexts = {};
-  extra = {};
-  type;
-  fingerprint;
-  breadcrumbs = [];
-  setTag(key, value) {
-    this.tags[key] = value;
-    return this;
-  }
-  setTags(tags) {
-    Object.assign(this.tags, tags);
-    return this;
-  }
-  setUser(user) {
-    this.user = user ?? void 0;
-    return this;
-  }
-  setContext(name, context) {
-    if (context === null) {
-      delete this.contexts[name];
-    } else {
-      this.contexts[name] = context;
-    }
-    return this;
-  }
-  setExtra(key, value) {
-    this.extra[key] = value;
-    return this;
+// src/tasks/api.ts
+var POLL_TIMEOUT_MS = 3e4;
+var UPDATE_TIMEOUT_MS = 1e4;
+var ATTACHMENT_TERMINAL_STATUSES = [429, 501, 503];
+var ITEMS_TERMINAL_STATUSES = [429];
+var UPLOAD_TIMEOUT_MS = 3e4;
+var UPLOAD_RETRY_DELAYS_MS = [1e3, 4e3];
+var TasksApiError = class extends Error {
+  constructor(message, status) {
+    super(message);
+    this.status = status;
+    this.name = "TasksApiError";
   }
-  setExtras(extras) {
-    Object.assign(this.extra, extras);
-    return this;
+};
+async function withRequestTimeout(timeoutMs, external, send) {
+  const { signal, cleanup } = withTimeoutSignal(timeoutMs, external);
+  try {
+    return await send(signal);
+  } finally {
+    cleanup();
   }
-  setType(type) {
-    this.type = type;
-    return this;
+}
+var TasksApi = class {
+  baseUrl;
+  key;
+  logger;
+  constructor(options) {
+    this.baseUrl = options.baseUrl;
+    this.key = options.key;
+    this.logger = options.logger;
   }
-  setFingerprint(fingerprint) {
-    this.fingerprint = fingerprint;
-    return this;
+  headers() {
+    return {
+      "content-type": "application/json",
+      authorization: `Bearer ${this.key}`
+    };
   }
-  addBreadcrumb(crumb, maxBreadcrumbs) {
-    this.breadcrumbs.push({ timestamp: nowISO(), ...crumb });
-    if (this.breadcrumbs.length > maxBreadcrumbs) {
-      this.breadcrumbs.splice(0, this.breadcrumbs.length - maxBreadcrumbs);
+  /** Um request só — o loop de polling é quem decide o backoff entre tentativas. */
+  async poll(request, signal) {
+    const { signal: timeoutSignal, cleanup } = withTimeoutSignal(POLL_TIMEOUT_MS, signal);
+    let response;
+    try {
+      response = await fetch(`${this.baseUrl}/poll`, {
+        method: "POST",
+        headers: this.headers(),
+        body: JSON.stringify(request),
+        signal: timeoutSignal
+      });
+    } finally {
+      cleanup();
     }
-    return this;
+    if (!response.ok) {
+      throw new TasksApiError(`poll falhou (HTTP ${response.status})`, response.status);
+    }
+    return this.parsePollResponse(await response.json(), request.max ?? 1);
   }
-  clearBreadcrumbs() {
-    this.breadcrumbs = [];
-    return this;
+  /**
+   * Abre uma run por conta própria (modo start). Um request só — como no poll, o
+   * ladder de espera entre tentativas é decisão do chamador (LocalRunner).
+   * 4xx (401 = chave rejeitada) vira TasksApiError com o status.
+   */
+  async createRun(request, signal) {
+    const { signal: timeoutSignal, cleanup } = withTimeoutSignal(UPDATE_TIMEOUT_MS, signal);
+    let response;
+    try {
+      response = await fetch(`${this.baseUrl}/runs`, {
+        method: "POST",
+        headers: this.headers(),
+        body: JSON.stringify(request),
+        signal: timeoutSignal
+      });
+    } finally {
+      cleanup();
+    }
+    if (!response.ok) {
+      throw new TasksApiError(`cria\xE7\xE3o da run falhou (HTTP ${response.status})`, response.status);
+    }
+    const body = await response.json().catch(() => null);
+    if (typeof body?.id !== "string" || typeof body.task !== "string") {
+      throw new TasksApiError("resposta inv\xE1lida da cria\xE7\xE3o de run (id/task ausentes)", 0);
+    }
+    return {
+      id: body.id,
+      task: body.task,
+      params: body.params && typeof body.params === "object" && !Array.isArray(body.params) ? body.params : {},
+      form: null,
+      source: typeof body.source === "string" ? body.source : "agent",
+      created_at: typeof body.created_at === "string" ? body.created_at : (/* @__PURE__ */ new Date()).toISOString()
+    };
   }
-  clone() {
-    const next = new _Scope();
-    next.tags = { ...this.tags };
-    next.user = this.user ? { ...this.user } : void 0;
-    next.contexts = Object.fromEntries(Object.entries(this.contexts).map(([k, v]) => [k, { ...v }]));
-    next.extra = { ...this.extra };
-    next.type = this.type;
-    next.fingerprint = this.fingerprint ? [...this.fingerprint] : void 0;
-    next.breadcrumbs = [...this.breadcrumbs];
-    return next;
-  }
-};
-
-// src/transaction.ts
-function stepId() {
-  return uuid4().slice(0, 16);
-}
-function stepLabel(op, description) {
-  return [op, description].filter(Boolean).join(" \u2014 ") || "(sem nome)";
-}
-function levelForStatus(status) {
-  switch (status) {
-    case "warning":
-      return "warning";
-    case "error":
-      return "error";
-    case "cancelled":
-      return "warning";
-    default:
-      return "success";
-  }
-}
-function colorForStatus(status) {
-  switch (status) {
-    case "warning":
-      return "yellow";
-    case "error":
-      return "red";
-    case "cancelled":
-      return "gray";
-    default:
-      return "green";
-  }
-}
-var Step = class {
-  constructor(transaction, parentStepId, op, description) {
-    this.transaction = transaction;
-    this.parentStepId = parentStepId;
-    this.op = op;
-    this.description = description;
-  }
-  stepId = stepId();
-  startTimestamp = nowISO();
-  status = "ok";
-  endTimestamp;
-  data;
-  setStatus(status) {
-    this.status = status;
-    return this;
-  }
-  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() {
-    if (this.endTimestamp) return;
-    this.endTimestamp = nowISO();
-    this.transaction.emit(
-      "step",
-      "finish",
-      stepLabel(this.op, this.description),
-      this.startTimestamp,
-      this.endTimestamp,
-      this.status
-    );
-  }
-  toJSON() {
-    return {
-      step_id: this.stepId,
-      parent_step_id: this.parentStepId,
-      op: this.op,
-      description: this.description,
-      status: this.status,
-      start_timestamp: this.startTimestamp,
-      timestamp: this.endTimestamp ?? nowISO(),
-      data: this.data
-    };
-  }
-};
-var Transaction = class {
-  constructor(client2, name, op, sampled = true, runId) {
-    this.client = client2;
-    this.name = name;
-    this.op = op;
-    this.sampled = sampled;
-    this.runId = runId;
-    this.emit("transaction", "start", op ? `${name} (${op})` : name);
-  }
-  eventId = uuid4();
-  stepId = stepId();
-  startTimestamp = nowISO();
-  status = "ok";
-  steps = [];
-  tags = {};
-  finished = false;
-  lifecycleSink;
-  // eventos emitidos antes do sink existir (o START da transaction sai no construtor,
-  // antes do RunReporter conectar) — replay no setLifecycleSink
-  lifecycleBacklog = [];
-  /**
-   * 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.
-   */
-  emit(kind, phase, label, startTs, endTs, status) {
-    const durationMs = startTs && endTs ? new Date(endTs).getTime() - new Date(startTs).getTime() : void 0;
-    const suffix = durationMs != null ? ` (${durationMs}ms)` : "";
-    if (this.client?.debug) {
-      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]);
-  }
-  /** Conecta o espelho de lifecycle (RunReporter) e faz replay do backlog em ordem. */
-  setLifecycleSink(sink) {
-    this.lifecycleSink = sink;
-    const backlog = this.lifecycleBacklog;
-    this.lifecycleBacklog = [];
-    for (const [level, message] of backlog) sink(level, message);
-  }
-  createStep(parentStepId, op, description) {
-    const step = new Step(this, parentStepId, 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);
-  }
-  setTag(key, value) {
-    this.tags[key] = value;
-    return this;
-  }
-  setStatus(status) {
-    this.status = status;
-    return this;
-  }
-  setName(name) {
-    this.name = name;
-    return this;
-  }
-  finish() {
-    if (this.finished) return;
-    this.finished = true;
-    for (const step of this.steps) step.finish();
-    const endTimestamp = nowISO();
-    this.emit(
-      "transaction",
-      "finish",
-      this.op ? `${this.name} (${this.op})` : this.name,
-      this.startTimestamp,
-      endTimestamp,
-      this.status
-    );
-    if (!this.sampled || !this.client) return;
-    const payload = {
-      event_id: this.eventId,
-      name: this.name,
-      op: this.op,
-      status: this.status,
-      start_timestamp: this.startTimestamp,
-      timestamp: endTimestamp,
-      steps: this.steps.map((step) => step.toJSON()),
-      tags: Object.keys(this.tags).length > 0 ? this.tags : void 0,
-      run_id: this.runId
-    };
-    this.client.sendTransaction(payload);
-  }
-};
-
-// src/tasks/api.ts
-var POLL_TIMEOUT_MS = 3e4;
-var UPDATE_TIMEOUT_MS = 1e4;
-var UPLOAD_TIMEOUT_MS = 3e4;
-var UPLOAD_RETRY_DELAYS_MS = [1e3, 4e3];
-var TasksApiError = class extends Error {
-  constructor(message, status) {
-    super(message);
-    this.status = status;
-    this.name = "TasksApiError";
-  }
-};
-var TasksApi = class {
-  baseUrl;
-  key;
-  logger;
-  constructor(options) {
-    this.baseUrl = options.baseUrl;
-    this.key = options.key;
-    this.logger = options.logger;
-  }
-  headers() {
-    return {
-      "content-type": "application/json",
-      authorization: `Bearer ${this.key}`
-    };
-  }
-  /** Um request só — o loop de polling é quem decide o backoff entre tentativas. */
-  async poll(request, signal) {
-    const { signal: timeoutSignal, cleanup } = withTimeoutSignal(POLL_TIMEOUT_MS, signal);
-    let response;
-    try {
-      response = await fetch(`${this.baseUrl}/poll`, {
-        method: "POST",
-        headers: this.headers(),
-        body: JSON.stringify(request),
-        signal: timeoutSignal
-      });
-    } finally {
-      cleanup();
-    }
-    if (!response.ok) {
-      throw new TasksApiError(`poll falhou (HTTP ${response.status})`, response.status);
-    }
-    return this.parsePollResponse(await response.json(), request.max ?? 1);
-  }
-  /** Nunca confia no shape da resposta: runs malformadas são descartadas e o `max` é respeitado. */
-  parsePollResponse(body, max) {
-    const runs = body?.runs;
-    if (!Array.isArray(runs)) {
-      throw new TasksApiError("resposta inv\xE1lida do poll (campo runs ausente)", 0);
-    }
-    const valid = [];
-    for (const run of runs.slice(0, Math.max(0, max))) {
-      if (typeof run?.id !== "string" || typeof run.task !== "string") continue;
-      const params = run.params && typeof run.params === "object" && !Array.isArray(run.params) ? run.params : {};
-      valid.push({ ...run, id: run.id, task: run.task, params });
-    }
-    if (valid.length < runs.length) {
-      this.logger.warn(`poll retornou ${runs.length - valid.length} run(s) inv\xE1lida(s)/excedente(s) \u2014 descartadas`);
-    }
-    return { runs: valid };
+  /** Nunca confia no shape da resposta: runs malformadas são descartadas e o `max` é respeitado. */
+  parsePollResponse(body, max) {
+    const runs = body?.runs;
+    if (!Array.isArray(runs)) {
+      throw new TasksApiError("resposta inv\xE1lida do poll (campo runs ausente)", 0);
+    }
+    const valid = [];
+    for (const run of runs.slice(0, Math.max(0, max))) {
+      if (typeof run?.id !== "string" || typeof run.task !== "string") continue;
+      const params = run.params && typeof run.params === "object" && !Array.isArray(run.params) ? run.params : {};
+      valid.push({ ...run, id: run.id, task: run.task, params });
+    }
+    if (valid.length < runs.length) {
+      this.logger.warn(`poll retornou ${runs.length - valid.length} run(s) inv\xE1lida(s)/excedente(s) \u2014 descartadas`);
+    }
+    return { runs: valid };
   }
   /**
    * PATCH de status/logs com retry em falha de rede/5xx/429.
@@ -1178,12 +1019,9 @@ var TasksApi = class {
           body: JSON.stringify(request),
           signal: AbortSignal.timeout(UPDATE_TIMEOUT_MS)
         }),
-        { logger: this.logger, label: `itens da run ${runId}` }
+        { logger: this.logger, label: `itens da run ${runId}`, noRetryStatuses: ITEMS_TERMINAL_STATUSES }
       );
     } catch (error) {
-      if (error instanceof Error && error.message === "HTTP 429") {
-        throw new TasksApiError("envio de itens rejeitado (HTTP 429)", 429);
-      }
       throw new Error(`envio de itens da run ${runId} descartado ap\xF3s retries: ${String(error)}`);
     }
     if (!response.ok) {
@@ -1200,21 +1038,19 @@ var TasksApi = class {
    * "esta instalação não tem anexos" — o RunReporter degrada em silêncio a partir daí.
    */
   async createAttachment(runId, request, signal) {
-    const { signal: timeoutSignal, cleanup } = withTimeoutSignal(UPDATE_TIMEOUT_MS, signal);
-    let response;
-    try {
-      response = await fetchWithRetry(
-        () => fetch(`${this.baseUrl}/runs/${encodeURIComponent(runId)}/attachments`, {
+    const response = await fetchWithRetry(
+      () => withRequestTimeout(
+        UPDATE_TIMEOUT_MS,
+        signal,
+        (timeoutSignal) => fetch(`${this.baseUrl}/runs/${encodeURIComponent(runId)}/attachments`, {
           method: "POST",
           headers: this.headers(),
           body: JSON.stringify(request),
           signal: timeoutSignal
-        }),
-        { logger: this.logger, label: `anexo da run ${runId}` }
-      );
-    } finally {
-      cleanup();
-    }
+        })
+      ),
+      { logger: this.logger, label: `anexo da run ${runId}`, noRetryStatuses: ATTACHMENT_TERMINAL_STATUSES }
+    );
     if (!response.ok) {
       throw new TasksApiError(`cria\xE7\xE3o de anexo rejeitada (HTTP ${response.status})`, response.status);
     }
@@ -1234,22 +1070,20 @@ var TasksApi = class {
    * está na assinatura da URL, e mandar o client secret para fora da API seria vazamento.
    */
   async uploadAttachment(url, headers, body, signal) {
-    const { signal: timeoutSignal, cleanup } = withTimeoutSignal(UPLOAD_TIMEOUT_MS, signal);
-    let response;
-    try {
-      response = await fetchWithRetry(
-        () => fetch(url, {
+    const response = await fetchWithRetry(
+      () => withRequestTimeout(
+        UPLOAD_TIMEOUT_MS,
+        signal,
+        (timeoutSignal) => fetch(url, {
           method: "PUT",
           headers,
           // BodyInit não aceita Uint8Array<ArrayBufferLike> em todos os lib.dom; o buffer é o mesmo
           body,
           signal: timeoutSignal
-        }),
-        { delays: UPLOAD_RETRY_DELAYS_MS, logger: this.logger, label: "upload de anexo" }
-      );
-    } finally {
-      cleanup();
-    }
+        })
+      ),
+      { delays: UPLOAD_RETRY_DELAYS_MS, logger: this.logger, label: "upload de anexo" }
+    );
     if (!response.ok) {
       throw new TasksApiError(`upload de anexo rejeitado (HTTP ${response.status})`, response.status);
     }
@@ -1271,14 +1105,87 @@ var TasksApi = class {
   }
 };
 
-// src/tasks/attachments.ts
-var MAX_ATTACHMENT_BYTES = 5242880;
-var MAX_ATTACHMENTS_PER_RUN = 20;
-var MAX_CONCURRENT_UPLOADS = 3;
-var MAX_CAPTION_CHARS = 200;
-var ATTACHMENT_DRAIN_MS = 15e3;
-async function readImageFile(path) {
-  if (!isNode()) {
+// src/tasks/backoff.ts
+var RETRY_DELAYS_MS = [1e3, 4e3, 16e3];
+var AUTH_FAILURE_INTERVAL_MS = 3e4;
+var Backoff = class {
+  constructor(logger, label, floorMs = 0) {
+    this.logger = logger;
+    this.label = label;
+    this.floorMs = floorMs;
+  }
+  failures = 0;
+  authFailures = 0;
+  reset() {
+    this.failures = 0;
+    this.authFailures = 0;
+  }
+  next(error) {
+    if (error instanceof TasksApiError && (error.status === 401 || error.status === 402)) {
+      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"
+        );
+      }
+      return Math.max(this.floorMs, AUTH_FAILURE_INTERVAL_MS);
+    }
+    this.failures++;
+    const ladder = RETRY_DELAYS_MS[Math.min(this.failures - 1, RETRY_DELAYS_MS.length - 1)];
+    const delay = Math.min(Math.max(jitter(ladder), 0), Math.max(this.floorMs, 16e3));
+    this.logger.warn(`${this.label} falhou (${String(error)}), pr\xF3xima tentativa em ${delay}ms`);
+    return delay;
+  }
+};
+
+// src/tasks/errors.ts
+function runCanceledError() {
+  return Object.assign(new Error("execu\xE7\xE3o cancelada"), { name: "RunCanceled" });
+}
+function taskTimeoutError(timeoutMs) {
+  return Object.assign(new Error(`timeout ap\xF3s ${timeoutMs}ms (o handler pode continuar em background)`), {
+    name: "TaskTimeout"
+  });
+}
+var TERMINAL_ERROR_NAMES = /* @__PURE__ */ new Set(["RunCanceled", "AbortError", "TaskTimeout"]);
+function isTerminalError(error) {
+  return error instanceof Error && TERMINAL_ERROR_NAMES.has(error.name);
+}
+
+// src/retry.ts
+var DEFAULT_RETRIES = 3;
+var DEFAULT_DELAY_MS = 1e3;
+function resolveDelay(delay, attempt, fallbackMs) {
+  const value = typeof delay === "function" ? delay(attempt) : delay ?? fallbackMs;
+  return Number.isFinite(value) && value > 0 ? Math.floor(value) : 0;
+}
+async function retryWithBackoff(fn, options = {}) {
+  const requested = options.retries ?? DEFAULT_RETRIES;
+  const retries = Number.isFinite(requested) ? Math.max(0, Math.floor(requested)) : DEFAULT_RETRIES;
+  const wait = options.wait ?? sleep;
+  for (let attempt = 1; ; attempt++) {
+    if (options.signal?.aborted) throw runCanceledError();
+    try {
+      return await fn(attempt);
+    } catch (error) {
+      const exhausted = attempt > retries;
+      const retriable = !isTerminalError(error) && !options.signal?.aborted && (options.shouldRetry?.(error) ?? true);
+      if (exhausted || !retriable) throw error;
+      const delay = resolveDelay(options.delayMs, attempt, DEFAULT_DELAY_MS);
+      options.onRetry?.(error, attempt, delay);
+      await wait(delay);
+    }
+  }
+}
+
+// src/tasks/attachments.ts
+var MAX_ATTACHMENT_BYTES = 5242880;
+var MAX_ATTACHMENTS_PER_RUN = 20;
+var MAX_CONCURRENT_UPLOADS = 3;
+var MAX_CAPTION_CHARS = 200;
+var ATTACHMENT_DRAIN_MS = 15e3;
+async function readImageFile(path) {
+  if (!isNode()) {
     throw new Error("caminho de arquivo s\xF3 \xE9 suportado em Node");
   }
   const { readFile } = await import("fs/promises");
@@ -1289,6 +1196,7 @@ function startsWith(bytes, signature, offset = 0) {
   return signature.every((byte, index) => bytes[offset + index] === byte);
 }
 var PNG_MAGIC = [137, 80, 78, 71, 13, 10, 26, 10];
+var MAX_PNG_DIMENSION = 2e4;
 var JPEG_MAGIC = [255, 216, 255];
 var RIFF_MAGIC = [82, 73, 70, 70];
 var WEBP_MAGIC = [87, 69, 66, 80];
@@ -1304,6 +1212,7 @@ function readPngDimensions(bytes) {
   const width = view.getUint32(16);
   const height = view.getUint32(20);
   if (width === 0 || height === 0) return void 0;
+  if (width > MAX_PNG_DIMENSION || height > MAX_PNG_DIMENSION) return void 0;
   return { width, height };
 }
 async function toBytes(input) {
@@ -1320,16 +1229,17 @@ var LOG_LEVEL_COLOR = {
   error: "red",
   success: "green"
 };
+function joinLogArgs(message, rest) {
+  if (rest.length === 0) return safeString(message);
+  return [message, ...rest].map(safeString).join(" ");
+}
 function printRunLog(task, level, message) {
   const line = colorize(`[hobots:${task}] ${level.toUpperCase()}`, LOG_LEVEL_COLOR[level]);
-  const method = level === "warning" ? "warn" : level === "success" ? "info" : level;
-  console[method](line, message);
-}
-function runCanceledError() {
-  return Object.assign(new Error("execu\xE7\xE3o cancelada"), { name: "RunCanceled" });
+  const method2 = level === "warning" ? "warn" : level === "success" ? "info" : level;
+  console[method2](line, message);
 }
 function cancelableSleep(ms, signal) {
-  return new Promise((resolve, reject) => {
+  return new Promise((resolve2, reject) => {
     if (signal.aborted) {
       reject(runCanceledError());
       return;
@@ -1340,7 +1250,7 @@ function cancelableSleep(ms, signal) {
     };
     const timer = setTimeout(() => {
       signal.removeEventListener("abort", onAbort);
-      resolve();
+      resolve2();
     }, ms);
     signal.addEventListener("abort", onAbort, { once: true });
   });
@@ -1370,7 +1280,7 @@ function scrubPayloadValue(value, depth) {
   return out;
 }
 var RunReporter = class {
-  constructor(api, runId, task, logger, tx, flushIntervalMs, cancelCheckIntervalMs) {
+  constructor(api, runId, task, logger, tx, flushIntervalMs, cancelCheckIntervalMs, params = {}) {
     this.api = api;
     this.runId = runId;
     this.logger = logger;
@@ -1380,24 +1290,47 @@ var RunReporter = class {
       Math.max(MIN_CANCEL_CHECK_INTERVAL_MS, cancelCheckIntervalMs ?? DEFAULT_CANCEL_CHECK_INTERVAL_MS)
     );
     const log = {
-      debug: (message) => this.log("debug", message),
-      info: (message) => this.log("info", message),
-      warn: (message) => this.log("warning", message),
-      error: (message) => this.log("error", message),
-      success: (message) => this.log("success", message)
+      debug: (message, ...rest) => this.log("debug", joinLogArgs(message, rest)),
+      info: (message, ...rest) => this.log("info", joinLogArgs(message, rest)),
+      warn: (message, ...rest) => this.log("warning", joinLogArgs(message, rest)),
+      error: (message, ...rest) => this.log("error", joinLogArgs(message, rest)),
+      success: (message, ...rest) => this.log("success", joinLogArgs(message, rest))
     };
     tx.setLifecycleSink((level, message) => this.push(level, message));
+    const checkCanceled = () => this.checkCanceled();
+    tx.setStepGuard(checkCanceled);
     const items = {
-      add: (item) => this.addItem(item.status, item.message, item.payload, item.id),
-      succeeded: (payload, options) => this.addItem("succeeded", void 0, payload, options?.id),
-      failed: (message, payload, options) => this.addItem("failed", message, payload, options?.id),
-      occurrence: (message, payload, options) => this.addItem("occurrence", message, payload, options?.id)
+      add: (item) => {
+        checkCanceled();
+        this.addItem(item.status, item.message, item.payload, item.id);
+      },
+      succeeded: (payload, options) => {
+        checkCanceled();
+        this.addItem("succeeded", void 0, payload, options?.id);
+      },
+      failed: (message, payload, options) => {
+        checkCanceled();
+        this.addItem("failed", message, payload, options?.id);
+      },
+      occurrence: (message, payload, options) => {
+        checkCanceled();
+        this.addItem("occurrence", message, payload, options?.id);
+      }
     };
     const progress = Object.defineProperties(
       {
-        total: (total) => this.setProgress(this.progressCurrent, total),
-        advance: (count = 1) => this.setProgress(this.progressCurrent + count, this.progressTotal),
-        set: (current, total) => this.setProgress(current, total ?? this.progressTotal)
+        total: (total) => {
+          checkCanceled();
+          this.setProgress(this.progressCurrent, total);
+        },
+        advance: (count = 1) => {
+          checkCanceled();
+          this.setProgress(this.progressCurrent + count, this.progressTotal);
+        },
+        set: (current, total) => {
+          checkCanceled();
+          this.setProgress(current, total ?? this.progressTotal);
+        }
       },
       {
         current: { enumerable: true, get: () => this.progressCurrent },
@@ -1409,18 +1342,20 @@ var RunReporter = class {
       // defineProperties não tipa os getters adicionados — a interface é a fonte de verdade
     );
     const signal = this.abortController.signal;
+    const sleep2 = (ms) => cancelableSleep(ms, signal);
     this.context = {
       runId,
       task,
+      params,
       log,
       items,
       progress,
-      tx,
+      transaction: tx,
       signal,
-      throwIfCanceled: () => {
-        if (signal.aborted) throw runCanceledError();
-      },
-      sleep: (ms) => cancelableSleep(ms, signal)
+      throwIfCanceled: checkCanceled,
+      sleep: sleep2,
+      attach: (image, options) => this.attach(image, options),
+      retry: (fn, options) => retryWithBackoff(fn, { ...options, signal, wait: sleep2 })
     };
   }
   context;
@@ -1469,6 +1404,10 @@ var RunReporter = class {
   get isDead() {
     return this.dead;
   }
+  /** Lança `RunCanceled` se o signal desta run já disparou. */
+  checkCanceled() {
+    if (this.abortController.signal.aborted) throw runCanceledError();
+  }
   /** Aborta o ctx.signal sem matar o reporter (timeout/shutdown ainda reportam o terminal). */
   abort() {
     this.stopCancelWatch();
@@ -1505,7 +1444,7 @@ var RunReporter = class {
   }
   log(level, message) {
     if (this.dead) return;
-    const scrubbed = scrubSecrets(message);
+    const scrubbed = scrubSecrets(safeString(message));
     printRunLog(this.context.task, level, scrubbed);
     this.push(level, scrubbed, true);
   }
@@ -1564,13 +1503,25 @@ var RunReporter = class {
     this.stopCancelWatch();
     this.clearFlushTimer();
     this.forceFinalProgress();
-    this.enqueue({ status: "succeeded", logs: this.takeLogs() });
+    this.enqueue({ status: "succeeded", logs: this.takeLogsForTerminal() });
   }
   reportFailure(error) {
     this.stopCancelWatch();
     this.clearFlushTimer();
     this.forceFinalProgress();
-    this.enqueue({ status: "failed", error, logs: this.takeLogs() });
+    this.enqueue({ status: "failed", error, logs: this.takeLogsForTerminal() });
+  }
+  /**
+   * Esvazia o buffer para o PATCH terminal respeitando o teto de 100 logs por PATCH:
+   * o excedente sai antes, em PATCHes `running` na mesma cadeia (a ordem se mantém).
+   */
+  takeLogsForTerminal() {
+    let logs = this.takeLogs();
+    while (logs.length > MAX_LOGS_PER_PATCH) {
+      this.enqueue({ status: "running", logs: logs.slice(0, MAX_LOGS_PER_PATCH) });
+      logs = logs.slice(MAX_LOGS_PER_PATCH);
+    }
+    return logs;
   }
   // ── Progresso ────────────────────────────────────────────────────────────────
   /** Valida, clampa e marca o snapshot como pendente; agenda flush só se nada mais vai sair. */
@@ -1678,7 +1629,7 @@ var RunReporter = class {
       id: id ? truncate(String(id), 255) : uuid4(),
       seq: this.itemSeq++,
       status,
-      ...message ? { message: truncate(scrubSecrets(message), MAX_ITEM_MESSAGE_CHARS) } : {},
+      ...message ? { message: truncate(scrubSecrets(safeString(message)), MAX_ITEM_MESSAGE_CHARS) } : {},
       ...scrubbedPayload ? { payload: scrubbedPayload } : {},
       ts: nowISO()
     });
@@ -1747,13 +1698,13 @@ var RunReporter = class {
     this.flushItems();
     await Promise.race([
       this.itemsChain,
-      new Promise((resolve) => unrefTimer(setTimeout(resolve, timeoutMs)))
+      new Promise((resolve2) => unrefTimer(setTimeout(resolve2, timeoutMs)))
     ]);
     if (this.itemsBuffer.length > 0 && !this.itemsUnsupported && !this.itemsQuotaExceeded) {
       this.flushItems();
       await Promise.race([
         this.itemsChain,
-        new Promise((resolve) => unrefTimer(setTimeout(resolve, timeoutMs)))
+        new Promise((resolve2) => unrefTimer(setTimeout(resolve2, timeoutMs)))
       ]);
     }
   }
@@ -1761,14 +1712,16 @@ var RunReporter = class {
   /**
    * Registra a linha de log com o id do anexo (síncrono, na ordem certa) e dispara
    * o upload em segundo plano. Nunca lança: todo caminho de erro vira `{ ok: false }`
-   * com um aviso no log da run. Chega ao handler pelos capture* do SDK — o hint
-   * `attachment` de Hobots.captureException/captureMessage cai aqui via run-context-store.
+   * com um aviso no log da run. É o `hobots.attach()`; o hint `attachment` de
+   * `hobots.captureException` também cai aqui via run-context-store.
    */
   async attach(image, options = {}) {
     const id = uuid4();
     const level = options.level ?? "info";
-    const caption = options.caption ? truncate(scrubSecrets(options.caption), MAX_CAPTION_CHARS) : void 0;
-    const message = options.message ?? options.caption ?? "captura de tela";
+    const rawCaption = options.caption !== void 0 ? safeString(options.caption) : void 0;
+    const rawMessage = options.message !== void 0 ? safeString(options.message) : void 0;
+    const caption = rawCaption ? truncate(scrubSecrets(rawCaption), MAX_CAPTION_CHARS) : void 0;
+    const message = rawMessage ?? rawCaption ?? "captura de tela";
     if (this.dead) return { id, ok: false, reason: "canceled" };
     if (this.attachmentsUnsupported) {
       this.log(level, message);
@@ -1784,8 +1737,8 @@ var RunReporter = class {
     printRunLog(this.context.task, level, `${scrubbed} [imagem]`);
     const logTs = this.push(level, scrubbed, true, [id]);
     let settle;
-    const result = new Promise((resolve) => {
-      settle = resolve;
+    const result = new Promise((resolve2) => {
+      settle = resolve2;
     });
     const work = this.uploadAttachment(id, image, { caption, logTs, contentType: options.contentType }).then((reason) => settle(reason ? { id, ok: false, reason } : { id, ok: true })).catch(() => settle({ id, ok: false, reason: "upload-failed" }));
     this.pendingAttachments.add(work);
@@ -1867,8 +1820,8 @@ var RunReporter = class {
       this.uploadSlots--;
       return Promise.resolve(release);
     }
-    return new Promise((resolve) => {
-      this.uploadQueue.push(() => resolve(release));
+    return new Promise((resolve2) => {
+      this.uploadQueue.push(() => resolve2(release));
     });
   }
   /**
@@ -1879,7 +1832,7 @@ var RunReporter = class {
     if (this.pendingAttachments.size === 0) return;
     await Promise.race([
       Promise.allSettled([...this.pendingAttachments]),
-      new Promise((resolve) => unrefTimer(setTimeout(resolve, timeoutMs)))
+      new Promise((resolve2) => unrefTimer(setTimeout(resolve2, timeoutMs)))
     ]);
   }
   enqueue(updateIn) {
@@ -1950,166 +1903,371 @@ async function runWithRunContext(store, fn) {
   await ensureStorage();
   return storage ? storage.run(store, fn) : fn();
 }
-function currentRunTransaction() {
-  return storage?.getStore()?.tx;
-}
-function currentRunAttach() {
-  return storage?.getStore()?.attach;
+function currentRunReporter() {
+  return storage?.getStore()?.reporter;
 }
 
-// src/tasks/shutdown.ts
-var WATCHED_SIGNALS = ["SIGINT", "SIGTERM"];
-function installShutdownHandlers(agent2) {
-  if (!isNode()) return () => {
-  };
-  let signaled = false;
-  const signalHandlers = /* @__PURE__ */ new Map();
-  for (const signal of WATCHED_SIGNALS) {
-    const handler = markInternal(() => {
-      if (externalListenerCount(signal) > 0) return;
-      if (signaled) return;
-      signaled = true;
-      const reraise = () => {
-        process.removeListener(signal, handler);
-        process.kill(process.pid, signal);
-      };
-      if (agent2.activeCount === 0) {
-        reraise();
-        return;
-      }
-      const report = agent2.reportAgentTerminated(`o processo do agente recebeu ${signal} durante a execu\xE7\xE3o`);
-      addEmergencyTask(report);
-      void report.finally(reraise);
-    });
-    process.on(signal, handler);
-    signalHandlers.set(signal, handler);
+// src/transaction.ts
+function stepId() {
+  return uuid4().slice(0, 16);
+}
+function stepLabel(op, description) {
+  return [op, description].filter(Boolean).join(" \u2014 ") || "(sem nome)";
+}
+function levelForStatus(status) {
+  switch (status) {
+    case "warning":
+      return "warning";
+    case "error":
+      return "error";
+    case "cancelled":
+      return "warning";
+    default:
+      return "success";
   }
-  const onFatal = markInternal((error) => {
-    const report = agent2.activeCount > 0 ? agent2.reportAgentTerminated("o processo do agente morreu com um erro n\xE3o tratado durante a execu\xE7\xE3o") : Promise.resolve();
-    addEmergencyTask(report);
-    if (!hasInstalledGlobalHandlers() && externalListenerCount("uncaughtException") === 0) {
-      void report.finally(() => {
-        console.error(error);
-        process.exit(1);
-      });
-    }
-  });
-  process.on("uncaughtException", onFatal);
-  return () => {
-    for (const [signal, handler] of signalHandlers) process.removeListener(signal, handler);
-    process.removeListener("uncaughtException", onFatal);
-  };
 }
-
-// src/tasks/agent.ts
-var DEFAULT_POLL_INTERVAL_MS = 2e3;
-var MIN_POLL_INTERVAL_MS = 1e3;
-var MAX_CONCURRENCY = 5;
-var POLL_RETRY_DELAYS_MS = [1e3, 4e3, 16e3];
-var AUTH_FAILURE_INTERVAL_MS = 3e4;
-var DEFAULT_CANCEL_GRACE_MS = 1e4;
-function hostname() {
-  if (!isNode()) return void 0;
-  return process.env.HOSTNAME || process.env.COMPUTERNAME || void 0;
+function colorForStatus(status) {
+  switch (status) {
+    case "warning":
+      return "yellow";
+    case "error":
+      return "red";
+    case "cancelled":
+      return "gray";
+    default:
+      return "green";
+  }
 }
-var TaskAgent = class {
-  constructor(options, registry2) {
-    this.options = options;
-    this.registry = registry2;
-    this.logger = makeLogger(options.debug ?? false);
-    const config = options.config;
-    this.api = new TasksApi({ baseUrl: config.tasksBaseUrl, key: config.key, logger: this.logger });
-    this.client = options.client;
-    this.pollIntervalMs = Math.max(MIN_POLL_INTERVAL_MS, options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS);
-    this.concurrency = Math.min(MAX_CONCURRENCY, Math.max(1, options.concurrency ?? 1));
-    this.instanceId = options.instanceId;
-    this.taskTimeoutMs = options.taskTimeoutMs;
-    this.logFlushIntervalMs = options.logFlushIntervalMs;
-    this.cancelCheckIntervalMs = options.cancelCheckIntervalMs;
-    this.cancelGraceMs = options.cancelGraceMs ?? DEFAULT_CANCEL_GRACE_MS;
-    this.logger.debug("agente configurado", { baseUrl: config.tasksBaseUrl });
+var Step = class {
+  constructor(transaction, parentStepId, op, description) {
+    this.transaction = transaction;
+    this.parentStepId = parentStepId;
+    this.op = op;
+    this.description = description;
   }
-  logger;
-  api;
-  client;
-  pollIntervalMs;
-  concurrency;
-  instanceId;
-  taskTimeoutMs;
-  logFlushIntervalMs;
-  cancelCheckIntervalMs;
-  cancelGraceMs;
-  state = "idle";
-  timer;
-  pollAbort;
-  consecutiveFailures = 0;
-  consecutiveAuthFailures = 0;
-  activeRuns = /* @__PURE__ */ new Set();
-  reporters = /* @__PURE__ */ new Set();
-  uninstallShutdown;
-  get activeCount() {
-    return this.activeRuns.size;
+  stepId = stepId();
+  startTimestamp = nowISO();
+  status = "ok";
+  endTimestamp;
+  data;
+  setStatus(status) {
+    this.status = status;
+    return this;
   }
-  start() {
-    if (this.state === "started") return;
-    if (this.state === "stopping") {
-      throw new Error("[hobots] start() chamado durante stop() \u2014 aguarde o stop terminar");
-    }
-    if (this.registry.size === 0) {
-      throw new Error("[hobots] nenhuma task registrada \u2014 chame register() antes de start()");
-    }
-    this.state = "started";
-    if (this.options.installExitHandlers !== false && !this.uninstallShutdown) {
-      this.uninstallShutdown = installShutdownHandlers(this);
-    }
-    this.logger.debug(`polling iniciado (tasks: ${[...this.registry.keys()].join(", ")})`);
-    this.schedule(0);
+  setData(key, value) {
+    this.data = { ...this.data, [key]: value };
+    return this;
   }
-  /** Para o polling e aguarda as runs ativas (até timeoutMs). Retorna true se tudo terminou a tempo. */
-  async stop(timeoutMs = 3e4) {
-    if (this.state === "idle") return true;
-    this.state = "stopping";
-    if (this.timer) {
-      clearTimeout(this.timer);
-      this.timer = void 0;
-    }
-    this.pollAbort?.abort();
-    const all = Promise.allSettled([...this.activeRuns]).then(() => true);
-    const finished = timeoutMs > 0 ? await Promise.race([all, sleep(timeoutMs).then(() => false)]) : false;
-    if (!finished && this.activeRuns.size > 0) {
-      this.logger.warn(`${this.activeRuns.size} run(s) ainda em execu\xE7\xE3o ap\xF3s ${timeoutMs}ms \u2014 abandonando a espera`);
-      await this.reportAgentTerminated("agente encerrado durante a execu\xE7\xE3o (shutdown excedeu o tempo de espera)");
-    }
-    this.uninstallShutdown?.();
-    this.uninstallShutdown = void 0;
-    this.state = "idle";
-    return finished;
+  /** Step aninhada (filha desta step). */
+  startChild(op, description) {
+    return this.transaction.createStep(this.stepId, op, description);
+  }
+  finish() {
+    if (this.endTimestamp) return;
+    this.endTimestamp = nowISO();
+    this.transaction.emit(
+      "step",
+      "finish",
+      stepLabel(this.op, this.description),
+      this.startTimestamp,
+      this.endTimestamp,
+      this.status
+    );
+  }
+  toJSON() {
+    return {
+      step_id: this.stepId,
+      parent_step_id: this.parentStepId,
+      op: this.op,
+      description: this.description,
+      status: this.status,
+      start_timestamp: this.startTimestamp,
+      timestamp: this.endTimestamp ?? nowISO(),
+      data: this.data
+    };
+  }
+};
+var Transaction = class {
+  constructor(client, name, op, runId) {
+    this.client = client;
+    this.name = name;
+    this.op = op;
+    this.runId = runId;
+    this.emit("transaction", "start", op ? `${name} (${op})` : name);
   }
+  eventId = uuid4();
+  stepId = stepId();
+  startTimestamp = nowISO();
+  status = "ok";
+  steps = [];
+  tags = {};
+  finished = false;
+  lifecycleSink;
+  // instalado pelo RunReporter: abrir uma step é um ponto de parada cooperativo (lança RunCanceled)
+  stepGuard;
+  // eventos emitidos antes do sink existir (o START da transaction sai no construtor,
+  // antes do RunReporter conectar) — replay no setLifecycleSink
+  lifecycleBacklog = [];
   /**
-   * Best-effort do exit path: reporta 'failed'/AgentTerminated para as runs ativas
-   * antes do processo morrer, fora da fila do reporter e com timeout curto. Runs já
-   * canceladas no app (reporter morto) são puladas; erros de rede são engolidos —
-   * o sweep server-side é o backstop.
+   * 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.
    */
-  async reportAgentTerminated(message, timeoutMs = 2500) {
-    const pending = [];
-    for (const reporter of this.reporters) {
-      if (reporter.isDead) continue;
-      const logs = reporter.drainLogs();
-      reporter.kill();
-      pending.push(
-        this.api.updateRunOnce(
-          reporter.context.runId,
-          { status: "failed", error: { type: "AgentTerminated", message }, logs: logs.length > 0 ? logs : void 0 },
-          timeoutMs
-        ).catch(() => {
-        })
-      );
+  emit(kind, phase, label, startTs, endTs, status) {
+    const durationMs = startTs && endTs ? new Date(endTs).getTime() - new Date(startTs).getTime() : void 0;
+    const suffix = durationMs != null ? ` (${durationMs}ms)` : "";
+    if (this.client?.debug) {
+      const tag = colorize(`[hobots:${kind}] ${phase.toUpperCase()}`, phase === "finish" ? colorForStatus(status ?? "ok") : "cyan");
+      console.log(`${tag} ${label}${suffix}`);
     }
-    if (pending.length === 0) return;
-    await Promise.race([Promise.allSettled(pending), sleep(timeoutMs)]);
-  }
-  /** Timer intencionalmente NÃO unref'd: o agente é a razão do processo existir. */
+    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]);
+  }
+  /** Conecta o espelho de lifecycle (RunReporter) e faz replay do backlog em ordem. */
+  setLifecycleSink(sink) {
+    this.lifecycleSink = sink;
+    const backlog = this.lifecycleBacklog;
+    this.lifecycleBacklog = [];
+    for (const [level, message] of backlog) sink(level, message);
+  }
+  /**
+   * Conecta a checagem de cancelamento chamada antes de cada step nova — é assim que
+   * `hobots.transaction.startChild()` (e `step.startChild()`) param uma run cancelada.
+   */
+  setStepGuard(guard) {
+    this.stepGuard = guard;
+  }
+  createStep(parentStepId, op, description) {
+    this.stepGuard?.();
+    const step = new Step(this, parentStepId, 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);
+  }
+  setTag(key, value) {
+    this.tags[key] = value;
+    return this;
+  }
+  setStatus(status) {
+    this.status = status;
+    return this;
+  }
+  setName(name) {
+    this.name = name;
+    return this;
+  }
+  finish() {
+    if (this.finished) return;
+    this.finished = true;
+    for (const step of this.steps) step.finish();
+    const endTimestamp = nowISO();
+    this.emit(
+      "transaction",
+      "finish",
+      this.op ? `${this.name} (${this.op})` : this.name,
+      this.startTimestamp,
+      endTimestamp,
+      this.status
+    );
+    if (!this.client) return;
+    const payload = {
+      event_id: this.eventId,
+      name: this.name,
+      op: this.op,
+      status: this.status,
+      start_timestamp: this.startTimestamp,
+      timestamp: endTimestamp,
+      steps: this.steps.map((step) => step.toJSON()),
+      tags: Object.keys(this.tags).length > 0 ? this.tags : void 0,
+      run_id: this.runId
+    };
+    this.client.sendTransaction(payload);
+  }
+};
+
+// src/tasks/runner.ts
+var DEFAULT_RETRY_DELAY_MS = 5e3;
+async function executeRun(input) {
+  const { run, task, api, client, logger, tracker } = input;
+  const options = task.options;
+  const tx = new Transaction(client, `run:${run.task}`, "hobots.task", run.id);
+  const reporter = new RunReporter(
+    api,
+    run.id,
+    run.task,
+    logger,
+    tx,
+    options.logFlushIntervalMs,
+    options.cancelCheckIntervalMs,
+    run.params
+  );
+  tracker.add(reporter);
+  try {
+    const ok = await reporter.reportRunning();
+    if (!ok) {
+      logger.debug(`run ${run.id} cancelada antes de iniciar \u2014 handler n\xE3o executado`);
+      tx.setStatus("cancelled");
+      tx.finish();
+      return;
+    }
+    logger.debug(`executando run ${run.id} (${run.task})`);
+    try {
+      await runWithRunContext({ reporter }, () => invokeWithRetry(task, run, reporter, logger));
+      await reporter.finalizeAttachments();
+      await reporter.finalizeItems();
+      tx.setStatus("ok");
+      tx.finish();
+      reporter.reportSuccess();
+      logger.debug(`run ${run.id} conclu\xEDda`);
+    } catch (error) {
+      await reporter.finalizeAttachments();
+      await reporter.finalizeItems();
+      tx.setStatus("error");
+      tx.finish();
+      reporter.reportFailure(toRunError(error));
+      logger.debug(`run ${run.id} falhou: ${String(error)}`);
+    }
+    await reporter.finalize();
+  } finally {
+    tracker.remove(reporter);
+  }
+}
+function invokeWithRetry(task, run, reporter, logger) {
+  const { retries, retryDelayMs } = task.options;
+  const total = retries + 1;
+  const ctx = reporter.context;
+  return retryWithBackoff(() => invokeWithTimeout(task, run, reporter, logger), {
+    retries,
+    delayMs: (attempt) => resolveDelay(retryDelayMs, attempt, DEFAULT_RETRY_DELAY_MS),
+    shouldRetry: () => !reporter.isDead,
+    signal: ctx.signal,
+    wait: (ms) => ctx.sleep(ms),
+    onRetry: (error, attempt, delayMs) => {
+      const reason = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+      ctx.log.warn(`tentativa ${attempt}/${total} falhou: ${truncate(reason, 500)} \u2014 nova tentativa em ${delayMs}ms`);
+    }
+  });
+}
+var TIMEOUT_SENTINEL = /* @__PURE__ */ Symbol("task-timeout");
+var CANCEL_SENTINEL = /* @__PURE__ */ Symbol("task-canceled");
+async function invokeWithTimeout(task, run, reporter, logger) {
+  const { timeoutMs, cancelGraceMs } = task.options;
+  const handler = task.handler;
+  const invocation = Promise.resolve().then(() => handler(run.params, reporter.context));
+  const races = [];
+  if (timeoutMs && timeoutMs > 0) {
+    races.push(sleep(timeoutMs).then(() => TIMEOUT_SENTINEL));
+  }
+  if (cancelGraceMs > 0) {
+    races.push(waitForCancelGrace(reporter.context.signal, cancelGraceMs).then(() => CANCEL_SENTINEL));
+  }
+  if (races.length === 0) {
+    await invocation;
+    return;
+  }
+  const outcome = await Promise.race([invocation, ...races]);
+  if (outcome !== TIMEOUT_SENTINEL && outcome !== CANCEL_SENTINEL) return;
+  if (outcome === CANCEL_SENTINEL) {
+    logger.warn(
+      `run ${run.id} cancelada \u2014 handler n\xE3o respondeu a hobots.signal em ${cancelGraceMs}ms, liberando o slot (o handler pode continuar rodando em segundo plano)`
+    );
+    return;
+  }
+  reporter.abort();
+  invocation.then(() => logger.warn(`run ${run.id} terminou depois do timeout de ${timeoutMs}ms`)).catch(() => logger.warn(`run ${run.id} falhou depois do timeout de ${timeoutMs}ms (erro descartado)`));
+  throw taskTimeoutError(timeoutMs);
+}
+function waitForCancelGrace(signal, graceMs) {
+  return new Promise((resolve2) => {
+    if (signal.aborted) {
+      setTimeout(resolve2, graceMs);
+      return;
+    }
+    signal.addEventListener("abort", () => setTimeout(resolve2, graceMs), { once: true });
+  });
+}
+var MAX_ERROR_MESSAGE_CHARS = 1e4;
+var MAX_ERROR_STACK_CHARS = 2e4;
+function toRunError(error) {
+  if (error instanceof Error) {
+    return {
+      type: error.name,
+      message: scrubSecrets(truncate(error.message, MAX_ERROR_MESSAGE_CHARS)),
+      stack: error.stack ? scrubSecrets(truncate(error.stack, MAX_ERROR_STACK_CHARS)) : void 0
+    };
+  }
+  return { message: scrubSecrets(truncate(String(error), MAX_ERROR_MESSAGE_CHARS)) };
+}
+
+// src/tasks/agent.ts
+var DEFAULT_POLL_INTERVAL_MS = 2e3;
+var MIN_POLL_INTERVAL_MS = 1e3;
+var MAX_CLAIM_PER_POLL = 5;
+var TaskAgent = class {
+  constructor(options) {
+    this.options = options;
+    this.logger = options.logger;
+    this.api = options.api;
+    this.client = options.client;
+    this.registry = options.registry;
+    this.tracker = options.tracker;
+    this.pollIntervalMs = Math.max(MIN_POLL_INTERVAL_MS, options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS);
+    this.backoff = new Backoff(this.logger, "poll", this.pollIntervalMs);
+  }
+  logger;
+  pollIntervalMs;
+  api;
+  client;
+  registry;
+  tracker;
+  backoff;
+  state = "idle";
+  timer;
+  pollAbort;
+  activeRuns = /* @__PURE__ */ new Set();
+  get activeCount() {
+    return this.activeRuns.size;
+  }
+  start() {
+    if (this.state === "started") return;
+    if (this.state === "stopping") {
+      throw new Error("[hobots] start do agente durante o stop \u2014 aguarde o stop terminar");
+    }
+    this.state = "started";
+    this.logger.debug(`polling iniciado (tasks: ${this.registry.remoteTasks().map((task) => task.slug).join(", ")})`);
+    this.schedule(0);
+  }
+  /** Uma task registrada depois do boot entra no próximo poll — que é antecipado para já. */
+  wake() {
+    if (this.state !== "started") return;
+    if (this.timer) {
+      clearTimeout(this.timer);
+      this.timer = void 0;
+    }
+    this.schedule(0);
+  }
+  /** Para o polling e aguarda as runs ativas (até timeoutMs). Retorna true se tudo terminou a tempo. */
+  async stop(timeoutMs = 3e4) {
+    if (this.state === "idle") return true;
+    this.state = "stopping";
+    if (this.timer) {
+      clearTimeout(this.timer);
+      this.timer = void 0;
+    }
+    this.pollAbort?.abort();
+    const all = Promise.allSettled([...this.activeRuns]).then(() => true);
+    const finished = timeoutMs > 0 ? await Promise.race([all, sleep(timeoutMs).then(() => false)]) : this.activeRuns.size === 0;
+    this.state = "idle";
+    return finished;
+  }
+  /** Timer intencionalmente NÃO unref'd: o agente é a razão do processo existir. */
   schedule(delayMs) {
     if (this.state !== "started" || this.timer) return;
     this.timer = setTimeout(() => {
@@ -2117,9 +2275,22 @@ var TaskAgent = class {
       void this.tick();
     }, delayMs);
   }
+  /** Slots livres por task remota — a soma vira o `max` do poll e as tasks com slot viram o filtro. */
+  freeSlots() {
+    const tasks = [];
+    let max = 0;
+    for (const task of this.registry.remoteTasks()) {
+      const free = task.options.concurrency - this.tracker.activeFor(task.slug);
+      if (free <= 0) continue;
+      tasks.push(task.slug);
+      max += free;
+    }
+    return { tasks, max: Math.min(MAX_CLAIM_PER_POLL, max) };
+  }
   async tick() {
     if (this.state !== "started") return;
-    if (this.activeRuns.size >= this.concurrency) {
+    const { tasks, max } = this.freeSlots();
+    if (max === 0) {
       this.schedule(this.pollIntervalMs);
       return;
     }
@@ -2127,224 +2298,498 @@ var TaskAgent = class {
     try {
       const response = await this.api.poll(
         {
-          instance: {
-            // identidade canônica do agente no painel — o mesmo instanceId do
-            // heartbeat da Telemetria, então os dois canais convergem em um agente
-            instance_id: this.instanceId,
-            version: SDK_VERSION,
-            host: hostname(),
-            // ambiente da instância: em agentes poll-only (sem heartbeat) este é o
-            // único canal por onde o servidor descobre onde o robô está rodando
-            environment: this.options.environment,
-            tasks: [...this.registry.keys()],
-            // o servidor calcula a tolerância de offline (3×) a partir disto em
-            // agentes poll-only — sem o campo, um poll lento flaparia offline/online.
-            // Clampado à faixa aceita pelo schema do poll (1s..15min).
-            poll_interval_ms: Math.min(Math.max(this.pollIntervalMs, 1e3), 9e5),
-            // recursos da máquina — alimenta a série da instância em agentes sem heartbeat
-            // (o servidor grava no máx. 1 ponto/30s por instância)
-            machine: this.options.machineSampler?.sample()
-          },
-          max: Math.min(MAX_CONCURRENCY, this.concurrency - this.activeRuns.size),
-          tasks: [...this.registry.keys()]
+          // identidade canônica do agente no painel — o mesmo instanceId do heartbeat,
+          // então os dois canais convergem em um agente. `instance.tasks` lista TODAS as
+          // tasks (register + start); o filtro `tasks` abaixo só as que este poll pode rodar.
+          instance: this.options.instanceInfo(),
+          max,
+          tasks
         },
         this.pollAbort.signal
       );
-      this.consecutiveFailures = 0;
-      this.consecutiveAuthFailures = 0;
+      this.backoff.reset();
       for (const run of response.runs) {
-        if (this.activeRuns.size >= this.concurrency) break;
         this.dispatch(run);
       }
       this.schedule(response.runs.length > 0 ? 0 : this.pollIntervalMs);
     } catch (error) {
       if (this.state !== "started") return;
-      this.schedule(this.delayAfterPollError(error));
+      this.schedule(this.backoff.next(error));
     } finally {
       this.pollAbort = void 0;
     }
   }
-  delayAfterPollError(error) {
-    if (error instanceof TasksApiError && error.status === 401) {
-      this.consecutiveAuthFailures++;
-      if (this.consecutiveAuthFailures === 1 || this.consecutiveAuthFailures % 10 === 0) {
-        this.logger.error("chave rejeitada (401) \u2014 verifique o Client Secret do agente em Configura\xE7\xF5es \u2192 Agentes");
-      }
-      return Math.max(this.pollIntervalMs, AUTH_FAILURE_INTERVAL_MS);
-    }
-    this.consecutiveFailures++;
-    const ladder = POLL_RETRY_DELAYS_MS[Math.min(this.consecutiveFailures - 1, POLL_RETRY_DELAYS_MS.length - 1)];
-    const delay = Math.min(Math.max(jitter(ladder), 0), Math.max(this.pollIntervalMs, 16e3));
-    this.logger.warn(`poll falhou (${String(error)}), pr\xF3xima tentativa em ${delay}ms`);
-    return delay;
-  }
   dispatch(run) {
-    const promise = this.executeRun(run).catch((error) => this.logger.error(`erro inesperado na run ${run.id}:`, error)).finally(() => {
+    const promise = this.executeClaimed(run).catch((error) => this.logger.error(`erro inesperado na run ${run.id}:`, error)).finally(() => {
       this.activeRuns.delete(promise);
       if (this.state === "started") this.schedule(0);
     });
     this.activeRuns.add(promise);
   }
-  async executeRun(run) {
-    const tx = new Transaction(this.client, `run:${run.task}`, "hobots.task", true, run.id);
-    const reporter = new RunReporter(this.api, run.id, run.task, this.logger, tx, this.logFlushIntervalMs, this.cancelCheckIntervalMs);
-    this.reporters.add(reporter);
+  async executeClaimed(run) {
+    const task = this.registry.get(run.task);
+    if (!task || task.mode !== "remote") {
+      const tx = new Transaction(this.client, `run:${run.task}`, "hobots.task", run.id);
+      const reporter = new RunReporter(this.api, run.id, run.task, this.logger, tx);
+      reporter.reportFailure(toRunError(Object.assign(new Error(`tarefa n\xE3o registrada no agente: ${run.task}`), { name: "HandlerNotFound" })));
+      await reporter.finalize();
+      tx.setStatus("error");
+      tx.finish();
+      return;
+    }
+    await executeRun({ run, task, api: this.api, client: this.client, logger: this.logger, tracker: this.tracker });
+  }
+};
+
+// src/tasks/item-columns.ts
+var KEY_RE = /^[a-zA-Z0-9_.-]{1,100}$/;
+var MAX_COLUMNS = 12;
+var MAX_LABEL_CHARS = 60;
+function normalizeItemColumns(slug, input, logger) {
+  if (input === void 0 || input === null) return void 0;
+  const columns = input.columns;
+  if (typeof input !== "object" || !Array.isArray(columns)) {
+    logger.warn(`task "${slug}": items.columns precisa ser uma lista \u2014 declara\xE7\xE3o de colunas ignorada`);
+    return void 0;
+  }
+  const result = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const entry of columns) {
+    const rawKey = typeof entry === "string" ? entry : entry?.key;
+    const rawLabel = typeof entry === "object" && entry !== null ? entry.label : void 0;
+    const key = typeof rawKey === "string" ? rawKey.trim() : "";
+    if (!KEY_RE.test(key)) {
+      logger.warn(`task "${slug}": coluna de item inv\xE1lida ignorada (${JSON.stringify(rawKey)}) \u2014 use letras, n\xFAmeros, ponto, h\xEDfen e underline`);
+      continue;
+    }
+    if (seen.has(key)) {
+      logger.warn(`task "${slug}": coluna de item "${key}" repetida ignorada`);
+      continue;
+    }
+    if (result.length >= MAX_COLUMNS) {
+      logger.warn(`task "${slug}": no m\xE1ximo ${MAX_COLUMNS} colunas de item \u2014 "${key}" em diante ignoradas`);
+      break;
+    }
+    seen.add(key);
+    const label = typeof rawLabel === "string" ? rawLabel.trim().slice(0, MAX_LABEL_CHARS) : "";
+    result.push(label ? { key, label } : { key });
+  }
+  return result.length > 0 ? result : void 0;
+}
+
+// src/tasks/local.ts
+var LocalRunner = class {
+  constructor(task, deps) {
+    this.task = task;
+    this.deps = deps;
+    this.backoff = new Backoff(deps.logger, `cria\xE7\xE3o da run "${task.slug}"`);
+    this.done = new Promise((resolve2) => {
+      this.resolveDone = resolve2;
+    });
+  }
+  abort = new AbortController();
+  backoff;
+  /** Resolve quando a run terminou (ou o runner foi parado antes de abri-la). */
+  done;
+  resolveDone;
+  async run() {
     try {
-      const handler = this.registry.get(run.task);
-      if (!handler) {
-        reporter.reportFailure({
-          type: "HandlerNotFound",
-          message: `tarefa n\xE3o registrada no agente: ${run.task}`
-        });
-        await reporter.finalize();
-        tx.setStatus("error");
-        tx.finish();
-        return;
-      }
-      const ok = await reporter.reportRunning();
-      if (!ok) {
-        this.logger.debug(`run ${run.id} cancelada antes de iniciar \u2014 handler n\xE3o executado`);
-        tx.setStatus("cancelled");
-        tx.finish();
-        return;
-      }
-      this.logger.debug(`executando run ${run.id} (${run.task})`);
+      const run = await this.createRun();
+      if (!run) return;
+      this.deps.logger.debug(`run ${run.id} aberta para "${this.task.slug}" (modo start)`);
+      await executeRun({
+        run,
+        task: this.task,
+        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 task "${this.task.slug}":`, 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();
+  }
+  async createRun() {
+    for (; ; ) {
+      if (this.abort.signal.aborted) return void 0;
       try {
-        await runWithRunContext(
-          { runId: run.id, tx, attach: (image, options) => reporter.attach(image, options) },
-          () => this.invokeWithTimeout(handler, run, reporter)
-        );
-        await reporter.finalizeAttachments();
-        await reporter.finalizeItems();
-        tx.setStatus("ok");
-        tx.finish();
-        reporter.reportSuccess();
-        this.logger.debug(`run ${run.id} conclu\xEDda`);
+        return await this.deps.api.createRun({ task: this.task.slug, instance: this.deps.instanceInfo() }, this.abort.signal);
       } catch (error) {
-        await reporter.finalizeAttachments();
-        await reporter.finalizeItems();
-        tx.setStatus("error");
-        tx.finish();
-        reporter.reportFailure(toRunError(error));
-        this.logger.debug(`run ${run.id} falhou: ${String(error)}`);
+        if (this.abort.signal.aborted) return void 0;
+        await abortableSleep(this.backoff.next(error), this.abort.signal);
       }
-      await reporter.finalize();
-    } finally {
-      this.reporters.delete(reporter);
     }
   }
-  async invokeWithTimeout(handler, run, reporter) {
-    const invocation = Promise.resolve().then(() => handler(run.params, reporter.context));
-    const races = [];
-    if (this.taskTimeoutMs && this.taskTimeoutMs > 0) {
-      races.push(sleep(this.taskTimeoutMs).then(() => TIMEOUT_SENTINEL));
+};
+
+// src/tasks/registry.ts
+var TaskRegistry = class {
+  tasks = /* @__PURE__ */ new Map();
+  add(task) {
+    if (this.tasks.has(task.slug)) {
+      throw new Error(`[hobots] task "${task.slug}" j\xE1 registrada \u2014 cada slug s\xF3 pode ter um handler (register ou start)`);
     }
-    if (this.cancelGraceMs > 0) {
-      races.push(waitForCancelGrace(reporter.context.signal, this.cancelGraceMs).then(() => CANCEL_SENTINEL));
+    this.tasks.set(task.slug, task);
+  }
+  get(slug) {
+    return this.tasks.get(slug);
+  }
+  get size() {
+    return this.tasks.size;
+  }
+  /** Tasks que chegam pelo poll (register). */
+  remoteTasks() {
+    return [...this.tasks.values()].filter((task) => task.mode === "remote");
+  }
+  /** Tasks abertas pelo próprio bot (start). */
+  localTasks() {
+    return [...this.tasks.values()].filter((task) => task.mode === "local");
+  }
+  /** Todos os slugs, para a presença da instância (`instance.tasks`). */
+  allSlugs() {
+    return [...this.tasks.keys()];
+  }
+  /** Colunas de itens declaradas no código, por slug (`instance.task_items`); undefined se nenhuma task declarou. */
+  itemDeclarations() {
+    let result;
+    for (const task of this.tasks.values()) {
+      if (!task.options.itemColumns) continue;
+      (result ??= {})[task.slug] = { attributes: task.options.itemColumns };
     }
-    if (races.length === 0) {
-      await invocation;
-      return;
+    return result;
+  }
+  clear() {
+    this.tasks.clear();
+  }
+};
+var RunTracker = class {
+  constructor(api) {
+    this.api = api;
+  }
+  reporters = /* @__PURE__ */ new Set();
+  waiters = /* @__PURE__ */ new Set();
+  add(reporter) {
+    this.reporters.add(reporter);
+  }
+  remove(reporter) {
+    this.reporters.delete(reporter);
+    if (this.reporters.size === 0) {
+      for (const resolve2 of this.waiters) resolve2();
+      this.waiters.clear();
     }
-    const outcome = await Promise.race([invocation, ...races]);
-    if (outcome !== TIMEOUT_SENTINEL && outcome !== CANCEL_SENTINEL) return;
-    if (outcome === CANCEL_SENTINEL) {
-      this.logger.warn(
-        `run ${run.id} cancelada \u2014 handler n\xE3o respondeu a ctx.signal em ${this.cancelGraceMs}ms, liberando o slot (o handler pode continuar rodando em segundo plano)`
+  }
+  get activeCount() {
+    return this.reporters.size;
+  }
+  /** Runs ativas de uma task (concorrência por task no poll). */
+  activeFor(slug) {
+    let count = 0;
+    for (const reporter of this.reporters) if (reporter.context.task === slug) count++;
+    return count;
+  }
+  /** A única run ativa, quando há exatamente uma — o que `hobots.*` usa fora de um contexto async. */
+  singleActive() {
+    if (this.reporters.size !== 1) return void 0;
+    return this.reporters.values().next().value;
+  }
+  /** Resolve quando não houver mais runs ativas (ou após timeoutMs, devolvendo false). */
+  async waitIdle(timeoutMs) {
+    if (this.reporters.size === 0) return true;
+    const idle = new Promise((resolve2) => this.waiters.add(() => resolve2(true)));
+    if (timeoutMs <= 0) return false;
+    return Promise.race([idle, sleep(timeoutMs).then(() => false)]);
+  }
+  /**
+   * Best-effort do exit path: reporta 'failed'/AgentTerminated para as runs ativas
+   * antes do processo morrer, fora da fila do reporter e com timeout curto. Runs já
+   * canceladas no app (reporter morto) são puladas; erros de rede são engolidos —
+   * o sweep server-side é o backstop.
+   */
+  async reportAgentTerminated(message, timeoutMs = 2500) {
+    const pending = [];
+    for (const reporter of this.reporters) {
+      if (reporter.isDead) continue;
+      const logs = reporter.drainLogs();
+      reporter.kill();
+      pending.push(
+        this.api.updateRunOnce(
+          reporter.context.runId,
+          { status: "failed", error: { type: "AgentTerminated", message }, logs: logs.length > 0 ? logs : void 0 },
+          timeoutMs
+        ).catch(() => {
+        })
       );
-      return;
     }
-    const timeoutMs = this.taskTimeoutMs;
-    reporter.abort();
-    invocation.then(() => this.logger.warn(`run ${run.id} terminou depois do timeout de ${timeoutMs}ms`)).catch(() => this.logger.warn(`run ${run.id} falhou depois do timeout de ${timeoutMs}ms (erro descartado)`));
-    throw Object.assign(new Error(`timeout ap\xF3s ${timeoutMs}ms (o handler pode continuar em background)`), {
-      name: "TaskTimeout"
-    });
+    if (pending.length === 0) return;
+    await Promise.race([Promise.allSettled(pending), sleep(timeoutMs)]);
   }
 };
-var TIMEOUT_SENTINEL = /* @__PURE__ */ Symbol("task-timeout");
-var CANCEL_SENTINEL = /* @__PURE__ */ Symbol("task-canceled");
-function waitForCancelGrace(signal, graceMs) {
-  return new Promise((resolve) => {
-    if (signal.aborted) {
-      setTimeout(resolve, graceMs);
-      return;
+
+// src/tasks/shutdown.ts
+var WATCHED_SIGNALS = ["SIGINT", "SIGTERM"];
+function installShutdownHandlers(agent) {
+  if (!isNode()) return () => {
+  };
+  let signaled = false;
+  const signalHandlers = /* @__PURE__ */ new Map();
+  for (const signal of WATCHED_SIGNALS) {
+    const handler = markInternal(() => {
+      if (externalListenerCount(signal) > 0) return;
+      if (signaled) return;
+      signaled = true;
+      const reraise = () => {
+        process.removeListener(signal, handler);
+        process.kill(process.pid, signal);
+      };
+      if (agent.activeCount === 0) {
+        reraise();
+        return;
+      }
+      const report = agent.reportAgentTerminated(`o processo do agente recebeu ${signal} durante a execu\xE7\xE3o`);
+      addEmergencyTask(report);
+      void report.finally(reraise);
+    });
+    process.on(signal, handler);
+    signalHandlers.set(signal, handler);
+  }
+  const onFatal = markInternal((error) => {
+    const report = agent.activeCount > 0 ? agent.reportAgentTerminated("o processo do agente morreu com um erro n\xE3o tratado durante a execu\xE7\xE3o") : Promise.resolve();
+    addEmergencyTask(report);
+    if (!hasInstalledGlobalHandlers() && externalListenerCount("uncaughtException") === 0) {
+      void report.finally(() => {
+        console.error(error);
+        process.exit(1);
+      });
     }
-    signal.addEventListener("abort", () => setTimeout(resolve, graceMs), { once: true });
   });
+  process.on("uncaughtException", onFatal);
+  return () => {
+    for (const [signal, handler] of signalHandlers) process.removeListener(signal, handler);
+    process.removeListener("uncaughtException", onFatal);
+  };
 }
-var MAX_ERROR_MESSAGE_CHARS = 1e4;
-var MAX_ERROR_STACK_CHARS = 2e4;
-function toRunError(error) {
-  if (error instanceof Error) {
-    return {
-      type: error.name,
-      message: scrubSecrets(truncate(error.message, MAX_ERROR_MESSAGE_CHARS)),
-      stack: error.stack ? scrubSecrets(truncate(error.stack, MAX_ERROR_STACK_CHARS)) : void 0
-    };
+
+// src/runtime.ts
+var HEARTBEAT_INTERVAL_MS = 3e4;
+var DEFAULT_RETRIES2 = 1;
+var DEFAULT_RETRY_DELAY_MS2 = 5e3;
+var DEFAULT_CANCEL_GRACE_MS = 1e4;
+var MAX_CONCURRENCY = 5;
+var MAX_SLUG_CHARS = 255;
+var PROCESS_LEVEL_KEYS = [
+  "clientSecret",
+  "instanceId",
+  "environment",
+  "release",
+  "tags",
+  "debug",
+  "machineMetrics",
+  "captureUnhandled",
+  "installExitHandlers"
+];
+var runtime;
+var warnedNoRuntime = false;
+function hostname() {
+  if (!isNode()) return void 0;
+  return process.env.HOSTNAME || process.env.COMPUTERNAME || void 0;
+}
+function sameValue(a, b) {
+  if (a === b) return true;
+  if (a && b && typeof a === "object" && typeof b === "object") return JSON.stringify(a) === JSON.stringify(b);
+  return false;
+}
+function ensureRuntime(options) {
+  if (runtime) {
+    for (const key of PROCESS_LEVEL_KEYS) {
+      if (options[key] !== void 0 && !sameValue(options[key], runtime.options[key])) {
+        runtime.logger.warn(
+          `op\xE7\xE3o "${key}" divergente ignorada \u2014 o primeiro register()/start() define as op\xE7\xF5es do processo`
+        );
+      }
+    }
+    return runtime;
+  }
+  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.tasksBaseUrl, key: config.key, logger });
+  runtime = {
+    options: { ...options, clientSecret: void 0 },
+    config,
+    client,
+    logger,
+    api,
+    registry: new TaskRegistry(),
+    tracker: new RunTracker(api),
+    sampler: void 0,
+    heartbeat: void 0,
+    agent: void 0,
+    locals: /* @__PURE__ */ new Map(),
+    instanceId: resolveInstanceId(options.instanceId),
+    environment,
+    pollIntervalMs: void 0,
+    booted: false,
+    bootScheduled: false,
+    bootPromise: void 0,
+    uninstallGlobalHandlers: options.captureUnhandled !== false ? installGlobalHandlers(client) : void 0,
+    uninstallShutdown: void 0
+  };
+  runtime.options.clientSecret = options.clientSecret;
+  logger.debug("inicializado", { endpoint: config.ingestEndpoint });
+  return runtime;
+}
+function validateTask(slug, handler, fn) {
+  if (typeof slug !== "string" || slug.trim().length === 0 || slug.length > MAX_SLUG_CHARS) {
+    throw new Error(`[hobots] ${fn}(): o slug da task precisa ser uma string de 1 a ${MAX_SLUG_CHARS} caracteres`);
   }
-  return { message: scrubSecrets(truncate(String(error), MAX_ERROR_MESSAGE_CHARS)) };
+  if (typeof handler !== "function") {
+    throw new Error(`[hobots] ${fn}('${slug}'): o handler precisa ser uma fun\xE7\xE3o`);
+  }
+  return slug.trim();
 }
-
-// src/core.ts
-var DEFAULT_MAX_BREADCRUMBS = 100;
-var client;
-var scope = new Scope();
-var heartbeat;
-var machineSampler;
-var agent;
-var uninstallGlobalHandlers;
-var registry = /* @__PURE__ */ new Map();
-var warnedTasksDisabled = false;
-function init(options) {
-  if (client) {
-    client.logger.warn("init() chamado mais de uma vez \u2014 substituindo o client anterior");
-    heartbeat?.stop();
-    heartbeat = void 0;
-  }
-  if (agent) {
-    void agent.stop(0);
-    agent = void 0;
-  }
-  uninstallGlobalHandlers?.();
-  uninstallGlobalHandlers = void 0;
-  warnedTasksDisabled = false;
-  const config = resolveConfig(options);
-  client = new Client(options, config);
-  machineSampler = options.machineMetrics === false ? void 0 : new MachineSampler(options.instanceId, client.logger);
-  void machineSampler?.start();
-  client.attachMachineSampler(machineSampler);
-  if (options.captureUnhandled !== false) {
-    uninstallGlobalHandlers = installGlobalHandlers(client, () => scope);
-  }
-  if (options.heartbeat) {
-    const heartbeatOptions = options.heartbeat === true ? {} : options.heartbeat;
-    heartbeat = new Heartbeat(client, heartbeatOptions, options.instanceId, machineSampler);
-    heartbeat.start();
-  }
-  if (options.tasks) {
-    const tasksOptions = options.tasks === true ? {} : options.tasks;
-    agent = new TaskAgent(
-      { ...tasksOptions, config, instanceId: options.instanceId, environment: options.environment, debug: options.debug, client, machineSampler },
-      registry
-    );
+function clampConcurrency(value) {
+  if (value === void 0 || !Number.isFinite(value)) return 1;
+  return Math.min(MAX_CONCURRENCY, Math.max(1, Math.floor(value)));
+}
+function resolveTaskOptions(slug, options, mode, logger) {
+  const retries = options.retries === void 0 || !Number.isFinite(options.retries) ? DEFAULT_RETRIES2 : Math.max(0, Math.floor(options.retries));
+  return {
+    retries,
+    retryDelayMs: options.retryDelayMs ?? DEFAULT_RETRY_DELAY_MS2,
+    timeoutMs: options.timeoutMs && options.timeoutMs > 0 ? options.timeoutMs : void 0,
+    concurrency: mode === "remote" ? clampConcurrency(options.concurrency) : 1,
+    logFlushIntervalMs: options.logFlushIntervalMs,
+    cancelCheckIntervalMs: options.cancelCheckIntervalMs,
+    cancelGraceMs: options.cancelGraceMs ?? DEFAULT_CANCEL_GRACE_MS,
+    itemColumns: normalizeItemColumns(slug, options.items, logger)
+  };
+}
+function instanceInfo(rt) {
+  return {
+    instance_id: rt.instanceId ?? "unknown",
+    version: SDK_VERSION,
+    host: hostname(),
+    // ambiente da instância: junto do heartbeat, é como o servidor sabe onde o robô roda
+    environment: rt.environment,
+    // TODAS as tasks (register + start) — o painel mostra o que o agente sabe fazer
+    tasks: rt.registry.allSlugs(),
+    // colunas da aba "itens" declaradas no código — a plataforma usa enquanto o usuário não personalizar
+    task_items: rt.registry.itemDeclarations(),
+    // o servidor calcula a tolerância de offline (3×) a partir disto em agentes que fazem
+    // poll; clampado à faixa aceita pelo schema (1s..15min)
+    poll_interval_ms: rt.agent ? Math.min(Math.max(rt.agent.pollIntervalMs, 1e3), 9e5) : void 0,
+    // recursos da máquina — alimenta a série da instância (o servidor grava no máx. 1 ponto/30s)
+    machine: rt.sampler?.sample()
+  };
+}
+function ensureAgent(rt) {
+  rt.agent ??= new TaskAgent({
+    api: rt.api,
+    client: rt.client,
+    logger: rt.logger,
+    registry: rt.registry,
+    tracker: rt.tracker,
+    instanceInfo: () => instanceInfo(rt),
+    pollIntervalMs: rt.pollIntervalMs
+  });
+  return rt.agent;
+}
+function launchLocal(rt, task) {
+  const runner = new LocalRunner(task, {
+    api: rt.api,
+    client: rt.client,
+    logger: rt.logger,
+    tracker: rt.tracker,
+    instanceInfo: () => instanceInfo(rt)
+  });
+  rt.locals.set(task.slug, runner);
+  void runner.run();
+}
+async function boot(rt) {
+  if (!rt.instanceId) {
+    const id = await fallbackInstanceId();
+    if (runtime !== rt) return;
+    rt.instanceId = id;
+    rt.logger.debug(`instanceId n\xE3o informado (env ${INSTANCE_ID_ENV}) \u2014 usando o hostname "${id}"`);
+  }
+  if (runtime !== rt) return;
+  rt.booted = true;
+  if (rt.options.machineMetrics !== false) {
+    rt.sampler = new MachineSampler(rt.instanceId, rt.logger);
+    void rt.sampler.start();
+    rt.client.attachMachineSampler(rt.sampler);
+  }
+  rt.heartbeat = new Heartbeat(rt.client, { intervalMs: HEARTBEAT_INTERVAL_MS, keepAlive: true }, rt.instanceId, rt.sampler);
+  rt.heartbeat.start();
+  if (rt.options.installExitHandlers !== false) {
+    rt.uninstallShutdown = installShutdownHandlers(rt.tracker);
+  }
+  if (rt.registry.remoteTasks().length > 0) ensureAgent(rt).start();
+  for (const task of rt.registry.localTasks()) launchLocal(rt, task);
+}
+function scheduleBoot(rt) {
+  if (rt.bootScheduled) return;
+  rt.bootScheduled = true;
+  queueMicrotask(() => {
+    rt.bootPromise = boot(rt).catch((error) => rt.logger.error("falha ao iniciar o SDK:", error));
+  });
+}
+function addTask(fn, mode, task, handler, options) {
+  const slug = validateTask(task, handler, fn);
+  const rt = ensureRuntime(options);
+  if (mode === "remote" && options.pollIntervalMs !== void 0) {
+    if (rt.pollIntervalMs === void 0 && !rt.agent) rt.pollIntervalMs = options.pollIntervalMs;
+    else if (rt.pollIntervalMs !== options.pollIntervalMs) {
+      rt.logger.warn('op\xE7\xE3o "pollIntervalMs" divergente ignorada \u2014 o primeiro register() define o intervalo do poll');
+    }
+  }
+  const registered = { slug, mode, handler, options: resolveTaskOptions(slug, options, mode, rt.logger) };
+  rt.registry.add(registered);
+  if (!rt.booted) {
+    scheduleBoot(rt);
+    return;
   }
-  client.logger.debug("inicializado", { endpoint: client.config.ingestEndpoint });
+  if (mode === "remote") {
+    const agent = ensureAgent(rt);
+    agent.start();
+    agent.wake();
+  } else {
+    launchLocal(rt, registered);
+  }
+}
+function register(task, handler, options = {}) {
+  addTask("register", "remote", task, handler, options);
+}
+function start(task, handler, options = {}) {
+  addTask("start", "local", task, handler, options);
+}
+function currentReporter() {
+  return currentRunReporter() ?? runtime?.tracker.singleActive();
 }
-function getClient() {
-  return client;
+function activeLogger() {
+  return runtime?.logger;
 }
 function toRunLogLevel(type) {
   return type === "fatal" ? "error" : type;
 }
-function forwardAttachment(attachment, message, type) {
-  const attach = currentRunAttach();
-  if (!attach) {
-    client?.logger.warn("attachment descartado \u2014 s\xF3 \xE9 suportado dentro de uma execu\xE7\xE3o de task (register/start)");
+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 de task");
     return;
   }
   const withMeta = typeof attachment === "object" && "image" in attachment ? attachment : { image: attachment };
-  void attach(withMeta.image, {
+  void reporter.attach(withMeta.image, {
     message,
     level: toRunLogLevel(type),
     caption: withMeta.caption,
@@ -2352,84 +2797,115 @@ function forwardAttachment(attachment, message, type) {
   });
 }
 function captureException(error, hint) {
-  if (hint?.attachment) {
-    const message = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
-    forwardAttachment(hint.attachment, message, hint.type ?? "error");
+  const rt = runtime;
+  if (!rt) {
+    if (!warnedNoRuntime) {
+      warnedNoRuntime = true;
+      console.warn("[hobots] captureException antes de registrar uma task (register/start) \u2014 evento descartado");
+    }
+    return void 0;
   }
-  return client?.captureException(error, hint, scope);
-}
-function captureMessage(message, type = "warning", hint) {
   if (hint?.attachment) {
-    forwardAttachment(hint.attachment, message, hint.type ?? type);
-  }
-  return client?.captureMessage(message, type, hint, scope);
-}
-function addBreadcrumb(crumb) {
-  scope.addBreadcrumb(crumb, client?.options.maxBreadcrumbs ?? DEFAULT_MAX_BREADCRUMBS);
-}
-function setTag(key, value) {
-  scope.setTag(key, value);
-}
-function setTags(tags) {
-  scope.setTags(tags);
-}
-function setUser(user) {
-  scope.setUser(user);
-}
-function setContext(name, context) {
-  scope.setContext(name, context);
-}
-function setExtra(key, value) {
-  scope.setExtra(key, value);
-}
-function withScope(callback) {
-  const previous = scope;
-  scope = previous.clone();
-  try {
-    return callback(scope);
-  } finally {
-    scope = previous;
-  }
-}
-function startTransaction(name, op) {
-  const active = currentRunTransaction();
-  if (active) {
-    client?.logger.debug(`startTransaction('${name}') dentro de uma execu\xE7\xE3o \u2014 reutilizando a transaction da run`);
-    return active;
-  }
-  const rate = client?.options.tracesSampleRate ?? 1;
-  const sampled = rate >= 1 || Math.random() < rate;
-  return new Transaction(client, name, op, sampled);
-}
-function flush(timeoutMs) {
-  return client ? client.flush(timeoutMs) : Promise.resolve(true);
-}
-function register(task, handler) {
-  if (registry.has(task)) {
-    (agent?.logger ?? client?.logger)?.warn(`register('${task}') sobrescreveu um handler existente`);
-  }
-  if (client && !agent && !warnedTasksDisabled) {
-    warnedTasksDisabled = true;
-    client.logger.warn(
-      `register('${task}') com tasks desabilitadas \u2014 passe tasks: true (ou op\xE7\xF5es) no init()`
-    );
-  }
-  registry.set(task, handler);
-}
-function start() {
-  if (!agent) {
-    throw new Error("[hobots] tasks n\xE3o configuradas \u2014 passe tasks: true (ou op\xE7\xF5es) no init() antes de start()");
-  }
-  agent.start();
-}
-function stop(timeoutMs) {
-  return agent ? agent.stop(timeoutMs) : Promise.resolve(true);
+    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);
+}
+async function close(timeoutMs = 3e4) {
+  const rt = runtime;
+  if (!rt) return true;
+  runtime = void 0;
+  await rt.bootPromise;
+  if (rt.agent) await rt.agent.stop(0);
+  for (const local of rt.locals.values()) local.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`);
+    await rt.tracker.reportAgentTerminated("agente encerrado durante a execu\xE7\xE3o (shutdown excedeu o tempo de espera)");
+  }
+  rt.heartbeat?.stop();
+  rt.uninstallShutdown?.();
+  rt.uninstallGlobalHandlers?.();
+  const flushed = await rt.client.close(timeoutMs);
+  return idle && flushed;
 }
-async function close(timeoutMs) {
-  const agentStopped = agent ? await agent.stop(timeoutMs) : true;
-  heartbeat?.stop();
-  heartbeat = void 0;
-  const clientClosed = client ? await client.close(timeoutMs) : true;
-  return agentStopped && clientClosed;
+
+// src/hobots.ts
+var warned = /* @__PURE__ */ new Set();
+function warnOutsideRun(member) {
+  if (warned.has(member)) return;
+  warned.add(member);
+  const message = `hobots.${member} usado fora de uma execu\xE7\xE3o de task \u2014 ignorado (registre a task com register()/start() e use dentro do handler)`;
+  const logger = activeLogger();
+  if (logger) logger.warn(message);
+  else console.warn(`[hobots] ${message}`);
+}
+var FALLBACK_TASK = "hobots";
+var fallbackLog = {
+  debug: (message, ...rest) => printRunLog(FALLBACK_TASK, "debug", joinLogArgs(message, rest)),
+  info: (message, ...rest) => printRunLog(FALLBACK_TASK, "info", joinLogArgs(message, rest)),
+  warn: (message, ...rest) => printRunLog(FALLBACK_TASK, "warning", joinLogArgs(message, rest)),
+  error: (message, ...rest) => printRunLog(FALLBACK_TASK, "error", joinLogArgs(message, rest)),
+  success: (message, ...rest) => printRunLog(FALLBACK_TASK, "success", joinLogArgs(message, rest))
+};
+var noop = () => void 0;
+var fallbackItems = { add: noop, succeeded: noop, failed: noop, occurrence: noop };
+var fallbackProgress = { total: noop, advance: noop, set: noop, current: 0, snapshot: null };
+var neverAborts = new AbortController().signal;
+var detachedTransaction;
+function resolve(member) {
+  const reporter = currentReporter();
+  if (reporter) return reporter.context;
+  warnOutsideRun(member);
+  return void 0;
 }
+function getter(member, fallback) {
+  return { enumerable: true, get: () => resolve(member)?.[member] ?? fallback() };
+}
+function method(value) {
+  return { enumerable: true, writable: false, value };
+}
+var hobots = Object.defineProperties({}, {
+  // ── contexto da run atual (getters) ─────────────────────────────────────────
+  runId: getter("runId", () => ""),
+  task: getter("task", () => ""),
+  params: getter("params", () => ({})),
+  log: getter("log", () => fallbackLog),
+  items: getter("items", () => fallbackItems),
+  progress: getter("progress", () => fallbackProgress),
+  transaction: getter("transaction", () => detachedTransaction ??= new Transaction(void 0, "hobots.detached")),
+  signal: getter("signal", () => neverAborts),
+  throwIfCanceled: method(() => resolve("throwIfCanceled")?.throwIfCanceled()),
+  sleep: method((ms) => resolve("sleep")?.sleep(ms) ?? sleep(ms)),
+  attach: method(
+    (image, options) => resolve("attach")?.attach(image, options) ?? Promise.resolve({ id: "", ok: false, reason: "canceled" })
+  ),
+  retry: method((fn, options) => {
+    const reporter = currentReporter();
+    return reporter ? reporter.context.retry(fn, options) : retryWithBackoff(fn, options);
+  }),
+  // ── processo ────────────────────────────────────────────────────────────────
+  register: method((task, handler, options) => {
+    register(task, handler, options);
+    installGlobalHobots();
+  }),
+  start: method((task, handler, options) => {
+    start(task, handler, options);
+    installGlobalHobots();
+  }),
+  close: method((timeoutMs) => close(timeoutMs)),
+  captureException: method((error, hint) => captureException(error, hint))
+});
+function installGlobalHobots() {
+  if (globalThis.hobots === hobots) return;
+  Object.defineProperty(globalThis, "hobots", { value: hobots, configurable: true, writable: true, enumerable: false });
+}
+var register2 = hobots.register;
+var start2 = hobots.start;
+var close2 = hobots.close;
+var captureException2 = hobots.captureException;
+var retry = hobots.retry;
+
+// src/index.ts
+var src_default = hobots;
 //# sourceMappingURL=index.cjs.map