hobots 3.4.0 → 4.1.0

package/dist/index.cjs

@@ -96,7 +96,7 @@ function scrubSecrets(text) {
 
 // src/utils.ts
 var SDK_NAME = "hobots";
-var SDK_VERSION = true ? "3.4.0" : "0.0.0-dev";
+var SDK_VERSION = true ? "4.1.0" : "0.0.0-dev";
 function isNode() {
   return typeof process !== "undefined" && typeof process.versions?.node === "string";
 }
@@ -281,7 +281,6 @@ var protocol_limits_default = {
   MAX_LOGS_PER_PATCH: 100,
   MAX_ERROR_MESSAGE_CHARS: 1e4,
   MAX_ERROR_STACK_CHARS: 2e4,
-  MAX_ITEMS_PER_RUN: 1e4,
   MAX_ITEMS_PER_REQUEST: 500,
   MAX_ITEM_MESSAGE_CHARS: 2e3,
   MAX_ITEM_PAYLOAD_BYTES: 16384,
@@ -580,7 +579,7 @@ function resolveConfig(options = {}, prefix = "[hobots]") {
   const origin = fromOption ? "clientSecret" : `env ${CLIENT_SECRET_ENV}`;
   if (!key) {
     throw new Error(
-      `${prefix} Client Secret ausente \u2014 defina a env ${CLIENT_SECRET_ENV} (ou passe clientSecret nas op\xE7\xF5es da task); copie o Client Secret do agente em Configura\xE7\xF5es \u2192 Agentes`
+      `${prefix} Client Secret ausente \u2014 defina a env ${CLIENT_SECRET_ENV} (ou passe clientSecret nas op\xE7\xF5es do register/start); copie o Client Secret do agente em Configura\xE7\xF5es \u2192 Agentes`
     );
   }
   if (!SECRET_PATTERN.test(key)) {
@@ -593,7 +592,7 @@ function resolveConfig(options = {}, prefix = "[hobots]") {
     key,
     baseUrl,
     ingestEndpoint: `${baseUrl}/v1/ingest`,
-    tasksBaseUrl: `${baseUrl}/v1/tasks`
+    runsBaseUrl: `${baseUrl}/v1/runs`
   };
 }
 
@@ -957,7 +956,7 @@ var TasksApi = class {
     const { signal: timeoutSignal, cleanup } = withTimeoutSignal(UPDATE_TIMEOUT_MS, signal);
     let response;
     try {
-      response = await fetch(`${this.baseUrl}/runs`, {
+      response = await fetch(`${this.baseUrl}`, {
         redirect: "error",
         method: "POST",
         headers: this.headers(),
@@ -971,12 +970,11 @@ var TasksApi = class {
       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);
+    if (typeof body?.id !== "string") {
+      throw new TasksApiError("resposta inv\xE1lida da cria\xE7\xE3o de run (id ausente)", 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",
@@ -991,9 +989,9 @@ var TasksApi = class {
     }
     const valid = [];
     for (const run of runs.slice(0, Math.max(0, max))) {
-      if (typeof run?.id !== "string" || typeof run.task !== "string") continue;
+      if (typeof run?.id !== "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 });
+      valid.push({ ...run, id: run.id, params });
     }
     if (valid.length < runs.length) {
       this.logger.warn(`poll retornou ${runs.length - valid.length} run(s) inv\xE1lida(s)/excedente(s) \u2014 descartadas`);
@@ -1008,7 +1006,7 @@ var TasksApi = class {
     let response;
     try {
       response = await fetchWithRetry(
-        () => fetch(`${this.baseUrl}/runs/${encodeURIComponent(runId)}`, {
+        () => fetch(`${this.baseUrl}/${encodeURIComponent(runId)}`, {
           redirect: "error",
           method: "PATCH",
           headers: this.headers(),
@@ -1030,7 +1028,7 @@ var TasksApi = class {
    * 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)}`, {
+    await fetch(`${this.baseUrl}/${encodeURIComponent(runId)}`, {
       redirect: "error",
       method: "PATCH",
       headers: this.headers(),
@@ -1047,7 +1045,7 @@ var TasksApi = class {
     let response;
     try {
       response = await fetchWithRetry(
-        () => fetch(`${this.baseUrl}/runs/${encodeURIComponent(runId)}/items`, {
+        () => fetch(`${this.baseUrl}/${encodeURIComponent(runId)}/items`, {
           redirect: "error",
           method: "POST",
           headers: this.headers(),
@@ -1077,7 +1075,7 @@ var TasksApi = class {
       () => withRequestTimeout(
         UPDATE_TIMEOUT_MS,
         signal,
-        (timeoutSignal) => fetch(`${this.baseUrl}/runs/${encodeURIComponent(runId)}/attachments`, {
+        (timeoutSignal) => fetch(`${this.baseUrl}/${encodeURIComponent(runId)}/attachments`, {
           redirect: "error",
           method: "POST",
           headers: this.headers(),
@@ -1128,7 +1126,7 @@ var TasksApi = class {
   /** Marca o anexo como enviado (ou falho). Best-effort — a leitura não depende disso. */
   async confirmAttachment(runId, attachmentId, request) {
     const response = await fetch(
-      `${this.baseUrl}/runs/${encodeURIComponent(runId)}/attachments/${encodeURIComponent(attachmentId)}`,
+      `${this.baseUrl}/${encodeURIComponent(runId)}/attachments/${encodeURIComponent(attachmentId)}`,
       {
         redirect: "error",
         method: "PATCH",
@@ -1386,8 +1384,8 @@ function splitLogArgs(message, rest) {
   if (text.length === 0) return { text: last.caption !== void 0 ? safeString(last.caption) : "captura de tela", image: last };
   return { text: joinLogArgs(text[0], text.slice(1)), image: last };
 }
-function printRunLog(task, level, message) {
-  const line = colorize(`[hobots:${task}] ${level.toUpperCase()}`, LOG_LEVEL_COLOR[level]);
+function printRunLog(level, message) {
+  const line = colorize(`[hobots] ${level.toUpperCase()}`, LOG_LEVEL_COLOR[level]);
   const method2 = level === "warning" ? "warn" : level === "success" ? "info" : level;
   console[method2](line, message);
 }
@@ -1415,7 +1413,6 @@ var MAX_CANCEL_CHECK_INTERVAL_MS = 15e3;
 var MAX_LOG_MESSAGE_CHARS = WIRE_LIMITS.MAX_LOG_MESSAGE_CHARS;
 var MAX_LOGS_PER_PATCH = WIRE_LIMITS.MAX_LOGS_PER_PATCH;
 var FLUSH_AT_BUFFERED = 20;
-var MAX_ITEMS_PER_RUN = WIRE_LIMITS.MAX_ITEMS_PER_RUN;
 var MAX_ITEMS_PER_REQUEST = WIRE_LIMITS.MAX_ITEMS_PER_REQUEST;
 var MAX_ITEM_MESSAGE_CHARS = WIRE_LIMITS.MAX_ITEM_MESSAGE_CHARS;
 var MAX_ITEM_PAYLOAD_BYTES = WIRE_LIMITS.MAX_ITEM_PAYLOAD_BYTES;
@@ -1433,10 +1430,11 @@ function scrubPayloadValue(value, depth) {
   return out;
 }
 var RunReporter = class {
-  constructor(api, runId, task, logger, tx, flushIntervalMs, cancelCheckIntervalMs, params = {}) {
+  constructor(api, runId, logger, tx, flushIntervalMs, cancelCheckIntervalMs, params = {}) {
     this.api = api;
     this.runId = runId;
     this.logger = logger;
+    this.tx = tx;
     this.flushIntervalMs = flushIntervalMs ?? DEFAULT_LOG_FLUSH_INTERVAL_MS;
     this.cancelCheckIntervalMs = Math.min(
       MAX_CANCEL_CHECK_INTERVAL_MS,
@@ -1515,12 +1513,12 @@ var RunReporter = class {
     const sleep2 = (ms) => cancelableSleep(ms, signal);
     this.context = {
       runId,
-      task,
       params,
       log,
       items,
       progress,
       transaction: tx,
+      flush: (timeoutMs) => this.flush(timeoutMs),
       signal,
       throwIfCanceled: checkCanceled,
       sleep: sleep2,
@@ -1530,6 +1528,7 @@ var RunReporter = class {
   api;
   runId;
   logger;
+  tx;
   context;
   buffer = [];
   dead = false;
@@ -1547,7 +1546,6 @@ var RunReporter = class {
   itemsChain = Promise.resolve();
   itemsTimer;
   itemSeq = 0;
-  itemCount = 0;
   /** Servidor sem o recurso (404) — para de tentar (e de avisar) nesta run. */
   itemsUnsupported = false;
   /** Cap de itens por run atingido (client-side ou 429) — degrada com um aviso só. */
@@ -1624,7 +1622,7 @@ var RunReporter = class {
     const scrubbed = scrubSecrets(safeString(message));
     const ts = nowISO();
     const attachmentId = image3 === void 0 ? void 0 : this.queueAttachment(image3, ts);
-    printRunLog(this.context.task, level, attachmentId ? `${scrubbed} [imagem]` : scrubbed);
+    printRunLog(level, attachmentId ? `${scrubbed} [imagem]` : scrubbed);
     this.push(level, scrubbed, true, attachmentId ? [attachmentId] : void 0, ts);
   }
   /** Bufferiza uma entrada de log sem eco no terminal (cap, truncate, flush). */
@@ -1670,6 +1668,21 @@ var RunReporter = class {
       this.enqueue({ status: "running", logs: logs.slice(i, i + MAX_LOGS_PER_PATCH) });
     }
   }
+  /**
+   * `hobots.flush()`: o bot decide quando entregar o que já fez — steps raiz finalizadas
+   * viram transactions parciais da run, e itens, logs e progresso pendentes saem já, sem
+   * esperar o throttle. Aguarda a entrega com teto. Nunca lança (pode ir num `finally`).
+   */
+  async flush(timeoutMs = ITEMS_DRAIN_MS) {
+    this.tx.flush();
+    this.flushItems();
+    if (this.progressDirty) this.flushProgress();
+    else this.flushLogs();
+    await Promise.race([
+      Promise.all([this.itemsChain, this.chain, this.tx.drain(timeoutMs)]).catch(() => void 0),
+      new Promise((resolve2) => unrefTimer(setTimeout(resolve2, timeoutMs)))
+    ]);
+  }
   /** Primeiro PATCH (claimed → running). Retorna false se a run já morreu (cancelada). */
   async reportRunning() {
     this.enqueue({ status: "running" });
@@ -1780,14 +1793,6 @@ var RunReporter = class {
    */
   addItem(status, message, payload, id, image3) {
     if (this.itemsClosed || this.itemsUnsupported) return;
-    if (this.itemCount >= MAX_ITEMS_PER_RUN) {
-      if (!this.itemsQuotaExceeded) {
-        this.itemsQuotaExceeded = true;
-        this.log("warning", `itens descartados: limite de ${MAX_ITEMS_PER_RUN} por execu\xE7\xE3o atingido`);
-      }
-      return;
-    }
-    this.itemCount++;
     let scrubbedPayload;
     if (payload) {
       scrubbedPayload = scrubPayloadValue(payload, 0);
@@ -2082,6 +2087,7 @@ function currentRunReporter() {
 }
 
 // src/transaction.ts
+var FLUSH_TRANSACTION_OP = "hobots.run.flush";
 var MAX_STEP_MESSAGE_CHARS = 2e3;
 function stepMessage(text) {
   return truncate(scrubSecrets(text), MAX_STEP_MESSAGE_CHARS);
@@ -2269,7 +2275,7 @@ var Transaction = class {
     if (this.attachmentSink) return this.attachmentSink(image3, nowISO());
     if (!this.warnedNoAttachmentSink) {
       this.warnedNoAttachmentSink = true;
-      console.warn("[hobots] imagem de step descartada \u2014 s\xF3 \xE9 suportada dentro de uma execu\xE7\xE3o de task");
+      console.warn("[hobots] imagem de step descartada \u2014 s\xF3 \xE9 suportada dentro de uma execu\xE7\xE3o");
     }
     return void 0;
   }
@@ -2303,6 +2309,60 @@ var Transaction = class {
     this.name = name;
     return this;
   }
+  /**
+   * Envia já as steps raiz finalizadas (e todas as descendentes, fechando as que
+   * ficaram abertas) como transactions parciais da mesma run (`op` hobots.run.flush,
+   * `event_id` novo, até 200 steps cada) e as tira da memória. Steps raiz ainda abertas
+   * ficam para o próximo flush ou para o `finish()`. É assim que um agente sempre
+   * ligado (`start()`), cuja run não termina, entrega as etapas enquanto processa.
+   * Devolve quantas steps foram enviadas.
+   */
+  flush() {
+    if (this.finished) return 0;
+    const ready = /* @__PURE__ */ new Set();
+    for (const step of this.steps) {
+      if (step.parentStepId === this.stepId && step.endTimestamp) ready.add(step.stepId);
+    }
+    if (ready.size === 0) return 0;
+    const batch = [];
+    const remaining = [];
+    for (const step of this.steps) {
+      if (ready.has(step.stepId) || ready.has(step.parentStepId)) {
+        ready.add(step.stepId);
+        batch.push(step);
+      } else {
+        remaining.push(step);
+      }
+    }
+    for (const step of batch) step.finish();
+    this.steps.splice(0, this.steps.length, ...remaining);
+    if (this.client) {
+      for (let i = 0; i < batch.length; i += MAX_STEPS) {
+        const chunk = batch.slice(i, i + MAX_STEPS);
+        const startTimestamp = chunk.reduce((min, step) => step.startTimestamp < min ? step.startTimestamp : min, chunk[0].startTimestamp);
+        const status = chunk.some((step) => step.status === "error") ? "error" : "ok";
+        this.client.sendTransaction(this.payload(uuid4(), FLUSH_TRANSACTION_OP, status, startTimestamp, nowISO(), chunk));
+      }
+    }
+    return batch.length;
+  }
+  /** Entrega já (com teto) o que está na fila do transport — as transactions parciais inclusive. */
+  async drain(timeoutMs) {
+    await this.client?.flush(timeoutMs);
+  }
+  payload(eventId, op, status, startTimestamp, timestamp, steps) {
+    return {
+      event_id: eventId,
+      name: this.name,
+      op,
+      status,
+      start_timestamp: startTimestamp,
+      timestamp,
+      steps: steps.map((step) => step.toJSON()),
+      tags: Object.keys(this.tags).length > 0 ? { ...this.tags } : void 0,
+      run_id: this.runId
+    };
+  }
   finish() {
     if (this.finished) return;
     this.finished = true;
@@ -2317,31 +2377,27 @@ var Transaction = class {
       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);
+    const steps = this.steps;
+    let first = 0;
+    while (steps.length - first > MAX_STEPS) {
+      const chunk = steps.slice(first, first + MAX_STEPS);
+      const status = chunk.some((step) => step.status === "error") ? "error" : "ok";
+      this.client.sendTransaction(this.payload(uuid4(), FLUSH_TRANSACTION_OP, status, chunk[0].startTimestamp, endTimestamp, chunk));
+      first += MAX_STEPS;
+    }
+    this.client.sendTransaction(this.payload(this.eventId, this.op, this.status, this.startTimestamp, endTimestamp, steps.slice(first)));
   }
 };
 
 // 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 { run, handler, api, client, logger, tracker } = input;
+  const options = handler.options;
+  const tx = new Transaction(client, "run", "hobots.run", run.id);
   const reporter = new RunReporter(
     api,
     run.id,
-    run.task,
     logger,
     tx,
     options.logFlushIntervalMs,
@@ -2357,9 +2413,9 @@ async function executeRun(input) {
       tx.finish();
       return;
     }
-    logger.debug(`executando run ${run.id} (${run.task})`);
+    logger.debug(`executando run ${run.id}`);
     try {
-      await runWithRunContext({ reporter }, () => invokeWithRetry(task, run, reporter, logger));
+      await runWithRunContext({ reporter }, () => invokeWithRetry(handler, run, reporter, logger));
       await reporter.finalizeAttachments();
       await reporter.finalizeItems();
       warnIncompleteProgress(reporter);
@@ -2387,11 +2443,11 @@ function warnIncompleteProgress(reporter) {
     `execu\xE7\xE3o conclu\xEDda com progresso incompleto: ${snapshot.current}/${snapshot.total} \u2014 o handler terminou sem processar (ou sem avan\xE7ar) todos os itens previstos`
   );
 }
-function invokeWithRetry(task, run, reporter, logger) {
-  const { retries, retryDelayMs } = task.options;
+function invokeWithRetry(agent, run, reporter, logger) {
+  const { retries, retryDelayMs } = agent.options;
   const total = retries + 1;
   const ctx = reporter.context;
-  return retryWithBackoff(() => invokeWithTimeout(task, run, reporter, logger), {
+  return retryWithBackoff(() => invokeWithTimeout(agent, run, reporter, logger), {
     retries,
     delayMs: (attempt) => resolveDelay(retryDelayMs, attempt, DEFAULT_RETRY_DELAY_MS),
     shouldRetry: () => !reporter.isDead,
@@ -2405,9 +2461,9 @@ function invokeWithRetry(task, run, reporter, logger) {
 }
 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;
+async function invokeWithTimeout(agent, run, reporter, logger) {
+  const { timeoutMs, cancelGraceMs } = agent.options;
+  const handler = agent.handler;
   const invocation = Promise.resolve().then(() => handler(run.params, reporter.context));
   const races = [];
   if (timeoutMs && timeoutMs > 0) {
@@ -2464,7 +2520,7 @@ var TaskAgent = class {
     this.logger = options.logger;
     this.api = options.api;
     this.client = options.client;
-    this.registry = options.registry;
+    this.handler = options.handler;
     this.tracker = options.tracker;
     this.pollIntervalMs = Math.max(MIN_POLL_INTERVAL_MS, options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS);
     this.backoff = new Backoff(this.logger, "poll", this.pollIntervalMs);
@@ -2474,7 +2530,7 @@ var TaskAgent = class {
   pollIntervalMs;
   api;
   client;
-  registry;
+  handler;
   tracker;
   backoff;
   state = "idle";
@@ -2490,10 +2546,10 @@ var TaskAgent = class {
       throw new Error("[hobots] start do agente durante o stop \u2014 aguarde o stop terminar");
     }
     this.state = "started";
-    this.logger.debug(`polling iniciado (tasks: ${this.registry.remoteTasks().map((task) => task.slug).join(", ")})`);
+    this.logger.debug(`polling iniciado (concorr\xEAncia ${this.handler.options.concurrency})`);
     this.schedule(0);
   }
-  /** Uma task registrada depois do boot entra no próximo poll — que é antecipado para já. */
+  /** Antecipa o próximo poll para já. */
   wake() {
     if (this.state !== "started") return;
     if (this.timer) {
@@ -2524,21 +2580,14 @@ 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. */
+  /** Slots livres do agente — vira o `max` do poll (nunca reivindica trabalho para deixar parado). */
   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) };
+    const free = this.handler.options.concurrency - this.tracker.activeCount;
+    return Math.min(MAX_CLAIM_PER_POLL, Math.max(0, free));
   }
   async tick() {
     if (this.state !== "started") return;
-    const { tasks, max } = this.freeSlots();
+    const max = this.freeSlots();
     if (max === 0) {
       this.schedule(this.pollIntervalMs);
       return;
@@ -2548,11 +2597,9 @@ var TaskAgent = class {
       const response = await this.api.poll(
         {
           // 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.
+          // então os dois canais convergem em um agente
           instance: this.options.instanceInfo(),
-          max,
-          tasks
+          max
         },
         this.pollAbort.signal
       );
@@ -2576,17 +2623,7 @@ var TaskAgent = class {
     this.activeRuns.add(promise);
   }
   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 });
+    await executeRun({ run, handler: this.handler, api: this.api, client: this.client, logger: this.logger, tracker: this.tracker });
   }
 };
 
@@ -2594,11 +2631,11 @@ var TaskAgent = class {
 var KEY_RE = /^[a-zA-Z0-9_.-]{1,100}$/;
 var MAX_COLUMNS = WIRE_LIMITS.MAX_ITEM_COLUMNS;
 var MAX_LABEL_CHARS = WIRE_LIMITS.MAX_ITEM_COLUMN_LABEL_CHARS;
-function normalizeItemColumns(slug, input, logger) {
+function normalizeItemColumns(input, logger) {
   if (input === void 0 || input === null) return void 0;
   const columns = input.columns;
   if (typeof input !== "object" || !Array.isArray(columns)) {
-    logger.warn(`task "${slug}": items.columns precisa ser uma lista \u2014 declara\xE7\xE3o de colunas ignorada`);
+    logger.warn(`items.columns precisa ser uma lista \u2014 declara\xE7\xE3o de colunas ignorada`);
     return void 0;
   }
   const result = [];
@@ -2608,15 +2645,15 @@ function normalizeItemColumns(slug, input, logger) {
     const rawLabel = typeof entry === "object" && entry !== null ? entry.label : void 0;
     const key = typeof rawKey === "string" ? rawKey.trim() : "";
     if (!KEY_RE.test(key)) {
-      logger.warn(`task "${slug}": coluna de item inv\xE1lida ignorada (${JSON.stringify(rawKey)}) \u2014 use letras, n\xFAmeros, ponto, h\xEDfen e underline`);
+      logger.warn(`coluna de item inv\xE1lida ignorada (${JSON.stringify(rawKey)}) \u2014 use letras, n\xFAmeros, ponto, h\xEDfen e underline`);
       continue;
     }
     if (seen.has(key)) {
-      logger.warn(`task "${slug}": coluna de item "${key}" repetida ignorada`);
+      logger.warn(`coluna de item "${key}" repetida ignorada`);
       continue;
     }
     if (result.length >= MAX_COLUMNS) {
-      logger.warn(`task "${slug}": no m\xE1ximo ${MAX_COLUMNS} colunas de item \u2014 "${key}" em diante ignoradas`);
+      logger.warn(`no m\xE1ximo ${MAX_COLUMNS} colunas de item \u2014 "${key}" em diante ignoradas`);
       break;
     }
     seen.add(key);
@@ -2628,15 +2665,15 @@ function normalizeItemColumns(slug, input, logger) {
 
 // src/tasks/local.ts
 var LocalRunner = class {
-  constructor(task, deps) {
-    this.task = task;
+  constructor(handler, deps) {
+    this.handler = handler;
     this.deps = deps;
-    this.backoff = new Backoff(deps.logger, `cria\xE7\xE3o da run "${task.slug}"`);
+    this.backoff = new Backoff(deps.logger, "cria\xE7\xE3o da run");
     this.done = new Promise((resolve2) => {
       this.resolveDone = resolve2;
     });
   }
-  task;
+  handler;
   deps;
   abort = new AbortController();
   backoff;
@@ -2647,17 +2684,17 @@ var LocalRunner = class {
     try {
       const run = await this.createRun();
       if (!run) return;
-      this.deps.logger.debug(`run ${run.id} aberta para "${this.task.slug}" (modo start)`);
+      this.deps.logger.debug(`run ${run.id} aberta (modo start)`);
       await executeRun({
         run,
-        task: this.task,
+        handler: this.handler,
         api: this.deps.api,
         client: this.deps.client,
         logger: this.deps.logger,
         tracker: this.deps.tracker
       });
     } catch (error) {
-      this.deps.logger.error(`erro inesperado na task "${this.task.slug}":`, error);
+      this.deps.logger.error("erro inesperado na execu\xE7\xE3o do agente:", error);
     } finally {
       this.resolveDone();
     }
@@ -2670,7 +2707,7 @@ var LocalRunner = class {
     for (; ; ) {
       if (this.abort.signal.aborted) return void 0;
       try {
-        return await this.deps.api.createRun({ task: this.task.slug, instance: this.deps.instanceInfo() }, this.abort.signal);
+        return await this.deps.api.createRun({ instance: this.deps.instanceInfo() }, this.abort.signal);
       } catch (error) {
         if (this.abort.signal.aborted) return void 0;
         await abortableSleep(this.backoff.next(error), this.abort.signal);
@@ -2680,45 +2717,6 @@ var LocalRunner = class {
 };
 
 // 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)`);
-    }
-    this.tasks.set(task.slug, task);
-  }
-  get(slug) {
-    return this.tasks.get(slug);
-  }
-  get size() {
-    return this.tasks.size;
-  }
-  /** Tasks que chegam pelo poll (register). */
-  remoteTasks() {
-    return [...this.tasks.values()].filter((task) => task.mode === "remote");
-  }
-  /** Tasks abertas pelo próprio bot (start). */
-  localTasks() {
-    return [...this.tasks.values()].filter((task) => task.mode === "local");
-  }
-  /** Todos os slugs, para a presença da instância (`instance.tasks`). */
-  allSlugs() {
-    return [...this.tasks.keys()];
-  }
-  /** Colunas de itens declaradas no código, por slug (`instance.task_items`); undefined se nenhuma task declarou. */
-  itemDeclarations() {
-    let result;
-    for (const task of this.tasks.values()) {
-      if (!task.options.itemColumns) continue;
-      (result ??= {})[task.slug] = { attributes: task.options.itemColumns };
-    }
-    return result;
-  }
-  clear() {
-    this.tasks.clear();
-  }
-};
 var RunTracker = class {
   constructor(api) {
     this.api = api;
@@ -2739,12 +2737,6 @@ var RunTracker = class {
   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;
@@ -2833,40 +2825,13 @@ 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;
-  }
+function createRuntime(options, handler) {
   const config = resolveConfig({ clientSecret: options.clientSecret });
   const logger = makeLogger(options.debug ?? false);
   const environment = resolveEnvironmentOption(options.environment);
@@ -2874,19 +2839,19 @@ function ensureRuntime(options) {
     { environment, release: options.release, tags: options.tags, debug: options.debug },
     config
   );
-  const api = new TasksApi({ baseUrl: config.tasksBaseUrl, key: config.key, logger });
-  runtime = {
+  const api = new TasksApi({ baseUrl: config.runsBaseUrl, key: config.key, logger });
+  const rt = {
     options: { ...options, clientSecret: void 0 },
     config,
     client,
     logger,
     api,
-    registry: new TaskRegistry(),
+    handler,
     tracker: new RunTracker(api),
     sampler: void 0,
     heartbeat: void 0,
     agent: void 0,
-    locals: /* @__PURE__ */ new Map(),
+    local: void 0,
     instanceId: resolveInstanceId(options.instanceId),
     environment,
     pollIntervalMs: void 0,
@@ -2896,24 +2861,19 @@ function ensureRuntime(options) {
     uninstallGlobalHandlers: options.captureUnhandled !== false ? installGlobalHandlers(client) : void 0,
     uninstallShutdown: void 0
   };
-  runtime.options.clientSecret = options.clientSecret;
   logger.debug("inicializado", { endpoint: config.ingestEndpoint });
-  return runtime;
+  return rt;
 }
-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`);
-  }
+function validateHandler(handler, fn) {
   if (typeof handler !== "function") {
-    throw new Error(`[hobots] ${fn}('${slug}'): o handler precisa ser uma fun\xE7\xE3o`);
+    throw new Error(`[hobots] ${fn}(): o handler precisa ser uma fun\xE7\xE3o \u2014 ${fn}(async (params) => { ... })`);
   }
-  return slug.trim();
 }
 function clampConcurrency(value) {
   if (value === void 0 || !Number.isFinite(value)) return 1;
   return Math.min(MAX_CONCURRENCY, Math.max(1, Math.floor(value)));
 }
-function resolveTaskOptions(slug, options, mode, logger) {
+function resolveRunOptions(options, mode, logger) {
   const retries = options.retries === void 0 || !Number.isFinite(options.retries) ? DEFAULT_RETRIES2 : Math.max(0, Math.floor(options.retries));
   return {
     retries,
@@ -2923,7 +2883,7 @@ function resolveTaskOptions(slug, options, mode, logger) {
     logFlushIntervalMs: options.logFlushIntervalMs,
     cancelCheckIntervalMs: options.cancelCheckIntervalMs,
     cancelGraceMs: options.cancelGraceMs ?? DEFAULT_CANCEL_GRACE_MS,
-    itemColumns: normalizeItemColumns(slug, options.items, logger)
+    itemColumns: normalizeItemColumns(options.items, logger)
   };
 }
 function instanceInfo(rt) {
@@ -2933,10 +2893,10 @@ function instanceInfo(rt) {
     host: hostname(),
     // ambiente da instância: junto do heartbeat, é como o servidor sabe onde o robô roda
     environment: rt.environment,
-    // TODAS as tasks (register + start) — o painel mostra o que o agente sabe fazer
-    tasks: rt.registry.allSlugs(),
+    // como esta instância trabalha — o painel mostra "sob demanda" / "sempre ligado"
+    mode: rt.handler.mode === "remote" ? "on_demand" : "always_on",
     // colunas da aba "itens" declaradas no código — a plataforma usa enquanto o usuário não personalizar
-    task_items: rt.registry.itemDeclarations(),
+    items: rt.handler.options.itemColumns ? { attributes: rt.handler.options.itemColumns } : void 0,
     // 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,
@@ -2949,22 +2909,22 @@ function ensureAgent(rt) {
     api: rt.api,
     client: rt.client,
     logger: rt.logger,
-    registry: rt.registry,
+    handler: rt.handler,
     tracker: rt.tracker,
     instanceInfo: () => instanceInfo(rt),
     pollIntervalMs: rt.pollIntervalMs
   });
   return rt.agent;
 }
-function launchLocal(rt, task) {
-  const runner = new LocalRunner(task, {
+function launchLocal(rt) {
+  const runner = new LocalRunner(rt.handler, {
     api: rt.api,
     client: rt.client,
     logger: rt.logger,
     tracker: rt.tracker,
     instanceInfo: () => instanceInfo(rt)
   });
-  rt.locals.set(task.slug, runner);
+  rt.local = runner;
   void runner.run();
 }
 async function boot(rt) {
@@ -2986,8 +2946,8 @@ async function boot(rt) {
   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);
+  if (rt.handler.mode === "remote") ensureAgent(rt).start();
+  else launchLocal(rt);
 }
 function scheduleBoot(rt) {
   if (rt.bootScheduled) return;
@@ -2996,34 +2956,23 @@ function scheduleBoot(rt) {
     rt.bootPromise = boot(rt).catch((error) => rt.logger.error("falha ao iniciar o SDK:", error));
   });
 }
-function addTask(fn, mode, task, handler, options) {
-  const slug = validateTask(task, handler, fn);
-  const rt = ensureRuntime(options);
-  if (mode === "remote" && options.pollIntervalMs !== void 0) {
-    if (rt.pollIntervalMs === void 0 && !rt.agent) rt.pollIntervalMs = options.pollIntervalMs;
-    else if (rt.pollIntervalMs !== options.pollIntervalMs) {
-      rt.logger.warn('op\xE7\xE3o "pollIntervalMs" divergente ignorada \u2014 o primeiro register() define o intervalo do poll');
-    }
-  }
-  const registered = { slug, mode, handler, options: resolveTaskOptions(slug, options, mode, rt.logger) };
-  rt.registry.add(registered);
-  if (!rt.booted) {
-    scheduleBoot(rt);
-    return;
-  }
-  if (mode === "remote") {
-    const agent = ensureAgent(rt);
-    agent.start();
-    agent.wake();
-  } else {
-    launchLocal(rt, registered);
+function startAgent(fn, mode, handler, options) {
+  validateHandler(handler, fn);
+  if (runtime) {
+    throw new Error(`[hobots] ${fn}(): o agente j\xE1 foi iniciado \u2014 register()/start() s\xF3 pode ser chamado uma vez por processo (chame hobots.close() antes de iniciar de novo)`);
   }
+  const logger = makeLogger(options.debug ?? false);
+  const agentHandler = { mode, handler, options: resolveRunOptions(options, mode, logger) };
+  const rt = createRuntime(options, agentHandler);
+  if (mode === "remote" && options.pollIntervalMs !== void 0) rt.pollIntervalMs = options.pollIntervalMs;
+  runtime = rt;
+  scheduleBoot(rt);
 }
-function register(task, handler, options = {}) {
-  addTask("register", "remote", task, handler, options);
+function register(handler, options = {}) {
+  startAgent("register", "remote", handler, options);
 }
-function start(task, handler, options = {}) {
-  addTask("start", "local", task, handler, options);
+function start(handler, options = {}) {
+  startAgent("start", "local", handler, options);
 }
 function currentReporter() {
   return currentRunReporter() ?? runtime?.tracker.singleActive();
@@ -3037,7 +2986,7 @@ function toRunLogLevel(type) {
 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");
+    rt.logger.warn("attachment descartado \u2014 s\xF3 \xE9 suportado dentro de uma execu\xE7\xE3o");
     return;
   }
   const withMeta = typeof attachment === "object" && !isImageAttachment(attachment) && "image" in attachment ? image(attachment.image, { caption: attachment.caption, contentType: attachment.contentType }) : attachment;
@@ -3048,7 +2997,7 @@ function captureException(error, hint) {
   if (!rt) {
     if (!warnedNoRuntime) {
       warnedNoRuntime = true;
-      console.warn("[hobots] captureException antes de registrar uma task (register/start) \u2014 evento descartado");
+      console.warn("[hobots] captureException antes de iniciar o agente (register/start) \u2014 evento descartado");
     }
     return void 0;
   }
@@ -3064,7 +3013,7 @@ async function close(timeoutMs = 3e4) {
   runtime = void 0;
   await rt.bootPromise;
   if (rt.agent) await rt.agent.stop(0);
-  for (const local of rt.locals.values()) local.stop();
+  rt.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`);
@@ -3082,15 +3031,14 @@ 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 message = `hobots.${member} usado fora de uma execu\xE7\xE3o \u2014 ignorado (inicie o agente 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 fallbackLogAt = (level) => (message, ...rest) => {
   const { text, image: dropped } = splitLogArgs(message, rest);
-  printRunLog(FALLBACK_TASK, level, dropped ? `${text} [imagem descartada]` : text);
+  printRunLog(level, dropped ? `${text} [imagem descartada]` : text);
 };
 var fallbackLog = {
   debug: fallbackLogAt("debug"),
@@ -3107,7 +3055,7 @@ var fallbackEachSink = {
   advance: noop,
   checkCanceled: noop,
   isAborted: () => false,
-  logError: (message) => printRunLog(FALLBACK_TASK, "error", message)
+  logError: (message) => printRunLog("error", message)
 };
 var fallbackItems = {
   add: noop,
@@ -3134,7 +3082,6 @@ function method(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),
@@ -3143,17 +3090,18 @@ var hobots = Object.defineProperties({}, {
   signal: getter("signal", () => neverAborts),
   throwIfCanceled: method(() => resolve("throwIfCanceled")?.throwIfCanceled()),
   sleep: method((ms) => resolve("sleep")?.sleep(ms) ?? sleep(ms)),
+  flush: method((timeoutMs) => resolve("flush")?.flush(timeoutMs) ?? Promise.resolve()),
   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);
+  register: method((handler, options) => {
+    register(handler, options);
     installGlobalHobots();
   }),
-  start: method((task, handler, options) => {
-    start(task, handler, options);
+  start: method((handler, options) => {
+    start(handler, options);
     installGlobalHobots();
   }),
   close: method((timeoutMs) => close(timeoutMs)),