@promptbook/cli 0.112.0-117 → 0.112.0-118

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

@@ -23,7 +23,7 @@ export type BookNodeAgentSource = Book | string_book;
  */
 export type BookNodeAgentSourceOptions = {
     readonly agentPath?: string;
-    readonly book?: BookNodeAgentSource;
+    readonly book?: string | BookNodeAgentSource;
     readonly currentWorkingDirectory?: string;
 };
 
@@ -92,7 +92,7 @@ export async function resolveBookNodeAgentSource(
  *
  * @private internal utility of `resolveBookNodeAgentSource`
  */
-function normalizeBookNodeAgentSource(book: BookNodeAgentSource): string_book {
+function normalizeBookNodeAgentSource(book: string | BookNodeAgentSource): string_book {
     if (book instanceof Book) {
         return book.stringify();
     }

package/src/book-3.0/CliAgent.ts

@@ -3,22 +3,30 @@ 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 = 'openai-codex' | 'github-copilot' | 'cline' | 'claude-code' | 'opencode' | 'gemini';
+export type CliAgentHarness = (typeof CLI_AGENT_HARNESS_NAMES)[number];
 
 /**
  * Thinking levels supported by CLI coding harnesses.
  *
  * @public exported from `@promptbook/node`
  */
-export type CliAgentThinkingLevel = 'low' | 'medium' | 'high' | 'xhigh';
+export type CliAgentThinkingLevel = (typeof CLI_AGENT_THINKING_LEVEL_VALUES)[number];
 
 /**
  * Per-run CLI options exposed by `CliAgent`.
@@ -31,6 +39,7 @@ export type CliAgentRunOptions = {
     readonly allowCredits?: boolean;
     readonly context?: string;
     readonly harness?: CliAgentHarness;
+    readonly isVerbose?: boolean;
     readonly model?: string;
     readonly noUi?: boolean;
     readonly thinkingLevel?: CliAgentThinkingLevel;
@@ -56,6 +65,9 @@ const DEFAULT_CLI_AGENT_IS_NO_UI = true;
  * 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 {
@@ -81,15 +93,30 @@ export class CliAgent {
         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: mergedOptions.harness,
-            model: mergedOptions.model,
+            agentName: harness,
+            model: mergedOptions.model ?? process.env[PTBK_MODEL_ENV],
             noUi: mergedOptions.noUi ?? DEFAULT_CLI_AGENT_IS_NO_UI,
-            thinkingLevel: mergedOptions.thinkingLevel,
+            thinkingLevel: mergedOptions.thinkingLevel ?? resolveCliAgentThinkingLevelFromEnv(),
             allowCredits: mergedOptions.allowCredits ?? false,
-            isVerbose: false,
+            isVerbose: mergedOptions.isVerbose ?? false,
             context: mergedOptions.context,
             currentWorkingDirectory: resolvedSource.currentWorkingDirectory,
         });
@@ -128,12 +155,63 @@ function mergeCliAgentRunOptions(defaults: CliAgentRunOptions, overrides: CliAge
         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.
  *

package/src/book-3.0/cliAgentEnv.ts

@@ -0,0 +1,46 @@
+// Note: [💞] Ignore a discrepancy between file name and entity name
+
+/**
+ * All CLI harness names supported by `CliAgent` and `ptbk agent exec`.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export const CLI_AGENT_HARNESS_NAMES = [
+    'openai-codex',
+    'github-copilot',
+    'cline',
+    'claude-code',
+    'opencode',
+    'gemini',
+] as const;
+
+/**
+ * All supported thinking-level values for CLI coding-agent runners.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export const CLI_AGENT_THINKING_LEVEL_VALUES = ['low', 'medium', 'high', 'xhigh'] as const;
+
+/**
+ * Environment variable used as the default runner identifier when `--harness` is omitted or not set in `CliAgent`.
+ *
+ * Set this to one of the harness names (`openai-codex`, `github-copilot`, `cline`, `claude-code`, `opencode`, `gemini`)
+ * so that `CliAgent` and `ptbk agent exec` can run without an explicit `harness` option.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export const PTBK_HARNESS_ENV = 'PTBK_HARNESS';
+
+/**
+ * Environment variable used as the default runner model when `--model` is omitted or not set in `CliAgent`.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export const PTBK_MODEL_ENV = 'PTBK_MODEL';
+
+/**
+ * Environment variable used as the default thinking level when `--thinking-level` is omitted or not set in `CliAgent`.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export const PTBK_THINKING_LEVEL_ENV = 'PTBK_THINKING_LEVEL';

package/src/cli/cli-commands/coder/run.ts

@@ -11,6 +11,7 @@ import {
     normalizePromptRunnerCliOptions,
     PROMPT_RUNNER_DESCRIPTION,
 } from '../common/promptRunnerCliOptions';
+import { parseDuration } from '../../../../scripts/run-codex-prompts/common/parseDuration';
 
 /**
  * Initializes `coder run` command for Promptbook CLI utilities
@@ -57,7 +58,17 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
     );
     addPromptRunnerExecutionOptions(command);
     command.option('--priority <minimum-priority>', 'Filter prompts by minimum priority level', parseIntOption, 0);
-    command.option('--no-wait', 'Skip user prompts between processing');
+    command.option(
+        '--wait [duration]',
+        spaceTrim(`
+            Wait between prompt rounds.
+            Without a value (default): waits for user confirmation before each prompt (interactive mode).
+            With a duration like 1h, 30m, 5s: waits that long between prompts to avoid hitting rate limits of the harness.
+        `),
+        true,
+    );
+    // Note: --no-wait disables the default interactive wait-for-user behaviour
+    command.option('--no-wait', 'Skip all waiting between prompts and run non-interactively');
     command.option(
         '--auto-migrate',
         'Run testing-server database migrations automatically after each successfully processed prompt',
@@ -76,7 +87,7 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
                     readonly test?: string | string[];
                     readonly preserveLogs: boolean;
                     readonly priority: number;
-                    readonly wait: boolean;
+                    readonly wait: boolean | string;
                     readonly autoMigrate: boolean;
                     readonly allowDestructiveAutoMigrate: boolean;
                 } & PromptRunnerCliOptions;
@@ -86,10 +97,24 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
                 isAgentRequired: !dryRun,
             });
 
+            // [1] Parse the --wait option:
+            //   true (default or --wait without value): wait for user confirmation
+            //   false (--no-wait): no waiting at all
+            //   string (--wait 1h): wait that long between prompt rounds
+            let waitForUser = false;
+            let waitBetweenPrompts = 0;
+
+            if (wait === true) {
+                waitForUser = true;
+            } else if (typeof wait === 'string' && wait !== '') {
+                waitBetweenPrompts = parseDuration(wait);
+            }
+
             // Convert commander options to RunOptions format
             const runOptions = {
                 dryRun,
-                waitForUser: wait,
+                waitForUser,
+                waitBetweenPrompts,
                 noCommit: runnerOptions.noCommit,
                 ignoreGitChanges: runnerOptions.ignoreGitChanges,
                 agentName: runnerOptions.agentName,

package/src/cli/cli-commands/common/promptRunnerCliOptions.ts

@@ -6,41 +6,21 @@ import {
 import { spaceTrim } from 'spacetrim';
 import type { ThinkingLevel } from '../coder/ThinkingLevel';
 import { THINKING_LEVEL_VALUES } from '../coder/ThinkingLevel';
+import {
+    CLI_AGENT_HARNESS_NAMES,
+    PTBK_HARNESS_ENV,
+    PTBK_MODEL_ENV,
+    PTBK_THINKING_LEVEL_ENV,
+} from '../../../book-3.0/cliAgentEnv';
 
-/**
- * Runner identifiers supported by Promptbook CLI agent orchestration commands.
- *
- * @private internal utility of `promptbookCli`
- */
-export const PROMPT_RUNNER_HARNESS_NAMES = [
-    'openai-codex',
-    'github-copilot',
-    'cline',
-    'claude-code',
-    'opencode',
-    'gemini',
-] as const;
-
-/**
- * Environment variable used as the default runner identifier when `--harness` is omitted.
- *
- * @private internal utility of `promptbookCli`
- */
-export const PTBK_HARNESS_ENV = 'PTBK_HARNESS';
-
-/**
- * Environment variable used as the default runner model when `--model` is omitted.
- *
- * @private internal utility of `promptbookCli`
- */
-export const PTBK_MODEL_ENV = 'PTBK_MODEL';
+export { PTBK_HARNESS_ENV, PTBK_MODEL_ENV, PTBK_THINKING_LEVEL_ENV };
 
 /**
- * Environment variable used as the default runner thinking level when `--thinking-level` is omitted.
+ * Runner identifiers supported by Promptbook CLI agent orchestration commands.
  *
  * @private internal utility of `promptbookCli`
  */
-export const PTBK_THINKING_LEVEL_ENV = 'PTBK_THINKING_LEVEL';
+export const PROMPT_RUNNER_HARNESS_NAMES = CLI_AGENT_HARNESS_NAMES;
 
 /**
  * Runner identifier supported by Promptbook CLI agent orchestration commands.