yoke-mcp 0.1.0

package/extension/browser/background.js

@@ -0,0 +1,371 @@
+import { attach, clickAt, consoleFor, detach, evaluate, insertText, networkFor, pressKey as dispatchKey, screenshot as capture, scrollBy, } from './cdp.js';
+import { collectSnapshot, locateRef } from './snapshot.js';
+// Must match HOST_NAME in ../install.ts exactly: Chrome matches the string
+// against the manifest filename it was registered under.
+const HOST = 'io.github.hamzahamidi.yoke';
+/** How long to wait for a navigation to report complete before giving up on it. */
+const NAVIGATE_TIMEOUT_MS = 20_000;
+let port;
+/** chrome.tabs ids are SessionID::id(), the same numbers Chrome's session file records. */
+const describeTab = (tab) => ({
+    id: tab.id ?? -1,
+    windowId: tab.windowId,
+    groupId: tab.groupId ?? -1,
+    title: tab.title ?? '',
+    url: tab.url ?? tab.pendingUrl ?? '',
+});
+const describeGroup = (group) => ({
+    id: group.id,
+    title: group.title ?? '',
+    color: group.color,
+    windowId: group.windowId,
+    collapsed: group.collapsed,
+});
+/**
+ * Waits for a tab to finish loading.
+ *
+ * Resolving on `status === 'complete'` rather than on the navigate call
+ * returning, because chrome.tabs.update resolves as soon as the navigation is
+ * *started*. Returning then would have every caller racing the page it just
+ * asked for.
+ */
+function waitForLoad(tabId, timeoutMs) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const finish = (outcome) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            chrome.tabs.onUpdated.removeListener(listener);
+            clearTimeout(timer);
+            resolve(outcome);
+        };
+        const listener = (changedId, change) => {
+            if (changedId === tabId && change.status === 'complete') {
+                finish('complete');
+            }
+        };
+        const timer = setTimeout(() => finish('timeout'), timeoutMs);
+        chrome.tabs.onUpdated.addListener(listener);
+        // The load may already have finished between the update and this listener.
+        void chrome.tabs.get(tabId).then((tab) => {
+            if (tab.status === 'complete') {
+                finish('complete');
+            }
+        }).catch(() => finish('timeout'));
+    });
+}
+async function navigate(args) {
+    const { tabId, url } = args;
+    await chrome.tabs.update(tabId, { url });
+    const status = await waitForLoad(tabId, args.timeoutMs ?? NAVIGATE_TIMEOUT_MS);
+    const tab = await chrome.tabs.get(tabId);
+    return { tabId, url: tab.url ?? url, title: tab.title ?? '', status };
+}
+/**
+ * The label on the group holding tabs yoke opened.
+ *
+ * The tool's own name rather than a generic word: the pill exists to tell the
+ * person which thing is working in their browser, and "agent" answers that with
+ * nothing. Overridable per call, because someone running two of these at once
+ * needs to tell them apart.
+ */
+const DEFAULT_GROUP_TITLE = 'yoke';
+/**
+ * The group with this title, creating it only if none exists.
+ *
+ * Reuse is keyed on the title within one window, which is the whole point: a
+ * fresh group per call is exactly how the bridge this replaces left four
+ * identical `Claude (MCP)` pills in the tab strip with no way to tell them
+ * apart. Safe to do freely because nothing addresses a tab through its group.
+ */
+async function ensureGroup(tabIds, title, windowId, color) {
+    // Scoped to one window because a group lives in one: a TabGroup carries a
+    // single windowId. A query by title alone can match a group in a different
+    // window, and joining that one would haul the tab out of the window it was
+    // opened in, which is the rearranging this is meant to avoid.
+    const existing = await chrome.tabGroups.query({ title, windowId });
+    // Matched exactly rather than taken from the query, because query treats the
+    // title as a pattern: a caller passing "*" would otherwise adopt and rename
+    // whichever group it happened to match, which is the opposite of only ever
+    // touching what we were pointed at.
+    const found = existing.find((group) => group.title === title);
+    const groupId = found === undefined
+        ? await chrome.tabs.group({ tabIds })
+        : await chrome.tabs.group({ tabIds, groupId: found.id });
+    await chrome.tabGroups.update(groupId, {
+        title,
+        ...(color === undefined ? {} : { color }),
+    });
+    const group = await chrome.tabGroups.get(groupId);
+    return { groupId, title: group.title ?? title };
+}
+async function openTab(args) {
+    const created = await chrome.tabs.create({
+        ...(args.url === undefined ? {} : { url: args.url }),
+        // Defaults to a background tab: opening something in a script should not
+        // yank focus away from whatever the person is doing.
+        active: args.active ?? false,
+        ...(args.windowId === undefined ? {} : { windowId: args.windowId }),
+    });
+    if (created.id !== undefined && args.url !== undefined) {
+        await waitForLoad(created.id, NAVIGATE_TIMEOUT_MS);
+    }
+    const title = args.groupTitle ?? DEFAULT_GROUP_TITLE;
+    let groupId = -1;
+    let groupTitle = title;
+    if (created.id !== undefined) {
+        // Grouping is cosmetic, so a failure here must not fail the open: the tab
+        // exists and is usable whether or not the strip shows a pill.
+        try {
+            const group = await ensureGroup([created.id], title, created.windowId, 'cyan');
+            groupId = group.groupId;
+            groupTitle = group.title;
+        }
+        catch {
+            groupId = -1;
+        }
+    }
+    const tab = created.id === undefined ? created : await chrome.tabs.get(created.id);
+    return { tab: describeTab(tab), groupId, groupTitle };
+}
+/**
+ * The page's visible text.
+ *
+ * innerText rather than textContent, because textContent includes script and
+ * style bodies and ignores layout, so it returns something no reader would
+ * recognise as the page.
+ */
+async function getPageText(args) {
+    const { tabId } = args;
+    const max = args.maxChars ?? 200_000;
+    const [injected] = await chrome.scripting.executeScript({
+        target: { tabId },
+        func: () => ({
+            text: document.body?.innerText ?? '',
+            title: document.title,
+            url: location.href,
+        }),
+    });
+    const value = injected?.result;
+    if (!value) {
+        throw new Error(`nothing came back from tab ${tabId}; a chrome:// or Web Store page cannot be read`);
+    }
+    const truncated = value.text.length > max;
+    return {
+        tabId,
+        url: value.url,
+        title: value.title,
+        text: truncated ? value.text.slice(0, max) : value.text,
+        truncated,
+    };
+}
+/**
+ * Where a reference is, right now.
+ *
+ * Resolved in the page at the moment of use rather than taken from the snapshot,
+ * because a page that has scrolled since would otherwise be clicked in the wrong
+ * place, and the caller would have no way to tell.
+ */
+async function pointFor(tabId, ref) {
+    const [found] = await chrome.scripting.executeScript({
+        target: { tabId },
+        func: locateRef,
+        args: [ref],
+    });
+    const point = found?.result;
+    if (!point?.found) {
+        throw new Error(`${ref} is not on this page any more. Call read_page again: a navigation or a `
+            + 're-render invalidates every reference from the previous snapshot.');
+    }
+    return point;
+}
+async function readPage(args) {
+    const { tabId } = args;
+    const max = args.maxElements ?? 200;
+    const [injected] = await chrome.scripting.executeScript({
+        target: { tabId },
+        func: collectSnapshot,
+        args: [max],
+    });
+    const snapshot = injected?.result;
+    if (!snapshot) {
+        throw new Error(`nothing came back from tab ${tabId}; Chrome's own pages cannot be read`);
+    }
+    // Coordinates stay inside the extension. A caller acts by reference.
+    const elements = snapshot.elements.map(({ x: _x, y: _y, ...rest }) => rest);
+    return {
+        tabId,
+        url: snapshot.url,
+        title: snapshot.title,
+        elements,
+        truncated: elements.length >= max,
+    };
+}
+async function handle(message) {
+    switch (message.op) {
+        case 'ping':
+            return { extension: chrome.runtime.getManifest().version };
+        case 'listTabs':
+            return { tabs: (await chrome.tabs.query({})).map(describeTab) };
+        case 'listGroups':
+            return { groups: (await chrome.tabGroups.query({})).map(describeGroup) };
+        case 'navigate':
+            return navigate(message.args);
+        case 'openTab':
+            return openTab((message.args ?? {}));
+        case 'closeTab': {
+            const { tabId } = message.args;
+            await chrome.tabs.remove(tabId);
+            return { closed: tabId };
+        }
+        case 'getPageText':
+            return getPageText(message.args);
+        case 'readPage':
+            return readPage(message.args);
+        case 'evaluate': {
+            const { tabId, expression } = message.args;
+            const outcome = await evaluate(tabId, expression);
+            return { tabId, ...outcome };
+        }
+        case 'screenshot': {
+            const args = message.args;
+            const format = args.format ?? 'png';
+            const shot = await capture(tabId2(args.tabId), format, args.quality);
+            return {
+                tabId: args.tabId,
+                format: shot.format,
+                base64: shot.base64,
+                bytes: Math.floor((shot.base64.length * 3) / 4),
+            };
+        }
+        case 'click': {
+            const args = message.args;
+            const point = await pointFor(args.tabId, args.ref);
+            await clickAt(args.tabId, point, args.button ?? 'left', args.clickCount ?? 1);
+            // What was on top is reported rather than swallowed. CDP says an event was
+            // dispatched and nothing about what received it, so this is the only part
+            // of the answer that is a claim about the page.
+            return {
+                tabId: args.tabId,
+                ref: args.ref,
+                dispatched: true,
+                hit: point.hit ?? 'nothing',
+                ...(point.topmost === undefined ? {} : { topmost: point.topmost }),
+            };
+        }
+        case 'typeText': {
+            const args = message.args;
+            if (args.ref !== undefined) {
+                const point = await pointFor(args.tabId, args.ref);
+                await clickAt(args.tabId, point, 'left', 1);
+            }
+            await insertText(args.tabId, args.text);
+            if (args.pressEnter === true) {
+                await dispatchKey(args.tabId, 'Enter');
+            }
+            return { tabId: args.tabId, typed: args.text.length };
+        }
+        case 'pressKey': {
+            const args = message.args;
+            if (args.ref !== undefined) {
+                const point = await pointFor(args.tabId, args.ref);
+                await clickAt(args.tabId, point, 'left', 1);
+            }
+            await dispatchKey(args.tabId, args.key);
+            return { tabId: args.tabId, key: args.key };
+        }
+        case 'scroll': {
+            const args = message.args;
+            const point = args.ref === undefined
+                ? { x: 200, y: 300 }
+                : await pointFor(args.tabId, args.ref);
+            const dx = args.dx ?? 0;
+            const dy = args.dy ?? 400;
+            await scrollBy(args.tabId, point, dx, dy);
+            return { tabId: args.tabId, dx, dy };
+        }
+        case 'consoleMessages': {
+            const args = message.args;
+            const { attachedNow } = await attach(args.tabId);
+            return { tabId: args.tabId, messages: consoleFor(args.tabId, args.limit ?? 100), attachedNow };
+        }
+        case 'networkRequests': {
+            const args = message.args;
+            const { attachedNow } = await attach(args.tabId);
+            return { tabId: args.tabId, requests: networkFor(args.tabId, args.limit ?? 100), attachedNow };
+        }
+        case 'groupTabs': {
+            const args = message.args;
+            const members = await Promise.all(args.tabIds.map((id) => chrome.tabs.get(id)));
+            const first = members[0];
+            if (first === undefined) {
+                throw new Error('groupTabs needs at least one tab id');
+            }
+            // Refused rather than resolved by picking a window, because a group holds
+            // tabs from one window and the only way to satisfy this request would be
+            // to move the others there.
+            const windows = new Set(members.map((tab) => tab.windowId));
+            if (windows.size > 1) {
+                throw new Error(`those ${args.tabIds.length} tabs are spread across ${windows.size} windows, and a group `
+                    + 'holds tabs from one window. Group them a window at a time.');
+            }
+            const group = await ensureGroup(args.tabIds, args.title ?? DEFAULT_GROUP_TITLE, first.windowId, args.color);
+            return { groupId: group.groupId, title: group.title, tabIds: args.tabIds };
+        }
+        case 'ungroupTabs': {
+            const args = message.args;
+            await chrome.tabs.ungroup(args.tabIds);
+            return { tabIds: args.tabIds };
+        }
+        case 'release': {
+            const args = message.args;
+            return { tabId: args.tabId, released: await detach(args.tabId) };
+        }
+        default:
+            throw new Error(`unknown op ${String(message.op)}`);
+    }
+}
+/** Narrows a tab id that has already been validated by the server. */
+const tabId2 = (value) => value;
+function connect() {
+    if (port) {
+        return;
+    }
+    try {
+        port = chrome.runtime.connectNative(HOST);
+    }
+    catch (failure) {
+        console.log('yoke: native host unavailable', failure);
+        return;
+    }
+    port.onMessage.addListener((message) => {
+        if (message?.id === undefined) {
+            return;
+        }
+        void handle(message)
+            .then((data) => {
+            const reply = { id: message.id, ok: true, data };
+            port?.postMessage(reply);
+        })
+            .catch((thrown) => {
+            const reply = {
+                id: message.id,
+                ok: false,
+                error: thrown instanceof Error ? thrown.message : String(thrown),
+            };
+            port?.postMessage(reply);
+        });
+    });
+    // An open port keeps the service worker alive, and a dropped port means the
+    // host went away. Reconnecting on a delay is what lets `install` followed by a
+    // first call work without reloading the extension by hand.
+    port.onDisconnect.addListener(() => {
+        port = undefined;
+        setTimeout(connect, 1_000);
+    });
+}
+chrome.runtime.onStartup.addListener(connect);
+chrome.runtime.onInstalled.addListener(connect);
+connect();

package/extension/browser/cdp.js

@@ -0,0 +1,259 @@
+/** How much history to keep per tab, so a long-lived attachment cannot grow without bound. */
+const BUFFER_LIMIT = 500;
+const state = new Map();
+const stateFor = (tabId) => {
+    let existing = state.get(tabId);
+    if (!existing) {
+        existing = { console: [], network: [], attached: false, painting: false };
+        state.set(tabId, existing);
+    }
+    return existing;
+};
+const push = (buffer, entry) => {
+    buffer.push(entry);
+    if (buffer.length > BUFFER_LIMIT) {
+        buffer.shift();
+    }
+};
+/**
+ * Records console and network events for tabs we are attached to.
+ *
+ * Registered once for the whole extension rather than per tab: chrome.debugger
+ * delivers every attached target through this one listener, and adding it per
+ * attachment would leak a listener per tab.
+ */
+chrome.debugger.onEvent.addListener((source, method, params) => {
+    const tabId = source.tabId;
+    if (tabId === undefined) {
+        return;
+    }
+    const tab = state.get(tabId);
+    if (!tab) {
+        return;
+    }
+    if (method === 'Runtime.consoleAPICalled') {
+        const event = params;
+        const text = (event.args ?? [])
+            .map((arg) => (arg.value !== undefined ? String(arg.value) : arg.description ?? ''))
+            .join(' ');
+        push(tab.console, { level: event.type ?? 'log', text, at: Date.now() });
+        return;
+    }
+    if (method === 'Log.entryAdded') {
+        const entry = params.entry;
+        if (entry) {
+            push(tab.console, {
+                level: entry.level ?? 'info',
+                text: entry.text ?? '',
+                ...(entry.url === undefined ? {} : { url: entry.url }),
+                ...(entry.lineNumber === undefined ? {} : { line: entry.lineNumber }),
+                at: Date.now(),
+            });
+        }
+        return;
+    }
+    if (method === 'Runtime.exceptionThrown') {
+        const details = params
+            .exceptionDetails;
+        push(tab.console, {
+            level: 'error',
+            text: details?.exception?.description ?? details?.text ?? 'uncaught exception',
+            at: Date.now(),
+        });
+        return;
+    }
+    if (method === 'Network.requestWillBeSent') {
+        const event = params;
+        push(tab.network, {
+            method: event.request?.method ?? 'GET',
+            url: event.request?.url ?? '',
+            ...(event.type === undefined ? {} : { type: event.type }),
+            at: Date.now(),
+        });
+        return;
+    }
+    if (method === 'Network.responseReceived') {
+        const event = params;
+        // Fills in the status on the most recent matching request rather than
+        // recording a second row for the same exchange.
+        const match = [...tab.network].reverse().find((entry) => entry.url === event.response?.url);
+        if (match && event.response?.status !== undefined) {
+            match.status = event.response.status;
+        }
+    }
+});
+// Chrome detaches when a tab closes, DevTools opens, or the user dismisses the
+// infobar. Forgetting the state keeps a later attach from looking already-done.
+chrome.debugger.onDetach.addListener((source) => {
+    if (source.tabId !== undefined) {
+        state.delete(source.tabId);
+    }
+});
+chrome.tabs.onRemoved.addListener((tabId) => { state.delete(tabId); });
+const send = (tabId, method, params) => chrome.debugger.sendCommand({ tabId }, method, params);
+/**
+ * Attaches to a tab if it is not already attached, and enables the domains whose
+ * events we buffer.
+ *
+ * Idempotent, because every operation calls it: a caller should not have to know
+ * whether some earlier call already attached.
+ */
+export async function attach(tabId) {
+    const tab = stateFor(tabId);
+    if (tab.attached) {
+        return { attachedNow: false };
+    }
+    try {
+        await chrome.debugger.attach({ tabId }, '1.3');
+    }
+    catch (failure) {
+        const message = failure instanceof Error ? failure.message : String(failure);
+        // Chrome's own wording when DevTools holds the target. Worth translating,
+        // because "another debugger" is not obviously "close your DevTools".
+        if (/already attached/i.test(message)) {
+            throw new Error(`tab ${tabId} already has a debugger attached, which is usually DevTools being open on it. `
+                + 'Chrome allows one debugger client per tab, so close DevTools there and retry.');
+        }
+        throw failure;
+    }
+    tab.attached = true;
+    // Enabled together so console and network history accumulate from the moment
+    // the tab is first driven, rather than only after someone asks for them.
+    await Promise.all([
+        send(tabId, 'Runtime.enable'),
+        send(tabId, 'Log.enable'),
+        send(tabId, 'Network.enable'),
+        send(tabId, 'Page.enable'),
+    ]);
+    tab.painting = await keepPainting(tabId);
+    return { attachedNow: true };
+}
+/**
+ * Makes a tab produce frames even while it is not the selected tab.
+ *
+ * Without this, input dispatched to a tab that has never rendered goes nowhere
+ * and reports success. Nothing rejects the event: RenderWidgetHostImpl's input
+ * filter has no visibility check at all. The renderer simply never runs the
+ * frame that would process it, because the compositor stops asking for frames
+ * when the widget is not visible.
+ *
+ * setFocusEmulationEnabled takes a visible capturer handle on the WebContents,
+ * which releases that deferral while leaving the tab unselected in the strip and
+ * the window untouched. It is what Playwright sends once per page for the same
+ * reason, and it survives navigation, so once per attachment is enough.
+ *
+ * The command is experimental, so a Chrome that refuses it must still work:
+ * a screenshot takes a weaker (hidden) capturer handle that also releases the
+ * deferral, and is the measured fallback.
+ */
+async function keepPainting(tabId) {
+    try {
+        await send(tabId, 'Emulation.setFocusEmulationEnabled', { enabled: true });
+        return true;
+    }
+    catch {
+        try {
+            await send(tabId, 'Page.captureScreenshot', { format: 'jpeg', quality: 1 });
+        }
+        catch { /* Nothing else to try: input on this tab may not land. */ }
+        return false;
+    }
+}
+export async function detach(tabId) {
+    const tab = state.get(tabId);
+    state.delete(tabId);
+    if (!tab?.attached) {
+        return false;
+    }
+    try {
+        await chrome.debugger.detach({ tabId });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export const consoleFor = (tabId, limit) => (state.get(tabId)?.console ?? []).slice(-limit);
+export const networkFor = (tabId, limit) => (state.get(tabId)?.network ?? []).slice(-limit);
+export async function evaluate(tabId, expression) {
+    await attach(tabId);
+    const reply = await send(tabId, 'Runtime.evaluate', {
+        expression,
+        returnByValue: true,
+        awaitPromise: true,
+        // The page's own world, so it sees the page's variables. An isolated world
+        // would answer questions about a context nobody asked about.
+        userGesture: true,
+    });
+    if (reply.exceptionDetails) {
+        return {
+            value: reply.exceptionDetails.exception?.description ?? reply.exceptionDetails.text ?? 'threw',
+            type: 'error',
+            threw: true,
+        };
+    }
+    const result = reply.result ?? {};
+    const value = result.value === undefined
+        ? result.description ?? 'undefined'
+        : typeof result.value === 'string' ? result.value : JSON.stringify(result.value);
+    return { value, type: result.type ?? 'undefined', threw: false };
+}
+export async function screenshot(tabId, format, quality) {
+    await attach(tabId);
+    // Page.captureScreenshot rather than chrome.tabs.captureVisibleTab, which can
+    // only photograph the active tab of a window. Going through CDP is what makes
+    // a background tab capturable at all.
+    const reply = await send(tabId, 'Page.captureScreenshot', {
+        format,
+        ...(format === 'jpeg' && quality !== undefined ? { quality } : {}),
+        captureBeyondViewport: false,
+    });
+    return { base64: reply.data, format };
+}
+export async function clickAt(tabId, point, button, clickCount) {
+    await attach(tabId);
+    const base = { x: point.x, y: point.y, button, clickCount };
+    await send(tabId, 'Input.dispatchMouseEvent', { ...base, type: 'mouseMoved', button: 'none' });
+    await send(tabId, 'Input.dispatchMouseEvent', { ...base, type: 'mousePressed' });
+    await send(tabId, 'Input.dispatchMouseEvent', { ...base, type: 'mouseReleased' });
+}
+export async function insertText(tabId, text) {
+    await attach(tabId);
+    // Input.insertText rather than a keydown per character: it is one round trip
+    // instead of hundreds, and it handles characters no single key produces.
+    await send(tabId, 'Input.insertText', { text });
+}
+export async function pressKey(tabId, key) {
+    await attach(tabId);
+    const named = {
+        Enter: { code: 'Enter', keyCode: 13, text: '\r' },
+        Tab: { code: 'Tab', keyCode: 9 },
+        Escape: { code: 'Escape', keyCode: 27 },
+        Backspace: { code: 'Backspace', keyCode: 8 },
+        ArrowUp: { code: 'ArrowUp', keyCode: 38 },
+        ArrowDown: { code: 'ArrowDown', keyCode: 40 },
+        ArrowLeft: { code: 'ArrowLeft', keyCode: 37 },
+        ArrowRight: { code: 'ArrowRight', keyCode: 39 },
+    };
+    const spec = named[key];
+    if (!spec) {
+        throw new Error(`unknown key ${JSON.stringify(key)}. Known: ${Object.keys(named).join(', ')}`);
+    }
+    const common = { key, code: spec.code, windowsVirtualKeyCode: spec.keyCode, nativeVirtualKeyCode: spec.keyCode };
+    await send(tabId, 'Input.dispatchKeyEvent', {
+        ...common,
+        type: spec.text === undefined ? 'keyDown' : 'keyDown',
+        ...(spec.text === undefined ? {} : { text: spec.text }),
+    });
+    await send(tabId, 'Input.dispatchKeyEvent', { ...common, type: 'keyUp' });
+}
+export async function scrollBy(tabId, point, dx, dy) {
+    await attach(tabId);
+    await send(tabId, 'Input.dispatchMouseEvent', {
+        type: 'mouseWheel',
+        x: point.x,
+        y: point.y,
+        deltaX: dx,
+        deltaY: dy,
+    });
+}