@promptbook/browser 0.112.0-11 → 0.112.0-12

package/esm/index.es.js

@@ -29,7 +29,7 @@ const BOOK_LANGUAGE_VERSION = '2.0.0';
  * @generated
  * @see https://github.com/webgptorg/promptbook
  */
-const PROMPTBOOK_ENGINE_VERSION = '0.112.0-11';
+const PROMPTBOOK_ENGINE_VERSION = '0.112.0-12';
 /**
  * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
  * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -10963,6 +10963,1232 @@ class UseBrowserCommitmentDefinition extends BaseCommitmentDefinition {
  * Note: [💞] Ignore a discrepancy between file name and entity name
  */
 
+/**
+ * Base Google Calendar API URL.
+ *
+ * @private constant of callGoogleCalendarApi
+ */
+const GOOGLE_CALENDAR_API_BASE_URL = 'https://www.googleapis.com/calendar/v3';
+/**
+ * Runs one Google Calendar API request and parses JSON response payload.
+ *
+ * @private function of UseCalendarCommitmentDefinition
+ */
+async function callGoogleCalendarApi(accessToken, options) {
+    const url = new URL(options.path, GOOGLE_CALENDAR_API_BASE_URL);
+    if (options.query) {
+        for (const [key, value] of Object.entries(options.query)) {
+            if (value && value.trim()) {
+                url.searchParams.set(key, value);
+            }
+        }
+    }
+    const response = await fetch(url.toString(), {
+        method: options.method,
+        headers: {
+            Authorization: `Bearer ${accessToken}`,
+            Accept: 'application/json',
+            'Content-Type': 'application/json',
+        },
+        body: options.body ? JSON.stringify(options.body) : undefined,
+    });
+    const textPayload = await response.text();
+    const parsedPayload = tryParseJson$2(textPayload);
+    if (options.allowNotFound && response.status === 404) {
+        return null;
+    }
+    if (!response.ok) {
+        throw new Error(spaceTrim$1(`
+                Google Calendar API request failed (${response.status} ${response.statusText}):
+                ${extractGoogleCalendarApiErrorMessage(parsedPayload, textPayload)}
+            `));
+    }
+    return parsedPayload;
+}
+/**
+ * Parses raw text into JSON when possible.
+ *
+ * @private function of callGoogleCalendarApi
+ */
+function tryParseJson$2(rawText) {
+    if (!rawText.trim()) {
+        return {};
+    }
+    try {
+        return JSON.parse(rawText);
+    }
+    catch (_a) {
+        return rawText;
+    }
+}
+/**
+ * Extracts a user-friendly Google Calendar API error message.
+ *
+ * @private function of callGoogleCalendarApi
+ */
+function extractGoogleCalendarApiErrorMessage(parsedPayload, fallbackText) {
+    if (parsedPayload && typeof parsedPayload === 'object') {
+        const payload = parsedPayload;
+        const errorPayload = payload.error;
+        if (errorPayload && typeof errorPayload === 'object') {
+            const normalizedErrorPayload = errorPayload;
+            const message = typeof normalizedErrorPayload.message === 'string' ? normalizedErrorPayload.message : '';
+            const errors = Array.isArray(normalizedErrorPayload.errors) ? normalizedErrorPayload.errors : [];
+            const flattenedErrors = errors
+                .map((errorEntry) => {
+                if (!errorEntry || typeof errorEntry !== 'object') {
+                    return '';
+                }
+                const normalizedErrorEntry = errorEntry;
+                const detailMessage = typeof normalizedErrorEntry.message === 'string' ? normalizedErrorEntry.message : '';
+                const reason = typeof normalizedErrorEntry.reason === 'string' ? normalizedErrorEntry.reason : '';
+                return [detailMessage, reason].filter(Boolean).join(' | ');
+            })
+                .filter(Boolean);
+            if (message || flattenedErrors.length > 0) {
+                return [message, ...flattenedErrors].filter(Boolean).join(' | ');
+            }
+        }
+    }
+    return fallbackText || 'Unknown Google Calendar API error';
+}
+
+/**
+ * Hostnames accepted for Google Calendar references.
+ *
+ * @private internal USE CALENDAR constant
+ */
+const GOOGLE_CALENDAR_HOSTNAMES = new Set(['calendar.google.com', 'www.calendar.google.com']);
+/**
+ * Default Google Calendar OAuth scopes when commitment content does not list any.
+ *
+ * @private internal USE CALENDAR constant
+ */
+const DEFAULT_GOOGLE_CALENDAR_SCOPES = ['https://www.googleapis.com/auth/calendar'];
+/**
+ * Parses one Google Calendar URL/reference into canonical details.
+ *
+ * Supported input forms:
+ * - `https://calendar.google.com/...`
+ * - `calendar.google.com/...`
+ *
+ * @private internal utility of USE CALENDAR commitment
+ */
+function parseGoogleCalendarReference(rawReference) {
+    const trimmedReference = rawReference.trim();
+    if (!trimmedReference) {
+        return null;
+    }
+    const normalizedReference = trimmedReference.startsWith('calendar.google.com/')
+        ? `https://${trimmedReference}`
+        : trimmedReference;
+    let parsedUrl;
+    try {
+        parsedUrl = new URL(normalizedReference);
+    }
+    catch (_a) {
+        return null;
+    }
+    if (!GOOGLE_CALENDAR_HOSTNAMES.has(parsedUrl.hostname.toLowerCase())) {
+        return null;
+    }
+    parsedUrl.protocol = 'https:';
+    parsedUrl.hash = '';
+    return {
+        provider: 'google',
+        url: parsedUrl.toString(),
+        calendarId: parseGoogleCalendarIdFromUrl(parsedUrl) || 'primary',
+        scopes: [...DEFAULT_GOOGLE_CALENDAR_SCOPES],
+    };
+}
+/**
+ * Parses `USE CALENDAR` commitment content into calendar reference + optional instructions.
+ *
+ * @private internal utility of USE CALENDAR commitment
+ */
+function parseUseCalendarCommitmentContent(content) {
+    const trimmedContent = spaceTrim$1(content);
+    if (!trimmedContent) {
+        return {
+            calendar: null,
+            calendarUrlRaw: null,
+            instructions: '',
+        };
+    }
+    const lines = trimmedContent
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean);
+    if (lines.length === 0) {
+        return {
+            calendar: null,
+            calendarUrlRaw: null,
+            instructions: '',
+        };
+    }
+    let calendarReferenceRaw = null;
+    let calendarReference = null;
+    const firstLine = lines[0] || '';
+    const firstLineTokens = firstLine.split(/\s+/).filter(Boolean);
+    for (const token of firstLineTokens) {
+        const cleanedToken = token.replace(/[),.;:!?]+$/g, '');
+        const parsedReference = parseGoogleCalendarReference(cleanedToken);
+        if (!parsedReference) {
+            continue;
+        }
+        calendarReferenceRaw = cleanedToken;
+        calendarReference = parsedReference;
+        break;
+    }
+    if (!calendarReference) {
+        const firstUrl = findFirstUrlToken(trimmedContent);
+        if (firstUrl) {
+            calendarReferenceRaw = firstUrl;
+            calendarReference = parseGoogleCalendarReference(firstUrl);
+        }
+    }
+    const scopes = extractGoogleCalendarScopes(trimmedContent);
+    if (calendarReference) {
+        calendarReference = {
+            ...calendarReference,
+            scopes: scopes.length > 0 ? scopes : [...DEFAULT_GOOGLE_CALENDAR_SCOPES],
+            tokenRef: extractTokenRef(trimmedContent),
+        };
+    }
+    const instructionLines = [...lines];
+    if (instructionLines.length > 0 && calendarReferenceRaw) {
+        instructionLines[0] = removeTokenFromLine(instructionLines[0] || '', calendarReferenceRaw);
+    }
+    const filteredInstructionLines = instructionLines.filter((line) => !/^\s*SCOPES?\s+/i.test(line) && !line.trim().startsWith('https://www.googleapis.com/auth/'));
+    return {
+        calendar: calendarReference,
+        calendarUrlRaw: calendarReferenceRaw,
+        instructions: filteredInstructionLines.join('\n').trim(),
+    };
+}
+/**
+ * Attempts to resolve one concrete Google Calendar id from URL.
+ *
+ * @private internal utility of USE CALENDAR commitment
+ */
+function parseGoogleCalendarIdFromUrl(url) {
+    const rawCalendarId = url.searchParams.get('cid') || url.searchParams.get('src') || url.searchParams.get('calendarId');
+    if (!rawCalendarId) {
+        return null;
+    }
+    const decodedCalendarId = decodeURIComponent(rawCalendarId).trim();
+    return decodedCalendarId || null;
+}
+/**
+ * Finds the first URL-looking token in text.
+ *
+ * @private utility of USE CALENDAR commitment
+ */
+function findFirstUrlToken(text) {
+    const match = text.match(/https?:\/\/[^\s)]+/i);
+    return match ? match[0] || null : null;
+}
+/**
+ * Extracts Google Calendar OAuth scopes declared in commitment text.
+ *
+ * @private utility of USE CALENDAR commitment
+ */
+function extractGoogleCalendarScopes(content) {
+    const scopesFromUrls = content.match(/https:\/\/www\.googleapis\.com\/auth\/[A-Za-z0-9._/-]+/gim) || [];
+    const scopesFromKeywordLines = content
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter((line) => /^\s*SCOPES?\s+/i.test(line))
+        .flatMap((line) => line
+        .replace(/^\s*SCOPES?\s+/i, '')
+        .split(/[,\s]+/)
+        .map((scope) => scope.trim())
+        .filter(Boolean))
+        .filter((scope) => scope.startsWith('https://www.googleapis.com/auth/'));
+    const uniqueScopes = new Set();
+    for (const scope of [...scopesFromUrls, ...scopesFromKeywordLines]) {
+        uniqueScopes.add(scope);
+    }
+    return [...uniqueScopes];
+}
+/**
+ * Extracts optional token reference marker from commitment text.
+ *
+ * @private utility of USE CALENDAR commitment
+ */
+function extractTokenRef(content) {
+    var _a;
+    const tokenRefMatch = content.match(/@[\w.-]+/);
+    const tokenRef = (_a = tokenRefMatch === null || tokenRefMatch === void 0 ? void 0 : tokenRefMatch[0]) === null || _a === void 0 ? void 0 : _a.trim();
+    return tokenRef || undefined;
+}
+/**
+ * Removes one specific token from one instruction line.
+ *
+ * @private utility of USE CALENDAR commitment
+ */
+function removeTokenFromLine(line, token) {
+    const tokens = line.split(/\s+/).filter(Boolean);
+    const filteredTokens = tokens.filter((lineToken) => lineToken.replace(/[),.;:!?]+$/g, '') !== token);
+    return filteredTokens.join(' ').trim();
+}
+/**
+ * Note: [💞] Ignore a discrepancy between file name and entity name
+ */
+
+/**
+ * Wallet metadata used by USE CALENDAR when resolving Google Calendar credentials.
+ *
+ * @private constant of UseCalendarCommitmentDefinition
+ */
+const UseCalendarWallet = {
+    service: 'google_calendar',
+    key: 'use-calendar-google-token',
+};
+
+/**
+ * Internal error used to signal missing wallet credentials.
+ *
+ * @private class of resolveUseCalendarToolRuntimeOrWalletCredentialResult
+ */
+class CalendarWalletCredentialRequiredError extends Error {
+    constructor(options) {
+        super('Google Calendar token is missing in wallet. Request it from user and store as ACCESS_TOKEN (service google_calendar, key use-calendar-google-token).');
+        this.name = 'CalendarWalletCredentialRequiredError';
+        this.service = UseCalendarWallet.service;
+        this.key = UseCalendarWallet.key;
+        this.calendarReference = options.calendarReference;
+    }
+}
+/**
+ * Resolves calendar runtime or returns a wallet-credential-required payload when missing.
+ *
+ * @private function of UseCalendarCommitmentDefinition
+ */
+function resolveUseCalendarToolRuntimeOrWalletCredentialResult(args) {
+    try {
+        return resolveUseCalendarToolRuntime(args);
+    }
+    catch (error) {
+        if (error instanceof CalendarWalletCredentialRequiredError) {
+            return {
+                walletResult: JSON.stringify(createCalendarWalletCredentialRequiredResult(error)),
+            };
+        }
+        throw error;
+    }
+}
+/**
+ * Resolves runtime calendar + token for a USE CALENDAR tool call.
+ *
+ * @private function of resolveUseCalendarToolRuntimeOrWalletCredentialResult
+ */
+function resolveUseCalendarToolRuntime(args) {
+    var _a, _b;
+    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);
+    let calendarReference = null;
+    if (calendarArgument) {
+        calendarReference = parseGoogleCalendarReference(calendarArgument);
+        if (!calendarReference) {
+            throw new Error(`Calendar URL "${calendarArgument}" is invalid.`);
+        }
+    }
+    else if (configuredCalendars.length === 1) {
+        calendarReference = configuredCalendars[0] || null;
+    }
+    else if (configuredCalendars.length > 1) {
+        throw new Error('Calendar is ambiguous. Provide "calendarUrl" argument with one calendar from USE CALENDAR commitments.');
+    }
+    else {
+        throw new Error('Calendar is required. Provide "calendarUrl" argument in the tool call.');
+    }
+    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) || '';
+    if (!accessToken) {
+        throw new CalendarWalletCredentialRequiredError({
+            calendarReference,
+        });
+    }
+    if (configuredCalendars.length > 0) {
+        const allowedCalendarUrls = new Set(configuredCalendars.map((configuredCalendar) => configuredCalendar.url));
+        if (!allowedCalendarUrls.has(calendarReference.url)) {
+            throw new Error(`Calendar "${calendarReference.url}" is not configured by USE CALENDAR for this agent.`);
+        }
+    }
+    return {
+        calendarReference,
+        accessToken,
+    };
+}
+/**
+ * Normalizes optional calendar list from runtime context.
+ *
+ * @private function of resolveUseCalendarToolRuntimeOrWalletCredentialResult
+ */
+function normalizeConfiguredCalendars$1(rawCalendars) {
+    if (!Array.isArray(rawCalendars)) {
+        return [];
+    }
+    const calendars = [];
+    const knownCalendars = new Set();
+    for (const rawCalendar of rawCalendars) {
+        if (!rawCalendar || typeof rawCalendar !== 'object') {
+            continue;
+        }
+        const calendar = rawCalendar;
+        const rawUrl = normalizeOptionalText$1(calendar.url);
+        if (!rawUrl) {
+            continue;
+        }
+        const parsedReference = parseGoogleCalendarReference(rawUrl);
+        if (!parsedReference) {
+            continue;
+        }
+        const key = `${parsedReference.provider}|${parsedReference.url}`;
+        if (knownCalendars.has(key)) {
+            continue;
+        }
+        knownCalendars.add(key);
+        const scopes = Array.isArray(calendar.scopes)
+            ? calendar.scopes
+                .filter((scope) => typeof scope === 'string')
+                .map((scope) => scope.trim())
+                .filter(Boolean)
+            : [];
+        calendars.push({
+            ...parsedReference,
+            scopes: scopes.length > 0 ? scopes : parsedReference.scopes,
+        });
+    }
+    return calendars;
+}
+/**
+ * Converts missing-wallet errors into structured tool result payloads.
+ *
+ * @private function of resolveUseCalendarToolRuntimeOrWalletCredentialResult
+ */
+function createCalendarWalletCredentialRequiredResult(error) {
+    return {
+        action: 'calendar-auth',
+        status: 'wallet-credential-required',
+        recordType: 'ACCESS_TOKEN',
+        service: error.service,
+        key: error.key,
+        isUserScoped: false,
+        isGlobal: false,
+        provider: 'google',
+        calendarUrl: error.calendarReference.url,
+        scopes: error.calendarReference.scopes,
+        message: error.message,
+    };
+}
+/**
+ * Normalizes unknown text input to trimmed non-empty string.
+ *
+ * @private function of resolveUseCalendarToolRuntimeOrWalletCredentialResult
+ */
+function normalizeOptionalText$1(value) {
+    if (typeof value !== 'string') {
+        return undefined;
+    }
+    const trimmedValue = value.trim();
+    return trimmedValue || undefined;
+}
+
+/**
+ * Names of tools used by the USE CALENDAR commitment.
+ *
+ * @private constant of UseCalendarCommitmentDefinition
+ */
+const UseCalendarToolNames = {
+    listEvents: 'calendar_list_events',
+    getEvent: 'calendar_get_event',
+    createEvent: 'calendar_create_event',
+    updateEvent: 'calendar_update_event',
+    deleteEvent: 'calendar_delete_event',
+    inviteGuests: 'calendar_invite_guests',
+};
+
+/**
+ * Gets Google Calendar tool function implementations.
+ *
+ * @private function of UseCalendarCommitmentDefinition
+ */
+function createUseCalendarToolFunctions() {
+    return {
+        async [UseCalendarToolNames.listEvents](args) {
+            return withUseCalendarRuntime(args, async ({ calendarReference, accessToken }) => {
+                const query = {};
+                if (normalizeOptionalText(args.timeMin)) {
+                    query.timeMin = args.timeMin.trim();
+                }
+                if (normalizeOptionalText(args.timeMax)) {
+                    query.timeMax = args.timeMax.trim();
+                }
+                if (normalizeOptionalText(args.query)) {
+                    query.q = args.query.trim();
+                }
+                if (typeof args.maxResults === 'number' && Number.isFinite(args.maxResults) && args.maxResults > 0) {
+                    query.maxResults = String(Math.floor(args.maxResults));
+                }
+                if (args.singleEvents !== undefined) {
+                    query.singleEvents = args.singleEvents ? 'true' : 'false';
+                }
+                if (args.orderBy === 'startTime' || args.orderBy === 'updated') {
+                    query.orderBy = args.orderBy;
+                }
+                if (normalizeOptionalText(args.timeZone)) {
+                    query.timeZone = args.timeZone.trim();
+                }
+                const payload = await callGoogleCalendarApi(accessToken, {
+                    method: 'GET',
+                    path: `/calendars/${encodeGoogleCalendarId(calendarReference.calendarId)}/events`,
+                    query,
+                });
+                const events = ((payload === null || payload === void 0 ? void 0 : payload.items) || []).map((event) => mapGoogleCalendarEvent(event));
+                return JSON.stringify({
+                    provider: calendarReference.provider,
+                    calendarUrl: calendarReference.url,
+                    calendarId: calendarReference.calendarId,
+                    events,
+                    nextPageToken: (payload === null || payload === void 0 ? void 0 : payload.nextPageToken) || null,
+                    nextSyncToken: (payload === null || payload === void 0 ? void 0 : payload.nextSyncToken) || null,
+                });
+            });
+        },
+        async [UseCalendarToolNames.getEvent](args) {
+            return withUseCalendarRuntime(args, async ({ calendarReference, accessToken }) => {
+                const eventId = normalizeRequiredText(args.eventId, 'eventId');
+                const payload = await callGoogleCalendarApi(accessToken, {
+                    method: 'GET',
+                    path: `/calendars/${encodeGoogleCalendarId(calendarReference.calendarId)}/events/${encodeURIComponent(eventId)}`,
+                });
+                return JSON.stringify({
+                    provider: calendarReference.provider,
+                    calendarUrl: calendarReference.url,
+                    calendarId: calendarReference.calendarId,
+                    event: mapGoogleCalendarEvent(payload || {}),
+                });
+            });
+        },
+        async [UseCalendarToolNames.createEvent](args) {
+            return withUseCalendarRuntime(args, async ({ calendarReference, accessToken }) => {
+                const requestBody = createGoogleCalendarEventPayload({
+                    summary: normalizeRequiredText(args.summary, 'summary'),
+                    description: normalizeOptionalText(args.description),
+                    location: normalizeOptionalText(args.location),
+                    start: normalizeRequiredText(args.start, 'start'),
+                    end: normalizeRequiredText(args.end, 'end'),
+                    timeZone: normalizeOptionalText(args.timeZone),
+                    attendees: normalizeAttendees(args.attendees),
+                    reminderMinutes: normalizeReminderMinutes(args.reminderMinutes),
+                });
+                const payload = await callGoogleCalendarApi(accessToken, {
+                    method: 'POST',
+                    path: `/calendars/${encodeGoogleCalendarId(calendarReference.calendarId)}/events`,
+                    query: createSendUpdatesQuery(args.sendUpdates),
+                    body: requestBody,
+                });
+                return JSON.stringify({
+                    provider: calendarReference.provider,
+                    calendarUrl: calendarReference.url,
+                    calendarId: calendarReference.calendarId,
+                    event: mapGoogleCalendarEvent(payload || {}),
+                });
+            });
+        },
+        async [UseCalendarToolNames.updateEvent](args) {
+            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),
+                    attendees: normalizeAttendees(args.attendees),
+                    reminderMinutes: normalizeReminderMinutes(args.reminderMinutes),
+                });
+                const payload = await callGoogleCalendarApi(accessToken, {
+                    method: 'PATCH',
+                    path: `/calendars/${encodeGoogleCalendarId(calendarReference.calendarId)}/events/${encodeURIComponent(eventId)}`,
+                    query: createSendUpdatesQuery(args.sendUpdates),
+                    body: requestBody,
+                });
+                return JSON.stringify({
+                    provider: calendarReference.provider,
+                    calendarUrl: calendarReference.url,
+                    calendarId: calendarReference.calendarId,
+                    event: mapGoogleCalendarEvent(payload || {}),
+                });
+            });
+        },
+        async [UseCalendarToolNames.deleteEvent](args) {
+            return withUseCalendarRuntime(args, async ({ calendarReference, accessToken }) => {
+                const eventId = normalizeRequiredText(args.eventId, 'eventId');
+                await callGoogleCalendarApi(accessToken, {
+                    method: 'DELETE',
+                    path: `/calendars/${encodeGoogleCalendarId(calendarReference.calendarId)}/events/${encodeURIComponent(eventId)}`,
+                    query: createSendUpdatesQuery(args.sendUpdates),
+                });
+                return JSON.stringify({
+                    provider: calendarReference.provider,
+                    calendarUrl: calendarReference.url,
+                    calendarId: calendarReference.calendarId,
+                    eventId,
+                    status: 'deleted',
+                });
+            });
+        },
+        async [UseCalendarToolNames.inviteGuests](args) {
+            return withUseCalendarRuntime(args, async ({ calendarReference, accessToken }) => {
+                const eventId = normalizeRequiredText(args.eventId, 'eventId');
+                const guests = normalizeAttendees(args.guests);
+                if (guests.length === 0) {
+                    throw new Error('Tool "calendar_invite_guests" requires non-empty "guests".');
+                }
+                const existingEvent = await callGoogleCalendarApi(accessToken, {
+                    method: 'GET',
+                    path: `/calendars/${encodeGoogleCalendarId(calendarReference.calendarId)}/events/${encodeURIComponent(eventId)}`,
+                });
+                const existingAttendees = ((existingEvent === null || existingEvent === void 0 ? void 0 : existingEvent.attendees) || [])
+                    .map((attendee) => normalizeOptionalText(attendee.email))
+                    .filter((email) => Boolean(email));
+                const mergedAttendees = [...new Set([...existingAttendees, ...guests])];
+                const payload = await callGoogleCalendarApi(accessToken, {
+                    method: 'PATCH',
+                    path: `/calendars/${encodeGoogleCalendarId(calendarReference.calendarId)}/events/${encodeURIComponent(eventId)}`,
+                    query: createSendUpdatesQuery(args.sendUpdates),
+                    body: {
+                        attendees: mergedAttendees.map((email) => ({ email })),
+                    },
+                });
+                return JSON.stringify({
+                    provider: calendarReference.provider,
+                    calendarUrl: calendarReference.url,
+                    calendarId: calendarReference.calendarId,
+                    event: mapGoogleCalendarEvent(payload || {}),
+                    invitedGuests: guests,
+                });
+            });
+        },
+    };
+}
+/**
+ * Executes one tool operation with resolved USE CALENDAR runtime.
+ *
+ * @private function of createUseCalendarToolFunctions
+ */
+async function withUseCalendarRuntime(args, operation) {
+    const runtime = resolveUseCalendarToolRuntimeOrWalletCredentialResult(args);
+    if ('walletResult' in runtime) {
+        return runtime.walletResult;
+    }
+    return operation(runtime);
+}
+/**
+ * Encodes one Google calendar id for URL path usage.
+ *
+ * @private function of createUseCalendarToolFunctions
+ */
+function encodeGoogleCalendarId(calendarId) {
+    return encodeURIComponent(calendarId);
+}
+/**
+ * Normalizes one required textual input.
+ *
+ * @private function of createUseCalendarToolFunctions
+ */
+function normalizeRequiredText(value, fieldName) {
+    const normalizedValue = normalizeOptionalText(value);
+    if (!normalizedValue) {
+        throw new Error(`Tool "${fieldName}" requires non-empty value.`);
+    }
+    return normalizedValue;
+}
+/**
+ * Normalizes unknown text input to trimmed non-empty string.
+ *
+ * @private function of createUseCalendarToolFunctions
+ */
+function normalizeOptionalText(value) {
+    if (typeof value !== 'string') {
+        return undefined;
+    }
+    const trimmedValue = value.trim();
+    return trimmedValue || undefined;
+}
+/**
+ * Normalizes optional attendee list from tool input.
+ *
+ * @private function of createUseCalendarToolFunctions
+ */
+function normalizeAttendees(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    const normalizedAttendees = value
+        .filter((attendee) => typeof attendee === 'string')
+        .map((attendee) => attendee.trim())
+        .filter(Boolean);
+    return [...new Set(normalizedAttendees)];
+}
+/**
+ * Normalizes optional reminder-minute offsets from tool input.
+ *
+ * @private function of createUseCalendarToolFunctions
+ */
+function normalizeReminderMinutes(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    const reminderMinutes = value
+        .filter((minute) => typeof minute === 'number' && Number.isFinite(minute))
+        .map((minute) => Math.max(0, Math.floor(minute)));
+    return [...new Set(reminderMinutes)];
+}
+/**
+ * Builds optional `sendUpdates` query for mutating Google Calendar requests.
+ *
+ * @private function of createUseCalendarToolFunctions
+ */
+function createSendUpdatesQuery(sendUpdates) {
+    if (sendUpdates === 'all' || sendUpdates === 'externalOnly' || sendUpdates === 'none') {
+        return { sendUpdates };
+    }
+    return {};
+}
+/**
+ * Creates one Google Calendar event payload from normalized tool arguments.
+ *
+ * @private function of createUseCalendarToolFunctions
+ */
+function createGoogleCalendarEventPayload(options) {
+    const payload = {};
+    if (options.summary) {
+        payload.summary = options.summary;
+    }
+    if (options.description) {
+        payload.description = options.description;
+    }
+    if (options.location) {
+        payload.location = options.location;
+    }
+    if (options.start) {
+        payload.start = createGoogleCalendarDateValue(options.start, options.timeZone);
+    }
+    if (options.end) {
+        payload.end = createGoogleCalendarDateValue(options.end, options.timeZone);
+    }
+    if (options.attendees && options.attendees.length > 0) {
+        payload.attendees = options.attendees.map((email) => ({ email }));
+    }
+    if (options.reminderMinutes && options.reminderMinutes.length > 0) {
+        payload.reminders = {
+            useDefault: false,
+            overrides: options.reminderMinutes.map((minutes) => ({
+                method: 'popup',
+                minutes,
+            })),
+        };
+    }
+    return payload;
+}
+/**
+ * Converts date/dateTime input into a Google Calendar-compatible date object.
+ *
+ * @private function of createUseCalendarToolFunctions
+ */
+function createGoogleCalendarDateValue(value, timeZone) {
+    const isDateOnly = /^\d{4}-\d{2}-\d{2}$/.test(value);
+    if (isDateOnly) {
+        return {
+            date: value,
+        };
+    }
+    return {
+        dateTime: value,
+        ...(timeZone ? { timeZone } : {}),
+    };
+}
+/**
+ * Maps raw Google Calendar event payload to a compact tool result object.
+ *
+ * @private function of createUseCalendarToolFunctions
+ */
+function mapGoogleCalendarEvent(event) {
+    return {
+        id: event.id || null,
+        summary: event.summary || null,
+        description: event.description || null,
+        location: event.location || null,
+        status: event.status || null,
+        htmlLink: event.htmlLink || null,
+        start: event.start || null,
+        end: event.end || null,
+        organizer: event.organizer || null,
+        attendees: (event.attendees || []).map((attendee) => ({
+            email: attendee.email || null,
+            responseStatus: attendee.responseStatus || null,
+        })),
+    };
+}
+
+/**
+ * Shared calendar URL argument description used in USE CALENDAR tool schemas.
+ *
+ * @private constant of createUseCalendarTools
+ */
+const CALENDAR_URL_PARAMETER_DESCRIPTION = 'Google Calendar URL configured by USE CALENDAR (for example "https://calendar.google.com/...").';
+/**
+ * Adds USE CALENDAR tool definitions while keeping already registered tools untouched.
+ *
+ * @private function of UseCalendarCommitmentDefinition
+ */
+function createUseCalendarTools(existingTools) {
+    const updatedTools = [...existingTools];
+    const addToolIfMissing = (tool) => {
+        if (!updatedTools.some((existingTool) => existingTool.name === tool.name)) {
+            updatedTools.push(tool);
+        }
+    };
+    addToolIfMissing({
+        name: UseCalendarToolNames.listEvents,
+        description: 'List events from a configured calendar for a time range.',
+        parameters: {
+            type: 'object',
+            properties: {
+                calendarUrl: {
+                    type: 'string',
+                    description: CALENDAR_URL_PARAMETER_DESCRIPTION,
+                },
+                timeMin: {
+                    type: 'string',
+                    description: 'Inclusive event start bound in ISO datetime.',
+                },
+                timeMax: {
+                    type: 'string',
+                    description: 'Exclusive event end bound in ISO datetime.',
+                },
+                query: {
+                    type: 'string',
+                    description: 'Optional free-text event search query.',
+                },
+                maxResults: {
+                    type: 'integer',
+                    description: 'Maximum number of events to return.',
+                },
+                singleEvents: {
+                    type: 'boolean',
+                    description: 'Expand recurring events into individual instances.',
+                },
+                orderBy: {
+                    type: 'string',
+                    description: 'Optional ordering ("startTime" or "updated").',
+                },
+                timeZone: {
+                    type: 'string',
+                    description: 'Optional IANA timezone for response rendering.',
+                },
+            },
+            required: [],
+        },
+    });
+    addToolIfMissing({
+        name: UseCalendarToolNames.getEvent,
+        description: 'Get one event by id from a configured calendar.',
+        parameters: {
+            type: 'object',
+            properties: {
+                calendarUrl: {
+                    type: 'string',
+                    description: CALENDAR_URL_PARAMETER_DESCRIPTION,
+                },
+                eventId: {
+                    type: 'string',
+                    description: 'Google Calendar event id.',
+                },
+            },
+            required: ['eventId'],
+        },
+    });
+    addToolIfMissing({
+        name: UseCalendarToolNames.createEvent,
+        description: 'Create one event in a configured calendar.',
+        parameters: {
+            type: 'object',
+            properties: {
+                calendarUrl: {
+                    type: 'string',
+                    description: CALENDAR_URL_PARAMETER_DESCRIPTION,
+                },
+                summary: {
+                    type: 'string',
+                    description: 'Event title/summary.',
+                },
+                description: {
+                    type: 'string',
+                    description: 'Optional event description.',
+                },
+                location: {
+                    type: 'string',
+                    description: 'Optional event location.',
+                },
+                start: {
+                    type: 'string',
+                    description: 'Event start as ISO datetime or date.',
+                },
+                end: {
+                    type: 'string',
+                    description: 'Event end as ISO datetime or date.',
+                },
+                timeZone: {
+                    type: 'string',
+                    description: 'Optional timezone for datetime values.',
+                },
+                attendees: {
+                    type: 'array',
+                    description: 'Optional guest email list.',
+                },
+                reminderMinutes: {
+                    type: 'array',
+                    description: 'Optional popup reminder minute offsets.',
+                },
+                sendUpdates: {
+                    type: 'string',
+                    description: 'Guest update policy ("all", "externalOnly", "none").',
+                },
+            },
+            required: ['summary', 'start', 'end'],
+        },
+    });
+    addToolIfMissing({
+        name: UseCalendarToolNames.updateEvent,
+        description: 'Update one existing event in a configured calendar.',
+        parameters: {
+            type: 'object',
+            properties: {
+                calendarUrl: {
+                    type: 'string',
+                    description: CALENDAR_URL_PARAMETER_DESCRIPTION,
+                },
+                eventId: {
+                    type: 'string',
+                    description: 'Google Calendar event id.',
+                },
+                summary: {
+                    type: 'string',
+                    description: 'Updated event summary.',
+                },
+                description: {
+                    type: 'string',
+                    description: 'Updated event description.',
+                },
+                location: {
+                    type: 'string',
+                    description: 'Updated event location.',
+                },
+                start: {
+                    type: 'string',
+                    description: 'Updated event start as ISO datetime or date.',
+                },
+                end: {
+                    type: 'string',
+                    description: 'Updated event end as ISO datetime or date.',
+                },
+                timeZone: {
+                    type: 'string',
+                    description: 'Optional timezone for datetime values.',
+                },
+                attendees: {
+                    type: 'array',
+                    description: 'Optional replacement guest email list.',
+                },
+                reminderMinutes: {
+                    type: 'array',
+                    description: 'Optional replacement popup reminder minute offsets.',
+                },
+                sendUpdates: {
+                    type: 'string',
+                    description: 'Guest update policy ("all", "externalOnly", "none").',
+                },
+            },
+            required: ['eventId'],
+        },
+    });
+    addToolIfMissing({
+        name: UseCalendarToolNames.deleteEvent,
+        description: 'Delete one event from a configured calendar.',
+        parameters: {
+            type: 'object',
+            properties: {
+                calendarUrl: {
+                    type: 'string',
+                    description: CALENDAR_URL_PARAMETER_DESCRIPTION,
+                },
+                eventId: {
+                    type: 'string',
+                    description: 'Google Calendar event id.',
+                },
+                sendUpdates: {
+                    type: 'string',
+                    description: 'Guest update policy ("all", "externalOnly", "none").',
+                },
+            },
+            required: ['eventId'],
+        },
+    });
+    addToolIfMissing({
+        name: UseCalendarToolNames.inviteGuests,
+        description: 'Add guests to an existing event in a configured calendar.',
+        parameters: {
+            type: 'object',
+            properties: {
+                calendarUrl: {
+                    type: 'string',
+                    description: CALENDAR_URL_PARAMETER_DESCRIPTION,
+                },
+                eventId: {
+                    type: 'string',
+                    description: 'Google Calendar event id.',
+                },
+                guests: {
+                    type: 'array',
+                    description: 'Guest email list to add to the event.',
+                },
+                sendUpdates: {
+                    type: 'string',
+                    description: 'Guest update policy ("all", "externalOnly", "none").',
+                },
+            },
+            required: ['eventId', 'guests'],
+        },
+    });
+    return updatedTools;
+}
+
+/**
+ * Gets human-readable tool labels for USE CALENDAR functions.
+ *
+ * @private function of UseCalendarCommitmentDefinition
+ */
+function getUseCalendarToolTitles() {
+    return {
+        [UseCalendarToolNames.listEvents]: 'List calendar events',
+        [UseCalendarToolNames.getEvent]: 'Get calendar event',
+        [UseCalendarToolNames.createEvent]: 'Create calendar event',
+        [UseCalendarToolNames.updateEvent]: 'Update calendar event',
+        [UseCalendarToolNames.deleteEvent]: 'Delete calendar event',
+        [UseCalendarToolNames.inviteGuests]: 'Invite calendar guests',
+    };
+}
+
+/**
+ * Normalizes unknown metadata payload into a typed list of configured calendars.
+ *
+ * @private internal utility of USE CALENDAR commitment
+ */
+function normalizeConfiguredCalendars(rawCalendars) {
+    if (!Array.isArray(rawCalendars)) {
+        return [];
+    }
+    const uniqueCalendars = new Set();
+    const calendars = [];
+    for (const rawCalendar of rawCalendars) {
+        if (!rawCalendar || typeof rawCalendar !== 'object') {
+            continue;
+        }
+        const calendar = rawCalendar;
+        const provider = normalizeProvider(calendar.provider);
+        const url = normalizeText(calendar.url);
+        const calendarId = normalizeText(calendar.calendarId);
+        if (!provider || !url || !calendarId) {
+            continue;
+        }
+        const uniqueKey = `${provider}|${url}`;
+        if (uniqueCalendars.has(uniqueKey)) {
+            continue;
+        }
+        uniqueCalendars.add(uniqueKey);
+        const scopes = Array.isArray(calendar.scopes)
+            ? calendar.scopes
+                .filter((scope) => typeof scope === 'string')
+                .map((scope) => scope.trim())
+                .filter(Boolean)
+            : [];
+        calendars.push({
+            provider,
+            url,
+            calendarId,
+            scopes,
+            ...(normalizeText(calendar.tokenRef) ? { tokenRef: normalizeText(calendar.tokenRef) } : {}),
+        });
+    }
+    return calendars;
+}
+/**
+ * Normalizes optional provider text to one supported value.
+ *
+ * @private function of normalizeConfiguredCalendars
+ */
+function normalizeProvider(value) {
+    if (typeof value !== 'string') {
+        return null;
+    }
+    const normalizedProvider = value.trim().toLowerCase();
+    if (normalizedProvider === 'google') {
+        return 'google';
+    }
+    return null;
+}
+/**
+ * Normalizes unknown text input to trimmed non-empty string.
+ *
+ * @private function of normalizeConfiguredCalendars
+ */
+function normalizeText(value) {
+    return typeof value === 'string' ? value.trim() : '';
+}
+
+/**
+ * USE CALENDAR commitment definition.
+ *
+ * `USE CALENDAR` enables calendar tooling so the agent can read and manage events
+ * in one configured Google Calendar.
+ *
+ * Authentication is expected through runtime context provided by the host app UI.
+ * Hosts can provide manual wallet tokens or host-managed OAuth tokens.
+ *
+ * @private [🪔] Maybe export the commitments through some package
+ */
+class UseCalendarCommitmentDefinition extends BaseCommitmentDefinition {
+    constructor() {
+        super('USE CALENDAR', ['CALENDAR']);
+    }
+    /**
+     * Short one-line description of USE CALENDAR.
+     */
+    get description() {
+        return 'Enable calendar tools for reading and managing events through Google Calendar.';
+    }
+    /**
+     * Icon for this commitment.
+     */
+    get icon() {
+        return '📅';
+    }
+    /**
+     * Markdown documentation for USE CALENDAR commitment.
+     */
+    get documentation() {
+        return spaceTrim$1(`
+            # USE CALENDAR
+
+            Enables the agent to access and manage one Google Calendar.
+
+            ## Key aspects
+
+            - The first URL in the commitment should point to a Google Calendar URL.
+            - Optional \`SCOPES\` lines can provide explicit OAuth scopes.
+            - Optional extra instructions can follow calendar reference lines.
+            - Runtime provides Google Calendar OAuth token (manual wallet token or host-managed OAuth token).
+            - Tools support listing events, reading one event, creating events, updating events, deleting events, and inviting guests.
+
+            ## Examples
+
+            \`\`\`book
+            Scheduling Assistant
+
+            PERSONA You coordinate meetings and schedules.
+            USE CALENDAR https://calendar.google.com/calendar/u/0/r
+            \`\`\`
+
+            \`\`\`book
+            Executive Assistant
+
+            USE CALENDAR https://calendar.google.com/calendar/u/0/r
+            SCOPES https://www.googleapis.com/auth/calendar.readonly
+            RULE Ask for confirmation before deleting events.
+            \`\`\`
+        `);
+    }
+    applyToAgentModelRequirements(requirements, content) {
+        var _a;
+        const parsedCommitment = parseUseCalendarCommitmentContent(content);
+        const existingConfiguredCalendars = normalizeConfiguredCalendars((_a = requirements._metadata) === null || _a === void 0 ? void 0 : _a.useCalendars);
+        if (parsedCommitment.calendar) {
+            addConfiguredCalendarIfMissing(existingConfiguredCalendars, parsedCommitment.calendar);
+        }
+        const calendarsList = existingConfiguredCalendars.length > 0
+            ? existingConfiguredCalendars
+                .map((calendar) => [
+                `- ${calendar.provider}: ${calendar.url}`,
+                calendar.scopes.length > 0 ? `  scopes: ${calendar.scopes.join(', ')}` : '',
+            ]
+                .filter(Boolean)
+                .join('\n'))
+                .join('\n')
+            : '- Calendar is resolved from runtime context';
+        const extraInstructions = formatOptionalInstructionBlock('Calendar instructions', parsedCommitment.instructions);
+        return this.appendToSystemMessage({
+            ...requirements,
+            tools: createUseCalendarTools(requirements.tools || []),
+            _metadata: {
+                ...requirements._metadata,
+                useCalendar: true,
+                useCalendars: existingConfiguredCalendars,
+            },
+        }, spaceTrim$1((block) => `
+                    Calendar tools:
+                    - You can inspect and manage events in configured calendars.
+                    - Supported operations include read, create, update, delete, invite guests, and reminders.
+                    - Configured calendars:
+                      ${block(calendarsList)}
+                    - USE CALENDAR credentials are read from wallet records (ACCESS_TOKEN, service "${UseCalendarWallet.service}", key "${UseCalendarWallet.key}").
+                    - If credentials are missing, ask user to connect calendar credentials in host UI and/or add them to wallet.
+                    ${block(extraInstructions)}
+                `));
+    }
+    /**
+     * Gets human-readable titles for tool functions provided by this commitment.
+     */
+    getToolTitles() {
+        return getUseCalendarToolTitles();
+    }
+    /**
+     * Gets calendar tool function implementations.
+     */
+    getToolFunctions() {
+        return createUseCalendarToolFunctions();
+    }
+}
+/**
+ * Adds calendar into configured calendars list if it is not already present.
+ *
+ * @private function of UseCalendarCommitmentDefinition
+ */
+function addConfiguredCalendarIfMissing(configuredCalendars, calendarReference) {
+    if (configuredCalendars.some((calendar) => calendar.provider === calendarReference.provider && calendar.url === calendarReference.url)) {
+        return;
+    }
+    configuredCalendars.push({
+        provider: calendarReference.provider,
+        url: calendarReference.url,
+        calendarId: calendarReference.calendarId,
+        scopes: [...calendarReference.scopes],
+        ...(calendarReference.tokenRef ? { tokenRef: calendarReference.tokenRef } : {}),
+    });
+}
+/**
+ * Note: [💞] Ignore a discrepancy between file name and entity name
+ */
+
 /**
  * Lightweight email token matcher used for `USE EMAIL` first-line parsing.
  *
@@ -14849,6 +16075,7 @@ const COMMITMENT_REGISTRY = [
     new UseTimeoutCommitmentDefinition(),
     new UseTimeCommitmentDefinition(),
     new UseUserLocationCommitmentDefinition(),
+    new UseCalendarCommitmentDefinition(),
     new UseEmailCommitmentDefinition(),
     new UsePopupCommitmentDefinition(),
     new UseImageGeneratorCommitmentDefinition('USE IMAGE GENERATOR'),
@@ -15845,6 +17072,14 @@ function parseAgentSource(agentSource) {
             });
             continue;
         }
+        if (commitment.type === 'USE CALENDAR') {
+            capabilities.push({
+                type: 'calendar',
+                label: 'Calendar',
+                iconName: 'Calendar',
+            });
+            continue;
+        }
         if (commitment.type === 'FROM') {
             const content = spaceTrim$2(commitment.content).split(/\r?\n/)[0] || '';
             if (content === 'Adam' || content === '' /* <- Note: Adam is implicit */) {