hobots 1.9.0 → 1.9.1

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) */
@@ -202,22 +180,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 +227,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 +296,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) */
@@ -202,22 +180,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 +227,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 +296,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

@@ -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"];
@@ -1688,7 +1691,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();
@@ -1778,10 +1784,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) {