@withpica/mcp-server 1.3.0

package/dist/tools/notes.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Notes Tools — add and manage notes on works, people, and general catalog observations
+ *
+ * Backed by the assistant_memory system (type: "note") via REST routes (/api/admin/notes/*).
+ * Notes support auto-linking to works and people mentioned in the text via Tier 1 extraction.
+ */
+import { PicaClient } from "@withpica/mcp-sdk";
+import { ToolDefinition, ToolExecutor } from "./index.js";
+export declare class NotesTools {
+    private pica;
+    constructor(pica: PicaClient);
+    getTools(): Array<{
+        definition: ToolDefinition;
+        executor: ToolExecutor;
+    }>;
+    private listNotes;
+    private getNote;
+    private createNote;
+    private deleteNote;
+}
+//# sourceMappingURL=notes.d.ts.map

package/dist/tools/notes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notes.d.ts","sourceRoot":"","sources":["../../src/tools/notes.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,cAAc,EAAE,YAAY,EAAc,MAAM,YAAY,CAAC;AAGtE,qBAAa,UAAU;IACrB,OAAO,CAAC,IAAI,CAAa;gBAEb,IAAI,EAAE,UAAU;IAI5B,QAAQ,IAAI,KAAK,CAAC;QAAE,UAAU,EAAE,cAAc,CAAC;QAAC,QAAQ,EAAE,YAAY,CAAA;KAAE,CAAC;YAyF3D,SAAS;YAWT,OAAO;YAKP,UAAU;YAKV,UAAU;CAIzB"}

package/dist/tools/notes.js

@@ -0,0 +1,115 @@
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+import { formatSuccess, formatStructuredList } from "@withpica/mcp-utils";
+export class NotesTools {
+    pica;
+    constructor(pica) {
+        this.pica = pica;
+    }
+    getTools() {
+        return [
+            {
+                definition: {
+                    name: "pica_notes_list",
+                    description: "List notes — filter by search query, linked work, or linked person. Notes can be attached to works, people, or stand alone.",
+                    workflows: "infrastructure",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            q: {
+                                type: "string",
+                                description: "Search notes by content or title",
+                            },
+                            work_id: {
+                                type: "string",
+                                description: "Filter notes linked to a specific work",
+                            },
+                            person_id: {
+                                type: "string",
+                                description: "Filter notes linked to a specific person",
+                            },
+                            limit: {
+                                type: "number",
+                                description: "Max results (default 20)",
+                            },
+                        },
+                    },
+                },
+                executor: this.listNotes.bind(this),
+            },
+            {
+                definition: {
+                    name: "pica_notes_get",
+                    description: "Get a specific note by ID.",
+                    workflows: "infrastructure",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            id: { type: "string", description: "Note ID" },
+                        },
+                        required: ["id"],
+                    },
+                },
+                executor: this.getNote.bind(this),
+            },
+            {
+                definition: {
+                    name: "pica_notes_create",
+                    description: "Add a note to the catalog. Notes can be linked to specific works or people, or stand alone as general observations. PICA auto-detects mentions of works and people in the note text. " +
+                        "Stored as `assistant_memory` rows with type='note' — other assistant_memory columns " +
+                        "(scope, type, key, confidence, source, expires_at, metadata) are service-managed by " +
+                        "captureNote() and not settable from the tool surface.",
+                    workflows: "infrastructure",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            content: {
+                                type: "string",
+                                description: "The note text. Mention work titles or people names — PICA auto-links entities via AI extraction.",
+                            },
+                        },
+                        required: ["content"],
+                    },
+                },
+                executor: this.createNote.bind(this),
+            },
+            {
+                definition: {
+                    name: "pica_notes_delete",
+                    description: "Delete a catalog note by id (destructive — no undo).",
+                    workflows: "infrastructure",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            id: { type: "string", description: "Note ID to delete" },
+                        },
+                        required: ["id"],
+                    },
+                },
+                executor: this.deleteNote.bind(this),
+            },
+        ];
+    }
+    async listNotes(args) {
+        const result = await this.pica.notes.list({
+            q: args.q,
+            work: args.work_id,
+            person: args.person_id,
+            limit: args.limit,
+        });
+        const notes = Array.isArray(result) ? result : [];
+        return formatStructuredList(notes, "note");
+    }
+    async getNote(args) {
+        const note = await this.pica.notes.get(args.id);
+        return formatSuccess("Note retrieved", note);
+    }
+    async createNote(args) {
+        const note = await this.pica.notes.create(args.content);
+        return formatSuccess("Note added", note);
+    }
+    async deleteNote(args) {
+        await this.pica.notes.delete(args.id);
+        return formatSuccess(`Note ${args.id} deleted`);
+    }
+}
+//# sourceMappingURL=notes.js.map

package/dist/tools/notes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"notes.js","sourceRoot":"","sources":["../../src/tools/notes.ts"],"names":[],"mappings":"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"}

package/dist/tools/notifications.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Notifications Tools — check and manage PICA notifications via MCP
+ */
+import { PicaClient } from "@withpica/mcp-sdk";
+import { ToolDefinition, ToolExecutor } from "./index.js";
+export declare class NotificationsTools {
+    private pica;
+    constructor(pica: PicaClient);
+    getTools(): Array<{
+        definition: ToolDefinition;
+        executor: ToolExecutor;
+    }>;
+    /**
+     * ADR-218 Primitive B — read the cross-transport notification feed.
+     */
+    private discoveriesRecent;
+    /**
+     * ADR-218 Primitive C — acknowledge cross-transport notifications.
+     */
+    private discoveriesAcknowledge;
+    private listPending;
+    private cancelPending;
+    private notifyUserAt;
+    private listNotifications;
+    private notifyPerson;
+    private markRead;
+}
+//# sourceMappingURL=notifications.d.ts.map

package/dist/tools/notifications.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notifications.d.ts","sourceRoot":"","sources":["../../src/tools/notifications.ts"],"names":[],"mappings":"AAGA;;GAEG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,cAAc,EAAE,YAAY,EAAc,MAAM,YAAY,CAAC;AAQtE,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,IAAI,CAAa;gBAEb,IAAI,EAAE,UAAU;IAI5B,QAAQ,IAAI,KAAK,CAAC;QAAE,UAAU,EAAE,cAAc,CAAC;QAAC,QAAQ,EAAE,YAAY,CAAA;KAAE,CAAC;IAsLzE;;OAEG;YACW,iBAAiB;IAwE/B;;OAEG;YACW,sBAAsB;YAkCtB,WAAW;YAeX,aAAa;YAuCb,YAAY;YA4CZ,iBAAiB;YAoBjB,YAAY;YA0CZ,QAAQ;CAOvB"}

package/dist/tools/notifications.js

@@ -0,0 +1,417 @@
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { formatAsText, formatSuccess, formatStructuredList, formatValidationError, } from "@withpica/mcp-utils";
+export class NotificationsTools {
+    pica;
+    constructor(pica) {
+        this.pica = pica;
+    }
+    getTools() {
+        return [
+            {
+                definition: {
+                    name: "pica_notifications_list",
+                    description: "Check for notifications from PICA — new collaborator invites, " +
+                        "enrichment results, verification requests, credit disputes, " +
+                        "and other flagged items that need attention.",
+                    workflows: "infrastructure",
+                    inputSchema: {
+                        type: "object",
+                        properties: {},
+                    },
+                },
+                executor: this.listNotifications.bind(this),
+            },
+            {
+                definition: {
+                    name: "pica_notify_person",
+                    description: "Send a notification to a person in the catalog. If the person has a PICA account, " +
+                        "they get an in-app notification + Telegram message (if connected). " +
+                        "If they're not a PICA user yet, returns a hint to use pica_collaborators_invite instead. " +
+                        "Use for credit verification requests, song updates, or any message to a collaborator.",
+                    workflows: "infrastructure",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            person_id: {
+                                type: "string",
+                                description: "The person's ID in your catalog",
+                            },
+                            message: {
+                                type: "string",
+                                description: "What to tell them (e.g. 'please verify your writing credit on Midnight Run')",
+                            },
+                            work_id: {
+                                type: "string",
+                                description: "Optional work ID for context — links the notification to a specific work",
+                            },
+                        },
+                        required: ["person_id", "message"],
+                    },
+                },
+                executor: this.notifyPerson.bind(this),
+            },
+            {
+                definition: {
+                    name: "pica_notifications_mark_read",
+                    description: "Mark one or more notifications as read.",
+                    workflows: "infrastructure",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            notification_ids: {
+                                type: "array",
+                                items: { type: "string" },
+                                description: "IDs of notifications to mark as read",
+                            },
+                        },
+                        required: ["notification_ids"],
+                    },
+                },
+                executor: this.markRead.bind(this),
+            },
+            {
+                definition: {
+                    name: "pica_notify_user_at",
+                    description: "Schedule a one-shot Telegram reminder for the future. The user can ask for reminders in any natural phrasing — 'remind me tomorrow at 9', 'ping me in 2 hours', 'check on this next monday'. Convert their phrasing to an ISO 8601 UTC timestamp before calling. Ask the user for their timezone once if you don't already know it. The message body IS the receipt — make it self-contained so the user reading it cold knows what to do. Delivery goes via Telegram, so pica_telegram_connect must be paired first. Per-user cap: 100 pending reminders.",
+                    workflows: "infrastructure",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            message: {
+                                type: "string",
+                                description: "The reminder body text. Self-contained — include enough context that the user reading it cold knows what to do. 1-4000 characters.",
+                            },
+                            deliver_at: {
+                                type: "string",
+                                description: "ISO 8601 UTC timestamp. Must be in the future and within 1 year. Convert from natural language using the user's timezone — ask first if you don't know it.",
+                            },
+                        },
+                        required: ["message", "deliver_at"],
+                    },
+                },
+                executor: this.notifyUserAt.bind(this),
+            },
+            {
+                definition: {
+                    name: "pica_notify_user_list_pending",
+                    description: "List all pending scheduled Telegram reminders for the current user, ordered by deliver_at ascending. Use to show the user what reminders are queued or to find an id for pica_notify_user_cancel.",
+                    workflows: "infrastructure",
+                    inputSchema: { type: "object", properties: {} },
+                },
+                executor: this.listPending.bind(this),
+            },
+            {
+                definition: {
+                    name: "pica_notify_user_cancel",
+                    description: "Cancel a pending scheduled reminder by id. Idempotent — if the reminder was already delivered or already cancelled, this surfaces that state gracefully instead of erroring. Use cancel + pica_notify_user_at together to reschedule a reminder.",
+                    workflows: "infrastructure",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            id: {
+                                type: "string",
+                                description: "The scheduled_notifications row id — get it from pica_notify_user_list_pending or from the response of pica_notify_user_at.",
+                            },
+                        },
+                        required: ["id"],
+                    },
+                },
+                executor: this.cancelPending.bind(this),
+            },
+            // --- ADR-218 cross-transport awareness ---
+            {
+                definition: {
+                    name: "pica_notifications_recent",
+                    description: "Read the recent cross-transport notification feed for the org — events that PICA has surfaced about your catalog (credit disputes, enrichment matches, " +
+                        "audio analysis outcomes, etc.). Distinct from `pica_notifications_list`: this reads the `discovery_events` ledger that " +
+                        "ALL surfaces (MCP, Telegram, web, email) share, so it stays in sync with what was sent to the user's Telegram channel. " +
+                        "Pass `unread_only: true` to see only events the agent has not yet acknowledged via " +
+                        "`pica_notification_acknowledge`. Default limit 20, max 100. The agent's ambient envelope at " +
+                        "_meta.session_state.notifications.unread_count tells you whether there's anything new before you call this.",
+                    workflows: "infrastructure",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            limit: {
+                                type: "number",
+                                description: "Optional. Default 20, max 100. Number of recent events to return.",
+                            },
+                            unread_only: {
+                                type: "boolean",
+                                description: "Optional. When true, filters to events the MCP surface has not acknowledged.",
+                            },
+                        },
+                    },
+                },
+                executor: this.discoveriesRecent.bind(this),
+            },
+            {
+                definition: {
+                    name: "pica_notification_acknowledge",
+                    description: "Acknowledge one or more cross-transport notifications. Appends 'mcp' to the event's `seen_in` array — " +
+                        "idempotent, so re-acknowledging is a safe no-op. Once acknowledged, the same event will NOT be re-fired to " +
+                        "the user's Telegram channel on subsequent emits of the same dedup key (until_resolved-strategy alerts like " +
+                        "credits_low_balance, system_warning, cascade_proposal_created). Use after summarising the events to the user " +
+                        "or after taking the action they describe — keeps the user from being re-pinged about the same thing on " +
+                        "another surface.",
+                    workflows: "infrastructure",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            event_ids: {
+                                type: "array",
+                                items: { type: "string" },
+                                description: "Discovery event UUIDs returned from `pica_notifications_recent`.",
+                            },
+                        },
+                        required: ["event_ids"],
+                    },
+                },
+                executor: this.discoveriesAcknowledge.bind(this),
+            },
+        ];
+    }
+    /**
+     * ADR-218 Primitive B — read the cross-transport notification feed.
+     */
+    async discoveriesRecent(args) {
+        const limit = typeof args.limit === "number" ? args.limit : undefined;
+        const unreadOnly = typeof args.unread_only === "boolean" ? args.unread_only : false;
+        try {
+            const events = await this.pica.discoveries.recent({
+                limit,
+                unreadOnly,
+            });
+            if (events.length === 0) {
+                return formatAsText({
+                    count: 0,
+                    unread_only: unreadOnly,
+                    message: unreadOnly
+                        ? "No unacknowledged notifications. The agent's inbox is clear."
+                        : "No recent notifications in the cross-transport feed.",
+                });
+            }
+            const summary = events.slice(0, 10).map((e) => {
+                const ackTag = e.seen_in.includes("mcp") ? " (acknowledged)" : "";
+                return `[${e.severity}] ${e.title}${ackTag} — ${e.event_type} @ ${e.created_at}`;
+            });
+            const more = events.length > 10
+                ? `\n\n_+${events.length - 10} more — pass a higher limit to see them._`
+                : "";
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `${events.length} notification${events.length === 1 ? "" : "s"}${unreadOnly ? " (unacknowledged)" : ""}:\n\n${summary.join("\n")}${more}`,
+                    },
+                ],
+                structuredContent: {
+                    kind: "pica.card.notifications_recent",
+                    version: 1,
+                    data: {
+                        count: events.length,
+                        unread_only: unreadOnly,
+                        events: events.map((e) => ({
+                            id: e.id,
+                            event_type: e.event_type,
+                            category: e.category,
+                            title: e.title,
+                            description: e.description,
+                            entity_type: e.entity_type,
+                            entity_id: e.entity_id,
+                            entity_name: e.entity_name,
+                            severity: e.severity,
+                            source: e.source,
+                            link: e.link,
+                            happened_at: e.created_at,
+                            seen_in: e.seen_in,
+                            acknowledged_by_mcp: e.seen_in.includes("mcp"),
+                        })),
+                    },
+                },
+            };
+        }
+        catch (err) {
+            return formatAsText({
+                error: `Failed to fetch recent notifications: ${err?.message || String(err)}`,
+            });
+        }
+    }
+    /**
+     * ADR-218 Primitive C — acknowledge cross-transport notifications.
+     */
+    async discoveriesAcknowledge(args) {
+        const ids = Array.isArray(args.event_ids)
+            ? args.event_ids.filter((v) => typeof v === "string" && v.length > 0)
+            : [];
+        if (ids.length === 0) {
+            return formatValidationError({
+                event_ids: "event_ids must be a non-empty array of UUID strings",
+            });
+        }
+        try {
+            const result = await this.pica.discoveries.acknowledge(ids);
+            return formatSuccess(result.acknowledged === 0
+                ? "Already acknowledged — no rows changed."
+                : `Acknowledged ${result.acknowledged} of ${ids.length} notification${ids.length === 1 ? "" : "s"} for the MCP surface.`, {
+                acknowledged: result.acknowledged,
+                surface: result.surface,
+                requested: ids.length,
+            });
+        }
+        catch (err) {
+            return formatAsText({
+                error: `Failed to acknowledge notifications: ${err?.message || String(err)}`,
+            });
+        }
+    }
+    async listPending(_args) {
+        try {
+            const result = await this.pica.notifications.listScheduled();
+            const data = result?.data || result || [];
+            const items = Array.isArray(data) ? data : [];
+            return formatStructuredList(items, "scheduled reminder", {
+                count: items.length,
+            });
+        }
+        catch (err) {
+            return formatAsText({
+                error: `Failed to list pending reminders: ${err?.message || String(err)}`,
+            });
+        }
+    }
+    async cancelPending(args) {
+        if (!args.id || typeof args.id !== "string") {
+            return formatValidationError({ id: "id is required" });
+        }
+        try {
+            const result = await this.pica.notifications.cancelScheduled(args.id);
+            const data = result?.data || result;
+            if (data?.status === "sent") {
+                return formatAsText({
+                    cancelled: false,
+                    status: "sent",
+                    message: `Already delivered on ${data.sent_at} — can't cancel.`,
+                    data,
+                });
+            }
+            if (data?.status === "cancelled" && data?.deliver_at) {
+                return formatSuccess(`Cancelled — was scheduled for ${data.deliver_at}.`, { cancelled: true, id: data.id, deliver_at: data.deliver_at });
+            }
+            if (data?.status === "failed") {
+                return formatAsText({
+                    cancelled: false,
+                    status: "failed",
+                    message: `Reminder already marked failed: ${data.error_text || "unknown"}`,
+                    data,
+                });
+            }
+            return formatSuccess("Cancelled.", { cancelled: true, data });
+        }
+        catch (err) {
+            const message = err?.message || String(err);
+            return formatAsText({
+                cancelled: false,
+                error: `Failed to cancel reminder: ${message}`,
+            });
+        }
+    }
+    async notifyUserAt(args) {
+        if (!args.message ||
+            typeof args.message !== "string" ||
+            !args.message.trim()) {
+            return formatValidationError({ message: "message is required" });
+        }
+        if (!args.deliver_at || typeof args.deliver_at !== "string") {
+            return formatValidationError({
+                deliver_at: "deliver_at is required (ISO 8601 UTC)",
+            });
+        }
+        try {
+            const result = await this.pica.notifications.schedule({
+                message: args.message.trim(),
+                deliverAt: args.deliver_at,
+                source: typeof args.source === "string" ? args.source : undefined,
+            });
+            const data = result?.data || result;
+            return formatSuccess(`Reminder scheduled for ${data.deliver_at}. I'll ping you on Telegram when it fires.`, {
+                id: data.id,
+                deliver_at: data.deliver_at,
+                message: data.message,
+                status: data.status,
+                completion_hints: {
+                    list: "pica_notify_user_list_pending",
+                    cancel: "pica_notify_user_cancel",
+                },
+            });
+        }
+        catch (err) {
+            const message = err?.message || String(err);
+            return formatAsText({
+                scheduled: false,
+                error: `Failed to schedule reminder: ${message}`,
+            });
+        }
+    }
+    async listNotifications(_args) {
+        try {
+            const result = await this.pica.notifications.list();
+            const notifications = result?.notifications || result || [];
+            const items = Array.isArray(notifications) ? notifications : [];
+            const unread = items.filter((n) => !n.read_at);
+            return formatStructuredList(items, "notification", {
+                total: items.length,
+                unread: unread.length,
+            });
+        }
+        catch (err) {
+            return formatAsText({
+                error: `Failed to list notifications: ${err?.message || String(err)}`,
+            });
+        }
+    }
+    async notifyPerson(args) {
+        if (!args.person_id?.trim()) {
+            return formatValidationError({ person_id: "person_id is required" });
+        }
+        if (!args.message?.trim()) {
+            return formatValidationError({ message: "message is required" });
+        }
+        try {
+            const result = await this.pica.notifications.sendToPerson({
+                person_id: args.person_id,
+                message: args.message,
+                work_id: args.work_id,
+            });
+            const data = result.data || result;
+            if (!data.delivered) {
+                return formatAsText({
+                    delivered: false,
+                    person_name: data.person_name,
+                    reason: data.reason,
+                    hint: data.hint,
+                });
+            }
+            const channels = [];
+            if (data.channels?.in_app)
+                channels.push("in-app");
+            if (data.channels?.telegram)
+                channels.push("Telegram");
+            if (data.channels?.email)
+                channels.push("email");
+            return formatSuccess(`Notified ${data.person_name} via ${channels.join(" + ")}`, data);
+        }
+        catch (err) {
+            return formatAsText({
+                error: `Failed to notify person: ${err?.message || String(err)}`,
+            });
+        }
+    }
+    async markRead(args) {
+        const ids = args.notification_ids;
+        await this.pica.notifications.markRead(ids);
+        return formatSuccess(`Marked ${ids.length} notification${ids.length !== 1 ? "s" : ""} as read`);
+    }
+}
+//# sourceMappingURL=notifications.js.map

package/dist/tools/notifications.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"notifications.js","sourceRoot":"","sources":["../../src/tools/notifications.ts"],"names":[],"mappings":"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"}

package/dist/tools/onboarding.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Onboarding Tools — pica_acknowledge_onboarding.
+ *
+ * OAuth-from-MCP signups (Claude.ai / ChatGPT / Cursor) bypass the
+ * /onboarding wizard via the auth/callback isOAuthSignup branch.
+ * The /api/mcp gate at handleMcpRequest then refuses every other
+ * tool until the agent walks the user through identity / security
+ * / intent and calls this tool to flip
+ * user_profiles.mcp_onboarding_acknowledged=true.
+ *
+ * Companion to fix/oauth-new-user-signup-redirect (Stage 3).
+ */
+import { PicaClient } from "@withpica/mcp-sdk";
+import { ToolDefinition, ToolExecutor } from "./index.js";
+export declare class OnboardingTools {
+    private pica;
+    constructor(pica: PicaClient);
+    getTools(): Array<{
+        definition: ToolDefinition;
+        executor: ToolExecutor;
+    }>;
+    private acknowledge;
+}
+//# sourceMappingURL=onboarding.d.ts.map

package/dist/tools/onboarding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"onboarding.d.ts","sourceRoot":"","sources":["../../src/tools/onboarding.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,cAAc,EAAE,YAAY,EAAc,MAAM,YAAY,CAAC;AAEtE,qBAAa,eAAe;IAC1B,OAAO,CAAC,IAAI,CAAa;gBAEb,IAAI,EAAE,UAAU;IAI5B,QAAQ,IAAI,KAAK,CAAC;QAAE,UAAU,EAAE,cAAc,CAAC;QAAC,QAAQ,EAAE,YAAY,CAAA;KAAE,CAAC;YAuC3D,WAAW;CA6C1B"}