hobots 3.2.1 → 3.3.0

package/dist/protocol.cjs

@@ -3,6 +3,10 @@ var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
 var __copyProps = (to, from, except, desc) => {
   if (from && typeof from === "object" || typeof from === "function") {
     for (let key of __getOwnPropNames(from))
@@ -15,5 +19,35 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 
 // src/protocol.ts
 var protocol_exports = {};
+__export(protocol_exports, {
+  WIRE_LIMITS: () => WIRE_LIMITS
+});
 module.exports = __toCommonJS(protocol_exports);
+
+// protocol-limits.json
+var protocol_limits_default = {
+  MAX_ITEMS_PER_ENVELOPE: 50,
+  HEARTBEAT_DEFAULT_INTERVAL_MS: 3e4,
+  HEARTBEAT_MIN_INTERVAL_MS: 1e3,
+  HEARTBEAT_MAX_INTERVAL_MS: 9e5,
+  MAX_CLAIM_PER_POLL: 5,
+  MAX_LOG_MESSAGE_CHARS: 1e4,
+  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,
+  MAX_ITEM_COLUMNS: 12,
+  MAX_ITEM_COLUMN_LABEL_CHARS: 60,
+  MAX_ATTACHMENT_BYTES: 5242880,
+  MAX_ATTACHMENTS_PER_RUN: 20,
+  MAX_ATTACHMENTS_PER_LOG_ENTRY: 4,
+  MAX_CAPTION_CHARS: 200,
+  MAX_IMAGE_DIMENSION_PX: 2e4
+};
+
+// src/wire-limits.ts
+var WIRE_LIMITS = protocol_limits_default;
 //# sourceMappingURL=protocol.cjs.map

package/dist/protocol.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/protocol.ts"],"sourcesContent":["/**\n * Tipos do protocolo do Hobots (SDK → servidor).\n *\n * Este arquivo é a fonte de verdade do wire format e só pode reexportar tipos:\n * o app valida os payloads com zod e trava o drift via `satisfies z.ZodType<...>`\n * contra estes tipos (importados de `hobots/protocol`).\n */\n\nimport type { EnvironmentInput } from './environment-protocol';\nimport type { MachineSnapshot } from './machine-protocol';\n\n// Wire format de tasks (agente ↔ servidor) — reexportado aqui para o app\n// consumir tudo de `hobots/protocol`.\nexport type {\n  RunStatus,\n  RunUpdateStatus,\n  RunLogLevel,\n  RunLogEntry,\n  InstanceInfo,\n  PollRequest,\n  RunDescriptor,\n  PollResponse,\n  RunCreateRequest,\n  RunCreateResponse,\n  RunError,\n  RunProgress,\n  RunUpdateRequest,\n  RunUpdateResponse,\n  RunItemStatus,\n  RunItemInput,\n  RunItemsCreateRequest,\n  RunItemsCreateResponse,\n  ItemColumn,\n  TaskItemsDeclaration,\n  RunAttachmentContentType,\n  RunAttachmentCreateRequest,\n  RunAttachmentCreateResponse,\n  RunAttachmentConfirmRequest,\n  RunAttachmentConfirmResponse,\n} from './tasks/protocol';\n\n// Snapshot de recursos da máquina — usado no heartbeat, no poll e em contexts.machine.\nexport type { MachineProcess, MachineSnapshot } from './machine-protocol';\nexport type { Environment, EnvironmentInput } from './environment-protocol';\n\n/**\n * Tipo de um evento — o que ele é, não o quanto ele fala. Só 'fatal', 'error' e\n * 'warning' viram issue; 'success' é ingerido e nunca abre issue.\n * Ruído de log não é evento: para isso existem os logs da execução (RunLogLevel)\n * e as breadcrumbs, que têm níveis próprios com 'debug'/'info'.\n */\nexport type EventType = 'fatal' | 'error' | 'warning' | 'success';\n\n/** Nível de uma breadcrumb — trilha do que aconteceu antes, aqui log é bem-vindo. */\nexport type BreadcrumbLevel = 'debug' | 'info' | 'warning' | 'error' | 'fatal';\n\n/** Frames em ordem innermost-first (mesma ordem impressa pelo V8). */\nexport interface StackFrame {\n  function?: string;\n  filename?: string;\n  lineno?: number;\n  colno?: number;\n  in_app: boolean;\n}\n\nexport interface Breadcrumb {\n  /** ISO 8601 */\n  timestamp: string;\n  type?: string;\n  category?: string;\n  message?: string;\n  level?: BreadcrumbLevel;\n  data?: Record<string, unknown>;\n}\n\nexport interface ExceptionData {\n  type: string;\n  value: string;\n  stacktrace?: { frames: StackFrame[] };\n}\n\nexport interface EventUser {\n  id?: string;\n  username?: string;\n  email?: string;\n}\n\nexport interface EventPayload {\n  /** uuid v4 sem hífens (32 hex), gerado pelo SDK */\n  event_id: string;\n  /** ISO 8601 */\n  timestamp: string;\n  type: EventType;\n  message?: string;\n  exception?: ExceptionData;\n  /** Override de agrupamento; quando ausente o servidor calcula pelo stack trace */\n  fingerprint?: string[];\n  breadcrumbs?: Breadcrumb[];\n  tags?: Record<string, string>;\n  user?: EventUser;\n  contexts?: Record<string, Record<string, unknown>>;\n  extra?: Record<string, unknown>;\n  release?: string;\n  environment?: EnvironmentInput;\n}\n\n/** Status de uma step (etapa). `warning` = terminou, mas merece atenção (não é falha). */\nexport type StepStatus = 'ok' | 'warning' | 'error' | 'cancelled';\n\nexport interface StepData {\n  /** 16 hex */\n  step_id: string;\n  parent_step_id?: string;\n  op?: string;\n  description?: string;\n  status?: StepStatus;\n  /** ISO 8601 */\n  start_timestamp: string;\n  /** ISO 8601 (fim da step) */\n  timestamp: string;\n  data?: Record<string, unknown>;\n}\n\nexport interface TransactionPayload {\n  event_id: string;\n  name: string;\n  op?: string;\n  status: string;\n  start_timestamp: string;\n  timestamp: string;\n  steps: StepData[];\n  tags?: Record<string, string>;\n  release?: string;\n  environment?: EnvironmentInput;\n  /** Correlaciona esta transaction a uma execução de task (ctx.tx dentro de um task handler) */\n  run_id?: string;\n}\n\nexport interface HeartbeatPayload {\n  instance_id: string;\n  name?: string;\n  interval_ms: number;\n  /** ISO 8601 */\n  timestamp: string;\n  metadata?: Record<string, unknown>;\n  release?: string;\n  /** Ambiente da instância — é ele que o app exibe e que as regras de alerta filtram */\n  environment?: EnvironmentInput;\n  /** Recursos da máquina no momento do beat (CPU, memória, disco, processo) */\n  machine?: MachineSnapshot;\n}\n\nexport type EnvelopeItem =\n  | { type: 'event'; payload: EventPayload }\n  | { type: 'transaction'; payload: TransactionPayload }\n  | { type: 'heartbeat'; payload: HeartbeatPayload };\n\nexport interface Envelope {\n  sdk: { name: string; version: string };\n  /** ISO 8601 */\n  sent_at: string;\n  items: EnvelopeItem[];\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAAA;AAAA;","names":[]}
+{"version":3,"sources":["../src/protocol.ts","../protocol-limits.json","../src/wire-limits.ts"],"sourcesContent":["/**\n * Tipos do protocolo do Hobots (SDK → servidor).\n *\n * Este arquivo é a fonte de verdade do wire format: reexporta tipos (o app valida\n * os payloads com zod e trava o drift via `satisfies z.ZodType<...>` contra eles)\n * e os LIMITES numéricos do wire (WIRE_LIMITS, de protocol-limits.json) — o único\n * valor de runtime daqui, para a api aplicar exatamente os caps que o SDK aplica.\n */\n\nexport { WIRE_LIMITS, type WireLimits } from './wire-limits';\n\nimport type { EnvironmentInput } from './environment-protocol';\nimport type { MachineSnapshot } from './machine-protocol';\n\n// Wire format de tasks (agente ↔ servidor) — reexportado aqui para o app\n// consumir tudo de `hobots/protocol`.\nexport type {\n  RunStatus,\n  RunUpdateStatus,\n  RunLogLevel,\n  RunLogEntry,\n  InstanceInfo,\n  PollRequest,\n  RunDescriptor,\n  PollResponse,\n  RunCreateRequest,\n  RunCreateResponse,\n  RunError,\n  RunProgress,\n  RunUpdateRequest,\n  RunUpdateResponse,\n  RunItemStatus,\n  RunItemInput,\n  RunItemsCreateRequest,\n  RunItemsCreateResponse,\n  ItemColumn,\n  TaskItemsDeclaration,\n  RunAttachmentContentType,\n  RunAttachmentCreateRequest,\n  RunAttachmentCreateResponse,\n  RunAttachmentConfirmRequest,\n  RunAttachmentConfirmResponse,\n} from './tasks/protocol';\n\n// Snapshot de recursos da máquina — usado no heartbeat, no poll e em contexts.machine.\nexport type { MachineProcess, MachineSnapshot } from './machine-protocol';\nexport type { Environment, EnvironmentInput } from './environment-protocol';\n\n/**\n * Tipo de um evento — o que ele é, não o quanto ele fala. Só 'fatal', 'error' e\n * 'warning' viram issue; 'success' é ingerido e nunca abre issue.\n * Ruído de log não é evento: para isso existem os logs da execução (RunLogLevel)\n * e as breadcrumbs, que têm níveis próprios com 'debug'/'info'.\n */\nexport type EventType = 'fatal' | 'error' | 'warning' | 'success';\n\n/** Nível de uma breadcrumb — trilha do que aconteceu antes, aqui log é bem-vindo. */\nexport type BreadcrumbLevel = 'debug' | 'info' | 'warning' | 'error' | 'fatal';\n\n/** Frames em ordem innermost-first (mesma ordem impressa pelo V8). */\nexport interface StackFrame {\n  function?: string;\n  filename?: string;\n  lineno?: number;\n  colno?: number;\n  in_app: boolean;\n}\n\nexport interface Breadcrumb {\n  /** ISO 8601 */\n  timestamp: string;\n  type?: string;\n  category?: string;\n  message?: string;\n  level?: BreadcrumbLevel;\n  data?: Record<string, unknown>;\n}\n\nexport interface ExceptionData {\n  type: string;\n  value: string;\n  stacktrace?: { frames: StackFrame[] };\n}\n\nexport interface EventUser {\n  id?: string;\n  username?: string;\n  email?: string;\n}\n\nexport interface EventPayload {\n  /** uuid v4 sem hífens (32 hex), gerado pelo SDK */\n  event_id: string;\n  /** ISO 8601 */\n  timestamp: string;\n  type: EventType;\n  message?: string;\n  exception?: ExceptionData;\n  /** Override de agrupamento; quando ausente o servidor calcula pelo stack trace */\n  fingerprint?: string[];\n  breadcrumbs?: Breadcrumb[];\n  tags?: Record<string, string>;\n  user?: EventUser;\n  contexts?: Record<string, Record<string, unknown>>;\n  extra?: Record<string, unknown>;\n  release?: string;\n  environment?: EnvironmentInput;\n}\n\n/** Status de uma step (etapa). `warning` = terminou, mas merece atenção (não é falha). */\nexport type StepStatus = 'ok' | 'warning' | 'error' | 'cancelled';\n\nexport interface StepData {\n  /** 16 hex */\n  step_id: string;\n  parent_step_id?: string;\n  op?: string;\n  description?: string;\n  status?: StepStatus;\n  /** ISO 8601 */\n  start_timestamp: string;\n  /** ISO 8601 (fim da step) */\n  timestamp: string;\n  data?: Record<string, unknown>;\n}\n\nexport interface TransactionPayload {\n  event_id: string;\n  name: string;\n  op?: string;\n  status: string;\n  start_timestamp: string;\n  timestamp: string;\n  steps: StepData[];\n  tags?: Record<string, string>;\n  release?: string;\n  environment?: EnvironmentInput;\n  /** Correlaciona esta transaction a uma execução de task (ctx.tx dentro de um task handler) */\n  run_id?: string;\n}\n\nexport interface HeartbeatPayload {\n  instance_id: string;\n  name?: string;\n  interval_ms: number;\n  /** ISO 8601 */\n  timestamp: string;\n  metadata?: Record<string, unknown>;\n  release?: string;\n  /** Ambiente da instância — é ele que o app exibe e que as regras de alerta filtram */\n  environment?: EnvironmentInput;\n  /** Recursos da máquina no momento do beat (CPU, memória, disco, processo) */\n  machine?: MachineSnapshot;\n}\n\nexport type EnvelopeItem =\n  | { type: 'event'; payload: EventPayload }\n  | { type: 'transaction'; payload: TransactionPayload }\n  | { type: 'heartbeat'; payload: HeartbeatPayload };\n\nexport interface Envelope {\n  sdk: { name: string; version: string };\n  /** ISO 8601 */\n  sent_at: string;\n  items: EnvelopeItem[];\n}\n","{\n  \"MAX_ITEMS_PER_ENVELOPE\": 50,\n  \"HEARTBEAT_DEFAULT_INTERVAL_MS\": 30000,\n  \"HEARTBEAT_MIN_INTERVAL_MS\": 1000,\n  \"HEARTBEAT_MAX_INTERVAL_MS\": 900000,\n  \"MAX_CLAIM_PER_POLL\": 5,\n  \"MAX_LOG_MESSAGE_CHARS\": 10000,\n  \"MAX_LOGS_PER_PATCH\": 100,\n  \"MAX_ERROR_MESSAGE_CHARS\": 10000,\n  \"MAX_ERROR_STACK_CHARS\": 20000,\n  \"MAX_ITEMS_PER_RUN\": 10000,\n  \"MAX_ITEMS_PER_REQUEST\": 500,\n  \"MAX_ITEM_MESSAGE_CHARS\": 2000,\n  \"MAX_ITEM_PAYLOAD_BYTES\": 16384,\n  \"MAX_ITEM_COLUMNS\": 12,\n  \"MAX_ITEM_COLUMN_LABEL_CHARS\": 60,\n  \"MAX_ATTACHMENT_BYTES\": 5242880,\n  \"MAX_ATTACHMENTS_PER_RUN\": 20,\n  \"MAX_ATTACHMENTS_PER_LOG_ENTRY\": 4,\n  \"MAX_CAPTION_CHARS\": 200,\n  \"MAX_IMAGE_DIMENSION_PX\": 20000\n}\n","import limits from '../protocol-limits.json';\n\n/**\n * Limites do wire SDK ↔ servidor — fonte ÚNICA (protocol-limits.json): o SDK\n * Node lê daqui, a @hobots/api importa de `hobots/protocol` e o SDK Python\n * confere a paridade num teste que lê o mesmo JSON. Mudar um limite = mudar o\n * JSON (e, no Python, a constante espelhada — o teste acusa).\n */\nexport const WIRE_LIMITS = limits as Readonly<typeof limits>;\nexport type WireLimits = typeof WIRE_LIMITS;\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACAA;AAAA,EACE,wBAA0B;AAAA,EAC1B,+BAAiC;AAAA,EACjC,2BAA6B;AAAA,EAC7B,2BAA6B;AAAA,EAC7B,oBAAsB;AAAA,EACtB,uBAAyB;AAAA,EACzB,oBAAsB;AAAA,EACtB,yBAA2B;AAAA,EAC3B,uBAAyB;AAAA,EACzB,mBAAqB;AAAA,EACrB,uBAAyB;AAAA,EACzB,wBAA0B;AAAA,EAC1B,wBAA0B;AAAA,EAC1B,kBAAoB;AAAA,EACpB,6BAA+B;AAAA,EAC/B,sBAAwB;AAAA,EACxB,yBAA2B;AAAA,EAC3B,+BAAiC;AAAA,EACjC,mBAAqB;AAAA,EACrB,wBAA0B;AAC5B;;;ACbO,IAAM,cAAc;","names":[]}

package/dist/protocol.d.cts

@@ -222,9 +222,9 @@ interface RunItemsCreateRequest {
     items: RunItemInput[];
 }
 interface RunItemsCreateResponse {
-    /** Itens inseridos */
+    /** Itens gravados — inseridos ou atualizados (id repetido na run: vale o último reporte) */
     accepted: number;
-    /** Ignorados por id repetido na run (retry de rede é idempotente) */
+    /** Colapsados por id repetido dentro do mesmo lote (vale o de maior seq) */
     duplicates: number;
 }
 /** Formatos aceitos para anexo. O S3 valida o content-type contra a assinatura. */
@@ -262,12 +262,65 @@ interface RunAttachmentConfirmResponse {
     ok: true;
 }
 
+var MAX_ITEMS_PER_ENVELOPE = 50;
+var HEARTBEAT_DEFAULT_INTERVAL_MS = 30000;
+var HEARTBEAT_MIN_INTERVAL_MS = 1000;
+var HEARTBEAT_MAX_INTERVAL_MS = 900000;
+var MAX_CLAIM_PER_POLL = 5;
+var MAX_LOG_MESSAGE_CHARS = 10000;
+var MAX_LOGS_PER_PATCH = 100;
+var MAX_ERROR_MESSAGE_CHARS = 10000;
+var MAX_ERROR_STACK_CHARS = 20000;
+var MAX_ITEMS_PER_RUN = 10000;
+var MAX_ITEMS_PER_REQUEST = 500;
+var MAX_ITEM_MESSAGE_CHARS = 2000;
+var MAX_ITEM_PAYLOAD_BYTES = 16384;
+var MAX_ITEM_COLUMNS = 12;
+var MAX_ITEM_COLUMN_LABEL_CHARS = 60;
+var MAX_ATTACHMENT_BYTES = 5242880;
+var MAX_ATTACHMENTS_PER_RUN = 20;
+var MAX_ATTACHMENTS_PER_LOG_ENTRY = 4;
+var MAX_CAPTION_CHARS = 200;
+var MAX_IMAGE_DIMENSION_PX = 20000;
+var limits = {
+	MAX_ITEMS_PER_ENVELOPE: MAX_ITEMS_PER_ENVELOPE,
+	HEARTBEAT_DEFAULT_INTERVAL_MS: HEARTBEAT_DEFAULT_INTERVAL_MS,
+	HEARTBEAT_MIN_INTERVAL_MS: HEARTBEAT_MIN_INTERVAL_MS,
+	HEARTBEAT_MAX_INTERVAL_MS: HEARTBEAT_MAX_INTERVAL_MS,
+	MAX_CLAIM_PER_POLL: MAX_CLAIM_PER_POLL,
+	MAX_LOG_MESSAGE_CHARS: MAX_LOG_MESSAGE_CHARS,
+	MAX_LOGS_PER_PATCH: MAX_LOGS_PER_PATCH,
+	MAX_ERROR_MESSAGE_CHARS: MAX_ERROR_MESSAGE_CHARS,
+	MAX_ERROR_STACK_CHARS: MAX_ERROR_STACK_CHARS,
+	MAX_ITEMS_PER_RUN: MAX_ITEMS_PER_RUN,
+	MAX_ITEMS_PER_REQUEST: MAX_ITEMS_PER_REQUEST,
+	MAX_ITEM_MESSAGE_CHARS: MAX_ITEM_MESSAGE_CHARS,
+	MAX_ITEM_PAYLOAD_BYTES: MAX_ITEM_PAYLOAD_BYTES,
+	MAX_ITEM_COLUMNS: MAX_ITEM_COLUMNS,
+	MAX_ITEM_COLUMN_LABEL_CHARS: MAX_ITEM_COLUMN_LABEL_CHARS,
+	MAX_ATTACHMENT_BYTES: MAX_ATTACHMENT_BYTES,
+	MAX_ATTACHMENTS_PER_RUN: MAX_ATTACHMENTS_PER_RUN,
+	MAX_ATTACHMENTS_PER_LOG_ENTRY: MAX_ATTACHMENTS_PER_LOG_ENTRY,
+	MAX_CAPTION_CHARS: MAX_CAPTION_CHARS,
+	MAX_IMAGE_DIMENSION_PX: MAX_IMAGE_DIMENSION_PX
+};
+
+/**
+ * Limites do wire SDK ↔ servidor — fonte ÚNICA (protocol-limits.json): o SDK
+ * Node lê daqui, a @hobots/api importa de `hobots/protocol` e o SDK Python
+ * confere a paridade num teste que lê o mesmo JSON. Mudar um limite = mudar o
+ * JSON (e, no Python, a constante espelhada — o teste acusa).
+ */
+declare const WIRE_LIMITS: Readonly<typeof limits>;
+type WireLimits = typeof WIRE_LIMITS;
+
 /**
  * Tipos do protocolo do Hobots (SDK → servidor).
  *
- * Este arquivo é a fonte de verdade do wire format e só pode reexportar tipos:
- * o app valida os payloads com zod e trava o drift via `satisfies z.ZodType<...>`
- * contra estes tipos (importados de `hobots/protocol`).
+ * Este arquivo é a fonte de verdade do wire format: reexporta tipos (o app valida
+ * os payloads com zod e trava o drift via `satisfies z.ZodType<...>` contra eles)
+ * e os LIMITES numéricos do wire (WIRE_LIMITS, de protocol-limits.json) — o único
+ * valor de runtime daqui, para a api aplicar exatamente os caps que o SDK aplica.
  */
 
 /**
@@ -388,4 +441,4 @@ interface Envelope {
     items: EnvelopeItem[];
 }
 
-export type { Breadcrumb, BreadcrumbLevel, Envelope, EnvelopeItem, Environment, EnvironmentInput, EventPayload, EventType, EventUser, ExceptionData, HeartbeatPayload, InstanceInfo, ItemColumn, MachineProcess, MachineSnapshot, PollRequest, PollResponse, RunAttachmentConfirmRequest, RunAttachmentConfirmResponse, RunAttachmentContentType, RunAttachmentCreateRequest, RunAttachmentCreateResponse, RunCreateRequest, RunCreateResponse, RunDescriptor, RunError, RunItemInput, RunItemStatus, RunItemsCreateRequest, RunItemsCreateResponse, RunLogEntry, RunLogLevel, RunProgress, RunStatus, RunUpdateRequest, RunUpdateResponse, RunUpdateStatus, StackFrame, StepData, StepStatus, TaskItemsDeclaration, TransactionPayload };
+export { type Breadcrumb, type BreadcrumbLevel, type Envelope, type EnvelopeItem, type Environment, type EnvironmentInput, type EventPayload, type EventType, type EventUser, type ExceptionData, type HeartbeatPayload, type InstanceInfo, type ItemColumn, type MachineProcess, type MachineSnapshot, type PollRequest, type PollResponse, type RunAttachmentConfirmRequest, type RunAttachmentConfirmResponse, type RunAttachmentContentType, type RunAttachmentCreateRequest, type RunAttachmentCreateResponse, type RunCreateRequest, type RunCreateResponse, type RunDescriptor, type RunError, type RunItemInput, type RunItemStatus, type RunItemsCreateRequest, type RunItemsCreateResponse, type RunLogEntry, type RunLogLevel, type RunProgress, type RunStatus, type RunUpdateRequest, type RunUpdateResponse, type RunUpdateStatus, type StackFrame, type StepData, type StepStatus, type TaskItemsDeclaration, type TransactionPayload, WIRE_LIMITS, type WireLimits };

package/dist/protocol.d.ts

@@ -222,9 +222,9 @@ interface RunItemsCreateRequest {
     items: RunItemInput[];
 }
 interface RunItemsCreateResponse {
-    /** Itens inseridos */
+    /** Itens gravados — inseridos ou atualizados (id repetido na run: vale o último reporte) */
     accepted: number;
-    /** Ignorados por id repetido na run (retry de rede é idempotente) */
+    /** Colapsados por id repetido dentro do mesmo lote (vale o de maior seq) */
     duplicates: number;
 }
 /** Formatos aceitos para anexo. O S3 valida o content-type contra a assinatura. */
@@ -262,12 +262,65 @@ interface RunAttachmentConfirmResponse {
     ok: true;
 }
 
+var MAX_ITEMS_PER_ENVELOPE = 50;
+var HEARTBEAT_DEFAULT_INTERVAL_MS = 30000;
+var HEARTBEAT_MIN_INTERVAL_MS = 1000;
+var HEARTBEAT_MAX_INTERVAL_MS = 900000;
+var MAX_CLAIM_PER_POLL = 5;
+var MAX_LOG_MESSAGE_CHARS = 10000;
+var MAX_LOGS_PER_PATCH = 100;
+var MAX_ERROR_MESSAGE_CHARS = 10000;
+var MAX_ERROR_STACK_CHARS = 20000;
+var MAX_ITEMS_PER_RUN = 10000;
+var MAX_ITEMS_PER_REQUEST = 500;
+var MAX_ITEM_MESSAGE_CHARS = 2000;
+var MAX_ITEM_PAYLOAD_BYTES = 16384;
+var MAX_ITEM_COLUMNS = 12;
+var MAX_ITEM_COLUMN_LABEL_CHARS = 60;
+var MAX_ATTACHMENT_BYTES = 5242880;
+var MAX_ATTACHMENTS_PER_RUN = 20;
+var MAX_ATTACHMENTS_PER_LOG_ENTRY = 4;
+var MAX_CAPTION_CHARS = 200;
+var MAX_IMAGE_DIMENSION_PX = 20000;
+var limits = {
+	MAX_ITEMS_PER_ENVELOPE: MAX_ITEMS_PER_ENVELOPE,
+	HEARTBEAT_DEFAULT_INTERVAL_MS: HEARTBEAT_DEFAULT_INTERVAL_MS,
+	HEARTBEAT_MIN_INTERVAL_MS: HEARTBEAT_MIN_INTERVAL_MS,
+	HEARTBEAT_MAX_INTERVAL_MS: HEARTBEAT_MAX_INTERVAL_MS,
+	MAX_CLAIM_PER_POLL: MAX_CLAIM_PER_POLL,
+	MAX_LOG_MESSAGE_CHARS: MAX_LOG_MESSAGE_CHARS,
+	MAX_LOGS_PER_PATCH: MAX_LOGS_PER_PATCH,
+	MAX_ERROR_MESSAGE_CHARS: MAX_ERROR_MESSAGE_CHARS,
+	MAX_ERROR_STACK_CHARS: MAX_ERROR_STACK_CHARS,
+	MAX_ITEMS_PER_RUN: MAX_ITEMS_PER_RUN,
+	MAX_ITEMS_PER_REQUEST: MAX_ITEMS_PER_REQUEST,
+	MAX_ITEM_MESSAGE_CHARS: MAX_ITEM_MESSAGE_CHARS,
+	MAX_ITEM_PAYLOAD_BYTES: MAX_ITEM_PAYLOAD_BYTES,
+	MAX_ITEM_COLUMNS: MAX_ITEM_COLUMNS,
+	MAX_ITEM_COLUMN_LABEL_CHARS: MAX_ITEM_COLUMN_LABEL_CHARS,
+	MAX_ATTACHMENT_BYTES: MAX_ATTACHMENT_BYTES,
+	MAX_ATTACHMENTS_PER_RUN: MAX_ATTACHMENTS_PER_RUN,
+	MAX_ATTACHMENTS_PER_LOG_ENTRY: MAX_ATTACHMENTS_PER_LOG_ENTRY,
+	MAX_CAPTION_CHARS: MAX_CAPTION_CHARS,
+	MAX_IMAGE_DIMENSION_PX: MAX_IMAGE_DIMENSION_PX
+};
+
+/**
+ * Limites do wire SDK ↔ servidor — fonte ÚNICA (protocol-limits.json): o SDK
+ * Node lê daqui, a @hobots/api importa de `hobots/protocol` e o SDK Python
+ * confere a paridade num teste que lê o mesmo JSON. Mudar um limite = mudar o
+ * JSON (e, no Python, a constante espelhada — o teste acusa).
+ */
+declare const WIRE_LIMITS: Readonly<typeof limits>;
+type WireLimits = typeof WIRE_LIMITS;
+
 /**
  * Tipos do protocolo do Hobots (SDK → servidor).
  *
- * Este arquivo é a fonte de verdade do wire format e só pode reexportar tipos:
- * o app valida os payloads com zod e trava o drift via `satisfies z.ZodType<...>`
- * contra estes tipos (importados de `hobots/protocol`).
+ * Este arquivo é a fonte de verdade do wire format: reexporta tipos (o app valida
+ * os payloads com zod e trava o drift via `satisfies z.ZodType<...>` contra eles)
+ * e os LIMITES numéricos do wire (WIRE_LIMITS, de protocol-limits.json) — o único
+ * valor de runtime daqui, para a api aplicar exatamente os caps que o SDK aplica.
  */
 
 /**
@@ -388,4 +441,4 @@ interface Envelope {
     items: EnvelopeItem[];
 }
 
-export type { Breadcrumb, BreadcrumbLevel, Envelope, EnvelopeItem, Environment, EnvironmentInput, EventPayload, EventType, EventUser, ExceptionData, HeartbeatPayload, InstanceInfo, ItemColumn, MachineProcess, MachineSnapshot, PollRequest, PollResponse, RunAttachmentConfirmRequest, RunAttachmentConfirmResponse, RunAttachmentContentType, RunAttachmentCreateRequest, RunAttachmentCreateResponse, RunCreateRequest, RunCreateResponse, RunDescriptor, RunError, RunItemInput, RunItemStatus, RunItemsCreateRequest, RunItemsCreateResponse, RunLogEntry, RunLogLevel, RunProgress, RunStatus, RunUpdateRequest, RunUpdateResponse, RunUpdateStatus, StackFrame, StepData, StepStatus, TaskItemsDeclaration, TransactionPayload };
+export { type Breadcrumb, type BreadcrumbLevel, type Envelope, type EnvelopeItem, type Environment, type EnvironmentInput, type EventPayload, type EventType, type EventUser, type ExceptionData, type HeartbeatPayload, type InstanceInfo, type ItemColumn, type MachineProcess, type MachineSnapshot, type PollRequest, type PollResponse, type RunAttachmentConfirmRequest, type RunAttachmentConfirmResponse, type RunAttachmentContentType, type RunAttachmentCreateRequest, type RunAttachmentCreateResponse, type RunCreateRequest, type RunCreateResponse, type RunDescriptor, type RunError, type RunItemInput, type RunItemStatus, type RunItemsCreateRequest, type RunItemsCreateResponse, type RunLogEntry, type RunLogLevel, type RunProgress, type RunStatus, type RunUpdateRequest, type RunUpdateResponse, type RunUpdateStatus, type StackFrame, type StepData, type StepStatus, type TaskItemsDeclaration, type TransactionPayload, WIRE_LIMITS, type WireLimits };

package/dist/protocol.js

@@ -1 +1,7 @@
+import {
+  WIRE_LIMITS
+} from "./chunk-5WIIACWC.js";
+export {
+  WIRE_LIMITS
+};
 //# sourceMappingURL=protocol.js.map

package/docs/api-reference.md

@@ -26,7 +26,7 @@ ESM e CommonJS (`const { hobots } = require('hobots')`), com `.d.ts`. Depois da
 | `runId`, `task` | `string` | Identidade da execução (`''` fora de uma execução) |
 | `params` | `Record<string, unknown>` | Params da solicitação; `{}` no modo start |
 | `log` | `RunLogger` — `debug/info/warn/error/success(message, ...rest)` | Nunca lança. Vários argumentos viram texto unidos por espaço (como `console.log`) |
-| `items` | `RunItems` — `add(item)`, `succeeded(payload?, opts?)`, `failed(message, payload?, opts?)`, `occurrence(message, payload?, opts?)`; `opts.id` = identidade de negócio | Ponto de parada cooperativo |
+| `items` | `RunItems` — `add(item)`, `succeeded(payload?, opts?)`, `failed(message, payload?, opts?)`, `occurrence(message, payload?, opts?)`; `opts.id` = identidade de negócio. `each(list, (element, item, index) => …, { id?, payload?, op?, description?, progress? }) => Promise<{ total, succeeded, failed, occurrence }>` processa a lista inteira: exceção no handler vira item `failed` + step em erro e o loop segue; `item: RunItemHandle` = `succeeded/failed/occurrence`, `id`, `index`, `step`, `reported` | Ponto de parada cooperativo (o `each` para só em cancelamento/timeout) |
 | `progress` | `RunProgressReporter` — `total(n)`, `advance(count = 1)`, `set(current, total?)`, `current`, `snapshot` | `total/advance/set` são pontos de parada |
 | `transaction` | `Transaction` — `startChild(op?, description?)`, `setTag`, `setStatus`, `setName`; `Step` — `startChild`, `setStatus('ok' \| 'warning' \| 'error', message?)`, `setError(err, message?)` (motivo em `data.error`, exibido na Central), `setData(k, v)`, `finish()` | Finalizada pelo SDK; `startChild` é ponto de parada |
 | `signal` | `AbortSignal` | Cancelamento (app, timeout, shutdown) |

package/docs/tasks.md

@@ -67,10 +67,37 @@ hobots.items.add({ status: 'succeeded', id: '11', payload: { … } });
 ```
 
 - Chamadas síncronas e bufferizadas (lotes de até 500); o SDK drena o buffer antes do reporte final.
-- `id` é a identidade de negócio do item na execução — repetido, o servidor ignora (retry de rede e retry do handler idempotentes). Sem `id`, cada chamada é um item novo.
+- `id` é a identidade de negócio do item na execução — repetido, **vale o último reporte** (o servidor faz upsert: uma conta que falhou numa tentativa e deu certo no retry fica como sucesso; retry de rede é no-op). Sem `id`, cada chamada é um item novo.
 - Limites: 10.000 itens/execução, payload 16 KB, mensagem 2.000 caracteres. Uma execução cancelada ainda aceita os itens já bufferizados (trabalho feito).
 - Cada chamada é um **ponto de parada cooperativo** (lança `RunCanceled` se a execução foi cancelada).
 
+### Processar uma lista inteira (`hobots.items.each`)
+
+O contrato da plataforma — **todo item previsto termina com um desfecho registrado, e a falha de um não interrompe os outros** — fica garantido pelo SDK quando o loop é dele:
+
+```js
+const resultado = await hobots.items.each(
+  contas,
+  async (conta, item) => {
+    await login(conta);                       // lançou → item `failed` com a mensagem, step em erro, segue
+    const fatura = await baixar(conta);
+    if (!fatura) return item.occurrence('sem fatura no mês');   // ocorrência de negócio
+    item.succeeded({ fatura: fatura.numero, valor: fatura.valor }); // mescla com o payload base
+    // retornou sem registrar nada → `succeeded`
+  },
+  { id: c => c.numero_cliente, payload: c => ({ cpf_cnpj: c.cpf_cnpj, nome: c.nome }) }
+);
+// resultado = { total, succeeded, failed, occurrence }
+```
+
+- Cada elemento vira uma **step** no waterfall (`op` 'item', descrição = `id`; `item.step.startChild(...)` mede sub-etapas) e um **item** com o `id` e o payload base.
+- **Exceção no handler** = item `failed` com a mensagem do erro, `step.setError(erro)`, linha de erro no log da run — e o loop **segue para o próximo**. Nada do que o handler já registrou (`item.failed/occurrence`) é sobrescrito.
+- **Progresso automático**: declara o total pelo tamanho da lista (se o bot ainda não declarou um) e avança a cada elemento, inclusive nos que falharam. `progress: false` deixa o progresso por conta do bot.
+- Só **cancelamento, timeout e shutdown** interrompem o loop: o `RunCanceled` sobe, o item em curso não é registrado e o progresso não avança.
+- Aceita `Iterable` ou `AsyncIterable` (sem `length`, nenhum total é declarado).
+
+> Se o handler da task termina com o progresso parado antes do total declarado (ex.: 45/76), o SDK deixa um aviso no log da execução — e a Central sinaliza o desencontro entre processados e itens reportados.
+
 ### Colunas da aba de itens
 
 As colunas vêm do código, não do formulário — valem para `register()` (com ou sem formulário) e `start()`:

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "hobots",
-  "version": "3.2.1",
-  "description": "SDK JavaScript da Hobots — tudo é uma task: register() atende solicitações da plataforma, start() roda sempre e reporta logs, itens e progresso. Credenciais por env, heartbeat sempre ligado, objeto global `hobots`.",
+  "version": "3.3.0",
+  "description": "SDK JavaScript da Hobots \u2014 tudo \u00e9 uma task: register() atende solicita\u00e7\u00f5es da plataforma, start() roda sempre e reporta logs, itens e progresso. Credenciais por env, heartbeat sempre ligado, objeto global `hobots`.",
   "type": "module",
   "sideEffects": false,
   "license": "MIT",
@@ -29,6 +29,7 @@
   },
   "scripts": {
     "build": "tsup",
+    "prepublishOnly": "tsup",
     "dev": "tsup --watch",
     "lint": "eslint . --max-warnings 0",
     "test": "vitest run",
@@ -39,6 +40,7 @@
     "@types/node": "^20",
     "@workspace/eslint-config": "workspace:*",
     "@workspace/typescript-config": "workspace:*",
+    "@workspace/utils": "workspace:*",
     "tsup": "^8.4.0",
     "typescript": "5.7.3",
     "vitest": "^4.1.10"