@promptbook/cli 0.113.0-9 → 0.114.0-0

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

@@ -1,13 +1,17 @@
 'use server';
 import type { Metadata, ResolvingMetadata } from 'next';
 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 { loadChatConfiguration } from '@/src/utils/chatConfiguration';
 import { ensureChatHistoryIdentity } from '@/src/utils/currentUserIdentity';
 import { getCurrentUser } from '@/src/utils/getCurrentUser';
+import { isUserGlobalAdmin } from '@/src/utils/isUserGlobalAdmin';
 import { peekShareTargetPayload } from '@/src/utils/shareTargetPayloads';
-import { getThinkingMessages } from '@/src/utils/thinkingMessages';
+import { getThinkingMessages, resolveThinkingMessages } from '@/src/utils/thinkingMessages';
 import { headers } from 'next/headers';
 import { notFound, redirect } from 'next/navigation';
 import { resolveSpeechRecognitionLanguage } from '../../../../../../../src/utils/language/getBrowserPreferredSpeechRecognitionLanguage';
@@ -67,6 +71,23 @@ 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.
  */
@@ -75,12 +96,23 @@ export default async function AgentChatPage({
     searchParams,
 }: {
     params: Promise<{ agentName: string }>;
-    searchParams: Promise<{ headless?: string; message?: string; chat?: string; newChat?: string; shareTarget?: string }>;
+    searchParams: Promise<{
+        headless?: string;
+        message?: string;
+        chat?: string;
+        newChat?: string;
+        shareTarget?: string;
+    }>;
 }) {
     const requestHeadersPromise = headers();
-    const [agentName, currentSearchParams, requestHeaders] = await Promise.all([getAgentName(params), searchParams, requestHeadersPromise]);
+    const [agentName, currentSearchParams, requestHeaders] = await Promise.all([
+        getAgentName(params),
+        searchParams,
+        requestHeadersPromise,
+    ]);
     $sideEffect(requestHeaders);
     const { headless, message, chat, newChat, shareTarget } = currentSearchParams;
+    const isHeadless = headless !== undefined;
 
     const isForcedNewChat = chat === FORCE_NEW_CHAT_QUERY_VALUE || parseBooleanFlag(newChat);
     const effectiveChatId = chat === FORCE_NEW_CHAT_QUERY_VALUE ? undefined : chat;
@@ -113,8 +145,11 @@ export default async function AgentChatPage({
     const historyIdentityAvailablePromise = ensureChatHistoryIdentity();
     const currentUserPromise = getCurrentUser();
     const chatConfigurationPromise = loadChatConfiguration();
-    const thinkingMessagesPromise = getThinkingMessages();
+    const serverThinkingMessagesPromise = getThinkingMessages();
     const providedServerPromise = $provideServer();
+    const agentProjectReferencesPromise = isHeadless
+        ? Promise.resolve<ReadonlyArray<AgentProjectItemInfo>>([])
+        : resolveAgentChatProjectReferences(canonicalAgentId);
     const shareTargetPayloadPromise = shareTarget
         ? peekShareTargetPayload({
               shareTargetId: shareTarget,
@@ -123,7 +158,6 @@ export default async function AgentChatPage({
         : Promise.resolve(null);
 
     const isDeleted = await isDeletedPromise;
-    const isHeadless = headless !== undefined;
 
     if (isDeleted) {
         return (
@@ -141,19 +175,23 @@ export default async function AgentChatPage({
         historyIdentityAvailable,
         currentUser,
         { isFileAttachmentsEnabled, feedbackMode },
-        thinkingMessages,
+        serverThinkingMessages,
         { publicUrl },
+        agentProjectReferences,
         shareTargetPayload,
-    ] =
-        await Promise.all([
+        isCurrentUserSuperAdmin,
+    ] = await Promise.all([
         agentProfilePromise,
         historyIdentityAvailablePromise,
         currentUserPromise,
         chatConfigurationPromise,
-        thinkingMessagesPromise,
+        serverThinkingMessagesPromise,
         providedServerPromise,
+        agentProjectReferencesPromise,
         shareTargetPayloadPromise,
+        isUserGlobalAdmin(),
     ]);
+    const thinkingMessages = resolveThinkingMessages(agentProfile.thinkingMessages, serverThinkingMessages);
     const agentUrl = new URL(`/agents/${encodeURIComponent(canonicalAgentId)}`, publicUrl).href;
     const agentDisplayName = agentProfile.meta.fullname || agentProfile.agentName || canonicalAgentId;
     const inputPlaceholder = agentProfile.meta.inputPlaceholder?.trim() || undefined;
@@ -179,6 +217,8 @@ export default async function AgentChatPage({
                 speechRecognitionLanguage={speechRecognitionLanguage}
                 isHistoryEnabled={historyIdentityAvailable}
                 isCurrentUserAdmin={currentUser?.isAdmin === true}
+                isCurrentUserSuperAdmin={isCurrentUserSuperAdmin}
+                projectReferences={agentProjectReferences}
                 areFileAttachmentsEnabled={isFileAttachmentsEnabled}
                 feedbackMode={feedbackMode}
                 isHeadlessMode={isHeadless}

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

@@ -0,0 +1,27 @@
+/**
+ * Minimum agent profile shape needed to resolve a human-readable chat name.
+ *
+ * @private type of the canonical agent chat
+ */
+export type AgentChatDisplayNameSource = {
+    readonly agentName?: string | null;
+    readonly meta?: {
+        readonly fullname?: string | null;
+    } | null;
+};
+
+/**
+ * Resolves the display name shared across the chat title, participants, and fallback copy.
+ *
+ * @param agent - Loaded agent profile, when available.
+ * @param fallbackDisplayName - Human-readable title resolved before the profile loads.
+ * @returns Display name that never needs the opaque route identifier as a fallback.
+ *
+ * @private function of the canonical agent chat
+ */
+export function resolveAgentChatDisplayName(
+    agent: AgentChatDisplayNameSource | null | undefined,
+    fallbackDisplayName: string,
+): string {
+    return agent?.meta?.fullname || fallbackDisplayName || agent?.agentName || 'Agent';
+}

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

@@ -2,6 +2,7 @@
 
 import type { ChatMessage } from '@promptbook-local/types';
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import type { AgentProjectItemInfo } from '../../../../components/AgentProjects/AgentProjectReferencesList';
 import { useAgentNaming } from '../../../../components/AgentNaming/AgentNamingContext';
 import { createMyChatsMobileMenuItem } from '../../../../components/Header/createMyChatsMobileMenuItem';
 import { useHoistedMobileMenuItems } from '../../../../components/Header/MobileMenuHoistingContext';
@@ -42,6 +43,15 @@ export type AgentChatHistoryClientProps = {
     initialAgentMessage?: string | null;
     isHistoryEnabled: boolean;
     isCurrentUserAdmin: boolean;
+    /**
+     * True when the viewer is the environment-backed super-admin
+     * who may browse all users' chats in a view-only mode.
+     */
+    isCurrentUserSuperAdmin?: boolean;
+    /**
+     * Compact project references shown in the chat surface.
+     */
+    projectReferences?: ReadonlyArray<AgentProjectItemInfo>;
     areFileAttachmentsEnabled: boolean;
     feedbackMode: ChatFeedbackMode;
     isHeadlessMode?: boolean;
@@ -117,6 +127,7 @@ export function useAgentChatHistoryClientState(
         initialForceNewChat = false,
         isHistoryEnabled,
         isCurrentUserAdmin,
+        isCurrentUserSuperAdmin = false,
         isHeadlessMode = false,
     } = props;
     const { formatText } = useAgentNaming();
@@ -159,7 +170,7 @@ export function useAgentChatHistoryClientState(
         clearPendingProfileMessage(agentName);
     }, [agentName, pendingProfileMessage]);
 
-    const shouldShowExternalChats = isCurrentUserAdmin && showExternalChats;
+    const shouldShowExternalChats = (isCurrentUserAdmin || isCurrentUserSuperAdmin) && showExternalChats;
     const {
         chats,
         activeChatId,

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

@@ -455,6 +455,7 @@ function createOptimisticUserChatSummary(chatId: string, timestamp: string): Use
         lastMessageAt: null,
         source: USER_CHAT_SOURCES.WEB_UI,
         isReadOnly: false,
+        isExternalUserChat: false,
         messagesCount: 0,
         title: '',
         preview: '',

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

@@ -23,6 +23,7 @@ import { useAgentChatMetaDisclaimer } from '../useAgentChatMetaDisclaimer';
 import { useAgentChatToolInteractions } from '../useAgentChatToolInteractions';
 import { useTeamAgentProfiles } from '../useTeamAgentProfiles';
 import { createReplyingToSnapshot, isReplyableCanonicalChatMessage } from './chatReplies';
+import { resolveAgentChatDisplayName } from './resolveAgentChatDisplayName';
 import { useCanonicalChatMessages } from './useCanonicalChatMessages';
 import { queuePendingOutboundMessage } from './usePendingOutboundMessages';
 
@@ -85,6 +86,7 @@ type CanonicalAgentKnowledgeSource = {
 type UseCanonicalAgentChatPanelStateOptions = {
     readonly chatId: string;
     readonly agentName: string;
+    readonly agentTitle: string;
     readonly agentUrl: string;
     readonly initialAgentMessage?: string | null;
     readonly isReadOnly: boolean;
@@ -184,6 +186,7 @@ export function useCanonicalAgentChatPanelState(
     const {
         chatId,
         agentName,
+        agentTitle,
         agentUrl,
         initialAgentMessage,
         isReadOnly,
@@ -360,7 +363,7 @@ export function useCanonicalAgentChatPanelState(
         onManualMessage: handleManualMessage,
     });
 
-    const agentDisplayName = useMemo(() => resolveAgentDisplayName(agent, agentName), [agent, agentName]);
+    const agentDisplayName = useMemo(() => resolveAgentChatDisplayName(agent, agentTitle), [agent, agentTitle]);
     const agentKnowledgeSources = useMemo(() => resolveAgentKnowledgeSources(agent), [agent]);
     const resolvedAgentAvatar = useMemo(
         () => resolveResolvedAgentAvatar(agent, agentName, agentUrl),
@@ -667,15 +670,6 @@ function resolveCurrentAgentPermanentId(agent: RemoteAgent | null | undefined, a
         : agentName;
 }
 
-/**
- * Resolves the display name shared across chat title, participants, and fallback copy.
- *
- * @private function of CanonicalAgentChatPanel
- */
-function resolveAgentDisplayName(agent: RemoteAgent | null | undefined, agentName: string): string {
-    return agent?.meta.fullname || agent?.agentName || agentName;
-}
-
 /**
  * Resolves valid knowledge sources exposed by the remote agent profile.
  *

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

@@ -2,6 +2,8 @@
 
 import type { Metadata } from 'next';
 import { resolveAgentRouteTarget } from '../../../utils/agentRouting/resolveAgentRouteTarget';
+import { resolveAgentProjectsAccess } from '../../../utils/agentProjects/agentProjectAccess';
+import { hasAgentProjects } from '../../../utils/agentProjects/hasAgentProjects';
 import { ActiveAgentBreadcrumbBinder } from './ActiveAgentBreadcrumbBinder';
 import { getAgentName, getAgentProfile } from './_utils';
 import { generateAgentMetadata } from './generateAgentMetadata';
@@ -36,13 +38,19 @@ async function tryResolveActiveAgentBreadcrumbInfo(
             return null;
         }
 
-        const agentProfile = await getAgentProfile(routeTarget.canonicalAgentId);
+        const [agentProfile, projectsAccess] = await Promise.all([
+            getAgentProfile(routeTarget.canonicalAgentId),
+            resolveAgentProjectsAccess(routeTarget.canonicalAgentId),
+        ]);
+        const isProjectsViewVisible =
+            projectsAccess.isProjectOverviewVisible && (await hasAgentProjects(routeTarget.canonicalAgentId));
 
         return {
             agentName: agentProfile.agentName,
             agentHash: agentProfile.agentHash,
             permanentId: agentProfile.permanentId,
             meta: agentProfile.meta,
+            isProjectsViewVisible,
         };
     } catch {
         return null;

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

@@ -1,16 +1,21 @@
 'use server';
 
 import { ForbiddenPage } from '@/src/components/ForbiddenPage/ForbiddenPage';
+import { AgentProjectReferencesList } 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 { buildAgentProjectsDashboardHref } from '@/src/utils/agentProjects/agentProjectHrefs';
+import { listAgentProjectChatReferences } from '@/src/utils/agentProjects/listAgentProjectChatReferences';
 import { isPublicAgentVisibility } from '@/src/utils/agentVisibility';
 import { ensureChatHistoryIdentity } from '@/src/utils/currentUserIdentity';
+import { createAgentEmailAddress } from '@/src/utils/email/agentEmailAddress';
 import { getServerVisibility } from '@/src/utils/getServerVisibility';
 import { isUserAdmin } from '@/src/utils/isUserAdmin';
 import { isPublicServerVisibility } from '@/src/utils/serverVisibility';
 import { saturate } from '@promptbook-local/color';
 import { NotFoundError, PROMPTBOOK_COLOR } from '@promptbook-local/core';
 import { headers } from 'next/headers';
+import Link from 'next/link';
 import { notFound, redirect } from 'next/navigation';
 import { resolveAgentAvatarImageUrl } from '../../../../../../src/utils/agents/resolveAgentAvatarImageUrl';
 import { Color } from '../../../../../../src/utils/color/Color';
@@ -103,6 +108,7 @@ type AgentPageViewModel = {
     inputPlaceholder: ReturnType<typeof resolveAgentChatInputPlaceholder>;
     brandColorHex: string;
     avatarSrc: string;
+    projects: Awaited<ReturnType<typeof listAgentProjectChatReferences>>;
     initialAgentMessage: AgentPageData['agentProfile']['initialMessage'];
     speechRecognitionLanguage: ReturnType<typeof resolveSpeechRecognitionLanguage>;
     isHistoryEnabled: boolean;
@@ -453,6 +459,7 @@ function isMissingAgentProfileError(error: unknown): boolean {
 function createAgentPageViewModel(
     route: Extract<ResolvedAgentPageRoute, { kind: 'local' }>,
     data: AgentPageData,
+    projects: Awaited<ReturnType<typeof listAgentProjectChatReferences>>,
 ): AgentPageViewModel {
     const { agentProfile, agentNaming, isDeleted, publicUrl, requestHeaders, serverVisibility } = data;
 
@@ -484,7 +491,14 @@ function createAgentPageViewModel(
         agent: agentProfile,
         agentUrl: route.canonicalUrl,
         publicUrl: publicUrl.href,
-        agentEmail: `${route.canonicalAgentId}@${publicUrl.hostname}`,
+        agentEmail: createAgentEmailAddress(
+            {
+                agentName: agentProfile.agentName,
+                permanentId: agentProfile.permanentId || route.canonicalAgentId,
+                fullname,
+            },
+            publicUrl.hostname,
+        ),
         agentName: route.canonicalAgentId,
         isAdmin: data.isAdmin,
         isAuthenticated: data.isAuthenticated,
@@ -496,6 +510,7 @@ function createAgentPageViewModel(
         inputPlaceholder,
         brandColorHex,
         avatarSrc,
+        projects,
         initialAgentMessage: agentProfile.initialMessage,
         speechRecognitionLanguage,
         isHistoryEnabled: data.historyIdentityAvailable,
@@ -587,9 +602,13 @@ function renderAgentProfilePage(viewModel: AgentPageViewModel) {
                 isAuthenticated={viewModel.isAuthenticated}
                 isHeadless={viewModel.isHeadless}
                 folderContext={viewModel.folderContext}
+                isProjectsViewVisible={viewModel.projects.length > 0}
                 actions={viewModel.actions}
             >
                 {viewModel.isDeleted && <DeletedAgentBanner />}
+                {viewModel.projects.length > 0 && (
+                    <AgentProfileProjectsSection agentPermanentId={viewModel.agentName} projects={viewModel.projects} />
+                )}
                 <DeferredAgentProfileChat
                     agentUrl={viewModel.agentUrl}
                     agentName={viewModel.agentName}
@@ -602,12 +621,54 @@ function renderAgentProfilePage(viewModel: AgentPageViewModel) {
                     speechRecognitionLanguage={viewModel.speechRecognitionLanguage}
                     isHistoryEnabled={viewModel.isHistoryEnabled}
                     areFileAttachmentsEnabled={viewModel.areFileAttachmentsEnabled}
+                    projectReferences={viewModel.projects}
                 />
             </AgentProfileWrapper>
         </>
     );
 }
 
+/**
+ * Renders compact project links on the agent profile page.
+ *
+ * @param props - Profile projects props.
+ * @returns Agent profile projects section.
+ */
+function AgentProfileProjectsSection({
+    agentPermanentId,
+    projects,
+}: {
+    /**
+     * Permanent id of the agent owning the projects.
+     */
+    readonly agentPermanentId: string;
+
+    /**
+     * Projects displayed on the profile.
+     */
+    readonly projects: Awaited<ReturnType<typeof listAgentProjectChatReferences>>;
+}) {
+    return (
+        <section className="mb-4 rounded-lg border border-white/40 bg-white/75 p-3 shadow-sm backdrop-blur-sm">
+            <div className="mb-2 flex items-center justify-between gap-3">
+                <h2 className="text-sm font-semibold text-gray-900">Projects</h2>
+                <Link
+                    href={buildAgentProjectsDashboardHref(agentPermanentId)}
+                    className="text-xs font-semibold text-blue-700 hover:text-blue-900 hover:underline"
+                >
+                    View all
+                </Link>
+            </div>
+            <AgentProjectReferencesList
+                agentPermanentId={agentPermanentId}
+                projects={projects}
+                className="flex-col"
+                itemClassName="w-full bg-white/85"
+            />
+        </section>
+    );
+}
+
 /**
  * Renders the main agent profile page.
  *
@@ -621,13 +682,16 @@ export default async function AgentPage(props: AgentPageProps) {
         return renderPseudoAgentProfilePage(route);
     }
 
-    const access = await resolveAgentAccess(route.canonicalAgentId);
+    const access = await resolveAgentProjectsAccess(route.canonicalAgentId);
     if (!access.isAllowed) {
         return <ForbiddenPage />;
     }
 
-    const pageData = await loadAgentPageData(route.canonicalAgentId, Boolean(access.currentUser));
-    return renderAgentProfilePage(createAgentPageViewModel(route, pageData));
+    const [pageData, projects] = await Promise.all([
+        loadAgentPageData(route.canonicalAgentId, Boolean(access.currentUser)),
+        access.isProjectOverviewVisible ? listAgentProjectChatReferences(route.canonicalAgentId) : Promise.resolve([]),
+    ]);
+    return renderAgentProfilePage(createAgentPageViewModel(route, pageData, projects));
 }
 
 // TODO: [🐱‍🚀] Make this page look nice - 🃏

package/apps/agents-server/src/app/agents/[agentName]/projects/[projectName]/AgentProjectVscodeKeyboardShortcut.tsx

@@ -0,0 +1,75 @@
+'use client';
+
+import { useEffect } from 'react';
+
+/**
+ * Props accepted by the project VS Code keyboard shortcut listener.
+ */
+type AgentProjectVscodeKeyboardShortcutProps = {
+    /**
+     * Launcher href for the current project.
+     */
+    readonly href: string;
+
+    /**
+     * Whether the shortcut should be active for the current viewer.
+     */
+    readonly isEnabled: boolean;
+};
+
+/**
+ * Registers the GitHub-style `.` shortcut for opening the project in browser VS Code.
+ *
+ * @param props - Keyboard shortcut configuration.
+ * @returns Nothing visible.
+ */
+export function AgentProjectVscodeKeyboardShortcut({ href, isEnabled }: AgentProjectVscodeKeyboardShortcutProps): null {
+    useEffect(() => {
+        if (!isEnabled) {
+            return;
+        }
+
+        const handleKeyDown = (event: KeyboardEvent): void => {
+            if (
+                event.key !== '.' ||
+                event.altKey ||
+                event.ctrlKey ||
+                event.metaKey ||
+                event.shiftKey ||
+                isEditableKeyboardTarget(event.target)
+            ) {
+                return;
+            }
+
+            event.preventDefault();
+            window.location.assign(href);
+        };
+
+        window.addEventListener('keydown', handleKeyDown);
+
+        return () => {
+            window.removeEventListener('keydown', handleKeyDown);
+        };
+    }, [href, isEnabled]);
+
+    return null;
+}
+
+/**
+ * Returns whether a keyboard event originated from an editable element.
+ *
+ * @param target - Raw event target.
+ * @returns `true` when the target should keep the `.` keystroke.
+ */
+function isEditableKeyboardTarget(target: EventTarget | null): boolean {
+    if (!(target instanceof HTMLElement)) {
+        return false;
+    }
+
+    if (target.isContentEditable) {
+        return true;
+    }
+
+    const tagName = target.tagName.toLowerCase();
+    return tagName === 'input' || tagName === 'textarea' || tagName === 'select';
+}

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

@@ -0,0 +1,77 @@
+'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';
+
+/**
+ * Starts one project from its project page.
+ *
+ * @param agentPermanentId - Permanent id of the agent owning the project.
+ * @param projectName - Project directory name.
+ */
+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);
+}
+
+/**
+ * Terminates the runtime assigned to one project from its project page.
+ *
+ * @param agentPermanentId - Permanent id of the agent owning the project.
+ * @param projectName - Project directory name.
+ */
+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');
+}

package/apps/agents-server/src/app/agents/[agentName]/projects/[projectName]/files/[...filePath]/route.ts

@@ -0,0 +1,86 @@
+import { NextResponse } from 'next/server';
+import { NotAllowed } from '../../../../../../../../../../src/errors/NotAllowed';
+import { NotFoundError } from '../../../../../../../../../../src/errors/NotFoundError';
+import { createAgentForbiddenResponse } from '@/src/utils/agentAccess';
+import {
+    AGENT_PROJECT_DETAILS_FORBIDDEN_MESSAGE,
+    resolveAgentProjectsAccess,
+} from '@/src/utils/agentProjects/agentProjectAccess';
+import { readAgentProjectFile } from '@/src/utils/agentProjects/readAgentProjectFile';
+import { resolveAgentRouteTarget } from '@/src/utils/agentRouting/resolveAgentRouteTarget';
+
+/**
+ * Content types that can execute scripts or load same-origin resources when rendered.
+ */
+const SANDBOXED_CONTENT_TYPE_PREFIXES = ['text/html', 'image/svg+xml', 'application/xml'];
+
+/**
+ * Serves one raw file of one agent project.
+ *
+ * The agent references these URLs in chat answers to share its project files, so access
+ * follows the agent visibility rules — whoever may chat with the agent may open the links.
+ */
+export async function GET(
+    request: Request,
+    { params }: { params: Promise<{ agentName: string; projectName: string; filePath: ReadonlyArray<string> }> },
+) {
+    const { agentName: rawAgentName, projectName: rawProjectName, filePath: rawFilePath } = await params;
+    const agentIdentifier = decodeURIComponent(rawAgentName);
+
+    const routeTarget = await resolveAgentRouteTarget(agentIdentifier);
+    if (routeTarget === null || routeTarget.kind !== 'local') {
+        return NextResponse.json({ error: 'Agent not found.' }, { status: 404 });
+    }
+
+    const access = await resolveAgentProjectsAccess(routeTarget.canonicalAgentId, { request });
+    if (!access.isProjectOverviewVisible) {
+        return createAgentForbiddenResponse();
+    }
+
+    if (!access.isProjectDetailsVisible) {
+        return createAgentForbiddenResponse(AGENT_PROJECT_DETAILS_FORBIDDEN_MESSAGE);
+    }
+
+    try {
+        const projectFile = await readAgentProjectFile({
+            agentPermanentId: routeTarget.canonicalAgentId,
+            projectName: decodeURIComponent(rawProjectName),
+            filePathSegments: rawFilePath.map((filePathSegment) => decodeURIComponent(filePathSegment)),
+        });
+
+        return new NextResponse(new Uint8Array(projectFile.content), {
+            status: 200,
+            headers: createProjectFileResponseHeaders(projectFile.contentType),
+        });
+    } catch (error) {
+        if (error instanceof NotAllowed) {
+            return NextResponse.json({ error: error.message }, { status: 400 });
+        }
+
+        if (error instanceof NotFoundError) {
+            return NextResponse.json({ error: error.message }, { status: 404 });
+        }
+
+        throw error;
+    }
+}
+
+/**
+ * Creates response headers keeping served project files safe to open in the browser.
+ *
+ * Active content (HTML, SVG, XML) is sandboxed into an opaque origin so a hosted page can
+ * render and run its own scripts but can never read Agents Server cookies or storage.
+ */
+function createProjectFileResponseHeaders(contentType: string): Headers {
+    const headers = new Headers({
+        'Content-Type': contentType,
+        'X-Content-Type-Options': 'nosniff',
+        'Cache-Control': 'no-store',
+    });
+
+    if (SANDBOXED_CONTENT_TYPE_PREFIXES.some((sandboxedPrefix) => contentType.startsWith(sandboxedPrefix))) {
+        headers.set('Content-Security-Policy', 'sandbox allow-scripts allow-forms allow-popups');
+    }
+
+    return headers;
+}