twinclaw 1.0.0

package/dist/services/delivery-tracker.js

@@ -0,0 +1,110 @@
+import { randomUUID } from 'node:crypto';
+import { logThought } from '../utils/logger.js';
+const MAX_HISTORY = 200;
+/**
+ * Tracks outbound message delivery outcomes for reliability telemetry.
+ *
+ * Maintains an in-memory ring buffer of delivery records. Each send operation
+ * is recorded with its attempts, timing, and final outcome. Provides summary
+ * metrics for dashboards and operational visibility.
+ *
+ * Not thread-safe — designed for single-process Node.js usage.
+ */
+export class DeliveryTracker {
+    #records = [];
+    #reconciliations = [];
+    /** Create a new delivery record and return its ID. */
+    createRecord(platform, chatId) {
+        const id = randomUUID();
+        const record = {
+            id,
+            platform,
+            chatId,
+            textPayload: '', // Added missing property
+            state: 'queued',
+            attempts: [],
+            createdAt: new Date().toISOString(),
+        };
+        this.#records.push(record);
+        // Trim ring buffer
+        if (this.#records.length > MAX_HISTORY) {
+            this.#records.splice(0, this.#records.length - MAX_HISTORY);
+        }
+        return id;
+    }
+    /** Record the start of a send attempt. */
+    recordAttemptStart(recordId) {
+        const record = this.#findRecord(recordId);
+        if (!record)
+            return;
+        const attempt = {
+            attemptNumber: record.attempts.length + 1,
+            startedAt: new Date().toISOString(),
+        };
+        record.attempts.push(attempt);
+        record.state = 'dispatching';
+    }
+    /** Mark the latest attempt as successful. */
+    recordSuccess(recordId) {
+        const record = this.#findRecord(recordId);
+        if (!record)
+            return;
+        const last = record.attempts[record.attempts.length - 1];
+        if (last) {
+            last.completedAt = new Date().toISOString();
+            last.durationMs = new Date(last.completedAt).getTime() - new Date(last.startedAt).getTime();
+        }
+        record.state = 'sent';
+        record.resolvedAt = new Date().toISOString();
+    }
+    /** Mark the latest attempt as failed. */
+    recordFailure(recordId, error) {
+        const record = this.#findRecord(recordId);
+        if (!record)
+            return;
+        const last = record.attempts[record.attempts.length - 1];
+        if (last) {
+            last.completedAt = new Date().toISOString();
+            last.error = error;
+            last.durationMs = new Date(last.completedAt).getTime() - new Date(last.startedAt).getTime();
+        }
+    }
+    /** Mark a record as ultimately failed (all retries exhausted). */
+    markFailed(recordId) {
+        const record = this.#findRecord(recordId);
+        if (!record)
+            return;
+        record.state = 'failed';
+        record.resolvedAt = new Date().toISOString();
+        void logThought(`[DeliveryTracker] Message ${recordId} FAILED after ${record.attempts.length} attempt(s) to ${record.platform}:${record.chatId}.`);
+    }
+    /** Record an external callback reconciliation event. */
+    recordReconciliation(payload) {
+        this.#reconciliations.push(payload);
+        if (this.#reconciliations.length > MAX_HISTORY) {
+            this.#reconciliations.splice(0, this.#reconciliations.length - MAX_HISTORY);
+        }
+        void logThought(`[DeliveryTracker] Callback reconciled — task: ${payload.taskId}, status: ${payload.status}.`);
+    }
+    /** Compute reliability metrics from the current record history. */
+    getMetrics(limit = 50) {
+        const resolved = this.#records.filter((r) => r.state === 'sent' || r.state === 'failed');
+        const totalSent = resolved.filter((r) => r.state === 'sent').length;
+        const totalFailed = resolved.filter((r) => r.state === 'failed').length;
+        const totalRetries = resolved.reduce((sum, r) => sum + Math.max(0, r.attempts.length - 1), 0);
+        const averageAttempts = resolved.length > 0
+            ? resolved.reduce((sum, r) => sum + r.attempts.length, 0) / resolved.length
+            : 0;
+        return {
+            totalSent,
+            totalFailed,
+            totalRetries,
+            averageAttempts: Math.round(averageAttempts * 100) / 100,
+            recentRecords: this.#records.slice(-limit),
+        };
+    }
+    // ── Private ───────────────────────────────────────────────────────────────
+    #findRecord(id) {
+        return this.#records.find((r) => r.id === id);
+    }
+}

package/dist/services/dm-pairing.js

@@ -0,0 +1,245 @@
+import { randomBytes } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+const CODE_ALPHABET = 'ABCDEFGHJKLMNPQRSTUVWXYZ23456789';
+const CODE_LENGTH = 8;
+const DEFAULT_CODE_TTL_MS = 60 * 60 * 1000;
+const DEFAULT_MAX_PENDING_PER_CHANNEL = 3;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+function isIsoTimestamp(value) {
+    return Number.isFinite(Date.parse(value));
+}
+function isPairingRequestRecord(value) {
+    if (!isRecord(value)) {
+        return false;
+    }
+    const senderId = value['senderId'];
+    const code = value['code'];
+    const requestedAt = value['requestedAt'];
+    const expiresAt = value['expiresAt'];
+    return (typeof senderId === 'string' &&
+        senderId.length > 0 &&
+        typeof code === 'string' &&
+        /^[A-Z2-9]{8}$/.test(code) &&
+        typeof requestedAt === 'string' &&
+        isIsoTimestamp(requestedAt) &&
+        typeof expiresAt === 'string' &&
+        isIsoTimestamp(expiresAt));
+}
+function assertPairingPendingStore(value, filePath) {
+    if (!isRecord(value) || !Array.isArray(value['requests'])) {
+        throw new Error(`Invalid pairing pending store format at '${filePath}'.`);
+    }
+    const requests = value['requests'];
+    if (!requests.every((entry) => isPairingRequestRecord(entry))) {
+        throw new Error(`Invalid pairing request entries at '${filePath}'.`);
+    }
+    return { requests };
+}
+function assertPairingAllowStore(value, filePath) {
+    if (!isRecord(value) || !Array.isArray(value['senderIds'])) {
+        throw new Error(`Invalid pairing allow store format at '${filePath}'.`);
+    }
+    const senderIds = value['senderIds'];
+    if (!senderIds.every((entry) => typeof entry === 'string' && entry.length > 0)) {
+        throw new Error(`Invalid allowlist sender IDs at '${filePath}'.`);
+    }
+    return { senderIds };
+}
+export function isPairingChannel(value) {
+    return value === 'telegram' || value === 'whatsapp';
+}
+export function normalizePairingSenderId(channel, senderId) {
+    const trimmed = senderId.trim();
+    if (channel === 'telegram') {
+        return trimmed;
+    }
+    const localPart = trimmed.split('@')[0] ?? trimmed;
+    return localPart.replace(/[\s\+\-\(\)]/g, '');
+}
+export class DmPairingService {
+    #credentialsDir;
+    #codeTtlMs;
+    #maxPendingPerChannel;
+    constructor(options = {}) {
+        this.#credentialsDir = options.credentialsDir
+            ? path.resolve(options.credentialsDir)
+            : path.resolve('memory', 'credentials');
+        this.#codeTtlMs =
+            Number.isFinite(options.codeTtlMs) && (options.codeTtlMs ?? 0) > 0
+                ? Number(options.codeTtlMs)
+                : DEFAULT_CODE_TTL_MS;
+        this.#maxPendingPerChannel =
+            Number.isFinite(options.maxPendingPerChannel) && (options.maxPendingPerChannel ?? 0) > 0
+                ? Number(options.maxPendingPerChannel)
+                : DEFAULT_MAX_PENDING_PER_CHANNEL;
+    }
+    listPending(channel, nowMs = Date.now()) {
+        const pending = this.#readPendingStore(channel);
+        const { activeRequests, changed } = this.#pruneExpired(pending.requests, nowMs);
+        if (changed) {
+            this.#writePendingStore(channel, activeRequests);
+        }
+        return [...activeRequests].sort((a, b) => a.requestedAt.localeCompare(b.requestedAt));
+    }
+    listApproved(channel) {
+        const store = this.#readAllowStore(channel);
+        return [...store.senderIds].sort();
+    }
+    isApproved(channel, senderId) {
+        const normalized = normalizePairingSenderId(channel, senderId);
+        if (!normalized) {
+            return false;
+        }
+        const store = this.#readAllowStore(channel);
+        return store.senderIds.includes(normalized);
+    }
+    seedAllowFrom(channel, senderIds) {
+        const normalized = senderIds
+            .map((senderId) => normalizePairingSenderId(channel, senderId))
+            .filter((senderId) => senderId.length > 0);
+        if (normalized.length === 0) {
+            return;
+        }
+        const store = this.#readAllowStore(channel);
+        const merged = [...new Set([...store.senderIds, ...normalized])].sort();
+        this.#writeAllowStore(channel, merged);
+    }
+    requestPairing(channel, senderId, nowMs = Date.now()) {
+        const normalizedSenderId = normalizePairingSenderId(channel, senderId);
+        if (!normalizedSenderId) {
+            return { status: 'limit_reached' };
+        }
+        const pending = this.#readPendingStore(channel);
+        const { activeRequests } = this.#pruneExpired(pending.requests, nowMs);
+        const existing = activeRequests.find((request) => request.senderId === normalizedSenderId);
+        if (existing) {
+            if (activeRequests.length !== pending.requests.length) {
+                this.#writePendingStore(channel, activeRequests);
+            }
+            return { status: 'existing', request: existing };
+        }
+        if (activeRequests.length >= this.#maxPendingPerChannel) {
+            if (activeRequests.length !== pending.requests.length) {
+                this.#writePendingStore(channel, activeRequests);
+            }
+            return { status: 'limit_reached' };
+        }
+        const request = {
+            senderId: normalizedSenderId,
+            code: this.#generateUniqueCode(activeRequests),
+            requestedAt: new Date(nowMs).toISOString(),
+            expiresAt: new Date(nowMs + this.#codeTtlMs).toISOString(),
+        };
+        this.#writePendingStore(channel, [...activeRequests, request]);
+        return { status: 'created', request };
+    }
+    approve(channel, code, nowMs = Date.now()) {
+        const normalizedCode = code.trim().toUpperCase();
+        if (!/^[A-Z2-9]{8}$/.test(normalizedCode)) {
+            return { status: 'not_found' };
+        }
+        const pending = this.#readPendingStore(channel);
+        const request = pending.requests.find((entry) => entry.code === normalizedCode);
+        const { activeRequests } = this.#pruneExpired(pending.requests, nowMs);
+        if (!request) {
+            if (activeRequests.length !== pending.requests.length) {
+                this.#writePendingStore(channel, activeRequests);
+            }
+            return { status: 'not_found' };
+        }
+        if (Date.parse(request.expiresAt) <= nowMs) {
+            const withoutExpired = activeRequests.filter((entry) => entry.code !== normalizedCode);
+            this.#writePendingStore(channel, withoutExpired);
+            return { status: 'expired' };
+        }
+        const remaining = activeRequests.filter((entry) => entry.code !== normalizedCode);
+        this.#writePendingStore(channel, remaining);
+        this.seedAllowFrom(channel, [request.senderId]);
+        return { status: 'approved', senderId: request.senderId };
+    }
+    #generateUniqueCode(existingRequests) {
+        const existingCodes = new Set(existingRequests.map((request) => request.code));
+        for (let attempts = 0; attempts < 128; attempts++) {
+            const code = this.#generateCode();
+            if (!existingCodes.has(code)) {
+                return code;
+            }
+        }
+        throw new Error('Unable to generate a unique pairing code after multiple attempts.');
+    }
+    #generateCode() {
+        const bytes = randomBytes(CODE_LENGTH);
+        let code = '';
+        for (let index = 0; index < CODE_LENGTH; index++) {
+            const alphabetIndex = bytes[index] % CODE_ALPHABET.length;
+            code += CODE_ALPHABET[alphabetIndex];
+        }
+        return code;
+    }
+    #pruneExpired(requests, nowMs) {
+        const activeRequests = requests.filter((request) => Date.parse(request.expiresAt) > nowMs);
+        return { activeRequests, changed: activeRequests.length !== requests.length };
+    }
+    #pendingStorePath(channel) {
+        return path.join(this.#credentialsDir, `${channel}-pairing.json`);
+    }
+    #allowStorePath(channel) {
+        return path.join(this.#credentialsDir, `${channel}-allowFrom.json`);
+    }
+    #readPendingStore(channel) {
+        const filePath = this.#pendingStorePath(channel);
+        if (!fs.existsSync(filePath)) {
+            return { requests: [] };
+        }
+        const raw = this.#readJson(filePath);
+        return assertPairingPendingStore(raw, filePath);
+    }
+    #readAllowStore(channel) {
+        const filePath = this.#allowStorePath(channel);
+        if (!fs.existsSync(filePath)) {
+            return { senderIds: [] };
+        }
+        const raw = this.#readJson(filePath);
+        return assertPairingAllowStore(raw, filePath);
+    }
+    #writePendingStore(channel, requests) {
+        this.#writeJson(this.#pendingStorePath(channel), { requests });
+    }
+    #writeAllowStore(channel, senderIds) {
+        this.#writeJson(this.#allowStorePath(channel), {
+            senderIds: [...new Set(senderIds)].sort(),
+        });
+    }
+    #readJson(filePath) {
+        const raw = fs.readFileSync(filePath, 'utf8');
+        return JSON.parse(raw);
+    }
+    #writeJson(filePath, payload) {
+        fs.mkdirSync(path.dirname(filePath), { recursive: true });
+        const tempPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+        const content = `${JSON.stringify(payload, null, 2)}\n`;
+        try {
+            fs.writeFileSync(tempPath, content, 'utf8');
+            fs.renameSync(tempPath, filePath);
+        }
+        catch (error) {
+            if (fs.existsSync(tempPath)) {
+                fs.unlinkSync(tempPath);
+            }
+            throw error;
+        }
+    }
+}
+let pairingServiceSingleton = null;
+export function getDmPairingService() {
+    if (!pairingServiceSingleton) {
+        pairingServiceSingleton = new DmPairingService();
+    }
+    return pairingServiceSingleton;
+}
+export function resetDmPairingServiceForTests() {
+    pairingServiceSingleton = null;
+}

package/dist/services/embedding-service.js

@@ -0,0 +1,125 @@
+import { getSecretVaultService } from './secret-vault.js';
+import { getConfigValue } from '../config/config-loader.js';
+const DEFAULT_OPENAI_URL = 'https://api.openai.com/v1/embeddings';
+const DEFAULT_OPENAI_MODEL = 'text-embedding-3-small';
+const DEFAULT_OLLAMA_URL = 'http://localhost:11434';
+const DEFAULT_OLLAMA_MODEL = 'mxbai-embed-large';
+function normalizeEmbeddingLength(embedding, expectedDimensions) {
+    if (embedding.length === expectedDimensions) {
+        return embedding;
+    }
+    if (embedding.length > expectedDimensions) {
+        return embedding.slice(0, expectedDimensions);
+    }
+    return [...embedding, ...new Array(expectedDimensions - embedding.length).fill(0)];
+}
+export class EmbeddingService {
+    expectedDimensions;
+    constructor() {
+        const configuredDimensions = Number(getConfigValue('MEMORY_EMBEDDING_DIM') ?? '1536');
+        this.expectedDimensions = Number.isFinite(configuredDimensions) && configuredDimensions > 0
+            ? configuredDimensions
+            : 1536;
+    }
+    async embedText(input) {
+        const normalizedInput = input.trim();
+        if (!normalizedInput) {
+            return null;
+        }
+        const providers = this.getProviderOrder();
+        for (const provider of providers) {
+            try {
+                const embedding = provider === 'ollama'
+                    ? await this.embedWithOllama(normalizedInput)
+                    : await this.embedWithOpenAI(normalizedInput);
+                if (embedding.length > 0) {
+                    return normalizeEmbeddingLength(embedding, this.expectedDimensions);
+                }
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                console.warn(`[EmbeddingService] Provider '${provider}' failed: ${message}`);
+            }
+        }
+        return null;
+    }
+    getProviderOrder() {
+        const configured = (getConfigValue('EMBEDDING_PROVIDER') ?? '').toLowerCase().trim();
+        if (configured === 'ollama') {
+            return ['ollama', 'openai'];
+        }
+        if (configured === 'openai') {
+            return ['openai', 'ollama'];
+        }
+        return ['openai', 'ollama'];
+    }
+    async embedWithOpenAI(input) {
+        const secretVault = getSecretVaultService();
+        const apiKey = secretVault.readSecret('EMBEDDING_API_KEY') ?? secretVault.readSecret('OPENAI_API_KEY') ?? '';
+        if (!apiKey) {
+            throw new Error('Missing EMBEDDING_API_KEY or OPENAI_API_KEY.');
+        }
+        const endpoint = getConfigValue('EMBEDDING_API_URL') ?? DEFAULT_OPENAI_URL;
+        const model = getConfigValue('EMBEDDING_MODEL') ?? DEFAULT_OPENAI_MODEL;
+        const response = await fetch(endpoint, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${apiKey}`,
+            },
+            body: JSON.stringify({
+                model,
+                input,
+            }),
+        });
+        if (!response.ok) {
+            throw new Error(`OpenAI embeddings request failed (${response.status}).`);
+        }
+        const data = await response.json();
+        const embedding = data.data?.[0]?.embedding;
+        if (!Array.isArray(embedding)) {
+            throw new Error('OpenAI embeddings response did not contain an embedding array.');
+        }
+        return embedding;
+    }
+    async embedWithOllama(input) {
+        const baseUrl = getConfigValue('OLLAMA_BASE_URL') ?? DEFAULT_OLLAMA_URL;
+        const model = getConfigValue('OLLAMA_EMBEDDING_MODEL') ?? DEFAULT_OLLAMA_MODEL;
+        const endpoint = `${baseUrl.replace(/\/$/, '')}/api/embeddings`;
+        const response = await fetch(endpoint, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({
+                model,
+                prompt: input,
+            }),
+        });
+        if (!response.ok) {
+            throw new Error(`Ollama embeddings request failed (${response.status}).`);
+        }
+        const data = await response.json();
+        if (!Array.isArray(data.embedding)) {
+            throw new Error('Ollama embeddings response did not contain an embedding array.');
+        }
+        return data.embedding;
+    }
+}
+export function chunkText(content, chunkSize = 900, overlap = 120) {
+    const source = content.replace(/\s+/g, ' ').trim();
+    if (!source) {
+        return [];
+    }
+    const chunks = [];
+    let index = 0;
+    while (index < source.length) {
+        const end = Math.min(index + chunkSize, source.length);
+        chunks.push(source.slice(index, end));
+        if (end >= source.length) {
+            break;
+        }
+        index = Math.max(end - overlap, index + 1);
+    }
+    return chunks;
+}

package/dist/services/file-watcher.js

@@ -0,0 +1,125 @@
+import { watch } from 'chokidar';
+import { logThought } from '../utils/logger.js';
+const DEFAULT_EXCLUDE = ['**/node_modules/**', '**/.git/**', '**/dist/**'];
+/**
+ * Monitors specific local directories for filesystem changes and notifies
+ * registered listeners.
+ *
+ * Uses `chokidar` for cross-platform, efficient file watching with debouncing
+ * and glob-based filtering.
+ *
+ * Usage:
+ * ```ts
+ * const watcher = new FileWatcherService();
+ * watcher.addTarget({
+ *   id: 'workspace',
+ *   directory: '/path/to/project',
+ *   exclude: ['node_modules/**'],
+ * });
+ * watcher.onEvent((event) => console.log(event));
+ * watcher.startAll();
+ * ```
+ */
+export class FileWatcherService {
+    #targets = new Map();
+    #watchers = new Map();
+    #listeners = new Set();
+    /** Register a directory to watch. Does NOT start watching until `start()` is called. */
+    addTarget(target) {
+        if (this.#targets.has(target.id)) {
+            throw new Error(`[FileWatcher] Target '${target.id}' is already registered.`);
+        }
+        this.#targets.set(target.id, target);
+    }
+    /** Remove a target and close its watcher if running. */
+    async removeTarget(targetId) {
+        const existing = this.#watchers.get(targetId);
+        if (existing) {
+            await existing.close();
+            this.#watchers.delete(targetId);
+        }
+        return this.#targets.delete(targetId);
+    }
+    /** Subscribe to all file events. Returns an unsubscribe function. */
+    onEvent(listener) {
+        this.#listeners.add(listener);
+        return () => {
+            this.#listeners.delete(listener);
+        };
+    }
+    /** Start watching a specific target by ID. */
+    async start(targetId) {
+        const target = this.#targets.get(targetId);
+        if (!target) {
+            throw new Error(`[FileWatcher] Target '${targetId}' is not registered.`);
+        }
+        if (this.#watchers.has(targetId))
+            return; // Already watching
+        const ignored = [...DEFAULT_EXCLUDE, ...(target.exclude ?? [])];
+        const watcher = watch(target.directory, {
+            ignored,
+            persistent: true,
+            ignoreInitial: true,
+            awaitWriteFinish: {
+                stabilityThreshold: 300,
+                pollInterval: 100,
+            },
+        });
+        const eventTypes = ['add', 'change', 'unlink', 'addDir', 'unlinkDir'];
+        for (const eventType of eventTypes) {
+            watcher.on(eventType, (filePath) => {
+                void this.#handleEvent(eventType, filePath);
+            });
+        }
+        watcher.on('error', (err) => {
+            const message = err instanceof Error ? err.message : String(err);
+            console.error(`[FileWatcher] Error on target '${targetId}':`, message);
+        });
+        this.#watchers.set(targetId, watcher);
+        await logThought(`[FileWatcher] Started watching '${targetId}' at ${target.directory}`);
+    }
+    /** Start watching all registered targets. */
+    async startAll() {
+        for (const targetId of this.#targets.keys()) {
+            await this.start(targetId);
+        }
+    }
+    /** Stop watching a specific target. */
+    async stop(targetId) {
+        const watcher = this.#watchers.get(targetId);
+        if (!watcher)
+            return;
+        await watcher.close();
+        this.#watchers.delete(targetId);
+        await logThought(`[FileWatcher] Stopped watching '${targetId}'.`);
+    }
+    /** Stop all watchers gracefully. */
+    async stopAll() {
+        for (const [targetId, watcher] of this.#watchers) {
+            await watcher.close();
+            await logThought(`[FileWatcher] Stopped watching '${targetId}'.`);
+        }
+        this.#watchers.clear();
+    }
+    /** Return a list of currently active watch target IDs. */
+    activeTargets() {
+        return [...this.#watchers.keys()];
+    }
+    // ── Private Helpers ────────────────────────────────────────────────────────
+    async #handleEvent(type, filePath) {
+        const event = {
+            type,
+            path: filePath,
+            timestamp: new Date().toISOString(),
+        };
+        await logThought(`[FileWatcher] ${type.toUpperCase()} detected: ${filePath}`);
+        for (const listener of this.#listeners) {
+            try {
+                await listener(event);
+            }
+            catch (err) {
+                console.error('[FileWatcher] Listener threw an error:', err);
+            }
+        }
+    }
+}

package/dist/services/inbound-debounce.js

@@ -0,0 +1,92 @@
+const DEFAULT_DEBOUNCE_MS = 1500;
+export class InboundDebounceService {
+    #enabled;
+    #debounceMs;
+    #now;
+    #pending = new Map();
+    constructor(options = {}) {
+        this.#enabled = options.enabled ?? true;
+        this.#debounceMs = Math.max(0, Math.floor(options.debounceMs ?? DEFAULT_DEBOUNCE_MS));
+        this.#now = options.now ?? (() => Date.now());
+    }
+    get enabled() {
+        return this.#enabled;
+    }
+    get debounceMs() {
+        return this.#debounceMs;
+    }
+    debounce(message) {
+        if (!this.#enabled || this.#debounceMs <= 0) {
+            return Promise.resolve(message);
+        }
+        const key = this.#buildKey(message);
+        return new Promise((resolve) => {
+            const existing = this.#pending.get(key);
+            if (existing) {
+                clearTimeout(existing.timer);
+                if (message.text) {
+                    existing.texts.push(message.text);
+                }
+                existing.resolve = resolve;
+                existing.timer = this.#scheduleFlush(key);
+            }
+            else {
+                const texts = message.text ? [message.text] : [];
+                const pending = {
+                    message,
+                    timer: this.#scheduleFlush(key),
+                    resolve,
+                    texts,
+                };
+                this.#pending.set(key, pending);
+            }
+        });
+    }
+    flushAll() {
+        const messages = [];
+        for (const [key, pending] of this.#pending) {
+            clearTimeout(pending.timer);
+            const merged = this.#mergeMessages(pending);
+            messages.push(merged);
+            this.#pending.delete(key);
+        }
+        return messages;
+    }
+    clear() {
+        for (const pending of this.#pending.values()) {
+            clearTimeout(pending.timer);
+        }
+        this.#pending.clear();
+    }
+    getPendingCount() {
+        return this.#pending.size;
+    }
+    #buildKey(message) {
+        return `${message.platform}:${message.chatId}`;
+    }
+    #scheduleFlush(key) {
+        return setTimeout(() => {
+            this.#flush(key);
+        }, this.#debounceMs);
+    }
+    #flush(key) {
+        const pending = this.#pending.get(key);
+        if (!pending)
+            return;
+        this.#pending.delete(key);
+        const merged = this.#mergeMessages(pending);
+        pending.resolve(merged);
+    }
+    #mergeMessages(pending) {
+        const base = pending.message;
+        const texts = pending.texts.filter(Boolean);
+        if (texts.length === 0) {
+            return base;
+        }
+        if (texts.length === 1) {
+            return { ...base, text: texts[0] };
+        }
+        const mergedText = texts.join('\n');
+        return { ...base, text: mergedText };
+    }
+}