@promptbook/cli 0.112.0-42 → 0.112.0-44

package/esm/scripts/run-codex-prompts/common/formatUnknownErrorDetails.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Formats one unknown error-like value into readable text for logs and feedback.
+ */
+export declare function formatUnknownErrorDetails(error: unknown): string;

package/esm/scripts/run-codex-prompts/common/runGoScript/$runGoScript.d.ts

@@ -1,5 +1,5 @@
 import type { RunGoScriptOptions } from './RunGoScriptOptions';
 /**
- * Creates a temporary script file, runs it, and then deletes it.
+ * Creates a temporary script file, runs it, and cleans it up immediately unless a round tracker defers that cleanup.
  */
 export declare function $runGoScript(options: RunGoScriptOptions): Promise<void>;

package/esm/scripts/run-codex-prompts/common/runGoScript/$runGoScriptUntilMarkerIdle.d.ts

@@ -1,6 +1,6 @@
 import type { RunGoScriptUntilMarkerIdleOptions } from './RunGoScriptUntilMarkerIdleOptions';
 /**
- * Creates a temporary script file, runs it, waits for a completion marker and idle time, and then deletes it.
+ * Creates a temporary script file, runs it, waits for a completion marker and idle time, and defers cleanup when a round tracker is provided.
  * Returns the captured output for post-processing.
  */
 export declare function $runGoScriptUntilMarkerIdle(options: RunGoScriptUntilMarkerIdleOptions): Promise<string>;

package/esm/scripts/run-codex-prompts/common/runGoScript/$runGoScriptWithOutput.d.ts

@@ -1,5 +1,5 @@
 import type { RunGoScriptOptions } from './RunGoScriptOptions';
 /**
- * Creates a temporary script file, runs it, captures output, and then deletes it.
+ * Creates a temporary script file, runs it, captures output, and cleans it up immediately unless a round tracker defers that cleanup.
  */
 export declare function $runGoScriptWithOutput(options: RunGoScriptOptions): Promise<string>;

package/esm/scripts/run-codex-prompts/common/runGoScript/PromptRoundArtifacts.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Kind of temporary artifact created during one coder prompt round.
+ */
+export type PromptRoundArtifactKind = 'runner-script' | 'test-script' | 'runtime-log';
+/**
+ * Final outcome of one coder prompt round.
+ */
+export type PromptRoundOutcome = 'success' | 'failure';
+/**
+ * Tracks temporary prompt-round artifacts and deletes only those not preserved for the final round outcome.
+ */
+export declare class PromptRoundArtifacts {
+    private readonly preservedArtifactKindsByOutcome;
+    private readonly trackedArtifacts;
+    /**
+     * Creates a new prompt-round artifact tracker.
+     */
+    constructor(preservedArtifactKindsByOutcome: Record<PromptRoundOutcome, ReadonlySet<PromptRoundArtifactKind>>);
+    /**
+     * Registers one temporary artifact for round-final cleanup.
+     */
+    track(path: string, kind: PromptRoundArtifactKind): void;
+    /**
+     * Cleans up all tracked artifacts that should not survive the final round outcome.
+     */
+    cleanup(outcome: PromptRoundOutcome): Promise<void>;
+}
+/**
+ * Creates the default artifact-retention policy used by `ptbk coder run`.
+ */
+export declare function createCoderRunPromptRoundArtifacts(isPreserveLogs: boolean): PromptRoundArtifacts;
+/**
+ * Derives the tracked artifact kind from one temporary shell path.
+ */
+export declare function getPromptRoundArtifactKindFromScriptPath(scriptPath: string): PromptRoundArtifactKind;

package/esm/scripts/run-codex-prompts/common/runGoScript/buildScriptLogPath.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Builds the temporary live runtime log path for one prompt script and its sibling test script.
+ */
+export declare function buildScriptLogPath(scriptPath: string): string;

package/esm/scripts/run-codex-prompts/common/runGoScript/runBashScriptWithOutput.d.ts

@@ -0,0 +1,5 @@
+import type { RunGoScriptOptions } from './RunGoScriptOptions';
+/**
+ * Runs one temporary bash script, optionally mirroring its raw input/output into a live runtime log file.
+ */
+export declare function runBashScriptWithOutput(options: RunGoScriptOptions): Promise<string>;

package/esm/scripts/run-codex-prompts/common/runGoScript/scriptExecutionLog.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Environment variable read by the shell wrapper to tee live output into the temporary runtime log file.
+ */
+export declare const PTBK_CODER_LOG_FILE_ENV_NAME = "PTBK_CODER_LOG_FILE";
+/**
+ * Shapes one bash invocation that optionally mirrors live script output into a temporary log file.
+ */
+export declare function buildLoggedBashExecution(scriptPath: string, logPath?: string): {
+    args: string[];
+    env?: Record<string, string>;
+};
+/**
+ * Appends one execution-start section with the raw script input before the shell begins producing output.
+ */
+export declare function appendScriptExecutionLogStart({ scriptPath, scriptContent, logPath, }: {
+    scriptPath: string;
+    scriptContent: string;
+    logPath?: string;
+}): Promise<void>;
+/**
+ * Appends one execution-finish section after the shell settles.
+ */
+export declare function appendScriptExecutionLogFinish({ scriptPath, logPath, status, details, }: {
+    scriptPath: string;
+    logPath?: string;
+    status: string;
+    details?: unknown;
+}): Promise<void>;

package/esm/scripts/run-codex-prompts/common/runGoScript/withPromptRuntimeLog.d.ts

@@ -0,0 +1,5 @@
+import type { PromptRoundArtifacts } from './PromptRoundArtifacts';
+/**
+ * Runs one prompt-processing round with a dedicated temporary runtime log file and optionally defers cleanup to the round tracker.
+ */
+export declare function withPromptRuntimeLog<T>(scriptPath: string, handler: (logPath: string) => Promise<T>, promptRoundArtifacts?: PromptRoundArtifacts): Promise<T>;

package/esm/scripts/run-codex-prompts/common/runGoScript/withTempScript.d.ts

@@ -1,5 +1,5 @@
 import type { RunGoScriptOptions } from './RunGoScriptOptions';
 /**
- * Creates a temporary script file, runs a handler, and ensures cleanup.
+ * Creates a temporary script file, runs a handler, and either cleans it up immediately or defers cleanup to the round tracker.
  */
 export declare function withTempScript<T>(options: RunGoScriptOptions, handler: (scriptPath: string) => Promise<T>): Promise<T>;

package/esm/scripts/run-codex-prompts/common/waitForPause.d.ts

@@ -4,5 +4,25 @@
 export declare function listenForPause(): void;
 /**
  * If the execution is paused, it will wait until it is resumed.
+ *
+ * @param options.silent - When `true`, suppresses console output (used when the terminal UI handles display).
+ * @param options.onPaused - Callback invoked when entering the PAUSED state.
+ * @param options.onResumed - Callback invoked when leaving the PAUSED state.
  */
-export declare function checkPause(): Promise<void>;
+export declare function checkPause(options?: {
+    silent?: boolean;
+    onPaused?: () => void;
+    onResumed?: () => void;
+}): Promise<void>;
+/**
+ * Returns the current pause state for external consumers such as the terminal UI.
+ */
+export declare function getPauseState(): 'RUNNING' | 'PAUSING' | 'PAUSED';
+/**
+ * Requests a pause from an external controller (e.g. the Ink UI).
+ */
+export declare function requestPause(): void;
+/**
+ * Resumes execution from an external controller after a pause.
+ */
+export declare function requestResume(): void;

package/esm/scripts/run-codex-prompts/git/commitChanges.d.ts

@@ -1,7 +1,7 @@
 /**
  * Commits staged changes with the provided message using the dedicated coding-agent identity when configured,
- * otherwise falls back to the default Git configuration.
+ * otherwise falls back to the default Git configuration. Remote pushing is opt-in via `options.autoPush`.
  */
 export declare function commitChanges(message: string, options?: {
-    noPush?: boolean;
+    autoPush?: boolean;
 }): Promise<void>;

package/esm/scripts/run-codex-prompts/prompts/formatPromptAttemptMetadata.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Formats optional attempt metadata stored in prompt status lines.
+ */
+export declare function formatPromptAttemptMetadata(status: 'done' | 'failed', attemptCount: number): string;

package/esm/scripts/run-codex-prompts/prompts/markPromptDone.d.ts

@@ -5,4 +5,4 @@ import type { PromptSection } from './types/PromptSection';
 /**
  * Marks a prompt section as done and records usage pricing and runner details.
  */
-export declare function markPromptDone(file: PromptFile, section: PromptSection, usage: Usage, runnerName: string | undefined, modelName: string | undefined, promptExecutionStartedDate: moment.Moment): void;
+export declare function markPromptDone(file: PromptFile, section: PromptSection, usage: Usage, runnerName: string | undefined, modelName: string | undefined, promptExecutionStartedDate: moment.Moment, attemptCount?: number): void;

package/esm/scripts/run-codex-prompts/prompts/markPromptFailed.d.ts

@@ -4,4 +4,4 @@ import type { PromptSection } from './types/PromptSection';
 /**
  * Marks a prompt section as failed and records runner details.
  */
-export declare function markPromptFailed(file: PromptFile, section: PromptSection, runnerName: string | undefined, modelName: string | undefined, promptExecutionStartedDate: moment.Moment): void;
+export declare function markPromptFailed(file: PromptFile, section: PromptSection, runnerName: string | undefined, modelName: string | undefined, promptExecutionStartedDate: moment.Moment, attemptCount?: number): void;

package/esm/scripts/run-codex-prompts/testing/runPromptTestCommand.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Options for running one verification command after a coding attempt.
+ */
+type RunPromptTestCommandOptions = {
+    command: string;
+    projectPath: string;
+    scriptPath: string;
+    logPath?: string;
+};
+/**
+ * Runs the configured verification command inside the project root and returns its output.
+ */
+export declare function runPromptTestCommand(options: RunPromptTestCommandOptions): Promise<string>;
+export {};

package/esm/scripts/run-codex-prompts/testing/runPromptWithTestFeedback.d.ts

@@ -0,0 +1,25 @@
+import type { PromptRunOptions } from '../runners/types/PromptRunOptions';
+import type { PromptRunResult } from '../runners/types/PromptRunResult';
+import type { PromptRunner } from '../runners/types/PromptRunner';
+import { runPromptTestCommand } from './runPromptTestCommand';
+/**
+ * Options for running one prompt with optional verification feedback retries.
+ */
+type RunPromptWithTestFeedbackOptions = PromptRunOptions & {
+    runner: PromptRunner;
+    promptLabel: string;
+    testCommand?: string;
+    onAttemptStarted?: (attemptCount: number) => void;
+    runPromptTestCommandExecutor?: typeof runPromptTestCommand;
+};
+/**
+ * Successful prompt execution result enriched with the number of attempts it took.
+ */
+export type RunPromptWithTestFeedbackResult = PromptRunResult & {
+    attemptCount: number;
+};
+/**
+ * Runs one coding prompt and, when configured, verifies it with a shell command that can feed failures back.
+ */
+export declare function runPromptWithTestFeedback(options: RunPromptWithTestFeedbackOptions): Promise<RunPromptWithTestFeedbackResult>;
+export {};

package/esm/scripts/run-codex-prompts/ui/CoderRunUiState.d.ts

@@ -0,0 +1,112 @@
+/// <reference types="node" />
+import { EventEmitter } from 'events';
+import moment from 'moment';
+import type { PromptStats } from '../prompts/types/PromptStats';
+/**
+ * Execution phase of the coder run process.
+ *
+ * @private internal type of coder run UI
+ */
+export type CoderRunPhase = 'initializing' | 'loading' | 'running' | 'verifying' | 'paused' | 'done' | 'error';
+/**
+ * Configuration display data for the coder run UI header.
+ *
+ * @private internal type of coder run UI
+ */
+export type CoderRunConfig = {
+    readonly agentName: string;
+    readonly modelName?: string;
+    readonly thinkingLevel?: string;
+    readonly context?: string;
+    readonly priority: number;
+    readonly testCommand?: string;
+};
+/**
+ * Computed progress snapshot for the coder run UI.
+ *
+ * @private internal type of coder run UI
+ */
+export type CoderRunProgressSnapshot = {
+    readonly totalPrompts: number;
+    readonly sessionDone: number;
+    readonly sessionTotal: number;
+    readonly percentage: number;
+    readonly elapsedText: string;
+    readonly estimatedTotalText: string;
+    readonly estimatedLabel: string;
+};
+/**
+ * Reactive state manager for the coder run terminal UI.
+ *
+ * Holds all data the Ink components need and emits `'change'` events
+ * whenever any property is updated so the UI can re-render.
+ *
+ * @private internal utility of coder run UI
+ */
+export declare class CoderRunUiState extends EventEmitter {
+    config: CoderRunConfig;
+    currentPromptLabel: string;
+    currentAttempt: number;
+    maxAttempts: number;
+    agentOutputLines: string[];
+    phase: CoderRunPhase;
+    statusMessage: string;
+    errors: string[];
+    private stats;
+    private readonly startTime;
+    private initialDone;
+    /**
+     * Total milliseconds the timer was paused/waiting (excluded from elapsed display).
+     */
+    private pausedMs;
+    /**
+     * Timestamp when the timer was last paused, or `undefined` when running.
+     */
+    private pausedSince;
+    constructor(startTime: moment.Moment);
+    /**
+     * Pauses the elapsed timer (e.g. while waiting for user input or paused state).
+     */
+    pauseTimer(): void;
+    /**
+     * Resumes the elapsed timer after a pause.
+     */
+    resumeTimer(): void;
+    /**
+     * Replaces the configuration shown in the UI header.
+     */
+    setConfig(config: CoderRunConfig): void;
+    /**
+     * Feeds new prompt statistics from the main loop so the progress bar updates.
+     */
+    updateProgress(stats: PromptStats): void;
+    /**
+     * Computes a progress snapshot on demand so elapsed time ticks with periodic re-renders.
+     */
+    getProgress(): CoderRunProgressSnapshot;
+    /**
+     * Sets the label of the prompt currently being processed and resets per-prompt state.
+     */
+    setCurrentPrompt(label: string): void;
+    /**
+     * Updates the current retry attempt number.
+     */
+    setAttempt(attempt: number): void;
+    /**
+     * Appends raw agent output text, keeping only the last `MAX_AGENT_OUTPUT_LINES`.
+     */
+    addAgentOutput(text: string): void;
+    /**
+     * Transitions the execution phase shown in the UI.
+     */
+    setPhase(phase: CoderRunPhase): void;
+    /**
+     * Updates the status message line beneath the current prompt label.
+     */
+    setStatusMessage(message: string): void;
+    /**
+     * Appends an error message to the error list shown in the UI.
+     */
+    addError(errorMessage: string): void;
+    private emitChange;
+}

package/esm/scripts/run-codex-prompts/ui/renderCoderRunUi.d.ts

@@ -0,0 +1,30 @@
+import moment from 'moment';
+import { CoderRunUiState } from './CoderRunUiState';
+/**
+ * Handle returned by `renderCoderRunUi` that exposes the state and lifecycle controls.
+ *
+ * @private internal type of coder run UI
+ */
+export type CoderRunUiHandle = {
+    /** Reactive state the caller updates throughout execution. */
+    readonly state: CoderRunUiState;
+    /** Enables console interception so runner output flows into the UI agent-output area. */
+    startCapturingAgentOutput(): void;
+    /** Disables console interception so normal logging resumes. */
+    stopCapturingAgentOutput(): void;
+    /** Tears down the UI and restores original console methods. */
+    cleanup(): void;
+};
+/**
+ * Boots the ANSI terminal UI for `ptbk coder run`.
+ *
+ * The UI reserves a fixed number of terminal lines and repaints them periodically.
+ * Between repaints, any console output from runners is captured and fed into the
+ * scrolling agent-output area.
+ *
+ * On non-interactive (non-TTY) terminals the UI is skipped entirely and
+ * only the state object is provided.
+ *
+ * @private internal entry point of coder run UI
+ */
+export declare function renderCoderRunUi(startTime: moment.Moment): CoderRunUiHandle;

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

@@ -66,7 +66,8 @@ export type AgentBasicInformation = {
     permanentId?: string_agent_permanent_id;
     /**
      * Optional description of the agent
-     * This is the line starting with "PERSONA"
+     * This is derived from the last `GOAL` / `GOALS` commitment,
+     * falling back to deprecated `PERSONA` / `PERSONAE` for backward compatibility.
      */
     personaDescription: string | null;
     /**

package/esm/src/book-2.0/agent-source/TeammateProfileResolver.d.ts

@@ -9,7 +9,8 @@ export type TeammateProfile = {
      */
     readonly agentName: string;
     /**
-     * Short description of what the agent does, from its PERSONA commitment.
+     * Short profile text for what the agent does, from the last GOAL commitment
+     * or deprecated PERSONA fallback.
      */
     readonly personaDescription: string | null;
 };

package/esm/src/book-components/Chat/Chat/ChatProps.d.ts

@@ -745,7 +745,7 @@ export type ChatProps = {
      * - `BUBBLE_MODE`: keeps the default bubble appearance for all messages.
      * - `ARTICLE_MODE`: keeps user bubbles while rendering assistant replies as borderless article blocks.
      *
-     * @default 'BUBBLE_MODE'
+     * @default 'ARTICLE_MODE'
      */
     readonly CHAT_VISUAL_MODE?: ChatVisualMode;
     /**

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

@@ -0,0 +1,19 @@
+/**
+ * Possible runtime shapes returned when importing the `typescript` package.
+ */
+type ImportedTypescriptModule = typeof import('typescript') | {
+    default: typeof import('typescript');
+};
+/**
+ * Loads the TypeScript runtime used for parsing JSONC-style project files.
+ *
+ * @private internal utility of `coder init`
+ */
+export declare function getTypescriptModule(): Promise<typeof import('typescript')>;
+/**
+ * Normalizes CommonJS-via-`default` and direct namespace imports of TypeScript.
+ *
+ * @private internal utility of `getTypescriptModule`
+ */
+export declare function normalizeImportedTypescriptModule(importedTypescriptModule: ImportedTypescriptModule): typeof import('typescript');
+export {};

package/esm/src/cli/cli-commands/coder/getTypescriptModule.test.d.ts

@@ -0,0 +1 @@
+export {};

package/esm/src/cli/cli-commands/coder/mergeStringRecordJsonFile.test.d.ts

@@ -0,0 +1 @@
+export {};

package/esm/src/commitments/PERSONA/PERSONA.d.ts

@@ -29,6 +29,13 @@ export declare class PersonaCommitmentDefinition extends BaseCommitmentDefinitio
      * Short one-line description of PERSONA.
      */
     get description(): string;
+    /**
+     * Optional UI/docs-only deprecation metadata.
+     */
+    get deprecation(): {
+        readonly message: "Use `GOAL` for agent profile text and inheritance-safe rewrites.";
+        readonly replacedBy: readonly ["GOAL"];
+    };
     /**
      * Icon for this commitment.
      */

package/esm/src/llm-providers/agent/Agent.test.d.ts

@@ -0,0 +1 @@
+export {};

package/esm/src/llm-providers/agent/AgentLlmExecutionTools.d.ts

@@ -44,6 +44,10 @@ export declare class AgentLlmExecutionTools implements LlmExecutionTools {
      * Cached parsed agent information
      */
     private _cachedAgentInfo;
+    /**
+     * Optional server-precomputed model requirements reused until the source changes.
+     */
+    private precomputedModelRequirements;
     /**
      * Creates new AgentLlmExecutionTools
      *

package/esm/src/llm-providers/agent/AgentOptions.d.ts

@@ -1,4 +1,5 @@
 import type { string_book } from '../../book-2.0/agent-source/string_book';
+import type { AgentModelRequirements } from '../../book-2.0/agent-source/AgentModelRequirements';
 import type { CommonToolsOptions } from '../../execution/CommonToolsOptions';
 import type { ExecutionTools } from '../../execution/ExecutionTools';
 import type { Updatable } from '../../types/Updatable';
@@ -27,6 +28,13 @@ export type AgentOptions = CommonToolsOptions & {
      * The source of the agent
      */
     agentSource: Updatable<string_book>;
+    /**
+     * Optional precomputed model requirements reused until `agentSource` changes.
+     *
+     * This keeps the actual runtime prompt aligned with server-prepared requirements
+     * such as compact-reference-resolved `TEAM` tools.
+     */
+    precomputedModelRequirements?: AgentModelRequirements;
     /**
      * Teacher agent for self-learning
      *

package/esm/src/llm-providers/agent/CreateAgentLlmExecutionToolsOptions.d.ts

@@ -1,4 +1,5 @@
 import type { string_book } from '../../book-2.0/agent-source/string_book';
+import type { AgentModelRequirements } from '../../book-2.0/agent-source/AgentModelRequirements';
 import type { CommonToolsOptions } from '../../execution/CommonToolsOptions';
 import type { LlmExecutionTools } from '../../execution/LlmExecutionTools';
 import type { OpenAiAgentKitExecutionTools } from '../openai/OpenAiAgentKitExecutionTools';
@@ -25,4 +26,12 @@ export type CreateAgentLlmExecutionToolsOptions = CommonToolsOptions & {
      * The agent source string that defines the agent's behavior
      */
     agentSource: string_book;
+    /**
+     * Optional precomputed model requirements reused until `agentSource` changes.
+     *
+     * This is useful for runtimes such as Agents Server that already resolved compact
+     * references (for example in `TEAM`) and need the executed prompt to stay aligned
+     * with the server-prepared tool list.
+     */
+    precomputedModelRequirements?: AgentModelRequirements;
 };

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.112.0-41`).
+ * It follows semantic versioning (e.g., `0.112.0-43`).
  *
  * @generated
  */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@promptbook/cli",
-    "version": "0.112.0-42",
+    "version": "0.112.0-44",
     "description": "Promptbook: Turn your company's scattered knowledge into AI ready books",
     "private": false,
     "sideEffects": false,
@@ -129,7 +129,8 @@
         "swagger-ui-express": "5.0.1",
         "type-fest": "4.5.0",
         "userhome": "1.0.1",
-        "waitasecond": "1.11.164"
+        "waitasecond": "1.11.164",
+        "typescript": "5.2.2"
     },
     "bin": {
         "promptbook": "bin/promptbook-cli.js",