@promptbook/cli 0.112.0-111 → 0.112.0-113

package/apps/agents-server/src/utils/codeRunnerConfiguration.ts

@@ -37,7 +37,7 @@ export async function readConfiguredCodeRunner(): Promise<ConfiguredCodeRunner>
     >;
 
     return {
-        agent: environmentByKey.PTBK_AGENT || process.env.PTBK_AGENT || 'github-copilot',
+        agent: environmentByKey.PTBK_HARNESS || process.env.PTBK_HARNESS || process.env.PTBK_AGENT || 'github-copilot',
         model: environmentByKey.PTBK_MODEL || process.env.PTBK_MODEL || 'gpt-5.4',
         thinkingLevel: environmentByKey.PTBK_THINKING_LEVEL || process.env.PTBK_THINKING_LEVEL || 'xhigh',
     };

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

@@ -0,0 +1,203 @@
+import { BOOK_LANGUAGE_VERSION, PROMPTBOOK_ENGINE_VERSION } from '../../../../../src/version';
+import {
+    createSentrySdkTags,
+    resolveSentrySdkCommitHash,
+    resolveSentrySdkEnvironment,
+    resolveSentrySdkRelease,
+    resolveSentrySdkRepositoryBranch,
+} from './sentrySdkConfig';
+import type { SentryStorePayload } from './sentryStore';
+
+/**
+ * Shared deployment and runtime context added to every Agents Server Sentry event.
+ */
+type AgentsServerSentryContext = {
+    /**
+     * Sentry release identifier.
+     */
+    readonly release: string;
+
+    /**
+     * Sentry environment identifier.
+     */
+    readonly environment: string;
+
+    /**
+     * Filterable Sentry tags.
+     */
+    readonly tags: Record<string, string>;
+
+    /**
+     * Full non-secret diagnostic context.
+     */
+    readonly extra: Record<string, unknown>;
+};
+
+/**
+ * Adds shared Agents Server release, environment, version, deployment, git, and runtime details.
+ *
+ * @param payload - Event-specific Sentry payload.
+ * @returns Payload enriched with common Agents Server diagnostics.
+ *
+ * @private internal helper for Agents Server Sentry reporting
+ */
+export function enrichSentryStorePayloadWithAgentsServerContext(payload: SentryStorePayload): SentryStorePayload {
+    const context = createAgentsServerSentryContext();
+
+    return {
+        ...payload,
+        release: context.release,
+        environment: context.environment,
+        tags: {
+            ...context.tags,
+            ...payload.tags,
+        },
+        extra: {
+            ...context.extra,
+            ...payload.extra,
+        },
+    };
+}
+
+/**
+ * Creates a current Agents Server diagnostic context matching the admin About page metadata.
+ *
+ * @returns Common Sentry context for one event.
+ *
+ * @private internal helper for Agents Server Sentry reporting
+ */
+export function createAgentsServerSentryContext(): AgentsServerSentryContext {
+    const deploymentEnvironment = resolveSentrySdkEnvironment();
+    const appPackageVersion = normalizeOptionalString(process.env.npm_package_version) ?? PROMPTBOOK_ENGINE_VERSION;
+    const commitHash = resolveSentrySdkCommitHash();
+    const repositoryBranch = resolveSentrySdkRepositoryBranch();
+    const memoryUsage = process.memoryUsage();
+
+    return {
+        release: resolveSentrySdkRelease(),
+        environment: deploymentEnvironment,
+        tags: createSentrySdkTags(),
+        extra: {
+            agentsServer: {
+                versions: {
+                    promptbookEngineVersion: PROMPTBOOK_ENGINE_VERSION,
+                    bookLanguageVersion: BOOK_LANGUAGE_VERSION,
+                    appPackageVersion,
+                    appPackageName: normalizeOptionalString(process.env.npm_package_name),
+                    nextBuildId: normalizeOptionalString(process.env.NEXT_BUILD_ID),
+                    nextDistDirectory: normalizeOptionalString(process.env.NEXT_DIST_DIR),
+                    npmLifecycleEvent: normalizeOptionalString(process.env.npm_lifecycle_event),
+                    npmUserAgent: normalizeOptionalString(process.env.npm_config_user_agent),
+                },
+                deployment: {
+                    environment: deploymentEnvironment,
+                    vercelEnvironment: getFirstNonEmptyString(process.env.NEXT_PUBLIC_VERCEL_ENV, process.env.VERCEL_ENV),
+                    targetEnvironment: getFirstNonEmptyString(
+                        process.env.NEXT_PUBLIC_VERCEL_TARGET_ENV,
+                        process.env.VERCEL_TARGET_ENV,
+                    ),
+                    siteUrl: normalizeOptionalString(process.env.NEXT_PUBLIC_SITE_URL),
+                    vercelUrl: getFirstNonEmptyString(process.env.NEXT_PUBLIC_VERCEL_URL, process.env.VERCEL_URL),
+                    vercelBranchUrl: normalizeOptionalString(process.env.NEXT_PUBLIC_VERCEL_BRANCH_URL),
+                    vercelProductionUrl: normalizeOptionalString(process.env.NEXT_PUBLIC_VERCEL_PROJECT_PRODUCTION_URL),
+                    vercelRegion: normalizeOptionalString(process.env.VERCEL_REGION),
+                    repositoryRef: normalizeOptionalString(process.env.PROMPTBOOK_REPOSITORY_REF),
+                    supabaseTablePrefix: normalizeOptionalString(process.env.SUPABASE_TABLE_PREFIX),
+                    currentWorkingDirectory: process.cwd(),
+                },
+                git: {
+                    provider: getFirstNonEmptyString(
+                        process.env.NEXT_PUBLIC_VERCEL_GIT_PROVIDER,
+                        process.env.VERCEL_GIT_PROVIDER,
+                    ),
+                    repositoryOwner: getFirstNonEmptyString(
+                        process.env.NEXT_PUBLIC_VERCEL_GIT_REPO_OWNER,
+                        process.env.VERCEL_GIT_REPO_OWNER,
+                    ),
+                    repositorySlug: getFirstNonEmptyString(
+                        process.env.NEXT_PUBLIC_VERCEL_GIT_REPO_SLUG,
+                        process.env.VERCEL_GIT_REPO_SLUG,
+                    ),
+                    repositoryId: getFirstNonEmptyString(
+                        process.env.NEXT_PUBLIC_VERCEL_GIT_REPO_ID,
+                        process.env.VERCEL_GIT_REPO_ID,
+                    ),
+                    commitHash,
+                    previousCommitHash: getFirstNonEmptyString(
+                        process.env.NEXT_PUBLIC_VERCEL_GIT_PREVIOUS_SHA,
+                        process.env.VERCEL_GIT_PREVIOUS_SHA,
+                    ),
+                    branch: repositoryBranch,
+                    commitMessage: getFirstNonEmptyString(
+                        process.env.NEXT_PUBLIC_VERCEL_GIT_COMMIT_MESSAGE,
+                        process.env.VERCEL_GIT_COMMIT_MESSAGE,
+                    ),
+                    authorName: getFirstNonEmptyString(
+                        process.env.NEXT_PUBLIC_VERCEL_GIT_COMMIT_AUTHOR_NAME,
+                        process.env.VERCEL_GIT_COMMIT_AUTHOR_NAME,
+                    ),
+                    authorLogin: getFirstNonEmptyString(
+                        process.env.NEXT_PUBLIC_VERCEL_GIT_COMMIT_AUTHOR_LOGIN,
+                        process.env.VERCEL_GIT_COMMIT_AUTHOR_LOGIN,
+                    ),
+                    pullRequestId: getFirstNonEmptyString(
+                        process.env.NEXT_PUBLIC_VERCEL_GIT_PULL_REQUEST_ID,
+                        process.env.VERCEL_GIT_PULL_REQUEST_ID,
+                    ),
+                },
+                runtime: {
+                    nodeVersion: process.version,
+                    nodeEnvironment: normalizeOptionalString(process.env.NODE_ENV),
+                    nextRuntime: normalizeOptionalString(process.env.NEXT_RUNTIME),
+                    processId: process.pid,
+                    processUptimeSeconds: process.uptime(),
+                    hostname: getFirstNonEmptyString(process.env.HOSTNAME, process.env.COMPUTERNAME),
+                    platform: process.platform,
+                    architecture: process.arch,
+                    timezone: Intl.DateTimeFormat().resolvedOptions().timeZone || 'UTC',
+                },
+                memory: {
+                    rssBytes: memoryUsage.rss,
+                    heapUsedBytes: memoryUsage.heapUsed,
+                    heapTotalBytes: memoryUsage.heapTotal,
+                    externalBytes: memoryUsage.external,
+                    arrayBuffersBytes: memoryUsage.arrayBuffers ?? 0,
+                },
+            },
+        },
+    };
+}
+
+/**
+ * Returns the first non-empty string from a list.
+ *
+ * @param values - Candidate values in priority order.
+ * @returns First trimmed string or null.
+ */
+function getFirstNonEmptyString(...values: Array<string | null | undefined>): string | null {
+    for (const value of values) {
+        const normalizedValue = normalizeOptionalString(value);
+
+        if (normalizedValue) {
+            return normalizedValue;
+        }
+    }
+
+    return null;
+}
+
+/**
+ * Trims one optional environment value.
+ *
+ * @param value - Raw optional value.
+ * @returns Trimmed string or null.
+ */
+function normalizeOptionalString(value: string | null | undefined): string | null {
+    if (typeof value !== 'string') {
+        return null;
+    }
+
+    const normalizedValue = value.trim();
+
+    return normalizedValue || null;
+}

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,
+    });
+}