@promptbook/cli 0.112.0-99 → 0.113.0-0

package/src/avatars/visuals/octopus3dAvatarVisual.ts

@@ -55,6 +55,53 @@ const LIGHT_DIRECTION: Point3D = normalizeVector3({
     z: 0.94,
 });
 
+/**
+ * Per-avatar stable state derived once from the seeded random factory and reused across frames.
+ *
+ * @private helper of `octopus3dAvatarVisual`
+ */
+type Octopus3dStableState = {
+    readonly morphologyProfile: Octopus3MorphologyProfile;
+    readonly animationPhase: number;
+    readonly leftEyePhaseOffset: number;
+    readonly rightEyePhaseOffset: number;
+};
+
+/**
+ * Cache keyed by the `createRandom` factory reference (stable per mounted `<Avatar/>`).
+ *
+ * @private helper of `octopus3dAvatarVisual`
+ */
+const octopus3dStableStateCache = new WeakMap<(salt: string) => () => number, Octopus3dStableState>();
+
+/**
+ * Returns the stable per-avatar state, computing it on first access and caching for subsequent frames.
+ *
+ * @private helper of `octopus3dAvatarVisual`
+ */
+function getOctopus3dStableState(createRandom: (salt: string) => () => number): Octopus3dStableState {
+    const cached = octopus3dStableStateCache.get(createRandom);
+
+    if (cached !== undefined) {
+        return cached;
+    }
+
+    const animationRandom = createRandom('octopus3d-animation-profile');
+    const eyeRandom = createRandom('octopus3d-eye-profile');
+    const leftEyePhaseOffset = eyeRandom() * 0.6;
+    const rightEyePhaseOffset = eyeRandom() * 0.6;
+    const state: Octopus3dStableState = {
+        morphologyProfile: createOctopus3MorphologyProfile(createRandom),
+        animationPhase: animationRandom() * Math.PI * 2,
+        leftEyePhaseOffset,
+        rightEyePhaseOffset,
+    };
+
+    octopus3dStableStateCache.set(createRandom, state);
+
+    return state;
+}
+
 /**
  * Proper 3D Octopus visual built from projected organic meshes and tentacles.
  *
@@ -67,10 +114,8 @@ export const octopus3dAvatarVisual: AvatarVisualDefinition = {
     isAnimated: true,
     supportsPointerTracking: true,
     render({ context, size, palette, createRandom, timeMs, interaction }) {
-        const morphologyProfile = createOctopus3MorphologyProfile(createRandom);
-        const animationRandom = createRandom('octopus3d-animation-profile');
-        const eyeRandom = createRandom('octopus3d-eye-profile');
-        const animationPhase = animationRandom() * Math.PI * 2;
+        const { morphologyProfile, animationPhase, leftEyePhaseOffset, rightEyePhaseOffset } =
+            getOctopus3dStableState(createRandom);
         const sceneCenterX = size * 0.5;
         const sceneCenterY = size * 0.56;
         const bob = Math.sin(timeMs / 920 + animationPhase) * size * 0.014;
@@ -201,7 +246,7 @@ export const octopus3dAvatarVisual: AvatarVisualDefinition = {
             size,
             palette,
             timeMs,
-            animationPhase + eyeRandom() * 0.6,
+            animationPhase + leftEyePhaseOffset,
             interaction,
             morphologyProfile.face.eyeStyle,
         );
@@ -228,7 +273,7 @@ export const octopus3dAvatarVisual: AvatarVisualDefinition = {
             size,
             palette,
             timeMs,
-            animationPhase + 0.7 + eyeRandom() * 0.6,
+            animationPhase + 0.7 + rightEyePhaseOffset,
             interaction,
             morphologyProfile.face.eyeStyle,
         );
@@ -334,6 +379,9 @@ function drawOctopus3dAtmosphere(
 /**
  * Draws the soft ground shadow below the octopus.
  *
+ * Uses a scaled radial gradient instead of `context.filter = 'blur()'` to approximate the
+ * blurry ellipse without triggering a costly software rasterization pass on every frame.
+ *
  * @private helper of `octopus3dAvatarVisual`
  */
 function drawOctopus3dShadow(
@@ -346,19 +394,23 @@ function drawOctopus3dShadow(
     },
     timeMs: number,
 ): void {
+    const cx = size * 0.5 + interaction.gazeX * size * 0.04;
+    const cy = size * 0.87 + Math.sin(timeMs / 920) * size * 0.008;
+    const rx = size * (0.18 + interaction.intensity * 0.02);
+    const ry = size * 0.06;
+
     context.save();
-    context.fillStyle = `${palette.shadow}66`;
-    context.filter = `blur(${size * 0.022}px)`;
+    context.translate(cx, cy);
+    context.scale(1, ry / rx);
+    const blurRadius = rx * 1.4;
+    const shadowGradient = context.createRadialGradient(0, 0, 0, 0, 0, blurRadius);
+    shadowGradient.addColorStop(0, `${palette.shadow}7a`);
+    shadowGradient.addColorStop(0.45, `${palette.shadow}44`);
+    shadowGradient.addColorStop(0.8, `${palette.shadow}1a`);
+    shadowGradient.addColorStop(1, `${palette.shadow}00`);
+    context.fillStyle = shadowGradient;
     context.beginPath();
-    context.ellipse(
-        size * 0.5 + interaction.gazeX * size * 0.04,
-        size * 0.87 + Math.sin(timeMs / 920) * size * 0.008,
-        size * (0.18 + interaction.intensity * 0.02),
-        size * 0.06,
-        0,
-        0,
-        Math.PI * 2,
-    );
+    context.arc(0, 0, blurRadius, 0, Math.PI * 2);
     context.fill();
     context.restore();
 }

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

@@ -4,6 +4,7 @@ import type { string_agent_url } from '../../types/string_agent_url';
 import type { string_fonts } from '../../types/string_markdown';
 import type { string_color } from '../../types/string_person_fullname';
 import type { string_url_image } from '../../types/string_url_image';
+import type { AgentVisibility } from './agentSourceVisibility';
 
 /**
  * Unified parameter representation that supports two different notations:
@@ -130,6 +131,7 @@ export type AgentBasicInformation = {
         font?: string_fonts;
         color?: string_color;
         voice?: string;
+        visibility?: AgentVisibility;
         [key: string]: string | undefined;
     };
 

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

@@ -0,0 +1,214 @@
+import { ParseError } from '../../errors/ParseError';
+import { spaceTrim } from '../../utils/organization/spaceTrim';
+import type { string_book } from './string_book';
+
+/**
+ * Supported visibility states for persisted agents.
+ *
+ * @public exported from `@promptbook/core`
+ */
+export const AGENT_VISIBILITY_VALUES = ['PRIVATE', 'UNLISTED', 'PUBLIC'] as const;
+
+/**
+ * Canonical visibility union for agents.
+ *
+ * @public exported from `@promptbook/core`
+ */
+export type AgentVisibility = (typeof AGENT_VISIBILITY_VALUES)[number];
+
+/**
+ * Fallback visibility used when no valid value is configured.
+ *
+ * @public exported from `@promptbook/core`
+ */
+export const DEFAULT_AGENT_VISIBILITY: AgentVisibility = 'UNLISTED';
+
+/**
+ * Matches a single-line `META VISIBILITY` commitment in book source.
+ */
+const META_VISIBILITY_LINE_PATTERN = /^(\s*)META\s+VISIBILITY\b([\s\S]*)$/iu;
+
+/**
+ * Returns `true` when the value is one of supported visibility states.
+ *
+ * @param value - Raw value to validate.
+ * @returns Whether the value is a valid `AgentVisibility`.
+ *
+ * @public exported from `@promptbook/core`
+ */
+export function isAgentVisibility(value: unknown): value is AgentVisibility {
+    return typeof value === 'string' && AGENT_VISIBILITY_VALUES.includes(value as AgentVisibility);
+}
+
+/**
+ * Normalizes raw visibility text into a supported value.
+ *
+ * @param value - Raw visibility value.
+ * @returns Normalized visibility, or `null` when invalid.
+ *
+ * @public exported from `@promptbook/core`
+ */
+export function normalizeAgentVisibility(value: unknown): AgentVisibility | null {
+    if (typeof value !== 'string') {
+        return null;
+    }
+
+    const normalized = value.trim().toUpperCase();
+    return isAgentVisibility(normalized) ? normalized : null;
+}
+
+/**
+ * Parses visibility from an unknown value with a safe fallback.
+ *
+ * @param value - Raw visibility value.
+ * @param fallback - Fallback when the value is invalid.
+ * @returns Parsed visibility.
+ *
+ * @public exported from `@promptbook/core`
+ */
+export function parseAgentVisibility(
+    value: unknown,
+    fallback: AgentVisibility = DEFAULT_AGENT_VISIBILITY,
+): AgentVisibility {
+    return normalizeAgentVisibility(value) ?? fallback;
+}
+
+/**
+ * Parses visibility and throws when the value is not supported.
+ *
+ * @param value - Raw visibility value.
+ * @param sourceLabel - Human-readable source used in the error message.
+ * @returns Parsed visibility.
+ *
+ * @public exported from `@promptbook/core`
+ */
+export function parseAgentVisibilityStrict(value: unknown, sourceLabel = 'visibility'): AgentVisibility {
+    const visibility = normalizeAgentVisibility(value);
+    if (visibility) {
+        return visibility;
+    }
+
+    throw new ParseError(
+        spaceTrim(`
+            Invalid ${sourceLabel}.
+
+            Value must be one of: ${AGENT_VISIBILITY_VALUES.map((allowedValue) => `\`${allowedValue}\``).join(', ')}.
+        `),
+    );
+}
+
+/**
+ * Extracts the last `META VISIBILITY` value from an agent source.
+ *
+ * @param agentSource - Raw book source.
+ * @param options - Strict parsing options.
+ * @returns Normalized visibility, or `null` when no commitment is present.
+ *
+ * @public exported from `@promptbook/core`
+ */
+export function parseAgentSourceVisibility(
+    agentSource: string_book,
+    options: { readonly isStrict?: boolean } = {},
+): AgentVisibility | null {
+    let visibilityContent: string | null = null;
+
+    for (const line of agentSource.split(/\r?\n/u)) {
+        const lineMatch = META_VISIBILITY_LINE_PATTERN.exec(line);
+        if (lineMatch) {
+            visibilityContent = lineMatch[2]!.trim();
+        }
+    }
+
+    if (visibilityContent === null) {
+        return null;
+    }
+
+    const visibility = normalizeAgentVisibility(visibilityContent);
+    if (visibility || !options.isStrict) {
+        return visibility;
+    }
+
+    return parseAgentVisibilityStrict(visibilityContent, '`META VISIBILITY` commitment');
+}
+
+/**
+ * Returns whether an agent should be listed publicly in anonymous views.
+ *
+ * @param visibility - Agent visibility to evaluate.
+ * @returns `true` for publicly listed agents.
+ *
+ * @public exported from `@promptbook/core`
+ */
+export function isPublicAgentVisibility(visibility: AgentVisibility | null | undefined): boolean {
+    return visibility === 'PUBLIC';
+}
+
+/**
+ * Returns the next visibility in UI rotation order.
+ *
+ * @param visibility - Current visibility.
+ * @returns Next visibility value.
+ *
+ * @public exported from `@promptbook/core`
+ */
+export function getNextAgentVisibility(visibility: AgentVisibility | null | undefined): AgentVisibility {
+    switch (visibility) {
+        case 'PRIVATE':
+            return 'UNLISTED';
+        case 'UNLISTED':
+            return 'PUBLIC';
+        case 'PUBLIC':
+        default:
+            return 'PRIVATE';
+    }
+}
+
+/**
+ * Inserts or replaces the `META VISIBILITY` commitment in a book source.
+ *
+ * @param agentSource - Raw book source.
+ * @param visibility - Visibility to persist.
+ * @returns Source with exactly one normalized `META VISIBILITY` line.
+ *
+ * @public exported from `@promptbook/core`
+ */
+export function setAgentSourceVisibility(agentSource: string_book, visibility: AgentVisibility): string_book {
+    const normalizedVisibility = parseAgentVisibilityStrict(visibility, '`META VISIBILITY` commitment');
+    const lines = agentSource.split(/\r?\n/u);
+    const nextLines: string[] = [];
+    let isVisibilityLineWritten = false;
+
+    for (const line of lines) {
+        const lineMatch = META_VISIBILITY_LINE_PATTERN.exec(line);
+        if (!lineMatch) {
+            nextLines.push(line);
+            continue;
+        }
+
+        if (isVisibilityLineWritten) {
+            continue;
+        }
+
+        nextLines.push(`${lineMatch[1] ?? ''}META VISIBILITY ${normalizedVisibility}`);
+        isVisibilityLineWritten = true;
+    }
+
+    if (!isVisibilityLineWritten) {
+        nextLines.splice(findMetaVisibilityInsertIndex(nextLines), 0, `META VISIBILITY ${normalizedVisibility}`);
+    }
+
+    return nextLines.join('\n') as string_book;
+}
+
+/**
+ * Finds the position after the first non-empty line, which is the agent title.
+ *
+ * @param lines - Source lines.
+ * @returns Insertion index for profile metadata.
+ */
+function findMetaVisibilityInsertIndex(lines: ReadonlyArray<string>): number {
+    const titleLineIndex = lines.findIndex((line) => line.trim().length > 0);
+    return titleLineIndex === -1 ? 0 : titleLineIndex + 1;
+}
+
+// Note: [💞] Ignore a discrepancy between file name and entity name

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

@@ -282,12 +282,28 @@ function collectExampleInteractionLines(
     const initialMessage = parseResult.commitments.find((commitment) => commitment.type === 'INITIAL MESSAGE')?.content;
 
     if (initialMessage) {
-        examples.push(`**Agent:**\n${initialMessage}`);
+        examples.push(
+            spaceTrim(
+                (block) => `
+                    **Agent:**
+                    ${block(initialMessage)}
+                `,
+            ),
+        );
     }
 
     if (samples && samples.length > 0) {
         for (const sample of samples) {
-            examples.push(`**User:** ${sample.question}\n\n**Agent:**\n${sample.answer}`);
+            examples.push(
+                spaceTrim(
+                    (block) => `
+                        **User:** ${block(String(sample.question))}
+
+                        **Agent:**
+                        ${block(sample.answer)}
+                    `,
+                ),
+            );
         }
     }
 

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

@@ -3,6 +3,7 @@ import { resolveAvatarVisualId } from '../../../avatars/visuals/avatarVisualRegi
 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';
 import type { ParseAgentSourceState } from './ParseAgentSourceState';
 
 /**
@@ -25,6 +26,7 @@ const META_COMMITMENT_APPLIERS: Readonly<Record<string, MetaCommitmentApplier |
     'META COLOR': applyMetaColorContent,
     'META FONT': applyMetaFontContent,
     'META VOICE': applyMetaVoiceContent,
+    'META VISIBILITY': applyMetaVisibilityContent,
 };
 
 /**
@@ -60,6 +62,11 @@ function applyGenericMetaCommitment(state: ParseAgentSourceState, content: strin
         return;
     }
 
+    if (metaTypeRaw.toUpperCase() === 'VISIBILITY') {
+        applyMetaVisibilityContent(state, metaValue);
+        return;
+    }
+
     const metaType = normalizeTo_camelCase(metaTypeRaw);
     state.meta[metaType] = metaValue;
 }
@@ -149,6 +156,16 @@ function applyMetaVoiceContent(state: ParseAgentSourceState, content: string): v
     state.meta.voice = spaceTrim(content);
 }
 
+/**
+ * Applies META VISIBILITY content into the normalized `meta.visibility` field.
+ */
+function applyMetaVisibilityContent(state: ParseAgentSourceState, content: string): void {
+    const visibility = normalizeAgentVisibility(content);
+    if (visibility) {
+        state.meta.visibility = visibility;
+    }
+}
+
 /**
  * Normalizes the separator in the content
  *

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

@@ -61,6 +61,7 @@ const PROFILE_COMMITMENT_TYPES = new Set([
     'META DESCRIPTION',
     'META DISCLAIMER',
     'META INPUT PLACEHOLDER',
+    'META VISIBILITY',
     'META COLOR',
     'META FONT',
     'META VOICE',

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

@@ -69,7 +69,13 @@ function removeLeadingTopLevelHeading(markdown: string): string {
  * @private internal utility of `createStandaloneBookLanguageMarkdown`
  */
 function renderDocumentationSection(title: string, documentation: string): string {
-    return `#### ${title}\n\n${removeLeadingTopLevelHeading(documentation)}`;
+    return spaceTrim(
+        (block) => `
+            #### ${title}
+
+            ${block(removeLeadingTopLevelHeading(documentation))}
+        `,
+    );
 }
 
 /**

package/src/book-3.0/Book.ts

@@ -215,7 +215,9 @@ function parseBookMessageHeader(line: string): Pick<BookMessageBlock, 'marker' |
  * @private internal utility of `Book`
  */
 function parseCommitmentHeader(line: string): Commitment | null {
-    const match = /^([A-Z][A-Z0-9]*(?: [A-Z0-9]+)*)(?:\s+(.*))?$/u.exec(line);
+    // Require at least 2 characters in the first keyword word to avoid treating common
+    // single-letter words (e.g. "V" in Czech, "I" or "A" in English) as commitment headers.
+    const match = /^([A-Z][A-Z0-9]+(?: [A-Z0-9]+)*)(?:\s+(.*))?$/u.exec(line);
     if (!match) {
         return null;
     }

package/src/book-3.0/BookNodeAgentSource.ts

@@ -0,0 +1,135 @@
+import { readFile } from 'fs/promises';
+import { dirname, resolve } from 'path';
+import type { string_book } from '../book-2.0/agent-source/string_book';
+import { assertsError } from '../errors/assertsError';
+import { NotAllowed } from '../errors/NotAllowed';
+import { NotFoundError } from '../errors/NotFoundError';
+import { spaceTrim } from '../utils/organization/spaceTrim';
+import { Book } from './Book';
+
+/**
+ * Book source value accepted by Node-backed Book agents.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export type BookNodeAgentSource = Book | string_book;
+
+/**
+ * Common source options shared by Node-backed Book agents.
+ *
+ * Provide either `agentPath` or `book`.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export type BookNodeAgentSourceOptions = {
+    readonly agentPath?: string;
+    readonly book?: string | BookNodeAgentSource;
+    readonly currentWorkingDirectory?: string;
+};
+
+/**
+ * Normalized source snapshot used internally by Node-backed Book agents.
+ *
+ * @private internal utility of `CliAgent` and `LiteAgent`
+ */
+export type ResolvedBookNodeAgentSource = {
+    readonly agentName: string;
+    readonly agentPath: string | null;
+    readonly agentSource: string_book;
+    readonly currentWorkingDirectory: string;
+    readonly sourceDirectoryPath: string;
+};
+
+/**
+ * Resolves shared Node-backed Book source options into one normalized source snapshot.
+ *
+ * @private internal utility of `CliAgent` and `LiteAgent`
+ */
+export async function resolveBookNodeAgentSource(
+    options: BookNodeAgentSourceOptions,
+): Promise<ResolvedBookNodeAgentSource> {
+    const hasAgentPath = typeof options.agentPath === 'string' && options.agentPath.trim().length > 0;
+    const hasBook = options.book !== undefined;
+
+    if (hasAgentPath === hasBook) {
+        throw new NotAllowed(
+            spaceTrim(`
+                Provide exactly one of \`agentPath\` or \`book\`.
+
+                These options are mutually exclusive because they define different source-resolution strategies.
+            `),
+        );
+    }
+
+    const currentWorkingDirectory = options.currentWorkingDirectory || process.cwd();
+
+    if (hasBook) {
+        const agentSource = normalizeBookNodeAgentSource(options.book!);
+
+        return {
+            agentName: resolveBookNodeAgentName(agentSource),
+            agentPath: null,
+            agentSource,
+            currentWorkingDirectory,
+            sourceDirectoryPath: currentWorkingDirectory,
+        };
+    }
+
+    const absoluteAgentPath = resolve(currentWorkingDirectory, options.agentPath!);
+    const agentSource = await readAgentSourceFile(absoluteAgentPath, options.agentPath!);
+
+    return {
+        agentName: resolveBookNodeAgentName(agentSource),
+        agentPath: absoluteAgentPath,
+        agentSource,
+        currentWorkingDirectory,
+        sourceDirectoryPath: dirname(absoluteAgentPath),
+    };
+}
+
+/**
+ * Normalizes one in-memory Book source into a persisted string.
+ *
+ * @private internal utility of `resolveBookNodeAgentSource`
+ */
+function normalizeBookNodeAgentSource(book: string | BookNodeAgentSource): string_book {
+    if (book instanceof Book) {
+        return book.stringify();
+    }
+
+    return (book.endsWith('\n') ? book : `${book}\n`) as string_book;
+}
+
+/**
+ * Reads one agent source file and wraps missing-file errors into Promptbook-branded errors.
+ *
+ * @private internal utility of `resolveBookNodeAgentSource`
+ */
+async function readAgentSourceFile(absoluteAgentPath: string, agentPathReference: string): Promise<string_book> {
+    try {
+        return (await readFile(absoluteAgentPath, 'utf-8')) as string_book;
+    } catch (error) {
+        assertsError(error);
+
+        if ((error as NodeJS.ErrnoException).code === 'ENOENT' || (error as NodeJS.ErrnoException).code === 'EISDIR') {
+            throw new NotFoundError(
+                spaceTrim(`
+                    Agent book \`${agentPathReference}\` was not found or is not a file.
+
+                    Pass a path to an existing \`.book\` file.
+                `),
+            );
+        }
+
+        throw error;
+    }
+}
+
+/**
+ * Resolves the display name used by Node-backed Book agents.
+ *
+ * @private internal utility of `resolveBookNodeAgentSource`
+ */
+function resolveBookNodeAgentName(agentSource: string_book): string {
+    return Book.parse(agentSource).agentName.trim() || 'Agent';
+}