cursorconnect 0.1.0 → 0.1.4

package/README.md

@@ -17,15 +17,16 @@ cd CursorConnect && npm install
 npm run install:cli
 ```
 
-`install:cli` собирает пакет и ставит глобально `cursorconnect`, вызывает `init` для текущего репо.
+`install:cli` собирает пакет и ставит глобально `cursorconnect` (relay встроен из `bridge/.env` при bundle).
 
-В `bridge/.env` задайте `RELAY_URL` и `RELAY_TOKEN`.
+Свой relay — опционально `~/.cursorconnect/config.env`.
 
 ## Команды
 
 ```bash
-cursorconnect start              # bridge + QR в терминале
-cursorconnect start -r           # перезапуск Cursor с CDP без вопроса
+cursorconnect start              # CDP (авто Cmd+Q + Cursor с :9222) + bridge + код
+cursorconnect start -r           # то же (явный перезапуск)
+cursorconnect start --no-restart-cursor  # не трогать Cursor (спросит y/n)
 cursorconnect status
 cursorconnect stop
 cursorconnect init /path/to/CursorConnect

package/bridge-runtime/.env.example

@@ -0,0 +1,19 @@
+CDP_URL=http://127.0.0.1:9222
+SERVER_HOST=127.0.0.1
+SERVER_PORT=3847
+POLL_INTERVAL_MS=400
+DEBOUNCE_MS=150
+WINDOW_POLL_INTERVAL_MS=8000
+WEBAPP_PASSWORD=
+# Leave empty to use ~/.cursor/projects
+# CURSOR_PROJECTS_DIR=
+LOG_LEVEL=info
+# Follow active Cursor window in CDP (1.5s poll). Set FOCUS_SYNC_ENABLED=0 to disable.
+# FOCUS_SYNC_INTERVAL_MS=1500
+# Voice → text in app (POST /api/transcribe, Whisper)
+OPENAI_API_KEY=
+# OPENAI_TRANSCRIBE_MODEL=whisper-1
+# Remote relay (VPS): transparent Socket.io forward; processing stays on this Mac
+# RELAY_URL=https://your-domain.example
+# RELAY_TOKEN=same-as-relay-.env
+# RELAY_ROOM_ID=default

package/bridge-runtime/dist/agent-title-match.d.ts

@@ -0,0 +1,17 @@
+import type { AgentSummary, AgentsIndex } from './types.js';
+export declare function normalizeAgentTitle(title: string): string;
+/** Score how well a Cursor sidebar title matches a JSONL agent row. */
+export declare function agentTitleMatchScore(sidebarTitle: string, jsonlLabel: string): number;
+export declare function findAgentById(jsonl: AgentsIndex, agentId: string): AgentSummary | undefined;
+/** Best JSONL agent for a Cursor sidebar row (generated title vs first user message). */
+export declare function matchJsonlAgentForSidebarTitle(rowTitle: string, jsonl: AgentsIndex, composerIdByTitle?: Record<string, string>): AgentSummary | undefined;
+export declare function isSyntheticAgentId(agentId: string): boolean;
+/** Map app/relay agentId (+ optional sidebar title) to an on-disk JSONL id. */
+export declare function resolveJsonlAgentId(projectsDir: string, agentId: string, opts?: {
+    title?: string;
+    composerIdByTitle?: Record<string, string>;
+}): string;
+export declare function resolveJsonlFilePath(projectsDir: string, agentId: string, opts?: {
+    title?: string;
+    composerIdByTitle?: Record<string, string>;
+}): string | null;

package/bridge-runtime/dist/agent-title-match.js

@@ -0,0 +1,213 @@
+import { basename, join } from 'path';
+import { existsSync, readdirSync, readFileSync } from 'fs';
+export function normalizeAgentTitle(title) {
+    return title
+        .trim()
+        .replace(/\s+/g, ' ')
+        .replace(/\d+\s*(?:s|m|h|d|w)\b/gi, '')
+        .replace(/\d+[smhdw]$/i, '')
+        .trim()
+        .toLowerCase();
+}
+/** Score how well a Cursor sidebar title matches a JSONL agent row. */
+export function agentTitleMatchScore(sidebarTitle, jsonlLabel) {
+    const a = normalizeAgentTitle(sidebarTitle);
+    const b = normalizeAgentTitle(jsonlLabel);
+    if (!a || !b)
+        return 0;
+    if (a === b)
+        return 100;
+    if (a.length >= 10 && b.length >= 10 && (a.includes(b) || b.includes(a)))
+        return 85;
+    let score = 0;
+    const wordsA = a.split(/\s+/).filter((w) => w.length > 3);
+    const wordsB = new Set(b.split(/\s+/).filter((w) => w.length > 3));
+    for (const w of wordsA) {
+        if (wordsB.has(w))
+            score += 2;
+    }
+    // Russian / iOS sidebar titles vs first user message (different wording, same topic).
+    const stems = [
+        [/\bios\b/i, 5],
+        [/приложен/i, 5],
+        [/полноцен/i, 4],
+        [/testflight/i, 4],
+        [/\bgit\b/i, 4],
+        [/репоз/i, 3],
+        [/развер/i, 3],
+        [/деплой/i, 3],
+        [/проект/i, 2],
+    ];
+    for (const [re, bonus] of stems) {
+        if (re.test(a) && re.test(b))
+            score += bonus;
+    }
+    if (/\bgit\b/.test(a) && (/\bgit\b/.test(b) || b.includes('гит') || b.includes('репо')))
+        score += 4;
+    if (/\b(repository|repo|deployment|deploy|project)\b/.test(a)) {
+        if (b.includes('репо') || b.includes('repo') || b.includes('разверни') || b.includes('deploy'))
+            score += 3;
+        if (b.includes('project') || b.includes('проект'))
+            score += 2;
+    }
+    return score;
+}
+export function findAgentById(jsonl, agentId) {
+    for (const repo of jsonl.repos) {
+        const hit = repo.agents.find((a) => a.id === agentId);
+        if (hit)
+            return hit;
+    }
+    return undefined;
+}
+/** Best JSONL agent for a Cursor sidebar row (generated title vs first user message). */
+export function matchJsonlAgentForSidebarTitle(rowTitle, jsonl, composerIdByTitle) {
+    const fromDomUuid = composerIdByTitle?.[normalizeAgentTitle(rowTitle)];
+    if (fromDomUuid) {
+        const hit = findAgentById(jsonl, fromDomUuid);
+        if (hit)
+            return hit;
+    }
+    let best;
+    for (const repo of jsonl.repos) {
+        for (const agent of repo.agents) {
+            let score = agentTitleMatchScore(rowTitle, agent.title);
+            if (agent.preview) {
+                score = Math.max(score, agentTitleMatchScore(rowTitle, agent.preview));
+            }
+            if (score >= 4 && (!best || score > best.score)) {
+                best = { agent, score };
+            }
+        }
+    }
+    return best?.agent;
+}
+function findJsonlByAgentId(projectsDir, agentId) {
+    if (!existsSync(projectsDir))
+        return null;
+    for (const project of readdirSync(projectsDir, { withFileTypes: true })) {
+        if (!project.isDirectory())
+            continue;
+        const base = join(projectsDir, project.name, 'agent-transcripts');
+        const direct = join(base, agentId, `${agentId}.jsonl`);
+        if (existsSync(direct))
+            return direct;
+        const found = walkForAgent(base, agentId);
+        if (found)
+            return found;
+    }
+    return null;
+}
+function walkForAgent(dir, agentId, depth = 0) {
+    if (depth > 5 || !existsSync(dir))
+        return null;
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        const full = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            const r = walkForAgent(full, agentId, depth + 1);
+            if (r)
+                return r;
+        }
+        else if (entry.name === `${agentId}.jsonl`) {
+            return full;
+        }
+    }
+    return null;
+}
+function peekFirstUserMessage(filePath) {
+    try {
+        const buf = readFileSync(filePath, 'utf-8').slice(0, 8192);
+        for (const line of buf.split('\n')) {
+            if (!line.trim())
+                continue;
+            const row = JSON.parse(line);
+            if (row.role !== 'user')
+                continue;
+            const text = row.message?.content?.find((c) => c.type === 'text')?.text ?? '';
+            const cleaned = text.replace(/<user_query>\s*/gi, '').replace(/<\/user_query>/gi, '').trim();
+            if (cleaned)
+                return cleaned.slice(0, 200);
+        }
+    }
+    catch {
+        /* ignore */
+    }
+    return undefined;
+}
+function collectJsonlAgents(projectsDir) {
+    const out = [];
+    if (!existsSync(projectsDir))
+        return out;
+    function walk(dir, depth) {
+        if (depth > 4)
+            return;
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            const full = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                walk(full, depth + 1);
+                continue;
+            }
+            if (!entry.name.endsWith('.jsonl') || full.includes('/subagents/'))
+                continue;
+            const id = basename(entry.name, '.jsonl');
+            const preview = peekFirstUserMessage(full);
+            out.push({
+                id,
+                title: preview?.slice(0, 80) || `Agent ${id.slice(0, 8)}`,
+                preview,
+            });
+        }
+    }
+    for (const project of readdirSync(projectsDir, { withFileTypes: true })) {
+        if (!project.isDirectory())
+            continue;
+        const transcriptsDir = join(projectsDir, project.name, 'agent-transcripts');
+        if (!existsSync(transcriptsDir))
+            continue;
+        walk(transcriptsDir, 0);
+    }
+    return out;
+}
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+export function isSyntheticAgentId(agentId) {
+    return (!agentId ||
+        /^tab-\d+$/.test(agentId) ||
+        /^sidebar-\d+$/.test(agentId) ||
+        agentId.startsWith('title:'));
+}
+/** Map app/relay agentId (+ optional sidebar title) to an on-disk JSONL id. */
+export function resolveJsonlAgentId(projectsDir, agentId, opts) {
+    if (findJsonlByAgentId(projectsDir, agentId))
+        return agentId;
+    const title = opts?.title?.trim();
+    const map = opts?.composerIdByTitle;
+    if (title && map) {
+        const mapped = map[normalizeAgentTitle(title)];
+        if (mapped && findJsonlByAgentId(projectsDir, mapped))
+            return mapped;
+    }
+    if (title) {
+        let best;
+        for (const row of collectJsonlAgents(projectsDir)) {
+            let score = agentTitleMatchScore(title, row.title);
+            if (row.preview)
+                score = Math.max(score, agentTitleMatchScore(title, row.preview));
+            if (score >= 4 && (!best || score > best.score))
+                best = { id: row.id, score };
+        }
+        if (best)
+            return best.id;
+    }
+    if (isSyntheticAgentId(agentId) && !title)
+        return agentId;
+    if (UUID_RE.test(agentId) && !findJsonlByAgentId(projectsDir, agentId) && title) {
+        const fromTitle = resolveJsonlAgentId(projectsDir, 'sidebar-0', { title, composerIdByTitle: map });
+        if (fromTitle !== 'sidebar-0' && findJsonlByAgentId(projectsDir, fromTitle))
+            return fromTitle;
+    }
+    return agentId;
+}
+export function resolveJsonlFilePath(projectsDir, agentId, opts) {
+    const resolved = resolveJsonlAgentId(projectsDir, agentId, opts);
+    return findJsonlByAgentId(projectsDir, resolved);
+}

package/bridge-runtime/dist/cdp-bridge.d.ts

@@ -0,0 +1,23 @@
+import { EventEmitter } from 'events';
+import type { ServerConfig, CursorWindow } from './types.js';
+import { CdpClient } from './cdp-client.js';
+export declare class CDPBridge extends EventEmitter {
+    private config;
+    private client;
+    private reconnectTimer;
+    private refreshTimer;
+    private backoffMs;
+    windows: CursorWindow[];
+    activeTargetId: string;
+    constructor(config: ServerConfig);
+    getClient(): CdpClient | null;
+    isConnected(): boolean;
+    start(): Promise<void>;
+    stop(): void;
+    refreshWindows(): Promise<void>;
+    switchWindow(targetId: string): Promise<void>;
+    /** Switch home CDP connection to the Cursor window that currently has focus. */
+    syncToForegroundWindow(): Promise<boolean>;
+    private connectActive;
+    private scheduleReconnect;
+}

package/bridge-runtime/dist/cdp-bridge.js

@@ -0,0 +1,116 @@
+import { EventEmitter } from 'events';
+import { CdpClient } from './cdp-client.js';
+import { detectForegroundTargetId } from './focused-window.js';
+export class CDPBridge extends EventEmitter {
+    config;
+    client = null;
+    reconnectTimer = null;
+    refreshTimer = null;
+    backoffMs = 1000;
+    windows = [];
+    activeTargetId = '';
+    constructor(config) {
+        super();
+        this.config = config;
+    }
+    getClient() {
+        return this.client;
+    }
+    isConnected() {
+        return this.client?.isConnected() ?? false;
+    }
+    async start() {
+        await this.refreshWindows();
+        if (this.windows.length > 0 && !this.activeTargetId) {
+            this.activeTargetId = this.windows[0].id;
+        }
+        await this.connectActive();
+        this.refreshTimer = setInterval(() => void this.refreshWindows(), 10_000);
+    }
+    stop() {
+        if (this.reconnectTimer)
+            clearTimeout(this.reconnectTimer);
+        if (this.refreshTimer)
+            clearInterval(this.refreshTimer);
+        this.client?.disconnect();
+        this.client = null;
+    }
+    async refreshWindows() {
+        try {
+            const res = await fetch(`${this.config.cdpUrl}/json`);
+            const targets = (await res.json());
+            this.windows = targets
+                .filter((t) => t.type === 'page' && t.url.includes('workbench'))
+                .map((t) => ({
+                id: t.id,
+                title: parseWindowTitle(t.title),
+                workspace: parseWindowTitle(t.title),
+                wsUrl: t.webSocketDebuggerUrl,
+            }));
+            if (this.activeTargetId && !this.windows.some((w) => w.id === this.activeTargetId)) {
+                this.activeTargetId = this.windows[0]?.id ?? '';
+            }
+        }
+        catch (err) {
+            console.warn('[cdp-bridge] refreshWindows:', err.message);
+        }
+    }
+    async switchWindow(targetId) {
+        if (targetId === this.activeTargetId && this.client?.isConnected())
+            return;
+        this.activeTargetId = targetId;
+        await this.connectActive();
+    }
+    /** Switch home CDP connection to the Cursor window that currently has focus. */
+    async syncToForegroundWindow() {
+        if (this.windows.length <= 1)
+            return false;
+        const nextId = await detectForegroundTargetId(this.windows, this.activeTargetId);
+        if (!nextId || nextId === this.activeTargetId)
+            return false;
+        const title = this.windows.find((w) => w.id === nextId)?.title ?? nextId;
+        console.log(`[cdp-bridge] Follow Cursor focus → "${title}"`);
+        await this.switchWindow(nextId);
+        return true;
+    }
+    async connectActive() {
+        if (!this.activeTargetId)
+            return;
+        try {
+            const res = await fetch(`${this.config.cdpUrl}/json`);
+            const targets = (await res.json());
+            const target = targets.find((t) => t.id === this.activeTargetId);
+            if (!target?.webSocketDebuggerUrl) {
+                throw new Error('Target not found');
+            }
+            this.client?.disconnect();
+            const client = new CdpClient();
+            client.on('disconnected', () => {
+                this.emit('disconnected');
+                this.scheduleReconnect();
+            });
+            await client.connect(target.webSocketDebuggerUrl);
+            this.client = client;
+            this.backoffMs = 1000;
+            this.emit('connected');
+            console.log(`[cdp-bridge] Connected: ${target.title}`);
+        }
+        catch (err) {
+            console.warn('[cdp-bridge] connect failed:', err.message);
+            this.emit('disconnected');
+            this.scheduleReconnect();
+        }
+    }
+    scheduleReconnect() {
+        if (this.reconnectTimer)
+            return;
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = null;
+            void this.connectActive();
+        }, this.backoffMs);
+        this.backoffMs = Math.min(this.backoffMs * 2, 30_000);
+    }
+}
+function parseWindowTitle(title) {
+    return title.replace(/\s*-\s*Cursor\s*$/i, '').trim();
+}

package/bridge-runtime/dist/cdp-client.d.ts

@@ -0,0 +1,24 @@
+import { EventEmitter } from 'events';
+export declare class CdpClient extends EventEmitter {
+    private ws;
+    private nextId;
+    private pending;
+    private _connected;
+    connect(wsUrl: string): Promise<void>;
+    disconnect(): void;
+    isConnected(): boolean;
+    send(method: string, params?: Record<string, unknown>, timeoutMs?: number): Promise<Record<string, unknown>>;
+    /**
+     * Evaluate a self-contained function in the page.
+     * Injects __name shim — regex strip of __name() breaks nested helpers (see TROUBLESHOOTING).
+     */
+    callFunction(fn: (...args: unknown[]) => unknown, ...args: unknown[]): Promise<unknown>;
+    evaluate(expression: string, timeoutMs?: number): Promise<unknown>;
+    typeText(text: string): Promise<void>;
+    pressKey(key: string, code: string, keyCode: number, modifiers?: number): Promise<void>;
+    /** Attach local image files to Cursor composer via hidden file input. */
+    attachComposerImages(filePaths: string[]): Promise<void>;
+    click(selectorPath: string): Promise<void>;
+    private handleMessage;
+    private rejectAll;
+}

package/bridge-runtime/dist/cdp-client.js

@@ -0,0 +1,145 @@
+import { EventEmitter } from 'events';
+import { WebSocket } from 'ws';
+const DEFAULT_TIMEOUT_MS = 10000;
+export class CdpClient extends EventEmitter {
+    ws = null;
+    nextId = 1;
+    pending = new Map();
+    _connected = false;
+    async connect(wsUrl) {
+        return new Promise((resolve, reject) => {
+            this.ws = new WebSocket(wsUrl);
+            this.ws.on('open', () => {
+                this._connected = true;
+                resolve();
+            });
+            this.ws.on('error', (err) => {
+                if (!this._connected)
+                    reject(err);
+            });
+            this.ws.on('message', (data) => this.handleMessage(data.toString()));
+            this.ws.on('close', () => {
+                const was = this._connected;
+                this._connected = false;
+                this.rejectAll('WebSocket closed');
+                if (was)
+                    this.emit('disconnected');
+            });
+        });
+    }
+    disconnect() {
+        this._connected = false;
+        this.rejectAll('disconnect');
+        this.ws?.close();
+        this.ws = null;
+    }
+    isConnected() {
+        return this._connected;
+    }
+    async send(method, params, timeoutMs = DEFAULT_TIMEOUT_MS) {
+        if (!this.ws || !this._connected)
+            throw new Error('CDP not connected');
+        const id = this.nextId++;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new Error(`CDP timeout: ${method}`));
+            }, timeoutMs);
+            this.pending.set(id, { resolve, reject, timer });
+            this.ws.send(JSON.stringify({ id, method, params }));
+        });
+    }
+    /**
+     * Evaluate a self-contained function in the page.
+     * Injects __name shim — regex strip of __name() breaks nested helpers (see TROUBLESHOOTING).
+     */
+    async callFunction(fn, ...args) {
+        const argStr = args.map((a) => JSON.stringify(a)).join(', ');
+        const shim = 'var __name=function(fn,_n){return fn;};';
+        return this.evaluate(`${shim}(${fn.toString()})(${argStr})`);
+    }
+    async evaluate(expression, timeoutMs = DEFAULT_TIMEOUT_MS) {
+        const result = await this.send('Runtime.evaluate', { expression, returnByValue: true, awaitPromise: true }, timeoutMs);
+        const ex = result.exceptionDetails;
+        if (ex) {
+            throw new Error(ex.exception?.description ?? ex.text ?? 'evaluate failed');
+        }
+        return result.result?.value;
+    }
+    async typeText(text) {
+        await this.send('Input.insertText', { text });
+    }
+    async pressKey(key, code, keyCode, modifiers = 0) {
+        const base = {
+            key,
+            code,
+            windowsVirtualKeyCode: keyCode,
+            nativeVirtualKeyCode: keyCode,
+            modifiers,
+        };
+        await this.send('Input.dispatchKeyEvent', { type: 'keyDown', ...base });
+        await this.send('Input.dispatchKeyEvent', { type: 'keyUp', ...base });
+    }
+    /** Attach local image files to Cursor composer via hidden file input. */
+    async attachComposerImages(filePaths) {
+        if (filePaths.length === 0)
+            return;
+        await this.send('DOM.enable', {});
+        const doc = (await this.send('DOM.getDocument', { depth: 0 }));
+        const rootId = doc.root?.nodeId;
+        if (!rootId)
+            throw new Error('DOM root not found');
+        const selectors = [
+            '[class*="agent-panel"] input[type="file"][accept*="image"]',
+            '[class*="composer-panel"] input[type="file"][accept*="image"]',
+            '.composer-bar input[type="file"]',
+            '[class*="composer-bar"] input[type="file"]',
+            'input[type="file"][accept*="image"]',
+        ];
+        let nodeId = 0;
+        for (const selector of selectors) {
+            const hit = (await this.send('DOM.querySelector', {
+                nodeId: rootId,
+                selector,
+            }));
+            if (hit.nodeId) {
+                nodeId = hit.nodeId;
+                break;
+            }
+        }
+        if (!nodeId)
+            throw new Error('Composer file input not found');
+        await this.send('DOM.setFileInputFiles', { nodeId, files: filePaths });
+    }
+    async click(selectorPath) {
+        await this.evaluate(`
+      (() => {
+        const el = document.querySelector(${JSON.stringify(selectorPath)});
+        if (!el) throw new Error('Element not found');
+        el.scrollIntoView({ block: 'center', behavior: 'instant' });
+        el.click();
+      })()
+    `);
+    }
+    handleMessage(raw) {
+        const msg = JSON.parse(raw);
+        if (msg.id == null)
+            return;
+        const p = this.pending.get(msg.id);
+        if (!p)
+            return;
+        clearTimeout(p.timer);
+        this.pending.delete(msg.id);
+        if (msg.error)
+            p.reject(new Error(msg.error.message));
+        else
+            p.resolve(msg.result ?? {});
+    }
+    rejectAll(reason) {
+        for (const [, p] of this.pending) {
+            clearTimeout(p.timer);
+            p.reject(new Error(reason));
+        }
+        this.pending.clear();
+    }
+}

package/bridge-runtime/dist/chat-display-store.d.ts

@@ -0,0 +1,13 @@
+import type { ChatMessage, HistoryMessage } from './types.js';
+/** Per-agent prepared history + merge with live DOM for subscribed chat. */
+export declare class ChatDisplayStore {
+    private historyByAgent;
+    clearAgent(agentId: string): void;
+    /** JSONL / HTTP / socket history — returns display-ready messages. */
+    applyHistory(agentId: string, rows: HistoryMessage[], opts?: {
+        mergeWithCache?: boolean;
+    }): ChatMessage[];
+    getHistory(agentId: string): ChatMessage[];
+    /** Raw DOM extract for active composer → merged display list when history exists. */
+    mergeLiveForAgent(agentId: string, rawDom: ChatMessage[]): ChatMessage[];
+}

package/bridge-runtime/dist/chat-display-store.js

@@ -0,0 +1,29 @@
+import { filterClientDisplayList, historyRowsToChat, mergeDomWithHistory, mergeHistoryTail, prepareChatMessagesForDisplay, } from './chat-display.js';
+/** Per-agent prepared history + merge with live DOM for subscribed chat. */
+export class ChatDisplayStore {
+    historyByAgent = new Map();
+    clearAgent(agentId) {
+        this.historyByAgent.delete(agentId);
+    }
+    /** JSONL / HTTP / socket history — returns display-ready messages. */
+    applyHistory(agentId, rows, opts) {
+        const incoming = prepareChatMessagesForDisplay(historyRowsToChat(rows));
+        const prev = this.historyByAgent.get(agentId) ?? [];
+        const merged = opts?.mergeWithCache && prev.length
+            ? mergeHistoryTail(prev, incoming)
+            : incoming;
+        const out = filterClientDisplayList(merged);
+        this.historyByAgent.set(agentId, out);
+        return out;
+    }
+    getHistory(agentId) {
+        return this.historyByAgent.get(agentId) ?? [];
+    }
+    /** Raw DOM extract for active composer → merged display list when history exists. */
+    mergeLiveForAgent(agentId, rawDom) {
+        const live = prepareChatMessagesForDisplay(rawDom);
+        const hist = this.historyByAgent.get(agentId) ?? [];
+        const merged = hist.length ? mergeDomWithHistory(hist, live) : live;
+        return filterClientDisplayList(merged);
+    }
+}

package/bridge-runtime/dist/chat-display.d.ts

@@ -0,0 +1,11 @@
+import type { ChatMessage, HistoryMessage } from './types.js';
+export declare function compareUserText(text: string): string;
+export declare function userTextsEquivalent(ta: string, tb: string): boolean;
+export declare function userMessagesEquivalent(a: ChatMessage, b: ChatMessage): boolean;
+export declare function sortMessagesChronologically(messages: ChatMessage[]): ChatMessage[];
+export declare function prepareChatMessagesForDisplay(messages: ChatMessage[]): ChatMessage[];
+export declare function mergeHistoryTail(prev: ChatMessage[], incoming: ChatMessage[]): ChatMessage[];
+export declare function mergeDomWithHistory(history: ChatMessage[], live: ChatMessage[]): ChatMessage[];
+export declare function historyRowsToChat(rows: HistoryMessage[]): ChatMessage[];
+export declare function filterClientDisplayList(messages: ChatMessage[]): ChatMessage[];
+export declare function userMessageCoversExisting(existing: ChatMessage, sentText: string): boolean;