import { RunAttachmentContentType, EventType, EnvironmentInput, MachineSnapshot, EventPayload, TransactionPayload, HeartbeatPayload, StepStatus, RunLogLevel, StepData, FileRef, RunItemStatus, RunProgress } from './protocol.cjs';
export { Breadcrumb, BreadcrumbLevel, Envelope, EnvelopeItem, Environment, EventUser, ExceptionData, FileDownloadResponse, FileStorage, 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);
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;
}

/** Aceita tudo que o handler pode ter em mãos: bytes ou um caminho de arquivo (só Node). */
type AttachInput = Uint8Array | ArrayBuffer | string;
interface ImageOptions {
    /** Legenda curta, exibida junto da imagem 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;
}
declare const IMAGE_BRAND: unique symbol;
/**
 * Uma imagem pronta para ser pendurada num evento da run — o retorno de `hobots.image()`.
 * É só um envelope (bytes/caminho + legenda); nenhum I/O acontece até o evento ser
 * registrado por `hobots.log.*`, `hobots.items.*` ou `step.setStatus/setError`.
 */
declare class ImageAttachment {
    readonly input: AttachInput;
    readonly caption?: string | undefined;
    readonly contentType?: RunAttachmentContentType | undefined;
    readonly [IMAGE_BRAND] = true;
    constructor(input: AttachInput, caption?: string | undefined, contentType?: RunAttachmentContentType | undefined);
}
/** O que os métodos com imagem aceitam: bytes/caminho crus ou o envelope de `hobots.image()`. */
type ImageInput = AttachInput | ImageAttachment;

interface Logger {
    debug: (...args: unknown[]) => void;
    warn: (...args: unknown[]) => void;
    error: (...args: unknown[]) => void;
}

/** Coluna de itens como o dev declara: só a chave, ou chave + rótulo. */
type ItemColumnInput = string | {
    key: string;
    label?: string;
};

/**
 * 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 execuções 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: env HOBOTS_ENVIRONMENT;
     * sem ela, '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;
}
/** Colunas de itens declaradas no código (até 12; chave: letras, números, `.`, `-`, `_`). */
interface ItemsOptions {
    columns: ItemColumnInput[];
}
/** 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
     * formulário — vale para register e start. Personalizar na plataforma
     * (Configurações → agente) sobrepõe o que for declarado aqui.
     * Ex.: `{ columns: ['numero_nota', { key: 'valor', label: 'valor (R$)' }] }`
     */
    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
     * 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()` — 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). Default: 2_000 */
    pollIntervalMs?: number;
}
/** 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) */
    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?: ImageInput | CaptureAttachment;
}

interface ResolvedConfig {
    /** Client Secret do agente (enviado como Authorization: Bearer, nunca na URL) */
    key: string;
    baseUrl: string;
    /** Ingestão de telemetria: <baseUrl>/v1/ingest */
    ingestEndpoint: string;
    /** API de execuções (poll, runs, itens, anexos): <baseUrl>/v1/runs */
    runsBaseUrl: string;
}

/**
 * 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;
}

/** 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;
    /** Eco de lifecycle (Transaction.emit) e afins só imprimem no terminal com debug ligado. */
    readonly debug: boolean;
    private readonly transport;
    private machine;
    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): 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 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.
     */
    private resolveEnvironment;
    flush(timeoutMs?: number): Promise<boolean>;
    close(timeoutMs?: number): Promise<boolean>;
}

/** Recebe os eventos de lifecycle da transaction para espelhá-los nos logs da run. */
type LifecycleSink = (level: RunLogLevel, message: string) => void;
/**
 * Recebe a imagem de uma step e dispara o upload pela run; devolve o id do anexo
 * (já referenciável em `data.attachments`) ou undefined quando descartada.
 */
type AttachmentSink = (image: ImageInput, ts: string) => string | undefined;
/** Opções dos desfechos de step que aceitam um print do estado da tela. */
interface StepOutcomeOptions {
    /** Print da step (bytes/caminho ou `hobots.image(bytes, { caption })`) — botão de imagem no app. */
    image?: ImageInput;
}
declare class Step {
    private readonly transaction;
    readonly parentStepId: string;
    readonly op?: string | undefined;
    readonly description?: string | undefined;
    readonly stepId: string;
    readonly startTimestamp: string;
    status: StepStatus;
    endTimestamp?: string;
    data?: Record<string, unknown>;
    constructor(transaction: Transaction, parentStepId: string, op?: string | undefined, description?: string | undefined);
    /**
     * Desfecho da step. `message` (opcional) é o motivo legível — vai em `data.message`
     * e aparece na Central (performance e banner da execução) e no log de FINISH.
     * `options.image` pendura um print do estado da tela em `data.attachments`.
     */
    setStatus(status: StepStatus, message?: string, options?: StepOutcomeOptions): this;
    /**
     * Marca a step como `error` guardando o motivo em `data.error` ({ type, message }).
     * Aceita qualquer valor lançado; `message` sobrescreve a mensagem do erro.
     * `options.image` pendura um print do estado da tela em `data.attachments`.
     */
    setError(error: unknown, message?: string, options?: StepOutcomeOptions): this;
    /**
     * Dispara o upload pela run (sink do RunReporter) e referencia o anexo em
     * `data.attachments` (chave reservada; teto igual ao das linhas de log). Fora de uma
     * run não há onde pendurar a imagem — descarta com aviso único.
     */
    private attachImage;
    /** Motivo registrado via setStatus(…, message) ou setError — usado no log de FINISH. */
    private reason;
    setData(key: string, value: unknown): this;
    /** Step aninhada (filha desta step). */
    startChild(op?: string, description?: string): Step;
    finish(): void;
    toJSON(): StepData;
}
/**
 * Uma unidade de trabalho nomeada (ex.: uma execução de rotina, uma sincronização).
 * Steps filhas medem as etapas internas (chamadas HTTP, queries, etc.).
 */
declare class Transaction {
    private readonly client;
    name: string;
    readonly op?: string | undefined;
    /** Correlaciona a uma execução do agente — preenchido automaticamente em hobots.transaction */
    private readonly runId?;
    readonly eventId: string;
    readonly stepId: string;
    readonly startTimestamp: string;
    status: string;
    private readonly steps;
    private readonly tags;
    private finished;
    private lifecycleSink?;
    private attachmentSink?;
    private warnedNoAttachmentSink;
    private stepGuard?;
    private lifecycleBacklog;
    constructor(client: Client | undefined, name: string, op?: string | undefined, 
    /** 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
     * lifecycle, se conectado (é assim que os eventos de performance aparecem nos
     * logs da run no app), e ecoa no terminal apenas com `debug: true` — o SDK não
     * escreve no stdout do processo do usuário sem permissão.
     */
    emit(kind: 'transaction' | 'step', phase: 'start' | 'finish', label: string, startTs?: string, endTs?: string, status?: StepStatus | string, reason?: string): void;
    /** Conecta o espelho de lifecycle (RunReporter) e faz replay do backlog em ordem. */
    setLifecycleSink(sink: LifecycleSink): void;
    /** Conecta o pipeline de anexos da run — é o que dá imagem às steps. */
    setAttachmentSink(sink: AttachmentSink): void;
    /** Imagem de uma step → id do anexo pela run; sem run, descarta com aviso único. */
    attachImage(image: ImageInput): string | undefined;
    /**
     * 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;
    setTag(key: string, value: string): this;
    setStatus(status: string): this;
    setName(name: string): this;
    /**
     * Envia já as steps raiz finalizadas (e todas as descendentes, fechando as que
     * ficaram abertas) como transactions parciais da mesma run (`op` hobots.run.flush,
     * `event_id` novo, até 200 steps cada) e as tira da memória. Steps raiz ainda abertas
     * ficam para o próximo flush ou para o `finish()`. É assim que um agente sempre
     * ligado (`start()`), cuja run não termina, entrega as etapas enquanto processa.
     * Devolve quantas steps foram enviadas.
     */
    flush(): number;
    /** Entrega já (com teto) o que está na fila do transport — as transactions parciais inclusive. */
    drain(timeoutMs: number): Promise<void>;
    private payload;
    finish(): void;
}

interface FileDownloadOptions {
    /**
     * Destino da cópia: uma pasta existente (ou terminada em `/`) recebe o arquivo com o nome
     * original; qualquer outro caminho é o arquivo final. Omitido: pasta temporária da
     * execução, apagada quando ela termina.
     */
    dest?: string;
}
/**
 * Arquivos dos campos de upload do formulário (`hobots.files`). O valor do campo nos
 * params é um `FileRef` (ou uma lista deles); `download` traz o arquivo para o disco
 * desta máquina — do S3 (enviado pela Central) ou da pasta do Studio (mesmo computador)
 * — e o consome na origem: cada arquivo é baixado uma vez.
 */
interface RunFiles {
    /** Todos os arquivos dos params (campos de topo, valor único ou lista), na ordem dos campos. */
    list(): FileRef[];
    /** O arquivo do campo (campo único), a lista (campo "vários arquivos") ou undefined. */
    get(field: string): FileRef | FileRef[] | undefined;
    /**
     * Baixa um arquivo e resolve com o caminho local. Aceita o `FileRef` ou o nome de um
     * campo de arquivo único (para campo com vários arquivos, use `downloadAll`). Só depois
     * da cópia completa e conferida o arquivo é consumido na origem — uma falha não perde
     * nada e pode ser tentada de novo. Respeita o cancelamento da execução.
     */
    download(refOrField: FileRef | string, options?: FileDownloadOptions): Promise<string>;
    /** Baixa todos os arquivos do campo (único ou lista), em ordem. `dest` aqui é uma pasta. */
    downloadAll(field: string, options?: FileDownloadOptions): Promise<string[]>;
    /** Conteúdo do arquivo em memória — baixa, lê e apaga a cópia temporária. */
    read(refOrField: FileRef | string): Promise<Buffer>;
}

/**
 * `hobots.log`: cada método aceita vários argumentos, como `console.log` — cada um vira
 * texto (`safeString`) e são unidos por espaço. Nunca lança, nem com a run cancelada.
 *
 * Um `hobots.image(...)` como **último** argumento não entra no texto: vira o print da
 * linha (botão de imagem no app). O upload roda em segundo plano e nunca bloqueia:
 * `hobots.log.error('login falhou', hobots.image(await page.screenshot()))`.
 */
interface RunLogger {
    debug(message: unknown, ...rest: unknown[]): void;
    info(message: unknown, ...rest: unknown[]): void;
    warn(message: unknown, ...rest: unknown[]): void;
    error(message: unknown, ...rest: unknown[]): void;
    success(message: unknown, ...rest: unknown[]): void;
}
interface RunItemImageOptions {
    /**
     * Print do item (bytes/caminho ou `hobots.image(bytes, { caption })`) — o estado da tela
     * no momento do desfecho, com botão de imagem na tabela de itens do app. O upload roda
     * em segundo plano e nunca bloqueia. PNG/JPEG/WEBP, até 5 MB, 20 por execução.
     */
    image?: ImageInput;
}
interface RunItemOptions extends RunItemImageOptions {
    /**
     * Identidade de negócio do item na run (ex.: nº da nota fiscal). Repetido na
     * mesma run = o servidor atualiza o item (vale o último reporte, retry idempotente).
     * Omitido: o SDK gera um id único e cada chamada vira um item novo.
     */
    id?: string;
}
/**
 * O item em processamento dentro de `items.each`: o desfecho (`succeeded`/`failed`/
 * `occurrence`) com o `id` e o payload base já resolvidos, e a step da etapa para quem
 * quiser medir sub-etapas (`item.step.startChild(...)`). Sem chamada explícita, o SDK
 * decide: retornou → `succeeded`; lançou → `failed` com a mensagem do erro.
 */
interface RunItemHandle {
    /** Posição do elemento na lista (0-based). */
    readonly index: number;
    /** Identidade de negócio resolvida por `options.id` (undefined = o SDK gera uma). */
    readonly id: string | undefined;
    /** Step desta etapa no waterfall de performance; undefined fora de uma execução. */
    readonly step: Step | undefined;
    /** true depois do primeiro desfecho registrado (o SDK não sobrescreve o que o handler decidiu). */
    readonly reported: boolean;
    /** Item processado com sucesso. `payload` é mesclado sobre o payload base de `options.payload`. */
    succeeded(payload?: Record<string, unknown>, options?: RunItemImageOptions): void;
    /** Falha sem lançar — o loop segue igual; a step vira `error` com o motivo. A imagem vai no item. */
    failed(message: string, payload?: Record<string, unknown>, options?: RunItemImageOptions): void;
    /** Ocorrência de negócio — a step vira `warning` com o motivo. A imagem vai no item. */
    occurrence(message: string, payload?: Record<string, unknown>, options?: RunItemImageOptions): void;
}
interface RunItemsEachOptions<T> {
    /** Identidade de negócio do item (ex.: nº do cliente). Omitido/null: o SDK gera um id único. */
    id?: (element: T, index: number) => string | number | null | undefined;
    /** Atributos base do item (viram colunas no app) — presentes em qualquer desfecho, inclusive falha. */
    payload?: (element: T, index: number) => Record<string, unknown> | undefined;
    /** `op` da step de cada item no waterfall. Default: 'item'. */
    op?: string;
    /** Descrição da step de cada item. Default: o `id`, senão `#<posição>`. */
    description?: (element: T, index: number) => string;
    /**
     * Progresso automático: declara o total (tamanho da lista, se o bot ainda não declarou um)
     * e avança a cada elemento. `false` deixa o progresso por conta do bot. Default: true.
     */
    progress?: boolean;
}
/** Totalizadores do `items.each`, pelo desfecho final de cada elemento. */
interface RunItemsEachResult {
    total: number;
    succeeded: number;
    failed: number;
    occurrence: number;
}
type RunItemsEachHandler<T> = (element: T, item: RunItemHandle, index: number) => unknown;
/**
 * 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. */
    add(item: {
        status: RunItemStatus;
        id?: string;
        message?: string;
        payload?: Record<string, unknown>;
        image?: ImageInput;
    }): void;
    /** Item processado com sucesso. `payload` = atributos do item (viram colunas na plataforma). */
    succeeded(payload?: Record<string, unknown>, options?: RunItemOptions): void;
    /** Falha técnica ao processar o item — `message` é o motivo exibido na plataforma. */
    failed(message: string, payload?: Record<string, unknown>, options?: RunItemOptions): void;
    /** 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;
    /**
     * Processa uma lista item a item com o contrato da plataforma garantido pelo SDK: cada
     * elemento vira uma step e um item; uma exceção no handler registra o item como `failed`
     * (com a mensagem do erro), marca a step com `setError` e **segue para o próximo** — a
     * lista inteira é processada, e o progresso avança a cada elemento. Só cancelamento,
     * timeout e shutdown interrompem o loop (o erro sobe como em qualquer ponto de parada).
     * Resolve com os totalizadores por desfecho.
     */
    each<T>(list: Iterable<T> | AsyncIterable<T>, handler: RunItemsEachHandler<T>, options?: RunItemsEachOptions<T>): Promise<RunItemsEachResult>;
}
/**
 * Progresso da execução (itens processados / total) — opcional e independente de
 * `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. */
    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;
}
/**
 * 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 {
    readonly runId: 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 */
    readonly items: RunItems;
    /** Progresso declarado (barra + ETA no app) — opcional, independente de `items` */
    readonly progress: RunProgressReporter;
    /**
     * Arquivos dos campos de upload do formulário: `list()`, `get(campo)`, `download(refOuCampo)`
     * (caminho local), `downloadAll(campo)` e `read(refOuCampo)` (conteúdo em memória).
     * Cada arquivo é consumido na origem ao ser baixado — baixe uma vez e reaproveite a cópia.
     */
    readonly files: RunFiles;
    /**
     * Transaction de performance desta execução — já correlacionada à run e finalizada
     * 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.
     */
    readonly transaction: Transaction;
    /**
     * Entrega já o que a execução fez: as steps raiz finalizadas viram transactions parciais
     * (waterfall da Central sem esperar a run terminar) e itens, logs e progresso pendentes
     * saem sem esperar o throttle. Quem decide quando chamar é o bot — num agente sempre
     * ligado (`start()`), ao fim de cada rodada que processou itens. Aguarda a entrega com
     * teto (`timeoutMs`, default 15s) e nunca lança.
     */
    flush(timeoutMs?: number): Promise<void>;
    /** Dispara em cancelamento (run cancelada no app), timeout ou shutdown — cancelamento cooperativo */
    readonly signal: AbortSignal;
    /**
     * 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 o signal disparar antes de ms. */
    sleep(ms: number): Promise<void>;
    /** 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 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/
 * 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.
 */
interface Hobots extends RunContext {
    /**
     * 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. */
    captureException(error: unknown, hint?: CaptureHint): string | undefined;
    /**
     * Embrulha um print para ir junto de um log, item ou step — `hobots.log.error('x', hobots.image(png))`,
     * `hobots.items.failed('x', payload, { image: hobots.image(png, { caption }) })`,
     * `step.setError(err, undefined, { image: png })`. Puro: nenhum I/O até o evento ser registrado.
     */
    image(input: AttachInput, options?: ImageOptions): ImageAttachment;
    /** O valor tem a forma de um arquivo de campo de upload (`FileRef`) — puro, sem I/O. */
    isFileRef(value: unknown): value is FileRef;
}
declare global {
    var hobots: Hobots;
}
declare const hobots: Hobots;
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;
declare const isFileRef: (value: unknown) => value is FileRef;

export { type AttachInput, type CaptureAttachment, type CaptureHint, EnvironmentInput, EventPayload, EventType, type FileDownloadOptions, FileRef, 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 RunFiles, 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, isFileRef, register, retry, start };