@promptbook/cli 0.112.0-41 → 0.112.0-43

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/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,13 @@
+/**
+ * Options for running one verification command after a coding attempt.
+ */
+type RunPromptTestCommandOptions = {
+    command: string;
+    projectPath: string;
+    scriptPath: 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/scripts/verify-prompts/verify-prompts.d.ts

@@ -1,8 +1,29 @@
+import type { PromptFile } from '../run-codex-prompts/prompts/types/PromptFile';
+/**
+ * Options supported by the prompt verification helper.
+ */
+export type VerifyPromptsOptions = {
+    /**
+     * Process prompt files in reverse order.
+     */
+    readonly reverse?: boolean;
+    /**
+     * Ignore prompt files whose filename or first prompt line contains one of the provided values.
+     */
+    readonly ignore?: ReadonlyArray<string>;
+};
 /**
  * Starts the verification loop and exits when no `[ ]` prompts remain.
  *
- * @param reverse - Process files in reverse order
+ * @public exported from `@promptbook/cli`
+ */
+export declare function verifyPrompts(options?: VerifyPromptsOptions): Promise<void>;
+/**
+ * Splits prompt files into files that should be verified now and files ignored for this run.
  *
  * @public exported from `@promptbook/cli`
  */
-export declare function verifyPrompts(reverse?: boolean): Promise<void>;
+export declare function partitionPromptFilesByIgnore(promptFiles: ReadonlyArray<PromptFile>, ignoreValues: ReadonlyArray<string>): {
+    promptFiles: PromptFile[];
+    ignoredPromptFiles: PromptFile[];
+};

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/cli/cli-commands/coder/verify.test.d.ts

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

package/esm/src/collection/agent-collection/constructors/agent-collection-in-supabase/AgentCollectionInSupabase.d.ts

@@ -4,23 +4,11 @@ import type { string_book } from '../../../../book-2.0/agent-source/string_book'
 import type { string_agent_name, string_agent_permanent_id } from '../../../../types/typeAliases';
 import { AgentCollectionInSupabaseOptions } from './AgentCollectionInSupabaseOptions';
 import type { AgentsDatabaseSchema } from './AgentsDatabaseSchema';
+import { type CreateAgentPersistenceRecordsOptions } from './createAgentPersistenceRecords';
 /**
  * Options for creating a new agent entry.
  */
-type CreateAgentOptions = {
-    /**
-     * Visibility for the new agent.
-     */
-    readonly visibility?: 'PRIVATE' | 'UNLISTED' | 'PUBLIC';
-    /**
-     * Folder identifier to assign the new agent to.
-     */
-    readonly folderId?: number | null;
-    /**
-     * Sort order for the agent within its parent folder.
-     */
-    readonly sortOrder?: number;
-};
+type CreateAgentOptions = CreateAgentPersistenceRecordsOptions;
 /**
  * Optional controls for persisting one source update.
  */

package/esm/src/collection/agent-collection/constructors/agent-collection-in-supabase/createAgentPersistenceRecords.d.ts

@@ -0,0 +1,40 @@
+import type { AgentBasicInformation } from '../../../../book-2.0/agent-source/AgentBasicInformation';
+import type { string_book } from '../../../../book-2.0/agent-source/string_book';
+import type { CreateAgentInput } from '../../CreateAgentInput';
+import type { AgentsDatabaseSchema } from './AgentsDatabaseSchema';
+/**
+ * Optional persistence overrides for one new agent row.
+ *
+ * @private shared persistence helper for `AgentCollectionInSupabase`
+ */
+export type CreateAgentPersistenceRecordsOptions = Omit<CreateAgentInput, 'source'>;
+/**
+ * Prepared insert rows and returned profile for one newly persisted agent.
+ *
+ * @private shared persistence helper for `AgentCollectionInSupabase`
+ */
+export type CreateAgentPersistenceRecordsResult = {
+    /**
+     * Parsed created agent profile including the resolved permanent id.
+     */
+    readonly createdAgent: AgentBasicInformation & Required<Pick<AgentBasicInformation, 'permanentId'>>;
+    /**
+     * Insert row for the `Agent` table.
+     */
+    readonly agentInsertRecord: AgentsDatabaseSchema['public']['Tables']['Agent']['Insert'];
+    /**
+     * Insert row for the `AgentHistory` table.
+     */
+    readonly agentHistoryInsertRecord: AgentsDatabaseSchema['public']['Tables']['AgentHistory']['Insert'];
+};
+/**
+ * Builds normalized insert rows for a newly created persisted agent.
+ *
+ * @param agentSource - Source content of the agent.
+ * @param options - Optional folder placement, ordering, and visibility overrides.
+ * @param createdAt - Shared creation timestamp used across all persisted rows.
+ * @returns Insert rows and the created agent profile.
+ *
+ * @private shared persistence helper for `AgentCollectionInSupabase`
+ */
+export declare function createAgentPersistenceRecords(agentSource: string_book, options?: CreateAgentPersistenceRecordsOptions, createdAt?: string): CreateAgentPersistenceRecordsResult;

package/esm/src/collection/agent-collection/constructors/agent-collection-in-supabase/createAgentPersistenceRecords.test.d.ts

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@promptbook/cli",
-    "version": "0.112.0-41",
+    "version": "0.112.0-43",
     "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",

package/umd/apps/agents-server/src/database/acquireMigrationExecutionLock.d.ts

@@ -1,14 +1,25 @@
 import type { Client } from 'pg';
 import type { DatabaseMigrationLogger } from './runDatabaseMigrations';
+/**
+ * Lock-acquisition strategies used by the migration runner.
+ *
+ * `wait` is appropriate for explicit/manual migration flows where the caller expects one serialized run.
+ * `skip` is appropriate for background startup checks where waiting would block request handling.
+ *
+ * @private function of runDatabaseMigrations
+ */
+export type DatabaseMigrationExecutionLockMode = 'wait' | 'skip';
 /**
  * Acquires advisory lock preventing concurrent migration execution across processes.
  *
  * @param client Connected PostgreSQL client.
  * @param logger Logger used for progress output.
+ * @param mode Whether the caller should block for the lock or skip when it is already held.
+ * @returns `true` when the lock was acquired and migrations may proceed.
  *
  * @private function of runDatabaseMigrations
  */
-export declare function acquireMigrationExecutionLock(client: Client, logger: DatabaseMigrationLogger): Promise<void>;
+export declare function acquireMigrationExecutionLock(client: Client, logger: DatabaseMigrationLogger, mode?: DatabaseMigrationExecutionLockMode): Promise<boolean>;
 /**
  * Releases advisory lock used for migration execution.
  *

package/umd/apps/agents-server/src/database/runDatabaseMigrations.d.ts

@@ -1,4 +1,5 @@
 import { type ServerRecord } from '../utils/serverRegistry';
+import { type DatabaseMigrationExecutionLockMode } from './acquireMigrationExecutionLock';
 /**
  * Allowed values describing who applied a migration record.
  */
@@ -67,6 +68,10 @@ export type RunDatabaseMigrationsOptions = {
      * If true, prints every SQL migration body before execution.
      */
     readonly logSqlStatements?: boolean;
+    /**
+     * Whether migration execution should wait for the advisory lock or skip when another process already owns it.
+     */
+    readonly executionLockMode?: DatabaseMigrationExecutionLockMode;
 };
 /**
  * Result of one prefix migration run.
@@ -97,6 +102,10 @@ export type RunDatabaseMigrationsResult = {
      * Per-prefix summary.
      */
     readonly perPrefix: ReadonlyArray<DatabaseMigrationPrefixResult>;
+    /**
+     * Whether migration execution was skipped because another process already held the advisory lock.
+     */
+    readonly isSkippedDueToActiveMigrationLock: boolean;
 };
 /**
  * Reads migration runtime configuration from environment variables and `_Server`.