@promptbook/wizard 0.110.0-9 → 0.111.0-0

package/esm/index.es.js

@@ -38,7 +38,7 @@ const BOOK_LANGUAGE_VERSION = '2.0.0';
  * @generated
  * @see https://github.com/webgptorg/promptbook
  */
-const PROMPTBOOK_ENGINE_VERSION = '0.110.0-9';
+const PROMPTBOOK_ENGINE_VERSION = '0.111.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
@@ -6567,6 +6567,36 @@ function prompt(strings, ...values) {
  * 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 Node.js environment
  *
@@ -8675,6 +8705,83 @@ function mapToolsToOpenAi(tools) {
     }));
 }
 
+/**
+ * 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
+ */
+
+/**
+ * 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
  *
@@ -9028,10 +9135,10 @@ class OpenAiCompatibleExecutionTools {
                             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,
                             });
                         }
@@ -10213,28 +10320,14 @@ class OpenAiExecutionTools extends OpenAiCompatibleExecutionTools {
     }
 }
 
-/**
- * @@@
- *
- * @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/);
@@ -10247,9 +10340,7 @@ function getFirstNonEmptyLine(content) {
     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);
@@ -10260,22 +10351,18 @@ function deriveBaseFilename(content) {
     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,
     };
 }
 /**
@@ -10286,10 +10373,18 @@ function createInlineKnowledgeSourceFile(content) {
 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)) {
@@ -11331,10 +11426,10 @@ class OpenAiAssistantExecutionTools extends OpenAiVectorStoreHandler {
                                 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) {
@@ -18464,6 +18559,7 @@ class KnowledgeCommitmentDefinition extends BaseCommitmentDefinition {
         `);
     }
     applyToAgentModelRequirements(requirements, content) {
+        var _a;
         const trimmedContent = content.trim();
         if (!trimmedContent) {
             return requirements;
@@ -18484,9 +18580,13 @@ class KnowledgeCommitmentDefinition extends BaseCommitmentDefinition {
         }
         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');
@@ -18568,6 +18668,182 @@ class LanguageCommitmentDefinition extends BaseCommitmentDefinition {
  * Note: [💞] Ignore a discrepancy between file name and entity name
  */
 
+/**
+ * @@@
+ *
+ * @private utility for commitments
+ */
+function formatOptionalInstructionBlock(label, content) {
+    const trimmedContent = spaceTrim$1(content);
+    if (!trimmedContent) {
+        return '';
+    }
+    return spaceTrim$1((block) => `
+        - ${label}:
+            ${block(trimmedContent
+        .split(/\r?\n/)
+        .map((line) => `- ${line}`)
+        .join('\n'))}
+    `);
+}
+
+/**
+ * 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
  *
@@ -18589,6 +18865,9 @@ class MemoryCommitmentDefinition extends BaseCommitmentDefinition {
     constructor(type = 'MEMORY') {
         super(type);
     }
+    get requiresContent() {
+        return false;
+    }
     /**
      * Short one-line description of MEMORY.
      */
@@ -18608,21 +18887,14 @@ class MemoryCommitmentDefinition extends BaseCommitmentDefinition {
         return spaceTrim$1(`
             # ${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
 
@@ -18630,10 +18902,7 @@ class MemoryCommitmentDefinition extends BaseCommitmentDefinition {
             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
             \`\`\`
 
@@ -18641,10 +18910,7 @@ class MemoryCommitmentDefinition extends BaseCommitmentDefinition {
             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
             \`\`\`
 
@@ -18652,23 +18918,245 @@ class MemoryCommitmentDefinition extends BaseCommitmentDefinition {
             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(`
+                    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(`
+                    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(`
+                    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(`
+                    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((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);
+                }
+            },
+        };
     }
 }
 /**
@@ -20654,7 +21142,8 @@ class TeamCommitmentDefinition extends BaseCommitmentDefinition {
         if (!trimmedContent) {
             return requirements;
         }
-        const teammates = parseTeamCommitmentContent(trimmedContent, { strict: true });
+        // Keep TEAM resilient: unresolved/malformed teammate entries are skipped, valid ones are still registered.
+        const teammates = parseTeamCommitmentContent(trimmedContent, { strict: false });
         if (teammates.length === 0) {
             return requirements;
         }
@@ -20780,14 +21269,30 @@ function buildTeammateRequest(message, context) {
 /**
  * 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,
+        },
     };
 }
 /**
@@ -20831,7 +21336,7 @@ function createTeamToolFunction(entry) {
         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 =
@@ -21381,25 +21886,6 @@ class UseBrowserCommitmentDefinition extends BaseCommitmentDefinition {
  * Note: [💞] Ignore a discrepancy between file name and entity name
  */
 
-/**
- * @@@
- *
- * @private utility for commitments
- */
-function formatOptionalInstructionBlock(label, content) {
-    const trimmedContent = spaceTrim$1(content);
-    if (!trimmedContent) {
-        return '';
-    }
-    return spaceTrim$1((block) => `
-        - ${label}:
-            ${block(trimmedContent
-        .split(/\r?\n/)
-        .map((line) => `- ${line}`)
-        .join('\n'))}
-    `);
-}
-
 /**
  * Client-side safe wrapper for sending emails.
  *
@@ -22713,14 +23199,42 @@ function removeCommentsFromSystemMessage(systemMessage) {
 }
 
 /**
- * Creates agent model requirements using the new commitment system
+ * Creates agent model requirements using the new commitment system.
+ *
  * This function uses a reduce-like pattern where each commitment applies its changes
- * to build the final requirements starting from a basic empty model
+ * to build the final requirements starting from a basic empty model.
  *
- * @public exported from `@promptbook/core`
+ * @param agentSource - Agent source book to parse.
+ * @param modelName - Optional override for the agent model name.
+ * @param options - Additional options such as the agent reference resolver.
+ *
+ * @private @@@
  */
-async function createAgentModelRequirementsWithCommitments(agentSource, modelName) {
+const COMMITMENTS_WITH_AGENT_REFERENCES = new Set(['FROM', 'IMPORT', 'IMPORTS', 'TEAM']);
+/**
+ * Returns a safe fallback content when a resolver fails to transform a reference commitment.
+ *
+ * @param commitmentType - Commitment being resolved.
+ * @param originalContent - Original unresolved commitment content.
+ * @returns Fallback content that keeps requirement creation resilient.
+ */
+function getSafeReferenceCommitmentFallback(commitmentType, originalContent) {
+    if (commitmentType === 'FROM') {
+        return 'VOID';
+    }
+    if (commitmentType === 'IMPORT' || commitmentType === 'IMPORTS' || commitmentType === 'TEAM') {
+        return '';
+    }
+    return originalContent;
+}
+/**
+ * @@@
+ *
+ * @private @@@
+ */
+async function createAgentModelRequirementsWithCommitments(agentSource, modelName, options) {
     var _a;
+    const agentReferenceResolver = options === null || options === void 0 ? void 0 : options.agentReferenceResolver;
     // Parse the agent source to extract commitments
     const parseResult = parseAgentSourceWithCommitments(agentSource);
     // Apply DELETE filtering: remove prior commitments tagged by parameters targeted by DELETE/CANCEL/DISCARD/REMOVE
@@ -22772,6 +23286,17 @@ async function createAgentModelRequirementsWithCommitments(agentSource, modelNam
     // Apply each commitment in order using reduce-like pattern
     for (let i = 0; i < filteredCommitments.length; i++) {
         const commitment = filteredCommitments[i];
+        const isReferenceCommitment = Boolean(agentReferenceResolver && COMMITMENTS_WITH_AGENT_REFERENCES.has(commitment.type));
+        let commitmentContent = commitment.content;
+        if (isReferenceCommitment && agentReferenceResolver) {
+            try {
+                commitmentContent = await agentReferenceResolver.resolveCommitmentContent(commitment.type, commitment.content);
+            }
+            catch (error) {
+                console.warn(`Failed to resolve commitment references for ${commitment.type}, falling back to safe defaults:`, error);
+                commitmentContent = getSafeReferenceCommitmentFallback(commitment.type, commitment.content);
+            }
+        }
         // CLOSED commitment should work only if its the last commitment in the book
         if (commitment.type === 'CLOSED' && i !== filteredCommitments.length - 1) {
             continue;
@@ -22779,7 +23304,7 @@ async function createAgentModelRequirementsWithCommitments(agentSource, modelNam
         const definition = getCommitmentDefinition(commitment.type);
         if (definition) {
             try {
-                requirements = definition.applyToAgentModelRequirements(requirements, commitment.content);
+                requirements = definition.applyToAgentModelRequirements(requirements, commitmentContent);
             }
             catch (error) {
                 console.warn(`Failed to apply commitment ${commitment.type}:`, error);
@@ -22887,6 +23412,7 @@ async function createAgentModelRequirementsWithCommitments(agentSource, modelNam
             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);
@@ -22895,6 +23421,54 @@ async function createAgentModelRequirementsWithCommitments(agentSource, modelNam
         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
  *
@@ -23238,23 +23812,28 @@ function normalizeSeparator(content) {
  */
 
 /**
- * Creates model requirements for an agent based on its source
+ * Creates model requirements for an agent based on its source.
  *
  * There are 2 similar functions:
  * - `parseAgentSource` which is a lightweight parser for agent source, it parses basic information and its purpose is to be quick and synchronous. The commitments there are hardcoded.
  * - `createAgentModelRequirements` which is an asynchronous function that creates model requirements it applies each commitment one by one and works asynchronous.
  *
+ * @param agentSource - Book describing the agent.
+ * @param modelName - Optional override for the agent's model.
+ * @param availableModels - Models that could fulfill the agent.
+ * @param llmTools - Execution tools used when selecting a best model.
+ * @param options - Optional hooks such as the agent reference resolver.
  * @public exported from `@promptbook/core`
  */
-async function createAgentModelRequirements(agentSource, modelName, availableModels, llmTools) {
+async function createAgentModelRequirements(agentSource, modelName, availableModels, llmTools, options) {
     // If availableModels are provided and no specific modelName is given,
     // use preparePersona to select the best model
     if (availableModels && !modelName && llmTools) {
         const selectedModelName = await selectBestModelUsingPersona(agentSource, llmTools);
-        return createAgentModelRequirementsWithCommitments(agentSource, selectedModelName);
+        return createAgentModelRequirementsWithCommitments(agentSource, selectedModelName, options);
     }
     // Use the new commitment-based system with provided or default model
-    return createAgentModelRequirementsWithCommitments(agentSource, modelName);
+    return createAgentModelRequirementsWithCommitments(agentSource, modelName, options);
 }
 /**
  * Selects the best model using the preparePersona function
@@ -30054,10 +30633,10 @@ class OpenAiAgentKitExecutionTools extends OpenAiVectorStoreHandler {
                         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 : {},
                             });
                         }
@@ -31088,6 +31667,20 @@ async function _Agent_selfLearnTeacher(prompt, result) {
  * 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.
  */
@@ -31162,7 +31755,9 @@ class RemoteAgent extends Agent {
     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) {
@@ -31263,6 +31858,7 @@ class RemoteAgent extends Agent {
             }
             const response = await fetch(`${this.agentUrl}/api/voice`, {
                 method: 'POST',
+                headers: attachClientVersionHeader(),
                 body: formData,
             });
             if (!response.ok) {
@@ -31292,13 +31888,14 @@ class RemoteAgent extends Agent {
         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?
@@ -31380,6 +31977,9 @@ class RemoteAgent extends Agent {
                         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 {