@promptbook/javascript 0.114.0-2 → 0.114.0-21

package/esm/src/book-components/Chat/utils/renderMarkdown.d.ts

@@ -1,4 +1,22 @@
 import type { string_html, string_markdown } from '../../../types/string_markdown';
+/**
+ * Attribute marking a client action generated for an inline-reference menu.
+ *
+ * @private utility shared with `MarkdownContent`
+ */
+export declare const MARKDOWN_INLINE_REFERENCE_MENU_ACTION_ATTRIBUTE = "data-promptbook-inline-reference-menu-action";
+/**
+ * Attribute identifying the inline reference which owns a client menu action.
+ *
+ * @private utility shared with `MarkdownContent`
+ */
+export declare const MARKDOWN_INLINE_REFERENCE_MENU_ACTION_REFERENCE_ATTRIBUTE = "data-promptbook-inline-reference-menu-action-reference";
+/**
+ * Attribute marking a favicon rendered inside an inline-reference chip.
+ *
+ * @private utility shared with `MarkdownContent`
+ */
+export declare const MARKDOWN_INLINE_REFERENCE_ICON_ATTRIBUTE = "data-promptbook-inline-reference-icon";
 /**
  * Options for markdown rendering.
  */
@@ -17,6 +35,13 @@ export type MarkdownInlineReference = {
      * Raw reference text between `[[` and `]]`.
      */
     readonly reference: string;
+    /**
+     * Optional text aliases which should render as this reference when an agent mentions them in markdown.
+     *
+     * They are also accepted inside a `[[reference]]` token. This lets application code use a stable
+     * technical reference while recognizing a human-facing name in older messages.
+     */
+    readonly sourceTextAliases?: ReadonlyArray<string>;
     /**
      * Human-readable label rendered inside the link chip.
      */
@@ -26,21 +51,42 @@ export type MarkdownInlineReference = {
      */
     readonly href: string;
     /**
-     * Markdown link destination prefixes that should render as this reference as well.
+     * Optional URL prefixes which also identify this reference in the authored markdown.
      *
-     * This supports legacy links such as an Agents Server project file URL while keeping
-     * `reference` as the canonical `[[project]]` token.
+     * A markdown link or a bare URL pointing to one of these prefixes is rendered as the same chip
+     * as the `[[reference]]` token. Both absolute URLs (for example `https://project.example.com`)
+     * and application paths (for example `/agents/agent/projects/website`) are supported; a path
+     * prefix matches on any host so that both relative and absolute links are recognized.
      */
     readonly sourceHrefPrefixes?: ReadonlyArray<string>;
     /**
      * Optional hover title for the rendered reference.
      */
     readonly title?: string;
+    /**
+     * Optional favicon and text fallback rendered before the reference label.
+     */
+    readonly icon?: MarkdownInlineReferenceIcon;
     /**
      * Optional expandable menu shown when the reference chip is clicked.
      */
     readonly menu?: MarkdownInlineReferenceMenu;
 };
+/**
+ * Visual identity rendered inside one markdown inline-reference chip.
+ *
+ * @public exported from `@promptbook/components`
+ */
+export type MarkdownInlineReferenceIcon = {
+    /**
+     * Optional image URL. The fallback remains visible when the image is unavailable.
+     */
+    readonly src?: string | null;
+    /**
+     * Short text rendered when the image is missing or broken.
+     */
+    readonly fallbackText: string;
+};
 /**
  * Status displayed alongside an expandable markdown inline reference.
  *
@@ -74,6 +120,25 @@ export type MarkdownInlineReferenceMenuOption = {
      * Optional hover text for the option.
      */
     readonly title?: string;
+    /**
+     * Optional client action rendered as a button instead of a link.
+     */
+    readonly action?: MarkdownInlineReferenceMenuAction;
+};
+/**
+ * Client-side action exposed by an expandable markdown inline-reference menu.
+ *
+ * @public exported from `@promptbook/components`
+ */
+export type MarkdownInlineReferenceMenuAction = {
+    /**
+     * Stable identifier unique within the owning reference menu.
+     */
+    readonly id: string;
+    /**
+     * Callback invoked when the menu button is selected.
+     */
+    readonly onSelect: () => void | Promise<void>;
 };
 /**
  * Expandable menu configuration for a markdown inline reference.

package/esm/src/book-components/Chat/utils/timeoutToolCallPresentation.d.ts

@@ -1,4 +1,22 @@
 import type { TODO_any } from '../../../utils/organization/TODO_any';
+/**
+ * Tool name of one scheduled wake-up, used by every producer of timeout chips.
+ *
+ * @private internal timeout-chat constant
+ */
+export declare const SET_TIMEOUT_TOOL_CALL_NAME = "set_timeout";
+/**
+ * Tool name of one re-planned wake-up, used by every producer of timeout chips.
+ *
+ * @private internal timeout-chat constant
+ */
+export declare const UPDATE_TIMEOUT_TOOL_CALL_NAME = "update_timeout";
+/**
+ * Tool name of one cancelled wake-up, used by every producer of timeout chips.
+ *
+ * @private internal timeout-chat constant
+ */
+export declare const CANCEL_TIMEOUT_TOOL_CALL_NAME = "cancel_timeout";
 /**
  * Action performed by timeout tools.
  *
@@ -140,4 +158,16 @@ export declare function buildTimeoutToolPrimarySentence(presentation: TimeoutToo
  * @private internal utility of `<Chat/>`
  */
 export declare function buildTimeoutToolScheduleSentence(presentation: TimeoutToolCallPresentation, translations?: TimeoutToolCallTranslations): string | null;
+/**
+ * Converts timeout duration into natural language sentence fragments.
+ *
+ * Shared by every timeout surface: the chat chips, the goal-chat planned messages of the Agents
+ * Server, and the planned-message prompt section of the agent-folder runner.
+ *
+ * @param milliseconds - Duration or repeat interval in milliseconds.
+ * @returns Label such as `5 minutes` or `1 hour 30 minutes`.
+ *
+ * @private internal utility of `<Chat/>` and the Agents Server planned messages
+ */
+export declare function formatTimeoutDurationHuman(milliseconds: number): string;
 export {};

package/esm/src/cli/cli-commands/agents-server/buildAgentsServer/createAgentsServerRuntimeEnvironment.d.ts

@@ -18,6 +18,12 @@ export declare const PTBK_AGENTS_SERVER_BUILD_WORKER_COUNT_ENV = "PTBK_AGENTS_SE
  * @private internal constant of `buildAgentsServer`
  */
 export declare const PTBK_AGENTS_SERVER_IGNORE_NEXT_VALIDATION_ENV = "PTBK_AGENTS_SERVER_IGNORE_NEXT_VALIDATION";
+/**
+ * Environment variable that disables throwaway webpack filesystem caches for CLI-owned production builds.
+ *
+ * @private internal constant of `buildAgentsServer`
+ */
+export declare const PTBK_AGENTS_SERVER_DISABLE_WEBPACK_FILESYSTEM_CACHE_ENV = "PTBK_AGENTS_SERVER_DISABLE_WEBPACK_FILESYSTEM_CACHE";
 /**
  * Adds dependency-resolution environment required by the materialized Agents Server runtime.
  *
@@ -25,4 +31,5 @@ export declare const PTBK_AGENTS_SERVER_IGNORE_NEXT_VALIDATION_ENV = "PTBK_AGENT
  */
 export declare function createAgentsServerRuntimeEnvironment(environment: NodeJS.ProcessEnv, nodeModulesPath: string, options?: {
     readonly isNextValidationIgnored?: boolean;
+    readonly isWebpackFilesystemCacheDisabled?: boolean;
 }): NodeJS.ProcessEnv;

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

@@ -0,0 +1,28 @@
+/**
+ * Supported values of the `--git-changes` option, which decides what happens with a dirty working tree.
+ *
+ * - `fail` — refuse to start while the working tree has uncommitted changes
+ * - `ignore` — start anyway and leave the uncommitted changes where they are
+ * - `continue` — resume the single prompt which was left in the middle of its implementation
+ *
+ * @private internal shared utility of `ptbk coder run`
+ */
+export declare const GIT_CHANGES_MODE_VALUES: readonly ["fail", "ignore", "continue"];
+/**
+ * Behavior requested for a working tree which has uncommitted changes.
+ *
+ * @private internal shared utility of `ptbk coder run`
+ */
+export type GitChangesMode = (typeof GIT_CHANGES_MODE_VALUES)[number];
+/**
+ * Mode applied when `--git-changes` is not used at all.
+ *
+ * @private internal shared utility of `ptbk coder run`
+ */
+export declare const DEFAULT_GIT_CHANGES_MODE: GitChangesMode;
+/**
+ * Checks whether a value is a supported `--git-changes` mode.
+ *
+ * @private internal shared utility of `ptbk coder run`
+ */
+export declare function isGitChangesMode(value: string): value is GitChangesMode;

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

@@ -0,0 +1,52 @@
+/**
+ * How many prompt boilerplate files are generated and how many prompts each of them contains.
+ *
+ * @private internal utility of `ptbk coder`
+ */
+export type BoilerplateCount = {
+    /**
+     * Number of generated prompt boilerplate files.
+     */
+    readonly filesCount: number;
+    /**
+     * Number of prompts written into each generated file.
+     *
+     * Note: More than one prompt per file is an advanced option - each prompt is one separate
+     *       coding task separated by `---`, with all prompts in the file sharing its fresh emoji tag.
+     */
+    readonly promptsPerFileCount: number;
+};
+/**
+ * Number of prompt boilerplate files and prompts per file used when `--count` is not provided.
+ *
+ * @private internal utility of `ptbk coder`
+ */
+export declare const DEFAULT_BOILERPLATE_COUNT: BoilerplateCount;
+/**
+ * Formats one boilerplate count back into the `N*M` notation of the `--count` option.
+ *
+ * @private internal utility of `ptbk coder`
+ */
+export declare function formatBoilerplateCount({ filesCount, promptsPerFileCount }: BoilerplateCount): string;
+/**
+ * Default value of the `--count` option rendered in the `N*M` notation, for example `5*1`.
+ *
+ * @private internal utility of `ptbk coder`
+ */
+export declare const DEFAULT_BOILERPLATE_COUNT_OPTION_VALUE: string;
+/**
+ * Description of the `--count` option shared by all commands which generate prompt boilerplates.
+ *
+ * @private internal utility of `ptbk coder`
+ */
+export declare const BOILERPLATE_COUNT_OPTION_DESCRIPTION: string;
+/**
+ * Parses the `--count` option value into the number of files and the number of prompts in each of them.
+ *
+ * Both notations are supported:
+ * - `N` and `N*1` => N files with one prompt each
+ * - `N*M` => N files with M prompts each
+ *
+ * @private internal utility of `ptbk coder`
+ */
+export declare function parseBoilerplateCount(countOption: string): BoilerplateCount;

package/esm/src/cli/cli-commands/coder/generate-boilerplates.d.ts

@@ -1,5 +1,6 @@
 import type { Command as Program } from 'commander';
 import type { $side_effect } from '../../../utils/organization/$side_effect';
+import type { BoilerplateCount } from './boilerplateCount';
 /**
  * Initializes `coder generate-boilerplates` command for Promptbook CLI utilities
  *
@@ -9,12 +10,12 @@ import type { $side_effect } from '../../../utils/organization/$side_effect';
  */
 export declare function $initializeCoderGenerateBoilerplatesCommand(program: Program): $side_effect;
 /**
- * Generates boilerplate prompt files with unique emoji tags.
+ * Generates boilerplate prompt files with one unique emoji tag per file.
  *
  * @private internal function of `generatePromptBoilerplate` command
  */
-export declare function generatePromptBoilerplate({ projectPath, filesCount, templateOption, }: {
+export declare function generatePromptBoilerplate({ projectPath, boilerplateCount, templateOption, }: {
     readonly projectPath: string;
-    readonly filesCount: number;
+    readonly boilerplateCount: BoilerplateCount;
     readonly templateOption?: string;
 }): Promise<void>;

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

@@ -1,12 +1,9 @@
 import type { Command as Program } from 'commander';
 import type { $side_effect } from '../../../utils/organization/$side_effect';
 /**
- * Initializes `coder ping` command for Promptbook CLI utilities.
+ * Initializes `coder ping` command for Promptbook CLI utilities
  *
- * The command makes one small, isolated harness/model call, prints its result
- * and reports how long the harness/model turn took.
- *
- * Note: `$` is used to indicate that this function is not a pure function - it registers a command in the CLI.
+ * Note: `$` is used to indicate that this function is not a pure function - it registers a command in the CLI
  *
  * @private internal function of `promptbookCli`
  */

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

@@ -1,4 +1,4 @@
-import type { Command as Program } from 'commander';
+import { Command as Program } from 'commander';
 import type { $side_effect } from '../../../utils/organization/$side_effect';
 /**
  * Initializes `coder verify` command for Promptbook CLI utilities

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

@@ -8,8 +8,8 @@ import type { $side_effect } from '../../utils/organization/$side_effect';
  * - add: Add one ready-to-run prompt file to the queue
  * - generate-boilerplates: Generate prompt boilerplate files
  * - find-refactor-candidates: Find files that need refactoring
- * - ping: Test one harness and model connection with a disposable task
  * - run: Run coding prompts with AI agents
+ * - ping: Test one harness and model with a tiny dummy prompt
  * - verify: Verify completed prompts
  * - find-fresh-emoji-tags: Find unused emoji tags
  *

package/esm/src/cli/cli-commands/common/coderGitSyncCliOptions.d.ts

@@ -0,0 +1,34 @@
+import type { Command as Program } from 'commander';
+import type { CoderGitSyncOptions } from '../../../../scripts/run-codex-prompts/git/coderGitSync';
+export type { CoderGitSyncOptions };
+/**
+ * Commander option bag for the shared `ptbk coder` git synchronization flags.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type CoderGitSyncCliOptions = {
+    readonly commit: boolean;
+    readonly autoPush: boolean;
+    readonly autoPull: boolean;
+};
+/**
+ * Description block shared by the `ptbk coder` commands which can synchronize their changes with git.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare const CODER_GIT_SYNC_DESCRIPTION: string;
+/**
+ * Registers the shared `--commit`, `--auto-push` and `--auto-pull` flags on a `ptbk coder` command.
+ *
+ * Note: Unlike `ptbk coder run`, which commits by default and opts out through `--no-commit`,
+ *       these commands never touch git unless the flags are used explicitly.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function addCoderGitSyncOptions(command: Program): void;
+/**
+ * Converts the Commander git synchronization flags into normalized git synchronization options.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function normalizeCoderGitSyncCliOptions(cliOptions: CoderGitSyncCliOptions): CoderGitSyncOptions;

package/esm/src/cli/cli-commands/common/harness/$checkHarnessInstallation.d.ts

@@ -1,10 +1,10 @@
 import type { HarnessDefinition } from './HarnessDefinition';
 import type { HarnessInstallationStatus } from './HarnessInstallationStatus';
 /**
- * Detects whether one CLI coding harness is installed globally and whether it is up to date.
+ * Detects whether one CLI coding harness is installed globally and, when enabled, whether it is up to date.
  *
- * Note: `$` is used to indicate that this function is not a pure function - it runs the harness command and queries npm
+ * Note: `$` is used to indicate that this function is not a pure function - it runs the harness command and may query npm
  *
  * @private internal utility of `promptbookCli`
  */
-export declare function $checkHarnessInstallation(definition: HarnessDefinition): Promise<HarnessInstallationStatus>;
+export declare function $checkHarnessInstallation(definition: HarnessDefinition, isHarnessUpdateCheckEnabled?: boolean): Promise<HarnessInstallationStatus>;

package/esm/src/cli/cli-commands/common/harness/$ensureHarnessInstallations.d.ts

@@ -1,7 +1,7 @@
 import type { PromptRunnerHarnessName } from '../promptRunnerCliOptions';
 /**
- * Checks that every given CLI coding harness is installed globally and up to date and offers to
- * install or update the ones which are not.
+ * Checks that every given CLI coding harness is installed globally and, when enabled, up to date.
+ * Offers to install missing harnesses and update outdated ones.
  *
  * Harness names which are `undefined`, for example when no `--harness` is selected in a dry run,
  * are ignored so that every call site can pass its raw selection.
@@ -10,4 +10,4 @@ import type { PromptRunnerHarnessName } from '../promptRunnerCliOptions';
  *
  * @private internal utility of `promptbookCli`
  */
-export declare function $ensureHarnessInstallations(harnessNames: ReadonlyArray<PromptRunnerHarnessName | undefined>): Promise<void>;
+export declare function $ensureHarnessInstallations(harnessNames: ReadonlyArray<PromptRunnerHarnessName | undefined>, isHarnessUpdateCheckEnabled?: boolean): Promise<void>;

package/esm/src/cli/cli-commands/common/harness/HarnessInstallationStatus.d.ts

@@ -5,11 +5,12 @@ import type { HarnessDefinition } from './HarnessDefinition';
  * - `up-to-date` the newest published version is installed
  * - `outdated` an older version is installed
  * - `not-installed` the harness command is not available globally
+ * - `installed` the harness is installed and automatic update checking was disabled
  * - `unknown` the harness is installed but the newest published version could not be resolved, for example when offline
  *
  * @private internal utility of `promptbookCli`
  */
-export type HarnessInstallationState = 'up-to-date' | 'outdated' | 'not-installed' | 'unknown';
+export type HarnessInstallationState = 'up-to-date' | 'outdated' | 'not-installed' | 'installed' | 'unknown';
 /**
  * Installation state of one CLI coding harness on the current machine.
  *
@@ -21,7 +22,7 @@ export type HarnessInstallationStatus = {
      */
     readonly definition: HarnessDefinition;
     /**
-     * Comparison of the installed version with the newest published one.
+     * Installation state, including whether the newest published version was checked.
      */
     readonly installationState: HarnessInstallationState;
     /**

package/esm/src/cli/cli-commands/common/harnessUpdateCliOptions.d.ts

@@ -0,0 +1,29 @@
+import type { Command as Program } from 'commander';
+/**
+ * Commander option bag for opting out of automatic coding-harness update checks.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type HarnessUpdateCliOptions = {
+    readonly harnessUpdate: boolean;
+};
+/**
+ * Normalized automatic coding-harness update-check option.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type NormalizedHarnessUpdateCliOptions = {
+    readonly isHarnessUpdateCheckEnabled: boolean;
+};
+/**
+ * Registers the shared `--no-harness-update` option on a `ptbk coder` command that uses a coding harness.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function addHarnessUpdateOption(command: Program): void;
+/**
+ * Converts the Commander harness-update flag into the normalized harness-check option.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function normalizeHarnessUpdateCliOptions(cliOptions: HarnessUpdateCliOptions): NormalizedHarnessUpdateCliOptions;

package/esm/src/cli/cli-commands/common/{harness/$askForHarnessInstallationApproval.d.ts → npm/$askForNpmPackageInstallationApproval.d.ts}

@@ -1,9 +1,9 @@
 /**
- * Asks the user in the terminal whether the harness should be installed or updated right now.
+ * Asks the user in the terminal whether an npm package should be installed or updated now.
  *
  * Note: `$` is used to indicate that this function is not a pure function - it reads the answer from stdin
  *
  * @returns `true` when the user confirms, `false` when the user declines or the terminal is not interactive
  * @private internal utility of `promptbookCli`
  */
-export declare function $askForHarnessInstallationApproval(question: string): Promise<boolean>;
+export declare function $askForNpmPackageInstallationApproval(question: string): Promise<boolean>;

package/{umd/src/cli/cli-commands/common/harness/$resolveLatestHarnessVersion.d.ts → esm/src/cli/cli-commands/common/npm/$resolveLatestNpmPackageVersion.d.ts}

@@ -1,10 +1,9 @@
-import type { HarnessDefinition } from './HarnessDefinition';
 /**
- * Reads the newest version of the harness published to npm.
+ * Reads the newest version of one npm package.
  *
  * Note: `$` is used to indicate that this function is not a pure function - it queries the npm registry
  *
  * @returns The newest published version or `null` when the registry could not be reached
  * @private internal utility of `promptbookCli`
  */
-export declare function $resolveLatestHarnessVersion(definition: HarnessDefinition): Promise<string | null>;
+export declare function $resolveLatestNpmPackageVersion(npmPackageName: string): Promise<string | null>;

package/esm/src/cli/cli-commands/common/npm/buildNpmPackageInstallCommand.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Place where an npm package should be installed or updated.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type NpmPackageInstallationLocation = 'local-dependency' | 'local-development-dependency' | 'global';
+/**
+ * Builds an npm command which installs or updates a package in the requested existing location.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function buildNpmPackageInstallCommand(npmPackageName: string, installationLocation: NpmPackageInstallationLocation): string;

package/esm/src/cli/cli-commands/common/npm/extractNpmPackageVersionFromOutput.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Extracts an npm package version from raw command output.
+ *
+ * Both npm and CLI commands may emit unrelated warnings before the version. CLI commands use the first matching token;
+ * npm registry commands can opt into the last matching token because npm warnings commonly precede their output.
+ *
+ * @returns The parsed version or `null` when the output contains no version
+ * @private internal utility of `promptbookCli`
+ */
+export declare function extractNpmPackageVersionFromOutput(output: string, { isLastMatchPreferred }?: {
+    readonly isLastMatchPreferred?: boolean;
+}): string | null;

package/esm/src/cli/cli-commands/common/npm/isNpmPackageVersionOutdated.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Compares an installed npm package version with the newest published version.
+ *
+ * Release and prerelease identifiers follow semantic-version precedence while build metadata is ignored. Harnesses can
+ * preserve their historical behavior by setting `isPrereleaseIgnored`, because some harness commands report a build
+ * suffix which does not correspond to npm release precedence.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function isNpmPackageVersionOutdated(installedVersion: string, latestVersion: string, { isPrereleaseIgnored }?: {
+    readonly isPrereleaseIgnored?: boolean;
+}): boolean;

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

@@ -1,5 +1,6 @@
 import { Command as Program } from 'commander';
 import { PTBK_HARNESS_ENV, PTBK_MODEL_ENV, PTBK_THINKING_LEVEL_ENV } from '../../../book-3.0/cliAgentEnv';
+import type { GitChangesMode } from '../coder/GitChangesMode';
 import type { ThinkingLevel } from '../coder/ThinkingLevel';
 export { PTBK_HARNESS_ENV, PTBK_MODEL_ENV, PTBK_THINKING_LEVEL_ENV };
 /**
@@ -25,7 +26,7 @@ export type PromptRunnerCliOptions = {
     readonly ui: boolean;
     readonly thinkingLevel?: ThinkingLevel;
     readonly commit: boolean;
-    readonly ignoreGitChanges: boolean;
+    readonly gitChanges: GitChangesMode;
     readonly allowCredits: boolean;
     readonly normalizeLineEndings: boolean;
     readonly autoPush: boolean;
@@ -48,7 +49,7 @@ export type NormalizedPromptRunnerCliOptions = {
     readonly noUi: boolean;
     readonly thinkingLevel?: ThinkingLevel;
     readonly noCommit: boolean;
-    readonly ignoreGitChanges: boolean;
+    readonly gitChanges: GitChangesMode;
     readonly allowCredits: boolean;
     readonly normalizeLineEndings: boolean;
     readonly autoPush: boolean;
@@ -78,6 +79,12 @@ export declare const PROMPT_RUNNER_HARNESS_OPTION_DESCRIPTION = "Select runner:
  * @private internal utility of `promptbookCli`
  */
 export declare const PROMPT_RUNNER_MODEL_OPTION_DESCRIPTION: string;
+/**
+ * Commander description for the `--git-changes` option.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare const GIT_CHANGES_OPTION_DESCRIPTION: string;
 /**
  * Registers runner selection flags on a command.
  *

package/esm/src/cli/cli-commands/common/promptbook-cli/$checkPromptbookCliInstallations.d.ts

@@ -0,0 +1,9 @@
+import type { PromptbookCliInstallationStatus } from './PromptbookCliInstallationStatus';
+/**
+ * Checks every local and global Promptbook CLI installation against the newest npm version.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it reads installed packages and queries npm
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function $checkPromptbookCliInstallations(): Promise<ReadonlyArray<PromptbookCliInstallationStatus>>;

package/esm/src/cli/cli-commands/common/promptbook-cli/$ensurePromptbookCliInstallations.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Checks local and global Promptbook CLI installations before an interactive coder run and offers to update them.
+ *
+ * Once an update succeeds, the caller must stop the current run and let the user start a fresh process. A local npm
+ * update can modify `package.json` and a lockfile, which would make the coder's clean-working-tree preflight fail;
+ * the current Node.js process has also already loaded the old CLI implementation.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it reads package manifests, queries npm,
+ * asks the user, and may install npm packages
+ *
+ * @returns `true` when at least one installation was updated and the current coder run should stop
+ * @private internal utility of `promptbookCli`
+ */
+export declare function $ensurePromptbookCliInstallations(): Promise<boolean>;

package/esm/src/cli/cli-commands/common/promptbook-cli/$resolvePromptbookCliInstallations.d.ts

@@ -0,0 +1,12 @@
+import { type PromptbookCliInstallation } from './PromptbookCliInstallation';
+/**
+ * Finds every directly declared local or directly installed global Promptbook CLI package which can be updated.
+ *
+ * Transitive packages are deliberately ignored because this command must update the dependency chosen by the current
+ * project or global npm installation, not mutate a dependency owned by another package.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it reads package manifests and runs npm
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function $resolvePromptbookCliInstallations(): Promise<ReadonlyArray<PromptbookCliInstallation>>;

package/esm/src/cli/cli-commands/common/promptbook-cli/$updatePromptbookCliInstallation.d.ts

@@ -0,0 +1,10 @@
+import type { PromptbookCliInstallationStatus } from './PromptbookCliInstallationStatus';
+/**
+ * Updates one Promptbook CLI package in its existing local or global location.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it installs an npm package
+ *
+ * @returns `true` when the package update succeeds, `false` when it fails
+ * @private internal utility of `promptbookCli`
+ */
+export declare function $updatePromptbookCliInstallation(status: PromptbookCliInstallationStatus): Promise<boolean>;