@promptbook/cli 0.112.0-109 → 0.112.0-110

package/apps/agents-server/src/app/agents/[agentName]/api/user-chats/[chatId]/stream/route.ts

@@ -1,6 +1,11 @@
 import { CHAT_STREAM_KEEP_ALIVE_INTERVAL_MS } from '@/src/constants/streaming';
 import { isPrivateModeEnabledFromRequest } from '@/src/utils/privateMode';
-import { createUserChatDetailPayload, getUserChat, isFrozenUserChatSource } from '@/src/utils/userChat';
+import {
+    createUserChatDetailPayload,
+    getUserChat,
+    getUserChatRevision,
+    isFrozenUserChatSource,
+} from '@/src/utils/userChat';
 import type { ChatMessage } from '@promptbook-local/types';
 import { NextResponse } from 'next/server';
 import { resolveUserChatScope } from '../../resolveUserChatScope';
@@ -32,6 +37,11 @@ type UserChatStreamFrame =
           type: 'keepalive';
       };
 
+/**
+ * Lightweight revision shape returned by `getUserChatRevision`.
+ */
+type UserChatRevision = Awaited<ReturnType<typeof getUserChatRevision>>;
+
 /**
  * Streams canonical chat snapshots for one scoped user chat so multiple viewers can observe the same background turn.
  */
@@ -73,6 +83,7 @@ export async function GET(request: Request, { params }: { params: Promise<{ agen
         async start(controller) {
             let isStreamClosed = false;
             let lastSnapshotSignature: string | null = null;
+            let lastRevisionSignature: string | null = null;
             let keepAliveInterval: ReturnType<typeof setInterval> | null = null;
 
             /**
@@ -138,6 +149,24 @@ export async function GET(request: Request, { params }: { params: Promise<{ agen
 
                 const payload = await createUserChatDetailPayload(currentChat);
                 const nextSignature = createUserChatDetailSignature(payload);
+                lastRevisionSignature = createUserChatRevisionSignature({
+                    id: payload.chat.id,
+                    updatedAt: payload.chat.updatedAt,
+                    draftMessage: payload.draftMessage,
+                    source: payload.chat.source,
+                    activeJobs: payload.activeJobs.map((job) => ({
+                        id: job.id,
+                        status: job.status,
+                        cancelRequestedAt: job.cancelRequestedAt,
+                    })),
+                    activeTimeouts: payload.activeTimeouts.map((timeout) => ({
+                        id: timeout.id,
+                        status: timeout.status,
+                        message: timeout.message,
+                        dueAt: timeout.dueAt,
+                        cancelRequestedAt: timeout.cancelRequestedAt,
+                    })),
+                });
 
                 if (nextSignature !== lastSnapshotSignature) {
                     lastSnapshotSignature = nextSignature;
@@ -149,6 +178,32 @@ export async function GET(request: Request, { params }: { params: Promise<{ agen
                 return !isFrozenUserChatSource(payload.chat.source) && payload.activeJobs.length > 0;
             };
 
+            /**
+             * Emits a full snapshot only when an idle chat revision changed.
+             *
+             * @private route helper
+             */
+            const emitLatestSnapshotWhenRevisionChanged = async (): Promise<boolean> => {
+                const currentRevision = await getUserChatRevision({
+                    userId: scopeResult.scope.userId,
+                    viewerIsAdmin: scopeResult.scope.viewerIsAdmin,
+                    agentPermanentId: scopeResult.scope.agentPermanentId,
+                    chatId,
+                });
+
+                if (!currentRevision) {
+                    closeStream();
+                    return false;
+                }
+
+                const nextRevisionSignature = createUserChatRevisionSignature(currentRevision);
+                if (nextRevisionSignature === lastRevisionSignature) {
+                    return false;
+                }
+
+                return emitLatestSnapshot();
+            };
+
             /**
              * Tracks client disconnects so the polling loop can exit promptly.
              *
@@ -165,11 +220,11 @@ export async function GET(request: Request, { params }: { params: Promise<{ agen
             keepAliveInterval.unref?.();
 
             try {
-                let hasActiveJobs = await emitLatestSnapshot();
+                let shouldUseFullPolling = await emitLatestSnapshot();
 
                 while (!isStreamClosed && !request.signal.aborted) {
                     await waitForNextUserChatStreamPoll(
-                        hasActiveJobs
+                        shouldUseFullPolling
                             ? ACTIVE_USER_CHAT_STREAM_POLL_INTERVAL_MS
                             : IDLE_USER_CHAT_STREAM_POLL_INTERVAL_MS,
                         request.signal,
@@ -179,7 +234,9 @@ export async function GET(request: Request, { params }: { params: Promise<{ agen
                         break;
                     }
 
-                    hasActiveJobs = await emitLatestSnapshot();
+                    shouldUseFullPolling = shouldUseFullPolling
+                        ? await emitLatestSnapshot()
+                        : await emitLatestSnapshotWhenRevisionChanged();
                 }
             } catch (error) {
                 if (!isStreamClosed && !request.signal.aborted) {
@@ -210,6 +267,30 @@ export async function GET(request: Request, { params }: { params: Promise<{ agen
     });
 }
 
+/**
+ * Builds a compact signature for idle stream revision checks.
+ */
+function createUserChatRevisionSignature(revision: NonNullable<UserChatRevision>): string {
+    return JSON.stringify({
+        id: revision.id,
+        updatedAt: revision.updatedAt,
+        draftMessage: revision.draftMessage || '',
+        source: revision.source,
+        activeJobs: revision.activeJobs.map((job) => ({
+            id: job.id,
+            status: job.status,
+            cancelRequestedAt: job.cancelRequestedAt,
+        })),
+        activeTimeouts: revision.activeTimeouts.map((timeout) => ({
+            id: timeout.id,
+            status: timeout.status,
+            message: timeout.message || '',
+            dueAt: timeout.dueAt,
+            cancelRequestedAt: timeout.cancelRequestedAt,
+        })),
+    });
+}
+
 /**
  * Builds a stable signature for the user-visible parts of a canonical chat snapshot.
  */
@@ -227,6 +308,7 @@ function createUserChatDetailSignature(payload: Awaited<ReturnType<typeof create
         activeTimeouts: payload.activeTimeouts.map((timeout) => ({
             id: timeout.id,
             status: timeout.status,
+            message: timeout.message || '',
             dueAt: timeout.dueAt,
             cancelRequestedAt: timeout.cancelRequestedAt,
         })),

package/apps/agents-server/src/database/loadAgentsServerEnvFile.ts

@@ -0,0 +1,29 @@
+import * as dotenv from 'dotenv';
+
+/**
+ * Environment variable pointing to the installed Agents Server `.env` file.
+ *
+ * @private utility of standalone database scripts
+ */
+export const AGENTS_SERVER_ENV_FILE_ENV_NAME = 'PTBK_AGENTS_SERVER_ENV_FILE';
+
+/**
+ * Loads Agents Server environment variables for standalone database scripts.
+ *
+ * The installer passes an explicit `.env` file from the installation directory. That file must override ambient
+ * `PTBK_*` values because these scripts often run from the repository checkout while the server runs from the
+ * installation directory, so a stale relative SQLite path would point at a different database.
+ *
+ * @private utility of standalone database scripts
+ */
+export function loadAgentsServerEnvFile(): void {
+    const explicitEnvFilePath = process.env[AGENTS_SERVER_ENV_FILE_ENV_NAME]?.trim();
+    if (explicitEnvFilePath) {
+        const explicitLoadResult = dotenv.config({ path: explicitEnvFilePath, override: true });
+        if (!explicitLoadResult.error) {
+            return;
+        }
+    }
+
+    dotenv.config();
+}

package/apps/agents-server/src/database/migrate.ts

@@ -1,18 +1,13 @@
 import colors from 'colors';
-import * as dotenv from 'dotenv';
 import {
     DATABASE_MIGRATION_APPLIED_BY,
     resolveDatabaseMigrationRuntimeConfiguration,
     runDatabaseMigrations,
 } from './runDatabaseMigrations';
 import { isAgentsServerSqliteMode } from './agentsServerDatabaseMode';
+import { loadAgentsServerEnvFile } from './loadAgentsServerEnvFile';
 
-/**
- * Environment variable pointing to the installed Agents Server `.env` file.
- */
-const AGENTS_SERVER_ENV_FILE_ENV_NAME = 'PTBK_AGENTS_SERVER_ENV_FILE';
-
-loadDatabaseMigrationEnvironment();
+loadAgentsServerEnvFile();
 
 /**
  * Runs manual migration command from CLI arguments.
@@ -57,24 +52,6 @@ async function migrate(): Promise<void> {
     }
 }
 
-/**
- * Loads database migration environment variables.
- *
- * Self-update runs the migration command from the repository checkout, while
- * the deployed Agents Server `.env` lives in the installation directory.
- */
-function loadDatabaseMigrationEnvironment(): void {
-    const explicitEnvFilePath = process.env[AGENTS_SERVER_ENV_FILE_ENV_NAME]?.trim();
-    if (explicitEnvFilePath) {
-        const explicitLoadResult = dotenv.config({ path: explicitEnvFilePath });
-        if (!explicitLoadResult.error) {
-            return;
-        }
-    }
-
-    dotenv.config();
-}
-
 /**
  * Parses optional `--only` flag from CLI arguments.
  *

package/apps/agents-server/src/database/seedDefaultAgents.ts

@@ -1,17 +1,10 @@
-import * as dotenv from 'dotenv';
 import type { SupabaseClient } from '@supabase/supabase-js';
 import { AgentCollectionInSupabase } from '../../../../src/collection/agent-collection/constructors/agent-collection-in-supabase/AgentCollectionInSupabase';
 import type { AgentsDatabaseSchema } from '../../../../src/collection/agent-collection/constructors/agent-collection-in-supabase/AgentsDatabaseSchema';
 import { $provideSupabaseForServer } from './$provideSupabaseForServer';
 import { DEFAULT_AGENT_VISIBILITY } from '../utils/agentVisibility';
 import { loadDefaultAgentBooks } from '../utils/defaultAgents/loadDefaultAgentBooks';
-
-/**
- * Environment variable pointing to the installed Agents Server `.env` file.
- *
- * @private utility of standalone default-agent seeding
- */
-const AGENTS_SERVER_ENV_FILE_ENV_NAME = 'PTBK_AGENTS_SERVER_ENV_FILE';
+import { loadAgentsServerEnvFile } from './loadAgentsServerEnvFile';
 
 /**
  * Environment variable with an explicit default-agent source directory.
@@ -178,30 +171,13 @@ function resolveAgentsDatabaseSupabaseClient(): SupabaseClient<AgentsDatabaseSch
     return $provideSupabaseForServer() as unknown as SupabaseClient<AgentsDatabaseSchema>;
 }
 
-/**
- * Loads the installed Agents Server environment before seeding.
- *
- * @private utility of standalone default-agent seeding
- */
-function loadSeedDefaultAgentsEnvironment(): void {
-    const explicitEnvFilePath = process.env[AGENTS_SERVER_ENV_FILE_ENV_NAME]?.trim();
-    if (explicitEnvFilePath) {
-        const explicitLoadResult = dotenv.config({ path: explicitEnvFilePath });
-        if (!explicitLoadResult.error) {
-            return;
-        }
-    }
-
-    dotenv.config();
-}
-
 /**
  * Runs the standalone default-agent seed command.
  *
  * @private utility of standalone default-agent seeding
  */
 async function runSeedDefaultAgentsCommand(): Promise<void> {
-    loadSeedDefaultAgentsEnvironment();
+    loadAgentsServerEnvFile();
     const result = await seedDefaultAgents();
 
     if (result.createdCount > 0) {

package/apps/agents-server/src/utils/agentRouting/resolveAgentRouteTarget.ts

@@ -1,11 +1,15 @@
 import { $provideServer } from '../../tools/$provideServer';
 import { $provideAgentCollectionForServer } from '../../tools/$provideAgentCollectionForServer';
+import { $getTableName } from '../../database/$getTableName';
+import { $provideSupabaseForServer } from '../../database/$provideSupabaseForServer';
 import { $provideAgentReferenceResolver } from '../agentReferenceResolver/$provideAgentReferenceResolver';
 import { consumeAgentReferenceResolutionIssues } from '../agentReferenceResolver/AgentReferenceResolutionIssue';
 import { parseBookScopedAgentIdentifier } from '../agentReferenceResolver/bookScopedAgentReferences';
+import { buildAgentNameOrIdFilter } from '../agentIdentifier';
 import { resolvePseudoAgentDescriptor } from '../pseudoAgents';
 import { normalizeAgentName } from '../../../../../src/_packages/core.index';
 import type { PseudoAgentKind } from '../../../../../src/book-2.0/agent-source/pseudoAgentReferences';
+import type { AgentsServerDatabase } from '../../database/schema';
 import { cache } from 'react';
 
 /**
@@ -50,6 +54,14 @@ type PseudoAgentRouteTarget = {
     canonicalUrl: string;
 };
 
+/**
+ * Minimal database row needed to resolve one local route target.
+ */
+type LocalAgentRouteRow = Pick<
+    AgentsServerDatabase['public']['Tables']['Agent']['Row'],
+    'agentName' | 'permanentId'
+>;
+
 /**
  * Target returned for an incoming `/agents/:agentId` route value.
  */
@@ -102,6 +114,11 @@ async function resolveAgentRouteTargetUncached(
         };
     }
 
+    const directLocalRouteTarget = await resolveLocalAgentRouteTargetFromDatabase(normalizedReference, localServerUrl);
+    if (directLocalRouteTarget) {
+        return directLocalRouteTarget;
+    }
+
     const resolver = await $provideAgentReferenceResolver({ forceRefresh: options?.forceRefresh });
     let resolvedUrlValue: string;
 
@@ -299,3 +316,42 @@ async function resolveLocalAgentRouteTarget(
         canonicalUrl: `${localServerUrl}${AGENT_PATH_PREFIX}${encodeURIComponent(canonicalAgentId)}`,
     };
 }
+
+/**
+ * Resolves the common local route case with a targeted indexed database lookup.
+ *
+ * The reference resolver has to initialize the full local/federated lookup map.
+ * Most page requests already carry a permanent id or exact local name, so checking
+ * the Agent table first keeps normal navigation from loading every agent profile.
+ *
+ * @param reference - Normalized route reference.
+ * @param localServerUrl - Normalized URL of the current Agents Server instance.
+ * @returns Local route target or `null` when the reference is not a local agent.
+ */
+async function resolveLocalAgentRouteTargetFromDatabase(
+    reference: string,
+    localServerUrl: string,
+): Promise<AgentRouteTarget | null> {
+    const supabase = $provideSupabaseForServer();
+    const agentTable = await $getTableName('Agent');
+    const result = await supabase
+        .from(agentTable)
+        .select('agentName, permanentId')
+        .or(buildAgentNameOrIdFilter(reference))
+        .is('deletedAt', null)
+        .order('createdAt', { ascending: true })
+        .limit(1);
+
+    if (result.error || !result.data || result.data.length === 0) {
+        return null;
+    }
+
+    const agent = result.data[0] as LocalAgentRouteRow;
+    const canonicalAgentId = agent.permanentId || agent.agentName;
+
+    return {
+        kind: 'local',
+        canonicalAgentId,
+        canonicalUrl: `${localServerUrl}${AGENT_PATH_PREFIX}${encodeURIComponent(canonicalAgentId)}`,
+    };
+}

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

@@ -39,6 +39,16 @@ type ImportedAgentCacheRecord = {
      */
     readonly source: string_book;
 
+    /**
+     * Fetch implementation that produced this cached record.
+     */
+    readonly fetchImplementation: typeof fetch;
+
+    /**
+     * Timestamp when the source was last fetched successfully.
+     */
+    readonly cachedAt: number;
+
     /**
      * Last observed ETag returned by the remote `/api/book` endpoint.
      */
@@ -55,6 +65,22 @@ type ImportedAgentCacheRecord = {
  */
 const IMPORTED_AGENT_CACHE = new Map<string, ImportedAgentCacheRecord>();
 
+/**
+ * Freshness window for successful imported agent books.
+ *
+ * This avoids a remote revalidation round trip on every server render while
+ * still allowing federated/default parent updates to appear shortly after.
+ */
+const IMPORTED_AGENT_CACHE_FRESH_TTL_MS = 60_000;
+
+/**
+ * Upper bound for fetching one imported agent book.
+ *
+ * Imported agents are used while rendering agent profiles and lists, so one slow
+ * federated/default parent must not block the entire Agents Server page render.
+ */
+const IMPORTED_AGENT_BOOK_FETCH_TIMEOUT_MS = 3_000;
+
 /**
  * In-flight remote imports deduplicated by canonical agent identifier.
  */
@@ -101,6 +127,26 @@ function createImportCacheKey(
     return agentIdentification.replace(/\/+$/g, '');
 }
 
+/**
+ * Returns `true` when a cached imported agent can be reused without revalidation.
+ *
+ * @param cachedImport - Cached successful import record.
+ * @returns Whether the cached import is still fresh enough for immediate reuse.
+ */
+function isImportedAgentCacheFresh(cachedImport: ImportedAgentCacheRecord): boolean {
+    return Date.now() - cachedImport.cachedAt < IMPORTED_AGENT_CACHE_FRESH_TTL_MS;
+}
+
+/**
+ * Returns `true` when the current fetch implementation can safely reuse the cached import.
+ *
+ * @param cachedImport - Cached successful import record.
+ * @returns Whether the cache was produced by the active fetch implementation.
+ */
+function isImportedAgentCacheCompatible(cachedImport: ImportedAgentCacheRecord): boolean {
+    return cachedImport.fetchImplementation === globalThis.fetch;
+}
+
 /**
  * Extracts one text/book payload from a successful HTTP response.
  *
@@ -153,7 +199,14 @@ export async function importAgent(
         inheritancePath: options?.inheritancePath,
     } satisfies ImportAgentOptions;
     const cacheKey = createImportCacheKey(agentIdentification);
-    const cachedImport = IMPORTED_AGENT_CACHE.get(cacheKey);
+    const storedCachedImport = IMPORTED_AGENT_CACHE.get(cacheKey);
+    const cachedImport =
+        storedCachedImport && isImportedAgentCacheCompatible(storedCachedImport) ? storedCachedImport : undefined;
+
+    if (cachedImport && isImportedAgentCacheFresh(cachedImport)) {
+        return cachedImport.source;
+    }
+
     const existingRequest = PENDING_IMPORTED_AGENT_REQUESTS.get(cacheKey);
     if (existingRequest) {
         return existingRequest;
@@ -175,6 +228,7 @@ export async function importAgent(
             const response: Response = await fetch(agentBookUrl, {
                 cache: 'no-store',
                 headers,
+                signal: AbortSignal.timeout(IMPORTED_AGENT_BOOK_FETCH_TIMEOUT_MS),
             });
 
             if (response.status === 304 && cachedImport) {
@@ -202,6 +256,8 @@ export async function importAgent(
             const source = await readImportedAgentSource(agentIdentification, response);
             IMPORTED_AGENT_CACHE.set(cacheKey, {
                 source,
+                fetchImplementation: globalThis.fetch,
+                cachedAt: Date.now(),
                 etag: response.headers.get('etag'),
                 lastModified: response.headers.get('last-modified'),
             });

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

@@ -19,6 +19,10 @@ type FailedImportedAgentFallbackCacheRecord = {
      * Generated fallback book returned for the failed import.
      */
     readonly fallbackSource: string_book;
+    /**
+     * Fetch implementation that produced this failed-import fallback.
+     */
+    readonly fetchImplementation: typeof fetch;
     /**
      * Cache expiration timestamp in epoch milliseconds.
      */
@@ -122,6 +126,11 @@ function readCachedFailedImportedAgentFallback(cacheKey: string): string_book |
         return null;
     }
 
+    if (cachedFallback.fetchImplementation !== globalThis.fetch) {
+        cachedFailedImportedAgentFallbackByKey.delete(cacheKey);
+        return null;
+    }
+
     return cachedFallback.fallbackSource;
 }
 
@@ -134,6 +143,7 @@ function readCachedFailedImportedAgentFallback(cacheKey: string): string_book |
 function writeCachedFailedImportedAgentFallback(cacheKey: string, fallbackSource: string_book): void {
     cachedFailedImportedAgentFallbackByKey.set(cacheKey, {
         fallbackSource,
+        fetchImplementation: globalThis.fetch,
         expiresAt: Date.now() + FAILED_IMPORTED_AGENT_FALLBACK_CACHE_TTL_MS,
     });
 }

package/apps/agents-server/src/utils/userChat/getUserChatRevision.ts

@@ -0,0 +1,145 @@
+import type { UserChatRow } from './UserChatRow';
+import { provideUserChatTable } from './provideUserChatTable';
+import type { UserChatJobRow } from './UserChatJobRow';
+import { provideUserChatJobTable } from './provideUserChatJobTable';
+import { ACTIVE_USER_CHAT_TIMEOUT_STATUSES } from '../userChatTimeout/userChatTimeoutStore/ACTIVE_USER_CHAT_TIMEOUT_STATUSES';
+import { isMissingUserChatTimeoutRelationError } from '../userChatTimeout/userChatTimeoutStore/isMissingUserChatTimeoutRelationError';
+import { provideUserChatTimeoutTable } from '../userChatTimeout/userChatTimeoutStore/provideUserChatTimeoutTable';
+import type { UserChatTimeoutRow } from '../userChatTimeout/UserChatTimeoutRecord';
+import { USER_CHAT_SOURCES } from './UserChatSource';
+
+/**
+ * Active user-chat job statuses that keep the live chat stream in a faster polling mode.
+ */
+const ACTIVE_USER_CHAT_JOB_STATUSES = ['QUEUED', 'RUNNING'] as const;
+
+/**
+ * Compact active-job shape used only for revision comparison.
+ */
+export type UserChatRevisionJob = Pick<UserChatJobRow, 'id' | 'status' | 'cancelRequestedAt'>;
+
+/**
+ * Compact active-timeout shape used only for revision comparison.
+ */
+export type UserChatRevisionTimeout = Pick<
+    UserChatTimeoutRow,
+    'id' | 'status' | 'message' | 'dueAt' | 'cancelRequestedAt'
+>;
+
+/**
+ * Lightweight revision metadata for detecting whether a chat detail payload changed.
+ */
+export type UserChatRevision = {
+    id: string;
+    updatedAt: string;
+    draftMessage: string | null;
+    source: UserChatRow['source'];
+    activeJobs: Array<UserChatRevisionJob>;
+    activeTimeouts: Array<UserChatRevisionTimeout>;
+};
+
+/**
+ * Loads one scoped chat revision without hydrating the full `messages` JSON payload.
+ */
+export async function getUserChatRevision(options: {
+    userId: number;
+    viewerIsAdmin?: boolean;
+    agentPermanentId: string;
+    chatId: string;
+}): Promise<UserChatRevision | null> {
+    const { userId, viewerIsAdmin = false, agentPermanentId, chatId } = options;
+    const userChatTable = await provideUserChatTable();
+
+    const { data, error } = await userChatTable
+        .select('id, userId, updatedAt, draftMessage, source')
+        .eq('id', chatId)
+        .eq('agentPermanentId', agentPermanentId)
+        .maybeSingle();
+
+    if (error) {
+        throw new Error(`Failed to load user chat revision "${chatId}": ${error.message}`);
+    }
+
+    if (!data) {
+        return null;
+    }
+
+    const row = data as Pick<UserChatRow, 'id' | 'userId' | 'updatedAt' | 'draftMessage' | 'source'>;
+    if (row.source === USER_CHAT_SOURCES.WEB_UI) {
+        if (row.userId !== userId) {
+            return null;
+        }
+    } else if (!viewerIsAdmin) {
+        return null;
+    }
+
+    const [activeJobs, activeTimeouts] = await Promise.all([
+        listUserChatRevisionActiveJobs({ userId: row.userId, agentPermanentId, chatId }),
+        listUserChatRevisionActiveTimeouts({ userId: row.userId, agentPermanentId, chatId }),
+    ]);
+
+    return {
+        id: row.id,
+        updatedAt: row.updatedAt,
+        draftMessage: row.draftMessage,
+        source: row.source,
+        activeJobs,
+        activeTimeouts,
+    };
+}
+
+/**
+ * Lists only active job fields that affect the canonical chat surface.
+ */
+async function listUserChatRevisionActiveJobs(options: {
+    userId: number;
+    agentPermanentId: string;
+    chatId: string;
+}): Promise<Array<UserChatRevisionJob>> {
+    const userChatJobTable = await provideUserChatJobTable();
+    const { data, error } = await userChatJobTable
+        .select('id, status, cancelRequestedAt')
+        .eq('chatId', options.chatId)
+        .eq('userId', options.userId)
+        .eq('agentPermanentId', options.agentPermanentId)
+        .in('status', ACTIVE_USER_CHAT_JOB_STATUSES)
+        .order('createdAt', { ascending: true });
+
+    if (error) {
+        throw new Error(`Failed to load active user chat job revisions for chat "${options.chatId}": ${error.message}`);
+    }
+
+    return (data || []) as Array<UserChatRevisionJob>;
+}
+
+/**
+ * Lists only active timeout fields that affect the canonical chat surface.
+ */
+async function listUserChatRevisionActiveTimeouts(options: {
+    userId: number;
+    agentPermanentId: string;
+    chatId: string;
+}): Promise<Array<UserChatRevisionTimeout>> {
+    const userChatTimeoutTable = await provideUserChatTimeoutTable();
+    const { data, error } = await userChatTimeoutTable
+        .select('id, status, message, dueAt, cancelRequestedAt')
+        .eq('chatId', options.chatId)
+        .eq('userId', options.userId)
+        .eq('agentPermanentId', options.agentPermanentId)
+        .in('status', ACTIVE_USER_CHAT_TIMEOUT_STATUSES)
+        .is('pausedAt', null)
+        .order('dueAt', { ascending: true })
+        .order('createdAt', { ascending: true });
+
+    if (error) {
+        if (isMissingUserChatTimeoutRelationError(error)) {
+            return [];
+        }
+
+        throw new Error(
+            `Failed to load active user chat timeout revisions for chat "${options.chatId}": ${error.message}`,
+        );
+    }
+
+    return (data || []) as Array<UserChatRevisionTimeout>;
+}

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

@@ -13,6 +13,7 @@ export { getUserChat } from './userChat/getUserChat';
 export { getUserChatJob } from './userChat/getUserChatJob';
 export { getUserChatJobById } from './userChat/getUserChatJobById';
 export { getUserChatJobByClientMessageId } from './userChat/getUserChatJobByClientMessageId';
+export { getUserChatRevision } from './userChat/getUserChatRevision';
 export { heartbeatUserChatJob } from './userChat/heartbeatUserChatJob';
 export { listExpiredRunningUserChatJobs } from './userChat/listExpiredRunningUserChatJobs';
 export { listUserChats, listUserChatSummarySeeds } from './userChat/listUserChats';