@promptbook/types 0.114.0-33 → 0.114.0-35

package/esm/src/book-2.0/book-language-documentation/getSafeCodeBlock.d.ts

@@ -5,6 +5,6 @@
  * @param language - Optional info-string language label.
  * @returns Fenced code block.
  *
- * @private internal utility of `createStandaloneBookLanguageMarkdown`
+ * @private internal utility of `createStandaloneBookLanguageMarkdown` and of the `ptbk coder` run traces
  */
 export declare function getSafeCodeBlock(content: string, language?: string): string;

package/esm/src/book-components/Chat/MockedChat/MockedChat.test.d.ts

@@ -0,0 +1,2 @@
+/** @jest-environment jsdom */
+export {};

package/esm/src/cli/cli-commands/coder/$ensureCoderHarnessGitignoreRules.d.ts

@@ -1,4 +1,5 @@
 import type { PromptRunnerHarnessName } from '../common/promptRunnerCliOptions';
+import type { NormalizedQuestionsCliOptions } from '../common/questionsCliOptions';
 /**
  * Offers to add missing project-local ignore rules for the selected coding harness.
  *
@@ -6,4 +7,4 @@ import type { PromptRunnerHarnessName } from '../common/promptRunnerCliOptions';
  *
  * @private internal utility of `ptbk coder`
  */
-export declare function $ensureCoderHarnessGitignoreRules(projectPath: string, harnessName: PromptRunnerHarnessName | undefined): Promise<void>;
+export declare function $ensureCoderHarnessGitignoreRules(projectPath: string, harnessName: PromptRunnerHarnessName | undefined, questionsOptions: NormalizedQuestionsCliOptions): Promise<void>;

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

@@ -0,0 +1,21 @@
+import type { Command as Program } from 'commander';
+/**
+ * Commander option bag for an optional Book agent used by coder commands.
+ *
+ * @private internal utility of `ptbk coder`
+ */
+export type CoderAgentCliOptions = {
+    readonly agent?: string;
+};
+/**
+ * Description shared by coder commands which accept an agent Book.
+ *
+ * @private internal utility of `ptbk coder`
+ */
+export declare const CODER_AGENT_OPTION_DESCRIPTION = "Path to a .book file used to personalize coding prompts and select agent-specific tasks";
+/**
+ * Registers the shared `--agent` option for coder commands.
+ *
+ * @private internal utility of `ptbk coder`
+ */
+export declare function addCoderAgentOption(command: Program): void;

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

@@ -16,6 +16,12 @@ export declare const PROMPTS_DONE_DIRECTORY_PATH: string;
  * @private internal utility of `ptbk coder`
  */
 export declare const PROMPTS_TEMPLATES_DIRECTORY_PATH: string;
+/**
+ * Relative path to the project-agnostic `common` boilerplate template referenced by the default coder scripts.
+ *
+ * @private internal utility of `ptbk coder`
+ */
+export declare const COMMON_PROMPT_TEMPLATE_FILE_PATH: string;
 /**
  * Initialization statuses used when creating or updating coder configuration artifacts.
  *
@@ -55,25 +61,6 @@ export type CoderPromptTemplateDefinition = {
      */
     readonly isDefaultProjectTemplate: boolean;
 };
-/**
- * Result of ensuring one default coder template file exists inside a project.
- *
- * @private internal utility of `ptbk coder`
- */
-export type EnsuredCoderPromptTemplateFile = {
-    /**
-     * Stable built-in identifier of the template.
-     */
-    readonly id: BuiltInCoderPromptTemplate;
-    /**
-     * Project-relative path of the materialized template file.
-     */
-    readonly relativeFilePath: string;
-    /**
-     * Status describing whether the file had to be created.
-     */
-    readonly status: InitializationStatus;
-};
 /**
  * Fully resolved boilerplate template used by `coder generate-boilerplates`.
  *
@@ -116,11 +103,11 @@ export declare function getDefaultCoderProjectPromptTemplateDefinitions(): Reado
  */
 export declare function getDefaultCoderPromptTemplateDefinition(template: BuiltInCoderPromptTemplate): CoderPromptTemplateDefinition;
 /**
- * Ensures the default project-owned coder template files exist without overwriting user customizations.
+ * Ensures one project-owned coder template file exists without overwriting user customizations.
  *
  * @private internal utility of `ptbk coder`
  */
-export declare function ensureDefaultCoderPromptTemplateFiles(projectPath: string): Promise<ReadonlyArray<EnsuredCoderPromptTemplateFile>>;
+export declare function ensureDefaultCoderPromptTemplateFile(projectPath: string, definition: CoderPromptTemplateDefinition): Promise<InitializationStatus>;
 /**
  * Resolves the template requested by `coder generate-boilerplates`.
  *

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

@@ -0,0 +1,33 @@
+import type { InitializationStatus } from './boilerplateTemplates';
+/**
+ * Status of one artifact referenced by the default coder scripts.
+ *
+ * `not-referenced` means that no newly added script points at the artifact, so `ptbk coder init` left it alone.
+ *
+ * @private internal utility of `coder init` command
+ */
+export type CoderReferencedArtifactStatus = InitializationStatus | 'not-referenced';
+/**
+ * Result of ensuring one artifact referenced by the default coder scripts.
+ *
+ * @private internal utility of `coder init` command
+ */
+export type EnsuredCoderReferencedArtifact = {
+    /**
+     * Project-relative path of the referenced artifact.
+     */
+    readonly relativeFilePath: string;
+    /**
+     * Status describing whether the artifact had to be created.
+     */
+    readonly status: CoderReferencedArtifactStatus;
+};
+/**
+ * Creates only those referenced artifacts which the freshly added coder scripts point at.
+ *
+ * An artifact of a script which the project already defines is intentionally **not** created - the project-owned
+ * script is kept as is, so it does not reference the default artifact in the first place.
+ *
+ * @private function of `initializeCoderProjectConfiguration`
+ */
+export declare function ensureCoderReferencedArtifacts(projectPath: string, referencedArtifactPaths: ReadonlySet<string>): Promise<ReadonlyArray<EnsuredCoderReferencedArtifact>>;

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

@@ -1,7 +1,9 @@
-import type { InitializationStatus } from './boilerplateTemplates';
+import type { MergedStringRecordJsonFile } from './mergeStringRecordJsonFile';
 /**
  * Ensures `package.json` contains the standalone Promptbook coder helper scripts.
  *
+ * Scripts which the project already defines are kept as they are, only missing ones are added.
+ *
  * @private function of `initializeCoderProjectConfiguration`
  */
-export declare function ensureCoderPackageJsonFile(projectPath: string): Promise<InitializationStatus>;
+export declare function ensureCoderPackageJsonFile(projectPath: string): Promise<MergedStringRecordJsonFile>;

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

@@ -2,6 +2,8 @@ import type { InitializationStatus } from './boilerplateTemplates';
 /**
  * Ensures VS Code routes pasted prompt images into `prompts/screenshots`.
  *
+ * Settings which the project already defines are kept as they are, only missing ones are added.
+ *
  * @private function of `initializeCoderProjectConfiguration`
  */
 export declare function ensureCoderVscodeSettingsFile(projectPath: string): Promise<InitializationStatus>;

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

@@ -5,3 +5,9 @@ import type { InitializationStatus } from './boilerplateTemplates';
  * @private function of `initializeCoderProjectConfiguration`
  */
 export declare function ensureDirectory(projectPath: string, relativeDirectoryPath: string): Promise<InitializationStatus>;
+/**
+ * Checks whether a project-relative directory is missing or contains no entries.
+ *
+ * @private internal utility of `coder init` command
+ */
+export declare function isDirectoryEmpty(projectPath: string, relativeDirectoryPath: string): Promise<boolean>;

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

@@ -4,3 +4,9 @@
  * @private internal utility of `coder init` command
  */
 export declare function getDefaultCoderPackageJsonScripts(): Readonly<Record<string, string>>;
+/**
+ * Collects the project-relative artifact paths referenced by the given default coder scripts.
+ *
+ * @private internal utility of `coder init` command
+ */
+export declare function resolveCoderPackageJsonScriptReferencedArtifactPaths(scriptNames: ReadonlyArray<string>): ReadonlySet<string>;

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

@@ -1,4 +1,5 @@
-import type { EnsuredCoderPromptTemplateFile, InitializationStatus } from './boilerplateTemplates';
+import type { InitializationStatus } from './boilerplateTemplates';
+import type { EnsuredCoderReferencedArtifact } from './coderReferencedArtifacts';
 /**
  * Result summary returned after coder configuration initialization.
  *
@@ -8,20 +9,21 @@ export type CoderInitializationSummary = {
     readonly promptsDirectoryStatus: InitializationStatus;
     readonly promptsDoneDirectoryStatus: InitializationStatus;
     readonly promptsTemplatesDirectoryStatus: InitializationStatus;
-    readonly promptTemplateFileStatuses: ReadonlyArray<EnsuredCoderPromptTemplateFile>;
     readonly agentsDirectoryStatus: InitializationStatus;
-    readonly developerAgentFileStatus: InitializationStatus;
-    readonly agentsFileStatus: InitializationStatus;
-    readonly agentCodingFileStatus: InitializationStatus;
     readonly envFileStatus: InitializationStatus;
     readonly gitignoreFileStatus: InitializationStatus;
     readonly packageJsonFileStatus: InitializationStatus;
     readonly vscodeSettingsFileStatus: InitializationStatus;
+    readonly addedPackageJsonScriptNames: ReadonlyArray<string>;
+    readonly referencedArtifactStatuses: ReadonlyArray<EnsuredCoderReferencedArtifact>;
     readonly initializedEnvVariableNames: ReadonlyArray<string>;
 };
 /**
  * Creates or updates all coder configuration artifacts required in the current project.
  *
+ * Nothing the project already owns is ever overwritten - existing scripts, settings and files are kept as they are,
+ * and the artifacts they would reference are created only together with the scripts which actually reference them.
+ *
  * @private internal utility of `coder init` command
  */
 export declare function initializeCoderProjectConfiguration(projectPath: string): Promise<CoderInitializationSummary>;

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

@@ -9,10 +9,28 @@ type MergeStringRecordJsonFileOptions = {
     readonly nextEntries: Readonly<Record<string, string>>;
     readonly ensureParentDirectoryPath?: string;
 };
+/**
+ * Result of one additive string-record merge into a JSON file.
+ *
+ * @private internal utility of `coder init` command
+ */
+export type MergedStringRecordJsonFile = {
+    /**
+     * Status describing whether the JSON file had to be created or updated.
+     */
+    readonly status: InitializationStatus;
+    /**
+     * Keys which were missing in the JSON file and therefore added by the merge.
+     */
+    readonly addedEntryKeys: ReadonlyArray<string>;
+};
 /**
  * Ensures one JSON object field contains the provided string-record entries.
  *
+ * Entries which the project already defines are **never** overridden - only missing keys are added,
+ * so hand-tuned scripts and settings survive every repeated `ptbk coder init`.
+ *
  * @private function of `initializeCoderProjectConfiguration`
  */
-export declare function mergeStringRecordJsonFile({ projectPath, relativeFilePath, fieldPath, nextEntries, ensureParentDirectoryPath, }: MergeStringRecordJsonFileOptions): Promise<InitializationStatus>;
+export declare function mergeStringRecordJsonFile({ projectPath, relativeFilePath, fieldPath, nextEntries, ensureParentDirectoryPath, }: MergeStringRecordJsonFileOptions): Promise<MergedStringRecordJsonFile>;
 export {};

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

@@ -0,0 +1,6 @@
+/**
+ * Prints why a coder run has ended to the terminal.
+ *
+ * @private internal utility of `coder run` and `coder server` commands
+ */
+export declare function printCoderRunFailure(error: Error): void;

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

@@ -1,9 +1,11 @@
+import type { NormalizedQuestionsCliOptions } from './questionsCliOptions';
 /**
  * Asks the user in the terminal to confirm one optional change.
  *
  * 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.
+ * @returns `true` when the user confirms, `false` when the user declines, the terminal is not interactive
+ *          or the questions are disabled by `--no-questions`.
  * @private internal utility of `promptbookCli`
  */
-export declare function $askForConfirmation(question: string): Promise<boolean>;
+export declare function $askForConfirmation(question: string, { isAskingQuestionsEnabled }: NormalizedQuestionsCliOptions): Promise<boolean>;

package/esm/src/cli/cli-commands/common/disk-space/$assertSufficientFreeDiskSpace.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Refuses to start one `ptbk coder` command when the disk which hosts the project is nearly full.
+ *
+ * A run which starts without enough free disk space fails somewhere in the middle, after the coding agent has
+ * already rewritten a part of the project, so it is stopped before it writes anything at all.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it reads the state of the filesystem
+ *
+ * @throws {LimitReachedError} when there is not enough free disk space left to start
+ * @private internal utility of `promptbookCli`
+ */
+export declare function $assertSufficientFreeDiskSpace(inspectedPath: string): Promise<void>;

package/esm/src/cli/cli-commands/common/disk-space/$assertSufficientFreeDiskSpace.test.d.ts

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

package/esm/src/cli/cli-commands/common/disk-space/$readFreeDiskSpaceStatus.d.ts

@@ -0,0 +1,11 @@
+import type { FreeDiskSpaceStatus } from './FreeDiskSpaceStatus';
+/**
+ * Measures the free disk space on the filesystem which hosts the given path.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it reads the state of the filesystem
+ *
+ * @returns the measurement, or `null` when the filesystem can not be measured, for example on a platform which
+ *          does not report filesystem statistics - a run is never stopped by a measurement which could not be taken
+ * @private internal utility of `promptbookCli`
+ */
+export declare function $readFreeDiskSpaceStatus(inspectedPath: string): Promise<FreeDiskSpaceStatus | null>;

package/esm/src/cli/cli-commands/common/disk-space/$readFreeDiskSpaceStatus.test.d.ts

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

package/esm/src/cli/cli-commands/common/disk-space/FreeDiskSpaceStatus.d.ts

@@ -0,0 +1,33 @@
+/**
+ * How much free disk space is left, measured against the `ptbk coder` free disk space limits.
+ *
+ * - `sufficient` - there is enough free disk space to start a run and to keep it running
+ * - `low` - there is not enough free disk space to start a new run
+ * - `critical` - there is not enough free disk space to keep a started run going
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type FreeDiskSpaceLevel = 'sufficient' | 'low' | 'critical';
+/**
+ * One measurement of the free disk space on the filesystem which hosts the inspected path.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type FreeDiskSpaceStatus = {
+    /**
+     * Path whose filesystem was measured.
+     */
+    readonly inspectedPath: string;
+    /**
+     * Bytes which are still available to the current user on that filesystem.
+     */
+    readonly availableBytes: number;
+    /**
+     * Total size of that filesystem in bytes.
+     */
+    readonly totalBytes: number;
+    /**
+     * Severity of the measured free disk space.
+     */
+    readonly level: FreeDiskSpaceLevel;
+};

package/esm/src/cli/cli-commands/common/disk-space/formatFreeDiskSpaceBytes.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Writes one byte count as a compact human-readable amount of disk space, for example `812 MB` or `1.5 GB`.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function formatFreeDiskSpaceBytes(bytes: number): string;

package/esm/src/cli/cli-commands/common/disk-space/formatFreeDiskSpaceBytes.test.d.ts

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

package/esm/src/cli/cli-commands/common/disk-space/formatLowFreeDiskSpaceWarning.d.ts

@@ -0,0 +1,10 @@
+import type { FreeDiskSpaceStatus } from './FreeDiskSpaceStatus';
+/**
+ * Writes the shared warning which explains one low free disk space measurement and how to get out of it.
+ *
+ * The very same wording is used by the check which refuses to start a run and by the check which pauses
+ * a run that ran out of disk space while it was working.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function formatLowFreeDiskSpaceWarning(freeDiskSpaceStatus: FreeDiskSpaceStatus): string;

package/esm/src/cli/cli-commands/common/disk-space/freeDiskSpaceConstants.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Free disk space below which `ptbk coder` refuses to start a new run.
+ *
+ * A coding round writes prompt and log artifacts, lets the harness rewrite the project, may install npm packages,
+ * may create a git worktree for `--isolate` and usually runs a build, so a run started with less than this
+ * would very likely die somewhere in the middle with a filesystem error.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare const LOW_FREE_DISK_SPACE_BYTES: number;
+/**
+ * Free disk space below which a started `ptbk coder` run stops at its next checkpoint and waits until space is freed.
+ *
+ * This limit is lower than `LOW_FREE_DISK_SPACE_BYTES`, because interrupting a run which is already in progress
+ * is more expensive than not starting one at all.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare const CRITICALLY_LOW_FREE_DISK_SPACE_BYTES: number;
+/**
+ * How long one free disk space measurement is reused before the filesystem is measured again during a run.
+ *
+ * Pause checkpoints are passed very often - for example on every tick of a timed wait - so without this
+ * interval the filesystem would be measured many times per second.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare const FREE_DISK_SPACE_RECHECK_INTERVAL_MS: number;

package/esm/src/cli/cli-commands/common/disk-space/resolveFreeDiskSpaceLevel.d.ts

@@ -0,0 +1,7 @@
+import type { FreeDiskSpaceLevel } from './FreeDiskSpaceStatus';
+/**
+ * Classifies one measured amount of free disk space against the `ptbk coder` free disk space limits.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function resolveFreeDiskSpaceLevel(availableBytes: number): FreeDiskSpaceLevel;

package/esm/src/cli/cli-commands/common/disk-space/resolveFreeDiskSpaceLevel.test.d.ts

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

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

@@ -1,3 +1,4 @@
+import type { NormalizedQuestionsCliOptions } from '../questionsCliOptions';
 import type { HarnessInstallationStatus } from './HarnessInstallationStatus';
 /**
  * Reports one detected harness installation status and offers to install or update the harness.
@@ -6,4 +7,4 @@ import type { HarnessInstallationStatus } from './HarnessInstallationStatus';
  *
  * @private internal utility of `promptbookCli`
  */
-export declare function $applyHarnessInstallationStatus(status: HarnessInstallationStatus): Promise<void>;
+export declare function $applyHarnessInstallationStatus(status: HarnessInstallationStatus, questionsOptions: NormalizedQuestionsCliOptions): Promise<void>;

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

@@ -1,6 +1,7 @@
 import type { PromptRunnerHarnessName } from '../promptRunnerCliOptions';
+import type { NormalizedQuestionsCliOptions } from '../questionsCliOptions';
 /**
- * Checks that every given CLI coding harness is installed globally and, when enabled, up to date.
+ * Checks that every given CLI coding harness is installed globally and, when the questions are 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,
@@ -10,4 +11,4 @@ import type { PromptRunnerHarnessName } from '../promptRunnerCliOptions';
  *
  * @private internal utility of `promptbookCli`
  */
-export declare function $ensureHarnessInstallations(harnessNames: ReadonlyArray<PromptRunnerHarnessName | undefined>, isHarnessUpdateCheckEnabled?: boolean): Promise<void>;
+export declare function $ensureHarnessInstallations(harnessNames: ReadonlyArray<PromptRunnerHarnessName | undefined>, questionsOptions: NormalizedQuestionsCliOptions): Promise<void>;

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

@@ -19,6 +19,28 @@ export type HarnessStandaloneInstallation = {
      */
     readonly updateCommand: string;
 };
+/**
+ * Description of how the user signs in to one CLI coding harness again.
+ *
+ * Every harness refuses to work once its login is missing or its session has expired, and each of them is
+ * signed in differently - some have a dedicated login command, others sign in from their own interactive UI.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type HarnessAuthenticationMethod = {
+    /**
+     * Command which starts the sign-in flow of the harness.
+     */
+    readonly command: string;
+    /**
+     * Step which finishes the sign-in inside the started command.
+     *
+     * Harnesses which sign in from their own interactive user interface leave the user in that interface, so
+     * naming just the command would not be enough to get them signed in. Harnesses with a dedicated login
+     * command leave this undefined.
+     */
+    readonly interactiveStep?: string;
+};
 /**
  * Static description of one supported CLI coding harness.
  *
@@ -49,6 +71,10 @@ export type HarnessDefinition = {
      * Project-local files or directories which this harness can create and which should not be committed.
      */
     readonly projectGitignoreRules: ReadonlyArray<string>;
+    /**
+     * How the user signs in to this harness again after its login is missing or has expired.
+     */
+    readonly authenticationMethod: HarnessAuthenticationMethod;
     /**
      * How a standalone installation of this harness is recognized and updated.
      *

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

@@ -1,9 +1,11 @@
+import type { NormalizedQuestionsCliOptions } from '../questionsCliOptions';
 /**
  * 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
+ * @returns `true` when the user confirms, `false` when the user declines, the terminal is not interactive
+ *          or the questions are disabled by `--no-questions`
  * @private internal utility of `promptbookCli`
  */
-export declare function $askForNpmPackageInstallationApproval(question: string): Promise<boolean>;
+export declare function $askForNpmPackageInstallationApproval(question: string, questionsOptions: NormalizedQuestionsCliOptions): Promise<boolean>;

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

@@ -1,3 +1,4 @@
+import type { NormalizedQuestionsCliOptions } from '../questionsCliOptions';
 /**
  * Checks local and global Promptbook CLI installations before an interactive coder run and offers to update them.
  *
@@ -11,4 +12,4 @@
  * @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>;
+export declare function $ensurePromptbookCliInstallations(questionsOptions: NormalizedQuestionsCliOptions): Promise<boolean>;

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

@@ -0,0 +1,45 @@
+import type { Command as Program } from 'commander';
+/**
+ * Commander option bag for opting out of every interactive question.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type QuestionsCliOptions = {
+    readonly questions: boolean;
+};
+/**
+ * Normalized interactive-questions option shared by every `ptbk coder` command which can ask something.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type NormalizedQuestionsCliOptions = {
+    readonly isAskingQuestionsEnabled: boolean;
+};
+/**
+ * Description block shared by the `ptbk coder` commands which can ask interactive questions.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare const QUESTIONS_DESCRIPTION: string;
+/**
+ * Registers the shared `--no-questions` option on a `ptbk coder` command which can ask interactive questions.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function addQuestionsOption(command: Program): void;
+/**
+ * Converts the Commander questions flag into the normalized interactive-questions option.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function normalizeQuestionsCliOptions(cliOptions: QuestionsCliOptions): NormalizedQuestionsCliOptions;
+/**
+ * Asserts that a command which waits for a user confirmation before each prompt is allowed to ask for it.
+ *
+ * @throws {NotAllowed} when `--no-auto` is combined with `--no-questions`
+ * @private internal utility of `promptbookCli`
+ */
+export declare function assertUserConfirmationIsAllowed(options: {
+    readonly isAskingQuestionsEnabled: boolean;
+    readonly isWaitingForUser: boolean;
+}): void;

package/esm/src/cli/cli-commands/common/questionsCliOptions.test.d.ts

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

package/esm/src/cli/common/$deprecateCliCommand.d.ts

@@ -3,6 +3,9 @@ import type { $side_effect } from '../../utils/organization/$side_effect';
 /**
  * Marks one CLI command as deprecated while keeping it available for existing callers.
  *
+ * Deprecated commands are not advertised anymore - they are hidden from the list of commands in the help of their
+ * parent command, they warn when they are used and they explain the deprecation in their own help.
+ *
  * @private utility of CLI
  */
 export declare function $deprecateCliCommand(command: Command, deprecationMessage: string): $side_effect;

package/esm/src/cli/common/$hideCliCommandFromHelp.d.ts

@@ -0,0 +1,11 @@
+import type { Command } from 'commander';
+import type { $side_effect } from '../../utils/organization/$side_effect';
+/**
+ * Keeps one already registered CLI command out of the help of its parent command while the command itself stays
+ * fully usable - it can still be run, it still has its own help and it is still reachable through `ptbk help <command>`.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it changes how the CLI renders its help
+ *
+ * @private utility of CLI
+ */
+export declare function $hideCliCommandFromHelp(command: Command): $side_effect;

package/esm/src/cli/common/$hideCliCommandFromHelp.test.d.ts

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

package/esm/src/cli/common/$requireCliSubcommand.d.ts

@@ -0,0 +1,18 @@
+import type { Command } from 'commander';
+import type { $side_effect } from '../../utils/organization/$side_effect';
+/**
+ * Makes one CLI command which only groups subcommands ask for a subcommand instead of doing anything on its own.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it registers an action in the CLI
+ *
+ * @private utility of CLI
+ */
+export declare function $requireCliSubcommand(command: Command): $side_effect;
+/**
+ * Asks for a subcommand of one CLI command, prints its help and exits the process.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it writes to the console and exits the process
+ *
+ * @private utility of CLI
+ */
+export declare function $reportMissingCliSubcommand(command: Command): never;

package/esm/src/cli/common/$requireCliSubcommand.test.d.ts

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

package/esm/src/llm-providers/vercel/VercelExecutionToolsOptions.d.ts

@@ -17,7 +17,10 @@ export type VercelExecutionToolsOptions = CommonToolsOptions & Pick<LlmExecution
      */
     readonly availableModels: ReadonlyArray<AvailableModel>;
     /**
-     * Additional settings for chat models when calling `vercelProvider.chat('model-name', settings)`
+     * Additional settings for chat models, for example `temperature` or `providerOptions`
+     *
+     * Note: Since Vercel AI SDK v5 these settings belong to the model call, not to
+     *       `vercelProvider.chat('model-name')` which takes just the model name
      */
-    readonly additionalChatSettings?: Partial<Parameters<VercelProvider['chat']>[1]>;
+    readonly additionalChatSettings?: Partial<Omit<Parameters<ReturnType<VercelProvider['chat']>['doGenerate']>[0], 'prompt'>>;
 };

package/esm/src/version.d.ts

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

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@promptbook/types",
-    "version": "0.114.0-33",
+    "version": "0.114.0-35",
     "description": "Promptbook: Create persistent AI agents that turn your company's scattered knowledge into action",
     "private": false,
     "sideEffects": false,
@@ -90,12 +90,9 @@
         "node": ">=18.18.0",
         "npm": ">=8.0.0"
     },
-    "overrides": {
-        "zod": "$zod"
-    },
     "types": "./esm/src/_packages/types.index.d.ts",
     "typings": "./esm/src/_packages/types.index.d.ts",
     "peerDependencies": {
-        "@promptbook/core": "0.114.0-33"
+        "@promptbook/core": "0.114.0-35"
     }
 }