@promptbook/cli 0.114.0-3 → 0.114.0-31

package/src/avatars/renderAvatarVisualTerminalText.ts

@@ -0,0 +1,249 @@
+import type { string_color } from '../types/string_person_fullname';
+import type { AsciiArtColorDepth } from '../utils/ascii-art/convertImageDataToAsciiArt';
+import { DEFAULT_ALPHA_THRESHOLD } from '../utils/ascii-art/convertImageDataToAsciiArt';
+import type { AnsiRgbColor } from '../utils/ascii-art/createAnsiColorCode';
+import { ANSI_RESET, createAnsiForegroundColorCode } from '../utils/ascii-art/createAnsiColorCode';
+import { Color } from '../utils/color/Color';
+import { createIdleAvatarInteractionState } from './avatarInteractionUtils';
+import type { ResolvedAvatarRenderDefinition } from './renderAvatarVisual';
+import { resolveAvatarRenderDefinition } from './renderAvatarVisual';
+import type { AvatarDefinition } from './types/AvatarDefinition';
+import type {
+    AvatarSurfaceStyle,
+    AvatarVisualId,
+    AvatarVisualTerminalTextCell,
+    AvatarVisualTerminalTextGrid,
+} from './types/AvatarVisualDefinition';
+
+// Note: [💞] Ignore a discrepancy between file name and entity name
+
+/**
+ * Height of one terminal character cell relative to its width.
+ *
+ * Terminal fonts are roughly twice as tall as they are wide, so a square avatar needs
+ * twice as many columns as rows to keep its proportions.
+ *
+ * @private within the repository
+ */
+const TERMINAL_CHARACTER_CELL_ASPECT_RATIO = 2;
+
+/**
+ * Options shared by the terminal-text avatar renderers.
+ *
+ * @private within the repository
+ */
+export type RenderAvatarVisualTerminalTextOptions = {
+    /**
+     * Stable visual identity of the rendered agent avatar.
+     */
+    readonly avatarDefinition: AvatarDefinition;
+
+    /**
+     * Built-in avatar visual to render, the same one used on the website.
+     */
+    readonly visualId: AvatarVisualId;
+
+    /**
+     * Surface used to derive the avatar palette.
+     *
+     * @default 'framed'
+     */
+    readonly surface?: AvatarSurfaceStyle;
+
+    /**
+     * Output width in terminal character cells.
+     */
+    readonly columns: number;
+
+    /**
+     * Output height in terminal character cells.
+     */
+    readonly rows: number;
+
+    /**
+     * Animation timestamp for animated visuals.
+     */
+    readonly timeMs: number;
+
+    /**
+     * Optional stable render data reused across frames.
+     */
+    readonly resolvedAvatarRenderDefinition?: ResolvedAvatarRenderDefinition;
+};
+
+/**
+ * Options for `renderAvatarVisualTerminalTextLines`.
+ *
+ * @private within the repository
+ */
+export type RenderAvatarVisualTerminalTextLinesOptions = RenderAvatarVisualTerminalTextOptions & {
+    /**
+     * Color depth of the emitted ANSI escape codes.
+     *
+     * @default 'TRUE_COLOR'
+     */
+    readonly colorDepth?: AsciiArtColorDepth;
+};
+
+/**
+ * Renders one frame of a character-based avatar visual straight into terminal character cells.
+ *
+ * Visuals which are themselves made of characters, for example `AsciiOctopus`, lose their identity
+ * when they are rasterized onto a canvas and converted back into half-block ASCII art - every glyph
+ * is averaged away into a colored blob. Such visuals expose `renderTerminalText`, which paints the
+ * terminal grid directly and is used instead of the raster pipeline.
+ *
+ * The square avatar is centered inside the requested grid the same way `renderAvatarVisualAsciiArt`
+ * centers the avatar canvas inside a wider terminal frame.
+ *
+ * @param options Avatar identity, visual selection, and output grid size.
+ * @returns Grid of `rows` rows of `columns` cells, or `null` when the visual has no terminal renderer.
+ *
+ * @private within the repository
+ */
+export function renderAvatarVisualTerminalTextGrid(
+    options: RenderAvatarVisualTerminalTextOptions,
+): AvatarVisualTerminalTextGrid | null {
+    const resolvedRenderDefinition =
+        options.resolvedAvatarRenderDefinition ||
+        resolveAvatarRenderDefinition({
+            avatarDefinition: options.avatarDefinition,
+            visualId: options.visualId,
+            surface: options.surface,
+        });
+    const { renderTerminalText } = resolvedRenderDefinition.avatarVisual;
+
+    if (renderTerminalText === undefined) {
+        return null;
+    }
+
+    const avatarColumnCount = Math.min(options.columns, options.rows * TERMINAL_CHARACTER_CELL_ASPECT_RATIO);
+    const avatarRowCount = Math.min(options.rows, Math.round(options.columns / TERMINAL_CHARACTER_CELL_ASPECT_RATIO));
+
+    if (avatarColumnCount <= 0 || avatarRowCount <= 0) {
+        return null;
+    }
+
+    const avatarGrid = renderTerminalText({
+        columns: avatarColumnCount,
+        rows: avatarRowCount,
+        timeMs: options.timeMs,
+        avatarDefinition: resolvedRenderDefinition.avatarDefinition,
+        palette: resolvedRenderDefinition.palette,
+        createRandom: resolvedRenderDefinition.createRandom,
+        interaction: createIdleAvatarInteractionState(),
+    });
+
+    return centerAvatarVisualTerminalTextGrid(avatarGrid, options.columns, options.rows);
+}
+
+/**
+ * Renders one frame of a character-based avatar visual into ANSI-colored terminal lines.
+ *
+ * @param options Avatar identity, visual selection, output grid size, and ANSI color depth.
+ * @returns One ANSI-colored string per output row, or `null` when the visual has no terminal renderer.
+ *
+ * @private within the repository
+ */
+export function renderAvatarVisualTerminalTextLines(
+    options: RenderAvatarVisualTerminalTextLinesOptions,
+): ReadonlyArray<string> | null {
+    const terminalTextGrid = renderAvatarVisualTerminalTextGrid(options);
+
+    if (terminalTextGrid === null) {
+        return null;
+    }
+
+    return terminalTextGrid.map((terminalTextRow) =>
+        buildAvatarVisualTerminalTextLine(terminalTextRow, options.colorDepth || 'TRUE_COLOR'),
+    );
+}
+
+/**
+ * Converts one avatar cell color into the opaque terminal color it is painted with.
+ *
+ * Terminal cells cannot be blended, so the cell alpha is composited onto the dark terminal
+ * background and fully transparent cells keep the terminal background instead.
+ *
+ * @param color Cell color as a CSS color string, optionally with an alpha channel.
+ * @returns Opaque terminal color or `null` when the cell should stay empty.
+ *
+ * @private helper of `renderAvatarVisualTerminalTextLines`
+ */
+function resolveAvatarVisualTerminalTextColor(color: string_color): AnsiRgbColor | null {
+    const parsedColor = Color.fromSafe(color);
+
+    if (parsedColor.alpha < DEFAULT_ALPHA_THRESHOLD) {
+        return null;
+    }
+
+    const opacity = parsedColor.alpha / 255;
+
+    return {
+        red: Math.round(parsedColor.red * opacity),
+        green: Math.round(parsedColor.green * opacity),
+        blue: Math.round(parsedColor.blue * opacity),
+    };
+}
+
+/**
+ * Places the square avatar grid into the center of the requested terminal grid.
+ *
+ * @private helper of `renderAvatarVisualTerminalTextGrid`
+ */
+function centerAvatarVisualTerminalTextGrid(
+    avatarGrid: AvatarVisualTerminalTextGrid,
+    columns: number,
+    rows: number,
+): AvatarVisualTerminalTextGrid {
+    const avatarRowCount = avatarGrid.length;
+    const avatarColumnCount = avatarGrid[0]?.length || 0;
+    const leftCellCount = Math.floor((columns - avatarColumnCount) / 2);
+    const topRowCount = Math.floor((rows - avatarRowCount) / 2);
+
+    return Array.from({ length: rows }, (_, rowIndex) => {
+        const avatarRow = avatarGrid[rowIndex - topRowCount];
+
+        return Array.from({ length: columns }, (__, columnIndex) => avatarRow?.[columnIndex - leftCellCount] || null);
+    });
+}
+
+/**
+ * Builds one ANSI-colored terminal line from resolved character cells.
+ *
+ * @private helper of `renderAvatarVisualTerminalTextLines`
+ */
+function buildAvatarVisualTerminalTextLine(
+    terminalTextRow: ReadonlyArray<AvatarVisualTerminalTextCell | null>,
+    colorDepth: AsciiArtColorDepth,
+): string {
+    let line = '';
+    let currentForegroundCode: string | undefined = undefined;
+
+    for (const terminalTextCell of terminalTextRow) {
+        const cellColor =
+            terminalTextCell === null ? null : resolveAvatarVisualTerminalTextColor(terminalTextCell.color);
+        const nextForegroundCode =
+            cellColor === null ? undefined : createAnsiForegroundColorCode(cellColor, colorDepth);
+
+        if (nextForegroundCode !== currentForegroundCode) {
+            // Note: A reset is required whenever a previously set color must be cleared,
+            //       otherwise a stale color would bleed into the following empty cells.
+            if (nextForegroundCode === undefined) {
+                line += ANSI_RESET;
+            } else {
+                line += nextForegroundCode;
+            }
+
+            currentForegroundCode = nextForegroundCode;
+        }
+
+        line += cellColor === null || terminalTextCell === null ? ' ' : terminalTextCell.character;
+    }
+
+    if (currentForegroundCode !== undefined) {
+        line += ANSI_RESET;
+    }
+
+    return line;
+}

package/src/avatars/types/AvatarVisualDefinition.ts

@@ -93,6 +93,57 @@ export type AvatarVisualRenderContext = {
  */
 export type AvatarVisual = (context: AvatarVisualRenderContext) => void;
 
+/**
+ * One painted character cell of a terminal-text avatar frame.
+ *
+ * @private shared contract for the avatar rendering system
+ */
+export type AvatarVisualTerminalTextCell = {
+    /**
+     * Single character painted in the cell.
+     */
+    readonly character: string;
+
+    /**
+     * Color of the character as a CSS color string, optionally with an alpha channel.
+     */
+    readonly color: string_color;
+};
+
+/**
+ * One rendered terminal-text avatar frame as a grid of character cells.
+ *
+ * Rows are ordered top to bottom, cells left to right, and `null` leaves the terminal background visible.
+ *
+ * @private shared contract for the avatar rendering system
+ */
+export type AvatarVisualTerminalTextGrid = ReadonlyArray<ReadonlyArray<AvatarVisualTerminalTextCell | null>>;
+
+/**
+ * Rendering context forwarded to a terminal-text avatar visual.
+ *
+ * Unlike `AvatarVisualRenderContext` this carries no canvas, because the visual paints
+ * character cells of a fixed terminal grid instead of pixels.
+ *
+ * @private shared contract for the avatar rendering system
+ */
+export type AvatarVisualTerminalTextRenderContext = {
+    readonly columns: number;
+    readonly rows: number;
+    readonly timeMs: number;
+    readonly avatarDefinition: AvatarDefinition;
+    readonly palette: AvatarPalette;
+    readonly createRandom: (salt: string) => () => number;
+    readonly interaction: AvatarInteractionState;
+};
+
+/**
+ * Signature of one terminal-text avatar visual renderer.
+ *
+ * @private shared contract for the avatar rendering system
+ */
+export type AvatarVisualTerminalText = (context: AvatarVisualTerminalTextRenderContext) => AvatarVisualTerminalTextGrid;
+
 /**
  * Metadata and renderer for one built-in avatar visual.
  *
@@ -105,6 +156,15 @@ export type AvatarVisualDefinition = {
     readonly isAnimated: boolean;
     readonly supportsPointerTracking?: boolean;
     readonly render: AvatarVisual;
+
+    /**
+     * Optional native terminal renderer of visuals which are themselves made of characters.
+     *
+     * Character-based visuals lose their identity when they are rasterized onto a canvas and
+     * converted back into half-block ASCII art, so they paint the terminal character grid directly.
+     * Visuals without this renderer are rasterized through `renderAvatarVisualAsciiArt` instead.
+     */
+    readonly renderTerminalText?: AvatarVisualTerminalText;
 };
 
 /**

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.
  *