@moxxy/plugin-telegram 0.27.0

package/dist/channel/frame-pump.js

@@ -0,0 +1,159 @@
+import { GrammyError } from 'grammy';
+import { FramePump as StreamPump } from '@moxxy/channel-kit';
+import { TurnRenderer, splitForTelegram } from '../render.js';
+import { composeFrame, stripHtml } from './html.js';
+/**
+ * Drives the throttled "compose snapshot → send/edit one message" loop
+ * for a turn. Owns the renderer and the Telegram-specific delivery —
+ * HTML parse-mode fallback + 4096-char message splitting — while the
+ * throttle/send-once-then-edit mechanics live in `@moxxy/channel-kit`'s
+ * {@link StreamPump} (one instance per turn).
+ *
+ * Lifecycle per turn:
+ *   1. `beginTurn(chatId)` resets state.
+ *   2. Renderer updates schedule edits via `scheduleEdit()`.
+ *   3. `flush(final)` drains the latest snapshot to Telegram.
+ *   4. `endTurn()` clears timers + chat binding.
+ */
+export class FramePump {
+    editFrameMs;
+    logger;
+    bot = null;
+    renderer = new TurnRenderer();
+    pump = null;
+    constructor(opts) {
+        this.editFrameMs = opts.editFrameMs;
+        if (opts.logger)
+            this.logger = opts.logger;
+    }
+    attachBot(bot) {
+        this.bot = bot;
+    }
+    /** Renderer the channel feeds events into. Owned here so reset/snapshot
+     *  cycles stay coordinated with the message-id state. */
+    get renderState() {
+        return this.renderer;
+    }
+    resetRenderer() {
+        this.renderer.reset();
+    }
+    beginTurn(chatId) {
+        this.renderer.reset();
+        this.pump = new StreamPump({
+            editFrameMs: this.editFrameMs,
+            // Only the FINAL frame collapses the activity trace into its expandable
+            // box — mid-stream frames keep it open so the user watches work land live.
+            frame: (final) => composeFrame(this.renderer.snapshot({ collapse: final })),
+            // The final flush must produce at least one message so the user isn't
+            // left with the typing indicator dangling.
+            emptyFinalText: '<i>(no output)</i>',
+            // The sink does final-only work (split-overflow tails below), so the
+            // final frame must reach it even when the text didn't change since the
+            // last streamed edit.
+            alwaysFlushFinal: true,
+            sink: {
+                send: (text, final) => this.sendFrame(chatId, text, final),
+                edit: (messageId, text, final) => this.editFrame(chatId, messageId, text, final),
+            },
+        });
+    }
+    endTurn() {
+        this.pump?.dispose();
+        this.pump = null;
+    }
+    scheduleEdit() {
+        this.pump?.scheduleEdit();
+    }
+    async flush(final) {
+        if (!this.bot || !this.pump)
+            return;
+        await this.pump.flush(final);
+    }
+    /** First real content of this turn — send (don't edit a placeholder). On the
+     *  final frame, overflow beyond Telegram's message limit goes out as
+     *  follow-up messages. */
+    async sendFrame(chatId, text, final) {
+        if (!this.bot)
+            return null;
+        const parts = splitForTelegram(text);
+        const sent = await this.safeSend(chatId, parts[0]);
+        if (final && parts.length > 1) {
+            for (const tail of parts.slice(1)) {
+                await this.safeSend(chatId, tail);
+            }
+        }
+        return sent;
+    }
+    async editFrame(chatId, messageId, text, final) {
+        if (!this.bot)
+            return;
+        const parts = splitForTelegram(text);
+        await this.safeEdit(chatId, messageId, parts[0]);
+        if (final && parts.length > 1) {
+            for (const tail of parts.slice(1)) {
+                await this.safeSend(chatId, tail);
+            }
+        }
+    }
+    /**
+     * `text` is already Telegram-flavored HTML (produced by
+     * `composeFrame`). Try HTML; on parse-entity errors, strip tags and
+     * send plain text so the message still lands instead of looping on
+     * the same edit forever.
+     */
+    async safeEdit(chatId, messageId, text) {
+        try {
+            await this.bot.api.editMessageText(chatId, messageId, text, {
+                parse_mode: 'HTML',
+                link_preview_options: { is_disabled: true },
+            });
+            return;
+        }
+        catch (err) {
+            if (err instanceof GrammyError && err.description?.includes('not modified'))
+                return;
+            if (err instanceof GrammyError && /can't parse entities|Bad Request: can't parse/i.test(err.description ?? '')) {
+                try {
+                    await this.bot.api.editMessageText(chatId, messageId, stripHtml(text));
+                    return;
+                }
+                catch (plainErr) {
+                    if (plainErr instanceof GrammyError && plainErr.description?.includes('not modified'))
+                        return;
+                    this.logger?.warn('editMessageText plain-fallback failed', { err: String(plainErr) });
+                    return;
+                }
+            }
+            this.logger?.warn('editMessageText failed', { err: String(err) });
+        }
+    }
+    /**
+     * Send a new message (first frame of a turn or split-tail).
+     * Returns the new message_id on success so callers can set
+     * messageId for future edits.
+     */
+    async safeSend(chatId, text) {
+        try {
+            const sent = await this.bot.api.sendMessage(chatId, text, {
+                parse_mode: 'HTML',
+                link_preview_options: { is_disabled: true },
+            });
+            return sent.message_id;
+        }
+        catch (err) {
+            if (err instanceof GrammyError && /can't parse entities|Bad Request: can't parse/i.test(err.description ?? '')) {
+                try {
+                    const sent = await this.bot.api.sendMessage(chatId, stripHtml(text));
+                    return sent.message_id;
+                }
+                catch (plainErr) {
+                    this.logger?.warn('sendMessage plain-fallback failed', { err: String(plainErr) });
+                    return null;
+                }
+            }
+            this.logger?.warn('sendMessage failed', { err: String(err) });
+            return null;
+        }
+    }
+}
+//# sourceMappingURL=frame-pump.js.map

package/dist/channel/frame-pump.js.map

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

package/dist/channel/html.d.ts

@@ -0,0 +1,24 @@
+import type { RenderedFrame } from '../render.js';
+/**
+ * Compose one Telegram message string from the renderer's structured
+ * snapshot. The activity block is pre-formatted HTML (the renderer
+ * emits `<blockquote>`, `<code>`, `<b>`, `<i>` directly so it can
+ * style tool calls without going through the markdown converter). The
+ * assistant body is plain Markdown from the model — convert it through
+ * `markdownToTelegramHtml` so `**bold**`, `` `code` ``, ```code blocks```,
+ * `[links](…)`, and list bullets render natively in Telegram.
+ *
+ * The error line is also pre-formatted HTML (small, controlled).
+ */
+export declare function composeFrame(snap: RenderedFrame): string;
+/** Strip every HTML tag for plain-text fallback when Telegram rejects
+ *  our parse_mode=HTML payload (rare — usually a malformed entity in
+ *  user-supplied content). Keeps text content intact.
+ *
+ *  Entities are decoded in a single pass with `&amp;` LAST: decoding it first
+ *  would double-decode (`&amp;lt;` → `&lt;` → `<`). Numeric entities
+ *  (`&#39;`, `&#x27;`) are handled too, since escaped user/code content can
+ *  carry them and they'd otherwise leak literally into the fallback message. */
+export declare function stripHtml(html: string): string;
+export declare function truncate(s: string, n: number): string;
+//# sourceMappingURL=html.d.ts.map

package/dist/channel/html.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"html.d.ts","sourceRoot":"","sources":["../../src/channel/html.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CAWxD;AAED;;;;;;;gFAOgF;AAChF,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAS9C;AAaD,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAErD"}

package/dist/channel/html.js

@@ -0,0 +1,62 @@
+import { markdownToTelegramHtml } from '../format.js';
+/**
+ * Compose one Telegram message string from the renderer's structured
+ * snapshot. The activity block is pre-formatted HTML (the renderer
+ * emits `<blockquote>`, `<code>`, `<b>`, `<i>` directly so it can
+ * style tool calls without going through the markdown converter). The
+ * assistant body is plain Markdown from the model — convert it through
+ * `markdownToTelegramHtml` so `**bold**`, `` `code` ``, ```code blocks```,
+ * `[links](…)`, and list bullets render natively in Telegram.
+ *
+ * The error line is also pre-formatted HTML (small, controlled).
+ */
+export function composeFrame(snap) {
+    const parts = [];
+    if (snap.activityHtml)
+        parts.push(snap.activityHtml);
+    if (snap.body)
+        parts.push(markdownToTelegramHtml(snap.body));
+    // File-diff blocks are already Telegram HTML (summary line + a
+    // <pre><code class="language-diff"> fence), so they skip the markdown
+    // converter. Append after the body; the frame pump's `splitForTelegram`
+    // handles the 4000-char cap, sending overflow as follow-up messages.
+    if (snap.diffHtml)
+        parts.push(snap.diffHtml);
+    if (snap.errorHtml)
+        parts.push(snap.errorHtml);
+    return parts.join('\n\n');
+}
+/** Strip every HTML tag for plain-text fallback when Telegram rejects
+ *  our parse_mode=HTML payload (rare — usually a malformed entity in
+ *  user-supplied content). Keeps text content intact.
+ *
+ *  Entities are decoded in a single pass with `&amp;` LAST: decoding it first
+ *  would double-decode (`&amp;lt;` → `&lt;` → `<`). Numeric entities
+ *  (`&#39;`, `&#x27;`) are handled too, since escaped user/code content can
+ *  carry them and they'd otherwise leak literally into the fallback message. */
+export function stripHtml(html) {
+    return html
+        .replace(/<\/?[a-z][^>]*>/gi, '')
+        .replace(/&#(\d+);/g, (_, dec) => safeFromCodePoint(parseInt(dec, 10)))
+        .replace(/&#x([0-9a-f]+);/gi, (_, hex) => safeFromCodePoint(parseInt(hex, 16)))
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&quot;/g, '"')
+        .replace(/&amp;/g, '&');
+}
+/** Decode a numeric entity's code point, leaving an out-of-range/invalid value
+ *  untouched (return empty) rather than throwing. */
+function safeFromCodePoint(cp) {
+    if (!Number.isFinite(cp) || cp < 0 || cp > 0x10ffff)
+        return '';
+    try {
+        return String.fromCodePoint(cp);
+    }
+    catch {
+        return '';
+    }
+}
+export function truncate(s, n) {
+    return s.length <= n ? s : s.slice(0, n) + '…';
+}
+//# sourceMappingURL=html.js.map

package/dist/channel/html.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"html.js","sourceRoot":"","sources":["../../src/channel/html.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAGtD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,YAAY,CAAC,IAAmB;IAC9C,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,IAAI,CAAC,YAAY;QAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IACrD,IAAI,IAAI,CAAC,IAAI;QAAE,KAAK,CAAC,IAAI,CAAC,sBAAsB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IAC7D,+DAA+D;IAC/D,sEAAsE;IACtE,wEAAwE;IACxE,qEAAqE;IACrE,IAAI,IAAI,CAAC,QAAQ;QAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC7C,IAAI,IAAI,CAAC,SAAS;QAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAC/C,OAAO,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AAC5B,CAAC;AAED;;;;;;;gFAOgF;AAChF,MAAM,UAAU,SAAS,CAAC,IAAY;IACpC,OAAO,IAAI;SACR,OAAO,CAAC,mBAAmB,EAAE,EAAE,CAAC;SAChC,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC,EAAE,GAAW,EAAE,EAAE,CAAC,iBAAiB,CAAC,QAAQ,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,CAAC;SAC9E,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAAC,EAAE,GAAW,EAAE,EAAE,CAAC,iBAAiB,CAAC,QAAQ,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,CAAC;SACtF,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC;SACrB,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC;SACrB,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC;SACvB,OAAO,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;AAC5B,CAAC;AAED;qDACqD;AACrD,SAAS,iBAAiB,CAAC,EAAU;IACnC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,GAAG,QAAQ;QAAE,OAAO,EAAE,CAAC;IAC/D,IAAI,CAAC;QACH,OAAO,MAAM,CAAC,aAAa,CAAC,EAAE,CAAC,CAAC;IAClC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,CAAS,EAAE,CAAS;IAC3C,OAAO,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,GAAG,CAAC;AACjD,CAAC"}

package/dist/channel/pairing-handler.d.ts

@@ -0,0 +1,66 @@
+import type { Bot, Context } from 'grammy';
+import type { VaultStore } from '@moxxy/plugin-vault';
+import { type PairingState } from '../pairing.js';
+/** Result returned by `confirmChatCode`. */
+export type PairingConfirmResult = {
+    ok: true;
+    chatId: number;
+} | {
+    ok: false;
+    reason: 'mismatch' | 'expired' | 'not-pending' | 'no-window';
+    message: string;
+};
+export interface PairingHandlerOptions {
+    readonly vault: VaultStore;
+    readonly logger?: {
+        info?(msg: string, meta?: Record<string, unknown>): void;
+        warn(msg: string, meta?: Record<string, unknown>): void;
+    };
+}
+/**
+ * Owns the pairing state machine + the bot-side `/start` handler for the
+ * host-issued QR pairing flow (see {@link beginHostWindow}). Keeps the bot
+ * reference (re-)settable so the TelegramChannel can wire it up after
+ * construction.
+ */
+export declare class PairingHandler {
+    private state;
+    private bot;
+    private readonly opts;
+    private readonly pairedListeners;
+    constructor(opts: PairingHandlerOptions);
+    attachBot(bot: Bot | null): void;
+    loadAuthorized(): Promise<void>;
+    isAuthorized(chatId: number): boolean;
+    phase(): PairingState['phase'];
+    /**
+     * Open a host-issued pairing window and return the code to embed in the
+     * `t.me/<bot>?start=<code>` deep link / QR the control surface renders. The
+     * user proves ownership by presenting THIS code back to the bot (deep-link tap
+     * or a plain message), which `handleStartCommand` / `confirmChatCode`
+     * validate. Returns the generated code.
+     */
+    beginHostWindow(): string;
+    unpair(): void;
+    /**
+     * Subscribe to "a chat just became authorized" — fires once each time pairing
+     * completes. The channel uses this to publish its "connected" connect-state so
+     * a watching control surface can swap the QR for a "✓ Connected" affordance,
+     * and the `pair` terminal command uses it to know pairing finished. Returns an
+     * unsubscribe function.
+     */
+    onPaired(listener: (chatId: number) => void): () => void;
+    /**
+     * A chat presented a code (deep-link `/start <code>` payload or a plain 6-digit
+     * message). On match the chat is authorized, persisted to the vault, and
+     * greeted. Returns a structured result the caller can branch on.
+     */
+    confirmChatCode(chatId: number, rawCode: string): Promise<PairingConfirmResult>;
+    /** Persist + greet + notify on a 'paired' decision; map every decision kind to
+     *  a {@link PairingConfirmResult}. */
+    private applyConfirmDecision;
+    private emitPaired;
+    /** Bot-side `/start` handler. */
+    handleStartCommand(ctx: Context): Promise<void>;
+}
+//# sourceMappingURL=pairing-handler.d.ts.map

package/dist/channel/pairing-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pairing-handler.d.ts","sourceRoot":"","sources":["../../src/channel/pairing-handler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAC3C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAQL,KAAK,YAAY,EAClB,MAAM,eAAe,CAAC;AAKvB,4CAA4C;AAC5C,MAAM,MAAM,oBAAoB,GAC5B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC5B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,UAAU,GAAG,SAAS,GAAG,aAAa,GAAG,WAAW,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjG,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE;QAChB,IAAI,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;QACzD,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;KACzD,CAAC;CACH;AAED;;;;;GAKG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,KAAK,CAAsC;IACnD,OAAO,CAAC,GAAG,CAAoB;IAC/B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAwB;IAC7C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAuC;gBAE3D,IAAI,EAAE,qBAAqB;IAIvC,SAAS,CAAC,GAAG,EAAE,GAAG,GAAG,IAAI,GAAG,IAAI;IAI1B,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC;IAWrC,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAIrC,KAAK,IAAI,YAAY,CAAC,OAAO,CAAC;IAI9B;;;;;;OAMG;IACH,eAAe,IAAI,MAAM;IAMzB,MAAM,IAAI,IAAI;IAId;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI;IAKxD;;;;OAIG;IACG,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAKrF;0CACsC;YACxB,oBAAoB;IA4BlC,OAAO,CAAC,UAAU;IAUlB,iCAAiC;IAC3B,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;CAgCtD"}

package/dist/channel/pairing-handler.js

@@ -0,0 +1,147 @@
+import { beginHostIssuedPairing, clearPairing, createPairingState, handleStart, isAuthorized, submitChatCode, } from '../pairing.js';
+import { parseChatId, TELEGRAM_AUTHORIZED_CHAT_KEY } from '../keys.js';
+const AUTHORIZED_CHAT_KEY = TELEGRAM_AUTHORIZED_CHAT_KEY;
+/**
+ * Owns the pairing state machine + the bot-side `/start` handler for the
+ * host-issued QR pairing flow (see {@link beginHostWindow}). Keeps the bot
+ * reference (re-)settable so the TelegramChannel can wire it up after
+ * construction.
+ */
+export class PairingHandler {
+    state = createPairingState();
+    bot = null;
+    opts;
+    pairedListeners = new Set();
+    constructor(opts) {
+        this.opts = opts;
+    }
+    attachBot(bot) {
+        this.bot = bot;
+    }
+    async loadAuthorized() {
+        const authorizedRaw = await this.opts.vault.get(AUTHORIZED_CHAT_KEY);
+        const authorizedChatId = parseChatId(authorizedRaw);
+        if (authorizedChatId == null && authorizedRaw) {
+            this.opts.logger?.warn('telegram pairing: stored chat id is not a number — treating as unpaired', {
+                raw: authorizedRaw,
+            });
+        }
+        this.state = createPairingState({ authorizedChatId });
+    }
+    isAuthorized(chatId) {
+        return isAuthorized(this.state, chatId);
+    }
+    phase() {
+        return this.state.phase;
+    }
+    /**
+     * Open a host-issued pairing window and return the code to embed in the
+     * `t.me/<bot>?start=<code>` deep link / QR the control surface renders. The
+     * user proves ownership by presenting THIS code back to the bot (deep-link tap
+     * or a plain message), which `handleStartCommand` / `confirmChatCode`
+     * validate. Returns the generated code.
+     */
+    beginHostWindow() {
+        const { state, code } = beginHostIssuedPairing(this.state);
+        this.state = state;
+        return code;
+    }
+    unpair() {
+        this.state = clearPairing(this.state);
+    }
+    /**
+     * Subscribe to "a chat just became authorized" — fires once each time pairing
+     * completes. The channel uses this to publish its "connected" connect-state so
+     * a watching control surface can swap the QR for a "✓ Connected" affordance,
+     * and the `pair` terminal command uses it to know pairing finished. Returns an
+     * unsubscribe function.
+     */
+    onPaired(listener) {
+        this.pairedListeners.add(listener);
+        return () => this.pairedListeners.delete(listener);
+    }
+    /**
+     * A chat presented a code (deep-link `/start <code>` payload or a plain 6-digit
+     * message). On match the chat is authorized, persisted to the vault, and
+     * greeted. Returns a structured result the caller can branch on.
+     */
+    async confirmChatCode(chatId, rawCode) {
+        const decision = submitChatCode(this.state, chatId, rawCode);
+        return this.applyConfirmDecision(decision);
+    }
+    /** Persist + greet + notify on a 'paired' decision; map every decision kind to
+     *  a {@link PairingConfirmResult}. */
+    async applyConfirmDecision(decision) {
+        this.state = decision.state;
+        const action = decision.action;
+        if (action.kind === 'paired') {
+            await this.opts.vault.set(AUTHORIZED_CHAT_KEY, String(action.chatId));
+            // Greet the chat that just got authorized so the user has a confirmation
+            // on the Telegram side too — symmetric with the success the surface shows.
+            if (this.bot) {
+                try {
+                    await this.bot.api.sendMessage(action.chatId, '✅ Paired with moxxy. Send a prompt to begin.');
+                }
+                catch (err) {
+                    this.opts.logger?.warn('pairing: greeting send failed', { err: String(err) });
+                }
+            }
+            this.emitPaired(action.chatId);
+            return { ok: true, chatId: action.chatId };
+        }
+        if (action.kind === 'still-paired')
+            return { ok: true, chatId: action.chatId };
+        if (action.kind === 'mismatch')
+            return { ok: false, reason: 'mismatch', message: action.message };
+        if (action.kind === 'expired')
+            return { ok: false, reason: 'expired', message: action.message };
+        if (action.kind === 'not-pending')
+            return { ok: false, reason: 'not-pending', message: action.message };
+        if (action.kind === 'reject')
+            return { ok: false, reason: 'not-pending', message: action.message };
+        return { ok: false, reason: 'mismatch', message: 'unexpected pairing state' };
+    }
+    emitPaired(chatId) {
+        for (const listener of this.pairedListeners) {
+            try {
+                listener(chatId);
+            }
+            catch (err) {
+                this.opts.logger?.warn('pairing paired-listener threw', { err: String(err) });
+            }
+        }
+    }
+    /** Bot-side `/start` handler. */
+    async handleStartCommand(ctx) {
+        const chatId = ctx.chat?.id;
+        if (!chatId)
+            return;
+        // Host-issued direction: the deep link the user scanned carries the code as
+        // the /start payload (grammy exposes it as `ctx.match`). Validate it here so
+        // "scan QR → tap START → paired" needs no typing. A bare /start (no payload —
+        // e.g. the user opened the chat manually) falls through to `handleStart`,
+        // which nudges them to use the link or send the digits (the message handler
+        // also accepts a bare 6-digit code).
+        if (this.state.phase === 'awaiting-host-code') {
+            const payload = typeof ctx.match === 'string' ? ctx.match.trim() : '';
+            if (payload) {
+                const result = await this.confirmChatCode(chatId, payload);
+                if (!result.ok && result.reason !== 'not-pending') {
+                    await ctx.reply(result.message);
+                }
+                return;
+            }
+        }
+        const decision = handleStart(this.state, chatId);
+        this.state = decision.state;
+        const action = decision.action;
+        if (action.kind === 'still-paired') {
+            await ctx.reply('Welcome back! Send me a prompt.');
+            return;
+        }
+        if (action.kind === 'reject' || action.kind === 'expired') {
+            await ctx.reply(action.message);
+        }
+    }
+}
+//# sourceMappingURL=pairing-handler.js.map

package/dist/channel/pairing-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pairing-handler.js","sourceRoot":"","sources":["../../src/channel/pairing-handler.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,sBAAsB,EACtB,YAAY,EACZ,kBAAkB,EAClB,WAAW,EACX,YAAY,EACZ,cAAc,GAGf,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,WAAW,EAAE,4BAA4B,EAAE,MAAM,YAAY,CAAC;AAEvE,MAAM,mBAAmB,GAAG,4BAA4B,CAAC;AAezD;;;;;GAKG;AACH,MAAM,OAAO,cAAc;IACjB,KAAK,GAAiB,kBAAkB,EAAE,CAAC;IAC3C,GAAG,GAAe,IAAI,CAAC;IACd,IAAI,CAAwB;IAC5B,eAAe,GAAG,IAAI,GAAG,EAA4B,CAAC;IAEvE,YAAY,IAA2B;QACrC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;IAED,SAAS,CAAC,GAAe;QACvB,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;IACjB,CAAC;IAED,KAAK,CAAC,cAAc;QAClB,MAAM,aAAa,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAC;QACrE,MAAM,gBAAgB,GAAG,WAAW,CAAC,aAAa,CAAC,CAAC;QACpD,IAAI,gBAAgB,IAAI,IAAI,IAAI,aAAa,EAAE,CAAC;YAC9C,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,yEAAyE,EAAE;gBAChG,GAAG,EAAE,aAAa;aACnB,CAAC,CAAC;QACL,CAAC;QACD,IAAI,CAAC,KAAK,GAAG,kBAAkB,CAAC,EAAE,gBAAgB,EAAE,CAAC,CAAC;IACxD,CAAC;IAED,YAAY,CAAC,MAAc;QACzB,OAAO,YAAY,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IAC1C,CAAC;IAED,KAAK;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC;IAC1B,CAAC;IAED;;;;;;OAMG;IACH,eAAe;QACb,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,sBAAsB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC3D,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM;QACJ,IAAI,CAAC,KAAK,GAAG,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACxC,CAAC;IAED;;;;;;OAMG;IACH,QAAQ,CAAC,QAAkC;QACzC,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACnC,OAAO,GAAG,EAAE,CAAC,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IACrD,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,eAAe,CAAC,MAAc,EAAE,OAAe;QACnD,MAAM,QAAQ,GAAG,cAAc,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;QAC7D,OAAO,IAAI,CAAC,oBAAoB,CAAC,QAAQ,CAAC,CAAC;IAC7C,CAAC;IAED;0CACsC;IAC9B,KAAK,CAAC,oBAAoB,CAAC,QAAyB;QAC1D,IAAI,CAAC,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC;QAC5B,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC;QAC/B,IAAI,MAAM,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC7B,MAAM,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,mBAAmB,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;YACtE,yEAAyE;YACzE,2EAA2E;YAC3E,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;gBACb,IAAI,CAAC;oBACH,MAAM,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,WAAW,CAC5B,MAAM,CAAC,MAAM,EACb,8CAA8C,CAC/C,CAAC;gBACJ,CAAC;gBAAC,OAAO,GAAG,EAAE,CAAC;oBACb,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,+BAA+B,EAAE,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;gBAChF,CAAC;YACH,CAAC;YACD,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YAC/B,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC;QAC7C,CAAC;QACD,IAAI,MAAM,CAAC,IAAI,KAAK,cAAc;YAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC;QAC/E,IAAI,MAAM,CAAC,IAAI,KAAK,UAAU;YAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC;QAClG,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS;YAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC;QAChG,IAAI,MAAM,CAAC,IAAI,KAAK,aAAa;YAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC;QACxG,IAAI,MAAM,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC;QACnG,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,0BAA0B,EAAE,CAAC;IAChF,CAAC;IAEO,UAAU,CAAC,MAAc;QAC/B,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,eAAe,EAAE,CAAC;YAC5C,IAAI,CAAC;gBACH,QAAQ,CAAC,MAAM,CAAC,CAAC;YACnB,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,+BAA+B,EAAE,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAChF,CAAC;QACH,CAAC;IACH,CAAC;IAED,iCAAiC;IACjC,KAAK,CAAC,kBAAkB,CAAC,GAAY;QACnC,MAAM,MAAM,GAAG,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC;QAC5B,IAAI,CAAC,MAAM;YAAE,OAAO;QAEpB,4EAA4E;QAC5E,6EAA6E;QAC7E,8EAA8E;QAC9E,0EAA0E;QAC1E,4EAA4E;QAC5E,qCAAqC;QACrC,IAAI,IAAI,CAAC,KAAK,CAAC,KAAK,KAAK,oBAAoB,EAAE,CAAC;YAC9C,MAAM,OAAO,GAAG,OAAO,GAAG,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACtE,IAAI,OAAO,EAAE,CAAC;gBACZ,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,eAAe,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;gBAC3D,IAAI,CAAC,MAAM,CAAC,EAAE,IAAI,MAAM,CAAC,MAAM,KAAK,aAAa,EAAE,CAAC;oBAClD,MAAM,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;gBAClC,CAAC;gBACD,OAAO;YACT,CAAC;QACH,CAAC;QAED,MAAM,QAAQ,GAAoB,WAAW,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;QAClE,IAAI,CAAC,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC;QAC5B,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC;QAC/B,IAAI,MAAM,CAAC,IAAI,KAAK,cAAc,EAAE,CAAC;YACnC,MAAM,GAAG,CAAC,KAAK,CAAC,iCAAiC,CAAC,CAAC;YACnD,OAAO;QACT,CAAC;QACD,IAAI,MAAM,CAAC,IAAI,KAAK,QAAQ,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;YAC1D,MAAM,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAClC,CAAC;IACH,CAAC;CACF"}

package/dist/channel/permission-prompt.d.ts

@@ -0,0 +1,21 @@
+import { type Bot } from 'grammy';
+import type { PendingToolCall, PermissionContext } from '@moxxy/sdk';
+import type { ClientSession as Session } from '@moxxy/sdk';
+import type { TelegramPermissionResolver } from '../permission.js';
+export interface PermissionPromptDeps {
+    readonly bot: Bot | null;
+    readonly chatId: number | null;
+    readonly session: Session | null;
+    readonly resolver: TelegramPermissionResolver;
+    readonly yolo: boolean;
+    readonly logger?: {
+        warn(msg: string, meta?: Record<string, unknown>): void;
+    };
+}
+/**
+ * Render an inline-keyboard permission prompt for a pending tool call.
+ * The decider promise resolves when the user clicks a button (routed
+ * back via the callback handler) or when the resolver aborts on stop.
+ */
+export declare function askForPermission(call: PendingToolCall, ctx: PermissionContext, deps: PermissionPromptDeps): Promise<void>;
+//# sourceMappingURL=permission-prompt.d.ts.map

package/dist/channel/permission-prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permission-prompt.d.ts","sourceRoot":"","sources":["../../src/channel/permission-prompt.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,GAAG,EAAkB,MAAM,QAAQ,CAAC;AAClD,OAAO,KAAK,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AACrE,OAAO,KAAK,EAAE,aAAa,IAAI,OAAO,EAAE,MAAM,YAAY,CAAC;AAC3D,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,kBAAkB,CAAC;AAGnE,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,GAAG,EAAE,GAAG,GAAG,IAAI,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,QAAQ,EAAE,0BAA0B,CAAC;IAC9C,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE;QAAE,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;KAAE,CAAC;CAC/E;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,eAAe,EACrB,GAAG,EAAE,iBAAiB,EACtB,IAAI,EAAE,oBAAoB,GACzB,OAAO,CAAC,IAAI,CAAC,CA0Bf"}

package/dist/channel/permission-prompt.js

@@ -0,0 +1,36 @@
+import { InlineKeyboard } from 'grammy';
+import { truncate } from './html.js';
+/**
+ * Render an inline-keyboard permission prompt for a pending tool call.
+ * The decider promise resolves when the user clicks a button (routed
+ * back via the callback handler) or when the resolver aborts on stop.
+ */
+export async function askForPermission(call, ctx, deps) {
+    if (!deps.bot || !deps.chatId || !deps.session)
+        return;
+    void ctx;
+    // YOLO short-circuit: resolve immediately without rendering a prompt.
+    // Mirrors the TUI's `/yolo` flag — once set, every tool call passes.
+    if (deps.yolo) {
+        deps.resolver.resolvePending(call.callId, { mode: 'allow', reason: 'yolo mode' });
+        return;
+    }
+    const keyboard = new InlineKeyboard()
+        .text('Allow once', `perm:${call.callId}:allow`)
+        .text('Allow session', `perm:${call.callId}:allow_session`)
+        .row()
+        .text('Deny', `perm:${call.callId}:deny`);
+    const description = deps.session.tools.get(call.name)?.description ?? '';
+    const summary = `🔐 Tool permission requested\n` +
+        `Tool: ${call.name}\n` +
+        (description ? `Desc: ${description}\n` : '') +
+        `Input: ${truncate(JSON.stringify(call.input), 300)}`;
+    try {
+        await deps.bot.api.sendMessage(deps.chatId, summary, { reply_markup: keyboard });
+    }
+    catch (err) {
+        deps.logger?.warn('permission send failed', { err: String(err) });
+        deps.resolver.resolvePending(call.callId, { mode: 'deny', reason: 'unable to render prompt' });
+    }
+}
+//# sourceMappingURL=permission-prompt.js.map

package/dist/channel/permission-prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"permission-prompt.js","sourceRoot":"","sources":["../../src/channel/permission-prompt.ts"],"names":[],"mappings":"AAAA,OAAO,EAAY,cAAc,EAAE,MAAM,QAAQ,CAAC;AAIlD,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAWrC;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,IAAqB,EACrB,GAAsB,EACtB,IAA0B;IAE1B,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,OAAO;QAAE,OAAO;IACvD,KAAK,GAAG,CAAC;IACT,sEAAsE;IACtE,qEAAqE;IACrE,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;QACd,IAAI,CAAC,QAAQ,CAAC,cAAc,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC,CAAC;QAClF,OAAO;IACT,CAAC;IACD,MAAM,QAAQ,GAAG,IAAI,cAAc,EAAE;SAClC,IAAI,CAAC,YAAY,EAAE,QAAQ,IAAI,CAAC,MAAM,QAAQ,CAAC;SAC/C,IAAI,CAAC,eAAe,EAAE,QAAQ,IAAI,CAAC,MAAM,gBAAgB,CAAC;SAC1D,GAAG,EAAE;SACL,IAAI,CAAC,MAAM,EAAE,QAAQ,IAAI,CAAC,MAAM,OAAO,CAAC,CAAC;IAC5C,MAAM,WAAW,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,WAAW,IAAI,EAAE,CAAC;IACzE,MAAM,OAAO,GACX,gCAAgC;QAChC,SAAS,IAAI,CAAC,IAAI,IAAI;QACtB,CAAC,WAAW,CAAC,CAAC,CAAC,SAAS,WAAW,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7C,UAAU,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC;IACxD,IAAI,CAAC;QACH,MAAM,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,WAAW,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,EAAE,YAAY,EAAE,QAAQ,EAAE,CAAC,CAAC;IACnF,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,wBAAwB,EAAE,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAClE,IAAI,CAAC,QAAQ,CAAC,cAAc,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,yBAAyB,EAAE,CAAC,CAAC;IACjG,CAAC;AACH,CAAC"}

package/dist/channel/slash-handler.d.ts

@@ -0,0 +1,47 @@
+import { type Bot, type Context } from 'grammy';
+import type { ClientSession as Session } from '@moxxy/sdk';
+/**
+ * Install guidance shown when enabling `/voice` with no active synthesizer —
+ * mirrors the voice-handler's transcriber guidance wording, pointing at the TTS
+ * plugin instead of the STT one.
+ */
+export declare const VOICE_NO_SYNTH_HINT = "No text-to-speech backend is configured yet, so replies stay text-only. Install one with `moxxy plugins install tts-openai` and run `moxxy login openai` (or set OPENAI_API_KEY) to enable spoken replies.";
+export interface SlashState {
+    readonly session: Session | null;
+    readonly model: string | undefined;
+    readonly activeModelOverride: string | null;
+    readonly yolo: boolean;
+    /** Whether voice replies are currently enabled (backs `/voice status`). */
+    readonly voiceReplies: boolean;
+}
+export interface SlashCallbacks {
+    /** Toggle yolo and return its new value (so we can echo the right message). */
+    toggleYolo(): boolean;
+    /** Persist + apply the voice-replies preference (backs `/voice on|off`). */
+    setVoiceReplies(on: boolean): Promise<void>;
+    /** Apply a `session-action` result emitted from a registered command. */
+    performSessionAction(ctx: Context, action: 'new' | 'clear' | 'exit', notice: string | undefined): Promise<void>;
+}
+/**
+ * Slash-command dispatcher for the Telegram channel.
+ *
+ * First tries the shared `session.commands` registry — this is where
+ * the universal commands (/info, /clear, /new, /exit, /help) live, so
+ * Telegram gets them for free alongside any plugin-contributed
+ * commands without needing a switch case here.
+ *
+ * Falls through to channel-local cases for Telegram-specific UI
+ * (model/loop pickers as inline keyboards, /yolo toggle, /tools and
+ * /skills as text dumps).
+ */
+export declare function runSlash(ctx: Context, text: string, state: SlashState, cb: SlashCallbacks): Promise<void>;
+/**
+ * Push the union of registry commands + Telegram-local commands to
+ * Telegram so they appear in the chat's command menu (the "/" picker
+ * the official client shows). Best-effort: a network failure here
+ * doesn't block channel startup, the commands still work via text.
+ */
+export declare function publishBotCommands(bot: Bot | null, session: Session | null, logger?: {
+    warn?(msg: string, meta?: Record<string, unknown>): void;
+}): Promise<void>;
+//# sourceMappingURL=slash-handler.d.ts.map

package/dist/channel/slash-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slash-handler.d.ts","sourceRoot":"","sources":["../../src/channel/slash-handler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,GAAG,EAAE,KAAK,OAAO,EAAkB,MAAM,QAAQ,CAAC;AAEhE,OAAO,KAAK,EAAE,aAAa,IAAI,OAAO,EAAE,MAAM,YAAY,CAAC;AAG3D;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,+MAC8K,CAAC;AAE/M,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5C,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,2EAA2E;IAC3E,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;CAChC;AAED,MAAM,WAAW,cAAc;IAC7B,+EAA+E;IAC/E,UAAU,IAAI,OAAO,CAAC;IACtB,4EAA4E;IAC5E,eAAe,CAAC,EAAE,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5C,yEAAyE;IACzE,oBAAoB,CAClB,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE,KAAK,GAAG,OAAO,GAAG,MAAM,EAChC,MAAM,EAAE,MAAM,GAAG,SAAS,GACzB,OAAO,CAAC,IAAI,CAAC,CAAC;CAClB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,QAAQ,CAC5B,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,UAAU,EACjB,EAAE,EAAE,cAAc,GACjB,OAAO,CAAC,IAAI,CAAC,CAsFf;AAiFD;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,GAAG,GAAG,IAAI,EACf,OAAO,EAAE,OAAO,GAAG,IAAI,EACvB,MAAM,CAAC,EAAE;IAAE,IAAI,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;CAAE,GACpE,OAAO,CAAC,IAAI,CAAC,CA6Bf"}