@promptbook/cli 0.113.0-1 → 0.113.0-10

package/src/book-3.0/CliAgent.ts

@@ -6,13 +6,7 @@ import { resolvePromptbookTemporaryPath } from '../utils/filesystem/promptbookTe
 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';
+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`.

package/src/book-3.0/LiteAgent.ts

@@ -8,22 +8,22 @@ import {
 import { readFile } from 'fs/promises';
 import { basename, resolve } from 'path';
 import { fileURLToPath } from 'url';
-import type { CreateAgentModelRequirementsOptions } from '../book-2.0/agent-source/CreateAgentModelRequirementsOptions';
-import { createAgentModelRequirements } from '../book-2.0/agent-source/createAgentModelRequirements';
 import type { AgentModelRequirements } from '../book-2.0/agent-source/AgentModelRequirements';
+import { createAgentModelRequirements } from '../book-2.0/agent-source/createAgentModelRequirements';
+import type { CreateAgentModelRequirementsOptions } from '../book-2.0/agent-source/CreateAgentModelRequirementsOptions';
 import { NotAllowed } from '../errors/NotAllowed';
 import type { ScriptExecutionTools } from '../execution/ScriptExecutionTools';
+import { computeOpenAiUsage } from '../llm-providers/openai/computeOpenAiUsage';
+import { OPENAI_MODELS } from '../llm-providers/openai/openai-models';
 import { OpenAiAgentKitExecutionToolsToolBuilder } from '../llm-providers/openai/OpenAiAgentKitExecutionToolsToolBuilder';
 import { OpenAiVectorStoreHandler } from '../llm-providers/openai/OpenAiVectorStoreHandler';
-import { OPENAI_MODELS } from '../llm-providers/openai/openai-models';
-import { computeOpenAiUsage } from '../llm-providers/openai/computeOpenAiUsage';
 import { $provideScriptingForNode } from '../scrapers/_common/register/$provideScriptingForNode';
 import type { string_knowledge_source_link } from '../types/string_knowledge_source_content';
 import type { string_markdown, string_markdown_text } from '../types/string_markdown';
 import type { string_model_name } from '../types/string_model_name';
 import type { string_title } from '../types/string_title';
-import type { TODO_any } from '../utils/organization/TODO_any';
 import { spaceTrim } from '../utils/organization/spaceTrim';
+import type { TODO_any } from '../utils/organization/TODO_any';
 import type { BookNodeAgentSourceOptions } from './BookNodeAgentSource';
 import { resolveBookNodeAgentSource } from './BookNodeAgentSource';
 

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

@@ -4,10 +4,7 @@ import { CSSProperties } from 'react';
 import type { AgentBasicInformation } from '../../../book-2.0/agent-source/AgentBasicInformation';
 import type { string_book } from '../../../book-2.0/agent-source/string_book';
 import type { string_css_class } from '../../../types/string_markdown';
-import {
-    resolveAgentAvatarFallbackUrl,
-    resolveAgentAvatarImageUrl,
-} from '../../../utils/agents/resolveAgentAvatarImageUrl';
+import { resolveAgentAvatarFallbackUrl, resolveAgentAvatarImageUrl } from '../../../utils/agents/resolveAgentAvatarImageUrl';
 import { classNames } from '../../_common/react-utils/classNames';
 import styles from './AvatarProfile.module.css';
 

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

@@ -2,11 +2,12 @@
 // <- Note: [👲] 'use client' is enforced by Next.js when building the https://book-components.ptbk.io/ but in ideal case,
 //          this would not be here because the `@promptbook/components` package should be React library independent of Next.js specifics
 
-import { type CSSProperties, useState } from 'react';
+import { useState, type CSSProperties } from 'react';
 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,7 +16,6 @@ import { countLines } from '../../utils/expectation-counters/countLines';
 import type { HoistedMenuItem } from '../_common/MenuHoisting/MenuHoistingContext';
 import { classNames } from '../_common/react-utils/classNames';
 import styles from './BookEditor.module.css';
-import { DEFAULT_IS_VERBOSE } from './BookEditorBrowserConfig';
 import { BookEditorMonaco } from './BookEditorMonaco';
 import type { BookEditorTheme } from './BookEditorTheme';
 import { BOOK_EDITOR_RENDER_THEME, resolveBookEditorRenderTheme } from './BookEditorTheme';

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

@@ -1,7 +1,8 @@
-import { BOOK_LANGUAGE_VERSION, PROMPTBOOK_ENGINE_VERSION } from '../../version';
+import { PUBLIC_AGENTS_SERVERS } from '../../../servers';
+import { CLAIM, IS_COST_PREVENTED, NAME } from '../../config';
 import { $detectRuntimeEnvironment } from '../../utils/environment/$detectRuntimeEnvironment';
 import type { AboutPromptbookInformationOptions } from '../../utils/misc/aboutPromptbookInformation';
-import { CLAIM, IS_COST_PREVENTED, NAME, PUBLIC_AGENTS_SERVERS } from './BookEditorBrowserConfig';
+import { BOOK_LANGUAGE_VERSION, PROMPTBOOK_ENGINE_VERSION } from '../../version';
 import styles from './BookEditor.module.css';
 
 /**

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

@@ -16,8 +16,8 @@ import { Dropdown } from '../_common/Dropdown/Dropdown';
 import type { HoistedMenuItem } from '../_common/MenuHoisting/MenuHoistingContext';
 import { useMenuHoisting } from '../_common/MenuHoisting/MenuHoistingContext';
 import { Modal } from '../_common/Modal/Modal';
-import { BookEditorAboutPromptbookInformation } from './BookEditorAboutPromptbookInformation';
 import styles from './BookEditor.module.css';
+import { BookEditorAboutPromptbookInformation } from './BookEditorAboutPromptbookInformation';
 
 /**
  * Props for book editor actionbar.

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

@@ -5,13 +5,14 @@
 import { useMonaco } from '@monaco-editor/react';
 import { useId } from 'react';
 import type { string_book } from '../../book-2.0/agent-source/string_book';
+import { SaveIcon } from '../icons/SaveIcon';
 import { MonacoEditorWithShadowDom } from '../_common/MonacoEditorWithShadowDom';
 import { classNames } from '../_common/react-utils/classNames';
-import { SaveIcon } from '../icons/SaveIcon';
 import type { BookEditorProps } from './BookEditor';
 import styles from './BookEditor.module.css';
 import { BookEditorActionbar } from './BookEditorActionbar';
 import { BookEditorMonacoConstants } from './BookEditorMonacoConstants';
+import { BookEditorMonacoUploadPanel } from './BookEditorMonacoUploadPanel';
 import { BOOK_EDITOR_RENDER_THEME, resolveBookEditorRenderTheme } from './BookEditorTheme';
 import { createDeprecatedCommitmentDiagnostics } from './createDeprecatedCommitmentDiagnostics.browser';
 import { useBookEditorMonacoDecorations } from './useBookEditorMonacoDecorations';
@@ -21,7 +22,6 @@ import { useBookEditorMonacoLanguage } from './useBookEditorMonacoLanguage';
 import { useBookEditorMonacoLifecycle } from './useBookEditorMonacoLifecycle';
 import { useBookEditorMonacoStyles } from './useBookEditorMonacoStyles';
 import { useBookEditorMonacoUploads } from './useBookEditorMonacoUploads';
-import { BookEditorMonacoUploadPanel } from './BookEditorMonacoUploadPanel';
 
 /**
  * Matches characters that are unsafe in CSS identifiers and HTML IDs.

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

@@ -1,6 +1,6 @@
 import styles from './BookEditor.module.css';
 import { BookEditorMonacoFormatting } from './BookEditorMonacoFormatting';
-import type { UploadItem, UploadStats } from './useBookEditorMonacoUploads';
+import type { UploadItem, UploadStats } from './useBookEditorMonacoUploads/bookEditorMonacoUploadTypes';
 
 /**
  * Map of upload status labels.

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

@@ -1,6 +1,6 @@
 import type { editor, Position } from 'monaco-editor';
 import { useEffect } from 'react';
-import { PROMPTBOOK_SYNTAX_COLORS } from './BookEditorBrowserConfig';
+import { PROMPTBOOK_SYNTAX_COLORS } from '../../config';
 import { BookEditorMonacoConstants } from './BookEditorMonacoConstants';
 import { BookEditorMonacoTokenization } from './BookEditorMonacoTokenization';
 import type { BookEditorTheme } from './BookEditorTheme';

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

@@ -1,5 +1,5 @@
 import { useEffect } from 'react';
-import { PROMPTBOOK_SYNTAX_COLORS } from './BookEditorBrowserConfig';
+import { PROMPTBOOK_SYNTAX_COLORS } from '../../config';
 import type { BookEditorTheme } from './BookEditorTheme';
 
 /**

package/src/book-components/BookEditor/useBookEditorMonacoUploads/bookEditorMonacoUploadTypes.ts

@@ -0,0 +1,147 @@
+import type { MutableRefObject } from 'react';
+import type { Promisable } from 'type-fest';
+
+// Note: [💞] This module groups the upload types shared across the `useBookEditorMonacoUploads` internals behind a
+//       descriptive name, so the file name intentionally does not match a single exported entity.
+
+/**
+ * Type describing upload status.
+ *
+ * @private function of BookEditorMonaco
+ */
+type UploadStatus = 'queued' | 'uploading' | 'paused' | 'completed' | 'failed';
+
+/**
+ * Type describing upload item.
+ */
+export type UploadItem = {
+    readonly id: string;
+    readonly fileName: string;
+    readonly fileSize: number;
+    readonly status: UploadStatus;
+    readonly progress: number;
+    readonly loadedBytes: number;
+    readonly totalBytes: number;
+    readonly startedAt: number | null;
+    readonly completedAt: number | null;
+    readonly errorMessage?: string;
+};
+
+/**
+ * Type describing upload progress update.
+ *
+ * @private function of BookEditorMonaco
+ */
+export type UploadProgressUpdate = {
+    readonly progress: number;
+    readonly loadedBytes: number;
+    readonly totalBytes: number;
+};
+
+/**
+ * Type describing placeholder entry inserted into Monaco while the file uploads.
+ *
+ * @private function of BookEditorMonaco
+ */
+export type UploadPlaceholderEntry = {
+    readonly id: string;
+    readonly file: File;
+    readonly placeholder: string;
+};
+
+/**
+ * Type describing upload stats.
+ */
+export type UploadStats = {
+    readonly totalFiles: number;
+    readonly queuedFiles: number;
+    readonly uploadingFiles: number;
+    readonly pausedFiles: number;
+    readonly failedFiles: number;
+    readonly completedFiles: number;
+    readonly totalBytes: number;
+    readonly uploadedBytes: number;
+    readonly progress: number;
+    readonly elapsedMs: number;
+    readonly speedBytesPerSecond: number;
+};
+
+/**
+ * Type describing book editor monaco upload progress callback.
+ *
+ * @private function of BookEditorMonaco
+ */
+export type BookEditorMonacoUploadProgressCallback = (
+    progress: number,
+    stats?: {
+        loadedBytes: number;
+        totalBytes: number;
+    },
+) => void;
+
+/**
+ * Options for book editor monaco upload.
+ *
+ * @private function of BookEditorMonaco
+ */
+export type BookEditorMonacoUploadOptions = {
+    readonly onProgress?: BookEditorMonacoUploadProgressCallback;
+    readonly abortSignal?: AbortSignal;
+};
+
+/**
+ * Type describing book editor monaco on file upload.
+ *
+ * @private function of BookEditorMonaco
+ */
+export type BookEditorMonacoOnFileUpload = (
+    file: File,
+    options?: BookEditorMonacoUploadOptions | BookEditorMonacoUploadProgressCallback,
+) => Promisable<string>;
+
+/**
+ * Setter-like updater used by upload state helpers.
+ *
+ * @private function of BookEditorMonaco
+ */
+export type SetUploadItems = (updater: (items: UploadItem[]) => UploadItem[]) => void;
+
+/**
+ * Single-upload updater used by upload state helpers.
+ *
+ * @private function of BookEditorMonaco
+ */
+export type UpdateUploadItem = (uploadId: string, createNextUploadItem: (uploadItem: UploadItem) => UploadItem) => void;
+
+/**
+ * Mutable upload items reference shared across upload helpers.
+ *
+ * @private function of BookEditorMonaco
+ */
+export type UploadItemsRef = MutableRefObject<UploadItem[]>;
+
+/**
+ * Mutable upload file registry reference shared across upload helpers.
+ *
+ * @private function of BookEditorMonaco
+ */
+export type UploadFilesRef = MutableRefObject<Map<string, File>>;
+
+/**
+ * Mutable Monaco decoration registry reference shared across upload helpers.
+ *
+ * @private function of BookEditorMonaco
+ */
+export type UploadDecorationIdsRef = MutableRefObject<Map<string, string>>;
+
+/**
+ * Type describing the callback used to enqueue debounced progress updates.
+ *
+ * @private function of BookEditorMonaco
+ */
+export type QueueProgressUpdate = (
+    uploadId: string,
+    progress: number,
+    loadedBytes: number,
+    totalBytes: number,
+) => void;

package/src/book-components/BookEditor/useBookEditorMonacoUploads/clearScheduledTimer.ts

@@ -0,0 +1,10 @@
+/**
+ * Clears an optional scheduled timer when it exists.
+ *
+ * @private function of BookEditorMonaco
+ */
+export function clearScheduledTimer(timerId: number | null): void {
+    if (timerId !== null) {
+        clearTimeout(timerId);
+    }
+}

package/src/book-components/BookEditor/useBookEditorMonacoUploads/enqueueFilesForUpload.ts

@@ -0,0 +1,209 @@
+import type { editor } from 'monaco-editor';
+import { BookEditable } from '../../../book-2.0/agent-source/BookEditable';
+import type { string_book } from '../../../book-2.0/agent-source/string_book';
+import { BookEditorMonacoFormatting } from '../BookEditorMonacoFormatting';
+import type { SetUploadItems, UploadItem, UploadPlaceholderEntry } from './bookEditorMonacoUploadTypes';
+
+/**
+ * Type describing monaco editor.
+ *
+ * @private function of BookEditorMonaco
+ */
+type MonacoEditor = typeof import('monaco-editor');
+
+/**
+ * Type describing how upload placeholders should be inserted into the Monaco model.
+ *
+ * @private function of BookEditorMonaco
+ */
+type UploadPlaceholderInsertPlan = {
+    readonly insertLine: number;
+    readonly insertColumn: number;
+    readonly insertStartOffset: number;
+    readonly prefixLength: number;
+    readonly textToInsert: string;
+};
+
+/**
+ * Generates deterministic ids for uploads that support server preloading.
+ *
+ * @private function of BookEditorMonaco
+ */
+const createUploadId = (() => {
+    let sequence = 0;
+    return () => {
+        if (typeof crypto !== 'undefined' && 'randomUUID' in crypto) {
+            return crypto.randomUUID();
+        }
+
+        sequence += 1;
+        return `upload-${Date.now()}-${sequence}`;
+    };
+})();
+
+/**
+ * Creates placeholder entries for files that are about to be uploaded.
+ *
+ * @private function of BookEditorMonaco
+ */
+function createUploadPlaceholderEntries(files: ReadonlyArray<File>): Array<UploadPlaceholderEntry> {
+    return files.map((file) => ({
+        id: createUploadId(),
+        file,
+        placeholder: BookEditorMonacoFormatting.getUploadPlaceholderText(file.name),
+    }));
+}
+
+/**
+ * Resolves the Monaco insertion point for new upload placeholders.
+ *
+ * @private function of BookEditorMonaco
+ */
+function createUploadPlaceholderInsertPlan(
+    model: editor.ITextModel,
+    monaco: MonacoEditor,
+    placeholders: ReadonlyArray<UploadPlaceholderEntry>,
+): UploadPlaceholderInsertPlan {
+    const currentValue = model.getValue() as string_book;
+    const bookEditable = new BookEditable(currentValue);
+    const closedLineIndex = bookEditable.findLastCommitmentLineIndex('CLOSED');
+    const isInsertingBeforeClosed = closedLineIndex !== null;
+    const insertLine = isInsertingBeforeClosed ? closedLineIndex + 1 : model.getLineCount();
+    const insertColumn = isInsertingBeforeClosed ? 1 : model.getLineMaxColumn(insertLine);
+    const shouldAddLeadingLineBreak = !isInsertingBeforeClosed && Boolean(currentValue);
+    const prefix = shouldAddLeadingLineBreak ? '\n' : '';
+    const placeholderBlock = placeholders.map(({ placeholder }) => `${placeholder}\n`).join('');
+    const textToInsert = `${prefix}${placeholderBlock}`;
+    const insertStartOffset = model.getOffsetAt(new monaco.Position(insertLine, insertColumn));
+
+    return {
+        insertLine,
+        insertColumn,
+        insertStartOffset,
+        prefixLength: prefix.length,
+        textToInsert,
+    };
+}
+
+/**
+ * Creates Monaco decorations tracking the placeholder ranges for later replacement.
+ *
+ * @private function of BookEditorMonaco
+ */
+function createUploadPlaceholderDecorations(
+    model: editor.ITextModel,
+    monaco: MonacoEditor,
+    placeholders: ReadonlyArray<UploadPlaceholderEntry>,
+    insertStartOffset: number,
+    prefixLength: number,
+): Array<editor.IModelDeltaDecoration> {
+    let runningOffset = prefixLength;
+
+    return placeholders.map((placeholder) => {
+        const startOffset = insertStartOffset + runningOffset;
+        const endOffset = startOffset + placeholder.placeholder.length;
+        const startPosition = model.getPositionAt(startOffset);
+        const endPosition = model.getPositionAt(endOffset);
+
+        runningOffset += placeholder.placeholder.length + 1;
+
+        return {
+            range: new monaco.Range(
+                startPosition.lineNumber,
+                startPosition.column,
+                endPosition.lineNumber,
+                endPosition.column,
+            ),
+            options: {
+                stickiness: monaco.editor.TrackedRangeStickiness.NeverGrowsWhenTypingAtEdges,
+            },
+        };
+    });
+}
+
+/**
+ * Creates queued upload items matching newly inserted placeholders.
+ *
+ * @private function of BookEditorMonaco
+ */
+function createQueuedUploadItems(placeholders: ReadonlyArray<UploadPlaceholderEntry>): Array<UploadItem> {
+    return placeholders.map(({ id, file }) => ({
+        id,
+        fileName: file.name,
+        fileSize: file.size,
+        status: 'queued',
+        progress: 0,
+        loadedBytes: 0,
+        totalBytes: file.size,
+        startedAt: null,
+        completedAt: null,
+    }));
+}
+
+/**
+ * Props for Monaco placeholder insertion.
+ *
+ * @private function of BookEditorMonaco
+ */
+type EnqueueFilesForUploadProps = {
+    readonly editor: editor.IStandaloneCodeEditor | null;
+    readonly monaco: MonacoEditor | null;
+    readonly registerUploadPlaceholderResources: (
+        placeholders: ReadonlyArray<UploadPlaceholderEntry>,
+        decorationIds: ReadonlyArray<string>,
+    ) => void;
+    readonly setUploadItems: SetUploadItems;
+};
+
+/**
+ * Inserts Monaco placeholders and queues matching upload items.
+ *
+ * @private function of BookEditorMonaco
+ */
+export function enqueueFilesForUpload({
+    editor,
+    monaco,
+    registerUploadPlaceholderResources,
+    setUploadItems,
+}: EnqueueFilesForUploadProps): (files: ReadonlyArray<File>) => boolean {
+    return (files) => {
+        if (!editor || !monaco) {
+            return false;
+        }
+
+        const model = editor.getModel();
+        if (!model) {
+            return false;
+        }
+
+        const placeholders = createUploadPlaceholderEntries(files);
+        const insertPlan = createUploadPlaceholderInsertPlan(model, monaco, placeholders);
+
+        editor.executeEdits('upload-placeholders', [
+            {
+                range: new monaco.Range(
+                    insertPlan.insertLine,
+                    insertPlan.insertColumn,
+                    insertPlan.insertLine,
+                    insertPlan.insertColumn,
+                ),
+                text: insertPlan.textToInsert,
+                forceMoveMarkers: true,
+            },
+        ]);
+
+        const placeholderDecorations = createUploadPlaceholderDecorations(
+            model,
+            monaco,
+            placeholders,
+            insertPlan.insertStartOffset,
+            insertPlan.prefixLength,
+        );
+        const decorationIds = editor.deltaDecorations([], placeholderDecorations);
+
+        registerUploadPlaceholderResources(placeholders, decorationIds);
+        setUploadItems((currentUploadItems) => [...currentUploadItems, ...createQueuedUploadItems(placeholders)]);
+
+        return true;
+    };
+}