@promptbook/cli 0.114.0-0 → 0.114.0-10

package/apps/agents-server/src/components/AgentProjects/AgentProjectItem.tsx

@@ -1,9 +1,9 @@
-import { FolderKanbanIcon } from 'lucide-react';
 import Link from 'next/link';
 import type { ReactNode } from 'react';
 import type { AgentProjectReferenceInfo } from '../../utils/agentProjects/AgentProjectReferenceInfo';
 import { buildAgentProjectProfileHrefForServer } from '../../utils/agentProjects/agentProjectHrefs';
 import { formatResourceBytes } from '../../utils/resourceMonitor/formatResourceMonitorValue';
+import { AgentProjectIcon } from './AgentProjectIcon';
 
 /**
  * Visual variants supported by project references.
@@ -76,12 +76,22 @@ export function AgentProjectItem({
         serverDomain,
         currentServerDomain,
     });
+    const icon = (
+        <AgentProjectIcon
+            agentPermanentId={agentPermanentId}
+            project={project}
+            serverDomain={serverDomain}
+            currentServerDomain={currentServerDomain}
+            size={variant === 'small' ? 'small' : 'card'}
+            className={variant === 'small' ? 'mt-0.5' : ''}
+        />
+    );
 
     if (variant === 'small') {
-        return <SmallAgentProjectItem href={href} project={project} className={className} />;
+        return <SmallAgentProjectItem href={href} project={project} icon={icon} className={className} />;
     }
 
-    return <FullAgentProjectItem href={href} project={project} className={className} footer={footer} />;
+    return <FullAgentProjectItem href={href} project={project} icon={icon} className={className} footer={footer} />;
 }
 
 /**
@@ -98,6 +108,11 @@ type AgentProjectItemVariantProps = {
      */
     readonly project: AgentProjectItemInfo;
 
+    /**
+     * Rendered project icon.
+     */
+    readonly icon: ReactNode;
+
     /**
      * Optional CSS class overrides.
      */
@@ -115,16 +130,17 @@ type AgentProjectItemVariantProps = {
  * @param props - Project item variant props.
  * @returns Full project link card.
  */
-function FullAgentProjectItem({ href, project, className, footer }: AgentProjectItemVariantProps) {
+function FullAgentProjectItem({ href, project, icon, className, footer }: AgentProjectItemVariantProps) {
     const isFooterVisible = footer !== undefined && footer !== null;
     const projectContent = (
         <>
             <div className="flex items-start gap-3">
-                <div className="flex h-11 w-11 shrink-0 items-center justify-center rounded-lg border border-blue-100 bg-blue-50 text-blue-700">
-                    <FolderKanbanIcon className="h-5 w-5" aria-hidden />
-                </div>
+                {icon}
                 <div className="min-w-0 flex-1">
-                    <h3 className="truncate text-base font-semibold text-gray-950 group-hover:text-blue-700">
+                    <h3
+                        className="line-clamp-2 text-base font-semibold text-gray-950 group-hover:text-blue-700"
+                        title={project.displayName}
+                    >
                         {project.displayName}
                     </h3>
                     {project.displayName !== project.projectName && (
@@ -170,14 +186,14 @@ function FullAgentProjectItem({ href, project, className, footer }: AgentProject
  * @param props - Project item variant props.
  * @returns Compact project link item.
  */
-function SmallAgentProjectItem({ href, project, className }: AgentProjectItemVariantProps) {
+function SmallAgentProjectItem({ href, project, icon, className }: AgentProjectItemVariantProps) {
     return (
         <Link
             href={href}
             title={project.description || project.displayName}
             className={`inline-flex max-w-full items-start gap-2 rounded-lg border border-gray-200 bg-white px-3 py-2 text-left shadow-sm transition hover:border-blue-300 hover:bg-blue-50/50 ${className}`}
         >
-            <FolderKanbanIcon className="mt-0.5 h-4 w-4 shrink-0 text-blue-600" aria-hidden />
+            {icon}
             <span className="min-w-0 flex-1">
                 <span className="block truncate text-sm font-semibold text-gray-900">{project.displayName}</span>
                 {project.description && (

package/apps/agents-server/src/components/AgentProjects/useAgentProjectMarkdownReferences.ts

@@ -0,0 +1,184 @@
+'use client';
+
+import type { MarkdownInlineReference } from '@promptbook-local/types';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import {
+    $startAgentProjectRuntimeAction,
+    $stopAgentProjectRuntimeAction,
+} from '../../app/agents/[agentName]/projectRuntimeActions';
+import type { AgentProjectReferenceInfo } from '../../utils/agentProjects/AgentProjectReferenceInfo';
+import type { AgentProjectRuntimeActionResult } from '../../utils/agentProjects/AgentProjectRuntimeActionResult';
+import {
+    createAgentProjectMarkdownReferences,
+    type AgentProjectMarkdownReferenceInfo,
+} from '../../utils/agentProjects/createAgentProjectMarkdownReferences';
+import { notifyError } from '../Notifications/notifications';
+
+/**
+ * Options used to build interactive project references for an Agents Server chat.
+ */
+type UseAgentProjectMarkdownReferencesOptions = {
+    /**
+     * Permanent id of the agent owning the projects.
+     */
+    readonly agentPermanentId: string;
+
+    /**
+     * Initial browser-safe project references loaded by the server page.
+     */
+    readonly projects: ReadonlyArray<AgentProjectReferenceInfo>;
+};
+
+/**
+ * Creates interactive project chips and keeps their runtime state current after menu actions.
+ *
+ * @param options - Owning agent and initial projects.
+ * @returns Markdown references consumed by the shared chat renderer.
+ */
+export function useAgentProjectMarkdownReferences(
+    options: UseAgentProjectMarkdownReferencesOptions,
+): ReadonlyArray<MarkdownInlineReference> {
+    const { agentPermanentId, projects } = options;
+    const [currentProjects, setCurrentProjects] = useState<ReadonlyArray<AgentProjectReferenceInfo>>(projects);
+    const previousProjectsRef = useRef(projects);
+
+    useEffect(() => {
+        if (areAgentProjectReferencesEqual(previousProjectsRef.current, projects)) {
+            return;
+        }
+
+        previousProjectsRef.current = projects;
+        setCurrentProjects(projects);
+    }, [projects]);
+
+    /**
+     * Merges one action result into the local project reference state.
+     */
+    const updateProjectRuntimeState = useCallback(
+        (projectName: string, result: AgentProjectRuntimeActionResult): void => {
+            setCurrentProjects((currentProjectReferences) =>
+                currentProjectReferences.map((project) =>
+                    project.projectName === projectName
+                        ? {
+                              ...project,
+                              isRunning: result.isRunning,
+                              projectUrl: result.projectUrl || project.projectUrl || null,
+                          }
+                        : project,
+                ),
+            );
+        },
+        [],
+    );
+
+    /**
+     * Starts or stops one project from its chip menu.
+     */
+    const changeProjectRuntime = useCallback(
+        async (project: AgentProjectMarkdownReferenceInfo, isRunning: boolean): Promise<void> => {
+            try {
+                const result = isRunning
+                    ? await $startAgentProjectRuntimeAction(agentPermanentId, project.projectName)
+                    : await $stopAgentProjectRuntimeAction(agentPermanentId, project.projectName);
+
+                updateProjectRuntimeState(project.projectName, result);
+
+                if (isRunning && !result.isRunning) {
+                    notifyError(`Project \`${project.displayName}\` did not start.`);
+                }
+            } catch (error) {
+                const actionName = isRunning ? 'start' : 'stop';
+                notifyError(resolveProjectRuntimeErrorMessage(error, `Failed to ${actionName} the project.`), {
+                    details: error,
+                });
+            }
+        },
+        [agentPermanentId, updateProjectRuntimeState],
+    );
+
+    /**
+     * Starts a stopped project and transfers an already-opened browser tab to its public URL.
+     */
+    const openProject = useCallback(
+        async (project: AgentProjectMarkdownReferenceInfo): Promise<void> => {
+            const projectWindow = window.open('about:blank', '_blank');
+
+            if (!projectWindow) {
+                notifyError('The browser blocked the new project tab.');
+                return;
+            }
+
+            projectWindow.opener = null;
+
+            try {
+                const result = await $startAgentProjectRuntimeAction(agentPermanentId, project.projectName);
+                updateProjectRuntimeState(project.projectName, result);
+
+                if (!result.isRunning || !result.projectUrl) {
+                    projectWindow.close();
+                    notifyError(`Project \`${project.displayName}\` did not start.`);
+                    return;
+                }
+
+                projectWindow.location.href = result.projectUrl;
+            } catch (error) {
+                projectWindow.close();
+                notifyError(resolveProjectRuntimeErrorMessage(error, 'Failed to start and open the project.'), {
+                    details: error,
+                });
+            }
+        },
+        [agentPermanentId, updateProjectRuntimeState],
+    );
+
+    return useMemo(
+        () =>
+            createAgentProjectMarkdownReferences({
+                agentPermanentId,
+                projects: currentProjects,
+                onOpenProject: openProject,
+                onChangeProjectRuntime: changeProjectRuntime,
+            }),
+        [agentPermanentId, changeProjectRuntime, currentProjects, openProject],
+    );
+}
+
+/**
+ * Selects a useful server-action error message without assuming a particular serialized error type.
+ *
+ * @param error - Unknown action failure.
+ * @param fallbackMessage - Message used when the action exposes no details.
+ * @returns User-facing error message.
+ */
+function resolveProjectRuntimeErrorMessage(error: unknown, fallbackMessage: string): string {
+    return error instanceof Error && error.message.trim() ? error.message : fallbackMessage;
+}
+
+/**
+ * Compares the project fields which affect a rendered chat reference.
+ *
+ * @param firstProjects - Previously received project references.
+ * @param secondProjects - Newly received project references.
+ * @returns Whether both collections render and behave identically in project chips.
+ */
+function areAgentProjectReferencesEqual(
+    firstProjects: ReadonlyArray<AgentProjectReferenceInfo>,
+    secondProjects: ReadonlyArray<AgentProjectReferenceInfo>,
+): boolean {
+    return (
+        firstProjects.length === secondProjects.length &&
+        firstProjects.every((firstProject, projectIndex) => {
+            const secondProject = secondProjects[projectIndex];
+
+            return (
+                secondProject !== undefined &&
+                firstProject.projectName === secondProject.projectName &&
+                firstProject.displayName === secondProject.displayName &&
+                firstProject.description === secondProject.description &&
+                firstProject.faviconRelativePath === secondProject.faviconRelativePath &&
+                firstProject.isRunning === secondProject.isRunning &&
+                firstProject.projectUrl === secondProject.projectUrl
+            );
+        })
+    );
+}

package/apps/agents-server/src/components/CloudflareDnsWizard/CloudflareDnsApiTokenImportStep.tsx

@@ -2,7 +2,7 @@
 
 import { useState } from 'react';
 import type { CloudflareDnsBatchRecordStatus } from '../../utils/cloudflare/CloudflareDnsBatchApplication';
-import type { DnsRecordSelection } from '../../utils/dnsRecords/DnsRecordInstruction';
+import type { DnsRecordGroup } from '../../utils/dnsRecords/DnsRecordInstruction';
 import type { DnsRecordBatchPlan } from '../../utils/dnsRecords/resolveDnsRecordBatchPlan';
 import { CloudflareDnsExcludedRecordsNote } from './CloudflareDnsExcludedRecordsNote';
 import { useCloudflareDnsRecordImport } from './useCloudflareDnsRecordImport';
@@ -35,7 +35,7 @@ const CLOUDFLARE_DNS_IMPORT_STATUS_CLASS_NAMES: Record<CloudflareDnsBatchRecordS
 export function CloudflareDnsApiTokenImportStep({
     batchPlan,
     domain,
-    recordSelection,
+    recordGroups,
 }: {
     /**
      * Records which can be imported at once together with the excluded ones.
@@ -48,15 +48,14 @@ export function CloudflareDnsApiTokenImportStep({
     readonly domain: string;
 
     /**
-     * Whether all listed records or one listed alternative must be configured.
+     * All record groups displayed by the DNS manual.
      */
-    readonly recordSelection: DnsRecordSelection;
+    readonly recordGroups: ReadonlyArray<DnsRecordGroup>;
 }) {
     const [apiToken, setApiToken] = useState('');
     const { isImporting, application, errorMessage, importRecords } = useCloudflareDnsRecordImport({
         domain,
-        recordSelection,
-        records: batchPlan.applicableRecords,
+        recordGroups,
     });
     const recordCount = batchPlan.applicableRecords.length;
 

package/apps/agents-server/src/components/CloudflareDnsWizard/CloudflareDnsCheckStep.tsx

@@ -1,4 +1,5 @@
-import type { DnsRecordSelection } from '../../utils/dnsRecords/DnsRecordInstruction';
+import type { DnsRecordGroup } from '../../utils/dnsRecords/DnsRecordInstruction';
+import { hasAlternativeDnsRecordGroup } from '../../utils/dnsRecords/dnsRecordGroups';
 
 /**
  * Explains how to verify the configured records after they were written to Cloudflare.
@@ -6,18 +7,18 @@ import type { DnsRecordSelection } from '../../utils/dnsRecords/DnsRecordInstruc
  * @private used by the Cloudflare DNS setup wizard
  */
 export function CloudflareDnsCheckStep({
-    recordSelection,
+    recordGroups,
 }: {
     /**
-     * Whether all listed records or one listed alternative must be configured.
+     * All record groups displayed by the DNS manual.
      */
-    readonly recordSelection: DnsRecordSelection;
+    readonly recordGroups: ReadonlyArray<DnsRecordGroup>;
 }) {
     return (
         <div className="space-y-2">
             <p className="font-medium">Check the result</p>
             <ol className="list-decimal space-y-1 pl-5 text-amber-900">
-                {recordSelection === 'one' ? (
+                {hasAlternativeDnsRecordGroup(recordGroups) ? (
                     <li>Remove conflicting A, AAAA, or CNAME records for the same hostname.</li>
                 ) : null}
                 <li>Wait for DNS propagation.</li>

package/apps/agents-server/src/components/CloudflareDnsWizard/CloudflareDnsManualStep.tsx

@@ -1,5 +1,6 @@
 import { isProxyableCloudflareDnsRecordType } from '../../utils/cloudflare/CloudflareApi';
-import type { DnsRecordInstruction, DnsRecordSelection } from '../../utils/dnsRecords/DnsRecordInstruction';
+import type { DnsRecordGroup } from '../../utils/dnsRecords/DnsRecordInstruction';
+import { countDnsRecordGroupRecords, isEveryDnsRecordGroupAlternative } from '../../utils/dnsRecords/dnsRecordGroups';
 
 /**
  * Direct Cloudflare dashboard URL for the DNS records page.
@@ -15,8 +16,7 @@ const CLOUDFLARE_DNS_RECORDS_URL = 'https://dash.cloudflare.com/?to=/:account/:z
  */
 export function CloudflareDnsManualStep({
     domain,
-    recordSelection,
-    records,
+    recordGroups,
 }: {
     /**
      * Hostname whose DNS records are being configured.
@@ -24,20 +24,16 @@ export function CloudflareDnsManualStep({
     readonly domain: string;
 
     /**
-     * Whether all listed records or one listed alternative must be configured.
+     * All record groups displayed by the DNS manual.
      */
-    readonly recordSelection: DnsRecordSelection;
-
-    /**
-     * The canonical DNS records displayed by the parent instruction panel.
-     */
-    readonly records: ReadonlyArray<DnsRecordInstruction>;
+    readonly recordGroups: ReadonlyArray<DnsRecordGroup>;
 }) {
+    const records = recordGroups.flatMap((recordGroup) => recordGroup.records);
     const isProxyStatusRelevant = records.some((record) => isProxyableCloudflareDnsRecordType(record.type));
-    const recordSelectionInstruction =
-        recordSelection === 'all'
-            ? `Repeat this for all ${records.length} record${records.length === 1 ? '' : 's'} shown above.`
-            : 'Choose one of the record alternatives shown above.';
+    const recordCount = countDnsRecordGroupRecords(recordGroups);
+    const recordSelectionInstruction = isEveryDnsRecordGroupAlternative(recordGroups)
+        ? 'Choose one of the record alternatives shown above.'
+        : `Repeat this for all ${recordCount} record${recordCount === 1 ? '' : 's'} shown above.`;
 
     return (
         <div className="space-y-2">

package/apps/agents-server/src/components/CloudflareDnsWizard/CloudflareDnsWizard.tsx

@@ -1,8 +1,8 @@
 'use client';
 
 import { useState } from 'react';
-import type { DnsRecordInstruction, DnsRecordSelection } from '../../utils/dnsRecords/DnsRecordInstruction';
-import { resolveDnsRecordBatchPlan } from '../../utils/dnsRecords/resolveDnsRecordBatchPlan';
+import type { DnsRecordGroup } from '../../utils/dnsRecords/DnsRecordInstruction';
+import { resolveDnsRecordBatchPlanForGroups } from '../../utils/dnsRecords/resolveDnsRecordBatchPlan';
 import { CloudflareDnsApiTokenImportStep } from './CloudflareDnsApiTokenImportStep';
 import { CloudflareDnsCheckStep } from './CloudflareDnsCheckStep';
 import { CloudflareDnsManualStep } from './CloudflareDnsManualStep';
@@ -15,14 +15,14 @@ import { CloudflareDnsZoneFileImportStep } from './CloudflareDnsZoneFileImportSt
  *
  * The record table remains the single source of truth for the values to configure. This wizard adds the two batch
  * ways of configuring all of them at once - an API token import and a zone file import - and keeps the manual steps
- * as a fallback.
+ * as a fallback. All record groups of the DNS manual, for example the server domain, the generated project domains,
+ * and the email records, are configured by this one wizard together.
  *
  * @private shared by the Agents Server DNS instruction views
  */
 export function CloudflareDnsWizard({
     domain,
-    recordSelection,
-    records,
+    recordGroups,
 }: {
     /**
      * Hostname whose DNS records are being configured.
@@ -30,16 +30,11 @@ export function CloudflareDnsWizard({
     readonly domain: string;
 
     /**
-     * Whether all listed records or one listed alternative must be configured.
+     * All record groups displayed by the parent instruction panel.
      */
-    readonly recordSelection: DnsRecordSelection;
-
-    /**
-     * The canonical DNS records displayed by the parent instruction panel.
-     */
-    readonly records: ReadonlyArray<DnsRecordInstruction>;
+    readonly recordGroups: ReadonlyArray<DnsRecordGroup>;
 }) {
-    const batchPlan = resolveDnsRecordBatchPlan({ records, recordSelection });
+    const batchPlan = resolveDnsRecordBatchPlanForGroups(recordGroups);
     const isBatchImportAvailable = batchPlan.applicableRecords.length > 0;
     const availableSteps = CLOUDFLARE_DNS_WIZARD_STEPS.filter((step) => isBatchImportAvailable || !step.isBatchStep);
     const [currentStep, setCurrentStep] = useState<CloudflareDnsWizardStep>(
@@ -67,11 +62,7 @@ export function CloudflareDnsWizard({
             />
 
             {currentStep === 'import-with-api-token' ? (
-                <CloudflareDnsApiTokenImportStep
-                    batchPlan={batchPlan}
-                    domain={domain}
-                    recordSelection={recordSelection}
-                />
+                <CloudflareDnsApiTokenImportStep batchPlan={batchPlan} domain={domain} recordGroups={recordGroups} />
             ) : null}
 
             {currentStep === 'import-zone-file' ? (
@@ -79,10 +70,10 @@ export function CloudflareDnsWizard({
             ) : null}
 
             {currentStep === 'add-manually' ? (
-                <CloudflareDnsManualStep domain={domain} recordSelection={recordSelection} records={records} />
+                <CloudflareDnsManualStep domain={domain} recordGroups={recordGroups} />
             ) : null}
 
-            {currentStep === 'check-dns' ? <CloudflareDnsCheckStep recordSelection={recordSelection} /> : null}
+            {currentStep === 'check-dns' ? <CloudflareDnsCheckStep recordGroups={recordGroups} /> : null}
         </section>
     );
 }

package/apps/agents-server/src/components/CloudflareDnsWizard/useCloudflareDnsRecordImport.ts

@@ -2,7 +2,7 @@
 
 import { useCallback, useState } from 'react';
 import type { CloudflareDnsBatchApplication } from '../../utils/cloudflare/CloudflareDnsBatchApplication';
-import type { DnsRecordInstruction, DnsRecordSelection } from '../../utils/dnsRecords/DnsRecordInstruction';
+import type { DnsRecordGroup } from '../../utils/dnsRecords/DnsRecordInstruction';
 
 /**
  * Endpoint which writes the records of one DNS manual into Cloudflare.
@@ -23,8 +23,7 @@ const CLOUDFLARE_DNS_IMPORT_ENDPOINT = '/api/admin/dns-records/cloudflare';
  */
 export function useCloudflareDnsRecordImport(options: {
     readonly domain: string;
-    readonly recordSelection: DnsRecordSelection;
-    readonly records: ReadonlyArray<DnsRecordInstruction>;
+    readonly recordGroups: ReadonlyArray<DnsRecordGroup>;
 }): {
     readonly isImporting: boolean;
     readonly application: CloudflareDnsBatchApplication | null;
@@ -34,7 +33,7 @@ export function useCloudflareDnsRecordImport(options: {
     const [isImporting, setIsImporting] = useState(false);
     const [application, setApplication] = useState<CloudflareDnsBatchApplication | null>(null);
     const [errorMessage, setErrorMessage] = useState<string | null>(null);
-    const { domain, recordSelection, records } = options;
+    const { domain, recordGroups } = options;
 
     const importRecords = useCallback(
         async (apiToken: string) => {
@@ -46,7 +45,7 @@ export function useCloudflareDnsRecordImport(options: {
                 const response = await fetch(CLOUDFLARE_DNS_IMPORT_ENDPOINT, {
                     method: 'POST',
                     headers: { 'Content-Type': 'application/json' },
-                    body: JSON.stringify({ apiToken, domain, recordSelection, records }),
+                    body: JSON.stringify({ apiToken, domain, recordGroups }),
                 });
                 const payload = (await response.json().catch(() => null)) as
                     | (CloudflareDnsBatchApplication & { readonly error?: string })
@@ -64,7 +63,7 @@ export function useCloudflareDnsRecordImport(options: {
                 setIsImporting(false);
             }
         },
-        [domain, recordSelection, records],
+        [domain, recordGroups],
     );
 
     return { isImporting, application, errorMessage, importRecords };