@promptbook/cli 0.114.0-2 → 0.114.0-20

package/apps/agents-server/src/app/agents/[agentName]/chat/AgentGoalChatPlannedMessages.tsx

@@ -0,0 +1,226 @@
+'use client';
+
+import { CalendarRangeIcon, Clock3Icon, RepeatIcon } from 'lucide-react';
+import { useCallback, useEffect, useState } from 'react';
+import { formatTimeoutDurationHuman } from '../../../../../../../src/book-components/Chat/utils/timeoutToolCallPresentation';
+import { useServerLanguage } from '../../../../components/ServerLanguage/ServerLanguageProvider';
+import { cancelAgentUserTimeout, fetchAgentUserTimeouts, type UserChatTimeout } from '../../../../utils/userChatClient';
+import { formatChatTimeoutRemainingTime } from './formatChatTimeoutRemainingTime';
+
+/**
+ * Timeout statuses that still represent a planned wake-up of the agent.
+ *
+ * @private function of AgentGoalChatPlannedMessages
+ */
+const PLANNED_MESSAGE_STATUSES = new Set(['QUEUED', 'RUNNING']);
+
+/**
+ * Refresh cadence that keeps model-created planned messages visible while a goal turn is running.
+ *
+ * @private function of AgentGoalChatPlannedMessages
+ */
+const PLANNED_MESSAGES_REFRESH_INTERVAL_MS = 5_000;
+
+/**
+ * Props consumed by the goal-chat planned-message list.
+ *
+ * @private function of AgentGoalChatPlannedMessages
+ */
+type AgentGoalChatPlannedMessagesProps = {
+    /**
+     * Agent whose planned messages are listed.
+     */
+    readonly agentName: string;
+    /**
+     * Current timestamp used for live countdowns, shared with the surrounding chat surface.
+     */
+    readonly currentTimestamp: number;
+};
+
+/**
+ * Renders one boundary of the window in which a planned message may wake the agent.
+ *
+ * @param boundary - Starting or ending date of the planned message.
+ * @returns Local date-time text, or `∞` for a side of the window which is not bounded.
+ *
+ * @private function of AgentGoalChatPlannedMessages
+ */
+function formatPlannedMessageBoundary(boundary: string | null): string {
+    return boundary === null ? '∞' : new Date(boundary).toLocaleString();
+}
+
+/**
+ * Keeps only the planned messages that can still wake the agent up.
+ *
+ * @private function of AgentGoalChatPlannedMessages
+ */
+function selectPlannedMessages(timeouts: ReadonlyArray<UserChatTimeout>): Array<UserChatTimeout> {
+    return timeouts
+        .filter((timeout) => PLANNED_MESSAGE_STATUSES.has(timeout.status) && !timeout.cancelRequestedAt)
+        .sort((leftTimeout, rightTimeout) => leftTimeout.dueAt.localeCompare(rightTimeout.dueAt));
+}
+
+/**
+ * Lists the planned messages of one agent inside its goal chat, with their due time and cancellation.
+ *
+ * This replaces the former standalone timeout manager page: the agent's own thread is now the single
+ * place where its future wake-ups are visible.
+ *
+ * @private Agents Server presentation logic for the agent goal chat.
+ */
+export function AgentGoalChatPlannedMessages({ agentName, currentTimestamp }: AgentGoalChatPlannedMessagesProps) {
+    const { t: translateText } = useServerLanguage();
+    const [plannedMessages, setPlannedMessages] = useState<ReadonlyArray<UserChatTimeout> | null>(null);
+    const [hasLoadFailed, setHasLoadFailed] = useState(false);
+    const [cancellingTimeoutIds, setCancellingTimeoutIds] = useState<ReadonlyArray<string>>([]);
+
+    const reloadPlannedMessages = useCallback(async () => {
+        try {
+            const payload = await fetchAgentUserTimeouts(agentName);
+            setPlannedMessages(selectPlannedMessages(payload.items));
+            setHasLoadFailed(false);
+        } catch {
+            setHasLoadFailed(true);
+        }
+    }, [agentName]);
+
+    useEffect(() => {
+        void reloadPlannedMessages();
+
+        const refreshInterval = window.setInterval(() => {
+            void reloadPlannedMessages();
+        }, PLANNED_MESSAGES_REFRESH_INTERVAL_MS);
+
+        return () => {
+            window.clearInterval(refreshInterval);
+        };
+    }, [reloadPlannedMessages]);
+
+    const handleCancelPlannedMessage = useCallback(
+        async (timeoutId: string) => {
+            setCancellingTimeoutIds((currentIds) => [...currentIds, timeoutId]);
+
+            try {
+                await cancelAgentUserTimeout(agentName, timeoutId);
+                await reloadPlannedMessages();
+            } catch {
+                setHasLoadFailed(true);
+            } finally {
+                setCancellingTimeoutIds((currentIds) => currentIds.filter((currentId) => currentId !== timeoutId));
+            }
+        },
+        [agentName, reloadPlannedMessages],
+    );
+
+    if (plannedMessages === null && !hasLoadFailed) {
+        return null;
+    }
+
+    return (
+        <section className="mx-4 mt-4 rounded-2xl border border-slate-200 bg-white/90 px-4 py-3 shadow-sm dark:border-slate-700 dark:bg-slate-950/80">
+            <h2 className="text-[11px] font-semibold uppercase tracking-[0.18em] text-slate-500 dark:text-slate-400">
+                {translateText('goalChat.plannedMessagesTitle')}
+            </h2>
+
+            {hasLoadFailed && (
+                <p className="mt-2 text-sm text-red-700 dark:text-red-300">
+                    {translateText('goalChat.plannedMessagesLoadErrorLabel')}
+                </p>
+            )}
+
+            {!hasLoadFailed && plannedMessages !== null && plannedMessages.length === 0 && (
+                <p className="mt-2 text-sm text-slate-500 dark:text-slate-400">
+                    {translateText('goalChat.plannedMessagesEmptyLabel')}
+                </p>
+            )}
+
+            {plannedMessages !== null && plannedMessages.length > 0 && (
+                <ul className="mt-3 space-y-2">
+                    {plannedMessages.map((plannedMessage) => {
+                        const isCancelling = cancellingTimeoutIds.includes(plannedMessage.timeoutId);
+
+                        return (
+                            <li
+                                key={plannedMessage.timeoutId}
+                                className="flex items-start justify-between gap-4 rounded-xl border border-slate-200 bg-slate-50/80 px-3 py-2 dark:border-slate-700 dark:bg-slate-900/60"
+                            >
+                                <div className="min-w-0 flex-1">
+                                    <div className="truncate text-sm font-medium text-slate-800 dark:text-slate-100">
+                                        {plannedMessage.message || translateText('goalChat.plannedMessageDefaultLabel')}
+                                    </div>
+                                    <div className="mt-1 flex flex-wrap items-center gap-x-3 gap-y-1 text-xs font-medium text-amber-700 dark:text-amber-300">
+                                        <span className="inline-flex items-center gap-1.5">
+                                            <Clock3Icon className="h-3.5 w-3.5" />
+                                            <span>
+                                                {formatChatTimeoutRemainingTime(plannedMessage.dueAt, currentTimestamp)}
+                                            </span>
+                                            <span className="text-slate-400 dark:text-slate-500">
+                                                {new Date(plannedMessage.dueAt).toLocaleString()}
+                                            </span>
+                                        </span>
+                                        {plannedMessage.recurrenceIntervalMs !== null && (
+                                            <span className="inline-flex items-center gap-1.5 text-slate-500 dark:text-slate-400">
+                                                <RepeatIcon className="h-3.5 w-3.5" />
+                                                <span>
+                                                    {translateText('goalChat.plannedMessageIntervalLabel', {
+                                                        interval: formatTimeoutDurationHuman(
+                                                            plannedMessage.recurrenceIntervalMs,
+                                                        ),
+                                                    })}
+                                                </span>
+                                            </span>
+                                        )}
+                                        {plannedMessage.cronExpression !== null && (
+                                            <span className="inline-flex items-center gap-1.5 text-slate-500 dark:text-slate-400">
+                                                <RepeatIcon className="h-3.5 w-3.5" />
+                                                <span>
+                                                    {translateText('goalChat.plannedMessageCronLabel', {
+                                                        cron: plannedMessage.cronExpression,
+                                                    })}
+                                                </span>
+                                            </span>
+                                        )}
+                                        {plannedMessage.maxRunCount !== null && (
+                                            <span className="inline-flex items-center gap-1.5 text-slate-500 dark:text-slate-400">
+                                                <RepeatIcon className="h-3.5 w-3.5" />
+                                                <span>
+                                                    {translateText('goalChat.plannedMessageRunCountLabel', {
+                                                        runCount: String(plannedMessage.runCount),
+                                                        maxRunCount: String(plannedMessage.maxRunCount),
+                                                    })}
+                                                </span>
+                                            </span>
+                                        )}
+                                        {(plannedMessage.startsAt !== null || plannedMessage.endsAt !== null) && (
+                                            <span className="inline-flex items-center gap-1.5 text-slate-500 dark:text-slate-400">
+                                                <CalendarRangeIcon className="h-3.5 w-3.5" />
+                                                <span>
+                                                    {translateText('goalChat.plannedMessageWindowLabel', {
+                                                        from: formatPlannedMessageBoundary(plannedMessage.startsAt),
+                                                        to: formatPlannedMessageBoundary(plannedMessage.endsAt),
+                                                    })}
+                                                </span>
+                                            </span>
+                                        )}
+                                    </div>
+                                </div>
+                                <button
+                                    type="button"
+                                    className="rounded-full border border-slate-300/80 bg-white px-3 py-1.5 text-[11px] font-semibold uppercase tracking-[0.15em] text-slate-700 transition hover:border-slate-400 hover:text-slate-900 disabled:cursor-default disabled:opacity-50 dark:border-slate-600 dark:bg-slate-950 dark:text-slate-200"
+                                    onClick={() => {
+                                        void handleCancelPlannedMessage(plannedMessage.timeoutId);
+                                    }}
+                                    disabled={isCancelling}
+                                >
+                                    {isCancelling
+                                        ? translateText('goalChat.plannedMessageCancellingLabel')
+                                        : translateText('goalChat.plannedMessageCancelLabel')}
+                                </button>
+                            </li>
+                        );
+                    })}
+                </ul>
+            )}
+        </section>
+    );
+}

package/apps/agents-server/src/app/agents/[agentName]/chat/CanonicalAgentChatPanel.tsx

@@ -31,6 +31,10 @@ type CanonicalAgentChatPanelProps = {
      * True when the viewed chat belongs to a different user than the current viewer.
      */
     isExternalUserChat?: boolean;
+    /**
+     * True when the viewed chat is the singleton thread the agent keeps with itself.
+     */
+    isAgentGoalChat?: boolean;
     /**
      * Optional actions rendered inside the read-only banner (for example super-admin shortcuts).
      */
@@ -88,6 +92,7 @@ export function CanonicalAgentChatPanel(props: CanonicalAgentChatPanelProps) {
         isReadOnly = false,
         readOnlySource,
         isExternalUserChat = false,
+        isAgentGoalChat = false,
         readOnlyExtraActions,
         projectReferences = [],
         messages,
@@ -142,6 +147,7 @@ export function CanonicalAgentChatPanel(props: CanonicalAgentChatPanelProps) {
                 isReadOnly={isReadOnly}
                 readOnlySource={readOnlySource}
                 isExternalUserChat={isExternalUserChat}
+                isAgentGoalChat={isAgentGoalChat}
                 readOnlyExtraActions={readOnlyExtraActions}
                 projectReferences={projectReferences}
                 onDraftMessageChange={onDraftMessageChange}

package/apps/agents-server/src/app/agents/[agentName]/chat/CanonicalAgentChatSurface.tsx

@@ -4,7 +4,9 @@ import { Chat } from '@promptbook-local/components';
 import { useCallback, useMemo, type CSSProperties, type ReactNode } from 'react';
 import type { ChatParticipant } from '../../../../../../../src/book-components/Chat/types/ChatParticipant';
 import type { ChatSaveFormatHandlerOptions } from '../../../../../../../src/book-components/Chat/save/_common/ChatSaveFormatHandler';
+import { AGENT_PROJECT_TOOL_CALL_NAME } from '../../../../../../../src/book-components/Chat/utils/agentProjectToolCall';
 import type { AgentProjectItemInfo } from '../../../../components/AgentProjects/AgentProjectReferencesList';
+import { useAgentProjectMarkdownReferences } from '../../../../components/AgentProjects/useAgentProjectMarkdownReferences';
 import { useAgentBackground } from '../../../../components/AgentProfile/useAgentBackground';
 import { useChatEnterBehaviorPreferences } from '../../../../components/ChatEnterBehavior/ChatEnterBehaviorPreferencesProvider';
 import { notifyError } from '../../../../components/Notifications/notifications';
@@ -24,10 +26,11 @@ import {
     toChatComponentFeedbackMode,
     type ChatFeedbackMode,
 } from '../../../../utils/chatFeedbackMode';
-import { createAgentProjectMarkdownReferences } from '../../../../utils/agentProjects/createAgentProjectMarkdownReferences';
 import { createDefaultSpeechRecognition } from '../../../../utils/speech-to-text/createDefaultSpeechRecognition';
 import { chatFileUploadHandler } from '../../../../utils/upload/createBookEditorUploadHandler';
 import { getUserChatSourceBannerLabel, type UserChatSource } from '../../../../utils/userChat/UserChatSource';
+import { AgentGoalChatNotice } from './AgentGoalChatNotice';
+import { AgentGoalChatPlannedMessages } from './AgentGoalChatPlannedMessages';
 import type { UserChatJob, UserChatTimeout } from '../../../../utils/userChatClient';
 import { ChatTimeoutButton } from './ChatTimeoutButton';
 import { isReplyableCanonicalChatMessage } from './chatReplies';
@@ -78,6 +81,10 @@ type CanonicalAgentChatSurfaceProps = {
      * True when the viewed chat belongs to a different user than the current viewer.
      */
     readonly isExternalUserChat?: boolean;
+    /**
+     * True when the viewed chat is the singleton thread the agent keeps with itself.
+     */
+    readonly isAgentGoalChat?: boolean;
     /**
      * Optional actions rendered inside the read-only banner (for example super-admin shortcuts).
      */
@@ -121,6 +128,7 @@ export function CanonicalAgentChatSurface({
     isReadOnly,
     readOnlySource,
     isExternalUserChat = false,
+    isAgentGoalChat = false,
     readOnlyExtraActions,
     projectReferences = [],
     onDraftMessageChange,
@@ -133,14 +141,11 @@ export function CanonicalAgentChatSurface({
     state,
 }: CanonicalAgentChatSurfaceProps) {
     const { backgroundImage, brandColorHex, brandColorLightHex, brandColorDarkHex } = useAgentBackground(brandColor);
-    const markdownInlineReferences = useMemo(
-        () =>
-            createAgentProjectMarkdownReferences({
-                agentPermanentId: agentName,
-                projects: projectReferences,
-            }),
-        [agentName, projectReferences],
-    );
+    const markdownInlineReferences = useAgentProjectMarkdownReferences({
+        agentPermanentId: agentName,
+        projects: projectReferences,
+        messages: state.renderedMessages,
+    });
     const chatBackgroundStyle = useMemo(
         () =>
             createCanonicalAgentChatBackgroundStyle({
@@ -171,7 +176,10 @@ export function CanonicalAgentChatSurface({
         ],
     );
     const { language, t: translateText } = useServerLanguage();
-    const translations = useMemo(() => createCanonicalAgentChatTranslations(translateText), [translateText]);
+    const translations = useMemo(
+        () => createCanonicalAgentChatTranslations(translateText, isAgentGoalChat),
+        [isAgentGoalChat, translateText],
+    );
     const frozenChatBannerLabel = useMemo(() => {
         const sourceBannerLabel = readOnlySource ? getUserChatSourceBannerLabel(readOnlySource) : null;
         if (sourceBannerLabel) {
@@ -319,6 +327,12 @@ export function CanonicalAgentChatSurface({
                     {readOnlyExtraActions}
                 </div>
             )}
+            {isAgentGoalChat && (
+                <>
+                    <AgentGoalChatNotice />
+                    <AgentGoalChatPlannedMessages agentName={agentName} currentTimestamp={currentTimestamp} />
+                </>
+            )}
         </Chat>
     );
 
@@ -422,7 +436,10 @@ function renderCanonicalAgentChatLoadingSkeleton(): ReactNode {
  *
  * @private function of CanonicalAgentChatPanel
  */
-function createCanonicalAgentChatTranslations(translateText: TranslateText): CanonicalAgentChatTranslations {
+function createCanonicalAgentChatTranslations(
+    translateText: TranslateText,
+    isAgentGoalChat: boolean,
+): CanonicalAgentChatTranslations {
     return {
         chatUiTranslations: {
             inputPlaceholder: translateText('chat.inputPlaceholder'),
@@ -511,9 +528,12 @@ function createCanonicalAgentChatTranslations(translateText: TranslateText): Can
             project_delete_file: translateText('chat.toolTitle.projectFileDeleter'),
             project_create_branch: translateText('chat.toolTitle.projectBranchCreator'),
             project_create_pull_request: translateText('chat.toolTitle.projectPullRequestCreator'),
+            [AGENT_PROJECT_TOOL_CALL_NAME]: translateText('chat.toolTitle.agentProjectTouched'),
         },
         timingTranslations: {
-            answerDurationLabel: translateText('chat.answerDurationLabel'),
+            answerDurationLabel: translateText(
+                isAgentGoalChat ? 'goalChat.executionDurationLabel' : 'chat.answerDurationLabel',
+            ),
         },
         feedbackTranslations: {
             reportIssueButtonTitle: translateText('chat.feedback.reportIssueButtonTitle'),

package/apps/agents-server/src/app/agents/[agentName]/chat/ExternalUserChatAdminActions.tsx

@@ -15,6 +15,13 @@ import {
  */
 const ADMIN_CHAT_HISTORY_ROUTE = '/admin/chat-history';
 
+/**
+ * Route of one admin user detail page linked from the external-chat view.
+ *
+ * @private constant of <ExternalUserChatAdminActions/>
+ */
+const ADMIN_USERS_ROUTE = '/admin/users';
+
 /**
  * Builds the admin chat-history link pointing at the most detailed view of one chat.
  *
@@ -23,13 +30,17 @@ const ADMIN_CHAT_HISTORY_ROUTE = '/admin/chat-history';
  *
  * @private utility of <ExternalUserChatAdminActions/>
  */
-function buildAdminChatHistoryHref(agentName: string, chatId: string): string {
+function buildAdminChatHistoryHref(agentName: string, chatId: string, userId: number | undefined): string {
     const params = new URLSearchParams();
 
     if (agentName) {
         params.set('agentName', agentName);
     }
 
+    if (isValidUserId(userId)) {
+        params.set('userId', String(userId));
+    }
+
     if (chatId) {
         params.set('chatId', chatId);
         params.set('view', 'chat');
@@ -39,6 +50,28 @@ function buildAdminChatHistoryHref(agentName: string, chatId: string): string {
     return qs ? `${ADMIN_CHAT_HISTORY_ROUTE}?${qs}` : ADMIN_CHAT_HISTORY_ROUTE;
 }
 
+/**
+ * Builds the user detail link for a valid chat owner id.
+ *
+ * @private utility of <ExternalUserChatAdminActions/>
+ */
+function buildAdminUserHref(userId: number | undefined): string | null {
+    if (!isValidUserId(userId)) {
+        return null;
+    }
+
+    return `${ADMIN_USERS_ROUTE}/${encodeURIComponent(String(userId))}`;
+}
+
+/**
+ * Returns whether a value can identify one persisted user.
+ *
+ * @private utility of <ExternalUserChatAdminActions/>
+ */
+function isValidUserId(userId: number | undefined): userId is number {
+    return typeof userId === 'number' && Number.isSafeInteger(userId) && userId > 0;
+}
+
 /**
  * Props for the super-admin actions shown on external users' chats.
  *
@@ -53,6 +86,10 @@ type ExternalUserChatAdminActionsProps = {
      * Canonical id of the viewed chat, used to deep-link the recorded conversation.
      */
     readonly chatId: string;
+    /**
+     * Database user id of the person who owns the viewed chat.
+     */
+    readonly userId?: number;
     /**
      * Title of the viewed chat used as the mocked-chat preset name.
      */
@@ -65,18 +102,20 @@ type ExternalUserChatAdminActionsProps = {
 
 /**
  * Super-admin quick actions rendered inside the frozen banner of external users' chats:
- * create a mocked chat from the conversation and jump to the admin chat history.
+ * create a mocked chat from the conversation, open its owner profile, and jump to the admin chat history.
  *
  * @private component of <AgentChatHistoryClient/>
  */
 export function ExternalUserChatAdminActions({
     agentName,
     chatId,
+    userId,
     chatTitle,
     messages,
 }: ExternalUserChatAdminActionsProps) {
     const [isCreatingMock, setIsCreatingMock] = useState(false);
-    const adminChatHistoryHref = buildAdminChatHistoryHref(agentName, chatId);
+    const adminChatHistoryHref = buildAdminChatHistoryHref(agentName, chatId, userId);
+    const adminUserHref = buildAdminUserHref(userId);
 
     const handleCreateMock = useCallback(async () => {
         if (isCreatingMock) {
@@ -113,6 +152,15 @@ export function ExternalUserChatAdminActions({
             >
                 {isCreatingMock ? 'Creating mock…' : 'Create mock'}
             </button>
+            {adminUserHref && (
+                <a
+                    href={adminUserHref}
+                    className="rounded-full border border-amber-300 bg-white/80 px-3 py-1 text-xs font-semibold text-amber-900 hover:bg-white dark:border-amber-500/40 dark:bg-transparent dark:text-amber-100"
+                    title="Open the profile of the user who created this chat"
+                >
+                    User #{userId}
+                </a>
+            )}
             <a
                 href={adminChatHistoryHref}
                 className="rounded-full border border-amber-300 bg-white/80 px-3 py-1 text-xs font-semibold text-amber-900 hover:bg-white dark:border-amber-500/40 dark:bg-transparent dark:text-amber-100"

package/apps/agents-server/src/app/agents/[agentName]/chat/TeamMemberFrozenChatPrimaryAgentLink.tsx

@@ -0,0 +1,31 @@
+'use client';
+
+import type { TeamMemberUserChatContext } from '../../../../utils/userChat/teamMemberUserChatContext';
+
+/**
+ * Link shown in a frozen teammate chat back to the primary agent chat that requested the consultation.
+ */
+export function TeamMemberFrozenChatPrimaryAgentLink({ context }: { readonly context: TeamMemberUserChatContext }) {
+    const primaryChatHref = buildPrimaryChatHref(context);
+
+    return (
+        <span className="ml-2 inline-flex items-center align-middle">
+            <a
+                href={primaryChatHref}
+                className="rounded-full border border-amber-300 bg-white/80 px-3 py-1 text-xs font-semibold text-amber-900 hover:bg-white dark:border-amber-500/40 dark:bg-transparent dark:text-amber-100"
+                title={`Open the chat with ${context.primaryAgentName} that requested this consultation`}
+            >
+                Open {context.primaryAgentName} chat
+            </a>
+        </span>
+    );
+}
+
+/**
+ * Builds a canonical primary-agent chat route from a persisted teammate-chat relation.
+ */
+function buildPrimaryChatHref(context: TeamMemberUserChatContext): string {
+    return `/agents/${encodeURIComponent(context.primaryAgentPermanentId)}/chat?chat=${encodeURIComponent(
+        context.primaryChatId,
+    )}`;
+}

package/apps/agents-server/src/app/agents/[agentName]/chat/page.tsx

@@ -4,8 +4,7 @@ import { ForbiddenPage } from '@/src/components/ForbiddenPage/ForbiddenPage';
 import type { AgentProjectItemInfo } from '@/src/components/AgentProjects/AgentProjectReferencesList';
 import { $provideServer } from '@/src/tools/$provideServer';
 import { resolveAgentAccess } from '@/src/utils/agentAccess';
-import { resolveAgentProjectsAccess } from '@/src/utils/agentProjects/agentProjectAccess';
-import { listAgentProjectChatReferences } from '@/src/utils/agentProjects/listAgentProjectChatReferences';
+import { resolveAgentChatProjectReferences } from '@/src/utils/agentProjects/resolveAgentChatProjectReferences';
 import { loadChatConfiguration } from '@/src/utils/chatConfiguration';
 import { ensureChatHistoryIdentity } from '@/src/utils/currentUserIdentity';
 import { getCurrentUser } from '@/src/utils/getCurrentUser';
@@ -71,23 +70,6 @@ function buildCanonicalAgentChatPath(
     return query ? `${pathname}?${query}` : pathname;
 }
 
-/**
- * Resolves compact project references available to the agent chat surface.
- *
- * @param agentPermanentId - Permanent id of the agent owning the projects.
- * @returns Display-only project references safe to send to the client.
- */
-async function resolveAgentChatProjectReferences(
-    agentPermanentId: string,
-): Promise<ReadonlyArray<AgentProjectItemInfo>> {
-    const projectAccess = await resolveAgentProjectsAccess(agentPermanentId);
-    if (!projectAccess.isProjectOverviewVisible) {
-        return [];
-    }
-
-    return await listAgentProjectChatReferences(agentPermanentId);
-}
-
 /**
  * Handles agent chat page.
  */
@@ -149,7 +131,7 @@ export default async function AgentChatPage({
     const providedServerPromise = $provideServer();
     const agentProjectReferencesPromise = isHeadless
         ? Promise.resolve<ReadonlyArray<AgentProjectItemInfo>>([])
-        : resolveAgentChatProjectReferences(canonicalAgentId);
+        : resolveAgentChatProjectReferences({ agentPermanentId: canonicalAgentId });
     const shareTargetPayloadPromise = shareTarget
         ? peekShareTargetPayload({
               shareTargetId: shareTarget,

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

@@ -70,6 +70,10 @@ export type AgentChatSidebarItem = {
     readonly isActive: boolean;
     readonly isEmpty: boolean;
     readonly isReadOnly: boolean;
+    /**
+     * True for the pinned goal chat the agent keeps with itself.
+     */
+    readonly isAgentGoalChat: boolean;
     readonly content: AgentChatSidebarItemContent;
 };
 
@@ -225,6 +229,22 @@ function resolveAgentChatSidebarItemContent(
     };
 }
 
+/**
+ * Keeps the pinned goal chat above every regular conversation while preserving their order.
+ *
+ * @private function of AgentChatSidebar
+ */
+function compareAgentChatSidebarItemsByPinning(
+    leftItem: AgentChatSidebarItem,
+    rightItem: AgentChatSidebarItem,
+): number {
+    if (leftItem.isAgentGoalChat === rightItem.isAgentGoalChat) {
+        return 0;
+    }
+
+    return leftItem.isAgentGoalChat ? -1 : 1;
+}
+
 /**
  * Closes the mobile sidebar after an action that should dismiss the overlay.
  *
@@ -262,10 +282,14 @@ export function useAgentChatSidebarState({
         isActive: chat.id === activeChatId,
         isEmpty: chat.messagesCount <= EMPTY_CHAT_MAX_MESSAGES,
         isReadOnly: chat.isReadOnly,
+        isAgentGoalChat: chat.isAgentGoalChat === true,
         content: resolveAgentChatSidebarItemContent(chat, formatText, formatChatTimestamp, currentTimestamp),
     }));
-    const emptyChatCount = allSidebarItems.filter((item) => item.isEmpty).length;
-    const sidebarItems = allSidebarItems.filter((item) => isShowingEmptyChats || !item.isEmpty || item.isActive);
+    // Note: The goal chat is a singleton pinned above every conversation and is never hidden as empty
+    const emptyChatCount = allSidebarItems.filter((item) => item.isEmpty && !item.isAgentGoalChat).length;
+    const sidebarItems = allSidebarItems
+        .filter((item) => item.isAgentGoalChat || isShowingEmptyChats || !item.isEmpty || item.isActive)
+        .sort(compareAgentChatSidebarItemsByPinning);
     const shouldRenderFilters = emptyChatCount > 0 || isAdmin;
 
     const handleChatSelection = (chatId: string) => {

package/apps/agents-server/src/app/agents/[agentName]/goal/page.tsx

@@ -0,0 +1,35 @@
+'use server';
+
+import { ForbiddenPage } from '@/src/components/ForbiddenPage/ForbiddenPage';
+import { buildAgentGoalChatId, canAccessAgentGoalChat, ensureAgentGoalChat } from '@/src/utils/agentGoalChat';
+import { resolveAgentAccess } from '@/src/utils/agentAccess';
+import { buildExistingAgentChatHref } from '@/src/utils/agentRouting/agentRouteHrefs';
+import { redirect } from 'next/navigation';
+import { enforceCanonicalLocalAgentId, getAgentName } from '../_utils';
+
+/**
+ * Builds canonical goal-chat entry path for one local agent id.
+ */
+function buildCanonicalAgentGoalPath(canonicalAgentId: string): string {
+    return `/agents/${encodeURIComponent(canonicalAgentId)}/goal`;
+}
+
+/**
+ * Opens the singleton goal chat of one agent inside the regular chat surface.
+ *
+ * The goal chat is one of the agent's chats, so this route only resolves its deterministic id and
+ * hands over to the shared chat page instead of duplicating the chat UI.
+ */
+export default async function AgentGoalChatPage({ params }: { params: Promise<{ agentName: string }> }) {
+    const agentName = await getAgentName(params);
+    const canonicalAgentId = await enforceCanonicalLocalAgentId(agentName, buildCanonicalAgentGoalPath);
+
+    const access = await resolveAgentAccess(canonicalAgentId);
+    if (!access.isAllowed || !(await canAccessAgentGoalChat())) {
+        return <ForbiddenPage />;
+    }
+
+    await ensureAgentGoalChat(canonicalAgentId);
+
+    redirect(buildExistingAgentChatHref(canonicalAgentId, buildAgentGoalChatId(canonicalAgentId)));
+}

package/apps/agents-server/src/app/agents/[agentName]/page.tsx

@@ -6,6 +6,7 @@ import { $provideServer } from '@/src/tools/$provideServer';
 import { resolveAgentProjectsAccess } from '@/src/utils/agentProjects/agentProjectAccess';
 import { buildAgentProjectsDashboardHref } from '@/src/utils/agentProjects/agentProjectHrefs';
 import { listAgentProjectChatReferences } from '@/src/utils/agentProjects/listAgentProjectChatReferences';
+import { resolveAgentChatProjectReferences } from '@/src/utils/agentProjects/resolveAgentChatProjectReferences';
 import { isPublicAgentVisibility } from '@/src/utils/agentVisibility';
 import { ensureChatHistoryIdentity } from '@/src/utils/currentUserIdentity';
 import { createAgentEmailAddress } from '@/src/utils/email/agentEmailAddress';
@@ -689,7 +690,7 @@ export default async function AgentPage(props: AgentPageProps) {
 
     const [pageData, projects] = await Promise.all([
         loadAgentPageData(route.canonicalAgentId, Boolean(access.currentUser)),
-        access.isProjectOverviewVisible ? listAgentProjectChatReferences(route.canonicalAgentId) : Promise.resolve([]),
+        resolveAgentChatProjectReferences({ agentPermanentId: route.canonicalAgentId, projectsAccess: access }),
     ]);
     return renderAgentProfilePage(createAgentPageViewModel(route, pageData, projects));
 }