@promptbook/cli 0.112.0-117 → 0.112.0-119

package/esm/index.es.js

@@ -58,7 +58,7 @@ const BOOK_LANGUAGE_VERSION = '2.0.0';
  * @generated
  * @see https://github.com/webgptorg/promptbook
  */
-const PROMPTBOOK_ENGINE_VERSION = '0.112.0-117';
+const PROMPTBOOK_ENGINE_VERSION = '0.112.0-119';
 /**
  * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
  * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -1740,12 +1740,13 @@ function parseThinkingLevel(thinkingLevelValue) {
 }
 // Note: [🟡] Code for CLI command [run](src/cli/cli-commands/coder/run.ts) should never be published outside of `@promptbook/cli`
 
+// Note: [💞] Ignore a discrepancy between file name and entity name
 /**
- * Runner identifiers supported by Promptbook CLI agent orchestration commands.
+ * All CLI harness names supported by `CliAgent` and `ptbk agent exec`.
  *
- * @private internal utility of `promptbookCli`
+ * @public exported from `@promptbook/node`
  */
-const PROMPT_RUNNER_HARNESS_NAMES = [
+const CLI_AGENT_HARNESS_NAMES = [
     'openai-codex',
     'github-copilot',
     'cline',
@@ -1754,23 +1755,33 @@ const PROMPT_RUNNER_HARNESS_NAMES = [
     'gemini',
 ];
 /**
- * Environment variable used as the default runner identifier when `--harness` is omitted.
+ * Environment variable used as the default runner identifier when `--harness` is omitted or not set in `CliAgent`.
  *
- * @private internal utility of `promptbookCli`
+ * 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`
  */
 const PTBK_HARNESS_ENV = 'PTBK_HARNESS';
 /**
- * Environment variable used as the default runner model when `--model` is omitted.
+ * Environment variable used as the default runner model when `--model` is omitted or not set in `CliAgent`.
  *
- * @private internal utility of `promptbookCli`
+ * @public exported from `@promptbook/node`
  */
 const PTBK_MODEL_ENV = 'PTBK_MODEL';
 /**
- * Environment variable used as the default runner thinking level when `--thinking-level` is omitted.
+ * Environment variable used as the default thinking level when `--thinking-level` is omitted or not set in `CliAgent`.
  *
- * @private internal utility of `promptbookCli`
+ * @public exported from `@promptbook/node`
  */
 const PTBK_THINKING_LEVEL_ENV = 'PTBK_THINKING_LEVEL';
+
+/**
+ * Runner identifiers supported by Promptbook CLI agent orchestration commands.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+const PROMPT_RUNNER_HARNESS_NAMES = CLI_AGENT_HARNESS_NAMES;
 /**
  * Description block shared by runner-backed CLI commands.
  *
@@ -3261,6 +3272,16 @@ const AGENTS_SERVER_NEXT_BUILD_ID_FILENAME = 'BUILD_ID';
  * @private internal constant of `ptbk agents-server`
  */
 const DEFAULT_AGENTS_SERVER_NEXT_DIST_DIRECTORY_NAME = '.next';
+/**
+ * Node.js heap size limit (in MiB) injected into `NODE_OPTIONS` for the Next.js production build.
+ *
+ * Next.js webpack peaks at ~1.9 GiB on a fresh install; the Node.js default cap is ~1.7 GiB,
+ * which causes an OOM crash on first-run VPS installations where swap is the primary resource.
+ * Raising the limit lets the build complete on the first attempt.
+ *
+ * @private internal constant of `ptbk agents-server`
+ */
+const AGENTS_SERVER_BUILD_MAX_OLD_SPACE_MIB = 4096;
 /**
  * Environment variable passed to the bundled Next app so webpack can resolve dependencies
  * installed beside `ptbk` even when the app sources are materialized into a project cache.
@@ -3658,7 +3679,10 @@ async function runNextBuild(options) {
         var _a, _b;
         const buildProcess = spawn(process.execPath, [options.nextCliPath, 'build'], {
             cwd: options.appPath,
-            env: options.environment,
+            env: {
+                ...options.environment,
+                NODE_OPTIONS: mergeNodeOptionsWithHeapSize(options.environment.NODE_OPTIONS, AGENTS_SERVER_BUILD_MAX_OLD_SPACE_MIB),
+            },
             stdio: ['ignore', 'pipe', 'pipe'],
         });
         (_a = buildProcess.stdout) === null || _a === void 0 ? void 0 : _a.on('data', (chunk) => {
@@ -3677,6 +3701,16 @@ async function runNextBuild(options) {
         });
     });
 }
+/**
+ * Prepends `--max-old-space-size=<mib>` to `NODE_OPTIONS` unless the caller already set one.
+ */
+function mergeNodeOptionsWithHeapSize(existingNodeOptions, maxOldSpaceMib) {
+    if (existingNodeOptions !== undefined && /--max-old-space-size[= ]/u.test(existingNodeOptions)) {
+        return existingNodeOptions;
+    }
+    const heapFlag = `--max-old-space-size=${maxOldSpaceMib}`;
+    return existingNodeOptions ? `${heapFlag} ${existingNodeOptions}` : heapFlag;
+}
 /**
  * Sends one Next build output chunk through the caller handler or to the foreground terminal.
  */
@@ -5124,6 +5158,7 @@ function createCoderRunOptionsForAgent(options) {
         noUi: options.noUi,
         thinkingLevel: options.thinkingLevel,
         waitForUser: false,
+        waitBetweenPrompts: 0,
         noCommit: options.noCommit,
         ignoreGitChanges: options.ignoreGitChanges,
         normalizeLineEndings: options.normalizeLineEndings,
@@ -10816,21 +10851,22 @@ function getPointBounds(points) {
  * @private helper of `fractalAvatarVisual`
  */
 function drawDragonCurveLayer(context, points, options) {
-    const { size, primaryColor, secondaryColor, tertiaryColor, shadowColor, strokeWidth, timeMs, layerIndex } = options;
+    const { primaryColor, secondaryColor, tertiaryColor, shadowColor, strokeWidth, timeMs, layerIndex } = options;
     const firstPoint = points[0];
     const lastPoint = points[points.length - 1];
     const ribbonGradient = context.createLinearGradient(firstPoint.x, firstPoint.y, lastPoint.x, lastPoint.y);
     ribbonGradient.addColorStop(0, `${primaryColor}f2`);
     ribbonGradient.addColorStop(0.5, `${secondaryColor}e6`);
     ribbonGradient.addColorStop(1, `${tertiaryColor}f2`);
+    // Approximate the blurred shadow stroke with a wider semi-transparent stroke instead of
+    // context.filter blur, which triggers a costly software rasterization pass every frame.
     context.save();
     context.beginPath();
     tracePolyline(context, points);
-    context.strokeStyle = `${shadowColor}82`;
-    context.lineWidth = strokeWidth * 1.8;
+    context.strokeStyle = `${shadowColor}48`;
+    context.lineWidth = strokeWidth * 4.5;
     context.lineJoin = 'round';
     context.lineCap = 'round';
-    context.filter = `blur(${size * 0.022}px)`;
     context.stroke();
     context.restore();
     context.beginPath();
@@ -11414,11 +11450,23 @@ function drawMinecraftBackdrop(context, size, palette, sceneCenterX, spotlightY,
  * @private helper of `minecraft2AvatarVisual`
  */
 function drawMinecraftShadow(context, size, palette, interaction, timeMs) {
+    const cx = size * 0.5 + interaction.gazeX * size * 0.03;
+    const cy = size * 0.85 + Math.sin(timeMs / 880) * size * 0.01;
+    const rx = size * (0.16 + interaction.intensity * 0.015);
+    const ry = size * 0.055;
+    // Radial gradient approximates the blurry ellipse shadow without context.filter blur.
     context.save();
-    context.fillStyle = `${palette.shadow}66`;
-    context.filter = `blur(${size * 0.02}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.03, size * 0.85 + Math.sin(timeMs / 880) * size * 0.01, size * (0.16 + interaction.intensity * 0.015), size * 0.055, 0, 0, Math.PI * 2);
+    context.arc(0, 0, blurRadius, 0, Math.PI * 2);
     context.fill();
     context.restore();
 }
@@ -11642,13 +11690,27 @@ const minecraftAvatarVisual = {
         spotlight.addColorStop(1, `${palette.highlight}00`);
         context.fillStyle = spotlight;
         context.fillRect(0, 0, size, size);
-        context.save();
-        context.fillStyle = 'rgba(0, 0, 0, 0.22)';
-        context.filter = `blur(${size * 0.018}px)`;
-        context.beginPath();
-        context.ellipse(size * 0.5, size * 0.86, size * 0.2, size * 0.06, 0, 0, Math.PI * 2);
-        context.fill();
-        context.restore();
+        {
+            // Radial gradient approximates the blurry ellipse shadow without context.filter blur.
+            const cx = size * 0.5;
+            const cy = size * 0.86;
+            const rx = size * 0.2;
+            const ry = size * 0.06;
+            const blurRadius = rx * 1.4;
+            const shadowGradient = context.createRadialGradient(0, 0, 0, 0, 0, blurRadius);
+            shadowGradient.addColorStop(0, 'rgba(0,0,0,0.28)');
+            shadowGradient.addColorStop(0.45, 'rgba(0,0,0,0.14)');
+            shadowGradient.addColorStop(0.8, 'rgba(0,0,0,0.05)');
+            shadowGradient.addColorStop(1, 'rgba(0,0,0,0)');
+            context.save();
+            context.translate(cx, cy);
+            context.scale(1, ry / rx);
+            context.fillStyle = shadowGradient;
+            context.beginPath();
+            context.arc(0, 0, blurRadius, 0, Math.PI * 2);
+            context.fill();
+            context.restore();
+        }
         drawVoxelCuboid(context, {
             x: bodyX,
             y: bodyY,
@@ -12700,6 +12762,35 @@ const LIGHT_DIRECTION$2 = normalizeVector3({
     y: -0.62,
     z: 0.94,
 });
+/**
+ * Cache keyed by the `createRandom` factory reference (stable per mounted `<Avatar/>`).
+ *
+ * @private helper of `octopus3dAvatarVisual`
+ */
+const octopus3dStableStateCache = new WeakMap();
+/**
+ * Returns the stable per-avatar state, computing it on first access and caching for subsequent frames.
+ *
+ * @private helper of `octopus3dAvatarVisual`
+ */
+function getOctopus3dStableState(createRandom) {
+    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 = {
+        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.
  *
@@ -12712,10 +12803,7 @@ const octopus3dAvatarVisual = {
     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;
@@ -12812,12 +12900,12 @@ const octopus3dAvatarVisual = {
             x: -faceEyeSpacing,
             y: faceEyeYOffset,
             z: resolveEllipsoidSurfaceDepth(mantleRadiusX, mantleRadiusY, mantleRadiusZ, -faceEyeSpacing, faceEyeYOffset),
-        }, faceEyeRadiusX, faceEyeRadiusY, mantleCenter, headPitch, headYaw, sceneCenterX, sceneCenterY, size, palette, timeMs, animationPhase + eyeRandom() * 0.6, interaction, morphologyProfile.face.eyeStyle);
+        }, faceEyeRadiusX, faceEyeRadiusY, mantleCenter, headPitch, headYaw, sceneCenterX, sceneCenterY, size, palette, timeMs, animationPhase + leftEyePhaseOffset, interaction, morphologyProfile.face.eyeStyle);
         drawProjectedOrganicEye(context, {
             x: faceEyeSpacing,
             y: faceEyeYOffset,
             z: resolveEllipsoidSurfaceDepth(mantleRadiusX, mantleRadiusY, mantleRadiusZ, faceEyeSpacing, faceEyeYOffset),
-        }, faceEyeRadiusX, faceEyeRadiusY, mantleCenter, headPitch, headYaw, sceneCenterX, sceneCenterY, size, palette, timeMs, animationPhase + 0.7 + eyeRandom() * 0.6, interaction, morphologyProfile.face.eyeStyle);
+        }, faceEyeRadiusX, faceEyeRadiusY, mantleCenter, headPitch, headYaw, sceneCenterX, sceneCenterY, size, palette, timeMs, animationPhase + 0.7 + rightEyePhaseOffset, interaction, morphologyProfile.face.eyeStyle);
         drawProjectedOrganicMouth(context, [
             {
                 x: -mouthHalfWidth,
@@ -12861,14 +12949,28 @@ function drawOctopus3dAtmosphere(context, size, palette, sceneCenterX, sceneCent
 /**
  * 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(context, size, palette, interaction, timeMs) {
+    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();
 }
@@ -13099,6 +13201,35 @@ const LIGHT_DIRECTION$1 = normalizeVector3({
     y: -0.6,
     z: 0.98,
 });
+/**
+ * Cache keyed by the `createRandom` factory reference (stable per mounted `<Avatar/>`).
+ *
+ * @private helper of `octopus3d2AvatarVisual`
+ */
+const octopus3d2StableStateCache = new WeakMap();
+/**
+ * Returns the stable per-avatar state, computing it on first access and caching for subsequent frames.
+ *
+ * @private helper of `octopus3d2AvatarVisual`
+ */
+function getOctopus3d2StableState(createRandom) {
+    const cached = octopus3d2StableStateCache.get(createRandom);
+    if (cached !== undefined) {
+        return cached;
+    }
+    const animationRandom = createRandom('octopus3d2-animation-profile');
+    const eyeRandom = createRandom('octopus3d2-eye-profile');
+    const leftEyePhaseOffset = eyeRandom() * 0.7;
+    const rightEyePhaseOffset = eyeRandom() * 0.7;
+    const state = {
+        morphologyProfile: createOctopus3MorphologyProfile(createRandom),
+        animationPhase: animationRandom() * Math.PI * 2,
+        leftEyePhaseOffset,
+        rightEyePhaseOffset,
+    };
+    octopus3d2StableStateCache.set(createRandom, state);
+    return state;
+}
 /**
  * Octopus 3D 2 avatar visual.
  *
@@ -13111,10 +13242,7 @@ const octopus3d2AvatarVisual = {
     isAnimated: true,
     supportsPointerTracking: true,
     render({ context, size, palette, createRandom, timeMs, interaction }) {
-        const morphologyProfile = createOctopus3MorphologyProfile(createRandom);
-        const animationRandom = createRandom('octopus3d2-animation-profile');
-        const eyeRandom = createRandom('octopus3d2-eye-profile');
-        const animationPhase = animationRandom() * Math.PI * 2;
+        const { morphologyProfile, animationPhase, leftEyePhaseOffset, rightEyePhaseOffset } = getOctopus3d2StableState(createRandom);
         const sceneCenterX = size * 0.5;
         const sceneCenterY = size * 0.575;
         const bob = Math.sin(timeMs / 940 + animationPhase) * size * 0.013;
@@ -13167,8 +13295,8 @@ const octopus3d2AvatarVisual = {
         const rightEyeLocalCenter = sampleBlobbyOctopusSurfacePoint(surfaceOptions, eyeLatitude, eyeLongitude);
         const eyeRadiusX = size * morphologyProfile.face.eyeRadiusXRatio * 0.78;
         const eyeRadiusY = eyeRadiusX * morphologyProfile.face.eyeHeightRatio * 0.92;
-        drawProjectedOrganicEye(context, leftEyeLocalCenter, eyeRadiusX, eyeRadiusY, meshCenter, rotationX, rotationY, sceneCenterX, sceneCenterY, size, palette, timeMs, animationPhase + eyeRandom() * 0.7, interaction, morphologyProfile.face.eyeStyle);
-        drawProjectedOrganicEye(context, rightEyeLocalCenter, eyeRadiusX, eyeRadiusY, meshCenter, rotationX, rotationY, sceneCenterX, sceneCenterY, size, palette, timeMs, animationPhase + 0.9 + eyeRandom() * 0.7, interaction, morphologyProfile.face.eyeStyle);
+        drawProjectedOrganicEye(context, leftEyeLocalCenter, eyeRadiusX, eyeRadiusY, meshCenter, rotationX, rotationY, sceneCenterX, sceneCenterY, size, palette, timeMs, animationPhase + leftEyePhaseOffset, interaction, morphologyProfile.face.eyeStyle);
+        drawProjectedOrganicEye(context, rightEyeLocalCenter, eyeRadiusX, eyeRadiusY, meshCenter, rotationX, rotationY, sceneCenterX, sceneCenterY, size, palette, timeMs, animationPhase + 0.9 + rightEyePhaseOffset, interaction, morphologyProfile.face.eyeStyle);
         drawProjectedOrganicMouth(context, [
             sampleBlobbyOctopusSurfacePoint(surfaceOptions, mouthLatitude, mouthCenterLongitude - mouthHalfLongitude),
             sampleBlobbyOctopusSurfacePoint(surfaceOptions, mouthCurveLatitude, mouthCenterLongitude),
@@ -13197,14 +13325,28 @@ function drawBlobbyOctopusAtmosphere(context, size, palette, sceneCenterX, scene
 /**
  * Draws the soft floor shadow that anchors the single mesh in the frame.
  *
+ * 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 `octopus3d2AvatarVisual`
  */
 function drawBlobbyOctopusShadow(context, size, palette, interaction, timeMs, morphologyProfile) {
+    const cx = size * 0.5 + interaction.gazeX * size * 0.045;
+    const cy = size * 0.88 + Math.sin(timeMs / 940) * size * 0.008;
+    const rx = size * (0.18 + (morphologyProfile.body.horizontalStretch - 1) * 0.04 + interaction.intensity * 0.018);
+    const ry = size * 0.062;
     context.save();
-    context.fillStyle = `${palette.shadow}66`;
-    context.filter = `blur(${size * 0.024}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.045, size * 0.88 + Math.sin(timeMs / 940) * size * 0.008, size * (0.18 + (morphologyProfile.body.horizontalStretch - 1) * 0.04 + interaction.intensity * 0.018), size * 0.062, 0, 0, Math.PI * 2);
+    context.arc(0, 0, blurRadius, 0, Math.PI * 2);
     context.fill();
     context.restore();
 }
@@ -13360,6 +13502,40 @@ const LIGHT_DIRECTION = normalizeVector3({
  * @private helper of `octopus3d3AvatarVisual`
  */
 const OCTOPUS_TENTACLE_COUNT = 8;
+/**
+ * Cache keyed by the `createRandom` factory reference, which is stable for the lifetime of one
+ * mounted `<Avatar/>` component (created inside `resolveAvatarRenderDefinition` and held in a
+ * React `useMemo`).  Using a `WeakMap` ensures the entry is collected when the component unmounts.
+ *
+ * @private helper of `octopus3d3AvatarVisual`
+ */
+const stableStateCache = new WeakMap();
+/**
+ * Returns the stable per-avatar state, computing it on first access and returning the cached
+ * result on every subsequent call within the same `<Avatar/>` mount.
+ *
+ * @private helper of `octopus3d3AvatarVisual`
+ */
+function getOctopus3d3StableState(createRandom) {
+    const cached = stableStateCache.get(createRandom);
+    if (cached !== undefined) {
+        return cached;
+    }
+    const morphologyProfile = createOctopus3MorphologyProfile(createRandom);
+    const animationRandom = createRandom('octopus3d3-animation-profile');
+    const eyeRandom = createRandom('octopus3d3-eye-profile');
+    const leftEyePhaseOffset = eyeRandom() * 0.7;
+    const rightEyePhaseOffset = eyeRandom() * 0.7;
+    const state = {
+        morphologyProfile,
+        animationPhase: animationRandom() * Math.PI * 2,
+        leftEyePhaseOffset,
+        rightEyePhaseOffset,
+        tentacleProfiles: createContinuousTentacleProfiles(createRandom, morphologyProfile),
+    };
+    stableStateCache.set(createRandom, state);
+    return state;
+}
 /**
  * Octopus 3D 3 avatar visual.
  *
@@ -13372,11 +13548,7 @@ const octopus3d3AvatarVisual = {
     isAnimated: true,
     supportsPointerTracking: true,
     render({ context, size, palette, createRandom, timeMs, interaction }) {
-        const morphologyProfile = createOctopus3MorphologyProfile(createRandom);
-        const animationRandom = createRandom('octopus3d3-animation-profile');
-        const eyeRandom = createRandom('octopus3d3-eye-profile');
-        const animationPhase = animationRandom() * Math.PI * 2;
-        const tentacleProfiles = createContinuousTentacleProfiles(createRandom, morphologyProfile);
+        const { morphologyProfile, animationPhase, leftEyePhaseOffset, rightEyePhaseOffset, tentacleProfiles } = getOctopus3d3StableState(createRandom);
         const sceneCenterX = size * 0.5;
         const sceneCenterY = size * 0.535;
         const bob = Math.sin(timeMs / 960 + animationPhase) * size * 0.012;
@@ -13453,8 +13625,8 @@ const octopus3d3AvatarVisual = {
             size,
             palette,
         });
-        drawProjectedOrganicEye(context, sampleContinuousOctopusSurfacePoint(surfaceOptions, eyeLatitude, -eyeLongitude), eyeRadiusX, eyeRadiusY, meshCenter, rotationX, rotationY, sceneCenterX, sceneCenterY, size, palette, timeMs, animationPhase + eyeRandom() * 0.7, interaction, morphologyProfile.face.eyeStyle);
-        drawProjectedOrganicEye(context, sampleContinuousOctopusSurfacePoint(surfaceOptions, eyeLatitude, eyeLongitude), eyeRadiusX, eyeRadiusY, meshCenter, rotationX, rotationY, sceneCenterX, sceneCenterY, size, palette, timeMs, animationPhase + 0.85 + eyeRandom() * 0.7, interaction, morphologyProfile.face.eyeStyle);
+        drawProjectedOrganicEye(context, sampleContinuousOctopusSurfacePoint(surfaceOptions, eyeLatitude, -eyeLongitude), eyeRadiusX, eyeRadiusY, meshCenter, rotationX, rotationY, sceneCenterX, sceneCenterY, size, palette, timeMs, animationPhase + leftEyePhaseOffset, interaction, morphologyProfile.face.eyeStyle);
+        drawProjectedOrganicEye(context, sampleContinuousOctopusSurfacePoint(surfaceOptions, eyeLatitude, eyeLongitude), eyeRadiusX, eyeRadiusY, meshCenter, rotationX, rotationY, sceneCenterX, sceneCenterY, size, palette, timeMs, animationPhase + 0.85 + rightEyePhaseOffset, interaction, morphologyProfile.face.eyeStyle);
         drawProjectedOrganicMouth(context, [
             sampleContinuousOctopusSurfacePoint(surfaceOptions, mouthLatitude, mouthCenterLongitude - mouthHalfLongitude),
             sampleContinuousOctopusSurfacePoint(surfaceOptions, mouthCurveLatitude, mouthCenterLongitude),
@@ -13505,14 +13677,30 @@ function drawContinuousOctopusAtmosphere(context, size, palette, sceneCenterX, s
 /**
  * Draws the soft lower shadow that anchors the octopus in the avatar frame.
  *
+ * 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 `octopus3d3AvatarVisual`
  */
 function drawContinuousOctopusShadow(context, size, palette, interaction, timeMs, morphologyProfile) {
+    const cx = size * 0.5 + interaction.gazeX * size * 0.045;
+    const cy = size * 0.9 + Math.sin(timeMs / 980) * size * 0.007;
+    const rx = size * (0.19 + morphologyProfile.tentacles.rootSpreadScale * 0.022 + interaction.intensity * 0.02);
+    const ry = size * 0.06;
+    // Scale the context so that drawing a circle produces the correct ellipse aspect ratio,
+    // then fill with a radial gradient that approximates the blurry edge without context.filter.
     context.save();
-    context.fillStyle = `${palette.shadow}66`;
-    context.filter = `blur(${size * 0.025}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.045, size * 0.9 + Math.sin(timeMs / 980) * size * 0.007, size * (0.19 + morphologyProfile.tentacles.rootSpreadScale * 0.022 + 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();
 }
@@ -28737,14 +28925,50 @@ function buildAgentMessageCommitMessage(messageFile) {
  * Builds the prompt sent to the selected coding runner for one queued user-thread book.
  */
 function buildAgentMessagePrompt(messageRelativePath, agentSystemMessage) {
-    const taskPrompt = spaceTrim$1(`
-            Answer 1 user question
+    return spaceTrim$1((block) => `
+                # Answer 1 user question
 
-            -   Read \`${messageRelativePath}\` and answer the most recent \`MESSAGE @User\`
-            -   Only change the queued message file by appending one new \`MESSAGE @Agent\` block
-            -   Do not modify any other file in the repository
-        `);
-    return `${taskPrompt}\n\n**This is how you should behave:**\n\n${agentSystemMessage.trim()}`;
+                -   Read \`${messageRelativePath}\` and answer the most recent \`MESSAGE @User\`
+                -   Only change the queued message file by appending one new \`MESSAGE @Agent\` block
+                -   Do not modify any other file in the repository
+
+                ## Rules for the answering
+
+                ## Formatting
+
+                - You can use Markdown formatting in the messages like **bold** or *italic*
+
+                ## Sources and citations
+
+                Mark sources and citations like this "【https://example.com/document123.pdf 】"
+
+                At the same time, you can write sources naturally in the text of the answers
+
+                For example:
+
+                > According to paragraph §745b, the fee can be waived for a person over 65 years old. 【https://praha13.cz/2026/paragraph-745.doc】
+
+                - "paragraph §745b" fits naturally in the text.
+                - "【https://praha13.cz/2026/paragraph-745.doc】" The exact format of the quote is important for further processing of the answer.
+                - The "【" and "】" symbols are used to mark the source and will be parsed, inside should be valid URL used as a source for the answer.
+
+                ## Quick buttons
+
+                If there is a meaningful follow-up procedure, use quick buttons at the end of the answer:
+
+                \`\`\`
+                How big is the contract you are posting?
+
+                [Up to 50,000 CZK](?message=We are posting an order up to 50,000 CZK)
+                [Up to 100,000 CZK](?message=We are posting an order up to 100,000 CZK)
+                [Over 100,000 CZK](?message=We are posting an order over 100,000 CZK)
+                \`\`\`
+
+
+                ## This is how you should behave
+
+                ${block(agentSystemMessage)}
+            `);
 }
 
 /**
@@ -35889,7 +36113,9 @@ function parseBookMessageHeader(line) {
  * @private internal utility of `Book`
  */
 function parseCommitmentHeader(line) {
-    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;
     }
@@ -39303,6 +39529,57 @@ function listDefaultCoderProjectPromptTemplateDisplayPaths() {
 // Note: [🟡] Code for CLI command [init](src/cli/cli-commands/coder/init.ts) should never be published outside of `@promptbook/cli`
 // Note: [💞] Ignore a discrepancy between file name and entity name
 
+/**
+ * Pattern that matches durations like "1h", "30m", "5s", "1h30m", "1h30m5s".
+ */
+const DURATION_PATTERN = /^(?:(\d+)h)?(?:(\d+)m(?:in)?)?(?:(\d+)s)?$/;
+/**
+ * Parses a human-readable duration string into milliseconds.
+ *
+ * Supported formats: `Xh`, `Xm`, `Xs`, and combinations like `1h30m`, `1h30m5s`.
+ *
+ * @returns Duration in milliseconds
+ * @throws When the string does not match any supported format
+ *
+ * @private internal utility of `ptbk coder run`
+ */
+function parseDuration(durationString) {
+    var _a, _b, _c;
+    const trimmed = durationString.trim();
+    if (!trimmed) {
+        throw new Error(`Invalid duration: empty string. Expected a format like "1h", "30m", "5s", or combinations like "1h30m".`);
+    }
+    const match = trimmed.match(DURATION_PATTERN);
+    if (!match || (match[1] === undefined && match[2] === undefined && match[3] === undefined)) {
+        throw new Error(`Invalid duration: "${durationString}". Expected a format like "1h", "30m", "5s", or combinations like "1h30m5s".`);
+    }
+    const hours = parseInt((_a = match[1]) !== null && _a !== void 0 ? _a : '0', 10);
+    const minutes = parseInt((_b = match[2]) !== null && _b !== void 0 ? _b : '0', 10);
+    const seconds = parseInt((_c = match[3]) !== null && _c !== void 0 ? _c : '0', 10);
+    return (hours * 3600 + minutes * 60 + seconds) * 1000;
+}
+/**
+ * Formats a duration in milliseconds into a compact human-readable string.
+ *
+ * Examples: `3600000` → `"1h"`, `90000` → `"1m 30s"`, `5000` → `"5s"`.
+ *
+ * @private internal utility of `ptbk coder run`
+ */
+function formatDurationMs(ms) {
+    const totalSeconds = Math.ceil(ms / 1000);
+    const hours = Math.floor(totalSeconds / 3600);
+    const minutes = Math.floor((totalSeconds % 3600) / 60);
+    const seconds = totalSeconds % 60;
+    const parts = [];
+    if (hours > 0)
+        parts.push(`${hours}h`);
+    if (minutes > 0)
+        parts.push(`${minutes}m`);
+    if (seconds > 0 || parts.length === 0)
+        parts.push(`${seconds}s`);
+    return parts.join(' ');
+}
+
 /**
  * Initializes `coder run` command for Promptbook CLI utilities
  *
@@ -39335,7 +39612,13 @@ function $initializeCoderRunCommand(program) {
     command.option('--preserve-logs', 'Keep generated temp prompt/log artifacts after successful rounds for debugging and analytics', false);
     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$1(`
+            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');
     command.option('--allow-destructive-auto-migrate', 'Allow auto-migrate even when heuristic SQL safety check flags destructive pending migrations');
     command.action(handleActionErrors(async (cliOptions) => {
@@ -39344,10 +39627,23 @@ function $initializeCoderRunCommand(program) {
         const runnerOptions = normalizePromptRunnerCliOptions(cliOptions, {
             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,
@@ -58186,7 +58482,7 @@ class OpenAiVectorStoreKnowledgeSourcePreparer {
                 return { skippedReason: 'invalid_data_url' };
             }
             return {
-                file: new File([parsed.buffer], parsed.filename, {
+                file: new File([new Uint8Array(parsed.buffer)], parsed.filename, {
                     type: parsed.mimeType,
                 }),
                 sizeBytes: parsed.buffer.length,
@@ -62790,6 +63086,7 @@ function createPromptRunnerOptions(options) {
         noUi: options.noUi,
         thinkingLevel: options.thinkingLevel,
         waitForUser: false,
+        waitBetweenPrompts: 0,
         noCommit: true,
         ignoreGitChanges: true,
         normalizeLineEndings: false,
@@ -68324,7 +68621,7 @@ var findRefactorCandidates$1 = /*#__PURE__*/Object.freeze({
 /**
  * CLI usage text for this script.
  */
-const USAGE = 'Usage: run-codex-prompts [--dry-run] [--harness <harness-name>] [--model <model>] [--context <context-or-file>] [--test <test-command...>] [--preserve-logs] [--no-ui] [--thinking-level <thinking-level>] [--priority <minimum-priority>] [--allow-credits] [--auto-migrate] [--allow-destructive-auto-migrate] [--no-wait] [--no-commit] [--ignore-git-changes] [--no-normalize-line-endings] [--auto-push] [--auto-pull]';
+const USAGE = 'Usage: run-codex-prompts [--dry-run] [--harness <harness-name>] [--model <model>] [--context <context-or-file>] [--test <test-command...>] [--preserve-logs] [--no-ui] [--thinking-level <thinking-level>] [--priority <minimum-priority>] [--allow-credits] [--auto-migrate] [--allow-destructive-auto-migrate] [--wait [duration]] [--no-wait] [--no-commit] [--ignore-git-changes] [--no-normalize-line-endings] [--auto-push] [--auto-pull]';
 /**
  * Top-level flags supported by this command.
  */
@@ -68341,6 +68638,7 @@ const KNOWN_OPTION_FLAGS = new Set([
     '--allow-credits',
     '--auto-migrate',
     '--allow-destructive-auto-migrate',
+    '--wait',
     '--no-wait',
     '--no-commit',
     '--ignore-git-changes',
@@ -68379,6 +68677,22 @@ function parseRunOptions(args) {
     const allowDestructiveAutoMigrate = args.includes('--allow-destructive-auto-migrate');
     const autoPush = args.includes('--auto-push');
     const autoPull = args.includes('--auto-pull');
+    // [1] Parse --wait [duration]:
+    //   absent or --no-wait: no waiting
+    //   --wait (no value): wait for user confirmation
+    //   --wait 1h: wait 1h between prompt rounds to avoid rate limits
+    const waitOptionalValue = readOptionalOptionValue(args, '--wait');
+    let waitForUser = false;
+    let waitBetweenPrompts = 0;
+    if (waitOptionalValue === null) {
+        // --wait present without a duration value: interactive mode
+        waitForUser = true;
+    }
+    else if (waitOptionalValue !== undefined) {
+        // --wait <duration>: time-based wait between rounds
+        waitBetweenPrompts = parseDuration(waitOptionalValue);
+    }
+    // --no-wait (or no flag): both waitForUser and waitBetweenPrompts remain false/0
     let thinkingLevel;
     if (hasTestCommandFlag && testCommand === undefined) {
         exitWithUsageError('Missing value for --test. Use a shell command such as `npm run test` and quote it when it contains top-level CLI flags.');
@@ -68397,7 +68711,8 @@ function parseRunOptions(args) {
     }
     return {
         dryRun,
-        waitForUser: !args.includes('--no-wait'),
+        waitForUser,
+        waitBetweenPrompts,
         noCommit,
         ignoreGitChanges,
         normalizeLineEndings,
@@ -68416,6 +68731,23 @@ function parseRunOptions(args) {
         priority,
     };
 }
+/**
+ * Reads an optional value for a flag that may appear with or without a following value.
+ *
+ * Returns `undefined` when the flag is absent, `null` when the flag is present but has no value
+ * (the next token is another flag or the end of args), and the value string otherwise.
+ */
+function readOptionalOptionValue(args, flag) {
+    if (!args.includes(flag)) {
+        return undefined;
+    }
+    const index = args.indexOf(flag);
+    const nextArg = args[index + 1];
+    if (nextArg === undefined || nextArg.startsWith('-')) {
+        return null;
+    }
+    return nextArg;
+}
 /**
  * Reads a value of a CLI option that follows a given flag.
  */
@@ -70871,6 +71203,7 @@ async function runCodexPrompts(providedOptions) {
         initializeRunUi(uiHandle, runner.name, actualRunnerModel, options);
         let hasShownUpcomingTasks = false;
         let hasWaitedForStart = false;
+        let hasRunAtLeastOneRound = false;
         while (just(true)) {
             if (options.autoPull && !options.dryRun) {
                 await waitForRequestedPause({
@@ -70906,6 +71239,16 @@ async function runCodexPrompts(providedOptions) {
             }
             const nextPrompt = promptQueueSnapshot.nextPrompt;
             const promptLabel = buildPromptLabelForDisplay(nextPrompt.file, nextPrompt.section);
+            // Wait between prompt rounds (skipped for the first round)
+            if (hasRunAtLeastOneRound) {
+                await waitBetweenPromptRoundsIfNeeded({
+                    options,
+                    isRichUiEnabled,
+                    progressDisplay,
+                    uiHandle,
+                });
+            }
+            hasRunAtLeastOneRound = true;
             hasWaitedForStart = await waitForPromptConfirmationIfNeeded({
                 options,
                 nextPrompt,
@@ -71141,6 +71484,39 @@ async function waitForPromptConfirmationIfNeeded(options) {
     uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.resumeTimer();
     return true;
 }
+/**
+ * Countdown update interval for the between-rounds wait display.
+ */
+const WAIT_COUNTDOWN_UPDATE_INTERVAL_MS = 30000;
+/**
+ * Waits the configured time between prompt rounds to avoid hitting harness rate limits.
+ * Does nothing when `waitBetweenPrompts` is zero.
+ */
+async function waitBetweenPromptRoundsIfNeeded(options) {
+    const { options: runOptions, isRichUiEnabled, progressDisplay, uiHandle } = options;
+    const { waitBetweenPrompts } = runOptions;
+    if (waitBetweenPrompts <= 0) {
+        return;
+    }
+    progressDisplay === null || progressDisplay === void 0 ? void 0 : progressDisplay.pauseTimer();
+    uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.pauseTimer();
+    uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setPhase('waiting');
+    let remaining = waitBetweenPrompts;
+    while (remaining > 0) {
+        const statusMessage = `Waiting ${formatDurationMs(remaining)} before next prompt to avoid rate limits...`;
+        if (!isRichUiEnabled) {
+            console.info(colors.gray(statusMessage));
+        }
+        else {
+            uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setStatusMessage(statusMessage);
+        }
+        const sleepMs = Math.min(WAIT_COUNTDOWN_UPDATE_INTERVAL_MS, remaining);
+        await new Promise((resolve) => setTimeout(resolve, sleepMs));
+        remaining -= sleepMs;
+    }
+    progressDisplay === null || progressDisplay === void 0 ? void 0 : progressDisplay.resumeTimer();
+    uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.resumeTimer();
+}
 /**
  * Stops active displays and prints the git identity tip for real runs.
  */