hobots 1.5.1 → 1.6.0

package/README.md

@@ -65,7 +65,7 @@ Cada projeto tem **um único Client Secret** — a mesma credencial autentica o
 hb_<64 hex>
 ```
 
-(Chaves antigas, 64 hex puros, continuam válidas no servidor.) A credencial é **secreta** e viaja sempre no header `Authorization: Bearer` — nunca na URL. Copie o Client Secret no app, em **Configurações → Projetos** — os snippets de integração já vêm prontos. O SDK fala com a API oficial `https://api2.hobots.app` automaticamente; em desenvolvimento, aponte para outro host com a env `HOBOTS_API_URL` (ex.: `HOBOTS_API_URL=http://localhost:3001`).
+A credencial é **secreta** e viaja sempre no header `Authorization: Bearer` — nunca na URL. Copie o Client Secret no app, em **Configurações → Projetos** — os snippets de integração já vêm prontos. O SDK fala com a API oficial `https://api2.hobots.app` automaticamente; em desenvolvimento, aponte para outro host com a env `HOBOTS_API_URL` (ex.: `HOBOTS_API_URL=http://localhost:3001`).
 
 ---
 
@@ -354,37 +354,7 @@ Para parar de aceitar execuções **sem** derrubar a telemetria, use `stop(timeo
 | `hobots` | Tudo: `init`, Monitor (captura, transactions, crons, heartbeat), Manager (`register`/`start`/`stop`), `close`, classes e tipos. |
 | `hobots/protocol` | Tipos do wire format (Monitor e Manager). |
 
-Empacotado em **ESM e CommonJS** com **definições de tipos** (`.d.ts`) para todas as entradas. (`hobots/manager/protocol` segue existindo como alias transitório de tipos.)
-
----
-
-## Migração da API antiga (`hobots/manager`)
-
-O Manager foi unificado no import raiz — `hobots/manager` **foi removido**:
-
-```diff
--import * as Monitor from 'hobots';
--import * as Manager from 'hobots/manager';
-+import * as Hobots from 'hobots';
-
--Monitor.init({ dsn, serverName: 'vm-01', heartbeat: true });
--Manager.init({ dsn, agentName: 'vm-01' });
-+Hobots.init({ clientSecret, instanceId: 'vm-01', heartbeat: true, manager: true });
-
--Manager.register('minha-task', handler);
--Manager.start();
-+Hobots.register('minha-task', handler);
-+Hobots.start();
-
--await Manager.stop(15_000);
--await Monitor.close(3_000);
-+await Hobots.close(15_000);
-```
-
-- A `dsn` (mecanismo antigo, `https://<secretKey>@host/<slug>`) não existe mais — passe `clientSecret` (em desenvolvimento, aponte para outro host com a env `HOBOTS_API_URL`). Copie o Client Secret em **Configurações → Projetos**.
-- `agentName` e `serverName` não existem mais — a identidade do agente é o `instanceId` (obrigatório, sem fallback).
-- As opções do Manager (`pollIntervalMs`, `concurrency`, `taskTimeoutMs`, `logFlushIntervalMs`, `cancelCheckIntervalMs`, `installExitHandlers`) vão no campo `manager` do `init()`; `clientSecret` e `debug` não se repetem.
-- Tipos (`ManagerTaskHandler`, `RunContext`, `ManagerOptions`) e classes (`ManagerAgent`, `ManagerApi`) agora vêm de `hobots`; o wire format vem de `hobots/protocol`.
+Empacotado em **ESM e CommonJS** com **definições de tipos** (`.d.ts`) para todas as entradas.
 
 ---
 

package/dist/index.cjs

@@ -48,6 +48,7 @@ __export(src_exports, {
   init: () => init,
   register: () => register,
   resolveConfig: () => resolveConfig,
+  scrubSecrets: () => scrubSecrets,
   setContext: () => setContext,
   setExtra: () => setExtra,
   setTag: () => setTag,
@@ -63,21 +64,47 @@ 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 projeto em Configura\xE7\xF5es \u2192 Projetos`);
   }
-  const baseUrl = (envBaseUrl() ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
-  try {
-    new URL(baseUrl);
-  } catch {
-    throw new Error(`${prefix} HOBOTS_API_URL inv\xE1lida: "${baseUrl}" \u2014 esperado ex.: http://localhost:3001`);
+  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 projeto em Configura\xE7\xF5es \u2192 Projetos`
+    );
   }
+  const baseUrl = validateBaseUrl(envBaseUrl() ?? DEFAULT_BASE_URL, prefix);
   return {
     key,
     baseUrl,
@@ -119,9 +146,28 @@ function parseStacktrace(stack) {
   return frames;
 }
 
+// src/scrub.ts
+var SECRET_PATTERNS = [
+  // client secret da Hobots
+  [/hb_[a-f0-9]{16,}/gi, "[REDACTED]"],
+  // tokens bearer em headers/mensagens
+  [/\b(authorization:?\s*)?bearer\s+[a-z0-9._~+/=-]{8,}/gi, "Bearer [REDACTED]"],
+  // chaves no formato sk-… (OpenAI e afins)
+  [/\bsk-[a-z0-9_-]{16,}\b/gi, "[REDACTED]"],
+  // credenciais embutidas em URL (https://user:pass@host)
+  [/\/\/[^/\s:@]+:[^/\s@]+@/g, "//[REDACTED]@"]
+];
+function scrubSecrets(text) {
+  let out = text;
+  for (const [pattern, replacement] of SECRET_PATTERNS) {
+    out = out.replace(pattern, replacement);
+  }
+  return out;
+}
+
 // src/utils.ts
 var SDK_NAME = "hobots";
-var SDK_VERSION = true ? "1.5.0" : "0.0.0-dev";
+var SDK_VERSION = true ? "1.6.0" : "0.0.0-dev";
 function isNode() {
   return typeof process !== "undefined" && typeof process.versions?.node === "string";
 }
@@ -130,6 +176,12 @@ function uuid4() {
   if (cryptoRef && typeof cryptoRef.randomUUID === "function") {
     return cryptoRef.randomUUID().replace(/-/g, "");
   }
+  if (cryptoRef && typeof cryptoRef.getRandomValues === "function") {
+    const bytes = cryptoRef.getRandomValues(new Uint8Array(16));
+    bytes[6] = bytes[6] & 15 | 64;
+    bytes[8] = bytes[8] & 63 | 128;
+    return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+  }
   let out = "";
   for (let i = 0; i < 32; i++) {
     out += Math.floor(Math.random() * 16).toString(16);
@@ -148,7 +200,42 @@ function sleep(ms) {
     unrefTimer(timer);
   });
 }
-var PREFIX = "[hobots-monitor]";
+function jitter(baseMs) {
+  return Math.floor(baseMs / 2 + Math.random() * (baseMs / 2));
+}
+var MAX_RETRY_AFTER_MS = 6e4;
+function retryAfterMs(response) {
+  const header = response.headers.get("retry-after");
+  if (!header) return void 0;
+  const seconds = Number(header);
+  if (Number.isFinite(seconds)) {
+    return Math.min(MAX_RETRY_AFTER_MS, Math.max(0, seconds * 1e3));
+  }
+  const date = Date.parse(header);
+  if (Number.isNaN(date)) return void 0;
+  return Math.min(MAX_RETRY_AFTER_MS, Math.max(0, date - Date.now()));
+}
+function withTimeoutSignal(timeoutMs, external) {
+  const controller = new AbortController();
+  const onAbort = () => controller.abort(external?.reason);
+  if (external?.aborted) {
+    onAbort();
+  } else {
+    external?.addEventListener("abort", onAbort, { once: true });
+  }
+  const timer = setTimeout(() => {
+    controller.abort(Object.assign(new Error(`timeout ap\xF3s ${timeoutMs}ms`), { name: "TimeoutError" }));
+  }, timeoutMs);
+  unrefTimer(timer);
+  return {
+    signal: controller.signal,
+    cleanup: () => {
+      clearTimeout(timer);
+      external?.removeEventListener("abort", onAbort);
+    }
+  };
+}
+var PREFIX = "[hobots]";
 function makeLogger(enabled, prefix = PREFIX) {
   return {
     debug: (...args) => enabled && console.debug(colorize(prefix, "gray"), ...args),
@@ -189,11 +276,11 @@ function eventFromException(error, level = "error") {
   let frames = [];
   if (error instanceof Error) {
     type = error.name || "Error";
-    value = error.message;
+    value = scrubSecrets(error.message);
     frames = parseStacktrace(error.stack);
   } else {
     type = "NonError";
-    value = safeString(error);
+    value = scrubSecrets(safeString(error));
   }
   return {
     event_id: uuid4(),
@@ -211,12 +298,13 @@ function eventFromMessage(message, level = "info") {
     event_id: uuid4(),
     timestamp: nowISO(),
     level,
-    message
+    message: scrubSecrets(message)
   };
 }
 
 // src/transport.ts
 var RETRY_DELAYS_MS = [1e3, 4e3, 16e3];
+var REQUEST_TIMEOUT_MS = 1e4;
 var DEFAULT_FLUSH_INTERVAL_MS = 2e3;
 var DEFAULT_MAX_BATCH_SIZE = 10;
 var DEFAULT_MAX_QUEUE_SIZE = 200;
@@ -283,11 +371,13 @@ var Transport = class {
   }
   async sendWithRetry(envelope) {
     for (let attempt = 0; ; attempt++) {
+      let serverDelay;
       try {
         const response = await fetch(this.endpoint, {
           method: "POST",
           headers: { "content-type": "application/json", authorization: `Bearer ${this.key}` },
-          body: JSON.stringify(envelope)
+          body: JSON.stringify(envelope),
+          signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
         });
         if (response.ok) {
           this.logger.debug(`envelope enviado (${envelope.items.length} itens)`);
@@ -297,13 +387,15 @@ var Transport = class {
           this.logger.error(`envelope rejeitado (HTTP ${response.status}), descartado`);
           return;
         }
+        if (response.status === 429) serverDelay = retryAfterMs(response);
         throw new Error(`HTTP ${response.status}`);
       } catch (error) {
-        const delay = RETRY_DELAYS_MS[attempt];
-        if (delay === void 0) {
+        const base = RETRY_DELAYS_MS[attempt];
+        if (base === void 0) {
           this.logger.error("envelope descartado ap\xF3s retries:", error);
           return;
         }
+        const delay = serverDelay ?? jitter(base);
         this.logger.warn(`falha no envio (${String(error)}), retry em ${delay}ms`);
         await sleep(delay);
       }
@@ -333,22 +425,38 @@ function runtimeContexts() {
   return { runtime: { name: "browser" } };
 }
 var Client = class {
-  options;
-  config;
   logger;
+  // campos privados + getters de protótipo: o clientSecret não aparece em
+  // JSON.stringify/serialização enumerável do Client (ex.: um objeto capturado
+  // que referencie o client), mas client.options/config seguem funcionando
+  #options;
+  #config;
   transport;
   constructor(options) {
-    this.options = options;
+    this.#options = options;
     this.logger = makeLogger(!!options.debug);
-    this.config = resolveConfig(options);
+    this.#config = resolveConfig(options);
     this.transport = new Transport({
-      endpoint: this.config.ingestEndpoint,
-      key: this.config.key,
+      endpoint: this.#config.ingestEndpoint,
+      key: this.#config.key,
       logger: this.logger,
       flushIntervalMs: options.flushIntervalMs,
       maxBatchSize: options.maxBatchSize
     });
   }
+  get options() {
+    return this.#options;
+  }
+  get config() {
+    return this.#config;
+  }
+  /** Serialização explícita nunca inclui o secret. */
+  toJSON() {
+    return { sdk: SDK_NAME, version: SDK_VERSION, baseUrl: this.#config.baseUrl };
+  }
+  [/* @__PURE__ */ Symbol.for("nodejs.util.inspect.custom")]() {
+    return `Client { baseUrl: '${this.#config.baseUrl}' }`;
+  }
   captureException(error, hint, scope2) {
     return this.captureEvent(eventFromException(error, hint?.level ?? "error"), hint, scope2);
   }
@@ -767,6 +875,8 @@ async function withMonitorImpl(client2, captureError, monitorSlug, fn, options)
 
 // src/manager/api.ts
 var RETRY_DELAYS_MS2 = [1e3, 4e3, 16e3];
+var POLL_TIMEOUT_MS = 3e4;
+var UPDATE_TIMEOUT_MS = 1e4;
 var ManagerApiError = class extends Error {
   constructor(message, status) {
     super(message);
@@ -791,16 +901,39 @@ var ManagerApi = class {
   }
   /** Um request só — o loop de polling é quem decide o backoff entre tentativas. */
   async poll(request, signal) {
-    const response = await fetch(`${this.baseUrl}/poll`, {
-      method: "POST",
-      headers: this.headers(),
-      body: JSON.stringify(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 ManagerApiError(`poll falhou (HTTP ${response.status})`, response.status);
     }
-    return await response.json();
+    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 ManagerApiError("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.
@@ -809,25 +942,29 @@ var ManagerApi = class {
   async updateRun(runId, update) {
     for (let attempt = 0; ; attempt++) {
       let retriable;
+      let serverDelay;
       try {
         const response = await fetch(`${this.baseUrl}/runs/${encodeURIComponent(runId)}`, {
           method: "PATCH",
           headers: this.headers(),
-          body: JSON.stringify(update)
+          body: JSON.stringify(update),
+          signal: AbortSignal.timeout(UPDATE_TIMEOUT_MS)
         });
         if (response.ok) return;
         if (response.status >= 400 && response.status < 500 && response.status !== 429) {
           throw new ManagerApiError(`update rejeitado (HTTP ${response.status})`, response.status);
         }
+        if (response.status === 429) serverDelay = retryAfterMs(response);
         retriable = new Error(`HTTP ${response.status}`);
       } catch (error) {
         if (error instanceof ManagerApiError) throw error;
         retriable = error;
       }
-      const delay = RETRY_DELAYS_MS2[attempt];
-      if (delay === void 0) {
+      const base = RETRY_DELAYS_MS2[attempt];
+      if (base === void 0) {
         throw new Error(`update da run ${runId} descartado ap\xF3s retries: ${String(retriable)}`);
       }
+      const delay = serverDelay ?? jitter(base);
       this.logger.warn(`falha no update da run ${runId} (${String(retriable)}), retry em ${delay}ms`);
       await sleep(delay);
     }
@@ -951,13 +1088,14 @@ var RunReporter = class {
   }
   log(level, message) {
     if (this.dead) return;
-    printRunLog(this.context.task, level, message);
+    const scrubbed = scrubSecrets(message);
+    printRunLog(this.context.task, level, scrubbed);
     if (this.loggedCount >= MAX_LOGS_PER_RUN) {
       this.droppedCount++;
       return;
     }
     this.loggedCount++;
-    const truncated = message.length > MAX_LOG_MESSAGE_CHARS ? `${message.slice(0, MAX_LOG_MESSAGE_CHARS)}\u2026 [truncado]` : message;
+    const truncated = scrubbed.length > MAX_LOG_MESSAGE_CHARS ? `${scrubbed.slice(0, MAX_LOG_MESSAGE_CHARS)}\u2026 [truncado]` : scrubbed;
     this.buffer.push({ ts: nowISO(), level, message: truncated });
     if (this.buffer.length >= FLUSH_AT_BUFFERED) {
       this.flushLogs();
@@ -1141,8 +1279,8 @@ var ManagerAgent = class {
   constructor(options, registry2) {
     this.options = options;
     this.registry = registry2;
-    this.logger = makeLogger(options.debug ?? false, "[hobots-manager]");
-    const config = resolveConfig(options, "[hobots-manager]");
+    this.logger = makeLogger(options.debug ?? false, "[hobots]");
+    const config = resolveConfig(options, "[hobots]");
     this.api = new ManagerApi({ baseUrl: config.managerBaseUrl, key: config.key, logger: this.logger });
     this.client = options.client;
     this.pollIntervalMs = Math.max(MIN_POLL_INTERVAL_MS, options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS);
@@ -1176,10 +1314,10 @@ var ManagerAgent = class {
   start() {
     if (this.state === "started") return;
     if (this.state === "stopping") {
-      throw new Error("[hobots-manager] start() chamado durante stop() \u2014 aguarde o stop terminar");
+      throw new Error("[hobots] start() chamado durante stop() \u2014 aguarde o stop terminar");
     }
     if (this.registry.size === 0) {
-      throw new Error("[hobots-manager] nenhuma task registrada \u2014 chame register() antes de start()");
+      throw new Error("[hobots] nenhuma task registrada \u2014 chame register() antes de start()");
     }
     this.state = "started";
     if (this.options.installExitHandlers !== false && !this.uninstallShutdown) {
@@ -1261,6 +1399,7 @@ var ManagerAgent = class {
       this.consecutiveFailures = 0;
       this.consecutiveAuthFailures = 0;
       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);
@@ -1281,7 +1420,7 @@ var ManagerAgent = class {
     }
     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(ladder, 0), Math.max(this.pollIntervalMs, 16e3));
+    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;
   }
@@ -1293,7 +1432,7 @@ var ManagerAgent = class {
     this.activeRuns.add(promise);
   }
   async executeRun(run) {
-    const tx = new Transaction(this.client, `run:${run.task}`, "manager.run", true, run.id);
+    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);
     try {
@@ -1359,11 +1498,11 @@ function toRunError(error) {
   if (error instanceof Error) {
     return {
       type: error.name,
-      message: truncate(error.message, MAX_ERROR_MESSAGE_CHARS),
-      stack: error.stack ? truncate(error.stack, MAX_ERROR_STACK_CHARS) : void 0
+      message: scrubSecrets(truncate(error.message, MAX_ERROR_MESSAGE_CHARS)),
+      stack: error.stack ? scrubSecrets(truncate(error.stack, MAX_ERROR_STACK_CHARS)) : void 0
     };
   }
-  return { message: truncate(String(error), MAX_ERROR_MESSAGE_CHARS) };
+  return { message: scrubSecrets(truncate(String(error), MAX_ERROR_MESSAGE_CHARS)) };
 }
 
 // src/core.ts