hobots 2.0.1 → 2.3.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { Breadcrumb, EventUser, EventType, EventPayload, TransactionPayload, HeartbeatPayload, StepStatus, RunLogLevel, StepData, RunItemStatus, RunAttachmentContentType } from './protocol.cjs';
-export { BreadcrumbLevel, Envelope, EnvelopeItem, ExceptionData, InstanceInfo, PollRequest, PollResponse, RunAttachmentConfirmRequest, RunAttachmentConfirmResponse, RunAttachmentCreateRequest, RunAttachmentCreateResponse, RunDescriptor, RunError, RunItemInput, RunItemsCreateRequest, RunItemsCreateResponse, RunLogEntry, RunStatus, RunUpdateRequest, RunUpdateResponse, RunUpdateStatus, StackFrame } from './protocol.cjs';
+import { Breadcrumb, EventUser, EventType, MachineSnapshot, EventPayload, TransactionPayload, HeartbeatPayload, StepStatus, RunLogLevel, StepData, RunItemStatus, RunProgress, RunAttachmentContentType } from './protocol.cjs';
+export { BreadcrumbLevel, Envelope, EnvelopeItem, ExceptionData, InstanceInfo, MachineProcess, PollRequest, PollResponse, RunAttachmentConfirmRequest, RunAttachmentConfirmResponse, RunAttachmentCreateRequest, RunAttachmentCreateResponse, RunDescriptor, RunError, RunItemInput, RunItemsCreateRequest, RunItemsCreateResponse, RunLogEntry, RunStatus, RunUpdateRequest, RunUpdateResponse, RunUpdateStatus, StackFrame } from './protocol.cjs';
 
 /** Aceita tudo que o handler pode ter em mãos: bytes ou um caminho de arquivo (só Node). */
 type AttachInput = Uint8Array | ArrayBuffer | string;
@@ -47,15 +47,46 @@ interface Logger {
     error: (...args: unknown[]) => void;
 }
 
+/**
+ * Coleta CPU/memória/disco da máquina e do processo — só em Node (no browser é no-op).
+ *
+ * Os módulos `node:*` entram por import dinâmico (o bundle é `platform: neutral`), e
+ * `sample()` é síncrono e barato: `os.cpus()` + `statfsSync` + `process.memoryUsage()`.
+ * Nunca lança — telemetria de recurso não pode derrubar o bot nem o capture de um erro.
+ */
+declare class MachineSampler {
+    private readonly instanceId;
+    private readonly logger;
+    private os;
+    private fs;
+    private ready;
+    private prevCpu;
+    private prevProcessCpu;
+    private prevAt;
+    private lastCpuPercent;
+    private lastProcessCpuPercent;
+    constructor(instanceId: string, logger: Logger);
+    /** Carrega os módulos e tira a leitura-base de CPU (a primeira amostra ainda sai com cpu_percent null). */
+    start(): Promise<void>;
+    sample(): MachineSnapshot | undefined;
+    private cpuTotals;
+    /** Média desde a leitura anterior; leituras com menos de 1s de janela reutilizam a última média. */
+    private updateCpu;
+    private diskUsage;
+}
+
 declare class Client {
     #private;
     readonly logger: Logger;
     /** Eco de lifecycle (Transaction.emit) e afins só imprimem no terminal com debug ligado. */
     readonly debug: boolean;
     private readonly transport;
+    private machine;
     constructor(options: InitOptions, config?: ResolvedConfig);
     get options(): InitOptions;
     get config(): ResolvedConfig;
+    /** Sampler de recursos da máquina — cada evento passa a levar `contexts.machine`. */
+    attachMachineSampler(sampler: MachineSampler | undefined): void;
     /** Serialização explícita nunca inclui o secret. */
     toJSON(): Record<string, unknown>;
     captureException(error: unknown, hint: CaptureHint | undefined, scope: Scope): string;
@@ -198,6 +229,24 @@ interface RunItems {
     /** Ocorrência de negócio (ex.: "nota nº 10 não encontrada") — não é falha do bot. */
     occurrence(message: string, payload?: Record<string, unknown>, options?: RunItemOptions): void;
 }
+/**
+ * Progresso da execução (itens processados / total) — opcional e independente de
+ * `ctx.items`. Declare o total antes do loop e avance a cada item: a plataforma e o
+ * Studio mostram barra, percentual e tempo restante estimado. Sem `total()` nada é
+ * enviado. Chamadas são síncronas e baratas (≤ 1 PATCH/s, pegando carona nos logs).
+ */
+interface RunProgressReporter {
+    /** Declara (ou ajusta) o total de itens previsto — inteiro >= 1. Idempotente. */
+    total(total: number): void;
+    /** Incrementa os processados (padrão 1). Clampa em `total`. */
+    advance(count?: number): void;
+    /** Define o valor absoluto de processados e, opcionalmente, o total. */
+    set(current: number, total?: number): void;
+    /** Processados até agora (0 antes de qualquer chamada). */
+    readonly current: number;
+    /** `{ current, total }` quando há total declarado; null caso contrário. */
+    readonly snapshot: RunProgress | null;
+}
 interface RunContext {
     runId: string;
     task: string;
@@ -205,6 +254,8 @@ interface RunContext {
     log: RunLogger;
     /** Itens processados/gerados pela execução — a entrega do bot, com status e atributos */
     items: RunItems;
+    /** Progresso declarado (barra + ETA no app) — opcional, independente de `ctx.items` */
+    progress: RunProgressReporter;
     /**
      * Transaction de performance desta execução — já correlacionada à run e finalizada
      * automaticamente ao fim do handler. Use `ctx.tx.startChild(op, description)` pra medir
@@ -250,6 +301,12 @@ interface InitOptions {
     maxBreadcrumbs?: number;
     /** Registra handlers globais de erro (uncaughtException etc.). Default: true */
     captureUnhandled?: boolean;
+    /**
+     * Coleta CPU, memória, disco e recursos do processo: vai em cada heartbeat/poll (série da
+     * instância no app) e como `contexts.machine` em cada evento (como estava a máquina na hora
+     * do erro). Só em Node; sem custo de timer — pega carona no heartbeat. Default: true
+     */
+    machineMetrics?: boolean;
     /** Habilita heartbeat periódico (true usa defaults) */
     heartbeat?: boolean | HeartbeatOptions;
     /**
@@ -336,4 +393,4 @@ declare function close(timeoutMs?: number): Promise<boolean>;
 
 declare function scrubSecrets(text: string): string;
 
-export { type AttachInput, Breadcrumb, type BreadcrumbInput, type CaptureAttachment, type CaptureHint, Client, DEFAULT_BASE_URL, EventPayload, EventType, EventUser, type HeartbeatOptions, HeartbeatPayload, type InitOptions, RunAttachmentContentType, type RunContext, type RunItemOptions, RunItemStatus, type RunItems, RunLogLevel, Scope, Step, StepData, type TaskHandler, type TasksOptions, Transaction, TransactionPayload, addBreadcrumb, captureException, captureMessage, close, flush, getClient, init, register, scrubSecrets, setContext, setExtra, setTag, setTags, setUser, start, startTransaction, stop, withScope };
+export { type AttachInput, Breadcrumb, type BreadcrumbInput, type CaptureAttachment, type CaptureHint, Client, DEFAULT_BASE_URL, EventPayload, EventType, EventUser, type HeartbeatOptions, HeartbeatPayload, type InitOptions, MachineSnapshot, RunAttachmentContentType, type RunContext, type RunItemOptions, RunItemStatus, type RunItems, RunLogLevel, RunProgress, type RunProgressReporter, Scope, Step, StepData, type TaskHandler, type TasksOptions, Transaction, TransactionPayload, addBreadcrumb, captureException, captureMessage, close, flush, getClient, init, register, scrubSecrets, setContext, setExtra, setTag, setTags, setUser, start, startTransaction, stop, withScope };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { Breadcrumb, EventUser, EventType, EventPayload, TransactionPayload, HeartbeatPayload, StepStatus, RunLogLevel, StepData, RunItemStatus, RunAttachmentContentType } from './protocol.js';
-export { BreadcrumbLevel, Envelope, EnvelopeItem, ExceptionData, InstanceInfo, PollRequest, PollResponse, RunAttachmentConfirmRequest, RunAttachmentConfirmResponse, RunAttachmentCreateRequest, RunAttachmentCreateResponse, RunDescriptor, RunError, RunItemInput, RunItemsCreateRequest, RunItemsCreateResponse, RunLogEntry, RunStatus, RunUpdateRequest, RunUpdateResponse, RunUpdateStatus, StackFrame } from './protocol.js';
+import { Breadcrumb, EventUser, EventType, MachineSnapshot, EventPayload, TransactionPayload, HeartbeatPayload, StepStatus, RunLogLevel, StepData, RunItemStatus, RunProgress, RunAttachmentContentType } from './protocol.js';
+export { BreadcrumbLevel, Envelope, EnvelopeItem, ExceptionData, InstanceInfo, MachineProcess, PollRequest, PollResponse, RunAttachmentConfirmRequest, RunAttachmentConfirmResponse, RunAttachmentCreateRequest, RunAttachmentCreateResponse, RunDescriptor, RunError, RunItemInput, RunItemsCreateRequest, RunItemsCreateResponse, RunLogEntry, RunStatus, RunUpdateRequest, RunUpdateResponse, RunUpdateStatus, StackFrame } from './protocol.js';
 
 /** Aceita tudo que o handler pode ter em mãos: bytes ou um caminho de arquivo (só Node). */
 type AttachInput = Uint8Array | ArrayBuffer | string;
@@ -47,15 +47,46 @@ interface Logger {
     error: (...args: unknown[]) => void;
 }
 
+/**
+ * Coleta CPU/memória/disco da máquina e do processo — só em Node (no browser é no-op).
+ *
+ * Os módulos `node:*` entram por import dinâmico (o bundle é `platform: neutral`), e
+ * `sample()` é síncrono e barato: `os.cpus()` + `statfsSync` + `process.memoryUsage()`.
+ * Nunca lança — telemetria de recurso não pode derrubar o bot nem o capture de um erro.
+ */
+declare class MachineSampler {
+    private readonly instanceId;
+    private readonly logger;
+    private os;
+    private fs;
+    private ready;
+    private prevCpu;
+    private prevProcessCpu;
+    private prevAt;
+    private lastCpuPercent;
+    private lastProcessCpuPercent;
+    constructor(instanceId: string, logger: Logger);
+    /** Carrega os módulos e tira a leitura-base de CPU (a primeira amostra ainda sai com cpu_percent null). */
+    start(): Promise<void>;
+    sample(): MachineSnapshot | undefined;
+    private cpuTotals;
+    /** Média desde a leitura anterior; leituras com menos de 1s de janela reutilizam a última média. */
+    private updateCpu;
+    private diskUsage;
+}
+
 declare class Client {
     #private;
     readonly logger: Logger;
     /** Eco de lifecycle (Transaction.emit) e afins só imprimem no terminal com debug ligado. */
     readonly debug: boolean;
     private readonly transport;
+    private machine;
     constructor(options: InitOptions, config?: ResolvedConfig);
     get options(): InitOptions;
     get config(): ResolvedConfig;
+    /** Sampler de recursos da máquina — cada evento passa a levar `contexts.machine`. */
+    attachMachineSampler(sampler: MachineSampler | undefined): void;
     /** Serialização explícita nunca inclui o secret. */
     toJSON(): Record<string, unknown>;
     captureException(error: unknown, hint: CaptureHint | undefined, scope: Scope): string;
@@ -198,6 +229,24 @@ interface RunItems {
     /** Ocorrência de negócio (ex.: "nota nº 10 não encontrada") — não é falha do bot. */
     occurrence(message: string, payload?: Record<string, unknown>, options?: RunItemOptions): void;
 }
+/**
+ * Progresso da execução (itens processados / total) — opcional e independente de
+ * `ctx.items`. Declare o total antes do loop e avance a cada item: a plataforma e o
+ * Studio mostram barra, percentual e tempo restante estimado. Sem `total()` nada é
+ * enviado. Chamadas são síncronas e baratas (≤ 1 PATCH/s, pegando carona nos logs).
+ */
+interface RunProgressReporter {
+    /** Declara (ou ajusta) o total de itens previsto — inteiro >= 1. Idempotente. */
+    total(total: number): void;
+    /** Incrementa os processados (padrão 1). Clampa em `total`. */
+    advance(count?: number): void;
+    /** Define o valor absoluto de processados e, opcionalmente, o total. */
+    set(current: number, total?: number): void;
+    /** Processados até agora (0 antes de qualquer chamada). */
+    readonly current: number;
+    /** `{ current, total }` quando há total declarado; null caso contrário. */
+    readonly snapshot: RunProgress | null;
+}
 interface RunContext {
     runId: string;
     task: string;
@@ -205,6 +254,8 @@ interface RunContext {
     log: RunLogger;
     /** Itens processados/gerados pela execução — a entrega do bot, com status e atributos */
     items: RunItems;
+    /** Progresso declarado (barra + ETA no app) — opcional, independente de `ctx.items` */
+    progress: RunProgressReporter;
     /**
      * Transaction de performance desta execução — já correlacionada à run e finalizada
      * automaticamente ao fim do handler. Use `ctx.tx.startChild(op, description)` pra medir
@@ -250,6 +301,12 @@ interface InitOptions {
     maxBreadcrumbs?: number;
     /** Registra handlers globais de erro (uncaughtException etc.). Default: true */
     captureUnhandled?: boolean;
+    /**
+     * Coleta CPU, memória, disco e recursos do processo: vai em cada heartbeat/poll (série da
+     * instância no app) e como `contexts.machine` em cada evento (como estava a máquina na hora
+     * do erro). Só em Node; sem custo de timer — pega carona no heartbeat. Default: true
+     */
+    machineMetrics?: boolean;
     /** Habilita heartbeat periódico (true usa defaults) */
     heartbeat?: boolean | HeartbeatOptions;
     /**
@@ -336,4 +393,4 @@ declare function close(timeoutMs?: number): Promise<boolean>;
 
 declare function scrubSecrets(text: string): string;
 
-export { type AttachInput, Breadcrumb, type BreadcrumbInput, type CaptureAttachment, type CaptureHint, Client, DEFAULT_BASE_URL, EventPayload, EventType, EventUser, type HeartbeatOptions, HeartbeatPayload, type InitOptions, RunAttachmentContentType, type RunContext, type RunItemOptions, RunItemStatus, type RunItems, RunLogLevel, Scope, Step, StepData, type TaskHandler, type TasksOptions, Transaction, TransactionPayload, addBreadcrumb, captureException, captureMessage, close, flush, getClient, init, register, scrubSecrets, setContext, setExtra, setTag, setTags, setUser, start, startTransaction, stop, withScope };
+export { type AttachInput, Breadcrumb, type BreadcrumbInput, type CaptureAttachment, type CaptureHint, Client, DEFAULT_BASE_URL, EventPayload, EventType, EventUser, type HeartbeatOptions, HeartbeatPayload, type InitOptions, MachineSnapshot, RunAttachmentContentType, type RunContext, type RunItemOptions, RunItemStatus, type RunItems, RunLogLevel, RunProgress, type RunProgressReporter, Scope, Step, StepData, type TaskHandler, type TasksOptions, Transaction, TransactionPayload, addBreadcrumb, captureException, captureMessage, close, flush, getClient, init, register, scrubSecrets, setContext, setExtra, setTag, setTags, setUser, start, startTransaction, stop, withScope };