@promptbook/cli 0.112.0-111 → 0.112.0-113

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;
 }

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

@@ -0,0 +1,237 @@
+import { BOOK_LANGUAGE_VERSION, PROMPTBOOK_ENGINE_VERSION } from '../../../../../src/version';
+
+/**
+ * Default Sentry project DSN for Promptbook Agents Server telemetry.
+ *
+ * @private internal Sentry SDK configuration for Agents Server
+ */
+export const DEFAULT_SENTRY_DSN =
+    'https://986f734e9cddaeeec33e2a360f7d0b62@o4508778158030848.ingest.de.sentry.io/4511534509785168';
+
+/**
+ * Sentry organization slug used by build-time SDK tooling.
+ *
+ * @private internal Sentry SDK configuration for Agents Server
+ */
+export const SENTRY_ORGANIZATION = 'promptbook';
+
+/**
+ * Sentry project slug used by build-time SDK tooling.
+ *
+ * @private internal Sentry SDK configuration for Agents Server
+ */
+export const SENTRY_PROJECT = 's22';
+
+/**
+ * Performance tracing sample rate requested for the Agents Server.
+ *
+ * @private internal Sentry SDK configuration for Agents Server
+ */
+export const SENTRY_TRACES_SAMPLE_RATE = 1.0;
+
+/**
+ * Browser-side targets that should receive distributed tracing headers.
+ *
+ * @private internal Sentry SDK configuration for Agents Server
+ */
+export const SENTRY_TRACE_PROPAGATION_TARGETS: Array<string | RegExp> = [
+    'localhost',
+    /^\/api\//,
+    /^https:\/\/.*\.ptbk\.io\/api\//,
+    /^https:\/\/.*\.vercel\.app\/api\//,
+];
+
+/**
+ * Release name used for Agents Server Sentry events.
+ */
+const AGENTS_SERVER_SENTRY_RELEASE_NAME = 'promptbook-agents-server';
+
+/**
+ * Fallback text used in Sentry tags when a value is not configured.
+ */
+const UNKNOWN_SENTRY_CONTEXT_VALUE = 'unknown';
+
+/**
+ * Maximum length kept for Sentry tag values.
+ */
+const MAX_SENTRY_TAG_VALUE_LENGTH = 200;
+
+/**
+ * Resolves the browser-safe Sentry DSN.
+ *
+ * @returns Browser-safe Sentry DSN.
+ *
+ * @private internal Sentry SDK configuration for Agents Server
+ */
+export function resolveBrowserSentryDsn(): string {
+    return process.env.NEXT_PUBLIC_SENTRY_DSN ?? DEFAULT_SENTRY_DSN;
+}
+
+/**
+ * Resolves the server-side Sentry DSN.
+ *
+ * @returns Server-side Sentry DSN.
+ *
+ * @private internal Sentry SDK configuration for Agents Server
+ */
+export function resolveServerSentryDsn(): string {
+    return process.env.SENTRY_DSN ?? resolveBrowserSentryDsn();
+}
+
+/**
+ * Resolves the most specific deployment environment name available.
+ *
+ * @returns Environment name suitable for Sentry.
+ *
+ * @private internal Sentry SDK configuration for Agents Server
+ */
+export function resolveSentrySdkEnvironment(): string {
+    return (
+        getFirstNonEmptyString(
+            process.env.SENTRY_ENVIRONMENT,
+            process.env.NEXT_PUBLIC_VERCEL_TARGET_ENV,
+            process.env.VERCEL_TARGET_ENV,
+            process.env.NEXT_PUBLIC_VERCEL_ENV,
+            process.env.VERCEL_ENV,
+            process.env.PROMPTBOOK_REPOSITORY_REF,
+            process.env.NODE_ENV,
+        ) ?? UNKNOWN_SENTRY_CONTEXT_VALUE
+    );
+}
+
+/**
+ * Resolves the current deployment commit hash from common hosting environment variables.
+ *
+ * @returns Commit hash or null when unavailable.
+ *
+ * @private internal Sentry SDK configuration for Agents Server
+ */
+export function resolveSentrySdkCommitHash(): string | null {
+    return getFirstNonEmptyString(
+        process.env.NEXT_PUBLIC_VERCEL_GIT_COMMIT_SHA,
+        process.env.VERCEL_GIT_COMMIT_SHA,
+        process.env.PROMPTBOOK_COMMIT_SHA,
+        process.env.GIT_COMMIT_SHA,
+        process.env.COMMIT_SHA,
+        process.env.SOURCE_VERSION,
+    );
+}
+
+/**
+ * Resolves the current repository branch or deployment ref.
+ *
+ * @returns Repository branch/ref or null when unavailable.
+ *
+ * @private internal Sentry SDK configuration for Agents Server
+ */
+export function resolveSentrySdkRepositoryBranch(): string | null {
+    return getFirstNonEmptyString(
+        process.env.NEXT_PUBLIC_VERCEL_GIT_COMMIT_REF,
+        process.env.VERCEL_GIT_COMMIT_REF,
+        process.env.PROMPTBOOK_REPOSITORY_REF,
+        process.env.GIT_BRANCH,
+        process.env.BRANCH_NAME,
+    );
+}
+
+/**
+ * Resolves the Sentry release name for the current Agents Server build.
+ *
+ * @returns Release identifier suitable for Sentry.
+ *
+ * @private internal Sentry SDK configuration for Agents Server
+ */
+export function resolveSentrySdkRelease(): string {
+    const appPackageVersion = normalizeOptionalString(process.env.npm_package_version) ?? PROMPTBOOK_ENGINE_VERSION;
+    const commitHash = resolveSentrySdkCommitHash();
+
+    if (!commitHash) {
+        return `${AGENTS_SERVER_SENTRY_RELEASE_NAME}@${appPackageVersion}`;
+    }
+
+    return `${AGENTS_SERVER_SENTRY_RELEASE_NAME}@${appPackageVersion}+${commitHash}`;
+}
+
+/**
+ * Creates shared filterable Sentry tags for Agents Server events.
+ *
+ * @returns Sanitized Sentry tags.
+ *
+ * @private internal Sentry SDK configuration for Agents Server
+ */
+export function createSentrySdkTags(): Record<string, string> {
+    return createSentryTags({
+        promptbookEngineVersion: PROMPTBOOK_ENGINE_VERSION,
+        bookLanguageVersion: BOOK_LANGUAGE_VERSION,
+        appPackageVersion: normalizeOptionalString(process.env.npm_package_version) ?? PROMPTBOOK_ENGINE_VERSION,
+        commitHash: resolveSentrySdkCommitHash(),
+        repositoryBranch: resolveSentrySdkRepositoryBranch(),
+        deploymentEnvironment: resolveSentrySdkEnvironment(),
+        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,
+        ),
+        nextRuntime: process.env.NEXT_RUNTIME,
+        nodeEnvironment: process.env.NODE_ENV,
+        vercelRegion: process.env.VERCEL_REGION,
+    });
+}
+
+/**
+ * Creates Sentry tag values, preserving missing values as explicit `unknown` markers.
+ *
+ * @param values - Raw tag values.
+ * @returns Sanitized Sentry tags.
+ */
+function createSentryTags(values: Record<string, string | null | undefined>): Record<string, string> {
+    return Object.fromEntries(
+        Object.entries(values).map(([key, value]) => [key, sanitizeSentryTagValue(value)]),
+    ) as Record<string, string>;
+}
+
+/**
+ * Normalizes one value for use as a Sentry tag.
+ *
+ * @param value - Optional tag value.
+ * @returns Non-empty bounded tag value.
+ */
+function sanitizeSentryTagValue(value: string | null | undefined): string {
+    const normalizedValue = normalizeOptionalString(value) ?? UNKNOWN_SENTRY_CONTEXT_VALUE;
+
+    return normalizedValue.replace(/\s+/gu, ' ').slice(0, MAX_SENTRY_TAG_VALUE_LENGTH);
+}
+
+/**
+ * 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/sentryStore.ts

@@ -0,0 +1,187 @@
+/**
+ * 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;
+
+    /**
+     * Sentry release identifier.
+     */
+    release?: string;
+
+    /**
+     * Deployment environment such as production, preview, or staging.
+     */
+    environment?: 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}`);
+    }
+}

package/apps/agents-server/src/utils/externalChatRunner/createExternalAgentRepositoryFiles.ts

@@ -53,9 +53,9 @@ function createExternalAgentRepositoryPackageJson(): string {
             scripts: {
                 start: 'npm run agent:run',
                 'agent:run':
-                    'npx ptbk agent-folder run-agent --agent github-copilot --model gpt-5.4 --thinking-level high --auto-pull --auto-push',
+                    'npx ptbk agent-folder run-agent --harness github-copilot --model gpt-5.4 --thinking-level high --auto-pull --auto-push',
                 'agent-local:run':
-                    'ts-node  ../../promptbook/src/cli/test/ptbk.ts agent-folder run-agent --agent github-copilot --model gpt-5.4 --auto-pull --auto-push',
+                    'ts-node  ../../promptbook/src/cli/test/ptbk.ts agent-folder run-agent --harness github-copilot --model gpt-5.4 --auto-pull --auto-push',
             },
         },
         null,

package/apps/agents-server/src/utils/serverManagement/createManagedServer/bootstrapManagedServer.ts

@@ -47,7 +47,9 @@ export async function bootstrapManagedServer(input: NormalizedCreateServerInput)
         await applyManagedServerMigrations(client, input, sqlRecorder, migrationLogger);
         await seedServerUsers(client, input, sqlRecorder);
         await seedServerMetadata(client, input, sqlRecorder);
-        await seedServerDefaultAgents(client, input, sqlRecorder);
+        if (input.isDefaultAgentsInstalled) {
+            await seedServerDefaultAgents(client, input, sqlRecorder);
+        }
 
         await client.query('COMMIT');
         sqlRecorder.addStatement('COMMIT');

package/apps/agents-server/src/utils/serverManagement/createManagedServer/normalizeCreateServerInput.ts

@@ -51,6 +51,11 @@ export type NormalizedCreateServerInput = {
      * Initial metadata rows inserted during bootstrap.
      */
     readonly metadataEntries: ReadonlyArray<ServerMetadataSeedEntry>;
+
+    /**
+     * Whether bundled default agents from `agents/default` should be created during bootstrap.
+     */
+    readonly isDefaultAgentsInstalled: boolean;
 };
 
 /**
@@ -103,5 +108,6 @@ export function normalizeCreateServerInput(input: CreateServerInput): Normalized
             iconUrl,
             initialSettings: input.initialSettings,
         }),
+        isDefaultAgentsInstalled: input.isDefaultAgentsInstalled !== false,
     };
 }