@promptbook/cli 0.114.0-13 → 0.114.0-14

package/esm/scripts/run-codex-prompts/ping/pingCoderHarnessPeriodically.d.ts

@@ -0,0 +1,22 @@
+import type { PingCoderHarnessOptions } from './pingCoderHarness';
+/**
+ * Options for the endless `ptbk coder ping --period <duration>` loop.
+ */
+export type PingCoderHarnessPeriodicallyOptions = PingCoderHarnessOptions & {
+    /**
+     * How long one ping period lasts, in milliseconds.
+     *
+     * The period is measured from the start of one ping to the start of the next one, so the pings
+     * really happen once per period instead of once per period plus the duration of the ping itself.
+     */
+    readonly periodMs: number;
+};
+/**
+ * Pings the selected harness and model once per period until the process is stopped.
+ *
+ * This keeps the quota window of the harness refreshing without any real work, so the window is
+ * always open by the time you need it. The loop never ends on its own — it is stopped with `CTRL+C`
+ * or by killing the process — therefore a failing ping is reported and the next period is started
+ * instead of tearing the whole loop down.
+ */
+export declare function pingCoderHarnessPeriodically(options: PingCoderHarnessPeriodicallyOptions): Promise<never>;

package/esm/src/cli/cli-commands/coder/waitOptions.d.ts

@@ -12,3 +12,15 @@ export declare const DEFAULT_WAIT_AFTER_ERROR_MS: number;
  * @private internal utility of `ptbk coder` wait handling
  */
 export declare function parseOptionalWaitDuration(value: string | undefined, defaultMs: number): number;
+/**
+ * Parses an optional Commander period duration string and returns the resolved milliseconds.
+ *
+ * Returns `undefined` when the flag was not provided or was provided without a non-empty value,
+ * which means the command runs only once instead of repeating itself.
+ *
+ * @throws {NotAllowed} When the duration is not a positive one, because a non-positive period
+ *                      would repeat the command without ever pausing between two rounds
+ *
+ * @private internal utility of `ptbk coder` wait handling
+ */
+export declare function parseOptionalPeriodDuration(optionName: string, value: string | undefined): number | undefined;

package/esm/src/version.d.ts

@@ -15,7 +15,7 @@ export declare const BOOK_LANGUAGE_VERSION: string_semantic_version;
 export declare const PROMPTBOOK_ENGINE_VERSION: string_promptbook_version;
 /**
  * Represents the version string of the Promptbook engine.
- * It follows semantic versioning (e.g., `0.114.0-12`).
+ * It follows semantic versioning (e.g., `0.114.0-13`).
  *
  * @generated
  */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@promptbook/cli",
-    "version": "0.114.0-13",
+    "version": "0.114.0-14",
     "description": "Promptbook: Create persistent AI agents that turn your company's scattered knowledge into action",
     "private": false,
     "sideEffects": false,

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

@@ -17,6 +17,7 @@ import {
     normalizePromptRunnerSelectionCliOptions,
     PROMPT_RUNNER_DESCRIPTION,
 } from '../common/promptRunnerCliOptions';
+import { parseOptionalPeriodDuration } from './waitOptions';
 
 /**
  * Initializes `coder ping` command for Promptbook CLI utilities
@@ -37,6 +38,7 @@ export function $initializeCoderPingCommand(program: Program): $side_effect {
             - Verifies that the selected harness, model, thinking level and authentication really work
             - Reports the answer of the harness, the response time and the reported usage
             - Starts the hourly/weekly quota window before you need it, so it is already refreshing when you do
+            - Optional --period keeps the quota window refreshing by pinging once per period until stopped
             - Leaves the project exactly as it was — nothing is read, written, changed or committed
             - Checks that the selected harness is installed globally and up to date unless --no-harness-update is used
             - Use --no-ui to stream the raw harness output instead of only the compact result
@@ -46,9 +48,20 @@ export function $initializeCoderPingCommand(program: Program): $side_effect {
     addPromptRunnerSelectionOptions(command);
     addHarnessUpdateOption(command);
     addPromptRunnerRuntimeOptions(command);
+    command.option(
+        '--period <duration>',
+        spaceTrim(`
+            Keep pinging once per period instead of pinging only once.
+            Accepts durations like 5h, 30m, 1h30m and repeats until it is stopped with CTRL+C.
+        `),
+    );
 
     command.action(
         handleActionErrors(async (cliOptions) => {
+            const { period: periodValue } = cliOptions as {
+                readonly period?: string;
+            } & PromptRunnerSelectionCliOptions;
+
             const runnerOptions = normalizePromptRunnerSelectionCliOptions(
                 cliOptions as PromptRunnerSelectionCliOptions,
                 { isAgentRequired: true },
@@ -57,23 +70,36 @@ export function $initializeCoderPingCommand(program: Program): $side_effect {
                 cliOptions as HarnessUpdateCliOptions,
             );
 
-            await $ensureHarnessInstallations([runnerOptions.agentName], isHarnessUpdateCheckEnabled);
+            // Note: The period is validated before the harness installation check, so a mistyped duration fails fast
+            const periodMs = parseOptionalPeriodDuration('--period', periodValue);
 
-            // Note: Import the ping dynamically to avoid loading heavy dependencies until needed
-            const { pingCoderHarness } = await import('../../../../scripts/run-codex-prompts/ping/pingCoderHarness');
-            const { printCoderPingResult } = await import(
-                '../../../../scripts/run-codex-prompts/ping/printCoderPingResult'
-            );
+            await $ensureHarnessInstallations([runnerOptions.agentName], isHarnessUpdateCheckEnabled);
 
-            const result = await pingCoderHarness({
+            const pingOptions = {
                 agentName: runnerOptions.agentName,
                 model: runnerOptions.model,
                 thinkingLevel: runnerOptions.thinkingLevel,
                 allowCredits: runnerOptions.allowCredits,
                 shouldPrintLiveOutput: runnerOptions.noUi,
-            });
+            };
+
+            // Note: Import the ping dynamically to avoid loading heavy dependencies until needed
+            if (periodMs !== undefined) {
+                const { pingCoderHarnessPeriodically } = await import(
+                    '../../../../scripts/run-codex-prompts/ping/pingCoderHarnessPeriodically'
+                );
+
+                // Note: This never returns - it keeps pinging until the user stops the process
+                await pingCoderHarnessPeriodically({ ...pingOptions, periodMs });
+                return;
+            }
+
+            const { pingCoderHarness } = await import('../../../../scripts/run-codex-prompts/ping/pingCoderHarness');
+            const { printCoderPingResult } = await import(
+                '../../../../scripts/run-codex-prompts/ping/printCoderPingResult'
+            );
 
-            printCoderPingResult(result);
+            printCoderPingResult(await pingCoderHarness(pingOptions));
         }),
     );
 }

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

@@ -1,4 +1,6 @@
+import { spaceTrim } from 'spacetrim';
 import { parseDuration } from '../../../../scripts/run-codex-prompts/common/parseDuration';
+import { NotAllowed } from '../../../errors/NotAllowed';
 
 /**
  * Default wait duration applied before retrying a prompt round after an error (10 minutes).
@@ -21,4 +23,35 @@ export function parseOptionalWaitDuration(value: string | undefined, defaultMs:
     return parseDuration(value);
 }
 
+/**
+ * Parses an optional Commander period duration string and returns the resolved milliseconds.
+ *
+ * Returns `undefined` when the flag was not provided or was provided without a non-empty value,
+ * which means the command runs only once instead of repeating itself.
+ *
+ * @throws {NotAllowed} When the duration is not a positive one, because a non-positive period
+ *                      would repeat the command without ever pausing between two rounds
+ *
+ * @private internal utility of `ptbk coder` wait handling
+ */
+export function parseOptionalPeriodDuration(optionName: string, value: string | undefined): number | undefined {
+    if (typeof value !== 'string' || value === '') {
+        return undefined;
+    }
+
+    const periodMs = parseDuration(value);
+
+    if (periodMs <= 0) {
+        throw new NotAllowed(
+            spaceTrim(`
+                Invalid value for \`${optionName}\`: \`${value}\`.
+
+                Use a **positive** duration like \`5h\`, \`30m\` or \`1h30m\`.
+            `),
+        );
+    }
+
+    return periodMs;
+}
+
 // Note: [💞] Ignore a discrepancy between file name and entity name