@promptbook/cli 0.114.0-1 → 0.114.0-3

package/src/book-2.0/book-language-documentation/renderGroupedCommitmentDocumentationMarkdown.ts

@@ -1,7 +1,12 @@
 import { spaceTrim } from 'spacetrim';
+import { parseAgentSourceWithCommitments } from '../agent-source/parseAgentSourceWithCommitments';
+import type { string_book } from '../agent-source/string_book';
+import type { BookCommitment } from '../../commitments/_base/BookCommitment';
+import { getAllCommitmentTypes } from '../../commitments/_common/getAllCommitmentTypes';
 import { getCommitmentDefinition } from '../../commitments/_common/getCommitmentDefinition';
 import type { string_markdown } from '../../types/string_markdown';
 import { shiftMarkdownHeadingLevels } from '../../utils/markdown/shiftMarkdownHeadingLevels';
+import { getSafeCodeBlock } from './getSafeCodeBlock';
 
 /**
  * Minimal commitment shape used by documentation renderers.
@@ -59,6 +64,23 @@ const CLOSED_COMMITMENT_TYPE = 'CLOSED';
  */
 const COMMITMENT_DOCUMENTATION_SECTION_HEADING_LEVEL = 2;
 
+/**
+ * Markdown code blocks whose Book source is shown as a commitment example.
+ *
+ * @private internal utility of `createStandaloneBookLanguageMarkdown`
+ */
+const BOOK_CODE_BLOCK_PATTERN = /(`{3,})book[^\n]*\n([\s\S]*?)\n\1/gu;
+
+/**
+ * Recognized commitment types, ordered so compound keywords take priority over
+ * their shorter prefixes when reducing an example line by line.
+ *
+ * @private internal utility of `createStandaloneBookLanguageMarkdown`
+ */
+const COMMITMENT_TYPES_BY_LENGTH = [...getAllCommitmentTypes()].sort(
+    (firstType, secondType) => secondType.length - firstType.length,
+);
+
 /**
  * Removes the top-level heading from one commitment documentation block.
  *
@@ -76,12 +98,18 @@ function removeLeadingTopLevelHeading(markdown: string): string {
  *
  * @param title - Heading label for the subsection.
  * @param documentation - Raw commitment documentation markdown.
+ * @param group - Commitment family represented by the documentation entry.
  * @param headingLevelShift - How many levels the whole entry is nested by its host document.
  * @returns Markdown subsection introducing one commitment of the family.
  *
  * @private internal utility of `createStandaloneBookLanguageMarkdown`
  */
-function renderDocumentationSection(title: string, documentation: string, headingLevelShift: number): string {
+function renderDocumentationSection(
+    title: string,
+    documentation: string,
+    group: GroupedCommitmentDocumentationSource,
+    headingLevelShift: number,
+): string {
     const headingPrefix = '#'.repeat(COMMITMENT_DOCUMENTATION_SECTION_HEADING_LEVEL + headingLevelShift);
 
     return spaceTrim(
@@ -90,7 +118,9 @@ function renderDocumentationSection(title: string, documentation: string, headin
 
             ${block(
                 shiftMarkdownHeadingLevels(
-                    removeLeadingTopLevelHeading(documentation) as string_markdown,
+                    removeLeadingTopLevelHeading(
+                        renderFocusedCommitmentExamples(documentation, group),
+                    ) as string_markdown,
                     headingLevelShift + 1,
                 ),
             )}
@@ -116,7 +146,10 @@ export function renderGroupedCommitmentDocumentationMarkdown(
 ): string {
     const commitmentTypes = new Set([group.primary.type, ...group.aliases]);
 
-    if (commitmentTypes.has(OPEN_COMMITMENT_TYPE) && commitmentTypes.has(CLOSED_COMMITMENT_TYPE)) {
+    const isOpenClosedCommitmentFamily =
+        commitmentTypes.has(OPEN_COMMITMENT_TYPE) && commitmentTypes.has(CLOSED_COMMITMENT_TYPE);
+
+    if (isOpenClosedCommitmentFamily) {
         const openCommitmentDefinition = getCommitmentDefinition(OPEN_COMMITMENT_TYPE);
         const closedCommitmentDefinition = getCommitmentDefinition(CLOSED_COMMITMENT_TYPE);
 
@@ -127,6 +160,7 @@ export function renderGroupedCommitmentDocumentationMarkdown(
                         renderDocumentationSection(
                             OPEN_COMMITMENT_TYPE,
                             openCommitmentDefinition.documentation,
+                            group,
                             headingLevelShift,
                         ),
                     )}
@@ -135,6 +169,7 @@ export function renderGroupedCommitmentDocumentationMarkdown(
                         renderDocumentationSection(
                             CLOSED_COMMITMENT_TYPE,
                             closedCommitmentDefinition.documentation,
+                            group,
                             headingLevelShift,
                         ),
                     )}
@@ -144,7 +179,259 @@ export function renderGroupedCommitmentDocumentationMarkdown(
     }
 
     return shiftMarkdownHeadingLevels(
-        removeLeadingTopLevelHeading(group.primary.documentation) as string_markdown,
+        removeLeadingTopLevelHeading(
+            renderFocusedCommitmentExamples(group.primary.documentation, group),
+        ) as string_markdown,
         headingLevelShift,
     );
 }
+
+/**
+ * Rewrites Book examples in commitment documentation to show one canonical
+ * commitment in isolation, with only `GOAL` and `CLOSED` as supporting syntax.
+ *
+ * @param documentation - Raw commitment documentation markdown.
+ * @param group - Commitment family represented by the documentation entry.
+ * @returns Documentation whose Book examples use focused canonical syntax.
+ *
+ * @private internal utility of `createStandaloneBookLanguageMarkdown`
+ */
+function renderFocusedCommitmentExamples(
+    documentation: string,
+    group: GroupedCommitmentDocumentationSource,
+): string {
+    return documentation.replace(BOOK_CODE_BLOCK_PATTERN, (codeBlock, _fence, source: string) => {
+        const focusedSource = createFocusedCommitmentExampleSource(source, group);
+        return focusedSource ? getSafeCodeBlock(focusedSource, 'book') : codeBlock;
+    });
+}
+
+/**
+ * Creates a focused Book source example for one commitment documentation entry.
+ *
+ * @param source - Original Book source from the commitment documentation.
+ * @param group - Commitment family represented by the documentation entry.
+ * @returns Focused source, or `null` when the source cannot be safely reduced.
+ *
+ * @private internal utility of `createStandaloneBookLanguageMarkdown`
+ */
+function createFocusedCommitmentExampleSource(
+    source: string,
+    group: GroupedCommitmentDocumentationSource,
+): string | null {
+    const parsedSource = parseAgentSourceWithCommitments(source as string_book);
+    const commitmentTypes = new Set([group.primary.type, ...group.aliases]);
+    const isOpenClosedCommitmentFamily =
+        commitmentTypes.has(OPEN_COMMITMENT_TYPE) && commitmentTypes.has(CLOSED_COMMITMENT_TYPE);
+    const allowedCommitmentTypes = new Set([
+        group.primary.type,
+        ...group.aliases,
+        'GOAL',
+        CLOSED_COMMITMENT_TYPE,
+    ]);
+    const canonicalTypeByCommitmentType = createCanonicalCommitmentTypeByCommitmentType(
+        group,
+        isOpenClosedCommitmentFamily,
+    );
+    const focusedCommitments = parsedSource.commitments
+        .filter((commitment) => allowedCommitmentTypes.has(commitment.type))
+        .map((commitment) => {
+            const type = canonicalTypeByCommitmentType.get(commitment.type) || commitment.type;
+            return `${type}${commitment.content ? ` ${commitment.content}` : ''}`;
+        });
+
+    if (focusedCommitments.length > 0) {
+        return finalizeFocusedCommitmentExampleSource(
+            getFocusedExampleAgentName(parsedSource.agentName),
+            focusedCommitments,
+        );
+    }
+
+    return createLineFocusedCommitmentExampleSource(source, group, isOpenClosedCommitmentFamily);
+}
+
+/**
+ * Creates a focused example when the Book parser cannot recognize the target
+ * commitment because it appears as the first source line or has a shared prefix.
+ *
+ * @param source - Original Book source from the documentation code block.
+ * @param group - Commitment family represented by the documentation entry.
+ * @param isOpenClosedCommitmentFamily - Whether the family contains both switch commitments.
+ * @returns Focused source, or `null` when the source does not use this commitment family.
+ *
+ * @private internal utility of `createStandaloneBookLanguageMarkdown`
+ */
+function createLineFocusedCommitmentExampleSource(
+    source: string,
+    group: GroupedCommitmentDocumentationSource,
+    isOpenClosedCommitmentFamily: boolean,
+): string | null {
+    const sourceLines = source.split(/\r?\n/u);
+    const allowedCommitmentTypes = new Set([group.primary.type, ...group.aliases, 'GOAL', CLOSED_COMMITMENT_TYPE]);
+    const canonicalTypeByCommitmentType = createCanonicalCommitmentTypeByCommitmentType(
+        group,
+        isOpenClosedCommitmentFamily,
+    );
+    const focusedCommitments: Array<string> = [];
+    const firstSourceLine = sourceLines.find((line) => line.trim().length > 0) || null;
+    const firstCommitmentType = firstSourceLine ? getCommitmentTypeAtLine(firstSourceLine) : null;
+    const agentName = firstSourceLine && !firstCommitmentType ? firstSourceLine.trim() : null;
+    let activeFocusedCommitmentIndex: number | null = null;
+    let isInsideCodeBlock = false;
+
+    for (const sourceLine of sourceLines) {
+        const trimmedSourceLine = sourceLine.trim();
+
+        if (trimmedSourceLine.startsWith('```')) {
+            appendLineToActiveCommitment(focusedCommitments, activeFocusedCommitmentIndex, sourceLine);
+            isInsideCodeBlock = !isInsideCodeBlock;
+            continue;
+        }
+
+        if (isInsideCodeBlock) {
+            appendLineToActiveCommitment(focusedCommitments, activeFocusedCommitmentIndex, sourceLine);
+            continue;
+        }
+
+        const commitmentType = getCommitmentTypeAtLine(sourceLine);
+
+        if (!commitmentType) {
+            appendLineToActiveCommitment(focusedCommitments, activeFocusedCommitmentIndex, sourceLine);
+            continue;
+        }
+
+        if (!allowedCommitmentTypes.has(commitmentType)) {
+            activeFocusedCommitmentIndex = null;
+            continue;
+        }
+
+        const canonicalType = canonicalTypeByCommitmentType.get(commitmentType) || commitmentType;
+        const content = trimmedSourceLine.slice(commitmentType.length).trimStart();
+        focusedCommitments.push(`${canonicalType}${content ? ` ${content}` : ''}`);
+        activeFocusedCommitmentIndex = focusedCommitments.length - 1;
+    }
+
+    return finalizeFocusedCommitmentExampleSource(agentName, focusedCommitments);
+}
+
+/**
+ * Finds the longest supported commitment keyword at the start of a source line.
+ *
+ * @param sourceLine - One Book source line to inspect.
+ * @returns Matching commitment type, or `null` when the line is ordinary content.
+ *
+ * @private internal utility of `createStandaloneBookLanguageMarkdown`
+ */
+function getCommitmentTypeAtLine(sourceLine: string): BookCommitment | null {
+    const trimmedSourceLine = sourceLine.trim();
+
+    return (
+        COMMITMENT_TYPES_BY_LENGTH.find(
+            (commitmentType) =>
+                trimmedSourceLine === commitmentType || trimmedSourceLine.startsWith(`${commitmentType} `),
+        ) || null
+    );
+}
+
+/**
+ * Appends a source line only when a focused commitment currently owns it.
+ *
+ * @param focusedCommitments - Focused commitments assembled from the example.
+ * @param activeFocusedCommitmentIndex - Index of the commitment receiving continuation lines.
+ * @param sourceLine - Source line to append.
+ *
+ * @private internal utility of `createStandaloneBookLanguageMarkdown`
+ */
+function appendLineToActiveCommitment(
+    focusedCommitments: Array<string>,
+    activeFocusedCommitmentIndex: number | null,
+    sourceLine: string,
+): void {
+    if (activeFocusedCommitmentIndex === null) {
+        return;
+    }
+
+    focusedCommitments[activeFocusedCommitmentIndex] += `\n${sourceLine}`;
+}
+
+/**
+ * Adds the standard closing marker and formats one reduced Book example.
+ *
+ * @param agentName - Optional human-readable title retained from the original example.
+ * @param focusedCommitments - Canonical commitment blocks kept in the example.
+ * @returns Focused source, or `null` when no relevant commitment was found.
+ *
+ * @private internal utility of `createStandaloneBookLanguageMarkdown`
+ */
+function finalizeFocusedCommitmentExampleSource(
+    agentName: string | null,
+    focusedCommitments: Array<string>,
+): string | null {
+    const normalizedFocusedCommitments = focusedCommitments.map((commitment) => commitment.trim());
+
+    if (normalizedFocusedCommitments.length === 0) {
+        return null;
+    }
+
+    const isClosedCommitmentIncluded = normalizedFocusedCommitments.some((commitment) =>
+        commitment.startsWith(CLOSED_COMMITMENT_TYPE),
+    );
+    const isOpenCommitmentIncluded = normalizedFocusedCommitments.some((commitment) =>
+        commitment.startsWith(OPEN_COMMITMENT_TYPE),
+    );
+
+    if (!isClosedCommitmentIncluded && !isOpenCommitmentIncluded) {
+        normalizedFocusedCommitments.push(CLOSED_COMMITMENT_TYPE);
+    }
+
+    return [agentName, ...normalizedFocusedCommitments]
+        .filter((line): line is string => Boolean(line))
+        .join('\n\n');
+}
+
+/**
+ * Keeps an example title unless the parser interpreted a commitment-only
+ * example's first line as its mandatory agent name.
+ *
+ * @param agentName - Parsed agent name from the original example.
+ * @returns Agent title suitable for a focused example, or `null` when absent.
+ *
+ * @private internal utility of `createStandaloneBookLanguageMarkdown`
+ */
+function getFocusedExampleAgentName(agentName: string | null): string | null {
+    if (!agentName || getCommitmentDefinition(agentName as BookCommitment)) {
+        return null;
+    }
+
+    return agentName;
+}
+
+/**
+ * Maps aliases to the canonical keyword shown by a commitment example.
+ *
+ * `OPEN` and `CLOSED` share one documentation entry, but each remains a
+ * distinct keyword and must therefore retain its own spelling.
+ *
+ * @param group - Commitment family represented by the documentation entry.
+ * @param isOpenClosedCommitmentFamily - Whether the family contains both switch commitments.
+ * @returns Canonical keyword by accepted source keyword.
+ *
+ * @private internal utility of `createStandaloneBookLanguageMarkdown`
+ */
+function createCanonicalCommitmentTypeByCommitmentType(
+    group: GroupedCommitmentDocumentationSource,
+    isOpenClosedCommitmentFamily: boolean,
+): ReadonlyMap<string, string> {
+    const canonicalTypeByCommitmentType = new Map<string, string>();
+
+    canonicalTypeByCommitmentType.set(group.primary.type, group.primary.type);
+
+    for (const alias of group.aliases) {
+        canonicalTypeByCommitmentType.set(
+            alias,
+            isOpenClosedCommitmentFamily ? alias : group.primary.type,
+        );
+    }
+
+    return canonicalTypeByCommitmentType;
+}

package/src/book-3.0/LiteAgent.ts

@@ -1,10 +1,4 @@
-import {
-    Agent as AgentFromKit,
-    fileSearchTool,
-    run,
-    setDefaultOpenAIClient,
-    setDefaultOpenAIKey,
-} from '@openai/agents';
+import type { Agent as AgentFromKit } from '@openai/agents';
 import { readFile } from 'fs/promises';
 import { basename, resolve } from 'path';
 import { fileURLToPath } from 'url';
@@ -17,6 +11,7 @@ import { computeOpenAiUsage } from '../llm-providers/openai/computeOpenAiUsage';
 import { OPENAI_MODELS } from '../llm-providers/openai/openai-models';
 import { OpenAiAgentKitExecutionToolsToolBuilder } from '../llm-providers/openai/OpenAiAgentKitExecutionToolsToolBuilder';
 import { OpenAiVectorStoreHandler } from '../llm-providers/openai/OpenAiVectorStoreHandler';
+import { loadOpenAiAgentsModule } from '../llm-providers/openai/utils/loadOpenAiAgentsModule';
 import { $provideScriptingForNode } from '../scrapers/_common/register/$provideScriptingForNode';
 import type { string_knowledge_source_link } from '../types/string_knowledge_source_content';
 import type { string_markdown, string_markdown_text } from '../types/string_markdown';
@@ -112,6 +107,7 @@ export class LiteAgent {
         const preparedAgent = await this.prepareAgent();
         preparedAgent.toolBuilder?.clearRunState();
 
+        const { run } = await loadOpenAiAgentsModule();
         const result = await run(
             preparedAgent.agent,
             createLiteAgentPromptText(normalizedMessage, options.context, preparedAgent.modelRequirements.promptSuffix),
@@ -165,6 +161,12 @@ export class LiteAgent {
             userId: this.options.userId,
         });
         const client = await runtime.getClient();
+        const {
+            Agent: AgentFromKit,
+            fileSearchTool,
+            setDefaultOpenAIClient,
+            setDefaultOpenAIKey,
+        } = await loadOpenAiAgentsModule();
 
         setDefaultOpenAIClient(client as TODO_any);
 
@@ -190,9 +192,9 @@ export class LiteAgent {
                   })
                 : null;
         const agentTools =
-            toolBuilder?.buildAgentKitTools({
+            (await toolBuilder?.buildAgentKitTools({
                 tools: modelRequirements.tools ? [...modelRequirements.tools] : undefined,
-            }) || [];
+            })) || [];
         const normalizedKnowledgeSources = await normalizeLiteAgentKnowledgeSources(
             modelRequirements.knowledgeSources || [],
             resolvedSource.sourceDirectoryPath,

package/src/book-components/Chat/utils/$provideServerDomWindow.ts

@@ -0,0 +1,77 @@
+import type { WindowLike as DomWindowLike } from 'dompurify';
+import { spaceTrim } from 'spacetrim';
+import { assertsError } from '../../../errors/assertsError';
+import { EnvironmentMismatchError } from '../../../errors/EnvironmentMismatchError';
+
+/**
+ * Shared DOM window reused by every render which happens outside of a browser
+ *
+ * @private utility of `$provideServerDomWindow`
+ */
+let serverDomWindow: DomWindowLike | null = null;
+
+/**
+ * Provides a DOM `window` for runtimes which do not have one, for example Node.js during server-side rendering
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it creates and caches one shared DOM window
+ *
+ * @returns DOM window which can back a DOM-dependent library like `DOMPurify`
+ * @throws {EnvironmentMismatchError} When the current runtime can not create a DOM window
+ * @private utility of `renderMarkdown`
+ */
+export function $provideServerDomWindow(): DomWindowLike {
+    if (serverDomWindow === null) {
+        const { JSDOM } = requireServerDomLibrary();
+        serverDomWindow = new JSDOM('').window as unknown as DomWindowLike;
+    }
+
+    return serverDomWindow;
+}
+
+/**
+ * Loads `jsdom` which backs the DOM window outside of a browser
+ *
+ * Note: [😷] `jsdom` reaches for Node.js built-ins like `fs`, `child_process` and `net`, so browser bundlers must
+ *       never follow the `require` below - even though it is unreachable in a browser, bundlers resolve it statically.
+ *       They are told to replace `jsdom` with an empty module by the `browser` field of the generated package
+ *       manifests, which is written by `applyBrowserUnsupportedDependencyStubs` during the package generation.
+ *
+ * @returns The `jsdom` library
+ * @throws {EnvironmentMismatchError} When `jsdom` can not be loaded in the current runtime
+ * @private utility of `$provideServerDomWindow`
+ */
+function requireServerDomLibrary(): typeof import('jsdom') {
+    let serverDomLibrary: Partial<typeof import('jsdom')> | null = null;
+    let serverDomLibraryError: Error | null = null;
+
+    try {
+        // Note: [😷] Keep `'jsdom'` written as a literal, bundlers do not replace a computed module name
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        serverDomLibrary = require('jsdom') as typeof import('jsdom');
+    } catch (error) {
+        assertsError(error);
+        serverDomLibraryError = error;
+    }
+
+    if (typeof serverDomLibrary?.JSDOM !== 'function') {
+        throw new EnvironmentMismatchError(
+            spaceTrim(
+                (block) => `
+                    Markdown can not be rendered because there is no DOM in the current runtime.
+
+                    Rendered markdown is sanitized through \`DOMPurify\`, which needs a DOM - the DOM of the browser
+                    when the code runs in a browser and \`jsdom\` in every other runtime, for example during
+                    server-side rendering in **Node.js**.
+
+                    ${block(
+                        serverDomLibraryError === null
+                            ? 'The `jsdom` module was resolved but it does not export `JSDOM`, which happens when a bundler replaces `jsdom` with an empty module in a build which is neither a browser build nor a Node.js build.'
+                            : `${serverDomLibraryError.name}: ${serverDomLibraryError.message}`,
+                    )}
+                `,
+            ),
+        );
+    }
+
+    return serverDomLibrary as typeof import('jsdom');
+}