@promptbook/cli 0.114.0-6 → 0.114.0-8

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

@@ -33,9 +33,9 @@ type AgentProjectMarkdownReferenceInfo = Pick<
 /**
  * Creates markdown references rendering every mention of one project as a project chip.
  *
- * One project is mentioned either by its `[[project-name]]` token, by a link into its project page
- * or files, or by its public project URL. All of them render the same chip showing the project name
- * together with its running state.
+ * One project is mentioned either by its display name in chat prose, its `[[project-name]]` token,
+ * a link into its project page or files, or its public project URL. All of them render the same chip
+ * showing the project name together with its running state.
  *
  * @param options - Agent and project metadata.
  * @returns Inline markdown references for the shared chat renderer.
@@ -50,6 +50,7 @@ export function createAgentProjectMarkdownReferences(
 
         return {
             reference: project.projectName,
+            sourceTextAliases: [label],
             label,
             href: projectProfileHref,
             sourceHrefPrefixes: [projectProfileHref, ...(projectUrl ? [projectUrl] : [])],

package/esm/index.es.js

@@ -48,7 +48,7 @@ const BOOK_LANGUAGE_VERSION = '2.0.0';
  * @generated
  * @see https://github.com/webgptorg/promptbook
  */
-const PROMPTBOOK_ENGINE_VERSION = '0.114.0-6';
+const PROMPTBOOK_ENGINE_VERSION = '0.114.0-8';
 /**
  * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
  * Note: [💞] Ignore a discrepancy between file name and entity name

package/esm/src/book-components/Chat/utils/renderMarkdown.d.ts

@@ -17,6 +17,13 @@ export type MarkdownInlineReference = {
      * Raw reference text between `[[` and `]]`.
      */
     readonly reference: string;
+    /**
+     * Optional text aliases which should render as this reference when an agent mentions them in markdown.
+     *
+     * They are also accepted inside a `[[reference]]` token. This lets application code use a stable
+     * technical reference while recognizing a human-facing name in older messages.
+     */
+    readonly sourceTextAliases?: ReadonlyArray<string>;
     /**
      * Human-readable label rendered inside the link chip.
      */

package/esm/src/version.d.ts

@@ -15,7 +15,7 @@ export declare const BOOK_LANGUAGE_VERSION: string_semantic_version;
 export declare const PROMPTBOOK_ENGINE_VERSION: string_promptbook_version;
 /**
  * Represents the version string of the Promptbook engine.
- * It follows semantic versioning (e.g., `0.114.0-5`).
+ * It follows semantic versioning (e.g., `0.114.0-6`).
  *
  * @generated
  */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@promptbook/cli",
-    "version": "0.114.0-6",
+    "version": "0.114.0-8",
     "description": "Promptbook: Create persistent AI agents that turn your company's scattered knowledge into action",
     "private": false,
     "sideEffects": false,

package/src/book-components/Chat/MarkdownContent/MarkdownContent.module.css

@@ -445,7 +445,7 @@
     opacity: 0.8;
 }
 
-.MarkdownContent details {
+.MarkdownContent details:not(.inlineReferenceChip) {
     margin: 0.95em 0;
     border: 1px solid var(--md-table-border);
     border-radius: 16px;
@@ -455,13 +455,13 @@
     transition: border-color 0.18s ease, box-shadow 0.18s ease, transform 0.18s ease;
 }
 
-.MarkdownContent details:hover,
-.MarkdownContent details:focus-within {
+.MarkdownContent details:not(.inlineReferenceChip):hover,
+.MarkdownContent details:not(.inlineReferenceChip):focus-within {
     border-color: color-mix(in srgb, var(--md-link-color) 24%, var(--md-table-border) 76%);
     box-shadow: 0 12px 28px rgba(15, 23, 42, 0.12);
 }
 
-.MarkdownContent details > summary {
+.MarkdownContent details:not(.inlineReferenceChip) > summary {
     display: flex;
     align-items: center;
     gap: 0.72rem;
@@ -479,7 +479,7 @@
     transition: background 0.18s ease, color 0.18s ease;
 }
 
-.MarkdownContent details > summary::before {
+.MarkdownContent details:not(.inlineReferenceChip) > summary::before {
     content: '';
     width: 0.62rem;
     height: 0.62rem;
@@ -492,8 +492,8 @@
     transition: transform 0.18s ease, opacity 0.18s ease;
 }
 
-.MarkdownContent details > summary:hover,
-.MarkdownContent details > summary:focus-visible {
+.MarkdownContent details:not(.inlineReferenceChip) > summary:hover,
+.MarkdownContent details:not(.inlineReferenceChip) > summary:focus-visible {
     background: linear-gradient(
         180deg,
         color-mix(in srgb, var(--md-table-head-bg) 76%, rgba(255, 255, 255, 0.95) 24%),
@@ -501,34 +501,34 @@
     );
 }
 
-.MarkdownContent details > summary:focus-visible {
+.MarkdownContent details:not(.inlineReferenceChip) > summary:focus-visible {
     outline: 2px solid color-mix(in srgb, var(--md-link-color) 52%, transparent);
     outline-offset: -2px;
 }
 
-.MarkdownContent details > summary::-webkit-details-marker {
+.MarkdownContent details:not(.inlineReferenceChip) > summary::-webkit-details-marker {
     display: none;
 }
 
-.MarkdownContent details[open] > summary {
+.MarkdownContent details:not(.inlineReferenceChip)[open] > summary {
     border-bottom: 1px solid color-mix(in srgb, var(--md-table-border) 88%, transparent);
 }
 
-.MarkdownContent details[open] > summary::before {
+.MarkdownContent details:not(.inlineReferenceChip)[open] > summary::before {
     transform: rotate(45deg);
     opacity: 1;
 }
 
-.MarkdownContent details > :not(summary) {
+.MarkdownContent details:not(.inlineReferenceChip) > :not(summary) {
     margin-left: 1.05em;
     margin-right: 1.05em;
 }
 
-.MarkdownContent details > summary + * {
+.MarkdownContent details:not(.inlineReferenceChip) > summary + * {
     margin-top: 0.95em;
 }
 
-.MarkdownContent details > :last-child {
+.MarkdownContent details:not(.inlineReferenceChip) > :last-child {
     margin-bottom: 1.05em;
 }
 

package/src/book-components/Chat/utils/renderMarkdown.ts

@@ -280,6 +280,23 @@ const INLINE_REFERENCE_PLACEHOLDER_PREFIX = '@@PROMPTBOOK_INLINE_REFERENCE_PLACE
  */
 const INLINE_REFERENCE_PLACEHOLDER_REGEX = new RegExp(`${INLINE_REFERENCE_PLACEHOLDER_PREFIX}(\\d+)__`, 'g');
 
+/**
+ * Prefix for markdown text-segment placeholders used while resolving plain-text inline-reference aliases.
+ *
+ * @private utility of `renderMarkdown`
+ */
+const MARKDOWN_REFERENCE_TEXT_MASK_PLACEHOLDER_PREFIX = '@@PROMPTBOOK_MARKDOWN_REFERENCE_TEXT_MASK_PLACEHOLDER__';
+
+/**
+ * Pattern matching markdown text-segment placeholders.
+ *
+ * @private utility of `renderMarkdown`
+ */
+const MARKDOWN_REFERENCE_TEXT_MASK_PLACEHOLDER_REGEX = new RegExp(
+    `${MARKDOWN_REFERENCE_TEXT_MASK_PLACEHOLDER_PREFIX}(\\d+)__`,
+    'g',
+);
+
 /**
  * Pattern matching markdown links and images together with their raw target.
  *
@@ -365,6 +382,14 @@ export type MarkdownInlineReference = {
      */
     readonly reference: string;
 
+    /**
+     * Optional text aliases which should render as this reference when an agent mentions them in markdown.
+     *
+     * They are also accepted inside a `[[reference]]` token. This lets application code use a stable
+     * technical reference while recognizing a human-facing name in older messages.
+     */
+    readonly sourceTextAliases?: ReadonlyArray<string>;
+
     /**
      * Human-readable label rendered inside the link chip.
      */
@@ -460,6 +485,14 @@ type MaskedCodeSegmentsResult = {
     restore: (value: string_markdown) => string_markdown;
 };
 
+/**
+ * Result of temporarily masked markdown links, images and bare URLs.
+ */
+type MaskedMarkdownLinkAndUrlSegmentsResult = {
+    masked: string_markdown;
+    restore: (value: string_markdown) => string_markdown;
+};
+
 /**
  * Result of masked details blocks.
  */
@@ -787,6 +820,44 @@ function maskMarkdownCodeSegments(markdown: string_markdown): MaskedCodeSegments
     };
 }
 
+/**
+ * Masks markdown links, images and bare URLs while plain-text reference aliases are resolved.
+ *
+ * A matching display name inside an unrelated link label must keep that original link instead of
+ * producing a nested chip inside its anchor.
+ *
+ * @param markdown - Markdown without code segments.
+ * @returns Masked markdown and a restore helper.
+ *
+ * @private utility of `renderMarkdown`
+ */
+function maskMarkdownLinksAndBareUrls(markdown: string_markdown): MaskedMarkdownLinkAndUrlSegmentsResult {
+    const segments: string[] = [];
+    const addPlaceholder = (segment: string): string => {
+        const placeholder = `${MARKDOWN_REFERENCE_TEXT_MASK_PLACEHOLDER_PREFIX}${segments.length}__`;
+        segments.push(segment);
+        return placeholder;
+    };
+
+    MARKDOWN_LINK_REGEX.lastIndex = 0;
+    let masked = markdown.replace(MARKDOWN_LINK_REGEX, (match) => addPlaceholder(match)) as string_markdown;
+
+    BARE_URL_REGEX.lastIndex = 0;
+    masked = masked.replace(BARE_URL_REGEX, (_match, leadingWhitespace: string, rawUrl: string) => {
+        return `${leadingWhitespace}${addPlaceholder(rawUrl)}`;
+    }) as string_markdown;
+
+    return {
+        masked,
+        restore(value: string_markdown): string_markdown {
+            return value.replace(
+                MARKDOWN_REFERENCE_TEXT_MASK_PLACEHOLDER_REGEX,
+                (_match, index) => segments[Number(index)] ?? '',
+            );
+        },
+    };
+}
+
 /**
  * Masks `<details>...</details>` blocks in the markdown source so that Showdown never
  * processes their content.
@@ -891,6 +962,18 @@ function normalizeMarkdownInlineReferenceKey(value: string): string {
     return value.trim().toLowerCase();
 }
 
+/**
+ * Lists all token keys which can identify one inline reference.
+ *
+ * @param reference - Inline reference with its stable key and optional display-name aliases.
+ * @returns Keys recognized inside `[[...]]` tokens.
+ *
+ * @private utility of `renderMarkdown`
+ */
+function listMarkdownInlineReferenceKeys(reference: MarkdownInlineReference): ReadonlyArray<string> {
+    return [reference.reference, ...(reference.sourceTextAliases || [])];
+}
+
 /**
  * Builds a lookup of inline markdown references keyed by the authored `[[reference]]` text.
  *
@@ -905,17 +988,148 @@ function createMarkdownInlineReferenceByKey(
     const referenceByKey = new Map<string, MarkdownInlineReference>();
 
     for (const reference of references) {
-        const normalizedReference = normalizeMarkdownInlineReferenceKey(reference.reference);
-        if (!normalizedReference || referenceByKey.has(normalizedReference)) {
-            continue;
-        }
+        for (const referenceKey of listMarkdownInlineReferenceKeys(reference)) {
+            const normalizedReference = normalizeMarkdownInlineReferenceKey(referenceKey);
+            if (!normalizedReference || referenceByKey.has(normalizedReference)) {
+                continue;
+            }
 
-        referenceByKey.set(normalizedReference, reference);
+            referenceByKey.set(normalizedReference, reference);
+        }
     }
 
     return referenceByKey;
 }
 
+/**
+ * One display-name alias and the inline reference it renders.
+ *
+ * @private utility of `renderMarkdown`
+ */
+type MarkdownInlineReferenceTextMatcher = {
+    /**
+     * Reference rendered for the alias.
+     */
+    readonly reference: MarkdownInlineReference;
+
+    /**
+     * Human-readable source text recognized in markdown.
+     */
+    readonly sourceTextAlias: string;
+};
+
+/**
+ * Escapes text before embedding it into a regular expression.
+ *
+ * @param value - Literal text to match.
+ * @returns Regular-expression-safe text.
+ *
+ * @private utility of `renderMarkdown`
+ */
+function escapeRegularExpression(value: string): string {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Creates non-ambiguous display-name matchers for inline references.
+ *
+ * Longer aliases are matched first so a project named `Prague Map` wins over a project named `Map`.
+ * An alias shared by more than one reference is deliberately ignored instead of linking to an arbitrary project.
+ *
+ * @param references - References available to this markdown render.
+ * @returns Plain-text matchers ordered from longest to shortest alias.
+ *
+ * @private utility of `renderMarkdown`
+ */
+function createMarkdownInlineReferenceTextMatchers(
+    references: ReadonlyArray<MarkdownInlineReference>,
+): ReadonlyArray<MarkdownInlineReferenceTextMatcher> {
+    const matcherByNormalizedAlias = new Map<string, MarkdownInlineReferenceTextMatcher | null>();
+
+    for (const reference of references) {
+        for (const sourceTextAliasCandidate of reference.sourceTextAliases || []) {
+            const sourceTextAlias = sourceTextAliasCandidate.trim();
+            const normalizedAlias = normalizeMarkdownInlineReferenceKey(sourceTextAlias);
+            if (!normalizedAlias) {
+                continue;
+            }
+
+            const existingMatcher = matcherByNormalizedAlias.get(normalizedAlias);
+            if (existingMatcher === undefined) {
+                matcherByNormalizedAlias.set(normalizedAlias, { reference, sourceTextAlias });
+            } else if (existingMatcher !== null && existingMatcher.reference !== reference) {
+                matcherByNormalizedAlias.set(normalizedAlias, null);
+            }
+        }
+    }
+
+    return Array.from(matcherByNormalizedAlias.values())
+        .filter((matcher): matcher is MarkdownInlineReferenceTextMatcher => matcher !== null)
+        .sort(
+            (firstMatcher, secondMatcher) =>
+                secondMatcher.sourceTextAlias.length - firstMatcher.sourceTextAlias.length ||
+                firstMatcher.sourceTextAlias.localeCompare(secondMatcher.sourceTextAlias),
+        );
+}
+
+/**
+ * Creates a regular expression matching one plain-text alias with optional bold markdown around it.
+ *
+ * @param sourceTextAlias - Literal display name to match.
+ * @param isMarkdownFormattingMatched - Whether matching `**alias**` and `__alias__` form.
+ * @returns Unicode-aware whole-text regular expression.
+ *
+ * @private utility of `renderMarkdown`
+ */
+function createMarkdownInlineReferenceTextAliasRegex(
+    sourceTextAlias: string,
+    isMarkdownFormattingMatched: boolean,
+): RegExp {
+    const escapedAlias = escapeRegularExpression(sourceTextAlias);
+    const boundaryCharacterClass = '\\p{L}\\p{N}_-';
+    const boundaryPattern = `[^${boundaryCharacterClass}]`;
+    const aliasPattern = isMarkdownFormattingMatched
+        ? `(?:\\*\\*|__)${escapedAlias}(?:\\*\\*|__)`
+        : escapedAlias;
+
+    return new RegExp(`(^|${boundaryPattern})${aliasPattern}(?=$|${boundaryPattern})`, 'giu');
+}
+
+/**
+ * Replaces known project display names in agent markdown with inline-reference placeholders.
+ *
+ * Bold aliases are replaced first so an older message such as `**Prague Murders Map**` becomes one
+ * chip rather than a chip nested inside formatting markup.
+ *
+ * @param markdown - Markdown with code and links already masked.
+ * @param matchers - Non-ambiguous display-name aliases available to this render.
+ * @param createPlaceholder - Renders a matched reference into a placeholder.
+ * @returns Markdown containing inline-reference placeholders.
+ *
+ * @private utility of `renderMarkdown`
+ */
+function replaceMarkdownInlineReferenceTextAliases(
+    markdown: string_markdown,
+    matchers: ReadonlyArray<MarkdownInlineReferenceTextMatcher>,
+    createPlaceholder: CreateMarkdownInlineReferencePlaceholder,
+): string_markdown {
+    let referencedMarkdown = markdown;
+
+    for (const matcher of matchers) {
+        for (const isMarkdownFormattingMatched of [true, false]) {
+            const aliasRegex = createMarkdownInlineReferenceTextAliasRegex(
+                matcher.sourceTextAlias,
+                isMarkdownFormattingMatched,
+            );
+            referencedMarkdown = referencedMarkdown.replace(aliasRegex, (_match, leadingBoundary: string) => {
+                return `${leadingBoundary || ''}${createPlaceholder(matcher.reference)}`;
+            }) as string_markdown;
+        }
+    }
+
+    return referencedMarkdown;
+}
+
 /**
  * Comparable parts of one URL used to recognize inline references written as links or bare URLs.
  *
@@ -1303,6 +1517,19 @@ function applyMarkdownInlineReferences(markdown: string_markdown, options?: Rend
         );
     }
 
+    const textMatchers = createMarkdownInlineReferenceTextMatchers(references);
+    if (textMatchers.length !== 0) {
+        const { masked: markdownWithMaskedLinksAndUrls, restore: restoreLinksAndUrls } =
+            maskMarkdownLinksAndBareUrls(referencedMarkdown);
+        referencedMarkdown = restoreLinksAndUrls(
+            replaceMarkdownInlineReferenceTextAliases(
+                markdownWithMaskedLinksAndUrls,
+                textMatchers,
+                createPlaceholder,
+            ),
+        );
+    }
+
     return restoreMarkdownInlineReferenceChips(referencedMarkdown, renderedChips);
 }