@larksuite/openclaw-lark 2026.3.9

package/src/core/agent-config.js

@@ -0,0 +1,140 @@
+// SPDX-License-Identifier: MIT
+/**
+ * Agent configuration helpers for the Feishu/Lark channel plugin.
+ *
+ * Reads agent-level configuration (identity, skills, tools, subagents)
+ * from the top-level `agents.list` in OpenClawConfig.  These helpers
+ * bridge the gap between the SDK's agent infrastructure and the Feishu
+ * plugin's dispatch/reply layers.
+ */
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Retrieve the full list of configured agents from config.
+ *
+ * @param cfg - The top-level application config.
+ * @returns Array of agent entries, or empty array if none configured.
+ */
+export function listConfiguredAgents(cfg) {
+    const agents = cfg.agents;
+    return agents?.list ?? [];
+}
+/**
+ * Look up a specific agent's configuration by its ID.
+ *
+ * @param cfg - The top-level application config.
+ * @param agentId - The agent ID to search for.
+ * @returns The matching agent entry, or `undefined` if not found.
+ */
+export function resolveAgentEntry(cfg, agentId) {
+    return listConfiguredAgents(cfg).find((a) => a.id === agentId);
+}
+/**
+ * Resolve a human-readable display name for an agent.
+ *
+ * Priority: `identity.name` > `name` > `undefined`.
+ *
+ * @param cfg - The top-level application config.
+ * @param agentId - The agent ID.
+ * @returns The display name, or `undefined` if none configured.
+ */
+export function getAgentDisplayName(cfg, agentId) {
+    const entry = resolveAgentEntry(cfg, agentId);
+    if (!entry)
+        return undefined;
+    return entry.identity?.name ?? entry.name;
+}
+/**
+ * Resolve the per-agent skills filter.
+ *
+ * @param cfg - The top-level application config.
+ * @param agentId - The agent ID.
+ * @returns Skill allowlist, or `undefined` if no agent-level filter.
+ */
+export function getAgentSkillsFilter(cfg, agentId) {
+    return resolveAgentEntry(cfg, agentId)?.skills;
+}
+/**
+ * Resolve the per-agent tools policy (allow/deny lists).
+ *
+ * @param cfg - The top-level application config.
+ * @param agentId - The agent ID.
+ * @returns Tools policy object, or `undefined` if none configured.
+ */
+export function getAgentToolsPolicy(cfg, agentId) {
+    const entry = resolveAgentEntry(cfg, agentId);
+    if (!entry?.tools)
+        return undefined;
+    const { allow, deny } = entry.tools;
+    if (!allow && !deny)
+        return undefined;
+    return { allow, deny };
+}
+/**
+ * Merge agent-level and group-level skill filters.
+ *
+ * When both are present, the effective filter is the intersection:
+ * a skill must appear in both lists to be included.  When only one
+ * is present, that list is used as-is.
+ *
+ * @param agentSkills - Per-agent skill allowlist (from AgentConfig.skills).
+ * @param groupSkills - Per-group skill allowlist (from FeishuGroupConfig.skills).
+ * @returns Merged skill filter, or `undefined` if neither is set.
+ */
+export function mergeSkillFilters(agentSkills, groupSkills) {
+    if (!agentSkills && !groupSkills)
+        return undefined;
+    if (!agentSkills)
+        return groupSkills;
+    if (!groupSkills)
+        return agentSkills;
+    // Intersection: group filter narrows the agent filter.
+    const agentSet = new Set(agentSkills);
+    return groupSkills.filter((s) => agentSet.has(s));
+}
+/**
+ * Check whether a tool name is permitted by an agent's tool policy.
+ *
+ * Evaluation order:
+ *   1. If `deny` list exists and tool matches → denied.
+ *   2. If `allow` list exists and tool does NOT match → denied.
+ *   3. Otherwise → allowed.
+ *
+ * Supports glob-like patterns with trailing `*` (e.g. `feishu_calendar_*`).
+ *
+ * @param toolName - The tool name being invoked.
+ * @param policy - The agent's tool policy.
+ * @returns `true` if the tool is allowed, `false` if denied.
+ */
+export function isToolAllowedByPolicy(toolName, policy) {
+    if (!policy)
+        return true;
+    if (policy.deny && policy.deny.length > 0) {
+        if (matchesAnyPattern(toolName, policy.deny))
+            return false;
+    }
+    if (policy.allow && policy.allow.length > 0) {
+        return matchesAnyPattern(toolName, policy.allow);
+    }
+    return true;
+}
+/**
+ * Check whether a string matches any of the given patterns.
+ * Supports trailing `*` as a simple wildcard.
+ */
+function matchesAnyPattern(value, patterns) {
+    for (const pattern of patterns) {
+        if (pattern === '*')
+            return true;
+        if (pattern.endsWith('*')) {
+            if (value.startsWith(pattern.slice(0, -1)))
+                return true;
+        }
+        else if (value === pattern) {
+            return true;
+        }
+    }
+    return false;
+}
+//# sourceMappingURL=agent-config.js.map

package/src/core/agent-config.js.map

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

package/src/core/api-error.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Shared Lark API error handling utilities.
+ *
+ * Provides unified error handling for two distinct error paths:
+ *
+ * 1. **Response-level errors** — The SDK returns a response object with a
+ *    non-zero `code`.  Handled by {@link assertLarkOk}.
+ *
+ * 2. **Thrown exceptions** — The SDK throws an Axios-style error (HTTP 4xx)
+ *    whose properties include the Feishu error `code` and `msg`.
+ *    Handled by {@link formatLarkError}.
+ *
+ * Both paths intercept well-known codes (e.g. LARK_ERROR.APP_SCOPE_MISSING (99991672) — missing API scopes)
+ * and produce user-friendly messages with actionable authorization links.
+ */
+/**
+ * 从 Lark SDK 抛错对象中提取飞书 API code。
+ *
+ * 支持三种常见结构：
+ * - `{ code }` — SDK 直接挂载
+ * - `{ data: { code } }` — 响应体嵌套
+ * - `{ response: { data: { code } } }` — Axios 风格
+ */
+export declare function extractLarkApiCode(err: unknown): number | undefined;
+/**
+ * Assert that a Lark SDK response is successful (code === 0).
+ *
+ * For permission errors (code LARK_ERROR.APP_SCOPE_MISSING (99991672)), the thrown error includes the
+ * required scope names and a direct authorization URL so the AI can
+ * present it to the end user.
+ */
+export declare function assertLarkOk(res: {
+    code?: number;
+    msg?: string;
+}): void;
+/**
+ * Extract a meaningful error message from a thrown Lark SDK / Axios error.
+ *
+ * The Lark SDK throws Axios errors whose object carries Feishu-specific
+ * fields (`code`, `msg`) alongside the standard `message`.  For permission
+ * errors (LARK_ERROR.APP_SCOPE_MISSING (99991672)) we format a user-friendly string with scopes + auth URL.
+ * For all other errors we try `err.msg` first (the Feishu detail) and fall
+ * back to `err.message` (the generic Axios text).
+ */
+export declare function formatLarkError(err: unknown): string;
+//# sourceMappingURL=api-error.d.ts.map

package/src/core/api-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-error.d.ts","sourceRoot":"","sources":["../../../src/core/api-error.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAqCH;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAUnE;AAMD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAOvE;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CA4BpD"}

package/src/core/api-error.js

@@ -0,0 +1,113 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Shared Lark API error handling utilities.
+ *
+ * Provides unified error handling for two distinct error paths:
+ *
+ * 1. **Response-level errors** — The SDK returns a response object with a
+ *    non-zero `code`.  Handled by {@link assertLarkOk}.
+ *
+ * 2. **Thrown exceptions** — The SDK throws an Axios-style error (HTTP 4xx)
+ *    whose properties include the Feishu error `code` and `msg`.
+ *    Handled by {@link formatLarkError}.
+ *
+ * Both paths intercept well-known codes (e.g. LARK_ERROR.APP_SCOPE_MISSING (99991672) — missing API scopes)
+ * and produce user-friendly messages with actionable authorization links.
+ */
+import { extractPermissionGrantUrl, extractPermissionScopes } from './permission-url';
+import { LARK_ERROR } from './auth-errors';
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Given a Feishu error code and msg, format a user-friendly permission
+ * error string if the code is LARK_ERROR.APP_SCOPE_MISSING (99991672).  Returns `null` for other codes.
+ */
+function formatPermissionError(code, msg) {
+    if (code !== LARK_ERROR.APP_SCOPE_MISSING)
+        return null;
+    const authUrl = extractPermissionGrantUrl(msg);
+    const scopes = extractPermissionScopes(msg);
+    return `权限不足：应用缺少 [${scopes}] 权限。\n` + `请管理员点击以下链接申请并开通权限：\n${authUrl}`;
+}
+// ---------------------------------------------------------------------------
+// Code extraction
+// ---------------------------------------------------------------------------
+function coerceCode(value) {
+    if (typeof value === 'number' && Number.isFinite(value)) {
+        return value;
+    }
+    if (typeof value === 'string') {
+        const parsed = Number(value);
+        if (Number.isFinite(parsed))
+            return parsed;
+    }
+    return undefined;
+}
+/**
+ * 从 Lark SDK 抛错对象中提取飞书 API code。
+ *
+ * 支持三种常见结构：
+ * - `{ code }` — SDK 直接挂载
+ * - `{ data: { code } }` — 响应体嵌套
+ * - `{ response: { data: { code } } }` — Axios 风格
+ */
+export function extractLarkApiCode(err) {
+    if (!err || typeof err !== 'object')
+        return undefined;
+    const e = err;
+    return coerceCode(e.code) ?? coerceCode(e.data?.code) ?? coerceCode(e.response?.data?.code);
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Assert that a Lark SDK response is successful (code === 0).
+ *
+ * For permission errors (code LARK_ERROR.APP_SCOPE_MISSING (99991672)), the thrown error includes the
+ * required scope names and a direct authorization URL so the AI can
+ * present it to the end user.
+ */
+export function assertLarkOk(res) {
+    if (!res.code || res.code === 0)
+        return;
+    const permMsg = formatPermissionError(res.code, res.msg ?? '');
+    if (permMsg)
+        throw new Error(permMsg);
+    throw new Error(res.msg ?? `Feishu API error (code: ${res.code})`);
+}
+/**
+ * Extract a meaningful error message from a thrown Lark SDK / Axios error.
+ *
+ * The Lark SDK throws Axios errors whose object carries Feishu-specific
+ * fields (`code`, `msg`) alongside the standard `message`.  For permission
+ * errors (LARK_ERROR.APP_SCOPE_MISSING (99991672)) we format a user-friendly string with scopes + auth URL.
+ * For all other errors we try `err.msg` first (the Feishu detail) and fall
+ * back to `err.message` (the generic Axios text).
+ */
+export function formatLarkError(err) {
+    if (!err || typeof err !== 'object') {
+        return String(err);
+    }
+    const e = err;
+    // Path 1: Lark SDK merges Feishu fields onto the thrown error object.
+    if (typeof e.code === 'number' && e.msg) {
+        const permMsg = formatPermissionError(e.code, e.msg);
+        if (permMsg)
+            return permMsg;
+        return e.msg;
+    }
+    // Path 2: Standard Axios error — dig into response.data.
+    const data = e.response?.data;
+    if (data && typeof data.code === 'number' && data.msg) {
+        const permMsg = formatPermissionError(data.code, data.msg);
+        if (permMsg)
+            return permMsg;
+        return data.msg;
+    }
+    // Fallback.
+    return e.message ?? String(err);
+}
+//# sourceMappingURL=api-error.js.map

package/src/core/api-error.js.map

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

package/src/core/app-owner-fallback.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * 应用所有者查询 — 复用 app-scope-checker 的 API 调用和统一 owner 定义。
+ *
+ * 所有 owner 判定统一使用 {@link getAppInfo} 返回的 `effectiveOwnerOpenId`。
+ * 不维护独立缓存，完全依赖 app-scope-checker 的 30s 缓存。
+ */
+import type { ConfiguredLarkAccount } from './types';
+/**
+ * 获取应用的 effectiveOwnerOpenId。
+ *
+ * 复用 app-scope-checker 的 API 调用、缓存和统一 owner 定义（effectiveOwnerOpenId）。
+ * 查询失败时返回 undefined（fail-open）。
+ *
+ * @param account - 已配置的飞书账号信息
+ * @param sdk - 飞书 SDK 实例（必须已初始化 TAT）
+ * @returns 应用所有者的 open_id，如果查询失败则返回 undefined
+ */
+export declare function getAppOwnerFallback(account: ConfiguredLarkAccount, sdk: any): Promise<string | undefined>;
+//# sourceMappingURL=app-owner-fallback.d.ts.map

package/src/core/app-owner-fallback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-owner-fallback.d.ts","sourceRoot":"","sources":["../../../src/core/app-owner-fallback.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAUrD;;;;;;;;;GASG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,qBAAqB,EAE9B,GAAG,EAAE,GAAG,GACP,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAU7B"}

package/src/core/app-owner-fallback.js

@@ -0,0 +1,39 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * 应用所有者查询 — 复用 app-scope-checker 的 API 调用和统一 owner 定义。
+ *
+ * 所有 owner 判定统一使用 {@link getAppInfo} 返回的 `effectiveOwnerOpenId`。
+ * 不维护独立缓存，完全依赖 app-scope-checker 的 30s 缓存。
+ */
+import { getAppInfo } from './app-scope-checker';
+import { larkLogger } from './lark-logger';
+const log = larkLogger('core/app-owner-fallback');
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * 获取应用的 effectiveOwnerOpenId。
+ *
+ * 复用 app-scope-checker 的 API 调用、缓存和统一 owner 定义（effectiveOwnerOpenId）。
+ * 查询失败时返回 undefined（fail-open）。
+ *
+ * @param account - 已配置的飞书账号信息
+ * @param sdk - 飞书 SDK 实例（必须已初始化 TAT）
+ * @returns 应用所有者的 open_id，如果查询失败则返回 undefined
+ */
+export async function getAppOwnerFallback(account, 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+sdk) {
+    const { appId } = account;
+    try {
+        const appInfo = await getAppInfo(sdk, appId);
+        return appInfo.effectiveOwnerOpenId;
+    }
+    catch (err) {
+        log.warn(`failed to get owner for ${appId}: ${err instanceof Error ? err.message : err}`);
+        return undefined; // fail-open: 获取失败不阻塞业务
+    }
+}
+//# sourceMappingURL=app-owner-fallback.js.map

package/src/core/app-owner-fallback.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-owner-fallback.js","sourceRoot":"","sources":["../../../src/core/app-owner-fallback.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAE3C,MAAM,GAAG,GAAG,UAAU,CAAC,yBAAyB,CAAC,CAAC;AAElD,8EAA8E;AAC9E,aAAa;AACb,8EAA8E;AAE9E;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,OAA8B;AAC9B,8DAA8D;AAC9D,GAAQ;IAER,MAAM,EAAE,KAAK,EAAE,GAAG,OAAO,CAAC;IAE1B,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,UAAU,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAC7C,OAAO,OAAO,CAAC,oBAAoB,CAAC;IACtC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,GAAG,CAAC,IAAI,CAAC,2BAA2B,KAAK,KAAK,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC;QAC1F,OAAO,SAAS,CAAC,CAAC,uBAAuB;IAC3C,CAAC;AACH,CAAC"}

package/src/core/app-scope-checker.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * App Scope Checker — 查询应用已开通的 scope 列表。
+ *
+ * 通过 `GET /open-apis/application/v6/applications/:app_id` (TAT) 获取
+ * 应用信息，从 `app.scopes` 中提取已开通的 scope 字符串列表。
+ *
+ * 结果带 30 秒内存缓存，避免每次 invoke() 都调远程 API。
+ * scope 检查失败后可调 {@link invalidateAppScopeCache} 清缓存重查。
+ */
+import type * as Lark from '@larksuiteoapi/node-sdk';
+export interface AppInfo {
+    appId: string;
+    creatorId?: string;
+    ownerOpenId?: string;
+    ownerType?: number;
+    /**
+     * 统一的 owner 判定结果。所有需要判定"谁是应用 owner"的场景都应使用此字段。
+     *
+     * 规则：owner_type=2（企业内成员）时取 owner_id，否则回退 creator_id。
+     * 兼容 owner.owner_type 和 owner.type 两种字段名。
+     */
+    effectiveOwnerOpenId?: string;
+    scopes: Array<{
+        scope: string;
+        token_types?: string[];
+    }>;
+}
+/** 清除指定 appId 的缓存。 */
+export declare function invalidateAppScopeCache(appId: string): void;
+/**
+ * 获取应用已开通的 scope 列表。
+ *
+ * 需要应用自身有 `application:application:self_manage` 权限。
+ * `appId` 可传 `"me"` 查自己。
+ *
+ * @param sdk - Lark SDK 实例
+ * @param appId - 应用 ID
+ * @param tokenType - token 类型，用于过滤只支持特定 token 类型的 scope
+ * @returns scope 字符串数组，如 `["calendar:calendar", "task:task:write"]`
+ */
+export declare function getAppGrantedScopes(sdk: Lark.Client, appId: string, tokenType?: 'user' | 'tenant'): Promise<string[]>;
+/**
+ * 获取应用信息，包括 owner 信息。
+ *
+ * 复用 getAppGrantedScopes 的 API 调用和缓存。
+ * 如果缓存中已有数据且未过期，直接从缓存提取。
+ *
+ * @param sdk - Lark SDK 实例
+ * @param appId - 应用 ID（可传 "me"）
+ */
+export declare function getAppInfo(sdk: Lark.Client, appId: string): Promise<AppInfo>;
+/**
+ * 计算 APP 已有 ∩ OAPI 需要 的交集。
+ *
+ * 用于传给 OAuth 的 scope 参数 — 只请求 APP 已开通且 API 需要的 scope。
+ *
+ * @param appGranted - 应用已开通的 scope 列表
+ * @param apiRequired - OAPI 要求的 scope 列表
+ * @returns 交集 scope 列表
+ */
+export declare function intersectScopes(appGranted: string[], apiRequired: string[]): string[];
+/**
+ * 计算 OAPI 需要但 APP 未开通的 scope（差集）。
+ *
+ * 用于 AppScopeMissingError 的 missingScopes。
+ *
+ * @param appGranted - 应用已开通的 scope 列表
+ * @param apiRequired - OAPI 要求的 scope 列表
+ * @returns 缺失的 scope 列表
+ */
+export declare function missingScopes(appGranted: string[], apiRequired: string[]): string[];
+/**
+ * 校验应用已开通的 scope 是否满足要求。
+ *
+ * 与 tool-client.ts invoke() 的 scope 校验逻辑完全一致，作为唯一真值来源：
+ *   - `scopeNeedType === "all"`: appScopes 必须包含 requiredScopes 的全部项
+ *   - 其他（默认 "one"）:        appScopes 与 requiredScopes 的交集非空即可
+ *   - appScopes 为空:            视为满足（API 查询失败，退回服务端判断）
+ *
+ * @param appScopes      - 应用已开通的 scope 列表（由 getAppGrantedScopes 返回）
+ * @param requiredScopes - 需要的 scope 列表
+ * @param scopeNeedType  - "all" 表示全部必须，undefined/"one" 表示任一即可
+ */
+export declare function isAppScopeSatisfied(appScopes: string[], requiredScopes: string[], scopeNeedType?: 'one' | 'all'): boolean;
+//# sourceMappingURL=app-scope-checker.d.ts.map

package/src/core/app-scope-checker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-scope-checker.d.ts","sourceRoot":"","sources":["../../../src/core/app-scope-checker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,KAAK,IAAI,MAAM,yBAAyB,CAAC;AAUrD,MAAM,WAAW,OAAO;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,MAAM,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC;CAC1D;AAeD,sBAAsB;AACtB,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAE3D;AAMD;;;;;;;;;;GAUG;AACH,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,IAAI,CAAC,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,SAAS,CAAC,EAAE,MAAM,GAAG,QAAQ,GAC5B,OAAO,CAAC,MAAM,EAAE,CAAC,CA+EnB;AAMD;;;;;;;;GAQG;AACH,wBAAsB,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CA2BlF;AAMD;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAGrF;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAGnF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,MAAM,EAAE,EACnB,cAAc,EAAE,MAAM,EAAE,EACxB,aAAa,CAAC,EAAE,KAAK,GAAG,KAAK,GAC5B,OAAO,CAOT"}