@fideliosai/server 2026.331.0-canary.0

package/dist/services/plugin-state-store.js

@@ -0,0 +1,190 @@
+import { and, eq, isNull } from "drizzle-orm";
+import { plugins, pluginState } from "@fideliosai/db";
+import { notFound } from "../errors.js";
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/** Default namespace used when the plugin does not specify one. */
+const DEFAULT_NAMESPACE = "default";
+/**
+ * Build the WHERE clause conditions for a scoped state lookup.
+ *
+ * The five-part composite key is:
+ *   `(pluginId, scopeKind, scopeId, namespace, stateKey)`
+ *
+ * `scopeId` may be null (for `instance` scope) or a non-empty string.
+ */
+function scopeConditions(pluginId, scopeKind, scopeId, namespace, stateKey) {
+    const conditions = [
+        eq(pluginState.pluginId, pluginId),
+        eq(pluginState.scopeKind, scopeKind),
+        eq(pluginState.namespace, namespace),
+        eq(pluginState.stateKey, stateKey),
+    ];
+    if (scopeId != null && scopeId !== "") {
+        conditions.push(eq(pluginState.scopeId, scopeId));
+    }
+    else {
+        conditions.push(isNull(pluginState.scopeId));
+    }
+    return and(...conditions);
+}
+// ---------------------------------------------------------------------------
+// Service
+// ---------------------------------------------------------------------------
+/**
+ * Plugin State Store — scoped key-value persistence for plugin workers.
+ *
+ * Provides `get`, `set`, `delete`, and `list` operations over the
+ * `plugin_state` table. Each plugin's data is strictly namespaced by
+ * `pluginId` so plugins cannot read or write each other's state.
+ *
+ * This service implements the server-side backing for the `ctx.state` SDK
+ * client exposed to plugin workers. The host is responsible for:
+ * - enforcing `plugin.state.read` capability before calling `get` / `list`
+ * - enforcing `plugin.state.write` capability before calling `set` / `delete`
+ *
+ * @see PLUGIN_SPEC.md §14 — SDK Surface (`ctx.state`)
+ * @see PLUGIN_SPEC.md §15.1 — Capabilities: Plugin State
+ * @see PLUGIN_SPEC.md §21.3 — `plugin_state` table
+ */
+export function pluginStateStore(db) {
+    // -----------------------------------------------------------------------
+    // Internal helpers
+    // -----------------------------------------------------------------------
+    async function assertPluginExists(pluginId) {
+        const rows = await db
+            .select({ id: plugins.id })
+            .from(plugins)
+            .where(eq(plugins.id, pluginId));
+        if (rows.length === 0) {
+            throw notFound(`Plugin not found: ${pluginId}`);
+        }
+    }
+    // -----------------------------------------------------------------------
+    // Public API
+    // -----------------------------------------------------------------------
+    return {
+        /**
+         * Read a state value.
+         *
+         * Returns the stored JSON value, or `null` if no entry exists for the
+         * given scope and key.
+         *
+         * Requires `plugin.state.read` capability (enforced by the caller).
+         *
+         * @param pluginId - UUID of the owning plugin
+         * @param scopeKind - Granularity of the scope
+         * @param scopeId - Identifier for the scoped entity (null for `instance` scope)
+         * @param stateKey - The key to read
+         * @param namespace - Sub-namespace (defaults to `"default"`)
+         */
+        get: async (pluginId, scopeKind, stateKey, { scopeId, namespace = DEFAULT_NAMESPACE, } = {}) => {
+            const rows = await db
+                .select()
+                .from(pluginState)
+                .where(scopeConditions(pluginId, scopeKind, scopeId, namespace, stateKey));
+            return rows[0]?.valueJson ?? null;
+        },
+        /**
+         * Write (create or replace) a state value.
+         *
+         * Uses an upsert so the caller does not need to check for prior existence.
+         * On conflict (same composite key) the existing row's `value_json` and
+         * `updated_at` are overwritten.
+         *
+         * Requires `plugin.state.write` capability (enforced by the caller).
+         *
+         * @param pluginId - UUID of the owning plugin
+         * @param input - Scope key and value to store
+         */
+        set: async (pluginId, input) => {
+            await assertPluginExists(pluginId);
+            const namespace = input.namespace ?? DEFAULT_NAMESPACE;
+            const scopeId = input.scopeId ?? null;
+            await db
+                .insert(pluginState)
+                .values({
+                pluginId,
+                scopeKind: input.scopeKind,
+                scopeId,
+                namespace,
+                stateKey: input.stateKey,
+                valueJson: input.value,
+                updatedAt: new Date(),
+            })
+                .onConflictDoUpdate({
+                target: [
+                    pluginState.pluginId,
+                    pluginState.scopeKind,
+                    pluginState.scopeId,
+                    pluginState.namespace,
+                    pluginState.stateKey,
+                ],
+                set: {
+                    valueJson: input.value,
+                    updatedAt: new Date(),
+                },
+            });
+        },
+        /**
+         * Delete a state value.
+         *
+         * No-ops silently if the entry does not exist (idempotent by design).
+         *
+         * Requires `plugin.state.write` capability (enforced by the caller).
+         *
+         * @param pluginId - UUID of the owning plugin
+         * @param scopeKind - Granularity of the scope
+         * @param stateKey - The key to delete
+         * @param scopeId - Identifier for the scoped entity (null for `instance` scope)
+         * @param namespace - Sub-namespace (defaults to `"default"`)
+         */
+        delete: async (pluginId, scopeKind, stateKey, { scopeId, namespace = DEFAULT_NAMESPACE, } = {}) => {
+            await db
+                .delete(pluginState)
+                .where(scopeConditions(pluginId, scopeKind, scopeId, namespace, stateKey));
+        },
+        /**
+         * List all state entries for a plugin, optionally filtered by scope.
+         *
+         * Returns all matching rows as `PluginStateRecord`-shaped objects.
+         * The `valueJson` field contains the stored value.
+         *
+         * Requires `plugin.state.read` capability (enforced by the caller).
+         *
+         * @param pluginId - UUID of the owning plugin
+         * @param filter - Optional scope filters (scopeKind, scopeId, namespace)
+         */
+        list: async (pluginId, filter = {}) => {
+            const conditions = [eq(pluginState.pluginId, pluginId)];
+            if (filter.scopeKind !== undefined) {
+                conditions.push(eq(pluginState.scopeKind, filter.scopeKind));
+            }
+            if (filter.scopeId !== undefined) {
+                conditions.push(eq(pluginState.scopeId, filter.scopeId));
+            }
+            if (filter.namespace !== undefined) {
+                conditions.push(eq(pluginState.namespace, filter.namespace));
+            }
+            return db
+                .select()
+                .from(pluginState)
+                .where(and(...conditions));
+        },
+        /**
+         * Delete all state entries owned by a plugin.
+         *
+         * Called during plugin uninstall when `removeData = true`. Also useful
+         * for resetting a plugin's state during testing.
+         *
+         * @param pluginId - UUID of the owning plugin
+         */
+        deleteAll: async (pluginId) => {
+            await db
+                .delete(pluginState)
+                .where(eq(pluginState.pluginId, pluginId));
+        },
+    };
+}
+//# sourceMappingURL=plugin-state-store.js.map

package/dist/services/plugin-state-store.js.map

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

package/dist/services/plugin-stream-bus.d.ts

@@ -0,0 +1,29 @@
+/**
+ * In-memory pub/sub bus for plugin SSE streams.
+ *
+ * Workers emit stream events via JSON-RPC notifications. The bus fans out
+ * each event to all connected SSE clients that match the (pluginId, channel,
+ * companyId) tuple.
+ *
+ * @see PLUGIN_SPEC.md §19.8 — Real-Time Streaming
+ */
+/** Valid SSE event types for plugin streams. */
+export type StreamEventType = "message" | "open" | "close" | "error";
+export type StreamSubscriber = (event: unknown, eventType: StreamEventType) => void;
+export interface PluginStreamBus {
+    /**
+     * Subscribe to stream events for a specific (pluginId, channel, companyId).
+     * Returns an unsubscribe function.
+     */
+    subscribe(pluginId: string, channel: string, companyId: string, listener: StreamSubscriber): () => void;
+    /**
+     * Publish an event to all subscribers of (pluginId, channel, companyId).
+     * Called by the worker manager when it receives a stream notification.
+     */
+    publish(pluginId: string, channel: string, companyId: string, event: unknown, eventType?: StreamEventType): void;
+}
+/**
+ * Create a new PluginStreamBus instance.
+ */
+export declare function createPluginStreamBus(): PluginStreamBus;
+//# sourceMappingURL=plugin-stream-bus.d.ts.map

package/dist/services/plugin-stream-bus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-stream-bus.d.ts","sourceRoot":"","sources":["../../src/services/plugin-stream-bus.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,gDAAgD;AAChD,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;AAErE,MAAM,MAAM,gBAAgB,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,eAAe,KAAK,IAAI,CAAC;AASpF,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,SAAS,CACP,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,gBAAgB,GACzB,MAAM,IAAI,CAAC;IAEd;;;OAGG;IACH,OAAO,CACL,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,OAAO,EACd,SAAS,CAAC,EAAE,eAAe,GAC1B,IAAI,CAAC;CACT;AAED;;GAEG;AACH,wBAAgB,qBAAqB,IAAI,eAAe,CA8BvD"}

package/dist/services/plugin-stream-bus.js

@@ -0,0 +1,48 @@
+/**
+ * In-memory pub/sub bus for plugin SSE streams.
+ *
+ * Workers emit stream events via JSON-RPC notifications. The bus fans out
+ * each event to all connected SSE clients that match the (pluginId, channel,
+ * companyId) tuple.
+ *
+ * @see PLUGIN_SPEC.md §19.8 — Real-Time Streaming
+ */
+/**
+ * Composite key for stream subscriptions: pluginId:channel:companyId
+ */
+function streamKey(pluginId, channel, companyId) {
+    return `${pluginId}:${channel}:${companyId}`;
+}
+/**
+ * Create a new PluginStreamBus instance.
+ */
+export function createPluginStreamBus() {
+    const subscribers = new Map();
+    return {
+        subscribe(pluginId, channel, companyId, listener) {
+            const key = streamKey(pluginId, channel, companyId);
+            let set = subscribers.get(key);
+            if (!set) {
+                set = new Set();
+                subscribers.set(key, set);
+            }
+            set.add(listener);
+            return () => {
+                set.delete(listener);
+                if (set.size === 0) {
+                    subscribers.delete(key);
+                }
+            };
+        },
+        publish(pluginId, channel, companyId, event, eventType = "message") {
+            const key = streamKey(pluginId, channel, companyId);
+            const set = subscribers.get(key);
+            if (!set)
+                return;
+            for (const listener of set) {
+                listener(event, eventType);
+            }
+        },
+    };
+}
+//# sourceMappingURL=plugin-stream-bus.js.map

package/dist/services/plugin-stream-bus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-stream-bus.js","sourceRoot":"","sources":["../../src/services/plugin-stream-bus.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAOH;;GAEG;AACH,SAAS,SAAS,CAAC,QAAgB,EAAE,OAAe,EAAE,SAAiB;IACrE,OAAO,GAAG,QAAQ,IAAI,OAAO,IAAI,SAAS,EAAE,CAAC;AAC/C,CAAC;AA2BD;;GAEG;AACH,MAAM,UAAU,qBAAqB;IACnC,MAAM,WAAW,GAAG,IAAI,GAAG,EAAiC,CAAC;IAE7D,OAAO;QACL,SAAS,CAAC,QAAQ,EAAE,OAAO,EAAE,SAAS,EAAE,QAAQ;YAC9C,MAAM,GAAG,GAAG,SAAS,CAAC,QAAQ,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC;YACpD,IAAI,GAAG,GAAG,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAC/B,IAAI,CAAC,GAAG,EAAE,CAAC;gBACT,GAAG,GAAG,IAAI,GAAG,EAAE,CAAC;gBAChB,WAAW,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;YAC5B,CAAC;YACD,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;YAElB,OAAO,GAAG,EAAE;gBACV,GAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;gBACtB,IAAI,GAAI,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;oBACpB,WAAW,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;gBAC1B,CAAC;YACH,CAAC,CAAC;QACJ,CAAC;QAED,OAAO,CAAC,QAAQ,EAAE,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,YAA6B,SAAS;YACjF,MAAM,GAAG,GAAG,SAAS,CAAC,QAAQ,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC;YACpD,MAAM,GAAG,GAAG,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACjC,IAAI,CAAC,GAAG;gBAAE,OAAO;YACjB,KAAK,MAAM,QAAQ,IAAI,GAAG,EAAE,CAAC;gBAC3B,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;YAC7B,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/services/plugin-tool-dispatcher.d.ts

@@ -0,0 +1,180 @@
+/**
+ * PluginToolDispatcher — orchestrates plugin tool discovery, lifecycle
+ * integration, and execution routing for the agent service.
+ *
+ * This service sits between the agent service and the lower-level
+ * `PluginToolRegistry` + `PluginWorkerManager`, providing a clean API that:
+ *
+ * - Discovers tools from loaded plugin manifests and registers them
+ *   in the tool registry.
+ * - Hooks into `PluginLifecycleManager` events to automatically register
+ *   and unregister tools when plugins are enabled or disabled.
+ * - Exposes the tool list in an agent-friendly format (with namespaced
+ *   names, descriptions, parameter schemas).
+ * - Routes `executeTool` calls to the correct plugin worker and returns
+ *   structured results.
+ * - Validates tool parameters against declared schemas before dispatch.
+ *
+ * The dispatcher is created once at server startup and shared across
+ * the application.
+ *
+ * @see PLUGIN_SPEC.md §11 — Agent Tools
+ * @see PLUGIN_SPEC.md §13.10 — `executeTool`
+ */
+import type { Db } from "@fideliosai/db";
+import type { FideliOSPluginManifestV1 } from "@fideliosai/shared";
+import type { ToolRunContext } from "@fideliosai/plugin-sdk";
+import type { PluginWorkerManager } from "./plugin-worker-manager.js";
+import type { PluginLifecycleManager } from "./plugin-lifecycle.js";
+import { type PluginToolRegistry, type RegisteredTool, type ToolListFilter, type ToolExecutionResult } from "./plugin-tool-registry.js";
+/**
+ * An agent-facing tool descriptor — the shape returned when agents
+ * query for available tools.
+ *
+ * This is intentionally simpler than `RegisteredTool`, exposing only
+ * what agents need to decide whether and how to call a tool.
+ */
+export interface AgentToolDescriptor {
+    /** Fully namespaced tool name (e.g. `"acme.linear:search-issues"`). */
+    name: string;
+    /** Human-readable display name. */
+    displayName: string;
+    /** Description for the agent — explains when and how to use this tool. */
+    description: string;
+    /** JSON Schema describing the tool's input parameters. */
+    parametersSchema: Record<string, unknown>;
+    /** The plugin that provides this tool. */
+    pluginId: string;
+}
+/**
+ * Options for creating the plugin tool dispatcher.
+ */
+export interface PluginToolDispatcherOptions {
+    /** The worker manager used to dispatch RPC calls to plugin workers. */
+    workerManager?: PluginWorkerManager;
+    /** The lifecycle manager to listen for plugin state changes. */
+    lifecycleManager?: PluginLifecycleManager;
+    /** Database connection for looking up plugin records. */
+    db?: Db;
+}
+/**
+ * The plugin tool dispatcher — the primary integration point between the
+ * agent service and the plugin tool system.
+ *
+ * Agents use this service to:
+ * 1. List all available tools (for prompt construction / tool choice)
+ * 2. Execute a specific tool by its namespaced name
+ *
+ * The dispatcher handles lifecycle management internally — when a plugin
+ * is loaded or unloaded, its tools are automatically registered or removed.
+ */
+export interface PluginToolDispatcher {
+    /**
+     * Initialize the dispatcher — load tools from all currently-ready plugins
+     * and start listening for lifecycle events.
+     *
+     * Must be called once at server startup after the lifecycle manager
+     * and worker manager are ready.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Tear down the dispatcher — unregister lifecycle event listeners
+     * and clear all tool registrations.
+     *
+     * Called during server shutdown.
+     */
+    teardown(): void;
+    /**
+     * List all available tools for agents, optionally filtered.
+     *
+     * Returns tool descriptors in an agent-friendly format.
+     *
+     * @param filter - Optional filter criteria
+     * @returns Array of agent tool descriptors
+     */
+    listToolsForAgent(filter?: ToolListFilter): AgentToolDescriptor[];
+    /**
+     * Look up a tool by its namespaced name.
+     *
+     * @param namespacedName - e.g. `"acme.linear:search-issues"`
+     * @returns The registered tool, or `null` if not found
+     */
+    getTool(namespacedName: string): RegisteredTool | null;
+    /**
+     * Execute a tool by its namespaced name, routing to the correct
+     * plugin worker.
+     *
+     * @param namespacedName - Fully qualified tool name
+     * @param parameters - Input parameters matching the tool's schema
+     * @param runContext - Agent run context
+     * @returns The execution result with routing metadata
+     * @throws {Error} if the tool is not found, the worker is not running,
+     *   or the tool execution fails
+     */
+    executeTool(namespacedName: string, parameters: unknown, runContext: ToolRunContext): Promise<ToolExecutionResult>;
+    /**
+     * Register all tools from a plugin manifest.
+     *
+     * This is called automatically when a plugin transitions to `ready`.
+     * Can also be called manually for testing or recovery scenarios.
+     *
+     * @param pluginId - The plugin's unique identifier
+     * @param manifest - The plugin manifest containing tool declarations
+     */
+    registerPluginTools(pluginId: string, manifest: FideliOSPluginManifestV1): void;
+    /**
+     * Unregister all tools for a plugin.
+     *
+     * Called automatically when a plugin is disabled or unloaded.
+     *
+     * @param pluginId - The plugin to unregister
+     */
+    unregisterPluginTools(pluginId: string): void;
+    /**
+     * Get the total number of registered tools, optionally scoped to a plugin.
+     *
+     * @param pluginId - If provided, count only this plugin's tools
+     */
+    toolCount(pluginId?: string): number;
+    /**
+     * Access the underlying tool registry for advanced operations.
+     *
+     * This escape hatch exists for internal use (e.g. diagnostics).
+     * Prefer the dispatcher's own methods for normal operations.
+     */
+    getRegistry(): PluginToolRegistry;
+}
+/**
+ * Create a new `PluginToolDispatcher`.
+ *
+ * The dispatcher:
+ * 1. Creates and owns a `PluginToolRegistry` backed by the given worker manager.
+ * 2. Listens for lifecycle events (plugin.enabled, plugin.disabled, plugin.unloaded)
+ *    to automatically register and unregister tools.
+ * 3. On `initialize()`, loads tools from all currently-ready plugins via the DB.
+ *
+ * @param options - Configuration options
+ *
+ * @example
+ * ```ts
+ * // At server startup
+ * const dispatcher = createPluginToolDispatcher({
+ *   workerManager,
+ *   lifecycleManager,
+ *   db,
+ * });
+ * await dispatcher.initialize();
+ *
+ * // In agent service — list tools for prompt construction
+ * const tools = dispatcher.listToolsForAgent();
+ *
+ * // In agent service — execute a tool
+ * const result = await dispatcher.executeTool(
+ *   "acme.linear:search-issues",
+ *   { query: "auth bug" },
+ *   { agentId: "a-1", runId: "r-1", companyId: "c-1", projectId: "p-1" },
+ * );
+ * ```
+ */
+export declare function createPluginToolDispatcher(options?: PluginToolDispatcherOptions): PluginToolDispatcher;
+//# sourceMappingURL=plugin-tool-dispatcher.d.ts.map

package/dist/services/plugin-tool-dispatcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-tool-dispatcher.d.ts","sourceRoot":"","sources":["../../src/services/plugin-tool-dispatcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,gBAAgB,CAAC;AACzC,OAAO,KAAK,EACV,wBAAwB,EAEzB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,cAAc,EAAc,MAAM,wBAAwB,CAAC;AACzE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACtE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AACpE,OAAO,EAEL,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,mBAAmB,EACzB,MAAM,2BAA2B,CAAC;AAQnC;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,uEAAuE;IACvE,IAAI,EAAE,MAAM,CAAC;IACb,mCAAmC;IACnC,WAAW,EAAE,MAAM,CAAC;IACpB,0EAA0E;IAC1E,WAAW,EAAE,MAAM,CAAC;IACpB,0DAA0D;IAC1D,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC1C,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C,uEAAuE;IACvE,aAAa,CAAC,EAAE,mBAAmB,CAAC;IACpC,gEAAgE;IAChE,gBAAgB,CAAC,EAAE,sBAAsB,CAAC;IAC1C,yDAAyD;IACzD,EAAE,CAAC,EAAE,EAAE,CAAC;CACT;AAMD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;;;OAMG;IACH,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAE5B;;;;;OAKG;IACH,QAAQ,IAAI,IAAI,CAAC;IAEjB;;;;;;;OAOG;IACH,iBAAiB,CAAC,MAAM,CAAC,EAAE,cAAc,GAAG,mBAAmB,EAAE,CAAC;IAElE;;;;;OAKG;IACH,OAAO,CAAC,cAAc,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAAC;IAEvD;;;;;;;;;;OAUG;IACH,WAAW,CACT,cAAc,EAAE,MAAM,EACtB,UAAU,EAAE,OAAO,EACnB,UAAU,EAAE,cAAc,GACzB,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAEhC;;;;;;;;OAQG;IACH,mBAAmB,CACjB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,wBAAwB,GACjC,IAAI,CAAC;IAER;;;;;;OAMG;IACH,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IAE9C;;;;OAIG;IACH,SAAS,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAErC;;;;;OAKG;IACH,WAAW,IAAI,kBAAkB,CAAC;CACnC;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,GAAE,2BAAgC,GACxC,oBAAoB,CAgOtB"}