@promptbook/wizard 0.112.0-62 → 0.112.0-63

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.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
@@ -20734,6 +20734,18 @@ function countOccurrences(value, searchedChar) {
     return count;
 }
 
+/**
+ * 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
  *
@@ -20855,9 +20867,17 @@ class KnowledgeCommitmentDefinition extends BaseCommitmentDefinition {
             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',
+        };
     }
 }
 /**
@@ -20871,6 +20891,128 @@ function hasMeaningfulNonUrlText(content, urls) {
     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$1(`
+                    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$1(`
+        ## ${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
@@ -28344,7 +28486,7 @@ function resolveUseCalendarToolRuntime(args) {
     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);
@@ -28364,7 +28506,7 @@ function resolveUseCalendarToolRuntime(args) {
     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,
@@ -28397,7 +28539,7 @@ function normalizeConfiguredCalendars$1(rawCalendars) {
             continue;
         }
         const calendar = rawCalendar;
-        const rawUrl = normalizeOptionalText$1(calendar.url);
+        const rawUrl = normalizeOptionalText$2(calendar.url);
         if (!rawUrl) {
             continue;
         }
@@ -28448,7 +28590,7 @@ function createCalendarWalletCredentialRequiredResult(error) {
  *
  * @private function of resolveUseCalendarToolRuntimeOrWalletCredentialResult
  */
-function normalizeOptionalText$1(value) {
+function normalizeOptionalText$2(value) {
     if (typeof value !== 'string') {
         return undefined;
     }
@@ -28480,13 +28622,13 @@ function createUseCalendarToolFunctions() {
         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) {
@@ -28498,7 +28640,7 @@ function createUseCalendarToolFunctions() {
                 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, {
@@ -28536,11 +28678,11 @@ function createUseCalendarToolFunctions() {
             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),
                 });
@@ -28562,12 +28704,12 @@ function createUseCalendarToolFunctions() {
             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),
                 });
@@ -28614,7 +28756,7 @@ function createUseCalendarToolFunctions() {
                     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, {
@@ -28662,7 +28804,7 @@ function encodeGoogleCalendarId(calendarId) {
  * @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.`);
     }
@@ -28673,7 +28815,7 @@ function normalizeRequiredText(value, fieldName) {
  *
  * @private function of createUseCalendarToolFunctions
  */
-function normalizeOptionalText(value) {
+function normalizeOptionalText$1(value) {
     if (typeof value !== 'string') {
         return undefined;
     }
@@ -33293,6 +33435,580 @@ class UseUserLocationCommitmentDefinition extends BaseCommitmentDefinition {
 }
 // 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$1((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$1(`
+        # ${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.
  *
@@ -33567,6 +34283,8 @@ const COMMITMENT_REGISTRY = [
     new MessageSuffixCommitmentDefinition(),
     new MessageCommitmentDefinition('MESSAGE'),
     new MessageCommitmentDefinition('MESSAGES'),
+    new WalletCommitmentDefinition('WALLET'),
+    new WalletCommitmentDefinition('WALLETS'),
     new ScenarioCommitmentDefinition('SCENARIO'),
     new ScenarioCommitmentDefinition('SCENARIOS'),
     new DeleteCommitmentDefinition('DELETE'),
@@ -34405,6 +35123,12 @@ const OVERWRITTEN_COMMITMENT_GROUP_BY_TYPE = new Map([
     ['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.
  *
@@ -34453,6 +35177,9 @@ function filterOverwrittenCommitments(commitments) {
 function filterDeletedCommitments(commitments) {
     const filteredCommitments = [];
     for (const commitment of commitments) {
+        if (isIgnoredCommitmentType(commitment.type)) {
+            continue;
+        }
         if (!isDeleteCommitmentType(commitment.type)) {
             filteredCommitments.push(commitment);
             continue;
@@ -34483,6 +35210,17 @@ function filterDeletedCommitments(commitments) {
 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.
  *
@@ -35090,7 +35828,6 @@ function createInheritanceCapability(content) {
     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',
@@ -35395,11 +36132,11 @@ function extractMcpServers(agentSource) {
  */
 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.
@@ -35498,7 +36235,7 @@ const SDK_TRANSPILER_KNOWLEDGE_THRESHOLD = 1000;
  */
 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,
@@ -35508,7 +36245,12 @@ async function prepareSdkTranspilerContext(book, options) {
     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,
@@ -35526,6 +36268,36 @@ async function prepareSdkTranspilerContext(book, options) {
         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.
  *
@@ -45504,8 +46276,8 @@ class OpenAiAgentKitExecutionTools extends OpenAiVectorStoreHandler {
      * 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', {
@@ -45513,11 +46285,10 @@ class OpenAiAgentKitExecutionTools extends OpenAiVectorStoreHandler {
                 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,
@@ -45526,13 +46297,19 @@ class OpenAiAgentKitExecutionTools extends OpenAiVectorStoreHandler {
             });
             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 Agent$1({
             name,
             model: this.agentKitModelName,
@@ -45551,7 +46328,7 @@ class OpenAiAgentKitExecutionTools extends OpenAiVectorStoreHandler {
                 name,
                 model: this.agentKitModelName,
                 toolCount: agentKitTools.length,
-                hasVectorStore: Boolean(vectorStoreId),
+                hasVectorStore: this.isNativeKnowledgeSearchEnabled && Boolean(vectorStoreId),
             });
         }
         return preparedAgent;
@@ -45571,14 +46348,11 @@ class OpenAiAgentKitExecutionTools extends OpenAiVectorStoreHandler {
      * 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(fileSearchTool(vectorStoreId));
         }
-        if (nativeAgentKitTools && nativeAgentKitTools.length > 0) {
-            agentKitTools.push(...nativeAgentKitTools);
-        }
         if (tools && tools.length > 0) {
             let scriptTools = null;
             for (const toolDefinition of tools) {
@@ -46053,6 +46827,12 @@ class OpenAiAgentKitExecutionTools extends OpenAiVectorStoreHandler {
     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.
      */