charness 3.6.1 → 3.8.0

package/dist/connectors/telegram/botApiConnection.d.ts

@@ -0,0 +1,74 @@
+/**
+ * @description The connections the bot keeps pooled to the Bot API, and what happens when the server closed one the bot
+ * still held.
+ *
+ * The bot keeps its connections alive and reuses them. A server closes an idle one after a while; a client that learns
+ * of it only when it writes its next request (a process starved of CPU, whose event loop has not yet read the close)
+ * gets «socket hang up» / `ECONNRESET` / `EPIPE` for a request the closed connection never delivered. Two layers:
+ *
+ *  1. The agent closes a connection that sat idle in the pool for {@link botApiFreeSocketTimeoutMs} itself, long before
+ *     the server's own idle limit (api.telegram.org kept an idle HTTP/1.1 connection for more than 130 s when measured),
+ *     so an ordinary pause between two sends never meets a connection the server closed. A client stalled past the
+ *     server's limit cannot be helped that way: its timers do not run either, and the stale connection is still in the
+ *     pool when the next request starts. What it meets then depends on the Node: since 22.23.4 the http agent looks for
+ *     what the server already sent on an idle socket before it reuses it («http: ensure agent data guard works without I/O»,
+ *     CVE-2026-105481) and opens a fresh connection; an older Node (`engines` allows 22.12) writes onto the closed one.
+ *  2. {@link wireBotApiClient} makes a client send such a request again ONCE, on a fresh connection — the case of those older
+ *     agents, and on every Node the one of a server that closes the connection as the request is on its way, which no
+ *     client sees coming. It does so only when
+ *     the request rode a REUSED connection (`ClientRequest.reusedSocket`, the signal Node documents for exactly this) and
+ *     the connection failed at once ({@link staleConnectionFailureWindowMs}) with the socket having read not a single byte
+ *     since the reuse: no answer began, not even a partial one, and the server did not sit on the request. A timeout, an
+ *     abort, an answer that began, a failure that came late and a first-time connection are never retried.
+ *
+ * This is a heuristic, not a guarantee. A server that took the request and dropped the connection at once, before a byte of
+ * its answer, looks the same to the client, and there the retry posts the message twice. That case is rare; the alternative
+ * is losing the message every time a pooled connection had been closed.
+ */
+import * as http from 'http';
+import * as https from 'https';
+import type { CallApiHost } from '../../outputTrace';
+/**
+ * @description How long a connection may idle in the pool before the agent closes it. Well under the server's own limit
+ * (the real Bot API held an idle HTTP/1.1 connection for more than 130 s when measured, and sends no `Keep-Alive` hint),
+ * long enough to span the pauses between a topic's sends and the typing indicator, so a streaming reply keeps its warm
+ * connection.
+ *
+ * It is a socket idle timeout, applied by Node only to FREE sockets (`http.Agent` destroys a socket on `timeout` only if
+ * it sits in the free list): a long poll that waits 50 s for an update is not cut.
+ */
+export declare const botApiFreeSocketTimeoutMs = 30000;
+/**
+ * @description How soon after a pooled connection was handed to a request its failure still counts as "the server had
+ * closed it". A closed connection fails within one turn of the event loop of the write — milliseconds, a second on a host
+ * that is starved of CPU —, while a server that took the request, worked on it for long and then dropped the connection
+ * (a slow send under load, a media group, a middlebox) fails later: that request is not retried.
+ */
+export declare const staleConnectionFailureWindowMs = 1000;
+/** The log line of a retry: `<prefix> (<method>): …`. Never carries the bot token. */
+export declare const reusedConnectionRetryLogPrefix = "[telegram] pooled connection was closed by the server, retrying once on a fresh one";
+/**
+ * @description The keep-alive, IPv4-pinned `https.Agent` the Bot API client and the file downloads ride: a warm
+ * connection avoids the cold-handshake stall.
+ */
+export declare function createBotApiHttpsAgent(freeSocketTimeoutMs?: number): https.Agent;
+/**
+ * @description The same pooling for an `http://` API root (the process-level tests' fake on loopback): Telegraf drops its
+ * agent for such a root and node-fetch then falls back to the global agent, which has other limits.
+ */
+export declare function createBotApiHttpAgent(freeSocketTimeoutMs?: number): http.Agent;
+/** A Telegraf `Telegram` client, as far as the wiring needs it. */
+export interface BotApiClient extends CallApiHost {
+    readonly options: {
+        agent?: http.Agent;
+    };
+}
+/**
+ * @description Put the bot's pooling on a Telegraf client: its agent (Telegraf drops the agent of an `http://` root, and
+ * builds every client from options that already lack it) and the retry of a request that met a closed pooled connection.
+ * Telegraf builds a NEW client for every update (`ctx.telegram`, behind `ctx.reply` / `ctx.answerCbQuery` /
+ * `ctx.editMessageText`), so this runs once for `bot.telegram` and once per update for `ctx.telegram`. For `bot.telegram`
+ * call it AFTER the output trace wrap, so the trace records both attempts of a retried request.
+ */
+export declare function wireBotApiClient(telegram: BotApiClient, agent: http.Agent): void;
+//# sourceMappingURL=botApiConnection.d.ts.map

package/dist/connectors/telegram/botApiConnection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"botApiConnection.d.ts","sourceRoot":"","sources":["../../../src/connectors/telegram/botApiConnection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAC7B,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAK/B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGrD;;;;;;;;GAQG;AACH,eAAO,MAAM,yBAAyB,QAAS,CAAC;AAKhD;;;;;GAKG;AACH,eAAO,MAAM,8BAA8B,OAAO,CAAC;AAEnD,sFAAsF;AACtF,eAAO,MAAM,8BAA8B,wFAAwF,CAAC;AAkDpI;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,mBAAmB,GAAE,MAAkC,GAAG,KAAK,CAAC,KAAK,CAE3G;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,mBAAmB,GAAE,MAAkC,GAAG,IAAI,CAAC,KAAK,CAEzG;AA0CD,mEAAmE;AACnE,MAAM,WAAW,YAAa,SAAQ,WAAW;IAC/C,QAAQ,CAAC,OAAO,EAAE;QAAE,KAAK,CAAC,EAAE,IAAI,CAAC,KAAK,CAAA;KAAE,CAAC;CAC1C;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,YAAY,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,GAAG,IAAI,CAGhF"}

package/dist/connectors/telegram/botApiConnection.js

@@ -0,0 +1,201 @@
+"use strict";
+/**
+ * @description The connections the bot keeps pooled to the Bot API, and what happens when the server closed one the bot
+ * still held.
+ *
+ * The bot keeps its connections alive and reuses them. A server closes an idle one after a while; a client that learns
+ * of it only when it writes its next request (a process starved of CPU, whose event loop has not yet read the close)
+ * gets «socket hang up» / `ECONNRESET` / `EPIPE` for a request the closed connection never delivered. Two layers:
+ *
+ *  1. The agent closes a connection that sat idle in the pool for {@link botApiFreeSocketTimeoutMs} itself, long before
+ *     the server's own idle limit (api.telegram.org kept an idle HTTP/1.1 connection for more than 130 s when measured),
+ *     so an ordinary pause between two sends never meets a connection the server closed. A client stalled past the
+ *     server's limit cannot be helped that way: its timers do not run either, and the stale connection is still in the
+ *     pool when the next request starts. What it meets then depends on the Node: since 22.23.4 the http agent looks for
+ *     what the server already sent on an idle socket before it reuses it («http: ensure agent data guard works without I/O»,
+ *     CVE-2026-105481) and opens a fresh connection; an older Node (`engines` allows 22.12) writes onto the closed one.
+ *  2. {@link wireBotApiClient} makes a client send such a request again ONCE, on a fresh connection — the case of those older
+ *     agents, and on every Node the one of a server that closes the connection as the request is on its way, which no
+ *     client sees coming. It does so only when
+ *     the request rode a REUSED connection (`ClientRequest.reusedSocket`, the signal Node documents for exactly this) and
+ *     the connection failed at once ({@link staleConnectionFailureWindowMs}) with the socket having read not a single byte
+ *     since the reuse: no answer began, not even a partial one, and the server did not sit on the request. A timeout, an
+ *     abort, an answer that began, a failure that came late and a first-time connection are never retried.
+ *
+ * This is a heuristic, not a guarantee. A server that took the request and dropped the connection at once, before a byte of
+ * its answer, looks the same to the client, and there the retry posts the message twice. That case is rare; the alternative
+ * is losing the message every time a pooled connection had been closed.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reusedConnectionRetryLogPrefix = exports.staleConnectionFailureWindowMs = exports.botApiFreeSocketTimeoutMs = void 0;
+exports.createBotApiHttpsAgent = createBotApiHttpsAgent;
+exports.createBotApiHttpAgent = createBotApiHttpAgent;
+exports.wireBotApiClient = wireBotApiClient;
+const http = __importStar(require("http"));
+const https = __importStar(require("https"));
+const async_hooks_1 = require("async_hooks");
+const net_1 = require("net");
+const perf_hooks_1 = require("perf_hooks");
+const stream_1 = require("stream");
+const sendErrorClassifier_1 = require("../../sendErrorClassifier");
+/**
+ * @description How long a connection may idle in the pool before the agent closes it. Well under the server's own limit
+ * (the real Bot API held an idle HTTP/1.1 connection for more than 130 s when measured, and sends no `Keep-Alive` hint),
+ * long enough to span the pauses between a topic's sends and the typing indicator, so a streaming reply keeps its warm
+ * connection.
+ *
+ * It is a socket idle timeout, applied by Node only to FREE sockets (`http.Agent` destroys a socket on `timeout` only if
+ * it sits in the free list): a long poll that waits 50 s for an update is not cut.
+ */
+exports.botApiFreeSocketTimeoutMs = 30_000;
+/** The initial delay of the TCP keep-alive probes on a pooled connection. */
+const tcpKeepAliveInitialDelayMs = 10_000;
+/**
+ * @description How soon after a pooled connection was handed to a request its failure still counts as "the server had
+ * closed it". A closed connection fails within one turn of the event loop of the write — milliseconds, a second on a host
+ * that is starved of CPU —, while a server that took the request, worked on it for long and then dropped the connection
+ * (a slow send under load, a media group, a middlebox) fails later: that request is not retried.
+ */
+exports.staleConnectionFailureWindowMs = 1000;
+/** The log line of a retry: `<prefix> (<method>): …`. Never carries the bot token. */
+exports.reusedConnectionRetryLogPrefix = '[telegram] pooled connection was closed by the server, retrying once on a fresh one';
+/** How deep a payload is searched for a one-shot stream (`{ media: [{ media: { source: stream } }] }` is the deepest shape). */
+const maxPayloadDepth = 5;
+/**
+ * The probe of the `callApi` that is running, handed to the agent through the async context: node-fetch sits between the
+ * two and keeps nothing of the request on the error it throws.
+ */
+const reuseProbeStorage = new async_hooks_1.AsyncLocalStorage();
+/**
+ * Mark the running `callApi`'s probe when this reused request fails at once ({@link staleConnectionFailureWindowMs}) with the
+ * socket having read nothing since the reuse. The socket's byte count, not the request's `response` event, is the test for
+ * "nothing": that event fires only once a whole response head is parsed, so a connection that delivered half a head — an
+ * answer that began — would pass for a closed one. `bytesRead` is the bytes of the application stream on a TLS socket too (a
+ * `close_notify` alert is not counted).
+ */
+function watchReusedRequest(socket, request) {
+    const probe = reuseProbeStorage.getStore();
+    if (!probe || !(socket instanceof net_1.Socket))
+        return;
+    const bytesReadAtReuse = socket.bytesRead;
+    const reusedAtMs = perf_hooks_1.performance.now();
+    request.once('error', () => {
+        const isAtOnce = perf_hooks_1.performance.now() - reusedAtMs <= exports.staleConnectionFailureWindowMs;
+        if (isAtOnce && socket.bytesRead === bytesReadAtReuse)
+            probe.isPooledConnectionLost = true;
+    });
+}
+/** `agent.reuseSocket` is called by Node, synchronously inside `http.request`, when a pooled socket is handed to a request. */
+function trackReusedConnections(agent) {
+    const reuseSocket = agent.reuseSocket.bind(agent);
+    agent.reuseSocket = (socket, request) => {
+        reuseSocket(socket, request);
+        watchReusedRequest(socket, request);
+    };
+    return agent;
+}
+/** The pooling both agents share. `freeSocketTimeoutMs` is a test seam; production keeps {@link botApiFreeSocketTimeoutMs}. */
+function getBotApiAgentOptions(freeSocketTimeoutMs) {
+    return { keepAlive: true, keepAliveMsecs: tcpKeepAliveInitialDelayMs, family: 4, timeout: freeSocketTimeoutMs };
+}
+/**
+ * @description The keep-alive, IPv4-pinned `https.Agent` the Bot API client and the file downloads ride: a warm
+ * connection avoids the cold-handshake stall.
+ */
+function createBotApiHttpsAgent(freeSocketTimeoutMs = exports.botApiFreeSocketTimeoutMs) {
+    return trackReusedConnections(new https.Agent(getBotApiAgentOptions(freeSocketTimeoutMs)));
+}
+/**
+ * @description The same pooling for an `http://` API root (the process-level tests' fake on loopback): Telegraf drops its
+ * agent for such a root and node-fetch then falls back to the global agent, which has other limits.
+ */
+function createBotApiHttpAgent(freeSocketTimeoutMs = exports.botApiFreeSocketTimeoutMs) {
+    return trackReusedConnections(new http.Agent(getBotApiAgentOptions(freeSocketTimeoutMs)));
+}
+/**
+ * A file handed to Telegraf as a stream can be read once: sending the payload again would upload what is left of it. Also
+ * skips a Buffer (its bytes are not walked) and bounds the walk.
+ */
+function checkIsPayloadReplayable(payload, depth = 0) {
+    if (payload instanceof stream_1.Readable)
+        return false;
+    if (ArrayBuffer.isView(payload) || depth >= maxPayloadDepth)
+        return true;
+    return Object.values(payload).every((value) => typeof value !== 'object' || value === null || checkIsPayloadReplayable(value, depth + 1));
+}
+/** Close every idle pooled connection: one that went stale was idle just as long as its siblings, so a retry must not meet another. */
+function destroyFreeSockets(agent) {
+    for (const sockets of Object.values(agent.freeSockets)) {
+        for (const socket of [...(sockets ?? [])])
+            socket.destroy();
+    }
+}
+/**
+ * Wrap `host.callApi` so a request that rode a reused connection and was dropped before any byte of an answer is sent again
+ * ONCE on a fresh connection (see the module description for what that does and does not guarantee). A second failure is the
+ * caller's, as before. `agent` is the one `host` sends through. Sits BELOW the send queue, the global pacer and the 429
+ * retry — the retry takes no permit, the thread's order is kept — and above the output trace, which therefore shows both
+ * attempts.
+ */
+function installReusedConnectionRetry(host, agent) {
+    const originalCallApi = host.callApi.bind(host);
+    host.callApi = async (method, payload, options) => {
+        const probe = { isPooledConnectionLost: false };
+        try {
+            return await reuseProbeStorage.run(probe, () => originalCallApi(method, payload, options));
+        }
+        catch (error) {
+            const isRetryable = probe.isPooledConnectionLost && (0, sendErrorClassifier_1.checkIsConnectionResetError)(error) && checkIsPayloadReplayable(payload);
+            if (!isRetryable)
+                throw error;
+            console.warn(`${exports.reusedConnectionRetryLogPrefix} (${method})`);
+            destroyFreeSockets(agent);
+            return originalCallApi(method, payload, options);
+        }
+    };
+}
+/**
+ * @description Put the bot's pooling on a Telegraf client: its agent (Telegraf drops the agent of an `http://` root, and
+ * builds every client from options that already lack it) and the retry of a request that met a closed pooled connection.
+ * Telegraf builds a NEW client for every update (`ctx.telegram`, behind `ctx.reply` / `ctx.answerCbQuery` /
+ * `ctx.editMessageText`), so this runs once for `bot.telegram` and once per update for `ctx.telegram`. For `bot.telegram`
+ * call it AFTER the output trace wrap, so the trace records both attempts of a retried request.
+ */
+function wireBotApiClient(telegram, agent) {
+    telegram.options.agent = agent;
+    installReusedConnectionRetry(telegram, agent);
+}
+//# sourceMappingURL=botApiConnection.js.map

package/dist/connectors/telegram/botApiConnection.js.map

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

package/dist/connectors/telegram/commands/botCore.d.ts

@@ -4,7 +4,7 @@
  * members it uses (`Pick<BotCore, …>`), and `bot.ts` builds the one object that satisfies them all.
  */
 import type { Context, NarrowedContext, Telegraf } from 'telegraf';
-import type { Message, Update } from 'telegraf/typings/core/types/typegram';
+import type { InlineKeyboardMarkup, Message, Update } from 'telegraf/typings/core/types/typegram';
 import type { InboundCommand } from '../../../platform/inbound';
 import type { SessionKey } from '../../../sessionKey';
 import type { StateStore } from '../../../state';
@@ -20,13 +20,23 @@ export interface BotCore {
      * getter each time a handler RUNS; a copy taken at registration would be `undefined`.
      */
     getState: () => StateStore;
-    /** Send into the topic (paced, tracked for `/clear_messages`); the sent message id, or `null` when the send failed. */
+    /**
+     * Send into the topic (paced, tracked for `/clear_messages`); the sent message id, or `null` when the send failed.
+     * `isSecret`: the text is a credential, the output trace records its length and nothing else.
+     */
     replyToThread: (key: SessionKey, text: string, extra?: object, options?: {
         unpaced?: boolean;
+        isSecret?: boolean;
     }) => Promise<number | null>;
     /** Edit a message of the topic in place; `false` when the edit failed. */
     editThreadMessage: (key: SessionKey, messageId: number, text: string, extra?: object) => Promise<boolean>;
-    deleteThreadMessage: (key: SessionKey, messageId: number) => Promise<void>;
+    /**
+     * Replace the inline keyboard of a message of the topic through the paced send queue (`null` removes it). A no-change
+     * edit is no failure; any other failure is logged under `logTag` and answered with `false`.
+     */
+    editThreadKeyboard: (key: SessionKey, messageId: number, keyboard: InlineKeyboardMarkup | null, logTag: string) => Promise<boolean>;
+    /** Delete a message of the topic; `false` when it stayed (older than 48 hours, already gone, not a topic of Telegram). */
+    deleteThreadMessage: (key: SessionKey, messageId: number) => Promise<boolean>;
     /** Gate a callback or message to an admin of the served group; the topic's key, or `null` when it is refused. */
     authoriseContext: (ctx: Context) => Promise<SessionKey | null>;
     /** Run `fn` with the topic's resolved locale for `t(…)`. */

package/dist/connectors/telegram/commands/botCore.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"botCore.d.ts","sourceRoot":"","sources":["../../../../src/connectors/telegram/commands/botCore.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACnE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,sCAAsC,CAAC;AAC5E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAEjD,gFAAgF;AAChF,MAAM,MAAM,cAAc,GAAG,eAAe,CAAC,OAAO,EAAE,MAAM,CAAC,aAAa,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC;AAEjG,wDAAwD;AACxD,MAAM,MAAM,eAAe,GAAG,CAC5B,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,EACvB,OAAO,EAAE,CAAC,GAAG,EAAE,cAAc,EAAE,GAAG,EAAE,UAAU,EAAE,MAAM,EAAE,cAAc,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,KAC5F,IAAI,CAAC;AAEV,MAAM,WAAW,OAAO;IACtB,GAAG,EAAE,QAAQ,CAAC;IACd,OAAO,EAAE,eAAe,CAAC;IACzB;;;OAGG;IACH,QAAQ,EAAE,MAAM,UAAU,CAAC;IAC3B,uHAAuH;IACvH,aAAa,EAAE,CAAC,GAAG,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC1H,0EAA0E;IAC1E,iBAAiB,EAAE,CAAC,GAAG,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC1G,mBAAmB,EAAE,CAAC,GAAG,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3E,iHAAiH;IACjH,gBAAgB,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;IAC/D,4DAA4D;IAC5D,gBAAgB,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,OAAO,KAAK,OAAO,CAAC;IAC3E,cAAc,EAAE,CAAC,GAAG,EAAE,UAAU,KAAK,OAAO,CAAC;IAC7C,4DAA4D;IAC5D,kBAAkB,EAAE,CAAC,GAAG,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACvD,6FAA6F;IAC7F,yBAAyB,EAAE,CAAC,GAAG,EAAE,UAAU,KAAK,IAAI,CAAC;IACrD;;;;OAIG;IACH,mBAAmB,EAAE,CAAC,GAAG,EAAE,UAAU,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CAClE"}
+{"version":3,"file":"botCore.d.ts","sourceRoot":"","sources":["../../../../src/connectors/telegram/commands/botCore.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACnE,OAAO,KAAK,EAAE,oBAAoB,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,sCAAsC,CAAC;AAClG,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAEjD,gFAAgF;AAChF,MAAM,MAAM,cAAc,GAAG,eAAe,CAAC,OAAO,EAAE,MAAM,CAAC,aAAa,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC;AAEjG,wDAAwD;AACxD,MAAM,MAAM,eAAe,GAAG,CAC5B,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,EACvB,OAAO,EAAE,CAAC,GAAG,EAAE,cAAc,EAAE,GAAG,EAAE,UAAU,EAAE,MAAM,EAAE,cAAc,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,KAC5F,IAAI,CAAC;AAEV,MAAM,WAAW,OAAO;IACtB,GAAG,EAAE,QAAQ,CAAC;IACd,OAAO,EAAE,eAAe,CAAC;IACzB;;;OAGG;IACH,QAAQ,EAAE,MAAM,UAAU,CAAC;IAC3B;;;OAGG;IACH,aAAa,EAAE,CAAC,GAAG,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC9I,0EAA0E;IAC1E,iBAAiB,EAAE,CAAC,GAAG,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC1G;;;OAGG;IACH,kBAAkB,EAAE,CAAC,GAAG,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,oBAAoB,GAAG,IAAI,EAAE,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACpI,0HAA0H;IAC1H,mBAAmB,EAAE,CAAC,GAAG,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9E,iHAAiH;IACjH,gBAAgB,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;IAC/D,4DAA4D;IAC5D,gBAAgB,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,OAAO,KAAK,OAAO,CAAC;IAC3E,cAAc,EAAE,CAAC,GAAG,EAAE,UAAU,KAAK,OAAO,CAAC;IAC7C,4DAA4D;IAC5D,kBAAkB,EAAE,CAAC,GAAG,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACvD,6FAA6F;IAC7F,yBAAyB,EAAE,CAAC,GAAG,EAAE,UAAU,KAAK,IAAI,CAAC;IACrD;;;;OAIG;IACH,mBAAmB,EAAE,CAAC,GAAG,EAAE,UAAU,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CAClE"}

package/dist/connectors/telegram/commands/botSkills.d.ts

@@ -0,0 +1,21 @@
+import type { SessionKey } from '../../../sessionKey';
+import type { BotSkillsInstanceValue, BotSkillsReader } from '../../../utils/botSkills';
+import type { BotCore } from './botCore';
+/** What the module needs from the bot: the shared core and the two things only the composition root knows. */
+export interface BotSkillsPorts extends Pick<BotCore, 'bot' | 'command' | 'getState' | 'replyToThread' | 'editThreadMessage' | 'authoriseContext' | 'withThreadLocale' | 'checkIsGeneral'> {
+    /** Whether the switch is on for a conversation; `null` asks for the instance value (General's, else `settings.json`'s, else ON). */
+    readBotSkills: BotSkillsReader;
+    /** The instance value with the layer it comes from (General's own choice, the settings file, the built-in default). */
+    readBotSkillsInstanceValue: () => BotSkillsInstanceValue;
+    /** Whether the topic's backend is OpenCode, whose one server serves every topic and so cannot hide the skills from one. */
+    checkIsOpenCodeTopic: (key: SessionKey) => boolean;
+}
+/**
+ * @description Build the «Bot skills» screen over its ports: `/bot_skills` and its three buttons. A tap writes the choice
+ * and edits the picker into its confirmation (a one-shot picker, like `/language`): the menu is gone once a choice is made.
+ */
+export declare function createBotSkills(ports: BotSkillsPorts): {
+    registerBotSkillsCommands: () => void;
+    registerBotSkillsCallbacks: () => void;
+};
+//# sourceMappingURL=botSkills.d.ts.map

package/dist/connectors/telegram/commands/botSkills.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"botSkills.d.ts","sourceRoot":"","sources":["../../../../src/connectors/telegram/commands/botSkills.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEtD,OAAO,KAAK,EAA2B,sBAAsB,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AACjH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAczC,8GAA8G;AAC9G,MAAM,WAAW,cACf,SAAQ,IAAI,CAAC,OAAO,EAAE,KAAK,GAAG,SAAS,GAAG,UAAU,GAAG,eAAe,GAAG,mBAAmB,GAAG,kBAAkB,GAAG,kBAAkB,GAAG,gBAAgB,CAAC;IAC1J,oIAAoI;IACpI,aAAa,EAAE,eAAe,CAAC;IAC/B,uHAAuH;IACvH,0BAA0B,EAAE,MAAM,sBAAsB,CAAC;IACzD,2HAA2H;IAC3H,oBAAoB,EAAE,CAAC,GAAG,EAAE,UAAU,KAAK,OAAO,CAAC;CACpD;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,cAAc;qCA0Fb,IAAI;sCAeH,IAAI;EAO5C"}

package/dist/connectors/telegram/commands/botSkills.js

@@ -0,0 +1,133 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createBotSkills = createBotSkills;
+/**
+ * The «Bot skills» switch — whether the skills Charness ships with its agents (`agent-plugin/`) and the hint to load the
+ * manager reach them, per topic or (in General) for the instance. See `utils/botSkills.ts` for the precedence and what OFF
+ * does, and README.md in this folder.
+ */
+const telegraf_1 = require("telegraf");
+const i18n_1 = require("../../../i18n");
+const callbackMessage_1 = require("./callbackMessage");
+/** The picker's buttons. */
+const botSkillsOnCallback = 'bsk_on';
+const botSkillsOffCallback = 'bsk_off';
+const botSkillsSameAsGeneralCallback = 'bsk_same';
+/** The word of `/bot_skills <word>` that hands a topic back to General's value. */
+const sameAsGeneralArgument = 'general';
+/**
+ * @description Build the «Bot skills» screen over its ports: `/bot_skills` and its three buttons. A tap writes the choice
+ * and edits the picker into its confirmation (a one-shot picker, like `/language`): the menu is gone once a choice is made.
+ */
+function createBotSkills(ports) {
+    const { bot, command, getState, replyToThread, editThreadMessage, authoriseContext, withThreadLocale, checkIsGeneral, readBotSkills, readBotSkillsInstanceValue, checkIsOpenCodeTopic } = ports;
+    const formatState = (isEnabled) => (isEnabled ? (0, i18n_1.t)('botSkills.on') : (0, i18n_1.t)('botSkills.off'));
+    /**
+     * What the topic is told about the agent it has: a Claude agent keeps its skills until its next start; an OpenCode topic's
+     * skills stay listed (one server serves every topic) and only the hint changes, when that server next restarts — and it is
+     * shared with the OpenCode topics of the same folder.
+     */
+    const getAgentNote = (key) => (checkIsOpenCodeTopic(key) ? (0, i18n_1.t)('botSkills.openCodeTopicNote') : (0, i18n_1.t)('botSkills.runningAgentNote'));
+    const instanceSourceKeys = {
+        general: 'botSkills.instanceSourceGeneral',
+        settingsFile: 'botSkills.instanceSourceSettingsFile',
+        builtInDefault: 'botSkills.instanceSourceBuiltIn',
+    };
+    /**
+     * @description Write a choice and RETURN the confirmation — the one write path behind the typed form and the buttons.
+     * General: the instance value (`null` — «as in General» — is not offered there and changes nothing). A topic: its own
+     * choice, `null` drops it.
+     */
+    async function applyBotSkills(key, isGeneral, choice) {
+        if (isGeneral) {
+            if (choice !== null)
+                await getState().setBotSkillsGlobalValue(choice);
+            return (0, i18n_1.t)('botSkills.setGeneralConfirmation', { state: formatState(readBotSkills(null)) });
+        }
+        await getState().setBotSkillsOverride(key, choice);
+        const state = formatState(readBotSkills(key));
+        const confirmation = choice === null ? (0, i18n_1.t)('botSkills.followGeneralConfirmation', { state }) : (0, i18n_1.t)('botSkills.setTopicConfirmation', { state });
+        // A Claude topic's note continues the confirmation's line; the OpenCode one is a paragraph of its own.
+        return checkIsOpenCodeTopic(key) ? `${confirmation}\n\n${getAgentNote(key)}` : `${confirmation} ${getAgentNote(key)}`;
+    }
+    /** The screen's text: the value in force and where it comes from, what the switch is, and what it means for the agent. */
+    function buildScreenText(key, isGeneral) {
+        if (isGeneral) {
+            const instance = readBotSkillsInstanceValue();
+            const title = (0, i18n_1.t)('botSkills.titleGeneral', { state: formatState(instance.isEnabled), source: (0, i18n_1.t)(instanceSourceKeys[instance.source]) });
+            return [title, (0, i18n_1.t)('botSkills.explanationText'), (0, i18n_1.t)('botSkills.runningAgentNote'), (0, i18n_1.t)('botSkills.generalScopeNote')].join('\n\n');
+        }
+        const source = getState().getBotSkillsOverride(key) === undefined ? (0, i18n_1.t)('botSkills.sourceGeneral') : (0, i18n_1.t)('botSkills.sourceTopic');
+        return [(0, i18n_1.t)('botSkills.titleTopic', { state: formatState(readBotSkills(key)), source }), (0, i18n_1.t)('botSkills.explanationText'), getAgentNote(key)].join('\n\n');
+    }
+    /**
+     * The screen's buttons, the current choice marked ✓. General: On / Off on the instance value in force. A topic: On / Off
+     * and «As in General» (with the value it would give); its mark is the topic's own choice, or «As in General» when it has none.
+     */
+    function buildKeyboard(key, isGeneral) {
+        const mark = (isCurrent) => (isCurrent ? ' ✓' : '');
+        if (isGeneral) {
+            const isEnabled = readBotSkills(null);
+            return telegraf_1.Markup.inlineKeyboard([[
+                    telegraf_1.Markup.button.callback(`${(0, i18n_1.t)('botSkills.onButton')}${mark(isEnabled)}`, botSkillsOnCallback),
+                    telegraf_1.Markup.button.callback(`${(0, i18n_1.t)('botSkills.offButton')}${mark(!isEnabled)}`, botSkillsOffCallback),
+                ]]);
+        }
+        const own = getState().getBotSkillsOverride(key);
+        return telegraf_1.Markup.inlineKeyboard([
+            [
+                telegraf_1.Markup.button.callback(`${(0, i18n_1.t)('botSkills.onButton')}${mark(own === true)}`, botSkillsOnCallback),
+                telegraf_1.Markup.button.callback(`${(0, i18n_1.t)('botSkills.offButton')}${mark(own === false)}`, botSkillsOffCallback),
+            ],
+            [telegraf_1.Markup.button.callback(`${(0, i18n_1.t)('botSkills.sameAsGeneralButton', { state: formatState(readBotSkills(null)) })}${mark(own === undefined)}`, botSkillsSameAsGeneralCallback)],
+        ]);
+    }
+    /** The choice a typed argument names; `undefined` for none (the screen opens), and `general` means nothing in General. */
+    function parseChoice(argument, isGeneral) {
+        if (argument === 'on')
+            return true;
+        if (argument === 'off')
+            return false;
+        if (argument === sameAsGeneralArgument && !isGeneral)
+            return null;
+        return undefined;
+    }
+    /** A tap: apply the choice to the tapped topic (or General), then turn the picker into the confirmation. */
+    async function handleBotSkillsCallback(ctx, choice) {
+        const key = await authoriseContext(ctx);
+        if (!key) {
+            await ctx.answerCbQuery((0, i18n_1.t)('cb.access_denied'));
+            return;
+        }
+        await ctx.answerCbQuery();
+        await withThreadLocale(key, async () => {
+            const confirmation = await applyBotSkills(key, checkIsGeneral(key), choice);
+            const messageId = (0, callbackMessage_1.getCallbackMessageId)(ctx);
+            if (messageId === null)
+                await replyToThread(key, confirmation);
+            else if (!(await editThreadMessage(key, messageId, confirmation)))
+                console.warn('[bsk_cb] picker relabel failed');
+        });
+    }
+    function registerBotSkillsCommands() {
+        // `/bot_skills` — in General the instance value, in a topic that topic's own choice. Not gated on an adapter or a
+        // session: a topic may choose before its agent starts, and the choice is read at the agent's next start. `on` / `off`
+        // (and `general` in a topic) apply at once; bare opens the one-shot picker.
+        command('bot_skills', async (_ctx, key, parsed) => {
+            const isGeneral = checkIsGeneral(key);
+            const choice = parseChoice(parsed.args.join(' ').trim().toLowerCase(), isGeneral);
+            if (choice !== undefined) {
+                await replyToThread(key, await applyBotSkills(key, isGeneral, choice));
+                return;
+            }
+            await replyToThread(key, buildScreenText(key, isGeneral), buildKeyboard(key, isGeneral));
+        });
+    }
+    function registerBotSkillsCallbacks() {
+        bot.action(botSkillsOnCallback, (ctx) => handleBotSkillsCallback(ctx, true));
+        bot.action(botSkillsOffCallback, (ctx) => handleBotSkillsCallback(ctx, false));
+        bot.action(botSkillsSameAsGeneralCallback, (ctx) => handleBotSkillsCallback(ctx, null));
+    }
+    return { registerBotSkillsCommands, registerBotSkillsCallbacks };
+}
+//# sourceMappingURL=botSkills.js.map

package/dist/connectors/telegram/commands/botSkills.js.map

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

package/dist/connectors/telegram/commands/callbackMessage.d.ts

@@ -10,6 +10,11 @@ import type { SessionKey } from '../../../sessionKey';
  * rather than resolve against another message's list.
  */
 export declare function getCallbackMessageId(ctx: Context): number | null;
+/**
+ * @description The text of the message a callback button sits on, as Telegram shows it (formatting marks resolved away), or
+ * `null` when the message carries none (a photo, a very old message). What a handler needs to rewrite a message it holds no record of.
+ */
+export declare function getCallbackMessageText(ctx: Context): string | null;
 /**
  * @description The map key of a per-MESSAGE snapshot (the list a keyboard's indexes resolve against, the rung a
  * question waits to add). A Telegram message id is unique only within ONE chat, so the chat (`key.space`) is part of

package/dist/connectors/telegram/commands/callbackMessage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"callbackMessage.d.ts","sourceRoot":"","sources":["../../../../src/connectors/telegram/commands/callbackMessage.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AACxC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEtD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAEhE;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAElF;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,EAAE,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAQnJ"}
+{"version":3,"file":"callbackMessage.d.ts","sourceRoot":"","sources":["../../../../src/connectors/telegram/commands/callbackMessage.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AACxC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEtD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAEhE;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAGlE;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAElF;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,EAAE,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAQnJ"}

package/dist/connectors/telegram/commands/callbackMessage.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getCallbackMessageId = getCallbackMessageId;
+exports.getCallbackMessageText = getCallbackMessageText;
 exports.buildMessageSnapshotKey = buildMessageSnapshotKey;
 exports.rememberBoundedSnapshot = rememberBoundedSnapshot;
 /**
@@ -12,6 +13,14 @@ exports.rememberBoundedSnapshot = rememberBoundedSnapshot;
 function getCallbackMessageId(ctx) {
     return ctx.callbackQuery?.message?.message_id ?? null;
 }
+/**
+ * @description The text of the message a callback button sits on, as Telegram shows it (formatting marks resolved away), or
+ * `null` when the message carries none (a photo, a very old message). What a handler needs to rewrite a message it holds no record of.
+ */
+function getCallbackMessageText(ctx) {
+    const message = ctx.callbackQuery?.message;
+    return message !== undefined && 'text' in message ? message.text : null;
+}
 /**
  * @description The map key of a per-MESSAGE snapshot (the list a keyboard's indexes resolve against, the rung a
  * question waits to add). A Telegram message id is unique only within ONE chat, so the chat (`key.space`) is part of

package/dist/connectors/telegram/commands/callbackMessage.js.map

@@ -1 +1 @@
-{"version":3,"file":"callbackMessage.js","sourceRoot":"","sources":["../../../../src/connectors/telegram/commands/callbackMessage.ts"],"names":[],"mappings":";;AAYA,oDAEC;AAOD,0DAEC;AAMD,0DAQC;AA/BD;;;;;GAKG;AACH,SAAgB,oBAAoB,CAAC,GAAY;IAC/C,OAAO,GAAG,CAAC,aAAa,EAAE,OAAO,EAAE,UAAU,IAAI,IAAI,CAAC;AACxD,CAAC;AAED;;;;GAIG;AACH,SAAgB,uBAAuB,CAAC,GAAe,EAAE,SAAiB;IACxE,OAAO,GAAG,GAAG,CAAC,QAAQ,IAAI,GAAG,CAAC,KAAK,IAAI,SAAS,EAAE,CAAC;AACrD,CAAC;AAED;;;GAGG;AACH,SAAgB,uBAAuB,CAAY,SAAiC,EAAE,WAAmB,EAAE,QAAmB,EAAE,KAAa;IAC3I,SAAS,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;IAC9B,SAAS,CAAC,GAAG,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;IACrC,OAAO,SAAS,CAAC,IAAI,GAAG,KAAK,EAAE,CAAC;QAC9B,MAAM,MAAM,GAAG,SAAS,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC;QAC7C,IAAI,MAAM,KAAK,SAAS;YAAE,MAAM;QAChC,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC3B,CAAC;AACH,CAAC"}
+{"version":3,"file":"callbackMessage.js","sourceRoot":"","sources":["../../../../src/connectors/telegram/commands/callbackMessage.ts"],"names":[],"mappings":";;AAYA,oDAEC;AAMD,wDAGC;AAOD,0DAEC;AAMD,0DAQC;AAxCD;;;;;GAKG;AACH,SAAgB,oBAAoB,CAAC,GAAY;IAC/C,OAAO,GAAG,CAAC,aAAa,EAAE,OAAO,EAAE,UAAU,IAAI,IAAI,CAAC;AACxD,CAAC;AAED;;;GAGG;AACH,SAAgB,sBAAsB,CAAC,GAAY;IACjD,MAAM,OAAO,GAAG,GAAG,CAAC,aAAa,EAAE,OAAO,CAAC;IAC3C,OAAO,OAAO,KAAK,SAAS,IAAI,MAAM,IAAI,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;AAC1E,CAAC;AAED;;;;GAIG;AACH,SAAgB,uBAAuB,CAAC,GAAe,EAAE,SAAiB;IACxE,OAAO,GAAG,GAAG,CAAC,QAAQ,IAAI,GAAG,CAAC,KAAK,IAAI,SAAS,EAAE,CAAC;AACrD,CAAC;AAED;;;GAGG;AACH,SAAgB,uBAAuB,CAAY,SAAiC,EAAE,WAAmB,EAAE,QAAmB,EAAE,KAAa;IAC3I,SAAS,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;IAC9B,SAAS,CAAC,GAAG,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;IACrC,OAAO,SAAS,CAAC,IAAI,GAAG,KAAK,EAAE,CAAC;QAC9B,MAAM,MAAM,GAAG,SAAS,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC;QAC7C,IAAI,MAAM,KAAK,SAAS;YAAE,MAAM;QAChC,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC3B,CAAC;AACH,CAAC"}