@promptbook/cli 0.112.0-99 → 0.113.0-0

package/apps/agents-server/src/utils/errorReporting/registerServerErrorSentryLogging.ts

@@ -0,0 +1,381 @@
+import { inspect } from 'node:util';
+import * as Sentry from '@sentry/nextjs';
+import { DEFAULT_APPLICATION_ERROR_SERVER_NAME } from './applicationErrorHandling';
+import { createAgentsServerSentryContext } from './agentsServerSentryContext';
+import { enrichSentryStorePayloadWithAgentsServerContext } from './agentsServerSentryContext';
+import {
+    createSentryTimestamp,
+    resolveOptionalSentryDsn,
+    sendSentryStorePayload,
+    type SentryStorePayload,
+} from './sentryStore';
+
+/**
+ * Logger name visible in Sentry events for server-side `console.error` calls.
+ */
+const SENTRY_SERVER_ERROR_LOGGER = 'agents-server.server-error';
+
+/**
+ * Marker used to keep the global console bridge idempotent across hot reloads.
+ */
+const SERVER_ERROR_SENTRY_LOGGING_STATE_SYMBOL = Symbol.for('promptbook.agents-server.serverErrorSentryLoggingState');
+
+/**
+ * Default label used when `console.error` is called without a string or error object.
+ */
+const DEFAULT_SERVER_ERROR_MESSAGE = 'Agents Server console.error';
+
+/**
+ * Keys that commonly hold nested error payloads inside structured logs.
+ */
+const NESTED_ERROR_PROPERTY_NAMES = ['error', 'cause', 'reason'] as const;
+
+/**
+ * Maximum traversal depth when looking for nested error-like objects.
+ */
+const MAX_ERROR_SEARCH_DEPTH = 2;
+
+/**
+ * Shared global state for the server-side console bridge.
+ */
+type ServerErrorSentryLoggingState = {
+    /**
+     * Original console implementation preserved before patching.
+     */
+    originalConsoleError: typeof console.error | null;
+
+    /**
+     * True once the bridge has been installed.
+     */
+    isRegistered: boolean;
+};
+
+/**
+ * Normalized error details extracted from logged values.
+ */
+type LoggedErrorInfo = {
+    /**
+     * Best available error type.
+     */
+    name: string;
+
+    /**
+     * Best available error message.
+     */
+    message: string;
+
+    /**
+     * Optional stack trace when present.
+     */
+    stack?: string;
+};
+
+/**
+ * Registers one server-side `console.error` bridge that forwards logs to Sentry.
+ */
+export function registerServerErrorSentryLogging(): void {
+    const loggingState = getServerErrorSentryLoggingState();
+
+    if (loggingState.isRegistered) {
+        return;
+    }
+
+    loggingState.originalConsoleError = console.error.bind(console);
+    console.error = (...consoleArguments: unknown[]): void => {
+        loggingState.originalConsoleError?.(...consoleArguments);
+
+        const sentryPayload = createServerErrorSentryStorePayload(consoleArguments);
+
+        if (captureServerErrorWithSentrySdk(sentryPayload)) {
+            return;
+        }
+
+        const sentryDsn = resolveOptionalSentryDsn();
+        if (!sentryDsn) {
+            return;
+        }
+
+        // Never log reporting failures through `console.error`, otherwise a broken Sentry configuration would recurse.
+        void sendSentryStorePayload(sentryPayload, sentryDsn).catch(() => undefined);
+    };
+
+    loggingState.isRegistered = true;
+}
+
+/**
+ * Restores the original `console.error` implementation after tests patch it.
+ *
+ * @private test helper for server-side Sentry console forwarding
+ */
+export function $resetServerErrorSentryLoggingForTests(): void {
+    const loggingState = getServerErrorSentryLoggingState();
+
+    if (loggingState.originalConsoleError) {
+        console.error = loggingState.originalConsoleError;
+    }
+
+    loggingState.originalConsoleError = null;
+    loggingState.isRegistered = false;
+}
+
+/**
+ * Returns the shared mutable global state used by the bridge.
+ *
+ * @returns Shared state object reused across reloads.
+ */
+function getServerErrorSentryLoggingState(): ServerErrorSentryLoggingState {
+    const globalObject = globalThis as typeof globalThis & Record<PropertyKey, unknown>;
+
+    const existingLoggingState = globalObject[
+        SERVER_ERROR_SENTRY_LOGGING_STATE_SYMBOL
+    ] as ServerErrorSentryLoggingState | undefined;
+    if (existingLoggingState) {
+        return existingLoggingState;
+    }
+
+    const newLoggingState: ServerErrorSentryLoggingState = {
+        originalConsoleError: null,
+        isRegistered: false,
+    };
+
+    globalObject[SERVER_ERROR_SENTRY_LOGGING_STATE_SYMBOL] = newLoggingState;
+    return newLoggingState;
+}
+
+/**
+ * Creates one Sentry store payload from a `console.error` call.
+ *
+ * @param consoleArguments - Original `console.error` arguments.
+ * @returns Structured Sentry event payload.
+ */
+function createServerErrorSentryStorePayload(consoleArguments: readonly unknown[]): SentryStorePayload {
+    const loggedError = findLoggedErrorInfo(consoleArguments);
+
+    return enrichSentryStorePayloadWithAgentsServerContext({
+        platform: 'javascript',
+        level: 'error',
+        logger: SENTRY_SERVER_ERROR_LOGGER,
+        timestamp: createSentryTimestamp(),
+        message: createServerErrorMessage(consoleArguments, loggedError),
+        server_name: process.env.NEXT_PUBLIC_SERVER_NAME ?? DEFAULT_APPLICATION_ERROR_SERVER_NAME,
+        tags: {
+            source: 'agents-server.console-error',
+        },
+        exception: loggedError
+            ? {
+                  values: [
+                      {
+                          type: loggedError.name,
+                          value: loggedError.message,
+                      },
+                  ],
+              }
+            : undefined,
+        extra: {
+            consoleArguments: consoleArguments.map(serializeConsoleArgument),
+            errorStack: loggedError?.stack ?? null,
+        },
+    });
+}
+
+/**
+ * Captures a server-side console error through the official Sentry SDK when it is initialized.
+ *
+ * @param sentryPayload - Structured event payload created from the original `console.error` call.
+ * @returns True when the SDK accepted the event.
+ */
+function captureServerErrorWithSentrySdk(sentryPayload: SentryStorePayload): boolean {
+    if (!Sentry.getClient()) {
+        return false;
+    }
+
+    const agentsServerContext = createAgentsServerSentryContext();
+
+    Sentry.captureException(createServerErrorSdkException(sentryPayload), {
+        level: sentryPayload.level,
+        tags: {
+            ...agentsServerContext.tags,
+            ...sentryPayload.tags,
+        },
+        extra: {
+            ...agentsServerContext.extra,
+            ...sentryPayload.extra,
+        },
+    });
+
+    return true;
+}
+
+/**
+ * Rebuilds an `Error` object from the structured Sentry payload so the SDK can parse stack frames.
+ *
+ * @param sentryPayload - Structured event payload created from the original `console.error` call.
+ * @returns Error object with the original stack when one was logged.
+ */
+function createServerErrorSdkException(sentryPayload: SentryStorePayload): Error {
+    const error = new Error(sentryPayload.message);
+    const exceptionValue = sentryPayload.exception?.values.at(0);
+    const errorStack = sentryPayload.extra?.errorStack;
+
+    error.name = exceptionValue?.type ?? 'Error';
+
+    if (typeof errorStack === 'string' && errorStack.trim()) {
+        error.stack = errorStack;
+    }
+
+    return error;
+}
+
+/**
+ * Creates one stable event message from a `console.error` call.
+ *
+ * @param consoleArguments - Original `console.error` arguments.
+ * @param loggedError - First extracted error-like payload when available.
+ * @returns Event message suitable for Sentry grouping and scanning.
+ */
+function createServerErrorMessage(
+    consoleArguments: readonly unknown[],
+    loggedError: LoggedErrorInfo | null,
+): string {
+    const stringMessage = consoleArguments
+        .filter((consoleArgument): consoleArgument is string => typeof consoleArgument === 'string')
+        .map((consoleArgument) => consoleArgument.trim())
+        .filter(Boolean)
+        .join(' ')
+        .trim();
+
+    if (stringMessage && loggedError?.message && !stringMessage.includes(loggedError.message)) {
+        return `${stringMessage} ${loggedError.message}`.trim();
+    }
+
+    if (stringMessage) {
+        return stringMessage;
+    }
+
+    if (loggedError?.message) {
+        return loggedError.message;
+    }
+
+    const firstConsoleArgument = consoleArguments.at(0);
+    if (firstConsoleArgument !== undefined) {
+        return serializeConsoleArgument(firstConsoleArgument);
+    }
+
+    return DEFAULT_SERVER_ERROR_MESSAGE;
+}
+
+/**
+ * Extracts the first meaningful error-like payload from structured console arguments.
+ *
+ * @param consoleArguments - Original `console.error` arguments.
+ * @returns Normalized logged error payload or `null`.
+ */
+function findLoggedErrorInfo(consoleArguments: readonly unknown[]): LoggedErrorInfo | null {
+    const visitedObjects = new WeakSet<object>();
+
+    for (const consoleArgument of consoleArguments) {
+        const loggedError = findLoggedErrorInfoInValue(consoleArgument, visitedObjects, 0);
+        if (loggedError) {
+            return loggedError;
+        }
+    }
+
+    return null;
+}
+
+/**
+ * Recursively searches one logged value for error-like payloads.
+ *
+ * @param value - Current logged value.
+ * @param visitedObjects - Cycle guard for nested objects.
+ * @param depth - Current recursion depth.
+ * @returns Normalized logged error payload or `null`.
+ */
+function findLoggedErrorInfoInValue(
+    value: unknown,
+    visitedObjects: WeakSet<object>,
+    depth: number,
+): LoggedErrorInfo | null {
+    if (value instanceof Error) {
+        return {
+            name: value.name || 'Error',
+            message: value.message || DEFAULT_SERVER_ERROR_MESSAGE,
+            stack: value.stack,
+        };
+    }
+
+    if (!value || typeof value !== 'object') {
+        return null;
+    }
+
+    if (visitedObjects.has(value)) {
+        return null;
+    }
+    visitedObjects.add(value);
+
+    const normalizedErrorInfo = normalizeLoggedErrorInfo(value as Record<string, unknown>);
+    if (normalizedErrorInfo) {
+        return normalizedErrorInfo;
+    }
+
+    if (depth >= MAX_ERROR_SEARCH_DEPTH) {
+        return null;
+    }
+
+    for (const propertyName of NESTED_ERROR_PROPERTY_NAMES) {
+        if (!(propertyName in value)) {
+            continue;
+        }
+
+        const nestedErrorInfo = findLoggedErrorInfoInValue(
+            (value as Record<string, unknown>)[propertyName],
+            visitedObjects,
+            depth + 1,
+        );
+        if (nestedErrorInfo) {
+            return nestedErrorInfo;
+        }
+    }
+
+    return null;
+}
+
+/**
+ * Converts one plain object into normalized error details when it looks like an error.
+ *
+ * @param value - Plain logged object.
+ * @returns Normalized logged error payload or `null`.
+ */
+function normalizeLoggedErrorInfo(value: Record<string, unknown>): LoggedErrorInfo | null {
+    const rawErrorName = typeof value.name === 'string' ? value.name.trim() : '';
+    const rawErrorMessage = typeof value.message === 'string' ? value.message.trim() : '';
+    const rawErrorStack = typeof value.stack === 'string' ? value.stack.trim() : '';
+
+    if (!rawErrorName && !rawErrorStack) {
+        return null;
+    }
+
+    return {
+        name: rawErrorName || 'Error',
+        message: rawErrorMessage || DEFAULT_SERVER_ERROR_MESSAGE,
+        stack: rawErrorStack || undefined,
+    };
+}
+
+/**
+ * Serializes one logged console value into a stable string representation.
+ *
+ * @param value - Original console argument.
+ * @returns Stable string suitable for Sentry `extra`.
+ */
+function serializeConsoleArgument(value: unknown): string {
+    if (typeof value === 'string') {
+        return value;
+    }
+
+    return inspect(value, {
+        depth: 6,
+        breakLength: 120,
+        maxArrayLength: 50,
+    });
+}

package/apps/agents-server/src/utils/errorReporting/sendApplicationErrorReportToSentry.ts

@@ -1,146 +1,18 @@
+import * as Sentry from '@sentry/nextjs';
 import type { ApplicationErrorReportPayload } from './applicationErrorHandling';
-
-/**
- * Sentry protocol version used for store endpoint requests.
- */
-const SENTRY_PROTOCOL_VERSION = '7';
-
-/**
- * Endpoint content type used when sending JSON payloads to Sentry.
- */
-const JSON_CONTENT_TYPE = 'application/json';
+import { enrichSentryStorePayloadWithAgentsServerContext } from './agentsServerSentryContext';
+import {
+    createSentryTimestamp,
+    resolveRequiredSentryDsn,
+    sendSentryStorePayload,
+    type SentryStorePayload,
+} from './sentryStore';
 
 /**
  * Logger name visible in Sentry events.
  */
 const SENTRY_APPLICATION_ERROR_LOGGER = 'agents-server.application-error';
 
-/**
- * Number of milliseconds in one second.
- */
-const MILLISECONDS_IN_SECOND = 1000;
-
-/**
- * Minimal Sentry DSN parts needed for store API requests.
- */
-type SentryDsnParts = {
-    /**
-     * Store endpoint derived from DSN host/project.
-     */
-    storeEndpoint: URL;
-};
-
-/**
- * Payload shape submitted to the Sentry store endpoint.
- */
-type SentryStorePayload = {
-    /**
-     * Event platform.
-     */
-    platform: 'javascript';
-
-    /**
-     * Event level.
-     */
-    level: 'error';
-
-    /**
-     * Event logger value.
-     */
-    logger: string;
-
-    /**
-     * Seconds since UNIX epoch.
-     */
-    timestamp: number;
-
-    /**
-     * Human readable message.
-     */
-    message: string;
-
-    /**
-     * Server/deployment name.
-     */
-    server_name: string;
-
-    /**
-     * Diagnostic tags used for filtering.
-     */
-    tags: Record<string, string>;
-
-    /**
-     * Structured exception details.
-     */
-    exception: {
-        /**
-         * Individual exception list.
-         */
-        values: Array<{
-            /**
-             * Exception type.
-             */
-            type: string;
-
-            /**
-             * Exception message.
-             */
-            value: string;
-        }>;
-    };
-
-    /**
-     * Additional diagnostic payload.
-     */
-    extra: Record<string, string | null>;
-};
-
-/**
- * Resolves Sentry DSN from environment.
- *
- * @returns Raw DSN string.
- * @throws Error when DSN is missing.
- */
-function resolveSentryDsn(): string {
-    const dsn = process.env.SENTRY_DSN ?? process.env.NEXT_PUBLIC_SENTRY_DSN;
-    if (!dsn) {
-        throw new Error('Missing Sentry DSN. Configure SENTRY_DSN or NEXT_PUBLIC_SENTRY_DSN.');
-    }
-
-    return dsn;
-}
-
-/**
- * Parses a DSN into pieces required for Sentry store API requests.
- *
- * @param dsn - Raw Sentry DSN.
- * @returns Parsed DSN details.
- * @throws Error when DSN format is invalid.
- */
-function parseSentryDsn(dsn: string): SentryDsnParts {
-    const dsnUrl = new URL(dsn);
-    const pathSegments = dsnUrl.pathname.split('/').filter(Boolean);
-    const projectId = pathSegments.at(-1);
-    const pathPrefix = pathSegments.slice(0, -1).join('/');
-
-    if (!projectId) {
-        throw new Error('Invalid Sentry DSN: missing project ID.');
-    }
-
-    if (!dsnUrl.username) {
-        throw new Error('Invalid Sentry DSN: missing public key.');
-    }
-
-    const basePath = pathPrefix ? `/${pathPrefix}` : '';
-    const storeEndpoint = new URL(`${dsnUrl.protocol}//${dsnUrl.host}${basePath}/api/${projectId}/store/`);
-    storeEndpoint.searchParams.set('sentry_key', dsnUrl.username);
-    storeEndpoint.searchParams.set('sentry_version', SENTRY_PROTOCOL_VERSION);
-
-    return {
-        storeEndpoint,
-    };
-}
-
 /**
  * Creates the Sentry-compatible JSON payload from the application report.
  *
@@ -148,11 +20,11 @@ function parseSentryDsn(dsn: string): SentryDsnParts {
  * @returns Sentry store payload.
  */
 function createSentryStorePayload(report: ApplicationErrorReportPayload): SentryStorePayload {
-    return {
+    return enrichSentryStorePayloadWithAgentsServerContext({
         platform: 'javascript',
         level: 'error',
         logger: SENTRY_APPLICATION_ERROR_LOGGER,
-        timestamp: Date.now() / MILLISECONDS_IN_SECOND,
+        timestamp: createSentryTimestamp(),
         message: report.errorMessage,
         server_name: report.serverName,
         tags: {
@@ -174,7 +46,7 @@ function createSentryStorePayload(report: ApplicationErrorReportPayload): Sentry
             pageUrl: report.pageUrl ?? null,
             reportedAt: report.reportedAt,
         },
-    };
+    });
 }
 
 /**
@@ -183,20 +55,39 @@ function createSentryStorePayload(report: ApplicationErrorReportPayload): Sentry
  * @param report - Structured browser report payload.
  */
 export async function sendApplicationErrorReportToSentry(report: ApplicationErrorReportPayload): Promise<void> {
-    const dsn = resolveSentryDsn();
-    const { storeEndpoint } = parseSentryDsn(dsn);
-    const payload = createSentryStorePayload(report);
+    const sentryPayload = createSentryStorePayload(report);
+
+    if (Sentry.getClient()) {
+        Sentry.captureException(createApplicationErrorSdkException(report, sentryPayload), {
+            level: sentryPayload.level,
+            tags: sentryPayload.tags,
+            extra: sentryPayload.extra,
+        });
+        await Sentry.flush(2000);
+        return;
+    }
 
-    const response = await fetch(storeEndpoint, {
-        method: 'POST',
-        headers: {
-            'Content-Type': JSON_CONTENT_TYPE,
-        },
-        body: JSON.stringify(payload),
-    });
+    await sendSentryStorePayload(sentryPayload, resolveRequiredSentryDsn());
+}
 
-    if (!response.ok) {
-        const responseBody = await response.text();
-        throw new Error(`Sentry rejected application error report (${response.status}): ${responseBody}`);
+/**
+ * Rebuilds an `Error` object from a browser application report so the SDK can parse stack frames.
+ *
+ * @param report - Browser-generated application error report.
+ * @param sentryPayload - Structured Sentry payload created from the report.
+ * @returns Error object with the original browser stack when available.
+ */
+function createApplicationErrorSdkException(
+    report: ApplicationErrorReportPayload,
+    sentryPayload: SentryStorePayload,
+): Error {
+    const error = new Error(sentryPayload.message);
+
+    error.name = report.errorName || 'Error';
+
+    if (report.errorStack?.trim()) {
+        error.stack = report.errorStack;
     }
+
+    return error;
 }