@agentlensai/server 0.2.0 → 0.5.0

package/dist/lib/analysis/tool-sequences.js

@@ -0,0 +1,145 @@
+/**
+ * Tool Sequence Analysis (Story 4.2)
+ *
+ * Analyzes tool_call events to extract N-grams (2-grams and 3-grams)
+ * of tool sequences per session, and identifies error-prone sequences.
+ */
+/**
+ * Analyze tool usage sequences across sessions.
+ */
+export async function analyzeToolSequences(store, opts = {}) {
+    const limit = opts.limit ?? 20;
+    // Query tool_call events
+    const toolCallResult = await store.queryEvents({
+        agentId: opts.agentId,
+        from: opts.from,
+        to: opts.to,
+        eventType: 'tool_call',
+        limit: 500,
+        order: 'asc',
+    });
+    // Also query tool_error events to identify error-prone sequences
+    const toolErrorResult = await store.queryEvents({
+        agentId: opts.agentId,
+        from: opts.from,
+        to: opts.to,
+        eventType: 'tool_error',
+        limit: 500,
+        order: 'asc',
+    });
+    const allToolCalls = toolCallResult.events;
+    const allToolErrors = toolErrorResult.events;
+    const eventsAnalyzed = allToolCalls.length + allToolErrors.length;
+    const timeRange = {
+        from: allToolCalls.length > 0 ? allToolCalls[0].timestamp : (opts.from ?? ''),
+        to: allToolCalls.length > 0 ? allToolCalls[allToolCalls.length - 1].timestamp : (opts.to ?? ''),
+    };
+    // Group tool_call events by session
+    const sessionToolCalls = new Map();
+    for (const event of allToolCalls) {
+        const list = sessionToolCalls.get(event.sessionId) ?? [];
+        list.push(event);
+        sessionToolCalls.set(event.sessionId, list);
+    }
+    // Group tool_error events by session for error-prone detection
+    const sessionErrors = new Map();
+    for (const event of allToolErrors) {
+        const list = sessionErrors.get(event.sessionId) ?? [];
+        list.push(event);
+        sessionErrors.set(event.sessionId, list);
+    }
+    // Extract tool names per session (ordered by timestamp)
+    const uniqueToolsSet = new Set();
+    let totalCalls = 0;
+    const sessionToolNames = new Map();
+    for (const [sessionId, calls] of sessionToolCalls) {
+        const names = calls.map((e) => {
+            const p = e.payload;
+            const name = String(p.toolName ?? 'unknown');
+            uniqueToolsSet.add(name);
+            return name;
+        });
+        sessionToolNames.set(sessionId, names);
+        totalCalls += names.length;
+    }
+    // Extract N-grams and count frequencies
+    // key = tools joined by "→", value = { frequency across sessions, set of sessions, errorFollowed count }
+    const ngramMap = new Map();
+    for (const [sessionId, toolNames] of sessionToolNames) {
+        const sessionErrorEvents = sessionErrors.get(sessionId) ?? [];
+        // Get the full session timeline for error-proximity checks
+        const sessionCalls = sessionToolCalls.get(sessionId) ?? [];
+        // Extract 2-grams and 3-grams
+        const seenInSession = new Set(); // Avoid counting same ngram twice per session
+        for (const n of [2, 3]) {
+            for (let i = 0; i <= toolNames.length - n; i++) {
+                const ngram = toolNames.slice(i, i + n);
+                const key = ngram.join('→');
+                if (!seenInSession.has(key)) {
+                    seenInSession.add(key);
+                    let entry = ngramMap.get(key);
+                    if (!entry) {
+                        entry = { tools: ngram, frequency: 0, sessions: new Set(), errorFollowed: 0 };
+                        ngramMap.set(key, entry);
+                    }
+                    entry.frequency++;
+                    entry.sessions.add(sessionId);
+                }
+                // Check if this ngram is followed by an error within 2 events
+                // The last event of the ngram is at index i + n - 1 in sessionCalls
+                const lastCallInNgram = sessionCalls[i + n - 1];
+                if (lastCallInNgram) {
+                    const isErrorFollowed = sessionErrorEvents.some((errEvt) => {
+                        // Error must be after the last tool call in ngram
+                        // and within 2 "event positions" (by timestamp)
+                        if (errEvt.timestamp < lastCallInNgram.timestamp)
+                            return false;
+                        // Count how many tool_call events are between the last ngram call and the error
+                        const callsAfter = sessionCalls.filter((c) => c.timestamp > lastCallInNgram.timestamp && c.timestamp <= errEvt.timestamp);
+                        return callsAfter.length <= 2;
+                    });
+                    if (isErrorFollowed) {
+                        // We only count this once per session per ngram for error rate calculation
+                        // But we need to track total occurrences vs error-followed
+                        let entry = ngramMap.get(key);
+                        // Track on first occurrence in session
+                        if (seenInSession.has(`${key}:error-checked`))
+                            continue;
+                        seenInSession.add(`${key}:error-checked`);
+                        entry.errorFollowed++;
+                    }
+                }
+            }
+        }
+    }
+    // Calculate stats
+    const sessionLengths = Array.from(sessionToolNames.values()).map((n) => n.length);
+    const avgSequenceLength = sessionLengths.length > 0
+        ? sessionLengths.reduce((a, b) => a + b, 0) / sessionLengths.length
+        : 0;
+    // Build sorted results
+    const sequences = Array.from(ngramMap.values())
+        .map((entry) => ({
+        tools: entry.tools,
+        frequency: entry.frequency,
+        sessions: entry.sessions.size,
+        errorRate: entry.sessions.size > 0
+            ? entry.errorFollowed / entry.sessions.size
+            : 0,
+    }))
+        .sort((a, b) => b.frequency - a.frequency)
+        .slice(0, limit);
+    return {
+        sequences,
+        stats: {
+            avgSequenceLength: Math.round(avgSequenceLength * 100) / 100,
+            uniqueTools: uniqueToolsSet.size,
+            totalCalls,
+        },
+        metadata: {
+            eventsAnalyzed,
+            timeRange,
+        },
+    };
+}
+//# sourceMappingURL=tool-sequences.js.map

package/dist/lib/analysis/tool-sequences.js.map

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

package/dist/lib/context/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Context Retrieval — exports (Epic 5)
+ */
+export { ContextRetriever } from './retrieval.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/lib/context/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/context/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/lib/context/index.js

@@ -0,0 +1,5 @@
+/**
+ * Context Retrieval — exports (Epic 5)
+ */
+export { ContextRetriever } from './retrieval.js';
+//# sourceMappingURL=index.js.map

package/dist/lib/context/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/lib/context/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/lib/context/retrieval.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Context Retriever (Story 5.2)
+ *
+ * Combines semantic search over session summaries, lesson search,
+ * and key event retrieval to build cross-session context.
+ *
+ * Falls back to text search when embeddings are unavailable.
+ */
+import type { ContextQuery, ContextResult } from '@agentlensai/core';
+import type { EmbeddingStore } from '../../db/embedding-store.js';
+import type { EmbeddingService } from '../embeddings/index.js';
+import type { SessionSummaryStore } from '../../db/session-summary-store.js';
+import type { LessonStore } from '../../db/lesson-store.js';
+import type { IEventStore } from '@agentlensai/core';
+export declare class ContextRetriever {
+    private readonly embeddingStore;
+    private readonly embeddingService;
+    private readonly sessionSummaryStore;
+    private readonly lessonStore;
+    private readonly eventStore;
+    constructor(embeddingStore: EmbeddingStore | null, embeddingService: EmbeddingService | null, sessionSummaryStore: SessionSummaryStore, lessonStore: LessonStore, eventStore: IEventStore);
+    /**
+     * Retrieve cross-session context by combining:
+     * 1. Semantic search over session summary embeddings
+     * 2. Lesson search (semantic or text-based)
+     * 3. Key events for matching sessions
+     * 4. Ranking by relevance + recency
+     */
+    retrieve(tenantId: string, query: ContextQuery): Promise<ContextResult>;
+    /**
+     * Find relevant sessions using semantic search (with text search fallback).
+     */
+    private findRelevantSessions;
+    /**
+     * Filter semantic search results by agentId/userId and rank by relevance + recency.
+     */
+    private filterAndRankSessions;
+    /**
+     * Text search fallback when embeddings are unavailable.
+     */
+    private textSearchSessions;
+    /**
+     * Find relevant lessons using semantic search (with text search fallback).
+     */
+    private findRelevantLessons;
+    /**
+     * Enrich a session result with key events from the timeline.
+     */
+    private enrichSessionWithEvents;
+    /**
+     * Compute a recency boost (0-1) based on how recent the content is.
+     * Items from the last 24h get ~1.0, items from 30+ days ago get ~0.0.
+     */
+    private computeRecencyBoost;
+}
+//# sourceMappingURL=retrieval.d.ts.map

package/dist/lib/context/retrieval.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retrieval.d.ts","sourceRoot":"","sources":["../../../src/lib/context/retrieval.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAkD,MAAM,mBAAmB,CAAC;AACrH,OAAO,KAAK,EAAE,cAAc,EAAoB,MAAM,6BAA6B,CAAC;AACpF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,KAAK,EAAE,mBAAmB,EAAwB,MAAM,mCAAmC,CAAC;AACnG,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AASrD,qBAAa,gBAAgB;IAEzB,OAAO,CAAC,QAAQ,CAAC,cAAc;IAC/B,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IACjC,OAAO,CAAC,QAAQ,CAAC,mBAAmB;IACpC,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,UAAU;gBAJV,cAAc,EAAE,cAAc,GAAG,IAAI,EACrC,gBAAgB,EAAE,gBAAgB,GAAG,IAAI,EACzC,mBAAmB,EAAE,mBAAmB,EACxC,WAAW,EAAE,WAAW,EACxB,UAAU,EAAE,WAAW;IAG1C;;;;;;OAMG;IACG,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,aAAa,CAAC;IAsB7E;;OAEG;YACW,oBAAoB;IA6BlC;;OAEG;YACW,qBAAqB;IAwCnC;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAqB1B;;OAEG;YACW,mBAAmB;IAwDjC;;OAEG;YACW,uBAAuB;IA+CrC;;;OAGG;IACH,OAAO,CAAC,mBAAmB;CAU5B"}

package/dist/lib/context/retrieval.js

@@ -0,0 +1,229 @@
+/**
+ * Context Retriever (Story 5.2)
+ *
+ * Combines semantic search over session summaries, lesson search,
+ * and key event retrieval to build cross-session context.
+ *
+ * Falls back to text search when embeddings are unavailable.
+ */
+import { summarizeEvent } from '../embeddings/summarizer.js';
+/** Default maximum results */
+const DEFAULT_LIMIT = 10;
+/** Maximum key events per session in results */
+const MAX_KEY_EVENTS = 5;
+export class ContextRetriever {
+    embeddingStore;
+    embeddingService;
+    sessionSummaryStore;
+    lessonStore;
+    eventStore;
+    constructor(embeddingStore, embeddingService, sessionSummaryStore, lessonStore, eventStore) {
+        this.embeddingStore = embeddingStore;
+        this.embeddingService = embeddingService;
+        this.sessionSummaryStore = sessionSummaryStore;
+        this.lessonStore = lessonStore;
+        this.eventStore = eventStore;
+    }
+    /**
+     * Retrieve cross-session context by combining:
+     * 1. Semantic search over session summary embeddings
+     * 2. Lesson search (semantic or text-based)
+     * 3. Key events for matching sessions
+     * 4. Ranking by relevance + recency
+     */
+    async retrieve(tenantId, query) {
+        const limit = query.limit ?? DEFAULT_LIMIT;
+        // Step 1: Find relevant sessions
+        const sessionResults = await this.findRelevantSessions(tenantId, query, limit);
+        // Step 2: Find relevant lessons
+        const lessonResults = await this.findRelevantLessons(tenantId, query, limit);
+        // Step 3: For each matching session, get key events
+        const sessionsWithEvents = await Promise.all(sessionResults.map((s) => this.enrichSessionWithEvents(tenantId, s)));
+        return {
+            topic: query.topic,
+            sessions: sessionsWithEvents,
+            lessons: lessonResults,
+            totalSessions: sessionsWithEvents.length,
+        };
+    }
+    /**
+     * Find relevant sessions using semantic search (with text search fallback).
+     */
+    async findRelevantSessions(tenantId, query, limit) {
+        // Try semantic search first
+        if (this.embeddingService && this.embeddingStore) {
+            try {
+                const queryVector = await this.embeddingService.embed(query.topic);
+                const results = this.embeddingStore.similaritySearch(tenantId, queryVector, {
+                    sourceType: 'session',
+                    from: query.from,
+                    to: query.to,
+                    limit: limit * 2, // over-fetch for post-filtering
+                    minScore: 0.3,
+                });
+                if (results.length > 0) {
+                    return this.filterAndRankSessions(tenantId, results, query, limit);
+                }
+            }
+            catch {
+                // Fall through to text search
+            }
+        }
+        // Fallback: text search on session summaries
+        return this.textSearchSessions(tenantId, query, limit);
+    }
+    /**
+     * Filter semantic search results by agentId/userId and rank by relevance + recency.
+     */
+    async filterAndRankSessions(tenantId, results, query, limit) {
+        const sessions = [];
+        for (const result of results) {
+            // sourceId is the sessionId for session-scope embeddings
+            const sessionId = result.sourceId;
+            // Filter by agentId if provided
+            if (query.agentId) {
+                const session = await this.eventStore.getSession(sessionId);
+                if (!session || session.agentId !== query.agentId)
+                    continue;
+            }
+            // Get the summary text from the store (richer than embedding text)
+            const summaryRecord = this.sessionSummaryStore.get(tenantId, sessionId);
+            const summary = summaryRecord?.summary ?? result.text;
+            // Recency boost: more recent sessions score slightly higher
+            const recencyBoost = this.computeRecencyBoost(result.createdAt);
+            const adjustedScore = result.score * 0.85 + recencyBoost * 0.15;
+            sessions.push({
+                sessionId,
+                summary,
+                relevanceScore: Math.round(adjustedScore * 10000) / 10000,
+            });
+            if (sessions.length >= limit)
+                break;
+        }
+        // Sort by adjusted score descending
+        sessions.sort((a, b) => b.relevanceScore - a.relevanceScore);
+        return sessions.slice(0, limit);
+    }
+    /**
+     * Text search fallback when embeddings are unavailable.
+     */
+    textSearchSessions(tenantId, query, limit) {
+        const results = this.sessionSummaryStore.search(tenantId, query.topic, limit * 2);
+        let filtered = results;
+        // If agentId filter is needed, we need to cross-reference sessions
+        // For text search, we can't easily filter by agentId synchronously here,
+        // so we'll skip that filter for the text fallback (best effort)
+        return filtered.slice(0, limit).map((r, index) => ({
+            sessionId: r.sessionId,
+            summary: r.summary,
+            // Assign a decreasing relevance score for text search results (1.0 → 0.5)
+            relevanceScore: Math.round((1.0 - index * (0.5 / Math.max(limit, 1))) * 10000) / 10000,
+        }));
+    }
+    /**
+     * Find relevant lessons using semantic search (with text search fallback).
+     */
+    async findRelevantLessons(tenantId, query, limit) {
+        // Try semantic search first
+        if (this.embeddingService && this.embeddingStore) {
+            try {
+                const queryVector = await this.embeddingService.embed(query.topic);
+                const results = this.embeddingStore.similaritySearch(tenantId, queryVector, {
+                    sourceType: 'lesson',
+                    limit,
+                    minScore: 0.3,
+                });
+                if (results.length > 0) {
+                    const lessons = [];
+                    for (const result of results) {
+                        const lesson = this.lessonStore.get(tenantId, result.sourceId);
+                        if (lesson) {
+                            lessons.push({
+                                id: lesson.id,
+                                title: lesson.title,
+                                content: lesson.content,
+                                category: lesson.category,
+                                importance: lesson.importance,
+                                relevanceScore: Math.round(result.score * 10000) / 10000,
+                            });
+                        }
+                    }
+                    return lessons;
+                }
+            }
+            catch {
+                // Fall through to text search
+            }
+        }
+        // Fallback: text search on lessons
+        const textResults = this.lessonStore.list(tenantId, {
+            search: query.topic,
+            limit,
+        });
+        return textResults.map((lesson, index) => ({
+            id: lesson.id,
+            title: lesson.title,
+            content: lesson.content,
+            category: lesson.category,
+            importance: lesson.importance,
+            // Assign decreasing scores for text search results
+            relevanceScore: Math.round((1.0 - index * (0.5 / Math.max(limit, 1))) * 10000) / 10000,
+        }));
+    }
+    /**
+     * Enrich a session result with key events from the timeline.
+     */
+    async enrichSessionWithEvents(tenantId, session) {
+        // Get session metadata for startedAt/endedAt/agentId
+        const sessionRecord = await this.eventStore.getSession(session.sessionId);
+        // Get timeline events for key event extraction
+        let keyEvents = [];
+        try {
+            const timeline = await this.eventStore.getSessionTimeline(session.sessionId);
+            // Extract key events: errors, tool calls, session boundaries
+            const significant = timeline.filter((e) => e.eventType === 'tool_error' ||
+                e.eventType === 'tool_call' ||
+                e.eventType === 'session_started' ||
+                e.eventType === 'session_ended' ||
+                e.severity === 'error' ||
+                e.severity === 'critical');
+            keyEvents = significant.slice(0, MAX_KEY_EVENTS).map((e) => {
+                const eventSummary = summarizeEvent(e) ?? `${e.eventType}`;
+                return {
+                    id: e.id,
+                    eventType: e.eventType,
+                    summary: eventSummary,
+                    timestamp: e.timestamp,
+                };
+            });
+        }
+        catch {
+            // Non-critical — return session without events
+        }
+        return {
+            sessionId: session.sessionId,
+            agentId: sessionRecord?.agentId ?? '',
+            summary: session.summary,
+            relevanceScore: session.relevanceScore,
+            startedAt: sessionRecord?.startedAt ?? '',
+            endedAt: sessionRecord?.endedAt,
+            keyEvents,
+        };
+    }
+    /**
+     * Compute a recency boost (0-1) based on how recent the content is.
+     * Items from the last 24h get ~1.0, items from 30+ days ago get ~0.0.
+     */
+    computeRecencyBoost(createdAt) {
+        const now = Date.now();
+        const created = new Date(createdAt).getTime();
+        const ageMs = now - created;
+        const thirtyDaysMs = 30 * 24 * 60 * 60 * 1000;
+        if (ageMs <= 0)
+            return 1.0;
+        if (ageMs >= thirtyDaysMs)
+            return 0.0;
+        return 1.0 - ageMs / thirtyDaysMs;
+    }
+}
+//# sourceMappingURL=retrieval.js.map

package/dist/lib/context/retrieval.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retrieval.js","sourceRoot":"","sources":["../../../src/lib/context/retrieval.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAQH,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAE7D,8BAA8B;AAC9B,MAAM,aAAa,GAAG,EAAE,CAAC;AAEzB,gDAAgD;AAChD,MAAM,cAAc,GAAG,CAAC,CAAC;AAEzB,MAAM,OAAO,gBAAgB;IAER;IACA;IACA;IACA;IACA;IALnB,YACmB,cAAqC,EACrC,gBAAyC,EACzC,mBAAwC,EACxC,WAAwB,EACxB,UAAuB;QAJvB,mBAAc,GAAd,cAAc,CAAuB;QACrC,qBAAgB,GAAhB,gBAAgB,CAAyB;QACzC,wBAAmB,GAAnB,mBAAmB,CAAqB;QACxC,gBAAW,GAAX,WAAW,CAAa;QACxB,eAAU,GAAV,UAAU,CAAa;IACvC,CAAC;IAEJ;;;;;;OAMG;IACH,KAAK,CAAC,QAAQ,CAAC,QAAgB,EAAE,KAAmB;QAClD,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,IAAI,aAAa,CAAC;QAE3C,iCAAiC;QACjC,MAAM,cAAc,GAAG,MAAM,IAAI,CAAC,oBAAoB,CAAC,QAAQ,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;QAE/E,gCAAgC;QAChC,MAAM,aAAa,GAAG,MAAM,IAAI,CAAC,mBAAmB,CAAC,QAAQ,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;QAE7E,oDAAoD;QACpD,MAAM,kBAAkB,GAAqB,MAAM,OAAO,CAAC,GAAG,CAC5D,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,uBAAuB,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,CACrE,CAAC;QAEF,OAAO;YACL,KAAK,EAAE,KAAK,CAAC,KAAK;YAClB,QAAQ,EAAE,kBAAkB;YAC5B,OAAO,EAAE,aAAa;YACtB,aAAa,EAAE,kBAAkB,CAAC,MAAM;SACzC,CAAC;IACJ,CAAC;IAED;;OAEG;IACK,KAAK,CAAC,oBAAoB,CAChC,QAAgB,EAChB,KAAmB,EACnB,KAAa;QAEb,4BAA4B;QAC5B,IAAI,IAAI,CAAC,gBAAgB,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;YACjD,IAAI,CAAC;gBACH,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC,gBAAgB,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;gBACnE,MAAM,OAAO,GAAG,IAAI,CAAC,cAAc,CAAC,gBAAgB,CAAC,QAAQ,EAAE,WAAW,EAAE;oBAC1E,UAAU,EAAE,SAAS;oBACrB,IAAI,EAAE,KAAK,CAAC,IAAI;oBAChB,EAAE,EAAE,KAAK,CAAC,EAAE;oBACZ,KAAK,EAAE,KAAK,GAAG,CAAC,EAAE,gCAAgC;oBAClD,QAAQ,EAAE,GAAG;iBACd,CAAC,CAAC;gBAEH,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;oBACvB,OAAO,IAAI,CAAC,qBAAqB,CAAC,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;gBACrE,CAAC;YACH,CAAC;YAAC,MAAM,CAAC;gBACP,8BAA8B;YAChC,CAAC;QACH,CAAC;QAED,6CAA6C;QAC7C,OAAO,IAAI,CAAC,kBAAkB,CAAC,QAAQ,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;IACzD,CAAC;IAED;;OAEG;IACK,KAAK,CAAC,qBAAqB,CACjC,QAAgB,EAChB,OAA2B,EAC3B,KAAmB,EACnB,KAAa;QAEb,MAAM,QAAQ,GAA0E,EAAE,CAAC;QAE3F,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;YAC7B,yDAAyD;YACzD,MAAM,SAAS,GAAG,MAAM,CAAC,QAAQ,CAAC;YAElC,gCAAgC;YAChC,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;gBAClB,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;gBAC5D,IAAI,CAAC,OAAO,IAAI,OAAO,CAAC,OAAO,KAAK,KAAK,CAAC,OAAO;oBAAE,SAAS;YAC9D,CAAC;YAED,mEAAmE;YACnE,MAAM,aAAa,GAAG,IAAI,CAAC,mBAAmB,CAAC,GAAG,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;YACxE,MAAM,OAAO,GAAG,aAAa,EAAE,OAAO,IAAI,MAAM,CAAC,IAAI,CAAC;YAEtD,4DAA4D;YAC5D,MAAM,YAAY,GAAG,IAAI,CAAC,mBAAmB,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;YAChE,MAAM,aAAa,GAAG,MAAM,CAAC,KAAK,GAAG,IAAI,GAAG,YAAY,GAAG,IAAI,CAAC;YAEhE,QAAQ,CAAC,IAAI,CAAC;gBACZ,SAAS;gBACT,OAAO;gBACP,cAAc,EAAE,IAAI,CAAC,KAAK,CAAC,aAAa,GAAG,KAAK,CAAC,GAAG,KAAK;aAC1D,CAAC,CAAC;YAEH,IAAI,QAAQ,CAAC,MAAM,IAAI,KAAK;gBAAE,MAAM;QACtC,CAAC;QAED,oCAAoC;QACpC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,cAAc,GAAG,CAAC,CAAC,cAAc,CAAC,CAAC;QAC7D,OAAO,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;IAClC,CAAC;IAED;;OAEG;IACK,kBAAkB,CACxB,QAAgB,EAChB,KAAmB,EACnB,KAAa;QAEb,MAAM,OAAO,GAAG,IAAI,CAAC,mBAAmB,CAAC,MAAM,CAAC,QAAQ,EAAE,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;QAElF,IAAI,QAAQ,GAAG,OAAO,CAAC;QAEvB,mEAAmE;QACnE,yEAAyE;QACzE,gEAAgE;QAEhE,OAAO,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC;YACjD,SAAS,EAAE,CAAC,CAAC,SAAS;YACtB,OAAO,EAAE,CAAC,CAAC,OAAO;YAClB,0EAA0E;YAC1E,cAAc,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,GAAG,KAAK,GAAG,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,GAAG,KAAK;SACvF,CAAC,CAAC,CAAC;IACN,CAAC;IAED;;OAEG;IACK,KAAK,CAAC,mBAAmB,CAC/B,QAAgB,EAChB,KAAmB,EACnB,KAAa;QAEb,4BAA4B;QAC5B,IAAI,IAAI,CAAC,gBAAgB,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;YACjD,IAAI,CAAC;gBACH,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC,gBAAgB,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;gBACnE,MAAM,OAAO,GAAG,IAAI,CAAC,cAAc,CAAC,gBAAgB,CAAC,QAAQ,EAAE,WAAW,EAAE;oBAC1E,UAAU,EAAE,QAAQ;oBACpB,KAAK;oBACL,QAAQ,EAAE,GAAG;iBACd,CAAC,CAAC;gBAEH,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;oBACvB,MAAM,OAAO,GAAoB,EAAE,CAAC;oBAEpC,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;wBAC7B,MAAM,MAAM,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC;wBAC/D,IAAI,MAAM,EAAE,CAAC;4BACX,OAAO,CAAC,IAAI,CAAC;gCACX,EAAE,EAAE,MAAM,CAAC,EAAE;gCACb,KAAK,EAAE,MAAM,CAAC,KAAK;gCACnB,OAAO,EAAE,MAAM,CAAC,OAAO;gCACvB,QAAQ,EAAE,MAAM,CAAC,QAAQ;gCACzB,UAAU,EAAE,MAAM,CAAC,UAAU;gCAC7B,cAAc,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,GAAG,KAAK,CAAC,GAAG,KAAK;6BACzD,CAAC,CAAC;wBACL,CAAC;oBACH,CAAC;oBAED,OAAO,OAAO,CAAC;gBACjB,CAAC;YACH,CAAC;YAAC,MAAM,CAAC;gBACP,8BAA8B;YAChC,CAAC;QACH,CAAC;QAED,mCAAmC;QACnC,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,QAAQ,EAAE;YAClD,MAAM,EAAE,KAAK,CAAC,KAAK;YACnB,KAAK;SACN,CAAC,CAAC;QAEH,OAAO,WAAW,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC;YACzC,EAAE,EAAE,MAAM,CAAC,EAAE;YACb,KAAK,EAAE,MAAM,CAAC,KAAK;YACnB,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,UAAU,EAAE,MAAM,CAAC,UAAU;YAC7B,mDAAmD;YACnD,cAAc,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,GAAG,KAAK,GAAG,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,GAAG,KAAK;SACvF,CAAC,CAAC,CAAC;IACN,CAAC;IAED;;OAEG;IACK,KAAK,CAAC,uBAAuB,CACnC,QAAgB,EAChB,OAAuE;QAEvE,qDAAqD;QACrD,MAAM,aAAa,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QAE1E,+CAA+C;QAC/C,IAAI,SAAS,GAAsB,EAAE,CAAC;QACtC,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,kBAAkB,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;YAE7E,6DAA6D;YAC7D,MAAM,WAAW,GAAG,QAAQ,CAAC,MAAM,CACjC,CAAC,CAAC,EAAE,EAAE,CACJ,CAAC,CAAC,SAAS,KAAK,YAAY;gBAC5B,CAAC,CAAC,SAAS,KAAK,WAAW;gBAC3B,CAAC,CAAC,SAAS,KAAK,iBAAiB;gBACjC,CAAC,CAAC,SAAS,KAAK,eAAe;gBAC/B,CAAC,CAAC,QAAQ,KAAK,OAAO;gBACtB,CAAC,CAAC,QAAQ,KAAK,UAAU,CAC5B,CAAC;YAEF,SAAS,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC,EAAE,cAAc,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;gBACzD,MAAM,YAAY,GAAG,cAAc,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,SAAS,EAAE,CAAC;gBAC3D,OAAO;oBACL,EAAE,EAAE,CAAC,CAAC,EAAE;oBACR,SAAS,EAAE,CAAC,CAAC,SAAS;oBACtB,OAAO,EAAE,YAAY;oBACrB,SAAS,EAAE,CAAC,CAAC,SAAS;iBACvB,CAAC;YACJ,CAAC,CAAC,CAAC;QACL,CAAC;QAAC,MAAM,CAAC;YACP,+CAA+C;QACjD,CAAC;QAED,OAAO;YACL,SAAS,EAAE,OAAO,CAAC,SAAS;YAC5B,OAAO,EAAE,aAAa,EAAE,OAAO,IAAI,EAAE;YACrC,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,cAAc,EAAE,OAAO,CAAC,cAAc;YACtC,SAAS,EAAE,aAAa,EAAE,SAAS,IAAI,EAAE;YACzC,OAAO,EAAE,aAAa,EAAE,OAAO;YAC/B,SAAS;SACV,CAAC;IACJ,CAAC;IAED;;;OAGG;IACK,mBAAmB,CAAC,SAAiB;QAC3C,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,MAAM,OAAO,GAAG,IAAI,IAAI,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,CAAC;QAC9C,MAAM,KAAK,GAAG,GAAG,GAAG,OAAO,CAAC;QAC5B,MAAM,YAAY,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;QAE9C,IAAI,KAAK,IAAI,CAAC;YAAE,OAAO,GAAG,CAAC;QAC3B,IAAI,KAAK,IAAI,YAAY;YAAE,OAAO,GAAG,CAAC;QACtC,OAAO,GAAG,GAAG,KAAK,GAAG,YAAY,CAAC;IACpC,CAAC;CACF"}

package/dist/lib/embeddings/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Embedding Service — interface and factory (Story 2.1)
+ *
+ * Supports local (Xenova/transformers.js ONNX) and OpenAI backends.
+ */
+import type { EmbeddingServiceConfig } from './types.js';
+export type { EmbeddingVector, EmbeddingBackend, EmbeddingServiceConfig } from './types.js';
+export { cosineSimilarity } from './math.js';
+/**
+ * Embedding service interface — embed text into vector space.
+ */
+export interface EmbeddingService {
+    /** Embed a single text string */
+    embed(text: string): Promise<Float32Array>;
+    /** Embed a batch of texts */
+    embedBatch(texts: string[]): Promise<Float32Array[]>;
+    /** Dimensionality of the output vectors */
+    readonly dimensions: number;
+    /** Name of the model used */
+    readonly modelName: string;
+}
+/**
+ * Create an embedding service from config or environment variables.
+ *
+ * Environment variables:
+ * - AGENTLENS_EMBEDDING_BACKEND: 'local' | 'openai' (default: 'local')
+ * - AGENTLENS_EMBEDDING_MODEL: model name override
+ * - OPENAI_API_KEY: required for 'openai' backend
+ */
+export declare function createEmbeddingService(config?: Partial<EmbeddingServiceConfig>): EmbeddingService;
+//# sourceMappingURL=index.d.ts.map

package/dist/lib/embeddings/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/embeddings/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAIzD,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAC5F,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAE7C;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,iCAAiC;IACjC,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IAE3C,6BAA6B;IAC7B,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;IAErD,2CAA2C;IAC3C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B,6BAA6B;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,sBAAsB,CAAC,GAAG,gBAAgB,CAgBjG"}

package/dist/lib/embeddings/index.js

@@ -0,0 +1,31 @@
+/**
+ * Embedding Service — interface and factory (Story 2.1)
+ *
+ * Supports local (Xenova/transformers.js ONNX) and OpenAI backends.
+ */
+import { createLocalEmbeddingService } from './local.js';
+import { createOpenAIEmbeddingService } from './openai.js';
+export { cosineSimilarity } from './math.js';
+/**
+ * Create an embedding service from config or environment variables.
+ *
+ * Environment variables:
+ * - AGENTLENS_EMBEDDING_BACKEND: 'local' | 'openai' (default: 'local')
+ * - AGENTLENS_EMBEDDING_MODEL: model name override
+ * - OPENAI_API_KEY: required for 'openai' backend
+ */
+export function createEmbeddingService(config) {
+    const backend = config?.backend ??
+        process.env['AGENTLENS_EMBEDDING_BACKEND'] ??
+        'local';
+    const modelName = config?.modelName ?? process.env['AGENTLENS_EMBEDDING_MODEL'];
+    switch (backend) {
+        case 'local':
+            return createLocalEmbeddingService(modelName);
+        case 'openai':
+            return createOpenAIEmbeddingService(config?.openaiApiKey, modelName);
+        default:
+            throw new Error(`Unknown embedding backend: ${backend}. Use 'local' or 'openai'.`);
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/lib/embeddings/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/lib/embeddings/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,2BAA2B,EAAE,MAAM,YAAY,CAAC;AACzD,OAAO,EAAE,4BAA4B,EAAE,MAAM,aAAa,CAAC;AAG3D,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAmB7C;;;;;;;GAOG;AACH,MAAM,UAAU,sBAAsB,CAAC,MAAwC;IAC7E,MAAM,OAAO,GACX,MAAM,EAAE,OAAO;QACd,OAAO,CAAC,GAAG,CAAC,6BAA6B,CAAoC;QAC9E,OAAO,CAAC;IAEV,MAAM,SAAS,GAAG,MAAM,EAAE,SAAS,IAAI,OAAO,CAAC,GAAG,CAAC,2BAA2B,CAAC,CAAC;IAEhF,QAAQ,OAAO,EAAE,CAAC;QAChB,KAAK,OAAO;YACV,OAAO,2BAA2B,CAAC,SAAS,CAAC,CAAC;QAChD,KAAK,QAAQ;YACX,OAAO,4BAA4B,CAAC,MAAM,EAAE,YAAY,EAAE,SAAS,CAAC,CAAC;QACvE;YACE,MAAM,IAAI,KAAK,CAAC,8BAA8B,OAAiB,4BAA4B,CAAC,CAAC;IACjG,CAAC;AACH,CAAC"}

package/dist/lib/embeddings/local.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Local embedding service using @xenova/transformers (ONNX) (Story 2.1)
+ *
+ * Uses all-MiniLM-L6-v2 model (384 dimensions) by default.
+ * Model is loaded once and cached for subsequent calls.
+ */
+import type { EmbeddingService } from './index.js';
+/**
+ * Create a local embedding service backed by @xenova/transformers.
+ *
+ * The @xenova/transformers package is dynamically imported, so it's
+ * not a hard dependency. If not installed, a clear error is thrown.
+ */
+export declare function createLocalEmbeddingService(modelName?: string): EmbeddingService;
+//# sourceMappingURL=local.d.ts.map

package/dist/lib/embeddings/local.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local.d.ts","sourceRoot":"","sources":["../../../src/lib/embeddings/local.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAKnD;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAwDhF"}

package/dist/lib/embeddings/local.js

@@ -0,0 +1,65 @@
+/**
+ * Local embedding service using @xenova/transformers (ONNX) (Story 2.1)
+ *
+ * Uses all-MiniLM-L6-v2 model (384 dimensions) by default.
+ * Model is loaded once and cached for subsequent calls.
+ */
+const DEFAULT_MODEL = 'Xenova/all-MiniLM-L6-v2';
+const DEFAULT_DIMENSIONS = 384;
+/**
+ * Create a local embedding service backed by @xenova/transformers.
+ *
+ * The @xenova/transformers package is dynamically imported, so it's
+ * not a hard dependency. If not installed, a clear error is thrown.
+ */
+export function createLocalEmbeddingService(modelName) {
+    const model = modelName ?? DEFAULT_MODEL;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    let pipelinePromise = null;
+    async function getPipeline() {
+        if (!pipelinePromise) {
+            pipelinePromise = (async () => {
+                try {
+                    // Dynamic import — @xenova/transformers may not be installed
+                    // Use a variable to prevent TypeScript from resolving the module at compile time
+                    const moduleName = '@xenova/transformers';
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    const mod = await Function('m', 'return import(m)')(moduleName);
+                    const { pipeline } = mod;
+                    return await pipeline('feature-extraction', model);
+                }
+                catch (err) {
+                    pipelinePromise = null; // Reset so user can retry after install
+                    if (err instanceof Error &&
+                        (err.message.includes('Cannot find module') ||
+                            err.message.includes('Cannot find package') ||
+                            err.message.includes('ERR_MODULE_NOT_FOUND'))) {
+                        throw new Error('Local embedding backend requires @xenova/transformers. ' +
+                            'Install it with: pnpm add @xenova/transformers');
+                    }
+                    throw err;
+                }
+            })();
+        }
+        return pipelinePromise;
+    }
+    return {
+        dimensions: DEFAULT_DIMENSIONS,
+        modelName: model,
+        async embed(text) {
+            const pipe = await getPipeline();
+            const output = await pipe(text, { pooling: 'mean', normalize: true });
+            return new Float32Array(output.data);
+        },
+        async embedBatch(texts) {
+            const pipe = await getPipeline();
+            const results = [];
+            for (const text of texts) {
+                const output = await pipe(text, { pooling: 'mean', normalize: true });
+                results.push(new Float32Array(output.data));
+            }
+            return results;
+        },
+    };
+}
+//# sourceMappingURL=local.js.map

package/dist/lib/embeddings/local.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"local.js","sourceRoot":"","sources":["../../../src/lib/embeddings/local.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,MAAM,aAAa,GAAG,yBAAyB,CAAC;AAChD,MAAM,kBAAkB,GAAG,GAAG,CAAC;AAE/B;;;;;GAKG;AACH,MAAM,UAAU,2BAA2B,CAAC,SAAkB;IAC5D,MAAM,KAAK,GAAG,SAAS,IAAI,aAAa,CAAC;IACzC,8DAA8D;IAC9D,IAAI,eAAe,GAAwB,IAAI,CAAC;IAEhD,KAAK,UAAU,WAAW;QACxB,IAAI,CAAC,eAAe,EAAE,CAAC;YACrB,eAAe,GAAG,CAAC,KAAK,IAAI,EAAE;gBAC5B,IAAI,CAAC;oBACH,6DAA6D;oBAC7D,iFAAiF;oBACjF,MAAM,UAAU,GAAG,sBAAsB,CAAC;oBAC1C,8DAA8D;oBAC9D,MAAM,GAAG,GAAG,MAAO,QAAQ,CAAC,GAAG,EAAE,kBAAkB,CAAiC,CAAC,UAAU,CAAC,CAAC;oBACjG,MAAM,EAAE,QAAQ,EAAE,GAAG,GAAG,CAAC;oBACzB,OAAO,MAAM,QAAQ,CAAC,oBAAoB,EAAE,KAAK,CAAC,CAAC;gBACrD,CAAC;gBAAC,OAAO,GAAY,EAAE,CAAC;oBACtB,eAAe,GAAG,IAAI,CAAC,CAAC,wCAAwC;oBAChE,IACE,GAAG,YAAY,KAAK;wBACpB,CAAC,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAC;4BACzC,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAAC;4BAC3C,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAAC,CAAC,EAC/C,CAAC;wBACD,MAAM,IAAI,KAAK,CACb,yDAAyD;4BACvD,gDAAgD,CACnD,CAAC;oBACJ,CAAC;oBACD,MAAM,GAAG,CAAC;gBACZ,CAAC;YACH,CAAC,CAAC,EAAE,CAAC;QACP,CAAC;QACD,OAAO,eAAe,CAAC;IACzB,CAAC;IAED,OAAO;QACL,UAAU,EAAE,kBAAkB;QAC9B,SAAS,EAAE,KAAK;QAEhB,KAAK,CAAC,KAAK,CAAC,IAAY;YACtB,MAAM,IAAI,GAAG,MAAM,WAAW,EAAE,CAAC;YACjC,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YACtE,OAAO,IAAI,YAAY,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACvC,CAAC;QAED,KAAK,CAAC,UAAU,CAAC,KAAe;YAC9B,MAAM,IAAI,GAAG,MAAM,WAAW,EAAE,CAAC;YACjC,MAAM,OAAO,GAAmB,EAAE,CAAC;YACnC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;gBACzB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;gBACtE,OAAO,CAAC,IAAI,CAAC,IAAI,YAAY,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;YAC9C,CAAC;YACD,OAAO,OAAO,CAAC;QACjB,CAAC;KACF,CAAC;AACJ,CAAC"}