@promptbook/cli 0.112.0-115 → 0.112.0-118

package/src/book-3.0/CliAgent.ts

@@ -1,24 +1,32 @@
 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 { spaceTrim } from '../utils/organization/spaceTrim';
 import type { BookNodeAgentSourceOptions, ResolvedBookNodeAgentSource } from './BookNodeAgentSource';
 import { resolveBookNodeAgentSource } from './BookNodeAgentSource';
+import {
+    CLI_AGENT_HARNESS_NAMES,
+    CLI_AGENT_THINKING_LEVEL_VALUES,
+    PTBK_HARNESS_ENV,
+    PTBK_MODEL_ENV,
+    PTBK_THINKING_LEVEL_ENV,
+} from './cliAgentEnv';
 
 /**
  * CLI harness names supported by `ptbk agent exec`.
  *
  * @public exported from `@promptbook/node`
  */
-export type CliAgentHarness = 'openai-codex' | 'github-copilot' | 'cline' | 'claude-code' | 'opencode' | 'gemini';
+export type CliAgentHarness = (typeof CLI_AGENT_HARNESS_NAMES)[number];
 
 /**
  * Thinking levels supported by CLI coding harnesses.
  *
  * @public exported from `@promptbook/node`
  */
-export type CliAgentThinkingLevel = 'low' | 'medium' | 'high' | 'xhigh';
+export type CliAgentThinkingLevel = (typeof CLI_AGENT_THINKING_LEVEL_VALUES)[number];
 
 /**
  * Per-run CLI options exposed by `CliAgent`.
@@ -31,6 +39,7 @@ export type CliAgentRunOptions = {
     readonly allowCredits?: boolean;
     readonly context?: string;
     readonly harness?: CliAgentHarness;
+    readonly isVerbose?: boolean;
     readonly model?: string;
     readonly noUi?: boolean;
     readonly thinkingLevel?: CliAgentThinkingLevel;
@@ -41,22 +50,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 +60,13 @@ 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 harnesses and execution path as `ptbk agent exec`, running the runner
+ * in-process instead of spawning a separate CLI process.
  *
- * 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.
+ * When no `harness` is provided in the constructor or per-run options, `CliAgent` falls back
+ * to the `PTBK_HARNESS` environment variable, mirroring `ptbk agent exec` behavior.
  *
  * @public exported from `@promptbook/node`
  */
@@ -79,11 +76,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 +93,39 @@ 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,
-            isVerbose: false,
+        const harness = mergedOptions.harness ?? resolveCliAgentHarnessFromEnv();
+
+        if (!harness) {
+            throw new NotAllowed(
+                spaceTrim(`
+                    No harness specified for \`CliAgent\`. Pass \`harness\` in the constructor options or per-run options,
+                    or set the \`${PTBK_HARNESS_ENV}\` environment variable.
+
+                    Available harnesses: ${CLI_AGENT_HARNESS_NAMES.join(', ')}
+
+                    Example: \`PTBK_HARNESS=claude-code\`
+                `),
+            );
+        }
+
+        const result = await executeAgentChatTurn({
+            agentPath,
+            messages: [{ sender: 'USER', content: normalizedMessage }],
+            agentName: harness,
+            model: mergedOptions.model ?? process.env[PTBK_MODEL_ENV],
+            noUi: mergedOptions.noUi ?? DEFAULT_CLI_AGENT_IS_NO_UI,
+            thinkingLevel: mergedOptions.thinkingLevel ?? resolveCliAgentThinkingLevelFromEnv(),
+            allowCredits: mergedOptions.allowCredits ?? false,
+            isVerbose: mergedOptions.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 +146,7 @@ export class CliAgent {
 }
 
 /**
- * Merges constructor defaults with per-run CLI overrides.
+ * Merges constructor defaults with per-run overrides.
  *
  * @private internal utility of `CliAgent`
  */
@@ -146,6 +155,7 @@ function mergeCliAgentRunOptions(defaults: CliAgentRunOptions, overrides: CliAge
         allowCredits: overrides.allowCredits ?? defaults.allowCredits,
         context: overrides.context ?? defaults.context,
         harness: overrides.harness ?? defaults.harness,
+        isVerbose: overrides.isVerbose ?? defaults.isVerbose,
         model: overrides.model ?? defaults.model,
         noUi: overrides.noUi ?? defaults.noUi,
         thinkingLevel: overrides.thinkingLevel ?? defaults.thinkingLevel,
@@ -153,47 +163,53 @@ function mergeCliAgentRunOptions(defaults: CliAgentRunOptions, overrides: CliAge
 }
 
 /**
- * Builds CLI arguments for `ptbk agent exec`.
+ * Reads and validates the harness name from the `PTBK_HARNESS` environment variable.
  *
  * @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];
+function resolveCliAgentHarnessFromEnv(): CliAgentHarness | undefined {
+    const envValue = process.env[PTBK_HARNESS_ENV];
 
-    if (options.harness) {
-        argumentsList.push('--harness', options.harness);
+    if (!envValue) {
+        return undefined;
     }
 
-    if (options.model) {
-        argumentsList.push('--model', options.model);
-    }
+    if (!(CLI_AGENT_HARNESS_NAMES as ReadonlyArray<string>).includes(envValue)) {
+        throw new NotAllowed(
+            spaceTrim(`
+                Invalid value for \`${PTBK_HARNESS_ENV}\` environment variable: \`${envValue}\`
 
-    if (options.noUi) {
-        argumentsList.push('--no-ui');
+                Must be one of: ${CLI_AGENT_HARNESS_NAMES.join(', ')}
+            `),
+        );
     }
 
-    if (options.thinkingLevel) {
-        argumentsList.push('--thinking-level', options.thinkingLevel);
-    }
+    return envValue as CliAgentHarness;
+}
 
-    if (options.allowCredits) {
-        argumentsList.push('--allow-credits');
+/**
+ * Reads and validates the thinking level from the `PTBK_THINKING_LEVEL` environment variable.
+ *
+ * @private internal utility of `CliAgent`
+ */
+function resolveCliAgentThinkingLevelFromEnv(): CliAgentThinkingLevel | undefined {
+    const envValue = process.env[PTBK_THINKING_LEVEL_ENV];
+
+    if (!envValue) {
+        return undefined;
     }
 
-    if (options.context?.trim()) {
-        argumentsList.push('--context', options.context.trim());
+    if (!(CLI_AGENT_THINKING_LEVEL_VALUES as ReadonlyArray<string>).includes(envValue)) {
+        throw new NotAllowed(
+            spaceTrim(`
+                Invalid value for \`${PTBK_THINKING_LEVEL_ENV}\` environment variable: \`${envValue}\`
+
+                Must be one of: ${CLI_AGENT_THINKING_LEVEL_VALUES.join(', ')}
+            `),
+        );
     }
 
-    return argumentsList;
+    return envValue as CliAgentThinkingLevel;
 }
 
 /**
@@ -214,7 +230,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-3.0/cliAgentEnv.ts

@@ -0,0 +1,46 @@
+// Note: [💞] Ignore a discrepancy between file name and entity name
+
+/**
+ * All CLI harness names supported by `CliAgent` and `ptbk agent exec`.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export const CLI_AGENT_HARNESS_NAMES = [
+    'openai-codex',
+    'github-copilot',
+    'cline',
+    'claude-code',
+    'opencode',
+    'gemini',
+] as const;
+
+/**
+ * All supported thinking-level values for CLI coding-agent runners.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export const CLI_AGENT_THINKING_LEVEL_VALUES = ['low', 'medium', 'high', 'xhigh'] as const;
+
+/**
+ * Environment variable used as the default runner identifier when `--harness` is omitted or not set in `CliAgent`.
+ *
+ * Set this to one of the harness names (`openai-codex`, `github-copilot`, `cline`, `claude-code`, `opencode`, `gemini`)
+ * so that `CliAgent` and `ptbk agent exec` can run without an explicit `harness` option.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export const PTBK_HARNESS_ENV = 'PTBK_HARNESS';
+
+/**
+ * Environment variable used as the default runner model when `--model` is omitted or not set in `CliAgent`.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export const PTBK_MODEL_ENV = 'PTBK_MODEL';
+
+/**
+ * Environment variable used as the default thinking level when `--thinking-level` is omitted or not set in `CliAgent`.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export const PTBK_THINKING_LEVEL_ENV = 'PTBK_THINKING_LEVEL';

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';

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

@@ -1,7 +1,3 @@
-import type { string_book } from '../../book-2.0/agent-source/string_book';
-import { parseAgentSourceWithCommitments } from '../../book-2.0/agent-source/parseAgentSourceWithCommitments';
-import type { BookCommitment } from '../../commitments/_base/BookCommitment';
-
 /**
  * Regex source for absolute URL references inside TEAM/FROM/IMPORT commitments.
  *
@@ -28,12 +24,41 @@ const AGENT_REFERENCE_BRACED_PATTERN = '\\{[^{}\\r\\n]+\\}';
  *
  * @private function of BookEditorMonaco
  */
-const AGENT_REFERENCE_COMMITMENT_TYPES: ReadonlySet<BookCommitment> = new Set<BookCommitment>([
+const AGENT_REFERENCE_COMMITMENT_TYPES = ['FROM', 'IMPORT', 'IMPORTS', 'TEAM'] as const;
+
+/**
+ * Commitment types known to the browser editor tokenizer.
+ *
+ * @private function of BookEditorMonaco
+ */
+const BOOK_EDITOR_COMMITMENT_TYPES = [
+    'PERSONA',
+    'KNOWLEDGE',
+    'TASK',
+    'PROMPT',
+    'EXPECT',
+    'FORMAT',
+    'MODEL',
+    'SAMPLE',
     'FROM',
     'IMPORT',
     'IMPORTS',
     'TEAM',
-]);
+    'TODO',
+    'NOTE',
+    'NOTES',
+    'NONCE',
+] as const;
+
+/**
+ * Regex pattern to match horizontal lines.
+ *
+ * @private function of BookEditorMonaco
+ */
+const HORIZONTAL_LINE_PATTERN = /^[\s]*[-_*][\s]*[-_*][\s]*[-_*][\s]*[-_*]*[\s]*$/;
+
+const BOOK_EDITOR_COMMITMENT_LINE_REGEX = createCommitmentLineRegex(BOOK_EDITOR_COMMITMENT_TYPES);
+const AGENT_REFERENCE_COMMITMENT_LINE_REGEX = createCommitmentLineRegex(AGENT_REFERENCE_COMMITMENT_TYPES);
 
 /**
  * Range descriptor for one commitment block in source coordinates.
@@ -249,31 +274,74 @@ function collectAgentReferenceCommitmentLineRanges(
     content: string,
     sourceLines: ReadonlyArray<string>,
 ): Array<CommitmentLineRange> {
-    const parsed = parseAgentSourceWithCommitments(content as string_book);
     const ranges: Array<CommitmentLineRange> = [];
+    let activeRangeStartLineNumber: number | null = null;
+    let isInsideCodeBlock = false;
+    const startLineIndex = findBookBodyStartLineIndex(sourceLines);
+
+    for (let lineIndex = startLineIndex; lineIndex < sourceLines.length; lineIndex++) {
+        const line = sourceLines[lineIndex] || '';
+        const trimmedLine = line.trim();
 
-    for (let index = 0; index < parsed.commitments.length; index++) {
-        const commitment = parsed.commitments[index];
-        if (!commitment || !AGENT_REFERENCE_COMMITMENT_TYPES.has(commitment.type)) {
+        if (trimmedLine.startsWith('```')) {
+            isInsideCodeBlock = !isInsideCodeBlock;
             continue;
         }
 
-        const nextCommitmentStartLine = parsed.commitments[index + 1]?.lineNumber ?? sourceLines.length + 1;
-        const endLineNumber = Math.min(nextCommitmentStartLine - 1, sourceLines.length);
+        if (isInsideCodeBlock) {
+            continue;
+        }
 
-        if (commitment.lineNumber > endLineNumber) {
+        if (HORIZONTAL_LINE_PATTERN.test(line)) {
+            if (activeRangeStartLineNumber !== null) {
+                ranges.push({
+                    startLineNumber: activeRangeStartLineNumber,
+                    endLineNumber: lineIndex,
+                });
+                activeRangeStartLineNumber = null;
+            }
+            continue;
+        }
+
+        if (!BOOK_EDITOR_COMMITMENT_LINE_REGEX.test(trimmedLine)) {
             continue;
         }
 
+        if (activeRangeStartLineNumber !== null) {
+            ranges.push({
+                startLineNumber: activeRangeStartLineNumber,
+                endLineNumber: lineIndex,
+            });
+        }
+
+        activeRangeStartLineNumber = AGENT_REFERENCE_COMMITMENT_LINE_REGEX.test(trimmedLine) ? lineIndex + 1 : null;
+    }
+
+    if (activeRangeStartLineNumber !== null) {
         ranges.push({
-            startLineNumber: commitment.lineNumber,
-            endLineNumber,
+            startLineNumber: activeRangeStartLineNumber,
+            endLineNumber: sourceLines.length,
         });
     }
 
     return ranges;
 }
 
+function createCommitmentLineRegex(commitmentTypes: ReadonlyArray<string>): RegExp {
+    const commitmentPattern = [...commitmentTypes]
+        .sort((a, b) => b.length - a.length)
+        .map((type) => type.replace(/\s+/, '\\s+'))
+        .join('|');
+
+    return new RegExp(`^\\s*(${commitmentPattern})(?=\\s|$)`, 'i');
+}
+
+function findBookBodyStartLineIndex(sourceLines: ReadonlyArray<string>): number {
+    const titleLineIndex = sourceLines.findIndex((line) => line.trim().length > 0);
+
+    return titleLineIndex === -1 ? 0 : titleLineIndex + 1;
+}
+
 /**
  * Agent reference helpers for `BookEditorMonaco`.
  *

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

@@ -0,0 +1,11 @@
+/**
+ * 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 function createDeprecatedCommitmentDiagnostics(_agentSource?: string): [] {
+    return [];
+}