hobots 1.9.2 → 2.0.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { Breadcrumb, EventUser, Severity, EventPayload, TransactionPayload, HeartbeatPayload, StepStatus, RunLogLevel, StepData, RunAttachmentContentType } from './protocol.cjs';
-export { AgentInfo, Envelope, EnvelopeItem, ExceptionData, PollRequest, PollResponse, RunAttachmentConfirmRequest, RunAttachmentConfirmResponse, RunAttachmentCreateRequest, RunAttachmentCreateResponse, RunDescriptor, RunError, RunLogEntry, RunStatus, RunUpdateRequest, RunUpdateResponse, RunUpdateStatus, StackFrame } from './protocol.cjs';
+import { Breadcrumb, EventUser, Severity, EventPayload, TransactionPayload, HeartbeatPayload, StepStatus, RunLogLevel, StepData, RunItemStatus, RunAttachmentContentType } from './protocol.cjs';
+export { Envelope, EnvelopeItem, ExceptionData, InstanceInfo, PollRequest, PollResponse, RunAttachmentConfirmRequest, RunAttachmentConfirmResponse, RunAttachmentCreateRequest, RunAttachmentCreateResponse, RunDescriptor, RunError, RunItemInput, RunItemsCreateRequest, RunItemsCreateResponse, RunLogEntry, RunStatus, RunUpdateRequest, RunUpdateResponse, RunUpdateStatus, StackFrame } from './protocol.cjs';
 
 /** Aceita tudo que o handler pode ter em mãos: bytes ou um caminho de arquivo (só Node). */
 type AttachInput = Uint8Array | ArrayBuffer | string;
@@ -50,6 +50,8 @@ interface Logger {
 declare class Client {
     #private;
     readonly logger: Logger;
+    /** Eco de lifecycle (Transaction.emit) e afins só imprimem no terminal com debug ligado. */
+    readonly debug: boolean;
     private readonly transport;
     constructor(options: InitOptions, config?: ResolvedConfig);
     get options(): InitOptions;
@@ -110,9 +112,10 @@ declare class Transaction {
     /** Correlaciona a uma execução de task — preenchido automaticamente em ctx.tx */
     runId?: string | undefined);
     /**
-     * Ecoa no terminal o início/fim de uma step ou transaction (sempre, independente de
-     * sampling ou do debug) e espelha a linha no sink de lifecycle, se conectado — é
-     * assim que os eventos de performance também aparecem nos logs da run no app.
+     * 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: 'transaction' | 'step', phase: 'start' | 'finish', label: string, startTs?: string, endTs?: string, status?: StepStatus | string): void;
     /** Conecta o espelho de lifecycle (RunReporter) e faz replay do backlog em ordem. */
@@ -167,11 +170,41 @@ interface RunLogger {
     error(message: string): void;
     success(message: string): void;
 }
+interface RunItemOptions {
+    /**
+     * Identidade de negócio do item na run (ex.: nº da nota fiscal). Repetido na
+     * mesma run = ignorado pelo servidor (registro único, retry idempotente).
+     * Omitido: o SDK gera um id único e cada chamada vira um item novo.
+     */
+    id?: string;
+}
+/**
+ * Registro dos itens que a execução processou/gerou (a entrega do bot: notas
+ * fiscais baixadas, boletos emitidos...). Chamadas são síncronas — os itens são
+ * bufferizados e enviados em lotes; o agente drena o buffer antes do reporte final.
+ */
+interface RunItems {
+    /** Forma genérica — os atalhos succeeded/failed/occurrence cobrem o dia a dia. */
+    add(item: {
+        status: RunItemStatus;
+        id?: string;
+        message?: string;
+        payload?: Record<string, unknown>;
+    }): void;
+    /** Item processado com sucesso. `payload` = atributos do item (viram colunas na plataforma). */
+    succeeded(payload?: Record<string, unknown>, options?: RunItemOptions): void;
+    /** Falha técnica ao processar o item — `message` é o motivo exibido na plataforma. */
+    failed(message: string, payload?: Record<string, unknown>, options?: RunItemOptions): void;
+    /** Ocorrência de negócio (ex.: "nota nº 10 não encontrada") — não é falha do bot. */
+    occurrence(message: string, payload?: Record<string, unknown>, options?: RunItemOptions): void;
+}
 interface RunContext {
     runId: string;
     task: string;
     /** Log bufferizado — enviado ao servidor em PATCHes incrementais com throttle */
     log: RunLogger;
+    /** Itens processados/gerados pela execução — a entrega do bot, com status e atributos */
+    items: RunItems;
     /**
      * Transaction de performance desta execução — já correlacionada à run e finalizada
      * automaticamente ao fim do handler. Use `ctx.tx.startChild(op, description)` pra medir
@@ -303,4 +336,4 @@ declare function close(timeoutMs?: number): Promise<boolean>;
 
 declare function scrubSecrets(text: string): string;
 
-export { type AttachInput, Breadcrumb, type BreadcrumbInput, type CaptureAttachment, type CaptureHint, Client, DEFAULT_BASE_URL, EventPayload, EventUser, type HeartbeatOptions, HeartbeatPayload, type InitOptions, RunAttachmentContentType, type RunContext, RunLogLevel, Scope, Severity, Step, StepData, type TaskHandler, type TasksOptions, Transaction, TransactionPayload, addBreadcrumb, captureException, captureMessage, close, flush, getClient, init, register, scrubSecrets, setContext, setExtra, setTag, setTags, setUser, start, startTransaction, stop, withScope };
+export { type AttachInput, Breadcrumb, type BreadcrumbInput, type CaptureAttachment, type CaptureHint, Client, DEFAULT_BASE_URL, EventPayload, EventUser, type HeartbeatOptions, HeartbeatPayload, type InitOptions, RunAttachmentContentType, type RunContext, type RunItemOptions, RunItemStatus, type RunItems, RunLogLevel, Scope, Severity, Step, StepData, type TaskHandler, type TasksOptions, Transaction, TransactionPayload, addBreadcrumb, captureException, captureMessage, close, flush, getClient, init, register, scrubSecrets, setContext, setExtra, setTag, setTags, setUser, start, startTransaction, stop, withScope };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { Breadcrumb, EventUser, Severity, EventPayload, TransactionPayload, HeartbeatPayload, StepStatus, RunLogLevel, StepData, RunAttachmentContentType } from './protocol.js';
-export { AgentInfo, Envelope, EnvelopeItem, ExceptionData, PollRequest, PollResponse, RunAttachmentConfirmRequest, RunAttachmentConfirmResponse, RunAttachmentCreateRequest, RunAttachmentCreateResponse, RunDescriptor, RunError, RunLogEntry, RunStatus, RunUpdateRequest, RunUpdateResponse, RunUpdateStatus, StackFrame } from './protocol.js';
+import { Breadcrumb, EventUser, Severity, EventPayload, TransactionPayload, HeartbeatPayload, StepStatus, RunLogLevel, StepData, RunItemStatus, RunAttachmentContentType } from './protocol.js';
+export { Envelope, EnvelopeItem, ExceptionData, InstanceInfo, PollRequest, PollResponse, RunAttachmentConfirmRequest, RunAttachmentConfirmResponse, RunAttachmentCreateRequest, RunAttachmentCreateResponse, RunDescriptor, RunError, RunItemInput, RunItemsCreateRequest, RunItemsCreateResponse, RunLogEntry, RunStatus, RunUpdateRequest, RunUpdateResponse, RunUpdateStatus, StackFrame } from './protocol.js';
 
 /** Aceita tudo que o handler pode ter em mãos: bytes ou um caminho de arquivo (só Node). */
 type AttachInput = Uint8Array | ArrayBuffer | string;
@@ -50,6 +50,8 @@ interface Logger {
 declare class Client {
     #private;
     readonly logger: Logger;
+    /** Eco de lifecycle (Transaction.emit) e afins só imprimem no terminal com debug ligado. */
+    readonly debug: boolean;
     private readonly transport;
     constructor(options: InitOptions, config?: ResolvedConfig);
     get options(): InitOptions;
@@ -110,9 +112,10 @@ declare class Transaction {
     /** Correlaciona a uma execução de task — preenchido automaticamente em ctx.tx */
     runId?: string | undefined);
     /**
-     * Ecoa no terminal o início/fim de uma step ou transaction (sempre, independente de
-     * sampling ou do debug) e espelha a linha no sink de lifecycle, se conectado — é
-     * assim que os eventos de performance também aparecem nos logs da run no app.
+     * 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: 'transaction' | 'step', phase: 'start' | 'finish', label: string, startTs?: string, endTs?: string, status?: StepStatus | string): void;
     /** Conecta o espelho de lifecycle (RunReporter) e faz replay do backlog em ordem. */
@@ -167,11 +170,41 @@ interface RunLogger {
     error(message: string): void;
     success(message: string): void;
 }
+interface RunItemOptions {
+    /**
+     * Identidade de negócio do item na run (ex.: nº da nota fiscal). Repetido na
+     * mesma run = ignorado pelo servidor (registro único, retry idempotente).
+     * Omitido: o SDK gera um id único e cada chamada vira um item novo.
+     */
+    id?: string;
+}
+/**
+ * Registro dos itens que a execução processou/gerou (a entrega do bot: notas
+ * fiscais baixadas, boletos emitidos...). Chamadas são síncronas — os itens são
+ * bufferizados e enviados em lotes; o agente drena o buffer antes do reporte final.
+ */
+interface RunItems {
+    /** Forma genérica — os atalhos succeeded/failed/occurrence cobrem o dia a dia. */
+    add(item: {
+        status: RunItemStatus;
+        id?: string;
+        message?: string;
+        payload?: Record<string, unknown>;
+    }): void;
+    /** Item processado com sucesso. `payload` = atributos do item (viram colunas na plataforma). */
+    succeeded(payload?: Record<string, unknown>, options?: RunItemOptions): void;
+    /** Falha técnica ao processar o item — `message` é o motivo exibido na plataforma. */
+    failed(message: string, payload?: Record<string, unknown>, options?: RunItemOptions): void;
+    /** Ocorrência de negócio (ex.: "nota nº 10 não encontrada") — não é falha do bot. */
+    occurrence(message: string, payload?: Record<string, unknown>, options?: RunItemOptions): void;
+}
 interface RunContext {
     runId: string;
     task: string;
     /** Log bufferizado — enviado ao servidor em PATCHes incrementais com throttle */
     log: RunLogger;
+    /** Itens processados/gerados pela execução — a entrega do bot, com status e atributos */
+    items: RunItems;
     /**
      * Transaction de performance desta execução — já correlacionada à run e finalizada
      * automaticamente ao fim do handler. Use `ctx.tx.startChild(op, description)` pra medir
@@ -303,4 +336,4 @@ declare function close(timeoutMs?: number): Promise<boolean>;
 
 declare function scrubSecrets(text: string): string;
 
-export { type AttachInput, Breadcrumb, type BreadcrumbInput, type CaptureAttachment, type CaptureHint, Client, DEFAULT_BASE_URL, EventPayload, EventUser, type HeartbeatOptions, HeartbeatPayload, type InitOptions, RunAttachmentContentType, type RunContext, RunLogLevel, Scope, Severity, Step, StepData, type TaskHandler, type TasksOptions, Transaction, TransactionPayload, addBreadcrumb, captureException, captureMessage, close, flush, getClient, init, register, scrubSecrets, setContext, setExtra, setTag, setTags, setUser, start, startTransaction, stop, withScope };
+export { type AttachInput, Breadcrumb, type BreadcrumbInput, type CaptureAttachment, type CaptureHint, Client, DEFAULT_BASE_URL, EventPayload, EventUser, type HeartbeatOptions, HeartbeatPayload, type InitOptions, RunAttachmentContentType, type RunContext, type RunItemOptions, RunItemStatus, type RunItems, RunLogLevel, Scope, Severity, Step, StepData, type TaskHandler, type TasksOptions, Transaction, TransactionPayload, addBreadcrumb, captureException, captureMessage, close, flush, getClient, init, register, scrubSecrets, setContext, setExtra, setTag, setTags, setUser, start, startTransaction, stop, withScope };

package/dist/index.js

@@ -103,7 +103,7 @@ function scrubSecrets(text) {
 
 // src/utils.ts
 var SDK_NAME = "hobots";
-var SDK_VERSION = true ? "1.9.1" : "0.0.0-dev";
+var SDK_VERSION = true ? "2.0.0" : "0.0.0-dev";
 function isNode() {
   return typeof process !== "undefined" && typeof process.versions?.node === "string";
 }
@@ -296,7 +296,8 @@ var Transport = class {
       return;
     }
     if (this.buffer.length >= this.maxQueueSize) {
-      this.buffer.shift();
+      const dropIndex = this.buffer.findIndex((queued) => queued.type !== "heartbeat");
+      this.buffer.splice(dropIndex === -1 ? 0 : dropIndex, 1);
       this.logger.warn("fila cheia, item mais antigo descartado");
     }
     this.buffer.push(item);
@@ -387,6 +388,8 @@ function runtimeContexts() {
 }
 var Client = class {
   logger;
+  /** Eco de lifecycle (Transaction.emit) e afins só imprimem no terminal com debug ligado. */
+  debug;
   // 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
@@ -395,7 +398,8 @@ var Client = class {
   transport;
   constructor(options, config = resolveConfig(options)) {
     this.#options = options;
-    this.logger = makeLogger(!!options.debug);
+    this.debug = !!options.debug;
+    this.logger = makeLogger(this.debug);
     this.#config = config;
     this.transport = new Transport({
       endpoint: this.#config.ingestEndpoint,
@@ -482,6 +486,8 @@ var Client = class {
 
 // 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) {
     this.client = client2;
@@ -498,12 +504,22 @@ var Heartbeat = class {
   start() {
     if (this.timer) return;
     this.beat();
-    this.timer = setInterval(() => this.beat(), this.intervalMs);
+    this.schedule();
+  }
+  /** Jitter de ±10%: uma frota iniciada junto não sincroniza todos os beats no mesmo segundo. */
+  schedule() {
+    this.timer = setTimeout(
+      () => {
+        this.beat();
+        this.schedule();
+      },
+      this.intervalMs * (0.9 + Math.random() * 0.2)
+    );
     unrefTimer(this.timer);
   }
   stop() {
     if (this.timer) {
-      clearInterval(this.timer);
+      clearTimeout(this.timer);
       this.timer = void 0;
     }
   }
@@ -511,7 +527,7 @@ var Heartbeat = class {
     this.client.sendHeartbeat({
       instance_id: this.instanceId,
       name: this.name,
-      interval_ms: this.intervalMs,
+      interval_ms: Math.min(Math.max(this.intervalMs, MIN_REPORTED_INTERVAL_MS), MAX_REPORTED_INTERVAL_MS),
       timestamp: nowISO(),
       metadata: this.metadata
     });
@@ -758,15 +774,18 @@ var Transaction = class {
   // antes do RunReporter conectar) — replay no setLifecycleSink
   lifecycleBacklog = [];
   /**
-   * Ecoa no terminal o início/fim de uma step ou transaction (sempre, independente de
-   * sampling ou do debug) e espelha a linha no sink de lifecycle, se conectado — é
-   * assim que os eventos de performance também aparecem nos logs da run no app.
+   * 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 tag = colorize(`[hobots:${kind}] ${phase.toUpperCase()}`, phase === "finish" ? colorForStatus(status ?? "ok") : "cyan");
     const suffix = durationMs != null ? ` (${durationMs}ms)` : "";
-    console.log(`${tag} ${label}${suffix}`);
+    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);
@@ -929,6 +948,38 @@ var TasksApi = class {
       signal: AbortSignal.timeout(timeoutMs)
     });
   }
+  /**
+   * Envia um lote de itens de execução. Retry em falha de rede/5xx/429-transporte;
+   * 4xx é definitivo (404 = servidor sem o recurso, 429 = cap de itens por run) —
+   * o RunReporter trata por status.
+   */
+  async createItems(runId, request) {
+    let response;
+    try {
+      response = await fetchWithRetry(
+        () => fetch(`${this.baseUrl}/runs/${encodeURIComponent(runId)}/items`, {
+          method: "POST",
+          headers: this.headers(),
+          body: JSON.stringify(request),
+          signal: AbortSignal.timeout(UPDATE_TIMEOUT_MS)
+        }),
+        { logger: this.logger, label: `itens da run ${runId}` }
+      );
+    } 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) {
+      throw new TasksApiError(`envio de itens rejeitado (HTTP ${response.status})`, response.status);
+    }
+    const body = await response.json().catch(() => null);
+    return {
+      accepted: typeof body?.accepted === "number" ? body.accepted : request.items.length,
+      duplicates: typeof body?.duplicates === "number" ? body.duplicates : 0
+    };
+  }
   /**
    * Registra o anexo e obtém a URL presignada de upload. 404/501/503 significam
    * "esta instalação não tem anexos" — o RunReporter degrada em silêncio a partir daí.
@@ -1086,6 +1137,22 @@ var MAX_CANCEL_CHECK_INTERVAL_MS = 15e3;
 var MAX_LOG_MESSAGE_CHARS = 1e4;
 var MAX_LOGS_PER_PATCH = 100;
 var FLUSH_AT_BUFFERED = 20;
+var MAX_ITEMS_PER_RUN = 1e4;
+var MAX_ITEMS_PER_REQUEST = 500;
+var MAX_ITEM_MESSAGE_CHARS = 2e3;
+var MAX_ITEM_PAYLOAD_BYTES = 16384;
+var ITEMS_FLUSH_AT_BUFFERED = 100;
+var ITEMS_DRAIN_MS = 15e3;
+function scrubPayloadValue(value, depth) {
+  if (typeof value === "string") return scrubSecrets(value);
+  if (depth >= 4 || value === null || typeof value !== "object") return value;
+  if (Array.isArray(value)) return value.map((entry) => scrubPayloadValue(entry, depth + 1));
+  const out = {};
+  for (const [key, entry] of Object.entries(value)) {
+    out[key] = scrubPayloadValue(entry, depth + 1);
+  }
+  return out;
+}
 var RunReporter = class {
   constructor(api, runId, task, logger, tx, flushIntervalMs, cancelCheckIntervalMs) {
     this.api = api;
@@ -1104,11 +1171,18 @@ var RunReporter = class {
       success: (message) => this.log("success", message)
     };
     tx.setLifecycleSink((level, message) => this.push(level, message));
+    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)
+    };
     const signal = this.abortController.signal;
     this.context = {
       runId,
       task,
       log,
+      items,
       tx,
       signal,
       throwIfCanceled: () => {
@@ -1127,6 +1201,23 @@ var RunReporter = class {
   abortController = new AbortController();
   flushIntervalMs;
   cancelCheckIntervalMs;
+  // Itens de execução vivem FORA de `this.chain` (status/liveness não pode ficar
+  // atrás de milhares de itens), mas têm cadeia própria serializada — ordem de
+  // envio preservada e sem lotes sobrepostos.
+  itemsBuffer = [];
+  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ó. */
+  itemsQuotaExceeded = false;
+  /**
+   * Só o kill() do exit path fecha os itens — `dead` (run cancelada/finalizada no
+   * servidor) NÃO fecha: o servidor aceita itens de run terminal (trabalho já feito).
+   */
+  itemsClosed = false;
   // Uploads de anexo vivem FORA de `this.chain`: a cadeia é um FIFO puro de
   // status/logs e não pode ficar bloqueada esperando um binário subir.
   pendingAttachments = /* @__PURE__ */ new Set();
@@ -1153,6 +1244,12 @@ var RunReporter = class {
     this.dead = true;
     this.clearFlushTimer();
     this.buffer = [];
+    this.itemsClosed = true;
+    this.clearItemsTimer();
+    if (this.itemsBuffer.length > 0) {
+      this.logger.warn(`${this.itemsBuffer.length} item(ns) de execu\xE7\xE3o descartados (processo encerrando)`);
+      this.itemsBuffer = [];
+    }
     const waiting = this.uploadQueue.splice(0, this.uploadQueue.length);
     for (const resume of waiting) resume();
   }
@@ -1255,6 +1352,120 @@ var RunReporter = class {
   finalize() {
     return this.chain;
   }
+  // ── Itens de execução ────────────────────────────────────────────────────────
+  /**
+   * Bufferiza um item (síncrono — a chamada nunca espera rede). Diferente do PATCH
+   * de status, o servidor aceita itens mesmo com a run cancelada (trabalho já feito),
+   * então um reporter morto não descarta: só um kill() de exit path descarta.
+   */
+  addItem(status, message, payload, id) {
+    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);
+      let serializedLength;
+      try {
+        serializedLength = JSON.stringify(scrubbedPayload).length;
+      } catch {
+      }
+      if (serializedLength === void 0 || serializedLength > MAX_ITEM_PAYLOAD_BYTES) {
+        this.logger.warn(
+          `payload do item descartado (${serializedLength === void 0 ? "n\xE3o serializ\xE1vel" : `${serializedLength} bytes > ${MAX_ITEM_PAYLOAD_BYTES}`}) \u2014 o item foi mantido`
+        );
+        scrubbedPayload = void 0;
+      }
+    }
+    this.itemsBuffer.push({
+      id: id ? truncate(String(id), 255) : uuid4(),
+      seq: this.itemSeq++,
+      status,
+      ...message ? { message: truncate(scrubSecrets(message), MAX_ITEM_MESSAGE_CHARS) } : {},
+      ...scrubbedPayload ? { payload: scrubbedPayload } : {},
+      ts: nowISO()
+    });
+    if (this.itemsBuffer.length >= ITEMS_FLUSH_AT_BUFFERED) {
+      this.flushItems();
+    } else {
+      this.scheduleItemsFlush();
+    }
+  }
+  scheduleItemsFlush() {
+    if (this.itemsTimer) return;
+    this.itemsTimer = setTimeout(() => {
+      this.itemsTimer = void 0;
+      this.flushItems();
+    }, this.flushIntervalMs);
+    unrefTimer(this.itemsTimer);
+  }
+  clearItemsTimer() {
+    if (this.itemsTimer) {
+      clearTimeout(this.itemsTimer);
+      this.itemsTimer = void 0;
+    }
+  }
+  /** Envia o buffer de itens em lotes serializados na cadeia própria. */
+  flushItems() {
+    this.clearItemsTimer();
+    if (this.itemsBuffer.length === 0 || this.itemsUnsupported) return;
+    const items = this.itemsBuffer.splice(0, this.itemsBuffer.length);
+    for (let i = 0; i < items.length; i += MAX_ITEMS_PER_REQUEST) {
+      const batch = items.slice(i, i + MAX_ITEMS_PER_REQUEST);
+      this.itemsChain = this.itemsChain.then(() => this.sendItems(batch));
+    }
+  }
+  async sendItems(batch) {
+    if (this.itemsUnsupported) return;
+    try {
+      await this.api.createItems(this.runId, { items: batch });
+    } catch (error) {
+      if (error instanceof TasksApiError && error.status === 404) {
+        this.itemsUnsupported = true;
+        this.logger.warn("itens de execu\xE7\xE3o n\xE3o s\xE3o suportados por este servidor Hobots \u2014 descartados");
+        return;
+      }
+      if (error instanceof TasksApiError && error.status === 429) {
+        if (!this.itemsQuotaExceeded) {
+          this.itemsQuotaExceeded = true;
+          this.log("warning", "itens descartados: limite de itens por execu\xE7\xE3o atingido no servidor");
+        }
+        return;
+      }
+      if (error instanceof TasksApiError) {
+        this.logger.error(`lote de ${batch.length} item(ns) rejeitado pelo servidor:`, error);
+        return;
+      }
+      this.itemsBuffer.unshift(...batch);
+      this.scheduleItemsFlush();
+      this.logger.error(`lote de ${batch.length} item(ns) n\xE3o enviado (devolvido ao buffer):`, error);
+    }
+  }
+  /**
+   * Dreno final de itens antes do PATCH terminal (com teto): garante que os
+   * totalizadores estejam completos quando a run vira succeeded/failed. Como o
+   * servidor aceita itens tardios, perder a corrida aqui não perde dados.
+   */
+  async finalizeItems(timeoutMs = ITEMS_DRAIN_MS) {
+    this.flushItems();
+    await Promise.race([
+      this.itemsChain,
+      new Promise((resolve) => unrefTimer(setTimeout(resolve, timeoutMs)))
+    ]);
+    if (this.itemsBuffer.length > 0 && !this.itemsUnsupported && !this.itemsQuotaExceeded) {
+      this.flushItems();
+      await Promise.race([
+        this.itemsChain,
+        new Promise((resolve) => unrefTimer(setTimeout(resolve, timeoutMs)))
+      ]);
+    }
+  }
   // ── Anexos ───────────────────────────────────────────────────────────────────
   /**
    * Registra a linha de log com o id do anexo (síncrono, na ordem certa) e dispara
@@ -1621,13 +1832,17 @@ var TaskAgent = class {
     try {
       const response = await this.api.poll(
         {
-          agent: {
+          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(),
-            tasks: [...this.registry.keys()]
+            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)
           },
           max: Math.min(MAX_CONCURRENCY, this.concurrency - this.activeRuns.size),
           tasks: [...this.registry.keys()]
@@ -1699,12 +1914,14 @@ var TaskAgent = class {
           () => 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`);
       } catch (error) {
         await reporter.finalizeAttachments();
+        await reporter.finalizeItems();
         tx.setStatus("error");
         tx.finish();
         reporter.reportFailure(toRunError(error));