@promptbook/cli 0.114.0-2 → 0.114.0-20

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

@@ -0,0 +1,113 @@
+import type { DnsRecordsSection, DnsRecordsSectionVariant } from '../dnsRecords/DnsRecordsSection';
+import { createAgentProjectDnsRecord } from './createAgentProjectDnsRecords';
+
+/**
+ * Inputs of the generated project domain DNS section.
+ *
+ * @private helper for the Agents Server project DNS instructions
+ */
+type CreateAgentProjectsDnsRecordsSectionOptions = {
+    /**
+     * Whether at least one generated project domain currently fails DNS verification.
+     */
+    readonly isDnsIssue?: boolean;
+
+    /**
+     * Example generated project domain used by the single-project variants, when one already exists.
+     */
+    readonly projectDomain?: string | null;
+
+    /**
+     * Public VPS IP address, when known by the server.
+     */
+    readonly publicIpAddress: string | null | undefined;
+
+    /**
+     * Base server domain used by generated project domains.
+     */
+    readonly serverDomain: string;
+};
+
+/**
+ * Creates the DNS section which publishes the generated agent project domains.
+ *
+ * Exactly one of the variants has to be configured, because the wildcard and the single-project records as well as
+ * the A and the CNAME records would collide on the same hostname.
+ *
+ * @param options - Server domain, example project domain, and the public VPS IP address.
+ * @returns Generated project domain section.
+ *
+ * @private shared by the Agents Server DNS instruction views
+ */
+export function createAgentProjectsDnsRecordsSection(
+    options: CreateAgentProjectsDnsRecordsSectionOptions,
+): DnsRecordsSection {
+    return {
+        id: 'agent-projects',
+        title: `Project domains under ${options.serverDomain}`,
+        description: `Project URLs use a subdomain of ${options.serverDomain}. Configure exactly one of the following setups; do not add both the single-project and the wildcard records, or both the A and the CNAME record for the same hostname.`,
+        variantsLabel: 'Project domain setup',
+        variants: [
+            createAgentProjectsDnsRecordsSectionVariant(options, { isWildcardDomain: true, isCnameRecord: true }),
+            createAgentProjectsDnsRecordsSectionVariant(options, { isWildcardDomain: true, isCnameRecord: false }),
+            createAgentProjectsDnsRecordsSectionVariant(options, { isWildcardDomain: false, isCnameRecord: true }),
+            createAgentProjectsDnsRecordsSectionVariant(options, { isWildcardDomain: false, isCnameRecord: false }),
+        ],
+        statusSummary: options.isDnsIssue
+            ? 'One or more generated project domains do not resolve to this VPS yet. The recommended wildcard CNAME setup is selected below.'
+            : null,
+        isDnsIssue: options.isDnsIssue,
+    };
+}
+
+/**
+ * Creates one selectable generated project domain setup.
+ *
+ * @param options - Inputs of the whole section.
+ * @param variant - Selected domain coverage and record type.
+ * @returns One section variant with its single DNS record.
+ *
+ * @private function of `createAgentProjectsDnsRecordsSection`
+ */
+function createAgentProjectsDnsRecordsSectionVariant(
+    options: CreateAgentProjectsDnsRecordsSectionOptions,
+    variant: {
+        /**
+         * Whether the variant covers every generated project domain.
+         */
+        readonly isWildcardDomain: boolean;
+
+        /**
+         * Whether the variant uses a CNAME instead of an A record.
+         */
+        readonly isCnameRecord: boolean;
+    },
+): DnsRecordsSectionVariant {
+    const { isCnameRecord, isWildcardDomain } = variant;
+
+    return {
+        id: `${isWildcardDomain ? 'wildcard' : 'single-project'}-${isCnameRecord ? 'cname' : 'a'}`,
+        label: isWildcardDomain
+            ? isCnameRecord
+                ? 'Wildcard CNAME (all projects, recommended)'
+                : 'Wildcard A record (all projects)'
+            : isCnameRecord
+            ? 'Single project CNAME'
+            : 'Single project A record',
+        description: isWildcardDomain
+            ? `This covers all generated project domains under ${options.serverDomain}.`
+            : options.projectDomain
+            ? `This covers one project, for example ${options.projectDomain}. Repeat it for each project that needs a public URL.`
+            : 'This covers one generated project. Replace the project name placeholder above with its full hostname.',
+        recordSelection: 'one',
+        records: [
+            createAgentProjectDnsRecord({
+                isCnameRecord,
+                isWildcardDomain,
+                projectDomain: options.projectDomain,
+                publicIpAddress: options.publicIpAddress,
+                serverDomain: options.serverDomain,
+            }),
+        ],
+    };
+}

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

@@ -3,15 +3,11 @@ import { readdir, readFile, stat } from 'fs/promises';
 import { basename, isAbsolute, join, relative, resolve } from 'path';
 import { NotAllowed } from '../../../../../src/errors/NotAllowed';
 import { spaceTrim } from '../../../../../src/utils/organization/spaceTrim';
+import { AGENT_PROJECT_INDEX_HTML_FILE_NAMES } from './agentProjectFileNames';
 import { assertSafeAgentProjectPathSegment } from './agentProjectsPaths';
 import { isMissingPathError } from './isMissingPathError';
 import { resolveAgentProjectFileContentType } from './resolveAgentProjectFileContentType';
 
-/**
- * Filenames served automatically when a request targets a project directory.
- */
-const STATIC_DIRECTORY_INDEX_FILENAMES = ['index.html', 'index.htm'] as const;
-
 /**
  * HTML content type used for generated static directory listings.
  */
@@ -170,7 +166,7 @@ async function serveStaticProjectDirectory(options: {
     readonly directoryPath: string;
     readonly response: ServerResponse;
 }): Promise<void> {
-    for (const indexFileName of STATIC_DIRECTORY_INDEX_FILENAMES) {
+    for (const indexFileName of AGENT_PROJECT_INDEX_HTML_FILE_NAMES) {
         const indexFilePath = join(options.directoryPath, indexFileName);
         const indexFileStats = await stat(indexFilePath).catch((error) => {
             if (isMissingPathError(error)) {

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

@@ -0,0 +1,25 @@
+import { capitalize } from '@promptbook-local/utils';
+
+/**
+ * Separators used between the words of one project directory name.
+ */
+const AGENT_PROJECT_NAME_WORD_SEPARATOR_REGEX = /[-_.\s]+/g;
+
+/**
+ * Converts one project directory name into a human-readable project name.
+ *
+ * For example `prague-murders-map` becomes `Prague Murders Map`.
+ *
+ * @param projectName - Project directory name.
+ * @returns Human-readable project name, or the original name when it cannot be humanized.
+ */
+export function humanizeAgentProjectName(projectName: string): string {
+    const humanizedProjectName = projectName
+        .trim()
+        .split(AGENT_PROJECT_NAME_WORD_SEPARATOR_REGEX)
+        .filter((projectNameWord) => projectNameWord !== '')
+        .map((projectNameWord) => capitalize(projectNameWord))
+        .join(' ');
+
+    return humanizedProjectName || projectName;
+}

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

@@ -1,6 +1,7 @@
 import type { AgentProjectReferenceInfo } from './AgentProjectReferenceInfo';
 import { listAgentProjectRuntimes } from './agentProjectRuntimeRegistry';
 import { listAgentProjects } from './listAgentProjects';
+import { resolveAgentProjectPublicUrls } from './resolveAgentProjectPublicUrls';
 
 /**
  * Lists browser-safe project references enriched with their current runtime state for chat.
@@ -11,7 +12,11 @@ import { listAgentProjects } from './listAgentProjects';
 export async function listAgentProjectChatReferences(
     agentPermanentId: string,
 ): Promise<ReadonlyArray<AgentProjectReferenceInfo>> {
-    const [projects, runtimes] = await Promise.all([listAgentProjects(agentPermanentId), listAgentProjectRuntimes()]);
+    const [projects, runtimes, publicUrlByProjectName] = await Promise.all([
+        listAgentProjects(agentPermanentId),
+        listAgentProjectRuntimes(),
+        resolveAgentProjectPublicUrls(agentPermanentId),
+    ]);
     const runtimeByProjectName = new Map(
         runtimes
             .filter((runtime) => runtime.agentPermanentId.toLowerCase() === agentPermanentId.toLowerCase())
@@ -19,15 +24,17 @@ export async function listAgentProjectChatReferences(
     );
 
     return projects.map((project) => {
-        const runtime = runtimeByProjectName.get(project.projectName.toLowerCase());
+        const normalizedProjectName = project.projectName.toLowerCase();
+        const runtime = runtimeByProjectName.get(normalizedProjectName);
 
         return {
             projectName: project.projectName,
             displayName: project.displayName,
             description: project.description,
             sizeBytes: project.sizeBytes,
+            faviconRelativePath: project.faviconRelativePath ?? null,
             isRunning: runtime?.isRunning ?? false,
-            projectUrl: runtime?.publicUrl ?? null,
+            projectUrl: runtime?.publicUrl ?? publicUrlByProjectName.get(normalizedProjectName) ?? null,
         };
     });
 }

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

@@ -0,0 +1,35 @@
+import { readdir } from 'fs/promises';
+import { resolveAgentProjectsRootPath } from './agentProjectsPaths';
+import { isMissingPathError } from './isMissingPathError';
+
+/**
+ * Lists the directory names of all projects of one agent.
+ *
+ * This is the cheap half of `listAgentProjects` — it reads the `projects/` folder itself and never walks
+ * the project trees, so it can answer "did the set of projects change?" without measuring every project.
+ *
+ * A missing projects folder is reported as an empty list — the folder is created lazily
+ * when the agent (or the runner) first needs it.
+ *
+ * @param agentPermanentId - Permanent id of the agent.
+ * @returns Project directory names ordered by name.
+ */
+export async function listAgentProjectNames(agentPermanentId: string): Promise<ReadonlyArray<string>> {
+    const projectsRootPath = resolveAgentProjectsRootPath(agentPermanentId);
+
+    let projectsRootEntries;
+    try {
+        projectsRootEntries = await readdir(projectsRootPath, { withFileTypes: true });
+    } catch (error) {
+        if (isMissingPathError(error)) {
+            return [];
+        }
+
+        throw error;
+    }
+
+    return projectsRootEntries
+        .filter((projectsRootEntry) => projectsRootEntry.isDirectory())
+        .map((projectDirectoryEntry) => projectDirectoryEntry.name)
+        .sort((firstProjectName, secondProjectName) => firstProjectName.localeCompare(secondProjectName));
+}

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

@@ -1,7 +1,6 @@
-import { readdir } from 'fs/promises';
 import type { AgentProjectInfo } from './AgentProjectInfo';
 import { resolveAgentProjectsRootPath } from './agentProjectsPaths';
-import { isMissingPathError } from './isMissingPathError';
+import { listAgentProjectNames } from './listAgentProjectNames';
 import { createAgentProjectInfo } from './resolveAgentProjectInfo';
 
 /**
@@ -15,27 +14,11 @@ import { createAgentProjectInfo } from './resolveAgentProjectInfo';
  */
 export async function listAgentProjects(agentPermanentId: string): Promise<ReadonlyArray<AgentProjectInfo>> {
     const projectsRootPath = resolveAgentProjectsRootPath(agentPermanentId);
+    const projectNames = await listAgentProjectNames(agentPermanentId);
 
-    let projectsRootEntries;
-    try {
-        projectsRootEntries = await readdir(projectsRootPath, { withFileTypes: true });
-    } catch (error) {
-        if (isMissingPathError(error)) {
-            return [];
-        }
-
-        throw error;
-    }
-
-    const projects = await Promise.all(
-        projectsRootEntries
-            .filter((projectsRootEntry) => projectsRootEntry.isDirectory())
-            .map((projectDirectoryEntry): Promise<AgentProjectInfo> =>
-                createAgentProjectInfo(projectsRootPath, projectDirectoryEntry.name),
-            ),
-    );
-
-    return projects.sort((firstProject, secondProject) =>
-        firstProject.projectName.localeCompare(secondProject.projectName),
+    return await Promise.all(
+        projectNames.map(
+            (projectName): Promise<AgentProjectInfo> => createAgentProjectInfo(projectsRootPath, projectName),
+        ),
     );
 }

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

@@ -0,0 +1,48 @@
+import { readdir } from 'fs/promises';
+import { resolveLocalAgentRootPath } from '../localChatRunner/ensureLocalAgentFolder';
+import type { AgentProjectIdentity } from './agentProjectIdentity';
+import { parseAgentPermanentIdFromDirectoryName } from './agentProjectsPaths';
+import { isMissingPathError } from './isMissingPathError';
+import { listAgentProjectNames } from './listAgentProjectNames';
+
+/**
+ * Lists every project folder present on this machine, across all agents of all servers.
+ *
+ * Unlike `listAllAgentProjectSummaries` this never asks a database which agents exist and never
+ * measures a project tree — it only reads the two directory levels needed to name a project. That
+ * makes it usable before the first request is served, when no server database is selected yet.
+ *
+ * @returns Identities of all local agent projects ordered by agent and project name.
+ */
+export async function listAllLocalAgentProjectIdentities(): Promise<ReadonlyArray<AgentProjectIdentity>> {
+    const localAgentRootPath = resolveLocalAgentRootPath();
+    let localAgentRootEntries;
+
+    try {
+        localAgentRootEntries = await readdir(localAgentRootPath, { withFileTypes: true });
+    } catch (error) {
+        if (isMissingPathError(error)) {
+            return [];
+        }
+
+        throw error;
+    }
+
+    const agentPermanentIds = localAgentRootEntries
+        .filter((localAgentRootEntry) => localAgentRootEntry.isDirectory())
+        .map((agentDirectoryEntry) => parseAgentPermanentIdFromDirectoryName(agentDirectoryEntry.name))
+        .filter((agentPermanentId): agentPermanentId is string => agentPermanentId !== null)
+        .sort((firstAgentPermanentId, secondAgentPermanentId) =>
+            firstAgentPermanentId.localeCompare(secondAgentPermanentId),
+        );
+
+    const identitiesPerAgent = await Promise.all(
+        agentPermanentIds.map(async (agentPermanentId): Promise<ReadonlyArray<AgentProjectIdentity>> => {
+            const projectNames = await listAgentProjectNames(agentPermanentId);
+
+            return projectNames.map((projectName) => ({ agentPermanentId, projectName }));
+        }),
+    );
+
+    return identitiesPerAgent.flat();
+}

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

@@ -0,0 +1,167 @@
+/**
+ * `rel` values of one `<link/>` tag recognized as the icon of a page, ordered by priority.
+ *
+ * The values are compared against the `rel` attribute normalized to lowercase single-spaced tokens.
+ */
+const FAVICON_LINK_RELATIONS = [
+    'icon',
+    'shortcut icon',
+    'icon shortcut',
+    'apple-touch-icon',
+    'apple-touch-icon-precomposed',
+    'mask-icon',
+] as const;
+
+/**
+ * Matches the content of the `<title/>` element of one HTML document.
+ */
+const HTML_TITLE_ELEMENT_REGEX = /<title\b[^>]*>([\s\S]*?)<\/title\s*>/i;
+
+/**
+ * Matches every `<link/>` tag of one HTML document.
+ */
+const HTML_LINK_TAG_REGEX = /<link\b[^>]*>/gi;
+
+/**
+ * Matches one named or numeric HTML entity.
+ */
+const HTML_ENTITY_REGEX = /&(#x[0-9a-f]+|#[0-9]+|[a-z]+);/gi;
+
+/**
+ * Replacements of the named HTML entities which can appear in a title or in an icon path.
+ */
+const HTML_ENTITY_REPLACEMENTS: Record<string, string> = {
+    amp: '&',
+    apos: "'",
+    gt: '>',
+    lt: '<',
+    nbsp: ' ',
+    quot: '"',
+};
+
+/**
+ * Highest code point which can be decoded from a numeric HTML entity.
+ */
+const MAXIMUM_UNICODE_CODE_POINT = 0x10ffff;
+
+/**
+ * Presentation of one project resolved from its `index.html`.
+ */
+export type AgentProjectIndexHtmlProfile = {
+    /**
+     * Content of the `<title/>` element, or `null` when the document has no usable title.
+     */
+    readonly title: string | null;
+
+    /**
+     * Icon `href` exactly as written in the document, or `null` when no icon is linked.
+     */
+    readonly faviconHref: string | null;
+};
+
+/**
+ * Parses the presentation of one project out of its `index.html`.
+ *
+ * Only the title and the linked icon are read, so the document is scanned with plain regular
+ * expressions instead of pulling a full HTML parser into the Agents Server.
+ *
+ * @param indexHtmlContent - Content of the project `index.html`.
+ * @returns Title and icon href found in the document.
+ */
+export function parseAgentProjectIndexHtml(indexHtmlContent: string): AgentProjectIndexHtmlProfile {
+    return {
+        title: parseIndexHtmlTitle(indexHtmlContent),
+        faviconHref: parseIndexHtmlFaviconHref(indexHtmlContent),
+    };
+}
+
+/**
+ * Parses the `<title/>` of one HTML document.
+ *
+ * @param indexHtmlContent - Content of the project `index.html`.
+ * @returns Single-line title, or `null` when the document has no non-empty title.
+ */
+function parseIndexHtmlTitle(indexHtmlContent: string): string | null {
+    const titleMatch = HTML_TITLE_ELEMENT_REGEX.exec(indexHtmlContent);
+    if (!titleMatch || titleMatch[1] === undefined) {
+        return null;
+    }
+
+    const title = decodeHtmlEntities(titleMatch[1]).replace(/\s+/gu, ' ').trim();
+    return title || null;
+}
+
+/**
+ * Parses the icon `href` linked by one HTML document.
+ *
+ * @param indexHtmlContent - Content of the project `index.html`.
+ * @returns Icon href of the best matching `<link/>` tag, or `null` when no icon is linked.
+ */
+function parseIndexHtmlFaviconHref(indexHtmlContent: string): string | null {
+    let bestFaviconHref: string | null = null;
+    let bestFaviconRelationIndex: number = FAVICON_LINK_RELATIONS.length;
+
+    for (const linkTag of indexHtmlContent.match(HTML_LINK_TAG_REGEX) || []) {
+        const linkRelation = parseHtmlTagAttribute(linkTag, 'rel');
+        const linkHref = parseHtmlTagAttribute(linkTag, 'href');
+        if (linkRelation === null || !linkHref) {
+            continue;
+        }
+
+        const relationIndex = FAVICON_LINK_RELATIONS.indexOf(
+            linkRelation.toLowerCase().replace(/\s+/gu, ' ').trim() as (typeof FAVICON_LINK_RELATIONS)[number],
+        );
+        if (relationIndex === -1 || relationIndex >= bestFaviconRelationIndex) {
+            continue;
+        }
+
+        bestFaviconHref = linkHref;
+        bestFaviconRelationIndex = relationIndex;
+    }
+
+    return bestFaviconHref;
+}
+
+/**
+ * Parses one attribute out of a single HTML tag.
+ *
+ * @param htmlTag - One complete HTML tag including its angle brackets.
+ * @param attributeName - Lowercase attribute name.
+ * @returns Decoded attribute value, or `null` when the tag does not have the attribute.
+ */
+function parseHtmlTagAttribute(htmlTag: string, attributeName: string): string | null {
+    const attributeMatch = new RegExp(`\\b${attributeName}\\s*=\\s*("[^"]*"|'[^']*'|[^\\s"'>]+)`, 'i').exec(htmlTag);
+    if (!attributeMatch || attributeMatch[1] === undefined) {
+        return null;
+    }
+
+    const rawAttributeValue = attributeMatch[1];
+    const isQuotedAttributeValue =
+        (rawAttributeValue.startsWith('"') && rawAttributeValue.endsWith('"')) ||
+        (rawAttributeValue.startsWith("'") && rawAttributeValue.endsWith("'"));
+
+    return decodeHtmlEntities(isQuotedAttributeValue ? rawAttributeValue.slice(1, -1) : rawAttributeValue).trim();
+}
+
+/**
+ * Decodes the HTML entities which can appear in a title or in an icon path.
+ *
+ * @param htmlText - Raw text taken from an HTML document.
+ * @returns Plain text.
+ */
+function decodeHtmlEntities(htmlText: string): string {
+    return htmlText.replace(HTML_ENTITY_REGEX, (entity, entityName: string) => {
+        if (entityName.startsWith('#')) {
+            const characterCode = entityName.startsWith('#x')
+                ? Number.parseInt(entityName.slice(2), 16)
+                : Number.parseInt(entityName.slice(1), 10);
+
+            const isDecodableCharacterCode =
+                Number.isInteger(characterCode) && characterCode >= 0 && characterCode <= MAXIMUM_UNICODE_CODE_POINT;
+
+            return isDecodableCharacterCode ? String.fromCodePoint(characterCode) : entity;
+        }
+
+        return HTML_ENTITY_REPLACEMENTS[entityName.toLowerCase()] ?? entity;
+    });
+}

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

@@ -0,0 +1,24 @@
+import { AGENT_PROJECT_INDEX_HTML_FILE_NAMES } from './agentProjectFileNames';
+import { parseAgentProjectIndexHtml, type AgentProjectIndexHtmlProfile } from './parseAgentProjectIndexHtml';
+import { readAgentProjectRootTextFile } from './readAgentProjectRootTextFile';
+
+/**
+ * Reads the presentation of one project from the `index.html` in its root.
+ *
+ * Only the root `index.html` is read, because it is the document the project serves on its own
+ * public URL — a nested one belongs to a build output or to a subpage of the project.
+ *
+ * @param projectPath - Absolute path of the project directory.
+ * @returns Title and icon href of the project, or `null` when the project has no `index.html`.
+ */
+export async function readAgentProjectIndexHtmlProfile(
+    projectPath: string,
+): Promise<AgentProjectIndexHtmlProfile | null> {
+    const indexHtml = await readAgentProjectRootTextFile(projectPath, AGENT_PROJECT_INDEX_HTML_FILE_NAMES);
+
+    if (indexHtml === null) {
+        return null;
+    }
+
+    return parseAgentProjectIndexHtml(indexHtml.content);
+}

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

@@ -1,6 +1,4 @@
-import { readdir, readFile } from 'fs/promises';
-import { join } from 'path';
-import { isMissingPathError } from './isMissingPathError';
+import { readAgentProjectRootTextFile, type AgentProjectRootTextFile } from './readAgentProjectRootTextFile';
 
 /**
  * README filenames recognized inside project roots, ordered by display priority.
@@ -10,17 +8,7 @@ const AGENT_PROJECT_README_FILE_NAMES = ['readme.md', 'readme.markdown', 'readme
 /**
  * README file loaded from one agent project.
  */
-export type AgentProjectReadme = {
-    /**
-     * Original filename used on disk.
-     */
-    readonly fileName: string;
-
-    /**
-     * README content decoded as UTF-8 text.
-     */
-    readonly content: string;
-};
+export type AgentProjectReadme = AgentProjectRootTextFile;
 
 /**
  * Reads the first recognized README file from a project directory.
@@ -29,43 +17,5 @@ export type AgentProjectReadme = {
  * @returns README content, or `null` when the project has no recognized README file.
  */
 export async function readAgentProjectReadme(projectPath: string): Promise<AgentProjectReadme | null> {
-    let projectRootEntries;
-
-    try {
-        projectRootEntries = await readdir(projectPath, { withFileTypes: true });
-    } catch (error) {
-        if (isMissingPathError(error)) {
-            return null;
-        }
-
-        throw error;
-    }
-
-    const projectFileNameByNormalizedName = new Map(
-        projectRootEntries
-            .filter((projectRootEntry) => projectRootEntry.isFile())
-            .map((projectRootEntry) => [projectRootEntry.name.toLowerCase(), projectRootEntry.name]),
-    );
-
-    for (const readmeFileName of AGENT_PROJECT_README_FILE_NAMES) {
-        const projectReadmeFileName = projectFileNameByNormalizedName.get(readmeFileName);
-        if (!projectReadmeFileName) {
-            continue;
-        }
-
-        try {
-            return {
-                fileName: projectReadmeFileName,
-                content: await readFile(join(projectPath, projectReadmeFileName), 'utf-8'),
-            };
-        } catch (error) {
-            if (isMissingPathError(error)) {
-                return null;
-            }
-
-            throw error;
-        }
-    }
-
-    return null;
+    return readAgentProjectRootTextFile(projectPath, AGENT_PROJECT_README_FILE_NAMES);
 }

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

@@ -0,0 +1,73 @@
+import { readdir, readFile } from 'fs/promises';
+import { join } from 'path';
+import { isMissingPathError } from './isMissingPathError';
+
+/**
+ * Text file loaded from the root of one agent project.
+ */
+export type AgentProjectRootTextFile = {
+    /**
+     * Original filename used on disk.
+     */
+    readonly fileName: string;
+
+    /**
+     * File content decoded as UTF-8 text.
+     */
+    readonly content: string;
+};
+
+/**
+ * Reads the first recognized text file from the root of one project directory.
+ *
+ * Project files are written by the agent, so their filename casing cannot be relied on — the
+ * recognized filenames are matched case-insensitively and the real filename on disk is preserved.
+ *
+ * @param projectPath - Absolute path of the project directory.
+ * @param recognizedFileNames - Lowercase filenames ordered by priority.
+ * @returns Content of the first matching file, or `null` when the project has none of them.
+ */
+export async function readAgentProjectRootTextFile(
+    projectPath: string,
+    recognizedFileNames: ReadonlyArray<string>,
+): Promise<AgentProjectRootTextFile | null> {
+    let projectRootEntries;
+
+    try {
+        projectRootEntries = await readdir(projectPath, { withFileTypes: true });
+    } catch (error) {
+        if (isMissingPathError(error)) {
+            return null;
+        }
+
+        throw error;
+    }
+
+    const projectFileNameByNormalizedName = new Map(
+        projectRootEntries
+            .filter((projectRootEntry) => projectRootEntry.isFile())
+            .map((projectRootEntry) => [projectRootEntry.name.toLowerCase(), projectRootEntry.name]),
+    );
+
+    for (const recognizedFileName of recognizedFileNames) {
+        const projectFileName = projectFileNameByNormalizedName.get(recognizedFileName.toLowerCase());
+        if (!projectFileName) {
+            continue;
+        }
+
+        try {
+            return {
+                fileName: projectFileName,
+                content: await readFile(join(projectPath, projectFileName), 'utf-8'),
+            };
+        } catch (error) {
+            if (isMissingPathError(error)) {
+                return null;
+            }
+
+            throw error;
+        }
+    }
+
+    return null;
+}