@vibearound/plugin-channel-sdk 0.1.2 → 0.4.0

package/dist/plugin.d.ts

@@ -0,0 +1,80 @@
+/**
+ * runChannelPlugin — the SDK entry point for every channel plugin.
+ *
+ * Handles the full ACP lifecycle: connect to host, validate config, create
+ * bot + renderer, start the bot, then await disconnect and stop. The plugin
+ * only implements platform-specific transport (sendText, sendBlock, editBlock).
+ *
+ * ## Usage
+ *
+ * ```ts
+ * import { runChannelPlugin } from "@vibearound/plugin-channel-sdk";
+ *
+ * runChannelPlugin({
+ *   name: "vibearound-slack",
+ *   version: "0.1.0",
+ *   requiredConfig: ["bot_token", "app_token"],
+ *   createBot: ({ config, agent, log, cacheDir }) =>
+ *     new SlackBot({ ... }, agent, log, cacheDir),
+ *   createRenderer: (bot, log, verbose) =>
+ *     new SlackRenderer(bot, log, verbose),
+ * });
+ * ```
+ */
+import type { Agent } from "@agentclientprotocol/sdk";
+import { BlockRenderer } from "./renderer.js";
+export type ChannelPluginLogger = (level: string, msg: string) => void;
+/**
+ * The platform bot — handles IM connectivity and message transport.
+ *
+ * Plugins implement this interface on their bot class. The SDK calls these
+ * methods during the plugin lifecycle.
+ */
+export interface ChannelBot<TRenderer extends BlockRenderer<any> = BlockRenderer<any>> {
+    /** Wire the renderer to receive streaming events. */
+    setStreamHandler(handler: TRenderer): void;
+    /** Connect to the IM platform and start receiving messages. */
+    start(): Promise<void> | void;
+    /** Disconnect and clean up. */
+    stop(): Promise<void> | void;
+}
+export interface CreateBotContext {
+    config: Record<string, unknown>;
+    agent: Agent;
+    log: ChannelPluginLogger;
+    cacheDir: string;
+}
+export interface VerboseOptions {
+    showThinking: boolean;
+    showToolUse: boolean;
+}
+export interface RunChannelPluginSpec<TBot extends ChannelBot<TRenderer>, TRenderer extends BlockRenderer<any>> {
+    /** Plugin name reported during ACP initialize (e.g. "vibearound-slack"). */
+    name: string;
+    /** Plugin version reported during ACP initialize. */
+    version: string;
+    /**
+     * Config keys that MUST be present. Plugin fails fast if any are missing.
+     */
+    requiredConfig?: string[];
+    /** Factory: build the platform bot. */
+    createBot: (ctx: CreateBotContext) => TBot | Promise<TBot>;
+    /**
+     * Factory: build the renderer (extends BlockRenderer).
+     * Only implements platform-specific sendText/sendBlock/editBlock.
+     */
+    createRenderer: (bot: TBot, log: ChannelPluginLogger, verbose: VerboseOptions) => TRenderer;
+    /**
+     * Optional hook invoked after bot constructed but before start().
+     */
+    afterCreate?: (bot: TBot, log: ChannelPluginLogger) => Promise<void> | void;
+}
+/**
+ * Run a channel plugin.
+ *
+ * Handles the full ACP lifecycle: connect to host, validate config,
+ * construct bot + renderer, start the bot, then wait for the host
+ * to disconnect before stopping and exiting.
+ */
+export declare function runChannelPlugin<TBot extends ChannelBot<TRenderer>, TRenderer extends BlockRenderer<any>>(spec: RunChannelPluginSpec<TBot, TRenderer>): Promise<void>;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAIH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,0BAA0B,CAAC;AAItD,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAW9C,MAAM,MAAM,mBAAmB,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;AAEvE;;;;;GAKG;AAEH,MAAM,WAAW,UAAU,CAAC,SAAS,SAAS,aAAa,CAAC,GAAG,CAAC,GAAG,aAAa,CAAC,GAAG,CAAC;IACnF,qDAAqD;IACrD,gBAAgB,CAAC,OAAO,EAAE,SAAS,GAAG,IAAI,CAAC;IAC3C,+DAA+D;IAC/D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC9B,+BAA+B;IAC/B,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CAC9B;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,KAAK,EAAE,KAAK,CAAC;IACb,GAAG,EAAE,mBAAmB,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,YAAY,EAAE,OAAO,CAAC;IACtB,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,oBAAoB,CACnC,IAAI,SAAS,UAAU,CAAC,SAAS,CAAC,EAClC,SAAS,SAAS,aAAa,CAAC,GAAG,CAAC;IAEpC,4EAA4E;IAC5E,IAAI,EAAE,MAAM,CAAC;IAEb,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAE1B,uCAAuC;IACvC,SAAS,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE3D;;;OAGG;IACH,cAAc,EAAE,CACd,GAAG,EAAE,IAAI,EACT,GAAG,EAAE,mBAAmB,EACxB,OAAO,EAAE,cAAc,KACpB,SAAS,CAAC;IAEf;;OAEG;IACH,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,mBAAmB,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CAC7E;AAMD;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,SAAS,UAAU,CAAC,SAAS,CAAC,EAClC,SAAS,SAAS,aAAa,CAAC,GAAG,CAAC,EACpC,IAAI,EAAE,oBAAoB,CAAC,IAAI,EAAE,SAAS,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAY5D"}

package/dist/plugin.js

@@ -0,0 +1,131 @@
+/**
+ * runChannelPlugin — the SDK entry point for every channel plugin.
+ *
+ * Handles the full ACP lifecycle: connect to host, validate config, create
+ * bot + renderer, start the bot, then await disconnect and stop. The plugin
+ * only implements platform-specific transport (sendText, sendBlock, editBlock).
+ *
+ * ## Usage
+ *
+ * ```ts
+ * import { runChannelPlugin } from "@vibearound/plugin-channel-sdk";
+ *
+ * runChannelPlugin({
+ *   name: "vibearound-slack",
+ *   version: "0.1.0",
+ *   requiredConfig: ["bot_token", "app_token"],
+ *   createBot: ({ config, agent, log, cacheDir }) =>
+ *     new SlackBot({ ... }, agent, log, cacheDir),
+ *   createRenderer: (bot, log, verbose) =>
+ *     new SlackRenderer(bot, log, verbose),
+ * });
+ * ```
+ */
+import os from "node:os";
+import path from "node:path";
+import { connectToHost, stripExtPrefix } from "./connection.js";
+import { extractErrorMessage } from "./errors.js";
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+/**
+ * Run a channel plugin.
+ *
+ * Handles the full ACP lifecycle: connect to host, validate config,
+ * construct bot + renderer, start the bot, then wait for the host
+ * to disconnect before stopping and exiting.
+ */
+export async function runChannelPlugin(spec) {
+    const prefix = `[${spec.name.replace(/^vibearound-/, "")}-plugin]`;
+    const log = (level, msg) => {
+        process.stderr.write(`${prefix}[${level}] ${msg}\n`);
+    };
+    try {
+        await runInner(spec, log);
+    }
+    catch (err) {
+        log("error", `fatal: ${extractErrorMessage(err)}`);
+        process.exit(1);
+    }
+}
+async function runInner(spec, log) {
+    log("info", "initializing ACP connection...");
+    let renderer = null;
+    const { agent, meta, agentInfo, conn } = await connectToHost({ name: spec.name, version: spec.version }, () => ({
+        async sessionUpdate(params) {
+            renderer?.onSessionUpdate(params);
+        },
+        async requestPermission(params) {
+            const first = params.options?.[0];
+            if (first) {
+                return { outcome: { outcome: "selected", optionId: first.optionId } };
+            }
+            throw new Error("No permission options provided");
+        },
+        async extNotification(method, params) {
+            const chatId = typeof params.chatId === "string" ? params.chatId : undefined;
+            switch (stripExtPrefix(method)) {
+                case "va/system_text": {
+                    const text = typeof params.text === "string" ? params.text : "";
+                    if (chatId && renderer) {
+                        renderer.onSystemText(chatId, text);
+                    }
+                    break;
+                }
+                case "va/agent_ready": {
+                    const agentName = typeof params.agent === "string" ? params.agent : "unknown";
+                    const version = typeof params.version === "string" ? params.version : "";
+                    log("info", `agent_ready: ${agentName} v${version}`);
+                    if (chatId && renderer) {
+                        renderer.onAgentReady(chatId, agentName, version);
+                    }
+                    break;
+                }
+                case "va/session_ready": {
+                    const sessionId = typeof params.sessionId === "string" ? params.sessionId : "";
+                    log("info", `session_ready: ${sessionId}`);
+                    if (chatId && renderer) {
+                        renderer.onSessionReady(chatId, sessionId);
+                    }
+                    break;
+                }
+                case "va/command_menu": {
+                    const systemCommands = Array.isArray(params.systemCommands) ? params.systemCommands : [];
+                    const agentCommands = Array.isArray(params.agentCommands) ? params.agentCommands : [];
+                    if (chatId && renderer) {
+                        renderer.onCommandMenu(chatId, systemCommands, agentCommands);
+                    }
+                    break;
+                }
+                default:
+                    log("warn", `unhandled ext_notification: ${method}`);
+            }
+        },
+    }));
+    const config = meta.config;
+    for (const key of spec.requiredConfig ?? []) {
+        if (config[key] === undefined || config[key] === null || config[key] === "") {
+            throw new Error(`${key} is required in config`);
+        }
+    }
+    const cacheDir = meta.cacheDir ?? path.join(os.homedir(), ".vibearound", ".cache");
+    log("info", `initialized, host=${agentInfo.name ?? "unknown"} cacheDir=${cacheDir}`);
+    const bot = await spec.createBot({ config, agent, log, cacheDir });
+    if (spec.afterCreate) {
+        await spec.afterCreate(bot, log);
+    }
+    const verboseRaw = config.verbose;
+    const verbose = {
+        showThinking: verboseRaw?.show_thinking ?? false,
+        showToolUse: verboseRaw?.show_tool_use ?? false,
+    };
+    renderer = spec.createRenderer(bot, log, verbose);
+    bot.setStreamHandler(renderer);
+    await bot.start();
+    log("info", "plugin started");
+    await conn.closed;
+    log("info", "connection closed, shutting down");
+    await bot.stop();
+    process.exit(0);
+}
+//# sourceMappingURL=plugin.js.map

package/dist/plugin.js.map

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

package/dist/renderer.d.ts

@@ -25,35 +25,29 @@
  *
  * ## Usage
  *
+ * Subclass and implement `sendText` + `sendBlock` (+ optionally `editBlock`):
+ *
  * ```ts
  * class MyRenderer extends BlockRenderer<string> {
- *   protected async sendBlock(channelId, kind, content) {
- *     const msg = await myApi.sendMessage(channelId, content);
+ *   protected async sendText(chatId, text) {
+ *     await myApi.sendMessage(chatId, text);
+ *   }
+ *   protected async sendBlock(chatId, kind, content) {
+ *     const msg = await myApi.sendMessage(chatId, content);
  *     return msg.id;
  *   }
- *   protected async editBlock(channelId, ref, kind, content, sealed) {
+ *   protected async editBlock(chatId, ref, kind, content, sealed) {
  *     await myApi.editMessage(ref, content);
  *   }
  * }
- *
- * // In main.ts:
- * const renderer = new MyRenderer({ verbose: { showThinking: false } });
- *
- * // When user sends a message:
- * renderer.onPromptSent(channelId);
- * try {
- *   await agent.prompt({ sessionId, content });
- *   await renderer.onTurnEnd(channelId);
- * } catch (e) {
- *   await renderer.onTurnError(channelId, String(e));
- * }
- *
- * // In the ACP client's sessionUpdate handler:
- * renderer.onSessionUpdate(notification);
  * ```
+ *
+ * The SDK's `runChannelPlugin` wires all ACP events to this renderer
+ * automatically — plugins don't call onSessionUpdate/onPromptSent/etc
+ * directly.
  */
 import type { SessionNotification } from "@agentclientprotocol/sdk";
-import type { BlockKind, BlockRendererOptions, VerboseConfig } from "./types.js";
+import type { BlockKind, BlockRendererOptions, CommandEntry, VerboseConfig } from "./types.js";
 /**
  * Abstract base class for block-based rendering of ACP session streams.
  *
@@ -62,18 +56,29 @@ import type { BlockKind, BlockRendererOptions, VerboseConfig } from "./types.js"
  *   return type of `sendBlock` and the first argument of `editBlock`.
  */
 export declare abstract class BlockRenderer<TRef = string> {
+    /** When true, blocks are sent and edited in real-time. When false, each
+     *  block is held until complete, then sent once (send-only mode). */
+    protected readonly streaming: boolean;
     protected readonly flushIntervalMs: number;
     protected readonly minEditIntervalMs: number;
     protected readonly verbose: VerboseConfig;
     private states;
+    /** The chatId of the most recent prompt. Used as fallback target for
+     *  notifications that arrive without an explicit chatId. */
+    private lastActiveChatId;
     constructor(options?: BlockRendererOptions);
     /**
-     * Send a new block message to the platform.
+     * Send a plain text message to the IM. Used for system text, agent ready
+     * notifications, session ready, and error messages.
+     */
+    protected abstract sendText(chatId: string, text: string): Promise<void>;
+    /**
+     * Send a new streaming block message to the platform.
      *
      * Return the platform message reference that will be passed to future
      * `editBlock` calls. Return `null` if editing is not supported.
      */
-    protected abstract sendBlock(channelId: string, kind: BlockKind, content: string): Promise<TRef | null>;
+    protected abstract sendBlock(chatId: string, kind: BlockKind, content: string): Promise<TRef | null>;
     /**
      * Edit an existing block message in-place.
      *
@@ -83,7 +88,7 @@ export declare abstract class BlockRenderer<TRef = string> {
      * @param sealed - `true` when this is the final edit (block done streaming).
      *   Use to switch from a "streaming" card format to a finalized one.
      */
-    protected editBlock?(channelId: string, ref: TRef, kind: BlockKind, content: string, sealed: boolean): Promise<void>;
+    protected editBlock?(chatId: string, ref: TRef, kind: BlockKind, content: string, sealed: boolean): Promise<void>;
     /**
      * Format block content before sending or editing.
      *
@@ -97,54 +102,55 @@ export declare abstract class BlockRenderer<TRef = string> {
     protected formatContent(kind: BlockKind, content: string, _sealed: boolean): string;
     /**
      * Called after the last block has been flushed and the turn is complete.
-     * Override to perform cleanup (e.g. remove a "typing" indicator, a
-     * processing reaction, etc.).
+     * Override to perform cleanup (e.g. remove a "typing" indicator).
      */
-    protected onAfterTurnEnd(_channelId: string): Promise<void>;
+    protected onAfterTurnEnd(_chatId: string): Promise<void>;
     /**
-     * Called after a turn error, once state has been cleaned up.
-     * Override to send an error message to the user.
+     * Called after a turn error. Default sends an error message via sendText.
+     * Override for platform-specific error rendering (e.g. error card).
      */
-    protected onAfterTurnError(_channelId: string, _error: string): Promise<void>;
-    /**
-     * Map an ACP `sessionId` to the channel ID used internally.
-     *
-     * Default: identity (sessionId === channelId).
-     *
-     * Override if your plugin namespaces channel IDs (e.g. Feishu uses
-     * `"feishu:<sessionId>"`, WeChat uses `"weixin-openclaw-bridge:<sessionId>"`).
-     */
-    protected sessionIdToChannelId(sessionId: string): string;
+    protected onAfterTurnError(chatId: string, error: string): Promise<void>;
     /**
      * Process an ACP `sessionUpdate` notification from the host.
      *
      * Routes the event to the correct block based on its variant, appending
      * deltas to the current block or starting a new one when the kind changes.
      *
-     * Call this from the ACP `Client.sessionUpdate` handler.
+     * Called automatically by `runChannelPlugin` — plugins don't call this directly.
      */
     onSessionUpdate(notification: SessionNotification): void;
     /**
-     * Call this before sending a prompt to the agent.
+     * Call before sending a prompt. Tracks the active chatId and clears
+     * leftover state from a previous turn.
+     */
+    onPromptSent(chatId: string): void;
+    /** Handle `va/system_text` from host. */
+    onSystemText(chatId: string, text: string): void;
+    /** Handle `va/agent_ready` from host. */
+    onAgentReady(chatId: string, agent: string, version: string): void;
+    /** Handle `va/session_ready` from host. */
+    onSessionReady(chatId: string, sessionId: string): void;
+    /**
+     * Handle `va/command_menu` from host — display available commands.
      *
-     * Clears any leftover state from a previous turn so the new turn starts
-     * with a clean slate.
+     * Default renders a plain-text list. Override for platform-specific
+     * rendering (e.g. Feishu interactive card, Slack Block Kit, Telegram
+     * inline keyboard).
      */
-    onPromptSent(channelId: string): void;
+    onCommandMenu(chatId: string, systemCommands: CommandEntry[], agentCommands: CommandEntry[]): void;
     /**
      * Call this after `agent.prompt()` resolves (turn complete).
      *
      * Seals and flushes the last block, then waits for all pending sends/edits
      * to complete before calling `onAfterTurnEnd`.
      */
-    onTurnEnd(channelId: string): Promise<void>;
+    onTurnEnd(chatId: string): Promise<void>;
     /**
      * Call this when `agent.prompt()` throws (turn error).
      *
-     * Discards pending state and calls `onAfterTurnError` so the subclass can
-     * send an error message to the user.
+     * Discards pending state and calls `onAfterTurnError`.
      */
-    onTurnError(channelId: string, error: string): Promise<void>;
+    onTurnError(chatId: string, error: string): Promise<void>;
     private appendToBlock;
     private scheduleFlush;
     private flush;

package/dist/renderer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"renderer.d.ts","sourceRoot":"","sources":["../src/renderer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AACpE,OAAO,KAAK,EAAE,SAAS,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAuCjF;;;;;;GAMG;AACH,8BAAsB,aAAa,CAAC,IAAI,GAAG,MAAM;IAC/C,SAAS,CAAC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IAC3C,SAAS,CAAC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IAC7C,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAE1C,OAAO,CAAC,MAAM,CAAyC;gBAE3C,OAAO,GAAE,oBAAyB;IAa9C;;;;;OAKG;IACH,SAAS,CAAC,QAAQ,CAAC,SAAS,CAC1B,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,SAAS,EACf,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC;IAEvB;;;;;;;;OAQG;IACH,SAAS,CAAC,SAAS,CAAC,CAClB,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,IAAI,EACT,IAAI,EAAE,SAAS,EACf,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,OAAO,GACd,OAAO,CAAC,IAAI,CAAC;IAEhB;;;;;;;;;OASG;IACH,SAAS,CAAC,aAAa,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,MAAM;IAQnF;;;;OAIG;IACH,SAAS,CAAC,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI3D;;;OAGG;IACH,SAAS,CAAC,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI7E;;;;;;;OAOG;IACH,SAAS,CAAC,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM;IAQzD;;;;;;;OAOG;IACH,eAAe,CAAC,YAAY,EAAE,mBAAmB,GAAG,IAAI;IAqCxD;;;;;OAKG;IACH,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAWrC;;;;;OAKG;IACG,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAqBjD;;;;;OAKG;IACG,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAWlE,OAAO,CAAC,aAAa;IA8BrB,OAAO,CAAC,aAAa;IASrB,OAAO,CAAC,KAAK;IAoBb,OAAO,CAAC,YAAY;YAMN,UAAU;CAqBzB"}
+{"version":3,"file":"renderer.d.ts","sourceRoot":"","sources":["../src/renderer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AACpE,OAAO,KAAK,EAAE,SAAS,EAAE,oBAAoB,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AA6E/F;;;;;;GAMG;AACH,8BAAsB,aAAa,CAAC,IAAI,GAAG,MAAM;IAC/C;yEACqE;IACrE,SAAS,CAAC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IACtC,SAAS,CAAC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IAC3C,SAAS,CAAC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IAC7C,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAE1C,OAAO,CAAC,MAAM,CAAyC;IAEvD;gEAC4D;IAC5D,OAAO,CAAC,gBAAgB,CAAuB;gBAEnC,OAAO,GAAE,oBAAyB;IAc9C;;;OAGG;IACH,SAAS,CAAC,QAAQ,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAExE;;;;;OAKG;IACH,SAAS,CAAC,QAAQ,CAAC,SAAS,CAC1B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,SAAS,EACf,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC;IAMvB;;;;;;;;OAQG;IACH,SAAS,CAAC,SAAS,CAAC,CAClB,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,IAAI,EACT,IAAI,EAAE,SAAS,EACf,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,OAAO,GACd,OAAO,CAAC,IAAI,CAAC;IAEhB;;;;;;;;;OASG;IACH,SAAS,CAAC,aAAa,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,MAAM;IAQnF;;;OAGG;IACH,SAAS,CAAC,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIxD;;;OAGG;cACa,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ9E;;;;;;;OAOG;IACH,eAAe,CAAC,YAAY,EAAE,mBAAmB,GAAG,IAAI;IA4CxD;;;OAGG;IACH,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAgBlC,yCAAyC;IACzC,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAIhD,yCAAyC;IACzC,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAIlE,2CAA2C;IAC3C,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;IAIvD;;;;;;OAMG;IACH,aAAa,CACX,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,YAAY,EAAE,EAC9B,aAAa,EAAE,YAAY,EAAE,GAC5B,IAAI;IA0BP;;;;;OAKG;IACG,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAoB9C;;;;OAIG;IACG,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAW/D,OAAO,CAAC,aAAa;IA8BrB,OAAO,CAAC,aAAa;IASrB,OAAO,CAAC,KAAK;IA4Bb,OAAO,CAAC,YAAY;YAMN,UAAU;CAqBzB"}