hobots 1.7.1 → 1.7.3

package/dist/index.d.cts

@@ -1,10 +1,10 @@
-import { Breadcrumb, EventUser, Severity, EventPayload, TransactionPayload, CheckInPayload, HeartbeatPayload, SpanStatus, SpanData, CheckInStatus } from './protocol.cjs';
-export { AgentInfo, Envelope, EnvelopeItem, ExceptionData, PollRequest, PollResponse, RunDescriptor, RunError, RunLogEntry, RunLogLevel, RunStatus, RunUpdateRequest, RunUpdateResponse, RunUpdateStatus, StackFrame } from './protocol.cjs';
+import { Breadcrumb, EventUser, Severity, EventPayload, TransactionPayload, CheckInPayload, HeartbeatPayload, RunLogLevel, SpanStatus, SpanData, CheckInStatus } from './protocol.cjs';
+export { AgentInfo, Envelope, EnvelopeItem, ExceptionData, PollRequest, PollResponse, RunDescriptor, RunError, RunLogEntry, RunStatus, RunUpdateRequest, RunUpdateResponse, RunUpdateStatus, StackFrame } from './protocol.cjs';
 
 /** API oficial da Hobots — o SDK sempre fala com ela em produção. */
 declare const DEFAULT_BASE_URL = "https://api2.hobots.app";
 interface ResolvedConfig {
-    /** Client Secret do projeto (enviado como Authorization: Bearer, nunca na URL) */
+    /** Client Secret do agente (enviado como Authorization: Bearer, nunca na URL) */
     key: string;
     baseUrl: string;
     /** Ingestão de telemetria: <baseUrl>/v1/ingest */
@@ -64,6 +64,8 @@ declare class Client {
     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;
 declare class Span {
     private readonly transaction;
     readonly parentSpanId: string;
@@ -100,9 +102,19 @@ declare class Transaction {
     private readonly spans;
     private readonly tags;
     private finished;
+    private lifecycleSink?;
+    private lifecycleBacklog;
     constructor(client: Client | undefined, name: string, op?: string | undefined, sampled?: boolean, 
     /** Correlaciona a uma execução de task — preenchido automaticamente em ctx.tx */
     runId?: string | undefined);
+    /**
+     * Ecoa no terminal o início/fim de um span ou transaction (sempre, independente de
+     * sampling ou do debug) e espelha a linha no sink de lifecycle, se conectado — é
+     * assim que os eventos de performance também aparecem nos logs da run no app.
+     */
+    emit(kind: 'transaction' | 'span', phase: 'start' | 'finish', label: string, startTs?: string, endTs?: string): void;
+    /** Conecta o espelho de lifecycle (RunReporter) e faz replay do backlog em ordem. */
+    setLifecycleSink(sink: LifecycleSink): void;
     createSpan(parentSpanId: string, op?: string, description?: string): Span;
     /** Span direto da transaction. */
     startChild(op?: string, description?: string): Span;
@@ -178,7 +190,7 @@ interface HeartbeatOptions {
     metadata?: Record<string, unknown>;
 }
 interface InitOptions {
-    /** O Client Secret do projeto (hb_…) — a mesma credencial para telemetria e tasks. Copie em Configurações → Projetos. */
+    /** O Client Secret do agente (hb_…) — a mesma credencial para telemetria e tasks. Copie em Configurações → Agentes. */
     clientSecret: string;
     /** Default: 'production' */
     environment?: string;
@@ -272,4 +284,4 @@ declare function close(timeoutMs?: number): Promise<boolean>;
 
 declare function scrubSecrets(text: string): string;
 
-export { Breadcrumb, type BreadcrumbInput, type CaptureHint, type CheckInOptions, CheckInPayload, CheckInStatus, Client, DEFAULT_BASE_URL, EventPayload, EventUser, type HeartbeatOptions, HeartbeatPayload, type InitOptions, type RunContext, Scope, Severity, Span, SpanData, type TaskHandler, type TasksOptions, Transaction, TransactionPayload, type WithMonitorOptions, addBreadcrumb, captureException, captureMessage, checkIn, close, flush, getClient, init, register, scrubSecrets, setContext, setExtra, setTag, setTags, setUser, start, startTransaction, stop, withMonitor, withScope };
+export { Breadcrumb, type BreadcrumbInput, type CaptureHint, type CheckInOptions, CheckInPayload, CheckInStatus, Client, DEFAULT_BASE_URL, EventPayload, EventUser, type HeartbeatOptions, HeartbeatPayload, type InitOptions, type RunContext, RunLogLevel, Scope, Severity, Span, SpanData, type TaskHandler, type TasksOptions, Transaction, TransactionPayload, type WithMonitorOptions, addBreadcrumb, captureException, captureMessage, checkIn, close, flush, getClient, init, register, scrubSecrets, setContext, setExtra, setTag, setTags, setUser, start, startTransaction, stop, withMonitor, withScope };

package/dist/index.d.ts

@@ -1,10 +1,10 @@
-import { Breadcrumb, EventUser, Severity, EventPayload, TransactionPayload, CheckInPayload, HeartbeatPayload, SpanStatus, SpanData, CheckInStatus } from './protocol.js';
-export { AgentInfo, Envelope, EnvelopeItem, ExceptionData, PollRequest, PollResponse, RunDescriptor, RunError, RunLogEntry, RunLogLevel, RunStatus, RunUpdateRequest, RunUpdateResponse, RunUpdateStatus, StackFrame } from './protocol.js';
+import { Breadcrumb, EventUser, Severity, EventPayload, TransactionPayload, CheckInPayload, HeartbeatPayload, RunLogLevel, SpanStatus, SpanData, CheckInStatus } from './protocol.js';
+export { AgentInfo, Envelope, EnvelopeItem, ExceptionData, PollRequest, PollResponse, RunDescriptor, RunError, RunLogEntry, RunStatus, RunUpdateRequest, RunUpdateResponse, RunUpdateStatus, StackFrame } from './protocol.js';
 
 /** API oficial da Hobots — o SDK sempre fala com ela em produção. */
 declare const DEFAULT_BASE_URL = "https://api2.hobots.app";
 interface ResolvedConfig {
-    /** Client Secret do projeto (enviado como Authorization: Bearer, nunca na URL) */
+    /** Client Secret do agente (enviado como Authorization: Bearer, nunca na URL) */
     key: string;
     baseUrl: string;
     /** Ingestão de telemetria: <baseUrl>/v1/ingest */
@@ -64,6 +64,8 @@ declare class Client {
     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;
 declare class Span {
     private readonly transaction;
     readonly parentSpanId: string;
@@ -100,9 +102,19 @@ declare class Transaction {
     private readonly spans;
     private readonly tags;
     private finished;
+    private lifecycleSink?;
+    private lifecycleBacklog;
     constructor(client: Client | undefined, name: string, op?: string | undefined, sampled?: boolean, 
     /** Correlaciona a uma execução de task — preenchido automaticamente em ctx.tx */
     runId?: string | undefined);
+    /**
+     * Ecoa no terminal o início/fim de um span ou transaction (sempre, independente de
+     * sampling ou do debug) e espelha a linha no sink de lifecycle, se conectado — é
+     * assim que os eventos de performance também aparecem nos logs da run no app.
+     */
+    emit(kind: 'transaction' | 'span', phase: 'start' | 'finish', label: string, startTs?: string, endTs?: string): void;
+    /** Conecta o espelho de lifecycle (RunReporter) e faz replay do backlog em ordem. */
+    setLifecycleSink(sink: LifecycleSink): void;
     createSpan(parentSpanId: string, op?: string, description?: string): Span;
     /** Span direto da transaction. */
     startChild(op?: string, description?: string): Span;
@@ -178,7 +190,7 @@ interface HeartbeatOptions {
     metadata?: Record<string, unknown>;
 }
 interface InitOptions {
-    /** O Client Secret do projeto (hb_…) — a mesma credencial para telemetria e tasks. Copie em Configurações → Projetos. */
+    /** O Client Secret do agente (hb_…) — a mesma credencial para telemetria e tasks. Copie em Configurações → Agentes. */
     clientSecret: string;
     /** Default: 'production' */
     environment?: string;
@@ -272,4 +284,4 @@ declare function close(timeoutMs?: number): Promise<boolean>;
 
 declare function scrubSecrets(text: string): string;
 
-export { Breadcrumb, type BreadcrumbInput, type CaptureHint, type CheckInOptions, CheckInPayload, CheckInStatus, Client, DEFAULT_BASE_URL, EventPayload, EventUser, type HeartbeatOptions, HeartbeatPayload, type InitOptions, type RunContext, Scope, Severity, Span, SpanData, type TaskHandler, type TasksOptions, Transaction, TransactionPayload, type WithMonitorOptions, addBreadcrumb, captureException, captureMessage, checkIn, close, flush, getClient, init, register, scrubSecrets, setContext, setExtra, setTag, setTags, setUser, start, startTransaction, stop, withMonitor, withScope };
+export { Breadcrumb, type BreadcrumbInput, type CaptureHint, type CheckInOptions, CheckInPayload, CheckInStatus, Client, DEFAULT_BASE_URL, EventPayload, EventUser, type HeartbeatOptions, HeartbeatPayload, type InitOptions, type RunContext, RunLogLevel, Scope, Severity, Span, SpanData, type TaskHandler, type TasksOptions, Transaction, TransactionPayload, type WithMonitorOptions, addBreadcrumb, captureException, captureMessage, checkIn, close, flush, getClient, init, register, scrubSecrets, setContext, setExtra, setTag, setTags, setUser, start, startTransaction, stop, withMonitor, withScope };

package/dist/index.js

@@ -33,11 +33,11 @@ function validateBaseUrl(raw, prefix) {
 function resolveConfig(options, prefix = "[hobots]") {
   const key = options.clientSecret?.trim();
   if (!key) {
-    throw new Error(`${prefix} clientSecret ausente \u2014 copie o Client Secret do projeto em Configura\xE7\xF5es \u2192 Projetos`);
+    throw new Error(`${prefix} clientSecret ausente \u2014 copie o Client Secret do agente em Configura\xE7\xF5es \u2192 Agentes`);
   }
   if (!SECRET_PATTERN.test(key)) {
     throw new Error(
-      `${prefix} clientSecret com formato inv\xE1lido (${key.length} caracteres) \u2014 esperado "hb_" + 64 hex; copie o Client Secret do projeto em Configura\xE7\xF5es \u2192 Projetos`
+      `${prefix} clientSecret com formato inv\xE1lido (${key.length} caracteres) \u2014 esperado "hb_" + 64 hex; copie o Client Secret do agente em Configura\xE7\xF5es \u2192 Agentes`
     );
   }
   const baseUrl = validateBaseUrl(envBaseUrl() ?? DEFAULT_BASE_URL, prefix);
@@ -103,7 +103,7 @@ function scrubSecrets(text) {
 
 // src/utils.ts
 var SDK_NAME = "hobots";
-var SDK_VERSION = true ? "1.7.0" : "0.0.0-dev";
+var SDK_VERSION = true ? "1.7.2" : "0.0.0-dev";
 function isNode() {
   return typeof process !== "undefined" && typeof process.versions?.node === "string";
 }
@@ -662,12 +662,6 @@ var Scope = class _Scope {
 function spanId() {
   return uuid4().slice(0, 16);
 }
-function printSpanLog(kind, phase, label, startTs, endTs) {
-  const durationMs = startTs && endTs ? new Date(endTs).getTime() - new Date(startTs).getTime() : void 0;
-  const tag = colorize(`[hobots:${kind}] ${phase.toUpperCase()}`, phase === "finish" ? "green" : "cyan");
-  const suffix = durationMs != null ? ` (${durationMs}ms)` : "";
-  console.log(`${tag} ${label}${suffix}`);
-}
 function spanLabel(op, description) {
   return [op, description].filter(Boolean).join(" \u2014 ") || "(sem nome)";
 }
@@ -698,7 +692,7 @@ var Span = class {
   finish() {
     if (this.endTimestamp) return;
     this.endTimestamp = nowISO();
-    printSpanLog("span", "finish", spanLabel(this.op, this.description), this.startTimestamp, this.endTimestamp);
+    this.transaction.emit("span", "finish", spanLabel(this.op, this.description), this.startTimestamp, this.endTimestamp);
   }
   toJSON() {
     return {
@@ -720,7 +714,7 @@ var Transaction = class {
     this.op = op;
     this.sampled = sampled;
     this.runId = runId;
-    printSpanLog("transaction", "start", op ? `${name} (${op})` : name);
+    this.emit("transaction", "start", op ? `${name} (${op})` : name);
   }
   eventId = uuid4();
   spanId = spanId();
@@ -729,10 +723,36 @@ var Transaction = class {
   spans = [];
   tags = {};
   finished = false;
+  lifecycleSink;
+  // eventos emitidos antes do sink existir (o START da transaction sai no construtor,
+  // antes do RunReporter conectar) — replay no setLifecycleSink
+  lifecycleBacklog = [];
+  /**
+   * Ecoa no terminal o início/fim de um span ou transaction (sempre, independente de
+   * sampling ou do debug) e espelha a linha no sink de lifecycle, se conectado — é
+   * assim que os eventos de performance também aparecem nos logs da run no app.
+   */
+  emit(kind, phase, label, startTs, endTs) {
+    const durationMs = startTs && endTs ? new Date(endTs).getTime() - new Date(startTs).getTime() : void 0;
+    const tag = colorize(`[hobots:${kind}] ${phase.toUpperCase()}`, phase === "finish" ? "green" : "cyan");
+    const suffix = durationMs != null ? ` (${durationMs}ms)` : "";
+    console.log(`${tag} ${label}${suffix}`);
+    const level = phase === "finish" ? "success" : "info";
+    const message = `[${kind}] ${phase.toUpperCase()} ${label}${suffix}`;
+    if (this.lifecycleSink) this.lifecycleSink(level, message);
+    else if (this.lifecycleBacklog.length < 100) this.lifecycleBacklog.push([level, message]);
+  }
+  /** Conecta o espelho de lifecycle (RunReporter) e faz replay do backlog em ordem. */
+  setLifecycleSink(sink) {
+    this.lifecycleSink = sink;
+    const backlog = this.lifecycleBacklog;
+    this.lifecycleBacklog = [];
+    for (const [level, message] of backlog) sink(level, message);
+  }
   createSpan(parentSpanId, op, description) {
     const span = new Span(this, parentSpanId, op, description);
     this.spans.push(span);
-    printSpanLog("span", "start", spanLabel(op, description));
+    this.emit("span", "start", spanLabel(op, description));
     return span;
   }
   /** Span direto da transaction. */
@@ -756,7 +776,7 @@ var Transaction = class {
     this.finished = true;
     for (const span of this.spans) span.finish();
     const endTimestamp = nowISO();
-    printSpanLog(
+    this.emit(
       "transaction",
       "finish",
       this.op ? `${this.name} (${this.op})` : this.name,
@@ -964,6 +984,7 @@ var RunReporter = class {
       error: (message) => this.log("error", message),
       success: (message) => this.log("success", message)
     };
+    tx.setLifecycleSink((level, message) => this.push(level, message));
     const signal = this.abortController.signal;
     this.context = {
       runId,
@@ -1008,10 +1029,25 @@ var RunReporter = class {
     this.clearFlushTimer();
     this.buffer = [];
   }
+  /**
+   * Drena o buffer pendente para o PATCH único do exit path (chame ANTES de kill,
+   * que descarta o buffer). Capado em um chunk — o exit path não tem retry nem fila,
+   * então preserva os logs mais recentes, os mais valiosos na morte do processo.
+   */
+  drainLogs() {
+    this.clearFlushTimer();
+    return this.takeLogs().slice(-MAX_LOGS_PER_PATCH);
+  }
   log(level, message) {
     if (this.dead) return;
     const scrubbed = scrubSecrets(message);
     printRunLog(this.context.task, level, scrubbed);
+    this.push(level, scrubbed, true);
+  }
+  /** Bufferiza uma entrada de log sem eco no terminal (cap, truncate, flush). */
+  push(level, message, alreadyScrubbed = false) {
+    if (this.dead) return;
+    const scrubbed = alreadyScrubbed ? message : scrubSecrets(message);
     if (this.loggedCount >= MAX_LOGS_PER_RUN) {
       this.droppedCount++;
       return;
@@ -1100,10 +1136,16 @@ var RunReporter = class {
     return this.chain;
   }
   enqueue(update) {
-    if (this.dead) return;
+    if (this.dead) {
+      this.salvageLogs(update.logs);
+      return;
+    }
     this.pendingUpdates++;
     this.chain = this.chain.then(async () => {
-      if (this.dead) return;
+      if (this.dead) {
+        this.salvageLogs(update.logs);
+        return;
+      }
       const payload = update.logs && update.logs.length === 0 ? { ...update, logs: void 0 } : update;
       try {
         await this.api.updateRun(this.runId, payload);
@@ -1112,16 +1154,35 @@ var RunReporter = class {
           this.dead = true;
           this.stopCancelWatch();
           this.abort();
-          this.buffer = [];
-          this.logger.warn(`run ${this.runId} cancelada/removida no servidor \u2014 reporte suprimido`);
+          const pending = this.buffer.splice(0, this.buffer.length);
+          this.salvageLogs(pending);
+          this.logger.warn(
+            `run ${this.runId} cancelada/finalizada no servidor \u2014 status suprimido` + (pending.length > 0 ? `, ${pending.length} log(s) enviados como log tardio` : "")
+          );
           return;
         }
+        if (update.logs && update.logs.length > 0) {
+          this.buffer.unshift(...update.logs);
+          this.scheduleFlush();
+        }
         this.logger.error(`update da run ${this.runId} perdido:`, error);
       }
     }).finally(() => {
       this.pendingUpdates--;
     });
   }
+  /**
+   * Best-effort de log tardio: envia logs para uma run já terminal, fora da fila.
+   * O servidor anexa os logs mesmo respondendo 409; erros são engolidos — este é
+   * o último recurso, não um canal confiável.
+   */
+  salvageLogs(logs) {
+    if (!logs || logs.length === 0) return;
+    for (let i = 0; i < logs.length; i += MAX_LOGS_PER_PATCH) {
+      void this.api.updateRunOnce(this.runId, { status: "running", logs: logs.slice(i, i + MAX_LOGS_PER_PATCH) }).catch(() => {
+      });
+    }
+  }
 };
 
 // src/tasks/run-context-store.ts
@@ -1277,9 +1338,14 @@ var TaskAgent = class {
     const pending = [];
     for (const reporter of this.reporters) {
       if (reporter.isDead) continue;
+      const logs = reporter.drainLogs();
       reporter.kill();
       pending.push(
-        this.api.updateRunOnce(reporter.context.runId, { status: "failed", error: { type: "AgentTerminated", message } }, timeoutMs).catch(() => {
+        this.api.updateRunOnce(
+          reporter.context.runId,
+          { status: "failed", error: { type: "AgentTerminated", message }, logs: logs.length > 0 ? logs : void 0 },
+          timeoutMs
+        ).catch(() => {
         })
       );
     }
@@ -1335,7 +1401,7 @@ var TaskAgent = class {
     if (error instanceof TasksApiError && error.status === 401) {
       this.consecutiveAuthFailures++;
       if (this.consecutiveAuthFailures === 1 || this.consecutiveAuthFailures % 10 === 0) {
-        this.logger.error("chave rejeitada (401) \u2014 verifique o Client Secret do projeto em Configura\xE7\xF5es \u2192 Projetos");
+        this.logger.error("chave rejeitada (401) \u2014 verifique o Client Secret do agente em Configura\xE7\xF5es \u2192 Agentes");
       }
       return Math.max(this.pollIntervalMs, AUTH_FAILURE_INTERVAL_MS);
     }
@@ -1378,15 +1444,16 @@ var TaskAgent = class {
       this.logger.debug(`executando run ${run.id} (${run.task})`);
       try {
         await runWithRunContext({ runId: run.id, tx }, () => this.invokeWithTimeout(handler, run, reporter));
-        reporter.reportSuccess();
         tx.setStatus("ok");
+        tx.finish();
+        reporter.reportSuccess();
         this.logger.debug(`run ${run.id} conclu\xEDda`);
       } catch (error) {
-        reporter.reportFailure(toRunError(error));
         tx.setStatus("error");
+        tx.finish();
+        reporter.reportFailure(toRunError(error));
         this.logger.debug(`run ${run.id} falhou: ${String(error)}`);
       }
-      tx.finish();
       await reporter.finalize();
     } finally {
       this.reporters.delete(reporter);