@promptbook/cli 0.114.0-0 → 0.114.0-10

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

@@ -0,0 +1,168 @@
+'use client';
+
+import { Clock3Icon } from 'lucide-react';
+import { useCallback, useEffect, useState } from 'react';
+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;
+};
+
+/**
+ * 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 inline-flex items-center gap-1.5 text-xs font-medium text-amber-700 dark:text-amber-300">
+                                        <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>
+                                    </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

@@ -5,6 +5,7 @@ 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 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 +25,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 +80,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 +127,7 @@ export function CanonicalAgentChatSurface({
     isReadOnly,
     readOnlySource,
     isExternalUserChat = false,
+    isAgentGoalChat = false,
     readOnlyExtraActions,
     projectReferences = [],
     onDraftMessageChange,
@@ -133,14 +140,10 @@ 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,
+    });
     const chatBackgroundStyle = useMemo(
         () =>
             createCanonicalAgentChatBackgroundStyle({
@@ -319,6 +322,12 @@ export function CanonicalAgentChatSurface({
                     {readOnlyExtraActions}
                 </div>
             )}
+            {isAgentGoalChat && (
+                <>
+                    <AgentGoalChatNotice />
+                    <AgentGoalChatPlannedMessages agentName={agentName} currentTimestamp={currentTimestamp} />
+                </>
+            )}
         </Chat>
     );
 

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/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]/projectRuntimeActions.ts

@@ -0,0 +1,97 @@
+'use server';
+
+import { revalidatePath } from 'next/cache';
+import { NotAllowed } from '../../../../../../src/errors/NotAllowed';
+import { spaceTrim } from '../../../../../../src/utils/organization/spaceTrim';
+import { resolveAgentProjectsAccess } from '@/src/utils/agentProjects/agentProjectAccess';
+import { buildAgentProjectProfileHref } from '@/src/utils/agentProjects/agentProjectHrefs';
+import type { AgentProjectRuntimeActionResult } from '@/src/utils/agentProjects/AgentProjectRuntimeActionResult';
+import {
+    startAgentProjectRuntime,
+    terminateAgentProjectRuntimeForProject,
+} from '@/src/utils/agentProjects/agentProjectRuntimeRegistry';
+import { resolveCurrentAgentProjectServerDomain } from '@/src/utils/agentProjects/resolveCurrentAgentProjectServerDomain';
+
+/**
+ * Starts one project after checking the current user's access.
+ *
+ * @param agentPermanentId - Permanent id of the agent owning the project.
+ * @param projectName - Project directory name.
+ * @returns Browser-safe state of the started runtime.
+ */
+export async function $startAgentProjectRuntimeAction(
+    agentPermanentId: string,
+    projectName: string,
+): Promise<AgentProjectRuntimeActionResult> {
+    await assertProjectRuntimeActionAccess(agentPermanentId, projectName, 'start');
+
+    const runtime = await startAgentProjectRuntime({
+        agentPermanentId,
+        projectName,
+        serverDomain: await resolveCurrentAgentProjectServerDomain(),
+    });
+    revalidateProjectRuntimePaths(agentPermanentId, projectName);
+
+    return {
+        isRunning: runtime.isRunning,
+        projectUrl: runtime.publicUrl || null,
+    };
+}
+
+/**
+ * Stops one project after checking the current user's access.
+ *
+ * @param agentPermanentId - Permanent id of the agent owning the project.
+ * @param projectName - Project directory name.
+ * @returns Browser-safe state of the stopped runtime.
+ */
+export async function $stopAgentProjectRuntimeAction(
+    agentPermanentId: string,
+    projectName: string,
+): Promise<AgentProjectRuntimeActionResult> {
+    await assertProjectRuntimeActionAccess(agentPermanentId, projectName, 'stop');
+
+    const runtime = await terminateAgentProjectRuntimeForProject({ agentPermanentId, projectName });
+    revalidateProjectRuntimePaths(agentPermanentId, projectName);
+
+    return {
+        isRunning: false,
+        projectUrl: runtime?.publicUrl || null,
+    };
+}
+
+/**
+ * Checks that the current user can perform a project runtime action.
+ *
+ * @param agentPermanentId - Permanent id of the agent owning the project.
+ * @param projectName - Project directory name.
+ * @param actionName - Human-readable action used in an access error.
+ */
+async function assertProjectRuntimeActionAccess(
+    agentPermanentId: string,
+    projectName: string,
+    actionName: 'start' | 'stop',
+): Promise<void> {
+    const access = await resolveAgentProjectsAccess(agentPermanentId);
+
+    if (!access.isProjectDetailsVisible) {
+        throw new NotAllowed(
+            spaceTrim(`
+                You are not allowed to ${actionName} project \`${projectName}\`.
+            `),
+        );
+    }
+}
+
+/**
+ * Revalidates pages which show project runtime state.
+ *
+ * @param agentPermanentId - Permanent id of the agent owning the project.
+ * @param projectName - Project directory name.
+ */
+function revalidateProjectRuntimePaths(agentPermanentId: string, projectName: string): void {
+    revalidatePath(buildAgentProjectProfileHref(agentPermanentId, projectName));
+    revalidatePath('/admin/projects');
+    revalidatePath('/superadmin/resource-monitor');
+    revalidatePath('/superadmin/servers');
+}

package/apps/agents-server/src/app/agents/[agentName]/projects/[projectName]/actions.ts

@@ -1,15 +1,9 @@
 'use server';
 
-import { revalidatePath } from 'next/cache';
-import { NotAllowed } from '../../../../../../../../src/errors/NotAllowed';
-import { spaceTrim } from '../../../../../../../../src/utils/organization/spaceTrim';
-import { resolveAgentProjectsAccess } from '@/src/utils/agentProjects/agentProjectAccess';
-import { buildAgentProjectProfileHref } from '@/src/utils/agentProjects/agentProjectHrefs';
 import {
-    startAgentProjectRuntime,
-    terminateAgentProjectRuntimeForProject,
-} from '@/src/utils/agentProjects/agentProjectRuntimeRegistry';
-import { resolveCurrentAgentProjectServerDomain } from '@/src/utils/agentProjects/resolveCurrentAgentProjectServerDomain';
+    $startAgentProjectRuntimeAction,
+    $stopAgentProjectRuntimeAction,
+} from '../../projectRuntimeActions';
 
 /**
  * Starts one project from its project page.
@@ -21,14 +15,7 @@ export async function $startAgentProjectRuntimeFromProjectPageAction(
     agentPermanentId: string,
     projectName: string,
 ): Promise<void> {
-    await assertProjectRuntimeActionAccess(agentPermanentId, projectName, 'start');
-
-    await startAgentProjectRuntime({
-        agentPermanentId,
-        projectName,
-        serverDomain: await resolveCurrentAgentProjectServerDomain(),
-    });
-    revalidateProjectRuntimePaths(agentPermanentId, projectName);
+    await $startAgentProjectRuntimeAction(agentPermanentId, projectName);
 }
 
 /**
@@ -41,37 +28,5 @@ export async function $terminateAgentProjectRuntimeFromProjectPageAction(
     agentPermanentId: string,
     projectName: string,
 ): Promise<void> {
-    await assertProjectRuntimeActionAccess(agentPermanentId, projectName, 'terminate');
-
-    await terminateAgentProjectRuntimeForProject({ agentPermanentId, projectName });
-    revalidateProjectRuntimePaths(agentPermanentId, projectName);
-}
-
-/**
- * Checks that the current user can perform a project runtime action.
- */
-async function assertProjectRuntimeActionAccess(
-    agentPermanentId: string,
-    projectName: string,
-    actionName: 'start' | 'terminate',
-): Promise<void> {
-    const access = await resolveAgentProjectsAccess(agentPermanentId);
-
-    if (!access.isProjectDetailsVisible) {
-        throw new NotAllowed(
-            spaceTrim(`
-                You are not allowed to ${actionName} project \`${projectName}\`.
-            `),
-        );
-    }
-}
-
-/**
- * Revalidates pages that show project runtime state.
- */
-function revalidateProjectRuntimePaths(agentPermanentId: string, projectName: string): void {
-    revalidatePath(buildAgentProjectProfileHref(agentPermanentId, projectName));
-    revalidatePath('/admin/projects');
-    revalidatePath('/superadmin/resource-monitor');
-    revalidatePath('/superadmin/servers');
+    await $stopAgentProjectRuntimeAction(agentPermanentId, projectName);
 }