@jobshimo/browser-link 0.21.0 → 0.22.0

package/dist/extension/background.js

@@ -3,6 +3,9 @@ import { buildKeyEventSequence, resolveKey, modifiersToBitmask, MODIFIER_BITS, }
 import { resolveSettleParams, settleSafely } from './settle.js';
 import { runFlow, } from './flow.js';
 import { DEFAULT_IDLE_TTL_MINUTES, IDLE_TTL_STORAGE_KEY, IDLE_TTL_UPDATED_AT_STORAGE_KEY, clampIdleTtlMinutes, parseIncomingSettings, shouldAcceptIncomingSettings, shouldDisconnectForIdle, shouldScheduleIdleSweep, } from './idle-policy.js';
+import { DEFAULT_FLOW_RECORDING_ENABLED, FLOW_RECORDING_STORAGE_KEY, FLOW_RECORDING_UPDATED_AT_STORAGE_KEY, normalizeFlowRecordingEnabled, parseIncomingFlowRecordingSettings, } from './flow-recording-policy.js';
+import { buildRecorderJs, buildStopRecorderJs } from './inpage/recorder.js';
+import { appendRecordingStep, buildAmbiguousNote, buildNavigationWaitForStep, generateRecordingSession, isNavigationForRecording, parseRecordedPayload, toFlowStep, } from './recording.js';
 const WS_URL = 'ws://127.0.0.1:17529';
 const CDP_VERSION = '1.3';
 const CONSOLE_BUFFER_MAX = 200;
@@ -77,21 +80,93 @@ async function applyIncomingSettings(settings) {
         // next settings.update (or a popup edit) can still apply it.
     }
 }
+/* Opt-in flow-recording toggle — mirrors the idle-ttl cache/apply pair
+ * above exactly, independent storage keys, independent updatedAt. The
+ * recorder is gated behind `flowRecordingEnabledCache`: `startRecording`
+ * refuses when it is false, and turning it off WHILE a recording is in
+ * progress force-stops and DISCARDS it immediately (see the
+ * chrome.storage.onChanged listener below) — "nothing records when the
+ * popup toggle is off" is enforced the instant the toggle flips, not just
+ * for recordings started afterward. */
+let flowRecordingEnabledCache = DEFAULT_FLOW_RECORDING_ENABLED;
+async function loadFlowRecordingEnabled() {
+    try {
+        const data = await chrome.storage.local.get(FLOW_RECORDING_STORAGE_KEY);
+        flowRecordingEnabledCache = normalizeFlowRecordingEnabled(data[FLOW_RECORDING_STORAGE_KEY]);
+    }
+    catch {
+        flowRecordingEnabledCache = DEFAULT_FLOW_RECORDING_ENABLED;
+    }
+}
+void loadFlowRecordingEnabled();
+chrome.storage.onChanged.addListener((changes, areaName) => {
+    if (areaName !== 'local')
+        return;
+    if (!(FLOW_RECORDING_STORAGE_KEY in changes))
+        return;
+    flowRecordingEnabledCache = normalizeFlowRecordingEnabled(changes[FLOW_RECORDING_STORAGE_KEY].newValue);
+    if (flowRecordingEnabledCache)
+        return;
+    // Turned off (popup toggle, or a losing settings.update — either way the
+    // new effective value is false): stop AND discard every in-progress
+    // recording right now, across every connected tab. `forceStopAndDiscard
+    // Recording` is defined further down (function declarations are hoisted,
+    // so this forward reference is safe) alongside the rest of the recording
+    // engine.
+    for (const tabId of tabStates.keys()) {
+        void forceStopAndDiscardRecording(tabId).catch(() => {
+            // Best effort — the tab may already be mid-teardown.
+        });
+    }
+});
+async function applyIncomingFlowRecordingSettings(settings) {
+    try {
+        const data = await chrome.storage.local.get(FLOW_RECORDING_UPDATED_AT_STORAGE_KEY);
+        const rawLocalUpdatedAt = data[FLOW_RECORDING_UPDATED_AT_STORAGE_KEY];
+        const localUpdatedAt = typeof rawLocalUpdatedAt === 'number' ? rawLocalUpdatedAt : undefined;
+        if (!shouldAcceptIncomingSettings(localUpdatedAt, settings.updatedAt))
+            return;
+        await chrome.storage.local.set({
+            [FLOW_RECORDING_STORAGE_KEY]: settings.flowRecordingEnabled,
+            [FLOW_RECORDING_UPDATED_AT_STORAGE_KEY]: settings.updatedAt,
+        });
+    }
+    catch {
+        // Best effort — same degrade-gracefully rule as applyIncomingSettings.
+    }
+}
 function isRuntimeMessage(msg) {
     if (typeof msg !== 'object' || msg === null)
         return false;
     const m = msg;
     if (m.action === 'versionCheck')
         return true;
+    if (m.action === 'saveRecording') {
+        return typeof m.tabId === 'number' && typeof m.name === 'string';
+    }
     if (typeof m.tabId !== 'number')
         return false;
     return (m.action === 'connect' ||
         m.action === 'disconnect' ||
         m.action === 'status' ||
         m.action === 'pendingDialog' ||
-        m.action === 'respondDialog');
+        m.action === 'respondDialog' ||
+        m.action === 'recordingStatus' ||
+        m.action === 'startRecording' ||
+        m.action === 'stopRecording' ||
+        m.action === 'discardRecording');
 }
 const tabStates = new Map();
+/** Per-tab `chrome.tabs.onUpdated` listener installed while that tab is
+ * recording, so `handleRecordingNavigation` fires on every navigation and
+ * `stopRecording`/`cleanup` can remove EXACTLY this listener rather than
+ * guessing which one belongs to which tab. Kept out of `TabState` itself
+ * (unlike `debuggerListener`) only because it needs to be reachable from
+ * `chrome.tabs.onRemoved`/`cleanup` even in the split second before a
+ * `TabState` exists — in practice that never happens today, but keeping
+ * the two concerns in separate maps avoids coupling tab-removal cleanup to
+ * TabState's shape. */
+const recordingNavListeners = new Map();
 function send(ws, msg) {
     ws.send(JSON.stringify(msg));
 }
@@ -399,6 +474,34 @@ function attachDebuggerListener(state) {
             }
             return;
         }
+        if (method === 'Runtime.bindingCalled') {
+            // Fired for EVERY CDP binding on the tab, not just ours. Two gates
+            // before a payload is even parsed: the per-session binding name must
+            // match, and — inside parseRecordedPayload — the payload must carry
+            // the per-session nonce only the injected recorder knows. A page
+            // script calling the binding blind (it CAN reach the function — CDP
+            // bindings are page-visible globals) fails the nonce check and
+            // records nothing. See recorder.ts's THREAT MODEL doc.
+            const p = params;
+            const recording = state.recording;
+            if (!recording || recording.status !== 'recording')
+                return;
+            if (p.name !== recording.bindingName)
+                return;
+            const payload = parseRecordedPayload(p.payload ?? '', recording.nonce);
+            if (!payload)
+                return;
+            const result = appendRecordingStep(recording.steps, toFlowStep(payload));
+            recording.steps = result.steps;
+            if (!result.capped && payload.kind !== 'press' && payload.ambiguous === true) {
+                recording.ambiguousStepIndices.push(result.steps.length - 1);
+            }
+            if (result.capped) {
+                recording.capped = true;
+                void finishRecording(state.tabId);
+            }
+            return;
+        }
     };
     state.debuggerListener = listener;
 }
@@ -1303,6 +1406,21 @@ async function cleanup(tabId) {
     const state = tabStates.get(tabId);
     if (!state)
         return;
+    // Recording never survives a disconnect — there is no server connection
+    // left to save to, and leaving captured-but-unsaved steps around after
+    // the tab drops its bridge would be a surprising place for them to
+    // linger.
+    removeRecordingNavListener(tabId);
+    // `chrome.debugger.detach` below drops the CDP binding SUBSCRIPTION but
+    // does NOT remove the plain `window.addEventListener` listeners the
+    // recorder installed in the page — those would leak, staying attached to
+    // a page the user is still browsing. Tear them down in-page FIRST, while
+    // the debugger is still attached and `evaluateInTab` can reach the page.
+    // Best-effort: the tab may already be gone (tab-removal path), in which
+    // case there is nothing left to tear down anyway.
+    if (state.recording) {
+        await teardownRecorderInPage(tabId, state.recording.stopFn);
+    }
     if (state.ws && state.ws.readyState !== WebSocket.CLOSED) {
         try {
             state.ws.close();
@@ -1465,6 +1583,21 @@ async function connectTab(tabId) {
                         const settings = parseIncomingSettings(msg.settings);
                         if (settings)
                             void applyIncomingSettings(settings);
+                        const flowRecordingSettings = parseIncomingFlowRecordingSettings(msg.settings);
+                        if (flowRecordingSettings)
+                            void applyIncomingFlowRecordingSettings(flowRecordingSettings);
+                        return;
+                    }
+                    case 'flow.recorded.result': {
+                        // Not agent/tool activity either — same rationale as
+                        // settings.update just above.
+                        const pending = state.pendingFlowSave;
+                        if (!pending)
+                            return;
+                        if (msg.ok)
+                            pending({ ok: true });
+                        else
+                            pending({ ok: false, error: msg.error });
                         return;
                     }
                     case 'tool.request': {
@@ -1535,6 +1668,276 @@ function getVersionCheck() {
         aligned: server === null ? null : server === extension,
     };
 }
+// === Flow recording by demonstration ===================================
+//
+// STRICTLY OPT-IN (see flowRecordingEnabledCache above) and per-tab/per-
+// session — nothing here runs unless the user both enabled the setting AND
+// pressed Record on this specific connected tab. Lifecycle:
+//
+//   startRecording -> [handleRecordingNavigation]* -> stopRecording
+//     -> saveRecording | discardRecording
+//
+// `Runtime.addBinding` (CDP) is added ONCE at start and left in place for
+// the whole session — per the CDP spec it is re-installed automatically on
+// every new execution context, INCLUDING ones created by a navigation, so
+// it survives document swaps on its own. The in-page LISTENERS
+// (`inpage/recorder.ts`, injected via `Runtime.evaluate`) do NOT survive a
+// navigation — a document swap tears down every JS global the previous
+// document set up — so `handleRecordingNavigation` re-injects the recorder
+// script (not the binding) after every navigation observed while
+// recording, using the same `chrome.tabs.onUpdated` "complete" signal
+// `waitForLoad` already uses elsewhere in this file for the standalone
+// `navigate` tool.
+function originOfUrl(url) {
+    try {
+        return new URL(url).origin;
+    }
+    catch {
+        return url;
+    }
+}
+function removeRecordingNavListener(tabId) {
+    const listener = recordingNavListeners.get(tabId);
+    if (listener) {
+        chrome.tabs.onUpdated.removeListener(listener);
+        recordingNavListeners.delete(tabId);
+    }
+}
+async function injectRecorder(tabId, session) {
+    await evaluateInTab(tabId, buildRecorderJs({
+        bindingName: session.bindingName,
+        activeFlag: session.activeFlag,
+        stopFn: session.stopFn,
+        nonce: session.nonce,
+    }));
+}
+/** Best-effort in-page teardown: calls the installed recorder's own stop
+ * function (named by the session's random `stopFn` global) so its listeners
+ * are removed even before the CDP binding subscription is dropped. A no-op
+ * when the tab already navigated away (nothing installed on the new
+ * document) — which is itself the correct end state, not a failure. Runs on
+ * EVERY exit path — Stop, Discard, setting-off force-stop, and `cleanup`
+ * (disconnect / tab removal / idle sweep) — because
+ * `chrome.debugger.detach` alone only drops the CDP binding subscription,
+ * NOT the plain `window.addEventListener` listeners the recorder installed;
+ * those must be removed in-page. */
+async function teardownRecorderInPage(tabId, stopFn) {
+    try {
+        await evaluateInTab(tabId, buildStopRecorderJs(stopFn));
+    }
+    catch {
+        // Tab closed/navigated/detached mid-teardown — nothing left to tear down.
+    }
+}
+async function handleRecordingNavigation(tabId, newUrl) {
+    const state = tabStates.get(tabId);
+    const recording = state?.recording;
+    if (!recording || recording.status !== 'recording')
+        return;
+    if (!isNavigationForRecording(recording.lastUrl, newUrl))
+        return;
+    recording.lastUrl = newUrl;
+    const result = appendRecordingStep(recording.steps, buildNavigationWaitForStep());
+    recording.steps = result.steps;
+    if (result.capped) {
+        recording.capped = true;
+        await finishRecording(tabId);
+        return;
+    }
+    // Re-inject only — the CDP binding itself persists across navigations
+    // automatically (see the section doc above). Same session identity: the
+    // nonce/binding name rotate per recording START, not per document.
+    await injectRecorder(tabId, recording);
+}
+/** Start recording user interactions on an already-connected tab. Refuses
+ * when the opt-in setting is off, the tab is not connected, or a recording
+ * (recording OR under-review) is already in progress for this tab. */
+async function startRecording(tabId) {
+    if (!flowRecordingEnabledCache) {
+        return { ok: false, error: 'Flow recording is disabled. Enable it in settings first.' };
+    }
+    const state = tabStates.get(tabId);
+    if (!state)
+        return { ok: false, error: 'This tab is not connected.' };
+    if (state.recording) {
+        return { ok: false, error: 'A recording is already in progress (or awaiting review).' };
+    }
+    let tab;
+    try {
+        tab = await chrome.tabs.get(tabId);
+    }
+    catch {
+        return { ok: false, error: 'Tab no longer exists.' };
+    }
+    // Fresh per-session identity: randomized binding name (no stable global
+    // for a page to probe) + nonce (the shared secret authenticating every
+    // payload). Rotated on EVERY recording start — see recorder.ts's THREAT
+    // MODEL doc.
+    const session = generateRecordingSession();
+    try {
+        await cdp(tabId, 'Runtime.addBinding', { name: session.bindingName });
+        await injectRecorder(tabId, session);
+    }
+    catch (err) {
+        return {
+            ok: false,
+            error: `Could not start recording: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+    state.recording = {
+        status: 'recording',
+        steps: [],
+        lastUrl: tab.url ?? '',
+        capped: false,
+        bindingName: session.bindingName,
+        activeFlag: session.activeFlag,
+        stopFn: session.stopFn,
+        nonce: session.nonce,
+        ambiguousStepIndices: [],
+    };
+    const navListener = (updatedId, info, updatedTab) => {
+        if (updatedId !== tabId)
+            return;
+        if (info.status !== 'complete')
+            return;
+        void handleRecordingNavigation(tabId, updatedTab.url ?? '');
+    };
+    chrome.tabs.onUpdated.addListener(navListener);
+    recordingNavListeners.set(tabId, navListener);
+    return { ok: true };
+}
+/** Shared tail of "stop recording": un-injects the in-page recorder,
+ * unsubscribes the CDP binding, removes the navigation listener, and moves
+ * `status` to 'reviewing' — steps stay on `state.recording` for the
+ * popup's review panel. Called both from the explicit Stop action and from
+ * the step-cap auto-stop path (`Runtime.bindingCalled` handler /
+ * `handleRecordingNavigation` above). */
+async function finishRecording(tabId) {
+    const state = tabStates.get(tabId);
+    if (!state?.recording || state.recording.status !== 'recording')
+        return;
+    removeRecordingNavListener(tabId);
+    state.recording.status = 'reviewing';
+    try {
+        await cdp(tabId, 'Runtime.removeBinding', { name: state.recording.bindingName });
+    }
+    catch {
+        // Best effort — tab may already be detached.
+    }
+    await teardownRecorderInPage(tabId, state.recording.stopFn);
+}
+async function stopRecording(tabId) {
+    const state = tabStates.get(tabId);
+    if (!state?.recording || state.recording.status !== 'recording') {
+        return { ok: false, error: 'Not currently recording this tab.' };
+    }
+    await finishRecording(tabId);
+    return { ok: true, steps: state.recording.steps, capped: state.recording.capped };
+}
+/** Full teardown, dropping any captured-but-unsaved steps. Used by
+ * Discard, by the "setting turned off mid-recording" force-stop, and by
+ * `cleanup`/disconnect. */
+function clearRecording(tabId) {
+    removeRecordingNavListener(tabId);
+    const state = tabStates.get(tabId);
+    if (state)
+        state.recording = undefined;
+}
+/** Discard a recording without saving. The popup only exposes Discard from
+ * the review panel (recorder already torn down by `finishRecording`), but
+ * routing through `forceStopAndDiscardRecording` makes it correct even if
+ * called while a recording is still ACTIVE — it tears the recorder down
+ * in-page first rather than orphaning its page listeners. */
+async function discardRecording(tabId) {
+    await forceStopAndDiscardRecording(tabId);
+    return { ok: true };
+}
+/** Stop (if still actively recording) AND discard in one call — the
+ * privacy-critical path used when the flow-recording setting flips off
+ * while a recording is in progress. Never leaves captured-but-unreviewed
+ * steps sitting in memory once the user has turned the feature off. */
+async function forceStopAndDiscardRecording(tabId) {
+    const state = tabStates.get(tabId);
+    if (!state?.recording)
+        return;
+    if (state.recording.status === 'recording') {
+        await finishRecording(tabId);
+    }
+    clearRecording(tabId);
+}
+function getRecordingStatus(tabId) {
+    const recording = tabStates.get(tabId)?.recording;
+    if (!recording)
+        return { active: false, reviewing: false, stepCount: 0, capped: false };
+    return {
+        active: recording.status === 'recording',
+        reviewing: recording.status === 'reviewing',
+        stepCount: recording.steps.length,
+        capped: recording.capped,
+        steps: recording.status === 'reviewing' ? recording.steps : undefined,
+        ambiguousStepIndices: recording.status === 'reviewing' ? recording.ambiguousStepIndices : undefined,
+    };
+}
+/** Send the reviewed recording to the server for validation + persistence
+ * (`flow.recorded` -> `flow.recorded.result`, see messages.ts). Clears the
+ * recording state on success only — a validation failure (e.g. an
+ * over-budget wait_for) leaves the steps in place so the user can edit the
+ * name/description and retry rather than losing the capture. */
+async function saveRecording(tabId, name, description) {
+    const state = tabStates.get(tabId);
+    const recording = state?.recording;
+    if (!state || !recording || recording.status !== 'reviewing') {
+        return { ok: false, error: 'No reviewed recording to save for this tab.' };
+    }
+    if (!state.ws || state.ws.readyState !== WebSocket.OPEN || !state.serverTabId) {
+        return { ok: false, error: 'Not connected to the server.' };
+    }
+    const trimmedName = name.trim();
+    if (trimmedName.length === 0)
+        return { ok: false, error: 'Name is required.' };
+    if (recording.steps.length === 0)
+        return { ok: false, error: 'No steps were captured.' };
+    // Fold the ambiguous-selector warning into the saved recipe's
+    // description so the computed safety signal travels WITH the recipe, not
+    // just in the transient popup review — an agent (or a human) that later
+    // recalls this flow sees the caution too.
+    const ambiguousNote = buildAmbiguousNote(recording.ambiguousStepIndices);
+    const userDescription = description?.trim() ? description.trim() : undefined;
+    const finalDescription = ambiguousNote && userDescription
+        ? `${userDescription}\n\n${ambiguousNote}`
+        : (ambiguousNote ?? userDescription);
+    const ws = state.ws;
+    const serverTabId = state.serverTabId;
+    const result = await new Promise((resolve) => {
+        let settled = false;
+        const settle = (r) => {
+            if (settled)
+                return;
+            settled = true;
+            state.pendingFlowSave = undefined;
+            resolve(r);
+        };
+        state.pendingFlowSave = settle;
+        send(ws, {
+            kind: 'flow.recorded',
+            payload: {
+                tab_id: serverTabId,
+                origin: originOfUrl(recording.lastUrl),
+                name: trimmedName,
+                description: finalDescription,
+                steps: recording.steps,
+            },
+        });
+        // Best-effort timeout so the popup never hangs forever if the WS drops
+        // mid-request without a clean close event.
+        setTimeout(() => {
+            settle({ ok: false, error: 'Timed out waiting for the server.' });
+        }, 10_000);
+    });
+    if (result.ok)
+        clearRecording(tabId);
+    return result;
+}
 async function respondToDialogFromPopup(tabId, accept, promptText) {
     try {
         const params = { accept };
@@ -1571,6 +1974,26 @@ chrome.runtime.onMessage.addListener((msg, _sender, sendResponse) => {
         sendResponse(getVersionCheck());
         return false;
     }
+    if (msg.action === 'recordingStatus') {
+        sendResponse(getRecordingStatus(msg.tabId));
+        return false;
+    }
+    if (msg.action === 'startRecording') {
+        void startRecording(msg.tabId).then(sendResponse);
+        return true;
+    }
+    if (msg.action === 'stopRecording') {
+        void stopRecording(msg.tabId).then(sendResponse);
+        return true;
+    }
+    if (msg.action === 'discardRecording') {
+        void discardRecording(msg.tabId).then(sendResponse);
+        return true;
+    }
+    if (msg.action === 'saveRecording') {
+        void saveRecording(msg.tabId, msg.name, msg.description).then(sendResponse);
+        return true;
+    }
     // 'status'
     sendResponse(getTabStatus(msg.tabId));
     return false;