hobots 3.2.2 → 3.4.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

@@ -204,7 +204,7 @@ type RunItemStatus = 'succeeded' | 'failed' | 'occurrence';
 interface RunItemInput {
     /**
      * Identidade do item dentro da run — id de negócio do dev (ex.: nº da nota)
-     * ou uuid4-hex gerado pelo SDK. Repetido na mesma run = ignorado (primeiro vence).
+     * ou uuid4-hex gerado pelo SDK. Repetido na mesma run = upsert (vale o último reporte).
      */
     id: string;
     /** Ordem de emissão no agente (contador monotônico por run) */
@@ -216,6 +216,8 @@ interface RunItemInput {
     payload?: Record<string, unknown>;
     /** ISO 8601 — relógio do agente, apenas para exibição */
     ts?: string;
+    /** Ids de anexo (print do item) — opcional; mesmo teto por entrada das linhas de log */
+    attachments?: string[];
 }
 /** POST /v1/tasks/runs/{id}/items — aceito mesmo com a run cancelada/terminal */
 interface RunItemsCreateRequest {
@@ -231,13 +233,13 @@ interface RunItemsCreateResponse {
 type RunAttachmentContentType = 'image/png' | 'image/jpeg' | 'image/webp';
 /** POST /v1/tasks/runs/{id}/attachments */
 interface RunAttachmentCreateRequest {
-    /** Id do anexo gerado pelo agente (32 hex) — já referenciado na linha de log */
+    /** Id do anexo gerado pelo agente (32 hex) — já referenciado no log/item/step que o carrega */
     id: string;
     content_type: RunAttachmentContentType;
     /** Tamanho exato do binário; o PUT presignado é assinado com este Content-Length */
     size_bytes: number;
     caption?: string;
-    /** ISO 8601 — ts da linha de log que referencia o anexo */
+    /** ISO 8601 — ts do evento (log/item/step) que referencia o anexo */
     log_ts?: string;
     width?: number;
     height?: number;
@@ -262,12 +264,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 +443,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

@@ -204,7 +204,7 @@ type RunItemStatus = 'succeeded' | 'failed' | 'occurrence';
 interface RunItemInput {
     /**
      * Identidade do item dentro da run — id de negócio do dev (ex.: nº da nota)
-     * ou uuid4-hex gerado pelo SDK. Repetido na mesma run = ignorado (primeiro vence).
+     * ou uuid4-hex gerado pelo SDK. Repetido na mesma run = upsert (vale o último reporte).
      */
     id: string;
     /** Ordem de emissão no agente (contador monotônico por run) */
@@ -216,6 +216,8 @@ interface RunItemInput {
     payload?: Record<string, unknown>;
     /** ISO 8601 — relógio do agente, apenas para exibição */
     ts?: string;
+    /** Ids de anexo (print do item) — opcional; mesmo teto por entrada das linhas de log */
+    attachments?: string[];
 }
 /** POST /v1/tasks/runs/{id}/items — aceito mesmo com a run cancelada/terminal */
 interface RunItemsCreateRequest {
@@ -231,13 +233,13 @@ interface RunItemsCreateResponse {
 type RunAttachmentContentType = 'image/png' | 'image/jpeg' | 'image/webp';
 /** POST /v1/tasks/runs/{id}/attachments */
 interface RunAttachmentCreateRequest {
-    /** Id do anexo gerado pelo agente (32 hex) — já referenciado na linha de log */
+    /** Id do anexo gerado pelo agente (32 hex) — já referenciado no log/item/step que o carrega */
     id: string;
     content_type: RunAttachmentContentType;
     /** Tamanho exato do binário; o PUT presignado é assinado com este Content-Length */
     size_bytes: number;
     caption?: string;
-    /** ISO 8601 — ts da linha de log que referencia o anexo */
+    /** ISO 8601 — ts do evento (log/item/step) que referencia o anexo */
     log_ts?: string;
     width?: number;
     height?: number;
@@ -262,12 +264,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 +443,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

@@ -25,17 +25,18 @@ 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 |
+| `log` | `RunLogger` — `debug/info/warn/error/success(message, ...rest)` | Nunca lança. Vários argumentos viram texto unidos por espaço (como `console.log`); um `hobots.image(...)` no **último** argumento vira o print da linha |
+| `items` | `RunItems` — `add(item)`, `succeeded(payload?, opts?)`, `failed(message, payload?, opts?)`, `occurrence(message, payload?, opts?)`; `opts.id` = identidade de negócio, `opts.image` = print do item. `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(payload?, { image }?)/failed(msg, payload?, { image }?)/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 |
+| `transaction` | `Transaction` — `startChild(op?, description?)`, `setTag`, `setStatus`, `setName`; `Step` — `startChild`, `setStatus('ok' \| 'warning' \| 'error', message?, { image }?)`, `setError(err, message?, { image }?)` (motivo em `data.error`, print em `data.attachments`, exibidos na Central), `setData(k, v)`, `finish()` | Finalizada pelo SDK; `startChild` é ponto de parada |
 | `signal` | `AbortSignal` | Cancelamento (app, timeout, shutdown) |
 | `throwIfCanceled()` | `() => void` | Lança `RunCanceled` se o signal disparou |
 | `sleep(ms)` | `(ms: number) => Promise<void>` | Rejeita com `RunCanceled` no cancelamento |
-| `attach(image, options?)` | `(image: AttachInput, options?: AttachOptions) => Promise<AttachResult>` | `AttachInput = Uint8Array \| ArrayBuffer \| string` (caminho); `AttachOptions = { caption?, level?, message?, contentType? }`; `AttachResult = { id, ok, reason? }`. Nunca lança |
 | `retry(fn, options?)` | como `hobots.retry` | |
 
-Fora de uma execução, `hobots.*` cai em fallbacks seguros com aviso único por membro (log ecoa no terminal; items/progress no-op; `signal` nunca aborta; `attach` resolve `{ ok: false }`).
+`hobots.image(input, options?)` — `(input: AttachInput, options?: ImageOptions) => ImageAttachment`; `AttachInput = Uint8Array \| ArrayBuffer \| string` (caminho); `ImageOptions = { caption?, contentType? }`; `ImageInput = AttachInput \| ImageAttachment` é o que `log.*` (só o embrulho), `items.*` e `step.setStatus/setError` aceitam. Puro, nunca lança; o upload (segundo plano, nunca bloqueia) acontece quando o evento é registrado.
+
+Fora de uma execução, `hobots.*` cai em fallbacks seguros com aviso único por membro (log ecoa no terminal, imagem descartada; items/progress no-op; `signal` nunca aborta).
 
 ## Tabelas de opções
 
@@ -88,7 +89,7 @@ Fora de uma execução, `hobots.*` cai em fallbacks seguros com aviso único por
 | --- | --- | --- |
 | `type` | `'fatal' \| 'error' \| 'warning' \| 'success'` | default `'error'` |
 | `tags`, `extra`, `fingerprint` | | metadados do evento (`fingerprint` sobrescreve o agrupamento) |
-| `attachment` | `AttachInput \| { image, caption?, contentType? }` | print anexado à linha de log da execução atual |
+| `attachment` | `ImageInput \| { image, caption?, contentType? }` | print anexado à linha de log da execução atual |
 
 ### `TaskHandler`
 

package/docs/protocol.md

@@ -117,7 +117,7 @@ Corpo `RunUpdateRequest`:
   "logs":   [
     { "ts": "…", "level": "info", "message": "…" },            // delta; o servidor concatena
     { "ts": "…", "level": "info", "message": "portal após o login",
-      "attachments": ["<32 hex>"] }                            // opcional; ids de anexo (máx. 4)
+      "attachments": ["<32 hex>"] }                            // opcional; ids de anexo (máx. 4) — hobots.image() no log
   ],
   "error":  { "type": "Error", "message": "…", "stack": "…" },  // só com 'failed'
   "progress": { "current": 10, "total": 100 }                     // opcional: snapshot de hobots.progress
@@ -149,13 +149,16 @@ Corpo `RunItemsCreateRequest`:
       "status": "succeeded",             // 'succeeded' | 'failed' | 'occurrence'
       "message": "…",                    // opcional — motivo (failed/occurrence), máx. 2100
       "payload": { "numero_nota": "12345", "cnpj_prestador": "…" },  // opcional, máx. 16 KB
-      "ts": "2026-08-10T12:00:00.000Z"   // opcional — relógio do agente, só exibição
+      "ts": "2026-08-10T12:00:00.000Z",  // opcional — relógio do agente, só exibição
+      "attachments": ["<32 hex>"]        // opcional — ids de anexo (máx. 4): print do item
     }
   ]
 }
 ```
 
-Resposta `200` `RunItemsCreateResponse`: `{ "accepted": 1, "duplicates": 0 }` — `duplicates` conta os ignorados por `(run, id)` repetido.
+Resposta `200` `RunItemsCreateResponse`: `{ "accepted": 1, "duplicates": 0 }` — `duplicates` conta os colapsados por `(run, id)` repetido no mesmo lote (vale o último reporte; no banco é upsert).
+
+- `attachments` é **opcional** e aditivo (uma API anterior ao recurso descarta o campo). As steps carregam o print do mesmo jeito, em `data.attachments` do `StepData` que vai no `POST /v1/ingest` da transaction — sem campo novo no wire.
 
 - **Run cancelada/terminal aceita itens** (200): item é fato de trabalho já feito — mesmo racional do log tardio. Esta rota não tem 409.
 - O insert e os **contadores materializados** da run (`items_total/succeeded/failed/occurrence`, que alimentam os totalizadores no app) saem num único statement atômico no servidor.
@@ -177,11 +180,11 @@ Corpo `RunAttachmentCreateRequest`:
 
 ```jsonc
 {
-  "id": "<32 hex>",              // gerado pelo agente, já referenciado na linha de log
+  "id": "<32 hex>",              // gerado pelo agente, já referenciado no log/item/step
   "content_type": "image/png",   // 'image/png' | 'image/jpeg' | 'image/webp'
   "size_bytes": 184320,          // exato — entra na assinatura da URL
   "caption": "portal após o login",  // opcional, máx. 500
-  "log_ts": "…",                 // opcional, ISO 8601 — ts da linha de log
+  "log_ts": "…",                 // opcional, ISO 8601 — ts do evento (log/item/step)
   "width": 1920, "height": 1080  // opcionais
 }
 ```
@@ -216,7 +219,7 @@ Confirma o upload. Corpo `RunAttachmentConfirmRequest`: `{ "status": "uploaded"
 
 É **conforto de UX**, não correção: enquanto não confirmado, o app mostra a miniatura como "enviando imagem…". O agente engole falhas desta chamada.
 
-Limites de anexo (aplicados no SDK **e** no servidor): PNG/JPEG/WEBP, 5 MB por imagem, 20 por execução, 4 por linha de log.
+Limites de anexo (aplicados no SDK **e** no servidor): PNG/JPEG/WEBP, 5 MB por imagem, 20 por execução, 4 por evento (linha de log, item ou step).
 
 ## Onde vive o claim atômico
 

package/docs/tasks.md

@@ -40,11 +40,11 @@ Isso funciona com `concurrency > 1` porque cada execução roda no seu contexto
 
 | Membro | Notas |
 | --- | --- |
-| `hobots.log.<debug\|info\|warn\|error\|success>(msg)` | Enviado incrementalmente (PATCHes com throttle) e ecoado no terminal. Nunca lança. |
+| `hobots.log.<debug\|info\|warn\|error\|success>(msg, ...rest)` | Enviado incrementalmente (PATCHes com throttle) e ecoado no terminal. Nunca lança. `hobots.image(...)` no último argumento = print da linha. |
 | `hobots.items` | Ver [Itens](#itens-de-execução-hobotsitems) |
 | `hobots.progress` | Ver [Progresso](#progresso-hobotsprogress) |
 | `hobots.transaction` | Transaction da execução, já correlacionada e finalizada pelo SDK. `startChild(op, descrição)` = uma step no waterfall. |
-| `hobots.attach(imagem, opts?)` | Ver [Anexos](#anexos-screenshots) |
+| `hobots.image(imagem, opts?)` | Ver [Imagens](#imagens-screenshots) |
 | `hobots.captureException(erro, hint?)` | Issue no módulo Issues; `hint.attachment` anexa um print à linha de log |
 | `hobots.retry(fn, opts?)` | Ver [Retry](#retry) |
 | `hobots.sleep(ms)` · `hobots.signal` · `hobots.throwIfCanceled()` | Ver [Cancelamento](#cancelamento-cooperativo) |
@@ -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()`:
@@ -97,20 +124,39 @@ for (const nota of notas) {
 
 Opcional e independente de `items`. Sem `total()` nada é enviado. Snapshot absoluto que pega carona nos PATCHes de log (no pior caso 1/s); o PATCH terminal leva o valor final. `set(atual, total?)`, `current` e `snapshot` completam a API. `total/advance/set` são pontos de parada cooperativos; `current`/`snapshot` nunca lançam.
 
-## Anexos (screenshots)
+## Imagens (screenshots)
+
+Um print vai **junto do evento** que ele ilustra — a linha de log, o item ou a step — para o
+usuário ver o estado do robô no momento em que aquilo aconteceu (botão de imagem no app):
 
 ```js
-await hobots.attach(await page.screenshot(), { caption: 'portal após o login' });
+// na linha de log: hobots.image(...) como ÚLTIMO argumento
+hobots.log.info('portal após o login', hobots.image(await page.screenshot()));
+hobots.log.error('login falhou', hobots.image(await page.screenshot(), { caption: 'tela do erro' }));
+
+// no item
+hobots.items.failed('nota rejeitada', { numero }, { image: await page.screenshot() });
+await hobots.items.each(notas, async (nota, item) => {
+  …
+  item.occurrence('sem fatura no mês', undefined, { image: await page.screenshot() });
+});
 
+// na step
+const step = hobots.transaction.startChild('emitir', numero);
 try {
-  await emitir(params);
+  await emitir(numero);
 } catch (erro) {
-  hobots.captureException(erro, { attachment: { image: await page.screenshot(), caption: 'tela no momento do erro' } });
+  step.setError(erro, undefined, { image: await page.screenshot() });
   throw erro;
+} finally {
+  step.finish();
 }
+
+// numa issue (módulo Issues) — o print vai na linha de log que espelha o erro
+hobots.captureException(erro, { attachment: hobots.image(await page.screenshot(), { caption: 'tela no momento do erro' }) });
 ```
 
-O SDK não tira o print: aceita bytes (`Uint8Array`/`ArrayBuffer`/`Buffer`) ou um caminho de arquivo. A linha de log entra na hora; o upload sobe em segundo plano direto para o S3 (URL presignada) e **nunca lança nem bloqueia** — falhas viram um aviso no log da execução. Limites: PNG/JPEG/WEBP, 5 MB, 20 por execução, 4 por linha de log. Fora de uma execução não há onde pendurar a imagem (descartada com aviso).
+O SDK não tira o print: aceita bytes (`Uint8Array`/`ArrayBuffer`/`Buffer`) ou um caminho de arquivo, crus ou embrulhados por `hobots.image(bytes, { caption?, contentType? })` (só o embrulho leva legenda; em `log.*` ele é obrigatório para distinguir a imagem de um argumento comum). O evento entra na hora com o id do anexo; o upload sobe em segundo plano direto para o S3 (URL presignada) e **nunca lança nem bloqueia** — falhas viram um aviso no log da execução. Limites: PNG/JPEG/WEBP, 5 MB, 20 por execução, 4 por evento. Fora de uma execução não há onde pendurar a imagem (descartada com aviso). O `hobots.attach` das versões anteriores foi removido nesta API.
 
 ## Cancelamento cooperativo
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hobots",
-  "version": "3.2.2",
+  "version": "3.4.0",
   "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`.",
   "type": "module",
   "sideEffects": false,
@@ -33,13 +33,16 @@
     "dev": "tsup --watch",
     "lint": "eslint . --max-warnings 0",
     "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit"
   },
   "devDependencies": {
     "@types/node": "^20",
+    "@vitest/coverage-v8": "^4.1.10",
     "@workspace/eslint-config": "workspace:*",
     "@workspace/typescript-config": "workspace:*",
+    "@workspace/utils": "workspace:*",
     "tsup": "^8.4.0",
     "typescript": "5.7.3",
     "vitest": "^4.1.10"