@promptbook/cli 0.114.0-2 → 0.114.0-21

package/src/avatars/visuals/asciiOctopusAvatarVisual.ts

@@ -1,6 +1,6 @@
 /* eslint-disable no-magic-numbers */
 
-import { drawAvatarFrame } from '../avatarRenderingUtils';
+import { DEFAULT_AVATAR_SIZE, drawAvatarFrame } from '../avatarRenderingUtils';
 import type { AvatarPalette, AvatarVisualDefinition } from '../types/AvatarVisualDefinition';
 import type { OrganicTentacleRibbonPoint } from './octopusAvatarVisualShared';
 import {
@@ -31,6 +31,16 @@ const OUTLINE_GLYPHS = ['#', '%', '@'];
  */
 const ATMOSPHERE_GLYPHS = ['.', ':', "'", '`'];
 
+/**
+ * Coordinate space the octopus layout is generated in when it is painted into a terminal.
+ *
+ * The terminal renderer has its own character grid, so the geometry only needs one stable
+ * square coordinate space which the grid is then sampled from.
+ *
+ * @private helper of `asciiOctopusAvatarVisual`
+ */
+const TERMINAL_ASCII_OCTOPUS_LAYOUT_SIZE = DEFAULT_AVATAR_SIZE;
+
 /**
  * One 2D point used by the ASCII octopus helpers.
  *
@@ -42,12 +52,11 @@ type Point = {
 };
 
 /**
- * Character-grid metrics used by the ASCII renderer.
+ * Character-cell sampling grid shared by the canvas and the terminal ASCII renderers.
  *
  * @private helper of `asciiOctopusAvatarVisual`
  */
-type AsciiGridMetrics = {
-    readonly fontSize: number;
+type AsciiSampleGrid = {
     readonly cellWidth: number;
     readonly cellHeight: number;
     readonly columnCount: number;
@@ -56,6 +65,22 @@ type AsciiGridMetrics = {
     readonly offsetY: number;
 };
 
+/**
+ * Character-grid metrics used by the canvas ASCII renderer.
+ *
+ * @private helper of `asciiOctopusAvatarVisual`
+ */
+type AsciiGridMetrics = AsciiSampleGrid & {
+    readonly fontSize: number;
+};
+
+/**
+ * Resolved glyph of every sampled cell of one ASCII octopus frame.
+ *
+ * @private helper of `asciiOctopusAvatarVisual`
+ */
+type AsciiOctopusGlyphGrid = ReadonlyArray<ReadonlyArray<AsciiGlyphDescriptor | null>>;
+
 /**
  * One seeded eye definition used by the ASCII renderer.
  *
@@ -135,6 +160,13 @@ export const asciiOctopusAvatarVisual: AvatarVisualDefinition = {
         const staticRandom = createRandom('ascii-octopus-static');
         const gridMetrics = createAsciiGridMetrics(size, gridRandom);
         const layout = createAsciiOctopusLayout(size, timeMs, createRandom, staticRandom, interaction);
+        const glyphGrid = createAsciiOctopusGlyphGrid({
+            sampleGrid: gridMetrics,
+            layout,
+            palette,
+            cellRandom: createRandom('ascii-octopus-cells'),
+            timeMs,
+        });
 
         drawAvatarFrame(context, size, palette);
         drawAsciiBackdrop(context, size, palette, layout, timeMs);
@@ -144,31 +176,15 @@ export const asciiOctopusAvatarVisual: AvatarVisualDefinition = {
         context.textAlign = 'center';
         context.textBaseline = 'middle';
 
-        // The ASCII renderer samples the morphing octopus field on a low-resolution grid so the shape stays organic
-        // while the glyph layout remains deterministic for the same avatar input.
-        const cellRandom = createRandom('ascii-octopus-cells');
-
         for (let rowIndex = 0; rowIndex < gridMetrics.rowCount; rowIndex++) {
             for (let columnIndex = 0; columnIndex < gridMetrics.columnCount; columnIndex++) {
-                const point = {
-                    x: gridMetrics.offsetX + columnIndex * gridMetrics.cellWidth,
-                    y: gridMetrics.offsetY + rowIndex * gridMetrics.cellHeight,
-                };
-                const noise = cellRandom();
-                const glyphDescriptor = resolveAsciiGlyph({
-                    point,
-                    layout,
-                    palette,
-                    cellWidth: gridMetrics.cellWidth,
-                    cellHeight: gridMetrics.cellHeight,
-                    noise,
-                    timeMs,
-                });
+                const glyphDescriptor = glyphGrid[rowIndex]![columnIndex]!;
 
                 if (!glyphDescriptor) {
                     continue;
                 }
 
+                const point = resolveAsciiSampleGridPoint(gridMetrics, columnIndex, rowIndex);
                 context.fillStyle = glyphDescriptor.color;
                 context.fillText(glyphDescriptor.character, point.x, point.y);
             }
@@ -176,8 +192,114 @@ export const asciiOctopusAvatarVisual: AvatarVisualDefinition = {
 
         context.restore();
     },
+    renderTerminalText({ columns, rows, palette, createRandom, timeMs, interaction }) {
+        const staticRandom = createRandom('ascii-octopus-static');
+        const layout = createAsciiOctopusLayout(
+            TERMINAL_ASCII_OCTOPUS_LAYOUT_SIZE,
+            timeMs,
+            createRandom,
+            staticRandom,
+            interaction,
+        );
+
+        return createAsciiOctopusGlyphGrid({
+            sampleGrid: createAsciiTerminalSampleGrid(columns, rows),
+            layout,
+            palette,
+            cellRandom: createRandom('ascii-octopus-cells'),
+            timeMs,
+        });
+    },
 };
 
+/**
+ * Resolves the geometry point sampled for one cell of the grid.
+ *
+ * @param sampleGrid Character-cell sampling grid.
+ * @param columnIndex Zero-based cell column.
+ * @param rowIndex Zero-based cell row.
+ * @returns Sampled point in the octopus coordinate space.
+ *
+ * @private helper of `asciiOctopusAvatarVisual`
+ */
+function resolveAsciiSampleGridPoint(sampleGrid: AsciiSampleGrid, columnIndex: number, rowIndex: number): Point {
+    return {
+        x: sampleGrid.offsetX + columnIndex * sampleGrid.cellWidth,
+        y: sampleGrid.offsetY + rowIndex * sampleGrid.cellHeight,
+    };
+}
+
+/**
+ * Builds the sampling grid used when the octopus is painted straight into terminal character cells.
+ *
+ * @param columns Available terminal columns.
+ * @param rows Available terminal rows.
+ * @returns Character-cell sampling grid covering the whole octopus coordinate space.
+ *
+ * @private helper of `asciiOctopusAvatarVisual`
+ */
+function createAsciiTerminalSampleGrid(columns: number, rows: number): AsciiSampleGrid {
+    const cellWidth = TERMINAL_ASCII_OCTOPUS_LAYOUT_SIZE / columns;
+    const cellHeight = TERMINAL_ASCII_OCTOPUS_LAYOUT_SIZE / rows;
+
+    return {
+        cellWidth,
+        cellHeight,
+        columnCount: columns,
+        rowCount: rows,
+        offsetX: cellWidth / 2,
+        offsetY: cellHeight / 2,
+    };
+}
+
+/**
+ * Samples the morphing octopus field into one deterministic grid of ASCII glyphs.
+ *
+ * The field is sampled on a low-resolution grid so the shape stays organic while the glyph
+ * layout remains deterministic for the same avatar input. Both the canvas visual and the
+ * terminal visual share this single sampling pass so they always describe the same octopus.
+ *
+ * @param options Sampling grid, prepared octopus layout, palette, per-cell noise, and animation time.
+ * @returns Resolved glyph of every sampled cell, where `null` means an empty cell.
+ *
+ * @private helper of `asciiOctopusAvatarVisual`
+ */
+function createAsciiOctopusGlyphGrid(options: {
+    sampleGrid: AsciiSampleGrid;
+    layout: AsciiOctopusLayout;
+    palette: AvatarPalette;
+    cellRandom: () => number;
+    timeMs: number;
+}): AsciiOctopusGlyphGrid {
+    const { sampleGrid, layout, palette, cellRandom, timeMs } = options;
+    const glyphGrid: Array<Array<AsciiGlyphDescriptor | null>> = [];
+
+    for (let rowIndex = 0; rowIndex < sampleGrid.rowCount; rowIndex++) {
+        const glyphRow: Array<AsciiGlyphDescriptor | null> = [];
+
+        for (let columnIndex = 0; columnIndex < sampleGrid.columnCount; columnIndex++) {
+            const point = resolveAsciiSampleGridPoint(sampleGrid, columnIndex, rowIndex);
+            const noise = cellRandom();
+
+            glyphRow.push(
+                resolveAsciiGlyph({
+                    point,
+                    layout,
+                    palette,
+                    cellWidth: sampleGrid.cellWidth,
+                    cellHeight: sampleGrid.cellHeight,
+                    noise,
+                    timeMs,
+                }),
+            );
+        }
+
+        glyphGrid.push(glyphRow);
+    }
+
+    return glyphGrid;
+}
+
 /**
  * Draws the dark terminal-like glow behind the ASCII octopus.
  *

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

@@ -36,29 +36,23 @@ export type BookParameter = {
 
 /**
  * Capability of the agent
- * This is parsed from commitments like USE BROWSER, USE SEARCH ENGINE, KNOWLEDGE, etc.
+ * This is parsed from commitments like USE CALENDAR, USE PROJECT, KNOWLEDGE, etc.
  */
 export type AgentCapability = {
     /**
      * The type of the capability
      */
     type:
-        | 'browser'
-        | 'search-engine'
         | 'knowledge'
-        | 'timeout'
-        | 'time'
         | 'user-location'
         | 'inheritance'
         | 'import'
         | 'image-generator'
         | 'team'
-        | 'email'
         | 'popup'
         | 'privacy'
         | 'project'
-        | 'calendar'
-        | 'wallet';
+        | 'calendar';
 
     /**
      * The label to display for this capability
@@ -160,7 +154,7 @@ export type AgentBasicInformation = {
 
     /**
      * Capabilities of the agent
-     * This is parsed from commitments like USE BROWSER, USE SEARCH ENGINE, KNOWLEDGE, etc.
+     * This is parsed from commitments like USE CALENDAR, USE PROJECT, KNOWLEDGE, etc.
      */
     capabilities: Array<AgentCapability>;
 

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

@@ -1,5 +1,6 @@
 import type { ParsedCommitment } from '../../commitments/_base/ParsedCommitment';
 import type { string_agent_name } from '../../types/string_agent_name';
+import type { ParsedUnknownCommitment } from './ParsedUnknownCommitment';
 
 /**
  * Result of parsing agent source for commitments
@@ -22,6 +23,11 @@ export type AgentSourceParseResult = {
      */
     commitments: ParsedCommitment[];
 
+    /**
+     * Uppercase commitment blocks whose types are not registered by Promptbook.
+     */
+    unknownCommitments: ParsedUnknownCommitment[];
+
     /**
      * Lines that are not commitments (for system message)
      */

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

@@ -0,0 +1,29 @@
+/**
+ * An uppercase Book commitment block whose keyword is not registered by Promptbook.
+ *
+ * Unknown commitments are retained as system-message context instead of being applied
+ * as executable commitments.
+ *
+ * @private internal type of `parseAgentSourceWithCommitments`
+ */
+export type ParsedUnknownCommitment = {
+    /**
+     * Uppercase unknown commitment type, for example `FOO` or `BAR BZZ`.
+     */
+    readonly type: string;
+
+    /**
+     * Original first line, retained for precise editor diagnostics.
+     */
+    readonly originalLine: string;
+
+    /**
+     * Line number in the agent source (1-based).
+     */
+    readonly lineNumber: number;
+
+    /**
+     * Complete unknown commitment block, including its keyword and continuation lines.
+     */
+    readonly source: string;
+};

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

@@ -46,8 +46,9 @@ export async function augmentAgentModelRequirementsFromSource(
     requirements = await importReferencedFiles(requirements);
     requirements = appendMcpServers(requirements, agentSource);
     requirements = appendNonCommitmentContent(requirements, parseResult);
+    requirements = appendExampleInteractions(requirements, parseResult);
 
-    return appendExampleInteractions(requirements, parseResult);
+    return appendUnknownCommitmentContent(requirements, parseResult);
 }
 
 /**
@@ -188,6 +189,42 @@ function appendNonCommitmentContent(
     return appendSystemMessageSection(requirements, nonCommitmentContent);
 }
 
+/**
+ * Appends unknown commitment blocks as final extra context without applying commitment side effects.
+ *
+ * @param requirements - Current requirements snapshot.
+ * @param parseResult - Parsed source including unknown commitment blocks.
+ * @returns Requirements with unknown commitment context appended at the end of the system message.
+ *
+ * @private internal utility of `augmentAgentModelRequirementsFromSource`
+ */
+function appendUnknownCommitmentContent(
+    requirements: AgentModelRequirements,
+    parseResult: ParsedAgentSourceWithCommitments,
+): AgentModelRequirements {
+    const unknownCommitmentContent = getUnknownCommitmentContent(parseResult);
+    if (!unknownCommitmentContent) {
+        return requirements;
+    }
+
+    return appendSystemMessageSection(requirements, unknownCommitmentContent);
+}
+
+/**
+ * Joins unknown commitment blocks into their final extra-context representation.
+ *
+ * @param parseResult - Parsed source including unknown commitment blocks.
+ * @returns Unknown commitment source blocks in their original order.
+ *
+ * @private internal utility of `appendUnknownCommitmentContent`
+ */
+function getUnknownCommitmentContent(parseResult: ParsedAgentSourceWithCommitments): string {
+    return parseResult.unknownCommitments
+        .map((commitment) => commitment.source)
+        .filter(Boolean)
+        .join('\n\n');
+}
+
 /**
  * Collects plain-text lines that were not parsed as commitments and should still become part of the final system message.
  *

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

@@ -19,13 +19,6 @@ const OVERWRITTEN_COMMITMENT_GROUP_BY_TYPE = new Map<BookCommitment, 'GOAL'>([
     ['GOALS', 'GOAL'],
 ]);
 
-/**
- * Legacy commitments that should be parsed for compatibility but ignored by the model-requirements pipeline.
- *
- * @private internal constant of `filterCommitmentsForAgentModelRequirements`
- */
-const IGNORED_COMMITMENT_TYPES = new Set<BookCommitment>(['WALLET', 'WALLETS']);
-
 /**
  * Applies the commitment filtering rules used before commitment definitions are executed.
  *
@@ -84,10 +77,6 @@ function filterDeletedCommitments(commitments: ReadonlyArray<ParsedCommitment>):
     const filteredCommitments: ParsedCommitment[] = [];
 
     for (const commitment of commitments) {
-        if (isIgnoredCommitmentType(commitment.type)) {
-            continue;
-        }
-
         if (!isDeleteCommitmentType(commitment.type)) {
             filteredCommitments.push(commitment);
             continue;
@@ -126,18 +115,6 @@ function isDeleteCommitmentType(commitmentType: ParsedCommitment['type']): boole
     return DELETE_COMMITMENT_TYPES.has(commitmentType);
 }
 
-/**
- * Checks whether a parsed commitment is intentionally ignored by the current model compiler.
- *
- * @param commitmentType - Commitment type to check.
- * @returns `true` when the commitment should not affect model requirements.
- *
- * @private internal utility of `filterDeletedCommitments`
- */
-function isIgnoredCommitmentType(commitmentType: ParsedCommitment['type']): boolean {
-    return IGNORED_COMMITMENT_TYPES.has(commitmentType);
-}
-
 /**
  * Extracts normalized parameter names used for DELETE-like invalidation matching.
  *

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/getBookCommitmentLineType.ts

@@ -0,0 +1,36 @@
+/**
+ * Pattern shared by Book parsing and editor highlighting for a commitment-like line.
+ *
+ * A Book commitment keyword consists of one or more all-uppercase words with at least
+ * two characters each. This deliberately mirrors the Book editor syntax rule so an
+ * unknown keyword starts a new source block everywhere it is interpreted.
+ *
+ * @private internal constant of `getBookCommitmentLineType`
+ */
+const BOOK_COMMITMENT_LINE_TYPE_REGEX = /^\s*(?<type>[A-Z][A-Z0-9]+(?:\s+[A-Z][A-Z0-9]+)*)(?=\s|$)/;
+
+/**
+ * Creates the regex used to recognize the uppercase commitment type at the beginning of a Book line.
+ *
+ * A fresh regular expression keeps Monaco tokenizer state isolated from parser calls.
+ *
+ * @returns Regular expression matching one Book commitment-like line.
+ *
+ * @private internal utility of Book parsing and `<BookEditor/>`
+ */
+export function createBookCommitmentLineTypeRegex(): RegExp {
+    return new RegExp(BOOK_COMMITMENT_LINE_TYPE_REGEX.source);
+}
+
+/**
+ * Extracts the uppercase commitment type from a Book line, including types not registered by Promptbook.
+ *
+ * @param line - One raw Book source line.
+ * @returns Matched commitment type or `null` when the line does not begin with commitment syntax.
+ *
+ * @private internal utility of Book parsing and `<BookEditor/>`
+ */
+export function getBookCommitmentLineType(line: string): string | null {
+    const match = BOOK_COMMITMENT_LINE_TYPE_REGEX.exec(line);
+    return match?.groups?.type || null;
+}

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',