@jobshimo/browser-link 0.25.2 → 0.26.0

package/dist/extension/background.js

@@ -2,6 +2,7 @@ import { buildSnapshotJs, buildFindJs, buildClickResolveJs, buildTypeResolveJs,
 import { buildKeyEventSequence, resolveKey, modifiersToBitmask, MODIFIER_BITS, } from './keymap.js';
 import { resolveSettleParams, settleSafely } from './settle.js';
 import { runFlow, } from './flow.js';
+import { appendFlowHistory, createFlowRegistry, flowHistoryKey, parseFlowHistory, toHistoryEntry, } from './flow-registry.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';
@@ -145,6 +146,8 @@ function isRuntimeMessage(msg) {
     if (m.action === 'saveRecording') {
         return typeof m.tabId === 'number' && typeof m.name === 'string';
     }
+    if (m.action === 'cancelFlow')
+        return typeof m.flowId === 'string';
     if (typeof m.tabId !== 'number')
         return false;
     return (m.action === 'connect' ||
@@ -155,9 +158,47 @@ function isRuntimeMessage(msg) {
         m.action === 'recordingStatus' ||
         m.action === 'startRecording' ||
         m.action === 'stopRecording' ||
-        m.action === 'discardRecording');
+        m.action === 'discardRecording' ||
+        m.action === 'flowsStatus');
 }
 const tabStates = new Map();
+/**
+ * Every `browser.flow` currently running in this service worker, across
+ * every connected tab. This is the whole basis of the kill switch: the
+ * runner polls `cancelled` off an entry here before each step, so stopping
+ * a flow means flipping one boolean and letting the loop decline to
+ * dispatch step N+1 — never interrupting an in-flight CDP command.
+ *
+ * Lives in the service worker's memory ON PURPOSE. If Chrome terminates
+ * the worker mid-flow the flow dies with it, the entry goes with it, and
+ * the popup shows nothing running — which is the truth. A registry that
+ * survived the worker would have to describe flows that no longer exist.
+ */
+const flowRegistry = createFlowRegistry();
+/** Fallback id for a `browser.flow` that arrived without one (a server
+ * older than this extension). `crypto.randomUUID` is available in the MV3
+ * service worker; the `flow_` prefix keeps a locally-minted id visually
+ * distinguishable from a server-minted one in the popup. */
+function newFlowId() {
+    return `flow_${crypto.randomUUID()}`;
+}
+/** Answer the popup's Flows panel: everything running (across ALL tabs —
+ * the Stop button has to reach a flow on a tab the user is not looking at)
+ * plus the completed history of the ONE tab the popup is showing. */
+async function getFlowsStatus(tabId) {
+    const running = flowRegistry.listRunning(Date.now());
+    let history = [];
+    try {
+        const key = flowHistoryKey(tabId);
+        const data = await chrome.storage.session.get(key);
+        history = parseFlowHistory(data[key]);
+    }
+    catch {
+        // Session storage unavailable — show the running half rather than
+        // failing the whole panel.
+    }
+    return { running, history };
+}
 /** 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
@@ -778,7 +819,15 @@ async function performPress(tabId, params) {
         return { ok: false, error: err instanceof Error ? err.message : String(err) };
     }
 }
-async function performWaitFor(tabId, state, params) {
+async function performWaitFor(tabId, state, params, 
+/** Cancellation flag of the flow this wait belongs to, when it is a flow
+ * step (see `handleFlow`). Checked on EVERY poll tick, which is what
+ * makes the advertised worst-case cancellation latency of one step true
+ * for a step that can legitimately park for 30 seconds — without it,
+ * pressing Stop during a long `wait_for` would do nothing visible until
+ * the wait timed out on its own. Absent for the standalone
+ * `browser.wait_for` tool, which has no flow to be cancelled with. */
+shouldCancel) {
     try {
         const waitSelector = params.selector;
         const waitExpression = params.expression;
@@ -846,7 +895,12 @@ async function performWaitFor(tabId, state, params) {
         const startedAt = Date.now();
         let checks = 0;
         let matched = false;
+        let cancelled = false;
         while (check) {
+            if (shouldCancel?.() === true) {
+                cancelled = true;
+                break;
+            }
             checks++;
             if (await check()) {
                 matched = true;
@@ -857,9 +911,19 @@ async function performWaitFor(tabId, state, params) {
             await sleep(pollIntervalMs);
         }
         const elapsedMs = Date.now() - startedAt;
+        // 'cancelled' is deliberately distinct from 'timeout': the step
+        // executor turns a timeout into a flow FAILURE (with a recovery
+        // snapshot) and a cancellation into a clean `stopped_by: 'cancelled'`.
+        // Reporting a stopped wait as a timeout would invent a diagnosis for a
+        // condition that was never given its budget.
         const result = matched
             ? { matched: true, elapsed_ms: elapsedMs, checks }
-            : { matched: false, elapsed_ms: elapsedMs, checks, reason: 'timeout' };
+            : {
+                matched: false,
+                elapsed_ms: elapsedMs,
+                checks,
+                reason: cancelled ? 'cancelled' : 'timeout',
+            };
         return { ok: true, result };
     }
     catch (err) {
@@ -1229,25 +1293,109 @@ async function handleFlow(tabId, state, msg, p) {
     const rawSteps = Array.isArray(p.steps)
         ? p.steps.filter((s) => typeof s === 'object' && s !== null)
         : [];
-    const flowResult = await runFlow(rawSteps, {
+    // Strict `=== true`: any other wire value (missing, "true", 1) runs
+    // the flow FOR REAL. A dry run that silently became a real run would
+    // be the worst possible failure of this flag, so only the exact
+    // boolean opts into it.
+    const dryRun = p.dry_run === true;
+    // The server mints the id (see `browser-dispatch.ts`) so the agent gets
+    // it back even when the extension never answers. The local fallback
+    // covers a server too old to send one: the popup's Stop button must work
+    // regardless of which half was upgraded first.
+    const flowId = typeof p.flow_id === 'string' && p.flow_id.length > 0 ? p.flow_id : newFlowId();
+    // A dry run dispatches nothing and finishes in milliseconds, so it is
+    // deliberately NOT registered: there is nothing to stop, and listing it
+    // would push real runs out of a 20-entry history with entries that never
+    // touched the page.
+    if (dryRun) {
+        const projection = await runFlow(rawSteps, buildFlowDeps(tabId, state), {
+            dryRun: true,
+        });
+        return { kind: 'tool.response', id: msg.id, ok: true, result: projection };
+    }
+    flowRegistry.register({ flowId, tabId, steps: rawSteps.length });
+    // Best effort and deliberately not awaited: the title is only there so
+    // the popup can tell two concurrent flows apart, and no flow should pay
+    // a round trip to chrome.tabs before its first step.
+    void chrome.tabs
+        .get(tabId)
+        .then((tab) => {
+        const entry = flowRegistry.get(flowId);
+        if (entry && typeof tab.title === 'string')
+            entry.title = tab.title;
+    })
+        .catch(() => {
+        // Tab gone or title unavailable — the panel falls back to the id.
+    });
+    const shouldCancel = () => flowRegistry.get(flowId)?.cancelled === true;
+    let flowResult = null;
+    try {
+        flowResult = await runFlow(rawSteps, {
+            ...buildFlowDeps(tabId, state, shouldCancel),
+            shouldCancel,
+            onProgress: (progress) => {
+                const entry = flowRegistry.get(flowId);
+                if (entry)
+                    entry.progress = progress;
+            },
+        });
+        // The wire-level response is ok:true whenever the flow RAN (even a
+        // failed step, and even a cancellation, is a legitimate business
+        // outcome — same pattern as wait_for's matched:false) — flowResult
+        // itself carries the ok:true/false and stopped_by the agent reads.
+        return { kind: 'tool.response', id: msg.id, ok: true, result: flowResult };
+    }
+    finally {
+        // In `finally` so a throw (detached debugger, closed tab) still retires
+        // the registry entry — a phantom "running" flow in the popup would be
+        // worse than no panel at all, since it offers a Stop button that can
+        // never do anything.
+        recordFinishedFlow(flowId, flowResult);
+    }
+}
+/** The perform* bindings `runFlow` needs, in one place so the real run and
+ * the dry-run projection cannot drift apart. `shouldCancel` is threaded
+ * into `performWaitFor` alone: it is the only perform* with a loop of its
+ * own to break out of. */
+function buildFlowDeps(tabId, state, shouldCancel) {
+    return {
         performFind: (params) => performFind(tabId, params),
         performClick: (params) => performClick(tabId, params),
         performType: (params) => performType(tabId, params),
         performPress: (params) => performPress(tabId, params),
-        performWaitFor: (params) => performWaitFor(tabId, state, params),
+        performWaitFor: (params) => performWaitFor(tabId, state, params, shouldCancel),
         performDrag: (params) => performDrag(tabId, params),
         buildRecoverySnapshot: () => evaluateInTab(tabId, buildSnapshotJs({ only_interactive: true, max_interactive: 40 })),
-    }, 
-    // Strict `=== true`: any other wire value (missing, "true", 1) runs
-    // the flow FOR REAL. A dry run that silently became a real run would
-    // be the worst possible failure of this flag, so only the exact
-    // boolean opts into it.
-    { dryRun: p.dry_run === true });
-    // The wire-level response is ok:true whenever the flow RAN (even a
-    // failed step is a legitimate business outcome, same pattern as
-    // wait_for's matched:false) — flowResult itself carries the
-    // ok:true/false the agent reads.
-    return { kind: 'tool.response', id: msg.id, ok: true, result: flowResult };
+    };
+}
+/** Serializes history writes. Appending is a read-modify-write over an
+ * async store, so two flows on the same tab finishing microseconds apart
+ * would otherwise both read the same list and the second `set` would drop
+ * the first's entry. One global chain (rather than one per tab) is enough:
+ * these writes happen once per finished flow, never in a hot path. */
+let flowHistoryWrites = Promise.resolve();
+/** Retire a finished flow: drop it from the in-flight registry and prepend
+ * its outcome to the tab's session-scoped history. Never throws — a
+ * storage failure must not turn a completed flow into a failed tool call. */
+function recordFinishedFlow(flowId, result) {
+    const entry = flowRegistry.finish(flowId);
+    if (!entry)
+        return;
+    const historyEntry = toHistoryEntry(entry, result, Date.now());
+    const key = flowHistoryKey(entry.tabId);
+    flowHistoryWrites = flowHistoryWrites
+        .then(async () => {
+        const data = await chrome.storage.session.get(key);
+        await chrome.storage.session.set({
+            [key]: appendFlowHistory(parseFlowHistory(data[key]), historyEntry),
+        });
+    })
+        .catch(() => {
+        // Best effort, and the chain must survive: the history is an
+        // operator convenience that dies with the browser session anyway, so
+        // one lost entry is not worth surfacing — but swallowing here is
+        // also what keeps a single failure from poisoning every later write.
+    });
 }
 async function handleDrag(tabId, msg, p, optStr) {
     // Thin wire wrapper over performDrag — the same pattern the standalone
@@ -1475,6 +1623,12 @@ async function cleanup(tabId) {
     // `state` and raw CDP calls, never the map entry — and deleting first
     // also makes a re-entrant cleanup a no-op instead of a double detach.
     tabStates.delete(tabId);
+    // A flow cannot outlive its bridge: the debugger is about to detach, so
+    // every remaining step would fail one by one anyway. Cancelling instead
+    // makes the flow stop AT ONCE and report what it completed — and, just
+    // as importantly, keeps the popup from offering a Stop button for a flow
+    // whose tab is already being torn down.
+    flowRegistry.cancelForTab(tabId);
     // 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
@@ -1808,6 +1962,20 @@ async function doConnectTab(tabId) {
                             send(ws, response);
                         return;
                     }
+                    case 'tool.cancel': {
+                        // Deliberately answered with SILENCE: the cancelled flow is
+                        // still parked in its own tool.request and replies there,
+                        // cleanly, with stopped_by:'cancelled' and its partial
+                        // results. An unknown or already-finished flow_id is a no-op —
+                        // the caller wanted the flow not running, and it is not.
+                        //
+                        // Counts as activity: an agent reaching for the kill switch is
+                        // very much using this tab, and letting the idle sweeper close
+                        // the bridge underneath it would be perverse.
+                        state.lastActivityAt = Date.now();
+                        flowRegistry.cancel(msg.flow_id);
+                        return;
+                    }
                     default: {
                         // Compile-time exhaustiveness check; at runtime an unknown kind
                         // (newer server, older extension) is ignored defensively.
@@ -2287,6 +2455,18 @@ chrome.runtime.onMessage.addListener((msg, _sender, sendResponse) => {
         void saveRecording(msg.tabId, msg.name, msg.description).then(sendResponse);
         return true;
     }
+    if (msg.action === 'flowsStatus') {
+        void getFlowsStatus(msg.tabId).then(sendResponse);
+        return true;
+    }
+    if (msg.action === 'cancelFlow') {
+        // Synchronous and unconditional: one boolean flip, then the runner
+        // stops at its next check. `cancelled` reports whether THIS call is
+        // what stopped it, so the popup can distinguish "stopping…" from an
+        // id that had already finished — never an error either way.
+        sendResponse({ cancelled: flowRegistry.cancel(msg.flowId) });
+        return false;
+    }
     // 'status'
     sendResponse(getTabStatus(msg.tabId));
     return false;
@@ -2299,6 +2479,11 @@ chrome.tabs.onRemoved.addListener((tabId) => {
     });
     // The Chrome tab is gone — drop any cached browser-link id for it.
     void forgetTabId(tabId);
+    // …and its flow history. Chrome reuses tab ids within a session, so a
+    // stale key would eventually show one tab's flows under another's.
+    void chrome.storage.session.remove(flowHistoryKey(tabId)).catch(() => {
+        // Best effort — session storage dies with the browser anyway.
+    });
 });
 /* Auto-connect tabs spawned by a connected tab.
  *