@promptbook/cli 0.112.0-110 → 0.112.0-112

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

@@ -0,0 +1,331 @@
+import { inspect } from 'node:util';
+import { DEFAULT_APPLICATION_ERROR_SERVER_NAME } from './applicationErrorHandling';
+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 sentryDsn = resolveOptionalSentryDsn();
+        if (!sentryDsn) {
+            return;
+        }
+
+        const sentryPayload = createServerErrorSentryStorePayload(consoleArguments);
+
+        // 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 {
+        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',
+            nextRuntime: process.env.NEXT_RUNTIME ?? 'nodejs',
+            nodeEnv: process.env.NODE_ENV ?? 'unknown',
+        },
+        exception: loggedError
+            ? {
+                  values: [
+                      {
+                          type: loggedError.name,
+                          value: loggedError.message,
+                      },
+                  ],
+              }
+            : undefined,
+        extra: {
+            consoleArguments: consoleArguments.map(serializeConsoleArgument),
+            errorStack: loggedError?.stack ?? null,
+            vercelEnv: process.env.VERCEL_ENV ?? null,
+            vercelRegion: process.env.VERCEL_REGION ?? null,
+            vercelUrl: process.env.VERCEL_URL ?? null,
+        },
+    };
+}
+
+/**
+ * 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,16 @@
 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 {
+    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.
  *
@@ -152,7 +22,7 @@ function createSentryStorePayload(report: ApplicationErrorReportPayload): Sentry
         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: {
@@ -183,20 +53,5 @@ 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 response = await fetch(storeEndpoint, {
-        method: 'POST',
-        headers: {
-            'Content-Type': JSON_CONTENT_TYPE,
-        },
-        body: JSON.stringify(payload),
-    });
-
-    if (!response.ok) {
-        const responseBody = await response.text();
-        throw new Error(`Sentry rejected application error report (${response.status}): ${responseBody}`);
-    }
+    await sendSentryStorePayload(createSentryStorePayload(report), resolveRequiredSentryDsn());
 }

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

@@ -0,0 +1,177 @@
+/**
+ * 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';
+
+/**
+ * Number of milliseconds in one second.
+ */
+const MILLISECONDS_IN_SECOND = 1000;
+
+/**
+ * Minimal Sentry DSN parts needed for store endpoint requests.
+ */
+type SentryDsnParts = {
+    /**
+     * Store endpoint derived from DSN host/project.
+     */
+    storeEndpoint: URL;
+};
+
+/**
+ * Payload shape submitted to the Sentry store endpoint.
+ */
+export type SentryStorePayload = {
+    /**
+     * Event platform.
+     */
+    platform: 'javascript';
+
+    /**
+     * Event level.
+     */
+    level: 'error';
+
+    /**
+     * Logger name visible in Sentry events.
+     */
+    logger: string;
+
+    /**
+     * Seconds since UNIX epoch.
+     */
+    timestamp: number;
+
+    /**
+     * Human readable message.
+     */
+    message: string;
+
+    /**
+     * Server/deployment name.
+     */
+    server_name: string;
+
+    /**
+     * Optional diagnostic tags used for filtering.
+     */
+    tags?: Record<string, string>;
+
+    /**
+     * Optional structured exception details.
+     */
+    exception?: {
+        /**
+         * Individual exception list.
+         */
+        values: Array<{
+            /**
+             * Exception type.
+             */
+            type: string;
+
+            /**
+             * Exception message.
+             */
+            value: string;
+        }>;
+    };
+
+    /**
+     * Optional additional diagnostic payload.
+     */
+    extra?: Record<string, unknown>;
+};
+
+/**
+ * Resolves Sentry DSN from environment when configured.
+ *
+ * @returns Raw DSN string or `null` when telemetry is not configured.
+ */
+export function resolveOptionalSentryDsn(): string | null {
+    return process.env.SENTRY_DSN ?? process.env.NEXT_PUBLIC_SENTRY_DSN ?? null;
+}
+
+/**
+ * Resolves Sentry DSN from environment.
+ *
+ * @returns Raw DSN string.
+ * @throws Error when DSN is missing.
+ */
+export function resolveRequiredSentryDsn(): string {
+    const sentryDsn = resolveOptionalSentryDsn();
+
+    if (!sentryDsn) {
+        throw new Error('Missing Sentry DSN. Configure SENTRY_DSN or NEXT_PUBLIC_SENTRY_DSN.');
+    }
+
+    return sentryDsn;
+}
+
+/**
+ * Parses a DSN into pieces required for Sentry store API requests.
+ *
+ * @param sentryDsn - Raw Sentry DSN.
+ * @returns Parsed DSN details.
+ * @throws Error when DSN format is invalid.
+ */
+function parseSentryDsn(sentryDsn: string): SentryDsnParts {
+    const sentryDsnUrl = new URL(sentryDsn);
+    const pathSegments = sentryDsnUrl.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 (!sentryDsnUrl.username) {
+        throw new Error('Invalid Sentry DSN: missing public key.');
+    }
+
+    const basePath = pathPrefix ? `/${pathPrefix}` : '';
+    const storeEndpoint = new URL(`${sentryDsnUrl.protocol}//${sentryDsnUrl.host}${basePath}/api/${projectId}/store/`);
+    storeEndpoint.searchParams.set('sentry_key', sentryDsnUrl.username);
+    storeEndpoint.searchParams.set('sentry_version', SENTRY_PROTOCOL_VERSION);
+
+    return {
+        storeEndpoint,
+    };
+}
+
+/**
+ * Creates a current Sentry timestamp expressed in seconds.
+ *
+ * @returns Current event timestamp in seconds.
+ */
+export function createSentryTimestamp(): number {
+    return Date.now() / MILLISECONDS_IN_SECOND;
+}
+
+/**
+ * Sends one Sentry store payload.
+ *
+ * @param payload - Fully constructed Sentry store payload.
+ * @param sentryDsn - Raw Sentry DSN used to derive the store endpoint.
+ */
+export async function sendSentryStorePayload(payload: SentryStorePayload, sentryDsn: string): Promise<void> {
+    const { storeEndpoint } = parseSentryDsn(sentryDsn);
+
+    const response = await fetch(storeEndpoint, {
+        method: 'POST',
+        headers: {
+            'Content-Type': JSON_CONTENT_TYPE,
+        },
+        body: JSON.stringify(payload),
+    });
+
+    if (!response.ok) {
+        const responseBody = await response.text();
+        throw new Error(`Sentry rejected error report (${response.status}): ${responseBody}`);
+    }
+}