@promptbook/javascript 0.107.0-0 → 0.110.0-0

package/esm/index.es.js

@@ -18,7 +18,7 @@ const BOOK_LANGUAGE_VERSION = '2.0.0';
  * @generated
  * @see https://github.com/webgptorg/promptbook
  */
-const PROMPTBOOK_ENGINE_VERSION = '0.107.0-0';
+const PROMPTBOOK_ENGINE_VERSION = '0.110.0-0';
 /**
  * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
  * Note: [💞] Ignore a discrepancy between file name and entity name

package/esm/typings/src/_packages/markdown-utils.index.d.ts

@@ -21,6 +21,7 @@ import { humanizeAiText } from '../utils/markdown/humanizeAiText';
 import { humanizeAiTextEllipsis } from '../utils/markdown/humanizeAiTextEllipsis';
 import { humanizeAiTextEmdashed } from '../utils/markdown/humanizeAiTextEmdashed';
 import { humanizeAiTextQuotes } from '../utils/markdown/humanizeAiTextQuotes';
+import { humanizeAiTextSources } from '../utils/markdown/humanizeAiTextSources';
 import { humanizeAiTextWhitespace } from '../utils/markdown/humanizeAiTextWhitespace';
 import type { MarkdownSection } from '../utils/markdown/parseMarkdownSection';
 import { parseMarkdownSection } from '../utils/markdown/parseMarkdownSection';
@@ -54,6 +55,7 @@ export { humanizeAiText };
 export { humanizeAiTextEllipsis };
 export { humanizeAiTextEmdashed };
 export { humanizeAiTextQuotes };
+export { humanizeAiTextSources };
 export { humanizeAiTextWhitespace };
 export type { MarkdownSection };
 export { parseMarkdownSection };

package/esm/typings/src/_packages/types.index.d.ts

@@ -20,6 +20,7 @@ import type { ChatEffect } from '../book-components/Chat/effects/types/ChatEffec
 import type { ChatEffectConfig } from '../book-components/Chat/effects/types/ChatEffectConfig';
 import type { ChatEffectsSystemProps } from '../book-components/Chat/effects/types/ChatEffectsSystemProps';
 import type { ChatEffectType } from '../book-components/Chat/effects/types/ChatEffectType';
+import type { ChatActionsOverlapResult } from '../book-components/Chat/hooks/useChatActionsOverlap';
 import type { ChatAutoScrollConfig } from '../book-components/Chat/hooks/useChatAutoScroll';
 import type { SendMessageToLlmChatFunction } from '../book-components/Chat/hooks/useSendMessageToLlmChat';
 import type { FriendlyErrorMessage } from '../book-components/Chat/LlmChat/FriendlyErrorMessage';
@@ -230,6 +231,9 @@ import type { SpeechRecognitionState } from '../types/SpeechRecognition';
 import type { SpeechRecognitionEvent } from '../types/SpeechRecognition';
 import type { TaskType } from '../types/TaskType';
 import type { ToolCall } from '../types/ToolCall';
+import type { SelfLearningCommitmentTypeCounts } from '../types/ToolCall';
+import type { SelfLearningTeacherSummary } from '../types/ToolCall';
+import type { SelfLearningToolCallResult } from '../types/ToolCall';
 import type { ASSISTANT_PREPARATION_TOOL_CALL_NAME } from '../types/ToolCall';
 import type { isAssistantPreparationToolCall } from '../types/ToolCall';
 import type { string_char_emoji } from '../types/typeAliasEmoji';
@@ -419,6 +423,7 @@ export type { ChatEffect };
 export type { ChatEffectConfig };
 export type { ChatEffectsSystemProps };
 export type { ChatEffectType };
+export type { ChatActionsOverlapResult };
 export type { ChatAutoScrollConfig };
 export type { SendMessageToLlmChatFunction };
 export type { FriendlyErrorMessage };
@@ -629,6 +634,9 @@ export type { SpeechRecognitionState };
 export type { SpeechRecognitionEvent };
 export type { TaskType };
 export type { ToolCall };
+export type { SelfLearningCommitmentTypeCounts };
+export type { SelfLearningTeacherSummary };
+export type { SelfLearningToolCallResult };
 export type { ASSISTANT_PREPARATION_TOOL_CALL_NAME };
 export type { isAssistantPreparationToolCall };
 export type { string_char_emoji };

package/esm/typings/src/book-components/AvatarProfile/AvatarProfile/AvatarProfile.d.ts

@@ -13,7 +13,7 @@ export type AvatarProfileProps = {
      */
     readonly agent: AgentBasicInformation;
     /**
-     * The source of the agent, which will be displayed in the BookEditor.
+     * The source of the agent, used to enable profile actions in the UI.
      */
     readonly agentSource?: string_book;
     /**

package/esm/typings/src/book-components/Chat/Chat/ChatActionsBar.d.ts

@@ -0,0 +1,32 @@
+import { type MouseEvent, type MutableRefObject, type ReactNode } from 'react';
+import type { Promisable } from 'type-fest';
+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 { ChatSoundSystem } from './ChatProps';
+/**
+ * Props for the Chat actions toolbar.
+ *
+ * @private component of `<Chat/>`
+ */
+export type ChatActionsBarProps = {
+    actionsRef: MutableRefObject<HTMLDivElement | null>;
+    actionsContainer?: HTMLElement | null;
+    messages: ReadonlyArray<ChatMessage>;
+    participants: ReadonlyArray<ChatParticipant>;
+    title: string;
+    onReset?: () => Promisable<void>;
+    onUseTemplate?: () => void;
+    extraActions?: ReactNode;
+    saveFormats?: Array<string_chat_format_name>;
+    isSaveButtonEnabled: boolean;
+    shouldFadeActions: boolean;
+    onButtonClick: (handler?: (event: MouseEvent<HTMLButtonElement>) => void) => (event: MouseEvent<HTMLButtonElement>) => void;
+    soundSystem?: ChatSoundSystem;
+};
+/**
+ * Renders the action buttons row for Chat.
+ *
+ * @private component of `<Chat/>`
+ */
+export declare function ChatActionsBar(props: ChatActionsBarProps): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,21 @@
+import type { ChatParticipant } from '../types/ChatParticipant';
+import type { ParsedCitation } from '../utils/parseCitationsFromContent';
+import type { ChatSoundSystem } from './ChatProps';
+/**
+ * Props for the citation preview modal.
+ *
+ * @private component of `<Chat/>`
+ */
+export type ChatCitationModalProps = {
+    isOpen: boolean;
+    citation: ParsedCitation | null;
+    participants: ReadonlyArray<ChatParticipant>;
+    soundSystem?: ChatSoundSystem;
+    onClose: () => void;
+};
+/**
+ * Modal that previews a citation source or excerpt.
+ *
+ * @private component of `<Chat/>`
+ */
+export declare function ChatCitationModal(props: ChatCitationModalProps): import("react/jsx-runtime").JSX.Element | null;

package/esm/typings/src/book-components/Chat/Chat/ChatInputArea.d.ts

@@ -0,0 +1,48 @@
+import { type MouseEvent } from 'react';
+import { Color } from '../../../utils/color/Color';
+import type { WithTake } from '../../../utils/take/interfaces/ITakeChain';
+import type { ChatParticipant } from '../types/ChatParticipant';
+import type { ChatProps, ChatSoundSystem } from './ChatProps';
+/**
+ * Wrapper for consistent button-click sound handling.
+ *
+ * @private component of `<Chat/>`
+ */
+export type ChatInputButtonClickHandler = (handler?: (event: MouseEvent<HTMLButtonElement>) => void) => (event: MouseEvent<HTMLButtonElement>) => void;
+/**
+ * Internal representation of an uploaded file in the chat input.
+ *
+ * @private component of `<Chat/>`
+ */
+export type ChatInputUploadedFile = {
+    id: string;
+    file: File;
+    content: string;
+};
+/**
+ * Props for the chat input area.
+ *
+ * @private component of `<Chat/>`
+ */
+export type ChatInputAreaProps = {
+    onMessage?: ChatProps['onMessage'];
+    onChange?: ChatProps['onChange'];
+    onFileUpload?: ChatProps['onFileUpload'];
+    speechRecognition?: ChatProps['speechRecognition'];
+    defaultMessage?: string;
+    placeholderMessageContent?: string;
+    isFocusedOnLoad?: boolean;
+    isMobile: boolean;
+    isVoiceCalling?: boolean;
+    participants: ReadonlyArray<ChatParticipant>;
+    buttonColor: WithTake<Color>;
+    soundSystem?: ChatSoundSystem;
+    onButtonClick: ChatInputButtonClickHandler;
+    chatInputClassName?: string;
+};
+/**
+ * Renders the chat input area with text, file upload, and voice controls.
+ *
+ * @private component of `<Chat/>`
+ */
+export declare function ChatInputArea(props: ChatInputAreaProps): import("react/jsx-runtime").JSX.Element | null;

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

@@ -0,0 +1,40 @@
+import type { UIEvent } from 'react';
+import type { Promisable } from 'type-fest';
+import type { id } from '../../../types/typeAliases';
+import type { ChatMessage } from '../types/ChatMessage';
+import type { ChatParticipant } from '../types/ChatParticipant';
+import type { ParsedCitation } from '../utils/parseCitationsFromContent';
+import type { ChatProps } from './ChatProps';
+/**
+ * Props for the Chat message list container.
+ *
+ * @private component of `<Chat/>`
+ */
+export type ChatMessageListProps = {
+    messages: ReadonlyArray<ChatMessage>;
+    participants: ReadonlyArray<ChatParticipant>;
+    expandedMessageId: id | null;
+    messageRatings: Map<id, number>;
+    setExpandedMessageId: (value: id | null) => void;
+    handleRating: (message: ChatMessage, rating: number) => void;
+    mode: 'LIGHT' | 'DARK';
+    isCopyButtonEnabled?: boolean;
+    isFeedbackEnabled?: boolean;
+    onCopy?: () => void;
+    onMessage?: (messageContent: string) => Promisable<void>;
+    onCreateAgent?: (bookContent: string) => void;
+    toolTitles?: Record<string, string>;
+    teammates?: ChatProps['teammates'];
+    onToolCallClick?: (toolCall: NonNullable<ChatMessage['toolCalls']>[number]) => void;
+    onCitationClick?: (citation: ParsedCitation) => void;
+    setChatMessagesElement: (element: HTMLDivElement | null) => void;
+    onScroll: (event: UIEvent<HTMLDivElement>) => void;
+    chatMessagesClassName?: string;
+    hasActions: boolean;
+};
+/**
+ * Renders the list of chat messages.
+ *
+ * @private component of `<Chat/>`
+ */
+export declare function ChatMessageList(props: ChatMessageListProps): import("react/jsx-runtime").JSX.Element;

package/esm/typings/src/book-components/Chat/Chat/ChatRatingModal.d.ts

@@ -0,0 +1,30 @@
+import type { id } from '../../../types/typeAliases';
+import type { ChatMessage } from '../types/ChatMessage';
+/**
+ * Props for the rating modal used in Chat.
+ *
+ * @private component of `<Chat/>`
+ */
+export type ChatRatingModalProps = {
+    isOpen: boolean;
+    selectedMessage: ChatMessage | null;
+    postprocessedMessages: ReadonlyArray<ChatMessage>;
+    messages: ReadonlyArray<ChatMessage>;
+    hoveredRating: number;
+    messageRatings: Map<id, number>;
+    textRating: string;
+    mode: 'LIGHT' | 'DARK';
+    isMobile: boolean;
+    onClose: () => void;
+    setHoveredRating: (value: number) => void;
+    setMessageRatings: (value: Map<id, number> | ((previous: Map<id, number>) => Map<id, number>)) => void;
+    setSelectedMessage: (value: ChatMessage | null) => void;
+    setTextRating: (value: string) => void;
+    submitRating: () => Promise<void>;
+};
+/**
+ * Modal that captures per-message rating feedback.
+ *
+ * @private component of `<Chat/>`
+ */
+export declare function ChatRatingModal(props: ChatRatingModalProps): import("react/jsx-runtime").JSX.Element | null;

package/esm/typings/src/book-components/Chat/Chat/ChatSelfLearningSummary.d.ts

@@ -0,0 +1,24 @@
+import type { TODO_any } from '../../../utils/organization/TODO_any';
+import type { ChatMessage } from '../types/ChatMessage';
+/**
+ * Resolved summary data for self-learning tool calls.
+ *
+ * @private component of `<Chat/>`
+ */
+export type SelfLearningSummaryData = {
+    commitments: Array<string>;
+    commitmentsText: string;
+    commitmentsLineCount: number;
+    hasTeacherCommitments: boolean;
+    samplesLabel: string | null;
+    updatedLabel: string | null;
+};
+/**
+ * Builds UI-ready data for the self-learning modal from a tool call.
+ *
+ * @private component of `<Chat/>`
+ */
+export declare function buildSelfLearningSummary(toolCall: NonNullable<ChatMessage['toolCalls']>[number], resultRaw: TODO_any): SelfLearningSummaryData;
+/**
+ * Note: [💞] Ignore a discrepancy between file name and entity name, BUT maybe rename to `buildSelfLearningSummary`
+ */

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

@@ -0,0 +1,23 @@
+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';
+/**
+ * Props for the tool call details modal.
+ *
+ * @private component of `<Chat/>`
+ */
+export type ChatToolCallModalProps = {
+    isOpen: boolean;
+    toolCall: NonNullable<ChatMessage['toolCalls']>[number] | null;
+    onClose: () => void;
+    toolTitles?: Record<string, string>;
+    agentParticipant?: ChatParticipant;
+    buttonColor: WithTake<Color>;
+};
+/**
+ * Modal that renders rich tool call details for chat chiplets.
+ *
+ * @private component of `<Chat/>`
+ */
+export declare function ChatToolCallModal(props: ChatToolCallModalProps): import("react/jsx-runtime").JSX.Element | null;

package/esm/typings/src/book-components/Chat/Chat/ChatToolCallModalComponents.d.ts

@@ -0,0 +1,39 @@
+import { type ReactNode } from 'react';
+/**
+ * Props for a team modal header profile badge.
+ *
+ * @private component of `<Chat/>`
+ */
+export type TeamHeaderProfileProps = {
+    label: string;
+    avatarSrc?: string | null;
+    href?: string;
+    fallbackColor?: string;
+};
+/**
+ * Renders a profile badge used in the TEAM modal header.
+ *
+ * @private component of `<Chat/>`
+ */
+export declare function TeamHeaderProfile({ label, avatarSrc, href, fallbackColor }: TeamHeaderProfileProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Props for a self-learning modal avatar.
+ *
+ * @private component of `<Chat/>`
+ */
+export type SelfLearningAvatarProps = {
+    label: string;
+    avatarSrc?: string | null;
+    fallbackColor?: string;
+    className?: string;
+    children?: ReactNode;
+};
+/**
+ * Renders an avatar badge for the self-learning modal header.
+ *
+ * @private component of `<Chat/>`
+ */
+export declare function SelfLearningAvatar({ label, avatarSrc, fallbackColor, className, children, }: SelfLearningAvatarProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Note: [💞] Ignore a discrepancy between file name and entity name, BUT maybe split to multiple files
+ */

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

@@ -0,0 +1,55 @@
+import { type MutableRefObject, type UIEvent } from 'react';
+/**
+ * Configuration for tracking action button overlap and scroll state.
+ *
+ * @private component of `<Chat/>`
+ */
+export type ChatActionsOverlapConfig = {
+    /**
+     * Provides the chat messages container ref for auto-scroll integration.
+     */
+    chatMessagesRef: (element: HTMLDivElement | null) => void;
+    /**
+     * Scroll handler from the auto-scroll hook.
+     */
+    handleScroll: (event: UIEvent<HTMLDivElement>) => void;
+    /**
+     * Selector used to locate message elements for overlap checks.
+     */
+    messageSelector: string;
+    /**
+     * Messages used to trigger overlap recalculation.
+     */
+    messages: ReadonlyArray<unknown>;
+};
+/**
+ * Result returned by the action overlap tracking hook.
+ */
+export type ChatActionsOverlapResult = {
+    /**
+     * Ref for the actions toolbar element.
+     */
+    actionsRef: MutableRefObject<HTMLDivElement | null>;
+    /**
+     * Combined ref setter for chat messages (auto-scroll + overlap tracking).
+     */
+    setChatMessagesElement: (element: HTMLDivElement | null) => void;
+    /**
+     * Scroll handler that updates both auto-scroll and overlap state.
+     */
+    handleChatScroll: (event: UIEvent<HTMLDivElement>) => void;
+    /**
+     * Whether the actions toolbar is currently being scrolled.
+     */
+    isActionsScrolling: boolean;
+    /**
+     * Whether the actions toolbar overlaps the first visible message.
+     */
+    isActionsOverlapping: boolean;
+};
+/**
+ * Tracks action toolbar overlap while coordinating with chat auto-scroll.
+ *
+ * @private component of `<Chat/>`
+ */
+export declare function useChatActionsOverlap(config: ChatActionsOverlapConfig): ChatActionsOverlapResult;

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

@@ -0,0 +1,67 @@
+import type { Promisable } from 'type-fest';
+import type { id } from '../../../types/typeAliases';
+import type { ChatMessage } from '../types/ChatMessage';
+/**
+ * Input parameters for the chat rating hook.
+ *
+ * @private component of `<Chat/>`
+ */
+export type UseChatRatingsOptions = {
+    /**
+     * Messages in the chat thread.
+     */
+    messages: ReadonlyArray<ChatMessage>;
+    /**
+     * Optional feedback handler passed to Chat.
+     */
+    onFeedback?: (feedback: {
+        message: ChatMessage;
+        rating: number;
+        textRating: string;
+        chatThread: string;
+        expectedAnswer: string | null;
+        url: string;
+    }) => Promisable<void>;
+    /**
+     * Whether the UI should apply mobile-specific behavior.
+     */
+    isMobile: boolean;
+};
+/**
+ * Rating state tracked for the chat UI.
+ *
+ * @private component of `<Chat/>`
+ */
+export type ChatRatingsState = {
+    ratingModalOpen: boolean;
+    selectedMessage: ChatMessage | null;
+    messageRatings: Map<id, number>;
+    textRating: string;
+    hoveredRating: number;
+    expandedMessageId: id | null;
+    ratingConfirmation: string | null;
+};
+/**
+ * Rating actions for the chat UI.
+ *
+ * @private component of `<Chat/>`
+ */
+export type ChatRatingsActions = {
+    setRatingModalOpen: (value: boolean) => void;
+    setSelectedMessage: (value: ChatMessage | null) => void;
+    setMessageRatings: (value: Map<id, number> | ((previous: Map<id, number>) => Map<id, number>)) => void;
+    setTextRating: (value: string) => void;
+    setHoveredRating: (value: number) => void;
+    setExpandedMessageId: (value: id | null) => void;
+    handleRating: (message: ChatMessage, newRating: number) => void;
+    submitRating: () => Promise<void>;
+};
+/**
+ * Hook that centralizes rating state and handlers for Chat.
+ *
+ * @private component of `<Chat/>`
+ */
+export declare function useChatRatings(options: UseChatRatingsOptions): {
+    state: ChatRatingsState;
+    actions: ChatRatingsActions;
+};

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

@@ -15,6 +15,12 @@ export type ToolCallChipletInfo = {
      * Agent data for team tools (if applicable)
      */
     agentData?: AgentChipData;
+    /**
+     * Whether to wrap the chip text in brackets when rendering.
+     *
+     * @default true
+     */
+    wrapInBrackets?: boolean;
 };
 /**
  * Technical to user-friendly tool names and emojis
@@ -24,6 +30,7 @@ export type ToolCallChipletInfo = {
 export declare const TOOL_TITLES: Record<string, {
     title: string;
     emoji: string;
+    wrapInBrackets?: boolean;
 }>;
 /**
  * Gets the chiplet information including text and agent data (for team tools).

package/esm/typings/src/book-components/icons/TeacherIcon.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Props for the TeacherIcon component.
+ */
+type TeacherIconProps = {
+    size?: number;
+    color?: string;
+};
+/**
+ * Renders a teacher/graduation cap icon.
+ *
+ * @param props - SVG properties augmented with an optional `size`
+ * @private internal subcomponent used by various components
+ */
+export declare function TeacherIcon({ size, color }: TeacherIconProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/esm/typings/src/collection/agent-collection/constructors/agent-collection-in-supabase/AgentCollectionInSupabase.d.ts

@@ -4,6 +4,19 @@ import type { string_book } from '../../../../book-2.0/agent-source/string_book'
 import type { string_agent_name, string_agent_permanent_id } from '../../../../types/typeAliases';
 import { AgentCollectionInSupabaseOptions } from './AgentCollectionInSupabaseOptions';
 import type { AgentsDatabaseSchema } from './AgentsDatabaseSchema';
+/**
+ * Options for creating a new agent entry.
+ */
+type CreateAgentOptions = {
+    /**
+     * Folder identifier to assign the new agent to.
+     */
+    readonly folderId?: number | null;
+    /**
+     * Sort order for the agent within its parent folder.
+     */
+    readonly sortOrder?: number;
+};
 /**
  * Agent collection stored in a Supabase table.
  *
@@ -39,8 +52,11 @@ export declare class AgentCollectionInSupabase {
      * Creates a new agent in the collection
      *
      * Note: You can set 'PARENT' in the agent source to inherit from another agent in the collection.
+     *
+     * @param agentSource - Source content of the agent.
+     * @param options - Optional folder placement and ordering data.
      */
-    createAgent(agentSource: string_book): Promise<AgentBasicInformation & Required<Pick<AgentBasicInformation, 'permanentId'>>>;
+    createAgent(agentSource: string_book, options?: CreateAgentOptions): Promise<AgentBasicInformation & Required<Pick<AgentBasicInformation, 'permanentId'>>>;
     /**
      * Updates an existing agent in the collection
      */
@@ -80,6 +96,7 @@ export declare class AgentCollectionInSupabase {
      */
     private getTableName;
 }
+export {};
 /**
  * TODO: [🐱‍🚀] Implement it here correctly and update JSDoc comments here, and on interface + other implementations
  * TODO: Write unit test

package/esm/typings/src/collection/agent-collection/constructors/agent-collection-in-supabase/AgentsDatabaseSchema.d.ts

@@ -11,9 +11,15 @@
  * NOTE: This file intentionally omits all other tables (`Metadata`, `ChatHistory`, `ChatFeedback`, `User`, `LlmCache`, etc.)
  *       and any extra schemas (e.g. `graphql_public`) to remain a strict subset.
  */
+/**
+ * Supabase-style JSON helper type.
+ */
 export type Json = string | number | boolean | null | {
     [key: string]: Json | undefined;
 } | Json[];
+/**
+ * Subset of the Agents Server database schema containing only Agent and AgentHistory tables.
+ */
 export type AgentsDatabaseSchema = {
     public: {
         Tables: {
@@ -31,13 +37,15 @@ export type AgentsDatabaseSchema = {
                     usage: Json | null;
                     preparedModelRequirements: Json | null;
                     preparedExternals: Json | null;
+                    folderId: number | null;
+                    sortOrder: number;
                     deletedAt: string | null;
                     visibility: 'PUBLIC' | 'PRIVATE';
                 };
                 Insert: {
                     id?: number;
                     agentName: string;
-                    createdAt: string;
+                    createdAt?: string;
                     updatedAt?: string | null;
                     permanentId?: string | null;
                     agentHash: string;
@@ -47,6 +55,8 @@ export type AgentsDatabaseSchema = {
                     usage?: Json | null;
                     preparedModelRequirements?: Json | null;
                     preparedExternals?: Json | null;
+                    folderId?: number | null;
+                    sortOrder?: number;
                     deletedAt?: string | null;
                     visibility?: 'PUBLIC' | 'PRIVATE';
                 };
@@ -63,10 +73,19 @@ export type AgentsDatabaseSchema = {
                     usage?: Json | null;
                     preparedModelRequirements?: Json | null;
                     preparedExternals?: Json | null;
+                    folderId?: number | null;
+                    sortOrder?: number;
                     deletedAt?: string | null;
                     visibility?: 'PUBLIC' | 'PRIVATE';
                 };
-                Relationships: [];
+                Relationships: [
+                    {
+                        foreignKeyName: 'Agent_folderId_fkey';
+                        columns: ['folderId'];
+                        referencedRelation: 'AgentFolder';
+                        referencedColumns: ['id'];
+                    }
+                ];
             };
             AgentHistory: {
                 Row: {
@@ -81,7 +100,7 @@ export type AgentsDatabaseSchema = {
                 };
                 Insert: {
                     id?: number;
-                    createdAt: string;
+                    createdAt?: string;
                     agentName: string;
                     permanentId: string;
                     agentHash: string;
@@ -115,7 +134,13 @@ export type AgentsDatabaseSchema = {
         CompositeTypes: Record<string, never>;
     };
 };
+/**
+ * Public schema reference for helper types.
+ */
 type PublicSchema = AgentsDatabaseSchema[Extract<keyof AgentsDatabaseSchema, 'public'>];
+/**
+ * Helper type to extract table row types from the public schema.
+ */
 export type Tables<PublicTableNameOrOptions extends keyof (PublicSchema['Tables'] & PublicSchema['Views']) | {
     schema: keyof AgentsDatabaseSchema;
 }, TableName extends PublicTableNameOrOptions extends {
@@ -127,6 +152,9 @@ export type Tables<PublicTableNameOrOptions extends keyof (PublicSchema['Tables'
 } ? R : never : PublicTableNameOrOptions extends keyof (PublicSchema['Tables'] & PublicSchema['Views']) ? (PublicSchema['Tables'] & PublicSchema['Views'])[PublicTableNameOrOptions] extends {
     Row: infer R;
 } ? R : never : never;
+/**
+ * Helper type to extract table insert types from the public schema.
+ */
 export type TablesInsert<PublicTableNameOrOptions extends keyof PublicSchema['Tables'] | {
     schema: keyof AgentsDatabaseSchema;
 }, TableName extends PublicTableNameOrOptions extends {
@@ -138,6 +166,9 @@ export type TablesInsert<PublicTableNameOrOptions extends keyof PublicSchema['Ta
 } ? I : never : PublicTableNameOrOptions extends keyof PublicSchema['Tables'] ? PublicSchema['Tables'][PublicTableNameOrOptions] extends {
     Insert: infer I;
 } ? I : never : never;
+/**
+ * Helper type to extract table update types from the public schema.
+ */
 export type TablesUpdate<PublicTableNameOrOptions extends keyof PublicSchema['Tables'] | {
     schema: keyof AgentsDatabaseSchema;
 }, TableName extends PublicTableNameOrOptions extends {
@@ -149,6 +180,9 @@ export type TablesUpdate<PublicTableNameOrOptions extends keyof PublicSchema['Ta
 } ? U : never : PublicTableNameOrOptions extends keyof PublicSchema['Tables'] ? PublicSchema['Tables'][PublicTableNameOrOptions] extends {
     Update: infer U;
 } ? U : never : never;
+/**
+ * Helper type to extract enum types from the public schema.
+ */
 export type Enums<PublicEnumNameOrOptions extends keyof PublicSchema['Enums'] | {
     schema: keyof AgentsDatabaseSchema;
 }, EnumName extends PublicEnumNameOrOptions extends {
@@ -156,6 +190,9 @@ export type Enums<PublicEnumNameOrOptions extends keyof PublicSchema['Enums'] |
 } ? keyof AgentsDatabaseSchema[PublicEnumNameOrOptions['schema']]['Enums'] : never = never> = PublicEnumNameOrOptions extends {
     schema: keyof AgentsDatabaseSchema;
 } ? AgentsDatabaseSchema[PublicEnumNameOrOptions['schema']]['Enums'][EnumName] : PublicEnumNameOrOptions extends keyof PublicSchema['Enums'] ? PublicSchema['Enums'][PublicEnumNameOrOptions] : never;
+/**
+ * Helper type to extract composite types from the public schema.
+ */
 export type CompositeTypes<PublicCompositeTypeNameOrOptions extends keyof PublicSchema['CompositeTypes'] | {
     schema: keyof AgentsDatabaseSchema;
 }, CompositeTypeName extends PublicCompositeTypeNameOrOptions extends {

package/esm/typings/src/types/ToolCall.d.ts

@@ -35,6 +35,73 @@ export type ToolCall = {
      */
     readonly warnings?: ReadonlyArray<TODO_any>;
 };
+/**
+ * Breakdown of teacher-learned commitment categories for self-learning.
+ */
+export type SelfLearningCommitmentTypeCounts = {
+    /**
+     * Total number of learned commitments.
+     */
+    readonly total: number;
+    /**
+     * Count of knowledge commitments.
+     */
+    readonly knowledge: number;
+    /**
+     * Count of rule commitments.
+     */
+    readonly rule: number;
+    /**
+     * Count of persona commitments.
+     */
+    readonly persona: number;
+    /**
+     * Count of other commitment types.
+     */
+    readonly other: number;
+};
+/**
+ * Summary of the teacher review step during self-learning.
+ */
+export type SelfLearningTeacherSummary = {
+    /**
+     * Indicates whether the teacher step was used.
+     */
+    readonly used: boolean;
+    /**
+     * Commitment breakdown produced by the teacher step.
+     */
+    readonly commitmentTypes: SelfLearningCommitmentTypeCounts;
+    /**
+     * Normalized commitment lines produced by the teacher step.
+     */
+    readonly commitments?: ReadonlyArray<string>;
+};
+/**
+ * Result payload for the self-learning tool call.
+ */
+export type SelfLearningToolCallResult = {
+    /**
+     * Indicates whether self-learning completed successfully.
+     */
+    readonly success: boolean;
+    /**
+     * Timestamp for when self-learning started.
+     */
+    readonly startedAt?: string_date_iso8601;
+    /**
+     * Timestamp for when self-learning finished.
+     */
+    readonly completedAt?: string_date_iso8601;
+    /**
+     * Number of conversation examples saved from this turn.
+     */
+    readonly samplesAdded?: number;
+    /**
+     * Summary of the teacher review step.
+     */
+    readonly teacher?: SelfLearningTeacherSummary;
+};
 /**
  * Tool call name emitted while preparing a GPT assistant for an agent.
  *

package/esm/typings/src/utils/linguistic-hash/linguisticHash.d.ts

@@ -1,6 +1,7 @@
 import type { LinguisticHashLanguage } from './LinguisticHashLanguage';
 export { DEFAULT_LINGUISTIC_HASH_LANGUAGE, LINGUISTIC_HASH_LANGUAGES, normalizeLinguisticHashLanguage, } from './LinguisticHashLanguage';
 export type { LinguisticHashLanguage } from './LinguisticHashLanguage';
+export { DEFAULT_LINGUISTIC_HASH_WORD_COUNT, MAX_LINGUISTIC_HASH_WORD_COUNT, MIN_LINGUISTIC_HASH_WORD_COUNT, normalizeLinguisticHashWordCount, } from './linguisticHashWordCount';
 /**
  * Creates a human-readable hash as a short, story-like phrase.
  *
@@ -11,27 +12,3 @@ export type { LinguisticHashLanguage } from './LinguisticHashLanguage';
  * @public exported from `@promptbook/utils`
  */
 export declare function linguisticHash(input: string, wordCount?: number, language?: LinguisticHashLanguage): Promise<string>;
-/**
- * The minimum number of words for a linguistic hash.
- *
- * @private utility of `linguisticHash`
- */
-export declare const MIN_LINGUISTIC_HASH_WORD_COUNT = 1;
-/**
- * The default number of words for a linguistic hash.
- *
- * @private utility of `linguisticHash`
- */
-export declare const DEFAULT_LINGUISTIC_HASH_WORD_COUNT = 7;
-/**
- * The maximum number of words for a linguistic hash.
- *
- * @private utility of `linguisticHash`
- */
-export declare const MAX_LINGUISTIC_HASH_WORD_COUNT: number;
-/**
- * Normalizes the word count to a supported integer range.
- *
- * @private utility of `linguisticHash`
- */
-export declare function normalizeLinguisticHashWordCount(wordCount?: number | null): number;

package/esm/typings/src/utils/linguistic-hash/linguisticHashWordCount.d.ts

@@ -0,0 +1,31 @@
+import { MAX_LINGUISTIC_HASH_WORD_COUNT } from './linguisticHashWordSelection';
+/**
+ * The minimum number of words for a linguistic hash.
+ *
+ * @private utility of `linguisticHash`
+ */
+export declare const MIN_LINGUISTIC_HASH_WORD_COUNT = 1;
+/**
+ * The default number of words for a linguistic hash.
+ *
+ * @private utility of `linguisticHash`
+ */
+export declare const DEFAULT_LINGUISTIC_HASH_WORD_COUNT = 7;
+/**
+ * Normalizes the word count to a supported integer range.
+ *
+ * @private utility of `linguisticHash`
+ */
+export declare function normalizeLinguisticHashWordCount(wordCount?: number | null): number;
+export { MAX_LINGUISTIC_HASH_WORD_COUNT };
+/**
+ * Bundled helpers for linguistic hash word count handling.
+ *
+ * @private utility of `linguisticHash`
+ */
+export declare const linguisticHashWordCount: {
+    DEFAULT_LINGUISTIC_HASH_WORD_COUNT: number;
+    MAX_LINGUISTIC_HASH_WORD_COUNT: number;
+    MIN_LINGUISTIC_HASH_WORD_COUNT: number;
+    normalizeLinguisticHashWordCount: typeof normalizeLinguisticHashWordCount;
+};

package/esm/typings/src/utils/linguistic-hash/linguisticHashWordSelection.d.ts

@@ -0,0 +1,22 @@
+import type { LinguisticHashWordLists } from './linguisticHashTypes';
+/**
+ * The maximum number of words for a linguistic hash.
+ *
+ * @private utility of `linguisticHash`
+ */
+export declare const MAX_LINGUISTIC_HASH_WORD_COUNT: number;
+/**
+ * Selects the requested number of words from the hash output.
+ *
+ * @private utility of `linguisticHash`
+ */
+export declare function createLinguisticHashWords(hash: string, wordCount: number, wordLists: LinguisticHashWordLists): string[];
+/**
+ * Bundled helpers for the linguistic hash word selection module.
+ *
+ * @private utility of `linguisticHash`
+ */
+export declare const linguisticHashWordSelection: {
+    createLinguisticHashWords: typeof createLinguisticHashWords;
+    MAX_LINGUISTIC_HASH_WORD_COUNT: number;
+};

package/esm/typings/src/utils/markdown/humanizeAiTextSources.d.ts

@@ -0,0 +1,13 @@
+import type { string_markdown } from '../../types/typeAliases';
+/**
+ * Remove bracketed source citation artifacts like `\u30105:1\u2020source\u3011`.
+ *
+ * Note: [??] This function is idempotent.
+ * Tip: If you want to do the full cleanup, look for `humanizeAiText` exported `@promptbook/markdown-utils`
+ *
+ * @public exported from `@promptbook/markdown-utils`
+ */
+export declare function humanizeAiTextSources(aiText: string_markdown): string_markdown;
+/**
+ * Note: [??] This function is not tested by itself but together with other cleanup functions with `humanizeAiText`
+ */

package/esm/typings/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.106.0-0`).
+ * It follows semantic versioning (e.g., `0.109.0-0`).
  *
  * @generated
  */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@promptbook/javascript",
-    "version": "0.107.0-0",
+    "version": "0.110.0-0",
     "description": "Promptbook: Turn your company's scattered knowledge into AI ready books",
     "private": false,
     "sideEffects": false,
@@ -94,7 +94,7 @@
     "module": "./esm/index.es.js",
     "typings": "./esm/typings/src/_packages/javascript.index.d.ts",
     "peerDependencies": {
-        "@promptbook/core": "0.107.0-0"
+        "@promptbook/core": "0.110.0-0"
     },
     "dependencies": {
         "crypto": "1.0.1",

package/umd/index.umd.js

@@ -22,7 +22,7 @@
      * @generated
      * @see https://github.com/webgptorg/promptbook
      */
-    const PROMPTBOOK_ENGINE_VERSION = '0.107.0-0';
+    const PROMPTBOOK_ENGINE_VERSION = '0.110.0-0';
     /**
      * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
      * Note: [💞] Ignore a discrepancy between file name and entity name