@promptbook/cli 0.112.0-115 → 0.112.0-117

package/esm/src/_packages/components.index.d.ts

@@ -12,6 +12,7 @@ import type { BookEditorUploadProgressCallback } from '../book-components/BookEd
 import type { BookEditorUploadOptions } from '../book-components/BookEditor/BookEditor';
 import type { BookEditorProps } from '../book-components/BookEditor/BookEditor';
 import { BookEditor } from '../book-components/BookEditor/BookEditor';
+import { BookEditorForClient } from '../book-components/BookEditor/BookEditorForClient';
 import { AgentChat } from '../book-components/Chat/AgentChat/AgentChat';
 import type { AgentChatProps } from '../book-components/Chat/AgentChat/AgentChatProps';
 import { Chat } from '../book-components/Chat/Chat/Chat';
@@ -95,6 +96,7 @@ export type { BookEditorUploadProgressCallback };
 export type { BookEditorUploadOptions };
 export type { BookEditorProps };
 export { BookEditor };
+export { BookEditorForClient };
 export { AgentChat };
 export type { AgentChatProps };
 export { Chat };

package/esm/src/_packages/node.index.d.ts

@@ -1,4 +1,9 @@
 import { BOOK_LANGUAGE_VERSION, PROMPTBOOK_ENGINE_VERSION } from '../version';
+import { AGENT_BOOK_FILE_PATH } from '../book-3.0/agentFolderPaths';
+import { AGENT_MESSAGES_DIRECTORY_PATH } from '../book-3.0/agentFolderPaths';
+import { AGENT_QUEUED_MESSAGES_DIRECTORY_PATH } from '../book-3.0/agentFolderPaths';
+import { AGENT_FINISHED_MESSAGES_DIRECTORY_PATH } from '../book-3.0/agentFolderPaths';
+import { AGENT_FAILED_MESSAGES_DIRECTORY_PATH } from '../book-3.0/agentFolderPaths';
 import type { BookNodeAgentSource } from '../book-3.0/BookNodeAgentSource';
 import type { BookNodeAgentSourceOptions } from '../book-3.0/BookNodeAgentSource';
 import type { CliAgentHarness } from '../book-3.0/CliAgent';
@@ -22,6 +27,11 @@ import { FileCacheStorage } from '../storage/file-cache-storage/FileCacheStorage
 import { $execCommand } from '../utils/execCommand/$execCommand';
 import { $execCommands } from '../utils/execCommand/$execCommands';
 export { BOOK_LANGUAGE_VERSION, PROMPTBOOK_ENGINE_VERSION };
+export { AGENT_BOOK_FILE_PATH };
+export { AGENT_MESSAGES_DIRECTORY_PATH };
+export { AGENT_QUEUED_MESSAGES_DIRECTORY_PATH };
+export { AGENT_FINISHED_MESSAGES_DIRECTORY_PATH };
+export { AGENT_FAILED_MESSAGES_DIRECTORY_PATH };
 export type { BookNodeAgentSource };
 export type { BookNodeAgentSourceOptions };
 export type { CliAgentHarness };

package/esm/src/book-3.0/CliAgent.d.ts

@@ -31,19 +31,12 @@ export type CliAgentRunOptions = {
  *
  * @public exported from `@promptbook/node`
  */
-export type CliAgentOptions = BookNodeAgentSourceOptions & CliAgentRunOptions & {
-    /**
-     * Executable used for the wrapper command.
-     *
-     * @default ptbk
-     */
-    readonly command?: string;
-};
+export type CliAgentOptions = BookNodeAgentSourceOptions & CliAgentRunOptions;
 /**
- * Lightweight JavaScript wrapper around `ptbk agent exec`.
+ * Lightweight JavaScript wrapper around the Promptbook agent execution pipeline.
  *
- * It uses the same CLI harnesses as Promptbook's agent command, making it the most faithful
- * way to run a local Book agent from Node.js when you want the CLI execution flow.
+ * It uses the same harnesses and execution path as `ptbk agent exec`, running the runner
+ * in-process instead of spawning a separate CLI process.
  *
  * @public exported from `@promptbook/node`
  */
@@ -52,15 +45,15 @@ export declare class CliAgent {
     private temporaryAgentPath;
     constructor(options: CliAgentOptions);
     /**
-     * Runs one non-interactive agent turn through `ptbk agent exec`.
+     * Runs one non-interactive agent turn through the selected harness.
      *
      * @param message - User message sent to the agent.
-     * @param options - Optional per-run CLI overrides.
-     * @returns Raw stdout emitted by the CLI command.
+     * @param options - Optional per-run overrides.
+     * @returns Final agent answer.
      */
     run(message: string, options?: CliAgentRunOptions): Promise<string>;
     /**
-     * Resolves the agent path passed to the CLI, materializing one temporary `.book` file when needed.
+     * Resolves the agent path passed to the runner, materializing one temporary `.book` file when needed.
      *
      * @private internal utility of `CliAgent`
      */

package/esm/src/book-3.0/agentFolderPaths.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Relative path to the local agent source used by the agent folder convention.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export declare const AGENT_BOOK_FILE_PATH = "agent.book";
+/**
+ * Relative path to the message queue root used by the agent folder convention.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export declare const AGENT_MESSAGES_DIRECTORY_PATH = "messages";
+/**
+ * Relative path to queued user messages consumed by the agent runner.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export declare const AGENT_QUEUED_MESSAGES_DIRECTORY_PATH: string;
+/**
+ * Relative path to answered messages written by the agent runner.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export declare const AGENT_FINISHED_MESSAGES_DIRECTORY_PATH: string;
+/**
+ * Relative path to messages that the agent runner stopped retrying.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export declare const AGENT_FAILED_MESSAGES_DIRECTORY_PATH: string;

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

@@ -0,0 +1,2 @@
+export { NAME, CLAIM, PROMPTBOOK_LEGAL_ENTITY, IS_COST_PREVENTED, DEFAULT_IS_VERBOSE, DEFAULT_MAX_CONCURRENT_UPLOADS, PROMPTBOOK_SYNTAX_COLORS, } from '../../config';
+export { PUBLIC_AGENTS_SERVERS } from '../../../servers';

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

@@ -0,0 +1,7 @@
+import { BookEditorProps } from './BookEditor';
+/**
+ * Renders a book editor
+ *
+ * @public exported from `@promptbook/components`
+ */
+export declare function BookEditorForClient(props: BookEditorProps): import("react/jsx-runtime").JSX.Element;

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/cli/cli-commands/agent-folder/agentProjectPaths.d.ts

@@ -1,39 +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 messages that the agent runner stopped retrying.
- *
- * @private internal utility of `ptbk agent-folder`
- */
-export declare const AGENT_FAILED_MESSAGES_DIRECTORY_PATH: string;
 /**
  * Relative path to generated local agent documentation initialized by `ptbk agent-folder init`.
  *

package/esm/src/scrapers/website/utils/createShowdownConverter.d.ts

@@ -1,7 +1,7 @@
-import { Converter as ShowdownConverter } from 'showdown';
+import showdown from 'showdown';
 /**
  * Create a new showdown converter instance
  *
  * @private utility of `WebsiteScraper`
  */
-export declare function createShowdownConverter(): ShowdownConverter;
+export declare function createShowdownConverter(): showdown.Converter;

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.112.0-114`).
+ * It follows semantic versioning (e.g., `0.112.0-116`).
  *
  * @generated
  */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@promptbook/cli",
-    "version": "0.112.0-115",
+    "version": "0.112.0-117",
     "description": "Promptbook: Create persistent AI agents that turn your company's scattered knowledge into action",
     "private": false,
     "sideEffects": false,

package/src/_packages/components.index.ts

@@ -17,6 +17,7 @@ import type { BookEditorUploadProgressCallback } from '../book-components/BookEd
 import type { BookEditorUploadOptions } from '../book-components/BookEditor/BookEditor';
 import type { BookEditorProps } from '../book-components/BookEditor/BookEditor';
 import { BookEditor } from '../book-components/BookEditor/BookEditor';
+import { BookEditorForClient } from '../book-components/BookEditor/BookEditorForClient';
 import { AgentChat } from '../book-components/Chat/AgentChat/AgentChat';
 import type { AgentChatProps } from '../book-components/Chat/AgentChat/AgentChatProps';
 import { Chat } from '../book-components/Chat/Chat/Chat';
@@ -106,6 +107,7 @@ export type { BookEditorUploadProgressCallback };
 export type { BookEditorUploadOptions };
 export type { BookEditorProps };
 export { BookEditor };
+export { BookEditorForClient };
 export { AgentChat };
 export type { AgentChatProps };
 export { Chat };

package/src/_packages/node.index.ts

@@ -2,6 +2,11 @@
 // `@promptbook/node`
 
 import { BOOK_LANGUAGE_VERSION, PROMPTBOOK_ENGINE_VERSION } from '../version';
+import { AGENT_BOOK_FILE_PATH } from '../book-3.0/agentFolderPaths';
+import { AGENT_MESSAGES_DIRECTORY_PATH } from '../book-3.0/agentFolderPaths';
+import { AGENT_QUEUED_MESSAGES_DIRECTORY_PATH } from '../book-3.0/agentFolderPaths';
+import { AGENT_FINISHED_MESSAGES_DIRECTORY_PATH } from '../book-3.0/agentFolderPaths';
+import { AGENT_FAILED_MESSAGES_DIRECTORY_PATH } from '../book-3.0/agentFolderPaths';
 import type { BookNodeAgentSource } from '../book-3.0/BookNodeAgentSource';
 import type { BookNodeAgentSourceOptions } from '../book-3.0/BookNodeAgentSource';
 import type { CliAgentHarness } from '../book-3.0/CliAgent';
@@ -31,6 +36,11 @@ export { BOOK_LANGUAGE_VERSION, PROMPTBOOK_ENGINE_VERSION };
 
 
 // Note: Entities of the `@promptbook/node`
+export { AGENT_BOOK_FILE_PATH };
+export { AGENT_MESSAGES_DIRECTORY_PATH };
+export { AGENT_QUEUED_MESSAGES_DIRECTORY_PATH };
+export { AGENT_FINISHED_MESSAGES_DIRECTORY_PATH };
+export { AGENT_FAILED_MESSAGES_DIRECTORY_PATH };
 export type { BookNodeAgentSource };
 export type { BookNodeAgentSourceOptions };
 export type { CliAgentHarness };

package/src/book-3.0/CliAgent.ts

@@ -1,8 +1,8 @@
 import { mkdir, writeFile } from 'fs/promises';
 import { dirname } from 'path';
+import { executeAgentChatTurn } from '../../scripts/run-agent-chat/executeAgentChatTurn';
 import { NotAllowed } from '../errors/NotAllowed';
 import { resolvePromptbookTemporaryPath } from '../utils/filesystem/promptbookTemporaryPath';
-import { $execCommand } from '../utils/execCommand/$execCommand';
 import type { BookNodeAgentSourceOptions, ResolvedBookNodeAgentSource } from './BookNodeAgentSource';
 import { resolveBookNodeAgentSource } from './BookNodeAgentSource';
 
@@ -41,22 +41,7 @@ export type CliAgentRunOptions = {
  *
  * @public exported from `@promptbook/node`
  */
-export type CliAgentOptions = BookNodeAgentSourceOptions &
-    CliAgentRunOptions & {
-        /**
-         * Executable used for the wrapper command.
-         *
-         * @default ptbk
-         */
-        readonly command?: string;
-    };
-
-/**
- * Default executable used by `CliAgent`.
- *
- * @private internal constant of `CliAgent`
- */
-const DEFAULT_CLI_AGENT_COMMAND = 'ptbk';
+export type CliAgentOptions = BookNodeAgentSourceOptions & CliAgentRunOptions;
 
 /**
  * Default non-interactive mode used by `CliAgent`.
@@ -66,10 +51,10 @@ const DEFAULT_CLI_AGENT_COMMAND = 'ptbk';
 const DEFAULT_CLI_AGENT_IS_NO_UI = true;
 
 /**
- * Lightweight JavaScript wrapper around `ptbk agent exec`.
+ * Lightweight JavaScript wrapper around the Promptbook agent execution pipeline.
  *
- * It uses the same CLI harnesses as Promptbook's agent command, making it the most faithful
- * way to run a local Book agent from Node.js when you want the CLI execution flow.
+ * It uses the same harnesses and execution path as `ptbk agent exec`, running the runner
+ * in-process instead of spawning a separate CLI process.
  *
  * @public exported from `@promptbook/node`
  */
@@ -79,11 +64,11 @@ export class CliAgent {
     public constructor(private readonly options: CliAgentOptions) {}
 
     /**
-     * Runs one non-interactive agent turn through `ptbk agent exec`.
+     * Runs one non-interactive agent turn through the selected harness.
      *
      * @param message - User message sent to the agent.
-     * @param options - Optional per-run CLI overrides.
-     * @returns Raw stdout emitted by the CLI command.
+     * @param options - Optional per-run overrides.
+     * @returns Final agent answer.
      */
     public async run(message: string, options: CliAgentRunOptions = {}): Promise<string> {
         const normalizedMessage = message.trim();
@@ -96,27 +81,24 @@ export class CliAgent {
         const agentPath = await this.resolveExecutableAgentPath(resolvedSource);
         const mergedOptions = mergeCliAgentRunOptions(this.options, options);
 
-        return $execCommand({
-            command: this.options.command || DEFAULT_CLI_AGENT_COMMAND,
-            args: createCliAgentExecArguments({
-                agentPath,
-                allowCredits: mergedOptions.allowCredits ?? false,
-                context: mergedOptions.context,
-                harness: mergedOptions.harness,
-                message: normalizedMessage,
-                model: mergedOptions.model,
-                noUi: mergedOptions.noUi ?? DEFAULT_CLI_AGENT_IS_NO_UI,
-                thinkingLevel: mergedOptions.thinkingLevel,
-            }),
-            cwd: resolvedSource.currentWorkingDirectory,
-            crashOnError: true,
-            timeout: Infinity,
+        const result = await executeAgentChatTurn({
+            agentPath,
+            messages: [{ sender: 'USER', content: normalizedMessage }],
+            agentName: mergedOptions.harness,
+            model: mergedOptions.model,
+            noUi: mergedOptions.noUi ?? DEFAULT_CLI_AGENT_IS_NO_UI,
+            thinkingLevel: mergedOptions.thinkingLevel,
+            allowCredits: mergedOptions.allowCredits ?? false,
             isVerbose: false,
+            context: mergedOptions.context,
+            currentWorkingDirectory: resolvedSource.currentWorkingDirectory,
         });
+
+        return result.answer;
     }
 
     /**
-     * Resolves the agent path passed to the CLI, materializing one temporary `.book` file when needed.
+     * Resolves the agent path passed to the runner, materializing one temporary `.book` file when needed.
      *
      * @private internal utility of `CliAgent`
      */
@@ -137,7 +119,7 @@ export class CliAgent {
 }
 
 /**
- * Merges constructor defaults with per-run CLI overrides.
+ * Merges constructor defaults with per-run overrides.
  *
  * @private internal utility of `CliAgent`
  */
@@ -152,50 +134,6 @@ function mergeCliAgentRunOptions(defaults: CliAgentRunOptions, overrides: CliAge
     };
 }
 
-/**
- * Builds CLI arguments for `ptbk agent exec`.
- *
- * @private internal utility of `CliAgent`
- */
-function createCliAgentExecArguments(options: {
-    readonly agentPath: string;
-    readonly allowCredits: boolean;
-    readonly context?: string;
-    readonly harness?: CliAgentHarness;
-    readonly message: string;
-    readonly model?: string;
-    readonly noUi: boolean;
-    readonly thinkingLevel?: CliAgentThinkingLevel;
-}): Array<string> {
-    const argumentsList = ['agent', 'exec', '--agent', options.agentPath, '--message', options.message];
-
-    if (options.harness) {
-        argumentsList.push('--harness', options.harness);
-    }
-
-    if (options.model) {
-        argumentsList.push('--model', options.model);
-    }
-
-    if (options.noUi) {
-        argumentsList.push('--no-ui');
-    }
-
-    if (options.thinkingLevel) {
-        argumentsList.push('--thinking-level', options.thinkingLevel);
-    }
-
-    if (options.allowCredits) {
-        argumentsList.push('--allow-credits');
-    }
-
-    if (options.context?.trim()) {
-        argumentsList.push('--context', options.context.trim());
-    }
-
-    return argumentsList;
-}
-
 /**
  * Creates the stable temporary path used when `CliAgent` is initialized from in-memory Book source.
  *
@@ -214,7 +152,7 @@ function createCliAgentTemporaryBookPath(resolvedSource: ResolvedBookNodeAgentSo
 }
 
 /**
- * Keeps in-memory Book source readable when persisted for the CLI wrapper.
+ * Keeps in-memory Book source readable when persisted for the runner.
  *
  * @private internal utility of `CliAgent`
  */

package/src/book-3.0/agentFolderPaths.ts

@@ -0,0 +1,38 @@
+import { join } from 'path';
+
+// Note: [💞] Ignore a discrepancy between file name and entity name
+
+/**
+ * Relative path to the local agent source used by the agent folder convention.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export const AGENT_BOOK_FILE_PATH = 'agent.book';
+
+/**
+ * Relative path to the message queue root used by the agent folder convention.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export const AGENT_MESSAGES_DIRECTORY_PATH = 'messages';
+
+/**
+ * Relative path to queued user messages consumed by the agent runner.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export const AGENT_QUEUED_MESSAGES_DIRECTORY_PATH = join(AGENT_MESSAGES_DIRECTORY_PATH, 'queued');
+
+/**
+ * Relative path to answered messages written by the agent runner.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export const AGENT_FINISHED_MESSAGES_DIRECTORY_PATH = join(AGENT_MESSAGES_DIRECTORY_PATH, 'finished');
+
+/**
+ * Relative path to messages that the agent runner stopped retrying.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export const AGENT_FAILED_MESSAGES_DIRECTORY_PATH = join(AGENT_MESSAGES_DIRECTORY_PATH, 'failed');

package/src/book-components/BookEditor/BookEditor.tsx

@@ -7,7 +7,6 @@ import { createPortal } from 'react-dom';
 import type { Promisable } from 'type-fest';
 import type { string_book } from '../../book-2.0/agent-source/string_book';
 import { DEFAULT_BOOK } from '../../book-2.0/agent-source/string_book';
-import { DEFAULT_IS_VERBOSE } from '../../config';
 import type { number_percent } from '../../types/number_percent';
 import type { number_positive } from '../../types/number_positive';
 import type { string_knowledge_source_content } from '../../types/string_knowledge_source_content';
@@ -15,6 +14,7 @@ import type { string_css_value } from '../../types/string_markdown';
 import { countLines } from '../../utils/expectation-counters/countLines';
 import type { HoistedMenuItem } from '../_common/MenuHoisting/MenuHoistingContext';
 import { classNames } from '../_common/react-utils/classNames';
+import { DEFAULT_IS_VERBOSE } from './BookEditorBrowserConfig';
 import styles from './BookEditor.module.css';
 import { BookEditorMonaco } from './BookEditorMonaco';
 import type { BookEditorTheme } from './BookEditorTheme';

package/src/book-components/BookEditor/BookEditorAboutPromptbookInformation.tsx

@@ -1,9 +1,7 @@
-import { PUBLIC_AGENTS_SERVERS } from '../../../servers';
-import { CLAIM, IS_COST_PREVENTED, NAME } from '../../config';
 import { BOOK_LANGUAGE_VERSION, PROMPTBOOK_ENGINE_VERSION } from '../../version';
 import { $detectRuntimeEnvironment } from '../../utils/environment/$detectRuntimeEnvironment';
 import type { AboutPromptbookInformationOptions } from '../../utils/misc/aboutPromptbookInformation';
-import { valueToString } from '../../utils/parameters/valueToString';
+import { CLAIM, IS_COST_PREVENTED, NAME, PUBLIC_AGENTS_SERVERS } from './BookEditorBrowserConfig';
 import styles from './BookEditor.module.css';
 
 /**
@@ -63,7 +61,7 @@ export function BookEditorAboutPromptbookInformation(props: AboutPromptbookInfor
                     <ul>
                         {Object.entries(runtimeEnvironmentInfo).map(([key, value]) => (
                             <li key={key}>
-                                <strong>{key}:</strong> {valueToString(value)}
+                                <strong>{key}:</strong> {String(value)}
                             </li>
                         ))}
                     </ul>

package/src/book-components/BookEditor/BookEditorActionbar.tsx

@@ -6,7 +6,6 @@ import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 // Note: Do not import from `../../package.json` because it would be included in the bundle
 // TODO: [🧠] Is there a better way to get the version?
 import { DEFAULT_BOOK, validateBook } from '../../book-2.0/agent-source/string_book';
-import { $induceBookDownload } from '../../utils/files/$induceBookDownload';
 import { AboutIcon } from '../icons/AboutIcon';
 import { AttachmentIcon } from '../icons/AttachmentIcon';
 import { CameraIcon } from '../icons/CameraIcon';
@@ -37,6 +36,37 @@ type BookEditorActionbarProps = {
     hoistedMenuItems?: ReadonlyArray<HoistedMenuItem>;
 };
 
+function induceBookDownloadInBrowser(book: string): void {
+    const filename = `${normalizeBookDownloadName(extractBookTitle(book) || 'AI Avatar')}.book`;
+    const objectUrl = URL.createObjectURL(new Blob([book], { type: 'application/json' }));
+    const link = window.document.createElement('a');
+
+    link.href = objectUrl;
+    link.download = filename;
+    link.click();
+    URL.revokeObjectURL(objectUrl);
+}
+
+function extractBookTitle(book: string): string | null {
+    return (
+        book
+            .split(/\r?\n/)
+            .map((line) => line.trim())
+            .find(Boolean) || null
+    );
+}
+
+function normalizeBookDownloadName(value: string): string {
+    return (
+        value
+            .normalize('NFD')
+            .replace(/[\u0300-\u036f]/g, '')
+            .replace(/[^\dA-Za-z]+/g, '-')
+            .replace(/^-+|-+$/g, '')
+            .toLowerCase() || 'ai-avatar'
+    );
+}
+
 /**
  * Handles book editor actionbar.
  *
@@ -67,7 +97,7 @@ export function BookEditorActionbar(props: BookEditorActionbarProps) {
 
     const handleDownload = useCallback(() => {
         const book = validateBook(valueRef.current || DEFAULT_BOOK);
-        /* not await */ $induceBookDownload(book);
+        induceBookDownloadInBrowser(book);
     }, []);
 
     const actions = useMemo(() => {

package/src/book-components/BookEditor/BookEditorBrowserConfig.ts

@@ -0,0 +1,11 @@
+// Re-export browser-compatible constants from canonical sources to avoid duplicate entity names
+export {
+    NAME,
+    CLAIM,
+    PROMPTBOOK_LEGAL_ENTITY,
+    IS_COST_PREVENTED,
+    DEFAULT_IS_VERBOSE,
+    DEFAULT_MAX_CONCURRENT_UPLOADS,
+    PROMPTBOOK_SYNTAX_COLORS,
+} from '../../config';
+export { PUBLIC_AGENTS_SERVERS } from '../../../servers';

package/src/book-components/BookEditor/BookEditorForClient.tsx

@@ -0,0 +1,33 @@
+import { useEffect, useState } from 'react';
+import { BookEditorProps } from './BookEditor';
+
+type BookEditorComponent = typeof import('./BookEditor').BookEditor;
+
+/**
+ * Renders a book editor
+ *
+ * @public exported from `@promptbook/components`
+ */
+export function BookEditorForClient(props: BookEditorProps) {
+    const [BookEditorComponent, setBookEditorComponent] = useState<BookEditorComponent | null>(null);
+
+    useEffect(() => {
+        let isCancelled = false;
+
+        void import('./BookEditor').then(({ BookEditor }) => {
+            if (!isCancelled) {
+                setBookEditorComponent(() => BookEditor);
+            }
+        });
+
+        return () => {
+            isCancelled = true;
+        };
+    }, []);
+
+    if (!BookEditorComponent) {
+        return <div style={{ minHeight: 260 }} />;
+    }
+
+    return <BookEditorComponent {...props} />;
+}

package/src/book-components/BookEditor/BookEditorMonaco.tsx

@@ -13,7 +13,7 @@ import styles from './BookEditor.module.css';
 import { BookEditorActionbar } from './BookEditorActionbar';
 import { BookEditorMonacoConstants } from './BookEditorMonacoConstants';
 import { BOOK_EDITOR_RENDER_THEME, resolveBookEditorRenderTheme } from './BookEditorTheme';
-import { createDeprecatedCommitmentDiagnostics } from './createDeprecatedCommitmentDiagnostics';
+import { createDeprecatedCommitmentDiagnostics } from './createDeprecatedCommitmentDiagnostics.browser';
 import { useBookEditorMonacoDecorations } from './useBookEditorMonacoDecorations';
 import { useBookEditorMonacoDiagnostics } from './useBookEditorMonacoDiagnostics';
 import { useBookEditorMonacoInteractions } from './useBookEditorMonacoInteractions';