agent-knowledge 1.0.0

package/dist/validate.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Input validation helpers for MCP tool arguments.
+ */
+export declare class ValidationError extends Error {
+    constructor(message: string);
+}
+export declare function requireString(args: Record<string, unknown>, key: string): string;
+export declare function optionalString(args: Record<string, unknown>, key: string): string | undefined;
+export declare function optionalNumber(args: Record<string, unknown>, key: string, opts?: {
+    min?: number;
+    max?: number;
+    defaultValue?: number;
+}): number | undefined;
+export declare function optionalBoolean(args: Record<string, unknown>, key: string, defaultValue?: boolean): boolean;
+export declare function requireEnum<T extends string>(args: Record<string, unknown>, key: string, allowed: readonly T[]): T;
+export declare function optionalEnum<T extends string>(args: Record<string, unknown>, key: string, allowed: readonly T[], defaultValue?: T): T | undefined;
+/**
+ * Validate a filename: no path separators, no special traversal chars.
+ */
+export declare function validateFilename(name: string): string;
+//# sourceMappingURL=validate.d.ts.map

package/dist/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,qBAAa,eAAgB,SAAQ,KAAK;gBAC5B,OAAO,EAAE,MAAM;CAI5B;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAMhF;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAQ7F;AAED,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,GAAG,EAAE,MAAM,EACX,IAAI,GAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAAO,GAC/D,MAAM,GAAG,SAAS,CAcpB;AAED,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,GAAG,EAAE,MAAM,EACX,YAAY,CAAC,EAAE,OAAO,GACrB,OAAO,CAOT;AAED,wBAAgB,WAAW,CAAC,CAAC,SAAS,MAAM,EAC1C,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,SAAS,CAAC,EAAE,GACpB,CAAC,CAMH;AAED,wBAAgB,YAAY,CAAC,CAAC,SAAS,MAAM,EAC3C,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,SAAS,CAAC,EAAE,EACrB,YAAY,CAAC,EAAE,CAAC,GACf,CAAC,GAAG,SAAS,CAOf;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAWrD"}

package/dist/validate.js

@@ -0,0 +1,86 @@
+/**
+ * Input validation helpers for MCP tool arguments.
+ */
+export class ValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ValidationError';
+    }
+}
+export function requireString(args, key) {
+    const val = args[key];
+    if (typeof val !== 'string' || val.trim().length === 0) {
+        throw new ValidationError(`"${key}" is required and must be a non-empty string`);
+    }
+    return val.trim();
+}
+export function optionalString(args, key) {
+    const val = args[key];
+    if (val === undefined || val === null)
+        return undefined;
+    if (typeof val !== 'string') {
+        throw new ValidationError(`"${key}" must be a string`);
+    }
+    const trimmed = val.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+export function optionalNumber(args, key, opts = {}) {
+    const val = args[key];
+    if (val === undefined || val === null)
+        return opts.defaultValue;
+    const num = typeof val === 'number' ? val : Number(val);
+    if (isNaN(num)) {
+        throw new ValidationError(`"${key}" must be a number`);
+    }
+    if (opts.min !== undefined && num < opts.min) {
+        throw new ValidationError(`"${key}" must be >= ${opts.min}`);
+    }
+    if (opts.max !== undefined && num > opts.max) {
+        throw new ValidationError(`"${key}" must be <= ${opts.max}`);
+    }
+    return num;
+}
+export function optionalBoolean(args, key, defaultValue) {
+    const val = args[key];
+    if (val === undefined || val === null)
+        return defaultValue ?? false;
+    if (typeof val === 'boolean')
+        return val;
+    if (val === 'true')
+        return true;
+    if (val === 'false')
+        return false;
+    throw new ValidationError(`"${key}" must be a boolean`);
+}
+export function requireEnum(args, key, allowed) {
+    const val = requireString(args, key);
+    if (!allowed.includes(val)) {
+        throw new ValidationError(`"${key}" must be one of: ${allowed.join(', ')}. Got: "${val}"`);
+    }
+    return val;
+}
+export function optionalEnum(args, key, allowed, defaultValue) {
+    const val = optionalString(args, key);
+    if (val === undefined)
+        return defaultValue;
+    if (!allowed.includes(val)) {
+        throw new ValidationError(`"${key}" must be one of: ${allowed.join(', ')}. Got: "${val}"`);
+    }
+    return val;
+}
+/**
+ * Validate a filename: no path separators, no special traversal chars.
+ */
+export function validateFilename(name) {
+    if (/[/\\:]/.test(name)) {
+        throw new ValidationError('Filename must not contain path separators');
+    }
+    if (name === '.' || name === '..' || name.startsWith('..')) {
+        throw new ValidationError('Invalid filename');
+    }
+    if (name.length > 255) {
+        throw new ValidationError('Filename too long (max 255 chars)');
+    }
+    return name;
+}
+//# sourceMappingURL=validate.js.map

package/dist/validate.js.map

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

package/dist/vectorstore/chunker.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Text chunking utilities for preparing content for embedding models.
+ *
+ * Two strategies:
+ * - Knowledge chunking: splits on markdown headers and paragraph breaks
+ * - Session chunking: treats each message as a natural chunk boundary
+ */
+/** A single chunk of text ready for embedding. */
+export interface Chunk {
+    index: number;
+    text: string;
+    metadata?: Record<string, unknown>;
+}
+/** A session message to be chunked. */
+export interface SessionMessage {
+    role: string;
+    text: string;
+    timestamp?: string;
+    sessionId?: string;
+}
+/**
+ * Chunk a knowledge-base document (typically markdown).
+ *
+ * Strategy:
+ * 1. Split on markdown headers (## and above)
+ * 2. Within each section, split on paragraph breaks if still too long
+ * 3. Apply character overlap between chunks for context continuity
+ * 4. Short texts (< maxChars/2) are returned as a single chunk
+ *
+ * @param text - The full document text
+ * @param maxChars - Maximum characters per chunk (default 2000, ~500 tokens)
+ * @returns Array of chunks with index and text
+ */
+export declare function chunkKnowledge(text: string, maxChars?: number): Chunk[];
+/**
+ * Chunk session messages for embedding.
+ *
+ * Strategy:
+ * - Each message is a natural chunk (role + text)
+ * - Messages exceeding maxChars are split at sentence/word boundaries
+ * - Timestamp and role are included as metadata
+ *
+ * @param messages - Array of session messages
+ * @param maxChars - Maximum characters per chunk (default 2000)
+ * @returns Array of chunks with index, text, and metadata
+ */
+export declare function chunkSession(messages: SessionMessage[], maxChars?: number): Chunk[];
+//# sourceMappingURL=chunker.d.ts.map

package/dist/vectorstore/chunker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunker.d.ts","sourceRoot":"","sources":["../../src/vectorstore/chunker.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,kDAAkD;AAClD,MAAM,WAAW,KAAK;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,uCAAuC;AACvC,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAsFD;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,GAAE,MAA0B,GAAG,KAAK,EAAE,CAgC1F;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,cAAc,EAAE,EAC1B,QAAQ,GAAE,MAA0B,GACnC,KAAK,EAAE,CAiCT"}

package/dist/vectorstore/chunker.js

@@ -0,0 +1,165 @@
+/**
+ * Text chunking utilities for preparing content for embedding models.
+ *
+ * Two strategies:
+ * - Knowledge chunking: splits on markdown headers and paragraph breaks
+ * - Session chunking: treats each message as a natural chunk boundary
+ */
+const DEFAULT_MAX_CHARS = 2000;
+const DEFAULT_OVERLAP = 200;
+/**
+ * Strip YAML frontmatter delimited by `---\n...\n---` from the start of text.
+ */
+function stripFrontmatter(text) {
+    const match = text.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/);
+    return match ? text.slice(match[0].length) : text;
+}
+/**
+ * Normalize whitespace: collapse runs of 3+ newlines to 2, trim each line,
+ * but preserve single blank lines (paragraph structure).
+ */
+function normalizeWhitespace(text) {
+    return text
+        .replace(/[ \t]+$/gm, '')
+        .replace(/^[ \t]+/gm, (m) => m)
+        .replace(/\n{3,}/g, '\n\n')
+        .trim();
+}
+/**
+ * Split text at a clean boundary (paragraph, sentence, or word) near maxChars.
+ * Returns [before, after].
+ */
+function splitAtBoundary(text, maxChars) {
+    if (text.length <= maxChars)
+        return [text, ''];
+    const doubleNewline = text.lastIndexOf('\n\n', maxChars);
+    if (doubleNewline > maxChars * 0.3) {
+        return [text.slice(0, doubleNewline).trimEnd(), text.slice(doubleNewline).trimStart()];
+    }
+    const sentenceEnd = text.slice(0, maxChars).search(/[.!?]\s+(?=[A-Z])[^]*$/);
+    if (sentenceEnd > maxChars * 0.3) {
+        const splitPos = sentenceEnd + 1;
+        return [text.slice(0, splitPos).trimEnd(), text.slice(splitPos).trimStart()];
+    }
+    const lastSpace = text.lastIndexOf(' ', maxChars);
+    if (lastSpace > maxChars * 0.3) {
+        return [text.slice(0, lastSpace).trimEnd(), text.slice(lastSpace).trimStart()];
+    }
+    return [text.slice(0, maxChars), text.slice(maxChars)];
+}
+/**
+ * Split a long text into chunks of approximately maxChars with overlap.
+ * Used internally when a single section exceeds the limit.
+ */
+function splitWithOverlap(text, maxChars, overlap) {
+    // Clamp overlap to at most half of maxChars to prevent infinite loops
+    const safeOverlap = Math.min(overlap, Math.floor(maxChars / 2));
+    const chunks = [];
+    let remaining = text;
+    while (remaining.length > 0) {
+        if (remaining.length <= maxChars) {
+            chunks.push(remaining);
+            break;
+        }
+        const [chunk, rest] = splitAtBoundary(remaining, maxChars);
+        chunks.push(chunk);
+        if (rest.length === 0)
+            break;
+        const overlapStart = Math.max(0, chunk.length - safeOverlap);
+        const overlapText = text.slice(text.length - remaining.length + overlapStart, text.length - remaining.length + chunk.length);
+        remaining = overlapText.length > 0 && safeOverlap > 0 ? overlapText + ' ' + rest : rest;
+        if (remaining.length >= text.length) {
+            remaining = rest;
+        }
+    }
+    return chunks;
+}
+/**
+ * Chunk a knowledge-base document (typically markdown).
+ *
+ * Strategy:
+ * 1. Split on markdown headers (## and above)
+ * 2. Within each section, split on paragraph breaks if still too long
+ * 3. Apply character overlap between chunks for context continuity
+ * 4. Short texts (< maxChars/2) are returned as a single chunk
+ *
+ * @param text - The full document text
+ * @param maxChars - Maximum characters per chunk (default 2000, ~500 tokens)
+ * @returns Array of chunks with index and text
+ */
+export function chunkKnowledge(text, maxChars = DEFAULT_MAX_CHARS) {
+    const stripped = stripFrontmatter(text);
+    const normalized = normalizeWhitespace(stripped);
+    if (normalized.length === 0)
+        return [];
+    if (normalized.length < maxChars / 2) {
+        return [{ index: 0, text: normalized }];
+    }
+    const headerPattern = /^(?=#{1,4}\s)/m;
+    const sections = normalized.split(headerPattern).filter((s) => s.trim().length > 0);
+    const chunks = [];
+    let chunkIndex = 0;
+    for (const section of sections) {
+        const trimmed = section.trim();
+        if (trimmed.length === 0)
+            continue;
+        if (trimmed.length <= maxChars) {
+            chunks.push({ index: chunkIndex++, text: trimmed });
+        }
+        else {
+            const subChunks = splitWithOverlap(trimmed, maxChars, DEFAULT_OVERLAP);
+            for (const sub of subChunks) {
+                if (sub.trim().length > 0) {
+                    chunks.push({ index: chunkIndex++, text: sub.trim() });
+                }
+            }
+        }
+    }
+    return chunks;
+}
+/**
+ * Chunk session messages for embedding.
+ *
+ * Strategy:
+ * - Each message is a natural chunk (role + text)
+ * - Messages exceeding maxChars are split at sentence/word boundaries
+ * - Timestamp and role are included as metadata
+ *
+ * @param messages - Array of session messages
+ * @param maxChars - Maximum characters per chunk (default 2000)
+ * @returns Array of chunks with index, text, and metadata
+ */
+export function chunkSession(messages, maxChars = DEFAULT_MAX_CHARS) {
+    const chunks = [];
+    let chunkIndex = 0;
+    for (const msg of messages) {
+        const text = normalizeWhitespace(msg.text);
+        if (text.length === 0)
+            continue;
+        const prefix = `[${msg.role}]: `;
+        const metadata = { role: msg.role };
+        if (msg.timestamp)
+            metadata.timestamp = msg.timestamp;
+        if (msg.sessionId)
+            metadata.sessionId = msg.sessionId;
+        const fullText = prefix + text;
+        if (fullText.length <= maxChars) {
+            chunks.push({ index: chunkIndex++, text: fullText, metadata });
+        }
+        else {
+            const subChunks = splitWithOverlap(fullText, maxChars, 0);
+            for (let i = 0; i < subChunks.length; i++) {
+                const sub = subChunks[i].trim();
+                if (sub.length > 0) {
+                    chunks.push({
+                        index: chunkIndex++,
+                        text: sub,
+                        metadata: { ...metadata, part: i },
+                    });
+                }
+            }
+        }
+    }
+    return chunks;
+}
+//# sourceMappingURL=chunker.js.map

package/dist/vectorstore/chunker.js.map

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

package/dist/vectorstore/index.d.ts

@@ -0,0 +1,5 @@
+export { VectorStore } from './store.js';
+export type { VectorEntry, VectorSearchResult, VectorStoreStats } from './store.js';
+export { chunkKnowledge, chunkSession } from './chunker.js';
+export type { Chunk, SessionMessage } from './chunker.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/vectorstore/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/vectorstore/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,YAAY,EAAE,WAAW,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEpF,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5D,YAAY,EAAE,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC"}

package/dist/vectorstore/index.js

@@ -0,0 +1,3 @@
+export { VectorStore } from './store.js';
+export { chunkKnowledge, chunkSession } from './chunker.js';
+//# sourceMappingURL=index.js.map

package/dist/vectorstore/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/vectorstore/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAGzC,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC"}

package/dist/vectorstore/store.d.ts

@@ -0,0 +1,139 @@
+/**
+ * SQLite-backed vector store using better-sqlite3 and sqlite-vec
+ * for semantic similarity search over knowledge and session embeddings.
+ */
+/** A single embedding entry to store. */
+export interface VectorEntry {
+    id: string;
+    source: 'knowledge' | 'session';
+    sourceId: string;
+    chunkIndex: number;
+    chunkText: string;
+    provider: string;
+    dimensions: number;
+    embedding: number[];
+    metadata?: Record<string, unknown>;
+}
+/** A search result with similarity score. */
+export interface VectorSearchResult {
+    id: string;
+    sourceId: string;
+    source: 'knowledge' | 'session';
+    chunkText: string;
+    score: number;
+    metadata?: Record<string, unknown>;
+}
+/** Aggregate statistics about the vector store. */
+export interface VectorStoreStats {
+    totalEntries: number;
+    knowledgeEntries: number;
+    sessionEntries: number;
+    dbSizeMB: number;
+    provider: string | null;
+    dimensions: number | null;
+}
+/**
+ * SQLite + sqlite-vec vector store for semantic search.
+ *
+ * Lazily initializes the database on first access. Stores embeddings as
+ * Float32 BLOBs and uses sqlite-vec's vec0 virtual table for cosine
+ * similarity search.
+ */
+export declare class VectorStore {
+    private db;
+    private dbPath;
+    private initialized;
+    private vecAvailable;
+    private currentDimensions;
+    /**
+     * Create a VectorStore instance.
+     * @param dbPath - Path to the SQLite database file. Defaults to `{claudeDir}/knowledge-vectors.db`.
+     */
+    constructor(dbPath?: string);
+    /**
+     * Initialize the database: create tables, load sqlite-vec extension.
+     * Called lazily on first operation that needs the DB.
+     */
+    private init;
+    /** Attempt to load the sqlite-vec extension. */
+    private loadVecExtension;
+    /** Create or verify the vec0 virtual table matches the expected dimensions. */
+    private ensureVecTable;
+    /** Get a value from the meta table. */
+    private getMetaValue;
+    /** Set a value in the meta table. */
+    private setMetaValue;
+    /** Ensure DB is initialized, using dimensions from the first entry or the stored value. */
+    private ensureInit;
+    /** Read stored dimensions from meta (requires db to exist). */
+    private getStoredDimensions;
+    /**
+     * Store embeddings for a source. Replaces existing chunks for the same source_id.
+     * Uses a transaction for atomicity.
+     *
+     * @param entries - The embedding entries to store
+     */
+    upsert(entries: VectorEntry[]): void;
+    /**
+     * Search by vector similarity. Returns top-k nearest neighbors.
+     *
+     * @param queryVector - The query embedding vector
+     * @param maxResults - Maximum number of results (default 10)
+     * @returns Sorted results with cosine similarity scores
+     */
+    search(queryVector: number[], maxResults?: number): VectorSearchResult[];
+    /**
+     * Search filtered by source type (knowledge or session).
+     *
+     * @param queryVector - The query embedding vector
+     * @param source - Filter to 'knowledge' or 'session' entries only
+     * @param maxResults - Maximum number of results (default 10)
+     * @returns Sorted results with cosine similarity scores
+     */
+    searchBySource(queryVector: number[], source: 'knowledge' | 'session', maxResults?: number): VectorSearchResult[];
+    /** Internal search implementation with optional source filter. */
+    private searchInternal;
+    /**
+     * Delete all embeddings for a given source_id.
+     *
+     * @param sourceId - The source identifier to remove
+     */
+    deleteBySource(sourceId: string): void;
+    /**
+     * Check whether a source_id has any stored embeddings.
+     *
+     * @param sourceId - The source identifier to check
+     * @returns True if at least one embedding exists for this source
+     */
+    hasEmbeddings(sourceId: string): boolean;
+    /**
+     * Get the name of the currently active embedding provider.
+     *
+     * @returns The provider name, or null if none is set
+     */
+    getCurrentProvider(): string | null;
+    /**
+     * Set the active embedding provider. If the provider has changed since
+     * the last call, all existing embeddings are wiped to avoid mixing
+     * incompatible vector spaces.
+     *
+     * @param providerName - The provider name (e.g. "openai", "ollama")
+     * @param dimensions - The embedding dimensions for this provider
+     * @returns True if a wipe was performed (provider changed)
+     */
+    setProvider(providerName: string, dimensions: number): boolean;
+    /**
+     * Wipe all embeddings and the vec0 index.
+     * Used when switching embedding providers to avoid mixing vector spaces.
+     */
+    wipe(): void;
+    /**
+     * Get statistics about the vector store.
+     *
+     * @returns Counts by source type, DB file size, provider, and dimensions
+     */
+    stats(): VectorStoreStats;
+    /** Close the database connection and release resources. */
+    close(): void;
+}
+//# sourceMappingURL=store.d.ts.map

package/dist/vectorstore/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/vectorstore/store.ts"],"names":[],"mappings":"AAAA;;;GAGG;AASH,yCAAyC;AACzC,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,WAAW,GAAG,SAAS,CAAC;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,6CAA6C;AAC7C,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,WAAW,GAAG,SAAS,CAAC;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,mDAAmD;AACnD,MAAM,WAAW,gBAAgB;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;IACzB,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAQD;;;;;;GAMG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,EAAE,CAAyB;IACnC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,iBAAiB,CAAuB;IAEhD;;;OAGG;gBACS,MAAM,CAAC,EAAE,MAAM;IAI3B;;;OAGG;IACH,OAAO,CAAC,IAAI;IAiDZ,gDAAgD;IAChD,OAAO,CAAC,gBAAgB;IAcxB,+EAA+E;IAC/E,OAAO,CAAC,cAAc;IA0BtB,uCAAuC;IACvC,OAAO,CAAC,YAAY;IAYpB,qCAAqC;IACrC,OAAO,CAAC,YAAY;IASpB,2FAA2F;IAC3F,OAAO,CAAC,UAAU;IAQlB,+DAA+D;IAC/D,OAAO,CAAC,mBAAmB;IAsB3B;;;;;OAKG;IACH,MAAM,CAAC,OAAO,EAAE,WAAW,EAAE,GAAG,IAAI;IA+DpC;;;;;;OAMG;IACH,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,EAAE,UAAU,GAAE,MAAW,GAAG,kBAAkB,EAAE;IAI5E;;;;;;;OAOG;IACH,cAAc,CACZ,WAAW,EAAE,MAAM,EAAE,EACrB,MAAM,EAAE,WAAW,GAAG,SAAS,EAC/B,UAAU,GAAE,MAAW,GACtB,kBAAkB,EAAE;IAIvB,kEAAkE;IAClE,OAAO,CAAC,cAAc;IA6EtB;;;;OAIG;IACH,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IA+BtC;;;;;OAKG;IACH,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAmBxC;;;;OAIG;IACH,kBAAkB,IAAI,MAAM,GAAG,IAAI;IASnC;;;;;;;;OAQG;IACH,WAAW,CAAC,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO;IAoB9D;;;OAGG;IACH,IAAI,IAAI,IAAI;IAoBZ;;;;OAIG;IACH,KAAK,IAAI,gBAAgB;IAuDzB,2DAA2D;IAC3D,KAAK,IAAI,IAAI;CAWd"}