@promptbook/cli 0.113.0-9 → 0.114.0-0

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

@@ -0,0 +1,94 @@
+import { stat } from 'fs/promises';
+import { join } from 'path';
+import { AGENT_PROJECTS_DIRECTORY_PATH } from '../../../../../src/book-3.0/agentFolderPaths';
+import type { AgentProjectInfo } from './AgentProjectInfo';
+import { resolveAgentProjectsRootPath, resolveSafeAgentProjectPath } from './agentProjectsPaths';
+import { isMissingPathError } from './isMissingPathError';
+import { measureDirectoryUsage } from './measureDirectoryUsage';
+import { readAgentProjectReadme } from './readAgentProjectReadme';
+import { resolveAgentProjectReadmeProfile } from './resolveAgentProjectReadmeProfile';
+
+/**
+ * Builds metadata for one project directory.
+ *
+ * @param projectsRootPath - Absolute path of the owning agent's `projects/` folder.
+ * @param projectDirectoryName - Direct child directory name inside `projects/`.
+ * @returns Project metadata.
+ */
+export async function createAgentProjectInfo(
+    projectsRootPath: string,
+    projectDirectoryName: string,
+): Promise<AgentProjectInfo> {
+    const projectPath = join(projectsRootPath, projectDirectoryName);
+    const [projectUsage, isGitRepository, readme] = await Promise.all([
+        measureDirectoryUsage(projectPath),
+        isGitRepositoryDirectory(projectPath),
+        readAgentProjectReadme(projectPath),
+    ]);
+    const profile = resolveAgentProjectReadmeProfile({
+        projectDirectoryName,
+        readme,
+    });
+
+    return {
+        projectName: projectDirectoryName,
+        displayName: profile.displayName,
+        description: profile.description,
+        readmeFileName: profile.readmeFileName,
+        relativePath: `${AGENT_PROJECTS_DIRECTORY_PATH}/${projectDirectoryName}`,
+        absolutePath: projectPath,
+        sizeBytes: projectUsage.sizeBytes,
+        fileCount: projectUsage.fileCount,
+        isGitRepository,
+        latestModifiedAt:
+            projectUsage.latestModifiedAtMs === null ? null : new Date(projectUsage.latestModifiedAtMs).toISOString(),
+    };
+}
+
+/**
+ * Resolves metadata for one project of one agent.
+ *
+ * @param agentPermanentId - Permanent id of the owning agent.
+ * @param projectName - Project directory name.
+ * @returns Project metadata or `null` when the project does not exist.
+ */
+export async function resolveAgentProjectInfo(
+    agentPermanentId: string,
+    projectName: string,
+): Promise<AgentProjectInfo | null> {
+    const projectPath = resolveSafeAgentProjectPath({ agentPermanentId, projectName });
+
+    try {
+        const projectStats = await stat(projectPath);
+        if (!projectStats.isDirectory()) {
+            return null;
+        }
+    } catch (error) {
+        if (isMissingPathError(error)) {
+            return null;
+        }
+
+        throw error;
+    }
+
+    return createAgentProjectInfo(resolveAgentProjectsRootPath(agentPermanentId), projectName);
+}
+
+/**
+ * Returns true when the directory contains a `.git` directory and therefore is a git repository.
+ *
+ * @param directoryPath - Project directory path.
+ * @returns `true` when the project is a git repository.
+ */
+async function isGitRepositoryDirectory(directoryPath: string): Promise<boolean> {
+    try {
+        const gitStats = await stat(join(directoryPath, '.git'));
+        return gitStats.isDirectory();
+    } catch (error) {
+        if (isMissingPathError(error)) {
+            return false;
+        }
+
+        throw error;
+    }
+}

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

@@ -0,0 +1,219 @@
+import { parseMarkdownSection, splitMarkdownIntoSections } from '@promptbook-local/markdown-utils';
+import type { string_markdown } from '@promptbook-local/types';
+import { stripMarkdownText } from '../stripMarkdownText';
+import type { AgentProjectReadme } from './readAgentProjectReadme';
+
+/**
+ * Maximum project description length shown in project references.
+ */
+const PROJECT_DESCRIPTION_MAX_CHARACTERS = 200;
+
+/**
+ * Markdown fence prefixes that start non-paragraph blocks.
+ */
+const MARKDOWN_CODE_FENCE_PREFIXES = ['```', '~~~'] as const;
+
+/**
+ * Parsed README sections used to resolve project display metadata.
+ */
+type AgentProjectReadmeSections = {
+    /**
+     * First section of the README, including a synthetic title when the README starts with text.
+     */
+    readonly firstSection: ReturnType<typeof parseMarkdownSection> | null;
+
+    /**
+     * First section that comes from an explicit README heading.
+     */
+    readonly firstExplicitHeadingSection: ReturnType<typeof parseMarkdownSection> | null;
+};
+
+/**
+ * Project profile values resolved from a project folder and optional README.
+ */
+export type AgentProjectReadmeProfile = {
+    /**
+     * User-facing project name.
+     */
+    readonly displayName: string;
+
+    /**
+     * Short plain-text project description.
+     */
+    readonly description: string;
+
+    /**
+     * README filename used to resolve the profile, or `null` when missing.
+     */
+    readonly readmeFileName: string | null;
+};
+
+/**
+ * Resolves display metadata for one agent project from its README.
+ *
+ * @param options - Project folder name and optional README content.
+ * @returns Project display profile.
+ */
+export function resolveAgentProjectReadmeProfile(options: {
+    readonly projectDirectoryName: string;
+    readonly readme: AgentProjectReadme | null;
+}): AgentProjectReadmeProfile {
+    const { projectDirectoryName, readme } = options;
+    if (!readme) {
+        return {
+            displayName: projectDirectoryName,
+            description: '',
+            readmeFileName: null,
+        };
+    }
+
+    const sections = parseMarkdownProfileSections(readme.content);
+    const displayName = resolveProjectDisplayName(
+        projectDirectoryName,
+        sections.firstExplicitHeadingSection?.title ?? null,
+    );
+    const description = resolveProjectDescription(readme.content, sections.firstSection?.content ?? readme.content);
+
+    return {
+        displayName,
+        description,
+        readmeFileName: readme.fileName,
+    };
+}
+
+/**
+ * Parses README markdown sections through the shared markdown parser.
+ *
+ * @param markdown - README markdown content.
+ * @returns Parsed sections needed for display metadata.
+ */
+function parseMarkdownProfileSections(markdown: string): AgentProjectReadmeSections {
+    const sections = splitMarkdownIntoSections(markdown as string_markdown);
+    const firstSection = sections[0];
+
+    if (!firstSection) {
+        return {
+            firstSection: null,
+            firstExplicitHeadingSection: null,
+        };
+    }
+
+    const parsedFirstSection = parseMarkdownSection(firstSection);
+    const firstExplicitHeadingSection = doesMarkdownStartWithHeading(markdown)
+        ? parsedFirstSection
+        : sections[1]
+          ? parseMarkdownSection(sections[1])
+          : null;
+
+    return {
+        firstSection: parsedFirstSection,
+        firstExplicitHeadingSection,
+    };
+}
+
+/**
+ * Resolves a project display name from the README heading or folder fallback.
+ *
+ * @param projectDirectoryName - Project folder name.
+ * @param parsedHeadingTitle - Title returned by the markdown section parser.
+ * @returns Display name.
+ */
+function resolveProjectDisplayName(projectDirectoryName: string, parsedHeadingTitle: string | null): string {
+    if (!parsedHeadingTitle) {
+        return projectDirectoryName;
+    }
+
+    const displayName = stripMarkdownText(parsedHeadingTitle);
+    return displayName || projectDirectoryName;
+}
+
+/**
+ * Resolves a short project description from the first README paragraph.
+ *
+ * @param readmeContent - Full README content.
+ * @param parsedSectionContent - Content of the first parsed markdown section.
+ * @returns Plain-text description, truncated when needed.
+ */
+function resolveProjectDescription(readmeContent: string, parsedSectionContent: string): string {
+    const contentForDescription = doesMarkdownStartWithHeading(readmeContent) ? parsedSectionContent : readmeContent;
+    const firstParagraph = resolveFirstMarkdownParagraph(contentForDescription);
+
+    if (!firstParagraph) {
+        return '';
+    }
+
+    const description = stripMarkdownText(firstParagraph, {
+        doubleNewlineReplacement: ' ',
+        newlineReplacement: ' ',
+    });
+
+    return truncateProjectDescription(description);
+}
+
+/**
+ * Returns whether markdown starts with an explicit heading.
+ *
+ * @param markdown - Markdown content to inspect.
+ * @returns `true` when the first non-empty line is a heading.
+ */
+function doesMarkdownStartWithHeading(markdown: string): boolean {
+    const firstNonEmptyLine = markdown
+        .replace(/\r\n/g, '\n')
+        .split('\n')
+        .find((line) => line.trim().length > 0);
+
+    return Boolean(firstNonEmptyLine?.trimStart().startsWith('#'));
+}
+
+/**
+ * Finds the first paragraph-like markdown block.
+ *
+ * @param markdown - Markdown content to inspect.
+ * @returns First paragraph block or an empty string.
+ */
+function resolveFirstMarkdownParagraph(markdown: string): string {
+    return (
+        markdown
+            .replace(/\r\n/g, '\n')
+            .split(/\n\s*\n/g)
+            .map((block) => block.trim())
+            .find(isMarkdownParagraphBlock) || ''
+    );
+}
+
+/**
+ * Returns whether one markdown block can be treated as a paragraph preview.
+ *
+ * @param block - Markdown block candidate.
+ * @returns `true` for paragraph-like blocks.
+ */
+function isMarkdownParagraphBlock(block: string): boolean {
+    if (!block) {
+        return false;
+    }
+
+    const firstLine = block.split(/\r?\n/, 1)[0]?.trimStart() || '';
+    if (!firstLine || firstLine.startsWith('#')) {
+        return false;
+    }
+
+    if (MARKDOWN_CODE_FENCE_PREFIXES.some((fencePrefix) => firstLine.startsWith(fencePrefix))) {
+        return false;
+    }
+
+    return !/^([-*_]){3,}$/.test(firstLine.trim());
+}
+
+/**
+ * Truncates project descriptions to the shared display limit.
+ *
+ * @param description - Plain-text project description.
+ * @returns Original or truncated description.
+ */
+function truncateProjectDescription(description: string): string {
+    if (description.length <= PROJECT_DESCRIPTION_MAX_CHARACTERS) {
+        return description;
+    }
+
+    return `${description.slice(0, PROJECT_DESCRIPTION_MAX_CHARACTERS).trimEnd()}...`;
+}

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

@@ -0,0 +1,12 @@
+import { resolveCurrentServerRegistryContext } from '../currentServerRegistryContext';
+
+/**
+ * Resolves the current public server domain used to scope agent project domain assignments.
+ *
+ * @returns Current server domain, host server domain, or `null` when no server context is available.
+ */
+export async function resolveCurrentAgentProjectServerDomain(): Promise<string | null> {
+    const context = await resolveCurrentServerRegistryContext();
+
+    return context.currentServer?.domain || context.hostServer?.domain || null;
+}

package/apps/agents-server/src/utils/agentRouting/agentRouteHrefs.ts

@@ -58,6 +58,20 @@ export function buildAgentChatHref(agentIdentifier: string): string {
     return `${buildAgentProfileHref(agentIdentifier)}/chat`;
 }
 
+/**
+ * Builds the canonical chat href that reopens one existing conversation with a local agent.
+ *
+ * @param agentIdentifier - Canonical permanent id.
+ * @param chatId - Id of the existing conversation to reopen.
+ * @returns Canonical chat href pointing at the existing conversation.
+ */
+export function buildExistingAgentChatHref(agentIdentifier: string, chatId: string): string {
+    const chatHref = buildAgentChatHref(agentIdentifier);
+    const parsedHref = new URL(chatHref, RELATIVE_HREF_BASE_URL);
+    parsedHref.searchParams.set(AGENT_CHAT_QUERY_PARAM, chatId);
+    return formatParsedHref(chatHref, parsedHref);
+}
+
 /**
  * Forces one chat href to start a fresh conversation.
  *

package/apps/agents-server/src/utils/agentRouting/resolveAgentRouteTarget.ts

@@ -4,6 +4,7 @@ import { $provideAgentReferenceResolver } from '../agentReferenceResolver/$provi
 import { consumeAgentReferenceResolutionIssues } from '../agentReferenceResolver/AgentReferenceResolutionIssue';
 import { parseBookScopedAgentIdentifier } from '../agentReferenceResolver/bookScopedAgentReferences';
 import { resolvePseudoAgentDescriptor } from '../pseudoAgents';
+import { isSameAgentPermanentId } from '../agentIdentifier';
 import { normalizeAgentName } from '../../../../../src/_packages/core.index';
 import type { PseudoAgentKind } from '../../../../../src/book-2.0/agent-source/pseudoAgentReferences';
 import { cache } from 'react';
@@ -345,7 +346,7 @@ async function findLocalAgentRouteMatch(
 
     return (
         agents.find((agent: { agentName: string; permanentId?: string | null }) => {
-            if (agent.agentName === reference || agent.permanentId === reference) {
+            if (agent.agentName === reference || isSameAgentPermanentId(agent.permanentId, reference)) {
                 return true;
             }
 

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

@@ -0,0 +1,170 @@
+import type { PagePreviewInputEvent } from '../../../../src/book-components/Chat/Chat/pagePreview/PagePreviewInputEvent';
+import type { PagePreviewViewport } from '../../../../src/book-components/Chat/Chat/pagePreview/PagePreviewViewport';
+import { assertSafeUrl } from './assertSafeUrl';
+import type { PagePreviewBrowserSession } from './pagePreviewBrowserSessions';
+import { updatePagePreviewBrowserSessionViewport } from './pagePreviewBrowserSessions';
+import { appendTaskTerminalLogLine } from './taskTerminal/taskTerminalLog';
+
+/**
+ * Navigation timeout for toolbar-initiated page-preview navigations.
+ *
+ * @private internal constant of Agents Server page-preview input handling
+ */
+const PAGE_PREVIEW_INPUT_NAVIGATION_TIMEOUT_MS = 30_000;
+
+/**
+ * Applies one normalized remote-control event to the live page of a browser preview session.
+ *
+ * Pointer ratios are converted into viewport coordinates, keyboard events are replayed through
+ * the Playwright keyboard (falling back to text insertion for keys outside the US layout, for
+ * example accented characters), and navigations run in the background so the input queue is not
+ * blocked while the page loads.
+ *
+ * @param session - Active browser preview session with an attached page and viewport.
+ * @param inputEvent - Normalized input event.
+ *
+ * @private internal utility of Agents Server page-preview input handling
+ */
+export async function applyPagePreviewBrowserInput(
+    session: PagePreviewBrowserSession,
+    inputEvent: PagePreviewInputEvent,
+): Promise<void> {
+    const page = session.page;
+    const viewport = session.viewport;
+    if (!page || !viewport) {
+        return;
+    }
+
+    switch (inputEvent.type) {
+        case 'move': {
+            const { x, y } = resolvePointerPosition(inputEvent, viewport);
+            await page.mouse.move(x, y);
+            return;
+        }
+
+        case 'down': {
+            const { x, y } = resolvePointerPosition(inputEvent, viewport);
+            await page.mouse.move(x, y);
+            await page.mouse.down({ button: inputEvent.button, clickCount: inputEvent.clickCount });
+            return;
+        }
+
+        case 'up': {
+            const { x, y } = resolvePointerPosition(inputEvent, viewport);
+            await page.mouse.move(x, y);
+            await page.mouse.up({ button: inputEvent.button, clickCount: inputEvent.clickCount });
+            return;
+        }
+
+        case 'click': {
+            const { x, y } = resolvePointerPosition(inputEvent, viewport);
+            await page.mouse.click(x, y);
+            return;
+        }
+
+        case 'wheel': {
+            const { x, y } = resolvePointerPosition(inputEvent, viewport);
+            await page.mouse.move(x, y);
+            await page.mouse.wheel(inputEvent.deltaX, inputEvent.deltaY);
+            return;
+        }
+
+        case 'keydown': {
+            try {
+                await page.keyboard.down(inputEvent.key);
+            } catch {
+                if (Array.from(inputEvent.key).length === 1) {
+                    await page.keyboard.insertText(inputEvent.key).catch(() => undefined);
+                }
+            }
+            return;
+        }
+
+        case 'keyup': {
+            await page.keyboard.up(inputEvent.key).catch(() => undefined);
+            return;
+        }
+
+        case 'resize': {
+            const requestedViewport: PagePreviewViewport = { width: inputEvent.width, height: inputEvent.height };
+            if (session.applyViewport) {
+                await session.applyViewport(requestedViewport);
+            } else {
+                await page.setViewportSize(requestedViewport);
+                updatePagePreviewBrowserSessionViewport(session.id, requestedViewport);
+            }
+            return;
+        }
+
+        case 'navigate': {
+            const navigationPromise =
+                inputEvent.action === 'back'
+                    ? page.goBack({ timeout: PAGE_PREVIEW_INPUT_NAVIGATION_TIMEOUT_MS })
+                    : inputEvent.action === 'forward'
+                    ? page.goForward({ timeout: PAGE_PREVIEW_INPUT_NAVIGATION_TIMEOUT_MS })
+                    : page.reload({ timeout: PAGE_PREVIEW_INPUT_NAVIGATION_TIMEOUT_MS });
+
+            watchBackgroundNavigation(session, inputEvent.action, navigationPromise);
+            return;
+        }
+
+        case 'goto': {
+            assertSafeUrl(inputEvent.url);
+            watchBackgroundNavigation(
+                session,
+                `goto ${inputEvent.url}`,
+                page.goto(inputEvent.url, {
+                    waitUntil: 'domcontentloaded',
+                    timeout: PAGE_PREVIEW_INPUT_NAVIGATION_TIMEOUT_MS,
+                }),
+            );
+            return;
+        }
+
+        default: {
+            const unreachableEvent: never = inputEvent;
+            void unreachableEvent;
+        }
+    }
+}
+
+/**
+ * Converts pointer ratios into coordinates inside the streamed viewport.
+ *
+ * @param pointer - Event carrying pointer ratios.
+ * @param viewport - Viewport of the streamed page.
+ * @returns Pointer position in viewport pixels.
+ */
+function resolvePointerPosition(
+    pointer: { readonly xRatio: number; readonly yRatio: number },
+    viewport: PagePreviewViewport,
+): { readonly x: number; readonly y: number } {
+    return {
+        x: Math.min(viewport.width - 1, pointer.xRatio * viewport.width),
+        y: Math.min(viewport.height - 1, pointer.yRatio * viewport.height),
+    };
+}
+
+/**
+ * Lets one toolbar navigation finish in the background, logging failures into the session log.
+ *
+ * The input response must not wait for the page load — progress is visible in the live stream.
+ *
+ * @param session - Session owning the navigation.
+ * @param actionDescription - Human-readable description used in the failure log line.
+ * @param navigationPromise - Running navigation.
+ */
+function watchBackgroundNavigation(
+    session: PagePreviewBrowserSession,
+    actionDescription: string,
+    navigationPromise: Promise<unknown>,
+): void {
+    void navigationPromise.catch((error) => {
+        appendTaskTerminalLogLine(
+            session.id,
+            `Browser preview navigation (${actionDescription}) failed: ${
+                error instanceof Error ? error.message : String(error)
+            }`,
+        );
+    });
+}

package/apps/agents-server/src/utils/bookLanguageDocumentation/BookLanguageDocumentationAgent.ts

@@ -0,0 +1,25 @@
+import type { string_book } from '../../../../../src/book-2.0/agent-source/string_book';
+
+/**
+ * One agent available for inclusion in a Book language manual export.
+ */
+export type BookLanguageDocumentationAgentOption = {
+    /**
+     * Stable server identifier used by the export request.
+     */
+    readonly id: string;
+    /**
+     * Human-readable agent name shown in the export menu.
+     */
+    readonly name: string;
+};
+
+/**
+ * Agent option with its current Book source, ready to be baked into a manual.
+ */
+export type BakedBookLanguageDocumentationAgent = BookLanguageDocumentationAgentOption & {
+    /**
+     * Current persisted Book source.
+     */
+    readonly source: string_book;
+};

package/apps/agents-server/src/utils/bookLanguageDocumentation/bookLanguageDocumentationExportParameters.ts

@@ -0,0 +1,9 @@
+/**
+ * URL parameter opting into the low-level commitments chapter of the manual.
+ *
+ * The chapter targets advanced authors only, therefore it is opt-in.
+ *
+ * This module intentionally holds no server-only imports, so both the export
+ * routes and the client-side docs toolbar can share one parameter name.
+ */
+export const BOOK_LANGUAGE_DOCUMENTATION_LOW_LEVEL_COMMITMENTS_PARAMETER = 'lowLevelCommitments';

package/apps/agents-server/src/utils/bookLanguageDocumentation/createBookLanguageDocumentationMarkdownResponse.ts

@@ -1,5 +1,9 @@
-import { NextResponse } from 'next/server';
 import { createStandaloneBookLanguageMarkdown } from '../../../../../src/book-2.0/book-language-documentation/createStandaloneBookLanguageMarkdown';
+import type { string_markdown } from '../../../../../src/types/string_markdown';
+import { NextResponse } from 'next/server';
+import { resolveServerLanguageCode, type ServerLanguageCode } from '../../languages/ServerLanguageRegistry';
+import { BOOK_LANGUAGE_DOCUMENTATION_LOW_LEVEL_COMMITMENTS_PARAMETER } from './bookLanguageDocumentationExportParameters';
+import { getBakedBookLanguageDocumentationAgents } from './getBookLanguageDocumentationAgents';
 
 /**
  * Response headers for standalone Book language markdown docs.
@@ -13,14 +17,91 @@ export const BOOK_LANGUAGE_DOCUMENTATION_MARKDOWN_HEADERS = Object.freeze({
 });
 
 /**
- * Creates markdown response for standalone Book language documentation.
+ * Selection and language options shared by Markdown and PDF manual exports.
+ */
+export type BookLanguageDocumentationExportOptions = {
+    /**
+     * `null` includes all current server agents; an empty array includes none.
+     */
+    readonly selectedAgentIds: ReadonlyArray<string> | null;
+    /**
+     * Requested export language, used for the generated manual and response metadata.
+     */
+    readonly language: ServerLanguageCode;
+    /**
+     * Whether the closing chapter with low-level commitments should be exported.
+     */
+    readonly isLowLevelCommitmentsIncluded: boolean;
+};
+
+/**
+ * Parses Book language manual export choices from a request URL.
+ *
+ * The absence of agent parameters means "all agents", matching the primary
+ * export action. `agents=none` intentionally produces the portable manual
+ * with no server-specific examples or prioritization.
+ *
+ * @param searchParams - URL parameters supplied to either export format.
+ * @param defaultLanguage - Current request language used when none is selected explicitly.
+ * @returns Validated manual export options.
+ */
+export function parseBookLanguageDocumentationExportOptions(
+    searchParams: URLSearchParams,
+    defaultLanguage: ServerLanguageCode,
+): BookLanguageDocumentationExportOptions {
+    const isNoAgentsSelected = searchParams.get('agents') === 'none';
+    const selectedAgentIds = isNoAgentsSelected
+        ? []
+        : Array.from(new Set(searchParams.getAll('agent').filter((agentId) => agentId.trim().length > 0)));
+
+    return {
+        selectedAgentIds: isNoAgentsSelected || selectedAgentIds.length > 0 ? selectedAgentIds : null,
+        language: resolveServerLanguageCode(searchParams.get('language') || defaultLanguage),
+        isLowLevelCommitmentsIncluded:
+            searchParams.get(BOOK_LANGUAGE_DOCUMENTATION_LOW_LEVEL_COMMITMENTS_PARAMETER) === 'true',
+    };
+}
+
+/**
+ * Creates one manual body from the selected current server agents.
+ *
+ * @param options - Agent selection and target language shared by all export formats.
+ * @returns Generated Markdown plus language metadata used by HTTP and PDF responses.
+ */
+export async function createBookLanguageDocumentationExport(options: BookLanguageDocumentationExportOptions): Promise<{
+    readonly language: ServerLanguageCode;
+    readonly markdown: string_markdown;
+}> {
+    const bakedAgents = await getBakedBookLanguageDocumentationAgents(options.selectedAgentIds);
+
+    return {
+        language: options.language,
+        markdown: createStandaloneBookLanguageMarkdown({
+            agents: bakedAgents.map((agent) => ({
+                agentName: agent.name,
+                agentSource: agent.source,
+            })),
+            language: options.language,
+            isLowLevelCommitmentsIncluded: options.isLowLevelCommitmentsIncluded,
+        }),
+    };
+}
+
+/**
+ * Creates a Markdown response for standalone Book language documentation.
  *
- * @returns HTTP response with generated markdown and canonical headers.
+ * @param options - Agent selection and language shared by all manual exports.
+ * @returns HTTP response with generated Markdown and canonical headers.
  */
-export function createBookLanguageDocumentationMarkdownResponse(): NextResponse<string> {
-    const markdown = createStandaloneBookLanguageMarkdown();
+export async function createBookLanguageDocumentationMarkdownResponse(
+    options: BookLanguageDocumentationExportOptions,
+): Promise<NextResponse<string>> {
+    const exportContent = await createBookLanguageDocumentationExport(options);
 
-    return new NextResponse(markdown, {
-        headers: BOOK_LANGUAGE_DOCUMENTATION_MARKDOWN_HEADERS,
+    return new NextResponse(exportContent.markdown, {
+        headers: {
+            ...BOOK_LANGUAGE_DOCUMENTATION_MARKDOWN_HEADERS,
+            'Content-Language': exportContent.language,
+        },
     });
 }