@dna113p/machines 0.1.0 → 0.3.0

package/dist/src/chatgpt-web.js

@@ -0,0 +1,946 @@
+import { spawn } from "node:child_process";
+import { constants } from "node:fs";
+import { access, mkdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import { delimiter, join, resolve } from "node:path";
+import { setTimeout as sleep } from "node:timers/promises";
+import * as v from "valibot";
+import { agentPrompt, readAgentEvent } from "./agent-protocol.js";
+/** Each list names the page as it is today and as it was before, for accounts a rollout has not reached. */
+export const defaultChatGptWebSelectors = {
+    composer: '#prompt-textarea, div.ProseMirror[contenteditable="true"]',
+    send: 'button[data-testid="send-button"], button[aria-label="Send"]',
+    stop: 'button[data-testid="stop-button"], button[aria-label="Stop"]',
+    assistant: '[data-message-author-role="assistant"], [data-chatgpt-search-unit-key$=":assistant"]',
+    plus: 'button[data-testid="composer-plus-btn"], button[aria-label="Add files and more"]',
+    menuItem: '[role="menuitem"], [role="menuitemradio"], [role="menuitemcheckbox"], [role="option"], button[data-list-navigation-item]',
+    signIn: '[data-testid="login-button"]',
+};
+const browserCandidates = [
+    "google-chrome-stable", "google-chrome", "google-chrome-beta", "chromium", "chromium-browser",
+    "brave-browser", "brave", "microsoft-edge", "microsoft-edge-stable", "vivaldi",
+    "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+    "/Applications/Chromium.app/Contents/MacOS/Chromium",
+];
+/** Finds a Chromium-family browser able to expose the DevTools protocol. */
+export async function findChromeExecutable(env = process.env) {
+    if (env.CHATGPT_WEB_BROWSER !== undefined && env.CHATGPT_WEB_BROWSER !== "")
+        return env.CHATGPT_WEB_BROWSER;
+    const directories = (env.PATH ?? "").split(delimiter).filter(entry => entry !== "");
+    for (const candidate of browserCandidates) {
+        const paths = candidate.startsWith("/") ? [candidate] : directories.map(directory => join(directory, candidate));
+        for (const path of paths) {
+            try {
+                await access(path, constants.X_OK);
+                return path;
+            }
+            catch { /* try the next candidate */ }
+        }
+    }
+    return undefined;
+}
+export function defaultChatGptWebProfile(env = process.env) {
+    const state = env.XDG_STATE_HOME !== undefined && env.XDG_STATE_HOME !== ""
+        ? env.XDG_STATE_HOME
+        : join(homedir(), ".local", "state");
+    return join(state, "machines", "chatgpt-web-profile");
+}
+/** Builds the conversation opener that points ChatGPT at the local workspace through rig-bridge. */
+export function chatGptWebPrompt(request, connector) {
+    return [
+        `You are working on my local computer through the "${connector}" connector (MCP tools such as workspace_open, read, ls, find, grep, write, edit, and bash).`,
+        `First call workspace_open with cwd ${JSON.stringify(request.cwd)} and follow the project instructions it returns.`,
+        "Do every file read, edit, and command through that workspace's tools. Nobody is watching this conversation, so do not ask me to run anything or wait for replies.",
+        `Immediately before returning control in your final reply, call work_handoff with workspace_id, a fresh request_key, reason matching one of: ${request.outcomes.join(", ")} (or completed, needs_input, blocked, failed, cancelled), and a short summary.`,
+        "Close the workspace with workspace_close when you are finished.",
+        "",
+        agentPrompt(request),
+        "Write the MACHINES_EVENT line as plain text on its own line, not inside a code block.",
+    ].join("\n");
+}
+const defaultApproveLabels = ["Confirm", "Allow", "Approve", "Allow once"];
+const signInLabels = ["log in", "sign in"];
+const conversationSegment = /\/c\/([^/]+)/u;
+const noLastingAddress = "ChatGPT did not show the chat's lasting address before the run ended, so this event has no conversation to continue.";
+/**
+ * Reads the conversation identifier from a page path. ChatGPT shows a new chat under a temporary
+ * identifier first, such as `local-chatgpt%3A<uuid>`, which stops opening the chat once it has a lasting one.
+ */
+function conversationId(pathname) {
+    const id = conversationSegment.exec(pathname)?.[1];
+    return id === undefined ? undefined : { id, lasting: /^[\w-]+$/u.test(id) };
+}
+function lastingConversation(url) {
+    return conversationId(new URL(url).pathname)?.lasting === true ? url : undefined;
+}
+function outputEmitter(report, outputMode) {
+    return text => {
+        const line = text.endsWith("\n") ? text : `${text}\n`;
+        report?.({ type: "output", text: line });
+        if (outputMode === "stream")
+            process.stdout.write(line);
+    };
+}
+function parseConversation(value) {
+    let url;
+    try {
+        url = new URL(String(value));
+    }
+    catch { /* reported below */ }
+    const found = url === undefined ? undefined : conversationId(url.pathname);
+    if (url === undefined || found === undefined || url.protocol !== "https:" || url.host !== "chatgpt.com"
+        || url.username !== "" || url.password !== "") {
+        throw new Error("ChatGPT Web continuation requires an https://chatgpt.com/c/<id> conversation URL without credentials");
+    }
+    if (!found.lasting) {
+        throw new Error(`ChatGPT Web continuation requires the chat's lasting https://chatgpt.com/c/<id> address: "${found.id}" is a temporary `
+            + "identifier that ChatGPT shows while a chat is new, and its address no longer opens the chat");
+    }
+    return { href: url.href, id: found.id };
+}
+/** Runs one fresh ChatGPT web conversation that works in the request's directory via rig-bridge. */
+export function chatGptWebAgent(options = {}) {
+    return async (request, report) => {
+        if (request.cwd === undefined)
+            throw new Error("ChatGPT Web Agent requires a working directory");
+        if (request.outcomes.length === 0)
+            throw new Error("ChatGPT Web Agent requires at least one allowed outcome");
+        const env = { ...process.env, ...options.env };
+        const cwd = resolve(request.cwd);
+        const connector = options.connector ?? env.CHATGPT_WEB_CONNECTOR ?? "rig-bridge";
+        const model = options.model ?? env.CHATGPT_WEB_MODEL;
+        const cdpUrl = (options.cdpUrl ?? env.CHATGPT_WEB_CDP_URL ?? "http://127.0.0.1:9222").replace(/\/+$/u, "");
+        const statusUrl = options.bridgeStatusUrl === false ? undefined
+            : options.bridgeStatusUrl ?? env.RIG_BRIDGE_STATUS_URL ?? "http://127.0.0.1:8767/api/status";
+        const selectors = { ...defaultChatGptWebSelectors, ...options.selectors };
+        const outputMode = options.output ?? "stream";
+        const timeoutMs = options.timeoutMs ?? 60 * 60_000;
+        const settleMs = options.settleMs ?? 5_000;
+        const pollMs = options.pollMs ?? 1_000;
+        const composerTimeoutMs = options.composerTimeoutMs ?? 45_000;
+        const start = new URL(options.url ?? env.CHATGPT_WEB_URL ?? "https://chatgpt.com/");
+        if (model !== undefined)
+            start.searchParams.set("model", model);
+        report?.({
+            type: "identity",
+            harness: options.harness ?? "chatgpt-web",
+            ...(model === undefined ? {} : { model }),
+        });
+        const emit = outputEmitter(report, outputMode);
+        let page;
+        let targetId;
+        let conversation;
+        let succeeded = false;
+        try {
+            await ensureBrowser(cdpUrl, options.launch ?? true, env);
+            targetId = await createTarget(cdpUrl, start.href);
+            page = await CdpPage.connect(await targetSocket(cdpUrl, targetId));
+            await page.send("Runtime.enable");
+            await page.send("Page.enable");
+            await page.send("Page.bringToFront");
+            await waitForComposer(page, selectors, composerTimeoutMs, pollMs);
+            if (options.selectConnector ?? true) {
+                if (!await selectConnector(page, selectors, connector)) {
+                    emit(`Could not enable "${connector}" from the composer menu; relying on the prompt to invoke it.`);
+                }
+            }
+            const baseline = (await snapshot(page, selectors)).assistantCount;
+            await submitPrompt(page, selectors, chatGptWebPrompt({ ...request, cwd }, connector), pollMs);
+            const bridge = statusUrl === undefined ? undefined : new BridgeActivity(statusUrl, cwd, Date.now() - 2_000, report);
+            const deadline = Date.now() + timeoutMs;
+            const approveLabels = (options.approveLabels ?? defaultApproveLabels).map(label => label.toLowerCase());
+            let lastText = "";
+            let changedAt = Date.now();
+            let waitingReported = false;
+            let finalText;
+            while (Date.now() < deadline) {
+                const current = await snapshot(page, selectors, approveLabels);
+                // The address is the temporary one at first; only the lasting one opens the chat again.
+                if (conversation === undefined && lastingConversation(current.url) !== undefined) {
+                    conversation = current.url;
+                    report?.({ type: "tool", id: "chatgpt-conversation", title: `ChatGPT conversation ${conversation}`, status: "in_progress" });
+                }
+                const busyBridge = await bridge?.poll() ?? false;
+                const handoff = bridge?.latestHandoff;
+                if (current.approval !== undefined) {
+                    if (options.approveToolCalls === true) {
+                        await click(page, current.approval);
+                        changedAt = Date.now();
+                    }
+                    else if (!waitingReported) {
+                        waitingReported = true;
+                        emit(`ChatGPT is waiting for tool approval in the browser tab${conversation === undefined ? "" : ` (${conversation})`}.`);
+                    }
+                }
+                const text = current.assistantCount > baseline ? current.lastAssistant : "";
+                if (text !== lastText || current.generating || busyBridge || current.approval !== undefined) {
+                    if (text !== lastText)
+                        lastText = text;
+                    changedAt = Date.now();
+                }
+                else if (text !== "") {
+                    const quiet = Date.now() - changedAt;
+                    const hasEvent = /^MACHINES_EVENT /mu.test(text);
+                    // When rig-bridge notifies a handoff, the assistant has completed work; use a brief quiet window.
+                    const minQuiet = handoff !== undefined ? Math.min(settleMs, 1_000) : (hasEvent ? settleMs : settleMs * 4);
+                    if (quiet >= minQuiet) {
+                        finalText = text;
+                        break;
+                    }
+                }
+                await sleep(pollMs);
+            }
+            if (finalText === undefined)
+                throw new Error(`ChatGPT did not finish within ${timeoutMs} ms`);
+            await bridge?.poll();
+            conversation ??= lastingConversation((await snapshot(page, selectors)).url);
+            if (conversation !== undefined) {
+                report?.({ type: "tool", id: "chatgpt-conversation", title: `ChatGPT conversation ${conversation}`, status: "completed" });
+            }
+            emit(finalText);
+            const handoff = bridge?.latestHandoff;
+            let event;
+            const hasMachinesEvent = /^MACHINES_EVENT /mu.test(finalText);
+            if (hasMachinesEvent) {
+                event = readAgentEvent(finalText, { adapter: "ChatGPT Web", includeMessage: outputMode === "capture" });
+                if (handoff !== undefined) {
+                    event = {
+                        ...event,
+                        summary: event.summary ?? handoff.summary,
+                        handoff,
+                    };
+                }
+            }
+            else if (handoff !== undefined) {
+                // Fallback: ChatGPT signaled work_handoff via MCP without adding a MACHINES_EVENT line in chat.
+                const type = request.outcomes.includes(handoff.reason) ? handoff.reason
+                    : request.outcomes.length === 1 && (handoff.reason === "completed" || handoff.reason === "done")
+                        ? request.outcomes[0]
+                        : handoff.reason;
+                event = {
+                    type,
+                    summary: handoff.summary,
+                    handoff,
+                    ...(outputMode === "capture" && finalText.trim() !== "" ? { message: finalText.trim() } : {}),
+                };
+            }
+            else {
+                event = readAgentEvent(finalText, { adapter: "ChatGPT Web", includeMessage: outputMode === "capture" });
+            }
+            // Only the address the page showed is returned: one the assistant wrote in its event may be the temporary one.
+            const { conversation: _written, ...read } = event;
+            if (conversation !== undefined) {
+                event = { ...read, conversation };
+            }
+            else {
+                // A temporary address would be returned in vain, so the event says why it carries none.
+                emit(noLastingAddress);
+                const summary = typeof read.summary === "string" && read.summary.trim() !== "" ? `${read.summary}\n` : "";
+                event = { ...read, summary: `${summary}${noLastingAddress}` };
+            }
+            if (handoff !== undefined && (options.acknowledgeHandoff ?? true)) {
+                await bridge?.acknowledge(handoff.id);
+            }
+            succeeded = true;
+            return event;
+        }
+        catch (cause) {
+            const message = cause instanceof Error ? cause.message : String(cause);
+            throw new Error(`ChatGPT Web Agent failed for "${cwd}": ${message}${conversation === undefined ? "" : `\nConversation: ${conversation}`}`, { cause });
+        }
+        finally {
+            page?.close();
+            if (targetId !== undefined && succeeded && options.keepTab !== true) {
+                await fetch(`${cdpUrl}/json/close/${targetId}`).catch(() => undefined);
+            }
+        }
+    };
+}
+/**
+ * Sends one message to an existing ChatGPT web conversation and returns the next rig-bridge handoff.
+ * The handoff is the whole result: assistant messages are never read from the page.
+ */
+export function chatGptWebContinue(options = {}) {
+    return async (input, report) => {
+        const { href: conversation, id } = parseConversation(input.conversation);
+        if (typeof input.text !== "string" || input.text.trim() === "") {
+            throw new Error("ChatGPT Web continuation requires a non-empty message");
+        }
+        if (typeof input.cwd !== "string" || input.cwd === "") {
+            throw new Error("ChatGPT Web continuation requires a working directory");
+        }
+        if (input.bridgeThreadId !== undefined && (typeof input.bridgeThreadId !== "string" || input.bridgeThreadId === "")) {
+            throw new Error("ChatGPT Web continuation requires bridgeThreadId to be a non-empty string when given");
+        }
+        if (options.bridgeStatusUrl === false) {
+            throw new Error("ChatGPT Web continuation requires a rig-bridge status URL; bridgeStatusUrl cannot be false");
+        }
+        const env = { ...process.env, ...options.env };
+        const cwd = resolve(input.cwd);
+        const cdpUrl = (options.cdpUrl ?? env.CHATGPT_WEB_CDP_URL ?? "http://127.0.0.1:9222").replace(/\/+$/u, "");
+        const statusUrl = options.bridgeStatusUrl ?? env.RIG_BRIDGE_STATUS_URL ?? "http://127.0.0.1:8767/api/status";
+        // Without an assistant selector, no page read below can reach assistant messages.
+        const selectors = { ...defaultChatGptWebSelectors, ...options.selectors, assistant: undefined };
+        const timeoutMs = options.timeoutMs ?? 60 * 60_000;
+        const pollMs = options.pollMs ?? 1_000;
+        const composerTimeoutMs = options.composerTimeoutMs ?? 45_000;
+        const approveLabels = (options.approveLabels ?? defaultApproveLabels).map(label => label.toLowerCase());
+        const emit = outputEmitter(report, options.output ?? "stream");
+        const reportConversation = (status) => {
+            report?.({ type: "tool", id: "chatgpt-conversation", title: `ChatGPT conversation ${conversation}`, status });
+        };
+        report?.({ type: "identity", harness: options.harness ?? "chatgpt-web" });
+        let page;
+        let targetId;
+        let succeeded = false;
+        try {
+            await ensureBrowser(cdpUrl, options.launch ?? true, env);
+            targetId = await createTarget(cdpUrl, conversation);
+            page = await CdpPage.connect(await targetSocket(cdpUrl, targetId));
+            await page.send("Runtime.enable");
+            await page.send("Page.enable");
+            await page.send("Page.bringToFront");
+            const ready = await waitForComposer(page, selectors, composerTimeoutMs, pollMs);
+            // The stop button can render after the composer while the page loads, so look twice before sending.
+            await sleep(pollMs);
+            const loaded = await snapshot(page, selectors);
+            if (conversationId(new URL(loaded.url).pathname)?.id !== id) {
+                throw new Error(`ChatGPT opened ${loaded.url} instead of the conversation; the message was not sent`);
+            }
+            if (ready.generating || loaded.generating) {
+                throw new Error("the conversation is busy generating a reply; the message was not sent");
+            }
+            // Entering text adds to what the composer holds, so a saved draft would be sent along with the message.
+            if (normalize(loaded.composerText) !== "") {
+                throw new Error("the composer already holds unsent text; the message was not sent");
+            }
+            reportConversation("in_progress");
+            // Only a handoff recorded once the message is on its way can answer it, however long entering it took.
+            let sentAt;
+            try {
+                await submitPrompt(page, selectors, input.text, pollMs, {
+                    exact: true,
+                    idle: true,
+                    onSend: () => { sentAt = Date.now(); },
+                });
+            }
+            catch (cause) {
+                const message = cause instanceof Error ? cause.message : String(cause);
+                // Nothing is sent before onSend runs, so an earlier failure leaves the message unsent.
+                if (sentAt === undefined)
+                    throw new Error(`${message}; the message was not sent`, { cause });
+                throw new Error(`delivery of the message is uncertain (${message}). It was not sent again; check the conversation before retrying`, { cause });
+            }
+            const bridge = new BridgeActivity(statusUrl, cwd, sentAt ?? Date.now(), report, {
+                requireWorkspace: true,
+                threadId: input.bridgeThreadId,
+            });
+            const deadline = Date.now() + timeoutMs;
+            let waitingReported = false;
+            let handoff;
+            while (handoff === undefined) {
+                if (Date.now() >= deadline)
+                    throw new Error(`no rig-bridge handoff arrived within ${timeoutMs} ms`);
+                const current = await snapshot(page, selectors, approveLabels);
+                if (current.approval !== undefined) {
+                    if (options.approveToolCalls === true) {
+                        await click(page, current.approval);
+                    }
+                    else if (!waitingReported) {
+                        waitingReported = true;
+                        emit(`ChatGPT is waiting for tool approval in the browser tab (${conversation}).`);
+                    }
+                }
+                await bridge.poll();
+                handoff = bridge.latestHandoff;
+                if (handoff === undefined)
+                    await sleep(pollMs);
+            }
+            // The handoff precedes the end of the reply; let it finish so the conversation is free for the next message.
+            while (Date.now() < deadline && (await snapshot(page, selectors)).generating) {
+                await sleep(pollMs);
+                await bridge.poll();
+            }
+            reportConversation("completed");
+            if (options.acknowledgeHandoff ?? true) {
+                await bridge.acknowledge(handoff.id);
+            }
+            succeeded = true;
+            return { type: handoff.reason, summary: handoff.summary, handoff, conversation };
+        }
+        catch (cause) {
+            const message = cause instanceof Error ? cause.message : String(cause);
+            throw new Error(`ChatGPT Web continuation failed for ${conversation}: ${message}`, { cause });
+        }
+        finally {
+            page?.close();
+            if (targetId !== undefined && succeeded && options.keepTab !== true) {
+                await fetch(`${cdpUrl}/json/close/${targetId}`).catch(() => undefined);
+            }
+        }
+    };
+}
+// ---------------------------------------------------------------------------
+// Browser and DevTools protocol
+const versionSchema = v.object({ webSocketDebuggerUrl: v.string() });
+const targetListSchema = v.array(v.object({ id: v.string(), webSocketDebuggerUrl: v.optional(v.string()) }));
+async function browserVersion(cdpUrl) {
+    try {
+        const response = await fetch(`${cdpUrl}/json/version`, { signal: AbortSignal.timeout(2_000) });
+        if (!response.ok)
+            return undefined;
+        const parsed = v.safeParse(versionSchema, await response.json());
+        return parsed.success ? parsed.output : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function ensureBrowser(cdpUrl, launch, env) {
+    if (await browserVersion(cdpUrl) !== undefined)
+        return;
+    if (launch === false)
+        throw new Error(`No browser DevTools endpoint at ${cdpUrl}`);
+    const endpoint = new URL(cdpUrl);
+    if (!["127.0.0.1", "localhost", "[::1]"].includes(endpoint.hostname)) {
+        throw new Error(`No browser DevTools endpoint at ${cdpUrl}; only local endpoints can be launched`);
+    }
+    const settings = launch === true ? {} : launch;
+    const executable = settings.executable ?? await findChromeExecutable(env);
+    if (executable === undefined) {
+        throw new Error("No Chromium-family browser found; set CHATGPT_WEB_BROWSER or launch.executable");
+    }
+    const profile = settings.userDataDir ?? env.CHATGPT_WEB_PROFILE ?? defaultChatGptWebProfile(env);
+    await mkdir(profile, { recursive: true, mode: 0o700 });
+    // The browser is a shared, persistent resource holding the login. Detach it so
+    // terminating one Machine run does not close other conversations or sign out.
+    const child = spawn(executable, [
+        `--remote-debugging-port=${endpoint.port === "" ? "9222" : endpoint.port}`,
+        `--user-data-dir=${profile}`,
+        "--no-first-run", "--no-default-browser-check",
+        ...(settings.headless === true ? ["--headless=new"] : []),
+        ...(settings.args ?? []),
+    ], { detached: true, stdio: "ignore" });
+    const failed = new Promise((_, reject) => child.once("error", reject));
+    child.unref();
+    const deadline = Date.now() + 20_000;
+    while (Date.now() < deadline) {
+        const ready = await Promise.race([browserVersion(cdpUrl), failed]);
+        if (ready !== undefined)
+            return;
+        await sleep(250);
+    }
+    throw new Error(`Browser "${executable}" did not expose DevTools at ${cdpUrl}`);
+}
+async function createTarget(cdpUrl, url) {
+    const version = await browserVersion(cdpUrl);
+    if (version === undefined)
+        throw new Error(`No browser DevTools endpoint at ${cdpUrl}`);
+    const browser = await CdpPage.connect(version.webSocketDebuggerUrl);
+    try {
+        const created = await browser.send("Target.createTarget", { url });
+        if (typeof created.targetId !== "string")
+            throw new Error("Browser did not create a tab");
+        return created.targetId;
+    }
+    finally {
+        browser.close();
+    }
+}
+async function targetSocket(cdpUrl, targetId) {
+    for (let attempt = 0; attempt < 20; attempt += 1) {
+        const response = await fetch(`${cdpUrl}/json/list`);
+        const targets = v.parse(targetListSchema, await response.json());
+        const url = targets.find(target => target.id === targetId)?.webSocketDebuggerUrl;
+        if (url !== undefined)
+            return url;
+        await sleep(100);
+    }
+    throw new Error("Browser tab is not available for automation");
+}
+class CdpPage {
+    #socket;
+    #pending = new Map();
+    #next = 1;
+    constructor(socket) {
+        this.#socket = socket;
+        socket.addEventListener("message", message => {
+            let data;
+            try {
+                data = JSON.parse(String(message.data));
+            }
+            catch {
+                return;
+            }
+            if (data.id === undefined)
+                return;
+            const pending = this.#pending.get(data.id);
+            if (pending === undefined)
+                return;
+            this.#pending.delete(data.id);
+            if (data.error !== undefined)
+                pending.reject(new Error(data.error.message ?? "DevTools request failed"));
+            else
+                pending.resolve(data.result ?? {});
+        });
+        socket.addEventListener("close", () => {
+            for (const pending of this.#pending.values())
+                pending.reject(new Error("Browser connection closed"));
+            this.#pending.clear();
+        });
+    }
+    static connect(url) {
+        return new Promise((resolveConnect, reject) => {
+            const socket = new WebSocket(url);
+            socket.addEventListener("open", () => resolveConnect(new CdpPage(socket)), { once: true });
+            socket.addEventListener("error", () => reject(new Error(`Could not connect to ${url}`)), { once: true });
+        });
+    }
+    send(method, params = {}) {
+        const id = this.#next++;
+        return new Promise((resolveSend, reject) => {
+            this.#pending.set(id, { resolve: resolveSend, reject });
+            this.#socket.send(JSON.stringify({ id, method, params }));
+        });
+    }
+    async call(fn, arg) {
+        const result = await this.send("Runtime.evaluate", {
+            expression: `(${fn.toString()})(${JSON.stringify(arg)})`,
+            returnByValue: true,
+            awaitPromise: true,
+        });
+        if (result.exceptionDetails !== undefined) {
+            const details = result.exceptionDetails;
+            throw new Error(details.exception?.description ?? details.text ?? "Page script failed");
+        }
+        return result.result?.value;
+    }
+    close() {
+        this.#socket.close();
+    }
+}
+function pageSnapshot(arg) {
+    const { selectors, approveLabels } = arg;
+    const composer = document.querySelector(selectors.composer);
+    const send = document.querySelector(selectors.send);
+    const assistants = selectors.assistant === undefined ? [] : document.querySelectorAll(selectors.assistant);
+    const last = assistants[assistants.length - 1];
+    let approval;
+    if (approveLabels.length > 0) {
+        for (const button of Array.from(document.querySelectorAll("button"))) {
+            if (composer !== null && button.closest("form")?.contains(composer))
+                continue;
+            if (!approveLabels.includes(button.innerText.trim().toLowerCase()) || button.disabled)
+                continue;
+            const rect = button.getBoundingClientRect();
+            if (rect.width === 0 || rect.height === 0)
+                continue;
+            button.scrollIntoView({ block: "center" });
+            const moved = button.getBoundingClientRect();
+            approval = { x: moved.left + moved.width / 2, y: moved.top + moved.height / 2 };
+            break;
+        }
+    }
+    return {
+        url: location.href,
+        composer: composer !== null,
+        composerText: composer instanceof HTMLTextAreaElement ? composer.value : composer?.innerText ?? "",
+        generating: document.querySelector(selectors.stop) !== null,
+        sendEnabled: send instanceof HTMLButtonElement && !send.disabled,
+        assistantCount: assistants.length,
+        lastAssistant: last?.innerText ?? "",
+        ...(approval === undefined ? {} : { approval }),
+    };
+}
+function locate(arg) {
+    const candidates = Array.from(document.querySelectorAll(arg.selector));
+    const pattern = arg.text?.toLowerCase();
+    const element = candidates.find(candidate => {
+        const rect = candidate.getBoundingClientRect();
+        if (rect.width === 0 || rect.height === 0)
+            return false;
+        return pattern === undefined || candidate.innerText.toLowerCase().includes(pattern);
+    });
+    if (element === undefined)
+        return undefined;
+    element.scrollIntoView({ block: "center" });
+    const rect = element.getBoundingClientRect();
+    return { x: rect.left + rect.width / 2, y: rect.top + rect.height / 2 };
+}
+function pasteText(arg) {
+    const composer = document.querySelector(arg.selector);
+    if (composer === null)
+        return false;
+    composer.focus();
+    if (composer instanceof HTMLTextAreaElement) {
+        const setter = Object.getOwnPropertyDescriptor(HTMLTextAreaElement.prototype, "value")?.set;
+        setter?.call(composer, arg.text);
+        composer.dispatchEvent(new Event("input", { bubbles: true }));
+        return true;
+    }
+    // ChatGPT's ProseMirror composer keeps paragraphs from a pasted plain-text payload.
+    const data = new DataTransfer();
+    data.setData("text/plain", arg.text);
+    composer.dispatchEvent(new ClipboardEvent("paste", { clipboardData: data, bubbles: true, cancelable: true }));
+    return true;
+}
+function signInVisible(arg) {
+    const shown = (element) => {
+        const rect = element.getBoundingClientRect();
+        return rect.width > 0 && rect.height > 0;
+    };
+    if (Array.from(document.querySelectorAll(arg.selector)).some(shown))
+        return true;
+    return Array.from(document.querySelectorAll('a, button, [role="button"]'))
+        .some(control => shown(control) && arg.labels.includes(control.innerText.trim().toLowerCase()));
+}
+function snapshot(page, selectors, approveLabels = []) {
+    return page.call(pageSnapshot, { selectors, approveLabels });
+}
+async function waitFor(page, selectors, predicate, timeoutMs, pollMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        try {
+            const current = await snapshot(page, selectors);
+            if (predicate(current))
+                return current;
+        }
+        catch { /* the page may be navigating */ }
+        await sleep(Math.min(pollMs, 250));
+    }
+    return undefined;
+}
+/** Waits for the composer. When it does not appear, the error tells a signed-out page from out-of-date selectors. */
+async function waitForComposer(page, selectors, timeoutMs, pollMs) {
+    const ready = await waitFor(page, selectors, current => current.composer, timeoutMs, pollMs);
+    if (ready !== undefined)
+        return ready;
+    const url = (await snapshot(page, selectors)).url;
+    if (await page.call(signInVisible, { selector: selectors.signIn, labels: [...signInLabels] })) {
+        throw new Error(`ChatGPT composer did not appear at ${url}: the page shows a sign-in control, so the browser is not signed in. `
+            + "Sign in to ChatGPT in the automation browser profile and retry");
+    }
+    throw new Error(`ChatGPT composer did not appear at ${url}, and the page shows no sign-in control. The page selectors are most likely `
+        + "out of date: compare them with the page and override `selectors`. If the page is signed out after all, "
+        + "sign in to ChatGPT in the automation browser profile and retry");
+}
+async function click(page, point) {
+    await page.send("Input.dispatchMouseEvent", { type: "mouseMoved", x: point.x, y: point.y });
+    await page.send("Input.dispatchMouseEvent", { type: "mousePressed", x: point.x, y: point.y, button: "left", clickCount: 1 });
+    await page.send("Input.dispatchMouseEvent", { type: "mouseReleased", x: point.x, y: point.y, button: "left", clickCount: 1 });
+}
+async function locateWithin(page, selector, text, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    do {
+        const point = await page.call(locate, text === undefined ? { selector } : { selector, text });
+        if (point !== undefined)
+            return point;
+        await sleep(100);
+    } while (Date.now() < deadline);
+    return undefined;
+}
+async function selectConnector(page, selectors, connector) {
+    const plus = await locateWithin(page, selectors.plus, undefined, 2_000);
+    if (plus === undefined)
+        return false;
+    await click(page, plus);
+    let item = await locateWithin(page, selectors.menuItem, connector, 1_000);
+    for (const submenu of ["Developer mode", "More"]) {
+        if (item !== undefined)
+            break;
+        const parent = await locateWithin(page, selectors.menuItem, submenu, 300);
+        if (parent === undefined)
+            continue;
+        await click(page, parent);
+        item = await locateWithin(page, selectors.menuItem, connector, 1_000);
+    }
+    if (item !== undefined)
+        await click(page, item);
+    await page.send("Input.dispatchKeyEvent", { type: "keyDown", key: "Escape", code: "Escape", windowsVirtualKeyCode: 27 });
+    await page.send("Input.dispatchKeyEvent", { type: "keyUp", key: "Escape", code: "Escape", windowsVirtualKeyCode: 27 });
+    return item !== undefined;
+}
+const normalize = (text) => text.replace(/\s+/gu, " ").trim();
+async function submitPrompt(page, selectors, prompt, pollMs, options = {}) {
+    const whole = normalize(prompt);
+    const probe = whole.slice(0, 60);
+    const typed = (current) => {
+        const text = normalize(current.composerText);
+        return options.exact === true ? text === whole : text.includes(probe);
+    };
+    await page.call(pasteText, { selector: selectors.composer, text: prompt });
+    if (await waitFor(page, selectors, typed, 1_500, pollMs) === undefined) {
+        // Typing into a composer that holds other text could never produce the prompt alone.
+        if (options.exact === true && normalize((await snapshot(page, selectors)).composerText) !== "") {
+            throw new Error("The ChatGPT composer holds text other than the prompt");
+        }
+        const composer = await locateWithin(page, selectors.composer, undefined, 1_000);
+        if (composer === undefined)
+            throw new Error("ChatGPT composer is unavailable");
+        await click(page, composer);
+        await page.send("Input.insertText", { text: prompt });
+        if (await waitFor(page, selectors, typed, 3_000, pollMs) === undefined) {
+            throw new Error("Could not enter the prompt into the ChatGPT composer");
+        }
+    }
+    const busy = (current) => options.idle === true && current.generating;
+    const ready = await waitFor(page, selectors, current => current.sendEnabled || busy(current), 10_000, pollMs);
+    const send = ready?.sendEnabled === true ? await locateWithin(page, selectors.send, undefined, 500) : undefined;
+    // The page can change while the prompt is entered and the send button becomes ready, so this is the last look.
+    const last = await snapshot(page, selectors);
+    // A reply can start after the caller saw the conversation idle, as when another tab sends to it.
+    if (busy(last))
+        throw new Error("The ChatGPT conversation is busy generating a reply");
+    // ChatGPT can restore a saved draft late.
+    if (options.exact === true && !typed(last)) {
+        throw new Error("The ChatGPT composer holds text other than the prompt");
+    }
+    options.onSend?.();
+    if (send !== undefined)
+        await click(page, send);
+    else {
+        await page.send("Input.dispatchKeyEvent", { type: "keyDown", key: "Enter", code: "Enter", windowsVirtualKeyCode: 13, text: "\r" });
+        await page.send("Input.dispatchKeyEvent", { type: "keyUp", key: "Enter", code: "Enter", windowsVirtualKeyCode: 13 });
+    }
+    const accepted = await waitFor(page, selectors, current => current.generating || !typed(current), 15_000, pollMs);
+    if (accepted === undefined)
+        throw new Error("ChatGPT did not accept the prompt");
+}
+// ---------------------------------------------------------------------------
+// rig-bridge activity and handoffs
+const commandSchema = v.object({
+    id: v.string(),
+    tool: v.string(),
+    description: v.optional(v.string()),
+    startedAt: v.number(),
+    success: v.optional(v.boolean()),
+});
+const handoffSchema = v.object({
+    id: v.string(),
+    projectId: v.string(),
+    threadId: v.string(),
+    runId: v.optional(v.string()),
+    reason: v.string(),
+    summary: v.string(),
+    createdAt: v.number(),
+    readAt: v.optional(v.nullable(v.number())),
+});
+const statusSchema = v.object({
+    version: v.optional(v.string()),
+    startedAt: v.optional(v.number()),
+    uptimeSeconds: v.optional(v.number()),
+    workspacesCount: v.optional(v.number()),
+    activeCommandsCount: v.optional(v.number()),
+    workspaces: v.array(v.object({
+        id: v.string(),
+        projectId: v.optional(v.string()),
+        threadId: v.optional(v.string()),
+        cwd: v.string(),
+        createdAt: v.optional(v.number()),
+        activeCommands: v.optional(v.array(commandSchema)),
+        recentCommands: v.optional(v.array(commandSchema)),
+    })),
+    notifications: v.optional(v.array(handoffSchema)),
+    unreadCount: v.optional(v.number()),
+});
+/** Mirrors commands and tracks handoffs that ChatGPT runs through rig-bridge in the target directory. */
+class BridgeActivity {
+    #reported = new Map();
+    #url;
+    #readUrl;
+    #cwd;
+    #since;
+    #report;
+    #handoffs;
+    #knownWorkspaceIds = new Set();
+    #knownThreadIds = new Set();
+    #knownProjectIds = new Set();
+    #latestHandoff;
+    constructor(url, cwd, since, report, handoffs = {}) {
+        this.#url = url;
+        this.#readUrl = url.replace(/\/api\/status\/?$/u, "/api/handoffs/read");
+        this.#cwd = cwd;
+        this.#since = since;
+        this.#report = report;
+        this.#handoffs = handoffs;
+    }
+    get latestHandoff() {
+        return this.#latestHandoff;
+    }
+    /** Returns true while a matching workspace has an active command. */
+    async poll() {
+        let status;
+        try {
+            const response = await fetch(this.#url, { signal: AbortSignal.timeout(2_000) });
+            if (!response.ok)
+                return false;
+            const parsed = v.safeParse(statusSchema, await response.json());
+            if (!parsed.success)
+                return false;
+            status = parsed.output;
+        }
+        catch {
+            return false;
+        }
+        let busy = false;
+        for (const workspace of status.workspaces) {
+            if (resolve(workspace.cwd) !== this.#cwd)
+                continue;
+            this.#knownWorkspaceIds.add(workspace.id);
+            if (workspace.threadId)
+                this.#knownThreadIds.add(workspace.threadId);
+            if (workspace.projectId)
+                this.#knownProjectIds.add(workspace.projectId);
+            if ((workspace.createdAt ?? 0) >= this.#since) {
+                this.#update(`workspace:${workspace.id}`, `workspace_open ${workspace.cwd}`, "completed");
+            }
+            for (const command of workspace.recentCommands ?? []) {
+                if (command.startedAt < this.#since)
+                    continue;
+                this.#update(command.id, command.description ?? command.tool, command.success === false ? "failed" : "completed");
+            }
+            for (const command of workspace.activeCommands ?? []) {
+                if (command.startedAt < this.#since)
+                    continue;
+                busy = true;
+                this.#update(command.id, command.description ?? command.tool, "in_progress");
+            }
+        }
+        for (const notification of status.notifications ?? []) {
+            if (notification.createdAt < this.#since)
+                continue;
+            const matchesThread = this.#knownThreadIds.has(notification.threadId);
+            const matchesProject = this.#handoffs.requireWorkspace !== true && this.#knownProjectIds.has(notification.projectId);
+            const anyWorkspace = this.#handoffs.requireWorkspace !== true
+                && this.#knownThreadIds.size === 0 && this.#knownProjectIds.size === 0;
+            if (!anyWorkspace && !matchesThread && !matchesProject)
+                continue;
+            if (this.#handoffs.threadId !== undefined && notification.threadId !== this.#handoffs.threadId)
+                continue;
+            if (this.#latestHandoff === undefined || this.#latestHandoff.id !== notification.id) {
+                this.#latestHandoff = {
+                    id: notification.id,
+                    projectId: notification.projectId,
+                    threadId: notification.threadId,
+                    ...(notification.runId ? { runId: notification.runId } : {}),
+                    reason: notification.reason,
+                    summary: notification.summary,
+                    createdAt: notification.createdAt,
+                };
+                this.#update(`handoff:${notification.id}`, `work_handoff (${notification.reason}): ${notification.summary}`, "completed");
+            }
+        }
+        return busy;
+    }
+    async acknowledge(handoffId) {
+        try {
+            const response = await fetch(this.#readUrl, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({ handoff_id: handoffId }),
+                signal: AbortSignal.timeout(3_000),
+            });
+            return response.ok;
+        }
+        catch {
+            return false;
+        }
+    }
+    #update(id, title, status) {
+        const previous = this.#reported.get(id);
+        if (previous === status || previous === "completed" || previous === "failed")
+            return;
+        this.#reported.set(id, status);
+        this.#report?.({ type: "tool", id, title, status });
+    }
+}
+/** Fetches the latest bridge status from rig-bridge. */
+export async function fetchRigBridgeStatus(statusUrl = process.env.RIG_BRIDGE_STATUS_URL ?? "http://127.0.0.1:8767/api/status") {
+    try {
+        const response = await fetch(statusUrl, { signal: AbortSignal.timeout(3_000) });
+        if (!response.ok)
+            return undefined;
+        const parsed = v.safeParse(statusSchema, await response.json());
+        return parsed.success ? parsed.output : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Finds the most recent handoff notification from rig-bridge matching the given directory or thread. */
+export async function fetchLatestRigBridgeHandoff(options = {}) {
+    const status = await fetchRigBridgeStatus(options.statusUrl);
+    if (!status || !status.notifications || status.notifications.length === 0)
+        return undefined;
+    const targetCwd = options.cwd ? resolve(options.cwd) : undefined;
+    const threadIds = new Set();
+    const projectIds = new Set();
+    if (targetCwd !== undefined) {
+        let matched = false;
+        for (const ws of status.workspaces) {
+            if (resolve(ws.cwd) === targetCwd) {
+                matched = true;
+                if (ws.threadId)
+                    threadIds.add(ws.threadId);
+                if (ws.projectId)
+                    projectIds.add(ws.projectId);
+            }
+        }
+        if (!matched && !options.threadId)
+            return undefined;
+    }
+    for (const notification of status.notifications) {
+        if (options.since !== undefined && notification.createdAt < options.since)
+            continue;
+        if ((threadIds.size > 0 || projectIds.size > 0) && !threadIds.has(notification.threadId) && !projectIds.has(notification.projectId)) {
+            continue;
+        }
+        return {
+            id: notification.id,
+            projectId: notification.projectId,
+            threadId: notification.threadId,
+            ...(notification.runId ? { runId: notification.runId } : {}),
+            reason: notification.reason,
+            summary: notification.summary,
+            createdAt: notification.createdAt,
+        };
+    }
+    return undefined;
+}
+/** Acknowledges / marks read a handoff on rig-bridge. */
+export async function acknowledgeRigBridgeHandoff(handoffId, options = {}) {
+    const base = (options.statusUrl ?? process.env.RIG_BRIDGE_STATUS_URL ?? "http://127.0.0.1:8767/api/status")
+        .replace(/\/api\/status\/?$/u, "/api/handoffs/read");
+    try {
+        const response = await fetch(base, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ handoff_id: handoffId }),
+            signal: AbortSignal.timeout(3_000),
+        });
+        return response.ok;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Creates an Operation for a Machine that inspects rig-bridge for the latest handoff notification,
+ * returning an Event with `type = handoff.reason` and attaching `summary` and `handoff`.
+ */
+export function rigBridgeHandoffOperation(options = {}) {
+    return async () => {
+        const handoff = await fetchLatestRigBridgeHandoff(options);
+        if (handoff === undefined) {
+            throw new Error("No rig-bridge handoff notification found");
+        }
+        if (options.acknowledge ?? true) {
+            await acknowledgeRigBridgeHandoff(handoff.id, options);
+        }
+        return {
+            type: handoff.reason,
+            summary: handoff.summary,
+            handoff,
+        };
+    };
+}