@adonis-agora/agent 0.1.0

package/dist/src/stores/factory.js

@@ -0,0 +1,341 @@
+/**
+ * The store factory namespace used in `config/agent.ts`:
+ *
+ * ```ts
+ * import { defineConfig, stores } from '@adonis-agora/agent'
+ *
+ * export default defineConfig({
+ *   store: 'lucid',
+ *   stores: {
+ *     memory: stores.memory(),
+ *     lucid: stores.lucid({ connection: 'pg' }),
+ *   },
+ * })
+ * ```
+ *
+ * Each factory returns a {@link StoreFactory} — a lazy thunk. Calling it in the config file costs
+ * nothing; the peer dependency is only imported when the provider builds the selected store at boot.
+ */
+export const stores = {
+    /** In-memory store — single-process, non-durable. Handy for tests and scratch/dev apps. */
+    memory(_config = {}) {
+        return async () => {
+            const { InMemoryAgentStore } = await import('../testing/in-memory-store.js');
+            return new InMemoryAgentStore();
+        };
+    },
+    /** Persist threads/messages/tool-calls/usage in SQL via `@adonisjs/lucid`. */
+    lucid(config = {}) {
+        return async () => {
+            const db = (await import('@adonisjs/lucid/services/db')).default;
+            const { LucidAgentStore } = await import('./lucid.js');
+            const client = (config.connection !== undefined
+                ? db.connection(config.connection)
+                : db);
+            return new LucidAgentStore(client, {
+                ...(config.autoCreateTables !== undefined
+                    ? { autoCreateTables: config.autoCreateTables }
+                    : {}),
+            });
+        };
+    },
+};
+/**
+ * The quota factory namespace used in `config/agent.ts`, mirroring {@link stores}:
+ *
+ * ```ts
+ * export default defineConfig({
+ *   store: 'lucid',
+ *   stores: { lucid: stores.lucid() },
+ *   quota: quotas.ledger({ limitTokens: 1_000_000 }),
+ * })
+ * ```
+ */
+export const quotas = {
+    /** In-memory per-actor/day budget — single-process, non-durable. Handy for tests and dev apps. */
+    memory(config) {
+        return async () => {
+            const { InMemoryQuotaStore } = await import('../testing/in-memory-quota.js');
+            return new InMemoryQuotaStore(config.limitTokens);
+        };
+    },
+    /**
+     * Enforce the budget off the persisted token-usage ledger (the selected `store`) — one source of
+     * truth across replicas, with no double-counting. Pairs with any {@link AgentStore}.
+     */
+    ledger(config) {
+        return async ({ store }) => {
+            const { LedgerQuotaStore } = await import('./ledger-quota.js');
+            return new LedgerQuotaStore(store, config.limitTokens);
+        };
+    },
+};
+/**
+ * The pricing factory namespace used in `config/agent.ts`, mirroring {@link stores}:
+ *
+ * ```ts
+ * export default defineConfig({
+ *   pricingStore: pricingStores.lucid(),
+ * })
+ * ```
+ *
+ * Seed model prices once (e.g. in a command) with `seedModelPrices(store, [...])`.
+ */
+export const pricingStores = {
+    /** In-memory pricing table — for tests and the offline demo. */
+    memory() {
+        return async () => {
+            const { InMemoryPricingStore } = await import('../testing/in-memory-pricing.js');
+            return new InMemoryPricingStore();
+        };
+    },
+    /** Persist per-model prices in SQL (the `agent_model_pricing` table) via `@adonisjs/lucid`. */
+    lucid(config = {}) {
+        return async () => {
+            const db = (await import('@adonisjs/lucid/services/db')).default;
+            const { LucidPricingStore } = await import('./lucid-pricing.js');
+            const client = (config.connection !== undefined
+                ? db.connection(config.connection)
+                : db);
+            return new LucidPricingStore(client);
+        };
+    },
+};
+/**
+ * The governance-queries factory namespace used in `config/agent.ts`, mirroring {@link pricingStores}:
+ *
+ * ```ts
+ * export default defineConfig({
+ *   pricingStore: pricingStores.lucid(),
+ *   governanceQueries: governanceQueries.lucid(),
+ * })
+ * ```
+ *
+ * The Lucid read-model aggregates the same five agent tables the store writes and prices cost against
+ * the configured `pricingStore`; wiring it mounts the `/agent/governance/*` read routes.
+ */
+export const governanceQueries = {
+    /** Aggregate the five agent tables in SQL via `@adonisjs/lucid`, priced against the pricing store. */
+    lucid(config = {}) {
+        return async ({ pricingStore }) => {
+            const db = (await import('@adonisjs/lucid/services/db')).default;
+            const { LucidGovernanceQueries } = await import('./lucid-governance-queries.js');
+            const client = (config.connection !== undefined
+                ? db.connection(config.connection)
+                : db);
+            return new LucidGovernanceQueries(client, pricingStore);
+        };
+    },
+};
+/**
+ * The retriever factory namespace used in `config/agent.ts`, mirroring {@link stores}:
+ *
+ * ```ts
+ * export default defineConfig({
+ *   model: () => aiSdkModel({ model: '...' }),
+ *   retriever: retrievers.memory({ embedder: myEmbedder, documents: [...] }),
+ *   retrievalTopK: 5,
+ * })
+ * ```
+ *
+ * Use `retrievers.pgvector({...})` for the production pgvector/Lucid store; `retrievers.memory` covers
+ * tests and small/embedded corpora.
+ */
+export const retrievers = {
+    /** In-memory embedding retriever — cosine over a Map, single-process. Handy for tests and dev apps. */
+    memory(config) {
+        return async () => {
+            const { MemoryVectorStore } = await import('../rag/memory-vector-store.js');
+            const { EmbeddingRetriever } = await import('../rag/embedding-retriever.js');
+            const { ingestDocuments } = await import('../rag/ingest.js');
+            const embedder = typeof config.embedder === 'function' ? await config.embedder() : config.embedder;
+            const store = new MemoryVectorStore();
+            if (config.documents !== undefined && config.documents.length > 0) {
+                await ingestDocuments(config.documents, {
+                    embedder,
+                    store,
+                    ...(config.chunkSize !== undefined ? { chunkSize: config.chunkSize } : {}),
+                    ...(config.overlap !== undefined ? { overlap: config.overlap } : {}),
+                });
+            }
+            return new EmbeddingRetriever(embedder, store);
+        };
+    },
+    /**
+     * Production pgvector retriever — cosine/L2/inner similarity over a `vector(N)` column via
+     * `@adonisjs/lucid` (raw SQL for the pgvector operators; the embedding is a `?::vector` binding). The
+     * Lucid peer is imported lazily inside the thunk (unless a structural `db` is passed), so it stays
+     * optional. Pass `ensureSchema: true` to provision the extension/table/index at boot for tests.
+     */
+    pgvector(config) {
+        return async () => {
+            const { PgVectorStore, PgVectorRetriever } = await import('../rag/pg-vector-store.js');
+            const { ingestDocuments } = await import('../rag/ingest.js');
+            const embedder = typeof config.embedder === 'function' ? await config.embedder() : config.embedder;
+            const db = config.db ??
+                (await (async () => {
+                    const dbService = (await import('@adonisjs/lucid/services/db')).default;
+                    return (config.connection !== undefined
+                        ? dbService.connection(config.connection)
+                        : dbService);
+                })());
+            const store = new PgVectorStore(db, {
+                ...(config.table !== undefined ? { table: config.table } : {}),
+                ...(config.dimension !== undefined ? { dimension: config.dimension } : {}),
+                ...(config.metric !== undefined ? { metric: config.metric } : {}),
+                ...(config.columns !== undefined ? { columns: config.columns } : {}),
+            });
+            if (config.ensureSchema === true) {
+                await store.ensureSchema();
+            }
+            if (config.documents !== undefined && config.documents.length > 0) {
+                await ingestDocuments(config.documents, {
+                    embedder,
+                    store,
+                    ...(config.chunkSize !== undefined ? { chunkSize: config.chunkSize } : {}),
+                    ...(config.overlap !== undefined ? { overlap: config.overlap } : {}),
+                });
+            }
+            return new PgVectorRetriever(embedder, store);
+        };
+    },
+};
+/**
+ * The attachment-staging factory namespace used in `config/agent.ts`, mirroring {@link stores}:
+ *
+ * ```ts
+ * export default defineConfig({
+ *   model: () => aiSdkModel({ model: '...' }),
+ *   attachmentStaging: attachmentStores.memory(),
+ * })
+ * ```
+ *
+ * A real deployment binds its own staging store (presigning against S3/GCS or wrapping the host's
+ * media pipeline) by passing an instance; `attachmentStores.memory` covers tests and the offline demo.
+ */
+export const attachmentStores = {
+    /**
+     * In-memory staging — encodes the uploaded bytes into a `data:` URL the model provider fetches
+     * inline (no external object store, no presigning). Single-process; handy for tests and dev apps.
+     */
+    memory() {
+        return async () => {
+            const { InMemoryAttachmentStagingStore } = await import('../testing/in-memory-attachment-staging.js');
+            return new InMemoryAttachmentStagingStore();
+        };
+    },
+};
+/**
+ * The token-sink factory namespace used in `config/agent.ts`, mirroring {@link stores}. Also exported as
+ * `streamTransports` (an alias — pick whichever name reads better):
+ *
+ * ```ts
+ * import { defineConfig, tokenSinks } from '@adonis-agora/agent'
+ *
+ * export default defineConfig({
+ *   model: () => aiSdkModel({ model: '...' }),
+ *   sink: tokenSinks.redis({ connection: 'main' }), // multi-replica; any pod serves any run's SSE
+ * })
+ * ```
+ *
+ * Omitting `sink` entirely keeps the in-process sink (single replica); `tokenSinks.memory()` selects it
+ * explicitly. `tokenSinks.redis()` fans a run's tokens across replicas over Redis pub/sub + a replayable
+ * list, keeping the SSE envelope byte-identical. The `@adonisjs/redis` peer is imported ONLY inside the
+ * `redis` thunk, so it stays fully optional.
+ */
+export const tokenSinks = {
+    /** The in-process sink — per-run in-memory buffers, single replica. The default when `sink` is omitted. */
+    memory() {
+        return async () => {
+            const { InProcessTokenStreamSink } = await import('../in-process-sink.js');
+            return new InProcessTokenStreamSink();
+        };
+    },
+    /**
+     * The Redis multi-replica sink: any pod can serve any run's SSE stream. Builds a
+     * {@link RedisStreamClient} over `@adonisjs/redis` (imported lazily here), or uses `config.client` when
+     * provided. Requires `@adonisjs/redis` installed + configured (`config/redis.ts`) unless a `client` is
+     * passed.
+     */
+    redis(config = {}) {
+        return async () => {
+            const { RedisTokenStreamSink } = await import('../redis-token-stream-sink.js');
+            const client = config.client ?? (await buildAdonisRedisClient(config.connection));
+            return new RedisTokenStreamSink(client, {
+                ...(config.keyPrefix !== undefined ? { keyPrefix: config.keyPrefix } : {}),
+            });
+        };
+    },
+};
+/** Alias of {@link tokenSinks}. */
+export const streamTransports = tokenSinks;
+/**
+ * Lazily import `@adonisjs/redis` and adapt its connection to a {@link RedisStreamClient}. The specifier
+ * is held in a variable so TypeScript does NOT resolve the (optional, possibly-uninstalled) module at
+ * build time — it stays a runtime-only dependency. Uses a DEDICATED duplicated connection per subscribe
+ * (a subscribed Redis connection can't run other commands).
+ */
+async function buildAdonisRedisClient(connection) {
+    const specifier = '@adonisjs/redis/services/main';
+    const mod = (await import(specifier));
+    const redis = mod.default;
+    const conn = connection !== undefined ? redis.connection(connection) : redis.connection();
+    return adaptIoRedis(conn.ioConnection);
+}
+/** Adapt an `ioredis`-shaped client to {@link RedisStreamClient}, using a duplicated subscriber connection. */
+function adaptIoRedis(io) {
+    return {
+        rpush: async (key, value) => {
+            await io.rpush(key, value);
+        },
+        lrange: (key, start, stop) => io.lrange(key, start, stop),
+        set: async (key, value) => {
+            await io.set(key, value);
+        },
+        get: (key) => io.get(key),
+        publish: async (channel, message) => {
+            await io.publish(channel, message);
+        },
+        subscribe: async (channel, onMessage) => {
+            const subscriber = io.duplicate();
+            const listener = (incoming, message) => {
+                if (incoming === channel) {
+                    onMessage(message);
+                }
+            };
+            subscriber.on('message', listener);
+            await subscriber.subscribe(channel);
+            return async () => {
+                subscriber.off('message', listener);
+                await subscriber.unsubscribe(channel);
+                await subscriber.quit();
+            };
+        },
+        del: async (...keys) => {
+            await io.del(...keys);
+        },
+    };
+}
+/**
+ * The actor-directory factory namespace used in `config/agent.ts`, mirroring {@link stores}:
+ *
+ * ```ts
+ * export default defineConfig({
+ *   actorDirectory: actorDirectories.memory({ labels: { u_1: 'Ada Lovelace' } }),
+ * })
+ * ```
+ *
+ * Omit `actorDirectory` → governance surfaces render raw opaque refs. A real deployment binds its own
+ * directory over the host's user table by passing an instance; `actorDirectories.memory` covers tests,
+ * the offline demo, and small fixed label tables.
+ */
+export const actorDirectories = {
+    /** In-memory `actorRef → label` map — single-process. Handy for tests and dev apps. */
+    memory(config = {}) {
+        return async () => {
+            const { InMemoryActorDirectory } = await import('../testing/in-memory-actor-directory.js');
+            return new InMemoryActorDirectory(config.labels ?? {});
+        };
+    },
+};
+//# sourceMappingURL=factory.js.map

package/dist/src/stores/factory.js.map

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

package/dist/src/stores/ledger-quota.d.ts

@@ -0,0 +1,23 @@
+import type { AgentStore } from '../spi/agent-store.js';
+import type { QuotaStore } from '../spi/quota-store.js';
+import type { QuotaState } from '../types.js';
+/**
+ * A production {@link QuotaStore} backed by the persisted usage ledger (the append-only
+ * `agent_token_usage` table the Lucid store writes each turn to). `check` reads the actor's
+ * tokens-so-far for the day straight from {@link AgentStore.quotaToday} and compares it to a fixed
+ * daily limit; `bump` is a deliberate no-op because the loop's `recordUsage` already writes every
+ * turn's tokens to that same ledger. One source of truth — so enforcement and what a usage dashboard
+ * reports can never drift, and it works across replicas with no extra shared state.
+ *
+ * Ledger-agnostic by design: it wraps any {@link AgentStore} (the `lucid` store for production, the
+ * in-memory store for tests), so no dedicated quota table is needed — the token-usage ledger IS the
+ * ledger. Wire it in `config/agent.ts` via `quota: quotas.ledger({ limitTokens })`.
+ */
+export declare class LedgerQuotaStore implements QuotaStore {
+    private readonly store;
+    private readonly limitTokens;
+    constructor(store: AgentStore, limitTokens: number);
+    check(actorRef: string, day: string): Promise<QuotaState>;
+    bump(): Promise<void>;
+}
+//# sourceMappingURL=ledger-quota.d.ts.map

package/dist/src/stores/ledger-quota.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ledger-quota.d.ts","sourceRoot":"","sources":["../../../src/stores/ledger-quota.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C;;;;;;;;;;;GAWG;AACH,qBAAa,gBAAiB,YAAW,UAAU;IAE/C,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,WAAW;gBADX,KAAK,EAAE,UAAU,EACjB,WAAW,EAAE,MAAM;IAGhC,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IASzD,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAG5B"}

package/dist/src/stores/ledger-quota.js

@@ -0,0 +1,32 @@
+/**
+ * A production {@link QuotaStore} backed by the persisted usage ledger (the append-only
+ * `agent_token_usage` table the Lucid store writes each turn to). `check` reads the actor's
+ * tokens-so-far for the day straight from {@link AgentStore.quotaToday} and compares it to a fixed
+ * daily limit; `bump` is a deliberate no-op because the loop's `recordUsage` already writes every
+ * turn's tokens to that same ledger. One source of truth — so enforcement and what a usage dashboard
+ * reports can never drift, and it works across replicas with no extra shared state.
+ *
+ * Ledger-agnostic by design: it wraps any {@link AgentStore} (the `lucid` store for production, the
+ * in-memory store for tests), so no dedicated quota table is needed — the token-usage ledger IS the
+ * ledger. Wire it in `config/agent.ts` via `quota: quotas.ledger({ limitTokens })`.
+ */
+export class LedgerQuotaStore {
+    store;
+    limitTokens;
+    constructor(store, limitTokens) {
+        this.store = store;
+        this.limitTokens = limitTokens;
+    }
+    async check(actorRef, day) {
+        const { usedTokens } = await this.store.quotaToday(actorRef, day);
+        return {
+            usedTokens,
+            limitTokens: this.limitTokens,
+            withinLimit: usedTokens < this.limitTokens,
+        };
+    }
+    async bump() {
+        // No-op: the ledger is the source of truth — recordUsage already persisted this turn's tokens.
+    }
+}
+//# sourceMappingURL=ledger-quota.js.map

package/dist/src/stores/ledger-quota.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ledger-quota.js","sourceRoot":"","sources":["../../../src/stores/ledger-quota.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,gBAAgB;IAER;IACA;IAFnB,YACmB,KAAiB,EACjB,WAAmB;QADnB,UAAK,GAAL,KAAK,CAAY;QACjB,gBAAW,GAAX,WAAW,CAAQ;IACnC,CAAC;IAEJ,KAAK,CAAC,KAAK,CAAC,QAAgB,EAAE,GAAW;QACvC,MAAM,EAAE,UAAU,EAAE,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;QAClE,OAAO;YACL,UAAU;YACV,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,WAAW,EAAE,UAAU,GAAG,IAAI,CAAC,WAAW;SAC3C,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,IAAI;QACR,+FAA+F;IACjG,CAAC;CACF"}

package/dist/src/stores/lucid-governance-queries.d.ts

@@ -0,0 +1,73 @@
+import type { ActorSpendRow, AgentGovernanceQueries, GovernanceRange, ListRunsFilter, ListRunsResult, ModelSpendRow, PendingApprovalRow, PendingApprovalsFilter, PerToolStatRow, RunDetail, RunReliability, ThreadActivityRow, ToolCallActivityRow, ToolStatsRange, UsageTrendPoint } from '../spi/governance-queries.js';
+import type { AgentPricingStore } from '../spi/pricing-store.js';
+import type { LucidDatabaseLike } from './lucid.js';
+/**
+ * A production {@link AgentGovernanceQueries} — the read/analytics half of the store SPI — backed by
+ * AdonisJS **Lucid** (Knex) over the same five agent tables {@link import('./lucid.js').LucidAgentStore}
+ * writes. Like the store it touches only the structural {@link LucidDatabaseLike} slice, so
+ * `@adonisjs/lucid` stays an *optional peer* (the factory casts the real `db` in).
+ *
+ * Cost is the token ledger priced against the current prices from the injected {@link AgentPricingStore}
+ * (fetched once per query, exactly like the Drizzle/MikroORM references and the loop's cost fold), so a
+ * host that binds its own pricing store controls the cost every governance surface reports. A
+ * provider-reported `cost_usd` on a usage row always wins; an unpriced model contributes 0 cost (its
+ * tokens still count). Omit the pricing store entirely for a zero-cost read-model. Aggregation is
+ * in-process (like `quotaToday`) so UTC-day bucketing stays dialect-portable across SQLite/Postgres/MySQL
+ * — the behavioral twin of {@link import('../testing/in-memory-governance-queries.js').InMemoryGovernanceQueries}.
+ */
+export declare class LucidGovernanceQueries implements AgentGovernanceQueries {
+    private readonly db;
+    private readonly pricingStore?;
+    constructor(db: LucidDatabaseLike, pricingStore?: AgentPricingStore | undefined);
+    private loadPricing;
+    /** Provider-reported cost wins per row; otherwise the cache-aware token estimate (0 when unpriced). */
+    private rowCost;
+    /** The usage ledger rows whose `created_at` falls inside the inclusive UTC-day range. */
+    private usageInRange;
+    spendByModel(range: GovernanceRange): Promise<ModelSpendRow[]>;
+    spendByActor(range: GovernanceRange): Promise<ActorSpendRow[]>;
+    usageTrend(range: GovernanceRange): Promise<UsageTrendPoint[]>;
+    /**
+     * Newest-first recent tool calls, capped at `limit`. Resolves each call's `threadId` through its
+     * owning message (the structural query slice has no `join`, so it's one lookup per call — bounded by
+     * `limit`, mirroring the reference adapters' N+1 for the recent feeds).
+     */
+    recentToolCalls(limit: number): Promise<ToolCallActivityRow[]>;
+    /**
+     * Newest-first recent threads (soft-deleted excluded, mirroring `listThreads`/the reference), each
+     * with its message count and rolled-up token total, capped at `limit`.
+     */
+    recentThreads(limit: number): Promise<ThreadActivityRow[]>;
+    /**
+     * Filterable, cursor-paginated run list, newest-first (`started_at` desc, then `id` desc for a
+     * stable tiebreak). The cursor is an opaque offset (over the SAME filter set); a page fetches
+     * `limit + 1` rows to learn whether a next page exists. A store without recorded runs yields an
+     * empty page.
+     */
+    listRuns(filter?: ListRunsFilter): Promise<ListRunsResult>;
+    /**
+     * The full trace of one run: the run row plus every message / tool call / usage row stamped with
+     * its `run_id` (oldest first), and the subset of tool calls still `pending_approval`. `null` when
+     * the run is unknown.
+     */
+    runDetail(runId: string): Promise<RunDetail | null>;
+    /**
+     * Tool calls sitting `pending_approval`, oldest first (an inbox drains from the back). Each call's
+     * owning actor is resolved through its run (`run_id → agent_run.actor_ref`), falling back to its
+     * thread (`message → agent_thread.actor_ref`) for a call recorded before run tracking. The `actor`
+     * filter is applied after resolution; `limit` caps the returned inbox.
+     */
+    pendingApprovals(filter?: PendingApprovalsFilter): Promise<PendingApprovalRow[]>;
+    /**
+     * Per-tool call/failure/rejection/latency rollup over the (optional) range, highest call count
+     * first. `avgDurationMs` is the mean `execution_ms` across calls that recorded one; `null` when
+     * none did.
+     */
+    perToolStats(range?: ToolStatsRange): Promise<PerToolStatRow[]>;
+    /**
+     * Success / failure / cancel rates + mean settled-run duration over the (optional) range, bucketed
+     * on `started_at`. A store without recorded runs yields all zeros / `null` duration.
+     */
+    runReliability(range?: ToolStatsRange): Promise<RunReliability>;
+}
+//# sourceMappingURL=lucid-governance-queries.d.ts.map

package/dist/src/stores/lucid-governance-queries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lucid-governance-queries.d.ts","sourceRoot":"","sources":["../../../src/stores/lucid-governance-queries.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,EACb,sBAAsB,EACtB,eAAe,EACf,cAAc,EACd,cAAc,EACd,aAAa,EACb,kBAAkB,EAClB,sBAAsB,EACtB,cAAc,EACd,SAAS,EAET,cAAc,EAId,iBAAiB,EACjB,mBAAmB,EACnB,cAAc,EACd,eAAe,EAChB,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EAAE,iBAAiB,EAAqB,MAAM,yBAAyB,CAAC;AAGpF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAsHpD;;;;;;;;;;;;;GAaG;AACH,qBAAa,sBAAuB,YAAW,sBAAsB;IAEjE,OAAO,CAAC,QAAQ,CAAC,EAAE;IACnB,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC;gBADb,EAAE,EAAE,iBAAiB,EACrB,YAAY,CAAC,EAAE,iBAAiB,YAAA;YAGrC,WAAW;IASzB,uGAAuG;IACvG,OAAO,CAAC,OAAO;IAef,yFAAyF;YAC3E,YAAY;IAWpB,YAAY,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;IA6B9D,YAAY,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;IAoB9D,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IAiBpE;;;;OAIG;IACG,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,EAAE,CAAC;IAwBpE;;;OAGG;IACG,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAoChE;;;;;OAKG;IACG,QAAQ,CAAC,MAAM,GAAE,cAAmB,GAAG,OAAO,CAAC,cAAc,CAAC;IAgCpE;;;;OAIG;IACG,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC;IA4CzD;;;;;OAKG;IACG,gBAAgB,CAAC,MAAM,GAAE,sBAA2B,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC;IA4C1F;;;;OAIG;IACG,YAAY,CAAC,KAAK,GAAE,cAAmB,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IA4DzE;;;OAGG;IACG,cAAc,CAAC,KAAK,GAAE,cAAmB,GAAG,OAAO,CAAC,cAAc,CAAC;CAsC1E"}