@promptbook/cli 0.114.0-0 → 0.114.0-10

package/src/book-2.0/agent-source/createAgentModelRequirementsWithCommitments.ts

@@ -1,4 +1,3 @@
-import { aggregateUseCommitmentSystemMessages } from '../../commitments/USE/aggregateUseCommitmentSystemMessages';
 import { createBasicAgentModelRequirements } from '../../commitments/_base/createEmptyAgentModelRequirements';
 import type { string_model_name } from '../../types/string_model_name';
 import type { AgentModelRequirements } from './AgentModelRequirements';
@@ -32,7 +31,6 @@ export async function createAgentModelRequirementsWithCommitments(
 
     let requirements = createInitialAgentModelRequirements(parseResult.agentName, modelName);
     requirements = await applyCommitmentsToAgentModelRequirements(requirements, filteredCommitments, options);
-    requirements = aggregateUseCommitmentSystemMessages(requirements, filteredCommitments);
     requirements = await augmentAgentModelRequirementsFromSource(requirements, parseResult, agentSource);
     requirements = await materializeInlineKnowledgeSources(requirements, options?.inlineKnowledgeSourceUploader);
 

package/src/book-2.0/agent-source/parseAgentSource/applyMetaCommitment.ts

@@ -1,6 +1,5 @@
 import { spaceTrim } from 'spacetrim';
 import { resolveAvatarVisualId } from '../../../avatars/visuals/avatarVisualRegistry';
-import { normalizeTo_camelCase } from '../../../utils/normalization/normalizeTo_camelCase';
 import { normalizeDomainForMatching } from '../../../utils/validators/url/normalizeDomainForMatching';
 import type { ParsedCommitment } from '../../../commitments/_base/ParsedCommitment';
 import { normalizeAgentVisibility } from '../agentSourceVisibility';
@@ -22,6 +21,8 @@ const META_COMMITMENT_APPLIERS: Readonly<Record<string, MetaCommitmentApplier |
     'META IMAGE': applyMetaImageContent,
     'META DESCRIPTION': applyMetaDescriptionContent,
     'META DISCLAIMER': applyMetaDisclaimerContent,
+    'META FULLNAME': applyMetaFullnameContent,
+    'META ID': applyMetaIdContent,
     'META INPUT PLACEHOLDER': applyMetaInputPlaceholderContent,
     'META THINKING MESSAGE': applyMetaThinkingMessageContent,
     'MESSAGE SUFFIX': applyMessageSuffixContent,
@@ -40,37 +41,7 @@ export function applyMetaCommitment(state: ParseAgentSourceState, commitment: Pa
     const applyMetaContent = META_COMMITMENT_APPLIERS[commitment.type];
     if (applyMetaContent) {
         applyMetaContent(state, commitment.content);
-        return;
-    }
-
-    if (commitment.type === 'META') {
-        applyGenericMetaCommitment(state, commitment.content);
-    }
-}
-
-/**
- * Applies the generic META commitment form (`META TYPE value`).
- */
-function applyGenericMetaCommitment(state: ParseAgentSourceState, content: string): void {
-    const metaTypeRaw = content.split(' ')[0] || 'NONE';
-    const metaValue = spaceTrim(content.substring(metaTypeRaw.length));
-
-    if (metaTypeRaw === 'LINK') {
-        state.links.push(metaValue);
-    }
-
-    if (metaTypeRaw.toUpperCase() === 'AVATAR') {
-        applyMetaAvatarContent(state, metaValue);
-        return;
     }
-
-    if (metaTypeRaw.toUpperCase() === 'VISIBILITY') {
-        applyMetaVisibilityContent(state, metaValue);
-        return;
-    }
-
-    const metaType = normalizeTo_camelCase(metaTypeRaw);
-    state.meta[metaType] = metaValue;
 }
 
 /**
@@ -123,6 +94,20 @@ function applyMetaDisclaimerContent(state: ParseAgentSourceState, content: strin
     state.meta.disclaimer = content;
 }
 
+/**
+ * Applies META FULLNAME content into the canonical `meta.fullname` field.
+ */
+function applyMetaFullnameContent(state: ParseAgentSourceState, content: string): void {
+    state.meta.fullname = spaceTrim(content);
+}
+
+/**
+ * Applies META ID content into the canonical `meta.id` field.
+ */
+function applyMetaIdContent(state: ParseAgentSourceState, content: string): void {
+    state.meta.id = spaceTrim(content);
+}
+
 /**
  * Applies META INPUT PLACEHOLDER content into the canonical `meta.inputPlaceholder` field.
  */

package/src/book-2.0/agent-source/parseAgentSource/createCapabilitiesFromCommitment.ts

@@ -12,46 +12,11 @@ import type { ParseAgentSourceState } from './ParseAgentSourceState';
  * Static capability descriptors for commitments that map one-to-one to a visible capability.
  */
 const SIMPLE_CAPABILITY_BY_COMMITMENT_TYPE: Readonly<Record<string, AgentCapability | undefined>> = {
-    'USE BROWSER': {
-        type: 'browser',
-        label: 'Browser',
-        iconName: 'Globe',
-    },
-    'USE SEARCH ENGINE': {
-        type: 'search-engine',
-        label: 'Internet',
-        iconName: 'Search',
-    },
-    'USE SEARCH': {
-        type: 'search-engine',
-        label: 'Internet',
-        iconName: 'Search',
-    },
-    'USE DEEPSEARCH': {
-        type: 'search-engine',
-        label: 'DeepSearch',
-        iconName: 'Search',
-    },
-    'USE TIME': {
-        type: 'time',
-        label: 'Time',
-        iconName: 'Clock',
-    },
-    'USE TIMEOUT': {
-        type: 'timeout',
-        label: 'Timers',
-        iconName: 'Clock',
-    },
     'USE USER LOCATION': {
         type: 'user-location',
         label: 'User location',
         iconName: 'MapPin',
     },
-    'USE EMAIL': {
-        type: 'email',
-        label: 'Email',
-        iconName: 'Mail',
-    },
     'USE POPUP': {
         type: 'popup',
         label: 'Popup',

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

@@ -98,9 +98,7 @@ export type BookLanguageManualDictionary = {
     readonly metadataLabels: {
         readonly bookLanguageVersion: string;
         readonly generatedAt: string;
-        readonly commitmentGroups: string;
-        readonly implementedCommitments: string;
-        readonly placeholderCommitments: string;
+        readonly commitmentCount: string;
     };
 
     /**
@@ -144,7 +142,6 @@ export type BookLanguageManualDictionary = {
     readonly primitivesSections: {
         readonly coreSyntax: BookLanguageManualChapter;
         readonly references: BookLanguageManualChapter;
-        readonly keywordsTitle: string;
     };
 
     /**
@@ -159,18 +156,7 @@ export type BookLanguageManualDictionary = {
      * Labels used in every commitment catalog entry.
      */
     readonly commitmentLabels: {
-        readonly status: string;
         readonly aliases: string;
-        readonly semantics: string;
-        readonly typeSchema: string;
-        readonly blockSchema: string;
-        readonly lowLevelNotice: string;
-        readonly usage: string;
-        readonly usageOccurrence: string;
-        readonly usageOccurrences: string;
-        readonly statusImplemented: string;
-        readonly statusPlaceholder: string;
-        readonly noAliases: string;
     };
 
     /**

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

@@ -21,19 +21,6 @@ export const bookLanguageDocumentationExamples: ReadonlyArray<BookLanguageDocume
             CLOSED
         `),
     },
-    {
-        id: 'tool-using-browser-search-agent',
-        source: spaceTrim(`
-            Web Research Assistant
-
-            GOAL Research topics using fresh and verifiable information.
-            USE SEARCH ENGINE Prefer official sources and recent publications.
-            USE BROWSER
-            RULE Verify important claims across multiple sources when possible.
-            RULE Include source links in your final answer.
-            INITIAL MESSAGE Ask me what topic you want to research and how deep the report should be.
-        `),
-    },
     {
         id: 'rule-and-knowledge-agent',
         source: spaceTrim(`
@@ -48,25 +35,12 @@ export const bookLanguageDocumentationExamples: ReadonlyArray<BookLanguageDocume
         `),
     },
     {
-        id: 'memory-agent-with-long-term-memory',
-        source: spaceTrim(`
-            Customer Success Memory Agent
-
-            GOAL Support SaaS customers while remembering relevant setup and preference context.
-            MEMORY Remember product setup, user goals, and communication preferences.
-            RULE Store only user-approved preferences and project context.
-            RULE Never store secrets or sensitive data unless explicitly requested and allowed.
-            INITIAL MESSAGE I can remember your setup and preferences for future sessions.
-        `),
-    },
-    {
-        id: 'use-project-and-wallet-integration-agent',
+        id: 'use-project-integration-agent',
         source: spaceTrim(`
             Repository Maintainer
 
             GOAL Maintain a GitHub repository and prepare safe pull requests.
             USE PROJECT https://github.com/acme/website
-            WALLET Store credentials for repository operations.
             RULE Before editing files, explain the planned change and impacted paths.
             RULE Never reveal raw credentials in chat output.
             INITIAL MESSAGE I can inspect the repository and help you prepare PR-ready changes.

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

@@ -1,5 +1,4 @@
 import { spaceTrim } from 'spacetrim';
-import { NotYetImplementedCommitmentDefinition } from '../../commitments/_base/NotYetImplementedCommitmentDefinition';
 import { getGroupedCommitmentDefinitions } from '../../commitments/_common/getGroupedCommitmentDefinitions';
 import { parseAgentSourceWithCommitments } from '../agent-source/parseAgentSourceWithCommitments';
 import type { string_book } from '../agent-source/string_book';
@@ -31,22 +30,13 @@ const COMPOSITION_COMMITMENT_TYPES = new Set(['FROM', 'IMPORT', 'IMPORTS', 'TEAM
  * @private internal utility of `createStandaloneBookLanguageMarkdown`
  */
 const TOOLING_COMMITMENT_TYPES = new Set([
-    'USE BROWSER',
-    'USE DEEPSEARCH',
-    'USE SEARCH ENGINE',
-    'USE SEARCH',
-    'USE SPAWN',
-    'USE EMAIL',
     'USE POPUP',
-    'USE TIME',
     'USE USER LOCATION',
     'USE PROJECT',
     'USE CALENDAR',
     'USE IMAGE GENERATOR',
     'USE MCP',
     'USE PRIVACY',
-    'MEMORY',
-    'MEMORIES',
 ]);
 
 /**
@@ -57,7 +47,6 @@ const TOOLING_COMMITMENT_TYPES = new Set([
 const PROFILE_COMMITMENT_TYPES = new Set([
     'GOAL',
     'GOALS',
-    'META',
     'META AVATAR',
     'META VISUAL',
     'META IMAGE',
@@ -65,6 +54,8 @@ const PROFILE_COMMITMENT_TYPES = new Set([
     'META DOMAIN',
     'META DESCRIPTION',
     'META DISCLAIMER',
+    'META FULLNAME',
+    'META ID',
     'META INPUT PLACEHOLDER',
     'META THINKING MESSAGE',
     'META VISIBILITY',
@@ -172,14 +163,10 @@ export function createStandaloneBookLanguageMarkdown(
         : [];
     const manualCommitments = [...catalogCommitments, ...lowLevelCommitments];
     const generatedAtIso = new Date().toISOString();
-    const placeholderCommitmentCount = manualCommitments.filter(
-        ({ primary }) => primary instanceof NotYetImplementedCommitmentDefinition,
-    ).length;
     const catalogTitleSuffix = isServerSpecificManual
         ? dictionary.commitmentCatalogTitleSuffixes.usedFirst
         : dictionary.commitmentCatalogTitleSuffixes.all;
-
-    const allCommitmentKeywords = manualCommitments.flatMap(({ primary, aliases }) => [primary.type, ...aliases]);
+    const commitmentSectionAnchorByType = createCommitmentSectionAnchorByType(manualCommitments);
 
     return spaceTrim(
         // [✨]
@@ -190,11 +177,7 @@ export function createStandaloneBookLanguageMarkdown(
 
             - ${dictionary.metadataLabels.bookLanguageVersion}: \`${BOOK_LANGUAGE_VERSION}\`
             - ${dictionary.metadataLabels.generatedAt}: \`${generatedAtIso}\`
-            - ${dictionary.metadataLabels.commitmentGroups}: \`${manualCommitments.length}\`
-            - ${dictionary.metadataLabels.implementedCommitments}: \`${
-            manualCommitments.length - placeholderCommitmentCount
-        }\`
-            - ${dictionary.metadataLabels.placeholderCommitments}: \`${placeholderCommitmentCount}\`
+            - ${dictionary.metadataLabels.commitmentCount}: \`${manualCommitments.length}\`
 
             ## <a id="table-of-contents"></a>${dictionary.tableOfContentsTitle}
 
@@ -203,14 +186,18 @@ export function createStandaloneBookLanguageMarkdown(
             - [${dictionary.chapters.howToStructure.title}](#how-to-structure-good-agents)
             - [${dictionary.chapters.primitives.title}](#primitives-and-constructs-reference)
             - [${dictionary.chapters.commitmentCatalog.title}${catalogTitleSuffix}](#commitment-catalog)
+            ${block(renderCommitmentCatalogTableOfContents(catalogCommitments))}
             - [${dictionary.chapters.examples.title}](#end-to-end-examples)
             - [${dictionary.chapters.pitfalls.title}](#do-nots-and-common-pitfalls)
             - [${dictionary.chapters.tutorial.title}](#build-an-agent-from-scratch-offline-tutorial)
-            ${
+            ${block(
                 isLowLevelCommitmentsIncluded
-                    ? `- [${dictionary.chapters.lowLevelCommitments.title}](#low-level-commitments)`
-                    : ''
-            }
+                    ? spaceTrim(`
+                        - [${dictionary.chapters.lowLevelCommitments.title}](#low-level-commitments)
+                        ${renderCommitmentCatalogTableOfContents(lowLevelCommitments)}
+                    `)
+                    : '',
+            )}
 
             ## <a id="what-book-language-is"></a>${dictionary.chapters.whatIs.title}
 
@@ -254,25 +241,23 @@ export function createStandaloneBookLanguageMarkdown(
 
             ${block(dictionary.primitivesSections.references.body)}
 
-            ### ${dictionary.primitivesSections.keywordsTitle}
-
-            ${block(getSafeCodeBlock(allCommitmentKeywords.join(', '), 'text'))}
-
-            <a id="commitment-catalog-all-commitments"></a>
-
             ## <a id="commitment-catalog"></a>${dictionary.chapters.commitmentCatalog.title}${catalogTitleSuffix}
 
             ${block(dictionary.chapters.commitmentCatalog.body)}
 
-            ${block(renderCommitmentCatalogSections(catalogCommitments, commitmentUsageByType, dictionary))}
+            ${block(renderCommitmentCatalogSections(catalogCommitments, dictionary))}
 
             ## <a id="end-to-end-examples"></a>${dictionary.chapters.examples.title}
 
             ${block(
                 isServerSpecificManual
-                    ? selectedAgents.map((agent) => renderBakedAgentExampleSection(agent, dictionary)).join('\n\n')
+                    ? selectedAgents
+                          .map((agent) =>
+                              renderBakedAgentExampleSection(agent, dictionary, commitmentSectionAnchorByType),
+                          )
+                          .join('\n\n')
                     : bookLanguageDocumentationExamples
-                          .map((example) => renderExampleSection(example, dictionary))
+                          .map((example) => renderExampleSection(example, dictionary, commitmentSectionAnchorByType))
                           .join('\n\n'),
             )}
 
@@ -295,9 +280,7 @@ export function createStandaloneBookLanguageMarkdown(
             ${block(dictionary.tutorialSections.checklistBody)}
 
             ${block(
-                isLowLevelCommitmentsIncluded
-                    ? renderLowLevelCommitmentsChapter(lowLevelCommitments, commitmentUsageByType, dictionary)
-                    : '',
+                isLowLevelCommitmentsIncluded ? renderLowLevelCommitmentsChapter(lowLevelCommitments, dictionary) : '',
             )}
 
             ---
@@ -345,7 +328,6 @@ function renderDetectedCommitmentList(
  * Renders every commitment section of one catalog chapter.
  *
  * @param commitmentGroups - Commitment groups to render, in final order.
- * @param commitmentUsageByType - Selected-agent occurrence counts by primary type.
  * @param dictionary - Translated labels of the manual.
  * @returns Markdown sections joined by blank lines.
  *
@@ -353,14 +335,12 @@ function renderDetectedCommitmentList(
  */
 function renderCommitmentCatalogSections(
     commitmentGroups: ReadonlyArray<BookLanguageManualCommitmentGroup>,
-    commitmentUsageByType: ReadonlyMap<string, number>,
     dictionary: BookLanguageManualDictionary,
 ): string {
     return commitmentGroups
         .map((groupedCommitment) =>
             renderCommitmentCatalogSection({
                 groupedCommitment,
-                usageCount: commitmentUsageByType.get(groupedCommitment.primary.type) || 0,
                 dictionary,
             }),
         )
@@ -371,7 +351,6 @@ function renderCommitmentCatalogSections(
  * Renders the closing chapter documenting low-level commitments.
  *
  * @param commitmentGroups - Low-level commitment groups, in final order.
- * @param commitmentUsageByType - Selected-agent occurrence counts by primary type.
  * @param dictionary - Translated labels of the manual.
  * @returns Markdown chapter for low-level commitments.
  *
@@ -379,7 +358,6 @@ function renderCommitmentCatalogSections(
  */
 function renderLowLevelCommitmentsChapter(
     commitmentGroups: ReadonlyArray<BookLanguageManualCommitmentGroup>,
-    commitmentUsageByType: ReadonlyMap<string, number>,
     dictionary: BookLanguageManualDictionary,
 ): string {
     return spaceTrim(
@@ -388,11 +366,55 @@ function renderLowLevelCommitmentsChapter(
 
             ${block(dictionary.chapters.lowLevelCommitments.body)}
 
-            ${block(renderCommitmentCatalogSections(commitmentGroups, commitmentUsageByType, dictionary))}
+            ${block(renderCommitmentCatalogSections(commitmentGroups, dictionary))}
         `,
     );
 }
 
+/**
+ * Renders links from the manual table of contents to the commitment sections.
+ *
+ * @param commitmentGroups - Commitment sections included in the manual.
+ * @returns Indented markdown links ordered like the catalog.
+ *
+ * @private internal utility of `createStandaloneBookLanguageMarkdown`
+ */
+function renderCommitmentCatalogTableOfContents(
+    commitmentGroups: ReadonlyArray<BookLanguageManualCommitmentGroup>,
+): string {
+    return commitmentGroups
+        .map(
+            ({ primary }) =>
+                `    - [${primary.icon} \`${primary.type}\`](#commitment-${toStableAnchorId(primary.type)})`,
+        )
+        .join('\n');
+}
+
+/**
+ * Maps every recognized spelling of a documented commitment to its stable section anchor.
+ *
+ * @param commitmentGroups - Commitment sections included in the manual.
+ * @returns Canonical anchor id by parsed commitment type.
+ *
+ * @private internal utility of `createStandaloneBookLanguageMarkdown`
+ */
+function createCommitmentSectionAnchorByType(
+    commitmentGroups: ReadonlyArray<BookLanguageManualCommitmentGroup>,
+): ReadonlyMap<string, string> {
+    const anchorByType = new Map<string, string>();
+
+    for (const { primary, aliases } of commitmentGroups) {
+        const anchorId = `commitment-${toStableAnchorId(primary.type)}`;
+        anchorByType.set(primary.type, anchorId);
+
+        for (const alias of aliases) {
+            anchorByType.set(alias, anchorId);
+        }
+    }
+
+    return anchorByType;
+}
+
 /**
  * Renders the "don't vs do" list of common authoring pitfalls.
  *
@@ -523,11 +545,12 @@ function prioritizeGroupedCommitments(
 function renderBakedAgentExampleSection(
     agent: BookLanguageDocumentationAgent,
     dictionary: BookLanguageManualDictionary,
+    commitmentSectionAnchorByType: ReadonlyMap<string, string>,
 ): string {
     const usedCommitmentTypes = Array.from(
         new Set(parseAgentSourceWithCommitments(agent.agentSource).commitments.map((commitment) => commitment.type)),
     );
-    const usedCommitmentsMarkdown = usedCommitmentTypes.map((type) => `\`${type}\``).join(', ');
+    const usedCommitmentsMarkdown = renderCommitmentSectionLinks(usedCommitmentTypes, commitmentSectionAnchorByType);
 
     return spaceTrim(
         (block) => `
@@ -556,6 +579,7 @@ function renderBakedAgentExampleSection(
 function renderExampleSection(
     example: BookLanguageDocumentationExample,
     dictionary: BookLanguageManualDictionary,
+    commitmentSectionAnchorByType: ReadonlyMap<string, string>,
 ): string {
     const exampleText = dictionary.exampleTexts[example.id];
 
@@ -569,6 +593,13 @@ function renderExampleSection(
 
             **${dictionary.exampleLabels.goal}:** ${exampleText.goal}
 
+            **${dictionary.exampleLabels.commitmentsUsed}:** ${renderCommitmentSectionLinks(
+            parseAgentSourceWithCommitments(example.source as string_book).commitments.map(
+                (commitment) => commitment.type,
+            ),
+            commitmentSectionAnchorByType,
+        )}
+
             **${dictionary.exampleLabels.fullSource}**
 
             ${block(getSafeCodeBlock(example.source, 'book'))}
@@ -579,3 +610,24 @@ function renderExampleSection(
         `,
     );
 }
+
+/**
+ * Renders unique commitment links used by an end-to-end example.
+ *
+ * @param commitmentTypes - Commitment types in their source order.
+ * @param commitmentSectionAnchorByType - Documented commitment anchors by parsed type.
+ * @returns Comma-separated markdown links, or an empty string when none are documented.
+ *
+ * @private internal utility of `createStandaloneBookLanguageMarkdown`
+ */
+function renderCommitmentSectionLinks(
+    commitmentTypes: ReadonlyArray<string>,
+    commitmentSectionAnchorByType: ReadonlyMap<string, string>,
+): string {
+    return Array.from(new Set(commitmentTypes))
+        .flatMap((type) => {
+            const anchorId = commitmentSectionAnchorByType.get(type);
+            return anchorId ? [`[\`${type}\`](#${anchorId})`] : [];
+        })
+        .join(', ');
+}