cursorconnect 0.1.0 → 0.1.4

package/bridge-runtime/dist/relay.js

@@ -0,0 +1,626 @@
+import express from 'express';
+import { createServer } from 'http';
+import { randomBytes, timingSafeEqual } from 'crypto';
+import { basename } from 'path';
+import { readAllowedMediaFile, resolveMediaPathParam } from './media-path.js';
+import { Server as SocketServer } from 'socket.io';
+import { ChatDisplayStore } from './chat-display-store.js';
+import { filterClientDisplayList, prepareChatMessagesForDisplay, } from './chat-display.js';
+import { isChatSyncedWithCursor } from './chat-sync.js';
+import { mergeSidebarWithJsonl } from './sidebar-merge.js';
+import { transcribeAudioBuffer } from './openai-transcribe.js';
+import { extensionForMime, saveUploadedImage } from './image-upload-store.js';
+import { RelayUpstream } from './relay-upstream.js';
+import { bridgePipelineLog, bridgePipelineReportLines, bridgePipelineSnapshot, } from './history-pipeline-log.js';
+export class Relay {
+    stateManager;
+    commandExecutor;
+    cdpBridge;
+    jsonlIndex;
+    messageDebugStore;
+    domExtractor;
+    lastJsonlIndex = { repos: [], updatedAt: 0 };
+    indexEmitTimer = null;
+    lastIndexBroadcastAt = 0;
+    lastSidebarIndexKey = '';
+    lastJsonlIndexKey = '';
+    config;
+    app = express();
+    httpServer = createServer(this.app);
+    io;
+    tokens = new Set();
+    upstream = null;
+    chatDisplay = new ChatDisplayStore();
+    constructor(config, stateManager, commandExecutor, cdpBridge, jsonlIndex, messageDebugStore, domExtractor) {
+        this.stateManager = stateManager;
+        this.commandExecutor = commandExecutor;
+        this.cdpBridge = cdpBridge;
+        this.jsonlIndex = jsonlIndex;
+        this.messageDebugStore = messageDebugStore;
+        this.domExtractor = domExtractor;
+        this.config = config;
+        this.io = new SocketServer(this.httpServer, {
+            cors: { origin: true, credentials: true },
+            maxHttpBufferSize: 20e6,
+        });
+        this.setupHttp();
+        this.setupSocket();
+        this.wireEvents();
+        if (this.config.relayUrl) {
+            if (!this.config.relayToken) {
+                console.warn('[relay] RELAY_URL set but RELAY_TOKEN empty — upstream disabled');
+            }
+            else {
+                this.upstream = new RelayUpstream(this.config, (event, ...args) => {
+                    this.handleRemoteClientEvent(event, ...args);
+                });
+                this.upstream.connect();
+            }
+        }
+    }
+    listen() {
+        return new Promise((resolve) => {
+            this.httpServer.listen(this.config.serverPort, this.config.serverHost, () => {
+                console.log(`[relay] http://${this.config.serverHost}:${this.config.serverPort}`);
+                resolve();
+            });
+        });
+    }
+    get authEnabled() {
+        return this.config.webappPassword.length > 0;
+    }
+    checkMediaAuth(req) {
+        if (!this.authEnabled)
+            return true;
+        const token = (typeof req.query.token === 'string' ? req.query.token : undefined) ||
+            (typeof req.headers.authorization === 'string'
+                ? req.headers.authorization.replace(/^Bearer\s+/i, '')
+                : undefined);
+        return Boolean(token && this.tokens.has(token));
+    }
+    setupHttp() {
+        this.app.get('/health', (_req, res) => {
+            res.json({ ok: true, cdp: this.cdpBridge.getClient()?.isConnected() ?? false });
+        });
+        this.app.get('/debug/messages', (_req, res) => {
+            const state = this.stateManager.getState();
+            res.json({
+                latest: this.messageDebugStore.latest(),
+                history: this.messageDebugStore.list(),
+                activeComposerId: state.activeComposerId,
+                domMessageCount: state.messages.length,
+                lastError: state.lastError,
+            });
+        });
+        this.app.get('/api/agents/index', async (req, res) => {
+            if (!this.checkMediaAuth(req)) {
+                res.status(401).json({ error: 'Unauthorized' });
+                return;
+            }
+            try {
+                const stale = Date.now() - (this.lastJsonlIndex.updatedAt ?? 0) > 60_000;
+                const index = this.lastJsonlIndex.repos.length && !stale
+                    ? this.lastJsonlIndex
+                    : await this.jsonlIndex.rebuild({ broadcast: false });
+                this.lastJsonlIndex = index;
+                const merged = mergeSidebarWithJsonl(this.stateManager.getState().sidebarRepos, index, this.stateManager.getState().composerIdByTitle);
+                const bytes = JSON.stringify(merged).length;
+                bridgePipelineLog({
+                    dir: 'out',
+                    event: 'http:agents:index',
+                    bytes,
+                    detail: `repos=${merged.repos?.length ?? 0}`,
+                });
+                res.json(merged);
+            }
+            catch (err) {
+                res.status(500).json({ error: err.message });
+            }
+        });
+        this.app.get('/api/agents/history', async (req, res) => {
+            if (!this.checkMediaAuth(req)) {
+                res.status(401).json({ error: 'Unauthorized' });
+                return;
+            }
+            const agentId = String(req.query.agentId ?? '').trim();
+            const title = typeof req.query.title === 'string' ? req.query.title.trim() : undefined;
+            const limitRaw = Number(req.query.limit ?? 0);
+            const limit = Number.isFinite(limitRaw) && limitRaw > 0 ? limitRaw : undefined;
+            const requestId = typeof req.query.requestId === 'string' ? req.query.requestId.trim() : undefined;
+            if (!agentId) {
+                res.status(400).json({ error: 'agentId required' });
+                return;
+            }
+            bridgePipelineLog({
+                dir: 'in',
+                event: 'http:agents:history',
+                requestId,
+                agentId,
+                detail: `limit=${limit ?? 'all'} title=${title?.slice(0, 32) ?? '-'}`,
+            });
+            try {
+                const history = await this.jsonlIndex.loadHistory(agentId, {
+                    title,
+                    composerIdByTitle: this.stateManager.getState().composerIdByTitle,
+                    limit,
+                });
+                const messages = this.chatDisplay.applyHistory(agentId, history.messages);
+                const body = { ...history, messages, requestId, updatedAt: Date.now() };
+                const bytes = JSON.stringify(body).length;
+                bridgePipelineLog({
+                    dir: 'out',
+                    event: 'http:agents:history',
+                    requestId,
+                    agentId,
+                    bytes,
+                    msgs: history.messages?.length ?? 0,
+                    detail: `total=${history.totalMessages ?? '?'}`,
+                });
+                res.json(body);
+            }
+            catch (err) {
+                bridgePipelineLog({
+                    dir: 'internal',
+                    event: 'http:agents:history:ERR',
+                    requestId,
+                    agentId,
+                    detail: err.message,
+                });
+                res.status(500).json({ error: err.message });
+            }
+        });
+        this.app.get('/api/debug/history-pipeline', (_req, res) => {
+            res.json({
+                ok: true,
+                at: Date.now(),
+                lines: bridgePipelineReportLines(),
+                entries: bridgePipelineSnapshot(),
+            });
+        });
+        this.app.get('/media/file', (req, res) => {
+            if (!this.checkMediaAuth(req)) {
+                res.status(401).json({ error: 'Unauthorized' });
+                return;
+            }
+            const filePath = resolveMediaPathParam(String(req.query.path ?? ''));
+            if (!filePath) {
+                res.status(400).json({ error: 'path required' });
+                return;
+            }
+            const file = readAllowedMediaFile(filePath);
+            if (!file) {
+                res.status(404).json({ error: 'Not found' });
+                return;
+            }
+            res.setHeader('Content-Type', file.contentType);
+            res.setHeader('Cache-Control', 'private, max-age=3600');
+            res.send(file.data);
+        });
+        this.app.post('/api/upload-image', express.json({ limit: '12mb' }), async (req, res) => {
+            if (!this.checkMediaAuth(req)) {
+                res.status(401).json({ error: 'Unauthorized' });
+                return;
+            }
+            const imageB64 = String(req.body?.imageBase64 ?? '');
+            const mimeType = String(req.body?.mimeType ?? 'image/jpeg');
+            if (!imageB64) {
+                res.status(400).json({ error: 'imageBase64 required' });
+                return;
+            }
+            let buffer;
+            try {
+                buffer = Buffer.from(imageB64, 'base64');
+            }
+            catch {
+                res.status(400).json({ error: 'Invalid imageBase64' });
+                return;
+            }
+            if (buffer.length < 32) {
+                res.status(400).json({ error: 'Image too small' });
+                return;
+            }
+            if (buffer.length > 10 * 1024 * 1024) {
+                res.status(413).json({ error: 'Image too large (max 10 MB)' });
+                return;
+            }
+            if (!extensionForMime(mimeType)) {
+                res.status(400).json({ error: 'Unsupported image type' });
+                return;
+            }
+            try {
+                const path = await saveUploadedImage(buffer, mimeType);
+                res.json({ path });
+            }
+            catch (err) {
+                res.status(500).json({ error: err.message });
+            }
+        });
+        this.app.post('/api/transcribe', express.json({ limit: '12mb' }), async (req, res) => {
+            if (!this.checkMediaAuth(req)) {
+                res.status(401).json({ error: 'Unauthorized' });
+                return;
+            }
+            const apiKey = this.config.openaiApiKey;
+            if (!apiKey) {
+                res.status(503).json({
+                    error: 'OPENAI_API_KEY not set on bridge (add to bridge/.env)',
+                });
+                return;
+            }
+            const audioB64 = String(req.body?.audioBase64 ?? '');
+            const mimeType = String(req.body?.mimeType ?? 'audio/m4a');
+            if (!audioB64) {
+                res.status(400).json({ error: 'audioBase64 required' });
+                return;
+            }
+            let audio;
+            try {
+                audio = Buffer.from(audioB64, 'base64');
+            }
+            catch {
+                res.status(400).json({ error: 'Invalid audioBase64' });
+                return;
+            }
+            if (audio.length < 32) {
+                res.status(400).json({ error: 'Recording too short' });
+                return;
+            }
+            if (audio.length > 10 * 1024 * 1024) {
+                res.status(413).json({ error: 'Recording too large (max 10 MB)' });
+                return;
+            }
+            try {
+                const text = await transcribeAudioBuffer(apiKey, audio, mimeType, this.config.openaiTranscribeModel);
+                res.json({ text });
+            }
+            catch (err) {
+                console.warn('[relay] transcribe:', err.message);
+                res.status(502).json({ error: err.message });
+            }
+        });
+        this.app.post('/api/login', express.json(), (req, res) => {
+            if (!this.authEnabled) {
+                res.json({ token: 'open' });
+                return;
+            }
+            const pw = String(req.body?.password ?? '');
+            const expected = Buffer.from(this.config.webappPassword);
+            const got = Buffer.from(pw);
+            if (expected.length !== got.length || !timingSafeEqual(expected, got)) {
+                res.status(401).json({ error: 'Invalid password' });
+                return;
+            }
+            const token = randomBytes(24).toString('hex');
+            this.tokens.add(token);
+            res.json({ token });
+        });
+    }
+    setupSocket() {
+        this.io.use((socket, next) => {
+            if (!this.authEnabled)
+                return next();
+            const token = socket.handshake.auth?.token;
+            if (token && this.tokens.has(token))
+                return next();
+            return next(new Error('Unauthorized'));
+        });
+        this.io.on('connection', (socket) => this.onConnect(socket));
+    }
+    broadcast(event, payload) {
+        if (event === 'agents:history' || event === 'agent:history') {
+            const h = payload;
+            const bytes = JSON.stringify(payload ?? {}).length;
+            bridgePipelineLog({
+                dir: 'out',
+                event: `broadcast:${event}`,
+                requestId: h?.requestId,
+                agentId: h?.agentId,
+                bytes,
+                msgs: h?.messages?.length ?? 0,
+                detail: `upstream=${this.upstream?.connected ?? false}`,
+            });
+        }
+        this.io.emit(event, payload);
+        this.upstream?.emit(event, payload);
+    }
+    prepareStateMessages(raw, patch) {
+        const state = { ...this.stateManager.getState(), ...patch };
+        for (const [agentId, meta] of this.jsonlIndex.getSubscribedAgents()) {
+            if (isChatSyncedWithCursor(agentId, meta.title, state)) {
+                return this.chatDisplay.mergeLiveForAgent(agentId, raw);
+            }
+        }
+        return filterClientDisplayList(prepareChatMessagesForDisplay(raw));
+    }
+    withDisplayState(payload) {
+        if (!payload.messages?.length)
+            return payload;
+        return {
+            ...payload,
+            messages: this.prepareStateMessages(payload.messages, payload),
+        };
+    }
+    wireEvents() {
+        this.stateManager.on('state:full', (state) => {
+            this.broadcast('state:full', this.withDisplayState(state));
+            this.emitAgentsIndex();
+        });
+        this.stateManager.on('state:patch', (patch) => {
+            this.broadcast('state:patch', this.withDisplayState(patch));
+            if (patch.sidebarRepos || patch.composerIdByTitle) {
+                const key = JSON.stringify([patch.sidebarRepos, patch.composerIdByTitle]);
+                if (key !== this.lastSidebarIndexKey) {
+                    this.lastSidebarIndexKey = key;
+                    this.emitAgentsIndex();
+                }
+            }
+        });
+        this.jsonlIndex.on('agents:index', (index) => {
+            const key = JSON.stringify(index.repos?.map((r) => [r.id, r.agents.length]));
+            if (key === this.lastJsonlIndexKey)
+                return;
+            this.lastJsonlIndexKey = key;
+            this.lastJsonlIndex = index;
+            this.emitAgentsIndex();
+        });
+        this.jsonlIndex.on('agent:history', (history) => {
+            const messages = this.chatDisplay.applyHistory(history.agentId, history.messages, {
+                mergeWithCache: true,
+            });
+            this.broadcast('agent:history', { ...history, messages });
+        });
+    }
+    emitAgentsIndex(force = false) {
+        const send = () => {
+            const merged = mergeSidebarWithJsonl(this.stateManager.getState().sidebarRepos, this.lastJsonlIndex, this.stateManager.getState().composerIdByTitle);
+            this.broadcast('agents:index', merged);
+            this.lastIndexBroadcastAt = Date.now();
+        };
+        if (force) {
+            if (this.indexEmitTimer)
+                clearTimeout(this.indexEmitTimer);
+            this.indexEmitTimer = null;
+            send();
+            return;
+        }
+        const elapsed = Date.now() - this.lastIndexBroadcastAt;
+        if (elapsed >= 60_000) {
+            send();
+            return;
+        }
+        if (this.indexEmitTimer)
+            return;
+        this.indexEmitTimer = setTimeout(() => {
+            this.indexEmitTimer = null;
+            send();
+        }, 60_000 - elapsed);
+    }
+    refreshAgentsIndex(force = false) {
+        void this.jsonlIndex.rebuild({ broadcast: false }).then((index) => {
+            this.lastJsonlIndex = index;
+            this.emitAgentsIndex(force);
+        });
+    }
+    pushFullStateToRemote() {
+        this.broadcast('state:full', this.withDisplayState(this.stateManager.getState()));
+        if (this.lastJsonlIndex.updatedAt > 0) {
+            this.emitAgentsIndex(true);
+            return;
+        }
+        this.refreshAgentsIndex(true);
+    }
+    async trySwitchWindowForAgent(agentId) {
+        const projectDir = this.jsonlIndex.findProjectDirForAgent(agentId);
+        if (!projectDir)
+            return;
+        const folder = basename(projectDir);
+        const repoSlug = folder.includes('-Projects-')
+            ? (folder.split('-Projects-').pop() ?? '')
+            : folder;
+        const repoName = repoSlug.replace(/-/g, ' ').toLowerCase();
+        if (!repoName)
+            return;
+        await this.cdpBridge.refreshWindows();
+        const match = this.cdpBridge.windows.find((w) => {
+            const t = w.title.toLowerCase();
+            return t.includes(repoName) || repoName.split(' ').every((wrd) => t.includes(wrd));
+        });
+        if (match && match.id !== this.cdpBridge.activeTargetId) {
+            await this.cdpBridge.switchWindow(match.id);
+            console.log(`[relay] CDP → window "${match.title}" for agent ${agentId.slice(0, 8)}`);
+        }
+    }
+    handleRemoteClientEvent(event, ...args) {
+        if (event === 'relay:sync') {
+            this.pushFullStateToRemote();
+            return;
+        }
+        const reply = (ev, payload) => this.broadcast(ev, payload);
+        this.dispatchClientEvent(event, args, reply);
+    }
+    onConnect(socket) {
+        socket.emit('state:full', this.withDisplayState(this.stateManager.getState()));
+        const sendIndex = (index) => {
+            socket.emit('agents:index', mergeSidebarWithJsonl(this.stateManager.getState().sidebarRepos, index, this.stateManager.getState().composerIdByTitle));
+        };
+        if (this.lastJsonlIndex.updatedAt > 0) {
+            sendIndex(this.lastJsonlIndex);
+        }
+        else {
+            void this.jsonlIndex.rebuild({ broadcast: false }).then((index) => {
+                this.lastJsonlIndex = index;
+                sendIndex(index);
+            });
+        }
+        const reply = (ev, payload) => {
+            socket.emit(ev, payload);
+        };
+        socket.on('command', async (payload) => {
+            await this.runCommand(payload, reply);
+        });
+        socket.on('agents:history', async (data) => {
+            await this.runAgentsHistory(data, reply);
+        });
+        socket.on('agents:subscribe', async (data) => {
+            await this.runAgentsSubscribe(data);
+        });
+        socket.on('agents:unsubscribe', (data) => {
+            this.runAgentsUnsubscribe(data);
+        });
+        socket.on('agents:focus', async (data) => {
+            await this.runAgentsFocus(data, reply);
+        });
+        socket.on('agents:refresh', () => {
+            this.refreshAgentsIndex(true);
+        });
+        socket.on('disconnect', () => {
+            /* subscriptions stay global — one phone session typical */
+        });
+    }
+    dispatchClientEvent(event, args, reply) {
+        if (event === 'command') {
+            void this.runCommand(args[0], reply);
+            return;
+        }
+        if (event === 'agents:history') {
+            void this.runAgentsHistory(args[0], reply);
+            return;
+        }
+        if (event === 'agents:subscribe') {
+            void this.runAgentsSubscribe(args[0]);
+            return;
+        }
+        if (event === 'agents:unsubscribe') {
+            this.runAgentsUnsubscribe(args[0]);
+            return;
+        }
+        if (event === 'agents:focus') {
+            void this.runAgentsFocus(args[0], reply);
+            return;
+        }
+        if (event === 'agents:refresh') {
+            this.refreshAgentsIndex(true);
+        }
+    }
+    async runCommand(payload, reply) {
+        console.log(`[relay] command ${payload.type} id=${payload.id}`);
+        if (payload.type === 'switch_window' && payload.windowId) {
+            await this.cdpBridge.refreshWindows();
+            await this.cdpBridge.switchWindow(payload.windowId);
+            this.stateManager.patchNow({
+                windows: this.cdpBridge.windows,
+                activeWindowId: this.cdpBridge.activeTargetId,
+            });
+            this.domExtractor.pollNow();
+            return;
+        }
+        const result = await this.commandExecutor.execute(payload);
+        reply('command:result', result);
+        if (payload.type === 'stop_agent' && result.ok) {
+            this.stateManager.patchNow({
+                agentWorking: false,
+                agentStatus: undefined,
+                agentStatusMessage: undefined,
+                composerDraft: undefined,
+                composerDraftImages: undefined,
+            });
+            this.domExtractor.pollNow();
+        }
+    }
+    async runAgentsHistory({ agentId, title, requestId, limit, }, reply) {
+        const t0 = Date.now();
+        const viaUpstream = this.upstream?.connected ?? false;
+        const socketLimit = limit && limit > 0 ? limit : 15;
+        console.log(`[relay] agents:history req agentId=${agentId} title=${title?.slice(0, 48) ?? '-'} limit=${socketLimit} rid=${requestId ?? '-'} upstream=${viaUpstream}`);
+        this.jsonlIndex.historyReplyInFlight.add(agentId);
+        bridgePipelineLog({
+            dir: 'in',
+            event: 'agents:history:req',
+            requestId,
+            agentId,
+            detail: `limit=${socketLimit} title=${title?.slice(0, 32) ?? '-'} upstream=${viaUpstream}`,
+        });
+        try {
+            const history = await this.jsonlIndex.loadHistory(agentId, {
+                title,
+                composerIdByTitle: this.stateManager.getState().composerIdByTitle,
+                limit: socketLimit,
+            });
+            const messages = this.chatDisplay.applyHistory(agentId, history.messages);
+            const ms = Date.now() - t0;
+            const bytes = JSON.stringify(messages).length;
+            console.log(`[relay] agents:history ok agentId=${history.agentId} msgs=${history.messages?.length ?? 0}/${history.totalMessages ?? '?'} bytes=${bytes} ms=${ms} rid=${requestId ?? '-'}`);
+            bridgePipelineLog({
+                dir: 'out',
+                event: 'agents:history:reply',
+                requestId,
+                agentId: history.agentId,
+                bytes,
+                msgs: history.messages?.length ?? 0,
+                detail: `total=${history.totalMessages ?? '?'} ms=${ms}`,
+            });
+            reply('agents:history', {
+                ...history,
+                messages,
+                requestId,
+                updatedAt: Date.now(),
+            });
+        }
+        catch (err) {
+            console.error(`[relay] agents:history fail agentId=${agentId} ms=${Date.now() - t0} rid=${requestId ?? '-'}:`, err.message);
+            bridgePipelineLog({
+                dir: 'internal',
+                event: 'agents:history:fail',
+                requestId,
+                agentId,
+                detail: err.message,
+            });
+            reply('agents:history', {
+                agentId,
+                messages: [],
+                totalMessages: 0,
+                requestId,
+                updatedAt: Date.now(),
+            });
+        }
+        finally {
+            this.jsonlIndex.historyReplyInFlight.delete(agentId);
+        }
+    }
+    async runAgentsSubscribe({ agentId, title, focus, }) {
+        if (!agentId)
+            return;
+        this.jsonlIndex.subscribe(agentId, title);
+        this.stateManager.patchNow({ lastError: undefined });
+        await this.trySwitchWindowForAgent(agentId);
+        if (focus === false)
+            return;
+        const result = await this.commandExecutor.execute({
+            id: `subscribe-focus-${Date.now()}`,
+            type: 'focus_agent',
+            agentId,
+            tabTitle: title,
+        });
+        if (!result.ok) {
+            console.warn('[relay] subscribe focus (non-fatal):', result.error);
+        }
+    }
+    runAgentsUnsubscribe({ agentId }) {
+        if (agentId) {
+            this.jsonlIndex.unsubscribe(agentId);
+            this.chatDisplay.clearAgent(agentId);
+        }
+    }
+    async runAgentsFocus({ agentId, title }, reply) {
+        if (!agentId)
+            return;
+        await this.trySwitchWindowForAgent(agentId);
+        const result = await this.commandExecutor.execute({
+            id: `focus-${Date.now()}`,
+            type: 'focus_agent',
+            agentId,
+            tabTitle: title,
+        });
+        reply('command:result', result);
+    }
+}

package/bridge-runtime/dist/sidebar-merge.d.ts

@@ -0,0 +1,4 @@
+import type { AgentsIndex, RepoGroup } from './types.js';
+export { normalizeAgentTitle } from './agent-title-match.js';
+/** Prefer Cursor DOM sidebar order/names; attach JSONL ids when titles match. */
+export declare function mergeSidebarWithJsonl(sidebarRepos: RepoGroup[] | undefined, jsonl: AgentsIndex, composerIdByTitle?: Record<string, string>): AgentsIndex;

package/bridge-runtime/dist/sidebar-merge.js

@@ -0,0 +1,47 @@
+import { matchJsonlAgentForSidebarTitle, normalizeAgentTitle, } from './agent-title-match.js';
+export { normalizeAgentTitle } from './agent-title-match.js';
+/** Prefer Cursor DOM sidebar order/names; attach JSONL ids when titles match. */
+export function mergeSidebarWithJsonl(sidebarRepos, jsonl, composerIdByTitle) {
+    if (!sidebarRepos?.length)
+        return { ...jsonl, listSource: 'jsonl' };
+    const byTitle = new Map();
+    for (const repo of jsonl.repos) {
+        for (const agent of repo.agents) {
+            byTitle.set(normalizeAgentTitle(agent.title), agent);
+            if (agent.preview)
+                byTitle.set(normalizeAgentTitle(agent.preview), agent);
+        }
+    }
+    const repos = sidebarRepos.map((section) => ({
+        id: section.id,
+        name: section.name,
+        path: section.path,
+        agents: section.agents.map((row) => {
+            const fuzzy = matchJsonlAgentForSidebarTitle(row.title, jsonl, composerIdByTitle);
+            if (fuzzy) {
+                return {
+                    ...fuzzy,
+                    title: row.title,
+                    isWorking: row.isWorking ?? fuzzy.isWorking,
+                    hasUnread: row.hasUnread ?? fuzzy.hasUnread,
+                    needsAttention: row.needsAttention ?? fuzzy.needsAttention,
+                };
+            }
+            const match = byTitle.get(normalizeAgentTitle(row.title));
+            if (match) {
+                return {
+                    ...match,
+                    title: row.title,
+                    isWorking: row.isWorking ?? match.isWorking,
+                    hasUnread: row.hasUnread ?? match.hasUnread,
+                    needsAttention: row.needsAttention ?? match.needsAttention,
+                };
+            }
+            return {
+                ...row,
+                id: row.id || `title:${normalizeAgentTitle(row.title)}`,
+            };
+        }),
+    }));
+    return { repos, updatedAt: Date.now(), listSource: 'sidebar' };
+}

package/bridge-runtime/dist/state-manager.d.ts

@@ -0,0 +1,19 @@
+import { EventEmitter } from 'events';
+import type { CursorState, CursorWindow, WindowSnapshot } from './types.js';
+export declare class StateManager extends EventEmitter {
+    private state;
+    private debounceMs;
+    private debounceTimer;
+    private pendingPatch;
+    constructor(debounceMs: number);
+    getState(): CursorState;
+    onExtraction(partial: CursorState | null, error?: string): void;
+    onConnectionChanged(connected: boolean): void;
+    updateWindows(windows: CursorWindow[], activeWindowId: string): void;
+    updateWindowSnapshots(snapshots: WindowSnapshot[]): void;
+    private queuePatch;
+    /** Immediate patch (e.g. after stop_agent) — skips debounce wait. */
+    patchNow(patch: Partial<CursorState>): void;
+    private flush;
+    emitFull(): void;
+}