@promptbook/core 0.112.0-62 → 0.112.0-63

package/umd/index.umd.js

@@ -27,7 +27,7 @@
      * @generated
      * @see https://github.com/webgptorg/promptbook
      */
-    const PROMPTBOOK_ENGINE_VERSION = '0.112.0-62';
+    const PROMPTBOOK_ENGINE_VERSION = '0.112.0-63';
     /**
      * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
      * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -12087,6 +12087,18 @@
     }
     // Note: [💞] Ignore a discrepancy between file name and entity name
 
+    /**
+     * Name of the tool used by agents to search configured `KNOWLEDGE` sources.
+     *
+     * @public exported from `@promptbook/core`
+     */
+    const KNOWLEDGE_SEARCH_TOOL_NAME = 'knowledge_search';
+    /**
+     * Title of the system-message section generated for `KNOWLEDGE` commitments.
+     *
+     * @private constant of `KnowledgeCommitmentDefinition`
+     */
+    const KNOWLEDGE_SEARCH_SYSTEM_SECTION_TITLE = 'Knowledge Search';
     /**
      * KNOWLEDGE commitment definition
      *
@@ -12208,9 +12220,17 @@
                 knowledgeInfoEntries.push(`Knowledge Source Inline: ${inlineSource.filename} (derived from inline content and processed for retrieval during chat)`);
             }
             if (knowledgeInfoEntries.length === 0) {
-                return nextRequirements;
+                return addKnowledgeSearchToolAndSystemSection(nextRequirements);
             }
-            return this.appendToSystemMessage(nextRequirements, knowledgeInfoEntries.join('\n'), '\n\n');
+            return addKnowledgeSearchToolAndSystemSection(nextRequirements);
+        }
+        /**
+         * Gets human-readable titles for tool functions provided by this commitment.
+         */
+        getToolTitles() {
+            return {
+                [KNOWLEDGE_SEARCH_TOOL_NAME]: 'Knowledge search',
+            };
         }
     }
     /**
@@ -12224,6 +12244,128 @@
         const significantText = contentWithoutUrls.replace(/[\s.,!?;:'"`()[\]{}<>/-]+/g, '');
         return significantText.length > 0;
     }
+    /**
+     * Adds the shared `knowledge_search` tool definition and the consolidated system-message section.
+     *
+     * @param requirements - Requirements after one `KNOWLEDGE` commitment was applied.
+     * @returns Requirements with the knowledge search instructions and tool definition.
+     *
+     * @private internal utility of `KnowledgeCommitmentDefinition`
+     */
+    function addKnowledgeSearchToolAndSystemSection(requirements) {
+        const nextRequirements = addKnowledgeSearchTool(requirements);
+        const section = createKnowledgeSearchSystemSection(nextRequirements);
+        const sectionHeader = `## ${KNOWLEDGE_SEARCH_SYSTEM_SECTION_TITLE}`;
+        if (nextRequirements.systemMessage.includes(sectionHeader)) {
+            return {
+                ...nextRequirements,
+                systemMessage: nextRequirements.systemMessage.replace(new RegExp(`## ${KNOWLEDGE_SEARCH_SYSTEM_SECTION_TITLE.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}[\\s\\S]*?(?=\\n\\n##|$)`), section),
+            };
+        }
+        return {
+            ...nextRequirements,
+            systemMessage: nextRequirements.systemMessage.trim()
+                ? `${nextRequirements.systemMessage}\n\n${section}`
+                : section,
+        };
+    }
+    /**
+     * Adds the `knowledge_search` model tool when it is not already present.
+     *
+     * @param requirements - Current model requirements.
+     * @returns Requirements with the tool definition available to the model.
+     *
+     * @private internal utility of `KnowledgeCommitmentDefinition`
+     */
+    function addKnowledgeSearchTool(requirements) {
+        const existingTools = requirements.tools || [];
+        if (existingTools.some((tool) => tool.name === KNOWLEDGE_SEARCH_TOOL_NAME)) {
+            return requirements;
+        }
+        return {
+            ...requirements,
+            tools: [
+                ...existingTools,
+                {
+                    name: KNOWLEDGE_SEARCH_TOOL_NAME,
+                    description: spacetrim.spaceTrim(`
+                    Search the agent's configured knowledge sources and return relevant excerpts with citation ids.
+                    Use this before answering questions that may depend on the agent's KNOWLEDGE commitments.
+                `),
+                    parameters: {
+                        type: 'object',
+                        properties: {
+                            query: {
+                                type: 'string',
+                                description: 'The natural-language search query for the knowledge base.',
+                            },
+                            limit: {
+                                type: 'integer',
+                                description: 'Maximum number of matching source excerpts to return.',
+                            },
+                        },
+                        required: ['query'],
+                    },
+                },
+            ],
+        };
+    }
+    /**
+     * Creates the model-facing system-message section for knowledge search.
+     *
+     * @param requirements - Current model requirements.
+     * @returns Markdown system-message section.
+     *
+     * @private internal utility of `KnowledgeCommitmentDefinition`
+     */
+    function createKnowledgeSearchSystemSection(requirements) {
+        const sourceEntries = createKnowledgeSourceSystemEntries(requirements);
+        const sourceList = sourceEntries.length > 0 ? sourceEntries.map((entry) => `-   ${entry}`).join('\n') : '-   None';
+        return spacetrim.spaceTrim(`
+        ## ${KNOWLEDGE_SEARCH_SYSTEM_SECTION_TITLE}
+
+        -   Use \`${KNOWLEDGE_SEARCH_TOOL_NAME}\` to search the configured knowledge sources before answering questions that depend on this agent's knowledge base.
+        -   Base source-backed factual answers on the returned excerpts.
+        -   When you use a returned excerpt, include its citation marker in the answer body, for example \`[0:0]\`.
+        -   If the search returns no relevant information, say that the knowledge base did not contain the answer instead of inventing it.
+
+        Configured knowledge sources:
+        ${sourceList}
+    `);
+    }
+    /**
+     * Builds a stable list of configured knowledge sources for system-message diagnostics.
+     *
+     * @param requirements - Current model requirements.
+     * @returns Human-readable source entries.
+     *
+     * @private internal utility of `KnowledgeCommitmentDefinition`
+     */
+    function createKnowledgeSourceSystemEntries(requirements) {
+        var _a;
+        const entries = [];
+        const seenEntries = new Set();
+        for (const source of requirements.knowledgeSources || []) {
+            const entry = `Source URL: ${source} (processed for retrieval during chat)`;
+            if (seenEntries.has(entry)) {
+                continue;
+            }
+            seenEntries.add(entry);
+            entries.push(entry);
+        }
+        const inlineSources = (((_a = requirements._metadata) === null || _a === void 0 ? void 0 : _a.inlineKnowledgeSources) || [])
+            .map((source) => source.filename)
+            .filter(Boolean);
+        for (const filename of inlineSources) {
+            const entry = `Knowledge Source Inline: ${filename} (Inline source: processed for retrieval during chat)`;
+            if (seenEntries.has(entry)) {
+                continue;
+            }
+            seenEntries.add(entry);
+            entries.push(entry);
+        }
+        return entries;
+    }
 
     /**
      * LANGUAGE commitment definition
@@ -19801,7 +19943,7 @@
         const runtimeContext = (readToolRuntimeContextFromToolArgs(args) ||
             {});
         const configuredCalendars = normalizeConfiguredCalendars$1((_a = runtimeContext.calendars) === null || _a === void 0 ? void 0 : _a.connections);
-        const calendarArgument = normalizeOptionalText$1(args.calendarUrl);
+        const calendarArgument = normalizeOptionalText$2(args.calendarUrl);
         let calendarReference = null;
         if (calendarArgument) {
             calendarReference = parseGoogleCalendarReference(calendarArgument);
@@ -19821,7 +19963,7 @@
         if (!calendarReference) {
             throw new Error('Calendar is required but was not resolved.');
         }
-        const accessToken = normalizeOptionalText$1((_b = runtimeContext.calendars) === null || _b === void 0 ? void 0 : _b.googleAccessToken) || '';
+        const accessToken = normalizeOptionalText$2((_b = runtimeContext.calendars) === null || _b === void 0 ? void 0 : _b.googleAccessToken) || '';
         if (!accessToken) {
             throw new CalendarWalletCredentialRequiredError({
                 calendarReference,
@@ -19854,7 +19996,7 @@
                 continue;
             }
             const calendar = rawCalendar;
-            const rawUrl = normalizeOptionalText$1(calendar.url);
+            const rawUrl = normalizeOptionalText$2(calendar.url);
             if (!rawUrl) {
                 continue;
             }
@@ -19905,7 +20047,7 @@
      *
      * @private function of resolveUseCalendarToolRuntimeOrWalletCredentialResult
      */
-    function normalizeOptionalText$1(value) {
+    function normalizeOptionalText$2(value) {
         if (typeof value !== 'string') {
             return undefined;
         }
@@ -19937,13 +20079,13 @@
             async [UseCalendarToolNames.listEvents](args) {
                 return withUseCalendarRuntime(args, async ({ calendarReference, accessToken }) => {
                     const query = {};
-                    if (normalizeOptionalText(args.timeMin)) {
+                    if (normalizeOptionalText$1(args.timeMin)) {
                         query.timeMin = args.timeMin.trim();
                     }
-                    if (normalizeOptionalText(args.timeMax)) {
+                    if (normalizeOptionalText$1(args.timeMax)) {
                         query.timeMax = args.timeMax.trim();
                     }
-                    if (normalizeOptionalText(args.query)) {
+                    if (normalizeOptionalText$1(args.query)) {
                         query.q = args.query.trim();
                     }
                     if (typeof args.maxResults === 'number' && Number.isFinite(args.maxResults) && args.maxResults > 0) {
@@ -19955,7 +20097,7 @@
                     if (args.orderBy === 'startTime' || args.orderBy === 'updated') {
                         query.orderBy = args.orderBy;
                     }
-                    if (normalizeOptionalText(args.timeZone)) {
+                    if (normalizeOptionalText$1(args.timeZone)) {
                         query.timeZone = args.timeZone.trim();
                     }
                     const payload = await callGoogleCalendarApi(accessToken, {
@@ -19993,11 +20135,11 @@
                 return withUseCalendarRuntime(args, async ({ calendarReference, accessToken }) => {
                     const requestBody = createGoogleCalendarEventPayload({
                         summary: normalizeRequiredText(args.summary, 'summary'),
-                        description: normalizeOptionalText(args.description),
-                        location: normalizeOptionalText(args.location),
+                        description: normalizeOptionalText$1(args.description),
+                        location: normalizeOptionalText$1(args.location),
                         start: normalizeRequiredText(args.start, 'start'),
                         end: normalizeRequiredText(args.end, 'end'),
-                        timeZone: normalizeOptionalText(args.timeZone),
+                        timeZone: normalizeOptionalText$1(args.timeZone),
                         attendees: normalizeAttendees(args.attendees),
                         reminderMinutes: normalizeReminderMinutes(args.reminderMinutes),
                     });
@@ -20019,12 +20161,12 @@
                 return withUseCalendarRuntime(args, async ({ calendarReference, accessToken }) => {
                     const eventId = normalizeRequiredText(args.eventId, 'eventId');
                     const requestBody = createGoogleCalendarEventPayload({
-                        summary: normalizeOptionalText(args.summary),
-                        description: normalizeOptionalText(args.description),
-                        location: normalizeOptionalText(args.location),
-                        start: normalizeOptionalText(args.start),
-                        end: normalizeOptionalText(args.end),
-                        timeZone: normalizeOptionalText(args.timeZone),
+                        summary: normalizeOptionalText$1(args.summary),
+                        description: normalizeOptionalText$1(args.description),
+                        location: normalizeOptionalText$1(args.location),
+                        start: normalizeOptionalText$1(args.start),
+                        end: normalizeOptionalText$1(args.end),
+                        timeZone: normalizeOptionalText$1(args.timeZone),
                         attendees: normalizeAttendees(args.attendees),
                         reminderMinutes: normalizeReminderMinutes(args.reminderMinutes),
                     });
@@ -20071,7 +20213,7 @@
                         path: `/calendars/${encodeGoogleCalendarId(calendarReference.calendarId)}/events/${encodeURIComponent(eventId)}`,
                     });
                     const existingAttendees = ((existingEvent === null || existingEvent === void 0 ? void 0 : existingEvent.attendees) || [])
-                        .map((attendee) => normalizeOptionalText(attendee.email))
+                        .map((attendee) => normalizeOptionalText$1(attendee.email))
                         .filter((email) => Boolean(email));
                     const mergedAttendees = [...new Set([...existingAttendees, ...guests])];
                     const payload = await callGoogleCalendarApi(accessToken, {
@@ -20119,7 +20261,7 @@
      * @private function of createUseCalendarToolFunctions
      */
     function normalizeRequiredText(value, fieldName) {
-        const normalizedValue = normalizeOptionalText(value);
+        const normalizedValue = normalizeOptionalText$1(value);
         if (!normalizedValue) {
             throw new Error(`Tool "${fieldName}" requires non-empty value.`);
         }
@@ -20130,7 +20272,7 @@
      *
      * @private function of createUseCalendarToolFunctions
      */
-    function normalizeOptionalText(value) {
+    function normalizeOptionalText$1(value) {
         if (typeof value !== 'string') {
             return undefined;
         }
@@ -24797,6 +24939,580 @@
     }
     // Note: [💞] Ignore a discrepancy between file name and entity name
 
+    /**
+     * Names of tools used by the WALLET commitment.
+     *
+     * @private constant of WalletCommitmentDefinition
+     */
+    const WalletToolNames = {
+        retrieve: 'retrieve_wallet_records',
+        store: 'store_wallet_record',
+        update: 'update_wallet_record',
+        delete: 'delete_wallet_record',
+        request: 'request_wallet_record',
+    };
+
+    /**
+     * Creates WALLET system-message instructions.
+     *
+     * @private function of WalletCommitmentDefinition
+     */
+    function createWalletSystemMessage(extraInstructions) {
+        return spacetrim.spaceTrim((block) => `
+            Wallet:
+            - Use "${WalletToolNames.retrieve}" before authenticated operations.
+            - Use "${WalletToolNames.store}" and "${WalletToolNames.update}" to maintain credentials.
+            - Use "${WalletToolNames.delete}" to remove invalid credentials.
+            - Use "${WalletToolNames.request}" to request missing credentials via UI popup.
+            - Scope records by user (\`isUserScoped\`) and/or by agent (\`isGlobal=false\`) as needed.
+            - Never expose raw credentials in chat responses.
+            ${block(extraInstructions)}
+        `);
+    }
+
+    /**
+     * Resolves disabled message for wallet runtime context.
+     *
+     * @private function of WalletCommitmentDefinition
+     */
+    function resolveWalletDisabledMessage(runtimeContext) {
+        if (runtimeContext.isPrivateMode) {
+            return 'Wallet is disabled because private mode is active.';
+        }
+        if (runtimeContext.isTeamConversation) {
+            return 'Wallet is disabled for TEAM conversations.';
+        }
+        if (!runtimeContext.enabled) {
+            return 'Wallet is disabled for unauthenticated users.';
+        }
+        return null;
+    }
+    /**
+     * Resolves runtime adapter for wallet tools or returns disabled payload when unavailable.
+     *
+     * @private function of WalletCommitmentDefinition
+     */
+    function getWalletToolRuntimeAdapterOrDisabledResult(action, runtimeContext) {
+        const disabledMessage = resolveWalletDisabledMessage(runtimeContext);
+        if (disabledMessage) {
+            return {
+                adapter: null,
+                disabledResult: {
+                    action,
+                    status: 'disabled',
+                    records: action === 'retrieve' ? [] : undefined,
+                    message: disabledMessage,
+                },
+            };
+        }
+        {
+            return {
+                adapter: null,
+                disabledResult: {
+                    action,
+                    status: 'disabled',
+                    records: action === 'retrieve' ? [] : undefined,
+                    message: 'Wallet runtime is not available in this environment.',
+                },
+            };
+        }
+    }
+
+    /**
+     * Parses store/update wallet payload.
+     *
+     * @private function of WalletCommitmentDefinition
+     */
+    function parseWalletPayload(args) {
+        const recordType = parseWalletRecordType(args.recordType);
+        return {
+            recordType,
+            service: parseWalletService(args.service),
+            key: parseWalletKey(args.key),
+            isUserScoped: args.isUserScoped === true,
+            isGlobal: args.isGlobal === true,
+            ...parseWalletSecrets({
+                recordType,
+                username: args.username,
+                password: args.password,
+                secret: args.secret,
+                cookies: args.cookies,
+            }),
+        };
+    }
+    /**
+     * Parses text argument and returns trimmed text when available.
+     *
+     * @private function of WalletCommitmentDefinition
+     */
+    function normalizeOptionalText(value) {
+        if (typeof value !== 'string') {
+            return undefined;
+        }
+        const trimmed = value.trim();
+        return trimmed || undefined;
+    }
+    /**
+     * Parses wallet service argument.
+     *
+     * @private function of WalletCommitmentDefinition
+     */
+    function parseWalletService(value) {
+        return (normalizeOptionalText(value) || 'generic').toLowerCase();
+    }
+    /**
+     * Parses wallet key argument.
+     *
+     * @private function of WalletCommitmentDefinition
+     */
+    function parseWalletKey(value) {
+        return normalizeOptionalText(value) || 'default';
+    }
+    /**
+     * Parses one wallet record id argument.
+     *
+     * @private function of WalletCommitmentDefinition
+     */
+    function parseWalletId(value) {
+        const walletId = normalizeOptionalText(value);
+        if (!walletId) {
+            throw new Error('Wallet id is required.');
+        }
+        return walletId;
+    }
+    /**
+     * Parses wallet record type.
+     *
+     * @private function of WalletCommitmentDefinition
+     */
+    function parseWalletRecordType(value, fallback) {
+        var _a;
+        const normalizedType = (_a = normalizeOptionalText(value)) === null || _a === void 0 ? void 0 : _a.toUpperCase();
+        if (normalizedType === 'USERNAME_PASSWORD') {
+            return 'USERNAME_PASSWORD';
+        }
+        if (normalizedType === 'SESSION_COOKIE') {
+            return 'SESSION_COOKIE';
+        }
+        if (normalizedType === 'ACCESS_TOKEN') {
+            return 'ACCESS_TOKEN';
+        }
+        if (fallback) {
+            return fallback;
+        }
+        throw new Error('Unsupported wallet recordType. Expected one of: USERNAME_PASSWORD, SESSION_COOKIE, ACCESS_TOKEN.');
+    }
+    /**
+     * Parses wallet secret fields according to record type.
+     *
+     * @private function of WalletCommitmentDefinition
+     */
+    function parseWalletSecrets(args) {
+        const username = normalizeOptionalText(args.username);
+        const password = normalizeOptionalText(args.password);
+        const secret = normalizeOptionalText(args.secret);
+        const cookies = normalizeOptionalText(args.cookies);
+        if (args.recordType === 'USERNAME_PASSWORD') {
+            if (!username || !password) {
+                throw new Error('Both username and password are required for USERNAME_PASSWORD.');
+            }
+            return { username, password };
+        }
+        if (args.recordType === 'SESSION_COOKIE') {
+            if (!cookies) {
+                throw new Error('Cookies are required for SESSION_COOKIE.');
+            }
+            return { cookies };
+        }
+        if (!secret) {
+            throw new Error('Secret is required for ACCESS_TOKEN.');
+        }
+        return { secret };
+    }
+    /**
+     * Collection of WALLET tool argument parsers.
+     *
+     * @private function of WalletCommitmentDefinition
+     */
+    const parseWalletToolArgs = {
+        /**
+         * Parses retrieve arguments.
+         */
+        retrieve(args) {
+            const limit = typeof args.limit === 'number' && Number.isFinite(args.limit) ? Math.floor(args.limit) : undefined;
+            return {
+                query: normalizeOptionalText(args.query),
+                recordType: normalizeOptionalText(args.recordType) ? parseWalletRecordType(args.recordType) : undefined,
+                service: normalizeOptionalText(args.service) ? parseWalletService(args.service) : undefined,
+                key: normalizeOptionalText(args.key) ? parseWalletKey(args.key) : undefined,
+                limit: limit && limit > 0 ? Math.min(limit, 20) : undefined,
+            };
+        },
+        /**
+         * Parses store payload.
+         */
+        store(args) {
+            return parseWalletPayload(args);
+        },
+        /**
+         * Parses update payload.
+         */
+        update(args) {
+            const walletId = parseWalletId(args.walletId);
+            const record = parseWalletPayload(args);
+            return {
+                ...record,
+                walletId,
+            };
+        },
+        /**
+         * Parses delete payload.
+         */
+        delete(args) {
+            return { walletId: parseWalletId(args.walletId) };
+        },
+        /**
+         * Parses request payload for user wallet input prompt.
+         */
+        request(args) {
+            return {
+                recordType: parseWalletRecordType(args.recordType, 'ACCESS_TOKEN'),
+                service: parseWalletService(args.service),
+                key: parseWalletKey(args.key),
+                message: normalizeOptionalText(args.message),
+                isUserScoped: args.isUserScoped === true,
+                isGlobal: args.isGlobal === true,
+            };
+        },
+    };
+
+    /**
+     * Resolves runtime context from hidden tool arguments.
+     *
+     * @private function of WalletCommitmentDefinition
+     */
+    function resolveWalletRuntimeContext(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,
+            isPrivateMode: (memoryContext === null || memoryContext === void 0 ? void 0 : memoryContext.isPrivateMode) === true,
+        };
+    }
+
+    /**
+     * Creates runtime wallet tool function implementations.
+     *
+     * @private function of WalletCommitmentDefinition
+     */
+    function createWalletToolFunctions() {
+        return {
+            async [WalletToolNames.retrieve](args) {
+                const runtimeContext = resolveWalletRuntimeContext(args);
+                const { adapter, disabledResult } = getWalletToolRuntimeAdapterOrDisabledResult('retrieve', runtimeContext);
+                if (!adapter || disabledResult) {
+                    return JSON.stringify(disabledResult);
+                }
+                try {
+                    const parsedArgs = parseWalletToolArgs.retrieve(args);
+                    const records = await adapter.retrieveWalletRecords(parsedArgs, runtimeContext);
+                    return JSON.stringify({
+                        action: 'retrieve',
+                        status: 'ok',
+                        query: parsedArgs.query,
+                        records,
+                    });
+                }
+                catch (error) {
+                    return JSON.stringify({
+                        action: 'retrieve',
+                        status: 'error',
+                        records: [],
+                        message: error instanceof Error ? error.message : String(error),
+                    });
+                }
+            },
+            async [WalletToolNames.store](args) {
+                const runtimeContext = resolveWalletRuntimeContext(args);
+                const { adapter, disabledResult } = getWalletToolRuntimeAdapterOrDisabledResult('store', runtimeContext);
+                if (!adapter || disabledResult) {
+                    return JSON.stringify(disabledResult);
+                }
+                try {
+                    const parsedArgs = parseWalletToolArgs.store(args);
+                    const record = await adapter.storeWalletRecord(parsedArgs, runtimeContext);
+                    return JSON.stringify({
+                        action: 'store',
+                        status: 'stored',
+                        record,
+                    });
+                }
+                catch (error) {
+                    return JSON.stringify({
+                        action: 'store',
+                        status: 'error',
+                        message: error instanceof Error ? error.message : String(error),
+                    });
+                }
+            },
+            async [WalletToolNames.update](args) {
+                const runtimeContext = resolveWalletRuntimeContext(args);
+                const { adapter, disabledResult } = getWalletToolRuntimeAdapterOrDisabledResult('update', runtimeContext);
+                if (!adapter || disabledResult) {
+                    return JSON.stringify(disabledResult);
+                }
+                try {
+                    const parsedArgs = parseWalletToolArgs.update(args);
+                    const record = await adapter.updateWalletRecord(parsedArgs, runtimeContext);
+                    return JSON.stringify({
+                        action: 'update',
+                        status: 'updated',
+                        record,
+                    });
+                }
+                catch (error) {
+                    return JSON.stringify({
+                        action: 'update',
+                        status: 'error',
+                        message: error instanceof Error ? error.message : String(error),
+                    });
+                }
+            },
+            async [WalletToolNames.delete](args) {
+                const runtimeContext = resolveWalletRuntimeContext(args);
+                const { adapter, disabledResult } = getWalletToolRuntimeAdapterOrDisabledResult('delete', runtimeContext);
+                if (!adapter || disabledResult) {
+                    return JSON.stringify(disabledResult);
+                }
+                try {
+                    const parsedArgs = parseWalletToolArgs.delete(args);
+                    const deleted = await adapter.deleteWalletRecord(parsedArgs, runtimeContext);
+                    return JSON.stringify({
+                        action: 'delete',
+                        status: 'deleted',
+                        walletId: deleted.id,
+                    });
+                }
+                catch (error) {
+                    return JSON.stringify({
+                        action: 'delete',
+                        status: 'error',
+                        message: error instanceof Error ? error.message : String(error),
+                    });
+                }
+            },
+            async [WalletToolNames.request](args) {
+                const runtimeContext = resolveWalletRuntimeContext(args);
+                const disabledMessage = resolveWalletDisabledMessage(runtimeContext);
+                if (disabledMessage) {
+                    return JSON.stringify({
+                        action: 'request',
+                        status: 'disabled',
+                        message: disabledMessage,
+                    });
+                }
+                const request = parseWalletToolArgs.request(args);
+                return JSON.stringify({
+                    action: 'request',
+                    status: 'requested',
+                    request,
+                    message: request.message ||
+                        `Request user to provide ${request.recordType} credentials for service "${request.service}".`,
+                });
+            },
+        };
+    }
+
+    /**
+     * Creates tool definitions required by WALLET commitment.
+     *
+     * @private function of WalletCommitmentDefinition
+     */
+    function createWalletTools(existingTools) {
+        const tools = [...(existingTools || [])];
+        addWalletToolIfMissing(tools, {
+            name: WalletToolNames.retrieve,
+            description: 'Retrieve wallet records relevant to the current task.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    query: { type: 'string', description: 'Optional text query used to filter wallet records.' },
+                    recordType: {
+                        type: 'string',
+                        description: 'Optional record type filter (USERNAME_PASSWORD, SESSION_COOKIE, ACCESS_TOKEN).',
+                    },
+                    service: { type: 'string', description: 'Optional service filter, for example github.' },
+                    key: { type: 'string', description: 'Optional wallet key filter.' },
+                    limit: { type: 'integer', description: 'Optional maximum number of records (default 5, max 20).' },
+                },
+                required: [],
+            },
+        });
+        addWalletToolIfMissing(tools, {
+            name: WalletToolNames.store,
+            description: 'Store one wallet record.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    recordType: {
+                        type: 'string',
+                        description: 'Record type: USERNAME_PASSWORD, SESSION_COOKIE, ACCESS_TOKEN.',
+                    },
+                    service: { type: 'string', description: 'Service identifier, for example github.' },
+                    key: { type: 'string', description: 'Logical credential key.' },
+                    username: { type: 'string', description: 'Username for USERNAME_PASSWORD.' },
+                    password: { type: 'string', description: 'Password for USERNAME_PASSWORD.' },
+                    secret: { type: 'string', description: 'Token/API key for ACCESS_TOKEN.' },
+                    cookies: { type: 'string', description: 'Cookie header/json for SESSION_COOKIE.' },
+                    isUserScoped: { type: 'boolean', description: 'Set true to scope this record to current user.' },
+                    isGlobal: { type: 'boolean', description: 'Set true to make this record global.' },
+                },
+                required: ['recordType', 'service'],
+            },
+        });
+        addWalletToolIfMissing(tools, {
+            name: WalletToolNames.update,
+            description: 'Update one existing wallet record.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    walletId: { type: 'string', description: 'Wallet record id to update.' },
+                    recordType: {
+                        type: 'string',
+                        description: 'Record type: USERNAME_PASSWORD, SESSION_COOKIE, ACCESS_TOKEN.',
+                    },
+                    service: { type: 'string', description: 'Service identifier, for example github.' },
+                    key: { type: 'string', description: 'Logical credential key.' },
+                    username: { type: 'string', description: 'Username for USERNAME_PASSWORD.' },
+                    password: { type: 'string', description: 'Password for USERNAME_PASSWORD.' },
+                    secret: { type: 'string', description: 'Token/API key for ACCESS_TOKEN.' },
+                    cookies: { type: 'string', description: 'Cookie header/json for SESSION_COOKIE.' },
+                    isUserScoped: { type: 'boolean', description: 'Set true to scope this record to current user.' },
+                    isGlobal: { type: 'boolean', description: 'Set true to make this record global.' },
+                },
+                required: ['walletId', 'recordType', 'service'],
+            },
+        });
+        addWalletToolIfMissing(tools, {
+            name: WalletToolNames.delete,
+            description: 'Delete one wallet record.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    walletId: { type: 'string', description: 'Wallet record id to delete.' },
+                },
+                required: ['walletId'],
+            },
+        });
+        addWalletToolIfMissing(tools, {
+            name: WalletToolNames.request,
+            description: 'Request missing credential from user via popup.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    recordType: {
+                        type: 'string',
+                        description: 'Requested record type: USERNAME_PASSWORD, SESSION_COOKIE, ACCESS_TOKEN.',
+                    },
+                    service: { type: 'string', description: 'Service identifier.' },
+                    key: { type: 'string', description: 'Logical credential key.' },
+                    message: { type: 'string', description: 'Optional UI message for user.' },
+                    isUserScoped: {
+                        type: 'boolean',
+                        description: 'Set true when record should be scoped to current user.',
+                    },
+                    isGlobal: { type: 'boolean', description: 'Set true when record should be global.' },
+                },
+                required: [],
+            },
+        });
+        return tools;
+    }
+    /**
+     * Registers one wallet tool when missing in current tool list.
+     *
+     * @private function of WalletCommitmentDefinition
+     */
+    function addWalletToolIfMissing(tools, tool) {
+        if (!tools.some((existingTool) => existingTool.name === tool.name)) {
+            tools.push(tool);
+        }
+    }
+
+    /**
+     * Gets markdown documentation for WALLET commitment.
+     *
+     * @private function of WalletCommitmentDefinition
+     */
+    function getWalletCommitmentDocumentation(type) {
+        return spacetrim.spaceTrim(`
+        # ${type}
+
+        Enables private credential storage for tokens, usernames/passwords, and session cookies.
+    `);
+    }
+
+    /**
+     * Gets human-readable titles for WALLET tool functions.
+     *
+     * @private function of WalletCommitmentDefinition
+     */
+    function getWalletToolTitles() {
+        return {
+            [WalletToolNames.retrieve]: 'Wallet',
+            [WalletToolNames.store]: 'Store wallet record',
+            [WalletToolNames.update]: 'Update wallet record',
+            [WalletToolNames.delete]: 'Delete wallet record',
+            [WalletToolNames.request]: 'Request wallet record',
+        };
+    }
+
+    /**
+     * WALLET commitment definition.
+     *
+     * @private [🪔] Maybe export the commitments through some package
+     */
+    class WalletCommitmentDefinition extends BaseCommitmentDefinition {
+        constructor(type = 'WALLET') {
+            super(type);
+        }
+        get requiresContent() {
+            return false;
+        }
+        get description() {
+            return 'Enable persistent private credential storage (tokens, logins, cookies) scoped per agent or globally.';
+        }
+        get icon() {
+            return '👛';
+        }
+        get documentation() {
+            return getWalletCommitmentDocumentation(this.type);
+        }
+        applyToAgentModelRequirements(requirements, content) {
+            const extraInstructions = formatOptionalInstructionBlock('Wallet instructions', content);
+            return this.appendToSystemMessage({
+                ...requirements,
+                tools: createWalletTools(requirements.tools),
+                _metadata: {
+                    ...requirements._metadata,
+                    useWallet: content || true,
+                },
+            }, createWalletSystemMessage(extraInstructions));
+        }
+        getToolTitles() {
+            return getWalletToolTitles();
+        }
+        getToolFunctions() {
+            return createWalletToolFunctions();
+        }
+    }
+    // Note: [💞] Ignore a discrepancy between file name and entity name
+
     /**
      * `WRITING RULES` commitment definition.
      *
@@ -25071,6 +25787,8 @@
         new MessageSuffixCommitmentDefinition(),
         new MessageCommitmentDefinition('MESSAGE'),
         new MessageCommitmentDefinition('MESSAGES'),
+        new WalletCommitmentDefinition('WALLET'),
+        new WalletCommitmentDefinition('WALLETS'),
         new ScenarioCommitmentDefinition('SCENARIO'),
         new ScenarioCommitmentDefinition('SCENARIOS'),
         new DeleteCommitmentDefinition('DELETE'),
@@ -25909,6 +26627,12 @@
         ['GOAL', 'GOAL'],
         ['GOALS', 'GOAL'],
     ]);
+    /**
+     * Legacy commitments that should be parsed for compatibility but ignored by the model-requirements pipeline.
+     *
+     * @private internal constant of `filterCommitmentsForAgentModelRequirements`
+     */
+    const IGNORED_COMMITMENT_TYPES = new Set(['WALLET', 'WALLETS']);
     /**
      * Applies the commitment filtering rules used before commitment definitions are executed.
      *
@@ -25957,6 +26681,9 @@
     function filterDeletedCommitments(commitments) {
         const filteredCommitments = [];
         for (const commitment of commitments) {
+            if (isIgnoredCommitmentType(commitment.type)) {
+                continue;
+            }
             if (!isDeleteCommitmentType(commitment.type)) {
                 filteredCommitments.push(commitment);
                 continue;
@@ -25987,6 +26714,17 @@
     function isDeleteCommitmentType(commitmentType) {
         return DELETE_COMMITMENT_TYPES.has(commitmentType);
     }
+    /**
+     * Checks whether a parsed commitment is intentionally ignored by the current model compiler.
+     *
+     * @param commitmentType - Commitment type to check.
+     * @returns `true` when the commitment should not affect model requirements.
+     *
+     * @private internal utility of `filterDeletedCommitments`
+     */
+    function isIgnoredCommitmentType(commitmentType) {
+        return IGNORED_COMMITMENT_TYPES.has(commitmentType);
+    }
     /**
      * Extracts normalized parameter names used for DELETE-like invalidation matching.
      *
@@ -26585,7 +27323,6 @@
         if (isVoidPseudoAgentReference(reference)) {
             label = VOID_PSEUDO_AGENT_REFERENCE; // <- {Void} label
             iconName = 'ShieldAlert';
-            return null; // <- Note: Do not show `{Void}` in capabilities, it's only used for internal logic
         }
         return {
             type: 'inheritance',
@@ -27642,11 +28379,11 @@
      */
     const IMPORTANT_COMMITMENT_TYPE_SORT_ORDER = new Map([
         ['GOAL', 0],
-        ['GOALS', 1],
-        ['RULE', 2],
-        ['RULES', 3],
-        ['KNOWLEDGE', 4],
-        ['TEAM', 5],
+        ['RULE', 1],
+        ['KNOWLEDGE', 2],
+        ['TEAM', 3],
+        ['GOALS', 4],
+        ['RULES', 5],
     ]);
     /**
      * Sort rank used when unfinished, low-level, and deprecated commitments should be grouped last.
@@ -27774,6 +28511,11 @@
             isUnfinishedLast: true,
             isLowLevelLast: true,
         })) {
+            const existingGroup = findExistingCommitmentGroup(groupedCommitments, commitment);
+            if (existingGroup) {
+                existingGroup.aliases.push(commitment.type);
+                continue;
+            }
             const lastGroup = groupedCommitments[groupedCommitments.length - 1];
             // Check if we should group with the previous item
             let shouldGroup = false;
@@ -27808,6 +28550,22 @@
         }
         return $deepFreeze(groupedCommitments);
     }
+    /**
+     * Finds an existing group for aliases that were separated from their primary commitment by priority sorting.
+     *
+     * @param groupedCommitments - Groups collected so far.
+     * @param commitment - Commitment definition that may be an alias of an earlier group.
+     * @returns Existing alias group or `null` when a new group should be created.
+     *
+     * @private internal utility of `getGroupedCommitmentDefinitions`
+     */
+    function findExistingCommitmentGroup(groupedCommitments, commitment) {
+        if (commitment instanceof NotYetImplementedCommitmentDefinition) {
+            return null;
+        }
+        return (groupedCommitments.find((group) => !(group.primary instanceof NotYetImplementedCommitmentDefinition) &&
+            group.primary.constructor === commitment.constructor) || null);
+    }
 
     /**
      * Checks if a commitment type is supported
@@ -36811,8 +37569,8 @@
          * Prepares an AgentKit agent with optional knowledge sources and tool definitions.
          */
         async prepareAgentKitAgent(options) {
-            var _a, _b, _c;
-            const { name, instructions, knowledgeSources, tools, nativeAgentKitTools, vectorStoreId: cachedVectorStoreId, storeAsPrepared, } = options;
+            var _a, _b;
+            const { name, instructions, knowledgeSources, tools, vectorStoreId: cachedVectorStoreId, storeAsPrepared, } = options;
             await this.ensureAgentKitDefaults();
             if (this.options.isVerbose) {
                 console.info('[🤰]', 'Preparing OpenAI AgentKit agent', {
@@ -36820,11 +37578,10 @@
                     instructionsLength: instructions.length,
                     knowledgeSourcesCount: (_a = knowledgeSources === null || knowledgeSources === void 0 ? void 0 : knowledgeSources.length) !== null && _a !== void 0 ? _a : 0,
                     toolsCount: (_b = tools === null || tools === void 0 ? void 0 : tools.length) !== null && _b !== void 0 ? _b : 0,
-                    nativeAgentKitToolsCount: (_c = nativeAgentKitTools === null || nativeAgentKitTools === void 0 ? void 0 : nativeAgentKitTools.length) !== null && _c !== void 0 ? _c : 0,
                 });
             }
             let vectorStoreId = cachedVectorStoreId;
-            if (!vectorStoreId && knowledgeSources && knowledgeSources.length > 0) {
+            if (this.isNativeKnowledgeSearchEnabled && !vectorStoreId && knowledgeSources && knowledgeSources.length > 0) {
                 const vectorStoreResult = await this.createVectorStoreWithKnowledgeSources({
                     client: await this.getClient(),
                     name,
@@ -36833,13 +37590,19 @@
                 });
                 vectorStoreId = vectorStoreResult.vectorStoreId;
             }
-            else if (vectorStoreId && this.options.isVerbose) {
+            else if (this.isNativeKnowledgeSearchEnabled && vectorStoreId && this.options.isVerbose) {
                 console.info('[🤰]', 'Using cached vector store for AgentKit agent', {
                     name,
                     vectorStoreId,
                 });
             }
-            const agentKitTools = this.buildAgentKitTools({ tools, nativeAgentKitTools, vectorStoreId });
+            if (!this.isNativeKnowledgeSearchEnabled) {
+                vectorStoreId = undefined;
+            }
+            const agentKitTools = this.buildAgentKitTools({
+                tools,
+                vectorStoreId,
+            });
             const openAiAgentKitAgent = new agents.Agent({
                 name,
                 model: this.agentKitModelName,
@@ -36858,7 +37621,7 @@
                     name,
                     model: this.agentKitModelName,
                     toolCount: agentKitTools.length,
-                    hasVectorStore: Boolean(vectorStoreId),
+                    hasVectorStore: this.isNativeKnowledgeSearchEnabled && Boolean(vectorStoreId),
                 });
             }
             return preparedAgent;
@@ -36878,14 +37641,11 @@
          * Builds the tool list for AgentKit, including hosted file search when applicable.
          */
         buildAgentKitTools(options) {
-            const { tools, nativeAgentKitTools, vectorStoreId } = options;
+            const { tools, vectorStoreId } = options;
             const agentKitTools = [];
             if (vectorStoreId) {
                 agentKitTools.push(agents.fileSearchTool(vectorStoreId));
             }
-            if (nativeAgentKitTools && nativeAgentKitTools.length > 0) {
-                agentKitTools.push(...nativeAgentKitTools);
-            }
             if (tools && tools.length > 0) {
                 let scriptTools = null;
                 for (const toolDefinition of tools) {
@@ -37360,6 +38120,12 @@
         get agentKitOptions() {
             return this.options;
         }
+        /**
+         * Returns true when hosted OpenAI vector-store search should back `knowledgeSources`.
+         */
+        get isNativeKnowledgeSearchEnabled() {
+            return this.agentKitOptions.isNativeKnowledgeSearchEnabled !== false;
+        }
         /**
          * Discriminant for type guards.
          */
@@ -41883,7 +42649,7 @@
      */
     async function prepareSdkTranspilerContext(book, options) {
         const { agentName } = await parseAgentSource(book);
-        const modelRequirements = await createAgentModelRequirements(book, undefined, undefined, undefined, {
+        const rawModelRequirements = await createAgentModelRequirements(book, undefined, undefined, undefined, {
             agentReferenceResolver: options === null || options === void 0 ? void 0 : options.agentReferenceResolver,
             inlineKnowledgeSourceUploader: options === null || options === void 0 ? void 0 : options.inlineKnowledgeSourceUploader,
             teammateProfileResolver: options === null || options === void 0 ? void 0 : options.teammateProfileResolver,
@@ -41893,7 +42659,12 @@
         const knowledgeContent = knowledgeCommitments.map((commitment) => commitment.content.trim());
         const directKnowledge = knowledgeContent.filter((content) => !isKnowledgeSourceUrl(content));
         const knowledgeSources = knowledgeContent.filter((content) => isKnowledgeSourceUrl(content));
-        const isKnowledgeHandledWithRetrieval = directKnowledge.join('\n').length > SDK_TRANSPILER_KNOWLEDGE_THRESHOLD || knowledgeSources.length > 0;
+        const isKnowledgeHandledWithRetrieval = directKnowledge.join('\n').length > SDK_TRANSPILER_KNOWLEDGE_THRESHOLD ||
+            knowledgeSources.length > 0 ||
+            knowledgeCommitments.length > 0;
+        const modelRequirements = normalizeSdkTranspilerModelRequirements(rawModelRequirements, {
+            isKnowledgeHandledWithRetrieval,
+        });
         const transpiledTeam = createTranspiledTeamExportForContext({
             agentName,
             agentSource: book,
@@ -41911,6 +42682,36 @@
             transpiledTeam,
         };
     }
+    /**
+     * Removes the runtime-only knowledge-search tool from SDK harnesses that provide
+     * their own generated retrieval scaffold.
+     *
+     * @param modelRequirements - Raw compiled model requirements.
+     * @param options - Knowledge handling mode selected for the generated harness.
+     * @returns Model requirements safe to embed into a standalone SDK export.
+     */
+    function normalizeSdkTranspilerModelRequirements(modelRequirements, options) {
+        var _a;
+        if (!options.isKnowledgeHandledWithRetrieval) {
+            return modelRequirements;
+        }
+        const tools = (_a = modelRequirements.tools) === null || _a === void 0 ? void 0 : _a.filter((tool) => tool.name !== KNOWLEDGE_SEARCH_TOOL_NAME);
+        return {
+            ...modelRequirements,
+            systemMessage: removeKnowledgeSearchSystemSection(modelRequirements.systemMessage),
+            ...(tools ? { tools } : {}),
+        };
+    }
+    /**
+     * Removes the generated `## Knowledge Search` instructions from SDK exports
+     * that answer with the transpiler's native retrieval scaffold instead.
+     *
+     * @param systemMessage - Raw system message from compiled model requirements.
+     * @returns System message without the runtime-only knowledge-search section.
+     */
+    function removeKnowledgeSearchSystemSection(systemMessage) {
+        return systemMessage.replace(/(?:^|\n\n)## Knowledge Search[\s\S]*?(?=\n\n##|$)/, '').trim();
+    }
     /**
      * Detects whether one knowledge commitment points to a URL instead of inline text.
      *
@@ -44654,6 +45455,7 @@
     exports.GenericFormfactorDefinition = GenericFormfactorDefinition;
     exports.HTTP_STATUS_CODES = HTTP_STATUS_CODES;
     exports.ImageGeneratorFormfactorDefinition = ImageGeneratorFormfactorDefinition;
+    exports.KNOWLEDGE_SEARCH_TOOL_NAME = KNOWLEDGE_SEARCH_TOOL_NAME;
     exports.KnowledgeScrapeError = KnowledgeScrapeError;
     exports.LIMITS = LIMITS;
     exports.LimitReachedError = LimitReachedError;