hobots 1.9.0 → 1.9.2

package/dist/index.d.cts

@@ -1,6 +1,9 @@
 import { Breadcrumb, EventUser, Severity, EventPayload, TransactionPayload, HeartbeatPayload, StepStatus, RunLogLevel, StepData, RunAttachmentContentType } from './protocol.cjs';
 export { AgentInfo, Envelope, EnvelopeItem, ExceptionData, PollRequest, PollResponse, RunAttachmentConfirmRequest, RunAttachmentConfirmResponse, RunAttachmentCreateRequest, RunAttachmentCreateResponse, RunDescriptor, RunError, 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;
+
 /** API oficial da Hobots — o SDK sempre fala com ela em produção. */
 declare const DEFAULT_BASE_URL = "https://api2.hobots.app";
 interface ResolvedConfig {
@@ -123,31 +126,6 @@ declare class Transaction {
     finish(): void;
 }
 
-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;
-
 /** 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: 5_000 (mínimo 1_000) */
@@ -168,6 +146,13 @@ interface TasksOptions {
      * 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
@@ -202,22 +187,6 @@ interface RunContext {
     throwIfCanceled(): void;
     /** Sleep cancelável: rejeita com `RunCanceled` se ctx.signal disparar antes de ms. */
     sleep(ms: number): Promise<void>;
-    /**
-     * Anexa uma imagem (print da tela) a uma linha de log da execução — a evidência
-     * visual aparece como miniatura junto do log, na aba "logs do agente".
-     *
-     * Aceita bytes (`Uint8Array`/`ArrayBuffer`/`Buffer`) ou um caminho de arquivo
-     * (só em Node). A linha de log é registrada imediatamente; o upload roda em
-     * segundo plano e **nunca bloqueia nem lança** — falhas viram um aviso no log da
-     * run e um `{ ok: false, reason }` no retorno, que pode ser ignorado com `void`.
-     *
-     * PNG, JPEG ou WEBP, até 5 MB, no máximo 20 anexos por execução.
-     *
-     * ```ts
-     * await ctx.attach(await page.screenshot(), { caption: 'portal após o login' });
-     * ```
-     */
-    attach(image: AttachInput, options?: AttachOptions): Promise<AttachResult>;
 }
 /** 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>;
@@ -265,17 +234,43 @@ interface InitOptions {
     /** 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 {
     level?: Severity;
     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;
 }
 
 /** 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). */
+/**
+ * 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, level?: Severity, hint?: CaptureHint): string | undefined;
 /** Registra um breadcrumb — anexado aos próximos eventos como trilha do que aconteceu antes. */
@@ -308,4 +303,4 @@ declare function close(timeoutMs?: number): Promise<boolean>;
 
 declare function scrubSecrets(text: string): string;
 
-export { type AttachFailureReason, type AttachOptions, type AttachResult, Breadcrumb, type BreadcrumbInput, type CaptureHint, Client, DEFAULT_BASE_URL, EventPayload, EventUser, type HeartbeatOptions, HeartbeatPayload, type InitOptions, RunAttachmentContentType, type RunContext, RunLogLevel, Scope, Severity, 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, EventUser, type HeartbeatOptions, HeartbeatPayload, type InitOptions, RunAttachmentContentType, type RunContext, RunLogLevel, Scope, Severity, 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,6 +1,9 @@
 import { Breadcrumb, EventUser, Severity, EventPayload, TransactionPayload, HeartbeatPayload, StepStatus, RunLogLevel, StepData, RunAttachmentContentType } from './protocol.js';
 export { AgentInfo, Envelope, EnvelopeItem, ExceptionData, PollRequest, PollResponse, RunAttachmentConfirmRequest, RunAttachmentConfirmResponse, RunAttachmentCreateRequest, RunAttachmentCreateResponse, RunDescriptor, RunError, 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;
+
 /** API oficial da Hobots — o SDK sempre fala com ela em produção. */
 declare const DEFAULT_BASE_URL = "https://api2.hobots.app";
 interface ResolvedConfig {
@@ -123,31 +126,6 @@ declare class Transaction {
     finish(): void;
 }
 
-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;
-
 /** 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: 5_000 (mínimo 1_000) */
@@ -168,6 +146,13 @@ interface TasksOptions {
      * 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
@@ -202,22 +187,6 @@ interface RunContext {
     throwIfCanceled(): void;
     /** Sleep cancelável: rejeita com `RunCanceled` se ctx.signal disparar antes de ms. */
     sleep(ms: number): Promise<void>;
-    /**
-     * Anexa uma imagem (print da tela) a uma linha de log da execução — a evidência
-     * visual aparece como miniatura junto do log, na aba "logs do agente".
-     *
-     * Aceita bytes (`Uint8Array`/`ArrayBuffer`/`Buffer`) ou um caminho de arquivo
-     * (só em Node). A linha de log é registrada imediatamente; o upload roda em
-     * segundo plano e **nunca bloqueia nem lança** — falhas viram um aviso no log da
-     * run e um `{ ok: false, reason }` no retorno, que pode ser ignorado com `void`.
-     *
-     * PNG, JPEG ou WEBP, até 5 MB, no máximo 20 anexos por execução.
-     *
-     * ```ts
-     * await ctx.attach(await page.screenshot(), { caption: 'portal após o login' });
-     * ```
-     */
-    attach(image: AttachInput, options?: AttachOptions): Promise<AttachResult>;
 }
 /** 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>;
@@ -265,17 +234,43 @@ interface InitOptions {
     /** 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 {
     level?: Severity;
     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;
 }
 
 /** 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). */
+/**
+ * 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, level?: Severity, hint?: CaptureHint): string | undefined;
 /** Registra um breadcrumb — anexado aos próximos eventos como trilha do que aconteceu antes. */
@@ -308,4 +303,4 @@ declare function close(timeoutMs?: number): Promise<boolean>;
 
 declare function scrubSecrets(text: string): string;
 
-export { type AttachFailureReason, type AttachOptions, type AttachResult, Breadcrumb, type BreadcrumbInput, type CaptureHint, Client, DEFAULT_BASE_URL, EventPayload, EventUser, type HeartbeatOptions, HeartbeatPayload, type InitOptions, RunAttachmentContentType, type RunContext, RunLogLevel, Scope, Severity, 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, EventUser, type HeartbeatOptions, HeartbeatPayload, type InitOptions, RunAttachmentContentType, type RunContext, RunLogLevel, Scope, Severity, 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.js

@@ -103,7 +103,7 @@ function scrubSecrets(text) {
 
 // src/utils.ts
 var SDK_NAME = "hobots";
-var SDK_VERSION = true ? "1.9.0" : "0.0.0-dev";
+var SDK_VERSION = true ? "1.9.1" : "0.0.0-dev";
 function isNode() {
   return typeof process !== "undefined" && typeof process.versions?.node === "string";
 }
@@ -1114,8 +1114,7 @@ var RunReporter = class {
       throwIfCanceled: () => {
         if (signal.aborted) throw runCanceledError();
       },
-      sleep: (ms) => cancelableSleep(ms, signal),
-      attach: (image, options) => this.attach(image, options)
+      sleep: (ms) => cancelableSleep(ms, signal)
     };
   }
   context;
@@ -1260,7 +1259,8 @@ var RunReporter = class {
   /**
    * Registra a linha de log com o id do anexo (síncrono, na ordem certa) e dispara
    * o upload em segundo plano. Nunca lança: todo caminho de erro vira `{ ok: false }`
-   * com um aviso no log da run.
+   * com um aviso no log da run. Chega ao handler pelos capture* do SDK — o hint
+   * `attachment` de Hobots.captureException/captureMessage cai aqui via run-context-store.
    */
   async attach(image, options = {}) {
     const id = uuid4();
@@ -1447,6 +1447,9 @@ async function runWithRunContext(store, fn) {
 function currentRunTransaction() {
   return storage?.getStore()?.tx;
 }
+function currentRunAttach() {
+  return storage?.getStore()?.attach;
+}
 
 // src/tasks/shutdown.ts
 var WATCHED_SIGNALS = ["SIGINT", "SIGTERM"];
@@ -1498,6 +1501,7 @@ var MIN_POLL_INTERVAL_MS = 1e3;
 var MAX_CONCURRENCY = 5;
 var POLL_RETRY_DELAYS_MS = [1e3, 4e3, 16e3];
 var AUTH_FAILURE_INTERVAL_MS = 3e4;
+var DEFAULT_CANCEL_GRACE_MS = 1e4;
 function hostname() {
   if (!isNode()) return void 0;
   return process.env.HOSTNAME || process.env.COMPUTERNAME || void 0;
@@ -1516,6 +1520,7 @@ var TaskAgent = class {
     this.taskTimeoutMs = options.taskTimeoutMs;
     this.logFlushIntervalMs = options.logFlushIntervalMs;
     this.cancelCheckIntervalMs = options.cancelCheckIntervalMs;
+    this.cancelGraceMs = options.cancelGraceMs ?? DEFAULT_CANCEL_GRACE_MS;
     this.logger.debug("agente configurado", { baseUrl: config.tasksBaseUrl });
   }
   logger;
@@ -1527,6 +1532,7 @@ var TaskAgent = class {
   taskTimeoutMs;
   logFlushIntervalMs;
   cancelCheckIntervalMs;
+  cancelGraceMs;
   state = "idle";
   timer;
   pollAbort;
@@ -1688,7 +1694,10 @@ var TaskAgent = class {
       }
       this.logger.debug(`executando run ${run.id} (${run.task})`);
       try {
-        await runWithRunContext({ runId: run.id, tx }, () => this.invokeWithTimeout(handler, run, reporter));
+        await runWithRunContext(
+          { runId: run.id, tx, attach: (image, options) => reporter.attach(image, options) },
+          () => this.invokeWithTimeout(handler, run, reporter)
+        );
         await reporter.finalizeAttachments();
         tx.setStatus("ok");
         tx.finish();
@@ -1708,14 +1717,26 @@ var TaskAgent = class {
   }
   async invokeWithTimeout(handler, run, reporter) {
     const invocation = Promise.resolve().then(() => handler(run.params, reporter.context));
-    if (!this.taskTimeoutMs || this.taskTimeoutMs <= 0) {
+    const races = [];
+    if (this.taskTimeoutMs && this.taskTimeoutMs > 0) {
+      races.push(sleep(this.taskTimeoutMs).then(() => TIMEOUT_SENTINEL));
+    }
+    if (this.cancelGraceMs > 0) {
+      races.push(waitForCancelGrace(reporter.context.signal, this.cancelGraceMs).then(() => CANCEL_SENTINEL));
+    }
+    if (races.length === 0) {
       await invocation;
       return;
     }
+    const outcome = await Promise.race([invocation, ...races]);
+    if (outcome !== TIMEOUT_SENTINEL && outcome !== CANCEL_SENTINEL) return;
+    if (outcome === CANCEL_SENTINEL) {
+      this.logger.warn(
+        `run ${run.id} cancelada \u2014 handler n\xE3o respondeu a ctx.signal em ${this.cancelGraceMs}ms, liberando o slot (o handler pode continuar rodando em segundo plano)`
+      );
+      return;
+    }
     const timeoutMs = this.taskTimeoutMs;
-    const timeout = sleep(timeoutMs).then(() => TIMEOUT_SENTINEL);
-    const outcome = await Promise.race([invocation, timeout]);
-    if (outcome !== TIMEOUT_SENTINEL) return;
     reporter.abort();
     invocation.then(() => this.logger.warn(`run ${run.id} terminou depois do timeout de ${timeoutMs}ms`)).catch(() => this.logger.warn(`run ${run.id} falhou depois do timeout de ${timeoutMs}ms (erro descartado)`));
     throw Object.assign(new Error(`timeout ap\xF3s ${timeoutMs}ms (o handler pode continuar em background)`), {
@@ -1724,6 +1745,16 @@ var TaskAgent = class {
   }
 };
 var TIMEOUT_SENTINEL = /* @__PURE__ */ Symbol("task-timeout");
+var CANCEL_SENTINEL = /* @__PURE__ */ Symbol("task-canceled");
+function waitForCancelGrace(signal, graceMs) {
+  return new Promise((resolve) => {
+    if (signal.aborted) {
+      setTimeout(resolve, graceMs);
+      return;
+    }
+    signal.addEventListener("abort", () => setTimeout(resolve, graceMs), { once: true });
+  });
+}
 var MAX_ERROR_MESSAGE_CHARS = 1e4;
 var MAX_ERROR_STACK_CHARS = 2e4;
 function toRunError(error) {
@@ -1778,10 +1809,34 @@ function init(options) {
 function getClient() {
   return client;
 }
+function toRunLogLevel(level) {
+  return level === "fatal" ? "error" : level;
+}
+function forwardAttachment(attachment, message, level) {
+  const attach = currentRunAttach();
+  if (!attach) {
+    client?.logger.warn("attachment descartado \u2014 s\xF3 \xE9 suportado dentro de uma execu\xE7\xE3o de task (register/start)");
+    return;
+  }
+  const withMeta = typeof attachment === "object" && "image" in attachment ? attachment : { image: attachment };
+  void attach(withMeta.image, {
+    message,
+    level: toRunLogLevel(level),
+    caption: withMeta.caption,
+    contentType: withMeta.contentType
+  });
+}
 function captureException(error, hint) {
+  if (hint?.attachment) {
+    const message = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+    forwardAttachment(hint.attachment, message, hint.level ?? "error");
+  }
   return client?.captureException(error, hint, scope);
 }
 function captureMessage(message, level = "info", hint) {
+  if (hint?.attachment) {
+    forwardAttachment(hint.attachment, message, hint.level ?? level);
+  }
   return client?.captureMessage(message, level, hint, scope);
 }
 function addBreadcrumb(crumb) {