hobots 3.4.0 → 4.1.0

package/dist/protocol.cjs

@@ -35,7 +35,6 @@ var protocol_limits_default = {
   MAX_LOGS_PER_PATCH: 100,
   MAX_ERROR_MESSAGE_CHARS: 1e4,
   MAX_ERROR_STACK_CHARS: 2e4,
-  MAX_ITEMS_PER_RUN: 1e4,
   MAX_ITEMS_PER_REQUEST: 500,
   MAX_ITEM_MESSAGE_CHARS: 2e3,
   MAX_ITEM_PAYLOAD_BYTES: 16384,

package/dist/protocol.cjs.map

@@ -1 +1 @@
-{"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":[]}
+{"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 execuções (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  ItemsDeclaration,\n  InstanceMode,\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 do agente (hobots.transaction dentro do 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_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,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;;;ACZO,IAAM,cAAc;","names":[]}

package/dist/protocol.d.cts

@@ -72,7 +72,10 @@ interface MachineSnapshot {
 }
 
 /**
- * Tipos do protocolo de tasks do Hobots (agente SDK ↔ servidor).
+ * Tipos do protocolo de execuções do Hobots (agente SDK ↔ servidor).
+ *
+ * O agente é a própria tarefa: não há slug de task no wire. O que o agente faz é
+ * identificado pelo client secret; a instância só declara COMO trabalha (`mode`).
  *
  * Este arquivo é a fonte de verdade do wire format e não pode importar nada:
  * o app valida os payloads com zod e trava o drift via `satisfies z.ZodType<...>`
@@ -91,7 +94,7 @@ interface RunLogEntry {
     message: string;
     /**
      * Ids dos anexos (imagens) desta linha — gerados pelo agente (32 hex) e criados via
-     * `POST /v1/tasks/runs/{id}/attachments`. O upload roda em segundo plano: a linha pode
+     * `POST /v1/runs/{id}/attachments`. O upload roda em segundo plano: a linha pode
      * chegar ao servidor antes do binário estar no S3.
      */
     attachments?: string[];
@@ -102,8 +105,10 @@ interface ItemColumn {
     /** ausente = a plataforma exibe a própria key */
     label?: string;
 }
-/** Colunas de itens declaradas no código para uma task (`items.columns` do register/start). */
-interface TaskItemsDeclaration {
+/** Como a instância trabalha: 'on_demand' = register (poll de solicitações); 'always_on' = start (abre a própria run). */
+type InstanceMode = 'on_demand' | 'always_on';
+/** Colunas de itens declaradas no código (`items.columns` do register/start). */
+interface ItemsDeclaration {
     attributes: ItemColumn[];
 }
 interface InstanceInfo {
@@ -116,10 +121,10 @@ interface InstanceInfo {
     host?: string;
     /** Ambiente da instância — mesmo valor do heartbeat; agentes poll-only só o informam aqui */
     environment?: EnvironmentInput;
-    /** Tasks registradas no agente */
-    tasks?: string[];
-    /** Colunas de itens declaradas no código, por task — só as tasks que declararam `items` */
-    task_items?: Record<string, TaskItemsDeclaration>;
+    /** Modo de trabalho desta instância (register = on_demand, start = always_on) */
+    mode?: InstanceMode;
+    /** Colunas de itens declaradas no código — só quando o register/start declarou `items` */
+    items?: ItemsDeclaration;
     /**
      * Intervalo de poll em ms — alimenta a tolerância de offline do servidor (3×) em
      * agentes poll-only, que sem isso herdariam a tolerância do heartbeat (30s × 3).
@@ -128,17 +133,14 @@ interface InstanceInfo {
     /** Recursos da máquina no momento do poll — alimenta a série da instância em agentes sem heartbeat */
     machine?: MachineSnapshot;
 }
-/** POST /v1/tasks/poll */
+/** POST /v1/runs/poll */
 interface PollRequest {
     instance?: InstanceInfo;
     /** Quantas runs reivindicar de uma vez (1..5). Default: 1 */
     max?: number;
-    /** Só entrega runs destas tasks (nomes registrados no agente) */
-    tasks?: string[];
 }
 interface RunDescriptor {
     id: string;
-    task: string;
     params: Record<string, unknown>;
     form: {
         id: string;
@@ -153,13 +155,11 @@ interface PollResponse {
     runs: RunDescriptor[];
 }
 /**
- * POST /v1/tasks/runs — modo start do SDK: a própria instância abre a run, que já
+ * POST /v1/runs — modo start do SDK: a própria instância abre a run, que já
  * nasce 'running' (started_at = now), sem formulário nem solicitante. Dali em diante
  * ela é reportada pelas mesmas rotas de uma run reivindicada no poll.
  */
 interface RunCreateRequest {
-    /** slug da task (1..255) — vira task_runs.task_slug */
-    task: string;
     /** presença da instância — obrigatória: a run nasce vinculada à instância */
     instance: InstanceInfo;
 }
@@ -181,7 +181,7 @@ interface RunProgress {
     /** total de itens previsto (>= 1) */
     total: number;
 }
-/** PATCH /v1/tasks/runs/{id} — 'running' pode repetir com logs incrementais */
+/** PATCH /v1/runs/{id} — 'running' pode repetir com logs incrementais */
 interface RunUpdateRequest {
     status: RunUpdateStatus;
     /** Apenas com status 'failed' */
@@ -219,7 +219,7 @@ interface RunItemInput {
     /** 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 */
+/** POST /v1/runs/{id}/items — aceito mesmo com a run cancelada/terminal */
 interface RunItemsCreateRequest {
     items: RunItemInput[];
 }
@@ -231,7 +231,7 @@ interface RunItemsCreateResponse {
 }
 /** Formatos aceitos para anexo. O S3 valida o content-type contra a assinatura. */
 type RunAttachmentContentType = 'image/png' | 'image/jpeg' | 'image/webp';
-/** POST /v1/tasks/runs/{id}/attachments */
+/** POST /v1/runs/{id}/attachments */
 interface RunAttachmentCreateRequest {
     /** Id do anexo gerado pelo agente (32 hex) — já referenciado no log/item/step que o carrega */
     id: string;
@@ -253,7 +253,7 @@ interface RunAttachmentCreateResponse {
     /** Validade da URL, em segundos */
     expires_in: number;
 }
-/** PATCH /v1/tasks/runs/{id}/attachments/{attachmentId} */
+/** PATCH /v1/runs/{id}/attachments/{attachmentId} */
 interface RunAttachmentConfirmRequest {
     status: 'uploaded' | 'failed';
     size_bytes?: number;
@@ -273,7 +273,6 @@ 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;
@@ -294,7 +293,6 @@ var limits = {
 	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,
@@ -407,7 +405,7 @@ interface TransactionPayload {
     tags?: Record<string, string>;
     release?: string;
     environment?: EnvironmentInput;
-    /** Correlaciona esta transaction a uma execução de task (ctx.tx dentro de um task handler) */
+    /** Correlaciona esta transaction a uma execução do agente (hobots.transaction dentro do handler) */
     run_id?: string;
 }
 interface HeartbeatPayload {
@@ -443,4 +441,4 @@ interface Envelope {
     items: EnvelopeItem[];
 }
 
-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 };
+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 InstanceMode, type ItemColumn, type ItemsDeclaration, 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 TransactionPayload, WIRE_LIMITS, type WireLimits };

package/dist/protocol.d.ts

@@ -72,7 +72,10 @@ interface MachineSnapshot {
 }
 
 /**
- * Tipos do protocolo de tasks do Hobots (agente SDK ↔ servidor).
+ * Tipos do protocolo de execuções do Hobots (agente SDK ↔ servidor).
+ *
+ * O agente é a própria tarefa: não há slug de task no wire. O que o agente faz é
+ * identificado pelo client secret; a instância só declara COMO trabalha (`mode`).
  *
  * Este arquivo é a fonte de verdade do wire format e não pode importar nada:
  * o app valida os payloads com zod e trava o drift via `satisfies z.ZodType<...>`
@@ -91,7 +94,7 @@ interface RunLogEntry {
     message: string;
     /**
      * Ids dos anexos (imagens) desta linha — gerados pelo agente (32 hex) e criados via
-     * `POST /v1/tasks/runs/{id}/attachments`. O upload roda em segundo plano: a linha pode
+     * `POST /v1/runs/{id}/attachments`. O upload roda em segundo plano: a linha pode
      * chegar ao servidor antes do binário estar no S3.
      */
     attachments?: string[];
@@ -102,8 +105,10 @@ interface ItemColumn {
     /** ausente = a plataforma exibe a própria key */
     label?: string;
 }
-/** Colunas de itens declaradas no código para uma task (`items.columns` do register/start). */
-interface TaskItemsDeclaration {
+/** Como a instância trabalha: 'on_demand' = register (poll de solicitações); 'always_on' = start (abre a própria run). */
+type InstanceMode = 'on_demand' | 'always_on';
+/** Colunas de itens declaradas no código (`items.columns` do register/start). */
+interface ItemsDeclaration {
     attributes: ItemColumn[];
 }
 interface InstanceInfo {
@@ -116,10 +121,10 @@ interface InstanceInfo {
     host?: string;
     /** Ambiente da instância — mesmo valor do heartbeat; agentes poll-only só o informam aqui */
     environment?: EnvironmentInput;
-    /** Tasks registradas no agente */
-    tasks?: string[];
-    /** Colunas de itens declaradas no código, por task — só as tasks que declararam `items` */
-    task_items?: Record<string, TaskItemsDeclaration>;
+    /** Modo de trabalho desta instância (register = on_demand, start = always_on) */
+    mode?: InstanceMode;
+    /** Colunas de itens declaradas no código — só quando o register/start declarou `items` */
+    items?: ItemsDeclaration;
     /**
      * Intervalo de poll em ms — alimenta a tolerância de offline do servidor (3×) em
      * agentes poll-only, que sem isso herdariam a tolerância do heartbeat (30s × 3).
@@ -128,17 +133,14 @@ interface InstanceInfo {
     /** Recursos da máquina no momento do poll — alimenta a série da instância em agentes sem heartbeat */
     machine?: MachineSnapshot;
 }
-/** POST /v1/tasks/poll */
+/** POST /v1/runs/poll */
 interface PollRequest {
     instance?: InstanceInfo;
     /** Quantas runs reivindicar de uma vez (1..5). Default: 1 */
     max?: number;
-    /** Só entrega runs destas tasks (nomes registrados no agente) */
-    tasks?: string[];
 }
 interface RunDescriptor {
     id: string;
-    task: string;
     params: Record<string, unknown>;
     form: {
         id: string;
@@ -153,13 +155,11 @@ interface PollResponse {
     runs: RunDescriptor[];
 }
 /**
- * POST /v1/tasks/runs — modo start do SDK: a própria instância abre a run, que já
+ * POST /v1/runs — modo start do SDK: a própria instância abre a run, que já
  * nasce 'running' (started_at = now), sem formulário nem solicitante. Dali em diante
  * ela é reportada pelas mesmas rotas de uma run reivindicada no poll.
  */
 interface RunCreateRequest {
-    /** slug da task (1..255) — vira task_runs.task_slug */
-    task: string;
     /** presença da instância — obrigatória: a run nasce vinculada à instância */
     instance: InstanceInfo;
 }
@@ -181,7 +181,7 @@ interface RunProgress {
     /** total de itens previsto (>= 1) */
     total: number;
 }
-/** PATCH /v1/tasks/runs/{id} — 'running' pode repetir com logs incrementais */
+/** PATCH /v1/runs/{id} — 'running' pode repetir com logs incrementais */
 interface RunUpdateRequest {
     status: RunUpdateStatus;
     /** Apenas com status 'failed' */
@@ -219,7 +219,7 @@ interface RunItemInput {
     /** 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 */
+/** POST /v1/runs/{id}/items — aceito mesmo com a run cancelada/terminal */
 interface RunItemsCreateRequest {
     items: RunItemInput[];
 }
@@ -231,7 +231,7 @@ interface RunItemsCreateResponse {
 }
 /** Formatos aceitos para anexo. O S3 valida o content-type contra a assinatura. */
 type RunAttachmentContentType = 'image/png' | 'image/jpeg' | 'image/webp';
-/** POST /v1/tasks/runs/{id}/attachments */
+/** POST /v1/runs/{id}/attachments */
 interface RunAttachmentCreateRequest {
     /** Id do anexo gerado pelo agente (32 hex) — já referenciado no log/item/step que o carrega */
     id: string;
@@ -253,7 +253,7 @@ interface RunAttachmentCreateResponse {
     /** Validade da URL, em segundos */
     expires_in: number;
 }
-/** PATCH /v1/tasks/runs/{id}/attachments/{attachmentId} */
+/** PATCH /v1/runs/{id}/attachments/{attachmentId} */
 interface RunAttachmentConfirmRequest {
     status: 'uploaded' | 'failed';
     size_bytes?: number;
@@ -273,7 +273,6 @@ 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;
@@ -294,7 +293,6 @@ var limits = {
 	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,
@@ -407,7 +405,7 @@ interface TransactionPayload {
     tags?: Record<string, string>;
     release?: string;
     environment?: EnvironmentInput;
-    /** Correlaciona esta transaction a uma execução de task (ctx.tx dentro de um task handler) */
+    /** Correlaciona esta transaction a uma execução do agente (hobots.transaction dentro do handler) */
     run_id?: string;
 }
 interface HeartbeatPayload {
@@ -443,4 +441,4 @@ interface Envelope {
     items: EnvelopeItem[];
 }
 
-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 };
+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 InstanceMode, type ItemColumn, type ItemsDeclaration, 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 TransactionPayload, WIRE_LIMITS, type WireLimits };

package/dist/protocol.js

@@ -1,6 +1,6 @@
 import {
   WIRE_LIMITS
-} from "./chunk-5WIIACWC.js";
+} from "./chunk-HKCDMUA3.js";
 export {
   WIRE_LIMITS
 };

package/docs/README.md

@@ -2,27 +2,29 @@
 
 SDK JavaScript da **Hobots** para robôs (RPAs) e integrações. Cliente HTTP puro, sem dependências de runtime, Node 18+.
 
-**Tudo é uma task.** Não existe `init()`: a primeira chamada a `register()`/`start()` configura o processo (credenciais do ambiente, heartbeat sempre ligado, captura de erros não tratados). O objeto global `hobots` expõe a execução atual — `hobots.log`, `hobots.items`, `hobots.progress`, `hobots.transaction`… — de qualquer lugar do programa.
+**O agente é a própria tarefa.** Não existe `init()` nem slug: a única chamada a `register()`/`start()` configura o processo (credenciais do ambiente, heartbeat sempre ligado, captura de erros não tratados) e diz o que o robô faz. O objeto global `hobots` expõe a execução atual — `hobots.log`, `hobots.items`, `hobots.progress`, `hobots.transaction`… — de qualquer lugar do programa.
 
 | Modo | Chamada | Para quê |
 | --- | --- | --- |
-| **Sob demanda** | `hobots.register(task, handler, options?)` | O robô faz polling e executa uma solicitação do app (formulário/agendamento) por vez — módulo **Solicitações**. |
-| **Sempre ligado** | `hobots.start(task, handler, options?)` | O robô abre a própria execução e roda o handler (o seu loop) dentro dela; a plataforma recebe logs, itens e progresso. |
+| **Sob demanda** | `hobots.register(handler, options?)` | O robô faz polling e executa uma solicitação do app (formulário do agente/agendamento) por vez — módulo **Trabalhos**. |
+| **Sempre ligado** | `hobots.start(handler, options?)` | O robô abre a própria execução e roda o handler (o seu loop) dentro dela; a plataforma recebe logs, itens e progresso. |
+
+Uma chamada por processo: um processo é um agente, e um agente faz uma coisa.
 
 ## Páginas
 
-- [Getting started](./getting-started.md) — instalação, envs, primeira task nos dois modos, encerramento.
-- [Tasks](./tasks.md) — handler, o objeto `hobots`, itens, progresso, anexos, cancelamento automático, retry, concorrência, idempotência.
-- [Conceitos](./concepts.md) — o vocabulário: task, execução, evento, issue, transaction, step, heartbeat, instância, claim.
+- [Getting started](./getting-started.md) — instalação, envs, o primeiro agente nos dois modos, encerramento.
+- [Execuções](./runs.md) — handler, o objeto `hobots`, itens, progresso, anexos, cancelamento automático, retry, concorrência, idempotência.
+- [Conceitos](./concepts.md) — o vocabulário: agente, execução, evento, issue, transaction, step, heartbeat, instância, claim.
 - [Referência de API](./api-reference.md) — assinaturas, tabelas de opções e tempos.
-- [Protocolo & transporte](./protocol.md) — Client Secret, endpoints (`/v1/ingest`, `/v1/tasks/*`), envelope, retries, claim atômico.
+- [Protocolo & transporte](./protocol.md) — Client Secret, endpoints (`/v1/ingest`, `/v1/runs/*`), envelope, retries, claim atômico.
 
 ## Exemplo mínimo
 
 ```js
 import hobots from 'hobots'; // HOBOTS_CLIENT_SECRET e HOBOTS_INSTANCE_ID no ambiente
 
-hobots.register('processar-nfe', async params => {
+hobots.register(async params => {
   hobots.log.info(`processando lote ${params.lote}…`);
   hobots.items.succeeded({ numero_nota: '123' }, { id: '123' });
   hobots.log.success('concluído'); // o retorno do handler é ignorado — reporte por log/itens

package/docs/api-reference.md

@@ -4,43 +4,47 @@
 
 | Import | Conteúdo |
 | --- | --- |
-| `hobots` | `hobots` (default e named), `register`, `start`, `close`, `captureException`, `retry` e os tipos. |
-| `hobots/protocol` | Tipos do wire format (telemetria e tasks). |
+| `hobots` | `hobots` (default e named), `register`, `start`, `close`, `captureException`, `retry`, `image` e os tipos. |
+| `hobots/protocol` | Tipos do wire format (telemetria e execuções). |
 
-ESM e CommonJS (`const { hobots } = require('hobots')`), com `.d.ts`. Depois da primeira task, `globalThis.hobots` também existe (tipado via `declare global`).
+ESM e CommonJS (`const { hobots } = require('hobots')`), com `.d.ts`. Depois do `register()`/`start()`, `globalThis.hobots` também existe (tipado via `declare global`).
 
 ## Funções do processo
 
 | Função | Assinatura | Notas |
 | --- | --- | --- |
-| `hobots.register` | `<P>(task: string, handler: TaskHandler<P>, options?: RegisterOptions) => void` | Task sob demanda. Síncrona: valida slug/handler/secret e lança na hora. O boot roda num microtask — chamadas seguidas entram no primeiro poll. Slug repetido lança. |
-| `hobots.start` | `(task: string, handler: TaskHandler, options?: StartOptions) => void` | Task sempre ligada: abre a própria execução e roda o handler uma vez. |
+| `hobots.register` | `<P>(handler: RunHandler<P>, options?: RegisterOptions) => void` | Agente sob demanda. Síncrona: valida handler/secret e lança na hora. O boot roda num microtask. **Uma chamada por processo** (register ou start) — a segunda lança `o agente já foi iniciado`. |
+| `hobots.start` | `(handler: RunHandler, options?: StartOptions) => void` | Agente sempre ligado: abre a própria execução e roda o handler uma vez. Mesma regra de uma chamada por processo. |
 | `hobots.close` | `(timeoutMs = 30_000) => Promise<boolean>` | Para o polling, espera as execuções em voo (até `timeoutMs`; as restantes viram `AgentTerminated`), para o heartbeat e faz o flush final. `false` se estourou. Um `register`/`start` depois inicia um runtime novo. |
-| `hobots.captureException` | `(error: unknown, hint?: CaptureHint) => string \| undefined` | Issue no módulo Issues; devolve o `event_id`. Antes de qualquer task: descarta com aviso. |
+| `hobots.captureException` | `(error: unknown, hint?: CaptureHint) => string \| undefined` | Issue no módulo Issues; devolve o `event_id`. Antes de iniciar o agente: descarta com aviso. |
 | `hobots.retry` | `<T>(fn: (attempt: number) => T \| Promise<T>, options?: RetryOptions) => Promise<T>` | async-retry; dentro de uma execução usa o signal dela. |
+| `hobots.image` | `(input: AttachInput, options?: ImageOptions) => ImageAttachment` | Embrulha um print para ir junto de um log, item ou step. Puro, nunca lança. |
 
 ## Contexto da execução (`RunContext` — os membros de `hobots` e o `ctx` do handler)
 
 | Membro | Tipo | Notas |
 | --- | --- | --- |
-| `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`); um `hobots.image(...)` no **último** argumento vira o print da linha |
+| `runId` | `string` | Identidade da execução (`''` fora de uma execução) |
+| `params` | `Record<string, unknown>` | Params da solicitação (formulário do agente); `{}` 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`); um `hobots.image(...)` no **último** argumento vira o print da linha. Eco no terminal: `[hobots] INFO …` |
 | `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?, { 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 |
+| `flush` | `(timeoutMs = 15_000) => Promise<void>` — envia já as steps raiz finalizadas (transactions parciais, op `hobots.run.flush`) e os itens/logs/progresso pendentes | Nunca lança |
+| `transaction` | `Transaction` (`run`, op `hobots.run`) — `startChild(op?, description?)`, `flush()`, `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 |
 | `retry(fn, options?)` | como `hobots.retry` | |
 
-`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.
+`AttachInput = Uint8Array \| ArrayBuffer \| string` (caminho); `ImageOptions = { caption?, contentType? }`; `ImageInput = AttachInput \| ImageAttachment` é o que `log.*` (só o embrulho), `items.*` e `step.setStatus/setError` aceitam. 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
 
-### `HobotsOptions` (processo — a primeira chamada define; divergências avisam e são ignoradas)
+Só há uma chamada por processo, então todas as opções são **do agente**. Os tipos se empilham: `HobotsOptions` (telemetria e identidade) → `RunOptions` (a execução) → `RegisterOptions` (só sob demanda); `StartOptions = RunOptions`.
+
+### `HobotsOptions` (telemetria, identidade, handlers globais)
 
 | Opção | Tipo | Default | Descrição |
 | --- | --- | --- | --- |
@@ -54,26 +58,26 @@ Fora de uma execução, `hobots.*` cai em fallbacks seguros com aviso único por
 | `captureUnhandled` | `boolean` | `true` | handlers globais de erro (issues) |
 | `installExitHandlers` | `boolean` | `true` | avançado — SIGINT/SIGTERM/uncaughtException reportam `AgentTerminated` |
 
-### `TaskOptions extends HobotsOptions` (por task)
+### `RunOptions extends HobotsOptions` (a execução — `register` e `start`)
 
 | Opção | Tipo | Default | Descrição |
 | --- | --- | --- | --- |
+| `items` | `ItemsOptions` = `{ columns: Array<string \| { key, label? }> }` | — | colunas da aba de itens no app (chaves do `payload` dos itens); até 12, chave `[a-zA-Z0-9_.-]`. Uma declaração só, do agente; independe de formulário; personalizar no app sobrepõe |
 | `retries` | `number` | `1` | tentativas extras do handler; `0` desliga |
 | `retryDelayMs` | `number \| (attempt) => number` | `5_000` | `attempt` 1-based (a que falhou) |
 | `timeoutMs` | `number` | — | por tentativa; terminal (`TaskTimeout`) |
 | `logFlushIntervalMs` | `number` | `2_000` | avançado |
 | `cancelCheckIntervalMs` | `number` | `5_000` (1_000..15_000) | avançado — PATCH vazio que detecta cancelamento e é o sinal de vida da execução |
 | `cancelGraceMs` | `number` | `10_000` | avançado — graça após o signal antes de liberar o slot |
-| `items` | `{ columns: Array<string \| { key, label? }> }` | — | colunas da aba de itens no app (chaves do `payload` dos itens); até 12, chave `[a-zA-Z0-9_.-]`. Independe de formulário; personalizar no app sobrepõe |
 
-### `RegisterOptions extends TaskOptions`
+### `RegisterOptions extends RunOptions` (só sob demanda)
 
 | Opção | Tipo | Default | Descrição |
 | --- | --- | --- | --- |
-| `concurrency` | `number` | `1` | execuções simultâneas desta task (1..5) |
-| `pollIntervalMs` | `number` | `2_000` (mín. 1_000) | intervalo entre polls sem trabalho; vale o do primeiro `register()` |
+| `concurrency` | `number` | `1` | execuções simultâneas do agente (1..5) |
+| `pollIntervalMs` | `number` | `2_000` (mín. 1_000) | intervalo entre polls sem trabalho |
 
-`StartOptions = TaskOptions`.
+`StartOptions = RunOptions`.
 
 ### `RetryOptions`
 
@@ -91,12 +95,22 @@ Fora de uma execução, `hobots.*` cai em fallbacks seguros com aviso único por
 | `tags`, `extra`, `fingerprint` | | metadados do evento (`fingerprint` sobrescreve o agrupamento) |
 | `attachment` | `ImageInput \| { image, caption?, contentType? }` | print anexado à linha de log da execução atual |
 
-### `TaskHandler`
+### `RunHandler`
 
 ```ts
-type TaskHandler<P = Record<string, unknown>> = (params: P, ctx: RunContext) => void | Promise<void>;
+type RunHandler<P = Record<string, unknown>> = (params: P, ctx: RunContext) => void | Promise<void>;
 ```
 
+### Tipos do wire que mudaram na 4.0
+
+| Tipo | O que é |
+| --- | --- |
+| `InstanceMode` | `'on_demand' \| 'always_on'` — como a instância trabalha (`register` / `start`) |
+| `ItemsDeclaration` | `{ attributes: ItemColumn[] }` — as colunas de itens declaradas pela opção `items` |
+| `InstanceInfo` | ganhou `mode?: InstanceMode` e `items?: ItemsDeclaration`; perdeu a lista de tasks e as colunas por task da 3.x |
+| `PollRequest` | `{ instance?, max? }` — sem lista de tasks |
+| `RunDescriptor` / `RunCreateRequest` | sem `task` |
+
 ## Tempos e intervalos
 
 | O quê | Valor |