@promptbook/cli 0.114.0-3 → 0.114.0-30

package/umd/src/book-components/Chat/utils/externalSourceToolCall.d.ts

@@ -0,0 +1,38 @@
+import type { AgentMessageTouchedExternalSource } from '../../../utils/agent-message-runtime/AgentMessageTouchedExternalSource';
+/**
+ * Synthetic tool name used for external-source chips in chat UI.
+ *
+ * The Agents Server emits one such tool call per source outside the agent an answer viewed or
+ * edited, so the chat shows which services, websites and searches the agent really reached below
+ * the message that touched them. Work the agent does inside itself emits nothing.
+ *
+ * @private internal chat-ui marker for touched external sources
+ */
+export declare const EXTERNAL_SOURCE_TOOL_CALL_NAME = "external_source_touched";
+/**
+ * Parses the external-source chip payload from one tool result.
+ *
+ * @param result - Raw tool result payload.
+ * @returns Parsed source metadata, or `null` when the result describes no external source.
+ *
+ * @private internal helper reused by chip and modal rendering
+ */
+export declare function parseExternalSourceToolCallResult(result: unknown): AgentMessageTouchedExternalSource | null;
+/**
+ * Resolves the chip label of one touched external source.
+ *
+ * @param externalSource - Parsed source metadata.
+ * @returns User-facing name of the source.
+ *
+ * @private internal helper reused by chip and modal rendering
+ */
+export declare function resolveExternalSourceToolCallLabel(externalSource: AgentMessageTouchedExternalSource): string;
+/**
+ * Resolves the chip emoji of one touched external source.
+ *
+ * @param externalSource - Parsed source metadata.
+ * @returns Emoji telling apart an integration, a website and a search.
+ *
+ * @private internal helper reused by chip and modal rendering
+ */
+export declare function resolveExternalSourceToolCallEmoji(externalSource: AgentMessageTouchedExternalSource): string;

package/umd/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/umd/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/umd/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/umd/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/umd/src/cli/cli-commands/coder/boilerplateCount.test.d.ts

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

package/umd/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/umd/src/cli/cli-commands/coder/generate-boilerplates.test.d.ts

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

package/umd/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/umd/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/umd/src/cli/cli-commands/common/harness/$applyHarnessInstallationStatus.d.ts

@@ -2,7 +2,7 @@ import type { HarnessInstallationStatus } from './HarnessInstallationStatus';
 /**
  * Reports one detected harness installation status and offers to install or update the harness.
  *
- * Note: `$` is used to indicate that this function is not a pure function - it asks the user and installs npm packages
+ * Note: `$` is used to indicate that this function is not a pure function - it asks the user and installs software
  *
  * @private internal utility of `promptbookCli`
  */

package/umd/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/umd/src/cli/cli-commands/common/harness/$checkHarnessInstallation.test.d.ts

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

package/umd/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/umd/src/cli/cli-commands/common/harness/$resolveHarnessCommandPath.d.ts

@@ -0,0 +1,14 @@
+import type { HarnessDefinition } from './HarnessDefinition';
+/**
+ * Finds out which file is really executed when the harness command runs.
+ *
+ * The lookup deliberately uses the very same `PATH` which runs the harness, so it reports the copy of the
+ * harness which Promptbook itself would use. Symbolic links are followed, because installers like the
+ * standalone OpenAI Codex installer only link their package into a directory on `PATH`.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it runs a command in a shell
+ *
+ * @returns Resolved path of the harness command or `null` when the command is not available
+ * @private internal utility of `promptbookCli`
+ */
+export declare function $resolveHarnessCommandPath(definition: HarnessDefinition): Promise<string | null>;

package/umd/src/cli/cli-commands/common/harness/$resolveHarnessInstallationOrigin.d.ts

@@ -0,0 +1,10 @@
+import type { HarnessDefinition } from './HarnessDefinition';
+import type { HarnessInstallationOrigin } from './HarnessInstallationOrigin';
+/**
+ * Finds out where one CLI coding harness is really installed and which tool manages it.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it runs shell commands
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function $resolveHarnessInstallationOrigin(definition: HarnessDefinition): Promise<HarnessInstallationOrigin>;

package/umd/src/cli/cli-commands/common/harness/$runHarnessInstallationCommand.d.ts

@@ -0,0 +1,43 @@
+import type { HarnessDefinition } from './HarnessDefinition';
+/**
+ * What one harness installation command does with the harness.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type HarnessInstallationOperation = 'install' | 'update';
+/**
+ * Options of one command which installs or updates a CLI coding harness.
+ *
+ * @private internal utility of `$runHarnessInstallationCommand`
+ */
+type HarnessInstallationCommandOptions = {
+    /**
+     * Harness which is installed or updated.
+     */
+    readonly definition: HarnessDefinition;
+    /**
+     * What the command does with the harness.
+     */
+    readonly operation: HarnessInstallationOperation;
+    /**
+     * Shell command which does it.
+     */
+    readonly command: string;
+    /**
+     * Extra environment variables required by the command.
+     */
+    readonly environment?: Readonly<Record<string, string>>;
+};
+/**
+ * Runs one command which installs or updates a CLI coding harness.
+ *
+ * A failed installation is reported but never aborts the running command, because the harness check
+ * is only an assistant - the command itself may still work with a manually managed harness.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it installs software
+ *
+ * @returns `true` when the command succeeded, `false` when it failed
+ * @private internal utility of `promptbookCli`
+ */
+export declare function $runHarnessInstallationCommand(options: HarnessInstallationCommandOptions): Promise<boolean>;
+export {};

package/umd/src/cli/cli-commands/common/harness/HarnessDefinition.d.ts

@@ -1,4 +1,24 @@
 import type { PromptRunnerHarnessName } from '../promptRunnerCliOptions';
+/**
+ * Description of a standalone *(self-managed)* installation of one CLI coding harness.
+ *
+ * Some harnesses are also distributed by their own installer which puts the harness outside of npm and
+ * updates it in place. Such an installation must never be updated with `npm install -g`, because that
+ * installs a second copy of the harness instead of updating the one which is really used.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type HarnessStandaloneInstallation = {
+    /**
+     * Directory names which appear in the resolved path of a standalone installation of the harness,
+     * for example `.codex` in `~/.codex/packages/standalone/current/bin/codex`.
+     */
+    readonly directoryNames: ReadonlyArray<string>;
+    /**
+     * Command which updates the standalone installation in place.
+     */
+    readonly updateCommand: string;
+};
 /**
  * Static description of one supported CLI coding harness.
  *
@@ -25,6 +45,12 @@ export type HarnessDefinition = {
      * Extra environment variables required by the global npm installation of this harness.
      */
     readonly npmInstallEnvironment?: Readonly<Record<string, string>>;
+    /**
+     * How a standalone installation of this harness is recognized and updated.
+     *
+     * Harnesses which are distributed only through npm leave this undefined.
+     */
+    readonly standaloneInstallation?: HarnessStandaloneInstallation;
 };
 /**
  * Single source of truth about how each supported CLI coding harness is installed and detected.

package/umd/src/cli/cli-commands/common/harness/HarnessInstallationOrigin.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Way in which the globally available harness command got onto the current machine.
+ *
+ * - `npm-global` the command comes from a global npm installation, so `npm install -g` really updates it
+ * - `standalone` the command was installed by the own installer of the harness and updates itself in place
+ * - `homebrew` the command is managed by Homebrew, so only `brew` may update it
+ * - `unknown` the command lives somewhere else or could not be located at all
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type HarnessInstallationMethod = 'npm-global' | 'standalone' | 'homebrew' | 'unknown';
+/**
+ * Place where the harness command really lives together with the way it was installed there.
+ *
+ * Knowing the origin is what keeps an update from installing a **second** copy of a harness which is
+ * managed outside of npm, for example the standalone installation of OpenAI Codex.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type HarnessInstallationOrigin = {
+    /**
+     * Resolved path of the harness command with every symbolic link followed
+     * or `null` when the command could not be located.
+     */
+    readonly commandPath: string | null;
+    /**
+     * Way in which the harness command was installed.
+     */
+    readonly installationMethod: HarnessInstallationMethod;
+};
+/**
+ * Origin used when the harness command was not looked up at all, for example when the update check is disabled.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare const UNKNOWN_HARNESS_INSTALLATION_ORIGIN: HarnessInstallationOrigin;

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

@@ -1,15 +1,17 @@
 import type { HarnessDefinition } from './HarnessDefinition';
+import type { HarnessInstallationOrigin } from './HarnessInstallationOrigin';
 /**
  * Result of comparing the globally installed harness version with the newest published one.
  *
  * - `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 +23,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;
     /**
@@ -32,4 +34,8 @@ export type HarnessInstallationStatus = {
      * Newest version published to npm or `null` when it could not be resolved.
      */
     readonly latestVersion: string | null;
+    /**
+     * Place where the harness command lives together with the way it was installed there.
+     */
+    readonly installationOrigin: HarnessInstallationOrigin;
 };

package/umd/src/cli/cli-commands/common/harness/HarnessUpdatePlan.d.ts

@@ -0,0 +1,23 @@
+/**
+ * How an outdated CLI coding harness can be brought up to date where it is really installed.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type HarnessUpdatePlan = {
+    /**
+     * Command which updates the harness in place
+     * or `null` when the installation is not understood well enough to name one.
+     */
+    readonly command: string | null;
+    /**
+     * Whether Promptbook may run the command itself instead of only printing it.
+     *
+     * Only installations which Promptbook can update without any side effect are updated automatically,
+     * everything else is left to the user together with the instructions.
+     */
+    readonly isRunnableByPromptbook: boolean;
+    /**
+     * Extra environment variables required by the update command.
+     */
+    readonly environment?: Readonly<Record<string, string>>;
+};

package/umd/src/cli/cli-commands/common/harness/buildHarnessInstallCommand.d.ts

@@ -2,9 +2,12 @@ import type { HarnessDefinition } from './HarnessDefinition';
 /**
  * Builds the shell command which installs or updates one CLI coding harness globally.
  *
- * The very same command is executed by `$installHarness` and printed as the manual fallback,
+ * The very same command is executed by `$runHarnessInstallationCommand` and printed as the manual fallback,
  * so the user always sees exactly what Promptbook would run.
  *
+ * Note: This command installs the harness through npm, so it may only update a harness which npm really owns,
+ * see `resolveHarnessUpdatePlan`.
+ *
  * @private internal utility of `promptbookCli`
  */
 export declare function buildHarnessInstallCommand(definition: HarnessDefinition): string;

package/umd/src/cli/cli-commands/common/harness/formatHarnessManualUpdateInstruction.d.ts

@@ -0,0 +1,8 @@
+import type { HarnessInstallationStatus } from './HarnessInstallationStatus';
+import type { HarnessUpdatePlan } from './HarnessUpdatePlan';
+/**
+ * Formats the instruction shown when an outdated harness must be updated by the user.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function formatHarnessManualUpdateInstruction(status: HarnessInstallationStatus, updatePlan: HarnessUpdatePlan): string;

package/umd/src/cli/cli-commands/common/harness/formatHarnessManualUpdateInstruction.test.d.ts

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

package/umd/src/cli/cli-commands/common/harness/resolveHarnessInstallationMethodFromPaths.d.ts

@@ -0,0 +1,31 @@
+import type { HarnessDefinition } from './HarnessDefinition';
+import type { HarnessInstallationMethod } from './HarnessInstallationOrigin';
+/**
+ * Options describing where the harness command was found.
+ *
+ * @private internal utility of `resolveHarnessInstallationMethodFromPaths`
+ */
+type HarnessInstallationPaths = {
+    /**
+     * Harness whose command was located.
+     */
+    readonly definition: HarnessDefinition;
+    /**
+     * Resolved path of the harness command with every symbolic link followed.
+     */
+    readonly commandPath: string;
+    /**
+     * Root directory of global npm installations or `null` when npm could not be asked for it.
+     */
+    readonly npmGlobalPrefixPath: string | null;
+};
+/**
+ * Decides how a harness command was installed from the place where it really lives.
+ *
+ * Only a command which npm owns may be updated with `npm install -g`, every other command has to be
+ * updated where it is installed, otherwise the update silently adds a second copy of the harness.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function resolveHarnessInstallationMethodFromPaths(paths: HarnessInstallationPaths): HarnessInstallationMethod;
+export {};

package/umd/src/cli/cli-commands/common/harness/resolveHarnessInstallationMethodFromPaths.test.d.ts

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

package/umd/src/cli/cli-commands/common/harness/resolveHarnessUpdatePlan.d.ts

@@ -0,0 +1,12 @@
+import type { HarnessDefinition } from './HarnessDefinition';
+import type { HarnessInstallationMethod } from './HarnessInstallationOrigin';
+import type { HarnessUpdatePlan } from './HarnessUpdatePlan';
+/**
+ * Decides how one outdated CLI coding harness should be updated.
+ *
+ * The plan follows the way the harness was installed, because `npm install -g` updates only a harness
+ * which npm owns and installs a **second** copy of every other one.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function resolveHarnessUpdatePlan(definition: HarnessDefinition, installationMethod: HarnessInstallationMethod): HarnessUpdatePlan;