@promptbook/utils 0.112.0-99 → 0.113.0-0

package/esm/src/book-components/BookEditor/createDeprecatedCommitmentDiagnostics.browser.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Browser-compatible stub for `createDeprecatedCommitmentDiagnostics`.
+ *
+ * In the browser build the full Node.js implementation is not available,
+ * so this stub always returns an empty array to keep the editor functional.
+ *
+ * @private internal utility of `BookEditorMonaco`
+ */
+export declare function createDeprecatedCommitmentDiagnostics(_agentSource?: string): [];

package/esm/src/book-components/BookEditor/useBookEditorMonacoLanguage.d.ts

@@ -1,14 +1,9 @@
 import type { editor } from 'monaco-editor';
+import type { BookEditorTheme } from './BookEditorTheme';
 /**
  * Type describing monaco editor.
  */
 type MonacoEditor = typeof import('monaco-editor');
-/**
- * Resolved visual theme supported by the Book editor.
- *
- * @private function of BookEditorMonaco
- */
-type BookEditorTheme = 'LIGHT' | 'DARK';
 /**
  * Props for use book editor monaco language.
  */

package/esm/src/book-components/BookEditor/useBookEditorMonacoLifecycle.d.ts

@@ -1,12 +1,9 @@
 import type { editor } from 'monaco-editor';
+import type { BookEditorTheme } from './BookEditorTheme';
 /**
  * Type describing monaco editor.
  */
 type MonacoEditor = typeof import('monaco-editor');
-/**
- * Resolved visual theme supported by the Book editor.
- */
-type BookEditorTheme = 'LIGHT' | 'DARK';
 /**
  * Props for use book editor monaco lifecycle.
  */

package/esm/src/book-components/BookEditor/useBookEditorMonacoStyles.d.ts

@@ -1,3 +1,4 @@
+import type { BookEditorTheme } from './BookEditorTheme';
 /**
  * Props for use book editor monaco styles.
  */
@@ -7,7 +8,7 @@ type UseBookEditorMonacoStylesProps = {
     readonly scaledContentPaddingLeft: number;
     readonly scaledVerticalLineLeft: number;
     readonly zoomLevel: number;
-    readonly theme: 'LIGHT' | 'DARK';
+    readonly theme: BookEditorTheme;
 };
 /**
  * Injects notebook-inspired styling that is unique per `BookEditorMonaco` instance.

package/esm/src/book-components/Chat/Chat/ChatCitationModal.d.ts

@@ -1,4 +1,5 @@
 import type { ChatParticipant } from '../types/ChatParticipant';
+import type { CitationLabelResolver } from '../types/CitationLabelResolver';
 import type { ParsedCitation } from '../utils/parseCitationsFromContent';
 import type { ChatSoundSystem } from './ChatProps';
 /**
@@ -10,6 +11,7 @@ export type ChatCitationModalProps = {
     isOpen: boolean;
     citation: ParsedCitation | null;
     participants: ReadonlyArray<ChatParticipant>;
+    resolveCitationLabel?: CitationLabelResolver;
     soundSystem?: ChatSoundSystem;
     onClose: () => void;
 };

package/esm/src/book-components/Chat/Chat/ChatMessageItem.d.ts

@@ -38,6 +38,10 @@ type ChatMessageItemProps = Pick<ChatProps, 'onMessage' | 'onActionButton' | 'on
      * Optional localized labels used by timestamp metadata.
      */
     timingTranslations?: ChatProps['timingTranslations'];
+    /**
+     * Optional resolver for turning technical citation sources into page/document titles.
+     */
+    resolveCitationLabel?: ChatProps['resolveCitationLabel'];
     /**
      * Optional moment locale used to format message timestamps.
      */

package/esm/src/book-components/Chat/Chat/ChatMessageList.d.ts

@@ -32,6 +32,10 @@ export type ChatMessageListProps = {
      * Optional localized labels used by timestamp metadata.
      */
     timingTranslations?: ChatProps['timingTranslations'];
+    /**
+     * Optional resolver for turning technical citation sources into page/document titles.
+     */
+    resolveCitationLabel?: ChatProps['resolveCitationLabel'];
     /**
      * Optional moment locale used to format message timestamps.
      */

package/esm/src/book-components/Chat/Chat/ChatProps.d.ts

@@ -8,6 +8,7 @@ import type { AgentChipData } from '../AgentChip/AgentChip';
 import type { string_chat_format_name } from '../save/_common/string_chat_format_name';
 import type { ChatMessage } from '../types/ChatMessage';
 import type { ChatParticipant } from '../types/ChatParticipant';
+import type { CitationLabelResolver } from '../types/CitationLabelResolver';
 import type { ChatSaveFormatHandlerMap } from '../save/_common/ChatSaveFormatHandler';
 /**
  * Response data returned by the optional `onFeedback` handler.
@@ -715,6 +716,10 @@ export type ChatProps = {
      * Optional localized labels used by timestamp metadata shown under messages.
      */
     readonly timingTranslations?: ChatTimingTranslations;
+    /**
+     * Optional resolver for turning technical citation sources into page/document titles.
+     */
+    readonly resolveCitationLabel?: CitationLabelResolver;
     /**
      * Optional localized labels for general Chat UI elements such as button labels,
      * lifecycle state badges, tool call modal strings, and the default input placeholder.

package/esm/src/book-components/Chat/Chat/ChatToolCallModal.d.ts

@@ -3,6 +3,7 @@ import type { WithTake } from '../../../utils/take/interfaces/ITakeChain';
 import type { AgentChipData } from '../AgentChip/AgentChip';
 import type { ChatMessage } from '../types/ChatMessage';
 import type { ChatParticipant } from '../types/ChatParticipant';
+import type { CitationLabelResolver } from '../types/CitationLabelResolver';
 /**
  * Props for the tool call details modal.
  *
@@ -20,6 +21,7 @@ export type ChatToolCallModalProps = {
     toolCallIdentity?: string | null;
     onClose: () => void;
     toolTitles?: Record<string, string>;
+    resolveCitationLabel?: CitationLabelResolver;
     agentParticipant?: ChatParticipant;
     buttonColor: WithTake<Color>;
     /**

package/esm/src/book-components/Chat/Chat/ChatToolCallModalContent.d.ts

@@ -3,6 +3,7 @@ import { Color } from '../../../utils/color/Color';
 import type { WithTake } from '../../../utils/take/interfaces/ITakeChain';
 import type { ChatMessage } from '../types/ChatMessage';
 import type { ChatParticipant } from '../types/ChatParticipant';
+import type { CitationLabelResolver } from '../types/CitationLabelResolver';
 import type { TeamToolCallSummary, TransitiveToolCall } from '../utils/collectTeamToolCallSummary';
 import type { AgentProfileData } from '../utils/loadAgentProfile';
 import type { TeamToolResult } from '../utils/toolCallParsing/TeamToolResult';
@@ -27,6 +28,7 @@ type ChatToolCallModalContentProps = {
     readonly isAdvancedView: boolean;
     readonly locale?: string;
     readonly mode: 'LIGHT' | 'DARK';
+    readonly resolveCitationLabel?: CitationLabelResolver;
     readonly onClearSelectedTeamToolCall: () => void;
     readonly onRequestAdvancedView: () => void;
     readonly onSelectTeamToolCall: (toolCall: TransitiveToolCall) => void;
@@ -43,5 +45,5 @@ type ChatToolCallModalContentProps = {
  *
  * @private component of `ChatToolCallModal`
  */
-export declare function ChatToolCallModalContent({ agentParticipant, availableTools, buttonColor, chatUiTranslations, focusedToolCall, isAdvancedView, locale, mode, onClearSelectedTeamToolCall, onRequestAdvancedView, onSelectTeamToolCall, selectedTeamToolCall, teamProfiles, teamResult, teamToolCallSummary, toolCall, toolCallDate, toolTitles, }: ChatToolCallModalContentProps): ReactElement;
+export declare function ChatToolCallModalContent({ agentParticipant, availableTools, buttonColor, chatUiTranslations, focusedToolCall, isAdvancedView, locale, mode, resolveCitationLabel, onClearSelectedTeamToolCall, onRequestAdvancedView, onSelectTeamToolCall, selectedTeamToolCall, teamProfiles, teamResult, teamToolCallSummary, toolCall, toolCallDate, toolTitles, }: ChatToolCallModalContentProps): ReactElement;
 export {};

package/esm/src/book-components/Chat/Chat/CitationIframePreview.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Props for the citation iframe preview component.
+ *
+ * @private component of `<ChatCitationModal/>`
+ */
+export type CitationIframePreviewProps = {
+    src: string;
+    title: string;
+};
+/**
+ * Renders a citation URL preview as an iframe when the target page allows embedding,
+ * or falls back to a server-side screenshot with an "Open in new tab" link when it
+ * does not (e.g. X-Frame-Options: DENY / SAMEORIGIN).
+ *
+ * Embedding capability is determined by `GET /api/page-preview/check?url=<url>`.
+ * If that endpoint is unavailable the component falls back to the iframe directly.
+ *
+ * @private component of `<ChatCitationModal/>`
+ */
+export declare function CitationIframePreview({ src, title }: CitationIframePreviewProps): import("react/jsx-runtime").JSX.Element;

package/esm/src/book-components/Chat/Chat/TeamToolCallModalContent.d.ts

@@ -2,6 +2,7 @@ import { type ReactElement } from 'react';
 import { Color } from '../../../utils/color/Color';
 import type { WithTake } from '../../../utils/take/interfaces/ITakeChain';
 import type { ChatParticipant } from '../types/ChatParticipant';
+import type { CitationLabelResolver } from '../types/CitationLabelResolver';
 import type { TeamToolCallSummary, TransitiveToolCall } from '../utils/collectTeamToolCallSummary';
 import type { AgentProfileData } from '../utils/loadAgentProfile';
 import type { TeamToolResult } from '../utils/toolCallParsing/TeamToolResult';
@@ -19,6 +20,7 @@ type TeamToolCallModalContentOptions = {
     onClearSelectedTeamToolCall: () => void;
     teamProfiles: Record<string, AgentProfileData>;
     toolTitles?: Record<string, string>;
+    resolveCitationLabel?: CitationLabelResolver;
     agentParticipant?: ChatParticipant;
     buttonColor: WithTake<Color>;
 };

package/esm/src/book-components/Chat/MarkdownContent/MarkdownContent.d.ts

@@ -7,6 +7,7 @@ type MarkdownContentProps = {
     content: string_markdown;
     className?: string;
     onCreateAgent?: (bookContent: string) => void;
+    theme?: 'LIGHT' | 'DARK';
 };
 /**
  * Renders markdown content with support for code highlighting, math, and tables.

package/esm/src/book-components/Chat/SourceChip/SourceChip.d.ts

@@ -1,3 +1,4 @@
+import type { CitationLabelResolver } from '../types/CitationLabelResolver';
 import type { ParsedCitation } from '../utils/parseCitationsFromContent';
 /**
  * Props for SourceChip component
@@ -19,6 +20,10 @@ export type SourceChipProps = {
      * Optional suffix text to display after the citation label.
      */
     suffix?: string;
+    /**
+     * Optional resolver for richer citation labels.
+     */
+    resolveCitationLabel?: CitationLabelResolver;
     /**
      * Controls whether the technical citation id is shown inside the chip label.
      */
@@ -41,4 +46,4 @@ export type SourceChipProps = {
  *
  * @private utility of `ChatMessageItem` component
  */
-export declare function SourceChip({ citation, onClick, className, suffix, isCitationIdVisible }: SourceChipProps): import("react/jsx-runtime").JSX.Element;
+export declare function SourceChip({ citation, onClick, className, suffix, resolveCitationLabel, isCitationIdVisible, }: SourceChipProps): import("react/jsx-runtime").JSX.Element;

package/esm/src/book-components/Chat/hooks/useResolvedCitationLabel.d.ts

@@ -0,0 +1,12 @@
+import type { CitationLabelResolver } from '../types/CitationLabelResolver';
+import type { ParsedCitation } from '../utils/parseCitationsFromContent';
+/**
+ * Resolves the best available label for one citation.
+ *
+ * @param citation - Citation metadata.
+ * @param resolveCitationLabel - Optional async host resolver.
+ * @returns Current label, starting with a synchronous fallback and updating when the resolver finishes.
+ *
+ * @private hook of `<Chat/>`
+ */
+export declare function useResolvedCitationLabel(citation: ParsedCitation, resolveCitationLabel?: CitationLabelResolver): string;

package/esm/src/book-components/Chat/types/ChatMessage.d.ts

@@ -254,6 +254,10 @@ export type ChatMessage = Omit<Message<id>, 'direction' | 'recipients' | 'thread
          * Optional URL to the source document
          */
         url?: string;
+        /**
+         * Optional human-readable source title.
+         */
+        title?: string;
         /**
          * Optional preview/excerpt from the source
          */

package/esm/src/book-components/Chat/types/ChatParticipant.d.ts

@@ -47,7 +47,7 @@ export type ChatParticipant = {
      * Knowledge sources (documents, URLs) used by the agent
      * Used for resolving document citations when the agent references sources
      */
-    knowledgeSources?: Array<{
+    knowledgeSources?: ReadonlyArray<{
         url: string;
         filename: string;
     }>;

package/esm/src/book-components/Chat/types/CitationLabelResolver.d.ts

@@ -0,0 +1,8 @@
+import type { Promisable } from 'type-fest';
+import type { ParsedCitation } from '../utils/parseCitationsFromContent';
+/**
+ * Optional host-provided resolver for citation display labels.
+ *
+ * @public exported from `@promptbook/components`
+ */
+export type CitationLabelResolver = (citation: ParsedCitation) => Promisable<string | null | undefined>;

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

@@ -37,3 +37,12 @@ export declare function getCitationLabel(citation: ParsedCitation): string;
  * @private utility of `<Chat/>` citation rendering
  */
 export declare function resolveCitationPreviewUrl(citation: ParsedCitation, participants: ReadonlyArray<ChatParticipant>): string | null;
+/**
+ * Creates a readable fallback label from a citation source when no title metadata is available.
+ *
+ * @param source - Raw citation source value.
+ * @returns Human-friendly source label.
+ *
+ * @private utility of `<Chat/>` citation rendering
+ */
+export declare function createReadableCitationSourceLabel(source: string): string;

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

@@ -0,0 +1,14 @@
+import type { string_markdown } from '../../../types/string_markdown';
+/**
+ * Decodes JSON-style Unicode escape sequences in markdown prose while preserving code.
+ *
+ * Model/tool output can occasionally arrive as already JSON-escaped text, which makes
+ * natural-language replies render `\u00fd` instead of the decoded character. This
+ * keeps code examples intact by skipping fenced code blocks and inline code spans.
+ *
+ * @param markdown - Markdown chat content to normalize for display.
+ * @returns Markdown chat content with non-ASCII JSON Unicode escapes decoded.
+ *
+ * @private internal utility of `<Chat/>`
+ */
+export declare function decodeJsonUnicodeEscapesInMarkdownText(markdown: string_markdown): string_markdown;

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

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

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

@@ -0,0 +1,10 @@
+import { type ToolCall } from '../../../types/ToolCall';
+/**
+ * Returns true when one tool call represents a user-facing action.
+ *
+ * @param toolCall - Tool call candidate.
+ * @returns Whether the tool call should be visible in chat progress and chips.
+ *
+ * @private internal utility of `<Chat/>`
+ */
+export declare function isVisibleChatToolCall(toolCall: Pick<ToolCall, 'name'>): boolean;

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

@@ -15,6 +15,10 @@ export type ParsedCitation = {
      * Optional URL to the source document
      */
     url?: string;
+    /**
+     * Optional human-readable source title.
+     */
+    title?: string;
     /**
      * Optional preview/excerpt from the source
      */

package/esm/src/book-components/_common/Dropdown/Dropdown.d.ts

@@ -1,4 +1,4 @@
-import { ReactNode } from 'react';
+import { type ReactNode } from 'react';
 /**
  * Props for dropdown.
  */

package/esm/src/book-components/_common/MenuHoisting/MenuHoistingContext.d.ts

@@ -1,4 +1,4 @@
-import { ReactNode } from 'react';
+import { type ReactNode } from 'react';
 /**
  * Item that can be hoisted to the top menu
  *

package/esm/src/book-components/_common/Modal/Modal.d.ts

@@ -1,4 +1,4 @@
-import { ReactNode } from 'react';
+import { type ReactNode } from 'react';
 /**
  * Handles modal.
  *

package/esm/src/book-components/icons/AboutIcon.d.ts

@@ -1,4 +1,4 @@
-import { SVGProps } from 'react';
+import type { SVGProps } from 'react';
 /**
  * Renders an information/about icon.
  *

package/esm/src/book-components/icons/DownloadIcon.d.ts

@@ -1,4 +1,4 @@
-import { SVGProps } from 'react';
+import type { SVGProps } from 'react';
 /**
  * Renders a download icon.
  *

package/esm/src/book-components/icons/ExitFullscreenIcon.d.ts

@@ -1,4 +1,4 @@
-import { JSX } from 'react';
+import type { JSX } from 'react';
 /**
  * Renders an icon that represents the exit fullscreen action
  *

package/esm/src/book-components/icons/FullscreenIcon.d.ts

@@ -1,4 +1,4 @@
-import { JSX } from 'react';
+import type { JSX } from 'react';
 /**
  * Renders an icon that represents the fullscreen action
  *

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

@@ -0,0 +1,38 @@
+import type { Command as Program } from 'commander';
+import type { NormalizedPromptRunnerSelectionCliOptions, PromptRunnerSelectionCliOptions } from '../common/promptRunnerCliOptions';
+/**
+ * Commander option bag shared by `ptbk agent` subcommands.
+ *
+ * @private internal utility of `ptbk agent`
+ */
+export type AgentCommandCliOptions = PromptRunnerSelectionCliOptions & {
+    readonly agent?: string;
+    readonly context?: string;
+    readonly message?: string;
+};
+/**
+ * Normalized shared options used by local `ptbk agent` subcommands.
+ *
+ * @private internal utility of `ptbk agent`
+ */
+export type NormalizedAgentCommandRunnerOptions = NormalizedPromptRunnerSelectionCliOptions & {
+    readonly isVerbose: boolean;
+};
+/**
+ * Normalizes shared runner flags for local agent subcommands.
+ *
+ * @private internal utility of `ptbk agent`
+ */
+export declare function normalizeAgentCommandRunnerOptions(cliOptions: AgentCommandCliOptions, command: Program): NormalizedAgentCommandRunnerOptions;
+/**
+ * Returns the required agent book path from Commander options.
+ *
+ * @private internal utility of `ptbk agent`
+ */
+export declare function resolveRequiredAgentPath(cliOptions: AgentCommandCliOptions): string;
+/**
+ * Returns the required single-turn user message from Commander options.
+ *
+ * @private internal utility of `ptbk agent`
+ */
+export declare function resolveRequiredAgentMessage(cliOptions: AgentCommandCliOptions): string;

package/esm/src/cli/cli-commands/agent/chat.d.ts

@@ -0,0 +1,10 @@
+import type { Command as Program } from 'commander';
+import type { $side_effect } from '../../../utils/organization/$side_effect';
+/**
+ * Initializes `agent chat` command for Promptbook CLI utilities.
+ *
+ * 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`
+ */
+export declare function $initializeAgentChatCommand(program: Program): $side_effect;

package/esm/src/cli/cli-commands/agent/exec.d.ts

@@ -0,0 +1,10 @@
+import type { Command as Program } from 'commander';
+import type { $side_effect } from '../../../utils/organization/$side_effect';
+/**
+ * Initializes `agent exec` command for Promptbook CLI utilities.
+ *
+ * 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`
+ */
+export declare function $initializeAgentExecCommand(program: Program): $side_effect;

package/esm/src/cli/cli-commands/agent/run.test.d.ts

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

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

@@ -1,33 +1,11 @@
-/**
- * Relative path to the local agent source initialized by `ptbk agent-folder init`.
- *
- * @private internal utility of `ptbk agent-folder`
- */
-export declare const AGENT_BOOK_FILE_PATH = "agent.book";
+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, };
 /**
  * Relative path to local knowledge files initialized by `ptbk agent-folder init`.
  *
  * @private internal utility of `ptbk agent-folder`
  */
 export declare const AGENT_KNOWLEDGE_DIRECTORY_PATH = "knowledge";
-/**
- * Relative path to the message queue root initialized by `ptbk agent-folder init`.
- *
- * @private internal utility of `ptbk agent-folder`
- */
-export declare const AGENT_MESSAGES_DIRECTORY_PATH = "messages";
-/**
- * Relative path to queued user messages consumed by `ptbk agent-folder run-once`.
- *
- * @private internal utility of `ptbk agent-folder`
- */
-export declare const AGENT_QUEUED_MESSAGES_DIRECTORY_PATH: string;
-/**
- * Relative path to answered messages written by `ptbk agent-folder run-once`.
- *
- * @private internal utility of `ptbk agent-folder`
- */
-export declare const AGENT_FINISHED_MESSAGES_DIRECTORY_PATH: string;
 /**
  * Relative path to generated local agent documentation initialized by `ptbk agent-folder init`.
  *

package/esm/src/cli/cli-commands/agent.d.ts

@@ -0,0 +1,14 @@
+import type { Command as Program } from 'commander';
+import type { $side_effect } from '../../utils/organization/$side_effect';
+/**
+ * Initializes `agent` command with subcommands for Promptbook CLI utilities.
+ *
+ * The agent command runs one `.book` source directly through a selected CLI harness:
+ * - chat: Run an interactive terminal chat session
+ * - exec: Send one message and print the response
+ *
+ * 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`
+ */
+export declare function $initializeAgentCommand(program: Program): $side_effect;

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

@@ -6,6 +6,12 @@
  * @private internal constant of `ptbk agents-server`
  */
 export declare const PTBK_AGENTS_SERVER_NODE_MODULES_PATH_ENV = "PTBK_AGENTS_SERVER_NODE_MODULES_PATH";
+/**
+ * Environment variable consumed by `apps/agents-server/next.config.ts` to throttle build workers.
+ *
+ * @private internal constant of `ptbk agents-server`
+ */
+export declare const PTBK_AGENTS_SERVER_BUILD_WORKER_COUNT_ENV = "PTBK_AGENTS_SERVER_BUILD_WORKER_COUNT";
 /**
  * Environment variable used only by the CLI-owned production build.
  *
@@ -34,6 +40,14 @@ export type AgentsServerBuildArtifacts = {
     readonly nodeModulesPath: string;
     readonly nextCliPath: string;
 };
+/**
+ * Runtime paths resolved for Agents Server commands before choosing build or dev execution.
+ *
+ * @private internal type of `ptbk agents-server`
+ */
+export type PreparedAgentsServerRuntime = AgentsServerBuildArtifacts & {
+    readonly isAppPathMaterialized: boolean;
+};
 /**
  * Input paths required to validate or update the cached Agents Server build.
  *
@@ -48,7 +62,15 @@ type AgentsServerBuildCacheOptions = {
  *
  * @private internal utility of `ptbk agents-server`
  */
-export declare function ensureAgentsServerBuild(options?: EnsureAgentsServerBuildOptions): Promise<AgentsServerBuildArtifacts>;
+export declare function ensureAgentsServerBuild(options?: EnsureAgentsServerBuildOptions): Promise<PreparedAgentsServerRuntime>;
+/**
+ * Resolves the runtime app and dependency paths shared by Agents Server start and dev commands.
+ *
+ * @private internal utility of `ptbk agents-server`
+ */
+export declare function prepareAgentsServerRuntime(options?: {
+    readonly appPath?: string;
+}): Promise<PreparedAgentsServerRuntime>;
 /**
  * Returns true when the production build marker and source fingerprint still match.
  *

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

@@ -6,6 +6,12 @@ import type { $side_effect } from '../../../utils/organization/$side_effect';
  * @private internal function of `promptbookCli`
  */
 export declare function $initializeAgentsServerStartCommand(program: Program): $side_effect;
+/**
+ * Initializes `agents-server dev` command for Promptbook CLI utilities.
+ *
+ * @private internal function of `promptbookCli`
+ */
+export declare function $initializeAgentsServerDevCommand(program: Program): $side_effect;
 /**
  * Initializes `agents-server build` command for Promptbook CLI utilities.
  *

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

@@ -1,6 +1,12 @@
 import type { ThinkingLevel } from '../coder/ThinkingLevel';
-import type { PromptRunnerAgentName } from '../common/promptRunnerCliOptions';
+import type { PromptRunnerHarnessName } from '../common/promptRunnerCliOptions';
 import type { number_port } from '../../../types/number_positive';
+/**
+ * Next runtime mode supported by the local Agents Server foreground launcher.
+ *
+ * @private internal type of `ptbk agents-server`
+ */
+export type AgentsServerNextRuntimeMode = 'start' | 'dev';
 /**
  * Options required to start the foreground Agents Server service group.
  *
@@ -8,11 +14,12 @@ import type { number_port } from '../../../types/number_positive';
  */
 export type StartAgentsServerOptions = {
     readonly port: number_port;
-    readonly agentName: PromptRunnerAgentName;
+    readonly agentName: PromptRunnerHarnessName;
     readonly model?: string;
     readonly noUi: boolean;
     readonly thinkingLevel?: ThinkingLevel;
     readonly allowCredits: boolean;
+    readonly nextRuntimeMode: AgentsServerNextRuntimeMode;
     readonly isBuildForced: boolean;
 };
 /**

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

@@ -3,7 +3,7 @@
  *
  * @private internal shared utility of `ptbk coder run`
  */
-export declare const THINKING_LEVEL_VALUES: readonly ["low", "medium", "high", "xhigh"];
+export declare const THINKING_LEVEL_VALUES: readonly ["low", "medium", "high", "xhigh", "max"];
 /**
  * Supported reasoning effort values for coding-agent runners with configurable thinking levels.
  *

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

@@ -0,0 +1,25 @@
+import type { InitializationStatus } from './boilerplateTemplates';
+/**
+ * Relative directory path for agents initialized by `ptbk coder init`.
+ *
+ * @private internal utility of `coder init` command
+ */
+export declare const CODER_AGENTS_DIRECTORY_PATH = "agents";
+/**
+ * Relative file path to the default developer agent initialized by `ptbk coder init`.
+ *
+ * @private internal utility of `coder init` command
+ */
+export declare const CODER_DEVELOPER_AGENT_FILE_PATH = "agents/developer.book";
+/**
+ * Source file path of the bundled developer agent inside the Promptbook repository.
+ *
+ * @private internal utility of `coder init` command
+ */
+export declare const DEFAULT_CODER_DEVELOPER_AGENT_SOURCE_FILE_PATH = "agents/default/developer.book";
+/**
+ * Ensures the default developer agent exists in the initialized project.
+ *
+ * @private function of `initializeCoderProjectConfiguration`
+ */
+export declare function ensureCoderDeveloperAgentFile(projectPath: string): Promise<InitializationStatus>;

package/esm/src/cli/cli-commands/coder/find-unwritten.d.ts

@@ -0,0 +1,10 @@
+import { Command as Program } from 'commander';
+import type { $side_effect } from '../../../utils/organization/$side_effect';
+/**
+ * Initializes `coder find-unwritten` command for Promptbook CLI utilities
+ *
+ * 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`
+ */
+export declare function $initializeCoderFindUnwrittenCommand(program: Program): $side_effect;