@shuyhere/takotako 0.0.1

package/dist/core/exec-approvals.js

@@ -0,0 +1,187 @@
+/**
+ * Exec approval system — require user confirmation for dangerous commands.
+ *
+ * Classifies commands by risk level and routes high-risk ones through
+ * an approval flow before execution.
+ */
+const DEFAULT_APPROVAL_CONFIG = {
+    mode: 'ask',
+    alwaysAsk: [],
+    allowed: [],
+    blocked: [],
+    timeoutMs: 60_000,
+    autoApproveAfter: undefined,
+};
+// ─── Risk classification patterns ──────────────────────────────────
+const BLOCKED_PATTERNS = [
+    { pattern: /\brm\s+-[^\s]*r[^\s]*f[^\s]*\s+\/\s*$/, reason: 'Recursive delete of root filesystem' },
+    { pattern: /\brm\s+-[^\s]*f[^\s]*r[^\s]*\s+\/\s*$/, reason: 'Recursive delete of root filesystem' },
+    { pattern: /\bformat\b/, reason: 'Disk format command' },
+    { pattern: /\bdd\s+if=/, reason: 'Raw disk write (dd)' },
+    { pattern: /\bmkfs\b/, reason: 'Filesystem creation' },
+    { pattern: /:\(\)\{\s*:\|:&\s*\};:/, reason: 'Fork bomb' },
+];
+const DANGEROUS_PATTERNS = [
+    { pattern: /\bsudo\b/, reason: 'Elevated privileges (sudo)' },
+    { pattern: /\brm\s+-[^\s]*r[^\s]*f/, reason: 'Recursive force delete' },
+    { pattern: /\bchmod\s+777\b/, reason: 'World-writable permissions' },
+    { pattern: /\bcurl\b.*\|\s*\bbash\b/, reason: 'Remote code execution (curl | bash)' },
+    { pattern: /\bwget\b.*\|\s*\bsh\b/, reason: 'Remote code execution (wget | sh)' },
+    { pattern: /\bshutdown\b/, reason: 'System shutdown' },
+    { pattern: /\breboot\b/, reason: 'System reboot' },
+];
+const MODERATE_PATTERNS = [
+    { pattern: /\bgit\s+push\s+--force\b/, reason: 'Force push (destructive)' },
+    { pattern: /\bnpm\s+publish\b/, reason: 'Package publish' },
+    { pattern: /\bdocker\s+rm\b/, reason: 'Docker container removal' },
+    { pattern: /\bkill\s+-9\b/, reason: 'Force kill process' },
+];
+const SAFE_PATTERNS = [
+    /^\s*(ls|cat|echo|pwd|git\s+status|git\s+log|npm\s+test|node)\b/,
+];
+export class ExecApprovalManager {
+    config;
+    pending;
+    sessionApprovals; // sessionId -> command -> approval count
+    constructor(config) {
+        this.config = { ...DEFAULT_APPROVAL_CONFIG, ...config };
+        this.pending = new Map();
+        this.sessionApprovals = new Map();
+    }
+    /** Check if a command needs approval. Returns null if auto-approved. */
+    checkCommand(command, sessionId) {
+        if (this.config.mode === 'off')
+            return null;
+        const { level, reason } = this.classifyRisk(command);
+        // Safe commands never need approval
+        if (level === 'safe')
+            return null;
+        // Blocked commands get an immediate blocked request (no approval possible)
+        if (level === 'blocked') {
+            const req = {
+                id: crypto.randomUUID().slice(0, 8),
+                command,
+                riskLevel: level,
+                reason,
+                sessionId,
+                timestamp: Date.now(),
+                status: 'denied',
+            };
+            return req;
+        }
+        // In allowlist mode, check if command is pre-approved
+        if (this.config.mode === 'allowlist') {
+            const isAllowed = this.config.allowed.some(pattern => command.includes(pattern) || new RegExp(pattern).test(command));
+            if (isAllowed)
+                return null;
+        }
+        // Check auto-approve threshold
+        if (this.config.autoApproveAfter !== undefined) {
+            const sessionMap = this.sessionApprovals.get(sessionId);
+            if (sessionMap) {
+                const count = sessionMap.get(command) ?? 0;
+                if (count >= this.config.autoApproveAfter)
+                    return null;
+            }
+        }
+        // In 'full' mode, everything non-safe needs approval
+        // In 'ask' mode, dangerous/moderate need approval
+        if (this.config.mode === 'full' || level === 'dangerous' || level === 'moderate') {
+            // Check alwaysAsk overrides
+            const forceAsk = this.config.alwaysAsk.some(pattern => command.includes(pattern));
+            // In ask mode, moderate commands don't need approval unless in alwaysAsk
+            if (this.config.mode === 'ask' && level === 'moderate' && !forceAsk) {
+                return null;
+            }
+            const req = {
+                id: crypto.randomUUID().slice(0, 8),
+                command,
+                riskLevel: level,
+                reason,
+                sessionId,
+                timestamp: Date.now(),
+                status: 'pending',
+            };
+            this.pending.set(req.id, req);
+            return req;
+        }
+        return null;
+    }
+    /** Classify command risk level. */
+    classifyRisk(command) {
+        // Check user-configured blocked list first
+        for (const pattern of this.config.blocked) {
+            if (command.includes(pattern) || new RegExp(pattern).test(command)) {
+                return { level: 'blocked', reason: `Blocked by policy: ${pattern}` };
+            }
+        }
+        // Check built-in blocked patterns
+        for (const { pattern, reason } of BLOCKED_PATTERNS) {
+            if (pattern.test(command)) {
+                return { level: 'blocked', reason };
+            }
+        }
+        // Check dangerous patterns
+        for (const { pattern, reason } of DANGEROUS_PATTERNS) {
+            if (pattern.test(command)) {
+                return { level: 'dangerous', reason };
+            }
+        }
+        // Check moderate patterns
+        for (const { pattern, reason } of MODERATE_PATTERNS) {
+            if (pattern.test(command)) {
+                return { level: 'moderate', reason };
+            }
+        }
+        // Check safe patterns
+        for (const pattern of SAFE_PATTERNS) {
+            if (pattern.test(command)) {
+                return { level: 'safe', reason: 'Known safe command' };
+            }
+        }
+        // Default: safe for unknown commands (ExecSafety handles blocking)
+        return { level: 'safe', reason: 'No risk patterns matched' };
+    }
+    /** Resolve a pending approval. */
+    resolve(requestId, decision) {
+        const req = this.pending.get(requestId);
+        if (!req)
+            return;
+        req.status = decision;
+        this.pending.delete(requestId);
+        // Track approval count for auto-approve
+        if (decision === 'approved' && this.config.autoApproveAfter !== undefined) {
+            if (!this.sessionApprovals.has(req.sessionId)) {
+                this.sessionApprovals.set(req.sessionId, new Map());
+            }
+            const sessionMap = this.sessionApprovals.get(req.sessionId);
+            const count = sessionMap.get(req.command) ?? 0;
+            sessionMap.set(req.command, count + 1);
+        }
+    }
+    /** Get pending approval for a session. */
+    getPending(sessionId) {
+        for (const req of this.pending.values()) {
+            if (req.sessionId === sessionId && req.status === 'pending') {
+                return req;
+            }
+        }
+        return undefined;
+    }
+    /** Format approval request as a user-facing message. */
+    formatRequest(req) {
+        const riskLabel = req.riskLevel.toUpperCase();
+        const lines = [
+            `⚠️  Command requires approval [${riskLabel}]`,
+            `Command: ${req.command}`,
+            `Reason:  ${req.reason}`,
+            ``,
+            `Reply with:`,
+            `  /approve ${req.id} allow    — execute this command`,
+            `  /approve ${req.id} deny     — block this command`,
+            `  /approve ${req.id} allow-always — approve and auto-approve future identical commands`,
+        ];
+        return lines.join('\n');
+    }
+}
+//# sourceMappingURL=exec-approvals.js.map

package/dist/core/exec-approvals.js.map

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

package/dist/core/heartbeat.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Heartbeat manager — periodic agent turns for proactive work.
+ *
+ * Implements the reference runtime heartbeat contract:
+ * - Periodic agent turns at configured interval
+ * - HEARTBEAT_OK response contract (ack stripped, reply dropped if ≤ maxChars)
+ * - Active hours support (only run during configured window)
+ * - HEARTBEAT.md workspace file read (skip if empty)
+ * - Delivery routing: "none" (silent), "last" (last channel), or explicit
+ * - Manual wake support
+ */
+import type { HeartbeatConfig } from '../config/schema.js';
+import type { AgentLoop } from './agent-loop.js';
+import type { SessionManager } from '../gateway/session.js';
+/** Result of a heartbeat run. */
+export interface HeartbeatResult {
+    /** Whether the agent responded with HEARTBEAT_OK (acknowledgment). */
+    isAck: boolean;
+    /** Raw response text from the agent. */
+    rawResponse: string;
+    /** Cleaned response (HEARTBEAT_OK stripped). */
+    deliverableText: string;
+    /** Whether the response should be delivered (not suppressed). */
+    shouldDeliver: boolean;
+    /** Timestamp of the heartbeat run. */
+    timestamp: Date;
+}
+/** Delivery handler called when heartbeat produces deliverable output. */
+export type HeartbeatDeliveryHandler = (result: HeartbeatResult, target: string) => void;
+export declare class HeartbeatManager {
+    private timer;
+    private config;
+    private agentLoop;
+    private sessions;
+    private workspaceRoot;
+    private heartbeatSession;
+    private running;
+    private deliveryHandlers;
+    private lastChannel;
+    private typingSuppressed;
+    constructor(config: HeartbeatConfig, workspaceRoot: string);
+    /** Inject dependencies after construction. */
+    setDeps(agentLoop: AgentLoop, sessions: SessionManager): void;
+    /** Register a handler for deliverable heartbeat output. */
+    onDelivery(handler: HeartbeatDeliveryHandler): void;
+    /** Track the last active channel for 'last' target routing. */
+    setLastChannel(channel: string): void;
+    /** Whether typing should be suppressed (heartbeat in progress). */
+    isTypingSuppressed(): boolean;
+    /** Start the heartbeat loop. */
+    start(): void;
+    /** Stop the heartbeat loop. */
+    stop(): void;
+    /** Manual wake — run heartbeat immediately outside the timer. */
+    wake(): Promise<HeartbeatResult | null>;
+    /** Execute a single heartbeat run. */
+    private runHeartbeat;
+    /** Parse a heartbeat response according to the HEARTBEAT_OK contract. */
+    private parseResponse;
+    /** Route delivery to the configured target. */
+    private deliver;
+    /** Check if the current time is within the active hours window. */
+    private isWithinActiveHours;
+    /** Read HEARTBEAT.md from workspace. Returns null if file doesn't exist. */
+    private readHeartbeatFile;
+    /** Get or create the dedicated heartbeat session. */
+    private getHeartbeatSession;
+}
+/** Parse a duration string like "30m", "1h", "2h30m" into milliseconds. */
+export declare function parseDuration(duration: string): number;
+//# sourceMappingURL=heartbeat.d.ts.map

package/dist/core/heartbeat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"heartbeat.d.ts","sourceRoot":"","sources":["../../src/core/heartbeat.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,EAAE,cAAc,EAAW,MAAM,uBAAuB,CAAC;AAErE,iCAAiC;AACjC,MAAM,WAAW,eAAe;IAC9B,sEAAsE;IACtE,KAAK,EAAE,OAAO,CAAC;IACf,wCAAwC;IACxC,WAAW,EAAE,MAAM,CAAC;IACpB,gDAAgD;IAChD,eAAe,EAAE,MAAM,CAAC;IACxB,iEAAiE;IACjE,aAAa,EAAE,OAAO,CAAC;IACvB,sCAAsC;IACtC,SAAS,EAAE,IAAI,CAAC;CACjB;AAED,0EAA0E;AAC1E,MAAM,MAAM,wBAAwB,GAAG,CAAC,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;AAEzF,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,KAAK,CAA+C;IAC5D,OAAO,CAAC,MAAM,CAAkB;IAChC,OAAO,CAAC,SAAS,CAA0B;IAC3C,OAAO,CAAC,QAAQ,CAA+B;IAC/C,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,gBAAgB,CAAwB;IAChD,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,gBAAgB,CAAkC;IAC1D,OAAO,CAAC,WAAW,CAAuB;IAC1C,OAAO,CAAC,gBAAgB,CAAS;gBAErB,MAAM,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM;IAK1D,8CAA8C;IAC9C,OAAO,CAAC,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,cAAc,GAAG,IAAI;IAK7D,2DAA2D;IAC3D,UAAU,CAAC,OAAO,EAAE,wBAAwB,GAAG,IAAI;IAInD,+DAA+D;IAC/D,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAIrC,mEAAmE;IACnE,kBAAkB,IAAI,OAAO;IAI7B,gCAAgC;IAChC,KAAK,IAAI,IAAI;IAiBb,+BAA+B;IAC/B,IAAI,IAAI,IAAI;IASZ,iEAAiE;IAC3D,IAAI,IAAI,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;IAI7C,sCAAsC;YACxB,YAAY;IA4C1B,yEAAyE;IACzE,OAAO,CAAC,aAAa;IAyBrB,+CAA+C;IAC/C,OAAO,CAAC,OAAO;IAkBf,mEAAmE;IACnE,OAAO,CAAC,mBAAmB;IA+B3B,4EAA4E;YAC9D,iBAAiB;IAQ/B,qDAAqD;IACrD,OAAO,CAAC,mBAAmB;CAS5B;AAED,2EAA2E;AAC3E,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAatD"}

package/dist/core/heartbeat.js

@@ -0,0 +1,214 @@
+/**
+ * Heartbeat manager — periodic agent turns for proactive work.
+ *
+ * Implements the reference runtime heartbeat contract:
+ * - Periodic agent turns at configured interval
+ * - HEARTBEAT_OK response contract (ack stripped, reply dropped if ≤ maxChars)
+ * - Active hours support (only run during configured window)
+ * - HEARTBEAT.md workspace file read (skip if empty)
+ * - Delivery routing: "none" (silent), "last" (last channel), or explicit
+ * - Manual wake support
+ */
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+export class HeartbeatManager {
+    timer = null;
+    config;
+    agentLoop = null;
+    sessions = null;
+    workspaceRoot;
+    heartbeatSession = null;
+    running = false;
+    deliveryHandlers = [];
+    lastChannel = null;
+    typingSuppressed = false;
+    constructor(config, workspaceRoot) {
+        this.config = config;
+        this.workspaceRoot = workspaceRoot;
+    }
+    /** Inject dependencies after construction. */
+    setDeps(agentLoop, sessions) {
+        this.agentLoop = agentLoop;
+        this.sessions = sessions;
+    }
+    /** Register a handler for deliverable heartbeat output. */
+    onDelivery(handler) {
+        this.deliveryHandlers.push(handler);
+    }
+    /** Track the last active channel for 'last' target routing. */
+    setLastChannel(channel) {
+        this.lastChannel = channel;
+    }
+    /** Whether typing should be suppressed (heartbeat in progress). */
+    isTypingSuppressed() {
+        return this.typingSuppressed;
+    }
+    /** Start the heartbeat loop. */
+    start() {
+        const intervalMs = parseDuration(this.config.every);
+        if (intervalMs <= 0) {
+            console.log('[heartbeat] Disabled (every=0)');
+            return;
+        }
+        this.running = true;
+        this.timer = setInterval(() => {
+            this.runHeartbeat().catch((err) => {
+                console.error('[heartbeat] Error:', err instanceof Error ? err.message : err);
+            });
+        }, intervalMs);
+        console.log(`[heartbeat] Started (every ${this.config.every}, target=${this.config.target})`);
+    }
+    /** Stop the heartbeat loop. */
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+        this.running = false;
+        console.log('[heartbeat] Stopped');
+    }
+    /** Manual wake — run heartbeat immediately outside the timer. */
+    async wake() {
+        return this.runHeartbeat();
+    }
+    /** Execute a single heartbeat run. */
+    async runHeartbeat() {
+        if (!this.agentLoop || !this.sessions) {
+            console.warn('[heartbeat] Not initialized (missing agentLoop or sessions)');
+            return null;
+        }
+        // 1. Check active hours
+        if (!this.isWithinActiveHours()) {
+            return null;
+        }
+        // 2. Read HEARTBEAT.md — skip if empty
+        const heartbeatContent = await this.readHeartbeatFile();
+        if (heartbeatContent !== null && heartbeatContent.trim() === '') {
+            return null;
+        }
+        // 3. Suppress typing during heartbeat
+        this.typingSuppressed = true;
+        try {
+            // 4. Get or create heartbeat session
+            const session = this.getHeartbeatSession();
+            // 5. Run agent loop with heartbeat prompt
+            let response = '';
+            for await (const chunk of this.agentLoop.run(session, this.config.prompt)) {
+                response += chunk;
+            }
+            // 6. Parse response: HEARTBEAT_OK contract
+            const result = this.parseResponse(response);
+            // 7. Route delivery
+            if (result.shouldDeliver) {
+                this.deliver(result);
+            }
+            return result;
+        }
+        finally {
+            this.typingSuppressed = false;
+        }
+    }
+    /** Parse a heartbeat response according to the HEARTBEAT_OK contract. */
+    parseResponse(raw) {
+        const trimmed = raw.trim();
+        const hasAck = trimmed.startsWith('HEARTBEAT_OK') || trimmed.endsWith('HEARTBEAT_OK');
+        // Strip HEARTBEAT_OK from the response
+        const cleaned = trimmed
+            .replace(/^HEARTBEAT_OK\s*/i, '')
+            .replace(/\s*HEARTBEAT_OK$/i, '')
+            .trim();
+        // If ack and remaining text is short, suppress delivery
+        const shouldDeliver = hasAck
+            ? cleaned.length > this.config.ackMaxChars
+            : cleaned.length > 0;
+        return {
+            isAck: hasAck,
+            rawResponse: raw,
+            deliverableText: cleaned,
+            shouldDeliver,
+            timestamp: new Date(),
+        };
+    }
+    /** Route delivery to the configured target. */
+    deliver(result) {
+        let target = this.config.target;
+        if (target === 'none')
+            return;
+        if (target === 'last') {
+            target = this.lastChannel ?? 'none';
+            if (target === 'none')
+                return;
+        }
+        for (const handler of this.deliveryHandlers) {
+            try {
+                handler(result, target);
+            }
+            catch {
+                // Don't let handler errors crash the heartbeat system
+            }
+        }
+    }
+    /** Check if the current time is within the active hours window. */
+    isWithinActiveHours() {
+        if (!this.config.activeHours)
+            return true;
+        const { start, end, timezone } = this.config.activeHours;
+        const now = new Date();
+        // Get current time in the configured timezone
+        const formatter = new Intl.DateTimeFormat('en-US', {
+            hour: '2-digit',
+            minute: '2-digit',
+            hour12: false,
+            timeZone: timezone ?? undefined,
+        });
+        const parts = formatter.formatToParts(now);
+        const hour = parseInt(parts.find((p) => p.type === 'hour')?.value ?? '0', 10);
+        const minute = parseInt(parts.find((p) => p.type === 'minute')?.value ?? '0', 10);
+        const currentMinutes = hour * 60 + minute;
+        const [startH, startM] = start.split(':').map(Number);
+        const [endH, endM] = end.split(':').map(Number);
+        const startMinutes = startH * 60 + startM;
+        const endMinutes = endH * 60 + endM;
+        if (startMinutes <= endMinutes) {
+            return currentMinutes >= startMinutes && currentMinutes < endMinutes;
+        }
+        // Wraps midnight
+        return currentMinutes >= startMinutes || currentMinutes < endMinutes;
+    }
+    /** Read HEARTBEAT.md from workspace. Returns null if file doesn't exist. */
+    async readHeartbeatFile() {
+        try {
+            return await readFile(join(this.workspaceRoot, 'HEARTBEAT.md'), 'utf-8');
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Get or create the dedicated heartbeat session. */
+    getHeartbeatSession() {
+        if (!this.heartbeatSession) {
+            this.heartbeatSession = this.sessions.create({
+                name: 'heartbeat',
+                metadata: { isHeartbeat: true },
+            });
+        }
+        return this.heartbeatSession;
+    }
+}
+/** Parse a duration string like "30m", "1h", "2h30m" into milliseconds. */
+export function parseDuration(duration) {
+    if (!duration || duration === '0' || duration === '0m')
+        return 0;
+    let totalMs = 0;
+    const hourMatch = duration.match(/(\d+)\s*h/i);
+    const minMatch = duration.match(/(\d+)\s*m/i);
+    const secMatch = duration.match(/(\d+)\s*s/i);
+    if (hourMatch)
+        totalMs += parseInt(hourMatch[1], 10) * 3600_000;
+    if (minMatch)
+        totalMs += parseInt(minMatch[1], 10) * 60_000;
+    if (secMatch)
+        totalMs += parseInt(secMatch[1], 10) * 1000;
+    return totalMs;
+}
+//# sourceMappingURL=heartbeat.js.map

package/dist/core/heartbeat.js.map

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

package/dist/core/message-queue.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Message queue — collect, debounce, and cap inbound messages.
+ *
+ * When messages arrive faster than the model can process them:
+ * - collect: batch messages within a time window
+ * - debounce: wait for a pause in typing before processing
+ * - cap: limit max queued messages to prevent context overflow
+ * - drop: configurable strategy when cap is hit (oldest, summarize)
+ */
+export interface QueueConfig {
+    /** Queue mode: 'off' | 'collect' | 'debounce' */
+    mode: 'off' | 'collect' | 'debounce';
+    /** Debounce delay in ms (default: 2000) */
+    debounceMs: number;
+    /** Max messages to collect before force-processing (default: 25) */
+    cap: number;
+    /** What to do when cap is hit: 'oldest' drops oldest, 'summarize' summarizes */
+    dropStrategy: 'oldest' | 'summarize';
+    /** Max wait time before force-processing in ms (default: 10000) */
+    maxWaitMs: number;
+}
+export interface QueuedMessage {
+    content: string;
+    channelId: string;
+    authorId: string;
+    timestamp: number;
+    messageId: string;
+}
+export declare class MessageQueue {
+    private config;
+    private queues;
+    private timers;
+    private maxTimers;
+    private processor;
+    constructor(config: Partial<QueueConfig>, processor: (sessionId: string, messages: QueuedMessage[]) => Promise<void>);
+    /** Enqueue a message. Returns true if message was queued (not processed immediately). */
+    enqueue(sessionId: string, message: QueuedMessage): boolean;
+    /** Force-flush a session's queue immediately. */
+    flush(sessionId: string): Promise<void>;
+    /** Get current queue depth for a session. */
+    depth(sessionId: string): number;
+    /** Clear all queues and timers. */
+    clear(): void;
+    /** Get queue status for all sessions. */
+    status(): Array<{
+        sessionId: string;
+        depth: number;
+        oldestMs: number;
+    }>;
+    /** Update the queue mode at runtime. */
+    setMode(mode: 'off' | 'collect' | 'debounce'): void;
+    /** Get current config. */
+    getConfig(): QueueConfig;
+    private startDebounceTimer;
+    private startMaxWaitTimer;
+    private processQueue;
+    /** Merge queued messages into a single string for the model. */
+    static mergeMessages(messages: QueuedMessage[]): string;
+}
+//# sourceMappingURL=message-queue.d.ts.map

package/dist/core/message-queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-queue.d.ts","sourceRoot":"","sources":["../../src/core/message-queue.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,WAAW,WAAW;IAC1B,iDAAiD;IACjD,IAAI,EAAE,KAAK,GAAG,SAAS,GAAG,UAAU,CAAC;IACrC,2CAA2C;IAC3C,UAAU,EAAE,MAAM,CAAC;IACnB,oEAAoE;IACpE,GAAG,EAAE,MAAM,CAAC;IACZ,gFAAgF;IAChF,YAAY,EAAE,QAAQ,GAAG,WAAW,CAAC;IACrC,mEAAmE;IACnE,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAUD,qBAAa,YAAY;IACvB,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,MAAM,CAA+B;IAC7C,OAAO,CAAC,MAAM,CAA6C;IAC3D,OAAO,CAAC,SAAS,CAA6C;IAC9D,OAAO,CAAC,SAAS,CAAkE;gBAGjF,MAAM,EAAE,OAAO,CAAC,WAAW,CAAC,EAC5B,SAAS,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,aAAa,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC;IAS5E,yFAAyF;IACzF,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,GAAG,OAAO;IA8C3D,iDAAiD;IAC3C,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI7C,6CAA6C;IAC7C,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM;IAIhC,mCAAmC;IACnC,KAAK,IAAI,IAAI;IAQb,yCAAyC;IACzC,MAAM,IAAI,KAAK,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IAcvE,wCAAwC;IACxC,OAAO,CAAC,IAAI,EAAE,KAAK,GAAG,SAAS,GAAG,UAAU,GAAG,IAAI;IAInD,0BAA0B;IAC1B,SAAS,IAAI,WAAW;IAIxB,OAAO,CAAC,kBAAkB;IAe1B,OAAO,CAAC,iBAAiB;YAcX,YAAY;IAuB1B,gEAAgE;IAChE,MAAM,CAAC,aAAa,CAAC,QAAQ,EAAE,aAAa,EAAE,GAAG,MAAM;CAyBxD"}