@vauban-org/agent-sdk 0.16.0

package/dist/hitl/callback-handlers.js

@@ -0,0 +1,30 @@
+/**
+ * HITL callback handlers — unified re-export of Slack + Telegram handlers.
+ *
+ * Consumers can import from this module or directly from slack.ts / telegram.ts.
+ * Also provides a combined Node HTTP handler for Slack interactive payloads.
+ *
+ * @public
+ */
+export { createSlackCallbackHandler, verifySlackSignature, } from "./slack.js";
+export { createTelegramCallbackHandler, verifyTelegramSignature, } from "./telegram.js";
+export { collectBody, extractHeaders, parseCallbackData, } from "./api.js";
+import { collectBody, extractHeaders } from "./api.js";
+import { createSlackCallbackHandler, } from "./slack.js";
+/**
+ * Create a Node.js `http.IncomingMessage` handler for Slack interactive payloads.
+ *
+ * Wire to: POST /slack/interactive
+ * Reads the raw body (required for HMAC), verifies signature, resolves HITLPort.
+ */
+export function createNodeSlackCallbackHandler(opts) {
+    const handler = createSlackCallbackHandler(opts);
+    return async (req, res) => {
+        const rawBody = await collectBody(req);
+        const headers = extractHeaders(req);
+        const result = await handler({ rawBody, headers });
+        res.writeHead(result.status, { "Content-Type": "application/json" });
+        res.end(JSON.stringify(result.body));
+    };
+}
+//# sourceMappingURL=callback-handlers.js.map

package/dist/hitl/callback-handlers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"callback-handlers.js","sourceRoot":"","sources":["../../src/hitl/callback-handlers.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EACL,0BAA0B,EAC1B,oBAAoB,GAIrB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,6BAA6B,EAC7B,uBAAuB,GAExB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,WAAW,EACX,cAAc,EACd,iBAAiB,GAGlB,MAAM,UAAU,CAAC;AAKlB,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AACvD,OAAO,EACL,0BAA0B,GAE3B,MAAM,YAAY,CAAC;AAEpB;;;;;GAKG;AACH,MAAM,UAAU,8BAA8B,CAC5C,IAA8B;IAE9B,MAAM,OAAO,GAAG,0BAA0B,CAAC,IAAI,CAAC,CAAC;IAEjD,OAAO,KAAK,EAAE,GAAoB,EAAE,GAAmB,EAAiB,EAAE;QACxE,MAAM,OAAO,GAAG,MAAM,WAAW,CAAC,GAAG,CAAC,CAAC;QACvC,MAAM,OAAO,GAAG,cAAc,CAAC,GAAG,CAAC,CAAC;QAEpC,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC;QAEnD,GAAG,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE,CAAC,CAAC;QACrE,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;IACvC,CAAC,CAAC;AACJ,CAAC"}

package/dist/hitl/index.d.ts

@@ -0,0 +1,3 @@
+export { InMemoryApprovalStore } from "./approval-channel.js";
+export type { ApprovalChannel, ApprovalRequest, Approval, ApprovalStore, ApprovalStatus, PendingApproval, } from "./approval-channel.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/hitl/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/hitl/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,YAAY,EACV,eAAe,EACf,eAAe,EACf,QAAQ,EACR,aAAa,EACb,cAAc,EACd,eAAe,GAChB,MAAM,uBAAuB,CAAC"}

package/dist/hitl/index.js

@@ -0,0 +1,2 @@
+export { InMemoryApprovalStore } from "./approval-channel.js";
+//# sourceMappingURL=index.js.map

package/dist/hitl/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/hitl/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/hitl/slack.d.ts

@@ -0,0 +1,76 @@
+/**
+ * HITL Slack adapter — Block Kit approval messages + HMAC-verified callback handler.
+ *
+ * Plan v6 §1.7: channels are transports; state lives in HITLPort (Postgres).
+ * HMAC-SHA256 verification uses Slack signing secret (replay window: 5 min).
+ *
+ * @public
+ */
+import type { HITLPort, HITLRequest } from "../ports/hitl.js";
+/** Slack channel config — webhook URL only (no bot token). */
+export interface SlackChannelConfig {
+    /** Slack Incoming Webhook URL. Never hardcoded — pass at runtime. */
+    webhookUrl: string;
+}
+export interface SendHITLSlackOpts {
+    channel: SlackChannelConfig;
+    hitlPort: HITLPort;
+    request: HITLRequest;
+    /** Optional cost in USD for the Block Kit display. */
+    costDisplayUsd?: number;
+}
+export interface SlackApprovalResult {
+    approvalId: string;
+    messageTs: string;
+}
+/**
+ * Record a new HITL approval request and post a Block Kit message to Slack.
+ * Returns the approvalId (=request.id) and the Slack message timestamp.
+ */
+export declare function sendHITLApprovalRequestSlack(opts: SendHITLSlackOpts): Promise<SlackApprovalResult>;
+interface BlockKitOpts {
+    agentSource: string;
+    question: string;
+    approvalId: string;
+    costDisplay: string;
+    payloadSummary: string;
+    deadline: string;
+}
+/**
+ * Build a Slack Block Kit structure for HITL approval.
+ * Exported for snapshot testing.
+ */
+export declare function buildBlockKit(opts: BlockKitOpts): unknown[];
+export interface SlackCallbackHandlerOpts {
+    hitlPort: HITLPort;
+    /** Slack signing secret. Never hardcoded — pass at runtime. */
+    signingSecret: string;
+}
+/** Raw HTTP request shape — agnostic of HTTP framework. */
+export interface RawRequest {
+    rawBody: string;
+    headers: Record<string, string | string[] | undefined>;
+}
+export interface HandlerResult {
+    status: number;
+    body: unknown;
+}
+/**
+ * Create a Slack interactive-payload callback handler.
+ *
+ * Wire to: POST /slack/interactive
+ * Verifies HMAC-SHA256 signature, parses payload, calls hitlPort.resolve().
+ * Idempotent: duplicate payloads for the same approvalId are silently ignored
+ * (HITLPort throws InvalidStateTransitionError on non-pending → we swallow it).
+ */
+export declare function createSlackCallbackHandler(opts: SlackCallbackHandlerOpts): (req: RawRequest) => Promise<HandlerResult>;
+/**
+ * Verify the X-Slack-Signature header using HMAC-SHA256.
+ * Signature format: `v0=<hex>` over `v0:{timestamp}:{rawBody}`.
+ * Rejects timestamps older than 5 minutes (replay protection).
+ *
+ * @public — exported for unit tests
+ */
+export declare function verifySlackSignature(rawBody: string, timestamp: string, signature: string, secret: string): boolean;
+export {};
+//# sourceMappingURL=slack.d.ts.map

package/dist/hitl/slack.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slack.d.ts","sourceRoot":"","sources":["../../src/hitl/slack.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAI9D,8DAA8D;AAC9D,MAAM,WAAW,kBAAkB;IACjC,qEAAqE;IACrE,UAAU,EAAE,MAAM,CAAC;CACpB;AAID,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,kBAAkB,CAAC;IAC5B,QAAQ,EAAE,QAAQ,CAAC;IACnB,OAAO,EAAE,WAAW,CAAC;IACrB,sDAAsD;IACtD,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB;AAID;;;GAGG;AACH,wBAAsB,4BAA4B,CAChD,IAAI,EAAE,iBAAiB,GACtB,OAAO,CAAC,mBAAmB,CAAC,CAsC9B;AAID,UAAU,YAAY;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,EAAE,CAwE3D;AAID,MAAM,WAAW,wBAAwB;IACvC,QAAQ,EAAE,QAAQ,CAAC;IACnB,+DAA+D;IAC/D,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,2DAA2D;AAC3D,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC;CACxD;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;CACf;AAED;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,wBAAwB,GAC7B,CAAC,GAAG,EAAE,UAAU,KAAK,OAAO,CAAC,aAAa,CAAC,CAuE7C;AAID;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,GACb,OAAO,CAmBT"}

package/dist/hitl/slack.js

@@ -0,0 +1,243 @@
+/**
+ * HITL Slack adapter — Block Kit approval messages + HMAC-verified callback handler.
+ *
+ * Plan v6 §1.7: channels are transports; state lives in HITLPort (Postgres).
+ * HMAC-SHA256 verification uses Slack signing secret (replay window: 5 min).
+ *
+ * @public
+ */
+import { createHmac, timingSafeEqual } from "node:crypto";
+const MAX_PAYLOAD_PREVIEW_BYTES = 1500;
+/**
+ * Record a new HITL approval request and post a Block Kit message to Slack.
+ * Returns the approvalId (=request.id) and the Slack message timestamp.
+ */
+export async function sendHITLApprovalRequestSlack(opts) {
+    const { channel, hitlPort, request, costDisplayUsd } = opts;
+    // Register in HITLPort state machine (pending)
+    const approvalId = await hitlPort.request(request);
+    const costDisplay = costDisplayUsd != null ? `$${costDisplayUsd.toFixed(2)}` : "unknown";
+    const payloadSummary = summarizePayload(request.context);
+    const blocks = buildBlockKit({
+        agentSource: request.agentSource,
+        question: request.question,
+        approvalId,
+        costDisplay,
+        payloadSummary,
+        deadline: request.deadline,
+    });
+    const response = await fetch(channel.webhookUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ blocks }),
+    });
+    if (!response.ok) {
+        const body = await response.text().catch(() => "<read error>");
+        throw new Error(`[hitl-slack] Slack webhook returned ${response.status}: ${body.slice(0, 300)}`);
+    }
+    // Incoming webhooks don't return a timestamp — use ISO time as placeholder
+    const messageTs = String(Date.now());
+    return { approvalId, messageTs };
+}
+/**
+ * Build a Slack Block Kit structure for HITL approval.
+ * Exported for snapshot testing.
+ */
+export function buildBlockKit(opts) {
+    const { agentSource, question, approvalId, costDisplay, payloadSummary, deadline, } = opts;
+    return [
+        {
+            type: "header",
+            text: {
+                type: "plain_text",
+                text: `:shield: HITL Approval Required — ${agentSource}`,
+                emoji: true,
+            },
+        },
+        {
+            type: "section",
+            fields: [
+                { type: "mrkdwn", text: `*Agent:*\n${agentSource}` },
+                { type: "mrkdwn", text: `*Question:*\n${question}` },
+                { type: "mrkdwn", text: `*Cost:*\n${costDisplay}` },
+                { type: "mrkdwn", text: `*Deadline:*\n\`${deadline}\`` },
+            ],
+        },
+        {
+            type: "section",
+            text: {
+                type: "mrkdwn",
+                text: `*Context:*\n\`\`\`${payloadSummary}\`\`\``,
+            },
+        },
+        {
+            type: "context",
+            elements: [
+                {
+                    type: "mrkdwn",
+                    text: `:clock1: ${new Date().toISOString()} · Approval ID: \`${truncate(approvalId, 8)}\``,
+                },
+            ],
+        },
+        {
+            type: "actions",
+            block_id: `hitl_${approvalId.slice(0, 8)}`,
+            elements: [
+                {
+                    type: "button",
+                    text: {
+                        type: "plain_text",
+                        text: ":white_check_mark: Approve",
+                        emoji: true,
+                    },
+                    style: "primary",
+                    value: JSON.stringify({ approval_id: approvalId, action: "approve" }),
+                    action_id: "hitl_approve",
+                },
+                {
+                    type: "button",
+                    text: { type: "plain_text", text: ":x: Reject", emoji: true },
+                    style: "danger",
+                    value: JSON.stringify({ approval_id: approvalId, action: "reject" }),
+                    action_id: "hitl_reject",
+                },
+            ],
+        },
+    ];
+}
+/**
+ * Create a Slack interactive-payload callback handler.
+ *
+ * Wire to: POST /slack/interactive
+ * Verifies HMAC-SHA256 signature, parses payload, calls hitlPort.resolve().
+ * Idempotent: duplicate payloads for the same approvalId are silently ignored
+ * (HITLPort throws InvalidStateTransitionError on non-pending → we swallow it).
+ */
+export function createSlackCallbackHandler(opts) {
+    const { hitlPort, signingSecret } = opts;
+    return async (req) => {
+        const timestamp = headerString(req.headers["x-slack-request-timestamp"]);
+        const signature = headerString(req.headers["x-slack-signature"]);
+        if (!verifySlackSignature(req.rawBody, timestamp, signature, signingSecret)) {
+            return { status: 401, body: { ok: false, error: "invalid signature" } };
+        }
+        // Slack wraps the JSON payload in a form-encoded "payload" field
+        const parsed = parseFormEncoded(req.rawBody);
+        const wrapped = parsed["payload"];
+        if (!wrapped) {
+            return {
+                status: 400,
+                body: { ok: false, error: "missing payload field" },
+            };
+        }
+        let interaction;
+        try {
+            interaction = JSON.parse(wrapped);
+        }
+        catch {
+            return { status: 400, body: { ok: false, error: "invalid JSON" } };
+        }
+        const actionBlock = interaction.actions?.[0];
+        if (!actionBlock?.value) {
+            return {
+                status: 400,
+                body: { ok: false, error: "no action value" },
+            };
+        }
+        const buttonVal = parseButtonValue(actionBlock.value);
+        if (!buttonVal) {
+            return {
+                status: 400,
+                body: { ok: false, error: "invalid button value" },
+            };
+        }
+        const { approvalId, action } = buttonVal;
+        const decision = action === "approve" ? "approved" : "rejected";
+        try {
+            await hitlPort.resolve(approvalId, decision, "slack");
+        }
+        catch (err) {
+            // Idempotence: already resolved → silently accept
+            if (err instanceof Error &&
+                (err.name === "InvalidStateTransitionError" ||
+                    err.name === "HITLNotFoundError")) {
+                return {
+                    status: 200,
+                    body: { ok: true, note: "already resolved" },
+                };
+            }
+            throw err;
+        }
+        return {
+            status: 200,
+            body: { text: `Action ${action}d for ${approvalId}` },
+        };
+    };
+}
+// ─── HMAC verification ───────────────────────────────────────────────────────
+/**
+ * Verify the X-Slack-Signature header using HMAC-SHA256.
+ * Signature format: `v0=<hex>` over `v0:{timestamp}:{rawBody}`.
+ * Rejects timestamps older than 5 minutes (replay protection).
+ *
+ * @public — exported for unit tests
+ */
+export function verifySlackSignature(rawBody, timestamp, signature, secret) {
+    if (!timestamp || !signature)
+        return false;
+    const age = Math.abs(Date.now() / 1000 - Number(timestamp));
+    if (Number.isNaN(age) || age > 300)
+        return false;
+    const base = `v0:${timestamp}:${rawBody}`;
+    const computed = `v0=${createHmac("sha256", secret)
+        .update(base)
+        .digest("hex")}`;
+    try {
+        return timingSafeEqual(Buffer.from(computed, "utf-8"), Buffer.from(signature, "utf-8"));
+    }
+    catch {
+        return false;
+    }
+}
+// ─── Private helpers ─────────────────────────────────────────────────────────
+function parseButtonValue(value) {
+    try {
+        const parsed = JSON.parse(value);
+        if (typeof parsed.approval_id === "string" &&
+            parsed.approval_id.length > 0 &&
+            (parsed.action === "approve" || parsed.action === "reject")) {
+            return { approvalId: parsed.approval_id, action: parsed.action };
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+function parseFormEncoded(body) {
+    const result = {};
+    for (const pair of body.split("&")) {
+        const idx = pair.indexOf("=");
+        if (idx === -1)
+            continue;
+        const key = decodeURIComponent(pair.slice(0, idx).replace(/\+/g, " "));
+        const val = decodeURIComponent(pair.slice(idx + 1).replace(/\+/g, " "));
+        result[key] = val;
+    }
+    return result;
+}
+function headerString(h) {
+    if (!h)
+        return "";
+    return Array.isArray(h) ? h[0] ?? "" : h;
+}
+function summarizePayload(payload) {
+    const raw = JSON.stringify(payload, null, 2);
+    if (Buffer.byteLength(raw, "utf-8") <= MAX_PAYLOAD_PREVIEW_BYTES)
+        return raw;
+    return `${raw.slice(0, MAX_PAYLOAD_PREVIEW_BYTES - 50)}\n... [truncated]`;
+}
+function truncate(s, maxLen) {
+    return s.length <= maxLen ? s : `${s.slice(0, maxLen)}…`;
+}
+//# sourceMappingURL=slack.js.map

package/dist/hitl/slack.js.map

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

package/dist/hitl/telegram.d.ts

@@ -0,0 +1,74 @@
+/**
+ * HITL Telegram adapter — inline keyboard approval messages + HMAC-verified callback handler.
+ *
+ * Plan v6 §1.7: channels are transports; state lives in HITLPort (Postgres).
+ * Callback_data uses compact keys (a/v) to stay within Telegram's 64-byte limit.
+ *
+ * @public
+ */
+import type { HITLPort, HITLRequest } from "../ports/hitl.js";
+/** Telegram channel config. */
+export interface TelegramChannelConfig {
+    /** Telegram Bot API token. Never hardcoded — pass at runtime. */
+    botToken: string;
+    /** Target chat ID (string or negative number for groups). */
+    chatId: string;
+}
+export interface SendHITLTelegramOpts {
+    channel: TelegramChannelConfig;
+    hitlPort: HITLPort;
+    request: HITLRequest;
+}
+export interface TelegramApprovalResult {
+    approvalId: string;
+    messageId: number;
+}
+/**
+ * Record a new HITL approval request and send an inline-keyboard message via Telegram.
+ * Returns the approvalId (=request.id) and the Telegram message_id.
+ */
+export declare function sendHITLApprovalRequestTelegram(opts: SendHITLTelegramOpts): Promise<TelegramApprovalResult>;
+interface TelegramTextOpts {
+    agentSource: string;
+    question: string;
+    approvalId: string;
+    payloadSummary: string;
+    deadline: string;
+}
+/**
+ * Build the MarkdownV2 message text for a HITL approval request.
+ * Exported for snapshot testing.
+ */
+export declare function buildTelegramText(opts: TelegramTextOpts): string;
+export interface TelegramCallbackHandlerOpts {
+    hitlPort: HITLPort;
+    /** Telegram bot token — used to answer the callback query (removes loading spinner). */
+    botToken: string;
+    /** Optional HMAC secret for validating x-telegram-hmac-sha256 header. */
+    callbackSecret?: string;
+}
+export interface HandlerResult {
+    status: number;
+    body: unknown;
+}
+/**
+ * Create a Telegram webhook callback handler.
+ *
+ * Validates optional HMAC signature, extracts callback_data (compact a/v format),
+ * calls hitlPort.resolve(), then answers the Telegram callback query.
+ * Idempotent: duplicate callbacks for an already-resolved request are silently ignored.
+ */
+export declare function createTelegramCallbackHandler(opts: TelegramCallbackHandlerOpts): (rawBody: string, headers: Record<string, string>) => Promise<HandlerResult>;
+/**
+ * Verify the x-telegram-hmac-sha256 header using HMAC-SHA256 of the raw body.
+ *
+ * @public — exported for unit tests
+ */
+export declare function verifyTelegramSignature(rawBody: string, signature: string, secret: string): boolean;
+/**
+ * Send a plain informational message to a Telegram chat (no buttons).
+ * Used for daily briefs and non-interactive notifications.
+ */
+export declare function sendTelegramMessage(text: string, channel: TelegramChannelConfig): Promise<void>;
+export {};
+//# sourceMappingURL=telegram.d.ts.map

package/dist/hitl/telegram.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telegram.d.ts","sourceRoot":"","sources":["../../src/hitl/telegram.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAI9D,+BAA+B;AAC/B,MAAM,WAAW,qBAAqB;IACpC,iEAAiE;IACjE,QAAQ,EAAE,MAAM,CAAC;IACjB,6DAA6D;IAC7D,MAAM,EAAE,MAAM,CAAC;CAChB;AAID,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,qBAAqB,CAAC;IAC/B,QAAQ,EAAE,QAAQ,CAAC;IACnB,OAAO,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,sBAAsB;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB;AAKD;;;GAGG;AACH,wBAAsB,+BAA+B,CACnD,IAAI,EAAE,oBAAoB,GACzB,OAAO,CAAC,sBAAsB,CAAC,CAgEjC;AAID,UAAU,gBAAgB;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,gBAAgB,GAAG,MAAM,CAkBhE;AAID,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,EAAE,QAAQ,CAAC;IACnB,wFAAwF;IACxF,QAAQ,EAAE,MAAM,CAAC;IACjB,yEAAyE;IACzE,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;CACf;AAED;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAC3C,IAAI,EAAE,2BAA2B,GAChC,CACD,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAC5B,OAAO,CAAC,aAAa,CAAC,CAsG1B;AAID;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,GACb,OAAO,CAWT;AAID;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,IAAI,CAAC,CAiBf"}