@promptbook/node 0.112.0-30 → 0.112.0-32

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

@@ -1,6 +1,9 @@
 import { Message } from '../../../types/Message';
+import type { LlmToolDefinition } from '../../../types/LlmToolDefinition';
+import type { ChatModelRequirements } from '../../../types/ModelRequirements';
 import type { ToolCall } from '../../../types/ToolCall';
-import type { id, string_date_iso8601, string_markdown } from '../../../types/typeAliases';
+import type { TODO_object } from '../../../utils/organization/TODO_object';
+import type { id, Parameters, string_date_iso8601, string_markdown, string_prompt, string_title } from '../../../types/typeAliases';
 export type ChatToolCall = ToolCall;
 /**
  * One item in a user-facing progress card shown while assistant response is still running.
@@ -52,6 +55,63 @@ export type ChatProgressCard = {
      */
     readonly isVisible?: boolean;
 };
+/**
+ * Serializable prompt snapshot stored alongside one assistant message for debugging and inspection.
+ */
+type ChatMessagePrompt = {
+    /**
+     * Human-readable label used for the prompt execution.
+     */
+    readonly title: string_title;
+    /**
+     * User-facing chat content submitted into the prompt pipeline.
+     */
+    readonly content: string_prompt;
+    /**
+     * Resolved prompt parameters passed into the agent turn.
+     */
+    readonly parameters: Parameters;
+    /**
+     * Chat-model requirements used when the turn was executed.
+     */
+    readonly modelRequirements: ChatModelRequirements;
+    /**
+     * Prior thread history provided to the prompt.
+     */
+    readonly thread?: ReadonlyArray<ChatMessage>;
+    /**
+     * Attachments submitted with the user turn.
+     */
+    readonly attachments?: ReadonlyArray<{
+        name: string;
+        type: string;
+        url: string;
+    }>;
+    /**
+     * Runtime tools explicitly passed on the chat prompt object.
+     */
+    readonly tools?: ReadonlyArray<LlmToolDefinition>;
+    /**
+     * Full list of tools available to the model for this turn.
+     */
+    readonly availableTools?: ReadonlyArray<LlmToolDefinition>;
+    /**
+     * Tool calls associated with the generated message, duplicated here for raw prompt inspection.
+     */
+    readonly toolCalls?: ReadonlyArray<ChatToolCall>;
+    /**
+     * Completed tool calls associated with the generated message, duplicated here for raw prompt inspection.
+     */
+    readonly completedToolCalls?: ReadonlyArray<ChatToolCall>;
+    /**
+     * Provider-facing prompt text after agent/runtime preparation, when available.
+     */
+    readonly rawPromptContent?: string_prompt;
+    /**
+     * Provider-facing raw request payload, when available.
+     */
+    readonly rawRequest?: TODO_object | null;
+};
 /**
  * Represents a single message within a chat interface.
  *
@@ -165,7 +225,23 @@ export type ChatMessage = Omit<Message<id>, 'direction' | 'recipients' | 'thread
      * Optional structured progress-card payload shown while a response is still in progress.
      */
     readonly progressCard?: ChatProgressCard;
+    /**
+     * Optional list of tools that were available to the model when generating this message.
+     *
+     * This field is populated by the server from the exact tool definitions passed to the LLM
+     * request so developers can inspect what capabilities the model had access to during
+     * each conversation turn.
+     */
+    readonly availableTools?: ReadonlyArray<LlmToolDefinition>;
+    /**
+     * Optional prompt snapshot from which this message was generated.
+     *
+     * Intended for advanced/raw inspection so developers can see the exact chat prompt,
+     * resolved parameters, tool availability, and provider payload associated with one turn.
+     */
+    readonly prompt?: ChatMessagePrompt;
 };
+export {};
 /**
  * TODO: Make all fields readonly
  * TODO: Delete `expectedAnswer` from ChatMessage

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

@@ -0,0 +1,37 @@
+/**
+ * Locale-aware date/time labels derived from one tool-call timestamp.
+ *
+ * @private utility of `<Chat/>`
+ */
+type ToolCallDateTimeLabels = {
+    /**
+     * Primary local time label shown in chips and clock panels.
+     */
+    readonly localTimeLabel: string;
+    /**
+     * Local calendar date label shown under the primary time.
+     */
+    readonly localDateLabel: string;
+    /**
+     * Exact local timestamp label used in detail sections.
+     */
+    readonly localDateTimeLabel: string;
+    /**
+     * Relative label such as `in 5 minutes` or `2 minutes ago`.
+     */
+    readonly relativeTimeLabel: string | null;
+};
+/**
+ * Formats one tool-call timestamp into shared locale-aware labels.
+ *
+ * @param date - Timestamp to format.
+ * @param options - Optional locale and relative-time reference point.
+ * @returns Shared labels consumed by tool-call chips and modals.
+ *
+ * @private utility of `<Chat/>`
+ */
+export declare function formatToolCallDateTime(date: Date, options?: {
+    locale?: string;
+    currentDate?: Date;
+}): ToolCallDateTimeLabels;
+export {};

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

@@ -0,0 +1,11 @@
+/**
+ * Formats a Date as a locale-aware short time string (e.g. "5:30 PM" or "17:30").
+ *
+ * @param date - Date to format.
+ * @param locale - Optional BCP-47 locale string (e.g. `"en"`, `"cs"`).
+ *                 When omitted the browser/OS default locale is used.
+ * @returns Formatted time string such as `"5:30 PM"` or `"17:30"`.
+ *
+ * @private utility of `<Chat/>`
+ */
+export declare function formatToolCallLocalTime(date: Date, locale?: string): string;

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

@@ -0,0 +1,10 @@
+/**
+ * Applies `{placeholder}` values to one tool-call translation template.
+ *
+ * @param template - Template from the host application or fallback copy.
+ * @param variables - Placeholder values keyed by variable name.
+ * @returns Formatted string ready for rendering.
+ *
+ * @private utility of `<Chat/>`
+ */
+export declare function formatToolCallTranslationTemplate(template: string, variables: Record<string, string | number>): string;

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

@@ -1,3 +1,4 @@
+import 'moment/locale/cs';
 import type { ChatMessage } from '../types/ChatMessage';
 /**
  * Display-ready timestamp values for a chat message.
@@ -21,6 +22,9 @@ export type ChatMessageTimingDisplay = {
 /**
  * Builds display-ready timestamp and duration labels for a chat message.
  *
+ * @param message - Message with optional timestamp metadata.
+ * @param locale - Optional moment locale used for formatting.
+ *
  * @private utility of `<Chat/>` component
  */
-export declare function getChatMessageTimingDisplay(message: ChatMessage): ChatMessageTimingDisplay | null;
+export declare function getChatMessageTimingDisplay(message: ChatMessage, locale?: string): ChatMessageTimingDisplay | null;

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

@@ -15,6 +15,25 @@ export type ToolCallChipletInfo = {
      */
     agentData?: AgentChipData;
 };
+/**
+ * Optional user-facing title overrides for technical tool names.
+ *
+ * @private utility of `<Chat/>`
+ */
+type ToolCallTitleOverrides = Readonly<Record<string, string>>;
+/**
+ * Optional localized labels used for user-facing chip text.
+ *
+ * @private utility of `<Chat/>`
+ */
+type ToolCallChipTranslations = {
+    readonly toolCallTimeChipLabel?: string;
+    readonly toolCallTimeoutChipLabel?: string;
+    readonly toolCallTimeoutChipCancelledLabel?: string;
+    readonly toolCallTimeoutChipInactiveLabel?: string;
+    readonly toolCallTimeoutChipUpdatedLabel?: string;
+    readonly toolCallTimeoutChipFallbackLabel?: string;
+};
 /**
  * Builds display text for a tool call chiplet.
  *
@@ -35,6 +54,12 @@ export declare const TOOL_TITLES: Record<string, {
 /**
  * Gets the chiplet information including text and agent data (for team tools).
  *
+ * @param toolCall - Tool call to build chiplet info for.
+ * @param locale - Optional BCP-47 locale string used to format time labels.
+ * @param titleOverrides - Optional localized titles keyed by tool name.
+ * @param chipTranslations - Optional localized chip templates for time-related tools.
+ *
  * @private [🧠] Maybe public?
  */
-export declare function getToolCallChipletInfo(toolCall: ToolCall): ToolCallChipletInfo;
+export declare function getToolCallChipletInfo(toolCall: ToolCall, locale?: string, titleOverrides?: ToolCallTitleOverrides, chipTranslations?: ToolCallChipTranslations): ToolCallChipletInfo;
+export {};

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

@@ -64,6 +64,24 @@ export type TimeoutToolCallPresentation = {
      */
     readonly localDueDateLabel: string | null;
 };
+/**
+ * Optional localized labels used by timeout chips and friendly modal copy.
+ *
+ * @private internal utility of `<Chat/>`
+ */
+type TimeoutToolCallTranslations = {
+    readonly toolCallTimeoutChipLabel?: string;
+    readonly toolCallTimeoutChipCancelledLabel?: string;
+    readonly toolCallTimeoutChipInactiveLabel?: string;
+    readonly toolCallTimeoutChipUpdatedLabel?: string;
+    readonly toolCallTimeoutChipFallbackLabel?: string;
+    readonly toolCallTimeoutPrimaryScheduledLabel?: string;
+    readonly toolCallTimeoutSecondaryDurationLabel?: string;
+    readonly toolCallTimeoutPrimaryCancelledLabel?: string;
+    readonly toolCallTimeoutPrimaryInactiveLabel?: string;
+    readonly toolCallTimeoutPrimaryUpdatedLabel?: string;
+    readonly toolCallTimeoutPrimaryFallbackLabel?: string;
+};
 /**
  * Inputs required to derive timeout presentation metadata.
  *
@@ -86,6 +104,11 @@ type ResolveTimeoutToolCallPresentationOptions = {
      * Current date used to calculate relative labels.
      */
     readonly currentDate?: Date;
+    /**
+     * Optional BCP-47 locale string used to format local-time labels.
+     * When omitted the browser/OS default locale is used.
+     */
+    readonly locale?: string;
 };
 /**
  * Determines whether a tool name belongs to the timeout commitment.
@@ -104,19 +127,19 @@ export declare function resolveTimeoutToolCallPresentation(options: ResolveTimeo
  *
  * @private internal utility of `<Chat/>`
  */
-export declare function buildTimeoutToolCallChipLabel(presentation: TimeoutToolCallPresentation): string;
+export declare function buildTimeoutToolCallChipLabel(presentation: TimeoutToolCallPresentation, translations?: TimeoutToolCallTranslations): string;
 /**
  * Builds the primary timeout sentence shown in default modal view.
  *
  * @private internal utility of `<Chat/>`
  */
-export declare function buildTimeoutToolPrimarySentence(presentation: TimeoutToolCallPresentation): string;
+export declare function buildTimeoutToolPrimarySentence(presentation: TimeoutToolCallPresentation, translations?: TimeoutToolCallTranslations): string;
 /**
  * Builds one default-view scheduling sentence with local-time and relative context.
  *
  * @private internal utility of `<Chat/>`
  */
-export declare function buildTimeoutToolScheduleSentence(presentation: TimeoutToolCallPresentation): string | null;
+export declare function buildTimeoutToolScheduleSentence(presentation: TimeoutToolCallPresentation, translations?: TimeoutToolCallTranslations): string | null;
 export {};
 /**
  * Note: [💞] Ignore a discrepancy between file name and entity name

package/esm/src/utils/toolCalls/mergeToolCalls.d.ts

@@ -1,4 +1,4 @@
-import type { ToolCall } from '../../types/ToolCall';
+import { type ToolCall } from '../../types/ToolCall';
 /**
  * Merges streamed tool-call snapshots by stable identity while preserving incremental logs,
  * warnings, and partial results.

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

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@promptbook/node",
-    "version": "0.112.0-30",
+    "version": "0.112.0-32",
     "description": "Promptbook: Turn your company's scattered knowledge into AI ready books",
     "private": false,
     "sideEffects": false,
@@ -96,7 +96,7 @@
     "module": "./esm/index.es.js",
     "typings": "./esm/typings/src/_packages/node.index.d.ts",
     "peerDependencies": {
-        "@promptbook/core": "0.112.0-30"
+        "@promptbook/core": "0.112.0-32"
     },
     "dependencies": {
         "@mozilla/readability": "0.6.0",

package/umd/index.umd.js

@@ -48,7 +48,7 @@
      * @generated
      * @see https://github.com/webgptorg/promptbook
      */
-    const PROMPTBOOK_ENGINE_VERSION = '0.112.0-30';
+    const PROMPTBOOK_ENGINE_VERSION = '0.112.0-32';
     /**
      * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
      * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -18410,10 +18410,6 @@
      * Prefix used for TEAM tool names.
      */
     const TEAM_TOOL_PREFIX = 'team_chat_';
-    /**
-     * Length of URL hash suffix appended to TEAM tool names.
-     */
-    const TEAM_TOOL_HASH_LENGTH = 10;
     /**
      * Fallback normalized name when teammate label is empty.
      */
@@ -18430,20 +18426,19 @@
         return normalized || TEAM_TOOL_FALLBACK_NAME;
     }
     /**
-     * Builds a deterministic TEAM tool name from teammate identity.
+     * Builds a deterministic TEAM tool name from the teammate label.
      *
-     * The readable part is based on teammate label while the hash suffix
-     * keeps uniqueness and stable mapping for the underlying teammate URL.
+     * The tool name is derived solely from the human-readable label so that it
+     * remains stable and predictable regardless of internal technical identifiers.
      *
-     * @param teammateUrl - Canonical teammate URL used at runtime.
-     * @param teammateLabel - Human-readable teammate label.
-     * @returns Deterministic TEAM tool name.
+     * @param _teammateUrl - Canonical teammate URL (kept for API compatibility, not used).
+     * @param teammateLabel - Human-readable teammate label used as the basis for the name.
+     * @returns TEAM tool name derived from the label.
      * @private internal utility of TEAM commitments and chat UI mapping
      */
-    function createTeamToolName(teammateUrl, teammateLabel) {
+    function createTeamToolName(_teammateUrl, teammateLabel) {
         const normalizedLabel = normalizeTeammateToolNamePart(teammateLabel);
-        const hash = computeHash(teammateUrl).substring(0, TEAM_TOOL_HASH_LENGTH);
-        return `${TEAM_TOOL_PREFIX}${normalizedLabel}_${hash}`;
+        return `${TEAM_TOOL_PREFIX}${normalizedLabel}`;
     }
 
     const urlRegex = /https?:\/\/[^\s]+/gi;
@@ -18648,7 +18643,7 @@
         `);
         }
         applyToAgentModelRequirements(requirements, content) {
-            var _a, _b;
+            var _a, _b, _c;
             const trimmedContent = content.trim();
             if (!trimmedContent) {
                 return requirements;
@@ -18660,14 +18655,18 @@
             }
             const agentName = ((_a = requirements._metadata) === null || _a === void 0 ? void 0 : _a.agentName) || 'Agent';
             const existingTeammates = ((_b = requirements._metadata) === null || _b === void 0 ? void 0 : _b.teammates) || [];
+            const preResolvedProfiles = (((_c = requirements._metadata) === null || _c === void 0 ? void 0 : _c.preResolvedTeammateProfiles) || {});
             const resolvedTeammates = resolveTeamTeammateLabels(trimmedContent, teammates);
             const teamEntries = resolvedTeammates.map((teammate) => {
+                const profile = preResolvedProfiles[teammate.url];
+                const resolvedLabel = (profile === null || profile === void 0 ? void 0 : profile.agentName) || teammate.label;
                 const existingTeammate = existingTeammates.find((entry) => entry.url === teammate.url);
                 return {
                     toolName: ((existingTeammate === null || existingTeammate === void 0 ? void 0 : existingTeammate.toolName) ||
-                        createTeamToolName(teammate.url, teammate.label)),
-                    teammate,
+                        createTeamToolName(teammate.url, resolvedLabel)),
+                    teammate: { ...teammate, label: resolvedLabel },
                     agentName,
+                    description: (profile === null || profile === void 0 ? void 0 : profile.personaDescription) || null,
                 };
             });
             for (const entry of teamEntries) {
@@ -18679,9 +18678,12 @@
                 if (updatedTools.some((tool) => tool.name === entry.toolName)) {
                     continue;
                 }
+                const toolDescription = entry.description
+                    ? `Consult teammate ${entry.teammate.label}\n${entry.description}`
+                    : `Consult teammate ${entry.teammate.label}`;
                 updatedTools.push({
                     name: entry.toolName,
-                    description: `Consult teammate ${entry.teammate.label}`,
+                    description: toolDescription,
                     parameters: {
                         type: 'object',
                         properties: {
@@ -18710,8 +18712,7 @@
                     toolName: entry.toolName,
                 });
             }
-            const teamOverviewText = createTeamOverviewText(trimmedContent, teamEntries);
-            const teamSystemMessage = this.createSystemMessageSection('Teammates:', buildTeamSystemMessageBody(teamOverviewText, teamEntries));
+            const teamSystemMessage = this.createSystemMessageSection('Teammates:', buildTeamSystemMessageBody(teamEntries));
             return this.appendToSystemMessage({
                 ...requirements,
                 tools: updatedTools,
@@ -18748,25 +18749,24 @@
             };
         });
     }
-    /**
-     * Rewrites TEAM commitment content into a URL-free teammate overview text.
-     */
-    function createTeamOverviewText(teamContent, teamEntries) {
-        let overviewText = teamContent;
-        for (const entry of teamEntries) {
-            overviewText = overviewText.split(entry.teammate.url).join(entry.teammate.label);
-        }
-        return overviewText.trim();
-    }
     /**
      * Builds the textual TEAM section body for the final system message.
+     *
+     * Each teammate is listed with its tool name and, when available, a one-line description.
+     * Uses `spaceTrim` to ensure consistent whitespace and indentation.
      */
-    function buildTeamSystemMessageBody(teamOverviewText, teamEntries) {
-        const teammateLines = teamEntries.map((entry, index) => `${index + 1}) ${entry.teammate.label} tool \`${entry.toolName}\``);
-        if (!teamOverviewText) {
-            return teammateLines.join('\n');
-        }
-        return `${teamOverviewText}\n\n${teammateLines.join('\n')}`;
+    function buildTeamSystemMessageBody(teamEntries) {
+        const lines = teamEntries.map((entry, index) => {
+            const toolLine = `${index + 1}) ${entry.teammate.label} tool \`${entry.toolName}\``;
+            if (!entry.description) {
+                return toolLine;
+            }
+            return _spaceTrim.spaceTrim(`
+            ${toolLine}
+               ${entry.description}
+        `);
+        });
+        return lines.join('\n');
     }
     /**
      * Registers tool function and title for a teammate tool.
@@ -27070,13 +27070,23 @@
      */
     function mergeToolCalls(existingToolCalls, incomingToolCalls) {
         if (!existingToolCalls || existingToolCalls.length === 0) {
-            return incomingToolCalls ? [...incomingToolCalls] : [];
+            return incomingToolCalls ? deduplicatePreparationToolCalls([...incomingToolCalls]) : [];
         }
         if (!incomingToolCalls || incomingToolCalls.length === 0) {
             return [...existingToolCalls];
         }
         const mergedToolCalls = [...existingToolCalls];
         for (const incomingToolCall of incomingToolCalls) {
+            if (isAssistantPreparationToolCall(incomingToolCall)) {
+                // A new preparation phase always replaces any previous assistant_preparation tool
+                // call, regardless of phase argument, so only one chip is ever shown at a time.
+                const existingPreparationIndex = mergedToolCalls.findIndex(isAssistantPreparationToolCall);
+                if (existingPreparationIndex !== -1) {
+                    mergedToolCalls.splice(existingPreparationIndex, 1);
+                }
+                mergedToolCalls.push(incomingToolCall);
+                continue;
+            }
             const incomingIdentity = getToolCallIdentity(incomingToolCall);
             const existingIndex = mergedToolCalls.findIndex((existingToolCall) => getToolCallIdentity(existingToolCall) === incomingIdentity);
             if (existingIndex === -1) {
@@ -27188,6 +27198,30 @@
             return String(value);
         }
     }
+    /**
+     * Ensures at most one `assistant_preparation` tool call survives in the list,
+     * keeping the last occurrence so the most recent preparation phase is shown.
+     *
+     * @param toolCalls - Mutable list to deduplicate in-place.
+     * @returns The same array after removing redundant preparation entries.
+     * @private helper of `mergeToolCalls`
+     */
+    function deduplicatePreparationToolCalls(toolCalls) {
+        let lastPreparationIndex = -1;
+        for (let index = toolCalls.length - 1; index >= 0; index--) {
+            if (!isAssistantPreparationToolCall(toolCalls[index])) {
+                continue;
+            }
+            if (lastPreparationIndex === -1) {
+                lastPreparationIndex = index;
+            }
+            else {
+                // Remove earlier duplicate — keep only the last (most recent) one.
+                toolCalls.splice(index, 1);
+            }
+        }
+        return toolCalls;
+    }
 
     /**
      * Computes SHA-256 hash of the agent source
@@ -28120,7 +28154,7 @@
      * @private @@@
      */
     async function createAgentModelRequirementsWithCommitments(agentSource, modelName, options) {
-        var _a;
+        var _a, _b, _c;
         const agentReferenceResolver = options === null || options === void 0 ? void 0 : options.agentReferenceResolver;
         // Parse the agent source to extract commitments
         const parseResult = parseAgentSourceWithCommitments(agentSource);
@@ -28188,6 +28222,36 @@
             if (commitment.type === 'CLOSED' && i !== filteredCommitments.length - 1) {
                 continue;
             }
+            // For TEAM commitments, pre-resolve teammate profiles if a resolver is provided
+            // and store them in metadata before the commitment is applied.
+            const profileResolver = (_a = options === null || options === void 0 ? void 0 : options.teammateProfileResolver) !== null && _a !== void 0 ? _a : options === null || options === void 0 ? void 0 : options.agentReferenceResolver;
+            if (commitment.type === 'TEAM' && (profileResolver === null || profileResolver === void 0 ? void 0 : profileResolver.resolveTeammateProfile)) {
+                try {
+                    const parsedTeammates = parseTeamCommitmentContent(commitmentContent, { strict: false });
+                    const preResolved = {
+                        ...(_b = requirements._metadata) === null || _b === void 0 ? void 0 : _b.preResolvedTeammateProfiles,
+                    };
+                    for (const teammate of parsedTeammates) {
+                        if (preResolved[teammate.url]) {
+                            continue;
+                        }
+                        const profile = await profileResolver.resolveTeammateProfile(teammate.url);
+                        if (profile) {
+                            preResolved[teammate.url] = profile;
+                        }
+                    }
+                    requirements = {
+                        ...requirements,
+                        _metadata: {
+                            ...requirements._metadata,
+                            preResolvedTeammateProfiles: preResolved,
+                        },
+                    };
+                }
+                catch (error) {
+                    console.warn('Failed to pre-resolve teammate profiles for TEAM commitment:', error);
+                }
+            }
             const definition = getCommitmentDefinition(commitment.type);
             if (definition) {
                 try {
@@ -28283,7 +28347,7 @@
         // Add example interactions to the system message
         const examples = [];
         // 1. Initial message as an example agent response
-        const initialMessage = (_a = parseResult.commitments.find((c) => c.type === 'INITIAL MESSAGE')) === null || _a === void 0 ? void 0 : _a.content;
+        const initialMessage = (_c = parseResult.commitments.find((c) => c.type === 'INITIAL MESSAGE')) === null || _c === void 0 ? void 0 : _c.content;
         if (initialMessage) {
             examples.push(`Agent: ${initialMessage}`);
         }
@@ -34128,6 +34192,7 @@
 
                 - Decide what the agent should learn from this interaction.
                 - Append new commitments at the end of the agent source.
+                - Return only newly learned commitments, never repeat commitments that are already present.
                 - Do not modify the current agent source, just return new commitments (KNOWLEDGE, RULE, etc.).
                 - If there is nothing new to learn, return empty book code block
                 - Wrap the commitments in a book code block.
@@ -34180,10 +34245,42 @@
          */
         appendToAgentSource(section) {
             const currentSource = this.options.getAgentSource();
-            const newSource = padBook(validateBook(_spaceTrim.spaceTrim(currentSource) + section));
+            const normalizedSection = normalizeBookSection(section);
+            if (!normalizedSection) {
+                return;
+            }
+            if (containsNormalizedBookSection(currentSource, normalizedSection)) {
+                return;
+            }
+            const newSource = padBook(validateBook(`${normalizeBookSection(currentSource)}\n\n${normalizedSection}`));
             this.options.updateAgentSource(newSource);
         }
     }
+    /**
+     * Normalizes one book fragment for deduplication and append composition.
+     *
+     * @param section Raw fragment from self-learning workflow.
+     * @returns Trimmed fragment, or empty string when nothing remains.
+     * @private function of Agent
+     */
+    function normalizeBookSection(section) {
+        return _spaceTrim.spaceTrim(section).replace(/\r\n/g, '\n');
+    }
+    /**
+     * Checks whether one normalized fragment already exists inside the current source.
+     *
+     * @param agentSource Current source.
+     * @param normalizedSection Candidate fragment expected to be normalized first.
+     * @returns True when appending would duplicate an existing fragment.
+     * @private function of Agent
+     */
+    function containsNormalizedBookSection(agentSource, normalizedSection) {
+        if (!normalizedSection) {
+            return true;
+        }
+        const normalizedSource = normalizeBookSection(agentSource);
+        return normalizedSource.includes(normalizedSection);
+    }
     /**
      * Determines whether the interaction runs in OpenAI-compatible JSON schema mode.
      *