@promptbook/browser 0.110.0 → 0.111.0-1

package/umd/index.umd.js

@@ -28,7 +28,7 @@
      * @generated
      * @see https://github.com/webgptorg/promptbook
      */
-    const PROMPTBOOK_ENGINE_VERSION = '0.110.0';
+    const PROMPTBOOK_ENGINE_VERSION = '0.111.0-1';
     /**
      * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
      * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -3859,6 +3859,36 @@
      * Note: [💞] Ignore a discrepancy between file name and entity name
      */
 
+    /**
+     * HTTP header used by Promptbook clients to advertise their release version.
+     *
+     * @public exported from `@promptbook/utils`
+     */
+    const CLIENT_VERSION_HEADER = 'x-promptbook-client-version';
+    /**
+     * The latest client (engine) version that the server expects.
+     *
+     * @public exported from `@promptbook/utils`
+     */
+    const CLIENT_LATEST_VERSION = PROMPTBOOK_ENGINE_VERSION;
+    /**
+     * Creates a headers object that includes the client version header.
+     *
+     * @param headers - Optional base headers to clone.
+     * @returns New headers object augmented with `CLIENT_VERSION_HEADER`.
+     *
+     * @public exported from `@promptbook/utils`
+     */
+    function attachClientVersionHeader(headers) {
+        return {
+            ...(headers !== null && headers !== void 0 ? headers : {}),
+            [CLIENT_VERSION_HEADER]: CLIENT_LATEST_VERSION,
+        };
+    }
+    /**
+     * Note: [💞] Ignore a discrepancy between file name and entity name
+     */
+
     /**
      * Detects if the code is running in a browser environment in main thread (Not in a web worker)
      *
@@ -6197,28 +6227,14 @@
      * Note: [💞] Ignore a discrepancy between file name and entity name
      */
 
-    /**
-     * @@@
-     *
-     * @private thing of inline knowledge
-     */
+    /** @private The default base name for inline knowledge files when the content lacks identifying text */
     const INLINE_KNOWLEDGE_BASE_NAME = 'inline-knowledge';
-    /**
-     * @@@
-     *
-     * @private thing of inline knowledge
-     */
+    /** @private The default file extension used for inline knowledge uploads */
     const INLINE_KNOWLEDGE_EXTENSION = '.txt';
-    /**
-     * @@@
-     *
-     * @private thing of inline knowledge
-     */
+    /** @private Prefix that identifies base64 data URLs */
     const DATA_URL_PREFIX = 'data:';
     /**
-     * @@@
-     *
-     * @private thing of inline knowledge
+     * @private Retrieves the first meaningful line from the inline content.
      */
     function getFirstNonEmptyLine(content) {
         const lines = content.split(/\r?\n/);
@@ -6231,9 +6247,7 @@
         return null;
     }
     /**
-     * @@@
-     *
-     * @private thing of inline knowledge
+     * @private Determines the base file name by normalizing the first non-empty line.
      */
     function deriveBaseFilename(content) {
         const firstLine = getFirstNonEmptyLine(content);
@@ -6244,22 +6258,18 @@
         return normalized || INLINE_KNOWLEDGE_BASE_NAME;
     }
     /**
-     * Creates a data URL that represents the inline knowledge content as a text file.
-     *
-     * @private thing of inline knowledge
+     * @private Converts inline knowledge into the internal metadata form used for uploads.
      */
     function createInlineKnowledgeSourceFile(content) {
         const trimmedContent = content.trim();
         const baseName = deriveBaseFilename(trimmedContent);
         const filename = `${baseName}${INLINE_KNOWLEDGE_EXTENSION}`;
         const mimeType = 'text/plain';
-        const base64 = Buffer.from(trimmedContent, 'utf-8').toString('base64');
-        const encodedFilename = encodeURIComponent(filename);
-        const url = `${DATA_URL_PREFIX}${mimeType};name=${encodedFilename};charset=utf-8;base64,${base64}`;
+        const buffer = Buffer.from(trimmedContent, 'utf-8');
         return {
             filename,
             mimeType,
-            url,
+            buffer,
         };
     }
     /**
@@ -6270,10 +6280,18 @@
     function isDataUrlKnowledgeSource(source) {
         return typeof source === 'string' && source.startsWith(DATA_URL_PREFIX);
     }
+    /**
+     * @private Converts a stored inline knowledge file into a data URL for backwards compatibility.
+     */
+    function inlineKnowledgeSourceToDataUrl(source) {
+        const base64 = source.buffer.toString('base64');
+        const encodedFilename = encodeURIComponent(source.filename);
+        return `${DATA_URL_PREFIX}${source.mimeType};name=${encodedFilename};charset=utf-8;base64,${base64}`;
+    }
     /**
      * Parses a data URL-based knowledge source into its raw buffer, filename, and MIME type.
      *
-     * @private thing of inline knowledge
+     * @private utility of inline knowledge processing
      */
     function parseDataUrlKnowledgeSource(source) {
         if (!isDataUrlKnowledgeSource(source)) {
@@ -6406,6 +6424,7 @@
         `);
         }
         applyToAgentModelRequirements(requirements, content) {
+            var _a;
             const trimmedContent = content.trim();
             if (!trimmedContent) {
                 return requirements;
@@ -6426,9 +6445,13 @@
             }
             else {
                 const inlineSource = createInlineKnowledgeSourceFile(trimmedContent);
+                const existingInlineSources = (((_a = requirements._metadata) === null || _a === void 0 ? void 0 : _a.inlineKnowledgeSources) || []).slice();
                 const updatedRequirements = {
                     ...requirements,
-                    knowledgeSources: [...(requirements.knowledgeSources || []), inlineSource.url],
+                    _metadata: {
+                        ...requirements._metadata,
+                        inlineKnowledgeSources: [...existingInlineSources, inlineSource],
+                    },
                 };
                 const knowledgeInfo = `Knowledge Source Inline: ${inlineSource.filename} (derived from inline content and processed for retrieval during chat)`;
                 return this.appendToSystemMessage(updatedRequirements, knowledgeInfo, '\n\n');
@@ -6510,6 +6533,237 @@
      * Note: [💞] Ignore a discrepancy between file name and entity name
      */
 
+    /**
+     * @@@
+     *
+     * @private utility for commitments
+     */
+    function formatOptionalInstructionBlock(label, content) {
+        const trimmedContent = spaceTrim$1.spaceTrim(content);
+        if (!trimmedContent) {
+            return '';
+        }
+        return spaceTrim$1.spaceTrim((block) => `
+        - ${label}:
+            ${block(trimmedContent
+        .split(/\r?\n/)
+        .map((line) => `- ${line}`)
+        .join('\n'))}
+    `);
+    }
+
+    /**
+     * Prompt parameter key used to pass hidden runtime context to tool execution.
+     *
+     * @private internal runtime wiring for commitment tools
+     */
+    const TOOL_RUNTIME_CONTEXT_PARAMETER = 'promptbookToolRuntimeContext';
+    /**
+     * Hidden argument key used to pass runtime context into individual tool calls.
+     *
+     * @private internal runtime wiring for commitment tools
+     */
+    const TOOL_RUNTIME_CONTEXT_ARGUMENT = '__promptbookToolRuntimeContext';
+    /**
+     * Parses unknown runtime context payload into a normalized object.
+     *
+     * @private internal runtime wiring for commitment tools
+     */
+    function parseToolRuntimeContext(rawValue) {
+        if (!rawValue) {
+            return null;
+        }
+        let parsed = rawValue;
+        if (typeof rawValue === 'string') {
+            try {
+                parsed = JSON.parse(rawValue);
+            }
+            catch (_a) {
+                return null;
+            }
+        }
+        if (!parsed || typeof parsed !== 'object') {
+            return null;
+        }
+        return parsed;
+    }
+    /**
+     * Reads runtime context attached to tool call arguments.
+     *
+     * @private internal runtime wiring for commitment tools
+     */
+    function readToolRuntimeContextFromToolArgs(args) {
+        return parseToolRuntimeContext(args[TOOL_RUNTIME_CONTEXT_ARGUMENT]);
+    }
+    /**
+     * Serializes runtime context for prompt parameters.
+     *
+     * @private internal runtime wiring for commitment tools
+     */
+    function serializeToolRuntimeContext(context) {
+        return JSON.stringify(context);
+    }
+    /**
+     * Note: [💞] Ignore a discrepancy between file name and entity name
+     */
+
+    /**
+     * Tool name used to retrieve persisted user memory.
+     *
+     * @private internal MEMORY commitment constant
+     */
+    const RETRIEVE_USER_MEMORY_TOOL_NAME = 'retrieve_user_memory';
+    /**
+     * Tool name used to store persisted user memory.
+     *
+     * @private internal MEMORY commitment constant
+     */
+    const STORE_USER_MEMORY_TOOL_NAME = 'store_user_memory';
+    const UPDATE_USER_MEMORY_TOOL_NAME = 'update_user_memory';
+    const DELETE_USER_MEMORY_TOOL_NAME = 'delete_user_memory';
+    /**
+     * Resolves runtime context from hidden tool arguments.
+     *
+     * @private utility of MEMORY commitment
+     */
+    function resolveMemoryRuntimeContext(args) {
+        const runtimeContext = readToolRuntimeContextFromToolArgs(args);
+        const memoryContext = runtimeContext === null || runtimeContext === void 0 ? void 0 : runtimeContext.memory;
+        return {
+            enabled: (memoryContext === null || memoryContext === void 0 ? void 0 : memoryContext.enabled) === true,
+            userId: memoryContext === null || memoryContext === void 0 ? void 0 : memoryContext.userId,
+            username: memoryContext === null || memoryContext === void 0 ? void 0 : memoryContext.username,
+            agentId: memoryContext === null || memoryContext === void 0 ? void 0 : memoryContext.agentId,
+            agentName: memoryContext === null || memoryContext === void 0 ? void 0 : memoryContext.agentName,
+            isTeamConversation: (memoryContext === null || memoryContext === void 0 ? void 0 : memoryContext.isTeamConversation) === true,
+        };
+    }
+    /**
+     * Builds a disabled memory-tool response payload.
+     *
+     * @private utility of MEMORY commitment
+     */
+    function createDisabledMemoryResult(action, message) {
+        if (action === 'retrieve') {
+            return {
+                action,
+                status: 'disabled',
+                memories: [],
+                message,
+            };
+        }
+        if (action === 'store') {
+            return {
+                action,
+                status: 'disabled',
+                message,
+            };
+        }
+        if (action === 'update') {
+            return {
+                action,
+                status: 'disabled',
+                message,
+            };
+        }
+        if (action === 'delete') {
+            return {
+                action,
+                status: 'disabled',
+                message,
+            };
+        }
+        throw new Error(`Unsupported memory tool action: ${action}`);
+    }
+    /**
+     * Gets the runtime adapter and returns a disabled result when unavailable.
+     *
+     * @private utility of MEMORY commitment
+     */
+    function getRuntimeAdapterOrDisabledResult(action, runtimeContext) {
+        if (!runtimeContext.enabled || runtimeContext.isTeamConversation) {
+            return {
+                adapter: null,
+                disabledResult: createDisabledMemoryResult(action, runtimeContext.isTeamConversation
+                    ? 'Memory is disabled for TEAM conversations.'
+                    : 'Memory is disabled for unauthenticated users.'),
+            };
+        }
+        {
+            return {
+                adapter: null,
+                disabledResult: createDisabledMemoryResult(action, 'Memory runtime is not available in this environment.'),
+            };
+        }
+    }
+    /**
+     * Parses retrieve memory arguments.
+     *
+     * @private utility of MEMORY commitment
+     */
+    function parseRetrieveMemoryArgs(args) {
+        const query = typeof args.query === 'string' ? args.query.trim() : undefined;
+        const limit = typeof args.limit === 'number' && Number.isFinite(args.limit) ? Math.floor(args.limit) : undefined;
+        return {
+            query: query && query.length > 0 ? query : undefined,
+            limit: limit && limit > 0 ? Math.min(limit, 20) : undefined,
+        };
+    }
+    /**
+     * Parses store memory arguments.
+     *
+     * @private utility of MEMORY commitment
+     */
+    function parseStoreMemoryArgs(args) {
+        const content = typeof args.content === 'string' ? args.content.trim() : '';
+        if (!content) {
+            throw new Error('Memory content is required.');
+        }
+        return {
+            content,
+            isGlobal: args.isGlobal === true,
+        };
+    }
+    /**
+     * Parses a memory identifier argument shared across MEMORY tools.
+     *
+     * @private utility of MEMORY commitment
+     */
+    function parseMemoryIdArg(value) {
+        const memoryId = typeof value === 'string' ? value.trim() : '';
+        if (!memoryId) {
+            throw new Error('Memory id is required.');
+        }
+        return memoryId;
+    }
+    /**
+     * Parses update memory arguments.
+     *
+     * @private utility of MEMORY commitment
+     */
+    function parseUpdateMemoryArgs(args) {
+        const memoryId = parseMemoryIdArg(args.memoryId);
+        const content = typeof args.content === 'string' ? args.content.trim() : '';
+        if (!content) {
+            throw new Error('Memory content is required.');
+        }
+        const isGlobal = typeof args.isGlobal === 'boolean' ? args.isGlobal : undefined;
+        return {
+            memoryId,
+            content,
+            isGlobal,
+        };
+    }
+    /**
+     * Parses delete memory arguments.
+     *
+     * @private utility of MEMORY commitment
+     */
+    function parseDeleteMemoryArgs(args) {
+        return {
+            memoryId: parseMemoryIdArg(args.memoryId),
+        };
+    }
     /**
      * MEMORY commitment definition
      *
@@ -6531,6 +6785,9 @@
         constructor(type = 'MEMORY') {
             super(type);
         }
+        get requiresContent() {
+            return false;
+        }
         /**
          * Short one-line description of MEMORY.
          */
@@ -6550,21 +6807,14 @@
             return spaceTrim$1.spaceTrim(`
             # ${this.type}
 
-            Similar to KNOWLEDGE but focuses on remembering past interactions and user preferences. This commitment helps the agent maintain context about the user's history, preferences, and previous conversations.
+            Enables persistent user memory for the current agent. The memory is stored by the runtime and can be retrieved in future conversations.
 
             ## Key aspects
 
-            - Both terms work identically and can be used interchangeably.
-            - Focuses on user-specific information and interaction history.
-            - Helps personalize responses based on past interactions.
-            - Maintains continuity across conversations.
-
-            ## Differences from KNOWLEDGE
-
-            - \`KNOWLEDGE\` is for domain expertise and factual information
-            - \`MEMORY\` is for user-specific context and preferences
-            - \`MEMORY\` creates more personalized interactions
-            - \`MEMORY\` often includes temporal or preference-based information
+            - Both \`MEMORY\` and \`MEMORIES\` work identically.
+            - Stores user-specific details through runtime tools.
+            - Retrieves relevant memories for personalized responses.
+            - Supports optional extra instructions in the commitment content.
 
             ## Examples
 
@@ -6572,10 +6822,7 @@
             Personal Assistant
 
             PERSONA You are a personal productivity assistant
-            MEMORY User is a software developer working in JavaScript/React
-            MEMORY User prefers morning work sessions and afternoon meetings
-            MEMORY Previously helped with project planning for mobile apps
-            MEMORY User timezone: UTC-8 (Pacific Time)
+            MEMORY Remember user projects and long-term preferences.
             GOAL Help optimize daily productivity and workflow
             \`\`\`
 
@@ -6583,10 +6830,7 @@
             Learning Companion
 
             PERSONA You are an educational companion for programming students
-            MEMORY Student is learning Python as their first programming language
-            MEMORY Previous topics covered: variables, loops, functions
-            MEMORY Student learns best with practical examples and exercises
-            MEMORY Last session: working on list comprehensions
+            MEMORY Remember only the student's learning progress and preferred study style.
             GOAL Provide progressive learning experiences tailored to student's pace
             \`\`\`
 
@@ -6594,23 +6838,245 @@
             Customer Support Agent
 
             PERSONA You are a customer support representative
-            MEMORY Customer has premium subscription since 2023
-            MEMORY Previous issue: billing question resolved last month
-            MEMORY Customer prefers email communication over phone calls
-            MEMORY Account shows frequent use of advanced features
+            MEMORY Remember only important support history and communication preferences.
             GOAL Provide personalized support based on customer history
             \`\`\`
         `);
         }
         applyToAgentModelRequirements(requirements, content) {
-            const trimmedContent = content.trim();
-            if (!trimmedContent) {
-                return requirements;
+            const extraInstructions = formatOptionalInstructionBlock('Memory instructions', content);
+            const existingTools = requirements.tools || [];
+            const tools = [...existingTools];
+            if (!tools.some((tool) => tool.name === RETRIEVE_USER_MEMORY_TOOL_NAME)) {
+                tools.push({
+                    name: RETRIEVE_USER_MEMORY_TOOL_NAME,
+                    description: spaceTrim$1.spaceTrim(`
+                    Retrieve previously stored user memories relevant to the current conversation.
+                    Use this before responding when user context can improve the answer.
+                `),
+                    parameters: {
+                        type: 'object',
+                        properties: {
+                            query: {
+                                type: 'string',
+                                description: 'Optional query used to filter relevant memories.',
+                            },
+                            limit: {
+                                type: 'integer',
+                                description: 'Optional maximum number of memories to return (default 5, max 20).',
+                            },
+                        },
+                    },
+                });
+            }
+            if (!tools.some((tool) => tool.name === STORE_USER_MEMORY_TOOL_NAME)) {
+                tools.push({
+                    name: STORE_USER_MEMORY_TOOL_NAME,
+                    description: spaceTrim$1.spaceTrim(`
+                    Store a durable user memory that should be remembered in future conversations.
+                    Store only stable and useful user-specific facts or preferences.
+                `),
+                    parameters: {
+                        type: 'object',
+                        properties: {
+                            content: {
+                                type: 'string',
+                                description: 'Memory text to store.',
+                            },
+                            isGlobal: {
+                                type: 'boolean',
+                                description: 'Set true to make this memory global across all user agents.',
+                            },
+                        },
+                        required: ['content'],
+                    },
+                });
+            }
+            if (!tools.some((tool) => tool.name === UPDATE_USER_MEMORY_TOOL_NAME)) {
+                tools.push({
+                    name: UPDATE_USER_MEMORY_TOOL_NAME,
+                    description: spaceTrim$1.spaceTrim(`
+                    Update an existing user memory after retrieving it, so the stored fact stays accurate.
+                    Always pass the memory id you retrieved along with the new content.
+                `),
+                    parameters: {
+                        type: 'object',
+                        properties: {
+                            memoryId: {
+                                type: 'string',
+                                description: 'Unique identifier of the memory entry to update.',
+                            },
+                            content: {
+                                type: 'string',
+                                description: 'Updated memory text.',
+                            },
+                            isGlobal: {
+                                type: 'boolean',
+                                description: 'Set true to keep the fact global; omit or false to keep it agent-scoped.',
+                            },
+                        },
+                        required: ['memoryId', 'content'],
+                    },
+                });
+            }
+            if (!tools.some((tool) => tool.name === DELETE_USER_MEMORY_TOOL_NAME)) {
+                tools.push({
+                    name: DELETE_USER_MEMORY_TOOL_NAME,
+                    description: spaceTrim$1.spaceTrim(`
+                    Delete a user memory that is no longer relevant. Deletions are soft so the record is hidden from future queries.
+                `),
+                    parameters: {
+                        type: 'object',
+                        properties: {
+                            memoryId: {
+                                type: 'string',
+                                description: 'Unique identifier of the memory entry to delete.',
+                            },
+                        },
+                        required: ['memoryId'],
+                    },
+                });
             }
-            // Create memory section for system message
-            const memorySection = `Memory: ${trimmedContent}`;
-            // Memory information is contextual and should be included in the system message
-            return this.appendToSystemMessage(requirements, memorySection, '\n\n');
+            return this.appendToSystemMessage({
+                ...requirements,
+                tools,
+                _metadata: {
+                    ...requirements._metadata,
+                    useMemory: content || true,
+                },
+            }, spaceTrim$1.spaceTrim((block) => `
+                    Memory:
+                    - Prefer storing agent-scoped memories; only make them global when the fact should apply across all your agents.
+                    - You can use persistent user memory tools.
+                    - Use "${RETRIEVE_USER_MEMORY_TOOL_NAME}" to load relevant memory before answering.
+                    - Use "${STORE_USER_MEMORY_TOOL_NAME}" to save stable user-specific facts that improve future help.
+                    - Use "${UPDATE_USER_MEMORY_TOOL_NAME}" to refresh an existing memory when the content changes.
+                    - Use "${DELETE_USER_MEMORY_TOOL_NAME}" to delete memories that are no longer accurate (deletions are soft and hidden from future queries).
+                    - Store concise memory items and avoid duplicates.
+                    - Never claim memory was saved or loaded unless the tool confirms it.
+                    ${block(extraInstructions)}
+                `));
+        }
+        /**
+         * Gets human-readable titles for MEMORY tool functions.
+         */
+        getToolTitles() {
+            return {
+                [RETRIEVE_USER_MEMORY_TOOL_NAME]: 'User memory',
+                [STORE_USER_MEMORY_TOOL_NAME]: 'Store user memory',
+                [UPDATE_USER_MEMORY_TOOL_NAME]: 'Update user memory',
+                [DELETE_USER_MEMORY_TOOL_NAME]: 'Delete user memory',
+            };
+        }
+        /**
+         * Gets MEMORY tool function implementations.
+         */
+        getToolFunctions() {
+            return {
+                async [RETRIEVE_USER_MEMORY_TOOL_NAME](args) {
+                    const runtimeContext = resolveMemoryRuntimeContext(args);
+                    const { adapter, disabledResult } = getRuntimeAdapterOrDisabledResult('retrieve', runtimeContext);
+                    if (!adapter || disabledResult) {
+                        return JSON.stringify(disabledResult);
+                    }
+                    const parsedArgs = parseRetrieveMemoryArgs(args);
+                    try {
+                        const memories = await adapter.retrieveMemories(parsedArgs, runtimeContext);
+                        const result = {
+                            action: 'retrieve',
+                            status: 'ok',
+                            query: parsedArgs.query,
+                            memories,
+                        };
+                        return JSON.stringify(result);
+                    }
+                    catch (error) {
+                        const result = {
+                            action: 'retrieve',
+                            status: 'error',
+                            query: parsedArgs.query,
+                            memories: [],
+                            message: error instanceof Error ? error.message : String(error),
+                        };
+                        return JSON.stringify(result);
+                    }
+                },
+                async [STORE_USER_MEMORY_TOOL_NAME](args) {
+                    const runtimeContext = resolveMemoryRuntimeContext(args);
+                    const { adapter, disabledResult } = getRuntimeAdapterOrDisabledResult('store', runtimeContext);
+                    if (!adapter || disabledResult) {
+                        return JSON.stringify(disabledResult);
+                    }
+                    try {
+                        const parsedArgs = parseStoreMemoryArgs(args);
+                        const memory = await adapter.storeMemory(parsedArgs, runtimeContext);
+                        const result = {
+                            action: 'store',
+                            status: 'stored',
+                            memory,
+                        };
+                        return JSON.stringify(result);
+                    }
+                    catch (error) {
+                        const result = {
+                            action: 'store',
+                            status: 'error',
+                            message: error instanceof Error ? error.message : String(error),
+                        };
+                        return JSON.stringify(result);
+                    }
+                },
+                async [UPDATE_USER_MEMORY_TOOL_NAME](args) {
+                    const runtimeContext = resolveMemoryRuntimeContext(args);
+                    const { adapter, disabledResult } = getRuntimeAdapterOrDisabledResult('update', runtimeContext);
+                    if (!adapter || disabledResult) {
+                        return JSON.stringify(disabledResult);
+                    }
+                    try {
+                        const parsedArgs = parseUpdateMemoryArgs(args);
+                        const memory = await adapter.updateMemory(parsedArgs, runtimeContext);
+                        const result = {
+                            action: 'update',
+                            status: 'updated',
+                            memory,
+                        };
+                        return JSON.stringify(result);
+                    }
+                    catch (error) {
+                        const result = {
+                            action: 'update',
+                            status: 'error',
+                            message: error instanceof Error ? error.message : String(error),
+                        };
+                        return JSON.stringify(result);
+                    }
+                },
+                async [DELETE_USER_MEMORY_TOOL_NAME](args) {
+                    const runtimeContext = resolveMemoryRuntimeContext(args);
+                    const { adapter, disabledResult } = getRuntimeAdapterOrDisabledResult('delete', runtimeContext);
+                    if (!adapter || disabledResult) {
+                        return JSON.stringify(disabledResult);
+                    }
+                    try {
+                        const parsedArgs = parseDeleteMemoryArgs(args);
+                        const deleted = await adapter.deleteMemory(parsedArgs, runtimeContext);
+                        const result = {
+                            action: 'delete',
+                            status: 'deleted',
+                            memoryId: deleted.id,
+                        };
+                        return JSON.stringify(result);
+                    }
+                    catch (error) {
+                        const result = {
+                            action: 'delete',
+                            status: 'error',
+                            message: error instanceof Error ? error.message : String(error),
+                        };
+                        return JSON.stringify(result);
+                    }
+                },
+            };
         }
     }
     /**
@@ -8723,14 +9189,30 @@
     /**
      * Builds a minimal chat prompt for teammate calls.
      */
-    function buildTeammatePrompt(request) {
+    function buildTeammatePrompt(request, runtimeContext) {
         return {
             title: 'Teammate consultation',
             modelRequirements: {
                 modelVariant: 'CHAT',
             },
             content: request,
-            parameters: {},
+            parameters: {
+                [TOOL_RUNTIME_CONTEXT_PARAMETER]: serializeToolRuntimeContext(runtimeContext),
+            },
+        };
+    }
+    /**
+     * Creates teammate runtime context and marks conversation as team-only memory-disabled.
+     */
+    function createTeamConversationRuntimeContext(value) {
+        const runtimeContext = parseToolRuntimeContext(value) || {};
+        return {
+            ...runtimeContext,
+            memory: {
+                ...(runtimeContext.memory || {}),
+                enabled: false,
+                isTeamConversation: true,
+            },
         };
     }
     /**
@@ -8774,7 +9256,7 @@
             let toolCalls;
             try {
                 const remoteAgent = await getRemoteTeammateAgent(entry.teammate.url);
-                const prompt = buildTeammatePrompt(request);
+                const prompt = buildTeammatePrompt(request, createTeamConversationRuntimeContext(args[TOOL_RUNTIME_CONTEXT_ARGUMENT]));
                 const teammateResult = await remoteAgent.callChatModel(prompt);
                 response = teammateResult.content || '';
                 toolCalls =
@@ -9324,25 +9806,6 @@
      * Note: [💞] Ignore a discrepancy between file name and entity name
      */
 
-    /**
-     * @@@
-     *
-     * @private utility for commitments
-     */
-    function formatOptionalInstructionBlock(label, content) {
-        const trimmedContent = spaceTrim$1.spaceTrim(content);
-        if (!trimmedContent) {
-            return '';
-        }
-        return spaceTrim$1.spaceTrim((block) => `
-        - ${label}:
-            ${block(trimmedContent
-        .split(/\r?\n/)
-        .map((line) => `- ${line}`)
-        .join('\n'))}
-    `);
-    }
-
     /**
      * Client-side safe wrapper for sending emails.
      *
@@ -9536,8 +9999,8 @@
     /**
      * USE IMAGE GENERATOR commitment definition
      *
-     * The `USE IMAGE GENERATOR` commitment indicates that the agent should utilize an image generation tool
-     * to create images based on text prompts.
+     * The `USE IMAGE GENERATOR` commitment indicates that the agent can output
+     * markdown placeholders for UI-driven image generation.
      *
      * Example usage in agent source:
      *
@@ -9552,11 +10015,14 @@
         constructor(type = 'USE IMAGE GENERATOR') {
             super(type, ['USE IMAGE GENERATION', 'IMAGE GENERATOR', 'IMAGE GENERATION', 'USE IMAGE']);
         }
+        get requiresContent() {
+            return false;
+        }
         /**
          * Short one-line description of USE IMAGE GENERATOR.
          */
         get description() {
-            return 'Enable the agent to use an image generation tool for creating images from text prompts.';
+            return 'Enable the agent to output markdown image placeholders that the UI turns into generated images.';
         }
         /**
          * Icon for this commitment.
@@ -9571,21 +10037,21 @@
             return spaceTrim$1.spaceTrim(`
             # USE IMAGE GENERATOR
 
-            Enables the agent to use an image generation tool to create images based on text prompts.
+            Enables the agent to output markdown image placeholders that trigger image generation in the user interface.
 
             ## Key aspects
 
             - The content following \`USE IMAGE GENERATOR\` is an arbitrary text that the agent should know (e.g. style instructions or safety guidelines).
-            - The actual image generation is handled by the agent runtime using LLM execution tools.
-            - Allows the agent to generate visual content based on user requests.
-            - Returns the URL of the generated image.
+            - The agent does **not** call an image-generation tool directly.
+            - The agent inserts markdown notation: \`![alt](?image-prompt=...)\`.
+            - The user interface detects the notation and generates the image asynchronously.
 
             ## Examples
 
             \`\`\`book
             Visual Artist
 
-            PERSONA You are a creative visual artist who can generate images.
+            PERSONA You are a creative visual artist.
             USE IMAGE GENERATOR
             RULE Always describe the generated image to the user.
             \`\`\`
@@ -9595,80 +10061,28 @@
 
             PERSONA You are an interior designer who helps users visualize their space.
             USE IMAGE GENERATOR Professional interior design renders.
-            ACTION Generate a preview of the designed room.
+            ACTION Add one generated image placeholder whenever a user asks for a visual.
             \`\`\`
         `);
         }
         applyToAgentModelRequirements(requirements, content) {
-            // Get existing tools array or create new one
-            const existingTools = requirements.tools || [];
-            // Add 'generate_image' to tools if not already present
-            const updatedTools = existingTools.some((tool) => tool.name === 'generate_image')
-                ? existingTools
-                : [
-                    ...existingTools,
-                    {
-                        name: 'generate_image',
-                        description: spaceTrim$1.spaceTrim(`
-                        Generate an image from a text prompt.
-                        Use this tool when the user asks to create, draw, or generate an image.
-                        ${!content ? '' : `Style instructions / guidelines: ${content}`}
-                    `),
-                        parameters: {
-                            type: 'object',
-                            properties: {
-                                prompt: {
-                                    type: 'string',
-                                    description: 'The detailed description of the image to generate',
-                                },
-                            },
-                            required: ['prompt'],
-                        },
-                    },
-                ];
-            // Return requirements with updated tools and metadata
+            const extraInstructions = formatOptionalInstructionBlock('Image instructions', content);
             return this.appendToSystemMessage({
                 ...requirements,
-                tools: updatedTools,
                 _metadata: {
                     ...requirements._metadata,
                     useImageGenerator: content || true,
                 },
-            }, spaceTrim$1.spaceTrim(`
-                You have access to an image generator. Use it to create images based on user requests.
-                When you generate an image, you will receive a URL of the generated image.
-            `));
-        }
-        /**
-         * Gets human-readable titles for tool functions provided by this commitment.
-         */
-        getToolTitles() {
-            return {
-                generate_image: 'Generate image',
-            };
-        }
-        /**
-         * Gets the `generate_image` tool function implementation.
-         */
-        getToolFunctions() {
-            return {
-                async generate_image(args, ...extra) {
-                    console.log('!!!! [Tool] generate_image called', { args });
-                    const { prompt } = args;
-                    if (!prompt) {
-                        throw new Error('Image prompt is required');
-                    }
-                    const { llmTools } = extra[0] || {};
-                    if (!llmTools || !llmTools.callImageGenerationModel) {
-                        throw new Error('Image generation is not supported by the current model provider');
-                    }
-                    const result = await llmTools.callImageGenerationModel({
-                        content: prompt,
-                        modelName: 'dall-e-3', // Defaulting to dall-e-3, but this could be configurable
-                    });
-                    return result.content;
-                },
-            };
+            }, spaceTrim$1.spaceTrim((block) => `
+                    Image generation:
+                    - You do not generate images directly and you do not call any image tool.
+                    - When the user asks for an image, include markdown notation in your message:
+                      \`![<alt text>](?image-prompt=<prompt>)\`
+                    - Keep \`<alt text>\` short and descriptive.
+                    - Keep \`<prompt>\` detailed so the generated image matches the request.
+                    - You can include normal explanatory text before and after the notation.
+                    ${block(extraInstructions)}
+                `));
         }
     }
     /**
@@ -16168,6 +16582,7 @@
                 systemMessage: requirements.systemMessage + '\n\n' + exampleInteractionsContent,
             };
         }
+        requirements = await applyPendingInlineKnowledgeSources(requirements, options === null || options === void 0 ? void 0 : options.inlineKnowledgeSourceUploader);
         // Remove comment lines (lines starting with #) from the final system message
         // while preserving the original content with comments in metadata
         const cleanedSystemMessage = removeCommentsFromSystemMessage(requirements.systemMessage);
@@ -16176,6 +16591,54 @@
             systemMessage: cleanedSystemMessage,
         };
     }
+    /**
+     * @private Attempts to upload inline knowledge entries, falling back to legacy data URLs when the upload fails or is not configured.
+     */
+    async function applyPendingInlineKnowledgeSources(requirements, uploader) {
+        var _a;
+        const inlineSources = extractInlineKnowledgeSources(requirements._metadata);
+        if (inlineSources.length === 0) {
+            return requirements;
+        }
+        const knowledgeSources = [...((_a = requirements.knowledgeSources) !== null && _a !== void 0 ? _a : [])];
+        for (const inlineSource of inlineSources) {
+            const url = uploader
+                ? await uploadInlineKnowledgeSourceWithFallback(inlineSource, uploader)
+                : inlineKnowledgeSourceToDataUrl(inlineSource);
+            knowledgeSources.push(url);
+        }
+        return {
+            ...requirements,
+            knowledgeSources,
+            _metadata: stripInlineKnowledgeMetadata(requirements._metadata),
+        };
+    }
+    async function uploadInlineKnowledgeSourceWithFallback(inlineSource, uploader) {
+        try {
+            return await uploader(inlineSource);
+        }
+        catch (error) {
+            console.error('[inline-knowledge] Failed to upload inline source', {
+                filename: inlineSource.filename,
+                error,
+            });
+            return inlineKnowledgeSourceToDataUrl(inlineSource);
+        }
+    }
+    function extractInlineKnowledgeSources(metadata) {
+        if (!metadata) {
+            return [];
+        }
+        const value = metadata.inlineKnowledgeSources;
+        return Array.isArray(value) ? value : [];
+    }
+    function stripInlineKnowledgeMetadata(metadata) {
+        if (!metadata || !Object.prototype.hasOwnProperty.call(metadata, 'inlineKnowledgeSources')) {
+            return metadata;
+        }
+        const { inlineKnowledgeSources: _unusedInlineKnowledgeSources, ...rest } = metadata;
+        return Object.keys(rest).length > 0 ? rest : undefined;
+    }
     /**
      * Mocked security check for imported files
      *
@@ -17235,6 +17698,28 @@
         }));
     }
 
+    /**
+     * Builds a tool invocation script that injects hidden runtime context into tool args.
+     *
+     * @private utility of OpenAI tool execution wrappers
+     */
+    function buildToolInvocationScript(options) {
+        const { functionName, functionArgsExpression } = options;
+        return `
+        const args = ${functionArgsExpression};
+        const runtimeContextRaw =
+            typeof ${TOOL_RUNTIME_CONTEXT_PARAMETER} === 'undefined'
+                ? undefined
+                : ${TOOL_RUNTIME_CONTEXT_PARAMETER};
+
+        if (runtimeContextRaw !== undefined && args && typeof args === 'object' && !Array.isArray(args)) {
+            args.${TOOL_RUNTIME_CONTEXT_ARGUMENT} = runtimeContextRaw;
+        }
+
+        return await ${functionName}(args);
+    `;
+    }
+
     /**
      * Parses an OpenAI error message to identify which parameter is unsupported
      *
@@ -17588,10 +18073,10 @@
                                 const scriptTool = scriptTools[0]; // <- TODO: [🧠] Which script tool to use?
                                 functionResponse = await scriptTool.execute({
                                     scriptLanguage: 'javascript',
-                                    script: `
-                                    const args = ${functionArgs};
-                                    return await ${functionName}(args);
-                                `,
+                                    script: buildToolInvocationScript({
+                                        functionName,
+                                        functionArgsExpression: functionArgs,
+                                    }),
                                     parameters: prompt.parameters,
                                 });
                             }
@@ -19293,10 +19778,10 @@
                             try {
                                 return await scriptTool.execute({
                                     scriptLanguage: 'javascript',
-                                    script: `
-                                        const args = ${JSON.stringify(functionArgs)};
-                                        return await ${functionName}(args);
-                                    `,
+                                    script: buildToolInvocationScript({
+                                        functionName,
+                                        functionArgsExpression: JSON.stringify(functionArgs),
+                                    }),
                                     parameters: (_c = (_b = runContext === null || runContext === void 0 ? void 0 : runContext.context) === null || _b === void 0 ? void 0 : _b.parameters) !== null && _c !== void 0 ? _c : {},
                                 });
                             }
@@ -19749,10 +20234,10 @@
                                     const scriptTool = scriptTools[0]; // <- TODO: [🧠] Which script tool to use?
                                     functionResponse = await scriptTool.execute({
                                         scriptLanguage: 'javascript',
-                                        script: `
-                                        const args = ${JSON.stringify(functionArgs)};
-                                        return await ${functionName}(args);
-                                    `,
+                                        script: buildToolInvocationScript({
+                                            functionName,
+                                            functionArgsExpression: JSON.stringify(functionArgs),
+                                        }),
                                         parameters: prompt.parameters,
                                     });
                                     if (this.options.isVerbose) {
@@ -20968,6 +21453,20 @@
      * TODO: [🧠][😰]Agent is not working with the parameters, should it be?
      */
 
+    /**
+     * Keep-alive helpers used for streaming chat responses.
+     *
+     * These constants coordinate the signal sent by the Agents Server streaming
+     * endpoint and the parser in the SDK so we can distinguish between
+     * real content and occasional pings.
+     *
+     * @private internal streaming helper for Promptbook chat connections
+     */
+    const CHAT_STREAM_KEEP_ALIVE_TOKEN = 'STREAM_KEEP_ALIVE';
+    /**
+     * Note: [💞] Ignore a discrepancy between file name and entity name
+     */
+
     /**
      * Resolve a remote META IMAGE value into an absolute URL when possible.
      */
@@ -21042,7 +21541,9 @@
         static async connect(options) {
             var _a, _b, _c;
             const agentProfileUrl = `${options.agentUrl}/api/profile`;
-            const profileResponse = await fetch(agentProfileUrl);
+            const profileResponse = await fetch(agentProfileUrl, {
+                headers: attachClientVersionHeader(),
+            });
             // <- TODO: [🐱‍🚀] What about closed-source agents?
             // <- TODO: [🐱‍🚀] Maybe use promptbookFetch
             if (!profileResponse.ok) {
@@ -21143,6 +21644,7 @@
                 }
                 const response = await fetch(`${this.agentUrl}/api/voice`, {
                     method: 'POST',
+                    headers: attachClientVersionHeader(),
                     body: formData,
                 });
                 if (!response.ok) {
@@ -21172,13 +21674,14 @@
             const chatPrompt = prompt;
             const bookResponse = await fetch(`${this.agentUrl}/api/chat`, {
                 method: 'POST',
-                headers: {
+                headers: attachClientVersionHeader({
                     'Content-Type': 'application/json',
-                },
+                }),
                 body: JSON.stringify({
                     message: prompt.content,
                     thread: chatPrompt.thread,
                     attachments: chatPrompt.attachments,
+                    parameters: chatPrompt.parameters,
                 }),
             });
             // <- TODO: [🐱‍🚀] What about closed-source agents?
@@ -21260,6 +21763,9 @@
                             const lines = textChunk.split(/\r?\n/);
                             for (const line of lines) {
                                 const trimmedLine = line.trim();
+                                if (trimmedLine === CHAT_STREAM_KEEP_ALIVE_TOKEN) {
+                                    continue;
+                                }
                                 let isToolCallLine = false;
                                 if (trimmedLine.startsWith('{') && trimmedLine.endsWith('}')) {
                                     try {