hobots 3.0.0 → 3.2.0

package/README.md

@@ -27,6 +27,7 @@ CommonJS: `const { hobots } = require('hobots')`.
 ```bash
 export HOBOTS_CLIENT_SECRET=hb_<64 hex>   # Configurações → Agentes
 export HOBOTS_INSTANCE_ID=vm-cliente-01   # opcional — default: hostname da máquina
+export HOBOTS_ENVIRONMENT=staging         # opcional — default: production
 ```
 
 ```js
@@ -65,6 +66,7 @@ O objeto **`hobots`** é global: `hobots.log`, `hobots.items`, `hobots.progress`
 | --- | --- | --- |
 | `HOBOTS_CLIENT_SECRET` | `clientSecret` | O **Client Secret do agente** (`hb_<64 hex>`), copiado em **Configurações → Agentes**. Viaja só no header `Authorization: Bearer`, nunca na URL. Ausente ou inválido → `register()`/`start()` lança na hora, citando a env (sem ecoar o valor). |
 | `HOBOTS_INSTANCE_ID` | `instanceId` | Identidade **estável** desta instância do robô (`vm-cliente-01`). Sem ela, o hostname. Heartbeat e tasks convergem nela: **um agente só** no painel. |
+| `HOBOTS_ENVIRONMENT` | `environment` | Ambiente lógico do robô (`development` \| `testing` \| `staging` \| `production`). Sem ela, `production`. |
 | `HOBOTS_API_URL` | — | Só em desenvolvimento: aponta o SDK para outro host (`http://localhost:3001`). Em produção é sempre `https://api2.hobots.app`. |
 
 A opção passada em `register()`/`start()` tem precedência sobre a env — útil para copiar e colar o snippet do app.
@@ -91,8 +93,8 @@ Os dois podem coexistir no mesmo processo: um monitor sempre ligado + tasks sob
 
 | Membro | O que faz |
 | --- | --- |
-| `hobots.log.debug/info/warn/error/success(msg)` | Log da execução, enviado incrementalmente ao app (e ecoado no terminal). **Nunca lança** — pode ir em `finally`. |
-| `hobots.items.succeeded(payload?, { id }?)` · `.failed(msg, payload?, …)` · `.occurrence(msg, payload?, …)` · `.add({...})` | **A entrega do robô**: cada item processado, com status e atributos (viram colunas no app). Bufferizado, em lotes. |
+| `hobots.log.debug/info/warn/error/success(msg, ...rest)` | Log da execução, enviado incrementalmente ao app (e ecoado no terminal). Aceita vários argumentos como `console.log` — `hobots.log.info('nota', numero, 'ok')` — cada um vira texto, unidos por espaço. **Nunca lança** — pode ir em `finally`. |
+| `hobots.items.succeeded(payload?, { id }?)` · `.failed(msg, payload?, …)` · `.occurrence(msg, payload?, …)` · `.add({...})` | **A entrega do robô**: cada item processado, com status e atributos (viram colunas no app — declare-as com a opção `items: { columns: [...] }` do `register`/`start`). Bufferizado, em lotes. |
 | `hobots.progress.total(n)` · `.advance(k = 1)` · `.set(atual, total?)` · `.current` · `.snapshot` | Barra, percentual e tempo restante na solicitação. Sem `total()` nada é enviado. |
 | `hobots.transaction.startChild(op, descrição)` | Uma **step** no waterfall de performance da execução. A transaction da execução já existe e é finalizada pelo SDK. |
 | `hobots.attach(imagem, { caption?, level? })` | Pendura um **print** (PNG/JPEG/WEBP, até 5 MB, 20 por execução) na linha de log. Nunca lança nem bloqueia. |
@@ -143,7 +145,7 @@ hobots.start(task, handler, options?: StartOptions);
 | --- | --- | --- |
 | `clientSecret` | env `HOBOTS_CLIENT_SECRET` | Client Secret do agente |
 | `instanceId` | env `HOBOTS_INSTANCE_ID` → hostname | Identidade da instância |
-| `environment` | `'production'` | `development` \| `testing` \| `staging` \| `production` — decide quem é alertado |
+| `environment` | env `HOBOTS_ENVIRONMENT` → `'production'` | `development` \| `testing` \| `staging` \| `production` — decide quem é alertado |
 | `release` | — | Versão do programa, ex. `robo-nfe@1.4.2` |
 | `tags` | — | Tags de todos os eventos |
 | `debug` | `false` | Loga a atividade do SDK |
@@ -176,6 +178,10 @@ Sem handler próprio de sinal, um `SIGINT`/`SIGTERM` (ou erro fatal) com execuç
 
 ---
 
+## Changelog resumido
+
+- **3.1.0** — `hobots.log.*` aceita vários argumentos (como `console.log`); `retries` inválido (`NaN`) cai no default em vez de tentar para sempre; 429 de itens e 429/501/503 de anexo são definitivos (sem esperar a ladder — `quota`/`unsupported` passam a funcionar de fato); timeout **por requisição** nos anexos; truncamento nos limites do servidor (tag 512, fingerprint 10×255, nome de transaction 500, 200 steps, `exception.value` 8192, `filename` 1024); PNG acima de 20 000 px não declara dimensões; PATCH terminal nunca passa de 100 logs.
+
 ## Documentação
 
 - [Getting started](./docs/getting-started.md) — instalação, envs, primeira task nos dois modos.

package/dist/index.cjs

@@ -42,6 +42,7 @@ module.exports = __toCommonJS(src_exports);
 
 // src/stacktrace.ts
 var MAX_FRAMES = 50;
+var MAX_FILENAME_CHARS = 1024;
 var FRAME_RE = /^\s*at\s+(?:async\s+)?(?:(.+?)\s+\()?(.+?)\)?$/;
 var LOCATION_RE = /^(.*?):(\d+):(\d+)$/;
 function isInApp(filename) {
@@ -64,7 +65,7 @@ function parseStacktrace(stack) {
     const filename = loc ? loc[1] : location;
     frames.push({
       function: fn || "<anonymous>",
-      filename: filename || void 0,
+      filename: filename ? filename.slice(0, MAX_FILENAME_CHARS) : void 0,
       lineno: loc?.[2] ? Number(loc[2]) : void 0,
       colno: loc?.[3] ? Number(loc[3]) : void 0,
       in_app: isInApp(filename)
@@ -94,7 +95,7 @@ function scrubSecrets(text) {
 
 // src/utils.ts
 var SDK_NAME = "hobots";
-var SDK_VERSION = true ? "3.0.0" : "0.0.0-dev";
+var SDK_VERSION = true ? "3.2.0" : "0.0.0-dev";
 function isNode() {
   return typeof process !== "undefined" && typeof process.versions?.node === "string";
 }
@@ -150,9 +151,19 @@ function jitter(baseMs) {
 function truncate(value, max) {
   return value.length > max ? `${value.slice(0, max)}\u2026 [truncado]` : value;
 }
+function safeString(value) {
+  if (typeof value === "string") return value;
+  try {
+    const json = JSON.stringify(value);
+    if (json && json !== "{}") return json;
+  } catch {
+  }
+  return String(value);
+}
 var DEFAULT_RETRY_DELAYS_MS = [1e3, 4e3, 16e3];
 async function fetchWithRetry(send, options) {
   const delays = options.delays ?? DEFAULT_RETRY_DELAYS_MS;
+  const noRetry = options.noRetryStatuses ?? [];
   for (let attempt = 0; ; attempt++) {
     let retriable;
     let serverDelay;
@@ -160,6 +171,7 @@ async function fetchWithRetry(send, options) {
       const response = await send();
       if (response.ok) return response;
       if (response.status >= 400 && response.status < 500 && response.status !== 429) return response;
+      if (noRetry.includes(response.status)) return response;
       if (response.status === 429) serverDelay = retryAfterMs(response);
       retriable = new Error(`HTTP ${response.status}`);
     } catch (error) {
@@ -232,26 +244,18 @@ function colorize(text, color) {
 }
 
 // src/eventbuilder.ts
-function safeString(value) {
-  if (typeof value === "string") return value;
-  try {
-    const json = JSON.stringify(value);
-    if (json && json !== "{}") return json;
-  } catch {
-  }
-  return String(value);
-}
+var MAX_EXCEPTION_VALUE_CHARS = 8192;
 function eventFromException(error, type = "error") {
   let exceptionType;
   let value;
   let frames = [];
   if (error instanceof Error) {
     exceptionType = error.name || "Error";
-    value = scrubSecrets(error.message);
+    value = truncate(scrubSecrets(error.message), MAX_EXCEPTION_VALUE_CHARS);
     frames = parseStacktrace(error.stack);
   } else {
     exceptionType = "NonError";
-    value = scrubSecrets(safeString(error));
+    value = truncate(scrubSecrets(safeString(error)), MAX_EXCEPTION_VALUE_CHARS);
   }
   return {
     event_id: uuid4(),
@@ -377,6 +381,18 @@ var Transport = class {
 };
 
 // src/client.ts
+var MAX_TAG_VALUE_CHARS = 512;
+var MAX_FINGERPRINT_ITEMS = 10;
+var MAX_FINGERPRINT_ITEM_CHARS = 255;
+var MAX_TRANSACTION_NAME_CHARS = 500;
+var MAX_STEPS = 200;
+function clipTags(tags) {
+  return Object.fromEntries(Object.entries(tags).map(([key, value]) => [key, truncate(String(value), MAX_TAG_VALUE_CHARS)]));
+}
+function clipFingerprint(fingerprint) {
+  if (fingerprint === void 0) return void 0;
+  return fingerprint.slice(0, MAX_FINGERPRINT_ITEMS).map((item) => truncate(String(item), MAX_FINGERPRINT_ITEM_CHARS));
+}
 function runtimeContexts() {
   if (isNode()) {
     return {
@@ -445,20 +461,27 @@ var Client = class {
       type: hint?.type ?? event.type ?? "error",
       release: event.release ?? this.options.release,
       environment: this.resolveEnvironment(event.environment),
-      tags: Object.keys(tags).length > 0 ? tags : void 0,
+      tags: Object.keys(tags).length > 0 ? clipTags(tags) : void 0,
       extra: Object.keys(extra).length > 0 ? extra : void 0,
       contexts: { ...runtimeContexts(), ...machine, ...event.contexts },
-      fingerprint: hint?.fingerprint ?? event.fingerprint
+      fingerprint: clipFingerprint(hint?.fingerprint ?? event.fingerprint)
     };
   }
   sendTransaction(payload) {
+    let steps = payload.steps;
+    if (steps.length > MAX_STEPS) {
+      this.logger.warn(`transaction com ${steps.length} steps \u2014 enviando as primeiras ${MAX_STEPS}`);
+      steps = steps.slice(0, MAX_STEPS);
+    }
     this.transport.enqueue({
       type: "transaction",
       payload: {
         ...payload,
+        name: truncate(payload.name || "(sem nome)", MAX_TRANSACTION_NAME_CHARS),
+        steps,
         release: payload.release ?? this.options.release,
         environment: this.resolveEnvironment(payload.environment),
-        tags: { ...this.options.tags, ...payload.tags }
+        tags: clipTags({ ...this.options.tags, ...payload.tags })
       }
     });
   }
@@ -551,12 +574,19 @@ function resolveConfig(options = {}, prefix = "[hobots]") {
 
 // src/env.ts
 var INSTANCE_ID_ENV = "HOBOTS_INSTANCE_ID";
+var ENVIRONMENT_ENV = "HOBOTS_ENVIRONMENT";
 function resolveInstanceId(option) {
   const fromOption = option?.trim();
   if (fromOption) return fromOption;
   if (typeof process === "undefined" || !process.env) return void 0;
   return process.env[INSTANCE_ID_ENV]?.trim() || void 0;
 }
+function resolveEnvironmentOption(option) {
+  const fromOption = option?.trim();
+  if (fromOption) return fromOption;
+  if (typeof process === "undefined" || !process.env) return void 0;
+  return process.env[ENVIRONMENT_ENV]?.trim() || void 0;
+}
 async function fallbackInstanceId() {
   if (!isNode()) return "browser";
   try {
@@ -635,6 +665,11 @@ function externalListenerCount(event) {
 var emergencyTasks = [];
 function addEmergencyTask(task) {
   emergencyTasks.push(task);
+  const forget = () => {
+    const index = emergencyTasks.indexOf(task);
+    if (index !== -1) emergencyTasks.splice(index, 1);
+  };
+  task.then(forget, forget);
 }
 async function awaitEmergencyTasks(capMs) {
   if (emergencyTasks.length === 0) return;
@@ -829,6 +864,8 @@ var MachineSampler = class {
 // src/tasks/api.ts
 var POLL_TIMEOUT_MS = 3e4;
 var UPDATE_TIMEOUT_MS = 1e4;
+var ATTACHMENT_TERMINAL_STATUSES = [429, 501, 503];
+var ITEMS_TERMINAL_STATUSES = [429];
 var UPLOAD_TIMEOUT_MS = 3e4;
 var UPLOAD_RETRY_DELAYS_MS = [1e3, 4e3];
 var TasksApiError = class extends Error {
@@ -838,6 +875,14 @@ var TasksApiError = class extends Error {
     this.name = "TasksApiError";
   }
 };
+async function withRequestTimeout(timeoutMs, external, send) {
+  const { signal, cleanup } = withTimeoutSignal(timeoutMs, external);
+  try {
+    return await send(signal);
+  } finally {
+    cleanup();
+  }
+}
 var TasksApi = class {
   baseUrl;
   key;
@@ -974,12 +1019,9 @@ var TasksApi = class {
           body: JSON.stringify(request),
           signal: AbortSignal.timeout(UPDATE_TIMEOUT_MS)
         }),
-        { logger: this.logger, label: `itens da run ${runId}` }
+        { logger: this.logger, label: `itens da run ${runId}`, noRetryStatuses: ITEMS_TERMINAL_STATUSES }
       );
     } catch (error) {
-      if (error instanceof Error && error.message === "HTTP 429") {
-        throw new TasksApiError("envio de itens rejeitado (HTTP 429)", 429);
-      }
       throw new Error(`envio de itens da run ${runId} descartado ap\xF3s retries: ${String(error)}`);
     }
     if (!response.ok) {
@@ -996,21 +1038,19 @@ var TasksApi = class {
    * "esta instalação não tem anexos" — o RunReporter degrada em silêncio a partir daí.
    */
   async createAttachment(runId, request, signal) {
-    const { signal: timeoutSignal, cleanup } = withTimeoutSignal(UPDATE_TIMEOUT_MS, signal);
-    let response;
-    try {
-      response = await fetchWithRetry(
-        () => fetch(`${this.baseUrl}/runs/${encodeURIComponent(runId)}/attachments`, {
+    const response = await fetchWithRetry(
+      () => withRequestTimeout(
+        UPDATE_TIMEOUT_MS,
+        signal,
+        (timeoutSignal) => fetch(`${this.baseUrl}/runs/${encodeURIComponent(runId)}/attachments`, {
           method: "POST",
           headers: this.headers(),
           body: JSON.stringify(request),
           signal: timeoutSignal
-        }),
-        { logger: this.logger, label: `anexo da run ${runId}` }
-      );
-    } finally {
-      cleanup();
-    }
+        })
+      ),
+      { logger: this.logger, label: `anexo da run ${runId}`, noRetryStatuses: ATTACHMENT_TERMINAL_STATUSES }
+    );
     if (!response.ok) {
       throw new TasksApiError(`cria\xE7\xE3o de anexo rejeitada (HTTP ${response.status})`, response.status);
     }
@@ -1030,22 +1070,20 @@ var TasksApi = class {
    * está na assinatura da URL, e mandar o client secret para fora da API seria vazamento.
    */
   async uploadAttachment(url, headers, body, signal) {
-    const { signal: timeoutSignal, cleanup } = withTimeoutSignal(UPLOAD_TIMEOUT_MS, signal);
-    let response;
-    try {
-      response = await fetchWithRetry(
-        () => fetch(url, {
+    const response = await fetchWithRetry(
+      () => withRequestTimeout(
+        UPLOAD_TIMEOUT_MS,
+        signal,
+        (timeoutSignal) => fetch(url, {
           method: "PUT",
           headers,
           // BodyInit não aceita Uint8Array<ArrayBufferLike> em todos os lib.dom; o buffer é o mesmo
           body,
           signal: timeoutSignal
-        }),
-        { delays: UPLOAD_RETRY_DELAYS_MS, logger: this.logger, label: "upload de anexo" }
-      );
-    } finally {
-      cleanup();
-    }
+        })
+      ),
+      { delays: UPLOAD_RETRY_DELAYS_MS, logger: this.logger, label: "upload de anexo" }
+    );
     if (!response.ok) {
       throw new TasksApiError(`upload de anexo rejeitado (HTTP ${response.status})`, response.status);
     }
@@ -1083,10 +1121,12 @@ var Backoff = class {
     this.authFailures = 0;
   }
   next(error) {
-    if (error instanceof TasksApiError && error.status === 401) {
+    if (error instanceof TasksApiError && (error.status === 401 || error.status === 402)) {
       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");
+        this.logger.error(
+          error.status === 402 ? "agente fora do limite do plano (402) \u2014 fa\xE7a upgrade em Plano e cobran\xE7a para reativ\xE1-lo" : "chave rejeitada (401) \u2014 verifique o Client Secret do agente em Configura\xE7\xF5es \u2192 Agentes"
+        );
       }
       return Math.max(this.floorMs, AUTH_FAILURE_INTERVAL_MS);
     }
@@ -1120,7 +1160,8 @@ function resolveDelay(delay, attempt, 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 requested = options.retries ?? DEFAULT_RETRIES;
+  const retries = Number.isFinite(requested) ? Math.max(0, Math.floor(requested)) : DEFAULT_RETRIES;
   const wait = options.wait ?? sleep;
   for (let attempt = 1; ; attempt++) {
     if (options.signal?.aborted) throw runCanceledError();
@@ -1155,6 +1196,7 @@ function startsWith(bytes, signature, offset = 0) {
   return signature.every((byte, index) => bytes[offset + index] === byte);
 }
 var PNG_MAGIC = [137, 80, 78, 71, 13, 10, 26, 10];
+var MAX_PNG_DIMENSION = 2e4;
 var JPEG_MAGIC = [255, 216, 255];
 var RIFF_MAGIC = [82, 73, 70, 70];
 var WEBP_MAGIC = [87, 69, 66, 80];
@@ -1170,6 +1212,7 @@ function readPngDimensions(bytes) {
   const width = view.getUint32(16);
   const height = view.getUint32(20);
   if (width === 0 || height === 0) return void 0;
+  if (width > MAX_PNG_DIMENSION || height > MAX_PNG_DIMENSION) return void 0;
   return { width, height };
 }
 async function toBytes(input) {
@@ -1186,6 +1229,10 @@ var LOG_LEVEL_COLOR = {
   error: "red",
   success: "green"
 };
+function joinLogArgs(message, rest) {
+  if (rest.length === 0) return safeString(message);
+  return [message, ...rest].map(safeString).join(" ");
+}
 function printRunLog(task, level, message) {
   const line = colorize(`[hobots:${task}] ${level.toUpperCase()}`, LOG_LEVEL_COLOR[level]);
   const method2 = level === "warning" ? "warn" : level === "success" ? "info" : level;
@@ -1243,11 +1290,11 @@ var RunReporter = class {
       Math.max(MIN_CANCEL_CHECK_INTERVAL_MS, cancelCheckIntervalMs ?? DEFAULT_CANCEL_CHECK_INTERVAL_MS)
     );
     const log = {
-      debug: (message) => this.log("debug", message),
-      info: (message) => this.log("info", message),
-      warn: (message) => this.log("warning", message),
-      error: (message) => this.log("error", message),
-      success: (message) => this.log("success", message)
+      debug: (message, ...rest) => this.log("debug", joinLogArgs(message, rest)),
+      info: (message, ...rest) => this.log("info", joinLogArgs(message, rest)),
+      warn: (message, ...rest) => this.log("warning", joinLogArgs(message, rest)),
+      error: (message, ...rest) => this.log("error", joinLogArgs(message, rest)),
+      success: (message, ...rest) => this.log("success", joinLogArgs(message, rest))
     };
     tx.setLifecycleSink((level, message) => this.push(level, message));
     const checkCanceled = () => this.checkCanceled();
@@ -1397,7 +1444,7 @@ var RunReporter = class {
   }
   log(level, message) {
     if (this.dead) return;
-    const scrubbed = scrubSecrets(message);
+    const scrubbed = scrubSecrets(safeString(message));
     printRunLog(this.context.task, level, scrubbed);
     this.push(level, scrubbed, true);
   }
@@ -1456,13 +1503,25 @@ var RunReporter = class {
     this.stopCancelWatch();
     this.clearFlushTimer();
     this.forceFinalProgress();
-    this.enqueue({ status: "succeeded", logs: this.takeLogs() });
+    this.enqueue({ status: "succeeded", logs: this.takeLogsForTerminal() });
   }
   reportFailure(error) {
     this.stopCancelWatch();
     this.clearFlushTimer();
     this.forceFinalProgress();
-    this.enqueue({ status: "failed", error, logs: this.takeLogs() });
+    this.enqueue({ status: "failed", error, logs: this.takeLogsForTerminal() });
+  }
+  /**
+   * Esvazia o buffer para o PATCH terminal respeitando o teto de 100 logs por PATCH:
+   * o excedente sai antes, em PATCHes `running` na mesma cadeia (a ordem se mantém).
+   */
+  takeLogsForTerminal() {
+    let logs = this.takeLogs();
+    while (logs.length > MAX_LOGS_PER_PATCH) {
+      this.enqueue({ status: "running", logs: logs.slice(0, MAX_LOGS_PER_PATCH) });
+      logs = logs.slice(MAX_LOGS_PER_PATCH);
+    }
+    return logs;
   }
   // ── Progresso ────────────────────────────────────────────────────────────────
   /** Valida, clampa e marca o snapshot como pendente; agenda flush só se nada mais vai sair. */
@@ -1570,7 +1629,7 @@ var RunReporter = class {
       id: id ? truncate(String(id), 255) : uuid4(),
       seq: this.itemSeq++,
       status,
-      ...message ? { message: truncate(scrubSecrets(message), MAX_ITEM_MESSAGE_CHARS) } : {},
+      ...message ? { message: truncate(scrubSecrets(safeString(message)), MAX_ITEM_MESSAGE_CHARS) } : {},
       ...scrubbedPayload ? { payload: scrubbedPayload } : {},
       ts: nowISO()
     });
@@ -1659,8 +1718,10 @@ var RunReporter = class {
   async attach(image, options = {}) {
     const id = uuid4();
     const level = options.level ?? "info";
-    const caption = options.caption ? truncate(scrubSecrets(options.caption), MAX_CAPTION_CHARS) : void 0;
-    const message = options.message ?? options.caption ?? "captura de tela";
+    const rawCaption = options.caption !== void 0 ? safeString(options.caption) : void 0;
+    const rawMessage = options.message !== void 0 ? safeString(options.message) : void 0;
+    const caption = rawCaption ? truncate(scrubSecrets(rawCaption), MAX_CAPTION_CHARS) : void 0;
+    const message = rawMessage ?? rawCaption ?? "captura de tela";
     if (this.dead) return { id, ok: false, reason: "canceled" };
     if (this.attachmentsUnsupported) {
       this.log(level, message);
@@ -2280,6 +2341,42 @@ var TaskAgent = class {
   }
 };
 
+// src/tasks/item-columns.ts
+var KEY_RE = /^[a-zA-Z0-9_.-]{1,100}$/;
+var MAX_COLUMNS = 12;
+var MAX_LABEL_CHARS = 60;
+function normalizeItemColumns(slug, input, logger) {
+  if (input === void 0 || input === null) return void 0;
+  const columns = input.columns;
+  if (typeof input !== "object" || !Array.isArray(columns)) {
+    logger.warn(`task "${slug}": items.columns precisa ser uma lista \u2014 declara\xE7\xE3o de colunas ignorada`);
+    return void 0;
+  }
+  const result = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const entry of columns) {
+    const rawKey = typeof entry === "string" ? entry : entry?.key;
+    const rawLabel = typeof entry === "object" && entry !== null ? entry.label : void 0;
+    const key = typeof rawKey === "string" ? rawKey.trim() : "";
+    if (!KEY_RE.test(key)) {
+      logger.warn(`task "${slug}": coluna de item inv\xE1lida ignorada (${JSON.stringify(rawKey)}) \u2014 use letras, n\xFAmeros, ponto, h\xEDfen e underline`);
+      continue;
+    }
+    if (seen.has(key)) {
+      logger.warn(`task "${slug}": coluna de item "${key}" repetida ignorada`);
+      continue;
+    }
+    if (result.length >= MAX_COLUMNS) {
+      logger.warn(`task "${slug}": no m\xE1ximo ${MAX_COLUMNS} colunas de item \u2014 "${key}" em diante ignoradas`);
+      break;
+    }
+    seen.add(key);
+    const label = typeof rawLabel === "string" ? rawLabel.trim().slice(0, MAX_LABEL_CHARS) : "";
+    result.push(label ? { key, label } : { key });
+  }
+  return result.length > 0 ? result : void 0;
+}
+
 // src/tasks/local.ts
 var LocalRunner = class {
   constructor(task, deps) {
@@ -2358,6 +2455,15 @@ var TaskRegistry = class {
   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();
   }
@@ -2511,8 +2617,9 @@ function ensureRuntime(options) {
   }
   const config = resolveConfig({ clientSecret: options.clientSecret });
   const logger = makeLogger(options.debug ?? false);
+  const environment = resolveEnvironmentOption(options.environment);
   const client = new Client(
-    { environment: options.environment, release: options.release, tags: options.tags, debug: options.debug },
+    { environment, release: options.release, tags: options.tags, debug: options.debug },
     config
   );
   const api = new TasksApi({ baseUrl: config.tasksBaseUrl, key: config.key, logger });
@@ -2529,6 +2636,7 @@ function ensureRuntime(options) {
     agent: void 0,
     locals: /* @__PURE__ */ new Map(),
     instanceId: resolveInstanceId(options.instanceId),
+    environment,
     pollIntervalMs: void 0,
     booted: false,
     bootScheduled: false,
@@ -2553,7 +2661,7 @@ 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) {
+function resolveTaskOptions(slug, options, mode, logger) {
   const retries = options.retries === void 0 || !Number.isFinite(options.retries) ? DEFAULT_RETRIES2 : Math.max(0, Math.floor(options.retries));
   return {
     retries,
@@ -2562,7 +2670,8 @@ function resolveTaskOptions(options, mode) {
     concurrency: mode === "remote" ? clampConcurrency(options.concurrency) : 1,
     logFlushIntervalMs: options.logFlushIntervalMs,
     cancelCheckIntervalMs: options.cancelCheckIntervalMs,
-    cancelGraceMs: options.cancelGraceMs ?? DEFAULT_CANCEL_GRACE_MS
+    cancelGraceMs: options.cancelGraceMs ?? DEFAULT_CANCEL_GRACE_MS,
+    itemColumns: normalizeItemColumns(slug, options.items, logger)
   };
 }
 function instanceInfo(rt) {
@@ -2571,9 +2680,11 @@ function instanceInfo(rt) {
     version: SDK_VERSION,
     host: hostname(),
     // ambiente da instância: junto do heartbeat, é como o servidor sabe onde o robô roda
-    environment: rt.options.environment,
+    environment: rt.environment,
     // TODAS as tasks (register + start) — o painel mostra o que o agente sabe fazer
     tasks: rt.registry.allSlugs(),
+    // colunas da aba "itens" declaradas no código — a plataforma usa enquanto o usuário não personalizar
+    task_items: rt.registry.itemDeclarations(),
     // o servidor calcula a tolerância de offline (3×) a partir disto em agentes que fazem
     // poll; clampado à faixa aceita pelo schema (1s..15min)
     poll_interval_ms: rt.agent ? Math.min(Math.max(rt.agent.pollIntervalMs, 1e3), 9e5) : void 0,
@@ -2642,7 +2753,7 @@ function addTask(fn, mode, task, handler, options) {
       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) };
+  const registered = { slug, mode, handler, options: resolveTaskOptions(slug, options, mode, rt.logger) };
   rt.registry.add(registered);
   if (!rt.booted) {
     scheduleBoot(rt);
@@ -2731,11 +2842,11 @@ function warnOutsideRun(member) {
 }
 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)
+  debug: (message, ...rest) => printRunLog(FALLBACK_TASK, "debug", joinLogArgs(message, rest)),
+  info: (message, ...rest) => printRunLog(FALLBACK_TASK, "info", joinLogArgs(message, rest)),
+  warn: (message, ...rest) => printRunLog(FALLBACK_TASK, "warning", joinLogArgs(message, rest)),
+  error: (message, ...rest) => printRunLog(FALLBACK_TASK, "error", joinLogArgs(message, rest)),
+  success: (message, ...rest) => printRunLog(FALLBACK_TASK, "success", joinLogArgs(message, rest))
 };
 var noop = () => void 0;
 var fallbackItems = { add: noop, succeeded: noop, failed: noop, occurrence: noop };