hobots 3.4.0 → 4.0.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import { RunAttachmentContentType, EventType, EnvironmentInput, MachineSnapshot, EventPayload, TransactionPayload, HeartbeatPayload, StepStatus, RunLogLevel, StepData, RunItemStatus, RunProgress } from './protocol.cjs';
-export { Breadcrumb, BreadcrumbLevel, Envelope, EnvelopeItem, Environment, EventUser, ExceptionData, InstanceInfo, ItemColumn, MachineProcess, PollRequest, PollResponse, RunAttachmentConfirmRequest, RunAttachmentConfirmResponse, RunAttachmentCreateRequest, RunAttachmentCreateResponse, RunCreateRequest, RunCreateResponse, RunDescriptor, RunError, RunItemInput, RunItemsCreateRequest, RunItemsCreateResponse, RunLogEntry, RunStatus, RunUpdateRequest, RunUpdateResponse, RunUpdateStatus, StackFrame, TaskItemsDeclaration } from './protocol.cjs';
+export { Breadcrumb, BreadcrumbLevel, Envelope, EnvelopeItem, Environment, EventUser, ExceptionData, InstanceInfo, InstanceMode, ItemColumn, ItemsDeclaration, MachineProcess, PollRequest, PollResponse, RunAttachmentConfirmRequest, RunAttachmentConfirmResponse, RunAttachmentCreateRequest, RunAttachmentCreateResponse, RunCreateRequest, RunCreateResponse, RunDescriptor, RunError, RunItemInput, RunItemsCreateRequest, RunItemsCreateResponse, RunLogEntry, RunStatus, RunUpdateRequest, RunUpdateResponse, RunUpdateStatus, StackFrame } from './protocol.cjs';
 
 /** Espera entre tentativas: ms fixo ou função do número da tentativa que acabou de falhar (1-based). */
 type RetryDelay = number | ((attempt: number) => number);
@@ -57,7 +57,7 @@ interface HobotsOptions {
     clientSecret?: string;
     /**
      * Identificador único e estável desta instância — a identidade do agente no painel
-     * (heartbeat e tasks convergem nele). Default: env HOBOTS_INSTANCE_ID; sem ela, o hostname.
+     * (heartbeat e execuções convergem nele). Default: env HOBOTS_INSTANCE_ID; sem ela, o hostname.
      */
     instanceId?: string;
     /**
@@ -88,11 +88,11 @@ interface HobotsOptions {
     installExitHandlers?: boolean;
 }
 /** Colunas de itens declaradas no código (até 12; chave: letras, números, `.`, `-`, `_`). */
-interface TaskItemsOptions {
+interface ItemsOptions {
     columns: ItemColumnInput[];
 }
-/** Opções de uma task (register ou start). */
-interface TaskOptions extends HobotsOptions {
+/** Opções da execução do agente (register ou start). */
+interface RunOptions extends HobotsOptions {
     /**
      * Colunas da aba "itens" da execução na plataforma: chaves do `payload` que cada
      * item reportado (`ctx.items.*`) carrega, com rótulo opcional. Independe de
@@ -100,7 +100,7 @@ interface TaskOptions extends HobotsOptions {
      * (Configurações → agente) sobrepõe o que for declarado aqui.
      * Ex.: `{ columns: ['numero_nota', { key: 'valor', label: 'valor (R$)' }] }`
      */
-    items?: TaskItemsOptions;
+    items?: ItemsOptions;
     /**
      * Tentativas extras do handler quando ele lança, na mesma run (itens e progresso já
      * enviados permanecem — escreva handlers idempotentes). Cancelamento e timeout nunca
@@ -128,15 +128,15 @@ interface TaskOptions extends HobotsOptions {
      */
     cancelGraceMs?: number;
 }
-/** Opções de `register()` — task executada sob demanda, a partir das solicitações do app. */
-interface RegisterOptions extends TaskOptions {
-    /** Runs simultâneas desta task (1..5). Default: 1 (sequencial) */
+/** Opções de `register()` — agente sob demanda, executado a partir das solicitações do app. */
+interface RegisterOptions extends RunOptions {
+    /** Runs simultâneas do agente (1..5). Default: 1 (sequencial) */
     concurrency?: number;
-    /** Intervalo entre polls sem trabalho (mínimo 1_000). Vale o do primeiro register(). Default: 2_000 */
+    /** Intervalo entre polls sem trabalho (mínimo 1_000). Default: 2_000 */
     pollIntervalMs?: number;
 }
-/** Opções de `start()` — task que roda sempre, aberta pelo próprio bot. */
-type StartOptions = TaskOptions;
+/** Opções de `start()` — agente sempre ligado, que abre a própria run. */
+type StartOptions = RunOptions;
 /** Imagem enviada junto de um captureException — com legenda e content-type opcionais. */
 interface CaptureAttachment {
     /** Bytes (`Uint8Array`/`ArrayBuffer`/`Buffer`) ou um caminho de arquivo (só em Node) */
@@ -170,8 +170,8 @@ interface ResolvedConfig {
     baseUrl: string;
     /** Ingestão de telemetria: <baseUrl>/v1/ingest */
     ingestEndpoint: string;
-    /** API de tasks (execução sob demanda): <baseUrl>/v1/tasks */
-    tasksBaseUrl: string;
+    /** API de execuções (poll, runs, itens, anexos): <baseUrl>/v1/runs */
+    runsBaseUrl: string;
 }
 
 /**
@@ -299,7 +299,7 @@ declare class Transaction {
     private readonly client;
     name: string;
     readonly op?: string | undefined;
-    /** Correlaciona a uma execução de task — preenchido automaticamente em hobots.transaction */
+    /** Correlaciona a uma execução do agente — preenchido automaticamente em hobots.transaction */
     private readonly runId?;
     readonly eventId: string;
     readonly stepId: string;
@@ -314,7 +314,7 @@ declare class Transaction {
     private stepGuard?;
     private lifecycleBacklog;
     constructor(client: Client | undefined, name: string, op?: string | undefined, 
-    /** Correlaciona a uma execução de task — preenchido automaticamente em hobots.transaction */
+    /** Correlaciona a uma execução do agente — preenchido automaticamente em hobots.transaction */
     runId?: string | undefined);
     /**
      * Registra o início/fim de uma step ou transaction: espelha a linha no sink de
@@ -475,7 +475,6 @@ interface RunProgressReporter {
  */
 interface RunContext {
     readonly runId: string;
-    readonly task: string;
     /** Params da solicitação (formulário do app); `{}` no modo start */
     readonly params: Record<string, unknown>;
     /** Log bufferizado — enviado ao servidor em PATCHes incrementais com throttle. Nunca lança. */
@@ -503,7 +502,7 @@ interface RunContext {
     retry<T>(fn: (attempt: number) => T | Promise<T>, options?: RetryOptions): Promise<T>;
 }
 /** O retorno do handler é ignorado — nada além de status/logs/erro é enviado ao servidor. */
-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>;
 
 /**
  * O objeto global do SDK: as funções do processo (register/start/close/captureException/
@@ -511,10 +510,13 @@ type TaskHandler<P = Record<string, unknown>> = (params: P, ctx: RunContext) =>
  * resolvido a cada acesso — funciona de qualquer módulo, sem passar `ctx` de mão em mão.
  */
 interface Hobots extends RunContext {
-    /** Task sob demanda: executada a cada solicitação do app (formulário/agendamento) via polling. */
-    register<P = Record<string, unknown>>(task: string, handler: TaskHandler<P>, options?: RegisterOptions): void;
-    /** Task sempre-ligada: o bot abre a própria run e roda o handler; a plataforma recebe logs, itens e progresso. */
-    start(task: string, handler: TaskHandler, options?: StartOptions): void;
+    /**
+     * Agente sob demanda: o handler roda a cada solicitação do app (formulário/agendamento), via polling.
+     * O agente é a própria tarefa: uma chamada por processo (register OU start).
+     */
+    register<P = Record<string, unknown>>(handler: RunHandler<P>, options?: RegisterOptions): void;
+    /** Agente sempre ligado: abre a própria run e roda o handler; a plataforma recebe logs, itens e progresso. */
+    start(handler: RunHandler, options?: StartOptions): void;
     /** Encerra tudo (polling, runs em voo, heartbeat, flush final). Chame antes do processo terminar. */
     close(timeoutMs?: number): Promise<boolean>;
     /** Captura uma exceção como issue (módulo Issues). Retorna o event_id. */
@@ -530,11 +532,11 @@ declare global {
     var hobots: Hobots;
 }
 declare const hobots: Hobots;
-declare const register: <P = Record<string, unknown>>(task: string, handler: TaskHandler<P>, options?: RegisterOptions) => void;
-declare const start: (task: string, handler: TaskHandler, options?: StartOptions) => void;
+declare const register: <P = Record<string, unknown>>(handler: RunHandler<P>, options?: RegisterOptions) => void;
+declare const start: (handler: RunHandler, options?: StartOptions) => void;
 declare const close: (timeoutMs?: number) => Promise<boolean>;
 declare const captureException: (error: unknown, hint?: CaptureHint) => string | undefined;
 declare const retry: <T>(fn: (attempt: number) => T | Promise<T>, options?: RetryOptions) => Promise<T>;
 declare const image: (input: AttachInput, options?: ImageOptions) => ImageAttachment;
 
-export { type AttachInput, type CaptureAttachment, type CaptureHint, EnvironmentInput, EventPayload, EventType, HeartbeatPayload, type Hobots, type HobotsOptions, ImageAttachment, type ImageInput, type ImageOptions, type ItemColumnInput, MachineSnapshot, type RegisterOptions, type RetryDelay, type RetryOptions, RunAttachmentContentType, type RunContext, type RunItemHandle, type RunItemImageOptions, type RunItemOptions, RunItemStatus, type RunItems, type RunItemsEachHandler, type RunItemsEachOptions, type RunItemsEachResult, RunLogLevel, type RunLogger, RunProgress, type RunProgressReporter, type StartOptions, Step, StepData, type StepOutcomeOptions, StepStatus, type TaskHandler, type TaskItemsOptions, type TaskOptions, Transaction, TransactionPayload, captureException, close, hobots as default, hobots, image, register, retry, start };
+export { type AttachInput, type CaptureAttachment, type CaptureHint, EnvironmentInput, EventPayload, EventType, HeartbeatPayload, type Hobots, type HobotsOptions, ImageAttachment, type ImageInput, type ImageOptions, type ItemColumnInput, type ItemsOptions, MachineSnapshot, type RegisterOptions, type RetryDelay, type RetryOptions, RunAttachmentContentType, type RunContext, type RunHandler, type RunItemHandle, type RunItemImageOptions, type RunItemOptions, RunItemStatus, type RunItems, type RunItemsEachHandler, type RunItemsEachOptions, type RunItemsEachResult, RunLogLevel, type RunLogger, type RunOptions, RunProgress, type RunProgressReporter, type StartOptions, Step, StepData, type StepOutcomeOptions, StepStatus, Transaction, TransactionPayload, captureException, close, hobots as default, hobots, image, register, retry, start };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { RunAttachmentContentType, EventType, EnvironmentInput, MachineSnapshot, EventPayload, TransactionPayload, HeartbeatPayload, StepStatus, RunLogLevel, StepData, RunItemStatus, RunProgress } from './protocol.js';
-export { Breadcrumb, BreadcrumbLevel, Envelope, EnvelopeItem, Environment, EventUser, ExceptionData, InstanceInfo, ItemColumn, MachineProcess, PollRequest, PollResponse, RunAttachmentConfirmRequest, RunAttachmentConfirmResponse, RunAttachmentCreateRequest, RunAttachmentCreateResponse, RunCreateRequest, RunCreateResponse, RunDescriptor, RunError, RunItemInput, RunItemsCreateRequest, RunItemsCreateResponse, RunLogEntry, RunStatus, RunUpdateRequest, RunUpdateResponse, RunUpdateStatus, StackFrame, TaskItemsDeclaration } from './protocol.js';
+export { Breadcrumb, BreadcrumbLevel, Envelope, EnvelopeItem, Environment, EventUser, ExceptionData, InstanceInfo, InstanceMode, ItemColumn, ItemsDeclaration, MachineProcess, PollRequest, PollResponse, RunAttachmentConfirmRequest, RunAttachmentConfirmResponse, RunAttachmentCreateRequest, RunAttachmentCreateResponse, RunCreateRequest, RunCreateResponse, RunDescriptor, RunError, RunItemInput, RunItemsCreateRequest, RunItemsCreateResponse, RunLogEntry, RunStatus, RunUpdateRequest, RunUpdateResponse, RunUpdateStatus, StackFrame } from './protocol.js';
 
 /** Espera entre tentativas: ms fixo ou função do número da tentativa que acabou de falhar (1-based). */
 type RetryDelay = number | ((attempt: number) => number);
@@ -57,7 +57,7 @@ interface HobotsOptions {
     clientSecret?: string;
     /**
      * Identificador único e estável desta instância — a identidade do agente no painel
-     * (heartbeat e tasks convergem nele). Default: env HOBOTS_INSTANCE_ID; sem ela, o hostname.
+     * (heartbeat e execuções convergem nele). Default: env HOBOTS_INSTANCE_ID; sem ela, o hostname.
      */
     instanceId?: string;
     /**
@@ -88,11 +88,11 @@ interface HobotsOptions {
     installExitHandlers?: boolean;
 }
 /** Colunas de itens declaradas no código (até 12; chave: letras, números, `.`, `-`, `_`). */
-interface TaskItemsOptions {
+interface ItemsOptions {
     columns: ItemColumnInput[];
 }
-/** Opções de uma task (register ou start). */
-interface TaskOptions extends HobotsOptions {
+/** Opções da execução do agente (register ou start). */
+interface RunOptions extends HobotsOptions {
     /**
      * Colunas da aba "itens" da execução na plataforma: chaves do `payload` que cada
      * item reportado (`ctx.items.*`) carrega, com rótulo opcional. Independe de
@@ -100,7 +100,7 @@ interface TaskOptions extends HobotsOptions {
      * (Configurações → agente) sobrepõe o que for declarado aqui.
      * Ex.: `{ columns: ['numero_nota', { key: 'valor', label: 'valor (R$)' }] }`
      */
-    items?: TaskItemsOptions;
+    items?: ItemsOptions;
     /**
      * Tentativas extras do handler quando ele lança, na mesma run (itens e progresso já
      * enviados permanecem — escreva handlers idempotentes). Cancelamento e timeout nunca
@@ -128,15 +128,15 @@ interface TaskOptions extends HobotsOptions {
      */
     cancelGraceMs?: number;
 }
-/** Opções de `register()` — task executada sob demanda, a partir das solicitações do app. */
-interface RegisterOptions extends TaskOptions {
-    /** Runs simultâneas desta task (1..5). Default: 1 (sequencial) */
+/** Opções de `register()` — agente sob demanda, executado a partir das solicitações do app. */
+interface RegisterOptions extends RunOptions {
+    /** Runs simultâneas do agente (1..5). Default: 1 (sequencial) */
     concurrency?: number;
-    /** Intervalo entre polls sem trabalho (mínimo 1_000). Vale o do primeiro register(). Default: 2_000 */
+    /** Intervalo entre polls sem trabalho (mínimo 1_000). Default: 2_000 */
     pollIntervalMs?: number;
 }
-/** Opções de `start()` — task que roda sempre, aberta pelo próprio bot. */
-type StartOptions = TaskOptions;
+/** Opções de `start()` — agente sempre ligado, que abre a própria run. */
+type StartOptions = RunOptions;
 /** Imagem enviada junto de um captureException — com legenda e content-type opcionais. */
 interface CaptureAttachment {
     /** Bytes (`Uint8Array`/`ArrayBuffer`/`Buffer`) ou um caminho de arquivo (só em Node) */
@@ -170,8 +170,8 @@ interface ResolvedConfig {
     baseUrl: string;
     /** Ingestão de telemetria: <baseUrl>/v1/ingest */
     ingestEndpoint: string;
-    /** API de tasks (execução sob demanda): <baseUrl>/v1/tasks */
-    tasksBaseUrl: string;
+    /** API de execuções (poll, runs, itens, anexos): <baseUrl>/v1/runs */
+    runsBaseUrl: string;
 }
 
 /**
@@ -299,7 +299,7 @@ declare class Transaction {
     private readonly client;
     name: string;
     readonly op?: string | undefined;
-    /** Correlaciona a uma execução de task — preenchido automaticamente em hobots.transaction */
+    /** Correlaciona a uma execução do agente — preenchido automaticamente em hobots.transaction */
     private readonly runId?;
     readonly eventId: string;
     readonly stepId: string;
@@ -314,7 +314,7 @@ declare class Transaction {
     private stepGuard?;
     private lifecycleBacklog;
     constructor(client: Client | undefined, name: string, op?: string | undefined, 
-    /** Correlaciona a uma execução de task — preenchido automaticamente em hobots.transaction */
+    /** Correlaciona a uma execução do agente — preenchido automaticamente em hobots.transaction */
     runId?: string | undefined);
     /**
      * Registra o início/fim de uma step ou transaction: espelha a linha no sink de
@@ -475,7 +475,6 @@ interface RunProgressReporter {
  */
 interface RunContext {
     readonly runId: string;
-    readonly task: string;
     /** Params da solicitação (formulário do app); `{}` no modo start */
     readonly params: Record<string, unknown>;
     /** Log bufferizado — enviado ao servidor em PATCHes incrementais com throttle. Nunca lança. */
@@ -503,7 +502,7 @@ interface RunContext {
     retry<T>(fn: (attempt: number) => T | Promise<T>, options?: RetryOptions): Promise<T>;
 }
 /** O retorno do handler é ignorado — nada além de status/logs/erro é enviado ao servidor. */
-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>;
 
 /**
  * O objeto global do SDK: as funções do processo (register/start/close/captureException/
@@ -511,10 +510,13 @@ type TaskHandler<P = Record<string, unknown>> = (params: P, ctx: RunContext) =>
  * resolvido a cada acesso — funciona de qualquer módulo, sem passar `ctx` de mão em mão.
  */
 interface Hobots extends RunContext {
-    /** Task sob demanda: executada a cada solicitação do app (formulário/agendamento) via polling. */
-    register<P = Record<string, unknown>>(task: string, handler: TaskHandler<P>, options?: RegisterOptions): void;
-    /** Task sempre-ligada: o bot abre a própria run e roda o handler; a plataforma recebe logs, itens e progresso. */
-    start(task: string, handler: TaskHandler, options?: StartOptions): void;
+    /**
+     * Agente sob demanda: o handler roda a cada solicitação do app (formulário/agendamento), via polling.
+     * O agente é a própria tarefa: uma chamada por processo (register OU start).
+     */
+    register<P = Record<string, unknown>>(handler: RunHandler<P>, options?: RegisterOptions): void;
+    /** Agente sempre ligado: abre a própria run e roda o handler; a plataforma recebe logs, itens e progresso. */
+    start(handler: RunHandler, options?: StartOptions): void;
     /** Encerra tudo (polling, runs em voo, heartbeat, flush final). Chame antes do processo terminar. */
     close(timeoutMs?: number): Promise<boolean>;
     /** Captura uma exceção como issue (módulo Issues). Retorna o event_id. */
@@ -530,11 +532,11 @@ declare global {
     var hobots: Hobots;
 }
 declare const hobots: Hobots;
-declare const register: <P = Record<string, unknown>>(task: string, handler: TaskHandler<P>, options?: RegisterOptions) => void;
-declare const start: (task: string, handler: TaskHandler, options?: StartOptions) => void;
+declare const register: <P = Record<string, unknown>>(handler: RunHandler<P>, options?: RegisterOptions) => void;
+declare const start: (handler: RunHandler, options?: StartOptions) => void;
 declare const close: (timeoutMs?: number) => Promise<boolean>;
 declare const captureException: (error: unknown, hint?: CaptureHint) => string | undefined;
 declare const retry: <T>(fn: (attempt: number) => T | Promise<T>, options?: RetryOptions) => Promise<T>;
 declare const image: (input: AttachInput, options?: ImageOptions) => ImageAttachment;
 
-export { type AttachInput, type CaptureAttachment, type CaptureHint, EnvironmentInput, EventPayload, EventType, HeartbeatPayload, type Hobots, type HobotsOptions, ImageAttachment, type ImageInput, type ImageOptions, type ItemColumnInput, MachineSnapshot, type RegisterOptions, type RetryDelay, type RetryOptions, RunAttachmentContentType, type RunContext, type RunItemHandle, type RunItemImageOptions, type RunItemOptions, RunItemStatus, type RunItems, type RunItemsEachHandler, type RunItemsEachOptions, type RunItemsEachResult, RunLogLevel, type RunLogger, RunProgress, type RunProgressReporter, type StartOptions, Step, StepData, type StepOutcomeOptions, StepStatus, type TaskHandler, type TaskItemsOptions, type TaskOptions, Transaction, TransactionPayload, captureException, close, hobots as default, hobots, image, register, retry, start };
+export { type AttachInput, type CaptureAttachment, type CaptureHint, EnvironmentInput, EventPayload, EventType, HeartbeatPayload, type Hobots, type HobotsOptions, ImageAttachment, type ImageInput, type ImageOptions, type ItemColumnInput, type ItemsOptions, MachineSnapshot, type RegisterOptions, type RetryDelay, type RetryOptions, RunAttachmentContentType, type RunContext, type RunHandler, type RunItemHandle, type RunItemImageOptions, type RunItemOptions, RunItemStatus, type RunItems, type RunItemsEachHandler, type RunItemsEachOptions, type RunItemsEachResult, RunLogLevel, type RunLogger, type RunOptions, RunProgress, type RunProgressReporter, type StartOptions, Step, StepData, type StepOutcomeOptions, StepStatus, Transaction, TransactionPayload, captureException, close, hobots as default, hobots, image, register, retry, start };