hobots 3.4.0 → 4.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.cts CHANGED
@@ -1,5 +1,5 @@
1
1
  import { RunAttachmentContentType, EventType, EnvironmentInput, MachineSnapshot, EventPayload, TransactionPayload, HeartbeatPayload, StepStatus, RunLogLevel, StepData, RunItemStatus, RunProgress } from './protocol.cjs';
2
- 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';
2
+ 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';
3
3
 
4
4
  /** Espera entre tentativas: ms fixo ou função do número da tentativa que acabou de falhar (1-based). */
5
5
  type RetryDelay = number | ((attempt: number) => number);
@@ -57,7 +57,7 @@ interface HobotsOptions {
57
57
  clientSecret?: string;
58
58
  /**
59
59
  * Identificador único e estável desta instância — a identidade do agente no painel
60
- * (heartbeat e tasks convergem nele). Default: env HOBOTS_INSTANCE_ID; sem ela, o hostname.
60
+ * (heartbeat e execuções convergem nele). Default: env HOBOTS_INSTANCE_ID; sem ela, o hostname.
61
61
  */
62
62
  instanceId?: string;
63
63
  /**
@@ -88,11 +88,11 @@ interface HobotsOptions {
88
88
  installExitHandlers?: boolean;
89
89
  }
90
90
  /** Colunas de itens declaradas no código (até 12; chave: letras, números, `.`, `-`, `_`). */
91
- interface TaskItemsOptions {
91
+ interface ItemsOptions {
92
92
  columns: ItemColumnInput[];
93
93
  }
94
- /** Opções de uma task (register ou start). */
95
- interface TaskOptions extends HobotsOptions {
94
+ /** Opções da execução do agente (register ou start). */
95
+ interface RunOptions extends HobotsOptions {
96
96
  /**
97
97
  * Colunas da aba "itens" da execução na plataforma: chaves do `payload` que cada
98
98
  * item reportado (`ctx.items.*`) carrega, com rótulo opcional. Independe de
@@ -100,7 +100,7 @@ interface TaskOptions extends HobotsOptions {
100
100
  * (Configurações → agente) sobrepõe o que for declarado aqui.
101
101
  * Ex.: `{ columns: ['numero_nota', { key: 'valor', label: 'valor (R$)' }] }`
102
102
  */
103
- items?: TaskItemsOptions;
103
+ items?: ItemsOptions;
104
104
  /**
105
105
  * Tentativas extras do handler quando ele lança, na mesma run (itens e progresso já
106
106
  * enviados permanecem — escreva handlers idempotentes). Cancelamento e timeout nunca
@@ -128,15 +128,15 @@ interface TaskOptions extends HobotsOptions {
128
128
  */
129
129
  cancelGraceMs?: number;
130
130
  }
131
- /** Opções de `register()` — task executada sob demanda, a partir das solicitações do app. */
132
- interface RegisterOptions extends TaskOptions {
133
- /** Runs simultâneas desta task (1..5). Default: 1 (sequencial) */
131
+ /** Opções de `register()` — agente sob demanda, executado a partir das solicitações do app. */
132
+ interface RegisterOptions extends RunOptions {
133
+ /** Runs simultâneas do agente (1..5). Default: 1 (sequencial) */
134
134
  concurrency?: number;
135
- /** Intervalo entre polls sem trabalho (mínimo 1_000). Vale o do primeiro register(). Default: 2_000 */
135
+ /** Intervalo entre polls sem trabalho (mínimo 1_000). Default: 2_000 */
136
136
  pollIntervalMs?: number;
137
137
  }
138
- /** Opções de `start()` — task que roda sempre, aberta pelo próprio bot. */
139
- type StartOptions = TaskOptions;
138
+ /** Opções de `start()` — agente sempre ligado, que abre a própria run. */
139
+ type StartOptions = RunOptions;
140
140
  /** Imagem enviada junto de um captureException — com legenda e content-type opcionais. */
141
141
  interface CaptureAttachment {
142
142
  /** Bytes (`Uint8Array`/`ArrayBuffer`/`Buffer`) ou um caminho de arquivo (só em Node) */
@@ -170,8 +170,8 @@ interface ResolvedConfig {
170
170
  baseUrl: string;
171
171
  /** Ingestão de telemetria: <baseUrl>/v1/ingest */
172
172
  ingestEndpoint: string;
173
- /** API de tasks (execução sob demanda): <baseUrl>/v1/tasks */
174
- tasksBaseUrl: string;
173
+ /** API de execuções (poll, runs, itens, anexos): <baseUrl>/v1/runs */
174
+ runsBaseUrl: string;
175
175
  }
176
176
 
177
177
  /**
@@ -299,7 +299,7 @@ declare class Transaction {
299
299
  private readonly client;
300
300
  name: string;
301
301
  readonly op?: string | undefined;
302
- /** Correlaciona a uma execução de task — preenchido automaticamente em hobots.transaction */
302
+ /** Correlaciona a uma execução do agente — preenchido automaticamente em hobots.transaction */
303
303
  private readonly runId?;
304
304
  readonly eventId: string;
305
305
  readonly stepId: string;
@@ -314,7 +314,7 @@ declare class Transaction {
314
314
  private stepGuard?;
315
315
  private lifecycleBacklog;
316
316
  constructor(client: Client | undefined, name: string, op?: string | undefined,
317
- /** Correlaciona a uma execução de task — preenchido automaticamente em hobots.transaction */
317
+ /** Correlaciona a uma execução do agente — preenchido automaticamente em hobots.transaction */
318
318
  runId?: string | undefined);
319
319
  /**
320
320
  * Registra o início/fim de uma step ou transaction: espelha a linha no sink de
@@ -340,6 +340,18 @@ declare class Transaction {
340
340
  setTag(key: string, value: string): this;
341
341
  setStatus(status: string): this;
342
342
  setName(name: string): this;
343
+ /**
344
+ * Envia já as steps raiz finalizadas (e todas as descendentes, fechando as que
345
+ * ficaram abertas) como transactions parciais da mesma run (`op` hobots.run.flush,
346
+ * `event_id` novo, até 200 steps cada) e as tira da memória. Steps raiz ainda abertas
347
+ * ficam para o próximo flush ou para o `finish()`. É assim que um agente sempre
348
+ * ligado (`start()`), cuja run não termina, entrega as etapas enquanto processa.
349
+ * Devolve quantas steps foram enviadas.
350
+ */
351
+ flush(): number;
352
+ /** Entrega já (com teto) o que está na fila do transport — as transactions parciais inclusive. */
353
+ drain(timeoutMs: number): Promise<void>;
354
+ private payload;
343
355
  finish(): void;
344
356
  }
345
357
 
@@ -475,7 +487,6 @@ interface RunProgressReporter {
475
487
  */
476
488
  interface RunContext {
477
489
  readonly runId: string;
478
- readonly task: string;
479
490
  /** Params da solicitação (formulário do app); `{}` no modo start */
480
491
  readonly params: Record<string, unknown>;
481
492
  /** Log bufferizado — enviado ao servidor em PATCHes incrementais com throttle. Nunca lança. */
@@ -490,6 +501,14 @@ interface RunContext {
490
501
  * medir as etapas (steps); elas aparecem como waterfall na aba de performance da execução.
491
502
  */
492
503
  readonly transaction: Transaction;
504
+ /**
505
+ * Entrega já o que a execução fez: as steps raiz finalizadas viram transactions parciais
506
+ * (waterfall da Central sem esperar a run terminar) e itens, logs e progresso pendentes
507
+ * saem sem esperar o throttle. Quem decide quando chamar é o bot — num agente sempre
508
+ * ligado (`start()`), ao fim de cada rodada que processou itens. Aguarda a entrega com
509
+ * teto (`timeoutMs`, default 15s) e nunca lança.
510
+ */
511
+ flush(timeoutMs?: number): Promise<void>;
493
512
  /** Dispara em cancelamento (run cancelada no app), timeout ou shutdown — cancelamento cooperativo */
494
513
  readonly signal: AbortSignal;
495
514
  /**
@@ -503,7 +522,7 @@ interface RunContext {
503
522
  retry<T>(fn: (attempt: number) => T | Promise<T>, options?: RetryOptions): Promise<T>;
504
523
  }
505
524
  /** O retorno do handler é ignorado — nada além de status/logs/erro é enviado ao servidor. */
506
- type TaskHandler<P = Record<string, unknown>> = (params: P, ctx: RunContext) => void | Promise<void>;
525
+ type RunHandler<P = Record<string, unknown>> = (params: P, ctx: RunContext) => void | Promise<void>;
507
526
 
508
527
  /**
509
528
  * O objeto global do SDK: as funções do processo (register/start/close/captureException/
@@ -511,10 +530,13 @@ type TaskHandler<P = Record<string, unknown>> = (params: P, ctx: RunContext) =>
511
530
  * resolvido a cada acesso — funciona de qualquer módulo, sem passar `ctx` de mão em mão.
512
531
  */
513
532
  interface Hobots extends RunContext {
514
- /** Task sob demanda: executada a cada solicitação do app (formulário/agendamento) via polling. */
515
- register<P = Record<string, unknown>>(task: string, handler: TaskHandler<P>, options?: RegisterOptions): void;
516
- /** Task sempre-ligada: o bot abre a própria run e roda o handler; a plataforma recebe logs, itens e progresso. */
517
- start(task: string, handler: TaskHandler, options?: StartOptions): void;
533
+ /**
534
+ * Agente sob demanda: o handler roda a cada solicitação do app (formulário/agendamento), via polling.
535
+ * O agente é a própria tarefa: uma chamada por processo (register OU start).
536
+ */
537
+ register<P = Record<string, unknown>>(handler: RunHandler<P>, options?: RegisterOptions): void;
538
+ /** Agente sempre ligado: abre a própria run e roda o handler; a plataforma recebe logs, itens e progresso. */
539
+ start(handler: RunHandler, options?: StartOptions): void;
518
540
  /** Encerra tudo (polling, runs em voo, heartbeat, flush final). Chame antes do processo terminar. */
519
541
  close(timeoutMs?: number): Promise<boolean>;
520
542
  /** Captura uma exceção como issue (módulo Issues). Retorna o event_id. */
@@ -530,11 +552,11 @@ declare global {
530
552
  var hobots: Hobots;
531
553
  }
532
554
  declare const hobots: Hobots;
533
- declare const register: <P = Record<string, unknown>>(task: string, handler: TaskHandler<P>, options?: RegisterOptions) => void;
534
- declare const start: (task: string, handler: TaskHandler, options?: StartOptions) => void;
555
+ declare const register: <P = Record<string, unknown>>(handler: RunHandler<P>, options?: RegisterOptions) => void;
556
+ declare const start: (handler: RunHandler, options?: StartOptions) => void;
535
557
  declare const close: (timeoutMs?: number) => Promise<boolean>;
536
558
  declare const captureException: (error: unknown, hint?: CaptureHint) => string | undefined;
537
559
  declare const retry: <T>(fn: (attempt: number) => T | Promise<T>, options?: RetryOptions) => Promise<T>;
538
560
  declare const image: (input: AttachInput, options?: ImageOptions) => ImageAttachment;
539
561
 
540
- 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 };
562
+ 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 CHANGED
@@ -1,5 +1,5 @@
1
1
  import { RunAttachmentContentType, EventType, EnvironmentInput, MachineSnapshot, EventPayload, TransactionPayload, HeartbeatPayload, StepStatus, RunLogLevel, StepData, RunItemStatus, RunProgress } from './protocol.js';
2
- 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';
2
+ 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';
3
3
 
4
4
  /** Espera entre tentativas: ms fixo ou função do número da tentativa que acabou de falhar (1-based). */
5
5
  type RetryDelay = number | ((attempt: number) => number);
@@ -57,7 +57,7 @@ interface HobotsOptions {
57
57
  clientSecret?: string;
58
58
  /**
59
59
  * Identificador único e estável desta instância — a identidade do agente no painel
60
- * (heartbeat e tasks convergem nele). Default: env HOBOTS_INSTANCE_ID; sem ela, o hostname.
60
+ * (heartbeat e execuções convergem nele). Default: env HOBOTS_INSTANCE_ID; sem ela, o hostname.
61
61
  */
62
62
  instanceId?: string;
63
63
  /**
@@ -88,11 +88,11 @@ interface HobotsOptions {
88
88
  installExitHandlers?: boolean;
89
89
  }
90
90
  /** Colunas de itens declaradas no código (até 12; chave: letras, números, `.`, `-`, `_`). */
91
- interface TaskItemsOptions {
91
+ interface ItemsOptions {
92
92
  columns: ItemColumnInput[];
93
93
  }
94
- /** Opções de uma task (register ou start). */
95
- interface TaskOptions extends HobotsOptions {
94
+ /** Opções da execução do agente (register ou start). */
95
+ interface RunOptions extends HobotsOptions {
96
96
  /**
97
97
  * Colunas da aba "itens" da execução na plataforma: chaves do `payload` que cada
98
98
  * item reportado (`ctx.items.*`) carrega, com rótulo opcional. Independe de
@@ -100,7 +100,7 @@ interface TaskOptions extends HobotsOptions {
100
100
  * (Configurações → agente) sobrepõe o que for declarado aqui.
101
101
  * Ex.: `{ columns: ['numero_nota', { key: 'valor', label: 'valor (R$)' }] }`
102
102
  */
103
- items?: TaskItemsOptions;
103
+ items?: ItemsOptions;
104
104
  /**
105
105
  * Tentativas extras do handler quando ele lança, na mesma run (itens e progresso já
106
106
  * enviados permanecem — escreva handlers idempotentes). Cancelamento e timeout nunca
@@ -128,15 +128,15 @@ interface TaskOptions extends HobotsOptions {
128
128
  */
129
129
  cancelGraceMs?: number;
130
130
  }
131
- /** Opções de `register()` — task executada sob demanda, a partir das solicitações do app. */
132
- interface RegisterOptions extends TaskOptions {
133
- /** Runs simultâneas desta task (1..5). Default: 1 (sequencial) */
131
+ /** Opções de `register()` — agente sob demanda, executado a partir das solicitações do app. */
132
+ interface RegisterOptions extends RunOptions {
133
+ /** Runs simultâneas do agente (1..5). Default: 1 (sequencial) */
134
134
  concurrency?: number;
135
- /** Intervalo entre polls sem trabalho (mínimo 1_000). Vale o do primeiro register(). Default: 2_000 */
135
+ /** Intervalo entre polls sem trabalho (mínimo 1_000). Default: 2_000 */
136
136
  pollIntervalMs?: number;
137
137
  }
138
- /** Opções de `start()` — task que roda sempre, aberta pelo próprio bot. */
139
- type StartOptions = TaskOptions;
138
+ /** Opções de `start()` — agente sempre ligado, que abre a própria run. */
139
+ type StartOptions = RunOptions;
140
140
  /** Imagem enviada junto de um captureException — com legenda e content-type opcionais. */
141
141
  interface CaptureAttachment {
142
142
  /** Bytes (`Uint8Array`/`ArrayBuffer`/`Buffer`) ou um caminho de arquivo (só em Node) */
@@ -170,8 +170,8 @@ interface ResolvedConfig {
170
170
  baseUrl: string;
171
171
  /** Ingestão de telemetria: <baseUrl>/v1/ingest */
172
172
  ingestEndpoint: string;
173
- /** API de tasks (execução sob demanda): <baseUrl>/v1/tasks */
174
- tasksBaseUrl: string;
173
+ /** API de execuções (poll, runs, itens, anexos): <baseUrl>/v1/runs */
174
+ runsBaseUrl: string;
175
175
  }
176
176
 
177
177
  /**
@@ -299,7 +299,7 @@ declare class Transaction {
299
299
  private readonly client;
300
300
  name: string;
301
301
  readonly op?: string | undefined;
302
- /** Correlaciona a uma execução de task — preenchido automaticamente em hobots.transaction */
302
+ /** Correlaciona a uma execução do agente — preenchido automaticamente em hobots.transaction */
303
303
  private readonly runId?;
304
304
  readonly eventId: string;
305
305
  readonly stepId: string;
@@ -314,7 +314,7 @@ declare class Transaction {
314
314
  private stepGuard?;
315
315
  private lifecycleBacklog;
316
316
  constructor(client: Client | undefined, name: string, op?: string | undefined,
317
- /** Correlaciona a uma execução de task — preenchido automaticamente em hobots.transaction */
317
+ /** Correlaciona a uma execução do agente — preenchido automaticamente em hobots.transaction */
318
318
  runId?: string | undefined);
319
319
  /**
320
320
  * Registra o início/fim de uma step ou transaction: espelha a linha no sink de
@@ -340,6 +340,18 @@ declare class Transaction {
340
340
  setTag(key: string, value: string): this;
341
341
  setStatus(status: string): this;
342
342
  setName(name: string): this;
343
+ /**
344
+ * Envia já as steps raiz finalizadas (e todas as descendentes, fechando as que
345
+ * ficaram abertas) como transactions parciais da mesma run (`op` hobots.run.flush,
346
+ * `event_id` novo, até 200 steps cada) e as tira da memória. Steps raiz ainda abertas
347
+ * ficam para o próximo flush ou para o `finish()`. É assim que um agente sempre
348
+ * ligado (`start()`), cuja run não termina, entrega as etapas enquanto processa.
349
+ * Devolve quantas steps foram enviadas.
350
+ */
351
+ flush(): number;
352
+ /** Entrega já (com teto) o que está na fila do transport — as transactions parciais inclusive. */
353
+ drain(timeoutMs: number): Promise<void>;
354
+ private payload;
343
355
  finish(): void;
344
356
  }
345
357
 
@@ -475,7 +487,6 @@ interface RunProgressReporter {
475
487
  */
476
488
  interface RunContext {
477
489
  readonly runId: string;
478
- readonly task: string;
479
490
  /** Params da solicitação (formulário do app); `{}` no modo start */
480
491
  readonly params: Record<string, unknown>;
481
492
  /** Log bufferizado — enviado ao servidor em PATCHes incrementais com throttle. Nunca lança. */
@@ -490,6 +501,14 @@ interface RunContext {
490
501
  * medir as etapas (steps); elas aparecem como waterfall na aba de performance da execução.
491
502
  */
492
503
  readonly transaction: Transaction;
504
+ /**
505
+ * Entrega já o que a execução fez: as steps raiz finalizadas viram transactions parciais
506
+ * (waterfall da Central sem esperar a run terminar) e itens, logs e progresso pendentes
507
+ * saem sem esperar o throttle. Quem decide quando chamar é o bot — num agente sempre
508
+ * ligado (`start()`), ao fim de cada rodada que processou itens. Aguarda a entrega com
509
+ * teto (`timeoutMs`, default 15s) e nunca lança.
510
+ */
511
+ flush(timeoutMs?: number): Promise<void>;
493
512
  /** Dispara em cancelamento (run cancelada no app), timeout ou shutdown — cancelamento cooperativo */
494
513
  readonly signal: AbortSignal;
495
514
  /**
@@ -503,7 +522,7 @@ interface RunContext {
503
522
  retry<T>(fn: (attempt: number) => T | Promise<T>, options?: RetryOptions): Promise<T>;
504
523
  }
505
524
  /** O retorno do handler é ignorado — nada além de status/logs/erro é enviado ao servidor. */
506
- type TaskHandler<P = Record<string, unknown>> = (params: P, ctx: RunContext) => void | Promise<void>;
525
+ type RunHandler<P = Record<string, unknown>> = (params: P, ctx: RunContext) => void | Promise<void>;
507
526
 
508
527
  /**
509
528
  * O objeto global do SDK: as funções do processo (register/start/close/captureException/
@@ -511,10 +530,13 @@ type TaskHandler<P = Record<string, unknown>> = (params: P, ctx: RunContext) =>
511
530
  * resolvido a cada acesso — funciona de qualquer módulo, sem passar `ctx` de mão em mão.
512
531
  */
513
532
  interface Hobots extends RunContext {
514
- /** Task sob demanda: executada a cada solicitação do app (formulário/agendamento) via polling. */
515
- register<P = Record<string, unknown>>(task: string, handler: TaskHandler<P>, options?: RegisterOptions): void;
516
- /** Task sempre-ligada: o bot abre a própria run e roda o handler; a plataforma recebe logs, itens e progresso. */
517
- start(task: string, handler: TaskHandler, options?: StartOptions): void;
533
+ /**
534
+ * Agente sob demanda: o handler roda a cada solicitação do app (formulário/agendamento), via polling.
535
+ * O agente é a própria tarefa: uma chamada por processo (register OU start).
536
+ */
537
+ register<P = Record<string, unknown>>(handler: RunHandler<P>, options?: RegisterOptions): void;
538
+ /** Agente sempre ligado: abre a própria run e roda o handler; a plataforma recebe logs, itens e progresso. */
539
+ start(handler: RunHandler, options?: StartOptions): void;
518
540
  /** Encerra tudo (polling, runs em voo, heartbeat, flush final). Chame antes do processo terminar. */
519
541
  close(timeoutMs?: number): Promise<boolean>;
520
542
  /** Captura uma exceção como issue (módulo Issues). Retorna o event_id. */
@@ -530,11 +552,11 @@ declare global {
530
552
  var hobots: Hobots;
531
553
  }
532
554
  declare const hobots: Hobots;
533
- declare const register: <P = Record<string, unknown>>(task: string, handler: TaskHandler<P>, options?: RegisterOptions) => void;
534
- declare const start: (task: string, handler: TaskHandler, options?: StartOptions) => void;
555
+ declare const register: <P = Record<string, unknown>>(handler: RunHandler<P>, options?: RegisterOptions) => void;
556
+ declare const start: (handler: RunHandler, options?: StartOptions) => void;
535
557
  declare const close: (timeoutMs?: number) => Promise<boolean>;
536
558
  declare const captureException: (error: unknown, hint?: CaptureHint) => string | undefined;
537
559
  declare const retry: <T>(fn: (attempt: number) => T | Promise<T>, options?: RetryOptions) => Promise<T>;
538
560
  declare const image: (input: AttachInput, options?: ImageOptions) => ImageAttachment;
539
561
 
540
- 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 };
562
+ 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 };