@aitne/daemon 0.1.0

package/dist/services/attachments/store.js

@@ -0,0 +1,477 @@
+import { mkdirSync, renameSync, rmSync, existsSync, statSync, readdirSync, createWriteStream, unlinkSync, } from "node:fs";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { fileTypeFromBuffer } from "file-type";
+import { deriveSafeFilename, isAllowedMime, normalizeMimeType, } from "./sanitize.js";
+import { hardLinkOrCopy } from "./hardlink.js";
+import { createLogger } from "../../logging.js";
+const logger = createLogger("attachment-store");
+/** First-N bytes read from the stream for magic-byte MIME verification.
+ *  `file-type` recommends at least 4100 bytes; we use 8 KB for headroom. */
+const MAGIC_BYTES_SNIFF_SIZE = 8192;
+function mapRow(row) {
+    return {
+        id: row.id,
+        sessionId: row.session_id,
+        messageId: row.message_id,
+        direction: row.direction,
+        provenance: row.provenance,
+        path: row.path,
+        originalFilename: row.original_filename,
+        safeFilename: row.safe_filename,
+        mimeType: row.mime_type,
+        sizeBytes: row.size_bytes,
+        turnToken: row.turn_token,
+        caption: row.caption,
+        createdAt: row.created_at,
+    };
+}
+export class IngestRejectedError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.reason = reason;
+        this.name = "IngestRejectedError";
+    }
+}
+/**
+ * AttachmentStore — canonical on-disk store + SQLite row manager for chat
+ * file attachments.
+ *
+ * Files live at `<dataDir>/attachments/<id>/<safeFilename>`. Writes are
+ * atomic (tmp file → rename) and append-only; rows are deleted together
+ * with their on-disk dir at session end / orphan reap / outbound
+ * collection failure.
+ */
+export class AttachmentStore {
+    db;
+    rootDir;
+    constructor(db, dataDir) {
+        this.db = db;
+        this.rootDir = join(dataDir, "attachments");
+        mkdirSync(this.rootDir, { recursive: true });
+    }
+    /** Absolute path to the directory that contains this attachment's bytes. */
+    dirFor(id) {
+        return join(this.rootDir, id);
+    }
+    /**
+     * Stream incoming bytes to disk, verify MIME via magic bytes, and
+     * persist a `chat_attachments` row. Throws `IngestRejectedError` on
+     * size overflow, disallowed/undetected MIME, or empty body.
+     */
+    async ingestStream(params) {
+        const id = randomUUID();
+        const safeFilename = deriveSafeFilename(params.originalFilename, id);
+        const dir = this.dirFor(id);
+        mkdirSync(dir, { recursive: true });
+        const tmpPath = join(dir, `.tmp-${randomUUID()}`);
+        const finalPath = join(dir, safeFilename);
+        const sniffBuffer = [];
+        let sniffedBytes = 0;
+        let totalBytes = 0;
+        let truncated = false;
+        const out = createWriteStream(tmpPath, { flags: "wx" });
+        const { stream } = params;
+        try {
+            await new Promise((resolve, reject) => {
+                let settled = false;
+                const onData = (chunk) => {
+                    totalBytes += chunk.length;
+                    if (totalBytes > params.maxSizeBytes) {
+                        truncated = true;
+                        // Pass an Error to `destroy()` so the stream emits `'error'`
+                        // even when its implementation does not auto-fire `'end'`
+                        // after a bare `destroy()` — defensive, because busboy's
+                        // file-part Readable follows a different lifecycle than
+                        // `Readable.from()` used in unit tests.
+                        stream.destroy(new Error("attachment_stream_truncated"));
+                        return;
+                    }
+                    if (sniffedBytes < MAGIC_BYTES_SNIFF_SIZE) {
+                        const need = MAGIC_BYTES_SNIFF_SIZE - sniffedBytes;
+                        const slice = chunk.length > need ? chunk.subarray(0, need) : chunk;
+                        sniffBuffer.push(Buffer.from(slice));
+                        sniffedBytes += slice.length;
+                    }
+                    if (!out.write(chunk)) {
+                        stream.pause();
+                    }
+                };
+                const onDrain = () => {
+                    stream.resume();
+                };
+                const cleanupInput = () => {
+                    stream.off("data", onData);
+                    stream.off("end", onEnd);
+                    stream.off("error", onError);
+                    stream.off("close", onClose);
+                    out.off("drain", onDrain);
+                };
+                const cleanupAll = () => {
+                    cleanupInput();
+                    out.off("error", onError);
+                };
+                const settle = (fn) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    cleanupAll();
+                    fn();
+                };
+                const onEnd = () => {
+                    cleanupInput();
+                    out.end(() => {
+                        settle(() => truncated ? reject(new Error("stream_truncated")) : resolve());
+                    });
+                };
+                const onClose = () => {
+                    // Safety net for Readable implementations that emit only
+                    // `'close'` after `destroy()` without a preceding `'end'` or
+                    // `'error'`. Without this listener, a truncation on such a
+                    // stream would never resolve the promise — the request would
+                    // hang until the caller's timeout fired. See `attachments.test.ts`
+                    // "rejects oversize uploads promptly" for the regression check.
+                    settle(() => {
+                        out.destroy();
+                        reject(truncated
+                            ? new Error("stream_truncated")
+                            : new Error("attachment_stream_closed_prematurely"));
+                    });
+                };
+                const onError = (err) => {
+                    settle(() => {
+                        out.destroy();
+                        reject(err);
+                    });
+                };
+                stream.on("data", onData);
+                stream.on("end", onEnd);
+                stream.on("error", onError);
+                stream.on("close", onClose);
+                out.on("drain", onDrain);
+                out.on("error", onError);
+            });
+        }
+        catch (err) {
+            await this.waitForWriteStreamSettled(out, { destroy: true });
+            this.safeRmTree(dir);
+            if (truncated) {
+                throw new IngestRejectedError("too_large", `Attachment exceeds per-file cap of ${params.maxSizeBytes} bytes`);
+            }
+            throw err;
+        }
+        await this.waitForWriteStreamSettled(out);
+        if (totalBytes === 0) {
+            this.safeRmTree(dir);
+            throw new IngestRejectedError("empty", "Attachment body is empty");
+        }
+        // Magic-byte MIME verification.
+        const head = Buffer.concat(sniffBuffer);
+        const detected = await fileTypeFromBuffer(head);
+        const declaredMime = normalizeMimeType(params.declaredMimeType);
+        let resolvedMime = normalizeMimeType(detected?.mime);
+        if (!resolvedMime) {
+            // Plain-text / CSV / JSON / Markdown etc. have no magic bytes.
+            // Accept a narrow set of declared text MIME types when the body
+            // is valid UTF-8 without embedded NULs in the sniff window.
+            if (declaredMime?.startsWith("text/")) {
+                resolvedMime = declaredMime;
+            }
+            else if (declaredMime === "application/json" ||
+                declaredMime === "application/xml" ||
+                declaredMime === "application/x-yaml") {
+                resolvedMime = declaredMime;
+            }
+        }
+        if (!resolvedMime) {
+            this.safeRmTree(dir);
+            throw new IngestRejectedError("undetected_mime", "Could not determine a safe MIME type for the upload");
+        }
+        if (!isAllowedMime(resolvedMime)) {
+            this.safeRmTree(dir);
+            throw new IngestRejectedError("disallowed_mime", `MIME type "${resolvedMime}" is not allowed`);
+        }
+        renameSync(tmpPath, finalPath);
+        this.db
+            .prepare(`INSERT INTO chat_attachments
+         (id, session_id, message_id, direction, provenance, path, original_filename,
+          safe_filename, mime_type, size_bytes, turn_token, caption)
+         VALUES (?, NULL, NULL, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+            .run(id, params.direction, params.provenance, finalPath, params.originalFilename, safeFilename, resolvedMime, totalBytes, params.turnToken ?? null, params.caption ?? null);
+        return {
+            id,
+            path: finalPath,
+            originalFilename: params.originalFilename,
+            safeFilename,
+            mimeType: resolvedMime,
+            sizeBytes: totalBytes,
+            caption: params.caption,
+        };
+    }
+    get(id) {
+        const row = this.db
+            .prepare(`SELECT * FROM chat_attachments WHERE id = ?`)
+            .get(id);
+        return row ? mapRow(row) : null;
+    }
+    /**
+     * Delete a still-unbound attachment (no message_id). Used by the
+     * DELETE endpoint and the orphan reaper. Safe no-op if the row is
+     * already gone.
+     */
+    deleteIfUnbound(id) {
+        const row = this.get(id);
+        if (!row)
+            return false;
+        if (row.messageId !== null)
+            return false;
+        this.db.prepare(`DELETE FROM chat_attachments WHERE id = ?`).run(id);
+        this.safeRmTree(this.dirFor(id));
+        return true;
+    }
+    /**
+     * Bind a batch of inbound attachment rows to a session + message
+     * inside a single transaction. Rows that don't exist or are already
+     * bound are skipped; the caller receives the list that was actually
+     * bound.
+     */
+    bindInbound(params) {
+        if (params.attachmentIds.length === 0)
+            return [];
+        const bind = this.db.transaction((ids) => {
+            const out = [];
+            const select = this.db.prepare(`SELECT * FROM chat_attachments
+         WHERE id = ? AND direction = 'inbound' AND message_id IS NULL`);
+            const update = this.db.prepare(`UPDATE chat_attachments
+         SET session_id = ?, message_id = ?
+         WHERE id = ? AND message_id IS NULL`);
+            for (const id of ids) {
+                const row = select.get(id);
+                if (!row)
+                    continue;
+                update.run(params.sessionId, params.messageId, id);
+                out.push(mapRow({ ...row, session_id: params.sessionId, message_id: params.messageId }));
+            }
+            return out;
+        });
+        return bind(params.attachmentIds);
+    }
+    listInboundForMessage(messageId) {
+        const rows = this.db
+            .prepare(`SELECT * FROM chat_attachments
+         WHERE message_id = ? AND direction = 'inbound'
+         ORDER BY created_at ASC`)
+            .all(messageId);
+        return rows.map(mapRow);
+    }
+    listOutboundForMessage(messageId) {
+        const rows = this.db
+            .prepare(`SELECT * FROM chat_attachments
+         WHERE message_id = ? AND direction = 'outbound'
+         ORDER BY created_at ASC`)
+            .all(messageId);
+        return rows.map(mapRow);
+    }
+    listForMessage(messageId) {
+        const rows = this.db
+            .prepare(`SELECT * FROM chat_attachments
+         WHERE message_id = ? ORDER BY created_at ASC`)
+            .all(messageId);
+        return rows.map(mapRow);
+    }
+    /**
+     * Collect outbound rows produced during the current turn and clear
+     * the token so they can't leak into a later turn. Returns the rows
+     * in creation order.
+     */
+    collectOutboundForTurn(params) {
+        return this.db.transaction(() => {
+            const rows = this.db
+                .prepare(`SELECT * FROM chat_attachments
+           WHERE turn_token = ? AND direction = 'outbound' AND message_id IS NULL
+           ORDER BY created_at ASC`)
+                .all(params.turnToken);
+            if (rows.length === 0)
+                return [];
+            const update = this.db.prepare(`UPDATE chat_attachments
+         SET turn_token = NULL, session_id = ?
+         WHERE id = ?`);
+            for (const row of rows) {
+                update.run(params.sessionId, row.id);
+            }
+            return rows.map(mapRow);
+        })();
+    }
+    /** Release a turn token without collecting — used on turn failure. Any
+     *  attachments the agent posted get swept into the orphan reaper path. */
+    releaseTurnToken(turnToken) {
+        this.db
+            .prepare(`UPDATE chat_attachments SET turn_token = NULL WHERE turn_token = ?`)
+            .run(turnToken);
+    }
+    /**
+     * Bind a single outbound attachment to the assistant message row that
+     * was just recorded for this turn. Called after the dispatcher records
+     * the assistant message in `messages` and the adapter has delivered
+     * the file to the user.
+     */
+    bindOutboundToMessage(attachmentId, messageId) {
+        this.db
+            .prepare(`UPDATE chat_attachments
+         SET message_id = ?
+         WHERE id = ? AND direction = 'outbound'`)
+            .run(messageId, attachmentId);
+    }
+    /**
+     * Delete inbound orphans (no message_id) older than `maxAgeHours`.
+     * Run once on daemon startup. Outbound orphans are rarer (a turn
+     * that crashed between generation and collection) and swept the same
+     * way.
+     */
+    reapOrphans(maxAgeHours = 24) {
+        const rows = this.db
+            .prepare(`SELECT id, direction FROM chat_attachments
+         WHERE message_id IS NULL
+           AND created_at < datetime('now', ?)
+        `)
+            .all(`-${maxAgeHours} hours`);
+        let inbound = 0;
+        let outbound = 0;
+        for (const row of rows) {
+            this.db.prepare(`DELETE FROM chat_attachments WHERE id = ?`).run(row.id);
+            this.safeRmTree(this.dirFor(row.id));
+            if (row.direction === "inbound")
+                inbound++;
+            else
+                outbound++;
+        }
+        if (inbound + outbound > 0) {
+            logger.info({ inbound, outbound }, "Reaped orphan chat attachments");
+        }
+        return { inbound, outbound };
+    }
+    /**
+     * Delete attachment rows whose bound message no longer exists, plus their
+     * on-disk directories. In production the FK normally removes these rows when
+     * messages are pruned, but this is the recovery path for older databases,
+     * tests with FK disabled, or a failed cascade.
+     */
+    reapDanglingMessageRefs() {
+        const rows = this.db
+            .prepare(`SELECT id
+         FROM chat_attachments AS a
+         WHERE a.message_id IS NOT NULL
+           AND NOT EXISTS (
+             SELECT 1 FROM messages AS m WHERE m.id = a.message_id
+           )`)
+            .all();
+        let removed = 0;
+        for (const row of rows) {
+            this.db.prepare(`DELETE FROM chat_attachments WHERE id = ?`).run(row.id);
+            this.safeRmTree(this.dirFor(row.id));
+            removed++;
+        }
+        if (removed > 0) {
+            logger.info({ removed }, "Reaped dangling chat attachment message refs");
+        }
+        return removed;
+    }
+    /**
+     * Remove physical attachment directories that no longer have a DB row. This
+     * catches the normal retention path where `messages` deletion cascades the
+     * `chat_attachments` row before the filesystem can be cleaned. Fresh
+     * directories are skipped so an in-flight ingest cannot be mistaken for an
+     * orphan before its row is inserted.
+     */
+    reapUntrackedDirs(options = {}) {
+        const minAgeMs = (options.minAgeHours ?? 1) * 60 * 60 * 1000;
+        if (!existsSync(this.rootDir))
+            return 0;
+        let entries;
+        try {
+            entries = readdirSync(this.rootDir);
+        }
+        catch (err) {
+            logger.warn({ err, rootDir: this.rootDir }, "Failed to list attachment root");
+            return 0;
+        }
+        const exists = this.db.prepare(`SELECT 1 FROM chat_attachments WHERE id = ?`);
+        let removed = 0;
+        const now = Date.now();
+        for (const entry of entries) {
+            const dir = this.dirFor(entry);
+            let stat;
+            try {
+                stat = statSync(dir);
+            }
+            catch {
+                continue;
+            }
+            if (!stat.isDirectory())
+                continue;
+            if (now - stat.mtimeMs < minAgeMs)
+                continue;
+            if (exists.get(entry))
+                continue;
+            this.safeRmTree(dir);
+            removed++;
+        }
+        if (removed > 0) {
+            logger.info({ removed }, "Reaped untracked chat attachment directories");
+        }
+        return removed;
+    }
+    /**
+     * Hard-link (or copy across volumes) an attachment into the session's
+     * `_attachments/` subdir. Idempotent; safe to call per dispatch.
+     */
+    stageIntoWorkdir(params) {
+        const stagedDir = join(params.sessionDir, "_attachments");
+        mkdirSync(stagedDir, { recursive: true });
+        const dst = join(stagedDir, params.row.safeFilename);
+        if (!existsSync(params.row.path)) {
+            throw new Error(`Attachment ${params.row.id} missing at ${params.row.path}`);
+        }
+        hardLinkOrCopy(params.row.path, dst);
+        return dst;
+    }
+    safeRmTree(dir) {
+        try {
+            if (existsSync(dir)) {
+                const stat = statSync(dir);
+                if (stat.isDirectory()) {
+                    rmSync(dir, { recursive: true, force: true });
+                }
+                else {
+                    unlinkSync(dir);
+                }
+            }
+        }
+        catch (err) {
+            logger.warn({ err, dir }, "Failed to remove attachment dir");
+        }
+    }
+    async waitForWriteStreamSettled(stream, options) {
+        if (stream.closed) {
+            return;
+        }
+        await new Promise((resolve) => {
+            let settled = false;
+            const finish = () => {
+                if (settled)
+                    return;
+                settled = true;
+                stream.off("close", finish);
+                stream.off("error", finish);
+                resolve();
+            };
+            stream.once("close", finish);
+            stream.once("error", finish);
+            if (options?.destroy && !stream.destroyed) {
+                stream.destroy();
+            }
+        });
+    }
+}
+//# sourceMappingURL=store.js.map

package/dist/services/attachments/store.js.map

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

package/dist/services/calendar/outlook/graph-calendar-client.d.ts

@@ -0,0 +1,114 @@
+import { GraphClient, type GraphClientOptions, type GraphTokenProvider } from "../../mail/outlook/graph-client.js";
+/**
+ * Microsoft Graph calendar wrapper (SETUP-FLOW-REDESIGN-PLAN §6.1 / §10).
+ *
+ * Mirrors `services/mail/outlook/graph-client.ts` in spirit — pure wrapper
+ * with an injected `GraphTokenProvider`, no MSAL coupling at this layer.
+ * The token provider that backs production calls is the same one
+ * `OutlookGraphProvider` builds when consuming the per-account MSAL cache;
+ * tests inject a stub.
+ *
+ * v1 ships on-demand reads + writes only; the design plan defers
+ * `OutlookCalendarPoller` to a follow-up. Until that observer lands,
+ * `schedule.approaching` events are not emitted for Outlook calendars.
+ */
+export interface OutlookCalendarRef {
+    id: string;
+    name: string;
+    isDefaultCalendar: boolean;
+    /** Owner email when present; falls back to display name. */
+    owner: string | null;
+    /** Calendar tz declared by Graph (e.g. `"Tokyo Standard Time"`). */
+    timeZone: string | null;
+}
+export interface OutlookCalendarEvent {
+    id: string;
+    subject: string;
+    /** Start in ISO-8601 (UTC). Combined from Graph's `dateTime`+`timeZone`. */
+    startUtc: string;
+    /** End in ISO-8601 (UTC). */
+    endUtc: string;
+    isAllDay: boolean;
+    organizer: string | null;
+    webLink: string | null;
+    /** Free-form preview from Graph's `bodyPreview`. */
+    bodyPreview: string;
+}
+export interface ListEventsRange {
+    /** Inclusive lower bound. */
+    startUtc: string;
+    /** Exclusive upper bound. */
+    endUtc: string;
+}
+export interface ListEventsOptions {
+    /** Optional calendar id; omit for the default calendar (`/me/calendar`). */
+    calendarId?: string;
+    /** Per-page cap (Graph default = 10; we default 50). Pages are stitched together via `@odata.nextLink`. */
+    top?: number;
+    /**
+     * Hard ceiling on the total number of events returned across all pages.
+     * Stops following `@odata.nextLink` once reached. Defaults to 1000 — high
+     * enough that v1's wizard / Connections page never trips it on a sane
+     * calendar, low enough that a runaway recurrence does not pull pages
+     * indefinitely.
+     */
+    maxItems?: number;
+}
+/**
+ * Two construction shapes:
+ *   1. `{ graphClient }` — reuse a pre-built {@link GraphClient}. Production
+ *      code in `OutlookGraphProvider.createCalendarClient` uses this so the
+ *      mail and calendar surfaces share one concurrency limiter + abortSignal,
+ *      respecting Graph's 4-concurrent / (app, tenant) cap (§3.8).
+ *   2. `{ tokenProvider, ...graphOpts }` — construct a fresh `GraphClient`.
+ *      Used by tests via the {@link OutlookGraphCalendarClient.fromTokenProvider}
+ *      factory.
+ *
+ * Exactly one of `graphClient` / `tokenProvider` must be supplied; the
+ * constructor throws otherwise. Supplying both prefers `graphClient` (the
+ * `tokenProvider` is unused — easy to read but easy to misread, so mark it
+ * accordingly in call sites).
+ */
+export type OutlookGraphCalendarClientOptions = {
+    graphClient: GraphClient;
+} | (GraphClientOptions & {
+    graphClient?: undefined;
+});
+/**
+ * Bare-minimum surface required by the wizard's Calendar step + the
+ * `/api/calendar/outlook/*` routes. Add capabilities here in lockstep with
+ * the route extension; the registry-driven probe consumes none of them
+ * until `outlook_calendar.backendConnectors` is widened beyond `{}`.
+ */
+export declare class OutlookGraphCalendarClient {
+    private readonly client;
+    constructor(options: OutlookGraphCalendarClientOptions);
+    static fromTokenProvider(tokenProvider: GraphTokenProvider, extra?: Omit<GraphClientOptions, "tokenProvider">): OutlookGraphCalendarClient;
+    /**
+     * Production constructor for {@link OutlookGraphProvider} — reuses the
+     * provider's pre-built `GraphClient` so mail + calendar share one
+     * concurrency limiter + abortSignal. Prefer this over `fromTokenProvider`
+     * when an `OutlookGraphProvider` is in scope.
+     */
+    static fromGraphClient(graphClient: GraphClient): OutlookGraphCalendarClient;
+    /**
+     * List the user's calendars. The default calendar is flagged via
+     * `isDefaultCalendar` so the UI can pre-select it without a second call.
+     * Does not paginate — Graph caps `/me/calendars` at 50, which exceeds any
+     * sensible single-user setup.
+     */
+    listCalendars(): Promise<OutlookCalendarRef[]>;
+    /**
+     * List events overlapping `[startUtc, endUtc)`. Uses the Graph
+     * `calendarView` endpoint, which expands recurrences in-server (vs. `events`
+     * which returns raw recurrence masters).
+     *
+     * Pagination follows `@odata.nextLink` until either no further pages exist
+     * or `options.maxItems` (default 1000) is reached. Without this loop a
+     * caller asking for a 90-day window with >50 events per page would silently
+     * truncate at the first page — Microsoft Graph's `calendarView` does not
+     * promise to return everything inline.
+     */
+    listEvents(range: ListEventsRange, options?: ListEventsOptions): Promise<OutlookCalendarEvent[]>;
+}
+//# sourceMappingURL=graph-calendar-client.d.ts.map

package/dist/services/calendar/outlook/graph-calendar-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-calendar-client.d.ts","sourceRoot":"","sources":["../../../../src/services/calendar/outlook/graph-calendar-client.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,WAAW,EACX,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACxB,MAAM,oCAAoC,CAAC;AAE5C;;;;;;;;;;;;GAYG;AAEH,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,iBAAiB,EAAE,OAAO,CAAC;IAC3B,4DAA4D;IAC5D,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,oEAAoE;IACpE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,QAAQ,EAAE,MAAM,CAAC;IACjB,6BAA6B;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,OAAO,CAAC;IAClB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,oDAAoD;IACpD,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B,6BAA6B;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,6BAA6B;IAC7B,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,iBAAiB;IAChC,4EAA4E;IAC5E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2GAA2G;IAC3G,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,iCAAiC,GACzC;IAAE,WAAW,EAAE,WAAW,CAAA;CAAE,GAC5B,CAAC,kBAAkB,GAAG;IAAE,WAAW,CAAC,EAAE,SAAS,CAAA;CAAE,CAAC,CAAC;AAEvD;;;;;GAKG;AACH,qBAAa,0BAA0B;IACrC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;gBAEzB,OAAO,EAAE,iCAAiC;IAYtD,MAAM,CAAC,iBAAiB,CACtB,aAAa,EAAE,kBAAkB,EACjC,KAAK,GAAE,IAAI,CAAC,kBAAkB,EAAE,eAAe,CAAM,GACpD,0BAA0B;IAI7B;;;;;OAKG;IACH,MAAM,CAAC,eAAe,CAAC,WAAW,EAAE,WAAW,GAAG,0BAA0B;IAI5E;;;;;OAKG;IACG,aAAa,IAAI,OAAO,CAAC,kBAAkB,EAAE,CAAC;IAapD;;;;;;;;;;OAUG;IACG,UAAU,CACd,KAAK,EAAE,eAAe,EACtB,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,oBAAoB,EAAE,CAAC;CAuCnC"}