@promptbook/cli 0.112.0-99 → 0.113.0-0

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/externalChatRunner/processExternalUserChatJob.ts

@@ -1,4 +1,5 @@
 import type { Json } from '@/src/database/schema';
+import { parseAgentSource } from '../../../../../src/book-2.0/agent-source/parseAgentSource';
 import { createUserChatJobFailureDetails } from '../userChat/createUserChatJobFailureDetails';
 import { claimNextQueuedUserChatJob } from '../userChat/claimNextQueuedUserChatJob';
 import { finalizeUserChatJob } from '../userChat/finalizeUserChatJob';
@@ -6,10 +7,14 @@ import { getUserChat } from '../userChat/getUserChat';
 import { getUserChatJobById } from '../userChat/getUserChatJobById';
 import { persistUserChatJobTerminalState } from '../userChat/persistUserChatJobTerminalState';
 import { provideUserChatJobTable } from '../userChat/provideUserChatJobTable';
+import { createUserChatRunnerProgressCard } from '../userChat/createUserChatRunnerProgressCard';
 import { updateUserChatAssistantMessage } from '../userChat/updateUserChatAssistantMessage';
 import type { UserChatJobRecord } from '../userChat/UserChatJobRecord';
 import type { UserChatJobRow } from '../userChat/UserChatJobRow';
-import { resolvePromptThreadBeforeUserMessage } from '../userChat/userChatMessageLifecycle';
+import {
+    createUserChatRunnerThreadMessages,
+    resolvePromptThreadBeforeUserMessage,
+} from '../userChat/userChatMessageLifecycle';
 import {
     EXTERNAL_USER_CHAT_JOB_ANSWER_TIMEOUT_MS,
     EXTERNAL_USER_CHAT_JOB_PROVIDER,
@@ -148,13 +153,11 @@ async function enqueueExternalUserChatJob(job: UserChatJobRecord): Promise<Proce
         return { didMutate: false, outcome: 'waiting' };
     }
 
-    const threadMessages = [...previousThreadMessages, userMessage]
-        .filter((message) => message.isComplete !== false)
-        .filter((message) => message.sender === 'USER' || message.sender === 'AGENT')
-        .map((message) => ({
-            sender: String(message.sender),
-            content: message.content,
-        }));
+    const threadMessages = createUserChatRunnerThreadMessages({
+        messages: chat.messages,
+        userMessageId: job.userMessageId,
+        resolveInitialAgentMessage: () => parseAgentSource(agentSourceSnapshot.agentSource).initialMessage,
+    });
 
     const repository = await ensureExternalAgentRepository(agentSourceSnapshot);
     const queuedAt = new Date().toISOString();
@@ -186,6 +189,10 @@ async function enqueueExternalUserChatJob(job: UserChatJobRecord): Promise<Proce
             isComplete: false,
             lifecycleState: 'running',
             lifecycleError: undefined,
+            progressCard: createUserChatRunnerProgressCard({
+                runnerKind: 'external',
+                phase: 'queued_for_runner',
+            }),
         }),
     });
 

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

@@ -0,0 +1,36 @@
+import { findAgentByIdentifier, findOwnedAgentByIdentifier, type OwnedAgentRow } from './agentOwnership';
+import { getCurrentUser } from './getCurrentUser';
+import { isUserAdmin } from './isUserAdmin';
+
+/**
+ * Loads one agent for the current caller, enforcing ownership-or-admin write access.
+ *
+ * Resolution order:
+ * 1. Anonymous callers receive `null` so routes can return `403`.
+ * 2. Owners are matched via {@link findOwnedAgentByIdentifier} using the authenticated user id.
+ * 3. Administrators (resolved via {@link isUserAdmin}) fall through to {@link findAgentByIdentifier} so they can manage any agent — including legacy `ADMIN_PASSWORD` admins that have no database user id.
+ *
+ * @param identifier - Permanent id or agent name supplied by the route.
+ * @returns Matching agent row when the caller owns it or is an administrator, otherwise `null`.
+ *
+ * @private internal helper of Agents Server route handlers
+ */
+export async function findAgentForCallerWriteAccess(identifier: string): Promise<OwnedAgentRow | null> {
+    const [currentUser, isAdmin] = await Promise.all([getCurrentUser(), isUserAdmin()]);
+    if (!currentUser) {
+        return null;
+    }
+
+    if (typeof currentUser.id === 'number') {
+        const ownedAgent = await findOwnedAgentByIdentifier(currentUser.id, identifier);
+        if (ownedAgent) {
+            return ownedAgent;
+        }
+    }
+
+    if (!isAdmin) {
+        return null;
+    }
+
+    return findAgentByIdentifier(identifier);
+}

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

@@ -3,6 +3,7 @@ import { cache } from 'react';
 import { $getTableName } from '../database/$getTableName';
 import { $provideSupabaseForServer } from '../database/$provideSupabaseForServer';
 import type { AgentsServerDatabase } from '../database/schema';
+import { isAdminPasswordEqual } from './isAdminPasswordEqual';
 import { getSession } from './session';
 
 /**
@@ -75,7 +76,7 @@ const getCachedCurrentUser = cache(async (): Promise<UserInfo | null> => {
     if (process.env.ADMIN_PASSWORD) {
         const cookieStore = await cookies();
         const adminToken = cookieStore.get('adminToken');
-        if (adminToken?.value === process.env.ADMIN_PASSWORD) {
+        if (adminToken?.value !== undefined && isAdminPasswordEqual(adminToken.value)) {
             return {
                 username: 'admin',
                 isAdmin: true,

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

@@ -1,27 +1,6 @@
 import { string_promptbook_server_url } from '@promptbook-local/types';
 import { getMetadataMap } from '../database/getMetadata';
 
-/**
- * Options that tweak the behavior of `getFederatedServers`.
- *
- * @public exported from `apps/agents-server`
- */
-export type GetFederatedServersOptions = {
-    /**
-     * When set, hide the core server from the resulting list if the metadata flag requests it.
-     *
-     * @private Internal toggle for UI surfaces that should hide the core server.
-     */
-    readonly excludeHiddenCoreServer?: boolean;
-};
-
-/**
- * Metadata key storing the core server URL.
- *
- * @private
- */
-const CORE_SERVER_METADATA_KEY = 'CORE_SERVER';
-
 /**
  * Metadata key storing the comma-separated federated servers list.
  *
@@ -29,67 +8,17 @@ const CORE_SERVER_METADATA_KEY = 'CORE_SERVER';
  */
 const FEDERATED_SERVERS_METADATA_KEY = 'FEDERATED_SERVERS';
 
-/**
- * Metadata key indicating whether the core server should be hidden from UI lists.
- *
- * @private
- */
-const IS_CORE_SERVER_HIDDEN_METADATA_KEY = 'IS_CORE_SERVER_HIDDEN';
-
 /**
  * Reads FEDERATED_SERVERS metadata and returns a normalized list of server URLs.
  *
  * @public exported from `apps/agents-server`
  */
-export async function getFederatedServers(options?: GetFederatedServersOptions): Promise<string_promptbook_server_url[]> {
-    const metadata = await getMetadataMap([
-        FEDERATED_SERVERS_METADATA_KEY,
-        CORE_SERVER_METADATA_KEY,
-        IS_CORE_SERVER_HIDDEN_METADATA_KEY,
-    ]);
+export async function getFederatedServers(): Promise<string_promptbook_server_url[]> {
+    const metadata = await getMetadataMap([FEDERATED_SERVERS_METADATA_KEY]);
     const federatedServersString = metadata[FEDERATED_SERVERS_METADATA_KEY] || '';
-    const rawCoreServer = metadata[CORE_SERVER_METADATA_KEY] || '';
-    const coreServer = rawCoreServer.trim() as string_promptbook_server_url;
 
-    if (!coreServer) {
-        throw new Error('Missing CORE_SERVER metadata value');
-    }
-
-    const federatedServers = federatedServersString
+    return federatedServersString
         .split(',')
         .map((server) => server.trim())
         .filter((server): server is string_promptbook_server_url => server !== '');
-
-    const allServers = [coreServer, ...federatedServers];
-    if (options?.excludeHiddenCoreServer && isCoreServerHidden(metadata)) {
-        const normalizedCoreServer = normalizeServerUrl(coreServer);
-        return allServers.filter((server) => normalizeServerUrl(server) !== normalizedCoreServer);
-    }
-
-    return allServers;
-}
-
-/**
- * Determines if the metadata flag explicitly hides the core server from UI lists.
- *
- * @param metadata - Metadata map containing IS_CORE_SERVER_HIDDEN value.
- * @returns Whether the core server should be hidden.
- *
- * @private Internal helper for filtering UI-friendly lists.
- */
-function isCoreServerHidden(metadata: Record<string, string | null>): boolean {
-    const rawValue = metadata[IS_CORE_SERVER_HIDDEN_METADATA_KEY] || '';
-    return rawValue.trim().toLowerCase() === 'true';
-}
-
-/**
- * Normalizes a server URL by trimming trailing slashes for comparison purposes.
- *
- * @param value - Raw server URL.
- * @returns Normalized server URL.
- *
- * @private Internal helper used when filtering hidden servers.
- */
-function normalizeServerUrl(value: string): string {
-    return value.replace(/\/+$/, '');
 }

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

@@ -3,21 +3,35 @@ import { $provideSupabaseForServer } from '@/src/database/$provideSupabaseForSer
 import type { AgentsServerDatabase } from '@/src/database/schema';
 
 /**
- * Database row shape for `User`.
+ * User row shape needed by durable chat execution.
  */
-type UserRow = AgentsServerDatabase['public']['Tables']['User']['Row'];
+type UserByIdRow = Pick<
+    AgentsServerDatabase['public']['Tables']['User']['Row'],
+    'id' | 'username' | 'isAdmin' | 'profileImageUrl'
+>;
+
+/**
+ * Supabase projection for user fields needed by durable chat execution.
+ */
+const USER_BY_ID_SELECT_COLUMNS = 'id, username, isAdmin, profileImageUrl';
 
 /**
  * Loads one user row by database id.
+ *
+ * @private internal Agents Server user lookup helper
  */
-export async function getUserById(userId: number): Promise<UserRow | null> {
+export async function getUserById(userId: number): Promise<UserByIdRow | null> {
     const supabase = $provideSupabaseForServer();
     const tableName = await $getTableName('User');
-    const { data, error } = await supabase.from(tableName).select('*').eq('id', userId).maybeSingle();
+    const { data, error } = await supabase
+        .from(tableName)
+        .select(USER_BY_ID_SELECT_COLUMNS)
+        .eq('id', userId)
+        .maybeSingle();
 
     if (error) {
         throw new Error(`Failed to resolve user "${userId}": ${error.message}`);
     }
 
-    return (data as UserRow | null) || null;
+    return (data as UserByIdRow | null) || null;
 }