@promptbook/cli 0.112.0-113 → 0.112.0-114

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

@@ -1,7 +1,13 @@
 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 type { ChatMessage } from '@promptbook-local/types';
+import {
+    createUserChatDetailPayload,
+    getUserChat,
+    isFrozenUserChatSource,
+    listUserChatJobs,
+} from '@/src/utils/userChat';
+import { hasPotentiallyPendingAssistantMessages } from '@/src/utils/userChat/hasPotentiallyPendingAssistantMessages';
+import { listUserChatTimeouts } from '@/src/utils/userChatTimeout/userChatTimeoutStore';
 import { NextResponse } from 'next/server';
 import { resolveUserChatScope } from '../../resolveUserChatScope';
 
@@ -136,17 +142,17 @@ export async function GET(request: Request, { params }: { params: Promise<{ agen
                     return false;
                 }
 
-                const payload = await createUserChatDetailPayload(currentChat);
-                const nextSignature = createUserChatDetailSignature(payload);
+                const livePollState = await loadLiveUserChatPollingState(currentChat);
 
-                if (nextSignature !== lastSnapshotSignature) {
-                    lastSnapshotSignature = nextSignature;
+                if (livePollState.signature !== lastSnapshotSignature) {
+                    const payload = await createUserChatDetailPayload(currentChat);
+                    lastSnapshotSignature = createUserChatPollingSignatureFromDetailPayload(payload);
                     if (!enqueueFrame({ type: 'snapshot', payload })) {
                         return false;
                     }
                 }
 
-                return !isFrozenUserChatSource(payload.chat.source) && payload.activeJobs.length > 0;
+                return !isFrozenUserChatSource(currentChat.source) && livePollState.hasActiveJobs;
             };
 
             /**
@@ -211,69 +217,92 @@ export async function GET(request: Request, { params }: { params: Promise<{ agen
 }
 
 /**
- * Builds a stable signature for the user-visible parts of a canonical chat snapshot.
+ * Minimal live poll state used to avoid rebuilding the full chat payload when nothing visible changed.
  */
-function createUserChatDetailSignature(payload: Awaited<ReturnType<typeof createUserChatDetailPayload>>): string {
-    return JSON.stringify({
-        chatId: payload.chat.id,
-        updatedAt: payload.chat.updatedAt,
-        draftMessage: payload.draftMessage || '',
-        messages: payload.messages.map(createUserChatMessageSignature),
-        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,
-            dueAt: timeout.dueAt,
-            cancelRequestedAt: timeout.cancelRequestedAt,
-        })),
-    });
-}
+type LiveUserChatPollState = {
+    signature: string;
+    hasActiveJobs: boolean;
+};
 
 /**
- * Builds one compact stable signature for a user-visible chat message.
+ * Loads the lightweight state needed to decide whether the active chat payload changed.
+ *
+ * The expensive detail payload does job reconciliation, local-runner synchronization, and full
+ * transcript serialization. Polling first with the persisted timestamps + active resource state
+ * keeps long-lived chat streams cheap when the conversation is idle.
+ *
+ * @param chat - Current scoped chat record.
+ * @returns Poll signature plus whether the chat should keep using the active-job cadence.
  */
-function createUserChatMessageSignature(
-    message: Awaited<ReturnType<typeof createUserChatDetailPayload>>['messages'][number],
-): Record<string, unknown> {
+async function loadLiveUserChatPollingState(chat: NonNullable<Awaited<ReturnType<typeof getUserChat>>>): Promise<LiveUserChatPollState> {
+    const shouldInspectActiveJobs = hasPotentiallyPendingAssistantMessages(chat.messages);
+    const [activeJobs, activeTimeouts] = await Promise.all([
+        shouldInspectActiveJobs
+            ? listUserChatJobs({
+                  userId: chat.userId,
+                  agentPermanentId: chat.agentPermanentId,
+                  chatId: chat.id,
+                  onlyActive: true,
+              })
+            : Promise.resolve([]),
+        listUserChatTimeouts({
+            userId: chat.userId,
+            agentPermanentId: chat.agentPermanentId,
+            chatId: chat.id,
+            onlyActive: true,
+        }),
+    ]);
+
     return {
-        id: message.id ?? null,
-        sender: message.sender,
-        isComplete: message.isComplete,
-        lifecycleState: message.lifecycleState ?? null,
-        lifecycleError: message.lifecycleError ?? null,
-        contentLength: message.content.length,
-        contentHash: createStableTextDigest(message.content),
-        replyingTo: message.replyingTo ? JSON.stringify(message.replyingTo) : null,
-        progressCard: message.progressCard ? JSON.stringify(message.progressCard) : null,
-        ongoingToolCalls: createToolCallsSignature(message.ongoingToolCalls),
-        completedToolCalls: createToolCallsSignature(message.completedToolCalls),
-        toolCalls: createToolCallsSignature(message.toolCalls),
+        signature: createUserChatPollingSignature({
+            chatUpdatedAt: chat.updatedAt,
+            draftMessage: chat.draftMessage,
+            activeJobs,
+            activeTimeouts,
+        }),
+        hasActiveJobs: activeJobs.length > 0,
     };
 }
 
 /**
- * Creates one compact stable digest for message text without pulling in heavier hashing helpers.
+ * Builds the polling signature for a fully hydrated detail payload.
  */
-function createStableTextDigest(value: string): string {
-    let hash = 2_166_136_261;
-
-    for (let index = 0; index < value.length; index++) {
-        hash ^= value.charCodeAt(index);
-        hash = Math.imul(hash, 16_777_619);
-    }
-
-    return (hash >>> 0).toString(16);
+function createUserChatPollingSignatureFromDetailPayload(
+    payload: Awaited<ReturnType<typeof createUserChatDetailPayload>>,
+): string {
+    return createUserChatPollingSignature({
+        chatUpdatedAt: payload.chat.updatedAt,
+        draftMessage: payload.draftMessage,
+        activeJobs: payload.activeJobs,
+        activeTimeouts: payload.activeTimeouts,
+    });
 }
 
 /**
- * Serializes optional tool-call arrays for snapshot signature comparisons.
+ * Builds a stable signature for the user-visible state that changes stream snapshots.
  */
-function createToolCallsSignature(toolCalls: ChatMessage['toolCalls']): string | null {
-    return toolCalls && toolCalls.length > 0 ? JSON.stringify(toolCalls) : null;
+function createUserChatPollingSignature(options: {
+    chatUpdatedAt: string;
+    draftMessage: string | null;
+    activeJobs: ReadonlyArray<Awaited<ReturnType<typeof createUserChatDetailPayload>>['activeJobs'][number]>;
+    activeTimeouts: ReadonlyArray<Awaited<ReturnType<typeof createUserChatDetailPayload>>['activeTimeouts'][number]>;
+}): string {
+    return JSON.stringify({
+        updatedAt: options.chatUpdatedAt,
+        draftMessage: options.draftMessage || '',
+        activeJobs: options.activeJobs.map((job) => ({
+            id: job.id,
+            status: job.status,
+            cancelRequestedAt: job.cancelRequestedAt,
+        })),
+        activeTimeouts: options.activeTimeouts.map((timeout) => ({
+            id: timeout.id,
+            status: timeout.status,
+            dueAt: timeout.dueAt,
+            cancelRequestedAt: timeout.cancelRequestedAt,
+            pausedAt: timeout.pausedAt,
+        })),
+    });
 }
 
 /**

package/apps/agents-server/src/app/agents/[agentName]/chat/useAgentChatHistorySyncEffects.ts

@@ -22,13 +22,6 @@ const USER_CHAT_STREAM_RECONNECT_DELAY_MS = 1_500;
  */
 const DISCONNECTED_CHAT_REFRESH_INTERVAL_MS = 4_000;
 
-/**
- * Periodic sidebar/list refresh cadence while the active chat stream is healthy.
- *
- * @private function of useAgentChatHistoryClientState
- */
-const CHAT_LIST_REFRESH_INTERVAL_MS = 20_000;
-
 /**
  * Inputs required to register side effects for durable chat-history synchronization.
  *
@@ -504,7 +497,7 @@ function keepActiveChatStreamConnected(params: {
 }
 
 /**
- * Refreshes the selected chat periodically and on tab visibility/focus changes.
+ * Refreshes the selected chat on disconnect polling and on tab visibility/focus changes.
  *
  * @private function of useAgentChatHistoryClientState
  */
@@ -529,9 +522,6 @@ function registerActiveChatRefreshPolling(params: {
         return undefined;
     }
 
-    const pollIntervalMs = isActiveChatStreamConnected
-        ? CHAT_LIST_REFRESH_INTERVAL_MS
-        : DISCONNECTED_CHAT_REFRESH_INTERVAL_MS;
     const runRefresh = () => {
         if (typeof document !== 'undefined' && document.hidden) {
             return;
@@ -540,7 +530,9 @@ function registerActiveChatRefreshPolling(params: {
         void refreshActiveChat({ preserveDirtyDraft: true });
     };
 
-    const interval = window.setInterval(runRefresh, pollIntervalMs);
+    const interval = isActiveChatStreamConnected
+        ? null
+        : window.setInterval(runRefresh, DISCONNECTED_CHAT_REFRESH_INTERVAL_MS);
     const handleVisibilityChange = () => {
         if (typeof document !== 'undefined' && !document.hidden) {
             runRefresh();
@@ -554,7 +546,9 @@ function registerActiveChatRefreshPolling(params: {
     window.addEventListener('focus', handleFocus);
 
     return () => {
-        window.clearInterval(interval);
+        if (interval !== null) {
+            window.clearInterval(interval);
+        }
         document.removeEventListener('visibilitychange', handleVisibilityChange);
         window.removeEventListener('focus', handleFocus);
     };

package/apps/agents-server/src/database/migrations/2026-06-1300-user-chat-active-read-indexes.sql

@@ -0,0 +1,7 @@
+CREATE INDEX IF NOT EXISTS "prefix_UserChatJob_chatId_userId_agentPermanentId_active_createdAt_idx"
+    ON "prefix_UserChatJob" ("chatId", "userId", "agentPermanentId", "createdAt" ASC)
+    WHERE "status" IN ('QUEUED', 'RUNNING');
+
+CREATE INDEX IF NOT EXISTS "prefix_UserChatTimeout_chatId_userId_agentPermanentId_active_dueAt_idx"
+    ON "prefix_UserChatTimeout" ("chatId", "userId", "agentPermanentId", "dueAt" ASC, "createdAt" ASC)
+    WHERE "status" IN ('QUEUED', 'RUNNING') AND "pausedAt" IS NULL;

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

@@ -102,6 +102,13 @@ async function resolveAgentRouteTargetUncached(
         };
     }
 
+    if (!options?.forceRefresh) {
+        const fastLocalRouteTarget = await resolveFastLocalAgentRouteTarget(normalizedReference, localServerUrl);
+        if (fastLocalRouteTarget) {
+            return fastLocalRouteTarget;
+        }
+    }
+
     const resolver = await $provideAgentReferenceResolver({ forceRefresh: options?.forceRefresh });
     let resolvedUrlValue: string;
 
@@ -145,6 +152,37 @@ async function resolveAgentRouteTargetUncached(
     };
 }
 
+/**
+ * Resolves the common local-agent case without constructing the heavier shared reference resolver.
+ *
+ * Normal page and chat routes almost always target one local agent by its stored name or permanent id.
+ * Handling that case up front keeps route resolution cheap while still falling back to the full TEAM/federation
+ * resolver for aliases, remote agents, and fuzzy matches.
+ *
+ * @param reference - Normalized route/reference text.
+ * @param localServerUrl - Normalized URL of the current Agents Server instance.
+ * @returns Local route target or `null` when a direct lookup does not match.
+ */
+async function resolveFastLocalAgentRouteTarget(
+    reference: string,
+    localServerUrl: string,
+): Promise<AgentRouteTarget | null> {
+    const collection = await $provideAgentCollectionForServer();
+    const directMatch = await collection.findAgentBasicInformation(reference);
+
+    if (!directMatch) {
+        return null;
+    }
+
+    const canonicalAgentId = directMatch.permanentId || directMatch.agentName;
+
+    return {
+        kind: 'local',
+        canonicalAgentId,
+        canonicalUrl: `${localServerUrl}${AGENT_PATH_PREFIX}${encodeURIComponent(canonicalAgentId)}`,
+    };
+}
+
 /**
  * Memoized route-target resolver used for normal page rendering.
  */

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

@@ -5,7 +5,7 @@ import { parseAgentSourceWithCommitments } from '../../../../../src/book-2.0/age
 import type { string_book } from '../../../../../src/book-2.0/agent-source/string_book';
 
 /**
- * Commitments safe to use in the immediate answer without triggering slow tools, knowledge, imports, or memory.
+ * Commitments safe to use in the immediate pre-answer without triggering slow tools, knowledge, imports, or memory.
  */
 const IMMEDIATE_USER_CHAT_ANSWER_INSTRUCTION_COMMITMENTS = new Set<string>([
     'PERSONA',
@@ -26,27 +26,30 @@ const IMMEDIATE_USER_CHAT_ANSWER_INSTRUCTION_COMMITMENTS = new Set<string>([
 ]);
 
 /**
- * Prefix added to the immediate answer system message.
+ * Prefix added to the immediate pre-answer system message.
  */
 const IMMEDIATE_USER_CHAT_ANSWER_SYSTEM_PREAMBLE = spaceTrim(`
-    You are preparing a fast draft answer for the user while a slower full agent run continues separately.
-    This response is not the final answer.
-    These immediate-answer rules override any agent instruction below that would make the answer sound final.
+    You are preparing a short in-progress confirmation for the user while a slower full agent run continues separately.
+    This response is not the final answer. It is only a confirmation that the task is being handled.
+    These immediate-answer rules override any agent instruction below that would make the answer sound final or complete.
 
     At the start of every response, clearly say in the user's language:
-    - This is only a draft or preliminary answer, not the final answer.
-    - The final answer will arrive in several minutes after the external service finishes processing.
-    - The final answer can change or correct this draft, so the user should not treat this draft as final.
+    - You understood what the user wants.
+    - You are working on it now or the job has already started.
+    - The final answer will arrive after the background processing finishes.
 
-    After that notice, give a brief useful draft of what is happening or the likely answer.
+    Keep the whole response short, preferably one or two sentences.
+    Do not provide any part of the final answer yet.
+    Do not include code snippets, detailed steps, calculations, drafted content, likely conclusions, or partial deliverables.
+    If helpful, briefly name the kind of work being done, such as writing code, checking something, preparing an answer, or generating an image.
     Answer directly and use only the instructions, conversation, attachments, and general model knowledge available in this request.
     Do not use or claim to have used external tools, memory, knowledge bases, web browsing, search, calendar, email, projects, or teammate agents.
-    Never present this draft as complete or definitive.
-    If the user asks for something that clearly requires those unavailable capabilities, explain that the checked final answer is still being prepared.
+    Never present this message as complete, definitive, or ready to use.
+    If the user asks for something that clearly requires unavailable capabilities, simply say the checked final answer is still being prepared.
 `);
 
 /**
- * Creates the lightweight model requirements used by the immediate answer path.
+ * Creates the lightweight model requirements used by the immediate pre-answer path.
  */
 export function createImmediateUserChatAnswerModelRequirements(
     agentSource: string_book,

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

@@ -1,5 +1,6 @@
 import type { UserChatRecord } from './UserChatRecord';
 import { synchronizeLocalUserChatJobsForChat } from '../localChatRunner/synchronizeLocalUserChatJobs';
+import { hasPotentiallyPendingAssistantMessages } from './hasPotentiallyPendingAssistantMessages';
 import { createUserChatTimeoutActivity } from '../userChatTimeout/createUserChatTimeoutActivity';
 import { listUserChatTimeouts } from '../userChatTimeout/userChatTimeoutStore';
 import { createUserChatSummary } from './createUserChatSummary';
@@ -18,31 +19,45 @@ export async function createUserChatDetailPayload(chat: UserChatRecord): Promise
     activeTimeouts: Awaited<ReturnType<typeof listUserChatTimeouts>>;
 }> {
     let currentChat = chat;
-    const hasSynchronizedLocalJobs = await synchronizeLocalUserChatJobsForChat(currentChat);
-
-    if (hasSynchronizedLocalJobs) {
-        const refreshedChat = await getUserChat({
-            userId: currentChat.userId,
-            agentPermanentId: currentChat.agentPermanentId,
-            chatId: currentChat.id,
-        });
-
-        if (refreshedChat) {
-            currentChat = refreshedChat;
-        }
-    }
-
     let activeJobs = await listUserChatJobs({
         userId: currentChat.userId,
         agentPermanentId: currentChat.agentPermanentId,
         chatId: currentChat.id,
         onlyActive: true,
     });
+    const shouldInspectJobState =
+        activeJobs.length > 0 || hasPotentiallyPendingAssistantMessages(currentChat.messages);
 
-    const hasReconciledJobs = await reconcileUserChatActiveJobs({
-        chat: currentChat,
-        activeJobs,
-    });
+    if (shouldInspectJobState) {
+        const hasSynchronizedLocalJobs = await synchronizeLocalUserChatJobsForChat(currentChat);
+
+        if (hasSynchronizedLocalJobs) {
+            const refreshedChat = await getUserChat({
+                userId: currentChat.userId,
+                agentPermanentId: currentChat.agentPermanentId,
+                chatId: currentChat.id,
+            });
+
+            if (refreshedChat) {
+                currentChat = refreshedChat;
+            }
+
+            activeJobs = await listUserChatJobs({
+                userId: currentChat.userId,
+                agentPermanentId: currentChat.agentPermanentId,
+                chatId: currentChat.id,
+                onlyActive: true,
+            });
+        }
+    }
+
+    const hasReconciledJobs =
+        activeJobs.length > 0
+            ? await reconcileUserChatActiveJobs({
+                  chat: currentChat,
+                  activeJobs,
+              })
+            : false;
 
     if (hasReconciledJobs) {
         const refreshedChat = await getUserChat({

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

@@ -0,0 +1,26 @@
+import type { ChatMessage } from '@promptbook-local/types';
+
+/**
+ * Returns `true` when the current transcript still suggests unfinished assistant work.
+ *
+ * This is intentionally message-based so readers can avoid heavier reconciliation work for
+ * settled chats while still inspecting threads that contain incomplete placeholders.
+ *
+ * @param messages - Current persisted chat transcript.
+ * @returns Whether the transcript still looks unfinished from the UI perspective.
+ * @private internal utility of `userChat`
+ */
+export function hasPotentiallyPendingAssistantMessages(messages: ReadonlyArray<ChatMessage>): boolean {
+    return messages.some((message) => {
+        const sender = String(message.sender || '').toUpperCase();
+        if (sender !== 'AGENT' && sender !== 'MODEL') {
+            return false;
+        }
+
+        return (
+            message.isComplete === false ||
+            message.lifecycleState === 'queued' ||
+            message.lifecycleState === 'running'
+        );
+    });
+}

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

@@ -44,7 +44,7 @@ type RunImmediateUserChatAnswerOptions = {
 };
 
 /**
- * Runs a fast local LLM answer into the incomplete assistant placeholder while the external runner is still working.
+ * Runs a fast local LLM pre-answer into the incomplete assistant placeholder while the external runner is still working.
  */
 export async function runImmediateUserChatAnswer(
     job: UserChatJobRecord,