hobots 2.4.0 → 3.0.0

package/dist/index.js

@@ -1,54 +1,3 @@
-// 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 FRAME_RE = /^\s*at\s+(?:async\s+)?(?:(.+?)\s+\()?(.+?)\)?$/;
@@ -103,7 +52,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.0.0" : "0.0.0-dev";
 function isNode() {
   return typeof process !== "undefined" && typeof process.versions?.node === "string";
 }
@@ -131,11 +80,28 @@ 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));
 }
@@ -256,14 +222,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;
@@ -397,7 +355,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);
@@ -427,43 +385,28 @@ 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);
+  captureException(error, hint) {
+    return this.captureEvent(eventFromException(error, hint?.type ?? "error"), hint);
   }
-  captureMessage(message, type, hint, scope2) {
-    return this.captureEvent(eventFromMessage(message, type), hint, scope2);
-  }
-  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,
       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: hint?.fingerprint ?? event.fingerprint
     };
   }
   sendTransaction(payload) {
@@ -489,7 +432,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.
    */
@@ -504,23 +447,103 @@ 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";
+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;
+}
+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;
@@ -536,7 +559,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) {
@@ -582,13 +605,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);
@@ -597,11 +620,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);
@@ -615,13 +638,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);
@@ -761,349 +784,138 @@ 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;
+// 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";
   }
-  setTags(tags) {
-    Object.assign(this.tags, tags);
-    return this;
+};
+var TasksApi = class {
+  baseUrl;
+  key;
+  logger;
+  constructor(options) {
+    this.baseUrl = options.baseUrl;
+    this.key = options.key;
+    this.logger = options.logger;
   }
-  setUser(user) {
-    this.user = user ?? void 0;
-    return this;
+  headers() {
+    return {
+      "content-type": "application/json",
+      authorization: `Bearer ${this.key}`
+    };
   }
-  setContext(name, context) {
-    if (context === null) {
-      delete this.contexts[name];
-    } else {
-      this.contexts[name] = context;
+  /** 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;
-  }
-  setExtra(key, value) {
-    this.extra[key] = value;
-    return this;
-  }
-  setExtras(extras) {
-    Object.assign(this.extra, extras);
-    return this;
-  }
-  setType(type) {
-    this.type = type;
-    return this;
+    if (!response.ok) {
+      throw new TasksApiError(`poll falhou (HTTP ${response.status})`, response.status);
+    }
+    return this.parsePollResponse(await response.json(), request.max ?? 1);
   }
-  setFingerprint(fingerprint) {
-    this.fingerprint = fingerprint;
-    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()
+    };
   }
-  addBreadcrumb(crumb, maxBreadcrumbs) {
-    this.breadcrumbs.push({ timestamp: nowISO(), ...crumb });
-    if (this.breadcrumbs.length > maxBreadcrumbs) {
-      this.breadcrumbs.splice(0, this.breadcrumbs.length - maxBreadcrumbs);
+  /** 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);
     }
-    return this;
+    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 };
   }
-  clearBreadcrumbs() {
-    this.breadcrumbs = [];
-    return this;
+  /**
+   * PATCH de status/logs com retry em falha de rede/5xx/429.
+   * 4xx é definitivo e vira TasksApiError imediato (409 = run cancelada/transição inválida).
+   */
+  async updateRun(runId, update) {
+    let response;
+    try {
+      response = await fetchWithRetry(
+        () => fetch(`${this.baseUrl}/runs/${encodeURIComponent(runId)}`, {
+          method: "PATCH",
+          headers: this.headers(),
+          body: JSON.stringify(update),
+          signal: AbortSignal.timeout(UPDATE_TIMEOUT_MS)
+        }),
+        { logger: this.logger, label: `update da run ${runId}` }
+      );
+    } catch (error) {
+      throw new Error(`update da run ${runId} descartado ap\xF3s retries: ${String(error)}`);
+    }
+    if (!response.ok) {
+      throw new TasksApiError(`update rejeitado (HTTP ${response.status})`, response.status);
+    }
   }
-  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 };
-  }
-  /**
-   * PATCH de status/logs com retry em falha de rede/5xx/429.
-   * 4xx é definitivo e vira TasksApiError imediato (409 = run cancelada/transição inválida).
-   */
-  async updateRun(runId, update) {
-    let response;
-    try {
-      response = await fetchWithRetry(
-        () => fetch(`${this.baseUrl}/runs/${encodeURIComponent(runId)}`, {
-          method: "PATCH",
-          headers: this.headers(),
-          body: JSON.stringify(update),
-          signal: AbortSignal.timeout(UPDATE_TIMEOUT_MS)
-        }),
-        { logger: this.logger, label: `update da run ${runId}` }
-      );
-    } catch (error) {
-      throw new Error(`update da run ${runId} descartado ap\xF3s retries: ${String(error)}`);
-    }
-    if (!response.ok) {
-      throw new TasksApiError(`update rejeitado (HTTP ${response.status})`, response.status);
-    }
-  }
-  /**
-   * Um único PATCH com timeout curto — exit path (o processo está morrendo, o retry
-   * ladder do updateRun é proibido aqui). Status HTTP é ignorado: 409/404 significa
-   * que a run já foi cancelada/finalizada, o que é aceitável nesse caminho.
-   */
-  async updateRunOnce(runId, update, timeoutMs = 2e3) {
-    await fetch(`${this.baseUrl}/runs/${encodeURIComponent(runId)}`, {
-      method: "PATCH",
-      headers: this.headers(),
-      body: JSON.stringify(update),
-      signal: AbortSignal.timeout(timeoutMs)
-    });
+  /**
+   * Um único PATCH com timeout curto — exit path (o processo está morrendo, o retry
+   * ladder do updateRun é proibido aqui). Status HTTP é ignorado: 409/404 significa
+   * que a run já foi cancelada/finalizada, o que é aceitável nesse caminho.
+   */
+  async updateRunOnce(runId, update, timeoutMs = 2e3) {
+    await fetch(`${this.baseUrl}/runs/${encodeURIComponent(runId)}`, {
+      method: "PATCH",
+      headers: this.headers(),
+      body: JSON.stringify(update),
+      signal: AbortSignal.timeout(timeoutMs)
+    });
   }
   /**
    * Envia um lote de itens de execução. Retry em falha de rede/5xx/429-transporte;
@@ -1206,13 +1018,83 @@ var TasksApi = class {
         body: JSON.stringify(request),
         signal: AbortSignal.timeout(UPDATE_TIMEOUT_MS)
       }
-    );
-    if (!response.ok) {
-      throw new TasksApiError(`confirma\xE7\xE3o de anexo rejeitada (HTTP ${response.status})`, response.status);
+    );
+    if (!response.ok) {
+      throw new TasksApiError(`confirma\xE7\xE3o de anexo rejeitada (HTTP ${response.status})`, response.status);
+    }
+  }
+};
+
+// 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) {
+      this.authFailures++;
+      if (this.authFailures === 1 || this.authFailures % 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.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 retries = Math.max(0, Math.floor(options.retries ?? 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;
@@ -1264,14 +1146,11 @@ var LOG_LEVEL_COLOR = {
 };
 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;
@@ -1282,7 +1161,7 @@ function cancelableSleep(ms, signal) {
     };
     const timer = setTimeout(() => {
       signal.removeEventListener("abort", onAbort);
-      resolve();
+      resolve2();
     }, ms);
     signal.addEventListener("abort", onAbort, { once: true });
   });
@@ -1312,7 +1191,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;
@@ -1329,17 +1208,40 @@ var RunReporter = class {
       success: (message) => this.log("success", message)
     };
     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 },
@@ -1351,18 +1253,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;
@@ -1411,6 +1315,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();
@@ -1689,13 +1597,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)))
       ]);
     }
   }
@@ -1703,8 +1611,8 @@ 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();
@@ -1726,8 +1634,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);
@@ -1809,8 +1717,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));
     });
   }
   /**
@@ -1821,7 +1729,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) {
@@ -1892,119 +1800,354 @@ async function runWithRunContext(store, fn) {
   await ensureStorage();
   return storage ? storage.run(store, fn) : fn();
 }
-function currentRunTransaction() {
-  return storage?.getStore()?.tx;
+function currentRunReporter() {
+  return storage?.getStore()?.reporter;
+}
+
+// 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 currentRunAttach() {
-  return storage?.getStore()?.attach;
+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(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 = [];
+  /**
+   * 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);
+  }
+  /**
+   * 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/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/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 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);
-      });
+  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 });
   });
-  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
+    };
+  }
+  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_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;
-}
+var MAX_CLAIM_PER_POLL = 5;
 var TaskAgent = class {
-  constructor(options, registry2) {
+  constructor(options) {
     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.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.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 });
+    this.backoff = new Backoff(this.logger, "poll", this.pollIntervalMs);
   }
   logger;
+  pollIntervalMs;
   api;
   client;
-  pollIntervalMs;
-  concurrency;
-  instanceId;
-  taskTimeoutMs;
-  logFlushIntervalMs;
-  cancelCheckIntervalMs;
-  cancelGraceMs;
+  registry;
+  tracker;
+  backoff;
   state = "idle";
   timer;
   pollAbort;
-  consecutiveFailures = 0;
-  consecutiveAuthFailures = 0;
   activeRuns = /* @__PURE__ */ new Set();
-  reporters = /* @__PURE__ */ new Set();
-  uninstallShutdown;
   get activeCount() {
     return this.activeRuns.size;
   }
   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()");
+      throw new Error("[hobots] start do agente durante o stop \u2014 aguarde o stop terminar");
     }
     this.state = "started";
-    if (this.options.installExitHandlers !== false && !this.uninstallShutdown) {
-      this.uninstallShutdown = installShutdownHandlers(this);
+    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.logger.debug(`polling iniciado (tasks: ${[...this.registry.keys()].join(", ")})`);
     this.schedule(0);
   }
   /** Para o polling e aguarda as runs ativas (até timeoutMs). Retorna true se tudo terminou a tempo. */
@@ -2017,40 +2160,10 @@ var TaskAgent = class {
     }
     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;
+    const finished = timeoutMs > 0 ? await Promise.race([all, sleep(timeoutMs).then(() => false)]) : this.activeRuns.size === 0;
     this.state = "idle";
     return finished;
   }
-  /**
-   * 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(() => {
-        })
-      );
-    }
-    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. */
   schedule(delayMs) {
     if (this.state !== "started" || this.timer) return;
@@ -2059,9 +2172,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;
     }
@@ -2069,224 +2195,448 @@ 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/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));
-    }
-    if (this.cancelGraceMs > 0) {
-      races.push(waitForCancelGrace(reporter.context.signal, this.cancelGraceMs).then(() => CANCEL_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 (races.length === 0) {
-      await invocation;
-      return;
+    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()];
+  }
+  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 client = new Client(
+    { environment: options.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),
+    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(options, mode) {
+  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
+  };
+}
+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.options.environment,
+    // TODAS as tasks (register + start) — o painel mostra o que o agente sabe fazer
+    tasks: rt.registry.allSlugs(),
+    // 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(options, mode) };
+  rt.registry.add(registered);
+  if (!rt.booted) {
+    scheduleBoot(rt);
+    return;
+  }
+  if (mode === "remote") {
+    const agent = ensureAgent(rt);
+    agent.start();
+    agent.wake();
+  } else {
+    launchLocal(rt, registered);
   }
-  client.logger.debug("inicializado", { endpoint: client.config.ingestEndpoint });
 }
-function getClient() {
-  return client;
+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 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,
@@ -2294,109 +2644,124 @@ 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) => printRunLog(FALLBACK_TASK, "debug", message),
+  info: (message) => printRunLog(FALLBACK_TASK, "info", message),
+  warn: (message) => printRunLog(FALLBACK_TASK, "warning", message),
+  error: (message) => printRunLog(FALLBACK_TASK, "error", message),
+  success: (message) => printRunLog(FALLBACK_TASK, "success", message)
+};
+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;
 export {
-  Client,
-  DEFAULT_BASE_URL,
-  Scope,
-  Step,
-  Transaction,
-  addBreadcrumb,
-  captureException,
-  captureMessage,
-  close,
-  flush,
-  getClient,
-  init,
-  register,
-  scrubSecrets,
-  setContext,
-  setExtra,
-  setTag,
-  setTags,
-  setUser,
-  start,
-  startTransaction,
-  stop,
-  withScope
+  captureException2 as captureException,
+  close2 as close,
+  src_default as default,
+  hobots,
+  register2 as register,
+  retry,
+  start2 as start
 };
 //# sourceMappingURL=index.js.map