@promptbook/cli 0.112.0-98 → 0.112.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/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/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';
+}

package/src/book-3.0/CliAgent.ts

@@ -0,0 +1,252 @@
+import { mkdir, writeFile } from 'fs/promises';
+import { dirname } from 'path';
+import { executeAgentChatTurn } from '../../scripts/run-agent-chat/executeAgentChatTurn';
+import { NotAllowed } from '../errors/NotAllowed';
+import { resolvePromptbookTemporaryPath } from '../utils/filesystem/promptbookTemporaryPath';
+import { spaceTrim } from '../utils/organization/spaceTrim';
+import type { BookNodeAgentSourceOptions, ResolvedBookNodeAgentSource } from './BookNodeAgentSource';
+import { resolveBookNodeAgentSource } from './BookNodeAgentSource';
+import {
+    CLI_AGENT_HARNESS_NAMES,
+    CLI_AGENT_THINKING_LEVEL_VALUES,
+    PTBK_HARNESS_ENV,
+    PTBK_MODEL_ENV,
+    PTBK_THINKING_LEVEL_ENV,
+} from './cliAgentEnv';
+
+/**
+ * CLI harness names supported by `ptbk agent exec`.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export type CliAgentHarness = (typeof CLI_AGENT_HARNESS_NAMES)[number];
+
+/**
+ * Thinking levels supported by CLI coding harnesses.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export type CliAgentThinkingLevel = (typeof CLI_AGENT_THINKING_LEVEL_VALUES)[number];
+
+/**
+ * Per-run CLI options exposed by `CliAgent`.
+ *
+ * `noUi` defaults to `true` so command output stays suitable for JavaScript callers.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export type CliAgentRunOptions = {
+    readonly allowCredits?: boolean;
+    readonly context?: string;
+    readonly harness?: CliAgentHarness;
+    readonly isVerbose?: boolean;
+    readonly model?: string;
+    readonly noUi?: boolean;
+    readonly thinkingLevel?: CliAgentThinkingLevel;
+};
+
+/**
+ * Constructor options for `CliAgent`.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export type CliAgentOptions = BookNodeAgentSourceOptions & CliAgentRunOptions;
+
+/**
+ * Default non-interactive mode used by `CliAgent`.
+ *
+ * @private internal constant of `CliAgent`
+ */
+const DEFAULT_CLI_AGENT_IS_NO_UI = true;
+
+/**
+ * Lightweight JavaScript wrapper around the Promptbook agent execution pipeline.
+ *
+ * It uses the same harnesses and execution path as `ptbk agent exec`, running the runner
+ * in-process instead of spawning a separate CLI process.
+ *
+ * When no `harness` is provided in the constructor or per-run options, `CliAgent` falls back
+ * to the `PTBK_HARNESS` environment variable, mirroring `ptbk agent exec` behavior.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export class CliAgent {
+    private temporaryAgentPath: string | null = null;
+
+    public constructor(private readonly options: CliAgentOptions) {}
+
+    /**
+     * Runs one non-interactive agent turn through the selected harness.
+     *
+     * @param message - User message sent to the agent.
+     * @param options - Optional per-run overrides.
+     * @returns Final agent answer.
+     */
+    public async run(message: string, options: CliAgentRunOptions = {}): Promise<string> {
+        const normalizedMessage = message.trim();
+
+        if (!normalizedMessage) {
+            throw new NotAllowed('Pass a non-empty message to `CliAgent.run(...)`.');
+        }
+
+        const resolvedSource = await resolveBookNodeAgentSource(this.options);
+        const agentPath = await this.resolveExecutableAgentPath(resolvedSource);
+        const mergedOptions = mergeCliAgentRunOptions(this.options, options);
+
+        const harness = mergedOptions.harness ?? resolveCliAgentHarnessFromEnv();
+
+        if (!harness) {
+            throw new NotAllowed(
+                spaceTrim(`
+                    No harness specified for \`CliAgent\`. Pass \`harness\` in the constructor options or per-run options,
+                    or set the \`${PTBK_HARNESS_ENV}\` environment variable.
+
+                    Available harnesses: ${CLI_AGENT_HARNESS_NAMES.join(', ')}
+
+                    Example: \`PTBK_HARNESS=claude-code\`
+                `),
+            );
+        }
+
+        const result = await executeAgentChatTurn({
+            agentPath,
+            messages: [{ sender: 'USER', content: normalizedMessage }],
+            agentName: harness,
+            model: mergedOptions.model ?? process.env[PTBK_MODEL_ENV],
+            noUi: mergedOptions.noUi ?? DEFAULT_CLI_AGENT_IS_NO_UI,
+            thinkingLevel: mergedOptions.thinkingLevel ?? resolveCliAgentThinkingLevelFromEnv(),
+            allowCredits: mergedOptions.allowCredits ?? false,
+            isVerbose: mergedOptions.isVerbose ?? false,
+            context: mergedOptions.context,
+            currentWorkingDirectory: resolvedSource.currentWorkingDirectory,
+        });
+
+        return result.answer;
+    }
+
+    /**
+     * Resolves the agent path passed to the runner, materializing one temporary `.book` file when needed.
+     *
+     * @private internal utility of `CliAgent`
+     */
+    private async resolveExecutableAgentPath(resolvedSource: ResolvedBookNodeAgentSource): Promise<string> {
+        if (resolvedSource.agentPath) {
+            return resolvedSource.agentPath;
+        }
+
+        if (!this.temporaryAgentPath) {
+            this.temporaryAgentPath = createCliAgentTemporaryBookPath(resolvedSource);
+
+            await mkdir(dirname(this.temporaryAgentPath), { recursive: true });
+            await writeFile(this.temporaryAgentPath, normalizeCliAgentBookSource(resolvedSource.agentSource), 'utf-8');
+        }
+
+        return this.temporaryAgentPath;
+    }
+}
+
+/**
+ * Merges constructor defaults with per-run overrides.
+ *
+ * @private internal utility of `CliAgent`
+ */
+function mergeCliAgentRunOptions(defaults: CliAgentRunOptions, overrides: CliAgentRunOptions): CliAgentRunOptions {
+    return {
+        allowCredits: overrides.allowCredits ?? defaults.allowCredits,
+        context: overrides.context ?? defaults.context,
+        harness: overrides.harness ?? defaults.harness,
+        isVerbose: overrides.isVerbose ?? defaults.isVerbose,
+        model: overrides.model ?? defaults.model,
+        noUi: overrides.noUi ?? defaults.noUi,
+        thinkingLevel: overrides.thinkingLevel ?? defaults.thinkingLevel,
+    };
+}
+
+/**
+ * Reads and validates the harness name from the `PTBK_HARNESS` environment variable.
+ *
+ * @private internal utility of `CliAgent`
+ */
+function resolveCliAgentHarnessFromEnv(): CliAgentHarness | undefined {
+    const envValue = process.env[PTBK_HARNESS_ENV];
+
+    if (!envValue) {
+        return undefined;
+    }
+
+    if (!(CLI_AGENT_HARNESS_NAMES as ReadonlyArray<string>).includes(envValue)) {
+        throw new NotAllowed(
+            spaceTrim(`
+                Invalid value for \`${PTBK_HARNESS_ENV}\` environment variable: \`${envValue}\`
+
+                Must be one of: ${CLI_AGENT_HARNESS_NAMES.join(', ')}
+            `),
+        );
+    }
+
+    return envValue as CliAgentHarness;
+}
+
+/**
+ * Reads and validates the thinking level from the `PTBK_THINKING_LEVEL` environment variable.
+ *
+ * @private internal utility of `CliAgent`
+ */
+function resolveCliAgentThinkingLevelFromEnv(): CliAgentThinkingLevel | undefined {
+    const envValue = process.env[PTBK_THINKING_LEVEL_ENV];
+
+    if (!envValue) {
+        return undefined;
+    }
+
+    if (!(CLI_AGENT_THINKING_LEVEL_VALUES as ReadonlyArray<string>).includes(envValue)) {
+        throw new NotAllowed(
+            spaceTrim(`
+                Invalid value for \`${PTBK_THINKING_LEVEL_ENV}\` environment variable: \`${envValue}\`
+
+                Must be one of: ${CLI_AGENT_THINKING_LEVEL_VALUES.join(', ')}
+            `),
+        );
+    }
+
+    return envValue as CliAgentThinkingLevel;
+}
+
+/**
+ * Creates the stable temporary path used when `CliAgent` is initialized from in-memory Book source.
+ *
+ * @private internal utility of `CliAgent`
+ */
+function createCliAgentTemporaryBookPath(resolvedSource: ResolvedBookNodeAgentSource): string {
+    const safeAgentName = normalizeCliAgentFileSegment(resolvedSource.agentName);
+    const uniqueSuffix = `${Date.now().toString(36)}-${process.pid.toString(36)}`;
+
+    return resolvePromptbookTemporaryPath(
+        resolvedSource.currentWorkingDirectory,
+        'book-3.0',
+        'cli-agent',
+        `${safeAgentName || 'agent'}-${uniqueSuffix}.book`,
+    );
+}
+
+/**
+ * Keeps in-memory Book source readable when persisted for the runner.
+ *
+ * @private internal utility of `CliAgent`
+ */
+function normalizeCliAgentBookSource(agentSource: string): string {
+    return agentSource.endsWith('\n') ? agentSource : `${agentSource}\n`;
+}
+
+/**
+ * Normalizes one filename segment used in temporary agent-book paths.
+ *
+ * @private internal utility of `CliAgent`
+ */
+function normalizeCliAgentFileSegment(value: string): string {
+    return value
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9._-]+/gu, '-')
+        .replace(/^[._-]+|[._-]+$/gu, '');
+}