cascade-ai 0.78.0 → 0.80.0

package/dist/index.cjs

@@ -11669,7 +11669,7 @@ function reconcilePrice(model, live) {
 }
 
 // src/constants.ts
-var CASCADE_VERSION = "0.78.0";
+var CASCADE_VERSION = "0.80.0";
 var CASCADE_CONFIG_DIR = ".cascade";
 var CASCADE_MD_FILE = "CASCADE.md";
 var CASCADE_IGNORE_FILE = ".cascadeignore";
@@ -16144,6 +16144,31 @@ var ToolsConfigSchema = zod.z.object({
    * stop control for the run that is acting.
    */
   agentBrowserControl: zod.z.boolean().default(false),
+  /**
+   * Where a HOSTED run gets a browser, since it has none of its own.
+   *
+   * The desktop drives the Chromium the user is signed into and can watch. A
+   * server has neither, and running one inside the container is wrong twice
+   * over — page JavaScript issues requests no URL check ever sees, from inside
+   * the trust boundary, and a session costs 200-400 MB. So this points at a
+   * browser somebody else runs.
+   *
+   * Absent by default: no provider, no capability. There is nothing to turn
+   * off because nothing is registered until an endpoint is supplied.
+   */
+  remoteBrowser: zod.z.object({
+    /** `cdp` for an endpoint you run; `steel` for a Steel deployment. */
+    provider: zod.z.enum(["cdp", "steel"]).optional(),
+    /** The websocket endpoint for `cdp`, or the API base for `steel`. */
+    url: zod.z.string().optional(),
+    apiKey: zod.z.string().optional(),
+    /**
+     * Concurrent sessions. One by default and deliberately so: every session
+     * is billed, and a wave of workers each opening their own is a cost the
+     * user did not choose. Raising it is a decision, not a default.
+     */
+    maxSessions: zod.z.number().int().min(1).max(16).default(1)
+  }).optional(),
   mcpServers: zod.z.array(McpServerConfigSchema).optional(),
   mcpTrusted: zod.z.array(zod.z.string()).optional(),
   /** Web search backends — at least one should be configured for best results */
@@ -31412,8 +31437,38 @@ ${input}` }],
    * run — it is simply not there.
    */
   setBrowserController(controller, release) {
+    this.registerBrowserControl(controller, release, this.config.tools?.agentBrowserControl === true);
+  }
+  /**
+   * Wire a REMOTE browser — one the host connects to rather than one the user
+   * is signed into.
+   *
+   * A separate entry point because the enablement is a different question, and
+   * conflating them made the hosted capability dead on arrival: this went out
+   * calling `setBrowserController`, which gates on `agentBrowserControl`, and
+   * that flag means "drive the browser I am signed into on this machine". It
+   * defaults to false and has no meaning on a server, so the hosted tool was
+   * never registered at all — the feature looked shipped and did nothing.
+   *
+   * Configuring a provider IS the opt-in here. It takes a deliberate act with
+   * an endpoint and usually a paid account, and the browser it reaches is a
+   * throwaway signed into nothing — a smaller consent than handing over the
+   * session the user is already authenticated in, and one the desktop flag
+   * cannot stand in for.
+   */
+  setRemoteBrowserController(controller, release) {
+    this.registerBrowserControl(controller, release, Boolean(this.config.tools?.remoteBrowser?.provider));
+  }
+  /**
+   * The gates every surface shares, with only enablement differing.
+   *
+   * One place, because the two callers above are exactly the sibling-writer
+   * shape that has already drifted twice in this feature: a rule added to one
+   * and not the other is silent on the surface that missed it.
+   */
+  registerBrowserControl(controller, release, enabled) {
     if (this.unattended) return;
-    if (!this.config.tools?.agentBrowserControl) return;
+    if (!enabled) return;
     if ((this.config.tools?.disabledTools ?? []).includes("browser_control")) return;
     this.toolRegistry.register(new BrowserControlTool(controller, release));
   }
@@ -32758,6 +32813,20 @@ function applySettingsPayload(config, data) {
     if (data.webSearch.tavilyApiKey) next.tavilyApiKey = data.webSearch.tavilyApiKey;
     config.tools.webSearch = next;
   }
+  if (data.remoteBrowser && typeof data.remoteBrowser === "object") {
+    const prior = config.tools.remoteBrowser ?? {};
+    const next = { ...prior };
+    if (data.remoteBrowser.provider === "cdp" || data.remoteBrowser.provider === "steel") {
+      next.provider = data.remoteBrowser.provider;
+    }
+    if (typeof data.remoteBrowser.url === "string") next.url = data.remoteBrowser.url.trim() || void 0;
+    if (data.remoteBrowser.apiKey) next.apiKey = data.remoteBrowser.apiKey;
+    const n = data.remoteBrowser.maxSessions;
+    if (typeof n === "number" && Number.isFinite(n)) {
+      next.maxSessions = Math.min(Math.max(Math.floor(n), 1), 16);
+    }
+    config.tools.remoteBrowser = next;
+  }
   if (data.advanced && typeof data.advanced === "object") {
     const a = data.advanced;
     const num = (v, min, max) => {
@@ -32804,6 +32873,7 @@ function settingsSnapshot(config) {
     if (p?.type && p?.baseUrl && p.type !== "azure") endpoints[p.type] = p.baseUrl;
   }
   const ws = config.tools?.webSearch ?? {};
+  const rb = config.tools?.remoteBrowser ?? {};
   return {
     models: config.models ?? {},
     budget: {
@@ -32833,6 +32903,15 @@ function settingsSnapshot(config) {
       hasBraveKey: typeof ws.braveApiKey === "string" && ws.braveApiKey.length > 0,
       hasTavilyKey: typeof ws.tavilyApiKey === "string" && ws.tavilyApiKey.length > 0
     },
+    // `hasApiKey`, never the key. The panel needs to show whether one is set;
+    // sending the value back would put a live credential in every settings
+    // response, where it reaches any client that can read them.
+    remoteBrowser: {
+      provider: rb.provider,
+      url: rb.url,
+      hasApiKey: typeof rb.apiKey === "string" && rb.apiKey.length > 0,
+      maxSessions: rb.maxSessions
+    },
     advanced: {
       autonomy: config.autonomy,
       planApproval: config.planApproval,
@@ -34943,6 +35022,1872 @@ async function discoverMcpTools(servers) {
   return results;
 }
 
+// src/browser/lease.ts
+var HUMAN_ACTOR = "__human__";
+var HUMAN_IDLE_MS = 12e4;
+var LEASE_DEADLOCK_CEILING_MS = 3e5;
+var QUEUE_WAIT_MS = 18e4;
+var MAX_QUEUED = 8;
+var ACTION_HANDOFF_MS = 2e3;
+var HANDBACK_RETRY_MS = 25;
+var BrowserLease = class {
+  actor = null;
+  session = null;
+  ceilingTimer = null;
+  waiting = [];
+  lifecycleWired = false;
+  /**
+   * The action holding the browser, if any.
+   *
+   * Needed alongside the lease for a reason the lease cannot cover: the lease
+   * is RE-ENTRANT for its holder — that is what makes a sequence a sequence —
+   * so nothing in it stops ONE actor running two actions at once. A retry
+   * racing the call it retried is exactly that shape.
+   *
+   * A symbol because it identifies the individual call: only the action that
+   * took the slot may release it.
+   */
+  action = null;
+  /** Whether the current action slot represents activity by its holder. */
+  actionCountsAsHumanActivity = false;
+  /**
+   * The human action that has already consumed its one idle-deadline grace.
+   * A single wedged CDP request must not look like fresh activity every two
+   * minutes forever. The first deadline may yield to an event that began before
+   * it; a second deadline for that SAME event becomes a pending lapse instead.
+   */
+  idleGraceAction = null;
+  /** Release the human hold as soon as this overlong action finally unwinds. */
+  idleLapseAfterAction = null;
+  /**
+   * Everyone waiting for that slot, IN THE ORDER THEY ASKED.
+   *
+   * A queue rather than a poll, and the ordering is the whole reason for it.
+   * `acquireActionSlot` used to spin on a 25ms timer, which decides nothing
+   * about who goes first: each waiter checks on its own phase, so the one that
+   * asked SECOND can find the slot free a full poll ahead of the one that asked
+   * first. The person types one event per keypress — `{ kind: 'text', text }`
+   * carries a single character — so that reordering is not a theoretical
+   * unfairness, it is "passowrd" appearing in the box.
+   *
+   * The slot is handed straight from `endAction` to the head of this line while
+   * still synchronous, so nothing can slip in between the two, and a waiter
+   * that reaches the front never has to be told the slot is already taken.
+   */
+  actionQueue = [];
+  /** Lapses a human hold nobody is using. See `HUMAN_IDLE_MS`. */
+  humanTimer = null;
+  /**
+   * The person ASKED for the hold to end and it could not end yet.
+   *
+   * Kept as a request rather than only a retry timer, because the retry shares
+   * `humanTimer` with the idle deadline: an authorised event settling after the
+   * request would otherwise call `touch()`, re-arm that timer for a full idle
+   * interval, and quietly cancel a handback the person had already asked for.
+   * "Give it back" is not undone by activity that was already under way when
+   * they said it.
+   *
+   * Explicit requests ONLY. An idle expiry must never set this: a deadline that
+   * lands on the person's own in-flight event is evidence they were THERE, and
+   * recording it here made `touch()` bail afterwards, so the hold dropped the
+   * instant a fresh interaction finished. See `lapse()`.
+   */
+  handBackWanted = false;
+  isRevoked;
+  onChange;
+  constructor(options = {}) {
+    this.isRevoked = options.isRevoked ?? (() => false);
+    this.onChange = options.onChange ?? (() => {
+    });
+  }
+  get holderActor() {
+    return this.actor;
+  }
+  /** Whether a person, rather than the agent, is driving the page right now. */
+  get heldByHuman() {
+    return this.actor === HUMAN_ACTOR;
+  }
+  /**
+   * Whether THIS actor is the one holding the browser right now.
+   *
+   * For asking again after a wait. `acquire` is re-entrant for the holder, so
+   * "I was granted the lease" is a fact about the moment it was granted and
+   * says nothing about the moment the caller finally gets to act.
+   */
+  heldBy(actorId) {
+    return this.actor === actorId;
+  }
+  get holderSession() {
+    return this.session;
+  }
+  get queueDepth() {
+    return this.waiting.length;
+  }
+  get actionInFlight() {
+    return this.action !== null;
+  }
+  /**
+   * Declare that this host reports worker terminal states.
+   *
+   * When it does, timers stop being ownership boundaries entirely. When it does
+   * not — an embedder that wired a controller but not the release — the
+   * fallbacks stay, because something has to break a deadlock.
+   */
+  setLifecycleReleaseWired(on) {
+    this.lifecycleWired = on;
+  }
+  /**
+   * Take the browser for this actor, waiting in line if someone else holds it.
+   *
+   * Re-entrant for the actor that already holds it: that is the sequence case —
+   * the same worker coming back for its next step must not queue behind itself.
+   */
+  async acquire(actorId, sessionId, signal) {
+    if (this.actor === HUMAN_ACTOR && actorId !== HUMAN_ACTOR) return "human";
+    if (this.actor === null || this.actor === actorId) {
+      this.actor = actorId;
+      this.session = sessionId;
+      this.armCeiling();
+      return "granted";
+    }
+    if (this.waiting.length >= MAX_QUEUED) return "busy";
+    return this.enqueue(actorId, sessionId, signal);
+  }
+  /**
+   * One worker has finished its whole sequence, so its hold ends.
+   *
+   * THIS is the semantic release. It comes from the worker's own terminal path,
+   * so it means "this actor will never ask again" — which a timer can never
+   * mean about a worker that is merely thinking.
+   *
+   * Idempotent, and safe for an actor that never touched the browser.
+   */
+  actorEnded(actorId) {
+    if (!actorId) return;
+    for (let i = this.waiting.length - 1; i >= 0; i--) {
+      const w = this.waiting[i];
+      if (w.actorId === actorId) w.settle("cancelled");
+    }
+    this.releaseIfHeldBy(actorId);
+    this.onChange();
+  }
+  /**
+   * Give the browser up when about to return without using it.
+   *
+   * Two guards, both load-bearing. Never while an action is in flight, because
+   * the lease is RE-ENTRANT: the action still running may be this same actor's
+   * previous step, and taking the lease off it hands the page to a queued
+   * worker mid-sequence. And only while still the holder, because by the time a
+   * refusal path runs a Stop may already have handed the lease on.
+   */
+  releaseIfHeldBy(actorId) {
+    if (this.action) return;
+    if (this.actor === actorId) this.release();
+  }
+  /**
+   * Give the browser to the person watching it.
+   *
+   * Callers must have waited the in-flight action out first — see
+   * `acquireActionSlot`. This does not interrupt one, because it cannot: a
+   * Playwright call already inside the page finishes whatever it started, and
+   * taking the lease off it would only mean the person and a still-running
+   * `fill` were both touching the same form. Waiting is what makes "you have
+   * control" true when the UI says it.
+   *
+   * Every queued worker is turned away rather than left in line, for the same
+   * reason `acquire` refuses: they were planned against a page the person is
+   * about to change.
+   */
+  takeOver(sessionId) {
+    for (let i = this.waiting.length - 1; i >= 0; i--) this.waiting[i].settle("human");
+    this.clearCeiling();
+    this.actor = HUMAN_ACTOR;
+    this.session = sessionId;
+    this.touch();
+    this.onChange();
+  }
+  /**
+   * The person is still there — anything they did counts.
+   *
+   * Called per authorised input rather than on a heartbeat, so the hold is
+   * extended by USE and not merely by a tab being open. A left-open panel on a
+   * forgotten laptop stops holding a billed session two minutes later.
+   */
+  touch() {
+    if (this.actor !== HUMAN_ACTOR) return;
+    if (this.handBackWanted) return;
+    this.armIdle();
+  }
+  /** (Re)start the idle interval. The only place the deadline is set. */
+  armIdle() {
+    this.clearHumanIdle();
+    this.humanTimer = setTimeout(() => {
+      this.lapse();
+    }, HUMAN_IDLE_MS);
+    this.humanTimer.unref?.();
+  }
+  /**
+   * The idle deadline came round.
+   *
+   * Both ways a hold ends obey the same rule — never while one of the person's
+   * own events is still landing — but they resolve that clash in OPPOSITE
+   * directions, and routing the lapse through `handBack()` collapsed them into
+   * one. An event in flight BEGAN before this deadline, which makes it evidence
+   * the person was there; deferring the lapse and then releasing the moment
+   * that event lands ends the hold immediately after a fresh interaction, which
+   * is the precise opposite of what an idle deadline measures. So an
+   * interrupted lapse yields: the interval starts again, and the next silence
+   * decides.
+   *
+   * `handBack()` keeps the deferral instead, because "Give it back" is a
+   * decision and activity already under way when it was made does not withdraw
+   * it. Same rule, different answer, which is why they are different methods.
+   */
+  lapse() {
+    if (this.actor !== HUMAN_ACTOR) return;
+    if (this.action && this.actionCountsAsHumanActivity) {
+      if (this.idleGraceAction !== this.action) {
+        this.idleGraceAction = this.action;
+        this.armIdle();
+      } else {
+        this.idleLapseAfterAction = this.action;
+        this.clearHumanIdle();
+      }
+      return;
+    }
+    this.release();
+  }
+  /**
+   * The person hands the browser back, or their hold lapses.
+   *
+   * Answers whether there was a human hold to end, so a caller can tell a real
+   * handback from a duplicate click or a lapse that already happened.
+   */
+  handBack() {
+    if (this.actor !== HUMAN_ACTOR) return false;
+    if (this.action) {
+      this.handBackWanted = true;
+      this.clearHumanIdle();
+      this.humanTimer = setTimeout(() => {
+        this.handBack();
+      }, HANDBACK_RETRY_MS);
+      this.humanTimer.unref?.();
+      return false;
+    }
+    this.release();
+    return true;
+  }
+  clearHumanIdle() {
+    if (this.humanTimer) {
+      clearTimeout(this.humanTimer);
+      this.humanTimer = null;
+    }
+  }
+  /** Drop every queued waiter belonging to a run, and the lease if it holds it. */
+  dropRun(sessionId) {
+    for (let i = this.waiting.length - 1; i >= 0; i--) {
+      const w = this.waiting[i];
+      if (w.sessionId === sessionId) w.settle("cancelled");
+    }
+    if (this.session === sessionId) this.release();
+  }
+  /** Turn everyone away — the capability itself has gone. */
+  dropAll() {
+    for (let i = this.waiting.length - 1; i >= 0; i--) this.waiting[i].settle("off");
+  }
+  /** Hand the browser to the next actor in line, if any. */
+  release() {
+    this.clearCeiling();
+    this.clearHumanIdle();
+    this.handBackWanted = false;
+    this.idleGraceAction = null;
+    this.idleLapseAfterAction = null;
+    this.actor = null;
+    this.session = null;
+    let next = this.waiting.shift();
+    while (next && this.isRevoked(next.sessionId)) {
+      next.settle("cancelled");
+      next = this.waiting.shift();
+    }
+    if (next) {
+      this.actor = next.actorId;
+      this.session = next.sessionId;
+      this.armCeiling();
+      next.settle("granted");
+    }
+    this.onChange();
+  }
+  /** Arm the deadlock ceiling. Not a release schedule — see the constant. */
+  armCeiling() {
+    this.clearCeiling();
+    if (this.lifecycleWired) return;
+    this.ceilingTimer = setTimeout(() => this.release(), LEASE_DEADLOCK_CEILING_MS);
+    this.ceilingTimer.unref?.();
+  }
+  clearCeiling() {
+    if (this.ceilingTimer) {
+      clearTimeout(this.ceilingTimer);
+      this.ceilingTimer = null;
+    }
+  }
+  /**
+   * Take the per-action slot, or null when one is already running.
+   *
+   * PRIVATE, so the queue is the only way in. A caller that could take the slot
+   * without joining the line would be exactly the jump-the-queue the ordering
+   * is there to prevent.
+   */
+  beginAction(countsAsHumanActivity = true) {
+    if (this.action) return null;
+    const token = /* @__PURE__ */ Symbol("browser-action");
+    this.action = token;
+    this.actionCountsAsHumanActivity = countsAsHumanActivity;
+    return token;
+  }
+  /**
+   * Release the slot, but only for the action that took it.
+   *
+   * Hands it to the head of the line rather than merely clearing it, and does
+   * so SYNCHRONOUSLY: the waiter's `beginAction` runs before this call returns,
+   * so there is no window in which the slot is free and somebody who asked
+   * later can take it.
+   */
+  endAction(token) {
+    if (this.action !== token) return false;
+    const lapseNow = this.actor === HUMAN_ACTOR && this.idleLapseAfterAction === token;
+    this.action = null;
+    this.actionCountsAsHumanActivity = false;
+    if (this.idleGraceAction === token) this.idleGraceAction = null;
+    if (this.idleLapseAfterAction === token) this.idleLapseAfterAction = null;
+    if (lapseNow) this.release();
+    this.actionQueue.shift()?.();
+    return true;
+  }
+  /**
+   * Take the slot only if it is free RIGHT NOW, never joining the line.
+   *
+   * For input that is a SAMPLE rather than a decision — pointer movement. A
+   * click or a keystroke is a thing the person meant to do and has to happen,
+   * so it waits its turn; a pointer position is one of many on the way
+   * somewhere, and one that cannot be applied now is worth less than the one
+   * behind it. Queueing them is actively harmful: on an endpoint slower than
+   * the client's sampling interval the backlog grows, and the click behind it
+   * can age out against `acquireActionSlot`'s bound and be refused — movement
+   * costing the person the action they actually intended.
+   *
+   * The queue length is checked as well as the slot, so a sample cannot step
+   * over a click that is already waiting.
+   */
+  tryActionSlot() {
+    if (this.action || this.actionQueue.length > 0) return null;
+    return this.beginAction();
+  }
+  /**
+   * Take the per-action slot, waiting in line for it if somebody has it.
+   *
+   * A release can hand the browser on while the previous holder's abort is
+   * still propagating through an awaited navigation. That is a handoff, not a
+   * conflict, so it is normally bounded: a wedged action must not pin an agent
+   * or a takeover forever. Human discrete input is the exception and passes
+   * `null`: once a click, key or committed text has been accepted into this
+   * ordered queue, expiring it merely because earlier accepted input took more
+   * than two seconds silently truncates what the person typed.
+   *
+   * Waiting and TAKING are one step, which they deliberately were not before:
+   * the wait used to answer "the slot looks free" and leave the caller to call
+   * `beginAction` afterwards. Two callers woken by the same release both saw it
+   * free, and the loser was told "another action is already running" — a
+   * refusal for having asked first. Granting it here means whoever reaches the
+   * front of the line gets it, and everybody else is still waiting rather than
+   * refused.
+   *
+   * `null` as a RESULT means a bounded wait ran out OR a caller-supplied queue
+   * cap refused a new waiter. `null` as `withinMs` means an ACCEPTED operation
+   * is intentionally unbounded by time and will leave the queue only when its
+   * turn arrives; it does not require accepting infinitely many operations.
+   * `countsAsHumanActivity=false` is for
+   * lifecycle barriers: they still serialize, but an idle deadline must not
+   * mistake framework cleanup for evidence that the person is present.
+   */
+  async acquireActionSlot(withinMs = ACTION_HANDOFF_MS, countsAsHumanActivity = true, maxQueued = null) {
+    if (!this.action && this.actionQueue.length === 0) {
+      return this.beginAction(countsAsHumanActivity);
+    }
+    if (maxQueued !== null && this.actionQueue.length >= maxQueued) return null;
+    return await new Promise((resolve2) => {
+      let done = false;
+      let timer;
+      const wake = () => {
+        if (done) return;
+        done = true;
+        if (timer) clearTimeout(timer);
+        resolve2(this.beginAction(countsAsHumanActivity));
+      };
+      if (withinMs !== null) {
+        timer = setTimeout(() => {
+          if (done) return;
+          done = true;
+          const i = this.actionQueue.indexOf(wake);
+          if (i >= 0) this.actionQueue.splice(i, 1);
+          resolve2(null);
+        }, withinMs);
+        timer.unref?.();
+      }
+      this.actionQueue.push(wake);
+    });
+  }
+  /**
+   * Queue one actor, resolving when it gets the browser or is turned away.
+   *
+   * `settle` is wrapped so it runs at most once and always takes the waiter out
+   * of the line: the timeout, an abort and a handoff all race, and settling
+   * twice would silently leave a dead entry holding a queue slot.
+   */
+  enqueue(actorId, sessionId, signal) {
+    return new Promise((resolve2) => {
+      let done = false;
+      const waiter = {
+        actorId,
+        sessionId,
+        settle: (result) => {
+          if (done) return;
+          done = true;
+          clearTimeout(timer);
+          signal?.removeEventListener("abort", giveUp);
+          const i = this.waiting.indexOf(waiter);
+          if (i >= 0) this.waiting.splice(i, 1);
+          resolve2(result);
+        }
+      };
+      const timer = this.lifecycleWired ? void 0 : setTimeout(() => waiter.settle("busy"), QUEUE_WAIT_MS);
+      timer?.unref?.();
+      const giveUp = () => waiter.settle("cancelled");
+      signal?.addEventListener("abort", giveUp, { once: true });
+      this.waiting.push(waiter);
+    });
+  }
+};
+
+// src/browser/remote/controller.ts
+var KEYS = {
+  Enter: { code: 13, text: "\r" },
+  Tab: { code: 9 },
+  Backspace: { code: 8 },
+  Delete: { code: 46 },
+  Escape: { code: 27 },
+  ArrowUp: { code: 38 },
+  ArrowDown: { code: 40 },
+  ArrowLeft: { code: 37 },
+  ArrowRight: { code: 39 },
+  Home: { code: 36 },
+  End: { code: 35 },
+  PageUp: { code: 33 },
+  PageDown: { code: 34 }
+};
+var BUTTONS = { left: 1, middle: 4, right: 2 };
+var SCREENCAST = { format: "jpeg", quality: 60, maxWidth: 1280, maxHeight: 800 };
+var ACTION_TIMEOUT_MS = 3e4;
+var RESTORE_FRAME_MS = 2e3;
+var MAX_HUMAN_INPUT_QUEUE = 64;
+var MAX_CAPTURE_TRANSITION_QUEUE = 16;
+var MAX_WATCH_LIFECYCLE_QUEUE = 16;
+var RemoteBrowserController = class {
+  provider;
+  maxSessions;
+  /**
+   * Live-view listeners, one per run.
+   *
+   * A single callback was fine while each run had its own controller. Now the
+   * controller is shared across a deployment, so one callback would send run
+   * A's live-view URL to whichever run registered last — and that URL is a
+   * bearer capability for a browser somebody else is driving.
+   */
+  liveViewListeners = /* @__PURE__ */ new Map();
+  /**
+   * Told when a run's browser changes hands, or stops being pictured.
+   *
+   * Needed because a takeover can end without anybody asking. The hold lapses
+   * on its own after `HUMAN_IDLE_MS`, and a client left believing it still has
+   * control would keep sending input into a lease it no longer holds — every
+   * event refused, with nothing on screen saying why.
+   */
+  controlListeners = /* @__PURE__ */ new Map();
+  /** What each run's listener was last told, so unchanged states stay quiet. */
+  controlAnnounced = /* @__PURE__ */ new Map();
+  /** An embedder that wants every run's live view, told which run each is. */
+  onLiveViewAll;
+  runs = /* @__PURE__ */ new Map();
+  /**
+   * Runs that have a pool slot but no browser yet.
+   *
+   * Counted alongside `runs` against the cap. Without it the limit was a
+   * check-then-act across four awaits, and simultaneous first uses both won.
+   */
+  opening = /* @__PURE__ */ new Map();
+  /**
+   * A run's stop signal, created when its slot is reserved.
+   *
+   * Before this, Stop looked only in `runs` — so during the first `open()`,
+   * while the run existed only in `opening` and four awaits were in flight, it
+   * found nothing and returned. The open then completed, built a FRESH
+   * unaborted controller, and the click the user had stopped went ahead. The
+   * signal has to exist before the browser does.
+   */
+  aborts = /* @__PURE__ */ new Map();
+  /**
+   * Runs whose provider session is being released right now.
+   *
+   * `stopRun`, `endRun`, `releaseIfIdle`, and the stale-page branch of `open`
+   * all delete a run from `runs` synchronously and only THEN await
+   * `disposeRun` settling — the browser disconnect, and `provider.endSession`,
+   * which for Steel is a real HTTP `/release` call. Between that delete and
+   * the call actually finishing, the admission check in `open()` — which
+   * counts only `runs` and `opening` — saw the slot as free, so a second run
+   * could pass admission and call `createSession` before the first run's
+   * session was truly released. At `maxSessions: 1` that is two live, BILLED
+   * provider sessions at once, exactly what the pool exists to prevent.
+   * Counting this set alongside the other two closes the window.
+   *
+   * Keyed by run id, not a counter: every one of those four call sites checks
+   * the run is still IN `runs` before deleting it and starting teardown, and
+   * that delete is synchronous, so at most one teardown can ever be in flight
+   * for a given run id at a time — a second caller finds the entry already
+   * gone and never starts a competing one. The entry is removed only once its
+   * own teardown settles, so a later, genuine re-open of the same run id
+   * never collides with one still in flight.
+   */
+  closing = /* @__PURE__ */ new Map();
+  /** Runs the user has stopped, by run id — same meaning as on the desktop. */
+  revoked = /* @__PURE__ */ new Set();
+  /**
+   * One lease PER RUN, because there is one browser per run.
+   *
+   * The desktop has a single lease because it has a single browser. Here each
+   * run gets its own session, so a global lease would make run B queue behind
+   * run A for a browser it was never going to use — and with no queue timeout,
+   * queue for as long as A lasts. What limits runs against each other is the
+   * session POOL, not the lease.
+   */
+  leases = /* @__PURE__ */ new Map();
+  constructor(options) {
+    this.provider = options.provider;
+    const asked = Math.max(1, options.maxSessions ?? 1);
+    this.maxSessions = options.provider.isolatesSessions ? asked : 1;
+    this.onLiveViewAll = options.onLiveView;
+    this.ready = options.ready;
+  }
+  /**
+   * The predecessor's teardown, until it has been waited for once.
+   *
+   * Cleared as soon as it settles so the wait is not re-entered on every open
+   * — and so the promise itself is not retained for the life of the process.
+   */
+  ready;
+  /**
+   * This controller has been retired and will never open anything again.
+   *
+   * Stronger than "its runs were ended", and it has to be. A caller parked on
+   * the `ready` gate above is invisible to `dispose()` — it holds no run and
+   * has reserved no slot, because it has not got that far — so a SECOND
+   * settings change, arriving while the first retirement is still settling,
+   * found nothing to wait for and let the newest controller start immediately.
+   * The parked caller then woke up on a controller nobody holds a reference to
+   * and allocated a session against the superseded configuration, with the
+   * newest controller free to allocate its own.
+   *
+   * Set synchronously at the top of `dispose`, so anything already waiting is
+   * excluded the moment retirement begins rather than when it finishes.
+   */
+  retired = false;
+  leaseFor(runId) {
+    let lease = this.leases.get(runId);
+    if (!lease) {
+      lease = new BrowserLease({
+        isRevoked: (id) => this.revoked.has(id),
+        onChange: () => this.announceControl(runId)
+      });
+      lease.setLifecycleReleaseWired(true);
+      this.leases.set(runId, lease);
+    }
+    return lease;
+  }
+  /** The controller to hand to `Cascade.setBrowserController`. */
+  get controller() {
+    return (action, context) => this.act(action, context);
+  }
+  /** Watch one run's browser. The URL never goes to any other run's listener. */
+  onLiveViewFor(runKey, listener) {
+    this.liveViewListeners.set(runKey, listener);
+  }
+  offLiveViewFor(runKey) {
+    this.liveViewListeners.delete(runKey);
+  }
+  onControlFor(runKey, listener) {
+    this.controlListeners.set(runKey, listener);
+  }
+  offControlFor(runKey) {
+    this.controlListeners.delete(runKey);
+    this.controlAnnounced.delete(runKey);
+  }
+  /**
+   * Say who has the browser, but only when the answer has changed.
+   *
+   * The lease reports every ownership change, and during ordinary work that is
+   * one per action as workers take it and give it back. None of those are
+   * interesting to a viewer — the agent had it before and has it now — and
+   * emitting them would put a socket message on every click the agent makes.
+   */
+  announceControl(runId, force = false) {
+    const listener = this.controlListeners.get(runId);
+    if (!listener) return;
+    const held = this.runs.get(runId);
+    const state = {
+      human: this.leases.get(runId)?.heldByHuman === true,
+      capturing: held?.capturing === true,
+      // A receipt vouches for a VIEW, so it stops meaning anything the moment
+      // there is no view. `stopWatching` clears the session without bumping the
+      // watch — deliberately, since replacing the consumer is what a new watch
+      // is about — so the receipt stayed matched across the whole detach and
+      // re-attach, which `beginWatching` performs on every reconnect and every
+      // return to a conversation. Announced `confirmed` through that window,
+      // the client mounted and FOCUSED the blind keyboard surface over a page
+      // no session was serving: keystrokes meant for the composer went to a
+      // remote page that could only refuse them.
+      confirmed: held?.screencast !== void 0 && held.watchGen !== void 0 && held.seenGen === held.watchGen
+    };
+    const key = `${state.human}:${state.capturing}:${state.confirmed}`;
+    if (!force && this.controlAnnounced.get(runId) === key) return;
+    this.controlAnnounced.set(runId, key);
+    listener(state);
+  }
+  /**
+   * Tell a run's listener what its browser situation is.
+   *
+   * `active` is separate from the URL and both are needed: a provider with no
+   * live view is attached-but-unwatchable, and a finished run is not attached
+   * at all. Both have no URL, so a listener given only the URL cannot tell them
+   * apart — and would drop the Stop control for the first as if it were the
+   * second.
+   */
+  announceLiveView(runId, liveViewUrl, active) {
+    this.liveViewListeners.get(runId)?.({ active, ...liveViewUrl ? { liveViewUrl } : {} });
+    this.onLiveViewAll?.(runId, liveViewUrl);
+  }
+  /**
+   * Hand back a session the run turned out not to want.
+   *
+   * A browser opened for an action that is then refused would otherwise stay
+   * allocated and billed until the whole run ended, for a run that has just
+   * been stopped.
+   */
+  async releaseIfIdle(runId, releaseSlot) {
+    const held = this.runs.get(runId);
+    if (!held) {
+      releaseSlot?.();
+      return;
+    }
+    this.runs.delete(runId);
+    const teardown = this.teardown(runId, held);
+    releaseSlot?.();
+    await teardown;
+  }
+  /** Release every run's session. For when the deployment's config changes. */
+  async dispose() {
+    this.retired = true;
+    const opening = [...this.opening.values()];
+    const ids = /* @__PURE__ */ new Set([...this.runs.keys(), ...this.opening.keys()]);
+    await Promise.all([...ids].map((runId) => this.endRun(runId)));
+    await Promise.all(opening.map((open) => open.catch(() => {
+    })));
+    await Promise.all([...this.closing.values()].map((done) => done.catch(() => {
+    })));
+  }
+  /** A worker finished; it will never ask for the browser again. */
+  actorEnded(actorId) {
+    for (const lease of this.leases.values()) lease.actorEnded(actorId);
+  }
+  /**
+   * Start streaming this run's page to whoever is watching it.
+   *
+   * Nothing streams until someone asks. That is the whole reason this is a
+   * method rather than something `open()` does: an unwatched run would
+   * otherwise pay to encode frames nobody sees, on every run, forever — and on
+   * a metered provider it would pay for the bandwidth too.
+   *
+   * Frames are ACKED after they are handed on, never before. Chrome sends the
+   * next frame only once the previous is acknowledged, so this bounds it to one
+   * outstanding frame against OUR OWN handling. It does not reach further than
+   * that, and an earlier version of this comment claimed it did: `onFrame` ends
+   * at a socket emit, which hands the JPEG to a transport rather than to a
+   * viewer, so the ack says nothing about what the person actually received.
+   * Bounding the rest of the path is the transport's job — see `emitFrame`,
+   * where frames go out lossy so a slow connection drops pictures instead of
+   * banking stale ones. Dropping the ack stops the stream dead, which is why it
+   * is best-effort but unconditional.
+   *
+   * Returns false when there is nothing to watch — the run has no browser, or
+   * it is already being watched. Callers use that to avoid promising a viewer
+   * a stream that will never arrive.
+   */
+  async startWatching(runId, onFrame) {
+    const held = this.runs.get(runId);
+    if (!held) return false;
+    return await this.queueWatch(held, async () => {
+      held.onFrame = onFrame;
+      held.watchGen = (held.watchGen ?? 0) + 1;
+      if (held.screencast) {
+        this.announceControl(runId);
+        return true;
+      }
+      const attached = await this.attachScreencast(runId, held, onFrame);
+      if (!attached && held.onFrame === onFrame) held.onFrame = void 0;
+      return attached !== null;
+    });
+  }
+  /**
+   * Run one watch or unwatch after every one already asked for.
+   *
+   * The chain is kept non-rejecting on purpose: a failed attach must not poison
+   * every later request for this run, which is what a bare `.then` chain would
+   * do. The caller still sees its own failure, because that is the promise
+   * returned rather than the one stored.
+   */
+  queueWatch(held, op) {
+    const depth = held.watchQueueDepth ?? 0;
+    if (held.watchCollapsedPromise || depth >= MAX_WATCH_LIFECYCLE_QUEUE) {
+      held.watchCollapsed = op;
+      if (!held.watchCollapsedPromise) {
+        const drain = async () => {
+          let result;
+          while (held.watchCollapsed) {
+            const latest = held.watchCollapsed;
+            held.watchCollapsed = void 0;
+            try {
+              result = await latest();
+            } catch {
+            }
+          }
+          return result;
+        };
+        const tail = (held.watchQueue ?? Promise.resolve()).then(drain, drain);
+        let tracked;
+        tracked = tail.finally(() => {
+          if (held.watchCollapsedPromise === tracked) {
+            held.watchCollapsedPromise = void 0;
+            held.watchCollapsed = void 0;
+          }
+        });
+        held.watchCollapsedPromise = tracked;
+        held.watchQueue = tracked.catch(() => {
+        });
+      }
+      return held.watchCollapsedPromise;
+    }
+    held.watchQueueDepth = depth + 1;
+    const mine = (held.watchQueue ?? Promise.resolve()).then(op, op);
+    const counted = mine.finally(() => {
+      held.watchQueueDepth = Math.max(0, (held.watchQueueDepth ?? 1) - 1);
+    });
+    held.watchQueue = counted.catch(() => {
+    });
+    return counted;
+  }
+  /**
+   * Attach at most one physical CDP screencast session at a time.
+   *
+   * `startWatching()` already serializes watcher lifecycle through `watchQueue`,
+   * but the agent's detached-hidden restore cannot join that queue: it holds the
+   * action slot, while an earlier unwatch may be waiting for exactly that slot.
+   * Sharing only the physical attach closes the two-session race without making
+   * watcher teardown and agent mutation wait on each other in a cycle.
+   *
+   * A real watcher claims `onFrame` immediately, before it waits for an attach
+   * already started by the agent. The lower-level attach never writes the sink,
+   * so finishing an older temporary attempt cannot overwrite a newer viewer.
+   */
+  async attachScreencast(runId, held, onFrame, popupDetachGen) {
+    const consumerIntent = onFrame && popupDetachGen !== void 0 ? popupDetachGen : void 0;
+    if (onFrame) held.onFrame = onFrame;
+    if (held.screencast && held.screencastPage === held.page) return held.screencast;
+    const targetPage = held.page;
+    const existing = held.attaching;
+    if (existing) {
+      const existingPage = held.attachingPage;
+      await existing.catch(() => null);
+      if (held.page !== targetPage || existingPage !== targetPage) {
+        return this.attachScreencast(runId, held, onFrame, popupDetachGen);
+      }
+      const cdp = held.screencastPage === targetPage ? held.screencast ?? null : null;
+      if (consumerIntent !== void 0 && (held.watchDetachGen ?? 0) !== consumerIntent) return null;
+      if (cdp && onFrame) held.onFrame = onFrame;
+      return cdp;
+    }
+    if (held.screencast && held.screencastPage !== targetPage) {
+      const stale = held.screencast;
+      held.screencast = void 0;
+      held.screencastPage = void 0;
+      await stale.send("Page.stopScreencast").catch(() => {
+      });
+      await stale.detach().catch(() => {
+      });
+    }
+    const attempt = this.attachScreencastFresh(runId, held, targetPage, consumerIntent);
+    held.attaching = attempt;
+    held.attachingPage = targetPage;
+    try {
+      const cdp = await attempt;
+      if (consumerIntent !== void 0 && (held.watchDetachGen ?? 0) !== consumerIntent) return null;
+      if (cdp && onFrame) held.onFrame = onFrame;
+      return cdp;
+    } finally {
+      if (held.attaching === attempt) {
+        held.attaching = void 0;
+        held.attachingPage = void 0;
+      }
+    }
+  }
+  /** Open one new CDP session and start the stream when it is safe to do so. */
+  async attachScreencastFresh(runId, held, targetPage, consumerIntent) {
+    const safetyGate = held.hiddenByHolder === true || held.visibilityUnconfirmed === true;
+    let cdp;
+    try {
+      cdp = await targetPage.context().newCDPSession(targetPage);
+    } catch {
+      if (!safetyGate) {
+        held.visibilityUnconfirmed = false;
+        held.capturing = true;
+        this.announceControl(runId);
+      }
+      return null;
+    }
+    if (held.page !== targetPage) {
+      await cdp.detach().catch(() => {
+      });
+      return null;
+    }
+    cdp.on("Page.screencastFrame", ((e) => {
+      if (held.page === targetPage && typeof e?.data === "string") {
+        const width = e.metadata?.deviceWidth ?? 0;
+        const height = e.metadata?.deviceHeight ?? 0;
+        held.metricsStale = true;
+        if (held.visibilityUnconfirmed) {
+          held.visibilityUnconfirmed = false;
+          if (held.capturing !== true) {
+            held.capturing = true;
+            this.announceControl(runId);
+          }
+        }
+        const ping = held.framePing;
+        held.framePing = void 0;
+        ping?.();
+        const deliver = held.onFrame;
+        if (deliver) {
+          deliver({ data: e.data, width, height, generation: held.watchGen ?? 0 });
+        }
+      }
+      void cdp.send("Page.screencastFrameAck", { sessionId: e?.sessionId }).catch(() => {
+      });
+    }));
+    const paused = held.hiddenByHolder === true;
+    if (!paused) {
+      try {
+        await cdp.send("Page.startScreencast", { ...SCREENCAST });
+      } catch {
+        if (!safetyGate) {
+          held.visibilityUnconfirmed = false;
+          held.capturing = true;
+          this.announceControl(runId);
+        } else {
+          held.capturing = false;
+          this.announceControl(runId);
+        }
+        await cdp.detach().catch(() => {
+        });
+        return null;
+      }
+    }
+    if (held.page !== targetPage) {
+      if (!paused) await cdp.send("Page.stopScreencast").catch(() => {
+      });
+      await cdp.detach().catch(() => {
+      });
+      return null;
+    }
+    if (consumerIntent !== void 0 && (held.watchDetachGen ?? 0) !== consumerIntent) {
+      if (!paused) await cdp.send("Page.stopScreencast").catch(() => {
+      });
+      await cdp.detach().catch(() => {
+      });
+      return null;
+    }
+    held.screencast = cdp;
+    held.screencastPage = targetPage;
+    held.capturing = !paused;
+    held.hiddenByHolder = paused;
+    this.announceControl(runId);
+    return cdp;
+  }
+  /** Nobody is watching any more: stop paying to render frames. */
+  async stopWatching(runId) {
+    const held = this.runs.get(runId);
+    if (!held) return;
+    held.watchDetachGen = (held.watchDetachGen ?? 0) + 1;
+    held.onFrame = void 0;
+    await this.queueWatch(held, async () => {
+      const cdp = held.screencast;
+      held.onFrame = void 0;
+      if (!cdp) return;
+      held.screencast = void 0;
+      held.screencastPage = void 0;
+      held.capturing = false;
+      this.announceControl(runId);
+      const lease = this.leases.get(runId);
+      const token = lease ? await lease.acquireActionSlot(null, false) : null;
+      if (lease && !token) return;
+      try {
+        await cdp.send("Page.stopScreencast").catch(() => {
+        });
+        await cdp.detach().catch(() => {
+        });
+      } finally {
+        if (token && lease) lease.endAction(token);
+      }
+    });
+  }
+  /**
+   * Suspend or resume the picture without giving up control.
+   *
+   * The credential case, and the only reason this is separate from watching. A
+   * person who has taken the page over to sign in is about to type a password
+   * into a field whose contents are echoed as dots — but a password manager's
+   * dropdown, a "show password" toggle, a one-time code in plain text and the
+   * confirmation page afterwards are not, and all of them would otherwise be
+   * encoded into frames and sent across the network.
+   *
+   * What this does NOT do is hide anything from the agent: it stops the
+   * picture, not the page. Nothing about a suspended capture would stop a
+   * `extract_text` from reading the same screen — it is the lease that stops
+   * that, by refusing the agent for as long as the person holds it.
+   *
+   * Answers whether frames are flowing afterwards, which is what a UI needs to
+   * show and is not always what was asked for: a run with nobody watching has
+   * no session to suspend.
+   */
+  async setCapture(runId, on) {
+    const held = this.runs.get(runId);
+    const cdp = held?.screencast;
+    const watch = held?.watchGen;
+    if (!held || !cdp) return false;
+    const lease = this.leaseFor(runId);
+    if (!on && !lease.heldByHuman) return held.capturing === true;
+    if (!on && (watch === void 0 || held.seenGen !== watch)) {
+      return held.capturing === true;
+    }
+    if (held.capturing === on) {
+      if (lease.heldByHuman) lease.touch();
+      return on;
+    }
+    const token = await lease.acquireActionSlot(null, true, MAX_CAPTURE_TRANSITION_QUEUE);
+    if (!token) return held.capturing === true;
+    try {
+      if (!on && !lease.heldByHuman) return held.capturing === true;
+      if (!on && (held.screencast !== cdp || held.watchGen !== watch)) {
+        return held.capturing === true;
+      }
+      if (!on && (watch === void 0 || held.seenGen !== watch)) {
+        return held.capturing === true;
+      }
+      const target = on ? held.screencast : cdp;
+      if (!target) {
+        if (on) {
+          held.hiddenByHolder = false;
+          if (lease.heldByHuman) lease.touch();
+        }
+        return held.capturing === true;
+      }
+      const now = await this.applyCapture(runId, held, target, on);
+      if (lease.heldByHuman) lease.touch();
+      return now;
+    } finally {
+      lease.endAction(token);
+    }
+  }
+  /**
+   * The capture transition itself, with no lease bookkeeping.
+   *
+   * Separate because the agent's restore in `act()` already holds the action
+   * slot — taking it again there would deadlock against itself, and the whole
+   * point of that call site is that it happens INSIDE the agent's turn.
+   *
+   * `confirmWithFrame` is used only by the agent's visibility gate. There, a
+   * successful CDP command is not enough: the externally visible state remains
+   * paused until a frame arrives, and the frame handler is the only code that
+   * promotes it to capturing. This makes a restore timeout sticky rather than
+   * a one-action refusal.
+   */
+  async applyCapture(runId, held, cdp, on, confirmWithFrame = false) {
+    if (held.capturing === on && !(on && confirmWithFrame && held.visibilityUnconfirmed)) return on;
+    const wasUnconfirmed = held.visibilityUnconfirmed === true;
+    const wasCapturing = held.capturing === true;
+    if (on) held.visibilityUnconfirmed = true;
+    try {
+      if (on) await cdp.send("Page.startScreencast", { ...SCREENCAST });
+      else await cdp.send("Page.stopScreencast");
+      if (on) {
+        if (!confirmWithFrame) held.capturing = true;
+      } else {
+        held.visibilityUnconfirmed = false;
+        held.capturing = false;
+      }
+      held.hiddenByHolder = !on;
+      this.announceControl(runId);
+    } catch {
+      if (on) {
+        held.visibilityUnconfirmed = wasUnconfirmed;
+        held.capturing = wasCapturing;
+        this.announceControl(runId);
+      }
+      return held.capturing === true && !held.visibilityUnconfirmed;
+    }
+    return on;
+  }
+  /**
+   * Wait, briefly, for Chrome to produce a frame.
+   *
+   * `Page.startScreencast` resolves when the command is accepted, which is not
+   * when a picture exists. The agent's visibility gate — "the page must be
+   * VISIBLE before anything changes it" — was therefore satisfied by a request
+   * rather than by a repaint, and the agent could click while the panel was
+   * still showing the page from before it was hidden, or nothing at all.
+   *
+   * A frame rather than a client receipt, deliberately. A receipt would prove
+   * somebody SAW it, which is stronger — and would make the agent's progress
+   * depend on a viewer that may not exist: this path runs after a handback or a
+   * lapse, when there may be nobody watching at all, and an agent that stalls
+   * because a tab was closed is a worse failure than the one being fixed. What
+   * this does guarantee is ours to guarantee: the stream is producing again.
+   *
+   * Bounded, and the bound rests on the property rounds 14 and 15 already rely
+   * on — a screencast that has just been started emits its first frame at once,
+   * whatever the page is doing. If one does not arrive, the picture genuinely
+   * has not come back, and the caller refuses on the same trade it already
+   * makes when the restore itself fails.
+   */
+  nextFrame(held, withinMs = RESTORE_FRAME_MS) {
+    return new Promise((resolve2) => {
+      const timer = setTimeout(() => {
+        if (held.framePing === ping) held.framePing = void 0;
+        resolve2(false);
+      }, withinMs);
+      timer.unref?.();
+      const ping = () => {
+        clearTimeout(timer);
+        resolve2(true);
+      };
+      held.framePing = ping;
+    });
+  }
+  /** Whether a person is driving this run's browser right now. */
+  humanHolds(runId) {
+    return this.leases.get(runId)?.heldByHuman === true;
+  }
+  /**
+   * Hand this run's browser to the person watching it.
+   *
+   * The wait is the substance. An agent action already inside Playwright cannot
+   * be interrupted — `click` waits for its element to become actionable and
+   * then clicks, whatever anyone decided in the meantime — so a takeover that
+   * returned immediately would put the person on a page an action was still
+   * about to change. Bounded by the action ceiling, because that is the longest
+   * an action can legitimately take; past it something is wedged, and saying so
+   * is better than a spinner that never resolves.
+   *
+   * Idempotent for someone who already holds it: a second click of Take control
+   * just says they are still there.
+   */
+  async takeOver(runId) {
+    if (this.revoked.has(runId)) {
+      return { ok: false, detail: "Browser control was stopped for this run." };
+    }
+    const requested = this.runs.get(runId);
+    if (!requested) {
+      return { ok: false, detail: "This run has no browser open." };
+    }
+    const requestedCdp = requested.screencast;
+    const requestedWatch = requested.watchGen;
+    if (!requestedCdp || requestedWatch === void 0 || !requested.onFrame) {
+      return { ok: false, detail: "This browser is not being watched right now." };
+    }
+    const lease = this.leaseFor(runId);
+    if (lease.heldByHuman) {
+      lease.touch();
+      this.announceControl(runId, true);
+      return { ok: true };
+    }
+    const token = await lease.acquireActionSlot(ACTION_TIMEOUT_MS);
+    if (!token) {
+      return {
+        ok: false,
+        detail: "The agent is still finishing an action on this page. Try again in a moment."
+      };
+    }
+    try {
+      const held = this.runs.get(runId);
+      if (this.revoked.has(runId)) {
+        return { ok: false, detail: "Browser control was stopped for this run." };
+      }
+      if (!held || held.page.isClosed()) {
+        return { ok: false, detail: "That browser closed while you were waiting for it." };
+      }
+      if (held.screencast !== requestedCdp || held.watchGen !== requestedWatch || !held.onFrame) {
+        return { ok: false, detail: "The browser view changed while you were waiting. Take control again from the current view." };
+      }
+      lease.takeOver(runId);
+    } finally {
+      lease.endAction(token);
+    }
+    return { ok: true };
+  }
+  /** The person is done. Answers whether they were holding it at all. */
+  /**
+   * The viewer confirms it received a picture of this run's page.
+   *
+   * Reliable, one per watch, and the only thing that opens Hide. Checked
+   * against the CURRENT watch: a receipt that names an older one is from a
+   * viewer that has since been replaced, and vouching for its successor is the
+   * reconnect hole this counter exists to close.
+   */
+  frameSeen(runId, generation) {
+    const held = this.runs.get(runId);
+    if (!held) return;
+    if (typeof generation !== "number" || !Number.isFinite(generation)) return;
+    if (held.watchGen === void 0 || generation !== held.watchGen) return;
+    if (held.seenGen === generation) return;
+    held.seenGen = generation;
+    this.announceControl(runId);
+  }
+  handBack(runId) {
+    return this.leases.get(runId)?.handBack() === true;
+  }
+  /**
+   * One thing the person did to the page.
+   *
+   * Authorised per event, not per session. A takeover is not a channel that
+   * stays open once opened: between two clicks the run can be stopped, the hold
+   * can lapse, the page can close, and each of those has to stop the NEXT
+   * event rather than be noticed at the end. So every event re-checks that this
+   * run is live and that the lease is still the person's, and every accepted
+   * event says so by extending the hold.
+   */
+  async input(runId, event) {
+    const held = this.runs.get(runId);
+    const cdp = held?.screencast;
+    const watch = held?.watchGen;
+    if (!held || held.page.isClosed()) return { ok: false, detail: "This run has no browser open." };
+    const page2 = held.page;
+    const pageGeneration = held.generation;
+    if (!cdp) return { ok: false, detail: "Nothing is streaming this browser, so it cannot be driven." };
+    const lease = this.leaseFor(runId);
+    if (!lease.heldByHuman) {
+      return { ok: false, detail: "You do not have control of this browser. Take control first." };
+    }
+    if (held.capturing !== true && (held.watchGen === void 0 || held.seenGen !== held.watchGen)) {
+      return { ok: false, detail: "Show the page before typing into it \u2014 this view has not seen it yet." };
+    }
+    const sampled = event.kind === "move";
+    const token = sampled ? lease.tryActionSlot() : await lease.acquireActionSlot(null, true, MAX_HUMAN_INPUT_QUEUE);
+    if (!token) {
+      if (sampled) return { ok: true };
+      return { ok: false, detail: "Too many browser inputs are already waiting. Let the page catch up, then try again." };
+    }
+    try {
+      if (!lease.heldByHuman) {
+        return { ok: false, detail: "Your control of this browser ended while that was waiting." };
+      }
+      if (held.page !== page2 || held.generation !== pageGeneration) {
+        return { ok: false, detail: "The page changed while that input was waiting, so it did not land." };
+      }
+      if (held.screencast !== cdp || held.watchGen !== watch) {
+        return { ok: false, detail: "The view you were driving is gone, so that did not land." };
+      }
+      const pagesBefore = new Set(held.page.context().pages());
+      await this.dispatch(cdp, held, event);
+      await this.followOpenedPage(runId, held, pagesBefore);
+    } catch (err) {
+      return { ok: false, detail: err instanceof Error ? err.message : String(err) };
+    } finally {
+      lease.endAction(token);
+    }
+    lease.touch();
+    return { ok: true };
+  }
+  /**
+   * The page's own coordinate space, measured rather than inferred.
+   *
+   * Cached, because a click should not cost a round trip, and invalidated by
+   * the frame metadata changing shape — which arrives free with every frame. A
+   * failed measurement falls back to the last good one rather than to a guess:
+   * a stale viewport is off by a resize, an invented one is off by anything.
+   */
+  async pageViewport(held, cdp) {
+    if (held.viewport && !held.metricsStale) return held.viewport;
+    try {
+      const metrics = await cdp.send("Page.getLayoutMetrics");
+      const width = metrics?.cssVisualViewport?.clientWidth;
+      const height = metrics?.cssVisualViewport?.clientHeight;
+      if (typeof width === "number" && typeof height === "number" && width > 0 && height > 0) {
+        held.viewport = { width, height };
+        held.metricsStale = false;
+        return held.viewport;
+      }
+    } catch {
+    }
+    return null;
+  }
+  /**
+   * Turn one authorised event into CDP calls. Coordinates arrive normalised.
+   *
+   * A switch with a default that REFUSES, rather than a chain of ifs ending in
+   * the click branch. This is a mutation boundary reached from a socket, so the
+   * question is not what a well-formed event does but what a malformed one
+   * does: the chain answered "clicks", which meant a version-skewed client
+   * sending `{ kind: 'drag', x, y }` pressed the mouse on a real page, and a
+   * kind with no coordinates at all clamped to 0 and clicked the top-left
+   * corner. Unknown input has to fail closed.
+   *
+   * The `never` in the default is the other half: adding a member to
+   * `BrowserInput` without handling it here stops compiling, so the next kind
+   * cannot silently inherit whatever the last branch happened to be.
+   */
+  async dispatch(cdp, held, event) {
+    switch (event.kind) {
+      case "text": {
+        if (typeof event.text !== "string") {
+          throw new Error("That is not text that can be typed into the page.");
+        }
+        const text = event.text.slice(0, 4e3);
+        if (!text) return;
+        await cdp.send("Input.insertText", { text });
+        return;
+      }
+      case "key": {
+        const modifiers = event.modifiers;
+        if (modifiers !== void 0) {
+          if (!Array.isArray(modifiers) || modifiers.some((m) => m !== "Control" && m !== "Meta" && m !== "Shift") || new Set(modifiers).size !== modifiers.length) {
+            throw new Error("That editing shortcut has invalid modifiers.");
+          }
+          const primary = modifiers.filter((m) => m === "Control" || m === "Meta");
+          const shifted = modifiers.includes("Shift");
+          if (primary.length !== 1) {
+            throw new Error("That editing shortcut cannot be sent to the page.");
+          }
+          const key = typeof event.key === "string" ? event.key : "";
+          const lower = key.toLowerCase();
+          const shortcut = lower === "a" && !shifted ? { key: "a", code: "KeyA", vk: 65 } : lower === "z" ? { key: "z", code: "KeyZ", vk: 90 } : lower === "y" && !shifted ? { key: "y", code: "KeyY", vk: 89 } : key === "Backspace" && !shifted ? { key: "Backspace", code: "Backspace", vk: 8 } : key === "Delete" && !shifted ? { key: "Delete", code: "Delete", vk: 46 } : void 0;
+          if (!shortcut) {
+            throw new Error(`That editing shortcut is not supported for the remote page: ${key}`);
+          }
+          const modifierBits = (primary[0] === "Control" ? 2 : 4) | (shifted ? 8 : 0);
+          const base2 = {
+            key: shortcut.key,
+            code: shortcut.code,
+            windowsVirtualKeyCode: shortcut.vk,
+            nativeVirtualKeyCode: shortcut.vk,
+            modifiers: modifierBits
+          };
+          await cdp.send("Input.dispatchKeyEvent", { ...base2, type: "rawKeyDown" });
+          await cdp.send("Input.dispatchKeyEvent", { ...base2, type: "keyUp" });
+          return;
+        }
+        const spec = typeof event.key === "string" && Object.hasOwn(KEYS, event.key) ? KEYS[event.key] : void 0;
+        if (!spec) throw new Error(`That key cannot be sent to the page: ${String(event.key)}`);
+        const base = {
+          key: event.key,
+          code: event.key,
+          windowsVirtualKeyCode: spec.code,
+          nativeVirtualKeyCode: spec.code,
+          ...spec.text ? { text: spec.text } : {}
+        };
+        await cdp.send("Input.dispatchKeyEvent", { ...base, type: spec.text ? "keyDown" : "rawKeyDown" });
+        await cdp.send("Input.dispatchKeyEvent", { ...base, type: "keyUp" });
+        return;
+      }
+      case "move":
+      case "scroll":
+      case "click": {
+        const view = await this.pageViewport(held, cdp);
+        if (!view) throw new Error("The page has not been measured yet, so a click cannot be placed on it.");
+        const x = coordinate(event.x, "horizontal position") * view.width;
+        const y = coordinate(event.y, "vertical position") * view.height;
+        if (event.kind === "move") {
+          await cdp.send("Input.dispatchMouseEvent", { type: "mouseMoved", x, y, button: "none", buttons: 0 });
+          return;
+        }
+        if (event.kind === "scroll") {
+          await cdp.send("Input.dispatchMouseEvent", {
+            type: "mouseWheel",
+            x,
+            y,
+            button: "none",
+            buttons: 0,
+            deltaX: 0,
+            deltaY: scrollDelta(event.deltaY)
+          });
+          return;
+        }
+        if (event.button !== void 0 && !Object.hasOwn(BUTTONS, event.button)) {
+          throw new Error(`That is not a mouse button: ${String(event.button)}`);
+        }
+        const button = event.button ?? "left";
+        const buttons = BUTTONS[button];
+        if (event.clicks !== void 0 && (typeof event.clicks !== "number" || !Number.isFinite(event.clicks))) {
+          throw new Error("That is not a number of clicks.");
+        }
+        const clickCount = Math.min(Math.max(Math.trunc(event.clicks ?? 1), 1), 3);
+        await cdp.send("Input.dispatchMouseEvent", { type: "mouseMoved", x, y, button: "none", buttons: 0 });
+        await cdp.send("Input.dispatchMouseEvent", { type: "mousePressed", x, y, button, buttons, clickCount });
+        await cdp.send("Input.dispatchMouseEvent", { type: "mouseReleased", x, y, button, buttons: 0, clickCount });
+        return;
+      }
+      default: {
+        const unknown = event;
+        throw new Error(`That is not something that can be done to the page: ${unknown?.kind ?? "an event with no kind"}`);
+      }
+    }
+  }
+  /** The user stopped this run. Refuses further actions and clears its queue. */
+  stopRun(runId) {
+    this.revoked.add(runId);
+    this.leases.get(runId)?.dropRun(runId);
+    this.aborts.get(runId)?.abort();
+    const held = this.runs.get(runId);
+    if (!held) return;
+    this.runs.delete(runId);
+    void this.teardown(runId, held);
+  }
+  /** A run ended: release its browser rather than pay for an idle session. */
+  async endRun(runId) {
+    this.leases.get(runId)?.dropRun(runId);
+    this.aborts.get(runId)?.abort();
+    const held = this.runs.get(runId);
+    if (!held) {
+      this.forgetRun(runId);
+      return;
+    }
+    this.runs.delete(runId);
+    await this.teardown(runId, held);
+    this.forgetRun(runId);
+  }
+  /** Forget a finished run entirely, so nothing accumulates per run. */
+  forgetRun(runId) {
+    this.revoked.delete(runId);
+    this.leases.delete(runId);
+    this.aborts.delete(runId);
+    this.liveViewListeners.delete(runId);
+    this.offControlFor(runId);
+  }
+  /**
+   * Let go of one run's browser.
+   *
+   * Best-effort throughout: a run is already over by the time this runs, and a
+   * provider that is briefly unreachable must not turn that into a failure the
+   * user sees. The provider's own idle timeout collects anything left.
+   */
+  async disposeRun(runId, held) {
+    held.abort.abort();
+    this.announceLiveView(runId, void 0, false);
+    await held.watchQueue?.catch(() => {
+    });
+    const watching = held.screencast;
+    held.screencast = void 0;
+    held.screencastPage = void 0;
+    if (watching) {
+      await watching.send("Page.stopScreencast").catch(() => {
+      });
+      await watching.detach().catch(() => {
+      });
+    }
+    await held.ownedContext?.close().catch(() => {
+    });
+    await held.browser.close().catch(() => {
+    });
+    await this.provider.endSession(held.session.id).catch(() => {
+    });
+  }
+  /**
+   * Run `disposeRun`, with the run id counted in `closing` until it settles.
+   *
+   * The caller adds the id to `closing` itself, synchronously, in the same
+   * breath as deleting the run from `runs` — see the field comment. This just
+   * guarantees the removal happens, success or failure, so a disposal that
+   * throws cannot leave the slot counted against the pool forever.
+   */
+  teardown(runId, held) {
+    const done = this.disposeRun(runId, held).finally(() => {
+      this.closing.delete(runId);
+    });
+    this.closing.set(runId, done);
+    return done;
+  }
+  async act(action, context) {
+    const runId = context.sessionId;
+    if (!runId) {
+      return { ok: false, detail: "This browser action arrived without a run identity, so it was not run." };
+    }
+    const actor = context.actorId || runId;
+    if (this.revoked.has(runId)) {
+      return { ok: false, detail: "The user stopped browser control for this run." };
+    }
+    if (context.signal?.aborted) {
+      return { ok: false, detail: "The run was cancelled." };
+    }
+    const plannedRun = this.runs.get(runId);
+    const planned = plannedRun?.generation ?? 0;
+    const recoveringClosedPage = plannedRun?.page.isClosed() === true;
+    const lease_ = this.leaseFor(runId);
+    const lease = await lease_.acquire(actor, runId, context.signal);
+    if (lease !== "granted") {
+      return { ok: false, detail: refusal(lease) };
+    }
+    if (this.revoked.has(runId)) {
+      lease_.releaseIfHeldBy(actor);
+      return { ok: false, detail: "The user stopped browser control for this run." };
+    }
+    if (context.signal?.aborted) {
+      lease_.releaseIfHeldBy(actor);
+      return { ok: false, detail: "The run was cancelled." };
+    }
+    const token = await lease_.acquireActionSlot();
+    if (!token) {
+      lease_.releaseIfHeldBy(actor);
+      return { ok: false, detail: "Another browser action is still finishing. Try again." };
+    }
+    if (!lease_.heldBy(actor)) {
+      lease_.endAction(token);
+      return { ok: false, detail: refusal(lease_.heldByHuman ? "human" : "off") };
+    }
+    let temporaryCapture;
+    try {
+      const held = await this.open(runId, context.signal);
+      if (this.revoked.has(runId)) {
+        await this.releaseIfIdle(runId, () => lease_.endAction(token));
+        return { ok: false, detail: "The user stopped browser control for this run." };
+      }
+      if (context.signal?.aborted || held.abort.signal.aborted) {
+        await this.releaseIfIdle(runId, () => lease_.endAction(token));
+        return { ok: false, detail: "The run was cancelled." };
+      }
+      if ((held.hiddenByHolder === true || held.visibilityUnconfirmed === true) && !held.screencast) {
+        const watchGen = held.watchGen;
+        let cdp = null;
+        try {
+          cdp = await this.attachScreencast(runId, held);
+        } catch {
+        }
+        if (!cdp) {
+          return {
+            ok: false,
+            detail: "The page could not be shown again, so nothing was done to it."
+          };
+        }
+        if (held.onFrame === void 0 && held.watchGen === watchGen) {
+          temporaryCapture = { held, cdp, watchGen };
+        }
+      }
+      if (held.screencast && (held.capturing === false || held.visibilityUnconfirmed === true)) {
+        const cdp = held.screencast;
+        if (held.capturing === true) {
+          await cdp.send("Page.stopScreencast").catch(() => {
+          });
+          held.capturing = false;
+          this.announceControl(runId);
+        }
+        const drawn = this.nextFrame(held);
+        if (!await this.applyCapture(runId, held, cdp, true, true)) {
+          return {
+            ok: false,
+            detail: "The page could not be shown again, so nothing was done to it."
+          };
+        }
+        if (!await drawn) {
+          held.visibilityUnconfirmed = true;
+          held.capturing = false;
+          await cdp.send("Page.stopScreencast").catch(() => {
+          });
+          this.announceControl(runId);
+          return {
+            ok: false,
+            detail: "The page did not come back on screen, so nothing was done to it."
+          };
+        }
+        if (this.revoked.has(runId)) {
+          await this.releaseIfIdle(runId, () => lease_.endAction(token));
+          return { ok: false, detail: "The user stopped browser control for this run." };
+        }
+        if (context.signal?.aborted || held.abort.signal.aborted) {
+          await this.releaseIfIdle(runId, () => lease_.endAction(token));
+          return { ok: false, detail: "The run was cancelled." };
+        }
+      }
+      return await this.perform(runId, held, action, recoveringClosedPage ? held.generation : planned);
+    } catch (err) {
+      return { ok: false, detail: err instanceof Error ? err.message : String(err) };
+    } finally {
+      if (temporaryCapture) {
+        const { held, cdp, watchGen } = temporaryCapture;
+        if (held.screencast === cdp && held.onFrame === void 0 && held.watchGen === watchGen && held.hiddenByHolder === false && held.visibilityUnconfirmed === false && held.capturing === true) {
+          held.onFrame = void 0;
+          held.screencast = void 0;
+          held.screencastPage = void 0;
+          held.capturing = true;
+          this.announceControl(runId);
+          await cdp.send("Page.stopScreencast").catch(() => {
+          });
+          await cdp.detach().catch(() => {
+          });
+        }
+      }
+      lease_.endAction(token);
+      if (context.signal?.aborted || this.revoked.has(runId)) lease_.releaseIfHeldBy(actor);
+    }
+  }
+  /**
+   * The run's browser, opened on first use.
+   *
+   * The ONE place the session cap is enforced. An earlier version also checked
+   * it before taking the lease, on the reasoning that a run which cannot get a
+   * session would otherwise queue forever — true when every run shared one
+   * lease, and false once each run got its own, because a second run no longer
+   * queues behind the first at all. Its own revert-check proved it dead: taking
+   * it out changed no test. Two copies of a cap invite them to disagree.
+   */
+  async open(runId, signal) {
+    if (this.ready) {
+      const settling = this.ready;
+      try {
+        await settling;
+      } catch {
+      }
+      if (this.ready === settling) this.ready = void 0;
+    }
+    const existing = this.runs.get(runId);
+    if (existing && !existing.page.isClosed()) return existing;
+    if (existing && existing.page.isClosed()) {
+      const fallback = existing.page.context().pages().filter((p) => !p.isClosed()).at(-1);
+      if (fallback) {
+        await this.adoptPage(runId, existing, fallback);
+        return existing;
+      }
+    }
+    if (existing) {
+      this.runs.delete(runId);
+      await this.teardown(runId, existing);
+    }
+    if (this.retired) {
+      throw new Error("The browser settings changed while this action was waiting. Try again.");
+    }
+    if (this.runs.size + this.opening.size + this.closing.size >= this.maxSessions) {
+      throw new Error(
+        `All ${this.maxSessions} browser session${this.maxSessions === 1 ? "" : "s"} are in use by other runs. Try again when one finishes, or raise the session limit in settings.`
+      );
+    }
+    if (!this.aborts.has(runId)) this.aborts.set(runId, new AbortController());
+    const opening = this.openReserved(runId, signal);
+    this.opening.set(runId, opening);
+    try {
+      return await opening;
+    } finally {
+      this.opening.delete(runId);
+    }
+  }
+  /** The part that may fail, with the pool slot already reserved. */
+  async openReserved(runId, signal) {
+    const playwright = await loadPlaywright();
+    const abort = this.aborts.get(runId)?.signal;
+    const creationSignal = signal && abort ? AbortSignal.any([signal, abort]) : signal ?? abort;
+    const session = await this.provider.createSession(creationSignal);
+    let browser;
+    let owned;
+    let held;
+    try {
+      browser = await playwright.chromium.connectOverCDP(session.cdpUrl);
+      owned = this.provider.isolatesSessions ? void 0 : await browser.newContext();
+      const context = owned ?? browser.contexts()[0] ?? await browser.newContext();
+      const page2 = owned ? await owned.newPage() : context.pages()[0] ?? await context.newPage();
+      const abort2 = this.aborts.get(runId);
+      if (!abort2) throw new Error("The run ended while its browser was still opening.");
+      held = { session, browser, page: page2, generation: 0, abort: abort2, ...owned ? { ownedContext: owned } : {} };
+      this.trackPageNavigation(runId, held, page2);
+      this.runs.set(runId, held);
+    } catch (err) {
+      await owned?.close().catch(() => {
+      });
+      await browser?.close().catch(() => {
+      });
+      await this.provider.endSession(session.id).catch(() => {
+      });
+      throw err;
+    }
+    this.announceLiveView(runId, session.liveViewUrl, true);
+    return held;
+  }
+  /** Count main-frame navigation only while this page is the run's active page. */
+  trackPageNavigation(runId, held, page2) {
+    page2.on("framenavigated", ((frame) => {
+      if (held.page !== page2 || frame !== page2.mainFrame()) return;
+      held.generation += 1;
+      if (held.onFrame && held.watchGen !== void 0) {
+        held.watchGen += 1;
+        this.announceControl(runId);
+      }
+    }));
+  }
+  /**
+   * Follow a page opened by the action that just finished.
+   *
+   * A popup/new tab is part of the same user gesture (OAuth is the common
+   * example). Keeping `held.page` and the screencast on its opener makes the
+   * new page both invisible and impossible to drive. This runs while the SAME
+   * action slot is still held, after the opening click/key has fully landed, so
+   * no later human/agent event can slip between detecting the popup and moving
+   * the view to it.
+   */
+  async followOpenedPage(runId, held, before) {
+    if (this.runs.get(runId) !== held || held.abort.signal.aborted) return;
+    const candidates = held.page.context().pages().filter((p) => !p.isClosed() && !before.has(p));
+    const next = candidates.at(-1);
+    if (!next || next === held.page) return;
+    await this.adoptPage(runId, held, next);
+  }
+  /**
+   * Make one live page the run's controlled/viewed page. Used in both
+   * directions: into a popup opened by an action, and back to another surviving
+   * page when that popup closes itself after OAuth/login completion.
+   */
+  async adoptPage(runId, held, next) {
+    if (next === held.page || next.isClosed()) return;
+    held.page = next;
+    held.generation += 1;
+    held.viewport = void 0;
+    held.metricsStale = true;
+    this.trackPageNavigation(runId, held, next);
+    const deliver = held.onFrame;
+    if (deliver) {
+      held.watchGen = (held.watchGen ?? 0) + 1;
+      held.visibilityUnconfirmed = true;
+      held.capturing = false;
+      this.announceControl(runId);
+      await this.attachScreencast(runId, held, deliver, held.watchDetachGen ?? 0);
+      return;
+    }
+    const pending = held.attaching;
+    if (pending) await pending.catch(() => null);
+    if (held.screencast && held.screencastPage !== next) {
+      const stale = held.screencast;
+      held.screencast = void 0;
+      held.screencastPage = void 0;
+      await stale.send("Page.stopScreencast").catch(() => {
+      });
+      await stale.detach().catch(() => {
+      });
+    }
+    held.visibilityUnconfirmed = false;
+    held.capturing = held.hiddenByHolder !== true;
+    this.announceControl(runId);
+  }
+  async perform(runId, held, action, planned) {
+    const { page: page2 } = held;
+    const stoppable = async (work) => {
+      if (held.abort.signal.aborted) throw new Error("The user stopped browser control for this run.");
+      let onAbort;
+      try {
+        return await Promise.race([
+          work,
+          new Promise((_, reject) => {
+            onAbort = () => {
+              void page2.close().catch(() => {
+              });
+              reject(new Error("The user stopped browser control for this run."));
+            };
+            held.abort.signal.addEventListener("abort", onAbort, { once: true });
+          })
+        ]);
+      } finally {
+        held.abort.signal.removeEventListener("abort", onAbort);
+      }
+    };
+    const timeout = Math.min(action.timeoutMs ?? 1e4, ACTION_TIMEOUT_MS);
+    const where = async () => {
+      const current = held.page;
+      return { url: current.url(), title: await current.title().catch(() => "") };
+    };
+    if (action.kind !== "navigate" && held.generation !== planned) {
+      return {
+        ok: false,
+        detail: "The page changed while this action was waiting for the browser, so it was not run. Look at the page again before retrying.",
+        ...await where()
+      };
+    }
+    switch (action.kind) {
+      case "navigate": {
+        const target = action.url ?? "";
+        if (!/^https?:\/\//i.test(target)) {
+          return { ok: false, detail: "Only http and https addresses can be opened." };
+        }
+        await stoppable(page2.goto(target, { timeout: ACTION_TIMEOUT_MS, waitUntil: "domcontentloaded" }));
+        return { ok: true, detail: `Opened ${target}`, ...await where() };
+      }
+      case "click": {
+        const pagesBefore = new Set(page2.context().pages());
+        await stoppable(page2.click(action.selector, { timeout }));
+        await this.followOpenedPage(runId, held, pagesBefore);
+        return { ok: true, detail: `Clicked ${action.selector}`, ...await where() };
+      }
+      case "fill":
+        await stoppable(page2.fill(action.selector, action.value ?? "", { timeout }));
+        return { ok: true, detail: `Filled ${action.selector}`, ...await where() };
+      case "press": {
+        const pagesBefore = new Set(page2.context().pages());
+        if (action.selector) await stoppable(page2.press(action.selector, action.key, { timeout }));
+        else await stoppable(page2.keyboard.press(action.key));
+        await this.followOpenedPage(runId, held, pagesBefore);
+        return { ok: true, detail: `Pressed ${action.key}`, ...await where() };
+      }
+      case "wait_for":
+        await stoppable(page2.waitForSelector(action.selector, { timeout }));
+        return { ok: true, detail: `${action.selector} appeared`, ...await where() };
+      case "extract_text": {
+        const text = await stoppable(page2.innerText(action.selector ?? "body", { timeout }));
+        return { ok: true, detail: text.slice(0, 2e5), ...await where() };
+      }
+      default:
+        return { ok: false, detail: `Unsupported action: ${String(action.kind)}` };
+    }
+  }
+};
+function refusal(result) {
+  if (result === "human") {
+    return "The user has taken control of this browser. Stop using it and tell them what you were about to do.";
+  }
+  if (result === "off") return "Browser control was turned off while this action waited for the browser.";
+  if (result === "cancelled") return "The run was cancelled while waiting for the browser.";
+  return "The browser is in use by another part of this run and did not come free in time. Try again, or do something else first.";
+}
+function coordinate(n, what) {
+  if (typeof n !== "number" || !Number.isFinite(n)) {
+    throw new Error(`That ${what} is not a position on the page.`);
+  }
+  return Math.min(Math.max(n, 0), 1);
+}
+function scrollDelta(n) {
+  if (typeof n !== "number" || !Number.isFinite(n)) {
+    throw new Error("That scroll has no distance to travel.");
+  }
+  return Math.min(Math.max(n, -2e3), 2e3);
+}
+async function loadPlaywright() {
+  try {
+    return await import('playwright');
+  } catch {
+    throw new Error("Playwright is not installed. Run: npm install playwright (no browser download is needed \u2014 this connects to a remote browser).");
+  }
+}
+
+// src/browser/remote/generic-cdp.ts
+var GenericCdpProvider = class {
+  name = "CDP endpoint";
+  // The endpoint is a single browser. There is no session to allocate, so two
+  // runs against it share a page — see the seam.
+  isolatesSessions = false;
+  endpoint;
+  constructor(endpoint) {
+    this.endpoint = endpoint;
+  }
+  /**
+   * There is no session to create — the endpoint is the session.
+   *
+   * `id` is a constant rather than a generated one because there is nothing to
+   * look up later: `endSession` has nothing to call. Inventing a unique id
+   * would imply a lifecycle this provider does not have.
+   */
+  async createSession() {
+    return { id: "cdp", cdpUrl: this.endpoint };
+  }
+  /**
+   * Deliberately nothing.
+   *
+   * The endpoint belongs to whoever runs it and outlives any single run, so
+   * "ending" it is not ours to do — closing it would take the browser away from
+   * every other user of a shared endpoint. The driver still closes its own
+   * connection and its pages; this is only about the browser's lifetime.
+   */
+  async endSession() {
+  }
+};
+function isCdpEndpoint(url) {
+  try {
+    const u = new URL(url);
+    return u.protocol === "ws:" || u.protocol === "wss:";
+  } catch {
+    return false;
+  }
+}
+
+// src/browser/remote/steel.ts
+var DEFAULT_BASE = "https://api.steel.dev";
+var CREATE_TIMEOUT_MS = 6e4;
+var SteelProvider = class {
+  name = "Steel";
+  // POST /v1/sessions allocates a browser per call, so concurrent runs are
+  // genuinely separate.
+  isolatesSessions = true;
+  base;
+  apiKey;
+  constructor(opts = {}) {
+    let base = opts.url || DEFAULT_BASE;
+    while (base.endsWith("/")) base = base.slice(0, -1);
+    this.base = base;
+    this.apiKey = opts.apiKey;
+  }
+  async createSession(signal) {
+    const details = await this.call("POST", "/v1/sessions", signal, {});
+    if (!details.id || !details.websocketUrl) {
+      throw new Error("Steel returned a session with no id or websocket URL.");
+    }
+    return {
+      id: details.id,
+      cdpUrl: details.websocketUrl,
+      ...details.debugUrl ? { liveViewUrl: details.debugUrl } : {}
+    };
+  }
+  async endSession(id) {
+    try {
+      await this.call("POST", `/v1/sessions/${encodeURIComponent(id)}/release`, void 0, {});
+    } catch {
+    }
+  }
+  async call(method, path30, signal, body) {
+    const timeout = AbortSignal.timeout(CREATE_TIMEOUT_MS);
+    const composed = signal ? AbortSignal.any([signal, timeout]) : timeout;
+    const res = await fetch(`${this.base}${path30}`, {
+      method,
+      headers: {
+        "content-type": "application/json",
+        // Sent only when configured — the self-hosted API takes no key, and an
+        // empty header is worse than none.
+        ...this.apiKey ? { "steel-api-key": this.apiKey } : {}
+      },
+      body: JSON.stringify(body),
+      signal: composed
+    });
+    if (!res.ok) {
+      const detail = await res.text().then((t) => t.slice(0, 300)).catch(() => "");
+      throw new Error(`Steel ${method} ${path30} failed: ${res.status}${detail ? ` \u2014 ${detail}` : ""}`);
+    }
+    return await res.json();
+  }
+};
+
 // src/retrieval/chunk.ts
 var DEFAULTS2 = { targetChars: 2e3, overlapChars: 200, minChars: 80 };
 function splitLongBlock(block, max) {
@@ -35598,6 +37543,7 @@ exports.AZURE_BASE_MODELS = AZURE_BASE_MODELS;
 exports.AZURE_BASE_URL_TEMPLATE = AZURE_BASE_URL_TEMPLATE;
 exports.AuditLogger = AuditLogger;
 exports.BrowserControlTool = BrowserControlTool;
+exports.BrowserLease = BrowserLease;
 exports.CASCADE_AUDIT_FILE = CASCADE_AUDIT_FILE;
 exports.CASCADE_CONFIG_DIR = CASCADE_CONFIG_DIR;
 exports.CASCADE_CONFIG_FILE = CASCADE_CONFIG_FILE;
@@ -35638,6 +37584,7 @@ exports.GLOBAL_DB_FILE = GLOBAL_DB_FILE;
 exports.GLOBAL_KEYSTORE_FILE = GLOBAL_KEYSTORE_FILE;
 exports.GLOBAL_RUNTIME_DB_FILE = GLOBAL_RUNTIME_DB_FILE;
 exports.GenerateDocumentTool = GenerateDocumentTool;
+exports.GenericCdpProvider = GenericCdpProvider;
 exports.GraphRetriever = GraphRetriever;
 exports.GraphSearchTool = GraphSearchTool;
 exports.HooksRunner = HooksRunner;
@@ -35654,9 +37601,11 @@ exports.OLLAMA_BASE_URL = OLLAMA_BASE_URL;
 exports.OpenAICompatibleEmbedder = OpenAICompatibleEmbedder;
 exports.PROVIDER_DISPLAY_NAMES = PROVIDER_DISPLAY_NAMES;
 exports.RESUME_SCHEMA_VERSION = RESUME_SCHEMA_VERSION;
+exports.RemoteBrowserController = RemoteBrowserController;
 exports.ResumeStore = ResumeStore;
 exports.Retriever = Retriever;
 exports.SqliteVectorStore = SqliteVectorStore;
+exports.SteelProvider = SteelProvider;
 exports.T1Administrator = T1Administrator;
 exports.T1_MODEL_PRIORITY = T1_MODEL_PRIORITY;
 exports.T2Manager = T2Manager;
@@ -35721,6 +37670,7 @@ exports.hashContent = hashContent;
 exports.heuristicCodeChunker = heuristicCodeChunker;
 exports.inferAzureBaseModel = inferAzureBaseModel;
 exports.inlineRuns = inlineRuns;
+exports.isCdpEndpoint = isCdpEndpoint;
 exports.isDocumentFormat = isDocumentFormat;
 exports.isMcpToolName = isMcpToolName;
 exports.matchImageLine = matchImageLine;