@a1hvdy/cc-openclaw 0.24.0 → 0.25.1

package/dist/src/channels/telegram-mirror/burst-accumulator.d.ts

@@ -0,0 +1,96 @@
+/**
+ * src/channels/telegram-mirror/burst-accumulator.ts — v0.25.0 M8.
+ *
+ * Per-chat 5-second settle window for non-slash inbound messages. When
+ * the user fires multiple message bubbles within 5s of each other, the
+ * accumulator concatenates them into one user-message payload (joined by
+ * "\n\n") before delivery to the engine. A gap > 5s flushes the prior
+ * buffer immediately and starts a new one.
+ *
+ * Decision: ADR-007 — 5s is the empirical saddle point. <3s gaps are
+ * almost always related thoughts; >8s gaps are almost always new turns.
+ * 5s matches the WARMUP_COOLDOWN_MS in typing-prefetch.ts (consistency).
+ *
+ * Routing responsibility lives in the inbound dispatcher (later milestone):
+ *   • Slash messages bypass this class — dispatched immediately via
+ *     dispatchCommand (commands.ts).
+ *   • Compose-active chats bypass this class — drafts go to ComposeBuffer
+ *     (compose-buffer.ts). M7 takes priority over M8 per ADR-007.
+ *   • Everything else flows through submit() here.
+ *
+ * The flush flow has TWO triggers:
+ *   1. A new submit() that arrives AFTER the settle window — that submit
+ *      returns the prior buffer in `flushed` and starts a fresh buffer.
+ *   2. A periodic flushIfReady() check that runs on a timer when no new
+ *      inbound has arrived since the window opened.
+ *
+ * Tests inject a deterministic clock; production passes Date.now.
+ */
+export interface BurstAccumulatorOptions {
+    /** Settle window in milliseconds (default 5000 per ADR-007). */
+    settleMs?: number;
+    /** Injectable clock for tests; defaults to Date.now. */
+    now?: () => number;
+    /** Custom separator between concatenated drafts (default "\n\n"). */
+    separator?: string;
+}
+export interface SubmitResult {
+    /**
+     * When the new submit() arrives AFTER the prior buffer's settle window,
+     * the prior buffer is returned here for immediate delivery; the new
+     * message starts a fresh buffer in its place. Undefined otherwise.
+     */
+    flushed?: string;
+}
+export declare class BurstAccumulator {
+    private readonly sessions;
+    private readonly settleMs;
+    private readonly now;
+    private readonly separator;
+    constructor(opts?: BurstAccumulatorOptions);
+    /**
+     * Submit a non-slash inbound message. Returns `flushed` populated when
+     * the prior buffer for the chat had timed out and this submit forced
+     * its flush; in that case the new message starts a fresh buffer.
+     *
+     * The returned `flushed` payload is the only value the caller delivers
+     * to the engine — the new message itself stays buffered for at least
+     * `settleMs` more, so it gets a chance to coalesce with follow-ups.
+     */
+    submit(chatId: string, text: string): SubmitResult;
+    /**
+     * Periodic check — when the settle window has elapsed without any new
+     * inbound, returns the buffered payload and clears the session. When
+     * the window has NOT yet elapsed, returns undefined and leaves the
+     * buffer intact. Returns undefined for chats without an active buffer.
+     *
+     * Production wiring: call from a 1Hz interval timer per known chatId
+     * (or from the inbound dispatcher's idle-tick).
+     */
+    flushIfReady(chatId: string): string | undefined;
+    /**
+     * Force-flush the buffer for a chat regardless of timing. Used when an
+     * explicit signal arrives that the current buffer must deliver now —
+     * e.g. a slash command was typed (its dispatcher flushes burst first,
+     * then routes the slash, so the bursted text reaches the engine before
+     * the slash response).
+     */
+    flushNow(chatId: string): string | undefined;
+    /**
+     * True when a buffer exists for the chat (regardless of settle state).
+     * Used by the inbound dispatcher to decide whether a slash arrival
+     * should trigger flushNow before routing.
+     */
+    hasBuffer(chatId: string): boolean;
+    /**
+     * Number of drafts currently buffered for the chat. Useful for status
+     * surfaces and for tests asserting the buffer state.
+     */
+    draftCount(chatId: string): number;
+    /**
+     * Clear all sessions. Test helper.
+     */
+    clear(): void;
+    private fresh;
+    private format;
+}

package/dist/src/channels/telegram-mirror/burst-accumulator.js

@@ -0,0 +1,130 @@
+/**
+ * src/channels/telegram-mirror/burst-accumulator.ts — v0.25.0 M8.
+ *
+ * Per-chat 5-second settle window for non-slash inbound messages. When
+ * the user fires multiple message bubbles within 5s of each other, the
+ * accumulator concatenates them into one user-message payload (joined by
+ * "\n\n") before delivery to the engine. A gap > 5s flushes the prior
+ * buffer immediately and starts a new one.
+ *
+ * Decision: ADR-007 — 5s is the empirical saddle point. <3s gaps are
+ * almost always related thoughts; >8s gaps are almost always new turns.
+ * 5s matches the WARMUP_COOLDOWN_MS in typing-prefetch.ts (consistency).
+ *
+ * Routing responsibility lives in the inbound dispatcher (later milestone):
+ *   • Slash messages bypass this class — dispatched immediately via
+ *     dispatchCommand (commands.ts).
+ *   • Compose-active chats bypass this class — drafts go to ComposeBuffer
+ *     (compose-buffer.ts). M7 takes priority over M8 per ADR-007.
+ *   • Everything else flows through submit() here.
+ *
+ * The flush flow has TWO triggers:
+ *   1. A new submit() that arrives AFTER the settle window — that submit
+ *      returns the prior buffer in `flushed` and starts a fresh buffer.
+ *   2. A periodic flushIfReady() check that runs on a timer when no new
+ *      inbound has arrived since the window opened.
+ *
+ * Tests inject a deterministic clock; production passes Date.now.
+ */
+const DEFAULT_BURST_SETTLE_MS = 5_000;
+export class BurstAccumulator {
+    sessions = new Map();
+    settleMs;
+    now;
+    separator;
+    constructor(opts = {}) {
+        this.settleMs = opts.settleMs ?? DEFAULT_BURST_SETTLE_MS;
+        this.now = opts.now ?? Date.now;
+        this.separator = opts.separator ?? '\n\n';
+    }
+    /**
+     * Submit a non-slash inbound message. Returns `flushed` populated when
+     * the prior buffer for the chat had timed out and this submit forced
+     * its flush; in that case the new message starts a fresh buffer.
+     *
+     * The returned `flushed` payload is the only value the caller delivers
+     * to the engine — the new message itself stays buffered for at least
+     * `settleMs` more, so it gets a chance to coalesce with follow-ups.
+     */
+    submit(chatId, text) {
+        const now = this.now();
+        const session = this.sessions.get(chatId);
+        if (session && now - session.lastTs > this.settleMs) {
+            // Gap exceeded — flush the prior buffer, then start a new one
+            // containing only the current message.
+            const flushed = this.format(session);
+            this.sessions.set(chatId, this.fresh(chatId, text, now));
+            return { flushed };
+        }
+        if (!session) {
+            this.sessions.set(chatId, this.fresh(chatId, text, now));
+        }
+        else {
+            session.pending.push({ text, ts: now });
+            session.lastTs = now;
+        }
+        return {};
+    }
+    /**
+     * Periodic check — when the settle window has elapsed without any new
+     * inbound, returns the buffered payload and clears the session. When
+     * the window has NOT yet elapsed, returns undefined and leaves the
+     * buffer intact. Returns undefined for chats without an active buffer.
+     *
+     * Production wiring: call from a 1Hz interval timer per known chatId
+     * (or from the inbound dispatcher's idle-tick).
+     */
+    flushIfReady(chatId) {
+        const session = this.sessions.get(chatId);
+        if (!session)
+            return undefined;
+        if (this.now() - session.lastTs <= this.settleMs)
+            return undefined;
+        const out = this.format(session);
+        this.sessions.delete(chatId);
+        return out;
+    }
+    /**
+     * Force-flush the buffer for a chat regardless of timing. Used when an
+     * explicit signal arrives that the current buffer must deliver now —
+     * e.g. a slash command was typed (its dispatcher flushes burst first,
+     * then routes the slash, so the bursted text reaches the engine before
+     * the slash response).
+     */
+    flushNow(chatId) {
+        const session = this.sessions.get(chatId);
+        if (!session)
+            return undefined;
+        const out = this.format(session);
+        this.sessions.delete(chatId);
+        return out;
+    }
+    /**
+     * True when a buffer exists for the chat (regardless of settle state).
+     * Used by the inbound dispatcher to decide whether a slash arrival
+     * should trigger flushNow before routing.
+     */
+    hasBuffer(chatId) {
+        return this.sessions.has(chatId);
+    }
+    /**
+     * Number of drafts currently buffered for the chat. Useful for status
+     * surfaces and for tests asserting the buffer state.
+     */
+    draftCount(chatId) {
+        return this.sessions.get(chatId)?.pending.length ?? 0;
+    }
+    /**
+     * Clear all sessions. Test helper.
+     */
+    clear() {
+        this.sessions.clear();
+    }
+    fresh(chatId, text, ts) {
+        return { chatId, pending: [{ text, ts }], lastTs: ts };
+    }
+    format(session) {
+        return session.pending.map((p) => p.text).join(this.separator);
+    }
+}
+//# sourceMappingURL=burst-accumulator.js.map

package/dist/src/channels/telegram-mirror/burst-accumulator.js.map

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

package/dist/src/channels/telegram-mirror/callback-mapping.d.ts

@@ -0,0 +1,61 @@
+/**
+ * src/channels/telegram-mirror/callback-mapping.ts — v0.25.0 M3.
+ *
+ * ADR-004 — Telegram's callback_data is capped at 64 bytes UTF-8. For
+ * payloads larger than that (most action+slug combinations are), the bot
+ * writes a short opaque base36 id into callback_data and stashes the real
+ * payload here. TTL prevents unbounded memory growth as users tap through
+ * keyboards or never tap at all.
+ *
+ * Default TTL is 10 minutes per ADR-004 monitoring signal (callback miss
+ * rate > 2% in soak → revisit TTL). The class accepts an injectable clock
+ * so tests can fast-forward without setTimeout games.
+ *
+ * No I/O, no global state. Each subsystem that hands out callback_data
+ * owns its own CallbackMap instance — keeps ownership boundaries clean
+ * for M4 (per-command), M9 (plan keyboards), M11 (cost subview).
+ */
+export interface CallbackMapOptions {
+    /** TTL in milliseconds (default 10 minutes per ADR-004). */
+    ttlMs?: number;
+    /** Injectable clock for tests; defaults to Date.now. */
+    now?: () => number;
+    /** Length of the opaque id string (default 8 base36 chars ≈ 41 bits entropy). */
+    idLength?: number;
+}
+export declare class CallbackMap {
+    private readonly entries;
+    private readonly ttlMs;
+    private readonly now;
+    private readonly idLength;
+    constructor(opts?: CallbackMapOptions);
+    /**
+     * Allocate a fresh opaque id and stash the payload behind it. Returns the
+     * id, which fits in a Telegram callback_data field with room to spare.
+     * Idempotent only at the data-shape level — calling create() with the
+     * same payload twice produces two distinct ids.
+     */
+    create(payload: unknown): string;
+    /**
+     * Resolve a callback id to its stashed payload. Returns undefined if the
+     * id was never minted OR if it has expired since. Stale entries are
+     * dropped lazily on access — no background timer needed.
+     */
+    get(id: string): unknown | undefined;
+    /**
+     * Manually evict an id (e.g., one-shot Approve/Reject buttons after the
+     * user taps once). Returns true if an entry was deleted.
+     */
+    delete(id: string): boolean;
+    /**
+     * Current entry count (after pruning expired). Useful for monitoring
+     * and the 2% callback-miss-rate signal in soak.
+     */
+    size(): number;
+    /**
+     * Drop everything. Test helper; production code never calls this.
+     */
+    clear(): void;
+    private prune;
+    private randomId;
+}

package/dist/src/channels/telegram-mirror/callback-mapping.js

@@ -0,0 +1,99 @@
+/**
+ * src/channels/telegram-mirror/callback-mapping.ts — v0.25.0 M3.
+ *
+ * ADR-004 — Telegram's callback_data is capped at 64 bytes UTF-8. For
+ * payloads larger than that (most action+slug combinations are), the bot
+ * writes a short opaque base36 id into callback_data and stashes the real
+ * payload here. TTL prevents unbounded memory growth as users tap through
+ * keyboards or never tap at all.
+ *
+ * Default TTL is 10 minutes per ADR-004 monitoring signal (callback miss
+ * rate > 2% in soak → revisit TTL). The class accepts an injectable clock
+ * so tests can fast-forward without setTimeout games.
+ *
+ * No I/O, no global state. Each subsystem that hands out callback_data
+ * owns its own CallbackMap instance — keeps ownership boundaries clean
+ * for M4 (per-command), M9 (plan keyboards), M11 (cost subview).
+ */
+import { randomBytes } from 'crypto';
+const DEFAULT_TTL_MS = 10 * 60_000;
+const DEFAULT_ID_LENGTH = 8;
+export class CallbackMap {
+    entries = new Map();
+    ttlMs;
+    now;
+    idLength;
+    constructor(opts = {}) {
+        this.ttlMs = opts.ttlMs ?? DEFAULT_TTL_MS;
+        this.now = opts.now ?? Date.now;
+        this.idLength = opts.idLength ?? DEFAULT_ID_LENGTH;
+    }
+    /**
+     * Allocate a fresh opaque id and stash the payload behind it. Returns the
+     * id, which fits in a Telegram callback_data field with room to spare.
+     * Idempotent only at the data-shape level — calling create() with the
+     * same payload twice produces two distinct ids.
+     */
+    create(payload) {
+        this.prune();
+        let id = this.randomId();
+        // Defensive — base36 ids of length 8 have ~3T possible values, so
+        // collisions are astronomically unlikely, but the loop is cheap.
+        while (this.entries.has(id)) {
+            id = this.randomId();
+        }
+        this.entries.set(id, { payload, expiresAt: this.now() + this.ttlMs });
+        return id;
+    }
+    /**
+     * Resolve a callback id to its stashed payload. Returns undefined if the
+     * id was never minted OR if it has expired since. Stale entries are
+     * dropped lazily on access — no background timer needed.
+     */
+    get(id) {
+        const entry = this.entries.get(id);
+        if (!entry)
+            return undefined;
+        if (entry.expiresAt <= this.now()) {
+            this.entries.delete(id);
+            return undefined;
+        }
+        return entry.payload;
+    }
+    /**
+     * Manually evict an id (e.g., one-shot Approve/Reject buttons after the
+     * user taps once). Returns true if an entry was deleted.
+     */
+    delete(id) {
+        return this.entries.delete(id);
+    }
+    /**
+     * Current entry count (after pruning expired). Useful for monitoring
+     * and the 2% callback-miss-rate signal in soak.
+     */
+    size() {
+        this.prune();
+        return this.entries.size;
+    }
+    /**
+     * Drop everything. Test helper; production code never calls this.
+     */
+    clear() {
+        this.entries.clear();
+    }
+    prune() {
+        const now = this.now();
+        for (const [id, entry] of this.entries) {
+            if (entry.expiresAt <= now)
+                this.entries.delete(id);
+        }
+    }
+    randomId() {
+        // 8 random bytes → 64 bits → BigInt → base36 → take left N chars.
+        // Leading zeroes are fine — base36 keeps id length bounded.
+        const hex = randomBytes(8).toString('hex');
+        const base36 = BigInt('0x' + hex).toString(36);
+        return base36.padStart(this.idLength, '0').slice(0, this.idLength);
+    }
+}
+//# sourceMappingURL=callback-mapping.js.map

package/dist/src/channels/telegram-mirror/callback-mapping.js.map

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

package/dist/src/channels/telegram-mirror/card-renderer.d.ts

@@ -0,0 +1,74 @@
+/**
+ * src/channels/telegram-mirror/card-renderer.ts — v0.25.0 M2.
+ *
+ * Pure-function renderer: Turn (from state-machine.ts) → message body string
+ * suitable for sendMessage / editMessageText. Telegram-API HTTP wiring
+ * (sendTg / editTg) lands in a later milestone alongside the dispatch path
+ * — M2's exit criterion is just "render a single turn (working → done)",
+ * which is satisfied by this pure function.
+ *
+ * Aesthetic: terminal-mimic per ADR-001. Header glyph ("▶" working,
+ * "✓" done) + tool call list (each prefixed with status glyph) + assistant
+ * text. Compact enough to fit in a single Telegram message bubble.
+ *
+ * Tests live at tests/channels/telegram-mirror/m2-render-pipeline.test.ts.
+ */
+import type { Turn, ToolCallRecord } from './state-machine.js';
+/**
+ * Format one tool-call line for inclusion in the rendered card body.
+ *   "✓ Bash · ls -la"
+ *   "… Read · src/index.ts"
+ *   "✗ Edit · …error glyph at left"
+ */
+export declare function renderToolLine(tc: ToolCallRecord): string;
+/**
+ * Render the thinking block (M6). Each line of the thinking text is
+ * prefixed with "> " to read as a block quote in plain-text Telegram
+ * bubbles — clearly visually distinct from the assistant text below it
+ * without depending on MarkdownV2 escapes. Empty thinking returns ''.
+ */
+export declare function renderThinkingBlock(thinkingText: string): string;
+/**
+ * Render the full turn into a Telegram-safe message body. The mirror keeps
+ * a single message per turn that gets edited in place — this function is
+ * idempotent for a given turn snapshot and produces the next body string.
+ *
+ * Body shape (lines separated by \n):
+ *
+ *   ▶ Working           ← or "✓ Done" when state==='done'
+ *   ✓ Bash · ls -la     ← one line per tool call, in arrival order
+ *   … Read · src/x.ts
+ *   <empty line>
+ *   💭 Thinking         ← M6, only when thinkingText non-empty
+ *   > reasoning line 1
+ *   > reasoning line 2
+ *   <empty line>
+ *   <assistant text>    ← present only when non-empty;
+ *                          ★ Insight ─ blocks preserved INLINE
+ *                          at their emission position (M6).
+ *
+ * Lines with no content (e.g. empty tool list, empty assistant text) are
+ * omitted entirely so the rendered body never has trailing whitespace.
+ */
+export declare function renderTurn(turn: Turn): string;
+/**
+ * A render action — abstraction the dispatch layer (added in a later
+ * milestone) consumes. M2 doesn't dispatch; it just builds the action so
+ * tests can assert against the planned message lifecycle.
+ *
+ *   - 'send' on turn start (no prior messageId)
+ *   - 'edit' on every subsequent state mutation
+ */
+export interface RenderAction {
+    type: 'send' | 'edit';
+    chatId: string;
+    text: string;
+    /** Defined only when type === 'edit'. */
+    messageId?: number;
+}
+/**
+ * Decide whether the current turn snapshot should be sent (first render)
+ * or edited (subsequent renders). The dispatcher tracks the (chatId →
+ * messageId) map; this function just produces the action shape.
+ */
+export declare function planRenderAction(turn: Turn, knownMessageId: number | undefined): RenderAction;

package/dist/src/channels/telegram-mirror/card-renderer.js

@@ -0,0 +1,131 @@
+/**
+ * src/channels/telegram-mirror/card-renderer.ts — v0.25.0 M2.
+ *
+ * Pure-function renderer: Turn (from state-machine.ts) → message body string
+ * suitable for sendMessage / editMessageText. Telegram-API HTTP wiring
+ * (sendTg / editTg) lands in a later milestone alongside the dispatch path
+ * — M2's exit criterion is just "render a single turn (working → done)",
+ * which is satisfied by this pure function.
+ *
+ * Aesthetic: terminal-mimic per ADR-001. Header glyph ("▶" working,
+ * "✓" done) + tool call list (each prefixed with status glyph) + assistant
+ * text. Compact enough to fit in a single Telegram message bubble.
+ *
+ * Tests live at tests/channels/telegram-mirror/m2-render-pipeline.test.ts.
+ */
+/**
+ * Glyph picked per tool-call status. Mirrors terminal "running / done /
+ * errored" iconography that A1 already reads in the live Claude Code TUI.
+ */
+function toolGlyph(tc) {
+    if (tc.isError)
+        return '✗';
+    if (tc.result !== undefined)
+        return '✓';
+    return '…';
+}
+/**
+ * Render the input argument summary for a tool call. Kept tight — full
+ * input is in the result; the mirror line is meant to read at a glance.
+ */
+function toolInputSummary(tc) {
+    const input = tc.input;
+    if (!input || typeof input !== 'object')
+        return '';
+    // Prefer common single-field shapes used by Bash/Read/Edit/Write.
+    const single = typeof input.command === 'string'
+        ? input.command
+        : typeof input.file_path === 'string'
+            ? input.file_path
+            : typeof input.path === 'string'
+                ? input.path
+                : typeof input.url === 'string'
+                    ? input.url
+                    : '';
+    if (single) {
+        return single.length > 60 ? single.slice(0, 57) + '...' : single;
+    }
+    return '';
+}
+/**
+ * Format one tool-call line for inclusion in the rendered card body.
+ *   "✓ Bash · ls -la"
+ *   "… Read · src/index.ts"
+ *   "✗ Edit · …error glyph at left"
+ */
+export function renderToolLine(tc) {
+    const glyph = toolGlyph(tc);
+    const summary = toolInputSummary(tc);
+    return summary ? `${glyph} ${tc.name} · ${summary}` : `${glyph} ${tc.name}`;
+}
+/**
+ * Render the thinking block (M6). Each line of the thinking text is
+ * prefixed with "> " to read as a block quote in plain-text Telegram
+ * bubbles — clearly visually distinct from the assistant text below it
+ * without depending on MarkdownV2 escapes. Empty thinking returns ''.
+ */
+export function renderThinkingBlock(thinkingText) {
+    const trimmed = thinkingText.trim();
+    if (trimmed.length === 0)
+        return '';
+    const lines = trimmed.split('\n');
+    return ['💭 Thinking', ...lines.map((l) => `> ${l}`)].join('\n');
+}
+/**
+ * Render the full turn into a Telegram-safe message body. The mirror keeps
+ * a single message per turn that gets edited in place — this function is
+ * idempotent for a given turn snapshot and produces the next body string.
+ *
+ * Body shape (lines separated by \n):
+ *
+ *   ▶ Working           ← or "✓ Done" when state==='done'
+ *   ✓ Bash · ls -la     ← one line per tool call, in arrival order
+ *   … Read · src/x.ts
+ *   <empty line>
+ *   💭 Thinking         ← M6, only when thinkingText non-empty
+ *   > reasoning line 1
+ *   > reasoning line 2
+ *   <empty line>
+ *   <assistant text>    ← present only when non-empty;
+ *                          ★ Insight ─ blocks preserved INLINE
+ *                          at their emission position (M6).
+ *
+ * Lines with no content (e.g. empty tool list, empty assistant text) are
+ * omitted entirely so the rendered body never has trailing whitespace.
+ */
+export function renderTurn(turn) {
+    const header = turn.state === 'done' ? '✓ Done' : '▶ Working';
+    const lines = [header];
+    if (turn.toolCalls.length > 0) {
+        for (const tc of turn.toolCalls) {
+            lines.push(renderToolLine(tc));
+        }
+    }
+    // Defensive default — Turn.thinkingText is required by the interface, but
+    // some test helpers and pre-M6 fixtures construct Turn-shaped objects
+    // without setting it. Treat absent / undefined as empty.
+    const thinking = renderThinkingBlock(turn.thinkingText ?? '');
+    if (thinking.length > 0) {
+        lines.push('');
+        lines.push(thinking);
+    }
+    const text = turn.assistantText.trim();
+    if (text.length > 0) {
+        lines.push('');
+        lines.push(text);
+    }
+    return lines.join('\n');
+}
+/**
+ * Decide whether the current turn snapshot should be sent (first render)
+ * or edited (subsequent renders). The dispatcher tracks the (chatId →
+ * messageId) map; this function just produces the action shape.
+ */
+export function planRenderAction(turn, knownMessageId) {
+    const text = renderTurn(turn);
+    if (knownMessageId === undefined) {
+        return { type: 'send', chatId: turn.chatId, text };
+    }
+    return { type: 'edit', chatId: turn.chatId, text, messageId: knownMessageId };
+}
+//# sourceMappingURL=card-renderer.js.map

package/dist/src/channels/telegram-mirror/card-renderer.js.map

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