@promptbook/cli 0.113.0-1 → 0.113.0-10

package/src/book-components/Chat/Chat/useChatInputAreaDictation.ts

@@ -1,13 +1,13 @@
 'use client';
 
 import {
-    useCallback,
-    useEffect,
-    useRef,
-    useState,
-    type Dispatch,
-    type MutableRefObject,
-    type SetStateAction,
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+  type Dispatch,
+  type MutableRefObject,
+  type SetStateAction
 } from 'react';
 import type { SpeechRecognitionErrorCode, SpeechRecognitionEvent } from '../../../types/SpeechRecognition';
 import type { ChatProps } from './ChatProps';
@@ -38,6 +38,17 @@ type DictationChunk = {
     readonly start: number;
 };
 
+/**
+ * Stable insertion range captured when the user starts dictation.
+ *
+ * @private function of `useChatInputAreaDictation`
+ */
+type DictationInsertionSelection = {
+    readonly selectionStart: number;
+    readonly selectionEnd: number;
+    readonly isReplacingSelection: boolean;
+};
+
 /**
  * Stable dictation error shape consumed by the correction panel UI.
  *
@@ -88,7 +99,7 @@ type UseChatInputAreaDictationFinalResultHandlerProps = {
     readonly applyMessageContent: (nextContent: string) => void;
     readonly dictationSettings: DictationRefinementSettings;
     readonly dictationDictionary: ReturnType<typeof useChatInputAreaDictationPersistence>['dictationDictionary'];
-    readonly replaceSelectionOnNextFinalRef: MutableRefObject<boolean>;
+    readonly dictationInsertionSelectionRef: MutableRefObject<DictationInsertionSelection | null>;
     readonly focusTextareaSelection: (selectionStart: number, selectionEnd: number) => void;
     readonly state: UseChatInputAreaDictationState;
 };
@@ -126,7 +137,7 @@ type UseChatInputAreaDictationVoiceInputControlsProps = {
     readonly resolvedSpeechRecognitionLanguage: string;
     readonly whisperMode: boolean;
     readonly pendingStopFallbackRef: MutableRefObject<ReturnType<typeof setTimeout> | null>;
-    readonly replaceSelectionOnNextFinalRef: MutableRefObject<boolean>;
+    readonly dictationInsertionSelectionRef: MutableRefObject<DictationInsertionSelection | null>;
     readonly clearPendingStopFallback: () => void;
     readonly state: Pick<
         UseChatInputAreaDictationState,
@@ -144,6 +155,7 @@ type UseChatInputAreaDictationCorrectionHandlersProps = {
     readonly dictationLastFinalChunk: string;
     readonly dictationEditableChunk: string;
     readonly dictationDictionary: ReturnType<typeof useChatInputAreaDictationPersistence>['dictationDictionary'];
+    readonly dictationInsertionSelectionRef: MutableRefObject<DictationInsertionSelection | null>;
     readonly messageContentRef: MutableRefObject<string>;
     readonly applyMessageContent: (nextContent: string) => void;
     readonly focusTextareaSelection: (selectionStart: number, selectionEnd: number) => void;
@@ -235,21 +247,96 @@ function clearPendingStopFallbackTimeout(
 }
 
 /**
- * Captures whether the next finalized chunk should replace the current selection.
+ * Captures where the next finalized chunk should be inserted.
  *
  * @private function of `useChatInputAreaDictation`
  */
-function captureSelectionReplacementIntent(
+function captureDictationInsertionSelection(
     textareaRef: MutableRefObject<HTMLTextAreaElement | null>,
-    replaceSelectionOnNextFinalRef: MutableRefObject<boolean>,
+    dictationInsertionSelectionRef: MutableRefObject<DictationInsertionSelection | null>,
 ): void {
     const textarea = textareaRef.current;
     if (!textarea) {
         return;
     }
 
-    const { selectionStart, selectionEnd } = resolveTextareaSelection(textarea, 0);
-    replaceSelectionOnNextFinalRef.current = selectionStart !== selectionEnd;
+    const { selectionStart, selectionEnd } = resolveTextareaSelection(textarea, textarea.value.length);
+    dictationInsertionSelectionRef.current = {
+        selectionStart,
+        selectionEnd,
+        isReplacingSelection: selectionStart !== selectionEnd,
+    };
+}
+
+/**
+ * Resolves the insertion range for one finalized dictation chunk.
+ *
+ * @private function of `useChatInputAreaDictation`
+ */
+function resolveDictationInsertionSelection(
+    textareaElement: HTMLTextAreaElement,
+    messageContentLength: number,
+    dictationInsertionSelection: DictationInsertionSelection | null,
+): DictationInsertionSelection {
+    if (dictationInsertionSelection) {
+        return dictationInsertionSelection;
+    }
+
+    const { selectionStart, selectionEnd } = resolveTextareaSelection(textareaElement, messageContentLength);
+
+    return {
+        selectionStart,
+        selectionEnd,
+        isReplacingSelection: selectionStart !== selectionEnd,
+    };
+}
+
+/**
+ * Removes one tracked dictated chunk from the current composer value.
+ *
+ * @private function of `useChatInputAreaDictation`
+ */
+function removeTrackedDictationChunk(currentValue: string, chunk: DictationChunk): string {
+    const trackedText = currentValue.slice(chunk.start, chunk.start + chunk.finalText.length);
+
+    if (trackedText === chunk.finalText) {
+        return `${currentValue.slice(0, chunk.start)}${currentValue.slice(chunk.start + chunk.finalText.length)}`;
+    }
+
+    return replaceLastOccurrence(currentValue, chunk.finalText, '');
+}
+
+/**
+ * Replaces one tracked dictated chunk inside the current composer value.
+ *
+ * @private function of `useChatInputAreaDictation`
+ */
+function replaceTrackedDictationChunk(currentValue: string, chunk: DictationChunk, correctedChunk: string): string {
+    const trackedText = currentValue.slice(chunk.start, chunk.start + chunk.finalText.length);
+
+    if (trackedText === chunk.finalText) {
+        return `${currentValue.slice(0, chunk.start)}${correctedChunk}${currentValue.slice(
+            chunk.start + chunk.finalText.length,
+        )}`;
+    }
+
+    return replaceLastOccurrence(currentValue, chunk.finalText, correctedChunk);
+}
+
+/**
+ * Stores the next append position after a programmatic dictation edit.
+ *
+ * @private function of `useChatInputAreaDictation`
+ */
+function updateDictationInsertionCaret(
+    dictationInsertionSelectionRef: MutableRefObject<DictationInsertionSelection | null>,
+    caret: number,
+): void {
+    dictationInsertionSelectionRef.current = {
+        selectionStart: caret,
+        selectionEnd: caret,
+        isReplacingSelection: false,
+    };
 }
 
 /**
@@ -376,7 +463,7 @@ function useChatInputAreaDictationFinalResultHandler({
     applyMessageContent,
     dictationSettings,
     dictationDictionary,
-    replaceSelectionOnNextFinalRef,
+    dictationInsertionSelectionRef,
     focusTextareaSelection,
     state,
 }: UseChatInputAreaDictationFinalResultHandlerProps) {
@@ -403,16 +490,20 @@ function useChatInputAreaDictationFinalResultHandler({
                 return;
             }
 
-            const { selectionStart, selectionEnd } = resolveTextareaSelection(textarea, previousMessageContent.length);
+            const { selectionStart, selectionEnd, isReplacingSelection } = resolveDictationInsertionSelection(
+                textarea,
+                previousMessageContent.length,
+                dictationInsertionSelectionRef.current,
+            );
             const insertion = insertDictationChunk({
                 currentValue: previousMessageContent,
                 dictatedText: refinedText,
                 selectionStart,
                 selectionEnd,
-                shouldReplaceSelection: replaceSelectionOnNextFinalRef.current,
+                isReplacingSelection,
             });
 
-            replaceSelectionOnNextFinalRef.current = false;
+            updateDictationInsertionCaret(dictationInsertionSelectionRef, insertion.caret);
             setDictationInterimText('');
             setDictationError(null);
             setDictationUiState('listening');
@@ -433,10 +524,10 @@ function useChatInputAreaDictationFinalResultHandler({
         [
             applyMessageContent,
             dictationDictionary,
+            dictationInsertionSelectionRef,
             dictationSettings,
             focusTextareaSelection,
             messageContentRef,
-            replaceSelectionOnNextFinalRef,
             setDictationChunks,
             setDictationEditableChunk,
             setDictationError,
@@ -491,7 +582,9 @@ function useChatInputAreaDictationSpeechRecognitionEventHandler({
                     return;
                 case 'STOP':
                     clearPendingStopFallback();
-                    setDictationUiState((currentState) => (currentState === 'disabled' ? currentState : 'idle'));
+                    setDictationUiState((currentState) =>
+                        currentState === 'disabled' || currentState === 'error' ? currentState : 'idle',
+                    );
                     setDictationInterimText('');
                     return;
             }
@@ -549,7 +642,7 @@ function useChatInputAreaDictationVoiceInputControls({
     resolvedSpeechRecognitionLanguage,
     whisperMode,
     pendingStopFallbackRef,
-    replaceSelectionOnNextFinalRef,
+    dictationInsertionSelectionRef,
     clearPendingStopFallback,
     state,
 }: UseChatInputAreaDictationVoiceInputControlsProps) {
@@ -560,7 +653,7 @@ function useChatInputAreaDictationVoiceInputControls({
             return;
         }
 
-        captureSelectionReplacementIntent(textareaRef, replaceSelectionOnNextFinalRef);
+        captureDictationInsertionSelection(textareaRef, dictationInsertionSelectionRef);
         setDictationError(null);
         setDictationInterimText('');
         setDictationUiState('listening');
@@ -570,7 +663,7 @@ function useChatInputAreaDictationVoiceInputControls({
             whisperMode,
         });
     }, [
-        replaceSelectionOnNextFinalRef,
+        dictationInsertionSelectionRef,
         resolvedSpeechRecognitionLanguage,
         setDictationError,
         setDictationInterimText,
@@ -635,6 +728,7 @@ function useChatInputAreaDictationCorrectionHandlers({
     dictationLastFinalChunk,
     dictationEditableChunk,
     dictationDictionary,
+    dictationInsertionSelectionRef,
     messageContentRef,
     applyMessageContent,
     focusTextareaSelection,
@@ -651,17 +745,23 @@ function useChatInputAreaDictationCorrectionHandlers({
             return;
         }
 
+        const nextMessageContent = removeTrackedDictationChunk(messageContentRef.current, lastChunk);
+        const nextCaret = Math.min(lastChunk.start, nextMessageContent.length);
+
         setDictationChunks(previousChunks);
-        applyMessageContent(lastChunk.beforeValue);
+        applyMessageContent(nextMessageContent);
 
         const previousFinalChunk = previousChunks[previousChunks.length - 1]?.finalText || '';
         setDictationLastFinalChunk(previousFinalChunk);
         setDictationEditableChunk(previousFinalChunk);
-        focusTextareaSelection(lastChunk.start, lastChunk.start);
+        updateDictationInsertionCaret(dictationInsertionSelectionRef, nextCaret);
+        focusTextareaSelection(nextCaret, nextCaret);
     }, [
         applyMessageContent,
+        dictationInsertionSelectionRef,
         dictationChunks,
         focusTextareaSelection,
+        messageContentRef,
         setDictationChunks,
         setDictationEditableChunk,
         setDictationLastFinalChunk,
@@ -673,21 +773,27 @@ function useChatInputAreaDictationCorrectionHandlers({
             return;
         }
 
-        const nextMessageContent = replaceLastOccurrence(
-            messageContentRef.current,
-            dictationLastFinalChunk,
-            correctedChunk,
-        );
+        const lastChunk = dictationChunks[dictationChunks.length - 1];
+        const nextMessageContent = lastChunk
+            ? replaceTrackedDictationChunk(messageContentRef.current, lastChunk, correctedChunk)
+            : replaceLastOccurrence(messageContentRef.current, dictationLastFinalChunk, correctedChunk);
+        const correctionStart = lastChunk?.start ?? nextMessageContent.length;
+        const correctionCaret = Math.min(correctionStart + correctedChunk.length, nextMessageContent.length);
 
         applyMessageContent(nextMessageContent);
         setDictationLastFinalChunk(correctedChunk);
         setDictationChunks((previousChunks) => replaceLastDictationChunk(previousChunks, correctedChunk));
         setDictationDictionary(learnDictationDictionary(dictationLastFinalChunk, correctedChunk, dictationDictionary));
+        updateDictationInsertionCaret(dictationInsertionSelectionRef, correctionCaret);
+        focusTextareaSelection(correctionCaret, correctionCaret);
     }, [
         applyMessageContent,
         dictationDictionary,
         dictationEditableChunk,
+        dictationChunks,
+        dictationInsertionSelectionRef,
         dictationLastFinalChunk,
+        focusTextareaSelection,
         messageContentRef,
         setDictationChunks,
         setDictationDictionary,
@@ -713,7 +819,7 @@ export function useChatInputAreaDictation({
     applyMessageContent,
 }: UseChatInputAreaDictationProps) {
     const pendingStopFallbackRef = useRef<ReturnType<typeof setTimeout> | null>(null);
-    const replaceSelectionOnNextFinalRef = useRef(false);
+    const dictationInsertionSelectionRef = useRef<DictationInsertionSelection | null>(null);
     const [dictationUiState, setDictationUiState] = useState<DictationUiState>('idle');
     const [dictationInterimText, setDictationInterimText] = useState('');
     const [dictationError, setDictationError] = useState<DictationError | null>(null);
@@ -753,7 +859,7 @@ export function useChatInputAreaDictation({
         applyMessageContent,
         dictationSettings,
         dictationDictionary,
-        replaceSelectionOnNextFinalRef,
+        dictationInsertionSelectionRef,
         focusTextareaSelection,
         state: dictationState,
     });
@@ -775,7 +881,7 @@ export function useChatInputAreaDictation({
         resolvedSpeechRecognitionLanguage,
         whisperMode: dictationSettings.whisperMode,
         pendingStopFallbackRef,
-        replaceSelectionOnNextFinalRef,
+        dictationInsertionSelectionRef,
         clearPendingStopFallback,
         state: {
             dictationUiState,
@@ -789,6 +895,7 @@ export function useChatInputAreaDictation({
         dictationLastFinalChunk,
         dictationEditableChunk,
         dictationDictionary,
+        dictationInsertionSelectionRef,
         messageContentRef,
         applyMessageContent,
         focusTextareaSelection,

package/src/book-components/Chat/Chat/useChatToolCallModalState.ts

@@ -13,10 +13,7 @@ import { getToolCallTimestamp } from '../utils/toolCallParsing/getToolCallTimest
 import { parseTeamToolResult } from '../utils/toolCallParsing/parseTeamToolResult';
 import { parseToolCallResult } from '../utils/toolCallParsing/parseToolCallResult';
 import type { TeamToolResult } from '../utils/toolCallParsing/TeamToolResult';
-import {
-    createAdvancedToolCallReportFilename,
-    createAdvancedToolCallReportMarkdown,
-} from './renderAdvancedToolCallDetails';
+import { createAdvancedToolCallReportFilename, createAdvancedToolCallReportMarkdown } from './renderAdvancedToolCallDetails';
 
 /**
  * Tool-call snapshot rendered by the modal.

package/src/book-components/Chat/hooks/useChatRatings.ts

@@ -1,5 +1,5 @@
-import { useCallback, useEffect, useRef, useState } from 'react';
 import type { MutableRefObject } from 'react';
+import { useCallback, useEffect, useRef, useState } from 'react';
 import type { Promisable } from 'type-fest';
 import type { id } from '../../../types/string_token';
 import type { ChatFeedbackMode, ChatFeedbackResponse, ChatProps } from '../Chat/ChatProps';

package/src/book-components/Chat/save/html/htmlSaveFormatDefinition.ts

@@ -4,7 +4,7 @@ import type { ChatParticipant } from '../../types/ChatParticipant';
 import { resolveCitationPreviewUrl } from '../../utils/citationHelpers';
 import { parseMessageButtons } from '../../utils/parseMessageButtons';
 import { renderMarkdown } from '../../utils/renderMarkdown';
-import type { ChatSaveFormatDefinition } from '../_common/ChatSaveFormatDefinition';
+import type { ChatExportCitationFootnoteRegistry, ChatExportCitationRenderModel } from '../_common/chatExportRendering';
 import {
     buildChatExportParticipantMap,
     createChatExportCitationFootnoteRegistry,
@@ -12,9 +12,8 @@ import {
     formatChatExportCitationFootnoteLabel,
     formatChatExportTimestamp,
     resolveChatExportParticipantVisuals,
-    type ChatExportCitationFootnoteRegistry,
-    type ChatExportCitationRenderModel,
 } from '../_common/chatExportRendering';
+import type { ChatSaveFormatDefinition } from '../_common/ChatSaveFormatDefinition';
 import { getPromptbookExportBranding } from '../_common/getPromptbookExportBranding';
 
 /**

package/src/book-components/Chat/save/markdown/mdSaveFormatDefinition.ts

@@ -2,7 +2,7 @@ import { spaceTrim } from 'spacetrim';
 import type { ChatMessage } from '../../types/ChatMessage';
 import type { ChatParticipant } from '../../types/ChatParticipant';
 import { resolveCitationPreviewUrl } from '../../utils/citationHelpers';
-import type { ChatSaveFormatDefinition } from '../_common/ChatSaveFormatDefinition';
+import type { ChatExportCitationFootnoteRegistry } from '../_common/chatExportRendering';
 import {
     buildChatExportParticipantMap,
     createChatExportCitationFootnoteRegistry,
@@ -10,8 +10,8 @@ import {
     formatChatExportCitationFootnoteLabel,
     formatChatExportTimestamp,
     resolveChatExportParticipantVisuals,
-    type ChatExportCitationFootnoteRegistry,
 } from '../_common/chatExportRendering';
+import type { ChatSaveFormatDefinition } from '../_common/ChatSaveFormatDefinition';
 import { getPromptbookExportBranding } from '../_common/getPromptbookExportBranding';
 
 /**

package/src/book-components/Chat/save/pdf/buildChatPdf.ts

@@ -4,8 +4,8 @@ import { spaceTrim } from 'spacetrim';
 import { UnexpectedError } from '../../../../errors/UnexpectedError';
 import type { ChatMessage } from '../../types/ChatMessage';
 import type { ChatParticipant } from '../../types/ChatParticipant';
-import { getPromptbookExportBranding } from '../_common/getPromptbookExportBranding';
 import { buildChatHtml, CHAT_HTML_EXPORT_RENDER_ROOT_CLASS_NAME } from '../html/htmlSaveFormatDefinition';
+import { getPromptbookExportBranding } from '../_common/getPromptbookExportBranding';
 
 /**
  * Pixel width used while the standalone HTML document is laid out for PDF pages.

package/src/book-components/Chat/utils/getToolCallChipletInfo.ts

@@ -3,11 +3,7 @@ import { ASSISTANT_PREPARATION_TOOL_CALL_NAME } from '../../../types/ToolCall';
 import type { AgentChipData } from '../AgentChip/AgentChip';
 import { formatToolCallLocalTime } from './formatToolCallLocalTime';
 import { formatToolCallTranslationTemplate } from './formatToolCallTranslationTemplate';
-import {
-    buildTimeoutToolCallChipLabel,
-    isTimeoutToolCallName,
-    resolveTimeoutToolCallPresentation,
-} from './timeoutToolCallPresentation';
+import { buildTimeoutToolCallChipLabel, isTimeoutToolCallName, resolveTimeoutToolCallPresentation } from './timeoutToolCallPresentation';
 import { getToolCallResultDate } from './toolCallParsing/getToolCallResultDate';
 import { parseTeamToolResult } from './toolCallParsing/parseTeamToolResult';
 import { parseToolCallArguments } from './toolCallParsing/parseToolCallArguments';

package/src/book-components/Chat/utils/isVisibleChatToolCall.ts

@@ -1,4 +1,5 @@
-import { ASSISTANT_PREPARATION_TOOL_CALL_NAME, type ToolCall } from '../../../types/ToolCall';
+import type { ToolCall } from '../../../types/ToolCall';
+import { ASSISTANT_PREPARATION_TOOL_CALL_NAME } from '../../../types/ToolCall';
 
 /**
  * Tool calls that stay available in message data but should not be surfaced as user-facing chat progress.

package/src/book-components/Chat/utils/parseMessageButtons.ts

@@ -9,6 +9,20 @@ export type MessageQuickButton = {
     message: string;
 };
 
+/**
+ * Represents a quick draft-message button parsed from chat markdown.
+ *
+ * Unlike `MessageQuickButton`, clicking this button prefills the composer with an
+ * editable draft instead of sending the message immediately.
+ *
+ * @private internal helper type of `MessageButton`
+ */
+export type MessageDraftQuickButton = {
+    type: 'messageDraft';
+    text: string;
+    messageDraft: string;
+};
+
 /**
  * Represents a quick action button parsed from chat markdown.
  *
@@ -25,7 +39,7 @@ export type ActionQuickButton = {
  *
  * @public exported from `@promptbook/components`
  */
-export type MessageButton = MessageQuickButton | ActionQuickButton;
+export type MessageButton = MessageQuickButton | MessageDraftQuickButton | ActionQuickButton;
 
 /**
  * Extracts one quick button definition from a markdown link query string.
@@ -48,6 +62,16 @@ function parseQuickButtonDefinition(text: string, query: string): MessageButton
         };
     }
 
+    const messageDraft = searchParams.get('messageDraft');
+
+    if (messageDraft !== null) {
+        return {
+            type: 'messageDraft',
+            text,
+            messageDraft,
+        };
+    }
+
     const code = searchParams.get('action');
 
     if (code !== null) {
@@ -62,7 +86,8 @@ function parseQuickButtonDefinition(text: string, query: string): MessageButton
 }
 
 /**
- * Parses markdown quick buttons in the format `[Button Text](?message=...)` or `[Button Text](?action=...)`.
+ * Parses markdown quick buttons in the format `[Button Text](?message=...)`, `[Button Text](?messageDraft=...)`
+ * or `[Button Text](?action=...)`.
  * Returns both the content without supported quick buttons and the extracted button definitions.
  *
  * @param content The markdown content that may contain buttons

package/src/cli/cli-commands/about.ts

@@ -1,6 +1,6 @@
 import colors from 'colors';
 import type {
-    Command as Program /* <- Note: [🔸] Using Program because Command is misleading name */,
+  Command as Program /* <- Note: [🔸] Using Program because Command is misleading name */
 } from 'commander';
 import { spaceTrim } from 'spacetrim';
 import { CLAIM } from '../../config';

package/src/cli/cli-commands/agent/agentCliOptions.ts

@@ -1,11 +1,8 @@
 import type {
-    Command as Program /* <- Note: [🔸] Using Program because Command is misleading name */,
+  Command as Program /* <- Note: [🔸] Using Program because Command is misleading name */
 } from 'commander';
 import { NotAllowed } from '../../../errors/NotAllowed';
-import type {
-    NormalizedPromptRunnerSelectionCliOptions,
-    PromptRunnerSelectionCliOptions,
-} from '../common/promptRunnerCliOptions';
+import type { NormalizedPromptRunnerSelectionCliOptions, PromptRunnerSelectionCliOptions } from '../common/promptRunnerCliOptions';
 import { normalizePromptRunnerSelectionCliOptions } from '../common/promptRunnerCliOptions';
 
 /**

package/src/cli/cli-commands/agent-folder/agentProjectPaths.ts

@@ -1,19 +1,13 @@
 import { join } from 'path';
 import { spaceTrim } from 'spacetrim';
-import {
-    AGENT_BOOK_FILE_PATH,
-    AGENT_FAILED_MESSAGES_DIRECTORY_PATH,
-    AGENT_FINISHED_MESSAGES_DIRECTORY_PATH,
-    AGENT_MESSAGES_DIRECTORY_PATH,
-    AGENT_QUEUED_MESSAGES_DIRECTORY_PATH,
-} from '../../../book-3.0/agentFolderPaths';
+import { AGENT_BOOK_FILE_PATH, AGENT_FAILED_MESSAGES_DIRECTORY_PATH, AGENT_FINISHED_MESSAGES_DIRECTORY_PATH, AGENT_MESSAGES_DIRECTORY_PATH, AGENT_QUEUED_MESSAGES_DIRECTORY_PATH } from '../../../book-3.0/agentFolderPaths';
 
 export {
-    AGENT_BOOK_FILE_PATH,
-    AGENT_FAILED_MESSAGES_DIRECTORY_PATH,
-    AGENT_FINISHED_MESSAGES_DIRECTORY_PATH,
-    AGENT_MESSAGES_DIRECTORY_PATH,
-    AGENT_QUEUED_MESSAGES_DIRECTORY_PATH,
+  AGENT_BOOK_FILE_PATH,
+  AGENT_FAILED_MESSAGES_DIRECTORY_PATH,
+  AGENT_FINISHED_MESSAGES_DIRECTORY_PATH,
+  AGENT_MESSAGES_DIRECTORY_PATH,
+  AGENT_QUEUED_MESSAGES_DIRECTORY_PATH,
 };
 
 /**

package/src/cli/cli-commands/agent-folder/init.ts

@@ -1,16 +1,11 @@
 import type {
-    Command as Program /* <- Note: [🔸] Using Program because Command is misleading name */,
+  Command as Program /* <- Note: [🔸] Using Program because Command is misleading name */
 } from 'commander';
 import { spaceTrim } from 'spacetrim';
+import { AGENT_BOOK_FILE_PATH, AGENT_FINISHED_MESSAGES_DIRECTORY_PATH, AGENT_QUEUED_MESSAGES_DIRECTORY_PATH } from '../../../book-3.0/agentFolderPaths';
 import type { $side_effect } from '../../../utils/organization/$side_effect';
 import { handleActionErrors } from '../common/handleActionErrors';
-import {
-    AGENT_BOOK_FILE_PATH,
-    AGENT_BOOK_LANGUAGE_MANUAL_FILE_PATH,
-    AGENT_FINISHED_MESSAGES_DIRECTORY_PATH,
-    AGENT_KNOWLEDGE_DIRECTORY_PATH,
-    AGENT_QUEUED_MESSAGES_DIRECTORY_PATH,
-} from './agentProjectPaths';
+import { AGENT_BOOK_LANGUAGE_MANUAL_FILE_PATH, AGENT_KNOWLEDGE_DIRECTORY_PATH } from './agentProjectPaths';
 import { initializeAgentProjectConfiguration } from './initializeAgentProjectConfiguration';
 import { printAgentInitializationSummary } from './printAgentInitializationSummary';
 

package/src/cli/cli-commands/agent-folder/initializeAgentProjectConfiguration.ts

@@ -1,17 +1,8 @@
+import { AGENT_BOOK_FILE_PATH, AGENT_FINISHED_MESSAGES_DIRECTORY_PATH, AGENT_MESSAGES_DIRECTORY_PATH, AGENT_QUEUED_MESSAGES_DIRECTORY_PATH } from '../../../book-3.0/agentFolderPaths';
 import type { InitializationStatus } from '../coder/boilerplateTemplates';
 import { ensureCoderMarkdownFile } from '../coder/ensureCoderMarkdownFile';
 import { ensureDirectory } from '../coder/ensureDirectory';
-import {
-    AGENT_BOOK_FILE_PATH,
-    AGENT_BOOK_LANGUAGE_MANUAL_FILE_PATH,
-    AGENT_DOCS_DIRECTORY_PATH,
-    AGENT_FINISHED_MESSAGES_DIRECTORY_PATH,
-    AGENT_KNOWLEDGE_DIRECTORY_PATH,
-    AGENT_MESSAGES_DIRECTORY_PATH,
-    AGENT_QUEUED_MESSAGES_DIRECTORY_PATH,
-    getDefaultAgentBookContent,
-    getDefaultBookLanguageManualContent,
-} from './agentProjectPaths';
+import { AGENT_BOOK_LANGUAGE_MANUAL_FILE_PATH, AGENT_DOCS_DIRECTORY_PATH, AGENT_KNOWLEDGE_DIRECTORY_PATH, getDefaultAgentBookContent, getDefaultBookLanguageManualContent } from './agentProjectPaths';
 
 /**
  * Result summary returned after local agent configuration initialization.

package/src/cli/cli-commands/agent-folder/printAgentInitializationSummary.ts

@@ -1,14 +1,7 @@
 import colors from 'colors';
+import { AGENT_BOOK_FILE_PATH, AGENT_FINISHED_MESSAGES_DIRECTORY_PATH, AGENT_MESSAGES_DIRECTORY_PATH, AGENT_QUEUED_MESSAGES_DIRECTORY_PATH } from '../../../book-3.0/agentFolderPaths';
 import type { InitializationStatus } from '../coder/boilerplateTemplates';
-import {
-    AGENT_BOOK_FILE_PATH,
-    AGENT_BOOK_LANGUAGE_MANUAL_FILE_PATH,
-    AGENT_DOCS_DIRECTORY_PATH,
-    AGENT_FINISHED_MESSAGES_DIRECTORY_PATH,
-    AGENT_KNOWLEDGE_DIRECTORY_PATH,
-    AGENT_MESSAGES_DIRECTORY_PATH,
-    AGENT_QUEUED_MESSAGES_DIRECTORY_PATH,
-} from './agentProjectPaths';
+import { AGENT_BOOK_LANGUAGE_MANUAL_FILE_PATH, AGENT_DOCS_DIRECTORY_PATH, AGENT_KNOWLEDGE_DIRECTORY_PATH } from './agentProjectPaths';
 import type { AgentInitializationSummary } from './initializeAgentProjectConfiguration';
 
 /**

package/src/cli/cli-commands/agents-server/buildAgentsServer/AGENTS_SERVER_BUILD_CACHE_FILENAME.ts

@@ -0,0 +1,6 @@
+/**
+ * Metadata file stored beside the production Next build output.
+ *
+ * @private internal constant of `buildAgentsServer`
+ */
+export const AGENTS_SERVER_BUILD_CACHE_FILENAME = '.ptbk-agents-server-build-cache.json';

package/src/cli/cli-commands/agents-server/buildAgentsServer/AGENTS_SERVER_BUILD_CACHE_VERSION.ts

@@ -0,0 +1,6 @@
+/**
+ * Version of the CLI-owned Agents Server build cache metadata.
+ *
+ * @private internal constant of `buildAgentsServer`
+ */
+export const AGENTS_SERVER_BUILD_CACHE_VERSION = 1;

package/src/cli/cli-commands/agents-server/buildAgentsServer/AGENTS_SERVER_NEXT_BUILD_ID_FILENAME.ts

@@ -0,0 +1,6 @@
+/**
+ * Next production build marker required before a cached build is reused.
+ *
+ * @private internal constant of `buildAgentsServer`
+ */
+export const AGENTS_SERVER_NEXT_BUILD_ID_FILENAME = 'BUILD_ID';

package/src/cli/cli-commands/agents-server/buildAgentsServer/AgentsServerBuildCache.ts

@@ -0,0 +1,11 @@
+import { AGENTS_SERVER_BUILD_CACHE_VERSION } from './AGENTS_SERVER_BUILD_CACHE_VERSION';
+
+/**
+ * Metadata persisted after one successful Agents Server production build.
+ *
+ * @private internal type of `buildAgentsServer`
+ */
+export type AgentsServerBuildCache = {
+    readonly version: typeof AGENTS_SERVER_BUILD_CACHE_VERSION;
+    readonly sourceFingerprint: string;
+};

package/src/cli/cli-commands/agents-server/buildAgentsServer/AgentsServerBuildCacheOptions.ts

@@ -0,0 +1,9 @@
+/**
+ * Input paths required to validate or update the cached Agents Server build.
+ *
+ * @private internal type of `buildAgentsServer`
+ */
+export type AgentsServerBuildCacheOptions = {
+    readonly appPath: string;
+    readonly environment?: NodeJS.ProcessEnv;
+};