@promptbook/cli 0.114.0-0 → 0.114.0-10

package/apps/agents-server/src/utils/agentGoalChat/prependAgentGoalChatSummarySeed.ts

@@ -0,0 +1,40 @@
+import { serializeError } from '@promptbook-local/utils';
+import type { UserChatSummarySeed } from '../userChat/createUserChatSummary';
+import { createUserChatSummarySeedFromChatRecord } from '../userChat/listUserChats';
+import { ensureAgentGoalChat } from './ensureAgentGoalChat';
+import { isAgentGoalChatId } from './agentGoalChatIdentity';
+
+/**
+ * Puts the singleton goal chat of one agent on top of the chat-history list.
+ *
+ * The goal chat is not owned by the viewer and is therefore not part of the normal chat listing
+ * query, so it is resolved separately and pinned in front of every other chat.
+ *
+ * @param options - Loaded chat seeds together with the agent and the viewer's access decision.
+ * @returns Chat seeds, with the goal chat first whenever the viewer may read it.
+ */
+export async function prependAgentGoalChatSummarySeed(options: {
+    readonly chatSummarySeeds: ReadonlyArray<UserChatSummarySeed>;
+    readonly agentPermanentId: string;
+    readonly isAgentGoalChatVisible: boolean;
+}): Promise<Array<UserChatSummarySeed>> {
+    const otherChatSummarySeeds = options.chatSummarySeeds.filter(
+        (chatSummarySeed) => !isAgentGoalChatId(chatSummarySeed.id),
+    );
+
+    if (!options.isAgentGoalChatVisible) {
+        return otherChatSummarySeeds;
+    }
+
+    try {
+        const goalChat = await ensureAgentGoalChat(options.agentPermanentId);
+        return [createUserChatSummarySeedFromChatRecord(goalChat), ...otherChatSummarySeeds];
+    } catch (error) {
+        // Note: A missing goal chat must never break the chat list of the agent
+        console.error('[agent-goal-chat]', 'list_seed_failed', {
+            agentPermanentId: options.agentPermanentId,
+            error: serializeError(error as Error),
+        });
+        return otherChatSummarySeeds;
+    }
+}

package/apps/agents-server/src/utils/agentGoalChat/recordAgentGoalChatLifecycleNote.ts

@@ -0,0 +1,53 @@
+import { computeHash, serializeError } from '@promptbook-local/utils';
+import type { string_book } from '../../../../../src/book-2.0/agent-source/string_book';
+import { appendAgentGoalChatNote } from './appendAgentGoalChatNote';
+import {
+    createAgentGoalChatLifecycleNoteContent,
+    type AgentGoalChatLifecycleEvent,
+} from './createAgentGoalChatNoteContent';
+import { enqueueAgentGoalChatTurn } from './enqueueAgentGoalChatTurn';
+import { resolveEffectiveAgentGoal } from './resolveEffectiveAgentGoal';
+
+/**
+ * Leaves the goal-chat note that records one agent lifecycle event.
+ *
+ * Writing the note is best-effort on purpose: creating or saving an agent must never fail because
+ * its goal chat could not be updated.
+ *
+ * @param options - Lifecycle event together with the affected agent.
+ */
+export async function recordAgentGoalChatLifecycleNote(options: {
+    readonly event: AgentGoalChatLifecycleEvent;
+    readonly agentPermanentId: string;
+    readonly agentName: string;
+    readonly agentSource: string_book;
+}): Promise<void> {
+    try {
+        const currentGoal = resolveEffectiveAgentGoal(options.agentSource);
+        const content = createAgentGoalChatLifecycleNoteContent({
+            event: options.event,
+            agentName: options.agentName,
+            currentGoal,
+        });
+
+        if (currentGoal) {
+            await enqueueAgentGoalChatTurn({
+                agentPermanentId: options.agentPermanentId,
+                content,
+                sourceFingerprint: computeHash(options.agentSource),
+                trigger: options.event,
+            });
+        } else {
+            await appendAgentGoalChatNote({
+                agentPermanentId: options.agentPermanentId,
+                content,
+            });
+        }
+    } catch (error) {
+        console.error('[agent-goal-chat]', 'lifecycle_note_failed', {
+            event: options.event,
+            agentPermanentId: options.agentPermanentId,
+            error: serializeError(error as Error),
+        });
+    }
+}

package/apps/agents-server/src/utils/agentGoalChat/resolveAgentGoalChatOwnerUserId.ts

@@ -0,0 +1,104 @@
+import { spaceTrim } from 'spacetrim';
+import { DatabaseError } from '../../../../../src/errors/DatabaseError';
+import { $getTableName } from '../../database/$getTableName';
+import { $provideSupabaseForServer } from '../../database/$provideSupabaseForServer';
+
+/**
+ * Resolves the database user the singleton goal chat of one agent is stored under.
+ *
+ * The goal chat conceptually belongs to the agent, not to any human, but `UserChat.userId` is a
+ * non-null foreign key. The agent owner is therefore used, with the same fallback ordering the
+ * ownership migration uses when an agent has no owner assigned yet.
+ *
+ * @param agentPermanentId - Permanent id of the agent owning the goal chat.
+ * @returns Database user id used as the goal-chat owner.
+ */
+export async function resolveAgentGoalChatOwnerUserId(agentPermanentId: string): Promise<number> {
+    const agentOwnerUserId = await loadAgentOwnerUserId(agentPermanentId);
+
+    if (typeof agentOwnerUserId === 'number') {
+        return agentOwnerUserId;
+    }
+
+    return loadFallbackOwnerUserId(agentPermanentId);
+}
+
+/**
+ * Loads the owner of one agent row.
+ *
+ * @param agentPermanentId - Permanent id of the agent.
+ * @returns Owning user id, or `null` when the agent has no owner assigned.
+ *
+ * @private function of `resolveAgentGoalChatOwnerUserId`
+ */
+async function loadAgentOwnerUserId(agentPermanentId: string): Promise<number | null> {
+    const supabase = $provideSupabaseForServer();
+    const agentTableName = await $getTableName('Agent');
+    const { data, error } = await supabase
+        .from(agentTableName)
+        .select('userId')
+        .eq('permanentId', agentPermanentId)
+        .maybeSingle();
+
+    if (error) {
+        throw new DatabaseError(
+            spaceTrim(`
+                Failed to load the owner of agent \`${agentPermanentId}\` for its goal chat.
+
+                **Cause:** \`${error.message}\`
+            `),
+        );
+    }
+
+    const userId = (data as { userId?: unknown } | null)?.userId;
+    return typeof userId === 'number' ? userId : null;
+}
+
+/**
+ * Loads the fallback goal-chat owner used when an agent has no owner assigned.
+ *
+ * Mirrors the `fallbackUser` ordering of the ownership migration so unowned agents keep a stable,
+ * predictable goal-chat owner.
+ *
+ * @param agentPermanentId - Permanent id of the agent, used only for error reporting.
+ * @returns Database user id of the fallback owner.
+ *
+ * @private function of `resolveAgentGoalChatOwnerUserId`
+ */
+async function loadFallbackOwnerUserId(agentPermanentId: string): Promise<number> {
+    const supabase = $provideSupabaseForServer();
+    const userTableName = await $getTableName('User');
+    const { data, error } = await supabase
+        .from(userTableName)
+        .select('id')
+        .order('isAdmin', { ascending: false })
+        .order('createdAt', { ascending: true })
+        .order('id', { ascending: true })
+        .limit(1)
+        .maybeSingle();
+
+    if (error) {
+        throw new DatabaseError(
+            spaceTrim(`
+                Failed to resolve the fallback goal-chat owner for agent \`${agentPermanentId}\`.
+
+                **Cause:** \`${error.message}\`
+            `),
+        );
+    }
+
+    const fallbackUserId = (data as { id?: unknown } | null)?.id;
+
+    if (typeof fallbackUserId !== 'number') {
+        throw new DatabaseError(
+            spaceTrim(`
+                Agent \`${agentPermanentId}\` has no owner and this server has no user to fall back to,
+                so its goal chat cannot be stored.
+
+                **Note:** Every goal chat is persisted as one \`UserChat\` row, which requires a \`userId\`.
+            `),
+        );
+    }
+
+    return fallbackUserId;
+}

package/apps/agents-server/src/utils/agentGoalChat/resolveEffectiveAgentGoal.ts

@@ -0,0 +1,29 @@
+import type { string_book } from '../../../../../src/book-2.0/agent-source/string_book';
+import { parseAgentSourceWithCommitments } from '../../../../../src/book-2.0/agent-source/parseAgentSourceWithCommitments';
+
+/**
+ * Resolves the effective non-empty `GOAL` or `GOALS` commitment from one agent source.
+ *
+ * Goal commitments overwrite each other in source order, so the last non-empty declaration is
+ * the same goal that reaches the agent model requirements.
+ *
+ * @param agentSource - Current persisted agent source.
+ * @returns Effective goal text, or `null` when no goal is defined.
+ */
+export function resolveEffectiveAgentGoal(agentSource: string_book): string | null {
+    const commitments = parseAgentSourceWithCommitments(agentSource).commitments;
+
+    for (let index = commitments.length - 1; index >= 0; index--) {
+        const commitment = commitments[index]!;
+        if (commitment.type !== 'GOAL' && commitment.type !== 'GOALS') {
+            continue;
+        }
+
+        const goal = commitment.content.trim();
+        if (goal) {
+            return goal;
+        }
+    }
+
+    return null;
+}

package/apps/agents-server/src/utils/agentGoalChat/scheduleAgentGoalChatModifiedNote.ts

@@ -0,0 +1,85 @@
+import { debounce } from '@promptbook-local/utils';
+import type { ProvidedServer } from '@/src/tools/$provideServer';
+import { runWithServerContextOverride } from '@/src/tools/serverContextOverride';
+import type { string_book } from '../../../../../src/book-2.0/agent-source/string_book';
+import { recordAgentGoalChatLifecycleNote } from './recordAgentGoalChatLifecycleNote';
+
+/**
+ * Delay after the final persisted book update before the goal chat receives one modification note.
+ */
+export const AGENT_GOAL_CHAT_MODIFIED_NOTE_DEBOUNCE_DELAY_MS = 60_000;
+
+/**
+ * Agent identity used to write one delayed book-modification note.
+ *
+ * @private function of scheduleAgentGoalChatModifiedNote
+ */
+type AgentGoalChatModifiedNote = {
+    readonly agentPermanentId: string;
+    readonly agentName: string;
+    readonly agentSource: string_book;
+    readonly server: ProvidedServer;
+};
+
+/**
+ * Runs delayed work under the server that owned the source update.
+ *
+ * @private function of scheduleAgentGoalChatModifiedNote
+ */
+type RunWithServerContext = (
+    server: ProvidedServer,
+    callback: () => Promise<void>,
+) => Promise<void>;
+
+/**
+ * Creates an independent one-minute debounce for each agent's goal-chat modification note.
+ *
+ * @private function of scheduleAgentGoalChatModifiedNote
+ */
+export function createAgentGoalChatModifiedNoteScheduler(options?: {
+    readonly recordAgentGoalChatLifecycleNote?: typeof recordAgentGoalChatLifecycleNote;
+    readonly runWithServerContextOverride?: RunWithServerContext;
+}): (agentGoalChatModifiedNote: AgentGoalChatModifiedNote) => void {
+    const debouncedNoteRecordersByServerAndAgent = new Map<
+        string,
+        ((agentGoalChatModifiedNote: AgentGoalChatModifiedNote) => void) & { cancel: () => void }
+    >();
+    const recordLifecycleNote = options?.recordAgentGoalChatLifecycleNote || recordAgentGoalChatLifecycleNote;
+    const runWithServerContext = options?.runWithServerContextOverride || runWithServerContextOverride;
+
+    return (agentGoalChatModifiedNote: AgentGoalChatModifiedNote) => {
+        const agentGoalChatModifiedNoteKey = createAgentGoalChatModifiedNoteKey(agentGoalChatModifiedNote);
+        let debouncedNoteRecorder = debouncedNoteRecordersByServerAndAgent.get(agentGoalChatModifiedNoteKey);
+
+        if (!debouncedNoteRecorder) {
+            debouncedNoteRecorder = debounce((latestAgentGoalChatModifiedNote: AgentGoalChatModifiedNote) => {
+                debouncedNoteRecordersByServerAndAgent.delete(agentGoalChatModifiedNoteKey);
+                void runWithServerContext(latestAgentGoalChatModifiedNote.server, () =>
+                    recordLifecycleNote({
+                        event: 'MODIFIED',
+                        agentPermanentId: latestAgentGoalChatModifiedNote.agentPermanentId,
+                        agentName: latestAgentGoalChatModifiedNote.agentName,
+                        agentSource: latestAgentGoalChatModifiedNote.agentSource,
+                    }),
+                );
+            }, AGENT_GOAL_CHAT_MODIFIED_NOTE_DEBOUNCE_DELAY_MS);
+            debouncedNoteRecordersByServerAndAgent.set(agentGoalChatModifiedNoteKey, debouncedNoteRecorder);
+        }
+
+        debouncedNoteRecorder(agentGoalChatModifiedNote);
+    };
+}
+
+/**
+ * Schedules one best-effort goal-chat note after the latest book update of each agent.
+ */
+export const scheduleAgentGoalChatModifiedNote = createAgentGoalChatModifiedNoteScheduler();
+
+/**
+ * Creates the per-server, per-agent key used to keep independent note debounces separate.
+ *
+ * @private function of scheduleAgentGoalChatModifiedNote
+ */
+function createAgentGoalChatModifiedNoteKey(agentGoalChatModifiedNote: AgentGoalChatModifiedNote): string {
+    return JSON.stringify([agentGoalChatModifiedNote.server.tablePrefix, agentGoalChatModifiedNote.agentPermanentId]);
+}

package/apps/agents-server/src/utils/agentGoalChat.ts

@@ -0,0 +1,24 @@
+export { AGENT_GOAL_CHAT_TITLE } from './agentGoalChat/agentGoalChatConstants';
+export {
+    AGENT_GOAL_CHAT_ID_PREFIX,
+    buildAgentGoalChatId,
+    isAgentGoalChatId,
+} from './agentGoalChat/agentGoalChatIdentity';
+export { appendAgentGoalChatNote } from './agentGoalChat/appendAgentGoalChatNote';
+export { canAccessAgentGoalChat } from './agentGoalChat/canAccessAgentGoalChat';
+export {
+    createAgentGoalChatCancelledPlannedMessageNoteContent,
+    createAgentGoalChatLifecycleNoteContent,
+    createAgentGoalChatPlannedMessageNoteContent,
+} from './agentGoalChat/createAgentGoalChatNoteContent';
+export { ensureAgentGoalChat } from './agentGoalChat/ensureAgentGoalChat';
+export {
+    createAgentGoalChatLifecycleClientMessageId,
+    enqueueAgentGoalChatTurn,
+} from './agentGoalChat/enqueueAgentGoalChatTurn';
+export { prependAgentGoalChatSummarySeed } from './agentGoalChat/prependAgentGoalChatSummarySeed';
+export { recordAgentGoalChatLifecycleNote } from './agentGoalChat/recordAgentGoalChatLifecycleNote';
+export { resolveEffectiveAgentGoal } from './agentGoalChat/resolveEffectiveAgentGoal';
+export { resolveAgentGoalChatOwnerUserId } from './agentGoalChat/resolveAgentGoalChatOwnerUserId';
+export { scheduleAgentGoalChatModifiedNote } from './agentGoalChat/scheduleAgentGoalChatModifiedNote';
+export type { AgentGoalChatLifecycleEvent } from './agentGoalChat/createAgentGoalChatNoteContent';

package/apps/agents-server/src/utils/agentProjects/AgentProjectInfo.ts

@@ -12,7 +12,8 @@ export type AgentProjectInfo = {
     readonly projectName: string;
 
     /**
-     * User-facing name of the project, resolved from the README heading when available.
+     * User-facing name of the project, resolved from the README heading, the `index.html` title
+     * or the humanized project directory name.
      */
     readonly displayName: string;
 
@@ -26,6 +27,14 @@ export type AgentProjectInfo = {
      */
     readonly readmeFileName: string | null;
 
+    /**
+     * Path of the project icon relative to the project root, or `null` when the project has no icon.
+     *
+     * The icon is the favicon linked by the project `index.html` or a favicon found in one of the
+     * conventional locations; a project without one is shown with an icon made of its initials.
+     */
+    readonly faviconRelativePath: string | null;
+
     /**
      * Path of the project relative to the agent folder root, for example `projects/my-website`.
      */

package/apps/agents-server/src/utils/agentProjects/AgentProjectReferenceInfo.ts

@@ -5,7 +5,7 @@ import type { AgentProjectInfo } from './AgentProjectInfo';
  */
 export type AgentProjectReferenceInfo = Pick<
     AgentProjectInfo,
-    'projectName' | 'displayName' | 'description' | 'sizeBytes'
+    'projectName' | 'displayName' | 'description' | 'sizeBytes' | 'faviconRelativePath'
 > & {
     /**
      * Whether the project currently accepts requests on its assigned runtime port.
@@ -13,7 +13,10 @@ export type AgentProjectReferenceInfo = Pick<
     readonly isRunning?: boolean;
 
     /**
-     * Public runtime URL when the project has been assigned a runtime, otherwise `null`.
+     * Stable public project URL when the project has an assigned runtime or domain, otherwise `null`.
+     *
+     * The URL stays the same while the project is stopped so that the project stays recognizable
+     * wherever it is referenced.
      */
     readonly projectUrl?: string | null;
 };

package/apps/agents-server/src/utils/agentProjects/AgentProjectRuntimeActionResult.ts

@@ -0,0 +1,14 @@
+/**
+ * Browser-safe runtime state returned after a project chip action.
+ */
+export type AgentProjectRuntimeActionResult = {
+    /**
+     * Whether the project accepts requests after the action completes.
+     */
+    readonly isRunning: boolean;
+
+    /**
+     * Public project URL assigned to the runtime, or `null` when none is available.
+     */
+    readonly projectUrl: string | null;
+};

package/apps/agents-server/src/utils/agentProjects/agentProjectFileNames.ts

@@ -0,0 +1,21 @@
+/**
+ * HTML entrypoint filenames recognized at the root of one agent project, ordered by priority.
+ *
+ * The static project server serves the first existing one of them for a directory request, so the
+ * same list decides which file describes the project — its `<title>` and its favicon.
+ */
+export const AGENT_PROJECT_INDEX_HTML_FILE_NAMES = ['index.html', 'index.htm'] as const;
+
+/**
+ * Conventional favicon locations searched inside one agent project, ordered by priority.
+ *
+ * They are used only when the project `index.html` does not link its icon explicitly.
+ */
+export const AGENT_PROJECT_CONVENTIONAL_FAVICON_RELATIVE_PATHS = [
+    'favicon.ico',
+    'favicon.svg',
+    'favicon.png',
+    'public/favicon.ico',
+    'public/favicon.svg',
+    'public/favicon.png',
+] as const;

package/apps/agents-server/src/utils/agentProjects/agentProjectHrefs.ts

@@ -107,6 +107,26 @@ export function buildAgentProjectFileHref(
     return `${buildAgentProjectProfileHref(agentPermanentId, projectName)}/files/${encodedFilePath}`;
 }
 
+/**
+ * Builds the href serving one raw file of one agent project on its owning server.
+ *
+ * @param options - Project file and server identity.
+ * @returns Server-scoped raw project file href.
+ */
+export function buildAgentProjectFileHrefForServer(options: {
+    readonly agentPermanentId: string;
+    readonly projectName: string;
+    readonly fileRelativePath: string;
+    readonly serverDomain: string | null;
+    readonly currentServerDomain: string | null;
+}): string {
+    return buildAgentProjectHrefForServer(
+        buildAgentProjectFileHref(options.agentPermanentId, options.projectName, options.fileRelativePath),
+        options.serverDomain,
+        options.currentServerDomain,
+    );
+}
+
 /**
  * Builds the href opening one project in browser VS Code.
  *

package/apps/agents-server/src/utils/agentProjects/agentProjectsPaths.ts

@@ -61,18 +61,28 @@ export function parseAgentPermanentIdFromDirectoryName(agentDirectoryName: strin
 }
 
 /**
- * Asserts that one path segment coming from a URL cannot escape its parent directory.
+ * Returns whether one path segment stays inside its parent directory.
  *
  * @param pathSegment - Single decoded path segment (project name or one file path part).
- * @param segmentPurpose - Human-readable description used in the error message.
- * @throws {NotAllowed} When the segment is empty or attempts path traversal.
+ * @returns `true` when the segment is non-empty and cannot escape its parent directory.
  */
-export function assertSafeAgentProjectPathSegment(pathSegment: string, segmentPurpose: string): void {
+export function isSafeAgentProjectPathSegment(pathSegment: string): boolean {
     const isTraversalSegment = pathSegment === '.' || pathSegment === '..';
     const hasPathSeparator = pathSegment.includes('/') || pathSegment.includes('\\');
     const hasNullByte = pathSegment.includes('\0');
 
-    if (pathSegment.length === 0 || isTraversalSegment || hasPathSeparator || hasNullByte) {
+    return pathSegment.length > 0 && !isTraversalSegment && !hasPathSeparator && !hasNullByte;
+}
+
+/**
+ * Asserts that one path segment coming from a URL cannot escape its parent directory.
+ *
+ * @param pathSegment - Single decoded path segment (project name or one file path part).
+ * @param segmentPurpose - Human-readable description used in the error message.
+ * @throws {NotAllowed} When the segment is empty or attempts path traversal.
+ */
+export function assertSafeAgentProjectPathSegment(pathSegment: string, segmentPurpose: string): void {
+    if (!isSafeAgentProjectPathSegment(pathSegment)) {
         throw new NotAllowed(
             spaceTrim(`
                 Invalid ${segmentPurpose} \`${pathSegment}\`.

package/apps/agents-server/src/utils/agentProjects/createAgentProjectDnsRecords.ts

@@ -33,19 +33,52 @@ export type AgentProjectDnsRecord = {
 };
 
 /**
- * Creates the one DNS record shown for a selected project-domain setup.
+ * Placeholder used when preventive project DNS guidance has no assigned project domain yet.
  *
- * @param options - Project domain, server domain, and selected DNS variants.
- * @returns One DNS record instruction.
+ * @private helper for the Agents Server project DNS instructions
+ */
+const PROJECT_DOMAIN_NAME_PLACEHOLDER = '<PROJECT_NAME>';
+
+/**
+ * Inputs used to create one project DNS record instruction.
+ *
+ * @private helper for the Agents Server project DNS instructions
  */
-export function createAgentProjectDnsRecord(options: {
+type CreateAgentProjectDnsRecordOptions = {
+    /**
+     * Whether the resulting DNS record should be a CNAME instead of an A record.
+     */
     readonly isCnameRecord: boolean;
+
+    /**
+     * Whether the resulting DNS record should cover every generated project domain.
+     */
     readonly isWildcardDomain: boolean;
-    readonly projectDomain: string;
+
+    /**
+     * Assigned project hostname used by the single-project variant, when available.
+     */
+    readonly projectDomain?: string | null;
+
+    /**
+     * Public VPS IP address used by the A-record variant, when known.
+     */
     readonly publicIpAddress: string | null | undefined;
+
+    /**
+     * Base server domain used by generated project hostnames.
+     */
     readonly serverDomain: string;
-}): AgentProjectDnsRecord {
-    const name = options.isWildcardDomain ? `*.${options.serverDomain}` : options.projectDomain;
+};
+
+/**
+ * Creates the one DNS record shown for a selected project-domain setup.
+ *
+ * @param options - Project domain, server domain, and selected DNS variants.
+ * @returns One DNS record instruction.
+ */
+export function createAgentProjectDnsRecord(options: CreateAgentProjectDnsRecordOptions): AgentProjectDnsRecord {
+    const name = createAgentProjectDnsRecordName(options);
 
     if (options.isCnameRecord) {
         return {
@@ -65,3 +98,16 @@ export function createAgentProjectDnsRecord(options: {
             : 'Replace <VPS_PUBLIC_IP> with the public IP address of this VPS.',
     };
 }
+
+/**
+ * Resolves the DNS hostname displayed for one project DNS record instruction.
+ *
+ * @private helper for createAgentProjectDnsRecord
+ */
+function createAgentProjectDnsRecordName(options: CreateAgentProjectDnsRecordOptions): string {
+    if (options.isWildcardDomain) {
+        return `*.${options.serverDomain}`;
+    }
+
+    return options.projectDomain || `${PROJECT_DOMAIN_NAME_PLACEHOLDER}.${options.serverDomain}`;
+}

package/apps/agents-server/src/utils/agentProjects/createAgentProjectInitials.ts

@@ -0,0 +1,36 @@
+import { humanizeAgentProjectName } from './humanizeAgentProjectName';
+
+/**
+ * Maximum count of letters shown in one project initials icon.
+ */
+const AGENT_PROJECT_INITIALS_MAX_LENGTH = 3;
+
+/**
+ * Matches the first letter or digit of one word of a project name.
+ */
+const PROJECT_NAME_WORD_INITIAL_REGEX = /[\p{L}\p{N}]/u;
+
+/**
+ * Initials used for a project whose name has no letters and no digits at all.
+ */
+const AGENT_PROJECT_FALLBACK_INITIALS = '#';
+
+/**
+ * Creates the initials shown for one project which has no favicon.
+ *
+ * For example `prague-murders-map` becomes `PMM`.
+ *
+ * @param projectName - Project directory name.
+ * @returns Up to three uppercase initials of the project name.
+ */
+export function createAgentProjectInitials(projectName: string): string {
+    const projectInitials = humanizeAgentProjectName(projectName)
+        .split(/\s+/u)
+        .map((projectNameWord) => PROJECT_NAME_WORD_INITIAL_REGEX.exec(projectNameWord)?.[0] || '')
+        .filter((projectNameInitial) => projectNameInitial !== '')
+        .slice(0, AGENT_PROJECT_INITIALS_MAX_LENGTH)
+        .join('')
+        .toUpperCase();
+
+    return projectInitials || AGENT_PROJECT_FALLBACK_INITIALS;
+}