@trusty-squire/mcp 1.1.16-rc.4 → 1.1.16-rc.5

package/README.md

@@ -87,7 +87,7 @@ npx @trusty-squire/mcp connect
 
 `connect` signs you in with Google or GitHub, detects your coding agent, and merges the `squire` MCP server into its existing configuration. On an enrolled machine, sign-in opens a tab in Trusty Squire's shared browser. When that browser is on the machine's own screen and you are running `connect` there, you finish sign-in in the window in front of you — no URL and no virtual display. Otherwise — the shared browser started without a screen and sits on a private Linux display, or you are running `connect` over SSH or a TTY with no screen of your own — the ceremony prints a single-use noVNC URL; open that URL on another device. The URL shows and controls the whole display that browser runs on until the ceremony ends: other sessions' tabs, and on a machine with its own screen, everything else on that screen. macOS and Windows draw their windows natively, so the shared browser's tab is on the screen in front of you there and nothing is exposed over noVNC. If the display cannot be shown, connect stops with an explanation instead of waiting indefinitely. On a first connect where no broker can serve, connect launches its own sign-in browser, using a visible desktop when one still answers or a login-scoped Xvfb + noVNC stack on headless Linux (including SSH/TTY sessions with an inherited virtual display, and a display that has stopped answering since startup).
 
-Ceremony completion, timeout, failure, or interruption tears down its quick tunnel and local exposure helpers. The shared browser and its display remain with the broker; a self-launched ceremony also closes its own browser and display. Operators may set both `TS_LOGIN_PUBLIC_HOSTNAME` and `TS_LOGIN_LOCAL_PORT` to reuse an externally managed named tunnel, which Trusty Squire never creates or stops. If that fixed local port is busy, login reports it and uses a one-off quick tunnel instead. Restart the agent and ask for the finished website outcome. Trusty Squire is free to start.
+Ceremony completion, timeout, failure, or interruption tears down its quick tunnel and local exposure helpers. Those helpers also hold a bound of their own — the sign-in link's lifetime plus a short grace, counted from the moment they are stood up — so a `connect` that is abandoned, wedged, or never waits still tears the display down and exits non-zero instead of leaving a tunnel published. The shared browser and its display remain with the broker; a self-launched ceremony also closes its own browser and display. Operators may set both `TS_LOGIN_PUBLIC_HOSTNAME` and `TS_LOGIN_LOCAL_PORT` to reuse an externally managed named tunnel, which Trusty Squire never creates or stops. If that fixed local port is busy, login reports it and uses a one-off quick tunnel instead. Restart the agent and ask for the finished website outcome. Trusty Squire is free to start.
 
 `connect` is also the only way to sign in again: `--force-relogin` switches the bound account and `--force-relogin=google` or `--force-relogin=github` refreshes one provider session. It re-checks provider sessions before reporting success; when the shared browser keeps the profile busy, that check uses committed cookies, which can outlive a server-side session. Use `--force-relogin` to refresh a stale session. The detailed [provider-probe and ceremony contract](docs/browser-broker.md) describes completion and failure handling.
 
@@ -127,7 +127,7 @@ Each report carries seven fields:
 - `browser_location` — where the ceremony browser actually opened, reported by the code that placed it: `{kind:"host_screen",display?}` (the screen you are at), `{kind:"virtual",url}` (a display nobody is sitting at — `url` is the noVNC address that reaches it, reported on a non-terminal line the moment the browser lands there, while the tunnel is up), `{kind:"unreachable",reason}` (nothing here could be shown the page — also the answer when a ceremony ran but no path ever reported a placement, with `reason` naming the failure), `{kind:"none"}` (no browser was opened), or `{kind:"unknown",reason}` (a browser opened that Squire did not place — `--skip-browser` hands the link to the machine's default browser). Squire decides this; callers do not detect screens.
 - `reason` — only what the five fields above cannot say: `provider_session_missing`, `requested_provider_missing`, `account_mismatch`, `profile_unverifiable`, `install_expired`, `cached_cookie_evidence`, `run_failed`. `null` otherwise.
 
-Connect never waits longer than the sign-in link lives — the wait is the link's lifetime counted from the moment connect received it, so a skewed machine clock cannot shorten or overrun it. A `sign_in_url` it hands back is still open; a wait that reached that deadline, or a link the server reported lapsed, is `no-browser` with `reason: "install_expired"` and no URL at all.
+Connect never waits longer than the sign-in link lives — the wait is the link's lifetime counted from the moment connect received it, so a skewed machine clock cannot shorten or overrun it. A `sign_in_url` it hands back is still open; a wait that reached that deadline, or a link the server reported lapsed, is `no-browser` with `reason: "install_expired"` and no URL at all. A ceremony display that outlives its own bound answers the same way, on a terminal line written before connect exits — so a run that wedged before it ever reached that wait still ends the machine channel.
 
 Supported targets: `claude-code`, `cursor`, `codex`, `opencode`, `goose`, `cline`, `continue`, and `hermes`.
 
@@ -190,6 +190,12 @@ grant; host scoping, auditing, and revocation still apply. When a grant reaches
 an explicit hourly limit, the proxy returns `429 rate_limited` with
 `scope: "grant"`, `Retry-After`, and window/reset metadata.
 
+The proxy passes the provider's response through as it arrives and forwards the
+upstream response headers (cookies, hop-by-hop headers, and the upstream
+content-length removed), so a streaming completion — `stream: true`,
+`text/event-stream` — reaches the app event by event rather than in one block
+once generation has finished. The body is not buffered and carries no size cap.
+
 The result contains a host-scoped egress `base_url` and a `token`, not the Clerk secret key. The token is returned once through the MCP result and remains valid until revoked. That means the scoped grant token can enter agent context; it is not the provider key. Move it directly into backend-only deployment secret storage, never browser code, logs, or source control. If you need zero grant-token exposure to the model, use `use_credential` for agent-initiated requests instead. Trusty Squire removes the grant authorization at the boundary and injects the vaulted provider credential into the upstream request.
 
 ## Security and threat model

package/dist/bot/act/act.d.ts

@@ -5,6 +5,18 @@ import { type ObserveDetail } from "../observe/observe.js";
 import { type CompactV2TargetAuthorization } from "./targets.js";
 import type { Observation, ProvisionAction } from "../provision-session.js";
 import type { Session } from "../session/model.js";
+export type ActExecutorOptions = {
+    drive?: boolean;
+};
+export type DriveActResult = {
+    kind: "ok";
+    combobox: boolean;
+} | {
+    kind: "stale";
+    reason: string;
+} | {
+    kind: "unsupported";
+};
 export declare function runSerializedGoogleIdentityOperation<T>(session: Session, operation: (browser: BrowserController) => Promise<T>, options?: {
     deadline?: OAuthActionDeadline;
 }): Promise<{
@@ -17,9 +29,11 @@ export interface InternalActResult {
     outcome: {
         selectedOption?: string;
     };
+    combobox?: boolean;
 }
-export declare function actInternally(sessionId: string, action: ProvisionAction, detail?: ObserveDetail, compactV2Authorization?: CompactV2TargetAuthorization, operationPage?: Page): Promise<InternalActResult>;
+export declare function actInternally(sessionId: string, action: ProvisionAction, detail?: ObserveDetail, compactV2Authorization?: CompactV2TargetAuthorization, operationPage?: Page, options?: ActExecutorOptions): Promise<InternalActResult>;
 export declare function act(sessionId: string, action: ProvisionAction, detail?: ObserveDetail, outputFormat?: "compact" | "full", compactMapEmitted?: boolean): Promise<Observation>;
+export declare function dispatchDriveAct(sessionId: string, action: ProvisionAction): Promise<DriveActResult>;
 export declare function compactV2SelectionFailureReason(error: unknown): string;
 export declare function settleAfterDriveAction(page?: Page, combobox?: boolean): Promise<void>;
 export declare function settleAfterStateChange(browser: BrowserController, page?: Page, options?: {

package/dist/bot/act/act.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"act.d.ts","sourceRoot":"","sources":["../../../src/bot/act/act.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EAGL,KAAK,iBAAiB,EAEvB,MAAM,eAAe,CAAC;AACvB,OAAO,EAWL,KAAK,mBAAmB,EAIzB,MAAM,mBAAmB,CAAC;AAY3B,OAAO,EAOL,KAAK,aAAa,EAMnB,MAAM,uBAAuB,CAAC;AAU/B,OAAO,EAiBL,KAAK,4BAA4B,EAClC,MAAM,cAAc,CAAC;AAEtB,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC5E,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AA4EnD,wBAAsB,oCAAoC,CAAC,CAAC,EAC1D,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,OAAO,CAAC,CAAC,CAAC,EACrD,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,mBAAmB,CAAA;CAAO,GAC/C,OAAO,CAAC;IAAE,OAAO,EAAE,iBAAiB,CAAC;IAAC,MAAM,EAAE,CAAC,CAAA;CAAE,CAAC,CAOpD;AA+GD,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,WAAW,CAAC;IACzB,aAAa,CAAC,EAAE,IAAI,CAAC;IACrB,OAAO,EAAE;QACP,cAAc,CAAC,EAAE,MAAM,CAAC;KACzB,CAAC;CACH;AAqED,wBAAsB,aAAa,CACjC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,eAAe,EACvB,MAAM,GAAE,aAAyB,EACjC,sBAAsB,CAAC,EAAE,4BAA4B,EACrD,aAAa,CAAC,EAAE,IAAI,GACnB,OAAO,CAAC,iBAAiB,CAAC,CAgD5B;AAED,wBAAsB,GAAG,CACvB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,eAAe,EACvB,MAAM,GAAE,aAAyB,EACjC,YAAY,GAAE,SAAS,GAAG,MAAe,EACzC,iBAAiB,UAAO,GACvB,OAAO,CAAC,WAAW,CAAC,CAwGtB;AAsjBD,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEtE;AA+FD,wBAAsB,sBAAsB,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,UAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAwCzF;AAED,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,iBAAiB,EAC1B,IAAI,CAAC,EAAE,IAAI,EACX,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAE,GAChD,OAAO,CAAC,IAAI,CAAC,CAUf"}
+{"version":3,"file":"act.d.ts","sourceRoot":"","sources":["../../../src/bot/act/act.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAS,IAAI,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,EAIL,KAAK,iBAAiB,EAEvB,MAAM,eAAe,CAAC;AACvB,OAAO,EAWL,KAAK,mBAAmB,EAIzB,MAAM,mBAAmB,CAAC;AAY3B,OAAO,EAOL,KAAK,aAAa,EAMnB,MAAM,uBAAuB,CAAC;AAU/B,OAAO,EAiBL,KAAK,4BAA4B,EAClC,MAAM,cAAc,CAAC;AAEtB,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC5E,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAuBnD,MAAM,MAAM,kBAAkB,GAAG;IAC/B,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AAIF,MAAM,MAAM,cAAc,GACtB;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,aAAa,CAAA;CAAE,CAAC;AA4E5B,wBAAsB,oCAAoC,CAAC,CAAC,EAC1D,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,OAAO,CAAC,CAAC,CAAC,EACrD,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,mBAAmB,CAAA;CAAO,GAC/C,OAAO,CAAC;IAAE,OAAO,EAAE,iBAAiB,CAAC;IAAC,MAAM,EAAE,CAAC,CAAA;CAAE,CAAC,CAOpD;AA+GD,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,WAAW,CAAC;IACzB,aAAa,CAAC,EAAE,IAAI,CAAC;IACrB,OAAO,EAAE;QACP,cAAc,CAAC,EAAE,MAAM,CAAC;KACzB,CAAC;IACF,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAqED,wBAAsB,aAAa,CACjC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,eAAe,EACvB,MAAM,GAAE,aAAyB,EACjC,sBAAsB,CAAC,EAAE,4BAA4B,EACrD,aAAa,CAAC,EAAE,IAAI,EACpB,OAAO,CAAC,EAAE,kBAAkB,GAC3B,OAAO,CAAC,iBAAiB,CAAC,CA4D5B;AAED,wBAAsB,GAAG,CACvB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,eAAe,EACvB,MAAM,GAAE,aAAyB,EACjC,YAAY,GAAE,SAAS,GAAG,MAAe,EACzC,iBAAiB,UAAO,GACvB,OAAO,CAAC,WAAW,CAAC,CAwGtB;AA6vBD,wBAAsB,gBAAgB,CACpC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,eAAe,GACtB,OAAO,CAAC,cAAc,CAAC,CA+DzB;AAED,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEtE;AA+FD,wBAAsB,sBAAsB,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,UAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAwCzF;AAED,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,iBAAiB,EAC1B,IAAI,CAAC,EAAE,IAAI,EACX,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAE,GAChD,OAAO,CAAC,IAAI,CAAC,CAUf"}

package/dist/bot/act/act.js

@@ -1,4 +1,4 @@
-import { BrowserClickDispatchError, clickDispatchStatusForError, } from "../browser.js";
+import { BrowserClickDispatchError, DRIVE_DISPATCH_PACING, clickDispatchStatusForError, } from "../browser.js";
 import { loginWithOAuth, oauthActionDeadline, oauthActionRemainingMs, oauthAutomatedActionTimeoutMs, oauthHumanHandoffTimeoutMs, oauthLoginLeaseCooldownMs, resetOAuthActionDeadline, settleAfterOAuth, withOAuthActionLease, withinOAuthActionDeadline, OAuthAwaitingHumanError, OAuthFailedError, OAuthOnboardingRequiredError, } from "../oauth-login.js";
 import { compactV2AuditUrl, safeStageV2 } from "../compact-observation-v2.js";
 import { ProvenPreDispatchMutationError } from "../mutation-dispatch-evidence.js";
@@ -11,6 +11,10 @@ import { substituteCardTokens } from "../card-secret-tokens.js";
 import { clickScreenshot, ScreenshotClickError } from "../screenshot-click.js";
 import { composeOperatorSignals, currentOperatorRequestSignal, operatorMutationDispatchPhase, } from "../request-cancellation.js";
 import { AmbiguousProvisionTargetError, compactV2AuthorizationForTarget, frameTargetFor, isRequiredShippingAddressLine1, parseLocatorTarget, preparedOAuthLoginTarget, resolveAuthorizedCompactV2Target, resolveTarget, staleTargetError, TargetStaleError, throwCompactV2StaleRef, CompactV2ActionFailureError, CompactV2StaleRefError, CompactV2UnresolvedLabelError, ProvisionTargetMissingError, ProvisionTargetNotAllowedError, } from "./targets.js";
+import { resolveIdentityScope, resolveLiveControlIdentity, } from "./identity.js";
+import { evaluateBound } from "../drive-evaluate.js";
+import { clickCrossOriginFrameTarget, commitDriveListOption, selectDriveOption, overlayOptionLabels, waitForOpenedOverlay, waitForOverlayOptionsToChange, } from "../drive-act.js";
+const DRIVE_DISPATCH = { drive: true };
 async function withOAuthActionBoundary(session, provider, run, outputFormat) {
     if (provider === "google") {
         const gate = await googleSessionGateForSession(session.id);
@@ -206,13 +210,18 @@ function oauthOnboardingRequiredObservation(session, error) {
     };
     return compactV2PublicObservation(session, { stage: "form", guidance, oauth, url });
 }
-export async function actInternally(sessionId, action, detail = "compact", compactV2Authorization, operationPage) {
+export async function actInternally(sessionId, action, detail = "compact", compactV2Authorization, operationPage, options) {
     const session = sessionForCall(sessionId);
     const capturedOperationPage = operationPage ?? (session === undefined ? undefined : operationPageForSession(session));
     const oauthProvider = action.kind === "oauth_login" || action.kind === "oauth_click" ? action.provider : undefined;
     try {
         const execute = async (deadline) => {
-            const run = async () => await executeAct(sessionId, action, detail, true, compactV2Authorization, deadline, capturedOperationPage, false);
+            const run = async () => {
+                const act = async () => await executeAct(sessionId, action, detail, true, compactV2Authorization, deadline, capturedOperationPage, false, undefined, "full", true, options);
+                return session === undefined || options?.drive !== true
+                    ? await act()
+                    : await session.browser.withDispatchPacing(DRIVE_DISPATCH_PACING, act);
+            };
             return (action.kind === "click" ||
                 action.kind === "js_click" ||
                 action.kind === "oauth_login" ||
@@ -240,7 +249,7 @@ export async function actInternally(sessionId, action, detail = "compact", compa
             return { observation: oauthOnboardingRequiredObservation(session, error), outcome: {} };
         }
         if (session?.compactV2Active === true && !(error instanceof ProvisionTargetMissingError)) {
-            throw new CompactV2ActionFailureError(compactV2ActionFailureReason(error, action.kind));
+            throw new CompactV2ActionFailureError(compactV2ActionFailureReason(error, action.kind), clickDispatchStatusForError(error));
         }
         throw error;
     }
@@ -341,10 +350,90 @@ function actDriverTarget(el) {
         return { kind: "frame", frame, selector: el.selector };
     return { kind: "selector", selector: el.selector };
 }
+function actsThroughOverlay(el, picker) {
+    if (picker)
+        return true;
+    const role = (el.role ?? "").toLowerCase();
+    const type = (el.type ?? "").toLowerCase();
+    return (role === "combobox" ||
+        role === "searchbox" ||
+        type === "search" ||
+        type === "date" ||
+        type === "datetime-local" ||
+        type === "month");
+}
+function submitsOnEnter(el, ariaLabel) {
+    const role = (el.role ?? "").toLowerCase();
+    const type = (el.type ?? "").toLowerCase();
+    return (role === "searchbox" ||
+        type === "search" ||
+        el.name === "q" ||
+        /search/i.test(`${ariaLabel} ${el.placeholder ?? ""}`));
+}
+function scopeForElement(page, el) {
+    if (el.framePath === undefined || el.framePath === null || el.framePath.length === 0)
+        return page;
+    let frame = page.mainFrame();
+    for (const part of el.framePath.split("/")) {
+        const child = frame.childFrames()[Number(part)];
+        if (child === undefined)
+            return page;
+        frame = child;
+    }
+    return frame;
+}
+// The occlusion guard the drive used to carry in its own dispatch: a cookie
+// banner or sticky footer over the target swallows the click while the page
+// still reports a dispatch, so the caller records a step that never landed.
+// Absent a box (still loading) it says nothing and the actionability waits rule.
+async function clickTargetOccluded(scope, selector) {
+    return await evaluateBound(scope, (sel) => {
+        const element = document.querySelector(sel);
+        if (element === null)
+            return false;
+        // The snapshot keeps offscreen fillables so the model can name them, and
+        // the dispatch scrolls before clicking — so measure where the click will
+        // actually land, not where the element sits right now. "instant" is
+        // load-bearing: a page with scroll-behavior:smooth would animate and the
+        // rect below would still be the pre-scroll one.
+        const before = element.getBoundingClientRect();
+        const inView = before.width > 0 &&
+            before.height > 0 &&
+            before.bottom > 0 &&
+            before.top < innerHeight &&
+            before.right > 0 &&
+            before.left < innerWidth;
+        if (!inView) {
+            element.scrollIntoView({ block: "center", inline: "nearest", behavior: "instant" });
+        }
+        const rect = element.getBoundingClientRect();
+        if (rect.width <= 0 || rect.height <= 0)
+            return false;
+        const hit = document.elementFromPoint(rect.x + rect.width / 2, rect.y + rect.height / 2);
+        return hit !== null && hit !== element && !element.contains(hit) && !hit.contains(element);
+    }, selector).catch(() => false);
+}
 // Re-resolve against FRESH elements — never trust a stale index. Shared by the
 // type_secret / select / click-group ref paths; `internalLabel`/`noMatchPrefix`
 // keep each caller's error wording, `withVisibleCandidates` its candidate list.
 async function resolveFreshActTarget(session, browser, compactV2ActionPage, compactV2Authorization, resolutionTarget, internalAccess, internalLabel, noMatchPrefix, actionTarget, withVisibleCandidates) {
+    const driveIdentity = session.drive?.identities?.get(resolutionTarget);
+    const livePage = compactV2ActionPage ?? browser.page;
+    if (driveIdentity !== undefined && livePage !== null) {
+        const live = await resolveLiveControlIdentity(livePage, resolutionTarget, driveIdentity);
+        if (live !== null) {
+            return { el: live, fresh: session.lastElements, driveIdentity };
+        }
+        if (session.compactV2Active) {
+            if (!internalAccess)
+                throwCompactV2StaleRef();
+            throw new CompactV2StaleRefError("stale_ref");
+        }
+        const stale = staleTargetError(session, actionTarget, session.lastElements);
+        if (stale !== null)
+            throw stale;
+        throw new CompactV2StaleRefError("stale_ref");
+    }
     const fresh = (await browser.extractBrowserUseObservation(compactV2ActionPage)).elements;
     retainSessionElements(session, fresh);
     // resolveTarget recomputes identities (incl. volatile positional-group
@@ -354,7 +443,7 @@ async function resolveFreshActTarget(session, browser, compactV2ActionPage, comp
         ? resolveTarget(fresh, resolutionTarget)
         : resolveAuthorizedCompactV2Target(session, fresh, compactV2Authorization);
     if (el !== null)
-        return { el, fresh };
+        return { el, fresh, driveIdentity: undefined };
     if (session.compactV2Active) {
         if (!internalAccess)
             throwCompactV2StaleRef();
@@ -373,15 +462,18 @@ async function resolveFreshActTarget(session, browser, compactV2ActionPage, comp
         : "";
     throw new Error(`${prefix}no element matched target "${actionTarget}".${visible}`);
 }
-async function executeAct(sessionId, action, detail, internalAccess, internalAuthorization, oauthDeadline, operationPage, preparedOAuthDispatch = false, onScreenshotDispatched, outputFormat = "full", compactMapEmitted = true) {
+async function executeAct(sessionId, action, detail, internalAccess, internalAuthorization, oauthDeadline, operationPage, preparedOAuthDispatch = false, onScreenshotDispatched, outputFormat = "full", compactMapEmitted = true, options) {
     const session = sessionForCall(sessionId);
     if (session === undefined)
         throw new Error(`unknown provision session ${sessionId}`);
     let browser = session.browser;
     const compactV2ActionPage = operationPage ?? operationPageForSession(session);
     const driveSettle = session.drive !== null && action.kind !== "oauth_login" && action.kind !== "oauth_click";
+    const skipToolSettle = options?.drive === true;
     let settleMs = 0;
     const settle = async (combobox = false) => {
+        if (skipToolSettle)
+            return;
         const started = Date.now();
         await settleAfterStateChange(browser, compactV2ActionPage, {
             drive: driveSettle,
@@ -390,6 +482,7 @@ async function executeAct(sessionId, action, detail, internalAccess, internalAut
         settleMs += Date.now() - started;
     };
     const actStarted = Date.now();
+    let actedCombobox = false;
     let actionPageAfter = compactV2ActionPage;
     let completedAction = action;
     let resolutionTarget;
@@ -529,7 +622,10 @@ async function executeAct(sessionId, action, detail, internalAccess, internalAut
             }
             case "select": {
                 const el = (await resolveFreshActTarget(session, browser, compactV2ActionPage, compactV2Authorization, resolutionTarget, internalAccess, "select", "select", action.target, true)).el;
-                const committedText = await browser.select(actDriverTarget(el), action.text, compactV2ActionPage);
+                const driveSelectPage = compactV2ActionPage ?? browser.page;
+                const committedText = options?.drive === true && driveSelectPage !== null && driveSelectPage !== undefined
+                    ? await selectDriveOptionOrRefuse(scopeForElement(driveSelectPage, el), el.selector, action.text ?? "")
+                    : await browser.select(actDriverTarget(el), action.text, compactV2ActionPage);
                 session.committedSelectValues.set(compactV2CommittedSelectKey(session, el.selector), compactV2CommittedSelectValue(session, committedText));
                 completedAction = { ...action, text: committedText };
                 await settle();
@@ -629,18 +725,79 @@ async function executeAct(sessionId, action, detail, internalAccess, internalAut
                     break;
                 }
                 // Re-resolve against FRESH elements every act — never trust a stale index.
-                const { el, fresh } = await resolveFreshActTarget(session, browser, compactV2ActionPage, compactV2Authorization, resolutionTarget, internalAccess, action.kind, "", action.target, true);
+                const { el, fresh, driveIdentity } = await resolveFreshActTarget(session, browser, compactV2ActionPage, compactV2Authorization, resolutionTarget, internalAccess, action.kind, "", action.target, true);
+                actedCombobox = actsThroughOverlay(el, driveIdentity?.picker === true);
+                const ariaLabelAttribute = driveIdentity === undefined ? (el.ariaLabel ?? "") : (driveIdentity.ariaLabel ?? "");
                 // Preserve frame identity (origin + path) for the frame-scoped fill.
                 if (action.kind === "click" || action.kind === "js_click") {
+                    const clickPage = compactV2ActionPage ?? browser.page;
+                    // Only the drive's extra dispatch arms consume a frame scope; the
+                    // tools reach a frame through actDriverTarget's frame target, so
+                    // walking the positional frame path for them would be dead work.
+                    const clickScope = options?.drive !== true || clickPage === null || clickPage === undefined
+                        ? undefined
+                        : scopeForElement(clickPage, el);
+                    if (action.kind === "click" &&
+                        clickScope !== undefined &&
+                        (await clickTargetOccluded(clickScope, el.selector))) {
+                        throw new BrowserClickDispatchError("not_dispatched", "click target is occluded by an overlay");
+                    }
+                    // One adoption arm/grace around whichever dispatch runs: an option row
+                    // or a cross-origin coordinate click can open a target=_blank tab
+                    // just as an ordinary click can, and paying the grace per candidate
+                    // would charge every click for the branches that declined.
+                    const commitsListOption = action.kind === "click" &&
+                        clickPage !== null &&
+                        clickPage !== undefined &&
+                        clickScope !== undefined;
+                    const crossOriginScope = action.kind === "click" && clickScope !== undefined && "parentFrame" in clickScope
+                        ? clickScope
+                        : undefined;
                     actionPageAfter =
                         (await adoptTabOpenedByClick(session, browser, async () => {
+                            if (commitsListOption &&
+                                clickPage !== null &&
+                                clickPage !== undefined &&
+                                clickScope !== undefined &&
+                                (await commitDriveListOption(clickPage, clickScope, el.selector))) {
+                                return;
+                            }
+                            if (crossOriginScope !== undefined &&
+                                clickPage !== null &&
+                                clickPage !== undefined &&
+                                (await clickCrossOriginFrameTarget(clickPage, crossOriginScope, el.selector))) {
+                                return;
+                            }
                             await actClick({ ...actDriverTarget(el), method: action.kind });
                         })) ?? actionPageAfter;
                 }
                 else if (action.kind === "type") {
                     clearCommittedSelectValue(session, el.selector);
                     const actTarget = actDriverTarget(el);
-                    await actType(actTarget, typedText, false);
+                    if (options?.drive === true && actedCombobox && compactV2ActionPage !== undefined) {
+                        // The click may remount the field into an overlay that takes focus,
+                        // so the text goes to whatever is focused — after an explicit
+                        // select-all, because insertText alone APPENDS to a committed value.
+                        // The suggestion baseline is read AFTER the overlay opens; reading
+                        // it before would make the refresh wait return on the stale rows.
+                        await actClick({ ...actTarget, method: "click" });
+                        await waitForOpenedOverlay(compactV2ActionPage).catch(() => undefined);
+                        const overlayBefore = await overlayOptionLabels(compactV2ActionPage);
+                        await compactV2ActionPage.keyboard.press("ControlOrMeta+a");
+                        await compactV2ActionPage.keyboard.insertText(typedText ?? "");
+                        await waitForOverlayOptionsToChange(compactV2ActionPage, overlayBefore);
+                        if (submitsOnEnter(el, ariaLabelAttribute)) {
+                            await compactV2ActionPage.keyboard.press("Enter").catch(() => undefined);
+                        }
+                    }
+                    else {
+                        await actType(actTarget, typedText, false);
+                        if (options?.drive === true && submitsOnEnter(el, ariaLabelAttribute)) {
+                            await (compactV2ActionPage ?? browser.page)?.keyboard
+                                .press("Enter")
+                                .catch(() => undefined);
+                        }
+                    }
                     // #635 fix (not a gate on typing): Shopify only enables delivery-rate
                     // selection after the required address line is committed by
                     // blur/change, not merely after the raw keystrokes land.
@@ -755,6 +912,7 @@ async function executeAct(sessionId, action, detail, internalAccess, internalAut
     if (session.drive !== null) {
         const observeMs = Date.now() - observeStarted;
         session.drive.lastActProfile = {
+            ...session.drive.lastActProfile,
             act_ms: Math.max(0, Date.now() - actStarted - settleMs - observeMs),
             settle_ms: settleMs,
             observe_ms: observeMs,
@@ -782,8 +940,88 @@ async function executeAct(sessionId, action, detail, internalAccess, internalAut
         outcome: {
             ...(completedAction.kind === "select" ? { selectedOption: completedAction.text } : {}),
         },
+        combobox: actedCombobox,
     };
 }
+async function selectDriveOptionOrRefuse(scope, selector, text) {
+    const { outcome, committed } = await selectDriveOption(scope, selector, text);
+    if (outcome === "ok")
+        return committed;
+    if (outcome === "missing")
+        throw new CompactV2StaleRefError("stale_ref");
+    throw new CompactV2ActionFailureError(outcome);
+}
+async function guardDriveOauthTarget(sessionId, target) {
+    const session = sessionForCall(sessionId);
+    const identity = session?.drive?.identities?.get(target);
+    const page = session?.browser.page ?? null;
+    if (session === undefined || identity === undefined || page === null) {
+        return { kind: "unsupported" };
+    }
+    const scope = await resolveIdentityScope(page, target, identity);
+    if (scope === null)
+        return { kind: "stale", reason: "stale_ref" };
+    if (await clickTargetOccluded(scope, identity.selector)) {
+        return { kind: "stale", reason: "occluded" };
+    }
+    return { kind: "unsupported" };
+}
+export async function dispatchDriveAct(sessionId, action) {
+    // "unsupported" means the shared executor has no drive verb for this action
+    // and the caller should fall back to the tools path. A DISPATCH failure is a
+    // different thing — the act did not land on the control, which is stale.
+    if (action.kind !== "click" &&
+        action.kind !== "type" &&
+        action.kind !== "select" &&
+        action.kind !== "scroll") {
+        // The tools' oauth_login clicks by coordinate after a visibility wait only,
+        // so a banner over the provider button costs the whole OAuth deadline. Hand
+        // the drive the same refusal its own guard gave, and fall through to the
+        // tools path only when the target is clean.
+        if (action.kind === "oauth_login")
+            return await guardDriveOauthTarget(sessionId, action.target);
+        return { kind: "unsupported" };
+    }
+    // A drive ref names the identity its own snapshot recorded. A target with no
+    // such record never came from a drive snapshot — a row from a fallback
+    // observation the drive did not capture — so it is the tools' to resolve.
+    // Dispatching it here would fail resolution and report a live control stale.
+    if (action.kind !== "scroll" &&
+        sessionForCall(sessionId)?.drive?.identities?.get(action.target) === undefined) {
+        return { kind: "unsupported" };
+    }
+    try {
+        const result = await actInternally(sessionId, action, "none", undefined, undefined, DRIVE_DISPATCH);
+        return { kind: "ok", combobox: result.combobox === true };
+    }
+    catch (error) {
+        if (error instanceof CompactV2StaleRefError)
+            return { kind: "stale", reason: "stale_ref" };
+        if (error instanceof TargetStaleError)
+            return { kind: "stale", reason: "stale" };
+        const message = error instanceof Error ? error.message : String(error);
+        // A tracked click that reached the element and only then failed did land —
+        // telling the drive it never executed invites a second submit. The evidence
+        // is a CLICK's own dispatch listener, so it says nothing about a type whose
+        // focusing click landed before the keystrokes were written.
+        const dispatchStatus = error instanceof CompactV2ActionFailureError
+            ? error.dispatchStatus
+            : clickDispatchStatusForError(error);
+        if (action.kind === "click" && dispatchStatus === "dispatched") {
+            return { kind: "ok", combobox: false };
+        }
+        // A select that could not take the value was refused by the CONTROL; the
+        // drive must not blame the ref and retire it. A ref that went stale before
+        // the select was ever attempted stays stale.
+        if (action.kind === "select" && !/stale_ref|reobserve_required/i.test(message)) {
+            return { kind: "stale", reason: message === "not_select" ? "not_select" : "option_missing" };
+        }
+        return {
+            kind: "stale",
+            reason: /occluded|intercepts pointer/i.test(message) ? "occluded" : "stale_ref",
+        };
+    }
+}
 export function compactV2SelectionFailureReason(error) {
     return compactV2ActionFailureReason(error, "select");
 }