hobots 2.4.0 → 3.0.0

package/dist/index.d.ts

@@ -1,11 +1,145 @@
-import { Breadcrumb, EventUser, EventType, MachineSnapshot, EventPayload, TransactionPayload, HeartbeatPayload, StepStatus, RunLogLevel, StepData, RunItemStatus, RunProgress, RunAttachmentContentType, EnvironmentInput } 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';
+import { RunLogLevel, RunAttachmentContentType, EventType, EnvironmentInput, MachineSnapshot, EventPayload, TransactionPayload, HeartbeatPayload, StepStatus, StepData, RunItemStatus, RunProgress } from './protocol.js';
+export { Breadcrumb, BreadcrumbLevel, Envelope, EnvelopeItem, Environment, EventUser, ExceptionData, InstanceInfo, 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);
+interface RetryOptions {
+    /** Tentativas extras depois da primeira falha. Default: 3 */
+    retries?: number;
+    /** Espera entre tentativas. Default: 1_000 */
+    delayMs?: RetryDelay;
+    /** Filtro adicional: retorne false para desistir na hora. Cancelamento e timeout nunca são re-tentados. */
+    shouldRetry?: (error: unknown) => boolean;
+}
+
+interface AttachOptions {
+    /** Legenda curta, exibida sob a miniatura no app. Passa pelo scrub de segredos. */
+    caption?: string;
+    /** Nível da linha de log que carrega o anexo. Default: 'info' */
+    level?: RunLogLevel;
+    /** Texto da linha de log. Default: a legenda, ou 'captura de tela' */
+    message?: string;
+    /** Informe quando os magic bytes não bastarem (o SDK sempre prefere o que detectar). */
+    contentType?: RunAttachmentContentType;
+}
+type AttachFailureReason = 
+/** A instalação do Hobots não tem anexos habilitados (ou a API é anterior ao recurso) */
+'unsupported' | 'too-large' | 'quota' | 'read-failed'
+/** Formato não reconhecido ou fora de PNG/JPEG/WEBP */
+ | 'unsupported-format' | 'upload-failed' | 'canceled';
+interface AttachResult {
+    /** Id do anexo, o mesmo referenciado na linha de log */
+    id: string;
+    ok: boolean;
+    /** Motivo do insucesso — para diagnóstico; `attach` nunca lança */
+    reason?: AttachFailureReason;
+}
 /** Aceita tudo que o handler pode ter em mãos: bytes ou um caminho de arquivo (só Node). */
 type AttachInput = Uint8Array | ArrayBuffer | string;
 
-/** API oficial da Hobots — o SDK sempre fala com ela em produção. */
-declare const DEFAULT_BASE_URL = "https://api2.hobots.app";
+/**
+ * Opções do processo (telemetria, identidade, handlers globais). Valem as da PRIMEIRA
+ * chamada a register()/start(); chamadas seguintes com valores diferentes avisam e são ignoradas.
+ */
+interface HobotsOptions {
+    /** Client Secret do agente (hb_…). Default: env HOBOTS_CLIENT_SECRET. Copie em Configurações → Agentes. */
+    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.
+     */
+    instanceId?: string;
+    /**
+     * Ambiente lógico onde este robô roda: 'development', 'testing', 'staging' ou
+     * 'production'. Vai em todo evento, transaction e na identidade da instância — é por
+     * ele que as regras de alerta decidem se notificam. Default: 'production'.
+     */
+    environment?: EnvironmentInput;
+    /** Versão do programa, ex.: 'robo-nfe@1.4.2' */
+    release?: string;
+    /** Tags aplicadas a todos os eventos */
+    tags?: Record<string, string>;
+    /** Loga atividade do SDK no console */
+    debug?: 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. Só em Node. Default: true
+     */
+    machineMetrics?: boolean;
+    /** Registra handlers globais de erro (uncaughtException etc.) que abrem issues. Default: true */
+    captureUnhandled?: boolean;
+    /**
+     * Avançado. Instala handlers de SIGINT/SIGTERM/uncaughtException que reportam as runs
+     * ativas como falha (AgentTerminated) antes do processo morrer. Nunca interfere quando
+     * o programa tem handler próprio para o sinal. Default: true
+     */
+    installExitHandlers?: boolean;
+}
+/** Opções de uma task (register ou start). */
+interface TaskOptions extends HobotsOptions {
+    /**
+     * Tentativas extras do handler quando ele lança, na mesma run (itens e progresso já
+     * enviados permanecem — escreva handlers idempotentes). Cancelamento e timeout nunca
+     * são re-tentados. Default: 1 (tenta 2 vezes no total); 0 desliga.
+     */
+    retries?: number;
+    /** Espera entre tentativas: ms fixo ou função da tentativa que falhou (1-based). Default: 5_000 */
+    retryDelayMs?: RetryDelay;
+    /**
+     * Timeout client-side por tentativa. O handler não é morto — a run é reportada como
+     * falha (TaskTimeout, terminal) e o slot é liberado. Default: sem timeout.
+     */
+    timeoutMs?: number;
+    /** Avançado. Intervalo do flush incremental de logs. Default: 2_000 */
+    logFlushIntervalMs?: number;
+    /**
+     * Avançado. Intervalo do heartbeat de cancelamento por run: um PATCH vazio que detecta
+     * runs canceladas no app e dispara o signal mesmo sem logs. Esse mesmo PATCH é o sinal
+     * de vida da run no servidor. Default: 5_000 (mínimo 1_000, máximo 15_000)
+     */
+    cancelCheckIntervalMs?: number;
+    /**
+     * Avançado. Tempo de graça após o signal disparar (run cancelada no app) antes do
+     * SDK desistir de esperar o handler e liberar o slot. Default: 10_000
+     */
+    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) */
+    concurrency?: number;
+    /** Intervalo entre polls sem trabalho (mínimo 1_000). Vale o do primeiro register(). Default: 2_000 */
+    pollIntervalMs?: number;
+}
+/** Opções de `start()` — task que roda sempre, aberta pelo próprio bot. */
+type StartOptions = TaskOptions;
+/** 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) */
+    image: AttachInput;
+    /** Legenda curta, exibida sob a miniatura no app. Passa pelo scrub de segredos. */
+    caption?: string;
+    /** Informe quando os magic bytes não bastarem (o SDK sempre prefere o que detectar). */
+    contentType?: RunAttachmentContentType;
+}
+interface CaptureHint {
+    type?: EventType;
+    tags?: Record<string, string>;
+    extra?: Record<string, unknown>;
+    fingerprint?: string[];
+    /**
+     * Print da tela enviado junto da captura. Dentro de uma execução, a imagem vira anexo
+     * da linha de log que espelha o evento — miniatura na aba "logs do agente". Fora de uma
+     * execução não há onde pendurar a imagem: o SDK descarta com um aviso. O upload roda
+     * em segundo plano e **nunca bloqueia nem lança**. PNG, JPEG ou WEBP, até 5 MB, 20 por execução.
+     *
+     * ```ts
+     * hobots.captureException(error, { attachment: { image: await page.screenshot(), caption: 'tela no momento do erro' } });
+     * ```
+     */
+    attachment?: AttachInput | CaptureAttachment;
+}
+
 interface ResolvedConfig {
     /** Client Secret do agente (enviado como Authorization: Bearer, nunca na URL) */
     key: string;
@@ -16,31 +150,6 @@ interface ResolvedConfig {
     tasksBaseUrl: string;
 }
 
-type BreadcrumbInput = Omit<Breadcrumb, 'timestamp'> & {
-    timestamp?: string;
-};
-/** Estado contextual anexado aos eventos: tags, usuário, contexts, extras e breadcrumbs. */
-declare class Scope {
-    tags: Record<string, string>;
-    user?: EventUser;
-    contexts: Record<string, Record<string, unknown>>;
-    extra: Record<string, unknown>;
-    type?: EventType;
-    fingerprint?: string[];
-    breadcrumbs: Breadcrumb[];
-    setTag(key: string, value: string): this;
-    setTags(tags: Record<string, string>): this;
-    setUser(user: EventUser | null): this;
-    setContext(name: string, context: Record<string, unknown> | null): this;
-    setExtra(key: string, value: unknown): this;
-    setExtras(extras: Record<string, unknown>): this;
-    setType(type: EventType): this;
-    setFingerprint(fingerprint: string[]): this;
-    addBreadcrumb(crumb: BreadcrumbInput, maxBreadcrumbs: number): this;
-    clearBreadcrumbs(): this;
-    clone(): Scope;
-}
-
 interface Logger {
     debug: (...args: unknown[]) => void;
     warn: (...args: unknown[]) => void;
@@ -75,6 +184,17 @@ declare class MachineSampler {
     private diskUsage;
 }
 
+/** Opções de telemetria resolvidas pelo runtime a partir do primeiro register()/start(). */
+interface ClientOptions {
+    environment?: EnvironmentInput;
+    release?: string;
+    /** Tags aplicadas a todos os eventos e transactions */
+    tags?: Record<string, string>;
+    debug?: boolean;
+    /** Knobs internos do transport (testes) — não fazem parte da API pública */
+    flushIntervalMs?: number;
+    maxBatchSize?: number;
+}
 declare class Client {
     #private;
     readonly logger: Logger;
@@ -82,21 +202,20 @@ declare class Client {
     readonly debug: boolean;
     private readonly transport;
     private machine;
-    constructor(options: InitOptions, config?: ResolvedConfig);
-    get options(): InitOptions;
+    constructor(options: ClientOptions, config: ResolvedConfig);
+    get options(): ClientOptions;
     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;
-    captureMessage(message: string, type: EventType, hint: CaptureHint | undefined, scope: Scope): string;
-    captureEvent(event: EventPayload, hint: CaptureHint | undefined, scope: Scope): string;
+    captureException(error: unknown, hint?: CaptureHint): string;
+    captureEvent(event: EventPayload, hint?: CaptureHint): string;
     private prepareEvent;
     sendTransaction(payload: TransactionPayload): void;
     sendHeartbeat(payload: HeartbeatPayload): void;
     /**
-     * Ambiente do item: o dele, senão o do init(), senão produção. Centralizado
+     * Ambiente do item: o dele, senão o das opções, senão produção. Centralizado
      * porque evento, transaction e heartbeat precisam responder igual — o servidor
      * normaliza apelidos legados, então aqui basta repassar.
      */
@@ -133,8 +252,7 @@ declare class Transaction {
     private readonly client;
     name: string;
     readonly op?: string | undefined;
-    private readonly sampled;
-    /** Correlaciona a uma execução de task — preenchido automaticamente em ctx.tx */
+    /** Correlaciona a uma execução de task — preenchido automaticamente em hobots.transaction */
     private readonly runId?;
     readonly eventId: string;
     readonly stepId: string;
@@ -144,9 +262,10 @@ declare class Transaction {
     private readonly tags;
     private finished;
     private lifecycleSink?;
+    private stepGuard?;
     private lifecycleBacklog;
-    constructor(client: Client | undefined, name: string, op?: string | undefined, sampled?: boolean, 
-    /** Correlaciona a uma execução de task — preenchido automaticamente em ctx.tx */
+    constructor(client: Client | undefined, name: string, op?: string | undefined, 
+    /** Correlaciona a uma execução de task — preenchido automaticamente em hobots.transaction */
     runId?: string | undefined);
     /**
      * Registra o início/fim de uma step ou transaction: espelha a linha no sink de
@@ -157,6 +276,11 @@ declare class Transaction {
     emit(kind: 'transaction' | 'step', phase: 'start' | 'finish', label: string, startTs?: string, endTs?: string, status?: StepStatus | string): void;
     /** Conecta o espelho de lifecycle (RunReporter) e faz replay do backlog em ordem. */
     setLifecycleSink(sink: LifecycleSink): void;
+    /**
+     * Conecta a checagem de cancelamento chamada antes de cada step nova — é assim que
+     * `hobots.transaction.startChild()` (e `step.startChild()`) param uma run cancelada.
+     */
+    setStepGuard(guard: () => void): void;
     createStep(parentStepId: string, op?: string, description?: string): Step;
     /** Step direta da transaction. */
     startChild(op?: string, description?: string): Step;
@@ -166,40 +290,6 @@ declare class Transaction {
     finish(): void;
 }
 
-/** Opções de tasks dentro de `init({ tasks: ... })`. Credencial (clientSecret), identidade (instanceId) e debug vêm do init. */
-interface TasksOptions {
-    /** Intervalo entre polls sem trabalho. Default: 2_000 (mínimo 1_000) */
-    pollIntervalMs?: number;
-    /** Runs simultâneas (1..5). Default: 1 (sequencial) */
-    concurrency?: number;
-    /**
-     * Timeout client-side por run. O handler não é morto — a run é reportada como
-     * falha e o slot é liberado. Default: sem timeout (o servidor é o backstop).
-     */
-    taskTimeoutMs?: number;
-    /** Intervalo do flush incremental de logs. Default: 2_000 */
-    logFlushIntervalMs?: number;
-    /**
-     * Intervalo do heartbeat de cancelamento por run: um PATCH vazio que detecta
-     * runs canceladas no app e dispara ctx.signal mesmo sem logs. Esse mesmo PATCH
-     * é o sinal de vida da run — o servidor marca como "encerrada inesperadamente"
-     * uma run sem reporte por ~60s. Default: 5_000 (mínimo 1_000, máximo 15_000)
-     */
-    cancelCheckIntervalMs?: number;
-    /**
-     * Tempo de graça após ctx.signal disparar (run cancelada no app) antes do
-     * agente desistir de esperar o handler e liberar o slot de concorrência. O
-     * handler não é morto — se ele nunca checar ctx.signal, pode continuar
-     * rodando em segundo plano; só o agente para de esperar por ele. Default: 10_000
-     */
-    cancelGraceMs?: number;
-    /**
-     * Instala handlers de SIGINT/SIGTERM/uncaughtException que reportam as runs
-     * ativas como falha (AgentTerminated) antes do processo morrer. Nunca interfere
-     * quando o programa tem handler próprio para o sinal. Default: true
-     */
-    installExitHandlers?: boolean;
-}
 interface RunLogger {
     debug(message: string): void;
     info(message: string): void;
@@ -219,6 +309,7 @@ interface RunItemOptions {
  * Registro dos itens que a execução processou/gerou (a entrega do bot: notas
  * fiscais baixadas, boletos emitidos...). Chamadas são síncronas — os itens são
  * bufferizados e enviados em lotes; o agente drena o buffer antes do reporte final.
+ * Cada chamada é um ponto de parada cooperativo: lança `RunCanceled` se a run foi cancelada.
  */
 interface RunItems {
     /** Forma genérica — os atalhos succeeded/failed/occurrence cobrem o dia a dia. */
@@ -237,9 +328,10 @@ interface RunItems {
 }
 /**
  * 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).
+ * `hobots.items`. Declare o total antes do loop e avance a cada item: a plataforma
+ * mostra barra, percentual e tempo restante estimado. Sem `total()` nada é enviado.
+ * Chamadas são síncronas e baratas (≤ 1 PATCH/s, pegando carona nos logs), e cada
+ * uma é um ponto de parada cooperativo (lança `RunCanceled` se a run foi cancelada).
  */
 interface RunProgressReporter {
     /** Declara (ou ajusta) o total de itens previsto — inteiro >= 1. Idempotente. */
@@ -253,158 +345,70 @@ interface RunProgressReporter {
     /** `{ current, total }` quando há total declarado; null caso contrário. */
     readonly snapshot: RunProgress | null;
 }
+/**
+ * Tudo que uma execução expõe ao código do bot. Acessível de qualquer lugar pelo
+ * objeto global `hobots` (resolve a run atual sozinho) ou pelo 2º argumento do handler.
+ */
 interface RunContext {
-    runId: string;
-    task: string;
-    /** Log bufferizado — enviado ao servidor em PATCHes incrementais com throttle */
-    log: RunLogger;
+    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. */
+    readonly 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;
+    readonly items: RunItems;
+    /** Progresso declarado (barra + ETA no app) — opcional, independente de `items` */
+    readonly 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
-     * as etapas (steps) da task; elas aparecem como waterfall na aba de performance da execução.
+     * automaticamente ao fim do handler. Use `transaction.startChild(op, description)` para
+     * medir as etapas (steps); elas aparecem como waterfall na aba de performance da execução.
      */
-    tx: Transaction;
+    readonly transaction: Transaction;
     /** Dispara em cancelamento (run cancelada no app), timeout ou shutdown — cancelamento cooperativo */
-    signal: AbortSignal;
+    readonly signal: AbortSignal;
     /**
-     * Lança um erro `RunCanceled` se a run foi cancelada/abortada — o ponto de
-     * parada cooperativo de 1 linha para chamar entre as etapas do trabalho.
+     * Lança um erro `RunCanceled` se a run foi cancelada/abortada. O SDK já chama isto em
+     * items/progress/transaction.startChild/sleep/retry; use para um controle mais fino.
      */
     throwIfCanceled(): void;
-    /** Sleep cancelável: rejeita com `RunCanceled` se ctx.signal disparar antes de ms. */
+    /** Sleep cancelável: rejeita com `RunCanceled` se o signal disparar antes de ms. */
     sleep(ms: number): Promise<void>;
-}
-/** 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>;
-
-interface HeartbeatOptions {
-    /** Intervalo entre batimentos. Default: 30_000 */
-    intervalMs?: number;
-    /** Nome amigável exibido no dashboard. Default: o instanceId do init */
-    name?: string;
-    metadata?: Record<string, unknown>;
-}
-interface InitOptions {
-    /** O Client Secret do agente (hb_…) — a mesma credencial para telemetria e tasks. Copie em Configurações → Agentes. */
-    clientSecret: string;
-    /**
-       * Ambiente lógico onde este robô roda: 'development', 'testing', 'staging'
-       * (homologação) ou 'production'. Vai em todo evento e transaction E na
-       * identidade da instância — é por ele que as regras de alerta decidem se
-       * notificam. Default: 'production'.
-       *
-       * Um valor livre herdado continua valendo — o servidor normaliza apelidos
-       * como 'prod' e 'qa'.
-       */
-    environment?: EnvironmentInput;
-    /** Versão do programa, ex.: 'robo-nfe@1.4.2' */
-    release?: string;
-    /** Identificador único e estável desta instância — a identidade do agente no painel (heartbeat e poll de tasks convergem nele) */
-    instanceId: string;
-    /** Tags aplicadas a todos os eventos */
-    tags?: Record<string, string>;
-    /** Amostragem de eventos de erro (0..1). Default: 1 */
-    sampleRate?: number;
-    /** Amostragem de transactions (0..1). Default: 1 */
-    tracesSampleRate?: number;
-    /** Default: 100 */
-    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;
     /**
-     * Habilita a execução remota de tarefas sob demanda — o módulo Solicitações do app
-     * (true usa defaults). Usa o mesmo clientSecret e o instanceId como identidade.
-     * Depois de init(), chame register() e start().
+     * Anexa uma imagem (print) a uma linha de log da run — miniatura no app. Nunca lança nem
+     * bloqueia: o upload roda em segundo plano. PNG/JPEG/WEBP, até 5 MB, 20 por execução.
      */
-    tasks?: boolean | TasksOptions;
-    /** Última chance de editar/descartar um evento (retorne null para descartar) */
-    beforeSend?: (event: EventPayload) => EventPayload | null;
-    /** Loga atividade do SDK no console */
-    debug?: boolean;
-    /** Intervalo do flush automático do transport. Default: 2_000 */
-    flushIntervalMs?: number;
-    /** Itens por envelope antes de flush imediato. Default: 10 */
-    maxBatchSize?: number;
-}
-/** Imagem enviada junto de um capture* — com legenda e content-type opcionais. */
-interface CaptureAttachment {
-    /** Bytes (`Uint8Array`/`ArrayBuffer`/`Buffer`) ou um caminho de arquivo (só em Node) */
-    image: AttachInput;
-    /** Legenda curta, exibida sob a miniatura no app. Passa pelo scrub de segredos. */
-    caption?: string;
-    /** Informe quando os magic bytes não bastarem (o SDK sempre prefere o que detectar). */
-    contentType?: RunAttachmentContentType;
-}
-interface CaptureHint {
-    type?: EventType;
-    tags?: Record<string, string>;
-    extra?: Record<string, unknown>;
-    fingerprint?: string[];
-    /**
-     * Print da tela enviado junto da captura. Dentro de uma execução de task, a imagem
-     * vira anexo da linha de log da execução que espelha o evento — miniatura na aba
-     * "logs do agente". Fora de uma execução não há onde pendurar a imagem: o SDK
-     * descarta com um aviso. O upload roda em segundo plano e **nunca bloqueia nem lança**.
-     *
-     * PNG, JPEG ou WEBP, até 5 MB, no máximo 20 anexos por execução.
-     *
-     * ```ts
-     * Hobots.captureException(error, { attachment: { image: await page.screenshot(), caption: 'tela no momento do erro' } });
-     * ```
-     */
-    attachment?: AttachInput | CaptureAttachment;
+    attach(image: AttachInput, options?: AttachOptions): Promise<AttachResult>;
+    /** async-retry ciente do cancelamento desta run (ver `RetryOptions`). */
+    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>;
 
-/** Inicializa o SDK. Chame uma vez, o mais cedo possível no programa. */
-declare function init(options: InitOptions): void;
-declare function getClient(): Client | undefined;
-/**
- * Captura uma exceção e retorna o event_id (undefined se o SDK não foi inicializado).
- * `hint.attachment` envia um print junto — dentro de uma execução de task, ele aparece
- * como miniatura na linha de log da run correspondente ao erro.
- */
-declare function captureException(error: unknown, hint?: CaptureHint): string | undefined;
-declare function captureMessage(message: string, type?: EventType, hint?: CaptureHint): string | undefined;
-/** Registra um breadcrumb — anexado aos próximos eventos como trilha do que aconteceu antes. */
-declare function addBreadcrumb(crumb: BreadcrumbInput): void;
-declare function setTag(key: string, value: string): void;
-declare function setTags(tags: Record<string, string>): void;
-declare function setUser(user: EventUser | null): void;
-declare function setContext(name: string, context: Record<string, unknown> | null): void;
-declare function setExtra(key: string, value: unknown): void;
-/** Executa o callback com uma cópia isolada do scope (alterações não vazam para fora). */
-declare function withScope<T>(callback: (scope: Scope) => T): T;
-/** Inicia uma transaction de performance. Chame .finish() para enviá-la. */
-declare function startTransaction(name: string, op?: string): Transaction;
-/** Aguarda o envio de tudo que está na fila (até timeoutMs). */
-declare function flush(timeoutMs?: number): Promise<boolean>;
-/** Registra o handler de uma task (o task_slug configurado no formulário do app, em Configurações → Formulários). */
-declare function register<P = Record<string, unknown>>(task: string, handler: TaskHandler<P>): void;
-/**
- * Inicia o polling de tasks. O timer NÃO é unref'd: o processo fica vivo
- * aguardando trabalho até stop()/close() — o inverso deliberado da telemetria.
- */
-declare function start(): void;
-/** Para só o polling de tasks e aguarda as runs ativas (até timeoutMs). A telemetria continua. */
-declare function stop(timeoutMs?: number): Promise<boolean>;
 /**
- * Encerra tudo: para o polling de tasks (aguardando runs em voo), o heartbeat
- * e faz o flush final do transport. Chame antes do processo terminar.
+ * O objeto global do SDK: as funções do processo (register/start/close/captureException/
+ * retry) e o contexto da execução ATUAL (log, items, progress, transaction, signal…),
+ * resolvido a cada acesso — funciona de qualquer módulo, sem passar `ctx` de mão em mão.
  */
-declare function close(timeoutMs?: number): Promise<boolean>;
-
-declare function scrubSecrets(text: string): string;
+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;
+    /** 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. */
+    captureException(error: unknown, hint?: CaptureHint): string | undefined;
+}
+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 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>;
 
-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 };
+export { type AttachFailureReason, type AttachInput, type AttachOptions, type AttachResult, type CaptureAttachment, type CaptureHint, EnvironmentInput, EventPayload, EventType, HeartbeatPayload, type Hobots, type HobotsOptions, MachineSnapshot, type RegisterOptions, type RetryDelay, type RetryOptions, RunAttachmentContentType, type RunContext, type RunItemOptions, RunItemStatus, type RunItems, RunLogLevel, type RunLogger, RunProgress, type RunProgressReporter, type StartOptions, Step, StepData, StepStatus, type TaskHandler, type TaskOptions, Transaction, TransactionPayload, captureException, close, hobots as default, hobots, register, retry, start };